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

package/src/components/picker/roving.ts

@@ -0,0 +1,70 @@
+import { useCallback, useRef, useState } from 'react'
+import type { KeyboardEvent } from 'react'
+import type { RovingGrid, RovingGridOptions } from './types.local.js'
+
+/** What marks a roving item inside the container. */
+const ITEM = '[data-roving-item]'
+
+/**
+ * Arrow-key focus across the buttons of a grid (or one row): a single tab stop, the arrows move
+ * within it — Left/Right along, Up/Down a whole row (counted from the layout, so it follows
+ * whatever the CSS grid wrapped to), Home/End to the ends. Enter and Space are the buttons' own.
+ */
+export const useRovingGrid = ({ count, selected, onExitUp, grid = true }: RovingGridOptions): RovingGrid => {
+  const ref = useRef<HTMLDivElement | null>(null)
+  const [current, setCurrent] = useState<number | null>(null)
+  const active = Math.min(Math.max(current ?? selected, 0), Math.max(count - 1, 0))
+
+  const items = (): HTMLElement[] => Array.from(ref.current?.querySelectorAll<HTMLElement>(ITEM) ?? [])
+
+  const columnsOf = (list: HTMLElement[]): number => {
+    const top = list[0]?.offsetTop
+    const first = list.findIndex(item => item.offsetTop !== top)
+
+    return first < 0 ? list.length : Math.max(first, 1)
+  }
+
+  const onKeyDown = (event: KeyboardEvent<HTMLElement>): void => {
+    if (event.altKey || event.ctrlKey || event.metaKey) {
+      return
+    }
+    const list = items()
+    const from = list.indexOf(event.target as HTMLElement)
+    if (from < 0) {
+      return
+    }
+    const columns = grid ? columnsOf(list) : list.length
+    const step: Record<string, number> = {
+      ArrowRight: 1, ArrowLeft: -1, ...(grid ? { ArrowDown: columns, ArrowUp: -columns } : {}),
+    }
+    let to: number
+    if (event.key === 'Home') {
+      to = 0
+    } else if (event.key === 'End') {
+      to = list.length - 1
+    } else if (event.key in step) {
+      to = from + step[event.key]
+      if (event.key === 'ArrowUp' && to < 0 && onExitUp != null) {
+        event.preventDefault()
+        onExitUp()
+
+        return
+      }
+      to = Math.min(Math.max(to, 0), list.length - 1)
+    } else {
+      return
+    }
+    event.preventDefault()
+    setCurrent(to)
+    list[to]?.focus()
+  }
+
+  const tabIndexOf = (index: number): number => index === active ? 0 : -1
+
+  const focusCurrent = useCallback(() => {
+    const list = items()
+    ;(list.find(item => item.tabIndex === 0) ?? list[0])?.focus()
+  }, [])
+
+  return { ref, onKeyDown, tabIndexOf, setCurrent, focusCurrent }
+}

package/src/components/picker/surface.tsx

