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

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

package/src/organisms/Combobox.js

@@ -0,0 +1,122 @@
+import { createElement, useId } from 'react';
+import { Icon } from '../atoms/Icon.js';
+import { FormMessage } from '../molecules/FormMessage.js';
+import { SelectionPopup } from './SelectionPopup.js';
+import { OL8_COMBOBOX_SIZES, OL8_COMBOBOX_APPEARANCES, OL8_COMBOBOX_MATERIALS,
+         OL8_VALUE_POLICIES, OL8_AUTOCOMPLETE_MODES, OL8_FILTER_SOURCES } from '../foundations/geometry.js';
+
+/**
+ * ORGANISM. Figma 883:2159: "Reuses approved Text Field, Selection Popup and
+ * governed icon atoms", and "Expanded remains Boolean" so the design does not
+ * explode into a variant per state.
+ *
+ * The contract is unusually specific about what code owns, and this markup is
+ * shaped by it:
+ *
+ *   "Editable Combobox uses a native single-line text input as its editing
+ *    surface" — so caret, selection, composition, dictation, undo and paste all
+ *    keep working, because they are the browser's.
+ *   "DOM focus remains on the Combobox and active option is communicated with
+ *    aria-activedescendant. Popup descendants are excluded from the page Tab
+ *    sequence."
+ *   "Current value, active option and keyboard focus are distinct states."
+ *
+ * React owns none of the keyboard model here. Opening, the active option and
+ * committing are application state, so they arrive as props and leave as
+ * callbacks; a component that tried to own them would fight the consumer.
+ */
+export function Combobox({
+  label, options = [], id, name, inputValue, value,
+  size = 'comfortable', appearance = 'outline', material = 'regular',
+  open = false, active, showLabel = true,
+  required = false, disabled = false, invalid = false, readOnly = false,
+  placeholder, leadingIcon, clearable = false,
+  instruction, message, messageTone = 'critical',
+  valuePolicy = 'constrained', autocomplete = 'list-manual', filter = 'local',
+  loading = false, emptyText, retrievalError,
+  popupWidth = 'anchor', onInputValueChange, onClear, className = '', ...rest
+}) {
+  if (typeof label !== 'string' || label === '') {
+    throw new Error('[ol8] Combobox requires a label, and its accessible name stays distinct from its value.');
+  }
+  if (!OL8_COMBOBOX_SIZES.includes(size)) throw new Error(`[ol8] unknown combobox size "${size}"`);
+  if (!OL8_COMBOBOX_APPEARANCES.includes(appearance)) throw new Error(`[ol8] unknown combobox appearance "${appearance}"`);
+  if (!OL8_COMBOBOX_MATERIALS.includes(material)) throw new Error(`[ol8] unknown combobox material "${material}"`);
+  if (!OL8_VALUE_POLICIES.includes(valuePolicy)) throw new Error(`[ol8] unknown value policy "${valuePolicy}"`);
+  if (!OL8_AUTOCOMPLETE_MODES.includes(autocomplete)) throw new Error(`[ol8] unknown autocomplete mode "${autocomplete}"`);
+  if (!OL8_FILTER_SOURCES.includes(filter)) throw new Error(`[ol8] unknown filter source "${filter}"`);
+  if (clearable && required) {
+    throw new Error('[ol8] a required Combobox is not clearable, because clearing it would leave a value the form cannot accept.');
+  }
+  if (readOnly && invalid) {
+    throw new Error('[ol8] a read only Combobox cannot be invalid, for the same reason a read only field cannot be.');
+  }
+
+  const auto = useId();
+  const uid = id ?? `ol8-combobox-${auto}`;
+  const popupId = `${uid}-listbox`;
+  const instructionId = instruction ? `${uid}-instruction` : undefined;
+  const messageId = message ? `${uid}-message` : undefined;
+  const describedBy = [instructionId, messageId].filter(Boolean).join(' ') || undefined;
+
+  // Four distinct conditions, never collapsed into one "nothing here".
+  const status = loading ? 'loading'
+    : retrievalError ? 'error'
+    : (options.length === 0 && emptyText) ? 'empty'
+    : 'none';
+  const statusText = loading ? 'Loading' : retrievalError || emptyText;
+
+  return createElement('div', {
+    ...rest,
+    className: `ol8-field ol8-combobox${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' } : {}),
+    'data-ol8-value-policy': valuePolicy,
+    'data-ol8-filter': filter,
+    ...(value !== undefined ? { 'data-ol8-committed': value } : {}),
+  }, [
+    showLabel ? createElement('div', { key: 'lr', className: 'ol8-field__label-row' }, [
+      createElement('label', { key: 'l', className: 'ol8-field__label', htmlFor: uid }, label),
+      required ? createElement('span', { key: 'r', className: 'ol8-field__requirement', 'aria-hidden': 'true' }, '*') : null,
+    ]) : null,
+    createElement('div', { key: 'cs', className: 'ol8-field__control-stack' },
+      createElement('div', { className: 'ol8-field__control' }, [
+        leadingIcon ? createElement(Icon, { key: 'li', name: leadingIcon, size: 18, className: 'ol8-field__leading-icon' }) : null,
+        createElement('input', {
+          key: 'input', className: 'ol8-field__input ol8-combobox__input', id: uid, type: 'text',
+          role: 'combobox', 'aria-expanded': String(open), 'aria-controls': popupId,
+          'aria-autocomplete': autocomplete === 'none' ? 'none' : 'list',
+          autoComplete: 'off',
+          ...(active ? { 'aria-activedescendant': `${popupId}-option-${active}` } : {}),
+          name, placeholder, required, disabled, readOnly,
+          ...(inputValue !== undefined
+            ? { value: inputValue, onChange: (e) => onInputValueChange && onInputValueChange(e.target.value) }
+            : {}),
+          ...(invalid ? { 'aria-invalid': 'true', ...(messageId ? { 'aria-errormessage': messageId } : {}) } : {}),
+          ...(describedBy ? { 'aria-describedby': describedBy } : {}),
+          ...(showLabel ? {} : { 'aria-label': label }),
+        }),
+        // "Clearing is an explicit named action", so it is a real button with a
+        // real name rather than an unlabelled cross. It is not a second tab
+        // stop: the input is the composite's only one.
+        clearable ? createElement('button', {
+          key: 'clear', type: 'button', className: 'ol8-combobox__clear', tabIndex: -1,
+          disabled, 'aria-label': `Clear ${label}`, onClick: onClear,
+        }, createElement(Icon, { name: 'clear', size: 18 })) : null,
+        createElement('span', { key: 'disc', className: 'ol8-combobox__disclosure', 'aria-hidden': 'true' },
+          createElement(Icon, { name: open ? 'chevron-up' : 'chevron-down', size: 18 })),
+      ])),
+    instruction ? createElement('div', { key: 'i', className: 'ol8-field__instruction', id: instructionId }, instruction) : null,
+    message ? createElement('div', { key: 'm', className: 'ol8-field__supporting' },
+      createElement(FormMessage, { tone: messageTone, id: messageId }, message)) : null,
+    createElement('div', { key: 'popup', className: 'ol8-combobox__popup', ...(open ? {} : { hidden: true }) },
+      createElement(SelectionPopup, {
+        id: popupId, label, options, selected: value, active,
+        width: popupWidth, size: size === 'large' ? 'large' : 'standard',
+        status, statusText,
+      })),
+  ]);
+}

package/src/organisms/MultiSelectField.js

@@ -0,0 +1,138 @@
+import { createElement, useId } from 'react';
+import { Token } from '../molecules/Token.js';
+import { SelectionPopup } from './SelectionPopup.js';
+import { OL8_MULTI_SELECT_SIZES, OL8_MULTI_SELECT_APPEARANCES,
+         OL8_MULTI_SELECT_MATERIALS, OL8_VALUE_POLICIES } from '../foundations/geometry.js';
+
+/**
+ * A committed value may be given as a bare string. In a constrained field that
+ * string is an option's value, so the token must show that option's label: a
+ * field holding "ui" reads "Interface", never "ui". Only a value with no
+ * matching option falls back to showing itself.
+ */
+const toEntry = (v, options) => {
+  if (typeof v !== 'string') return v;
+  const match = options.find(o => o.value === v);
+  return match ? { value: match.value, label: match.label } : { value: v, label: v };
+};
+
+/**
+ * ORGANISM. Several committed values in one field, built from the canonical
+ * Text Field, Token and Selection Popup owners exactly as the Figma organism
+ * is. Outline and Filled are one component with an appearance axis, because the
+ * two Figma sets differ only by which field owner they instantiate.
+ *
+ * The committed values and the editable input are siblings in one wrapping run,
+ * because they have to wrap together. The field grows rather than compressing
+ * tokens to hold one nominal row.
+ */
+export function MultiSelectField({
+  label, id, name, values = [], options = [],
+  valuePolicy = 'constrained', size = 'comfortable', appearance = 'outline',
+  material = 'regular', expanded = false, inputValue, placeholder,
+  maximumValues, allowDuplicates = false, showLabel = true, required = false,
+  disabled = false, readOnly = false, invalid = false, instruction, message,
+  messageTone = 'critical', status = 'none', statusText,
+  onRemoveValue, onInputValueChange, className = '', ...rest
+}) {
+  if (!label) throw new Error('[ol8] a Multi-select Field requires a label');
+  if (!OL8_MULTI_SELECT_SIZES.includes(size)) throw new Error(`[ol8] unknown size "${size}"`);
+  if (!OL8_MULTI_SELECT_APPEARANCES.includes(appearance)) throw new Error(`[ol8] unknown appearance "${appearance}"`);
+  if (!OL8_MULTI_SELECT_MATERIALS.includes(material)) throw new Error(`[ol8] unknown material "${material}"`);
+  if (!OL8_VALUE_POLICIES.includes(valuePolicy)) throw new Error(`[ol8] unknown value policy "${valuePolicy}"`);
+  if (readOnly && invalid) {
+    throw new Error('[ol8] a read only field cannot be invalid, because nobody can act on the message');
+  }
+
+  const committed = values.map(v => toEntry(v, options));
+  if (valuePolicy === 'constrained' && options.length) {
+    const known = new Set(options.map(o => o.value));
+    const stray = committed.find(v => !known.has(v.value));
+    if (stray) throw new Error(`[ol8] "${stray.value}" is not one of the options, and a constrained field may not hold an authored value`);
+  }
+  if (!allowDuplicates) {
+    const seen = new Set();
+    for (const v of committed) {
+      if (seen.has(v.value)) throw new Error(`[ol8] "${v.value}" is committed twice and allowDuplicates is false`);
+      seen.add(v.value);
+    }
+  }
+  if (maximumValues !== undefined && committed.length > maximumValues) {
+    throw new Error(`[ol8] ${committed.length} values exceed the maximum of ${maximumValues}`);
+  }
+
+  const auto = useId();
+  const uid = id ?? `ol8-multiselect-${auto}`;
+  const popupId = `${uid}-popup`;
+  const statusId = `${uid}-status`;
+  const instructionId = instruction ? `${uid}-instruction` : undefined;
+  const messageId = message ? `${uid}-message` : undefined;
+  const full = maximumValues !== undefined && committed.length >= maximumValues;
+  const locked = readOnly || disabled;
+  const describedBy = [instructionId, messageId, statusId].filter(Boolean).join(' ') || undefined;
+
+  return createElement('div', {
+    ...rest,
+    className: `ol8-multiselect${className ? ` ${className}` : ''}`,
+    'data-ol8-expanded': String(expanded),
+    'data-ol8-value-policy': valuePolicy,
+    ...(disabled ? { 'data-ol8-availability': 'disabled' } : {}),
+    ...(readOnly ? { 'data-ol8-readonly': 'true' } : {}),
+    ...(full ? { 'data-ol8-full': 'true' } : {}),
+  }, [
+    createElement('div', {
+      key: 'field',
+      className: 'ol8-field ol8-multiselect__field',
+      'data-ol8-size': size, 'data-ol8-appearance': appearance,
+      ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+      ...(invalid ? { 'data-ol8-validity': 'invalid' } : {}),
+      ...(disabled ? { 'data-ol8-availability': 'disabled' } : {}),
+    }, [
+      showLabel ? createElement('div', { key: 'lr', className: 'ol8-field__label-row' }, [
+        createElement('label', { key: 'l', className: 'ol8-field__label', htmlFor: uid }, label),
+        required ? createElement('span', { key: 'r', className: 'ol8-field__requirement', 'aria-hidden': 'true' }, '*') : null,
+      ]) : null,
+      createElement('div', { key: 'cs', className: 'ol8-field__control-stack' },
+        createElement('div', { key: 'c', className: 'ol8-field__control ol8-multiselect__control' }, [
+          ...committed.map((v, i) => createElement(Token, {
+            key: v.value, size, selected: true,
+            mark: locked ? 'none' : 'remove', removable: !locked, focusable: false,
+            className: 'ol8-multiselect__token',
+            id: `${uid}-token-${i}`,
+            onRemove: onRemoveValue ? () => onRemoveValue(v) : undefined,
+          }, v.label)),
+          createElement('input', {
+            key: 'input',
+            className: 'ol8-field__input ol8-multiselect__input', id: uid, name, type: 'text',
+            role: 'combobox', 'aria-expanded': String(expanded), 'aria-controls': popupId,
+            'aria-autocomplete': 'list', 'aria-haspopup': 'listbox',
+            ...(showLabel ? {} : { 'aria-label': label }),
+            ...(inputValue !== undefined
+              ? { value: inputValue, onChange: (e) => onInputValueChange && onInputValueChange(e.target.value) }
+              : {}),
+            placeholder, required, disabled, readOnly,
+            ...(invalid ? { 'aria-invalid': 'true', 'aria-errormessage': messageId } : {}),
+            ...(describedBy ? { 'aria-describedby': describedBy } : {}),
+          }),
+        ])),
+      instruction ? createElement('div', { key: 'i', className: 'ol8-field__instruction', id: instructionId }, instruction) : null,
+      message ? createElement('div', { key: 'm', className: 'ol8-field__supporting' },
+        createElement('span', {
+          className: 'ol8-field__message', id: messageId, 'data-ol8-tone': messageTone,
+          role: messageTone === 'critical' ? 'alert' : 'status',
+        }, message)) : null,
+    ]),
+    expanded
+      ? createElement(SelectionPopup, {
+          key: 'popup', id: popupId, label, options, multiple: true,
+          selected: committed.map(v => v.value),
+          width: 'anchor', size: size === 'large' ? 'large' : 'standard',
+          status, statusText, className: 'ol8-multiselect__popup',
+        })
+      : createElement('div', { key: 'popup', id: popupId, hidden: true }),
+    createElement('span', {
+      key: 'status', className: 'ol8-multiselect__status', id: statusId,
+      role: 'status', 'aria-live': 'polite',
+    }, full ? `Maximum of ${maximumValues} reached` : ''),
+  ]);
+}

package/src/organisms/SegmentedControl.js

@@ -0,0 +1,114 @@
+import { createElement, forwardRef, useCallback, useRef, useState } from 'react';
+import { OL8_SEGMENT_BEHAVIORS, OL8_SEGMENT_PRESENTATIONS, OL8_NAVIGATION_SIZES } from '../foundations/geometry.js';
+import { NavigationItem } from '../molecules/NavigationItem.js';
+
+/**
+ * ORGANISM. Figma 698:4792.
+ *
+ * "Behavior is a consuming contract: single = Radio Group, multi = independent
+ * Toggle Buttons, momentary = grouped actions." The contract says to declare
+ * exactly one, so this component refuses to guess and checks that the shape of
+ * `value` matches the behaviour that was declared.
+ *
+ * "Presentation never changes behavior", so nothing below reads presentation
+ * except to decide how an item lays its own content out.
+ */
+export const SegmentedControl = forwardRef(function SegmentedControl({
+  label, behavior, items = [], value, defaultValue, onChange,
+  presentation = 'inset-fill', size = 'standard', material = 'regular',
+  className = '', ...rest
+}, ref) {
+  if (typeof label !== 'string' || label === '') throw new Error('[ol8] a segmented control requires an accessible name.');
+  if (!OL8_SEGMENT_BEHAVIORS.includes(behavior)) {
+    throw new Error('[ol8] a segmented control must declare exactly one behavior: single, multi or momentary.');
+  }
+  if (!OL8_SEGMENT_PRESENTATIONS.includes(presentation)) throw new Error(`[ol8] unknown segmented control presentation "${presentation}"`);
+  if (!OL8_NAVIGATION_SIZES.includes(size)) throw new Error(`[ol8] unknown segmented control size "${size}"`);
+  if (!Array.isArray(items) || items.length === 0) throw new Error('[ol8] a segmented control needs at least one segment.');
+  if (behavior === 'multi' && value !== undefined && !Array.isArray(value)) {
+    throw new Error('[ol8] multi selection holds an array of values.');
+  }
+  if (behavior === 'single' && Array.isArray(value)) {
+    throw new Error('[ol8] single selection holds one value, not an array.');
+  }
+  if (behavior === 'momentary' && (value !== undefined || defaultValue !== undefined)) {
+    throw new Error('[ol8] a momentary control invokes an action and stores no selected state.');
+  }
+
+  const [internal, setInternal] = useState(defaultValue ?? (behavior === 'multi' ? [] : undefined));
+  const current = value ?? internal;
+  const groupRef = useRef(null);
+
+  const isSelected = (id) => {
+    if (behavior === 'momentary') return false;
+    if (behavior === 'multi') return Array.isArray(current) && current.includes(id);
+    return current === id;
+  };
+
+  const activate = useCallback((id) => {
+    if (behavior === 'momentary') { onChange?.(id); return; }
+    const next = behavior === 'multi'
+      ? (Array.isArray(current) && current.includes(id)
+          ? current.filter(v => v !== id)
+          : [...(current ?? []), id])
+      : id;
+    if (value === undefined) setInternal(next);
+    onChange?.(next);
+  }, [behavior, current, value, onChange]);
+
+  // Only single selection roves, because it is the only behaviour where the
+  // group holds one value. Multi and momentary are ordinary buttons in a row.
+  const onKeyDown = useCallback((event) => {
+    if (behavior !== 'single') return;
+    const buttons = [...(groupRef.current?.querySelectorAll('.ol8-nav-item--segment') ?? [])];
+    const at = buttons.indexOf(document.activeElement);
+    if (at === -1) return;
+    const rtl = getComputedStyle(groupRef.current).direction === 'rtl';
+    const forward = rtl ? 'ArrowLeft' : 'ArrowRight';
+    const back = rtl ? 'ArrowRight' : 'ArrowLeft';
+    let next = -1;
+    if (event.key === 'Home') next = items.findIndex(i => !i.disabled);
+    else if (event.key === 'End') next = items.map(i => !i.disabled).lastIndexOf(true);
+    else if (event.key === forward || event.key === back) {
+      const step = event.key === forward ? 1 : -1;
+      for (let hop = 1; hop <= items.length; hop += 1) {
+        const i = (at + step * hop + items.length * hop) % items.length;
+        if (!items[i].disabled) { next = i; break; }
+      }
+    }
+    if (next === -1 || next === at) return;
+    event.preventDefault();
+    buttons[next].focus();
+    activate(items[next].id);
+  }, [behavior, items, activate]);
+
+  const iconOnly = presentation === 'icon-only';
+  const layout = presentation === 'stacked-label' ? 'stacked' : 'inline';
+  const focusStop = behavior === 'single'
+    ? (items.find(i => isSelected(i.id) && !i.disabled) ?? items.find(i => !i.disabled))
+    : null;
+
+  return createElement('div', {
+    ...rest, ref: (node) => {
+      groupRef.current = node;
+      if (typeof ref === 'function') ref(node); else if (ref) ref.current = node;
+    },
+    className: `ol8-segmented${className ? ` ${className}` : ''}`,
+    role: behavior === 'single' ? 'radiogroup' : 'group',
+    'aria-label': label,
+    'data-ol8-presentation': presentation,
+    'data-ol8-behavior': behavior,
+    'data-ol8-size': size,
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+    onKeyDown,
+  }, items.map(item => createElement(NavigationItem, {
+    key: item.id, kind: 'segment', size, layout,
+    label: iconOnly ? undefined : item.label,
+    icon: item.icon, badge: item.badge,
+    ariaLabel: item.ariaLabel ?? (iconOnly ? item.label : undefined),
+    disabled: item.disabled,
+    selected: isSelected(item.id),
+    ...(focusStop ? { tabIndex: item.id === focusStop.id ? 0 : -1 } : {}),
+    onClick: () => activate(item.id),
+  })));
+});

package/src/organisms/SelectionPopup.js

@@ -0,0 +1,73 @@
+import { createElement } from 'react';
+import { Icon } from '../atoms/Icon.js';
+import { SelectionOption } from '../molecules/SelectionOption.js';
+import { OL8_POPUP_WIDTHS, OL8_POPUP_SIZES, OL8_POPUP_STATUSES } from '../foundations/geometry.js';
+
+/**
+ * ORGANISM. The option collection a Select, Combobox or Multi-select Field
+ * points at. It owns no focus: a listbox moves a virtual cursor with
+ * aria-activedescendant while real focus stays on the input that owns it.
+ *
+ * A status is a region, never an option, because "No results" is not something
+ * a person can choose.
+ */
+export function SelectionPopup({
+  id, label, options = [], selected, active, width = 'anchor', size = 'standard',
+  status = 'none', statusText, multiple = false, className = '', ...rest
+}) {
+  if (!id) throw new Error('[ol8] a selection popup needs an id, because the combobox that owns it points at it.');
+  if (typeof label !== 'string' || label === '') {
+    throw new Error('[ol8] a listbox requires an accessible name, distinct from the value it holds.');
+  }
+  if (!OL8_POPUP_WIDTHS.includes(width)) throw new Error(`[ol8] unknown popup width "${width}"`);
+  if (!OL8_POPUP_SIZES.includes(size)) throw new Error(`[ol8] unknown popup size "${size}"`);
+  if (!OL8_POPUP_STATUSES.includes(status)) throw new Error(`[ol8] unknown popup status "${status}"`);
+  if (status !== 'none' && !statusText) {
+    throw new Error('[ol8] a popup status needs words. A spinner alone tells a screen reader nothing.');
+  }
+
+  const isSelected = (value) => Array.isArray(selected) ? selected.includes(value) : selected === value;
+
+  // Grouped results keep their source order; grouping never reorders matches.
+  const groups = [];
+  for (const item of options) {
+    const name = item.group ?? null;
+    const last = groups[groups.length - 1];
+    if (last && last.name === name) last.items.push(item);
+    else groups.push({ name, items: [item] });
+  }
+
+  const rail = groups.map((group, index) => {
+    const groupId = group.name ? `${id}-group-${index}` : null;
+    const rendered = group.items.map(item => createElement(SelectionOption, {
+      key: item.value, value: item.value, size,
+      selected: isSelected(item.value), active: item.value === active,
+      disabled: item.disabled, description: item.description,
+      leadingIcon: item.leadingIcon, id: `${id}-option-${item.value}`,
+    }, item.label));
+    if (!group.name) return rendered;
+    return createElement('div', { key: `g${index}`, role: 'group', 'aria-labelledby': groupId }, [
+      createElement('span', { key: 'l', className: 'ol8-popup__group-label', id: groupId }, group.name),
+      ...rendered,
+    ]);
+  });
+
+  return createElement('div', {
+    ...rest,
+    className: `ol8-popup${className ? ` ${className}` : ''}`,
+    'data-ol8-width': width, 'data-ol8-size': size,
+  }, [
+    createElement('div', {
+      key: 'rail', className: 'ol8-popup__rail', role: 'listbox', id, 'aria-label': label,
+      ...(multiple ? { 'aria-multiselectable': 'true' } : {}),
+    }, rail),
+    status === 'none' ? null : createElement('div', {
+      key: 'status', className: 'ol8-popup__status', 'data-ol8-status': status,
+      role: 'status', 'aria-live': 'polite',
+    }, [
+      status === 'loading' ? createElement(Icon, { key: 'i', name: 'loading', size: 18 }) : null,
+      status === 'error' ? createElement(Icon, { key: 'i', name: 'critical', size: 18 }) : null,
+      createElement('span', { key: 's' }, statusText),
+    ]),
+  ]);
+}

package/src/organisms/TabBar.js

@@ -0,0 +1,68 @@
+import { createElement, forwardRef, useCallback } from 'react';
+import { OL8_TAB_BAR_PRESENTATIONS, OL8_NAVIGATION_SIZES } from '../foundations/geometry.js';
+import { NavigationItem } from '../molecules/NavigationItem.js';
+
+/**
+ * ORGANISM. Figma 701:460.
+ *
+ * "Production uses native destination links, requires a non empty navigation
+ * name, resolves exactly one current destination, and rejects disabled pseudo
+ * destinations."
+ *
+ * `onNavigate` lets a router take over without replacing link semantics: the
+ * destination stays a real link, so opening in a new tab, copying the address
+ * and middle clicking all keep working.
+ */
+export const TabBar = forwardRef(function TabBar({
+  label, items = [], current, onNavigate,
+  presentation = 'bottom', size = 'standard', material = 'regular',
+  className = '', ...rest
+}, ref) {
+  if (typeof label !== 'string' || label === '') {
+    throw new Error('[ol8] a tab bar requires a navigation name, so a person can tell one landmark from another.');
+  }
+  if (!OL8_TAB_BAR_PRESENTATIONS.includes(presentation)) throw new Error(`[ol8] unknown tab bar presentation "${presentation}"`);
+  if (!OL8_NAVIGATION_SIZES.includes(size)) throw new Error(`[ol8] unknown tab bar size "${size}"`);
+  if (!Array.isArray(items) || items.length === 0) throw new Error('[ol8] a tab bar needs at least one destination.');
+  const seen = new Set();
+  for (const item of items) {
+    if (typeof item.href !== 'string' || item.href === '') {
+      throw new Error('[ol8] every destination needs an href. A tab bar navigates, so it uses real links.');
+    }
+    if (item.disabled) {
+      throw new Error('[ol8] a destination cannot be disabled. Remove the place rather than showing a door that does not open.');
+    }
+    if (seen.has(item.href)) throw new Error(`[ol8] two destinations share the href "${item.href}"`);
+    seen.add(item.href);
+  }
+  if (current !== undefined && !seen.has(current)) {
+    throw new Error(`[ol8] the current destination "${current}" is not one of the destinations listed.`);
+  }
+
+  const handleClick = useCallback((href) => (event) => {
+    if (!onNavigate) return;
+    if (event.defaultPrevented || event.button !== 0) return;
+    if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    event.preventDefault();
+    onNavigate(href, event);
+  }, [onNavigate]);
+
+  // The spatial rail carries no labels, so a name has to come from somewhere.
+  const iconOnly = presentation === 'spatial-rail';
+
+  return createElement('nav', {
+    ...rest, ref,
+    className: `ol8-tab-bar${className ? ` ${className}` : ''}`,
+    'aria-label': label,
+    'data-ol8-presentation': presentation,
+    'data-ol8-size': size,
+    ...(material === 'gem' ? { 'data-ol8-material': 'gem' } : {}),
+  }, items.map(item => createElement(NavigationItem, {
+    key: item.href, kind: 'destination', size,
+    label: iconOnly ? undefined : item.label,
+    icon: item.icon, badge: item.badge, href: item.href,
+    ariaLabel: item.ariaLabel ?? (iconOnly ? item.label : undefined),
+    selected: item.href === current,
+    onClick: handleClick(item.href),
+  })));
+});