chore: add in code doc

lsagetlethias · lsagetlethias · commit 58fed4c33bdb · 2023-09-20T18:25:03.000+02:00
diff --git a/src/next-appdir/DsfrHead.tsx b/src/next-appdir/DsfrHead.tsx
@@ -12,6 +12,8 @@ import { setLink, type RegisteredLinkProps } from "../link";
 //See: https://github.com/vercel/next.js/issues/16630
 // @import url(...) doesn't work. Using Sass and @use is our last resort.
 import "../assets/dsfr_plus_icons.scss";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- used in doc
+import { type startReactDsfr } from "./zz_internal/start";
 
 export type DsfrHeadProps = {
     /** If not provided no fonts are preloaded.
@@ -20,7 +22,22 @@ export type DsfrHeadProps = {
     preloadFonts?: (keyof typeof fontUrlByFileBasename)[];
     /** Default: <a /> */
     Link?: (props: RegisteredLinkProps & { children: ReactNode }) => ReturnType<React.FC>;
+    /**
+     * When set, the value will be used as the nonce attribute of subsequent script tags.
+     *
+     * Don't forget to add `checkNonce: true` in {@link startReactDsfr} options.
+     *
+     * @see https://developer.mozilla.org/fr/docs/Web/HTML/Global_attributes/nonce
+     */
     nonce?: string;
+    /**
+     * Enable Trusted Types with a custom policy name.
+     *
+     * Don't forget to add `trustedTypesPolicyName` in {@link startReactDsfr} options.
+     *
+     * @see https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types
+     * @default "react-dsfr"
+     */
     trustedTypesPolicyName?: string;
 };
 
diff --git a/src/next-appdir/zz_internal/start.ts b/src/next-appdir/zz_internal/start.ts
@@ -4,17 +4,42 @@ import type { RegisteredLinkProps } from "../../link";
 import { setLink } from "../../link";
 import { type DefaultColorScheme, setDefaultColorSchemeClientSide } from "./defaultColorScheme";
 import { isBrowser } from "../../tools/isBrowser";
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- used in doc
+import { type DsfrHead } from "../DsfrHead";
 
 let isAfterFirstEffect = false;
 const actions: (() => void)[] = [];
 
