@ponchia/ui 0.6.0 → 0.6.4

package/behaviors/table.js

@@ -19,9 +19,20 @@ import { hasDom, resolveHost, noop, bindOnce, collectHosts } from './internal.js
  *
  * SSR-safe, idempotent per table; returns a cleanup function.
  *
- * The numeric sort parses each cell as display text (strips non-[0-9.-] chars),
- * so it is locale-naive — group/decimal separators beyond `.`/`-` are not
- * interpreted. It is a client-side convenience sorter, not a data grid.
+ * The numeric sort parses each cell's display text after normalizing the
+ * common report shapes: a Unicode minus (U+2212) and en/em dashes count as a
+ * sign (so a "−5" loss sorts BELOW a "5" gain, not above it), accounting
+ * parentheses `(1,234)` read as negative, and `,` thousands separators are
+ * dropped. Note the consequence: a bare `,` in the *display text* is read as a
+ * thousands separator, so a European decimal "3,5" sorts as 35, not 3.5 — for a
+ * European decimal comma (or mixed units, or any ambiguous text) put the
+ * canonical number in a `data-sort-value` attribute on the cell. That escape
+ * hatch wins over the parsed text and accepts either a dot ("3.5") or a single
+ * decimal comma ("3,5"). It is a client-side convenience sorter, not a data
+ * grid. (component audit C3/C5.)
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initTableSort({ root } = {}) {
   if (!hasDom()) return noop;
@@ -44,6 +55,38 @@ export function initTableSort({ root } = {}) {
 
     const colIndex = (th) => [...th.parentElement.children].indexOf(th);
     const cellText = (row, i) => row.children[i]?.textContent.trim() ?? '';
+    // Numeric value of a cell for sorting. A `data-sort-value` attribute is the
+    // authoritative escape hatch; otherwise normalize the display text so the
+    // sign survives (U+2212 / en-em dashes → minus, accounting parens →
+    // negative) and `,` grouping is dropped. Returns 0 for unparseable cells so
+    // they cluster rather than scatter. (component audit C3.)
+    const cellNum = (row, i) => {
+      const cell = row.children[i];
+      const explicit = cell?.getAttribute?.('data-sort-value');
+      if (explicit != null && explicit.trim() !== '') {
+        const raw = explicit.trim();
+        let v = Number(raw);
+        // The escape hatch must actually handle the case the doc names it for: a
+        // European decimal comma. `Number("3,5")` is NaN, which silently fell
+        // back to parsing the display text (where `,` is dropped as a thousands
+        // separator → "35"). A lone comma with no dot is a decimal point here.
+        if (!Number.isFinite(v) && /^[+-]?\d+,\d+$/.test(raw)) v = Number(raw.replace(',', '.'));
+        if (Number.isFinite(v)) return v;
+      }
+      let s = (cell?.textContent ?? '').trim();
+      if (!s) return 0;
+      let sign = 1;
+      const paren = /^\((.*)\)$/.exec(s); // accounting negative
+      if (paren) {
+        sign = -1;
+        s = paren[1];
+      }
+      s = s.replace(/[−–—]/g, '-'); // minus / en / em dash → '-'
+      if (/-/.test(s)) sign *= -1;
+      s = s.replace(/,/g, ''); // drop thousands separators
+      const v = parseFloat(s.replace(/[^\d.]/g, '')); // magnitude
+      return Number.isFinite(v) ? sign * v : 0;
+    };
 
     const sortBy = (th, numeric) => {
       const headers = th.closest('tr').querySelectorAll('th');
@@ -61,12 +104,9 @@ export function initTableSort({ root } = {}) {
       const emptyRows = [...tbody.rows].filter((r) => r.classList.contains('ui-table__empty'));
       const rows = [...tbody.rows].filter((r) => !r.classList.contains('ui-table__empty'));
       rows.sort((a, b) => {
-        const x = cellText(a, i);
-        const y = cellText(b, i);
         const cmp = numeric
-          ? (parseFloat(x.replace(/[^\d.-]/g, '')) || 0) -
-            (parseFloat(y.replace(/[^\d.-]/g, '')) || 0)
-          : x.localeCompare(y);
+          ? cellNum(a, i) - cellNum(b, i)
+          : cellText(a, i).localeCompare(cellText(b, i));
         return cmp * sign;
       });
       // Re-parent in document order: sorted data rows, then any empty/sentinel

package/behaviors/tabs.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Wire `[data-bronto-tabs]` groups for full keyboard a11y. The framework
+ * ships the look + the ARIA/`.is-active` contract; this adds the WAI-ARIA
+ * Tabs pattern: roving `tabindex`, `aria-selected`, Arrow/Home/End
+ * navigation with automatic activation, and panel `hidden` sync. Tabs are
+ * `.ui-tab[data-tab]`; panels are `.ui-tabs__panel[data-panel]` with
+ * matching values. SSR-safe and idempotent (re-init replaces, never
+ * stacks, the per-group listeners); returns a cleanup function.
+ *
+ * Accessibility caveat: this is what makes tabs operable. Do **not**
+ * author `hidden` on `.ui-tabs__panel` in server-rendered markup unless
+ * `initTabs` is guaranteed to run client-side — without it the panels
+ * stay hidden with no keyboard/pointer way to reveal them. Prefer
+ * authoring all panels visible and letting `initTabs` add `hidden`.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initTabs({ root }?: import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+//# sourceMappingURL=tabs.d.ts.map

package/behaviors/tabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["tabs.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,oCAHW,OAAO,eAAe,EAAE,YAAY,GAClC,OAAO,eAAe,EAAE,OAAO,CAuF3C"}

package/behaviors/tabs.js

@@ -14,6 +14,9 @@ import { hasDom, resolveHost, noop, bindOnce, nextFieldUid, collectHosts } from
  * `initTabs` is guaranteed to run client-side — without it the panels
  * stay hidden with no keyboard/pointer way to reveal them. Prefer
  * authoring all panels visible and letting `initTabs` add `hidden`.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initTabs({ root } = {}) {
   if (!hasDom()) return noop;

package/behaviors/theme.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @typedef {object} ThemeStorageOpts
+ * @property {string} [storageKey] localStorage key for the persisted theme. Default: `"bronto-theme"`.
+ *
+ * @typedef {ThemeStorageOpts & { root?: Element }} ApplyThemeOpts
+ *   `root` is the element to set `data-theme` on. Default: `<html>`.
+ *
+ * @typedef {object} ThemeChangeDetail
+ * @property {'light' | 'dark'} theme `bronto:themechange` CustomEvent detail.
+ */
+/**
+ * Apply the persisted theme to <html data-theme>. Call as early as
+ * possible (an inline module in <head>) to avoid a flash before the
+ * toggle wires up. No stored value → leaves prefers-color-scheme to act.
+ *
+ * @param {ApplyThemeOpts} [opts]
+ * @returns {void}
+ */
+export function applyStoredTheme({ storageKey, root }?: ApplyThemeOpts): void;
+/**
+ * Wire `[data-bronto-theme-toggle]` controls. Click toggles light/dark,
+ * persists to localStorage, and **always** sets `data-theme` on <html>
+ * (a theme is document-global). State is reflected via `aria-pressed`
+ * and a `bronto:themechange` CustomEvent ({ detail: { theme } }) is
+ * dispatched on <html> so consumers can sync their own UI without
+ * racing the click handler. A control may set
+ * `data-bronto-theme-toggle="dark"` to force a specific theme.
+ *
+ * `root` scopes event delegation and which controls are queried/reflected
+ * (default `document`); it does not change where the theme is applied.
+ *
+ * @param {ThemeStorageOpts & import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initThemeToggle({ storageKey, root }?: ThemeStorageOpts & import("./internal.js").DelegateOpts): import("./internal.js").Cleanup;
+export type ThemeStorageOpts = {
+    /**
+     * localStorage key for the persisted theme. Default: `"bronto-theme"`.
+     */
+    storageKey?: string | undefined;
+};
+/**
+ * `root` is the element to set `data-theme` on. Default: `<html>`.
+ */
+export type ApplyThemeOpts = ThemeStorageOpts & {
+    root?: Element;
+};
+export type ThemeChangeDetail = {
+    /**
+     * `bronto:themechange` CustomEvent detail.
+     */
+    theme: "light" | "dark";
+};
+//# sourceMappingURL=theme.d.ts.map

package/behaviors/theme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"theme.d.ts","sourceRoot":"","sources":["theme.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH;;;;;;;GAOG;AACH,wDAHW,cAAc,GACZ,IAAI,CAahB;AAED;;;;;;;;;;;;;;GAcG;AACH,uDAHW,gBAAgB,GAAG,OAAO,eAAe,EAAE,YAAY,GACrD,OAAO,eAAe,EAAE,OAAO,CAmD3C;;;;;;;;;;6BA5FY,gBAAgB,GAAG;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE;;;;;WAIpC,OAAO,GAAG,MAAM"}

package/behaviors/theme.js

@@ -2,10 +2,24 @@ import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
 
 const THEMES = ['light', 'dark'];
 
+/**
+ * @typedef {object} ThemeStorageOpts
+ * @property {string} [storageKey] localStorage key for the persisted theme. Default: `"bronto-theme"`.
+ *
+ * @typedef {ThemeStorageOpts & { root?: Element }} ApplyThemeOpts
+ *   `root` is the element to set `data-theme` on. Default: `<html>`.
+ *
+ * @typedef {object} ThemeChangeDetail
+ * @property {'light' | 'dark'} theme `bronto:themechange` CustomEvent detail.
+ */
+
 /**
  * Apply the persisted theme to <html data-theme>. Call as early as
  * possible (an inline module in <head>) to avoid a flash before the
  * toggle wires up. No stored value → leaves prefers-color-scheme to act.
+ *
+ * @param {ApplyThemeOpts} [opts]
+ * @returns {void}
  */
 export function applyStoredTheme({ storageKey = 'bronto-theme', root } = {}) {
   if (!hasDom()) return;
@@ -31,6 +45,9 @@ export function applyStoredTheme({ storageKey = 'bronto-theme', root } = {}) {
  *
  * `root` scopes event delegation and which controls are queried/reflected
  * (default `document`); it does not change where the theme is applied.
+ *
+ * @param {ThemeStorageOpts & import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function initThemeToggle({ storageKey = 'bronto-theme', root } = {}) {
   if (!hasDom()) return noop;

package/behaviors/toast.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @typedef {object} ToastOpts
+ * @property {'accent' | 'success' | 'warning' | 'danger' | 'info'} [tone] Status tone — maps to `ui-toast--<tone>`.
+ * @property {string} [title] Optional uppercase label rendered above the message.
+ * @property {number} [duration] Auto-dismiss delay in ms. `0` keeps it until dismissed. Default: `4000`.
+ * @property {boolean} [assertive] Route to the assertive live region so AT interrupts immediately. Defaults to `true` when `tone === 'danger'`.
+ * @property {boolean} [closable] Render a dismiss button on the toast.
+ */
+/**
+ * Push a transient toast into a shared, screen-anchored stack. The stack
+ * is the `aria-live="polite"` region: it is created once, appended to
+ * <body>, and **kept resident even when empty** so the live region is
+ * always present before content is inserted (a freshly created region
+ * that receives its first child in the same tick is not reliably
+ * announced by VoiceOver/NVDA). On first creation the empty region is
+ * inserted and the toast is appended on the next frame for the same
+ * reason. `tone` is accent/success/warning/danger/info; `title` is an
+ * optional uppercase label; `duration` ms before auto-dismiss (0 keeps
+ * it until dismissed). Returns a function that dismisses the toast
+ * early. SSR-safe (no-op).
+ *
+ * @param {string} message
+ * @param {ToastOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function toast(message: string, { tone, title, duration, assertive, closable }?: ToastOpts): import("./internal.js").Cleanup;
+export type ToastOpts = {
+    /**
+     * Status tone — maps to `ui-toast--<tone>`.
+     */
+    tone?: "accent" | "success" | "warning" | "danger" | "info" | undefined;
+    /**
+     * Optional uppercase label rendered above the message.
+     */
+    title?: string | undefined;
+    /**
+     * Auto-dismiss delay in ms. `0` keeps it until dismissed. Default: `4000`.
+     */
+    duration?: number | undefined;
+    /**
+     * Route to the assertive live region so AT interrupts immediately. Defaults to `true` when `tone === 'danger'`.
+     */
+    assertive?: boolean | undefined;
+    /**
+     * Render a dismiss button on the toast.
+     */
+    closable?: boolean | undefined;
+};
+//# sourceMappingURL=toast.d.ts.map

package/behaviors/toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["toast.js"],"names":[],"mappings":"AA2HA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,+BAJW,MAAM,mDACN,SAAS,GACP,OAAO,eAAe,EAAE,OAAO,CAgD3C"}

package/behaviors/toast.js

@@ -25,7 +25,13 @@ function toastStack(isAssertive) {
     stack = document.createElement('div');
     stack.className = isAssertive ? 'ui-toast-stack ui-toast-stack--assertive' : 'ui-toast-stack';
     stack.setAttribute('aria-live', isAssertive ? 'assertive' : 'polite');
-    if (isAssertive) stack.setAttribute('role', 'alert');
+    if (isAssertive) {
+      stack.setAttribute('role', 'alert');
+      // The assertive region carries one error at a time and must be read whole;
+      // aria-atomic ensures the full toast (title + message) announces, not just
+      // the diff. (component audit C38.)
+      stack.setAttribute('aria-atomic', 'true');
+    }
     document.body.appendChild(stack);
   }
   return { stack, fresh };
@@ -57,7 +63,12 @@ function toastElement(message, { tone, title }) {
   }
   el.className = validTone ? `ui-toast ui-toast--${validTone}` : 'ui-toast';
   // No per-item role: the stack itself is the live region; a nested
-  // live region risks double announcement in some SRs.
+  // live region risks double announcement in some SRs. But mark the toast
+  // aria-atomic so a *titled* toast announces title + message as one unit, not
+  // disjointly — and unlike aria-atomic on the polite STACK (which would re-read
+  // every resident toast on each new one), scoping it to the toast keeps sibling
+  // toasts out of the announcement. (component audit C23.)
+  el.setAttribute('aria-atomic', 'true');
   if (title) {
     const t = document.createElement('p');
     t.className = 'ui-toast__title';
@@ -110,6 +121,15 @@ function addToastClose(el, dismiss) {
   el.appendChild(close);
 }
 
+/**
+ * @typedef {object} ToastOpts
+ * @property {'accent' | 'success' | 'warning' | 'danger' | 'info'} [tone] Status tone — maps to `ui-toast--<tone>`.
+ * @property {string} [title] Optional uppercase label rendered above the message.
+ * @property {number} [duration] Auto-dismiss delay in ms. `0` keeps it until dismissed. Default: `4000`.
+ * @property {boolean} [assertive] Route to the assertive live region so AT interrupts immediately. Defaults to `true` when `tone === 'danger'`.
+ * @property {boolean} [closable] Render a dismiss button on the toast.
+ */
+
 /**
  * Push a transient toast into a shared, screen-anchored stack. The stack
  * is the `aria-live="polite"` region: it is created once, appended to
@@ -122,6 +142,10 @@ function addToastClose(el, dismiss) {
  * optional uppercase label; `duration` ms before auto-dismiss (0 keeps
  * it until dismissed). Returns a function that dismisses the toast
  * early. SSR-safe (no-op).
+ *
+ * @param {string} message
+ * @param {ToastOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
  */
 export function toast(message, { tone, title, duration = 4000, assertive, closable } = {}) {
   if (!hasDom()) return noop;
@@ -158,6 +182,14 @@ export function toast(message, { tone, title, duration = 4000, assertive, closab
   // it gets a dismiss affordance by default; any toast can opt in via
   // `closable`. The button carries no text node (glyph is a CSS
   // ::before) so the toast's announced/textContent stays the message.
+  // Explicitly opting OUT of the close button on a sticky toast strands it with
+  // no in-UI dismissal — warn that the caller must retain and call the returned
+  // dismiss fn. (component audit C37.)
+  if (duration === 0 && closable === false && typeof console !== 'undefined') {
+    console.warn(
+      '[bronto] toast(): duration:0 + closable:false has no in-UI dismissal — keep the returned dismiss() and call it yourself, or set closable:true.',
+    );
+  }
   if (closable ?? duration === 0) addToastClose(el, dismiss);
   if (duration > 0) timer = setTimeout(dismiss, duration);
   return dismiss;