@adia-ai/web-components 0.8.42 → 0.8.44

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

@@ -18,10 +18,38 @@
     --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;
 
+    /* ── Search-tight stage (ADR-0076, REQ-S-002) ──
+       Stepped-down search field extents applied under the
+       search-tight/icon-only/overflow @container query below (or the
+       matching [stage] pin). Public so a consumer can retune the
+       compacted width without forking component CSS, same posture as
+       every other --table-toolbar-* token. */
+    --table-toolbar-search-tight-min: 9rem;
+    --table-toolbar-search-tight-max: 14rem;
+
+    /* ── Compaction breakpoints (ADR-0076, REQ-M-006) ──
+       Normative default pixel widths, token-indirected so a consumer can
+       retune without forking component CSS. Boundaries are inclusive on
+       the narrower side (max-width semantics) — a container at exactly
+       the boundary width renders the narrower of the two adjacent
+       stages. MUST stay monotonically decreasing
+       (bp-search-tight > bp-icon-only > bp-overflow); no stage-specific
+       @container rules exist yet (step 1 lands only this substrate —
+       steps 2/3/5 land each stage's own CSS). Same three thresholds
+       data-stage-resolved's ResizeObserver (step 7) will classify
+       against — one source of truth, never a second hardcoded copy. */
+    --table-toolbar-bp-search-tight: 56rem;
+    --table-toolbar-bp-icon-only:    40rem;
+    --table-toolbar-bp-overflow:     26rem;
+
     /* Popover tokens removed — popover escapes to top layer and
        cannot inherit @scope tokens. Raw --a-* tokens are used
        directly in the unscoped popover rules below (see comment
@@ -34,6 +62,151 @@
     box-sizing: border-box;
     display: block;
     color: var(--md-sys-color-neutral-on-surface);
+    /* Width-only compaction measurement substrate (ADR-0076, REQ-M-001).
+       inline-size containment only — never `size` — per chart.css's own
+       documented size-containment trap (container-type: size forces
+       block-size containment, collapsing any height-less element; chart
+       needs it only because it queries aspect-ratio, table-toolbar's axis
+       is width alone). Steps 3/5 land icon-only/overflow's own CSS
+       against this same container. */
+    container-type: inline-size;
+    container-name: table-toolbar;
+  }
+
+  /* ═══════ Search-tight stage ═══════ (ADR-0076, REQ-S-002/REQ-O-001, step 2)
+     Auto-snap: the container query fires the step-down once the toolbar's
+     own inline-size crosses --table-toolbar-bp-search-tight (56rem
+     default). `max-width` is inclusive-on-the-narrower-side by construction
+     (REQ-M-006) — a container at exactly the boundary width already renders
+     search-tight. `:not([stage])`/`[stage=""]` together cover "no pin" —
+     an explicit [stage="full"] pin must NOT auto-snap even inside a narrow
+     container (REQ-O-001, the pin wins), so the auto-snap selector
+     excludes every OTHER pinned value too.
+
+     BUG (caught in review, CodeRabbit on PR #1672, verified live in a real
+     browser before fixing): the token reassignment below targets
+     `[data-toolbar]`, a DESCENDANT of `:scope` — never `:scope` itself. A
+     container query only matches elements whose NEAREST ANCESTOR
+     establishes the named container; the container element is never its
+     own ancestor, so `@container table-toolbar (...) { :scope { ... } }`
+     can never match the host that declared `container-type` in the first
+     place — it's permanently-dead CSS, regardless of the container's
+     actual width. The custom properties still cascade correctly from
+     `[data-toolbar]` down to `[data-search]` (a further descendant), so
+     targeting the wrapper one level down is both the fix and the reason
+     it works: normal inheritance, no container-query involvement needed
+     for the property to reach its consumer.
+
+     CSS custom properties cannot be referenced inside an `@container` size
+     query's condition (only `style()` container queries read custom
+     properties, and those query computed values, not literal breakpoints)
+     — so the boundary below is the literal `56rem`, bound in this comment
+     to --table-toolbar-bp-search-tight's own default one line above; the
+     table-toolbar.test.js source-assertion suite pins the two values equal
+     so this literal can never silently drift from the token. */
+  @container table-toolbar (max-width: 56rem) {
+    :scope:is(:not([stage]), [stage=""]) > [data-toolbar] {
+      --table-toolbar-search-min: var(--table-toolbar-search-tight-min);
+      --table-toolbar-search-max: var(--table-toolbar-search-tight-max);
+    }
+  }
+
+  /* Explicit pin (REQ-O-001) — forces the search-tight extents regardless
+     of the container's actual measured width. Also applies at
+     [stage="icon-only"]/[stage="overflow"] (steps 3/5's own, MORE compact
+     pins): each later stage is strictly more compact than the last
+     (REQ-S), so the search field never widens back out just because a
+     tighter stage hasn't landed its own CSS yet. */
+  :scope:is([stage="search-tight"], [stage="icon-only"], [stage="overflow"]) {
+    --table-toolbar-search-min: var(--table-toolbar-search-tight-min);
+    --table-toolbar-search-max: var(--table-toolbar-search-tight-max);
+  }
+
+  /* ═══════ Icon-only stage ═══════ (ADR-0076, REQ-S-003/REQ-M-003/REQ-M-004,
+     step 3) — [data-controls] buttons drop their rendered label; the range
+     summary's own compaction/hide (REQ-S-003, step 4) rides the SAME
+     breakpoint just below, since both are decided by the same container
+     crossing --table-toolbar-bp-icon-only.
+
+     ::after content:none overrides button.css's own `:scope[text]::after {
+     content: attr(text) }` generated-content rule (REQ-M-003) — aria-label
+     is untouched (button-ui stamps it from [text] unconditionally in its
+     own render(), REQ-X-001), so the accessible name survives regardless of
+     the CSS-hidden visual label. The selector below is deliberately more
+     specific than button.css's own (adds the `:scope` ancestor + `[text]`)
+     so it wins the cascade outright rather than relying on scope-proximity
+     tie-breaking, which would resolve in button.css's OWN favor at equal
+     specificity (its rule is proximity-0 to its own host). Geometry mirrors
+     button-ui's own [data-icon-only] treatment exactly (REQ-M-004) —
+     --button-px/width are button-ui's own exposed tokens, set here from the
+     table-toolbar side the same way [data-sort-row][data-active] overrides
+     menu-item-ui's tokens above. Literal `40rem` bound to
+     --table-toolbar-bp-icon-only's default (same duplication rationale +
+     source-assertion test as the search-tight boundary above). */
+  @container table-toolbar (max-width: 40rem) {
+    :scope:is(:not([stage]), [stage=""]) [data-toolbar-btn][text]::after {
+      content: none;
+    }
+    :scope:is(:not([stage]), [stage=""]) [data-toolbar-btn] {
+      --button-px: 0;
+
+      width: var(--button-height);
+    }
+  }
+
+  :scope:is([stage="icon-only"], [stage="overflow"]) [data-toolbar-btn][text]::after {
+    content: none;
+  }
+  :scope:is([stage="icon-only"], [stage="overflow"]) [data-toolbar-btn] {
+    --button-px: 0;
+
+    width: var(--button-height);
+  }
+
+  /* ═══════ Range-summary conditional compact/hide ═══════ (ADR-0076
+     REQ-S-003, step 4) — at the SAME icon-only breakpoint as above:
+       - [data-page-size] present AND visible (no [hidden]) → its own
+         pagination context already carries the range info, so [data-summary]
+         hides entirely (its info is genuinely redundant here).
+       - [data-page-size] absent/hidden → [data-summary] is the toolbar's
+         ONLY visible range context, so it never fully disappears; instead
+         it swaps its full text for the short form (see [data-summary-compact]
+         below, "1–25/320" vs "Showing 1–25 of 320").
+     Which branch applies is a pure :has()/:not() container-width read — no
+     JS drives this (REQ-M-002); #updateSummary() populates BOTH
+     [data-summary-text] and [data-summary-compact] together whenever a
+     valid range exists, and CSS alone decides which one paints. */
+  @container table-toolbar (max-width: 40rem) {
+    :scope:is(:not([stage]), [stage=""]):has([data-page-size]:not([hidden])) [data-summary] {
+      display: none;
+    }
+    :scope:is(:not([stage]), [stage=""]):not(:has([data-page-size]:not([hidden]))) [data-summary-text] {
+      display: none;
+    }
+    /* :not([hidden]) — reviewer finding on PR #1674: without it, this
+       author-origin `display: inline` OUTRANKS the UA-origin
+       `[hidden] { display: none }` rule regardless of specificity (origin
+       comes before specificity in the cascade), so a JS-hidden
+       [data-summary-compact] (#updateSummary()'s empty-slot/loading
+       branches, which set compact.hidden = true) would still paint —
+       stale compact text alongside the empty-state content after a
+       positive range transitions to range-total="0" in icon-only mode.
+       Same class of gotcha this file already reinforces explicitly for
+       every other JS-toggled node ([data-toolbar-btn][hidden],
+       [data-search][hidden], [data-toolbar-overflow][hidden], etc). */
+    :scope:is(:not([stage]), [stage=""]):not(:has([data-page-size]:not([hidden]))) [data-summary-compact]:not([hidden]) {
+      display: inline;
+    }
+  }
+
+  :scope:is([stage="icon-only"], [stage="overflow"]):has([data-page-size]:not([hidden])) [data-summary] {
+    display: none;
+  }
+  :scope:is([stage="icon-only"], [stage="overflow"]):not(:has([data-page-size]:not([hidden]))) [data-summary-text] {
+    display: none;
+  }
+  :scope:is([stage="icon-only"], [stage="overflow"]):not(:has([data-page-size]:not([hidden]))) [data-summary-compact]:not([hidden]) {
+    display: inline;
   }
 
   [data-toolbar] {
@@ -68,6 +241,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 +271,40 @@
 
   [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);
+  }
+
+  /* Short-form compact text ("1–25/320", ADR-0076 REQ-S-003) — hidden by
+     default (`display: none`, not just [hidden]) since it only ever paints
+     inside the icon-only-without-page-size branch above; that branch is the
+     ONLY place this flips to `display: inline`. Same typography as
+     [data-summary-text] — it's the same information, just terser. */
+  [data-summary-compact] {
+    display: none;
+    font-size: var(--table-toolbar-summary-size);
+    color: var(--table-toolbar-summary-fg);
+    line-height: var(--a-font-leading-snug);
+  }
+
+  /* ═══════ Empty-state slot ═══════ (ADR-0076 REQ-E — renders in
+     [data-summary]'s own position, alongside [data-summary-text]; only one
+     of the two is ever visible at a time, per #updateSummary(). Plain
+     author-supplied markup (REQ-E-003) — no forced typography here, unlike
+     [data-summary-text] above, which styles OUR OWN generated text. */
+
+  [data-summary-empty][hidden] { display: none; }
+
   /* ═══════ Controls cluster ═══════ */
 
   [data-controls] {
@@ -96,8 +314,63 @@
     flex: 0 0 auto;
   }
 
