@c15t/scripts 3.0.0-alpha.2 → 3.0.0-alpha.4

package/docs/customization/slots.md

@@ -1,55 +1,236 @@
 ---
-title: Style component slots
-description: Target a specific c15t component part without replacing its markup or behavior.
+title: Component parts
+description: Find every part of c15t's banner, dialog, widget, trigger and
+  ConsentGate placeholder, its key in your framework's part API, and the data
+  attributes to select on.
 group: customization
 ---
 
-## Use slots for local changes
+## Which part API your framework uses
 
-In React and Next.js, put per-part attributes in `options.components`. This
-fragment belongs in an existing provider's options:
+Each framework has one way to add classes, inline styles or attributes to a
+single part of a stock component. The keys differ between the two
+vocabularies, so a configuration from one does not work in the other.
+
+| Framework               | Part API                                                      | Keys look like            | Class key                |
+| ----------------------- | ------------------------------------------------------------- | ------------------------- | ------------------------ |
+| Next.js, TanStack Start | `options.components` on `ConsentRoot`                         | `components.banner.card`  | `className`              |
+| React                   | `components` in the `ConsentProvider` options                 | `components.banner.card`  | `className`              |
+| Nuxt                    | `components` in the `c15t` options, or in `app/app.config.ts` | `components.banner.card`  | `class`                  |
+| Vue                     | `components` in the `c15tVue` options                         | `components.banner.card`  | `class`                  |
+| Astro                   | `theme.slots` in the `c15t()` integration options             | `slots.consentBannerCard` | A string, or `className` |
+| Svelte, SvelteKit       | `theme.slots` on `ConsentManagerProvider`                     | `slots.consentBannerCard` | A string, or `className` |
+| HTML, JavaScript        | `ui.theme.slots`                                              | `slots.consentBannerCard` | A string, or `className` |
+
+React and Vue also read `theme.slots` from the theme in their options, and
+apply each slot to the matching `components` part, such as
+`consentDialogCard` to `dialog.card` and `toggle` to `switch.root`. Where both
+set the same part, classes from both apply, inline styles merge with
+`components` winning per property, and any other attribute in `components`
+replaces the theme's. In Vue and Nuxt, each part object is bound with
+`v-bind`, so write `class` and `style` rather than React's `className`.
+
+Svelte's stock components, and Astro's `ConsentBanner`, `IABConsentBanner`
+and `ConsentDialogTrigger`, also take a `class` prop. On `ConsentBanner` it
+goes on the banner root.
+
+This React fragment belongs in the provider options:
 
 ```tsx
 components: {
   banner: {
-    card: { className: 'rounded-none shadow-none' },
-    title: { className: 'font-semibold' },
-    footer: { className: 'border-t' },
+    card: { className: 'brand-card' },
+    title: { style: { fontWeight: 600 } },
   },
+},
+```
+
+The same parts with `theme.slots`, which every framework reads:
+
+```ts
+theme: {
+  slots: {
+    consentBannerCard: 'brand-card',
+    consentBannerTitle: 'brand-title',
+  },
+},
+```
+
+A slot can also be `{ className, style }`. Svelte applies both on every part,
+including the IAB banner and dialog.
+
+[Class names and CSS-in-JS](./class-names.md) covers CSS
+Modules, vanilla-extract, StyleX and Emotion, and
+[Tailwind CSS](./tailwind.md) covers utilities on parts.
+
+## Banner parts
+
+| Part                                        | `components` key                     | `theme.slots` key                  | `data-testid`         |
+| ------------------------------------------- | ------------------------------------ | ---------------------------------- | --------------------- |
+| Positioning root, with the state attributes | `banner.root`                        | `consentBanner`                    | `consent-banner-root` |
+| Card sizing and branding container          | `banner.cardShell`                   | None                               |                       |
+| Visible card                                | `banner.card`                        | `consentBannerCard`                | `consent-banner-card` |
+| Title and description container             | `banner.header`                      | `consentBannerHeader`              |                       |
+| Title                                       | `banner.title`                       | `consentBannerTitle`               |                       |
+| Description                                 | `description.banner`                 | `consentBannerDescription`         |                       |
+| Action area                                 | `banner.footer`                      | `consentBannerFooter`              |                       |
+| Group of action groups                      | `banner.actions`                     | None                               |                       |
+| One group of equally prominent actions      | `banner.actionGroup`                 | `consentBannerFooterSubGroup`      |                       |
+| Group of right links                        | `banner.rights`                      | `consentBannerRights`              |                       |
+| One right link                              | `banner.rightLink`                   | `consentBannerRightLink`           |                       |
+| Backdrop of a blocking banner               | `banner.overlay`                     | `consentBannerOverlay`             |                       |
+| "Secured by" tag                            | `tag.banner`                         | `consentBannerTag`                 |                       |
+| Filled and outlined buttons                 | `button.primary`, `button.secondary` | `buttonPrimary`, `buttonSecondary` |                       |
+
+The button parts apply to every c15t button of that style, in the banner and
+the dialog. The script tag's banner has no rights group, so
+`consentBannerRights` does not apply there.
+
+## Preference dialog parts
+
+| Part             | `components` key     | `theme.slots` key          | `data-testid`         |
+| ---------------- | -------------------- | -------------------------- | --------------------- |
+| Positioner       | `dialog.root`        | None                       |                       |
+| Dialog container | `dialog.container`   | `consentDialog`            | `consent-dialog-root` |
+| Card             | `dialog.card`        | `consentDialogCard`        |                       |
+| Header           | `dialog.header`      | `consentDialogHeader`      |                       |
+| Title            | `dialog.title`       | `consentDialogTitle`       |                       |
+| Description      | `description.dialog` | `consentDialogDescription` |                       |
+| Content          | `dialog.content`     | `consentDialogContent`     |                       |
+| Backdrop         | `dialog.overlay`     | `consentDialogOverlay`     |                       |
+| "Secured by" tag | `tag.dialog`         | `consentDialogTag`         |                       |
+
+The stock dialog's footer is the preference widget's footer. Style it with
+`consentWidgetFooter`. There is no `consentDialogFooter` slot.
+
+## Preference widget parts
+
+The widget is the list of categories inside the dialog. React and Vue call it
+`manager`.
+
+| Part                   | `components` key                                                                                                                                                                                     | `theme.slots` key             |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| Widget root            | `manager.root`                                                                                                                                                                                       | `consentWidget`               |
+| Footer                 | `manager.footer`                                                                                                                                                                                     | `consentWidgetFooter`         |
+| Group of action groups | `manager.actions`                                                                                                                                                                                    | None                          |
+| One action group       | `manager.actionGroup`                                                                                                                                                                                | `consentWidgetFooterSubGroup` |
+| Category accordion     | `accordion.root`, `accordion.triggerRow`, `accordion.arrow`, `accordion.header`, `accordion.title`, `accordion.control`, `accordion.contentViewport`, `accordion.contentInner`                       | `consentWidgetAccordion`      |
+| One accordion item     | `accordion-item.root`, `accordion-item.trigger`, `accordion-item.content`                                                                                                                            | None                          |
+| Category switch        | `switch.root`, `switch.track`, `switch.thumb`                                                                                                                                                        | `toggle`                      |
+| Vendor list            | `vendor-list.root`, `vendor-list.trigger`, `vendor-list.content`, `vendor-list.item`, `vendor-list.header`, `vendor-list.name`, `vendor-list.description`, `vendor-list.link`, `vendor-list.control` | None                          |
+| "Secured by" tag       | `tag.manager` in React, `tag.dialog` in Vue                                                                                                                                                          | `consentWidgetTag`            |
+
+## Floating trigger parts
+
+| Part                         | `components` key                                                | `theme.slots` key                                                                                   |
+| ---------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button                       | `trigger.root`                                                  | `consentDialogTrigger`                                                                              |
+| Icon                         | `trigger.icon`                                                  | `consentDialogTriggerIcon`                                                                          |
+| Label                        | `trigger.text`                                                  | None                                                                                                |
+| Toolbar, its items and icons | `trigger.toolbar`, `trigger.toolbarItem`, `trigger.toolbarIcon` | `consentDialogTriggerToolbar`, `consentDialogTriggerToolbarItem`, `consentDialogTriggerToolbarIcon` |
+
+Only React renders the toolbar. Vue has no toolbar, and the toolbar slots only
+reach Astro's React dialog.
+
+## Legal links and IAB TCF parts
+
+| Component                          | `components` keys                                                                                                                                                                                                                                                          | `theme.slots` keys                                                                                                                               |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Legal links                        | `legal-links.root`, and `link.banner`, `link.dialog`, `link.manager` for one link                                                                                                                                                                                          | None                                                                                                                                             |
+| IAB banner                         | `iab-banner.root`, `cardShell`, `card`, `header`, `title`, `description`, `partnersLink`, `purposeList`, `purposeMore`, `legitimateInterestNotice`, `footer`, `actions`, `actionGroup`, `overlay`                                                                          | `iabConsentBanner`, `iabConsentBannerCard`, `iabConsentBannerHeader`, `iabConsentBannerFooter`, `iabConsentBannerTag`, `iabConsentBannerOverlay` |
+| IAB dialog                         | `iab-dialog.root`, `card`, `header`, `headerContent`, `title`, `description`, `closeButton`, `body`, `content`, `loading`, `footer`, `tabs`, `tabsList`, `tabTrigger`, `tabIndicator`, `tabPanel`, `specialPurposes`, `consentNotice`, `actions`, `actionGroup`, `overlay` | `iabConsentDialog`, `iabConsentDialogCard`, `iabConsentDialogHeader`, `iabConsentDialogFooter`, `iabConsentDialogTag`, `iabConsentDialogOverlay` |
+| IAB purpose, stack and vendor rows | `iab-purpose-item.*`, `iab-stack-item.*`, `iab-vendor-list.*`                                                                                                                                                                                                              | None                                                                                                                                             |
+
+Legal links take no `theme.slots` key. They keep their stock link class, and
+a description slot's classes stay on the description around them.
+
+## ConsentGate placeholder parts
+
+`ConsentGate` shows a placeholder card while its category is denied. React,
+Next.js, TanStack Start, Vue, Nuxt, Svelte and SvelteKit render the same
+three parts:
+
+| Part                          | `components` key      | `theme.slots` key   | `data-testid`              |
+| ----------------------------- | --------------------- | ------------------- | -------------------------- |
+| Placeholder card              | `consent-gate.root`   | `consentGate`       | `consent-gate-placeholder` |
+| Title                         | `consent-gate.title`  | `consentGateTitle`  | `consent-gate-title`       |
+| Button that opens preferences | `consent-gate.button` | `consentGateButton` | `consent-gate-button`      |
+
+The button part applies on top of `button.primary`, or `buttonPrimary`. The
+parts only reach the built-in placeholder. A placeholder you pass yourself
+takes your own classes, and the wrapper around the gate takes `className` in
+React or `class` in Svelte. Astro, HTML and JavaScript have no `ConsentGate`.
+
+## Style parts from outside the script tag's shadow root
+
+The script tag and `init()` render into a shadow root. Every part that has a
+`theme.slots` key carries it in a `part` attribute, so page CSS can reach it
+with `::part()`:
+
+```css
+[data-c15t-ui]::part(consentBannerCard) {
+  border: 3px solid #6943a3;
 }
 ```
 
