@ponchia/ui 0.6.6 → 0.6.7

package/behaviors/splitter.js

@@ -0,0 +1,200 @@
+import { hasDom, resolveHost, noop, bindOnce, collectHosts } from './internal.js';
+
+const SELECTOR = '[data-bronto-splitter]';
+const HANDLE_SELECTOR = '.ui-splitter__handle';
+const DEFAULT_MIN = 20;
+const DEFAULT_MAX = 80;
+const DEFAULT_VALUE = 50;
+const STEP = 2;
+const LARGE_STEP = 10;
+
+/**
+ * @typedef {object} SplitterResizeDetail
+ * @property {number} value The first pane size as a 0..100 percentage.
+ * @property {'vertical' | 'horizontal'} orientation Splitter orientation.
+ */
+
+const num = (v, fallback) => {
+  const n = Number.parseFloat(String(v ?? '').trim());
+  return Number.isFinite(n) ? n : fallback;
+};
+
+const fmt = (v) => String(Math.round(v * 10) / 10);
+
+const clamp = (v, min, max) => Math.min(max, Math.max(min, v));
+
+const readCssValue = (splitter) => splitter.style.getPropertyValue('--splitter-pos');
+
+const readOrientation = (splitter, handle) => {
+  const data = splitter.getAttribute('data-bronto-splitter');
+  if (data === 'horizontal' || data === 'vertical') return data;
+  if (splitter.classList.contains('ui-splitter--horizontal')) return 'horizontal';
+  if (splitter.classList.contains('ui-splitter--vertical')) return 'vertical';
+  return handle.getAttribute('aria-orientation') === 'horizontal' ? 'horizontal' : 'vertical';
+};
+
+const getView = (el) => el.ownerDocument?.defaultView || null;
+
+const dispatchResize = (splitter, detail) => {
+  splitter.dispatchEvent(
+    new CustomEvent('bronto:splitter:resize', {
+      bubbles: true,
+      detail,
+    }),
+  );
+};
+
+function wireSplitter(splitter) {
+  const handle = splitter.querySelector(HANDLE_SELECTOR);
+  if (!handle) return noop;
+
+  const orientation = readOrientation(splitter, handle);
+  const min = num(handle.getAttribute('aria-valuemin'), DEFAULT_MIN);
+  const max = Math.max(min, num(handle.getAttribute('aria-valuemax'), DEFAULT_MAX));
+  let value = clamp(
+    num(handle.getAttribute('aria-valuenow'), num(readCssValue(splitter), DEFAULT_VALUE)),
+    min,
+    max,
+  );
+  let activePointer = null;
+
+  const apply = (next, { emit = true } = {}) => {
+    value = clamp(next, min, max);
+    const label = fmt(value);
+    splitter.style.setProperty('--splitter-pos', `${label}%`);
+    handle.setAttribute('aria-valuenow', label);
+    if (emit) dispatchResize(splitter, { value, orientation });
+  };
+
+  if (!handle.hasAttribute('role')) handle.setAttribute('role', 'separator');
+  if (!handle.hasAttribute('tabindex')) handle.tabIndex = 0;
+  if (!handle.hasAttribute('aria-orientation'))
+    handle.setAttribute('aria-orientation', orientation);
+  if (!handle.hasAttribute('aria-valuemin')) handle.setAttribute('aria-valuemin', fmt(min));
+  if (!handle.hasAttribute('aria-valuemax')) handle.setAttribute('aria-valuemax', fmt(max));
+  apply(value, { emit: false });
+
+  const fromPointer = (event) => {
+    const rect = splitter.getBoundingClientRect();
+    const size = orientation === 'horizontal' ? rect.height : rect.width;
+    if (!size) return value;
+    if (orientation === 'horizontal') {
+      return ((event.clientY - rect.top) / size) * 100;
+    }
+    const view = getView(splitter);
+    const dir = view?.getComputedStyle?.(splitter).direction;
+    const x = dir === 'rtl' ? rect.right - event.clientX : event.clientX - rect.left;
+    return (x / size) * 100;
+  };
+
+  const capturePointer = (pointerId) => {
+    if (pointerId === undefined || pointerId === null) return;
+    try {
+      handle.setPointerCapture?.(pointerId);
+    } catch {
+      /* Pointer capture is an affordance; drag still works through document listeners. */
+    }
+  };
+
+  const releasePointer = (pointerId = activePointer) => {
+    if (pointerId === undefined || pointerId === null) return;
+    try {
+      if (!handle.hasPointerCapture || handle.hasPointerCapture(pointerId)) {
+        handle.releasePointerCapture?.(pointerId);
+      }
+    } catch {
+      /* The element may have been removed or capture may already be gone. */
+    }
+  };
+
+  const onKeydown = (event) => {
+    let next = value;
+    if (event.key === 'Home') next = min;
+    else if (event.key === 'End') next = max;
+    else if (event.key === 'PageUp') next += LARGE_STEP;
+    else if (event.key === 'PageDown') next -= LARGE_STEP;
+    else if (event.key === 'ArrowRight' || event.key === 'ArrowDown')
+      next += event.shiftKey ? LARGE_STEP : STEP;
+    else if (event.key === 'ArrowLeft' || event.key === 'ArrowUp')
+      next -= event.shiftKey ? LARGE_STEP : STEP;
+    else return;
+    event.preventDefault();
+    apply(next);
+  };
+
+  const onPointerMove = (event) => {
+    if (
+      activePointer !== null &&
+      event.pointerId !== undefined &&
+      event.pointerId !== activePointer
+    )
+      return;
+    apply(fromPointer(event));
+  };
+
+  const onPointerUp = (event) => {
+    if (
+      activePointer !== null &&
+      event.pointerId !== undefined &&
+      event.pointerId !== activePointer
+    )
+      return;
+    releasePointer(event.pointerId);
+    activePointer = null;
+    handle.classList.remove('is-active');
+    splitter.ownerDocument.removeEventListener('pointermove', onPointerMove);
+    splitter.ownerDocument.removeEventListener('pointerup', onPointerUp);
+    splitter.ownerDocument.removeEventListener('pointercancel', onPointerUp);
+  };
+
+  const onPointerDown = (event) => {
+    if (event.button !== undefined && event.button !== 0) return;
+    event.preventDefault();
+    activePointer = event.pointerId ?? null;
+    capturePointer(activePointer);
+    handle.classList.add('is-active');
+    apply(fromPointer(event));
+    splitter.ownerDocument.addEventListener('pointermove', onPointerMove);
+    splitter.ownerDocument.addEventListener('pointerup', onPointerUp);
+    splitter.ownerDocument.addEventListener('pointercancel', onPointerUp);
+  };
+
+  return bindOnce(splitter, 'splitter', () => {
+    handle.addEventListener('keydown', onKeydown);
+    handle.addEventListener('pointerdown', onPointerDown);
+    return () => {
+      handle.removeEventListener('keydown', onKeydown);
+      handle.removeEventListener('pointerdown', onPointerDown);
+      splitter.ownerDocument.removeEventListener('pointermove', onPointerMove);
+      splitter.ownerDocument.removeEventListener('pointerup', onPointerUp);
+      splitter.ownerDocument.removeEventListener('pointercancel', onPointerUp);
+      releasePointer();
+      handle.classList.remove('is-active');
+      activePointer = null;
+    };
+  });
+}
+
+/**
+ * Wire focusable ARIA splitters. Each `[data-bronto-splitter]` host contains
+ * two `.ui-splitter__pane` elements separated by one `.ui-splitter__handle`
+ * (`role="separator"`). The behavior keeps `--splitter-pos` and
+ * `aria-valuenow` in sync for keyboard and pointer resizing, then dispatches
+ * `bronto:splitter:resize` with `{ value, orientation }`.
+ *
+ * Bronto owns the control affordance only. The host owns pane content,
+ * persistence, min/max policy, collapse behavior, and any saved layout state.
+ * SSR-safe and idempotent per splitter; returns a cleanup function.
+ *
+ * @param {import('./internal.js').DelegateOpts} [opts]
+ * @returns {import('./internal.js').Cleanup}
+ */
+export function initSplitter({ root } = {}) {
+  if (!hasDom()) return noop;
+  const host = resolveHost(root);
+  if (!host) return noop;
+  const splitters = collectHosts(host, SELECTOR);
+  if (!splitters.length) return noop;
+  const cleanups = splitters.map(wireSplitter).filter(Boolean);
+  return () => cleanups.forEach((fn) => fn());
+}

