@c15t/react 3.0.0-alpha.1 → 3.0.0-alpha.11

package/docs/customization/dark-mode.md

@@ -0,0 +1,157 @@
+---
+title: Dark mode
+description: Switch c15t's banner and dialog to dark colors with colorScheme,
+  set your own dark tokens, follow your site's theme switch, and paint dark on
+  the first frame in every framework.
+group: customization
+---
+
+## How c15t turns dark
+
+c15t's stylesheet switches every `--c15t-*` color token to its dark value when
+`<html>` has a `dark` or a `c15t-dark` class. The `colorScheme` option decides
+whether c15t sets `c15t-dark` itself:
+
+| `colorScheme` | What c15t does with `c15t-dark`                                          |
+| ------------- | ------------------------------------------------------------------------ |
+| `'light'`     | Removes it once                                                          |
+| `'dark'`      | Adds it once                                                             |
+| `'system'`    | Follows `prefers-color-scheme`, including changes while the page is open |
+| Unset         | Copies your `dark` class into `c15t-dark` and follows it as it changes   |
+| `null`        | Leaves it alone. Your site sets it                                       |
+
+Astro also accepts `'none'`, which means the same as `null`.
+
+`'light'` only removes `c15t-dark`. If your site puts `dark` on `<html>`, the
+stylesheet still switches the tokens to dark. Pick one class convention for
+your site and let c15t follow it.
+
+## Defaults in each framework
+
+| Framework               | Where to set it                                                                   | Default              |
+| ----------------------- | --------------------------------------------------------------------------------- | -------------------- |
+| Next.js, TanStack Start | `options.colorScheme` on `ConsentRoot`, and `colorScheme` on `ConsentTheme`       | Unset: copies `dark` |
+| React                   | `colorScheme` in the `ConsentProvider` options, and on `ConsentTheme`             | Unset: copies `dark` |
+| Nuxt                    | `colorScheme` under the `c15t` key in `nuxt.config.ts`, or in `app/app.config.ts` | Unset: copies `dark` |
+| Vue                     | `colorScheme` in the `c15tVue` options                                            | Unset: copies `dark` |
+| Astro                   | `colorScheme` in the `c15t()` integration options                                 | `'system'`           |
+| Svelte, SvelteKit       | `colorScheme` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)          | Unset: copies `dark` |
+| HTML                    | `data-color-scheme` on the script tag: `light`, `dark`, `system` or `none`        | `system`             |
+| JavaScript              | `ui.colorScheme` in `init()`                                                      | `'system'`           |
+
+React, Vue and Svelte apps usually already have a theme switch that toggles a
+`dark` class, such as next-themes. Copying that class keeps c15t in step with
+the site without extra code.
+
+Astro and the script tag default to `'system'` because neither can rely on a
+site convention. Astro paints the banner from server HTML before any site
+script runs, and Astro sites share no `dark` class convention, so following the
+operating system is the one choice its inline script can make correctly. A plain
+HTML page has no convention either. A site that has one opts in with `null`.
+
+### Set colorScheme null in Nuxt
+
+In Nuxt, set `colorScheme: null` under the `c15t` key in `nuxt.config.ts` or
+in `app/app.config.ts`. Nuxt drops a `null` in inline module options, such as
+`modules: [['@c15t/vue', { colorScheme: null }]]`, before the module reads it,
+so c15t would copy your `dark` class as if `colorScheme` were unset.
+
+## Follow your site's theme switch
+
+In React, Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit, leave
+`colorScheme` unset and toggle `dark` on `<html>`. c15t watches the class and switches with
+it. Include the class in the server HTML when your site renders dark, so the
+first paint matches.
+
+In Astro, set `colorScheme: 'none'` and toggle `c15t-dark` together with your
+own class. A `ClientRouter` navigation replaces the attributes of `<html>`, so
+set the class again on `astro:after-swap` if your theme script does not.
+
+With the script tag, add `data-color-scheme="none"`. With `init()`, pass
+`ui: { colorScheme: null }`. The UI is then dark while `<html>` has `dark` or
+`c15t-dark`, and follows the class as it changes. The UI renders in a shadow
+root that the page's class cannot reach, so c15t copies the class onto the
+shadow host.
+
+If your site sets `c15t-dark` itself in React, Next.js, TanStack Start, Vue,
+Nuxt, Svelte or SvelteKit, pass `colorScheme: null` so c15t leaves it alone.
+
+## Set your own dark colors
+
+Theme tokens take a `dark` object with the same color keys as `colors`. Every
+color you set in `colors` also applies in dark mode, unless `dark` sets it too,
+so give a dark value for each brand color:
+
+```ts title="consent-theme.ts"
+export const theme = {
+	colors: { primary: '#2f6f4e', primaryHover: '#24563c', surface: '#fbf8f3' },
+	dark: { primary: '#7fd1a8', primaryHover: '#9fdcbd', surface: '#1b1f1d' },
+};
+```
+
+Where the theme goes depends on the framework:
+
+* **React, Next.js, TanStack Start.** Pass it to `ConsentTheme`. To write the
+  CSS outside a component, call `generateThemeCSS(theme, colorScheme)` from
+  `c15t/react/utils`, or `@c15t/react/utils` if you installed the scoped
+  package. It writes the same CSS as `ConsentTheme`.
+* **Vue, Nuxt.** Pass it as `theme` in the plugin or module options. It goes
+  into the `<style id="c15t-css-vars">` element with `tokens`.
+* **Astro.** Pass it as `theme` in the integration options.
+* **SvelteKit, Svelte.** Pass it to `generateThemeCSS(theme, colorScheme)` from
+  `@c15t/ui/theme` on the server.
+* **HTML, JavaScript.** Pass it as `ui.theme`.
+
+This Nuxt example follows the system setting and uses its own dark primary
+color. Every other dark token keeps c15t's default:
+
+```ts title="nuxt.config.ts (c15t options)"
+// Follow the visitor's system setting, with a dark primary of our own.
+colorScheme: 'system',
+theme: { dark: { primary: '#7fd1a8' } },
+```
+
+To set dark values in plain CSS instead, write them for both classes:
+
+```css
+:root.dark,
+:root.c15t-dark {
+  --c15t-primary: #7fd1a8;
+  --c15t-surface: #1b1f1d;
+}
+```
+
+A generated theme, such as the output of `ConsentTheme` or
+`generateThemeCSS`, writes its dark values on `:root:root.dark` and
+`:root:root.c15t-dark`. Those selectors outrank the rule above. If you use both,
+put dark values in the theme, or repeat `:root` in your own selectors.
+
+## Paint dark on the first frame
+
+A banner that renders light and then turns dark flashes. How to avoid that
+depends on where the banner first renders:
+
+| Framework               | What to do                                                                                                                                                                                                                                                                                                                                      |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start | Render `<ConsentTheme theme={theme} colorScheme="system" />` on the server, with the same value as `options.colorScheme`. `'dark'` writes dark tokens as the default and `'system'` adds a `prefers-color-scheme` media query, so the server HTML is dark before hydration. With `colorScheme` unset, put your `dark` class in the server HTML. |
+| React                   | Render `<ConsentTheme colorScheme="system" />` next to the provider, with the same value as the provider's `colorScheme`. Its CSS makes the tokens dark from the first frame, before the provider sets the class. In a server-rendered React app, render it on the server.                                                                      |
+| Nuxt                    | For `'dark'` and `'system'`, the module adds an inline script to `<head>` that sets `c15t-dark` before the server-rendered banner paints. It carries the module's `nonce`. With `colorScheme` unset, put your `dark` class in the server HTML.                                                                                                  |
+| Vue                     | The plugin applies `colorScheme` and writes the tokens when you install it, before the first render.                                                                                                                                                                                                                                            |
+| Astro                   | `ConsentScript` in `<head>` sets the class from an inline script before the banner paints, and c15t sets it again after each `ClientRouter` navigation. Keep `ConsentScript` in your layout's `<head>`.                                                                                                                                         |
+| Svelte                  | The provider sets the class as it mounts. With `colorScheme` unset, the stylesheet reads your `dark` class directly, so the tokens are dark from the first frame.                                                                                                                                                                               |
+| SvelteKit               | Pass the scheme to `generateThemeCSS(theme, 'system')` in your server load, so the CSS in `<svelte:head>` already has the media query. With `colorScheme` unset, put your `dark` class in the server HTML.                                                                                                                                      |
+| HTML, JavaScript        | c15t applies the scheme when it mounts the UI, before any surface renders.                                                                                                                                                                                                                                                                      |
+
+[Theme tokens](./tokens.md) lists every color token, and your
+framework's customize page shows where its theme goes.
+
+## Check the result
+
+1. Open the page in a private window with your operating system in dark mode,
+   or add your `dark` class to `<html>`.
+2. The banner is dark on its first frame. Reload with the Network panel
+   throttled to see the first paint.
+3. Open the preference dialog. It uses the same dark tokens as the banner.
+4. Switch the scheme while the page is open. With `'system'` or an unset
+   `colorScheme`, the banner and dialog follow without a reload.
+5. Check the contrast of the primary button text in both schemes.

