@adia-ai/web-components 0.6.17 → 0.6.19

package/components/text/text.a2ui.json

@@ -13,6 +13,20 @@
     }
   ],
   "properties": {
+    "color": {
+      "description": "Override the variant's color token. Permissive: unknown values are no-ops (variant color wins). Added v0.6.18 (FB-10).",
+      "type": "string",
+      "enum": [
+        "default",
+        "subtle",
+        "strong",
+        "accent",
+        "danger",
+        "success",
+        "warning"
+      ],
+      "default": ""
+    },
     "component": {
       "const": "Text"
     },
@@ -21,11 +35,32 @@
       "type": "number",
       "default": 0
     },
+    "size": {
+      "description": "Override the variant's font-size on the body ladder. Maps to --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values are no-ops (variant size wins). Added v0.6.18 (FB-10).",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": ""
+    },
     "strong": {
       "description": "When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy.",
       "type": "boolean",
       "default": false
     },
+    "text-align": {
+      "description": "Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10).",
+      "type": "string",
+      "enum": [
+        "start",
+        "center",
+        "end",
+        "justify"
+      ],
+      "default": ""
+    },
     "textContent": {
       "description": "Display text content. The main payload field for Text components extracted from HTML.",
       "$ref": "common_types.json#/$defs/DynamicString"
@@ -67,6 +102,17 @@
         "section": "Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.",
         "subsection": "Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section."
       }
