@skdx/web-components 0.26.0 → 0.28.0

package/dist/tour/Tour.d.ts

@@ -1,294 +1,253 @@
 import { LitElement } from 'lit';
 import { type Align, type Side } from '../internal/positioning.js';
 /**
- * How a step presents itself. `tooltip` and `floating` both anchor to the
- * step's target; `dialog` renders centred even when a target is present, so a
- * step can spotlight an element while explaining it from the middle of the
- * screen. Published as `data-type` on `<skdx-tour-content>` either way.
+ * How a step presents itself: `tooltip`/`floating` anchor to the target,
+ * `dialog` renders centered even with a target.
  */
 export type SkdxTourStepType = 'tooltip' | 'dialog' | 'floating';
-/**
- * One step of a tour. Steps are **data, not markup** — the whole ordered list
- * is set on `<skdx-tour>`'s `steps` property (property-only: an array cannot
- * come from an attribute string) and the parts render whichever one is active.
- */
+/** One step of a tour: data-driven, not markup. */
 export interface SkdxTourStep {
     /**
-     * The element this step points at, as a CSS selector or an element. A step
-     * with no target renders centred and spotlights nothing — that is how a tour
-     * opens and closes.
-     *
-     * The selector is matched against the **document**, not against the tour's
-     * own subtree: a tour's targets are the page it is explaining, which is
-     * almost never inside the `<skdx-tour>` element.
-     * @default undefined — the step is centred, with no spotlight and no anchoring.
+     * Stable name for this step, reported on `step-change` alongside the index.
+     * @default undefined — `step-change` reports the index alone.
+     */
+    id?: string;
+    /**
+     * Element this step points at, as a CSS selector or element.
+     * The selector matches the document, not the tour's subtree.
+     * @default undefined — step is centered with no spotlight or anchor.
      */
     target?: string | Element;
     /**
-     * Short name for the step, announced to screen readers alongside its
-     * position. Purely for the announcement — render the visible heading with
-     * `<skdx-tour-title>`.
-     * @default undefined — only the position ("Step 2 of 5") is announced.
+     * Short name for the step, announced to screen readers.
+     * @default undefined — only position ("Step 2 of 5") is announced.
      */
     title?: string;
     /**
-     * Side of the target this step's content is placed against, fed straight to
-     * the shared popper layer. `start`/`end` are logical and mirror under RTL.
-     * @default undefined — falls back to `<skdx-tour-content>`'s own `side`, which defaults to `bottom`.
+     * Body text displayed in this step's panel content.
+     * @default undefined
+     */
+    description?: string;
+    /**
+     * Side of the target this step's content is placed against.
+     * @default undefined — falls back to content's `side` (defaults to `bottom`).
      */
     placement?: Side;
     /**
-     * Alignment along `placement`.
-     * @default undefined — falls back to `<skdx-tour-content>`'s own `align`, which defaults to `center`.
+     * Alignment position along the placement edge.
+     * @default undefined — falls back to content's `align` (defaults to `center`).
      */
     align?: Align;
     /**
-     * How this step presents itself. `dialog` forces centred content even with a
-     * target set; the other two anchor.
-     * @default undefined — anchored when the step has a target, centred when it does not.
+     * How this step is positioned and displayed.
+     * @default undefined — anchored with target, centered without.
      */
     type?: SkdxTourStepType;
+    /**
+     * Whether this step dims the page behind it.
+     * @default true
+     */
+    backdrop?: boolean;
+}
+/** Detail of the `step-change` event. */
+export interface SkdxTourStepChangeDetail {
+    index: number;
+    id?: string;
 }
-/** The detail of `step-target-missing`. */
+/** Detail of the `step-target-missing` event. */
 export interface SkdxTourStepTargetMissingDetail {
     index: number;
     step: SkdxTourStep;
 }
 /**
- * @internal The event `<skdx-tour>` dispatches on **itself** whenever anything
- * a part renders from has changed. Not bubbling and not composed: the parts
- * subscribe on the root element directly, which is the only thing that works
- * once `<skdx-tour-portal>` has moved half of them out of the root's subtree.
+ * @internal Internal update event dispatched when step data changes.
+ * Not bubbling: parts subscribe on root directly.
  */
 export declare const TOUR_INTERNAL_UPDATE = "skdx-tour-internal-update";
-/** The four numbers a CSS-only spotlight cutout needs. */
-export declare const SPOTLIGHT_PROPERTIES: readonly ["--skdx-tour-x", "--skdx-tour-y", "--skdx-tour-width", "--skdx-tour-height"];
-/**
- * @internal The `<div data-skdx-tour-layer>` `<skdx-tour-portal>` parks the
- * tour's DOM in, carrying a back-reference to the tour that owns it.
- */
+/** Spotlight geometry CSS custom properties. */
+export declare const SPOTLIGHT_PROPERTIES: readonly ["--skdx-tour-x", "--skdx-tour-y", "--skdx-tour-width", "--skdx-tour-height", "--skdx-tour-radius"];
+/** @internal Reset malformed steps warning state. */
+export declare function resetMalformedStepsWarning(): void;
+/** @internal Portal layer element holding a back-reference to its tour root. */
 export interface SkdxTourLayerElement extends HTMLElement {
     tourRoot?: SkdxTour | null;
 }
-/**
- * @internal Finds the `<skdx-tour>` a part belongs to.
- *
- * Every other family here resolves its root with `closest()` alone, and that
- * is still the first thing tried. It is not enough for Tour: `<skdx-tour-portal>`
- * moves Backdrop, Spotlight and Content — and everything inside Content — out
- * to `document.body`, where they have no `<skdx-tour>` ancestor left to find.
- * The portal stamps the owning root onto the layer element it moves them into,
- * and that is the fallback.
- */
+/** @internal Find the `<skdx-tour>` a part belongs to, via closest or layer reference. */
 export declare function findTourRoot(el: Element): SkdxTour | null;