@@ -0,0 +1,62 @@
+import { useRef } from 'react'
+import type { FC } from 'react'
+import { cn } from '../../@/lib/utils.js'
+import { Popover, PopoverAnchor, PopoverContent } from '../../@/components/ui/popover.js'
+import { Sheet, SheetContent, SheetTitle } from '../../@/components/ui/sheet.js'
+import type { PickerSurfaceProps } from './types.local.js'
+import { GRAB, POPOVER, SHEET, TALL } from './consts.local.js'
+
+/**
+ * Where a picker's panel opens: a popover beside the trigger, or a sheet from the bottom edge.
+ *
+ * The popover is MODAL. That is what makes it work inside an application's own Dialog or Sheet:
+ * the topmost scroll lock and focus scope are its own, so the mouse wheel scrolls it and focus stays
+ * in it, where a non-modal one portalled outside the dialog is locked out of both. It keeps 12px off
+ * the viewport's edges and never grows past the space it has (`--radix-popover-content-available-height`),
+ * scrolling inside instead.
+ *
+ * The sheet has no close cross: a grab handle, the panel's own Done button, Esc, or a tap outside
+ * close it. Both surfaces state their own colours (`bg-popover text-popover-foreground`) — they are
+ * portalled to the document body and inherit nothing. Focus goes in on open and back to the trigger
+ * on close, by hand, because the trigger is an anchor rather than a Radix trigger.
+ */
+export const PickerSurface: FC<PickerSurfaceProps> = (
+  { open, onOpenChange, kind, tall, anchor, title, onOpenFocus, onCloseFocus, children }
+) => {
+  const popover = useRef<HTMLDivElement | null>(null)
+  const sheet = useRef<HTMLDivElement | null>(null)
+
+  const focusIn = (content: HTMLDivElement | null) => (event: Event): void => {
+    event.preventDefault()
+    if (content != null) {
+      onOpenFocus(content)
+    }
+  }
+  const focusBack = (event: Event): void => {
+    event.preventDefault()
+    onCloseFocus()
+  }
+
+  return <>
+    <Popover open={open && kind === 'popover'} onOpenChange={onOpenChange} modal>
+      <PopoverAnchor asChild>{anchor}</PopoverAnchor>
+      <PopoverContent
+        ref={popover} data-picker-surface="popover" aria-label={title}
+        align="start" sideOffset={6} collisionPadding={12}
+        onOpenAutoFocus={event => focusIn(popover.current)(event)} onCloseAutoFocus={focusBack}
+        className={cn(POPOVER, tall && TALL.popover)}
+      >{kind === 'popover' && children}</PopoverContent>
+    </Popover>
+    <Sheet open={open && kind === 'sheet'} onOpenChange={onOpenChange}>
+      <SheetContent
+        ref={sheet} side="bottom" showCloseButton={false} aria-describedby={undefined} data-picker-surface="sheet"
+        onOpenAutoFocus={event => focusIn(sheet.current)(event)} onCloseAutoFocus={focusBack}
+        className={cn(SHEET, tall && TALL.sheet)}
+      >
+        <SheetTitle className="sr-only">{title}</SheetTitle>
+        <div aria-hidden="true" className={GRAB} />
+        {kind === 'sheet' && children}
+      </SheetContent>
+    </Sheet>
+  </>
+}

package/src/components/picker/swatches/custom.tsx

