@owlmeans/web-panel 0.1.18-rc.9 → 0.1.18

package/tests/harness/mount.tsx

@@ -1,15 +1,30 @@
 import '../../src/@/globals.css'
 
 import type { FC, PropsWithChildren } from 'react'
+import { useState } from 'react'
 import { createRoot } from 'react-dom/client'
 import { config } from '@owlmeans/client-context'
 import { AppType, service } from '@owlmeans/config'
 import { BASE, HOME } from '@owlmeans/context'
-import { entrypoint } from '@owlmeans/client-entrypoint'
+import { bindScreen } from '@owlmeans/client-entrypoint'
+import { openProtocol } from '@owlmeans/entrypoint'
 import { frontend, route } from '@owlmeans/route'
 import { handler, useNavigate } from '@owlmeans/client'
+import { toast } from 'sonner'
 import type { PanelNavConfig, PanelNavLink } from '../../src/index.js'
-import { makeContext, modules as baseModules, NavLayout, PanelApp } from '../../src/index.js'
+import {
+  makeContext, useContext, entrypoints as baseEntrypoints, NavLayout, PanelApp, Toaster,
+  lazyHandler, lazyComponent,
+} from '../../src/index.js'
+import { LoginScreen } from '../../src/components/login/index.js'
+import {
+  PanelCookieConsent, PanelConsentMenuWidget, appendConsentWidgetService, useConsentMenuPresence,
+  appendConsentGeoPlugin,
+} from '../../src/consent/index.js'
+import { LoginOutcome, ensureLoginService } from '@owlmeans/client-auth/login'
+import type { LoginMethod } from '@owlmeans/client-auth/login'
+import { EditorHarness } from './editor.js'
+import { PickerScreen, TranslatedPickerScreen } from './picker.js'
 
 // A real app: a context, a layout entrypoint rendering NavLayout, and screens under it.
 // The nav model resolves the active screen from the router, so nothing here may be faked.
@@ -22,42 +37,219 @@ const alias = {
   reports: `${SERVICE}:web:reports`,
   reportsIndex: `${SERVICE}:web:reports-index`,
   reportDetail: `${SERVICE}:web:report-detail`,
+  reportSibling: `${SERVICE}:web:report-sibling`,
   prefs: `${SERVICE}:web:prefs`,
+  login: `${SERVICE}:web:login`,
+  socket: `${SERVICE}:web:socket`,
+  lazy: `${SERVICE}:web:lazy`,
+  lazyEntry: `${SERVICE}:web:lazy-entry`,
+  picker: `${SERVICE}:web:picker`,
 }
 
+/** A harness id for the ONE tracked connection this screen simulates — a real `ws()`/`useWs()`
+ *  connection would generate its own, but the status service only cares that it is stable across
+ *  the two buttons below. */
+const HARNESS_SOCKET_ID = 'harness-socket'
+
 const navConfig: PanelNavConfig = {
   sections: [
     // Two screens — the side menu shows.
     {
       name: 'work', label: 'Work', items: [
-        { alias: alias.dash, label: 'Dashboard' },
+        { alias: alias.dash, label: 'Dashboard', testId: 'dashboard-nav' },
         { alias: alias.reports, label: 'Reports' },
       ]
     },
     // One screen — the side menu must not render at all.
-    { name: 'settings', label: 'Settings', items: [{ alias: alias.prefs, label: 'Preferences' }] },
+    { name: 'settings', label: 'Settings', testId: 'settings-nav', items: [{ alias: alias.prefs, label: 'Preferences' }] },
     // No literal labels: exercises the humanized-alias fallback with no i18n present.
     { name: 'extra', items: [{ alias: HOME }] },
   ],
 }
 
 const footerLinks: PanelNavLink[] = [
-  { alias: alias.dash, label: 'Dashboard' },
+  { alias: alias.dash, label: 'Dashboard', testId: 'dashboard-nav' },
   { href: 'https://owlmeans.com', label: 'OwlMeans', open: true },
 ]
 
 const screen = (id: string, text: string): FC => () => <div id={id}>{text}</div>
 