-/**
- * @internal Writes (or clears) the four spotlight custom properties on a part.
- * Shared by Backdrop and Spotlight, which publish exactly the same geometry.
- */
+/** @internal Write spotlight geometry custom properties to an element. */
 export declare function applySpotlightProperties(el: HTMLElement, vars: Record<string, string>): void;
 /**
- * `<skdx-tour>` — the Web Components implementation of the shared Tour contract
- * (see `@skdx/shared`'s `tourContract`): a stepped walkthrough anchored to
- * real elements on the page, with a spotlight cutout, a focus trap, and every
- * step change announced.
- *
- * Renders only a `<slot>` (`display: contents`). It owns the running state,
- * the active step index, the step list, target resolution and the spotlight
- * geometry, and pushes them to `<skdx-tour-trigger>` / `<skdx-tour-portal>` /
- * `<skdx-tour-backdrop>` / `<skdx-tour-spotlight>` / `<skdx-tour-content>` and
- * the navigation triggers through the `skdx-tour-internal-update` event — the
- * same shared-state pattern `<skdx-popover>` uses, since custom elements have
- * no context mechanism.
- *
- * **Steps are data.** Each declares the element it points at (a selector or an
- * element), optionally a `placement`, an `align`, a `title` for the
- * announcement, and a `type`. A step with no target renders centred, which is
- * how a tour usually opens and closes. `steps` is property-only — an array
- * cannot come from an attribute — so set it from script.
+ * `<skdx-tour>` — the Web Components implementation of `@skdx/shared`'s
+ * `tourContract`: a stepped walkthrough anchored to real page elements,
+ * with a spotlight cutout, a focus trap, and every step change announced.
+ * It owns running state, the active step, step list, and spotlight
+ * geometry, pushing them to its parts through an internal update event.
  *
- * A target that has not mounted yet is polled for up to `targetTimeout`; on
- * timeout `step-target-missing` fires and the tour skips forward rather than
- * showing a popup anchored to nothing. A target that is found is scrolled into
- * view before it is measured.
+ * **Steps are data**: each declares its target (a selector or element), a
+ * `placement`, `align`, `title`, and `type`. A step with no target renders
+ * centred, how a tour usually opens and closes.
  *
- * `open`/`step` are plain properties, each with a `default-open` /
- * `default-step` counterpart applied once on connect: the property is the
- * single source of truth and a consumer that wants "controlled" behaviour
- * listens for `open-change`/`step-change` and writes the property back.
- *
- * **Arrow keys are deliberately unbound.** They belong to whatever the step is
- * pointing at — a listbox, a slider, a calendar — and stealing them would
- * break the very control the user has just been told to try.
- *
- * @example
- * ```html
- * <skdx-tour id="tour">
- *   <skdx-tour-trigger>Take the tour</skdx-tour-trigger>
- *   <skdx-tour-portal>
- *     <skdx-tour-backdrop></skdx-tour-backdrop>
- *     <skdx-tour-spotlight></skdx-tour-spotlight>
- *     <skdx-tour-content>
- *       <skdx-tour-title>Your inbox</skdx-tour-title>
- *       <skdx-tour-description>Everything lands here first.</skdx-tour-description>
- *       <skdx-tour-progress-text></skdx-tour-progress-text>
- *       <skdx-tour-prev-trigger>Back</skdx-tour-prev-trigger>
- *       <skdx-tour-next-trigger>Next</skdx-tour-next-trigger>
- *       <skdx-tour-skip-trigger>Skip</skdx-tour-skip-trigger>
- *     </skdx-tour-content>
- *   </skdx-tour-portal>
- * </skdx-tour>
- * <script type="module">
- *   document.getElementById('tour').steps = [
- *     { title: 'Welcome' },
- *     { target: '#inbox', title: 'Your inbox', placement: 'right' },
- *     { title: 'All set' },
- *   ];
- * </script>
- * ```
- *
- * @fires open-change - Fired with the new open state whenever the tour starts or ends, controlled or not.
- * @fires step-change - Fired with the new zero-based index whenever the active step changes, controlled or not. Not fired on completion or skip — those have their own events.
- * @fires complete - Fired when the user advances past the last step. The tour closes either way; this is where the consumer records that the user has seen it.
- * @fires skip - Fired when the tour ends early — the skip trigger, the close trigger, or Escape.
- * @fires step-target-missing - Fired with `{ index, step }` when a step's target never appeared within `target-timeout`. The tour then skips forward rather than rendering an unanchored popup.
+ * `open`/`step` are plain properties — a consumer wanting controlled
+ * behaviour listens for the matching `*-change` event and writes it back.
+ * **Arrow keys are deliberately unbound**: they belong to whatever the step
+ * points at.
+ * @fires open-change - Fired with the new open state whenever the tour starts or ends.
+ * @fires open-change-complete - Fired with the new open state after content animation finishes.
+ * @fires step-change - Fired with `{ index, id }` whenever the active step changes.
+ * @fires complete - Fired when the user advances past the last step.
+ * @fires skip - Fired when the tour ends early (skip trigger, close, or Escape).
+ * @fires step-target-missing - Fired with `{ index, step }` when a step's target does not appear.
  */
 export declare class SkdxTour extends LitElement {
     static styles: import("lit").CSSResult;
     /**
-     * The ordered steps. Required: a tour with no steps has nothing to show, and
-     * the array's length is what "Step 2 of 5" counts against. Property-only —
-     * an attribute string cannot carry an array.
-     * @default [] — nothing to show.
+     * The ordered steps. Settable as JSON attribute or property with element targets.
+     * @default []
      */
     steps: SkdxTourStep[];
     /**
-     * Whether the tour is running. Listen for `open-change` to observe or
-     * override changes.
+     * Whether the tour is currently running; listen for `open-change` to observe or override it.
      * @default false
      */
     open: boolean;
     /**
-     * Whether the tour is running on mount, for uncontrolled usage. Applied once,
-     * on connect, and only if `open` wasn't already set.
-     * @default false — the tour waits for a trigger, so a first-visit tour is started deliberately rather than on every render.
+     * Whether the tour is running on mount, for uncontrolled usage.
+     * @default false
      */
     defaultOpen: boolean;
     /**
-     * Zero-based index of the active step. Listen for `step-change` to observe
-     * or override changes.
+     * Zero-based index of the active step.
      * @default 0
      */
     step: number;
     /**
-     * Index the tour starts on, for uncontrolled usage — useful for resuming a
-     * tour the user abandoned. Applied once, on connect, and only if `step`
-     * wasn't already set.
+     * Index the tour starts on, for uncontrolled usage.
      * @default 0
      */
     defaultStep: number;
     /**
-     * Whether pressing Escape ends the tour the same way skipping does.
-     *
-     * Uses the `optOutBoolean` converter rather than Lit's stock `Boolean`, so
-     * `close-on-escape="false"` actually switches it off instead of reading as
-     * attribute presence.
-     * @default true — Escape must always get a user out of a modal layer; set it `false` only when the tour genuinely cannot be abandoned, and then provide another way out.
+     * Whether pressing Escape ends the tour.
+     * @default true
      */
     closeOnEscape: boolean;
+    /**
+     * Whether the page behind the tour is marked inert and `aria-modal="true"`.
+     * @default false
+     */
+    preventInteraction: boolean;
     /**
      * Whether a pointer-down outside the content skips the tour.
-     * @default false — during a tour an outside click is almost always a misclick on the very UI being explained, and losing the tour to it is worse than ignoring it.
+     * @default false
      */
     closeOnInteractOutside: boolean;
     /**
-     * Pixels of breathing room added around the target on every side when the
-     * spotlight geometry is published.
-     * @default 8 — the cutout clears the target's own focus ring instead of clipping it.
+     * Pixels of breathing room added around the target.
+     * @default 8
      */
     spotlightPadding: number;
     /**
-     * How long, in milliseconds, to keep polling for a step's target before
-     * giving up on it. Covers targets that mount late — a lazy route, a panel
-     * that opens on the previous step's action.
-     * @default 2000 — long enough for a lazy chunk to land, short enough that a genuinely absent target does not strand the tour.
+     * Corner radius of the spotlight cutout, in pixels.
+     * @default 0
+     */
+    spotlightRadius: number;
+    /**
+     * How to scroll the target into view before positioning.
+     * Respects `prefers-reduced-motion: reduce`.
+     * Property is `scrollIntoViewOption` (not `scrollIntoView`,
+     * which is a native HTMLElement method).
+     * @default `{ block: 'center', inline: 'center' }`
+     */
+    scrollIntoViewOption?: boolean | ScrollIntoViewOptions;
+    /**
+     * How long in milliseconds to poll for a step's target.
+     * @default 2000
      */
     targetTimeout: number;
     /**
-     * Builds the string announced to screen readers on every step change.
-     * Override it to translate, or to include more of the step than its title.
-     * Property-only: a function cannot come from an attribute.
-     * @default undefined — announces the step's `title` (when set) followed by "Step {n} of {total}", in English.
+     * Whether arrow keys advance/step back the tour while content has focus.
+     * Never interrupts editable fields inside the panel.
+     * @default false
+     */
+    keyboardNavigation: boolean;
+    /**
+     * Builds the announcement string for screen readers on every step change.
+     * Property-only.
+     * @default announces step title (if set) and position.
      */
     getAnnouncement?: (step: SkdxTourStep, index: number, total: number) => string;
-    readonly contentId: string;
-    readonly titleId: string;
-    readonly descriptionId: string;
-    /** @internal Set by `<skdx-tour-trigger>` once its native button mounts. */
-    triggerEl: HTMLElement | null;
-    /** @internal The active step's resolved target element, or `null` for a centred step. */
-    target: HTMLElement | null;
     /**
-     * @internal The active target's padded, viewport-clamped rect as the four
-     * `--skdx-tour-*` custom properties, ready to be written onto Backdrop and
-     * Spotlight. Empty while there is no target.
+     * Whether the derived anatomy includes a progress text part.
+     * @default true
      */
+    showProgress: boolean;
+    /**
+     * Whether the derived anatomy includes a skip trigger part.
+     * @default true
+     */
+    showSkip: boolean;
+    /**
+     * Whether the derived anatomy includes a spotlight cutout.
+     * @default true
+     */
+    spotlight: boolean;
+    contentId: string;
+    titleId: string;
+    descriptionId: string;
+    /** @internal Trigger element set on connect. */
+    triggerEl: HTMLElement | null;
+    /** @internal Active step's resolved target element or null. */
+    target: HTMLElement | null;
+    /** @internal Spotlight geometry as custom properties. */
     spotlightVars: Record<string, string>;
     private hasUpdatedOnce;
     private pollTimer?;
     private measuring;
     private lastResolve?;
-    /** The active step, or `undefined` when `steps` is empty or `step` is out of range. */
+    /** The active step or undefined. */
     get activeStep(): SkdxTourStep | undefined;
-    /** How many steps the tour has — what "Step 2 of 5" counts against. */
+    /** Number of steps in the tour. */
     get total(): number;
-    /**
-     * @internal True when the active step's content is positioned against a
-     * resolved target rather than centred. A `type: 'dialog'` step still
-     * spotlights its target — it just explains it from the middle of the screen.
-     */
+    /** @internal True when content is positioned against target, not centered. */
     get anchored(): boolean;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    private teardownOpenChangeComplete?;
+    private _anatomyBuilt;
+    /** Build canonical anatomy into light DOM if no consumer parts exist. */
+    private readonly _fillAnatomy;
+    /** Rebuild anatomy when structure-altering props change. */
+    private readonly _rebuildAnatomy;
     protected updated(changed: Map<string, unknown>): void;
-    /** @internal Sets `open`; the `open-change` event follows from `updated()`. */
+    /** @internal Set the open state. */
     setOpen(next: boolean): void;
-    /** @internal Moves to `index`, clamped to the step list. */
+    /** @internal Move to clamped step index. */
     goTo(index: number): void;
-    /** @internal Advances a step, or completes the tour when already on the last one. */
+    /** @internal Advance a step or complete the tour. */
     next(): void;
-    /** @internal Steps back. A no-op on the first step, which has nowhere to go. */
+    /** Skip forward on missing target; on last step, skip tour instead. */
+    private abandon;
+    /** @internal Step back; no-op on first step. */
     prev(): void;
-    /**
-     * @internal Ends the tour early — the skip trigger, the close trigger, or
-     * Escape. Always dispatches: skipping is an action, not a state change, and
-     * a consumer that hears "skipped" twice is better off than one that hears it
-     * never because the tour happened to be closed already.
-     */
+    /** @internal End the tour early with skip event. */
     skip(): void;
-    /** @internal Ends the tour by advancing past the last step. Always dispatches, for the same reason as {@link skip}. */
+    /** @internal End the tour by advancing past the last step. */
     complete(): void;
-    /** @internal */
+    /** @internal Focus the trigger element. */
     focusTrigger(): void;
-    /** @internal Tells every part to re-read this element. */
+    /** @internal Notify all parts to re-read state. */
     notifyParts(): void;
     /**
-     * Resolves the active step's target — polling for one that has not mounted
-     * yet, and skipping the step outright once `targetTimeout` is up. An
-     * unanchored popup pointing at nothing is worse than no step at all.
+     * Resolve active step's target, poll if missing, abandon on timeout.
      */
     private resolveActiveTarget;
     private settleTarget;
     private setTarget;
     private startMeasuring;
     private stopMeasuring;
-    /**
-     * Four numbers is everything a cutout needs, so the hole over the target is
-     * drawable in CSS alone. Clamped to the viewport: a target scrolled halfway
-     * off-screen would otherwise publish negative coordinates and an over-long
-     * box, and every consumer would have to re-clamp them by hand.
-     */
+    /** Calculate target geometry clamped to viewport. */
     private readonly measure;
     private stopPolling;
+    /** Announce the active step to screen readers. */
     private announceStep;
     render(): import("lit").TemplateResult<1>;
 }

