@adia-ai/web-components 0.8.45 → 0.8.46

package/components/chart/chart.css

@@ -15,6 +15,17 @@
     --chart-fg:             var(--md-sys-color-neutral-on-surface);
     --chart-bar:            var(--md-sys-color-primary);
     --chart-bar-hover:      var(--a-primary-bg-hover);
+    /* REQ-F-015/016 — a provisional bar's soft fill, paired with
+       `--chart-bar`'s primary role the same way calendar-grid-ui pairs
+       `--md-sys-color-primary` with `--md-sys-color-primary-container`
+       for its own soft/tonal fill. Flat across every series/color variant
+       — a judgment call named here, not left silent: the provisional
+       state already discards per-series hue for its OUTLINE color
+       (`--chart-bar` above, not each series' own stroke), so a single
+       tonal fill costs nothing further and keeps "provisional" reading as
+       one consistent state regardless of which series or chart `color` it
+       belongs to. */
+    --chart-provisional-fill: var(--md-sys-color-primary-container);
     --chart-line:           var(--md-sys-color-primary);
     --chart-dot:            var(--md-sys-color-primary);
     --chart-grid:           var(--md-sys-color-neutral-outline-variant);
@@ -45,6 +56,70 @@
     --chart-segments-gap:   2px;
     --chart-pie-gap:        1.25px;
 
+    /* ── Charts 2.0 foundations (ADR-0081, gh#1804) ──
+       REQ-F-009/010 — chrome-layer clearance + the zero-line→chip-band
+       gap, both --a-space-*-aliased (chart.class.js's #dims() reads these
+       via getComputedStyle with a matching JS fallback for the
+       happy-dom test environment, which doesn't resolve var()/calc()). */
+    --chart-chrome-inset:   var(--a-space-2);
+    --chart-band-gap:       var(--a-space-1);
+    /* REQ-F-008 — today-marker color, default the primary role. */
+    --chart-today:          var(--md-sys-color-primary);
+    /* REQ-F-005 — chip token contract, all six resolving through the
+       existing --a-* / --md-sys-color-* ladders (no new roles minted).
+       OPEN-5 (chip background role) — MEASURED, gh#1814 (real resolved
+       oklch → sRGB + WCAG contrast math, both schemes, both named
+       backdrops: --md-sys-color-neutral-container-low composited over
+       the page background for the full-bleed case, line 842 below; a
+       plain top-level card's own --md-sys-color-neutral-surface for the
+       other). Text legibility (chip-fg on chip-bg) clears AA with a wide
+       margin in every combination (>=11:1, gate floor 4.5:1) — this
+       repo's own verify:contrast discipline is fully satisfied regardless
+       of which of these two tokens is used, since both sit in the same
+       tight, deliberately-subtle neutral "surface elevation" band.
+       Non-text surface DISTINCTNESS is the real, disclosed limitation:
+       no existing --a-* / --md-sys-color-* neutral role reaches the
+       informal 3:1 UI-boundary heuristic against either backdrop, in
+       either scheme — swapping among them is a matter of degree, not a
+       pass/fail token pick, and minting a new role to clear 3:1 would
+       violate this SPEC's own no-new-roles non-goal. The originally
+       shipped --md-sys-color-neutral-surface-bright measured ~1.0-1.1:1
+       against both backdrops in both schemes (barely perceptible — a
+       real gap, not the "distinct pill" its own prior comment claimed
+       without having actually rendered it). --md-sys-color-neutral-
+       container-high measures ~1.24-1.40:1 instead (a real, screenshot-
+       confirmed improvement — the chip's rounded boundary reads clearly
+       in both schemes and against both backdrops) while keeping text
+       legibility comfortably >=11:1 — the better of the two available
+       options, not a 3:1-clearing fix. Full numbers + screenshots in the
+       gh#1814 Findings. */
+    --chart-chip-bg:        var(--md-sys-color-neutral-container-high);
+    --chart-chip-fg:        var(--md-sys-color-neutral-on-surface);
+    --chart-chip-radius:    var(--a-radius-sm);
+    --chart-chip-pad-x:     var(--a-space-1-5);
+    --chart-chip-pad-y:     var(--a-space-1);
+    --chart-chip-font-size: var(--a-ui-tiny);
+    /* REQ-F-013/OPEN-4 — min-plot-height degradation floors (chip mode
+       only, see #dims()'s own doc comment for why `outside` mode never
+       applies these). MEASURED breakpoints, not spacing values (OPEN-4's
+       resolution posture distinguishes the two) — but expressed through
+       the SAME --a-density-scaled-rem mechanism --a-space-* itself is
+       built from (space.css), rather than a bare px literal, so a scoped
+       [density] host still rescales the floor consistently with every
+       other foundations token (REQ-F-014) even though there's no single
+       NAMED --a-space-* rung at exactly 180/120px.
+       OPEN-4 RESOLVED (gh#1814): a real-browser measurement sweep across
+       all three ratio buckets confirmed both values unchanged AND
+       confirmed the model itself — height-only, never per-bucket (the
+       chip/gridline vertical geometry these floors gate doesn't depend on
+       plot width). Full rationale in the SPEC's REQ-F-013 resolution
+       note. That same sweep found and fixed an unrelated real defect: the
+       domain-min/-max y-chip's own edge clamp could overlap its unclamped
+       neighbor at ~155-220px with 7 nice-number ticks — see
+       `#renderYChips`'s own doc comment. */
+    --chart-min-plot-height-chips: calc(var(--a-density) * 11.25rem); /* 180px at d=1 */
+    --chart-min-plot-height-grid:  calc(var(--a-density) * 7.5rem);   /* 120px at d=1 */
+
     /* Transitions */
     --chart-duration:       var(--a-duration-fast);
     --chart-easing:         var(--a-easing);
