@oneli8/core 1.0.0-beta.5 → 1.0.0-beta.7

package/src/molecules/link/link.css

@@ -0,0 +1,114 @@
+/**
+ * Oneli8 · Link (MOLECULE)
+ *
+ * Figma (138:260, 139:260, 139:453): "Runtime href, native anchor behavior,
+ * visited resolution, aria-current, motion preference and navigation list
+ * hierarchy live in code." Figma's five States are visual evidence for review,
+ * not classes: they are :hover, :active, :focus-visible, :visited and
+ * [aria-current] here.
+ *
+ * "Icons remain intentionally parked and must not be added as local artwork."
+ */
+
+.ol8-link {
+  position: relative;
+  color: var(--ol8-color-text-link-default);
+  font-family: var(--ol8-font-family-functional);
+  font-weight: var(--ol8-font-weight-semibold);
+  text-decoration-line: underline;
+  text-decoration-thickness: var(--ol8-component-link-underline-default);
+  text-underline-offset: var(--ol8-component-link-underline-offset);
+  transition-property: color, text-decoration-thickness, background-color, box-shadow;
+  transition-duration: var(--ol8-motion-interaction-hover-duration);
+  transition-timing-function: var(--ol8-motion-interaction-hover-timing-function);
+}
+
+/* ---- Size ------------------------------------------------------------- */
+.ol8-link[data-ol8-size="small"] {
+  font-size: var(--ol8-typography-body-small-font-size);
+  line-height: var(--ol8-typography-body-small-line-height);
+  letter-spacing: var(--ol8-typography-body-small-letter-spacing);
+}
+.ol8-link[data-ol8-size="standard"] {
+  font-size: var(--ol8-typography-body-medium-font-size);
+  line-height: var(--ol8-typography-body-medium-line-height);
+  letter-spacing: var(--ol8-typography-body-medium-letter-spacing);
+}
+.ol8-link[data-ol8-size="large"] {
+  font-size: var(--ol8-typography-body-large-font-size);
+  line-height: var(--ol8-typography-body-large-line-height);
+  letter-spacing: var(--ol8-typography-body-large-letter-spacing);
+}
+/* Not a Figma size. An inline link inside body copy that does not follow its
+   surrounding type is broken, and Figma cannot express "inherit" as a variant.
+   Flagged for the design source rather than left undocumented. */
+.ol8-link[data-ol8-size="inherit"] {
+  font-size: inherit;
+  line-height: inherit;
+  letter-spacing: inherit;
+}
+
+/* ---- State ------------------------------------------------------------ */
+.ol8-link:hover,
+.ol8-link:active {
+  text-decoration-thickness: var(--ol8-component-link-underline-emphasis);
+}
+.ol8-link:hover  { color: var(--ol8-color-text-link-hover); }
+.ol8-link:active { color: var(--ol8-color-text-link-pressed); }
+
+/* Navigation links live in a list where visited carries no meaning. */
+.ol8-link[data-ol8-form="inline"]:visited,
+.ol8-link[data-ol8-form="standalone"]:visited {
+  color: var(--ol8-color-text-link-visited);
+}
+
+.ol8-link:focus-visible {
+  outline: none;
+  color: var(--ol8-color-text-primary);
+  text-decoration-color: var(--ol8-color-text-link-default);
+  border-radius: var(--ol8-shape-radius-subtle);
+  box-shadow:
+    0 0 0 var(--ol8-focus-ring-innerwidth) var(--ol8-color-focus-inner),
+    0 0 0 var(--ol8-focus-ring-totalwidth) var(--ol8-color-focus-outer);
+}
+
+/* ---- Form ------------------------------------------------------------- */
+/* Standalone and navigation are targets in their own right, so they take the
+   protected minimum. Inline sits in a sentence and must not. Figma pads both by
+   the minimal inline step and carries a gap for the parked icon slot. */
+.ol8-link[data-ol8-form="standalone"],
+.ol8-link[data-ol8-form="navigation"] {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--ol8-component-link-gap-standard);
+  min-block-size: var(--ol8-component-link-targetnavigation);
+  padding-inline: var(--ol8-spacing-inline-minimal);
+}
+.ol8-link[data-ol8-form="standalone"][data-ol8-size="small"],
+.ol8-link[data-ol8-form="navigation"][data-ol8-size="small"] {
+  gap: var(--ol8-component-link-gap-small);
+}
+.ol8-link[data-ol8-form="standalone"][data-ol8-size="large"],
+.ol8-link[data-ol8-form="navigation"][data-ol8-size="large"] {
+  gap: var(--ol8-component-link-gap-large);
+}
+
+/* Figma keeps the underline in every navigation state and marks the current
+   destination by thickening it to the current marker weight. */
+.ol8-link[data-ol8-form="navigation"][aria-current] {
+  text-decoration-thickness: var(--ol8-component-link-underline-current);
+}
+
+/* ---- Motion ----------------------------------------------------------- */
+.ol8-link[data-ol8-motion="none"] { transition-duration: var(--ol8-motion-duration-instant); }
+@media (prefers-reduced-motion: reduce) {
+  .ol8-link { transition-duration: var(--ol8-motion-duration-instant); }
+}
+@media (forced-colors: active) {
+  .ol8-link { forced-color-adjust: auto; }
+  .ol8-link:focus-visible {
+    outline: var(--ol8-focus-ring-innerwidth) solid Highlight;
+    outline-offset: calc(var(--ol8-focus-ring-innerwidth) * -1);
+    box-shadow: none;
+  }
+}