package/dist/tour/Tour.js

@@ -1,5 +1,5 @@
-var g=Object.defineProperty;var f=Object.getOwnPropertyDescriptor;var o=(s,n,t,e)=>{for(var i=e>1?void 0:e?f(n,t):n,l=s.length-1,p;l>=0;l--)(p=s[l])&&(i=(e?p(n,t,i):p(i))||i);return e&&i&&g(n,t,i),i};import{css as v,html as b,LitElement as T}from"lit";import{property as a}from"lit/decorators.js";import{customElement as x}from"../internal/define.js";import{nextId as d}from"../internal/ids.js";import{optOutBoolean as y}from"../internal/positioning.js";import{announce as E}from"../utils/live-announcer.js";var S="skdx-tour-internal-update",k=50,w=["--skdx-tour-x","--skdx-tour-y","--skdx-tour-width","--skdx-tour-height"];function u(s,n,t){return Math.min(Math.max(s,n),t)}function M(s,n,t){return[s.title,`Step ${n+1} of ${t}`].filter(Boolean).join(", ")}function m(s){return s?typeof s=="string"?document.querySelector(s):s:null}function C(s){let n=s.closest("skdx-tour");return n||(s.closest("[data-skdx-tour-layer]")?.tourRoot??null)}function N(s,n){for(let t of w){let e=n[t];e===void 0?s.style.removeProperty(t):s.style.setProperty(t,e)}}var r=class extends T{constructor(){super(...arguments);this.steps=[];this.open=!1;this.defaultOpen=!1;this.step=0;this.defaultStep=0;this.closeOnEscape=!0;this.closeOnInteractOutside=!1;this.spotlightPadding=8;this.targetTimeout=2e3;this.contentId=d("skdx-tour-content");this.titleId=d("skdx-tour-title");this.descriptionId=d("skdx-tour-description");this.triggerEl=null;this.target=null;this.spotlightVars={};this.hasUpdatedOnce=!1;this.measuring=!1;this.measure=()=>{let t=this.target?.getBoundingClientRect();if(!t){this.spotlightVars={},this.notifyParts();return}let e=window.innerWidth,i=window.innerHeight,l=u(t.left-this.spotlightPadding,0,e),p=u(t.top-this.spotlightPadding,0,i);this.spotlightVars={"--skdx-tour-x":`${l}px`,"--skdx-tour-y":`${p}px`,"--skdx-tour-width":`${u(t.width+this.spotlightPadding*2,0,e-l)}px`,"--skdx-tour-height":`${u(t.height+this.spotlightPadding*2,0,i-p)}px`},this.notifyParts()}}get activeStep(){return this.steps[this.step]}get total(){return this.steps.length}get anchored(){return this.target!==null&&this.activeStep?.type!=="dialog"}connectedCallback(){super.connectedCallback(),this.defaultOpen&&!this.hasAttribute("open")&&(this.open=!0),this.hasAttribute("step")||(this.step=this.defaultStep)}disconnectedCallback(){this.stopPolling(),this.stopMeasuring(),this.lastResolve=void 0,super.disconnectedCallback()}updated(t){let e=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,t.has("open")&&!e&&this.dispatchEvent(new CustomEvent("open-change",{detail:this.open,bubbles:!0,composed:!0})),t.has("step")&&!e&&this.dispatchEvent(new CustomEvent("step-change",{detail:this.step,bubbles:!0,composed:!0})),(t.has("open")||t.has("step")||t.has("steps")||t.has("targetTimeout"))&&(this.resolveActiveTarget(),this.announceStep()),t.size>0&&this.notifyParts()}setOpen(t){this.open=t}goTo(t){this.step=u(t,0,Math.max(this.total-1,0))}next(){this.step>=this.total-1?this.complete():this.goTo(this.step+1)}prev(){this.goTo(this.step-1)}skip(){this.setOpen(!1),this.dispatchEvent(new CustomEvent("skip",{bubbles:!0,composed:!0}))}complete(){this.setOpen(!1),this.dispatchEvent(new CustomEvent("complete",{bubbles:!0,composed:!0}))}focusTrigger(){this.triggerEl?.focus()}notifyParts(){this.dispatchEvent(new CustomEvent(S))}resolveActiveTarget(){let t=this.activeStep?.target,e={open:this.open,step:this.step,spec:t,timeout:this.targetTimeout},i=this.lastResolve;if(i&&i.open===e.open&&i.step===e.step&&i.spec===e.spec&&i.timeout===e.timeout)return;if(this.lastResolve=e,this.stopPolling(),!this.open||!t){this.setTarget(null);return}let l=m(t);if(l){this.settleTarget(l);return}this.setTarget(null);let p=Date.now(),h=this.step;this.pollTimer=setInterval(()=>{let c=m(t);if(c){this.stopPolling(),this.settleTarget(c);return}Date.now()-p<this.targetTimeout||(this.stopPolling(),this.dispatchEvent(new CustomEvent("step-target-missing",{detail:{index:h,step:this.steps[h]},bubbles:!0,composed:!0})),this.next())},k)}settleTarget(t){t.scrollIntoView?.({block:"center",inline:"center"}),this.setTarget(t)}setTarget(t){this.target!==t&&(this.target=t,t?this.startMeasuring():(this.stopMeasuring(),this.spotlightVars={}),this.notifyParts())}startMeasuring(){this.measure(),!this.measuring&&(this.measuring=!0,window.addEventListener("scroll",this.measure,!0),window.addEventListener("resize",this.measure))}stopMeasuring(){this.measuring&&(this.measuring=!1,window.removeEventListener("scroll",this.measure,!0),window.removeEventListener("resize",this.measure))}stopPolling(){this.pollTimer!==void 0&&(clearInterval(this.pollTimer),this.pollTimer=void 0)}announceStep(){if(!this.open)return;let t=this.activeStep;t&&E((this.getAnnouncement??M)(t,this.step,this.total))}render(){return b`<slot></slot>`}};r.styles=v`
+var v=Object.defineProperty;var b=Object.getOwnPropertyDescriptor;var r=(e,i,t,s)=>{for(var n=s>1?void 0:s?b(i,t):i,l=e.length-1,p;l>=0;l--)(p=e[l])&&(n=(s?p(i,t,n):p(n))||n);return s&&n&&v(i,t,n),n};import{css as y,html as T,LitElement as x}from"lit";import{property as a}from"lit/decorators.js";import{hasAuthoredParts as w}from"../internal/authored.js";import{customElement as S}from"../internal/define.js";import{nextId as m}from"../internal/ids.js";import{notifyOpenChangeComplete as E}from"../internal/open-change-complete.js";import{optOutBoolean as k}from"../internal/positioning.js";import{isDevMode as O}from"../utils/is-dev-mode.js";import{announce as A}from"../utils/live-announcer.js";import{fillTourAnatomy as M,refreshTourAnatomyText as P,TOUR_ANATOMY_GENERATED as C}from"./TourAnatomy.js";var I="skdx-tour-internal-update",L=50,R=["--skdx-tour-x","--skdx-tour-y","--skdx-tour-width","--skdx-tour-height","--skdx-tour-radius"];function _(e,i){if(i===!1)return;let t=i===!0||i===void 0?{block:"center",inline:"center"}:i,s=window.matchMedia?.("(prefers-reduced-motion: reduce)").matches??!1;e.scrollIntoView?.(s?{...t,behavior:"auto"}:t)}function c(e,i,t){return Math.min(Math.max(e,i),t)}function B(e,i,t){return[e.title,`Step ${i+1} of ${t}`].filter(Boolean).join(", ")}function g(e){return e?typeof e=="string"?document.querySelector(e):e:null}var f=!1;function K(){f=!1}function N(e){f||(f=!0,O()&&console.warn(`[skdx] <skdx-tour> steps attribute is not valid JSON and was ignored: ${e}`))}function H(e){if(!e||typeof e!="object")return null;let{target:i,title:t,description:s,placement:n,align:l,type:p,id:d,backdrop:h}=e,u={};return typeof i=="string"&&(u.target=i),typeof t=="string"&&(u.title=t),typeof s=="string"&&(u.description=s),typeof n=="string"&&(u.placement=n),typeof l=="string"&&(u.align=l),typeof p=="string"&&(u.type=p),typeof d=="string"&&(u.id=d),typeof h=="boolean"&&(u.backdrop=h),u}var V={fromAttribute(e){if(!e)return[];try{let i=JSON.parse(e);if(!Array.isArray(i))throw new Error("steps attribute must be a JSON array");return i.map(H).filter(t=>t!==null)}catch{return N(e),[]}}};function Q(e){let i=e.closest("skdx-tour");return i||(e.closest("[data-skdx-tour-layer]")?.tourRoot??null)}function X(e,i){for(let t of R){let s=i[t];s===void 0?e.style.removeProperty(t):e.style.setProperty(t,s)}}var o=class extends x{constructor(){super(...arguments);this.steps=[];this.open=!1;this.defaultOpen=!1;this.step=0;this.defaultStep=0;this.closeOnEscape=!0;this.preventInteraction=!1;this.closeOnInteractOutside=!1;this.spotlightPadding=8;this.spotlightRadius=0;this.targetTimeout=2e3;this.keyboardNavigation=!1;this.showProgress=!0;this.showSkip=!0;this.spotlight=!0;this.contentId=m("skdx-tour-content");this.titleId=m("skdx-tour-title");this.descriptionId=m("skdx-tour-description");this.triggerEl=null;this.target=null;this.spotlightVars={};this.hasUpdatedOnce=!1;this.measuring=!1;this._anatomyBuilt=!1;this._fillAnatomy=()=>{if(w(this,C)){this._anatomyBuilt=!1;return}this._anatomyBuilt||(this._anatomyBuilt=!0,M(this))};this._rebuildAnatomy=()=>{this._anatomyBuilt=!1,this._fillAnatomy()};this.measure=()=>{let t=this.target?.getBoundingClientRect();if(!t){this.spotlightVars={},this.notifyParts();return}let s=window.innerWidth,n=window.innerHeight,l=c(t.left-this.spotlightPadding,0,s),p=c(t.top-this.spotlightPadding,0,n);this.spotlightVars={"--skdx-tour-x":`${l}px`,"--skdx-tour-y":`${p}px`,"--skdx-tour-width":`${c(t.width+this.spotlightPadding*2,0,s-l)}px`,"--skdx-tour-height":`${c(t.height+this.spotlightPadding*2,0,n-p)}px`,"--skdx-tour-radius":`${this.spotlightRadius}px`},this.notifyParts()}}get activeStep(){return this.steps[this.step]}get total(){return this.steps.length}get anchored(){return this.target!==null&&this.activeStep?.type!=="dialog"}connectedCallback(){super.connectedCallback(),this.defaultOpen&&!this.hasAttribute("open")&&(this.open=!0),this.hasAttribute("step")||(this.step=this.defaultStep),queueMicrotask(this._fillAnatomy)}disconnectedCallback(){this.stopPolling(),this.stopMeasuring(),this.lastResolve=void 0,this.teardownOpenChangeComplete?.(),super.disconnectedCallback()}updated(t){let s=!this.hasUpdatedOnce;this.hasUpdatedOnce=!0,t.has("open")&&!s&&this.dispatchEvent(new CustomEvent("open-change",{detail:this.open,bubbles:!0,composed:!0})),t.has("step")&&!s&&this.dispatchEvent(new CustomEvent("step-change",{detail:{index:this.step,id:this.activeStep?.id},bubbles:!0,composed:!0})),t.has("open")&&!s&&(this.teardownOpenChangeComplete?.(),this.teardownOpenChangeComplete=E(()=>document.getElementById(this.contentId),this.open,n=>this.dispatchEvent(new CustomEvent("open-change-complete",{detail:n,bubbles:!0,composed:!0})))),(t.has("open")||t.has("step")||t.has("steps")||t.has("targetTimeout"))&&(this.resolveActiveTarget(),this.announceStep()),t.has("showProgress")||t.has("showSkip")||t.has("spotlight")?this._rebuildAnatomy():this._fillAnatomy(),(t.has("steps")||t.has("step"))&&P(this),t.size>0&&this.notifyParts()}setOpen(t){this.open=t}goTo(t){this.step=c(t,0,Math.max(this.total-1,0))}next(){this.step>=this.total-1?this.complete():this.goTo(this.step+1)}abandon(){this.step>=this.total-1?this.skip():this.goTo(this.step+1)}prev(){this.goTo(this.step-1)}skip(){this.setOpen(!1),this.dispatchEvent(new CustomEvent("skip",{bubbles:!0,composed:!0}))}complete(){this.setOpen(!1),this.dispatchEvent(new CustomEvent("complete",{bubbles:!0,composed:!0}))}focusTrigger(){this.triggerEl?.focus()}notifyParts(){this.dispatchEvent(new CustomEvent(I))}resolveActiveTarget(){let t=this.activeStep?.target,s={open:this.open,step:this.step,spec:t,timeout:this.targetTimeout},n=this.lastResolve;if(n&&n.open===s.open&&n.step===s.step&&n.spec===s.spec&&n.timeout===s.timeout)return;if(this.lastResolve=s,this.stopPolling(),!this.open||!t){this.setTarget(null);return}let l=g(t);if(l){this.settleTarget(l);return}this.setTarget(null);let p=Date.now(),d=this.step;this.pollTimer=setInterval(()=>{let h=g(t);if(h){this.stopPolling(),this.settleTarget(h);return}Date.now()-p<this.targetTimeout||(this.stopPolling(),this.dispatchEvent(new CustomEvent("step-target-missing",{detail:{index:d,step:this.steps[d]},bubbles:!0,composed:!0})),this.abandon())},L)}settleTarget(t){_(t,this.scrollIntoViewOption),this.setTarget(t)}setTarget(t){this.target!==t&&(this.target=t,t?this.startMeasuring():(this.stopMeasuring(),this.spotlightVars={}),this.notifyParts())}startMeasuring(){this.measure(),!this.measuring&&(this.measuring=!0,window.addEventListener("scroll",this.measure,!0),window.addEventListener("resize",this.measure))}stopMeasuring(){this.measuring&&(this.measuring=!1,window.removeEventListener("scroll",this.measure,!0),window.removeEventListener("resize",this.measure))}stopPolling(){this.pollTimer!==void 0&&(clearInterval(this.pollTimer),this.pollTimer=void 0)}announceStep(){if(!this.open)return;let t=this.activeStep;t&&A((this.getAnnouncement??B)(t,this.step,this.total))}render(){return T`<slot @slotchange=${this._fillAnatomy}></slot>`}};o.styles=y`
     :host {
       display: contents;
     }
