@adia-ai/web-components 0.7.10 → 0.7.12

package/components/theme-provider/theme-provider.test.js

@@ -0,0 +1,94 @@
+/**
+ * <theme-provider> tests
+ *
+ * The provider adopts the AdiaUI foundation (a constructable stylesheet) into
+ * `document.adoptedStyleSheets` — once, deduped — and renders `display: contents`
+ * + `role=presentation`. The real foundation sheet (`web-components.sheet.js`,
+ * ~512 KB of LightningCSS output) is mocked here with a 1-rule stub so the test
+ * exercises the ELEMENT's contract (adopt-once, dedup, transparency), not the
+ * bundle's CSS. Byte-parity of the real sheet is covered by `check:css-bundles-fresh`.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+
+// Stub the heavy foundation sheet — same default-export shape as the generated
+// module: a constructSheet() returning a memoized CSSStyleSheet singleton.
+vi.mock('../../dist/web-components.sheet.js', () => {
+  let sheet = null;
+  return {
+    default: () => {
+      if (typeof CSSStyleSheet === 'undefined') return null;
+      if (!sheet) { sheet = new CSSStyleSheet(); sheet.replaceSync('theme-provider{display:contents}'); }
+      return sheet;
+    },
+  };
+});
+
+// Stub the opt-in twins — the element dynamic-imports these when theme=/scale= is
+// set. We test the attribute contract (sync), not the adopted CSS. (Factories are
+// inlined because vi.mock hoists above any shared `const`.)
+vi.mock('../../dist/themes.sheet.js', () => ({ default: () => { const s = new CSSStyleSheet(); s.replaceSync(':root{}'); return s; } }));
+vi.mock('../../dist/verse.sheet.js', () => ({ default: () => { const s = new CSSStyleSheet(); s.replaceSync(':root{}'); return s; } }));
+vi.mock('../../dist/prose.sheet.js', () => ({ default: () => { const s = new CSSStyleSheet(); s.replaceSync(':root{}'); return s; } }));
+
+import '../../core/element.js';
+import './theme-provider.js'; // registers the tag + adopts the (mocked) foundation at module-eval
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('<theme-provider>', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('adopts the foundation sheet at import (module-eval side effect)', () => {
+    expect(document.adoptedStyleSheets.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('is display:contents + role=presentation on connect', async () => {
+    const el = mount('<theme-provider><span>hi</span></theme-provider>');
+    await tick();
+    expect(el.style.display).toBe('contents');
+    expect(el.getAttribute('role')).toBe('presentation');
+  });
+
+  it('does not clobber an author-set role', async () => {
+    const el = mount('<theme-provider role="group"><span>hi</span></theme-provider>');
+    await tick();
+    expect(el.getAttribute('role')).toBe('group');
+  });
+
+  it('dedupes — N instances adopt the foundation exactly once', async () => {
+    const before = document.adoptedStyleSheets.length; // singleton already adopted at import
+    mount('<theme-provider></theme-provider>');
+    mount('<theme-provider></theme-provider>');
+    mount('<theme-provider></theme-provider>');
+    await tick();
+    expect(document.adoptedStyleSheets.length).toBe(before);
+  });
+
+  it('reflects theme= to the [theme] attribute hook', async () => {
+    const el = mount('<theme-provider theme="ocean"><span>x</span></theme-provider>');
+    await tick();
+    expect(el.getAttribute('theme')).toBe('ocean');
+  });
+
+  it('scale="verse" maps to the [verse] register attribute', async () => {
+    const el = mount('<theme-provider scale="verse"><span>x</span></theme-provider>');
+    await tick();
+    expect(el.hasAttribute('verse')).toBe(true);
+    expect(el.hasAttribute('prose')).toBe(false);
+  });
+
+  it('scale="prose" maps to the [prose] register attribute', async () => {
+    const el = mount('<theme-provider scale="prose"><span>x</span></theme-provider>');
+    await tick();
+    expect(el.hasAttribute('prose')).toBe(true);
+    expect(el.hasAttribute('verse')).toBe(false);
+  });
+});

package/components/theme-provider/theme-provider.yaml

@@ -0,0 +1,96 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIThemeProvider
+tag: theme-provider
+status: experimental
+component: ThemeProvider
+category: layout
+version: 1
+description: |
+  Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens +
+  resets + page-frame + every primitive's CSS) into the document from anywhere
+  in the DOM, so a surface renders fully-styled WITHOUT a hand-wired
+  <link rel="stylesheet"> in <head>. Layout-transparent (display: contents): the
+  element owns no box; children lay out as if it weren't there.
+
+  Mechanism: it imports the constructable-stylesheet twin of web-components.min.css
+  (byte-identical to the CDN bundle, emitted from the same build buffer) and
+  adopts it once into document.adoptedStyleSheets, deduped — adoption fires at
+  module load, before paint. Coexists with the render-blocking <link> path; both
+  deliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for
+  multi-page / top-level surfaces (cacheable across navigations, zero flash); use
+  <theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do
+  not control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend).
+
+  Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in
+  attributes adopt their layer on demand — theme="ocean|forest|slate|…" applies a
+  named preset (adopts the themes layer; matches the [theme] hook) and
+  scale="verse|prose" sets the compact / long-form typographic register (adopts the
+  matching register layer; maps onto the [verse]/[prose] attribute). Each layer is
+  fetched only when its attribute is set, so a bare provider stays lean.
+  Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries
+  the whole foundation); import @adia-ai/web-components/components/theme-provider
+  explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery)
+  and the page shells (chrome over the same foundation).
+props:
+  theme:
+    description: 'Named theme preset for the wrapped subtree (default, ocean, forest, sunset, lavender, rose, slate, midnight). Adopts the themes layer on demand + matches the [theme="…"] hook.'
+    type: string
+    default: ""
+    reflect: true
+  scale:
+    description: 'Typographic / density register for the subtree — "verse" (compact) or "prose" (long-form). Adopts the matching register layer on demand; maps onto the [verse]/[prose] attribute (additive).'
+    type: string
+    default: ""
+    reflect: true
+events: {}
+slots: {}
+states:
+  - name: idle
+    description: Default — foundation adopted into the document; children rendered.
+traits: []
+tokens: {}
+a2ui:
+  rules:
+    - rule: 'Wrap a client-mounted surface root (SPA shell, embedded app, dynamic mount) in <theme-provider> so it self-provides the AdiaUI foundation — no <head> stylesheet link required.'
+      reason: 'Adopts the foundation bundle into the document from anywhere in the tree (document.adoptedStyleSheets).'
+    - rule: 'For multi-page / top-level pages, prefer a render-blocking <link rel="stylesheet" href=".../web-components.min.css"> in <head> instead — cacheable across navigations, styled on the first frame. <theme-provider> and the link deliver byte-identical CSS, so they coexist.'
+      reason: 'Link for multi-page (no flash); provider for SPA/embedded (no head access).'
+    - rule: 'Theme the wrapped subtree with theme="ocean" (a named preset) and/or scale="verse|prose" (compact / long-form register) — the provider adopts the matching opt-in layer on demand. The base foundation is OS light/dark automatically. Keep <theme-provider> at/near the mount root — display:contents means an ancestor "> " child selector will not reach its children.'
+      reason: 'theme/scale each fetch + adopt their layer (themes.css / verse.css / prose.css) on demand; display:contents preserves custom-property inheritance but not child-combinator reach (Light DOM, ADR-0033).'
+anti_patterns: []
+examples:
+  - name: spa-root
+    description: A client-mounted app root that self-provides the foundation (no head link).
+    a2ui: >-
+      [
+        { "id": "root", "component": "ThemeProvider", "children": ["panel"] },
+        { "id": "panel", "component": "Frame", "children": ["body", "actions"] },
+        { "id": "body", "component": "Section", "children": ["copy"] },
+        { "id": "copy", "component": "Text", "variant": "body", "textContent": "Fully styled — no <head> stylesheet link." },
+        { "id": "actions", "component": "Footer", "children": ["go"] },
+        { "id": "go", "component": "Button", "text": "Continue", "variant": "primary" }
+      ]
+keywords:
+  - style
+  - provider
+  - foundation
+  - tokens
+  - reset
+  - adopt
+  - stylesheet
+  - shell
+  - embed
+  - spa
+synonyms:
+  provider:
+    - provider
+    - root
+    - host
+  foundation:
+    - foundation
+    - tokens
+    - styles
+related:
+  - Frame
+  - Card