-const Layout: FC<PropsWithChildren> = ({ children }) => <NavLayout
-  nav={navConfig}
-  title="Harness"
-  actions={<button id="action-slot">action</button>}
-  footer={footerLinks}
->{children}</NavLayout>
+/**
+ * What the sign-in screen offers in the harness.
+ *
+ * Real methods, with real `start` handlers that record they were called — the one thing the
+ * screen must never do is start one on its own, and a method that only pretended to start could
+ * not prove it.
+ */
+const started: string[] = []
+;(globalThis as unknown as { __loginStarted: string[] }).__loginStarted = started
+
+const method = (id: string, over?: Partial<LoginMethod>): LoginMethod => ({
+  id,
+  order: 10,
+  start: async () => { started.push(id); return LoginOutcome.Handled },
+  ...over,
+})
+
+/** The sign-in screen, with the terms confirmation the configuration requires. */
+const LoginHarness: FC = () => {
+  const [locale, setLocale] = useState<string | undefined>(localizedTerms ? 'pl' : undefined)
+
+  return <>
+    {localizedTerms && <button id="login-language-fr" onClick={() => setLocale('fr')}>Français</button>}
+    <LoginScreen
+      Logo={() => <span id="login-logo">logo</span>}
+      translate={(_key, defaultValue) => defaultValue}
+      locale={locale}
+    />
+  </>
+}
+
+// `?header=broken` simulates the layout-restyle bug this harness pins: a `headerClassName`
+// carrying an invalid Tailwind v4 arbitrary-value background (v3 syntax, silently dropped) and a
+// bare `bg-transparent`, either of which used to leave the sticky header with no background paint
+// of its own at all. One harness process serves both branches, exactly like `reloadDialog` above.
+const brokenHeader = new URLSearchParams(window.location.search).get('header') === 'broken'
+// `?footer=none` omits the `footer` prop entirely — the shape every area layout had before the
+// shell grew a footer-links convention. `NavLayout` must still render the credit line then.
+const noFooterProp = new URLSearchParams(window.location.search).get('footer') === 'none'
+// `?footer=node` hands `NavLayout` a NODE footer — an application's own footer layout (a brand
+// block and a Legal column), the shape a generated app's footer takes — instead of links.
+const nodeFooter = new URLSearchParams(window.location.search).get('footer') === 'node'
+// `?mobileMenu=1` opts into the narrow-viewport menu sheet. Absent, the prop is not passed at
+// all — the shape every existing layout has — and the shell must render exactly what it always did.
+const mobileMenu = new URLSearchParams(window.location.search).get('mobileMenu') === '1'
+// `?consent=bare` mounts `PanelCookieConsent` on a context that never appended the presence
+// service — an application using the dialog on its own. `?consent=menu` appends the service, so
+// the footer's "Cookie settings" control takes over the floating button's job.
+const consentMode = new URLSearchParams(window.location.search).get('consent')
+// `?consentCfg=window|bar` sets `cfg.cookieConsent.mode`; `?modeProp=bar|window` passes `mode` as a
+// prop on top of it (the prop must win). `?consentGeo=<CC>|fail` appends a context-level locator
+// with `appendConsentGeoPlugin` — the gate turns on with no `geo` configured anywhere.
+const consentCfg = new URLSearchParams(window.location.search).get('consentCfg')
+const modeProp = new URLSearchParams(window.location.search).get('modeProp')
+const consentGeo = new URLSearchParams(window.location.search).get('consentGeo')
+// `?skip=off` passes `skipLinkLabel={false}` — an application that renders its own skip link.
+const skipOff = new URLSearchParams(window.location.search).get('skip') === 'off'
+// `?themeToggle=1` asks for the footer's light/dark switcher. Absent, the prop is not passed.
+const themeToggle = new URLSearchParams(window.location.search).get('themeToggle') === '1'
+// `?terms=extended` adds billing/product/custom documents and a revision date to the terms
+// confirmation — the shape that pins the "still exactly one checkbox" and "documents render
+// outside the notice" rules even when there is more than terms+privacy to show.
+const extendedTerms = new URLSearchParams(window.location.search).get('terms') === 'extended'
+// `?terms=localized` selects known translated destinations using the live screen locale.
+const localizedTerms = new URLSearchParams(window.location.search).get('terms') === 'localized'
+// `?defer=bound` registers a step that CONFIRMS the terms, bound to a real screen — the sign-in
+// screen must then show no checkbox, only the privacy notice, and block nothing.
+// `?defer=unbound` registers the same step but never binds its entrypoint — the checkbox must
+// stay (fail-closed): a step nobody can reach must never silently remove the confirmation.
+const defer = new URLSearchParams(window.location.search).get('defer')
+// `?domains=1` passes `linker` through to `PanelCookieConsent` — proving the prop reaches
+// `@owlmeans/web-consent`'s `CookieConsent` with nothing lost in between (the props already just
+// spread through; this is what pins that they keep doing so).
+const withDomains = new URLSearchParams(window.location.search).get('domains') === '1'
+// `?provider=top|inline` configures who signs the person in — the disclosure a platform-hosted
+// app shows. A product name is set only then, so every other screen keeps the brand it always had.
+const providerPlacement = new URLSearchParams(window.location.search).get('provider')
+
+/**
+ * The footer's "Cookie settings" control — the menu widget, rendered from an always-mounted
+ * component that also declares the presence, exactly as the `./consent` rules ask.
+ */
+const CookieSettings: FC = () => {
+  useConsentMenuPresence()
+
+  return <PanelConsentMenuWidget label="Cookie settings" className="w-auto" />
+}
+
+const FooterBlock: FC = () => <div id="footer-block" className="flex flex-wrap justify-between gap-8">
+  <div>
+    <strong>Harness</strong>
+    <p>One line about what the harness does.</p>
+  </div>
+  <nav aria-label="Legal">
+    <p>Legal</p>
+    <ul>
+      <li><a href="/privacy">Privacy</a></li>
+      <li><a href="/terms">Terms</a></li>
+      {consentMode != null && <li><CookieSettings /></li>}
+    </ul>
+  </nav>
+</div>
+
+// `/picker` is a page of its own — no shell around it, so its screenshots show the picker alone.
+const pickerPage = window.location.pathname.startsWith('/picker')
+// `/picker?bare=1` is mounted with no `PanelApp` and no i18n instance at all — the parts must render.
+const pickerBare = pickerPage && new URLSearchParams(window.location.search).get('bare') === '1'
+
+const Layout: FC<PropsWithChildren> = ({ children }) => pickerPage ? <>{children}</> : <>
+  <NavLayout
+    nav={navConfig}
+    navTestId="harness-nav"
+    title="Harness"
+    actions={<button id="action-slot">action</button>}
+    {...(noFooterProp ? {} : { footer: nodeFooter ? <FooterBlock /> : footerLinks })}
+    {...(mobileMenu ? { mobileMenu: true } : {})}
+    {...(skipOff ? { skipLinkLabel: false as const } : {})}
+    {...(themeToggle ? { themeToggle: true } : {})}
+    // A DARK APPLICATION SHELL, which is what a themed app does to the root: a contrasting
+    // surface pair, both halves correct. The header paints its own opaque background, so it is
+    // a different surface, and everything in it must stay legible against `--background`
+    // rather than against this. The harness carries it permanently so every navigation test
+    // runs against the hostile case instead of a default-coloured page.
+    className="bg-primary text-primary-foreground"
+    // A WIDTH-ONLY rhythm override, which is what a design pass writes when it wants a wider
+    // page. It names the width and nothing else, so the centring and the side padding must
+    // survive it — substituting this for the default is a page running flush to the window edge.
+    containerClassName="max-w-[1280px]"
+    {...(brokenHeader ? { headerClassName: 'bg-[--nope] bg-transparent' } : {})}
+  >{children}</NavLayout>
+  {/* Mounted ONCE, in the layout — exactly where an application mounts it. */}
+  <Toaster />
+</>
+
+/** The toast surface's exercise: a screen action that reports its outcome. */
+const PrefsScreen: FC = () => <div id="prefs">
+  prefs-screen
+  <button id="fire-toast" onClick={() => toast.success('preferences saved')}>save</button>
+  {/* Outlives any assertion — a theme check must not race the 5s default dismissal. */}
+  <button id="fire-sticky" onClick={() => toast.error('sticky failure', { duration: 600_000 })}>fail</button>
+</div>
 
 /** A grouping screen — it renders whichever child the router matched. */
 const ReportsGroup: FC<PropsWithChildren> = ({ children }) => <div id="reports-group">{children}</div>
 
