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

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-picker/choice-picker.css

@@ -0,0 +1,98 @@
+/**
+ * Oneli8 · Choice Picker (ORGANISM)
+ * Figma: Organism / Choice Picker / Soft Hexagon 906:2898 (16 variants)
+ *
+ * Three parts stacked twelve apart: a search field, a wrapping matrix of chips,
+ * and in Apply mode a commitment line. The search field is the canonical Text
+ * Field owner and the chips are the canonical Choice Chip owner, so neither is
+ * restyled here.
+ *
+ * Read from all four sizes in Figma: the root gap, the matrix gap and the
+ * commitment typography do NOT scale with the picker size. They are twelve,
+ * six, and 12/18 at Compact, Standard, Comfortable and Large alike. Only the
+ * search field and the chips take the size.
+ */
+
+.ol8-picker {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ol8-spacing-stack-related);
+  inline-size: 100%;
+}
+
+/* "The matrix wraps with 6px gaps and preserves source/reading order; it is not
+   a masonry layout." A plain wrapping flex row is exactly that. */
+.ol8-picker__matrix {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--ol8-component-choice-chip-gap);
+}
+
+/* Figma: HORIZONTAL, space between, 24 tall, both texts secondary at 12/18. */
+.ol8-picker__commitment {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--ol8-spacing-inline-standard);
+  min-block-size: var(--ol8-size-icon-standard);
+  font-size: var(--ol8-font-size-012);
+  line-height: var(--ol8-font-line-018);
+  color: var(--ol8-color-text-secondary);
+}
+
+.ol8-picker__summary {
+  font-family: var(--ol8-font-family-functional);
+  color: inherit;
+}
+
+/* Clear all and the apply hint are text weight actions rather than Button
+   instances. The contract asks for Clear all to be quiet, and Figma's row is
+   twenty four tall, which a Button's protected forty eight target would break.
+   They are still real buttons, so they are reachable and announced. */
+.ol8-picker__apply,
+.ol8-picker__clear {
+  padding: 0;
+  border: 0;
+  background: none;
+  font-family: var(--ol8-font-family-functional);
+  font-size: inherit;
+  line-height: inherit;
+  color: var(--ol8-color-actionquiet-contentdefault);
+  cursor: pointer;
+}
+.ol8-picker__apply:hover,
+.ol8-picker__clear:hover {
+  color: var(--ol8-color-actionquiet-contenthover);
+  text-decoration: underline;
+}
+.ol8-picker__apply:focus-visible,
+.ol8-picker__clear:focus-visible {
+  outline: var(--ol8-focus-ring-innerwidth) solid var(--ol8-color-focus-inner);
+  outline-offset: var(--ol8-focus-ring-offset);
+}
+
+.ol8-picker[data-ol8-availability="disabled"] .ol8-picker__apply,
+.ol8-picker[data-ol8-availability="disabled"] .ol8-picker__clear {
+  color: var(--ol8-color-actionquiet-contentdisabled);
+  cursor: not-allowed;
+}
+
+/* The search label stays associated while the composition hides it. */
+.ol8-picker__label-row--hidden {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* Retrieval and result counts are announced rather than only drawn. */
+.ol8-picker__status {
+  position: absolute;
+  inline-size: 1px;
+  block-size: 1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Choice Picker (ORGANISM) — search over a wrapping matrix of choices.
+ * The inline composition is canonical: an accessible group holding a search
+ * field, real checkboxes wearing the Choice Chip appearance, and, in Apply
+ * mode, a commitment line. It is deliberately not a dialog pretending to be a
+ * listbox, because the surface holds search, many choices and actions.
+ */
+export type Ol8PickerSize = 'compact' | 'standard' | 'comfortable' | 'large';
+export type Ol8PickerMaterial = 'regular' | 'gem';
+export type Ol8CommitBehavior = 'immediate' | 'apply';
+export type Ol8PickerPresentation = 'inline' | 'popup';
+/** One treatment across an instance; peers never mix Check and None. */
+export type Ol8PickerMark = 'check' | 'none';
+
+export declare const OL8_PICKER_SIZES: readonly Ol8PickerSize[];
+export declare const OL8_PICKER_MATERIALS: readonly Ol8PickerMaterial[];
+export declare const OL8_COMMIT_BEHAVIORS: readonly Ol8CommitBehavior[];
+export declare const OL8_PICKER_PRESENTATIONS: readonly Ol8PickerPresentation[];
+export declare const OL8_PICKER_MARKS: readonly Ol8PickerMark[];
+
+export interface Ol8PickerOption {
+  value: string;
+  label: string;
+  selected?: boolean;
+  disabled?: boolean;
+}
+
+export interface Ol8ChoicePickerOptions {
+  /** Names the search. Kept associated even when visually hidden. */
+  label: string;
+  id?: string;
+  name?: string;
+  options?: Ol8PickerOption[];
+  /** Apply holds a pending set; immediate commits each toggle at once. */
+  commitBehavior?: Ol8CommitBehavior;
+  presentation?: Ol8PickerPresentation;
+  mark?: Ol8PickerMark;
+  size?: Ol8PickerSize;
+  material?: Ol8PickerMaterial;
+  inputValue?: string;
+  placeholder?: string;
+  showLabel?: boolean;
+  selectedSummary?: string;
+  /** Apply mode only. Immediate mode rejects it rather than drawing a lie. */
+  applyHint?: string;
+  showClearAll?: boolean;
+  clearAllLabel?: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+  status?: 'none' | 'loading' | 'empty' | 'error';
+  statusText?: string;
+  className?: string;
+}
+
+export declare function renderChoicePicker(options: Ol8ChoicePickerOptions): string;
+
+/**
+ * Apply mode only. Enter commits the pending set, Escape restores the last
+ * committed one without closing or moving focus, and a composing IME is left
+ * alone. Both dispatch events rather than mutating state.
+ */
+export declare function hydrateChoicePickers(root?: ParentNode): number;

package/src/organisms/choice-picker/choice-picker.js

@@ -0,0 +1,201 @@
+/**
+ * Oneli8 · Choice Picker (ORGANISM)
+ *
+ * Figma: Organism / Choice Picker / Soft Hexagon 906:2898 (16 variants,
+ * Material x Commitment x Size).
+ *
+ * From the Figma description:
+ *   "Choice Picker organism using canonical search-field and Soft Hexagon
+ *    Choice Chip owners. Size propagates through all children; Commitment
+ *    controls Apply versus Immediate behavior."
+ *
+ * And from the maintainer decision recorded on the same component:
+ *   "Public ChoicePicker defaults to presentation=inline ... Search, existing
+ *    Choice Chip/Token molecules and commitment summary remain in place. Apply
+ *    mode holds pending selection; Enter from Search or a checkbox commits it,
+ *    Escape restores the last committed set without closing the inline panel.
+ *    The Enter-to-apply hint is also a focusable clickable action ... Immediate
+ *    mode commits each toggle and omits that action."
+ *
+ * So the inline composition is canonical, and it is a group rather than a
+ * dialog: a search field, a wrapping matrix of real checkboxes wearing the
+ * chip appearance, and a commitment line that exists only in Apply mode.
+ *
+ * THE HINT IS A BUTTON, NOT A SENTENCE
+ * Figma draws "Enter to apply" as text. The decision above requires it to be an
+ * actual clickable and focusable action, because a keyboard instruction is not
+ * an affordance for anyone using a pointer, touch, or a screen reader. So it is
+ * a button that reads as the hint.
+ */
+import { renderChoiceChip } from '../../molecules/choice-chip/choice-chip.js';
+import { renderIcon } from '../../atoms/icon/icon.js';
+
+export const OL8_PICKER_SIZES = ['compact', 'standard', 'comfortable', 'large'];
+export const OL8_PICKER_MATERIALS = ['regular', 'gem'];
+export const OL8_COMMIT_BEHAVIORS = ['immediate', 'apply'];
+export const OL8_PICKER_PRESENTATIONS = ['inline', 'popup'];
+/** One mark treatment across an instance; peers never mix Check and None. */
+export const OL8_PICKER_MARKS = ['check', 'none'];
+
+/**
+ * @param {{
+ *   label:string, id?:string, name?:string,
+ *   options?:Array<{value:string,label:string,selected?:boolean,disabled?:boolean}>,
+ *   commitBehavior?:string, presentation?:string, mark?:string,
+ *   size?:string, material?:string,
+ *   inputValue?:string, placeholder?:string, showLabel?:boolean,
+ *   selectedSummary?:string, applyHint?:string,
+ *   showClearAll?:boolean, clearAllLabel?:string,
+ *   disabled?:boolean, readOnly?:boolean,
+ *   status?:string, statusText?:string, className?:string,
+ * }} options
+ */
+export function renderChoicePicker(options = {}) {
+  const {
+    label, id, name, options: items = [],
+    commitBehavior = 'immediate', presentation = 'inline', mark = 'check',
+    size = 'comfortable', material = 'regular',
+    inputValue = '', placeholder, showLabel = false,
+    selectedSummary, applyHint = 'Enter to apply',
+    showClearAll = false, clearAllLabel = 'Clear all',
+    disabled = false, readOnly = false,
+    status = 'none', statusText, className,
+  } = options;
+
+  if (!label || !String(label).trim()) throw new Error('[ol8] a Choice Picker requires a label for its search');
+  if (!OL8_PICKER_SIZES.includes(size)) throw new Error(`[ol8] unknown size "${size}"`);
+  if (!OL8_PICKER_MATERIALS.includes(material)) throw new Error(`[ol8] unknown material "${material}"`);
+  if (!OL8_COMMIT_BEHAVIORS.includes(commitBehavior)) throw new Error(`[ol8] unknown commit behavior "${commitBehavior}"`);
+  if (!OL8_PICKER_PRESENTATIONS.includes(presentation)) throw new Error(`[ol8] unknown presentation "${presentation}"`);
+  if (!OL8_PICKER_MARKS.includes(mark)) throw new Error(`[ol8] unknown mark "${mark}"`);
+  if (commitBehavior === 'immediate' && options.applyHint !== undefined) {
+    throw new Error('[ol8] immediate commitment applies every toggle at once, so an apply action would be a lie');
+  }
+  if (status !== 'none' && !statusText) {
+    throw new Error('[ol8] a picker status needs words. A spinner alone tells a screen reader nothing.');
+  }
+
+  const uid = id ?? `ol8-picker-${Math.random().toString(36).slice(2, 9)}`;
+  const labelId = `${uid}-label`;
+  const statusId = `${uid}-status`;
+  const selected = items.filter(o => o.selected);
+
+  // Every option is a real checkbox wearing the chip appearance. The mark
+  // treatment is the same for every peer, which is why it is one setting on
+  // the picker rather than a property of each chip.
+  const matrix = items.map((o, i) => renderChoiceChip(o.label, {
+    size,
+    selected: !!o.selected,
+    showMark: mark === 'check' && !!o.selected,
+    disabled: disabled || readOnly || o.disabled,
+    name: name ? `${name}[]` : undefined,
+    value: o.value,
+    id: `${uid}-option-${i}`,
+    className: 'ol8-picker__chip',
+  })).join('');
+
+  const summary = selectedSummary
+    ?? `${selected.length} selected`;
+
+  // Apply mode holds a pending set, so it says what is pending and offers the
+  // way to commit it. Immediate mode has nothing pending and says nothing.
+  const commitment = commitBehavior === 'apply'
+    ? `<div class="ol8-picker__commitment">` +
+        `<span class="ol8-picker__summary">${escapeText(summary)}</span>` +
+        (showClearAll
+          ? `<button type="button" class="ol8-picker__clear">${escapeText(clearAllLabel)}</button>`
+          : '') +
+        `<button type="button" class="ol8-picker__apply">${escapeText(applyHint)}</button>` +
+      `</div>`
+    : '';
+
+  const search =
+    `<div class="ol8-field ol8-picker__field" data-ol8-size="${size}" data-ol8-appearance="outline"` +
+    (material === 'gem' ? ' data-ol8-material="gem"' : '') + '>' +
+      `<div class="ol8-field__label-row${showLabel ? '' : ' ol8-picker__label-row--hidden'}">` +
+        `<label class="ol8-field__label" id="${labelId}" for="${uid}">${escapeText(label)}</label>` +
+      `</div>` +
+      `<div class="ol8-field__control-stack"><div class="ol8-field__control">` +
+        renderIcon('search', { size: 18, className: 'ol8-field__leading-icon' }) +
+        `<input class="ol8-field__input ol8-picker__input" id="${uid}" type="search"` +
+          ` value="${escapeAttr(inputValue)}"` +
+          (placeholder ? ` placeholder="${escapeAttr(placeholder)}"` : '') +
+          (disabled ? ' disabled' : '') + (readOnly ? ' readonly' : '') +
+          ` aria-describedby="${statusId}">` +
+      `</div></div>` +
+    `</div>`;
+
+  const rootAttrs = [
+    `class="ol8-picker${className ? ` ${className}` : ''}"`,
+    `data-ol8-size="${size}"`,
+    `data-ol8-commitment="${commitBehavior}"`,
+    `data-ol8-presentation="${presentation}"`,
+    `data-ol8-mark="${mark}"`,
+    material === 'gem' ? 'data-ol8-material="gem"' : '',
+    disabled ? 'data-ol8-availability="disabled"' : '',
+    readOnly ? 'data-ol8-readonly="true"' : '',
+    // A group, not a dialog: the surface holds search, many independent
+    // choices and actions, so pretending it is one listbox would be a lie.
+    `role="group" aria-labelledby="${labelId}"`,
+  ].filter(Boolean).join(' ');
+
+  return `<div ${rootAttrs}>` +
+    search +
+    `<div class="ol8-picker__matrix">${matrix}</div>` +
+    commitment +
+    `<span class="ol8-picker__status" id="${statusId}" role="status" aria-live="polite">` +
+      escapeText(status !== 'none' ? statusText : '') +
+    `</span>` +
+    `</div>`;
+}
+
+/**
+ * Binds every picker under `root`. Idempotent.
+ *
+ * Only Apply mode needs behaviour: it holds a pending set, so Enter commits it
+ * and Escape restores the last committed one without closing the panel or
+ * moving focus. Immediate mode has nothing to hold, so a toggle is the whole
+ * interaction and the browser already does it.
+ *
+ * Both dispatch events rather than mutating state, because the selection
+ * belongs to the application.
+ */
+export function hydrateChoicePickers(root = document) {
+  const pickers = [...root.querySelectorAll('.ol8-picker')];
+
+  for (const picker of pickers) {
+    if (picker.dataset.ol8PickerBound === 'true') continue;
+    if (picker.dataset.ol8Commitment !== 'apply') { picker.dataset.ol8PickerBound = 'true'; continue; }
+
+    const commit = () => picker.dispatchEvent(new CustomEvent('ol8:apply', { bubbles: true }));
+    const restore = () => picker.dispatchEvent(new CustomEvent('ol8:cancel', { bubbles: true }));
+
+    picker.addEventListener('keydown', (event) => {
+      // A composing IME uses Enter to choose a candidate. Committing there
+      // would apply a selection the person was in the middle of typing.
+      if (event.isComposing || event.keyCode === 229) return;
+      const from = event.target;
+      const inSearch = from.classList && from.classList.contains('ol8-picker__input');
+      const inChip = from.closest && from.closest('.ol8-picker__chip');
+      if (event.key === 'Enter' && (inSearch || inChip)) {
+        event.preventDefault();
+        commit();
+      } else if (event.key === 'Escape') {
+        event.preventDefault();
+        restore();                       // focus deliberately stays put
+      }
+    });
+
+    const apply = picker.querySelector(':scope .ol8-picker__apply');
+    if (apply) apply.addEventListener('click', commit);
+    const clear = picker.querySelector(':scope .ol8-picker__clear');
+    if (clear) clear.addEventListener('click', () =>
+      picker.dispatchEvent(new CustomEvent('ol8:clearall', { bubbles: true })));
+
+    picker.dataset.ol8PickerBound = 'true';
+  }
+  return pickers.length;
+}
+
+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/organisms/choice-picker/index.d.ts

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

package/src/organisms/choice-picker/index.js

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

package/src/organisms/combobox/combobox.css

@@ -0,0 +1,40 @@
+/**
+ * Oneli8 · Combobox (ORGANISM)
+ * Figma: Organism / Combobox 883:2159 — "Reuses approved Text Field, Selection
+ * Popup and governed icon atoms."
+ *
+ * So the field geometry is the field's, the popup is the popup's, and this
+ * file adds only what belongs to the combination: where the popup sits, and
+ * the two marks at the trailing edge.
+ */
+
+.ol8-combobox { position: relative; }
+
+/* "Closed control to popup block gap" is a token, so the popup sits where the
+   design says rather than wherever absolute positioning lands it. */
+.ol8-combobox__popup {
+  position: absolute;
+  z-index: 1;
+  inset-inline: 0;
+  inset-block-start: calc(100% + var(--ol8-component-selectionpopup-gap));
+}
+
+.ol8-combobox__disclosure {
+  flex: none;
+  display: inline-flex;
+  color: var(--ol8-color-icon-secondary);
+  cursor: pointer;
+}
+
+.ol8-combobox__clear {
+  flex: none;
+  display: inline-flex;
+  border: 0;
+  padding: 0;
+  background: none;
+  color: var(--ol8-color-icon-secondary);
+  cursor: pointer;
+}
+.ol8-combobox__clear:disabled { color: var(--ol8-color-icon-disabled); cursor: not-allowed; }
+
+.ol8-combobox[data-ol8-disabled] .ol8-combobox__disclosure { color: var(--ol8-color-icon-disabled); cursor: not-allowed; }