@oneli8/core 1.0.0-beta.10

package/src/molecules/text-field/text-field.js

@@ -0,0 +1,234 @@
+/**
+ * Oneli8 · Text Field — headless behavior.
+ *
+ * Two sources govern this file and they govern different things.
+ *
+ * Figma (182:33 Outline, 186:53 Filled, 211:36 and 215:226 Gem) governs what is
+ * drawn: anatomy, geometry, colour and material. Its description is explicit
+ * that "runtime input type, name, value, autofill, IME, validationStatus,
+ * grapheme limiting, required/disabled/readOnly and native input semantics live
+ * in code". Its five Conditions are review evidence, never classes: here they
+ * are :hover, aria-invalid, readonly and :disabled on the real input.
+ *
+ * The Text Field contract governs what the API means: the property vocabulary,
+ * the defaults, the state precedence and the prohibitions. Figma has no opinion
+ * on those, so there is nothing to reconcile.
+ */
+import { renderIcon } from '../../atoms/icon/index.js';
+import { renderFormMessage } from '../form-message/index.js';
+
+export const OL8_TEXT_FIELD_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+export const OL8_TEXT_FIELD_APPEARANCES = ['outline', 'filled'];
+export const OL8_TEXT_FIELD_MATERIALS = ['regular', 'gem'];
+
+/** The four semantic tones a message can carry. Pending is not one of them. */
+export const OL8_MESSAGE_TONES = ['critical', 'caution', 'positive', 'informative'];
+
+/** "Pending is a validation process status, not a fifth message tone." */
+export const OL8_VALIDATION_STATUSES = ['idle', 'pending', 'resolved'];
+
+/** Soft lets a person overshoot and then correct. Hard is for real technical limits. */
+export const OL8_CHARACTER_LIMIT_BEHAVIORS = ['soft', 'hard'];
+
+let sequence = 0;
+const nextId = () => `ol8-field-${++sequence}`;
+
+/** @param {import('./text-field.js').Ol8TextFieldOptions} options */
+export function renderTextField(options = {}) {
+  const {
+    label, name, id = nextId(), type = 'text', value, placeholder,
+    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',
+    className,
+  } = options;
+
+  assertContract({ label, size, appearance, material, messageTone, validationStatus,
+    characterLimit, characterLimitBehavior, readOnly, invalid });
+
+  const instructionId = instruction ? `${id}-instruction` : null;
+  const messageId = message ? `${id}-message` : null;
+  const counterId = characterLimit !== undefined ? `${id}-counter` : null;
+  const describedBy = [instructionId, messageId, counterId].filter(Boolean).join(' ');
+
+  const labelRow = showLabel
+    ? `<div class="ol8-field__label-row">` +
+      `<label class="ol8-field__label" for="${escapeAttr(id)}">${escapeText(label)}</label>` +
+      (required ? `<span class="ol8-field__requirement" aria-hidden="true">*</span>` : '') +
+      `</div>`
+    : '';
+
+  const control =
+    `<div class="ol8-field__control">` +
+    (leadingIcon ? renderIcon(leadingIcon, { size: 18, className: 'ol8-field__leading-icon' }) : '') +
+    (prefix ? `<span class="ol8-field__affix" aria-hidden="true">${escapeText(prefix)}</span>` : '') +
+    `<input class="ol8-field__input" id="${escapeAttr(id)}" type="${escapeAttr(type)}"` +
+      (name ? ` name="${escapeAttr(name)}"` : '') +
+      (value !== undefined ? ` value="${escapeAttr(value)}"` : '') +
+      (placeholder ? ` placeholder="${escapeAttr(placeholder)}"` : '') +
+      (required ? ' required' : '') +
+      (disabled ? ' disabled' : '') +
+      (readOnly ? ' readonly' : '') +
+      (invalid ? ' aria-invalid="true"' : '') +
+      (invalid && messageId ? ` aria-errormessage="${messageId}"` : '') +
+      // A native maxlength counts UTF-16 units, which would cut an emoji in half.
+      // The limit is enforced here instead, in graphemes, per the contract.
+      (characterLimit !== undefined ? ` data-ol8-limit="${characterLimit}" data-ol8-limit-behavior="${characterLimitBehavior}"` : '') +
+      (describedBy ? ` aria-describedby="${escapeAttr(describedBy)}"` : '') +
+      (showLabel ? '' : ` aria-label="${escapeAttr(label)}"`) +
+    `>` +
+    (suffix ? `<span class="ol8-field__affix" aria-hidden="true">${escapeText(suffix)}</span>` : '') +
+    (trailingAction
+      ? `<button class="ol8-field__trailing-action" type="button"` +
+        (disabled ? ' disabled' : '') +
+        ` aria-label="${escapeAttr(trailingAction.label)}">` +
+        renderIcon(trailingAction.icon, { size: 18 }) +
+        `</button>`
+      : '') +
+    `</div>`;
+
+  // Instruction is its own full width row. Message and counter share the next
+  // one, counter at the logical inline end, wrapping below at narrow widths.
+  const supporting = (message || counterId)
+    ? `<div class="ol8-field__supporting">` +
+      (message
+        ? renderFormMessage(message, { tone: validationStatus === 'pending' ? 'pending' : messageTone, icon: messageIcon, id: messageId })
+        : '<span class="ol8-field__supporting-spacer"></span>') +
+      (counterId
+        ? `<span class="ol8-field__counter" id="${counterId}">${countGraphemes(value)} / ${characterLimit}</span>`
+        : '') +
+      `</div>`
+    : '';
+
+  const attrs = [
+    `class="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}"` : '',
+  ].filter(Boolean).join(' ');
+
+  return `<div ${attrs}>` +
+    labelRow +
+    `<div class="ol8-field__control-stack">${control}</div>` +
+    (instruction ? `<div class="ol8-field__instruction" id="${instructionId}">${escapeText(instruction)}</div>` : '') +
+    supporting +
+    `</div>`;
+}
+
+/**
+ * Enforces the runtime contract on existing `.ol8-field` markup. Idempotent.
+ *
+ *   - a field must own exactly one native input, since that is what carries
+ *     type, value, autofill, IME, undo and the platform's text services
+ *   - the label must point at that input, or it labels nothing
+ *   - clicking anywhere in the control frame focuses the input, except on the
+ *     independent trailing action
+ *   - the counter counts graphemes as the person types, and a hard limit stops
+ *     accepting input rather than corrupting a cluster
+ */
+export function hydrateTextFields(root = document) {
+  const problems = [];
+  for (const field of root.querySelectorAll('.ol8-field')) {
+    const input = field.querySelector('.ol8-field__input');
+    if (!input) { problems.push(field); continue; }
+
+    if (!field.dataset.ol8Size) field.dataset.ol8Size = 'comfortable';
+    if (!field.dataset.ol8Appearance) field.dataset.ol8Appearance = 'outline';
+
+    const label = field.querySelector('.ol8-field__label');
+    if (label && !label.getAttribute('for')) {
+      if (!input.id) input.id = nextId();
+      label.setAttribute('for', input.id);
+    }
+
+    const control = field.querySelector('.ol8-field__control');
+    if (control && control.dataset.ol8Wired !== 'true') {
+      control.dataset.ol8Wired = 'true';
+      control.addEventListener('mousedown', (event) => {
+        if (event.target === input) return;
+        if (event.target.closest('.ol8-field__trailing-action')) return;
+        event.preventDefault();
+        input.focus();
+      });
+    }
+
+    const limit = Number(input.dataset.ol8Limit);
+    if (Number.isInteger(limit) && input.dataset.ol8Counting !== 'true') {
+      input.dataset.ol8Counting = 'true';
+      const counter = field.querySelector('.ol8-field__counter');
+      const paint = () => {
+        if (input.dataset.ol8LimitBehavior === 'hard') {
+          const clipped = clipToGraphemes(input.value, limit);
+          if (clipped !== input.value) input.value = clipped;
+        }
+        if (counter) counter.textContent = `${countGraphemes(input.value)} / ${limit}`;
+      };
+      input.addEventListener('input', paint);
+      paint();
+    }
+  }
+  if (problems.length > 0) {
+    console.warn(`[ol8] ${problems.length} .ol8-field element(s) contain no native input`, problems);
+  }
+  return problems.length;
+}
+
+/**
+ * Counts what a reader would call characters. An emoji built from several code
+ * points is one, which is why 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];
+}
+
+/** Every rule here is one the contract states outright. */
+function assertContract({
+  label, size, appearance, material, messageTone, validationStatus,
+  characterLimit, characterLimitBehavior, readOnly, invalid,
+}) {
+  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.');
+  }
+}
+
+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/token/index.d.ts

