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,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.
|
||||
Reference in new issue
Block a user