Skip to content

Commit f97a2c2

Browse files
bradpottsbradpotts
committed
Add P3 API docs tasks and update roadmap
Expand ROADMAP and TODO to add a blocking P3 section for API documentation required before Phase 4. Documented README examples are specified for meta/afterNavigate (title & a11y), onNavigationStart/onNavigationEnd (loading state), and router.subscribe() (signals bridge). Update Phase/status text, mark several Phase 3 items complete, adjust recommended execution order, and add spectre-init consumer requirements and template checklist. Nested routing remains design-only.
1 parent 6c70176 commit f97a2c2

2 files changed

Lines changed: 113 additions & 17 deletions

File tree

‎ROADMAP.md‎

Lines changed: 36 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -120,8 +120,42 @@ Complete the navigation lifecycle surface for a11y, analytics, and side effects.
120120

121121
#### Nested routing
122122

123-
Design-only until a concrete application need is proven. Evaluate alongside `spectre-ui-astro`
124-
layout patterns before committing to an API.
123+
Design-only until a concrete application need is proven. Evaluate alongside
124+
`spectre-ui-astro` layout patterns before committing to an API.
125+
126+
---
127+
128+
### P3: API Documentation — BLOCKING Phase 4
129+
130+
These APIs shipped in v1.1.0 but README examples are missing or incomplete.
131+
This section must be closed before any Phase 4 work ships. `spectre-init`
132+
templates cannot safely scaffold these patterns without documented examples.
133+
134+
#### `meta` + `afterNavigate` — document title and a11y pattern
135+
136+
Add a README example showing:
137+
138+
- A route definition with `meta: { title: string }`.
139+
- An `afterNavigate(context)` handler that reads `context.meta?.title` and
140+
sets `document.title`.
141+
- A note on a11y focus management as a secondary use case.
142+
143+
#### `onNavigationStart` / `onNavigationEnd` — loading state pattern
144+
145+
Add a README example showing:
146+
147+
- Both callbacks toggling a boolean.
148+
- A note that these drive a `navigating` signal at the app layer via
149+
`spectre-shell-signals`.
150+
151+
#### `router.subscribe()` — signals bridge pattern
152+
153+
Add a README example showing:
154+
155+
- Wrapping `router.subscribe()` in a `signal()` from `spectre-shell-signals`
156+
to expose a reactive `currentRoute` at the app layer.
157+
- This is the canonical pattern for reactive route state — one example is
158+
enough; the goal is a copy-able reference.
125159

126160
---
127161

‎TODO.md‎

Lines changed: 77 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -49,11 +49,11 @@ All Phase 2 items were delivered. The routing contract is stable and complete.
4949

5050
---
5151

52-
## Phase 3 — Ecosystem Integration
52+
## Phase 3 — Ecosystem Integration: P0/P1 Complete — P3 Docs Blocking Phase 4
5353

54-
Active phase. The foundation is solid — now the router needs to integrate with the broader
55-
Spectre ecosystem so `spectre-shell-signals`, `spectre-ui`, and `spectre-ui-astro` can build
56-
on top of it. Focus is on exposing router state reactively and supporting real application needs.
54+
P0 and P1 delivered. P2 (nested routing) remains evaluation-only. P3 API docs
55+
are NOT done and are blocking Phase 4 ship and spectre-init Phase 6 templates.
56+
Close P3 docs before starting any Phase 4 work.
5757

5858
### P0: Signals Bridge
5959

@@ -93,13 +93,45 @@ on top of it. Focus is on exposing router state reactively and supporting real a
9393
- [ ] **Nested routing proposal** (planning doc only; implement only when a concrete need is proven)
9494
- Evaluate alongside `spectre-ui-astro` layout patterns before committing to an API
9595

