@oneli8/react 1.0.0-beta.5 → 1.0.0-beta.6

package/src/molecules/FormMessage.js

@@ -0,0 +1,33 @@
+import { createElement, forwardRef } from 'react';
+import { OL8_FORM_MESSAGE_TONES, OL8_FORM_MESSAGE_ICONS } from '../foundations/geometry.js';
+import { Icon } from '../atoms/Icon.js';
+
+/**
+ * MOLECULE. Figma 177:13: "Tone maps to semantic message tone; Pending is
+ * resolved through validationStatus rather than treated as a fifth error tone.
+ * Runtime role, status announcement and relationships live in code."
+ *
+ * So the role and the live region are decided here, from the tone: critical is
+ * the only tone that interrupts, because it is the only one that stops a person
+ * from finishing.
+ */
+export const FormMessage = forwardRef(function FormMessage({
+  children, tone = 'critical', icon = true, className = '', ...rest
+}, ref) {
+  if (!OL8_FORM_MESSAGE_TONES.includes(tone)) {
+    throw new Error(`[ol8] unknown form message tone "${tone}"`);
+  }
+
+  return createElement('div', {
+    ...rest, ref,
+    className: `ol8-form-message${className ? ` ${className}` : ''}`,
+    'data-ol8-tone': tone,
+    role: tone === 'critical' ? 'alert' : 'status',
+    'aria-live': tone === 'critical' ? 'assertive' : 'polite',
+  },
+    icon
+      ? createElement(Icon, { key: 'icon', name: OL8_FORM_MESSAGE_ICONS[tone], size: 18, className: 'ol8-form-message__icon' })
+      : null,
+    createElement('span', { key: 'text', className: 'ol8-form-message__text' }, children),
+  );
+});

package/src/molecules/Link.js

@@ -0,0 +1,31 @@
+import { createElement, forwardRef } from 'react';
+import { OL8_LINK_FORMS, OL8_LINK_SIZES, OL8_LINK_MOTIONS } from '../foundations/geometry.js';
+
+/**
+ * MOLECULE. Figma's five States are visual evidence for review, never props:
+ * :hover, :active, :focus-visible, :visited and [aria-current] carry them.
+ * Icons are intentionally parked and must not be added as local artwork.
+ */
+export const Link = forwardRef(function Link({
+  children, href, form = 'inline', size = 'standard', current, motion = 'system',
+  className = '', ...rest
+}, ref) {
+  if (!OL8_LINK_FORMS.includes(form)) throw new Error(`[ol8] unknown link form "${form}"`);
+  if (!OL8_LINK_SIZES.includes(size)) throw new Error(`[ol8] unknown link size "${size}"`);
+  if (!OL8_LINK_MOTIONS.includes(motion)) throw new Error(`[ol8] unknown link motion "${motion}"`);
+  if (typeof href !== 'string' || href === '') {
+    throw new Error('[ol8] Link requires an href. A link without a destination is a button.');
+  }
+  if (current !== undefined && form !== 'navigation') {
+    throw new Error('[ol8] aria-current belongs to a navigation link, not an inline or standalone one.');
+  }
+
+  return createElement('a', {
+    ...rest, ref, href,
+    className: `ol8-link${className ? ` ${className}` : ''}`,
+    'data-ol8-form': form,
+    'data-ol8-size': size,
+    ...(motion === 'none' ? { 'data-ol8-motion': 'none' } : {}),
+    ...(current ? { 'aria-current': current === true ? 'page' : String(current) } : {}),
+  }, children);
+});

package/src/molecules/NavigationItem.js