@@ -0,0 +1,110 @@
+import { useEffect, useId, useRef, useState } from 'react'
+import type { ChangeEvent, FC, KeyboardEvent } from 'react'
+import { ChevronDownIcon } from 'lucide-react'
+import { HexColorPicker } from 'react-colorful'
+import { cn } from '../../../@/lib/utils.js'
+import { pickerColorHelper } from '../../../picker/vocabulary.js'
+import type { CustomColorProps } from '../types.local.js'
+import {
+  CUSTOM_DISC, CUSTOM_PANEL, CUSTOM_ROW, CUSTOM_START, FIELD, FIELD_ERROR, FULL_HEX, HAIRLINE, HEX_FIELD, RAINBOW,
+  SWATCH_SELECTED, WHEEL_STYLE,
+} from '../consts.local.js'
+
+/**
+ * The opt-in custom colour: a row that opens a colour wheel (react-colorful — accessible sliders,
+ * touch) and a hex field. The wheel commits as it moves, like a native colour input; the field
+ * commits a full `#rrggbb` while typing and a short `#rgb` on Enter or blur, always normalized to
+ * lowercase six digits. Anything else marks the field invalid and changes nothing.
+ */
+export const CustomColor: FC<CustomColorProps> = ({ value, onChange, text }) => {
+  const [open, setOpen] = useState(value != null)
+  const [draft, setDraft] = useState(value?.key ?? '')
+  const [checked, setChecked] = useState(false)
+  const typing = useRef(false)
+  const panelId = useId()
+  const errorId = useId()
+
+  // Follow the committed value, but never under the person's fingers.
+  useEffect(() => {
+    if (!typing.current) {
+      setDraft(value?.key ?? '')
+    }
+  }, [value?.key])
+
+  const normalized = pickerColorHelper.normalizeHex(draft)
+  const invalid = checked && draft.trim() !== '' && normalized == null
+  const label = text.text('custom', 'Custom colour')
+
+  const commit = (hex: string): void => {
+    if (hex !== value?.key) {
+      onChange(hex)
+    }
+  }
+
+  const onText = (event: ChangeEvent<HTMLInputElement>): void => {
+    const next = event.target.value
+    setDraft(next)
+    setChecked(false)
+    const full = FULL_HEX.test(next.trim()) ? pickerColorHelper.normalizeHex(next) : null
+    if (full != null) {
+      commit(full)
+    }
+  }
+
+  const settle = (): void => {
+    setChecked(true)
+    if (normalized != null) {
+      setDraft(normalized)
+      commit(normalized)
+    }
+  }
+
+  const onKey = (event: KeyboardEvent<HTMLInputElement>): void => {
+    if (event.key === 'Enter') {
+      // Never the enclosing form's submit.
+      event.preventDefault()
+      settle()
+    }
+  }
+
+  const onWheel = (hex: string): void => {
+    setDraft(hex)
+    setChecked(false)
+    commit(hex)
+  }
+
+  return <>
+    <button
+      type="button" data-picker-color="custom" data-selected={value != null || undefined}
+      aria-label={value != null ? `${label}: ${value.label}` : label}
+      aria-expanded={open} aria-controls={open ? panelId : undefined}
+      onClick={() => setOpen(!open)} className={CUSTOM_ROW}
+    >
+      <span
+        aria-hidden="true"
+        style={value != null ? pickerColorHelper.styleOf(value.key) : undefined}
+        className={cn(CUSTOM_DISC, HAIRLINE, value != null ? 'bg-(--pick-swatch)' : RAINBOW, value != null && SWATCH_SELECTED)}
+      />
+      <span className="min-w-0 flex-1 truncate">{label}</span>
+      {value != null && <span className="font-mono text-xs text-muted-foreground">{value.label}</span>}
+      <ChevronDownIcon
+        aria-hidden="true"
+        className={cn('size-4 shrink-0 text-muted-foreground transition-transform motion-reduce:transition-none', open && 'rotate-180')}
+      />
+    </button>
+    {open && <div id={panelId} className={CUSTOM_PANEL}>
+      <HexColorPicker color={normalized ?? value?.key ?? CUSTOM_START} onChange={onWheel} style={WHEEL_STYLE} />
+      <input
+        data-picker-hex type="text" inputMode="text" autoComplete="off" autoCapitalize="off" spellCheck={false}
+        enterKeyHint="done" maxLength={7} placeholder={CUSTOM_START}
+        aria-label={text.text('hex', 'Hex colour')} aria-invalid={invalid || undefined}
+        aria-describedby={invalid ? errorId : undefined}
+        value={draft} onChange={onText} onKeyDown={onKey}
+        onFocus={() => { typing.current = true }}
+        onBlur={() => { typing.current = false; settle() }}
+        className={cn(FIELD, HEX_FIELD)}
+      />
+      {invalid && <p id={errorId} className={FIELD_ERROR}>{text.text('invalidHex', 'Enter a colour like #3b82f6')}</p>}
+    </div>}
+  </>
+}

package/src/components/picker/swatches.tsx