96+
### P3: Phase 3 API Documentation — NEXT — Blocking Phase 4 and spectre-init
97+
98+
These APIs shipped in v1.1.0 but README examples are missing or incomplete.
99+
Do these before any Phase 4 work. spectre-init templates cannot safely scaffold
100+
these patterns without documented examples to copy.
101+
102+
- [ ] **Document `meta: { title: string }` pattern in README**
103+
- Files: `README.md`
104+
- Acceptance: route definition shows `meta` field; `afterNavigate` example reads
105+
`context.meta?.title` and sets `document.title`
106+
- Why: spectre-init shell-app template needs a copy-able title management pattern
107+
108+
- [ ] **Document `afterNavigate` hook in README**
109+
- Files: `README.md`
110+
- Acceptance: `RouterOptions` example shows `afterNavigate(context)` reading
111+
`context.meta?.title`; includes note on a11y focus management use case
112+
- Why: without a documented example, consumers will not know how to complete
113+
the navigation lifecycle
114+
115+
- [ ] **Document `onNavigationStart` / `onNavigationEnd` loading-state pattern in README**
116+
- Files: `README.md`
117+
- Acceptance: `RouterOptions` example shows both callbacks toggling a boolean;
118+
includes note that these drive a `navigating` signal at the app layer via
119+
`spectre-shell-signals`
120+
- Why: spectre-init loading indicator pattern depends on this being documented
121+
122+
- [ ] **Document `router.subscribe()` signals integration pattern in README**
123+
- Files: `README.md`
124+
- Acceptance: example shows wrapping `router.subscribe()` in a `signal()` from
125+
`spectre-shell-signals` to get a reactive `currentRoute` at the app layer
126+
- Why: this is the canonical bridge between the router and signals — consumers
127+
need a single clear example
128+
96129
---
97130

98-
## Phase 4 — Production Readiness
131+
## Phase 4 — Production Readiness: Active
99132

100-
Builds on the complete Phase 3 contract. Closes remaining gaps that surface in real production
101-
applications: explicit error handling, navigation history helpers, and nested outlet support
102-
promoted from Phase 3 when a concrete need is confirmed.
133+
Phase 3 core APIs are delivered. Phase 4 closes remaining production gaps: deterministic error
134+
handling, navigation history helpers, and nested outlet support when a concrete need is proven.
103135

104136
### P0: Error Routes
105137

@@ -144,16 +176,46 @@ promoted from Phase 3 when a concrete need is confirmed.
144176

145177
## Recommended Execution Order
146178

147-
1. Navigation subscription API (unblocks spectre-shell-signals integration)
148-
2. Navigating state hooks (unblocks loading UI in spectre-ui)
149-
3. Per-route metadata (unblocks title management and analytics)
150-
4. `afterNavigate` hook (completes the lifecycle surface)
151-
5. Error routes (closes the silent-failure gap for production apps)
152-
6. Navigation history helpers (ergonomic, low-risk, additive)
153-
7. Nested routing (only when a concrete application need is proven)
179+
1. ~~Navigation subscription API~~ ✓
180+
2. ~~Navigating state hooks~~ ✓
181+
3. ~~Per-route metadata~~ ✓
182+
4. ~~`afterNavigate` hook~~ ✓
183+
5. **Phase 3 API docs** ← current (meta, afterNavigate, onNavigationStart/End, subscribe pattern)
184+
6. Error routes (closes the silent-failure gap; Phase 4 P0)
185+
7. Navigation history helpers (back/forward/replace; Phase 4 P1)
186+
8. Nested routing (only when a concrete application need is proven)
187+
188+
---
154189

155190
---
156191

192+
## spectre-init Consumer Requirements
193+
194+
`@phcdevworks/spectre-init` scaffolds templates against this package. These items
195+
are needed for templates to work correctly and demonstrate the full routing surface.
196+
197+
### P0: Confirmed — Route Array Contract
198+
199+
`bootstrapApp` calls `routes()` and expects `Route[]` as the return value.
200+
Templates have been fixed to return `Route[]` with `{ path, loader }` shape.
201+
No router changes needed — this is confirmed correct.
202+
203+
- [x] `Route` type (`path`, `name?`, `meta?`, `loader`) is the correct shape — templates updated
204+
205+
### P1: Template Showcase Items — Needed for Phase 6
206+
207+
These are shipped in v1.1.0 but not yet used in scaffolded templates. Confirm
208+
they are stable and covered in README examples so spectre-init can reference them.
209+
210+
- [ ] Confirm `meta: { title: string }` on route definitions is documented with an example
211+
- [ ] Confirm `afterNavigate(context)` usage for `document.title` is documented
212+
- [ ] Confirm `onNavigationStart` / `onNavigationEnd` pattern is documented
213+
214+
### P2: Error Routes — Needed for Phase 6 template hardening
215+
216+
- [ ] `errorRoute` option on `RouterOptions` (Phase 4 P0) — when shipped, spectre-init shell-app template should add an error route
217+
- [ ] `onError(error, context)` callback — when shipped, document the pattern for template consumers
218+
157219
## Explicitly Out of Scope
158220

159221
- Application state management (owned by spectre-shell-signals)

0 commit comments

Comments
 (0)