@@ -0,0 +1,55 @@
+import { createElement, forwardRef } from 'react';
+import { Icon } from '../atoms/Icon.js';
+import { NavigationBadge } from '../atoms/NavigationBadge.js';
+
+/**
+ * The shared internal molecule behind Tabs, Segmented Control and Tab Bar.
+ * Figma draws it three times (688:51, 695:167, 700:292); it is one molecule
+ * with three selection languages. The navigation contract keeps it internal, so
+ * it is not exported from the package index.
+ */
+export const NavigationItem = forwardRef(function NavigationItem({
+  kind, label, icon, badge, layout = 'inline', size = 'standard',
+  selected = false, disabled = false, ariaLabel, href, ...rest
+}, ref) {
+  if (!label && !icon) throw new Error('[ol8] a navigation item needs a label, an icon, or both.');
+  if (!label && !ariaLabel) {
+    throw new Error('[ol8] an icon only navigation item requires an ariaLabel, since a glyph is not a name.');
+  }
+  if (kind === 'destination' && disabled) {
+    throw new Error('[ol8] a destination cannot be disabled. A place a person cannot go does not belong in navigation.');
+  }
+
+  const content = createElement('span', { className: 'ol8-nav-item__content' },
+    icon ? createElement(Icon, { key: 'i', name: icon, size: 18, className: 'ol8-nav-item__icon' }) : null,
+    label ? createElement('span', { key: 'l', className: 'ol8-nav-item__label' }, label) : null,
+    badge !== undefined && badge !== null && badge !== ''
+      ? createElement(NavigationBadge, { key: 'b' }, badge) : null,
+  );
+
+  const shared = {
+    ...rest, ref,
+    className: `ol8-nav-item ol8-nav-item--${kind}`,
+    'data-ol8-layout': layout,
+    'data-ol8-size': size,
+    'aria-label': ariaLabel,
+  };
+
+  if (kind === 'destination') {
+    if (typeof href !== 'string' || href === '') {
+      throw new Error('[ol8] a destination requires an href. Tab Bar navigates, so it uses real links.');
+    }
+    return createElement('a', { ...shared, href, 'aria-current': selected ? 'page' : undefined }, content);
+  }
+
+  return createElement('button', {
+    ...shared, type: 'button', disabled,
+    ...(kind === 'tab'
+      ? { role: 'tab', 'aria-selected': selected }
+      : { 'aria-pressed': selected }),
+  },
+    content,
+    // Always present, so selecting does not change the box.
+    kind === 'tab' ? createElement('span', { key: 'ind', className: 'ol8-nav-item__indicator', 'aria-hidden': 'true' }) : null,
+  );
+});

package/src/molecules/Select.js

