@panyam/tsappkit 0.7.5 → 0.7.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,98 +1,125 @@
1
1
  # @panyam/tsappkit
2
2
 
3
- TypeScript application toolkit with component lifecycle management, event system, and UI utilities.
3
+ The browser half of [goapplib](https://github.com/panyam/goapplib), a Go framework for server-rendered pages. It has a component lifecycle and event bus, island pages that mount client code into a page Go rendered, presenter ports, and wasmhost, which runs an app's Go handlers as wasm in a Web Worker. It doesn't depend on a UI framework; [@panyam/tsappkit-solid](https://www.npmjs.com/package/@panyam/tsappkit-solid) adds Solid islands.
4
4
 
5
- ## Installation
5
+ The guides are at https://panyam.github.io/goapplib/. This page lists what's in the package and links to the guide for each part.
6
6
 
7
7
  ```bash
8
8
  npm install @panyam/tsappkit
9
9
  ```
10
10
 
11
- ## Features
11
+ goapplib and both packages share one version, so goapplib `v0.7.7` goes with `@panyam/tsappkit@0.7.7`.
12
12
 
13
- ### Component Lifecycle System
13
+ ## `@panyam/tsappkit`
14
14
 
15
- A sophisticated component lifecycle system that eliminates initialization order dependencies and race conditions:
15
+ ### Island pages
16
16
 
17
- - **LCMComponent**: Lifecycle Managed Component interface with 4-phase initialization
18
- - **LifecycleController**: Breadth-first component orchestration with synchronization barriers
19
- - **BaseComponent**: Abstract base class with event bus integration
17
+ A Go page writes a spec saying which islands go where and when each loads (`eager`, `idle`, `visible` or `media:<query>`). An `IslandPage` reads it and mounts each island from a registry:
20
18
 
21
- ```typescript
22
- import { BaseComponent, LCMComponent, LifecycleController, EventBus } from '@panyam/tsappkit';
19
+ ```ts
20
+ import { IslandPage, lazy } from "@panyam/tsappkit";
23
21
 
24
- class MyComponent extends BaseComponent {
25
- performLocalInit(): LCMComponent[] {
26
- // Phase 1: Initialize and return child components
27
- return [];
28
- }
22
+ class HomePage extends IslandPage<Ctx> {
23
+ protected registry() {
24
+ return {
25
+ player: lazy(() => import("./islands/player")), // default export is the factory
26
+ chat: (el, island, ctx, bus) => new ChatIsland(el, ctx, bus),
27
+ };
28
+ }
29
+ protected makeContext(): Ctx {
30
+ return { api: new ApiClient() };
31
+ }
32
+ }
33
+
34
+ IslandPage.loadAfterPageLoaded("homePage", HomePage, "HomePage");
35
+ ```
36
+
37
+ Also here: `readSpec`, `mountIslands`, `scheduleMount` and `IslandOverlay` (add `?islands` to a page's URL to see each slot labelled). See [Islands](https://panyam.github.io/goapplib/guide/islands/).
38
+
39
+ ### Presenter ports
29
40
 
30
- setupDependencies(): void {
31
- // Phase 2: Receive dependencies
32
- }
41
+ A `Port<V>` lets one presenter drive several views, such as two islands showing the same state. `each` sends a command to every attached view, and the function given to the constructor replays the current state to each view as it attaches, so an island that mounts late catches up:
33
42
 
34
- activate(): void {
35
- // Phase 3: Component is ready
36
- }
43
+ ```ts
44
+ import { Port } from "@panyam/tsappkit";
37
45
 
38
- deactivate(): void {
39
- // Cleanup
40
- }
46
+ class EditorPresenter {
47
+ private color = "red";
48
+ readonly tools = new Port<ToolsView>((v) => v.setColor(this.color));
49
+
50
+ pick(c: string) {
51
+ this.color = c;
52
+ this.tools.each((v) => v.setColor(c));
53
+ }
41
54
  }
42
55
  ```
43
56
 
44
- ### Event System
57
+ See [One presenter, several islands](https://panyam.github.io/goapplib/guide/islands/#one-presenter-several-islands).
58
+
59
+ ### Components and events
45
60
 
46
- Type-safe event bus with error isolation:
61
+ - **`LifecycleController`** runs components through their phases breadth-first: `performLocalInit` (which returns child components), `setupDependencies`, then `activate`. Every component is set up before any activates, so startup order stops mattering.
62
+ - **`BaseComponent`** is a base class for components that use the `EventBus`.
63
+ - **`EventBus`** delivers events to subscribers, and an error in one subscriber doesn't stop the rest.
64
+ - **`BasePage`** is a page built from components. `IslandPage` extends it.
47
65
 
48
- ```typescript
49
- import { EventBus, EventSubscriber } from '@panyam/tsappkit';
66
+ ```ts
67
+ import { BasePage, type LCMComponent } from "@panyam/tsappkit";
50
68
 
51
- class MySubscriber implements EventSubscriber {
52
- handleBusEvent(eventType: string, data: any, subject: any, emitter: any): void {
53
- console.log(`Received ${eventType}:`, data);
54
- }
69
+ class MyPage extends BasePage {
70
+ protected initializeSpecificComponents(): LCMComponent[] {
71
+ return [];
72
+ }
73
+ protected bindSpecificEvents(): void {}
55
74
  }
56
75
 
57
- const eventBus = new EventBus();
58
- eventBus.addSubscription('my-event', null, new MySubscriber());
59
- eventBus.emit('my-event', { value: 42 }, null, this);
76
+ BasePage.loadAfterPageLoaded("myPage", MyPage, "MyPage");
60
77
  ```
61
78
 
62
- ### UI Components
79
+ ### Guided tours
80
+
81
+ A `Tour` walks a reader through an app while they do each step. It dims the page, leaves a hole over each step's targets so input still reaches them, and moves to the next step when the app reports the step's event, not when a click lands on a selector:
63
82
 
64
- - **Modal**: Singleton modal dialog manager with template loading
65
- - **ToastManager**: Toast notification system
66
- - **ThemeManager**: Light/dark/system theme management
67
- - **SplashScreen**: Loading screen with progress updates
68
- - **MobileBottomDrawer**: Swipe-to-close drawer for mobile
69
- - **TemplateLoader**: HTML template loading system
83
+ ```ts
84
+ import { Tour } from "@panyam/tsappkit";
70
85
 
71
- ### Utilities
86
+ interface AppEvents { checksRun: void; findingSelected: { id: string } }
87
+ const tour = new Tour<AppEvents>([
88
+ { id: "run", text: "Run the checks.", target: () => runButton, advanceOn: { event: "checksRun" } },
89
+ { id: "pick", text: "Click F2.", target: () => document.querySelectorAll("#findings li"),
90
+ advanceOn: { event: "findingSelected", where: (d) => d.id === "F2" }, offPath: { event: "findingSelected" } },
91
+ ]);
92
+ tour.attach(bus);
93
+ tour.start();
94
+ ```
72
95
 
73
- - **DOMUtils**: Input context detection, modifier key checks
74
- - **KeyboardShortcutManager**: Multi-key keyboard shortcut system with state machine
96
+ See [Guided tours](https://panyam.github.io/goapplib/guide/tour/).
75
97
 
76
- ## Usage with BasePage
98
+ ### UI pieces
77
99
 
78
- ```typescript
79
- import { BasePage, LCMComponent } from '@panyam/tsappkit';
100
+ `Modal`, `ToastManager`, `ThemeManager` (light, dark or the system's), `SplashScreen`, `MobileBottomDrawer`, `TemplateLoader`, and `KeyboardShortcutManager` for multi-key shortcuts, with `shouldIgnoreShortcut` and the other `DOMUtils` helpers.
80
101
 
81
- class MyPage extends BasePage {
82
- protected initializeSpecificComponents(): LCMComponent[] {
83
- // Initialize page-specific components
84
- return [];
85
- }
86
-
87
- protected bindSpecificEvents(): void {
88
- // Bind page-specific event handlers
89
- }
90
- }
102
+ ## `@panyam/tsappkit/wasmhost`
103
+
104
+ The page side of wasmhost. The Go side builds an app's own HTTP or Connect handler to wasm with `goapplib/wasmhost`, and the page talks to it through a fetch that never reaches the network:
105
+
106
+ ```ts
107
+ import { mountFiles, startWorker, workerFetch } from "@panyam/tsappkit/wasmhost";
91
108
 
92
- // Auto-initialize on DOM ready
93
- BasePage.loadAfterPageLoaded('myPage', MyPage, 'MyPage');
109
+ const worker = await startWorker({ worker: "worker.js", wasm: "app.wasm", exec: "wasm_exec.js", ns: "files" });
110
+ await mountFiles(worker, "docs", { "hello.txt": new TextEncoder().encode("hello") });
111
+ // Any client that takes a fetch works, Connect's included. Only the path and query reach the handler.
112
+ const res = await workerFetch(worker)(location.origin + "/read?path=docs/hello.txt");
94
113
  ```
95
114
 
115
+ The worker script ships prebuilt as `@panyam/tsappkit/wasmhost/worker.js`. Serve it beside your bundle, from the same version as the rest of the package. `addFiles`, `filesFromDrop` and `filesFromFileList` fill the mounts, and `workerMemory` and `workerStats` report the worker's memory and its Go heap. See [Go handlers in a Web Worker](https://panyam.github.io/goapplib/guide/wasmhost/).
116
+
117
+ For state that survives a reload, a job with a big memory peak (`oneShotFetch`), or long jobs on a worker of their own that can be aborted, or replaced when it grows (`startLane`), see [State, heavy jobs and long requests](https://panyam.github.io/goapplib/guide/wasmhost-state/).
118
+
119
+ ## `@panyam/tsappkit/docs`
120
+
121
+ Pieces for documentation sites built with s3gen: `initCodeBlocks` and `CodeBlock` add a copy button to code blocks, `initPageSetup` and `highlightActiveSidebarLink` handle the sidebar, and `ActionCompiler` compiles and runs code typed into an Ace editor (`ace-builds` is an optional peer dependency, needed only for this). The SCSS is in `@panyam/tsappkit/styles/docs/`, and the package ships it compiled as `dist/docs/DocsPage.css`. See [Documentation site best practices](https://github.com/panyam/goapplib/blob/main/tsappkit/docs/BESTPRACTICES.md).
122
+
96
123
  ## License
97
124
 
98
- MIT
125
+ Apache-2.0
package/dist/index.d.mts CHANGED
@@ -799,6 +799,175 @@ declare class Port<V> {
799
799
  get size(): number;
800
800
  }
801
801
 
802
+ /** A rectangle in viewport (client) coordinates. */
803
+ interface Rect {
804
+ x: number;
805
+ y: number;
806
+ width: number;
807
+ height: number;
808
+ }
809
+
810
+ /** The panel's button labels, for an app that isn't in English. */
811
+ interface TourLabels {
812
+ next: string;
813
+ done: string;
814
+ showMe: string;
815
+ close: string;
816
+ }
817
+
818
+ /**
819
+ * What a step lets the reader reach: one element, several (a NodeList or an array), a rectangle in
820
+ * viewport coordinates, or a mix. Each becomes a hole in the overlay. Nothing (null, or an empty
821
+ * list) leaves the whole page dimmed, which is how a target that hasn't rendered yet looks until
822
+ * it does: the tour re-reads `target` every frame.
823
+ */
824
+ type TourTarget = Element | DOMRectReadOnly | Rect | Iterable<Element | DOMRectReadOnly | Rect> | null | undefined;
825
+ /**
826
+ * An app event, by its name in the app's event map E, with an optional test of its payload. `where`
827
+ * is typed from the event named, so a payload field the event doesn't carry is a type error.
828
+ */
829
+ type AppTrigger<E> = {
830
+ [K in keyof E & string]: {
831
+ event: K;
832
+ where?: (data: E[K]) => boolean;
833
+ };
834
+ }[keyof E & string];
835
+ /**
836
+ * A DOM event on the step's own target elements, for steps that teach the UI rather than the app
837
+ * (hover for a tooltip, drag a splitter). It matches when an event of this type passes through a
838
+ * target and infers nothing more. It sees nothing on a rectangle target, since a rectangle has no
839
+ * element to pass through.
840
+ */
841
+ interface DomTrigger {
842
+ dom: keyof HTMLElementEventMap;
843
+ }
844
+ /** Something a step waits for: an app event (`event`) or a DOM event on its target (`dom`). */
845
+ type TourTrigger<E> = AppTrigger<E> | DomTrigger;
846
+ /** One step of a tour, written as data. */
847
+ interface TourStep<E> {
848
+ /** Names the step in callbacks and in the overlay's `data-tour-step`. */
849
+ id: string;
850
+ /** Shown above the text, when given. */
851
+ title?: string;
852
+ /** What the reader should do, or what they're looking at. Set as text, never parsed as HTML. */
853
+ text: string;
854
+ /** The regions the reader can reach during the step. Called every frame while the step is live. */
855
+ target?: () => TourTarget;
856
+ /**
857
+ * What finishes the step. Without one the step is something to look at, and the panel shows Next
858
+ * (Done on the last step).
859
+ */
860
+ advanceOn?: TourTrigger<E>;
861
+ /**
862
+ * Events that mean the reader went somewhere else. One that matches `offPath` and not
863
+ * `advanceOn` applies `onOffPath`; naming the same event as `advanceOn` without its `where`
864
+ * catches every other payload of it.
865
+ */
866
+ offPath?: TourTrigger<E> | readonly TourTrigger<E>[];
867
+ /**
868
+ * `"end"` (the default) removes the overlay and leaves the app doing what it does with that
869
+ * input, so the reader has simply left the tour. `"stay"` keeps waiting for `advanceOn`.
870
+ */
871
+ onOffPath?: "end" | "stay";
872
+ /**
873
+ * Does the step's action for the reader, behind a "Show me" button. It should act through the app
874
+ * as a reader would, so the step still advances on the app's event rather than on the button.
875
+ */
876
+ doItForMe?: () => void;
877
+ }
878
+ /** Why a tour ended: its last step finished, the reader closed it, or the reader went off path. */
879
+ type TourEndReason = "done" | "cancelled" | "offPath";
880
+ /** Hooks and settings for a tour. */
881
+ interface TourOptions<E> {
882
+ /** Runs as each step goes live, the first one included. */
883
+ onStep?: (step: TourStep<E>, index: number) => void;
884
+ /** Runs once when the tour ends, with the step it was on. */
885
+ onEnd?: (reason: TourEndReason, step: TourStep<E>, index: number) => void;
886
+ /** How far each hole extends past its target, in px. Defaults to 4. */
887
+ padding?: number;
888
+ /** The panel's button labels. */
889
+ labels?: Partial<TourLabels>;
890
+ }
891
+ /**
892
+ * The part of an event bus a tour needs: tsappkit's EventBus has it, and so can anything else.
893
+ */
894
+ interface TourEventSource {
895
+ on(type: string, handler: (data?: any) => void): void;
896
+ off(type: string, handler: (data?: any) => void): void;
897
+ }
898
+ /**
899
+ * A guided walk over an app in which the reader does each step. The page is dimmed, the step's
900
+ * targets stay reachable through holes in the dimming, and the step advances when the app reports
901
+ * that the reader did the thing: an app event matched by `advanceOn`, not a click inferred from a
902
+ * selector. E is the app's event map (event name to payload), so a step naming an event the app
903
+ * doesn't have, or a payload field the event doesn't carry, fails to compile:
904
+ *
905
+ * interface ViewerEvents { checksRun: void; cellSelected: { table: string; row: number } }
906
+ * const tour = new Tour<ViewerEvents>([
907
+ * { id: "run", text: "Run the checks.", target: () => runButton, advanceOn: { event: "checksRun" } },
908
+ * { id: "cell", text: "Click a part in the first row.", target: () => rows,
909
+ * advanceOn: { event: "cellSelected", where: (d) => d.row === 0 },
910
+ * offPath: { event: "cellSelected" } },
911
+ * ]);
912
+ * tour.attach(bus); // or call tour.notify(type, data) from the app's own channels
913
+ * tour.start();
914
+ *
915
+ * An action the app reports no event for can't be a step, and the fix is an app event rather than
916
+ * a cleverer listener: an action nothing outside the app can observe can't be checked by a tour, a
917
+ * browser test or an agent either. The `dom` trigger is the narrow exception, for steps about the
918
+ * UI itself.
919
+ *
920
+ * Esc and the panel's close button end any tour. Input outside the holes (pointer and wheel) is
921
+ * blocked; keyboard input isn't, so a reader can still Tab to the rest of the page.
922
+ */
923
+ declare class Tour<E extends object = Record<string, any>> {
924
+ readonly steps: readonly TourStep<E>[];
925
+ private readonly options;
926
+ private at;
927
+ private overlay;
928
+ private frame;
929
+ private domTypes;
930
+ private readonly labels;
931
+ /** @param steps the steps, in order. A tour with no steps never starts. */
932
+ constructor(steps: readonly TourStep<E>[], options?: TourOptions<E>);
933
+ /** Whether the tour is showing a step. */
934
+ get running(): boolean;
935
+ /** The live step's index, or -1 when the tour isn't running. */
936
+ get index(): number;
937
+ /** The live step, or undefined when the tour isn't running. */
938
+ get step(): TourStep<E> | undefined;
939
+ /**
940
+ * Shows the overlay and step `at` (0 by default). On a running tour it moves to that step. A tour
941
+ * can be started again after it ends.
942
+ */
943
+ start(at?: number): void;
944
+ /** Moves to the next step, or ends the tour as `"done"` after the last one. */
945
+ next(): void;
946
+ /** Removes the overlay and runs `onEnd`. Does nothing on a tour that isn't running. */
947
+ end(reason?: TourEndReason): void;
948
+ /**
949
+ * Tells the tour an app event happened, for an app that keeps its own channels rather than an
950
+ * EventBus. Ignored while the tour isn't running. The live step advances when it matches
951
+ * `advanceOn`, and otherwise applies `onOffPath` when it matches `offPath`. An event whose payload
952
+ * is `void` takes no data.
953
+ */
954
+ notify<K extends keyof E & string>(type: K, ...data: E[K] extends void ? [data?: E[K]] : [data: E[K]]): void;
955
+ /**
956
+ * Subscribes to every app event any step names (in `advanceOn` or `offPath`) and passes each to
957
+ * `notify`. The subscriptions last until the returned function is called, across ends and
958
+ * restarts; events arriving while the tour isn't running are ignored.
959
+ */
960
+ attach(source: TourEventSource): () => void;
961
+ private go;
962
+ private seen;
963
+ private listenDom;
964
+ private readonly onDom;
965
+ private readonly onKey;
966
+ private readonly tick;
967
+ private measure;
968
+ private resolve;
969
+ }
970
+
802
971
  /**
803
972
  * When an island mounts: its `load` in the page spec (goapplib's
804
973
  * page.Island.Load), read and waited for. Every strategy mounts once; an
@@ -1137,4 +1306,4 @@ declare class KeyboardShortcutManager {
1137
1306
  getCurrentArgs(): string;
1138
1307
  }
1139
1308
 
1140
- export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandOverlay, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, Port, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };
1309
+ export { type AppTrigger, BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, type DomTrigger, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandOverlay, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, Port, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, Tour, type TourEndReason, type TourEventSource, type TourLabels, type TourOptions, type Rect as TourRect, type TourStep, type TourTarget, type TourTrigger, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };
package/dist/index.d.ts CHANGED
@@ -799,6 +799,175 @@ declare class Port<V> {
799
799
  get size(): number;
800
800
  }
801
801
 
802
+ /** A rectangle in viewport (client) coordinates. */
803
+ interface Rect {
804
+ x: number;
805
+ y: number;
806
+ width: number;
807
+ height: number;
808
+ }
809
+
810
+ /** The panel's button labels, for an app that isn't in English. */
811
+ interface TourLabels {
812
+ next: string;
813
+ done: string;
814
+ showMe: string;
815
+ close: string;
816
+ }
817
+
818
+ /**
819
+ * What a step lets the reader reach: one element, several (a NodeList or an array), a rectangle in
820
+ * viewport coordinates, or a mix. Each becomes a hole in the overlay. Nothing (null, or an empty
821
+ * list) leaves the whole page dimmed, which is how a target that hasn't rendered yet looks until
822
+ * it does: the tour re-reads `target` every frame.
823
+ */
824
+ type TourTarget = Element | DOMRectReadOnly | Rect | Iterable<Element | DOMRectReadOnly | Rect> | null | undefined;
825
+ /**
826
+ * An app event, by its name in the app's event map E, with an optional test of its payload. `where`
827
+ * is typed from the event named, so a payload field the event doesn't carry is a type error.
828
+ */
829
+ type AppTrigger<E> = {
830
+ [K in keyof E & string]: {
831
+ event: K;
832
+ where?: (data: E[K]) => boolean;
833
+ };
834
+ }[keyof E & string];
835
+ /**
836
+ * A DOM event on the step's own target elements, for steps that teach the UI rather than the app
837
+ * (hover for a tooltip, drag a splitter). It matches when an event of this type passes through a
838
+ * target and infers nothing more. It sees nothing on a rectangle target, since a rectangle has no
839
+ * element to pass through.
840
+ */
841
+ interface DomTrigger {
842
+ dom: keyof HTMLElementEventMap;
843
+ }
844
+ /** Something a step waits for: an app event (`event`) or a DOM event on its target (`dom`). */
845
+ type TourTrigger<E> = AppTrigger<E> | DomTrigger;
846
+ /** One step of a tour, written as data. */
847
+ interface TourStep<E> {
848
+ /** Names the step in callbacks and in the overlay's `data-tour-step`. */
849
+ id: string;
850
+ /** Shown above the text, when given. */
851
+ title?: string;
852
+ /** What the reader should do, or what they're looking at. Set as text, never parsed as HTML. */
853
+ text: string;
854
+ /** The regions the reader can reach during the step. Called every frame while the step is live. */
855
+ target?: () => TourTarget;
856
+ /**
857
+ * What finishes the step. Without one the step is something to look at, and the panel shows Next
858
+ * (Done on the last step).
859
+ */
860
+ advanceOn?: TourTrigger<E>;
861
+ /**
862
+ * Events that mean the reader went somewhere else. One that matches `offPath` and not
863
+ * `advanceOn` applies `onOffPath`; naming the same event as `advanceOn` without its `where`
864
+ * catches every other payload of it.
865
+ */
866
+ offPath?: TourTrigger<E> | readonly TourTrigger<E>[];
867
+ /**
868
+ * `"end"` (the default) removes the overlay and leaves the app doing what it does with that
869
+ * input, so the reader has simply left the tour. `"stay"` keeps waiting for `advanceOn`.
870
+ */
871
+ onOffPath?: "end" | "stay";
872
+ /**
873
+ * Does the step's action for the reader, behind a "Show me" button. It should act through the app
874
+ * as a reader would, so the step still advances on the app's event rather than on the button.
875
+ */
876
+ doItForMe?: () => void;
877
+ }
878
+ /** Why a tour ended: its last step finished, the reader closed it, or the reader went off path. */
879
+ type TourEndReason = "done" | "cancelled" | "offPath";
880
+ /** Hooks and settings for a tour. */
881
+ interface TourOptions<E> {
882
+ /** Runs as each step goes live, the first one included. */
883
+ onStep?: (step: TourStep<E>, index: number) => void;
884
+ /** Runs once when the tour ends, with the step it was on. */
885
+ onEnd?: (reason: TourEndReason, step: TourStep<E>, index: number) => void;
886
+ /** How far each hole extends past its target, in px. Defaults to 4. */
887
+ padding?: number;
888
+ /** The panel's button labels. */
889
+ labels?: Partial<TourLabels>;
890
+ }
891
+ /**
892
+ * The part of an event bus a tour needs: tsappkit's EventBus has it, and so can anything else.
893
+ */
894
+ interface TourEventSource {
895
+ on(type: string, handler: (data?: any) => void): void;
896
+ off(type: string, handler: (data?: any) => void): void;
897
+ }
898
+ /**
899
+ * A guided walk over an app in which the reader does each step. The page is dimmed, the step's
900
+ * targets stay reachable through holes in the dimming, and the step advances when the app reports
901
+ * that the reader did the thing: an app event matched by `advanceOn`, not a click inferred from a
902
+ * selector. E is the app's event map (event name to payload), so a step naming an event the app
903
+ * doesn't have, or a payload field the event doesn't carry, fails to compile:
904
+ *
905
+ * interface ViewerEvents { checksRun: void; cellSelected: { table: string; row: number } }
906
+ * const tour = new Tour<ViewerEvents>([
907
+ * { id: "run", text: "Run the checks.", target: () => runButton, advanceOn: { event: "checksRun" } },
908
+ * { id: "cell", text: "Click a part in the first row.", target: () => rows,
909
+ * advanceOn: { event: "cellSelected", where: (d) => d.row === 0 },
910
+ * offPath: { event: "cellSelected" } },
911
+ * ]);
912
+ * tour.attach(bus); // or call tour.notify(type, data) from the app's own channels
913
+ * tour.start();
914
+ *
915
+ * An action the app reports no event for can't be a step, and the fix is an app event rather than
916
+ * a cleverer listener: an action nothing outside the app can observe can't be checked by a tour, a
917
+ * browser test or an agent either. The `dom` trigger is the narrow exception, for steps about the
918
+ * UI itself.
919
+ *
920
+ * Esc and the panel's close button end any tour. Input outside the holes (pointer and wheel) is
921
+ * blocked; keyboard input isn't, so a reader can still Tab to the rest of the page.
922
+ */
923
+ declare class Tour<E extends object = Record<string, any>> {
924
+ readonly steps: readonly TourStep<E>[];
925
+ private readonly options;
926
+ private at;
927
+ private overlay;
928
+ private frame;
929
+ private domTypes;
930
+ private readonly labels;
931
+ /** @param steps the steps, in order. A tour with no steps never starts. */
932
+ constructor(steps: readonly TourStep<E>[], options?: TourOptions<E>);
933
+ /** Whether the tour is showing a step. */
934
+ get running(): boolean;
935
+ /** The live step's index, or -1 when the tour isn't running. */
936
+ get index(): number;
937
+ /** The live step, or undefined when the tour isn't running. */
938
+ get step(): TourStep<E> | undefined;
939
+ /**
940
+ * Shows the overlay and step `at` (0 by default). On a running tour it moves to that step. A tour
941
+ * can be started again after it ends.
942
+ */
943
+ start(at?: number): void;
944
+ /** Moves to the next step, or ends the tour as `"done"` after the last one. */
945
+ next(): void;
946
+ /** Removes the overlay and runs `onEnd`. Does nothing on a tour that isn't running. */
947
+ end(reason?: TourEndReason): void;
948
+ /**
949
+ * Tells the tour an app event happened, for an app that keeps its own channels rather than an
950
+ * EventBus. Ignored while the tour isn't running. The live step advances when it matches
951
+ * `advanceOn`, and otherwise applies `onOffPath` when it matches `offPath`. An event whose payload
952
+ * is `void` takes no data.
953
+ */
954
+ notify<K extends keyof E & string>(type: K, ...data: E[K] extends void ? [data?: E[K]] : [data: E[K]]): void;
955
+ /**
956
+ * Subscribes to every app event any step names (in `advanceOn` or `offPath`) and passes each to
957
+ * `notify`. The subscriptions last until the returned function is called, across ends and
958
+ * restarts; events arriving while the tour isn't running are ignored.
959
+ */
960
+ attach(source: TourEventSource): () => void;
961
+ private go;
962
+ private seen;
963
+ private listenDom;
964
+ private readonly onDom;
965
+ private readonly onKey;
966
+ private readonly tick;
967
+ private measure;
968
+ private resolve;
969
+ }
970
+
802
971
  /**
803
972
  * When an island mounts: its `load` in the page spec (goapplib's
804
973
  * page.Island.Load), read and waited for. Every strategy mounts once; an
@@ -1137,4 +1306,4 @@ declare class KeyboardShortcutManager {
1137
1306
  getCurrentArgs(): string;
1138
1307
  }
1139
1308
 
1140
- export { BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandOverlay, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, Port, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };
1309
+ export { type AppTrigger, BaseComponent, BasePage, type Component, type ComponentEventType, ComponentEventTypes, type ComponentLifecycleEvent, type DomTrigger, EventBus, type EventHandler, type EventSubscriber, type IslandFactory, IslandOverlay, IslandPage, type IslandSpec, KeyboardShortcutManager, KeyboardState, type LCMComponent, type LCMComponentConfig, type LCMComponentEvent, type LazyIsland, LifecycleController, type LifecycleEventType, LifecycleEventTypes, type LoadEnv, type LoadStrategy, MobileBottomDrawer, Modal, type MountOptions, type PageSpec, Port, type Registry, SPEC_ELEMENT_ID, type ShortcutConfig, type ShortcutManagerConfig, type SpecExtension, SplashScreen, TemplateLoader, ThemeManager, ToastManager, Tour, type TourEndReason, type TourEventSource, type TourLabels, type TourOptions, type Rect as TourRect, type TourStep, type TourTarget, type TourTrigger, hasModifierKeys, isInInputContext, lazy, mountIslands, parseLoad, readSpec, scheduleMount, shouldIgnoreShortcut };