@adia-ai/web-components 0.8.43 → 0.8.44

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

@@ -26,6 +26,30 @@
     --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
@@ -38,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] {
@@ -116,6 +285,26 @@
     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] {
@@ -125,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] {
@@ -140,6 +384,27 @@
 
   [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

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

@@ -1,5 +1,5 @@
 /**
- * `<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.
+ * `<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
  *
@@ -19,6 +19,8 @@ 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. */
@@ -43,6 +45,8 @@ export class UITableToolbar extends UIElement {
   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. */

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

@@ -9,16 +9,17 @@ description: >-
   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.
+  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:
@@ -29,6 +30,7 @@ composes:
   - field-ui
   - select-ui
   - input-ui
+  - menu-ui
   - menu-item-ui
   - icon-ui
   - check-ui
@@ -127,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
@@ -153,8 +202,33 @@ events:
 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.
@@ -186,6 +260,7 @@ requiredIcons:
   - arrow-up
   - arrow-down
   - caret-up-down
+  - dots-three-vertical
 a2ui:
   rules:
     - >-
@@ -223,6 +298,39 @@ a2ui:
       + [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
@@ -237,13 +345,20 @@ examples:
       ]
   - 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.
+      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-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": "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}

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.