npm - @adia-ai/web-modules - Versions diffs - 0.8.36 → 0.8.37 - Mend

@adia-ai/web-modules 0.8.36 → 0.8.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (89) hide show

package/CHANGELOG.md +17 -0
package/README.md +3 -3
package/agent-admin/admin-roster/admin-roster.js +1 -1
package/agent-admin/admin-settings/admin-settings.js +1 -1
package/agent-admin/agent-admin/agent-admin.js +1 -1
package/billing/billing-overview/billing-overview.a2ui.json +281 -0
package/billing/billing-overview/billing-overview.class.js +838 -0
package/billing/billing-overview/billing-overview.css +223 -0
package/billing/billing-overview/billing-overview.js +16 -0
package/billing/billing-overview/billing-overview.yaml +441 -0
package/billing/index.js +21 -0
package/billing/invoice-detail/invoice-detail.a2ui.json +276 -0
package/billing/invoice-detail/invoice-detail.class.js +711 -0
package/billing/invoice-detail/invoice-detail.css +305 -0
package/billing/invoice-detail/invoice-detail.js +16 -0
package/billing/invoice-detail/invoice-detail.yaml +411 -0
package/billing/invoice-history/invoice-history.a2ui.json +315 -0
package/billing/invoice-history/invoice-history.class.js +672 -0
package/billing/invoice-history/invoice-history.css +130 -0
package/billing/invoice-history/invoice-history.js +16 -0
package/billing/invoice-history/invoice-history.yaml +398 -0
package/billing/payment-method-form/payment-method-form.a2ui.json +310 -0
package/billing/payment-method-form/payment-method-form.class.js +886 -0
package/billing/payment-method-form/payment-method-form.css +149 -0
package/billing/payment-method-form/payment-method-form.js +16 -0
package/billing/payment-method-form/payment-method-form.yaml +430 -0
package/billing/payment-method-list/payment-method-list.a2ui.json +283 -0
package/billing/payment-method-list/payment-method-list.class.js +705 -0
package/billing/payment-method-list/payment-method-list.css +128 -0
package/billing/payment-method-list/payment-method-list.js +16 -0
package/billing/payment-method-list/payment-method-list.yaml +355 -0
package/billing/plan-picker/plan-picker.a2ui.json +349 -0
package/billing/plan-picker/plan-picker.class.js +635 -0
package/billing/plan-picker/plan-picker.css +227 -0
package/billing/plan-picker/plan-picker.js +16 -0
package/billing/plan-picker/plan-picker.yaml +453 -0
package/chat/README.md +1 -1
package/chat/chat-composer/chat-composer.js +2 -2
package/chat/chat-empty/chat-empty.js +2 -2
package/chat/chat-shell/chat-shell.js +4 -4
package/chat/chat-sidebar/chat-sidebar.js +2 -2
package/chat/chat-surfaces/chat-surfaces.js +2 -2
package/chat/chat-thread/chat-thread.js +2 -2
package/dashboard/dashboard-layout/dashboard-layout.a2ui.json +254 -0
package/dashboard/dashboard-layout/dashboard-layout.css +190 -0
package/dashboard/dashboard-layout/dashboard-layout.js +289 -0
package/dashboard/dashboard-layout/dashboard-layout.yaml +374 -0
package/dashboard/date-range-selector/date-range-selector.a2ui.json +236 -0
package/dashboard/date-range-selector/date-range-selector.css +84 -0
package/dashboard/date-range-selector/date-range-selector.js +686 -0
package/dashboard/date-range-selector/date-range-selector.yaml +358 -0
package/dashboard/index.js +14 -0
package/dist/everything.min.js +1 -1
package/editor/editor-canvas/editor-canvas.js +2 -2
package/editor/editor-shell/editor-shell.js +2 -2
package/editor/editor-sidebar/editor-sidebar.js +2 -2
package/editor/editor-toolbar/editor-toolbar.js +2 -2
package/feedback/confirm-dialog/confirm-dialog.a2ui.json +206 -0
package/feedback/confirm-dialog/confirm-dialog.css +157 -0
package/feedback/confirm-dialog/confirm-dialog.js +383 -0
package/feedback/confirm-dialog/confirm-dialog.yaml +297 -0
package/feedback/index.js +10 -0
package/form/form-popover/form-popover.js +1 -1
package/generative/index.d.ts +1 -1
package/generative/index.js +2 -2
package/onboarding/index.js +1 -0
package/onboarding/onboarding-checklist/onboarding-checklist.a2ui.json +263 -0
package/onboarding/onboarding-checklist/onboarding-checklist.css +157 -0
package/onboarding/onboarding-checklist/onboarding-checklist.js +428 -0
package/onboarding/onboarding-checklist/onboarding-checklist.yaml +236 -0
package/package.json +99 -6
package/runtime/a2ui-root/a2ui-root.js +3 -3
package/runtime/gen-root/gen-root.js +5 -5
package/settings/index.js +12 -0
package/settings/integrations-page/integrations-page.a2ui.json +274 -0
package/settings/integrations-page/integrations-page.css +177 -0
package/settings/integrations-page/integrations-page.d.ts +77 -0
package/settings/integrations-page/integrations-page.js +413 -0
package/settings/integrations-page/integrations-page.yaml +317 -0
package/settings/notification-preferences/notification-preferences.a2ui.json +245 -0
package/settings/notification-preferences/notification-preferences.css +204 -0
package/settings/notification-preferences/notification-preferences.js +622 -0
package/settings/notification-preferences/notification-preferences.yaml +358 -0
package/shell/admin-command/admin-command.js +2 -2
package/shell/admin-shell/admin-shell.js +2 -2
package/shell/admin-sidebar/admin-sidebar.js +2 -2
package/shell/embed-shell/embed-shell.js +3 -3
package/simple/simple-shell/simple-shell.js +1 -1
package/theme/theme-panel/theme-panel.js +2 -2