package/src/molecules/link/link.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Link (MOLECULE) — headless behavior. Figma's five States are visual evidence
+ * for review, never classes: :hover, :active, :focus-visible, :visited and
+ * [aria-current] carry them. Icons are intentionally parked.
+ */
+export type Ol8LinkForm = 'inline' | 'standalone' | 'navigation';
+export type Ol8LinkSize = 'small' | 'standard' | 'large';
+export type Ol8LinkMotion = 'system' | 'none';
+
+export declare const OL8_LINK_FORMS: readonly Ol8LinkForm[];
+export declare const OL8_LINK_SIZES: readonly Ol8LinkSize[];
+export declare const OL8_LINK_MOTIONS: readonly Ol8LinkMotion[];
+
+export interface Ol8LinkOptions {
+  form?: Ol8LinkForm;
+  size?: Ol8LinkSize;
+  /** Navigation only. `true` emits aria-current="page"; a string names the kind. */
+  current?: boolean | string;
+  motion?: Ol8LinkMotion;
+  className?: string;
+}
+
+/** @throws without an href, on an unknown form or size, or for current outside navigation. */
+export declare function renderLink(label: string, href: string, options?: Ol8LinkOptions): string;
+
+/** Enforces the runtime contract on existing `.ol8-link` markup. Returns the count of elements that are not anchors with an href. */
+export declare function hydrateLinks(root?: ParentNode): number;

package/src/molecules/link/link.js

@@ -0,0 +1,76 @@
+/**
+ * Oneli8 · Link — headless behavior.
+ *
+ * The Figma component description is explicit that "runtime href, native anchor
+ * behavior, visited resolution, aria-current, motion preference and navigation
+ * list hierarchy live in code". This module is that code.
+ *
+ * Figma's five States are visual evidence for review. They are never classes:
+ * :hover, :active, :focus-visible, :visited and [aria-current] carry them.
+ */
+export const OL8_LINK_FORMS = ['inline', 'standalone', 'navigation'];
+export const OL8_LINK_SIZES = ['small', 'standard', 'large'];
+export const OL8_LINK_MOTIONS = ['system', 'none'];
+
+/**
+ * @param {string} label
+ * @param {string} href
+ * @param {{form?:string,size?:string,current?:boolean|string,motion?:string,className?:string}} [options]
+ */
+export function renderLink(label, href, options = {}) {
+  const { form = 'inline', size = 'standard', current, motion = 'system', className } = options;
+
+  if (!OL8_LINK_FORMS.includes(form)) throw new Error(`[ol8] unknown link form "${form}"`);
+  if (!OL8_LINK_SIZES.includes(size)) throw new Error(`[ol8] unknown link size "${size}"`);
+  if (!OL8_LINK_MOTIONS.includes(motion)) throw new Error(`[ol8] unknown link motion "${motion}"`);
+  if (typeof href !== 'string' || href === '') {
+    throw new Error('[ol8] Link requires an href. A link without a destination is a button.');
+  }
+  if (current !== undefined && form !== 'navigation') {
+    throw new Error('[ol8] aria-current belongs to a navigation link, not an inline or standalone one.');
+  }
+
+  const attrs = [
+    `class="ol8-link${className ? ` ${className}` : ''}"`,
+    `href="${escapeAttr(href)}"`,
+    `data-ol8-form="${form}"`,
+    `data-ol8-size="${size}"`,
+    motion === 'none' ? 'data-ol8-motion="none"' : '',
+    // true means this page; a string names what kind of current it is
+    current ? `aria-current="${current === true ? 'page' : escapeAttr(String(current))}"` : '',
+  ].filter(Boolean).join(' ');
+
+  return `<a ${attrs}>${escapeText(label)}</a>`;
+}
+
+/**
+ * Enforces the runtime contract on existing `.ol8-link` markup. Idempotent.
+ *   - an anchor with no href is not a link, so it is reported rather than styled
+ *   - a form is required for the size and target rules to apply
+ *   - aria-current outside a navigation link is removed, since it claims a
+ *     position in a set that does not exist
+ */
+export function hydrateLinks(root = document) {
+  const problems = [];
+  for (const el of root.querySelectorAll('.ol8-link')) {
+    if (el.tagName !== 'A' || !el.getAttribute('href')) {
+      problems.push(el);
+      continue;
+    }
+    if (!el.dataset.ol8Form) el.dataset.ol8Form = 'inline';
+    if (!el.dataset.ol8Size) el.dataset.ol8Size = 'standard';
+    if (el.hasAttribute('aria-current') && el.dataset.ol8Form !== 'navigation') {
+      el.removeAttribute('aria-current');
+    }
+  }
+  if (problems.length > 0) {
+    console.warn(`[ol8] ${problems.length} .ol8-link element(s) are not anchors with an href`, problems);
+  }
+  return problems.length;
+}
+
+// Defined locally, matching every other molecule in this package. Six modules
+// carry their own copy; consolidating them is a separate change, not part of
+// restoring Link.
+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/navigation-item/index.js

