@adia-ai/web-components 0.6.38 → 0.6.40

package/components/tour/tour-step.a2ui.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/TourStep.json",
+  "title": "TourStep",
+  "description": "Single step inside a `<tour-ui>` walkthrough. Declares a target\nelement (via CSS selector), a title, and body content. The host\n`<tour-ui>` reads these declaratively and renders them in the\npopover as the user advances through the tour.\n\n`<tour-step>` itself renders nothing — it's a data carrier (light\nDOM source of truth). The tour-ui orchestrator clones the body\ncontent into the spotlight popover when the step becomes active.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "title": {
+      "description": "Step heading rendered in the popover.",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "TourStep"
+    },
+    "placement": {
+      "description": "Preferred popover placement relative to the target. Same vocabulary\nas `core/anchor.js` (`top`, `bottom`, `left`, `right`,\n`bottom-start`, `bottom-end`, etc.). Auto-flips on viewport overflow\nvia position-try-fallbacks.\n",
+      "type": "string",
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end",
+        "left-start",
+        "left-end",
+        "right-start",
+        "right-end"
+      ],
+      "default": "bottom"
+    },
+    "target": {
+      "description": "CSS selector for the element to spotlight when this step is\nactive. Resolved via `document.querySelector(target)` at step\nactivation time. If the selector matches nothing, the spotlight\nfalls back to viewport-center and the popover anchors to the\npage (no halo cutout).\n",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<tour-step target=\"#dashboard\">",
+        "why": "target is a CSS selector — bare \"dashboard\" doesn't match.",
+        "wrong": "<tour-step target=\"dashboard\">"
+      }
+    ],
+    "category": "feedback",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "tour-step",
+      "walkthrough-step",
+      "guided-step"
+    ],
+    "name": "UITourStep",
+    "related": [
+      "tour"
+    ],
+    "slots": {
+      "default": {
+        "description": "Body content rendered inside the step popover (plain text or inline HTML)."
+      }
+    },
+    "states": [],
+    "status": "stable",
+    "synonyms": {
+      "step": [
+        "tour-step",
+        "walkthrough-step"
+      ]
+    },
+    "tag": "tour-step-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/tour/tour-step.yaml

@@ -0,0 +1,84 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITourStep
+tag: tour-step-ui
+status: stable
+component: TourStep
+category: feedback
+version: 1
+description: |
+  Single step inside a `<tour-ui>` walkthrough. Declares a target
+  element (via CSS selector), a title, and body content. The host
+  `<tour-ui>` reads these declaratively and renders them in the
+  popover as the user advances through the tour.
+
+  `<tour-step>` itself renders nothing — it's a data carrier (light
+  DOM source of truth). The tour-ui orchestrator clones the body
+  content into the spotlight popover when the step becomes active.
+props:
+  target:
+    description: |
+      CSS selector for the element to spotlight when this step is
+      active. Resolved via `document.querySelector(target)` at step
+      activation time. If the selector matches nothing, the spotlight
+      falls back to viewport-center and the popover anchors to the
+      page (no halo cutout).
+    type: string
+    default: ''
+    reflect: true
+  title:
+    description: Step heading rendered in the popover.
+    type: string
+    default: ''
+    reflect: true
+  placement:
+    description: |
+      Preferred popover placement relative to the target. Same vocabulary
+      as `core/anchor.js` (`top`, `bottom`, `left`, `right`,
+      `bottom-start`, `bottom-end`, etc.). Auto-flips on viewport overflow
+      via position-try-fallbacks.
+    type: string
+    default: bottom
+    enum:
+      - top
+      - bottom
+      - left
+      - right
+      - top-start
+      - top-end
+      - bottom-start
+      - bottom-end
+      - left-start
+      - left-end
+      - right-start
+      - right-end
+    reflect: true
+events: {}
+slots:
+  default:
+    description: 'Body content rendered inside the step popover (plain text or inline HTML).'
+states: []
+traits: []
+tokens: {}
+a2ui:
+  rules:
+    - rule: 'Single step inside <tour-ui>. Declares target (CSS selector) + title + body content.'
+      reason: 'Data carrier for tour-ui.'
+    - rule: 'target is a CSS selector (e.g. "#dashboard", ".filters button"), NOT a bare ID. Use the # prefix.'
+      reason: 'Selector contract.'
+    - rule: 'Renders nothing on its own — tour-ui orchestrates the popover stamping when the step becomes active.'
+      reason: 'Stamp-nothing wrapper.'
+anti_patterns:
+  - wrong: '<tour-step target="dashboard">'
+    why: 'target is a CSS selector — bare "dashboard" doesn''t match.'
+    fix: '<tour-step target="#dashboard">'
+examples: []
+keywords:
+  - tour-step
+  - walkthrough-step
+  - guided-step
+synonyms:
+  step:
+    - tour-step
+    - walkthrough-step
+related:
+  - tour

