@adia-ai/web-components 0.6.45 → 0.6.47

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.47] — 2026-05-29
+
+### Added — `<card-ui>` `[grow]` section attribute
+
+- **`components/card/card.css`** — `<section grow>` inside `card-ui` fills the card's remaining vertical height via `flex: 1`. The card becomes a `flex-direction: column` container when any direct `<section[grow]>` child is present, so the grow section absorbs the leftover space after header/footer. Requires the card to have a definite height (explicit inline height, grid row track, or flex parent) — a content-sized card has nothing to fill. Composable with `[bleed]`: `<section bleed grow>` for edge-to-edge fill surfaces (maps, canvases, full-bleed tables). A `<chart-ui>` directly inside `<section bleed>` auto-grows without `[grow]` (pre-existing zero-config convenience for the common chart case).
+- **`components/card/card.examples.html`** — examples demonstrating the grow pattern.
+- **`components/card/card.yaml`** — a2ui rules updated to document `[grow]`.
+
+### Maintenance
+
+- **`dist/web-components.min.css`** — bundle rebuild reflecting the `card.css` addition.
+
+## [0.6.46] — 2026-05-29
+
+### Added — declarative `traits="..."` Quick start sections on all 56 trait pages
+
+- **`traits/*/\*.examples.html`** — every trait page now opens with a "Quick start" section before the hero demo showing `traits="traitname"` on a real `*-ui` host element. No JS, no import — the declarative attribute is the primary example. Variants shown where config attrs exist. Hallucinated config attr names corrected in 13 pages (agents invented plausible-sounding names; fixed against JS source: e.g. `data-snap-grid` not `data-grid-size`, `data-noise-strength` not `data-noise-opacity`, `data-intersection-threshold` not `data-threshold`, etc.).
+
+### Added — expanded slot vocabulary for `header-ui`, `footer-ui`, `card-ui`
+
+- **`components/header/header.yaml`** — added `icon`, `heading`, `description` slots (previously only `default` + `action` were declared, but the parent container's `@scope` activates a 5-slot grid vocabulary when these are present). Each description explains the parent-`@scope` activation contract.
+- **`components/footer/footer.yaml`** — added `heading`, `description`, `action`, `action-leading` slots (all were styled by card/drawer/modal `@scope` but absent from the yaml; footer `heading`/`description` is the trend-stat / KPI pattern).
+- **`components/card/card.yaml`** — added `media` slot (full-bleed hero image/video region); updated `heading`, `description`, `action`, `action-leading` descriptions to accurately state they work in both `<header>` AND `<footer>` context, not just "in the header".
+
+### Fixed — spurious `bleed` removed from 31 section elements
+
+- **`patterns/kanban-board/kanban-board.examples.html`** and **`traits/confetti|magnetic-hover|tilt-hover/...examples.html`** — removed `bleed` from `<section bleed>` where the direct first child was `text-ui`, `stack-ui`, or `list-ui` without `divider`. `bleed` removes the card section's inset padding and is only correct for edge-to-edge content (tables, charts, code, divider-lists); it was being cargo-culted onto text sections that needed normal padding.
+
+### Fixed — stale token references in shipped examples
+
+- **`components/skeleton/skeleton.examples.html`**: `var(--ui-border)` → `var(--a-border)` (dead token; border was rendering colorless).
+- **`styles/overview.examples.html`**: token tier documentation table updated — `--ui-primary` → `--a-primary`, `--button-bg: var(--ui-primary)` → `var(--a-primary)` (the actual semantic token and component wiring).
+
+### Maintenance
+
+- **`packages/web-components/README.md`** — CDN example URLs updated from frozen `@0.6.30` to `@0.6` minor-range; `check:cdn-pins` guard added to `npm run check` aggregate.
+- **`dist/web-components.min.{js,css}` + `dist/icons-manifest.js`** — bundle rebuild.
+
 ## [0.6.45] — 2026-05-29
 
 ### Fixed — `<canvas-ui>` lazy `a2ui-root` import uses a bare specifier (FEEDBACK-85, follow-up to FB-81)

package/README.md

@@ -38,12 +38,14 @@ Since **v0.6.30**, this package ships pre-flattened + minified bundles under `di
 
 ```html
 <!-- CSS: all primitives, tokens, resets (443 KB raw / ~50 KB gzipped) -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6.30/dist/web-components.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6/dist/web-components.min.css">
 
 <!-- JS: registers all 95 primitives (~250 KB gzipped via Brotli) -->
-<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6.30/dist/web-components.min.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6/dist/web-components.min.js"></script>
 ```
 
+The `@0.6` range tracks the latest `0.6.x` patch automatically (won't jump to a breaking `0.7`). For reproducible builds, pin an exact version instead — e.g. `@adia-ai/web-components@0.6.45/dist/web-components.min.css`.
+
 For composite shells, add the corresponding bundle from `@adia-ai/web-modules` — see [its README](../web-modules/#cdn-no-bundler--codepen-marketing-pages-static-html) or the [CDN usage guide](https://ui-kit.exe.xyz/site/cdn-usage). The kitchen-sink path is `@adia-ai/web-modules/dist/everything.min.js` (all primitives + all 4 shells; ~190 KB gzipped) — one tag for CodePen demos.
 
 **Pick ONE bundle path.** Mixing (e.g. `everything.min.js` + a separate `web-components.min.js`) causes `customElements.define` to throw "name already defined" on dup-load. The choice tree:

package/components/card/card.a2ui.json

@@ -115,19 +115,22 @@
     ],
     "slots": {
       "description": {
-        "description": "Optional descriptive text beneath the heading. Renders in the header slot at body-subtle typography. Use for short metadata lines (timestamp, author, status sentence)."
+        "description": "Secondary metadata — grid row 2 beneath the heading inside `<header>`, or a period/caption line beneath a metric inside `<footer>` (e.g. \"Jan – Mar 2024\"). Also accepts bare `<p>` / `<small>` / body-variant `<text-ui>` as direct children without slot=\"description\". Triggers space-between layout in the footer when combined with slot=\"action\"."
       },
       "action": {
-        "description": "Trailing action cluster in the header (e.g. icon-buttons, menu trigger, more-options). Aligns to the header's flex-end edge."
+        "description": "Trailing control cluster inside `<header>` (icon-buttons, menu trigger, more-options) or the primary action cluster inside `<footer>` (e.g. Save, Confirm). Aligns to the flex-end edge in both contexts. Pair with slot=\"action-leading\" for dual-cluster footers."
       },
       "action-leading": {
-        "description": "Leading action cluster in the header (e.g. back button, switcher, breadcrumb-context). Aligns to the header's flex-start edge, before the icon/heading column."
+        "description": "Leading control cluster — inline-start edge of the header or footer. In the header: back button, breadcrumb context, or workspace switcher, before the icon/heading column. In the footer: secondary action (e.g. Back) opposite the primary cluster."
       },
       "heading": {
-        "description": "Card title. Renders in the header slot with title typography. Typically a short noun phrase or document/object name."
+        "description": "Primary title — grid row 1 inside `<header>`, or the prominent metric value inside `<footer>` (trend-stat / KPI pattern). Also accepts bare `<h1>`–`<h6>` tags as direct children without slot=\"heading\". A slot=\"heading\" wrapper can contain inline badges or metadata alongside the title text."
       },
       "icon": {
-        "description": "Optional leading icon for the card header (status / brand / type marker). Renders next to the heading. Use `<icon-ui name=\"…\">` or any inline icon element."
+        "description": "Leading icon for the card header — status, brand, or type marker. Placed in column 1 of the 3-column header grid when present; heading + description shift to column 2. Use `<icon-ui name=\"…\">`, `<avatar-ui>`, or any inline icon element as a DIRECT child of the `<header>` with slot=\"icon\" (not inside a wrapper — direct-child only, per the :has(> [slot=\"icon\"]) gate)."
+      },
+      "media": {
+        "description": "Full-bleed media region — placed before the first `<header>` or `<section>` as the card's hero image / video / illustration slot. Stretches edge-to-edge (negative margin equal to the card's inset); first-child `[slot=\"media\"]` gets zero border-radius on the top corners so it sits flush with the card border."
       }
     },
     "states": [

package/components/card/card.css

@@ -304,12 +304,28 @@
     padding: 0;
   }
 
