Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/docs/ui-inventory/hot-swap-status.md
T
2026-07-08 16:15:37 +02:00

4.4 KiB

UI Hot-Swap Status

What's wired

The boilerplate ships three UI adapter packages under packages/:

Package Purpose Current state
@hivegrid/ui-app App-shell registries (sidebar, breadcrumb, mobile shell, portals) Skeleton + registry types, no concrete component bindings.
@hivegrid/ui-subframe Subframe (design-tool) component placeholder bridge Placeholder factory only — createSubframePlaceholder() returns { status: "empty" }.
@hivegrid/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

  • @hivegrid/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 @hivegrid/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 @hivegrid/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 @hivegrid/ui-app, @hivegrid/ui-mock, @hivegrid/foundation, @hivegrid/view-models.
  • apps/web/app/components/ui/hot-swap/HotSwapPageRenderer.tsx bridges the descriptor shape from @hivegrid/ui-mock to RR7 JSX using createShellRegistries() from @hivegrid/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 @hivegrid/foundation + @hivegrid/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 @hivegrid/ui-app, @hivegrid/ui-mock, @hivegrid/foundation, @hivegrid/view-models to apps/web/package.json dependencies. — done.
  2. ✓ Pick one low-risk route and refactor it to consume from @hivegrid/ui-app's page registry. — done at apps/web/app/routes/hot-swap-demo.tsx, dev-only.
  3. ☐ Add @hivegrid/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.
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