timothyandClaude Opus 4.8
a2c056dd7a
Build ErsatzTV Image / Docs update reminder (push) Has been skipped
Build ErsatzTV Image / decisions.md append-only (push) Has been skipped
Build ErsatzTV Image / API docs in sync (OpenAPI + endpoint index) (push) Has been skipped
Build ErsatzTV Image / Formatting (changed .cs conform to .editorconfig) (push) Has been skipped
Build ErsatzTV Image / Build & push image (amd64) (push) Has been cancelled
Build ErsatzTV Image / Build & test (.NET) (push) Has been cancelled
Build ErsatzTV Image / EF migration integrity (SQLite + MySql) (push) Has been cancelled
Build ErsatzTV Image / Functional E2E (curl contracts) (push) Has been cancelled
Consolidate docs/decisions.md (1923 -> 1028) by extracting four cohesive topic clusters into docs/decisions/ (optimistic-concurrency, api-auth-security, release-ci-governance, spa-modularization) — content relocated verbatim (lossless; all rationale + reversals preserved), main Index rebuilt to reference the topic files plus the remaining in-file entries, docs/README.md points back at the decisions Index. Add the v26.9.0 row to the ci-cd.md version table. refs #340 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
99 lines
7.4 KiB
Markdown
99 lines
7.4 KiB
Markdown
# SPA modularization — App.tsx screen/shell extraction epic (#243)
|
|
|
|
Why the ChicoryTV SPA was decomposed out of a monolithic `App.tsx`, and the conventions the
|
|
extraction froze (single-file screens, screen-owned route wrappers, explicit primary-action
|
|
ownership). Pure structural moves — no API/route/CSS/behavior change — so the rationale is
|
|
about *boundaries*, relocated from the append-only `docs/decisions.md` at the v26.9.0
|
|
consolidation. Cross-links: `docs/spa-conventions.md` §2/§6/§10.
|
|
|
|
Issue trail: epic #243 — phase 1 #244 (Channels), phase 2 #245 (Playouts), phase 4 #247
|
|
(shell/routing + primary actions). Refs #238 #230.
|
|
|
|
## Contents
|
|
|
|
- [2026-07-11 — Channels screen extraction (#244): single-file screen, no sibling helper dir (epic #243 phase 1)](#2026-07-11--channels-screen-extraction-244-single-file-screen-no-sibling-helper-dir-epic-243-phase-1)
|
|
- [2026-07-14 — Playouts screen extraction (#245): screen-owned route wrapper (epic #243 phase 2)](#2026-07-14--playouts-screen-extraction-245-screen-owned-route-wrapper-epic-243-phase-2)
|
|
- [2026-07-15 — App shell/routing extraction + explicit primary-action ownership (#247)](#2026-07-15--app-shellrouting-extraction--explicit-primary-action-ownership-247)
|
|
|
|
---
|
|
|
|
## 2026-07-11 — Channels screen extraction (#244): single-file screen, no sibling helper dir (epic #243 phase 1)
|
|
|
|
First bounded extraction under the App.tsx modularization epic (#243): the Channels domain moved
|
|
verbatim out of `web/src/App.tsx` into `web/src/screens/ChannelsScreen.tsx` (zero-prop, self-sufficient,
|
|
mirroring the SchedulesScreen extraction), with its behavior tests moved to a colocated
|
|
`ChannelsScreen.test.tsx` that owns its own scoped fetch mock (spa-conventions §6). Pure structural
|
|
move: no API/route/CSS/visual change; `App.tsx` retains only the import + the `<ChannelsScreen />`
|
|
dispatch clause.
|
|
|
|
**Decision — no `web/src/channels/` sibling helper directory** (unlike Schedules' `web/src/schedules/`).
|
|
Channels' pure logic (`stateByChannelId`, `sortedChannels`, `groupedChannels`, `progressFromChannelState`,
|
|
`formatChannelNumber`) totals ~30 lines with no independent business-rule layer comparable to Schedules'
|
|
`itemRules.ts` (~470 lines, separately unit-tested). Keeping it inside the single screen file matches the
|
|
Blocks/Decos/Templates precedent. Revisit only if a later #243 phase adds substantial pure Channels logic
|
|
worth isolating.
|
|
|
|
**One cross-domain helper inlined, not shared:** the Dashboard-owned `progressFromNowPlaying` (still in
|
|
`App.tsx`, used by `OnAirCard`) was structurally reused by the Channels `progressFromChannelState`. Rather
|
|
than export it from App or create a shared module, its ~5-line start/finish/now percentage math was inlined
|
|
into the moved `progressFromChannelState` (behavior-identical — `ChannelState.nowPlaying` carries the same
|
|
`startUtc`/`finishUtc` shape), so `ChannelsScreen.tsx` has no import back into `App.tsx`.
|
|
|
|
**#238 (TopBar `primaryAction` dead button) left untouched** — the `channels` route's inert `ctv:primary-action`
|
|
dispatch is #238's owned bug and out of scope for a behavior-preserving extraction; the shell/action redesign
|
|
is deferred to #247 (epic phase 4).
|
|
|
|
## 2026-07-14 — Playouts screen extraction (#245): screen-owned route wrapper (epic #243 phase 2)
|
|
|
|
Second bounded extraction under the App.tsx modularization epic (#243): the Playouts domain moved from
|
|
`web/src/App.tsx` into `web/src/screens/PlayoutsScreen.tsx`, including its loading/error/empty states,
|
|
dialogs, mutations, timeline/filter helpers, and the existing `PlayoutsRouteScreen`. The dedicated
|
|
`PlayoutScheduleEditors.tsx` modules remain separate. This is a pure structural move: no API, route, CSS,
|
|
or runtime behavior changed; `App.tsx` retains only the import and `<PlayoutsRouteScreen />` dispatch.
|
|
|
|
**The unguarded route wrapper moves with the screen.** Playouts owns two sibling sub-path editors and,
|
|
per `spa-conventions.md` §2, must keep its local pathname state plus `popstate` listener because App's
|
|
allow-sub-path route object is reference-stable. Colocating the wrapper keeps that screen-specific route
|
|
ownership beside the base screen while App-level tests retain the cross-route navigation assertions.
|
|
|
|
**Temporal mutation behavior stays verbatim.** `mutatingRef`, `runMutation`, and the explicit
|
|
`query.refresh()` after a 409 moved as one unit. The extraction deliberately does not add mount/current
|
|
guards to these pre-existing promise completions; changing those semantics belongs to a separate issue.
|
|
Detailed behavior tests now render `PlayoutsScreen` directly with a scoped fetch mock, including the
|
|
zero-playout Add Playout affordance, lock/409 handling, refresh/poll ownership, action and kind gates, and
|
|
dialog flows. Refs #245 #243.
|
|
|
|
## 2026-07-15 — App shell/routing extraction + explicit primary-action ownership (#247)
|
|
|
|
Final phase of the App.tsx modularization epic (#243). `web/src/App.tsx` is now only the composition
|
|
root: it owns `activeRoute`, `currentPathRef`, the `navigate`/`popstate` pair that consults the dirty
|
|
guard, the approved `librariesSubPath`, and the global theme/health inputs, then composes the shell with
|
|
the matched screen. Route metadata/matching/sidebar groups moved to `web/src/app/routes.tsx`; shell chrome
|
|
(Sidebar, TopBar, Connect menu, version and theme controls) moved to `app/AppShell.tsx`; exhaustive screen
|
|
dispatch plus the Media/Libraries wrappers moved to `app/ScreenContent.tsx`. No route, styling, API, or
|
|
dependency changed.
|
|
|
|
**Route identity is deliberate infrastructure.** `routes.tsx` contains the ONE stable module-level array
|
|
of shared `ScreenRoute` objects. `routeFromLocation()` returns those same references for an
|
|
`allowSubPaths` base path and every owned sub-path, so React's `Object.is` state bailout remains part of
|
|
the contract rather than an accidental implementation detail. The three existing sub-path mechanisms stay
|
|
distinct: Playouts and Media self-own `pathname`/`popstate`; guarded Libraries receives only the path App
|
|
approved after its dirty guard; the remaining route screens retain their established self-owned or keyed
|
|
remount behavior. The extraction does not unify them into a speculative router/framework. `ScreenContent`
|
|
uses an exhaustive `ScreenId` switch, so a future route added without a dispatch branch fails typecheck
|
|
instead of silently falling through to a placeholder.
|
|
|
|
**Primary actions are one explicit screen-owned registration, not a global event.** The old
|
|
`ctv:primary-action` window `CustomEvent` and string-keyed dispatcher are removed. `PrimaryActionProvider`
|
|
holds exactly one `{ routeId, handler, owner }` registration shared by the active screen and TopBar;
|
|
`usePrimaryAction` registers it, keeps the latest handler behind a ref without ownership churn, and clears
|
|
it only when the same opaque owner unmounts. A stale cleanup therefore cannot erase a newer screen's
|
|
action. TopBar renders the Plus action only when the route has a non-empty label AND that active route owns
|
|
a matching registration, so metadata alone can no longer create a dead button. This is intentionally not a
|
|
generic action bus: one declared action per screen is the whole contract.
|
|
|
|
Tests pin stable route-object identity (including sibling sub-paths and query-only URLs), composition-level
|
|
sub-path rendering and dirty-popstate restoration, and primary-action matching/latest-handler/route-change/
|
|
cleanup/stale-owner behavior. Detailed Builder and Settings behavior is colocated with those screens while
|
|
`App.test.tsx` remains shell/routing/composition coverage. Refs #247 #243 #238 #230.
|