@owlmeans/web-consent 0.1.18-rc.43 → 0.1.18-rc.44

package/README.md

@@ -1,3 +1,227 @@
+# @owlmeans/web-consent
+
+The React components of OwlMeans cookie consent: the preferences dialog with its persistent re-open
+button, a menu row for hosts that reopen it from their own navigation, the generated cookie-policy
+page, and the `useConsent` hooks. It re-exports a named selection of `@owlmeans/consent` (the store,
+storage, Consent Mode and linker helpers, constants and types), so a web app usually needs one
+import. Any React surface uses it — a panel app, a generated app, an Astro island — because it
+depends on no shadcn primitive, no `@` alias and no OwlMeans context. An app built on
+`@owlmeans/web-panel` mounts `PanelCookieConsent` / `PanelCookiePolicy` from
+`@owlmeans/web-panel/consent` instead, which binds these components to OwlMeans i18n; code that only
+needs the model (no React) imports `@owlmeans/consent`; the Google tag snippet is `@owlmeans/web-gtm`.
+The `web-consent` skill covers the components, the `consent` skill the model behind them.
+
+## Installation
+
+```bash
+bun add @owlmeans/web-consent@^0.1.18-rc.44
+```
+
+Peer dependencies the app provides: `react`, `tailwindcss`, `tailwind-merge`, `clsx`, `lucide-react`.
+
+The components emit Tailwind classes that appear nowhere in the app's own sources, so the app's
+Tailwind entry must scan the package's `src`:
+
+```css
+@import "tailwindcss";
+
+@source "<relative path to node_modules>/@owlmeans/web-consent/src";
+```
+
+## Concepts
+
+- **Category** — a `ConsentCategory` (`essential` required, `analytics`, `marketing` by default). A
+  required category is disclosure, not a question: it renders locked and labelled *Required*.
+- **Record** — the visitor's decision, `ConsentRecord`, stored under `site_cookie_consent` in both
+  localStorage and a cookie.
+- **Store** — `consentStore`, a module singleton: consent belongs to the document, not to a component
+  tree. Both hooks subscribe to it through `useSyncExternalStore`.
+- **Reason** — why the dialog is open: `'initial'` (no record), `'reopen'`, or `'login'` (raised by
+  the sign-in precondition, which relabels the primary action *Accept & continue*).
+- **Parity** — the category set, `storageKey`, `cookieDays` and `cookieDomain` given to the dialog
+  must match what stamps the head snippet and what renders the policy page.
+- **Linker** — optional cross-domain consent (`linker: { domains }`): a decision made on one listed
+  first-party domain is carried to another by a decorated link.
+
+## Usage
+
+### 1. Mount it once
+
+At the application root or layout. It opens itself when no decision is stored and renders only the
+re-open button once one is. A first-time visitor is asked with a tall bar across the bottom of a
+transparent overlay — "Cookie preferences", "Accept only mandatory", "Accept all" — and every later
+opening is the preferences window; `mode="window"` asks with the window straight away.
+
+```tsx
+import { CookieConsent } from '@owlmeans/web-consent'
+
+export const Layout = ({ children, locale }: { children: ReactNode, locale: string }) => <>
+  {children}
+  <CookieConsent
+    locale={locale}
+    policyHref="/legal/cookies"
+    links={[{ href: '/legal/privacy', labelKey: 'privacy', defaultLabel: 'Privacy Policy' }]}
+  />
+</>
+```
+
+Pass `geo={{ cloudflare: true }}` on a Cloudflare-proxied host to ask only visitors located in a
+consent country (a spinner shows while they are located; anyone else is decided for automatically —
+see `@owlmeans/consent`). Pass `linker={{ domains: ['owlmeans.com', 'owlmeans.pl'] }}` to share the
+decision across domains; the surface then discloses the domain list. `noReopenButton` hides the floating button for an app
+that offers a footer link calling `consentStore.open('reopen')`.
+
+### 2. Read the decision
+
+```tsx
+import { consentStore, useConsentCategory, CONSENT_ANALYTICS } from '@owlmeans/web-consent'
+
+export const AnalyticsChart = () => {
+  const allowed = useConsentCategory(CONSENT_ANALYTICS)   // subscribes, does not init
+
+  return allowed ? <Chart /> : <p>Enable analytics cookies to see this chart.</p>
+}
+
+// outside React — a click handler, a service
+if (consentStore.granted(CONSENT_ANALYTICS)) {
+  startTracking()
+}
+```
+
+`useConsent(opts?)` returns the whole model (`record`, `open`, `reason`, `granted`, `save`,
+`acceptAll`, `openDialog`, `close`) but also runs `consentStore.init(opts)` on mount — use it only
+where the dialog's own options are in hand.
+
+### 3. Reopen from a host menu
+
+```tsx
+import { ConsentMenuWidget } from '@owlmeans/web-consent'
+
+<nav aria-label="Settings">
+  <ConsentMenuWidget locale={locale} className="px-3 py-2" />
+</nav>
+```
+
+The row calls `consentStore.open('reopen')` (or your `onSelect`). It does not hide the floating
+button by itself; pass `noReopenButton` to `CookieConsent` when the menu fully replaces it.
+
+### 4. Render the cookie policy
+
+```tsx
+import { CookiePolicy } from '@owlmeans/web-consent'
+import { googleTagHelper } from '@owlmeans/web-gtm'
+
+<CookiePolicy
+  locale={locale}
+  operator="Example Sp. z o.o."
+  privacyHref="/legal/privacy"
+  termsHref="/legal/terms"
+  services={googleTag !== '' ? googleTagHelper.googleTagServices(googleTag) : undefined}
+/>
+```
+
+The page lists the categories in force, the services each one gates (unmatched services go to a
+trailing *Other services* item), the storage key, the retention and, with `linker`, the domains. It
+ends with a *Manage preferences* button that reopens the dialog.
+
+### 5. Build your own dialog body
+
+`ConsentToggle` is one accessible category row; its wording is the caller's, already resolved.
+
+```tsx
+import { ConsentToggle } from '@owlmeans/web-consent'
+
+<ConsentToggle
+  id="cc-analytics" label="Analytics" description="Helps us understand usage."
+  checked={draft.analytics === true} requiredLabel="Required"
+  onChange={value => setDraft({ ...draft, analytics: value })}
+/>
+```
+
+## API
+
+### Components and hooks
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `CookieConsent` | component (`CookieConsentProps`) | The consent UI — the bar, the preferences window, the locating spinner — and the floating re-open button (`[data-consent-reopen]`) |
+| `CONSENT_DEFAULT_MODE`, `ConsentDisplayMode` | const, type | `'bar'`; `'bar' \| 'window'` |
+| `ConsentMenuWidget` | component (`ConsentMenuWidgetProps`) | One menu row reopening the dialog; never initialises the store |
+| `CookiePolicy` | component (`CookiePolicyProps`) | The generated cookie-policy page |
+| `ConsentToggle` | component (`ConsentToggleProps`) | One category row with a switch; locked when `required` |
+| `useConsent(opts?)` | hook → `UseConsentModel` | Full consent state and actions; **initialises the store on mount** |
+| `useConsentCategory(key)` | hook → `boolean` | Whether one category is granted (false while no record exists); no init |
+
+### Props
+
+| Type | Fields |
+|---|---|
+| `CookieConsentProps` | `locale?`, `categories?`, `translate?`, `mode?`, `geo?`, `policyHref?`, `links?: ConsentLink[]`, `storageKey?`, `cookieDays?`, `cookieDomain?`, `silent?`, `noReopenButton?`, `className?` (the window's card), `barClassName?`, `linker?` |
+| `CookiePolicyProps` | `locale?`, `translate?`, `categories?`, `operator?`, `privacyHref?`, `termsHref?`, `storageKey?`, `cookieDays?`, `services?: ConsentService[]`, `className?`, `linker?`, `geo?` (adds the regional rule) |
+| `ConsentMenuWidgetProps` | `locale?`, `translate?`, `label?`, `className?`, `onSelect?` |
+| `ConsentToggleProps` | `id`, `label`, `description`, `checked`, `required?`, `requiredLabel`, `onChange(value)` |
+| `ConsentLink` | `{ href, labelKey, defaultLabel }` |
+| `UseConsentModel` | `{ record, open, reason, locating, granted(key), save(record), acceptAll(), openDialog(reason?), close() }` |
+
+`translate` is `(key, defaultValue) => string`; without it the packaged bundle for `locale` is used
+(`CONSENT_LOCALES`: en, pl, ru, be, uk, es, de, fr; anything else falls back to English).
+
+### Re-exported from `@owlmeans/consent`
+
+| Group | Symbols |
+|---|---|
+| Store | `consentStore` |
+| Helpers | `consentStorageHelper`, `consentModeHelper`, `consentI18nHelper`, `consentPluginHelper`, `consentLinkHelper`, `consentGeoHelper` |
+| Geo gate | `CONSENT_REQUIRED_COUNTRIES`, `CONSENT_COUNTRIES_GDPR`, `CONSENT_COUNTRIES_ALIGNED`, `CONSENT_COUNTRIES_OPT_IN`, `CONSENT_GEO_UNKNOWN`, `CONSENT_TRACE_PATH`, `CONSENT_GEO_TIMEOUT`, `CONSENT_AUTO_MAX_AGE`, `CONSENT_IDLE_STATE`, `CONSENT_STATE_ATTRIBUTE` and the types `ConsentGeoOptions`, `ConsentGeoPlugin`, `ConsentGeoLocation`, `ConsentCloudflareOptions`, `ConsentLocating`, `ConsentGeoHelper`, `ConsentGeoVerdict`, `ConsentAutoState` |
+| Defaults | `DEFAULT_CONSENT_CATEGORIES`, `DEFAULT_CONSENT_MESSAGES` |
+| Constants | `CONSENT_KEY`, `CONSENT_COOKIE_DAYS`, `CONSENT_SCHEMA_VERSION`, `CONSENT_LOCALES`, `CONSENT_ESSENTIAL`, `CONSENT_ANALYTICS`, `CONSENT_MARKETING`, `CONSENT_LANGUAGE_KEY`, `CONSENT_EVENT`, `CONSENT_LINK_PARAM`, `CONSENT_LINK_MAX_AGE`, `CONSENT_LINK_SKEW` |
+| Deprecated wrappers | `openConsent`, `isConsented`, `readConsent`, `writeConsent`, `clearConsent`, `consentBootstrapScript`, `defaultConsentTranslate`, `decorateConsentUrl`, `encodeConsentLink`, `consentLinkerScript` — use the helper members instead |
+| Types | `ConsentCategory`, `ConsentOptions`, `ConsentReason`, `ConsentRecord`, `ConsentService`, `ConsentSignal`, `ConsentState`, `ConsentStore`, `ConsentLocale`, `ConsentLinkerOptions`, `ConsentLinkerLanguage`, `ConsentPlugin`, `ConsentLinkPayload`, and the five helper interfaces |
+
+`makeConsentStore`, `CONSENT_SETUP_FLAG`, `CONSENT_SIGNAL_DEFAULTS` and `ConsentListener` are not
+re-exported; import them from `@owlmeans/consent`.
+
+## Test and styling hooks
+
+| Selector | Element |
+|---|---|
+| `[data-consent-dialog]` | whichever surface asks — the bar or the window (`data-consent-mode="bar\|window"`) |
+| `[data-consent-bar]`, `[data-consent-overlay]` | the bar, and the transparent overlay it sits on |
+| `[data-consent-preferences]`, `[data-consent-mandatory]`, `[data-consent-accept-all]` | the bar's three answers |
+| `[data-consent-save]`, `[data-consent-accept-all]` | the window's two actions |
+| `[data-consent-locating="first"]`, `[data-consent-spinner]` | the locating overlay and its spinner |
+| `[data-consent-links]`, `[data-consent-auto]` | the legal links row; the "applied automatically" line |
+| `html[data-consent]` | the phase: `locating`, `open`, `decided`, `idle` |
+| `[data-consent-reopen]` | the floating re-open button |
+| `[data-consent-reason]`, `[data-consent-domains]` | login-reason line, disclosed domains |
+| `[data-consent-menu-widget]` | the menu row |
+| `[data-cookie-policy]`, `[data-cookie-policy-category="<key>"]`, `[data-cookie-policy-services]`, `[data-cookie-policy-service]`, `[data-cookie-policy-other]`, `[data-cookie-policy-domains]`, `[data-cookie-policy-regional]`, `[data-cookie-policy-manage]` | the policy page |
+
+## Common pitfalls
+
+- Pointing `@source` at `build` instead of `src`: under a linked workspace it scans zero files and
+  the dialog renders half-styled with no error. Verify with `grep -c 'max-w-lg' dist/assets/*.css`.
+- A bare `useConsent()` in a component that only reads opens the dialog for a first-time visitor and
+  may fix the Consent Mode defaults from the default categories. Read with `useConsentCategory` or
+  `consentStore.granted`.
+- `useConsent` reads `opts` only on its mounting pass; changing them later has no effect.
+- Passing `translate` disables the packaged bundle entirely — a resolver must fall back to
+  `consentI18nHelper.defaultConsentTranslate(locale)` or every unmapped key renders in English.
+- Different `categories`, `storageKey`, `cookieDays` or `cookieDomain` between the dialog, the head
+  snippet and the policy page make them disagree about what was asked.
+- Do not add decorative classes (gradients, shadows, blur) to the dialog; the package tests reject
+  them, and the look comes from the host's theme tokens.
+- `silent` suppresses runtime `dataLayer` and global writes only; the stamped bootstrap snippet still
+  pushes Consent Mode commands.
+
+## Related packages
+
+- [`@owlmeans/consent`](../consent) — the model: categories, storage, store, Consent Mode, linker
+- [`@owlmeans/web-gtm`](../web-gtm) — the Google tag head snippet and `googleTagServices` for the policy page
+- [`@owlmeans/web-panel`](../web-panel) — `./consent` subpath binding these components to OwlMeans i18n
+- [`@owlmeans/web-log`](../web-log) — consent-gated analytics plugins for `@owlmeans/log`
+- [`@owlmeans/astro`](../astro) — stamping the consent scripts from a static site's layout
+
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
 
@@ -6,7 +230,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.51
+npx @owlmeans/agent-skills@^0.1.18-rc.52
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/web-consent",
-  "version": "0.1.18-rc.43",
-  "generatedAt": "2026-10-06T11:45:57.669Z",
+  "version": "0.1.18-rc.44",
+  "generatedAt": "2026-10-08T21:27:54.304Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/web-consent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: web-consent
-description: How to use @owlmeans/web-consent — the React cookie-consent dialog, its re-open button, the generated cookie-policy page and the useConsent hooks, plus the Tailwind @source line every consumer must add. Auto-invoked when mounting a consent dialog, rendering a cookie policy, gating a feature on a consent category, or importing CookieConsent, CookiePolicy or useConsent.
+description: How to use @owlmeans/web-consent — the React cookie-consent UI (the bottom bar by default, the preferences window, the locating spinner), its re-open button, the geo gate's props, the generated cookie-policy page and the useConsent hooks, plus the Tailwind @source line every consumer must add. Auto-invoked when mounting a consent bar or dialog, rendering a cookie policy, gating a feature on a consent category, or importing CookieConsent, CookiePolicy or useConsent.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/web-consent
 
 **Layer:** Web (React)
-**Install:** `"@owlmeans/web-consent": "^0.1.18-rc.43"` in `dependencies`
+**Install:** `"@owlmeans/web-consent": "^0.1.18-rc.44"` in `dependencies`
 
 The browser components of the consent set. The model — categories, storage, migration, the store,
 Consent Mode signalling — is `@owlmeans/consent`, and this package re-exports a **named selection**
@@ -34,20 +34,34 @@ components — see below.
 
 | Export | Description |
 |--------|-------------|
-| `CookieConsent` | The preferences dialog **and** the persistent re-open button |
+| `CookieConsent` | The consent UI — the bar, the preferences window, the locating spinner — **and** the persistent re-open button |
+| `ConsentDisplayMode` / `CONSENT_DEFAULT_MODE` | `'bar'` (the default) or `'window'` — how a first-time visitor is asked |
 | `ConsentMenuWidget` | A plain row a HOST'S OWN menu renders to reopen the dialog, in place of (or beside) `CookieConsent`'s own floating button — see below |
 | `CookiePolicy` | The cookie-policy page, generated from the configuration in force |
 | `ConsentToggle` | One category row — locked and labelled when the category is required |
 | `useConsent(opts?)` | This document's consent state and the actions over it (`UseConsentModel`) — **it also initialises the store on mount**, see below |
 | `useConsentCategory(key)` | Whether one category is granted, for a component gating a single thing |
 | `CookieConsentProps` / `CookiePolicyProps` / `ConsentLink` | The component props |
-| Re-exports from `@owlmeans/consent` | The complete list: `consentStore`; `consentStorageHelper` (`readConsent`, `writeConsent`, `clearConsent`, `migrateConsent`); `consentModeHelper` (`applyConsent`, `pushConsentDefaults`, `consentBootstrapScript`, `consentDefaults`, `consentUpdate`, `gtagConsent`, `trackingGranted`, `consentGateScript`); `consentI18nHelper` (`defaultConsentTranslate`, `interpolate`, `normalizeLocale`); `DEFAULT_CONSENT_CATEGORIES`, `DEFAULT_CONSENT_MESSAGES`, `CONSENT_KEY`, `CONSENT_COOKIE_DAYS`, `CONSENT_SCHEMA_VERSION`, `CONSENT_LOCALES`, `CONSENT_ESSENTIAL` / `CONSENT_ANALYTICS` / `CONSENT_MARKETING`, the plugin seam (`consentPluginHelper`: `registerConsentPlugin`, `consentPlugins`, `decorateConsentUrl`, `consentDomains`, `adoptConsent`, `startConsentPlugins`, `adoptConsentLanguage`), the linker (`consentLinkHelper`: `consentLinker`, `encodeConsentLink`, `decodeConsentLink`, `stripConsentLinkParam`, `consentLinkerScript`, `writeConsentLanguage`; `CONSENT_LANGUAGE_KEY`, `CONSENT_EVENT`, `CONSENT_LINK_PARAM`, `CONSENT_LINK_MAX_AGE`, `CONSENT_LINK_SKEW`), and the types `ConsentCategory`, `ConsentOptions`, `ConsentReason`, `ConsentRecord`, `ConsentService`, `ConsentSignal`, `ConsentState`, `ConsentStore`, `ConsentLocale`, `ConsentLinkerOptions`, `ConsentLinkerLanguage`, `ConsentPlugin`, `ConsentLinkPayload` and the five helper interfaces |
+| Re-exports from `@owlmeans/consent` | The complete list: `consentStore`; `consentStorageHelper` (`readConsent`, `writeConsent`, `clearConsent`, `migrateConsent`); `consentModeHelper` (`applyConsent`, `pushConsentDefaults`, `consentBootstrapScript`, `consentDefaults`, `consentUpdate`, `gtagConsent`, `trackingGranted`, `consentGateScript`); `consentI18nHelper` (`defaultConsentTranslate`, `interpolate`, `normalizeLocale`); `DEFAULT_CONSENT_CATEGORIES`, `DEFAULT_CONSENT_MESSAGES`, `CONSENT_KEY`, `CONSENT_COOKIE_DAYS`, `CONSENT_SCHEMA_VERSION`, `CONSENT_LOCALES`, `CONSENT_ESSENTIAL` / `CONSENT_ANALYTICS` / `CONSENT_MARKETING`, the plugin seam (`consentPluginHelper`: `registerConsentPlugin`, `unregisterConsentPlugin`, `consentPlugins`, `decorateConsentUrl`, `consentDomains`, `adoptConsent`, `startConsentPlugins`, `adoptConsentLanguage`, `locateConsent`), the geo gate (`consentGeoHelper`; `CONSENT_REQUIRED_COUNTRIES`, `CONSENT_COUNTRIES_GDPR` / `_ALIGNED` / `_OPT_IN`, `CONSENT_GEO_UNKNOWN`, `CONSENT_TRACE_PATH`, `CONSENT_GEO_TIMEOUT`, `CONSENT_AUTO_MAX_AGE`, `CONSENT_IDLE_STATE`, `CONSENT_STATE_ATTRIBUTE`; the types `ConsentGeoOptions`, `ConsentGeoPlugin`, `ConsentGeoLocation`, `ConsentCloudflareOptions`, `ConsentLocating`, `ConsentGeoHelper`, `ConsentGeoVerdict`, `ConsentAutoState`), the linker (`consentLinkHelper`: `consentLinker`, `encodeConsentLink`, `decodeConsentLink`, `stripConsentLinkParam`, `consentLinkerScript`, `writeConsentLanguage`; `CONSENT_LANGUAGE_KEY`, `CONSENT_EVENT`, `CONSENT_LINK_PARAM`, `CONSENT_LINK_MAX_AGE`, `CONSENT_LINK_SKEW`), and the types `ConsentCategory`, `ConsentOptions`, `ConsentReason`, `ConsentRecord`, `ConsentService`, `ConsentSignal`, `ConsentState`, `ConsentStore`, `ConsentLocale`, `ConsentLinkerOptions`, `ConsentLinkerLanguage`, `ConsentPlugin`, `ConsentLinkPayload` and the five helper interfaces |
 
 ## Mounting the dialog
 
 `CookieConsent` is mounted **once**, at the application root or in the layout. It opens itself when
 no decision is stored, renders nothing but the re-open button once one is, and needs no state from
-the caller:
+the caller. One surface at a time:
+
+- **while a first-time visitor is located** (`geo`): a transparent overlay that blocks the page,
+  and a spinner (`[data-consent-locating="first"]`, `[data-consent-spinner]` after
+  `CONSENT_LOCATING_DELAY`, 300 ms) — never the bar;
+- **the first ask** (`reason: 'initial'`) in `bar` mode, the default: the bar;
+- **every other opening** — the bar's own "Cookie preferences" (`'preferences'`), a footer link or
+  the corner button (`'reopen'`), the sign-in gate (`'login'`) — and the first ask in `window`
+  mode: the preferences window.
+
+`[data-consent-dialog]` (with `role="dialog"`, `aria-modal`) and `[data-consent-accept-all]` sit on
+whichever surface is up, so a test or a host keys on them without knowing the mode;
+`data-consent-mode="bar|window"` and `[data-consent-bar]` tell them apart. "Cookie preferences"
+REPLACES the bar with the window — exactly one of each exists at a time.
 
 ```tsx
 import { CookieConsent } from '@owlmeans/web-consent'
@@ -68,6 +82,11 @@ import { CookieConsent } from '@owlmeans/web-consent'
   work — the component must not know how its host does routing.
 - `noReopenButton` hides the floating button for an app that offers a footer link instead; that link
   calls `consentStore.open('reopen')`.
+- **`mode`** (`'bar'` | `'window'`, default `CONSENT_DEFAULT_MODE`) picks the first ask's surface.
+- **`geo`** (`ConsentGeoOptions`, plain data — an Astro island can pass it) turns on the geo gate:
+  `geo={{ cloudflare: true }}` on a Cloudflare-proxied host. It is passed through to
+  `consentStore.init` like `linker`; the `consent` skill's "Where consent is asked" is the model. A
+  locator plugin is code and is registered, not passed. Pass the same `geo` to `CookiePolicy`.
 - **The re-open button is a bare icon in the very corner (`bottom-1 left-1`), not a card.** No
   filled background, no border, no shadow, no hover-scale — `bg-transparent`, dimmed
   (`opacity-70`) at rest and picked out on hover/focus — because it sits on every page of a site
@@ -87,15 +106,45 @@ import { CookieConsent } from '@owlmeans/web-consent'
   analytics and marketing toggles only; the language is strictly necessary storage that no toggle
   governs (the `consent` skill). The built-in bundle (8 languages) describes it in the required row.
 
+## The bar
+
+A tall bar across the bottom of a **transparent** overlay (`[data-consent-overlay]`,
+`fixed inset-0 bg-transparent`): the page stays in sight and scrolls, but nothing on it can be
+pressed until the visitor answers. The bar (`fixed inset-x-0 bottom-0 max-h-[85vh] border-t
+bg-background`) holds, left to right on a wide screen and stacked on a phone:
+
+- the cookie icon and `barTitle`;
+- `barDescription` — what the essential cookies do, the optional categories in force as a list
+  after a colon (`{{categories}}`, so no language has to decline a label), that they stay off until
+  allowed, and that the choice can be changed or withdrawn at any time; `barDescriptionEssential`
+  when nothing is optional;
+- the cross-domain line (`[data-consent-domains]`) when `linker` names more than this host;
+- the links row (`[data-consent-links]`: `policyHref` then `links`, 44px targets, new tab);
+- three answers: `[data-consent-preferences]` "Cookie preferences" (outlined), then
+  `[data-consent-mandatory]` "Accept only mandatory" and `[data-consent-accept-all]` "Accept All" —
+  the two answers carry the SAME accent class: refusing is exactly as prominent as accepting, and
+  one click away. With no optional category there is nothing to refuse, so "mandatory" is absent.
+
+`barClassName` styles the bar; `className` still styles the window's card.
+
+**Focus.** On open, focus moves to the surface itself (`tabIndex={-1}`) — never to an answer, which
+would be a nudge; Tab and Shift+Tab cycle inside it; on close focus returns where it was. Nothing
+pulls focus back on `focusin` (a script focusing a field is not a keyboard user escaping). The
+spinner overlay takes no focus.
+
 ## The look — flat, from the host's tokens
 
-The dialog is the first thing every new visitor of a generated app sees, so it follows the flat
-rule those apps are held to: **no gradient, shadow, glow, glass or `backdrop-filter`** anywhere in
-it. Everything is a theme token, so light and dark follow the host:
+The bar and the window are the first thing every new visitor of a generated app sees, so they
+follow the flat rule those apps are held to: **no gradient, shadow, glow, glass or
+`backdrop-filter`** anywhere. Everything is a theme token, so light and dark follow the host:
 
 | Part | Classes |
 |---|---|
-| Overlay | `bg-black/70`, flat — no blur |
+| Bar overlay, locating overlay | `bg-transparent` — the page stays in sight |
+| Bar | `border-t border-border bg-background text-foreground`, no shadow |
+| Bar answers | "Accept only mandatory" and "Accept All" both the accent pill; "Cookie preferences" outlined |
+| Spinner | `text-muted-foreground motion-safe:animate-spin` |
+| Window overlay | `bg-black/70`, flat — no blur |
 | Card | `rounded-3xl border border-border bg-background text-foreground`, no shadow or ring |
 | Icon | `rounded-full bg-muted text-primary` |
 | Category row | `rounded-2xl border border-border`; *Required* is plain uppercase muted text, never a badge |
@@ -115,19 +164,24 @@ carries `aria-labelledby="<id>-label"` (the category label) and `aria-describedb
 `<id>-required` and `<id>-desc`. Drop those and axe reports three unnamed checkboxes (`label`,
 critical). A required category stays `disabled` and keeps its name.
 
-`tests/a11y.spec.ts` runs axe-core (a dev dependency) against the open dialog in both schemes, the
-re-open button, and the policy page with services, and fails on any serious or critical
-violation. It loads the harness with `?styled=1` (plus `&theme=dark`), which compiles the package
+`tests/a11y.spec.ts` runs axe-core (a dev dependency) against the open bar and the open window in
+both schemes, the locating overlay, the re-open button, and the policy page with services and the
+regional rule, and fails on any serious or critical violation. It loads the harness with `?styled=1` (plus `&theme=dark`), which compiles the package
 sources with a generated app's neutral tokens — contrast cannot be judged on the unstyled harness
-the other specs need.
+the other specs need. The harness also takes `?mode=bar|window`, `?categories=essential`,
+`?geo=<CC>|fail|html|hang` (its server answers `/cdn-cgi/trace` from the page's own query, so every
+case is still chosen by URL; `&geoDelay=<ms>`, `&geoTimeout=<ms>`), `?geoPlugin=<CC>|fail` and
+`?gpc=1` — `tests/bar.spec.ts` and `tests/geo.spec.ts` drive them.
 - `silent` skips every `dataLayer` and global write. It is for tests and for an app that runs no
   tags at all.
-- The draft is **re-seeded from storage every time the dialog opens**, not from the last render — a
-  visitor reopening preferences must see the answer they gave.
+- The window's switches are **seeded from storage every time it opens** — it is mounted only while
+  open — never from the last render: a visitor reopening preferences must see the answer they gave.
+  An automatic decision past its age seeds nothing.
 
-**When the dialog was raised by something waiting on it** — `reason === 'login'`, which the sign-in
+**When the window was raised by something waiting on it** — `reason === 'login'`, which the sign-in
 precondition in `@owlmeans/client-iam` raises — it says so and relabels the primary action *Accept
-& continue*. That is what makes the interruption legible instead of looking like the page asking
+& continue*. The sign-in gate always gets the window, never the bar. An automatic decision is said
+to be one when the window opens over it (`[data-consent-auto]`, `autoReason`). That is what makes the interruption legible instead of looking like the page asking
 twice. Word that path as an acknowledgement, never as "you must consent to essential cookies": a
 required category is disclosure, not a question.
 
@@ -162,14 +216,15 @@ if (consentStore.granted('analytics')) { /* outside React — a click handler, a
 Both hooks subscribe through `useSyncExternalStore` over the module-singleton store, because consent
 is a property of the DOCUMENT rather than of a component tree: the dialog, the re-open button, the
 policy page and whatever an app gates on it all read one value, and local copies would disagree the
-moment one of them saved. During server rendering the snapshot is "no record, closed", so the dialog
-never flashes into static HTML before hydration corrects it.
+moment one of them saved. During server rendering the snapshot is `CONSENT_IDLE_STATE` — one frozen
+object, "no record, closed, not locating" — so no surface flashes into static HTML before hydration
+corrects it (`tests/ssr.spec.tsx`). `UseConsentModel.locating` exposes the lookup.
 
 **`useConsent` is not a pure reader — it runs `consentStore.init(opts)` on mount.** Two consequences
 a component that only wanted to read has to plan for:
 
-- **It opens the dialog.** `init` reads storage, and with no stored record it publishes
-  `open: true, reason: 'initial'`. So a `useConsent()` in a card that merely wanted `granted('analytics')`
+- **It opens the consent UI.** `init` reads storage, and with no stored record it publishes
+  `open: true, reason: 'initial'` — or, with `geo`, starts locating. So a `useConsent()` in a card that merely wanted `granted('analytics')`
   gates the page for a first-time visitor. Read a single category with `useConsentCategory(key)` —
   that hook subscribes and does **not** init — or `consentStore.granted(key)` outside React.
 - **The first `useConsent` to mount fixes the Consent Mode defaults.** `init` calls
@@ -203,6 +258,9 @@ Everything OwlMeans cannot assert on the operator's behalf — who the controlle
 basis, how to exercise rights — is deferred to those two links. It also renders a *Manage
 preferences* control, so the policy page is a way back into the decision.
 
+**`geo`**, the same object the dialog was given, adds the regional rule
+(`[data-cookie-policy-regional]`, `policyRegional`) after the category list.
+
 **`services`** (`ConsentService[]`, see the `consent` skill) discloses WHO receives data: each
 service is listed inside the item of the category whose `key` it names — name, provider, purpose,
 cookie names in `<code>`, and a link to the provider's privacy policy (new tab). A service whose

package/build/consent/bar.d.ts

@@ -0,0 +1,22 @@
+import { type FC } from 'react';
+import type { ConsentBarProps } from './types.local.js';
+/**
+ * The first question a visitor is asked, as a tall bar across the bottom of the page.
+ *
+ * It sits on a TRANSPARENT overlay: the page stays in sight and scrolls, but nothing on it can be
+ * pressed until the visitor answers. The text says what the essential cookies do, names the
+ * optional categories in force (as a list after a colon, so no language has to decline a label),
+ * that they stay off until allowed, and that the choice can be changed or withdrawn — then the
+ * policy and the host's other links.
+ *
+ * Three answers: "Cookie preferences" replaces the bar with the preferences window, "Accept only
+ * mandatory" refuses every optional category, "Accept all" grants them. The two answers carry the
+ * same accent — refusing is exactly as prominent as accepting, and exactly one click away. With no
+ * optional category at all there is nothing to refuse, so "Accept only mandatory" is not offered.
+ *
+ * `[data-consent-dialog]` and `[data-consent-accept-all]` are here as on the window — one surface is
+ * open at a time, so a test or a host keys on them without knowing the mode; `[data-consent-bar]`
+ * tells the two apart.
+ */
+export declare const ConsentBar: FC<ConsentBarProps>;
+//# sourceMappingURL=bar.d.ts.map

package/build/consent/bar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar.d.ts","sourceRoot":"","sources":["../../src/consent/bar.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,EAAE,EAAE,MAAM,OAAO,CAAA;AAOvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEvD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,EAAE,EAAE,CAAC,eAAe,CAkE1C,CAAA"}

package/build/consent/bar.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from 'react';
+import { Cookie } from 'lucide-react';
+import { consentI18nHelper } from '@owlmeans/consent';
+import { webConsentUtils } from '../lib/utils.js';
+import { ACCENT, BAR_PILL, OUTLINED } from './consts.local.js';
+import { useConsentFocus } from './focus.js';
+import { ConsentLinks } from './links.js';
+/**
+ * The first question a visitor is asked, as a tall bar across the bottom of the page.
+ *
+ * It sits on a TRANSPARENT overlay: the page stays in sight and scrolls, but nothing on it can be
+ * pressed until the visitor answers. The text says what the essential cookies do, names the
+ * optional categories in force (as a list after a colon, so no language has to decline a label),
+ * that they stay off until allowed, and that the choice can be changed or withdrawn — then the
+ * policy and the host's other links.
+ *
+ * Three answers: "Cookie preferences" replaces the bar with the preferences window, "Accept only
+ * mandatory" refuses every optional category, "Accept all" grants them. The two answers carry the
+ * same accent — refusing is exactly as prominent as accepting, and exactly one click away. With no
+ * optional category at all there is nothing to refuse, so "Accept only mandatory" is not offered.
+ *
+ * `[data-consent-dialog]` and `[data-consent-accept-all]` are here as on the window — one surface is
+ * open at a time, so a test or a host keys on them without knowing the mode; `[data-consent-bar]`
+ * tells the two apart.
+ */
+export const ConsentBar = props => {
+    const { t, categories, domains } = props;
+    const surface = useRef(null);
+    useConsentFocus(surface, true);
+    const optional = categories.filter(category => category.required !== true);
+    const description = optional.length > 0
+        ? consentI18nHelper.interpolate(t('barDescription', 'We use essential cookies to make this site work — for signing in, security and remembering your choices. With your consent we would also use these optional cookies: {{categories}}. They stay off until you allow them, and you can change or withdraw your choice at any time in the cookie preferences.'), { categories: optional.map(category => t(category.labelKey, category.key)).join(', ') })
+        : t('barDescriptionEssential', 'This site uses only essential cookies — for signing in, security and remembering your choices. They need no consent and cannot be switched off.');
+    return _jsx("div", { className: "fixed inset-0 z-[999998] bg-transparent", "data-consent-overlay": true, children: _jsx("div", { ref: surface, tabIndex: -1, className: webConsentUtils.cn('fixed inset-x-0 bottom-0 z-[999999] max-h-[85vh] overflow-y-auto border-t border-border bg-background text-foreground outline-none', props.barClassName), role: "dialog", "aria-modal": "true", "aria-labelledby": "cc-bar-title", "aria-describedby": domains.length > 1 ? 'cc-bar-desc cc-bar-domains' : 'cc-bar-desc', "data-consent-dialog": true, "data-consent-bar": true, "data-consent-mode": "bar", children: _jsxs("div", { className: "mx-auto flex max-w-6xl flex-col gap-6 px-4 py-6 sm:px-8 sm:py-8 lg:flex-row lg:items-end lg:gap-10", children: [_jsxs("div", { className: "min-w-0 flex-1", children: [_jsxs("div", { className: "mb-3 flex items-center gap-3", children: [_jsx("div", { className: "flex h-10 w-10 flex-shrink-0 items-center justify-center rounded-full bg-muted text-primary", children: _jsx(Cookie, { className: "h-5 w-5", "aria-hidden": "true" }) }), _jsx("h2", { id: "cc-bar-title", className: "text-balance text-lg font-extrabold tracking-tight text-foreground sm:text-xl", children: t('barTitle', 'Cookies on this site') })] }), _jsx("p", { id: "cc-bar-desc", className: "text-pretty text-sm leading-relaxed text-muted-foreground", children: description }), domains.length > 1 && _jsx("p", { id: "cc-bar-domains", "data-consent-domains": true, className: "mt-2 text-pretty text-xs text-muted-foreground", children: consentI18nHelper.interpolate(t('domains', 'This choice applies to {{domains}}.'), { domains: domains.join(', ') }) }), _jsx(ConsentLinks, { t: t, policyHref: props.policyHref, links: props.links, className: "mt-1" })] }), _jsxs("div", { className: "flex w-full flex-col gap-3 sm:flex-row sm:flex-wrap sm:justify-end lg:w-auto lg:max-w-xl lg:flex-shrink-0", children: [_jsx("button", { type: "button", onClick: props.onPreferences, "data-consent-preferences": true, className: webConsentUtils.cn(BAR_PILL, OUTLINED), children: t('openPreferences', 'Cookie preferences') }), optional.length > 0 && _jsx("button", { type: "button", onClick: props.onMandatory, "data-consent-mandatory": true, className: webConsentUtils.cn(BAR_PILL, ACCENT), children: t('acceptMandatory', 'Accept only mandatory') }), _jsx("button", { type: "button", onClick: props.onAcceptAll, "data-consent-accept-all": true, className: webConsentUtils.cn(BAR_PILL, ACCENT), children: t('acceptAll', 'Accept All') })] })] }) }) });
+};
+//# sourceMappingURL=bar.js.map

package/build/consent/bar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bar.js","sourceRoot":"","sources":["../../src/consent/bar.tsx"],"names":[],"mappings":"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"}

package/build/consent/component.d.ts

@@ -1,4 +1,15 @@
 import { type FC } from 'react';
 import type { CookieConsentProps } from '../types.js';
+/**
+ * The cookie-consent UI of a document: one of three surfaces at a time, and the corner button.
+ *
+ * - While a first-time visitor is being located (`geo`), a transparent overlay with a spinner.
+ * - The first ask (`reason: 'initial'`) in `bar` mode — the default — the bar.
+ * - Every other opening, and the first ask in `window` mode, the preferences window.
+ *
+ * Mounted once, at the application root, outside the router: a surface mounted in a route is torn
+ * down by the first navigation. The bar and the window share one save path, so whichever answers,
+ * the record carries every required category on and exactly the optional ones chosen.
+ */
 export declare const CookieConsent: FC<CookieConsentProps>;
 //# sourceMappingURL=component.d.ts.map

package/build/consent/component.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/consent/component.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAoC,KAAK,EAAE,EAAE,MAAM,OAAO,CAAA;AAMjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAerD,eAAO,MAAM,aAAa,EAAE,EAAE,CAAC,kBAAkB,CA0IhD,CAAA"}
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../../src/consent/component.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAe,KAAK,EAAE,EAAE,MAAM,OAAO,CAAA;AAM5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAMrD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,EAAE,EAAE,CAAC,kBAAkB,CAsEhD,CAAA"}

package/build/consent/component.js

@@ -1,41 +1,40 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useState } from 'react';
+import { useCallback } from 'react';
 import { Cookie } from 'lucide-react';
-import { DEFAULT_CONSENT_CATEGORIES, consentI18nHelper, consentStorageHelper } from '@owlmeans/consent';
+import { DEFAULT_CONSENT_CATEGORIES, consentI18nHelper } from '@owlmeans/consent';
 import { webConsentUtils } from '../lib/utils.js';
 import { useConsent } from '../hooks.js';
-import { ConsentToggle } from './toggle.js';
+import { CONSENT_DEFAULT_MODE } from '../consts.js';
+import { ConsentBar } from './bar.js';
+import { ConsentLocatingOverlay } from './locating.js';
+import { ConsentWindow } from './window.js';
 import { FOCUS } from './consts.local.js';
-/** A pill button: 44px tall at minimum, full width on a phone, sharing the row above that. */
-const PILL = webConsentUtils.cn('inline-flex min-h-11 flex-1 items-center justify-center rounded-full px-6 py-2.5 text-[15px] transition-colors motion-safe:active:scale-[0.98]', FOCUS);
-/** A text link: muted, underlined at rest (colour is never the only signal), 44px tall to tap. */
-const LINK = webConsentUtils.cn('inline-flex min-h-11 items-center font-semibold underline decoration-1 underline-offset-4 transition-colors hover:text-foreground hover:decoration-2', FOCUS);
+/**
+ * The cookie-consent UI of a document: one of three surfaces at a time, and the corner button.
+ *
+ * - While a first-time visitor is being located (`geo`), a transparent overlay with a spinner.
+ * - The first ask (`reason: 'initial'`) in `bar` mode — the default — the bar.
+ * - Every other opening, and the first ask in `window` mode, the preferences window.
+ *
+ * Mounted once, at the application root, outside the router: a surface mounted in a route is torn
+ * down by the first navigation. The bar and the window share one save path, so whichever answers,
+ * the record carries every required category on and exactly the optional ones chosen.
+ */
 export const CookieConsent = props => {
     const categories = props.categories ?? DEFAULT_CONSENT_CATEGORIES;
     const t = props.translate ?? consentI18nHelper.defaultConsentTranslate(props.locale);
-    const consentOpts = {
+    const mode = props.mode ?? CONSENT_DEFAULT_MODE;
+    const consent = useConsent({
         categories,
         ...(props.storageKey != null ? { storageKey: props.storageKey } : {}),
         ...(props.cookieDays != null ? { cookieDays: props.cookieDays } : {}),
         ...(props.cookieDomain != null ? { cookieDomain: props.cookieDomain } : {}),
         ...(props.silent != null ? { silent: props.silent } : {}),
         ...(props.linker != null ? { linker: props.linker } : {}),
-    };
-    const consent = useConsent(consentOpts);
+        ...(props.geo != null ? { geo: props.geo } : {}),
+    });
     const domains = webConsentUtils.disclosedDomains(props.linker);
     const optional = categories.filter(category => category.required !== true);
-    const [draft, setDraft] = useState({});
-    // Re-seed the draft whenever the dialog opens, from what is actually stored: a visitor who opens
-    // preferences a second time must see the answer they gave, not the one the last render held.
-    useEffect(() => {
-        if (!consent.open) {
-            return;
-        }
-        const stored = consent.record ?? consentStorageHelper.readConsent({
-            ...(props.storageKey != null ? { storageKey: props.storageKey } : {}),
-        });
-        setDraft(Object.fromEntries(optional.map(category => [category.key, stored?.[category.key] === true])));
-    }, [consent.open, consent.record]);
     const persist = useCallback((values) => {
         const record = Object.fromEntries([
             ...categories.filter(c => c.required === true).map(c => [c.key, true]),
@@ -43,14 +42,9 @@ export const CookieConsent = props => {
         ]);
         consent.save(record);
     }, [categories, consent]);
-    const onSave = useCallback(() => persist(draft), [draft, persist]);
-    const onAcceptAll = useCallback(() => persist(Object.fromEntries(optional.map(c => [c.key, true]))), [optional, persist]);
-    // The dialog was raised by something that needs an answer before it can continue — signing in,
-    // today. Saying so, and relabelling the primary action, is what makes the interruption make
-    // sense rather than look like the page asking twice.
-    const gated = consent.reason === 'login';
-    return _jsxs(_Fragment, { children: [consent.open && _jsx("div", { className: "fixed inset-0 z-[999998] flex items-center justify-center overflow-y-auto bg-black/70 px-4 py-6", "aria-modal": "true", role: "dialog", "aria-labelledby": "cc-title", "aria-describedby": domains.length > 1 ? 'cc-desc cc-domains' : 'cc-desc', "data-consent-dialog": true, children: _jsxs("div", { className: webConsentUtils.cn('relative z-[999999] w-full max-w-lg rounded-3xl border border-border bg-background p-6 text-foreground sm:p-8', props.className), children: [_jsxs("div", { className: "mb-4 flex items-center gap-3", children: [_jsx("div", { className: "flex h-10 w-10 flex-shrink-0 items-center justify-center rounded-full bg-muted text-primary", children: _jsx(Cookie, { className: "h-5 w-5", "aria-hidden": "true" }) }), _jsx("h2", { id: "cc-title", className: "text-balance text-xl font-extrabold tracking-tight text-foreground sm:text-2xl", children: t('title', 'Cookie Preferences') })] }), _jsx("p", { id: "cc-desc", className: "mb-6 text-pretty text-sm leading-relaxed text-muted-foreground", children: t('description', 'We use cookies to enhance your browsing experience, serve personalized ads or content, and analyze our traffic.') }), domains.length > 1 && _jsx("p", { id: "cc-domains", "data-consent-domains": true, className: "mb-6 -mt-3 text-pretty text-xs text-muted-foreground", children: consentI18nHelper.interpolate(t('domains', 'This choice applies to {{domains}}.'), { domains: domains.join(', ') }) }), _jsx("div", { className: "space-y-3", children: categories.map(category => _jsx(ConsentToggle, { id: `cc-${category.key}`, label: t(category.labelKey, category.key), description: t(category.descriptionKey, ''), checked: draft[category.key] === true, ...(category.required === true ? { required: true } : {}), requiredLabel: t('required', 'Required'), onChange: value => setDraft(current => ({ ...current, [category.key]: value })) }, category.key)) }), gated && _jsx("p", { role: "status", "data-consent-reason": true, className: "mt-4 text-sm font-semibold text-foreground", children: t('loginReason', 'Signing in stores a session cookie. Accept essential cookies to continue.') }), _jsxs("div", { className: "mt-8 flex flex-col gap-3 sm:flex-row sm:gap-4", children: [_jsx("button", { type: "button", onClick: onSave, "data-consent-save": true, className: webConsentUtils.cn(PILL, 'border-[1.5px] border-foreground bg-transparent font-semibold text-foreground hover:bg-muted'), children: t('savePreferences', 'Save Preferences') }), _jsx("button", { type: "button", onClick: onAcceptAll, "data-consent-accept-all": true, className: webConsentUtils.cn(PILL, 'bg-primary font-bold text-primary-foreground hover:bg-primary/90'), children: gated
-                                        ? t('acceptAndContinue', 'Accept & continue')
-                                        : t('acceptAll', 'Accept All') })] }), (props.policyHref != null || props.links != null) && _jsxs("div", { className: "mt-3 flex flex-wrap justify-center gap-x-4 text-[13px] text-muted-foreground", children: [props.policyHref != null && _jsx("a", { href: props.policyHref, target: "_blank", rel: "noopener noreferrer", className: LINK, children: t('policyLink', 'Cookie Policy') }), props.links?.map(link => _jsx("a", { href: link.href, target: "_blank", rel: "noopener noreferrer", className: LINK, children: t(link.labelKey, link.defaultLabel) }, link.href))] })] }) }), props.noReopenButton !== true && consent.record != null && !consent.open && _jsx("button", { type: "button", onClick: () => consent.openDialog('reopen'), "aria-label": t('openPreferences', 'Cookie preferences'), "data-consent-reopen": true, className: webConsentUtils.cn('fixed bottom-1 left-1 z-[999997] inline-flex h-11 w-11 items-center justify-center rounded border-0 bg-transparent p-0 text-muted-foreground opacity-70 transition-opacity hover:opacity-100 hover:text-primary focus-visible:opacity-100', FOCUS), children: _jsx(Cookie, { className: "h-5 w-5", "aria-hidden": "true" }) })] });
+    const surface = consent.open
+        ? mode === 'bar' && consent.reason === 'initial' ? 'bar' : 'window'
+        : consent.locating === 'first' ? 'locating' : null;
+    return _jsxs(_Fragment, { children: [surface === 'locating' && _jsx(ConsentLocatingOverlay, { t: t }), surface === 'bar' && _jsx(ConsentBar, { t: t, categories: categories, domains: domains, policyHref: props.policyHref, links: props.links, barClassName: props.barClassName, onPreferences: () => consent.openDialog('preferences'), onMandatory: () => persist({}), onAcceptAll: () => persist(Object.fromEntries(optional.map(c => [c.key, true]))) }), surface === 'window' && _jsx(ConsentWindow, { t: t, categories: categories, domains: domains, record: consent.record, ...(props.storageKey != null ? { storageKey: props.storageKey } : {}), gated: consent.reason === 'login', policyHref: props.policyHref, links: props.links, className: props.className, onSave: persist }, consent.reason ?? 'window'), props.noReopenButton !== true && consent.record != null && !consent.open && consent.locating == null && _jsx("button", { type: "button", onClick: () => consent.openDialog('reopen'), "aria-label": t('openPreferences', 'Cookie preferences'), "data-consent-reopen": true, className: webConsentUtils.cn('fixed bottom-1 left-1 z-[999997] inline-flex h-11 w-11 items-center justify-center rounded border-0 bg-transparent p-0 text-muted-foreground opacity-70 transition-opacity hover:opacity-100 hover:text-primary focus-visible:opacity-100', FOCUS), children: _jsx(Cookie, { className: "h-5 w-5", "aria-hidden": "true" }) })] });
 };
 //# sourceMappingURL=component.js.map