@adia-ai/web-components 0.8.41 → 0.8.43

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

@@ -57,6 +57,18 @@ function popoverHead(text) {
   return el;
 }
 
+// `col.label` is sometimes set to an nbsp or a bare space — the idiom
+// consumers use on render-only columns (e.g. `_cancel` / `_download` /
+// `_replay`) to keep the TABLE header cell blank while still rendering a
+// custom cell. That whitespace is truthy, so a plain `col.label || col.key`
+// fallback never engages and popover rows (filter / sort / columns) render
+// with no visible text. Trim before testing so the fallback only skips when
+// a label is genuinely present, never when it's intentional whitespace.
+function columnLabel(col) {
+  const label = col.label;
+  return typeof label === 'string' && label.trim() ? label : col.key;
+}
+
 const SELECT_THRESHOLD = 50;
 const SAMPLE_LIMIT     = 500;
 
@@ -116,6 +128,10 @@ export class UITableToolbar extends UIElement {
     for:         { type: String,  default: '',         reflect: true },
     text:        { type: String,  default: '',         reflect: false },
     count:       { type: String,  default: '',         reflect: false },
+    rangeStart:  { type: Number,  default: 0,          reflect: true, attribute: 'range-start' },
+    rangeEnd:    { type: Number,  default: 0,          reflect: true, attribute: 'range-end' },
+    rangeTotal:  { type: Number,  default: 0,          reflect: true, attribute: 'range-total' },
+    pageSize:    { type: Number,  default: 0,          reflect: true, attribute: 'page-size' },
     noFilter:    { type: Boolean, default: false,      reflect: true, attribute: 'no-filter' },
     noSort:      { type: Boolean, default: false,      reflect: true, attribute: 'no-sort' },
     noColumns:   { type: Boolean, default: false,      reflect: true, attribute: 'no-columns' },
@@ -137,6 +153,19 @@ export class UITableToolbar extends UIElement {
   #docListenersBound = false;
   #docListenerRaf = null;
   #sortIndicatorRafs = new Set();
+  #pageSizeOptions = [];
+
+  // ── Public API: pageSizeOptions ──────────────────────────────────────────
+  // Dynamic array prop (JS-set collection, custom setter) — same shape as
+  // table-ui's `columns`/`data`. Deliberately not in `static properties`
+  // (gh#970 — an array prop needs its own setter, not the scalar signal path).
+
+  set pageSizeOptions(arr) {
+    this.#pageSizeOptions = Array.isArray(arr) ? arr.map(Number).filter((n) => Number.isFinite(n)) : [];
+    this.#updatePageSizeSelect();
+  }
+
+  get pageSizeOptions() { return this.#pageSizeOptions; }
 
   // §381 (v0.6.10, slice F): one-shot dev-mode warning when consumers
   // set common-but-unknown opt-out attributes (e.g. `searchable`,
@@ -153,11 +182,37 @@ export class UITableToolbar extends UIElement {
   connected() {
     this.setAttribute('role', 'toolbar');
     this.#warnUnknownOptOutAttrs();
+    // gh#1615 — hydrate `page-size-options="[10,25,50]"` once at connect,
+    // same pattern as table-ui's `data`/`columns` JSON-array attributes
+    // (table.class.js connected()). A later programmatic `.pageSizeOptions
+    // = [...]` set still wins (guarded by the length check).
+    if (this.#pageSizeOptions.length === 0 && this.hasAttribute('page-size-options')) {
+      try {
+        const parsed = JSON.parse(this.getAttribute('page-size-options'));
+        if (Array.isArray(parsed)) this.pageSizeOptions = parsed;
+      } catch (_) { /* malformed JSON — leave empty, select renders hidden */ }
+    }
     this.#stamp();
     this.#resolveTarget();
     this.#syncFromTarget();
   }
 
+  // gh#1620 — this used to live in a declared `attributeChanged(name)` hook
+  // that the base class never calls (core/element.js only ever invokes
+  // `updated(changed)`, keyed by property name, not attribute name); the
+  // reactions below silently never fired. Migrated verbatim onto the live
+  // hook, keyed by the matching property names.
+  updated(changed) {
+    if (changed.has('noFilter') || changed.has('noSort')
+      || changed.has('noColumns') || changed.has('noSearch')) {
+      this.#updateControlVisibility();
+    }
+    if (changed.has('placeholder')) {
+      const search = this.querySelector(':scope [data-search]');
+      search?.setAttribute('placeholder', this.placeholder);
+    }
+  }
+
   disconnected() {
     if (this.#docListenerRaf != null) {
       cancelAnimationFrame(this.#docListenerRaf);
@@ -174,6 +229,8 @@ export class UITableToolbar extends UIElement {
     this.#resolveTarget();
     this.#syncFromTarget();
     this.#updateTitle();
+    this.#updateSummary();
+    this.#updatePageSizeSelect();
   }
 
   // ── Unknown opt-out attribute warning (§381, v0.6.10 slice F) ────────────
@@ -261,6 +318,20 @@ export class UITableToolbar extends UIElement {
     const root = document.createElement('div');
     root.setAttribute('data-toolbar', '');
 
+    // Scope slot passthrough (gh#1615) — leading region before the title
+    // cluster. Same real-insertion-point pattern as [slot="actions"] below:
+    // move any pre-existing [slot="scope"] children into a stamped wrapper
+    // rather than declaring a template-owned `parts:` entry (ADR-0067 — an
+    // author-fillable span is `slots:`, never `parts:`).
+    const scopeSlot = document.createElement('div');
+    scopeSlot.setAttribute('data-scope', '');
+    for (const node of [...this.children]) {
+      if (node === root) continue;
+      if (node.getAttribute?.('slot') === 'scope') {
+        scopeSlot.appendChild(node);
+      }
+    }
+
     // Title cluster
     const title = document.createElement('div');
     title.setAttribute('data-title', '');
@@ -276,6 +347,16 @@ export class UITableToolbar extends UIElement {
     badge.hidden = true;
     title.appendChild(badge);
 
+    // Range summary ("Showing X–Y of N", gh#1615) — its own cluster,
+    // independent of [data-title]: coexists with [text]/[count] rather than
+    // nesting inside their hide-with-children logic (ADIA2-8897).
+    const summary = document.createElement('div');
+    summary.setAttribute('data-summary', '');
+    summary.hidden = true;
+    const summaryText = document.createElement('span');
+    summaryText.setAttribute('data-summary-text', '');
+    summary.appendChild(summaryText);
+
     // Controls cluster
     const controls = document.createElement('div');
     controls.setAttribute('data-controls', '');
@@ -295,6 +376,19 @@ export class UITableToolbar extends UIElement {
     search.setAttribute('debounce', String(SEARCH_DEBOUNCE));
     search.addEventListener('search', this.#onSearch);
 
+    // Page-size select (gh#1615) — hidden until pageSizeOptions is set
+    // (additive opt-in, zero footprint on existing consumers). Carries the
+    // same `margin-inline-start: auto` as [data-search] so the trailing
+    // group (controls/search/page-size/actions) still pushes to the far
+    // edge when [no-search] drops search — without touching search's own
+    // existing default behavior for consumers that never set pageSizeOptions.
+    const pageSize = document.createElement('select-ui');
+    pageSize.setAttribute('data-page-size', '');
+    pageSize.setAttribute('size', 'sm');
+    pageSize.setAttribute('aria-label', 'Rows per page');
+    pageSize.hidden = true;
+    pageSize.addEventListener('change', this.#onPageSizeChange);
+
     // Actions slot passthrough — we move any pre-existing [slot="actions"] children here
     const actionsSlot = document.createElement('div');
     actionsSlot.setAttribute('data-actions', '');
@@ -305,14 +399,19 @@ export class UITableToolbar extends UIElement {
       }
     }
 
+    root.appendChild(scopeSlot);
     root.appendChild(title);
+    root.appendChild(summary);
     root.appendChild(controls);
     root.appendChild(search);
+    root.appendChild(pageSize);
     root.appendChild(actionsSlot);
 
     this.appendChild(root);
     this.#updateTitle();
+    this.#updateSummary();
     this.#updateControlVisibility();
+    this.#updatePageSizeSelect();
   }
 
   #mkPopoverAction(label, onClick) {
@@ -385,6 +484,70 @@ export class UITableToolbar extends UIElement {
     }
   }
 
+  // ── Range summary ("Showing X–Y of N", gh#1615) ─────────────────────────
+  // Independent of #updateTitle's [data-title] cluster by design — coexists
+  // with [text]/[count] rather than sharing their hide-with-children logic.
+
+  #updateSummary() {
+    const summary = this.querySelector(':scope > [data-toolbar] > [data-summary]');
+    if (!summary) return;
+    const start = Number(this.rangeStart) || 0;
+    const end = Number(this.rangeEnd) || 0;
+    const total = Number(this.rangeTotal) || 0;
+    if (start > 0 && end > 0 && total > 0) {
+      const text = summary.querySelector(':scope [data-summary-text]');
+      if (text) text.textContent = `Showing ${start}–${end} of ${total}`;
+      summary.hidden = false;
+    } else {
+      summary.hidden = true;
+    }
+  }
+
+  // ── Page-size select (gh#1615) ───────────────────────────────────────────
+  // Hidden whenever pageSizeOptions is empty — additive opt-in, matching the
+  // [slot="actions"]:empty pattern's "no footprint unless a consumer opts in".
+
+  #updatePageSizeSelect() {
+    const select = this.querySelector(':scope > [data-toolbar] > [data-page-size]');
+    if (!select) return;
+    const options = this.#pageSizeOptions;
+    if (!options.length) {
+      select.hidden = true;
+      return;
+    }
+    select.hidden = false;
+
+    // `.options = [...]` (select-ui's documented programmatic API) rather
+    // than appending light-DOM <option> children: select-ui's own
+    // #parseOptions() PARSES-THEN-REMOVES any <option>/<optgroup> children
+    // once connected, and only re-parses newly-appended ones via an async
+    // MutationObserver — appending after this element is already connected
+    // (which it is, by the time a later pageSizeOptions/pageSize change
+    // reaches this method) races that observer. `.options=` is synchronous
+    // and connection-state-agnostic, matching table-toolbar's own
+    // initial-mount-through-any-later-update determinism elsewhere.
+    const desired = options.map((n) => ({ value: String(n), label: `${n} / page` }));
+    select.options = desired;
+
+    const size = Number(this.pageSize) || 0;
+    const value = options.includes(size) ? size : options[0];
+    select.value = String(value);
+  }
+
+  #onPageSizeChange = (e) => {
+    const pageSize = Number(e.detail?.value ?? this.querySelector(':scope [data-page-size]')?.value) || 0;
+    this.pageSize = pageSize;
+    // Applied directly to the bound table's own [paginate] (rows-per-page)
+    // prop — the same "mirror to URL/analytics via the event, but the
+    // toolbar already wires the change into the target" pattern
+    // columns-change/sort-change already use.
+    if (this.#target) this.#target.paginate = pageSize;
+    this.dispatchEvent(new CustomEvent('page-size-change', {
+      bubbles: true,
+      detail: { pageSize },
+    }));
+  };
+
   #updateControlVisibility() {
     const root = this.querySelector(':scope > [data-toolbar]');
     if (!root) return;
@@ -400,17 +563,6 @@ export class UITableToolbar extends UIElement {
     setHidden('[data-search]',                this.noSearch);
   }
 
-  // Re-run on attribute changes for boolean flags.
-  attributeChanged(name) {
-    if (['no-filter', 'no-sort', 'no-columns', 'no-search'].includes(name)) {
-      this.#updateControlVisibility();
-    }
-    if (name === 'placeholder') {
-      const search = this.querySelector(':scope [data-search]');
-      search?.setAttribute('placeholder', this.placeholder);
-    }
-  }
-
   // ── Search ───────────────────────────────────────────────────────────────
 
   #onSearch = (e) => {
@@ -530,7 +682,7 @@ export class UITableToolbar extends UIElement {
       const row = document.createElement('field-ui');
       row.setAttribute('data-filter-row', '');
       row.setAttribute('inline', '');
-      row.setAttribute('label', col.label || col.key);
+      row.setAttribute('label', columnLabel(col));
 
       const shape = detectFilterShape(col, data);
       const current = filters[col.key];
@@ -637,7 +789,7 @@ export class UITableToolbar extends UIElement {
       const dir = dirByKey.get(col.key);
       const row = document.createElement('menu-item-ui');
       row.setAttribute('data-sort-row', '');
-      row.setAttribute('text', col.label || col.key);
+      row.setAttribute('text', columnLabel(col));
       row.dataset.key = col.key;
       if (dir) row.dataset.active = dir;
 
@@ -731,7 +883,7 @@ export class UITableToolbar extends UIElement {
       const row = document.createElement('field-ui');
       row.setAttribute('data-columns-row', '');
       row.setAttribute('inline', '');
-      row.setAttribute('label', col.label || col.key);
+      row.setAttribute('label', columnLabel(col));
 
       const check = document.createElement('check-ui');
       if (!col.hidden) check.setAttribute('checked', '');

package/components/table-toolbar/table-toolbar.css

@@ -18,6 +18,10 @@
     --table-toolbar-title-weight:  var(--a-weight-medium);
     --table-toolbar-title-gap:     var(--a-space-2);
 
+    /* ── Range summary ("Showing X–Y of N") ── */
+    --table-toolbar-summary-fg:    var(--md-sys-color-neutral-on-surface-variant);
+    --table-toolbar-summary-size:  var(--a-ui-size);
+
     /* ── Search ── */
     --table-toolbar-search-min:    14rem;
     --table-toolbar-search-max:    22rem;
@@ -68,6 +72,17 @@
     --table-toolbar-px:           var(--a-space-4);
   }
 
+  /* ═══════ Scope slot ═══════ (gh#1615 — leading region before the title cluster) */
+
+  [data-scope] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--table-toolbar-cluster-gap);
+    flex: 0 0 auto;
+  }
+
+  [data-scope]:empty { display: none; }
+
   /* ═══════ Title cluster ═══════ */
 
   [data-title] {
@@ -87,6 +102,20 @@
 
   [data-toolbar-count-badge][hidden] { display: none; }
 
+  /* ═══════ Range summary ═══════ (gh#1615 — "Showing X–Y of N", independent of [data-title]) */
+
+  [data-summary] {
+    flex: 0 0 auto;
+  }
+
+  [data-summary][hidden] { display: none; }
+
+  [data-summary-text] {
+    font-size: var(--table-toolbar-summary-size);
+    color: var(--table-toolbar-summary-fg);
+    line-height: var(--a-font-leading-snug);
+  }
+
   /* ═══════ Controls cluster ═══════ */
 
   [data-controls] {
@@ -111,6 +140,23 @@
 
   [data-search][hidden] { display: none; }
 
+  /* ═══════ Page-size select ═══════ (gh#1615)
+     Carries the SAME margin-inline-start:auto as [data-search] so the
+     trailing group (controls/search/page-size/actions) still pushes to the
+     far edge when [no-search] drops search — without changing search's own
+     existing default for consumers that never set [page-size-options]
+     (the element doesn't render at all until then; see [hidden] below and
+     #updatePageSizeSelect). Multiple auto-margin siblings in one flex row
+     is safe — only the first one with unclaimed free space to its left
+     actually receives it. */
+
+  [data-page-size] {
+    flex: 0 0 auto;
+    margin-inline-start: auto;
+  }
+
+  [data-page-size][hidden] { display: none; }
+
   /* ═══════ Actions slot ═══════ */
 
   [data-actions] {

package/components/table-toolbar/table-toolbar.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<table-toolbar-ui>` — 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.
+ * `<table-toolbar-ui>` — 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 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.
  *
  * @see https://ui-kit.exe.xyz/site/components/table-toolbar
  *
@@ -14,6 +14,7 @@ import { UIElement } from '../../core/element.js';
 
 export type TableToolbarColumnsChangeEvent = CustomEvent<unknown>;
 export type TableToolbarFilterChangeEvent = CustomEvent<unknown>;
+export type TableToolbarPageSizeChangeEvent = CustomEvent<unknown>;
 export type TableToolbarSearchEvent = CustomEvent<unknown>;
 export type TableToolbarSortChangeEvent = CustomEvent<unknown>;
 
@@ -30,8 +31,18 @@ export class UITableToolbar extends UIElement {
   noSearch: boolean;
   /** Hide the Sort popover button. Sort is shown by default; set to opt out. */
   noSort: boolean;
+  /** 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. */
+  pageSize: number;
+  /** 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. */
+  pageSizeOptions: string;
   /** Placeholder text for the search input. */
   placeholder: string;
+  /** 1-indexed last row number of the current page, for the range summary (e.g. `25` in "Showing 1–25 of 320"). See rangeStart. */
+  rangeEnd: number;
+  /** 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. */
+  rangeStart: number;
+  /** 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. */
+  rangeTotal: number;
   /** Title text shown on the left. */
   text: string;
   /** Toolbar visual variant. `default` renders bare on parent surface; `card` adds the same chrome as a card-ui header. */
@@ -39,6 +50,7 @@ export class UITableToolbar extends UIElement {
 
   addEventListener(type: 'columns-change', listener: (ev: TableToolbarColumnsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'filter-change', listener: (ev: TableToolbarFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'page-size-change', listener: (ev: TableToolbarPageSizeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'search', listener: (ev: TableToolbarSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'sort-change', listener: (ev: TableToolbarSortChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(

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

@@ -6,16 +6,19 @@ 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 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:
@@ -43,6 +46,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
@@ -88,7 +148,11 @@ 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.
   actions:
     description: Trailing action area — primary buttons (e.g. "New row") rendered after the search input.
 states:
@@ -114,6 +178,10 @@ 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
@@ -142,10 +210,19 @@ 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.
 anti_patterns: []
 examples:
   - name: members-toolbar
@@ -158,6 +235,19 @@ 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): scope menu,
+      range summary, filter/columns triggers, page-size select, and a
+      primary CTA — search and sort dropped per that contract.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Column", "gap": "3", "children": ["bar", "card"]},
+        {"id": "bar", "component": "TableToolbar", "for": "accounts", "no-sort": true, "no-search": true, "range-start": 1, "range-end": 25, "range-total": 320, "page-size": 25, "page-size-options": [10, 25, 50, 100]},
+        {"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/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/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,