@blukavantui/community 0.0.0-stage → 1.1.0

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/grid-basic.ts

@@ -0,0 +1,46 @@
+/** BluGrid Basic — a deliberately small, read-only Community adapter. */
+import {createGrid,themeQuartz,ClientSideRowModelModule,TextFilterModule,NumberFilterModule,DateFilterModule,RenderApiModule,PaginationModule,RowSelectionModule,ColumnAutoSizeModule,CellStyleModule,type ColDef,type GridApi} from 'ag-grid-community';
+import {normalizeOptions,formatValue,parseDate,type Row,type GridBasicOptions,type GridBasicEvents,type NormalizedOptions} from './grid-spec.js';
+export type {BasicColumn,ColumnType,Row,GridBasicOptions,GridBasicEvents} from './grid-spec.js';
+export interface GridBasic {
+ readonly element:HTMLElement;
+ /** Validated input update. The underlying grid API is intentionally private. */
+ update(patch:Partial<GridBasicOptions>):void;
+ clearSelection():void;
+ destroy():void;
+}
+const modules=[ClientSideRowModelModule,TextFilterModule,NumberFilterModule,DateFilterModule,RenderApiModule,PaginationModule,RowSelectionModule,ColumnAutoSizeModule,CellStyleModule];
+const theme=themeQuartz.withParams({accentColor:'var(--bluui-primary, #5144ed)',backgroundColor:'var(--bluui-surface, #fff)',foregroundColor:'var(--bluui-text, #182333)',borderColor:'var(--bluui-border, #dce3ed)',headerBackgroundColor:'var(--bluui-surface-muted, #f4f6fa)',headerTextColor:'var(--bluui-text-muted, #68758b)',rowHoverColor:'var(--bluui-surface-muted, #f4f6fa)',selectedRowBackgroundColor:'var(--bluui-primary-soft, #edeaff)',fontFamily:'var(--blu-font-family, system-ui)',fontSize:14,headerFontSize:12,headerFontWeight:600,rowHeight:44,headerHeight:44,wrapperBorderRadius:12,browserColorScheme:'inherit'});
+const copy=(r:Row|undefined)=>r?{...r}:null;
+function columns(p:NormalizedOptions):ColDef<Row>[] {
+ return p.Columns.map(c=>{const type=c.Type||'Text';const isDate=type==='Date'||type==='DateTime';return {
+  field:c.Field,colId:c.Field,headerName:c.Header??c.Field,minWidth:c.MinWidth||100,width:c.Width,flex:c.Width?undefined:1,
+  sortable:c.IsSortable!==false,filter:c.IsFilterable===false?false:(isDate?'agDateColumnFilter':type==='Number'||type==='Currency'?'agNumberColumnFilter':'agTextColumnFilter'),
+  editable:false,cellDataType:false,suppressMovable:true,lockPinned:true,
+  valueFormatter:({value})=>formatValue(value,type,p),
+  filterValueGetter:({data})=>isDate?parseDate(data?.[c.Field],type==='DateTime'):type==='Boolean'?formatValue(data?.[c.Field],type,p):data?.[c.Field],
+  filterParams:{maxNumConditions:1,...(isDate?{comparator:(local:Date,v:unknown)=>{if(!(v instanceof Date))return -1;const parts=new Intl.DateTimeFormat('en-CA',{timeZone:type==='Date'?'UTC':p.TimeZone,year:'numeric',month:'2-digit',day:'2-digit'}).formatToParts(v);const val=(k:string)=>Number(parts.find(x=>x.type===k)?.value);const t=new Date(val('year'),val('month')-1,val('day')).getTime();return Math.sign(t-local.getTime());}}:{})},
+  cellClass:type==='Number'||type==='Currency'?'blu-grid-basic__number':undefined,
+ };});
+}
+export function createGridBasic(host:HTMLElement,input:GridBasicOptions,events:GridBasicEvents={}):GridBasic {
+ let p=normalizeOptions(input),disposed=false,api:GridApi<Row>;
+ if(!host.isConnected)throw Error('Mount BluGrid Basic into a connected element.');
+ const root=document.createElement('div');host.append(root);
+ const appearance=()=>{root.className='blu-grid-basic'+(p.ExtendedClass?' '+p.ExtendedClass:'');root.style.height=p.Height;};appearance();
+ try { api=createGrid<Row>(root,{
+  theme,rowData:p.Rows,columnDefs:columns(p),getRowId:({data})=>String(data[p.RowKeyField]),
+  rowModelType:'clientSide',pagination:p.EnablePagination,paginationPageSize:p.PageSize,paginationPageSizeSelector:false,
+  rowSelection:p.EnableSelection?{mode:'singleRow',enableClickSelection:true,checkboxes:false}:undefined,
+  suppressMultiSort:true,suppressMovableColumns:true,animateRows:false,ensureDomOrder:true,
+  defaultColDef:{resizable:true,editable:false},enableCellTextSelection:true,
+  onGridReady:()=>events.Ready?.(),onRowClicked:e=>{if(e.data)events.RowClicked?.({...e.data});},
+  onSelectionChanged:e=>events.SelectionChanged?.(copy(e.api.getSelectedRows()[0])),
+ },{modules});api.setGridAriaProperty('label',p.AccessibleLabel);
+ }catch(error){root.remove();throw error;}
+ return {element:root,update(patch){if(disposed)throw Error('Grid is destroyed.');const next=normalizeOptions({...p,...patch});if(next.RowKeyField!==p.RowKeyField)throw Error('RowKeyField cannot change after initialization.');const changeColumns=JSON.stringify(next.Columns)!==JSON.stringify(p.Columns)||next.Locale!==p.Locale||next.Currency!==p.Currency||next.TimeZone!==p.TimeZone;
+  const selectionChanged=next.EnableSelection!==p.EnableSelection;p=next;appearance();
+  api.updateGridOptions({rowData:p.Rows,...(changeColumns?{columnDefs:columns(p)}:{}),pagination:p.EnablePagination,paginationPageSize:p.PageSize,...(selectionChanged?{rowSelection:p.EnableSelection?{mode:'singleRow' as const,enableClickSelection:true,checkboxes:false}:undefined}:{})});
+  if(selectionChanged&&!p.EnableSelection)api.deselectAll();api.setGridAriaProperty('label',p.AccessibleLabel);
+ },clearSelection(){if(!disposed)api.deselectAll();},destroy(){if(disposed)return;disposed=true;api.destroy();root.remove();}};
+}

