@panyam/tsappkit 0.7.6 → 0.7.8
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 +90 -61
- package/dist/index.d.mts +209 -90
- package/dist/index.d.ts +209 -90
- package/dist/index.js +377 -4
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +377 -5
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
- package/src/LCMComponent.ts +24 -77
- package/src/LifecycleController.ts +16 -13
- 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/dist/index.d.ts
CHANGED
|
@@ -97,98 +97,46 @@ type LifecycleEventType = typeof LifecycleEventTypes[keyof typeof LifecycleEvent
|
|
|
97
97
|
type ComponentEventType = typeof ComponentEventTypes[keyof typeof ComponentEventTypes];
|
|
98
98
|
|
|
99
99
|
/**
|
|
100
|
-
*
|
|
100
|
+
* A LifeCycle Managed Component: one that a LifecycleController starts in
|
|
101
|
+
* phases, so a component can rely on every other component being set up
|
|
102
|
+
* before it activates.
|
|
101
103
|
*
|
|
102
|
-
*
|
|
103
|
-
*
|
|
104
|
-
*
|
|
105
|
-
*
|
|
106
|
-
*
|
|
107
|
-
* 2. bindToDOM() - Basic DOM setup, discover child components
|
|
108
|
-
* 3. injectDependencies() - Receive references to other components
|
|
109
|
-
* 4. activate() - Final setup when all dependencies are ready
|
|
110
|
-
*
|
|
111
|
-
* Key Benefits:
|
|
112
|
-
* - Order Independence: Components can be created in any sequence
|
|
113
|
-
* - Async Safety: Each phase waits for all components before proceeding
|
|
114
|
-
* - Clear Dependencies: Explicit injection points prevent race conditions
|
|
115
|
-
* - Error Isolation: Component failures don't cascade to others
|
|
116
|
-
*/
|
|
117
|
-
/**
|
|
118
|
-
* LCM Component - Short for LifeCycle Managed Component
|
|
119
|
-
* enable components to be declared first and their loading be managed by a
|
|
120
|
-
* LifecycleController so that we have layered creation, dependency injection and setup
|
|
121
|
-
* in a breadth first way.
|
|
122
|
-
*
|
|
123
|
-
* A key constraint on LCMComponents are that they should not perform any initialization
|
|
124
|
-
* in the constructor. This is because a LifecycleController should be used to load/setup
|
|
125
|
-
* these components and they will follow a layered approach. Performing these actions in
|
|
126
|
-
* the constructor could violate the idempotency guarantees.
|
|
104
|
+
* Keep the constructor to storing its arguments. The controller decides when
|
|
105
|
+
* the real work happens, phase by phase over the whole tree:
|
|
106
|
+
* performLocalInit, then setupDependencies, then activate. deactivate runs
|
|
107
|
+
* when the controller is torn down, leaves first.
|
|
108
|
+
* See https://panyam.github.io/goapplib/guide/components/.
|
|
127
109
|
*/
|
|
128
110
|
interface LCMComponent {
|
|
129
111
|
/**
|
|
130
|
-
* Phase 1:
|
|
131
|
-
*
|
|
132
|
-
* In this phase the component initializes itself and returns any children it might
|
|
133
|
-
* want initialized as part of the lifecycled loading.
|
|
112
|
+
* Phase 1: set the component itself up, and return its children.
|
|
134
113
|
*
|
|
135
|
-
*
|
|
136
|
-
*
|
|
137
|
-
*
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
* This phase must be synchronous and should not:
|
|
141
|
-
* - Access other components or external dependencies
|
|
142
|
-
* - Perform async operations
|
|
143
|
-
* - Emit events or notifications
|
|
144
|
-
*
|
|
145
|
-
* @returns Array of child components to be managed by lifecycle controller
|
|
114
|
+
* Bind to the DOM and create child components here, without starting
|
|
115
|
+
* them. The children returned become the next level of the tree. Other
|
|
116
|
+
* components may not be set up yet, so don't reach for them. A Promise is
|
|
117
|
+
* awaited before the next component in the level starts.
|
|
146
118
|
*/
|
|
147
119
|
performLocalInit(): Promise<LCMComponent[]> | LCMComponent[];
|
|
148
120
|
/**
|
|
149
|
-
* Phase 2:
|
|
150
|
-
*
|
|
151
|
-
* This phase should:
|
|
152
|
-
* - Receive and store references to required dependencies
|
|
153
|
-
* - Validate that required dependencies are provided
|
|
154
|
-
* - Set up internal state based on dependencies
|
|
121
|
+
* Phase 2: take references to other components.
|
|
155
122
|
*
|
|
156
|
-
*
|
|
157
|
-
*
|
|
158
|
-
*
|
|
159
|
-
*
|
|
160
|
-
*
|
|
161
|
-
* @param deps Record of dependency name to dependency instance
|
|
162
|
-
* @returns Promise<void> or void - can be async
|
|
123
|
+
* Every component in the tree has finished performLocalInit by now, so a
|
|
124
|
+
* parent can hand its children their siblings, or itself. The controller
|
|
125
|
+
* doesn't await a Promise returned here: activate can start before it
|
|
126
|
+
* resolves, so do async work in activate instead.
|
|
163
127
|
*/
|
|
164
128
|
setupDependencies(): Promise<void> | void;
|
|
165
129
|
/**
|
|
166
|
-
* Phase 3:
|
|
167
|
-
*
|
|
168
|
-
* This phase should:
|
|
169
|
-
* - Complete final initialization
|
|
170
|
-
* - Enable component functionality
|
|
171
|
-
* - Start listening for external events
|
|
172
|
-
* - Begin normal operation
|
|
173
|
-
*
|
|
174
|
-
* This phase can be async and may:
|
|
175
|
-
* - Connect to external services
|
|
176
|
-
* - Load initial data
|
|
177
|
-
* - Emit ready notifications
|
|
130
|
+
* Phase 3: start working. Subscribe to events, load data, render.
|
|
178
131
|
*
|
|
179
|
-
*
|
|
132
|
+
* Every component has finished setupDependencies. A level's activate
|
|
133
|
+
* calls run together, and the next level starts once all of them resolve.
|
|
180
134
|
*/
|
|
181
135
|
activate(): Promise<void> | void;
|
|
182
136
|
/**
|
|
183
|
-
*
|
|
184
|
-
*
|
|
185
|
-
*
|
|
186
|
-
* - Stop all ongoing operations
|
|
187
|
-
* - Remove event listeners
|
|
188
|
-
* - Clean up external connections
|
|
189
|
-
* - Dispose of child components
|
|
190
|
-
*
|
|
191
|
-
* @returns Promise<void> or void - can be async
|
|
137
|
+
* Stop working and release what activate took: subscriptions, listeners,
|
|
138
|
+
* connections. LifecycleController.deactivateAll calls it on the children
|
|
139
|
+
* before the parent, so a component doesn't deactivate its children itself.
|
|
192
140
|
*/
|
|
193
141
|
deactivate(): Promise<void> | void;
|
|
194
142
|
}
|
|
@@ -318,19 +266,22 @@ declare abstract class BaseComponent implements Component, LCMComponent, EventSu
|
|
|
318
266
|
}
|
|
319
267
|
|
|
320
268
|
/**
|
|
321
|
-
*
|
|
322
|
-
*
|
|
323
|
-
* This controller implements a breadth-first traversal of the component tree
|
|
324
|
-
* followed by phase-wise initialization with synchronization barriers.
|
|
269
|
+
* Starts a tree of LCMComponents, one phase at a time over the whole tree.
|
|
325
270
|
*
|
|
326
|
-
*
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
*
|
|
330
|
-
*
|
|
271
|
+
* initializeFromRoot runs three phases, and each one finishes for every
|
|
272
|
+
* component before the next one starts:
|
|
273
|
+
* 1. performLocalInit, breadth-first from the root. Each component returns its
|
|
274
|
+
* children, which become the next level. Within a level, one component's
|
|
275
|
+
* call finishes (its Promise included) before the next one's starts.
|
|
276
|
+
* 2. setupDependencies, in the same order. A Promise it returns isn't awaited.
|
|
277
|
+
* 3. activate, level by level. A level's calls run together, and the next
|
|
278
|
+
* level starts once all of them have resolved.
|
|
331
279
|
*
|
|
332
|
-
*
|
|
333
|
-
*
|
|
280
|
+
* deactivateAll runs deactivate the other way, leaves first. A component
|
|
281
|
+
* returned by two parents is an error, and so is a second initializeFromRoot
|
|
282
|
+
* on the same controller. A phase that throws or rejects rejects
|
|
283
|
+
* initializeFromRoot, and the phases after it don't run.
|
|
284
|
+
* See https://panyam.github.io/goapplib/guide/components/.
|
|
334
285
|
*/
|
|
335
286
|
declare class LifecycleController {
|
|
336
287
|
protected eventBus: EventBus;
|
|
@@ -343,8 +294,7 @@ declare class LifecycleController {
|
|
|
343
294
|
* Initialize component tree starting from root component
|
|
344
295
|
*
|
|
345
296
|
* @param rootComponent The root component to start initialization from
|
|
346
|
-
* @
|
|
347
|
-
* @returns Promise that resolves when all components are fully initialized
|
|
297
|
+
* @returns Promise that resolves when every component has activated
|
|
348
298
|
*/
|
|
349
299
|
initializeFromRoot(rootComponent: LCMComponent): Promise<void>;
|
|
350
300
|
/**
|
|
@@ -799,6 +749,175 @@ declare class Port<V> {
|
|
|
799
749
|
get size(): number;
|
|
800
750
|
}
|
|
801
751
|
|
|
752
|
+
/** A rectangle in viewport (client) coordinates. */
|
|
753
|
+
interface Rect {
|
|
754
|
+
x: number;
|
|
755
|
+
y: number;
|
|
756
|
+
width: number;
|
|
757
|
+
height: number;
|
|
758
|
+
}
|
|
759
|
+
|
|
760
|
+
/** The panel's button labels, for an app that isn't in English. */
|
|
761
|
+
interface TourLabels {
|
|
762
|
+
next: string;
|
|
763
|
+
done: string;
|
|
764
|
+
showMe: string;
|
|
765
|
+
close: string;
|
|
766
|
+
}
|
|
767
|
+
|
|
768
|
+
/**
|
|
769
|
+
* What a step lets the reader reach: one element, several (a NodeList or an array), a rectangle in
|
|
770
|
+
* viewport coordinates, or a mix. Each becomes a hole in the overlay. Nothing (null, or an empty
|
|
771
|
+
* list) leaves the whole page dimmed, which is how a target that hasn't rendered yet looks until
|
|
772
|
+
* it does: the tour re-reads `target` every frame.
|
|
773
|
+
*/
|
|
774
|
+
type TourTarget = Element | DOMRectReadOnly | Rect | Iterable<Element | DOMRectReadOnly | Rect> | null | undefined;
|
|
775
|
+
/**
|
|
776
|
+
* An app event, by its name in the app's event map E, with an optional test of its payload. `where`
|
|
777
|
+
* is typed from the event named, so a payload field the event doesn't carry is a type error.
|
|
778
|
+
*/
|
|
779
|
+
type AppTrigger<E> = {
|
|
780
|
+
[K in keyof E & string]: {
|
|
781
|
+
event: K;
|
|
782
|
+
where?: (data: E[K]) => boolean;
|
|
783
|
+
};
|
|
784
|
+
}[keyof E & string];
|
|
785
|
+
/**
|
|
786
|
+
* A DOM event on the step's own target elements, for steps that teach the UI rather than the app
|
|
787
|
+
* (hover for a tooltip, drag a splitter). It matches when an event of this type passes through a
|
|
788
|
+
* target and infers nothing more. It sees nothing on a rectangle target, since a rectangle has no
|
|
789
|
+
* element to pass through.
|
|
790
|
+
*/
|
|
791
|
+
interface DomTrigger {
|
|
792
|
+
dom: keyof HTMLElementEventMap;
|
|
793
|
+
}
|
|
794
|
+
/** Something a step waits for: an app event (`event`) or a DOM event on its target (`dom`). */
|
|
795
|
+
type TourTrigger<E> = AppTrigger<E> | DomTrigger;
|
|
796
|
+
/** One step of a tour, written as data. */
|
|
797
|
+
interface TourStep<E> {
|
|
798
|
+
/** Names the step in callbacks and in the overlay's `data-tour-step`. */
|
|
799
|
+
id: string;
|
|
800
|
+
/** Shown above the text, when given. */
|
|
801
|
+
title?: string;
|
|
802
|
+
/** What the reader should do, or what they're looking at. Set as text, never parsed as HTML. */
|
|
803
|
+
text: string;
|
|
804
|
+
/** The regions the reader can reach during the step. Called every frame while the step is live. */
|
|
805
|
+
target?: () => TourTarget;
|
|
806
|
+
/**
|
|
807
|
+
* What finishes the step. Without one the step is something to look at, and the panel shows Next
|
|
808
|
+
* (Done on the last step).
|
|
809
|
+
*/
|
|
810
|
+
advanceOn?: TourTrigger<E>;
|
|
811
|
+
/**
|
|
812
|
+
* Events that mean the reader went somewhere else. One that matches `offPath` and not
|
|
813
|
+
* `advanceOn` applies `onOffPath`; naming the same event as `advanceOn` without its `where`
|
|
814
|
+
* catches every other payload of it.
|
|
815
|
+
*/
|
|
816
|
+
offPath?: TourTrigger<E> | readonly TourTrigger<E>[];
|
|
817
|
+
/**
|
|
818
|
+
* `"end"` (the default) removes the overlay and leaves the app doing what it does with that
|
|
819
|
+
* input, so the reader has simply left the tour. `"stay"` keeps waiting for `advanceOn`.
|
|
820
|
+
*/
|
|
821
|
+
onOffPath?: "end" | "stay";
|
|
822
|
+
/**
|
|
823
|
+
* Does the step's action for the reader, behind a "Show me" button. It should act through the app
|
|
824
|
+
* as a reader would, so the step still advances on the app's event rather than on the button.
|
|
825
|
+
*/
|
|
826
|
+
doItForMe?: () => void;
|
|
827
|
+
}
|
|
828
|
+
/** Why a tour ended: its last step finished, the reader closed it, or the reader went off path. */
|
|
829
|
+
type TourEndReason = "done" | "cancelled" | "offPath";
|
|
830
|
+
/** Hooks and settings for a tour. */
|
|
831
|
+
interface TourOptions<E> {
|
|
832
|
+
/** Runs as each step goes live, the first one included. */
|
|
833
|
+
onStep?: (step: TourStep<E>, index: number) => void;
|
|
834
|
+
/** Runs once when the tour ends, with the step it was on. */
|
|
835
|
+
onEnd?: (reason: TourEndReason, step: TourStep<E>, index: number) => void;
|
|
836
|
+
/** How far each hole extends past its target, in px. Defaults to 4. */
|
|
837
|
+
padding?: number;
|
|
838
|
+
/** The panel's button labels. */
|
|
839
|
+
labels?: Partial<TourLabels>;
|
|
840
|
+
}
|
|
841
|
+
/**
|
|
842
|
+
* The part of an event bus a tour needs: tsappkit's EventBus has it, and so can anything else.
|
|
843
|
+
*/
|
|
844
|
+
interface TourEventSource {
|
|
845
|
+
on(type: string, handler: (data?: any) => void): void;
|
|
846
|
+
off(type: string, handler: (data?: any) => void): void;
|
|
847
|
+
}
|
|
848
|
+
/**
|
|
849
|
+
* A guided walk over an app in which the reader does each step. The page is dimmed, the step's
|
|
850
|
+
* targets stay reachable through holes in the dimming, and the step advances when the app reports
|
|
851
|
+
* that the reader did the thing: an app event matched by `advanceOn`, not a click inferred from a
|
|
852
|
+
* selector. E is the app's event map (event name to payload), so a step naming an event the app
|
|
853
|
+
* doesn't have, or a payload field the event doesn't carry, fails to compile:
|
|
854
|
+
*
|
|
855
|
+
* interface ViewerEvents { checksRun: void; cellSelected: { table: string; row: number } }
|
|
856
|
+
* const tour = new Tour<ViewerEvents>([
|
|
857
|
+
* { id: "run", text: "Run the checks.", target: () => runButton, advanceOn: { event: "checksRun" } },
|
|
858
|
+
* { id: "cell", text: "Click a part in the first row.", target: () => rows,
|
|
859
|
+
* advanceOn: { event: "cellSelected", where: (d) => d.row === 0 },
|
|
860
|
+
* offPath: { event: "cellSelected" } },
|
|
861
|
+
* ]);
|
|
862
|
+
* tour.attach(bus); // or call tour.notify(type, data) from the app's own channels
|
|
863
|
+
* tour.start();
|
|
864
|
+
*
|
|
865
|
+
* An action the app reports no event for can't be a step, and the fix is an app event rather than
|
|
866
|
+
* a cleverer listener: an action nothing outside the app can observe can't be checked by a tour, a
|
|
867
|
+
* browser test or an agent either. The `dom` trigger is the narrow exception, for steps about the
|
|
868
|
+
* UI itself.
|
|
869
|
+
*
|
|
870
|
+
* Esc and the panel's close button end any tour. Input outside the holes (pointer and wheel) is
|
|
871
|
+
* blocked; keyboard input isn't, so a reader can still Tab to the rest of the page.
|
|
872
|
+
*/
|
|
873
|
+
declare class Tour<E extends object = Record<string, any>> {
|
|
874
|
+
readonly steps: readonly TourStep<E>[];
|
|
875
|
+
private readonly options;
|
|
876
|
+
private at;
|
|
877
|
+
private overlay;
|
|
878
|
+
private frame;
|
|
879
|
+
private domTypes;
|
|
880
|
+
private readonly labels;
|
|
881
|
+
/** @param steps the steps, in order. A tour with no steps never starts. */
|
|
882
|
+
constructor(steps: readonly TourStep<E>[], options?: TourOptions<E>);
|
|
883
|
+
/** Whether the tour is showing a step. */
|
|
884
|
+
get running(): boolean;
|
|
885
|
+
/** The live step's index, or -1 when the tour isn't running. */
|
|
886
|
+
get index(): number;
|
|
887
|
+
/** The live step, or undefined when the tour isn't running. */
|
|
888
|
+
get step(): TourStep<E> | undefined;
|
|
889
|
+
/**
|
|
890
|
+
* Shows the overlay and step `at` (0 by default). On a running tour it moves to that step. A tour
|
|
891
|
+
* can be started again after it ends.
|
|
892
|
+
*/
|
|
893
|
+
start(at?: number): void;
|
|
894
|
+
/** Moves to the next step, or ends the tour as `"done"` after the last one. */
|
|
895
|
+
next(): void;
|
|
896
|
+
/** Removes the overlay and runs `onEnd`. Does nothing on a tour that isn't running. */
|
|
897
|
+
end(reason?: TourEndReason): void;
|
|
898
|
+
/**
|
|
899
|
+
* Tells the tour an app event happened, for an app that keeps its own channels rather than an
|
|
900
|
+
* EventBus. Ignored while the tour isn't running. The live step advances when it matches
|
|
901
|
+
* `advanceOn`, and otherwise applies `onOffPath` when it matches `offPath`. An event whose payload
|
|
902
|
+
* is `void` takes no data.
|
|
903
|
+
*/
|
|
904
|
+
notify<K extends keyof E & string>(type: K, ...data: E[K] extends void ? [data?: E[K]] : [data: E[K]]): void;
|
|
905
|
+
/**
|
|
906
|
+
* Subscribes to every app event any step names (in `advanceOn` or `offPath`) and passes each to
|
|
907
|
+
* `notify`. The subscriptions last until the returned function is called, across ends and
|
|
908
|
+
* restarts; events arriving while the tour isn't running are ignored.
|
|
909
|
+
*/
|
|
910
|
+
attach(source: TourEventSource): () => void;
|
|
911
|
+
private go;
|
|
912
|
+
private seen;
|
|
913
|
+
private listenDom;
|
|
914
|
+
private readonly onDom;
|
|
915
|
+
private readonly onKey;
|
|
916
|
+
private readonly tick;
|
|
917
|
+
private measure;
|
|
918
|
+
private resolve;
|
|
919
|
+
}
|
|
920
|
+
|
|
802
921
|
/**
|
|
803
922
|
* When an island mounts: its `load` in the page spec (goapplib's
|
|
804
923
|
* page.Island.Load), read and waited for. Every strategy mounts once; an
|
|
@@ -1137,4 +1256,4 @@ declare class KeyboardShortcutManager {
|
|
|
1137
1256
|
getCurrentArgs(): string;
|
|
1138
1257
|
}
|
|
1139
1258
|
|
|
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 };
|
|
1259
|
+
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 };
|