@adia-ai/web-modules 0.8.25 → 0.8.26

package/agent-admin/admin-roster/admin-roster.yaml

@@ -0,0 +1,167 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAdminRoster
+tag: admin-roster-ui
+status: stable
+component: AdminRoster
+category: container
+version: 1
+description: |
+  L4 persona roster (CHAT-HARNESS.md §Components row L4, gh#600 / WCH-5) —
+  one row per persona with exactly-one-active menu semantics
+  (`role="menu"` of `role="menuitemradio"` rows, `aria-checked` mirroring
+  `[active-id]`). Clicking a row fires `persona-change` with the clicked
+  persona's id; clicking the already-active row is a no-op. Import/export
+  buttons ride `@adia-ai/persona`'s persona-file functions verbatim —
+  export downloads the active persona as JSON, import reads a chosen file
+  and re-emits the minted persona as `persona-import` for the host to
+  append and persist.
+
+  Lives in `packages/web-modules/agent-admin/` alongside
+  `<admin-settings-ui>` and `<agent-admin-ui>` — the L4 admin composite
+  family over `@adia-ai/persona`'s L2 store contract.
+
+composes:
+  - button-ui
+  - icon-ui
+
+props:
+  personas:
+    description: |
+      Array of `{ id, label, category? }` persona summaries. Empty array
+      renders "No personas yet."
+    type: array
+    default: []
+    required: true
+    dynamic: true
+  active-id:
+    description: |
+      The currently-active persona's id. Reflects so a host can deep-link;
+      drives `aria-checked` + the visible check glyph on the matching row.
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+
+events:
+  persona-change:
+    description: A non-active row was clicked.
+    detail:
+      personaId:
+        type: string
+        description: The id of the persona the user switched to.
+  persona-import:
+    description: A persona file was chosen and parsed successfully.
+    detail:
+      persona:
+        type: object
+        description: The minted persona (fresh, collision-safe id) from `importPersona`.
+  persona-import-error:
+    description: A chosen file failed to parse or validate as a persona file.
+    detail:
+      error:
+        type: string
+        description: The error message from `importPersona`.
+
+slots: {}
+
+states:
+  - name: idle
+    description: Default; renders the persona list.
+  - name: empty
+    description: "`personas` is an empty array."
+
+traits: []
+
+tokens:
+  --admin-roster-bg:
+    description: Panel background.
+    default: var(--a-bg)
+  --admin-roster-fg:
+    description: Primary foreground.
+    default: var(--a-fg)
+  --admin-roster-fg-muted:
+    description: Secondary foreground (category text, empty state).
+    default: var(--a-fg-muted)
+  --admin-roster-px:
+    description: Horizontal padding.
+    default: var(--a-space-4)
+  --admin-roster-py:
+    description: Vertical padding.
+    default: var(--a-space-4)
+  --admin-roster-gap:
+    description: Vertical gap between header / menu / toolbar.
+    default: var(--a-space-3)
+  --admin-roster-row-gap:
+    description: Gap between rows.
+    default: var(--a-space-1)
+  --admin-roster-row-radius:
+    description: Row border radius.
+    default: var(--a-radius-md)
+  --admin-roster-active-bg:
+    description: Active/hover row background.
+    default: var(--a-bg-muted)
+  --admin-roster-active-fg:
+    description: Active row foreground.
+    default: var(--a-fg-strong)
+
+a2ui:
+  rules:
+    - rule: |
+        Use <admin-roster-ui> for the canonical persona-switch list in an
+        agent-admin surface. Supply the `personas` array; the composite
+        owns menuitemradio semantics and the active-row check glyph.
+      reason: One composite replaces a hand-rolled persona list.
+    - rule: |
+        Listen for `persona-change` to swap the bound `SettingsStore`
+        (CHAT-HARNESS §Interfaces 5) — a genuine store reference change
+        resets the conversation + open surfaces; this composite never
+        touches the store itself.
+      reason: Store-swap is the host composition's job, not the roster's.
+
+anti_patterns:
+  - wrong: |
+      {"component": "AdminRoster", "personas": [{"id": "a", "label": "A"}], "children": [
+        {"component": "Button", "text": "Switch"}
+      ]}
+    why: Rows are generated from the `personas` prop — slotted children are ignored.
+    fix: |
+      {"component": "AdminRoster", "personas": [{"id": "a", "label": "A"}]}
+
+examples:
+  - name: two-personas
+    description: Roster with one active persona.
+    a2ui: |
+      [{"id": "roster", "component": "AdminRoster",
+        "active-id": "support",
+        "personas": [
+          {"id": "support", "label": "Support agent", "category": "Customer"},
+          {"id": "writer", "label": "Writer", "category": "Content"}
+        ]}]
+  - name: empty
+    description: No personas yet.
+    a2ui: |
+      [{"id": "roster", "component": "AdminRoster", "personas": []}]
+
+keywords:
+  - admin
+  - persona
+  - roster
+  - agent
+  - switch
+  - menu
+
+synonyms:
+  roster:
+    - list
+    - personas
+    - agents
+  persona:
+    - agent
+    - config
+    - profile
+
+related:
+  - AdminSettings
+  - AgentAdmin
+  - Menu

package/agent-admin/admin-settings/admin-settings.a2ui.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminSettings.json",
+  "title": "AdminSettings",
+  "description": "L4 settings pane over ONE bound per-persona store (CHAT-HARNESS.md\n§Components row L4 + §Interfaces 5, gh#600 / WCH-5). Sections group by\n`@adia-ai/persona`'s `KNOWN_KINDS` — DISPLAY grouping only; this\ncomposite never switches on `entry.kind` for logic (law 7: Entry is one\ngeneric primitive). Each Entry renders through the same row: label +\ndescription, an enabled toggle, and a collapsible content textarea\n(authoring). Both write through `store.set(...)` immediately — the\nstore is the state, persisted per persona.\n\n`persona` and `store` are plain JS properties (no attribute path);\n`store` is an opaque `SettingsStore` object from\n`@adia-ai/persona`'s `personaStore`.\n\nLives in `packages/web-modules/agent-admin/` alongside\n`<admin-roster-ui>` and `<agent-admin-ui>`.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdminSettings"
+    },
+    "persona": {
+      "description": "The `Persona` (from `@adia-ai/persona`) whose entries this pane\nrenders, grouped by `KNOWN_KINDS`. JS property only — no attribute.\n",
+      "type": "object"
+    },
+    "store": {
+      "description": "The `SettingsStore` bound to `persona` (typically\n`personaStore(persona)`). Toggle + content edits write through it\nimmediately; external `store.set()` calls (e.g. a live-apply probe)\nre-render this pane via `store.subscribe`. JS property only.\n",
+      "type": "object"
+    }
+  },
+  "required": [
+    "component",
+    "persona",
+    "store"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "const el = document.querySelector('admin-settings-ui');\nel.persona = myPersona;\nel.store = personaStore(myPersona);\n",
+        "why": "Renders \"No persona selected.\" — `persona` and `store` must be set as JS properties before use.",
+        "wrong": "{\"component\": \"AdminSettings\"}\n"
+      }
+    ],
+    "category": "container",
+    "composes": [
+      "switch-ui",
+      "textarea-ui",
+      "text-ui",
+      "icon-ui"
+    ],
+    "events": {
+      "entry-change": {
+        "description": "An entry's `enabled` or `content` field was written through the store.",
+        "detail": {
+          "entryId": {
+            "type": "string"
+          },
+          "field": {
+            "description": "'enabled' or 'content'.",
+            "type": "string"
+          },
+          "value": {
+            "description": "The new value (boolean for enabled, string for content).",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Settings pane bound to a persona + its store (JS-driven; not expressible as static a2ui JSON since `store` is an opaque object).",
+        "a2ui": "[{\"id\": \"settings\", \"component\": \"AdminSettings\"}]\n",
+        "name": "bound-to-a-persona"
+      }
+    ],
+    "keywords": [
+      "admin",
+      "settings",
+      "persona",
+      "entry",
+      "store",
+      "agent"
+    ],
+    "name": "UIAdminSettings",
+    "related": [
+      "AdminRoster",
+      "AgentAdmin"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default; renders `persona`'s entries grouped by kind.",
+        "name": "idle"
+      },
+      {
+        "description": "No `persona` set.",
+        "name": "empty"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "persona": [
+        "agent",
+        "profile"
+      ],
+      "settings": [
+        "config",
+        "preferences",
+        "entries"
+      ]
+    },
+    "tag": "admin-settings-ui",
+    "tokens": {
+      "--admin-settings-bg": {
+        "description": "Panel background.",
+        "default": "var(--a-bg)"
+      },
+      "--admin-settings-border": {
+        "description": "Entry card border.",
+        "default": "var(--a-border-subtle)"
+      },
+      "--admin-settings-entry-gap": {
+        "description": "Gap between sibling entries in a section.",
+        "default": "var(--a-space-1)"
+      },
+      "--admin-settings-fg": {
+        "description": "Primary foreground.",
+        "default": "var(--a-fg)"
+      },
+      "--admin-settings-fg-muted": {
+        "description": "Secondary foreground (description, empty state).",
+        "default": "var(--a-fg-muted)"
+      },
+      "--admin-settings-gap": {
+        "description": "Vertical gap between header and sections.",
+        "default": "var(--a-space-5)"
+      },
+      "--admin-settings-px": {
+        "description": "Horizontal padding.",
+        "default": "var(--a-space-4)"
+      },
+      "--admin-settings-py": {
+        "description": "Vertical padding.",
+        "default": "var(--a-space-4)"
+      },
+      "--admin-settings-radius": {
+        "description": "Entry card border radius.",
+        "default": "var(--a-radius-md)"
+      },
+      "--admin-settings-section-gap": {
+        "description": "Gap between a section's heading and its entries.",
+        "default": "var(--a-space-2)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/agent-admin/admin-settings/admin-settings.css

@@ -0,0 +1,114 @@
+/* ═══════════════════════════════════════════════════════════════
+   admin-settings-ui — Module CSS
+
+   Two-block @scope:
+     Block 1 — TOKENS  (:where(:scope))
+     Block 2 — BASE    (:scope + descendant rules)
+
+   Composition note: layout + spacing only; child primitives (switch-ui,
+   textarea-ui, text-ui, icon-ui) carry their own chrome.
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (admin-settings-ui) {
+
+  :where(:scope) {
+    --admin-settings-bg:              var(--a-bg);
+    --admin-settings-fg:              var(--a-fg);
+    --admin-settings-fg-muted:        var(--a-fg-muted);
+    --admin-settings-px:              var(--a-space-4);
+    --admin-settings-py:              var(--a-space-4);
+    --admin-settings-gap:             var(--a-space-5);
+    --admin-settings-section-gap:     var(--a-space-2);
+    --admin-settings-entry-gap:       var(--a-space-1);
+    --admin-settings-border:          var(--a-border-subtle);
+    --admin-settings-radius:          var(--a-radius-md);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: grid;
+    gap: var(--admin-settings-gap);
+    padding: var(--admin-settings-py) var(--admin-settings-px);
+    background: var(--admin-settings-bg);
+    color: var(--admin-settings-fg);
+    min-width: 0;
+  }
+
+  :scope > [data-part="header"] > [data-part="title"] {
+    margin: 0;
+    font-size: var(--a-text-lg);
+    font-weight: var(--a-weight-medium);
+  }
+
+  :scope [data-part="sections"] {
+    display: grid;
+    gap: var(--a-space-6);
+  }
+
+  :scope [data-part="section"] {
+    display: grid;
+    gap: var(--admin-settings-section-gap);
+  }
+
+  :scope [data-part="entries"] {
+    display: grid;
+    gap: var(--admin-settings-entry-gap);
+  }
+
+  :scope [data-part="entry"] {
+    border: 1px solid var(--admin-settings-border);
+    border-radius: var(--admin-settings-radius);
+    padding: var(--a-space-2) var(--a-space-3);
+  }
+
+  :scope [data-part="entry-row"] {
+    display: flex;
+    align-items: center;
+    gap: var(--a-space-2);
+  }
+
+  :scope [data-part="entry-meta"] {
+    flex: 1 1 auto;
+    min-width: 0;
+    display: grid;
+    gap: 2px;
+  }
+
+  :scope [data-part="entry-label"] {
+    font-weight: var(--a-weight-medium);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  :scope [data-part="entry-description"] {
+    font-size: var(--a-ui-sm);
+    color: var(--admin-settings-fg-muted);
+  }
+
+  :scope [data-action="collapse-toggle"] {
+    flex: 0 0 auto;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    border: none;
+    background: transparent;
+    color: var(--admin-settings-fg-muted);
+    cursor: pointer;
+    padding: var(--a-space-1);
+  }
+
+  :scope [data-part="entry-enabled"] {
+    flex: 0 0 auto;
+  }
+
+  :scope [data-part="entry-content"] {
+    margin-top: var(--a-space-2);
+  }
+
+  :scope [data-part="empty"] {
+    padding: var(--a-space-6);
+    text-align: center;
+    color: var(--admin-settings-fg-muted);
+  }
+}

package/agent-admin/admin-settings/admin-settings.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `<admin-settings-ui>` — L4 settings pane over ONE bound per-persona
+ * store (CHAT-HARNESS.md §Components row L4 + §Interfaces 5, gh#600 /
+ * WCH-5).
+ *
+ * Hand-authored alongside `<name>.yaml`; regenerate when the props /
+ * events shape changes.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+import type { Persona, SettingsStore } from '@adia-ai/persona';
+
+export interface AdminSettingsEntryChangeDetail {
+  entryId: string;
+  field: 'enabled' | 'content';
+  value: boolean | string;
+}
+export type AdminSettingsEntryChangeEvent = CustomEvent<AdminSettingsEntryChangeDetail>;
+
+export class UIAdminSettings extends UIElement {
+  persona: Persona | null;
+  store: SettingsStore | null;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAdminSettings, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'entry-change', listener: (ev: AdminSettingsEntryChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/agent-admin/admin-settings/admin-settings.js

@@ -0,0 +1,219 @@
+/**
+ * <admin-settings-ui> — L4 settings pane over ONE bound per-persona store
+ * (CHAT-HARNESS.md §Components row L4 + §Interfaces 5, gh#600 / WCH-5).
+ *
+ *   <admin-settings-ui id="settings"></admin-settings-ui>
+ *   <script>
+ *     const el = document.querySelector('#settings');
+ *     el.persona = myPersona;              // @adia-ai/persona Persona
+ *     el.store = personaStore(myPersona);  // @adia-ai/persona SettingsStore
+ *   </script>
+ *
+ * Sections are grouped by `KNOWN_KINDS` (display grouping ONLY — this file
+ * never switches on `entry.kind` for logic, per CHAT-HARNESS law 7: Entry
+ * is ONE generic primitive, six kinds are seed data). Each Entry renders
+ * through the SAME markup: a label + description, an enabled toggle, and a
+ * collapsible content textarea (authoring, M-scope 2). Both the toggle and
+ * the textarea write through `store.set(...)` IMMEDIATELY on change — this
+ * composite holds no local edit buffer; the store IS the state, persisted
+ * per persona (`@adia-ai/persona`'s `personaStore`).
+ *
+ * `persona` / `store` are plain JS properties (no attribute path for
+ * either; `store` is an opaque `SettingsStore` object, never
+ * attribute-serializable) that force a re-render through `_v`, an
+ * internal reflected counter declared in `static properties` — the same
+ * "reassign a declared reactive prop to force a repaint" trick
+ * `<integrations-page-ui>` uses for its own non-attribute state.
+ *
+ * Per ADR-0027 — composites that programmatically create primitives in
+ * render() do NOT auto-import those primitives; a consumer imports
+ * <switch-ui>, <textarea-ui>, <text-ui>, <icon-ui>, <button-ui> alongside this module.
+ */
+
+import { UIElement, html } from '../../../web-components/core/element.js';
+import { KNOWN_KINDS } from '@adia-ai/persona';
+import { entryStoreKey } from '../live-persona.js';
+
+const GROUP_LABEL = {
+  'prompt-section': 'Prompt sections',
+  skill: 'Skills',
+  workflow: 'Workflows',
+  resource: 'Resources',
+  tool: 'Tools',
+  'pattern-source': 'Pattern sources',
+};
+
+class UIAdminSettings extends UIElement {
+  // `_v` is an internal repaint counter — not a public prop, never meant
+  // to be read or set by a consumer. Bumping it (an ordinary declared-
+  // property write) is how persona/store/collapse-state changes reach the
+  // framework's own render effect, without inventing a second reactivity
+  // mechanism alongside it (that duplication is what caused a signals
+  // drain-loop warning in an earlier draft of this file).
+  static properties = {
+    _v: { type: Number, default: 0 },
+  };
+
+  static template = (host) => host._renderTemplate();
+
+  #headerId = `admin-settings-h-${Math.random().toString(36).slice(2, 8)}`;
+  #persona = null;
+  #store = null;
+  #expanded = new Set();
+  #unsubscribe = null;
+
+  connected() {
+    this.setAttribute('role', 'region');
+    this.setAttribute('aria-labelledby', this.#headerId);
+    this.addEventListener('change', this.#onChange);
+    this.addEventListener('input', this.#onContentInput);
+    this.addEventListener('press', this.#onToggleCollapse);
+  }
+
+  disconnected() {
+    this.removeEventListener('change', this.#onChange);
+    this.removeEventListener('input', this.#onContentInput);
+    this.removeEventListener('press', this.#onToggleCollapse);
+    if (this.#unsubscribe) { this.#unsubscribe(); this.#unsubscribe = null; }
+  }
+
+  get persona() { return this.#persona; }
+  set persona(value) {
+    this.#persona = value;
+    this._v++;
+  }
+
+  get store() { return this.#store; }
+  set store(value) {
+    if (this.#unsubscribe) { this.#unsubscribe(); this.#unsubscribe = null; }
+    this.#store = value;
+    if (value?.subscribe) {
+      this.#unsubscribe = value.subscribe(() => { this._v++; });
+    }
+    this._v++;
+  }
+
+  _renderTemplate() {
+    // Touch `_v` unconditionally so this render subscribes to it even on
+    // the empty-state branch below.
+    void this._v;
+    const persona = this.#persona;
+    const store = this.#store;
+
+    if (!persona) {
+      return html`<div data-part="empty" role="status">No persona selected.</div>`;
+    }
+    const groups = this.#groupedEntries(persona);
+    return html`
+      <header data-part="header">
+        <h2 data-part="title" id=${this.#headerId}>${persona.label ?? persona.id} — Settings</h2>
+      </header>
+      <div data-part="sections">
+        ${groups.map((g) => this.#renderSection(g, store))}
+      </div>
+    `;
+  }
+
+  #groupedEntries(persona) {
+    const byKind = new Map();
+    for (const entry of persona.entries) {
+      const list = byKind.get(entry.kind);
+      if (list) list.push(entry);
+      else byKind.set(entry.kind, [entry]);
+    }
+    return KNOWN_KINDS
+      .filter((kind) => byKind.has(kind))
+      .map((kind) => ({ kind, label: GROUP_LABEL[kind] ?? kind, entries: byKind.get(kind).sort((a, b) => a.order - b.order) }));
+  }
+
+  #renderSection(group, store) {
+    return html`
+      <section data-part="section" data-kind=${group.kind} aria-label=${group.label}>
+        <text-ui data-part="section-heading" variant="kicker">${group.label}</text-ui>
+        <div data-part="entries">
+          ${group.entries.map((entry) => this.#renderEntry(entry, store))}
+        </div>
+      </section>
+    `;
+  }
+
+  #renderEntry(entry, store) {
+    const enabled = this.#readEnabled(entry, store);
+    const content = this.#readContent(entry, store);
+    const isOpen = this.#expanded.has(entry.id);
+    return html`
+      <div data-part="entry" data-entry-id=${entry.id}>
+        <div data-part="entry-row">
+          <div data-part="entry-meta">
+            <span data-part="entry-label">${entry.label}</span>
+            ${entry.description ? html`<span data-part="entry-description">${entry.description}</span>` : null}
+          </div>
+          <button-ui data-action="collapse-toggle" data-entry-id=${entry.id}
+            variant="ghost" size="sm" icon=${isOpen ? 'caret-up' : 'caret-down'}
+            aria-expanded=${String(isOpen)} aria-label=${`Edit ${entry.label} content`}></button-ui>
+          <switch-ui data-part="entry-enabled" data-entry-id=${entry.id} .checked=${enabled}
+            aria-label=${`Enable ${entry.label}`}></switch-ui>
+        </div>
+        ${isOpen ? html`
+          <div data-part="entry-content">
+            <textarea-ui data-part="entry-content-input" data-entry-id=${entry.id}
+              .value=${content} rows="4"></textarea-ui>
+          </div>
+        ` : null}
+      </div>
+    `;
+  }
+
+  #readEnabled(entry, store) {
+    const stored = store?.get(entryStoreKey(entry.id, 'enabled'));
+    return typeof stored === 'boolean' ? stored : entry.enabled;
+  }
+
+  #readContent(entry, store) {
+    const stored = store?.get(entryStoreKey(entry.id, 'content'));
+    return typeof stored === 'string' ? stored : entry.content;
+  }
+
+  // ── event delegation ────────────────────────────────────────────
+
+  #onChange = (e) => {
+    const sw = e.target.closest?.('[data-part="entry-enabled"]');
+    if (sw && this.contains(sw)) {
+      const entryId = sw.getAttribute('data-entry-id');
+      const checked = !!e.detail?.checked;
+      this.store?.set(entryStoreKey(entryId, 'enabled'), checked);
+      this.dispatchEvent(new CustomEvent('entry-change', {
+        bubbles: true,
+        detail: { entryId, field: 'enabled', value: checked },
+      }));
+    }
+  };
+
+  #onContentInput = (e) => {
+    const ta = e.target.closest?.('[data-part="entry-content-input"]');
+    if (ta && this.contains(ta)) {
+      const entryId = ta.getAttribute('data-entry-id');
+      const value = e.detail?.value ?? ta.value ?? '';
+      this.store?.set(entryStoreKey(entryId, 'content'), value);
+      this.dispatchEvent(new CustomEvent('entry-change', {
+        bubbles: true,
+        detail: { entryId, field: 'content', value },
+      }));
+    }
+  };
+
+  #onToggleCollapse = (e) => {
+    const btn = e.target.closest?.('[data-action="collapse-toggle"]');
+    if (!btn || !this.contains(btn)) return;
+    const entryId = btn.getAttribute('data-entry-id');
+    if (this.#expanded.has(entryId)) this.#expanded.delete(entryId);
+    else this.#expanded.add(entryId);
+    this._v++;
+  };
+}
+
+if (!customElements.get('admin-settings-ui')) {
+  customElements.define('admin-settings-ui', UIAdminSettings);
+}
+
+export { UIAdminSettings };