@@ -0,0 +1,67 @@
+import { useMemo } from 'react'
+import type { FC } from 'react'
+import { cn } from '../../@/lib/utils.js'
+import { pickerColorHelper } from '../../picker/vocabulary.js'
+import { PICKER_COLORS } from '../../picker/vocabulary/consts.js'
+import type { ColorSwatchesProps } from './types.js'
+import type { SwatchGridProps } from './types.local.js'
+import { CustomColor } from './swatches/custom.js'
+import { useRovingGrid } from './roving.js'
+import { makePickerText } from './text.js'
+import { PICK_SCOPE, SWATCH, SWATCH_DISC, SWATCH_SELECTED, SWATCHES } from './consts.local.js'
+
+/**
+ * The swatch grid every picker shares, laid out for its surface: twelve to a row in a popover,
+ * as many 44px cells as fit in a sheet or below 768px. One tab stop; the arrows move in two
+ * dimensions. A swatch is a `<button type="button">` named by its colour and pressed while chosen.
+ */
+export const SwatchGrid: FC<SwatchGridProps> = (
+  { value, onChange, onCustomChange, colors, customColors, text, layout, label, className }
+) => {
+  const resolved = pickerColorHelper.resolve(value, colors)
+  const selected = resolved == null || resolved.custom ? -1 : colors.findIndex(color => color.key === resolved.key)
+  const roving = useRovingGrid({ count: colors.length, selected })
+
+  return <div className={className}>
+    <div
+      ref={roving.ref} role="group" aria-label={label} onKeyDown={roving.onKeyDown}
+      data-picker-swatches className={SWATCHES[layout]}
+    >
+      {colors.map((color, index) => {
+        const named = pickerColorHelper.resolve(color.key, colors)
+        const name = named != null ? text.color(named) : color.key
+        const chosen = index === selected
+
+        return <button
+          key={color.key} type="button" data-roving-item data-picker-color={color.key}
+          aria-label={name} aria-pressed={chosen} title={name}
+          tabIndex={roving.tabIndexOf(index)} onFocus={() => roving.setCurrent(index)}
+          onClick={() => onChange(color.key)}
+          style={pickerColorHelper.styleOf(color.key, colors)}
+          className={cn(PICK_SCOPE, SWATCH)}
+        >
+          <span aria-hidden="true" className={cn(SWATCH_DISC, chosen && SWATCH_SELECTED)} />
+        </button>
+      })}
+    </div>
+    {customColors && <CustomColor
+      value={resolved?.custom === true ? resolved : null} onChange={onCustomChange ?? onChange} text={text}
+    />}
+  </div>
+}
+
+/**
+ * The colour swatches inline — for a dialog or sheet the application already owns. Commits on
+ * click; `customColors` adds the colour wheel and hex field. Strings through `translate` (English
+ * without it — never an implicit i18n read).
+ */
+export const ColorSwatches: FC<ColorSwatchesProps> = (
+  { value, onChange, colors = PICKER_COLORS, customColors = false, translate, label, className }
+) => {
+  const text = useMemo(() => makePickerText(translate), [translate])
+
+  return <SwatchGrid
+    value={value} onChange={onChange} colors={colors} customColors={customColors} text={text} layout="inline"
+    label={label ?? text.text('color', 'Colour')} className={className}
+  />
+}

package/src/components/picker/text.ts

@@ -0,0 +1,46 @@
+import { PICKER_COLORS } from '../../picker/vocabulary/consts.js'
+import type { PickerIconCategory, ResolvedPickerColor } from '../../picker/vocabulary/types.js'
+import type { PickerTranslate } from './types.js'
+import type { PickerMode, PickerText } from './types.local.js'
+
+const english: PickerTranslate = (_key, fallback) => fallback
+
+const humanize = (name: string): string => {
+  const words = name.replace(/-/g, ' ')
+
+  return words === '' ? name : words[0].toUpperCase() + words.slice(1)
+}
+
+/** Every string a picker shows, through one `translate` (English without one). Built once per render. */
+export const makePickerText = (translate: PickerTranslate = english): PickerText => {
+  const text = (key: string, fallback: string): string => translate(key, fallback)
+
+  // Only the palette's own names translate; an application palette's labels are shown as given
+  // (a status palette may well have a key called `red` labelled "Blocked").
+  const color = (resolved: ResolvedPickerColor): string =>
+    !resolved.custom && PICKER_COLORS.some(entry => entry.key === resolved.key && entry.label === resolved.label)
+      ? translate(`colors.${resolved.key}`, resolved.label)
+      : resolved.label
+
+  const icon = (name: string): string => humanize(name)
+
+  const category = (value: PickerIconCategory): string => translate(`categories.${value}`, humanize(value))
+
+  // Filled after translation: a `{count}` placeholder is never one i18next interpolates or strips.
+  const count = (value: number): string => translate('results', 'Icons found: {count}').replace('{count}', String(value))
+
+  const empty = (query: string): string => translate('empty', 'No icons match “{query}”').replace('{query}', query)
+
+  const summary = (
+    iconName: string | null | undefined, resolved: ResolvedPickerColor | null, mode: PickerMode
+  ): string | null => {
+    const parts = [
+      mode !== 'color' && iconName != null && iconName !== '' ? icon(iconName) : null,
+      mode !== 'icon' && resolved != null ? color(resolved) : null,
+    ].filter((part): part is string => part != null)
+
+    return parts.length > 0 ? parts.join(' · ') : null
+  }
+
+  return { text, color, icon, category, count, empty, summary }
+}