package/components/tour/tour.a2ui.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Tour.json",
+  "title": "Tour",
+  "description": "Spotlight-driven product tour / guided walkthrough. Hosts a sequence\nof `<tour-step>` children, each targeting an element via CSS selector.\nWhen active, dims the page with a scrim, cuts a \"hole\" around the\ncurrent step's target, and renders a popover next to it with step\ncontent + Skip / Previous / Next navigation.\n\nUse for first-run onboarding tours, feature introductions after a\nrelease, and inline walkthroughs the user opts into (\"Take the tour\").\nDistinct from `<onboarding-checklist-ui>` (persistent todo-list of\nsetup steps the user works through at their own pace) and from\n`<tooltip-ui>` (single hover hint with no orchestration).\n\nArchitecture: tour-ui is a behavioral wrapper (`display: contents`)\nthat reads target / title / content from `<tour-step>` children. On\nstart, mounts a spotlight + popover surface into `document.body`\n(top-layer via Popover API). The spotlight is a transparent\nposition:fixed element with a huge box-shadow that produces the\ndimmed scrim outside its bounds (single-element backdrop, no clip-path\nor SVG mask needed). The popover is anchored to the target via the\nsame `core/anchor.js` pattern used by menu-ui / context-menu-ui /\npopover-ui.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "active": {
+      "description": "Whether the tour is currently running. Setting to `true` mounts\nthe spotlight + popover; setting to `false` tears down.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "auto-start": {
+      "description": "Start the tour automatically when the element connects. Useful for\nfirst-run flows gated by a storage flag on the consumer side.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "Tour"
+    },
+    "step": {
+      "description": "Current step index (0-based). Setting this property advances the\ntour to that step (updating spotlight + popover position).\n",
+      "type": "number",
+      "default": 0
+    },
+    "storage-key": {
+      "description": "Optional localStorage key. When set, the tour records its\ncompletion state (`\"done\"`) to that key on finish/skip — and\nrefuses to auto-start on subsequent loads if the key is \"done\".\nUseful for \"show this tour once per user\" flows.\n",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "<tour-ui><tour-step target=\"#dashboard\" title=\"Dashboard\">Tour the dashboard…</tour-step>…</tour-ui>",
+        "why": "Bare divs have no target / title — tour-ui can't position the spotlight.",
+        "wrong": "<tour-ui><div>step 1 content</div><div>step 2 content</div></tour-ui>"
+      },
+      {
+        "fix": "<tour-step target=\"#dashboard\">",
+        "why": "target is a CSS selector — bare \"dashboard\" matches a <dashboard> element, NOT an id; use the # prefix.",
+        "wrong": "<tour-step target=\"dashboard\">"
+      }
+    ],
+    "category": "feedback",
+    "composes": [
+      "button-ui",
+      "tour-step-ui"
+    ],
+    "events": {
+      "tour-finish": {
+        "description": "Fired when the user completes the last step. detail = { totalSteps }. Bubbles."
+      },
+      "tour-skip": {
+        "description": "Fired when the user skips the tour mid-way. detail = { step, totalSteps }. Bubbles."
+      },
+      "tour-start": {
+        "description": "Fired when the tour starts (after spotlight + popover mount). detail = { step }. Bubbles."
+      },
+      "tour-step-change": {
+        "description": "Fired when the active step changes. detail = { from, to, totalSteps }. Bubbles."
+      }
+    },
+    "examples": [
+      {
+        "description": "A 3-step product tour anchored to selector-resolved elements.",
+        "a2ui": "[\n  { \"id\": \"tour\", \"component\": \"Tour\", \"auto-start\": true, \"children\": [\"s1\", \"s2\", \"s3\"] },\n  { \"id\": \"s1\", \"component\": \"TourStep\", \"target\": \"#dashboard\", \"title\": \"Your dashboard\", \"textContent\": \"Here's where you'll see your latest activity.\" },\n  { \"id\": \"s2\", \"component\": \"TourStep\", \"target\": \"#filters\", \"title\": \"Filters\", \"textContent\": \"Narrow results by status, owner, or date.\" },\n  { \"id\": \"s3\", \"component\": \"TourStep\", \"target\": \"#export\", \"title\": \"Export\", \"textContent\": \"Download a CSV of the current view.\" }\n]\n",
+        "name": "basic-tour"
+      }
+    ],
+    "keywords": [
+      "tour",
+      "product-tour",
+      "walkthrough",
+      "guided-tour",
+      "spotlight",
+      "coachmark",
+      "feature-introduction"
+    ],
+    "name": "UITour",
+    "related": [
+      "tooltip",
+      "popover",
+      "onboarding-checklist"
+    ],
+    "slots": {
+      "default": {
+        "description": "<tour-step> children — each declares target + title + body content."
+      }
+    },
+    "states": [
+      {
+        "description": "Tour is dormant; no scrim / popover rendered.",
+        "name": "idle"
+      },
+      {
+        "description": "Tour is running; scrim dims the page, current target is spotlighted.",
+        "name": "active"
+      },
+      {
+        "description": "Last step reached (Done is shown instead of Next).",
+        "name": "complete"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "spotlight": [
+        "coachmark",
+        "feature-highlight"
+      ],
+      "tour": [
+        "product-tour",
+        "guided-tour",
+        "walkthrough",
+        "feature-intro"
+      ]
+    },
+    "tag": "tour-ui",
+    "tokens": {
+      "--tour-popover-bg": {
+        "description": "Background of the step-content popover.",
+        "default": "var(--a-bg-subtle)"
+      },
+      "--tour-popover-border": {
+        "description": "Border color of the popover.",
+        "default": "var(--a-border-subtle)"
+      },
+      "--tour-popover-max-width": {
+        "description": "Maximum width of the popover.",
+        "default": "22rem"
+      },
+      "--tour-popover-min-width": {
+        "description": "Minimum width of the popover (so step text wraps reasonably).",
+        "default": "18rem"
+      },
+      "--tour-popover-radius": {
+        "description": "Border-radius of the popover.",
+        "default": "var(--a-radius-lg)"
+      },
+      "--tour-popover-shadow": {
+        "description": "Shadow of the popover.",
+        "default": "var(--a-shadow-lg)"
+      },
+      "--tour-scrim": {
+        "description": "Backdrop scrim color (everything outside the spotlight).",
+        "default": "var(--a-scrim-dialog)"
+      },
+      "--tour-spotlight-padding": {
+        "description": "Padding around the target bounding box (the spotlight's \"halo\").",
+        "default": "var(--a-space-2)"
+      },
+      "--tour-spotlight-radius": {
+        "description": "Border radius of the spotlight cutout.",
+        "default": "var(--a-radius-md)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/tour/tour.class.js

@@ -0,0 +1,309 @@
+/**
+ * `<tour-ui>` — spotlight-driven product tour / guided walkthrough.
+ *
+ * Orchestrates a sequence of `<tour-step>` children, each declaring a
+ * target element via CSS selector. When active, dims the page with a
+ * scrim, cuts a "hole" around the current step's target, and renders
+ * a popover next to it with step content + Skip / Previous / Next.
+ *
+ * Architecture:
+ *   - Host is `display: contents` (no chrome).
+ *   - On start, mounts two surfaces into `document.body`:
+ *     1. [data-tour-spotlight] — transparent rect with huge box-shadow
+ *        scrim. Position via top/left, size via width/height (animated).
+ *     2. [data-tour-popover] — manual popover with step content + nav,
+ *        anchored to the target via core/anchor.js (same mechanism as
+ *        menu-ui / context-menu-ui / popover-ui).
+ *   - Spotlight repositions on window resize/scroll while active.
+ *
+ * @see ../../core/anchor.js
+ * @see ../onboarding-checklist/ — peer onboarding primitive (user-paced).
+ */
+
+import { UIElement } from '../../core/element.js';
+import { anchorPopover } from '../../core/anchor.js';
+
+export class UITour extends UIElement {
+  static properties = {
+    active:        { type: Boolean, default: false, reflect: true },
+    step:          { type: Number,  default: 0,     reflect: false },
+    autoStart:     { type: Boolean, default: false, reflect: true, attribute: 'auto-start' },
+    storageKey:    { type: String,  default: '',    reflect: true, attribute: 'storage-key' },
+  };
+
+  static template = () => null;
+
+  #spotlight = null;
+  #popover = null;
+  #anchorCleanup = null;
+  #onResize = null;
+  #onScroll = null;
+  #onKeydown = null;
+
+  connected() {
+    super.connected();
+    if (this.autoStart && !this.#alreadyDone()) {
+      // Defer one frame so consumer targets (which may also mount on the
+      // same tick) have a chance to land in the DOM first.
+      requestAnimationFrame(() => {
+        if (this.isConnected && this.autoStart) this.start();
+      });
+    }
+  }
+
+  disconnected() {
+    super.disconnected();
+    this.#teardown();
+  }
+
+  /* ── Public API ──────────────────────────────────────────────────── */
+
+  start() {
+    if (this.active) return;
+    if (!this.#steps.length) {
+      // eslint-disable-next-line no-console
+      console.warn('[tour-ui] start() called with no <tour-step> children — nothing to render.');
+      return;
+    }
+    this.step = 0;
+    this.active = true;
+    this.#mount();
+    this.#renderStep();
+    this.dispatchEvent(new CustomEvent('tour-start', {
+      bubbles: true,
+      detail: { step: 0 },
+    }));
+  }
+
+  next() {
+    if (!this.active) return;
+    const total = this.#steps.length;
+    if (this.step >= total - 1) { this.finish(); return; }
+    const from = this.step;
+    this.step = from + 1;
+    this.#renderStep();
+    this.dispatchEvent(new CustomEvent('tour-step-change', {
+      bubbles: true,
+      detail: { from, to: this.step, totalSteps: total },
+    }));
+  }
+
+  previous() {
+    if (!this.active) return;
+    if (this.step <= 0) return;
+    const from = this.step;
+    this.step = from - 1;
+    this.#renderStep();
+    this.dispatchEvent(new CustomEvent('tour-step-change', {
+      bubbles: true,
+      detail: { from, to: this.step, totalSteps: this.#steps.length },
+    }));
+  }
+
+  skip() {
+    if (!this.active) return;
+    const total = this.#steps.length;
+    const at = this.step;
+    this.#recordDone();
+    this.active = false;
+    this.#teardown();
+    this.dispatchEvent(new CustomEvent('tour-skip', {
+      bubbles: true,
+      detail: { step: at, totalSteps: total },
+    }));
+  }
+
+  finish() {
+    if (!this.active) return;
+    const total = this.#steps.length;
+    this.#recordDone();
+    this.active = false;
+    this.#teardown();
+    this.dispatchEvent(new CustomEvent('tour-finish', {
+      bubbles: true,
+      detail: { totalSteps: total },
+    }));
+  }
+
+  /* ── Internals ───────────────────────────────────────────────────── */
+
+  get #steps() {
+    return [...this.querySelectorAll(':scope > tour-step-ui')];
+  }
+
+  #alreadyDone() {
+    if (!this.storageKey) return false;
+    try { return localStorage.getItem(this.storageKey) === 'done'; }
+    catch { return false; }
+  }
+
+  #recordDone() {
+    if (!this.storageKey) return;
+    try { localStorage.setItem(this.storageKey, 'done'); }
+    catch { /* quota / privacy mode — silently ignore */ }
+  }
+
+  #mount() {
+    if (!this.#spotlight) {
+      const sp = document.createElement('div');
+      sp.setAttribute('data-tour-spotlight', '');
+      sp.setAttribute('aria-hidden', 'true');
+      document.body.appendChild(sp);
+      this.#spotlight = sp;
+    }
+    if (!this.#popover) {
+      const pop = document.createElement('div');
+      pop.setAttribute('data-tour-popover', '');
+      pop.setAttribute('popover', 'manual');
+      pop.setAttribute('role', 'dialog');
+      pop.setAttribute('aria-modal', 'false');
+      pop.tabIndex = -1;
+      pop.style.outline = 'none';
+      pop.addEventListener('click', this.#onPopoverClick);
+      document.body.appendChild(pop);
+      this.#popover = pop;
+    }
+
+    // Reposition spotlight on viewport changes while active. anchorPopover
+    // (called per-step in #renderStep) handles popover repositioning.
+    this.#onResize = () => this.#positionSpotlight();
+    this.#onScroll = () => this.#positionSpotlight();
+    window.addEventListener('resize', this.#onResize);
+    window.addEventListener('scroll', this.#onScroll, true /* capture */);
+
+    // Keyboard navigation
+    this.#onKeydown = (e) => {
+      if (!this.active) return;
+      if (e.key === 'Escape') { e.preventDefault(); this.skip(); }
+      else if (e.key === 'ArrowRight') { e.preventDefault(); this.next(); }
+      else if (e.key === 'ArrowLeft')  { e.preventDefault(); this.previous(); }
+    };
+    document.addEventListener('keydown', this.#onKeydown);
+  }
+
+  #teardown() {
+    this.#anchorCleanup?.();
+    this.#anchorCleanup = null;
+    if (this.#onResize) window.removeEventListener('resize', this.#onResize);
+    if (this.#onScroll) window.removeEventListener('scroll', this.#onScroll, true);
+    if (this.#onKeydown) document.removeEventListener('keydown', this.#onKeydown);
+    this.#onResize = this.#onScroll = this.#onKeydown = null;
+    try { this.#popover?.hidePopover?.(); } catch { /* noop */ }
+    this.#popover?.removeEventListener('click', this.#onPopoverClick);
+    this.#popover?.remove();
+    this.#popover = null;
+    this.#spotlight?.remove();
+    this.#spotlight = null;
+  }
+
+  #renderStep() {
+    const step = this.#steps[this.step];
+    if (!step) return;
+
+    const total = this.#steps.length;
+    const isLast = this.step === total - 1;
+    const isFirst = this.step === 0;
+    const title = step.getAttribute('title') || '';
+    const placement = step.getAttribute('placement') || 'bottom';
+    const targetSel = step.getAttribute('target') || '';
+    const target = targetSel ? document.querySelector(targetSel) : null;
+
+    // Spotlight position
+    this.#currentTarget = target;
+    this.#positionSpotlight();
+
+    // Popover content
+    const indicator = `${this.step + 1} of ${total}`;
+    const bodyHTML = step.innerHTML;
+    this.#popover.innerHTML = `
+      <div data-tour-header>
+        <span data-tour-indicator>${indicator}</span>
+        <span></span>
+      </div>
+      <h3 data-tour-title>${escapeHtml(title)}</h3>
+      <div data-tour-body>${bodyHTML}</div>
+      <div data-tour-footer>
+        <button-ui data-tour-skip variant="ghost" size="sm" text="Skip"></button-ui>
+        <div data-tour-nav>
+          ${isFirst ? '' : '<button-ui data-tour-previous variant="outline" size="sm" text="Back"></button-ui>'}
+          <button-ui data-tour-next variant="primary" size="sm" text="${isLast ? 'Done' : 'Next →'}"></button-ui>
+        </div>
+      </div>
+    `;
+
+    // Open the popover (idempotent) + position it.
+    try { this.#popover.showPopover(); } catch { /* popover API unavailable */ }
+    this.#anchorCleanup?.();
+    if (target) {
+      this.#anchorCleanup = anchorPopover(target, this.#popover, { placement, gap: 12 });
+    } else {
+      // No target — center the popover in the viewport
+      this.#popover.style.position = 'fixed';
+      this.#popover.style.top = '50%';
+      this.#popover.style.left = '50%';
+      this.#popover.style.transform = 'translate(-50%, -50%)';
+    }
+
+    // Move focus to the popover so keyboard nav works immediately
+    queueMicrotask(() => this.#popover?.focus?.());
+  }
+
+  #currentTarget = null;
+
+  #positionSpotlight() {
+    if (!this.#spotlight) return;
+    const target = this.#currentTarget;
+    if (!target) {
+      this.#spotlight.setAttribute('data-tour-no-target', '');
+      return;
+    }
+    this.#spotlight.removeAttribute('data-tour-no-target');
+    const rect = target.getBoundingClientRect();
+    // Add halo padding around the target
+    const cs = getComputedStyle(this);
+    const halo = parseFloat(cs.getPropertyValue('--tour-spotlight-padding')) || 8;
+    const top  = Math.max(0, rect.top - halo);
+    const left = Math.max(0, rect.left - halo);
+    const w = rect.width + halo * 2;
+    const h = rect.height + halo * 2;
+    this.#spotlight.style.top = `${top}px`;
+    this.#spotlight.style.left = `${left}px`;
+    this.#spotlight.style.width = `${w}px`;
+    this.#spotlight.style.height = `${h}px`;
+  }
+
+  #onPopoverClick = (e) => {
+    const t = e.target;
+    if (!t || !t.closest) return;
+    if (t.closest('[data-tour-skip]')) { this.skip(); return; }
+    if (t.closest('[data-tour-previous]')) { this.previous(); return; }
+    if (t.closest('[data-tour-next]')) { this.next(); return; }
+  };
+}
+
+/**
+ * `<tour-step>` — data carrier for a single step inside `<tour-ui>`.
+ *
+ * Renders nothing on its own (`display: none` via tour.css). tour-ui
+ * reads target / title / placement / body content from it on activation.
+ */
+export class UITourStep extends UIElement {
+  static properties = {
+    target:    { type: String, default: '',       reflect: true },
+    title:     { type: String, default: '',       reflect: true },
+    placement: { type: String, default: 'bottom', reflect: true },
+  };
+
+  static template = () => null;
+
+  // No connected/disconnected behavior needed — pure data carrier.
+}
+
+function escapeHtml(s) {
+  return String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}