@adia-ai/web-modules 0.8.17 → 0.8.19

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.17",
+  "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",