@blukavantui/community 1.0.1 → 1.2.0

package/src/form-layout/choice.ts

@@ -0,0 +1,82 @@
+import { el, frame, lifecycle, common, attr, uid } from './shared.js';
+import type { CheckboxOptions, SwitchOptions, RadioButtonOptions, RadioGroupOptions, FieldComponent, FieldEvents } from './types.js';
+
+type ToggleOptions = CheckboxOptions & SwitchOptions;
+function toggle(host: HTMLElement, initial: ToggleOptions, events: FieldEvents<boolean>, kind: 'checkbox' | 'switch' | 'radio'): FieldComponent<ToggleOptions, boolean> {
+  let p = { ...initial }, initialized = false; const f = frame(host, p), label = el('label', 'blu-choice');
+  const input = el('input', 'blu-choice__input'), mark = el('span', 'blu-choice__mark'), text = el('span'), state = el('span', 'blu-choice__state');
+  input.type = kind === 'radio' ? 'radio' : 'checkbox'; if (kind === 'switch') input.setAttribute('role', 'switch');
+  label.classList.add('blu-choice--' + kind); mark.setAttribute('aria-hidden', 'true'); state.setAttribute('aria-hidden', 'true');
+  label.append(input, mark, text, state); f.body.append(label); const life = lifecycle(f.root, reset);
+  function update(patch: Partial<ToggleOptions>) {
+    life.check(); if (initialized && kind === 'radio' && !('Checked' in patch)) p.Checked = input.checked;
+    p = { ...p, ...patch }; f.paint(p, [input]); f.label.hidden = true;
+    // The wrapping label names this control. Safari also includes a hidden
+    // explicit label in its accessible name if that label keeps its `for`.
+    f.label.removeAttribute('for');
+    common(input, p); input.checked = !!p.Checked; input.indeterminate = kind === 'checkbox' && !!p.Indeterminate;
+    input.value = p.Value || 'on'; attr(input, 'aria-readonly', p.ReadOnly ? 'true' : undefined);
+    text.textContent = (p.Label || '') + (p.Required ? ' *' : ''); state.textContent = input.checked ? (p.OnText || '') : (p.OffText || ''); initialized = true;
+  }
+  function reset() { update({ Checked: !!initial.Checked, Indeterminate: !!initial.Indeterminate }); }
+  input.addEventListener('click', event => { if (p.ReadOnly) event.preventDefault(); }, { signal: life.signal });
+  input.addEventListener('keydown', event => { if (p.ReadOnly && ['ArrowLeft','ArrowRight','ArrowUp','ArrowDown',' '].includes(event.key)) event.preventDefault(); }, { signal: life.signal });
+  input.addEventListener('change', () => { p.Checked = input.checked; p.Indeterminate = false; state.textContent = input.checked ? (p.OnText || '') : (p.OffText || ''); events.Change?.(input.checked); }, { signal: life.signal });
+  input.addEventListener('blur', () => events.Blur?.(), { signal: life.signal }); update({});
+  return { element: f.root, control: input, update, reset, getValue: () => input.checked, focus: () => input.focus(), validate: () => input.reportValidity(), destroy: life.destroy };
+}
+export function createCheckbox(host: HTMLElement, options: CheckboxOptions = {}, events: FieldEvents<boolean> = {}) { return toggle(host, options, events, 'checkbox'); }
+export function createSwitch(host: HTMLElement, options: SwitchOptions = {}, events: FieldEvents<boolean> = {}) { return toggle(host, options, events, 'switch'); }
+export function createRadioButton(host: HTMLElement, options: RadioButtonOptions, events: FieldEvents<boolean> = {}) { return toggle(host, options, events, 'radio'); }
+
+export function createRadioGroup(host: HTMLElement, initial: RadioGroupOptions, events: FieldEvents<string> = {}) {
+  let p = { ...initial }, controls: HTMLInputElement[] = [];
+  const f = frame(host, p, true), name = p.Name || uid(); const life = lifecycle(f.root, reset);
+  function update(patch: Partial<RadioGroupOptions>) {
+    life.check();
+    // Native bindings resend Options on every value change. Preserve the same
+    // inputs when the options are unchanged so keyboard and screen-reader focus
+    // stay on the selected choice.
+    const replace = !controls.length || (!!patch.Options && (
+      patch.Options.length !== p.Options.length || patch.Options.some((option, i) => {
+        const previous = p.Options[i];
+        return option.Value !== previous.Value || option.Label !== previous.Label ||
+          option.Description !== previous.Description || option.Disabled !== previous.Disabled;
+      })
+    ));
+    const focusedValue = controls.find(input => input === document.activeElement)?.value;
+    p = { ...p, ...patch };
+    if (new Set(p.Options.map(o => o.Value)).size !== p.Options.length) throw Error('Radio option values must be unique.');
+    f.body.className = 'blu-radio-group blu-radio-group--' + (p.Direction || 'Vertical').toLowerCase();
+    if (replace) {
+      f.body.replaceChildren(); controls = p.Options.map((option, i) => {
+        const label = el('label', 'blu-choice blu-choice--radio'), input = el('input', 'blu-choice__input'), mark = el('span', 'blu-choice__mark'), copy = el('span');
+        input.type = 'radio'; input.id = f.id + '-' + i; input.value = option.Value; mark.setAttribute('aria-hidden', 'true');
+        const title = el('span', '', option.Label); title.id = input.id + '-label'; copy.append(title);
+        // Keep the option's name separate from its description so screen
+        // readers do not announce the description twice via the wrapping label.
+        input.setAttribute('aria-labelledby', title.id);
+        if (option.Description) { const desc = el('small', 'blu-choice__description', option.Description); desc.id = input.id + '-description'; copy.append(desc); }
+        label.append(input, mark, copy); f.body.append(label);
+        input.onchange = () => { if (input.checked) { p.Value = input.value; events.Change?.(input.value); } };
+        input.onclick = event => { if (p.ReadOnly) event.preventDefault(); };
+        input.onkeydown = event => { if (p.ReadOnly && ['ArrowLeft','ArrowRight','ArrowUp','ArrowDown',' '].includes(event.key)) event.preventDefault(); };
+        input.onblur = () => events.Blur?.(); return input;
+      });
+    }
+    f.paint(p, controls);
+    controls.forEach((input, i) => {
+      common(input, p); input.name = p.Name || name; input.disabled = !!p.Disabled || !!p.Options[i].Disabled; input.checked = input.value === p.Value;
+      attr(input, 'aria-readonly', p.ReadOnly ? 'true' : undefined);
+      if (p.Options[i].Description) attr(input, 'aria-describedby', [input.getAttribute('aria-describedby'), input.id + '-description'].filter(Boolean).join(' '));
+    });
+    if (replace && focusedValue !== undefined) {
+      (controls.find(input => input.value === focusedValue && !input.disabled) ||
+        controls.find(input => input.checked && !input.disabled) || controls.find(input => !input.disabled))?.focus();
+    }
+  }
+  function reset() { update({ Value: initial.Value || '' }); } update({});
+  return { element: f.root, update, reset, getValue: () => controls.find(c => c.checked)?.value || '',
+    focus: () => (controls.find(c => c.checked && !c.disabled) || controls.find(c => !c.disabled))?.focus(),
+    validate: () => controls.filter(c => !c.disabled).every(c => c.reportValidity()), destroy: life.destroy };
+}

