@aircall/ds 0.2.7 → 0.6.0

package/README.md

@@ -40,6 +40,21 @@ pnpm add @aircall/ds
 pnpm add react react-dom @aircall/icons @aircall/numbers
 ```
 
+**Optional peer dependencies (install only if you use these components):**
+
+| Component | Packages to install |
+|-----------|-------------------|
+| `Calendar` | `react-day-picker`, `date-fns` |
+| `DataTable` | `@tanstack/react-table` |
+
+```bash
+# If using Calendar
+pnpm add react-day-picker date-fns
+
+# If using DataTable
+pnpm add @tanstack/react-table
+```
+
 ## Usage
 
 ### Import Components
@@ -134,7 +149,7 @@ Versatile button component with multiple variants, colors, sizes, and shapes.
 - `shape`: 'default' | 'square' | 'circle'
 - `readOnly`: boolean
 - `block`: boolean (full width)
-- `asChild`: boolean (use with Slot for polymorphic rendering)
+- `render`: ReactElement — render Button as a different element (e.g. `<a>`). Replaces the former `asChild` / Slot pattern.
 
 **Examples:**
 
@@ -162,10 +177,8 @@ Versatile button component with multiple variants, colors, sizes, and shapes.
 // Destructive button
 <Button color="destructive">Delete</Button>
 
-// Link as button (using asChild with Slot)
-<Button asChild>
-  <a href="/profile">Go to Profile</a>
-</Button>
+// Link rendered as a button — use the `render` prop
+<Button render={<a href="/profile" />}>Go to Profile</Button>
 ```
 
 ## Storybook
@@ -194,10 +207,11 @@ View at: http://localhost:6008
 ### Building Storybook
 
 ```bash
-pnpm sb:build
+pnpm sb:build            # plain build — no recipe registry
+pnpm sb:build:deploy     # full build including the recipe registry (what CI deploys)
 ```
 
-Static site output: `storybook-static/`
+Static site output: `storybook-static/`. See [Recipes (shadcn Registry)](#recipes-shadcn-registry) below for when to use each.
 
 ## Development
 
@@ -214,7 +228,7 @@ pnpm add <component-name>
 
 ```
 src/
-├── components/        # React components
+├── components/        # React components (published to npm)
 │   └── button/
 │       ├── __stories__/
 │       │   └── Button.stories.tsx
@@ -226,6 +240,10 @@ src/
 │   └── utils.ts      # cn() helper for class merging
 ├── hooks/            # Custom React hooks
 └── fonts/            # Fellix Aircall font files
+├── recipes/          # shadcn registry recipes (copy-paste patterns)
+│   ├── combobox-searchable-select.tsx
+│   ├── combobox-dropdown-search.tsx
+│   └── combobox-multi-select.tsx
 ```
 
 ### Styling System
@@ -271,6 +289,64 @@ The design system uses CSS variables with OKLch color space for better color per
 
 Colors automatically adapt when `data-theme="dark"` is set on the root element.
 
+## Recipes (shadcn Registry)
+
+Recipes are pre-built, copy-paste component patterns built on top of `@aircall/ds` primitives. They are distributed via the [shadcn registry](https://ui.shadcn.com/docs/registry) — consumers run `shadcn add` to install a recipe into their project, and they own the code afterwards. They can customize it freely.
+
+> Note: in the shadcn registry schema these items are typed `registry:block` — that's a shadcn enum value, not our terminology. Internally we call them "recipes".
+
+### What is the Registry?
+
+The registry is a set of JSON files that describe each recipe — its name, description, npm dependencies, and full source code. These JSON files are generated by `shadcn build` and served as static files alongside the DS Storybook.
+
+**How it works:**
+
+1. Recipe source files live in `src/recipes/` using relative imports (`../components/combobox`)
+2. `pnpm run registry:build` copies the recipes, rewrites imports to `@aircall/ds`, runs `shadcn build`, and outputs JSON files to `public/r/`
+3. Storybook serves `public/` as static files via `staticDirs` config
+4. A consumer runs `shadcn add <url>` — the CLI fetches the JSON, extracts the source code, and writes it into their project with `@aircall/ds` imports
+
+### Local Development
+
+Run `pnpm run registry:build` before starting Storybook to generate the JSON files. Then start Storybook:
+
+```bash
+pnpm run registry:build
+pnpm run sb:dev
+```
+
+The recipe JSON files are served at `http://localhost:6008/r/<name>.json`. You can test the full consumer flow locally:
+
+```bash
+pnpm dlx shadcn@latest add http://localhost:6008/r/combobox-searchable-select.json
+```
+
+### Production (Published Storybook)
+
+When the DS Storybook is deployed to `ds.aircall.io`, the same JSON files are served at the public URL. Consumers install recipes with:
+
+```bash
+pnpm dlx shadcn@latest add https://ds.aircall.io/r/combobox-searchable-select.json
+```
+
+The deployment CI job runs `pnpm sb:build:ds` at the repo root, which maps to `sb:build:deploy` inside this package. That script runs `registry:build` first, then `storybook build` — Storybook's `staticDirs: ['../public']` config picks up `public/r/` and copies it into `storybook-static/r/` so the JSON files ship alongside the deployed Storybook. **`sb:build` on its own does NOT bundle the registry** — use `sb:build:deploy` (or `pnpm sb:build:ds` at the root) whenever you need the registry included.
+
+### Available Recipes
+
+| Recipe | Description |
+|---|---|
+| `combobox-searchable-select` | Single-select combobox — input acts as trigger and search filter |
+| `combobox-dropdown-search` | Button-triggered combobox with search inside dropdown |
+| `combobox-multi-select` | Multi-select with inline chips and type-ahead filtering |
+
+### Adding a New Recipe
+
+1. Create `src/recipes/<name>.tsx` — import primitives from `../components/`
+2. Add an entry to `registry.json` at the package root
+3. Add a story in `src/stories/` that imports from the recipe
+4. Run `pnpm run registry:build` to generate JSON in `public/r/`
+5. Verify at `http://localhost:6008/r/<name>.json` after starting Storybook
+
 ## Scripts
 
 ```bash
@@ -283,12 +359,20 @@ pnpm build:package       # Build both JS and CSS for publishing
 pnpm build:js            # Build JavaScript bundle only
 pnpm build:css           # Build pre-compiled CSS only
 
+# Registry
+pnpm registry:build      # Generate recipe JSON files in public/r/
+                         # (rewrites relative imports to @aircall/ds)
+
+# Storybook — three distinct builds
+pnpm sb:build            # Plain Storybook build. NO registry JSON.
+pnpm sb:build:chromatic  # Storybook build for Chromatic (--test --stats-json). NO registry JSON.
+pnpm sb:build:deploy     # Full deployment build: runs registry:build, builds Storybook,
+                         # and copies public/r into storybook-static/r/.
+                         # This is what CI runs (via `pnpm sb:build:ds` at the repo root).
+
 # Testing Package Locally
 pnpm pack                # Create tarball for local testing
 
-# Storybook
-pnpm sb:build            # Build static Storybook site
-
 # Component Management
 pnpm add <component>     # Add new shadcn component