@oneli8/react 1.0.0-beta.10

package/src/index.d.ts

@@ -0,0 +1,381 @@
+import type {
+  ComponentPropsWithoutRef, ForwardRefExoticComponent, ReactElement, ReactNode, RefAttributes,
+} from 'react';
+import type { Ol8IconName } from './foundations/icons.generated.js';
+
+export type { Ol8IconName };
+export { OL8_ICONS, OL8_ICON_VIEWBOX } from './foundations/icons.generated.js';
+
+export type Ol8Variant = 'primary' | 'secondary' | 'quiet' | 'destructive';
+export type Ol8Size = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8Material = 'regular' | 'gem';
+export type Ol8SelectionKind = 'checkbox' | 'radio' | 'switch';
+export type Ol8SelectionSize = 'compact' | 'comfortable';
+export type Ol8Selection =
+  | 'unchecked' | 'checked' | 'mixed'
+  | 'unselected' | 'selected'
+  | 'off' | 'on';
+export type Ol8LinkForm = 'inline' | 'standalone' | 'navigation';
+export type Ol8LinkSize = 'small' | 'standard' | 'large';
+export type Ol8LinkMotion = 'system' | 'none';
+export declare const OL8_LINK_FORMS: readonly Ol8LinkForm[];
+export declare const OL8_LINK_SIZES: readonly Ol8LinkSize[];
+export declare const OL8_LINK_MOTIONS: readonly Ol8LinkMotion[];
+
+export type Ol8TextFieldSize = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8TextFieldAppearance = 'outline' | 'filled';
+/** Pending is a validation process status, not a fifth message tone. */
+export type Ol8MessageTone = 'critical' | 'caution' | 'positive' | 'informative';
+export type Ol8ValidationStatus = 'idle' | 'pending' | 'resolved';
+export type Ol8CharacterLimitBehavior = 'soft' | 'hard';
+/** Form Message itself draws all five, because Figma 177:13 enumerates five. */
+export type Ol8FormMessageTone = Ol8MessageTone | 'pending';
+export declare const OL8_TEXT_FIELD_SIZES: readonly Ol8TextFieldSize[];
+export declare const OL8_TEXT_FIELD_APPEARANCES: readonly Ol8TextFieldAppearance[];
+export declare const OL8_TEXT_FIELD_MATERIALS: readonly Ol8Material[];
+export declare const OL8_MESSAGE_TONES: readonly Ol8MessageTone[];
+export declare const OL8_VALIDATION_STATUSES: readonly Ol8ValidationStatus[];
+export declare const OL8_CHARACTER_LIMIT_BEHAVIORS: readonly Ol8CharacterLimitBehavior[];
+export declare const OL8_FORM_MESSAGE_TONES: readonly Ol8FormMessageTone[];
+export declare const OL8_FORM_MESSAGE_ICONS: Readonly<Record<Ol8FormMessageTone, string>>;
+
+export type Ol8NavigationSize = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8TabsHierarchy = 'primary' | 'secondary' | 'tertiary';
+export type Ol8TabsOrientation = 'horizontal' | 'vertical';
+export type Ol8TabsActivation = 'automatic' | 'manual';
+export type Ol8SegmentBehavior = 'single' | 'multi' | 'momentary';
+export type Ol8SegmentPresentation =
+  | 'inset-fill' | 'line-indicator' | 'outlined-selection'
+  | 'soft-pill' | 'icon-only' | 'stacked-label';
+export type Ol8TabBarPresentation = 'bottom' | 'inline' | 'sidebar' | 'spatial-rail';
+export declare const OL8_TABS_HIERARCHIES: readonly Ol8TabsHierarchy[];
+export declare const OL8_TABS_ORIENTATIONS: readonly Ol8TabsOrientation[];
+export declare const OL8_TABS_ACTIVATIONS: readonly Ol8TabsActivation[];
+export declare const OL8_SEGMENT_BEHAVIORS: readonly Ol8SegmentBehavior[];
+export declare const OL8_SEGMENT_PRESENTATIONS: readonly Ol8SegmentPresentation[];
+export declare const OL8_TAB_BAR_PRESENTATIONS: readonly Ol8TabBarPresentation[];
+
+export type Ol8OptionSize = 'standard' | 'large';
+export type Ol8Aggregate = 'none' | 'some' | 'all';
+
+export declare const OL8_BUTTON_VARIANTS: readonly Ol8Variant[];
+export declare const OL8_BUTTON_SIZES: readonly Ol8Size[];
+export declare const OL8_MATERIALS: readonly Ol8Material[];
+/** Gem is approved for Primary and Secondary only (Figma 100:3). */
+export declare const GEM_VARIANTS: readonly ('primary' | 'secondary')[];
+export declare const OL8_ICON_BUTTON_VARIANTS: readonly Ol8Variant[];
+export declare const OL8_ICON_BUTTON_SIZES: readonly Ol8Size[];
+export declare const OL8_ICON_BUTTON_SHAPES: readonly ('rounded' | 'circle')[];
+export declare const OL8_SELECTION_KINDS: readonly Ol8SelectionKind[];
+export declare const OL8_SELECTION_SIZES: readonly Ol8SelectionSize[];
+export declare const OL8_SELECTION_STATES: Record<Ol8SelectionKind, readonly Ol8Selection[]>;
+export declare const OL8_CHOICE_KINDS: readonly Ol8SelectionKind[];
+export declare const OL8_CHOICE_SIZES: readonly Ol8Size[];
+export declare const OL8_OPTION_SIZES: readonly Ol8OptionSize[];
+export declare const OL8_AGGREGATE: readonly Ol8Aggregate[];
+
+export declare function isOl8IconName(name: string): name is Ol8IconName;
+export declare function iconSizeForButton(size: Ol8Size): 18 | 24;
+export declare function artworkSizeForIconButton(size: Ol8Size): 18 | 24;
+export declare function indicatorSizeFor(size: Ol8Size): Ol8SelectionSize;
+export declare function selectionStateFor(
+  kind: Ol8SelectionKind, state?: { checked?: boolean; mixed?: boolean }
+): Ol8Selection;
+export declare function computeAggregate(
+  children: Iterable<{ checked?: boolean; disabled?: boolean }>
+): Ol8Aggregate;
+
+/** ATOM. Decorative unless given a label; the parent control carries meaning. */
+export interface IconProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children'> {
+  name: Ol8IconName;
+  size?: number;
+  /** Promotes the icon to role="img". Omit for decorative. */
+  label?: string;
+}
+export declare function Icon(props: IconProps): ReactElement;
+
+/** ATOM. Presentational only; the native input in ChoiceItem owns state and focus. */
+export interface SelectionIndicatorProps extends Omit<ComponentPropsWithoutRef<'span'>, 'children'> {
+  kind: Ol8SelectionKind;
+  selection?: Ol8Selection;
+  size?: Ol8SelectionSize;
+  disabled?: boolean;
+  /** Switch thumb artwork only. */
+  icon?: Ol8IconName;
+}
+export declare function SelectionIndicator(props: SelectionIndicatorProps): ReactElement;
+
+/** MOLECULE. States are CSS, never classes. */
+export interface ButtonProps extends Omit<ComponentPropsWithoutRef<'button'>, 'type'> {
+  children?: ReactNode;
+  variant?: Ol8Variant;
+  size?: Ol8Size;
+  /** Throws for quiet and destructive: Gem has no approved treatment there. */
+  material?: Ol8Material;
+  leadingIcon?: Ol8IconName;
+  trailingIcon?: Ol8IconName;
+  loading?: boolean;
+  pressed?: boolean;
+  fullWidth?: boolean;
+  /** Renders an anchor instead of a button. */
+  href?: string;
+  type?: 'button' | 'submit' | 'reset';
+  /** Keeps the leading icon beside the spinner, Figma's literal reading. */
+  keepLeadingIconWhileLoading?: boolean;
+}
+export declare const Button: ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLElement>>;
+
+/** MOLECULE. An accessible name is mandatory and enforced at runtime. */
+export interface IconButtonProps extends Omit<ComponentPropsWithoutRef<'button'>, 'type'> {
+  icon: Ol8IconName;
+  accessibleName: string;
+  variant?: Ol8Variant;
+  size?: Ol8Size;
+  shape?: 'rounded' | 'circle';
+  material?: Ol8Material;
+  loading?: boolean;
+  pressed?: boolean;
+  type?: 'button' | 'submit' | 'reset';
+}
+export declare const IconButton: ForwardRefExoticComponent<IconButtonProps & RefAttributes<HTMLButtonElement>>;
+
+/** MOLECULE. A real input owns state, focus and form participation. */
+export interface ChoiceItemProps extends Omit<ComponentPropsWithoutRef<'input'>, 'size' | 'type' | 'children'> {
+  kind: Ol8SelectionKind;
+  children?: ReactNode;
+  size?: Ol8Size;
+  /** Checkbox only. Sets the JavaScript-only indeterminate flag. */
+  mixed?: boolean;
+  invalid?: boolean;
+  /** Associated with aria-describedby, outside the accessible name. */
+  description?: ReactNode;
+  material?: Ol8Material;
+}
+export declare const ChoiceItem: ForwardRefExoticComponent<ChoiceItemProps & RefAttributes<HTMLInputElement>>;
+
+/** MOLECULE. States are CSS, never props. Icons are intentionally parked. */
+export interface LinkProps extends Omit<ComponentPropsWithoutRef<'a'>, 'href'> {
+  children?: ReactNode;
+  href: string;
+  form?: Ol8LinkForm;
+  size?: Ol8LinkSize;
+  /** Navigation only. `true` emits aria-current="page"; a string names the kind. */
+  current?: boolean | string;
+  motion?: Ol8LinkMotion;
+}
+export declare const Link: ForwardRefExoticComponent<LinkProps & RefAttributes<HTMLAnchorElement>>;
+
+/** MOLECULE. Tone maps to semantic message tone; Pending is the validating state. */
+export interface FormMessageProps extends ComponentPropsWithoutRef<'div'> {
+  children?: ReactNode;
+  tone?: Ol8FormMessageTone;
+  /** Figma's Show Icon. */
+  icon?: boolean;
+}
+export declare const FormMessage: ForwardRefExoticComponent<FormMessageProps & RefAttributes<HTMLDivElement>>;
+
+/** MOLECULE. Conditions are CSS and native state, never props. Gem changes material only. */
+export interface TextFieldProps extends Omit<ComponentPropsWithoutRef<'input'>, 'size' | 'prefix'> {
+  /** Required and visible. A placeholder is never the label. */
+  label: string;
+  /** Default Comfortable, the cross platform size. */
+  size?: Ol8TextFieldSize;
+  appearance?: Ol8TextFieldAppearance;
+  material?: Ol8Material;
+  /** False keeps the label as the accessible name without showing it, which needs a documented exception. */
+  showLabel?: boolean;
+  /** Correction is required. Never set without also exposing a Critical message. */
+  invalid?: boolean;
+  leadingIcon?: string;
+  prefix?: ReactNode;
+  suffix?: ReactNode;
+  trailingAction?: { icon: string; label: string; onClick?: () => void; pressed?: boolean };
+  instruction?: ReactNode;
+  message?: ReactNode;
+  messageTone?: Ol8MessageTone;
+  messageIcon?: boolean;
+  /** Pending shows the loader; it never freezes typing. */
+  validationStatus?: Ol8ValidationStatus;
+  /** Counted in graphemes, so an emoji counts as one. */
+  characterLimit?: number;
+  /** Soft lets a person overshoot and then correct. Hard is for real technical limits. */
+  characterLimitBehavior?: Ol8CharacterLimitBehavior;
+}
+export declare const TextField: ForwardRefExoticComponent<TextFieldProps & RefAttributes<HTMLInputElement>>;
+
+/** Counts what a reader would call characters. */
+export declare function countGraphemes(value: unknown): number;
+
+/** Keeps the first `limit` graphemes, so a cluster is never cut in half. */
+export declare function clipToGraphemes(value: unknown, limit: number): string;
+
+/** MOLECULE. Never focusable; a listbox moves a virtual cursor instead. */
+export interface SelectionOptionProps extends Omit<ComponentPropsWithoutRef<'li'>, 'children'> {
+  children?: ReactNode;
+  value?: string;
+  size?: Ol8OptionSize;
+  selected?: boolean;
+  active?: boolean;
+  disabled?: boolean;
+  description?: ReactNode;
+  leadingIcon?: Ol8IconName;
+  focusRing?: boolean;
+}
+export declare function SelectionOption(props: SelectionOptionProps): ReactElement;
+
+export interface Ol8GroupOption {
+  label: ReactNode;
+  value: string;
+  description?: ReactNode;
+  disabled?: boolean;
+  /** CheckboxGroup only; radios take a single group value. */
+  checked?: boolean;
+}
+interface Ol8GroupShell {
+  legend: ReactNode;
+  instruction?: ReactNode;
+  message?: ReactNode;
+  invalid?: boolean;
+  disabled?: boolean;
+  size?: Ol8Size;
+  material?: Ol8Material;
+  id?: string;
+  className?: string;
+}
+/** ORGANISM. Native radios already give roving focus and single selection. */
+export interface RadioGroupProps extends Ol8GroupShell {
+  name: string;
+  options: Ol8GroupOption[];
+  value?: string;
+  onChange?: (value: string) => void;
+  orientation?: 'vertical' | 'horizontal';
+  required?: boolean;
+}
+export declare function RadioGroup(props: RadioGroupProps): ReactElement;
+
+/** ORGANISM. Aggregate is computed; Mixed is never a third preference. */
+export interface CheckboxGroupProps extends Ol8GroupShell {
+  parentLabel: ReactNode;
+  options: Ol8GroupOption[];
+  name?: string;
+  onChange?: (state: Record<string, boolean>) => void;
+}
+export declare function CheckboxGroup(props: CheckboxGroupProps): ReactElement;
+
+/** ATOM. One badge serves all three navigation organisms. */
+export interface NavigationBadgeProps extends ComponentPropsWithoutRef<'span'> {
+  children: ReactNode;
+}
+export declare const NavigationBadge: ForwardRefExoticComponent<NavigationBadgeProps & RefAttributes<HTMLSpanElement>>;
+
+export interface Ol8TabItem {
+  /** Required: exactly one panel is paired with it. */
+  id: string;
+  label?: string;
+  icon?: string;
+  badge?: string | number;
+  disabled?: boolean;
+  /** Required when the item shows an icon and no label. */
+  ariaLabel?: string;
+}
+
+/** ORGANISM. Emits tablist, tab and tabpanel, and keeps one enabled tab stop. */
+export interface TabsProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange'> {
+  /** Required. A region nobody can name is a region nobody can reach. */
+  label: string;
+  items: Ol8TabItem[];
+  value?: string;
+  defaultValue?: string;
+  onChange?: (id: string) => void;
+  hierarchy?: Ol8TabsHierarchy;
+  size?: Ol8NavigationSize;
+  material?: Ol8Material;
+  orientation?: Ol8TabsOrientation;
+  activation?: Ol8TabsActivation;
+  /** Supply it and Tabs renders the owned panel for each item. */
+  renderPanel?: (item: Ol8TabItem) => ReactNode;
+}
+export declare const Tabs: ForwardRefExoticComponent<TabsProps & RefAttributes<HTMLDivElement>>;
+
+export interface Ol8SegmentItem {
+  id: string;
+  label?: string;
+  icon?: string;
+  badge?: string | number;
+  disabled?: boolean;
+  /** Required when the item shows an icon and no label. */
+  ariaLabel?: string;
+}
+
+/** ORGANISM. Behaviour is declared, never inferred; presentation never changes it. */
+export interface SegmentedControlProps extends Omit<ComponentPropsWithoutRef<'div'>, 'onChange' | 'defaultValue'> {
+  /** Required accessible name. */
+  label: string;
+  /** Exactly one: single is a radio group, multi is toggle buttons, momentary stores nothing. */
+  behavior: Ol8SegmentBehavior;
+  items: Ol8SegmentItem[];
+  /** One value for single, an array for multi, nothing for momentary. */
+  value?: string | string[];
+  defaultValue?: string | string[];
+  onChange?: (value: string | string[]) => void;
+  presentation?: Ol8SegmentPresentation;
+  size?: Ol8NavigationSize;
+  material?: Ol8Material;
+}
+export declare const SegmentedControl: ForwardRefExoticComponent<SegmentedControlProps & RefAttributes<HTMLDivElement>>;
+
+export interface Ol8Destination {
+  /** Required. A tab bar navigates, so it uses real links. */
+  href: string;
+  label?: string;
+  icon?: string;
+  badge?: string | number;
+  /** Required when the destination shows an icon and no label. */
+  ariaLabel?: string;
+}
+
+/** ORGANISM. Native destination links, one current destination, no disabled pseudo destinations. */
+export interface TabBarProps extends ComponentPropsWithoutRef<'nav'> {
+  /** Required navigation name, so a person can tell one landmark from another. */
+  label: string;
+  items: Ol8Destination[];
+  /** The href of the destination a person is on. */
+  current?: string;
+  /** Routes an ordinary left click while the link stays a real link. */
+  onNavigate?: (href: string, event: MouseEvent) => void;
+  presentation?: Ol8TabBarPresentation;
+  size?: Ol8NavigationSize;
+  material?: Ol8Material;
+}
+export declare const TabBar: ForwardRefExoticComponent<TabBarProps & RefAttributes<HTMLElement>>;
+
+export type Ol8SelectNativePolicy = 'preferred' | 'required' | 'custom-allowed';
+export declare const OL8_SELECT_NATIVE_POLICIES: readonly Ol8SelectNativePolicy[];
+
+export interface Ol8SelectOption {
+  value: string;
+  label: string;
+  disabled?: boolean;
+  group?: string;
+}
+
+/** MOLECULE. Native first: a real select, wearing the Text Field geometry Figma reuses. */
+export interface SelectProps extends Omit<ComponentPropsWithoutRef<'select'>, 'size'> {
+  /** Required and visible. A placeholder is never the label. */
+  label: string;
+  options: Ol8SelectOption[];
+  size?: Ol8TextFieldSize;
+  appearance?: Ol8TextFieldAppearance;
+  material?: Ol8Material;
+  showLabel?: boolean;
+  invalid?: boolean;
+  /** Only when an unselected value is valid, or required validation needs a prompt. */
+  placeholderOption?: string;
+  leadingIcon?: string;
+  instruction?: ReactNode;
+  message?: ReactNode;
+  messageTone?: Ol8MessageTone;
+  /** 'custom-allowed' is refused: use Combobox, which implements the full contract. */
+  native?: Ol8SelectNativePolicy;
+}
+export declare const Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLSelectElement>>;

