@adia-ai/web-components 0.6.8 → 0.6.9

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.9] — 2026-05-21
+
+### Fixed
+- **9 component CSS files — `@scope` blocks no longer use bare-combinator descendants (F-002, P1).** Pre-fix: 92 selector clauses across `action-list.css`, `card.css`, `chart.css`, `chat-thread.css`, `code.css`, `command.css`, `grid.css`, `pane.css`, `stack.css` used the `@scope { > X { } }` shape (bare `>` combinator with no left-hand selector inside `@scope`). Chromium/Firefox tolerate this; LightningCSS rejects it as "Invalid empty selector" (matches the CSS Nesting + `@scope` spec strictly). Symptom: consumers on Vite 7 (default `cssMinify: 'lightningcss'`) saw build-time failures at `card.css:152`; Vite 6 + earlier Vite 7 (esbuild minify) silently swallowed the same source. Fix: codemod-driven rewrite of all 92 clauses from `> X` to `& > X` (explicit `&` reference matches the modern CSS Nesting idiom; semantically identical; LightningCSS-clean). All 120 CSS files now pass LightningCSS minify against Vite 8 default targets (Chromium 125+, Safari 18+, Firefox 129+). Codemod source: `scripts/build/codemod-scope-bare-descendants.mjs` (committed for future audits; idempotent + `--verify` mode). Paired CI gate `check:scope-bare-descendants` blocks regression at PR time; companion `check:lightningcss-build` smoke-minifies every CSS file end-to-end against Vite 8 targets. Closes claims-ui FEEDBACK-02.
+
+### Documentation
+- **`USAGE.md` — new "Looking up a component's API" subsection.** Three discovery paths now documented in one place: `npx adia-ai-doc <component>` CLI (machine-readable + offline-safe), `<component>.examples.html` per-component live demo + Properties table, and `<component>.yaml` source-of-truth schema. Closes claims-ui FEEDBACK-09 (per-component opt-out attributes are documented; this subsection makes the doc-path discoverable from the top-level USAGE entrypoint).
+
 ## [0.6.8] — 2026-05-20
 
 ### Fixed

package/USAGE.md