@@ -0,0 +1,2 @@
+export { OL8_TOKEN_SIZES, OL8_TOKEN_MARKS, resolveTokenMark, renderToken } from './token.js';
+export type { Ol8TokenSize, Ol8TokenMark, Ol8TokenOptions } from './token.js';

package/src/molecules/token/index.js

@@ -0,0 +1 @@
+export { OL8_TOKEN_SIZES, OL8_TOKEN_MARKS, resolveTokenMark, renderToken } from './token.js';

package/src/molecules/token/token.css

@@ -0,0 +1,63 @@
+/**
+ * Oneli8 · Token (MOLECULE)
+ * Figma: Select and Combobox / Molecule / Token 897:2106 (24 variants)
+ *
+ * The silhouette, sizes and colours all come from the Choice Chip stylesheet,
+ * because Figma's Token instantiates the Choice Chip Geometry Owner rather than
+ * redrawing it. Every rule here is about the one axis Token adds: the Mark.
+ */
+
+/* A token is content, not a control. Only its Remove mark is interactive. */
+.ol8-token.ol8-chip { cursor: default; }
+
+/* ---- Remove ---------------------------------------------------------- */
+.ol8-token__remove {
+  position: relative;      /* anchors the expanded target below */
+  padding: 0;
+  border: 0;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+  /* The ring follows the mark, not the chip: the chip is not the target. */
+  border-radius: var(--ol8-shape-radius-full);
+}
+
+/* The mark is drawn at 18 because that is what Figma draws, but the contract
+   asks for a target of at least 24 that does not overlap anything. The target
+   is expanded with a pseudo element so the drawn size and the reachable size
+   can differ without moving the label: it grows 3 into the 9 gap on one side
+   and into the rail inset on the other, so it still touches neither. */
+.ol8-token__remove::before {
+  content: "";
+  position: absolute;
+  inline-size: var(--ol8-component-choice-chip-mark-target);
+  block-size: var(--ol8-component-choice-chip-mark-target);
+  transform: translate(-50%, -50%);
+  inset-block-start: 50%;
+  inset-inline-start: 50%;
+}
+
+.ol8-token__remove:focus-visible {
+  outline: var(--ol8-focus-ring-innerwidth) solid var(--ol8-color-focus-inner);
+  outline-offset: var(--ol8-focus-ring-offset);
+}
+
+/* ---- Mark size parity ------------------------------------------------
+   The two marks have to read as one size, and they did not. The Icon Library's
+   cross spans 12 x 12 in the canonical 24 space while the check spans
+   10.2 x 6.9, so drawn at one frame size the cross was fifteen percent wider
+   and well over half again as tall, and it swamped the check beside it.
+
+   Figma does not draw it that way: its Remove mark is an Icon Frame instance at
+   18, so the cross comes out at 9 x 9 there, a little narrower than the check
+   and balanced against it. The oversized cross was this stylesheet rendering
+   the library source at full size, not a decision in the design.
+
+   So the cross is scaled to the 9 span Figma draws. The stroke does not follow
+   it: it is a non scaling stroke, so it stays the governed 1.8 that every glyph
+   in the system uses, which is also what Figma keeps. */
+.ol8-token__remove > svg > * {
+  transform: scale(0.75);        /* 9 / 12, the span Figma draws */
+  transform-box: fill-box;
+  transform-origin: center;
+}

