@devalok/shilp-sutra 0.37.0 → 0.38.0

package/docs/recipes/server-components.md

@@ -0,0 +1,209 @@
+# Server vs Client Components
+
+Reference for using `@devalok/shilp-sutra` correctly inside React Server Components (Next.js App Router, TanStack Start, Remix v3+, Astro, future RSC frameworks).
+
+## TL;DR
+
+- **Always use per-component imports** (`@devalok/shilp-sutra/ui/button`, NOT `@devalok/shilp-sutra/ui`) — barrels drag in client-only siblings and trip the RSC barrel-import error.
+- **Importing a client component into a Server Component is fine.** The client component renders as a client island at that point. The Server Component shell stays server-rendered.
+- **What actually breaks RSC**, in order of frequency: (a) calling a client hook in a server file; (b) passing functions or class instances as props from server → client; (c) reading `window`/`document` in a server module's top-level body.
+- The matrix below tells you which components have NO `"use client"` (so they SSR without hydration cost) vs. which become client islands (still importable, just hydrate).
+
+## RSC-safety matrix
+
+The list is generated from the `// @server-safe` source annotation. Components without the annotation get `"use client"` injected at build time and ship as client islands.
+
+### `@devalok/shilp-sutra/ui`
+
+| Server-safe (renders without hydration) | Everything else |
+|---|---|
+| `Text` | All other UI primitives become client islands when rendered |
+| `Stack` | |
+| `Container` | |
+| `Skeleton` | |
+| `Table` (and child components: `TableHeader`, `TableRow`, `TableCell`) | |
+| `Code` | |
+| `VisuallyHidden` | |
+
+```tsx
+// ✅ Server Component — Text/Stack/Container/etc. SSR with zero hydration cost
+import { Text } from "@devalok/shilp-sutra/ui/text";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+
+export default function ServerPage() {
+  return (
+    <Stack className="p-ds-08">
+      <Text variant="heading-2xl">Server-rendered</Text>
+    </Stack>
+  );
+}
+```
+
+```tsx
+// ✅ Also fine — Button is a client component, but importing one into a Server
+// Component just creates a client island at that boundary. No wrapper needed.
+import { Button } from "@devalok/shilp-sutra/ui/button";
+
+export default function ServerPage() {
+  return <Button>Click</Button>;
+}
+```
+
+```tsx
+// ❌ NOT fine — passing a function as a prop from server → client.
+// Functions are not serializable across the RSC boundary.
+import { Button } from "@devalok/shilp-sutra/ui/button";
+
+export default function ServerPage() {
+  return <Button onClick={() => console.log("hi")}>Click</Button>;
+  //              ^^^^^^^ — define handler inside a "use client" wrapper instead
+}
+```
+
+When you need an event handler, define it inside a client component:
+
+```tsx
+// app/components/MyButton.tsx
+"use client";
+import { Button } from "@devalok/shilp-sutra/ui/button";
+
+export function MyButton() {
+  return <Button onClick={() => console.log("hi")}>Click</Button>;
+}
+```
+
+### `@devalok/shilp-sutra/composed`
+
+| Server-safe (renders without hydration) | Everything else |
+|---|---|
+| `ContentCard` | All other composed components become client islands when rendered |
+| `PageHeader` | |
+| `LoadingSkeleton` | |
+| `PageSkeletons` | |
+
+### `@devalok/shilp-sutra/shell`
+
+All shell components are client islands. They manage state (open/close, active route, viewport detection) and require hydration.
+
+### `@devalok/shilp-sutra/ai`
+
+All AI components are client islands. They manage conversation state, streaming responses, and command bar focus.
+
+### `@devalok/shilp-sutra/hooks`
+
+All hooks (`useColorMode`, `useIsMobile`, etc.) are client-only by definition (React hooks).
+
+### `@devalok/shilp-sutra/utils`, `/ui/lib/utils`, `/ui/lib/motion`, `/ui/lib/date-utils`
+
+Pure functions. Server-safe.
+
+## Why barrel imports break RSC
+
+The barrel re-exports every component in a layer. When a Server Component imports anything from `@devalok/shilp-sutra/ui`, the bundler walks the barrel and pulls in code from sibling components. If any sibling has `"use client"`, the bundler complains:
+
+```
+You're importing a component that needs useState. 
+It only works in a Client Component.
+```
+
+Per-component imports avoid this — the bundler only walks the imported file's module graph.
+
+This is also why **per-component imports tree-shake better** even in non-RSC frameworks. They're the recommended pattern everywhere.
+
+## "use client" propagation
+
+A component is server-safe only if:
+
+1. It has no `"use client"` directive at the top of its source file
+2. None of its imports have `"use client"` either (transitively)
+
+We mark sources `// @server-safe` and a build-time check verifies the import graph stays clean. The `"use client"` directive is injected automatically during the build for components without that annotation.
+
+If you fork the source and remove `"use client"` from a component that uses `useState`, the build will still inject it back unless you also remove the React-hook usage. Don't fight the system — wrap in a client component instead.
+
+## Streaming and Suspense
+
+All shilp-sutra components SSR cleanly. They have no client-only side effects at module top-level — no `window.*`, `document.*`, or `localStorage.*` access during render. Side effects happen in `useEffect`, which runs after hydration.
+
+Use `<Suspense>` boundaries normally:
+
+```tsx
+import { Suspense } from "react";
+import { LoadingSkeleton } from "@devalok/shilp-sutra/composed/loading-skeleton";
+
+export default function Page() {
+  return (
+    <Suspense fallback={<LoadingSkeleton variant="page" />}>
+      <ClientHeavyComponent />
+    </Suspense>
+  );
+}
+```
+
+Both `<Suspense>` and `<LoadingSkeleton>` are server-safe.
+
+## Common RSC mistakes
+
+### Mistake 1: Calling a client hook in a Server Component
+
+```tsx
+// ❌ — useColorMode is a React hook; hooks only run in client components
+import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
+
+export default function ServerPage() {
+  const { mode } = useColorMode(); // breaks
+  return <div>{mode}</div>;
+}
+```
+
+Fix: use the hook inside a `"use client"` component.
+
+### Mistake 2: Reading `window.*` in a server module's top level
+
+```tsx
+// ❌ — window is undefined on the server
+const w = window.innerWidth;
+
+export default function ServerPage() {
+  return <p>{w}px</p>;
+}
+```
+
+Fix: read inside a `useEffect` of a client component, or use `useIsMobile` in a client wrapper.
+
+### Mistake 3: Passing functions as props from a Server Component to a client island
+
+```tsx
+// ❌ — function props are not serializable across the RSC boundary
+import { Button } from "@devalok/shilp-sutra/ui/button";
+
+export default function ServerPage() {
+  return <Button onClick={() => console.log("hi")}>Click</Button>;
+}
+```
+
+Fix: define the handler inside the client island, or use a Server Action and pass the action reference (Server Actions ARE serializable).
+
+### Mistake 4: Barrel-importing into a Server Component
+
+```tsx
+// ❌ — pulls every UI primitive's module graph into the server file,
+//      and any sibling with "use client" trips the bundler error.
+import { Text } from "@devalok/shilp-sutra/ui";
+```
+
+Fix: per-component import.
+
+```tsx
+// ✅
+import { Text } from "@devalok/shilp-sutra/ui/text";
+```
+
+## When in doubt
+
+If you're unsure whether a component is server-safe, look at the source:
+
+- `packages/core/src/ui/<name>.tsx` — top of file. The `// @server-safe` annotation marks components that ship without `"use client"`.
+- `packages/core/src/composed/<name>/index.tsx` — same.
+
+The matrix in this file is the authoritative public list. If you find a discrepancy, file an issue.