-  `,o([a({attribute:!1})],r.prototype,"steps",2),o([a({type:Boolean,reflect:!0})],r.prototype,"open",2),o([a({type:Boolean,attribute:"default-open"})],r.prototype,"defaultOpen",2),o([a({type:Number,reflect:!0})],r.prototype,"step",2),o([a({type:Number,attribute:"default-step"})],r.prototype,"defaultStep",2),o([a({converter:y,attribute:"close-on-escape"})],r.prototype,"closeOnEscape",2),o([a({type:Boolean,attribute:"close-on-interact-outside"})],r.prototype,"closeOnInteractOutside",2),o([a({type:Number,attribute:"spotlight-padding"})],r.prototype,"spotlightPadding",2),o([a({type:Number,attribute:"target-timeout"})],r.prototype,"targetTimeout",2),o([a({attribute:!1})],r.prototype,"getAnnouncement",2),r=o([x("skdx-tour")],r);export{w as SPOTLIGHT_PROPERTIES,r as SkdxTour,S as TOUR_INTERNAL_UPDATE,N as applySpotlightProperties,C as findTourRoot};
+  `,r([a({converter:V})],o.prototype,"steps",2),r([a({type:Boolean,reflect:!0})],o.prototype,"open",2),r([a({type:Boolean,attribute:"default-open"})],o.prototype,"defaultOpen",2),r([a({type:Number,reflect:!0})],o.prototype,"step",2),r([a({type:Number,attribute:"default-step"})],o.prototype,"defaultStep",2),r([a({converter:k,attribute:"close-on-escape"})],o.prototype,"closeOnEscape",2),r([a({type:Boolean,attribute:"prevent-interaction"})],o.prototype,"preventInteraction",2),r([a({type:Boolean,attribute:"close-on-interact-outside"})],o.prototype,"closeOnInteractOutside",2),r([a({type:Number,attribute:"spotlight-padding"})],o.prototype,"spotlightPadding",2),r([a({type:Number,attribute:"spotlight-radius"})],o.prototype,"spotlightRadius",2),r([a({type:Object,attribute:"scroll-into-view"})],o.prototype,"scrollIntoViewOption",2),r([a({type:Number,attribute:"target-timeout"})],o.prototype,"targetTimeout",2),r([a({type:Boolean,attribute:"keyboard-navigation"})],o.prototype,"keyboardNavigation",2),r([a({attribute:!1})],o.prototype,"getAnnouncement",2),r([a({type:Boolean,attribute:"show-progress"})],o.prototype,"showProgress",2),r([a({type:Boolean,attribute:"show-skip"})],o.prototype,"showSkip",2),r([a({type:Boolean,reflect:!0})],o.prototype,"spotlight",2),o=r([S("skdx-tour")],o);export{R as SPOTLIGHT_PROPERTIES,o as SkdxTour,I as TOUR_INTERNAL_UPDATE,X as applySpotlightProperties,Q as findTourRoot,K as resetMalformedStepsWarning};

