@adia-ai/web-components 0.7.24 → 0.7.25

package/components/accordion/accordion.css

@@ -27,6 +27,16 @@
 /* ── Item ── */
 @scope (accordion-item-ui) {
   :where(:scope) {
+    /* ── Surface (variant) ──
+       Flat-pixel-exact defaults (SPEC-R2/AC-2): transparent bg, no border,
+       no header/body divider, zero body top-padding — byte-identical to the
+       pre-variant item. Re-pointed by :scope[variant="contained"] below
+       (SPEC-R1/AC-1); consumer-overridable in BOTH postures (SPEC-R3/AC-3). */
+    --accordion-item-bg:      transparent;
+    --accordion-item-border:  none;
+    --accordion-item-divider: none;
+    --accordion-item-body-pt: 0;
+
     /* ── Colors ── */
     --accordion-item-header-fg:       var(--a-fg-subtle);
     --accordion-item-header-fg-hover: var(--a-fg-strong);
@@ -51,11 +61,58 @@
 
     /* ── State ── */
     --accordion-item-focus-ring:      var(--a-focus-ring);
+
+    /* Header-scoped surface tokens — flat defaults keep today's look; contained
+       re-points them (pill flush + inner ring off, ring relocates to the item).
+       Kept as tokens (not [slot="header"] rules under an accordion-ui-led selector)
+       so slot-vocab-vs-css attributes the header slot to accordion-item.yaml. */
+    --accordion-item-header-radius:        var(--accordion-item-radius);
+    --accordion-item-header-focus-shadow:  var(--accordion-item-focus-ring);
   }
 
   :scope {
     box-sizing: border-box;
     display: block;
+    background: var(--accordion-item-bg);
+    border: var(--accordion-item-border);
+    border-radius: var(--accordion-item-radius);   /* invisible in flat: no border/bg */
+  }
+
+  /* ═══════ Variant: contained (token-only re-point + sanctioned layout exception) ═══════
+     Own variant OR inherited from a contained host. CHILD combinator (`>`) so a FLAT
+     accordion nested inside a contained one does NOT leak contained styling to the inner
+     items (Finding 4); items are canonically direct children. Per-item opt-out: [variant="flat"].
+     Two layout touches (overflow clip + surface focus-ring relocation) are documented
+     exceptions in component-token-contract.md's sanctioned-exception table; bg/border/divider/
+     body-pt AND the header pill-radius / inner-ring (via --accordion-item-header-*) stay pure
+     token re-points.
+     NB: the inherited form MUST use `:scope` (not a literal `accordion-item-ui`) — under
+     @scope, only `:scope` may reference the `accordion-ui` ancestor to its LEFT; a literal
+     tag is confined to the scope donut and would not match the outside ancestor. */
+  :scope[variant="contained"],
+  :where(accordion-ui[variant="contained"]) > :scope:not([variant="flat"]) {
+    --accordion-item-bg:                  var(--a-bg-subtle);
+    --accordion-item-border:              1px solid var(--a-border-subtle);
+    --accordion-item-divider:             1px solid var(--a-border-subtle);
+    --accordion-item-body-pt:             var(--a-space-2);
+    --accordion-item-header-radius:       0;      /* pill corners flush to the surface (Finding 8) */
+    --accordion-item-header-focus-shadow: none;   /* inner ring off; surface ring below (Finding 2) */
+  }
+
+  :scope[variant="contained"],
+  :where(accordion-ui[variant="contained"]) > :scope:not([variant="flat"]) {
+    overflow: hidden;                              /* pill + body clip to --accordion-item-radius */
+  }
+
+  /* Focus ring follows the SURFACE radius (AC-4); the item's own box-shadow is NOT clipped by
+     its own overflow:hidden. `:has(> :focus-visible)` fires when the header — the item's only
+     focusable DIRECT child (a body-nested control is a grandchild) — is focused, WITHOUT naming
+     [slot="header"] in an accordion-ui-led selector. Covers BOTH own-variant and host-inherited
+     forms; the inner ring is suppressed via --accordion-item-header-focus-shadow → none, so no
+     double ring in the attribute-less-item case (Finding 2). */
+  :scope[variant="contained"]:has(> :focus-visible),
+  :where(accordion-ui[variant="contained"]) > :scope:not([variant="flat"]):has(> :focus-visible) {
+    box-shadow: var(--accordion-item-focus-ring);
   }
 
   /* ── Header ── */
@@ -67,7 +124,7 @@
     justify-content: space-between;
     gap: var(--accordion-item-header-gap);
     padding: var(--accordion-item-py) var(--accordion-item-px);
-    border-radius: var(--accordion-item-radius);
+    border-radius: var(--accordion-item-header-radius);   /* flat: = --accordion-item-radius; contained: 0 */
     cursor: pointer;
     user-select: none;
     font-size: var(--accordion-item-header-font);
@@ -90,7 +147,7 @@
   }
 
   :scope [slot="header"]:focus-visible {
-    box-shadow: var(--accordion-item-focus-ring);
+    box-shadow: var(--accordion-item-header-focus-shadow);   /* flat: = --accordion-item-focus-ring; contained: none (surface ring instead) */
   }
 
   :scope[open] [slot="header"] {
@@ -125,6 +182,7 @@
 
   :scope[open] [slot="body"] {
     display: block;
-    padding: 0 var(--accordion-item-px) var(--accordion-item-py);
+    padding: var(--accordion-item-body-pt) var(--accordion-item-px) var(--accordion-item-py);
+    border-top: var(--accordion-item-divider);   /* default `none` in flat → invisible, zero layout (Finding 3) */
   }
 }

