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

package/guide/index.d.ts

@@ -0,0 +1,474 @@
+import * as i0 from '@angular/core';
+import { Signal, TemplateRef, Type, InjectionToken, ElementRef, OnDestroy, EnvironmentProviders } from '@angular/core';
+import { Observable } from 'rxjs';
+
+type TheSeamGuideCloseReason = 'completed' | 'dismissed' | 'targetMissing' | 'superseded' | 'destroyed';
+interface TheSeamGuideResult {
+    reason: TheSeamGuideCloseReason;
+    /** Index of the step that was active when the guide closed, or -1. */
+    lastIndex: number;
+}
+type TheSeamGuideEvent = {
+    type: 'started';
+} | {
+    type: 'stepChanged';
+    index: number;
+    step: TheSeamGuideStep;
+} | {
+    type: 'stepSkipped';
+    index: number;
+    step: TheSeamGuideStep;
+} | {
+    type: 'targetLost';
+    index: number;
+    step: TheSeamGuideStep;
+} | {
+    type: 'targetRecovered';
+    index: number;
+    step: TheSeamGuideStep;
+} | {
+    type: 'closed';
+    result: TheSeamGuideResult;
+};
+
+/**
+ * The contract between a {@link TheSeamGuideRef} and the session backing it.
+ * `TheSeamGuideRef` delegates every member to an implementation of this
+ * interface, so it never depends on `TheSeamGuideSession` directly.
+ */
+interface TheSeamGuideSessionController {
+    /**
+     * Replays every event emitted so far for this guide, from `started`
+     * onward, to each new subscriber — so attaching at any point yields the
+     * complete history rather than only future events.
+     */
+    readonly events$: Observable<TheSeamGuideEvent>;
+    readonly afterClosed$: Observable<TheSeamGuideResult>;
+    readonly activeIndex: Signal<number>;
+    readonly dismissible: boolean;
+    next(): void;
+    previous(): void;
+    moveTo(index: number): void;
+    refresh(): void;
+    close(reason: TheSeamGuideCloseReason): void;
+}
+/**
+ * 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())
+ * ```
+ */
+declare class TheSeamGuideRef {
+    private readonly _session;
+    constructor(_session: TheSeamGuideSessionController);
+    /**
+     * 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$(): Observable<TheSeamGuideEvent>;
+    get afterClosed$(): Observable<TheSeamGuideResult>;
+    get activeIndex(): Signal<number>;
+    /** Whether the user may dismiss this guide. Read by the service's concurrency rule. */
+    get dismissible(): boolean;
+    next(): void;
+    previous(): void;
+    moveTo(index: number): void;
+    refresh(): void;
+    /** Always works, including when `dismissible` is false. */
+    close(reason?: TheSeamGuideCloseReason): void;
+}
+
+/**
+ * Application-defined values handed to popover content.
+ *
+ * The library reserves **no keys** here. That is why `text` is a sibling field
+ * on the content spec rather than a well-known key in this bag: an application
+ * can name its data anything without colliding with the guide.
+ */
+type TheSeamGuideContentData = Record<string, unknown>;
+interface TheSeamGuideContentBase {
+    /** The slot's plain text. A bare string is sugar for this. Nearest-wins. */
+    text?: string;
+    /** Shallow-merged across provider -> session -> step. */
+    data?: TheSeamGuideContentData;
+}
+interface TheSeamGuideTemplateContent extends TheSeamGuideContentBase {
+    template: TemplateRef<TheSeamGuideContentContext>;
+    component?: never;
+}
+interface TheSeamGuideComponentContent extends TheSeamGuideContentBase {
+    component: Type<unknown>;
+    template?: never;
+}
+/** Text and/or data for whichever renderer an outer layer supplies. */
+interface TheSeamGuideInheritedContent extends TheSeamGuideContentBase {
+    template?: never;
+    component?: never;
+}
+/**
+ * The `never` guards make `template` and `component` on one object a compile
+ * error, rather than a runtime precedence rule nobody remembers.
+ */
+type TheSeamGuideContentSpec = TheSeamGuideTemplateContent | TheSeamGuideComponentContent | TheSeamGuideInheritedContent;
+type TheSeamGuideContent = string | TheSeamGuideContentSpec;
+/**
+ * What popover content receives. Templates get this as their context;
+ * components get it from {@link THE_SEAM_GUIDE_CONTENT}.
+ *
+ * `data` is never spread, so `let-index` is unambiguously the step index and
+ * never an application value.
+ */
+interface TheSeamGuideContentContext {
+    /** `data`, so `let-d` in a template reads `d.icon`. */
+    $implicit: TheSeamGuideContentData;
+    data: TheSeamGuideContentData;
+    text: string | undefined;
+    step: TheSeamGuideStep;
+    index: number;
+    total: number;
+    guide: TheSeamGuideRef;
+}
+/** Injected by a component used as popover content. */
+declare const THE_SEAM_GUIDE_CONTENT: InjectionToken<TheSeamGuideContentContext>;
+/** One popover slot after its three layers are resolved. */
+type TheSeamGuideResolvedSlot = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'template';
+    template: TemplateRef<TheSeamGuideContentContext>;
+    text: string | undefined;
+    data: TheSeamGuideContentData;
+} | {
+    kind: 'component';
+    component: Type<unknown>;
+    text: string | undefined;
+    data: TheSeamGuideContentData;
+};
+/** A resolved slot that needs an Angular view. */
+type TheSeamGuideViewSlot = Exclude<TheSeamGuideResolvedSlot, {
+    kind: 'text';
+}>;
+/** A rendered slot. Destroying it tears the view down. */
+interface TheSeamGuideContentView {
+    destroy(): void;
+}
+/**
+ * Published so `testing/` can fake it, exactly as `TheSeamGuideAdapter` is.
+ * The DOM implementation itself is internal.
+ */
+interface TheSeamGuideContentRenderer {
+    render(slot: TheSeamGuideViewSlot, context: TheSeamGuideContentContext, host: HTMLElement): TheSeamGuideContentView;
+}
+
+/** What to do when a step's target element cannot be resolved. */
+type TheSeamGuideMissPolicy = 'skip' | 'elementless' | 'end';
+interface TheSeamGuidePopover {
+    /**
+     * A string, a `TemplateRef`, or a standalone component.
+     *
+     * Omitting inherits from the guide and application layers. `null` opts this
+     * step out of a slot the guide layer supplies — omission cannot express
+     * that, because omission means "inherit".
+     */
+    title?: TheSeamGuideContent | null;
+    description?: TheSeamGuideContent | null;
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    align?: 'start' | 'center' | 'end';
+}
+interface TheSeamGuideStep {
+    /**
+     * Target for this step. Omit for an elementless (centered) step.
+     *
+     * A string is resolved against the target registry first, then falls back to
+     * `document.querySelector`. Only registry-resolved targets get mid-step
+     * recovery.
+     */
+    element?: string | Element | ElementRef<Element>;
+    popover?: TheSeamGuidePopover;
+    /** Overrides the guide-level value for this step. */
+    targetTimeout?: number;
+    /** Overrides the guide-level policy. `'end'` marks this step required. */
+    onMissingTarget?: TheSeamGuideMissPolicy;
+    /** Overrides the guide-level mid-step loss policy. */
+    onTargetLost?: TheSeamGuideMissPolicy;
+    /**
+     * Runs before this step paints. An Observable result must **emit**, not
+     * merely complete — the transition waits for the first emission and an
+     * Observable that completes without ever emitting will hang it forever.
+     */
+    beforeStep?: () => void | Promise<void> | Observable<unknown>;
+    /**
+     * Runs after this step is left. An Observable result must **emit**, not
+     * merely complete — the transition waits for the first emission and an
+     * Observable that completes without ever emitting will hang it forever.
+     */
+    afterStep?: () => void | Promise<void> | Observable<unknown>;
+}
+
+interface TheSeamGuideConfig {
+    steps: TheSeamGuideStep[];
+    /** User may dismiss via Escape, overlay click, or close button. Default true. */
+    dismissible?: boolean;
+    /** Milliseconds to wait for a target before the miss policy applies. Default 3000. */
+    targetTimeout?: number;
+    /** Guide-level miss policy, applied at step entry. Default 'skip'. */
+    onMissingTarget?: TheSeamGuideMissPolicy;
+    /**
+     * Milliseconds to wait for a target to return after it disappears mid-step,
+     * before `onTargetLost` applies. Default 1000.
+     */
+    targetLostGrace?: number;
+    /** Policy for a target lost mid-step. Default 'elementless'. */
+    onTargetLost?: TheSeamGuideMissPolicy;
+    /**
+     * Popover defaults for every step in this guide — the middle content layer.
+     * Decorates slots a step supplies, and can supply a slot itself; a step
+     * opts out of one with `null`.
+     */
+    popover?: TheSeamGuidePopover;
+}
+type TheSeamGuideResolvedConfig = Required<Omit<TheSeamGuideConfig, 'steps' | 'popover'>>;
+declare const THE_SEAM_GUIDE_DEFAULTS: TheSeamGuideResolvedConfig;
+
+declare class TheSeamGuideBusyError extends Error {
+    constructor();
+}
+declare class TheSeamGuideTargetTimeoutError extends Error {
+    readonly targetName: string;
+    constructor(targetName: string);
+}
+
+/**
+ * Tracks elements registered by `[seamGuideTarget]` so a guide can await a
+ * target that does not exist yet, and notice one that disappears.
+ */
+declare class TheSeamGuideTargetRegistry {
+    private readonly _targets;
+    private readonly _changes;
+    /** Emits the target name whenever its registrations change. */
+    readonly changes$: Observable<string>;
+    register(name: string, element: Element): void;
+    unregister(name: string, element: Element): void;
+    /** The most recently registered element for `name` that is still in the DOM. */
+    resolve(name: string): Element | null;
+    /** Emits as soon as `name` resolves. Errors with a timeout error otherwise. */
+    waitFor(name: string, timeoutMs: number): Observable<Element>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TheSeamGuideTargetRegistry, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<TheSeamGuideTargetRegistry>;
+}
+
+/**
+ * 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.
+ */
+declare class TheSeamGuideTargetDirective implements OnDestroy {
+    private readonly _registry;
+    private readonly _elementRef;
+    readonly seamGuideTarget: i0.InputSignal<string>;
+    private _registeredName;
+    constructor();
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TheSeamGuideTargetDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<TheSeamGuideTargetDirective, "[seamGuideTarget]", never, { "seamGuideTarget": { "alias": "seamGuideTarget"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * A popover as the presentation engine sees it.
+ *
+ * `HTMLElement` carries template and component content. The service creates,
+ * owns, and destroys that node; the adapter only places it, which is what
+ * keeps the adapter free of Angular.
+ *
+ * **An `HTMLElement` slot must be re-adopted on every re-render — never
+ * cloned, never wrapped in a fresh element, never rebuilt from its
+ * `outerHTML`.** The engine may tear down and rebuild its whole popover DOM
+ * on every render (driver.js does, including on the re-drive behind
+ * `refresh()`), but the identical node handed in here must end up back in
+ * the new DOM each time. Re-adoption of that exact node is what lets the
+ * Angular view living inside it survive untouched across a rebuild —
+ * preserving scroll position, a typed-in value, or an in-flight animation
+ * instead of resetting it.
+ */
+interface TheSeamGuideAdapterPopover {
+    title?: string | HTMLElement;
+    description?: string | HTMLElement;
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    align?: 'start' | 'center' | 'end';
+}
+/**
+ * A step as the presentation engine sees it.
+ *
+ * `element` is a resolver function, not an element, so the engine re-resolves
+ * at paint time. That is what makes mid-step recovery a `refresh()` rather than
+ * a step transition.
+ */
+interface TheSeamGuideAdapterStep {
+    element?: () => Element | undefined;
+    popover?: TheSeamGuideAdapterPopover;
+}
+interface TheSeamGuideAdapterConfig {
+    steps: TheSeamGuideAdapterStep[];
+    /** When false, Escape, overlay click, and the close button must not dismiss. */
+    allowUserDismiss: boolean;
+}
+/** How the engine reports user intent. It never advances itself. */
+interface TheSeamGuideAdapterCallbacks {
+    onNextRequested(): void;
+    onPreviousRequested(): void;
+    onCloseRequested(): void;
+}
+interface TheSeamGuideAdapter {
+    start(config: TheSeamGuideAdapterConfig, callbacks: TheSeamGuideAdapterCallbacks): void;
+    next(): void;
+    previous(): void;
+    moveTo(index: number): void;
+    /**
+     * Re-resolves and repositions the current step in place, without a step
+     * transition. This is the operation mid-step recovery depends on.
+     *
+     * **Must re-invoke the current step's element resolver** (the function on
+     * `TheSeamGuideAdapterStep.element`), not merely reposition around a
+     * previously-resolved element. An implementation that only repositions
+     * passes every session-layer spec — the session never observes the
+     * difference directly — but silently keeps highlighting a detached element
+     * during recovery while still reporting `targetRecovered`. driver.js's own
+     * `refresh()` has exactly this bug, which is why the driver.js adapter does
+     * not call it and instead re-drives the current index to force
+     * re-resolution.
+     */
+    refresh(): void;
+    destroy(): void;
+    isActive(): boolean;
+}
+declare const THE_SEAM_GUIDE_ADAPTER: InjectionToken<TheSeamGuideAdapter>;
+
+declare class TheSeamGuideService implements OnDestroy {
+    private readonly _adapter;
+    private readonly _registry;
+    private readonly _popoverDefaults;
+    private readonly _contentRenderer;
+    private readonly _activeGuide;
+    /**
+     * The running guide, or null. Exposed so a caller can queue itself:
+     * `activeGuide()?.afterClosed$.subscribe(() => start(next))`.
+     */
+    readonly activeGuide: Signal<TheSeamGuideRef | null>;
+    /**
+     * 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: TheSeamGuideConfig): TheSeamGuideRef;
+    /**
+     * 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: TheSeamGuideStep): TheSeamGuideRef;
+    /**
+     * 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(): void;
+    private _clearIfCurrent;
+    static ɵfac: i0.ɵɵFactoryDeclaration<TheSeamGuideService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<TheSeamGuideService>;
+}
+
+/**
+ * Application-wide popover defaults — the outermost of the three content
+ * layers. Always provided by {@link provideTheSeamGuide}, defaulting to `{}`.
+ */
+declare const THE_SEAM_GUIDE_POPOVER_DEFAULTS: InjectionToken<TheSeamGuidePopover>;
+interface TheSeamGuideProviderOptions {
+    /** Replace the presentation engine. Defaults to the driver.js adapter. */
+    adapter?: Type<TheSeamGuideAdapter>;
+    /**
+     * Popover defaults for every guide in the application. This layer decorates
+     * slots that a guide or a step supplies; it never creates one.
+     */
+    popover?: TheSeamGuidePopover;
+}
+/**
+ * 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.
+ */
+declare function provideTheSeamGuide(options?: TheSeamGuideProviderOptions): EnvironmentProviders;
+
+interface TheSeamFakeGuideContentRender {
+    slot: TheSeamGuideViewSlot;
+    context: TheSeamGuideContentContext;
+    host: HTMLElement;
+    destroyed: boolean;
+}
+/**
+ * Angular-free renderer for specs. Records what the session asked to render so
+ * a test can assert view lifetime without a `TestBed`.
+ */
+declare class TheSeamFakeGuideContentRenderer implements TheSeamGuideContentRenderer {
+    readonly renders: TheSeamFakeGuideContentRender[];
+    render(slot: TheSeamGuideViewSlot, context: TheSeamGuideContentContext, host: HTMLElement): TheSeamGuideContentView;
+    /** Renders that have not been destroyed. */
+    get live(): TheSeamFakeGuideContentRender[];
+}
+
+/**
+ * Engine-free adapter for specs. Records what the service asked for and lets a
+ * test simulate user intent without a DOM.
+ */
+declare class TheSeamFakeGuideAdapter implements TheSeamGuideAdapter {
+    readonly calls: string[];
+    startedConfig: TheSeamGuideAdapterConfig | null;
+    private _callbacks;
+    private _active;
+    start(config: TheSeamGuideAdapterConfig, callbacks: TheSeamGuideAdapterCallbacks): void;
+    next(): void;
+    previous(): void;
+    moveTo(index: number): void;
+    refresh(): void;
+    destroy(): void;
+    isActive(): boolean;
+    /** Resolves the element for a step, as the engine would at paint time. */
+    resolveStepElement(index: number): Element | undefined;
+    emitNext(): void;
+    emitPrevious(): void;
+    emitClose(): void;
+}
+
+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 };
+export type { TheSeamFakeGuideContentRender, TheSeamGuideAdapter, TheSeamGuideAdapterCallbacks, TheSeamGuideAdapterConfig, TheSeamGuideAdapterPopover, TheSeamGuideAdapterStep, TheSeamGuideCloseReason, TheSeamGuideComponentContent, TheSeamGuideConfig, TheSeamGuideContent, TheSeamGuideContentBase, TheSeamGuideContentContext, TheSeamGuideContentData, TheSeamGuideContentRenderer, TheSeamGuideContentSpec, TheSeamGuideContentView, TheSeamGuideEvent, TheSeamGuideInheritedContent, TheSeamGuideMissPolicy, TheSeamGuidePopover, TheSeamGuideProviderOptions, TheSeamGuideResolvedConfig, TheSeamGuideResolvedSlot, TheSeamGuideResult, TheSeamGuideSessionController, TheSeamGuideStep, TheSeamGuideTemplateContent, TheSeamGuideViewSlot };

package/guide/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/theseam-ui-common-guide.mjs"
+}

package/guide/styles/_utilities.scss

@@ -0,0 +1,4 @@
+// Variables, functions, and mixins only. Must not emit CSS.
+@import '../../styles/utilities';
+
+@import './variables';

package/guide/styles/_variables.scss

@@ -0,0 +1,6 @@
+$seam-guide-popover-bg: $white !default;
+$seam-guide-popover-color: $body-color !default;
+$seam-guide-popover-border-radius: $border-radius !default;
+$seam-guide-popover-max-width: 20rem !default;
+$seam-guide-overlay-color: rgba(0, 0, 0, 0.6) !default;
+$seam-guide-overlay-opacity: 0.7 !default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theseam/ui-common",
-  "version": "2.0.1-beta.101",
+  "version": "2.0.1-beta.104",
   "peerDependencies": {
     "@angular/cdk": "^20.2.3",
     "@angular/common": "^20.3.0",
@@ -8,6 +8,7 @@
     "@angular/forms": "^20.3.0",
     "@angular/animations": "^20.3.0",
     "@angular/router": "^20.3.0",
+    "@angular/google-maps": "^20.2.3",
     "rxjs": "~7.8.0",
     "@fortawesome/angular-fontawesome": "^0.13.0",
     "@fortawesome/fontawesome-svg-core": "^1.2.35",
@@ -24,6 +25,7 @@
     "@types/overlayscrollbars": "~1.7.0",
     "bootstrap": "~4.6.0",
     "css-element-queries": "^1.2.3",
+    "driver.js": "^1.8.0",
     "file-saver": "~2.0.2",
     "graphql": "^16.0.0",
     "ngx-toastr": "~16.1.0",
@@ -43,6 +45,8 @@
     "@turf/kinks": "^7.2.0",
     "shpjs": "^6.2.0",
     "@types/geojson": "^7946.0.8",
+    "terra-draw": "^1.31.2",
+    "terra-draw-google-maps-adapter": "^1.6.1",
     "tslib": "^2.3.0"
   },
   "repository": {
@@ -219,6 +223,10 @@
       "types": "./graphql/index.d.ts",
       "default": "./fesm2022/theseam-ui-common-graphql.mjs"
     },
+    "./guide": {
+      "types": "./guide/index.d.ts",
+      "default": "./fesm2022/theseam-ui-common-guide.mjs"
+    },
     "./icon": {
       "types": "./icon/index.d.ts",
       "default": "./fesm2022/theseam-ui-common-icon.mjs"