@adia-ai/web-components 0.8.47 → 0.8.50

package/custom-elements.json

@@ -2089,7 +2089,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Chart 2.0 aspect-ratio bucket (ADR-0074). Unset (default) auto-snaps to the nearest of the three studied ratios by comparing the chart's own live box aspect against two midpoint boundaries (5:4 between 3:2/1:1, 4:5 between 1:1/2:3) — never interpolated; the resolved bucket reflects onto the host as `data-ratio-resolved`. Setting `ratio` explicitly pins that bucket regardless of the box's actual aspect, overriding the auto-snap. Orthogonal to `size` (overall scale) and `type`/`color` (ADR-0064's family axis) — this attribute lands the grammar + snap plumbing only; per-type studied renderings per bucket are later waves (gh#1624 plan steps 2-4)."
+              "description": "Chart 2.0 aspect-ratio bucket (ADR-0074). Unset (default) auto-snaps to the nearest of the three studied ratios by comparing the chart's own live box aspect against two midpoint boundaries (5:4 between 3:2/1:1, 4:5 between 1:1/2:3) — never interpolated; the resolved bucket reflects onto the host as `data-ratio-resolved`. Setting `ratio` explicitly pins that bucket regardless of the box's actual aspect, overriding the auto-snap. Orthogonal to `size` (overall scale) and `type`/`color` (ADR-0064's family axis) — per-type studied renderings per bucket shipped across Waves A-C (gh#1624 plan steps 2-4: radial-bar/gauge/segments/stacked-bar/grouped-bar/multi-line, funnel/treemap/sankey/composed) — all 18 types have dedicated per-ratio render paths."
             },
             {
               "name": "labels",
@@ -8245,7 +8245,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Search input with magnifying-glass icon, clear button, and debounced search event.",
+          "description": "Search input with magnifying-glass icon, clear button, and debounced search event. Fills its",
           "name": "UISearch",
           "tagName": "search-ui",
           "superclass": {
@@ -9217,7 +9217,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Horizontal-bleed KPI layout. With a `slot=\"chart\"` child, the value / label / change stack on the left while the chart fills the right column at full height and bleeds to the card's top / right / bottom edges (the horizontal counterpart to a chart in a card `<section bleed>`). No effect without a chart slot."
+              "description": "The chart reaches the card's edges — which edges depends on `band`: a column bleeding top/right/bottom without it, a three-edge (inline-start, inline-end, block-end) bottom band with it. With `slot=\"chart\"` alone (no `band`), the value / label / change stack on the left while the chart fills the right column at full height and bleeds to the card's top / right / bottom edges (the horizontal counterpart to a chart in a card `<section bleed>`). Set together with `band` for the full-bleed KPI tile — see `band`. No effect without a chart slot."
             },
             {
               "name": "band",
@@ -9225,7 +9225,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Chart-band KPI layout. With a `slot=\"chart\"` child, label / value / change stack full width top to bottom and the chart forms a short full-width band between the value and the change row (the Gmail/Vercel/shadcn stat-card shape). Composes with `icon` exactly as the base layout does. No effect without a chart slot."
+              "description": "Chart-band KPI layout. With a `slot=\"chart\"` child, label / value / change stack full width top to bottom and the chart forms a short full-width band between the value and the change row (the Gmail/Vercel/shadcn stat-card shape). Composes with `icon` exactly as the base layout does. Set together with `bleed` (`band bleed`) for the KPI tile: the band bleeds to the card's inline-start, inline-end, and block-end edges, and the `change` delta overlays it as a chip instead of stacking below it (ADR-0083) — the tile's `stat-ui` must be the card's last content (no trailing footer/section). No effect without a chart slot."
             }
           ],
           "slots": [
@@ -9965,11 +9965,26 @@
             },
             {
               "name": "range-total",
+              "type": {
+                "text": "[number, string]"
+              },
+              "default": "0",
+              "description": "Total ROWS across all pages. Absent (the default) means \"not yet known\" (loading) — never \"zero\"; both the range label and the pager stay hidden until this is set. Explicit range-total=\"0\" is the confirmed-empty state (pager hidden; the `empty` slot renders in the range label's position when supplied). Named identically to table-toolbar-ui's [range-total] and table-ui's own [range-total] (gh#1754, ADR-0082) and deliberately NOT `total` (pagination-ui's `total` is total PAGES — the ADR-0063 B5 collision rule). Explicit range-total=\"?\" (gh#1877, ADR-0082 Amendment) is the OPEN/unproven- total state — cursor/hasMore server paging with no known row count yet: the range label renders \"Showing X–Y\" with no \"of N\", and the pager stays in has-more mode (next enabled) rather than hiding — distinct from both \"loading\" (attribute absent) and \"confirmed empty\" (range-total=\"0\"). Resolves to the normal finite behavior the moment a real number replaces the \"?\". 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 target's own \"?\" carries through identically); the identity rule: the footer's range-total derives from the table's range-total, never the table's filteredCount, and this branch wins even when the target's [paginate] is also > 0; (2) otherwise, when the target has [paginate] > 0, CLIENT mode: the target's filtered row count (search + column filters applied, before pagination). Refreshes on the target's `page` / `filter-change` / `sort` events in either branch. Widened named staleness edge: a programmatic `.data` swap on the target — or a `range-total` update on the target without an accompanying page move — emits no event; either re-set this footer's own attributes after such a change, or accept staleness until the target's next event."
+            },
+            {
+              "name": "range-of",
               "type": {
                 "text": "number"
               },
               "default": "0",
-              "description": "Total ROWS across all pages. Absent (the default) means \"not yet known\" (loading) — never \"zero\"; both the range label and the pager stay hidden until this is set. Explicit range-total=\"0\" is the confirmed-empty state (pager hidden; the `empty` slot renders in the range label's position when supplied). Named identically to table-toolbar-ui's [range-total] and table-ui's own [range-total] (gh#1754, ADR-0082) and deliberately NOT `total` (pagination-ui's `total` is total PAGES — the ADR-0063 B5 collision rule). When this attribute is unset, the footer derives it from the resolved target via a two-branch ladder (REQ-W-006, amended 0.2.0/ADR-0082): (1) the target's own [range-total] attribute, when present — the table-authoritative SERVER mode (gh#1754 Shape 1's second lawful composition); the identity rule: the footer's range-total derives from the table's range-total, never the table's filteredCount, and this branch wins even when the target's [paginate] is also > 0; (2) otherwise, when the target has [paginate] > 0, CLIENT mode: the target's filtered row count (search + column filters applied, before pagination). Refreshes on the target's `page` / `filter-change` / `sort` events in either branch. Widened named staleness edge: a programmatic `.data` swap on the target — or a `range-total` update on the target without an accompanying page move — emits no event; either re-set this footer's own attributes after such a change, or accept staleness until the target's next event."
+              "description": "gh#1877, ADR-0082 Amendment — secondary whole-set total for the \"filtered-of-whole\" shape: a client-side facet narrows [range-total] (a filtered count) while range-of names the unfiltered set size, e.g. \"Showing 1–4 of 4 traversals (6 total)\". Appends \"(of <range-of> total)\" onto the normal finite range text; unset (the default) changes nothing. Never applies while [range-total] is absent (loading) or \"?\" (open/unproven) — there's no finite range text to append onto yet. Named identically on table-toolbar-ui (ADR-0082 §\"same name on both companions\")."
+            },
+            {
+              "name": "range-noun",
+              "type": {
+                "text": "string"
+              },
+              "description": "gh#1877, ADR-0082 Amendment — optional per-slice noun appended after the range total (\"of 80 users\") so consumers stop hand-painting the noun themselves. Applies in both the normal finite range text and the open/unproven-total text (\"Showing 51–100 users\" with no \"of N\"). Unset (the default) changes nothing. Named identically on table-toolbar-ui (ADR-0082 §\"same name on both companions\")."
             },
             {
               "name": "siblings",
@@ -10083,11 +10098,26 @@
             },
             {
               "name": "range-total",
+              "type": {
+                "text": "[number, string]"
+              },
+              "default": "0",
+              "description": "Total row count across all pages, for the range summary (e.g. `320` in \"Showing 1–25 of 320\"). Distinct from pagination-ui's `total` (total PAGES) — this is total ROWS; deliberately not spelled `total` to avoid that cross-sibling name collision (ADR-0063 B5). See rangeStart. Explicit range-total=\"?\" (gh#1877, ADR-0082 Amendment) is the OPEN/unproven-total state — cursor/hasMore server paging with no known row count yet: the summary reads \"Showing X–Y\" with no \"of N\", requiring only [range-start]/[range-end] (> 0) to render, not rangeTotal too. Resolves to the normal finite summary the moment a real number replaces the \"?\". Named identically to table-footer-ui's own [range-total] (ADR-0082 §\"same name on both companions\")."
+            },
+            {
+              "name": "range-of",
               "type": {
                 "text": "number"
               },
               "default": "0",
-              "description": "Total row count across all pages, for the range summary (e.g. `320` in \"Showing 1–25 of 320\"). Distinct from pagination-ui's `total` (total PAGES) — this is total ROWS; deliberately not spelled `total` to avoid that cross-sibling name collision (ADR-0063 B5). See rangeStart."
+              "description": "gh#1877, ADR-0082 Amendment — secondary whole-set total for the \"filtered-of-whole\" shape: a client-side facet narrows [rangeTotal] (a filtered count) while rangeOf names the unfiltered set size, e.g. \"Showing 1–4 of 4 traversals (6 total)\". Appends \"(of <rangeOf> total)\" onto the normal finite range summary; unset (the default) changes nothing. Never applies while the summary is in its open (\"?\") or opted-out (all-zero) state. Named identically to table-footer-ui's own [range-of] (ADR-0082 §\"same name on both companions\")."
+            },
+            {
+              "name": "range-noun",
+              "type": {
+                "text": "string"
+              },
+              "description": "gh#1877, ADR-0082 Amendment — optional per-slice noun appended after the range total (\"of 80 users\") so consumers stop hand-painting the noun themselves. Applies in both the normal finite range summary and the open/unproven-total summary (\"Showing 51–100 users\" with no \"of N\"). Unset (the default) changes nothing. Named identically to table-footer-ui's own [range-noun] (ADR-0082 §\"same name on both companions\")."
             },
             {
               "name": "page-size",
@@ -10152,6 +10182,14 @@
               "default": "false",
               "description": "Suppress all four native controls/search at once (filter, sort, columns, search) as additive sugar over noFilter/noSort/noColumns/ noSearch (ADR-0076, ADIA2-9123). Precedence is pure, absolute OR — while set, all four stay off regardless of any individual no-* attribute's own value, with no partial re-enable path; to re-enable one control, remove chrome-only entirely and set the other three no-* attributes explicitly instead. The four granular attributes are not deprecated or removed — they remain the independently-addressable shipped API; chrome-only never replaces them, it's a convenience preset on top."
             },