package/src/index.js

@@ -0,0 +1,23 @@
+export { Icon } from './atoms/Icon.js';
+export { SelectionIndicator } from './atoms/SelectionIndicator.js';
+export { Button } from './molecules/Button.js';
+export { IconButton } from './molecules/IconButton.js';
+export { Link } from './molecules/Link.js';
+export { ChoiceItem } from './molecules/ChoiceItem.js';
+export { SelectionOption } from './molecules/SelectionOption.js';
+export { FormMessage } from './molecules/FormMessage.js';
+export { TextField, countGraphemes, clipToGraphemes } from './molecules/TextField.js';
+export { Select, OL8_SELECT_NATIVE_POLICIES } from './molecules/Select.js';
+export { ChoiceChip } from './molecules/ChoiceChip.js';
+export { Token } from './molecules/Token.js';
+export { RadioGroup, CheckboxGroup } from './organisms/ChoiceGroup.js';
+export { SelectionPopup } from './organisms/SelectionPopup.js';
+export { MultiSelectField } from './organisms/MultiSelectField.js';
+export { ChoicePicker } from './organisms/ChoicePicker.js';
+export { Combobox } from './organisms/Combobox.js';
+export { NavigationBadge } from './atoms/NavigationBadge.js';
+export { Tabs } from './organisms/Tabs.js';
+export { SegmentedControl } from './organisms/SegmentedControl.js';
+export { TabBar } from './organisms/TabBar.js';
+export * from './foundations/geometry.js';
+export { OL8_ICONS, OL8_ICON_VIEWBOX } from './foundations/icons.generated.js';

