@adia-ai/web-components 0.8.42 → 0.8.44

package/components/table-toolbar/table-toolbar.yaml

@@ -6,16 +6,20 @@ component: TableToolbar
 category: agent
 version: 1
 description: >-
-  Header / companion bar for a sibling table-ui. Renders title + count badge,
-  filter / sort / columns popovers, and a search input — all wired to the
-  target table via an [for] id-ref. Modeled on chart-legend-ui's [for] binding
-  pattern. Drop next to (or above) any table-ui to add the standard data-grid
-  toolbar without re-implementing search, filter, sort, or column visibility.
-  Filter rows auto-pick a primitive per column: ≤ 50 distinct values → multi-
-  select (searchable when ≥ 12 options), id-like keys → free-text contains. The
-  column descriptor's `filter` field overrides the auto-detect: `'select'`
-  forces multi-select even on high-cardinality columns; `'text'` forces a
-  contains input even on small enums.
+  Header / companion bar for a sibling table-ui. Renders an optional leading
+  [slot="scope"] region, title + count badge, an optional "Showing X–Y of N"
+  range summary, filter / sort / columns popovers, a search input, an
+  optional [slot="actions-leading"] region, an optional page-size select,
+  and a trailing [slot="actions"] region — all wired to the target table via
+  an [for] id-ref. Modeled on chart-legend-ui's [for] binding pattern. Drop
+  next to (or above) any table-ui to add the standard data-grid toolbar
+  without re-implementing search, filter, sort, column visibility, or
+  pagination summary/page-size. Filter rows auto-pick a primitive per
+  column: ≤ 50 distinct values → multi-select (searchable when ≥ 12
+  options), id-like keys → free-text contains. The column descriptor's
+  `filter` field overrides the auto-detect: `'select'` forces multi-select
+  even on high-cardinality columns; `'text'` forces a contains input even on
+  small enums.
 # Per ADR-0027 — primitives that programmatically create other primitives
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
@@ -26,6 +30,7 @@ composes:
   - field-ui
   - select-ui
   - input-ui
+  - menu-ui
   - menu-item-ui
   - icon-ui
   - check-ui
@@ -43,6 +48,63 @@ props:
     description: Optional count badge value shown next to the title. When unset, falls back to the row count of the bound table.
     type: string
     default: ""
+  rangeStart:
+    description: >-
+      1-indexed first row number of the current page, for the "Showing X–Y
+      of N" range summary (e.g. `1` in "Showing 1–25 of 320"). Renders
+      alongside — never in place of — [text]/[count]; the range summary is
+      its own cluster, independent of the title cluster. All three of
+      rangeStart/rangeEnd/rangeTotal must be set (> 0) for the summary to
+      render; omit all three (the default) to opt out entirely.
+    type: number
+    default: 0
+    reflect: true
+    attribute: range-start
+  rangeEnd:
+    description: >-
+      1-indexed last row number of the current page, for the range summary
+      (e.g. `25` in "Showing 1–25 of 320"). See rangeStart.
+    type: number
+    default: 0
+    reflect: true
+    attribute: range-end
+  rangeTotal:
+    description: >-
+      Total row count across all pages, for the range summary (e.g. `320`
+      in "Showing 1–25 of 320"). Distinct from pagination-ui's `total`
+      (total PAGES) — this is total ROWS; deliberately not spelled `total`
+      to avoid that cross-sibling name collision (ADR-0063 B5). See
+      rangeStart.
+    type: number
+    default: 0
+    reflect: true
+    attribute: range-total
+  pageSize:
+    description: >-
+      Current rows-per-page value, shown as the selected option in the
+      page-size select. Falls back to the first entry of pageSizeOptions
+      when unset (0) or not present among the options. Applied directly to
+      the bound table's own [paginate] prop (rows-per-page), the same way
+      filter/sort/columns changes are applied to the target — mirror this
+      prop only to reflect state to URL / persistence / analytics.
+    type: number
+    default: 0
+    reflect: true
+    attribute: page-size
+  pageSizeOptions:
+    description: >-
+      Rows-per-page choices rendered as `<option>`s in the page-size select
+      (e.g. `[10, 25, 50, 100]`). JS property (`.pageSizeOptions = [...]`),
+      or a declarative JSON-array `page-size-options="[10,25,50]"` attribute
+      hydrated once at connect — the same dynamic-array pattern table-ui's
+      own `columns`/`data` props use. Empty (the default) hides the
+      page-size select entirely — additive opt-in, no footprint on existing
+      consumers.
+    type: array
+    items:
+      type: number
+    default: []
+    dynamic: true  # JS-set collection prop with a custom setter — deliberately not in static properties
   noFilter:
     description: Hide the Filter popover button. Filter is shown by default; set to opt out.
     type: boolean