+            {
+              "name": "title-always",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt out of the scope-reconciliation title hide: by default, a filled [slot=\"scope\"] region (a select/menu whose own displayed value already names the entity being listed) hides the separate [text]/[count] title cluster next to it, since together they'd say the same thing twice. Set [title-always] to keep the title cluster visible alongside a filled scope slot — e.g. a scope select PLUS an explicit text/count title on the same row (gh#1879)."
+            },
             {
               "name": "placeholder",
               "type": {
@@ -10185,6 +10223,10 @@
             {
               "name": "actions",
               "description": "Trailing action area — primary buttons (e.g. \"New row\") rendered after the search input, [slot=\"actions-leading\"], and the page-size select."
+            },
+            {
+              "name": "summary",
+              "description": "gh#1883 — trailing, text-tier cluster for an aggregate datum that belongs with the table but has no home in the range summary or the actions area (e.g. batch-detail's line-items Subtotal: `<span slot=\"summary\">Subtotal <strong>$1,240.00</strong></span>`). Rendered in the same flex row, after [slot=\"actions-leading\"] and before the page-size select / [slot=\"actions\"] — closer to the trailing edge than [slot=\"scope\"]/[range-*], since it reads as a result/total rather than pagination or view-switching context. Text sized via [--table-toolbar-summary-size] (shared with the \"Showing X–Y of N\" range summary — both are the same text tier). Plain author-supplied markup, same real-insertion-point pattern as every other table-toolbar slot — no forced typography beyond the font-size token. Stays visible at every ADR-0076 compaction stage: it is DATA (an aggregate figure the consumer chose to show), not chrome, so it is never dropped or compacted the way the range summary/ controls are — a consumer needing narrower-container behavior owns that via its own slotted content, not a component-side compaction rule. Empty (the default) has zero footprint on existing consumers."
             }
           ],
           "events": [
@@ -10337,10 +10379,10 @@
             {
               "name": "range-total",
               "type": {
-                "text": "number"
+                "text": "[number, string]"
               },
               "default": "0",
-              "description": "Total row count across ALL server pages (gh#1754, ADR-0082) — the table-authoritative server-mode data contract. Presence-gated: the attribute's PRESENCE, not its value, is the mode switch (checked via hasAttribute, never the coerced value alone — the same discipline table-footer-ui's own [range-total] ships). Absent (the default) means client mode: today's behavior exactly, [paginate] slices `.data` as always. Present with [paginate] > 0 means server mode: no local slicing (`.data` IS the current page and renders whole, after local search/sort/filter), the internal pager's page count becomes `max(1, ceil(range-total / paginate))` (one calc site, consolidated), and the internal page-reset sites (`data` set, `setFilter`, `clearFilters`) are suppressed so a fetch write-back never fights the pager back to page 0 — page state then moves only via pager interaction, the `footer-page` command, or `setState()`. The existing `page` event (0-based, unchanged) becomes the fetch trigger: the consumer listens for it, fetches that server page, and writes `.data` back. Explicit `range-total=\"0\"` is server-confirmed empty (pager hidden), never conflated with absent. With [paginate] absent/0, [range-total] is inert for this table's own rendering but stays readable by a bound table-footer-ui (REQ-W-006 branch 2) for its count-only label — see the footer-authoritative shape below, which remains lawful and is unaffected by this attribute. Named identically to table-toolbar-ui's and table-footer-ui's own [range-total] (rows, never `pagination-ui[total]`'s pages — the ADR-0063 B5 collision rule); a third instance of one name for one concept."
+              "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. Explicit `range-total=\"?\"` (gh#1877, ADR-0082 Amendment) is the OPEN/unproven-total state — cursor/hasMore server paging with no known row count yet: still server mode (still presence-gated), but the internal pager's page count stays exactly one page ahead of wherever the pager currently sits (never a fixed ceil(...) total), keeping `next` enabled indefinitely instead of hiding the pager the way a confirmed `range-total=\"0\"` would. Resolves to the normal finite server-mode behavior the instant a real number replaces the \"?\" — every reader downstream (table-toolbar-ui, table-footer-ui) shares this same distinction. Note: this prop is Number-typed and reflected; \"?\" parses to NaN (`+\"?\"`), and the coerced numeric PROPERTY is what carries the open/unproven signal (non-finite) — every reader checks the property, never `getAttribute(...) === '?'`. The DOM attribute itself keeps the authored \"?\" (gh#1895 — the framework's attribute-reflection leaves a non-finite Number value unwritten rather than stringifying it back as the literal \"NaN\")."
             },
             {
               "name": "filteredCount",
@@ -11153,7 +11195,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens + resets + page-frame + every primitive's CSS) into the document from anywhere in the DOM, so a surface renders fully-styled WITHOUT a hand-wired <link rel=\"stylesheet\"> in <head>. Layout-transparent (display: contents): the element owns no box; children lay out as if it weren't there. Mechanism: it imports the constructable-stylesheet twin of web-components.min.css (byte-identical to the CDN bundle, emitted from the same build buffer) and adopts it once into document.adoptedStyleSheets, deduped — adoption fires at module load, before paint. Coexists with the render-blocking <link> path; both deliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for multi-page / top-level surfaces (cacheable across navigations, zero flash); use <theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do not control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend). Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in attributes adopt their layer on demand — theme=\"ocean|forest|slate|…\" applies a named preset (adopts the themes layer; matches the [theme] hook) and scale=\"ui-sm|ui-md|ui-lg|content-sm|content-md|content-lg\" sets the sizing register (adopts the matching register layer). Deprecated aliases \"verse\" (→ ui-sm) and \"prose\" (→ content-md) still map onto the legacy [verse]/[prose] attributes; removed at v1.0. Each layer is fetched only when its attribute is set, so a bare provider stays lean. Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries the whole foundation); import @adia-ai/web-components/components/theme-provider explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery) and the page shells (chrome over the same foundation).",
+          "description": "Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens + resets + page-frame + every primitive's CSS) into the document from anywhere in the DOM, so a surface renders fully-styled WITHOUT a hand-wired <link rel=\"stylesheet\"> in <head>. Layout-transparent (display: contents): the element owns no box; children lay out as if it weren't there. Mechanism: it imports the constructable-stylesheet twin of web-components.min.css (byte-identical to the CDN bundle, emitted from the same build buffer) and adopts it once into document.adoptedStyleSheets, deduped — adoption fires at module load, before paint. Coexists with the render-blocking <link> path; both deliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for multi-page / top-level surfaces (cacheable across navigations, zero flash); use <theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do not control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend). Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in attributes adopt their layer on demand — theme=\"ocean|forest|slate|…\" applies a named preset (adopts the themes layer; matches the [theme] hook) and scale=\"ui-sm|ui-md|ui-lg|content-sm|content-md|content-lg\" sets the sizing register (adopts the matching register layer). Each layer is fetched only when its attribute is set, so a bare provider stays lean. Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries the whole foundation); import @adia-ai/web-components/components/theme-provider explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery) and the page shells (chrome over the same foundation).",
           "name": "UIThemeProvider",
           "tagName": "theme-provider",
           "superclass": {
@@ -11173,7 +11215,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Sizing register for the subtree — one of the six [scale] tiers: ui-sm (dense product UI), ui-md (base), ui-lg (touch/presentation), content-sm (compact article), content-md (long-form), content-lg (hero/marketing). Adopts the scale layer on demand; the reflected attribute is the [scale=\"…\"] CSS hook. Deprecated aliases \"verse\" (→ ui-sm) and \"prose\" (→ content-md) still map onto the legacy [verse]/[prose] attributes; removed at v1.0."
+              "description": "Sizing register for the subtree — one of the six [scale] tiers: ui-sm (dense product UI), ui-md (base), ui-lg (touch/presentation), content-sm (compact article), content-md (long-form), content-lg (hero/marketing). Adopts the scale layer on demand; the reflected attribute is the [scale=\"…\"] CSS hook."
             }
           ]
         }