@@ -0,0 +1 @@
+export { renderNavigationItem, OL8_NAVIGATION_KINDS, OL8_NAVIGATION_SIZES, OL8_NAVIGATION_LAYOUTS } from './navigation-item.js';

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

@@ -0,0 +1,153 @@
+/**
+ * Oneli8 · Navigation Item (MOLECULE, internal)
+ * Figma: Tab Item 688:51, Segment Item 695:167, Destination Item 700:292.
+ *
+ * All three are one molecule. Read from Figma: a box at the size's control
+ * height with centred content, a horizontal content row at the canonical
+ * navigation gap, an eighteen unit icon, a Semibold label at the size's reading
+ * step, and an optional badge. States are identical across the three:
+ *
+ *   Hover     Action Quiet Surface Hover   + Action Quiet Content Hover
+ *   Pressed   Action Quiet Surface Pressed + Action Quiet Content Pressed
+ *   Focus     an inward Focus Inner edge, so a parent cannot crop it
+ *   Disabled  Text Disabled, no surface
+ *
+ * Only the selection language differs. Tab Item raises an indicator bar in the
+ * primary colour, inset by the governed amount. Segment Item and Destination
+ * Item take the selection surface and content instead.
+ */
+
+.ol8-nav-item {
+  position: relative;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  block-size: var(--_height);
+  border: 0;
+  border-radius: var(--_radius);
+  padding-inline: var(--_inset);
+  background: transparent;
+  color: var(--ol8-color-text-secondary);
+  font-family: var(--ol8-font-family-functional);
+  font-weight: var(--ol8-font-weight-semibold);
+  text-decoration: none;
+  cursor: pointer;
+  transition-property: background-color, color;
+  transition-duration: var(--ol8-motion-interaction-hover-duration);
+  transition-timing-function: var(--ol8-motion-interaction-hover-timing-function);
+}
+
+.ol8-nav-item__content {
+  display: flex;
+  align-items: center;
+  gap: var(--ol8-component-navigation-item-gap);
+  min-inline-size: 0;
+}
+
+/* "Labels do not wrap." A narrow list scrolls; it never grows a second line. */
+.ol8-nav-item__label {
+  white-space: nowrap;
+  font-size: var(--_label-size);
+  line-height: var(--_label-line);
+}
+
+.ol8-nav-item__icon { flex: none; }
+
+.ol8-nav-item[data-ol8-layout="stacked"] .ol8-nav-item__content {
+  flex-direction: column;
+  gap: 0;
+}
+
+/* ---- Size ------------------------------------------------------------- */
+.ol8-nav-item[data-ol8-size="compact"] {
+  --_height: var(--ol8-component-tab-item-height-compact);
+  --_inset:  var(--ol8-component-tab-item-inset-compact);
+  --_label-size: var(--ol8-font-size-012);
+  --_label-line: var(--ol8-font-line-018);
+}
+.ol8-nav-item[data-ol8-size="standard"] {
+  --_height: var(--ol8-component-tab-item-height-standard);
+  --_inset:  var(--ol8-component-tab-item-inset-standard);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+}
+.ol8-nav-item[data-ol8-size="comfortable"] {
+  --_height: var(--ol8-component-tab-item-height-comfortable);
+  --_inset:  var(--ol8-component-tab-item-inset-comfortable);
+  --_label-size: var(--ol8-font-size-016);
+  --_label-line: var(--ol8-font-line-024);
+}
+.ol8-nav-item[data-ol8-size="large"] {
+  --_height: var(--ol8-component-tab-item-height-large);
+  --_inset:  var(--ol8-component-tab-item-inset-large);
+  --_label-size: var(--ol8-font-size-021);
+  --_label-line: var(--ol8-font-line-030);
+}
+
+.ol8-nav-item--tab,
+.ol8-nav-item--segment     { --_radius: var(--ol8-component-tab-item-radius); }
+.ol8-nav-item--destination { --_radius: var(--ol8-component-tab-bar-item-radius); }
+
+/* ---- State ------------------------------------------------------------ */
+@media (hover: hover) and (pointer: fine) {
+  .ol8-nav-item:hover:not(:disabled) {
+    background: var(--ol8-color-actionquiet-surfacehover);
+    color: var(--ol8-color-actionquiet-contenthover);
+  }
+}
+.ol8-nav-item:active:not(:disabled) {
+  background: var(--ol8-color-actionquiet-surfacepressed);
+  color: var(--ol8-color-actionquiet-contentpressed);
+}
+
+/* "Focus uses the approved inward treatment so parent clipping cannot crop it."
+   An outward ring would be cut by a scrolling tab list. */
+.ol8-nav-item:focus-visible {
+  outline: none;
+  box-shadow: inset 0 0 0 var(--ol8-component-navigation-focus-inset) var(--ol8-color-focus-inner);
+}
+
+.ol8-nav-item:disabled {
+  color: var(--ol8-color-text-disabled);
+  background: transparent;
+  cursor: not-allowed;
+}
+
+/* ---- Selection · Tab Item raises an indicator ------------------------- */
+.ol8-nav-item__indicator {
+  position: absolute;
+  inset-block-end: 0;
+  inset-inline: var(--ol8-component-tab-item-indicator-inset);
+  block-size: var(--ol8-component-tab-item-indicator-thickness);
+  border-radius: var(--ol8-shape-radius-full);
+  background: transparent;
+}
+.ol8-nav-item--tab[aria-selected="true"] {
+  color: var(--ol8-color-actionprimary-default);
+}
+.ol8-nav-item--tab[aria-selected="true"] > .ol8-nav-item__indicator {
+  background: var(--ol8-color-actionprimary-default);
+}
+
+/* ---- Selection · Segment and Destination take the surface ------------- */
+.ol8-nav-item--segment[aria-pressed="true"],
+.ol8-nav-item--destination[aria-current] {
+  background: var(--ol8-color-selection-surface);
+  color: var(--ol8-color-selection-content);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ol8-nav-item { transition-duration: var(--ol8-motion-duration-instant); }
+}
+
+@media (forced-colors: active) {
+  .ol8-nav-item:focus-visible {
+    outline: var(--ol8-component-navigation-focus-inset) solid Highlight;
+    outline-offset: calc(var(--ol8-component-navigation-focus-inset) * -1);
+    box-shadow: none;
+  }
+  .ol8-nav-item--tab[aria-selected="true"] > .ol8-nav-item__indicator { background: Highlight; }
+  .ol8-nav-item--segment[aria-pressed="true"],
+  .ol8-nav-item--destination[aria-current] { background: Highlight; color: HighlightText; }
+}

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