package/src/molecules/token/token.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Token (MOLECULE) — a committed value. It delegates every bit of geometry to
+ * the Choice Chip owner, exactly as the Figma component does, and adds only the
+ * Mark axis. A token is content with an optional Remove button, not a control.
+ */
+import type { Ol8ChipSize } from '../choice-chip/choice-chip.js';
+
+export type Ol8TokenSize = Ol8ChipSize;
+/** Figma draws the last three; `auto` resolves to one of them. */
+export type Ol8TokenMark = 'auto' | 'none' | 'check' | 'remove';
+
+export declare const OL8_TOKEN_SIZES: readonly Ol8TokenSize[];
+export declare const OL8_TOKEN_MARKS: readonly Ol8TokenMark[];
+
+/** Remove for a removable value, Check for a selected one, None otherwise. */
+export declare function resolveTokenMark(
+  mark: Ol8TokenMark,
+  state?: { removable?: boolean; selected?: boolean },
+): Exclude<Ol8TokenMark, 'auto'>;
+
+export interface Ol8TokenOptions {
+  size?: Ol8TokenSize;
+  selected?: boolean;
+  mark?: Ol8TokenMark;
+  /** A non removable token may not carry a Remove mark. */
+  removable?: boolean;
+  /** Overrides the default "Remove {label}" accessible name. */
+  removeLabel?: string;
+  /** False makes the Remove button reachable by arrow key rather than Tab. */
+  focusable?: boolean;
+  id?: string;
+  className?: string;
+}
+
+export declare function renderToken(label: string, options?: Ol8TokenOptions): string;