+/**
+ * Drives the SAME status service `SocketReloadDialog` reads, exactly the way a real dropped
+ * `ws()`/`useWs()` connection would — through `report()`/`release()`, never a prop the dialog
+ * itself exposes, since it has none: the whole point is that any socket, anywhere in the app,
+ * can put the dialog up.
+ */
+const SocketStatusScreen: FC = () => {
+  const context = useContext()
+  // A revive the way a real carrier's goes: the connection is retrying again the moment it is
+  // asked to. How that retry ends is up to the test — `#report-online` or `#report-lost`.
+  const [revived, setRevived] = useState(0)
+  const reportLost = () => context.socketStatus().report(HARNESS_SOCKET_ID, 'lost', () => {
+    setRevived(n => n + 1)
+    context.socketStatus().report(HARNESS_SOCKET_ID, 'reconnecting')
+  })
+
+  return <div id="socket-status">
+    socket-status-screen
+    <span id="revived">{revived}</span>
+    <button id="report-lost" onClick={reportLost}>
+      lose connection
+    </button>
+    <button id="report-online" onClick={() => context.socketStatus().report(HARNESS_SOCKET_ID, 'online')}>
+      reconnected
+    </button>
+    <button id="release-lost" onClick={() => context.socketStatus().release(HARNESS_SOCKET_ID)}>
+      restore connection
+    </button>
+  </div>
+}
+
 /**
  * The section's landing screen. Its button navigates to a screen the MENU DOES NOT LIST,
  * which is the only way to exercise the parent-chain walk: an in-app navigation puts the
@@ -69,6 +261,38 @@ const ReportsIndex: FC = () => {
   return <div id="reports">
     reports-screen
     <button id="to-detail" onClick={nav.press(alias.reportDetail)}>detail</button>
+    <button id="to-sibling" onClick={nav.press(alias.reportSibling)}>sibling detail</button>
+  </div>
+}
+
+/**
+ * Lazily-loaded screens, declared at MODULE SCOPE as the helpers require — the route renderer
+ * remounts a screen on every navigation, so a lazy object made during render would re-suspend
+ * each time. Both go through the package root, which is what an application imports.
+ *
+ * `flakyScreen` fails its first load on purpose: a rejected load must be retried, never cached.
+ * The globals let a spec drive `preload()` without a screen of its own.
+ */
+let flakyLoads = 0
+const lazyScreen = lazyHandler(
+  () => import('./lazy-screen.js'), 'LazyScreen', { fallback: <div id="lazy-fallback">loading</div> }
+)
+const flakyScreen = lazyComponent(async () => {
+  if (++flakyLoads === 1) throw new Error('first-load-fails')
+  return import('./lazy-screen.js')
+}, 'LazyScreen')
+;(globalThis as unknown as { __lazyPreload: () => Promise<boolean> }).__lazyPreload =
+  async () => typeof await lazyScreen.preload() === 'function'
+;(globalThis as unknown as { __flakyPreload: () => Promise<string> }).__flakyPreload =
+  () => flakyScreen.preload().then(() => 'loaded', (e: Error) => e.message)
+
+/** The lazy screen's way in: an in-app navigation, so the layout around it is already mounted. */
+const LazyEntry: FC = () => {
+  const nav = useNavigate()
+
+  return <div id="lazy-entry">
+    lazy-entry-screen
+    <button id="to-lazy" onClick={nav.press(alias.lazy)}>lazy</button>
   </div>
 }
 