package/src/grid-spec.ts

@@ -0,0 +1,93 @@
+/** Closed, read-only contract. No AG Grid options or engine API escape hatch. */
+export type Row = Record<string, string | number | boolean | null>;
+export type ColumnType = 'Text' | 'Number' | 'Currency' | 'Date' | 'DateTime' | 'Boolean';
+export interface BasicColumn {
+  Field: string;
+  Header?: string;
+  Type?: ColumnType;
+  Width?: number;
+  MinWidth?: number;
+  IsSortable?: boolean;
+  IsFilterable?: boolean;
+}
+export interface GridBasicOptions {
+  Columns: BasicColumn[];
+  Rows: Row[];
+  RowKeyField?: string;
+  Height?: string;
+  PageSize?: number;
+  EnablePagination?: boolean;
+  EnableSelection?: boolean;
+  Locale?: string;
+  Currency?: string;
+  TimeZone?: string;
+  AccessibleLabel?: string;
+  ExtendedClass?: string;
+}
+export interface GridBasicEvents {
+  Ready?: () => void;
+  RowClicked?: (row: Row) => void;
+  SelectionChanged?: (row: Row | null) => void;
+  Error?: (message: string) => void;
+}
+export type NormalizedOptions = Required<GridBasicOptions>;
+const blocked = new Set(['__proto__', 'prototype', 'constructor']);
+function record(value: unknown): value is Record<string,unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype,null].includes(Object.getPrototypeOf(value));
+}
+function fields(value: Record<string,unknown>, allowed: readonly string[], scope: string) {
+  for (const key of Object.keys(value)) if (!allowed.includes(key) || blocked.has(key)) throw Error(`${scope}: unsupported property ${key}.`);
+}
+function text(value: unknown, label: string, empty = false): asserts value is string {
+  if (typeof value !== 'string' || (!empty && !value.trim())) throw Error(`${label} must be text${empty?'':' and nonempty'}.`);
+}
+function boolean(value:unknown,label:string) { if(typeof value !== 'boolean') throw Error(`${label} must be Boolean.`); }
+const optionKeys = ['Columns','Rows','RowKeyField','Height','PageSize','EnablePagination','EnableSelection','Locale','Currency','TimeZone','AccessibleLabel','ExtendedClass'];
+const columnKeys = ['Field','Header','Type','Width','MinWidth','IsSortable','IsFilterable'];
+export function normalizeOptions(input:GridBasicOptions):NormalizedOptions {
+  if(!record(input)) throw Error('Grid options must be an object.');
+  fields(input,optionKeys,'Grid');
+  const p:NormalizedOptions = {RowKeyField:'Id',Height:'480px',PageSize:25,EnablePagination:true,EnableSelection:true,Locale:'en-US',Currency:'USD',TimeZone:'UTC',AccessibleLabel:'Data table',ExtendedClass:'',...input};
+  for(const key of ['RowKeyField','Height','Locale','Currency','TimeZone','AccessibleLabel'] as const)text(p[key],key);
+  text(p.ExtendedClass,'ExtendedClass',true);
+  if(blocked.has(p.RowKeyField))throw Error('Invalid RowKeyField.');
+  if(!/^\d+(\.\d+)?(px|rem|vh|dvh|%)$/.test(p.Height))throw Error('Height must be a nonnegative CSS length (px, rem, vh, dvh or %).');
+  if(!Number.isSafeInteger(p.PageSize)||p.PageSize<1||p.PageSize>10000)throw Error('PageSize must be an integer from 1 to 10000.');
+  boolean(p.EnablePagination,'EnablePagination');boolean(p.EnableSelection,'EnableSelection');
+  new Intl.NumberFormat(p.Locale,{style:'currency',currency:p.Currency});
+  new Intl.DateTimeFormat(p.Locale,{timeZone:p.TimeZone});
+  if(!Array.isArray(p.Columns)||!p.Columns.length)throw Error('Columns must contain at least one column.');
+  const seen=new Set<string>();
+  p.Columns=p.Columns.map(c=>{
+    if(!record(c))throw Error('Each column must be an object.');fields(c,columnKeys,'Column');text(c.Field,'Column.Field');
+    if(blocked.has(c.Field)||seen.has(c.Field))throw Error('Column fields must be unique and safe.');seen.add(c.Field);
+    if(c.Header!==undefined)text(c.Header,'Column.Header',true);
+    if(c.Type!==undefined&&!['Text','Number','Currency','Date','DateTime','Boolean'].includes(c.Type))throw Error('Invalid column Type.');
+    for(const k of ['Width','MinWidth'] as const)if(c[k]!==undefined&&(!Number.isFinite(c[k])||c[k]!<40||c[k]!>4000))throw Error(`${k} must be from 40 to 4000.`);
+    for(const k of ['IsSortable','IsFilterable'] as const)if(c[k]!==undefined)boolean(c[k],k);
+    return {...c};
+  });
+  if(!Array.isArray(p.Rows))throw Error('Rows must be a list.');
+  const ids=new Set<string>();
+  p.Rows=p.Rows.map(r=>{
+    if(!record(r))throw Error('Every row must be an object.');
+    for(const [k,v]of Object.entries(r))if(blocked.has(k)||!(v===null||typeof v==='string'||typeof v==='boolean'||(typeof v==='number'&&Number.isFinite(v))))throw Error(`Invalid value in row field ${k}.`);
+    const id=r[p.RowKeyField];if(!['string','number'].includes(typeof id)||String(id)===''||ids.has(String(id)))throw Error('Rows need unique, nonempty keys in RowKeyField.');ids.add(String(id));
+    return {...r};
+  });
+  return p;
+}
+/** Date-only values never shift across zones. Invalid values display as blank. */
+export function parseDate(value:unknown,instant=false):Date|null {
+  if(typeof value!=='string'||!value)return null;
+  if(!instant){if(!/^\d{4}-\d{2}-\d{2}$/.test(value))return null;const d=new Date(value+'T00:00:00Z');return Number.isFinite(d.getTime())&&d.toISOString().slice(0,10)===value?d:null;}
+  if(!/^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value))return null;
+  const d=new Date(value);return Number.isFinite(d.getTime())?d:null;
+}
+export function formatValue(value:unknown,type:ColumnType,p:NormalizedOptions):string {
+  if(value===null||value===undefined)return '';
+  if(type==='Boolean')return value===true?'Yes':value===false?'No':'';
+  if(type==='Number'||type==='Currency')return typeof value==='number'&&Number.isFinite(value)?new Intl.NumberFormat(p.Locale,type==='Currency'?{style:'currency',currency:p.Currency}:{}).format(value):'';
+  if(type==='Date'||type==='DateTime'){const d=parseDate(value,type==='DateTime');return d?new Intl.DateTimeFormat(p.Locale,{dateStyle:'medium',...(type==='DateTime'?{timeStyle:'short',timeZone:p.TimeZone}:{timeZone:'UTC'})}).format(d):'';}
+  return String(value);
+}

