@panyam/tsappkit 0.7.7 → 0.7.9

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
@@ -8,7 +8,7 @@ The guides are at https://panyam.github.io/goapplib/. This page lists what's in
8
8
  npm install @panyam/tsappkit
9
9
  ```
10
10
 
11
- goapplib and both packages share one version, so goapplib `v0.7.7` goes with `@panyam/tsappkit@0.7.7`.
11
+ goapplib and the packages share one version, so goapplib `v0.7.9` goes with `@panyam/tsappkit@0.7.9`.
12
12
 
13
13
  ## `@panyam/tsappkit`
14
14
 
@@ -58,7 +58,7 @@ See [One presenter, several islands](https://panyam.github.io/goapplib/guide/isl
58
58
 
59
59
  ### Components and events
60
60
 
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.
61
+ - **`LifecycleController`** starts a tree of components in phases: `performLocalInit` (which returns child components) breadth-first, then `setupDependencies`, then `activate` level by level. Each phase finishes for every component before the next one starts, so the order of the constructor calls doesn't matter.
62
62
  - **`BaseComponent`** is a base class for components that use the `EventBus`.
63
63
  - **`EventBus`** delivers events to subscribers, and an error in one subscriber doesn't stop the rest.
64
64
  - **`BasePage`** is a page built from components. `IslandPage` extends it.
@@ -76,6 +76,8 @@ class MyPage extends BasePage {
76
76
  BasePage.loadAfterPageLoaded("myPage", MyPage, "MyPage");
77
77
  ```
78
78
 
79
+ See [Components and the page lifecycle](https://panyam.github.io/goapplib/guide/components/).
80
+
79
81
  ### Guided tours
80
82
 
81
83
  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:
@@ -118,7 +120,7 @@ For state that survives a reload, a job with a big memory peak (`oneShotFetch`),
118
120
 
119
121
  ## `@panyam/tsappkit/docs`
120
122
 
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).
123
+ 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`. Load the CSS with a `<link>` rather than a script import. See [tsappkit/docs](https://panyam.github.io/goapplib/reference/docs-kit/).
122
124
 
123
125
  ## License
124
126
 
package/dist/index.d.mts 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.
134
- *
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
112
+ * Phase 1: set the component itself up, and return its children.
144
113
  *
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
121
+ * Phase 2: take references to other components.
150
122
  *
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
155
- *
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
  /**
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.
134
- *
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
112
+ * Phase 1: set the component itself up, and return its children.
144
113
  *
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
121
+ * Phase 2: take references to other components.
150
122
  *
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
155
- *
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
  /**
package/dist/index.js CHANGED
@@ -327,8 +327,7 @@ var LifecycleController = class {
327
327
  * Initialize component tree starting from root component
328
328
  *
329
329
  * @param rootComponent The root component to start initialization from
330
- * @param rootName Optional name for the root component (for debugging)
331
- * @returns Promise that resolves when all components are fully initialized
330
+ * @returns Promise that resolves when every component has activated
332
331
  */
333
332
  async initializeFromRoot(rootComponent) {
334
333
  await this.performLocalInit(rootComponent);
@@ -356,6 +355,7 @@ var LifecycleController = class {
356
355
  `Component hierarchy integrity violation: Component '${component.constructor.name}' discovered as child of multiple parents at level ${level}. Component hierarchies must form a tree structure where each component has exactly one parent.`
357
356
  );
358
357
  }
358
+ visited.add(component);
359
359
  this.emitEvent(LifecycleEventTypes.LOCAL_INIT_STARTED, component, level);
360
360
  const result = component.performLocalInit();
361
361
  promises.push(Promise.resolve(result).then((children) => {