package/components/accordion/accordion.d.ts

@@ -29,6 +29,14 @@ export type AccordionToggleEvent = CustomEvent<AccordionToggleEventDetail>;
 export class UIAccordion extends UIElement {
   /** Allow multiple panels to be open simultaneously */
   multiple: boolean;
+  /** Visual posture, inherited by child accordion-item-ui elements unless a
+child sets its own [variant]. `flat` (default) renders items with no
+chrome — settings pages, FAQ blocks, anywhere the accordion sits
+directly on the page canvas. `contained` gives every item a bounded
+surface (background + border + radius spanning header and open body,
+plus a divider between them when open) — the composition to reach for
+when nesting the accordion inside <card-ui>. */
+  variant: 'flat' | 'contained';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
@@ -50,6 +58,10 @@ export class UIAccordionItem extends UIElement {
   open: boolean;
   /** Header text — the clickable label that toggles the section. */
   text: string;
+  /** Per-item posture override. Items normally inherit their host
+accordion-ui's [variant] — set this directly on ONE item only to
+opt it out of (`flat`) or into (`contained`) the host's posture. */
+  variant: 'flat' | 'contained';
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/accordion/accordion.yaml

@@ -24,6 +24,21 @@ props:
     description: Allow multiple panels to be open simultaneously
     type: boolean
     default: false
+  variant:
+    description: |-
+      Visual posture, inherited by child accordion-item-ui elements unless a
+      child sets its own [variant]. `flat` (default) renders items with no
+      chrome — settings pages, FAQ blocks, anywhere the accordion sits
+      directly on the page canvas. `contained` gives every item a bounded
+      surface (background + border + radius spanning header and open body,
+      plus a divider between them when open) — the composition to reach for
+      when nesting the accordion inside <card-ui>.
+    type: string
+    default: flat
+    enum:
+      - flat
+      - contained
+    reflect: true
 events:
   toggle:
     description: Fired when the accordion panel opens or closes (single-pane accordion-ui dispatch — multi-pane group emits the same event per child).
@@ -49,6 +64,8 @@ a2ui:
       reason: 'Decision rule vs tabs.'
     - rule: 'Item ordering is DOM-order; no auto-sort.'
       reason: 'Author-controlled order.'
+    - rule: 'Set variant="contained" for a bounded per-item surface (background, border, radius, and an open-state divider) — the composition to reach for when nesting inside <card-ui>. Default variant="flat" (no chrome) suits settings pages and FAQ blocks sitting on the page canvas.'
+      reason: 'Posture selection guidance (flat vs contained).'
 anti_patterns: []
 examples:
   - name: accordion-settings

package/components/code/code.class.js

@@ -26,7 +26,7 @@
  * CodeMirror 6 is lazy-loaded and mounted in place of `<pre><code>` for
  * syntax-highlighted rendering. Phase 1 shipped read-only; Phase 2 added
  * `[editable]`; Phase 3 added lint + form-association (see
- * `docs/specs/code-editor.md §12`).
+ * `.claude/docs/specs/code-editor.md §12`).
  *
  * Form participation — editable instances are Form-Associated Custom
  * Elements (FACE). Set `name`, `required`, `disabled`, `readonly` to

package/components/drawer/drawer.class.js

@@ -88,7 +88,7 @@ export class UIDrawer extends UIElement {
     // after the property change, which Safari treats as outside the user-gesture
     // window and silently no-ops the showModal. Wrap the auto-installed `open`
     // setter so dialog state syncs in the same synchronous frame as the
-    // assignment. See docs/BROWSER-COMPAT.md §3a (Flavor C).
+    // assignment. See .claude/docs/BROWSER-COMPAT.md §3a (Flavor C).
     const desc = Object.getOwnPropertyDescriptor(this, 'open');
     if (desc?.set) {
       const origSet = desc.set;
@@ -337,7 +337,7 @@ export class UIDrawer extends UIElement {
       // requestAnimationFrame when a top-layer dialog is open, sometimes
       // delaying [data-open] (and the slide-in transition) by tens of
       // seconds. Forcing a reflow keeps the animation start in the same
-      // synchronous frame. See docs/BROWSER-COMPAT.md §3a (Flavor C).
+      // synchronous frame. See .claude/docs/BROWSER-COMPAT.md §3a (Flavor C).
       void dialog.offsetHeight;
       dialog.setAttribute('data-open', '');
       // §FB-27 (P2): emit `opened` after the slide-in transition completes

package/components/feed/feed.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Feed.json",
   "title": "Feed",
-  "description": "Shared top-layer feed channel. Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.",
+  "description": "Shared top-layer feed channel. Per .claude/docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.",
   "type": "object",
   "allOf": [
     {

package/components/feed/feed.class.js

@@ -14,7 +14,7 @@
 /**
  * <feed-ui> + <feed-item-ui> — Shared top-layer feed channel.
  *
- * Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001).
+ * Per .claude/docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001).
  *
  * Phase 1 (skeleton) ships here:
  *   - Per-position singletons (`<feed-ui position="bottom-right">`)

package/components/feed/feed.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<feed-ui>` — Shared top-layer feed channel. Per docs/specs/feed-channel.md
+ * `<feed-ui>` — Shared top-layer feed channel. Per .claude/docs/specs/feed-channel.md
  * (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into
  * document.body via Popover API; consumers post via the static API
  * (`UIFeed.post()`) or the global 'feed' CustomEvent.

package/components/feed/feed.yaml

@@ -8,7 +8,7 @@ component: Feed
 category: container
 version: 1
 description: >-
-  Shared top-layer feed channel. Per docs/specs/feed-channel.md
+  Shared top-layer feed channel. Per .claude/docs/specs/feed-channel.md
   (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into
   document.body via Popover API; consumers post via the static API
   (`UIFeed.post()`) or the global 'feed' CustomEvent.
@@ -60,7 +60,7 @@ related:
 a2ui:
   rules:
     - rule: 'Top-layer notification feed channel — singleton per position (top-right, bottom-center, etc.) mounted lazily into document.body.'
-      reason: 'Per docs/specs/feed-channel.md.'
+      reason: 'Per .claude/docs/specs/feed-channel.md.'
     - rule: 'Hosts <feed-item-ui> children programmatically via static API (UIFeed.post(...)). Do not place feed-items declaratively.'
       reason: 'Imperative API ownership.'
     - rule: 'For inline persistent alerts inside content regions use <alert-ui> instead; feed is ephemeral overlay.'

package/components/field/field.class.js

@@ -60,7 +60,7 @@ export class UIField extends UIElement {
   // is the single source of truth — validity is a property of the value, not
   // of the layout wrapper). field-ui mirrors the child's error string into
   // its own [data-field-error] slot so the validation message renders below
-  // the control. See docs/specs/component-token-contract.md "Toggle state
+  // the control. See .claude/docs/specs/component-token-contract.md "Toggle state
   // naming" / open decisions resolution log.
   get error() {
     const ctrl = this.#findControl();

package/components/loading-overlay/loading-overlay.class.js

@@ -49,7 +49,7 @@
  * changes are driven by the reactive [active] setter wrapper, which
  * starts/cancels the timer + applies aria-busy when the timer fires.
  *
- * @see SPEC-034 (docs/specs/implementation-ready/SPEC-034-loading-overlay.md)
+ * @see SPEC-034 (.claude/docs/specs/implementation-ready/SPEC-034-loading-overlay.md)
  */
 
 import { UIElement } from '../../core/element.js';

package/components/loading-overlay/loading-overlay.yaml

@@ -1,4 +1,4 @@
-# Hand-authored per SPEC-034 (docs/specs/implementation-ready/SPEC-034-loading-overlay.md).
+# Hand-authored per SPEC-034 (.claude/docs/specs/implementation-ready/SPEC-034-loading-overlay.md).
 # Edit this file; run `npm run build:components` to regenerate loading-overlay.a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UILoadingOverlay

package/components/modal/modal.class.js

@@ -212,7 +212,7 @@ export class UIModal extends UIElement {
     // Sync open state. Synchronous reflow instead of rAF — Safari throttles
     // requestAnimationFrame when a top-layer dialog is open, sometimes
     // delaying [data-open] (and the scale-in transition) by tens of seconds.
-    // See docs/BROWSER-COMPAT.md §3a (Flavor C).
+    // See .claude/docs/BROWSER-COMPAT.md §3a (Flavor C).
     if (this.open && !dialog.open) {
       this.#closing = false;
       this.#previousFocus = document.activeElement;

package/components/nav/nav.class.js

@@ -134,7 +134,7 @@ export class UINav extends UIElement {
   // Safari macOS leaves :hover stuck on items the cursor passed through
   // when the DOM mutates during click+route navigation. Toggling pointer-
   // events forces re-evaluation of hover state on next paint.
-  // See docs/BROWSER-COMPAT.md §3a.
+  // See .claude/docs/BROWSER-COMPAT.md §3a.
   #flushHoverState() {
     this.style.pointerEvents = 'none';
     requestAnimationFrame(() => {

package/components/nav/nav.examples.md

@@ -18,10 +18,10 @@
 
 ```html
 <nav-ui variant="section" heading="Documentation" style="width:240px;">
-  <nav-item-ui text="Overview" value="docs/overview" selected></nav-item-ui>
-  <nav-item-ui text="Quickstart" value="docs/quickstart"></nav-item-ui>
-  <nav-item-ui text="API reference" value="docs/api"></nav-item-ui>
-  <nav-item-ui text="Examples" value="docs/examples"></nav-item-ui>
+  <nav-item-ui text="Overview" value=".claude/docs/overview" selected></nav-item-ui>
+  <nav-item-ui text="Quickstart" value=".claude/docs/quickstart"></nav-item-ui>
+  <nav-item-ui text="API reference" value=".claude/docs/api"></nav-item-ui>
+  <nav-item-ui text="Examples" value=".claude/docs/examples"></nav-item-ui>
 </nav-ui>
 ```
 

package/components/popover/popover.class.js

@@ -96,7 +96,7 @@ export class UIPopover extends UIElement {
       // try/catch covers test envs (happy-dom) without the API. Known iOS
       // Safari quirks at the supported floor (light-dismiss broken on
       // 17.0–18.2, virtual-keyboard-on-input persists past 18.3) are
-      // documented in docs/BROWSER-COMPAT.md §3a.
+      // documented in .claude/docs/BROWSER-COMPAT.md §3a.
       try { content.showPopover(); } catch { /* popover API unavailable — anchor positioning still runs */ }
     }
 

package/components/spinner/spinner.class.js

@@ -36,7 +36,7 @@
  * sets the three ARIA attributes once; render() keeps aria-valuetext in
  * sync with the [label] prop.
  *
- * @see SPEC-001 (docs/specs/implementation-ready/SPEC-001-spinner-loader.md)
+ * @see SPEC-001 (.claude/docs/specs/implementation-ready/SPEC-001-spinner-loader.md)
  */
 
 import { UIElement } from '../../core/element.js';

package/components/spinner/spinner.yaml

@@ -1,4 +1,4 @@
-# Hand-authored per SPEC-001 (docs/specs/implementation-ready/SPEC-001-spinner-loader.md).
+# Hand-authored per SPEC-001 (.claude/docs/specs/implementation-ready/SPEC-001-spinner-loader.md).
 # Edit this file; run `npm run build:components` to regenerate spinner.a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UISpinner

package/components/toast/toast.class.js

@@ -14,7 +14,7 @@
 /**
  * <toast-ui> — Thin facade over `<feed-ui>` / `UIFeed.post()`.
  *
- * Phase 4 of `docs/specs/feed-channel.md` (SPEC-FEED-CHANNEL-001) —
+ * Phase 4 of `.claude/docs/specs/feed-channel.md` (SPEC-FEED-CHANNEL-001) —
  * toast-ui no longer owns its own per-position container. Both
  * declarative `<toast-ui>` and imperative `UIToast.show()` paths
  * route through `UIFeed`. The element exists for back-compat:

package/custom-elements.json

@@ -4076,7 +4076,7 @@
         },
         {
           "kind": "class",
-          "description": "Shared top-layer feed channel. Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.",
+          "description": "Shared top-layer feed channel. Per .claude/docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.",
           "name": "UIFeedContainer",
           "tagName": "feed-ui",
           "superclass": {