@loykin/designkit 0.0.1-dev.3 → 0.0.1-dev.5

package/README.md

@@ -13,21 +13,28 @@ npm install @loykin/designkit
 
 Requires React 19 and Tailwind CSS v4. UI components are based on [shadcn/ui](https://ui.shadcn.com) — if your app has shadcn set up, theming integrates automatically via shared CSS variables (`--primary`, `--background`, `--radius`, etc.).
 
-Import the styles in your global CSS:
+shadcn/ui is the component and semantic-token convention, not a runtime
+dependency. Consumers do not need to install the shadcn CLI, but they must use
+Tailwind CSS v4 and should define the shared semantic variables they want to
+customize.
+
+Import Tailwind and DesignKit from the same global CSS entry:
 
 ```css
 /* globals.css */
+@import "tailwindcss";
 @import "@loykin/designkit/styles";
 ```
 
-The styles file includes pre-built Tailwind utility classes — no `@source` configuration required. You can also import the stylesheet from your app entry, as shown below.
+`@loykin/designkit/styles` registers the package's compiled JavaScript as a
+Tailwind source. The consuming application's Tailwind v4 build generates the
+utilities for both the application and DesignKit in one cascade. DesignKit does
+not ship a second, pre-built copy of Tailwind utilities.
 
 ## Quick Start
 
 ```tsx
 import { DataBodyTemplate, PageTopBar, Button } from '@loykin/designkit'
-import '@loykin/designkit/styles'
-
 export function UsersPage() {
   return (
     <DataBodyTemplate
@@ -204,15 +211,15 @@ handle stays inside the clipped panel corner:
 
 ```css
 .layout-dashboard .react-grid-item:not(.react-grid-placeholder) {
-  --dk-resize-handle-size: clamp(20px, calc(var(--radius) * 1.6), 40px);
-  --dk-resize-handle-inset: clamp(4px, calc(var(--radius) * 0.45), 16px);
-  --dk-resize-handle-mark-size: clamp(6px, calc(var(--radius) * 0.55), 12px);
-  --dk-resize-handle-color: rgba(0, 0, 0, 0.35);
-  --dk-resize-handle-mark-radius: min(var(--radius), var(--dk-resize-handle-mark-size));
+  --designkit-resize-handle-size: clamp(20px, calc(var(--radius) * 1.6), 40px);
+  --designkit-resize-handle-inset: clamp(4px, calc(var(--radius) * 0.45), 16px);
+  --designkit-resize-handle-mark-size: clamp(6px, calc(var(--radius) * 0.55), 12px);
+  --designkit-resize-handle-color: rgba(0, 0, 0, 0.35);
+  --designkit-resize-handle-mark-radius: min(var(--radius), var(--designkit-resize-handle-mark-size));
 }
 
 .dark .layout-dashboard .react-grid-item:not(.react-grid-placeholder) {
-  --dk-resize-handle-color: rgba(255, 255, 255, 0.4);
+  --designkit-resize-handle-color: rgba(255, 255, 255, 0.4);
 }
 ```
 
@@ -453,6 +460,39 @@ import {
 } from '@loykin/designkit'
 ```
 
+### PageTopBar
+
+Top breadcrumb / action bar placed at the top of a page template via the `topBar` prop.
+
+```tsx
+import { PageTopBar } from '@loykin/designkit'
+
+<PageTopBar left="Admin / Users" right={<Button size="sm">Add</Button>} />
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `left` | `ReactNode` | — | Left content. A plain string is parsed as `/`-separated breadcrumbs. |
+| `right` | `ReactNode` | — | Right-aligned actions |
+| `variant` | `'ghost' \| 'default'` | `'ghost'` | `'default'` adds a bottom border |
+| `sidebarTrigger` | `false \| ReactNode` | auto | Mobile sidebar open button. `undefined` auto-detects SidebarProvider context; `false` suppresses; pass a `ReactNode` for a custom trigger. |
+| `height` | `string` | `var(--designkit-toolbar-height)` | Bar height |
+| `className` | `string` | — | Class applied to the bar root |
+
+**Mobile sidebar trigger**
+
+When `PageTopBar` is rendered inside a `SidebarShell` on a mobile viewport, it automatically prepends a hamburger trigger to open the sidebar drawer — no extra code required. To suppress this (e.g. when the left slot already has a back button), pass `sidebarTrigger={false}`:
+
+```tsx
+// Back-button detail page — suppress auto trigger
+<PageTopBar sidebarTrigger={false} left={<BackButton />} />
+
+// Custom trigger
+<PageTopBar sidebarTrigger={<MyTrigger />} left="Settings" />
+```
+
+---
+
 ### EmptyState
 
 ```tsx
@@ -471,20 +511,20 @@ import { Users } from 'lucide-react'
 
 ## Theming
 
-Designkit maps shadcn/ui CSS variables onto its own `--dk-*` tokens. Changing your shadcn theme automatically updates all designkit components.
+Designkit maps shadcn/ui CSS variables onto its own `--designkit-*` tokens. Changing your shadcn theme automatically updates all designkit components.
 
 | What | How |
 |---|---|
 | Colors, radius, typography | shadcn/ui theme variables (`--primary`, `--radius`, etc.) |
-| Spacing, density, padding | `--dk-density`, `--dk-page-padding-*`, `--dk-panel-gap` |
+| Spacing, density, padding | `--designkit-density`, `--designkit-page-padding-*`, `--designkit-panel-gap` |
 | Per-page overrides | `className` or `theme` prop |
 
 ```css
 :root {
-  --dk-density:        1;        /* 0.85 compact / 1 default / 1.15 comfortable */
-  --dk-page-padding-x: 1.5rem;
-  --dk-page-padding-y: 1rem;
-  --dk-panel-gap:      1rem;
+  --designkit-density:        1;        /* 0.85 compact / 1 default / 1.15 comfortable */
+  --designkit-page-padding-x: 1.5rem;
+  --designkit-page-padding-y: 1rem;
+  --designkit-panel-gap:      1rem;
 }
 ```
 
@@ -492,7 +532,7 @@ Per-page override via `className`:
 
 ```css
 .layout-dashboard {
-  --dk-density: 0.85;
+  --designkit-density: 0.85;
 }
 ```
 
@@ -504,7 +544,7 @@ Or via `theme` prop:
 
 ```tsx
 <DataBodyTemplate
-  theme={{ '--dk-density': '1.15' } as React.CSSProperties}
+  theme={{ '--designkit-density': '1.15' } as React.CSSProperties}
   title="Settings"
 >
 ```