@adia-ai/web-components 0.8.44 → 0.8.46

package/core/provider.d.ts

@@ -1,7 +1,8 @@
 /**
  * `<router-ui>` provider — declarative + imperative client-side
- * routing built on {@link RouteController} (re-declared here for
- * historical reasons; the canonical export lives in `core/controller.js`).
+ * routing built on {@link RouteController} (re-exported here for
+ * back-compat — gh#1766 — the canonical implementation lives in
+ * `core/controller.js`).
  *
  * Two consumer paths:
  *
@@ -25,22 +26,17 @@
  */
 
 import { UIElement } from './element.js';
-import type { Route, RouteCommands, RouteState, ControllerSchema, RouteControllerOptions } from './controller.js';
-import { BaseController } from './controller.js';
+import type { Route } from './controller.js';
+import { RouteController } from './controller.js';
 
 /**
- * Routing-state controller. Re-declared from `core/controller.js` for
- * historical compatibility — both files define the same class shape;
- * consumers can import either. New code should prefer
+ * Routing-state controller, re-exported from `core/controller.js`
+ * (gh#1766) for back-compat — consumers can import either path.
+ * New code should prefer
  * `import { RouteController } from '@adia-ai/web-components/core/controller'`
  * for the canonical path.
  */
-export class RouteController extends BaseController {
-  static schema: ControllerSchema;
-  constructor(options?: RouteControllerOptions);
-  getState(): RouteState;
-  commands: RouteCommands;
-}
+export { RouteController };
 
 /**
  * Optional async transform applied to fetched route content before

package/core/provider.js

@@ -1,8 +1,10 @@
 /**
  * AdiaUI Router — Self-contained vanilla JS bundle.
- * Includes: RouteController + router-ui component.
+ * Includes: router-ui component; re-exports `RouteController` for
+ * back-compat (gh#1766 — the canonical definition lives in
+ * `core/controller.js`, alongside its `BaseController` superclass).
  *
- * Depends on: core.js (UIElement), controllers.js (BaseController)
+ * Depends on: element.js (UIElement), controller.js (RouteController)
  *
  * Usage:
  *   import { UIElement } from './core.js';
@@ -24,7 +26,7 @@
 
 import { UIElement } from './element.js';
 import { defineIfFree } from './register.js';
-import { BaseController } from './controller.js';
+import { RouteController } from './controller.js';
 import { viewTransition } from '../traits/view-transition/view-transition.js';
 
 // ═══════════════════════════════════════════════════════════════
@@ -46,118 +48,12 @@ class UIProvider extends UIElement {
 }
 
 // ═══════════════════════════════════════════════════════════════
-// ROUTE CONTROLLER
+// ROUTE CONTROLLER — re-exported for back-compat (gh#1766); the
+// canonical definition lives in `core/controller.js`, which is
+// where `BaseController` (its own superclass) already lives.
 // ═══════════════════════════════════════════════════════════════
 
-export class RouteController extends BaseController {
-  static schema = {
-    name: 'route',
-    state: { path: 'string', params: 'object', route: 'object', previous: 'string' },
-    commands: ['navigate', 'replace', 'back', 'forward', 'setRoutes'],
-    attributes: ['data-route-path'],
-  };
-
-  #routes = [];
-  #path = '';
-  #previous = '';
-  #params = {};
-  #route = null;
-  #historySync = true;
-  #boundPopState = null;
-
-  constructor({ routes = [], initial, historySync = true } = {}) {
-    super();
-    this.#routes = routes;
-    this.#historySync = historySync;
-    this.#path = initial ?? location.pathname;
-    this.#match();
-  }
-
-  getState() {
-    return {
-      path: this.#path,
-      params: { ...this.#params },
-      route: this.#route,
-      previous: this.#previous,
-    };
-  }
-
-  reflect() {
-    const host = this.host;
-    if (!host) return;
-    host.setAttribute('data-route-path', this.#path);
-  }
-
-  onConnect(host) {
-    if (this.#historySync) {
-      this.#boundPopState = () => {
-        this.#previous = this.#path;
-        this.#path = location.pathname;
-        this.#match();
-        this.notify();
-      };
-      window.addEventListener('popstate', this.#boundPopState);
-    }
-  }
-
-  onDisconnect() {
-    if (this.#boundPopState) {
-      window.removeEventListener('popstate', this.#boundPopState);
-      this.#boundPopState = null;
-    }
-  }
-
-  #match() {
-    this.#params = {};
-    this.#route = null;
-    for (const route of this.#routes) {
-      const match = this.#matchPath(route.path, this.#path);
-      if (match) {
-        this.#params = match.params;
-        this.#route = route;
-        return;
-      }
-    }
-  }
-
-  #matchPath(pattern, path) {
-    const patternParts = pattern.split('/').filter(Boolean);
-    const pathParts = path.split('/').filter(Boolean);
-    if (!pattern.includes(':')) return pattern === path ? { params: {} } : null;
-    if (patternParts.length !== pathParts.length) return null;
-    const params = {};
-    for (let i = 0; i < patternParts.length; i++) {
-      if (patternParts[i].startsWith(':')) params[patternParts[i].slice(1)] = pathParts[i];
-      else if (patternParts[i] !== pathParts[i]) return null;
-    }
-    return { params };
-  }
-
-  commands = {
-    navigate: (path) => {
-      if (path === this.#path) return;
-      this.#previous = this.#path;
-      this.#path = path;
-      this.#match();
-      if (this.#historySync) history.pushState(null, '', path);
-      this.notify();
-    },
-    replace: (path) => {
-      this.#previous = this.#path;
-      this.#path = path;
-      this.#match();
-      if (this.#historySync) history.replaceState(null, '', path);
-      this.notify();
-    },
-    back: () => { if (this.#historySync) history.back(); },
-    forward: () => { if (this.#historySync) history.forward(); },
-    setRoutes: (routes) => {
-      this.#routes = routes;
-      this.#match();
-      this.notify();
-    },
-  };
-}
+export { RouteController };
 
 // ═══════════════════════════════════════════════════════════════
 // ROUTER-UI — content fragment renderer

package/core/store.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Shared app store — the blessed R2 primitive. Signal-backed, with a
+ * Set-of-listeners-compatible `subscribe()` channel for imperative
+ * (non-`effect()`) consumers.
+ *
+ * @see ./store.js (runtime SoT)
+ * @see ../USAGE.md
+ */
+
+/**
+ * A `signal()`-backed store. `.value` composes with `computed()`/`effect()`
+ * exactly like a plain signal; `subscribe()` is the extra imperative
+ * channel the seven hand-rolled app-layer stores already share (see
+ * `store.js`'s header for the full rationale and the rejected
+ * BaseController alternative).
+ */
+export interface Store<T> {
+  /** Tracked read/write, same semantics as `Signal<T>.value`. */
+  value: T;
+  /** Read without subscribing the surrounding `effect()`. */
+  peek(): T;
+  /**
+   * Subscribe to changes. `cb` receives the new value on every write that
+   * doesn't fail the `Object.is` no-notify guard. Returns an unsubscribe
+   * function — safe to call more than once. Compatible with
+   * `UIElement`'s `controller` setter (`element.controller = store`).
+   */
+  subscribe(cb: (value: T) => void): () => void;
+}
+
+/**
+ * Create a shared app store.
+ *
+ * @example
+ *   const count = createStore(0);
+ *   const stop = count.subscribe((v) => console.log('count is', v));
+ *   count.value = 1;   // logs "count is 1"
+ *   count.value = 1;   // no-op — Object.is guard, no log
+ *   stop();
+ *
+ * @example Controller-setter interop
+ *   class MyEl extends UIElement {}
+ *   const el = new MyEl();
+ *   el.controller = createStore({ ready: false }); // re-renders on change
+ */
+export function createStore<T>(initial: T): Store<T>;

