@adia-ai/web-components 0.6.37 → 0.6.39

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.39] — 2026-05-26
+
+### Added — `<tour-ui>` spotlight-driven product tour primitive (Wave 5e last P1, #259)
+
+- **`<tour-ui>`** — spotlight-driven product tour primitive. Closes the last Wave 5e P1. Component count 177 → 179 (+2 with tour + tour-step sub-primitive).
+
+### Fixed — substrate defensive slot-selector sweep + admin-entity-item icon size
+
+- **Substrate sweep**: slot selectors changed from direct-child to descendant across remaining primitives. Defensive companion to the v0.6.38 `<list-item-ui>` fix — same drift class in adjacent components.
+- **`<admin-entity-item>`**: icon size now matches `<nav-item-ui>`'s row icon (24px) instead of hardcoded 16px. Brings the canonical brand-chrome pattern into visual parity with the nav-item it sits next to.
+- **`<list-item-ui>`**: now declares `slot="action"` — closes P2 from the v0.6.38 `dogfood:status` gate.
+
+## [0.6.38] — 2026-05-26
+
+### Added — Wave 5e cohort: 3 new primitives + slot-vocab-vs-css backlog closed
+
+- **`<mark-ui>`** — inline highlighted text primitive (#357)
+- **`<inline-edit-ui>`** — click-to-edit text in place (#212)
+- **Notification deep-link demo + Mark All Read verify** for `<feed-ui>` (#344/#343)
+
+### Fixed — substrate polish across the v0.6.38 window
+
+- **`<list-item-ui>`**: slot selectors changed from direct-child to descendant — description row now lands on row 2 as intended
+- **`<segmented-ui>`**: stale indicator stripping — duplicate pills on re-render eliminated
+- **`<stat-ui>`**: chart slot bottom-aligns to value baseline; aspect 4:3
+- **`<toolbar-ui>`** mixed-controls demo: `<segment-ui>` (not `<button-ui>`) inside `<segmented-ui>`
+
+### Maintenance — slot-vocab-vs-css audit reached 0 critical findings
+
+- `audit-slot-vocab-vs-css` substrate backlog closed → gate now enforced. Multi-yaml + @scope-aware pairing landed in the audit script.
+- 5 Wave 5a/b/c/d gap-analysis flips landed (substrate-verified as covered; no new code).
+
 ## [0.6.37] — 2026-05-25
 
 ### Changed — `--a-warning-bg` redirected from `-strong` to `-20-tint` (bright caution-tape amber, scheme-independent)

package/components/accordion/accordion-item.a2ui.json

@@ -63,6 +63,9 @@
       "action": {
         "description": "§206 (v0.5.7): action buttons inside a custom header (e.g. Copy /\nDownload / settings). Children placed at `[slot=\"action\"]` (or\n`[slot=\"actions\"]`, or marked `[data-no-toggle]`) are excluded from\nthe toggle-on-click cascade — clicking them fires their own handler\nwithout also toggling the section."
       },
+      "body": {
+        "description": "The section's collapsible content. Renders below the header; hidden when `[open]` is unset. Author-fills with prose, lists, embedded forms, or any rich markup the panel needs."
+      },
       "header": {
         "description": "Custom header content. By default `[text]` renders as a plain header\nlabel, but a `[slot=\"header\"]` override lets consumers author rich\nheaders (icon + title + action buttons + caret)."
       }

package/components/accordion/accordion-item.yaml

@@ -39,6 +39,11 @@ slots:
       `[slot="actions"]`, or marked `[data-no-toggle]`) are excluded from
       the toggle-on-click cascade — clicking them fires their own handler
       without also toggling the section.
+  body:
+    description: >-
+      The section's collapsible content. Renders below the header; hidden
+      when `[open]` is unset. Author-fills with prose, lists, embedded
+      forms, or any rich markup the panel needs.
 events:
   toggle:
     description: Fired when the section opens or closes.

package/components/action-list/action-item.a2ui.json

@@ -62,7 +62,11 @@
       "MenuItem",
       "Button"
     ],
-    "slots": {},
+    "slots": {
+      "icon": {
+        "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
+      }
+    },
     "states": [],
     "status": "stable",
     "synonyms": {

package/components/action-list/action-item.yaml

@@ -37,6 +37,13 @@ props:
     type: boolean
     default: false
 
+slots:
+  icon:
+    description: >-
+      Override the [icon] glyph with a custom slotted element (custom
+      icon-ui, image, avatar). Mutually exclusive with the [icon]
+      attribute — slot child wins.
+
 keywords:
   - action-item
   - command-row

package/components/card/card.a2ui.json

@@ -113,7 +113,23 @@
       "alert",
       "skeleton"
     ],
-    "slots": {},
+    "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)."
+      },
+      "action": {
+        "description": "Trailing action cluster in the header (e.g. icon-buttons, menu trigger, more-options). Aligns to the header's flex-end edge."
+      },
+      "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."
+      },
+      "heading": {
+        "description": "Card title. Renders in the header slot with title typography. Typically a short noun phrase or document/object name."
+      },
+      "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."
+      }
+    },
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/card/card.yaml

