@adia-ai/web-components 0.8.44 → 0.8.45

package/core/store.js

@@ -0,0 +1,89 @@
+/**
+ * AdiaUI shared app store — the blessed R2 primitive.
+ *
+ * A signal-backed replacement for the Set-of-listeners pub/sub pattern
+ * hand-rolled across the app layer: plan-store, data-client, patient-visit
+ * record, persona store, task-service, a2ui BaseController, a2ui Surface
+ * watchers (reactivity review, .claude/docs/reports/2026-08-20-reactivity-
+ * review/03-app-layer-stores.md §4). Doctrine's pattern menu row 1 says
+ * reactive state -> signals; `createStore` is `signal()` plus the one thing
+ * those seven stores actually needed on top of it: an imperative
+ * `subscribe(cb) -> unsubscribe` channel for consumers that are closures or
+ * classes rather than `effect()` bodies.
+ *
+ * `.value` reads/writes pass straight through to a real `signal()`, so a
+ * store composes with `computed()`/`effect()` exactly like any other signal
+ * (tracked reads, `Object.is` no-notify, microtask-batched effect re-runs).
+ * `subscribe()` is the separate, synchronous, imperative channel the seven
+ * hand-rolled stores already share — same shape, so migrating one onto this
+ * primitive is a mechanical swap (opportunistic, later, per store; this
+ * primitive lands with NO migration).
+ *
+ * Interops with `UIElement`'s `controller` setter (`core/element.js`)
+ * out of the box: `element.controller = store` wires `store.subscribe(fn)`
+ * into the element's own render-trigger machinery — the setter calls
+ * `c.connect?.(this)` / `c.subscribe?.(...)` / `c.disconnect?.(this)`, all
+ * optional-chained, and `subscribe()` alone satisfies that contract.
+ *
+ * Rejected alternative: promoting/absorbing `BaseController`
+ * (`core/controller.js`) into this role, per the reactivity review's F5.
+ * BaseController's `connect()` bakes in schema/`getState()` validation
+ * (dev-warns without a static `schema`, dev-errors without an overridden
+ * `getState()`) that exists to serve DOM-reflecting UI controllers
+ * (`RouteController`'s attributes/commands surface) — semantics a plain
+ * data store has no use for and would either have to satisfy with a dummy
+ * schema or suppress. The one thing BaseController actually offers this
+ * role — the `subscribe(fn) -> unsubscribe` shape the controller setter
+ * expects — costs nothing to reimplement directly on `signal()`, and doing
+ * so keeps the store from inheriting a validation path built for a
+ * different kind of thing. BaseController stays as-is; still one consumer
+ * (`RouteController` / `<router-ui>`), still F5's to resolve separately.
+ *
+ * @see ../USAGE.md
+ * @see ./element.js (the `controller` setter this interops with)
+ * @see ./controller.js (BaseController — the rejected alternative above)
+ */
+
+import { signal } from './signals.js';
+
+export function createStore(initial) {
+  const s = signal(initial);
+  const listeners = new Set();
+
+  return {
+    get value() {
+      return s.value;
+    },
+    set value(next) {
+      // Object.is no-notify guard — matches persona-store's proven
+      // behavior (packages/llm/persona/src/store.ts) and the underlying
+      // signal's own equality cutoff. Checked here, not inferred from
+      // signal()'s silent no-op, so an identical write never reaches
+      // `listeners` either.
+      const changed = !Object.is(s.peek(), next);
+      s.value = next;
+      if (changed) {
+        // Pass the captured `next`, never re-read `s.peek()` here — a
+        // listener that re-entrantly writes `store.value` during this
+        // loop would otherwise make every later listener observe THAT
+        // write's value instead of this one's, silently skipping the
+        // value this write actually delivered.
+        for (const cb of listeners) cb(next);
+      }
+    },
+    /** Read without subscribing the surrounding `effect()`. */
+    peek() {
+      return s.peek();
+    },
+    /**
+     * Set-of-listeners-compatible subscribe. `cb` receives the new value;
+     * callers that only care that *something* changed (the
+     * `UIElement.controller` setter among them) simply ignore the
+     * argument. Returns an unsubscribe function.
+     */
+    subscribe(cb) {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+  };
+}

package/custom-elements.json

@@ -3271,7 +3271,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Right-click activated menu — the OS-native context-menu pattern as a web component. Distinct from `menu-ui` (which is button-triggered): same item shape (`menu-item-ui` children), different trigger surface (`contextmenu` event), and pointer-anchored positioning instead of element-anchored. Pattern: WAI-APG Menu. Two binding modes: **A. Wrap.** Default-slot child becomes the target: `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`. **B. Selector.** Point at one or more existing elements via [for]: `<context-menu-ui for=\"#my-table\">...items</context-menu-ui>`. On `contextmenu` event on a target: `preventDefault()`, position the menu at the pointer coords, show via Popover API. Touch long-press (configurable via [long-press-ms]) does the same. Shift+F10 / Menu key opens at the focused target's center for keyboard users.",
+          "description": "Right-click activated menu — the OS-native context-menu pattern as a web component. Distinct from `menu-ui` (which is button-triggered): same item shape (`menu-item-ui` children), different trigger surface (`contextmenu` event), and pointer-anchored positioning instead of element-anchored. Pattern: WAI-APG Menu. Two binding modes: **A. Wrap.** Default-slot child becomes the target: `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`. **B. Selector.** Point at one or more existing elements via [target-selector]: `<context-menu-ui target-selector=\"#my-table\">...items</context-menu-ui>`. On `contextmenu` event on a target: `preventDefault()`, position the menu at the pointer coords, show via Popover API. Touch long-press (configurable via [long-press-ms]) does the same. Shift+F10 / Menu key opens at the focused target's center for keyboard users.",
           "name": "UIContextMenu",
           "tagName": "context-menu-ui",
           "superclass": {
@@ -3279,12 +3279,19 @@
             "module": "/core/element.js"
           },
           "attributes": [
+            {
+              "name": "target-selector",
+              "type": {
+                "text": "string"
+              },
+              "description": "CSS selector(s) for target element(s). Empty = use default-slot child. Ratified name (gh#1764/#1780, ADR-0079) for what [for] used to carry — [for] means an id-ref everywhere else in AdiaUI (table-toolbar-ui, chart-legend-ui, tooltip-ui); context-menu-ui's own selector meaning predates that convention and was a same-name/ different-contract collision (ADR-0053's no-shadowing doctrine)."
+            },
             {
               "name": "for",
               "type": {
                 "text": "string"
               },
-              "description": "CSS selector(s) for target element(s). Empty = use default-slot child."
+              "description": "DEPRECATED alias for [target-selector] — still a CSS selector, NOT an id-ref. Honored when [target-selector] is unset, with a one-shot console.warn pointing consumers at the replacement. New authoring should use [target-selector]."
             },
             {
               "name": "open",
@@ -6519,7 +6526,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only."
+              "description": "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below."
             },
             {
               "name": "multi-expand",
@@ -6533,7 +6540,7 @@
           "slots": [
             {
               "name": "default",
-              "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+              "description": "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers and <span data-nav-label> for hand-placed group-label kickers (titled runs of items/groups that aren't wrapped in a <nav-group-ui>). <span data-nav-label> renders with the same uppercase/tracking/muted kicker treatment as the [heading] ::before kicker, and is hidden alongside dividers whenever the primary-variant rail collapses ([collapsed] or ≤96px container width)."
             }
           ],
           "events": [
@@ -8566,6 +8573,14 @@
               },
               "description": "Label text above the trigger"
             },
+            {
+              "name": "label-hidden",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, [label] still sets the accessible name (aria-label) but the visible `::before` text is suppressed via the canonical sr-only technique (gh#1748, mirrors check-ui's [label-hidden], gh#1010). Use when a sibling/ancestor composition already conveys the same name visually (e.g. a scope/view-switcher select in a table-toolbar-ui [slot=\"scope\"], where the toolbar's own title already names the view) and a second visible \"Scope\"-style label would paint it twice."
+            },
             {
               "name": "hint",
               "type": {
@@ -10089,6 +10104,41 @@
                 "text": "CustomEvent"
               },
               "description": "Page-size select changed. Detail: { pageSize }."
+            },
+            {
+              "name": "toolbar-search",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "gh#1764/#1780, ADR-0079 (events-only interaction contract) — dispatched directly at the resolved [for] target (not bubbled from this element) in place of the pre-#1780 direct `.search =` write. table-ui listens for this on itself. Detail: { value }."
+            },
+            {
+              "name": "toolbar-filter-set",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.setFilter()` call. table-ui listens for this on itself. Detail: { key, value, op }; a null `value` clears that one column's filter."
+            },
+            {
+              "name": "toolbar-filter-clear",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.clearFilters()` call. table-ui listens for this on itself. No detail."
+            },
+            {
+              "name": "toolbar-columns-set",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.columns =` write. table-ui listens for this on itself. Detail: { columns }."
+            },
+            {
+              "name": "toolbar-paginate",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "gh#1764/#1780, ADR-0079 — dispatched directly at the resolved [for] target in place of the pre-#1780 direct `target.paginate =` write. table-ui listens for this on itself. Detail: { pageSize }."
             }
           ]
         }