@adia-ai/web-modules 0.8.18 → 0.8.19

package/form/form-popover/form-popover.a2ui.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/FormPopover.json",
+  "title": "FormPopover",
+  "description": "Module-tier \"form fragment in a popover\" (operator mock, 2026-07-27): a\nselect-style summary trigger that opens an anchored panel holding ANY\nform primitives — check-ui groups, radio-ui groups, input-ui,\ndivider-ui, field-ui — slotted as ordinary light-DOM children. The\nmodule owns the trigger + popover packaging and a live selection\nsummary; the slotted controls keep their own name/value/event\ncontracts untouched.\n\nSummary contract: the trigger reads `{label} · N selected` while any\nslotted check-ui is checked, `{label} · N total` when none are (N =\ncheck-ui count), and just `{label}` when the fragment contains no\ncheck-ui at all. Radio groups, inputs, and other controls deliberately\ndo not count — checkboxes are the only \"N selected\" semantic that\nreads unambiguously in a summary.\n\nDecision rule vs adjacent surfaces (inherits popover-ui's): a pure\naction list is menu-ui; a single-value choice is select-ui (which owns\nits option list — do NOT rebuild select inside this module); an\nedge-anchored multi-field form is drawer-ui. form-popover-ui is for the\nin-between: a small anchored fragment mixing selection controls and\ninputs, e.g. a filter panel or a quick-save form.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "FormPopover"
+    },
+    "heading": {
+      "description": "Optional panel heading rendered above the slotted fragment inside\nthe popover (\"Select options\"). Empty = no heading row.\n",
+      "type": "string",
+      "default": ""
+    },
+    "label": {
+      "description": "Summary-trigger prefix (\"Option items\"). The live count is\nappended after a middle dot; with no count the label renders\nalone. Required — with no label AND no check-ui children the\ntrigger would otherwise be an empty, nameless button; the runtime\nfalls back to \"Options\" in that state as a defensive accessible\nname, but authors must set a real label.\n",
+      "type": "string",
+      "default": ""
+    },
+    "placement": {
+      "description": "Passed through to the internal popover-ui. `bottom-start` default\nper ADR-0034 — the panel is trigger-anchored and roughly\ntrigger-width, like a select listbox.\n",
+      "type": "string",
+      "default": "bottom-start"
+    }
+  },
+  "required": [
+    "component",
+    "label"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "input",
+    "composes": [
+      "popover-ui",
+      "button-ui"
+    ],
+    "events": {
+      "summary-change": {
+        "description": "Fired (bubbling) whenever the selection summary recomputes —\ndetail: { selected, total }. The slotted controls' own change /\ninput events bubble through untouched; listen to those for\nvalues.\n"
+      }
+    },
+    "examples": [
+      {
+        "description": "Filter fragment — checkbox group + divider + radio pair + name input behind a summary trigger.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"FormPopover\", \"label\": \"Option items\", \"heading\": \"Select options\", \"children\": [\"c1\", \"c2\", \"c3\", \"d1\", \"r1\", \"r2\", \"d2\", \"name\"]},\n  {\"id\": \"c1\", \"component\": \"CheckBox\", \"label\": \"Option item\", \"checked\": true},\n  {\"id\": \"c2\", \"component\": \"CheckBox\", \"label\": \"Option item\"},\n  {\"id\": \"c3\", \"component\": \"CheckBox\", \"label\": \"Option item\", \"checked\": true},\n  {\"id\": \"d1\", \"component\": \"Divider\"},\n  {\"id\": \"r1\", \"component\": \"Radio\", \"name\": \"mode\", \"label\": \"Save\", \"checked\": true},\n  {\"id\": \"r2\", \"component\": \"Radio\", \"name\": \"mode\", \"label\": \"Delete\"},\n  {\"id\": \"d2\", \"component\": \"Divider\"},\n  {\"id\": \"name\", \"component\": \"Input\", \"placeholder\": \"Option name\"}\n]",
+        "name": "filter-popover"
+      }
+    ],
+    "keywords": [],
+    "name": "FormPopover",
+    "related": [],
+    "slots": {
+      "default": {
+        "description": "The form fragment. Any AdiaUI form primitives, in author order —\ncheck-ui, radio-ui, input-ui, divider-ui, field-ui, textarea-ui.\nAdopted into the popover panel on connect; DOM order is layout\norder (light-DOM contract).\n"
+      }
+    },
+    "states": [],
+    "status": "experimental",
+    "synonyms": {},
+    "tag": "form-popover-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/form/form-popover/form-popover.css

@@ -0,0 +1,48 @@
+/* ═══════════════════════════════════════════════════════════════
+   <form-popover-ui> — summary trigger + form-fragment panel.
+   Two-block @scope pattern per component-token-contract.md.
+   The panel surface itself (bg/border/shadow) belongs to popover-ui —
+   this module styles only its own trigger chrome and body layout.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── 1. Token declarations ── */
+
+form-popover-ui {
+  --form-popover-min-width:  16rem;
+  --form-popover-gap:        var(--a-space-2);
+  --form-popover-trigger-bg: var(--a-ui-bg);
+  --form-popover-trigger-fg: var(--a-ui-text);
+  --form-popover-trigger-border: var(--a-ui-border);
+  --form-popover-heading-fg: var(--a-fg-strong);
+}
+
+/* ── 2. Scoped layout ── */
+
+@scope (form-popover-ui) {
+  :scope {
+    display: block;
+  }
+
+  /* Field-look trigger: bordered, full-width, summary left / chevron
+     right — reads as a select trigger, not a button. Re-points
+     button-ui's own tokens (the sanctioned consumer override path). */
+  button-ui[data-form-popover-trigger] {
+    --button-bg: var(--form-popover-trigger-bg);
+    --button-fg: var(--form-popover-trigger-fg);
+    --button-border: var(--form-popover-trigger-border);
+    width: 100%;
+    justify-content: space-between;
+  }
+
+  [data-form-popover-body] {
+    display: flex;
+    flex-direction: column;
+    gap: var(--form-popover-gap);
+    min-width: var(--form-popover-min-width);
+  }
+
+  [data-form-popover-heading] {
+    font-weight: var(--a-weight-medium);
+    color: var(--form-popover-heading-fg);
+  }
+}

package/form/form-popover/form-popover.js

@@ -0,0 +1,140 @@
+/**
+ * <form-popover-ui> — a form fragment behind a select-style summary trigger.
+ *
+ * Anatomy (all light-DOM, stamped once in connected()):
+ *   <form-popover-ui label="Option items" heading="Select options">
+ *     <check-ui label="…"></check-ui> …            ← author's fragment
+ *   </form-popover>
+ * becomes
+ *   <form-popover-ui …>
+ *     <popover-ui placement="…">
+ *       <button-ui slot="trigger" data-form-popover-trigger
+ *                  icon-trailing="caret-down" text="Option items · 3 selected">
+ *       <div slot="content" data-form-popover-body>
+ *         [data-form-popover-heading]?   ← from [heading]
+ *         …the author's fragment, moved, order preserved…
+ *       </div>
+ *     </popover-ui>
+ *   </form-popover>
+ *
+ * The module owns packaging + summary only. Slotted controls keep their
+ * own name/value/event contracts; their change/input events bubble
+ * through untouched (we listen to the same bubbling events to recompute
+ * the summary — no state is duplicated here, the DOM is the source of
+ * truth, same rule as chart-legend-ui's peer contract).
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+const SUMMARY_EVENTS = ['change', 'input'];
+
+class FormPopover extends UIElement {
+  static properties = {
+    label:     { type: String, default: '', reflect: true },
+    heading:   { type: String, default: '', reflect: true },
+    placement: { type: String, default: 'bottom-start', reflect: true },
+  };
+
+  static template = () => null;
+
+  #stamped = false;
+  #triggerEl = null;
+  #bodyEl = null;
+  // Stable handler ref so disconnected() can remove what connected()
+  // added (lifecycle symmetry — inline arrows can't be removed).
+  #onFragmentChange = () => this.#updateSummary();
+
+  connected() {
+    if (!this.#stamped) {
+      this.#stamp();
+      this.#stamped = true;
+    }
+    for (const type of SUMMARY_EVENTS) this.addEventListener(type, this.#onFragmentChange);
+    this.#updateSummary();
+  }
+
+  disconnected() {
+    for (const type of SUMMARY_EVENTS) this.removeEventListener(type, this.#onFragmentChange);
+  }
+
+  updated(changed) {
+    if (!this.#stamped) return;
+    if (changed.has('label')) this.#updateSummary();
+    if (changed.has('heading')) this.#renderHeading();
+    if (changed.has('placement')) {
+      this.querySelector(':scope > popover-ui')?.setAttribute('placement', this.placement);
+    }
+  }
+
+  /** { selected, total } over the slotted check-ui population. */
+  get summary() {
+    const boxes = this.#bodyEl ? this.#bodyEl.querySelectorAll('check-ui') : [];
+    let selected = 0;
+    for (const box of boxes) if (box.hasAttribute('checked') || box.checked) selected += 1;
+    return { selected, total: boxes.length };
+  }
+
+  #stamp() {
+    // Adopt the author's fragment BEFORE stamping our own skeleton so the
+    // move loop never eats the popover we create (gh#284 class of bug).
+    const fragment = document.createDocumentFragment();
+    while (this.firstChild) fragment.appendChild(this.firstChild);
+
+    const popover = document.createElement('popover-ui');
+    popover.setAttribute('placement', this.placement);
+
+    const trigger = document.createElement('button-ui');
+    trigger.setAttribute('slot', 'trigger');
+    trigger.setAttribute('data-form-popover-trigger', '');
+    trigger.setAttribute('icon-trailing', 'caret-down');
+    this.#triggerEl = trigger;
+    popover.appendChild(trigger);
+
+    const body = document.createElement('div');
+    body.setAttribute('slot', 'content');
+    body.setAttribute('data-form-popover-body', '');
+    body.appendChild(fragment);
+    this.#bodyEl = body;
+    popover.appendChild(body);
+
+    this.appendChild(popover);
+    this.#renderHeading();
+  }
+
+  #renderHeading() {
+    if (!this.#bodyEl) return;
+    let el = this.#bodyEl.querySelector(':scope > [data-form-popover-heading]');
+    if (!this.heading) { el?.remove(); return; }
+    if (!el) {
+      el = document.createElement('div');
+      el.setAttribute('data-form-popover-heading', '');
+      this.#bodyEl.prepend(el);
+    }
+    el.textContent = this.heading;
+  }
+
+  #updateSummary() {
+    if (!this.#triggerEl) return;
+    const { selected, total } = this.summary;
+    let text = this.label;
+    if (total > 0) {
+      const count = selected > 0 ? `${selected} selected` : `${total} total`;
+      text = text ? `${text} · ${count}` : count;
+    }
+    // [label] is required by contract; this fallback only guards the
+    // no-label + no-checkbox misuse so the trigger never renders as an
+    // empty, nameless button (a11y — CodeRabbit finding on #441).
+    if (!text) text = 'Options';
+    this.#triggerEl.setAttribute('text', text);
+    this.dispatchEvent(new CustomEvent('summary-change', {
+      bubbles: true,
+      detail: { selected, total },
+    }));
+  }
+}
+
+if (!customElements.get('form-popover-ui')) {
+  customElements.define('form-popover-ui', FormPopover);
+}
+
+export { FormPopover };

