@redacto.io/consent-sdk-react 10.2.2-beta.3 → 10.3.0-beta.4

package/README.md

@@ -87,7 +87,7 @@ The SDK follows a client-server architecture pattern:
   - Token-based authentication
 
 - **Configuration**
-  - Customizable UI settings
+  - Appearance set in the Redacto console (templates, colours, styles)
   - Language preferences
   - API endpoint configuration
 
@@ -326,7 +326,7 @@ A modal popup component for consent collection. Displays a full-screen modal wit
 | `ledgerBaseUrl`   | `string`                 | No       | -       | Go ledger base URL. When set, consent writes and prior-consent checks route through the ledger (falls back: ledger → baseUrl → default). Omit to keep the legacy consent-server path. |
 | `blockUI`         | `boolean`                | No       | `true`  | Whether to block UI interaction     |
 | `language`        | `string`                 | No       | `"en"`  | Language code                       |
-| `settings`        | `object`                 | No       | -       | Custom styling options              |
+| `settings`        | `object`                 | No       | -       | Optional code overrides; win over the console appearance key by key. See [Appearance](#notice-appearance) |
 | `applicationId`   | `string`                 | No       | -       | Application-specific UUID           |
 | `validateAgainst` | `"all" \| "required"`    | No       | `"all"` | Consent validation mode (see below) |
 | `includeFullyConsentedData` | `boolean` | No | `false` | When true, API returns 200 with pre-selected purposes instead of 409 when user has already consented |
@@ -412,7 +412,7 @@ The component automatically submits consent when all of the following conditions
 | `baseUrl`            | `string`                     | No       | -       | Base URL for the consent API           |
 | `ledgerBaseUrl`      | `string`                     | No       | -       | Go ledger base URL. When set, consent writes and already-consented checks route through the ledger. Omit for legacy behavior. |
 | `language`           | `string`                     | No       | `"en"`  | Language code                          |
-| `settings`           | `object`                     | No       | -       | Custom styling options                 |
+| `settings`           | `object`                     | No       | -       | Optional code overrides of the console appearance |
 | `applicationId`      | `string`                     | No       | -       | Application-specific UUID              |
 | `onAccept`           | `() => void`                 | No       | -       | Callback when consent is accepted      |
 | `onDecline`          | `() => void`                 | No       | -       | Callback when consent is declined      |
@@ -745,56 +745,136 @@ export function AssistedConsent() {
 }
 ```
 
-### Custom Styling
+<a id="notice-appearance"></a>
 
-`RedactoNoticeConsent` and `RedactoNoticeConsentInline` support extensive styling customization via the `settings` prop, which overrides the notice's own API configuration. (`RedactoNoticeAssisted` does not take a `settings` prop — it themes itself entirely from the notice's API configuration, such as primary/secondary colour and font.)
+### Appearance (set in the Redacto console)
+
+How a notice looks is configured by your workspace admin in the Redacto console,
+in the notice wizard's **Display settings → Appearance** step, and served with the
+notice. No code change is needed: every notice component (`RedactoNoticeConsent`,
+`RedactoNoticeConsentInline`, `RedactoNoticeAssisted`) on every platform renders
+what the console saved.
+
+The console offers:
+
+- **Templates:** Classic, Glass and Dark, as starting points.
+- **Style:**
+  - **`classic`:** the centred modal.
+  - **`minimal`:** flat, with hairline edges and no shadows.
+  - **`soft`:** a lifted, rounded card with brand-washed purpose rows and pill buttons.
+  - **`glass`:** a translucent, frosted sheet. It docks to the bottom on phones and floats as a card on wider screens. The notice text and the grievance/DPO block collapse into sections. On phones, Accept Selected and Decline sit side by side under Accept All.
+- **Colours:** Light, Dark, From brand colour, or fully Custom. There are per-element colours for the background, text, links, borders, overlay and each button, the toggle states, and the **text-to-speech highlight**.
+- **Layout, in any style:**
+  - on phones, a centred **modal** or a **bottom sheet**
+  - on wider screens, **centre**, **bottom right**, **bottom left** or a full-width **bottom bar**
+  - whether the page behind is **dimmed**
+  - **collapsible** notice text and grievance/DPO sections
+  - a **stacked or paired** phone footer
+- **Colours:** optionally a second, dark palette that applies automatically when the visitor's device is in **dark mode**.
+- **Size and type:** the card's **max width**, the **logo size** and a **text size** (small, regular or large).
+- **Corner radius**, the **selection control** (checkbox, radio or dropdown), whether checkbox rows are drawn as **checkboxes or switches** (in any style), an optional **"are you sure" step** before submitting, and whether the notice **animates**.
+- **Custom CSS**, scoped to the notice (see below).
+
+A notice whose admin set no appearance renders as classic from its brand colours,
+exactly as before. Developers can still override any of it in code (below), and
+code wins. Motion respects `prefers-reduced-motion`.
+
+#### Custom CSS
+
+Admins can add CSS for a notice in the console, and hosts can pass `settings.customCss`. It applies only to that notice: the SDK wraps it in `@scope ([data-redacto-notice-id="<notice uuid>"])` and removes it when the notice unmounts. CSS carrying `@import`, `javascript:`, `expression(`, `behavior:` or `</style` (even escaped) is refused whole, as is anything over 20,000 characters and anything whose brackets don't pair up (a stray `}` would close the scope).
+
+Target the notice's parts through stable hooks:
+
+`root`, `overlay`, `header`, `logo`, `title`, `language`, `notice-text`, `purposes`, `product`, `purpose`, `purpose-title`, `data-element`, `section`, `dpo`, `footer`, `accept-all`, `accept-selected`, `decline`, `confirm-dialog`, `otp`
+
+The notice styles its parts inline, so use `!important`:
+
+```css
+[data-redacto-part="accept-all"] {
+  border-radius: 0 !important;
+  text-transform: uppercase;
+}
+```
+
+`@scope` is supported by current Chrome, Edge, Safari (17.4+) and Firefox (128+); older browsers skip the custom CSS and draw the notice as configured.
+
+#### Overriding the console in code (`settings`)
+
+`settings` is optional. Anything you set there **wins over the console, key by key**. Every key you leave out keeps the console's value, which in turn falls back to the notice's brand colours.
+
+The order is:
+
+1. host `settings`
+2. console appearance
+3. brand colours and SDK defaults
+
+`settings` covers everything the console does:
 
 ```tsx
-const customSettings = {
-  button: {
-    accept: {
-      backgroundColor: "#9810fa",
-      textColor: "white",
-    },
-    decline: {
-      backgroundColor: "#0a0a14",
-      textColor: "white",
-    },
-    language: {
-      backgroundColor: "#0a0a14",
-      textColor: "white",
-      selectedBackgroundColor: "#9810fa",
-      selectedTextColor: "white",
-    },
-  },
-  borderRadius: "8px",
-  backgroundColor: "#1a1a2e",
-  headingColor: "#ffffff",
-  textColor: "#e6e6e6",
-  borderColor: "white",
-  link: "#9810fa",
-  font: "Arial, sans-serif", // Optional: overrides the notice's Font Family
-};
-
-// Use in component
 <RedactoNoticeConsent
   // ... other props
-  settings={customSettings}
-/>;
+  settings={{
+    theme: "glass", // "classic" | "glass" | "minimal" | "soft"
+    backgroundColor: "#ffffff",
+    surfaceColor: "#f8fafc",
+    headingColor: "#101828",
+    textColor: "#344054",
+    mutedTextColor: "#475467",
+    borderColor: "#d0d5dd",
+    overlayColor: "rgba(0, 0, 0, 0.5)",
+    link: "#4f87ff",
+    borderRadius: "12px",
+    font: "Inter, system-ui, sans-serif",
+    button: {
+      accept: { backgroundColor: "#4f87ff", textColor: "#ffffff" }, // brand accent; Accept All's fallback
+      acceptAll: { backgroundColor: "#4f87ff", textColor: "#ffffff" },
+      acceptSelected: { backgroundColor: "#ffffff", textColor: "#4f87ff" },
+      decline: { backgroundColor: "#ffffff", textColor: "#000000", borderColor: "#d0d5dd" },
+      language: {
+        backgroundColor: "#ffffff",
+        textColor: "#344054",
+        selectedBackgroundColor: "#f3f4f6",
+        selectedTextColor: "#344054",
+      },
+    },
+    toggle: { onColor: "#4f87ff", offColor: "#d0d5dd", knobColor: "#ffffff" },
+    ttsHighlight: { backgroundColor: "#FFF9C4", textColor: "#111827" },
+    selectionControl: "checkbox", // "checkbox" | "radio" | "dropdown"
+    controlStyle: "switch", // "checkbox" | "switch", in any style (default: checkboxes)
+    confirmBeforeSubmit: false,
+    mobileLayout: "sheet", // "modal" | "sheet"
+    desktopPosition: "bottom-right", // "center" | "bottom-right" | "bottom-left" | "bottom-bar"
+    backdrop: "none", // "dim" | "none"
+    collapsibleSections: true,
+    phoneFooter: "paired", // "stacked" | "paired"
+    autoDark: true, // follow the device's dark mode with darkPalette (else the console's)
+    darkPalette: { backgroundColor: "#0b1220", headingColor: "#f8fafc", textColor: "#cbd5e1" },
+    maxWidth: "560px",
+    logoSize: "40px",
+    textScale: "lg", // "sm" | "md" | "lg"
+    motion: false,
+    customCss: '[data-redacto-part="accept-all"] { border-radius: 0 !important; }',
+  }}
+/>
 ```
 
-### Available Style Properties
+Existing integrations keep working unchanged. `button.accept` keeps its meaning: it is the brand accent, and Accept All's colour when `acceptAll` is unset. Host colours override the light palette; when automatic dark mode is on and the device is dark, the dark palette replaces them, and `darkPalette` is where a host overrides it. `RedactoNoticeConsentInline` and `RedactoNoticeAssisted` take the same `settings` and use the parts they draw:
+- **Inline:** text and control colours, the selection control and switches, text size, dark mode and custom CSS.
+- **Assisted:** the full palette, style shape, corners, text size, logo position, dark mode and custom CSS.
+
+Layout, size and motion keys apply to the modal notice only. `docs/sdk-appearance-spec.md` lists every console setting and which component draws it.
+
+#### Previewing a notice (console use)
+
+`RedactoNoticePreview` draws a notice from given content, the same way a visitor
+sees it. It fetches, submits, plays and focuses nothing. It exists for the Redacto
+console's live preview and is not meant for visitor-facing pages.
 
-- `backgroundColor`: Background color of the modal/form
-- `headingColor`: Color for headings
-- `textColor`: Color for body text
-- `borderColor`: Color for borders
-- `borderRadius`: Border radius for rounded corners
-- `link`: Color for links
-- `font`: Font family (optional) — overrides the Font Family configured on the notice
-- `button.accept`: Styles for accept button
-- `button.decline`: Styles for decline button
-- `button.language`: Styles for language selector
+```tsx
+import { RedactoNoticePreview } from "@redacto.io/consent-sdk-react";
+
+<RedactoNoticePreview content={noticeReadResponse} isMobile />;
+```
 
 #### Font family
 
@@ -803,14 +883,9 @@ Redacto console (`active_config.font_preference`), so the rendered notice matche
 console's live preview without any host configuration.
 
 Resolution order is `settings.font` → the notice's Font Family → the host page's font.
-Pass `settings.font` only when the host needs to override the configured family; omit it
-and the console selection is used. The selected family is expanded into a full CSS stack
-with a generic fallback (`Times New Roman` becomes `"Times New Roman", Times, serif`).
-
-The two sources are deliberately **not** interchangeable. The notice's own Font Family must be one
-of the families above; a stored value that is no longer offered renders as Arial, so the console and
-the notice can never disagree. `settings.font` is a host override and is respected verbatim — pass a
-family you have loaded yourself, or a full stack, and the SDK uses it as-is.
+The selected family is expanded into a full CSS stack with a
+generic fallback (`Times New Roman` becomes `"Times New Roman", Times, serif`). A stored value
+that is no longer offered renders as Arial, so the console and the notice can never disagree.
 
 **Available families.** One is a self-hosted webfont — Montserrat — and five are system families
 needing no download: Arial, Georgia, Times New Roman, Trebuchet MS, Verdana. The catalogue is
@@ -888,7 +963,7 @@ import { RedactoPrivacyCenter } from "@redacto.io/consent-sdk-react/privacy-cent
   slug="acme-co"
   accessToken={accessToken}
   refreshToken={refreshToken}
-  theme="light"
+  settings={{ theme: "glass" }}
   initialPage="consent-manager"
   onError={(error) => {
     console.error(error);
@@ -907,17 +982,28 @@ import { RedactoPrivacyCenter } from "@redacto.io/consent-sdk-react/privacy-cent
 | `accessToken`  | `string`                                                                                                                   | Yes      | -                    | JWT access token                                         |
 | `refreshToken` | `string`                                                                                                                   | Yes      | -                    | JWT refresh token                                        |
 | `onError`      | `(error: Error) => boolean`                                                                                                | Yes      | -                    | Error handler; return `true` if handled                  |
-| `theme`        | `"light" \| "dark"`                                                                                                        | No       | `"light"`            | Theme variant                                            |
+| `settings`     | `{ theme?: "classic" \| "glass" }`                                                                                        | No       | -                    | Presentation options; `theme` picks the visual style (see [Theme](#privacy-center-appearance)). Colours always come from workspace branding |
 | `initialPage`  | `"consent-manager" \| "form" \| "activity" \| "case-details"`                                                              | No       | `"consent-manager"` | Page to render first                                     |
 | `onBack`       | `"back" \| "signout"`                                                                                                      | No       | -                    | Behaviour of the navbar back/signout control             |
 
+<a id="privacy-center-appearance"></a>
+
+### Theme
+
+`settings.theme` picks the visual style; colours, logo and brand name still come from the workspace's branding.
+
+- **`classic`** (default): the standard look.
+- **`glass`**: frosted, translucent surfaces over a soft wash of the brand colour, pill-shaped controls and motion. On phones, dialogs and the navigation menu rise as bottom sheets; on wider screens dialogs float as centred cards. Motion respects `prefers-reduced-motion`.
+
+Unknown values fall back to `classic`. When composing `PrivacyCenterLayout` yourself, pass `settings={{ theme: "glass" }}` to it directly.
+
 ### Composable Pages and Layout
 
 If you want to compose your own shell (e.g. embed the Privacy Center inside an existing app chrome), import the page-level building blocks instead of the certified component:
 
 | Export                              | Purpose                                                                  |
 | ----------------------------------- | ------------------------------------------------------------------------ |
-| `PrivacyCenterLayout`               | Outer chrome (navbar, sidebar, footer, theme)                            |
+| `PrivacyCenterLayout`               | Outer chrome (navbar, sidebar, footer); accepts `settings.theme`        |
 | `PrivacyCenterHomePage`             | Default home that switches between the pages below                       |
 | `PrivacyCenterConsentManagerPage`   | "Manage Consents" view                                                   |
 | `PrivacyCenterFormPage`             | DSR / grievance form                                                     |