@skdx/web-components 0.26.0

package/dist/tour/Tour.d.cts

@@ -0,0 +1,299 @@
+import { LitElement } from 'lit';
+import { type Align, type Side } from '../internal/positioning.cjs';
+/**
+ * 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.
+ */
+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.
+ */
+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.
+     */
+    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.
+     */
+    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`.
+     */
+    placement?: Side;
+    /**
+     * Alignment along `placement`.
+     * @default undefined — falls back to `<skdx-tour-content>`'s own `align`, which 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.
+     */
+    type?: SkdxTourStepType;
+}
+/** The detail of `step-target-missing`. */
+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.
+ */
+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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
+     */
+    steps: SkdxTourStep[];
+    /**
+     * Whether the tour is running. Listen for `open-change` to observe or
+     * override changes.
+     * @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.
+     */
+    defaultOpen: boolean;
+    /**
+     * Zero-based index of the active step. Listen for `step-change` to observe
+     * or override changes.
+     * @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.
+     * @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.
+     */
+    closeOnEscape: 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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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. */
+    get activeStep(): SkdxTourStep | undefined;
+    /** How many steps the tour has — what "Step 2 of 5" counts against. */
+    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.
+     */
+    get anchored(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /** @internal Sets `open`; the `open-change` event follows from `updated()`. */
+    setOpen(next: boolean): void;
+    /** @internal Moves to `index`, clamped to the step list. */
+    goTo(index: number): void;
+    /** @internal Advances a step, or completes the tour when already on the last one. */
+    next(): void;
+    /** @internal Steps back. A no-op on the first step, which has nowhere to go. */
+    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.
+     */
+    skip(): void;
+    /** @internal Ends the tour by advancing past the last step. Always dispatches, for the same reason as {@link skip}. */
+    complete(): void;
+    /** @internal */
+    focusTrigger(): void;
+    /** @internal Tells every part to re-read this element. */
+    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.
+     */
+    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 measure;
+    private stopPolling;
+    private announceStep;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tour': SkdxTour;
+    }
+}

package/dist/tour/Tour.d.ts

@@ -0,0 +1,299 @@
+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.
+ */
+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.
+ */
+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.
+     */
+    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.
+     */
+    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`.
+     */
+    placement?: Side;
+    /**
+     * Alignment along `placement`.
+     * @default undefined — falls back to `<skdx-tour-content>`'s own `align`, which 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.
+     */
+    type?: SkdxTourStepType;
+}
+/** The detail of `step-target-missing`. */
+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.
+ */
+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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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.
+     */
+    steps: SkdxTourStep[];
+    /**
+     * Whether the tour is running. Listen for `open-change` to observe or
+     * override changes.
+     * @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.
+     */
+    defaultOpen: boolean;
+    /**
+     * Zero-based index of the active step. Listen for `step-change` to observe
+     * or override changes.
+     * @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.
+     * @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.
+     */
+    closeOnEscape: 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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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.
+     */
+    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. */
+    get activeStep(): SkdxTourStep | undefined;
+    /** How many steps the tour has — what "Step 2 of 5" counts against. */
+    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.
+     */
+    get anchored(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: Map<string, unknown>): void;
+    /** @internal Sets `open`; the `open-change` event follows from `updated()`. */
+    setOpen(next: boolean): void;
+    /** @internal Moves to `index`, clamped to the step list. */
+    goTo(index: number): void;
+    /** @internal Advances a step, or completes the tour when already on the last one. */
+    next(): void;
+    /** @internal Steps back. A no-op on the first step, which has nowhere to go. */
+    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.
+     */
+    skip(): void;
+    /** @internal Ends the tour by advancing past the last step. Always dispatches, for the same reason as {@link skip}. */
+    complete(): void;
+    /** @internal */
+    focusTrigger(): void;
+    /** @internal Tells every part to re-read this element. */
+    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.
+     */
+    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 measure;
+    private stopPolling;
+    private announceStep;
+    render(): import("lit").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tour': SkdxTour;
+    }
+}

package/dist/tour/Tour.js

@@ -0,0 +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`
+    :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};

package/dist/tour/TourArrow.cjs

@@ -0,0 +1 @@
+"use strict";var n=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var y=Object.getOwnPropertyNames;var u=Object.prototype.hasOwnProperty;var f=(o,t)=>{for(var r in t)n(o,r,{get:t[r],enumerable:!0})},k=(o,t,r,s)=>{if(t&&typeof t=="object"||typeof t=="function")for(let e of y(t))!u.call(o,e)&&e!==r&&n(o,e,{get:()=>t[e],enumerable:!(s=p(t,e))||s.enumerable});return o};var E=o=>k(n({},"__esModule",{value:!0}),o),h=(o,t,r,s)=>{for(var e=s>1?void 0:s?p(t,r):t,d=o.length-1,l;d>=0;d--)(l=o[d])&&(e=(s?l(t,r,e):l(e))||e);return s&&e&&n(t,r,e),e};var R={};f(R,{SkdxTourArrow:()=>a});module.exports=E(R);var m=require("../internal/define.cjs"),c=require("../internal/overlay-arrow.cjs"),v=require("../internal/styles.cjs"),i=require("./Tour.cjs");var a=class extends c.SkdxOverlayArrow{constructor(){super(...arguments);this.root=null;this.onRootUpdate=()=>this.syncHostState()}connectedCallback(){super.connectedCallback(),this.root=(0,i.findTourRoot)(this),this.root?.addEventListener(i.TOUR_INTERNAL_UPDATE,this.onRootUpdate),this.syncHostState()}disconnectedCallback(){this.root?.removeEventListener(i.TOUR_INTERNAL_UPDATE,this.onRootUpdate),super.disconnectedCallback()}syncHostState(){this.hidden=!this.root?.anchored}};a.styles=[c.SkdxOverlayArrow.styles,v.hiddenHostStyles],a=h([(0,m.customElement)("skdx-tour-arrow","tour","arrow")],a);0&&(module.exports={SkdxTourArrow});

package/dist/tour/TourArrow.d.cts

@@ -0,0 +1,32 @@
+import { SkdxOverlayArrow } from '../internal/overlay-arrow.cjs';
+/**
+ * `<skdx-tour-arrow>` — optional pointer from `<skdx-tour-content>` back at the
+ * step's target, self-positioning on the edge facing it. Render it inside
+ * `<skdx-tour-content>`; it takes no positioning attributes of its own (see
+ * `data-side` on the content for where it landed).
+ *
+ * Hidden on a step that is centred — one with no target, or with
+ * `type: 'dialog'`. There is nothing for it to point at, and the popper layer
+ * writes it no offsets on that branch.
+ *
+ * @example
+ * ```html
+ * <skdx-tour-content>
+ *   <skdx-tour-title>Your inbox</skdx-tour-title>
+ *   <skdx-tour-arrow></skdx-tour-arrow>
+ * </skdx-tour-content>
+ * ```
+ */
+export declare class SkdxTourArrow extends SkdxOverlayArrow {
+    static styles: import("lit").CSSResultGroup[];
+    private root;
+    private readonly onRootUpdate;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private syncHostState;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'skdx-tour-arrow': SkdxTourArrow;
+    }
+}