package/form/form-popover/form-popover.test.js

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import './form-popover.js';
+
+const mount = (html) => {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+};
+
+describe('form-popover-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('adopts the fragment into the popover body, order preserved', () => {
+    const el = mount(`<form-popover-ui label="Options">
+      <check-ui label="a"></check-ui>
+      <divider-ui></divider-ui>
+      <input-ui placeholder="name"></input-ui>
+    </form-popover>`);
+    const body = el.querySelector('[data-form-popover-body]');
+    expect(body).toBeTruthy();
+    const tags = [...body.children].map((c) => c.tagName.toLowerCase());
+    expect(tags).toEqual(['check-ui', 'divider-ui', 'input-ui']);
+    // the popover skeleton is NOT part of the adopted fragment
+    expect(el.querySelector(':scope > popover-ui')).toBeTruthy();
+  });
+
+  it('summary counts checked check-ui: "N selected" / "N total"', () => {
+    const el = mount(`<form-popover-ui label="Option items">
+      <check-ui label="a" checked></check-ui>
+      <check-ui label="b"></check-ui>
+      <check-ui label="c" checked></check-ui>
+    </form-popover>`);
+    const trigger = el.querySelector('[data-form-popover-trigger]');
+    expect(trigger.getAttribute('text')).toBe('Option items · 2 selected');
+    expect(el.summary).toEqual({ selected: 2, total: 3 });
+    // uncheck everything → falls back to total
+    for (const box of el.querySelectorAll('check-ui')) box.removeAttribute('checked');
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    expect(trigger.getAttribute('text')).toBe('Option items · 3 total');
+  });
+
+  it('renders the bare label when the fragment has no check-ui', () => {
+    const el = mount(`<form-popover-ui label="Rename">
+      <input-ui placeholder="name"></input-ui>
+    </form-popover>`);
+    expect(el.querySelector('[data-form-popover-trigger]').getAttribute('text')).toBe('Rename');
+  });
+
+  it('[heading] renders and clears', async () => {
+    const el = mount(`<form-popover-ui label="x" heading="Select options"><check-ui label="a"></check-ui></form-popover>`);
+    expect(el.querySelector('[data-form-popover-heading]').textContent).toBe('Select options');
+    el.heading = '';
+    await Promise.resolve();
+    expect(el.querySelector('[data-form-popover-heading]')).toBeNull();
+  });
+
+  it('emits summary-change with detail', () => {
+    const el = mount(`<form-popover-ui label="x"><check-ui label="a"></check-ui></form-popover>`);
+    let detail = null;
+    el.addEventListener('summary-change', (e) => { detail = e.detail; });
+    el.querySelector('check-ui').setAttribute('checked', '');
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    expect(detail).toEqual({ selected: 1, total: 1 });
+  });
+
+  it('falls back to "Options" with no label and no checkboxes (a11y guard)', () => {
+    const el = mount(`<form-popover-ui><input-ui placeholder="name"></input-ui></form-popover-ui>`);
+    expect(el.querySelector('[data-form-popover-trigger]').getAttribute('text')).toBe('Options');
+  });
+
+  it('passes [placement] through to the internal popover, including updates', async () => {
+    const el = mount(`<form-popover-ui label="x" placement="top"><check-ui label="a"></check-ui></form-popover-ui>`);
+    expect(el.querySelector(':scope > popover-ui').getAttribute('placement')).toBe('top');
+    el.placement = 'bottom-end';
+    await Promise.resolve();
+    expect(el.querySelector(':scope > popover-ui').getAttribute('placement')).toBe('bottom-end');
+  });
+
+  it('[label] updates re-render the summary reactively', async () => {
+    const el = mount(`<form-popover-ui label="Old"><check-ui label="a" checked></check-ui></form-popover-ui>`);
+    el.label = 'New';
+    await Promise.resolve();
+    expect(el.querySelector('[data-form-popover-trigger]').getAttribute('text')).toBe('New · 1 selected');
+  });
+
+  it('disconnect removes the summary listener (no stale updates after removal)', () => {
+    const el = mount(`<form-popover-ui label="x"><check-ui label="a"></check-ui></form-popover-ui>`);
+    const trigger = el.querySelector('[data-form-popover-trigger]');
+    el.remove();
+    el.querySelector('check-ui').setAttribute('checked', '');
+    el.dispatchEvent(new Event('change', { bubbles: true }));
+    expect(trigger.getAttribute('text')).toBe('x · 1 total');
+  });
+});