package/dashboard/date-range-selector/date-range-selector.js ADDED Viewed

@@ -0,0 +1,686 @@
+/**
+ * <date-range-selector-ui> — Page-level time-window chooser for dashboards.
+ *
+ * A module-tier composite that pairs a preset chip-row (Today / 7d / 30d /
+ * 90d / QTD / YTD / Custom) with an embedded <date-range-picker-ui>
+ * (SPEC-037) and broadcasts the resolved range to range-aware panels on
+ * the page via a documented CustomEvent + reflected attributes.
+ *
+ * SPEC: .claude/docs/specs/implementation-ready/SPEC-019-date-range-selector-global.md
+ * Composed primitives (consumer must side-effect import — ADR-0027):
+ *   - <segmented-ui> + <segment-ui> (preset chip row)
+ *   - <date-range-picker-ui> (custom-range editor, Wave-1 primitive)
+ *   - <text-ui> (resolved-range readout)
+ *
+ * Why a composite (not a primitive subclassing segmented-ui):
+ *   The composite owns three layered surfaces — preset chip row, picker,
+ *   readout — plus the broadcast bus. None of these belong inside
+ *   segmented-ui (which is a generic single-select group). The composite
+ *   stamps each piece in its own light-DOM region and reflects per-region
+ *   attributes for CSS layout. Per ADR-0033 (Light-DOM substrate) we
+ *   rely on tag-and-ancestor selectors; no shadow DOM.
+ *
+ * Broadcast contract (§8):
+ *   - `range-change` fires ONCE per resolved range on the broadcast target
+ *     ({document.documentElement, host element, or none} per [broadcast]).
+ *   - `from <= to` always; the composite swaps reversed ranges before commit.
+ *   - ISO-8601 strings (YYYY-MM-DD) on the wire; no Date instances.
+ *   - When [broadcast=document], writes data-range-from / data-range-to
+ *     to <html>; one-broadcaster-per-page invariant enforced via a
+ *     module-level Set + console.warn on conflict.
+ *
+ * Form participation:
+ *   When [name] is set, ElementInternals serializes the range as a
+ *   colon-pair "{from}:{to}" (e.g. "2026-05-01:2026-05-07") under [name].
+ *   Without [name], the composite emits events only.
+ */
+import { UIFormElement } from '@adia-ai/web-components/core/form';
+import { untracked } from '@adia-ai/web-components/core/signals';
+// ── Module-level invariant tracking ──
+//
+// SPEC §3.3 / §6 anti-pattern: only one document-broadcaster per page is
+// permitted. Two instances racing for data-range-* on <html> produce
+// flicker. We track the set of currently-mounted document-broadcasters
+// and emit a one-shot console.warn when a second one connects.
+/** Set of currently-mounted instances with broadcast="document". */
+const documentBroadcasters = new Set();
+/** One-shot warn flag — keyed per page lifetime, not per instance. */
+let multiBroadcasterWarned = false;
+// ── Preset resolver ──
+//
+// Each preset key resolves to a {from, to} ISO pair against "today" (the
+// resolver is called lazily on each range commit so the user's clock
+// advancing across midnight is reflected). Keys not in this table are
+// silently ignored (the chip row renders only recognized keys).
+function pad(n) { return String(n).padStart(2, '0'); }
+function toISO(d) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+function parseISO(str) {
+  if (!str) return null;
+  const m = String(str).match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (!m) return null;
+  const d = new Date(+m[1], +m[2] - 1, +m[3]);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+/** Default labels for the preset chips. Consumers override via [presets]. */
+const PRESET_LABELS = {
+  today: 'Today',
+  '7d':  'Last 7 days',
+  '30d': 'Last 30 days',
+  '90d': 'Last 90 days',
+  qtd:   'Quarter to date',
+  ytd:   'Year to date',
+  custom: 'Custom',
+};
+const KNOWN_PRESETS = new Set(Object.keys(PRESET_LABELS));
+/**
+ * Resolve a preset key to a {from, to} ISO pair against `now`. For
+ * `custom`, the caller supplies the from/to (or we fall back to the
+ * prior range — see #resolveRange). Returns null for unknown keys.
+ */
+function resolvePreset(key, now = new Date()) {
+  const t0 = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const iso = toISO(t0);
+  const sub = (days) => {
+    const d = new Date(t0);
+    d.setDate(d.getDate() - days);
+    return toISO(d);
+  };
+  switch (key) {
+    case 'today':
+      return { from: iso, to: iso };
+    case '7d':
+      return { from: sub(6), to: iso };
+    case '30d':
+      return { from: sub(29), to: iso };
+    case '90d':
+      return { from: sub(89), to: iso };
+    case 'qtd': {
+      // Calendar quarter only (Jan/Apr/Jul/Oct) — SPEC OD-002 lean A.
+      const qStartMonth = Math.floor(t0.getMonth() / 3) * 3;
+      return { from: toISO(new Date(t0.getFullYear(), qStartMonth, 1)), to: iso };
+    }
+    case 'ytd':
+      return { from: toISO(new Date(t0.getFullYear(), 0, 1)), to: iso };
+    case 'custom':
+      // Custom is consumer-supplied; caller resolves.
+      return null;
+    default:
+      return null;
+  }
+}
+/** Format an ISO range to a human-readable readout ("1 May – 7 May 2026"). */
+function formatReadout(from, to) {
+  const f = parseISO(from);
+  const t = parseISO(to);
+  if (!f || !t) return '';
+  const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  const sameYear = f.getFullYear() === t.getFullYear();
+  const sameMonthYear = sameYear && f.getMonth() === t.getMonth();
+  if (sameYear && f.getMonth() === t.getMonth() && f.getDate() === t.getDate()) {
+    return `${months[f.getMonth()]} ${f.getDate()}, ${f.getFullYear()}`;
+  }
+  if (sameMonthYear) {
+    return `${months[f.getMonth()]} ${f.getDate()} – ${t.getDate()}, ${t.getFullYear()}`;
+  }
+  if (sameYear) {
+    return `${months[f.getMonth()]} ${f.getDate()} – ${months[t.getMonth()]} ${t.getDate()}, ${t.getFullYear()}`;
+  }
+  return `${months[f.getMonth()]} ${f.getDate()}, ${f.getFullYear()} – ${months[t.getMonth()]} ${t.getDate()}, ${t.getFullYear()}`;
+}
+// ═══════════════════════════════════════════════════════════════
+// UIDateRangeSelector
+// ═══════════════════════════════════════════════════════════════
+export class UIDateRangeSelector extends UIFormElement {
+  // Per AGENTS.md §170 / form.js — `label` is NOT first-class here.
+  // The host carries aria-label directly (see properties).
+  static labelDeprecated = true;
+  static get properties() {
+    return {
+      ...UIFormElement.properties,
+      // `value` is the preset key (today / 7d / ... / custom). Reflected.
+      value:     { type: String,  default: '7d',         reflect: true },
+      from:      { type: String,  default: '',           reflect: true },
+      to:        { type: String,  default: '',           reflect: true },
+      presets:   { type: String,  default: 'today,7d,30d,90d,qtd,ytd,custom' },
+      broadcast: { type: String,  default: 'document',   reflect: true },
+      // Host aria-label, surfaced as a property for prop-set updates.
+      ariaLabelAttr: { type: String, default: 'Time period', attribute: 'aria-label', reflect: true },
+      pickerOpen:    { type: Boolean, default: false, attribute: 'picker-open', reflect: true },
+    };
+  }
+  // No template — the composite imperatively stamps a fixed three-region
+  // skeleton (chips · picker · readout) once on first connect, then
+  // mutates per-region attributes across renders. Returning html`` would
+  // trigger stamp() → replaceChildren() and wipe the authored slots /
+  // composed children. Same pattern as confirm-dialog-ui / modal-ui.
+  static template = () => null;
+  // ── Field refs ───────────────────────────────────────────────────
+  #stamped = false;
+  #cleanups = [];
+  #segmented = null;
+  #picker = null;
+  #readout = null;
+  #regions = { prefix: null, chips: null, picker: null, readout: null, suffix: null };
+  // Tracks whether THIS instance currently owns the document broadcast.
+  // Set true on first connect when broadcast=document; cleared on disconnect.
+  #isDocumentOwner = false;
+  // Suppress nested attribute-change loops while the composite is
+  // resolving a range internally (preset click → #commit() → reflect
+  // value attribute → attributeChangedCallback → recompute).
+  #internalUpdate = false;
+  // Pre-render guard for SPEC anti-pattern: log a one-shot warn on
+  // unknown preset keys (so consumer-debugging is loud, not silent).
+  static #warnedUnknownPreset = new WeakSet();
+  // ── Public imperative API (SPEC §4 Methods) ──────────────────────
+  /**
+   * Programmatic equivalent of clicking a preset. For `custom`, pass
+   * from + to ISO strings; for named presets, from/to are derived.
+   * Fires `range-change` exactly once when the resolved range changes.
+   *
+   * @param {string} preset — one of the value enum keys
+   * @param {string} [fromISO] — required when preset === 'custom'
+   * @param {string} [toISO]   — required when preset === 'custom'
+   */
+  setRange(preset, fromISO, toISO) {
+    if (preset === 'custom') {
+      if (!fromISO || !toISO) {
+        // SPEC §9 anti-pattern: custom requires from/to.
+        // eslint-disable-next-line no-console
+        console.warn('[date-range-selector-ui] setRange("custom", …) requires from + to ISO dates.');
+        return;
+      }
+      const ordered = this.#orderRange(fromISO, toISO);
+      this.#commit('custom', ordered.from, ordered.to);
+      return;
+    }
+    if (!KNOWN_PRESETS.has(preset)) {
+      // eslint-disable-next-line no-console
+      console.warn(`[date-range-selector-ui] unknown preset "${preset}" — ignored. Use one of: ${[...KNOWN_PRESETS].join(', ')}.`);
+      return;
+    }
+    const resolved = resolvePreset(preset);
+    if (!resolved) return;
+    this.#commit(preset, resolved.from, resolved.to);
+  }
+  /** Returns the currently resolved range + preset. */
+  getRange() {
+    return {
+      value: this.value,
+      preset: this.value,
+      from: this.from,
+      to: this.to,
+    };
+  }
+  /**
+   * Helper for JS consumers — binds a handler to `range-change` on the
+   * current broadcast target and returns an unsubscribe function. The
+   * target is resolved at subscribe time; if [broadcast] changes later,
+   * the consumer must re-subscribe.
+   */
+  subscribe(handler) {
+    const target = this.#broadcastTarget();
+    if (!target) {
+      // broadcast="none" — emit nothing; subscriber unsubscribe is a no-op.
+      return () => {};
+    }
+    target.addEventListener('range-change', handler);
+    return () => target.removeEventListener('range-change', handler);
+  }
+  // ── Lifecycle ────────────────────────────────────────────────────
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'group');
+    if (!this.hasAttribute('aria-label')) {
+      this.setAttribute('aria-label', this.ariaLabelAttr || 'Time period');
+    }
+    if (!this.#stamped) {
+      this.#stamp();
+      this.#wireListeners();
+      this.#stamped = true;
+    }
+    // Register as the document-broadcaster (one-per-page invariant)
+    // BEFORE the initial commit so #writeBroadcastAttributes sees the
+    // ownership flag set and writes data-range-* to <html>.
+    if (this.broadcast === 'document') {
+      this.#claimDocumentBroadcaster();
+    }
+    // Resolve initial range from [value]. If from/to are already set
+    // (declarative attributes), respect them for `custom`; otherwise
+    // derive from the preset key.
+    untracked(() => {
+      const initialResolved = this.#resolveInitial();
+      if (initialResolved) {
+        this.#commit(this.value, initialResolved.from, initialResolved.to, { initial: true });
+      }
+    });
+  }
+  disconnected() {
+    super.disconnected();
+    for (const fn of this.#cleanups) {
+      try { fn(); } catch { /* tolerate stale ref */ }
+    }
+    this.#cleanups.length = 0;
+    this.#releaseDocumentBroadcaster();
+  }
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback?.(name, oldVal, newVal);
+    if (!this.#stamped || this.#internalUpdate) return;
+    if (name === 'presets') {
+      this.#renderChips();
+      return;
+    }
+    if (name === 'broadcast') {
+      // Re-route future broadcasts. Clear stale doc attrs if we were the
+      // doc-owner and the new mode isn't document.
+      if (oldVal === 'document' && newVal !== 'document') {
+        this.#releaseDocumentBroadcaster();
+      }
+      if (newVal === 'document') {
+        this.#claimDocumentBroadcaster();
+        // Write current range to the new target.
+        this.#writeBroadcastAttributes();
+      } else if (newVal === 'self') {
+        this.#writeBroadcastAttributes();
+      }
+      return;
+    }
+    if (name === 'value' && oldVal !== newVal && newVal && KNOWN_PRESETS.has(newVal)) {
+      // Programmatic [value] flip → re-resolve range (unless `custom`,
+      // which depends on author-supplied from/to).
+      if (newVal !== 'custom') {
+        const resolved = resolvePreset(newVal);
+        if (resolved) this.#commit(newVal, resolved.from, resolved.to);
+      }
+      return;
+    }
+  }
+  // ── Form participation ───────────────────────────────────────────
+  /**
+   * Override syncValue so the form value is the colon-pair "{from}:{to}".
+   * For pickers/selectors that don't have a meaningful single-string
+   * value, this is the de-facto convention.
+   */
+  syncValue(_val) {
+    const formVal = this.from && this.to ? `${this.from}:${this.to}` : '';
+    this.internals.setFormValue(formVal);
+  }
+  // ── Render — narrow; only mirrors current state to per-region nodes ──
+  render() {
+    if (!this.#stamped) return;
+    // Sync segmented selection to current preset key.
+    if (this.#segmented && this.#segmented.value !== this.value) {
+      this.#segmented.value = this.value;
+    }
+    // Sync picker open state into reflected [picker-open] attr (set by
+    // the picker's `open`/`close` events — see #wireListeners).
+    if (this.#picker) {
+      // Cascade min/max if author put them on the host (rare but
+      // documented in SPEC-037).
+      if (this.hasAttribute('min')) this.#picker.setAttribute('min', this.getAttribute('min'));
+      if (this.hasAttribute('max')) this.#picker.setAttribute('max', this.getAttribute('max'));
+      // Mirror the resolved range into the picker's value so segmented
+      // preset clicks (e.g. "30d") propagate into the picker — without
+      // this, clicking a chip resolved the range on the host (this.from
+      // / this.to / value) but the picker stayed at its prior state,
+      // so opening the picker afterward showed empty or stale dates.
+      // value is a JSON-string at the attribute boundary per the
+      // picker's UIFormElement.properties contract (see
+      // date-range-picker class.js); empty string clears the picker.
+      const targetValue = (this.from && this.to)
+        ? JSON.stringify({ from: this.from, to: this.to })
+        : '';
+      if (this.#picker.value !== targetValue) {
+        this.#picker.value = targetValue;
+      }
+    }
+    // Readout text mirrors from/to.
+    if (this.#readout) {
+      const txt = formatReadout(this.from, this.to);
+      this.#readout.textContent = txt;
+      // Hide when empty so the readout doesn't reserve space.
+      this.#readout.hidden = !txt;
+    }
+  }
+  // ── Internal — DOM stamping ──────────────────────────────────────
+  #stamp() {
+    // Chip row — a single <segmented-ui> with one <segment-ui> per preset.
+    const chips = document.createElement('segmented-ui');
+    chips.setAttribute('data-region', 'chips');
+    chips.setAttribute('role', 'radiogroup');
+    chips.setAttribute('aria-label', 'Preset ranges');
+    this.appendChild(chips);
+    this.#segmented = chips;
+    this.#regions.chips = chips;
+    // Picker — embedded <date-range-picker-ui> for the `custom` preset.
+    // Hidden via CSS when value != "custom" (see date-range-selector.css).
+    const picker = document.createElement('date-range-picker-ui');
+    picker.setAttribute('data-region', 'picker');
+    picker.setAttribute('format', 'short');
+    picker.setAttribute('placeholder', 'Custom range');
+    this.appendChild(picker);
+    this.#picker = picker;
+    this.#regions.picker = picker;
+    // Readout — a <text-ui> showing the resolved range when value="custom".
+    // For non-custom presets the chip label communicates the range; the
+    // readout stays hidden to reduce visual noise. Authors can override
+    // via the [data-show-readout] attribute on the host (not yet wired).
+    const readout = document.createElement('text-ui');
+    readout.setAttribute('data-region', 'readout');
+    readout.setAttribute('part', 'readout');
+    readout.setAttribute('role', 'status');
+    readout.setAttribute('aria-live', 'polite');
+    readout.hidden = true;
+    this.appendChild(readout);
+    this.#readout = readout;
+    this.#regions.readout = readout;
+    // Render the initial chip list.
+    this.#renderChips();
+  }
+  #renderChips() {
+    if (!this.#segmented) return;
+    const presetList = (this.presets || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    // Wipe + restamp existing chips. Preset cardinality is small (≤7).
+    // Preserve the segmented's auto-stamped indicator span (the
+    // [data-indicator] node prepended by segmented-ui on first render);
+    // re-creating it would jump the indicator transition.
+    const indicator = this.#segmented.querySelector(':scope > [data-indicator]');
+    this.#segmented.replaceChildren();
+    if (indicator) this.#segmented.appendChild(indicator);
+    for (const key of presetList) {
+      if (!KNOWN_PRESETS.has(key)) {
+        if (!UIDateRangeSelector.#warnedUnknownPreset.has(this)) {
+          UIDateRangeSelector.#warnedUnknownPreset.add(this);
+          // eslint-disable-next-line no-console
+          console.warn(`[date-range-selector-ui] unknown preset key "${key}" in [presets] — ignored. Use one of: ${[...KNOWN_PRESETS].join(', ')}.`);
+        }
+        continue;
+      }
+      const seg = document.createElement('segment-ui');
+      seg.setAttribute('value', key);
+      seg.setAttribute('text', PRESET_LABELS[key]);
+      this.#segmented.appendChild(seg);
+    }
+    // Re-sync segmented's [value] so the indicator lands on the right chip.
+    this.#segmented.value = this.value;
+  }
+  #wireListeners() {
+    // ── Chip row → preset click ──
+    const onSegmentedChange = (e) => {
+      const presetKey = e.detail?.value;
+      if (!presetKey || !KNOWN_PRESETS.has(presetKey)) return;
+      e.stopPropagation();
+      if (presetKey === 'custom') {
+        // Open the picker; commit on its `change` event below.
+        this.#openPicker();
+        // Also flip value so [value="custom"] selectors gate the picker
+        // visibility per the CSS rule. Range stays at the previous
+        // resolved value until the picker commits.
+        this.#setValueOnly('custom');
+        return;
+      }
+      const resolved = resolvePreset(presetKey);
+      if (!resolved) return;
+      this.#commit(presetKey, resolved.from, resolved.to);
+    };
+    this.#segmented.addEventListener('change', onSegmentedChange);
+    this.#cleanups.push(() => this.#segmented.removeEventListener('change', onSegmentedChange));
+    // ── Picker → custom range commit ──
+    const onPickerChange = (e) => {
+      e.stopPropagation();
+      const detail = e.detail || {};
+      const val = detail.value || null;
+      if (!val || !val.from || !val.to) return;
+      const ordered = this.#orderRange(val.from, val.to);
+      this.#commit('custom', ordered.from, ordered.to);
+    };
+    this.#picker.addEventListener('change', onPickerChange);
+    this.#cleanups.push(() => this.#picker.removeEventListener('change', onPickerChange));
+    // Reflect picker open/close into [picker-open] on the host.
+    const onPickerOpen = () => {
+      this.pickerOpen = true;
+    };
+    const onPickerClose = () => {
+      this.pickerOpen = false;
+    };
+    this.#picker.addEventListener('open', onPickerOpen);
+    this.#picker.addEventListener('close', onPickerClose);
+    this.#cleanups.push(() => this.#picker.removeEventListener('open', onPickerOpen));
+    this.#cleanups.push(() => this.#picker.removeEventListener('close', onPickerClose));
+  }
+  // ── Range commit pipeline ────────────────────────────────────────
+  /**
+   * Single commit point. Updates from/to/value, syncs form value,
+   * dispatches `range-change` on the broadcast target + `change` on the
+   * host, and writes data-range-* attributes per [broadcast].
+   *
+   * @param {string} presetKey
+   * @param {string} fromISO
+   * @param {string} toISO
+   * @param {{initial?: boolean}} [opts] — when initial, the from/to may
+   *   already match the props; we still emit so subscribers wired at
+   *   connect-time see the first range.
+   */
+  #commit(presetKey, fromISO, toISO, opts = {}) {
+    const sameRange = this.from === fromISO && this.to === toISO && this.value === presetKey;
+    if (sameRange && !opts.initial) return;
+    this.#internalUpdate = true;
+    try {
+      this.from = fromISO;
+      this.to = toISO;
+      this.value = presetKey;
+    } finally {
+      this.#internalUpdate = false;
+    }
+    this.syncValue();
+    this.#writeBroadcastAttributes();
+    const detail = {
+      value: presetKey,
+      from: fromISO,
+      to: toISO,
+      preset: presetKey,
+    };
+    // Host-level `change` event (UIFormElement convention + alias).
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: presetKey, from: fromISO, to: toISO },
+    }));
+    // Broadcast `range-change` on the configured target.
+    const target = this.#broadcastTarget();
+    if (target) {
+      target.dispatchEvent(new CustomEvent('range-change', {
+        bubbles: target === this, // bubble on self; not meaningful on document
+        detail,
+      }));
+    }
+  }
+  /**
+   * Set [value] without re-resolving the range. Used when the user clicks
+   * the Custom chip — we flip the chip selection synchronously so the
+   * picker visibility CSS rule kicks in, but the range stays at the
+   * prior commit until the picker emits `change`.
+   */
+  #setValueOnly(presetKey) {
+    if (this.value === presetKey) return;
+    this.#internalUpdate = true;
+    try {
+      this.value = presetKey;
+    } finally {
+      this.#internalUpdate = false;
+    }
+  }
+  #orderRange(fromISO, toISO) {
+    return fromISO <= toISO
+      ? { from: fromISO, to: toISO }
+      : { from: toISO,   to: fromISO };
+  }
+  /** Resolve the from/to to use on first connect from current props. */
+  #resolveInitial() {
+    if (this.value === 'custom') {
+      if (this.from && this.to) {
+        const ordered = this.#orderRange(this.from, this.to);
+        return ordered;
+      }
+      // SPEC §9 anti-pattern: custom with no from/to. Fall back to 7d
+      // so first paint has a meaningful range; chip selection stays on
+      // `custom` to surface the picker.
+      return resolvePreset('7d');
+    }
+    const known = KNOWN_PRESETS.has(this.value) ? this.value : '7d';
+    return resolvePreset(known);
+  }
+  // ── Broadcast plumbing ───────────────────────────────────────────
+  /**
+   * The DOM target we dispatch range-change on (or null for broadcast=none).
+   * For `document`, we dispatch on `document` directly so consumers can
+   * listen with `document.addEventListener('range-change', …)` per
+   * SPEC §8. The data-range-* attributes still land on `<html>` (i.e.
+   * `document.documentElement`) so CSS-only subscribers match
+   * `html[data-range-from]` selectors.
+   */
+  #broadcastTarget() {
+    if (this.broadcast === 'document') return document;
+    if (this.broadcast === 'self') return this;
+    return null;
+  }
+  /** Target the data-range-* attributes are written to. */
+  #attributeTarget() {
+    if (this.broadcast === 'document') return document.documentElement;
+    if (this.broadcast === 'self') return this;
+    return null;
+  }
+  #writeBroadcastAttributes() {
+    const target = this.#attributeTarget();
+    if (!target) return;
+    // Only the document-owner writes to <html>. If a second instance
+    // claims doc broadcaster (multi-broadcaster scenario), only the
+    // claimant writes; others abstain.
+    if (this.broadcast === 'document' && !this.#isDocumentOwner) return;
+    if (this.from) target.setAttribute('data-range-from', this.from);
+    else target.removeAttribute('data-range-from');
+    if (this.to) target.setAttribute('data-range-to', this.to);
+    else target.removeAttribute('data-range-to');
+  }
+  #claimDocumentBroadcaster() {
+    if (documentBroadcasters.size > 0 && !documentBroadcasters.has(this)) {
+      // Second broadcaster on the page. Per SPEC anti-pattern 2, warn
+      // once + let the original keep ownership. The new instance still
+      // emits range-change events on document (subscribers can listen),
+      // but does not write the data-range-* attributes (so CSS-only
+      // subscribers don't flicker).
+      if (!multiBroadcasterWarned) {
+        multiBroadcasterWarned = true;
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[date-range-selector-ui] multiple instances with broadcast="document" on the same page; ' +
+          'only the first writes data-range-from / data-range-to to <html>. Use broadcast="self" for ' +
+          'secondary instances. See SPEC-019 §6 nesting rules.',
+        );
+      }
+      this.#isDocumentOwner = false;
+      documentBroadcasters.add(this);
+      return;
+    }
+    documentBroadcasters.add(this);
+    this.#isDocumentOwner = true;
+  }
+  #releaseDocumentBroadcaster() {
+    if (!documentBroadcasters.has(this)) return;
+    documentBroadcasters.delete(this);
+    if (this.#isDocumentOwner) {
+      // Clear the document attributes — we owned them.
+      document.documentElement.removeAttribute('data-range-from');
+      document.documentElement.removeAttribute('data-range-to');
+      this.#isDocumentOwner = false;
+      // Promote the next broadcaster (if any) to owner so subsequent
+      // commits write the attributes again.
+      const next = documentBroadcasters.values().next().value;
+      if (next) {
+        next.#isDocumentOwner = true;
+        next.#writeBroadcastAttributes();
+      }
+    }
+  }
+  // ── Imperative picker open helper ────────────────────────────────
+  #openPicker() {
+    if (!this.#picker) return;
+    if (typeof this.#picker.openPopover === 'function') {
+      this.#picker.openPopover();
+    } else {
+      this.#picker.open = true;
+    }
+  }
+}
+if (!customElements.get('date-range-selector-ui')) {
+  customElements.define('date-range-selector-ui', UIDateRangeSelector);
+}