@adia-ai/web-modules

Composite custom elements built from @adia-ai/web-components primitives. Organized into clusters by use case; each cluster ships as a subpath export so consumers install only what they need.

Install

npm install @adia-ai/web-modules @adia-ai/web-components

@adia-ai/web-components is a peer dependency (modules compose primitives at runtime). Consumers can import the full barrel or a specific cluster subpath:

import '@adia-ai/web-modules';                  // every cluster
import '@adia-ai/web-modules/shell';             // admin-shell + admin-sidebar + admin-command
import '@adia-ai/web-modules/chat';              // chat-shell + chat-thread + chat-composer + …
import '@adia-ai/web-modules/editor';            // editor-shell + editor-canvas + editor-sidebar + …
import '@adia-ai/web-modules/simple';            // simple-shell + simple-content + simple-hero
import '@adia-ai/web-modules/theme';             // theme-panel
import '@adia-ai/web-modules/runtime';           // gen-root + a2ui-root

Each cluster carries a shell host (behavior-only orchestrator) plus a family of bespoke shell-tier children (cluster-namespaced custom elements with state-as-attribute semantics) per ADR-0023. The bespoke vocabulary is the only recognized authoring shape since v0.4.0 (ADR-0024).

The patterns directory lived inside @adia-ai/web-components as patterns/ until this package was extracted (see ADR-0012). Tags, CSS, and YAML/A2UI contracts are unchanged; only the import path moves.

Clusters

| Cluster | Host | Bespoke children | What's inside | |---|---|---|---| | shell | <admin-shell> | <admin-sidebar>, <admin-command> (JS-bearing); <admin-content>, <admin-topbar>, <admin-statusbar>, <admin-scroll>, <admin-page>, <admin-page-header>, <admin-page-body> (CSS-only); 9 children total | Admin-shell composition: sidebars, command palette, page chrome. Resize/collapse/persistence on <admin-sidebar>; Cmd+K palette on <admin-command>. | | chat | <chat-shell> | <chat-thread>, <chat-composer>, <chat-sidebar> (JS-bearing); <chat-empty>, <chat-header>, <chat-status> (CSS-only); 6 children total | Conversational surface — streaming messages, composer with [disabled] propagation, scroll-to-bottom thread, [streaming] reflected. | | editor | <editor-shell> | <editor-toolbar>, <editor-canvas>, <editor-sidebar> (JS-bearing); <editor-statusbar>, <editor-canvas-empty> (CSS-only); 5 children total | Design-tool surface — toolbar with [full-screen], central canvas with [focused]/[empty], sidebar wraps <pane-ui resizable> for delegation. | | runtime | <gen-root>, <a2ui-root> | — | Render roots that turn JSON or gen-UI intents into live DOM. | | theme | — (controls-only) | <theme-panel> (JS-bearing); 1 child total | Appearance-preferences control surface — [data-theme] named themes, --a-density / --a-radius-k parametric overrides, color-scheme light/dark, opt-in [persist]. Drops into any consumer's <popover-ui slot="content"> topbar. Spec: docs/specs/theme-panel-module.md. |

Future clusters on the strategic horizon: data (kanban, filters, table-toolbar), agent (agent-trace, reasoning panels).

See bespoke-shell-children skill for the canonical decomposition recipe used by all three families.

Quick start

<!-- CSS for each cluster you import -->
<link rel="stylesheet" href="node_modules/@adia-ai/web-modules/shell/admin-shell/admin-shell.css" />

<!-- Primitives (nav-ui, nav-group-ui, nav-item-ui live here) -->
<link rel="stylesheet" href="node_modules/@adia-ai/web-components/index.css" />

<script type="module">
  import '@adia-ai/web-components';        // primitives + nav family
  import '@adia-ai/web-modules/shell';     // admin-shell + bespoke children
  import '@adia-ai/web-modules/chat';      // chat-shell + bespoke children
  import '@adia-ai/web-modules/editor';    // editor-shell + bespoke children
  import '@adia-ai/web-modules/runtime';   // gen-root, a2ui-root
  import '@adia-ai/web-modules/theme';     // theme-panel (appearance prefs)
</script>

<!-- Bespoke shape (canonical since v0.4.0): -->
<admin-shell mode="rounded">
  <admin-sidebar slot="leading" resizable collapsible>
    <header-ui>
      <span slot="heading">App</span>
    </header-ui>
    <section-ui>
      <nav-ui>…</nav-ui>
    </section-ui>
  </admin-sidebar>
  <main>…</main>
  <admin-command>
    <command-ui placeholder="Search..."></command-ui>
  </admin-command>
</admin-shell>

Three-tier architecture

@adia-ai/web-components   — primitives (button, table, card, …)
@adia-ai/web-modules      — composites (this package; clusters via subpath)
@adia-ai/web-themes       — token sets per vendor/brand (future)

Modules and themes both peer-depend web-components directly; they do not import each other. Composition happens at the consumer's site, not inside the library. See ADR-0012 for the rationale and the patterns/modules collapse.

Migration from @adia-ai/web-components/patterns

Before:

import '@adia-ai/web-components/patterns/app-shell/app-shell.js';
import '@adia-ai/web-components/patterns/adia-chat/adia-chat.js';

After:

import '@adia-ai/web-modules/shell/app-shell/app-shell.js';
import '@adia-ai/web-modules/chat/adia-chat/adia-chat.js';

Or, more idiomatically, import the cluster:

import '@adia-ai/web-modules/shell';     // every shell-cluster element
import '@adia-ai/web-modules/chat';      // adia-chat

CSS paths shift the same way (/patterns/<x>/<x>.css → /<cluster>/<x>/<x>.css).

Layout

web-modules/
├── shell/
│   └── admin-shell/    <admin-shell-ui> (full component, 251 LOC JS)
│                       Nav primitives (nav-ui, nav-group-ui, nav-item-ui)
│                       live in @adia-ai/web-components.
├── chat/
│   └── adia-chat/
├── editor/
│   └── adia-editor/
├── runtime/
│   ├── gen-ui/         <gen-ui> render root
│   └── a2ui-root/      <a2ui-root> A2UI render root
├── theme/
│   └── theme-panel/    <theme-panel> appearance-preferences control surface
└── index.js            barrel re-export of every cluster

Each element directory carries its .js, .css, .yaml, and .a2ui.json files — same shape as web-components/components/<x>/. The yaml + a2ui.json contracts feed the gen-UI catalog at packages/a2ui/corpus/catalog-a2ui_0_9.json; the build script at scripts/build/components.mjs scans both web-components/components/ and web-modules/<cluster>/.

License

MIT