package/form/form-popover/form-popover.yaml

@@ -0,0 +1,123 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: FormPopover
+tag: form-popover-ui
+status: experimental
+component: FormPopover
+category: input
+version: 1
+description: |
+  Module-tier "form fragment in a popover" (operator mock, 2026-07-27): a
+  select-style summary trigger that opens an anchored panel holding ANY
+  form primitives — check-ui groups, radio-ui groups, input-ui,
+  divider-ui, field-ui — slotted as ordinary light-DOM children. The
+  module owns the trigger + popover packaging and a live selection
+  summary; the slotted controls keep their own name/value/event
+  contracts untouched.
+
+  Summary contract: the trigger reads `{label} · N selected` while any
+  slotted check-ui is checked, `{label} · N total` when none are (N =
+  check-ui count), and just `{label}` when the fragment contains no
+  check-ui at all. Radio groups, inputs, and other controls deliberately
+  do not count — checkboxes are the only "N selected" semantic that
+  reads unambiguously in a summary.
+
+  Decision rule vs adjacent surfaces (inherits popover-ui's): a pure
+  action list is menu-ui; a single-value choice is select-ui (which owns
+  its option list — do NOT rebuild select inside this module); an
+  edge-anchored multi-field form is drawer-ui. form-popover-ui is for the
+  in-between: a small anchored fragment mixing selection controls and
+  inputs, e.g. a filter panel or a quick-save form.
+
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - popover-ui
+  - button-ui
+props:
+  label:
+    description: |
+      Summary-trigger prefix ("Option items"). The live count is
+      appended after a middle dot; with no count the label renders
+      alone. Required — with no label AND no check-ui children the
+      trigger would otherwise be an empty, nameless button; the runtime
+      falls back to "Options" in that state as a defensive accessible
+      name, but authors must set a real label.
+    type: string
+    required: true
+    default: ""
+    reflect: true
+
+  heading:
+    description: |
+      Optional panel heading rendered above the slotted fragment inside
+      the popover ("Select options"). Empty = no heading row.
+    type: string
+    default: ""
+    reflect: true
+
+  placement:
+    description: |
+      Passed through to the internal popover-ui. `bottom-start` default
+      per ADR-0034 — the panel is trigger-anchored and roughly
+      trigger-width, like a select listbox.
+    type: string
+    default: bottom-start
+    reflect: true
+
+events:
+  summary-change:
+    description: |
+      Fired (bubbling) whenever the selection summary recomputes —
+      detail: { selected, total }. The slotted controls' own change /
+      input events bubble through untouched; listen to those for
+      values.
+slots:
+  default:
+    description: |
+      The form fragment. Any AdiaUI form primitives, in author order —
+      check-ui, radio-ui, input-ui, divider-ui, field-ui, textarea-ui.
+      Adopted into the popover panel on connect; DOM order is layout
+      order (light-DOM contract).
+icons:
+  - caret-down            # summary-trigger chevron (button-ui[icon-trailing])
+a2ui:
+  category: input
+  description: Summary-trigger popover holding an arbitrary form fragment (checkbox groups, radio groups, inputs).
+  rules:
+    - >-
+      Children are the form fragment, in author order: CheckBox, Radio,
+      Input, Textarea, Divider, Field. Do NOT put Option children here —
+      a single-value option list is Select's contract; FormPopover never
+      rebuilds it.
+    - >-
+      Decision rule vs siblings: single-value choice → Select (with
+      multiple:true for multi-select chips); pure action list → Menu;
+      edge-anchored multi-field form → Drawer. FormPopover is only for a
+      small MIXED fragment (checks + radios + an input) behind a summary
+      trigger.
+    - >-
+      The trigger summary counts CheckBox children only ("N selected" /
+      "N total"); Radio and Input children never count. Give every Radio
+      child one shared name per group or the browser treats them as
+      independent.
+  props:
+    label: { type: string, description: "Summary-trigger prefix text" }
+    heading: { type: string, description: "Optional panel heading" }
+    placement: { type: string, description: "Popover placement (default bottom-start)" }
+  children: form primitives (CheckBox, Radio, Input, Divider, Field)
+examples:
+  - name: filter-popover
+    description: Filter fragment — checkbox group + divider + radio pair + name input behind a summary trigger.
+    a2ui: >-
+      [
+        {"id": "root", "component": "FormPopover", "label": "Option items", "heading": "Select options", "children": ["c1", "c2", "c3", "d1", "r1", "r2", "d2", "name"]},
+        {"id": "c1", "component": "CheckBox", "label": "Option item", "checked": true},
+        {"id": "c2", "component": "CheckBox", "label": "Option item"},
+        {"id": "c3", "component": "CheckBox", "label": "Option item", "checked": true},
+        {"id": "d1", "component": "Divider"},
+        {"id": "r1", "component": "Radio", "name": "mode", "label": "Save", "checked": true},
+        {"id": "r2", "component": "Radio", "name": "mode", "label": "Delete"},
+        {"id": "d2", "component": "Divider"},
+        {"id": "name", "component": "Input", "placeholder": "Option name"}
+      ]

package/form/index.js

@@ -0,0 +1 @@
+export { FormPopover } from './form-popover/form-popover.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.8.18",
+  "version": "0.8.19",
   "description": "AdiaUI composite custom elements \u2014 shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {
@@ -235,6 +235,10 @@
     "!generative/**/*.examples.html",
     "!generative/**/*.examples.js",
     "!generative/**/*.html",
+    "form/",
+    "!form/**/*.examples.html",
+    "!form/**/*.examples.js",
+    "!form/**/*.html",
     "index.js",
     "css-module.d.ts",
     "web-modules.sheet.d.ts",