@adia-ai/web-components 0.8.44 → 0.8.46

package/components/table/table.css

@@ -486,10 +486,13 @@
   /* ═══════ Density ═══════ */
 
   /* No local override (ADR-0054 convergence) — --table-py/-px above already
-     derive from --a-space-* steps, which the ambient global
-     [density="compact"|"spacious"] attribute already scales via
-     --a-density. Do not reintroduce a component-local :scope[density=…]
-     block; that would re-shadow the global grammar (ADR-0053). */
+     derive from --a-space-* steps, which the global [density="compact"|
+     "spacious"] attribute scales via --a-density on ANY host, root or
+     scoped (gh#1771 — api/sizing.css re-declares the --a-space-* formulas
+     at the [density] boundary itself, the gh#570 cure; previously this
+     comment's "already scales" claim only held for root-level [density]).
+     Do not reintroduce a component-local :scope[density=…] block; that
+     would re-shadow the global grammar (ADR-0053). */
 
   /* ═══════ Pinned cells ═══════ */
 

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:
@@ -302,7 +378,25 @@ a2ui:
       needs search / filter / sort / columns visibility. Do NOT
       re-implement those affordances in the card header — the toolbar
       auto-wires search/filter/sort/columns changes into the bound
-      table.
+      table via `toolbar-*` CustomEvents (gh#1764/#1780, ADR-0079 —
+      events-only interaction contract; table-ui listens for
+      toolbar-search/toolbar-filter-set/toolbar-filter-clear/
+      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
@@ -329,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
+  }
+}