Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,74 @@
# UI Adapter Migration Playbook
Use this when moving UI primitives toward `packages/ui` hotswap-ready adapters.
## Goal
App code should eventually depend on stable adapter contracts such as `@toolctrl/ui/buttons`, not directly on a specific library implementation. Migration happens category by category.
## Migration Order
1. Navigation and shell
2. Buttons
3. Dialogs and modals
4. Tabs and tables
5. Inputs
6. Feedback
## Adapter Levels
- `placeholder`: category exists but exports no real adapter contract.
- `available`: package exposes stable metadata/contract for the current implementation.
- `component-backed`: package exports real reusable components or wrappers.
- `migrated`: app imports use the package adapter instead of app-local primitives.
Current status:
- `buttons`: `available` contract for `Button` and `buttonVariants`.
- `layout`: `available` contract for `ShadcnSidebarLayout` and `UiRegistry`.
- `navigation`: `available` contract for `AppSidebar`, `AdminSidebar`, `DocsSidebar`, `NavMain`, `NavSecondary`, `NavQuickLinks`, `NavActions`, and `SidebarPrimitives`.
- all other categories: placeholder registry.
## Rules
- Start with metadata/contract exports before moving components.
- Keep adapter exports source-only and runtime-safe.
- Keep runtime components in `apps/web/app/` until a migration phase explicitly moves imports.
- Do not import app routes, data loaders, tenant context, admin context, or feature modules into `packages/ui`.
- Do not hide feature-specific behavior inside `packages/ui`.
- Keep shadcn/Radix as the current core default until a category-specific migration says otherwise.
- Treat Headless UI as legacy unless explicitly retained by a category decision.
## Required Checks
For each category migration:
- Update `packages/ui/README.md`.
- Update the relevant `packages/ui/src/<category>.ts`.
- Update `docs/ui-inventory/components.json`.
- Add or update adapter contract tests.
- Keep app imports unchanged unless the phase explicitly migrates them.
## Button Example
Current button adapter contract:
- `@toolctrl/ui/buttons`
- `buttonAdapterNames`
- `buttonAdapters`
- source: `apps/web/app/components/ui/button.tsx`
This records stable intent without moving the current shadcn implementation yet.
## Shell/Navigation Example
Current shell/navigation adapter contracts:
- `@toolctrl/ui/layout`
- `layoutAdapterNames`
- `layoutAdapters`
- `@toolctrl/ui/navigation`
- `navigationAdapterNames`
- `navigationAdapters`
These records point agents to the current runtime sources in `apps/web/app/` and are guarded by `apps/web/app/application/ui/uiAdapters.test.ts` plus the inventory tests.