@adia-ai/web-components 0.6.38 → 0.6.39

package/components/tour/tour.css

@@ -0,0 +1,135 @@
+@scope (tour-ui) {
+  :where(:scope) {
+    --tour-scrim-default:             var(--a-scrim-dialog);
+    --tour-spotlight-padding-default: var(--a-space-2);
+    --tour-spotlight-radius-default:  var(--a-radius-md);
+  }
+
+  :scope {
+    /* Behavioral wrapper — no chrome. Tour-step children are hidden;
+       the orchestrator clones their content into the popover surface. */
+    display: contents;
+  }
+
+  :scope > tour-step-ui {
+    display: none;
+  }
+}
+
+/* The spotlight + popover surfaces are NOT scoped to tour-ui — they're
+   appended to document.body (top-layer via Popover API), outside the
+   @scope (tour-ui) boundary. Mirror the menu-ui / context-menu-ui
+   pattern: chrome lives in the global scope keyed off a data-attribute. */
+
+/* ── Spotlight ──
+   A position:fixed transparent rectangle with a huge box-shadow that
+   produces the dimmed scrim everywhere outside its bounds. Single
+   element, no clip-path / SVG mask. Animated via top/left/width/height
+   transitions when the step changes. */
+[data-tour-spotlight] {
+  position: fixed;
+  inset: 0 auto auto 0;            /* anchor at viewport top-left; top/left set imperatively */
+  width: 0;
+  height: 0;
+  pointer-events: none;
+  border-radius: var(--tour-spotlight-radius, var(--a-radius-md));
+  background: transparent;
+  box-shadow: 0 0 0 9999px var(--tour-scrim, var(--a-scrim-dialog));
+  z-index: 1000;
+  transition:
+    top var(--a-duration) var(--a-easing-out),
+    left var(--a-duration) var(--a-easing-out),
+    width var(--a-duration) var(--a-easing-out),
+    height var(--a-duration) var(--a-easing-out);
+}
+
+[data-tour-spotlight][data-tour-no-target] {
+  /* No target match — fall back to a non-cutout full-viewport scrim */
+  inset: 0;
+  width: 100vw;
+  height: 100vh;
+  box-shadow: none;
+  background: var(--tour-scrim, var(--a-scrim-dialog));
+  border-radius: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-tour-spotlight] { transition: none; }
+}
+
+/* ── Step popover ── */
+[data-tour-popover] {
+  margin: 0;
+  padding: var(--a-space-4);
+  border: 1px solid var(--tour-popover-border, var(--a-border-subtle));
+  border-radius: var(--tour-popover-radius, var(--a-radius-lg));
+  background: var(--tour-popover-bg, var(--a-bg-subtle));
+  box-shadow: var(--tour-popover-shadow, var(--a-shadow-lg));
+  min-width: var(--tour-popover-min-width, 18rem);
+  max-width: var(--tour-popover-max-width, 22rem);
+  font-family: inherit;
+  font-size: var(--a-ui-size);
+  color: var(--a-fg);
+  /* Above the spotlight (1000) so the user can read + click it */
+  z-index: 1001;
+  opacity: 1;
+  translate: 0 0;
+  transition:
+    opacity var(--a-duration-fast) var(--a-easing-out),
+    translate var(--a-duration-fast) var(--a-easing-out);
+}
+
+[data-tour-popover]:popover-open {
+  @starting-style {
+    opacity: 0;
+    translate: 0 -4px;
+  }
+}
+
+[data-tour-popover]:not(:popover-open) {
+  display: none !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-tour-popover] { transition: none; }
+}
+
+/* Layout of the popover internal content (set by the orchestrator). */
+[data-tour-popover] [data-tour-header] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--a-space-3);
+  margin-block-end: var(--a-space-2);
+}
+
+[data-tour-popover] [data-tour-indicator] {
+  font-size: var(--a-ui-sm);
+  color: var(--a-fg-muted);
+  font-variant-numeric: tabular-nums;
+}
+
+[data-tour-popover] [data-tour-title] {
+  margin: 0;
+  font-size: var(--a-text-lg);
+  font-weight: 600;
+}
+
+[data-tour-popover] [data-tour-body] {
+  margin: 0 0 var(--a-space-4);
+  font-size: var(--a-ui-size);
+  color: var(--a-fg);
+  line-height: 1.5;
+}
+
+[data-tour-popover] [data-tour-footer] {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--a-space-2);
+}
+
+[data-tour-popover] [data-tour-nav] {
+  display: flex;
+  gap: var(--a-space-2);
+}

