@adia-ai/web-modules 0.8.35 → 0.8.37

package/onboarding/onboarding-checklist/onboarding-checklist.js

@@ -0,0 +1,428 @@
+/**
+ * <onboarding-checklist-ui
+ *   storage-key="acme:onboarding:v1"
+ *   items='[{"id":"profile","label":"Complete your profile","href":"/settings/profile"}, …]'>
+ *   <button-ui slot="footer" variant="ghost" text="Hide for now"></button-ui>
+ * </onboarding-checklist-ui>
+ *
+ * Module-tier onboarding checklist — composes <progress-ui> + <list-ui> +
+ * <list-item-ui> + <check-ui> + <button-ui>. Data-driven (items prop),
+ * persistent (storage-key), auto-dismissing on completion.
+ *
+ * Per ADR-0027 — composites that programmatically create primitives do
+ * NOT auto-import those primitives. The consumer (app shell or page)
+ * must explicitly import <progress-ui>, <list-ui>, <check-ui>,
+ * <button-ui> in addition to this module.
+ */
+
+import { UIElement, html } from '@adia-ai/web-components/core/element';
+
+class UIOnboardingChecklist extends UIElement {
+  static properties = {
+    items:                { type: Array,   default: [] },
+    'storage-key':        { type: String,  default: '', reflect: true },
+    storage:              { type: String,  default: 'local', reflect: true },
+    'dismiss-on-complete':{ type: Boolean, default: false, reflect: true },
+    collapsible:          { type: Boolean, default: true,  reflect: true },
+    collapsed:            { type: Boolean, default: false, reflect: true },
+    value:                { type: Object,  default: {} },
+    title:                { type: String,  default: 'Get started', reflect: true },
+  };
+
+  // Data-driven internal DOM; we render via tagged template literal so
+  // the child count can change as `items` changes.
+  static template = (host) => host._renderTemplate();
+
+  // ── lifecycle ────────────────────────────────────────────────
+
+  #headerId = `obc-h-${Math.random().toString(36).slice(2, 8)}`;
+  #liveId   = `obc-l-${Math.random().toString(36).slice(2, 8)}`;
+  #valueHostControlled = false;
+  #lastEmittedComplete = false;
+  #boundChange = null;
+  #boundClick = null;
+
+  // ── attribute parsing ────────────────────────────────────────
+  //
+  // `items` + `value` accept JSON strings via the HTML attribute path
+  // (the canonical authoring shape for a2ui-generated markup). The
+  // default UIElement `attributeChangedCallback` would assign the
+  // string verbatim to the property — breaking the array/object shape.
+  // Override to parse JSON before assignment for those two props.
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (name === 'items' || name === 'value') {
+      if (newVal == null) {
+        this[name] = name === 'items' ? [] : {};
+      } else {
+        try {
+          const parsed = JSON.parse(newVal);
+          this[name] = parsed;
+        } catch {
+          this[name] = name === 'items' ? [] : {};
+        }
+      }
+      return;
+    }
+    super.attributeChangedCallback(name, oldVal, newVal);
+  }
+
+  connected() {
+    this.setAttribute('role', 'region');
+    this.setAttribute('aria-labelledby', this.#headerId);
+
+    // Late-parse JSON attributes that were present at construct time
+    // (UIElement reads the attribute as a String, so we re-parse here).
+    if (this.hasAttribute('items') && !Array.isArray(this.items)) {
+      try { this.items = JSON.parse(this.getAttribute('items')); }
+      catch { this.items = []; }
+    }
+    if (this.hasAttribute('value') && (typeof this.value !== 'object' || Array.isArray(this.value))) {
+      try { this.value = JSON.parse(this.getAttribute('value')); }
+      catch { this.value = {}; }
+    }
+
+    // Determine whether host is supplying `value` (host-controlled mode).
+    // If host set the property before connect, treat as host-controlled
+    // and skip storage hydration.
+    this.#valueHostControlled = this.value && Object.keys(this.value).length > 0;
+    if (!this.#valueHostControlled) {
+      const hydrated = this.#readStorage();
+      if (hydrated) this.value = hydrated;
+    }
+
+    this.#boundChange = this.#onChange.bind(this);
+    this.#boundClick  = this.#onClick.bind(this);
+    this.addEventListener('change', this.#boundChange);
+    this.addEventListener('click',  this.#boundClick);
+
+    this.#lastEmittedComplete = this.#isAllDone();
+    this.#syncCompletionAttrs();
+  }
+
+  disconnected() {
+    if (this.#boundChange) this.removeEventListener('change', this.#boundChange);
+    if (this.#boundClick)  this.removeEventListener('click',  this.#boundClick);
+    this.#boundChange = null;
+    this.#boundClick  = null;
+
+    // Persist final state on detach if storage-key is set.
+    this.#writeStorage();
+  }
+
+  // ── render ───────────────────────────────────────────────────
+
+  render() {
+    // Sync per-item completion attributes after each stamp (the
+    // template engine handles primary structure; this keeps reflected
+    // attrs + aria correct after items/value changes).
+    this.#syncCompletionAttrs();
+    this.#announceProgress();
+    this.#maybeEmitComplete();
+  }
+
+  _renderTemplate() {
+    const safeItems = Array.isArray(this.items) ? this.items : [];
+    const { done, total, percent } = this.#progressSnapshot();
+    const collapseLabel = this.collapsed ? 'Expand' : 'Collapse';
+    const collapseIcon  = this.collapsed ? 'chevron-down' : 'chevron-up';
+    const showCollapse  = !!this.collapsible;
+    const headerTitle   = this.title || 'Get started';
+    const allDone       = total > 0 && done === total;
+
+    // The body content (progress + items + footer) is hidden via CSS
+    // when [collapsed] is set; we keep the nodes mounted so collapsing
+    // is a paint-only operation and focus inside the item list is
+    // preserved across collapse/expand toggles.
+
+    return html`
+      <div data-part="header">
+        <div data-part="title" id=${this.#headerId}>${headerTitle}</div>
+        ${showCollapse
+          ? html`<button-ui
+              data-part="collapse-toggle"
+              variant="ghost"
+              size="sm"
+              .icon=${collapseIcon}
+              aria-expanded=${String(!this.collapsed)}
+              aria-controls=${this.#liveId}
+              aria-label=${collapseLabel}
+              @click=${(e) => this.#onCollapseToggle(e)}
+            ></button-ui>`
+          : null}
+      </div>
+      <progress-ui
+        data-part="progress"
+        .value=${percent}
+        aria-label="Onboarding progress"
+      ></progress-ui>
+      <div
+        data-part="meter"
+        id=${this.#liveId}
+        aria-live="polite"
+        aria-atomic="true"
+      >${total > 0
+          ? (allDone ? 'All steps complete' : `${done} of ${total} steps complete`)
+          : ''}</div>
+      <list-ui data-part="items">
+        ${safeItems.map((item) => this.#renderItem(item))}
+      </list-ui>
+      ${allDone && !this['dismiss-on-complete']
+        ? html`<div data-part="complete">
+            <slot name="complete"></slot>
+            <button-ui
+              data-part="dismiss"
+              variant="primary"
+              size="sm"
+              text="Done"
+              @click=${() => this.#dismiss('user')}
+            ></button-ui>
+          </div>`
+        : null}
+      <div data-part="footer"><slot name="footer"></slot></div>
+    `;
+  }
+
+  #renderItem(item) {
+    const id          = String(item?.id ?? '');
+    const label       = String(item?.label ?? '');
+    const description = String(item?.description ?? '');
+    const href        = String(item?.href ?? '');
+    const done        = this.#isItemDone(item);
+    return html`
+      <list-item-ui data-item-id=${id} data-done=${String(done)}>
+        <check-ui
+          slot="icon"
+          data-step-check
+          data-step-id=${id}
+          .checked=${done}
+          aria-label=${label}
+        ></check-ui>
+        <span slot="text">${label}</span>
+        ${description
+          ? html`<span slot="description">${description}</span>`
+          : null}
+        ${href
+          ? html`<button-ui
+              slot="action"
+              data-step-action
+              data-step-id=${id}
+              data-href=${href}
+              variant="ghost"
+              icon-trailing="arrow-right"
+              text="Open"
+            ></button-ui>`
+          : null}
+      </list-item-ui>
+    `;
+  }
+
+  // ── event delegation ─────────────────────────────────────────
+
+  #onChange(e) {
+    const target = e.target;
+    if (!target || !target.closest) return;
+    const check = target.closest('[data-step-check]');
+    if (!check || !this.contains(check)) return;
+
+    const id = check.getAttribute('data-step-id') || '';
+    if (!id) return;
+
+    const wasDone = this.#isItemDoneById(id);
+    const nowDone = !!check.checked;
+    if (wasDone === nowDone) return;
+
+    this.#setItemDone(id, nowDone, { emit: nowDone });
+  }
+
+  #onClick(e) {
+    const target = e.target;
+    if (!target || !target.closest) return;
+    const action = target.closest('[data-step-action]');
+    if (!action || !this.contains(action)) return;
+
+    const id   = action.getAttribute('data-step-id') || '';
+    const href = action.getAttribute('data-href')    || '';
+    if (!id) return;
+
+    this.dispatchEvent(new CustomEvent('onboarding-step-action', {
+      bubbles: true,
+      detail: { id, href },
+    }));
+    // Per spec OD-001 — clicking the CTA does NOT auto-complete.
+  }
+
+  #onCollapseToggle(e) {
+    e?.stopPropagation?.();
+    const next = !this.collapsed;
+    this.collapsed = next;
+    if (next) {
+      this.dispatchEvent(new CustomEvent('onboarding-dismiss', {
+        bubbles: true,
+        detail: { reason: 'collapsed' },
+      }));
+    }
+  }
+
+  // ── state helpers ────────────────────────────────────────────
+
+  #isItemDone(item) {
+    if (!item) return false;
+    const id = item.id;
+    if (id != null && Object.prototype.hasOwnProperty.call(this.value || {}, id)) {
+      return !!this.value[id];
+    }
+    return !!item.done;
+  }
+
+  #isItemDoneById(id) {
+    const safeItems = Array.isArray(this.items) ? this.items : [];
+    const it = safeItems.find((i) => i && String(i.id) === String(id));
+    return this.#isItemDone(it);
+  }
+
+  #setItemDone(id, done, { emit = true } = {}) {
+    const next = { ...(this.value || {}), [id]: !!done };
+    this.value = next;
+    this.#writeStorage();
+    if (emit && done) {
+      this.dispatchEvent(new CustomEvent('onboarding-step-complete', {
+        bubbles: true,
+        detail: { id, value: next },
+      }));
+    }
+  }
+
+  #progressSnapshot() {
+    const safeItems = Array.isArray(this.items) ? this.items : [];
+    const total = safeItems.length;
+    let done = 0;
+    for (const it of safeItems) if (this.#isItemDone(it)) done++;
+    const percent = total === 0 ? 0 : Math.round((done / total) * 100);
+    return { done, total, percent };
+  }
+
+  #isAllDone() {
+    const { done, total } = this.#progressSnapshot();
+    return total > 0 && done === total;
+  }
+
+  #syncCompletionAttrs() {
+    if (this.#isAllDone()) this.setAttribute('data-complete', '');
+    else this.removeAttribute('data-complete');
+  }
+
+  #maybeEmitComplete() {
+    const isDone = this.#isAllDone();
+    if (isDone && !this.#lastEmittedComplete) {
+      this.#lastEmittedComplete = true;
+      this.dispatchEvent(new CustomEvent('onboarding-complete', {
+        bubbles: true,
+        detail: { value: this.value },
+      }));
+      // dismiss-on-complete now defaults FALSE — by default the widget stays
+      // and surfaces a "Dismiss" button so the user controls when it goes away
+      // (per operator: a button rather than the widget silently vanishing).
+      // Auto-dismiss is opt-in via the [dismiss-on-complete] attribute.
+      if (this['dismiss-on-complete']) this.#dismiss('complete');
+    } else if (!isDone) {
+      this.#lastEmittedComplete = false;
+    }
+  }
+
+  /** Hide the checklist + announce dismissal. Triggered by the user's Dismiss
+   *  button on completion, or automatically when [dismiss-on-complete] is set. */
+  #dismiss(reason = 'user') {
+    this.setAttribute('hidden', '');
+    this.dispatchEvent(new CustomEvent('onboarding-dismiss', {
+      bubbles: true,
+      detail: { reason },
+    }));
+  }
+
+  #announceProgress() {
+    // The live region's textContent is set declaratively in the
+    // template; nothing else to do here — the polite live region
+    // re-reads on text change.
+  }
+
+  // ── storage ──────────────────────────────────────────────────
+
+  #storageArea() {
+    if (this.#valueHostControlled) return null;
+    if (this.storage === 'none') return null;
+    if (!this['storage-key']) return null;
+    if (typeof window === 'undefined') return null;
+    try {
+      return this.storage === 'session' ? window.sessionStorage : window.localStorage;
+    } catch {
+      return null;
+    }
+  }
+
+  #readStorage() {
+    const area = this.#storageArea();
+    if (!area) return null;
+    try {
+      const raw = area.getItem(this['storage-key']);
+      if (!raw) return null;
+      const parsed = JSON.parse(raw);
+      return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+
+  #writeStorage() {
+    const area = this.#storageArea();
+    if (!area) return;
+    try {
+      area.setItem(this['storage-key'], JSON.stringify(this.value || {}));
+    } catch {
+      /* quota / privacy mode — silently ignore */
+    }
+  }
+
+  // ── public methods ───────────────────────────────────────────
+
+  /**
+   * Mark an item as done (idempotent). Fires `onboarding-step-complete`
+   * if the item transitions from undone → done.
+   */
+  complete(id) {
+    if (id == null) return;
+    const key = String(id);
+    const was = this.#isItemDoneById(key);
+    if (was) return;
+    this.#setItemDone(key, true, { emit: true });
+  }
+
+  /**
+   * Reset one item (or all items, when id is omitted) to undone. Wipes
+   * the storage entry when resetting all.
+   */
+  reset(id) {
+    if (id == null) {
+      this.value = {};
+      const area = this.#storageArea();
+      try { area?.removeItem(this['storage-key']); } catch { /* ignore */ }
+      this.#lastEmittedComplete = false;
+      this.removeAttribute('hidden');
+      return;
+    }
+    const key = String(id);
+    if (!Object.prototype.hasOwnProperty.call(this.value || {}, key)) return;
+    this.#setItemDone(key, false, { emit: false });
+  }
+
+  /** Snapshot of progress numbers. */
+  progress() {
+    return this.#progressSnapshot();
+  }
+}
+
+if (!customElements.get('onboarding-checklist-ui')) {
+  customElements.define('onboarding-checklist-ui', UIOnboardingChecklist);
+}
+
+export { UIOnboardingChecklist };