package/src/molecules/Button.js

@@ -0,0 +1,50 @@
+import { createElement, forwardRef } from 'react';
+import { Icon, IconGlyph } from '../atoms/Icon.js';
+import { assertVariant, iconSizeForButton } from '../foundations/geometry.js';
+
+/**
+ * MOLECULE. Figma's six States are visual evidence for review, not classes.
+ * In code they are :hover, :active, :focus-visible, [disabled] and
+ * [data-ol8-loading]. There is no .ol8-btn--hover.
+ */
+export const Button = forwardRef(function Button({
+  children, variant = 'primary', size = 'standard', material = 'regular',
+  leadingIcon, trailingIcon, loading = false, disabled = false, pressed,
+  fullWidth = false, href, type = 'button', className = '',
+  keepLeadingIconWhileLoading = false, ...rest
+}, ref) {
+  assertVariant(variant, size, material);
+  const isLink = typeof href === 'string';
+  const inert = disabled || loading;
+  const iconSize = iconSizeForButton(size);
+
+  // The spinner takes the leading slot by default, so the control never shows
+  // two competing leading glyphs and its width stays predictable.
+  const content = [];
+  if (loading) {
+    if (keepLeadingIconWhileLoading && leadingIcon) {
+      content.push(createElement(Icon, { key: 'leading', name: leadingIcon, size: iconSize }));
+    }
+    content.push(createElement('span', { key: 'spinner', className: 'ol8-btn__spinner ol8-icon', 'aria-hidden': 'true' },
+      createElement(IconGlyph, { name: 'loading' })));
+  } else if (leadingIcon) {
+    content.push(createElement(Icon, { key: 'leading', name: leadingIcon, size: iconSize }));
+  }
+  content.push(createElement('span', { key: 'label', className: 'ol8-btn__label' }, children));
+  if (trailingIcon) content.push(createElement(Icon, { key: 'trailing', name: trailingIcon, size: iconSize }));
+
+  const shared = {
+    ...rest, ref,
+    className: `ol8-btn ol8-btn--${variant}${className ? ` ${className}` : ''}`,
+    'data-ol8-size': size,
+    ...(loading ? { 'data-ol8-loading': 'true', 'aria-busy': 'true' } : {}),
+    ...(pressed !== undefined ? { 'aria-pressed': String(pressed) } : {}),
+    ...(fullWidth ? { 'data-ol8-fullwidth': 'true' } : {}),
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+    ...(loading && keepLeadingIconWhileLoading ? { 'data-ol8-loading-keep-icon': 'true' } : {}),
+  };
+  // A link cannot be natively disabled, so it leaves the tab order instead.
+  return isLink
+    ? createElement('a', { ...shared, ...(inert ? { role: 'button', 'aria-disabled': 'true', tabIndex: -1 } : { href }) }, content)
+    : createElement('button', { ...shared, type, ...(inert ? { disabled: true } : {}) }, content);
+});