@@ -0,0 +1,95 @@
+/**
+ * Oneli8 · Navigation Item — the shared internal molecule.
+ *
+ * Figma draws three of these: Tab Item (688:51), Segment Item (695:167) and
+ * Destination Item (700:292). They are the same molecule with three selection
+ * languages, and the navigation contract is explicit that all three are
+ * internal: "The public package exports the three Organisms, preventing
+ * consumers from breaking group ownership or creating disconnected state
+ * behavior." So nothing here is re-exported from the package index.
+ *
+ * Figma's six States are review evidence, never classes. Hover, Pressed and
+ * Focus are browser interactions; Selected and Current are owned by the parent
+ * organism; Disabled is the native attribute.
+ */
+import { renderIcon } from '../../atoms/icon/index.js';
+import { renderNavigationBadge } from '../../atoms/navigation-badge/index.js';
+
+export const OL8_NAVIGATION_KINDS = ['tab', 'segment', 'destination'];
+export const OL8_NAVIGATION_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+export const OL8_NAVIGATION_LAYOUTS = ['inline', 'stacked'];
+
+/**
+ * @param {{
+ *   kind:string, label?:string, icon?:string, badge?:string|number,
+ *   layout?:string, selected?:boolean, disabled?:boolean,
+ *   ariaLabel?:string, id?:string, controls?:string, href?:string,
+ *   tabIndex?:number, extraAttrs?:string,
+ * }} item
+ */
+export function renderNavigationItem(item) {
+  const {
+    kind, label, icon, badge, layout = 'inline',
+    selected = false, disabled = false, ariaLabel, id, controls, href,
+    tabIndex, extraAttrs = '',
+  } = item;
+
+  if (!OL8_NAVIGATION_KINDS.includes(kind)) throw new Error(`[ol8] unknown navigation item kind "${kind}"`);
+  if (!OL8_NAVIGATION_LAYOUTS.includes(layout)) throw new Error(`[ol8] unknown navigation layout "${layout}"`);
+  if (!label && !icon) throw new Error('[ol8] a navigation item needs a label, an icon, or both.');
+  // "Icon-only items require ariaLabel and a product level discoverable Tooltip."
+  if (!label && !ariaLabel) {
+    throw new Error('[ol8] an icon only navigation item requires an ariaLabel, since a glyph is not a name.');
+  }
+  // "Disabled TabBar destination is unsupported and blocks; no silent redesign."
+  if (kind === 'destination' && disabled) {
+    throw new Error('[ol8] a destination cannot be disabled. A place a person cannot go does not belong in navigation.');
+  }
+
+  const content =
+    `<span class="ol8-nav-item__content">` +
+    (icon ? renderIcon(icon, { size: 18, className: 'ol8-nav-item__icon' }) : '') +
+    (label ? `<span class="ol8-nav-item__label">${escapeText(label)}</span>` : '') +
+    (badge !== undefined && badge !== null && badge !== '' ? renderNavigationBadge(badge) : '') +
+    `</span>`;
+
+  // Tab Item marks selection with an indicator bar; Segment and Destination
+  // mark it with the selection surface. The bar is always in the DOM so
+  // selecting does not change the box.
+  const indicator = kind === 'tab' ? `<span class="ol8-nav-item__indicator" aria-hidden="true"></span>` : '';
+
+  const shared = [
+    `class="ol8-nav-item ol8-nav-item--${kind}"`,
+    `data-ol8-layout="${layout}"`,
+    id ? `id="${escapeAttr(id)}"` : '',
+    ariaLabel ? `aria-label="${escapeAttr(ariaLabel)}"` : '',
+    extraAttrs,
+  ].filter(Boolean);
+
+  if (kind === 'destination') {
+    if (typeof href !== 'string' || href === '') {
+      throw new Error('[ol8] a destination requires an href. Tab Bar navigates, so it uses real links.');
+    }
+    const attrs = [
+      ...shared,
+      `href="${escapeAttr(href)}"`,
+      selected ? 'aria-current="page"' : '',
+    ].filter(Boolean).join(' ');
+    return `<a ${attrs}>${content}</a>`;
+  }
+
+  const attrs = [
+    ...shared,
+    'type="button"',
+    kind === 'tab' ? 'role="tab"' : '',
+    kind === 'tab' ? `aria-selected="${selected}"` : `aria-pressed="${selected}"`,
+    kind === 'tab' && controls ? `aria-controls="${escapeAttr(controls)}"` : '',
+    disabled ? 'disabled' : '',
+    tabIndex !== undefined ? `tabindex="${tabIndex}"` : '',
+  ].filter(Boolean).join(' ');
+
+  return `<button ${attrs}>${content}${indicator}</button>`;
+}
+
+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/select/index.js

