@theseam/ui-common 2.0.1-beta.103 → 2.0.1-beta.104

package/fesm2022/theseam-ui-common-guide.mjs

@@ -0,0 +1,1192 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, isDevMode, Injectable, inject, ElementRef, input, effect, Directive, ApplicationRef, EnvironmentInjector, createComponent, Injector, makeEnvironmentProviders, signal } from '@angular/core';
+import { Subject, defer, of, throwError, ReplaySubject, EMPTY, isObservable, from } from 'rxjs';
+import { filter, map, take, timeout, switchMap, catchError, tap } from 'rxjs/operators';
+import { driver } from 'driver.js';
+
+/** Injected by a component used as popover content. */
+const THE_SEAM_GUIDE_CONTENT = new InjectionToken('THE_SEAM_GUIDE_CONTENT');
+
+const THE_SEAM_GUIDE_DEFAULTS = {
+    dismissible: true,
+    targetTimeout: 3000,
+    onMissingTarget: 'skip',
+    targetLostGrace: 1000,
+    onTargetLost: 'elementless',
+};
+
+class TheSeamGuideBusyError extends Error {
+    constructor() {
+        super('TheSeamGuide: a non-dismissible guide is already active. Wait for' +
+            ' `activeGuide()?.afterClosed$` before starting another guide.');
+        this.name = 'TheSeamGuideBusyError';
+    }
+}
+class TheSeamGuideTargetTimeoutError extends Error {
+    targetName;
+    constructor(targetName) {
+        super(`TheSeamGuide: timed out waiting for target "${targetName}".`);
+        this.targetName = targetName;
+        this.name = 'TheSeamGuideTargetTimeoutError';
+    }
+}
+
+/**
+ * Tracks elements registered by `[seamGuideTarget]` so a guide can await a
+ * target that does not exist yet, and notice one that disappears.
+ */
+class TheSeamGuideTargetRegistry {
+    _targets = new Map();
+    _changes = new Subject();
+    /** Emits the target name whenever its registrations change. */
+    changes$ = this._changes.asObservable();
+    register(name, element) {
+        const list = this._targets.get(name) ?? [];
+        if (!list.includes(element)) {
+            list.push(element);
+        }
+        this._targets.set(name, list);
+        if (isDevMode() && list.filter((e) => e.isConnected).length > 1) {
+            console.warn(`TheSeamGuideTargetRegistry: more than one connected element is` +
+                ` registered as guide target "${name}". The most recently registered` +
+                ` one will be used, which may not be the one you meant.`);
+        }
+        this._changes.next(name);
+    }
+    unregister(name, element) {
+        const list = this._targets.get(name);
+        if (!list) {
+            return;
+        }
+        const index = list.indexOf(element);
+        if (index === -1) {
+            return;
+        }
+        list.splice(index, 1);
+        if (list.length === 0) {
+            this._targets.delete(name);
+        }
+        this._changes.next(name);
+    }
+    /** The most recently registered element for `name` that is still in the DOM. */
+    resolve(name) {
+        const list = this._targets.get(name);
+        if (!list) {
+            return null;
+        }
+        for (let i = list.length - 1; i >= 0; i--) {
+            if (list[i].isConnected) {
+                return list[i];
+            }
+        }
+        return null;
+    }
+    /** Emits as soon as `name` resolves. Errors with a timeout error otherwise. */
+    waitFor(name, timeoutMs) {
+        return defer(() => {
+            const existing = this.resolve(name);
+            if (existing !== null) {
+                return of(existing);
+            }
+            return this._changes.pipe(filter((changed) => changed === name), map(() => this.resolve(name)), filter((el) => el !== null), take(1), timeout({
+                first: timeoutMs,
+                with: () => throwError(() => new TheSeamGuideTargetTimeoutError(name)),
+            }));
+        });
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideTargetRegistry, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideTargetRegistry, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideTargetRegistry, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Marks an element as a named guide target.
+ *
+ * Registering on init and unregistering on destroy is what lets a guide await a
+ * target that has not rendered yet, and recover when one is destroyed and
+ * recreated mid-step.
+ */
+class TheSeamGuideTargetDirective {
+    _registry = inject(TheSeamGuideTargetRegistry);
+    _elementRef = inject(ElementRef);
+    seamGuideTarget = input.required(...(ngDevMode ? [{ debugName: "seamGuideTarget" }] : []));
+    _registeredName = null;
+    constructor() {
+        effect(() => {
+            const name = this.seamGuideTarget();
+            if (this._registeredName === name) {
+                return;
+            }
+            const element = this._elementRef.nativeElement;
+            if (this._registeredName !== null) {
+                this._registry.unregister(this._registeredName, element);
+            }
+            this._registry.register(name, element);
+            this._registeredName = name;
+        });
+    }
+    ngOnDestroy() {
+        if (this._registeredName !== null) {
+            this._registry.unregister(this._registeredName, this._elementRef.nativeElement);
+            this._registeredName = null;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideTargetDirective, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "20.3.15", type: TheSeamGuideTargetDirective, isStandalone: true, selector: "[seamGuideTarget]", inputs: { seamGuideTarget: { classPropertyName: "seamGuideTarget", publicName: "seamGuideTarget", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideTargetDirective, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[seamGuideTarget]',
+                    standalone: true,
+                }]
+        }], ctorParameters: () => [], propDecorators: { seamGuideTarget: [{ type: i0.Input, args: [{ isSignal: true, alias: "seamGuideTarget", required: true }] }] } });
+
+const THE_SEAM_GUIDE_ADAPTER = new InjectionToken('THE_SEAM_GUIDE_ADAPTER');
+
+/**
+ * Consumer-facing handle to a running guide.
+ *
+ * The caller owns this ref's lifetime. A guide is not closed automatically
+ * when the component that started it is destroyed — `TheSeamGuideService` is
+ * `providedIn: 'root'`, so its `ngOnDestroy` only fires when the root
+ * injector itself is destroyed, not on ordinary route/component teardown. A
+ * component that may be destroyed before its guide naturally ends should tie
+ * the ref to its own lifetime:
+ *
+ * ```ts
+ * const ref = this._guide.start(config)
+ * inject(DestroyRef).onDestroy(() => ref.close())
+ * ```
+ */
+class TheSeamGuideRef {
+    _session;
+    constructor(_session) {
+        this._session = _session;
+    }
+    /**
+     * Replays every event emitted so far for this guide, from `started`
+     * onward — a subscriber attached at any point sees the complete history,
+     * not just events emitted after it subscribes. This is why subscribing
+     * immediately after `start()` returns still observes `started`: `start()`
+     * runs synchronously, but the event is not lost, it is replayed.
+     */
+    get events$() {
+        return this._session.events$;
+    }
+    get afterClosed$() {
+        return this._session.afterClosed$;
+    }
+    get activeIndex() {
+        return this._session.activeIndex;
+    }
+    /** Whether the user may dismiss this guide. Read by the service's concurrency rule. */
+    get dismissible() {
+        return this._session.dismissible;
+    }
+    next() {
+        this._session.next();
+    }
+    previous() {
+        this._session.previous();
+    }
+    moveTo(index) {
+        this._session.moveTo(index);
+    }
+    refresh() {
+        this._session.refresh();
+    }
+    /** Always works, including when `dismissible` is false. */
+    close(reason = 'dismissed') {
+        this._session.close(reason);
+    }
+}
+
+/**
+ * Creates and destroys the Angular view behind a popover slot.
+ *
+ * Separate from `TheSeamGuideSession` so session specs can run against a fake
+ * and stay free of a real `ApplicationRef`, and so the session stays free of
+ * rendering concerns.
+ */
+class TheSeamGuideDomContentRenderer {
+    _appRef = inject(ApplicationRef);
+    _envInjector = inject(EnvironmentInjector);
+    /**
+     * Renders `slot` into `host`, which the caller owns.
+     *
+     * Views are attached to `ApplicationRef` rather than created through a
+     * `ViewContainerRef`, because this is a `providedIn: 'root'` service and
+     * there is no view container to reach. Attachment is what makes a view
+     * change-detected; where its nodes sit in the DOM is independent of it,
+     * which is what lets driver.js move `host` around as it rebuilds its
+     * popover on every render.
+     */
+    render(slot, context, host) {
+        if (slot.kind === 'template') {
+            const view = slot.template.createEmbeddedView(context);
+            this._appRef.attachView(view);
+            host.append(...view.rootNodes);
+            return {
+                destroy: () => {
+                    this._appRef.detachView(view);
+                    view.destroy();
+                },
+            };
+        }
+        const ref = createComponent(slot.component, {
+            environmentInjector: this._envInjector,
+            // DI rather than `setInput`: `data` is shallow-merged across three
+            // layers, so it routinely carries keys a given component never declared
+            // as an input, and `setInput` throws NG0303 for those.
+            elementInjector: Injector.create({
+                parent: this._envInjector,
+                providers: [
+                    { provide: THE_SEAM_GUIDE_CONTENT, useValue: context },
+                    { provide: TheSeamGuideRef, useValue: context.guide },
+                ],
+            }),
+        });
+        this._appRef.attachView(ref.hostView);
+        host.append(ref.location.nativeElement);
+        return {
+            destroy: () => {
+                this._appRef.detachView(ref.hostView);
+                ref.destroy();
+            },
+        };
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideDomContentRenderer, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideDomContentRenderer, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideDomContentRenderer, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * driver.js implementation of the guide adapter.
+ *
+ * The whole step array is handed to driver.js so its buttons, progress
+ * indicator, and keyboard handling are preserved, but every navigation click is
+ * intercepted and reported instead of acted on. The session decides what
+ * happens next.
+ */
+class DriverJsGuideAdapter {
+    _driver = null;
+    start(config, callbacks) {
+        this.destroy();
+        const driverConfig = {
+            steps: config.steps.map((step) => this._toDriveStep(step)),
+            allowClose: config.allowUserDismiss,
+            showButtons: config.allowUserDismiss
+                ? ['next', 'previous', 'close']
+                : ['next', 'previous'],
+            // Intercept every navigation: driver.js must never advance itself,
+            // because the session owns sequencing.
+            onNextClick: () => callbacks.onNextRequested(),
+            onPrevClick: () => callbacks.onPreviousRequested(),
+            onCloseClick: () => callbacks.onCloseRequested(),
+            onDestroyStarted: () => callbacks.onCloseRequested(),
+        };
+        this._driver = driver(driverConfig);
+    }
+    next() {
+        this._driver?.moveNext();
+    }
+    previous() {
+        this._driver?.movePrevious();
+    }
+    moveTo(index) {
+        if (this._driver === null) {
+            return;
+        }
+        if (!this._driver.isActive()) {
+            this._driver.drive(index);
+            return;
+        }
+        this._driver.moveTo(index);
+    }
+    refresh() {
+        // driver.js's own refresh() only repositions the overlay/popover around
+        // the cached active element — it never re-invokes the step's element
+        // resolver. Re-driving the current index is what forces re-resolution,
+        // which is the whole point of `refresh()` for mid-step recovery.
+        //
+        // This re-drive rebuilds the popover DOM every time, producing a visible
+        // flash even when the resolved element hasn't changed — driver.js has no
+        // primitive for "re-resolve without re-render". Callers should treat this
+        // as a recovery operation, not something to invoke speculatively.
+        const index = this._driver?.getActiveIndex();
+        if (index !== undefined) {
+            this._driver?.moveTo(index);
+        }
+    }
+    destroy() {
+        if (this._driver === null) {
+            return;
+        }
+        const instance = this._driver;
+        // Null first, out of caution: if driver.js's public destroy() ever starts
+        // invoking onDestroyStarted synchronously, we don't want that callback
+        // re-entering this adapter through a non-null _driver. Today it doesn't —
+        // destroy() tears down with confirm=false and always skips
+        // onDestroyStarted — so this ordering isn't load-bearing for the current
+        // wiring, just defensive against a future driver.js change.
+        this._driver = null;
+        instance.destroy();
+    }
+    isActive() {
+        return this._driver?.isActive() ?? false;
+    }
+    _toDriveStep(step) {
+        // Typed honestly as `Element | undefined`, matching what the resolver
+        // can actually return — `undefined` is a real outcome, not an absent
+        // one, since the elementless path depends on it.
+        const resolveElement = step.element === undefined ? undefined : () => step.element?.();
+        return {
+            // driver.js's own public type only declares `() => Element`, but its
+            // runtime falls back to a centered popover when the resolver returns
+            // `undefined`. This cast crosses that documentation gap at the one
+            // point it matters; `resolveElement` above keeps `undefined` visible
+            // everywhere else in this method.
+            element: resolveElement,
+            popover: step.popover === undefined
+                ? undefined
+                : this._toDrivePopover(step.popover),
+        };
+    }
+    /**
+     * `ExhaustiveMap` makes every key of `TheSeamGuideAdapterPopover` required
+     * in `mapped`, so adding a field to the boundary is a compile error here
+     * until it is carried through.
+     */
+    _toDrivePopover(popover) {
+        const mapped = {
+            title: popover.title,
+            description: popover.description,
+            side: popover.side,
+            align: popover.align,
+        };
+        const { title, description, side, align } = mapped;
+        const hasNode = title instanceof HTMLElement || description instanceof HTMLElement;
+        return {
+            title: typeof title === 'string' ? title : undefined,
+            description: typeof description === 'string' ? description : undefined,
+            side,
+            align,
+            // driver.js hides a slot whose string is falsy, so a slot filled with a
+            // node must be un-hidden as well as populated. It also rebuilds the
+            // whole popover on every render, so this runs again on each re-drive
+            // and simply re-adopts the same host node.
+            onPopoverRender: hasNode
+                ? (dom) => {
+                    if (title instanceof HTMLElement) {
+                        dom.title.replaceChildren(title);
+                        dom.title.style.display = 'block';
+                    }
+                    if (description instanceof HTMLElement) {
+                        dom.description.replaceChildren(description);
+                        dom.description.style.display = 'block';
+                    }
+                }
+                : undefined,
+        };
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: DriverJsGuideAdapter, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: DriverJsGuideAdapter });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: DriverJsGuideAdapter, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Application-wide popover defaults — the outermost of the three content
+ * layers. Always provided by {@link provideTheSeamGuide}, defaulting to `{}`.
+ */
+const THE_SEAM_GUIDE_POPOVER_DEFAULTS = new InjectionToken('THE_SEAM_GUIDE_POPOVER_DEFAULTS');
+/**
+ * Wires the guide's presentation engine.
+ *
+ * The engine is named only here — no consumer imports driver.js — so replacing
+ * it is a change to this call, not to application code.
+ */
+function provideTheSeamGuide(options = {}) {
+    return makeEnvironmentProviders([
+        {
+            provide: THE_SEAM_GUIDE_ADAPTER,
+            useClass: options.adapter ?? DriverJsGuideAdapter,
+        },
+        {
+            provide: THE_SEAM_GUIDE_POPOVER_DEFAULTS,
+            useValue: options.popover ?? {},
+        },
+    ]);
+}
+
+/** A bare string is sugar for `{ text }`. */
+function normalize(value) {
+    if (value === undefined || value === null) {
+        return value;
+    }
+    return typeof value === 'string' ? { text: value } : value;
+}
+/**
+ * Resolves one popover slot from its three layers. `null` means the slot is
+ * absent and nothing is rendered for it.
+ *
+ * Presence and content are decided separately: only the step and session
+ * layers can make a slot present, but once it is, all three layers contribute
+ * the renderer, the text, and the data. That is what lets a step say
+ * `title: 'Step One'` and still get the application's title component.
+ */
+function resolveGuideContentSlot(layers) {
+    const presence = layers.step !== undefined ? layers.step : layers.session;
+    if (presence === undefined || presence === null) {
+        return null;
+    }
+    const provider = normalize(layers.provider);
+    const session = normalize(layers.session);
+    const step = normalize(layers.step);
+    const nearestFirst = [step, session, provider];
+    const outermostFirst = [provider, session, step];
+    // One search for the renderer, not one per kind: the nearest layer naming
+    // either wins outright, so a step's template beats a session's component.
+    const renderer = nearestFirst.find((layer) => layer?.template != null || layer?.component != null);
+    const text = nearestFirst.find((layer) => layer?.text !== undefined)?.text;
+    const data = {};
+    for (const layer of outermostFirst) {
+        if (layer?.data !== undefined) {
+            Object.assign(data, layer.data);
+        }
+    }
+    if (renderer?.template != null) {
+        return { kind: 'template', template: renderer.template, text, data };
+    }
+    if (renderer?.component != null) {
+        return { kind: 'component', component: renderer.component, text, data };
+    }
+    return text === undefined ? null : { kind: 'text', text };
+}
+
+class TheSeamGuideSession {
+    // ReplaySubject, not Subject: `start()` runs synchronously (including its
+    // `'started'` emit) before the service hands the ref back to the caller, so
+    // a subscriber that attaches right after `start()` returns is necessarily
+    // late. Replaying history is what lets it still observe events already
+    // emitted during that synchronous start, matching `_afterClosed` below.
+    _events = new ReplaySubject();
+    _afterClosed = new ReplaySubject(1);
+    _activeIndex = signal(-1, ...(ngDevMode ? [{ debugName: "_activeIndex" }] : []));
+    _transitions = new Subject();
+    _transitionSub = null;
+    _recoverySub = null;
+    // Bumped by every `_disarmRecovery()` call. A re-arm queued on a microtask
+    // captures the generation in effect when it was queued and checks it before
+    // acting, so a re-arm for a step the session has since moved past (a
+    // transition disarmed-and-rearmed for a *different* step in between) is a
+    // no-op instead of clobbering the newer arming.
+    _recoveryGeneration = 0;
+    _closed = false;
+    // Whether the currently active step's `afterStep` has already fired for
+    // this departure. A skip or a cancellation re-requests a transition
+    // without changing `_activeIndex` (the departed-from step never painted
+    // anything new), so without this guard the same step's `afterStep` would
+    // re-run on every retry. Reset to `false` whenever a step actually paints.
+    _afterStepFired = false;
+    // Index whose `beforeStep` has already been fired while its transition is
+    // still in flight (target not yet resolved), or `null`. driver.js leaves
+    // the Next/Previous buttons live during that wait, so a second click
+    // re-requests the same index; without this guard `switchMap` would restart
+    // the transition and run `beforeStep` a second time before the first
+    // attempt ever settles. Reset to `null` whenever a step actually paints —
+    // mirroring `_afterStepFired` — so a later, genuine re-entry to the same
+    // index still runs its `beforeStep`.
+    _beforeStepFiredFor = null;
+    steps;
+    options;
+    events$ = this._events.asObservable();
+    afterClosed$ = this._afterClosed.asObservable();
+    activeIndex = this._activeIndex.asReadonly();
+    _adapter;
+    _registry;
+    _contentRenderer;
+    _getRef;
+    _slots = [];
+    _popoverDefaults;
+    _sessionPopover;
+    _onClosed;
+    constructor(config, deps) {
+        this._adapter = deps.adapter;
+        this._registry = deps.registry;
+        this._contentRenderer = deps.contentRenderer;
+        this._getRef = deps.getRef;
+        this._popoverDefaults = deps.popoverDefaults;
+        this._sessionPopover = config.popover;
+        this._onClosed = deps.onClosed;
+        this.steps = config.steps;
+        this.options = { ...THE_SEAM_GUIDE_DEFAULTS, ...stripUndefined(config) };
+        this._transitionSub = this._transitions
+            .pipe(switchMap((request) => this._runTransition(request.index, request.direction)))
+            .subscribe();
+    }
+    get dismissible() {
+        return this.options.dismissible;
+    }
+    start() {
+        this._buildSlots();
+        this._adapter.start({
+            steps: this.steps.map((step, index) => this._toAdapterStep(step, index)),
+            allowUserDismiss: this.options.dismissible,
+        }, {
+            onNextRequested: () => this.next(),
+            onPreviousRequested: () => this.previous(),
+            onCloseRequested: () => this.close('dismissed'),
+        });
+        this._emit({ type: 'started' });
+        this.moveTo(0);
+    }
+    next() {
+        this._request(this._activeIndex() + 1, 1);
+    }
+    previous() {
+        this._request(this._activeIndex() - 1, -1);
+    }
+    moveTo(index) {
+        this._request(index, index >= this._activeIndex() ? 1 : -1);
+    }
+    /**
+     * Requests a transition.
+     *
+     * The emission is deferred to a microtask because `_applyMissPolicy` calls
+     * this from *inside* the `switchMap` projection. Emitting synchronously there
+     * would make the transition cancel itself mid-flight. `fakeAsync`'s `tick()`
+     * flushes microtasks, so specs are unaffected.
+     */
+    _request(index, direction) {
+        if (this._closed) {
+            return;
+        }
+        queueMicrotask(() => {
+            if (this._closed) {
+                return;
+            }
+            this._transitions.next({ index, direction });
+        });
+    }
+    refresh() {
+        this._adapter.refresh();
+    }
+    close(reason) {
+        if (this._closed) {
+            return;
+        }
+        this._closed = true;
+        this._transitionSub?.unsubscribe();
+        this._transitionSub = null;
+        this._disarmRecovery();
+        const result = {
+            reason,
+            lastIndex: this._activeIndex(),
+        };
+        this._adapter.destroy();
+        this._destroyAllSlots();
+        this._emit({ type: 'closed', result });
+        this._afterClosed.next(result);
+        this._afterClosed.complete();
+        this._events.complete();
+        this._onClosed(this);
+    }
+    _emit(event) {
+        this._events.next(event);
+    }
+    /**
+     * The one sequence every transition runs. Cancellable: a new request causes
+     * `switchMap` to unsubscribe from this, so nothing paints after teardown.
+     *
+     * A `catchError` wraps the whole sequence: a hook that throws or rejects
+     * must not escape to the outer `_transitions` subscriber, because that
+     * subscriber has no error handler of its own and an uncaught error there
+     * would unsubscribe it permanently, silently wedging the session (`next`,
+     * `previous`, and `moveTo` would become no-ops forever). A caught failure
+     * closes the guide rather than running the miss policy: the miss policy
+     * exists for a target that never appeared, not an arbitrary thrown error,
+     * and reusing it would (a) misreport the close reason as `'targetMissing'`
+     * for an `'end'`-policy step that never had a target problem, and (b) run
+     * `_applyMissPolicy` unprotected as the last step of an error handler,
+     * where a further throw (e.g. from `_paint` → `_onStepPainted`, which
+     * Task 7 turns into real logic) would escape to the same unhandled outer
+     * subscriber this whole `catchError` exists to protect.
+     */
+    _runTransition(index, direction) {
+        if (this._closed) {
+            return EMPTY;
+        }
+        this._disarmRecovery();
+        if (index >= this.steps.length) {
+            this.close('completed');
+            return EMPTY;
+        }
+        if (index < 0) {
+            return EMPTY;
+        }
+        const outgoing = this._activeIndex() >= 0 ? this.steps[this._activeIndex()] : undefined;
+        const incoming = this.steps[index];
+        const afterStep$ = this._afterStepFired
+            ? of(null)
+            : defer(() => {
+                this._afterStepFired = true;
+                return this._runHook(outgoing?.afterStep);
+            });
+        const beforeStep$ = this._beforeStepFiredFor === index
+            ? of(null)
+            : defer(() => {
+                this._beforeStepFiredFor = index;
+                return this._runHook(incoming.beforeStep);
+            });
+        return afterStep$.pipe(switchMap(() => beforeStep$), switchMap(() => this._resolveTarget(incoming)), switchMap((outcome) => {
+            if (this._closed) {
+                return EMPTY;
+            }
+            if (outcome === 'missing') {
+                return this._applyMissPolicy(index, incoming, direction);
+            }
+            this._paint(index, incoming);
+            return EMPTY;
+        }), catchError((err) => {
+            // Deliberately no call-out to `_applyMissPolicy` or anything else
+            // that could itself throw: this handler is the last backstop before
+            // the outer, handler-less `_transitions` subscription, so the whole
+            // body is wrapped in `try/catch` and swallows on failure — there is
+            // nothing left to recover to.
+            try {
+                if (this._closed) {
+                    return EMPTY;
+                }
+                if (isDevMode()) {
+                    console.warn(`TheSeamGuideSession: step ${index} threw during its` +
+                        ` transition (${String(err)}); closing the guide.`);
+                }
+                this.close('destroyed');
+            }
+            catch {
+                // Nothing left to recover from.
+            }
+            return EMPTY;
+        }));
+    }
+    /** Paints a step that is actually entering: real target or elementless. */
+    _paint(index, step) {
+        const outgoing = this._activeIndex();
+        // Before `moveTo`: driver.js calls `onPopoverRender` synchronously from
+        // there, so the host must already hold its view.
+        this._renderSlots(index);
+        // A content component is given `TheSeamGuideRef` on its element injector,
+        // so its constructor runs synchronously inside `_renderSlots` above and
+        // can call `ref.close()` re-entrantly. `close()` cannot destroy the view
+        // `_renderSlots` just created — it is only assigned into `binding.view`
+        // after `render()` returns — so this must destroy it here instead, and
+        // must not touch the (already-destroyed) adapter or emit any further
+        // events for a session that is no longer open.
+        if (this._closed) {
+            this._destroySlots(index);
+            return;
+        }
+        this._activeIndex.set(index);
+        this._afterStepFired = false;
+        this._beforeStepFiredFor = null;
+        this._adapter.moveTo(index);
+        if (outgoing !== index) {
+            this._destroySlots(outgoing);
+        }
+        this._emit({ type: 'stepChanged', index, step });
+        this._onStepPainted(index, step);
+    }
+    _buildSlots() {
+        for (const step of this.steps) {
+            this._slots.push({
+                title: this._bindSlot(step, 'title'),
+                description: this._bindSlot(step, 'description'),
+            });
+        }
+    }
+    _bindSlot(step, name) {
+        const resolved = this._resolveSlot(step, name);
+        if (resolved === null) {
+            return null;
+        }
+        if (resolved.kind === 'text') {
+            return { kind: 'text', text: resolved.text };
+        }
+        return {
+            kind: 'view',
+            slot: resolved,
+            host: document.createElement('div'),
+            view: null,
+        };
+    }
+    _renderSlots(index) {
+        const slots = this._slots[index];
+        if (slots === undefined) {
+            return;
+        }
+        for (const binding of [slots.title, slots.description]) {
+            if (binding === null ||
+                binding.kind !== 'view' ||
+                binding.view !== null) {
+                continue;
+            }
+            binding.view = this._contentRenderer.render(binding.slot, this._contentContext(index, binding.slot), binding.host);
+        }
+    }
+    _destroySlots(index) {
+        const slots = this._slots[index];
+        if (slots === undefined) {
+            return;
+        }
+        for (const binding of [slots.title, slots.description]) {
+            if (binding === null ||
+                binding.kind !== 'view' ||
+                binding.view === null) {
+                continue;
+            }
+            binding.view.destroy();
+            binding.view = null;
+            binding.host.replaceChildren();
+        }
+    }
+    _destroyAllSlots() {
+        for (let index = 0; index < this._slots.length; index++) {
+            this._destroySlots(index);
+        }
+    }
+    /** `data` is per slot, so the context is built per slot rather than per step. */
+    _contentContext(index, slot) {
+        return {
+            $implicit: slot.data,
+            data: slot.data,
+            text: slot.text,
+            step: this.steps[index],
+            index,
+            total: this.steps.length,
+            guide: this._getRef(),
+        };
+    }
+    /**
+     * Arms mid-step loss detection for a painted step.
+     *
+     * Only named targets are watched — a selector or `Element` has no
+     * notification channel, so recovery does not apply to them in v1.
+     */
+    _onStepPainted(index, step) {
+        // A re-entrant `close()` from inside `_renderSlots` (see `_paint`) can
+        // reach here via the same synchronous call stack that `close()` itself
+        // triggered — `_paint` returns before calling this when it detects that
+        // case, but a defensive check here is what stops `TheSeamGuideTargetRegistry`
+        // (`providedIn: 'root'`) from ever seeing a subscription arm for a session
+        // that no longer exists to disarm it.
+        if (this._closed) {
+            return;
+        }
+        this._disarmRecovery();
+        const generation = this._recoveryGeneration;
+        const name = typeof step.element === 'string' ? step.element : null;
+        if (name === null) {
+            return;
+        }
+        // `_resolveNow` — not the registry's own `resolve` — is the same lookup
+        // that feeds the popover's resolver closure (registry, then selector
+        // fallback). Arming and the loss check below must agree with it: a name
+        // that also happens to be a live selector (e.g. `'nav'`) must not be
+        // treated as lost while the selector still finds it on screen.
+        if (this._resolveNow(step) === null) {
+            return;
+        }
+        this._recoverySub = this._registry.changes$
+            .pipe(filter((changed) => changed === name), filter(() => this._resolveNow(step) === null), take(1), switchMap(() => {
+            this._emit({ type: 'targetLost', index, step });
+            const grace = this.options.targetLostGrace;
+            return this._registry.waitFor(name, grace).pipe(map(() => 'recovered'), catchError(() => of('lost')));
+        }), tap((outcome) => {
+            if (this._closed) {
+                return;
+            }
+            if (outcome === 'recovered') {
+                this._adapter.refresh();
+                this._emit({ type: 'targetRecovered', index, step });
+                // Re-arm on a microtask: `_onStepPainted` calls `_disarmRecovery`,
+                // which would otherwise unsubscribe this subscription from inside
+                // its own `tap`. Guarded by generation: if the session has moved
+                // on (another `_disarmRecovery()` ran in between — a transition,
+                // or a fresher arm for this same step), this queued re-arm must
+                // not resurrect detection for a step that is no longer active.
+                queueMicrotask(() => {
+                    if (!this._closed && this._recoveryGeneration === generation) {
+                        this._onStepPainted(index, step);
+                    }
+                });
+                return;
+            }
+            this._applyTargetLostPolicy(index, step);
+        }), catchError((err) => {
+            // Swallowed deliberately, not silently: a broken recovery pipeline
+            // must not close a guide the user is actively reading, but it
+            // should still be visible to whoever is developing against it.
+            if (isDevMode()) {
+                console.warn(`TheSeamGuideSession: mid-step recovery for step ${index}` +
+                    ` threw (${String(err)}); recovery detection for this step` +
+                    ' is now disarmed.');
+            }
+            return EMPTY;
+        }))
+            .subscribe();
+    }
+    _applyTargetLostPolicy(index, step) {
+        const policy = step.onTargetLost ?? this.options.onTargetLost;
+        if (policy === 'end') {
+            this.close('targetMissing');
+            return;
+        }
+        if (policy === 'skip') {
+            this._request(index + 1, 1);
+            return;
+        }
+        // 'elementless' — the resolver now returns undefined, so a refresh collapses
+        // the popover to centered without a step transition. This is terminal:
+        // recovery detection was already disarmed on entry to this branch (the
+        // `take(1)` above), and nothing re-arms it afterwards, so if the target
+        // returns later the popover stays centered until the next transition.
+        this._adapter.refresh();
+    }
+    _disarmRecovery() {
+        this._recoveryGeneration++;
+        this._recoverySub?.unsubscribe();
+        this._recoverySub = null;
+    }
+    _runHook(hook) {
+        if (hook === undefined) {
+            return of(null);
+        }
+        return defer(() => {
+            const result = hook();
+            if (result === undefined || result === null) {
+                return of(null);
+            }
+            if (isObservable(result)) {
+                return result.pipe(take(1));
+            }
+            return from(result);
+        });
+    }
+    /** Resolves `'resolved'` or `'missing'`. Never throws. */
+    _resolveTarget(step) {
+        const target = step.element;
+        if (target === undefined) {
+            return of('resolved');
+        }
+        if (typeof target !== 'string') {
+            const el = target instanceof Element ? target : target.nativeElement;
+            return of(el?.isConnected ? 'resolved' : 'missing');
+        }
+        const direct = this._registry.resolve(target);
+        if (direct !== null) {
+            return of('resolved');
+        }
+        const selectorMatch = safeQuerySelector(target);
+        if (selectorMatch !== null) {
+            return of('resolved');
+        }
+        const timeoutMs = step.targetTimeout ?? this.options.targetTimeout;
+        return this._registry.waitFor(target, timeoutMs).pipe(map(() => 'resolved'), catchError(() => of('missing')));
+    }
+    _applyMissPolicy(index, step, direction) {
+        const policy = step.onMissingTarget ?? this.options.onMissingTarget;
+        if (policy === 'end') {
+            this.close('targetMissing');
+            return EMPTY;
+        }
+        if (policy === 'elementless') {
+            this._paint(index, step);
+            return EMPTY;
+        }
+        if (isDevMode()) {
+            console.warn(`TheSeamGuideSession: skipping step ${index} because its target` +
+                ` "${String(step.element)}" never appeared.`);
+        }
+        this._emit({ type: 'stepSkipped', index, step });
+        const nextIndex = index + direction;
+        if (nextIndex < 0 || nextIndex >= this.steps.length) {
+            this.close(direction === 1 ? 'completed' : 'dismissed');
+            return EMPTY;
+        }
+        this._request(nextIndex, direction);
+        return EMPTY;
+    }
+    /** Element is a resolver function so the engine re-resolves at paint time. */
+    _toAdapterStep(step, index) {
+        return {
+            element: step.element === undefined
+                ? undefined
+                : () => this._resolveNow(step) ?? undefined,
+            popover: this._toAdapterPopover(step, index),
+        };
+    }
+    /**
+     * `ExhaustiveMap` makes every key of `TheSeamGuidePopover` required in
+     * `mapped`, so adding a field to the popover is a compile error here until
+     * it is carried through. This is the exact hop on which `side` and `align`
+     * were once silently dropped by a spread.
+     */
+    _toAdapterPopover(step, index) {
+        const slots = this._slots[index];
+        const mapped = {
+            title: slotValue(slots?.title),
+            description: slotValue(slots?.description),
+            side: this._nearestScalar(step, 'side'),
+            align: this._nearestScalar(step, 'align'),
+        };
+        return Object.values(mapped).every((value) => value === undefined)
+            ? undefined
+            : mapped;
+    }
+    _resolveSlot(step, name) {
+        return resolveGuideContentSlot({
+            provider: this._popoverDefaults[name],
+            session: this._sessionPopover?.[name],
+            step: step.popover?.[name],
+        });
+    }
+    _nearestScalar(step, key) {
+        return (step.popover?.[key] ??
+            this._sessionPopover?.[key] ??
+            this._popoverDefaults[key]);
+    }
+    /**
+     * Synchronous best-effort resolution, used by the adapter's live element
+     * resolver at paint time. `_resolveTarget` is the awaiting version used to
+     * gate transitions.
+     */
+    _resolveNow(step) {
+        const target = step.element;
+        if (target === undefined) {
+            return null;
+        }
+        if (typeof target === 'string') {
+            return this._registry.resolve(target) ?? safeQuerySelector(target);
+        }
+        if (target instanceof Element) {
+            return target;
+        }
+        return target.nativeElement;
+    }
+}
+function stripUndefined(config) {
+    const { steps: _steps, popover: _popover, ...rest } = config;
+    const out = {};
+    for (const [key, value] of Object.entries(rest)) {
+        if (value !== undefined) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/** A text slot goes to the engine as a string; a view slot as its host node. */
+function slotValue(binding) {
+    if (binding === null || binding === undefined) {
+        return undefined;
+    }
+    return binding.kind === 'text' ? binding.text : binding.host;
+}
+/** `querySelector` throws on an invalid selector; a registry name often is one. */
+function safeQuerySelector(selector) {
+    try {
+        return document.querySelector(selector);
+    }
+    catch {
+        return null;
+    }
+}
+
+class TheSeamGuideService {
+    _adapter = inject(THE_SEAM_GUIDE_ADAPTER);
+    _registry = inject(TheSeamGuideTargetRegistry);
+    _popoverDefaults = inject(THE_SEAM_GUIDE_POPOVER_DEFAULTS, { optional: true }) ?? {};
+    _contentRenderer = inject(TheSeamGuideDomContentRenderer);
+    _activeGuide = signal(null, ...(ngDevMode ? [{ debugName: "_activeGuide" }] : []));
+    /**
+     * The running guide, or null. Exposed so a caller can queue itself:
+     * `activeGuide()?.afterClosed$.subscribe(() => start(next))`.
+     */
+    activeGuide = this._activeGuide.asReadonly();
+    /**
+     * Starts a guide. One runs at a time: a dismissible active guide is
+     * superseded, a non-dismissible one throws `TheSeamGuideBusyError`.
+     *
+     * The caller owns the returned ref's lifetime. A guide is **not** closed
+     * automatically when the component that started it is destroyed — only
+     * when the root injector is (this service is `providedIn: 'root'`), which
+     * does not happen on ordinary route/component teardown. A component that
+     * starts a guide and may be destroyed before it naturally ends should tie
+     * the ref to its own lifetime:
+     *
+     * ```ts
+     * const ref = this._guide.start(config)
+     * inject(DestroyRef).onDestroy(() => ref.close())
+     * ```
+     */
+    start(config) {
+        const active = this._activeGuide();
+        if (active !== null) {
+            if (!active.dismissible) {
+                throw new TheSeamGuideBusyError();
+            }
+            active.close('superseded');
+        }
+        if (isDevMode() &&
+            config.dismissible === false &&
+            (config.onMissingTarget ?? THE_SEAM_GUIDE_DEFAULTS.onMissingTarget) ===
+                'skip') {
+            console.warn('TheSeamGuideService: this guide sets `dismissible: false` with' +
+                " `onMissingTarget: 'skip'`, so the user is forced through a guide" +
+                ' that may silently drop its own steps. Consider onMissingTarget:' +
+                " 'end' or 'elementless'.");
+        }
+        // eslint-disable-next-line prefer-const -- captured by the closure below before assignment
+        let ref;
+        const session = new TheSeamGuideSession(config, {
+            adapter: this._adapter,
+            registry: this._registry,
+            contentRenderer: this._contentRenderer,
+            popoverDefaults: this._popoverDefaults,
+            getRef: () => ref,
+            onClosed: () => this._clearIfCurrent(ref),
+        });
+        ref = new TheSeamGuideRef(session);
+        this._activeGuide.set(ref);
+        session.start();
+        return ref;
+    }
+    /**
+     * Highlights a single element. A one-step guide.
+     *
+     * As with {@link start}, the caller owns the returned ref's lifetime: it is
+     * not closed automatically when the component that requested it is
+     * destroyed. See {@link start}'s doc comment for the `DestroyRef` pattern.
+     */
+    highlight(step) {
+        return this.start({ steps: [step] });
+    }
+    /**
+     * Closes any active guide when the owning injector is destroyed —
+     * otherwise driver.js's overlay is left in the DOM, and its
+     * `pointer-events: none` blocks every click on the page with no recovery
+     * short of a reload. `close` always works programmatically even when the
+     * guide is `dismissible: false`, which is exactly the case that must not
+     * be left behind.
+     */
+    ngOnDestroy() {
+        this._activeGuide()?.close('destroyed');
+    }
+    _clearIfCurrent(ref) {
+        if (this._activeGuide() === ref) {
+            this._activeGuide.set(null);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideService, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideService, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.15", ngImport: i0, type: TheSeamGuideService, decorators: [{
+            type: Injectable,
+            args: [{ providedIn: 'root' }]
+        }] });
+
+/**
+ * Angular-free renderer for specs. Records what the session asked to render so
+ * a test can assert view lifetime without a `TestBed`.
+ */
+class TheSeamFakeGuideContentRenderer {
+    renders = [];
+    render(slot, context, host) {
+        const record = {
+            slot,
+            context,
+            host,
+            destroyed: false,
+        };
+        this.renders.push(record);
+        host.textContent = context.text ?? '';
+        return {
+            destroy: () => {
+                record.destroyed = true;
+            },
+        };
+    }
+    /** Renders that have not been destroyed. */
+    get live() {
+        return this.renders.filter((r) => !r.destroyed);
+    }
+}
+
+/**
+ * Engine-free adapter for specs. Records what the service asked for and lets a
+ * test simulate user intent without a DOM.
+ */
+class TheSeamFakeGuideAdapter {
+    calls = [];
+    startedConfig = null;
+    _callbacks = null;
+    _active = false;
+    start(config, callbacks) {
+        this.startedConfig = config;
+        this._callbacks = callbacks;
+        this._active = true;
+        this.calls.push('start');
+    }
+    next() {
+        this.calls.push('next');
+    }
+    previous() {
+        this.calls.push('previous');
+    }
+    moveTo(index) {
+        this.calls.push(`moveTo:${index}`);
+    }
+    refresh() {
+        this.calls.push('refresh');
+    }
+    destroy() {
+        this._active = false;
+        // Dropped, not merely inert-by-`_active`: `emitNext`/`emitPrevious`/
+        // `emitClose` call through `_callbacks` directly and do not consult
+        // `_active`, so a stale reference here would still fire callbacks a test
+        // simulates after destroy.
+        this._callbacks = null;
+        this.calls.push('destroy');
+    }
+    isActive() {
+        return this._active;
+    }
+    /** Resolves the element for a step, as the engine would at paint time. */
+    resolveStepElement(index) {
+        return this.startedConfig?.steps[index]?.element?.();
+    }
+    emitNext() {
+        this._callbacks?.onNextRequested();
+    }
+    emitPrevious() {
+        this._callbacks?.onPreviousRequested();
+    }
+    emitClose() {
+        this._callbacks?.onCloseRequested();
+    }
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { THE_SEAM_GUIDE_ADAPTER, THE_SEAM_GUIDE_CONTENT, THE_SEAM_GUIDE_DEFAULTS, THE_SEAM_GUIDE_POPOVER_DEFAULTS, TheSeamFakeGuideAdapter, TheSeamFakeGuideContentRenderer, TheSeamGuideBusyError, TheSeamGuideRef, TheSeamGuideService, TheSeamGuideTargetDirective, TheSeamGuideTargetRegistry, TheSeamGuideTargetTimeoutError, provideTheSeamGuide };
+//# sourceMappingURL=theseam-ui-common-guide.mjs.map