@@ -67,6 +129,53 @@ props:
     default: false
     reflect: true
     attribute: no-search
+  stage:
+    description: >-
+      Explicit compaction-stage override (ADR-0076). Unset (the default,
+      empty string) means auto-snap: the toolbar's own inline-size
+      container query picks the nearest stage from its live width against
+      the three --table-toolbar-bp-* breakpoints, snapping discretely,
+      never interpolating. Setting stage explicitly pins that stage's
+      rendering regardless of the container's actual width — overriding
+      the container query, mirroring chart-ui's ratio override shape.
+      Primary use: visual-eval fixtures that need a deterministic stage
+      without resizing a real container, and a consumer embedding the
+      toolbar inside a known-narrow panel who wants to skip auto-detection
+      entirely. All four stages' CSS is now live (ADR-0076): search-tight
+      steps the search field down (step 2); icon-only drops control labels
+      and compacts/hides the range summary (steps 3+4); overflow collapses
+      Filter/Sort/Columns into one "More" trigger routed through the same
+      menu-ui/menu-item-ui pattern used elsewhere in the corpus (step 5).
+      The resolved stage — the pin if set, otherwise the live width
+      classification — also reflects onto the host as
+      `data-stage-resolved` (step 7, informational only, mirrors chart-ui's
+      `data-ratio-resolved` convention — never drives table-toolbar's own
+      rendering, which stays 100% CSS-driven).
+    type: string
+    default: ""
+    enum:
+      - ""
+      - full
+      - search-tight
+      - icon-only
+      - overflow
+    reflect: true
+  chromeOnly:
+    description: >-
+      Suppress all four native controls/search at once (filter, sort,
+      columns, search) as additive sugar over noFilter/noSort/noColumns/
+      noSearch (ADR-0076, ADIA2-9123). Precedence is pure, absolute OR —
+      while set, all four stay off regardless of any individual no-*
+      attribute's own value, with no partial re-enable path; to
+      re-enable one control, remove chrome-only entirely and set the
+      other three no-* attributes explicitly instead. The four granular
+      attributes are not deprecated or removed — they remain the
+      independently-addressable shipped API; chrome-only never replaces
+      them, it's a convenience preset on top.
+    type: boolean
+    default: false
+    reflect: true
+    attribute: chrome-only
   placeholder:
     description: Placeholder text for the search input.
     type: string
@@ -88,9 +197,38 @@ events:
     description: "Sort state changed. Detail: { sortState }."
   columns-change:
     description: "Column visibility changed. Detail: { hiddenColumns }."
+  page-size-change:
+    description: "Page-size select changed. Detail: { pageSize }."
 slots:
+  scope:
+    description: Leading region rendered BEFORE the [text]/[count] title cluster — e.g. a scope/view-switcher menu (an org's teams, a saved view). Positioning is CSS by DOM order, mirroring how [slot="actions"] is a real, author-fillable insertion point rather than template-stamped content.
+  empty:
+    description: >-
+      Renders in place of the range-summary text — the same [data-summary]
+      region — when [range-total] is EXPLICITLY present and equal to "0"
+      (checked via hasAttribute, never the computed value alone, so an
+      unset range-total during loading never flashes this content;
+      ADR-0076, REQ-E-001). Mutually exclusive with a positive
+      [range-total]: the normal "Showing X-Y of N" text always wins
+      whenever range-total is a positive number. Empty (the default)
+      preserves today's exact behavior — [data-summary] hides on a
+      confirmed range-total="0" exactly as before this slot existed.
+      Plain author-supplied markup (text, an empty-state-ui composite, an
+      icon+text pair) — table-toolbar does not template or constrain its
+      shape. Naming matches chart-ui's own existing `empty` slot
+      convention.
+  actions-leading:
+    description: >-
+      Region rendered AFTER the search input and BEFORE the native
+      page-size select (gh#1649) — for app-owned trigger buttons (e.g.
+      custom Filter / Columns triggers that open the consumer's own
+      drawer instead of the native filter/columns popovers) that must
+      land ahead of the page-size select rather than after it, unlike
+      [slot="actions"]. Same real-insertion-point pattern as [slot="scope"]
+      / [slot="actions"] — positioning is CSS by DOM order, not a template
+      stamp. Empty (the default) has zero footprint on existing consumers.
   actions:
-    description: Trailing action area — primary buttons (e.g. "New row") rendered after the search input.
+    description: Trailing action area — primary buttons (e.g. "New row") rendered after the search input, [slot="actions-leading"], and the page-size select.
 states:
   - name: idle
     description: Default, ready for interaction.
@@ -114,10 +252,15 @@ tokens:
     description: Title font size
   --table-toolbar-title-weight:
     description: Title font weight
+  --table-toolbar-summary-fg:
+    description: Range-summary ("Showing X–Y of N") text color
+  --table-toolbar-summary-size:
+    description: Range-summary font size
 requiredIcons:
   - arrow-up
   - arrow-down
   - caret-up-down
+  - dots-three-vertical
 a2ui:
   rules:
     - >-
@@ -142,10 +285,52 @@ a2ui:
       when content is markup (a <span> + <badge-ui>, etc.).
     - >-
       Listen for toolbar events (`search`, `filter-change`,
-      `sort-change`, `columns-change`) only to mirror state to URL /
-      persistence / analytics. The toolbar already wires its changes
-      into the bound table — you don't need to manually update the
-      table.
+      `sort-change`, `columns-change`, `page-size-change`) only to mirror
+      state to URL / persistence / analytics. The toolbar already wires
+      its changes into the bound table — you don't need to manually
+      update the table.
+    - >-
+      Use [slot="scope"] for a leading scope/view switcher (an org's
+      teams, a saved view) rendered before [text]/[count]. Use
+      [range-start] / [range-end] / [range-total] together for a
+      "Showing X–Y of N" summary — it renders independently of, and
+      alongside, [text]/[count], never in place of them. Use [page-size]
+      + [page-size-options] for a rows-per-page select; it applies
+      directly to the bound table's [paginate] prop the same way
+      filter/sort/columns changes apply directly to the target.
+    - >-
+      Use [slot="actions-leading"] (gh#1649) for app-owned trigger
+      buttons that must land BEFORE the page-size select — e.g. custom
+      Filter / Columns triggers that open the consumer's own drawer
+      instead of the native filter/columns popovers (drop [no-filter]
+      [no-columns] to hide the native ones when doing this). [slot="actions"]
+      stays the trailing region AFTER the page-size select, for a
+      primary CTA.
+    - >-
+      Use [chrome-only] (ADR-0076, ADIA2-9123) instead of stacking
+      [no-filter] [no-sort] [no-columns] [no-search] individually when an
+      app owns ALL FOUR affordances itself (its own drawer/menu). Pure OR,
+      absolute while set — clearing an individual no-* attribute does NOT
+      re-enable that one control; drop [chrome-only] entirely and set the
+      three you still want off explicitly instead. Combine with
+      [slot="actions-leading"] for the app's own Filter/Columns triggers.
+    - >-
+      Use <span slot="empty"> (or any markup) inside a table-toolbar-ui
+      that also sets [range-total="0"] to show a "no results" message in
+      the range-summary's own position, without a layout shift versus the
+      normal "Showing X-Y of N" text (ADR-0076, REQ-E). Only fires on an
+      EXPLICIT range-total="0" — omitting range-* entirely (loading) never
+      shows it.
+    - >-
+      Read the host's [data-stage-resolved] attribute (ADR-0076 REQ-M-005,
+      ADIA2-9123 S4-ii) to compact a consumer's own [slot="actions-leading"]
+      content in sympathy with table-toolbar's native regions, without
+      re-deriving the same breakpoints yourself. Informational only —
+      mirrors the CSS-decided compaction stage (full | search-tight |
+      icon-only | overflow), never drives table-toolbar's own rendering.
+      Reports the pinned [stage] value when set, the live width
+      classification otherwise; updates on both a live resize and a
+      [stage] attribute change.
 anti_patterns: []
 examples:
   - name: members-toolbar