@@ -0,0 +1 @@
+export { renderSelect, OL8_SELECT_SIZES, OL8_SELECT_APPEARANCES, OL8_SELECT_MATERIALS, OL8_SELECT_NATIVE_POLICIES } from './select.js';

package/src/molecules/select/select.css

@@ -0,0 +1,31 @@
+/**
+ * Oneli8 · Select (MOLECULE)
+ * Figma: Select / Trigger 583:338, Molecule / Select 875:1778.
+ *
+ * "Geometry and appearance reuse approved Text Field tokens", and Figma proves
+ * it: every bound variable on the trigger control is a Text Field one. So
+ * Select carries the field classes and adds only what a native select needs,
+ * which is the disclosure mark and the removal of the platform's own arrow.
+ */
+
+.ol8-select__input {
+  appearance: none;
+  cursor: pointer;
+}
+.ol8-select__input:disabled { cursor: not-allowed; }
+
+/* The native control keeps its own text colour rules, so the value takes the
+   primary ink while an unselected placeholder option stays secondary. */
+.ol8-select__input:has(option[value=""]:checked) { color: var(--ol8-color-text-secondary); }
+
+.ol8-select__disclosure {
+  flex: none;
+  color: var(--ol8-color-icon-secondary);
+  pointer-events: none;
+}
+.ol8-select[data-ol8-disabled] .ol8-select__disclosure { color: var(--ol8-color-icon-disabled); }
+
+/* The disclosure sits over the control, so a click anywhere still reaches the
+   native select underneath and opens the platform picker. */
+.ol8-select .ol8-field__control { position: relative; }
+.ol8-select__input { flex: 1 1 auto; min-inline-size: 0; }