-  /* Flex-column growth for bleed chart cards (sparklines, area, line).
-     Switches the card to a column flex container so the bleed section
-     can flex-grow to fill remaining height after the header. The chart
-     then uses height:100% to fill the section. Only activates when a
-     chart-ui is a direct child of a bleed section — no effect on other
-     card layouts. */
+  /* [grow] — section fills remaining card height. Switches the card to a
+     column flex container so the section flex-grows into the leftover
+     space after the header/footer. Matches the col-ui[grow] / row-ui[grow]
+     semantics (flex:1) — same mental model, applied to a card body section.
+     Requires the card to have a definite height (inline height, a grid row
+     track, or a flex parent); a content-sized card has no leftover to fill.
+     Combine with [bleed] for edge-to-edge fill (tables, charts, maps):
+     <section bleed grow>. */
+  :scope:has(> section[grow]) {
+    display: flex;
+    flex-direction: column;
+  }
+
+  & > section[grow] {
+    flex: 1;
+    min-height: 0;
+  }
+
+  /* Auto-grow for bleed chart cards (sparklines, area, line) — a chart-ui
+     directly inside a bleed section fills height without an explicit [grow]
+     (the chart itself uses height:100%). Equivalent to the [grow] rule
+     above; kept as a zero-config convenience for the common chart case. */
   :scope:has(> section[bleed] > chart-ui) {
     display: flex;
     flex-direction: column;

package/components/card/card.yaml

@@ -61,27 +61,45 @@ events: {}
 slots:
   icon:
     description: >-
-      Optional leading icon for the card header (status / brand / type
-      marker). Renders next to the heading. Use `<icon-ui name="…">` or
-      any inline icon element.
+      Leading icon for the card header — status, brand, or type marker.
+      Placed in column 1 of the 3-column header grid when present;
+      heading + description shift to column 2. Use `<icon-ui name="…">`,
+      `<avatar-ui>`, or any inline icon element as a DIRECT child of the
+      `<header>` with slot="icon" (not inside a wrapper — direct-child
+      only, per the :has(> [slot="icon"]) gate).
   heading:
     description: >-
-      Card title. Renders in the header slot with title typography.
-      Typically a short noun phrase or document/object name.
+      Primary title — grid row 1 inside `<header>`, or the prominent metric
+      value inside `<footer>` (trend-stat / KPI pattern). Also accepts bare
+      `<h1>`–`<h6>` tags as direct children without slot="heading". A
+      slot="heading" wrapper can contain inline badges or metadata alongside
+      the title text.
   description:
     description: >-
-      Optional descriptive text beneath the heading. Renders in the
-      header slot at body-subtle typography. Use for short metadata
-      lines (timestamp, author, status sentence).
+      Secondary metadata — grid row 2 beneath the heading inside `<header>`,
+      or a period/caption line beneath a metric inside `<footer>` (e.g.
+      "Jan – Mar 2024"). Also accepts bare `<p>` / `<small>` / body-variant
+      `<text-ui>` as direct children without slot="description". Triggers
+      space-between layout in the footer when combined with slot="action".
   action:
     description: >-
-      Trailing action cluster in the header (e.g. icon-buttons, menu
-      trigger, more-options). Aligns to the header's flex-end edge.
+      Trailing control cluster inside `<header>` (icon-buttons, menu
+      trigger, more-options) or the primary action cluster inside `<footer>`
+      (e.g. Save, Confirm). Aligns to the flex-end edge in both contexts.
+      Pair with slot="action-leading" for dual-cluster footers.
   action-leading:
     description: >-
-      Leading action cluster in the header (e.g. back button, switcher,
-      breadcrumb-context). Aligns to the header's flex-start edge,
-      before the icon/heading column.
+      Leading control cluster — inline-start edge of the header or footer.
+      In the header: back button, breadcrumb context, or workspace switcher,
+      before the icon/heading column. In the footer: secondary action (e.g.
+      Back) opposite the primary cluster.
+  media:
+    description: >-
+      Full-bleed media region — placed before the first `<header>` or
+      `<section>` as the card's hero image / video / illustration slot.
+      Stretches edge-to-edge (negative margin equal to the card's inset);
+      first-child `[slot="media"]` gets zero border-radius on the top
+      corners so it sits flush with the card border.
 states:
 - name: idle
   description: Default, ready for interaction.
@@ -119,6 +137,11 @@ a2ui:
     row 2 without needing slot="description".
   - Multiple <section> siblings are allowed and stack vertically. [bleed] on a section removes its margin for edge-to-edge
     content (tables, charts); [padding] adds a canvas-scrim background for hero regions.
+  - '[grow] on a section makes it fill the card''s remaining height (flex:1 — same semantics as col-ui[grow]/row-ui[grow]).
+    The card becomes a flex column so the section absorbs the leftover space after the header/footer. Requires the card to
+    have a definite height (inline height, grid row track, or flex parent) — a content-sized card has nothing to fill.
+    Combine with [bleed] for edge-to-edge fill: <section bleed grow>. A <chart-ui> directly inside a <section bleed>
+    auto-grows without [grow] (zero-config convenience for the common chart case).'
   - 'Footer with a [slot="description"] + [slot="action"] pair triggers justify-content: space-between — useful for a "Last
     saved …" note on the left and a Save/Cancel button group on the right.'
   - >-

package/components/footer/footer.a2ui.json

@@ -61,8 +61,20 @@
       "table"
     ],
     "slots": {
+      "description": {
+        "description": "Caption or period text rendered beneath slot=\"heading\" — small, muted. Triggers space-between layout when combined with slot=\"action\". Also accepts bare <p> / <small> elements as direct children without slot=\"description\"."
+      },
       "default": {
-        "description": "Default slot — primary child content."
+        "description": "Default slot — primary child content. Typically flat <button-ui> children laid out by the `justify` prop. Prefer flat children; a nested <row-ui> double-applies layout and breaks the chrome's gap."
+      },
+      "action": {
+        "description": "Trailing action cluster — self-aligns to the inline-end edge of the footer. Pair with slot=\"action-leading\" for dual-cluster footers (e.g. Back on the left, Save on the right). Activated by card-ui, drawer-ui, and modal-ui @scope rules."
+      },
+      "action-leading": {
+        "description": "Leading action cluster — self-aligns to the inline-start edge of the footer. Typically a Back or secondary action that needs to sit opposite the primary cluster. Activated by drawer-ui @scope; also works in card-ui footers via the same slot selector."
+      },
+      "heading": {
+        "description": "Metric or period label — rendered prominently at the leading edge of the footer chrome (e.g. \"$12.4k\" / \"Jan – Mar 2024\"). When present the parent's @scope switches to a heading + description layout. Pairs with slot=\"description\" for a caption line below the value (trend-stat footer pattern). Activated by card-ui and drawer-ui @scope rules."
       }
     },
     "states": [

package/components/footer/footer.yaml

@@ -21,7 +21,35 @@ props:
 events: {}
 slots:
   default:
-    description: "Default slot — primary child content."
+    description: >-
+      Default slot — primary child content. Typically flat <button-ui>
+      children laid out by the `justify` prop. Prefer flat children; a
+      nested <row-ui> double-applies layout and breaks the chrome's gap.
+  heading:
+    description: >-
+      Metric or period label — rendered prominently at the leading edge of
+      the footer chrome (e.g. "$12.4k" / "Jan – Mar 2024"). When present
+      the parent's @scope switches to a heading + description layout. Pairs
+      with slot="description" for a caption line below the value (trend-stat
+      footer pattern). Activated by card-ui and drawer-ui @scope rules.
+  description:
+    description: >-
+      Caption or period text rendered beneath slot="heading" — small,
+      muted. Triggers space-between layout when combined with slot="action".
+      Also accepts bare <p> / <small> elements as direct children without
+      slot="description".
+  action:
+    description: >-
+      Trailing action cluster — self-aligns to the inline-end edge of the
+      footer. Pair with slot="action-leading" for dual-cluster footers (e.g.
+      Back on the left, Save on the right). Activated by card-ui, drawer-ui,
+      and modal-ui @scope rules.
+  action-leading:
+    description: >-
+      Leading action cluster — self-aligns to the inline-start edge of the
+      footer. Typically a Back or secondary action that needs to sit opposite
+      the primary cluster. Activated by drawer-ui @scope; also works in
+      card-ui footers via the same slot selector.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/header/header.a2ui.json

@@ -55,11 +55,20 @@
       "alert"
     ],
     "slots": {
+      "description": {
+        "description": "Secondary metadata — grid row 2 beneath the heading, spanning the heading and action columns. Also accepts bare <p> / <small> / body-variant <text-ui> as direct children without slot=\"description\". Renders muted + small."
+      },
       "default": {
-        "description": "Default slot — primary child content."
+        "description": "Default slot — primary child content. When no named slot= attributes are used, all children flow here as a block. Most card/drawer/modal usages prefer the named vocabulary below so the parent's @scope grid activates."
       },
       "action": {
-        "description": "Action region — buttons or badges on the right."
+        "description": "Trailing control cluster — placed in the last column of the parent container's header grid. Use for icon-buttons, menu triggers, or badge/button combinations. The first [slot=\"action\"] child pushes itself to the grid's end; subsequent siblings flow with gap."
+      },
+      "heading": {
+        "description": "Primary title — grid row 1 of the header grid. Also accepts bare <h1>–<h6> tags as direct children without slot=\"heading\". Renders at title weight + size per the parent's @scope. A slot=\"heading\" wrapper element can contain inline badges or metadata alongside the title text."
+      },
+      "icon": {
+        "description": "Leading icon column — placed in column 1 of the parent container's header grid (card-ui / drawer-ui / modal-ui / page-ui). Use <icon-ui name=\"...\">, <avatar-ui>, or any inline icon element. The grid activates only when this slot is present; without it the heading spans the full width."
       }
     },
     "states": [

package/components/header/header.yaml

@@ -17,9 +17,37 @@ props:
 events: {}
 slots:
   default:
-    description: "Default slot — primary child content."
+    description: >-
+      Default slot — primary child content. When no named slot= attributes
+      are used, all children flow here as a block. Most card/drawer/modal
+      usages prefer the named vocabulary below so the parent's @scope grid
+      activates.
+  icon:
+    description: >-
+      Leading icon column — placed in column 1 of the parent container's
+      header grid (card-ui / drawer-ui / modal-ui / page-ui). Use
+      <icon-ui name="...">, <avatar-ui>, or any inline icon element.
+      The grid activates only when this slot is present; without it the
+      heading spans the full width.
+  heading:
+    description: >-
+      Primary title — grid row 1 of the header grid. Also accepts bare
+      <h1>–<h6> tags as direct children without slot="heading". Renders
+      at title weight + size per the parent's @scope. A slot="heading"
+      wrapper element can contain inline badges or metadata alongside
+      the title text.
+  description:
+    description: >-
+      Secondary metadata — grid row 2 beneath the heading, spanning the
+      heading and action columns. Also accepts bare <p> / <small> /
+      body-variant <text-ui> as direct children without slot="description".
+      Renders muted + small.
   action:
-    description: "Action region — buttons or badges on the right."
+    description: >-
+      Trailing control cluster — placed in the last column of the parent
+      container's header grid. Use for icon-buttons, menu triggers, or
+      badge/button combinations. The first [slot="action"] child pushes
+      itself to the grid's end; subsequent siblings flow with gap.
 states:
   - name: idle
     description: Default, ready for interaction.