-export async function startReactDsfr(params: {
+export function startReactDsfr(params: {
     defaultColorScheme: DefaultColorScheme;
     /** Default: false */
     verbose?: boolean;
     /** Default: <a /> */
     Link?: (props: RegisteredLinkProps & { children: ReactNode }) => ReturnType<React.FC>;
+    /**
+     * When true, the nonce of the script tag will be checked, fetched from {@link DsfrHead} component and injected in react-dsfr scripts.
+     *
+     * @see https://developer.mozilla.org/fr/docs/Web/HTML/Global_attributes/nonce
+     */
     checkNonce?: boolean;
+    /**
+     * Enable Trusted Types with a custom policy name.
+     *
+     * Don't forget to also add the policy name in {@link DsfrHead} component.
+     *
+     * `<trustedTypesPolicyName>` and `<trustedTypesPolicyName>-asap` should be set in your Content-Security-Policy header.
+     *
+     * For example:
+     * ```txt
+     * With a policy name of "react-dsfr":
+     * Content-Security-Policy:
+     *  require-trusted-types-for 'script';
+     *  trusted-types react-dsfr react-dsfr-asap nextjs nextjs#bundler;
+     * ```
+     *
+     * @see https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types
+     * @default "react-dsfr"
+     */
     trustedTypesPolicyName?: string;
 }) {
     const {
diff --git a/src/next-pagesdir.tsx b/src/next-pagesdir.tsx
@@ -41,7 +41,22 @@ export type CreateNextDsfrIntegrationApiParams = {
     doPersistDarkModePreferenceWithCookie?: boolean;
     /** Default: ()=> "fr" */
     useLang?: () => string;
-    nonce?: string;
+    /**
+     * Enable Trusted Types with a custom policy name.
+     *
+     * `<trustedTypesPolicyName>` and `<trustedTypesPolicyName>-asap` should be set in your Content-Security-Policy header.
+     *
+     * For example:
+     * ```txt
+     * With a policy name of "react-dsfr":
+     * Content-Security-Policy:
+     *  require-trusted-types-for 'script';
+     *  trusted-types react-dsfr react-dsfr-asap nextjs nextjs#bundler;
+     * ```
+     *
+     * @see https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types
+     * @default "react-dsfr"
+     */
     trustedTypesPolicyName?: string;
 };
 
@@ -91,7 +106,6 @@ export function createNextDsfrIntegrationApi(
         preloadFonts = [],
         doPersistDarkModePreferenceWithCookie = false,
         useLang,
-        nonce,
         trustedTypesPolicyName
     } = params;
 
@@ -169,10 +183,9 @@ export function createNextDsfrIntegrationApi(
                         />
                         {!isBrowser && ( //NOTE: On browser we handle this manually
                             <>
-                                <style
-                                    nonce={nonce}
-                                    id={rootColorSchemeStyleTagId}
-                                >{`:root { color-scheme: ${isDark ? "dark" : "light"}; }`}</style>
+                                <style id={rootColorSchemeStyleTagId}>{`:root { color-scheme: ${
+                                    isDark ? "dark" : "light"
+                                }; }`}</style>
                                 <meta
                                     name="theme-color"
                                     content={
@@ -184,11 +197,9 @@ export function createNextDsfrIntegrationApi(
                         )}
                         {isProduction && !isBrowser && (
                             <script
-                                nonce={nonce}
                                 dangerouslySetInnerHTML={{
                                     "__html": getScriptToRunAsap({
                                         defaultColorScheme,
-                                        nonce,
                                         trustedTypesPolicyName
                                     })
                                 }}
diff --git a/src/spa.ts b/src/spa.ts
@@ -15,15 +15,36 @@ export function startReactDsfr(params: {
     Link?: (props: RegisteredLinkProps & { children: ReactNode }) => ReturnType<React.FC>;
     /** Default: ()=> "fr" */
     useLang?: () => string;
-    checkNonce?: boolean;
+    /**
+     * When set, the value will be used as the nonce attribute of subsequent script tags.
+     *
+     * @see https://developer.mozilla.org/fr/docs/Web/HTML/Global_attributes/nonce
+     */
+    nonce?: string;
+    /**
+     * Enable Trusted Types with a custom policy name.
+     *
+     * `<trustedTypesPolicyName>` and `<trustedTypesPolicyName>-asap` should be set in your Content-Security-Policy header.
+     *
+     * For example:
+     * ```txt
+     * With a policy name of "react-dsfr":
+     * Content-Security-Policy:
+     *  require-trusted-types-for 'script';
+     *  trusted-types react-dsfr react-dsfr-asap nextjs nextjs#bundler;
+     * ```
+     *
+     * @see https://developer.mozilla.org/fr/docs/Web/HTTP/Headers/Content-Security-Policy/trusted-types
+     * @default "react-dsfr"
+     */
     trustedTypesPolicyName?: string;
 }) {
     const {
         defaultColorScheme,
         verbose = false,
         Link,
         useLang,
-        checkNonce,
+        nonce,
         trustedTypesPolicyName
     } = params;
 
@@ -35,6 +56,11 @@ export function startReactDsfr(params: {
         setUseLang({ useLang });
     }
 
+    const checkNonce = !!nonce;
+    if (checkNonce) {
+        window.ssrNonce = nonce;
+    }
+
     start({
         defaultColorScheme,
         verbose,
diff --git a/test/integration/cra/public/index.html b/test/integration/cra/public/index.html
@@ -5,6 +5,8 @@
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <meta name="description" content="Web site created using create-react-app" />
+  <meta http-equiv="Content-Security-Policy"
+    content="require-trusted-types-for 'script'; trusted-types react-dsfr react-dsfr-asap" />
 
   <link rel="apple-touch-icon" href="%PUBLIC_URL%/dsfr/favicon/apple-touch-icon.png" />
   <link rel="icon" href="%PUBLIC_URL%/dsfr/favicon/favicon.svg" type="image/svg+xml" />
diff --git a/test/integration/vite/index.html b/test/integration/vite/index.html
@@ -3,6 +3,8 @@
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta http-equiv="Content-Security-Policy"
+      content="require-trusted-types-for 'script'; trusted-types react-dsfr react-dsfr-asap" />
 
     <link rel="apple-touch-icon" href="/dsfr/favicon/apple-touch-icon.png" />
     <link rel="icon" href="/dsfr/favicon/favicon.svg" type="image/svg+xml" />