-The class names above assume Tailwind. A slot can also receive `style` and other
-supported element attributes. Keep shared colors and radius scales in tokens;
-use slots when only one component part should change.
+## Select on state attributes
+
+Parts carry `data-*` attributes that describe their state. Select on these
+instead of guessing at markup:
+
+| Element                  | Attributes                                                                                                                |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
+| Banner root              | `data-prompt`, `data-model`, `data-variant`, `data-position`, `data-blocking`                                             |
+| Action buttons           | `data-action` (`accept`, `reject`, `customize`, `dismiss` or `save`), `data-variant`, `data-mode`                         |
+| Footer and action groups | `data-direction`, `data-fill`, `data-split`                                                                               |
+| Right links              | `data-action="right"`, `data-right`                                                                                       |
+| Preference dialog        | `data-state` (`open` or `closed`), on the elements listed in [motion](./motion.md#animate-your-own-rules-on-dialog-state) |
+| Category switch          | `data-state`, `data-disabled`                                                                                             |
+
+The script tag's banner root has `data-variant`, `data-position` and
+`data-blocking` only, with `data-blocking` set to `"true"` or `"false"`. Its
+right links carry `data-action="customize"`.
+
+The banner card does not inherit the root's attributes. With Tailwind, give
+the root `group` and read the root's attribute from a child part:
+
+```tsx
+components: {
+  banner: {
+    root: { className: 'group' },
+    card: { className: 'group-data-[variant=bar]:rounded-none' },
+  },
+},
+```
 
-## Read attributes on the right element
+Test notices as well as choice prompts. A notice has an acknowledge action,
+`data-action="dismiss"`, instead of accept and reject.
 
-The banner root carries `data-prompt`, `data-model`, `data-variant`,
-`data-position` and `data-blocking`. Its child card does not inherit those HTML
-attributes. In Tailwind, give the root `className: 'group'` and use
-`group-data-[variant=bar]:...` on a child slot.
+## Do not target c15t's class names
 
-| React banner slot                  | Use                                   |
-| ---------------------------------- | ------------------------------------- |
-| `root`                             | Position wrapper and state attributes |
-| `cardShell`                        | Card sizing and branding container    |
-| `card`                             | Visible card                          |
-| `header`, `title`, `description`   | Heading and explanatory copy          |
-| `footer`, `actions`, `actionGroup` | Action layout                         |
-| `rights`, `rightLink`              | Preferences access controls           |
-| `overlay`                          | Backdrop for blocking presentation    |
+c15t's stock class names are generated from CSS Modules and end in a hash, such
+as `c15t-ui-card-lgjVq`. The hash changes whenever the source CSS changes, and
+the classes disappear under `noStyle`. A rule that targets one breaks on an
+upgrade without warning. Target a part API, `data-testid`, a `data-*`
+attribute or `::part()` instead.
 
-Buttons expose `data-action` for action-specific CSS. Test notices as well as
-choice prompts; a notice uses acknowledgement rather than accept/reject.
+## Remove c15t's classes with noStyle
 
-## When to remove styles
+`noStyle` renders the same markup and behavior without c15t's stock classes. It
+keeps your part classes and styles, `data-testid` and the `data-*` attributes.
+It does not replace layout, spacing, focus indicators or responsive behavior,
+so use it when you intend to write all of that yourself.
 
-`noStyle` removes the built-in component styling. It does not supply replacement
-layout, spacing, focus indicators or responsive behavior. Use it when you intend
-to own all of that work, not as the first response to a token that appears to do
-nothing.
+| Framework                      | Where                                                                                                                                                                                              |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Next.js, TanStack Start, React | `noStyle` in the provider options for every component, or the `noStyle` prop on `ConsentBanner`, `ConsentDialog`, `ConsentWidget`, `ConsentDialogTrigger` and the IAB components                   |
+| Svelte, SvelteKit              | `noStyle` in the provider options, or the prop on a stock component                                                                                                                                |
+| Astro                          | `noStyle` prop on `ConsentBanner` and `IABConsentBanner`                                                                                                                                           |
+| HTML, JavaScript               | `ui.noStyle`, which also drops the bundled stylesheet                                                                                                                                              |
+| Vue, Nuxt                      | The `noStyle` prop on `ConsentWidget`, and on the `PreferenceItemRoot` and `PreferenceItemContent` primitives, whose other parts follow the root. The banner, dialog and trigger have no `noStyle` |
 
-If the markup itself must change, use the adapter's compound components or
-headless API. The slot objects above are the React contract; check Vue and Svelte
-slot types before reusing them.
+In `theme.slots`, `{ noStyle: true }` on one slot replaces that part's stock
+classes in Svelte, Astro's banner and the script tag. React and Vue, including
+Astro's React and Vue dialog islands, ignore a slot's `noStyle`, so its classes
+apply on top of the stock ones. If the markup itself must change, use your framework's compound
+components or headless API.

package/docs/customization/stylesheets.md

@@ -0,0 +1,147 @@
+---
+title: Stylesheets and CSS layers
+description: Load the right c15t stylesheet for your framework, see when the
+  dialog's CSS loads, order c15t's cascade layer against your own, and run c15t
+  without its styles.
+group: customization
+---
+
+## Load one stylesheet for your framework
+
+| Framework         | What to load                     | Where                                                                |
+| ----------------- | -------------------------------- | -------------------------------------------------------------------- |
+| Next.js           | `c15t/next/styles.css`           | Your global stylesheet, or the layout that renders the consent root  |
+| TanStack Start    | `c15t/tanstack-start/styles.css` | A `<link>` from the root route's `head()`, or your global stylesheet |
+| React             | `c15t/react/styles.css`          | The module that renders `ConsentProvider`, or your global stylesheet |
+| Nuxt, Vue         | Nothing                          | Each Vue component imports its own stylesheet                        |
+| Astro             | Nothing                          | The integration adds `c15t/astro/styles.css` to every page           |
+| Svelte, SvelteKit | `@c15t/svelte/styles.css`        | Your entry module or root layout                                     |
+| HTML              | Nothing                          | `c15t.js` carries its stylesheet into the UI's shadow root           |
+| JavaScript        | Nothing                          | `init()` carries its stylesheet into the UI's shadow root            |
+
+Load it once. With IAB TCF in Next.js, TanStack Start, React, Svelte or
+SvelteKit, also load the adapter's `iab/styles.css`, such as
+`c15t/next/iab/styles.css`, after `styles.css`. Astro adds its IAB stylesheet
+when the integration sets `iab`. Tailwind 3 uses the same files and adds a
+PostCSS plugin; [Tailwind CSS](./tailwind.md#set-up-tailwind-css-3)
+shows the setup.
+
+## What loads with the first paint
+
+A stylesheet that blocks rendering should hold only what the first paint can
+show. c15t's main stylesheet holds the default tokens, every c15t CSS variable,
+and the rules for the banner, the floating trigger and the `ConsentGate`
+placeholder. The preference dialog's rules load separately in most frameworks:
+
+| Framework                      | The preference dialog's rules                                                                                                                                                        |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Next.js, TanStack Start, React | The dialog's code imports `@c15t/ui/styles/dialog.css`. Your bundler emits it with the dialog's lazy chunk and loads it before that chunk runs, so the dialog never renders unstyled |
+| Nuxt, Vue                      | The dialog component imports its stylesheet, so the rules load with the dialog's code, not the banner's                                                                              |
+| Astro                          | c15t links the dialog's stylesheets when a visitor first points at, focuses or opens a control that opens the dialog, and keeps them across `ClientRouter` navigation                |
+| Svelte, SvelteKit              | Part of `@c15t/svelte/styles.css`, so they load up front                                                                                                                             |
+| HTML, JavaScript               | Part of the stylesheet in the shadow root, which holds only the rules the stock surfaces use                                                                                         |
+
+In React, Next.js and TanStack Start, do not import `dialog.css` yourself. The
+`@c15t/react/components/consent-dialog`, `/components/consent-widget`,
+`/primitives`, `/primitives/*` and `/iab` entry points import it as soon as
+you import them, because they render dialog parts outside the lazy chunk.
+
+These modules import the stylesheet through `@c15t/ui/styles/dialog`. Under
+the `node` export condition that module imports nothing, so server code that
+loads `@c15t/react` with plain Node, such as the Pages Router or an SSR build
+that keeps dependencies external, does not fail on the `.css` file. In your own
+components, import `@c15t/ui/styles/dialog` rather than the `.css` file if the
+module can run on the server.
+
+## Order c15t's layer against your CSS
+
+c15t puts its component rules in the cascade layer `components`. Tokens,
+variables and keyframes stay unlayered. Each stylesheet opens with Tailwind
+CSS 4's layer order:
+
+```css
+@layer properties, theme, base, components, utilities;
+```
+
+Cascade layers rank by the order they are first named, so `components` stays
+above Tailwind's preflight in `base` and below `utilities`, whichever
+stylesheet loads first. Without Tailwind the other layers stay empty. Vue's
+per-component stylesheets open with the same statement.
+
+What this means for your overrides:
+
+* Any unlayered rule of yours outranks every c15t component rule, whatever its
+  specificity or load order. You do not need `!important`.
+* A rule in one of your own layers wins only if that layer comes after
+  `components` in the layer order.
+* Tokens are not layered. Set them as described in
+  [theme tokens](./tokens.md).
+
+If your CSS declares its own layer order, load that statement before c15t's
+stylesheet. If you import c15t's stylesheet into a named layer, such as
+`@import 'c15t/react/styles.css' layer(c15t)`, the dialog's lazy rules still
+join the top-level `components` layer. List `components` in your statement,
+for example `@layer c15t, components, app;`, so it does not land after your
+own layers.
+
+## Load Astro's stylesheets yourself
+
+The Astro integration adds `c15t/astro/styles.css` to every page ahead of your
+own CSS. To control the order yourself, for example from a global stylesheet
+that names its own layers, set `styles: false` in the `c15t()` options and
+import the files after your layer order statement. With `styles: false`, c15t
+links no dialog stylesheet either, so import the dialog's rules too. The
+Svelte dialog, the default `ui`, also needs the primitives stylesheet:
+
+```css title="src/styles/global.css"
+@import 'c15t/astro/styles.css';
+@import 'c15t/astro/dialog.css';
+/* Only with ui: 'svelte'. */
+@import 'c15t/astro/primitives.css';
+/* Only when the integration sets iab. */
+@import 'c15t/astro/iab/styles.css';
+```
+
+Keep c15t's stylesheet when you restyle the surfaces. The browser hides the
+Astro banner with the `hidden` attribute, and the stylesheet makes that
+attribute beat the banner's own `display` rule.
+
+## Style the script tag's shadow root
+
+The script tag and `init()` from `@c15t/browser` render into a shadow root with
+their own copy of the stylesheet. Your page's CSS does not reach the UI, and
+the UI's CSS does not reach your page. To style it:
+
+| Option                                       | What it does                                                                                                                                                               |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ui.theme`                                   | Tokens, written after the stylesheet inside the shadow root                                                                                                                |
+| `ui.css`                                     | A string of CSS added after the stylesheet and the theme                                                                                                                   |
+| `ui.stylesheetURLs`                          | Stylesheets linked inside the shadow root, after c15t's, with the client's `nonce`. They load asynchronously, so the first frame can render without them                   |
+| `::part()`                                   | Page CSS that reaches a part by its slot key, as in `[data-c15t-ui]::part(consentBannerCard)`                                                                              |
+| `ui.shadow: false`, or `data-shadow="false"` | Renders into the page, so your stylesheets apply. c15t still injects its stylesheet next to the UI                                                                         |
+| `ui.styles: false`                           | Drops the injected stylesheet. With `shadow: false`, load `@c15t/browser/styles.css` from your bundle, or link `dist/c15t.css` from the same package version as the script |
+
+A stylesheet in `ui.stylesheetURLs` should also load on the page. Some CSS,
+such as Tailwind 4's `@property` rules, only takes effect in the page's
+stylesheets. Of these options, the script tag has an attribute for `shadow`
+only. Set the others with `c15t.push(['config', { ui: { ... } }])`.
+
+## Run without c15t's styles
+
+`noStyle` removes c15t's stock classes from the markup, and in the script tag
+also the injected stylesheet. Your part classes, `data-testid` and the `data-*`
+attributes stay. [Component parts](./slots.md#remove-c15ts-classes-with-nostyle)
+lists where each framework takes it.
+
+`noStyle` does not supply layout, spacing, focus indicators or responsive
+behavior. If a token seems to do nothing, check the layer order and your
+selector before you reach for `noStyle`.
+
+## Check the result
+
+1. Open DevTools Network, clear site data and reload. Your framework's c15t
+   stylesheet loads once, and no second copy appears.
+2. Open the preference dialog. It is styled on its first frame, with no flash
+   of unstyled content.
+3. Select a banner part and read the Styles panel. c15t's rules appear under
+   `@layer components`, and your unlayered rules for the same property win.