@@ -211,6 +286,85 @@
     font-family: var(--chart-font);
   }
 
+  /* ── Chip labels (REQ-F-004/005/006, ADR-0081) ──
+     Rendered by #renderYChips/#renderXChips (chart.class.js) only when
+     `data-labels-resolved="chip"` — geometry (position/clamp/thin/corner
+     clearance) is computed in JS; this is styling only. `rx`/`ry` are set
+     here (not as SVG attributes) because CSS custom properties don't
+     resolve inside a bare SVG presentation-attribute string
+     (svg-authoring.md §5) — a real CSS declaration is required. */
+
+  [data-chip] {
+    fill: var(--chart-chip-bg);
+    rx: var(--chart-chip-radius);
+    ry: var(--chart-chip-radius);
+  }
+
+  [data-chip-label] {
+    fill: var(--chart-chip-fg);
+    font-size: var(--chart-chip-font-size);
+    font-family: var(--chart-font);
+  }
+
+  /* ── Today-marker (REQ-F-008, ADR-0081) ──
+     Anatomy: a baseline dot + a short band tick, never a full-height rule
+     — geometry (position, direction) is computed in
+     #todayMarkerVertical/#todayMarkerHorizontal (chart.class.js); this is
+     styling only. */
+
+  [data-today-dot] {
+    fill: var(--chart-today);
+    stroke: var(--chart-dot-stroke);
+    stroke-width: 1.5;
+  }
+
+  [data-today-tick] {
+    stroke: var(--chart-today);
+    stroke-width: 2;
+    stroke-linecap: round;
+  }
+
+  /* ── Provisional datum (REQ-F-015/016, ADR-0081 §3) ──
+     Per-datum `.provisional` flag — bar family renders a soft tonal fill +
+     dashed outline (never the ordinary solid fill) instead of the
+     ordinary filled bar; scatter's dot renders a hollow ring the same way
+     (no fill at all — a dot has no area to give hover feedback the way a
+     bar's own body does, so it stays hollow). Multi-series types
+     (stacked-bar/grouped-bar/composed) set their per-series color via an
+     inline `style="fill:var(--color-{key},...)"` (#seriesFill(), fill
+     only) — the flat `--chart-bar`/`--chart-provisional-fill`/`--chart-dot`
+     tokens here are this build's deliberate simplification for the
+     provisional OUTLINE/FILL color rather than re-deriving each series'
+     own color, named as a judgment call in the build's Findings rather
+     than left silent. Multi-series bars never carry `data-bar` (only
+     `data-slice` — see #seriesFill), so the selector below also targets
+     `[data-slice]` bar shapes directly; `!important` on `fill` is
+     required to beat that same inline style (expressing this any other
+     way needs the render path to skip #seriesFill for provisional rows,
+     a larger change than this selector fix warrants).
+     Giving the fill a real, visible value (rather than `none`) is
+     deliberate, not decorative: a hollow bar has nothing for a `:hover`
+     rule to darken/lighten, so hovering a provisional bar previously gave
+     no feedback at all. No separate `[data-provisional]:hover` rule is
+     needed — `path[data-slice]:hover`/`rect[data-slice]:hover`/
+     `[data-bar]:hover`'s existing `opacity: 0.92` already match these
+     same elements; they simply had nothing visible to dim before. */
+
+  [data-bar][data-provisional],
+  path[data-slice][data-provisional],
+  rect[data-slice][data-provisional] {
+    fill: var(--chart-provisional-fill) !important;
+    stroke: var(--chart-bar);
+    stroke-width: 1.5;
+    stroke-dasharray: 4 3;
+  }
+
+  [data-dot][data-provisional] {
+    fill: none;
+    stroke: var(--chart-dot);
+    stroke-width: 1.5;
+  }
+
   /* ── Bar ── */
 
   [data-bar] {
@@ -232,6 +386,26 @@
     stroke-linecap: round;
   }
 