@@ -59,6 +59,35 @@ import { signal, computed, effect, html, UIElement, UIFormElement } from '@adia-
 import '@adia-ai/web-components/traits';
 ```
 
+### Looking up a component's API
+
+Three reliable surfaces, in order of immediacy:
+
+```bash
+# 1. CLI (since v0.6.7) — prints yaml summary + live demo URL + first example
+npx adia-ui-doc table-toolbar     # full prop / slot / event surface
+npx adia-ui-doc                   # bare invocation lists all 96 components
+```
+
+```bash
+# 2. Per-component examples (ship in npm tarball since v0.6.7)
+cat node_modules/@adia-ai/web-components/components/table-toolbar/table-toolbar.examples.md
+
+# Or the richer .examples.html for Properties tables + multi-section walks
+open node_modules/@adia-ai/web-components/components/table-toolbar/table-toolbar.examples.html
+```
+
+```bash
+# 3. The component's yaml (authoritative — all props, defaults, descriptions)
+cat node_modules/@adia-ai/web-components/components/table-toolbar/table-toolbar.yaml
+```
+
+The yaml is the source of truth for every property, slot, event, and token.
+The CLI reads it. The `.d.ts` files are generated from it. When this USAGE
+guide and the yaml disagree, the yaml wins — file a doc-bug FEEDBACK.
+
+For the live demo of every component: <https://ui-kit.exe.xyz/site/components/>.
+
 ---
 
 ## The mental model

package/components/action-list/action-list.css

@@ -99,7 +99,7 @@ action-item-ui:hover [slot="icon"] {
   }
 
   /* Default slot (trailing content: kbd, badge, chevron) pushed to far right */
-  > :not([slot="icon"]):not([slot="text"]) {
+  & > :not([slot="icon"]):not([slot="text"]) {
     flex-shrink: 0;
     margin-inline-start: auto;
     color: var(--action-item-icon-fg);

package/components/card/card.css

@@ -149,7 +149,7 @@
      [padding] switches to padding mode with background.
      Grid layout: optional icon | heading+description | optional action */
 
-  > header {
+  & > header {
     display: block;
     margin: var(--card-inset);
   }
@@ -157,24 +157,24 @@
   /* Activate grid layout only when a DIRECT slotted child is present.
      Constraining to `:has(> [slot])` prevents deeply nested slots (e.g. an
      [slot="icon"] inside an <avatar-ui>) from falsely activating the grid. */
-  > header:has(> [slot]) {
+  & > header:has(> [slot]) {
     display: grid;
     gap: var(--card-header-gap);
     align-items: center;
   }
 
-  > header[padding] {
+  & > header[padding] {
     margin: 0;
     padding: var(--card-inset);
     background: var(--card-bg-padded);
   }
 
-  > header[divider] {
+  & > header[divider] {
     padding-bottom: var(--card-inset);
     border-bottom: 1px solid var(--card-divider);
   }
 
-  > header[center] {
+  & > header[center] {
     text-align: center;
     justify-items: center;
   }
@@ -182,16 +182,16 @@
   /* Column templates — match gen-ui-kit pattern. Direct-child `:has(> …)` so
      nested [slot="icon"] inside a composite (e.g. <avatar-ui>) can't trigger
      the icon column by accident. */
-  > header:has(> [slot="icon"]):has(> [slot="action"])         { grid-template-columns: max-content 1fr max-content; }
-  > header:has(> [slot="icon"]):not(:has(> [slot="action"]))   { grid-template-columns: max-content 1fr; }
-  > header:not(:has(> [slot="icon"])):has(> [slot="action"])   { grid-template-columns: 1fr max-content; }
-  > header:not(:has(> [slot="icon"])):not(:has(> [slot="action"])) { grid-template-columns: 1fr; }
+  & > header:has(> [slot="icon"]):has(> [slot="action"])         { grid-template-columns: max-content 1fr max-content; }
+  & > header:has(> [slot="icon"]):not(:has(> [slot="action"]))   { grid-template-columns: max-content 1fr; }
+  & > header:not(:has(> [slot="icon"])):has(> [slot="action"])   { grid-template-columns: 1fr max-content; }
+  & > header:not(:has(> [slot="icon"])):not(:has(> [slot="action"])) { grid-template-columns: 1fr; }
 
   /* Unslotted children (zettel fragment injection, etc.) — each on its own row,
      spanning the full width, stacked ABOVE the heading/description/action grid.
      This lets compositions inject logos, banners, etc. into a header without
      having to know the slot vocabulary. */
-  > header > *:not([slot]):not(h1):not(h2):not(h3):not(h4):not(h5):not(h6):not(p):not(small) {
+  & > header > *:not([slot]):not(h1):not(h2):not(h3):not(h4):not(h5):not(h6):not(p):not(small) {
     grid-column: 1 / -1;
     justify-self: center;
   }
@@ -200,7 +200,7 @@
      Default: single row, center-aligned with heading/action.
      When a description row exists, spans both rows and anchors to the
      start so the icon visually aligns with the heading. */
-  > header > [slot="icon"] {
+  & > header > [slot="icon"] {
     grid-column: 1;
     grid-row: 1;
     align-self: center;
@@ -209,39 +209,39 @@
     justify-content: center;
   }
 
-  > header:has(> :is([slot="description"], p, small)) > [slot="icon"] {
+  & > header:has(> :is([slot="description"], p, small)) > [slot="icon"] {
     grid-row: 1 / span 2;
     align-self: start;
   }
 
   /* Heading — row 1 */
-  > header > :is([slot="heading"], h1, h2, h3, h4, h5, h6),
-  > header > [slot="heading"] :is(h1, h2, h3, h4, h5, h6) {
+  & > header > :is([slot="heading"], h1, h2, h3, h4, h5, h6),
+  & > header > [slot="heading"] :is(h1, h2, h3, h4, h5, h6) {
     grid-row: 1;
     line-height: 1.3;
     margin: 0;
   }
   /* Heading slot is a flex container — can hold title + inline badges/metadata */
-  > header > [slot="heading"] {
+  & > header > [slot="heading"] {
     display: flex;
     align-items: center;
     gap: var(--card-header-gap);
   }
-  > header:has(> [slot="icon"]) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 2; }
-  > header:not(:has(> [slot="icon"])) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 1; }
+  & > header:has(> [slot="icon"]) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 2; }
+  & > header:not(:has(> [slot="icon"])) > :is([slot="heading"], h1, h2, h3, h4, h5, h6) { grid-column: 1; }
 
   /* Description — row 2 */
-  > header > :is([slot="description"], p, small) {
+  & > header > :is([slot="description"], p, small) {
     grid-row: 2;
     grid-column: 1 / -1;
     line-height: 1.4;
     margin: 0;
   }
-  > header:has(> [slot="icon"]) > :is([slot="description"], p, small) { grid-column: 2 / -1; }
+  & > header:has(> [slot="icon"]) > :is([slot="description"], p, small) { grid-column: 2 / -1; }
 
   /* Action — row 1, last column.
      Flex container so it can hold badge + button + anything inline. */
-  > header [slot="action"] {
+  & > header [slot="action"] {
     justify-self: end;
     align-self: center;
     grid-row: 1;
@@ -256,17 +256,17 @@
      [padding] switches to padding with background.
      [bleed] removes all spacing for edge-to-edge content. */
 
-  > section {
+  & > section {
     margin: var(--card-inset);
   }
 
-  > section[padding] {
+  & > section[padding] {
     margin: 0;
     padding: var(--card-inset);
     background: var(--card-bg-padded);
   }
 
-  > section[bleed] {
+  & > section[bleed] {
     margin: 0;
     padding: 0;
   }
@@ -276,7 +276,7 @@
      [divider] adds top border.
      [padding] switches to padded mode. */
 
-  > footer {
+  & > footer {
     display: block;
     margin: var(--card-inset);
   }
@@ -284,8 +284,8 @@
   /* Activate flex layout when a direct slotted child or multiple children are
      present. `:has(> [slot])` so nested [slot="…"] inside composites can't
      trigger the flex row. */
-  > footer:has(> [slot]),
-  > footer:has(> :nth-child(2)) {
+  & > footer:has(> [slot]),
+  & > footer:has(> :nth-child(2)) {
     display: flex;
     flex-wrap: wrap;
     align-items: center;
@@ -293,30 +293,30 @@
   }
 
   /* col-ui in footer takes full width (common for stacked footer: button + divider + social) */
-  > footer > col-ui { width: 100%; }
+  & > footer > col-ui { width: 100%; }
 
-  > footer[justify="end"] {
+  & > footer[justify="end"] {
     justify-content: flex-end;
   }
 
-  > footer[divider] {
+  & > footer[divider] {
     margin-top: var(--card-inset);
     padding-top: var(--card-inset);
     border-top: 1px solid var(--card-divider);
   }
 
-  > footer[padding] {
+  & > footer[padding] {
     margin: 0;
     padding: var(--card-inset);
     background: var(--card-bg-padded);
   }
 
   /* Footer with direct-child description + action = space-between */
-  > footer:has(> :is([slot="description"], p, small)):has(> [slot="action"]) {
+  & > footer:has(> :is([slot="description"], p, small)):has(> [slot="action"]) {
     justify-content: space-between;
   }
 
-  > footer :is([slot="description"], p, small) {
+  & > footer :is([slot="description"], p, small) {
     font-size: var(--card-description-size);
     color: var(--card-description-fg);
     flex: 1;
@@ -327,7 +327,7 @@
   /* Footer heading — trend-stat line (symmetric with header's [slot="heading"]).
      Used for chart trend-footer patterns like "Trending up by 5.2% this month".
      Paired with [slot="description"] for a "Jan – Mar 2024" period caption. */
-  > footer > [slot="heading"] {
+  & > footer > [slot="heading"] {
     font-size: var(--card-font-size);
     font-weight: var(--a-weight-medium);
     color: var(--card-heading-fg);
@@ -339,21 +339,21 @@
   /* Footer with heading + description = column stack, heading on top. The
      existing flex-row layout becomes a flex-column when a heading is present,
      so the trend line and period caption stack naturally. */
-  > footer:has(> [slot="heading"]) {
+  & > footer:has(> [slot="heading"]) {
     flex-direction: column;
     align-items: flex-start;
     gap: var(--a-space-0-5);
   }
 
-  > footer:has(> [slot="heading"])[justify="end"] {
+  & > footer:has(> [slot="heading"])[justify="end"] {
     align-items: flex-end;
   }
 
-  > footer:has(> [slot="heading"])[justify="center"] {
+  & > footer:has(> [slot="heading"])[justify="center"] {
     align-items: center;
   }
 
-  > footer [slot="action"] {
+  & > footer [slot="action"] {
     margin-inline-start: auto;
     display: flex;
     gap: var(--card-footer-gap);
@@ -361,14 +361,14 @@
 
   /* Multiple direct action-slotted children (A2UI pattern):
      only the first pushes the group right; subsequent ones flow with gap */
-  > footer > [slot="action"] ~ [slot="action"] {
+  & > footer > [slot="action"] ~ [slot="action"] {
     margin-inline-start: 0;
   }
 
   /* Dual-cluster footer: leading action (e.g. Delete) on the inline-start
      edge, trailing action cluster on the inline-end. margin-inline-end:
      auto fills the gap between the two groups. */
-  > footer > [slot="action-leading"] {
+  & > footer > [slot="action-leading"] {
     margin-inline-end: auto;
     display: flex;
     gap: var(--card-footer-gap);
@@ -376,15 +376,15 @@
 
   /* ═══════ Images ═══════ */
 
-  > img,
-  > [slot="media"] {
+  & > img,
+  & > [slot="media"] {
     display: block;
     width: 100%;
     object-fit: cover;
   }
 
-  > img:first-child,
-  > [slot="media"]:first-child {
+  & > img:first-child,
+  & > [slot="media"]:first-child {
     border-radius: var(--card-radius) var(--card-radius) 0 0;
   }
 

package/components/chart/chart.css

@@ -112,7 +112,7 @@
   /* Empty-state slot — author places <empty-state-ui slot="empty"> inside
      chart-ui. CSS toggles visibility on [data-has-data] (set by chart.js
      when .data is non-empty). No data ⇒ empty-state visible; data ⇒ hidden. */
-  > [slot="empty"] { display: none; }
+  & > [slot="empty"] { display: none; }
   :scope:not([data-has-data]) > [slot="empty"] {
     display: flex;
     flex: 1 1 auto;

package/components/chat-thread/chat-thread.css

@@ -65,7 +65,7 @@
   }
 
   /* -- Header -- */
-  > header {
+  & > header {
     display: flex;
     align-items: center;
     gap: var(--chat-gap);
@@ -73,7 +73,7 @@
     border-bottom: 1px solid var(--chat-border-color);
   }
 
-  > header [slot="avatar"] {
+  & > header [slot="avatar"] {
     width: var(--chat-header-avatar-size);
     height: var(--chat-header-avatar-size);
     border-radius: var(--chat-header-avatar-radius);
@@ -87,19 +87,19 @@
     flex-shrink: 0;
   }
 
-  > header [slot="name"] {
+  & > header [slot="name"] {
     font-weight: var(--chat-header-name-weight);
     font-size: var(--chat-header-name-size);
   }
 
-  > header [slot="status"] {
+  & > header [slot="status"] {
     font-size: var(--chat-header-status-size);
     color: var(--chat-header-status-fg);
     margin-inline-start: auto;
   }
 
   /* -- Messages -- */
-  > section {
+  & > section {
     flex: 1;
     overflow-y: auto;
     padding: var(--chat-messages-padding);
@@ -175,7 +175,7 @@
   }
 
   /* -- Footer -- */
-  > footer {
+  & > footer {
     min-height: var(--chat-footer-min-height);
     display: flex;
     align-items: center;

package/components/code/code.css

@@ -90,7 +90,7 @@
   }
 
   /* Header — chrome band above the code block */
-  > header {
+  & > header {
     display: flex;
     flex-direction: row;
     align-items: center;
@@ -103,14 +103,14 @@
     color: var(--code-header-fg);
   }
 
-  > header [slot="label"] {
+  & > header [slot="label"] {
     font-weight: 500;
     text-transform: uppercase;
     letter-spacing: 0.05em;
   }
 
   /* Copy button — ghost style */
-  > header [slot="copy"] {
+  & > header [slot="copy"] {
     all: unset;
     cursor: pointer;
     font-size: var(--code-header-font);
@@ -121,7 +121,7 @@
       background var(--code-duration) var(--code-easing),
       color var(--code-duration) var(--code-easing);
   }
-  > header [slot="copy"]:hover {
+  & > header [slot="copy"]:hover {
     background: var(--code-copy-hover-bg);
     color: var(--code-copy-hover-fg);
   }
@@ -129,7 +129,7 @@
   /* Pre > Code — reset any ambient page styling (margins, borders,
      radii, backgrounds) so the <code-ui> chrome is the single source
      of visual framing. */
-  > pre {
+  & > pre {
     margin: 0;
     border: none;
     border-radius: 0;
@@ -141,11 +141,11 @@
     line-height: 1.5;
     scrollbar-width: none;
   }
-  > pre::-webkit-scrollbar {
+  & > pre::-webkit-scrollbar {
     display: none;
   }
 
-  > pre > code {
+  & > pre > code {
     margin: 0;
     padding: 0;
     border: none;
@@ -162,10 +162,10 @@
      a `[data-line-state]` row whose bg picks up the state token. The
      CodeMirror path doesn't use these markers; line decorations there go
      through CM extensions instead. */
-  > pre > code[data-line-state-mode] {
+  & > pre > code[data-line-state-mode] {
     display: block;
   }
-  > pre > code[data-line-state-mode] > [data-line-state] {
+  & > pre > code[data-line-state-mode] > [data-line-state] {
     display: grid;
     grid-template-columns: 1fr;
     /* Bleed the row tint to the pre's padding edges so it reads as a
@@ -173,33 +173,33 @@
     margin-inline: calc(-1 * var(--code-px));
     padding-inline: var(--code-px);
   }
-  > pre > code[data-line-numbers] > [data-line-state] {
+  & > pre > code[data-line-numbers] > [data-line-state] {
     grid-template-columns: auto 1fr;
     column-gap: var(--a-space-3);
   }
-  > pre > code[data-line-state-mode] [data-line-num] {
+  & > pre > code[data-line-state-mode] [data-line-num] {
     color: var(--a-fg-subtle);
     text-align: end;
     user-select: none;
     min-width: 1.5ch;
   }
-  > pre > code[data-line-state-mode] [data-line-body] {
+  & > pre > code[data-line-state-mode] [data-line-body] {
     white-space: pre;
   }
   /* Empty lines still need height so the diff column counts line up. */
-  > pre > code[data-line-state-mode] [data-line-body]:empty::before {
+  & > pre > code[data-line-state-mode] [data-line-body]:empty::before {
     content: " ";
   }
-  > pre > code [data-line-state="added"] {
+  & > pre > code [data-line-state="added"] {
     background: var(--a-success-muted);
   }
-  > pre > code [data-line-state="removed"] {
+  & > pre > code [data-line-state="removed"] {
     background: var(--a-danger-muted);
   }
 
   /* Footer — optional chrome band below the code block
      (line counts, byte size, language family, etc.) */
-  > footer {
+  & > footer {
     display: flex;
     flex-direction: row;
     align-items: center;
@@ -288,7 +288,7 @@
      CM's CSS-in-JS stylesheets load first + at lower specificity, so
      these rules override without !important. */
 
-  > [data-cm-mount] {
+  & > [data-cm-mount] {
     display: block;
     overflow: hidden;
   }

package/components/command/command.css

@@ -87,7 +87,7 @@
   }
 
   /* ── Search header ── */
-  > header {
+  & > header {
     display: flex;
     align-items: center;
     gap: var(--command-gap);
@@ -96,13 +96,13 @@
     flex-shrink: 0;
   }
 
-  > header icon-ui {
+  & > header icon-ui {
     flex-shrink: 0;
     color: var(--command-fg-muted);
     --a-icon-size: 1rem;
   }
 
-  > header input {
+  & > header input {
     flex: 1;
     min-width: 0;
     border: none;
@@ -115,16 +115,16 @@
     padding: 0;
   }
 
-  > header input::placeholder {
+  & > header input::placeholder {
     color: var(--command-fg-muted);
   }
 
   /* Suppress focus ring on the input — the palette itself is the focused surface */
-  > header input:focus-visible {
+  & > header input:focus-visible {
     outline: none;
     box-shadow: none;
   }
-  > header:focus-within {
+  & > header:focus-within {
     outline: none;
     box-shadow: none;
   }
@@ -217,7 +217,7 @@
   }
 
   /* ── Footer ── */
-  > footer {
+  & > footer {
     display: flex;
     align-items: center;
     gap: var(--command-px);

package/components/grid/grid.css

@@ -33,10 +33,10 @@
   :scope[columns="auto-fit"]  { grid-template-columns: repeat(auto-fit, minmax(12rem, 1fr)); }
 
   /* Column span — children can span multiple columns */
-  > [span="2"] { grid-column: span 2; }
-  > [span="3"] { grid-column: span 3; }
-  > [span="4"] { grid-column: span 4; }
-  > [span="5"] { grid-column: span 5; }
-  > [span="6"] { grid-column: span 6; }
-  > [span="full"] { grid-column: 1 / -1; }
+  & > [span="2"] { grid-column: span 2; }
+  & > [span="3"] { grid-column: span 3; }
+  & > [span="4"] { grid-column: span 4; }
+  & > [span="5"] { grid-column: span 5; }
+  & > [span="6"] { grid-column: span 6; }
+  & > [span="full"] { grid-column: 1 / -1; }
 }

package/components/pane/pane.css

@@ -81,7 +81,7 @@
   }
 
   /* ── Pane header ── */
-  > header {
+  & > header {
     box-sizing: border-box;
     display: flex;
     align-items: center;
@@ -98,17 +98,17 @@
     transition: background var(--pane-duration) var(--pane-easing);
   }
 
-  > header:hover {
+  & > header:hover {
     background: var(--pane-header-bg-hover);
   }
 
-  > header:focus-visible {
+  & > header:focus-visible {
     outline: none;
     box-shadow: var(--a-focus-ring) inset;
   }
 
   /* Collapse indicator — stamped by JS as icon-ui */
-  > header > [slot="chevron"] {
+  & > header > [slot="chevron"] {
     --a-icon-size: var(--a-caret-size);
     flex-shrink: 0;
     margin-inline-start: auto;
@@ -122,7 +122,7 @@
   }
 
   /* ── Sections ── */
-  > section {
+  & > section {
     flex: 1;
     min-height: 0;
     overflow-y: auto;
@@ -130,13 +130,13 @@
     padding: var(--pane-section-py) var(--pane-section-px);
   }
 
-  > section::-webkit-scrollbar {
+  & > section::-webkit-scrollbar {
     display: none;
   }
 
   /* Section header — section's padding is the single source of horizontal inset;
      content inside the section must not add its own padding. */
-  > section > header {
+  & > section > header {
     font-size: var(--pane-section-header-size);
     color: var(--pane-section-header-fg);
     padding-bottom: var(--pane-col-gap);
@@ -147,12 +147,12 @@
 
   /* Defensive: a data-col directly under a section inherits the section's inset;
      adding its own padding would compound and misalign with the section header. */
-  > section > [data-col] {
+  & > section > [data-col] {
     padding: 0;
   }
 
   /* Section divider between sections */
-  > section + section {
+  & > section + section {
     border-top: 1px solid var(--pane-border);
   }
 
@@ -165,7 +165,7 @@
   }
 
   /* ── Footer ── */
-  > footer {
+  & > footer {
     min-height: var(--pane-bar-height);
     display: flex;
     align-items: center;

package/components/stack/stack.css

@@ -14,7 +14,7 @@
     text-align: inherit;
   }
 
-  > * {
+  & > * {
     grid-area: 1 / 1;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "description": "AdiaUI web components \u2014 vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",