package/core/store.js

@@ -0,0 +1,89 @@
+/**
+ * AdiaUI shared app store — the blessed R2 primitive.
+ *
+ * A signal-backed replacement for the Set-of-listeners pub/sub pattern
+ * hand-rolled across the app layer: plan-store, data-client, patient-visit
+ * record, persona store, task-service, a2ui BaseController, a2ui Surface
+ * watchers (reactivity review, .claude/docs/reports/2026-08-20-reactivity-
+ * review/03-app-layer-stores.md §4). Doctrine's pattern menu row 1 says
+ * reactive state -> signals; `createStore` is `signal()` plus the one thing
+ * those seven stores actually needed on top of it: an imperative
+ * `subscribe(cb) -> unsubscribe` channel for consumers that are closures or
+ * classes rather than `effect()` bodies.
+ *
+ * `.value` reads/writes pass straight through to a real `signal()`, so a
+ * store composes with `computed()`/`effect()` exactly like any other signal
+ * (tracked reads, `Object.is` no-notify, microtask-batched effect re-runs).
+ * `subscribe()` is the separate, synchronous, imperative channel the seven
+ * hand-rolled stores already share — same shape, so migrating one onto this
+ * primitive is a mechanical swap (opportunistic, later, per store; this
+ * primitive lands with NO migration).
+ *
+ * Interops with `UIElement`'s `controller` setter (`core/element.js`)
+ * out of the box: `element.controller = store` wires `store.subscribe(fn)`
+ * into the element's own render-trigger machinery — the setter calls
+ * `c.connect?.(this)` / `c.subscribe?.(...)` / `c.disconnect?.(this)`, all
+ * optional-chained, and `subscribe()` alone satisfies that contract.
+ *
+ * Rejected alternative: promoting/absorbing `BaseController`
+ * (`core/controller.js`) into this role, per the reactivity review's F5.
+ * BaseController's `connect()` bakes in schema/`getState()` validation
+ * (dev-warns without a static `schema`, dev-errors without an overridden
+ * `getState()`) that exists to serve DOM-reflecting UI controllers
+ * (`RouteController`'s attributes/commands surface) — semantics a plain
+ * data store has no use for and would either have to satisfy with a dummy
+ * schema or suppress. The one thing BaseController actually offers this
+ * role — the `subscribe(fn) -> unsubscribe` shape the controller setter
+ * expects — costs nothing to reimplement directly on `signal()`, and doing
+ * so keeps the store from inheriting a validation path built for a
+ * different kind of thing. BaseController stays as-is; still one consumer
+ * (`RouteController` / `<router-ui>`), still F5's to resolve separately.
+ *
+ * @see ../USAGE.md
+ * @see ./element.js (the `controller` setter this interops with)
+ * @see ./controller.js (BaseController — the rejected alternative above)
+ */
+
+import { signal } from './signals.js';
+
+export function createStore(initial) {
+  const s = signal(initial);
+  const listeners = new Set();
+
+  return {
+    get value() {
+      return s.value;
+    },
+    set value(next) {
+      // Object.is no-notify guard — matches persona-store's proven
+      // behavior (packages/llm/persona/src/store.ts) and the underlying
+      // signal's own equality cutoff. Checked here, not inferred from
+      // signal()'s silent no-op, so an identical write never reaches
+      // `listeners` either.
+      const changed = !Object.is(s.peek(), next);
+      s.value = next;
+      if (changed) {
+        // Pass the captured `next`, never re-read `s.peek()` here — a
+        // listener that re-entrantly writes `store.value` during this
+        // loop would otherwise make every later listener observe THAT
+        // write's value instead of this one's, silently skipping the
+        // value this write actually delivered.
+        for (const cb of listeners) cb(next);
+      }
+    },
+    /** Read without subscribing the surrounding `effect()`. */
+    peek() {
+      return s.peek();
+    },
+    /**
+     * Set-of-listeners-compatible subscribe. `cb` receives the new value;
+     * callers that only care that *something* changed (the
+     * `UIElement.controller` setter among them) simply ignore the
+     * argument. Returns an unsubscribe function.
+     */
+    subscribe(cb) {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+  };
+}

package/custom-elements.json

@@ -2091,6 +2091,20 @@
               },
               "description": "Chart 2.0 aspect-ratio bucket (ADR-0074). Unset (default) auto-snaps to the nearest of the three studied ratios by comparing the chart's own live box aspect against two midpoint boundaries (5:4 between 3:2/1:1, 4:5 between 1:1/2:3) — never interpolated; the resolved bucket reflects onto the host as `data-ratio-resolved`. Setting `ratio` explicitly pins that bucket regardless of the box's actual aspect, overriding the auto-snap. Orthogonal to `size` (overall scale) and `type`/`color` (ADR-0064's family axis) — this attribute lands the grammar + snap plumbing only; per-type studied renderings per bucket are later waves (gh#1624 plan steps 2-4)."
             },
+            {
+              "name": "labels",
+              "type": {
+                "text": "string"
+              },
+              "description": "Chart 2.0 axis-label mode (ADR-0081). Unset (default, \"\") always resolves to `outside` — today's pre-2.0 outside-the-plot axis labels, byte-for-byte unchanged. Set explicitly to `chip` to opt into the pill-treated overlay labels inset within the plot box (never hanging outside it) — the resolved value reflects onto the host as `data-labels-resolved=\"chip\"|\"outside\"`. Deliberately explicit-opt-in rather than auto-detected from full-bleed ancestry (`section[bleed]`/ `card-ui[padding=\"none\"]`): an earlier draft auto-activated chip mode on any full-bleed composition, which silently changed the rendering of every ALREADY-SHIPPED full-bleed chart the moment it shipped — this build's own 60-fixture Charts visual-eval floor caught it (2 `comp-chart-in-card-n-*` regressions). `chart-in-card` compositions opt in explicitly once their own examples are updated (gh#1805)."
+            },
+            {
+              "name": "today",
+              "type": {
+                "text": "string"
+              },
+              "description": "Names the datum whose x-axis value marks \"today\" (ADR-0081). Unset (default, \"\") renders no marker — additive. Compared against each datum's x-key value via a loose string comparison (`String(datum[x]) === String(today)`), so category axes (\"month\", \"region\") work the same as literal date strings; chart-ui never auto-derives today from the clock. Renders a baseline dot + a short band tick (REQ-F-008) on cartesian types (bar, line, area, scatter, multi-line, stacked-bar, grouped-bar, composed); a no-op on every radial/part-to-whole type and on sparkline (gh#1690's N/A list). Fallback (not the primary mechanism): a datum already carrying a truthy `today` key is treated as an equivalent marker even with this attribute unset."
+            },
             {
               "name": "smooth",
               "type": {
@@ -2158,7 +2172,7 @@
                 "text": "array"
               },
               "default": "[]",
-              "description": "JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x=\"month\" y=\"revenue\">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute."
+              "description": "JS property (set programmatically — `el.data = [...]`). An array of plain objects; each object's keys are named by the `x` and `y` attributes — e.g. `<chart-ui x=\"month\" y=\"revenue\">` consumes `[{month:'Jan', revenue:3200}, {month:'Feb', revenue:4100}]`. The Chart.js `{labels, datasets}` envelope is NOT chart-ui's API — passing it (or any non-array value) renders an empty chart. May also be supplied declaratively as a JSON-array `data=\"[…]\"` attribute, hydrated once at connect. Custom accessor on the element class, not a reflected attribute. A datum object carrying a truthy `provisional` key (ADR-0081) renders that period's type-specific incomplete-period treatment (hollow/dashed bar, dashed line + faded area, hollow ring dot) on cartesian types; a no-op on radial/part-to-whole types and sparkline (gh#1690's N/A list). Provisional state is per-datum data-shape, not a chart-ui attribute — see ADR-0081 §3."
             }
           ],
           "slots": [
@@ -3271,7 +3285,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Right-click activated menu — the OS-native context-menu pattern as a web component. Distinct from `menu-ui` (which is button-triggered): same item shape (`menu-item-ui` children), different trigger surface (`contextmenu` event), and pointer-anchored positioning instead of element-anchored. Pattern: WAI-APG Menu. Two binding modes: **A. Wrap.** Default-slot child becomes the target: `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`. **B. Selector.** Point at one or more existing elements via [for]: `<context-menu-ui for=\"#my-table\">...items</context-menu-ui>`. On `contextmenu` event on a target: `preventDefault()`, position the menu at the pointer coords, show via Popover API. Touch long-press (configurable via [long-press-ms]) does the same. Shift+F10 / Menu key opens at the focused target's center for keyboard users.",
+          "description": "Right-click activated menu — the OS-native context-menu pattern as a web component. Distinct from `menu-ui` (which is button-triggered): same item shape (`menu-item-ui` children), different trigger surface (`contextmenu` event), and pointer-anchored positioning instead of element-anchored. Pattern: WAI-APG Menu. Two binding modes: **A. Wrap.** Default-slot child becomes the target: `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`. **B. Selector.** Point at one or more existing elements via [target-selector]: `<context-menu-ui target-selector=\"#my-table\">...items</context-menu-ui>`. On `contextmenu` event on a target: `preventDefault()`, position the menu at the pointer coords, show via Popover API. Touch long-press (configurable via [long-press-ms]) does the same. Shift+F10 / Menu key opens at the focused target's center for keyboard users.",
           "name": "UIContextMenu",
           "tagName": "context-menu-ui",
           "superclass": {
@@ -3279,12 +3293,19 @@
             "module": "/core/element.js"
           },
           "attributes": [
+            {
+              "name": "target-selector",
+              "type": {
+                "text": "string"
+              },
+              "description": "CSS selector(s) for target element(s). Empty = use default-slot child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used to carry — [for] means an id-ref everywhere else in AdiaUI (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's own selector meaning predates that convention and was a same-name/ different-contract collision (ADR-0053's no-shadowing doctrine)."
+            },
             {
               "name": "for",
               "type": {
                 "text": "string"
               },
-              "description": "CSS selector(s) for target element(s). Empty = use default-slot child."
+              "description": "DEPRECATED alias for [target-selector] — still a CSS selector, NOT an id-ref. Honored when [target-selector] is unset, with a one-shot console.warn pointing consumers at the replacement. New authoring should use [target-selector]."
             },
             {
               "name": "open",
@@ -6519,7 +6540,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only."
+              "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below."
             },
             {
               "name": "multi-expand",
@@ -6533,7 +6554,7 @@
           "slots": [
             {
               "name": "default",
-              "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+              "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers and <span data-nav-label> for hand-placed group-label kickers (titled runs of items/groups that aren't wrapped in a <nav-group-ui>). <span data-nav-label> renders with the same uppercase/tracking/muted kicker treatment as the [heading] ::before kicker, and is hidden alongside dividers whenever the primary-variant rail collapses ([collapsed] or ≤96px container width)."
             }
           ],
           "events": [
@@ -8566,6 +8587,14 @@
               },
               "description": "Label text above the trigger"
             },
+            {
+              "name": "label-hidden",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, [label] still sets the accessible name (aria-label) but the visible `::before` text is suppressed via the canonical sr-only technique (gh#1748, mirrors check-ui's [label-hidden], gh#1010). Use when a sibling/ancestor composition already conveys the same name visually (e.g. a scope/view-switcher select in a table-toolbar-ui [slot=\"scope\"], where the toolbar's own title already names the view) and a second visible \"Scope\"-style label would paint it twice."
+            },
             {
               "name": "hint",
               "type": {
@@ -9897,6 +9926,103 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "components/table-footer/table-footer.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "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.",
+          "name": "UITableFooter",
+          "tagName": "table-footer-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "for",
+              "type": {
+                "text": "string"
+              },
+              "description": "id-ref of the table-ui to control. Falls back to the first sibling table-ui within the same parent when omitted."
+            },
+            {
+              "name": "page",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Current page, 1-based. Explicit attributes always win over derivation (per-attribute, not all-or-nothing) — see page-size/range-total."
+            },
+            {
+              "name": "page-size",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "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."
+            },
+            {
+              "name": "range-total",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "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."
+            },
+            {
+              "name": "siblings",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Passed through to the composed pagination-ui's own [siblings] (page-number window size on each side of the current page)."
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "string"
+              },
+              "default": "md",
+              "description": "Passed through to the composed pagination-ui's own [size] (sm | md | lg, the universal size system)."
+            }
+          ],
+          "slots": [
+            {
+              "name": "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."
+            }
+          ],
+          "events": [
+            {
+              "name": "footer-page",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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."
+            },
+            {
+              "name": "page-change",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "table-footer-ui",
+          "declaration": {
+            "name": "UITableFooter",
+            "module": "./components/table-footer/table-footer.js"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "components/table-toolbar/table-toolbar.js",
@@ -10089,6 +10215,41 @@
                 "text": "CustomEvent"
               },
               "description": "Page-size select changed. Detail: { pageSize }."
+            },
+            {
+              "name": "toolbar-search",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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 }."
+            },
+            {
+              "name": "toolbar-filter-set",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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."
+            },
+            {
+              "name": "toolbar-filter-clear",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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."
+            },
+            {
+              "name": "toolbar-columns-set",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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 }."
+            },
+            {
+              "name": "toolbar-paginate",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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 }."
             }
           ]
         }
@@ -10156,7 +10317,30 @@
                 "text": "number"
               },
               "default": "0",
-              "description": "Rows per page. 0 = show all rows without pagination. When > 0, renders a pagination bar"
+              "description": "Rows per page. 0 = show all rows without pagination. When > 0, renders the internal"
+            },
+            {
+              "name": "no-pager",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hide the internal pagination bar while leaving [paginate] slicing, page state, the `page` event, and the `footer-page` command listener all intact (gh#1807, ADR-0080). The anti-doubled-pager mechanism for a table-footer-ui composition, client- or server-mode alike (gh#1754, ADR-0082): without it, a bound footer's own composed pager and the table's own internal one would both render for any non-empty paginated table. Explicit author intent — never suppressed automatically just because a footer happens to be bound."
+            },
+            {
+              "name": "range-total",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "Total row count across ALL server pages (gh#1754, ADR-0082) — the table-authoritative server-mode data contract. Presence-gated: the attribute's PRESENCE, not its value, is the mode switch (checked via hasAttribute, never the coerced value alone — the same discipline table-footer-ui's own [range-total] ships). Absent (the default) means client mode: today's behavior exactly, [paginate] slices `.data` as always. Present with [paginate] > 0 means server mode: no local slicing (`.data` IS the current page and renders whole, after local search/sort/filter), the internal pager's page count becomes `max(1, ceil(range-total / paginate))` (one calc site, consolidated), and the internal page-reset sites (`data` set, `setFilter`, `clearFilters`) are suppressed so a fetch write-back never fights the pager back to page 0 — page state then moves only via pager interaction, the `footer-page` command, or `setState()`. The existing `page` event (0-based, unchanged) becomes the fetch trigger: the consumer listens for it, fetches that server page, and writes `.data` back. Explicit `range-total=\"0\"` is server-confirmed empty (pager hidden), never conflated with absent. With [paginate] absent/0, [range-total] is inert for this table's own rendering but stays readable by a bound table-footer-ui (REQ-W-006 branch 2) for its count-only label — see the footer-authoritative shape below, which remains lawful and is unaffected by this attribute. Named identically to table-toolbar-ui's and table-footer-ui's own [range-total] (rows, never `pagination-ui[total]`'s pages — the ADR-0063 B5 collision rule); a third instance of one name for one concept."
+            },
+            {
+              "name": "filteredCount",
+              "type": {
+                "text": "number"
+              },
+              "description": "Read-only. The row count AFTER search + column filters apply but BEFORE pagination slices it (gh#1807, ADR-0080, REQ-W-006) — a plain JS getter, no setter, never a reflected attribute. table-footer-ui's client-mode range-total derivation reads this directly; a raw `.data.length` read (the toolbar's own `count` fallback precedent) would double-count a filtered-out row. In server mode ([range-total] set, gh#1754, ADR-0082), filteredCount stays page-scoped — the loaded page's rows after local filters, NOT the server total across all pages; [range-total] is the server total, filteredCount never is (REQ-D-006)."
             },
             {
               "name": "raw",
@@ -10171,7 +10355,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Global search/filter string. Filters visible rows across all columns using"
+              "description": "Global search/filter string. Filters visible rows across all columns using case-insensitive substring matching. Does NOT reset the current page (verified against source at the gh#1754/ADR-0082 build — unlike setFilter()/clearFilters(), no internal page reset ever ran for a search change; this description previously claimed \"resets to page 1 on change,\" which the source never did). Aligning the doc to observed behavior here, not a behavior change — a page reset on search, if wanted, is a separate client-mode ticket."
             },
             {
               "name": "selectable",
@@ -10257,7 +10441,7 @@
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Fired when the user navigates to a different page."
+              "description": "Fired when the table's own internal page state changes — an internal pager click, or a `footer-page` command applied (REQ-W-002). This is a RESYNC notification a bound `<table-footer-ui>` listens to for its own `page` attribute (REQ-W-004) — it is NOT the public server-mode fetch trigger a consumer should listen to; use `<table-footer-ui>`'s own `page-change` event for that (1-based, gh#1754/ADR-0082 REQ-W-003). Listening to both risks a duplicate fetch or an index-base mismatch."
             },
             {
               "name": "resize",