package/dist/tour/TourActions.cjs

@@ -0,0 +1,5 @@
+"use strict";var i=Object.defineProperty;var n=Object.getOwnPropertyDescriptor;var v=Object.getOwnPropertyNames;var f=Object.prototype.hasOwnProperty;var E=(r,t)=>{for(var s in t)i(r,s,{get:t[s],enumerable:!0})},b=(r,t,s,a)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of v(t))!f.call(r,e)&&e!==s&&i(r,e,{get:()=>t[e],enumerable:!(a=n(t,e))||a.enumerable});return r};var g=r=>b(i({},"__esModule",{value:!0}),r),d=(r,t,s,a)=>{for(var e=a>1?void 0:a?n(t,s):t,m=r.length-1,c;m>=0;m--)(c=r[m])&&(e=(a?c(t,s,e):c(e))||e);return a&&e&&i(t,s,e),e};var h={};E(h,{SkdxTourActions:()=>o});module.exports=g(h);var l=require("lit"),p=require("../internal/define.cjs");var o=class extends l.LitElement{render(){return l.html`<div part="actions"><slot></slot></div>`}};o.styles=l.css`
+    :host {
+      display: block;
+    }
+  `,o=d([(0,p.customElement)("skdx-tour-actions","tour","actions")],o);0&&(module.exports={SkdxTourActions});

