@adia-ai/web-components 0.6.36 → 0.6.37

package/components/slider/slider.d.ts

@@ -1,20 +1,36 @@
 /**
- * `<slider-ui>` — Single-handle slider for numeric input.
+ * `<slider-ui>` — Single- or two-thumb slider for numeric input.
+ *
+ * Default: single-thumb (`value`).
+ * Dual mode: set `[dual]` and use `[lower-value]` / `[upper-value]`; the fill
+ * spans between the thumbs and the `change` event detail becomes
+ * `{lower, upper}`.
  *
  * @see https://ui-kit.exe.xyz/site/components/slider
  */
 
 import { UIFormElement } from '../../core/form.js';
 
-export interface SliderChangeEventDetail {
+export interface SliderChangeEventDetailSingle {
   value: number;
 }
+export interface SliderChangeEventDetailDual {
+  lower: number;
+  upper: number;
+}
+export type SliderChangeEventDetail = SliderChangeEventDetailSingle | SliderChangeEventDetailDual;
 export type SliderChangeEvent = CustomEvent<SliderChangeEventDetail>;
 export type SliderInputEvent = CustomEvent<SliderChangeEventDetail>;
 
 export class UISlider extends UIFormElement {
-  /** Numeric value — overrides UIFormElement.value (which is String). */
+  /** Numeric value — overrides UIFormElement.value (which is String). Single-thumb mode; ignored when [dual]. */
   value: number;
+  /** Two-thumb range slider mode. */
+  dual: boolean;
+  /** Lower thumb value (dual mode). */
+  lowerValue: number;
+  /** Upper thumb value (dual mode). */
+  upperValue: number;
   min: number;
   max: number;
   step: number;

package/components/slider/slider.test.js

@@ -144,4 +144,59 @@ describe('slider-ui', () => {
 
     expect(s.querySelector('[slot="suffix"]').textContent).toBe('rem');
   });
+
+  // ─── Dual-thumb mode ────────────────────────────────────────────────
+  // v1.9.x: dual-thumb range slider lives on slider-ui[dual] + [lower-value]/[upper-value].
+  // Fill spans BETWEEN the two thumb centers; thumbs are positioned via
+  // --slider-pct-lower / --slider-pct-upper CSS variables.
+  const pctLower = (s) => s.style.getPropertyValue('--slider-pct-lower').trim();
+  const pctUpper = (s) => s.style.getPropertyValue('--slider-pct-upper').trim();
+
+  it('dual mode: writes --slider-pct-lower and --slider-pct-upper from lower-value / upper-value', async () => {
+    const s = mount('<slider-ui dual lower-value="20" upper-value="80" min="0" max="100"></slider-ui>');
+    await tick();
+    expect(pctLower(s)).toBe('0.2');
+    expect(pctUpper(s)).toBe('0.8');
+  });
+
+  it('dual mode: stamps two thumb elements with data-thumb="lower" and data-thumb="upper"', async () => {
+    const s = mount('<slider-ui dual lower-value="20" upper-value="80" min="0" max="100"></slider-ui>');
+    await tick();
+    const lowerThumb = s.querySelector('[slot="thumb"][data-thumb="lower"]');
+    const upperThumb = s.querySelector('[slot="thumb"][data-thumb="upper"]');
+    expect(lowerThumb).not.toBeNull();
+    expect(upperThumb).not.toBeNull();
+  });
+
+  it('dual mode: change event detail carries {lower, upper}', async () => {
+    const s = mount('<slider-ui dual lower-value="20" upper-value="80" min="0" max="100" step="1"></slider-ui>');
+    await tick();
+    let captured = null;
+    s.addEventListener('change', (e) => { captured = e; });
+    // Focus the lower thumb explicitly so the keyboard handler targets it
+    const lowerThumb = s.querySelector('[slot="thumb"][data-thumb="lower"]');
+    lowerThumb.focus();
+    lowerThumb.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true }));
+    await tick();
+    expect(captured).not.toBeNull();
+    expect(captured.detail).toEqual({ lower: 21, upper: 80 });
+  });
+
+  it('dual mode: lower setter clamps DOWN to upper when set too high', async () => {
+    const s = mount('<slider-ui dual lower-value="20" upper-value="80" min="0" max="100" step="1"></slider-ui>');
+    await tick();
+    s.lowerValue = 90; // > upperValue (80) → constraint clamps lower DOWN to upper
+    await tick();
+    expect(s.lowerValue).toBe(80);
+    expect(s.upperValue).toBe(80); // upper unchanged
+  });
+
+  it('dual mode: upper setter clamps UP to lower when set too low', async () => {
+    const s = mount('<slider-ui dual lower-value="20" upper-value="80" min="0" max="100" step="1"></slider-ui>');
+    await tick();
+    s.upperValue = 10; // < lowerValue (20) → constraint clamps upper UP to lower
+    await tick();
+    expect(s.upperValue).toBe(20);
+    expect(s.lowerValue).toBe(20); // lower unchanged
+  });
 });

