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

package/tests/picker-vocabulary.spec.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from 'bun:test'
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  PICKER_COLORS, PICKER_COLOR_KEYS, PICKER_FALLBACK_COLOR, PICKER_FALLBACK_ICON, PICKER_ICON_CATEGORIES,
+  PICKER_ICON_ENTRIES, PICKER_ICON_NAMES, pickerColorHelper,
+} from '../src/picker/vocabulary.js'
+import { PICKER_ICONS } from '../src/picker/icons/consts.js'
+import { pickerIconHelper } from '../src/picker/icons.js'
+
+// Colour arithmetic written here, independently of the package's own, so the palette is checked
+// against the definitions rather than against itself.
+const channels = (hex: string): number[] => [1, 3, 5].map(at => parseInt(hex.slice(at, at + 2), 16) / 255)
+const linear = (c: number): number => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
+const luminance = (hex: string): number => {
+  const [r, g, b] = channels(hex).map(linear)
+
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b
+}
+const contrast = (a: string, b: string): number => {
+  const [x, y] = [luminance(a), luminance(b)]
+
+  return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05)
+}
+const oklab = (hex: string): number[] => {
+  const [r, g, b] = channels(hex).map(linear)
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b)
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b)
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b)
+
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ]
+}
+const distance = (a: string, b: string): number => {
+  const [x, y] = [oklab(a), oklab(b)]
+
+  return Math.hypot(x[0] - y[0], x[1] - y[1], x[2] - y[2])
+}
+
+/** The ten hues the generated targets' look has always used — their values may never move. */
+const LEGACY: Record<string, [string, string, string, string]> = {
+  slate: ['#334155', '#F1F5F9', '#CBD5E1', '#1E293B'],
+  blue: ['#1D4ED8', '#DBEAFE', '#93C5FD', '#172554'],
+  sky: ['#0369A1', '#E0F2FE', '#7DD3FC', '#082F49'],
+  teal: ['#115E59', '#CCFBF1', '#5EEAD4', '#042F2E'],
+  green: ['#166534', '#DCFCE7', '#86EFAC', '#052E16'],
+  amber: ['#92400E', '#FEF3C7', '#FCD34D', '#451A03'],
+  orange: ['#9A3412', '#FFEDD5', '#FDBA74', '#431407'],
+  red: ['#B91C1C', '#FEE2E2', '#FCA5A5', '#450A0A'],
+  pink: ['#BE185D', '#FCE7F3', '#F9A8D4', '#500724'],
+  violet: ['#6D28D9', '#EDE9FE', '#C4B5FD', '#2E1065'],
+}
+
+/**
+ * Minimum OKLab distance between two inks of one mode. A just-noticeable difference is about 0.02.
+ * Two legacy neighbours sit closest — orange and amber's light inks, 0.028 — and their values are
+ * fixed, so every pair keeps 0.025; a pair with at least one of the fourteen newer colours keeps 0.045.
+ */
+const MIN_DISTANCE = 0.025
+const MIN_DISTANCE_NEW = 0.045
+
+/** The icons the planning kits use (viable-agent `KIT_ICONS`) — the catalogue must hold every one. */
+const KIT_ICONS = [
+  'circle', 'tag', 'layers', 'flag', 'target', 'star', 'briefcase', 'folder', 'book-open', 'file-text', 'sparkles',
+  'lightbulb', 'rocket', 'bug', 'shield', 'square-check', 'list-checks', 'clipboard-list', 'funnel', 'trending-up',
+  'handshake', 'building', 'contact', 'user-round', 'user-round-check', 'users', 'phone', 'mail', 'message-square',
+  'megaphone', 'calendar', 'calendar-check', 'clock', 'headset', 'inbox', 'siren', 'warehouse', 'package', 'receipt',
+  'truck', 'map', 'map-pin', 'wrench', 'workflow', 'send', 'stamp',
+]
+
+describe('@owlmeans/web-panel/picker/vocabulary — the palette', () => {
+  test('24 unique keys in hue order; the ten legacy hues keep their exact values', () => {
+    expect(PICKER_COLORS.map(color => color.key)).toEqual([...PICKER_COLOR_KEYS])
+    expect(new Set(PICKER_COLOR_KEYS).size).toBe(24)
+    expect(PICKER_COLOR_KEYS).toContain(PICKER_FALLBACK_COLOR)
+    for (const [key, values] of Object.entries(LEGACY)) {
+      const color = PICKER_COLORS.find(candidate => candidate.key === key)
+      expect({ key, values: [color?.ink, color?.soft, color?.inkDark, color?.softDark] }).toEqual({ key, values })
+    }
+  })
+
+  test('every ink keeps 4.5:1 on its ground and on the page, in both modes; every value is distinct', () => {
+    for (const color of PICKER_COLORS) {
+      const dark = { ink: color.inkDark ?? color.ink, soft: color.softDark ?? color.soft }
+      const ratios = {
+        key: color.key,
+        onSoft: contrast(color.ink, color.soft) >= 4.5,
+        onWhite: contrast(color.ink, '#FFFFFF') >= 4.5,
+        onSoftDark: contrast(dark.ink, dark.soft) >= 4.5,
+        onBlack: contrast(dark.ink, '#000000') >= 4.5,
+      }
+      expect(ratios).toEqual({ key: color.key, onSoft: true, onWhite: true, onSoftDark: true, onBlack: true })
+    }
+    const values = PICKER_COLORS.flatMap(color => [color.swatch, color.ink, color.soft, color.inkDark, color.softDark])
+      .map(value => value?.toLowerCase())
+    expect(values.every(value => value != null && /^#[0-9a-f]{6}$/.test(value))).toBe(true)
+    expect(new Set(values).size).toBe(PICKER_COLORS.length * 5)
+  })
+
+  test('the inks of one mode stay apart in OKLab', () => {
+    for (const mode of ['ink', 'inkDark'] as const) {
+      for (let i = 0; i < PICKER_COLORS.length; i++) {
+        for (let j = i + 1; j < PICKER_COLORS.length; j++) {
+          const [a, b] = [PICKER_COLORS[i], PICKER_COLORS[j]]
+          const legacy = a.key in LEGACY && b.key in LEGACY
+          const apart = distance(a[mode] ?? a.ink, b[mode] ?? b.ink)
+          expect({ mode, pair: `${a.key}/${b.key}`, apart: apart >= (legacy ? MIN_DISTANCE : MIN_DISTANCE_NEW) })
+            .toEqual({ mode, pair: `${a.key}/${b.key}`, apart: true })
+        }
+      }
+    }
+  })
+})
+
+describe('@owlmeans/web-panel/picker/vocabulary — pickerColorHelper', () => {
+  test('normalizes hex and resolves keys, hex and unknown values', () => {
+    expect(pickerColorHelper.normalizeHex('#ABC')).toBe('#aabbcc')
+    expect(pickerColorHelper.normalizeHex('abc')).toBe('#aabbcc')
+    expect(pickerColorHelper.normalizeHex(' AABBCC ')).toBe('#aabbcc')
+    expect(pickerColorHelper.normalizeHex('#abcd')).toBeNull()
+    expect(pickerColorHelper.normalizeHex('blue')).toBeNull()
+    expect(pickerColorHelper.isHex('#aBc')).toBe(true)
+    expect(pickerColorHelper.isHex('aabbcc')).toBe(false)
+    expect(pickerColorHelper.isHex(42)).toBe(false)
+
+    expect(pickerColorHelper.resolve('blue')).toMatchObject({ key: 'blue', custom: false, label: 'Blue', inkDark: '#93C5FD' })
+    expect(pickerColorHelper.resolve('#0F766E')).toMatchObject({ key: '#0f766e', custom: true, label: '#0F766E', swatch: '#0f766e' })
+    expect(pickerColorHelper.resolve('abc')).toBeNull()
+    expect(pickerColorHelper.resolve('nope')).toBeNull()
+    expect(pickerColorHelper.resolve('')).toBeNull()
+    expect(pickerColorHelper.resolve(null)).toBeNull()
+
+    const statuses = [
+      { key: 'neutral', swatch: 'var(--tone-neutral)', ink: 'var(--tone-neutral)', soft: 'var(--tone-neutral-soft)' },
+      { key: 'info', swatch: 'var(--tone-info)', ink: 'var(--tone-info)', soft: 'var(--tone-info-soft)', label: 'In progress' },
+    ]
+    expect(pickerColorHelper.resolve('info', statuses)).toMatchObject({ label: 'In progress', inkDark: 'var(--tone-info)' })
+    expect(pickerColorHelper.styleOf('unknown', statuses)['--pick-ink']).toBe('var(--tone-neutral)')
+    expect(pickerColorHelper.styleOf('unknown')).toEqual({
+      '--pick-swatch': '#64748B', '--pick-ink': '#334155', '--pick-soft': '#F1F5F9',
+      '--pick-ink-dark': '#CBD5E1', '--pick-soft-dark': '#1E293B',
+    })
+    expect(pickerColorHelper.hashKey('card-42')).toBe(pickerColorHelper.hashKey('card-42'))
+    expect(PICKER_COLOR_KEYS).toContain(pickerColorHelper.hashKey('card-42') as typeof PICKER_COLOR_KEYS[number])
+    expect(new Set(Array.from({ length: 200 }, (_, n) => pickerColorHelper.hashKey(`seed-${n}`))).size).toBeGreaterThan(18)
+  })
+
+  test('a custom colour gets inks that keep 4.5:1 on its grounds and the page, in both modes', () => {
+    let seed = 7
+    const random = (): string => {
+      seed = (seed * 1103515245 + 12345) % 2147483648
+
+      return `#${(seed % 0x1000000).toString(16).padStart(6, '0')}`
+    }
+    const samples = [
+      '#ffffff', '#000000', '#ffff00', '#00ff00', '#00ffff', '#0000ff', '#ff0000', '#ff00ff', '#808080',
+      '#3b82f6', '#fde047', '#0f766e', '#111827', '#f5f5f5', '#7f1d1d', ...Array.from({ length: 60 }, random),
+    ]
+    for (const hex of samples) {
+      const color = pickerColorHelper.resolve(hex)
+      expect(color?.custom).toBe(true)
+      const safe = color != null
+        && contrast(color.ink, color.soft) >= 4.5 && contrast(color.ink, '#ffffff') >= 4.5
+        && contrast(color.inkDark, color.softDark) >= 4.5 && contrast(color.inkDark, '#000000') >= 4.5
+      expect({ hex, safe }).toEqual({ hex, safe: true })
+    }
+  })
+})
+
+describe('@owlmeans/web-panel/picker/vocabulary — the icon catalogue', () => {
+  test('entries and components name the same icons; kebab names, known categories, the kit icons included', () => {
+    expect(Object.keys(PICKER_ICONS).sort()).toEqual([...PICKER_ICON_NAMES].sort())
+    expect(new Set(PICKER_ICON_NAMES).size).toBe(PICKER_ICON_NAMES.length)
+    expect(PICKER_ICON_NAMES.length).toBeGreaterThanOrEqual(200)
+    expect(PICKER_ICON_NAMES.every(name => /^[a-z0-9]+(-[a-z0-9]+)*$/.test(name))).toBe(true)
+    expect(PICKER_ICON_ENTRIES.every(entry => entry.keywords.length > 0)).toBe(true)
+    for (const category of PICKER_ICON_CATEGORIES) {
+      expect({ category, icons: PICKER_ICON_ENTRIES.filter(entry => entry.category === category).length >= 15 })
+        .toEqual({ category, icons: true })
+    }
+    expect(KIT_ICONS.filter(name => !PICKER_ICON_NAMES.includes(name))).toEqual([])
+    expect(PICKER_ICON_NAMES).toContain(PICKER_FALLBACK_ICON)
+  })
+
+  test('pickerIconHelper looks up, falls back and searches', () => {
+    expect(pickerIconHelper.iconOf('rocket')).toBe(PICKER_ICONS.rocket)
+    expect(pickerIconHelper.iconOf('no-such-icon')).toBe(PICKER_ICONS[PICKER_FALLBACK_ICON])
+    expect(pickerIconHelper.iconOf(null)).toBe(PICKER_ICONS[PICKER_FALLBACK_ICON])
+    expect(pickerIconHelper.has('truck')).toBe(true)
+    expect(pickerIconHelper.has('toString')).toBe(false)
+
+    expect(pickerIconHelper.search('').length).toBe(PICKER_ICON_NAMES.length)
+    expect(pickerIconHelper.search('Rocket')[0]?.name).toBe('rocket')
+    expect(pickerIconHelper.search('hand').map(entry => entry.name).slice(0, 2)).toEqual(['hand', 'handshake'])
+    expect(pickerIconHelper.search('deal').map(entry => entry.name)).toContain('handshake')
+    expect(pickerIconHelper.search('user check').map(entry => entry.name)).toContain('user-round-check')
+    expect(pickerIconHelper.search('zzzz')).toEqual([])
+    expect(pickerIconHelper.search('', ['truck', 'nope', 'bug']).map(entry => entry.name)).toEqual(['truck', 'bug'])
+    expect(pickerIconHelper.byCategory('places').every(entry => entry.category === 'places')).toBe(true)
+  })
+
+  test('the vocabulary imports nothing outside the picker — no React, no icon set', () => {
+    const roots = [join(import.meta.dir, '../src/picker'), join(import.meta.dir, '../src/picker/vocabulary'),
+      join(import.meta.dir, '../src/picker/utils'), join(import.meta.dir, '../src/picker/utils/color')]
+    const files = [
+      join(roots[0], 'vocabulary.ts'), join(roots[2], 'color.ts'),
+      ...readdirSync(roots[1]).map(file => join(roots[1], file)), ...readdirSync(roots[3]).map(file => join(roots[3], file)),
+    ]
+    for (const file of files) {
+      const specifiers = [...readFileSync(file, 'utf8').matchAll(/from\s+['"]([^'"]+)['"]/g)].map(match => match[1])
+      expect({ file, outside: specifiers.filter(specifier => !specifier.startsWith('.')) }).toEqual({ file, outside: [] })
+    }
+  })
+})

package/tests/picker.spec.ts

@@ -0,0 +1,333 @@
+import { afterAll, describe, expect, test } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { browserHelper, mountComponent } from '@owlmeans/test-ui'
+import type { Page } from '@owlmeans/test-ui'
+import { HARNESS_URL } from './context.js'
+import { PICKER_COLOR_KEYS, PICKER_ICON_CATEGORIES } from '../src/picker/vocabulary.js'
+
+const TIMEOUT = 30_000
+
+afterAll(async () => {
+  await browserHelper.closeBrowser()
+})
+
+const url = (path: string): string => `${HARNESS_URL.replace(/\/$/, '')}${path}`
+const open = async (path: string) => mountComponent({ url: url(path) })
+
+/** A phone: 375px wide, touch, a coarse pointer. */
+const phone = async (path: string) => {
+  const browser = await browserHelper.launchBrowser()
+  const context = await browser.newContext({ viewport: { width: 375, height: 812 }, hasTouch: true, isMobile: true })
+  const page = await context.newPage()
+  await page.goto(url(path), { waitUntil: 'domcontentloaded' })
+
+  return { page, close: () => context.close() }
+}
+
+const mark = async (page: Page): Promise<Record<string, string>> =>
+  JSON.parse(await page.locator('#mark-value').textContent() ?? '{}') as Record<string, string>
+
+const active = (page: Page) => page.evaluate(() => {
+  const element = document.activeElement as HTMLElement | null
+
+  return {
+    trigger: element?.hasAttribute('data-picker-trigger') === true,
+    search: element?.hasAttribute('data-picker-search') === true,
+    icon: element?.getAttribute('data-picker-icon') ?? null,
+    inSurface: element?.closest('[data-picker-surface]') != null,
+  }
+})
+
+/** Focus goes back to the trigger once the surface's focus scope has unmounted — a tick after it detaches. */
+const backOnTrigger = async (page: Page): Promise<boolean> => {
+  await page.waitForFunction(() => document.activeElement?.hasAttribute('data-picker-trigger') === true)
+
+  return (await active(page)).trigger
+}
+
+describe('@owlmeans/web-panel/picker — IconColorPicker on a desktop', () => {
+  test('opens a popover, commits a colour and an icon, searches, and Esc gives focus back', async () => {
+    const { page, close } = await open('/picker')
+    try {
+      const trigger = page.locator('[data-picker-trigger]').first()
+      await trigger.click()
+      const surface = page.locator('[data-picker-surface="popover"]')
+      await surface.waitFor()
+      expect(await surface.locator('[data-picker-swatches] [data-picker-color]').count()).toBe(24)
+      // A fine pointer lands in the search field.
+      expect((await active(page)).search).toBe(true)
+
+      await surface.locator('[data-picker-color="emerald"]').click()
+      expect(await mark(page)).toEqual({ icon: 'rocket', color: 'emerald' })
+      expect(await surface.locator('[data-picker-color="emerald"]').getAttribute('aria-pressed')).toBe('true')
+      // The composite stays open for its other half.
+      expect(await surface.isVisible()).toBe(true)
+
+      await surface.locator('[data-picker-search]').fill('hand')
+      expect(await surface.locator('[data-picker-icon]').first().getAttribute('data-picker-icon')).toBe('hand')
+      expect(await surface.locator('[data-picker-icon="handshake"]').count()).toBe(1)
+      await surface.locator('[data-picker-icon="handshake"]').click()
+      expect(await mark(page)).toEqual({ icon: 'handshake', color: 'emerald' })
+
+      await surface.locator('[data-picker-search]').fill('zzzz')
+      await surface.locator('[data-picker-empty]').waitFor()
+
+      await page.keyboard.press('Escape')
+      await surface.waitFor({ state: 'detached' })
+      expect(await backOnTrigger(page)).toBe(true)
+      expect(await trigger.getAttribute('aria-label')).toBe('Mark: Handshake · Emerald')
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('the keyboard walks the grid: ArrowDown from the search, arrows in two dimensions, Enter picks', async () => {
+    const { page, close } = await open('/picker')
+    try {
+      await page.locator('[data-picker-trigger]').first().click()
+      await page.locator('[data-picker-surface]').waitFor()
+      await page.keyboard.press('ArrowDown')
+      // The selected icon is the grid's tab stop.
+      expect((await active(page)).icon).toBe('rocket')
+      const columns = await page.locator('[data-picker-surface] [data-picker-icon]').evaluateAll(cells => {
+        const top = (cells[0] as HTMLElement).offsetTop
+
+        return cells.filter(cell => (cell as HTMLElement).offsetTop === top).length
+      })
+      expect(columns).toBeGreaterThanOrEqual(8)
+      await page.keyboard.press('ArrowRight')
+      expect((await active(page)).icon).toBe('lightbulb')
+      const before = await page.locator('[data-picker-surface] [data-picker-icon]').evaluateAll(
+        cells => cells.map(cell => cell.getAttribute('data-picker-icon'))
+      )
+      await page.keyboard.press('ArrowDown')
+      expect((await active(page)).icon).toBe(before[before.indexOf('lightbulb') + columns])
+      await page.keyboard.press('Home')
+      expect((await active(page)).icon).toBe('briefcase')
+      await page.keyboard.press('Enter')
+      expect((await mark(page)).icon).toBe('briefcase')
+      // ArrowUp from the first row goes back to the search field.
+      await page.keyboard.press('ArrowUp')
+      expect((await active(page)).search).toBe(true)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('a pick never submits the form, and the parts are plain buttons with names', async () => {
+    const { page, close } = await open('/picker')
+    try {
+      await page.locator('[data-picker-trigger]').nth(1).click()
+      const surface = page.locator('[data-picker-surface]')
+      await surface.waitFor()
+      const buttons = surface.locator('button')
+      expect(await buttons.count()).toBeGreaterThan(20)
+      expect(await surface.locator('button:not([type="button"]), button:not([aria-label])').count()).toBe(0)
+      expect(await page.locator('[data-picker-surface] [data-slot="button"], [data-picker-surface] [data-tone]').count()).toBe(0)
+      expect(await page.locator('[data-picker-trigger][data-slot="button"], [data-picker-trigger][data-tone]').count()).toBe(0)
+      // A single-purpose picker closes on the pick.
+      await surface.locator('[data-picker-color="violet"]').click()
+      await surface.waitFor({ state: 'detached' })
+      expect(await page.locator('#color-value').textContent()).toBe('violet')
+
+      await page.locator('[data-picker-trigger]').nth(2).click()
+      await page.locator('[data-picker-surface] [data-picker-icon="bug"]').click()
+      expect(await page.locator('#icon-value').textContent()).toBe('bug')
+      expect(await page.locator('#submits').textContent()).toBe('0')
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('inside an application\'s own Sheet the popover scrolls with the wheel and keeps focus', async () => {
+    const { page, close } = await open('/picker?inSheet=1')
+    try {
+      await page.locator('#open-sheet').click()
+      const sheet = page.locator('[data-slot="sheet-content"]:not([data-picker-surface])')
+      await sheet.waitFor()
+      await sheet.locator('[data-picker-trigger]').first().click()
+      const surface = page.locator('[data-picker-surface="popover"]')
+      await surface.waitFor()
+      expect((await active(page)).inSurface).toBe(true)
+
+      const body = surface.locator('[data-picker-scroll]')
+      const box = await body.boundingBox()
+      await page.mouse.move((box?.x ?? 0) + (box?.width ?? 0) / 2, (box?.y ?? 0) + (box?.height ?? 0) / 2)
+      await page.mouse.wheel(0, 600)
+      await page.waitForFunction(
+        () => (document.querySelector('[data-picker-surface] [data-picker-scroll]')?.scrollTop ?? 0) > 100
+      )
+      expect((await active(page)).inSurface).toBe(true)
+
+      await surface.locator('[data-picker-icon="truck"]').click()
+      expect((await mark(page)).icon).toBe('truck')
+      await page.keyboard.press('Escape')
+      await surface.waitFor({ state: 'detached' })
+      // Only the picker closed; the application's sheet is still there, focus on the trigger in it.
+      expect(await sheet.isVisible()).toBe(true)
+      expect(await backOnTrigger(page)).toBe(true)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
+describe('@owlmeans/web-panel/picker — on a phone', () => {
+  test('opens a bottom sheet with 44px cells, seven icons a row and a Done button', async () => {
+    const { page, close } = await phone('/picker')
+    try {
+      const trigger = page.locator('[data-picker-trigger]').first()
+      await trigger.waitFor()
+      expect((await trigger.boundingBox())?.height ?? 0).toBeGreaterThanOrEqual(44)
+      await trigger.tap()
+      const surface = page.locator('[data-picker-surface="sheet"]')
+      await surface.waitFor()
+      // No on-screen keyboard: the search field does not take focus on a touch screen.
+      expect((await active(page)).search).toBe(false)
+
+      const sizes = async (selector: string) => surface.locator(selector).evaluateAll(cells => cells.map(cell => {
+        const rect = cell.getBoundingClientRect()
+
+        return { width: rect.width, height: rect.height, top: Math.round(rect.top) }
+      }))
+      const swatches = await sizes('[data-picker-swatches] [data-picker-color]')
+      expect(swatches.every(cell => cell.width >= 44 && cell.height >= 44)).toBe(true)
+      expect(swatches.filter(cell => cell.top === swatches[0].top).length).toBe(6)
+      const icons = await sizes('[data-picker-icon]')
+      expect(icons.every(cell => cell.width >= 44 && cell.height >= 44)).toBe(true)
+      expect(icons.filter(cell => cell.top === icons[0].top).length).toBe(7)
+      const chips = await sizes('[data-picker-category]')
+      expect(chips.every(cell => cell.height >= 44)).toBe(true)
+
+      const done = surface.locator('[data-picker-done]')
+      const doneBox = await done.boundingBox()
+      expect((doneBox?.width ?? 0) >= 44 && (doneBox?.height ?? 0) >= 44).toBe(true)
+      expect(await page.evaluate(() => document.documentElement.scrollWidth)).toBeLessThanOrEqual(375)
+
+      await surface.locator('[data-picker-color="navy"]').tap()
+      expect((await mark(page)).color).toBe('navy')
+      await done.tap()
+      await surface.waitFor({ state: 'detached' })
+      expect(await backOnTrigger(page)).toBe(true)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
+describe('@owlmeans/web-panel/picker — custom colours', () => {
+  test('a valid hex commits normalized; an invalid one is marked and changes nothing', async () => {
+    const { page, close } = await open('/picker?custom=1')
+    try {
+      await page.locator('[data-picker-trigger]').first().click()
+      const surface = page.locator('[data-picker-surface]')
+      await surface.locator('[data-picker-color="custom"]').click()
+      const hex = surface.locator('[data-picker-hex]')
+      await hex.fill('#0F766E')
+      expect((await mark(page)).color).toBe('#0f766e')
+      expect(await surface.locator('[data-picker-color="custom"]').getAttribute('data-selected')).toBe('true')
+      expect(await surface.locator('[data-picker-swatches] [aria-pressed="true"]').count()).toBe(0)
+
+      await hex.fill('#12')
+      await hex.press('Enter')
+      expect(await hex.getAttribute('aria-invalid')).toBe('true')
+      expect((await mark(page)).color).toBe('#0f766e')
+
+      await hex.fill('ABC')
+      await hex.press('Enter')
+      expect(await hex.getAttribute('aria-invalid')).toBeNull()
+      expect((await mark(page)).color).toBe('#aabbcc')
+      expect(await page.locator('#submits').textContent()).toBe('0')
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})
+
+describe('@owlmeans/web-panel/picker — strings', () => {
+  test('renders and opens with no PanelApp and no i18n instance, in English', async () => {
+    const { page, close } = await open('/picker?bare=1')
+    const errors: string[] = []
+    page.on('pageerror', error => errors.push(error.message))
+    try {
+      const trigger = page.locator('[data-picker-trigger]').first()
+      await trigger.click()
+      const surface = page.locator('[data-picker-surface]')
+      await surface.waitFor()
+      expect(await surface.locator('[data-picker-search]').getAttribute('placeholder')).toBe('Search icons…')
+      expect(await surface.locator('[data-picker-category="all"]').textContent()).toBe('All')
+      expect(errors).toEqual([])
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+
+  test('usePickerTranslate reads the packaged bundle in the current language', async () => {
+    const browser = await browserHelper.launchBrowser()
+    const context = await browser.newContext()
+    await context.addInitScript(() => window.localStorage.setItem('owlmeans-lng', 'de'))
+    const page = await context.newPage()
+    try {
+      await page.goto(url('/picker'), { waitUntil: 'domcontentloaded' })
+      // Icon names stay English; colour names and chrome translate.
+      await page.locator('[data-picker-trigger]').nth(1).waitFor()
+      expect(await page.locator('[data-picker-trigger]').nth(1).textContent()).toBe('Petrol')
+      await page.locator('[data-picker-trigger]').first().click()
+      expect(await page.locator('[data-picker-surface] [data-picker-search]').getAttribute('placeholder')).toBe('Symbole suchen…')
+      expect(await page.locator('[data-picker-surface] [data-picker-summary]').textContent()).toBe('Rocket · Indigo')
+    } finally {
+      await context.close()
+    }
+  }, TIMEOUT)
+
+  test('the picker bundle carries the same keys in all eight languages', () => {
+    const dir = join(import.meta.dir, '../src/components/picker/i18n')
+    const keysOf = (value: unknown, prefix = ''): string[] => typeof value === 'object' && value != null
+      ? Object.entries(value).flatMap(([key, child]) => keysOf(child, prefix === '' ? key : `${prefix}.${key}`))
+      : [prefix]
+    const english = JSON.parse(readFileSync(join(dir, 'en.json'), 'utf8')) as Record<string, Record<string, string>>
+    expect(Object.keys(english.colors)).toEqual([...PICKER_COLOR_KEYS])
+    expect(Object.keys(english.categories)).toEqual([...PICKER_ICON_CATEGORIES])
+    for (const language of ['pl', 'ru', 'be', 'uk', 'es', 'de', 'fr']) {
+      const bundle = JSON.parse(readFileSync(join(dir, `${language}.json`), 'utf8')) as unknown
+      expect({ language, keys: keysOf(bundle) }).toEqual({ language, keys: keysOf(english) })
+    }
+  })
+})
+
+describe('@owlmeans/web-panel/picker — light and dark', () => {
+  test('a stored mark follows .dark and the system dark unless .light', async () => {
+    const { page, close } = await open('/picker')
+    try {
+      const tile = page.locator('#samples [data-icon-tile][data-color="blue"]').first()
+      await tile.waitFor()
+      const look = () => tile.evaluate(element => {
+        const style = window.getComputedStyle(element)
+
+        return [style.color, style.backgroundColor]
+      })
+      const dot = () => page.locator('#samples [data-color-dot][data-color="blue"]')
+        .evaluate(element => window.getComputedStyle(element).backgroundColor)
+      const classes = (names: string[]) => page.evaluate(list => {
+        document.documentElement.classList.remove('light', 'dark')
+        document.documentElement.classList.add(...list)
+      }, names)
+      const LIGHT = ['rgb(29, 78, 216)', 'rgb(219, 234, 254)']
+      const DARK = ['rgb(147, 197, 253)', 'rgb(23, 37, 84)']
+
+      expect(await look()).toEqual(LIGHT)
+      expect(await dot()).toBe(LIGHT[0])
+      await classes(['dark'])
+      expect(await look()).toEqual(DARK)
+      expect(await dot()).toBe(DARK[0])
+      await classes([])
+      await page.emulateMedia({ colorScheme: 'dark' })
+      expect(await look()).toEqual(DARK)
+      await classes(['light'])
+      expect(await look()).toEqual(LIGHT)
+    } finally {
+      await close()
+    }
+  }, TIMEOUT)
+})