@boostdev/design-system-components 1.2.4 → 1.2.6

package/AGENTS.md

@@ -1,10 +1,10 @@
-# @boostdev/components - Agent Guide
+# @boostdev/design-system-components - Agent Guide
 
 ## What this package provides
 
 A component library with three targets:
 - **React (web)** — CSS Modules, design tokens from `@boostdev/design-system-foundation`, full component suite
-- **Web Components** (experimental) — Lit-based custom elements, framework-agnostic, entry point `@boostdev/components/web-components`
+- **Web Components** (experimental) — Lit-based custom elements, framework-agnostic, entry point `@boostdev/design-system-components/web-components`
 - **React Native** (alpha) — React Native primitives, JS token layer, Metro-resolved via `"react-native"` export condition
 
 ## Prerequisites
@@ -17,10 +17,10 @@ All component styles live inside `@layer component`.
 
 **Web Components:** import the bundle to register all custom elements:
 ```js
-import '@boostdev/components/web-components';
+import '@boostdev/design-system-components/web-components';
 ```
 
-**React Native:** wrap the app in `ThemeProvider` from `@boostdev/components/native/ThemeContext`. Metro resolves the native bundle automatically via the `"react-native"` export condition — no extra config needed.
+**React Native:** wrap the app in `ThemeProvider` from `@boostdev/design-system-components/native/ThemeContext`. Metro resolves the native bundle automatically via the `"react-native"` export condition — no extra config needed.
 
 ## Component categories
 
@@ -61,10 +61,12 @@ Also: never define story component functions inside a `render: () => { function
 
 ### React Native (alpha) — `src/components/**/*.native.tsx`
 Native implementations co-located with their web counterparts. Metro resolves them automatically.
-- **ui/**: Typography, Badge, Avatar, Alert, NotificationBanner, Progress, Skeleton, Loading, Separator
-- **layout/**: Card, SectionHeader, ButtonGroup, IconWrapper
-- **interaction/**: Button
-- **interaction/form/**: Checkbox, Radio, Switch + atoms (Label, Message)
+- **ui/** (22): Accordion, Alert, Avatar, Badge, Breadcrumb, Calendar, Carousel, Collapsible, DescriptionList, Link, Loading, NotificationBanner, Pagination, Progress, ProgressCircle, Separator, Skeleton, Table, Tabs, Tooltip, Typography
+- **layout/** (4): ButtonGroup, Card, IconWrapper, SectionHeader
+- **interaction/** (7): Button, Dialog, Drawer, DropdownMenu, Popover, Rating, Toast (ToastProvider + useToast)
+- **interaction/form/** (13): Checkbox, CheckboxGroup, Combobox, FileInput, FormInput, NumberInput, Radio, RadioGroup, SegmentedControl, Select, Slider, Switch, Textarea + atoms (Label, Message)
+
+**Not ported** (deferred): Command (cmdk dependency), SkipLink (browser-only pattern)
 
 Storybook stories: `src/components/**/*.native.stories.tsx` (title `'React Native/{UI|Interaction|Form|Layout}/{Name}'`, tags `['!stable', 'alpha']`). All stories wrap in `<ThemeProvider>` decorator.
 
@@ -189,16 +191,27 @@ Error focus rings substitute `--bds-color_error` for `--bds-color_interactive`.
 ## Import paths
 
 ```ts
-// Named exports — plain React / Vite
-import { Button, Badge, Typography } from '@boostdev/components';
+// Server-safe components — works in Next.js Server Components and client components:
+import { Typography, Badge, Card } from '@boostdev/design-system-components';
+
+// Client-only components (use React hooks) — must be inside a 'use client' boundary in Next.js:
+import { ToastProvider, useToast, Dialog, Drawer } from '@boostdev/design-system-components/client';
+
+// All components — client entry with 'use client' banner (safe for any component in Next.js):
+import { Button, Badge, Typography } from '@boostdev/design-system-components/client';
 
-// Named exports — Next.js / RSC (adds 'use client' to the bundle)
-import { Button, Badge, Typography } from '@boostdev/components/client';
+// Utilities — server-safe (no CSS, no 'use client'), works in Server Components, layouts, middleware
+import { cn } from '@boostdev/design-system-components/utils';
+import type { WithClassName } from '@boostdev/design-system-components/utils';
 
 // CSS (import once, at the app root)
-import '@boostdev/components/css';
+import '@boostdev/design-system-components/css';
 ```
 
+> **Root entry is RSC-safe**: The root entry (`@boostdev/design-system-components`) can be safely imported in Next.js Server Components — all `createContext` calls are lazily initialised. However, client-only components (those using hooks like `useState`, `useEffect`) must still be rendered inside a `'use client'` boundary.
+
+> **`cn()` in Server Components**: For `cn` only, prefer `@boostdev/design-system-components/utils` — the root entry includes a CSS side-effect import.
+
 ## Accessibility requirements (WCAG 2.1 AA)
 
 Every component must meet WCAG 2.1 Level AA:
@@ -218,6 +231,10 @@ Every component must meet WCAG 2.1 Level AA:
 
 References: https://developer.mozilla.org/en-US/docs/Web/Accessibility | https://www.w3.org/WAI/WCAG21/quickref/
 
+## Usage guidelines
+
+- **Form buttons must be wrapped in `ButtonGroup`**: Whenever buttons are used inside a form (submit, reset, cancel, navigation), wrap them in a `ButtonGroup` component. Use `variant="flow"` for multi-step form navigation (Back / Next) and `variant="card"` for single-form submissions. This ensures consistent spacing, alignment, and responsive behaviour.
+
 ## Key decisions
 
 - **Button variants**: `default` (filled) and `outline` (transparent, outlined). `ghost` is a deprecated alias for `outline` — use `outline` for new code.
@@ -269,6 +286,16 @@ A live version of this design system is available as an MCP server at:
 https://ds.boostdev.nl/api/mcp
 ```
 
-Connect to it to look up component props and tokens without reading source files. Use
-`ds_get_component` before writing any component code to ensure you have the correct prop names.
+Connect to it to look up component props, CSS custom properties, and tokens without reading source files. Use
+`ds_get_component` before writing any component code — it returns the props interface **and** all
+overridable CSS custom properties with their defaults. Override CSS variables on the component
+element or any parent in plain CSS (no `@layer` needed):
+
+```css
+.my-branded-button {
+  --button_color: var(--bds-color_success);
+  --button_on-color: var(--bds-color_on-success);
+}
+```
+
 Run `pnpm mcp:start` to start a local instance at `http://localhost:3001/api/mcp`.

package/README.md

@@ -52,6 +52,9 @@ import { Button, Card } from '@boostdev/components';
 
 // Next.js / RSC — use the /client subpath
 import { Button, Card } from '@boostdev/components/client';
+
+// Server-safe utilities (cn, WithClassName) — works in Server Components, layouts, middleware
+import { cn } from '@boostdev/components/utils';
 ```
 
 ---
@@ -416,6 +419,10 @@ Renders a circular container sized to its own `font-size`. Override the backgrou
 Composes class name strings, filtering out falsy values:
 
 ```ts
+// Server-safe — works in Server Components, layouts, middleware
+import { cn } from '@boostdev/components/utils';
+
+// Also available from root or /client (but these are client-only in Next.js)
 import { cn } from '@boostdev/components';
 
 cn('card', isActive && 'card--active', [extraClass])