package/components/slider/slider.yaml

@@ -49,9 +49,31 @@ props:
     type: string
     default: ""
   value:
-    description: Current slider value
+    description: Current slider value (single-thumb mode; ignored when [dual] is set)
     type: number
     default: 50
+  dual:
+    description: |-
+      Two-thumb range slider mode. When enabled, [lower-value] and
+      [upper-value] are authoritative and [value] is ignored. The fill
+      renders between the two thumbs (not from left to thumb). Form-data
+      under [name] serializes as "<lower>,<upper>". Use for price filters,
+      date ranges, audio range gates, etc.
+    type: boolean
+    default: false
+    reflect: true
+  lowerValue:
+    description: Lower thumb value (dual mode only; clamped to ≤ [upper-value]).
+    type: number
+    default: 0
+    reflect: true
+    attribute: lower-value
+  upperValue:
+    description: Upper thumb value (dual mode only; clamped to ≥ [lower-value]).
+    type: number
+    default: 100
+    reflect: true
+    attribute: upper-value
   throttle:
     description: |-
       §184 (v0.5.5, FEEDBACK-08 §4): when > 0, debounce the `input` event by this many milliseconds. Value updates + visual feedback remain immediate; only event dispatch accumulates. Pending input flushes BEFORE `change` so consumers always see input→…→input→change ordering. throttle="0" (default) preserves the pre-§184 every-pointer-move-fires-input behavior. Common values: 50-100ms for palette regen / shader compile / large list reflow.
@@ -94,12 +116,12 @@ tokens:
     description: Full track height (scales via universal [size] attribute)
 a2ui:
   rules:
-    - rule: 'Single-handle slider for selecting one value in a range. Form-associated; emits numeric change events.'
+    - rule: 'Default mode is single-handle. Form-associated; emits numeric change events with detail.value.'
       reason: 'Single-value range-input contract.'
-    - rule: 'For two-handle range selection use <range-ui> instead.'
-      reason: 'Single vs range sibling.'
-    - rule: 'Step attribute controls increments; show-value enables an inline value label.'
-      reason: 'Standard slider knobs.'
+    - rule: 'For two-handle range selection (price filters, date ranges, audio range gates), set [dual] and use [lower-value]/[upper-value] instead of [value]. Form-data submits as "<lower>,<upper>" under [name]; change event detail carries {lower, upper}. Do NOT use <range-ui> — that primitive is a draggable numeric field, not a two-thumb range slider.'
+      reason: 'Dual-thumb range selection lives on slider-ui[dual], not on a separate primitive.'
+    - rule: '[step] controls increments for both single and dual modes. Constraint: in dual mode, [lower-value] ≤ [upper-value] is enforced on each setter; reversed values clamp to equal.'
+      reason: 'Standard slider knobs + dual-mode constraint.'
 anti_patterns: []
 examples:
   - name: slider-range

