42 lines
2.6 KiB
Markdown
42 lines
2.6 KiB
Markdown
# @toolctrl/ui
|
|
|
|
Source-only UI adapter boundary for future primitive migration.
|
|
|
|
This package intentionally does not replace existing app imports yet. Runtime components remain in `apps/web/app` until a category migration explicitly moves them. The adapter contracts live in `@toolctrl/ui/*` so agents can target stable names before runtime imports are migrated.
|
|
|
|
## Categories
|
|
|
|
| Category | Export | Intended ownership |
|
|
| --- | --- | --- |
|
|
| `buttons` | `@toolctrl/ui/buttons` | Button-like actions, icon buttons and grouped controls. |
|
|
| `inputs` | `@toolctrl/ui/inputs` | Text fields, selects, checkboxes, switches and form-adjacent controls. |
|
|
| `dialogs` | `@toolctrl/ui/dialogs` | Modals, alert dialogs, drawers, popovers and confirmation surfaces. |
|
|
| `tables` | `@toolctrl/ui/tables` | Data tables, row actions, pagination and empty states for tabular data. |
|
|
| `layout` | `@toolctrl/ui/layout` | Page shells, panels, stacks, grids, containers and spacing primitives. |
|
|
| `navigation` | `@toolctrl/ui/navigation` | Menus, tabs, breadcrumbs, sidebars and command/navigation affordances. |
|
|
| `feedback` | `@toolctrl/ui/feedback` | Toasts, alerts, progress, skeletons, badges and status indicators. |
|
|
|
|
## Current Usage
|
|
|
|
The package is runtime-safe and still source-only. `buttons`, `layout`, and `navigation` expose available adapter metadata for the current app-level implementation:
|
|
|
|
```ts
|
|
import { uiAdapterCategories } from "@toolctrl/ui";
|
|
import { buttonAdapters } from "@toolctrl/ui/buttons";
|
|
import { layoutAdapters } from "@toolctrl/ui/layout";
|
|
import { navigationAdapters } from "@toolctrl/ui/navigation";
|
|
```
|
|
|
|
`buttonAdapters` describes `Button` and `buttonVariants`. `layoutAdapters` describes `ShadcnSidebarLayout` and `UiRegistry`. `navigationAdapters` describes `AppSidebar`, `AdminSidebar`, `DocsSidebar`, `NavMain`, `NavSecondary`, `NavQuickLinks`, `NavActions`, and `SidebarPrimitives`.
|
|
|
|
These contracts do not render components, import React or alter app runtime behavior yet. Other category exports remain empty readonly registries until their migration phase.
|
|
|
|
## Migration Guidance
|
|
|
|
1. Keep current `apps/web/app/components` imports in place until a migration phase owns that category.
|
|
2. Migrate one category at a time, starting with leaf primitives that have low app-specific coupling.
|
|
3. Add concrete component exports to the matching category subpath, then re-export from `@toolctrl/ui` only when the API is stable.
|
|
4. Keep category exports backward-compatible once app code starts importing them.
|
|
|
|
See [docs/migration.md](./docs/migration.md) for the category migration checklist.
|