@@ -58,7 +58,30 @@ props:
     - soft
     - primary
 events: {}
-slots: {}
+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.
+  heading:
+    description: >-
+      Card title. Renders in the header slot with title typography.
+      Typically a short noun phrase or document/object name.
+  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).
+  action:
+    description: >-
+      Trailing action cluster in the header (e.g. icon-buttons, menu
+      trigger, more-options). Aligns to the header's flex-end edge.
+  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.
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/date-range-picker/date-range-picker.css

@@ -81,7 +81,7 @@
      stamped by date-range-picker.class.js — these rules override button-ui's defaults at
      equal specificity so the picker trigger reads as part of the
      input/picker family rather than a generic button. */
-  :scope > [slot="trigger"] {
+  :scope [slot="trigger"] {
     min-width: var(--date-range-picker-trigger-min-width, var(--date-range-picker-trigger-min-width-default));
     min-height: var(--date-range-picker-trigger-height, var(--date-range-picker-trigger-height-default));
     padding: 0 var(--date-range-picker-trigger-px, var(--date-range-picker-trigger-px-default));
@@ -101,12 +101,12 @@
       border-color var(--date-range-picker-duration, var(--date-range-picker-duration-default)) var(--date-range-picker-easing, var(--date-range-picker-easing-default)),
       background   var(--date-range-picker-duration, var(--date-range-picker-duration-default)) var(--date-range-picker-easing, var(--date-range-picker-easing-default));
   }
-  :scope > [slot="trigger"]:hover {
+  :scope [slot="trigger"]:hover {
     border-color: var(--date-range-picker-trigger-border-hover, var(--date-range-picker-trigger-border-hover-default));
     background: var(--date-range-picker-trigger-bg-hover, var(--date-range-picker-trigger-bg-hover-default));
   }
   :scope:focus-visible { outline: none; }
-  :scope:focus-visible > [slot="trigger"] {
+  :scope:focus-visible [slot="trigger"] {
     box-shadow: var(--date-range-picker-trigger-focus-ring, var(--date-range-picker-trigger-focus-ring-default));
   }
 
@@ -115,7 +115,7 @@
     opacity: 0.5;
     pointer-events: none;
   }
-  :scope[readonly] > [slot="trigger"] {
+  :scope[readonly] [slot="trigger"] {
     cursor: default;
   }
 }

package/components/datetime-picker/datetime-picker.css

@@ -55,7 +55,7 @@
 
   /* Default trigger sizing — composes button-ui's surface; just
      stretches the min-width so "Jan 1, 2026 14:30" fits. */
-  :scope > [slot="trigger"] {
+  :scope [slot="trigger"] {
     min-width: var(--datetime-picker-trigger-min-width, var(--datetime-picker-trigger-min-width-default));
   }
 
@@ -64,7 +64,7 @@
     opacity: 0.5;
     pointer-events: none;
   }
-  :scope[readonly] > [slot="trigger"] {
+  :scope[readonly] [slot="trigger"] {
     cursor: default;
   }
 }
@@ -131,7 +131,7 @@ datetime-picker-ui [slot="popover"] > [data-time-pane] {
 
 /* Footer area (consumer-supplied [slot="footer"]) — spans all three
    columns under the panes. */
-datetime-picker-ui [slot="popover"] > [slot="footer"] {
+datetime-picker-ui [slot="popover"] [slot="footer"] {
   grid-column: 1 / -1;
   display: flex;
   justify-content: flex-end;

package/components/demo-toggle/demo-toggle.css

@@ -57,15 +57,15 @@
   /* -- Stage area (where the slotted content lives) -- */
   /* Slotted children are anything that isn't the [slot="bar"]. They sit in
      the second flex row; default mode shows only the active slot. */
-  :scope > [slot="on"],
-  :scope > [slot="off"] {
+  :scope [slot="on"],
+  :scope [slot="off"] {
     box-sizing: border-box;
     width: 100%;
     padding: var(--demo-toggle-stage-padding, var(--demo-toggle-stage-padding-default));
   }
 
-  :scope[data-state="on"]  > [slot="off"] { display: none; }
-  :scope[data-state="off"] > [slot="on"]  { display: none; }
+  :scope[data-state="on"]  [slot="off"] { display: none; }
+  :scope[data-state="off"] [slot="on"]  { display: none; }
 
   /* Overlay mode — both slots stack on the same coordinates so toggling
      never reflows the surrounding layout. The inactive slot is
@@ -76,8 +76,8 @@
     /* The bar is row 1; the stage cell is row 2. The cell's children all
        claim the same grid-area so they overlap. */
   }
-  :scope[data-mode="overlay"] > [slot="on"],
-  :scope[data-mode="overlay"] > [slot="off"] {
+  :scope[data-mode="overlay"] [slot="on"],
+  :scope[data-mode="overlay"] [slot="off"] {
     display: block;
   }
   :scope[data-mode="overlay"] {
@@ -86,7 +86,7 @@
        via the second slot's positioning. */
     position: relative;
   }
-  :scope[data-mode="overlay"] > [slot="on"] {
+  :scope[data-mode="overlay"] [slot="on"] {
     position: absolute;
     inset: 0;
     /* Bar height — the slot starts beneath the bar. We can't query the
@@ -98,17 +98,17 @@
     top: auto;
     height: auto;
   }
-  :scope[data-mode="overlay"][data-state="on"]  > [slot="off"] {
+  :scope[data-mode="overlay"][data-state="on"]  [slot="off"] {
     visibility: hidden;
   }
-  :scope[data-mode="overlay"][data-state="off"] > [slot="on"]  {
+  :scope[data-mode="overlay"][data-state="off"] [slot="on"]  {
     visibility: hidden;
   }
   /* Reset display:none branches above for overlay — already handled by
      visibility:hidden, but the default-mode display:none rules above
      would otherwise fight overlay. Override here. */
-  :scope[data-mode="overlay"][data-state="on"]  > [slot="off"],
-  :scope[data-mode="overlay"][data-state="off"] > [slot="on"] {
+  :scope[data-mode="overlay"][data-state="on"]  [slot="off"],
+  :scope[data-mode="overlay"][data-state="off"] [slot="on"] {
     display: block;
   }
 

package/components/empty-state/empty-state.a2ui.json

@@ -85,8 +85,17 @@
       "select"
     ],
     "slots": {
+      "description": {
+        "description": "Override slot for the description text. Use for multi-paragraph or richly-marked-up explanatory copy."
+      },
       "action": {
         "description": "User-provided action element (e.g. button) displayed below the description"
+      },
+      "heading": {
+        "description": "Override slot for the heading text. Use when richer markup than the plain [heading] attribute is needed (line breaks, inline links, bold emphasis)."
+      },
+      "icon": {
+        "description": "Override slot for the [icon] glyph. Use when the attribute-driven Phosphor icon isn't enough (e.g., custom SVG, illustration, or a styled icon-ui with non-default weight). Mutually exclusive with [icon]."
       }
     },
     "states": [

package/components/empty-state/empty-state.yaml

@@ -53,6 +53,21 @@ props:
     reflect: true
 events: {}
 slots:
+  icon:
+    description: >-
+      Override slot for the [icon] glyph. Use when the attribute-driven
+      Phosphor icon isn't enough (e.g., custom SVG, illustration, or
+      a styled icon-ui with non-default weight). Mutually exclusive
+      with [icon].
+  heading:
+    description: >-
+      Override slot for the heading text. Use when richer markup than
+      the plain [heading] attribute is needed (line breaks, inline
+      links, bold emphasis).
+  description:
+    description: >-
+      Override slot for the description text. Use for multi-paragraph
+      or richly-marked-up explanatory copy.
   action:
     description: User-provided action element (e.g. button) displayed below the description
 states:

package/components/feed/feed-item.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "action": {
+      "description": "Label of an inline action button (the \"deep-link\" / \"undo\" pattern).\nPair with `onAction` callback in `UIFeed.post()` — click invokes the\ncallback then auto-dismisses. Empty string renders no action button.\n",
+      "type": "string",
+      "default": ""
+    },
     "component": {
       "const": "FeedItem"
     },

package/components/feed/feed-item.yaml

@@ -42,6 +42,14 @@ props:
     description: Render an x close button (default true for sticky, false for auto-fade)
     type: boolean
     default: false
+  action:
+    description: |
+      Label of an inline action button (the "deep-link" / "undo" pattern).
+      Pair with `onAction` callback in `UIFeed.post()` — click invokes the
+      callback then auto-dismisses. Empty string renders no action button.
+    type: string
+    default: ""
+    reflect: true
 events:
   close:
     description: Fired after the item finishes its exit animation
@@ -74,3 +82,5 @@ a2ui:
       reason: 'Imperative ownership.'
     - rule: 'Different from <alert-ui> (inline persistent) and <toast-ui> (standalone ephemeral); feed-item is feed-scoped.'
       reason: 'Surface boundary.'
+    - rule: 'For "notification deep-link" pattern: post with action + onAction. Click navigates and auto-dismisses (router.push() / location.href / api.markRead()).'
+      reason: 'Deep-link pattern lives in the onAction callback, not in markup.'

package/components/feed/feed.css

@@ -144,14 +144,14 @@ feed-item-ui[data-closing] {
     transform: translateY(0.5rem);
     pointer-events: auto;
   }
-  :scope > [slot="body"] {
+  :scope [slot="body"] {
     flex: 1;
     min-width: 0;
     display: flex;
     flex-direction: column;
     gap: 0.125rem;
   }
-  :scope > [slot="body"] strong {
+  :scope [slot="body"] strong {
     font-weight: var(--a-weight-semibold);
   }
   :scope > [data-feed-close] {

package/components/field/field.a2ui.json

@@ -103,6 +103,12 @@
       "action": {
         "description": "Button adjacent to the control for inline actions (clear, reset, help popover)."
       },
+      "error": {
+        "description": "Override slot for error markup richer than the plain [error] attribute string. Rendered below the control with danger-text styling. Mutually exclusive with [error]."
+      },
+      "hint": {
+        "description": "Override slot for hint markup richer than the plain [hint] attribute string (inline links, code spans, abbreviations). Rendered below the control at body-subtle typography. Mutually exclusive with [hint]."
+      },
       "trailing": {
         "description": "Secondary text or badge aligned with the label in the stacked layout (right-aligned) or between label and control in the inline layout."
       }

package/components/field/field.css

@@ -42,7 +42,7 @@
      (~7-8 px) than non-field-ui siblings in a `<row-ui align="center">`.
      FB-54 (v0.6.32) — closes the trap for compact filter bars that
      mix field-ui with bare primitives. */
-  :scope:has(> [slot="hint"], > [slot="error"]) {
+  :scope:has([slot="hint"], [slot="error"]) {
     row-gap: var(--field-gap, var(--field-gap-default));
   }
 
@@ -56,12 +56,12 @@
   }
 
   /* Stacked + no label, no trailing → drop the empty top row. */
-  :scope:not([label]):not(:has(> [slot="trailing"])) {
+  :scope:not([label]):not(:has([slot="trailing"])) {
     grid-template-areas:
       "control"
       "message";
   }
-  :scope:not([label]):not(:has(> [slot="trailing"])):has(> [slot="action"]) {
+  :scope:not([label]):not(:has([slot="trailing"])):has([slot="action"]) {
     grid-template-columns: minmax(0, 1fr) auto;
     grid-template-areas:
       "control action"
@@ -69,10 +69,10 @@
   }
 
   /* Hide the label cell when the label attr is absent. */
-  :scope:not([label]) > [slot="label"] { display: none; }
+  :scope:not([label]) [slot="label"] { display: none; }
 
   /* ── Slot styling ── */
-  :scope > [slot="label"] {
+  :scope [slot="label"] {
     grid-area: label;
     color: var(--field-label-color, var(--field-label-color-default));
     font-size: var(--field-label-size, var(--field-label-size-default));
@@ -80,12 +80,12 @@
     cursor: pointer;
     min-width: 0;
   }
-  :scope > [slot="label"] > [data-field-required] {
+  :scope [slot="label"] > [data-field-required] {
     color: var(--field-required-color, var(--field-required-color-default));
     margin-inline-start: 0.15em;
     font-weight: var(--a-weight-bold);
   }
-  :scope > [slot="trailing"] {
+  :scope [slot="trailing"] {
     grid-area: trailing;
     justify-self: end;
     color: var(--field-trailing-color, var(--field-trailing-color-default));
@@ -95,20 +95,20 @@
     grid-area: control;
     min-width: 0;
   }
-  :scope > [slot="action"] {
+  :scope [slot="action"] {
     grid-area: action;
     justify-self: end;
   }
-  :scope > [slot="hint"],
-  :scope > [slot="error"] {
+  :scope [slot="hint"],
+  :scope [slot="error"] {
     grid-area: message;
     line-height: 1.3;
   }
-  :scope > [slot="hint"] {
+  :scope [slot="hint"] {
     color: var(--field-hint-color, var(--field-hint-color-default));
     font-size: var(--field-hint-size, var(--field-hint-size-default));
   }
-  :scope > [slot="error"] {
+  :scope [slot="error"] {
     color: var(--field-error-color, var(--field-error-color-default));
     font-size: var(--field-error-size, var(--field-error-size-default));
     font-weight: var(--a-weight-medium);
@@ -125,31 +125,31 @@
       "label   control"
       ".       message";
   }
-  :scope[inline]:has(> [slot="trailing"]):not(:has(> [slot="action"])) {
+  :scope[inline]:has([slot="trailing"]):not(:has([slot="action"])) {
     grid-template-columns: minmax(var(--field-label-inline-min, var(--field-label-inline-min-default)), auto) auto minmax(0, 1fr);
     grid-template-areas:
       "label   trailing control"
       ".       .        message";
   }
-  :scope[inline]:not(:has(> [slot="trailing"])):has(> [slot="action"]) {
+  :scope[inline]:not(:has([slot="trailing"])):has([slot="action"]) {
     grid-template-columns: minmax(var(--field-label-inline-min, var(--field-label-inline-min-default)), auto) minmax(0, 1fr) auto;
     grid-template-areas:
       "label   control action"
       ".       message message";
   }
-  :scope[inline]:has(> [slot="trailing"]):has(> [slot="action"]) {
+  :scope[inline]:has([slot="trailing"]):has([slot="action"]) {
     grid-template-columns: minmax(var(--field-label-inline-min, var(--field-label-inline-min-default)), auto) auto minmax(0, 1fr) auto;
     grid-template-areas:
       "label   trailing control action"
       ".       .        message message";
   }
-  :scope[inline]:not([label]):not(:has(> [slot="trailing"])):not(:has(> [slot="action"])) {
+  :scope[inline]:not([label]):not(:has([slot="trailing"])):not(:has([slot="action"])) {
     grid-template-columns: minmax(0, 1fr);
     grid-template-areas:
       "control"
       "message";
   }
-  :scope[inline]:not([label]):not(:has(> [slot="trailing"])):has(> [slot="action"]) {
+  :scope[inline]:not([label]):not(:has([slot="trailing"])):has([slot="action"]) {
     grid-template-columns: minmax(0, 1fr) auto;
     grid-template-areas:
       "control action"
@@ -172,7 +172,7 @@
   /* align="end": label text is right-aligned within the label cell.   */
   /* Useful in multi-field forms where labels share a visual column     */
   /* and trailing-flush alignment aids scanability (right-to-input).   */
-  :scope[align="end"] > [slot="label"] {
+  :scope[align="end"] [slot="label"] {
     justify-self: end;
     text-align: end;
   }

package/components/field/field.yaml

@@ -89,6 +89,16 @@ slots:
     description: >-
       Button adjacent to the control for inline actions (clear,
       reset, help popover).
+  hint:
+    description: >-
+      Override slot for hint markup richer than the plain [hint] attribute
+      string (inline links, code spans, abbreviations). Rendered below
+      the control at body-subtle typography. Mutually exclusive with [hint].
+  error:
+    description: >-
+      Override slot for error markup richer than the plain [error] attribute
+      string. Rendered below the control with danger-text styling. Mutually
+      exclusive with [error].
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/heatmap/heatmap.css

@@ -39,7 +39,7 @@
   }
 
   /* Title slot */
-  :scope > [slot="title"] {
+  :scope [slot="title"] {
     font-weight: 600;
     margin: 0;
   }

package/components/index.js

@@ -93,6 +93,9 @@ export { UIMenu, UIMenuItem, UIMenuDivider } from './menu/menu.js';
 export { UIContextMenu } from './context-menu/context-menu.js';
 export { UIVisuallyHidden } from './visually-hidden/visually-hidden.js';
 export { UISkipNav } from './skip-nav/skip-nav.js';
+export { UIMark } from './mark/mark.js';
+export { UIInlineEdit } from './inline-edit/inline-edit.js';
+export { UITour, UITourStep } from './tour/tour.js';
 export { UIToolbar, UIToolbarGroup } from './toolbar/toolbar.js';
 export { UINav } from './nav/nav.js';
 export { UINavGroup } from './nav-group/nav-group.js';