@@ -158,6 +343,26 @@ examples:
         {"id": "sec", "component": "Section", "bleed": true, "children": ["tbl"]},
         {"id": "tbl", "component": "Table", "id": "members", "sortable": true, "raw": true}
       ]
+  - name: adiav2-list-page-toolbar-row
+    description: >-
+      The ratified adiav2 list-page toolbar row (ADIA2-9123, gh#1649): scope
+      menu, range summary, app-owned Filter/Columns triggers (their own
+      filter drawer, not the native popovers — [no-filter]/[no-columns]/
+      [no-sort]/[no-search] drop the native affordances), page-size select,
+      and a primary CTA — [slot="actions-leading"] carries the Filter/Columns
+      triggers so they land BEFORE the page-size select, while [slot="actions"]
+      carries the CTA so it lands after.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Column", "gap": "3", "children": ["bar", "card"]},
+        {"id": "bar", "component": "TableToolbar", "for": "accounts", "no-filter": true, "no-sort": true, "no-columns": true, "no-search": true, "range-start": 1, "range-end": 25, "range-total": 320, "page-size": 25, "page-size-options": [10, 25, 50, 100], "children": ["btn-filter", "btn-columns", "btn-new"]},
+        {"id": "btn-filter", "component": "Button", "text": "Filter", "variant": "ghost", "slot": "actions-leading"},
+        {"id": "btn-columns", "component": "Button", "text": "Columns", "variant": "ghost", "slot": "actions-leading"},
+        {"id": "btn-new", "component": "Button", "text": "New account", "variant": "primary", "slot": "actions"},
+        {"id": "card", "component": "Card", "children": ["sec"]},
+        {"id": "sec", "component": "Section", "bleed": true, "children": ["tbl"]},
+        {"id": "tbl", "component": "Table", "id": "accounts", "sortable": true, "raw": true}
+      ]
 keywords:
   - table-toolbar
   - data-grid

package/components/tag/tag.class.js

