@adia-ai/web-modules 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -11,6 +11,38 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [0.4.8] - 2026-05-12
+
+### Added — TypeScript declarations for all web-modules (FEEDBACK-02 #1, v0.4.8)
+
+Closes consumer-friction item #1 from FEEDBACK-adia-packages-02. Hand-codegen'd `.d.ts` declarations now ship for every web-module across all clusters:
+
+- **chat** (6): `chat-composer`, `chat-shell`, `chat-sidebar`, `chat-thread` + supporting types.
+- **editor** (5): `editor-canvas`, `editor-shell`, `editor-sidebar`, `editor-toolbar` + supporting types.
+- **runtime** (2): `a2ui-root`, `gen-root`.
+- **admin shell** (10): admin-command, admin-content, admin-page, admin-page-{body,header}, admin-scroll, admin-shell, admin-sidebar, admin-statusbar, admin-topbar.
+- **simple** + **theme** clusters: companion `.d.ts` files for the remaining modules.
+
+TypeScript consumers now get typed `document.querySelector('admin-shell')` returns `AdminShell`, typed reflected properties, typed methods (`.toggle()`, `.collapse()`, etc.), and typed custom events. `HTMLElementTagNameMap` augmentation in the package barrel makes the tag-name lookups type-aware. Mirrors the `@adia-ai/web-components@0.4.7` §74 codegen pattern.
+
+### Added — `composes:` field on YAMLs + `.a2ui.json` regen (ADR-0027 wiring, v0.4.8)
+
+Each web-module YAML now declares a `composes:` field listing the `@adia-ai/web-components` primitives it instantiates internally. ADR-0027 (cross-primitive composition imports are consumer's responsibility) becomes mechanically auditable — the `composes:` linter ships in this release and runs as part of `npm run components`. `.a2ui.json` sidecars regenerated to surface the `composes:` data through the v0.9 catalog.
+
+`chat-shell.yaml` + `gen-root.yaml` documented the LLM-pipeline wiring expectations alongside the composes declarations.
+
+### Documentation — lexical-scope authoring guide
+
+`README.md` § Module authoring updated with the `composes:` field semantics + lexical-scope rationale (why composes-declared imports must live at the consumer page, not transitively pulled by the module). Aligns with §66's `adaptV09Component()` catalog reader work.
+
+See root [CHANGELOG.md `[Unreleased]`](../../CHANGELOG.md) for the cross-cutting arc narrative.
+
+## [0.4.7] - 2026-05-12
+
+### Changed — `chat/chat-thread.yaml` populates `synonyms.tags` (§72)
+
+The composite `chat-thread.yaml` picks up the alias array previously held in the retired `@adia-ai/a2ui-corpus/patterns/_components.json` — `chat`, `conversation`, `messages`, `chat-log`, `message-thread`. Sidecar regenerated by `npm run components`. Mirrors the per-component yaml sweep on `@adia-ai/web-components` for §72 (the §65 carry-over from v0.4.6).
+
 ## [0.4.6] - 2026-05-12
 
 ### Fixed — `<editor-sidebar>` resize-state detection via `:has()`

package/chat/chat-composer/chat-composer.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [],
     "events": {
       "composer-submit": {
         "description": "Bubbles when the inner input fires its 'submit' event. Detail mirrors the inner event's detail (typically text + model).",

package/chat/chat-composer/chat-composer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `<chat-composer-ui>` — Module-tier chat composer wrapper — replaces legacy <chat-input-ui
+data-chat-input> direct child of <chat-shell> per ADR-0023.
+Forwards submit events as 'composer-submit', propagates [disabled]
+to the inner input, provides slot vocabulary for future composer
+surfaces (file attach, autocomplete, model picker).
+
+Sits inside <chat-shell> as the input region (typically inside or
+alongside the footer). Authors place an inner <chat-input-ui>
+(or input-ui / textarea-ui) as the primary input.
+
+Backwards compat — <chat-shell> still recognizes the legacy
+<chat-input-ui data-chat-input> shape via :is() selector. New
+code should prefer <chat-composer>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-composer
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 '../../../web-components/core/element.js';
+
+export interface ChatComposerComposerSubmitEventDetail {
+  model: string;
+  text: string;
+}
+
+export type ChatComposerComposerSubmitEvent = CustomEvent<ChatComposerComposerSubmitEventDetail>;
+
+export class UIChatComposer extends UIElement {
+  /** Reflected — set by the host while streaming, or by application
+code. Propagated to the inner input element automatically.
+ */
+  disabled: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatComposer, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'composer-submit', listener: (ev: ChatComposerComposerSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-empty/chat-empty.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "feedback",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/chat/chat-header/chat-header.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/chat/chat-shell/chat-shell.a2ui.json

@@ -54,6 +54,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "code-ui"
+    ],
     "events": {
       "abort": {
         "description": "Fired when the user aborts an in-flight request."

package/chat/chat-shell/chat-shell.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `<chat-shell-ui>` — Behavior-only chat orchestrator (LLM-streaming module). Author supplies the
+DOM structure via [data-chat-messages], [data-chat-input], [data-chat-empty],
+[data-chat-status] elements; chat-shell wires message streaming, markdown
+rendering, code-block upgrades, and an LLM integration path via proxy-url
+(or via external submit).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 '../../../web-components/core/element.js';
+
+export type ChatShellAbortEvent = CustomEvent<unknown>;
+export interface ChatShellChunkEventDetail {
+  snapshot: string;
+  text: string;
+}
+
+export type ChatShellChunkEvent = CustomEvent<ChatShellChunkEventDetail>;
+export type ChatShellClearEvent = CustomEvent<unknown>;
+export interface ChatShellDoneEventDetail {
+  stopReason: string;
+  text: string;
+  usage: string;
+}
+
+export type ChatShellDoneEvent = CustomEvent<ChatShellDoneEventDetail>;
+export interface ChatShellErrorEventDetail {
+  error: string;
+}
+
+export type ChatShellErrorEvent = CustomEvent<ChatShellErrorEventDetail>;
+export interface ChatShellMessageEventDetail {
+  content: string;
+  id: string;
+  role: string;
+}
+
+export type ChatShellMessageEvent = CustomEvent<ChatShellMessageEventDetail>;
+export interface ChatShellSubmitEventDetail {
+  model: string;
+  text: string;
+}
+
+export type ChatShellSubmitEvent = CustomEvent<ChatShellSubmitEventDetail>;
+export interface ChatShellThinkingEventDetail {
+  text: string;
+}
+
+export type ChatShellThinkingEvent = CustomEvent<ChatShellThinkingEventDetail>;
+
+export class UIChatShell extends UIElement {
+  /** Model identifier. */
+  model: string;
+  /** LLM provider name (anthropic | openai | google | stub). */
+  provider: string;
+  /** API proxy endpoint for LLM calls; enables self-contained chat without external wiring. */
+  proxyUrl: string;
+  /** Active streaming indicator; toggled while a response is being received. */
+  streaming: boolean;
+  /** System prompt prepended to conversations. */
+  system: string;
+  /** Enable Anthropic extended-thinking mode. */
+  thinking: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatShell, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'abort', listener: (ev: ChatShellAbortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chunk', listener: (ev: ChatShellChunkEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'clear', listener: (ev: ChatShellClearEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'done', listener: (ev: ChatShellDoneEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'error', listener: (ev: ChatShellErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'message', listener: (ev: ChatShellMessageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'submit', listener: (ev: ChatShellSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'thinking', listener: (ev: ChatShellThinkingEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-shell/chat-shell.yaml

@@ -11,6 +11,10 @@ description: |
   rendering, code-block upgrades, and an LLM integration path via proxy-url
   (or via external submit).
 
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - code-ui
 props:
   streaming:
     type: boolean

package/chat/chat-sidebar/chat-sidebar.a2ui.json

@@ -54,6 +54,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "sidebar-resize": {
         "description": "Bubbles when an active pointer-drag releases.",

package/chat/chat-sidebar/chat-sidebar.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `<chat-sidebar-ui>` — Module-tier chat-cluster sidebar — owns resize, snap-to-collapsed,
+persistence, and the [collapsed] reflected attribute. Sits inside
+<chat-shell> as slot="leading" (conversation history rail) or
+slot="trailing" (artifacts/citations panel). Mirrors the admin-sidebar
+shape — same 4 concerns, cluster-namespaced for the chat family.
+
+This is the chat-cluster equivalent of <admin-sidebar> per ADR-0023.
+<chat-shell> doesn't currently have a legacy sidebar shape (chat is
+typically a single-pane experience), so <chat-sidebar> is purely
+forward-looking — for chat apps that want conversation-history or
+inspector rails.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-sidebar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 '../../../web-components/core/element.js';
+
+export interface ChatSidebarSidebarResizeEventDetail {
+  name: string;
+  width: string;
+}
+
+export type ChatSidebarSidebarResizeEvent = CustomEvent<ChatSidebarSidebarResizeEventDetail>;
+export interface ChatSidebarSidebarToggleEventDetail {
+  expanded: string;
+  name: string;
+}
+
+export type ChatSidebarSidebarToggleEvent = CustomEvent<ChatSidebarSidebarToggleEventDetail>;
+
+export class UIChatSidebar extends UIElement {
+  /** Reflected — set when the sidebar's measured width is at or below
+96px. Consumers query this to style "collapsed mode" without
+duplicating threshold math.
+ */
+  collapsed: boolean;
+  /** Opts in to programmatic collapse — toggle button wiring + the
+.toggle() / .collapse() / .expand() public methods.
+ */
+  collapsible: boolean;
+  /** Identifier for localStorage namespacing. Defaults to slot value
+("leading" or "trailing"). Override when running multiple sidebars
+with the same slot.
+ */
+  name: string;
+  /** Opts in to drag-to-resize behavior. Author supplies a child
+[data-resize] element as the drag handle.
+ */
+  resizable: boolean;
+  /** Reflected — set during an active pointer-drag on the resize handle.
+Useful for suppressing transitions while dragging.
+ */
+  resizing: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatSidebar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'sidebar-resize', listener: (ev: ChatSidebarSidebarResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: ChatSidebarSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-status/chat-status.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "feedback",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/chat/chat-thread/chat-thread.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [
@@ -76,6 +77,12 @@
         "messages",
         "message-stream"
       ],
+      "tags": [
+        "Chat",
+        "conversation",
+        "chat-log",
+        "message-thread"
+      ],
       "thread": [
         "conversation",
         "dialogue",

package/chat/chat-thread/chat-thread.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `<chat-thread-ui>` — Module-tier chat message thread container — replaces legacy
+<section data-chat-messages> per ADR-0023. Owns scroll-to-bottom
+on new message (with user-scroll-up suspension), [streaming] and
+[empty] reflected attributes, and a stable target for the host's
+message rendering pipeline.
+
+Sits inside <chat-shell> as the central scroll surface. Authors
+compose <chat-empty> as an optional first child for the empty
+state; message children are appended dynamically by the host.
+
+Backwards compat — <chat-shell> still recognizes the legacy
+<section data-chat-messages> shape via :is() selector. New code
+should prefer <chat-thread>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-thread
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 '../../../web-components/core/element.js';
+
+export class UIChatThread extends UIElement {
+  /** Reflected — set when zero message children. Drives the
+<chat-empty> visibility via CSS — no JS toggling needed.
+ */
+  empty: boolean;
+  /** Reflected — set by the host while an LLM response is streaming.
+Consumers can style streaming-mode (e.g. cursor blink) via
+:has(chat-thread[streaming]) or attribute selectors.
+ */
+  streaming: boolean;
+}

package/chat/chat-thread/chat-thread.yaml

@@ -1,89 +1,98 @@
-# Edit this file; run `npm run build:components` to regenerate a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: ChatThread
 tag: chat-thread
 component: ChatThread
 category: container
 version: 1
-description: |
-  Module-tier chat message thread container — replaces legacy
+description: 'Module-tier chat message thread container — replaces legacy
+
   <section data-chat-messages> per ADR-0023. Owns scroll-to-bottom
+
   on new message (with user-scroll-up suspension), [streaming] and
-  [empty] reflected attributes, and a stable target for the host's
+
+  [empty] reflected attributes, and a stable target for the host''s
+
   message rendering pipeline.
 
+
   Sits inside <chat-shell> as the central scroll surface. Authors
+
   compose <chat-empty> as an optional first child for the empty
+
   state; message children are appended dynamically by the host.
 
+
   Backwards compat — <chat-shell> still recognizes the legacy
+
   <section data-chat-messages> shape via :is() selector. New code
+
   should prefer <chat-thread>.
 
+  '
 props:
   streaming:
-    description: |
-      Reflected — set by the host while an LLM response is streaming.
+    description: 'Reflected — set by the host while an LLM response is streaming.
+
       Consumers can style streaming-mode (e.g. cursor blink) via
+
       :has(chat-thread[streaming]) or attribute selectors.
+
+      '
     type: boolean
     default: false
     reflect: true
-
   empty:
-    description: |
-      Reflected — set when zero message children. Drives the
+    description: 'Reflected — set when zero message children. Drives the
+
       <chat-empty> visibility via CSS — no JS toggling needed.
+
+      '
     type: boolean
     default: true
     reflect: true
-
 events: {}
-
 slots:
   default:
-    description: >-
-      Default — message children (typically appended dynamically by
-      <chat-shell>'s rendering pipeline) plus an optional first
-      <chat-empty> sibling for the empty state.
-
+    description: Default — message children (typically appended dynamically by <chat-shell>'s rendering pipeline) plus an
+      optional first <chat-empty> sibling for the empty state.
 states:
-  - name: idle
-    description: Default, no streaming.
-  - name: streaming
-    attribute: streaming
-    description: Host is actively streaming an LLM response.
-  - name: empty
-    attribute: empty
-    description: Zero message children — empty state visible.
-
+- name: idle
+  description: Default, no streaming.
+- name: streaming
+  attribute: streaming
+  description: Host is actively streaming an LLM response.
+- name: empty
+  attribute: empty
+  description: Zero message children — empty state visible.
 traits: []
-
 a2ui:
   rules:
-    - >-
-      chat-thread is the bespoke replacement for legacy
-      <section data-chat-messages> inside <chat-shell>. Use it for
-      the message scroll surface; the host appends dynamic message
-      divs as children.
-    - >-
-      Place <chat-empty> as an optional first child for the empty
-      state; the [empty] reflected attribute drives its visibility
-      via CSS (no JS toggling).
-
+  - chat-thread is the bespoke replacement for legacy <section data-chat-messages> inside <chat-shell>. Use it for the message
+    scroll surface; the host appends dynamic message divs as children.
+  - Place <chat-empty> as an optional first child for the empty state; the [empty] reflected attribute drives its visibility
+    via CSS (no JS toggling).
 keywords:
-  - chat-thread
-  - message-list
-  - conversation
-  - thread
-  - scroll-surface
-
+- chat-thread
+- message-list
+- conversation
+- thread
+- scroll-surface
 synonyms:
-  thread: [conversation, dialogue, chat-log, transcript]
-  message-list: [messages, message-stream]
-
+  thread:
+  - conversation
+  - dialogue
+  - chat-log
+  - transcript
+  message-list:
+  - messages
+  - message-stream
+  tags:
+  - Chat
+  - conversation
+  - chat-log
+  - message-thread
 related:
-  - ChatShell
-  - ChatEmpty
-  - ChatComposer
-  - ChatSidebar
+- ChatShell
+- ChatEmpty
+- ChatComposer
+- ChatSidebar

package/editor/editor-canvas/editor-canvas.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-canvas/editor-canvas.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `<editor-canvas-ui>` — Module-tier editor canvas surface — replaces legacy <div data-canvas>
+inside <editor-shell> per ADR-0023. Owns scroll/zoom container
+semantics, [empty] and [focused] reflected attributes, and a stable
+target for the host's content rendering pipeline.
+
+Sits as the central content region inside <editor-shell>, between
+the optional <editor-sidebar slot="leading"> and <editor-sidebar
+slot="trailing">. Authors compose <editor-canvas-empty> as an
+optional first child for the empty state; canvas content children
+(artboards, document body, etc.) are appended either statically or
+dynamically by the host.
+
+Backwards compat — <editor-shell> still recognizes the legacy
+<div data-canvas> shape via :is() selector. New code should prefer
+<editor-canvas>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-canvas
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 '../../../web-components/core/element.js';
+
+export class UIEditorCanvas extends UIElement {
+  /** Reflected — set when zero non-<editor-canvas-empty> children.
+Drives the <editor-canvas-empty> visibility via parent CSS —
+no JS toggling needed.
+ */
+  empty: boolean;
+  /** Reflected — set when canvas claims focus ownership (programmatic
+.focus() call or toolbar full-screen toggle).
+ */
+  focused: boolean;
+}

package/editor/editor-canvas-empty/editor-canvas-empty.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "feedback",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-shell/editor-shell.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-shell/editor-shell.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `<editor-shell-ui>` — Behavior-only editor shell module for design-tool layouts. Author
+provides the structural DOM — header (topbar), [data-editor-body] with
+pane-ui children ([data-left], [data-right]), [data-canvas] for the
+central surface, and a footer (statusbar). editor-shell wires
+select-ui[data-options] for JSON-parsed option lists.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 '../../../web-components/core/element.js';
+
+export class UIEditorShell extends UIElement {
+}

package/editor/editor-sidebar/editor-sidebar.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "sidebar-toggle": {
         "description": "Bubbles when .toggle() / .collapse() / .expand() is called.",