package/src/form-layout/layout.ts

@@ -0,0 +1,40 @@
+import { el, frame, bound } from './shared.js';
+import type { FormFieldOptions, ColumnsOptions, ColumnsComponent } from './types.js';
+
+/** Wrap a consumer-owned control. Destroy restores its original ARIA attributes. */
+export function createFormField(host: HTMLElement, initial: FormFieldOptions = {}) {
+  let p = { ...initial }, disposed = false, current: HTMLElement | undefined;
+  let original: Record<string, string | null> = {};
+  const f = frame(host, p), content = f.body;
+  const attributes = ['id', 'aria-describedby', 'aria-invalid', 'aria-required'];
+  function restore() { if (current) for (const name of attributes) { const value = original[name]; if (value === null) current.removeAttribute(name); else current.setAttribute(name, value); } }
+  function update(patch: Partial<FormFieldOptions>) {
+    if (disposed) throw Error('Component is destroyed.'); p = { ...p, ...patch };
+    if (p.Control !== current) {
+      restore(); content.replaceChildren(); current = p.Control;
+      if (current) { original = Object.fromEntries(attributes.map(name => [name, current!.getAttribute(name)])); content.append(current); }
+    }
+    f.paint(p, current ? [current] : []);
+    if (current && original['aria-describedby']) current.setAttribute('aria-describedby', [original['aria-describedby'], current.getAttribute('aria-describedby')].filter(Boolean).join(' '));
+  }
+  update({}); return { element: f.root, content, update, destroy() { if (disposed) return; disposed = true; restore(); f.root.remove(); } };
+}
+
+export function createColumns(host: HTMLElement, count: 2 | 3 | 4, initial: ColumnsOptions = {}): ColumnsComponent {
+  let p = { ...initial }, disposed = false; const root = el('div', 'blu-columns');
+  const columns = Array.from({ length: count }, (_, i) => { const column = el('div', 'blu-columns__column'); column.dataset.column = String(i + 1); root.append(column); return column; }); host.append(root);
+  function update(patch: Partial<ColumnsOptions>) {
+    if (disposed) throw Error('Component is destroyed.'); p = { ...p, ...patch };
+    const pairs: Record<string, string> = { Equal: 'minmax(0,1fr) minmax(0,1fr)', OneThirdTwoThirds: 'minmax(0,1fr) minmax(0,2fr)', TwoThirdsOneThird: 'minmax(0,2fr) minmax(0,1fr)', OneQuarterThreeQuarters: 'minmax(0,1fr) minmax(0,3fr)', ThreeQuartersOneQuarter: 'minmax(0,3fr) minmax(0,1fr)' };
+    if (count === 2 && p.Ratio && !pairs[p.Ratio]) throw Error('Unsupported two-column ratio.');
+    if (count === 3 && p.Ratio && !['Equal', 'WideCenter'].includes(p.Ratio)) throw Error('Unsupported three-column ratio.');
+    if (count === 4 && p.Ratio && p.Ratio !== 'Equal') throw Error('Four columns use equal widths.');
+    root.className = 'blu-columns blu-columns--stack-' + (p.StackAt || 'Medium').toLowerCase() + (p.EqualHeight ? ' blu-columns--equal-height' : '') + (p.ExtendedClass ? ' ' + p.ExtendedClass : '');
+    root.style.setProperty('--blu-columns-tracks', count === 2 ? pairs[p.Ratio || 'Equal'] : count === 3 && p.Ratio === 'WideCenter' ? 'minmax(0,1fr) minmax(0,2fr) minmax(0,1fr)' : `repeat(${count}, minmax(0, 1fr))`);
+    root.style.setProperty('--blu-columns-gap', bound(p.Gap, 24, 0, 96) + 'px'); root.style.alignItems = p.EqualHeight ? 'stretch' : (p.Align || 'Stretch').toLowerCase();
+  }
+  update({}); return { element: root, columns, update, destroy() { if (disposed) return; disposed = true; root.remove(); } };
+}
+export const createColumns2 = (host: HTMLElement, options: ColumnsOptions = {}) => createColumns(host, 2, options);
+export const createColumns3 = (host: HTMLElement, options: ColumnsOptions = {}) => createColumns(host, 3, options);
+export const createColumns4 = (host: HTMLElement, options: ColumnsOptions = {}) => createColumns(host, 4, options);

package/src/form-layout/select.ts