@@ -25,6 +25,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 export class UITag extends UIElement {
   // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
@@ -75,6 +76,17 @@ export class UITag extends UIElement {
 
   static template = () => null;
 
+  // gh#1644: tracks the aria-label VALUE this element itself last derived
+  // from `text` (undefined when none), so re-renders refresh/clear OUR
+  // name without ever clobbering a consumer's own aria-label. The
+  // compare-against-what-we-last-wrote guard lives in core/a11y.js's
+  // `syncAutoAriaLabel` (gh#1647 / gh#1651); this field is its state.
+  #lastAutoAriaLabel = undefined;
+
+  #syncAccessibleName() {
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, this.text || '');
+  }
+
   #onClick = (e) => {
     if (this.disabled) return;
     if (e.target.closest('[slot="dismiss"]')) {
@@ -112,7 +124,7 @@ export class UITag extends UIElement {
   }
 
   render() {
-    if (this.text) this.setAttribute('aria-label', this.text);
+    this.#syncAccessibleName();
 
     if (this.disabled) {
       this.setAttribute('aria-disabled', 'true');

package/components/text/text.a2ui.json

@@ -96,10 +96,10 @@
         "deck": "Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.",
         "display": "Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners.",
         "heading": "Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.",
-        "kicker": "Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).",
-        "label": "Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.",
+        "kicker": "Eyebrow text above a `title`. UPPERCASE + small + tracking, mono font stack at regular (400) weight. Use for content eyebrows (NOT form labels — use `label` for those).",
+        "label": "Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized, mono font stack at regular (400) weight. Use for field labels bound to form controls.",
         "metric": "Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.",
-        "section": "Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.",
+        "section": "Inline form-group / navlist heading (visual rank H4). Mono font stack at medium (500) weight, normal casing. Use for form group labels, nav list headings.",
         "subsection": "Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section."
       }
     },

package/components/text/text.d.ts

@@ -25,13 +25,13 @@ export type UITextVariant =
   | 'display'
   /** Annotation under a primary line — smaller + muted. Use for image captions, footnotes. */
   | 'caption'
-  /** Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls. */
+  /** Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized, mono font stack at regular (400) weight. Use for field labels bound to form controls. */
   | 'label'
-  /** Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those). */
+  /** Eyebrow text above a `title`. UPPERCASE + small + tracking, mono font stack at regular (400) weight. Use for content eyebrows (NOT form labels — use `label` for those). */
   | 'kicker'
   /** Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title. */
   | 'deck'
-  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
+  /** Inline form-group / navlist heading (visual rank H4). Mono font stack at medium (500) weight, normal casing. Use for form group labels, nav list headings. */
   | 'section'
   /** Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers. */
   | 'metric'
@@ -47,6 +47,8 @@ export class UIText extends UIElement {
   size: 'sm' | 'md' | 'lg';
   /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
   strong: boolean;
+  /** Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10). Converged onto the global Enum·semantic `[text-align]` physical vocabulary (gh#1335) — `start`/`end` renamed to `left`/`right`; `justify` kept (a genuine physical alignment value, now also supported by the global grammar). */
+  textAlign: 'left' | 'center' | 'right' | 'justify';
   /** Display text content. The main payload field for Text components extracted from HTML. */
   textContent: string;
   /** Single-line truncation with ellipsis. Ignored when `lines` is set. */

package/components/text/text.yaml

@@ -103,10 +103,10 @@ props:
       title: Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog.
       heading: Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.
       subsection: Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section.
-      section: Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.
+      section: Inline form-group / navlist heading (visual rank H4). Mono font stack at medium (500) weight, normal casing. Use for form group labels, nav list headings.
       caption: Annotation under a primary line — smaller + muted. Use for image captions, footnotes.
-      label: Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.
-      kicker: Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).
+      label: Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized, mono font stack at regular (400) weight. Use for field labels bound to form controls.
+      kicker: Eyebrow text above a `title`. UPPERCASE + small + tracking, mono font stack at regular (400) weight. Use for content eyebrows (NOT form labels — use `label` for those).
       deck: Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.
       metric: Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.
       code: Inline monospace code reference. Use for inline code within prose.

package/components/textarea/textarea.class.js

@@ -18,6 +18,7 @@
  */
 
 import { UIFormElement } from '../../core/form.js';
+import { syncAutoAriaLabel } from '../../core/a11y.js';
 
 export class UITextarea extends UIFormElement {
   static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per textarea.yaml
@@ -32,6 +33,10 @@ export class UITextarea extends UIFormElement {
   static template = () => null;
 
   #textEl = null;
+  // gh#1647: tracks the aria-label VALUE this element itself last derived
+  // from `label`/`placeholder` (undefined when none) — value-tracking
+  // guard ported from tag.class.js/select.class.js (gh#1644/#1646).
+  #lastAutoAriaLabel = undefined;
 
   connected() {
     super.connected();
@@ -82,7 +87,10 @@ export class UITextarea extends UIFormElement {
     const label = this.querySelector('[slot="label"]');
     if (label && this.label) label.setAttribute('label', this.label);
 
-    this.setAttribute('aria-label', this.label || this.placeholder || '');
+    // A11y (gh#1647): never clobber a consumer's own aria-label
+    // (value-tracking guard, gh#1644/#1646).
+    const ariaSource = this.label || this.placeholder || '';
+    this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, ariaSource);
   }
 
   #onInput = () => {

package/components/textarea/textarea.css

@@ -37,6 +37,9 @@ textarea-ui:not([disabled]) [slot="text"]:hover {
     --textarea-label-fg-focus:  var(--md-sys-color-neutral-on-surface-variant);
     --textarea-bg-disabled:     var(--a-ui-bg-disabled);
     --textarea-fg-disabled:     var(--a-ui-text-disabled);
+    /* Same gap as gh#1595 (input-ui) — rides along here since it's the
+       identical shared-field pattern, same root-cause class. */
+    --textarea-border-disabled: var(--a-ui-border-disabled);
     text-align: start;  /* §text-align-reset — blocks inheritance from centered ancestors */
 }
 
@@ -124,6 +127,7 @@ textarea-ui:not([disabled]) [slot="text"]:hover {
   :scope[disabled] [slot="text"] {
     background: var(--textarea-bg-disabled);
     color: var(--textarea-fg-disabled);
+    border-color: var(--textarea-border-disabled);
     cursor: not-allowed;
   }
 }

package/components/time-picker/time-picker.yaml

@@ -175,8 +175,9 @@ a2ui:
       (`h12` / `h23`) when the surface needs a specific cycle (cron
       editors, log queries, system surfaces).
     - >-
-      For datetime selection use `<datetime-picker-ui>` (SPEC-038) —
-      it composes this primitive as its time pane.
+      For datetime selection use `<calendar-picker-ui precision="minute">`
+      (SPEC-038; the former `<datetime-picker-ui>` thin alias was cut in
+      0.8.43, gh#1617) — it composes this primitive as its time pane.
 anti_patterns:
   - wrong: |
       {"component": "TimePicker", "value": "9:30 AM"}

package/components/tour/tour.d.ts

@@ -43,10 +43,20 @@ export class UITour extends UIElement {
 the spotlight + popover; setting to `false` tears down.
  */
   active: boolean;
+  /** Start the tour automatically when the element connects. Useful for
+first-run flows gated by a storage flag on the consumer side.
+ */
+  autoStart: boolean;
   /** Current step index (0-based). Setting this property advances the
 tour to that step (updating spotlight + popover position).
  */
   step: number;
+  /** Optional localStorage key. When set, the tour records its
+completion state (`"done"`) to that key on finish/skip — and
+refuses to auto-start on subsequent loads if the key is "done".
+Useful for "show this tour once per user" flows.
+ */
+  storageKey: string;
 
   addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/tree/tree.yaml

@@ -108,7 +108,7 @@ a2ui:
       for one-level collapsible groups use <accordion-ui>.
     - >-
       Canonical mount: inside <editor-sidebar slot="leading"> →
-      <pane-ui side="leading" resizable> → <section> → <tree-ui id="…">
+      <pane-ui edge="leading" resizable> → <section> → <tree-ui id="…">
       as the structure / navigator pane of the three-pane editor shell.
       Pair with a <header> in the same pane (e.g. "Structure",
       "Layers", "Files").

package/components/upload/upload.class.js

@@ -93,6 +93,22 @@ export class UIUpload extends UIFormElement {
     return this.#files;
   }
 
+  /**
+   * Empty the selected file list and return the dropzone to idle — the
+   * public counterpart to `open()` (gh#1605). A consumer's own Clear/Reset
+   * action can call this without reaching into `[data-dropzone]`'s internal
+   * anatomy, which the yaml spec forbids.
+   */
+  clear() {
+    this.#setFiles([]);
+  }
+
+  // ── Form lifecycle ──
+
+  onFormReset() {
+    this.clear();
+  }
+
   // ── File picking ──
 
   /**

package/components/upload/upload.d.ts

@@ -40,6 +40,13 @@ export class UIUpload extends UIFormElement {
    */
   open(): Promise<void>;
 
+  /**
+   * gh#1605: empty the selected file list and return the dropzone to idle
+   * — the public counterpart to `open()`. Also runs automatically on
+   * native form reset (the element is form-associated).
+   */
+  clear(): void;
+
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UIUpload, ev: HTMLElementEventMap[K]) => unknown,

package/components/upload/upload.yaml

@@ -67,9 +67,11 @@ slots: {}
 # (the audit-slot-vocab-vs-css vocabulary is slot-attr based). Consumers
 # must NOT reach into `[data-dropzone]` to trigger the picker — that is
 # what the public `.open()` method and the [compact] trigger mode are for
-# (gh#1493). Hint + label are declared as props above (text-only); for an
-# avatar / icon / form-element wrapper, compose <field-ui label> around
-# the upload.
+# (gh#1493). Emptying the selection is the public `.clear()` method
+# (gh#1605) — it also fires on native form reset, since the element is
+# form-associated. Hint + label are declared as props above (text-only);
+# for an avatar / icon / form-element wrapper, compose <field-ui label>
+# around the upload.
 states:
   - name: idle
     description: Default, ready for interaction.
@@ -88,6 +90,8 @@ a2ui:
       reason: 'Standard file-input knobs.'
     - rule: 'compact renders an icon-only trigger (no drop-zone chrome) — use in toolbars/dense rows; label becomes the trigger''s aria-label. Programmatic triggering goes through the public .open() method, never the internal [data-dropzone] part.'
       reason: 'Public trigger API (gh#1493); internal anatomy is not a contract.'
+    - rule: 'A consumer''s own Clear/Reset action empties the selection through the public .clear() method — it also runs automatically on native form reset.'
+      reason: 'Public reset API (gh#1605); form-associated elements react to form reset without a manual wire-up.'
     - rule: 'For agent chat attachments use <chat-composer-ui>''s built-in upload affordance instead.'
       reason: 'Chat composer has its own attachment lane.'
 anti_patterns: []

package/core/a11y.d.ts

@@ -0,0 +1,22 @@
+/**
+ * core/a11y.js — shared accessible-name authorship guard.
+ *
+ * See the runtime module's own JSDoc for the full contract and the usage
+ * pattern (gh#1644 / gh#1646 / gh#1647).
+ */
+
+/**
+ * Reconcile an auto-derived `aria-label` against a possible consumer
+ * override, using a value-tracking guard rather than a plain boolean flag.
+ *
+ * @param el - the host element.
+ * @param lastAuto - the value this component wrote last time (`undefined`
+ *   = no active auto-derived value, either never set or consumer-owned).
+ * @param source - the label this render would derive; falsy = no auto name.
+ * @returns the new `lastAuto` to store back in the caller's own field.
+ */
+export function syncAutoAriaLabel(
+  el: HTMLElement,
+  lastAuto: string | undefined,
+  source: string,
+): string | undefined;

package/core/a11y.js

@@ -0,0 +1,64 @@
+/**
+ * core/a11y.js — shared accessible-name authorship guard.
+ *
+ * Ports the value-tracking guard proven on `tag.class.js`'s
+ * `#syncAccessibleName` (gh#1644 / PR #1645) and `select.class.js`'s
+ * `labeledElsewhere` variant (gh#1646 / PR #1648) into one shared helper,
+ * so every primitive that derives its own `aria-label` doesn't need to
+ * reimplement the compare-against-what-we-last-wrote logic (gh#1647).
+ *
+ * A plain boolean "did we ever set it" flag isn't enough: a consumer can
+ * overwrite `aria-label` directly via `setAttribute` at any point BETWEEN
+ * renders, bypassing the flag entirely. This guard instead compares the
+ * CURRENT attribute value against the value THIS component last wrote —
+ * a mismatch means a consumer has taken ownership, and auto-derivation
+ * stops until the source value the caller passes in changes again.
+ *
+ * Per-component gating (e.g. select-ui's `labeledElsewhere` — don't
+ * auto-name when a visible `label` or `aria-labelledby` already names the
+ * element, or don't auto-name off a default/placeholder-only value) is
+ * the CALLER's job: resolve the source string to '' when no auto name
+ * should apply this render, and pass the real derived string otherwise.
+ * This helper only ever reconciles "what we'd write" against "what's
+ * there now, and did we write it" — it carries no per-component policy.
+ *
+ * Usage (per component):
+ *
+ *   import { syncAutoAriaLabel } from '../../core/a11y.js';
+ *
+ *   #lastAutoAriaLabel = undefined;
+ *
+ *   #syncAccessibleName() {
+ *     const source = <derive the label this render, or '' for none>;
+ *     this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, source);
+ *   }
+ *
+ * Call `#syncAccessibleName()` early in `render()`, before any other
+ * aria-* bookkeeping that might read the (possibly just-changed)
+ * `aria-label` attribute.
+ *
+ * @param {HTMLElement} el
+ * @param {string | undefined} lastAuto - the value this component wrote
+ *   last time (`undefined` = the component has never derived a name for
+ *   the CURRENT attribute value, either because it never has, or because
+ *   a consumer has since taken ownership).
+ * @param {string} source - the label the component would derive right
+ *   now. Empty string (or any other falsy value) means "no auto name" —
+ *   any auto-set label is removed.
+ * @returns {string | undefined} the new `lastAuto` value — store this
+ *   back into the caller's own private field.
+ */
+export function syncAutoAriaLabel(el, lastAuto, source) {
+  const current = el.getAttribute('aria-label');
+  if (lastAuto !== undefined && current !== lastAuto) {
+    lastAuto = undefined; // a consumer took ownership between renders
+  }
+  const authored = current !== null && lastAuto === undefined;
+  if (authored) return lastAuto;
+  if (source) {
+    if (current !== source) el.setAttribute('aria-label', source);
+    return source;
+  }
+  if (current !== null) el.removeAttribute('aria-label');
+  return undefined;
+}