@oneli8/core 1.0.0-beta.10

package/src/molecules/selection-option/selection-option.css

@@ -0,0 +1,121 @@
+/**
+ * Oneli8 · Selection Option (MOLECULE)
+ * Figma: Select and Combobox -> 01 · Atomic Selection Building Blocks
+ *        Building Blocks / Selection Option 570:122 (8 variants)
+ *        Size Standard|Large x Selection x Availability
+ *
+ * From the Figma description (570:122):
+ *   "Description is associated through aria-describedby and REMAINS OUTSIDE
+ *    the option accessible name. Selection Popup composes this owner;
+ *    KEYBOARD FOCUS REMAINS ON THE COMBOBOX INPUT through
+ *    aria-activedescendant."
+ *
+ * Two consequences that shape everything here:
+ *   - the option is never focusable and carries no tabindex
+ *   - "active" (the aria-activedescendant highlight) is a DIFFERENT thing from
+ *     :hover and from selected, so it gets its own attribute
+ *
+ * Row geometry: 48px (Standard) / 60px (Large) minimum, but the content box
+ * stays 24px tall in both — the padding absorbs the difference.
+ *   padding-block = (minimum - 24) / 2  ->  12px and 18px
+ */
+
+.ol8-option {
+  --_min:   var(--ol8-component-selectionoption-minimum-standard);
+  --_inset: var(--ol8-component-selectionoption-inset-standard);
+
+  box-sizing: border-box;
+  display: flex;
+  align-items: center;
+  min-block-size: var(--_min);
+  font-family: var(--ol8-font-family-functional);
+  font-variation-settings: "ARRR" var(--ol8-font-axis-arrr-baseline);
+  list-style: none;
+  cursor: pointer;
+}
+.ol8-option[data-ol8-size="large"] {
+  --_min:   var(--ol8-component-selectionoption-minimum-large);
+  --_inset: var(--ol8-component-selectionoption-inset-large);
+}
+.ol8-option[aria-disabled="true"] { cursor: not-allowed; }
+
+/* The surface carries every wash and the focus ring; the row itself stays
+   clean so a popup can lay options out without fighting them. */
+.ol8-option__surface {
+  box-sizing: border-box;
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--ol8-component-choice-gap-standard);
+  flex: 1 0 0;
+  min-inline-size: 0;
+  block-size: 100%;
+  padding-inline: var(--_inset);
+  padding-block: calc((var(--_min) - var(--ol8-font-line-024)) / 2);
+  border-radius: var(--ol8-shape-radius-medium);
+  overflow: clip;
+}
+
+/* Selected, hover and active all paint the same wash. Selected is a state of
+   the data; active is the aria-activedescendant cursor; hover is the pointer.
+   They coincide visually by design. */
+.ol8-option[aria-selected="true"] > .ol8-option__surface,
+.ol8-option[data-ol8-active="true"] > .ol8-option__surface,
+.ol8-option:hover:not([aria-disabled="true"]) > .ol8-option__surface {
+  background: var(--ol8-color-selection-surface);
+}
+.ol8-option:active:not([aria-disabled="true"]) > .ol8-option__surface {
+  background: var(--ol8-color-selection-surface);
+  opacity: 0.84;
+}
+
+/* Focus lives on the combobox input, never here — but the option still shows
+   the active ring when a popup marks it, so the two-tone ring is reproduced. */
+.ol8-option[data-ol8-focus-ring="true"] > .ol8-option__surface {
+  border: var(--ol8-focus-ring-outerwidth) solid var(--ol8-color-focus-outer);
+}
+.ol8-option[data-ol8-focus-ring="true"] > .ol8-option__surface::after {
+  content: "";
+  position: absolute;
+  inset: 2px;
+  border: var(--ol8-focus-ring-innerwidth) solid var(--ol8-color-focus-inner);
+  border-radius: 7px;
+  pointer-events: none;
+}
+
+.ol8-option__text {
+  display: flex;
+  flex-direction: column;
+  flex: 1 0 0;
+  min-inline-size: 0;
+}
+.ol8-option__label {
+  font-size: var(--ol8-font-size-016);
+  line-height: var(--ol8-font-line-024);
+  font-weight: var(--ol8-font-weight-regular);
+  color: var(--ol8-color-text-primary);
+  overflow-wrap: break-word;
+}
+.ol8-option__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-option[aria-disabled="true"] .ol8-option__label,
+.ol8-option[aria-disabled="true"] .ol8-option__description {
+  color: var(--ol8-color-text-disabled);
+}
+
+/* The trailing slot is ALWAYS reserved, selected or not, so the label column
+   never shifts when selection changes. Figma keeps an empty 18px node there. */
+.ol8-option__check {
+  flex: none;
+  inline-size: var(--ol8-size-icon-small);
+  block-size: var(--ol8-size-icon-small);
+  color: var(--ol8-color-selection-content);
+}
+.ol8-option__check > svg { display: block; inline-size: 100%; block-size: 100%; }
+
+.ol8-option .ol8-icon { --_ol8-icon-size: var(--ol8-size-icon-small); }

package/src/molecules/selection-option/selection-option.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Selection Option (MOLECULE) — headless. The option is NEVER focusable: a
+ * listbox moves a virtual cursor with aria-activedescendant while real focus
+ * stays on the controlling combobox input.
+ */
+import type { Ol8IconName } from '../../atoms/icon/icons.generated.js';
+
+export type Ol8OptionSize = 'standard' | 'large';
+export declare const OL8_OPTION_SIZES: readonly Ol8OptionSize[];
+
+export interface Ol8SelectionOptionOptions {
+  value?: string;
+  size?: Ol8OptionSize;
+  selected?: boolean;
+  /** The listbox's virtual cursor, not DOM focus. */
+  active?: boolean;
+  /** Options cannot be natively disabled, so this emits aria-disabled. */
+  disabled?: boolean;
+  /** Associated with aria-describedby, kept out of the accessible name. */
+  description?: string;
+  leadingIcon?: Ol8IconName;
+  id?: string;
+  focusRing?: boolean;
+  className?: string;
+}
+
+export declare function renderSelectionOption(
+  label: string,
+  options?: Ol8SelectionOptionOptions,
+): string;
+
+export declare function setOptionSelected(option: Element, selected: boolean): void;
+
+/**
+ * Moves the virtual cursor within a listbox: marks one option active and points
+ * the controller's aria-activedescendant at it. Real focus is never moved.
+ */
+export declare function setActiveOption(
+  listbox: Element,
+  option: Element,
+  controller: Element,
+): void;

package/src/molecules/selection-option/selection-option.js

@@ -0,0 +1,97 @@
+/**
+ * Oneli8 · Selection Option (MOLECULE) — headless.
+ *
+ * Figma (570:122): "Description is associated through aria-describedby and
+ * remains outside the option accessible name. Selection Popup composes this
+ * owner; keyboard focus remains on the Combobox input through
+ * aria-activedescendant."
+ *
+ * That single sentence sets the whole contract:
+ *   - role="option", named by its LABEL only. The description is referenced,
+ *     never nested into the name, so aria-labelledby points at the label and
+ *     aria-describedby at the description.
+ *   - the option is NOT focusable. No tabindex, ever. A listbox moves a
+ *     virtual cursor with aria-activedescendant while real focus stays put.
+ *   - "active" (the cursor) is distinct from "selected" (the data) and from
+ *     :hover (the pointer), so it is its own attribute.
+ *   - options cannot use the `disabled` attribute — it is not valid on the
+ *     element an option renders as — so unavailability is aria-disabled.
+ */
+import { renderIcon, renderIconSvg, isOl8IconName } from '../../atoms/icon/icon.js';
+
+export const OL8_OPTION_SIZES = ['standard', 'large'];
+
+/**
+ * @param {string} label
+ * @param {{value?:string,size?:string,selected?:boolean,active?:boolean,disabled?:boolean,
+ *          description?:string,leadingIcon?:string,id?:string,focusRing?:boolean,className?:string}} [options]
+ */
+export function renderSelectionOption(label, options = {}) {
+  const {
+    value, size = 'standard', selected = false, active = false, disabled = false,
+    description, leadingIcon, id, focusRing = false, className,
+  } = options;
+
+  if (!OL8_OPTION_SIZES.includes(size)) throw new Error(`[ol8] unknown option size "${size}"`);
+  if (!label || !String(label).trim()) throw new Error('[ol8] a selection option requires a label');
+  if (leadingIcon && !isOl8IconName(leadingIcon)) throw new Error(`[ol8] unknown icon "${leadingIcon}"`);
+
+  const uid = id ?? `ol8-option-${Math.random().toString(36).slice(2, 9)}`;
+  const labelId = `${uid}-label`;
+  const descId = description ? `${uid}-desc` : null;
+
+  const attrs = [
+    `class="ol8-option${className ? ` ${className}` : ''}"`,
+    'role="option"',
+    `id="${uid}"`,
+    value !== undefined ? `data-ol8-value="${escapeAttr(value)}"` : '',
+    `data-ol8-size="${size}"`,
+    `aria-selected="${selected ? 'true' : 'false'}"`,
+    active ? 'data-ol8-active="true"' : '',
+    disabled ? 'aria-disabled="true"' : '',
+    focusRing ? 'data-ol8-focus-ring="true"' : '',
+    // Named by the label alone; the description is referenced, not nested.
+    `aria-labelledby="${labelId}"`,
+    descId ? `aria-describedby="${descId}"` : '',
+  ].filter(Boolean).join(' ');
+
+  const lead = leadingIcon ? renderIcon(leadingIcon, { size: 18 }) : '';
+  const check = `<span class="ol8-option__check" aria-hidden="true">${selected ? renderIconSvg('check') : ''}</span>`;
+
+  return `<div ${attrs}><span class="ol8-option__surface">` +
+    lead +
+    `<span class="ol8-option__text">` +
+      `<span class="ol8-option__label" id="${labelId}">${escapeText(label)}</span>` +
+      (description ? `<span class="ol8-option__description" id="${descId}">${escapeText(description)}</span>` : '') +
+    `</span>` +
+    check +
+    `</span></div>`;
+}
+
+/** Flips one option's selected state and repaints its trailing check. */
+export function setOptionSelected(option, selected) {
+  option.setAttribute('aria-selected', selected ? 'true' : 'false');
+  const check = option.querySelector('.ol8-option__check');
+  if (check) check.innerHTML = selected ? renderIconSvg('check') : '';
+}
+
+/**
+ * Moves the virtual cursor within a listbox: marks one option active and
+ * points the controlling element's aria-activedescendant at it. Real focus is
+ * never moved, which is the entire point of the pattern.
+ */
+export function setActiveOption(listbox, option, controller) {
+  for (const other of listbox.querySelectorAll('.ol8-option[data-ol8-active="true"]')) {
+    if (other !== option) delete other.dataset.ol8Active;
+  }
+  if (!option) {
+    controller?.removeAttribute('aria-activedescendant');
+    return;
+  }
+  option.dataset.ol8Active = 'true';
+  controller?.setAttribute('aria-activedescendant', option.id);
+  option.scrollIntoView({ block: 'nearest' });
+}
+
+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/text-field/index.d.ts

@@ -0,0 +1 @@
+export * from './text-field.js';

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;