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

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

@@ -0,0 +1,5 @@
+export {
+  renderTextField, hydrateTextFields, countGraphemes, clipToGraphemes,
+  OL8_TEXT_FIELD_SIZES, OL8_TEXT_FIELD_APPEARANCES, OL8_TEXT_FIELD_MATERIALS,
+  OL8_MESSAGE_TONES, OL8_VALIDATION_STATUSES, OL8_CHARACTER_LIMIT_BEHAVIORS,
+} from './text-field.js';

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

@@ -0,0 +1,266 @@
+/**
+ * Oneli8 · Text Field (MOLECULE)
+ * Figma: Text Field / Outline 182:33, Text Field / Filled 186:53,
+ *        Text Field / Outline / Gem 211:36, Text Field / Filled / Gem 215:226,
+ *        Text Field / Content 175:2, Form Message 177:13.
+ *
+ * ANATOMY, read from Figma rather than assumed:
+ *   root                vertical, gap Component / Text Field / Gap / Supporting
+ *   · Label Row         horizontal, gap Component / Text Field / Gap / Label
+ *     · Label           twelve over eighteen, Semibold, Tracking Open, Text Primary
+ *     · Requirement     a star in Feedback Critical Content, Regular weight
+ *   · Control Stack     fixed at Component / Text Field / Height / <size>
+ *     · Focus Edge      shown only while focused, Focus Ring Inner Width
+ *     · Control         gap Inline; inset, radius and boundary per size; surface and border
+ *                       per appearance and condition
+ *       · Leading Icon  Size / Icon / Small
+ *       · Prefix        the content size, Text Secondary
+ *       · Input         fills the row
+ *       · Suffix        the content size, Text Secondary
+ *       · Trailing      twenty four
+ *   · Instruction       twelve over eighteen, Text Secondary
+ *   · Supporting Region horizontal, space between, gap Message Counter
+ *     · Form Message    its own molecule
+ *     · Counter         twelve over eighteen, Text Secondary
+ *
+ * CONDITION IS NOT A CLASS. Figma's five Conditions are review evidence. Here
+ * they are :hover, [aria-invalid], [readonly] and :disabled on the real input,
+ * exactly as the Figma description asks.
+ */
+
+.ol8-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ol8-component-textfield-gap-supporting);
+  inline-size: 100%;
+
+  --_surface: var(--ol8-color-surface-default);
+  --_border:  var(--ol8-color-border-default);
+  --_label:   var(--ol8-color-text-primary);
+  --_ink:     var(--ol8-color-text-primary);
+  --_muted:   var(--ol8-color-text-secondary);
+}
+
+/* ---- Label ------------------------------------------------------------ */
+.ol8-field__label-row {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--ol8-component-textfield-gap-requirement);
+}
+.ol8-field__label {
+  color: var(--_label);
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--ol8-font-size-012);
+  font-weight: var(--ol8-font-weight-semibold);
+  line-height: var(--ol8-font-line-018);
+  letter-spacing: var(--ol8-font-tracking-open);
+}
+.ol8-field__requirement {
+  color: var(--ol8-color-feedbackcritical-content);
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--ol8-font-size-012);
+  font-weight: var(--ol8-font-weight-regular);
+  line-height: var(--ol8-font-line-018);
+}
+
+/* ---- Control ---------------------------------------------------------- */
+.ol8-field__control-stack {
+  position: relative;
+  display: flex;
+  block-size: var(--_height);
+}
+
+/* The contract asks a coarse pointer adapter to expand the activation region
+   for Compact and Standard, which are shorter than the protected minimum,
+   without overlapping a neighbouring field. That belongs to a platform adapter:
+   an overlay drawn here would sit over the value and take the caret away from
+   the person, which is worse than the shortfall it fixes. Not implemented. */
+
+.ol8-field__control {
+  display: flex;
+  align-items: center;
+  gap: var(--ol8-component-textfield-gap-inline);
+  inline-size: 100%;
+  block-size: var(--_height);
+  padding-inline: var(--_inset);
+  border: var(--ol8-component-textfield-boundary) solid var(--_border);
+  border-radius: var(--_radius);
+  background: var(--_surface);
+  transition-property: border-color, background-color;
+  transition-duration: var(--ol8-motion-interaction-hover-duration);
+  transition-timing-function: var(--ol8-motion-interaction-hover-timing-function);
+}
+
+.ol8-field__leading-icon { flex: none; color: var(--ol8-color-icon-secondary); }
+
+.ol8-field__affix {
+  flex: none;
+  color: var(--_muted);
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--_content-size);
+  font-weight: var(--ol8-font-weight-regular);
+  line-height: var(--_content-line);
+}
+
+/* The input carries the value, so it takes the primary ink and hands the
+   secondary ink to its placeholder. That is exactly the Content molecule's
+   Value and Placeholder types. */
+.ol8-field__input {
+  flex: 1 1 auto;
+  min-inline-size: 0;
+  border: 0;
+  padding: 0;
+  background: none;
+  color: var(--_ink);
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--_content-size);
+  font-weight: var(--ol8-font-weight-regular);
+  line-height: var(--_content-line);
+}
+.ol8-field__input::placeholder { color: var(--_muted); opacity: 1; }
+.ol8-field__input:focus { outline: none; }
+
+.ol8-field__trailing-action {
+  flex: none;
+  display: inline-flex;
+  border: 0;
+  padding: 0;
+  background: none;
+  color: var(--ol8-color-icon-secondary);
+  cursor: pointer;
+}
+.ol8-field__trailing-action:disabled { color: var(--ol8-color-icon-disabled); cursor: not-allowed; }
+
+/* ---- Size ------------------------------------------------------------- */
+.ol8-field[data-ol8-size="compact"] {
+  --_height: var(--ol8-component-textfield-height-compact);
+  --_inset:  var(--ol8-component-textfield-inset-compact);
+  --_radius: var(--ol8-component-textfield-radius-compact);
+  --_content-size: var(--ol8-font-size-012);
+  --_content-line: var(--ol8-font-line-018);
+}
+.ol8-field[data-ol8-size="standard"] {
+  --_height: var(--ol8-component-textfield-height-standard);
+  --_inset:  var(--ol8-component-textfield-inset-standard);
+  --_radius: var(--ol8-component-textfield-radius-standard);
+  --_content-size: var(--ol8-font-size-016);
+  --_content-line: var(--ol8-font-line-024);
+}
+/* Comfortable grows its box and keeps the standard reading size, which is what
+   Figma's Content set does at this step. */
+.ol8-field[data-ol8-size="comfortable"] {
+  --_height: var(--ol8-component-textfield-height-comfortable);
+  --_inset:  var(--ol8-component-textfield-inset-comfortable);
+  --_radius: var(--ol8-component-textfield-radius-comfortable);
+  --_content-size: var(--ol8-font-size-016);
+  --_content-line: var(--ol8-font-line-024);
+}
+.ol8-field[data-ol8-size="large"] {
+  --_height: var(--ol8-component-textfield-height-large);
+  --_inset:  var(--ol8-component-textfield-inset-large);
+  --_radius: var(--ol8-component-textfield-radius-large);
+  --_content-size: var(--ol8-font-size-021);
+  --_content-line: var(--ol8-font-line-030);
+}
+
+/* ---- Appearance ------------------------------------------------------- */
+.ol8-field[data-ol8-appearance="filled"] {
+  --_surface: var(--ol8-color-surface-sunken);
+  --_border:  var(--ol8-color-border-subtle);
+}
+
+/* ---- Condition, carried by the real input ----------------------------- */
+/* Base condition precedence is Disabled, then Read only, then Invalid, then
+   Default. Hover is an overlay that renders only above Default or Invalid, and
+   only for a fine pointer. */
+@media (hover: hover) and (pointer: fine) {
+  .ol8-field:hover:not([data-ol8-disabled]):not([data-ol8-readonly]) .ol8-field__control {
+    --_border: var(--ol8-color-border-strong);
+  }
+}
+
+.ol8-field[data-ol8-readonly] .ol8-field__control { --_border: var(--ol8-color-border-subtle); }
+
+/* Focus never suppresses Invalid; the focus edge is added on top of it. */
+.ol8-field[data-ol8-invalid] .ol8-field__control,
+.ol8-field:has(.ol8-field__input[aria-invalid="true"]) .ol8-field__control {
+  --_border: var(--ol8-color-feedbackcritical-inlinecontent);
+}
+
+.ol8-field[data-ol8-disabled] {
+  --_label: var(--ol8-color-text-disabled);
+  --_muted: var(--ol8-color-text-disabled);
+  --_ink:   var(--ol8-color-text-disabled);
+}
+.ol8-field[data-ol8-disabled] .ol8-field__control {
+  --_surface: var(--ol8-color-surface-disabled);
+  --_border:  var(--ol8-color-border-disabled);
+}
+.ol8-field[data-ol8-disabled] .ol8-field__input { cursor: not-allowed; }
+.ol8-field[data-ol8-disabled] .ol8-field__leading-icon { color: var(--ol8-color-icon-disabled); }
+
+/* ---- Focus -----------------------------------------------------------
+   Figma draws a Focus Edge sibling that is shown only while focused, at the
+   Focus Ring Inner Width in the outer focus colour. The stack owns it so the
+   edge cannot change the control's own metrics. */
+.ol8-field__control-stack::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: var(--_radius);
+  box-shadow: inset 0 0 0 var(--ol8-focus-ring-innerwidth) var(--ol8-color-focus-outer);
+  opacity: 0;
+  pointer-events: none;
+  transition-property: opacity;
+  transition-duration: var(--ol8-motion-interaction-focus-duration);
+  transition-timing-function: var(--ol8-motion-interaction-focus-timing-function);
+}
+.ol8-field:has(.ol8-field__input:focus-visible) .ol8-field__control-stack::after { opacity: 1; }
+
+@media (prefers-reduced-motion: reduce) {
+  .ol8-field__control,
+  .ol8-field__control-stack::after { transition-duration: var(--ol8-motion-duration-instant); }
+}
+
+/* ---- Instruction, message and counter --------------------------------- */
+.ol8-field__instruction {
+  color: var(--_muted);
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--ol8-font-size-012);
+  font-weight: var(--ol8-font-weight-regular);
+  line-height: var(--ol8-font-line-018);
+  letter-spacing: var(--ol8-font-tracking-open);
+}
+
+/* The message and the counter share one row, counter at the logical inline end.
+   At a narrow width or with enlarged text the counter wraps below the message in
+   source order, and the row gap becomes the tighter status step. The counter is
+   never hidden merely because a message appeared. */
+.ol8-field__supporting {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  justify-content: space-between;
+  column-gap: var(--ol8-component-textfield-gap-messagecounter);
+  row-gap: var(--ol8-component-textfield-gap-status);
+}
+.ol8-field__supporting-spacer { flex: 1 1 auto; }
+
+/* Counter is information, not validation, so it never takes a feedback colour. */
+.ol8-field__counter {
+  flex: none;
+  color: var(--_muted);
+  font-family: var(--ol8-font-family-functional);
+  font-size: var(--ol8-font-size-012);
+  font-weight: var(--ol8-font-weight-regular);
+  line-height: var(--ol8-font-line-018);
+  letter-spacing: var(--ol8-font-tracking-open);
+  font-variant-numeric: tabular-nums;
+}
+
+@media (forced-colors: active) {
+  .ol8-field__control { border-color: ButtonBorder; }
+  .ol8-field:has(.ol8-field__input:focus-visible) .ol8-field__control-stack::after {
+    box-shadow: inset 0 0 0 var(--ol8-focus-ring-innerwidth) Highlight;
+  }
+}

