@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/ConsentBanner/ConsentBanner.tsx

@@ -0,0 +1,210 @@
+"use client";
+
+import { useId, useRef, type ReactElement, type ReactNode } from "react";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { Button } from "../Button/Button.tsx";
+import { Checkbox } from "../Forms/Checkbox.tsx";
+import { Icon } from "../Icon/Icon.tsx";
+import { Link, linkClass } from "../Link/Link.tsx";
+import type { ConsentChoice } from "./consent.ts";
+import {
+  tickedCategories,
+  useConsent,
+  type ConsentAction,
+  type ConsentRecording,
+} from "./useConsent.ts";
+
+/** A link the consent copy names: the Cookie Policy or the Cookie settings page. */
+export interface ConsentLink {
+  label: string;
+  href: string;
+}
+
+/**
+ * Draws one of the consent links. An app with a router passes its own link component here, so the
+ * policy and the settings page open without a full page load; `className` is the library's link
+ * style. It is a function, so it comes from a client module.
+ */
+export type ConsentLinkRenderer = (link: ConsentLink, className: string) => ReactNode;
+
+/** A consent link as the default anchor, or as the app's `renderLink` draws it. */
+export function ConsentLinkText({
+  link,
+  renderLink,
+}: {
+  link: ConsentLink;
+  renderLink: ConsentLinkRenderer | undefined;
+}): ReactNode {
+  return renderLink ? renderLink(link, linkClass) : <Link href={link.href}>{link.label}</Link>;
+}
+
+/** An optional cookie category behind Choose. */
+export interface ConsentCategory {
+  /**
+   * The field name the category posts under and the key it is recorded by. It must match
+   * `CONSENT_CATEGORY_NAME`: a letter, then letters, digits, underscores or hyphens, 64 characters
+   * at most (`preferences`, `analytics_storage`). The cookie adapter rejects a write with any
+   * other name.
+   */
+  name: string;
+  label: string;
+}
+
+export interface ConsentBannerProps {
+  title: string;
+  body?: string;
+  policy?: ConsentLink;
+  acceptLabel?: string;
+  rejectLabel?: string;
+  chooseLabel?: string;
+  necessary?: string;
+  categories?: ConsentCategory[];
+  saveLabel?: string;
+  /** The browser sends Global Privacy Control: show the confirmation instead of the choices. */
+  gpc?: boolean;
+  onChoice?: (choice: ConsentChoice) => void;
+  /** A second link after the policy, to the page where the choice can be changed. */
+  settings?: ConsentLink;
+  /** The Global Privacy Control confirmation; the `mk.consent.gpc` catalog message when omitted. */
+  gpcLabel?: string;
+  /** Posts the choice as plain forms, which work before any script loads. */
+  action?: ConsentAction;
+  /** Draws the policy and settings links with the app's router link; a plain anchor when omitted. */
+  renderLink?: ConsentLinkRenderer;
+  /**
+   * Lets the banner keep the decision itself: it reads the adapter once, stays hidden when a
+   * decision exists, and writes each choice with its timestamp, policy version and signal flag.
+   */
+  record?: ConsentRecording;
+}
+
+const sectionClass = cx(
+  "border-b border-border-subtle bg-bg-surface p-16 font-sans text-text-primary print:hidden",
+);
+const innerClass = cx("mx-auto flex max-w-layout-reading flex-col gap-12");
+const textClass = cx("m-0 text-text-13 text-text-secondary");
+
+/**
+ * The cookie banner both sites share (Section 14.3). Accept and Reject are the same Button, side by
+ * side, and no category behind Choose starts ticked. A Global Privacy Control signal, from the
+ * request (`gpc`) or from `navigator.globalPrivacyControl`, is a refusal: the banner shows the
+ * confirmation and offers no choices. Every string is a prop or comes from the `ui` catalog.
+ */
+export function ConsentBanner({
+  title,
+  body,
+  policy,
+  acceptLabel,
+  rejectLabel,
+  chooseLabel,
+  necessary,
+  categories,
+  saveLabel,
+  gpc,
+  onChoice,
+  settings,
+  gpcLabel,
+  action,
+  renderLink,
+  record,
+}: ConsentBannerProps): ReactElement | null {
+  const t = useT();
+  const id = useId();
+  const custom = useRef<HTMLFormElement>(null);
+  const names = (categories ?? []).map((c) => c.name);
+  const { signal, stored, choose } = useConsent({
+    gpc,
+    categories: names,
+    record,
+    action,
+    onChoice,
+  });
+
+  if (signal) {
+    return (
+      <section className={sectionClass} aria-label={title}>
+        <div className={innerClass}>
+          <p className="m-0 flex items-center gap-8 text-text-13" role="status">
+            <span className="flex text-success">
+              <Icon name="ShieldCheck" size={16} />
+            </span>
+            <span>{gpcLabel ?? t("mk.consent.gpc")}</span>
+          </p>
+        </div>
+      </section>
+    );
+  }
+  // With an adapter the banner waits for the stored consent, and a visitor who decided sees nothing.
+  if (record !== undefined && stored !== null) return null;
+
+  const posts = action !== undefined;
+  const type = posts ? "submit" : "button";
+  return (
+    <section className={sectionClass} aria-labelledby={id}>
+      <div className={innerClass}>
+        <h2 id={id} className="m-0 text-heading-16 font-semibold">
+          {title}
+        </h2>
+        {body || policy || settings ? (
+          <p className={textClass}>
+            {body}
+            {policy ? (
+              <>
+                {" "}
+                <ConsentLinkText link={policy} renderLink={renderLink} />
+              </>
+            ) : null}
+            {settings ? (
+              <>
+                {policy ? " · " : " "}
+                <ConsentLinkText link={settings} renderLink={renderLink} />
+              </>
+            ) : null}
+          </p>
+        ) : null}
+        <form
+          {...(posts ? { action } : {})}
+          onSubmit={posts ? undefined : (event) => event.preventDefault()}
+          className="flex flex-wrap items-center gap-8"
+        >
+          <Button type={type} name="choice" value="all" size="lg" onClick={() => choose("all")}>
+            {acceptLabel}
+          </Button>
+          <Button type={type} name="choice" value="none" size="lg" onClick={() => choose("none")}>
+            {rejectLabel}
+          </Button>
+        </form>
+        {categories ? (
+          <details>
+            <summary className="w-fit cursor-pointer text-text-13 font-medium text-accent-text">
+              {chooseLabel}
+            </summary>
+            {/* data-keep-input: the save always succeeds and the page renders again from the stored choice. */}
+            <form
+              ref={custom}
+              {...(posts ? { action } : {})}
+              onSubmit={posts ? undefined : (event) => event.preventDefault()}
+              data-keep-input="not-refusable"
+              className="mt-8 flex flex-col items-start gap-8 text-text-13"
+            >
+              <input type="hidden" name="choice" value="save" />
+              {necessary ? <p className={textClass}>{necessary}</p> : null}
+              {categories.map((c) => (
+                <Checkbox key={c.name} name={c.name} label={c.label} />
+              ))}
+              <div>
+                <Button
+                  type={type}
+                  onClick={() => choose("save", tickedCategories(custom.current, names))}
+                >
+                  {saveLabel}
+                </Button>
+              </div>
+            </form>
+          </details>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/src/ConsentBanner/ConsentBannerStatic.tsx

@@ -0,0 +1,163 @@
+import type { ReactElement, ReactNode } from "react";
+import { buttonClass } from "../Button/button-class.ts";
+import { Icon } from "../Icon/Icon.tsx";
+import { cx } from "../lib/cx.ts";
+import { linkClass } from "../Link/link-class.ts";
+import type { ConsentCategory, ConsentLink } from "./ConsentBanner.tsx";
+
+/**
+ * Draws one of the consent links in a server component. Unlike `ConsentLinkRenderer` it never
+ * crosses to the client, so a server component can pass its router's link component directly.
+ */
+export type ConsentStaticLinkRenderer = (link: ConsentLink, className: string) => ReactNode;
+
+interface ConsentBannerStaticCopy {
+  title: string;
+  body?: string;
+  policy?: ConsentLink;
+  /** A second link after the policy, to the page where the choice can be changed. */
+  settings?: ConsentLink;
+  acceptLabel: string;
+  rejectLabel: string;
+  chooseLabel?: string;
+  necessary?: string;
+  categories?: ConsentCategory[];
+  saveLabel?: string;
+  /**
+   * Where the forms post: a URL, or a function such as a Next.js server action. The fields are
+   * `choice` (`all`, `none` or `save`) and each ticked category by name with the value `on`.
+   */
+  action: string | ((form: FormData) => void | Promise<void>);
+  /** Draws the policy and settings links with the app's router link; a plain anchor when omitted. */
+  renderLink?: ConsentStaticLinkRenderer;
+  /** The id of the heading the region is labelled by, when the page needs its own. */
+  headingId?: string;
+}
+
+/**
+ * `gpc`: the request carries `Sec-GPC: 1` (`sendsGlobalPrivacyControl`), so the banner shows the
+ * confirmation in place of the choices. The caller records the refusal; this component only says
+ * so. `gpcLabel` is the confirmation, and the type requires it whenever `gpc` can be true: there is
+ * no catalog to fall back on in a server component.
+ */
+type ConsentBannerStaticSignal =
+  | { gpc: true; gpcLabel: string }
+  | { gpc?: false; gpcLabel?: string }
+  | { gpc: boolean; gpcLabel: string };
+
+export type ConsentBannerStaticProps = ConsentBannerStaticCopy & ConsentBannerStaticSignal;
+
+const sectionClass = cx(
+  "border-b border-border-subtle bg-bg-surface p-16 font-sans text-text-primary print:hidden",
+);
+const innerClass = cx("mx-auto flex max-w-layout-reading flex-col gap-12");
+const textClass = cx("m-0 text-text-13 text-text-secondary");
+/** Accept and Reject are this one class: the same variant and the same size. */
+const choiceClass = buttonClass("secondary", "lg");
+
+function link(target: ConsentLink, renderLink: ConsentStaticLinkRenderer | undefined): ReactNode {
+  return renderLink ? (
+    renderLink(target, linkClass)
+  ) : (
+    <a href={target.href} className={linkClass}>
+      {target.label}
+    </a>
+  );
+}
+
+/**
+ * The cookie banner with no script (Section 14.3): the markup and the equal choices of
+ * ConsentBanner as plain forms, with no hooks, context or event handlers, so a server component
+ * that renders it sends no JavaScript for it (ADR 0027). Atlas shows it on every route. It reads
+ * nothing from the browser: it does not see `navigator.globalPrivacyControl`, keeps no record and
+ * does not hide itself, so the server decides whether to render it and passes `gpc` from the
+ * request header. Use ConsentBanner where the banner keeps the decision through an adapter.
+ */
+export function ConsentBannerStatic({
+  title,
+  body,
+  policy,
+  settings,
+  acceptLabel,
+  rejectLabel,
+  chooseLabel,
+  necessary,
+  categories,
+  saveLabel,
+  action,
+  gpc,
+  gpcLabel,
+  renderLink,
+  headingId = "consent-banner-title",
+}: ConsentBannerStaticProps): ReactElement {
+  if (gpc) {
+    return (
+      <section className={sectionClass} aria-label={title}>
+        <div className={innerClass}>
+          <p className="m-0 flex items-center gap-8 text-text-13" role="status">
+            <span className="flex text-success">
+              <Icon name="ShieldCheck" size={16} />
+            </span>
+            <span>{gpcLabel}</span>
+          </p>
+        </div>
+      </section>
+    );
+  }
+  return (
+    <section className={sectionClass} aria-labelledby={headingId}>
+      <div className={innerClass}>
+        <h2 id={headingId} className="m-0 text-heading-16 font-semibold">
+          {title}
+        </h2>
+        {body || policy || settings ? (
+          <p className={textClass}>
+            {body}
+            {policy ? <> {link(policy, renderLink)}</> : null}
+            {settings ? (
+              <>
+                {policy ? " · " : " "}
+                {link(settings, renderLink)}
+              </>
+            ) : null}
+          </p>
+        ) : null}
+        <form action={action} className="flex flex-wrap items-center gap-8">
+          <button type="submit" name="choice" value="all" className={choiceClass}>
+            {acceptLabel}
+          </button>
+          <button type="submit" name="choice" value="none" className={choiceClass}>
+            {rejectLabel}
+          </button>
+        </form>
+        {categories && chooseLabel && saveLabel ? (
+          <details>
+            <summary className="w-fit cursor-pointer text-text-13 font-medium text-accent-text">
+              {chooseLabel}
+            </summary>
+            {/* data-keep-input: the save always succeeds and the page renders again from the stored choice. */}
+            <form
+              action={action}
+              data-keep-input="not-refusable"
+              className="mt-8 flex flex-col items-start gap-8 text-text-13"
+            >
+              <input type="hidden" name="choice" value="save" />
+              {necessary ? <p className={textClass}>{necessary}</p> : null}
+              {categories.map((category) => (
+                <label key={category.name} className="flex items-start gap-8">
+                  <input type="checkbox" name={category.name} className="mt-2" />
+                  <span>{category.label}</span>
+                </label>
+              ))}
+              <div>
+                <button type="submit" className={buttonClass("secondary", "md")}>
+                  {saveLabel}
+                </button>
+              </div>
+            </form>
+          </details>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/src/ConsentBanner/ConsentSettings.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import { useRef, type ReactElement } from "react";
+import { cx } from "../lib/cx.ts";
+import { useT } from "../lib/context.tsx";
+import { Button } from "../Button/Button.tsx";
+import { Checkbox } from "../Forms/Checkbox.tsx";
+import { InlineAlert } from "../Feedback/InlineAlert.tsx";
+import type { ConsentChoice, ConsentState } from "./consent.ts";
+import {
+  ConsentLinkText,
+  type ConsentCategory,
+  type ConsentLink,
+  type ConsentLinkRenderer,
+} from "./ConsentBanner.tsx";
+import {
+  tickedCategories,
+  useConsent,
+  type ConsentAction,
+  type ConsentRecording,
+} from "./useConsent.ts";
+
+/** An optional category on the settings page, with the choice in force. */
+export interface ConsentSettingsCategory extends ConsentCategory {
+  /** The category is allowed now. With `record`, the stored consent decides instead. */
+  checked?: boolean;
+}
+
+/** The table of cookies the site sets, which a cookie policy asks for by name. */
+export interface ConsentCookieTable {
+  caption: string;
+  nameLabel: string;
+  categoryLabel: string;
+  purposeLabel: string;
+  rows: { name: string; category: string; purpose: string }[];
+}
+
+export interface ConsentSettingsProps {
+  title: string;
+  lead?: string;
+  /**
+   * The sentence that states the choice in force. A function receives the stored consent, or null
+   * before a choice, when `record` keeps the decision.
+   */
+  status: string | ((state: ConsentState | null) => string);
+  /** The request carries Global Privacy Control. */
+  gpc?: boolean;
+  /** What the signal means here; the `mk.consent.gpc` catalog message when omitted. */
+  gpcNotice?: string;
+  categoriesLabel: string;
+  /** The strictly necessary category, shown ticked and locked. */
+  necessary: string;
+  categories: ConsentSettingsCategory[];
+  saveLabel: string;
+  acceptLabel: string;
+  rejectLabel: string;
+  cookies?: ConsentCookieTable;
+  policy?: ConsentLink;
+  /** The heading level of the title: 1 on a page of its own. */
+  headingLevel?: 1 | 2;
+  onChoice?: (choice: ConsentChoice) => void;
+  /** Posts the choice as plain forms, which work before any script loads. */
+  action?: ConsentAction;
+  /** Lets the page keep the decision itself, through an adapter. */
+  record?: ConsentRecording;
+  /** Draws the policy link with the app's router link; a plain anchor when omitted. */
+  renderLink?: ConsentLinkRenderer;
+}
+
+const cellClass = cx("py-4 pe-8 text-start");
+
+/**
+ * The settings view of the cookie banner (Section 14.3): the choice in force, the categories, the
+ * same Accept and Reject pair at equal weight, and the cookies by name. Under Global Privacy
+ * Control it says so, and the optional categories and Accept are locked while the signal is on.
+ */
+export function ConsentSettings({
+  title,
+  lead,
+  status,
+  gpc,
+  gpcNotice,
+  categoriesLabel,
+  necessary,
+  categories,
+  saveLabel,
+  acceptLabel,
+  rejectLabel,
+  cookies,
+  policy,
+  headingLevel = 1,
+  onChoice,
+  action,
+  record,
+  renderLink,
+}: ConsentSettingsProps): ReactElement {
+  const t = useT();
+  const custom = useRef<HTMLFormElement>(null);
+  const names = categories.map((c) => c.name);
+  const { signal, browserOnly, stored, choose } = useConsent({
+    gpc,
+    categories: names,
+    record,
+    action,
+    onChoice,
+  });
+  const Heading = headingLevel === 1 ? "h1" : "h2";
+  const posts = action !== undefined;
+  const type = posts ? "submit" : "button";
+  const allowed = (c: ConsentSettingsCategory): boolean =>
+    record === undefined ? (c.checked ?? false) : stored?.categories[c.name] === true;
+  // The boxes are uncontrolled so they work before any script loads; a new stored choice remounts
+  // them, and only them, so the button that was pressed keeps the keyboard focus.
+  const boxesKey = record === undefined ? "props" : JSON.stringify(stored ?? null);
+  // Only the browser reports the signal: tell the server, which saw no Sec-GPC header.
+  const gpcField = browserOnly ? <input type="hidden" name="gpc" value="1" /> : null;
+  return (
+    <div className="mx-auto flex max-w-layout-reading flex-col gap-16 p-24">
+      <Heading className="m-0 text-heading-24 font-semibold">{title}</Heading>
+      {lead ? <p className="m-0 text-text-14 text-text-secondary">{lead}</p> : null}
+      {signal ? <InlineAlert tone="info">{gpcNotice ?? t("mk.consent.gpc")}</InlineAlert> : null}
+      <p className="m-0 text-text-14" role="status">
+        {typeof status === "function" ? status(stored ?? null) : status}
+      </p>
+      {/* data-keep-input: the save always succeeds and the page renders again from the stored choice. */}
+      <form
+        ref={custom}
+        {...(posts ? { action } : {})}
+        onSubmit={posts ? undefined : (event) => event.preventDefault()}
+        data-keep-input="not-refusable"
+        className="flex flex-col gap-12"
+      >
+        <input type="hidden" name="choice" value="save" />
+        {gpcField}
+        <fieldset key={boxesKey} className="m-0 flex flex-col items-start gap-8 border-0 p-0">
+          <legend className="mb-4 text-text-13 font-medium">{categoriesLabel}</legend>
+          <Checkbox label={necessary} checked disabled readOnly />
+          {categories.map((c) => (
+            <Checkbox
+              key={c.name}
+              name={c.name}
+              label={c.label}
+              defaultChecked={allowed(c)}
+              disabled={signal}
+            />
+          ))}
+        </fieldset>
+        <div className="flex flex-wrap gap-8">
+          <Button
+            type={type}
+            variant="primary"
+            onClick={() => choose("save", tickedCategories(custom.current, names))}
+          >
+            {saveLabel}
+          </Button>
+        </div>
+      </form>
+      <form
+        {...(posts ? { action } : {})}
+        onSubmit={posts ? undefined : (event) => event.preventDefault()}
+        className="flex flex-wrap gap-8"
+      >
+        {gpcField}
+        <Button
+          type={type}
+          name="choice"
+          value="all"
+          disabled={signal}
+          onClick={() => choose("all")}
+        >
+          {acceptLabel}
+        </Button>
+        <Button type={type} name="choice" value="none" onClick={() => choose("none")}>
+          {rejectLabel}
+        </Button>
+      </form>
+      {cookies ? (
+        <table className="w-full border-collapse text-start text-text-13">
+          <caption className="mb-8 text-start text-text-13 font-medium">{cookies.caption}</caption>
+          <thead>
+            <tr className="border-b border-border-subtle">
+              <th scope="col" className={cellClass}>
+                {cookies.nameLabel}
+              </th>
+              <th scope="col" className={cellClass}>
+                {cookies.categoryLabel}
+              </th>
+              <th scope="col" className="py-4 text-start">
+                {cookies.purposeLabel}
+              </th>
+            </tr>
+          </thead>
+          <tbody>
+            {cookies.rows.map((row) => (
+              <tr key={row.name} className="border-b border-border-subtle">
+                <th scope="row" className={cx(cellClass, "font-mono font-regular")}>
+                  {row.name}
+                </th>
+                <td className={cellClass}>{row.category}</td>
+                <td className="py-4">{row.purpose}</td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      ) : null}
+      {policy ? (
+        <p className="m-0 text-text-13 text-text-secondary">
+          <ConsentLinkText link={policy} renderLink={renderLink} />
+        </p>
+      ) : null}
+    </div>
+  );
+}

package/src/ConsentBanner/README.md

@@ -0,0 +1,101 @@
+# ConsentBanner
+
+ConsentBanner asks a visitor once which cookies a site may set, and ConsentSettings is the page where the choice is changed. The marketing site renders both. Atlas renders ConsentSettings and, on every route, the script-free ConsentBannerStatic described below.
+
+- Import them from `@xos/ui/consent`, or from `@xos/ui` on the client. Both components are client modules; the adapter contract in `consent.ts` has no React and runs anywhere.
+- Accept and Reject are the same Button at the same size, side by side. Neither is primary, and neither has focus when the banner opens. No category behind Choose starts ticked.
+- Global Privacy Control is a refusal. Pass `gpc` when the request carries `Sec-GPC: 1` (`sendsGlobalPrivacyControl`); the components also read `navigator.globalPrivacyControl`. Under the signal the banner shows the confirmation in place of the choices, and the settings page says so and locks the optional categories and Accept.
+- Every string is a prop. The one exception is the confirmation, which falls back to the `mk.consent.gpc` message of the `ui` catalog when `gpcLabel` or `gpcNotice` is not passed.
+- A category `name` is a letter followed by letters, digits, underscores or hyphens, 64 characters at most (`CONSENT_CATEGORY_NAME`): `preferences`, `analytics_storage` and `Marketing` fit. The cookie adapter rejects a write with any other name, and reads nothing from a cookie that holds one.
+- The links are plain anchors. An app with a router passes `renderLink` to draw them with its own link component.
+
+## With no script
+
+`ConsentBannerStatic`, from `@xos/ui/consent/static`, is the same banner with no hooks, context or event handlers: a server component that renders it sends no JavaScript for it. Atlas shows it on every route, because the client ConsentBanner adds about 7 KB of script to each page that renders it.
+
+- It takes the same copy props, a required `action` (a URL or a server action) and an optional `renderLink`, which a server component can pass directly because nothing crosses to the client.
+- It reads nothing from the browser. The server decides whether to render it, and passes `gpc` and `gpcLabel` when the request carries `Sec-GPC: 1` to show the confirmation in place of the choices.
+- It keeps no record and does not see `navigator.globalPrivacyControl`. Use ConsentBanner with `record` where the banner keeps the decision through an adapter, as a site with no server does.
+
+## From a server component
+
+A server component can pass only props that serialize: the copy, `gpc`, `policy`, `settings`, `categories`, `cookies`, a string `status`, and `action` as a URL or a server action. That is how Atlas renders ConsentSettings. The rule covers the two client components; ConsentBannerStatic is rendered on the server, so it takes any prop.
+
+`record`, `onChoice`, `renderLink` and a function `status` are functions or hold functions. They must be passed from a file of the consumer's marked `"use client"`; a server component that passes them fails to render.
+
+## Where the decision is kept
+
+The components never touch storage. They work in one of three ways:
+
+1. `action`: plain forms post the choice to a URL or a function (a Next.js server action). The fields are `choice` (`all`, `none` or `save`) and each ticked category by name with the value `on`. The forms work before any script loads. Atlas uses this for ConsentSettings.
+2. `record`: an adapter and a policy version. The banner reads the adapter once, stays hidden when a decision exists, and writes each decision with its timestamp, the policy version and the Global Privacy Control flag.
+3. `onChoice` alone: the consumer hears the choice and does the rest.
+
+### Global Privacy Control that only the browser reports
+
+When `navigator.globalPrivacyControl` is on and `gpc` was not passed, the server has not seen the signal. What happens depends on the mode:
+
+- `record`: the refusal is written through the adapter once, flagged as a signal.
+- `action` as a function: it is called once per mount with `choice=none` and `gpc=1`. The receiver should do nothing when it already holds a refusal from the signal, as Atlas's `saveCookieChoice` does.
+- `action` as a URL: nothing is sent, because the banner shows no form under the signal and makes no request of its own. Record the refusal from `onChoice("none")`, or pass `gpc` from the request header.
+- In every `action` mode, each form still on screen (the two on ConsentSettings) carries a hidden `gpc` field with the value `1`, so a choice made there keeps the flag.
+
+`onChoice("none")` is called once in all of these.
+
+## The adapter
+
+```ts
+interface ConsentState {
+  readonly categories: Readonly<Record<string, boolean>>;
+  readonly gpc: boolean;
+}
+interface ConsentDecision extends ConsentState {
+  readonly decidedAt: string; // ISO 8601, UTC
+  readonly policyVersion: string;
+}
+interface ConsentAdapter {
+  read(): Promise<ConsentState | null>;
+  write(decision: ConsentDecision): Promise<void>;
+}
+```
+
+`cookieConsentAdapter()` is the reference implementation with no database: the whole decision lives in one first-party cookie, `xos-consent-decision`, for 12 months. It reads and writes `document.cookie` by default.
+
+- It never throws. Storage that cannot be reached and a category name outside the rule reject; the components then keep the choices on screen.
+- It takes any `store` with `get` and `set`, so a server can back it with its response cookies. Encoding is the store's job: `get` returns and `set` receives the decoded JSON value. A framework's cookie jar encodes and decodes by itself, as the default `document.cookie` store does, so a decision the server writes is read in the browser and the other way round.
+- On a server with no `store`, `read` resolves null and `write` rejects.
+
+A site with no database keeps the decision in the cookie from a small client file:
+
+```tsx
+"use client";
+
+import { ConsentBanner, cookieConsentAdapter, type ConsentBannerProps } from "@xos/ui/consent";
+import { useState } from "react";
+
+/** The copy comes in as props from the server page; the adapter is made here, in the browser. */
+export function SiteConsentBanner(props: Omit<ConsentBannerProps, "record" | "action">) {
+  const [record] = useState(() => ({
+    adapter: cookieConsentAdapter(),
+    policyVersion: "cookie-policy 1.0.0",
+  }));
+  return <ConsentBanner {...props} record={record} />;
+}
+```
+
+```tsx
+// A server page or layout: strings only.
+<SiteConsentBanner
+  title={copy.title}
+  body={copy.body}
+  policy={{ label: copy.policy, href: "/legal/cookie-policy" }}
+  acceptLabel={copy.accept}
+  rejectLabel={copy.reject}
+  chooseLabel={copy.choose}
+  necessary={copy.necessary}
+  categories={[{ name: "preferences", label: copy.preferences }]}
+  saveLabel={copy.save}
+/>
+```
+
+Atlas keeps its own adapter, over the consent log in the platform database, in `apps/atlas/lib/privacy/consent-adapter.ts`.