package/dist/tour/TourActions.d.cts

@@ -0,0 +1,26 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-tour-actions>` — the row for tour navigation triggers. Purely
+ * presentational: no `role`, no generated label. The buttons inside name themselves.
+ *
+ * @csspart actions - The row element inside the shadow root.
+ *
+ * @example
+ * ```html
+ * <skdx-tour-content>
+ *   <skdx-tour-actions>
+ *     <skdx-tour-skip-trigger>Skip</skdx-tour-skip-trigger>
+ *     <skdx-tour-next-trigger>Next</skdx-tour-next-trigger>
+ *   </skdx-tour-actions>
+ * </skdx-tour-content>
+ * ```
+ */
+export declare class SkdxTourActions extends LitElement {
+    static styles: import("lit").CSSResult;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tour-actions': SkdxTourActions;
+    }
+}

package/dist/tour/TourActions.d.ts

@@ -0,0 +1,26 @@
+import { LitElement } from 'lit';
+/**
+ * `<skdx-tour-actions>` — the row for tour navigation triggers. Purely
+ * presentational: no `role`, no generated label. The buttons inside name themselves.
+ *
+ * @csspart actions - The row element inside the shadow root.
+ *
+ * @example
+ * ```html
+ * <skdx-tour-content>
+ *   <skdx-tour-actions>
+ *     <skdx-tour-skip-trigger>Skip</skdx-tour-skip-trigger>
+ *     <skdx-tour-next-trigger>Next</skdx-tour-next-trigger>
+ *   </skdx-tour-actions>
+ * </skdx-tour-content>
+ * ```
+ */
+export declare class SkdxTourActions extends LitElement {
+    static styles: import("lit").CSSResult;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tour-actions': SkdxTourActions;
+    }
+}

package/dist/tour/TourActions.js

@@ -0,0 +1,5 @@
+var c=Object.defineProperty;var n=Object.getOwnPropertyDescriptor;var m=(a,r,o,s)=>{for(var t=s>1?void 0:s?n(r,o):r,l=a.length-1,i;l>=0;l--)(i=a[l])&&(t=(s?i(r,o,t):i(t))||t);return s&&t&&c(r,o,t),t};import{css as d,html as p,LitElement as v}from"lit";import{customElement as f}from"../internal/define.js";var e=class extends v{render(){return p`<div part="actions"><slot></slot></div>`}};e.styles=d`
+    :host {
+      display: block;
+    }
+  `,e=m([f("skdx-tour-actions","tour","actions")],e);export{e as SkdxTourActions};

package/dist/tour/TourAnatomy.cjs

@@ -0,0 +1 @@
+"use strict";var d=Object.defineProperty;var k=Object.getOwnPropertyDescriptor;var E=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var f=(t,e)=>{for(var n in e)d(t,n,{get:e[n],enumerable:!0})},T=(t,e,n,i)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of E(e))!g.call(t,o)&&o!==n&&d(t,o,{get:()=>e[o],enumerable:!(i=k(e,o))||i.enumerable});return t};var h=t=>T(d({},"__esModule",{value:!0}),t);var A={};f(A,{TOUR_ANATOMY_GENERATED:()=>s,fillTourAnatomy:()=>C,refreshTourAnatomyText:()=>x});module.exports=h(A);var l=require("../internal/authored.cjs"),v=require("./TourPortal.cjs"),y=require("./TourBackdrop.cjs"),b=require("./TourSpotlight.cjs"),I=require("./TourContent.cjs"),B=require("./TourTitle.cjs"),N=require("./TourDescription.cjs"),w=require("./TourProgressText.cjs"),G=require("./TourActions.cjs"),O=require("./TourNextTrigger.cjs"),R=require("./TourPrevTrigger.cjs"),_=require("./TourSkipTrigger.cjs"),D=require("./TourCloseTrigger.cjs"),s="data-skdx-tour-generated";function C(t){let e=[],n=document.createElement("skdx-tour-content"),i=document.createElement("skdx-tour-title");n.append(i);let o=document.createElement("skdx-tour-description");n.append(o),t.showProgress&&n.append(document.createElement("skdx-tour-progress-text"));let p=document.createElement("skdx-tour-actions"),m=document.createElement("skdx-tour-prev-trigger");m.textContent="Back";let a=document.createElement("skdx-tour-next-trigger");if(a.textContent="Next",p.append(m,a),t.showSkip){let u=document.createElement("skdx-tour-skip-trigger");u.textContent="Skip tour",p.append(u)}let c=document.createElement("skdx-tour-close-trigger");c.setAttribute("aria-label","Close tour"),c.textContent="\u2715",p.append(c),n.append(p);let r=document.createElement("skdx-tour-portal");r.setAttribute(s,""),r.append(document.createElement("skdx-tour-backdrop")),t.spotlight&&r.append(document.createElement("skdx-tour-spotlight")),r.append(n),e.push(r),t.replaceChildren(...e),x(t)}function x(t){if(!(0,l.hasGeneratedContent)(t,s))return;let e=document.getElementById(t.titleId);e&&(e.textContent=t.activeStep?.title??"");let n=document.getElementById(t.descriptionId);n&&(n.textContent=t.activeStep?.description??"")}0&&(module.exports={TOUR_ANATOMY_GENERATED,fillTourAnatomy,refreshTourAnatomyText});

package/dist/tour/TourAnatomy.d.cts

@@ -0,0 +1,27 @@
+import type { SkdxTour } from './Tour.cjs';
+import './TourPortal.cjs';
+import './TourBackdrop.cjs';
+import './TourSpotlight.cjs';
+import './TourContent.cjs';
+import './TourTitle.cjs';
+import './TourDescription.cjs';
+import './TourProgressText.cjs';
+import './TourActions.cjs';
+import './TourNextTrigger.cjs';
+import './TourPrevTrigger.cjs';
+import './TourSkipTrigger.cjs';
+import './TourCloseTrigger.cjs';
+/** @internal Marks a direct child of `<skdx-tour>` this module generated. */
+export declare const TOUR_ANATOMY_GENERATED = "data-skdx-tour-generated";
+/**
+ * Build the canonical anatomy: Portal with Backdrop, Spotlight, and Content.
+ * No Trigger (drive `open` externally). CloseTrigger always derives even when
+ * Skip and Escape are disabled, to keep a dismiss affordance.
+ * @internal
+ */
+export declare function fillTourAnatomy(root: SkdxTour): void;
+/**
+ * Update the Title and Description for the active step.
+ * @internal
+ */
+export declare function refreshTourAnatomyText(root: SkdxTour): void;

package/dist/tour/TourAnatomy.d.ts

@@ -0,0 +1,27 @@
+import type { SkdxTour } from './Tour.js';
+import './TourPortal.js';
+import './TourBackdrop.js';
+import './TourSpotlight.js';
+import './TourContent.js';
+import './TourTitle.js';
+import './TourDescription.js';
+import './TourProgressText.js';
+import './TourActions.js';
+import './TourNextTrigger.js';
+import './TourPrevTrigger.js';
+import './TourSkipTrigger.js';
+import './TourCloseTrigger.js';
+/** @internal Marks a direct child of `<skdx-tour>` this module generated. */
+export declare const TOUR_ANATOMY_GENERATED = "data-skdx-tour-generated";
+/**
+ * Build the canonical anatomy: Portal with Backdrop, Spotlight, and Content.
+ * No Trigger (drive `open` externally). CloseTrigger always derives even when
+ * Skip and Escape are disabled, to keep a dismiss affordance.
+ * @internal
+ */
+export declare function fillTourAnatomy(root: SkdxTour): void;
+/**
+ * Update the Title and Description for the active step.
+ * @internal
+ */
+export declare function refreshTourAnatomyText(root: SkdxTour): void;

package/dist/tour/TourAnatomy.js

@@ -0,0 +1 @@
+import{hasGeneratedContent as u}from"../internal/authored.js";import"./TourPortal.js";import"./TourBackdrop.js";import"./TourSpotlight.js";import"./TourContent.js";import"./TourTitle.js";import"./TourDescription.js";import"./TourProgressText.js";import"./TourActions.js";import"./TourNextTrigger.js";import"./TourPrevTrigger.js";import"./TourSkipTrigger.js";import"./TourCloseTrigger.js";var s="data-skdx-tour-generated";function I(t){let n=[],e=document.createElement("skdx-tour-content"),m=document.createElement("skdx-tour-title");e.append(m);let a=document.createElement("skdx-tour-description");e.append(a),t.showProgress&&e.append(document.createElement("skdx-tour-progress-text"));let r=document.createElement("skdx-tour-actions"),p=document.createElement("skdx-tour-prev-trigger");p.textContent="Back";let c=document.createElement("skdx-tour-next-trigger");if(c.textContent="Next",r.append(p,c),t.showSkip){let d=document.createElement("skdx-tour-skip-trigger");d.textContent="Skip tour",r.append(d)}let i=document.createElement("skdx-tour-close-trigger");i.setAttribute("aria-label","Close tour"),i.textContent="\u2715",r.append(i),e.append(r);let o=document.createElement("skdx-tour-portal");o.setAttribute(s,""),o.append(document.createElement("skdx-tour-backdrop")),t.spotlight&&o.append(document.createElement("skdx-tour-spotlight")),o.append(e),n.push(o),t.replaceChildren(...n),l(t)}function l(t){if(!u(t,s))return;let n=document.getElementById(t.titleId);n&&(n.textContent=t.activeStep?.title??"");let e=document.getElementById(t.descriptionId);e&&(e.textContent=t.activeStep?.description??"")}export{s as TOUR_ANATOMY_GENERATED,I as fillTourAnatomy,l as refreshTourAnatomyText};