package/behaviors/table.js

@@ -49,6 +49,7 @@ export function initTableSort({ root } = {}) {
     // announces the column as sortable from the start (it was unset until the
     // first click — C10).
     for (const sort of table.querySelectorAll('.ui-table__sort')) {
+      if (sort.tagName === 'BUTTON' && !sort.hasAttribute('type')) sort.type = 'button';
       const th = sort.closest('th');
       if (th && !th.hasAttribute('aria-sort')) th.setAttribute('aria-sort', 'none');
     }
@@ -110,9 +111,8 @@ export function initTableSort({ root } = {}) {
         return cmp * sign;
       });
       // Re-parent in document order: sorted data rows, then any empty/sentinel
-      // row last. A single appendChild pass over the existing <tr> nodes (no
-      // markup is created — these are trusted DOM elements being moved).
-      for (const r of [...rows, ...emptyRows]) tbody.appendChild(r);
+      // row last. These are existing <tr> nodes being moved; no markup is parsed.
+      tbody.append(...rows, ...emptyRows);
     };
 
     const allBox = table.querySelector('[data-bronto-select-all]');

package/behaviors/theme.js

@@ -1,4 +1,4 @@
-import { hasDom, resolveHost, noop, bindOnce } from './internal.js';
+import { hasDom, resolveHost, noop, bindOnce, collectHosts } from './internal.js';
 
 const THEMES = ['light', 'dark'];
 
