@adia-ai/web-components 0.8.45 → 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.yaml

@@ -293,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

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": [
@@ -9912,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",
@@ -10206,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",
@@ -10221,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",
@@ -10307,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",