package/src/grid.ts

@@ -0,0 +1 @@
+export * from './grid-basic.js';

package/src/hero-section.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/hero-section.js';
+export type * from './types.js';

package/src/image-compare.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/image-compare.js';
+export type * from './types.js';

package/src/index.ts

@@ -0,0 +1,58 @@
+export * from './theme.js';
+export * from './button.js';
+export * from './badge.js';
+export * from './chip.js';
+export * from './card.js';
+export * from './breadcrumbs.js';
+export * from './page-header.js';
+export * from './sidebar.js';
+export * from './skeleton.js';
+export * from './tree-select.js';
+export * from './command-palette.js';
+export * from './upload-manager.js';
+export * from './splitter.js';
+export * from './tree-view.js';
+export * from './transfer-list.js';
+export * from './timeline.js';
+export * from './modal.js';
+export * from './drawer.js';
+export * from './notification.js';
+export * from './pagination.js';
+export * from './cascader.js';
+export * from './statistic.js';
+export * from './qr-code.js';
+export * from './tour.js';
+export * from './empty-state.js';
+export * from './descriptions.js';
+export * from './sparkline.js';
+export * from './app-layout.js';
+export * from './page-layout.js';
+export * from './dashboard-canvas.js';
+export * from './notification-center.js';
+export * from './dashboard-panel.js';
+export * from './video-player.js';
+export * from './video-lightbox.js';
+export * from './media-image.js';
+export * from './media-card.js';
+export * from './image-compare.js';
+export * from './text-highlight.js';
+export * from './content-carousel.js';
+export * from './profile-card.js';
+export * from './quote-card.js';
+export * from './collection-layout.js';
+export * from './hero-section.js';
+export * from './split-section.js';
+export * from './logo-cloud.js';
+export * from './chat.js';
+export * from './chat-widget.js';
+export * from './float-button.js';
+export * from './date-picker.js';
+export * from './time-picker.js';
+export * from './date-time-picker.js';
+export * from './date-range-picker.js';
+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';