package/docs/customization/motion.md

@@ -0,0 +1,128 @@
+---
+title: Motion and animation
+description: Change how fast c15t's banner and dialog animate with duration and
+  easing tokens, turn animations off per surface with disableAnimation, and
+  check reduced-motion behavior in each framework.
+group: customization
+---
+
+## Change the speed with motion tokens
+
+c15t animates its surfaces with three durations and five easing curves. Set
+them in the theme's `motion` object, or as CSS variables:
+
+| CSS variable             | Theme key                | Default                                  | Used by                                                        |
+| ------------------------ | ------------------------ | ---------------------------------------- | -------------------------------------------------------------- |
+| `--c15t-duration-fast`   | `motion.duration.fast`   | `80ms`                                   | Banner fade out, buttons, tabs                                 |
+| `--c15t-duration-normal` | `motion.duration.normal` | `150ms`                                  | Preference dialog, late banner fade in, switches, accordions   |
+| `--c15t-duration-slow`   | `motion.duration.slow`   | `200ms`                                  | Legal links, floating trigger                                  |
+| `--c15t-easing`          | `motion.easing`          | `cubic-bezier(0.4, 0, 0.2, 1)`           | Switches, accordions                                           |
+| `--c15t-easing-out`      | `motion.easingOut`       | `cubic-bezier(0.215, 0.61, 0.355, 1)`    | Preference dialog, late banner fade in, floating trigger hover |
+| `--c15t-easing-in`       | `motion.easingIn`        | `cubic-bezier(0.55, 0.055, 0.675, 0.19)` | Banner fade out                                                |
+| `--c15t-easing-in-out`   | `motion.easingInOut`     | `cubic-bezier(0.645, 0.045, 0.355, 1)`   | Floating trigger snapping to a corner                          |
+| `--c15t-easing-spring`   | `motion.easingSpring`    | `cubic-bezier(0.34, 1.56, 0.64, 1)`      | The dialog's scale in                                          |
+
+This theme slows the dialog down and removes its overshoot:
+
+```ts title="consent-theme.ts"
+export const theme = {
+	motion: {
+		duration: { fast: '120ms', normal: '220ms' },
+		easingSpring: 'cubic-bezier(0.215, 0.61, 0.355, 1)',
+	},
+};
+```
+
+The banner never slides in. When it shows with the page, it is part of the
+first paint and appears on its first frame. When it arrives more than 100ms
+after the page first painted, such as after a slow script or a client-side
+init, it fades in over `--c15t-duration-normal` instead, and its root and
+backdrop carry `data-entry="late"`. A banner rendered on the server always
+shows at once. When it hides, Vue, Svelte and the script tag fade it out over
+`--c15t-duration-fast`.
+
+The theme goes where your framework's other tokens go. See
+[theme tokens](./tokens.md) and your framework's customize page.
+In Vue and Nuxt, set `tokens` with the variable name without the leading
+`--`, such as `'c15t-duration-normal': '220ms'`.
+
+## Turn animations off
+
+`disableAnimation` removes the banner's fades, the enter and exit
+transitions of the dialogs, and the hover and snap transitions of the floating
+`ConsentDialogTrigger`. Set it once for every surface, then override it for one
+surface where your framework allows:
+
+| Framework               | For every surface                                                                | For one surface                                                                                                                     |
+| ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start | `options.disableAnimation` in Next.js `c15t.config.ts`, or on `ConsentRoot`      | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
+| React                   | `disableAnimation` in the `ConsentProvider` options                              | The same component props                                                                                                            |
+| Nuxt                    | `disableAnimation` in the `c15t` module options                                  | `disableAnimation` prop on `consent-banner.vue`, `consent-manager.vue` and the IAB banner and dialog, when you render them yourself |
+| Vue                     | `disableAnimation` in the `c15tVue` options                                      | The same component props                                                                                                            |
+| Astro                   | `disableAnimation` in the `c15t()` integration options                           | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
+| Svelte, SvelteKit       | `disableAnimation` on `ConsentProvider` (Svelte) or `ConsentRoot` (SvelteKit)    | `disableAnimation` prop on `ConsentBanner`, `ConsentDialog`, `IABConsentBanner`, `IABConsentDialog`                                 |
+| HTML                    | `data-disable-animation` on the script tag, or `ui.disableAnimation` in `config` | `ui.banner.disableAnimation`, `ui.dialog.disableAnimation`                                                                          |
+| JavaScript              | `ui.disableAnimation` in `init()`                                                | `ui.banner.disableAnimation`, `ui.dialog.disableAnimation`                                                                          |
+
+A value on one surface wins over the value for every surface.
+
+Vue's `ConsentRoot` renders the banner and dialog without props, so in Vue and
+Nuxt a per-surface value only applies when you render the surface components
+yourself.
+
+## Follow the visitor's reduced motion setting
+
+c15t's stylesheet stops the banner, dialog, floating trigger, switches, tabs
+and accordions from animating while the visitor asks for reduced motion. The
+rules sit in a `prefers-reduced-motion: reduce` media query, so they apply in
+every framework and follow the setting as it changes, with no option to set.
+
+`disableAnimation: false` does not bring the animations back for these
+visitors, because the stylesheet rule applies whatever the option says.
+
+## Animate your own rules on dialog state
+
+The preference dialog marks its open state with `data-state`, `open` or
+`closed`, so a rule can animate your own additions to it. Which element
+carries the attribute depends on the framework:
+
+| Framework                      | Elements with `data-state`                                                                          |
+| ------------------------------ | --------------------------------------------------------------------------------------------------- |
+| HTML, JavaScript               | Dialog overlay, positioner and content                                                              |
+| Svelte, SvelteKit              | Dialog backdrop, positioner and content                                                             |
+| Vue, Nuxt                      | Dialog content and overlay. The dialog unmounts when it closes, so you only see `open`              |
+| React, Next.js, TanStack Start | Not on `ConsentDialog`. The `Dialog` primitive's trigger, overlay, content and close parts carry it |
+
+Banners do not carry `data-state`. Read `data-prompt`, `data-variant` and the
+other attributes in [component parts](./slots.md) instead.
+
+## Stop transitions while you switch themes
+
+Every c15t stylesheet has a `c15t-no-transitions` class that sets
+`transition` and `animation` to `none` on an element and its children. Add it
+to `<html>` while your app swaps themes, so colors change in one frame. Force
+a style and layout pass before you remove it. Otherwise the browser computes
+the new theme only after the class is gone, and the change animates:
+
+```ts
+const root = document.documentElement;
+root.classList.add('c15t-no-transitions');
+applyYourTheme();
+// Reading layout applies the new theme while transitions are off.
+root.getBoundingClientRect();
+root.classList.remove('c15t-no-transitions');
+```
+
+This assumes `applyYourTheme` changes classes or custom properties
+synchronously. If your framework applies the theme in a later render, run the
+last two lines after that render commits.
+
+## Check the result
+
+1. In DevTools, open the Rendering panel and emulate
+   `prefers-reduced-motion: reduce`. Reload with site data cleared.
+2. The banner appears without sliding in.
+3. Open the preference dialog and toggle a switch. The switch changes without
+   animating.
+4. Turn the emulation off, set a slower `motion.duration.normal`, and open the
+   dialog again. It fades in at the new speed.

