@adia-ai/web-components 0.8.42 → 0.8.44

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

@@ -18,7 +18,9 @@
  *   • title + optional count badge
  *   • filter / sort / columns popover buttons
  *   • search input
- *   • optional [slot="actions"] trailing region
+ *   • optional [slot="actions-leading"] region, BEFORE the page-size select (gh#1649)
+ *   • optional page-size select
+ *   • optional [slot="actions"] trailing region, AFTER the page-size select
  *
  * [for] resolution mirrors chart-legend-ui — the toolbar mounts an element by
  * id, then dispatches state changes against it. When [for] is absent, falls
@@ -35,10 +37,24 @@
  */
 
 import { UIElement } from '../../core/element.js';
-import { anchorPopover } from '../../core/anchor.js';
+import { anchorPopover, resolveLengthPx } from '../../core/anchor.js';
 
 const SEARCH_DEBOUNCE = 200;
 
+// ADR-0076 REQ-M-006 — the three breakpoints' NORMATIVE default pixel
+// widths (56rem/40rem/26rem at the standard 16px root), duplicated here
+// ONLY as a fallback for #classifyStage() below when the live
+// `--table-toolbar-bp-*` custom property can't be read (no table-toolbar.css
+// stylesheet attached yet, an SSR shim, or a unit-test harness with no real
+// cascade) — resolveLengthPx() returns NaN in that case, `||` falls
+// through to these. Table-toolbar.css's own `:where(:scope)` declarations
+// are the actual source of truth whenever a real stylesheet IS present;
+// this fallback exists so the reflection degrades to the DOCUMENTED
+// default instead of silently misclassifying against NaN.
+const DEFAULT_BP_SEARCH_TIGHT_PX = 56 * 16;
+const DEFAULT_BP_ICON_ONLY_PX    = 40 * 16;
+const DEFAULT_BP_OVERFLOW_PX     = 26 * 16;
+
 function emptyHint(text) {
   const el = document.createElement('text-ui');
   el.setAttribute('data-popover-empty', '');
@@ -128,18 +144,36 @@ 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' },
     noSearch:    { type: Boolean, default: false,      reflect: true, attribute: 'no-search' },
+    // ADR-0076 (ADIA2-9123) — additive sugar over the four `no-*` attributes
+    // above. Pure, absolute OR: see #updateControlVisibility(), which is the
+    // single place that combines chromeOnly with each granular no-* value.
+    chromeOnly:  { type: Boolean, default: false,      reflect: true, attribute: 'chrome-only' },
     placeholder: { type: String,  default: 'Search...', reflect: false },
     variant:     { type: String,  default: 'default',  reflect: true },
+    // ADR-0076 REQ-O-001 — explicit compaction-stage override. Unset (the
+    // default, empty string) means auto-snap via the @container query
+    // (table-toolbar.css's :scope container-type/container-name). All four
+    // stages' CSS is now live: 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 (step 5).
+    stage:       { type: String,  default: '',         reflect: true },
   };
 
   // §205 (v0.5.7): dynamic sort-indicator icons (table-toolbar.class.js:576 — nested ternary
   // `dir === 'asc' ? 'arrow-up' : dir === 'desc' ? 'arrow-down' : 'caret-up-down'`).
   // Per FEEDBACK-16 §1 + §209 slot-11 ternary-walker discovery.
-  static requiredIcons = ['arrow-up', 'arrow-down', 'caret-up-down'];
+  // 'dots-three-vertical' — the overflow-stage "More" trigger icon
+  // (ADR-0076 REQ-S-004, PLAN step 5, #mkOverflowTrigger()).
+  static requiredIcons = ['arrow-up', 'arrow-down', 'caret-up-down', 'dots-three-vertical'];
 
   static template = () => null;
 
@@ -149,6 +183,30 @@ export class UITableToolbar extends UIElement {
   #docListenersBound = false;
   #docListenerRaf = null;
   #sortIndicatorRafs = new Set();
+  #pageSizeOptions = [];
+  // ADR-0076 REQ-M-005 (ADIA2-9123 S4-ii), PLAN step 7 — data-stage-resolved
+  // reflection. #resizeObs classifies live width against the SAME three
+  // breakpoints table-toolbar.css's @container rules use (read from the
+  // custom properties themselves, never a second hardcoded copy of
+  // 56/40/26 — see #classifyStage()). #lastWidthPx caches the last
+  // measured inline-size so a `stage` attribute change alone (no resize)
+  // can still re-classify without waiting on the next ResizeObserver
+  // callback (REQ-M-005's dual-trigger requirement).
+  #resizeObs = null;
+  #lastWidthPx = null;
+  #stageRaf = null;
+
+  // ── 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`,
@@ -165,9 +223,88 @@ 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();
+
+    // ADR-0076 REQ-M-005, PLAN step 7 — classify synchronously off
+    // `clientWidth` at connect time too (0 pre-layout treated as "no
+    // measurement yet", the same `null`-width fallback #reflectResolvedStage
+    // uses) rather than waiting on the ResizeObserver's own first
+    // (asynchronous) callback — avoids a brief connect-time gap with no
+    // `data-stage-resolved` reflected at all, mirroring how chart.class.js's
+    // own `data-ratio-resolved` is set synchronously from `#dims()` at
+    // first render(), not deferred to its ResizeObserver's first tick.
+    this.#lastWidthPx = this.clientWidth || null;
+    this.#reflectResolvedStage();
+
+    // gh#285 SSR DOM shims (linkedom) have no ResizeObserver global, same
+    // guard chart.class.js's own ResizeObserver setup uses.
+    if (typeof ResizeObserver !== 'undefined') {
+      this.#resizeObs = new ResizeObserver((entries) => {
+        const { inlineSize } = entries[0].contentBoxSize[0];
+        this.#lastWidthPx = inlineSize;
+        // rAF-batch, mirroring chart.class.js's own ResizeObserver setup —
+        // avoids a same-tick reflect→layout→observer-refire loop.
+        if (this.#stageRaf) return;
+        this.#stageRaf = requestAnimationFrame(() => {
+          this.#stageRaf = null;
+          this.#reflectResolvedStage();
+        });
+      });
+      this.#resizeObs.observe(this);
+    }
+  }
+
+  // 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')
+      || changed.has('chromeOnly')) {
+      this.#updateControlVisibility();
+    }
+    if (changed.has('placeholder')) {
+      const search = this.querySelector(':scope [data-search]');
+      search?.setAttribute('placeholder', this.placeholder);
+    }
+  }
+
+  // ADR-0076 REQ-E-001 — `updated(changed)` alone MISSES a live loading→
+  // confirmed-zero transition: `rangeTotal`'s default is already 0, so
+  // setting `range-total="0"` from an unset start parses to the SAME
+  // Number(0), the base class's property setter's `Object.is` short-circuit
+  // swallows the signal write (core/element.js `installProps()`), and
+  // `changed` never gets a `rangeTotal` entry — `#updateSummary()`'s
+  // hasAttribute-based branch never re-runs. Verified live in a browser
+  // (not just the vitest suite, which happened to only exercise the
+  // positive→zero transition, where the signal DOES change). REQ-E-001's
+  // check is fundamentally an ATTRIBUTE-presence concern, not a coerced-
+  // value one, so it needs the raw attribute callback, not the signal diff.
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback(name, oldVal, newVal);
+    if (name === 'range-total') this.#updateSummary();
+    // ADR-0076 REQ-M-005 — the SECOND of the two triggers `data-stage-
+    // resolved` must react to: a live resize (the ResizeObserver callback
+    // above) AND a `stage` attribute change alone, with no resize needed.
+    // Re-classifies against the cached last-measured width — a pin set
+    // before the first resize observation (#lastWidthPx still null) simply
+    // reports the pin; classifyStage() below treats a null width as "no
+    // live width to compare against yet", never a false 0-width match.
+    if (name === 'stage') this.#reflectResolvedStage();
   }
 
   disconnected() {
@@ -179,6 +316,68 @@ export class UITableToolbar extends UIElement {
     this.#sortIndicatorRafs.clear();
     this.#closePopover();
     this.#detachTarget();
+    if (this.#stageRaf != null) {
+      cancelAnimationFrame(this.#stageRaf);
+      this.#stageRaf = null;
+    }
+    this.#resizeObs?.disconnect();
+    this.#resizeObs = null;
+  }
+
+  // ── data-stage-resolved reflection (ADR-0076 REQ-M-005, ADIA2-9123 ─────────
+  // S4-ii, PLAN step 7) ────────────────────────────────────────────────────
+  //
+  // Purely informational — mirrors the CSS-decided stage for a consumer's
+  // own [slot="actions-leading"] content, never drives table-toolbar's own
+  // rendering (REQ-S stays 100% CSS `@container`-driven, REQ-M-002). The
+  // three breakpoints are read live off the SAME custom properties the CSS
+  // `@container` rules consume (--table-toolbar-bp-search-tight/-icon-only/
+  // -overflow) via `resolveLengthPx` (core/anchor.js, shared with its
+  // --popover-max-height use) — one source of truth, never a second
+  // hardcoded copy of 56/40/26 here.
+
+  #classifyStage(widthPx) {
+    const cs = getComputedStyle(this);
+    // resolveLengthPx() returns NaN when the custom property is unreadable
+    // — no table-toolbar.css stylesheet attached yet, an SSR shim, or a
+    // headless unit-test harness with no real cascade — so an explicit
+    // Number.isFinite() check falls through to each breakpoint's own
+    // documented REQ-M-006 default. This must be a real NaN check, not a
+    // `|| DEFAULT` fallback: `0` is a legitimate consumer override (e.g.
+    // `--table-toolbar-bp-overflow: 0rem` to disable the overflow stage
+    // entirely) and `||` would silently discard it as falsy, substituting
+    // the default instead — reviewer finding on PR #1676, fixed here.
+    // Whenever a real stylesheet IS present, the live custom property
+    // (overridable per-consumer, same posture as every other
+    // --table-toolbar-* token) wins, zero included.
+    const resolveBp = (raw, fallback) => {
+      const v = resolveLengthPx(raw);
+      return Number.isFinite(v) ? v : fallback;
+    };
+    const searchTightPx = resolveBp(cs.getPropertyValue('--table-toolbar-bp-search-tight'), DEFAULT_BP_SEARCH_TIGHT_PX);
+    const iconOnlyPx    = resolveBp(cs.getPropertyValue('--table-toolbar-bp-icon-only'),    DEFAULT_BP_ICON_ONLY_PX);
+    const overflowPx    = resolveBp(cs.getPropertyValue('--table-toolbar-bp-overflow'),     DEFAULT_BP_OVERFLOW_PX);
+
+    // Inclusive-on-the-narrower-side (max-width semantics, REQ-M-006) — a
+    // width exactly AT a boundary classifies to the narrower stage, same
+    // rule the CSS `@container (max-width: …)` conditions already encode.
+    if (widthPx <= overflowPx) return 'overflow';
+    if (widthPx <= iconOnlyPx) return 'icon-only';
+    if (widthPx <= searchTightPx) return 'search-tight';
+    return 'full';
+  }
+
+  #reflectResolvedStage() {
+    // REQ-O-001/REQ-M-005 — the pin wins for the reflection exactly as it
+    // wins for rendering: an explicit `stage` reports itself, never the
+    // width-derived classification, even inside a container sized for a
+    // different stage.
+    const resolved = this.stage || (this.#lastWidthPx == null ? 'full' : this.#classifyStage(this.#lastWidthPx));
+    // Is-different guard — same shape as chart.class.js's own
+    // data-ratio-resolved reflection (chart.class.js:533).
+    if (this.getAttribute('data-stage-resolved') !== resolved) {
+      this.setAttribute('data-stage-resolved', resolved);
+    }
   }
 
   render() {
@@ -186,6 +385,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) ────────────
@@ -273,6 +474,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', '');
@@ -288,12 +503,61 @@ 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);
+
+    // ADR-0076 REQ-S-003 — short-form compact text ("1–25/320"), a sibling
+    // of [data-summary-text] holding the SAME range values in a terser
+    // shape. Which of the two is visible is decided entirely by CSS
+    // (table-toolbar.css's icon-only @container rule / [stage] pin) —
+    // both nodes are always populated together in #updateSummary(), never
+    // a JS branch keyed on a resolved-stage signal (REQ-M-002 stays true:
+    // no JS decides rendering here, only which text each stage's CSS shows).
+    const summaryCompact = document.createElement('span');
+    summaryCompact.setAttribute('data-summary-compact', '');
+    summaryCompact.hidden = true;
+    summary.appendChild(summaryCompact);
+
+    // Empty-state slot (ADR-0076 REQ-E, adiav2 ADIA2-9123) — renders in
+    // [data-summary]'s own position, alongside [data-summary-text], never a
+    // separate region: only one of the two is ever visible at a time (see
+    // #updateSummary()). Same real-insertion-point pattern as [slot="scope"]
+    // / [slot="actions"] / [slot="actions-leading"] above — move any
+    // pre-existing [slot="empty"] children into this stamped wrapper rather
+    // than declaring a template-owned `parts:` entry (ADR-0067).
+    const summaryEmpty = document.createElement('div');
+    summaryEmpty.setAttribute('data-summary-empty', '');
+    summaryEmpty.hidden = true;
+    for (const node of [...this.children]) {
+      if (node === root) continue;
+      if (node.getAttribute?.('slot') === 'empty') {
+        summaryEmpty.appendChild(node);
+      }
+    }
+    summary.appendChild(summaryEmpty);
+
     // Controls cluster
     const controls = document.createElement('div');
     controls.setAttribute('data-controls', '');
     controls.appendChild(this.#mkButton('filter', 'Filter', 'funnel-simple'));
     controls.appendChild(this.#mkButton('sort', 'Sort', 'arrows-down-up'));
     controls.appendChild(this.#mkButton('columns', 'Columns', 'columns'));
+    // ADR-0076 REQ-S-004/REQ-X-003, PLAN step 5 — overflow-stage "More"
+    // trigger. Stamped unconditionally alongside the three granular
+    // buttons above (never removed/re-created), CSS-hidden except at the
+    // overflow breakpoint/pin (REQ-M-002 stays true: which cluster paints
+    // is a pure CSS decision, not a JS branch). Keeping all four buttons
+    // permanently in the DOM is the simplest way to honor REQ-X-004's
+    // tab-order guarantee — nothing is ever created/destroyed across a
+    // stage transition, only shown/hidden.
+    controls.appendChild(this.#mkOverflowTrigger());
 
     // Search — compose <search-ui>, which already stamps input-ui with
     // the magnifying-glass prefix + clear suffix and debounces a `search`
@@ -307,6 +571,38 @@ 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-leading slot passthrough (gh#1649) — a real insertion point
+    // (ADR-0067), same pattern as [slot="scope"]/[slot="actions"] above,
+    // rendered BEFORE the page-size select rather than after it: app-owned
+    // trigger buttons (e.g. custom Filter/Columns triggers that open the
+    // consumer's own drawer instead of the native filter/columns popovers)
+    // need to land ahead of page-size, which [slot="actions"] alone can't
+    // reach since it renders trailing (after page-size).
+    const actionsLeadingSlot = document.createElement('div');
+    actionsLeadingSlot.setAttribute('data-actions-leading', '');
+    // Move any pre-existing [slot="actions-leading"] children into this
+    // stamped wrapper — same real-insertion-point pattern as [slot="scope"]
+    // / [slot="actions"] above.
+    for (const node of [...this.children]) {
+      if (node === root) continue;
+      if (node.getAttribute?.('slot') === 'actions-leading') {
+        actionsLeadingSlot.appendChild(node);
+      }
+    }
+
     // Actions slot passthrough — we move any pre-existing [slot="actions"] children here
     const actionsSlot = document.createElement('div');
     actionsSlot.setAttribute('data-actions', '');
@@ -317,14 +613,20 @@ export class UITableToolbar extends UIElement {
       }
     }
 
+    root.appendChild(scopeSlot);
     root.appendChild(title);
+    root.appendChild(summary);
     root.appendChild(controls);
     root.appendChild(search);
+    root.appendChild(actionsLeadingSlot);
+    root.appendChild(pageSize);
     root.appendChild(actionsSlot);
 
     this.appendChild(root);
     this.#updateTitle();
+    this.#updateSummary();
     this.#updateControlVisibility();
+    this.#updatePageSizeSelect();
   }
 
   #mkPopoverAction(label, onClick) {
@@ -346,6 +648,14 @@ export class UITableToolbar extends UIElement {
     btn.setAttribute('variant', 'outline');
     btn.setAttribute('size', 'sm');
     btn.setAttribute('aria-haspopup', 'menu');
+    // ADR-0076 REQ-X-002 — unconditional (harmless at full-text stages,
+    // becomes the hover-tooltip affordance at the icon-only stage once
+    // the rendered label is CSS-hidden, REQ-M-003). button-ui's own
+    // title→aria-label mirror (button.class.js) only fires when no
+    // aria-label is already present — button-ui stamps aria-label from
+    // [text] unconditionally in its own render(), so this never conflicts
+    // with REQ-X-001's already-set accessible name.
+    btn.setAttribute('title', label);
     btn.addEventListener('click', (e) => {
       e.stopPropagation();
       this.#togglePopover(kind, btn);
@@ -353,6 +663,55 @@ export class UITableToolbar extends UIElement {
     return btn;
   }
 
+  // ADR-0076 REQ-S-004/REQ-X-003, PLAN step 5 — the overflow-stage "More"
+  // trigger. Reuses menu-ui/menu-item-ui unchanged (table-toolbar already
+  // `composes: menu-item-ui`; menu-ui is added to the yaml's composes list
+  // alongside it — no new runtime dependency, both already ship in this
+  // package) and routes every item straight through the EXISTING
+  // #togglePopover(kind, btn) — the same method the three granular buttons
+  // above call, never a reimplementation of filter/sort/columns logic.
+  #mkOverflowTrigger() {
+    const menu = document.createElement('menu-ui');
+    menu.setAttribute('data-toolbar-overflow', '');
+
+    const trigger = document.createElement('button-ui');
+    trigger.setAttribute('slot', 'trigger');
+    trigger.setAttribute('icon', 'dots-three-vertical');
+    trigger.setAttribute('variant', 'outline');
+    trigger.setAttribute('size', 'sm');
+    // REQ-X-003 — a genuinely new interactive element (not a repurposed
+    // existing button), so it needs its own static accessible name rather
+    // than an inherited one. No [text] attribute — always icon-only,
+    // button-ui's own render() reflects [data-icon-only] geometry from
+    // that (no CSS override needed here, unlike REQ-M-004's granular
+    // buttons which carry a real text label at wider stages).
+    trigger.setAttribute('aria-label', 'More table actions');
+    trigger.setAttribute('aria-haspopup', 'menu');
+    menu.appendChild(trigger);
+
+    for (const [kind, label, icon] of [
+      ['filter', 'Filter', 'funnel-simple'],
+      ['sort', 'Sort', 'arrows-down-up'],
+      ['columns', 'Columns', 'columns'],
+    ]) {
+      const item = document.createElement('menu-item-ui');
+      item.setAttribute('icon', icon);
+      item.setAttribute('text', label);
+      item.setAttribute('value', kind);
+      menu.appendChild(item);
+    }
+
+    // menu-ui fires `action` with { value, text } (menu.class.js's own
+    // #onItemClick) — anchor the resulting popover on the "More" trigger
+    // itself (not any of the three hidden granular buttons), same
+    // #togglePopover(kind, btn) every other entry point already calls.
+    menu.addEventListener('action', (e) => {
+      this.#togglePopover(e.detail.value, trigger);
+    });
+
+    return menu;
+  }
+
   #updateTitle() {
     const heading = this.querySelector(':scope [data-heading]');
     if (heading) {
@@ -397,29 +756,145 @@ 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.
+
+  // ADR-0076 REQ-E — the `empty` slot renders ONLY on an explicit
+  // range-total="0" (checked via hasAttribute, never the computed number
+  // alone — REQ-E-001/AC-013: an unset range-total, adiav2's loading state,
+  // must never flash the empty-state message). A positive range-total
+  // always wins over empty-slot content (REQ-E-002's additive guarantee /
+  // AC-014's mutual-exclusion check) — the two states can never render
+  // simultaneously.
+  #updateSummary() {
+    const summary = this.querySelector(':scope > [data-toolbar] > [data-summary]');
+    if (!summary) return;
+    const text = summary.querySelector(':scope > [data-summary-text]');
+    const compact = summary.querySelector(':scope > [data-summary-compact]');
+    const empty = summary.querySelector(':scope > [data-summary-empty]');
+    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) {
+      // Normal range text — always wins over the empty slot (AC-014).
+      // Both the full ("Showing X–Y of N") and short-form ("X–Y/N", ADR-0076
+      // REQ-S-003) strings are populated together — which one paints is a
+      // pure CSS decision (icon-only @container rule / [stage] pin), never
+      // a JS branch (REQ-M-002).
+      if (text) text.textContent = `Showing ${start}–${end} of ${total}`;
+      if (text) text.hidden = false;
+      if (compact) compact.textContent = `${start}–${end}/${total}`;
+      if (compact) compact.hidden = false;
+      if (empty) empty.hidden = true;
+      summary.hidden = false;
+      return;
+    }
+
+    const confirmedZero = this.hasAttribute('range-total') && this.getAttribute('range-total') === '0';
+    const hasEmptyContent = !!empty && empty.childNodes.length > 0;
+
+    if (confirmedZero && hasEmptyContent) {
+      // Explicit range-total="0" + author-supplied empty content (AC-011).
+      if (text) text.hidden = true;
+      if (compact) compact.hidden = true;
+      empty.hidden = false;
+      summary.hidden = false;
+      return;
+    }
+
+    // Loading (range-total unset, AC-013) or confirmed-zero-with-no-slot-
+    // content (AC-012) — hide [data-summary] exactly as today (REQ-E-002).
+    if (text) text.hidden = true;
+    if (compact) compact.hidden = true;
+    if (empty) empty.hidden = true;
+    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 },
+    }));
+  };
+
+  // ADR-0076 REQ-C-002 — `chromeOnly` is PURE, ABSOLUTE OR over the four
+  // granular `no-*` attributes: while set, all four stay off regardless of
+  // any individual `no-*` attribute's own value, with no partial re-enable
+  // path (AC-010). This is the ONLY place chromeOnly is combined with the
+  // granular attributes — never re-derive the OR elsewhere.
   #updateControlVisibility() {
     const root = this.querySelector(':scope > [data-toolbar]');
     if (!root) return;
 
