@adia-ai/web-components 0.8.40 → 0.8.42

package/components/tour/tour-step.a2ui.json

@@ -51,6 +51,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "Tour"
+    ],
     "anti_patterns": [
       {
         "fix": "<tour-step target=\"#dashboard\">",
@@ -68,6 +71,7 @@
       "guided-step"
     ],
     "name": "UITourStep",
+    "parts": {},
     "related": [
       "tour"
     ],

package/components/tour/tour-step.yaml

@@ -60,6 +60,8 @@ states: []
 traits: []
 tokens: {}
 a2ui:
+  allowedParents:
+    - Tour
   rules:
     - rule: 'Single step inside <tour-ui>. Declares target (CSS selector) + title + body content.'
       reason: 'Data carrier for tour-ui.'

package/components/tour/tour.a2ui.json

@@ -42,6 +42,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "TourStep"
+    ],
     "anti_patterns": [
       {
         "fix": "<tour-ui><tour-step target=\"#dashboard\" title=\"Dashboard\">Tour the dashboard…</tour-step>…</tour-ui>",
@@ -90,6 +93,7 @@
       "feature-introduction"
     ],
     "name": "UITour",
+    "parts": {},
     "related": [
       "tooltip",
       "popover",

package/components/tour/tour.yaml

@@ -110,6 +110,8 @@ tokens:
     description: Maximum width of the popover.
     default: 22rem
 a2ui:
+  allowedChildren:
+    - TourStep
   rules:
     - rule: 'Use tour-ui for spotlight-driven product tours / walkthroughs — sequence of steps each targeting a CSS-selector-resolved element.'
       reason: 'Primary use case — guided feature introduction.'

package/components/tree/tree-item.a2ui.json

@@ -46,6 +46,10 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "Tree",
+      "TreeItem"
+    ],
     "anti_patterns": [],
     "category": "data",
     "composes": [],
@@ -58,6 +62,7 @@
       "hierarchy-item"
     ],
     "name": "UITreeItem",
+    "parts": {},
     "related": [
       "Tree",
       "List",

package/components/tree/tree-item.yaml

@@ -61,6 +61,9 @@ slots:
       rather than wrapping below it.
 
 a2ui:
+  allowedParents:
+    - Tree
+    - TreeItem
   rules:
     - >-
       <tree-item-ui> MUST be a direct or nested descendant of

package/components/tree/tree.a2ui.json

@@ -22,6 +22,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "TreeItem"
+    ],
     "anti_patterns": [],
     "category": "data",
     "composes": [
@@ -70,6 +73,7 @@
       "folder"
     ],
     "name": "UITree",