package/docs/recipes/troubleshoot.md

@@ -0,0 +1,217 @@
+# Troubleshoot
+
+A decision tree for the most common shilp-sutra setup breakages. Read symptoms top-to-bottom; the first match is usually the right diagnosis.
+
+## Symptom: Tailwind utilities don't apply (no styling at all)
+
+**Diagnosis:** Tailwind is not detecting design-system source classes, OR the CSS imports are out of order.
+
+Check 1 — import order. Open the global CSS file. The order MUST be:
+
+```css
+@import "tailwindcss";          /* FIRST */
+@import "@devalok/shilp-sutra/css";  /* SECOND */
+```
+
+If reversed, swap them.
+
+Check 2 — both imports present. Some setups accidentally drop `@import "tailwindcss"` after a refactor. Both imports are required.
+
+Check 3 — file is actually loaded. In Next.js, `globals.css` must be imported from `app/layout.tsx` (App Router) or `pages/_app.tsx` (Pages Router). In Vite, from `src/main.tsx`. In Remix, via `links` export. In Astro, from a layout file.
+
+## Symptom: Spacing utilities like `p-4` don't work but `p-ds-04` does
+
+**Diagnosis:** Working as designed.
+
+Shilp Sutra uses the `--spacing-ds-*` namespace to avoid colliding with consumer numeric spacing. Use `p-ds-04`, `gap-ds-03`, `mx-ds-08`, etc. Plain `p-4` is the consumer's own spacing (Tailwind's default scale) — it works but is unrelated to the design system.
+
+If `p-ds-*` does NOT work, you have the styling-not-applying issue above.
+
+## Symptom: Console error or weird animation glitches involving `MotionConfig`, `LayoutGroup`, or `AnimatePresence`
+
+**Diagnosis:** Multiple copies of `framer-motion` are resolved.
+
+Run:
+
+```bash
+pnpm why framer-motion
+# or
+npm ls framer-motion
+```
+
+If more than one version is listed, fix with overrides:
+
+**pnpm:**
+```jsonc
+// package.json
+{
+  "pnpm": {
+    "overrides": {
+      "framer-motion": "^12"
+    }
+  }
+}
+```
+
+**npm:**
+```jsonc
+// package.json
+{
+  "overrides": {
+    "framer-motion": "^12"
+  }
+}
+```
+
+**yarn (berry):**
+```jsonc
+// package.json
+{
+  "resolutions": {
+    "framer-motion": "^12"
+  }
+}
+```
+
+**bun:**
+```jsonc
+// package.json
+{
+  "overrides": {
+    "framer-motion": "^12"
+  }
+}
+```
+
+After editing, delete the lockfile + `node_modules` and reinstall.
+
+## Symptom: Next.js error: `Cannot find module '@devalok/shilp-sutra/...'` or `Module parse failed: Unexpected token`
+
+**Diagnosis:** `transpilePackages` is missing from `next.config.{ts,js,mjs}`.
+
+Add:
+
+```ts
+transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+```
+
+If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
+
+## Symptom: Hydration warning on every page load (Next.js)
+
+**Diagnosis:** `next-themes` writes the `class` attribute on `<html>` before React hydrates, causing a server/client class mismatch.
+
+Add `suppressHydrationWarning` to `<html>` in `app/layout.tsx` (App Router) or `pages/_document.tsx` (Pages Router):
+
+```tsx
+<html lang="en" suppressHydrationWarning>
+```
+
+This warning is specific to the `class` attribute on `<html>` — it does NOT suppress hydration warnings on other elements.
+
+## Symptom: Dark mode toggle does nothing
+
+**Diagnosis:** The `.dark` class is not being applied to `<html>` (or any ancestor of the components).
+
+Quick verification — open the browser console and run:
+
+```js
+document.documentElement.classList.add("dark");
+```
+
+If components now render in dark mode, the toggle wiring is broken (not the design system). Check:
+
+- `next-themes` is installed and `<ThemeProvider attribute="class">` wraps the app
+- For Vite/Remix/Astro/TanStack: the `theme-bootstrap.js` script runs before any React mount
+
+If `.dark` IS on `<html>` and components still look light, the CSS imports are out of order — see the first symptom above.
+
+## Symptom: RSC error — `You're importing a component that needs useState. It only works in a Client Component`
+
+**Diagnosis:** A client-only shilp-sutra component is being imported into a Server Component via the barrel.
+
+Switch to per-component imports:
+
+```tsx
+// ❌ pulls client code into RSC
+import { Button } from "@devalok/shilp-sutra/ui";
+
+// ✅ component-scoped, declares "use client" only where needed
+import { Button } from "@devalok/shilp-sutra/ui/button";
+```
+
+For the full RSC-safety matrix, see [server-components.md](./server-components.md).
+
+## Symptom: Fonts render in browser default (Times/Arial), not Inter/Ranade
+
+**Diagnosis:** Either the CSS import did not load (see first symptom), or the consumer is overriding `--font-sans` / `--font-display` and pointing at a font that isn't loaded.
+
+Check the computed value of `--font-sans` on `<html>` in DevTools. It should be `"Inter Variable", system-ui, ...`. If the override variable points at a font that isn't loaded, the browser falls back.
+
+The font files ship inside the package — no `next/font` configuration is required for the defaults to work.
+
+## Symptom: Bare `shadow` class produces no visible shadow
+
+**Diagnosis:** Working as designed. Tailwind 4 has no default `--shadow` token, so the `shadow` utility no longer exists.
+
+Use the explicit shadow variants:
+
+- `shadow-raised` — cards, buttons
+- `shadow-overlay` — popovers, dropdowns
+- `shadow-floating` — modals, dialogs
+- `shadow-brand` — accent emphasis
+
+## Symptom: `<Toaster />` is mounted but `toast()` doesn't show anything
+
+**Diagnosis:** Either `sonner` is not installed, or two `<Toaster />` instances are mounted at different positions and they're stacking off-screen.
+
+Check 1 — `pnpm list sonner` shows `^2.0.0` or higher.
+
+Check 2 — only ONE `<Toaster />` is mounted in the app. Search the project: `grep -r "<Toaster" src/ app/`.
+
+In dev mode, calling `toast()` without a mounted `<Toaster />` logs a one-time console warning pointing to the fix (since v0.36.0).
+
+## Symptom: Build error mentioning `use-sync-external-store`
+
+**Diagnosis:** Should not happen since v0.37.0 — `use-sync-external-store` was moved to runtime dependencies and is auto-installed transitively.
+
+If it still happens, install it explicitly:
+
+```bash
+pnpm add use-sync-external-store
+```
+
+And open an issue at <https://github.com/devalok-design/shilp-sutra/issues> with the resolution graph (`pnpm why use-sync-external-store`) so we can fix the root cause.
+
+## Symptom: Storybook MCP server `localhost:6006/mcp` returns 404
+
+**Diagnosis:** Storybook dev server isn't running, OR the MCP plugin is not enabled in this Storybook version.
+
+Check 1 — `pnpm dev` is running and `http://localhost:6006/` shows the Storybook UI.
+Check 2 — the MCP endpoint requires Storybook 9+ with the MCP plugin enabled. Older versions of this repo's Storybook setup may need an upgrade.
+
+The MCP server is a development convenience for AI agents — `llms.txt` and `llms-full.txt` are the authoritative docs and do not require a running server.
+
+## Still stuck
+
+Open an issue with this template:
+
+```md
+## Environment
+- Framework + version (Next.js 15.x / Vite 5.x / Remix 2.x / Astro 5.x / TanStack Start ...)
+- Package manager + version (pnpm 10.x / npm 11.x / yarn / bun)
+- Node version
+- @devalok/shilp-sutra version
+- Other peer deps (framer-motion, sonner, tailwindcss versions)
+
+## What I tried
+[Recipe followed, step where it broke]
+
+## What happened
+[Exact error message, stack trace, screenshot]
+
+## What I expected
+[Behavior described in the recipe]
+```
+
+File at: <https://github.com/devalok-design/shilp-sutra/issues/new>