@adia-ai/web-components 0.8.44 → 0.8.46

package/components/table-footer/table-footer.yaml

@@ -0,0 +1,219 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITableFooter
+tag: table-footer-ui
+status: beta
+component: TableFooter
+category: agent
+version: 1
+description: >-
+  Footer / companion bar for a sibling table-ui (gh#1807, ADR-0080) — a
+  "Showing X–Y of N" range label paired with a composed pagination-ui.
+  Derivation-model API: set `page` / `page-size` / `range-total` and the
+  footer derives total pages and the range window itself, so it never
+  drifts out of sync with its own pager. Wired to the target table via a
+  [for] id-ref and CustomEvents only (ADR-0079/ADR-0080) — the footer never
+  writes a property or calls a method on the bound table. Drop below (or
+  inside a card-ui footer alongside) any table-ui to add the standard
+  data-grid pager + range summary without re-implementing pagination-ui's
+  ellipsis truncation, keyboard handling, or ARIA.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - pagination-ui
+props:
+  for:
+    description: id-ref of the table-ui to control. Falls back to the first sibling table-ui within the same parent when omitted.
+    type: string
+    default: ""
+    reflect: true
+  page:
+    description: >-
+      Current page, 1-based. Explicit attributes always win over derivation
+      (per-attribute, not all-or-nothing) — see page-size/range-total.
+    type: number
+    default: 1
+    reflect: true
+  page-size:
+    description: >-
+      Rows per page. Default 0 (unknown) is the ORDINARY default state, not
+      an exotic edge case: with page-size absent/0 and range-total present,
+      the range label renders in count-only form ("128 items") and the
+      pager does not render — the derivation math (pages = range-total /
+      page-size) is undefined without a page size. In a client-mode
+      composition (the resolved target has [paginate] > 0) and this
+      attribute is unset, the footer derives page-size from the target's
+      own [paginate] value.
+    type: number
+    default: 0
+    reflect: true
+  range-total:
+    description: >-
+      Total ROWS across all pages. Absent (the default) means "not yet
+      known" (loading) — never "zero"; both the range label and the pager
+      stay hidden until this is set. Explicit range-total="0" is the
+      confirmed-empty state (pager hidden; the `empty` slot renders in the
+      range label's position when supplied). Named identically to
+      table-toolbar-ui's [range-total] and table-ui's own [range-total]
+      (gh#1754, ADR-0082) and deliberately NOT `total` (pagination-ui's
+      `total` is total PAGES — the ADR-0063 B5 collision rule). When this
+      attribute is unset, the footer derives it from the resolved target
+      via a two-branch ladder (REQ-W-006, amended 0.2.0/ADR-0082):
+      (1) the target's own [range-total] attribute, when present — the
+      table-authoritative SERVER mode (gh#1754 Shape 1's second lawful
+      composition); the identity rule: the footer's range-total derives
+      from the table's range-total, never the table's filteredCount, and
+      this branch wins even when the target's [paginate] is also > 0;
+      (2) otherwise, when the target has [paginate] > 0, CLIENT mode: the
+      target's filtered row count (search + column filters applied, before
+      pagination). Refreshes on the target's `page` / `filter-change` /
+      `sort` events in either branch. Widened named staleness edge: a
+      programmatic `.data` swap on the target — or a `range-total` update
+      on the target without an accompanying page move — emits no event;
+      either re-set this footer's own attributes after such a change, or
+      accept staleness until the target's next event.
+    type: number
+    default: 0
+    reflect: true
+  siblings:
+    description: Passed through to the composed pagination-ui's own [siblings] (page-number window size on each side of the current page).
+    type: number
+    default: 1
+    reflect: true
+  size:
+    description: Passed through to the composed pagination-ui's own [size] (sm | md | lg, the universal size system).
+    type: string
+    default: md
+    reflect: true
+events:
+  footer-page:
+    description: >-
+      gh#1807, ADR-0080 (events-only interaction contract, extending
+      ADR-0079's sender-prefixed toolbar-* precedent to a second sender) —
+      dispatched directly at the resolved [for] target on every pager
+      interaction. Detail: { page } (1-based). table-ui listens for this on
+      itself, applied only when [paginate] > 0 (clamped to the valid page
+      range; a non-numeric/NaN detail.page is a no-op); at [paginate="0"]
+      the command is a documented no-op on the table. Additive: any
+      consumer, not only table-footer-ui, may dispatch this at a table-ui.
+  page-change:
+    description: >-
+      The footer's own consumer-facing notification — a distinct name from
+      the inbound footer-page command (ADR-0079's command≠notification
+      separation). Fires on every pager interaction, in both client- and
+      server-mode. Detail: { page } (1-based). This is the server-mode
+      fetch hook: a consumer listens for it, fetches the new page, then
+      sets `table.data` and the footer's own `page` (and `range-total` if
+      the server's total moved) — the footer never optimistically advances
+      its own state in server-mode.
+slots:
+  empty:
+    description: >-
+      Renders in place of the range label — the same [data-range] 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). Mutually
+      exclusive with a positive [range-total]: the normal "Showing X–Y of N"
+      (or count-only) text always wins whenever range-total resolves
+      positive. Plain author-supplied markup — table-footer-ui does not
+      template or constrain its shape. Naming matches table-toolbar-ui's own
+      `empty` slot convention.
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens:
+  --table-footer-gap:
+    description: Gap between the range label and the pager
+  --table-footer-py:
+    description: Vertical padding
+  --table-footer-px:
+    description: Horizontal padding
+  --table-footer-summary-fg:
+    description: Range-label text color
+  --table-footer-summary-size:
+    description: Range-label font size
+a2ui:
+  rules:
+    - >-
+      Pair <table-footer-ui> with <table-ui> via [for="<table-id>"] (or
+      rely on first-sibling fallback when both are inside the same parent).
+      Client-mode composition (a [paginate]-sliced table): set [no-pager]
+      on the table-ui so its own internal pagination bar doesn't render
+      alongside the footer's composed one — table-footer-ui never
+      auto-suppresses it for you.
+    - >-
+      Server-mode composition (gh#1754 Shape 1 — the server returns the
+      page's rows plus the total row count): set [range-total] to the
+      server's total, [page] / [page-size] from your own request state, and
+      listen for the footer's `page-change` event to fetch the next page —
+      the footer does not optimistically advance its own [page] in
+      server-mode; write it back after the fetch resolves.
+    - >-
+      The toolbar's [count] badge and this footer's range label coexist by
+      design — they answer different questions (the collection summary vs.
+      the page-window position) and neither replaces the other. In a
+      composition that includes a table-footer-ui, leave the toolbar's
+      [range-start]/[range-end]/[range-total] unset — the range summary's
+      home is the footer.
+    - >-
+      Canonical composition: card-ui header (title + primary action) →
+      a plain <section> wrapping a title-less <table-toolbar-ui for> → a
+      <section bleed> wrapping the <table-ui id> → a <footer divider>
+      wrapping this <table-footer-ui for> — see the table-in-card pattern.
+    - >-
+      Use <span slot="empty"> (or any markup) inside a table-footer-ui that
+      also sets [range-total="0"] to show a "no results" message in the
+      range label's own position, without a layout shift versus the normal
+      range text. Only fires on an EXPLICIT range-total="0" — omitting
+      range-total entirely (loading) never shows it.
+anti_patterns:
+  - wrong: '<table-footer-ui range-start="1" range-end="10" range-total="128"></table-footer-ui>'
+    why: >-
+      table-footer-ui is derivation-only (REQ-F-002) — there is no
+      [range-start]/[range-end] attribute pair (that shape belongs to
+      table-toolbar-ui, which has no page/page-size knowledge of its own).
+      Setting [page] + [page-size] + [range-total] derives the range window
+      instead; a permanent three-way drift hazard is exactly what the
+      derivation model exists to avoid.
+    fix: '<table-footer-ui page="1" page-size="10" range-total="128"></table-footer-ui>'
+examples:
+  - name: table-footer-server-mode
+    description: Server-mode footer (gh#1754 Shape 1) paired with a for=-bound table-ui.
+    a2ui: >-
+      [
+        {"id": "root", "component": "Column", "gap": "0", "children": ["tests", "ftr"]},
+        {"id": "tests", "component": "Table", "raw": true},
+        {"id": "ftr", "component": "TableFooter", "for": "tests", "page": 1, "page-size": 10, "range-total": 128}
+      ]
+  - name: table-footer-client-mode
+    description: Client-mode footer bound to a [paginate]d table-ui with its own internal pager suppressed via [no-pager].
+    a2ui: >-
+      [
+        {"id": "root", "component": "Column", "gap": "0", "children": ["tests-c", "ftr"]},
+        {"id": "tests-c", "component": "Table", "paginate": 10, "no-pager": true, "raw": true},
+        {"id": "ftr", "component": "TableFooter", "for": "tests-c"}
+      ]
+keywords:
+  - table-footer
+  - pagination
+  - pager
+  - range
+  - showing
+  - data-grid
+  - directory
+  - admin
+  - backoffice
+  - listing
+  - records
+synonyms:
+  pagination:
+    - table-footer
+    - pagination
+  pager:
+    - table-footer
+    - pagination
+related:
+  - table
+  - table-toolbar
+  - pagination
+  - card

package/components/table-toolbar/table-toolbar.a2ui.json

@@ -142,6 +142,21 @@
       },
       "sort-change": {
         "description": "Sort state changed. Detail: { sortState }."
+      },
+      "toolbar-columns-set": {
+        "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.columns =` write. table-ui listens for this on itself. Detail: { columns }."
+      },
+      "toolbar-filter-clear": {
+        "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.clearFilters()` call. table-ui listens for this on itself. No detail."
+      },
+      "toolbar-filter-set": {
+        "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.setFilter()` call. table-ui listens for this on itself. Detail: { key, value, op }; a null `value` clears that one column's filter."
+      },
+      "toolbar-paginate": {
+        "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.paginate =` write. table-ui listens for this on itself. Detail: { pageSize }."
+      },
+      "toolbar-search": {
+        "description": "gh#1764/#1780, ADR-0079 (events-only interaction contract) — dispatched directly at the resolved [for] target (not bubbled from this element) in place of the pre-#1780 direct `.search =` write. table-ui listens for this on itself. Detail: { value }."
       }
     },
     "examples": [

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

@@ -29,11 +29,22 @@
  * Popovers use the platform Popover API + core/anchor.js, the same primitives
  * that menu-ui / popover-ui / toolbar-ui already use in this package.
  *
- * State flow:
- *   search        → table.search       (string property)
- *   filters       → table.setFilter()  (per-key)
- *   sort          → simulated click on table's [data-sort-key] header
- *   column hidden → table.columns =    (clone with hidden flag flipped)
+ * State flow — events-only interaction contract (gh#1764/#1780, ADR-0079;
+ * mirrors chart-legend-ui↔chart-ui's own bubbling-CustomEvent model). The
+ * toolbar never writes a property or calls a method on the bound table
+ * directly — every command is a `toolbar-*` CustomEvent dispatched AT the
+ * resolved target, which table.class.js listens for in its own
+ * connected()/disconnected() and applies via its existing public surface:
+ *   search        → `toolbar-search`        { value }          → table.search =
+ *   filters       → `toolbar-filter-set`    { key, value, op }  → table.setFilter()
+ *   filters clear → `toolbar-filter-clear`  {}                  → table.clearFilters()
+ *   sort          → simulated click on table's [data-sort-key] header (already
+ *                   event-shaped — a real DOM event dispatched at the target,
+ *                   not a property write; left as-is, see gh#1780's PR notes)
+ *   column hidden → `toolbar-columns-set`   { columns }         → table.columns =
+ *   page size     → `toolbar-paginate`      { pageSize }        → table.paginate =
+ * The table→toolbar direction (`sort`, `filter-change` listened on #target)
+ * was already events-only and is unchanged.
  */
 
 import { UIElement } from '../../core/element.js';
@@ -846,11 +857,16 @@ export class UITableToolbar extends UIElement {
   #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;
+    // gh#1764/#1780 (events-only interaction contract, ADR-0079) — the
+    // bound table applies its own [paginate] through the `toolbar-paginate`
+    // command event rather than a direct property write; table.class.js
+    // listens for it in connected() and sets `this.paginate` itself.
+    if (this.#target) {
+      this.#target.dispatchEvent(new CustomEvent('toolbar-paginate', {
+        bubbles: true,
+        detail: { pageSize },
+      }));
+    }
     this.dispatchEvent(new CustomEvent('page-size-change', {
       bubbles: true,
       detail: { pageSize },
@@ -902,7 +918,15 @@ export class UITableToolbar extends UIElement {
 
   #onSearch = (e) => {
     const value = e.detail?.value ?? '';
-    if (this.#target) this.#target.search = value;
+    // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+    // `toolbar-search` replaces the direct `.search =` write; table.class.js
+    // listens for it in connected() and sets `this.search` itself.
+    if (this.#target) {
+      this.#target.dispatchEvent(new CustomEvent('toolbar-search', {
+        bubbles: true,
+        detail: { value },
+      }));
+    }
     this.dispatchEvent(new CustomEvent('search', {
       bubbles: true,
       detail: { value },
@@ -1044,8 +1068,14 @@ export class UITableToolbar extends UIElement {
         }
         sel.addEventListener('change', () => {
           const v = sel.value || '';
-          if (v) target.setFilter(col.key, v, 'select');
-          else target.setFilter(col.key, null);
+          // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+          // `toolbar-filter-set` replaces the direct target.setFilter()
+          // call; table.class.js applies it synchronously in its own
+          // listener, so `target.filters` below already reflects it.
+          target.dispatchEvent(new CustomEvent('toolbar-filter-set', {
+            bubbles: true,
+            detail: { key: col.key, value: v || null, op: 'select' },
+          }));
           this.dispatchEvent(new CustomEvent('filter-change', {
             bubbles: true,
             detail: { filters: target.filters },
@@ -1061,8 +1091,12 @@ export class UITableToolbar extends UIElement {
         if (current?.op === 'contains') input.value = current.value ?? '';
         input.addEventListener('input', () => {
           const v = input.value;
-          if (v) target.setFilter(col.key, v, 'contains');
-          else target.setFilter(col.key, null);
+          // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+          // see the select-filter handler above for the same normalization.
+          target.dispatchEvent(new CustomEvent('toolbar-filter-set', {
+            bubbles: true,
+            detail: { key: col.key, value: v || null, op: 'contains' },
+          }));
           this.dispatchEvent(new CustomEvent('filter-change', {
             bubbles: true,
             detail: { filters: target.filters },
@@ -1078,7 +1112,11 @@ export class UITableToolbar extends UIElement {
 
     if (Object.keys(filters).length) {
       const clear = this.#mkPopoverAction('Clear all filters', () => {
-        target.clearFilters();
+        // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+        // `toolbar-filter-clear` replaces the direct target.clearFilters()
+        // call; table.class.js applies it synchronously in its own
+        // listener before #refreshFilterPanel() re-reads target.filters.
+        target.dispatchEvent(new CustomEvent('toolbar-filter-clear', { bubbles: true }));
         this.dispatchEvent(new CustomEvent('filter-change', {
           bubbles: true,
           detail: { filters: {} },
@@ -1227,7 +1265,13 @@ export class UITableToolbar extends UIElement {
         const next = target.columns.map((c) => (
           c.key === col.key ? { ...c, hidden: !check.hasAttribute('checked') } : { ...c }
         ));
-        target.columns = next;
+        // gh#1764/#1780 (events-only interaction contract, ADR-0079) —
+        // `toolbar-columns-set` replaces the direct target.columns= write;
+        // table.class.js applies it synchronously in its own listener.
+        target.dispatchEvent(new CustomEvent('toolbar-columns-set', {
+          bubbles: true,
+          detail: { columns: next },
+        }));
         this.dispatchEvent(new CustomEvent('columns-change', {
           bubbles: true,
           detail: { hiddenColumns: next.filter((c) => c.hidden).map((c) => c.key) },

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

@@ -163,6 +163,40 @@
     width: var(--button-height);
   }
 
+  /* ═══════ Actions-leading icon-only reduction ═══════ (gh#1748) — extends
+     the SAME icon-only collapse above to a plain <button-ui> a consumer
+     slots into [slot="actions-leading"] (gh#1649, e.g. the app-owned
+     Filter/Columns triggers on the ratified adiav2 row), so it reads as
+     part of the same toolbar affordance cluster rather than staying
+     full-width while its native siblings compact. A separate rule block
+     (rather than folding into [data-toolbar-btn]'s own selector list above)
+     keeps that block's literal text byte-identical for its own
+     source-assertion tests. Same breakpoint/pin pair, same
+     aria-label-survives guarantee (button-ui's own REQ-X-001 stamp,
+     unaffected here) — light-DOM real insertion point (no shadow
+     boundary), so a plain descendant tag selector reaches it directly, no
+     `::slotted()` needed. Literal `40rem` bound to
+     --table-toolbar-bp-icon-only's default, same as the native block. */
+  @container table-toolbar (max-width: 40rem) {
+    :scope:is(:not([stage]), [stage=""]) [data-actions-leading] button-ui[text]::after {
+      content: none;
+    }
+    :scope:is(:not([stage]), [stage=""]) [data-actions-leading] button-ui {
+      --button-px: 0;
+
+      width: var(--button-height);
+    }
+  }
+
+  :scope:is([stage="icon-only"], [stage="overflow"]) [data-actions-leading] button-ui[text]::after {
+    content: none;
+  }
+  :scope:is([stage="icon-only"], [stage="overflow"]) [data-actions-leading] button-ui {
+    --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

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

@@ -17,6 +17,11 @@ export type TableToolbarFilterChangeEvent = CustomEvent<unknown>;
 export type TableToolbarPageSizeChangeEvent = CustomEvent<unknown>;
 export type TableToolbarSearchEvent = CustomEvent<unknown>;
 export type TableToolbarSortChangeEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarColumnsSetEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarFilterClearEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarFilterSetEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarPaginateEvent = CustomEvent<unknown>;
+export type TableToolbarToolbarSearchEvent = 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. */
@@ -57,6 +62,11 @@ export class UITableToolbar extends UIElement {
   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(type: 'toolbar-columns-set', listener: (ev: TableToolbarToolbarColumnsSetEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-filter-clear', listener: (ev: TableToolbarToolbarFilterClearEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-filter-set', listener: (ev: TableToolbarToolbarFilterSetEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-paginate', listener: (ev: TableToolbarToolbarPaginateEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toolbar-search', listener: (ev: TableToolbarToolbarSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
     listener: (this: UITableToolbar, ev: HTMLElementEventMap[K]) => unknown,

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

@@ -199,6 +199,33 @@ events:
     description: "Column visibility changed. Detail: { hiddenColumns }."
   page-size-change:
     description: "Page-size select changed. Detail: { pageSize }."
+  toolbar-search:
+    description: >-
+      gh#1764/#1780, ADR-0079 (events-only interaction contract) — dispatched
+      directly at the resolved [for] target (not bubbled from this element)
+      in place of the pre-#1780 direct `.search =` write. table-ui listens
+      for this on itself. Detail: { value }.
+  toolbar-filter-set:
+    description: >-
+      gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for]
+      target in place of the pre-#1780 direct `target.setFilter()` call.
+      table-ui listens for this on itself. Detail: { key, value, op }; a
+      null `value` clears that one column's filter.
+  toolbar-filter-clear:
+    description: >-
+      gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for]
+      target in place of the pre-#1780 direct `target.clearFilters()` call.
+      table-ui listens for this on itself. No detail.
+  toolbar-columns-set:
+    description: >-
+      gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for]
+      target in place of the pre-#1780 direct `target.columns =` write.
+      table-ui listens for this on itself. Detail: { columns }.
+  toolbar-paginate:
+    description: >-
+      gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for]
+      target in place of the pre-#1780 direct `target.paginate =` write.
+      table-ui listens for this on itself. Detail: { pageSize }.
 slots:
   scope:
     description: Leading region rendered BEFORE the [text]/[count] title cluster — e.g. a scope/view-switcher menu (an org's teams, a saved view). Positioning is CSS by DOM order, mirroring how [slot="actions"] is a real, author-fillable insertion point rather than template-stamped content.
@@ -266,18 +293,29 @@ a2ui:
     - >-
       Pair <table-toolbar-ui> with <table-ui> via [for="<table-id>"]
       (or rely on first-sibling fallback when both are inside the
-      same parent). One toolbar per table. Do NOT also use
-      <card-ui>'s <header> on the same card — that produces a doubled
-      chrome row.
+      same parent). One toolbar per table. The doubled-chrome hazard is
+      a TITLE COLLISION, not a blanket card-header ban (gh#1807, SPEC
+      REQ-C-004): a toolbar carrying [text] must not share a card with
+      a heading-slotted <card-ui> <header> — that pairing doubles the
+      title row. A title-less toolbar (no [text]) inside a card whose
+      <header> owns the title is the canonical table-in-card
+      composition (see the table-in-card pattern) and is NOT doubled
+      chrome — the toolbar renders only its count/search/filter/sort/
+      columns cluster, with the title living in the card header alone.
     - >-
       All four affordances (search, filter, sort, columns) default ON.
       Opt out individually via [no-search] / [no-filter] / [no-sort]
       / [no-columns]. The previous [searchable] / [filterable]
       attributes are deprecated — do NOT emit them.
     - >-
-      Place the toolbar ABOVE the <card-ui> containing the table-ui,
-      or use [variant="card"] when standing alone outside a card-ui
-      parent (the variant wraps the toolbar in card-style chrome).
+      Three legitimate placements: ABOVE the <card-ui> containing the
+      table-ui; standing alone outside a card-ui parent with
+      [variant="card"] (wraps the toolbar in card-style chrome); or
+      INSIDE the card, in its own plain (non-bleed) <section> between
+      the card header and the bleed table section — the canonical
+      table-in-card shape (gh#1807) — title-less (no [text]) since the
+      card header already owns the title (see the title-collision rule
+      above).
     - >-
       Use slot="action" (or [slot="actions"]) for trailing primary
       buttons (Invite, Export, +New). Use [text] / [count] props for
@@ -322,15 +360,20 @@ a2ui:
       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.
+      A plain <button-ui> slotted into [slot="actions-leading"] (e.g. the
+      app-owned Filter/Columns triggers above) already collapses to
+      icon-only at the SAME breakpoint as the native Filter/Sort/Columns
+      buttons (gh#1748) — no consumer JS/CSS required. Read the host's
+      [data-stage-resolved] attribute (ADR-0076 REQ-M-005, ADIA2-9123
+      S4-ii) only for compaction BEYOND plain icon-only reduction — e.g.
+      hiding a slotted button entirely at the overflow stage, or reacting
+      to the stage in a consumer's own drawer/menu — 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

package/core/data-stream.js

@@ -37,6 +37,14 @@
  *   stream-load   — first signal value received for this element
  *   stream-update — each subsequent value, detail.data = the new value
  *   stream-error  — transport-level error, detail.error = message
+ *
+ * Opting out (gh#1760):
+ *   `data-stream-managed="false"` tells the document-level observer to
+ *   never claim this element, even though it carries `data-stream-src`.
+ *   For elements that own their own imperative fetch (e.g. the billing
+ *   composites' `refresh()`) and must not also be claimed by this module —
+ *   never mix an imperative fetch with an unmanaged `data-stream-src` on
+ *   the same element (data-stream-protocol.md §10.1).
  */
 
 import { signal, effect, untracked } from './signals.js';
@@ -54,6 +62,11 @@ const ATTRS = {
   merge:     'data-stream-merge',
   format:    'data-stream-format',
   id:        'data-stream-id',
+  // gh#1760 — opt-out for elements that carry `data-stream-src` but manage
+  // their own fetch (e.g. the billing composites' hand-rolled `refresh()`).
+  // `"false"` tells the document-level observer to never claim this element,
+  // so exactly one owner (the element's own imperative fetch) ever runs.
+  managed:   'data-stream-managed',
 };
 
 const STREAMS = new Map();           /* streamId → { signal, refs, transport, opts } */
@@ -386,6 +399,7 @@ function applyData(el, raw, opts) {
 export function start(el) {
   stop(el);
   if (!el.isConnected) return;
+  if (attr(el, 'managed') === 'false') return; // gh#1760 — self-managed opt-out
   const src = attr(el, 'src');
   if (!src) return;
 
@@ -442,7 +456,8 @@ export function stop(el) {
 const ATTR_FILTER = Object.values(ATTRS);
 
 function isStreamingEl(node) {
-  return node && node.nodeType === 1 && node.hasAttribute && node.hasAttribute(ATTRS.src);
+  return !!(node && node.nodeType === 1 && node.hasAttribute && node.hasAttribute(ATTRS.src)
+    && node.getAttribute(ATTRS.managed) !== 'false');
 }
 
 function visitSubtree(root, fn) {
@@ -476,11 +491,31 @@ const observer = typeof MutationObserver !== 'undefined'
 
 function bootstrap() {
   if (typeof document === 'undefined') return;
+  // Register the observer synchronously — no live mutation is missed.
   observer?.observe(document.documentElement, {
     childList: true, subtree: true,
     attributes: true, attributeFilter: ATTR_FILTER,
   });
-  document.querySelectorAll(`[${ATTRS.src}]`).forEach(start);
+  // gh#1760 — defer the INITIAL sweep of already-present markup by one
+  // microtask. Without this, a page whose entry module imports the core
+  // barrel (this module) BEFORE a self-managed composite's own module
+  // (which sets `data-stream-managed="false"` synchronously from its
+  // upgrade-triggered `connectedCallback`) races: this sweep would claim
+  // pre-existing SSR markup before the composite ever gets a chance to
+  // opt out. Deferring to a microtask lets the rest of the SAME
+  // synchronous module-evaluation phase — including every sibling
+  // module's own top-level side effects — finish first, so by the time
+  // this sweep runs, every already-loaded composite has already set its
+  // marker. (A composite loaded asynchronously — a dynamic `import()` —
+  // after this microtask has already fired is not covered by this
+  // deferral alone; its own `connected()` marker-set plus the observer's
+  // live attribute-mutation handling still tears down a wrongly-started
+  // stream, bounding the damage to at most one extra fetch.)
+  queueMicrotask(() => {
+    document.querySelectorAll(`[${ATTRS.src}]`).forEach((el) => {
+      if (isStreamingEl(el)) start(el);
+    });
+  });
 }
 
 if (typeof document !== 'undefined') {

package/core/index.d.ts

@@ -9,6 +9,7 @@ export * from './template.js';
 export * from './element.js';
 export * from './form.js';
 export * from './register.js';
+export * from './store.js';
 // Mirror the explicit re-export in core/index.js — `streams` + `whenStream`
 // (the public surface of the data-stream attribute-driven ingestion module).
 // `export *` from data-stream.js would also expose internals; keep the

package/core/index.js

@@ -18,6 +18,7 @@ export * from './signals.js';
 export * from './template.js';
 export * from './register.js';
 export * from './controller.js';
+export * from './store.js';
 export * from './provider.js';
 export * from './anchor.js';
 export * from './icons.js';