@adia-ai/web-modules 0.8.35 → 0.8.37

package/settings/notification-preferences/notification-preferences.yaml

@@ -0,0 +1,358 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UINotificationPreferences
+tag: notification-preferences-ui
+status: stable
+component: NotificationPreferences
+category: container
+version: 1
+description: |
+  Page-level Settings composite: a matrix of notification types (rows)
+  × delivery channels (columns: in-app, email, SMS) with a binary
+  <check-ui> in each cell and an optional <switch-ui> column-header
+  master toggle for bulk-flipping a channel across every row.
+
+  Form-bearing — the composite extends UIFormElement and serializes its
+  current preferences shape as JSON on `value`. Per first-principle #2
+  ("save is the consumer's job"), the composite does NOT mutate the
+  passed-in `preferences` array; it emits a typed `change` event per
+  cell toggle and a `bulk-toggle` event per column-header switch, and
+  exposes the staged JSON via the form value so a host <form> submit
+  carries it through ElementInternals.
+
+  Channels are columns; types are rows (the smaller-set / larger-set
+  invariant — channels are 3-5 in the wild, types are 10-50). Layout
+  renders as a semantic ARIA grid (`role="table"`/`row`/`cell`/
+  `rowheader`/`columnheader`) — NOT native `<table>` (per the HTML
+  parser strip rule, table-content tags would foster-parent out of a
+  custom-element subtree).
+
+  Spec: .claude/docs/specs/implementation-ready/SPEC-064-notification-preferences.md.
+
+# Per ADR-0027 — composites do NOT auto-import the primitives they
+# stamp in connected()/render(). The consumer (or this primitive's
+# .html demo shell) must explicitly side-effect-import each one.
+composes:
+  - check-ui
+  - switch-ui
+  - icon-ui
+  - text-ui
+  - empty-state-ui
+
+props:
+  preferences:
+    description: |
+      Matrix data — one row per notification type. Each record carries
+      a stable `key`, a `label`, optional `description` (rendered under
+      the label), optional `group` (when `group-by="group"`), and a
+      `channels` map keyed by channel key with boolean values.
+      Example: {key:"mentions", label:"Mentions", channels:{"in-app":true,
+      email:false, sms:false}}. Empty array renders the empty state.
+    type: array
+    default: []
+    dynamic: true
+    required: true
+
+  channels:
+    description: |
+      Column definitions — one record per delivery channel. Each
+      carries a stable `key`, a `label` (the column header), and an
+      optional `icon` name (Phosphor — defaults to no icon when
+      absent). Example: [{key:"in-app", label:"In-app", icon:"chat-circle"},
+      {key:"email", label:"Email", icon:"envelope"}]. Empty array
+      renders nothing (the matrix needs at least one column).
+    type: array
+    default: []
+    dynamic: true
+    required: true
+
+  channelEnabled:
+    description: |
+      Map of channel-key → master-toggle boolean for the column-header
+      <switch-ui>. When omitted, master toggles default to `true` for
+      every channel. Independent of cell values — toggling the master
+      off does NOT auto-update the cells; the host receives a
+      `bulk-toggle` event and updates `preferences` itself.
+    type: object
+    default: {}
+    dynamic: true
+
+  loading:
+    description: |
+      Renders a skeleton matrix overlay. Cells become non-interactive
+      and dim while loading.
+    type: boolean
+    default: false
+    reflect: true
+
+  disabled:
+    description: All cells + master toggles become non-interactive.
+    type: boolean
+    default: false
+    reflect: true
+
+  group-by:
+    description: |
+      Row-grouping mode. `none` (default) renders all rows in one
+      block. `group` renders one section per unique `preferences[].group`
+      value with a header row above each section.
+    type: string
+    default: "none"
+    enum:
+      - none
+      - group
+    reflect: true
+
+events:
+  change:
+    description: |
+      Fired when the user toggles a cell <check-ui>. Bubbles. The
+      composite emits this with the previous state — the host must
+      apply the new state to its own data and re-pass `preferences`
+      for the cell to visually update.
+    detail:
+      row:
+        type: string
+        description: The `key` of the notification type whose cell flipped.
+      channel:
+        type: string
+        description: The `key` of the channel column whose cell flipped.
+      enabled:
+        type: boolean
+        description: The new desired state (true = opted in).
+
+  bulk-toggle:
+    description: |
+      Fired when the user toggles a column-header <switch-ui>.
+      Bubbles. Mirrors `change` shape but for the column master —
+      host applies the bulk change to its own `preferences` data.
+    detail:
+      channel:
+        type: string
+        description: The `key` of the channel column whose master flipped.
+      enabled:
+        type: boolean
+        description: The new desired master state.
+
+slots:
+  header:
+    description: |
+      Optional content above the matrix — e.g. a page title, intro
+      copy, or per-page save row. Falls back to nothing when empty.
+
+  footer:
+    description: |
+      Optional content below the matrix — e.g. a global Save Changes
+      button row or fine-print disclaimer. Falls back to nothing.
+
+  empty:
+    description: |
+      Custom empty-state copy shown when `preferences` is empty. Falls
+      back to a default <empty-state-ui> when not provided.
+
+states:
+  - name: idle
+    description: Default — matrix rendered, ready for interaction.
+  - name: loading
+    description: Skeleton overlay while data loads.
+    attribute: loading
+  - name: disabled
+    description: All toggles non-interactive.
+    attribute: disabled
+  - name: empty
+    description: No notification types configured.
+    attribute: empty
+
+traits: []
+
+tokens:
+  --notification-preferences-bg:
+    description: Host background.
+    default: var(--a-bg)
+  --notification-preferences-row-bg:
+    description: Even-row zebra background.
+    default: var(--a-bg-muted)
+  --notification-preferences-px:
+    description: Host horizontal padding.
+    default: var(--a-space-5)
+  --notification-preferences-py:
+    description: Host vertical padding.
+    default: var(--a-space-5)
+  --notification-preferences-row-py:
+    description: Per-row vertical padding.
+    default: var(--a-space-3)
+  --notification-preferences-row-px:
+    description: Per-cell horizontal padding.
+    default: var(--a-space-3)
+  --notification-preferences-channel-width:
+    description: Minimum column width for each channel cell.
+    default: var(--a-space-9)
+  --notification-preferences-row-label-min:
+    description: Minimum row-label column width.
+    default: 12rem
+  --notification-preferences-border:
+    description: Row separator color.
+    default: var(--a-border-subtle)
+  --notification-preferences-radius:
+    description: Outer matrix container radius.
+    default: var(--a-radius-md)
+  --notification-preferences-group-fg:
+    description: Group-heading label color.
+    default: var(--a-fg-muted)
+
+requiredIcons:
+  - bell
+  - envelope
+  - device-mobile
+  - chat-circle
+
+a2ui:
+  rules:
+    - >-
+      NotificationPreferences.channels MUST be non-empty. A matrix with
+      zero columns renders nothing meaningful — author at least one
+      channel record.
+    - >-
+      NotificationPreferences.preferences[].channels keys MUST match the
+      channels[].key set. Mismatched keys silently render the cell as
+      `false` (off) — they do NOT raise an error, but the user can never
+      toggle them into existence either.
+    - >-
+      The composite is fully CONTROLLED — toggling a cell does NOT
+      mutate `preferences`. The host MUST listen for `change` (and
+      `bulk-toggle` for the column master), apply the change to its
+      own state, then re-pass the new `preferences` array. Failing to
+      do this leaves the toggle visually flipping back to its prior
+      state on the next render.
+    - >-
+      For binary on/off cell toggles, use <check-ui> semantics — NOT
+      <switch-ui>. The column-header master IS a <switch-ui> (because
+      it's a "setting" — flip the whole column), but each cell is a
+      multi-select-style checkbox.
+    - >-
+      Use `group-by="group"` only when `preferences[]` records carry a
+      stable `group` field. Mixing grouped + ungrouped rows in the
+      same matrix produces inconsistent section heights.
+
+anti_patterns:
+  - wrong: |
+      <notification-preferences-ui>
+        <switch-ui label="Email mentions"></switch-ui>
+        <switch-ui label="Email replies"></switch-ui>
+      </notification-preferences-ui>
+    why: |
+      Cells are generated from the `preferences` matrix. Slotted
+      switches are ignored and the host renders empty.
+    fix: |
+      <notification-preferences-ui id="prefs"></notification-preferences-ui>
+      <script>
+        document.querySelector('#prefs').channels = [
+          {key:'email', label:'Email'}
+        ];
+        document.querySelector('#prefs').preferences = [
+          {key:'mentions', label:'Mentions', channels:{email:true}},
+          {key:'replies',  label:'Replies',  channels:{email:false}}
+        ];
+      </script>
+  - wrong: |
+      <table>
+        <thead><tr><th></th><th>Email</th></tr></thead>
+        <tbody>
+          <tr><th>Mentions</th><td><check-ui></check-ui></td></tr>
+        </tbody>
+      </table>
+    why: |
+      Re-implements the matrix in raw HTML — loses the typed
+      `change` / `bulk-toggle` event contract, the column-master
+      switch, the group-by support, and the consistent token-driven
+      visual treatment. Worse, table-content tags inside a custom
+      element subtree are foster-parented out of the DOM by the HTML
+      parser — they silently vanish.
+    fix: |
+      <notification-preferences-ui id="prefs"></notification-preferences-ui>
+      <script>/* set channels + preferences here */</script>
+
+examples:
+  - name: default
+    description: Three channels (in-app / email / SMS) × four notification types.
+    a2ui: |
+      [
+        {
+          "id": "np-default",
+          "component": "NotificationPreferences",
+          "name": "notifications",
+          "channels": [
+            {"key": "in-app", "label": "In-app", "icon": "chat-circle"},
+            {"key": "email",  "label": "Email",  "icon": "envelope"},
+            {"key": "sms",    "label": "SMS",    "icon": "device-mobile"}
+          ],
+          "preferences": [
+            {"key": "mentions", "label": "Mentions",
+             "channels": {"in-app": true, "email": true,  "sms": false}},
+            {"key": "comments", "label": "Comments",
+             "channels": {"in-app": true, "email": false, "sms": false}},
+            {"key": "releases", "label": "Releases",
+             "channels": {"in-app": false,"email": true,  "sms": false}},
+            {"key": "security", "label": "Security alerts",
+             "channels": {"in-app": true, "email": true,  "sms": true}}
+          ]
+        }
+      ]
+  - name: grouped
+    description: Same matrix grouped by category via group-by="group".
+    a2ui: |
+      [
+        {
+          "id": "np-grouped",
+          "component": "NotificationPreferences",
+          "name": "notifications",
+          "groupBy": "group",
+          "channels": [
+            {"key": "in-app", "label": "In-app"},
+            {"key": "email",  "label": "Email"}
+          ],
+          "preferences": [
+            {"key": "mentions", "label": "Mentions", "group": "Activity",
+             "channels": {"in-app": true, "email": true}},
+            {"key": "comments", "label": "Comments", "group": "Activity",
+             "channels": {"in-app": true, "email": false}},
+            {"key": "digest",   "label": "Weekly digest", "group": "Summaries",
+             "channels": {"in-app": false, "email": true}}
+          ]
+        }
+      ]
+
+keywords:
+  - notification-preferences
+  - notifications
+  - preferences
+  - opt-in
+  - opt-out
+  - alerts
+  - channels
+  - in-app
+  - email
+  - sms
+  - subscriptions
+  - notification-settings
+
+synonyms:
+  notifications:
+    - alerts
+    - messages
+    - updates
+  preferences:
+    - settings
+    - opt-ins
+    - subscriptions
+  channels:
+    - delivery
+    - destinations
+
+related:
+  - Check
+  - Switch
+  - Table
+  - EmptyState
+  - Icon
+  - Text

package/shell/admin-command/admin-command.js

@@ -36,8 +36,8 @@
  * should prefer <admin-command>.
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 class AdminCommand extends UIElement {
   static properties = {

package/shell/admin-shell/admin-shell.js

@@ -29,8 +29,8 @@
  *   4. command-select re-emit + nav routing when a <nav-ui> is present
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 const DEFAULT_MODE = 'rounded borderless';
 

package/shell/admin-sidebar/admin-sidebar.js

@@ -37,8 +37,8 @@
  * code should prefer <admin-sidebar>.
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 const SNAP_THRESHOLD = 96;
 const SNAP_MIN_USABLE = 160;

package/shell/embed-shell/embed-shell.js

@@ -31,9 +31,9 @@
  * edge to resize + a `resize-end` event), not a CSS stand-in. The trait is imported
  * here so it's registered for declarative lookup.
  */
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
-import '../../../web-components/traits/resizable/resizable.js'; // register `resizable` for traits="resizable"
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
+import '@adia-ai/web-components/traits'; // registers the full trait library (incl. `resizable`) for declarative traits="resizable" lookup
 
 class EmbedShell extends UIElement {
   static template = () => null; // behavior-only, light-DOM — keep the consumer's children

package/simple/simple-shell/simple-shell.js

@@ -1,4 +1,4 @@
-import { UIElement } from '../../../web-components/core/element.js';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 /**
  * <simple-shell> — Minimal shell for marketing / landing / error pages.

package/theme/theme-panel/theme-panel.js

@@ -51,8 +51,8 @@
  *   theme-panel[active-scheme="dark"] button-ui { … }
  */
 
-import { defineIfFree } from '../../../web-components/core/register.js';
-import { UIElement } from '../../../web-components/core/element.js';
+import { defineIfFree } from '@adia-ai/web-components/core/register';
+import { UIElement } from '@adia-ai/web-components/core/element';
 
 // The 12 named identities shipped in styles/themes.css (real recolor +
 // real typeface pairing per theme, not a decorative hue nudge) — see that