+  /* ── Line/area provisional-span overlay (REQ-F-015, ADR-0081 §3) ──
+     #lineProvisionalOverlay (chart.class.js) emits these two elements
+     only when at least one datum in the series is provisional; a fixture
+     with no provisional data never emits them at all. */
+
+  [data-line-provisional] {
+    stroke: var(--chart-line);
+    stroke-width: var(--chart-line-width);
+    fill: none;
+    stroke-linejoin: round;
+    stroke-linecap: round;
+    stroke-dasharray: 5 4;
+  }
+
+  [data-area-provisional-fade] {
+    fill: var(--md-sys-color-neutral-surface);
+    opacity: 0.55;
+    pointer-events: none;
+  }
+
   /* ── Area fill ──
      Enabled by default for line / multi-line charts. Fades from the top
      (most visible, tinted by --chart-area-opacity) to transparent at the

package/components/chart/chart.d.ts

@@ -24,12 +24,14 @@ export class UIChart extends UIElement {
   color: 'accent' | 'success' | 'warning' | 'danger' | 'info';
   /** Bar corner radius in px (null = let CSS tokens decide) */
   cornerRadius: number | null;
-  /** 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. */
+  /** 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. */
   data: string;
   /** Marker (dot) visibility for line and multi-line series. `all` draws a circle[data-dot] on every datum (default — matches pre-gh#561 behavior). `none` hides all dots so a dense series reads as a clean line. `hover` shows only the currently-hovered datum's dot. `last` shows only the terminal point per series (sparkline convention). Tooltip hit targets ([data-hit]) are a separate always-rendered layer — every mode keeps hover/click working along the whole line. */
   dots: 'all' | 'none' | 'hover' | 'last';
   /** Number-format mode applied to axis labels + value overlays + donut total + gauge value + treemap value + funnel value + internal tooltip. `abbr` is the legacy 1.2K / 3M format; `decimal` fixes 2 decimals; `currency` prefixes via `--chart-currency-prefix` token (default "$"); `percent` multiplies × 100 and adds a % suffix. */
   format: 'abbr' | 'decimal' | 'currency' | 'percent';
+  /** 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). */
+  labels: '' | 'chip' | 'outside';
   /** Show a skeleton placeholder instead of the chart body. Set to true while data is being fetched; clear once data arrives. Preserves the element's aspect-ratio dimensions so the skeleton occupies the same space the chart will fill. Parity with stat-ui[loading] and table-ui[loading] (§FB-12, v0.6.27). */
   loading: boolean;
   /** When true, suppress the overlaid average line. Canonical spelling (ADR-0063, gh#1563) — the deprecated `hideAverage` dual-read shim was cut in 0.8.43 (gh#1617). */
