@skdx/web-components 0.27.0 → 0.29.0

package/dist/tour/Tour.d.ts

@@ -1,296 +1,246 @@
-import { LitElement } from 'lit';
+import { LitElement, type TemplateResult } 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 Reset malformed steps warning state. */
+export declare function resetMalformedStepsWarning(): void;
 /**
- * @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.
- */
-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.
- */
-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.
- */
-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.
- */
-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.
+ * `<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.
  *
- * 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.
+ * **Stepper 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.
  *
- * **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.
- *
- * 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.
- *
- * `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 move between steps** while `keyboardNavigation` is set and the
+ * panel has focus, mirrored under RTL; everywhere else 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;
+    /** @internal Generated title id, published as aria-labelledby on the step. */
+    titleId: string;
+    /** @internal Generated description id, published as aria-describedby on the step. */
+    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 scrollRaf;
     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()`. */
+    private announceStateChanges;
+    /** @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.
-     */
+    private readonly onScroll;
+    /** 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>;
+    render(): TemplateResult;
 }
 declare global {
     interface HTMLElementTagNameMap {

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

package/dist/tour/TourActions.cjs

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

package/dist/tour/TourActions.d.cts

@@ -0,0 +1,26 @@
+import { LitElement, type TemplateResult } 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(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tour-actions': SkdxTourActions;
+    }
+}

package/dist/tour/TourActions.d.ts

@@ -0,0 +1,26 @@
+import { LitElement, type TemplateResult } 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(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tour-actions': SkdxTourActions;
+    }
+}

package/dist/tour/TourActions.js

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

package/dist/tour/TourAnatomy.cjs

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