package/src/molecules/select/select.js

@@ -0,0 +1,127 @@
+/**
+ * Oneli8 · Select — headless behavior.
+ *
+ * Figma (583:338 Trigger, 875:1778 Select): "Geometry and appearance reuse
+ * approved Text Field tokens; focus remains inward."
+ *
+ * The contract is native first and says so plainly: "On the web, ordinary
+ * Select uses a labelled native select whenever its option and appearance
+ * requirements fit native behavior", and "A native control is not replaced
+ * merely to force pixel identity."
+ *
+ * So this renders a real <select>. The user agent owns the keyboard, the type
+ * ahead, the picker and the announcements, which is exactly what the contract
+ * asks for: "Oneli8 does not intercept native keys to imitate a different
+ * platform." A custom listbox is available, but only when the caller says
+ * native="custom-allowed" and therefore accepts the whole contract that comes
+ * with it.
+ */
+import { renderIcon } from '../../atoms/icon/index.js';
+import { renderFormMessage } from '../form-message/index.js';
+
+export const OL8_SELECT_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+export const OL8_SELECT_APPEARANCES = ['outline', 'filled'];
+export const OL8_SELECT_MATERIALS = ['regular', 'gem'];
+export const OL8_SELECT_NATIVE_POLICIES = ['preferred', 'required', 'custom-allowed'];
+
+let sequence = 0;
+
+/**
+ * @param {{
+ *   label:string, options:Array<{value:string,label:string,disabled?:boolean,group?:string}>,
+ *   name?:string, id?:string, value?:string, size?:string, appearance?:string, material?:string,
+ *   showLabel?:boolean, required?:boolean, disabled?:boolean, invalid?:boolean,
+ *   placeholderOption?:string, leadingIcon?:string,
+ *   instruction?:string, message?:string, messageTone?:string,
+ *   native?:string, className?:string,
+ * }} options
+ */
+export function renderSelect(options) {
+  const {
+    label, options: items = [], name, id = `ol8-select-${++sequence}`, value,
+    size = 'comfortable', appearance = 'outline', material = 'regular',
+    showLabel = true, required = false, disabled = false, invalid = false,
+    placeholderOption, leadingIcon,
+    instruction, message, messageTone = 'critical',
+    native = 'preferred', className,
+  } = options ?? {};
+
+  if (typeof label !== 'string' || label === '') {
+    throw new Error('[ol8] Select requires a label. A placeholder is never the label.');
+  }
+  if (!Array.isArray(items) || items.length === 0) throw new Error('[ol8] Select needs at least one option.');
+  if (!OL8_SELECT_SIZES.includes(size)) throw new Error(`[ol8] unknown select size "${size}"`);
+  if (!OL8_SELECT_APPEARANCES.includes(appearance)) throw new Error(`[ol8] unknown select appearance "${appearance}"`);
+  if (!OL8_SELECT_MATERIALS.includes(material)) throw new Error(`[ol8] unknown select material "${material}"`);
+  if (!OL8_SELECT_NATIVE_POLICIES.includes(native)) throw new Error(`[ol8] unknown native policy "${native}"`);
+  if (native === 'custom-allowed') {
+    throw new Error('[ol8] a custom select is justified only when the product needs behaviour native Select cannot provide, and only with the complete focus, keyboard, announcement, form, mobile and forced colour contract implemented. Use Combobox, which implements it.');
+  }
+
+  const instructionId = instruction ? `${id}-instruction` : null;
+  const messageId = message ? `${id}-message` : null;
+  const describedBy = [instructionId, messageId].filter(Boolean).join(' ');
+
+  // Grouped options keep their source order, the way the popup groups do.
+  const groups = [];
+  for (const item of items) {
+    const group = item.group ?? null;
+    const last = groups[groups.length - 1];
+    if (last && last.name === group) last.items.push(item);
+    else groups.push({ name: group, items: [item] });
+  }
+  const optionMarkup = groups.map(group => {
+    const inner = group.items.map(item =>
+      `<option value="${escapeAttr(item.value)}"${item.value === value ? ' selected' : ''}` +
+      `${item.disabled ? ' disabled' : ''}>${escapeText(item.label)}</option>`).join('');
+    return group.name
+      ? `<optgroup label="${escapeAttr(group.name)}">${inner}</optgroup>`
+      : inner;
+  }).join('');
+
+  // "placeholderOption only when an unselected value is valid or required
+  // validation needs an explicit prompt."
+  const placeholder = placeholderOption
+    ? `<option value=""${value ? '' : ' selected'}${required ? ' disabled' : ''}>${escapeText(placeholderOption)}</option>`
+    : '';
+
+  const attrs = [
+    `class="ol8-field ol8-select${className ? ` ${className}` : ''}"`,
+    `data-ol8-size="${size}"`,
+    `data-ol8-appearance="${appearance}"`,
+    material === 'gem' ? 'data-ol8-material="gem"' : '',
+    disabled ? 'data-ol8-disabled="true"' : '',
+    invalid ? 'data-ol8-invalid="true"' : '',
+  ].filter(Boolean).join(' ');
+
+  return `<div ${attrs}>` +
+    (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>`
+      : '') +
+    `<div class="ol8-field__control-stack"><div class="ol8-field__control">` +
+      (leadingIcon ? renderIcon(leadingIcon, { size: 18, className: 'ol8-field__leading-icon' }) : '') +
+      `<select class="ol8-field__input ol8-select__input" id="${escapeAttr(id)}"` +
+        (name ? ` name="${escapeAttr(name)}"` : '') +
+        (required ? ' required' : '') +
+        (disabled ? ' disabled' : '') +
+        (invalid ? ' aria-invalid="true"' : '') +
+        (invalid && messageId ? ` aria-errormessage="${messageId}"` : '') +
+        (describedBy ? ` aria-describedby="${escapeAttr(describedBy)}"` : '') +
+        (showLabel ? '' : ` aria-label="${escapeAttr(label)}"`) +
+      `>${placeholder}${optionMarkup}</select>` +
+      // The disclosure is decoration: the native control already tells a screen
+      // reader that it opens a list.
+      renderIcon('chevron-down', { size: 18, className: 'ol8-select__disclosure' }) +
+    `</div></div>` +
+    (instruction ? `<div class="ol8-field__instruction" id="${instructionId}">${escapeText(instruction)}</div>` : '') +
+    (message
+      ? `<div class="ol8-field__supporting">${renderFormMessage(message, { tone: messageTone, id: messageId })}</div>`
+      : '') +
+    `</div>`;
+}
+
+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/selection-option/selection-option.js

@@ -14,8 +14,8 @@
  *     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 <li> —
- *     so unavailability is aria-disabled.
+ *   - 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';
 
@@ -58,14 +58,14 @@ export function renderSelectionOption(label, options = {}) {
   const lead = leadingIcon ? renderIcon(leadingIcon, { size: 18 }) : '';
   const check = `<span class="ol8-option__check" aria-hidden="true">${selected ? renderIconSvg('check') : ''}</span>`;
 
-  return `<li ${attrs}><span class="ol8-option__surface">` +
+  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></li>`;
+    `</span></div>`;
 }
 
 /** Flips one option's selected state and repaints its trailing check. */

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

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