@panyam/tsappkit 0.7.6 → 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 +88 -61
- package/dist/index.d.mts +170 -1
- package/dist/index.d.ts +170 -1
- package/dist/index.js +375 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +375 -3
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
- package/src/index.ts +15 -0
- package/src/tour/Tour.ts +316 -0
- package/src/tour/geometry.ts +113 -0
- package/src/tour/overlay.ts +178 -0
package/README.md
CHANGED
|
@@ -1,98 +1,125 @@
|
|
|
1
1
|
# @panyam/tsappkit
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
|
|
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
|
-
|
|
11
|
+
goapplib and both packages share one version, so goapplib `v0.7.7` goes with `@panyam/tsappkit@0.7.7`.
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
## `@panyam/tsappkit`
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
### Island pages
|
|
16
16
|
|
|
17
|
-
|
|
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
|
-
```
|
|
22
|
-
import {
|
|
19
|
+
```ts
|
|
20
|
+
import { IslandPage, lazy } from "@panyam/tsappkit";
|
|
23
21
|
|
|
24
|
-
class
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
|
|
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
|
-
|
|
35
|
-
|
|
36
|
-
}
|
|
43
|
+
```ts
|
|
44
|
+
import { Port } from "@panyam/tsappkit";
|
|
37
45
|
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
```
|
|
49
|
-
import {
|
|
66
|
+
```ts
|
|
67
|
+
import { BasePage, type LCMComponent } from "@panyam/tsappkit";
|
|
50
68
|
|
|
51
|
-
class
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
69
|
+
class MyPage extends BasePage {
|
|
70
|
+
protected initializeSpecificComponents(): LCMComponent[] {
|
|
71
|
+
return [];
|
|
72
|
+
}
|
|
73
|
+
protected bindSpecificEvents(): void {}
|
|
55
74
|
}
|
|
56
75
|
|
|
57
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
65
|
-
|
|
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
|
-
|
|
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
|
-
|
|
74
|
-
- **KeyboardShortcutManager**: Multi-key keyboard shortcut system with state machine
|
|
96
|
+
See [Guided tours](https://panyam.github.io/goapplib/guide/tour/).
|
|
75
97
|
|
|
76
|
-
|
|
98
|
+
### UI pieces
|
|
77
99
|
|
|
78
|
-
|
|
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
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
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
|
-
|
|
93
|
-
|
|
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
|
-
|
|
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 };
|