package/src/molecules/text-field/text-field.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Text Field (MOLECULE). Figma 182:33 Outline, 186:53 Filled, 211:36 and
+ * 215:226 Gem.
+ *
+ * Figma's five Conditions are review evidence, never options. Default, Hover,
+ * Invalid, Read-only and Disabled are :hover, aria-invalid, readOnly and
+ * disabled on the native input. Gem changes token bound material only.
+ */
+export type Ol8TextFieldSize = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8TextFieldAppearance = 'outline' | 'filled';
+export type Ol8TextFieldMaterial = 'regular' | 'gem';
+/** Pending is a validation process status, not a fifth message tone. */
+export type Ol8MessageTone = 'critical' | 'caution' | 'positive' | 'informative';
+export type Ol8ValidationStatus = 'idle' | 'pending' | 'resolved';
+export type Ol8CharacterLimitBehavior = 'soft' | 'hard';
+
+export declare const OL8_TEXT_FIELD_SIZES: readonly Ol8TextFieldSize[];
+export declare const OL8_TEXT_FIELD_APPEARANCES: readonly Ol8TextFieldAppearance[];
+export declare const OL8_TEXT_FIELD_MATERIALS: readonly Ol8TextFieldMaterial[];
+export declare const OL8_MESSAGE_TONES: readonly Ol8MessageTone[];
+export declare const OL8_VALIDATION_STATUSES: readonly Ol8ValidationStatus[];
+export declare const OL8_CHARACTER_LIMIT_BEHAVIORS: readonly Ol8CharacterLimitBehavior[];
+
+export interface Ol8TextFieldOptions {
+  /** Required. A field nobody can name is a field nobody can fill. */
+  label: string;
+  name?: string;
+  id?: string;
+  type?: string;
+  value?: string;
+  placeholder?: string;
+  size?: Ol8TextFieldSize;
+  appearance?: Ol8TextFieldAppearance;
+  material?: Ol8TextFieldMaterial;
+  /** False keeps the label as the accessible name without showing it, which needs a documented exception. */
+  showLabel?: boolean;
+  required?: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+  /** Correction is required. Never set without also exposing a Critical message. */
+  invalid?: boolean;
+  leadingIcon?: string;
+  prefix?: string;
+  suffix?: string;
+  trailingAction?: { icon: string; label: string };
+  instruction?: string;
+  message?: string;
+  messageTone?: Ol8MessageTone;
+  messageIcon?: boolean;
+  /** Pending shows the loader; it never freezes typing. */
+  validationStatus?: Ol8ValidationStatus;
+  /** Counted in graphemes, so an emoji counts as one. */
+  characterLimit?: number;
+  /** Soft lets a person overshoot and then correct. Hard is for real technical limits. */
+  characterLimitBehavior?: Ol8CharacterLimitBehavior;
+  className?: string;
+}
+
+/** @throws without a label, on an unknown size, appearance, material, tone or status, or when a read only field is marked invalid. */
+export declare function renderTextField(options: Ol8TextFieldOptions): string;
+
+/** Enforces the runtime contract on existing `.ol8-field` markup. Returns the count of fields with no native input. */
+export declare function hydrateTextFields(root?: ParentNode): number;
+
+/** Counts what a reader would call characters. */
+export declare function countGraphemes(value: unknown): number;
+
+/** Keeps the first `limit` graphemes, so a cluster is never cut in half. */
+export declare function clipToGraphemes(value: unknown, limit: number): string;

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