+  /* ADR-0076 REQ-C-003 — with [chrome-only] set, all three buttons carry
+     [hidden] (see #updateControlVisibility()); this collapses the cluster
+     to zero footprint via the same :empty{display:none} shape [data-scope]/
+     [data-actions]/[data-actions-leading] already use above, defensively
+     covering the case where no button children are stamped at all. */
+  [data-controls]:empty { display: none; }
+
   [data-toolbar-btn][hidden] { display: none; }
 
+  /* ═══════ Overflow stage ═══════ (ADR-0076 REQ-S-004/REQ-X-003/004,
+     PLAN step 5) — collapses Filter/Sort/Columns into one "More" trigger
+     at the tightest breakpoint. The three granular buttons STAY in the
+     DOM (never created/destroyed across a stage transition — the simplest
+     way to keep REQ-X-004's tab-order guarantee correct); CSS alone
+     decides which cluster paints (REQ-M-002). [data-toolbar-overflow] is
+     the <menu-ui> wrapper stamped by #mkOverflowTrigger() — hiding/showing
+     it hides/shows its [slot="trigger"] button together with its (closed)
+     menu-item-ui children in one rule, matching how every other stage
+     toggle in this file targets one wrapper element rather than each
+     child individually. Literal `26rem` bound to
+     --table-toolbar-bp-overflow's own default (same duplication +
+     source-assertion discipline as the search-tight/icon-only boundaries
+     above). */
+  [data-toolbar-overflow] { display: none; }
+
+  @container table-toolbar (max-width: 26rem) {
+    :scope:is(:not([stage]), [stage=""]) [data-toolbar-btn] {
+      display: none;
+    }
+    :scope:is(:not([stage]), [stage=""]) [data-toolbar-overflow] {
+      display: inline-flex;
+    }
+  }
+
+  :scope[stage="overflow"] [data-toolbar-btn] {
+    display: none;
+  }
+  :scope[stage="overflow"] [data-toolbar-overflow] {
+    display: inline-flex;
+  }
+
+  /* [hidden] (per-kind chrome-only/no-* suppression, #updateControlVisibility())
+     must win over the stage-driven `display: inline-flex` rules above —
+     both for the reason `[data-toolbar-btn][hidden]`/`[data-search][hidden]`
+     etc reinforce it above (the browser's own UA-origin `[hidden]{display:
+     none}` rule is LOWER origin priority than any author rule, so an
+     unreinforced [hidden] would lose to author CSS) AND because this
+     selector must match or exceed the (0,3,0) specificity of the
+     `:scope … [data-toolbar-overflow]` show-rules above to win the tie —
+     `:scope [data-toolbar-overflow][hidden]` (0,3,0), placed after both in
+     source order, satisfies that. This covers the whole-trigger-suppressed
+     case (chrome-only, or all three no-* set) — the per-menu-item-ui
+     hidden state inside the (closed) menu needs no CSS help since
+     [hidden]'s UA default applies cleanly to a plain child with no
+     conflicting author rule. */
+  :scope [data-toolbar-overflow][hidden] { display: none; }
+
   /* ═══════ Search ═══════ */
 
   [data-search] {
@@ -111,6 +384,44 @@
 
   [data-search][hidden] { display: none; }
 
+  /* ═══════ Actions-leading slot ═══════ (gh#1649 — app-owned triggers, e.g.
+     custom Filter/Columns buttons, that land BEFORE the page-size select)
+     Carries the SAME margin-inline-start:auto as [data-search]/[data-page-size]
+     so the trailing group still pushes to the far edge even when EVERY
+     native affordance ahead of it is dropped ([no-search] + [no-filter]/
+     [no-sort]/[no-columns], the adiav2 shape) and this slot becomes the
+     first visible member of the trailing cluster. Multiple auto-margin
+     siblings in one flex row is safe — only the first one with unclaimed
+     free space to its left actually receives it (same note as [data-page-size]
+     below). */
+
+  [data-actions-leading] {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--table-toolbar-cluster-gap);
+    flex: 0 0 auto;
+    margin-inline-start: auto;
+  }
+
+  [data-actions-leading]:empty { 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 [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.
  *
  * @see https://ui-kit.exe.xyz/site/components/table-toolbar
  *
@@ -14,10 +14,13 @@ 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>;
 
 export class UITableToolbar extends UIElement {
+  /** 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. */
+  chromeOnly: boolean;
   /** Optional count badge value shown next to the title. When unset, falls back to the row count of the bound table. */
   count: string;
   /** id-ref of the table-ui to control. Falls back to the first sibling table-ui within the same parent when omitted. */
@@ -30,8 +33,20 @@ 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;
+  /** 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). */
+  stage: '' | 'full' | 'search-tight' | 'icon-only' | 'overflow';
   /** 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 +54,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>(