package/components/table/table.class.js

@@ -326,12 +326,20 @@ export class UITable extends UIElement {
       this.#bound = true;
       this.addEventListener('click', this.#onClick);
       this.addEventListener('keydown', this.#onKeydown);
+      // Column resize needs pointerdown (drag start) — NOT click. click fires
+      // after pointerup, so by the time #startResize runs from a click
+      // handler, the user has already released and the document-level
+      // move/up listeners never trigger. pointerdown also covers touch +
+      // pen automatically; Playwright's page.mouse.* synthesizes pointer
+      // events (not mouse events), so a mousedown-only handler tests dead.
+      this.addEventListener('pointerdown', this.#onPointerdown);
     }
   }
 
   disconnected() {
     this.removeEventListener('click', this.#onClick);
     this.removeEventListener('keydown', this.#onKeydown);
+    this.removeEventListener('pointerdown', this.#onPointerdown);
     this.#bound = false;
     this.#cleanupResize();
     if (this.#renderRaf) {
@@ -1178,6 +1186,21 @@ export class UITable extends UIElement {
     bar.appendChild(clearAll);
   }
 
+  // ── Event Handling: Pointerdown (resize-drag start) ───────────────────────
+
+  /** Resize-handle drag MUST start on pointerdown, not click — click fires
+   *  only on full down→up gestures (no drag delta), so the document-level
+   *  move/up listeners #startResize attaches arrive after the release.
+   *  pointer events cover mouse + touch + pen in one handler. */
+  #onPointerdown = (e) => {
+    if (e.button !== undefined && e.button !== 0) return;  // primary button only
+    const handle = e.target.closest('[data-resize-handle]');
+    if (handle && this.contains(handle)) {
+      e.preventDefault();
+      this.#startResize(e, handle);
+    }
+  };
+
   // ── Event Handling: Click ──────────────────────────────────────────────────
 
   #onClick = (e) => {
@@ -1355,8 +1378,8 @@ export class UITable extends UIElement {
 
     this.#resizeState = { key, col, startX, startWidth };
 
-    document.addEventListener('mousemove', this.#onResizeMove);
-    document.addEventListener('mouseup', this.#onResizeEnd);
+    document.addEventListener('pointermove', this.#onResizeMove);
+    document.addEventListener('pointerup', this.#onResizeEnd);
   }
 
   #onResizeMove = (e) => {
@@ -1378,8 +1401,8 @@ export class UITable extends UIElement {
     if (!this.#resizeState) return;
     const { key } = this.#resizeState;
 
-    document.removeEventListener('mousemove', this.#onResizeMove);
-    document.removeEventListener('mouseup', this.#onResizeEnd);
+    document.removeEventListener('pointermove', this.#onResizeMove);
+    document.removeEventListener('pointerup', this.#onResizeEnd);
 
     this.removeAttribute('data-resizing');
 
@@ -1395,8 +1418,8 @@ export class UITable extends UIElement {
   };
 
   #cleanupResize() {
-    document.removeEventListener('mousemove', this.#onResizeMove);
-    document.removeEventListener('mouseup', this.#onResizeEnd);
+    document.removeEventListener('pointermove', this.#onResizeMove);
+    document.removeEventListener('pointerup', this.#onResizeEnd);
     this.#resizeState = null;
   }
 

package/components/table/table.css

@@ -25,7 +25,11 @@
     --table-accent-default:           var(--a-primary);
     --table-fg-disabled-default:      var(--a-ui-text-disabled);
     --table-bg-default:               var(--a-bg);
-    --table-radius-default:           var(--a-radius-lg);
+    /* No default rounding — table-ui composes inside card-ui / drawer-ui
+       which own the surface rounding; doubly-rounded corners (table inside
+       card) look broken. Override per-instance via `--table-radius: …` if
+       table-ui sits standalone on the page. */
+    --table-radius-default:           0;
 
     /* ── Resize + pinned-column intrinsics ── */
     --table-resize-width-default:     var(--a-space-1);
@@ -103,11 +107,22 @@
   :scope {
     box-sizing: border-box;
     display: grid;
-    overflow-x: auto;
+    /* `overflow: auto` (both axes) — needed so position:sticky on the
+       header works relative to table-ui's own scroll viewport. Vertical
+       scroll only kicks in when consumer sets max-height; horizontal
+       only when grid-template-columns sum exceeds the container width.
+       Pre-fix: overflow-x: auto alone made table-ui the sticky-containing
+       block but with no vertical clip — wrapping in an outer max-height
+       div made the WHOLE table scroll (header included), defeating sticky. */
+    overflow: auto;
     font-size: var(--table-font-size, var(--table-font-size-default));
     color: var(--table-fg, var(--table-fg-default));
     background: var(--table-bg, var(--table-bg-default));
-    border: 1px solid var(--table-border, var(--table-border-default));
+    /* Use inset box-shadow as a faux border so the 1px chrome paints
+       inside the content box and doesn't shrink clientWidth — a real
+       `border: 1px` made grid content overflow by exactly 2 px on every
+       table (scrollbar appeared with nothing to scroll). */
+    box-shadow: inset 0 0 0 1px var(--table-border, var(--table-border-default));
     border-radius: var(--table-radius, var(--table-radius-default));
     position: relative;
     /* Own stacking context — sticky headers, pinned columns, and filter
@@ -119,7 +134,7 @@
 
   :scope[raw] {
     background: none;
-    border: none;
+    box-shadow: none;
     border-radius: 0;
   }
 
@@ -377,6 +392,18 @@
     bottom: 0;
     width: var(--table-resize-width, var(--table-resize-width-default));
     cursor: col-resize;
+    /* Sit above the next column header so pointer events hit the handle
+       (the handle is centered on the column boundary; without z-index the
+       neighbor's content wins the overlap and the resize never starts). */
+    z-index: 2;
+  }
+
+  /* Hide the resize handle on the last column — it overflows 2 px past the
+     table's right edge (handle centered on the column boundary; the last
+     column has no neighbor to resize against) and triggered a 2 px scrollbar
+     overhang on every table even with nothing to scroll. */
+  [role="row"] > [role="columnheader"]:last-child [data-resize-handle] {
+    display: none;
     z-index: 1;
   }
 

package/components/table-toolbar/table-toolbar.class.js

@@ -435,7 +435,9 @@ export class UITableToolbar extends UIElement {
     document.body.appendChild(panel);
 
     try { panel.showPopover(); } catch { /* popover API unavailable */ }
-    const cleanup = anchorPopover(btn, panel, { placement: 'bottom-start', gap: 4 });
+    // ADR-0034 Rule 2: filter/sort/columns panels (200-320px) >> icon trigger (~32px) → center.
+    // Placement is internal — not consumer-overridable on table-toolbar-ui.
+    const cleanup = anchorPopover(btn, panel, { placement: 'bottom', gap: 4 });
 
     this.#activePopover = { kind, btn, panel, cleanup };
 

package/components/tag/tag.a2ui.json

@@ -45,11 +45,12 @@
       "$ref": "common_types.json#/$defs/DynamicString"
     },
     "tone": {
-      "description": "Fill style — orthogonal to [variant]. Default (`solid`) for family\nvariants is a saturated bg with on-strong (near-white) text — the\nchip IS the state. Opt-out via `tone=\"muted\"` for a tinted bg with\nscheme-paired text (matches <badge-ui>'s default look) when the\nchip is metadata in a dense list rather than a status stamp. The\n`default` variant stays quiet chrome regardless of tone unless\n`tone=\"solid\"` is set explicitly (high-contrast neutral inverse).\n",
+      "description": "Fill style — orthogonal to [variant]. Three values:\n  - `solid` (default for family variants) — saturated bg + on-strong\n    (near-white) text. The chip IS the state.\n  - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s\n    default look. Use on metadata chips in dense lists where the\n    saturated default would compete for attention.\n  - `outline` — transparent bg + family-colored border + family-colored\n    text. The lightest visual weight; good in dense data tables or\n    faceted filter rows where multiple chips would otherwise compete.\nThe `default` variant (no family) stays quiet chrome regardless of\ntone unless `tone=\"solid\"` is set explicitly (high-contrast neutral\ninverse), or `tone=\"outline\"` (fg-muted text + subtle border).\n",
       "type": "string",
       "enum": [
         "solid",
-        "muted"
+        "muted",
+        "outline"
       ],
       "default": "solid"
     },

package/components/tag/tag.css

@@ -90,18 +90,12 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-fg-default: var(--a-success-fg);
   }
 
-  /* `--a-warning-bg` (= --a-warning-strong / -50) is too dark to read
-     against `--a-warning-fg` (= -text-strong / -10-shade), giving a
-     muddy brown-on-brown chip. Per the semantics.css comment "warning
-     is light-colored — text on warning fills should be dark", the
-     intent is bright-amber-bg + dark-text. The literal `-20-tint`
-     step is bright in BOTH schemes (independent of light-dark swap),
-     so warning solid keeps the same caution-tape look across modes.
-     The other family variants stay on `-bg` + `-fg` because their
-     -text-strong is `-05-tint` (near-white) which contrasts fine
-     against their saturated `-strong` bg. */
+  /* `--a-warning-bg` is the bright-amber step (semantics.css L3 redirect
+     to `-20-tint`) paired with `--a-warning-fg` (dark brown text) — the
+     canonical caution-tape pair. Pre-v0.6.36 this rule had a local
+     `-20-tint` override; that workaround moved to the token system. */
   :scope[variant="warning"] {
-    --tag-bg-default: var(--a-warning-20-tint);
+    --tag-bg-default: var(--a-warning-bg);
     --tag-fg-default: var(--a-warning-fg);
   }
 
@@ -149,6 +143,36 @@ tag-ui[removable]:not([disabled]):hover {
     --tag-fg-default: var(--a-bg);
   }
 
+  /* ── `[tone="outline"]` — transparent bg + family-colored border + text ──
+     The third common chip shape: no fill, just a ring + colored label.
+     Reads as "metadata that wants color recognition but minimum
+     visual weight" — good in dense data tables, faceted filter rows,
+     or anywhere multiple chips would compete if filled. */
+  :scope[tone="outline"] {
+    --tag-bg-default: transparent;
+  }
+  :scope[tone="outline"][variant="info"] {
+    --tag-fg-default:     var(--a-info-text);
+    --tag-border-default: var(--a-info-border);
+  }
+  :scope[tone="outline"][variant="success"] {
+    --tag-fg-default:     var(--a-success-text);
+    --tag-border-default: var(--a-success-border);
+  }
+  :scope[tone="outline"][variant="warning"] {
+    --tag-fg-default:     var(--a-warning-text);
+    --tag-border-default: var(--a-warning-border);
+  }
+  :scope[tone="outline"][variant="danger"] {
+    --tag-fg-default:     var(--a-danger-text);
+    --tag-border-default: var(--a-danger-border);
+  }
+  /* Outline on neutral (no family) — fg-muted text + subtle border. */
+  :scope[tone="outline"]:not([variant="info"]):not([variant="success"]):not([variant="warning"]):not([variant="danger"]) {
+    --tag-fg-default:     var(--a-fg-muted);
+    --tag-border-default: var(--a-border);
+  }
+
   /* Size handled by universal [size] attribute system. */
 
   /* hover rule moved outside @scope — see Safari 17.x bug note at top. */

package/components/tag/tag.d.ts

@@ -40,6 +40,20 @@ export class UITag extends UIElement {
   text: string;
   /** Tag label. Renderer routes this to the `text` attribute, rendered via CSS attr(text) on ::after. */
   textContent: string;
+  /** Fill style — orthogonal to [variant]. Three values:
+  - `solid` (default for family variants) — saturated bg + on-strong
+    (near-white) text. The chip IS the state.
+  - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s
+    default look. Use on metadata chips in dense lists where the
+    saturated default would compete for attention.
+  - `outline` — transparent bg + family-colored border + family-colored
+    text. The lightest visual weight; good in dense data tables or
+    faceted filter rows where multiple chips would otherwise compete.
+The `default` variant (no family) stays quiet chrome regardless of
+tone unless `tone="solid"` is set explicitly (high-contrast neutral
+inverse), or `tone="outline"` (fg-muted text + subtle border).
+ */
+  tone: 'solid' | 'muted' | 'outline';
   /** Semantic variant — `default | info | success | warning | danger`. */
   variant: 'default' | 'info' | 'success' | 'warning' | 'danger';
 

package/components/tag/tag.test.js

@@ -72,18 +72,13 @@ describe('tag-ui — variant defaults to solid fill', () => {
     expect(TAG_CSS).toMatch(block);
   });
 
-  it('[variant="warning"] uses the literal --a-warning-20-tint bg (NOT --a-warning-bg)', () => {
-    // The token-system convention `-bg` + `-fg` collapses for warning
-    // because `--a-warning-fg` is dark (`-10-shade`) but `--a-warning-bg`
-    // (= `-strong` = `-50`) is mid-tone amber — dark-on-mid is muddy.
-    // The literal `-20-tint` step is bright in both schemes, restoring
-    // the caution-tape look the semantics.css comment intends.
+  it('[variant="warning"] uses the canonical --a-warning-bg + --a-warning-fg pair', () => {
+    // v0.6.36 token-system fix: --a-warning-bg now redirects to
+    // --a-warning-20-tint at the L3 layer (semantics.css), so consumers
+    // can pair `-bg` + `-fg` cleanly without local overrides. The pair
+    // resolves to bright-amber-bg + dark-brown-text in both schemes.
     expect(TAG_CSS).toMatch(
-      /:scope\[variant="warning"\]\s*\{[^}]*--tag-bg-default:\s*var\(--a-warning-20-tint\)[^}]*--tag-fg-default:\s*var\(--a-warning-fg\)/s
-    );
-    // Negative — guard against accidental revert to the muddy pair.
-    expect(TAG_CSS).not.toMatch(
-      /:scope\[variant="warning"\]\s*\{[^}]*--tag-bg-default:\s*var\(--a-warning-bg\)/s
+      /:scope\[variant="warning"\]\s*\{[^}]*--tag-bg-default:\s*var\(--a-warning-bg\)[^}]*--tag-fg-default:\s*var\(--a-warning-fg\)/s
     );
   });
 });
@@ -118,3 +113,32 @@ describe('tag-ui — neutral default + explicit solid stamp', () => {
     );
   });
 });
+
+describe('tag-ui — [tone="outline"] strips fill + colors border', () => {
+  it('[tone="outline"] base rule sets bg to transparent', () => {
+    expect(TAG_CSS).toMatch(
+      /:scope\[tone="outline"\]\s*\{[^}]*--tag-bg-default:\s*transparent/s
+    );
+  });
+
+  it.each([
+    ['info'],
+    ['success'],
+    ['warning'],
+    ['danger'],
+  ])('[tone="outline"][variant="%s"] colors fg + border per family', (family) => {
+    const block = new RegExp(
+      `:scope\\[tone="outline"\\]\\[variant="${family}"\\]\\s*\\{[^}]*` +
+      `--tag-fg-default:\\s*var\\(--a-${family}-text\\)[^}]*` +
+      `--tag-border-default:\\s*var\\(--a-${family}-border\\)`,
+      's'
+    );
+    expect(TAG_CSS).toMatch(block);
+  });
+
+  it('[tone="outline"] on neutral uses --a-fg-muted text + --a-border ring', () => {
+    expect(TAG_CSS).toMatch(
+      /:scope\[tone="outline"\]:not\(\[variant="info"\]\)[\s\S]*?--tag-fg-default:\s*var\(--a-fg-muted\)[\s\S]*?--tag-border-default:\s*var\(--a-border\)/
+    );
+  });
+});

package/components/tag/tag.yaml

@@ -53,18 +53,24 @@ props:
       - danger
   tone:
     description: |
-      Fill style — orthogonal to [variant]. Default (`solid`) for family
-      variants is a saturated bg with on-strong (near-white) text — the
-      chip IS the state. Opt-out via `tone="muted"` for a tinted bg with
-      scheme-paired text (matches <badge-ui>'s default look) when the
-      chip is metadata in a dense list rather than a status stamp. The
-      `default` variant stays quiet chrome regardless of tone unless
-      `tone="solid"` is set explicitly (high-contrast neutral inverse).
+      Fill style — orthogonal to [variant]. Three values:
+        - `solid` (default for family variants) — saturated bg + on-strong
+          (near-white) text. The chip IS the state.
+        - `muted` — tinted bg with scheme-paired text. Matches <badge-ui>'s
+          default look. Use on metadata chips in dense lists where the
+          saturated default would compete for attention.
+        - `outline` — transparent bg + family-colored border + family-colored
+          text. The lightest visual weight; good in dense data tables or
+          faceted filter rows where multiple chips would otherwise compete.
+      The `default` variant (no family) stays quiet chrome regardless of
+      tone unless `tone="solid"` is set explicitly (high-contrast neutral
+      inverse), or `tone="outline"` (fg-muted text + subtle border).
     type: string
     default: solid
     enum:
       - solid
       - muted
+      - outline
 events:
   remove:
     description: Fired when the dismiss button is activated.

package/components/toast/toast.class.js

@@ -78,10 +78,14 @@ export class UIToast extends UIElement {
    * @param {string} [opts.variant='info']  — `error` aliases to `danger`.
    * @param {number} [opts.duration=4000]
    * @param {string} [opts.position='bottom-right']
+   * @param {boolean} [opts.dismissible]  Force-show the close button on auto-
+   *                                fade toasts (sticky toasts always show it).
+   * @param {string} [opts.action]  Optional action button label (e.g. 'Undo').
+   * @param {function} [opts.onAction]  Action button click handler.
    * @returns {{id:string|null, dismiss:function, update:function}}  FeedHandle.
    */
   static show(opts = {}) {
-    const { text, variant = 'info', duration = 4000, position = 'bottom-right' } = opts;
+    const { text, variant = 'info', position = 'bottom-right', action, onAction } = opts;
     // §224 (v0.5.9, FEEDBACK-10 §2): mark the spawned feed container so
     // DOM-query consumers (Playwright, devtools, instrumentation) can
     // distinguish toast-spawned <feed-ui> from user-authored ones. The marker
@@ -91,11 +95,15 @@ export class UIToast extends UIElement {
     if (container && !container.hasAttribute('data-spawned-by')) {
       container.setAttribute('data-spawned-by', 'toast');
     }
-    return UIFeed.post({
+    const payload = {
       text,
       variant: variant === 'error' ? 'danger' : variant,
-      duration,
       position,
-    });
+    };
+    if ('duration' in opts) payload.duration = opts.duration;
+    if ('dismissible' in opts) payload.dismissible = !!opts.dismissible;
+    if (action) payload.action = action;
+    if (typeof onAction === 'function') payload.onAction = onAction;
+    return UIFeed.post(payload);
   }
 }