package/src/components/picker/tile.tsx

@@ -0,0 +1,35 @@
+import type { FC } from 'react'
+import { cn } from '../../@/lib/utils.js'
+import { pickerIconHelper } from '../../picker/icons.js'
+import { pickerColorHelper } from '../../picker/vocabulary.js'
+import { PICKER_FALLBACK_ICON } from '../../picker/vocabulary/consts.js'
+import type { IconTileProps } from './types.js'
+import { PICK_SCOPE, PLAIN, PLAIN_SIZE, TILE, TILE_SIZE } from './consts.local.js'
+
+/**
+ * A stored mark rendered — the way a list, a chip or a header shows what a person chose.
+ *
+ * `tile` puts the icon in the colour's ink on the colour's ground; `plain` is the ink alone. Both
+ * follow the page's scheme on their own (`.dark`, or the system's dark unless `.light`). An unknown
+ * icon renders the fallback circle and an unknown colour slate — a stored value never breaks a page.
+ */
+export const IconTile: FC<IconTileProps> = (
+  { icon, color, colors, size = 'md', variant = 'tile', label, className, style }
+) => {
+  const Icon = pickerIconHelper.iconOf(icon)
+  const resolved = pickerColorHelper.resolve(color, colors)
+
+  return <span
+    data-icon-tile={variant}
+    data-icon={pickerIconHelper.has(icon) ? icon : PICKER_FALLBACK_ICON}
+    data-color={resolved?.key}
+    role={label != null ? 'img' : undefined}
+    aria-label={label}
+    aria-hidden={label != null ? undefined : true}
+    title={label}
+    style={{ ...pickerColorHelper.styleOf(color, colors), ...style }}
+    className={cn(PICK_SCOPE, variant === 'tile' ? TILE : PLAIN, variant === 'tile' ? TILE_SIZE[size] : PLAIN_SIZE[size], className)}
+  >
+    <Icon aria-hidden="true" />
+  </span>
+}

package/src/components/picker/translate.ts

@@ -0,0 +1,15 @@
+import { useCallback } from 'react'
+import { useI18nLib } from '@owlmeans/client-i18n'
+import type { PickerTranslate } from './types.js'
+
+/**
+ * A `translate` reading the picker's own library bundle (`lib:picker`, eight languages) in the
+ * current language — what an application rendered by `PanelApp` / `render()` passes to every picker
+ * part. It needs that i18n instance: called anywhere without one it throws inside render, which is
+ * exactly why no picker part calls it by itself. Missing keys fall back to the English text.
+ */
+export const usePickerTranslate = (): PickerTranslate => {
+  const t = useI18nLib('picker')
+
+  return useCallback<PickerTranslate>((key, fallback) => t(key, { defaultValue: fallback }), [t])
+}

package/src/components/picker/trigger.tsx