package/src/molecules/token/token.js

@@ -0,0 +1,83 @@
+/**
+ * Oneli8 · Token (MOLECULE) — a committed value.
+ *
+ * Figma: Select and Combobox / Molecule / Token 897:2106 (24 variants,
+ * Size x Selection x Mark).
+ *
+ * From the Figma description:
+ *   "Compact/Standard/Comfortable/Large delegate all 30/36/42/42px geometry to
+ *    the Soft Hexagon Choice Chip owner. Selection and None/Check/Remove mark
+ *    contracts remain independent; governed Check and Close atoms are reused
+ *    instead of duplicated."
+ *
+ * So this draws no silhouette of its own. It instantiates the Choice Chip's
+ * geometry exactly as the Figma component instantiates the Geometry Owner, and
+ * adds the one thing that is genuinely its own: the Mark axis.
+ *
+ * A Token is not a Choice Chip. A chip is a checkbox a person toggles; a token
+ * is a value that has already been committed, so it is ordinary content with an
+ * optional Remove button rather than a form control.
+ *
+ * MARK
+ * Figma's axis is the concrete None / Check / Remove. The contract adds `auto`
+ * as the public default, which resolves rather than draws: "Remove for
+ * removable committed values, Check for selected Choice Chips, and None for
+ * unselected or informational chips." A variant cannot be `auto`, which is why
+ * Figma has no such option and code does.
+ */
+import { renderIconSvg } from '../../atoms/icon/icon.js';
+import { renderChipShape, escapeAttr, OL8_CHIP_SIZES } from '../choice-chip/choice-chip.js';
+
+export const OL8_TOKEN_SIZES = OL8_CHIP_SIZES;
+/** Figma draws the last three. `auto` resolves to one of them. */
+export const OL8_TOKEN_MARKS = ['auto', 'none', 'check', 'remove'];
+
+/** The contract's resolution, stated once so both packages agree. */
+export function resolveTokenMark(mark, { removable = true, selected = false } = {}) {
+  if (mark !== 'auto') return mark;
+  if (removable) return 'remove';
+  return selected ? 'check' : 'none';
+}
+
+/**
+ * @param {string} label
+ * @param {{size?:string,selected?:boolean,mark?:string,removable?:boolean,
+ *          removeLabel?:string,id?:string,className?:string}} [options]
+ */
+export function renderToken(label, options = {}) {
+  const {
+    size = 'standard', selected = false, mark = 'auto', removable = true,
+    removeLabel, focusable = true, id, className,
+  } = options;
+
+  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 (!label || !String(label).trim()) 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 uid = id ?? `ol8-token-${Math.random().toString(36).slice(2, 9)}`;
+  const resolved = resolveTokenMark(mark, { removable, selected });
+
+  // The Remove mark is the only interactive part, so it is a real button with
+  // its own accessible name. It follows the label, which is the anatomy the
+  // contract writes down, and the label stays the token's content: the complete
+  // value must remain readable, never shortened or overlaid by its mark.
+  const markup = resolved === 'remove'
+    ? `<button type="button" class="ol8-chip__mark ol8-token__remove" ` +
+      (focusable ? '' : 'tabindex="-1" ') +
+      `aria-label="${escapeAttr(removeLabel ?? `Remove ${label}`)}">${renderIconSvg('close')}</button>`
+    : resolved === 'check'
+      ? `<span class="ol8-chip__mark" aria-hidden="true">${renderIconSvg('check')}</span>`
+      : '';
+
+  const attrs = [
+    `class="ol8-token ol8-chip${className ? ` ${className}` : ''}"`,
+    `data-ol8-size="${size}"`,
+    `data-ol8-selection="${selected ? 'selected' : 'inactive'}"`,
+    `data-ol8-mark="${resolved}"`,
+  ].join(' ');
+
+  return `<span ${attrs}>${renderChipShape(uid, label, markup)}</span>`;
+}