@@ -0,0 +1,109 @@
+import { createElement, forwardRef, useId } from 'react';
+import { OL8_TEXT_FIELD_SIZES, OL8_TEXT_FIELD_APPEARANCES, OL8_TEXT_FIELD_MATERIALS, OL8_MESSAGE_TONES } from '../foundations/geometry.js';
+import { Icon } from '../atoms/Icon.js';
+import { FormMessage } from './FormMessage.js';
+
+/** "native='preferred' | 'required' | 'custom-allowed'", default preferred. */
+export const OL8_SELECT_NATIVE_POLICIES = ['preferred', 'required', 'custom-allowed'];
+
+/**
+ * MOLECULE. Figma 583:338 Trigger, 875:1778 Select.
+ *
+ * "Geometry and appearance reuse approved Text Field tokens", and Figma proves
+ * it: every bound variable on the trigger is a Text Field one. So Select wears
+ * the field's own classes.
+ *
+ * The contract is native first: "ordinary Select uses a labelled native select
+ * whenever its option and appearance requirements fit native behavior", and "a
+ * native control is not replaced merely to force pixel identity". This renders
+ * a real select, so the platform keeps the keyboard, the type ahead, the picker
+ * and the announcements.
+ */
+export const Select = forwardRef(function Select({
+  label, options = [], id, size = 'comfortable', appearance = 'outline', material = 'regular',
+  showLabel = true, required = false, disabled = false, invalid = false,
+  placeholderOption, leadingIcon, instruction, message, messageTone = 'critical',
+  native = 'preferred', className = '', ...rest
+}, ref) {
+  if (typeof label !== 'string' || label === '') {
+    throw new Error('[ol8] Select requires a label. A placeholder is never the label.');
+  }
+  if (!Array.isArray(options) || options.length === 0) throw new Error('[ol8] Select needs at least one option.');
+  if (!OL8_TEXT_FIELD_SIZES.includes(size)) throw new Error(`[ol8] unknown select size "${size}"`);
+  if (!OL8_TEXT_FIELD_APPEARANCES.includes(appearance)) throw new Error(`[ol8] unknown select appearance "${appearance}"`);
+  if (!OL8_TEXT_FIELD_MATERIALS.includes(material)) throw new Error(`[ol8] unknown select material "${material}"`);
+  if (!OL8_MESSAGE_TONES.includes(messageTone)) throw new Error(`[ol8] unknown message tone "${messageTone}"`);
+  if (!OL8_SELECT_NATIVE_POLICIES.includes(native)) throw new Error(`[ol8] unknown native policy "${native}"`);
+  if (native === 'custom-allowed') {
+    throw new Error('[ol8] a custom select is justified only when the product needs behaviour native Select cannot provide, and only with the complete focus, keyboard, announcement, form, mobile and forced colour contract implemented. Use Combobox, which implements it.');
+  }
+
+  const generated = useId();
+  const selectId = id ?? generated;
+  const instructionId = instruction ? `${selectId}-instruction` : undefined;
+  const messageId = message ? `${selectId}-message` : undefined;
+  const describedBy = [instructionId, messageId].filter(Boolean).join(' ') || undefined;
+
+  // Grouped options keep their source order, the way the popup groups do.
+  const groups = [];
+  for (const option of options) {
+    const name = option.group ?? null;
+    const last = groups[groups.length - 1];
+    if (last && last.name === name) last.items.push(option);
+    else groups.push({ name, items: [option] });
+  }
+  const renderOption = (option) => createElement('option', {
+    key: option.value, value: option.value, disabled: option.disabled,
+  }, option.label);
+
+  return createElement('div', {
+    className: `ol8-field ol8-select${className ? ` ${className}` : ''}`,
+    'data-ol8-size': size,
+    'data-ol8-appearance': appearance,
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+    ...(disabled ? { 'data-ol8-disabled': 'true' } : {}),
+    ...(invalid ? { 'data-ol8-invalid': 'true' } : {}),
+  },
+    showLabel
+      ? createElement('div', { key: 'label-row', className: 'ol8-field__label-row' },
+          createElement('label', { key: 'l', className: 'ol8-field__label', htmlFor: selectId }, label),
+          required ? createElement('span', { key: 'r', className: 'ol8-field__requirement', 'aria-hidden': 'true' }, '*') : null,
+        )
+      : null,
+
+    createElement('div', { key: 'stack', className: 'ol8-field__control-stack' },
+      createElement('div', { className: 'ol8-field__control' },
+        leadingIcon ? createElement(Icon, { key: 'i', name: leadingIcon, size: 18, className: 'ol8-field__leading-icon' }) : null,
+        createElement('select', {
+          key: 'select', ...rest, ref,
+          id: selectId,
+          className: 'ol8-field__input ol8-select__input',
+          required, disabled,
+          'aria-label': showLabel ? undefined : label,
+          'aria-invalid': invalid || undefined,
+          'aria-errormessage': invalid ? messageId : undefined,
+          'aria-describedby': describedBy,
+        },
+          // "placeholderOption only when an unselected value is valid or
+          // required validation needs an explicit prompt."
+          placeholderOption
+            ? createElement('option', { key: '__placeholder', value: '', disabled: required }, placeholderOption)
+            : null,
+          groups.map((group, index) => group.name
+            ? createElement('optgroup', { key: `g${index}`, label: group.name }, group.items.map(renderOption))
+            : group.items.map(renderOption)),
+        ),
+        // Decoration: the native control already tells a screen reader it opens a list.
+        createElement(Icon, { key: 'disclosure', name: 'chevron-down', size: 18, className: 'ol8-select__disclosure' }),
+      ),
+    ),
+
+    instruction
+      ? createElement('div', { key: 'instruction', className: 'ol8-field__instruction', id: instructionId }, instruction)
+      : null,
+    message
+      ? createElement('div', { key: 'supporting', className: 'ol8-field__supporting' },
+          createElement(FormMessage, { tone: messageTone, id: messageId }, message))
+      : null,
+  );
+});