@@ -0,0 +1,54 @@
+import type { FC } from 'react'
+import { ChevronDownIcon, PlusIcon } from 'lucide-react'
+import { cn } from '../../@/lib/utils.js'
+import { pickerColorHelper } from '../../picker/vocabulary.js'
+import type { PickerTriggerProps } from './types.local.js'
+import { IconTile } from './tile.js'
+import {
+  CHEVRON, HAIRLINE, TRIGGER_BUTTON, TRIGGER_COMPACT, TRIGGER_DISC, TRIGGER_DOT, TRIGGER_EMPTY,
+} from './consts.local.js'
+
+/**
+ * What opens a picker: a field-like button (the mark, its names, a chevron) or the mark alone.
+ *
+ * It is the popover's anchor and stays mounted in one place whichever surface opens, so focus has
+ * one element to return to. Its accessible name is the label and the current choice ("Mark:
+ * Rocket · Indigo"); it carries `data-picker-trigger`, never `data-slot="button"` or `data-tone`.
+ * Extra props — the popover anchor's — land on the button.
+ */
+export const PickerTrigger: FC<PickerTriggerProps> = ({
+  ref, mode, variant, icon, color, colors, text, label, placeholder, open, disabled, id, className, onOpen, ...anchor
+}) => {
+  const resolved = pickerColorHelper.resolve(color, colors)
+  const summary = text.summary(icon, resolved, mode)
+  const name = label != null && label !== '' ? `${label}: ${summary ?? placeholder}` : summary ?? placeholder
+  const empty = summary == null
+
+  const mark = mode === 'color'
+    ? empty
+      ? <span aria-hidden="true" className={cn(TRIGGER_EMPTY, 'rounded-full', variant === 'dot' && 'size-5')} />
+      : <span
+        aria-hidden="true" style={pickerColorHelper.styleOf(color, colors)}
+        className={cn(TRIGGER_DISC, HAIRLINE, variant === 'dot' && 'size-5')}
+      />
+    : empty
+      ? <span aria-hidden="true" className={cn(TRIGGER_EMPTY, variant === 'tile' && 'size-full rounded-lg')}><PlusIcon /></span>
+      : <IconTile icon={icon} color={color} colors={colors} size={variant === 'tile' ? 'md' : 'sm'} className={variant === 'tile' ? 'size-full' : undefined} />
+
+  return <button
+    {...anchor}
+    ref={ref} type="button" id={id} disabled={disabled}
+    data-picker-trigger={variant} aria-haspopup="dialog" aria-expanded={open} aria-label={name}
+    title={variant === 'button' ? undefined : name}
+    onClick={onOpen}
+    className={cn(
+      variant === 'button' ? TRIGGER_BUTTON : TRIGGER_COMPACT, variant === 'dot' && TRIGGER_DOT, className
+    )}
+  >
+    {variant === 'button' && mode === 'color' ? <span className="inline-flex size-7 shrink-0 items-center justify-center">{mark}</span> : mark}
+    {variant === 'button' && <>
+      <span className={cn('min-w-0 flex-1 truncate', empty && 'text-muted-foreground')}>{summary ?? placeholder}</span>
+      <ChevronDownIcon aria-hidden="true" className={CHEVRON} />
+    </>}
+  </button>
+}

package/src/components/picker/types.local.ts