+    },
+    "weight": {
+      "description": "Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10).",
+      "type": "string",
+      "enum": [
+        "regular",
+        "medium",
+        "semibold",
+        "bold"
+      ],
+      "default": ""
     }
   },
   "required": [

package/components/text/text.css

@@ -61,6 +61,47 @@
   :scope[variant="deck"]       { --text-family: var(--a-deck-family);       --text-weight: var(--a-deck-weight);       --text-size: var(--a-deck-size);       --text-leading: var(--a-deck-leading);       --text-tracking: var(--a-deck-tracking);       --text-case: var(--a-deck-case);       --text-color: var(--a-deck-color); }
   :scope[variant="metric"]     { --text-family: var(--a-metric-family);     --text-weight: var(--a-metric-weight);     --text-size: var(--a-metric-size);     --text-leading: var(--a-metric-leading);     --text-tracking: var(--a-metric-tracking);     --text-case: var(--a-metric-case);     --text-color: var(--a-metric-color); }
 
+  /* ── v0.6.18 (FB-10) — finer-control overrides on top of `variant` ──
+     The skill always documented an overlay API (color="subtle",
+     size="sm", weight="semibold", text-align="center"). Pre-v0.6.18 these
+     attributes existed only as documentation — text-ui ignored them and
+     rendered the variant default. v0.6.18 implements them as attribute
+     selectors that override the `--text-*` CSS variables set by [variant].
+     Each is intentionally permissive: unknown values fall back to the
+     variant's value rather than throwing. Authoring `<text-ui color="...">`
+     with an unknown color = no-op (variant color wins). */
+
+  /* size — sm | md | lg (md is the body default ~15-16px) */
+  :scope[size="sm"]  { --text-size: var(--a-body-sm); }
+  :scope[size="md"]  { --text-size: var(--a-body-md); }
+  :scope[size="lg"]  { --text-size: var(--a-body-lg); }
+
+  /* color — default | subtle | strong | accent | danger | success | warning
+     (no value = variant default; "default" is an explicit reset). */
+  :scope[color="default"] { --text-color: var(--a-fg); }
+  :scope[color="subtle"]  { --text-color: var(--a-fg-muted); }
+  :scope[color="strong"]  { --text-color: var(--a-fg-strong); }
+  :scope[color="accent"]  { --text-color: var(--a-accent); }
+  :scope[color="danger"]  { --text-color: var(--a-danger-bg); }
+  :scope[color="success"] { --text-color: var(--a-success-bg); }
+  :scope[color="warning"] { --text-color: var(--a-warning-bg); }
+
+  /* weight — regular | medium | semibold | bold */
+  :scope[weight="regular"]  { --text-weight: var(--a-weight); }
+  :scope[weight="medium"]   { --text-weight: var(--a-weight-medium); }
+  :scope[weight="semibold"] { --text-weight: var(--a-weight-semibold); }
+  :scope[weight="bold"]     { --text-weight: var(--a-weight-bold); }
+
+  /* text-align — start | center | end | justify */
+  :scope[text-align="start"]   { text-align: start; }
+  :scope[text-align="center"]  { text-align: center; }
+  :scope[text-align="end"]     { text-align: end; }
+  :scope[text-align="justify"] { text-align: justify; }
+  /* Note: `<text-ui>` defaults to display:inline. text-align only takes
+     effect when text-ui itself is block-like (e.g. via wrapping or a
+     `display: block`/`grid` parent). The override-attribute pattern keeps
+     the inline default but lets consumers flip alignment with one attr. */
+
   /* ── Truncation (single-line) ── */
   :scope[truncate] {
     overflow: hidden;

package/components/text/text.d.ts

@@ -39,8 +39,12 @@ export type UITextVariant =
   | 'code';
 
 export class UIText extends UIElement {
+  /** Override the variant's color token. Permissive: unknown values are no-ops (variant color wins). Added v0.6.18 (FB-10). */
+  color: 'default' | 'subtle' | 'strong' | 'accent' | 'danger' | 'success' | 'warning';
   /** Multi-line clamp count (0 = no clamp) */
   lines: number;
+  /** Override the variant's font-size on the body ladder. Maps to --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values are no-ops (variant size wins). Added v0.6.18 (FB-10). */
+  size: 'sm' | 'md' | 'lg';
   /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
   strong: boolean;
   /** Display text content. The main payload field for Text components extracted from HTML. */
@@ -57,4 +61,6 @@ For semantic headings, wrap with native `<h1>`-`<h6>` OR add
 labels (eyebrows, kickers, captions, deck), the presentational default
 is correct. The §221k chooser guide in USAGE.md documents picker heuristics. */
   variant: UITextVariant;
+  /** Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10). */
+  weight: 'regular' | 'medium' | 'semibold' | 'bold';
 }

package/components/text/text.test.js

@@ -110,3 +110,93 @@ describe('text-ui §210 — variant enum vs CSS rule completeness', () => {
     }
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────
+// v0.6.18 (FB-10) — overlay attributes on top of `variant`
+// ─────────────────────────────────────────────────────────────────────
+
+describe('text-ui v0.6.18 — overlay props (FB-10)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  // ── Attribute reflection: each new prop reflects to the host ──
+  it.each([
+    ['size', 'sm'],
+    ['size', 'md'],
+    ['size', 'lg'],
+    ['color', 'subtle'],
+    ['color', 'strong'],
+    ['color', 'accent'],
+    ['color', 'danger'],
+    ['color', 'success'],
+    ['color', 'warning'],
+    ['color', 'default'],
+    ['weight', 'regular'],
+    ['weight', 'medium'],
+    ['weight', 'semibold'],
+    ['weight', 'bold'],
+    ['text-align', 'start'],
+    ['text-align', 'center'],
+    ['text-align', 'end'],
+    ['text-align', 'justify'],
+  ])('<text-ui %s="%s"> reflects the attribute', async (prop, value) => {
+    const el = mount(`<text-ui ${prop}="${value}">x</text-ui>`);
+    await tick();
+    expect(el.getAttribute(prop)).toBe(value);
+  });
+
+  // ── CSS-side: every documented value has a :scope[attr="value"] rule ──
+  const sizes = ['sm', 'md', 'lg'];
+  const colors = ['default', 'subtle', 'strong', 'accent', 'danger', 'success', 'warning'];
+  const weights = ['regular', 'medium', 'semibold', 'bold'];
+  const aligns = ['start', 'center', 'end', 'justify'];
+
+  it.each(sizes)('text.css ships :scope[size="%s"] rule', (s) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[size="${s}"\\]`));
+  });
+
+  it.each(colors)('text.css ships :scope[color="%s"] rule', (c) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[color="${c}"\\]`));
+  });
+
+  it.each(weights)('text.css ships :scope[weight="%s"] rule', (w) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[weight="${w}"\\]`));
+  });
+
+  it.each(aligns)('text.css ships :scope[text-align="%s"] rule', (a) => {
+    expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[text-align="${a}"\\]`));
+  });
+
+  // ── yaml-vs-impl consistency: every prop in the a2ui enum has a CSS rule ──
+  it('a2ui.json color enum matches CSS rules 1:1', () => {
+    const colorEnum = TEXT_A2UI.properties.color?.enum ?? [];
+    expect(colorEnum.sort()).toEqual([...colors].sort());
+    for (const c of colorEnum) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[color="${c}"\\]`));
+    }
+  });
+
+  it('a2ui.json size enum matches CSS rules 1:1', () => {
+    const sizeEnum = TEXT_A2UI.properties.size?.enum ?? [];
+    expect(sizeEnum.sort()).toEqual([...sizes].sort());
+    for (const s of sizeEnum) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[size="${s}"\\]`));
+    }
+  });
+
+  it('a2ui.json weight enum matches CSS rules 1:1', () => {
+    const weightEnum = TEXT_A2UI.properties.weight?.enum ?? [];
+    expect(weightEnum.sort()).toEqual([...weights].sort());
+    for (const w of weightEnum) {
+      expect(TEXT_CSS).toMatch(new RegExp(`:scope\\[weight="${w}"\\]`));
+    }
+  });
+
+  // ── Permissive fallback: unknown values are no-ops (no JS error) ──
+  it('unknown color value renders without throwing', async () => {
+    const el = mount('<text-ui color="banana">x</text-ui>');
+    await tick();
+    expect(el.getAttribute('color')).toBe('banana');
+    // The variant default wins; no CSS rule matches "banana". Test the
+    // shape: no thrown error during mount, no console.error.
+  });
+});

