@adia-ai/web-components 0.8.39 → 0.8.41

package/components/toggle-group/toggle-group.yaml

@@ -4,26 +4,30 @@
 # ADR-0056 (gh#1303): <toggle-option-ui>'s current-state surface converges
 # onto <segment-ui>'s declared, reflected `[selected]` prop (see
 # toggle-option.yaml). This container sets that prop, keeping `value` as the
-# single source of truth. It also stamps the legacy `data-selected`
-# attribute on each option in parallel — DEPRECATED (undocumented external
-# CSS may target it); its removal rides the 0.9.0 breaking wave, not this
-# change.
+# single source of truth.
+#
+# DEPRECATED (gh#1369, #1363 C1, ADR-0057): superseded by
+# <segmented-ui multiple> + <segment-ui> — same comma-separated value
+# encoding, same corpus/catalog presence. Kept working as-is (no behavior
+# change, one-time console.warn on connect); status: deprecated per the
+# yaml deprecation contract rather than a literal JS-level delegation —
+# see PR body "Rejected alternatives" for why.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIToggleGroup
 tag: toggle-group-ui
-status: stable
+status: deprecated
 component: ToggleGroup
 category: navigation
 version: 1
 description: >-
-  Multi-select button group (unlike <segmented-ui> which is
-  single-select). Hosts <toggle-option-ui> children, each independently
-  toggleable; emits change events with the active value set. Use for
-  filter chips or feature flag clusters; for single-select option groups
-  use <segmented-ui> instead.
+  DEPRECATED (gh#1369) — use <segmented-ui multiple> + <segment-ui>
+  instead. Multi-select button group (unlike <segmented-ui> which is
+  single-select by default). Hosts <toggle-option-ui> children, each
+  independently toggleable; emits change events with the active value
+  set.
 props:
   single:
-    description: When true, restrict to one active option (single-select).
+    description: "When true, restrict to one active option (single-select) — clicking the already-selected option again CLEARS it (empty value), unlike a native radiogroup. Migration (gh#1369): [single]=true maps to plain <segmented-ui> (no [multiple]) — note segmented-ui's single-select never clears on re-click, it's standard radiogroup semantics; the default (false, multi-select) maps to <segmented-ui multiple>."
     type: boolean
     default: false
     reflect: false  # declarative presentational attribute — CSS/author-time read, non-reactive by design
@@ -81,15 +85,17 @@ tokens:
   --toggle-option-selected-fg:
     description: Text color when selected
 a2ui:
+  allowedChildren:
+    - ToggleOption
   rules:
+    - rule: 'DEPRECATED (gh#1369, #1363 C1) — generate <segmented-ui multiple> + <segment-ui> children instead when [single] is false/absent (the default, multi-select). When [single] is true, generate plain <segmented-ui> (no [multiple]) instead — single-select toggle-group maps to segmented''s own single-select mode, not the multiple axis; note segmented-ui single-select never clears on re-click (toggle-group[single] does). Same comma-separated value encoding either way; toggle-group is kept working for existing consumers but should not appear in new generated output.'
+      reason: 'Deprecation redirect — this is the primary rule for this component now.'
     - rule: 'Multi-select button cluster — hosts <toggle-option-ui> children, each independently toggleable.'
-      reason: 'Multi-select cluster contract.'
-    - rule: 'Different from <segmented-ui> (single-select) — toggle-group emits a SET of active values.'
-      reason: 'Selection model distinction.'
+      reason: 'Multi-select cluster contract (legacy).'
     - rule: 'Use for filter chips, multi-flag toggles, day-of-week pickers; for binary on/off use <switch-ui>.'
-      reason: 'Capacity guidance.'
+      reason: 'Capacity guidance (legacy).'
     - rule: 'Sets the child <toggle-option-ui>''s declared [selected] prop to reflect the group value (ADR-0056) — do not author [selected] directly in generated markup; author the group''s value instead.'
-      reason: 'Parent-managed declared state — group value stays the single source of truth.'
+      reason: 'Parent-managed declared state — group value stays the single source of truth (legacy).'
 anti_patterns: []
 examples:
   - name: basic-toggle-group

package/components/toggle-group/toggle-option.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ToggleOption.json",
   "title": "ToggleOption",
-  "description": "Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.",
+  "description": "DEPRECATED (gh#1369) — use `<segment-ui>` inside `<segmented-ui multiple>` instead. Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.",
   "type": "object",
   "allOf": [
     {
@@ -27,7 +27,7 @@
       "default": ""
     },
     "selected": {
-      "description": "Whether this option is currently selected. Managed by the parent\n<toggle-group-ui> container (ADR-0056) — don't set directly; the group's\n`value` is the single source of truth. Converges onto <segment-ui>'s\ndeclared reflected-prop mechanism (was previously a private\n`data-selected` stamp with no declared API surface).",
+      "description": "Whether this option is currently selected. Managed by the parent\n<toggle-group-ui> container (ADR-0056) — don't set directly; the group's\n`value` is the single source of truth. Converges onto <segment-ui>'s\ndeclared reflected-prop mechanism.",
       "type": "boolean",
       "default": false
     },
@@ -47,8 +47,11 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ToggleGroup"
+    ],
     "anti_patterns": [],
-    "category": "forms",
+    "category": "form",
     "composes": [],
     "events": {},
     "examples": [],
@@ -59,6 +62,7 @@
       "segmented-option"
     ],
     "name": "UIToggleOption",