+    const chromeOnly = this.chromeOnly;
     const setHidden = (sel, hidden) => {
       const el = root.querySelector(sel);
       if (el) el.hidden = hidden;
     };
 
-    setHidden('[data-toolbar-btn="filter"]',  this.noFilter);
-    setHidden('[data-toolbar-btn="sort"]',    this.noSort);
-    setHidden('[data-toolbar-btn="columns"]', this.noColumns);
-    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);
+    const filterHidden  = chromeOnly || this.noFilter;
+    const sortHidden    = chromeOnly || this.noSort;
+    const columnsHidden = chromeOnly || this.noColumns;
+
+    setHidden('[data-toolbar-btn="filter"]',  filterHidden);
+    setHidden('[data-toolbar-btn="sort"]',    sortHidden);
+    setHidden('[data-toolbar-btn="columns"]', columnsHidden);
+    setHidden('[data-search]',                chromeOnly || this.noSearch);
+
+    // ADR-0076 REQ-S-004, PLAN step 5 — the overflow "More" trigger's own
+    // menu-item-ui children mirror the SAME granular/chrome-only
+    // suppression as the three native buttons above: a control suppressed
+    // via no-*/chrome-only stays suppressed inside the overflow menu too,
+    // never resurrected there. Hide the whole trigger only once every item
+    // it would offer is suppressed — an empty "More" menu is worse than no
+    // trigger at all.
+    const overflow = root.querySelector('[data-toolbar-overflow]');
+    if (overflow) {
+      const hiddenByKind = { filter: filterHidden, sort: sortHidden, columns: columnsHidden };
+      for (const item of overflow.querySelectorAll('menu-item-ui')) {
+        item.hidden = !!hiddenByKind[item.getAttribute('value')];
+      }
+      overflow.hidden = filterHidden && sortHidden && columnsHidden;
     }
   }