@devalok/shilp-sutra 0.39.0 → 0.40.1

package/skill/references/setup-astro.md

@@ -31,6 +31,21 @@ Add only if rendering `<Toaster />`:
 pnpm add sonner
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or Astro's Vite build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `astro.config`
 
 Astro has its own `@astrojs/tailwind` integration, but for Tailwind 4 use the Vite plugin directly (Astro 4.5+ supports this):

package/skill/references/setup-next-app-router.md

@@ -10,10 +10,9 @@ You are in this recipe if **all** of these are true:
 
 - `package.json` lists `"next"` at version `^13.0.0` or higher
 - An `app/` directory exists at the project root or under `src/`
-- An `app/layout.tsx` (or `.jsx`) file exists
-- No `pages/` directory at the project root, OR `pages/` exists but only contains `_app.{js,tsx}` and `_document.{js,tsx}` (legacy artifacts)
+- An `app/layout.{tsx,jsx}` file exists
 
-If `pages/` is the primary router, use [install-next-pages.md](./install-next-pages.md).
+If a `pages/` directory exists at the project root AND contains route files (not just `_app`/`_document` legacy artifacts from older `create-next-app` versions), use [install-next-pages.md](./install-next-pages.md). `create-next-app@16+` no longer scaffolds `pages/` for App Router projects.
 
 ## 2. Install dependencies
 
@@ -43,11 +42,22 @@ Add only if you will render `<Toaster />`:
 pnpm add sonner
 ```
 
-Add brand assets package if you need Devalok or Karm logos:
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
 
-```bash
-pnpm add @devalok/shilp-sutra-brand
-```
+Some components depend on third-party libraries that ship as optional peers. **Install BEFORE first import** of the matching component, or `next build` will exit with `Module not found`. Skip entirely if you only use core components (`Button`, `Text`, `Stack`, `Dialog`, `Toast`, `Form*`, `Input`, `Card`, etc.).
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*` (BarChart, LineChart, …)| `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` use with Tabler icons            | `pnpm add @tabler/icons-react`                                                                          |
+
+> These aren't in core deps so consumers who never render a chart, OTP input, or rich-text editor don't pay the install / bundle cost. One-time decision at install.
 
 ## 3. Configure PostCSS
 
@@ -105,7 +115,7 @@ Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
-  transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+  transpilePackages: ["@devalok/shilp-sutra"],
 };
 
 export default nextConfig;
@@ -213,8 +223,8 @@ If anything is off, see [troubleshoot.md](./troubleshoot.md).
   }
   ```
   For npm/yarn/bun equivalents, see [troubleshoot.md](./troubleshoot.md).
-- **Server Component imports.** Use per-component imports (`@devalok/shilp-sutra/ui/text`) inside Server Components. The barrel import `@devalok/shilp-sutra/ui` pulls client-only code and breaks RSC. See [server-components.md](./server-components.md).
-- **`p-3` vs `p-ds-03`.** Our spacing namespace is `--spacing-ds-*` to avoid collision with consumer numeric spacing. Use `p-ds-04`, not `p-4`.
+- **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Inside Server Components, prefer `@devalok/shilp-sutra/ui/text`, `…/composed/page-header`, etc. The barrel `@devalok/shilp-sutra/ui` re-exports many client components — including some with hard peer-dep imports (e.g. `input-otp`) — so it both inflates the client bundle and forces those peers to be installed even when you never render those components. See [server-components.md](./server-components.md) for the full RSC-safety matrix.
+- **`p-3` vs `p-ds-03` — both are valid.** DS spacing uses the `--spacing-ds-*` namespace (`p-ds-04`, `gap-ds-03`); Tailwind 4's default numeric scale (`p-4`, `gap-2`) coexists by design. Pick `p-ds-*` for values that should track DS theme changes (card padding, form gaps); pick `p-N` for one-off layout values (section breathing room). Do NOT mass-codemod `p-4` → `p-ds-04` — that is not what the package intends.
 - **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
 
 ## 9. What you should NOT do

package/skill/references/setup-next-pages.md

@@ -18,6 +18,8 @@ If both `app/` and `pages/` exist, prefer [install-next-app-router.md](./install
 
 Same dependencies as the App Router recipe — see [install-next-app-router.md § 2](./install-next-app-router.md#2-install-dependencies). Replace `next-themes`'s `attribute="class"` setup with the same on Pages Router (it works identically).
 
+**Optional peer dependencies** — if you'll render `<DataTable>`, any chart, `<DatePicker>`, `<RichTextEditor>`, `<InputOTP>`, `<FilePreview>`, `<MarkdownViewer>`, or use Tabler icons, install the matching peers BEFORE first import. Full table at [install-next-app-router.md § 2a](./install-next-app-router.md#2a-optional-peer-dependencies-install-only-when-importing-the-matching-subpath) — identical for Pages Router.
+
 ## 3. PostCSS
 
 Same as App Router — see [§ 3](./install-next-app-router.md#3-configure-postcss).

package/skill/references/setup-remix.md

@@ -27,6 +27,21 @@ Optional:
 pnpm add sonner   # only if rendering <Toaster />
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or Remix's Vite build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `vite.config.ts`
 
 ```ts

