@adia-ai/web-components 0.6.20 → 0.6.22

package/components/tree/tree-item.yaml

@@ -39,3 +39,45 @@ props:
 
       Added in §184 (v0.5.5, FEEDBACK-08 §1).
     type: string
+
+a2ui:
+  rules:
+    - >-
+      <tree-item-ui> MUST be a direct or nested descendant of
+      <tree-ui>. It is not a standalone primitive — outside a <tree-ui>
+      parent, selection / expansion / keyboard nav don't wire.
+    - >-
+      Provide a stable [value] attribute on every <tree-item-ui> that
+      consumers will select. The `tree-select` event's detail.value is
+      the identifier downstream code reads to know which node was
+      picked.
+    - >-
+      Use [open] to pre-expand branch nodes on initial render. Do NOT
+      set [selected] declaratively on more than one item — the parent
+      <tree-ui> manages selection. The host listens for click /
+      Enter / Space / ArrowRight (expand) / ArrowLeft (collapse) per
+      WAI-ARIA tree-view APG.
+    - >-
+      Use [icon] (Phosphor name) for affordance (folder / file /
+      component icons); use [badge] for counts or short status labels
+      (§184 v0.5.5).
+    - >-
+      Nest further <tree-item-ui> in the default slot only — no
+      <list-item-ui>, <nav-item-ui>, or arbitrary content inside a
+      tree row. The chevron is auto-stamped when the row has nested
+      tree-item-ui children.
+
+keywords:
+  - tree-item
+  - tree-row
+  - tree-node
+  - hierarchy-item
+
+related:
+  - Tree
+  - List
+  - Nav
+  - Accordion
+
+synonyms:
+  tree-item: [tree-node, tree-row, hierarchy-row]

package/components/tree/tree.a2ui.json

@@ -70,7 +70,12 @@
       "folder"
     ],
     "name": "UITree",
