@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/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
- * LCMComponent Interface - Defines multi-phase component initialization
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
- * This interface implements a breadth-first lifecycle pattern that eliminates
103
- * initialization order dependencies and race conditions through synchronization barriers.
104
- *
105
- * Lifecycle Phases:
106
- * 1. Construction - Components are created but not initialized
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: The "local" initialization of the component.
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
- * This phase should:
136
- * - Set up basic DOM elements and event listeners
137
- * - Create child components (but don't initialize them) and return them
138
- * - Return array of child components for lifecycle controller discovery
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: Inject dependencies from parent/siblings
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
- * This phase can be async and may:
157
- * - Load external data or resources
158
- * - Perform validation or setup operations
159
- * - Initialize internal components that depend on injected references
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: Activate component when all dependencies are ready
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
- * @returns Promise<void> or void - can be async
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
- * Cleanup phase: Deactivate component and clean up resources
184
- *
185
- * This should:
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
- * LifecycleController - Orchestrates breadth-first component initialization
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
- * Process:
327
- * 1. Discovery Phase: Traverse component tree to find all components
328
- * 2. DOM Binding Phase: All components bind to DOM simultaneously
329
- * 3. Dependency Injection Phase: All components receive dependencies
330
- * 4. Activation Phase: All components complete initialization
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
- * Each phase acts as a synchronization barrier - no component can proceed
333
- * to the next phase until ALL components have completed the current phase.
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
- * @param rootName Optional name for the root component (for debugging)
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 };