package/skill/references/setup-tanstack-start.md

@@ -25,6 +25,21 @@ Optional:
 pnpm add sonner   # only if rendering <Toaster />
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or the TanStack Start dev/build will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `app.config.ts`
 
 ```ts

package/skill/references/setup-vite.md

@@ -42,6 +42,21 @@ Add only if rendering `<Toaster />`:
 pnpm add sonner
 ```
 
+### 2a. Optional peer dependencies (install ONLY when importing the matching subpath)
+
+Some components ship hard peers as optional. **Install BEFORE first import** or `vite dev` / `vite build` will fail with `Failed to resolve import`. Skip if you only use core components.
+
+| When you import…                                          | Install                                                                                                |
+|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
+| `@devalok/shilp-sutra/ui/charts/*`                         | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+| `@devalok/shilp-sutra/ui/data-table`                       | `pnpm add @tanstack/react-table @tanstack/react-virtual`                                                |
+| `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns`                                                                       |
+| `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`            |
+| `@devalok/shilp-sutra/ui/input-otp`                        | `pnpm add input-otp`                                                                                    |
+| `@devalok/shilp-sutra/composed/file-preview`               | `pnpm add react-pdf react-zoom-pan-pinch`                                                               |
+| `@devalok/shilp-sutra/composed/markdown-viewer`            | `pnpm add react-markdown react-syntax-highlighter`                                                      |
+| Any `Icon` / `IconButton` with Tabler icons                | `pnpm add @tabler/icons-react`                                                                          |
+
 ## 3. Wire Tailwind 4 in `vite.config.ts`
 
 Use the official Tailwind 4 Vite plugin (faster than PostCSS for Vite):

package/skill/references/troubleshoot.md

@@ -94,10 +94,32 @@ After editing, delete the lockfile + `node_modules` and reinstall.
 Add:
 
 ```ts
-transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+transpilePackages: ["@devalok/shilp-sutra"],
 ```
 
