@apliteni/apliteni-ui 0.3.0 → 0.5.0

package/src/components/dropdown.js

@@ -0,0 +1,229 @@
+// Dropdown — the kit's one popover-list primitive. A trigger (label + optional
+// value + rotating chevron) opens a panel of item rows (label, optional
+// description, optional leading icon, optional trailing badge, selected +
+// disabled state). Two flavours share the same panel + the same open/close JS:
+//
+//   variant: 'select'  → role="listbox" / role="option", value shown in trigger
+//   variant: 'menu'    → role="menu"    / role="menuitem", action list
+//
+// "dropdown" (not "menu" or "select") is deliberate: `menu` implies actions
+// only and `select` implies a form control bound to a value — this factory is
+// the umbrella both of those are specialisations of, and it's the word the
+// issue and the topbar already use. The topbar's version switcher and account
+// menu are thin consumers of the SAME wiring (wireDropdown) so there is exactly
+// one open/close/click-outside/Esc/keyboard implementation in the kit.
+//
+//   container.innerHTML = dropdown({ label: 'version:', value: '…', items });
+//   wireDropdown(container);   // or let wireTopbar() do it (it calls this)
+import { esc, icon } from './index.js';
+
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// A trailing status badge. `badge` is a string ("live") or { text, tone }.
+function ddBadge(badge) {
+  if (!badge) return '';
+  const text = typeof badge === 'string' ? badge : badge.text;
+  let tone = typeof badge === 'string' ? '' : (badge.tone || '');
+  if (!tone) tone = /^live$/i.test(text) ? 'live' : 'neutral';
+  return `<span class="${cx('ui-dropdown__badge', `is-${tone}`)}">${esc(text)}</span>`;
+}
+
+// One item row. `listbox` picks role=option (selectable) vs role=menuitem (action).
+function ddItem(it, listbox) {
+  if (it === '---' || it.separator) return '<div class="ui-dropdown__sep" role="separator"></div>';
+  const disabled = !!it.disabled;
+  const selected = !!it.selected;
+  const role = listbox ? 'option' : 'menuitem';
+  const asLink = !!it.href && !disabled && !listbox;
+  const tag = asLink ? 'a' : 'div';
+  const lead = it.icon ? `<span class="ui-dropdown__ic">${icon(it.icon)}</span>` : '';
+  const desc = it.description ? `<span class="ui-dropdown__desc">${esc(it.description)}</span>` : '';
+  const main = `<span class="ui-dropdown__main"><span class="ui-dropdown__label">${esc(it.label)}</span>${desc}</span>`;
+  const badge = ddBadge(it.badge);
+  const tick = listbox ? `<span class="ui-dropdown__tick" aria-hidden="true">${icon('check')}</span>` : '';
+  const attrs = [
+    `class="${cx('ui-dropdown__item', selected && 'is-selected', disabled && 'is-disabled', it.danger && 'is-danger')}"`,
+    'data-dd-item',
+    `role="${role}"`,
+    'tabindex="-1"',
+    it.value != null ? `data-value="${esc(it.value)}"` : '',
+    listbox ? `aria-selected="${selected ? 'true' : 'false'}"` : '',
+    disabled ? 'aria-disabled="true"' : '',
+    asLink ? `href="${esc(it.href)}"` : '',
+    asLink && it.target ? `target="${esc(it.target)}"` : '',
+  ].filter(Boolean).join(' ');
+  return `<${tag} ${attrs}>${lead}${main}${badge}${tick}</${tag}>`;
+}
+
+// Render a flat item list or grouped sections ([{ label, items }]).
+function ddBody({ items, sections }, listbox) {
+  if (sections && sections.length) {
+    return sections.map((s) => {
+      const head = s.label ? `<div class="ui-dropdown__group" role="presentation">${esc(s.label)}</div>` : '';
+      return `<div class="ui-dropdown__section" role="group"${s.label ? ` aria-label="${esc(s.label)}"` : ''}>${head}${(s.items || []).map((it) => ddItem(it, listbox)).join('')}</div>`;
+    }).join('');
+  }
+  return (items || []).map((it) => ddItem(it, listbox)).join('');
+}
+
+// The public factory. Returns an HTML string; wire it with wireDropdown().
+//   label       muted prefix in the trigger (e.g. "version:")
+//   value       current value shown in the trigger (single-select)
+//   placeholder shown when there's no value
+//   variant     'select' (listbox) | 'menu' (default inferred from items)
+//   items       [{ label, value?, description?, icon?, badge?, selected?, disabled?, href?, danger? }]
+//   sections    [{ label, items }] — grouped alternative to items
+//   header/footer  raw HTML blocks pinned top/bottom of the panel
+//   align       'start' (default) | 'end'  — which edge the panel hugs
+//   scroll      true | maxHeight px — cap panel height and scroll
+//   open        render already-open (handy for screenshots)
+//   ariaLabel   accessible name for the panel (and trigger, if no visible text)
+export function dropdown({
+  label, value, placeholder = 'Select…', variant, items, sections,
+  header = '', footer = '', triggerContent, triggerClass = '', chevron = true,
+  align = 'start', scroll = false, open = false, ariaLabel, id, panelClass = '',
+} = {}) {
+  const flat = sections ? sections.flatMap((s) => s.items || []) : (items || []);
+  const isSelect = variant === 'select' || (variant == null && flat.some((it) => it && (it.selected || it.value != null)));
+  const listRole = isSelect ? 'listbox' : 'menu';
+  const cur = value != null ? value : (isSelect ? (flat.find((it) => it && it.selected)?.label) : null);
+
+  const trig = triggerContent != null
+    ? triggerContent
+    : `${label ? `<span class="ui-dropdown__pre">${esc(label)}</span>` : ''}` +
+      `<span class="ui-dropdown__value">${esc(cur != null ? cur : placeholder)}</span>`;
+  const triggerAttrs = [
+    `class="${cx('ui-dropdown__trigger', triggerClass)}"`,
+    'type="button"',
+    'data-dropdown-trigger',
+    `aria-haspopup="${listRole}"`,
+    `aria-expanded="${open ? 'true' : 'false'}"`,
+    ariaLabel && triggerContent != null ? `aria-label="${esc(ariaLabel)}"` : '',
+  ].filter(Boolean).join(' ');
+
+  const panelAttrs = [
+    `class="${cx('ui-dropdown__panel', align === 'end' && 'is-end', scroll && 'is-scroll', panelClass)}"`,
+    'data-dropdown-panel',
+    `role="${listRole}"`,
+    ariaLabel ? `aria-label="${esc(ariaLabel)}"` : '',
+    scroll && scroll !== true ? `style="max-height:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '',
+  ].filter(Boolean).join(' ');
+
+  return `<div class="${cx('ui-dropdown', open && 'open')}" data-dropdown${isSelect ? ' data-dropdown-select' : ''}${id ? ` id="${esc(id)}"` : ''}>` +
+    `<button ${triggerAttrs}>${trig}${chevron ? '<span class="ui-dropdown__chevron" aria-hidden="true"></span>' : ''}</button>` +
+    `<div ${panelAttrs}>${header}${ddBody({ items, sections }, isSelect)}${footer}</div>` +
+    `</div>`;
+}
+
+// ---- Shared behaviour ----------------------------------------------------
+// One implementation for every dropdown in the kit — the generic component AND
+// the topbar's version switcher / account menu (they emit the same data hooks:
+// [data-dropdown] > [data-dropdown-trigger] + [data-dropdown-panel], toggling
+// `.open` on the container so each keeps its own visual CSS).
+//
+// Per-instance trigger + keyboard handlers are attached once (guarded by a flag
+// on the element). Document-level click-outside + Esc are attached once per
+// document. Safe to call repeatedly (e.g. Storybook re-renders).
+let _ddGlobalWired = false;
+
+function ddItemsOf(dd) {
+  const panel = dd.querySelector('[data-dropdown-panel]');
+  if (!panel) return [];
+  return Array.from(panel.querySelectorAll('[data-dd-item]'))
+    .filter((el) => el.getAttribute('aria-disabled') !== 'true');
+}
+
+function closeDropdown(dd) {
+  if (!dd.classList.contains('open')) return;
+  dd.classList.remove('open');
+  dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'false');
+}
+
+function closeAllDropdowns(except) {
+  document.querySelectorAll('[data-dropdown].open').forEach((dd) => { if (dd !== except) closeDropdown(dd); });
+}
+
+function openDropdown(dd, focusIdx) {
+  closeAllDropdowns(dd);
+  dd.classList.add('open');
+  dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'true');
+  if (focusIdx != null) {
+    const items = ddItemsOf(dd);
+    const sel = items.findIndex((el) => el.getAttribute('aria-selected') === 'true');
+    (items[focusIdx === 'selected' && sel >= 0 ? sel : (focusIdx === 'selected' ? 0 : focusIdx)] || items[0])?.focus();
+  }
+}
+
+// Single-select: reflect the picked option into aria-selected + the trigger value.
+function selectOption(dd, item) {
+  if (!dd.hasAttribute('data-dropdown-select')) return;
+  ddItemsOf(dd).forEach((el) => el.setAttribute('aria-selected', el === item ? 'true' : 'false'));
+  dd.querySelectorAll('[data-dd-item].is-selected').forEach((el) => el.classList.remove('is-selected'));
+  item.classList.add('is-selected');
+  const valueEl = dd.querySelector('[data-dropdown-trigger] .ui-dropdown__value');
+  const label = item.querySelector('.ui-dropdown__label');
+  if (valueEl && label) valueEl.textContent = label.textContent;
+}
+
+export function wireDropdown(root = document) {
+  const scope = root === document ? document : root;
+  scope.querySelectorAll('[data-dropdown]').forEach((dd) => {
+    if (dd.__ddWired) return;
+    dd.__ddWired = true;
+    const trigger = dd.querySelector('[data-dropdown-trigger]');
+    const panel = dd.querySelector('[data-dropdown-panel]');
+    if (!trigger) return;
+
+    trigger.addEventListener('click', (e) => {
+      e.stopPropagation();
+      if (dd.classList.contains('open')) closeDropdown(dd);
+      else openDropdown(dd);
+    });
+
+    if (panel) {
+      // Clicks inside the panel shouldn't reach the document close handler;
+      // activating an item selects (single-select) + closes.
+      panel.addEventListener('click', (e) => {
+        e.stopPropagation();
+        const item = e.target.closest('[data-dd-item]');
+        if (!item || item.getAttribute('aria-disabled') === 'true') return;
+        selectOption(dd, item);
+        closeDropdown(dd);
+        trigger.focus();
+      });
+    }
+
+    dd.addEventListener('keydown', (e) => {
+      const open = dd.classList.contains('open');
+      const onTrigger = e.target === trigger;
+      if ((e.key === 'ArrowDown' || e.key === 'ArrowUp') && (onTrigger || open)) {
+        e.preventDefault();
+        if (!open) return openDropdown(dd, e.key === 'ArrowDown' ? 0 : 'selected');
+        const items = ddItemsOf(dd);
+        const i = items.indexOf(document.activeElement);
+        const next = e.key === 'ArrowDown' ? (i + 1) % items.length : (i - 1 + items.length) % items.length;
+        items[next < 0 ? 0 : next]?.focus();
+      } else if (e.key === 'Home' && open) {
+        e.preventDefault(); ddItemsOf(dd)[0]?.focus();
+      } else if (e.key === 'End' && open) {
+        e.preventDefault(); const it = ddItemsOf(dd); it[it.length - 1]?.focus();
+      } else if ((e.key === 'Enter' || e.key === ' ') && open && e.target.matches('[data-dd-item]')) {
+        e.preventDefault(); e.target.click();
+      } else if (e.key === 'Escape' && open) {
+        e.preventDefault(); e.stopPropagation(); closeDropdown(dd); trigger.focus();
+      } else if (e.key === 'Tab' && open) {
+        closeDropdown(dd);
+      }
+    });
+  });
+
+  if (!_ddGlobalWired) {
+    _ddGlobalWired = true;
+    document.addEventListener('click', () => closeAllDropdowns());
+    document.addEventListener('keydown', (e) => {
+      if (e.key !== 'Escape') return;
+      const open = document.querySelector('[data-dropdown].open');
+      if (open) { closeDropdown(open); open.querySelector('[data-dropdown-trigger]')?.focus(); }
+    });
+  }
+}

package/src/components/feedback.js

@@ -23,6 +23,12 @@ export function feedbackWidget({
   doneTitle = 'Feedback sent. Thank you!',
   doneBody = 'Thanks — your note is on its way.',
 } = {}) {
+  // The composer's Cancel/Send/Close use .ui-fbbtn, NOT the kit's button() — an
+  // intentional exception. They're internal to this self-contained widget and
+  // carry composer-scoped treatment button() doesn't model: a tighter footer
+  // size, the inline send-spinner, and a disabled-until-valid state wired by
+  // data-attributes. Promoting them to .ui-btn would regress the widget's look
+  // for no consumer gain, since the app never renders these buttons directly.
   return `
 <div class="ui-fbpill" data-fb-pill>${IC_MSG}${esc(label)}</div>
 <div class="ui-fbscrim" data-fb-scrim></div>

package/src/components/footer.js

@@ -0,0 +1,95 @@
+// Footer factory — the canonical site/app footer as an HTML string, matching the
+// topbar idiom so any server-render consumer adopts it with no framework.
+// Composes a brand lockup, grouped link columns, a legal/copyright row, optional
+// social icons and an optional theme/accent switcher slot. Three variants:
+//   full — multi-column marketing footer (brand + columns + legal bar)
+//   slim — a single legal/copyright row
+//   app  — compact, in-product (tight padding, surface background)
+import { brand as brandLockup } from '../assets/brand.js';
+import { esc } from './index.js';
+
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// Minimal brand-glyph set for the optional social row. Feather-ish where generic,
+// simplified brand marks otherwise. Kept local so the footer is self-contained
+// (the shared icon set is line-only and has no brand glyphs).
+const SOCIAL = {
+  github: '<path d="M12 2a10 10 0 0 0-3.16 19.49c.5.09.68-.22.68-.48v-1.7c-2.78.6-3.37-1.34-3.37-1.34-.45-1.16-1.11-1.47-1.11-1.47-.9-.62.07-.6.07-.6 1 .07 1.53 1.03 1.53 1.03.9 1.53 2.34 1.09 2.91.83.09-.65.35-1.09.63-1.34-2.22-.25-4.55-1.11-4.55-4.94 0-1.09.39-1.98 1.03-2.68-.1-.25-.45-1.27.1-2.64 0 0 .84-.27 2.75 1.02a9.5 9.5 0 0 1 5 0c1.91-1.29 2.75-1.02 2.75-1.02.55 1.37.2 2.39.1 2.64.64.7 1.03 1.59 1.03 2.68 0 3.84-2.34 4.68-4.57 4.93.36.31.68.92.68 1.85v2.74c0 .27.18.58.69.48A10 10 0 0 0 12 2z"/>',
+  x: '<path d="M4 3h4.5l4 5.5L17.5 3H21l-6.5 8.5L21 21h-4.5l-4.3-5.9L7 21H3.5l6.8-8.9z"/>',
+  linkedin: '<rect x="3" y="3" width="18" height="18" rx="2"/><path d="M8 10v6M8 7v.01M12 16v-3a2 2 0 0 1 4 0v3" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>',
+  mail: '<rect x="3" y="5" width="18" height="14" rx="2" fill="none" stroke="currentColor" stroke-width="1.7"/><path d="m3 7 9 6 9-6" fill="none" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>',
+};
+
+function socialLink({ label, href = '#', icon: ic = 'github' } = {}) {
+  const glyph = SOCIAL[ic] || SOCIAL.github;
+  const fill = ic === 'github' || ic === 'x' ? 'currentColor' : 'none';
+  return `<a class="ui-footer__social" href="${href}" aria-label="${esc(label || ic)}">` +
+    `<svg viewBox="0 0 24 24" fill="${fill}" aria-hidden="true">${glyph}</svg></a>`;
+}
+
+function linkList(links = []) {
+  return `<ul class="ui-footer__links">${links.map(({ label, href = '#', target }) =>
+    `<li><a href="${href}"${target ? ` target="${target}" rel="noreferrer"` : ''}>${esc(label)}</a></li>`).join('')}</ul>`;
+}
+
+function column({ title, links = [] } = {}) {
+  return `<div class="ui-footer__col">` +
+    (title ? `<h4 class="ui-footer__col-title">${esc(title)}</h4>` : '') +
+    linkList(links) + `</div>`;
+}
+
+// Inline legal row (label + legal links + switcher slot). Shared by every variant.
+function legalBar({ legal, legalLinks = [], switcher = '' } = {}) {
+  const links = legalLinks.length
+    ? `<nav class="ui-footer__legal-links" aria-label="Legal">` +
+      legalLinks.map(({ label, href = '#' }) => `<a href="${href}">${esc(label)}</a>`).join('') + `</nav>`
+    : '';
+  const sw = switcher ? `<div class="ui-footer__switcher">${switcher}</div>` : '';
+  return `<div class="ui-footer__bar">` +
+    `<span class="ui-footer__legal">${esc(legal)}</span>` +
+    `${links}${sw}</div>`;
+}
+
+// Full footer. Pass which pieces to include; everything but `variant` is optional.
+//   brand      — lockup options object ({ word, href }) or false to hide it
+//   tagline    — short line under the brand (full variant only)
+//   columns    — [{ title, links: [{ label, href, target }] }]
+//   social     — [{ label, href, icon }]  (icon: github|x|linkedin|mail)
+//   legal      — copyright text (defaults to "© <year> Apliteni")
+//   legalLinks — [{ label, href }] inline row links
+//   switcher   — trusted HTML slot (e.g. accentPicker()+themeToggle()), or ''
+export function footer({
+  variant = 'full',
+  brand = { word: 'Strategy' },
+  tagline = '',
+  columns = [],
+  social = [],
+  legal = `© ${new Date().getFullYear()} Apliteni`,
+  legalLinks = [],
+  switcher = '',
+} = {}) {
+  const cls = cx('ui-footer', `ui-footer--${variant}`);
+
+  // slim + app: a single legal row, no brand block or columns.
+  if (variant === 'slim' || variant === 'app') {
+    return `<footer class="${cls}" role="contentinfo"><div class="ui-footer__in">` +
+      legalBar({ legal, legalLinks, switcher }) +
+      `</div></footer>`;
+  }
+
+  // full: brand block + link columns on top, legal bar below a divider.
+  const socialRow = social.length
+    ? `<div class="ui-footer__socials">${social.map(socialLink).join('')}</div>` : '';
+  const brandBlock = brand !== false
+    ? `<div class="ui-footer__brand">${brandLockup(brand)}` +
+      (tagline ? `<p class="ui-footer__tagline">${esc(tagline)}</p>` : '') +
+      socialRow + `</div>`
+    : '';
+  const nav = columns.length
+    ? `<nav class="ui-footer__nav" aria-label="Footer">${columns.map(column).join('')}</nav>` : '';
+
+  return `<footer class="${cls}" role="contentinfo"><div class="ui-footer__in">` +
+    `<div class="ui-footer__top">${brandBlock}${nav}</div>` +
+    legalBar({ legal, legalLinks, switcher }) +
+    `</div></footer>`;
+}

package/src/components/index.js

@@ -1,13 +1,18 @@
 // apliteni-ui component factories — each returns an HTML string, matching the
 // viz/ server-render idiom so the portal can adopt them with no framework.
 import { icon } from '../assets/icons.js';
+import { illo } from '../assets/illustrations.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
 export const esc = (s) => String(s == null ? '' : s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
 
 // ---- Button --------------------------------------------------------------
+// `iconSvg` is a raw leading-icon SVG string (trusted markup, not escaped) for
+// branded glyphs the kit's icon set doesn't own — e.g. a Google "G". It takes
+// the leading slot; `icon` is the named-icon shorthand for kit glyphs. This is
+// what lets third-party buttons go through button() instead of hand-rolled markup.
 export function button({
-  label = 'Button', variant = 'secondary', size = 'md', icon: ic, iconRight,
+  label = 'Button', variant = 'secondary', size = 'md', icon: ic, iconSvg, iconRight,
   block = false, disabled = false, busy = false, type = 'button', href, iconOnly = false,
 } = {}) {
   const cls = cx(
@@ -18,7 +23,8 @@ export function button({
     iconOnly && 'ui-btn--icon',
   );
   const bars = busy ? '<span class="ui-btn__bars"><i></i><i></i></span>' : '';
-  const inner = `${ic ? icon(ic) : ''}${iconOnly ? '' : `<span>${esc(label)}</span>`}${iconRight ? icon(iconRight) : ''}${bars}`;
+  const lead = iconSvg || (ic ? icon(ic) : '');
+  const inner = `${lead}${iconOnly ? '' : `<span>${esc(label)}</span>`}${iconRight ? icon(iconRight) : ''}${bars}`;
   // busy ⇒ disabled (not clickable while it works)
   const attrs = `class="${cls}"${disabled || busy ? ' disabled aria-disabled="true"' : ''}${busy ? ' aria-busy="true"' : ''}${iconOnly ? ` aria-label="${esc(label)}"` : ''}`;
   return href
@@ -48,6 +54,28 @@ export function card({ title, sub, body = '', variant, pad, icon: ic } = {}) {
   return `<div class="${cls}">${head}${body}</div>`;
 }
 
+// ---- Aurora — ambient warm backdrop --------------------------------------
+// Layered blurred glow "blobs" + optional paper grain. Colours default to the
+// accent glow tokens, so the field re-themes with the sub-theme. Drop it as the
+// first child of a positioned wrapper (or use fixed: true for full-bleed) and
+// give the real content a normal stacking context — it sits on top.
+const AURORA_PRESET = [
+  { tone: 'accent', x: '22%', y: '12%', size: '64%', delay: '0s' },
+  { tone: 'teal',   x: '84%', y: '24%', size: '56%', delay: '-9s' },
+  { tone: 'warm',   x: '54%', y: '92%', size: '70%', delay: '-17s' },
+];
+export function aurora({ blobs = AURORA_PRESET, grain = false, fixed = false, animated = true, className = '' } = {}) {
+  const items = blobs.map((b) => {
+    const tone = b.tone || 'accent';
+    const style = `--au-x:${b.x ?? '50%'};--au-y:${b.y ?? '50%'};--au-size:${b.size ?? '60%'}`
+      + (b.delay != null ? `;--au-delay:${b.delay}` : '');
+    return `<span class="ui-aurora__blob ui-aurora__blob--${tone}" style="${style}"></span>`;
+  }).join('');
+  const grainEl = grain ? '<span class="ui-aurora__grain"></span>' : '';
+  const cls = cx('ui-aurora', animated && 'ui-aurora--animated', fixed && 'ui-aurora--fixed', className);
+  return `<div class="${cls}" aria-hidden="true">${items}${grainEl}</div>`;
+}
+
 // ---- Segmented control ---------------------------------------------------
 export function segmented({ options = [], active = 0, size, block, name = 'seg' } = {}) {
   const cls = cx('ui-seg', size && `ui-seg--${size}`, block && 'ui-seg--block');
@@ -73,16 +101,57 @@ export function accentPicker({ active = 'default', options = ['default', 'phoeni
 }
 
 // ---- Field / input -------------------------------------------------------
-export function field({ label, hint, error, control } = {}) {
-  return `<div class="ui-field">${label ? `<label class="ui-field__label">${esc(label)}</label>` : ''}${control || ''}${error ? `<div class="ui-field__error">${icon('alert')}${esc(error)}</div>` : hint ? `<div class="ui-field__hint">${esc(hint)}</div>` : ''}</div>`;
+// Auto-generated ids let field() tie its <label for> to the control it wraps.
+// A module counter (never Date/random) keeps ids unique within a rendered page.
+let _uid = 0;
+const nextId = (p = 'ui') => `${p}-${++_uid}`;
+// Give the first form control in `html` an id (or reuse one it already carries)
+// so a <label> can point at it. Returns { html, id }; id is null if there's no
+// form element to name.
+function withControlId(html) {
+  const existing = html.match(/<(?:input|textarea|select)\b[^>]*\bid="([^"]+)"/);
+  if (existing) return { html, id: existing[1] };
+  let id = null;
+  const out = html.replace(/<(input|textarea|select)\b/, (m) => { id = nextId('field'); return `${m} id="${id}"`; });
+  return { html: out, id };
 }
-export function input({ type = 'text', placeholder = '', value = '', icon: ic, invalid, disabled, name } = {}) {
-  const el = `<input class="${cx('ui-input', invalid && 'is-invalid')}" type="${type}" placeholder="${esc(placeholder)}" value="${esc(value)}"${name ? ` name="${name}"` : ''}${disabled ? ' disabled' : ''}>`;
+
+export function field({ label, hint, error, control = '', id } = {}) {
+  let ctl = control;
+  let forId = id;
+  if (label && control) {
+    const r = withControlId(control);
+    ctl = r.html;
+    forId = id || r.id;
+  }
+  const lab = label
+    ? `<label class="ui-field__label"${forId ? ` for="${forId}"` : ''}>${esc(label)}</label>`
+    : '';
+  const foot = error
+    ? `<div class="ui-field__error">${icon('alert')}${esc(error)}</div>`
+    : hint ? `<div class="ui-field__hint">${esc(hint)}</div>` : '';
+  return `<div class="ui-field">${lab}${ctl}${foot}</div>`;
+}
+// `ariaLabel` gives a standalone control (no wrapping field) an accessible name.
+export function input({ type = 'text', placeholder = '', value = '', icon: ic, invalid, disabled, name, id, ariaLabel } = {}) {
+  const attrs = `${id ? ` id="${esc(id)}"` : ''}${name ? ` name="${name}"` : ''}${ariaLabel ? ` aria-label="${esc(ariaLabel)}"` : ''}${disabled ? ' disabled' : ''}`;
+  const el = `<input class="${cx('ui-input', invalid && 'is-invalid')}" type="${type}" placeholder="${esc(placeholder)}" value="${esc(value)}"${attrs}>`;
   if (!ic) return el;
   return `<div class="ui-input-group"><span class="ui-input-group__icon">${icon(ic)}</span>${el}</div>`;
 }
-export function textarea({ placeholder = '', value = '', rows = 4 } = {}) {
-  return `<textarea class="ui-textarea" rows="${rows}" placeholder="${esc(placeholder)}">${esc(value)}</textarea>`;
+export function textarea({ placeholder = '', value = '', rows = 4, name, id, ariaLabel } = {}) {
+  return `<textarea class="ui-textarea" rows="${rows}" placeholder="${esc(placeholder)}"${id ? ` id="${esc(id)}"` : ''}${name ? ` name="${name}"` : ''}${ariaLabel ? ` aria-label="${esc(ariaLabel)}"` : ''}>${esc(value)}</textarea>`;
+}
+// Native <select>. Pass a `label` via field() or an `ariaLabel` for a bare one —
+// a select with neither has no accessible name.
+export function select({ options = [], value, name, id, ariaLabel, disabled } = {}) {
+  const opts = options.map((o) => {
+    const label = typeof o === 'string' ? o : o.label;
+    const val = typeof o === 'string' ? o : (o.value ?? o.label);
+    const sel = value != null && String(val) === String(value);
+    return `<option value="${esc(val)}"${sel ? ' selected' : ''}>${esc(label)}</option>`;
+  }).join('');
+  return `<select class="ui-select"${id ? ` id="${esc(id)}"` : ''}${name ? ` name="${name}"` : ''}${ariaLabel ? ` aria-label="${esc(ariaLabel)}"` : ''}${disabled ? ' disabled' : ''}>${opts}</select>`;
 }
 export function checkbox({ label, checked, type = 'checkbox', name } = {}) {
   return `<label class="ui-check"><input type="${type}"${name ? ` name="${name}"` : ''}${checked ? ' checked' : ''}><span>${label}</span></label>`;
@@ -97,13 +166,48 @@ export function switchToggle({ checked = false, disabled = false, name, label =
 export function callout({ variant, icon: ic = 'info', body } = {}) {
   return `<div class="${cx('ui-callout', variant && `ui-callout--${variant}`)}"><span class="ui-callout__icon">${icon(ic)}</span><div>${body}</div></div>`;
 }
-export function toast({ variant = 'success', title, body, icon: ic = 'check' } = {}) {
-  return `<div class="${cx('ui-toast', `ui-toast--${variant}`)}"><span class="ui-toast__icon">${icon(ic)}</span><div class="ui-toast__body">${title ? `<div class="ui-toast__title">${esc(title)}</div>` : ''}${body ? `<div>${esc(body)}</div>` : ''}</div><button class="ui-toast__close" aria-label="Dismiss">${icon('x')}</button></div>`;
+// Default icon per status — overridable with `icon`.
+const TOAST_ICON = { success: 'check', danger: 'x', warn: 'alert', info: 'info', neutral: 'bolt' };
+// A toast carries a status (colour) and a style (surface). Everything visual is
+// token-driven: the status modifier sets --toast-accent/-glow/-on, the style
+// modifier consumes them. `action` adds a trailing button ("Undo"/"Retry"),
+// `timer` adds an auto-dismiss progress bar (true → default 5s, or a number of
+// seconds), `compact` drops the body for a single-line toast.
+export function toast({
+  variant = 'success', style = 'soft', title, body, icon: ic,
+  action, timer = false, compact = false, dismissible = true,
+} = {}) {
+  const cls = cx('ui-toast', `ui-toast--${variant}`, `ui-toast--${style}`, compact && 'ui-toast--compact');
+  const actLabel = typeof action === 'string' ? action : action && action.label;
+  const actBtn = actLabel ? `<button class="ui-toast__action" type="button">${esc(actLabel)}</button>` : '';
+  const closeBtn = dismissible ? `<button class="ui-toast__close" aria-label="Dismiss">${icon('x')}</button>` : '';
+  const bodyHtml = compact || !body ? '' : `<div class="ui-toast__text">${esc(body)}</div>`;
+  const dur = typeof timer === 'number' ? ` style="--toast-dur:${timer}s"` : '';
+  const timerBar = timer ? '<span class="ui-toast__timer" data-toast-timer></span>' : '';
+  return `<div class="${cls}" role="status" aria-live="polite"${dur}>`
+    + `<span class="ui-toast__icon">${icon(ic || TOAST_ICON[variant] || 'info')}</span>`
+    + `<div class="ui-toast__body">${title ? `<div class="ui-toast__title">${esc(title)}</div>` : ''}${bodyHtml}</div>`
+    + `${actBtn}${closeBtn}${timerBar}</div>`;
 }
 export function successPanel({ title = 'Done', sub = '' } = {}) {
   return `<div class="ui-success"><div class="ui-success__check">${icon('check')}</div><div class="ui-success__title">${esc(title)}</div>${sub ? `<div class="ui-success__sub">${esc(sub)}</div>` : ''}</div>`;
 }
 
+// ---- Empty state ---------------------------------------------------------
+// The placeholder for an empty list/table/page. Pass `art` as an illustration
+// name (see illustrations.js) or raw <svg> markup; a legacy line `icon` name is
+// also accepted. `actions` is trusted button markup (e.g. button({…})).
+export function emptyState({ art, icon: ic, title, sub, actions } = {}) {
+  const artHtml = art
+    ? `<div class="ui-empty__art">${/<svg/.test(art) ? art : illo(art)}</div>`
+    : ic ? `<div class="ui-empty__icon">${icon(ic)}</div>` : '';
+  return `<div class="ui-empty">${artHtml}`
+    + `${title ? `<div class="ui-empty__title">${esc(title)}</div>` : ''}`
+    + `${sub ? `<div class="ui-empty__sub">${esc(sub)}</div>` : ''}`
+    + `${actions ? `<div class="ui-empty__actions">${actions}</div>` : ''}`
+    + `</div>`;
+}
+
 // ---- Snippet -------------------------------------------------------------
 export function snippet({ label = 'shell', code = '', reveal = false, copy = true } = {}) {
   return `<div class="${cx('ui-snippet', reveal && 'ui-snippet--reveal')}"><div class="ui-snippet__bar"><span>${esc(label)}</span>${copy ? `<button class="ui-snippet__copy">${icon('copy')}Copy</button>` : ''}</div><pre>${code}</pre></div>`;
@@ -124,3 +228,4 @@ export const hlShell = (raw) =>
   );
 
 export { icon };
+export { illo, illoNames } from '../assets/illustrations.js';