package/docs/customization/overview.md

@@ -1,45 +1,80 @@
 ---
-title: Customize your consent interface
-description: Choose presentation, theme tokens, slots or custom markup for the
-  change you need.
+title: Customize the interface
+description: Change c15t's consent banner and dialog one step at a time, from a
+  prop to your own markup, and find where each step lives in your framework.
 group: customization
 ---
 
-## Start with the change you want
+## Climb the ladder one step at a time
 
-| Change                                    | Use                                 | Why                                                          |
-| ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------ |
-| Banner shape or location                  | Presentation or banner props        | Keeps policy actions and built-in layout behavior            |
-| Brand colors, radius, typography, spacing | Theme tokens                        | Changes related component parts together                     |
-| One card, footer, title or button group   | Component slots                     | Targets existing markup                                      |
-| Labels, descriptions or language          | i18n configuration                  | Keeps banner and preferences copy consistent                 |
-| A different component structure           | Compound components where available | Retains the component behavior while changing markup         |
-| Your own interaction and markup           | Headless APIs                       | You own rendering, focus behavior and policy action coverage |
+Each step keeps everything the step below it gives you. Stop at the first one
+that makes the change you need:
 
-Most brand changes need tokens and a few slots. Start there before opting out
-of the stock styles. The [recipes](./recipes.md) show how each
-choice affects a real banner.
+1. **Props and presentation.** Pick a shape, a position, button order or
+   blocking. c15t keeps its markup, styles and behavior.
+2. **Theme tokens.** Change colors, type, radius, spacing, shadows and motion
+   everywhere at once. Dark mode is a second set of tokens.
+3. **Parts and classes.** Add a class or inline style to one part of one
+   component, such as the banner card. Tailwind, CSS Modules and CSS-in-JS
+   classes go here.
+4. **Compose.** Rebuild a component from c15t's parts, in your own layout, while
+   c15t still renders the actions the policy requires.
+5. **Headless.** Render your own markup from c15t's state and actions. You own
+   the layout, focus handling and labels.
 