package/src/molecules/ChoiceChip.js

@@ -0,0 +1,101 @@
+import { createElement, useId } from 'react';
+import { IconGlyph } from '../atoms/Icon.js';
+import { OL8_CHIP_SIZES } from '../foundations/geometry.js';
+
+/**
+ * MOLECULE. The Soft Hexagon, built the way Figma builds it: a fixed 12 unit
+ * terminal, a rail that grows with the label, and a mirrored terminal. Only the
+ * rail grows, so peer chips of any length keep one shoulder depth and angle.
+ *
+ * The terminal paths and the shape are private, as they are in Figma, where the
+ * terminals are named "Private Geometry" and the contract says they are "not
+ * published cap atoms, layer variants, or independently swappable components".
+ * Token imports them from this module; the package index does not export them.
+ *
+ * One viewBox serves all four heights: read from Figma, every terminal path at
+ * 30, 36 and 42 shares identical X values and Y values that are the same
+ * fractions of the height, so stretching Y alone is exact.
+ */
+const TERMINAL_FILL =
+  'M12 0 L8.96202541 0 C7.44303812 0 6.43037944 0.83333333 5.92405035 2.5 ' +
+  'L0.45569618 12.5 C-0.15189877 13.75 -0.15189877 16.25 0.45569618 17.5 ' +
+  'L5.92405035 27.5 C6.43037944 29.16666667 7.44303812 30 8.96202541 30 L12 30 Z';
+const TERMINAL_EDGE =
+  'M12 0 L8.96202541 0 C7.44303812 0 6.43037944 0.83333333 5.92405035 2.5 ' +
+  'L0.45569618 12.5 C-0.15189877 13.75 -0.15189877 16.25 0.45569618 17.5 ' +
+  'L5.92405035 27.5 C6.43037944 29.16666667 7.44303812 30 8.96202541 30 L12 30';
+
+function Terminal({ uid, side }) {
+  const clip = `${uid}-clip-${side}`;
+  return createElement('svg', {
+    className: `ol8-chip__terminal ol8-chip__terminal--${side}`,
+    viewBox: '0 0 12 30', preserveAspectRatio: 'none',
+    'aria-hidden': 'true', focusable: 'false',
+  }, [
+    createElement('clipPath', { key: 'c', id: clip }, createElement('path', { d: TERMINAL_FILL })),
+    createElement('path', { key: 'fo', className: 'ol8-chip__focus-outer', d: TERMINAL_EDGE }),
+    createElement('path', { key: 'fi', className: 'ol8-chip__focus-inner', d: TERMINAL_EDGE }),
+    createElement('path', { key: 'f', className: 'ol8-chip__fill', d: TERMINAL_FILL }),
+    createElement('path', { key: 'e', className: 'ol8-chip__edge', d: TERMINAL_EDGE, clipPath: `url(#${clip})` }),
+  ]);
+}
+
+/**
+ * The silhouette and its rail. Figma's "Choice Chip / Geometry Owner".
+ * The mark follows the label, which is the anatomy the contract writes down as
+ * "Label + optional Remove mark", and one position serves Check and Remove
+ * alike so peer marks never end up on opposite sides.
+ */
+export function ChipShape({ uid, label, mark = null }) {
+  return [
+    createElement(Terminal, { key: 'l', uid, side: 'leading' }),
+    createElement('span', { key: 'r', className: 'ol8-chip__rail' }, [
+      createElement('span', { key: 'label', className: 'ol8-chip__label' }, label),
+      mark,
+    ]),
+    createElement(Terminal, { key: 't', uid, side: 'trailing' }),
+  ];
+}
+
+/**
+ * A Choice Chip is a real checkbox. The contract is explicit that every picker
+ * option is "a real Checkbox rendered with the approved quiet Choice Chip
+ * appearance", with native checked state among the redundant cues, so selection
+ * never rests on colour alone.
+ */
+export function ChoiceChip({
+  children, size = 'standard', selected, defaultSelected, showMark = false,
+  disabled = false, name, value, id, className = '', onChange, ...rest
+}) {
+  if (!OL8_CHIP_SIZES.includes(size)) throw new Error(`[ol8] unknown chip size "${size}"`);
+  if (!children) throw new Error('[ol8] Choice Chip requires a label');
+  const auto = useId();
+  const uid = id ?? `ol8-chip-${auto}`;
+  const isOn = selected ?? defaultSelected ?? false;
+
+  return createElement('label', {
+    className: `ol8-chip${className ? ` ${className}` : ''}`,
+    htmlFor: uid,
+    'data-ol8-size': size,
+    'data-ol8-selection': isOn ? 'selected' : 'inactive',
+    'data-ol8-availability': disabled ? 'disabled' : 'enabled',
+  }, [
+    createElement('input', {
+      key: 'input', ...rest,
+      type: 'checkbox', className: 'ol8-chip__input', id: uid, name, value, disabled, onChange,
+      // A controlled chip with nothing listening is a display of state, not a
+      // control. Saying so is what React asks for, and it is the truth: the
+      // chip cannot change anything until someone handles the change.
+      ...(selected !== undefined
+        ? { checked: selected, ...(onChange ? {} : { readOnly: true }) }
+        : defaultSelected !== undefined ? { defaultChecked: defaultSelected } : {}),
+    }),
+    createElement(ChipShape, {
+      key: 'shape', uid, label: children,
+      mark: showMark
+        ? createElement('span', { key: 'mark', className: 'ol8-chip__mark', 'aria-hidden': 'true' },
+            createElement(IconGlyph, { name: 'check' }))
+        : null,
+    }),
+  ]);
+}