package/src/organisms/choice-group/choice-group.css

@@ -0,0 +1,93 @@
+/**
+ * Oneli8 · Choice Group (ORGANISM)
+ * Figma: Documentation / Organism / Choice Group
+ *   Checkbox Hierarchy 273:603  Aggregate = None | Some | All
+ *   Radio Group        859:5180 Behavior  = Safe Default | No Default |
+ *                                           Horizontal | Invalid
+ *
+ * First organism in the system, and the first tier allowed to hold logic:
+ * the checkbox group computes its parent from its children, and the radio
+ * group owns group-level validation.
+ *
+ * From Figma (273:603): "Aggregate None/Some/All is computed from nested
+ * Checkbox molecules; MIXED IS NEVER A THIRD PREFERENCE. Runtime recursion,
+ * parent-child synchronization, group naming, required behavior, reset, and
+ * announcements live in code."
+ *
+ * So Aggregate is an OUTPUT, never an input. Nothing may author it.
+ *
+ * The two shells differ, deliberately:
+ *   checkbox  bordered, radius-container (24px), legend Title/Small
+ *   radio     unbordered, radius-standard (12px), legend Body/Medium
+ */
+
+.ol8-choice-group {
+  box-sizing: border-box;
+  display: flex;
+  flex-direction: column;
+  gap: var(--ol8-spacing-stack-related);
+  padding: var(--ol8-spacing-inset-standard);
+  background: var(--ol8-color-surface-raised);
+  border: 0;
+  border-radius: var(--ol8-shape-radius-standard);
+  font-family: var(--ol8-font-family-functional);
+  font-variation-settings: "ARRR" var(--ol8-font-axis-arrr-baseline);
+  min-inline-size: 0;   /* fieldset defaults to min-content; this lets it shrink */
+}
+
+.ol8-choice-group--checkbox {
+  border: 1px solid var(--ol8-color-border-subtle);
+  border-radius: var(--ol8-shape-radius-container);
+}
+
+/* <legend> is taken out of flow by default, so it is laid out as a normal
+   flex child instead — the group label is a real legend for assistive tech. */
+.ol8-choice-group__legend {
+  display: block;
+  float: none;
+  padding: 0;
+  inline-size: 100%;
+  color: var(--ol8-color-text-primary);
+}
+.ol8-choice-group--checkbox > .ol8-choice-group__legend {
+  font-size: var(--ol8-font-size-021);
+  line-height: var(--ol8-font-line-030);
+  font-weight: var(--ol8-font-weight-semibold);
+}
+.ol8-choice-group--radio > .ol8-choice-group__legend {
+  font-size: var(--ol8-font-size-016);
+  line-height: var(--ol8-font-line-024);
+  font-weight: var(--ol8-font-weight-regular);
+}
+
+.ol8-choice-group__instruction {
+  font-size: var(--ol8-font-size-012);
+  line-height: var(--ol8-font-line-018);
+  letter-spacing: 0.12px;
+  color: var(--ol8-color-text-secondary);
+}
+
+.ol8-choice-group__options { display: flex; flex-direction: column; }
+.ol8-choice-group[data-ol8-orientation="horizontal"] > .ol8-choice-group__options {
+  flex-direction: row;
+  gap: var(--ol8-spacing-stack-related);
+  flex-wrap: wrap;
+}
+
+/* Children of a hierarchy sit under their parent, indented one 24px step. */
+.ol8-choice-group__children {
+  display: flex;
+  flex-direction: column;
+  padding-inline-start: var(--ol8-dimension-scale-024);
+}
+
+/* Group-level validation message. */
+.ol8-choice-group__message {
+  font-size: var(--ol8-font-size-012);
+  line-height: var(--ol8-font-line-018);
+  letter-spacing: 0.12px;
+  color: var(--ol8-color-text-secondary);
+}
+.ol8-choice-group[data-ol8-invalid="true"] > .ol8-choice-group__message {
+  color: var(--ol8-color-feedbackcritical-inlinecontent);
+}