@@ -0,0 +1,97 @@
+import { el, attr, frame, lifecycle, common } from './shared.js';
+import type { SelectOptions, FieldEvents, FieldComponent } from './types.js';
+
+/** A styled listbox backed by a form-associated select; the native menu is never shown. */
+export function createSelect(host: HTMLElement, initial: SelectOptions, events: FieldEvents<string> = {}): FieldComponent<SelectOptions, string> {
+  let p = { ...initial }, open = false, active = -1, prefix = '', prefixAt = 0;
+  const f = frame(host, p), shell = el('div', 'blu-select'), control = el('select', 'blu-select__native');
+  const trigger = el('button', 'blu-select__trigger'), clear = el('button', 'blu-text__action', '×'), popup = el('div', 'blu-select__popup');
+  const search = el('input', 'blu-select__search'), list = el('div', 'blu-select__list'), empty = el('p', 'blu-field__help', 'No matching options');
+  control.tabIndex = -1; control.setAttribute('aria-hidden', 'true'); control.dataset.enhanced = 'true';
+  trigger.type = clear.type = 'button'; trigger.id = f.id; trigger.setAttribute('role', 'combobox'); trigger.setAttribute('aria-haspopup', 'listbox');
+  list.id = f.id + '-list'; list.setAttribute('role', 'listbox'); trigger.setAttribute('aria-controls', list.id);
+  search.type = 'search'; search.placeholder = 'Search options'; search.setAttribute('role', 'combobox'); search.setAttribute('aria-autocomplete', 'list'); search.setAttribute('aria-controls', list.id);
+  popup.hidden = true; popup.append(search, list, empty); shell.append(control, trigger, clear, popup); f.body.append(shell);
+  const hasPopover = typeof popup.showPopover === 'function'; if (hasPopover) popup.setAttribute('popover', 'manual');
+  const life = lifecycle(f.root, reset); let visible: number[] = [];
+  function position() {
+    if (!open || !hasPopover) return; const r = trigger.getBoundingClientRect();
+    const below = window.innerHeight - r.bottom - 12, above = r.top - 12;
+    const up = below < 220 && above > below, height = Math.min(320, Math.max(100, up ? above : below));
+    popup.style.cssText = `position:fixed;inset:auto;margin:0;left:${Math.max(8, Math.min(r.left, window.innerWidth - r.width - 8))}px;width:${Math.min(r.width, window.innerWidth - 16)}px;max-height:${height}px;${up ? 'bottom:' + (window.innerHeight - r.top + 6) : 'top:' + (r.bottom + 6)}px;`;
+  }
+  function activeOption(index: number) {
+    active = index; list.querySelectorAll<HTMLElement>('[role=option]').forEach(node => {
+      const isActive = Number(node.dataset.index) === active; node.dataset.active = String(isActive);
+      if (isActive) node.scrollIntoView({ block: 'nearest' });
+    });
+    const id = active < 0 ? undefined : f.id + '-option-' + active;
+    attr(trigger, 'aria-activedescendant', open ? id : undefined); attr(search, 'aria-activedescendant', open ? id : undefined);
+  }
+  function renderOptions() {
+    visible = p.Options.map((_, i) => i).filter(i => p.Options[i].Label.toLocaleLowerCase().includes(search.value.toLocaleLowerCase()));
+    list.replaceChildren();
+    for (const i of visible) {
+      const o = p.Options[i], row = el('div', 'blu-select__option', o.Label); row.id = f.id + '-option-' + i;
+      row.setAttribute('role', 'option'); row.dataset.index = String(i); row.setAttribute('aria-selected', String(o.Value === control.value));
+      row.setAttribute('aria-disabled', String(!!o.Disabled)); if (o.Description) row.append(el('small', 'blu-choice__description', o.Description));
+      row.onpointerdown = event => event.preventDefault(); row.onclick = () => { if (!o.Disabled) choose(i); }; list.append(row);
+    }
+    empty.hidden = !!visible.length;
+    const enabled = visible.filter(i => !p.Options[i].Disabled);
+    activeOption(enabled.includes(active) ? active : (enabled.find(i => p.Options[i].Value === control.value) ?? enabled[0] ?? -1));
+  }
+  function show(value: boolean, focus = true) {
+    if (value && (p.Disabled || p.ReadOnly)) return;
+    open = value; trigger.setAttribute('aria-expanded', String(open)); search.setAttribute('aria-expanded', String(open));
+    if (open) { popup.hidden = false; if (hasPopover && !popup.matches(':popover-open')) popup.showPopover(); search.value = ''; active = -1; renderOptions(); position(); if (p.Searchable) search.focus(); }
+    else { if (hasPopover && popup.matches(':popover-open')) popup.hidePopover(); popup.hidden = true; activeOption(-1); if (focus) trigger.focus(); }
+  }
+  function choose(index: number) { p.Value = index < 0 ? '' : p.Options[index].Value; control.value = p.Value; paintValue(); show(false); events.Change?.(p.Value); }
+  function paintValue() {
+    trigger.textContent = p.Options.find(o => o.Value === control.value)?.Label || p.Placeholder || 'Choose an option';
+    trigger.dataset.placeholder = String(!control.value); clear.hidden = !p.Clearable || !control.value || !!p.ReadOnly;
+    if (control.validity.valid && !p.Error) { f.error.hidden = true; f.error.textContent = ''; f.paint(p, [trigger]); }
+  }
+  function update(patch: Partial<SelectOptions>) {
+    life.check(); p = { ...p, ...patch };
+    if (p.Options.some(o => !o.Value) || new Set(p.Options.map(o => o.Value)).size !== p.Options.length) throw Error('Select option values must be non-empty and unique.');
+    common(control, p); f.paint(p, [trigger]); control.id = f.id + '-native';
+    const placeholder = el('option', '', p.Placeholder || 'Choose an option'); placeholder.value = '';
+    control.replaceChildren(placeholder, ...p.Options.map(o => { const option = el('option', '', o.Label); option.value = o.Value; option.disabled = !!o.Disabled; return option; }));
+    control.value = p.Options.some(o => o.Value === p.Value) ? p.Value! : ''; p.Value = control.value;
+    trigger.disabled = clear.disabled = !!p.Disabled; attr(trigger, 'aria-readonly', p.ReadOnly ? 'true' : undefined);
+    clear.setAttribute('aria-label', 'Clear ' + (p.Label || 'selection')); search.setAttribute('aria-label', 'Search ' + (p.Label || 'options'));
+    list.setAttribute('aria-label', p.Label || 'Options'); search.hidden = !p.Searchable;
+    if (p.Disabled || p.ReadOnly) show(false, false); else if (open) { renderOptions(); position(); }
+    trigger.setAttribute('aria-expanded', String(open)); paintValue();
+  }
+  function key(event: KeyboardEvent) {
+    if (p.Disabled || p.ReadOnly) return;
+    const enabled = visible.filter(i => !p.Options[i].Disabled), from = enabled.indexOf(active);
+    if (event.key === 'Escape' && open) { event.preventDefault(); show(false); }
+    else if (event.key === 'Tab') show(false, false);
+    else if (['ArrowDown','ArrowUp','Home','End'].includes(event.key)) {
+      if (!open) { event.preventDefault(); show(true); return; }
+      event.preventDefault();
+      const next = event.key === 'Home' ? 0 : event.key === 'End' ? enabled.length - 1 : Math.max(0, Math.min(enabled.length - 1, from + (event.key === 'ArrowDown' ? 1 : -1)));
+      activeOption(enabled[next] ?? -1);
+    } else if (event.key === 'Enter' || (event.key === ' ' && event.target !== search)) {
+      event.preventDefault(); if (!open) show(true); else if (active >= 0) choose(active);
+    } else if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && event.target !== search) {
+      event.preventDefault(); if (!open) show(true);
+      prefix = Date.now() - prefixAt > 650 ? event.key : prefix + event.key; prefixAt = Date.now();
+      const next = visible.find(i => !p.Options[i].Disabled && p.Options[i].Label.toLocaleLowerCase().startsWith(prefix.toLocaleLowerCase())); if (next !== undefined) activeOption(next);
+    }
+  }
+  function reset() { update({ Value: initial.Value || '' }); show(false, false); }
+  trigger.addEventListener('click', () => show(!open), { signal: life.signal }); clear.addEventListener('click', () => choose(-1), { signal: life.signal });
+  shell.addEventListener('keydown', key, { signal: life.signal }); search.addEventListener('input', renderOptions, { signal: life.signal });
+  document.addEventListener('pointerdown', e => { if (open && !f.root.contains(e.target as Node)) show(false, false); }, { signal: life.signal });
+  shell.addEventListener('focusout', e => { if (!shell.contains(e.relatedTarget as Node)) { show(false, false); events.Blur?.(); } }, { signal: life.signal });
+  window.addEventListener('resize', position, { signal: life.signal }); window.addEventListener('scroll', position, { signal: life.signal, capture: true });
+  control.addEventListener('invalid', e => { e.preventDefault(); attr(trigger, 'aria-invalid', 'true'); f.error.textContent = control.validationMessage; f.error.hidden = false; attr(trigger, 'aria-describedby', f.error.id); trigger.focus(); }, { signal: life.signal });
+  control.addEventListener('change', () => { p.Value = control.value; paintValue(); events.Change?.(control.value); }, { signal: life.signal });
+  update({});
+  return { element: f.root, control, update, reset, getValue: () => control.value, focus: () => trigger.focus(), validate: () => control.reportValidity(), destroy() { show(false, false); life.destroy(); } };
+}