-    "related": [],
+    "related": [
+      "TreeItem",
+      "Nav",
+      "List",
+      "Accordion"
+    ],
     "slots": {
       "default (tree-item-ui children)": {
         "description": "Child content region for the `default (tree-item-ui children)` slot."

package/components/tree/tree.yaml

@@ -92,7 +92,32 @@ tokens:
 requiredIcons:
   - caret-right
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Use <tree-ui> only when data is hierarchical with arbitrary
+      nesting AND a single selected node is meaningful. For flat
+      lists use <list-ui>; for flat sidebar navigation use <nav-ui>;
+      for one-level collapsible groups use <accordion-ui>.
+    - >-
+      Canonical mount: inside <editor-sidebar slot="leading"> →
+      <pane-ui side="leading" resizable> → <section> → <tree-ui id="…">
+      as the structure / navigator pane of the three-pane editor shell.
+      Pair with a <header> in the same pane (e.g. "Structure",
+      "Layers", "Files").
+    - >-
+      Direct children of <tree-ui> MUST be <tree-item-ui>. No other
+      element types in the default slot. <tree-ui> manages
+      single-selection across the whole subtree and implements
+      WAI-ARIA tree-view keyboard navigation (Arrow keys, Enter /
+      Space, Home / End).
+    - >-
+      Listen for `tree-select` on the <tree-ui>, NOT on individual
+      rows — selection is managed by the parent and bubbles once.
+      Detail = {item, text, value, ctrlKey, metaKey, shiftKey}.
+    - >-
+      Per ADR-0027, <tree-ui> composes <icon-ui> (for chevrons) but
+      does NOT auto-import its children. Consumer pages must
+      explicitly import both <tree-ui> and <tree-item-ui>.
 anti_patterns: []
 examples:
   - name: basic-tree
@@ -128,4 +153,8 @@ synonyms:
     - sidebar
     - nav
     - tree
-related: []
+related:
+  - TreeItem
+  - Nav
+  - List
+  - Accordion

package/components/upload/upload.yaml

@@ -66,7 +66,13 @@ states:
 traits: []
 tokens: {}
 a2ui:
-  rules: []
+  rules:
+    - rule: 'File-upload input with drop zone + browse button. Form-associated; emits file-list change events.'
+      reason: 'File-input canonical primitive.'
+    - rule: 'Multiple attribute enables multi-file selection; accept= constrains file types.'
+      reason: 'Standard file-input knobs.'
+    - rule: 'For agent chat attachments use <chat-composer-ui>''s built-in upload affordance instead.'
+      reason: 'Chat composer has its own attachment lane.'
 anti_patterns: []
 examples:
   - name: data-import

package/core/index.js

@@ -31,3 +31,4 @@ export * from './transport.js';
 export * from './polyfills.js';
 export { streams, whenStream } from './data-stream.js';
 export * from './streams-bridge.js';
+export * from './responsive.js';

package/core/responsive.d.ts

@@ -0,0 +1,29 @@
+import type { Signal } from './signals.js';
+
+/** Min-width px thresholds keyed by breakpoint name. */
+export declare const BREAKPOINTS: { xs: 0; sm: 480; md: 768; lg: 1024; xl: 1280 };
+
+/** Ordered breakpoint names, narrowest → widest. */
+export declare const BP_NAMES: string[];
+
+/**
+ * Shared signal holding the current viewport breakpoint name.
+ * Read inside a UIElement `render()` to subscribe; the component
+ * re-renders automatically on breakpoint change.
+ */
+export declare const breakpoint: Signal<'xs' | 'sm' | 'md' | 'lg' | 'xl'>;
+
+/**
+ * Resolve a responsive attribute value for the given breakpoint.
+ *
+ * Syntax: `"base @bp:override ..."` — e.g. `"1 2@sm 4@lg"`.
+ * Mobile-first: `@bp` applies at that breakpoint and all wider ones.
+ * Returns the unannotated default when no annotation matches.
+ *
+ * @param value    Raw attribute string (e.g. `"1 2@sm 4@lg"`).
+ * @param activeBp Breakpoint to resolve for. Defaults to `breakpoint.value`.
+ */
+export declare function parseResponsive(
+  value: string | null | undefined,
+  activeBp?: string,
+): string | null;

package/core/responsive.js

@@ -0,0 +1,120 @@
+/**
+ * AdiaUI Responsive — viewport-breakpoint signal + `@bp` attribute parser.
+ *
+ * Components that support responsive attribute values read `breakpoint.value`
+ * inside their `render()` method. UIElement wraps render() in an effect, so
+ * the component automatically re-renders whenever the viewport crosses a
+ * breakpoint boundary — no manual subscription needed.
+ *
+ * ## Syntax
+ *
+ *   "4"             → scalar, fast-path (no parsing)
+ *   "1 2@sm 4@lg"   → 1 on xs, 2 from sm, 4 from lg/xl
+ *   "4 1@sm"        → 4 on md/lg/xl, 1 on xs/sm
+ *   "2@md"          → 2 from md+, inherits component default below md
+ *
+ * Semantics: mobile-first / min-width — `@bp` means "apply at this
+ * breakpoint and all wider viewports, unless overridden by a larger
+ * annotation". The unannotated value is the base (smallest screens).
+ *
+ * Resolution: largest `@bp` whose index ≤ active-bp-index wins.
+ * If no annotation matches, the unannotated default is returned.
+ *
+ * @example
+ *   import { parseResponsive, breakpoint } from '../../core/responsive.js';
+ *
+ *   render() {
+ *     const bp   = breakpoint.value;              // subscribe
+ *     const cols = parseResponsive(this.columns, bp);
+ *     this.style.gridTemplateColumns = `repeat(${cols}, 1fr)`;
+ *   }
+ */
+
+import { signal } from './signals.js';
+
+// ─── Breakpoint scale ─────────────────────────────────────────────────────────
+
+/** Min-width px thresholds, narrowest first. */
+export const BREAKPOINTS = /** @type {Record<string, number>} */ ({
+  xs:    0,
+  sm:  480,
+  md:  768,
+  lg: 1024,
+  xl: 1280,
+});
+
+/** Ordered list of breakpoint names, narrowest → widest. */
+export const BP_NAMES = /** @type {string[]} */ (Object.keys(BREAKPOINTS));
+const BP_VALS          = /** @type {number[]} */ (Object.values(BREAKPOINTS));
+
+// ─── Active-breakpoint signal ─────────────────────────────────────────────────
+
+function _detect() {
+  if (typeof window === 'undefined') return 'lg'; // SSR / non-browser fallback
+  const w = window.innerWidth;
+  for (let i = BP_NAMES.length - 1; i >= 0; i--) {
+    if (w >= BP_VALS[i]) return BP_NAMES[i];
+  }
+  return 'xs';
+}
+
+/**
+ * Shared signal — current viewport breakpoint name.
+ * Reading `.value` inside a UIElement `render()` creates a subscription;
+ * the component re-renders automatically on breakpoint change.
+ *
+ * @type {import('./signals.js').Signal<string>}
+ */
+export const breakpoint = signal(_detect());
+
+// Wire matchMedia listeners once (browser only, skipped in SSR / tests)
+if (typeof window !== 'undefined') {
+  // One listener per non-zero threshold; fires whenever the viewport crosses
+  // that boundary in either direction.
+  for (let i = 1; i < BP_VALS.length; i++) {
+    window
+      .matchMedia(`(min-width: ${BP_VALS[i]}px)`)
+      .addEventListener('change', () => { breakpoint.value = _detect(); });
+  }
+}
+
+// ─── Parser ───────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a responsive attribute value for the given breakpoint.
+ *
+ * @param {string | null | undefined} value    Raw attribute string.
+ * @param {string}                    activeBp Current breakpoint name.
+ * @returns {string | null}                    Resolved scalar, or null.
+ */
+export function parseResponsive(value, activeBp = breakpoint.value) {
+  if (!value) return null;
+  if (!value.includes('@')) return value; // fast path — plain scalar
+
+  let defaultVal = /** @type {string | null} */ (null);
+  const bpMap    = /** @type {Map<string, string>} */ (new Map());
+
+  for (const token of value.trim().split(/\s+/)) {
+    const at = token.lastIndexOf('@');
+    if (at === -1) {
+      defaultVal = token;
+    } else {
+      bpMap.set(token.slice(at + 1), token.slice(0, at));
+    }
+  }
+
+  // Find the largest @bp annotation whose index ≤ active-bp index.
+  const activeIdx = BP_NAMES.indexOf(activeBp);
+  let   best      = /** @type {string | null} */ (null);
+  let   bestIdx   = -1;
+
+  for (const [bp, val] of bpMap) {
+    const idx = BP_NAMES.indexOf(bp);
+    if (idx !== -1 && idx <= activeIdx && idx > bestIdx) {
+      best    = val;
+      bestIdx = idx;
+    }
+  }
+
+  return best ?? defaultVal;
+}

package/core/responsive.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { parseResponsive, BP_NAMES, BREAKPOINTS } from './responsive.js';
+
+// ── parseResponsive ────────────────────────────────────────────────────────
+
+describe('parseResponsive — scalar fast path', () => {
+  it('returns value unchanged when no @ present', () => {
+    expect(parseResponsive('3',        'md')).toBe('3');
+    expect(parseResponsive('auto-fill','lg')).toBe('auto-fill');
+    expect(parseResponsive('md',       'sm')).toBe('md');
+  });
+
+  it('returns null for null / undefined input', () => {
+    expect(parseResponsive(null,      'md')).toBeNull();
+    expect(parseResponsive(undefined, 'md')).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(parseResponsive('', 'md')).toBeNull();
+  });
+});
+
+describe('parseResponsive — mobile-first resolution', () => {
+  // "1 2@sm 4@lg" = 1 at xs, 2 from sm, 4 from lg
+  const val = '1 2@sm 4@lg';
+
+  it('base (xs) — no annotation matches, returns unannotated default', () => {
+    expect(parseResponsive(val, 'xs')).toBe('1');
+  });
+
+  it('sm — @sm matches exactly', () => {
+    expect(parseResponsive(val, 'sm')).toBe('2');
+  });
+
+  it('md — largest annotation ≤ md is @sm', () => {
+    expect(parseResponsive(val, 'md')).toBe('2');
+  });
+
+  it('lg — @lg matches exactly', () => {
+    expect(parseResponsive(val, 'lg')).toBe('4');
+  });
+
+  it('xl — largest annotation ≤ xl is @lg', () => {
+    expect(parseResponsive(val, 'xl')).toBe('4');
+  });
+});
+
+describe('parseResponsive — sparse annotations (two-point)', () => {
+  it('"4 1@sm": 4 at xs, 1 from sm upward', () => {
+    expect(parseResponsive('4 1@sm', 'xs')).toBe('4');
+    expect(parseResponsive('4 1@sm', 'sm')).toBe('1');
+    expect(parseResponsive('4 1@sm', 'md')).toBe('1');
+    expect(parseResponsive('4 1@sm', 'lg')).toBe('1');
+  });
+
+  it('"2@md": no default — returns null below md, 2 from md up', () => {
+    expect(parseResponsive('2@md', 'xs')).toBeNull();
+    expect(parseResponsive('2@md', 'sm')).toBeNull();
+    expect(parseResponsive('2@md', 'md')).toBe('2');
+    expect(parseResponsive('2@md', 'xl')).toBe('2');
+  });
+
+  it('"1 4@lg": only one override — md falls back to base', () => {
+    expect(parseResponsive('1 4@lg', 'xs')).toBe('1');
+    expect(parseResponsive('1 4@lg', 'md')).toBe('1');
+    expect(parseResponsive('1 4@lg', 'lg')).toBe('4');
+    expect(parseResponsive('1 4@lg', 'xl')).toBe('4');
+  });
+});
+
+describe('parseResponsive — order-independence', () => {
+  it('annotations in any order resolve identically', () => {
+    const a = '1 2@sm 4@lg';
+    const b = '4@lg 1 2@sm';
+    const c = '2@sm 4@lg 1';
+    for (const bp of BP_NAMES) {
+      const ref = parseResponsive(a, bp);
+      expect(parseResponsive(b, bp)).toBe(ref);
+      expect(parseResponsive(c, bp)).toBe(ref);
+    }
+  });
+});
+
+describe('parseResponsive — edge cases', () => {
+  it('unknown bp annotation is silently skipped; default still returned', () => {
+    expect(parseResponsive('3 1@xxl', 'xl')).toBe('3');
+  });
+
+  it('single annotation with no default', () => {
+    expect(parseResponsive('2@sm', 'xs')).toBeNull();
+    expect(parseResponsive('2@sm', 'sm')).toBe('2');
+  });
+
+  it('all five breakpoints annotated — each resolves to its own value', () => {
+    const val = '0 1@xs 2@sm 3@md 4@lg 5@xl';
+    expect(parseResponsive(val, 'xs')).toBe('1');
+    expect(parseResponsive(val, 'sm')).toBe('2');
+    expect(parseResponsive(val, 'md')).toBe('3');
+    expect(parseResponsive(val, 'lg')).toBe('4');
+    expect(parseResponsive(val, 'xl')).toBe('5');
+  });
+});
+
+// ── BREAKPOINTS contract ───────────────────────────────────────────────────
+
+describe('BREAKPOINTS / BP_NAMES exports', () => {
+  it('BP_NAMES is ordered narrowest → widest', () => {
+    expect(BP_NAMES).toEqual(['xs', 'sm', 'md', 'lg', 'xl']);
+  });
+
+  it('BREAKPOINTS values are strictly increasing', () => {
+    const vals = BP_NAMES.map((bp) => BREAKPOINTS[bp]);
+    for (let i = 1; i < vals.length; i++) {
+      expect(vals[i]).toBeGreaterThan(vals[i - 1]);
+    }
+  });
+
+  it('xs starts at 0', () => {
+    expect(BREAKPOINTS.xs).toBe(0);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.20",
+  "version": "0.6.22",
   "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",

package/styles/tokens.css

@@ -96,15 +96,15 @@
   --a-radius: var(--a-radius-md);
 
   /* ── Inset ── */
-  --a-inset-sm: var(--a-space-4);
-  --a-inset-md: var(--a-space-6);
-  --a-inset-lg: var(--a-space-8);
+  --a-inset-sm: var(--a-space-2);
+  --a-inset-md: var(--a-space-4);
+  --a-inset-lg: var(--a-space-6);
   --a-inset: var(--a-inset-md);
 
   /* ── Gaps ── */
-  --a-gap-sm: var(--a-space-3);
-  --a-gap-md: var(--a-space-4);
-  --a-gap-lg: var(--a-space-6);
+  --a-gap-sm: var(--a-space-2);
+  --a-gap-md: var(--a-space-3);
+  --a-gap-lg: var(--a-space-4);
   --a-gap: var(--a-gap-md);
 
   /* ── Sizing (component heights) ──