package/components/tour/tour.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `<tour-ui>` — Spotlight-driven product tour / guided walkthrough. Hosts a sequence
+of `<tour-step>` children, each targeting an 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 navigation.
+
+Use for first-run onboarding tours, feature introductions after a
+release, and inline walkthroughs the user opts into ("Take the tour").
+Distinct from `<onboarding-checklist-ui>` (persistent todo-list of
+setup steps the user works through at their own pace) and from
+`<tooltip-ui>` (single hover hint with no orchestration).
+
+Architecture: tour-ui is a behavioral wrapper (`display: contents`)
+that reads target / title / content from `<tour-step>` children. On
+start, mounts a spotlight + popover surface into `document.body`
+(top-layer via Popover API). The spotlight is a transparent
+position:fixed element with a huge box-shadow that produces the
+dimmed scrim outside its bounds (single-element backdrop, no clip-path
+or SVG mask needed). The popover is anchored to the target via the
+same `core/anchor.js` pattern used by menu-ui / context-menu-ui /
+popover-ui.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/tour
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type TourFinishEvent = CustomEvent<unknown>;
+export type TourSkipEvent = CustomEvent<unknown>;
+export type TourStartEvent = CustomEvent<unknown>;
+export type TourStepChangeEvent = CustomEvent<unknown>;
+
+export class UITour extends UIElement {
+  /** Whether the tour is currently running. Setting to `true` mounts
+the spotlight + popover; setting to `false` tears down.
+ */
+  active: boolean;
+  /** Current step index (0-based). Setting this property advances the
+tour to that step (updating spotlight + popover position).
+ */
+  step: number;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITour, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-start', listener: (ev: TourStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'tour-step-change', listener: (ev: TourStepChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}
+
+export class UITourStep extends UIElement {
+  /** Step heading rendered in the popover. */
+  title: string;
+  /** 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.
+ */
+  placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end';
+  /** 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).
+ */
+  target: string;
+}

package/components/tour/tour.js

@@ -0,0 +1,13 @@
+/**
+ * `<tour-ui>` + `<tour-step>` — auto-registers both tags on import.
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UITour, UITourStep } from './tour.class.js';
+
+defineIfFree('tour-ui', UITour);
+defineIfFree('tour-step-ui', UITourStep);
+
+export { UITour, UITourStep };

package/components/tour/tour.yaml

@@ -0,0 +1,161 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITour
+tag: tour-ui
+status: stable
+component: Tour
+category: feedback
+version: 1
+description: |
+  Spotlight-driven product tour / guided walkthrough. Hosts a sequence
+  of `<tour-step>` children, each targeting an 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 navigation.
+
+  Use for first-run onboarding tours, feature introductions after a
+  release, and inline walkthroughs the user opts into ("Take the tour").
+  Distinct from `<onboarding-checklist-ui>` (persistent todo-list of
+  setup steps the user works through at their own pace) and from
+  `<tooltip-ui>` (single hover hint with no orchestration).
+
+  Architecture: tour-ui is a behavioral wrapper (`display: contents`)
+  that reads target / title / content from `<tour-step>` children. On
+  start, mounts a spotlight + popover surface into `document.body`
+  (top-layer via Popover API). The spotlight is a transparent
+  position:fixed element with a huge box-shadow that produces the
+  dimmed scrim outside its bounds (single-element backdrop, no clip-path
+  or SVG mask needed). The popover is anchored to the target via the
+  same `core/anchor.js` pattern used by menu-ui / context-menu-ui /
+  popover-ui.
+composes:
+  - button-ui
+  - tour-step-ui
+props:
+  active:
+    description: |
+      Whether the tour is currently running. Setting to `true` mounts
+      the spotlight + popover; setting to `false` tears down.
+    type: boolean
+    default: false
+    reflect: true
+  step:
+    description: |
+      Current step index (0-based). Setting this property advances the
+      tour to that step (updating spotlight + popover position).
+    type: number
+    default: 0
+    reflect: false
+  auto-start:
+    description: |
+      Start the tour automatically when the element connects. Useful for
+      first-run flows gated by a storage flag on the consumer side.
+    type: boolean
+    default: false
+    reflect: true
+  storage-key:
+    description: |
+      Optional localStorage key. When set, the tour records its
+      completion state (`"done"`) to that key on finish/skip — and
+      refuses to auto-start on subsequent loads if the key is "done".
+      Useful for "show this tour once per user" flows.
+    type: string
+    default: ''
+    reflect: true
+events:
+  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.'
+  tour-skip:
+    description: 'Fired when the user skips the tour mid-way. detail = { step, totalSteps }. Bubbles.'
+  tour-finish:
+    description: 'Fired when the user completes the last step. detail = { totalSteps }. Bubbles.'
+slots:
+  default:
+    description: '<tour-step> children — each declares target + title + body content.'
+states:
+  - name: idle
+    description: Tour is dormant; no scrim / popover rendered.
+  - name: active
+    description: Tour is running; scrim dims the page, current target is spotlighted.
+  - name: complete
+    description: Last step reached (Done is shown instead of Next).
+traits: []
+tokens:
+  --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)
+  --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-shadow:
+    description: Shadow of the popover.
+    default: var(--a-shadow-lg)
+  --tour-popover-radius:
+    description: Border-radius of the popover.
+    default: var(--a-radius-lg)
+  --tour-popover-min-width:
+    description: Minimum width of the popover (so step text wraps reasonably).
+    default: 18rem
+  --tour-popover-max-width:
+    description: Maximum width of the popover.
+    default: 22rem
+a2ui:
+  rules:
+    - rule: 'Use tour-ui for spotlight-driven product tours / walkthroughs — sequence of steps each targeting a CSS-selector-resolved element.'
+      reason: 'Primary use case — guided feature introduction.'
+    - rule: 'Children are <tour-step target="..." title="..."> with body content as the default slot. tour-ui reads them in DOM order.'
+      reason: 'Authoring contract.'
+    - rule: 'Set [auto-start] for first-run flows (paired with [storage-key] so it only shows once). Otherwise call .start() programmatically from a "Take the tour" button.'
+      reason: 'Activation contract.'
+    - rule: 'Distinct from <onboarding-checklist-ui> (persistent setup todo-list, user-paced) and <tooltip-ui> (single hover hint, no orchestration).'
+      reason: 'Sibling-component boundary.'
+    - rule: 'Listen to `tour-finish` for "user completed the tour" analytics; `tour-skip` for "user opted out". Both fire once per session.'
+      reason: 'Event-handling contract.'
+anti_patterns:
+  - wrong: '<tour-ui><div>step 1 content</div><div>step 2 content</div></tour-ui>'
+    why: 'Bare divs have no target / title — tour-ui can''t position the spotlight.'
+    fix: '<tour-ui><tour-step target="#dashboard" title="Dashboard">Tour the dashboard…</tour-step>…</tour-ui>'
+  - wrong: '<tour-step target="dashboard">'
+    why: 'target is a CSS selector — bare "dashboard" matches a <dashboard> element, NOT an id; use the # prefix.'
+    fix: '<tour-step target="#dashboard">'
+examples:
+  - name: basic-tour
+    description: A 3-step product tour anchored to selector-resolved elements.
+    a2ui: |
+      [
+        { "id": "tour", "component": "Tour", "auto-start": true, "children": ["s1", "s2", "s3"] },
+        { "id": "s1", "component": "TourStep", "target": "#dashboard", "title": "Your dashboard", "textContent": "Here's where you'll see your latest activity." },
+        { "id": "s2", "component": "TourStep", "target": "#filters", "title": "Filters", "textContent": "Narrow results by status, owner, or date." },
+        { "id": "s3", "component": "TourStep", "target": "#export", "title": "Export", "textContent": "Download a CSV of the current view." }
+      ]
+keywords:
+  - tour
+  - product-tour
+  - walkthrough
+  - guided-tour
+  - spotlight
+  - coachmark
+  - feature-introduction
+synonyms:
+  tour:
+    - product-tour
+    - guided-tour
+    - walkthrough
+    - feature-intro
+  spotlight:
+    - coachmark
+    - feature-highlight
+related:
+  - tooltip
+  - popover
+  - onboarding-checklist