@@ -66,7 +66,7 @@ export function initThemeToggle({ storageKey = 'bronto-theme', root } = {}) {
 
   const reflect = () => {
     const c = current();
-    host.querySelectorAll('[data-bronto-theme-toggle]').forEach((el) => {
+    collectHosts(host, '[data-bronto-theme-toggle]').forEach((el) => {
       const forced = el.getAttribute('data-bronto-theme-toggle');
       // A forced control is "pressed" when its theme is the active one;
       // a plain toggle reflects whether dark is active.

package/classes/classes.json

@@ -1,8 +1,8 @@
 {
   "$comment": "@ponchia/ui class vocabulary as language-neutral data — validate emitted markup without executing the ESM cls map or parsing the .d.ts. Generated from classes/index.js — do not edit by hand; run `npm run classes:json:build`. Drift-checked in CI. `groups[].base` is null for a parts-only namespace (no standalone base class — do NOT emit it). A modifier whose name contains `__` (e.g. `ui-spark__bar--pos`) attaches to THAT part, not the base host. `states` is the author-applied `is-*` hooks (runtime/behavior-managed hooks are excluded); `behaviorAttributes` are the `data-bronto-*` wiring hooks the optional behaviors delegate on; `requiredAria` is the role/aria a generator must emit per component. `states` + `customProperties` are documented in docs/reference.md and ship outside `cls` by design.",
   "counts": {
-    "classes": 593,
-    "groups": 171
+    "classes": 634,
+    "groups": 177
   },
   "groups": {
     "ui-accordion": {
@@ -322,6 +322,17 @@
         "ui-claim__status"
       ]
     },
+    "ui-clamp": {
+      "base": "ui-clamp",
+      "modifiers": [],
+      "parts": [
+        "ui-clamp__body",
+        "ui-clamp__control",
+        "ui-clamp__less",
+        "ui-clamp__more",
+        "ui-clamp__toggle"
+      ]
+    },
     "ui-cluster": {
       "base": "ui-cluster",
       "modifiers": [
@@ -583,6 +594,21 @@
       "modifiers": [],
       "parts": []
     },
+    "ui-figure": {
+      "base": "ui-figure",
+      "modifiers": [
+        "ui-figure__body--key-right"
+      ],
+      "parts": [
+        "ui-figure__body",
+        "ui-figure__caption",
+        "ui-figure__data",
+        "ui-figure__key",
+        "ui-figure__media",
+        "ui-figure__overlay",
+        "ui-figure__stage"
+      ]
+    },
     "ui-file": {
       "base": "ui-file",
       "modifiers": [],
@@ -613,6 +639,11 @@
       "modifiers": [],
       "parts": []
     },
+    "ui-highlights": {
+      "base": "ui-highlights",
+      "modifiers": [],
+      "parts": []
+    },
     "ui-hint": {
       "base": "ui-hint",
       "modifiers": [
@@ -654,6 +685,37 @@
         "ui-inspector__head"
       ]
     },
+    "ui-interval": {
+      "base": "ui-interval",
+      "modifiers": [],
+      "parts": [
+        "ui-interval__bounds",
+        "ui-interval__label",
+        "ui-interval__point",
+        "ui-interval__range",
+        "ui-interval__track"
+      ]
+    },
+    "ui-job": {
+      "base": "ui-job",
+      "modifiers": [
+        "ui-job--blocked",
+        "ui-job--compact",
+        "ui-job--complete",
+        "ui-job--failed",
+        "ui-job--queued",
+        "ui-job--running"
+      ],
+      "parts": [
+        "ui-job__actions",
+        "ui-job__bar",
+        "ui-job__body",
+        "ui-job__head",
+        "ui-job__meta",
+        "ui-job__progress",
+        "ui-job__title"
+      ]
+    },
     "ui-kbd": {
       "base": "ui-kbd",
       "modifiers": [],
@@ -1134,6 +1196,17 @@
       "modifiers": [],
       "parts": []
     },
+    "ui-splitter": {
+      "base": "ui-splitter",
+      "modifiers": [
+        "ui-splitter--horizontal",
+        "ui-splitter--vertical"
+      ],
+      "parts": [
+        "ui-splitter__handle",
+        "ui-splitter__pane"
+      ]
+    },
     "ui-spotlight": {
       "base": "ui-spotlight",
       "modifiers": [
@@ -1554,6 +1627,12 @@
     "ui-claim__scope",
     "ui-claim__statement",
     "ui-claim__status",
+    "ui-clamp",
+    "ui-clamp__body",
+    "ui-clamp__control",
+    "ui-clamp__less",
+    "ui-clamp__more",
+    "ui-clamp__toggle",
     "ui-cluster",
     "ui-cluster--between",
     "ui-code",
@@ -1667,6 +1746,15 @@
     "ui-eyebrow--muted",
     "ui-eyebrow--sm",
     "ui-field",
+    "ui-figure",
+    "ui-figure__body",
+    "ui-figure__body--key-right",
+    "ui-figure__caption",
+    "ui-figure__data",
+    "ui-figure__key",
+    "ui-figure__media",
+    "ui-figure__overlay",
+    "ui-figure__stage",
     "ui-file",
     "ui-generated",
     "ui-generated__label",
@@ -1675,6 +1763,7 @@
     "ui-glossary__term",
     "ui-grid",
     "ui-halftone",
+    "ui-highlights",
     "ui-hint",
     "ui-hint--error",
     "ui-icon",
@@ -1687,6 +1776,26 @@
     "ui-inspector",
     "ui-inspector__body",
     "ui-inspector__head",
+    "ui-interval",
+    "ui-interval__bounds",
+    "ui-interval__label",
+    "ui-interval__point",
+    "ui-interval__range",
+    "ui-interval__track",
+    "ui-job",
+    "ui-job--blocked",
+    "ui-job--compact",
+    "ui-job--complete",
+    "ui-job--failed",
+    "ui-job--queued",
+    "ui-job--running",
+    "ui-job__actions",
+    "ui-job__bar",
+    "ui-job__body",
+    "ui-job__head",
+    "ui-job__meta",
+    "ui-job__progress",
+    "ui-job__title",
     "ui-kbd",
     "ui-keep",
     "ui-key-value",
@@ -1895,6 +2004,11 @@
     "ui-spark__bar--neg",
     "ui-spark__bar--pos",
     "ui-spinner",
+    "ui-splitter",
+    "ui-splitter--horizontal",
+    "ui-splitter--vertical",
+    "ui-splitter__handle",
+    "ui-splitter__pane",
     "ui-spotlight",
     "ui-spotlight--ring",
     "ui-spotlight__hole",
@@ -2026,7 +2140,7 @@
     {
       "class": "is-open",
       "scope": "controlled .ui-modal / .ui-popover",
-      "effect": "open state (focus-trap is the host's)"
+      "effect": "open visibility state; focus management belongs to the matching behavior/host"
     },
     {
       "class": "is-active",
@@ -2090,6 +2204,13 @@
       "example": "92",
       "note": "measured value as a UNITLESS number 0..100 (registered <number>, never a %). Set it on the meter/progress host — it inherits to the __fill/__bar. Prefer attrs.meter(value)/attrs.progress(value) from @ponchia/ui/classes, which sets it plus role + aria-valuenow/min/max together."
     },
+    {
+      "name": "--job-progress",
+      "on": ".ui-job",
+      "type": "percentage",
+      "example": "64%",
+      "note": "determinate background-job progress. Set it on the .ui-job host; pair the .ui-job__progress element with role=\"progressbar\" and matching aria-valuenow/min/max when the value is known."
+    },
     {
       "name": "--icon-mask",
       "on": ".ui-icon",
@@ -2142,6 +2263,27 @@
       "example": "var(--accent-soft)",
       "note": "the ::target-text highlight wash for the matched cited sentence (default var(--accent-soft)). The host builds the #:~:text= href; Bronto owns the paint — see docs/textref.md."
     },
+    {
+      "name": "--figure-max-inline",
+      "on": ".ui-figure__stage",
+      "type": "length",
+      "example": "32rem",
+      "note": "maximum inline size of the centered figure stage (default 42rem). The host still owns chart/media dimensions and data mapping."
+    },
+    {
+      "name": "--figure-min-block",
+      "on": ".ui-figure__stage",
+      "type": "length",
+      "example": "16rem",
+      "note": "minimum block size reserved for a live or late-rendered figure stage (default 0px)."
+    },
+    {
+      "name": "--figure-key-width",
+      "on": ".ui-figure__body--key-right",
+      "type": "length",
+      "example": "12rem",
+      "note": "width of the right-side key column before the figure body collapses to one column (default 14rem)."
+    },
     {
       "name": "--v",
       "on": ".ui-bullet__measure",
@@ -2178,6 +2320,78 @@
       "example": "1rem",
       "note": "the sticky inset from the top of the scroll container (default var(--space-md))."
     },
+    {
+      "name": "--lo",
+      "on": ".ui-interval",
+      "type": "number 0..1",
+      "example": "0.22",
+      "required": true,
+      "note": "REQUIRED — normalised lower bound of the interval. The host normalises; Bronto only paints."
+    },
+    {
+      "name": "--hi",
+      "on": ".ui-interval",
+      "type": "number 0..1",
+      "example": "0.68",
+      "required": true,
+      "note": "REQUIRED — normalised upper bound of the interval. The host normalises; Bronto only paints."
+    },
+    {
+      "name": "--v",
+      "on": ".ui-interval__point",
+      "type": "number 0..1",
+      "example": "0.52",
+      "note": "optional normalised point estimate inside the interval. Omit the point element when there is no point estimate."
+    },
+    {
+      "name": "--clamp-lines",
+      "on": ".ui-clamp",
+      "type": "integer",
+      "example": "3",
+      "note": "number of lines shown before the optional reveal control expands the excerpt (default 4)."
+    },
+    {
+      "name": "--highlight-evidence",
+      "on": ".ui-highlights",
+      "type": "color",
+      "example": "var(--accent-soft)",
+      "note": "CSS Custom Highlight API wash for host-registered bronto-evidence ranges."
+    },
+    {
+      "name": "--highlight-search",
+      "on": ".ui-highlights",
+      "type": "color",
+      "example": "var(--warning-soft)",
+      "note": "CSS Custom Highlight API wash for host-registered bronto-search ranges."
+    },
+    {
+      "name": "--highlight-current",
+      "on": ".ui-highlights",
+      "type": "color",
+      "example": "color-mix(in srgb, var(--accent) 22%, transparent)",
+      "note": "CSS Custom Highlight API wash for the host-registered bronto-current range."
+    },
+    {
+      "name": "--splitter-pos",
+      "on": ".ui-splitter",
+      "type": "percentage",
+      "example": "36%",
+      "note": "first pane size in the splitter axis. initSplitter keeps this and aria-valuenow in sync; the host may persist the last value."
+    },
+    {
+      "name": "--splitter-handle",
+      "on": ".ui-splitter",
+      "type": "length",
+      "example": "0.75rem",
+      "note": "fixed size of the separator handle track (default 0.75rem)."
+    },
+    {
+      "name": "--splitter-pane-min",
+      "on": ".ui-splitter",
+      "type": "length",
+      "example": "12rem",
+      "note": "minimum first-pane size before the grid track clamps (default 0px); pair with matching aria-valuemin when the limit is user-visible."
+    },
     {
       "name": "--stack-gap",
       "on": ".ui-stack",
@@ -2488,7 +2702,7 @@
       "name": "data-bronto-modal",
       "on": "a controlled (non-<dialog>) .ui-modal overlay",
       "behavior": "initModal",
-      "note": "inert focus-trap + .is-open toggling for a modal that is not a native <dialog>; needs an accessible name"
+      "note": "inert focus-trap, focus-return, and Escape close signal for a consumer-owned .is-open modal; needs an accessible name"
     },
     {
       "name": "data-bronto-menu",
@@ -2515,6 +2729,13 @@
       "behavior": "initSources",
       "note": "scopes citation preview metadata and source-card focus/highlight behavior; the host still owns numbering, fetching, and trust decisions."
     },
+    {
+      "name": "data-bronto-splitter",
+      "on": "a .ui-splitter host",
+      "value": "optional 'vertical' | 'horizontal' (otherwise inferred from .ui-splitter--horizontal / aria-orientation)",
+      "behavior": "initSplitter",
+      "note": "keyboard + pointer ARIA window-splitter behavior; updates --splitter-pos and aria-valuenow, then emits bronto:splitter:resize. The host owns persistence and pane state."
+    },
     {
       "name": "data-bronto-source-ref",
       "on": "a button/control that references a source card",
@@ -2728,6 +2949,11 @@
       "on": ".ui-error-summary",
       "require": "role=\"alert\" + tabindex=\"-1\" on the hand-authored summary so it is announced and focusable when validation fails",
       "helper": "initFormValidation wires this for the dynamic summary; a static summary needs it hand-set"
+    },
+    {
+      "on": ".ui-splitter__handle",
+      "require": "role=\"separator\" + tabindex=\"0\" + aria-controls=\"<first-pane-id>\" + an accessible name + aria-orientation + aria-valuemin/max/now. The aria-valuenow value mirrors --splitter-pos.",
+      "helper": "initSplitter fills missing role/tabindex/orientation/value defaults and updates aria-valuenow; author the accessible name, aria-controls, and meaningful min/max."
     }
   ]
 }

package/classes/index.d.ts

@@ -330,6 +330,15 @@ export declare const cls: {
   readonly compare2up: 'ui-compare--2up';
   readonly compareCol: 'ui-compare__col';
   readonly compareHead: 'ui-compare__head';
+  readonly figure: 'ui-figure';
+  readonly figureCaption: 'ui-figure__caption';
+  readonly figureBody: 'ui-figure__body';
+  readonly figureBodyKeyRight: 'ui-figure__body--key-right';
+  readonly figureStage: 'ui-figure__stage';
+  readonly figureMedia: 'ui-figure__media';
+  readonly figureOverlay: 'ui-figure__overlay';
+  readonly figureKey: 'ui-figure__key';
+  readonly figureData: 'ui-figure__data';
   readonly legend: 'ui-legend';
   readonly legendVertical: 'ui-legend--vertical';
   readonly legendCompact: 'ui-legend--compact';
@@ -459,6 +468,19 @@ export declare const cls: {
   readonly srcReviewed: 'ui-src--reviewed';
   readonly srcStale: 'ui-src--stale';
   readonly srcConflict: 'ui-src--conflict';
+  readonly interval: 'ui-interval';
+  readonly intervalTrack: 'ui-interval__track';
+  readonly intervalRange: 'ui-interval__range';
+  readonly intervalPoint: 'ui-interval__point';
+  readonly intervalLabel: 'ui-interval__label';
+  readonly intervalBounds: 'ui-interval__bounds';
+  readonly clamp: 'ui-clamp';
+  readonly clampBody: 'ui-clamp__body';
+  readonly clampToggle: 'ui-clamp__toggle';
+  readonly clampControl: 'ui-clamp__control';
+  readonly clampMore: 'ui-clamp__more';
+  readonly clampLess: 'ui-clamp__less';
+  readonly highlights: 'ui-highlights';
   readonly diff: 'ui-diff';
   readonly diffSplit: 'ui-diff--split';
   readonly diffPane: 'ui-diff__pane';
@@ -524,6 +546,20 @@ export declare const cls: {
   readonly stateReviewed: 'ui-state--reviewed';
   readonly stateNeedsReview: 'ui-state--needs-review';
   readonly syncbar: 'ui-syncbar';
+  readonly job: 'ui-job';
+  readonly jobHead: 'ui-job__head';
+  readonly jobTitle: 'ui-job__title';
+  readonly jobMeta: 'ui-job__meta';
+  readonly jobBody: 'ui-job__body';
+  readonly jobProgress: 'ui-job__progress';
+  readonly jobBar: 'ui-job__bar';
+  readonly jobActions: 'ui-job__actions';
+  readonly jobCompact: 'ui-job--compact';
+  readonly jobQueued: 'ui-job--queued';
+  readonly jobRunning: 'ui-job--running';
+  readonly jobBlocked: 'ui-job--blocked';
+  readonly jobFailed: 'ui-job--failed';
+  readonly jobComplete: 'ui-job--complete';
   readonly generated: 'ui-generated';
   readonly generatedLabel: 'ui-generated__label';
   readonly originLabel: 'ui-origin-label';
@@ -544,6 +580,11 @@ export declare const cls: {
   readonly selectionbar: 'ui-selectionbar';
   readonly selectionbarCount: 'ui-selectionbar__count';
   readonly selectionbarActions: 'ui-selectionbar__actions';
+  readonly splitter: 'ui-splitter';
+  readonly splitterVertical: 'ui-splitter--vertical';
+  readonly splitterHorizontal: 'ui-splitter--horizontal';
+  readonly splitterPane: 'ui-splitter__pane';
+  readonly splitterHandle: 'ui-splitter__handle';
   readonly command: 'ui-command';
   readonly commandInput: 'ui-command__input';
   readonly commandList: 'ui-command__list';
@@ -699,7 +740,7 @@ export interface DotbarOpts {
 }
 export interface ModalOpts {
   drawer?: boolean;
-  /** Controlled non-dialog usage — adds the is-open state (focus-trap is yours). */
+  /** Controlled non-dialog usage — adds only the is-open state; pair with initModal for focus management. */
   open?: boolean;
 }
 export interface TabOpts {
@@ -810,6 +851,12 @@ export interface StateOpts {
   /** Pulse the indicator for an in-progress state (saving / syncing / retrying). Reduced-motion-safe. */
   busy?: boolean;
 }
+export type JobState = 'queued' | 'running' | 'blocked' | 'failed' | 'complete';
+export interface JobOpts {
+  /** Persistent background-job state. Pair with written status text; tone is only a scanning aid. */
+  state?: JobState;
+  compact?: boolean;
+}
 export interface OriginLabelOpts {
   /** Accent-tint the label for AI/model-generated origin (vs a neutral tag). */
   ai?: boolean;
@@ -892,6 +939,7 @@ export interface Ui {
   sparkBar(opts?: SparkBarOpts): string;
   bulletMeasure(opts?: BulletMeasureOpts): string;
   state(opts?: StateOpts): string;
+  job(opts?: JobOpts): string;
   originLabel(opts?: OriginLabelOpts): string;
 }