@pie-players/pie-section-player 0.3.36 → 0.3.37
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 +67 -0
- package/dist/pie-section-player.js +3340 -3311
- package/package.json +10 -10
package/README.md
CHANGED
|
@@ -32,6 +32,73 @@ entrypoints under `@pie-players/pie-section-player/components/*`.
|
|
|
32
32
|
Standalone browser variants for this package are intentionally deferred; the
|
|
33
33
|
current supported contract is the default bundler entrypoints under `dist`.
|
|
34
34
|
|
|
35
|
+
## SectionController
|
|
36
|
+
|
|
37
|
+
`SectionController` is the domain authority inside a section player. It owns
|
|
38
|
+
in-section navigation state, the canonical aggregation of per-item sessions,
|
|
39
|
+
and the host-facing persistence snapshot. The layout custom elements
|
|
40
|
+
(`pie-section-player-splitpane` / `-vertical` / `-tabbed`) are transport
|
|
41
|
+
adapters around it. See
|
|
42
|
+
[`docs/section-player/controller-boundaries.md`](../../docs/section-player/controller-boundaries.md)
|
|
43
|
+
for the rationale behind that split, and
|
|
44
|
+
[`docs/section-player/client-architecture-tutorial.md`](../../docs/section-player/client-architecture-tutorial.md)
|
|
45
|
+
for the end-to-end walkthrough.
|
|
46
|
+
|
|
47
|
+
The handle implements `SectionControllerHandle` from
|
|
48
|
+
`@pie-players/pie-assessment-toolkit`; see the JSDoc on that interface for
|
|
49
|
+
the per-method contract.
|
|
50
|
+
|
|
51
|
+
### Obtaining the handle
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
const host = document.querySelector("pie-section-player-splitpane") as any;
|
|
55
|
+
const controller = await host.waitForSectionController?.(5000);
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`waitForSectionController(timeoutMs)` resolves when the layout CE has wired
|
|
59
|
+
its controller (the same anchor `pie-stage-change` reaches with
|
|
60
|
+
`detail.stage === "engine-ready"`). Use `getSectionController()` if you've
|
|
61
|
+
already passed the readiness anchor synchronously. The legacy
|
|
62
|
+
`section-controller-ready` event was removed; either of these helpers
|
|
63
|
+
replaces it.
|
|
64
|
+
|
|
65
|
+
### Session lifecycle
|
|
66
|
+
|
|
67
|
+
A typical host flow:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
controller?.configureSessionPersistence?.({ context, strategy });
|
|
71
|
+
await controller?.hydrate?.();
|
|
72
|
+
const unsubscribe = controller?.subscribe?.(handleEvent);
|
|
73
|
+
// ...later, on save / unload:
|
|
74
|
+
await controller?.persist?.();
|
|
75
|
+
unsubscribe?.();
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`getSession()` / `applySession(session, { mode })` / `updateItemSession(itemId,
|
|
79
|
+
detail)` are the direct read/write surfaces and exchange the same
|
|
80
|
+
`SectionControllerSessionState` shape the persistence strategy load/save
|
|
81
|
+
methods receive. See [Item session management](#item-session-management) for
|
|
82
|
+
worked examples.
|
|
83
|
+
|
|
84
|
+
### Event stream
|
|
85
|
+
|
|
86
|
+
The controller's typed event stream (`SectionControllerEvent` discriminated
|
|
87
|
+
union) is the single source of truth for in-section change. Hosts usually
|
|
88
|
+
subscribe through `ToolkitCoordinator.subscribeItemEvents` /
|
|
89
|
+
`subscribeSectionLifecycleEvents` (cohort-aware filtering, survives
|
|
90
|
+
navigation) — see [JS API example for advanced host
|
|
91
|
+
policy](#js-api-example-for-advanced-host-policy). Key event types:
|
|
92
|
+
|
|
93
|
+
- `item-selected` — item navigation within the current section.
|
|
94
|
+
- `item-session-data-changed` / `item-session-meta-changed` — per-item
|
|
95
|
+
session updates the persistence layer should observe.
|
|
96
|
+
- `content-loaded` — passage / item / rubric finished loading.
|
|
97
|
+
- `section-loading-complete` — every renderable in the section finished
|
|
98
|
+
loading.
|
|
99
|
+
- `section-items-complete-changed` — aggregate completion flip.
|
|
100
|
+
- `section-navigation-change` — the controller's section identity changed.
|
|
101
|
+
|
|
35
102
|
## Usage
|
|
36
103
|
|
|
37
104
|
Import the custom-element registration entrypoint in consumers:
|