Track HiveGrid Cloud planning reference
This commit is contained in:
1 parent
b3d5ea6764
commit
e341c5938a
5784 files changed
+1104929
-3
No files matched your search
@@ -0,0 +1,65 @@
|
||||
# UI Hot-Swap Status
|
||||
|
||||
## What's wired
|
||||
|
||||
The boilerplate ships three UI adapter packages under `packages/`:
|
||||
|
||||
| Package | Purpose | Current state |
|
||||
| --- | --- | --- |
|
||||
| `@toolctrl/ui-app` | App-shell registries (sidebar, breadcrumb, mobile shell, portals) | Skeleton + registry types, no concrete component bindings. |
|
||||
| `@toolctrl/ui-subframe` | Subframe (design-tool) component placeholder bridge | Placeholder factory only — `createSubframePlaceholder()` returns `{ status: "empty" }`. |
|
||||
| `@toolctrl/ui-mock` | Fixture-driven mock surface for visual/hot-swap testing | Has `createHotSwapDrillPage()` and is consumed by `scripts/verify-ui-hot-swap.ts`. |
|
||||
|
||||
`packages/foundation` and `packages/view-models` provide the contract these adapters compose against.
|
||||
|
||||
## What is NOT wired
|
||||
|
||||
- `@toolctrl/ui-subframe` is still a placeholder bridge — no real design-source binding.
|
||||
- Outside the activation reference route (see below), `apps/web/app/routes/**` does not render through any `@toolctrl/ui-*` registry — concrete components still live in `apps/web/app/components/`.
|
||||
- The majority of consumer surfaces (admin shell, tenant dashboard, marketing) have not been refactored to consume from `@toolctrl/ui-app`'s page registry.
|
||||
|
||||
## What IS wired (activation reference)
|
||||
|
||||
A minimal hot-swap activation now lives in `apps/web`:
|
||||
|
||||
- `apps/web/package.json` depends on `@toolctrl/ui-app`, `@toolctrl/ui-mock`, `@toolctrl/foundation`, `@toolctrl/view-models`.
|
||||
- `apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.tsx` bridges the descriptor shape from `@toolctrl/ui-mock` to RR7 JSX using `createShellRegistries()` from `@toolctrl/ui-app`.
|
||||
- `apps/web/app/routes/hot-swap-demo.tsx` renders `createHotSwapDrillPage()` through the renderer. The route is gated to `NODE_ENV !== "production"` so production surface area is unchanged.
|
||||
- `apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.test.tsx` asserts the descriptor → DOM mapping (sidebar, breadcrumbs, header, cards, activity).
|
||||
|
||||
This is the first activation milestone: the registry path is alive end-to-end against a real consumer route, but is still fixture-driven (no Subframe binding yet).
|
||||
|
||||
## Why this is intentional (Settings API Onboarding-era)
|
||||
|
||||
The adapter packages were introduced in the Phase-C boundary work to lock down what a **whitelabel-friendly** UI swap can look like without forcing a big-bang component rewrite. Boundaries are enforced by `scripts/verify-phase-c-boundaries.mjs` so any future activation cannot accidentally cross a runtime line.
|
||||
|
||||
Until an activation milestone explicitly enables Subframe (or another design source), the registries stay as a structural placeholder. The cost of registering them in `apps/web` without a real binding would be:
|
||||
|
||||
- pulling `@toolctrl/foundation` + `@toolctrl/view-models` into the web bundle for no consumer,
|
||||
- adding registry warm-up code paths to SSR + hot-swap tests with no real fixture to exercise,
|
||||
- noise in the hot-swap verifier (`verify:ui-hot-swap`) that would have to allowlist “empty registry” permanently.
|
||||
|
||||
## When to activate
|
||||
|
||||
Activate the hot-swap path when **at least one** is true:
|
||||
|
||||
- A real Subframe/Figma source is being integrated and `ui-subframe` becomes a non-empty bridge.
|
||||
- A second consumer app (admin shell, partner portal) needs to share `apps/web` components through a registry instead of importing relative paths.
|
||||
- A whitelabel deployment needs to swap the dashboard surface per-tenant without forking the codebase.
|
||||
|
||||
## Activation checklist
|
||||
|
||||
1. ✓ Add `@toolctrl/ui-app`, `@toolctrl/ui-mock`, `@toolctrl/foundation`, `@toolctrl/view-models` to `apps/web/package.json` `dependencies`. — done.
|
||||
2. ✓ Pick one low-risk route and refactor it to consume from `@toolctrl/ui-app`'s page registry. — done at `apps/web/app/routes/hot-swap-demo.tsx`, dev-only.
|
||||
3. ☐ Add `@toolctrl/ui-subframe` to `apps/web/package.json` once it becomes a non-empty bridge.
|
||||
4. ☐ Promote the mock fixture in `packages/ui-mock/src/index.ts` (`createHotSwapDrillPage`) to a non-mock descriptor source once a design tool is wired.
|
||||
5. ☐ Refactor a second real consumer surface (admin shell or tenant dashboard) through the renderer to prove cross-surface reuse.
|
||||
6. ☐ Update `docs/ui-inventory/surface-map.md` to claim the new surfaces as hot-swappable.
|
||||
|
||||
## Related verification
|
||||
|
||||
```sh
|
||||
pnpm run verify:phase-c-boundaries # boundaries that future activation must not cross
|
||||
pnpm run verify:ui-visual # current mock visual baseline
|
||||
pnpm run test:hot-swap # mock-driven hot-swap drill
|
||||
```
|
||||
Reference in new issue
Block a user