@loykin/designkit 0.0.1-dev.2 → 0.0.1-dev.4

package/README.md

@@ -2,6 +2,9 @@
 
 React page template library. Provides ready-to-use page layouts for admin and dashboard applications.
 
+For AI-assisted implementation in consuming applications, see the
+[DesignKit Consumer Agent Guide](docs/consumer-guide.md).
+
 ## Installation
 
 ```bash
@@ -17,14 +20,7 @@ Import the styles in your global CSS:
 @import "@loykin/designkit/styles";
 ```
 
-If your app builds Tailwind utilities from package source, include designkit in
-your Tailwind scan sources:
-
-```css
-@source "@loykin/designkit";
-```
-
-You can also import the stylesheet from your app entry, as shown below.
+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.
 
 ## Quick Start
 
@@ -138,6 +134,16 @@ Groups content within a tab or section. The `layout` prop controls the visual st
 | `inline` | Table-style rows (detail view) |
 | `split` | Left list + right detail |
 
+| Prop | Type | Description |
+|---|---|---|
+| `layout` | `GroupLayout` | Visual structure — see table above |
+| `variant` | `'card' \| 'plain' \| 'bordered'` | Wrapper style (defaults per layout) |
+| `title` | `ReactNode` | Group heading |
+| `description` | `ReactNode` | Subtitle below the heading |
+| `actions` | `ReactNode` | Action slot next to the heading |
+| `danger` | `boolean` | Renders title in destructive color |
+| `className` | `string` | Class applied to the group root element |
+
 ```tsx
 <DataBodyTemplate.Tab id="settings" label="Settings">
   <DataBodyTemplate.Group layout="horizontal" title="Identity" description="Basic information">
@@ -198,15 +204,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);
 }
 ```
 
@@ -300,6 +306,44 @@ Panel card component. Wrap your panel viewer in `DashboardPanel` for consistent
 
 ---
 
+### WorkbenchBodyTemplate
+
+Resizable editor/workbench shell for products like panel editors, SQL editors, log explorers, and data workspaces. The template owns the pane chrome and resize handles; the app owns editor, preview, inspector, schema, and result content.
+
+```tsx
+import { WorkbenchBodyTemplate, PageTopBar, Button } from '@loykin/designkit'
+
+export function SqlEditorPage() {
+  return (
+    <WorkbenchBodyTemplate
+      topBar={<PageTopBar left="Data / Query editor" />}
+      title="SQL editor"
+      headerRight={<Button variant="outline" size="sm">Run</Button>}
+      leftPane={<SchemaBrowser />}
+      mainPane={<SqlEditor />}
+      bottomPane={<ResultsGrid />}
+      resizable
+    />
+  )
+}
+```
+
+**WorkbenchBodyTemplate props:**
+
+| Prop | Type | Description |
+|---|---|---|
+| `topBar` | `ReactNode` | Top bar above the workbench |
+| `title` / `description` | `ReactNode` | Header copy above the panes |
+| `headerRight` / `actions` | `ReactNode` | Header action slots |
+| `leftPane` / `rightPane` | `ReactNode` | Optional side panes |
+| `mainPane` | `ReactNode` | Primary editor or preview area |
+| `bottomPane` | `ReactNode` | Optional result, query, or logs pane |
+| `resizable` | `boolean` | Enables pane drag handles |
+| `leftPaneCollapsed` / `rightPaneCollapsed` / `bottomPaneCollapsed` | `boolean` | Hides optional panes while preserving the template layout model |
+| `leftPaneWidth` / `rightPaneWidth` / `bottomPaneHeight` | `number` | Initial pane sizes in pixels |
+
+---
+
 ### FormWizardBodyTemplate
 
 Multi-step input wizard. Wraps each step's `content` in a `<form>` element automatically.
@@ -409,6 +453,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
@@ -427,20 +504,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;
 }
 ```
 
@@ -448,7 +525,7 @@ Per-page override via `className`:
 
 ```css
 .layout-dashboard {
-  --dk-density: 0.85;
+  --designkit-density: 0.85;
 }
 ```
 
@@ -460,13 +537,27 @@ Or via `theme` prop:
 
 ```tsx
 <DataBodyTemplate
-  theme={{ '--dk-density': '1.15' } as React.CSSProperties}
+  theme={{ '--designkit-density': '1.15' } as React.CSSProperties}
   title="Settings"
 >
 ```
 
 ---
 
+## Using with gridkit
+
+If your app also uses `@loykin/gridkit`, import its styles **after** designkit:
+
+```css
+@import "tailwindcss";
+@import "@loykin/designkit/styles";
+@import "@loykin/gridkit/styles";  /* must come last — uses @layer gridkit */
+```
+
+gridkit registers a named `@layer gridkit`. Importing it before `tailwindcss` or `designkit/styles` causes layer ordering conflicts where utility overrides resolve incorrectly.
+
+---
+
 ## Playground
 
 Interactive development tool to preview templates and generate code.