package/components/text/text.yaml

@@ -8,20 +8,56 @@ category: display
 version: 1
 description: Typography wrapper that applies role tokens. Supports truncation and line clamping.
 props:
+  color:
+    description: >-
+      Override the variant's color token. Permissive: unknown values are
+      no-ops (variant color wins). Added v0.6.18 (FB-10).
+    type: string
+    enum: ["default", "subtle", "strong", "accent", "danger", "success", "warning"]
+    default: ""
+    reflect: true
   lines:
     description: Multi-line clamp count (0 = no clamp)
     type: number
     default: 0
+  size:
+    description: >-
+      Override the variant's font-size on the body ladder. Maps to
+      --a-body-sm / --a-body-md / --a-body-lg. Permissive: unknown values
+      are no-ops (variant size wins). Added v0.6.18 (FB-10).
+    type: string
+    enum: ["sm", "md", "lg"]
+    default: ""
+    reflect: true
   strong:
     description: When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy.
     type: boolean
     default: false
     reflect: true
+  text-align:
+    description: >-
+      Override text alignment. Note: text-ui defaults to display:inline,
+      so this only takes effect when text-ui is block-like (wrapping or
+      parent display:block/grid). Added v0.6.18 (FB-10).
+    type: string
+    enum: ["start", "center", "end", "justify"]
+    default: ""
+    reflect: true
   truncate:
     description: Single-line truncation with ellipsis. Ignored when `lines` is set.
     type: boolean
     default: false
     reflect: true
+  weight:
+    description: >-
+      Override the variant's font-weight. Maps to --a-weight /
+      --a-weight-medium / --a-weight-semibold / --a-weight-bold.
+      Permissive: unknown values are no-ops (variant weight wins). Added
+      v0.6.18 (FB-10).
+    type: string
+    enum: ["regular", "medium", "semibold", "bold"]
+    default: ""
+    reflect: true
   textContent:
     description: Display text content. The main payload field for Text components extracted from HTML.
     type: string