+    "parts": {},
     "related": [
       "ToggleGroup",
       "Segment",
@@ -66,7 +70,7 @@
     ],
     "slots": {},
     "states": [],
-    "status": "stable",
+    "status": "deprecated",
     "synonyms": {
       "toggle-option": [
         "toggle-segment",

package/components/toggle-group/toggle-option.yaml

@@ -5,21 +5,22 @@
 # + is registered alongside UIToggleGroup.
 #
 # ADR-0056 (gh#1303): `selected` converges onto <segment-ui>'s declared,
-# parent-managed, reflected-prop convention. `<toggle-group-ui>` also stamps
-# the legacy `data-selected` attribute in parallel — DEPRECATED, kept only
-# because it was an undocumented hook external CSS may already target;
-# removal rides the 0.9.0 breaking wave (see toggle-group.yaml + CHANGELOG).
+# parent-managed, reflected-prop convention.
+#
+# DEPRECATED (gh#1369, #1363 C1, ADR-0057): superseded by <segment-ui>
+# (used as a child of <segmented-ui multiple>). Kept working as-is; see
+# toggle-group.yaml's header for the deprecation rationale.
 
 # Child component of <toggle-group-ui>. Surface only inside that parent.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIToggleOption
 tag: toggle-option-ui
-status: stable
+status: deprecated
 component: ToggleOption
-category: forms
+category: form
 version: 1
 description: |-
-  Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.
+  DEPRECATED (gh#1369) — use `<segment-ui>` inside `<segmented-ui multiple>` instead. Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.
 
 props:
   value:
@@ -43,8 +44,7 @@ props:
       Whether this option is currently selected. Managed by the parent
       <toggle-group-ui> container (ADR-0056) — don't set directly; the group's
       `value` is the single source of truth. Converges onto <segment-ui>'s
-      declared reflected-prop mechanism (was previously a private
-      `data-selected` stamp with no declared API surface).
+      declared reflected-prop mechanism.
     type: boolean
     default: false
     reflect: true
@@ -64,10 +64,12 @@ related:
   - Radio
 
 a2ui:
+  allowedParents:
+    - ToggleGroup
   rules:
+    - rule: 'DEPRECATED (gh#1369, #1363 C1) — generate <segment-ui> instead, as a child of <segmented-ui multiple> (or plain <segmented-ui>, no [multiple], if the parent toggle-group had [single] — see toggle-group.yaml). toggle-option is kept working for existing consumers but should not appear in new generated output.'
+      reason: 'Deprecation redirect — this is the primary rule for this component now.'
     - rule: 'Child of <toggle-group-ui> — one independently-toggleable button in a multi-select cluster.'
-      reason: 'Multi-select cluster contract.'
-    - rule: 'Different from <segment-ui> (which is single-select inside <segmented-ui>).'
-      reason: 'Selection model boundary.'
+      reason: 'Multi-select cluster contract (legacy).'
     - rule: 'Selected state exposed via its own declared [selected] reflected prop, set by the parent <toggle-group-ui> (ADR-0056) — mirrors <segment-ui>''s convention. Do not set [selected] directly; drive the group''s value instead.'
-      reason: 'Parent-managed declared state — group value stays the single source of truth.'
+      reason: 'Parent-managed declared state — group value stays the single source of truth (legacy).'

package/components/toggle-scheme/toggle-scheme.a2ui.json

@@ -121,7 +121,7 @@
   "unevaluatedProperties": false,
   "x-adiaui": {
     "anti_patterns": [],
-    "category": "control",
+    "category": "action",
     "composes": [
       "button-ui"
     ],
@@ -158,6 +158,7 @@
       "sun"
     ],
     "name": "UIToggleScheme",
+    "parts": {},
     "related": [
       "Button",
       "Switch"

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

@@ -4,7 +4,7 @@ name: UIToggleScheme
 tag: toggle-scheme-ui
 status: stable
 component: ToggleScheme
-category: control
+category: action
 version: 1
 description: >-
   Icon-button primitive that toggles `color-scheme` between light and dark on

package/components/toolbar/toolbar-group.a2ui.json

@@ -34,6 +34,7 @@
       "toolbar-cluster"
     ],
     "name": "UIToolbarGroup",
+    "parts": {},
     "related": [
       "Toolbar",
       "Button",

package/components/toolbar/toolbar.a2ui.json

@@ -67,6 +67,7 @@
       "actions"
     ],
     "name": "UIToolbar",
+    "parts": {},
     "related": [
       "button",
       "divider"

package/components/toolbar/toolbar.class.js

@@ -263,6 +263,9 @@ export class UIToolbar extends UIElement {
 
   #queueReflow() {
     if (this.#reflowQueued) return;
+    // No rAF (SSR shim — gh#1436's render sweep) → no layout to measure
+    // overflow against; every item stays inline and the client reflows.
+    if (typeof requestAnimationFrame !== 'function') return;
     this.#reflowQueued = true;
     this.#reflowRaf = requestAnimationFrame(() => {
       this.#reflowRaf = null;

package/components/tooltip/tooltip.a2ui.json

@@ -95,6 +95,7 @@
       "popover"
     ],
     "name": "UITooltip",
+    "parts": {},
     "related": [
       "button"
     ],

package/components/tooltip/tooltip.css

@@ -30,7 +30,7 @@
   color: var(--md-sys-color-neutral-background);
   font-family: var(--a-font-family);
   font-size: var(--a-ui-sm);
-  line-height: 1.4;
+  line-height: var(--a-font-leading-normal);
   border: none;
   border-radius: var(--a-radius-full);
   box-shadow: var(--a-shadow-sm);

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.css

@@ -112,14 +112,14 @@
 [data-tour-popover] [data-tour-title] {
   margin: 0;
   font-size: var(--a-text-lg);
-  font-weight: 600;
+  font-weight: var(--a-weight-semibold);
 }
 
 [data-tour-popover] [data-tour-body] {
   margin: 0 0 var(--a-space-4);
   font-size: var(--a-ui-size);
   color: var(--md-sys-color-neutral-on-surface);
-  line-height: 1.5;
+  line-height: var(--a-font-leading-relaxed);
 }
 
 [data-tour-popover] [data-tour-footer] {

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.css

@@ -141,7 +141,7 @@
     background: var(--tree-badge-bg, transparent);
     padding: 0 var(--tree-badge-px, var(--a-space-1));
     border-radius: var(--tree-badge-radius, var(--a-radius-sm));
-    line-height: 1;
+    line-height: var(--a-font-leading-none);
     font-variant-numeric: tabular-nums;
   }
   [slot="badge"]:empty {

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"
     ],