@apliteni/apliteni-ui 0.23.1 → 0.23.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.23.1",
+  "version": "0.23.3",
   "workspaces": [
     "react"
   ],

package/src/components/confirm.js

@@ -3,18 +3,13 @@
 //   container.innerHTML = confirm({ title, body, confirmLabel, cancelLabel });
 //   wireConfirm(container);   // scrim/Esc/answers + focus trap
 //
-// A page trigger opens it by id:  <button data-confirm-open="ID">…</button>
-// (or call openConfirm(rootEl) directly). Pass `open: true` to render it already
-// open, or `specimen: true` for a picture of one on a documentation page.
+// A page trigger opens it by id: <button data-confirm-open="ID">. Answering is
+// the caller's job — a listener on [data-confirm-accept] is where the
+// destructive work goes — and focus opens on the SAFE answer, so a reader who
+// hits Enter out of habit keeps what they have.
 //
-// Answering is the caller's job: both answers close the dialog, and a listener
-// on [data-confirm-accept] is where the destructive work goes. Focus opens on
-// the SAFE answer, never the destructive one, so a reader who hits Enter out of
-// habit keeps what they have.
-//
-// Inertness, Escape and the focus trap come from ./overlay.js — one stack for
-// every overlay on the page, so a confirm over a drawer never has to guess which
-// of the two the keyboard belongs to.
+// Inertness, Escape and the focus trap come from ./overlay.js: one stack for
+// every overlay on the page.
 import { button, esc } from './index.js';
 import { OVERLAY_LAYER, adoptOverlay, focusablesIn, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
 
@@ -24,23 +19,27 @@ const cx = (...a) => a.filter(Boolean).join(' ');
 let _uid = 0;
 const nextId = (p = 'confirm') => `${p}-${++_uid}`;
 
-// The public factory. Returns an HTML string; wire it with wireConfirm().
-//   title         the question — also the dialog's accessible name
-//   body          the consequence — the dialog's accessible description
-//   confirmLabel  the destructive answer (default 'Confirm')
-//   cancelLabel   the safe answer (default 'Cancel')
-//   variant       'danger' (default) | 'primary' — which button the answer is
-//   open          render already-open, as a real dialog: wireConfirm() adopts it
-//                 onto the overlay stack, so the page behind it goes inert, Tab
-//                 is trapped in the panel and Escape closes it
-//   specimen      render open as a *picture* of the dialog: same markup, minus
-//                 the data-confirm hook and aria-modal, so no wiring and no key
-//                 handler can reach it. A documentation page shows several at
-//                 once and none of them owns the page or answers Escape — an
-//                 answered specimen would erase itself with nothing to bring it
-//                 back, and three modal dialogs on one page trap the reader in
-//                 the first. `open` is the one to use when the dialog is real.
-//   id            root id — a [data-confirm-open="id"] trigger targets it
+/**
+ * The public factory. Returns an HTML string; wire it with wireConfirm().
+ *
+ * `specimen` renders open as a *picture* of the dialog — same markup, minus the
+ * data-confirm hook and aria-modal, so no wiring and no key handler can reach
+ * it. A documentation page shows several at once and none of them may own the
+ * page or answer Escape: an answered specimen would erase itself with nothing to
+ * bring it back, and three modal dialogs on one page trap the reader in the
+ * first. Use `open` when the dialog is real.
+ *
+ * @param {object} [o]
+ * @param {string} [o.title]         the question — also the accessible name
+ * @param {string} [o.body]          the consequence — the accessible description
+ * @param {string} [o.confirmLabel]  the destructive answer (default 'Confirm')
+ * @param {string} [o.cancelLabel]   the safe answer (default 'Cancel')
+ * @param {string} [o.variant]       'danger' (default) | 'primary'
+ * @param {boolean} [o.open]         render already-open, as a real dialog
+ * @param {boolean} [o.specimen]     render open as a picture of the dialog
+ * @param {string} [o.id]            root id a [data-confirm-open] trigger targets
+ * @returns {string} html
+ */
 export function confirm({
   title = 'Are you sure?', body = '', confirmLabel = 'Confirm', cancelLabel = 'Cancel',
   variant = 'danger', id, open = false, specimen = false,

package/src/components/drawer.js

@@ -1,19 +1,15 @@
-// Drawer — the kit's edge-anchored overlay panel (a.k.a. Sheet / Slide-over): a
-// panel that slides in from any screen edge over a scrim. Header (title + close)
-// / scrollable body / footer actions. Sizes sm|md|lg — full-height for
-// left|right, full-width for top|bottom.
+// Drawer — the kit's edge-anchored overlay panel: a panel that slides in from
+// any screen edge over a scrim. Header / scrollable body / footer actions, sizes
+// sm|md|lg along the slide axis.
 //
 //   container.innerHTML = drawer({ side: 'right', title: 'Filters', body });
 //   wireDrawer(container);   // scrim/Esc/close-button + focus trap
 //
-// A page trigger opens it by id:  <button data-drawer-open="ID">…</button>
-// (or call openDrawer(rootEl) directly). Pass `open: true` to render it already
-// open, or `specimen: true` for a picture of one on a documentation page.
-//
-// Inertness, Escape and the focus trap are shared with confirm(): both are
+// A page trigger opens it by id: <button data-drawer-open="ID">. Inertness,
+// Escape and the focus trap are shared with confirm(): both are
 // "content over a scrim, focus-trapped, Esc-dismissable", and they push onto one
-// stack in ./overlay.js so the two can never disagree about which of them the
-// keyboard currently belongs to.
+// stack in ./overlay.js, so the two can never disagree about which of them the
+// keyboard belongs to.
 import { esc, icon } from './index.js';
 import { OVERLAY_LAYER, adoptOverlay, focusablesIn, popOverlay, pushOverlay, returnFocus, syncOverlays } from './overlay.js';
 
@@ -23,23 +19,26 @@ const cx = (...a) => a.filter(Boolean).join(' ');
 let _uid = 0;
 const nextId = (p = 'drawer') => `${p}-${++_uid}`;
 
-// The public factory. Returns an HTML string; wire it with wireDrawer().
-//   side        'right' (default) | 'left' | 'top' | 'bottom' — the edge it hugs
-//   size        'sm' | 'md' (default) | 'lg' — panel extent along the slide axis
-//   title       header heading (also the dialog's accessible name)
-//   body        scrollable body HTML (trusted markup)
-//   footer      pinned footer actions HTML (trusted markup)
-//   open        render already-open, as a real panel: wireDrawer() adopts it onto
-//               the overlay stack, so the page behind it goes inert, Tab is
-//               trapped in the panel and Escape closes it
-//   specimen    render open as a *picture* of the panel: same markup, minus the
-//               data-drawer hook and aria-modal, so no wiring and no key handler
-//               can reach it. See confirm() for why a documentation page wants
-//               that; `open` is the one to use when the drawer is real.
-//   id          root id — a [data-drawer-open="id"] trigger targets it
-//   ariaLabel   accessible name when there's no visible title
-//   dismissible show the close button + allow scrim/Esc dismiss (default true)
-//   closeLabel  accessible name for the close button (default 'Close')
+/**
+ * The public factory. Returns an HTML string; wire it with wireDrawer().
+ *
+ * `specimen` renders open as a *picture* of the panel — see confirm() for why a
+ * documentation page wants that. Use `open` when the drawer is real.
+ *
+ * @param {object} [o]
+ * @param {string} [o.side]        'right' (default) | 'left' | 'top' | 'bottom'
+ * @param {string} [o.size]        'sm' | 'md' (default) | 'lg', along the slide axis
+ * @param {string} [o.title]       header heading, also the accessible name
+ * @param {string} [o.body]        scrollable body HTML (trusted markup)
+ * @param {string} [o.footer]      pinned footer actions HTML (trusted markup)
+ * @param {boolean} [o.open]       render already-open, as a real panel
+ * @param {boolean} [o.specimen]   render open as a picture of the panel
+ * @param {string} [o.id]          root id a [data-drawer-open] trigger targets
+ * @param {string} [o.ariaLabel]   accessible name when there is no visible title
+ * @param {boolean} [o.dismissible] close button + scrim/Esc dismiss (default true)
+ * @param {string} [o.closeLabel]  accessible name for the close button
+ * @returns {string} html
+ */
 export function drawer({
   side = 'right', size = 'md', title, body = '', footer = '',
   open = false, specimen = false, id, ariaLabel, dismissible = true, closeLabel = 'Close',

package/src/components/dropdown.js

@@ -1,20 +1,17 @@
-// 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:
+// Dropdown — the kit's one popover-list primitive. A trigger opens a panel of
+// item rows; two flavours share the same panel and 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.
+// The name is deliberate: `menu` implies actions only and `select` implies a
+// form control bound to a value, and this factory is the umbrella both are
+// specialisations of. The topbar's version switcher and account menu are thin
+// consumers of the SAME wiring, so there is one open/close/Esc/keyboard
+// implementation in the kit.
 //
 //   container.innerHTML = dropdown({ label: 'version:', value: '…', items });
-//   wireDropdown(container);   // or let wireTopbar() do it (it calls this)
+//   wireDropdown(container);   // or let wireTopbar() do it
 import { esc, icon } from './index.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');
@@ -66,18 +63,24 @@ function ddBody({ items, sections }, listbox) {
   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)
+/**
+ * The public factory. Returns an HTML string; wire it with wireDropdown().
+ *
+ * @param {object} [o]
+ * @param {string} [o.label]       muted prefix in the trigger (e.g. "version:")
+ * @param {string} [o.value]       current value shown in the trigger
+ * @param {string} [o.placeholder] shown when there is no value
+ * @param {string} [o.variant]     'select' (listbox) | 'menu' (inferred from items)
+ * @param {Array}  [o.items]       [{ label, value?, description?, icon?, badge?, selected?, disabled?, href?, danger? }]
+ * @param {Array}  [o.sections]    [{ label, items }] — grouped alternative to items
+ * @param {string} [o.header]      raw HTML pinned to the top of the panel
+ * @param {string} [o.footer]      raw HTML pinned to the bottom of the panel
+ * @param {string} [o.align]       'start' (default) | 'end' — the edge the panel hugs
+ * @param {boolean|number} [o.scroll] true, or a maxHeight in px, to cap and scroll
+ * @param {boolean} [o.open]       render already-open (handy for screenshots)
+ * @param {string} [o.ariaLabel]   accessible name for the panel and trigger
+ * @returns {string} html
+ */
 export function dropdown({
   label, value, placeholder = 'Select…', variant, items, sections,
   header = '', footer = '', triggerContent, triggerClass = '', chevron = true,

package/src/components/index.js

@@ -66,21 +66,17 @@ export function card({ title, sub, body = '', variant, pad, icon: ic } = {}) {
 }
 
 // ---- Segmented control ---------------------------------------------------
-// A strip of mutually exclusive toggle buttons — a filter, a unit switch, a
-// language picker. It is NOT a tablist: it controls no panel, so it must not
-// announce one. `role="toolbar"` with a roving tabindex is the honest shape —
-// one Tab stop for the whole strip, ArrowLeft/ArrowRight to move between the
-// options, Home/End to jump to the ends, and `aria-pressed` to say which is on.
-// wireTopbar() ships that keyboard behaviour (see topbar.js); the markup here
-// carries the state it reads.
+// A strip of mutually exclusive toggle buttons.
+// It is NOT a tablist: it controls no panel, so it must not announce one.
+// `role="toolbar"` with a roving tabindex is the honest shape, and wireTopbar()
+// ships the keyboard behaviour.
 //
-// When the pill drives a real change of view with content behind it, reach for
-// tabs() instead — that one owns panels and earns the tab announcement.
+// When the pill drives a real change of view, reach for tabs() instead —
+// that one owns panels and earns the tab announcement.
 //
-// `ariaLabel` names the strip. `name` seeds data-seg (a hook for callers) and
-// is deliberately not an accessible name — it is an identifier, not prose.
-// Defaults to "Options" so a strip is never left unlabelled, the same way
-// switchToggle() defaults its label.
+// `ariaLabel` names the strip. `name` seeds data-seg and is deliberately
+// not an accessible name — it is an identifier, not prose, defaulting to
+// "Options" so a strip is never left unlabelled.
 export function segmented({ options = [], active = 0, size, block, name = 'seg', ariaLabel = 'Options' } = {}) {
   const cls = cx('ui-seg', size && `ui-seg--${size}`, block && 'ui-seg--block');
   // Exactly one option holds the Tab stop. If `active` points nowhere (nothing

package/src/components/nav.js

@@ -1,24 +1,11 @@
-// 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:
+// Navigation — the kit's primary wayfinding primitives. `nav({ variant })`
+// dispatches to sidebarNav(), navTabs() and breadcrumbs(), each also exported
+// directly: the three share tokens and classes but almost no markup, so a single
+// options bag would mean wildly different fields per variant.
 //
-//   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).
+// These are NAVIGATION controls, not tab panels — so tabs render as
+// <nav> + <a aria-current="page">, not role="tablist" (that is what segmented()
+// is for). Only the collapsible sidebar groups need JS; wire with wireNav().
 import { esc, icon } from './index.js';
 
 const cx = (...a) => a.filter(Boolean).join(' ');

package/src/components/overlay.js

@@ -1,19 +1,12 @@
-// Overlay primitives — the page state the kit's modal surfaces share.
-//
-// Drawer and Confirm are the same problem twice: content over a scrim that owns
-// the keyboard until it is answered. Three of the questions they raise are
-// properties of the *page*, not of either component — what is inert right now,
-// which overlay Escape talks to, and where Tab may go — and an overlay that
-// answers them from its own storage gets them wrong as soon as a second one is
-// open. So they are answered here, once, from one stack per document.
-//
-// Internal — not re-exported from src/index.js.
-
-// What each overlay paints on, as its stylesheet resolves it today: a drawer at
-// `--z-overlay` (src/styles/drawer.css) and a confirm one above it
-// (src/styles/confirm.css). Absolute values, not ranks, so a sheet that moves and
-// a table that did not is a failed test rather than a keyboard on the wrong layer
-// — stories/overlay-css.test.js holds these two numbers to those two rules.
+// Overlay primitives — the page state the kit's modal surfaces share. Drawer and Confirm
+// are the same problem twice: content over a scrim that owns the keyboard until it is
+// answered. What is inert, which overlay Escape talks to and where Tab may go are
+// properties of the *page*, so they are answered here from one stack per document rather
+// than from either component's own storage. Internal — not re-exported from src/index.js.
+
+// What each overlay paints on today: a drawer at `--z-overlay` (styles/drawer.css) and a
+// confirm above it (styles/confirm.css). Absolute values, not ranks, so a sheet that moves
+// and a table that did not is a failed test — stories/overlay-css.test.js holds both.
 export const OVERLAY_LAYER = { drawer: 100, confirm: 101 };
 
 const FOCUSABLE = [
@@ -33,10 +26,9 @@ function pageOf(doc) {
   return page;
 }
 
-// Focusable to the *browser*, not merely matching the selector. A control in a
-// closed overlay, an inert subtree or a hidden ancestor is skipped by the real
-// tab order, so a trap that counts it wraps at an element focus never reaches
-// and Tab walks straight out of the modal.
+// Focusable to the *browser*, not merely matching the selector. A control in a closed
+// overlay, an inert subtree or a hidden ancestor is skipped by the real tab order, so a
+// trap that counts it wraps at an element focus never reaches.
 function reachable(el) {
   for (let n = el; n && n.nodeType === 1; n = n.parentElement) {
     if (n.inert || n.hasAttribute('inert') || n.hasAttribute('hidden')) return false;
@@ -53,10 +45,9 @@ export function focusablesIn(panel) {
   return Array.from(panel.querySelectorAll(FOCUSABLE)).filter(reachable);
 }
 
-// Hide everything *outside* `root` from AT + the tab order: walk root→body and
-// mark each ancestor's other children. The scrim and panel live inside the root
-// so they stay interactive; an overlay one layer down is outside it, so it does
-// not — a drawer under an aria-modal alertdialog must not be tabbable.
+// Hide everything *outside* `root` from AT + the tab order: walk root→body and mark each
+// ancestor's other children. Scrim and panel live inside the root so they stay
+// interactive; a drawer under an aria-modal alertdialog is outside it and must not be.
 function mark(page, doc, root) {
   let node = root;
   while (node && node.parentElement && node !== doc.body) {
@@ -81,10 +72,9 @@ function unmark(page) {
   page.marked = [];
 }
 
-// Recompute the page from the stack — never replay a snapshot taken when an
-// overlay opened, because by the time it closes that snapshot describes a page
-// that has moved on. Roots torn down while open drop out here, so the record of
-// what to give back outlives the node that hid it.
+// Recompute the page from the stack — never replay a snapshot taken when an overlay
+// opened, because by the time it closes that snapshot describes a page that has moved on.
+// Roots torn down while open drop out here.
 function sync(doc) {
   const page = pageOf(doc);
   for (let i = page.stack.length - 1; i >= 0; i--) {
@@ -128,12 +118,11 @@ function place(root, panel, dismiss, layer, where) {
   sync(doc);
 }
 
-// The layer this root actually paints on. In a browser the live z-index is the
-// truth, so a consumer who moves either overlay in their own stylesheet gets the
-// keyboard on the layer they can see. JSDOM has no cascade to resolve: it hands
-// back the declared text — `calc(var(--z-overlay) + 1)` with the kit's sheets,
-// `auto` with none — and neither is a number, so under test the passed constant
-// stands. `auto` must not read as 0; anything unparseable falls through.
+// The layer this root actually paints on. In a browser the live z-index is the truth, so
+// a consumer who moves an overlay in their own stylesheet gets the keyboard on the layer
+// they can see. JSDOM hands back declared text rather than a number, so under test the
+// passed constant stands — `auto` must not read as 0, and anything unparseable falls
+// through.
 function paintedLayer(root, layer) {
   const painted = root.ownerDocument.defaultView?.getComputedStyle(root)?.zIndex;
   const live = painted ? Number(painted) : NaN;
@@ -152,25 +141,11 @@ export function pushOverlay(root, panel, dismiss, layer) {
 }
 
 /**
- * Take on a root that arrived already open — markup rendered with `open: true`,
- * which nobody called open…() for. Without this its aria-modal is a claim the
- * page contradicts: nothing is inert, Tab walks out, Escape has no owner.
- *
- * It goes in by paint order, because wiring has no history to order by and the
- * overlay the reader is looking at is the one drawn over the rest: a confirm sits
- * a layer above a drawer whichever component's wiring ran first, and whichever
- * root the markup happens to put first. Document position only separates two
- * overlays on the same layer, and there it is the right answer rather than a
- * fallback — at equal stack levels the later root paints on top (CSS 2.2 Appendix
- * E, steps 8 and 9). That comparison earns its keep whenever adoption order and
- * document order disagree: a root inserted above one already on the stack and
- * wired after it, and — in a browser only — a consumer stylesheet that lifts the
- * drawer onto the confirm's layer, where wiring runs drawer-first however the
- * markup is ordered. A browser refines the layer from the live z-index; JSDOM has
- * none to give, so the tests hold OVERLAY_LAYER to the sheets instead. A root that
- * renders closed is left alone: wiring is not an opening, and it waits for the one
- * that is. A specimen never reaches here at all — it carries no hook for the
- * wiring to find.
+ * Take on a root that arrived already open — markup rendered with `open: true`, which
+ * nobody called open…() for. Without this its aria-modal is a claim the page contradicts.
+ * It goes in by PAINT ORDER, because wiring has no history to order by; document position
+ * separates two overlays on the same layer, where the later root paints on top (CSS 2.2
+ * Appendix E, steps 8 and 9). A root that renders closed is left alone.
  */
 export function adoptOverlay(root, panel, dismiss, layer) {
   if (!root.classList.contains('is-open')) return;