@adia-ai/web-components 0.8.31 → 0.8.32

package/components/stat/stat.js

@@ -32,9 +32,15 @@ class UIStat extends UIElement {
 
   static template = () => null;
 
+  // Trend arrows the class stamps directly (issue 805) — consumers calling
+  // installIconLoaders() manually need these two names present.
+  static requiredIcons = ['arrow-up', 'arrow-down'];
+
   #valueEl = null;
   #labelEl = null;
   #changeEl = null;
+  #changeIconEl = null;
+  #changeTextEl = null;
   #iconEl = null;
 
   connected() {
@@ -59,6 +65,28 @@ class UIStat extends UIElement {
       this.appendChild(this.#changeEl);
     }
 
+    // Trend arrow (issue 805): a real icon-ui child instead of a CSS ::before
+    // unicode triangle, so the delta indicator rides the Phosphor icon
+    // system (contrast, weight, RTL) like every other icon on the page.
+    // No `slot="icon"` attribute on this child — that value is reserved for
+    // stat's own outer `[slot="icon"]` region, and an ancestor's `[slot="icon"]`
+    // descendant selector would otherwise leak margin/positioning onto it
+    // (issue 809, PR 810 shape). `[data-trend-icon]` is scoped to stat's own CSS.
+    this.#changeIconEl = this.#changeEl.querySelector(':scope > icon-ui[data-trend-icon]');
+    if (!this.#changeIconEl) {
+      this.#changeIconEl = document.createElement('icon-ui');
+      this.#changeIconEl.setAttribute('data-trend-icon', '');
+      this.#changeIconEl.hidden = true;
+      this.#changeEl.appendChild(this.#changeIconEl);
+    }
+
+    this.#changeTextEl = this.#changeEl.querySelector(':scope > [data-trend-text]');
+    if (!this.#changeTextEl) {
+      this.#changeTextEl = document.createElement('span');
+      this.#changeTextEl.setAttribute('data-trend-text', '');
+      this.#changeEl.appendChild(this.#changeTextEl);
+    }
+
     this.#iconEl = this.querySelector(':scope > [slot="icon"]');
     if (!this.#iconEl) {
       this.#iconEl = document.createElement('icon-ui');
@@ -83,6 +111,9 @@ class UIStat extends UIElement {
       // value+change visual mass without being so wide as to look like text.
       this.#valueEl.textContent = '';
       this.#valueEl.innerHTML = '<skeleton-ui width="60%" height="2em" radius="sm"></skeleton-ui>';
+      // Skeleton replaces the trend icon + text children wholesale; the
+      // non-loading branch below detects the detached refs (parentNode
+      // check) and re-inserts them once real data arrives.
       this.#changeEl.textContent = '';
       this.#changeEl.innerHTML = '<skeleton-ui width="40%" height="1em" radius="sm"></skeleton-ui>';
       this.#changeEl.hidden = false;
@@ -103,7 +134,39 @@ class UIStat extends UIElement {
 
     // Change badge
     if (this.change) {
-      this.#changeEl.textContent = this.change;
+      // Contract: the generated icon+text pair owns [slot="change"]'s
+      // content — same "consumer content is overwritten" rule #valueEl /
+      // #labelEl already apply (their textContent is replaced every render
+      // regardless of what markup a consumer authored there). #changeEl
+      // additionally needs a specific two-node SHAPE (icon then text), not
+      // just overwritten text, so any deviation from that exact shape is
+      // normalized before writing: a consumer-authored `<stat-ui
+      // change="…"><span slot="change">stale</span></stat-ui>` gets its
+      // stale content cleared and the generated pair installed; loading's
+      // skeleton wipe (above) detaches the pair the same way and is
+      // recovered by the same branch; a disconnect/reconnect cycle that
+      // leaves an orphaned skeleton behind is also caught here (fresh
+      // #changeIconEl/#changeTextEl instances from the new connected()
+      // never match old stray children).
+      const hasOnlyTrendChildren =
+        this.#changeEl.childNodes.length === 2 &&
+        this.#changeEl.firstChild === this.#changeIconEl &&
+        this.#changeEl.lastChild === this.#changeTextEl;
+      if (!hasOnlyTrendChildren) {
+        this.#changeEl.textContent = '';
+        this.#changeEl.appendChild(this.#changeIconEl);
+        this.#changeEl.appendChild(this.#changeTextEl);
+      }
+      this.#changeTextEl.textContent = this.change;
+      if (this.trend === 'up') {
+        this.#changeIconEl.setAttribute('name', 'arrow-up');
+        this.#changeIconEl.hidden = false;
+      } else if (this.trend === 'down') {
+        this.#changeIconEl.setAttribute('name', 'arrow-down');
+        this.#changeIconEl.hidden = false;
+      } else {
+        this.#changeIconEl.hidden = true;
+      }
       this.#changeEl.hidden = false;
     } else {
       this.#changeEl.hidden = true;
@@ -122,6 +185,8 @@ class UIStat extends UIElement {
     this.#valueEl = null;
     this.#labelEl = null;
     this.#changeEl = null;
+    this.#changeIconEl = null;
+    this.#changeTextEl = null;
     this.#iconEl = null;
   }
 }

package/components/stat/stat.yaml

@@ -112,6 +112,9 @@ tokens:
     description: Font size for the primary value
   --stat-value-weight:
     description: Font weight for the primary value
+requiredIcons:
+  - arrow-up
+  - arrow-down
 a2ui:
   rules:
     - rule: 'Use for prominent metric/KPI displays inside dashboard cards. Value + label + optional delta indicator.'

package/components/stepper/stepper-item.a2ui.json

@@ -21,6 +21,11 @@
     "component": {
       "const": "StepperItem"
     },
+    "disabled": {
+      "description": "S2's phase-gating mechanism (gh#711 S1 review). Skipped in the parent's [interactive] roving tabindex/arrow order, unclickable, carries aria-disabled. Independent of [status] — a completed or upcoming step can still be disabled for a different reason (e.g. the visit phase hasn't unlocked it yet).",
+      "type": "boolean",
+      "default": false
+    },
     "icon": {
       "description": "Optional leading Phosphor icon name; overrides the auto-stamped numeric badge.",
       "type": "string",

package/components/stepper/stepper-item.yaml

@@ -39,6 +39,15 @@ props:
       - active
       - completed
       - error
+  disabled:
+    description: >-
+      S2's phase-gating mechanism (gh#711 S1 review). Skipped in the
+      parent's [interactive] roving tabindex/arrow order, unclickable,
+      carries aria-disabled. Independent of [status] — a completed or
+      upcoming step can still be disabled for a different reason (e.g.
+      the visit phase hasn't unlocked it yet).
+    type: boolean
+    default: false
 slots:
   label:
     description: Custom label content; falls through to `[text]` prop if not slotted.
@@ -73,3 +82,5 @@ a2ui:
       reason: 'Parent owns step progression.'
     - rule: 'For chronological events (no completion semantics) use <timeline-item-ui> instead.'
       reason: 'Stepper is process; timeline is history.'
+    - rule: 'Set [disabled] to phase-gate a step out of click/keyboard reach without changing [status].'
+      reason: 'gh#711 S1 review — S2 uses this to lock steps the current visit phase hasn''t unlocked.'

package/components/stepper/stepper.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Stepper.json",
   "title": "Stepper",
-  "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.",
+  "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead. Add [interactive] to opt into click-to-navigate + roving- tabindex keyboard (arrow keys / Home / End) — the host still owns whether navigation is permitted: listen for the cancelable [step-request] event and call preventDefault() to veto a step before it lands, or set [disabled] on a stepper-item-ui to phase-gate it out of reach entirely.",
   "type": "object",
   "allOf": [
     {
@@ -16,6 +16,11 @@
     "component": {
       "const": "Stepper"
     },
+    "interactive": {
+      "description": "Opt into click-to-navigate + roving-tabindex keyboard nav (arrow keys / Home / End / Enter / Space). Absent by default — a bare stepper is a read-only progress display, not a nav control (gh#711 S1).",
+      "type": "boolean",
+      "default": false
+    },
     "orientation": {
       "description": "horizontal | vertical",
       "type": "string",
@@ -37,12 +42,40 @@
     "composes": [
       "icon-ui"
     ],
-    "events": {},
+    "events": {
+      "change": {
+        "description": "Fired after a click or keyboard navigation changes [step] (i.e. only when the preceding [step-request] wasn't vetoed). Only fires when [interactive] is set.",
+        "detail": {
+          "step": {
+            "description": "New current step index.",
+            "type": "number"
+          }
+        }
+      },
+      "step-request": {
+        "description": "Cancelable — fires BEFORE [step] mutates, on a click or keyboard navigation. call preventDefault() to veto: the step does not change, [change] does not fire, and focus/roving-tabindex stay exactly where they were. A host that never listens for this event keeps the pre-veto uncontrolled behavior unchanged (gh#711 S1 review).",
+        "detail": {
+          "previous": {
+            "description": "The current step index before this navigation.",
+            "type": "number"
+          },
+          "step": {
+            "description": "The step index the navigation would land on if not vetoed.",
+            "type": "number"
+          }
+        }
+      }
+    },
     "examples": [
       {
         "description": "Three-step wizard",
         "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Stepper\",\n    \"step\": 1,\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Account\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Details\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Review\"\n  }\n]",
         "name": "basic"
+      },
+      {
+        "description": "Click/keyboard-navigable stepper — host allows jumping between steps.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Stepper\",\n    \"step\": 1,\n    \"interactive\": true,\n    \"children\": [\n      \"s1\",\n      \"s2\",\n      \"s3\"\n    ]\n  },\n  {\n    \"id\": \"s1\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Account\"\n  },\n  {\n    \"id\": \"s2\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Details\"\n  },\n  {\n    \"id\": \"s3\",\n    \"component\": \"StepperItem\",\n    \"text\": \"Review\"\n  }\n]",
+        "name": "interactive"
       }
     ],
     "keywords": [
@@ -51,7 +84,9 @@
       "steps",
       "process",
       "onboarding",
-      "multi-step"
+      "multi-step",
+      "interactive",
+      "click-to-navigate"
     ],
     "name": "UIStepper",
     "related": [

package/components/stepper/stepper.class.js

@@ -28,21 +28,104 @@
  *
  *   el.next(); el.prev(); el.goTo(2);
  *
+ *   <!-- Host-controlled click-to-navigate + keyboard (gh#711 S1) -->
+ *   <stepper-ui step="1" interactive>
+ *     <stepper-item-ui text="Account"></stepper-item-ui>
+ *     <stepper-item-ui text="Details" disabled></stepper-item-ui>
+ *     ...
+ *   </stepper-ui>
+ *
+ *   <!-- Veto a navigation before it lands (gh#711 S1 review) -->
+ *   el.addEventListener('step-request', (e) => {
+ *     if (!phaseAllows(e.detail.step)) e.preventDefault();
+ *   });
+ *
  * Attributes:
  *   step        — current step index (0-based)
  *   orientation — horizontal (default) | vertical
+ *   interactive — opt-in click-to-navigate + roving-tabindex keyboard
+ *                 nav (arrow keys / Home / End). Absent by default —
+ *                 a bare stepper is a read-only progress display.
+ *
+ * Events (interactive only):
+ *   step-request — cancelable, fires BEFORE `step` mutates.
+ *                  { detail: { step, previous } }. `preventDefault()`
+ *                  vetoes the navigation: no mutation, no `change`,
+ *                  focus/roving state unaffected. A host that never
+ *                  listens keeps today's uncontrolled behavior —
+ *                  this is additive, not a breaking change.
+ *   change       — { detail: { step } } — fires AFTER a click or
+ *                  keyboard navigation changes `step` (i.e. only if
+ *                  `step-request` wasn't vetoed). The host reacts;
+ *                  the stepper does not itself drive any other UI.
  */
 
 import { UIElement } from '../../core/element.js';
 
+// gh#736 — during static innerHTML parsing, a stepper-item-ui's attribute
+// list is on the DOM node the instant the parser inserts it, but its
+// `disabled` PROPERTY mirror only lands once its own attributeChangedCallback
+// replay has run — which some environments (this repo's happy-dom test env,
+// certain upgrade orderings) don't guarantee has happened yet by the time the
+// PARENT's connectedCallback (and its first render()) fires, since children
+// connect after their parent in tree order. Reading the attribute directly
+// is synchronous with parsing and never lags, so it's the race-proof source
+// of truth; the property read stays primary for the (overwhelmingly common)
+// already-upgraded case.
+function isDisabled(item) {
+  return item.disabled || item.hasAttribute('disabled');
+}
+
 export class UIStepper extends UIElement {
   static properties = {
-    step:        { type: Number, default: 0,            reflect: true },
-    orientation: { type: String, default: 'horizontal', reflect: true },
+    step:        { type: Number,  default: 0,            reflect: true },
+    orientation: { type: String,  default: 'horizontal', reflect: true },
+    interactive: { type: Boolean, default: false,         reflect: true },
   };
 
   static template = () => null;
 
+  // gh#736 — two related child-reactivity gaps, one observer:
+  //   1. Upgrade-order race: during static innerHTML parsing this element's
+  //      connectedCallback (and its first synchronous render()) can fire
+  //      BEFORE its stepper-item-ui children are even appended as DOM
+  //      children (confirmed: this element's own render() sees zero items
+  //      on that first pass) — the isDisabled() hasAttribute fallback in
+  //      render() alone can't help when there's nothing to iterate yet.
+  //      Watching `childList` catches children landing a tick later and
+  //      re-renders once they're actually there.
+  //   2. A child's [disabled] flip after mount must re-render this parent's
+  //      roving-tabindex/aria-disabled computation without the host
+  //      manually poking render() (nav-group-ui's gh#501 idiom: a scoped
+  //      MutationObserver, not a signal, since `disabled` lives on
+  //      descendant DOM, not this element's own reactive properties).
+  // attributeFilter is narrow (['disabled']) and render() never writes
+  // childList or that attribute itself (it only reads `disabled`), so the
+  // observer can't feed back into its own render.
+  #onChildMutation = () => this.render();
+  #childObserver = null;
+
+  connected() {
+    this.addEventListener('click', this.#handleClick);
+    this.addEventListener('keydown', this.#handleKeydown);
+    if (!this.#childObserver) {
+      this.#childObserver = new MutationObserver(this.#onChildMutation);
+      this.#childObserver.observe(this, {
+        childList: true,
+        subtree: true,
+        attributes: true,
+        attributeFilter: ['disabled'],
+      });
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#handleClick);
+    this.removeEventListener('keydown', this.#handleKeydown);
+    this.#childObserver?.disconnect();
+    this.#childObserver = null;
+  }
+
   render() {
     const items = [...this.querySelectorAll('stepper-item-ui')];
 
@@ -64,7 +147,40 @@ export class UIStepper extends UIElement {
       } else {
         item.setAttribute('status', 'idle');
       }
+
+      // Roving tabindex + button semantics only when the host opts
+      // in via [interactive] — a bare stepper stays a non-focusable
+      // progress display (Rule: absent attribute is the default).
+      if (this.interactive) {
+        item.setAttribute('role', 'button');
+        if (i === this.step) item.setAttribute('aria-current', 'step');
+        else item.removeAttribute('aria-current');
+      } else {
+        item.removeAttribute('role');
+        item.removeAttribute('tabindex');
+        item.removeAttribute('aria-current');
+        item.removeAttribute('aria-disabled');
+      }
     });
+
+    // Disabled items (S2's phase-gating mechanism) never take the
+    // roving tabindex stop and are never clickable/keyboard-reachable
+    // — an author-set [disabled] on a stepper-item-ui always wins,
+    // whatever [status] the parent computed for it above.
+    if (this.interactive) {
+      const enabled = items.filter((item) => !isDisabled(item));
+      const current = items[this.step];
+      const focusTarget = current && !isDisabled(current) ? current : enabled[0];
+      for (const item of items) {
+        if (isDisabled(item)) {
+          item.setAttribute('aria-disabled', 'true');
+          item.removeAttribute('tabindex');
+        } else {
+          item.removeAttribute('aria-disabled');
+          item.setAttribute('tabindex', item === focusTarget ? '0' : '-1');
+        }
+      }
+    }
   }
 
   next() {
@@ -80,6 +196,82 @@ export class UIStepper extends UIElement {
     const max = this.querySelectorAll('stepper-item-ui').length - 1;
     this.step = Math.max(0, Math.min(index, max));
   }
+
+  get #items() {
+    return [...this.querySelectorAll('stepper-item-ui')];
+  }
+
+  get #enabledItems() {
+    return this.#items.filter((item) => !isDisabled(item));
+  }
+
+  /** @returns {boolean} true if the navigation landed, false if vetoed or a no-op. */
+  #select(index) {
+    const items = this.#items;
+    const max = items.length - 1;
+    const next = Math.max(0, Math.min(index, max));
+    if (next === this.step || (items[next] && isDisabled(items[next]))) return false;
+
+    // Pre-mutation cancelable event (gh#711 S1 review) — the host
+    // gets a veto BEFORE `step` changes. `preventDefault()` stops
+    // the mutation and the `change` event; focus/roving are
+    // untouched either way. A host that never listens sees no
+    // difference from before this event existed.
+    const previous = this.step;
+    const proceed = this.dispatchEvent(new CustomEvent('step-request', {
+      bubbles: true,
+      cancelable: true,
+      detail: { step: next, previous },
+    }));
+    if (!proceed) return false; // vetoed
+
+    this.step = next;
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { step: this.step } }));
+    return true;
+  }
+
+  #handleClick = (e) => {
+    if (!this.interactive) return;
+    const item = e.target.closest('stepper-item-ui');
+    if (!item || !this.contains(item) || isDisabled(item)) return;
+    const index = this.#items.indexOf(item);
+    if (index < 0) return;
+    this.#select(index);
+  };
+
+  #handleKeydown = (e) => {
+    if (!this.interactive) return;
+    const item = e.target.closest('stepper-item-ui');
+    if (!item || !this.contains(item)) return;
+
+    // Disabled items are unreachable (no tabindex) and skipped in the
+    // arrow/Home/End order — the roving set is the enabled subset.
+    const items = this.#enabledItems;
+    const idx = items.indexOf(item);
+    if (idx < 0) return;
+
+    const isVertical = this.orientation === 'vertical';
+    const nextKey = isVertical ? 'ArrowDown' : 'ArrowRight';
+    const prevKey = isVertical ? 'ArrowUp' : 'ArrowLeft';
+
+    let next;
+    switch (e.key) {
+      case nextKey:    next = idx < items.length - 1 ? idx + 1 : 0; break; // wraps to first
+      case prevKey:    next = idx > 0 ? idx - 1 : items.length - 1; break; // wraps to last
+      case 'Home':     next = 0; break;
+      case 'End':      next = items.length - 1; break;
+      case 'Enter':
+      case ' ':        e.preventDefault(); this.#select(this.#items.indexOf(item)); return;
+      default: return;
+    }
+
+    e.preventDefault();
+    const target = items[next];
+    // Only move roving focus if the navigation actually landed — a
+    // veto leaves focus (and the tabindex roving stop) exactly where
+    // it was, per the review's "focus/roving unaffected" contract.
+    if (this.#select(this.#items.indexOf(target))) target.focus();
+  };
 }
 
 export class UIStepperItem extends UIElement {
@@ -92,6 +284,11 @@ export class UIStepperItem extends UIElement {
     // values prevent the `active && completed` footgun the prior multi-
     // Boolean shape allowed.
     status:      { type: String,  default: 'idle', reflect: true },
+    // S2's phase-gating mechanism (gh#711 S1 review) — a disabled step
+    // is skipped in [interactive] roving tabindex/arrow order, is
+    // unclickable, and carries aria-disabled. Independent of `status`:
+    // a completed or upcoming step can be disabled for a different reason.
+    disabled:    { type: Boolean, default: false,   reflect: true },
   };
 
   static template = () => null;

package/components/stepper/stepper.css

@@ -253,6 +253,36 @@
   :scope [slot]:empty {
     display: none;
   }
+
+  /* Interactive (click-to-navigate) — host opts in via [interactive]
+     on the parent; absent by default (Rule: bare stepper is a
+     read-only progress display, not a nav control). */
+  stepper-ui[interactive] > :scope {
+    cursor: pointer;
+    outline: none;
+  }
+
+  stepper-ui[interactive] > :scope:focus-visible::after {
+    outline: 2px solid var(--md-sys-color-primary);
+    outline-offset: 2px;
+  }
+
+  /* Disabled (S2's phase-gating mechanism) — never clickable, never
+     the roving-tabindex stop; visually recedes regardless of status. */
+  stepper-ui[interactive] > :scope[disabled] {
+    cursor: not-allowed;
+  }
+
+  :scope[disabled]::after,
+  :scope[disabled] [slot="icon"] {
+    opacity: 0.5;
+  }
+
+  :scope[disabled] [slot="label"],
+  :scope[disabled] [slot="description"] {
+    color: var(--stepper-item-pending-fg);
+    opacity: 0.5;
+  }
 }
 
 /* ── Vertical orientation rules — must reach across stepper-ui →

package/components/stepper/stepper.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<stepper-ui>` — Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead.
+ * `<stepper-ui>` — Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead. Add [interactive] to opt into click-to-navigate + roving- tabindex keyboard (arrow keys / Home / End) — the host still owns whether navigation is permitted: listen for the cancelable [step-request] event and call preventDefault() to veto a step before it lands, or set [disabled] on a stepper-item-ui to phase-gate it out of reach entirely.
  *
  * @see https://ui-kit.exe.xyz/site/components/stepper
  *
@@ -12,16 +12,43 @@
 
 import { UIElement } from '../../core/element.js';
 
+export interface StepperChangeEventDetail {
+  /** New current step index. */
+  step: number;
+}
+
+export type StepperChangeEvent = CustomEvent<StepperChangeEventDetail>;
+export interface StepperStepRequestEventDetail {
+  /** The current step index before this navigation. */
+  previous: number;
+  /** The step index the navigation would land on if not vetoed. */
+  step: number;
+}
+
+export type StepperStepRequestEvent = CustomEvent<StepperStepRequestEventDetail>;
+
 export class UIStepper extends UIElement {
+  /** Opt into click-to-navigate + roving-tabindex keyboard nav (arrow keys / Home / End / Enter / Space). Absent by default — a bare stepper is a read-only progress display, not a nav control (gh#711 S1). */
+  interactive: boolean;
   /** horizontal | vertical */
   orientation: string;
   /** Current step index (0-based). */
   step: number;
+
+  addEventListener(type: 'change', listener: (ev: StepperChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'step-request', listener: (ev: StepperStepRequestEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIStepper, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
 }
 
 export class UIStepperItem extends UIElement {
   /** Secondary description line under the label. */
   description: string;
+  /** S2's phase-gating mechanism (gh#711 S1 review). Skipped in the parent's [interactive] roving tabindex/arrow order, unclickable, carries aria-disabled. Independent of [status] — a completed or upcoming step can still be disabled for a different reason (e.g. the visit phase hasn't unlocked it yet). */
+  disabled: boolean;
   /** Optional leading Phosphor icon name; overrides the auto-stamped numeric badge. */
   icon: string;
   /** Canonical stage-progress state. Mutually exclusive (prevents the

package/components/stepper/stepper.yaml

@@ -12,7 +12,12 @@ description: >-
   complete/current/upcoming states automatically. Renders horizontally as
   a labeled step bar with connectors. Use for multi-step forms,
   onboarding, or pipelines; for read-only event history use <timeline-ui>
-  instead.
+  instead. Add [interactive] to opt into click-to-navigate + roving-
+  tabindex keyboard (arrow keys / Home / End) — the host still owns
+  whether navigation is permitted: listen for the cancelable
+  [step-request] event and call preventDefault() to veto a step before
+  it lands, or set [disabled] on a stepper-item-ui to phase-gate it
+  out of reach entirely.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -26,7 +31,39 @@ props:
     description: Current step index (0-based).
     type: number
     default: 0
-events: {}
+  interactive:
+    description: >-
+      Opt into click-to-navigate + roving-tabindex keyboard nav
+      (arrow keys / Home / End / Enter / Space). Absent by default —
+      a bare stepper is a read-only progress display, not a nav
+      control (gh#711 S1).
+    type: boolean
+    default: false
+events:
+  step-request:
+    description: >-
+      Cancelable — fires BEFORE [step] mutates, on a click or keyboard
+      navigation. call preventDefault() to veto: the step does not
+      change, [change] does not fire, and focus/roving-tabindex stay
+      exactly where they were. A host that never listens for this
+      event keeps the pre-veto uncontrolled behavior unchanged
+      (gh#711 S1 review).
+    detail:
+      step:
+        type: number
+        description: The step index the navigation would land on if not vetoed.
+      previous:
+        type: number
+        description: The current step index before this navigation.
+  change:
+    description: >-
+      Fired after a click or keyboard navigation changes [step] (i.e.
+      only when the preceding [step-request] wasn't vetoed).
+      Only fires when [interactive] is set.
+    detail:
+      step:
+        type: number
+        description: New current step index.
 slots:
   default:
     description: "Default slot — primary child content."
@@ -43,6 +80,10 @@ a2ui:
       reason: 'Surface examples.'
     - rule: 'For read-only event history use <timeline-ui>; stepper requires forward progress semantics.'
       reason: 'Decision rule vs timeline.'
+    - rule: 'Add [interactive] only when the host permits jumping to a step out of order; leave absent for a linear wizard the host advances programmatically.'
+      reason: 'Click-to-navigate is host-controlled, not automatic (gh#711 S1).'
+    - rule: 'Listen for [step-request] and call preventDefault() to veto a navigation conditionally (e.g. block a phase the app has not unlocked); set [disabled] on a stepper-item-ui to phase-gate it out of reach unconditionally.'
+      reason: 'Two host-controlled gates at different granularities (gh#711 S1 review).'
 anti_patterns: []
 examples:
   - name: basic
@@ -75,6 +116,37 @@ examples:
           "text": "Review"
         }
       ]
+  - name: interactive
+    description: Click/keyboard-navigable stepper — host allows jumping between steps.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Stepper",
+          "step": 1,
+          "interactive": true,
+          "children": [
+            "s1",
+            "s2",
+            "s3"
+          ]
+        },
+        {
+          "id": "s1",
+          "component": "StepperItem",
+          "text": "Account"
+        },
+        {
+          "id": "s2",
+          "component": "StepperItem",
+          "text": "Details"
+        },
+        {
+          "id": "s3",
+          "component": "StepperItem",
+          "text": "Review"
+        }
+      ]
 keywords:
   - stepper
   - wizard
@@ -82,6 +154,8 @@ keywords:
   - process
   - onboarding
   - multi-step
+  - interactive
+  - click-to-navigate
 synonyms:
   timeline-ui mode=steps: stepper-ui
 related: