@adia-ai/web-components 0.8.45 → 0.8.46

package/components/table/table.class.js

@@ -26,7 +26,21 @@
  * table-ui has no local `density` prop (ADR-0054) — it converges onto the
  * ambient global [density="compact"|"spacious"] attribute; --table-py/-px
  * already derive from --a-space-* steps, which --a-density scales.
- *   paginate   — rows per page (0 = no pagination)
+ *   paginate   — rows per page (0 = no pagination); purely presentational
+ *                (page-size only) when [range-total] is present — gh#1754/ADR-0082
+ *   range-total — total row count across ALL server pages (Number, reflected,
+ *                presence-gated via hasAttribute — the attribute's PRESENCE, not
+ *                its value, is the server-mode switch, gh#1754/ADR-0082). Absent
+ *                → client mode, today's behavior exactly. Present + [paginate] > 0
+ *                → server mode: no local slicing (`.data` IS the current page and
+ *                renders whole, after local search/sort/filter), page count =
+ *                max(1, ceil(range-total / paginate)), 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. 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 for its count-only label.
  *   loading    — show loading overlay
  *   search     — global search filter string
  *
@@ -61,6 +75,27 @@
  *   toolbar-filter-clear — { detail: {} }                      → this.clearFilters()
  *   toolbar-columns-set  — { detail: { columns } }             → this.columns =
  *   toolbar-paginate     — { detail: { pageSize } }            → this.paginate =
+ *   footer-page          — { detail: { page } }, 1-based       → gh#1807/ADR-0080,
+ *                           refined 0.2.0/ADR-0082. Dispatched directly at this
+ *                           element (table-footer-ui, or any other consumer).
+ *                           Applies whenever [paginate] > 0 — client mode and
+ *                           table-authoritative server mode ([range-total]
+ *                           present, REQ-D-003) alike, since #pageCount already
+ *                           knows server math; clamped to [1, pageCount]; a
+ *                           non-numeric/NaN detail.page is a documented no-op.
+ *                           At [paginate="0"] the command stays a no-op in
+ *                           either mode — with no page size there is no page
+ *                           range to move within. On a valid page, applies
+ *                           exactly like an internal pager click: updates the
+ *                           page, re-renders, and fires the existing `page`
+ *                           event (the fetch trigger in server mode).
+ *
+ * [no-pager] — boolean, reflected (gh#1807/ADR-0080). Hides the internal
+ * pagination bar while [paginate] slicing, page state, the `page` event, and
+ * the `footer-page` listener all stay intact — the anti-doubled-pager
+ * mechanism for a table-footer-ui composition, client- or server-mode alike
+ * (gh#1754/ADR-0082). Explicit author intent, never an auto-suppression
+ * side-effect of binding a footer.
  */
 
 import { UIElement } from '../../core/element.js';
@@ -243,6 +278,18 @@ export class UITable extends UIElement {
     wrap:       { type: Boolean, default: false, reflect: true },
     raw:        { type: Boolean, default: false, reflect: true },
     paginate:   { type: Number,  default: 0,     reflect: true },
+    // gh#1807/ADR-0080 — opt-out for the internal pagination bar. Additive:
+    // [paginate] slicing, page state, the `page` event, and the
+    // `footer-page` listener are all unaffected; only the internally
+    // stamped [data-footer] pagination-ui is suppressed. Explicit intent,
+    // for a client-mode table-footer-ui composition to avoid a doubled
+    // pager (REQ-W-005).
+    noPager:    { type: Boolean, default: false, reflect: true, attribute: 'no-pager' },
+    // gh#1754/ADR-0082 — the server-total data contract. Presence-gated
+    // (#serverMode reads hasAttribute, never this coerced value): total row
+    // count across all server pages. See the class-header doc comment above
+    // and REQ-D-003..006 for the full server-mode contract.
+    rangeTotal: { type: Number,  default: 0,     reflect: true, attribute: 'range-total' },
     loading:    { type: Boolean, default: false, reflect: true },
     search:     { type: String,  default: '',    reflect: true },
     // adiav2 zero-overrides purge (gh#1680) deleted an app-side [data-clickable]
@@ -271,6 +318,23 @@ export class UITable extends UIElement {
   #openFilter = null;        // column key of open filter dropdown
   #filterFocusRaf = null;
 
+  // gh#1754/ADR-0082 — the mode switch is the [range-total] attribute's
+  // PRESENCE, never its coerced value (mirrors table-footer-ui's own
+  // REQ-S-001/002 hasAttribute discipline). One predicate for both the
+  // page-count/no-slice/visibility branches (step 2) and the reset-guard
+  // sites (step 3) — deliberately not narrowed by `paginate > 0` (see the
+  // reset-suppression call sites for why that widened scope is safe).
+  get #serverMode() { return this.hasAttribute('range-total'); }
+
+  // gh#1754/ADR-0082 REQ-D-003 (CodeRabbit, PR #1828) — a raw
+  // `Number(x) || 0` accepts negative and non-finite values verbatim (both
+  // are truthy), which can drive #pageCount/the footer's own range text
+  // negative or infinite. Clamps to a finite, non-negative integer.
+  #safeRangeTotal() {
+    const n = Number(this.rangeTotal);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+  }
+
   // ── Public API: columns ──
 
   set columns(arr) {
@@ -285,7 +349,11 @@ export class UITable extends UIElement {
   set data(arr) {
     this.#data = Array.isArray(arr) ? arr : [];
     this.#selected.clear();
-    this.#page = 0;
+    // gh#1754/ADR-0082 REQ-D-004 — in server mode a `.data` set is the
+    // consumer's fetch write-back for the CURRENT page; resetting to page 0
+    // here would fight the pager back to the start on every fetch. Selection
+    // still clears unconditionally (rows changed under it either way).
+    if (!this.#serverMode) this.#page = 0;
     this.#requestRender();
   }
 
@@ -349,7 +417,10 @@ export class UITable extends UIElement {
     } else {
       this.#filters.set(key, { op, value });
     }
-    this.#page = 0;
+    // gh#1754/ADR-0082 REQ-D-004 — server mode: page state moves only via
+    // pager interaction, the `footer-page` command, or setState(); a filter
+    // change never resets it (the consumer's fetch loop owns page moves).
+    if (!this.#serverMode) this.#page = 0;
     this.#requestRender();
     this.dispatchEvent(new CustomEvent('filter-change', {
       detail: { filters: Object.fromEntries(this.#filters) },
@@ -360,7 +431,7 @@ export class UITable extends UIElement {
   clearFilters() {
     this.#filters.clear();
     this.#openFilter = null;
-    this.#page = 0;
+    if (!this.#serverMode) this.#page = 0; // gh#1754/ADR-0082 REQ-D-004 — same suppression as setFilter above.
     this.#requestRender();
     this.dispatchEvent(new CustomEvent('filter-change', {
       detail: { filters: {} },
@@ -416,6 +487,42 @@ export class UITable extends UIElement {
     this.paginate = Number(e.detail?.pageSize) || 0;
   };
 
+  // gh#1807/ADR-0080, refined 0.2.0/ADR-0082 — `footer-page` is the
+  // footer→table page-navigation command (REQ-W-002), sender-prefixed like
+  // the five `toolbar-*` commands above but from a second sender
+  // (table-footer-ui). Applies whenever [paginate] > 0 — client mode AND
+  // table-authoritative server mode ([range-total] present, REQ-D-003)
+  // alike, since #pageCount already knows server math (step 2 above): the
+  // clamp below reads the right ceiling in either mode with no extra
+  // branching needed here. At [paginate="0"] the command stays a documented
+  // no-op in either mode — with no page size there is no page range to move
+  // within. Clamps to the valid page range and never throws (AC-004/AC-018);
+  // a non-numeric/NaN detail.page is silently ignored (no page change, no
+  // `page` notification).
+  #onFooterPage = (e) => {
+    if (e.target !== this) return;
+    if (!(this.paginate > 0)) return; // paginate=0: documented no-op, either mode
+    const n = Number(e.detail?.page);
+    if (!Number.isFinite(n)) return;
+    const clamped = Math.max(1, Math.min(Math.trunc(n), this.#pageCount));
+    this.#page = clamped - 1; // this.#page is 0-based internally
+    this.render();
+    this.dispatchEvent(new CustomEvent('page', {
+      bubbles: true,
+      detail: { page: this.#page },
+    }));
+  };
+
+  // ── Public API: filteredCount ──
+  // gh#1807/ADR-0080, REQ-W-006 — read-only. The row count AFTER search +
+  // column filters apply but BEFORE pagination slices it — exactly the
+  // number table-footer-ui's client-mode derivation needs for its
+  // range-total (a raw `.data.length` read, the toolbar's own `count`
+  // fallback precedent, would double-count a filtered-out row). Undocumented
+  // in table.yaml by design, matching `.selected`/`.sortState`/`.filters` —
+  // a plain read-only JS getter, not a reflected attribute.
+  get filteredCount() { return this.#getProcessedIndices().length; }
+
   // ── Public API: expansion ──
 
   toggleExpand(index) {
@@ -568,6 +675,9 @@ export class UITable extends UIElement {
       this.addEventListener('toolbar-filter-clear', this.#onToolbarFilterClear);
       this.addEventListener('toolbar-columns-set', this.#onToolbarColumnsSet);
       this.addEventListener('toolbar-paginate', this.#onToolbarPaginate);
+      // gh#1807/ADR-0080 — a second sender-prefixed command, alongside the
+      // five toolbar-* listeners above (same symmetric-lifecycle rule).
+      this.addEventListener('footer-page', this.#onFooterPage);
     }
   }
 
@@ -580,6 +690,7 @@ export class UITable extends UIElement {
     this.removeEventListener('toolbar-filter-clear', this.#onToolbarFilterClear);
     this.removeEventListener('toolbar-columns-set', this.#onToolbarColumnsSet);
     this.removeEventListener('toolbar-paginate', this.#onToolbarPaginate);
+    this.removeEventListener('footer-page', this.#onFooterPage);
     this.#bound = false;
     this.#cleanupResize();
     if (this.#renderRaf) {
@@ -592,6 +703,21 @@ export class UITable extends UIElement {
     }
   }
 
+  // gh#1754/ADR-0082 — ported from table-footer.class.js's own
+  // attributeChangedCallback gotcha (its rangeTotal, same default-0 shape).
+  // [range-total]'s default is already 0 (Number), so an absent → "0"
+  // transition parses to the SAME coerced value; the base class property
+  // setter's Object.is short-circuit (element.js installProps) swallows the
+  // signal write, and the reactive render effect never re-runs on its own.
+  // This is a presence concern (#serverMode reads hasAttribute, not the
+  // coerced value), not a value one. Batched via #requestRender — never
+  // render() directly — honoring the R7 render-clock discipline (no edits to
+  // #requestRender/#renderRaf themselves).
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback(name, oldVal, newVal);
+    if (name === 'range-total') this.#requestRender();
+  }
+
   // ── <col-def> Parsing ──────────────────────────────────────────────────────
 
   #parseColDefs() {
@@ -787,9 +913,15 @@ export class UITable extends UIElement {
   }
 
   /**
-   * Paginate a set of indices.
+   * Paginate a set of indices. gh#1754/ADR-0082 REQ-D-003 — server mode:
+   * `.data` IS the current page already (the consumer sliced it server-side),
+   * so no local slicing runs; [paginate] supplies only the page-size for
+   * pager math. `indices` here has already had local search/sort/filter
+   * applied by #getProcessedIndices — server mode still renders that whole
+   * (unsliced) result.
    */
   #getPageSlice(indices) {
+    if (this.#serverMode) return indices;
     if (!this.paginate || this.paginate <= 0) return indices;
     const start = this.#page * this.paginate;
     return indices.slice(start, start + this.paginate);
@@ -797,6 +929,11 @@ export class UITable extends UIElement {
 
   get #pageCount() {
     if (!this.paginate || this.paginate <= 0) return 1;
+    // gh#1754/ADR-0082 REQ-D-003 — server mode: page count is server-total-
+    // derived, not the loaded page's own length (the exact dual-math drift
+    // gh#1754's evidence quoted — this is now the ONE calc site;
+    // #renderPagination reads this getter instead of recomputing).
+    if (this.#serverMode) return Math.max(1, Math.ceil(this.#safeRangeTotal() / this.paginate));
     // pageCount should reflect filtered data, not raw data
     const filteredCount = this.#getProcessedIndices().length;
     return Math.max(1, Math.ceil(filteredCount / this.paginate));
@@ -910,7 +1047,15 @@ export class UITable extends UIElement {
 
     // ── Pagination footer ──
 
-    const showPagination = this.paginate > 0 && this.#data.length > 0;
+    // gh#1807/ADR-0080 REQ-W-005 — [no-pager] hides only the internally
+    // stamped bar; slicing/page-state/events are untouched (they don't
+    // route through this flag at all).
+    // gh#1754/ADR-0082 REQ-D-005 — server mode drops the client-mode
+    // `data.length > 0` term: an in-flight fetch (momentarily empty `.data`)
+    // must not flicker the pager away, so visibility gates on `range-total`
+    // instead.
+    const showPagination = this.paginate > 0 && !this.noPager
+      && (this.#serverMode ? this.#safeRangeTotal() > 0 : this.#data.length > 0);
     let footer = this.querySelector(':scope > [data-footer]');
 
     if (showPagination) {
@@ -919,7 +1064,7 @@ export class UITable extends UIElement {
         footer.setAttribute('data-footer', '');
         this.appendChild(footer);
       }
-      this.#renderPagination(footer, allProcessed.length);
+      this.#renderPagination(footer);
     } else if (footer) {
       footer.remove();
     }
@@ -1320,7 +1465,7 @@ export class UITable extends UIElement {
 
   // ── Pagination ─────────────────────────────────────────────────────────────
 
-  #renderPagination(footer, filteredTotal) {
+  #renderPagination(footer) {
     let pag = footer.querySelector('pagination-ui');
     if (!pag) {
       footer.innerHTML = '';
@@ -1335,10 +1480,16 @@ export class UITable extends UIElement {
       });
       footer.appendChild(pag);
     }
-    const pageCount = this.paginate > 0
-      ? Math.max(1, Math.ceil(filteredTotal / this.paginate))
-      : 1;
-    pag.setAttribute('page', String(this.#page + 1));
+    // gh#1754/ADR-0082 — #pageCount is now the single calc site (client AND
+    // server math); the duplicated `ceil(filteredTotal / paginate)` this
+    // function used to recompute is gone — that dual-math drift is exactly
+    // gh#1754's evidence. Clamp only the RENDERED page attribute (a display
+    // concern, e.g. the server total shrank below the current page) — never
+    // mutate `#page` or dispatch `page` from render (REQ-D-005: a render must
+    // never self-trigger a fetch).
+    const pageCount = this.#pageCount;
+    const p = Math.min(this.#page, pageCount - 1);
+    pag.setAttribute('page', String(p + 1));
     pag.setAttribute('total', String(pageCount));
   }
 

package/components/table/table.d.ts

@@ -31,7 +31,7 @@ export interface TableFilterChangeEventDetail {
 
 export type TableFilterChangeEvent = CustomEvent<TableFilterChangeEventDetail>;
 export interface TablePageEventDetail {
-  /** New active page index (1-based). */
+  /** New active page index (0-based — gh#1808; the `footer-page` command and the `page` attribute on <table-footer-ui> are 1-based, this event's own detail is not). */
   page: number;
 }
 
@@ -94,15 +94,21 @@ export class UITable extends UIElement {
   data: string;
   /** Enable row expansion */
   expandable: boolean;
+  /** 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). */
+  readonly filteredCount: number;
   /** Drop the table's outer 1px perimeter and nothing else (gh#511) — row dividers are untouched (the perimeter is split onto its own --table-perimeter token, defaulting to --table-border). For card-composed tables: the card owns the frame, so the table's square perimeter otherwise renders a doubled edge (flush bleed) or a stray inner box (with content above). Standalone tables keep their chrome by default. Theming path without the attribute: set --table-perimeter to transparent per instance. Note: `<card-ui><section bleed>` already drops a direct-child table-ui's chrome automatically (card.css, gh#796) — `frameless`/`raw` on the instance still applies and is honored, but is no longer required just to avoid the doubled-edge look in that composition. */
   frameless: boolean;
   /** Renders N ghost skeleton rows in place of the body data (count derived from `paginate` if set, else 5). Header + columns stay intact so the table layout is preserved while data fetches. Sets aria-busy="true" on the host. Data updates are deferred until loading is set back to false. */
   loading: boolean;
-  /** Rows per page. 0 = show all rows without pagination. When > 0, renders a pagination bar below the table. */
+  /** 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. */
+  noPager: boolean;
+  /** Rows per page. 0 = show all rows without pagination. When > 0, renders the internal pagination bar below the table — UNLESS [no-pager] is also set (gh#1807, ADR-0080), which keeps [paginate]'s slicing/page-state/`page`-event/`footer-page`-listener behavior but suppresses only the bar itself (the anti-doubled-pager path for a table-footer-ui composition). When [range-total] is also set (gh#1754, ADR-0082), [paginate] becomes purely presentational — it supplies only the page-size for pager math; no local slicing runs. */
   paginate: number;
+  /** 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. */
+  rangeTotal: number;
   /** Visual-only passthrough — applies `<table-ui>`'s chrome reset (background / border / border-radius all transparent) AND short-circuits the data lifecycle entirely. The consumer owns the body shape: no header injection, no row reconciliation from `.data`, no empty-state / loading overlays, no aggregation or pagination footers. Use raw when embedding `<table-ui>` inside surfaces that supply their own chrome (e.g. `<card-ui><section bleed>`), or when wrapping a consumer-authored native `<table>` for design-token styling without the framework's data semantics. Note: a `<table-ui>` placed directly inside `<card-ui><section bleed>` drops the table's visual chrome automatically (card.css, gh#796) even without `raw` — `raw` is still required to also short-circuit the data lifecycle. Pre-v0.6.33 (FB-53 §2) `raw` was visual-only and the data lifecycle still ran — wrapping a `.data`-unset native table produced a phantom "No data" overlay. v0.6.33+ matches the documented contract. */
   raw: boolean;
-  /** Global search/filter string. Filters visible rows across all columns using case-insensitive substring matching. Resets to page 1 on change. */
+  /** 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. */
   search: string;
   /** Show checkbox column for row selection. Select-all checkbox in header. Shift+click for range select. */
   selectable: boolean;

package/components/table/table.yaml

@@ -50,10 +50,71 @@ props:
     default: false
     reflect: true
   paginate:
-    description: Rows per page. 0 = show all rows without pagination. When > 0, renders a pagination bar
-      below the table.
+    description: Rows per page. 0 = show all rows without pagination. When > 0, renders the internal
+      pagination bar below the table — UNLESS [no-pager] is also set (gh#1807, ADR-0080), which keeps
+      [paginate]'s slicing/page-state/`page`-event/`footer-page`-listener behavior but suppresses only
+      the bar itself (the anti-doubled-pager path for a table-footer-ui composition). When [range-total]
+      is also set (gh#1754, ADR-0082), [paginate] becomes purely presentational — it supplies only the
+      page-size for pager math; no local slicing runs.
     type: number
     default: 0
+  no-pager:
+    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.
+    type: boolean
+    default: false
+    reflect: true
+  range-total:
+    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.
+    type: number
+    default: 0
+    reflect: true
+  filteredCount:
+    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).
+    type: number
+    readonly: true  # getter-only, no setter — never A2UI-bindable (not `dynamic:`)
   raw:
     description: >-
       Visual-only passthrough — applies `<table-ui>`'s chrome reset
@@ -76,8 +137,13 @@ props:
     default: false
     reflect: true
   search:
-    description: Global search/filter string. Filters visible rows across all columns using
-      case-insensitive substring matching. Resets to page 1 on change.
+    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.
     type: string
     default: ""
   selectable:
@@ -180,11 +246,21 @@ events:
         type: object
         description: "Map of `{ [columnKey]: filterValue }` reflecting active filters."
   page:
-    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.
     detail:
       page:
         type: number
-        description: New active page index (1-based).
+        description: >-
+          New active page index (0-based — gh#1808; the `footer-page`
+          command and the `page` attribute on <table-footer-ui> are
+          1-based, this event's own detail is not).
   resize:
     description: Fired when a column is resized via drag.
     detail:
@@ -308,6 +384,19 @@ a2ui:
       toolbar-columns-set/toolbar-paginate on itself). Any consumer, not
       only table-toolbar-ui, may dispatch these events directly at a
       table-ui instance.
+    - >-
+      Pair with <table-footer-ui for="<table-id>"> for the pager +
+      "Showing X-Y of N" range label (gh#1807, ADR-0080; gh#1754, ADR-0082)
+      — table-ui listens for its `footer-page` command (detail {page},
+      1-based) on itself, applied whenever [paginate] > 0 — client mode
+      AND table-authoritative server mode ([range-total] set) alike —
+      clamped to the valid page range (server-derived when [range-total]
+      is set). Only at [paginate="0"] does the table treat it as a
+      documented no-op, in either mode. Set [no-pager] on the table when
+      a composition also binds a footer (client- or server-mode), or the
+      internal pagination bar and the footer's composed one both render —
+      [no-pager] leaves slicing/page-state/the `page` event untouched, it
+      only hides the internal bar.
     - >-
       Cells truncate single-line by default (v0.6.21 §403
       truncate-default). Opt out per-table with [wrap] for whole-table
@@ -334,8 +423,20 @@ a2ui:
       rendered rows and add a pagination bar. [virtual] is NOT a
       recognized prop and is silently ignored — there is no DOM-level
       virtual scrolling in table-ui. [paginate] is the supported
-      performance mechanism. Wire [paginate] with optional [search]
-      and the `page` event for server-driven pagination.
+      performance mechanism. For server-driven pagination (gh#1754,
+      ADR-0082), set [paginate="N"] (page size) + [range-total="M"]
+      (server total row count) together — [paginate] then becomes purely
+      presentational (no local slicing), `.data` holds exactly the
+      current server page. The table's own `page` event (0-based) is an
+      internal resync notification, not the fetch trigger — a bound
+      <table-footer-ui> listens to it to keep its own [page] in sync.
+      The PUBLIC fetch trigger is <table-footer-ui>'s own `page-change`
+      event (1-based): listen for it, fetch that server page, then write
+      the rows back to `.data` and the footer's own [page]. Listening to
+      the table's `page` event instead risks a duplicate fetch or an
+      index-base mismatch (0-based vs 1-based). [search]/[sort]/column
+      filters, when used alongside server paging, still operate on the
+      loaded page only — not a server-side query.
 anti_patterns:
   - wrong: '<table-ui virtual></table-ui>'
     why: >-

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

@@ -0,0 +1,150 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/TableFooter.json",
+  "title": "TableFooter",
+  "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.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "TableFooter"
+    },
+    "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": ""
+    },
+    "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
+    },
+    "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
+    },
+    "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
+    },
+    "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
+    },
+    "size": {
+      "description": "Passed through to the composed pagination-ui's own [size] (sm | md | lg, the universal size system).",
+      "type": "string",
+      "default": "md"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<table-footer-ui page=\"1\" page-size=\"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.",
+        "wrong": "<table-footer-ui range-start=\"1\" range-end=\"10\" range-total=\"128\"></table-footer-ui>"
+      }
+    ],
+    "category": "agent",
+    "composes": [
+      "pagination-ui"
+    ],
+    "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."
+      }
+    },
+    "examples": [
+      {
+        "description": "Server-mode footer (gh#1754 Shape 1) paired with a for=-bound table-ui.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Column\", \"gap\": \"0\", \"children\": [\"tests\", \"ftr\"]},\n  {\"id\": \"tests\", \"component\": \"Table\", \"raw\": true},\n  {\"id\": \"ftr\", \"component\": \"TableFooter\", \"for\": \"tests\", \"page\": 1, \"page-size\": 10, \"range-total\": 128}\n]",
+        "name": "table-footer-server-mode"
+      },
+      {
+        "description": "Client-mode footer bound to a [paginate]d table-ui with its own internal pager suppressed via [no-pager].",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Column\", \"gap\": \"0\", \"children\": [\"tests-c\", \"ftr\"]},\n  {\"id\": \"tests-c\", \"component\": \"Table\", \"paginate\": 10, \"no-pager\": true, \"raw\": true},\n  {\"id\": \"ftr\", \"component\": \"TableFooter\", \"for\": \"tests-c\"}\n]",
+        "name": "table-footer-client-mode"
+      }
+    ],
+    "keywords": [
+      "table-footer",
+      "pagination",
+      "pager",
+      "range",
+      "showing",
+      "data-grid",
+      "directory",
+      "admin",
+      "backoffice",
+      "listing",
+      "records"
+    ],
+    "name": "UITableFooter",
+    "parts": {},
+    "related": [
+      "table",
+      "table-toolbar",
+      "pagination",
+      "card"
+    ],
+    "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": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "status": "beta",
+    "synonyms": {
+      "pager": [
+        "table-footer",
+        "pagination"
+      ],
+      "pagination": [
+        "table-footer",
+        "pagination"
+      ]
+    },
+    "tag": "table-footer-ui",
+    "tokens": {
+      "--table-footer-gap": {
+        "description": "Gap between the range label and the pager"
+      },
+      "--table-footer-px": {
+        "description": "Horizontal padding"
+      },
+      "--table-footer-py": {
+        "description": "Vertical padding"
+      },
+      "--table-footer-summary-fg": {
+        "description": "Range-label text color"
+      },
+      "--table-footer-summary-size": {
+        "description": "Range-label font size"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}