@@ -77,7 +301,55 @@ const ReportsIndex: FC = () => {
 // sides are declared here exactly as a real app declares them.
 const base = service({ type: AppType.Frontend, service: SERVICE, host: 'localhost', port: 5173 })
 service({ type: AppType.Backend, service: API, host: 'localhost', port: 5174, base: 'api' }, base)
-base.security = { unsecure: true }
+base.security = {
+  unsecure: true,
+  auth: {
+    login: {
+      // Confirmation required, which is the case that matters: a method must be blocked until it
+      // is given, and blocking must SAY so rather than swallow the click.
+      terms: {
+        required: true, terms: 'https://example.test/terms', privacy: 'https://example.test/privacy',
+        ...(localizedTerms ? {
+          billing: { href: 'https://example.test/billing', revisedAt: '2026-10-04' },
+          cookies: 'https://example.test/cookies', showRevision: true,
+          localizedHrefs: {
+            terms: { pl: 'https://example.test/pl/terms', fr: 'https://example.test/fr/terms' },
+            billing: { pl: 'https://example.test/pl/billing', fr: 'https://example.test/fr/billing' },
+            privacy: { pl: 'https://example.test/pl/privacy', fr: 'https://example.test/fr/privacy' },
+            cookies: { pl: 'https://example.test/pl/cookies', fr: 'https://example.test/fr/cookies' },
+          },
+        } : {}),
+        ...(extendedTerms ? {
+          billing: { href: 'https://example.test/billing', revisedAt: '2026-01-01' },
+          product: { name: 'Harness', href: 'https://example.test/product' },
+          documents: [
+            { key: 'custom-a', href: 'https://example.test/custom-a', label: 'Custom A' },
+            { key: 'custom-b', href: 'https://example.test/custom-b', label: 'Custom B' },
+          ],
+          showRevision: true,
+        } : {}),
+      },
+      credit: { poweredBy: true, product: 'Harness', organization: 'Acme' },
+      ...(providerPlacement === 'top' || providerPlacement === 'inline' ? {
+        provider: {
+          name: 'Harness IAM', operator: 'Harness Hosting', info: 'https://example.test/about',
+          placement: providerPlacement,
+        },
+      } : {}),
+    },
+  },
+}
+if (providerPlacement != null) {
+  base.brand = { ...base.brand, name: 'Harness App' }
+}
+// Every other screen in this harness stays unaffected: nothing ever reports into the status
+// service unless `#report-lost` is clicked, so the flag being on by default costs nothing. A
+// test that needs the OFF case loads `?reloadDialog=0` — one harness process, both branches.
+const reloadDialogEnabled = new URLSearchParams(window.location.search).get('reloadDialog') !== '0'
+;(base as { socket?: { reloadDialog?: boolean } }).socket = { reloadDialog: reloadDialogEnabled }
+if (consentCfg === 'window' || consentCfg === 'bar') {
+  ;(base as { cookieConsent?: { mode: 'window' | 'bar' } }).cookieConsent = { mode: consentCfg }
+}
 
 // `ready` stays false: the Router compiles the entrypoint tree into routes ONLY while the
 // context is un-initialized, so a pre-readied context renders a blank page.
@@ -85,29 +357,98 @@ const cfg = config(SERVICE, base as never)
 const context = makeContext(cfg as never)
 context.serviceRoute(SERVICE, true)
 context.serviceRoute(API, true)
+if (consentMode === 'menu') {
+  appendConsentWidgetService(context as never)
+}
+if (consentGeo != null) {
+  appendConsentGeoPlugin(context as never, {
+    alias: 'harness-geo',
+    locate: async () => {
+      if (consentGeo === 'fail') {
+        throw new Error('the harness locator cannot tell')
+      }
+
+      return { country: consentGeo }
+    },
+  })
+}
+
+ensureLoginService(context as never).registerMethodSource({
+  alias: 'harness',
+  list: () => [
+    method('primary', { emphasis: 'primary', icon: 'google', label: 'Continue with Google' }),
+    // A method that finishes without moving the document — the shape of a relying party that
+    // could not build an authorization URL. The screen must SAY so; silence reads as a dead
+    // button, which is exactly the bug this pins.
+    method('secondary', {
+      order: 20, label: 'Sign in with a key',
+      start: async () => { started.push('secondary'); return LoginOutcome.Passed },
+    }),
+    method('operator', { order: 900, restricted: true, label: 'Secret key' }),
+  ],
+})
+
+if (defer != null) {
+  ensureLoginService(context as never).registerStep({
+    alias: 'harness-terms-step',
+    // "bound" points at a real screen of this harness (`/prefs`, already registered below) —
+    // `termsDeferred` only reads `ctx.hasEntrypoint`, so any bound alias proves the point.
+    // "unbound" points nowhere: `hasEntrypoint` answers false and the step stays unreachable.
+    entrypoint: defer === 'bound' ? alias.prefs : 'harness-terms-step-nowhere',
+    confirmsTerms: true,
+    required: true,
+    pending: async () => false,
+  })
+}
+
+const protocols = {
+  base: openProtocol(route(BASE, '/', frontend())),
+  home: openProtocol(route(HOME, '/', frontend({ default: true, parent: BASE }))),
+  dash: openProtocol(route(alias.dash, '/dash', frontend({ parent: BASE }))),
+  reports: openProtocol(route(alias.reports, '/reports', frontend({ parent: BASE }))),
+  reportsIndex: openProtocol(route(alias.reportsIndex, '/', frontend({ default: true, parent: alias.reports }))),
+  reportDetail: openProtocol(route(alias.reportDetail, '/detail', frontend({ parent: alias.reports }))),
+  reportSibling: openProtocol(route(alias.reportSibling, '/reports/sibling', frontend({ parent: BASE }))),
+  prefs: openProtocol(route(alias.prefs, '/prefs', frontend({ parent: BASE }))),
+  login: openProtocol(route(alias.login, '/login', frontend({ parent: BASE }))),
+  socket: openProtocol(route(alias.socket, '/socket', frontend({ parent: BASE }))),
+  lazy: openProtocol(route(alias.lazy, '/lazy', frontend({ parent: BASE }))),
+  lazyEntry: openProtocol(route(alias.lazyEntry, '/lazy-entry', frontend({ parent: BASE }))),
+  picker: openProtocol(route(alias.picker, '/picker', frontend({ parent: BASE }))),
+}
 
-const modules = [
+const entrypoints = [
   // The framework's own entrypoints come first — the api-config middleware the panel context
   // registers resolves one of them during init, and without them init throws before any route
   // is compiled.
-  ...baseModules,
-  entrypoint(route(BASE, '/', frontend()), handler(Layout)),
-  entrypoint(route(HOME, '/', frontend({ default: true, parent: BASE })), handler(screen('home', 'home-screen'))),
-  entrypoint(route(alias.dash, '/dash', frontend({ parent: BASE })), handler(screen('dash', 'dash-screen'))),
+  ...baseEntrypoints,
+  bindScreen(protocols.base, handler(Layout)),
+  bindScreen(protocols.home, handler(screen('home', 'home-screen'))),
+  bindScreen(protocols.dash, handler(screen('dash', 'dash-screen'))),
   // A screen that has children needs a `default: true` child of its own — without one its own
   // path matches nothing and the page renders blank.
-  entrypoint(route(alias.reports, '/reports', frontend({ parent: BASE })), handler(ReportsGroup)),
-  entrypoint(
-    route(alias.reportsIndex, '/', frontend({ default: true, parent: alias.reports })),
-    handler(ReportsIndex)
-  ),
-  entrypoint(
-    route(alias.reportDetail, '/detail', frontend({ parent: alias.reports })),
-    handler(screen('detail', 'detail-screen'))
-  ),
-  entrypoint(route(alias.prefs, '/prefs', frontend({ parent: BASE })), handler(screen('prefs', 'prefs-screen'))),
+  bindScreen(protocols.reports, handler(ReportsGroup)),
+  bindScreen(protocols.reportsIndex, handler(ReportsIndex)),
+  bindScreen(protocols.reportDetail, handler(screen('detail', 'detail-screen'))),
+  bindScreen(protocols.reportSibling, handler(screen('sibling-detail', 'sibling-detail-screen'))),
+  bindScreen(protocols.prefs, handler(PrefsScreen)),
+  bindScreen(protocols.login, handler(LoginHarness)),
+  bindScreen(protocols.socket, handler(SocketStatusScreen)),
+  bindScreen(protocols.lazy, lazyScreen),
+  bindScreen(protocols.lazyEntry, handler(LazyEntry)),
+  bindScreen(protocols.picker, handler(TranslatedPickerScreen)),
 ]
 
-context.registerEntrypoints(modules)
+context.registerEntrypoints(entrypoints)
 
-createRoot(document.getElementById('root')!).render(<PanelApp context={context as never} />)
+// The consent dialog is a sibling of the Router, as in an application — and only on the consent
+// branches, since its first-visit overlay covers the page every other test clicks through.
+createRoot(document.getElementById('root')!).render(new URLSearchParams(location.search).has('editor') ? <EditorHarness /> : pickerBare
+  ? <div className="min-h-screen bg-background text-foreground"><PickerScreen /></div>
+  : <PanelApp context={context as never}>
+  {consentMode != null && <PanelCookieConsent
+    policyHref="/cookies"
+    {...(withDomains ? { linker: { domains: ['harness-partner.test'] } } : {})}
+    {...(modeProp === 'window' || modeProp === 'bar' ? { mode: modeProp } : {})}
+  />}
+</PanelApp>)

package/tests/harness/picker.tsx

@@ -0,0 +1,110 @@
+import { useState } from 'react'
+import type { FC } from 'react'
+import {
+  ColorDot, ColorPicker, ColorSwatches, IconColorPicker, IconGrid, IconPicker, IconTile, usePickerTranslate,
+} from '../../src/picker/index.js'
+import type { IconColorChange, PickerTranslate } from '../../src/picker/index.js'
+import { Sheet, SheetContent, SheetTitle, SheetTrigger } from '../../src/@/components/ui/sheet.js'
+
+/**
+ * The picker's scenarios, picked by query parameters:
+ *
+ * - `?custom=1` — `customColors` on every picker;
+ * - `?surface=popover|sheet` — forces the surface (default `auto`);
+ * - `?compact=1` — the `tile` / `dot` triggers;
+ * - `?empty=1` — nothing chosen yet;
+ * - `?inSheet=1` — the composite picker inside a Radix Sheet of the page's own;
+ * - `?inline=1` — the inline parts (`ColorSwatches`, `IconGrid`) on the page;
+ * - `?bare=1` — mounted with no `PanelApp` and no i18n instance at all (mount.tsx);
+ * - `?dark=1` — `.dark` on the document element.
+ */
+const params = new URLSearchParams(window.location.search)
+const custom = params.get('custom') === '1'
+const compact = params.get('compact') === '1'
+const empty = params.get('empty') === '1'
+const inSheet = params.get('inSheet') === '1'
+const inline = params.get('inline') === '1'
+const surfaceParam = params.get('surface')
+const surface = surfaceParam === 'popover' || surfaceParam === 'sheet' ? surfaceParam : 'auto'
+
+if (params.get('dark') === '1') {
+  document.documentElement.classList.add('dark')
+}
+
+const SAMPLES: Array<[string, string]> = [
+  ['rocket', 'blue'], ['bug', 'red'], ['handshake', 'emerald'], ['flag', 'amber'], ['users', 'violet'],
+  ['package', 'brown'], ['map-pin', 'navy'], ['siren', 'maroon'], ['leaf', 'olive'], ['star', 'graphite'],
+]
+
+export const PickerScreen: FC<{ translate?: PickerTranslate }> = ({ translate }) => {
+  const [mark, setMark] = useState<IconColorChange>(empty ? {} : { icon: 'rocket', color: 'indigo' })
+  const [color, setColor] = useState<string | undefined>(empty ? undefined : 'teal')
+  const [icon, setIcon] = useState<string | undefined>(empty ? undefined : 'briefcase')
+  const [submits, setSubmits] = useState(0)
+
+  const form = (id: string) => <form
+    id={id} className="flex flex-col gap-4"
+    onSubmit={event => { event.preventDefault(); setSubmits(count => count + 1) }}
+  >
+    <div className="flex flex-col gap-1.5">
+      <label htmlFor={`${id}-mark`} className="text-sm font-medium">Mark</label>
+      <IconColorPicker
+        id={`${id}-mark`} label="Mark" value={mark} onChange={setMark} customColors={custom} surface={surface}
+        trigger={compact ? 'tile' : 'button'} translate={translate}
+      />
+    </div>
+    <div className="grid gap-4 sm:grid-cols-2">
+      <div className="flex flex-col gap-1.5">
+        <label htmlFor={`${id}-color`} className="text-sm font-medium">Colour</label>
+        <ColorPicker
+          id={`${id}-color`} label="Colour" value={color} onChange={setColor} customColors={custom} surface={surface}
+          trigger={compact ? 'dot' : 'button'} translate={translate}
+        />
+      </div>
+      <div className="flex flex-col gap-1.5">
+        <label htmlFor={`${id}-icon`} className="text-sm font-medium">Icon</label>
+        <IconPicker
+          id={`${id}-icon`} label="Icon" value={icon} onChange={setIcon} color={color} surface={surface}
+          trigger={compact ? 'tile' : 'button'} translate={translate}
+        />
+      </div>
+    </div>
+    <button type="submit" className="self-start rounded-md border px-3 py-1.5 text-sm">Save</button>
+  </form>
+
+  return <main id="picker" className="mx-auto flex w-full max-w-2xl flex-col gap-6 px-4 py-8">
+    <h1 className="text-xl font-semibold">Icon and colour picker</h1>
+    {inSheet
+      ? <Sheet>
+        <SheetTrigger id="open-sheet" className="self-start rounded-md border px-3 py-1.5 text-sm">Open sheet</SheetTrigger>
+        <SheetContent side="right" aria-describedby={undefined} className="gap-0 p-6 text-foreground">
+          <SheetTitle className="mb-4">Edit type</SheetTitle>
+          {form('sheet-form')}
+        </SheetContent>
+      </Sheet>
+      : <section className="rounded-xl border p-4">{form('picker-form')}</section>}
+    {inline && <section id="inline" className="flex flex-col gap-4 rounded-xl border p-4">
+      <ColorSwatches value={mark.color} onChange={next => setMark({ ...mark, color: next })} customColors={custom} translate={translate} />
+      <div className="max-h-72 overflow-y-auto">
+        <IconGrid value={mark.icon} onChange={next => setMark({ ...mark, icon: next })} color={mark.color} translate={translate} />
+      </div>
+    </section>}
+    <section id="samples" className="flex flex-wrap items-center gap-3 rounded-xl border p-4">
+      {SAMPLES.map(([sampleIcon, sampleColor]) =>
+        <IconTile key={sampleColor} icon={sampleIcon} color={sampleColor} label={`${sampleIcon} ${sampleColor}`} />)}
+      <IconTile icon="rocket" color="blue" variant="plain" size="lg" label="plain rocket" />
+      <IconTile icon="not-an-icon" color="not-a-colour" label="fallback" />
+      <ColorDot color="blue" size="md" label="blue dot" />
+      <ColorDot color="#ff00aa" size="md" label="custom dot" />
+    </section>
+    <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1 text-sm">
+      <dt>mark</dt><dd><output id="mark-value">{JSON.stringify(mark)}</output></dd>
+      <dt>colour</dt><dd><output id="color-value">{color ?? ''}</output></dd>
+      <dt>icon</dt><dd><output id="icon-value">{icon ?? ''}</output></dd>
+      <dt>submits</dt><dd><output id="submits">{submits}</output></dd>
+    </dl>
+  </main>
+}
+
+/** The screen as an application rendered by `PanelApp` mounts it: strings from the packaged bundle. */
+export const TranslatedPickerScreen: FC = () => <PickerScreen translate={usePickerTranslate()} />