@apliteni/apliteni-ui 0.4.0 → 0.6.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,28 +54,6 @@ 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');
@@ -160,13 +144,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>`;
@@ -187,3 +206,4 @@ export const hlShell = (raw) =>
   );
 
 export { icon };
+export { illo, illoNames } from '../assets/illustrations.js';

package/src/components/nav.js

@@ -0,0 +1,190 @@
+// Navigation — the kit's primary wayfinding primitives. One umbrella factory,
+// `nav({ variant })`, dispatches to three shapes that share tokens + classes but
+// almost no markup, so each is also exported directly for ergonomic use:
+//
+//   variant: 'sidebar'      → sidebarNav()   vertical rail: sections, icon+label
+//                             items, active state, collapsible groups, an
+//                             icon-only collapsed mode, optional per-item badge.
+//   variant: 'tabs'         → navTabs()      horizontal page tabs with an active
+//                             underline (default) or pill.
+//   variant: 'breadcrumbs'  → breadcrumbs()  the `Finance / Payouts` trail.
+//
+// Why an umbrella AND named exports (unlike dropdown, which is one factory): the
+// three variants don't share a body the way select/menu share a panel, so a
+// single options bag would mean wildly different fields per variant. The named
+// exports keep each call site honest; `nav()` stays the discoverable entry the
+// issue asks for and the one thing to import when the variant is data-driven.
+//
+// These are NAVIGATION controls (links between locations), not tab panels — so
+// tabs render as <nav> + <a aria-current="page">, not role="tablist" (that's
+// what segmented() is for). Only the collapsible sidebar groups need JS; wire
+// them once after mount with wireNav() (preview.js does this for Storybook).
+import { esc, icon } from './index.js';
+
+const cx = (...a) => a.filter(Boolean).join(' ');
+
+// Unique-per-render ids so a section heading can label its own list. Module
+// counter (never Date/random) — matches field()'s nextId() in index.js.
+let _uid = 0;
+const nextId = (p = 'nav') => `${p}-${++_uid}`;
+
+// A trailing counter/badge on a nav item. `badge` is a number, a string, or
+// { text, tone }. Tones map to the badge token set (accent | live | neutral…).
+function navBadge(badge) {
+  if (badge == null || badge === '') return '';
+  const text = typeof badge === 'object' ? badge.text : badge;
+  const tone = typeof badge === 'object' && badge.tone ? badge.tone : 'neutral';
+  return `<span class="${cx('ui-nav__badge', `is-${tone}`)}">${esc(text)}</span>`;
+}
+
+// One sidebar leaf: a link (or a plain, aria-disabled span). `collapsed` folds
+// the label into an aria-label + title so the icon stays named and hoverable.
+function sideLeaf(it, active, { collapsed, sub } = {}) {
+  const on = it.id != null && it.id === active;
+  const disabled = !!it.disabled;
+  const label = it.label || '';
+  const lead = it.icon ? `<span class="ui-nav__ic">${icon(it.icon)}</span>` : '';
+  const text = `<span class="ui-nav__label">${esc(label)}</span>`;
+  const badge = navBadge(it.badge);
+  const cls = cx('ui-nav__item', sub && 'ui-nav__item--sub', on && 'is-active', it.danger && 'is-danger', disabled && 'is-disabled');
+  const name = collapsed ? ` aria-label="${esc(label)}" title="${esc(label)}"` : '';
+  if (disabled) {
+    return `<li><span class="${cls}" aria-disabled="true"${name}>${lead}${text}${badge}</span></li>`;
+  }
+  const attrs = [
+    `class="${cls}"`,
+    `href="${esc(it.href || '#' + (it.id ?? ''))}"`,
+    it.target ? `target="${esc(it.target)}"` : '',
+    on ? 'aria-current="page"' : '',
+    name.trim(),
+  ].filter(Boolean).join(' ');
+  return `<li><a ${attrs}>${lead}${text}${badge}</a></li>`;
+}
+
+// A collapsible group: a toggle button (aria-expanded/-controls) over a nested
+// list. In collapsed (icon-only) mode groups don't expand, so we render the
+// group head as a plain, non-collapsing icon row.
+function sideGroup(it, active, { collapsed } = {}) {
+  const listId = nextId('nav-grp');
+  const childActive = (it.items || []).some((c) => c.id != null && c.id === active);
+  const open = collapsed ? false : (it.open != null ? !!it.open : childActive);
+  const lead = it.icon ? `<span class="ui-nav__ic">${icon(it.icon)}</span>` : '';
+  const label = it.label || '';
+  const text = `<span class="ui-nav__label">${esc(label)}</span>`;
+  const kids = (it.items || []).map((c) => sideLeaf(c, active, { collapsed, sub: true })).join('');
+  const name = collapsed ? ` aria-label="${esc(label)}" title="${esc(label)}"` : '';
+  const btn =
+    `<button type="button" class="${cx('ui-nav__item', 'ui-nav__toggle', childActive && 'is-current')}"` +
+    ` data-nav-toggle aria-expanded="${open ? 'true' : 'false'}" aria-controls="${listId}"${name}>` +
+    `${lead}${text}<span class="ui-nav__caret" aria-hidden="true"></span></button>`;
+  return `<li class="${cx('ui-nav__group', open && 'is-open')}">${btn}` +
+    `<ul class="ui-nav__sub" id="${listId}"${open ? '' : ' hidden'}>${kids}</ul></li>`;
+}
+
+function sideItem(it, active, opts) {
+  return (it.items && it.items.length) ? sideGroup(it, active, opts) : sideLeaf(it, active, opts);
+}
+
+// Sidebar nav. Pass `sections` ([{ label, items }]) or a flat `items` list.
+//   items/section items: { id, label, icon?, href?, target?, badge?, danger?,
+//                           disabled?, items?, open? }  (items ⇒ collapsible group)
+//   active     id of the current item (gets aria-current="page")
+//   collapsed  icon-only rail; labels fold into aria-label + title
+//   footer     trusted HTML pinned below a divider (e.g. a sign-out link)
+//   ariaLabel  accessible name for the <nav> landmark
+export function sidebarNav({
+  sections, items, active, collapsed = false, footer = '', ariaLabel = 'Sidebar', id,
+} = {}) {
+  const blocks = (sections && sections.length)
+    ? sections
+    : [{ items: items || [] }];
+  const body = blocks.map((sec) => {
+    const capId = sec.label ? nextId('nav-cap') : '';
+    const cap = sec.label
+      ? `<div class="ui-nav__cap" id="${capId}"${collapsed ? ' aria-hidden="true"' : ''}>${esc(sec.label)}</div>`
+      : '';
+    const list = `<ul class="ui-nav__list"${capId ? ` aria-labelledby="${capId}"` : ''}>` +
+      (sec.items || []).map((it) => sideItem(it, active, { collapsed })).join('') + `</ul>`;
+    return `<div class="ui-nav__section">${cap}${list}</div>`;
+  }).join('');
+  const foot = footer ? `<div class="ui-nav__foot">${footer}</div>` : '';
+  return `<nav class="${cx('ui-nav', 'ui-nav--side', collapsed && 'is-collapsed')}"` +
+    ` aria-label="${esc(ariaLabel)}"${id ? ` id="${esc(id)}"` : ''}>${body}${foot}</nav>`;
+}
+
+// Horizontal page tabs — links, not a tablist. `variant` picks the active
+// affordance: 'underline' (default) or 'pill'.
+//   items   { id, label, href?, target?, badge?, disabled? }
+//   active  id of the current tab (aria-current="page")
+export function navTabs({
+  items = [], active, variant = 'underline', ariaLabel = 'Tabs', id,
+} = {}) {
+  const tabs = items.map((it) => {
+    const on = it.id != null && it.id === active;
+    const badge = navBadge(it.badge);
+    const inner = `<span class="ui-nav__tab-label">${esc(it.label)}</span>${badge}`;
+    if (it.disabled) {
+      return `<span class="ui-nav__tab is-disabled" aria-disabled="true">${inner}</span>`;
+    }
+    const attrs = [
+      `class="${cx('ui-nav__tab', on && 'is-active')}"`,
+      `href="${esc(it.href || '#' + (it.id ?? ''))}"`,
+      it.target ? `target="${esc(it.target)}"` : '',
+      on ? 'aria-current="page"' : '',
+    ].filter(Boolean).join(' ');
+    return `<a ${attrs}>${inner}</a>`;
+  }).join('');
+  return `<nav class="${cx('ui-nav', 'ui-nav--tabs', `is-${variant}`)}"` +
+    ` aria-label="${esc(ariaLabel)}"${id ? ` id="${esc(id)}"` : ''}>${tabs}</nav>`;
+}
+
+// Breadcrumb trail. The last crumb is the current page (aria-current="page",
+// rendered as text). Earlier crumbs link when they carry an `href`.
+//   items   { label, href?, target?, icon? }
+export function breadcrumbs({ items = [], ariaLabel = 'Breadcrumb', id } = {}) {
+  const last = items.length - 1;
+  const crumbs = items.map((it, i) => {
+    const lead = it.icon ? `<span class="ui-nav__ic">${icon(it.icon)}</span>` : '';
+    const label = `<span class="ui-nav__crumb-label">${esc(it.label)}</span>`;
+    const inner = `${lead}${label}`;
+    const isLast = i === last;
+    const cell = (!isLast && it.href)
+      ? `<a class="ui-nav__crumb" href="${esc(it.href)}"${it.target ? ` target="${esc(it.target)}"` : ''}>${inner}</a>`
+      : `<span class="${cx('ui-nav__crumb', isLast && 'is-current')}"${isLast ? ' aria-current="page"' : ''}>${inner}</span>`;
+    return `<li class="ui-nav__crumb-item">${cell}</li>`;
+  }).join('');
+  return `<nav class="ui-nav ui-nav--crumbs" aria-label="${esc(ariaLabel)}"${id ? ` id="${esc(id)}"` : ''}>` +
+    `<ol class="ui-nav__crumbs">${crumbs}</ol></nav>`;
+}
+
+// Umbrella dispatcher — the one thing to import when the variant is data-driven.
+export function nav({ variant = 'sidebar', ...opts } = {}) {
+  if (variant === 'tabs') return navTabs(opts);
+  if (variant === 'breadcrumbs') return breadcrumbs(opts);
+  return sidebarNav(opts);
+}
+
+// ---- Behaviour -----------------------------------------------------------
+// Only the collapsible sidebar groups need JS: toggle a group's `.is-open` +
+// its button's aria-expanded, and show/hide the nested list. Idempotent and
+// event-delegated, so it's safe to call repeatedly (Storybook re-renders).
+let _navGlobalWired = false;
+
+function toggleGroup(btn) {
+  const li = btn.closest('.ui-nav__group');
+  const list = document.getElementById(btn.getAttribute('aria-controls'));
+  const open = btn.getAttribute('aria-expanded') === 'true';
+  btn.setAttribute('aria-expanded', open ? 'false' : 'true');
+  if (li) li.classList.toggle('is-open', !open);
+  if (list) { if (open) list.setAttribute('hidden', ''); else list.removeAttribute('hidden'); }
+}
+
+export function wireNav(root = document) {
+  // Per-collapsed-rail behaviour would go here; groups use one delegated handler.
+  if (_navGlobalWired) return;
+  _navGlobalWired = true;
+  document.addEventListener('click', (e) => {
+    const btn = e.target.closest && e.target.closest('[data-nav-toggle]');
+    if (btn) { e.preventDefault(); toggleGroup(btn); }
+  });
+}