@adia-ai/web-modules 0.8.36 → 0.8.37

package/settings/notification-preferences/notification-preferences.js

@@ -0,0 +1,622 @@
+/**
+ * <notification-preferences-ui> — Module-tier Settings composite.
+ *
+ *   <notification-preferences-ui id="prefs" name="notifications">
+ *   </notification-preferences-ui>
+ *   <script>
+ *     const el = document.querySelector('#prefs');
+ *     el.channels = [
+ *       { key: 'in-app', label: 'In-app', icon: 'chat-circle' },
+ *       { key: 'email',  label: 'Email',  icon: 'envelope' },
+ *       { key: 'sms',    label: 'SMS',    icon: 'device-mobile' }
+ *     ];
+ *     el.preferences = [
+ *       { key: 'mentions', label: 'Mentions',
+ *         channels: { 'in-app': true, email: true, sms: false } },
+ *       { key: 'releases', label: 'Releases',
+ *         channels: { 'in-app': false, email: true, sms: false } }
+ *     ];
+ *     el.addEventListener('change',      (e) => save(e.detail));
+ *     el.addEventListener('bulk-toggle', (e) => bulkSave(e.detail));
+ *   </script>
+ *
+ * Composes <check-ui> (per-cell binary toggle) + <switch-ui> (column-
+ * master master) + <icon-ui> (channel-header icons) + <text-ui> +
+ * <empty-state-ui>. Renders as an ARIA grid via role="table"/row/cell/
+ * rowheader/columnheader on plain <div> nodes — NOT native <table>
+ * (HTML parser strips <thead>/<tbody>/<tr>/<th>/<td> out of custom-
+ * element subtrees per FEEDBACK rule).
+ *
+ * Form participation:
+ *   Extends UIFormElement. The `value` is a JSON string of the current
+ *   preferences shape ({preferences, channelEnabled}) serialized via
+ *   ElementInternals.setFormValue. A host <form> submit carries the
+ *   matrix through standard form semantics; the composite never mutates
+ *   the passed-in `preferences` (host-controlled per spec).
+ *
+ * Architecture (light-DOM, ADR-0033):
+ *   First-connect stamps a four-region skeleton (header · matrix ·
+ *   empty · footer). Subsequent renders mutate the matrix subtree by
+ *   id-keyed in-place diff so focus survives toggling.
+ *
+ * Per ADR-0027 — composites that programmatically create primitives in
+ * their render() do NOT auto-import those primitives. Consumer (or
+ * demo shell) must explicitly import <check-ui>, <switch-ui>,
+ * <icon-ui>, <text-ui>, <empty-state-ui> in addition to this module.
+ */
+
+import { UIFormElement } from '@adia-ai/web-components/core/form';
+import { untracked } from '@adia-ai/web-components/core/signals';
+
+class UINotificationPreferences extends UIFormElement {
+  static get properties() {
+    return {
+      ...UIFormElement.properties,
+      preferences:    { type: Array,   default: [] },
+      channels:       { type: Array,   default: [] },
+      channelEnabled: { type: Object,  default: {} },
+      loading:        { type: Boolean, default: false, reflect: true },
+      disabled:       { type: Boolean, default: false, reflect: true },
+      'group-by':     { type: String,  default: 'none', reflect: true },
+    };
+  }
+
+  // Composite stamps a fixed region skeleton once and mutates the
+  // matrix subtree across renders. Returning html`` from template()
+  // would trigger stamp() → replaceChildren() and wipe authored slot
+  // children (same rationale as plan-picker / confirm-dialog).
+  static template = () => null;
+
+  // ── Field refs ────────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+  #headerHost = null;
+  #matrixHost = null;
+  #headerRow = null;
+  #bodyHost = null;
+  #emptyHost = null;
+  #footerHost = null;
+  #rowsByKey = new Map();      // row-key → <div role="row">
+  #cellsByKey = new Map();     // `${row}::${channel}` → <check-ui>
+  #headerCellsByKey = new Map(); // channel-key → <div role="columnheader">
+  #masterByKey = new Map();    // channel-key → <switch-ui> column master
+  #groupHeadingsByKey = new Map(); // group-key → <div data-part="group-heading">
+  #internalUpdate = false;
+  #headerId = `np-h-${Math.random().toString(36).slice(2, 8)}`;
+
+  // ── attribute parsing — preferences / channels / channelEnabled
+  //    accept JSON via the HTML attribute path (canonical authoring
+  //    shape for a2ui-generated markup). Default UIElement attribute
+  //    reflection would assign the string verbatim and break the
+  //    array/object shape; parse here.
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (name === 'preferences' || name === 'channels' || name === 'channelenabled') {
+      // Key-cased prop name (preferences, channels, channelEnabled);
+      // the attribute is always lower-case so map back.
+      const propName = name === 'channelenabled' ? 'channelEnabled' : name;
+      if (newVal == null) {
+        this[propName] = (propName === 'channelEnabled') ? {} : [];
+      } else {
+        try {
+          const parsed = JSON.parse(newVal);
+          if (propName === 'channelEnabled') {
+            this[propName] = (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+              ? parsed : {};
+          } else {
+            this[propName] = Array.isArray(parsed) ? parsed : [];
+          }
+        } catch {
+          this[propName] = (propName === 'channelEnabled') ? {} : [];
+        }
+      }
+      return;
+    }
+    super.attributeChangedCallback?.(name, oldVal, newVal);
+  }
+
+  // ── Lifecycle ─────────────────────────────────────────────────────
+
+  connected() {
+    super.connected();
+
+    // ARIA landmark + accessible name. Don't steal a host-supplied
+    // aria-label; default to a sensible string.
+    if (!this.hasAttribute('aria-label') && !this.hasAttribute('aria-labelledby')) {
+      this.setAttribute('aria-label', 'Notification preferences');
+    }
+    this.setAttribute('role', 'region');
+
+    if (!this.#stamped) {
+      // Late-parse JSON attrs that were present at construct time
+      // (UIElement reads attributes as String on first connect).
+      if (this.hasAttribute('preferences') && !Array.isArray(this.preferences)) {
+        try { this.preferences = JSON.parse(this.getAttribute('preferences')); }
+        catch { this.preferences = []; }
+      }
+      if (this.hasAttribute('channels') && !Array.isArray(this.channels)) {
+        try { this.channels = JSON.parse(this.getAttribute('channels')); }
+        catch { this.channels = []; }
+      }
+      if (this.hasAttribute('channelenabled') &&
+          (typeof this.channelEnabled !== 'object' || Array.isArray(this.channelEnabled))) {
+        try { this.channelEnabled = JSON.parse(this.getAttribute('channelenabled')); }
+        catch { this.channelEnabled = {}; }
+      }
+
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+
+    // Trigger first render after the registry has had a chance to
+    // upgrade the composed primitives.
+    untracked(() => this.render());
+  }
+
+  disconnected() {
+    super.disconnected();
+    for (const fn of this.#cleanups) {
+      try { fn(); } catch { /* ignore stale */ }
+    }
+    this.#cleanups.length = 0;
+  }
+
+  // ── Form participation ────────────────────────────────────────────
+
+  /**
+   * The form value is the JSON-stringified current shape so a host
+   * <form> submit carries the matrix through standard form semantics.
+   * `value` is recomputed in render(); we override syncValue to read
+   * the live shape rather than the inherited `this.value`.
+   */
+  syncValue() {
+    const shape = {
+      preferences: Array.isArray(this.preferences) ? this.preferences : [],
+      channelEnabled: this.channelEnabled && typeof this.channelEnabled === 'object'
+        ? this.channelEnabled : {},
+    };
+    const serialized = JSON.stringify(shape);
+    this.value = serialized;
+    this.internals.setFormValue(serialized);
+  }
+
+  // ── Render — narrow; mutates matrix subtree only ──────────────────
+
+  render() {
+    if (!this.#stamped) return;
+
+    const channels = Array.isArray(this.channels) ? this.channels : [];
+    const prefs = Array.isArray(this.preferences) ? this.preferences : [];
+
+    // Empty-state attribute (CSS-gated reveal).
+    if (prefs.length === 0 || channels.length === 0) {
+      this.setAttribute('empty', '');
+    } else {
+      this.removeAttribute('empty');
+    }
+
+    // CSS column-template uses --np-columns; set it on the host so
+    // the grid-template-columns expansion is data-driven.
+    this.style.setProperty(
+      '--np-columns',
+      `repeat(${Math.max(channels.length, 1)}, minmax(var(--notification-preferences-channel-width, var(--notification-preferences-channel-width-default)), auto))`,
+    );
+
+    // Re-render the column headers (header row + column-masters).
+    this.#renderHeaderRow(channels);
+
+    // Re-render the body — grouped or flat.
+    const groupBy = this['group-by'] || 'none';
+    if (groupBy === 'group') {
+      this.#renderGroupedBody(prefs, channels);
+    } else {
+      this.#renderFlatBody(prefs, channels);
+    }
+
+    // Sync form value with current shape.
+    this.syncValue();
+  }
+
+  // ── Internal — DOM stamping ───────────────────────────────────────
+
+  #stamp() {
+    // Header slot host (consumer-supplied content above the matrix).
+    const header = document.createElement('div');
+    header.setAttribute('data-part', 'header');
+    const headerSlot = document.createElement('slot');
+    headerSlot.setAttribute('name', 'header');
+    header.appendChild(headerSlot);
+    this.appendChild(header);
+    this.#headerHost = header;
+
+    // Matrix host — the ARIA grid container.
+    const matrix = document.createElement('div');
+    matrix.setAttribute('data-part', 'matrix');
+    matrix.setAttribute('role', 'table');
+    matrix.setAttribute('aria-labelledby', this.#headerId);
+    this.appendChild(matrix);
+    this.#matrixHost = matrix;
+
+    // Column-header row — separate `data-part` so CSS can style it
+    // distinctly from body rows (no zebra).
+    const headerRow = document.createElement('div');
+    headerRow.setAttribute('data-part', 'header-row');
+    headerRow.setAttribute('role', 'row');
+    matrix.appendChild(headerRow);
+    this.#headerRow = headerRow;
+
+    // Body wrapper (zebra stripes target [data-part="body"] > [role="row"]).
+    const body = document.createElement('div');
+    body.setAttribute('data-part', 'body');
+    matrix.appendChild(body);
+    this.#bodyHost = body;
+
+    // Default empty-state (overridable via slot="empty").
+    const empty = document.createElement('div');
+    empty.setAttribute('data-part', 'empty');
+    const emptySlot = document.createElement('slot');
+    emptySlot.setAttribute('name', 'empty');
+    // Fallback content if no consumer slot content is provided.
+    const fallback = document.createElement('empty-state-ui');
+    fallback.setAttribute('icon', 'bell');
+    fallback.setAttribute('heading', 'No notification types configured');
+    fallback.setAttribute(
+      'description',
+      'Add at least one notification type and one delivery channel to begin.',
+    );
+    emptySlot.appendChild(fallback);
+    empty.appendChild(emptySlot);
+    this.appendChild(empty);
+    this.#emptyHost = empty;
+
+    // Footer slot host (consumer-supplied content below the matrix).
+    const footer = document.createElement('div');
+    footer.setAttribute('data-part', 'footer');
+    const footerSlot = document.createElement('slot');
+    footerSlot.setAttribute('name', 'footer');
+    footer.appendChild(footerSlot);
+    this.appendChild(footer);
+    this.#footerHost = footer;
+  }
+
+  // ── Internal — render header row (column headers) ─────────────────
+
+  #renderHeaderRow(channels) {
+    if (!this.#headerRow) return;
+
+    // First cell — empty row-label spacer (rowheader column).
+    let labelCell = this.#headerRow.querySelector(':scope > [data-row-label]');
+    if (!labelCell) {
+      labelCell = document.createElement('div');
+      labelCell.setAttribute('role', 'columnheader');
+      labelCell.setAttribute('data-row-label', '');
+      labelCell.id = this.#headerId;
+      labelCell.textContent = 'Notification';
+      this.#headerRow.appendChild(labelCell);
+    }
+
+    // Diff channel header cells by key.
+    const seen = new Set();
+    for (const channel of channels) {
+      if (!channel?.key) continue;
+      seen.add(channel.key);
+      let cell = this.#headerCellsByKey.get(channel.key);
+      if (!cell) {
+        cell = document.createElement('div');
+        cell.setAttribute('role', 'columnheader');
+        cell.setAttribute('data-channel-key', channel.key);
+        this.#headerRow.appendChild(cell);
+        this.#headerCellsByKey.set(channel.key, cell);
+      }
+      this.#decorateHeaderCell(cell, channel);
+    }
+
+    // Remove dropped header cells.
+    for (const [key, cell] of this.#headerCellsByKey) {
+      if (!seen.has(key)) {
+        try { cell.remove(); } catch { /* ignore */ }
+        this.#headerCellsByKey.delete(key);
+        this.#masterByKey.delete(key);
+      }
+    }
+
+    // Re-order header cells to match channels array.
+    for (const channel of channels) {
+      const cell = this.#headerCellsByKey.get(channel.key);
+      if (cell) this.#headerRow.appendChild(cell);
+    }
+  }
+
+  #decorateHeaderCell(cell, channel) {
+    // Wipe + restamp the small fixed shape (icon? + label + switch).
+    cell.replaceChildren();
+
+    if (channel.icon) {
+      const icon = document.createElement('icon-ui');
+      icon.setAttribute('name', String(channel.icon));
+      icon.setAttribute('aria-hidden', 'true');
+      cell.appendChild(icon);
+    }
+
+    const label = document.createElement('span');
+    label.setAttribute('data-channel-label', '');
+    label.textContent = String(channel.label || channel.key);
+    cell.appendChild(label);
+
+    // Column master <switch-ui>. The default master state is `true`
+    // unless the host explicitly set `channelEnabled[channel.key]`
+    // to false.
+    let master = this.#masterByKey.get(channel.key);
+    if (!master) {
+      master = document.createElement('switch-ui');
+      master.setAttribute('size', 'sm');
+      master.setAttribute('data-channel-master', channel.key);
+      this.#masterByKey.set(channel.key, master);
+    }
+    const enabledMap = this.channelEnabled && typeof this.channelEnabled === 'object'
+      ? this.channelEnabled : {};
+    const masterChecked = Object.prototype.hasOwnProperty.call(enabledMap, channel.key)
+      ? !!enabledMap[channel.key]
+      : true;
+    if (master.checked !== masterChecked) {
+      this.#internalUpdate = true;
+      try { master.checked = masterChecked; }
+      finally { this.#internalUpdate = false; }
+    }
+    master.setAttribute(
+      'aria-label',
+      `Toggle ${channel.label || channel.key} for all rows`,
+    );
+    if (this.disabled || this.loading) {
+      master.setAttribute('disabled', '');
+    } else {
+      master.removeAttribute('disabled');
+    }
+    cell.appendChild(master);
+  }
+
+  // ── Internal — render flat body (group-by="none") ─────────────────
+
+  #renderFlatBody(prefs, channels) {
+    if (!this.#bodyHost) return;
+
+    // Remove any group-heading rows from a prior grouped render.
+    for (const [, heading] of this.#groupHeadingsByKey) {
+      try { heading.remove(); } catch { /* ignore */ }
+    }
+    this.#groupHeadingsByKey.clear();
+
+    const seenRows = new Set();
+    const seenCells = new Set();
+
+    for (const pref of prefs) {
+      if (!pref?.key) continue;
+      seenRows.add(pref.key);
+      const row = this.#getOrCreateRow(pref);
+      this.#decorateRow(row, pref, channels, seenCells);
+    }
+
+    // Remove dropped rows.
+    for (const [key, row] of this.#rowsByKey) {
+      if (!seenRows.has(key)) {
+        try { row.remove(); } catch { /* ignore */ }
+        this.#rowsByKey.delete(key);
+      }
+    }
+
+    // Remove dropped cells.
+    for (const [key, cell] of this.#cellsByKey) {
+      if (!seenCells.has(key)) {
+        try { cell.remove(); } catch { /* ignore */ }
+        this.#cellsByKey.delete(key);
+      }
+    }
+
+    // Re-order rows to match preferences array.
+    for (const pref of prefs) {
+      const row = this.#rowsByKey.get(pref.key);
+      if (row) this.#bodyHost.appendChild(row);
+    }
+  }
+
+  // ── Internal — render grouped body (group-by="group") ─────────────
+
+  #renderGroupedBody(prefs, channels) {
+    if (!this.#bodyHost) return;
+
+    // Bucket rows by `group` field (preserve first-seen order).
+    const order = [];
+    const byGroup = new Map();
+    for (const pref of prefs) {
+      const g = String(pref?.group ?? 'Other') || 'Other';
+      if (!byGroup.has(g)) {
+        byGroup.set(g, []);
+        order.push(g);
+      }
+      byGroup.get(g).push(pref);
+    }
+
+    const seenGroups = new Set();
+    const seenRows = new Set();
+    const seenCells = new Set();
+
+    for (const groupKey of order) {
+      seenGroups.add(groupKey);
+      // Group heading row.
+      let heading = this.#groupHeadingsByKey.get(groupKey);
+      if (!heading) {
+        heading = document.createElement('div');
+        heading.setAttribute('data-part', 'group-heading');
+        heading.setAttribute('data-group', groupKey);
+        heading.setAttribute('role', 'rowgroup');
+        this.#groupHeadingsByKey.set(groupKey, heading);
+      }
+      heading.textContent = groupKey;
+      this.#bodyHost.appendChild(heading);
+
+      for (const pref of byGroup.get(groupKey)) {
+        if (!pref?.key) continue;
+        seenRows.add(pref.key);
+        const row = this.#getOrCreateRow(pref);
+        this.#decorateRow(row, pref, channels, seenCells);
+        this.#bodyHost.appendChild(row);
+      }
+    }
+
+    // Remove dropped rows / cells / group headings.
+    for (const [key, row] of this.#rowsByKey) {
+      if (!seenRows.has(key)) {
+        try { row.remove(); } catch { /* ignore */ }
+        this.#rowsByKey.delete(key);
+      }
+    }
+    for (const [key, cell] of this.#cellsByKey) {
+      if (!seenCells.has(key)) {
+        try { cell.remove(); } catch { /* ignore */ }
+        this.#cellsByKey.delete(key);
+      }
+    }
+    for (const [key, heading] of this.#groupHeadingsByKey) {
+      if (!seenGroups.has(key)) {
+        try { heading.remove(); } catch { /* ignore */ }
+        this.#groupHeadingsByKey.delete(key);
+      }
+    }
+  }
+
+  // ── Internal — per-row helpers ────────────────────────────────────
+
+  #getOrCreateRow(pref) {
+    let row = this.#rowsByKey.get(pref.key);
+    if (!row) {
+      row = document.createElement('div');
+      row.setAttribute('role', 'row');
+      row.setAttribute('data-row-key', pref.key);
+      this.#bodyHost.appendChild(row);
+      this.#rowsByKey.set(pref.key, row);
+    }
+    return row;
+  }
+
+  #decorateRow(row, pref, channels, seenCells) {
+    // Row header (notification-type label cell).
+    let rowHeader = row.querySelector(':scope > [role="rowheader"]');
+    if (!rowHeader) {
+      rowHeader = document.createElement('div');
+      rowHeader.setAttribute('role', 'rowheader');
+      row.appendChild(rowHeader);
+    }
+    rowHeader.replaceChildren();
+
+    const labelText = document.createElement('span');
+    labelText.setAttribute('data-row-label-text', '');
+    labelText.textContent = String(pref.label || pref.key);
+    rowHeader.appendChild(labelText);
+
+    if (pref.description) {
+      const desc = document.createElement('span');
+      desc.setAttribute('data-row-description', '');
+      desc.textContent = String(pref.description);
+      rowHeader.appendChild(desc);
+    }
+
+    // Cells — one <check-ui> per channel.
+    const cellMap = (pref.channels && typeof pref.channels === 'object') ? pref.channels : {};
+
+    for (const channel of channels) {
+      if (!channel?.key) continue;
+      const cellKey = `${pref.key}::${channel.key}`;
+      seenCells.add(cellKey);
+
+      let cell = row.querySelector(`:scope > [data-cell-key="${CSS.escape(cellKey)}"]`);
+      if (!cell) {
+        cell = document.createElement('div');
+        cell.setAttribute('role', 'cell');
+        cell.setAttribute('data-cell-key', cellKey);
+        row.appendChild(cell);
+      }
+
+      let check = this.#cellsByKey.get(cellKey);
+      if (!check) {
+        check = document.createElement('check-ui');
+        check.setAttribute('data-row-key', pref.key);
+        check.setAttribute('data-channel-key', channel.key);
+        cell.appendChild(check);
+        this.#cellsByKey.set(cellKey, check);
+      }
+
+      const checked = !!cellMap[channel.key];
+      if (check.checked !== checked) {
+        this.#internalUpdate = true;
+        try { check.checked = checked; }
+        finally { this.#internalUpdate = false; }
+      }
+
+      check.setAttribute(
+        'aria-label',
+        `${pref.label || pref.key} via ${channel.label || channel.key}`,
+      );
+
+      const cellDisabled = !!this.disabled || !!this.loading || !!pref.disabled;
+      if (cellDisabled) check.setAttribute('disabled', '');
+      else check.removeAttribute('disabled');
+    }
+
+    // Re-order cells to match channels array (right of rowheader).
+    for (const channel of channels) {
+      const cellKey = `${pref.key}::${channel.key}`;
+      const cell = row.querySelector(`:scope > [data-cell-key="${CSS.escape(cellKey)}"]`);
+      if (cell) row.appendChild(cell);
+    }
+  }
+
+  // ── Internal — event delegation ───────────────────────────────────
+
+  #wireListeners() {
+    const onChange = (e) => {
+      if (this.#internalUpdate) return;
+      const target = e?.target;
+      if (!target) return;
+
+      // ── Column master <switch-ui> bulk toggle ──
+      const master = target.closest?.('switch-ui[data-channel-master]');
+      if (master && this.#matrixHost.contains(master)) {
+        const channelKey = master.getAttribute('data-channel-master') || '';
+        if (!channelKey) return;
+        if (this.disabled || this.loading) return;
+        e.stopPropagation();
+        const enabled = !!master.checked;
+        this.dispatchEvent(new CustomEvent('bulk-toggle', {
+          bubbles: true,
+          detail: { channel: channelKey, enabled },
+        }));
+        return;
+      }
+
+      // ── Per-cell <check-ui> toggle ──
+      const check = target.closest?.('check-ui[data-row-key][data-channel-key]');
+      if (check && this.#bodyHost.contains(check)) {
+        const rowKey = check.getAttribute('data-row-key') || '';
+        const channelKey = check.getAttribute('data-channel-key') || '';
+        if (!rowKey || !channelKey) return;
+        if (this.disabled || this.loading) return;
+        e.stopPropagation();
+        const enabled = !!check.checked;
+        this.dispatchEvent(new CustomEvent('change', {
+          bubbles: true,
+          detail: { row: rowKey, channel: channelKey, enabled },
+        }));
+        return;
+      }
+    };
+
+    this.#matrixHost.addEventListener('change', onChange);
+    this.#cleanups.push(() => this.#matrixHost.removeEventListener('change', onChange));
+  }
+}
+
+if (!customElements.get('notification-preferences-ui')) {
+  customElements.define('notification-preferences-ui', UINotificationPreferences);
+}
+
+export { UINotificationPreferences };