@@ -46,6 +48,8 @@ export class UIChart extends UIElement {
   size: 'sm' | 'md' | 'lg';
   /** Line smoothing factor */
   smooth: number;
+  /** 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. */
+  today: string;
   /** Data key for x-axis (category) values */
   x: string;
   /** Y-axis key(s), comma-separated for multi-series */

package/components/chart/chart.yaml

@@ -115,6 +115,45 @@ props:
       - "1:1"
       - "2:3"
     reflect: true
+  labels:
+    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).
+    type: string
+    default: ""
+    enum:
+      - ""
+      - chip
+      - outside
+    reflect: true
+  today:
+    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.
+    type: string
+    default: ""
+    reflect: true
   smooth:
     description: Line smoothing factor
     type: number
@@ -213,7 +252,12 @@ props:
       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.
+      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.
     type: array
     items:
       type: object

package/components/field/field.css

@@ -77,8 +77,30 @@
     row-gap: var(--field-gap);
   }
 
-  /* Stacked + (trailing or action) → 2-col */
-  :scope:has(> :is([slot="trailing"], [slot="action"])) {
+  /* Stacked + trailing only (no action) — the "action" column would
+     otherwise still be sized by row 1's trailing content while row 2's
+     action cell sits empty, stealing width from `control` (gh#1836).
+     `control` spans both columns so it fills the full row instead. */
+  :scope:has(> [slot="trailing"]):not(:has(> [slot="action"])) {
+    grid-template-columns: minmax(0, 1fr) auto;
+    grid-template-areas:
+      "label   trailing"
+      "control control"
+      "message message";
+  }
+  /* Stacked + action only (no trailing) — label spans the full row since
+     there's no trailing content contesting it. */
+  :scope:has(> [slot="action"]):not(:has(> [slot="trailing"])) {
+    grid-template-columns: minmax(0, 1fr) auto;
+    grid-template-areas:
+      "label   label"
+      "control action"
+      "message message";
+  }
+  /* Stacked + both trailing and action — today's combined template,
+     unchanged: row 2's second column is legitimately contested only by
+     `action`, since `trailing` lives in row 1. */
+  :scope:has(> [slot="trailing"]):has(> [slot="action"]) {
     grid-template-columns: minmax(0, 1fr) auto;
     grid-template-areas:
       "label   trailing"

package/components/index.js

@@ -55,6 +55,7 @@ export { UIColorInput } from './color-input/color-input.js';
 export { UINoodles } from './noodles/noodles.js';
 export { UITable } from './table/table.js';
 export { UITableToolbar } from './table-toolbar/table-toolbar.js';
+export { UITableFooter } from './table-footer/table-footer.js';
 export { UITimeline, UITimelineItem } from './timeline/timeline.js';
 export { UIStepper, UIStepperItem } from './stepper/stepper.js';
 export { UISwiper } from './swiper/swiper.js';

package/components/input/input.css

@@ -92,6 +92,13 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     min-width: var(--input-label-min-width);
     color: var(--input-affix-fg);
     font-size: var(--input-font-size);
+    /* Match [slot="field"]'s line-height (§113) — without it the label
+       falls back to the UA's normal line-height for its font/size, which
+       differs from --a-font-leading-normal. align-items: center on the
+       field centers each flex item's own line box, so a mismatched
+       line-height shifts the label's glyph baseline off the value/
+       placeholder text's baseline even though both boxes are centered. */
+    line-height: var(--a-font-leading-normal);
     user-select: none;
     pointer-events: none;
   }

package/components/table/table.a2ui.json

@@ -34,6 +34,11 @@
       "type": "boolean",
       "default": false
     },
+    "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
+    },
     "frameless": {
       "description": "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.",
       "type": "boolean",
@@ -44,8 +49,18 @@
       "type": "boolean",
       "default": false
     },
+    "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
+    },
     "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
+    },
+    "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
     },
@@ -55,7 +70,7 @@
       "default": false
     },
     "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": ""
     },
@@ -141,10 +156,10 @@
         }
       },
       "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": {
-            "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).",
             "type": "number"
           }
         }