package/onboarding/onboarding-checklist/onboarding-checklist.yaml

@@ -0,0 +1,236 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIOnboardingChecklist
+tag: onboarding-checklist-ui
+status: stable
+component: OnboardingChecklist
+category: feedback
+version: 1
+description: |
+  Module-tier onboarding checklist — a progressive setup-step widget
+  ("Getting started" card seen in Stripe / Linear / Vercel dashboards).
+  Composes <progress-ui> (top fill bar), <list-ui> + <list-item-ui>
+  (the step rows), <check-ui> (per-item completion checkbox), and
+  optional <button-ui> (per-item action CTA).
+
+  Owns the data model (items: array of {id, label, description, href,
+  done}), the persistence contract (storage-key writes a JSON blob to
+  localStorage / sessionStorage), the auto-computed progress display,
+  and the dismiss-on-complete behavior. Items are data, not slotted
+  markup — host wiring uses stable per-item ids, not DOM positions.
+
+  Use for the "card of optional setup tasks" case; use <step-progress-ui>
+  for horizontal multi-screen wizards where the user is locked into
+  linear progression.
+
+props:
+  items:
+    description: Step list — each item is { id, label, description?, href?, done? }. Required, non-empty.
+    type: array
+    default: []
+    required: true
+    dynamic: true
+  storage-key:
+    description: localStorage key for per-item completion persistence. Empty string disables storage (ephemeral).
+    type: string
+    default: ""
+    reflect: true
+  storage:
+    description: Persistence backend when storage-key is set.
+    type: string
+    default: local
+    enum: [local, session, none]
+    reflect: true
+  dismiss-on-complete:
+    description: Auto-hide the widget when all items are done.
+    type: boolean
+    default: true
+    reflect: true
+  collapsible:
+    description: Show a top-right collapse toggle.
+    type: boolean
+    default: true
+    reflect: true
+  collapsed:
+    description: Initial / current collapsed state — hides the item list, keeps progress + header visible.
+    type: boolean
+    default: false
+    reflect: true
+    dynamic: true
+  value:
+    description: "Completion map mapping item id to boolean. When set, host owns state and storage attributes are ignored."
+    type: object
+    default: {}
+    dynamic: true
+  title:
+    description: Header label above the progress bar. Defaults to "Get started".
+    type: string
+    default: "Get started"
+    reflect: true
+
+events:
+  onboarding-step-complete:
+    description: Fired when a step transitions from undone to done.
+    detail:
+      id:
+        type: string
+        description: The id of the step that just completed.
+      value:
+        type: object
+        description: Snapshot of the full completion map after the change.
+  onboarding-step-action:
+    description: Fired when the user clicks an item's action CTA.
+    detail:
+      id:
+        type: string
+        description: The id of the step whose CTA was clicked.
+      href:
+        type: string
+        description: The href of the CTA (may be empty when host wires the click elsewhere).
+  onboarding-complete:
+    description: Fired when all items become done.
+    detail:
+      value:
+        type: object
+        description: The completion map at the moment of full completion.
+  onboarding-dismiss:
+    description: Fired when the widget collapses or auto-dismisses on completion.
+    detail:
+      reason:
+        type: string
+        description: Why the widget was dismissed.
+        enum: [collapsed, complete]
+
+slots:
+  header:
+    description: Custom title region above the progress bar. Overrides the default [title] attribute label.
+  description:
+    description: >-
+      Optional subtitle / supporting prose rendered beneath the header.
+      Renders at body-subtle typography. Use for richer markup than the
+      plain [description] attribute string.
+  footer:
+    description: Optional footer content (e.g. "Skip for now" link / button).
+  complete:
+    description: Content shown when all items are done and dismiss-on-complete is false.
+
+states:
+  - name: idle
+    description: Some items incomplete; widget visible and expanded.
+  - name: collapsed
+    description: Item list hidden; header + progress visible.
+    attribute: collapsed
+  - name: complete
+    description: All items done. Behavior depends on dismiss-on-complete.
+    attribute: data-complete
+  - name: dismissed
+    description: Widget removed from layout after collapse or auto-dismiss.
+    attribute: hidden
+
+traits: []
+
+tokens:
+  --onboarding-checklist-bg:
+    description: Card background. Defaults to elevated canvas tier.
+    default: var(--a-canvas-1)
+  --onboarding-checklist-fg:
+    description: Primary foreground color.
+    default: var(--a-fg)
+  --onboarding-checklist-fg-muted:
+    description: Secondary foreground color for descriptions + meta.
+    default: var(--a-fg-muted)
+  --onboarding-checklist-radius:
+    description: Outer card radius.
+    default: var(--a-radius-lg)
+  --onboarding-checklist-px:
+    description: Inline (left/right) padding.
+    default: var(--a-space-4)
+  --onboarding-checklist-py:
+    description: Block (top/bottom) padding.
+    default: var(--a-space-4)
+  --onboarding-checklist-gap:
+    description: Gap between header / progress / items / footer.
+    default: var(--a-space-3)
+  --onboarding-checklist-progress-fill:
+    description: Progress-bar fill color (forwarded to inner <progress-ui> via --progress-fill).
+    default: var(--md-sys-color-primary)
+  --onboarding-checklist-shadow:
+    description: Card elevation.
+    default: var(--a-shadow-sm)
+  --onboarding-checklist-border:
+    description: Outer border.
+    default: 1px solid var(--a-border-subtle)
+
+a2ui:
+  rules:
+    - rule: 'OnboardingChecklist MUST have a non-empty `items` array. Empty items renders an empty card.'
+      reason: 'Without steps the widget has nothing to display.'
+    - rule: 'Each item MUST have a unique `id` within the list — used as the storage key + event detail.'
+      reason: 'Stable per-item identifier; completion cannot be persisted otherwise.'
+    - rule: '`storageKey` SHOULD be namespaced per product (e.g. `myapp:onboarding:v1`) to avoid cross-app collisions.'
+      reason: 'localStorage is a shared global key-space across the origin.'
+    - rule: 'Items SHOULD number 3 to 8. Fewer than 3 is not worth a checklist; more than 8 should split into stages.'
+      reason: 'Empirical product-design heuristic — readable progress, no overwhelm.'
+    - rule: 'Use for the "card of optional setup tasks" case. For horizontal multi-screen wizards use <step-progress-ui>; for generic to-do lists compose <list-ui> + <check-ui> directly.'
+      reason: 'Onboarding-specific semantics (dismiss-on-complete, persistent storage) leak into generic lists.'
+    - rule: 'Do not nest two <onboarding-checklist-ui> with the same `storageKey` — they will clobber each other.'
+      reason: 'Single storage slot per key.'
+
+anti_patterns:
+  - wrong: |
+      { "component": "OnboardingChecklist", "items": [] }
+    why: |
+      Empty checklist — renders an empty card.
+    fix: |
+      { "component": "OnboardingChecklist", "items": [{ "id": "x", "label": "Step 1" }] }
+  - wrong: |
+      { "component": "OnboardingChecklist", "items": [
+        { "label": "Step A" }, { "label": "Step B" }
+      ] }
+    why: |
+      Items missing `id`. The component cannot persist completion
+      without stable per-item identifiers.
+    fix: |
+      { "component": "OnboardingChecklist", "items": [
+        { "id": "a", "label": "Step A" }, { "id": "b", "label": "Step B" }
+      ] }
+
+examples:
+  - name: basic-checklist
+    description: Three-step dashboard setup card.
+    a2ui: |
+      [
+        {
+          "id": "onb-1",
+          "component": "OnboardingChecklist",
+          "storageKey": "acme:onboarding:v1",
+          "items": [
+            { "id": "profile", "label": "Complete your profile", "description": "Add a photo and bio", "href": "/settings/profile" },
+            { "id": "team",    "label": "Invite your team",      "description": "Add at least one teammate", "href": "/settings/team" },
+            { "id": "connect", "label": "Connect a data source", "description": "Hook up the first integration", "href": "/integrations" }
+          ]
+        }
+      ]
+
+keywords:
+  - onboarding
+  - checklist
+  - getting-started
+  - setup
+  - steps
+  - progress
+  - getting started
+
+synonyms:
+  onboarding: [getting-started, setup, welcome, kickoff]
+  checklist: [todo, task-list, steps]
+  getting-started: [onboarding, setup, welcome]
+  setup: [onboarding, getting-started, configuration]
+
+related:
+  - Check
+  - List
+  - ListItem
+  - Progress
+  - Button
+  - StepProgress