+    "parts": {},
     "related": [
       "TreeItem",
       "Nav",

package/components/tree/tree.class.js

@@ -33,6 +33,7 @@
  */
 
 import { UIElement } from '../../core/element.js';
+import { isElement } from '../../core/dom.js';
 
 export class UITree extends UIElement {
   // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
@@ -91,7 +92,7 @@ export class UITree extends UIElement {
    */
   #resolveItem(arg) {
     if (!arg) return null;
-    if (arg instanceof Element) {
+    if (isElement(arg)) {
       return arg.matches?.('tree-item-ui') ? arg : null;
     }
     if (typeof arg === 'string') {

package/components/tree/tree.yaml

@@ -98,6 +98,8 @@ tokens:
 requiredIcons:
   - caret-right
 a2ui:
+  allowedChildren:
+    - TreeItem
   rules:
     - >-
       Use <tree-ui> only when data is hierarchical with arbitrary

package/components/upload/upload.a2ui.json

@@ -23,6 +23,11 @@
       "type": "string",
       "default": ""
     },
+    "compact": {
+      "description": "Icon-only trigger mode (sanctioned mode attribute, gh#1493) — collapses the dropzone to a compact icon button. The prompt text and visible label hide; [label] feeds the trigger's aria-label (\"Upload files\" when unset).",
+      "type": "boolean",
+      "default": false
+    },
     "component": {
       "const": "Upload"
     },
@@ -90,9 +95,11 @@
       "import",
       "transfer",
       "file-manager",
-      "files"
+      "files",
+      "compact"
     ],
     "name": "UIUpload",
+    "parts": {},
     "related": [
       "progress",
       "button",

package/components/upload/upload.class.js

@@ -21,11 +21,20 @@ import { UIFormElement } from '../../core/form.js';
 
 export class UIUpload extends UIFormElement {
   static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per upload.yaml
+  // Phosphor icons this primitive auto-stamps (without consumer markup).
+  // Aggregated by installIconLoadersForRegistered() across all defined
+  // elements. Audited by check-required-icons.mjs.
+  static requiredIcons = ['upload-simple'];
+
   static properties = {
     ...UIFormElement.properties,
     label:    { type: String,  default: '', reflect: true },
     accept:   { type: String,  default: '', reflect: true },
     multiple: { type: Boolean, default: false, reflect: true },
+    /* gh#1493 — sanctioned mode attribute (component-token-contract.md
+       § Variants vs modes): icon-only trigger. Collapses the dropzone to a
+       compact icon button; [label] feeds the trigger's aria-label. */
+    compact:  { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;
@@ -38,7 +47,7 @@ export class UIUpload extends UIFormElement {
 
     if (!this.querySelector('[data-dropzone]')) {
       this.innerHTML = `
-        <div data-dropzone tabindex="0" role="button">Drop files here or click to browse</div>
+        <div data-dropzone tabindex="0" role="button"><icon-ui data-upload-icon name="upload-simple"></icon-ui><span data-upload-text>Drop files here or click to browse</span></div>
         <span hint="${this.hint || ''}"></span>
         <div data-filelist></div>
       `;
@@ -58,6 +67,15 @@ export class UIUpload extends UIFormElement {
     const filelist = this.querySelector('[data-filelist]');
     if (!this.#dropzoneEl || !filelist) return;
 
+    // Compact trigger a11y (gh#1493) — the icon-only surface has no visible
+    // text, so it needs an accessible name. [label] feeds it; the visible
+    // ::before label is CSS-hidden in [compact], so this is a move, not a dupe.
+    if (this.compact) {
+      this.#dropzoneEl.setAttribute('aria-label', this.label || 'Upload files');
+    } else {
+      this.#dropzoneEl.removeAttribute('aria-label');
+    }
+
     // Update hint attribute
     const hintEl = this.querySelector('span[hint]');
     if (hintEl && this.hint) hintEl.setAttribute('hint', this.hint);
@@ -77,16 +95,28 @@ export class UIUpload extends UIFormElement {
 
   // ── File picking ──
 
-  #onClickZone = () => {
+  /**
+   * Programmatically open the file picker — the public trigger API
+   * (gh#1493). Equivalent to activating the dropzone, without reaching
+   * into the internal `[data-dropzone]` part. No-ops when [disabled].
+   * Note: browsers gate the native picker on transient user activation,
+   * so call this from within a user-gesture handler.
+   * @returns {Promise<void>} resolves after selection commits or the
+   *   user cancels.
+   */
+  async open() {
     if (this.disabled) return;
-    this.#pickFiles();
+    await this.#pickFiles();
+  }
+
+  #onClickZone = () => {
+    this.open();
   };
 
   #onKeyZone = (e) => {
-    if (this.disabled) return;
     if (e.key === 'Enter' || e.key === ' ') {
       e.preventDefault();
-      this.#pickFiles();
+      this.open();
     }
   };
 

package/components/upload/upload.css

@@ -23,6 +23,7 @@
 
     /* ── Spacing ── */
     --upload-dropzone-pad:     var(--a-space-6);
+    --upload-compact-pad:      var(--a-space-2);
 
     /* ── Transitions ── */
     --upload-duration:         var(--a-duration-fast);
@@ -82,6 +83,33 @@
     background: var(--upload-bg-dragover);
   }
 
+  /* Stamped leading icon — hidden in the default (text) dropzone; it IS
+     the surface in [compact] icon-only mode. */
+  [data-upload-icon] {
+    display: none;
+  }
+
+  /* ── Mode: [compact] — icon-only trigger (gh#1493) ──
+     Sanctioned mode attribute; see component-token-contract.md
+     § Variants vs modes. Host shrink-wraps instead of filling the row,
+     the dropzone collapses to icon padding, the prompt text and ::before
+     label hide (label feeds the trigger's aria-label from class.js). */
+  :scope[compact] {
+    display: inline-flex;
+  }
+  :scope[compact]::before {
+    display: none;
+  }
+  :scope[compact] [data-dropzone] {
+    padding: var(--upload-compact-pad);
+  }
+  :scope[compact] [data-upload-icon] {
+    display: inline-flex;
+  }
+  :scope[compact] [data-upload-text] {
+    display: none;
+  }
+
   /* Hint via ::after on span */
   span[hint]::after {
     content: attr(hint);

package/components/upload/upload.d.ts

@@ -23,6 +23,22 @@ export class UIUpload extends UIFormElement {
   accept: string;
   /** §207 (v0.5.7): allow multi-file selection. */
   multiple: boolean;
+  /**
+   * gh#1493: icon-only compact trigger mode (sanctioned mode attribute).
+   * Collapses the dropzone to a compact icon button; `label` feeds the
+   * trigger's `aria-label` (`"Upload files"` when unset).
+   */
+  compact: boolean;
+
+  /**
+   * gh#1493: programmatically open the file picker — the public trigger
+   * API. Equivalent to activating the dropzone, without reaching into the
+   * internal `[data-dropzone]` part. No-ops when `disabled`. Browsers gate
+   * the native picker on transient user activation, so call from within a
+   * user-gesture handler. Resolves after selection commits or the user
+   * cancels.
+   */
+  open(): Promise<void>;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,

package/components/upload/upload.yaml

@@ -40,6 +40,15 @@ props:
     description: Allows selecting multiple files
     type: boolean
     default: false
+  compact:
+    description: >-
+      Icon-only trigger mode (sanctioned mode attribute, gh#1493) —
+      collapses the dropzone to a compact icon button. The prompt text and
+      visible label hide; [label] feeds the trigger's aria-label
+      ("Upload files" when unset).
+    type: boolean
+    default: false
+    reflect: true
   value:
     description: Current value
     type: string
@@ -48,13 +57,19 @@ events:
   change:
     description: Fired when files are selected via click or drag-and-drop
 slots: {}
-# Authoring note (2026-05-26): the previous slots block declared
-# dropzone/filelist/hint/input/label, but class.js stamps these as
-# `<div data-dropzone>` / `<div data-filelist>` / `<span hint="…">` etc.
-# — NOT as `[slot="X"]` anchors. `<upload-ui><div slot="dropzone">…`
-# wouldn't render (innerHTML stamp wipes child). Hint + label are
-# already declared as props above (text-only); for an avatar / icon
-# / form-element wrapper, compose <field-ui label> around the upload.
+# Authoring note (2026-05-26, refreshed 2026-08-17 gh#1493): the previous
+# slots block declared dropzone/filelist/hint/input/label, but class.js
+# stamps these as `<div data-dropzone>` / `<div data-filelist>` /
+# `<span hint="…">` etc. — template-owned anatomy (ADR-0067 `parts:`
+# semantics), NOT `[slot="X"]` insertion points. `<upload-ui><div
+# slot="dropzone">…` wouldn't render (innerHTML stamp wipes child). They
+# stay undeclared here because they are data-attr anatomy, not slot attrs
+# (the audit-slot-vocab-vs-css vocabulary is slot-attr based). Consumers
+# must NOT reach into `[data-dropzone]` to trigger the picker — that is
+# what the public `.open()` method and the [compact] trigger mode are for
+# (gh#1493). Hint + label are declared as props above (text-only); for an
+# avatar / icon / form-element wrapper, compose <field-ui label> around
+# the upload.
 states:
   - name: idle
     description: Default, ready for interaction.
@@ -63,12 +78,16 @@ states:
     attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - upload-simple
 a2ui:
   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: 'compact renders an icon-only trigger (no drop-zone chrome) — use in toolbars/dense rows; label becomes the trigger''s aria-label. Programmatic triggering goes through the public .open() method, never the internal [data-dropzone] part.'
+      reason: 'Public trigger API (gh#1493); internal anatomy is not a contract.'
     - 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: []
@@ -257,6 +276,7 @@ keywords:
   - transfer
   - file-manager
   - files
+  - compact
 synonyms:
   attach:
     - file

package/components/visually-hidden/visually-hidden.a2ui.json

@@ -47,6 +47,7 @@
       "accessibility"
     ],
     "name": "UIVisuallyHidden",
+    "parts": {},
     "related": [
       "text"
     ],

package/core/dom.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Structural node/element guards — `nodeType`-based, so they hold under DOM
+ * shims (linkedom via custom-elements-ssr) where `Node`/`Element` are not
+ * globals and a bare `instanceof` throws (gh#1436).
+ */
+
+/** True for any DOM node (anything with a numeric `nodeType`). */
+export declare function isNode(v: unknown): v is Node;
+
+/** True for ELEMENT_NODE (nodeType 1) only. */
+export declare function isElement(v: unknown): v is Element;

package/core/dom.js

@@ -0,0 +1,34 @@
+/**
+ * AdiaUI DOM guards — structural node/element tests that survive DOM shims.
+ *
+ * Why (gh#1436): under SSR shims such as linkedom via `custom-elements-ssr`,
+ * only `HTMLElement` is installed as a global — `Node`, `Element`, `Text`,
+ * `DocumentFragment` are not — so a bare `v instanceof Node` is a
+ * `ReferenceError`, not `false`. Testing the wire shape (`nodeType`) instead
+ * of the constructor identity works in browsers, happy-dom, and linkedom
+ * alike, and also matches nodes from another realm (iframe, DOMParser
+ * document) that `instanceof` against the main-window constructor would
+ * reject. Same failure shape as
+ * `.claude/skills/ssr-compatibility/references/guard-patterns.md` §1.
+ *
+ * Use these anywhere the framework accepts "a node or something else"
+ * (renderer return values, `ref` arguments, event targets) instead of a bare
+ * `instanceof <DOM constructor>`.
+ */
+
+/**
+ * @param {unknown} v
+ * @returns {v is Node}
+ */
+export function isNode(v) {
+  return v != null && typeof v === 'object' && typeof (/** @type {any} */ (v).nodeType) === 'number';
+}
+
+/**
+ * ELEMENT_NODE (1) only — excludes text, comment, fragment and document nodes.
+ * @param {unknown} v
+ * @returns {v is Element}
+ */
+export function isElement(v) {
+  return isNode(v) && v.nodeType === 1;
+}

package/core/form.js

@@ -26,6 +26,13 @@
  *   data-msg-pattern="Invalid format"
  *   data-msg-minlength="Too short"
  *   data-msg-maxlength="Too long"
+ * Numeric-constraint siblings read by individual subclasses (input, tags-input):
+ *   data-msg-min / data-msg-max / data-msg-bad-input
+ * This whole `data-msg-*` family is deliberately EXEMPT from yaml `states:`/
+ * `props:` declaration — component-side config read by this shared mixin
+ * across 7+ consuming components, not a per-component state or prop.
+ * Disposition + rationale: primitive-authoring's yaml-contract.md
+ * (gh#1332/#1464, ADR-0060 §Decision 3).
  *
  * Manual control:
  *   el.validate()          → returns boolean, surfaces error

package/core/icons.js

@@ -306,6 +306,11 @@ function discoverRequiredIcons() {
     'agent-trace-ui',
     'calendar-picker-ui',
     'color-picker-ui',
+    // ADR-0063 (gh#1563) — color-picker-ui's real implementation moved to
+    // color-area-ui (the new canonical tag); color-picker-ui is now a thin
+    // deprecated alias. Both need to resolve here since either tag may be
+    // the one actually defined+used on a given page.
+    'color-area-ui',
     'command-ui',
     'pane-ui',
     'select-ui',

package/core/index.d.ts

@@ -15,3 +15,4 @@ export * from './register.js';
 // explicit form so the type barrel matches the runtime exactly.
 export { streams, whenStream } from './data-stream.js';
 export type { StreamEntry } from './data-stream.js';
+export * from './dom.js';

package/core/index.js

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

package/core/responsive.js

@@ -49,9 +49,20 @@ const BP_VALS          = /** @type {number[]} */ (Object.values(BREAKPOINTS));
 
 // ─── Active-breakpoint signal ─────────────────────────────────────────────────
 
+// Feature-detect, never environment-detect (gh#1430): SSR DOM shims
+// (linkedom under custom-elements-ssr) define `window` as an object with
+// no layout engine — `innerWidth` is undefined and `matchMedia` is absent —
+// so `typeof window !== 'undefined'` passes there and the browser-only
+// call throws at module import, taking every importer (row/col/grid/
+// block/text) off the server. Same guard shape as
+// `.claude/skills/ssr-compatibility/references/guard-patterns.md` §1.
+
 function _detect() {
-  if (typeof window === 'undefined') return 'lg'; // SSR / non-browser fallback
-  const w = window.innerWidth;
+  // A real viewport reports a numeric width; SSR / DOM shims / non-browser
+  // runtimes don't → the widest-common fallback so server output isn't a
+  // mobile layout.
+  const w = typeof window !== 'undefined' ? window.innerWidth : undefined;
+  if (typeof w !== 'number') return 'lg';
   for (let i = BP_NAMES.length - 1; i >= 0; i--) {
     if (w >= BP_VALS[i]) return BP_NAMES[i];
   }
@@ -67,8 +78,9 @@ function _detect() {
  */
 export const breakpoint = signal(_detect());
 
-// Wire matchMedia listeners once (browser only, skipped in SSR / tests)
-if (typeof window !== 'undefined') {
+// Wire matchMedia listeners once — only where the API exists (browser).
+// Skipped under SSR shims and non-DOM tests; nothing to observe there.
+if (typeof window !== 'undefined' && typeof window.matchMedia === 'function') {
   // 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++) {

package/core/template.js

@@ -11,6 +11,7 @@
  */
 
 import { effect, isSignal } from './signals.js';
+import { isNode } from './dom.js';
 
 const [PART, KEY_MAP] = [Symbol(), Symbol()];
 
@@ -467,7 +468,7 @@ function applyValue(p, v) {
           c.appendChild(document.createTextNode(item ?? ''));
         }
       }
-    } else if (v instanceof Node) {
+    } else if (isNode(v)) {
       p.n.replaceWith(v);
       p.n = v;
     } else if (p.n[PART]) {