@aceshooting/lyra-ui 4.1.0 → 5.0.0

package/dist/components/utility/tour/tour.class.d.ts

@@ -0,0 +1,253 @@
+import { type TemplateResult, type PropertyValues } from 'lit';
+import type { Placement } from '@floating-ui/dom';
+import { LyraElement } from '../../../internal/lyra-element.js';
+/**
+ * Resolves the element a step spotlights/anchors to. A `string` is resolved via
+ * `this.ownerDocument.querySelector<HTMLElement>(target)` (top-level light DOM only -- CSS
+ * selectors can't pierce a closed shadow root); pass a direct `HTMLElement` or a resolver
+ * function for anything else (inside a shadow root, not yet mounted, computed dynamically).
+ * Re-resolved every time this step becomes active (never cached) so a target that mounts later
+ * in the app's lifecycle still resolves correctly once its own step is reached. A direct
+ * `HTMLElement` reference is checked for `isConnected` on every re-resolution (same
+ * target-missing handling as a selector/function that returns nothing) since, unlike a selector
+ * string, a stale element reference can't "self-heal" across a DOM remount -- prefer a `string`
+ * or function resolver for targets that might be replaced while the tour runs.
+ */
+export type TourTarget = string | HTMLElement | (() => HTMLElement | null);
+export interface TourStep {
+    /** Stable id for this step. Used in event details/DOM bookkeeping, never shown to the user. */
+    id: string;
+    /** The element this step spotlights and anchors its popover to. */
+    target: TourTarget;
+    /** Visible step heading -- becomes the popover panel's accessible name via `aria-labelledby`.
+     *  Required: every step always has a name, so `<lr-tour>` never needs a generic fallback
+     *  label of its own. Plain text; not localized by this component (caller-supplied data, per
+     *  the library's i18n exception for app content). */
+    heading: string;
+    /** Visible step body copy. Rendered as plain text (Lit auto-escapes -- no HTML/markdown
+     *  parsing). Ignored for the currently active step if the default slot carries real content
+     *  (see the class doc's Slots section) -- the slot wins when both are present. */
+    content?: string;
+    /** Per-step Floating UI placement override. Falls back to the tour-level `placement` prop
+     *  (`'bottom'`) when omitted. Resolved through `rtlAwarePlacement()` before being passed to
+     *  `place()`, same as `lr-menu`/`lr-popover`. */
+    placement?: Placement;
+    /** Per-step override of the tour-level `spotlightPadding` prop (`4`). Extra px between the
+     *  target's own box and the spotlight cutout/ring. `distance` (the offset between the target
+     *  and the popover itself) is a tour-level-only setting -- it has no per-step override. */
+    spotlightPadding?: number;
+    /** Opts this step's target OUT of the tour's default non-interactive-spotlight behavior --
+     *  see the class doc's "Target interactivity" section. Defaults to `false`. */
+    interactiveTarget?: boolean;
+    /** Hides the Previous control outright (not just disables it) for this step -- e.g. a step
+     *  reached only via a side effect that can't be cleanly reversed. Defaults to `false`; compare
+     *  with the first step, whose Previous control is disabled-but-visible instead, for a stable
+     *  footer layout across steps. */
+    hidePrevious?: boolean;
+}
+/**
+ * Reason a tour ended, forwarded as the `lr-tour-end` event detail.
+ * `'completed'`/`'skip'`/`'escape'` are emitted by the tour's own built-in dismiss triggers;
+ * `'unmount'` is emitted when the tour is removed from the DOM while still open by something
+ * other than its own `end()` (mirrors `lr-dialog`'s identical `'unmount'` case); any other
+ * string is whatever a caller passes to `end()` directly.
+ */
+export type TourEndReason = 'completed' | 'skip' | 'escape' | 'api' | 'unmount' | (string & Record<never, never>);
+export interface LyraTourEventMap {
+    'lr-tour-start': CustomEvent<{
+        index: number;
+    }>;
+    'lr-tour-step-change': CustomEvent<{
+        index: number;
+        previousIndex: number;
+        step: TourStep;
+        via: 'next' | 'back' | 'goto';
+    }>;
+    'lr-tour-end': CustomEvent<TourEndReason>;
+    'lr-tour-target-missing': CustomEvent<{
+        index: number;
+        step: TourStep;
+    }>;
+}
+/**
+ * `<lr-tour>` -- a spotlight-and-step guided walkthrough for first-run onboarding. A sequence
+ * of steps, each anchored to a target element elsewhere in the page via the shared Floating UI
+ * positioner, shown against a dimmed full-viewport backdrop with a cutout/ring highlighting the
+ * current target, with Next/Previous/Skip controls and a step-progress indicator. First-party
+ * invention (no Web Awesome equivalent) -- nearest precedent in shape is `lr-dialog` (overlay
+ * lifecycle/focus trap) + `lr-carousel` (index-based navigation) + `lr-stepper`
+ * (progress/RTL arrow-key nav).
+ *
+ * **Not a form-associated control.** A tour is a walkthrough, not a field -- it deliberately has
+ * no `label`/`hint`/`error` chrome and no `FormAssociated` mixin.
+ *
+ * **Controlled component.** `steps` is never mutated by this component (mirrors
+ * `lr-stepper`'s `steps`); only `activeIndex` and `open` are self-managed, mirroring
+ * `lr-carousel`'s `index`.
+ *
+ * **Target interactivity.** By default, the step's spotlighted target is non-interactive while
+ * its step is active: it stays visually revealed and perceivable/announceable by assistive tech
+ * (not `inert`, not `aria-hidden`) but cannot be clicked -- every pointer event over the full
+ * viewport, including directly over the visually-revealed target, is captured by the backdrop
+ * (CSS `mask` does not affect hit-testing, only `clip-path` does) -- and cannot be reached by Tab
+ * (the shared overlay focus trap confines Tab to the popover panel). Set `step.interactiveTarget`
+ * to opt a step's target out of this: the backdrop additionally clips itself (via `clip-path`,
+ * which *does* affect hit-testing) around the same rect, so pointer/click events fall through to
+ * the live target underneath. This only restores pointer/click reachability, not Tab
+ * reachability -- the focus trap still confines keyboard focus to the step popover regardless of
+ * `interactiveTarget`. If the interaction a step demonstrates must also be keyboard-reachable,
+ * don't rely on Tab to reach the live target -- have the app's own listener on the target call
+ * `tourEl.next()` to advance the tour programmatically.
+ *
+ * **Focus management.** Uses the shared overlay manager with `modal: false` -- a deliberate
+ * choice, not an oversight. The default `modal: true` would mark the entire rest of the page
+ * (including the spotlighted target itself, since it lives outside `<lr-tour>`'s own ancestor
+ * chain) `inert`, stripping it from the accessibility tree entirely -- stronger than the
+ * "non-interactive but still perceivable" default described above. `modal: false` skips that
+ * DOM-wide `inert` marking; the shared Tab-trap still confines keyboard Tab to the popover panel
+ * unconditionally regardless of `modal`, and the backdrop's own hit-testing handles
+ * pointer/click reachability, so nothing is lost. `role="dialog"` and `aria-modal="true"` are
+ * still rendered on the popover panel anyway: most screen readers restrict their own virtual-
+ * cursor/browse-mode navigation to an `aria-modal="true"` element's subtree, giving assistive-
+ * tech users the same "can perceive, can't wander into, the live target" experience that the
+ * Tab-trap and backdrop hit-testing already give sighted/mouse users.
+ *
+ * Each step transition mounts a genuinely new popover DOM node (keyed on the step's `id`) so
+ * focus reliably re-enters the panel every time, even though the Previous/Next button that
+ * triggered the transition lives inside that same persistent-looking region.
+ *
+ * No `Home`/`End` jump-to-first/last-step shortcut and no click-to-jump progress dots, unlike
+ * `lr-stepper` -- a tour's steps are tied to live DOM targets that may not exist until an
+ * earlier step's side effect (opening a menu, navigating a route) has run, so free jumping is
+ * unsafe by default. `goToStep()` remains available for a host that knows what it's doing (e.g.
+ * a "restart tour" affordance elsewhere).
+ *
+ * @customElement lr-tour
+ * @slot - Rich content overriding the currently active step's plain-text `content` for that step
+ *   only. When real content is assigned, it's shown instead of `step.content`; when empty,
+ *   `step.content` renders as plain text. Not scoped per step by this component itself -- a
+ *   consumer that needs different rich content per step swaps the slotted children (or listens
+ *   for `lr-tour-step-change` and re-renders them) itself, the same "consumer owns slotted
+ *   content" pattern `lr-dialog`'s default slot already uses.
+ * @event lr-tour-start - Fired by `start()`. `detail: { index }`. Not cancelable.
+ * @event lr-tour-step-change - Fired by `next()`/`back()`/`goToStep()` before `activeIndex`
+ *   changes. `detail: { index, previousIndex, step, via }`. Cancelable -- a listener calling
+ *   `preventDefault()` leaves `activeIndex` unchanged, letting a tour gate advancement on a real
+ *   action (e.g. an onboarding step demonstrating "click this button" shouldn't let Next silently
+ *   skip past it). This is a deliberate departure from `lr-carousel`'s non-cancelable
+ *   `lr-slide-change`.
+ * @event lr-tour-end - Fired by `end()` (and by `next()` on the last step, with reason
+ *   `'completed'`). `detail: TourEndReason`. Cancelable, except in practice for `'unmount'` since
+ *   the element is already being removed -- mirrors `lr-dialog-close` exactly.
+ * @event lr-tour-target-missing - The active step's `target` did not resolve to a connected
+ *   element. `detail: { index, step }`. Not cancelable -- informational. The tour does not
+ *   auto-end; it renders that step's popover unanchored (viewport-centered, no spotlight cutout)
+ *   instead of throwing. A host can listen and decide to `skip()`/`goToStep()` in response.
+ * @csspart backdrop - The full-viewport dimmed scrim with the spotlight cutout, an inline `<svg>`.
+ *   `aria-hidden="true"`.
+ * @csspart spotlight - The decorative highlight ring drawn around the current target's (padded)
+ *   rect. `pointer-events: none`, `aria-hidden="true"`.
+ * @csspart popover - The step panel itself. `role="dialog"`.
+ * @csspart heading - The step's visible heading text element -- the `aria-labelledby` target.
+ * @csspart body - Wrapper around the step's content (slotted or `step.content`).
+ * @csspart progress - Wrapper around the built-in step-progress indicator (dots + text).
+ * @csspart progress-dot - An individual decorative dot within `progress`. `aria-hidden="true"`.
+ * @csspart progress-text - The visible "Step X of Y" text -- one of the popover's
+ *   `aria-describedby` targets.
+ * @csspart footer - Wrapper around the Previous/Skip/Next-or-Done control row.
+ * @csspart skip-button - The Skip control.
+ * @csspart previous-button - The Previous control.
+ * @csspart next-button - The Next/Done control (label switches on the last step).
+ * @cssprop --lr-tour-backdrop-color - Backdrop scrim fill. Defaults to `--lr-color-overlay`.
+ * @cssprop --lr-tour-spotlight-radius - Corner radius shared by the cutout and the ring.
+ *   Defaults to `--lr-radius`.
+ * @cssprop --lr-tour-spotlight-ring-color - Spotlight ring color. Defaults to `--lr-color-brand`.
+ * @cssprop --lr-tour-spotlight-ring-width - Spotlight ring thickness. Defaults to
+ *   `--lr-border-width-medium`.
+ * @cssprop --lr-tour-popover-max-width - Maximum popover inline size. Defaults to `--lr-size-22rem`.
+ */
+export declare class LyraTour extends LyraElement<LyraTourEventMap> {
+    static styles: import("lit").CSSResultGroup[];
+    /** Whether the tour is open. Set this (or call `start()`/`end()`) -- there is no separate
+     *  `show()`/`hide()` pair. */
+    open: boolean;
+    /** Ordered step data. Never mutated by this component -- see the class doc's controlled-
+     *  component contract. Empty (the default) renders nothing. */
+    steps: TourStep[];
+    /** Index of the currently active step, clamped to `[0, steps.length - 1]` by `goToStep()` --
+     *  and, for a direct property/attribute assignment that bypasses that method (e.g. two-way
+     *  binding an external store, or a bad `active-index` attribute), normalized the same way in
+     *  `willUpdate()` below. */
+    activeIndex: number;
+    /** Tour-level default Floating UI placement, overridable per step via `TourStep.placement`. */
+    placement: Placement;
+    /** Distance (px) between the target and the popover, passed straight to Floating UI's
+     *  `offset()` middleware -- a tour-level-only setting, mirroring `lr-popover`'s `distance`
+     *  prop exactly (can legitimately be negative for overlap). */
+    distance: number;
+    /** Tour-level default extra px between a target's own box and the spotlight cutout/ring,
+     *  overridable per step via `TourStep.spotlightPadding`. Non-negative. */
+    spotlightPadding: number;
+    /** Whether a backdrop click dismisses the tour (`end('skip')`). Defaults to `false` -- a
+     *  deliberate inversion of `lr-dialog`'s `noLightDismiss` (opt-out, default
+     *  dismiss-on-backdrop-click): a guided tour's backdrop click doing nothing by default avoids
+     *  losing onboarding progress to a stray click. Set this to restore dismiss-on-backdrop-click. */
+    lightDismiss: boolean;
+    /** Whether the built-in "Step X of Y" progress indicator (dots + text) renders in the footer. */
+    showProgress: boolean;
+    /** Host-level `aria-label` override for every step popover's accessible name -- wins over each
+     *  step's own `heading`, matching `lr-dialog`'s `accessibleLabel` pattern. Most consumers
+     *  won't need this since each step already has a meaningful name via `heading`; setting it
+     *  makes the *same* string name every step's panel. Set as a plain `aria-label` attribute on
+     *  `<lr-tour>` itself, not a public JS property. */
+    private accessibleLabel;
+    private unanchored;
+    private hasSlotContent;
+    private overlay?;
+    private releaseScrollLock?;
+    private placeCleanup?;
+    private spotlightCleanup?;
+    private readonly maskId;
+    private readonly headingId;
+    private readonly bodyId;
+    private readonly progressTextId;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Opens the tour at `index` (default `0`), clamped to `[0, steps.length - 1]`. Equivalent to
+     *  `this.activeIndex = index; this.open = true;` plus the `lr-tour-start` event. */
+    start(index?: number): void;
+    /** Advances to the next step. On the last step, ends the tour instead (`end('completed')`) --
+     *  the built-in Next/Done button calls this same method, so a custom control wired to `next()`
+     *  behaves identically to the built-in one. Cancelable via `lr-tour-step-change` (or
+     *  `lr-tour-end` when it triggers completion). */
+    next(): void;
+    /** Moves to the previous step. No-op on the first step (`activeIndex === 0`). */
+    back(): void;
+    /** Jumps directly to `index`, clamped to `[0, steps.length - 1]`. */
+    goToStep(index: number): void;
+    /** Sugar for `end('skip')`. What the built-in Skip button calls. */
+    skip(): void;
+    /** Ends the tour. `reason` is forwarded as the `lr-tour-end` detail. Cancelable (except in
+     *  practice for `'unmount'`) -- mirrors `LyraDialog.close(reason)` exactly. */
+    end(reason?: TourEndReason): void;
+    private clampIndex;
+    private transitionTo;
+    private resolveTarget;
+    private activateStep;
+    private paintSpotlight;
+    private disposePositioning;
+    private activateOverlayInternal;
+    private deactivateOverlayInternal;
+    private onBackdropClick;
+    private onDefaultSlotChange;
+    private onPopoverKeyDown;
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'lr-tour': LyraTour;
+    }
+}
+//# sourceMappingURL=tour.class.d.ts.map

package/dist/components/utility/tour/tour.class.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour.class.d.ts","sourceRoot":"","sources":["../../../../src/components/utility/tour/tour.class.ts"],"names":[],"mappings":"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"}