@panyam/tsappkit 0.7.7 → 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 +5 -3
- package/dist/index.d.mts +39 -89
- package/dist/index.d.ts +39 -89
- package/dist/index.js +2 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
- package/src/LCMComponent.ts +24 -77
- package/src/LifecycleController.ts +16 -13
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
|
|
11
|
+
goapplib and the packages share one version, so goapplib `v0.7.8` goes with `@panyam/tsappkit@0.7.8`.
|
|
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`**
|
|
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`.
|
|
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
|
-
*
|
|
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.
|
|
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
|
-
*
|
|
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:
|
|
121
|
+
* Phase 2: take references to other components.
|
|
150
122
|
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
*
|
|
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:
|
|
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
|
/**
|
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.
|
|
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
|
-
*
|
|
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:
|
|
121
|
+
* Phase 2: take references to other components.
|
|
150
122
|
*
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
*
|
|
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:
|
|
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
|
/**
|
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
|
-
* @
|
|
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) => {
|