-If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
+## Symptom: Build error `Cannot find module 'sonner' / 'input-otp' / 'date-fns' / '@tiptap/react' / 'react-pdf' / 'react-markdown' / '@emoji-mart/react'`
+
+**Diagnosis:** an optional peer dependency is missing. Each component below has a peer it pulls only when imported. Install the matching peer (always BEFORE the first import):
+
+| You imported (per-component subpath) | Install                                                                                       |
+|--------------------------------------|-----------------------------------------------------------------------------------------------|
+| `…/ui/toaster` or `…/ui/toast`       | `pnpm add sonner`                                                                             |
+| `…/ui/input-otp`                     | `pnpm add input-otp`                                                                          |
+| `…/composed/date-picker`             | `pnpm add date-fns`                                                                           |
+| `…/composed/emoji-picker`            | `pnpm add @emoji-mart/data @emoji-mart/react`                                                 |
+| `…/composed/extensions/emoji-node` or `…/extensions/emoji-suggestion` | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/rich-text-editor`        | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/rich-chat-input`         | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder`                    |
+| `…/composed/file-preview`            | `pnpm add react-pdf react-zoom-pan-pinch`                                                     |
+| `…/composed/markdown-viewer`         | `pnpm add react-markdown react-syntax-highlighter remark-gfm`                                 |
+| `…/ai/block-renderer`, `…/ai/blocks/text`, `…/ai/blocks/error` | `pnpm add react-markdown remark-gfm`                                                          |
+| Any `…/ui/charts/*`                  | `pnpm add d3-array d3-axis d3-format d3-interpolate d3-scale d3-selection d3-shape d3-time-format d3-transition` |
+
+These ship as **optional** peers so consumers who never render the matching component don't pay the install cost. Once you import the component, the peer becomes required. Each affected component's JSDoc carries the same install hint — hover the import in your editor to see it inline.
+
+**Catch this at edit time, not build time:** install `@devalok/eslint-plugin-shilp-sutra` (`pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`). Its `prefer-per-component-import` rule flags peer-cliff symbols imported from a barrel and autofixes the path — surfacing the cliff in your editor before the bundler ever fails.
+
+For the full table in your framework's install recipe, see `install-<framework>.md → §2a. Optional peer dependencies`.
 
 ## Symptom: Hydration warning on every page load (Next.js)
 

package/skill/references/upgrading.md

@@ -0,0 +1,54 @@
+<!-- Source: packages/core/docs/recipes/upgrading.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
+
+# Upgrading shilp-sutra safely
+
+A version bump is **not** safe-by-default. Breaking changes in this design system are often type-level (prop types narrowed, symbols moved between barrels) and only surface at `tsc`/build time — never assume a bump is low-risk before doing the checks below.
+
+> **Hard rule for AI agents:** On ANY version bump, do not report the upgrade as safe before you have read the COMPLETE changelog **and** `MIGRATION.md` for the target version, grepped the consumer codebase for moved/renamed/narrowed symbols, and run `typecheck` + `build`. Breaking entries are frequently ordered LAST in the changelog (changesets orders by file, not severity) — skimming the top and relaxing is the #1 failure mode.
+
+## Step 1 — read the full breaking surface
+
+1. Open the target version's section in `node_modules/@devalok/shilp-sutra/CHANGELOG.md` (or the GitHub release). **Read all of it**, not just the top.
+2. Open `node_modules/@devalok/shilp-sutra/MIGRATION.md` and read every section from your current version up to the target.
+3. Scan for these signals — each is a potential break:
+   - `feat!` / `BREAKING` headers
+   - "removed", "moved", "renamed", "narrowed", "no longer exported"
+   - any prop **type** change (a narrowing — new type accepts less than the old — fails `tsc` for values that compiled before)
+   - peer-dependency changes (a symbol now imported from a per-component subpath instead of the barrel)
+
+## Step 2 — find affected call sites in your code
+
+```bash
+# Symbols moved out of barrels (0.40.0 peer-cliff cleanup example):
+grep -rn "from '@devalok/shilp-sutra/ui'" src/ | grep -E "Toaster|toast|InputOTP"
+grep -rn "from '@devalok/shilp-sutra/composed'" src/ | grep -E "DatePicker|EmojiPicker|FilePreview|MarkdownViewer|RichTextEditor|RichChatInput"
+grep -rn "from '@devalok/shilp-sutra/ai'" src/ | grep -E "BlockRenderer|ErrorBlock|TextBlock"
+
+# Type narrowings — find icon sources annotated as the wide React.ReactNode:
+grep -rn "React.ReactNode" src/ | grep -i "icon"
+```
+
+## Step 3 — let the ESLint plugin do the mechanical work
+
+```bash
+pnpm add -D @devalok/eslint-plugin-shilp-sutra
+# one-shot codemod: repoints moved barrel imports + flags deprecated APIs
+pnpm eslint --fix --config node_modules/@devalok/eslint-plugin-shilp-sutra/migration src/
+```
+
+The `prefer-per-component-import` rule autofixes barrel→subpath moves and splits multi-symbol lines correctly. It cannot retype your own annotations — narrowings (Step 4) are still manual.
+
+## Step 4 — typecheck + build BEFORE deploy
+
+```bash
+pnpm typecheck && pnpm build
+```
+
+This is the gate that catches type narrowings the changelog may have under-described. Two real examples from 0.40.0:
+
+- **Barrel peer-cliff cleanup (breaking):** `import { Toaster } from '@devalok/shilp-sutra/ui'` → `import { Toaster } from '@devalok/shilp-sutra/ui/toaster'`. 12 symbol families. Full table in `MIGRATION.md → v0.40.0`.
+- **Icon API narrowing:** the unified `IconInput` type excludes `string`/`number`/iterables that `React.ReactNode` allowed. If you stored icons in a `Record<string, React.ReactNode>` map or `icon?: React.ReactNode` field and passed them to a migrated component (`CommandItem.icon`, `ActivityItem.icon`, `Chat.Message.Avatar`), retype the source to `React.ReactElement`.
+
+## Step 5 — only now is the bump "safe"
+
+Report the upgrade as complete only after Steps 1-4 pass. If anything in the changelog was ambiguous, prefer a per-prop `expectTypeOf` probe over assuming "non-breaking".