@oneli8/core 1.0.0-beta.10

package/src/molecules/choice-chip/choice-chip.js

@@ -0,0 +1,170 @@
+/**
+ * Oneli8 · Choice Chip (MOLECULE) — the Soft Hexagon.
+ *
+ * Figma: Select and Combobox / Choice Chip / Soft Hexagon 636:847 (8 variants,
+ * Size x Selection, plus a Label text property and a Show Mark boolean).
+ *
+ * From the Figma description:
+ *   "Compact/Standard/Comfortable/Large use approved 30/36/42/42px visible
+ *    geometry inside protected 48/48/48/60px targets. Fixed 12px terminals and
+ *    tokenized 9/12/15/15px inner rail insets preserve one silhouette at every
+ *    label width."
+ *
+ * Figma builds the silhouette from three boxes, and so does this: a fixed 12px
+ * left terminal, a centre rail that grows with the label, and a mirrored right
+ * terminal. Only the rail grows, which is why a short chip and a long chip keep
+ * the same shoulder depth and side angle. The contract is explicit that ends
+ * which scale with the text are prohibited.
+ *
+ * WHY SVG RATHER THAN clip-path
+ * The terminals are not polygons. Each has three small curves softening the
+ * shoulders and the point, and the contract rejects approximating that softness
+ * with extra vertices because it reads as an Octagon. `clip-path: polygon()`
+ * can only draw straight vertices, so the terminals are real paths.
+ *
+ * HOW ONE PATH SERVES FOUR HEIGHTS
+ * Read from Figma, every terminal path at 30, 36 and 42 has identical X values
+ * and Y values that scale exactly with the height: 1/36, 1/12, 5/12, 11/24,
+ * 13/24, 7/12, 11/12, 35/36 of the height, at every size. So one viewBox of
+ * 12 x 30 with `preserveAspectRatio="none"` and a fixed 12px width reproduces
+ * Figma at all four sizes: the height stretches, the width cannot.
+ * `vector-effect="non-scaling-stroke"` keeps the edge an even 2px through that
+ * uneven stretch.
+ *
+ * THE OPEN EDGE
+ * Figma draws two vectors per terminal: a closed fill and an open outline that
+ * "deliberately omits the hidden vertical closing edge", so the rail's own top
+ * and bottom borders continue the perimeter without a doubled seam. This keeps
+ * that construction. Figma reaches an inside stroke by scaling the outline path
+ * to 98.75% of the width; here the edge is clipped to the fill instead, which
+ * is the same rendered result stated directly.
+ */
+import { renderIconSvg } from '../../atoms/icon/icon.js';
+
+export const OL8_CHIP_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+
+/**
+ * The terminal, in the 12 x 30 space Figma draws it in. The closed path is the
+ * fill; the open one is the perimeter, missing the seam edge at x=12.
+ */
+export const OL8_CHIP_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';
+export const OL8_CHIP_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';
+
+/**
+ * One terminal. `side` only picks a class; the right terminal is the left one
+ * mirrored in CSS, so the two can never drift apart.
+ *
+ * The focus bands are strokes on the same path, painted before the fill and at
+ * double width, so their inner half lands under the fill and the visible half
+ * sits outside the silhouette. That is how a ring follows a hexagon instead of
+ * boxing it.
+ */
+function renderTerminal(uid, side) {
+  const clip = `${uid}-clip-${side}`;
+  return `<svg class="ol8-chip__terminal ol8-chip__terminal--${side}" viewBox="0 0 12 30" ` +
+    `preserveAspectRatio="none" aria-hidden="true" focusable="false">` +
+    `<clipPath id="${clip}"><path d="${OL8_CHIP_TERMINAL_FILL}"/></clipPath>` +
+    `<path class="ol8-chip__focus-outer" d="${OL8_CHIP_TERMINAL_EDGE}"/>` +
+    `<path class="ol8-chip__focus-inner" d="${OL8_CHIP_TERMINAL_EDGE}"/>` +
+    `<path class="ol8-chip__fill" d="${OL8_CHIP_TERMINAL_FILL}"/>` +
+    `<path class="ol8-chip__edge" d="${OL8_CHIP_TERMINAL_EDGE}" clip-path="url(#${clip})"/>` +
+    `</svg>`;
+}
+
+/**
+ * The silhouette plus its rail contents. Private: Figma names this the
+ * "Choice Chip / Geometry Owner" and both the public chip and the Token
+ * instantiate it rather than redrawing it.
+ *
+ * `mark` is markup for the rail's trailing slot, or an empty string. 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 renderChipShape(uid, label, mark = '') {
+  return renderTerminal(uid, 'leading') +
+    `<span class="ol8-chip__rail">` +
+      `<span class="ol8-chip__label">${escapeText(label)}</span>` +
+      mark +
+    `</span>` +
+    renderTerminal(uid, 'trailing');
+}
+
+/**
+ * A Choice Chip is a real checkbox. The contract is explicit: "Every option is
+ * a real Checkbox rendered with the approved quiet Choice Chip appearance",
+ * with "native checked state" among the redundant cues, so selection is never
+ * carried by colour alone.
+ *
+ * @param {string} label
+ * @param {{size?:string,selected?:boolean,showMark?:boolean,disabled?:boolean,
+ *          name?:string,value?:string,id?:string,className?:string}} [options]
+ */
+export function renderChoiceChip(label, options = {}) {
+  const {
+    size = 'standard', selected = false, showMark = false, disabled = false,
+    name, value, id, className,
+  } = options;
+
+  if (!OL8_CHIP_SIZES.includes(size)) throw new Error(`[ol8] unknown chip size "${size}"`);
+  if (!label || !String(label).trim()) throw new Error('[ol8] Choice Chip requires a label');
+
+  const uid = id ?? `ol8-chip-${Math.random().toString(36).slice(2, 9)}`;
+  const mark = showMark
+    ? `<span class="ol8-chip__mark" aria-hidden="true">${renderIconSvg('check')}</span>`
+    : '';
+
+  const inputAttrs = [
+    'type="checkbox"', 'class="ol8-chip__input"', `id="${uid}"`,
+    name ? `name="${escapeAttr(name)}"` : '',
+    value !== undefined ? `value="${escapeAttr(value)}"` : '',
+    selected ? 'checked' : '', disabled ? 'disabled' : '',
+  ].filter(Boolean).join(' ');
+
+  const rowAttrs = [
+    `class="ol8-chip${className ? ` ${className}` : ''}"`,
+    `for="${uid}"`,
+    `data-ol8-size="${size}"`,
+    `data-ol8-selection="${selected ? 'selected' : 'inactive'}"`,
+    `data-ol8-availability="${disabled ? 'disabled' : 'enabled'}"`,
+  ].filter(Boolean).join(' ');
+
+  return `<label ${rowAttrs}><input ${inputAttrs}>${renderChipShape(uid, label, mark)}</label>`;
+}
+
+/**
+ * Keeps each chip's Selection attribute in step with its input. A chip in a
+ * group is an ordinary checkbox, so the browser owns the toggling; this only
+ * mirrors the result onto the attribute the stylesheet reads.
+ */
+export function hydrateChoiceChips(root = document) {
+  const chips = [...root.querySelectorAll('.ol8-chip')];
+  for (const chip of chips) {
+    const input = chip.querySelector(':scope > .ol8-chip__input');
+    if (!input) continue;
+    syncChip(chip);
+    if (chip.dataset.ol8ChipBound === 'true') continue;
+    input.addEventListener('change', () => syncChip(chip));
+    chip.dataset.ol8ChipBound = 'true';
+  }
+  return chips.length;
+}
+
+/** Repaints one chip from the live state of its input. */
+export function syncChip(chip) {
+  const input = chip.querySelector(':scope > .ol8-chip__input');
+  if (!input) return;
+  chip.dataset.ol8Selection = input.checked ? 'selected' : 'inactive';
+  chip.dataset.ol8Availability = input.disabled ? 'disabled' : 'enabled';
+}
+
+/* Private. Exported only so Token can reuse the same escaping; neither name
+   reaches the package index. */
+export function escapeAttr(v) { return String(v).replace(/&/g,'&amp;').replace(/"/g,'&quot;').replace(/</g,'&lt;'); }
+function escapeText(v) { return String(v).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;'); }

package/src/molecules/choice-chip/index.d.ts

@@ -0,0 +1,2 @@
+export { OL8_CHIP_SIZES, renderChoiceChip, hydrateChoiceChips, syncChip } from './choice-chip.js';
+export type { Ol8ChipSize, Ol8ChoiceChipOptions } from './choice-chip.js';

package/src/molecules/choice-chip/index.js

@@ -0,0 +1,10 @@
+/**
+ * The public surface. The terminal paths, the shape composer and the escape
+ * helpers stay module private on purpose: Figma names the terminals "Private
+ * Geometry" and the contract is explicit that they "are private construction
+ * inside the canonical Choice Chip molecule ... not published cap atoms, layer
+ * variants, or independently swappable components". Token reaches them by
+ * importing the module directly, exactly as its Figma counterpart instantiates
+ * the Geometry Owner.
+ */
+export { OL8_CHIP_SIZES, renderChoiceChip, hydrateChoiceChips, syncChip } from './choice-chip.js';

package/src/molecules/choice-item/choice-item.css

@@ -0,0 +1,265 @@
+/**
+ * Oneli8 · Choice Item (MOLECULE)
+ * Figma: Documentation / Molecule / Choice Item
+ *   Checkbox 252:301 (24 variants) · Radio 331:1309 (16) · Switch 825:1591 (16)
+ *
+ * From the Figma description (252:301):
+ *   "Selection maps Unchecked/Checked/Mixed to checked/indeterminate;
+ *    Availability maps enabled/disabled ... The indicator is a shared
+ *    selection atom, not local artwork. Native input, name/value, required,
+ *    reset, form submission, and onCheckedChange live in code."
+ *
+ * So the molecule is: a real <input>, the selection-indicator atom, a label,
+ * an optional description — and NOTHING that duplicates native behaviour.
+ *
+ * ANATOMY (Figma 266:257 / 252:74 / 252:77)
+ *   <label class=ol8-choice>          the whole row is the target
+ *     input                            visually hidden, still focusable
+ *     __surface                        hover / pressed / gem wash, bleeds 9px inline
+ *     __indicator                      slot: indicator wide, label-line tall
+ *     __content                        label + optional description
+ *
+ * ROW GEOMETRY — every size resolves to the same 48px minimum row:
+ *   size         gap  indicator  slot h   label          padding-block
+ *   compact       6      18        18     Body/Small      15
+ *   standard      9      18        24     Body/Medium     12
+ *   comfortable   9      24        24     Body/Medium     12
+ *   large         9      24        30     Body/Large       9
+ * padding-block is derived: (48 - slot height) / 2.
+ */
+
+.ol8-choice {
+  --_gap:    var(--ol8-component-choice-gap-standard);
+  --_slot-h: var(--ol8-font-line-024);
+  --_pad:    calc((var(--ol8-component-choice-rowminimum) - var(--_slot-h)) / 2);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+  --_indicator: var(--ol8-size-icon-small);
+  /* The hover / pressed / focus wash bleeds outside the text column. */
+  --_bleed: var(--ol8-dimension-scale-009);
+
+  box-sizing: border-box;
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  gap: var(--_gap);
+  min-block-size: var(--ol8-component-choice-rowminimum);
+  padding-block: var(--_pad);
+  font-family: var(--ol8-font-family-functional);
+  font-variation-settings: "ARRR" var(--ol8-font-axis-arrr-baseline);
+  cursor: pointer;
+}
+.ol8-choice[data-ol8-availability="disabled"] { cursor: not-allowed; }
+
+/* ---- Size ------------------------------------------------------------ */
+.ol8-choice[data-ol8-size="compact"] {
+  --_gap: var(--ol8-component-choice-gap-compact);
+  --_slot-h: var(--ol8-font-line-018);
+  --_label-size: var(--ol8-font-size-012);
+  --_label-line: var(--ol8-font-line-018);
+  --_indicator: var(--ol8-size-icon-small);
+}
+.ol8-choice[data-ol8-size="standard"] {
+  --_slot-h: var(--ol8-font-line-024);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+  --_indicator: var(--ol8-size-icon-small);
+}
+.ol8-choice[data-ol8-size="comfortable"] {
+  --_slot-h: var(--ol8-font-line-024);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+  --_indicator: var(--ol8-size-icon-standard);
+}
+.ol8-choice[data-ol8-size="large"] {
+  --_slot-h: var(--ol8-font-line-030);
+  --_label-size: var(--ol8-font-size-021);
+  --_label-line: var(--ol8-font-line-030);
+  --_indicator: var(--ol8-size-icon-standard);
+}
+/* Compact's label carries the Body/Small tracking. */
+.ol8-choice[data-ol8-size="compact"] .ol8-choice__label { letter-spacing: 1px; }
+
+/* ---- The native input owns everything semantic ----------------------- */
+.ol8-choice__input {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  opacity: 0;
+  pointer-events: none;
+  /* No margin reset needed — it is absolutely positioned, so margin cannot
+     affect layout. The structure lint would reject one regardless. */
+}
+
+/* ---- Wash: hover, pressed, focus, gem -------------------------------- */
+.ol8-choice__surface {
+  position: absolute;
+  inset-block: 0;
+  inset-inline: calc(-1 * var(--_bleed));
+  border-radius: var(--ol8-shape-radius-medium);
+  pointer-events: none;
+}
+.ol8-choice:hover:not([data-ol8-availability="disabled"]) > .ol8-choice__surface,
+.ol8-choice:active:not([data-ol8-availability="disabled"]) > .ol8-choice__surface {
+  background: var(--ol8-color-selection-surface);
+}
+
+/* Two nested rings, both visible — outer 3px, inner 3px at a 2px inset.
+   This is the same two-tone ring the Icon Button focus tokens describe. */
+.ol8-choice:has(> .ol8-choice__input:focus-visible) > .ol8-choice__surface {
+  border: var(--ol8-focus-ring-outerwidth) solid var(--ol8-color-focus-outer);
+}
+.ol8-choice:has(> .ol8-choice__input:focus-visible) > .ol8-choice__surface::after {
+  content: "";
+  position: absolute;
+  inset: 2px;
+  border: var(--ol8-focus-ring-innerwidth) solid var(--ol8-color-focus-inner);
+  border-radius: 7px;
+}
+
+/* ---- Indicator slot -------------------------------------------------- */
+.ol8-choice__indicator {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+  flex: none;
+  inline-size: var(--_indicator);
+  block-size: var(--_slot-h);
+}
+
+/* Invalid draws an extra boundary over the indicator, same shape. */
+.ol8-choice[data-ol8-invalid="true"] .ol8-choice__indicator::after {
+  content: "";
+  position: absolute;
+  inline-size: var(--_indicator);
+  block-size: var(--_indicator);
+  border: var(--ol8-component-checkbox-boundary) solid var(--ol8-color-feedbackcritical-inlinecontent);
+  border-radius: var(--ol8-component-checkbox-radius-compact);
+  pointer-events: none;
+}
+.ol8-choice[data-ol8-size="comfortable"][data-ol8-invalid="true"] .ol8-choice__indicator::after,
+.ol8-choice[data-ol8-size="large"][data-ol8-invalid="true"] .ol8-choice__indicator::after {
+  border-radius: var(--ol8-component-checkbox-radius-comfortable);
+}
+.ol8-choice--radio[data-ol8-invalid="true"] .ol8-choice__indicator::after {
+  border-radius: var(--ol8-shape-radius-full);
+}
+
+/* ---- Content --------------------------------------------------------- */
+.ol8-choice__content {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ol8-dimension-scale-003);
+  flex: 1 0 0;
+  min-inline-size: 0;
+  position: relative;
+}
+.ol8-choice__label {
+  font-size: var(--_label-size);
+  line-height: var(--_label-line);
+  font-weight: var(--ol8-font-weight-regular);
+  color: var(--ol8-color-text-primary);
+  overflow-wrap: break-word;
+}
+.ol8-choice__description {
+  font-size: var(--ol8-font-size-012);
+  line-height: var(--ol8-font-line-018);
+  letter-spacing: 0.12px;
+  color: var(--ol8-color-text-secondary);
+  overflow-wrap: break-word;
+}
+.ol8-choice[data-ol8-availability="disabled"] .ol8-choice__label,
+.ol8-choice[data-ol8-availability="disabled"] .ol8-choice__description {
+  color: var(--ol8-color-text-disabled);
+}
+
+/* ---- Gem material ----------------------------------------------------
+   "Gem is one Boolean material adapter over the same anatomy; Regular
+   remains the default." A wash on the row, not a different component. */
+.ol8-choice[data-ol8-material="gem"] > .ol8-choice__surface {
+  background: var(--ol8-material-gem-color-quiet-environmentalface);
+  border: 1px solid var(--ol8-material-gem-color-cutedge-high);
+  border-radius: var(--ol8-shape-radius-standard);
+  inset-inline: 0;
+}
+/* The quiet face is clear glass — near-white at 0.18/0.27, not a dark tint —
+   so it cannot guarantee what sits behind it at all. Content on it therefore
+   takes the stable near-white gem ink rather than body text, and carries its
+   own halo, which is the only thing standing between the label and whatever
+   the environment happens to be. Unlike the gem text field, the label and
+   description here really are on the face: .ol8-choice__surface spans the row
+   beneath them. Disabled is excluded — it resolves to the opaque equivalent,
+   where the regular disabled ink applies and no halo is wanted. */
+/* ONE GLOW, TWO SYNTAXES.
+   Content on Gem means ALL content — glyphs and control geometry alike. Text
+   takes the halo through text-shadow; an SVG stroke cannot, so the indicator
+   takes the identical halo through chained drop-shadow filters. Both are built
+   from the same two tokens and the same four repetitions, which is what makes
+   the label's glow and the checkbox's glow read as one field rather than two
+   near-misses. Change the radius or the colour and both follow. */
+.ol8-choice[data-ol8-material="gem"] {
+  --_gem-glow: 0 0 var(--ol8-material-gem-blur-contentglow)
+               var(--ol8-material-gem-color-quiet-contentglow);
+  /* Control geometry takes one stack FEWER than text, on purpose. WCAG 1.4.11
+     asks 3:1 of a graphical object where 1.4.3 asks 4.5:1 of text, so the
+     boundary does not need the fourth repetition — and leaving it off is what
+     keeps the indicator blended into the glass instead of ringed. Measured at
+     3px: text in four stacks is 5.06:1, the boundary in three is 3.75:1. */
+  --_gem-glow-filter:
+    drop-shadow(var(--_gem-glow)) drop-shadow(var(--_gem-glow))
+    drop-shadow(var(--_gem-glow));
+}
+
+/* DISABLED ON GEM IS ONE GREY, SHARED.
+   color.text.disabled is dark in the Light appearance, so a disabled row on
+   glass whose enabled content is near-white ended up with a dark label beside
+   a dark box — it read broken rather than unavailable. On Gem, disabled text
+   and disabled control geometry take the SAME whitish grey, and neither takes
+   the halo: the absence of the glow is part of how unavailable reads.
+   Disabled content is exempt from 1.4.3, which excludes inactive controls. */
+.ol8-choice[data-ol8-material="gem"][data-ol8-availability="disabled"] .ol8-choice__label,
+.ol8-choice[data-ol8-material="gem"][data-ol8-availability="disabled"] .ol8-choice__description {
+  color: var(--ol8-material-gem-color-quiet-contentdisabled);
+  text-shadow: none;
+}
+.ol8-choice[data-ol8-material="gem"][data-ol8-availability="disabled"] .ol8-selection {
+  --_edge: var(--ol8-material-gem-color-quiet-contentdisabled);
+  --_ink: var(--ol8-material-gem-color-quiet-contentdisabled);
+  filter: none;
+}
+
+/* The unselected control boundary is content, not chrome. It was
+   color.border.strong, which is dark in the Light appearance and left the
+   checkbox reading as a dark hole in a surface whose text had gone near-white.
+   On Gem it takes the same ink as the label. Selected and mixed are untouched:
+   those fill with the primary action family and carry their own white mark,
+   which already reads on glass. */
+.ol8-choice[data-ol8-material="gem"]:not([data-ol8-availability="disabled"]) .ol8-selection {
+  --_edge: var(--ol8-material-gem-color-quiet-content);
+  filter: var(--_gem-glow-filter);
+}
+
+/* Any iconography sitting on the face takes the token that already exists for
+   exactly this and is already stable across appearances. */
+.ol8-choice[data-ol8-material="gem"]:not([data-ol8-availability="disabled"]) .ol8-icon {
+  color: var(--ol8-color-icon-on-gem);
+  filter: var(--_gem-glow-filter);
+}
+
+.ol8-choice[data-ol8-material="gem"]:not([data-ol8-availability="disabled"]) .ol8-choice__label,
+.ol8-choice[data-ol8-material="gem"]:not([data-ol8-availability="disabled"]) .ol8-choice__description {
+  color: var(--ol8-material-gem-color-quiet-content);
+  /* Stacked three times on purpose. A single shadow at this radius reaches
+     only 1.71:1 against near-white ink on a bright plate, and widening the
+     radius makes it WEAKER because blur spreads a fixed alpha budget over more
+     area. Repeating the same shadow accumulates alpha instead of spreading it:
+     1 - (1 - a)^4. Measured in proof/gem-halo-contrast.html. */
+  text-shadow: var(--_gem-glow), var(--_gem-glow),
+               var(--_gem-glow), var(--_gem-glow);
+}
+@media (prefers-reduced-transparency: reduce) {
+  .ol8-choice[data-ol8-material="gem"] > .ol8-choice__surface {
+    background: var(--ol8-material-gem-color-quiet-opaqueequivalent);
+  }
+}

package/src/molecules/choice-item/choice-item.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Choice Item (MOLECULE) — headless behavior around a real <input>. It does not
+ * reimplement toggling, focus or form participation; the native input does all
+ * of it. `indeterminate` is the one thing markup cannot express, which is why
+ * the Mixed state needs hydration and the other states do not.
+ */
+import type { Ol8IconName } from '../../atoms/icon/icons.generated.js';
+import type { Ol8Selection, Ol8SelectionSize } from '../../atoms/selection-indicator/selection-indicator.js';
+
+export type Ol8ChoiceKind = 'checkbox' | 'radio' | 'switch';
+export type Ol8ChoiceSize = 'compact' | 'standard' | 'comfortable' | 'large';
+
+export declare const OL8_CHOICE_KINDS: readonly Ol8ChoiceKind[];
+export declare const OL8_CHOICE_SIZES: readonly Ol8ChoiceSize[];
+
+/** The molecule's four sizes map onto the atom's two. */
+export declare function indicatorSizeFor(size: Ol8ChoiceSize): Ol8SelectionSize;
+
+/** Figma's Selection axis, derived from native input state. */
+export declare function selectionStateFor(
+  kind: Ol8ChoiceKind,
+  state?: { checked?: boolean; mixed?: boolean },
+): Ol8Selection;
+
+export interface Ol8ChoiceItemOptions {
+  size?: Ol8ChoiceSize;
+  checked?: boolean;
+  /** Checkbox only. Renders Mixed; the real indeterminate flag is set on hydrate. */
+  mixed?: boolean;
+  disabled?: boolean;
+  invalid?: boolean;
+  /** Associated with aria-describedby, kept out of the accessible name. */
+  description?: string;
+  name?: string;
+  value?: string;
+  required?: boolean;
+  id?: string;
+  material?: 'regular' | 'gem';
+  className?: string;
+}
+
+export declare function renderChoiceItem(
+  kind: Ol8ChoiceKind,
+  label: string,
+  options?: Ol8ChoiceItemOptions,
+): string;
+
+/** Applies the JS-only indeterminate flag to Mixed rows. Idempotent. */
+export declare function hydrateChoiceItems(root?: ParentNode): void;
+
+/** Repaints one row's indicator from its input's current state. */
+export declare function syncIndicator(row: Element): void;
+
+export declare function setChoiceMixed(row: Element, mixed: boolean): void;

package/src/molecules/choice-item/choice-item.js

@@ -0,0 +1,153 @@
+/**
+ * Oneli8 · Choice Item (MOLECULE) — headless behavior.
+ *
+ * Figma (252:301): "Native input, name/value, required, reset, form
+ * submission, and onCheckedChange live in code." This module is that code —
+ * and deliberately nothing more. It does not reimplement toggling, focus or
+ * form participation; a real <input> already does all of it.
+ *
+ * The one thing that genuinely cannot be expressed in markup or CSS is
+ * `indeterminate`, which is a JS-only property. That is why the Mixed state
+ * needs hydration and the other states do not.
+ */
+import { renderSelectionIndicator } from '../../atoms/selection-indicator/selection-indicator.js';
+
+export const OL8_CHOICE_KINDS = ['checkbox', 'radio', 'switch'];
+export const OL8_CHOICE_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+
+/** The molecule's four sizes map onto the atom's two. */
+export function indicatorSizeFor(size) {
+  return size === 'comfortable' || size === 'large' ? 'comfortable' : 'compact';
+}
+
+/** Figma's Selection axis, derived from native input state. */
+export function selectionStateFor(kind, { checked = false, mixed = false } = {}) {
+  if (kind === 'checkbox') return mixed ? 'mixed' : checked ? 'checked' : 'unchecked';
+  if (kind === 'radio') return checked ? 'selected' : 'unselected';
+  return checked ? 'on' : 'off';
+}
+
+/**
+ * @param {'checkbox'|'radio'|'switch'} kind
+ * @param {string} label
+ * @param {{size?:string,checked?:boolean,mixed?:boolean,disabled?:boolean,invalid?:boolean,
+ *          description?:string,name?:string,value?:string,required?:boolean,
+ *          id?:string,material?:string,className?:string}} [options]
+ */
+export function renderChoiceItem(kind, label, options = {}) {
+  if (!OL8_CHOICE_KINDS.includes(kind)) throw new Error(`[ol8] unknown choice kind "${kind}"`);
+  const {
+    size = 'standard', checked = false, mixed = false, disabled = false, invalid = false,
+    description, name, value, required = false, id, material = 'regular', className,
+  } = options;
+
+  if (!OL8_CHOICE_SIZES.includes(size)) throw new Error(`[ol8] unknown choice size "${size}"`);
+  if (mixed && kind !== 'checkbox') throw new Error('[ol8] only a checkbox has a Mixed state');
+  if (!label || !String(label).trim()) throw new Error('[ol8] Choice Item requires a label');
+
+  const uid = id ?? `ol8-choice-${Math.random().toString(36).slice(2, 9)}`;
+  const descId = description ? `${uid}-desc` : null;
+  const selection = selectionStateFor(kind, { checked, mixed });
+
+  const inputAttrs = [
+    `type="${kind === 'radio' ? 'radio' : 'checkbox'}"`,
+    kind === 'switch' ? 'role="switch"' : '',
+    `class="ol8-choice__input"`,
+    `id="${uid}"`,
+    name ? `name="${escapeAttr(name)}"` : '',
+    value !== undefined ? `value="${escapeAttr(value)}"` : '',
+    checked ? 'checked' : '',
+    disabled ? 'disabled' : '',
+    required ? 'required' : '',
+    invalid ? 'aria-invalid="true"' : '',
+    descId ? `aria-describedby="${descId}"` : '',
+  ].filter(Boolean).join(' ');
+
+  const rowAttrs = [
+    `class="ol8-choice ol8-choice--${kind}${className ? ` ${className}` : ''}"`,
+    `for="${uid}"`,
+    `data-ol8-size="${size}"`,
+    `data-ol8-kind="${kind}"`,
+    `data-ol8-availability="${disabled ? 'disabled' : 'enabled'}"`,
+    invalid ? 'data-ol8-invalid="true"' : '',
+    mixed ? 'data-ol8-mixed="true"' : '',
+    material === 'gem' ? 'data-ol8-material="gem"' : '',
+  ].filter(Boolean).join(' ');
+
+  const indicator = renderSelectionIndicator(kind, {
+    selection, size: indicatorSizeFor(size), disabled,
+  });
+
+  return `<label ${rowAttrs}>` +
+    `<input ${inputAttrs}>` +
+    `<span class="ol8-choice__surface" aria-hidden="true"></span>` +
+    `<span class="ol8-choice__indicator">${indicator}</span>` +
+    `<span class="ol8-choice__content">` +
+      `<span class="ol8-choice__label">${escapeText(label)}</span>` +
+      (description ? `<span class="ol8-choice__description" id="${descId}">${escapeText(description)}</span>` : '') +
+    `</span></label>`;
+}
+
+/**
+ * Binds every `.ol8-choice` under `root`. Idempotent.
+ * Applies `indeterminate` (JS-only) and keeps the indicator in step with the
+ * input — including radios, where selecting one silently clears its siblings.
+ */
+export function hydrateChoiceItems(root = document) {
+  const rows = [...root.querySelectorAll('.ol8-choice')];
+
+  for (const row of rows) {
+    const input = row.querySelector(':scope > .ol8-choice__input');
+    if (!input) continue;
+
+    input.indeterminate = row.dataset.ol8Mixed === 'true';
+    syncIndicator(row);
+
+    if (row.dataset.ol8ChoiceBound === 'true') continue;
+    input.addEventListener('change', () => {
+      // Any interaction resolves Mixed; the browser has already cleared
+      // `indeterminate` on click, so mirror that in our own state.
+      delete row.dataset.ol8Mixed;
+      syncIndicator(row);
+      // A radio turning on turns its whole group off — repaint the siblings.
+      if (input.type === 'radio' && input.name) {
+        for (const other of (row.ownerDocument ?? document)
+          .querySelectorAll(`input.ol8-choice__input[type="radio"][name="${CSS.escape(input.name)}"]`)) {
+          const otherRow = other.closest('.ol8-choice');
+          if (otherRow && otherRow !== row) syncIndicator(otherRow);
+        }
+      }
+    });
+    row.dataset.ol8ChoiceBound = 'true';
+  }
+  return rows.length;
+}
+
+/** Repaints one row's indicator from the live state of its input. */
+export function syncIndicator(row) {
+  const input = row.querySelector(':scope > .ol8-choice__input');
+  const slot = row.querySelector(':scope > .ol8-choice__indicator');
+  if (!input || !slot) return;
+
+  const kind = row.dataset.ol8Kind ?? 'checkbox';
+  const selection = selectionStateFor(kind, { checked: input.checked, mixed: input.indeterminate });
+
+  row.dataset.ol8Availability = input.disabled ? 'disabled' : 'enabled';
+  slot.innerHTML = renderSelectionIndicator(kind, {
+    selection,
+    size: indicatorSizeFor(row.dataset.ol8Size ?? 'standard'),
+    disabled: input.disabled,
+  });
+}
+
+/** Sets the Mixed (indeterminate) state on a checkbox row. */
+export function setChoiceMixed(row, mixed) {
+  const input = row.querySelector(':scope > .ol8-choice__input');
+  if (!input) return;
+  input.indeterminate = !!mixed;
+  if (mixed) row.dataset.ol8Mixed = 'true'; else delete row.dataset.ol8Mixed;
+  syncIndicator(row);
+}
+
+function escapeAttr(v) { return String(v).replace(/&/g,'&amp;').replace(/"/g,'&quot;').replace(/</g,'&lt;'); }
+function escapeText(v) { return String(v).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;'); }

package/src/molecules/choice-item/index.d.ts

@@ -0,0 +1 @@
+export * from './choice-item.js';

package/src/molecules/choice-item/index.js

@@ -0,0 +1 @@
+export * from './choice-item.js';