package/src/form-layout/shared.ts

@@ -0,0 +1,57 @@
+import type { FieldOptions } from './types.js';
+export function el<K extends keyof HTMLElementTagNameMap>(tag: K, cls = '', text?: string) {
+  const node = document.createElement(tag); node.className = cls;
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+let sequence = 0;
+export function uid() { return 'blu-field-' + (++sequence) + '-' + Math.random().toString(36).slice(2, 8); }
+export function attr(node: Element, name: string, value?: string | number | boolean) {
+  if (value === undefined || value === false || value === '') node.removeAttribute(name);
+  else node.setAttribute(name, String(value));
+}
+export function frame(host: HTMLElement, options: FieldOptions, group = false) {
+  const root = el(group ? 'fieldset' : 'div', 'blu-field');
+  const label = el(group ? 'legend' : 'label', 'blu-field__label');
+  const body = el('div', 'blu-field__body'), description = el('div', 'blu-field__help'), error = el('div', 'blu-field__error');
+  const id = options.Id || uid(); description.id = id + '-help'; error.id = id + '-error'; error.setAttribute('aria-live', 'polite');
+  root.append(label, body, description, error); host.append(root);
+  function paint(p: FieldOptions, controls: HTMLElement[]) {
+    root.className = 'blu-field blu-field--' + (p.Size || 'Medium').toLowerCase() + (p.ExtendedClass ? ' ' + p.ExtendedClass : '');
+    root.dataset.invalid = String(!!p.Error); root.dataset.disabled = String(!!p.Disabled);
+    label.textContent = (p.Label || '') + (p.Required ? ' *' : ''); label.hidden = !p.Label;
+    if (!group && controls[0]) { controls[0].id ||= id; label.setAttribute('for', controls[0].id); }
+    description.textContent = p.Description || ''; description.hidden = !p.Description;
+    error.textContent = p.Error || ''; error.hidden = !p.Error;
+    const described = [p.Description ? description.id : '', p.Error ? error.id : ''].filter(Boolean).join(' ');
+    for (const control of controls) {
+      attr(control, 'aria-describedby', described); attr(control, 'aria-invalid', p.Error ? 'true' : undefined);
+      attr(control, 'aria-required', p.Required ? 'true' : undefined);
+    }
+  }
+  return { root, label, body, description, error, id, paint };
+}
+export function lifecycle(root: HTMLElement, reset: () => void) {
+  const abort = new AbortController(); let disposed = false;
+  // Native form reset is cancelable and restores values after event dispatch.
+  const form = root.closest('form');
+  form?.addEventListener('reset', event => queueMicrotask(() => { if (!disposed && !event.defaultPrevented) reset(); }), { signal: abort.signal });
+  return {
+    signal: abort.signal,
+    check() { if (disposed) throw Error('Component is destroyed.'); },
+    destroy() { if (disposed) return; disposed = true; abort.abort(); root.remove(); },
+  };
+}
+export function common(control: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement, p: FieldOptions) {
+  control.name = p.Name || ''; control.disabled = !!p.Disabled; control.required = !!p.Required;
+  if ('readOnly' in control) control.readOnly = !!p.ReadOnly;
+  control.setCustomValidity(p.Error || '');
+}
+export function bound(value: number | undefined, fallback: number, min: number, max: number) {
+  return Number.isFinite(value) ? Math.max(min, Math.min(max, value!)) : fallback;
+}
+export function imageUrl(value: string) {
+  const url = new URL(value, document.baseURI);
+  if (!['http:', 'https:'].includes(url.protocol)) throw Error('Adornment images must use an HTTP(S) or relative URL.');
+  return url.href;
+}

package/src/form-layout/table.ts

@@ -0,0 +1,86 @@
+import { el, bound, uid } from './shared.js';
+import type { TableOptions, TableEvents } from './types.js';
+
+export function tableRows<Row extends object>(options: TableOptions<Row>) {
+  const rows = [...options.Rows], key = options.SortKey;
+  if (key && options.Columns.some(c => c.Key === key && c.Sortable)) rows.sort((a, b) => {
+    const x = a[key], y = b[key]; if (x == null || y == null) return x == null ? (y == null ? 0 : 1) : -1;
+    const difference = typeof x === 'number' && typeof y === 'number' ? x - y : String(x).localeCompare(String(y), undefined, { numeric: true, sensitivity: 'base' });
+    return options.SortDirection === 'Descending' ? -difference : difference;
+  });
+  const size = options.PageSize ? Math.floor(bound(options.PageSize, 10, 1, 10000)) : Math.max(1, rows.length);
+  const pages = Math.max(1, Math.ceil(rows.length / size)), page = Math.floor(bound(options.Page, 1, 1, pages));
+  return { rows: rows.slice((page - 1) * size, page * size), page, pages, total: rows.length, start: rows.length ? (page - 1) * size + 1 : 0, end: Math.min(page * size, rows.length) };
+}
+
+/** Semantic HTML table, client-side sorting/paging, no grid engine or editing model. */
+export function createTable<Row extends object>(host: HTMLElement, initial: TableOptions<Row>, events: TableEvents<Row> = {}) {
+  let p = { ...initial }, disposed = false; const root = el('div', 'blu-table'), scroll = el('div', 'blu-table__scroll');
+  const table = el('table'), caption = el('caption'), head = el('thead'), body = el('tbody'), footer = el('div', 'blu-table__footer');
+  const status = el('span'), previous = el('button', 'blu-table-button', 'Previous'), next = el('button', 'blu-table-button', 'Next');
+  let headerSignature = '';
+  caption.id = uid(); scroll.tabIndex = 0; scroll.setAttribute('role', 'region'); scroll.setAttribute('aria-labelledby', caption.id);
+  previous.type = next.type = 'button'; status.setAttribute('role', 'status'); footer.append(status, previous, next); table.append(caption, head, body); scroll.append(table); root.append(scroll, footer); host.append(root);
+  function update(patch: Partial<TableOptions<Row>>) {
+    if (disposed) throw Error('Component is destroyed.'); p = { ...p, ...patch };
+    if (!p.Columns.length) throw Error('Table needs at least one column.');
+    if (new Set(p.Columns.map(c => c.Key)).size !== p.Columns.length) throw Error('Table column keys must be unique.');
+    root.className = 'blu-table' + (p.ExtendedClass ? ' ' + p.ExtendedClass : ''); root.dataset.density = p.Density || 'Comfortable'; root.dataset.striped = String(!!p.Striped);
+    table.setAttribute('aria-busy', String(!!p.Loading)); caption.textContent = p.Caption;
+    const focused = document.activeElement instanceof HTMLElement && root.contains(document.activeElement) ? document.activeElement.dataset.focusKey : undefined;
+    const focusedPagination = document.activeElement === next ? next : document.activeElement === previous ? previous : undefined;
+    const nextHeaderSignature = JSON.stringify([p.Columns.map(c => [c.Key, c.Header, !!c.Sortable, c.Align || 'Left']), !!p.Actions?.length]);
+    // Retain sortable header controls during sorting, paging and row updates.
+    // VoiceOver can activate a header without moving DOM keyboard focus to it.
+    if (nextHeaderSignature !== headerSignature) {
+      headerSignature = nextHeaderSignature;
+      head.replaceChildren(); const tr = el('tr'); head.append(tr);
+      for (const column of p.Columns) {
+        const th = el('th'); th.scope = 'col'; th.style.textAlign = (column.Align || 'Left').toLowerCase();
+        if (column.Sortable) {
+          const button = el('button', 'blu-table__sort', column.Header); button.type = 'button'; button.dataset.focusKey = 'sort-' + column.Key;
+          const glyph = el('span'); glyph.setAttribute('aria-hidden', 'true'); button.append(glyph);
+          button.onclick = () => { const direction = p.SortKey === column.Key && p.SortDirection !== 'Descending' ? 'Descending' : 'Ascending'; update({ SortKey: column.Key, SortDirection: direction, Page: 1 } as Partial<TableOptions<Row>>); events.SortChanged?.(column.Key, direction); };
+          th.append(button);
+        } else th.textContent = column.Header; tr.append(th);
+      }
+      if (p.Actions?.length) { const th = el('th', '', 'Actions'); th.scope = 'col'; tr.append(th); }
+    }
+    p.Columns.forEach((column, index) => {
+      if (!column.Sortable) return;
+      const th = head.rows[0].cells[index];
+      th.setAttribute('aria-sort', p.SortKey === column.Key ? (p.SortDirection || 'Ascending').toLowerCase() : 'none');
+      th.querySelector('span')!.textContent = p.SortKey === column.Key ? (p.SortDirection === 'Descending' ? '↓' : '↑') : '↕';
+    });
+    const state = tableRows(p); p.Page = state.page; body.replaceChildren();
+    if (p.Loading || !state.rows.length) {
+      const row = el('tr'), cell = el('td', 'blu-table__empty', p.Loading ? 'Loading records…' : (p.EmptyMessage || 'No records yet.')); cell.colSpan = p.Columns.length + (p.Actions?.length ? 1 : 0); row.append(cell); body.append(row);
+    } else for (const [index, row] of state.rows.entries()) {
+      const rowEl = el('tr'); for (const column of p.Columns) {
+        const cell = el('td'); cell.style.textAlign = (column.Align || 'Left').toLowerCase();
+        cell.textContent = column.Format ? column.Format(row[column.Key], row) : String(row[column.Key] ?? '—'); rowEl.append(cell);
+      }
+      if (p.Actions?.length) { const cell = el('td'), actions = el('div', 'blu-table__actions');
+        for (const action of p.Actions) {
+          const button = el('button', 'blu-table-button', action.Label); button.type = 'button'; button.disabled = typeof action.Disabled === 'function' ? action.Disabled(row) : !!action.Disabled;
+          button.dataset.focusKey = 'row-' + String(p.RowKey ? row[p.RowKey] : index) + '-' + action.Key;
+          if (p.RowKey) button.setAttribute('aria-label', action.Label + ' ' + String(row[p.RowKey]));
+          button.onclick = () => events.RowAction?.(action.Key, row); actions.append(button);
+        } cell.append(actions); rowEl.append(cell);
+      } body.append(rowEl);
+    }
+    status.textContent = p.Loading ? 'Loading records…' : `${state.start}–${state.end} of ${state.total} records`;
+    previous.hidden = next.hidden = !p.PageSize; previous.disabled = !!p.Loading || state.page <= 1; next.disabled = !!p.Loading || state.page >= state.pages;
+    previous.onclick = () => { update({ Page: state.page - 1 } as Partial<TableOptions<Row>>); events.PageChanged?.(p.Page!); };
+    next.onclick = () => { update({ Page: state.page + 1 } as Partial<TableOptions<Row>>); events.PageChanged?.(p.Page!); };
+    if (focused) Array.from(root.querySelectorAll<HTMLElement>('[data-focus-key]')).find(node => node.dataset.focusKey === focused)?.focus();
+    // Safari restarts Tab navigation at the page top if the focused pagination
+    // button becomes disabled. Keep the user at the available adjacent control.
+    if (!p.Loading && p.PageSize) {
+      if (focusedPagination === next && next.disabled) (previous.disabled ? scroll : previous).focus();
+      else if (focusedPagination === previous && previous.disabled) (next.disabled ? scroll : next).focus();
+    }
+  }
+  try { update({}); } catch (error) { root.remove(); throw error; }
+  return { element: root, update, getState: () => ({ Page: p.Page || 1, SortKey: p.SortKey, SortDirection: p.SortDirection || 'Ascending' }), destroy() { if (disposed) return; disposed = true; root.remove(); } };
+}

package/src/form-layout/text.ts

@@ -0,0 +1,73 @@
+import { el, attr, frame, lifecycle, common, bound, imageUrl } from './shared.js';
+import type { Adornment, TextInputOptions, TextInputEvents, TextAreaOptions, FieldEvents, FieldComponent } from './types.js';
+
+export function createTextInput(host: HTMLElement, initial: TextInputOptions = {}, events: TextInputEvents = {}): FieldComponent<TextInputOptions, string> {
+  let p = { ...initial }, revealed = false;
+  const f = frame(host, p), shell = el('div', 'blu-text'), input = el('input', 'blu-text__input');
+  const leading = el('span', 'blu-text__adornment'), trailing = el('span', 'blu-text__adornment');
+  const clear = el('button', 'blu-text__action', '×'), reveal = el('button', 'blu-text__action', 'Show');
+  clear.type = reveal.type = 'button'; clear.setAttribute('aria-label', 'Clear ' + (p.Label || 'text'));
+  shell.append(leading, input, trailing, clear, reveal); f.body.append(shell);
+  const life = lifecycle(f.root, reset);
+  const adornmentKinds = new WeakMap<HTMLElement, Adornment['Kind']>();
+  function adorn(target: HTMLElement, value?: Adornment) {
+    // Keep an existing action alive while validation/state updates run. Replacing
+    // the focused button leaves VoiceOver pointing at a detached control.
+    if (adornmentKinds.get(target) !== value?.Kind) target.replaceChildren();
+    target.removeAttribute('role'); target.removeAttribute('aria-label'); target.removeAttribute('aria-hidden'); target.hidden = !value;
+    if (!value) { adornmentKinds.delete(target); return; }
+    adornmentKinds.set(target, value.Kind);
+    if (value.Kind === 'Image') { const img = target.querySelector('img') || el('img'); const src = imageUrl(value.Src); if (img.src !== src) img.src = src; img.alt = value.Alt; if (!img.parentNode) target.append(img); }
+    else if (value.Kind === 'Action') {
+      const button = target.querySelector('button') || el('button', 'blu-text__action'); button.type = 'button'; button.textContent = value.Text; button.setAttribute('aria-label', value.Label);
+      button.disabled = !!p.Disabled || !!p.ReadOnly; button.onclick = () => events.Action?.(value.Key, input.value); if (!button.parentNode) target.append(button);
+    } else { target.textContent = value.Text; if (value.Kind === 'Icon') { attr(target, 'role', value.Label ? 'img' : undefined); attr(target, 'aria-label', value.Label); attr(target, 'aria-hidden', value.Label ? undefined : 'true'); } }
+  }
+  function refreshActions() { clear.hidden = !p.Clearable || !input.value || !!p.ReadOnly; reveal.hidden = !p.RevealPassword || p.Type !== 'password'; }
+  function update(patch: Partial<TextInputOptions>) {
+    life.check(); p = { ...p, ...patch }; f.paint(p, [input]); common(input, p);
+    input.type = p.Type === 'password' && revealed ? 'text' : (p.Type || 'text');
+    if (input.value !== (p.Value || '')) input.value = p.Value || '';
+    input.placeholder = p.Placeholder || ''; attr(input, 'maxlength', p.MaxLength === undefined ? undefined : Math.max(0, Math.floor(p.MaxLength)));
+    attr(input, 'autocomplete', p.Autocomplete); adorn(leading, p.Leading); adorn(trailing, p.Trailing);
+    clear.disabled = reveal.disabled = !!p.Disabled; clear.setAttribute('aria-label', 'Clear ' + (p.Label || 'text'));
+    reveal.textContent = revealed ? 'Hide' : 'Show'; reveal.setAttribute('aria-label', revealed ? 'Hide password' : 'Show password');
+    reveal.setAttribute('aria-pressed', String(revealed)); refreshActions();
+  }
+  function changed() { p.Value = input.value; refreshActions(); events.Change?.(input.value); }
+  function reset() { revealed = false; update({ Value: initial.Value || '' }); }
+  input.addEventListener('input', changed, { signal: life.signal });
+  input.addEventListener('blur', () => events.Blur?.(), { signal: life.signal });
+  clear.addEventListener('click', () => { input.value = ''; changed(); input.focus(); }, { signal: life.signal });
+  reveal.addEventListener('click', () => { revealed = !revealed; update({}); input.focus(); }, { signal: life.signal });
+  update({});
+  return { element: f.root, control: input, update, reset, getValue: () => input.value, focus: () => input.focus(), validate: () => input.reportValidity(), destroy: life.destroy };
+}
+
+export function createTextArea(host: HTMLElement, initial: TextAreaOptions = {}, events: FieldEvents<string> = {}): FieldComponent<TextAreaOptions, string> {
+  let p = { ...initial };
+  const f = frame(host, p), input = el('textarea', 'blu-textarea'), count = el('div', 'blu-field__count');
+  count.id = f.id + '-count'; f.body.append(input, count); const life = lifecycle(f.root, reset);
+  function resize() {
+    count.hidden = !p.ShowCount; count.textContent = input.value.length + (p.MaxLength === undefined ? ' characters' : ' / ' + p.MaxLength);
+    input.style.maxHeight = p.AutoGrow ? bound(p.MaxHeight, 320, 80, 2000) + 'px' : '';
+    input.style.resize = p.AutoGrow ? 'none' : 'vertical';
+    input.style.height = ''; if (p.AutoGrow) input.style.height = Math.min(input.scrollHeight + 2, bound(p.MaxHeight, 320, 80, 2000)) + 'px';
+  }
+  function update(patch: Partial<TextAreaOptions>) {
+    life.check(); p = { ...p, ...patch }; f.paint(p, [input]); common(input, p);
+    input.rows = Math.floor(bound(p.Rows, 4, 1, 30)); input.placeholder = p.Placeholder || '';
+    attr(input, 'maxlength', p.MaxLength === undefined ? undefined : Math.max(0, Math.floor(p.MaxLength)));
+    if (input.value !== (p.Value || '')) input.value = p.Value || '';
+    if (p.ShowCount) attr(input, 'aria-describedby', [input.getAttribute('aria-describedby'), count.id].filter(Boolean).join(' '));
+    resize();
+  }
+  function reset() { update({ Value: initial.Value || '' }); }
+  input.addEventListener('input', () => { p.Value = input.value; resize(); events.Change?.(input.value); }, { signal: life.signal });
+  input.addEventListener('blur', () => events.Blur?.(), { signal: life.signal });
+  let lastWidth = 0;
+  // Observe the host width only; height changes from auto-grow must not feed back.
+  const widthObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(entries => { const w = entries[0].contentRect.width; if (w !== lastWidth) { lastWidth = w; resize(); } }) : undefined;
+  widthObserver?.observe(f.root); update({});
+  return { element: f.root, control: input, update, reset, getValue: () => input.value, focus: () => input.focus(), validate: () => input.reportValidity(), destroy() { widthObserver?.disconnect(); life.destroy(); } };
+}

package/src/form-layout/types.ts

@@ -0,0 +1,59 @@
+/** Local Community additions. Not present in the published 1.0.1 package. */
+export type FieldSize = 'Small' | 'Medium' | 'Large';
+export interface FieldOptions {
+  Id?: string; Name?: string; Label?: string; Description?: string; Error?: string;
+  Required?: boolean; Disabled?: boolean; ReadOnly?: boolean; Size?: FieldSize;
+  ExtendedClass?: string;
+}
+export interface FieldEvents<T> { Change?: (value: T) => void; Blur?: () => void; }
+export interface FieldComponent<P, T> {
+  element: HTMLElement; control: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement;
+  update(patch: Partial<P>): void; getValue(): T; reset(): void; focus(): void;
+  validate(): boolean; destroy(): void;
+}
+export type Adornment =
+  | { Kind: 'Text'; Text: string }
+  | { Kind: 'Icon'; Text: string; Label?: string }
+  | { Kind: 'Image'; Src: string; Alt: string }
+  | { Kind: 'Action'; Text: string; Label: string; Key: string };
+export interface TextInputOptions extends FieldOptions {
+  Value?: string; Type?: 'text' | 'email' | 'password' | 'search' | 'tel' | 'url';
+  Placeholder?: string; MaxLength?: number; Autocomplete?: string;
+  Leading?: Adornment; Trailing?: Adornment; Clearable?: boolean; RevealPassword?: boolean;
+}
+export interface TextInputEvents extends FieldEvents<string> { Action?: (key: string, value: string) => void; }
+export interface TextAreaOptions extends FieldOptions {
+  Value?: string; Placeholder?: string; Rows?: number; MaxLength?: number;
+  AutoGrow?: boolean; MaxHeight?: number; ShowCount?: boolean;
+}
+export interface CheckboxOptions extends FieldOptions { Checked?: boolean; Indeterminate?: boolean; Value?: string; }
+export interface SwitchOptions extends FieldOptions { Checked?: boolean; OnText?: string; OffText?: string; }
+export interface RadioButtonOptions extends FieldOptions { Checked?: boolean; Value: string; }
+export interface Choice { Value: string; Label: string; Description?: string; Disabled?: boolean; }
+export interface RadioGroupOptions extends FieldOptions { Value?: string; Options: Choice[]; Direction?: 'Horizontal' | 'Vertical'; }
+export interface SelectOptions extends FieldOptions { Value?: string; Options: Choice[]; Placeholder?: string; Clearable?: boolean; Searchable?: boolean; }
+export interface FormFieldOptions extends FieldOptions { Control?: HTMLElement; }
+export interface ColumnsOptions {
+  Ratio?: 'Equal' | 'OneThirdTwoThirds' | 'TwoThirdsOneThird' | 'OneQuarterThreeQuarters' | 'ThreeQuartersOneQuarter' | 'WideCenter';
+  /** Match column heights within a row and stretch a single content wrapper. Stacked rows keep natural height. */
+  EqualHeight?: boolean;
+  Gap?: number; Align?: 'Start' | 'Center' | 'End' | 'Stretch';
+  StackAt?: 'Small' | 'Medium' | 'Large'; ExtendedClass?: string;
+}
+export interface ColumnsComponent { element: HTMLElement; columns: HTMLElement[]; update(patch: Partial<ColumnsOptions>): void; destroy(): void; }
+export interface TableColumn<Row extends object> {
+  Key: Extract<keyof Row, string>; Header: string; Sortable?: boolean; Align?: 'Left' | 'Center' | 'Right';
+  Format?: (value: Row[Extract<keyof Row, string>], row: Row) => string;
+}
+export interface TableAction<Row> { Key: string; Label: string; Disabled?: boolean | ((row: Row) => boolean); }
+export interface TableOptions<Row extends object> {
+  Columns: TableColumn<Row>[]; Rows: Row[]; Caption: string; RowKey?: Extract<keyof Row, string>;
+  Actions?: TableAction<Row>[]; Loading?: boolean; EmptyMessage?: string;
+  PageSize?: number; Page?: number; SortKey?: Extract<keyof Row, string>; SortDirection?: 'Ascending' | 'Descending';
+  Density?: 'Compact' | 'Comfortable'; Striped?: boolean; ExtendedClass?: string;
+}
+export interface TableEvents<Row> {
+  RowAction?: (key: string, row: Row) => void;
+  SortChanged?: (key: Extract<keyof Row, string>, direction: 'Ascending' | 'Descending') => void;
+  PageChanged?: (page: number) => void;
+}

package/src/form-layout.ts

@@ -0,0 +1,12 @@
+export * from './checkbox.js';
+export * from './text-input.js';
+export * from './text-area.js';
+export * from './radio-button.js';
+export * from './radio-group.js';
+export * from './switch.js';
+export * from './select.js';
+export * from './form-field.js';
+export * from './columns2.js';
+export * from './columns3.js';
+export * from './columns4.js';
+export * from './table.js';

package/src/index.ts

@@ -54,3 +54,5 @@ export * from './font-provider.js';
 export * from './shape-mask.js';
 export * from './chip-group.js';
 export * from './grid-basic.js';
+
+export * from './form-layout.js';

package/src/inputs.ts

@@ -6,3 +6,11 @@ export * from './date-picker.js';
 export * from './time-picker.js';
 export * from './date-time-picker.js';
 export * from './date-range-picker.js';
+export * from './checkbox.js';
+export * from './text-input.js';
+export * from './text-area.js';
+export * from './radio-button.js';
+export * from './radio-group.js';
+export * from './switch.js';
+export * from './select.js';
+export * from './form-field.js';

package/src/layout.ts

@@ -6,3 +6,6 @@ export * from './splitter.js';
 export * from './app-layout.js';
 export * from './page-layout.js';
 export * from './shape-mask.js';
+export * from './columns2.js';
+export * from './columns3.js';
+export * from './columns4.js';

package/src/motion/action-feedback.ts

@@ -0,0 +1,38 @@
+import type { MotionController } from './controller.js';
+
+export interface ActionMessages { pending: string; success: string; error: string }
+export type ActionResult = 'success' | 'error' | 'busy' | 'cancelled';
+
+/** Feedback follows an actual action promise. No simulated success, timed reset,
+ * duplicated live region or overlapping action. The caller owns data and controls. */
+export function createActionFeedback(status: HTMLElement, motion: MotionController) {
+  const original = { role: status.getAttribute('role'), atomic: status.getAttribute('aria-atomic'), state: status.getAttribute('data-action-state') };
+  status.setAttribute('role', 'status'); status.setAttribute('aria-atomic', 'true');
+  let dead = false, pending = false;
+  const show = (text: string, state: string) => {
+    status.textContent = text; status.dataset.actionState = state;
+    void motion.play(status, 'fade', { duration: 350, easing: 'ease-out' });
+  };
+  return {
+    get pending() { return pending; },
+    async run(action: () => unknown | Promise<unknown>, messages: ActionMessages): Promise<ActionResult> {
+      if (dead) return 'cancelled';
+      if (pending) return 'busy';
+      pending = true; show(messages.pending, 'pending');
+      try {
+        await action();
+        if (dead) return 'cancelled';
+        show(messages.success, 'success'); return 'success';
+      } catch {
+        if (dead) return 'cancelled';
+        show(messages.error, 'error'); return 'error';
+      } finally { pending = false; }
+    },
+    destroy() {
+      if (dead) return; dead = true; motion.cancel(status);
+      for (const [key, value] of [['role', original.role], ['aria-atomic', original.atomic], ['data-action-state', original.state]]) {
+        if (value === null) status.removeAttribute(key!); else status.setAttribute(key!, value!);
+      }
+    },
+  };
+}