@adia-ai/web-components 0.8.23 → 0.8.25

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog — @adia-ai/web-components
 
+## [0.8.25] — 2026-07-31
+
+### Fixed
+- **`theme-panel[parametric]` works with a non-root `[target]`** (gh#570). Custom-property formulas resolve at their DECLARING element's own cascade, then inherit the already-resolved value down — the `--a-radius-*`/`--a-space-*`/`--a-size-*` derived tokens are declared once, on `:root`, so a scoped target overriding `--a-density`/`--a-radius-k` never triggered their re-derivation; only root-target parametric theming ever actually worked. `theme-panel.js` now marks a non-root `[parametric]` target with `data-parametric-scope`; a new `styles/api/parametric-scope.css` (attribute-API layer, mirroring the codebase's own established pattern of duplicating `calc()` formulas across layers — see `[size="sm"]` in `api/sizing.css`) re-declares the same formula bodies scoped to that marker, so the target's own subtree gets a working copy of the full derivation chain (radius, space, inset, gap, padding, margin, size). `[theme]`/`color-scheme` scoping was never affected (both resolve per-element natively). Browser-verified: a scoped preview pane's radius and padding both react to the panel's sliders while a sibling under `:root` stays untouched.
+- **`chart-ui`'s `--color-<key>` per-series color hook is actually overridable from an ancestor** (gh#561). `#injectSeriesColors()` wrote `--color-{key}: var(--chart-N)` as an inline style on the chart HOST — inline styles beat everything but `!important`, so a consumer setting `--color-MAU` on any ancestor silently lost to the chart's own default. The method (and its call) are gone; each series element already carries its own `var(--color-{key}, var(--chart-{slot}))` fallback, which resolves the same default when unset and now lets an ancestor override win. `tooltip-ui`'s top-layer popover — which bridges `--color-{key}` values by copying them at show time, since a popover appended to `document.body` doesn't inherit custom properties from the chart's ancestor chain — read only the (now-removed) inline style; it now resolves each declared series key via `getComputedStyle` off `chart-ui`'s public `legendData`, so it correctly picks up an ancestor-set value too.
+
+### Added
+- **`anchor-bar-ui`** (gh#495, `status: beta`) — persistent, anchored, elevated surface for chrome that must stay visible while a condition holds: floating bulk-action toolbars, undo bars, sticky wizard/commit footers. Pre-build audit (§0) found the gap real: `toast-ui` is auto-dismissing (wrong lifecycle), `modal-ui`/`drawer-ui` are blocking overlays (wrong semantics), and the bulk-action-toolbar pattern's floating variant (gh#494/PR#509) hand-rolled a `card-ui` + `position: sticky` recipe scoped to one consumer that by its own documented rule "never `position: fixed` to the viewport" — structurally can't reach the viewport-global case (undo bars, arbitrary layouts). Default mode (`[viewport]` unset) generalizes that exact recipe as the primitive's own default: `position: sticky` within the nearest scroll container, `[anchor="bottom"\|"top"]` + `[align="start"\|"center"\|"end"]`. `[viewport]` opts into `position: fixed` to the browser viewport, promoted to the top layer via the Popover API (`popover="manual"`, mirroring `popover-ui`'s convention) so it wins stacking over shell chrome without a z-index war — manual popovers never light-dismiss or close on Escape, matching the "no auto-dismiss" persistence contract. `[open]` (default `false`) controls visibility via `opacity`/`visibility` transitions, never `display`/`[hidden]` — a `display:none` toggle resets `toolbar-ui`'s `ResizeObserver`-driven overflow measurement at 0px, the same trap the bulk-action-toolbar pattern's own code comments document. Bulk-action-toolbar pattern's own comment already named this primitive as its eventual home; its floating-variant demo now composes `anchor-bar-ui` directly instead of the hand-rolled `card-ui` recipe.
+- **`stat-ui` gains a `band` chart layout** (gh#557, adia-v2 ADIA2-7059). Neither existing chart placement produces the Gmail/Vercel/shadcn stat-card shape — inline squeezes the value column at 4-up widths (titles truncating to "Acti…"), `[bleed]` halves the text column. `band` (alongside `bleed`) stacks label/icon, value, chart, and change as four full-width rows via `grid-template-areas: "label icon" "value value" "chart chart" "change change"`; the chart band gets its own fixed-height token (`--stat-chart-band-height`, default `3rem`) with `aspect-ratio` released, text rows stay baseline-aligned, and it composes with `icon` exactly as the base layout does. No effect without a `slot="chart"` child, same guard as `bleed`. Replaces the interim `stat-ui[data-chart-band]` app-side override shipped downstream.
+- **`chart-ui` line/multi-line dot control + per-series emphasis** (gh#561, adia-v2 dashboard pass). Three related line-chart gaps: (1) `dots="all|none|hover|last"` (default `all`, back-compat) — `none` renders no `[data-dot]`s on dense series, `hover` shows only the hovered datum's dot (paired via DOM adjacency to its `[data-hit]` sibling, toggled through `chart-hover`/`chart-leave`), `last` shows only the terminal point per series; `[data-hit]` tooltip targets are untouched in every mode. (2) `series-emphasis="<seriesKey>"` for multi-line — the named series keeps area fill + full-strength line, every other series drops its area and renders line-only at the new `--chart-deemphasized-opacity` token (default 0.4). `y-max`/domain-padding for small-integer domains (also filed on the issue) is deferred — out of scope for this pass, noted on the issue.
+
+### Maintenance
+- **`components/` touched in this release window** (47 file(s), e.g. `adia-mark/adia-mark.examples.html`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (6 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (3 file(s), e.g. `bulk-action-toolbar/bulk-action-toolbar.examples.html`) — carried by the entries above.
+
+## [0.8.24] — 2026-07-30
+
+### Fixed
+- **`list-item-ui` two-line items center the leading glyph on the whole item** (gh#558, operator screenshot). The icon was pinned to the title row, hanging 9–18px above the item center on title+description rows — Material's two-line convention centers it. Explicit `grid-row: 1 / span 2` scoped by `:has([slot="description"])` (with no `grid-template-rows` the explicit grid has zero rows, so the old `1 / -1` collapsed to one row — the reason the earlier anatomy comment called them "identical"); single-line items untouched (probe: two-line offset 0/0/0, single-line 24px rows unchanged).
+- **`card-ui` pins a direct `<footer>` to the card bottom** (gh#559, operator screenshot). In an equal-height grid row, a shorter card's CTA floated at content end (Free tier 42px above the edge vs 17px on its siblings) — the buttons were already in footers; the card just had no pinning rule. `:has(> footer)` promotes the card to a flex column with `margin-top: auto` on the footer; footerless cards keep block flow. Probe: 17/17/17.
+- **`requiredIcons` drift cleared across 16 components** (gh#550). Eight primitives that auto-stamp icons (alert/drawer/feed/modal `x`, input steppers `caret-up`/`caret-down`, nav-group `caret-right`, swiper `caret-left`/`caret-right`, toolbar overflow `dots-three`) now declare `static requiredIcons`, mirrored in their yaml SoTs (calendar-grid and pagination gained the missing yaml blocks); four stale declarations pruned (combobox `check`, date-range-picker `arrow-right`, datetime-picker `clock`, select `magnifying-glass` — none ever stamped) and agent-questions' leftover yaml block removed (options render via option-card-ui since gh#276). Checker itself hardened: `//` line comments no longer read as stamp sites (button `plus` false positive) and yaml list entries may carry trailing `#` comments (select's three phantom mismatches). 125/125 components clean.
+- **`toolbar-ui` overflow measurement traps closed** (gh#528). (1) Flex-grow children (spacers, stretched groups) measured at their EXPANDED width, so the row always read "full" and the last action spilled unrecoverably — grow is zeroed for the read and restored. (2) A `display:none` mount committed a spill from a 0-width reading and stranded the bar collapsed — a zero-width guard now leaves everything visible until the ResizeObserver delivers a real size. Browser-verified both ways.
+- **Corpus/demo enum drift swept** (gh#529): 41 uses of never-implemented values (Tag `muted`/`primary`, Text `primary`/`muted`/`xxl`, Card `soft`/`primary`, Badge `subtle`, Chart `muted`, Button `danger`) mapped to their nearest real values across 15 harvest sources — they silently rendered as defaults. `verify:corpus` warnings 138 → 97.
+- **10 standalone example routes actually render** (gh#530): the sitemap pointed iframe-served routes at headless `.contents.html` fragments; thin standalone wrappers added (single-source fetch-inject), annotations repointed, `frame`/`theme-provider` demos wired for phosphor. 108/108 clean. The `check-required-icons` checker also now reads `<comp>.class.js` and all stamp shapes — 20 false positives gone, 19 real findings exposed → gh#550.
+
+### Maintenance
+- **`dist/` bundles rebuilt** in this cut's window (4 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`patterns/` touched in this release window** (7 file(s), e.g. `admin-keys-and-export/admin-keys-and-export.examples.html`) — carried by the entries above.
+
 ## [0.8.23] — 2026-07-30
 
 ### Removed

package/components/agent-questions/agent-questions.yaml

@@ -56,8 +56,6 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
-requiredIcons:
-  - check
 a2ui:
   rules:
     - rule: 'Multi-choice clarifying-question card emitted by an agent when it needs disambiguation before proceeding.'

package/components/alert/alert.class.js

@@ -42,6 +42,11 @@ function _warnOnce(key, message) {
 }
 
 export class UIAlert extends UIElement {
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['x'];
+
   static properties = {
     text:        { type: String,  default: '', reflect: true },
     title:       { type: String,  default: '', reflect: true },

package/components/alert/alert.yaml

@@ -173,6 +173,8 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - x
 a2ui:
   rules:
     - rule: 'Inline alert/banner for status messages within a content region. Severity via variant (info, success, warn, error).'

package/components/anchor-bar/anchor-bar.a2ui.json

@@ -0,0 +1,139 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AnchorBar.json",
+  "title": "AnchorBar",
+  "description": "Persistent, anchored, elevated surface for chrome that must stay visible while a condition holds — floating bulk-action toolbars, undo bars, sticky wizard/commit footers. Distinct from <toast-ui> (auto-dismissing, notification semantics) and <modal-ui>/<drawer-ui> (blocking overlays with backdrop + focus-trap semantics). Default mode anchors [anchor] to the nearest scroll container via `position: sticky` — the shape gh#494's bulk-action-toolbar pattern hand-rolled with card-ui + position:sticky. Opt into [viewport] for a surface that anchors to the browser viewport instead, promoted to the top layer via the Popover API (`popover=\"manual\"`) so it wins stacking over shell chrome without a z-index war. Visibility is [open] (default false, no auto-dismiss timer) — arbitrary content (typically <toolbar-ui> or <text-ui> + <button-ui>) rides the default slot.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "align": {
+      "description": "Horizontal alignment along the anchored edge.",
+      "type": "string",
+      "enum": [
+        "start",
+        "center",
+        "end"
+      ],
+      "default": "center"
+    },
+    "anchor": {
+      "description": "Viewport/container edge the bar sticks to.",
+      "type": "string",
+      "enum": [
+        "bottom",
+        "top"
+      ],
+      "default": "bottom"
+    },
+    "component": {
+      "const": "AnchorBar"
+    },
+    "open": {
+      "description": "Controls visibility. No auto-dismiss — caller toggles explicitly.",
+      "type": "boolean",
+      "default": false
+    },
+    "viewport": {
+      "description": "false (default) anchors to the nearest scroll container via `position: sticky` — safe for content with ResizeObserver-driven children (e.g. <toolbar-ui>'s overflow measurement never sees a display:none reset). true anchors to the browser viewport via `position: fixed` + Popover API top-layer promotion — note the native Popover UA stylesheet applies `display:none` while closed, which DOES reset ResizeObserver-driven children on first open; prefer the default for content wrapping <toolbar-ui>.",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "container",
+    "composes": [],
+    "events": {
+      "close": {
+        "description": "Fired when [open] becomes false."
+      },
+      "open": {
+        "description": "Fired when [open] becomes true."
+      }
+    },
+    "examples": [
+      {
+        "description": "Bottom-anchored bar containing a toolbar with a selection count and action buttons, shown persistently while open.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"bar\"\n    ]\n  },\n  {\n    \"id\": \"bar\",\n    \"component\": \"AnchorBar\",\n    \"anchor\": \"bottom\",\n    \"open\": true,\n    \"children\": [\n      \"toolbar\"\n    ]\n  },\n  {\n    \"id\": \"toolbar\",\n    \"component\": \"Toolbar\",\n    \"children\": [\n      \"count\"\n    ]\n  },\n  {\n    \"id\": \"count\",\n    \"component\": \"Text\",\n    \"text\": \"3 selected\"\n  }\n]",
+        "name": "anchor-bar-demo"
+      }
+    ],
+    "keywords": [
+      "anchor",
+      "bar",
+      "floating",
+      "toolbar",
+      "undo",
+      "persistent",
+      "sticky",
+      "footer",
+      "selection",
+      "bulk action"
+    ],
+    "name": "UIAnchorBar",
+    "related": [],
+    "slots": {
+      "default": {
+        "description": "Arbitrary bar content — typically <toolbar-ui> (bulk-action bars) or <text-ui> + <button-ui> (undo bars, wizard footers). The bar owns only the elevated surface chrome (bg/border/radius/shadow) and positioning; content layout is the slotted children's own."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "status": "beta",
+    "synonyms": {
+      "bar": [
+        "toolbar",
+        "anchor",
+        "footer"
+      ],
+      "floating": [
+        "anchor",
+        "sticky",
+        "popover"
+      ],
+      "undo": [
+        "anchor",
+        "toast",
+        "alert"
+      ]
+    },
+    "tag": "anchor-bar-ui",
+    "tokens": {
+      "--anchor-bar-bg": {
+        "description": "Override background color"
+      },
+      "--anchor-bar-border": {
+        "description": "Override border color"
+      },
+      "--anchor-bar-fg": {
+        "description": "Override text color"
+      },
+      "--anchor-bar-offset": {
+        "description": "Override distance from the anchored edge"
+      },
+      "--anchor-bar-radius": {
+        "description": "Override corner radius"
+      },
+      "--anchor-bar-shadow": {
+        "description": "Override elevation shadow"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/anchor-bar/anchor-bar.class.js

@@ -0,0 +1,124 @@
+/**
+ * Non-side-effect class export for `<anchor-bar-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/anchor-bar`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <anchor-bar-ui> — Persistent, anchored, elevated surface (gh#495).
+ *
+ * Fills the gap between <toast-ui> (auto-dismissing) and <modal-ui>/
+ * <drawer-ui> (blocking overlays): chrome that must stay visible while a
+ * condition holds — floating bulk-action toolbars, undo bars, sticky
+ * wizard/commit footers.
+ *
+ *     <!-- Default — sticky within the nearest scroll container -->
+ *     <anchor-bar-ui anchor="bottom" open>
+ *       <toolbar-ui role="toolbar" aria-label="Bulk actions">…</toolbar-ui>
+ *     </anchor-bar-ui>
+ *
+ *     <!-- Viewport-anchored, top-layer (undo bars, arbitrary layouts) -->
+ *     <anchor-bar-ui anchor="bottom" viewport open>
+ *       <text-ui>3 items archived</text-ui>
+ *       <button-ui text="Undo" variant="ghost"></button-ui>
+ *     </anchor-bar-ui>
+ *
+ * [viewport] promotes the element itself to the top layer via the Popover
+ * API (`popover="manual"` + `showPopover()`/`hidePopover()`), mirroring
+ * `popover-ui`'s established convention — but `manual` popovers, unlike
+ * `auto`, never light-dismiss or close on Escape: visibility is entirely
+ * caller-driven via [open], matching the "no auto-dismiss" persistence
+ * contract. No listeners are added when [viewport] is false — a `[toggle]`
+ * listener exists only while the element carries `popover="manual"`, to
+ * reflect programmatic/browser-driven `showPopover()`/`hidePopover()` calls
+ * back into the [open] property.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIAnchorBar extends UIElement {
+  static properties = {
+    anchor:   { type: String,  default: 'bottom', reflect: true },
+    align:    { type: String,  default: 'center', reflect: true },
+    viewport: { type: Boolean, default: false,    reflect: true },
+    open:     { type: Boolean, default: false,     reflect: true },
+  };
+
+  static template = () => null;
+
+  #popoverBound = false;
+
+  connected() {
+    if (this.viewport) this.#bindPopover();
+  }
+
+  updated(changed) {
+    if (changed.has('viewport')) {
+      if (this.viewport) this.#bindPopover();
+      else this.#unbindPopover();
+    }
+    if (changed.has('open')) {
+      this.#sync();
+      this.dispatchEvent(new Event(this.open ? 'open' : 'close', { bubbles: true }));
+    }
+  }
+
+  render() {
+    // Re-assert popover state on every reactive pass — cheap no-op when
+    // already in sync (guards match(':popover-open') before calling).
+    if (this.viewport) this.#sync();
+  }
+
+  disconnected() {
+    if (this.viewport && this.matches(':popover-open')) {
+      try { this.hidePopover(); } catch { /* popover API unavailable */ }
+    }
+    if (this.#popoverBound) {
+      this.#popoverBound = false;
+      this.removeEventListener('toggle', this.#onToggle);
+    }
+  }
+
+  // ── Internal ──
+
+  #bindPopover() {
+    if (!this.hasAttribute('popover')) this.setAttribute('popover', 'manual');
+    if (!this.#popoverBound) {
+      this.#popoverBound = true;
+      this.addEventListener('toggle', this.#onToggle);
+    }
+    this.#sync();
+  }
+
+  #unbindPopover() {
+    if (this.matches(':popover-open')) {
+      try { this.hidePopover(); } catch { /* popover API unavailable */ }
+    }
+    if (this.#popoverBound) {
+      this.#popoverBound = false;
+      this.removeEventListener('toggle', this.#onToggle);
+    }
+    this.removeAttribute('popover');
+  }
+
+  #sync() {
+    if (!this.viewport) return;
+    if (this.open && !this.matches(':popover-open')) {
+      try { this.showPopover(); } catch { /* popover API unavailable */ }
+    } else if (!this.open && this.matches(':popover-open')) {
+      try { this.hidePopover(); } catch { /* popover API unavailable */ }
+    }
+  }
+
+  #onToggle = (e) => {
+    const nowOpen = e.newState === 'open';
+    if (nowOpen !== this.open) this.open = nowOpen;
+  };
+}

package/components/anchor-bar/anchor-bar.css

@@ -0,0 +1,140 @@
+/* ═══════════════════════════════════════════════════════════════
+   ANCHOR-BAR-N — Persistent anchored surface (floating toolbars,
+   undo bars, wizard footers). Issue gh-495.
+
+   [open] is a dynamic runtime-toggled attribute and this component's
+   base rule anchors to `:popover-open` in [viewport] mode — both
+   selector shapes are hoisted OUT of @scope per BROWSER-COMPAT.md §3a
+   Flavor B (Safari 17.x fails to restyle `:scope[dyn-attr]` on
+   attribute removal) and the top-layer convention in
+   component-token-contract.md (popover-promoted content's non-token
+   rules stay outside @scope). [anchor] / [align] / [viewport] are
+   set once at markup (mode selection, not toggled per-frame) and stay
+   inside @scope alongside the token block, mirroring toast-ui's
+   [position="…"] mode-attribute rules.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (anchor-bar-ui) {
+  :where(:scope) {
+    --anchor-bar-bg:       var(--md-sys-color-neutral-surface-bright);
+    --anchor-bar-fg:       var(--md-sys-color-neutral-on-surface);
+    --anchor-bar-border:   var(--md-sys-color-neutral-outline-variant);
+    --anchor-bar-radius:   var(--a-radius-lg);
+    --anchor-bar-shadow:   var(--a-shadow-lg);
+    --anchor-bar-px:       var(--a-space-4);
+    --anchor-bar-py:       var(--a-space-3);
+    --anchor-bar-gap:      var(--a-space-3);
+    --anchor-bar-offset:   var(--a-space-4);
+    --anchor-bar-duration: var(--a-duration);
+    --anchor-bar-easing:   var(--a-easing-out);
+    --anchor-bar-font:     var(--a-font-family);
+    --anchor-bar-size:     var(--a-ui-md);
+    /* width:100% + a capped max-width, NOT width:max-content/fit-content —
+       the bulk-action-toolbar pattern (gh-494) hit this exact trap first:
+       a fit-content box derives its size from slotted <toolbar-ui>'s
+       rendered content, but toolbar-ui's own overflow reflow measures ITS
+       available width FROM this box — a self-reinforcing collapse the
+       first time reflow runs while still narrow (0 available width spills
+       every item into the "more" overflow popover, and toolbar-ui does not
+       reliably re-measure afterward). A fixed max-width breaks the loop:
+       deterministic, independent of the toolbar's own spillover state.
+       Both tokens are consumer-overridable, matching toast-ui's own
+       `--toast-max-width` precedent. */
+    --anchor-bar-width:     100%;
+    --anchor-bar-max-width: min(46rem, calc(100% - var(--a-space-6)));
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    gap: var(--anchor-bar-gap);
+    width: var(--anchor-bar-width);
+    max-width: var(--anchor-bar-max-width);
+    padding: var(--anchor-bar-py) var(--anchor-bar-px);
+    background: var(--anchor-bar-bg);
+    color: var(--anchor-bar-fg);
+    font-family: var(--anchor-bar-font);
+    font-size: var(--anchor-bar-size);
+    border: 1px solid var(--anchor-bar-border);
+    border-radius: var(--anchor-bar-radius);
+    box-shadow: var(--anchor-bar-shadow);
+  }
+
+  /* Horizontal alignment along the anchored edge — static mode attr. */
+  :where(:scope),
+  :where(:scope[align="center"]) { margin-inline: auto; }
+  :where(:scope[align="start"])  { margin-inline: 0; }
+  :where(:scope[align="end"])    { margin-inline: auto 0; }
+
+  /* A slotted <toolbar-ui> (the bulk-action-bar shape) must fill the bar's
+     real width, not shrink to its own content — mirrors toast-ui's
+     `[slot="message"] { flex: 1; min-width: 0; }`. Without this, toolbar-ui
+     is a default `flex: 0 1 auto` item that hugs its own content, and its
+     overflow reflow then measures ITS OWN shrunk size as "available width"
+     — the same circular-collapse trap the width token comment above
+     documents, one level down. Other default-slot content (text-ui +
+     button-ui for an undo bar) keeps natural content sizing. */
+  :scope > toolbar-ui {
+    flex: 1;
+    min-width: 0;
+  }
+}
+
+/* ── Positioning + visibility — outside @scope, see file-header note ──
+   Default mode: sticky within the nearest scroll container (never
+   `position: fixed` to the viewport) — the same recipe the
+   bulk-action-toolbar pattern (issue gh-494) hand-rolled with card-ui, now
+   the primitive's own default. Visibility toggles opacity/visibility,
+   never display/[hidden] — a display:none reset stalls toolbar-ui's
+   ResizeObserver-driven overflow measurement at 0px (documented gotcha,
+   packages/web-components/patterns/bulk-action-toolbar). */
+anchor-bar-ui {
+  position: sticky;
+  z-index: 9999;  /* fallback stacking; [viewport] wins via top-layer */
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(var(--anchor-bar-offset));
+  transition: opacity var(--anchor-bar-duration) var(--anchor-bar-easing),
+              transform var(--anchor-bar-duration) var(--anchor-bar-easing),
+              visibility 0s linear var(--anchor-bar-duration);
+}
+anchor-bar-ui[anchor="top"] {
+  transform: translateY(calc(-1 * var(--anchor-bar-offset)));
+}
+anchor-bar-ui[open] {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto;
+  transform: translateY(0);
+  transition: opacity var(--anchor-bar-duration) var(--anchor-bar-easing),
+              transform var(--anchor-bar-duration) var(--anchor-bar-easing);
+}
+
+anchor-bar-ui,
+anchor-bar-ui[anchor="bottom"] { bottom: var(--anchor-bar-offset); top: auto; }
+anchor-bar-ui[anchor="top"]    { top: var(--anchor-bar-offset); bottom: auto; }
+
+/* [viewport] — position:fixed to the browser viewport; [popover="manual"]
+   (set in anchor-bar.class.js) promotes to the top layer once shown, so
+   this wins stacking over shell chrome without a z-index war. `env()`
+   safe-area insets are a CSS environment function, not a raw px literal
+   — no token exists for device safe-area, this is the platform-standard
+   way to read it. */
+anchor-bar-ui[viewport] {
+  position: fixed;
+  left: 0;
+  right: 0;
+}
+anchor-bar-ui[viewport][anchor="bottom"] {
+  bottom: calc(var(--anchor-bar-offset) + env(safe-area-inset-bottom, 0px));
+}
+anchor-bar-ui[viewport][anchor="top"] {
+  top: calc(var(--anchor-bar-offset) + env(safe-area-inset-top, 0px));
+}
+
+@media (prefers-reduced-motion: reduce) {
+  anchor-bar-ui,
+  anchor-bar-ui[open] { transition: none; }
+}

package/components/anchor-bar/anchor-bar.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `<anchor-bar-ui>` — Persistent, anchored, elevated surface for chrome that must stay visible while a condition holds — floating bulk-action toolbars, undo bars, sticky wizard/commit footers. Distinct from <toast-ui> (auto-dismissing, notification semantics) and <modal-ui>/<drawer-ui> (blocking overlays with backdrop + focus-trap semantics). Default mode anchors [anchor] to the nearest scroll container via `position: sticky` — the shape gh#494's bulk-action-toolbar pattern hand-rolled with card-ui + position:sticky. Opt into [viewport] for a surface that anchors to the browser viewport instead, promoted to the top layer via the Popover API (`popover="manual"`) so it wins stacking over shell chrome without a z-index war. Visibility is [open] (default false, no auto-dismiss timer) — arbitrary content (typically <toolbar-ui> or <text-ui> + <button-ui>) rides the default slot.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/anchor-bar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type AnchorBarCloseEvent = CustomEvent<unknown>;
+export type AnchorBarOpenEvent = CustomEvent<unknown>;
+
+export class UIAnchorBar extends UIElement {
+  /** Horizontal alignment along the anchored edge. */
+  align: 'start' | 'center' | 'end';
+  /** Viewport/container edge the bar sticks to. */
+  anchor: 'bottom' | 'top';
+  /** Controls visibility. No auto-dismiss — caller toggles explicitly. */
+  open: boolean;
+  /** false (default) anchors to the nearest scroll container via `position: sticky` — safe for content with ResizeObserver-driven children (e.g. <toolbar-ui>'s overflow measurement never sees a display:none reset). true anchors to the browser viewport via `position: fixed` + Popover API top-layer promotion — note the native Popover UA stylesheet applies `display:none` while closed, which DOES reset ResizeObserver-driven children on first open; prefer the default for content wrapping <toolbar-ui>. */
+  viewport: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAnchorBar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: AnchorBarCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'open', listener: (ev: AnchorBarOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/anchor-bar/anchor-bar.examples.md

@@ -0,0 +1,32 @@
+# anchor-bar — Examples
+
+## anchor
+
+```html
+<div style="position: relative; height: 6rem; overflow: auto; border: 1px solid var(--md-sys-color-neutral-outline-variant); border-radius: var(--a-radius-md);">
+  <div style="height: 10rem;"></div>
+  <anchor-bar-ui anchor="bottom" open>
+    <text-ui>Bottom-anchored</text-ui>
+  </anchor-bar-ui>
+</div>
+```
+
+## align
+
+```html
+<div style="position: relative; height: 4rem; overflow: auto; border: 1px solid var(--md-sys-color-neutral-outline-variant); border-radius: var(--a-radius-md);">
+  <anchor-bar-ui anchor="bottom" align="start" open>
+    <text-ui>Start</text-ui>
+  </anchor-bar-ui>
+</div>
+```
+
+## viewport
+
+```html
+<button-ui text="Archive item" variant="outline" size="sm" onclick="customElements.whenDefined('anchor-bar-ui').then(()=>{const b=document.getElementById('viewport-undo-bar'); if(b) b.open = true;})"></button-ui>
+<anchor-bar-ui id="viewport-undo-bar" anchor="bottom" viewport>
+  <text-ui>1 item archived</text-ui>
+  <button-ui text="Undo" variant="ghost" size="sm" onclick="const b=this.closest('anchor-bar-ui'); if(b) b.open=false;"></button-ui>
+</anchor-bar-ui>
+```

package/components/anchor-bar/anchor-bar.js

@@ -0,0 +1,17 @@
+/**
+ * `<anchor-bar-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIAnchorBar } from '@adia-ai/web-components/components/anchor-bar/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIAnchorBar } from './anchor-bar.class.js';
+
+defineIfFree('anchor-bar-ui', UIAnchorBar);
+
+export { UIAnchorBar };