package/src/organisms/choice-group/choice-group.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Choice Group (ORGANISM) — headless behavior. Aggregate None/Some/All is
+ * computed from nested checkboxes; Mixed is never a third preference. The radio
+ * group needs almost nothing: native radios already give roving focus, single
+ * selection and form submission.
+ */
+import type { Ol8ChoiceSize } from '../../molecules/choice-item/choice-item.js';
+
+export type Ol8Aggregate = 'none' | 'some' | 'all';
+export declare const OL8_AGGREGATE: readonly Ol8Aggregate[];
+
+/** Disabled children are excluded from the tally. */
+export declare function computeAggregate(
+  children: Iterable<HTMLInputElement> | ArrayLike<HTMLInputElement>,
+): Ol8Aggregate;
+
+interface Ol8ChoiceGroupShell {
+  legend: string;
+  instruction?: string;
+  message?: string;
+  invalid?: boolean;
+  disabled?: boolean;
+  size?: Ol8ChoiceSize;
+  material?: 'regular' | 'gem';
+  id?: string;
+  className?: string;
+}
+
+export interface Ol8RadioOption {
+  label: string;
+  value: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+export interface Ol8RadioGroupConfig extends Ol8ChoiceGroupShell {
+  /** Required — it is what makes the radios a group. */
+  name: string;
+  options: Ol8RadioOption[];
+  /** The selected option's value. Omit for no default. */
+  value?: string;
+  orientation?: 'vertical' | 'horizontal';
+  required?: boolean;
+}
+
+export interface Ol8CheckboxOption {
+  label: string;
+  value: string;
+  /** Checkboxes are independent, so each carries its own state. */
+  checked?: boolean;
+  description?: string;
+  disabled?: boolean;
+}
+
+export interface Ol8CheckboxGroupConfig extends Ol8ChoiceGroupShell {
+  /** Required — the hierarchy's parent row. */
+  parentLabel: string;
+  options: Ol8CheckboxOption[];
+  /** Shared input name for the children. Optional: checkboxes need no group name. */
+  name?: string;
+}
+
+/**
+ * Native semantics do the work; this only builds the shell.
+ * @throws if legend, name or options are missing.
+ */
+export declare function renderRadioGroup(config: Ol8RadioGroupConfig): string;
+
+/**
+ * Checkbox hierarchy: one parent whose state is computed from its children. The
+ * parent renders unchecked; hydration derives its real state.
+ * @throws if legend, parentLabel or options are missing.
+ */
+export declare function renderCheckboxGroup(config: Ol8CheckboxGroupConfig): string;
+
+/**
+ * Wires every checkbox hierarchy under `root`. Idempotent.
+ * Radio groups need no wiring — the browser already owns their behaviour.
+ */
+export declare function hydrateChoiceGroups(root?: ParentNode): void;