package/components/textarea/textarea.a2ui.json

@@ -13,9 +13,24 @@
     }
   ],
   "properties": {
+    "required": {
+      "description": "Marks the field as required for form validation. Sets aria-required. Inherited from UIFormElement.",
+      "type": "boolean",
+      "default": false
+    },
     "component": {
       "const": "Textarea"
     },
+    "disabled": {
+      "description": "Disables interaction, removes contenteditable, and dims the control. Inherited from UIFormElement.",
+      "type": "boolean",
+      "default": false
+    },
+    "error": {
+      "description": "Validation error message. Set by constraint validation or manually via setInvalid(). Inherited from UIFormElement.",
+      "type": "string",
+      "default": ""
+    },
     "hint": {
       "description": "Help text displayed below the textarea. Hidden when error is set.",
       "type": "string",
@@ -36,6 +51,11 @@
       "type": "string",
       "default": ""
     },
+    "readonly": {
+      "description": "Prevents editing while keeping the surface focusable. Sets contenteditable=false. Inherited from UIFormElement.",
+      "type": "boolean",
+      "default": false
+    },
     "resize": {
       "description": "Resize behavior of the textarea.",
       "type": "string",
@@ -56,6 +76,11 @@
       "description": "§220 (v0.5.9, FEEDBACK-14 §3). Trailing-debounce on the `input`\nevent in milliseconds. When > 0, value mutates immediately + the UI\nstays responsive, but `input` dispatch is collapsed so only the\nfinal value in the throttle window emits. Useful for expensive\n`input`-driven computation (autosave preview, server-side\nautocomplete, large-doc reflow). `change` fires unthrottled on blur\n/ Enter; any pending `input` flushes before `change` so consumers\nsee input→input→…→input→change ordering. Default 0 preserves\nsynchronous emission.",
       "type": "number",
       "default": 0
+    },
+    "value": {
+      "description": "Current textarea value, synced with the contenteditable text surface. Inherited from UIFormElement.",
+      "type": "string",
+      "default": ""
     }
   },
   "required": [

package/components/textarea/textarea.yaml

@@ -8,6 +8,15 @@ category: layout
 version: 1
 description: Multiline text input. The host IS the interactive surface.
 props:
+  disabled:
+    description: Disables interaction, removes contenteditable, and dims the control. Inherited from UIFormElement.
+    type: boolean
+    default: false
+    reflect: true
+  error:
+    description: Validation error message. Set by constraint validation or manually via setInvalid(). Inherited from UIFormElement.
+    type: string
+    default: ""
   hint:
     description: Help text displayed below the textarea. Hidden when error is set.
     type: string
@@ -24,6 +33,16 @@ props:
     description: Placeholder text shown when textarea is empty.
     type: string
     default: ""
+  readonly:
+    description: Prevents editing while keeping the surface focusable. Sets contenteditable=false. Inherited from UIFormElement.
+    type: boolean
+    default: false
+    reflect: true
+  required:
+    description: Marks the field as required for form validation. Sets aria-required. Inherited from UIFormElement.
+    type: boolean
+    default: false
+    reflect: true
   resize:
     description: Resize behavior of the textarea.
     type: string
@@ -51,6 +70,10 @@ props:
     type: number
     default: 0
     reflect: true
+  value:
+    description: Current textarea value, synced with the contenteditable text surface. Inherited from UIFormElement.
+    type: string
+    default: ""
 events:
   change:
     description: Fired when the textarea loses focus after a value change.

package/components/toggle-scheme/class.js

@@ -272,11 +272,17 @@ export class UIToggleScheme extends UIElement {
   #writeTarget(scheme) {
     const t = this.#resolveTarget();
     t.style.setProperty('color-scheme', scheme);
+    // FEEDBACK-14: also write the [data-scheme] attribute. styles/themes.css
+    // selects on [data-scheme="dark"] etc., so consumer CSS patterned after
+    // themes.css needs the attribute — the inline color-scheme style alone
+    // satisfies AdiaUI's light-dark() tokens but not [data-scheme]-scoped CSS.
+    t.setAttribute('data-scheme', scheme);
   }
 
   #clearTargetOverride() {
     const t = this.#resolveTarget();
     t.style.removeProperty('color-scheme');
+    t.removeAttribute('data-scheme'); // FEEDBACK-14 — paired with #writeTarget
     if (this.persist) {
       try { localStorage.removeItem(`${this.storagePrefix}scheme`); } catch {}
     }

package/components/toggle-scheme/toggle-scheme.yaml

@@ -149,7 +149,13 @@ tokens:
   --toggle-scheme-icon-transition:
     description: Duration + easing for icon-color transition when scheme flips.
 a2ui:
-  rules: []
+  rules:
+    - >-
+      Place toggle-scheme-ui in the shell topbar's trailing action cluster
+      — slot="action" inside <admin-topbar slot="header"> of
+      <admin-content>. It is a persistent, app-wide preference control;
+      never put it in a sidebar footer / <admin-statusbar>, which hosts
+      user-account items only.
 anti_patterns: []
 examples:
   - name: header-action

package/core/element.js

@@ -262,6 +262,18 @@ export class UIElement extends HTMLElement {
 
   signal(v) { const s = signal(v); this.#as.push(s); return s; }
 
+  /**
+   * Get-or-create a structural part by slot name. Returns the existing
+   * `[slot="X"]` child when present, otherwise clones the part blueprint
+   * (`static parts`) and appends it. Re-stamped parts carry `_uiPart = true`
+   * so a part wiped by a host `innerHTML` mutation is detectable downstream.
+   *
+   * INVARIANT (FEEDBACK-31) — call `ensure()` from `render()`; never cache
+   * its result once in `connected()`. A consumer that replaces the host's
+   * children (`el.innerHTML = …`) wipes stamped parts; `render()` re-stamps
+   * them, but a reference captured once in `connected()` is left pointing at
+   * detached DOM. Part identity does not survive a host child-list wipe.
+   */
   ensure(slot) {
     for (const ch of this.children) {
       if (ch.getAttribute('slot') === slot) return ch;
@@ -272,6 +284,7 @@ export class UIElement extends HTMLElement {
     const blueprint = this.constructor._pp?.[slot];
     if (!blueprint) return null;
     const el = blueprint.cloneNode(true);
+    el._uiPart = true;
     this.appendChild(el);
     return el;
   }

package/css-module.d.ts

@@ -0,0 +1,6 @@
+// Ambient declaration so TypeScript (moduleResolution: bundler / node16)
+// can resolve CSS side-effect subpath imports — e.g.
+//   import '@adia-ai/web-components/css';
+// without a TS2882 "no type declarations for side-effect import" error.
+// See FEEDBACK-26.
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "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",
@@ -13,7 +13,10 @@
       "import": "./index.js",
       "default": "./index.js"
     },
-    "./css": "./index.css",
+    "./css": {
+      "types": "./css-module.d.ts",
+      "default": "./index.css"
+    },
     "./core": {
       "types": "./core/index.d.ts",
       "import": "./core/index.js",
@@ -39,9 +42,18 @@
       "import": "./components/*/class.js",
       "default": "./components/*/class.js"
     },
-    "./components/*.css": "./components/*/*.css",
-    "./components/*/*.css": "./components/*/*.css",
-    "./components/*/css/*.css": "./components/*/css/*.css",
+    "./components/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./components/*/*.css"
+    },
+    "./components/*/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./components/*/*.css"
+    },
+    "./components/*/css/*.css": {
+      "types": "./css-module.d.ts",
+      "default": "./components/*/css/*.css"
+    },
     "./styles/*": "./styles/*",
     "./traits": {
       "types": "./traits.d.ts",
@@ -77,6 +89,7 @@
     "index.js",
     "index.css",
     "index.d.ts",
+    "css-module.d.ts",
     "bin/",
     "custom-elements.json",
     "USAGE.md",