-## Keep behavior and appearance separate
+Most brand work needs tokens and a few part classes. See
+[banner designs](./recipes.md) for five banners built at
+different steps, with screenshots and tested code.
+
+## Where each step lives in your framework
+
+| Framework      | Props and presentation                        | Tokens                                    | Parts and classes                         | Compose                                                                           | Headless                                                                |
+| -------------- | --------------------------------------------- | ----------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| Next.js        | `ConsentBanner` props, `options.presentation` | `ConsentTheme` in a Server Component      | `options.components`, `className`         | [Compose](https://v3.c15t.com/docs/frameworks/next/compose)                       | [Headless](https://v3.c15t.com/docs/frameworks/next/headless)           |
+| TanStack Start | `ConsentBanner` props, `options.presentation` | `ConsentTheme` in the root route          | `options.components`, `className`         | [Compose](https://v3.c15t.com/docs/frameworks/tanstack-start/compose)             | [Headless](https://v3.c15t.com/docs/frameworks/tanstack-start/headless) |
+| React          | `ConsentBanner` props, `presentation`         | `ConsentTheme`, or CSS variables          | `components`, `className`                 | [Compose](../frameworks/react/compose.md)                                         | [Headless](../frameworks/react/headless.md)                             |
+| Nuxt           | `presentation` in `nuxt.config.ts`            | `tokens` or `theme` in the module options | `components`, `class`                     | None                                                                              | [Headless](https://v3.c15t.com/docs/frameworks/nuxt/headless)           |
+| Vue            | `presentation` in the `c15tVue` options       | `tokens` or `theme` in the plugin options | `components`, `class`                     | None                                                                              | [Headless](https://v3.c15t.com/docs/frameworks/vue/headless)            |
+| Astro          | `presentation` in the integration options     | `theme` in the integration options        | `theme.slots`, `class` on `ConsentBanner` | None                                                                              | None                                                                    |
+| Svelte         | `ConsentBanner` props, `presentation`         | CSS variables, or `generateThemeCSS()`    | `theme.slots`, `class` on `ConsentBanner` | [Primitives](https://v3.c15t.com/docs/frameworks/svelte/components/primitives)    | [Headless](https://v3.c15t.com/docs/frameworks/svelte/headless)         |
+| SvelteKit      | `ConsentBanner` props, `presentation`         | `generateThemeCSS()` in a server load     | `theme.slots`, `class` on `ConsentBanner` | [Primitives](https://v3.c15t.com/docs/frameworks/sveltekit/components/primitives) | [Headless](https://v3.c15t.com/docs/frameworks/sveltekit/headless)      |
+| HTML           | `presentation.prompt` in `config`             | `ui.theme`                                | `ui.theme.slots`, `::part()`, `ui.css`    | None                                                                              | [Headless](https://v3.c15t.com/docs/frameworks/html/headless)           |
+| JavaScript     | `presentation.prompt` in `init()`             | `ui.theme`                                | `ui.theme.slots`, `::part()`, `ui.css`    | None                                                                              | [Headless](https://v3.c15t.com/docs/frameworks/javascript/headless)     |
 
-Presentation controls the prompt's shape, position and blocking behavior.
-Policy controls which actions and rights are required. Changing colors or button
-order does not change a saved choice or policy scope.
+Configuration shapes differ between frameworks. React's
+`components.banner.card`, Vue's `components.banner.card` with `class`, and the
+`consentBannerCard` key in `theme.slots` target the same part through
+different APIs. Check your framework's customize page before you move a
+configuration from one framework to another.
+
+## Keep behavior and appearance separate
 
-A choice wall always blocks. Notices never block and cannot become a wall merely
-because `variant: 'wall'` was requested. Preference dialogs remain centered;
-prompt positioning does not move them. Required actions omitted from a custom
-layout can be restored by the policy renderer.
+Presentation controls the prompt's shape, position and blocking. The policy
+controls which actions and rights the visitor gets. Changing colors or button
+order does not change a saved choice or the policy's scope.
 
-## Use the adapter's configuration shape
+A choice wall always blocks. A notice never blocks and does not become a wall
+because you asked for `variant: 'wall'`. The preference dialog stays centered,
+whatever position the banner has. If a custom layout leaves out an action the
+policy requires, c15t puts it back.
 
-React and Next.js accept provider `theme`, `presentation` and `components`
-options. Vue and Nuxt expose their own shared configuration, including CSS
-`tokens` and component slots. Svelte accepts its provider options and theme
-contract. Astro serializes integration options and uses the selected adapter for
-dialogs. Do not move a configuration object between frameworks without checking
-the target types.
+## Read the rest of this section
 
-Read [tokens and CSS](./tokens.md),
-[slots](./slots.md) or
-[copy and translations](./translations.md) for the next step.
+* [Banner designs](./recipes.md): five designs with tested code.
+* [Theme tokens](./tokens.md): every `--c15t-*` variable and
+  its theme key.
+* [Dark mode](./dark-mode.md): `colorScheme`, dark tokens and a
+  dark first paint.
+* [Motion and animation](./motion.md): duration and easing
+  tokens, `disableAnimation` and reduced motion.
+* [Stylesheets and CSS layers](./stylesheets.md): how c15t
+  loads its rules, when to import `styles.css` yourself, when the dialog's CSS
+  loads, and how to run without c15t's styles.
+* [Component parts](./slots.md): every part, its keys in each
+  framework, and the `data-*` attributes to select on.
+* [Class names and CSS-in-JS](./class-names.md): CSS Modules,
+  vanilla-extract, StyleX and Emotion on c15t's parts.
+* [Tailwind CSS](./tailwind.md): Tailwind 4 and 3 in every
+  framework.
+* [Copy and translations](./translations.md): labels,
+  languages and right-to-left text.