@adia-ai/web-components 0.6.37 → 0.6.38

package/components/inline-edit/inline-edit.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `<inline-edit-ui>` — Click-to-edit text in place. Renders as static text until clicked /
+focused + Enter, then becomes editable. Enter or blur commits; Escape
+cancels and restores the original value. Form-participating.
+
+Use for editable titles, breadcrumb labels, table-cell text fields,
+draft document names — any case where a user expects to edit text
+without opening a separate dialog or input. Distinct from `<input-ui>`
+(always-editable chrome) and from `<field-ui>` (stacked label + input
+composition). inline-edit reads as text in static state.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/inline-edit
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type InlineEditCancelEvent = CustomEvent<unknown>;
+export type InlineEditChangeEvent = CustomEvent<unknown>;
+export type InlineEditEditEndEvent = CustomEvent<unknown>;
+export type InlineEditEditStartEvent = CustomEvent<unknown>;
+
+export class UIInlineEdit extends UIElement {
+  /** When to commit pending edits. `blur` (default) — saves on focusout
+or Enter. `enter` — Enter saves, blur cancels (returns to original).
+`manual` — only programmatic `commitEdit()` saves.
+ */
+  commit: 'blur' | 'enter' | 'manual';
+  /** Reflected state — `true` when the element is actively being edited.
+Toggles automatically on click / Enter / blur / Escape; rarely set
+by consumers. Listen to `edit-start` / `edit-end` events instead.
+ */
+  editing: boolean;
+  /** Hint text shown when the value is empty (inline-edit reads this in the static state). */
+  placeholder: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIInlineEdit, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'cancel', listener: (ev: InlineEditCancelEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: InlineEditChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'edit-end', listener: (ev: InlineEditEditEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'edit-start', listener: (ev: InlineEditEditStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/inline-edit/inline-edit.js

@@ -0,0 +1,12 @@
+/**
+ * `<inline-edit-ui>` — auto-registers the tag on import.
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIInlineEdit } from './inline-edit.class.js';
+
+defineIfFree('inline-edit-ui', UIInlineEdit);
+
+export { UIInlineEdit };

package/components/inline-edit/inline-edit.yaml

@@ -0,0 +1,125 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIInlineEdit
+tag: inline-edit-ui
+status: stable
+component: InlineEdit
+category: form
+version: 1
+description: |
+  Click-to-edit text in place. Renders as static text until clicked /
+  focused + Enter, then becomes editable. Enter or blur commits; Escape
+  cancels and restores the original value. Form-participating.
+
+  Use for editable titles, breadcrumb labels, table-cell text fields,
+  draft document names — any case where a user expects to edit text
+  without opening a separate dialog or input. Distinct from `<input-ui>`
+  (always-editable chrome) and from `<field-ui>` (stacked label + input
+  composition). inline-edit reads as text in static state.
+props:
+  placeholder:
+    description: Hint text shown when the value is empty (inline-edit reads this in the static state).
+    type: string
+    default: Click to edit
+    reflect: true
+  editing:
+    description: |
+      Reflected state — `true` when the element is actively being edited.
+      Toggles automatically on click / Enter / blur / Escape; rarely set
+      by consumers. Listen to `edit-start` / `edit-end` events instead.
+    type: boolean
+    default: false
+    reflect: true
+  commit:
+    description: |
+      When to commit pending edits. `blur` (default) — saves on focusout
+      or Enter. `enter` — Enter saves, blur cancels (returns to original).
+      `manual` — only programmatic `commitEdit()` saves.
+    type: string
+    default: blur
+    enum:
+      - blur
+      - enter
+      - manual
+    reflect: true
+events:
+  change:
+    description: 'Fired after a successful commit. detail = { value, oldValue }. Bubbles.'
+  cancel:
+    description: 'Fired when Escape (or blur with commit=enter) restores the original. Bubbles.'
+  edit-start:
+    description: 'Fired when entering edit mode. Bubbles.'
+  edit-end:
+    description: 'Fired when leaving edit mode. detail = { committed: boolean }. Bubbles.'
+slots: {}
+states:
+  - name: idle
+    description: Static — text reads as plain text with a hover hint.
+  - name: hover
+    description: Hover affordance — subtle background tint signals editability.
+  - name: editing
+    description: contenteditable — host is the input surface; outline + caret.
+  - name: empty
+    description: Value is empty and not editing — placeholder text renders.
+  - name: disabled
+    description: Locked; click + keyboard activation are no-ops.
+traits: []
+tokens:
+  --inline-edit-bg-hover:
+    description: Background tint on hover (idle state).
+    default: var(--a-bg-muted)
+  --inline-edit-bg-edit:
+    description: Background while editing.
+    default: var(--a-bg)
+  --inline-edit-outline:
+    description: Outline color in the editing state.
+    default: var(--a-accent-strong)
+  --inline-edit-placeholder:
+    description: Placeholder text color in empty-static state.
+    default: var(--a-fg-subtle)
+  --inline-edit-px:
+    description: Horizontal padding (inner gutter so hover tint reads as a pill, not a flush block).
+    default: var(--a-space-1)
+  --inline-edit-py:
+    description: Vertical padding.
+    default: var(--a-space-0-5)
+  --inline-edit-radius:
+    description: Border-radius for the hover / editing chrome.
+    default: var(--a-radius-sm)
+a2ui:
+  rules:
+    - rule: 'Use inline-edit-ui for click-to-edit titles, draft names, table-cell text, breadcrumb labels — anywhere the user expects to edit text without opening a dialog.'
+      reason: 'Primary use case — inline rename/edit.'
+    - rule: 'inline-edit-ui IS form-participating (extends UIFormElement). Pair with a hidden <form> + name="..." to submit edits as a field.'
+      reason: 'Form participation contract.'
+    - rule: 'Distinct from <input-ui> (always shows input chrome) and from <field-ui> (stacked label + input composition). inline-edit reads as text in the static state.'
+      reason: 'Sibling-component boundary.'
+    - rule: 'Listen to `change` event (detail.value, detail.oldValue) for commit; `cancel` for Escape. Default commit=blur saves on focusout + Enter.'
+      reason: 'Event-handling contract.'
+anti_patterns:
+  - wrong: '<input-ui value="Title" name="title" variant="ghost">'
+    why: 'Ghost variant still renders input chrome (border on focus). Looks like a control, not text.'
+    fix: '<inline-edit-ui value="Title" name="title"> — reads as text in static state; chrome only appears while editing.'
+  - wrong: '<text-ui contenteditable>Title</text-ui>'
+    why: 'No state machine — no commit/cancel semantics, no form participation, no a11y wiring.'
+    fix: '<inline-edit-ui value="Title">'
+examples:
+  - name: editable-title
+    description: A draft document title that becomes editable on click.
+    a2ui: |
+      [{ "id": "title", "component": "InlineEdit", "value": "Untitled draft" }]
+keywords:
+  - inline-edit
+  - editable
+  - click-to-edit
+  - rename
+  - edit-in-place
+synonyms:
+  inline-edit:
+    - editable
+    - click-to-edit
+    - edit-in-place
+    - rename-in-place
+related:
+  - input
+  - field
+  - text

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

@@ -53,7 +53,14 @@
       "MenuItem",
       "TreeItem"
     ],
-    "slots": {},
+    "slots": {
+      "description": {
+        "description": "Override slot for richer description markup than the plain [description] attribute string (inline links, code spans, multiple lines). Renders beneath the primary text at body-subtle typography."
+      },
+      "icon": {
+        "description": "Override the [icon] glyph with a custom slotted element (e.g. a colored <icon-ui>, an image, or an avatar-ui). Mutually exclusive with the [icon] attribute — slot child wins if both are present."
+      }
+    },
     "states": [],
     "status": "stable",
     "synonyms": {

package/components/list/list-item.yaml

@@ -29,6 +29,18 @@ props:
     description: Secondary line below the primary text. Subtle color.
     type: string
 
+slots:
+  icon:
+    description: >-
+      Override the [icon] glyph with a custom slotted element (e.g. a colored
+      <icon-ui>, an image, or an avatar-ui). Mutually exclusive with the
+      [icon] attribute — slot child wins if both are present.
+  description:
+    description: >-
+      Override slot for richer description markup than the plain [description]
+      attribute string (inline links, code spans, multiple lines). Renders
+      beneath the primary text at body-subtle typography.
+
 keywords:
   - list-item
   - list-row

package/components/list/list.css

@@ -126,19 +126,27 @@
     min-height: var(--a-space-6);
   }
 
-  :scope > [slot="icon"] {
+  /* Slot positioning uses descendant (not direct-child >) because the
+     template engine wraps `${...}` conditional renders in
+     <span style="display:contents"> housekeeping nodes — so slot="…"
+     children land as grandchildren in template-rendered hosts.
+     display:contents makes the wrapper layout-transparent (the grid
+     places the inner element), but CSS selectors still see the wrapper
+     as a real node. Descendant selectors handle both shapes (direct
+     authored children + template-engine-wrapped conditionals). */
+  :scope [slot="icon"] {
     grid-column: 1;
     grid-row: 1 / -1;
     align-self: center;
     color: var(--list-item-icon-color);
   }
 
-  :scope > [slot="text"] {
+  :scope [slot="text"] {
     grid-column: 2;
     grid-row: 1;
   }
 
-  :scope > [slot="description"] {
+  :scope [slot="description"] {
     grid-column: 2;
     grid-row: 2;
     color: var(--list-item-desc-color);
@@ -146,11 +154,33 @@
     line-height: 1.3;
   }
 
+  /* When a [slot="action"] child is present, the grid becomes 3-column:
+     icon | content | action. The :has() selector promotes the template
+     only when an action exists, so 2-column layouts stay unaffected.
+     Action is right-aligned + vertically centered (spans both content rows).
+     Used by onboarding-checklist-ui item rows + any consumer that needs an
+     end-aligned action button on a list-item row.
+     NOTE: NOT using `> [slot="action"]` (direct-child) — the template
+     engine wraps conditional `${...}` renders in <span style="display:
+     contents"> housekeeping nodes, so slot="action" lands as a grandchild
+     in template-rendered hosts. display:contents makes the wrapper a
+     transparent grid pass-through at layout time, but CSS selectors still
+     see it as a node. Descendant combinator handles both shapes. */
+  :scope:has([slot="action"]) {
+    grid-template-columns: auto 1fr auto;
+  }
+  :scope [slot="action"] {
+    grid-column: 3;
+    grid-row: 1 / -1;
+    align-self: center;
+    justify-self: end;
+  }
+
   /* Custom-content escape hatch — consumer authored a [slot="content"]
      child, the auto-stamp early-returned, and the consumer owns the
      full body. Span all columns so the consumer's layout isn't boxed
      into the content column. */
-  :scope > [slot="content"] {
+  :scope [slot="content"] {
     grid-column: 1 / -1;
   }
 
@@ -167,8 +197,8 @@
     box-shadow: inset 2px 0 0 var(--a-accent-strong);
   }
 
-  :scope[data-active] > [slot="icon"],
-  :scope[data-active] > [slot="description"] {
+  :scope[data-active] [slot="icon"],
+  :scope[data-active] [slot="description"] {
     color: var(--a-accent-strong);
   }
 }

package/components/mark/mark.a2ui.json

@@ -0,0 +1,109 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Mark.json",
+  "title": "Mark",
+  "description": "Highlighted inline text — token-driven theme-aware wrapper around the\nnative `<mark>` semantic. Use for search-result match highlighting,\ndiff additions in prose, \"new since last visit\" emphasis, and any\ninline text that needs a visual rail without changing its weight.\n\nDistinct from `<text-ui strong>` (semantic emphasis via weight) and\nfrom `<tag-ui>` (block-shaped pill chrome). mark-ui keeps the inline\ntext flow intact — same line-height, same baseline — just paints a\nbackground highlight behind the matched span.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "Mark"
+    },
+    "variant": {
+      "description": "Highlight color variant. Default `warning` is the conventional yellow-marker tone.",
+      "type": "string",
+      "enum": [
+        "warning",
+        "info",
+        "success",
+        "danger",
+        "muted"
+      ],
+      "default": "warning"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<mark-ui>matched</mark-ui> — same semantic role but theme-aware.",
+        "why": "Native <mark> uses UA default (yellow-on-white) that doesn't adapt to theme — invisible in dark mode + jarring in light mode.",
+        "wrong": "<mark>matched</mark>"
+      }
+    ],
+    "category": "typography",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Highlight the search query within a result title.",
+        "a2ui": "[\n  { \"id\": \"row\", \"component\": \"Row\", \"children\": [\"pre\", \"mk\", \"post\"] },\n  { \"id\": \"pre\", \"component\": \"Text\", \"textContent\": \"Quarterly \" },\n  { \"id\": \"mk\",  \"component\": \"Mark\", \"textContent\": \"revenue\" },\n  { \"id\": \"post\", \"component\": \"Text\", \"textContent\": \" report — Q4 2025\" }\n]\n",
+        "name": "search-match"
+      }
+    ],
+    "keywords": [
+      "mark",
+      "highlight",
+      "search-match",
+      "emphasis"
+    ],
+    "name": "UIMark",
+    "related": [
+      "text",
+      "tag"
+    ],
+    "slots": {
+      "default": {
+        "description": "The text content to highlight (plain text or inline elements)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default — highlighted background painted behind the slotted text.",
+        "name": "idle"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "highlight": [
+        "mark",
+        "emphasis"
+      ],
+      "search-match": [
+        "mark",
+        "highlight"
+      ]
+    },
+    "tag": "mark-ui",
+    "tokens": {
+      "--mark-bg": {
+        "description": "Background color of the highlight.",
+        "default": "var(--a-warning-muted)"
+      },
+      "--mark-fg": {
+        "description": "Foreground (text) color inside the highlight.",
+        "default": "var(--a-warning-text)"
+      },
+      "--mark-px": {
+        "description": "Horizontal padding around the highlighted text.",
+        "default": "var(--a-space-0-5)"
+      },
+      "--mark-radius": {
+        "description": "Border radius of the highlight box.",
+        "default": "var(--a-radius-xs)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/mark/mark.class.js

@@ -0,0 +1,22 @@
+/**
+ * `<mark-ui>` — token-driven inline text highlight (search-match,
+ * "new since", diff prose). Theme-aware wrapper around the native
+ * `<mark>` semantic role. Pure CSS atom — no template, no JS behavior.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIMark extends UIElement {
+  static properties = {
+    variant: { type: String, default: 'warning', reflect: true }, // warning | info | success | danger | muted
+  };
+
+  static template = () => null;
+
+  connected() {
+    super.connected();
+    // Inherit the <mark> role for screen readers — "highlighted" / "marked"
+    // is the conventional AT announcement for search matches.
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'mark');
+  }
+}

package/components/mark/mark.css

@@ -0,0 +1,39 @@
+@scope (mark-ui) {
+  :where(:scope) {
+    --mark-bg-default:     var(--a-warning-muted);
+    --mark-fg-default:     var(--a-warning-text);
+    --mark-px-default:     var(--a-space-0-5);
+    --mark-radius-default: var(--a-radius-xs);
+  }
+
+  :scope {
+    /* Inline so it sits in normal text flow without breaking baselines.
+       Padding-inline only — vertical padding would push line-height. */
+    display: inline;
+    box-sizing: border-box;
+    padding-inline: var(--mark-px, var(--mark-px-default));
+    background: var(--mark-bg, var(--mark-bg-default));
+    color: var(--mark-fg, var(--mark-fg-default));
+    border-radius: var(--mark-radius, var(--mark-radius-default));
+    /* Preserve text decoration from ancestors (e.g. link underlines) */
+    text-decoration: inherit;
+  }
+
+  /* Variants — same role × state pair as alert-ui / tag-ui */
+  :scope[variant="info"] {
+    --mark-bg-default: var(--a-info-muted);
+    --mark-fg-default: var(--a-info-text);
+  }
+  :scope[variant="success"] {
+    --mark-bg-default: var(--a-success-muted);
+    --mark-fg-default: var(--a-success-text);
+  }
+  :scope[variant="danger"] {
+    --mark-bg-default: var(--a-danger-muted);
+    --mark-fg-default: var(--a-danger-text);
+  }
+  :scope[variant="muted"] {
+    --mark-bg-default: var(--a-bg-muted);
+    --mark-fg-default: var(--a-fg);
+  }
+}

package/components/mark/mark.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `<mark-ui>` — Highlighted inline text — token-driven theme-aware wrapper around the
+native `<mark>` semantic. Use for search-result match highlighting,
+diff additions in prose, "new since last visit" emphasis, and any
+inline text that needs a visual rail without changing its weight.
+
+Distinct from `<text-ui strong>` (semantic emphasis via weight) and
+from `<tag-ui>` (block-shaped pill chrome). mark-ui keeps the inline
+text flow intact — same line-height, same baseline — just paints a
+background highlight behind the matched span.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/mark
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIMark extends UIElement {
+  /** Highlight color variant. Default `warning` is the conventional yellow-marker tone. */
+  variant: 'warning' | 'info' | 'success' | 'danger' | 'muted';
+}

package/components/mark/mark.js

@@ -0,0 +1,12 @@
+/**
+ * `<mark-ui>` — auto-registers the tag on import.
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIMark } from './mark.class.js';
+
+defineIfFree('mark-ui', UIMark);
+
+export { UIMark };

package/components/mark/mark.yaml

@@ -0,0 +1,87 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIMark
+tag: mark-ui
+status: stable
+component: Mark
+category: typography
+version: 1
+description: |
+  Highlighted inline text — token-driven theme-aware wrapper around the
+  native `<mark>` semantic. Use for search-result match highlighting,
+  diff additions in prose, "new since last visit" emphasis, and any
+  inline text that needs a visual rail without changing its weight.
+
+  Distinct from `<text-ui strong>` (semantic emphasis via weight) and
+  from `<tag-ui>` (block-shaped pill chrome). mark-ui keeps the inline
+  text flow intact — same line-height, same baseline — just paints a
+  background highlight behind the matched span.
+props:
+  variant:
+    description: Highlight color variant. Default `warning` is the conventional yellow-marker tone.
+    type: string
+    default: warning
+    enum:
+      - warning
+      - info
+      - success
+      - danger
+      - muted
+    reflect: true
+events: {}
+slots:
+  default:
+    description: The text content to highlight (plain text or inline elements).
+states:
+  - name: idle
+    description: Default — highlighted background painted behind the slotted text.
+traits: []
+tokens:
+  --mark-bg:
+    description: Background color of the highlight.
+    default: var(--a-warning-muted)
+  --mark-fg:
+    description: Foreground (text) color inside the highlight.
+    default: var(--a-warning-text)
+  --mark-px:
+    description: Horizontal padding around the highlighted text.
+    default: var(--a-space-0-5)
+  --mark-radius:
+    description: Border radius of the highlight box.
+    default: var(--a-radius-xs)
+a2ui:
+  rules:
+    - rule: 'Use mark-ui for search-result match highlighting — wrap the matched substring in <mark-ui> within the surrounding text. Inline; preserves text flow.'
+      reason: 'Search-result highlight pattern.'
+    - rule: 'variant=warning (default) is the conventional yellow-marker tone; info for brand-color highlights; success for "new since" / "added" emphasis; danger for "removed" / "deleted-line" in diff prose.'
+      reason: 'Semantic variant vocabulary.'
+    - rule: 'Distinct from <text-ui strong> (weight emphasis), <tag-ui> (block pill), <code-ui> (monospace). mark-ui is specifically the "visual rail behind matched text" use case.'
+      reason: 'Sibling-component boundary.'
+anti_patterns:
+  - wrong: '<mark>matched</mark>'
+    why: 'Native <mark> uses UA default (yellow-on-white) that doesn''t adapt to theme — invisible in dark mode + jarring in light mode.'
+    fix: '<mark-ui>matched</mark-ui> — same semantic role but theme-aware.'
+examples:
+  - name: search-match
+    description: Highlight the search query within a result title.
+    a2ui: |
+      [
+        { "id": "row", "component": "Row", "children": ["pre", "mk", "post"] },
+        { "id": "pre", "component": "Text", "textContent": "Quarterly " },
+        { "id": "mk",  "component": "Mark", "textContent": "revenue" },
+        { "id": "post", "component": "Text", "textContent": " report — Q4 2025" }
+      ]
+keywords:
+  - mark
+  - highlight
+  - search-match
+  - emphasis
+synonyms:
+  highlight:
+    - mark
+    - emphasis
+  search-match:
+    - mark
+    - highlight
+related:
+  - text
+  - tag

package/components/modal/modal.a2ui.json

@@ -76,6 +76,15 @@
     "slots": {
       "default": {
         "description": "Content placed inside the modal surface. Accepts any elements (card-ui, command-ui, custom markup)."
+      },
+      "body": {
+        "description": "Main body region for prose, forms, or arbitrary content. Sits between header and footer; scrolls when content overflows."
+      },
+      "footer": {
+        "description": "Optional footer region rendered below the body, typically for action buttons. Author-fills with Confirm / Cancel buttons or similar trailing affordances."
+      },
+      "header": {
+        "description": "Optional header region rendered above the body. Author-fillable with title + supporting markup. CSS positions it at the top of the modal surface with consistent padding + the dismiss-close affordance."
       }
     },
     "states": [

package/components/modal/modal.yaml

@@ -45,6 +45,20 @@ events:
 slots:
   default:
     description: Content placed inside the modal surface. Accepts any elements (card-ui, command-ui, custom markup).
+  header:
+    description: >-
+      Optional header region rendered above the body. Author-fillable with
+      title + supporting markup. CSS positions it at the top of the modal
+      surface with consistent padding + the dismiss-close affordance.
+  body:
+    description: >-
+      Main body region for prose, forms, or arbitrary content. Sits between
+      header and footer; scrolls when content overflows.
+  footer:
+    description: >-
+      Optional footer region rendered below the body, typically for action
+      buttons. Author-fills with Confirm / Cancel buttons or similar trailing
+      affordances.
 states:
 - name: idle
   description: Default, ready for interaction.

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

@@ -98,6 +98,9 @@
       },
       "header": {
         "description": "Optional custom header. Auto-generated when missing."
+      },
+      "icon": {
+        "description": "Override the leading [icon] glyph in the auto-generated header with a custom slotted element. Mutually exclusive with the [icon] attribute."
       }
     },
     "states": [

package/components/nav-group/nav-group.yaml

@@ -63,6 +63,11 @@ slots:
     description: "Children — typically <nav-item-ui> rows."
   header:
     description: "Optional custom header. Auto-generated when missing."
+  icon:
+    description: >-
+      Override the leading [icon] glyph in the auto-generated header
+      with a custom slotted element. Mutually exclusive with the [icon]
+      attribute.
 
 states:
   - name: closed