package/src/molecules/SelectionOption.js

@@ -16,7 +16,10 @@ export function SelectionOption({
   const optionId = id ?? `ol8-option-${auto}`;
   const labelId = `${optionId}-label`;
   const descId = description ? `${optionId}-desc` : undefined;
-  return createElement('li', {
+  // A div, not an li: the popup rail is a div with role="listbox", and an li
+  // outside a list is invalid markup. The core renderer has always emitted a
+  // div here; this had drifted.
+  return createElement('div', {
     ...rest,
     className: `ol8-option${className ? ` ${className}` : ''}`,
     role: 'option', id: optionId,

package/src/molecules/TextField.js

@@ -0,0 +1,174 @@
+import { createElement, forwardRef, useCallback, useId, useRef } from 'react';
+import {
+  OL8_TEXT_FIELD_SIZES, OL8_TEXT_FIELD_APPEARANCES, OL8_TEXT_FIELD_MATERIALS,
+  OL8_MESSAGE_TONES, OL8_VALIDATION_STATUSES, OL8_CHARACTER_LIMIT_BEHAVIORS,
+} from '../foundations/geometry.js';
+import { Icon } from '../atoms/Icon.js';
+import { FormMessage } from './FormMessage.js';
+
+/**
+ * MOLECULE. Figma 182:33 Outline, 186:53 Filled, 211:36 and 215:226 Gem.
+ *
+ * Figma's five Conditions are review evidence, never props. They arrive here as
+ * :hover, aria-invalid, readOnly and disabled on the native input, which is also
+ * what carries type, value, autofill, IME, undo and dictation.
+ *
+ * Gem is a material adapter. It changes token bound material and nothing else.
+ */
+export const TextField = forwardRef(function TextField({
+  label, id, size = 'comfortable', appearance = 'outline', material = 'regular',
+  showLabel = true, required = false, disabled = false, readOnly = false, invalid = false,
+  leadingIcon, prefix, suffix, trailingAction,
+  instruction, message, messageTone = 'critical', messageIcon = true,
+  validationStatus = 'idle', characterLimit, characterLimitBehavior = 'soft',
+  value, defaultValue, onChange, className = '', ...rest
+}, ref) {
+  if (typeof label !== 'string' || label === '') {
+    throw new Error('[ol8] Text Field requires a label. A placeholder is never the label.');
+  }
+  if (!OL8_TEXT_FIELD_SIZES.includes(size)) throw new Error(`[ol8] unknown text field size "${size}"`);
+  if (!OL8_TEXT_FIELD_APPEARANCES.includes(appearance)) throw new Error(`[ol8] unknown text field appearance "${appearance}"`);
+  if (!OL8_TEXT_FIELD_MATERIALS.includes(material)) throw new Error(`[ol8] unknown text field material "${material}"`);
+  if (!OL8_MESSAGE_TONES.includes(messageTone)) {
+    throw new Error(`[ol8] unknown message tone "${messageTone}". Pending is a validationStatus, not a tone.`);
+  }
+  if (!OL8_VALIDATION_STATUSES.includes(validationStatus)) {
+    throw new Error(`[ol8] unknown validation status "${validationStatus}"`);
+  }
+  if (!OL8_CHARACTER_LIMIT_BEHAVIORS.includes(characterLimitBehavior)) {
+    throw new Error(`[ol8] unknown character limit behavior "${characterLimitBehavior}"`);
+  }
+  if (characterLimit !== undefined && (!Number.isInteger(characterLimit) || characterLimit <= 0)) {
+    throw new Error('[ol8] characterLimit counts graphemes, so it must be a positive whole number.');
+  }
+  if (readOnly && invalid) {
+    throw new Error('[ol8] a read only field cannot be invalid. If a person cannot correct the value, the problem belongs to system feedback rather than to an editable field error.');
+  }
+
+  const generated = useId();
+  const fieldId = id ?? generated;
+  const instructionId = instruction ? `${fieldId}-instruction` : undefined;
+  const messageId = message ? `${fieldId}-message` : undefined;
+  const counterId = characterLimit !== undefined ? `${fieldId}-counter` : undefined;
+  const describedBy = [instructionId, messageId, counterId].filter(Boolean).join(' ') || undefined;
+
+  const inputRef = useRef(null);
+  const attach = useCallback((node) => {
+    inputRef.current = node;
+    if (typeof ref === 'function') ref(node);
+    else if (ref) ref.current = node;
+  }, [ref]);
+
+  // "Clicking or tapping anywhere inside the control frame focuses the native
+  // input, except an independent trailing action."
+  const focusInput = useCallback((event) => {
+    if (event.target === inputRef.current) return;
+    if (event.target.closest?.('.ol8-field__trailing-action')) return;
+    event.preventDefault();
+    inputRef.current?.focus();
+  }, []);
+
+  // A native maxLength counts UTF-16 units, which would cut an emoji in half,
+  // so a hard limit is enforced here in graphemes instead.
+  const handleChange = useCallback((event) => {
+    if (characterLimit !== undefined && characterLimitBehavior === 'hard') {
+      const clipped = clipToGraphemes(event.target.value, characterLimit);
+      if (clipped !== event.target.value) event.target.value = clipped;
+    }
+    onChange?.(event);
+  }, [characterLimit, characterLimitBehavior, onChange]);
+
+  const shown = value ?? defaultValue ?? '';
+  const tone = validationStatus === 'pending' ? 'pending' : messageTone;
+
+  return createElement('div', {
+    className: `ol8-field${className ? ` ${className}` : ''}`,
+    'data-ol8-size': size,
+    'data-ol8-appearance': appearance,
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+    ...(disabled ? { 'data-ol8-disabled': 'true' } : {}),
+    ...(readOnly ? { 'data-ol8-readonly': 'true' } : {}),
+    ...(invalid ? { 'data-ol8-invalid': 'true' } : {}),
+    ...(validationStatus !== 'idle' ? { 'data-ol8-validation': validationStatus } : {}),
+  },
+    showLabel
+      ? createElement('div', { key: 'label-row', className: 'ol8-field__label-row' },
+          createElement('label', { key: 'label', className: 'ol8-field__label', htmlFor: fieldId }, label),
+          required
+            ? createElement('span', { key: 'req', className: 'ol8-field__requirement', 'aria-hidden': 'true' }, '*')
+            : null,
+        )
+      : null,
+
+    createElement('div', { key: 'stack', className: 'ol8-field__control-stack' },
+      createElement('div', { className: 'ol8-field__control', onMouseDown: focusInput },
+        leadingIcon
+          ? createElement(Icon, { key: 'lead', name: leadingIcon, size: 18, className: 'ol8-field__leading-icon' })
+          : null,
+        prefix
+          ? createElement('span', { key: 'prefix', className: 'ol8-field__affix', 'aria-hidden': 'true' }, prefix)
+          : null,
+        createElement('input', {
+          key: 'input', ...rest, ref: attach,
+          id: fieldId,
+          className: 'ol8-field__input',
+          value, defaultValue, onChange: handleChange,
+          required, disabled, readOnly,
+          'aria-label': showLabel ? undefined : label,
+          'aria-invalid': invalid || undefined,
+          'aria-errormessage': invalid ? messageId : undefined,
+          'aria-describedby': describedBy,
+        }),
+        suffix
+          ? createElement('span', { key: 'suffix', className: 'ol8-field__affix', 'aria-hidden': 'true' }, suffix)
+          : null,
+        trailingAction
+          ? createElement('button', {
+              key: 'trailing', type: 'button', className: 'ol8-field__trailing-action',
+              disabled, onClick: trailingAction.onClick, 'aria-label': trailingAction.label,
+              'aria-pressed': trailingAction.pressed,
+            }, createElement(Icon, { name: trailingAction.icon, size: 18 }))
+          : null,
+      ),
+    ),
+
+    instruction
+      ? createElement('div', { key: 'instruction', className: 'ol8-field__instruction', id: instructionId }, instruction)
+      : null,
+
+    (message || counterId)
+      ? createElement('div', { key: 'supporting', className: 'ol8-field__supporting' },
+          message
+            ? createElement(FormMessage, { key: 'message', tone, icon: messageIcon, id: messageId }, message)
+            : createElement('span', { key: 'spacer', className: 'ol8-field__supporting-spacer' }),
+          counterId
+            ? createElement('span', { key: 'counter', className: 'ol8-field__counter', id: counterId },
+                `${countGraphemes(shown)} / ${characterLimit}`)
+            : null,
+        )
+      : null,
+  );
+});
+
+/**
+ * Counts what a reader would call characters, so an emoji built from several
+ * code points counts as one. The contract asks for extended grapheme clusters
+ * rather than UTF-16 code units or bytes.
+ */
+export function countGraphemes(value) {
+  return segment(value).length;
+}
+
+/** Keeps the first `limit` graphemes, so a cluster is never cut in half. */
+export function clipToGraphemes(value, limit) {
+  const parts = segment(value);
+  return parts.length <= limit ? String(value ?? '') : parts.slice(0, limit).join('');
+}
+
+function segment(value) {
+  const text = String(value ?? '');
+  if (typeof Intl !== 'undefined' && Intl.Segmenter) {
+    return [...new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(text)].map(s => s.segment);
+  }
+  return [...text];
+}

package/src/molecules/Token.js

@@ -0,0 +1,49 @@
+import { createElement, useId } from 'react';
+import { IconGlyph } from '../atoms/Icon.js';
+import { ChipShape } from './ChoiceChip.js';
+import { OL8_TOKEN_SIZES, OL8_TOKEN_MARKS, resolveTokenMark } from '../foundations/geometry.js';
+
+/**
+ * MOLECULE. A committed value. It draws no silhouette of its own: Figma's Token
+ * instantiates the Choice Chip Geometry Owner, and so does this. The one axis
+ * it adds is the Mark.
+ *
+ * A Token is not a Choice Chip. A chip is a checkbox a person toggles; a token
+ * is a value already committed, so it is ordinary content whose only
+ * interactive part is the optional Remove button.
+ */
+export function Token({
+  children, size = 'standard', selected = false, mark = 'auto', removable = true,
+  removeLabel, focusable = true, onRemove, id, className = '', ...rest
+}) {
+  if (!OL8_TOKEN_SIZES.includes(size)) throw new Error(`[ol8] unknown token size "${size}"`);
+  if (!OL8_TOKEN_MARKS.includes(mark)) throw new Error(`[ol8] unknown token mark "${mark}"`);
+  if (!children) throw new Error('[ol8] Token requires a label');
+  if (mark === 'remove' && !removable) {
+    throw new Error('[ol8] mark "remove" offers a removal path a non removable token does not have');
+  }
+  const auto = useId();
+  const uid = id ?? `ol8-token-${auto}`;
+  const resolved = resolveTokenMark(mark, { removable, selected });
+
+  // The label stays the token's content: the contract requires the complete
+  // value to remain readable, never shortened or overlaid by its mark.
+  const markup = resolved === 'remove'
+    ? createElement('button', {
+        key: 'mark', type: 'button', className: 'ol8-chip__mark ol8-token__remove',
+        'aria-label': removeLabel ?? `Remove ${children}`, onClick: onRemove,
+        ...(focusable ? {} : { tabIndex: -1 }),
+      }, createElement(IconGlyph, { name: 'close' }))
+    : resolved === 'check'
+      ? createElement('span', { key: 'mark', className: 'ol8-chip__mark', 'aria-hidden': 'true' },
+          createElement(IconGlyph, { name: 'check' }))
+      : null;
+
+  return createElement('span', {
+    ...rest,
+    className: `ol8-token ol8-chip${className ? ` ${className}` : ''}`,
+    'data-ol8-size': size,
+    'data-ol8-selection': selected ? 'selected' : 'inactive',
+    'data-ol8-mark': resolved,
+  }, createElement(ChipShape, { uid, label: children, mark: markup }));
+}

package/src/organisms/ChoicePicker.js

@@ -0,0 +1,114 @@
+import { createElement, useId } from 'react';
+import { Icon } from '../atoms/Icon.js';
+import { ChoiceChip } from '../molecules/ChoiceChip.js';
+import { OL8_PICKER_SIZES, OL8_PICKER_MATERIALS, OL8_COMMIT_BEHAVIORS,
+         OL8_PICKER_PRESENTATIONS, OL8_PICKER_MARKS } from '../foundations/geometry.js';
+
+/**
+ * ORGANISM. Search over a wrapping matrix of choices. The inline composition is
+ * canonical: an accessible group holding a search field, real checkboxes
+ * wearing the Choice Chip appearance, and, in Apply mode, a commitment line.
+ *
+ * It is a group rather than a dialog pretending to be a listbox, because the
+ * surface holds search, many independent choices and actions.
+ *
+ * Figma draws "Enter to apply" as text. The maintainer decision requires it to
+ * be a real clickable and focusable action, because a keyboard instruction is
+ * not an affordance for a pointer, touch, or a screen reader.
+ */
+export function ChoicePicker({
+  label, id, name, options = [], commitBehavior = 'immediate',
+  presentation = 'inline', mark = 'check', size = 'comfortable', material = 'regular',
+  inputValue, placeholder, showLabel = false, selectedSummary, applyHint,
+  showClearAll = false, clearAllLabel = 'Clear all',
+  disabled = false, readOnly = false, status = 'none', statusText,
+  onApply, onCancel, onClearAll, onToggle, onInputValueChange,
+  className = '', ...rest
+}) {
+  if (!label) throw new Error('[ol8] a Choice Picker requires a label for its search');
+  if (!OL8_PICKER_SIZES.includes(size)) throw new Error(`[ol8] unknown size "${size}"`);
+  if (!OL8_PICKER_MATERIALS.includes(material)) throw new Error(`[ol8] unknown material "${material}"`);
+  if (!OL8_COMMIT_BEHAVIORS.includes(commitBehavior)) throw new Error(`[ol8] unknown commit behavior "${commitBehavior}"`);
+  if (!OL8_PICKER_PRESENTATIONS.includes(presentation)) throw new Error(`[ol8] unknown presentation "${presentation}"`);
+  if (!OL8_PICKER_MARKS.includes(mark)) throw new Error(`[ol8] unknown mark "${mark}"`);
+  if (commitBehavior === 'immediate' && applyHint !== undefined) {
+    throw new Error('[ol8] immediate commitment applies every toggle at once, so an apply action would be a lie');
+  }
+  if (status !== 'none' && !statusText) {
+    throw new Error('[ol8] a picker status needs words. A spinner alone tells a screen reader nothing.');
+  }
+
+  const auto = useId();
+  const uid = id ?? `ol8-picker-${auto}`;
+  const labelId = `${uid}-label`;
+  const statusId = `${uid}-status`;
+  const selected = options.filter(o => o.selected);
+  const hint = applyHint ?? 'Enter to apply';
+  const locked = disabled || readOnly;
+
+  // A composing IME uses Enter to choose a candidate; committing there would
+  // apply a selection the person was still typing.
+  const onKeyDown = commitBehavior !== 'apply' ? undefined : (event) => {
+    if (event.nativeEvent && event.nativeEvent.isComposing) return;
+    if (event.key === 'Enter') { event.preventDefault(); onApply && onApply(); }
+    else if (event.key === 'Escape') { event.preventDefault(); onCancel && onCancel(); }
+  };
+
+  return createElement('div', {
+    ...rest, onKeyDown,
+    className: `ol8-picker${className ? ` ${className}` : ''}`,
+    role: 'group', 'aria-labelledby': labelId,
+    'data-ol8-size': size, 'data-ol8-commitment': commitBehavior,
+    'data-ol8-presentation': presentation, 'data-ol8-mark': mark,
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+    ...(disabled ? { 'data-ol8-availability': 'disabled' } : {}),
+    ...(readOnly ? { 'data-ol8-readonly': 'true' } : {}),
+  }, [
+    createElement('div', {
+      key: 'search', className: 'ol8-field ol8-picker__field',
+      'data-ol8-size': size, 'data-ol8-appearance': 'outline',
+      ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+    }, [
+      createElement('div', {
+        key: 'lr',
+        className: `ol8-field__label-row${showLabel ? '' : ' ol8-picker__label-row--hidden'}`,
+      }, createElement('label', { className: 'ol8-field__label', id: labelId, htmlFor: uid }, label)),
+      createElement('div', { key: 'cs', className: 'ol8-field__control-stack' },
+        createElement('div', { className: 'ol8-field__control' }, [
+          createElement(Icon, { key: 'i', name: 'search', size: 18, className: 'ol8-field__leading-icon' }),
+          createElement('input', {
+            key: 'input', className: 'ol8-field__input ol8-picker__input', id: uid, type: 'search',
+            ...(inputValue !== undefined
+              ? { value: inputValue, onChange: (e) => onInputValueChange && onInputValueChange(e.target.value) }
+              : {}),
+            placeholder, disabled, readOnly, 'aria-describedby': statusId,
+          }),
+        ])),
+    ]),
+    createElement('div', { key: 'matrix', className: 'ol8-picker__matrix' },
+      options.map((o, i) => createElement(ChoiceChip, {
+        key: o.value, size, selected: !!o.selected,
+        showMark: mark === 'check' && !!o.selected,
+        disabled: locked || o.disabled,
+        name: name ? `${name}[]` : undefined, value: o.value,
+        id: `${uid}-option-${i}`, className: 'ol8-picker__chip',
+        onChange: onToggle ? () => onToggle(o) : undefined,
+      }, o.label))),
+    commitBehavior === 'apply'
+      ? createElement('div', { key: 'commit', className: 'ol8-picker__commitment' }, [
+          createElement('span', { key: 's', className: 'ol8-picker__summary' },
+            selectedSummary ?? `${selected.length} selected`),
+          showClearAll ? createElement('button', {
+            key: 'c', type: 'button', className: 'ol8-picker__clear', onClick: onClearAll, disabled: locked,
+          }, clearAllLabel) : null,
+          createElement('button', {
+            key: 'a', type: 'button', className: 'ol8-picker__apply', onClick: onApply, disabled: locked,
+          }, hint),
+        ])
+      : null,
+    createElement('span', {
+      key: 'status', className: 'ol8-picker__status', id: statusId,
+      role: 'status', 'aria-live': 'polite',
+    }, status !== 'none' ? statusText : ''),
+  ]);
+}