@platned/ui 0.3.0 → 0.6.0

package/README.md

@@ -1,6 +1,7 @@
 # @platned/ui
 
-Platned Design System — React component library used across Platned products.
+React + TypeScript component library used across Platned products, with design tokens
+generated from Figma.
 
 ## Install
 
@@ -8,44 +9,143 @@ Platned Design System — React component library used across Platned products.
 npm install @platned/ui
 ```
 
+Peer dependencies:
+
+| Package | Range | Required |
+|---|---|---|
+| `react`, `react-dom` | `>=18` | yes |
+| `react-icons` | `>=5.4.0` | yes — components render Lucide glyphs from `react-icons/lu` |
+| `react-router-dom` | `>=6` | **optional** — only for the `./sidebar` entry point |
+
+`clsx`, `tailwind-merge`, `@floating-ui/react` and `tabbable` are regular dependencies, not
+peers. They are implementation details.
+
 ## Usage
 
+Import the stylesheet once, at your app root:
+
 ```tsx
-// Import styles once at your app root
 import '@platned/ui/styles'
+```
+
+Then import components:
+
+```tsx
+import { Button, Input, Select, Modal, DataTable } from '@platned/ui'
+```
+
+### Dark mode
 
-// Use components
-import { Button, Input, Modal, DataTable } from '@platned/ui'
-import { AppSidebar } from '@platned/ui/sidebar'
+Add the `dark` class to `<html>`. Every component follows, because the tokens are CSS custom
+properties rather than compiled values.
+
+```ts
+document.documentElement.classList.toggle('dark')
 ```
 
-## Tailwind users
+### Tailwind users
 
-If your project uses Tailwind CSS, extend your config with the Platned preset instead of importing the pre-built CSS:
+Consume the preset so your own utility classes resolve against the same tokens:
 
 ```js
 // tailwind.config.js
 module.exports = {
   presets: [require('@platned/ui/tailwind-preset')],
+  content: ['./src/**/*.{ts,tsx}'],
 }
 ```
 
-## AppSidebar
+Use the preset's unprefixed names — `bg-brand`, `text-default`, `border-default`. A class the
+preset does not define silently produces no CSS.
+
+### App sidebar
 
-The sidebar ships as a separate entry point to avoid forcing `react-router-dom` on consumers who don't need it.
+The collapsible nav rail is a separate entry point because it needs `react-router-dom`, which
+is an optional peer — importing the main bundle never pulls it in. It takes its nav as data and
+its brand and footer as slots.
 
 ```tsx
-import { AppSidebar } from '@platned/ui/sidebar'
+import { AppSidebar, SidebarUserCard } from '@platned/ui/sidebar'
+
+const [collapsed, setCollapsed] = useState(false)
 
 <AppSidebar
-  collapsed={false}
-  onToggle={() => {}}
-  userName="Jane Smith"
-  userRole="Admin"
-  onLogout={() => signOut()}
+  groups={[
+    { items: [
+        { to: '/dashboard', label: 'Dashboard', icon: <LuLayoutGrid />, end: true },
+        { to: '/entities', label: 'Entities', icon: <LuLayers />, indicator: true },
+      ] },
+    { title: 'Review', items: [
+        { to: '/queue', label: 'Review queue', icon: <LuClipboardList /> },
+      ] },
+  ]}
+  collapsed={collapsed}
+  onToggle={() => setCollapsed(c => !c)}
+  brand={({ collapsed }) => (collapsed ? <Mark /> : <Logo />)}
+  footerNav={[{ to: '/settings', label: 'Settings', icon: <LuSettings /> }]}
+  footer={
+    <SidebarUserCard name={user.name} role={user.role} collapsed={collapsed} onLogout={signOut} />
+  }
 />
 ```
 
+## Package entries
+
+| Import | Contents |
+|---|---|
+| `@platned/ui` | Every UI component |
+| `@platned/ui/sidebar` | `AppSidebar`, `SidebarUserCard`, `NavTabs` — needs `react-router-dom` |
+| `@platned/ui/styles` | Pre-built stylesheet. Import once at the app root |
+| `@platned/ui/tailwind-preset` | CJS Tailwind preset |
+
+## Components
+
+Grouped as they are in the docs. Every component is exported from the package root — the
+folder layout is internal.
+
+**Forms & inputs** — `Button`, `IconButton`, `ButtonGroup`, `Input`, `Textarea`,
+`PasswordInput`, `InputGroup`, `SearchInput`, `InputOTP`, `Select`, `Combobox`, `Command`,
+`DatePicker`, `Calendar`, `Checkbox`, `Switch`, `Toggle`, `ToggleGroup`, `RadioGroup`,
+`SegmentedControl`, `MultiSelectCard`, `Slider`, `Stepper`, `FileDropZone`, `Label`,
+`Field` and parts, `ControlSizeProvider`
+
+**Data display** — `Badge`, `StatusBadge`, `StatusDot`, `StatusChip`, `TagPill`, `CountBadge`,
+`RoleBadge`, `UserStatusPill`, `TrailChip`, `CheckIndicator`, `EntityIconBadge`, `DataTable`
+and cell parts, `Table` and parts, `ListRow`, `FileRow`, `ScoredRow`, `NumberedList`,
+`IconTextRow`, `ChecklistRow`, `StepsList`, `DetailItem`, `DetailGrid`, `CheckedGroupList`,
+`StatTile`, `StatNumber`, `ScoreValue`, `TileGrid`, `Avatar`, `AvatarGroup`, `AvatarBlock`
+
+**Data visualisation** — `Sparkline`, `MiniBarChart`, `BarChart`, `DonutChart`, `RadialGauge`,
+`ChartLegend`, `LegendDot`, `TrendLabel`
+
+**Layout & containers** — `Card` and parts, `AspectRatio`, `ScrollArea`, `Carousel`,
+`Resizable`, `Accordion`, `Collapsible`, `Separator`, `Kbd`, `Skeleton`, `Spinner`,
+`WidgetHeader`, `WidgetTitle`, `WidgetFooter`
+
+**Page chrome** — `PageHeading`, `PageToolbar`, `FilterBar`, `Tabs`, `EyebrowLabel`, `NavItem`,
+`Breadcrumb`, `NavigationMenu`, `Pagination`
+
+**Overlays** — `Modal`, `Drawer`, `ConfirmDialog`, `NoteConfirmModal`, `BlockedModal`,
+`DropdownMenu`, `ContextMenu`, `Menubar`, `Popover`, `HoverCard`, `Tooltip`, `Portal`
+
+**Feedback** — `InlineAlert`, `Banner`, `Toast`, `Toaster`, `EmptyState`, `ProgressBar`
+
+**AI & decorative** — `AIChatBar`, `AISuggestionChip`, `QuickActionsBar`, `AuroraBackdrop`
+
+Icons are **not** re-exported. Import them from `react-icons/lu` at the call site.
+
+## Documentation
+
+Run the docs site locally:
+
+```bash
+npm run docs   # localhost:5173
+```
+
+Every component page carries its examples, its keyboard contract and its props table. See
+[CHANGELOG.md](CHANGELOG.md) for the release history — 0.3.0, 0.4.0 and 0.5.0 each carry
+breaking renames with migration tables.
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for local development setup and publishing.
+See [CONTRIBUTING.md](CONTRIBUTING.md).