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

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