package/src/molecules/ChoiceItem.js

@@ -0,0 +1,55 @@
+import { createElement, forwardRef, useId } from 'react';
+import { SelectionIndicator } from '../atoms/SelectionIndicator.js';
+import { OL8_CHOICE_KINDS, OL8_CHOICE_SIZES, indicatorSizeFor, selectionStateFor } from '../foundations/geometry.js';
+
+/**
+ * MOLECULE. A real input owns state, focus and form participation; this never
+ * reimplements toggling. `indeterminate` is the one thing markup cannot express,
+ * so React sets it through a ref callback rather than an attribute.
+ */
+export const ChoiceItem = forwardRef(function ChoiceItem({
+  kind, children, size = 'standard', checked, defaultChecked, mixed = false,
+  disabled = false, invalid = false, description, name, value, required = false,
+  material = 'regular', id, className = '', onChange, ...rest
+}, ref) {
+  if (!OL8_CHOICE_KINDS.includes(kind)) throw new Error(`[ol8] unknown choice kind "${kind}"`);
+  if (!OL8_CHOICE_SIZES.includes(size)) throw new Error(`[ol8] unknown choice size "${size}"`);
+  const auto = useId();
+  const rowId = id ?? `ol8-choice-${auto}`;
+  const descId = description ? `${rowId}-desc` : undefined;
+  const isOn = checked ?? defaultChecked ?? false;
+
+  return createElement('label', {
+    className: `ol8-choice ol8-choice--${kind}${className ? ` ${className}` : ''}`,
+    htmlFor: rowId,
+    'data-ol8-size': size,
+    'data-ol8-kind': kind,
+    'data-ol8-availability': disabled ? 'disabled' : 'enabled',
+    ...(invalid ? { 'data-ol8-validity': 'invalid' } : {}),
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+  }, [
+    createElement('input', {
+      key: 'input', ...rest,
+      ref: (node) => {
+        if (node) node.indeterminate = kind === 'checkbox' && mixed;
+        if (typeof ref === 'function') ref(node); else if (ref) ref.current = node;
+      },
+      type: kind === 'radio' ? 'radio' : 'checkbox',
+      className: 'ol8-choice__input', id: rowId, name, value, required, disabled, onChange,
+      ...(checked !== undefined ? { checked } : defaultChecked !== undefined ? { defaultChecked } : {}),
+      ...(descId ? { 'aria-describedby': descId } : {}),
+      ...(invalid ? { 'aria-invalid': 'true' } : {}),
+      ...(kind === 'switch' ? { role: 'switch' } : {}),
+    }),
+    createElement('span', { key: 'surface', className: 'ol8-choice__surface', 'aria-hidden': 'true' }),
+    createElement('span', { key: 'indicator', className: 'ol8-choice__indicator' },
+      createElement(SelectionIndicator, {
+        kind, size: indicatorSizeFor(size), disabled,
+        selection: selectionStateFor(kind, { checked: isOn, mixed }),
+      })),
+    createElement('span', { key: 'text', className: 'ol8-choice__text' }, [
+      createElement('span', { key: 'label', className: 'ol8-choice__label' }, children),
+      description ? createElement('span', { key: 'desc', className: 'ol8-choice__description', id: descId }, description) : null,
+    ]),
+  ]);
+});

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),
+  );
+});