@@ -0,0 +1,154 @@
+import type { ComponentProps, KeyboardEvent, ReactElement, ReactNode, Ref, RefObject } from 'react'
+import type { PickerColor, PickerIconCategory, ResolvedPickerColor } from '../../picker/vocabulary/types.js'
+import type { PickerTranslate } from './types.js'
+
+/** Where a panel is laid out — it decides cell sizes and paddings. */
+export type PickerLayout = 'popover' | 'sheet' | 'inline'
+
+/** Which halves a picker edits. */
+export type PickerMode = 'both' | 'icon' | 'color'
+
+/** Every string a picker shows, resolved through one `translate`. */
+export interface PickerText {
+  /** A chrome string by key, English fallback. */
+  text: (key: string, fallback: string) => string
+  /** A colour's name: a palette name through `colors.<key>`, a custom colour's hex as is. */
+  color: (color: ResolvedPickerColor) => string
+  /** An icon's name — the kebab name humanized; icon names are never translated. */
+  icon: (name: string) => string
+  category: (category: PickerIconCategory) => string
+  /** "Icons found: 12" for the live region. */
+  count: (count: number) => string
+  /** "No icons match …". */
+  empty: (query: string) => string
+  /** "Rocket · Indigo", or `null` while nothing is chosen. */
+  summary: (icon: string | null | undefined, color: ResolvedPickerColor | null, mode: PickerMode) => string | null
+}
+
+/** Arrow-key focus across a grid of buttons; only one of them is in the tab order. */
+export interface RovingGrid {
+  ref: RefObject<HTMLDivElement | null>
+  onKeyDown: (event: KeyboardEvent<HTMLElement>) => void
+  /** `0` for the one item in the tab order, `-1` for the rest. */
+  tabIndexOf: (index: number) => number
+  /** Remember an item as the current one (it took focus). */
+  setCurrent: (index: number) => void
+  /** Focus the current item. */
+  focusCurrent: () => void
+}
+
+export interface RovingGridOptions {
+  count: number
+  /** The item that starts in the tab order — the selected one. */
+  selected: number
+  /** ArrowUp from the first row: hand focus back (the search field above a grid). */
+  onExitUp?: () => void
+  /** `false` — one row, Left/Right only. */
+  grid?: boolean
+}
+
+export interface SwatchGridProps {
+  value?: string | null
+  /** A swatch was pressed. */
+  onChange: (color: string) => void
+  /** The custom wheel or hex field changed; default `onChange`. A picker that closes on a pick keeps this open. */
+  onCustomChange?: (color: string) => void
+  colors: readonly PickerColor[]
+  customColors: boolean
+  text: PickerText
+  layout: PickerLayout
+  label: string
+  className?: string
+}
+
+export interface CustomColorProps {
+  /** The current value when it is a custom colour, else `null`. */
+  value: ResolvedPickerColor | null
+  onChange: (color: string) => void
+  text: PickerText
+}
+
+export interface IconBrowserProps {
+  value?: string | null
+  onChange: (icon: string) => void
+  color?: string | null
+  colors: readonly PickerColor[]
+  icons?: readonly string[]
+  text: PickerText
+  layout: PickerLayout
+  label: string
+  /** The search field — the surface focuses it on open for a fine pointer. */
+  searchRef?: Ref<HTMLInputElement>
+  className?: string
+}
+
+export interface PickerPanelProps {
+  mode: PickerMode
+  icon?: string | null
+  color?: string | null
+  onIcon: (icon: string) => void
+  /** A swatch was pressed. */
+  onColor: (color: string) => void
+  /** The custom wheel or hex field changed. */
+  onCustomColor: (color: string) => void
+  colors: readonly PickerColor[]
+  icons?: readonly string[]
+  customColors: boolean
+  text: PickerText
+  layout: 'popover' | 'sheet'
+  title: string
+  /** The sheet's Done button; the popover has none. */
+  onDone?: () => void
+  searchRef: Ref<HTMLInputElement>
+}
+
+export interface PickerSurfaceProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  kind: 'popover' | 'sheet'
+  /** Holds an icon grid — keep one height so filtering never makes the surface jump. */
+  tall: boolean
+  /** The trigger — the popover's anchor, kept in the same place in the tree for both surfaces. */
+  anchor: ReactElement
+  title: string
+  /** Focus on open (the search field for a fine pointer, the selected cell otherwise). */
+  onOpenFocus: (content: HTMLElement) => void
+  /** Focus back on the trigger once closed. */
+  onCloseFocus: () => void
+  children: ReactNode
+}
+
+/** The trigger's own props; anything else (the popover anchor's) lands on the button. */
+export interface PickerTriggerProps extends Omit<ComponentProps<'button'>, 'color' | 'onClick' | 'type' | 'children'> {
+  mode: PickerMode
+  variant: 'button' | 'tile' | 'dot'
+  icon?: string | null
+  color?: string | null
+  colors: readonly PickerColor[]
+  text: PickerText
+  label?: string
+  placeholder: string
+  open: boolean
+  onOpen: () => void
+}
+
+export interface PickerRootProps {
+  mode: PickerMode
+  icon?: string | null
+  color?: string | null
+  onIcon: (icon: string) => void
+  onColor: (color: string) => void
+  colors?: readonly PickerColor[]
+  icons?: readonly string[]
+  customColors?: boolean
+  trigger: 'button' | 'tile' | 'dot'
+  /** A single-purpose picker closes once something is picked; the composite stays for the other half. */
+  closeOnPick: boolean
+  label?: string
+  placeholder?: string
+  disabled?: boolean
+  surface?: 'auto' | 'popover' | 'sheet'
+  translate?: PickerTranslate
+  className?: string
+  id?: string
+}