@devalok/shilp-sutra 0.37.1 → 0.39.0

package/docs/recipes/install-next-app-router.md

@@ -0,0 +1,230 @@
+# Install: Next.js (App Router)
+
+> Setup recipe for adding `@devalok/shilp-sutra` to a Next.js 13+ App Router project.
+
+## 1. Detect the framework
+
+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)
+
+If `pages/` is the primary router, use [install-next-pages.md](./install-next-pages.md).
+
+## 2. Install dependencies
+
+Pick the package manager that matches the project's lockfile.
+
+```bash
+# pnpm  (lockfile: pnpm-lock.yaml)
+pnpm add @devalok/shilp-sutra framer-motion next-themes
+pnpm add -D tailwindcss@^4 @tailwindcss/postcss
+
+# npm  (lockfile: package-lock.json)
+npm install @devalok/shilp-sutra framer-motion next-themes
+npm install -D tailwindcss@^4 @tailwindcss/postcss
+
+# yarn  (lockfile: yarn.lock)
+yarn add @devalok/shilp-sutra framer-motion next-themes
+yarn add -D tailwindcss@^4 @tailwindcss/postcss
+
+# bun  (lockfile: bun.lockb)
+bun add @devalok/shilp-sutra framer-motion next-themes
+bun add -d tailwindcss@^4 @tailwindcss/postcss
+```
+
+Add only if you will render `<Toaster />`:
+
+```bash
+pnpm add sonner
+```
+
+Add brand assets package if you need Devalok or Karm logos:
+
+```bash
+pnpm add @devalok/shilp-sutra-brand
+```
+
+## 3. Configure PostCSS
+
+Create or update `postcss.config.mjs` at the project root:
+
+```js
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+```
+
+If a `postcss.config.{js,cjs,json}` already exists, merge the plugin in. Do not delete the existing file.
+
+## 4. Wire Tailwind 4 + design tokens
+
+Locate the global CSS file. Common paths in priority order:
+
+- `app/globals.css`
+- `src/app/globals.css`
+- `app/global.css`
+
+If none exists, create `app/globals.css`. Set the file contents to (or merge into):
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+**Order matters.** `tailwindcss` MUST come first. The shilp-sutra `/css` entry registers `@theme` blocks that the Tailwind import must process.
+
+If the project has its own theme overrides, place them AFTER both imports:
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+
+@theme {
+  --color-brand: oklch(0.65 0.2 280);
+}
+```
+
+Import the CSS file once from `app/layout.tsx` (it should already be imported in a fresh `create-next-app` project):
+
+```tsx
+import "./globals.css";
+```
+
+## 5. Configure `transpilePackages`
+
+Edit `next.config.{ts,js,mjs}`. Add the `transpilePackages` field:
+
+```ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
+};
+
+export default nextConfig;
+```
+
+If a `transpilePackages` array already exists, append to it. Do not replace.
+
+Without `transpilePackages`, Next will refuse to load our pre-built `dist/*.js` because it ships native ESM that does not match Next's CJS-leaning loader for `node_modules`.
+
+## 6. Scaffold the Providers wrapper
+
+Create `app/providers.tsx`:
+
+```tsx
+"use client";
+
+import type { ReactNode } from "react";
+import { ThemeProvider } from "next-themes";
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+
+export function Providers({ children }: { children: ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      {children}
+      <Toaster />
+    </ThemeProvider>
+  );
+}
+```
+
+`next-themes` is already in the install list from § 2 — no extra install step needed here. If `<Toaster />` is not used:
+
+- Drop the `Toaster` import and its JSX usage
+- Skip installing `sonner`
+
+Mount `<Providers>` from `app/layout.tsx`:
+
+```tsx
+import "./globals.css";
+import { Providers } from "./providers";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+`suppressHydrationWarning` on `<html>` is required because `next-themes` writes the `class` attribute before React hydrates. Without it, every page logs a hydration warning.
+
+## 7. Verify the install
+
+Replace the contents of `app/page.tsx`:
+
+```tsx
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+
+export default function Home() {
+  return (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+        <Button variant="outline">Outline</Button>
+      </Stack>
+    </Stack>
+  );
+}
+```
+
+Run the dev server:
+
+```bash
+pnpm dev
+```
+
+Open `http://localhost:3000`. You should see:
+
+- The heading rendered in **Ranade** (display font), the buttons in **Inter** (body font)
+- The primary button on a saturated accent background, the soft button with a tinted background and no border, the outline button with a border and transparent background
+- No hydration warning in the browser console
+- No 404 for fonts (fonts are bundled inside the package; `next/font` is not required)
+
+If anything is off, see [troubleshoot.md](./troubleshoot.md).
+
+## 8. Common gotchas
+
+- **CSS import order.** `tailwindcss` BEFORE `@devalok/shilp-sutra/css`. Reversing the order silently produces a build with no design-system utilities.
+- **Multiple `framer-motion` copies.** Run `pnpm why framer-motion`. If it shows more than one resolved version, contexts (`MotionConfig`, `LayoutGroup`, `AnimatePresence`) silently break. Fix:
+  ```jsonc
+  // package.json
+  {
+    "pnpm": {
+      "overrides": {
+        "framer-motion": "^12"
+      }
+    }
+  }
+  ```
+  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`.
+- **Bare `shadow` is dead.** Tailwind 4 has no `--shadow-DEFAULT`. Use `shadow-raised`, `shadow-overlay`, or `shadow-floating`.
+
+## 9. What you should NOT do
+
+- ❌ Create `tailwind.config.ts` with `presets: [shilpSutra]` — the JS preset was removed in 0.38.
+- ❌ Add `@plugin "@devalok/shilp-sutra/tailwind"` — also removed.
+- ❌ Wrap the whole app in `<MotionConfig reducedMotion="...">` unless the user explicitly asks for a global motion override; Shilp Sutra components already respect `prefers-reduced-motion`.
+- ❌ Import from `@devalok/shilp-sutra/tailwind` — the export was removed in 0.38.
+- ❌ Run `pnpm add @radix-ui/react-*` — Radix is vendored; no @radix-ui runtime deps are required.
+
+## 10. Optional next steps
+
+- **Brand customization** — swap accent color, radius scale, or fonts: see [customize-brand.md](./customize-brand.md).
+- **App shell** — add a sidebar + topbar layout: read `llms-full.txt` sections for `AppSidebar` and `TopBar`.
+- **Server-safe components** — push as much rendering as possible into Server Components: see [server-components.md](./server-components.md).

package/docs/recipes/install-next-pages.md

@@ -0,0 +1,123 @@
+# Install: Next.js (Pages Router)
+
+> Setup recipe for adding `@devalok/shilp-sutra` to a Next.js project that uses the Pages Router (`pages/_app.tsx` as the entry).
+
+## 1. Detect
+
+You are in this recipe if:
+
+- `package.json` lists `"next"` (any version `>= 12`)
+- A `pages/` directory exists at the project root or under `src/` and contains `_app.{js,tsx}` (and optionally `_document.{js,tsx}`)
+- `app/` directory does NOT exist, OR exists but is unused
+
+If both `app/` and `pages/` exist, prefer [install-next-app-router.md](./install-next-app-router.md) and treat the Pages Router as legacy.
+
+## 2. 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).
+
+## 3. PostCSS
+
+Same as App Router — see [§ 3](./install-next-app-router.md#3-configure-postcss).
+
+## 4. Wire Tailwind 4 + tokens
+
+Common CSS entry paths in priority order:
+
+- `styles/globals.css`
+- `src/styles/globals.css`
+- `pages/_app.css` (rare)
+
+If none exists, create `styles/globals.css` with:
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+Import it from `pages/_app.tsx`:
+
+```tsx
+import "../styles/globals.css";
+```
+
+## 5. `transpilePackages`
+
+Identical to App Router — see [§ 5](./install-next-app-router.md#5-configure-transpilepackages).
+
+## 6. Providers in `_app.tsx`
+
+Replace or merge into `pages/_app.tsx`:
+
+```tsx
+import "../styles/globals.css";
+import type { AppProps } from "next/app";
+import { ThemeProvider } from "next-themes";
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      <Component {...pageProps} />
+      <Toaster />
+    </ThemeProvider>
+  );
+}
+```
+
+For `next-themes` to avoid hydration warnings, add a `_document.tsx` with `suppressHydrationWarning` on the `<html>`:
+
+```tsx
+// pages/_document.tsx
+import { Html, Head, Main, NextScript } from "next/document";
+
+export default function Document() {
+  return (
+    <Html lang="en" suppressHydrationWarning>
+      <Head />
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}
+```
+
+## 7. Verify
+
+Replace `pages/index.tsx`:
+
+```tsx
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+
+export default function Home() {
+  return (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+      </Stack>
+    </Stack>
+  );
+}
+```
+
+Run `pnpm dev` and open `http://localhost:3000`. Expected output is the same as the App Router recipe — see [§ 7](./install-next-app-router.md#7-verify-the-install).
+
+## 8. Pages Router specifics
+
+- **No React Server Components.** Every component runs on the client. Per-component imports still help tree-shaking but are not required for RSC safety.
+- **`getServerSideProps` / `getStaticProps`** — do not import shilp-sutra components inside these (they run server-side and won't render JSX). Components are imported and used in the page module's default export, as usual.
+- **`pages/_document.tsx` runs server-only.** Do not import shilp-sutra components there.
+
+## 9. Gotchas
+
+Same as App Router — see [§ 8](./install-next-app-router.md#8-common-gotchas).
+
+## 10. What NOT to do
+
+Same as App Router — see [§ 9](./install-next-app-router.md#9-what-you-should-not-do).

package/docs/recipes/install-remix.md

@@ -0,0 +1,171 @@
+# Install: Remix
+
+> Setup recipe for adding `@devalok/shilp-sutra` to a Remix project (v2 with Vite).
+
+## 1. Detect
+
+You are in this recipe if:
+
+- `package.json` lists `"@remix-run/node"` and `"@remix-run/react"`
+- `vite.config.{ts,js}` exists with the `vitePlugin` from `@remix-run/dev`
+- `app/root.tsx` exists with `<Outlet />` inside `<Document>` shell
+
+For React Router v7 (the spiritual successor to Remix), use the [install-vite.md](./install-vite.md) recipe — it works the same way.
+
+## 2. Install
+
+```bash
+pnpm add @devalok/shilp-sutra framer-motion
+pnpm add -D tailwindcss@^4 @tailwindcss/vite
+```
+
+Optional:
+
+```bash
+pnpm add sonner   # only if rendering <Toaster />
+```
+
+## 3. Wire Tailwind 4 in `vite.config.ts`
+
+```ts
+import { vitePlugin as remix } from "@remix-run/dev";
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    remix(),
+  ],
+});
+```
+
+`tailwindcss()` should come before `remix()` so the design tokens are processed first.
+
+## 4. Wire tokens
+
+Create `app/styles/globals.css`:
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+Wire it as a Remix link export from `app/root.tsx`:
+
+```tsx
+import type { LinksFunction } from "@remix-run/node";
+import globalsCss from "./styles/globals.css?url";
+
+export const links: LinksFunction = () => [
+  { rel: "stylesheet", href: globalsCss },
+];
+```
+
+The `?url` suffix is critical — it tells Vite to emit the file as an asset URL instead of inlining the CSS contents.
+
+## 5. Theme toggle
+
+Create `public/theme-bootstrap.js` (a static asset served verbatim):
+
+```js
+(function () {
+  try {
+    var stored = localStorage.getItem("theme");
+    var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    if (stored === "dark" || (!stored && prefersDark)) {
+      document.documentElement.classList.add("dark");
+    }
+  } catch (e) {}
+})();
+```
+
+Reference it from `app/root.tsx` so it loads before any React hydration:
+
+```tsx
+import { Outlet, Meta, Links, Scripts, ScrollRestoration } from "@remix-run/react";
+
+export default function App() {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <Meta />
+        <Links />
+        <script src="/theme-bootstrap.js" />
+      </head>
+      <body>
+        <Outlet />
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+```
+
+For runtime toggling inside React components, use `useColorMode`:
+
+```tsx
+import { useColorMode } from "@devalok/shilp-sutra/hooks/use-color-mode";
+
+export function ThemeToggle() {
+  const { mode, toggle } = useColorMode();
+  return (
+    <button onClick={toggle} aria-label="Toggle theme">
+      {mode === "dark" ? "☀" : "☾"}
+    </button>
+  );
+}
+```
+
+## 6. Toaster (optional)
+
+Mount once in `app/root.tsx` next to `<Outlet />`:
+
+```tsx
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+
+// inside <body>
+<>
+  <Outlet />
+  <Toaster />
+</>
+```
+
+## 7. Verify
+
+Create `app/routes/_index.tsx`:
+
+```tsx
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+
+export default function Index() {
+  return (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+      </Stack>
+    </Stack>
+  );
+}
+```
+
+Run `pnpm dev` and open the URL.
+
+## 8. Remix-specific gotchas
+
+- **`?url` suffix on CSS imports.** Without it, Vite tries to inline the CSS, which breaks Tailwind processing.
+- **Loaders are server-only.** Do not import shilp-sutra components inside a `loader` function — they will not render.
+- **Server-rendered output.** Remix SSRs every route. The CSS-in-JS-free approach of shilp-sutra works perfectly here; no extra config needed.
+- **`framer-motion` and SSR.** All shilp-sutra animations gracefully degrade for the initial server render. No special handling required.
+- **CSP.** If your CSP blocks inline scripts, the `theme-bootstrap.js` static asset above already complies (no `unsafe-inline` needed).
+
+## 9. What NOT to do
+
+- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Skip the `?url` suffix on CSS imports.
+- ❌ Mount `<Toaster />` inside route components — it should live once at the root.

package/docs/recipes/install-tanstack-start.md

@@ -0,0 +1,143 @@
+# Install: TanStack Start
+
+> Setup recipe for adding `@devalok/shilp-sutra` to a TanStack Start project (the React full-stack framework built on Vinxi/Vite).
+
+## 1. Detect
+
+You are in this recipe if:
+
+- `package.json` lists `"@tanstack/start"` and `"@tanstack/react-router"`
+- `app.config.{ts,js}` (Vinxi) exists at the project root
+- `app/router.tsx` and `app/routes/__root.tsx` exist
+
+## 2. Install
+
+```bash
+pnpm add @devalok/shilp-sutra framer-motion
+pnpm add -D tailwindcss@^4 @tailwindcss/vite
+```
+
+Optional:
+
+```bash
+pnpm add sonner   # only if rendering <Toaster />
+```
+
+## 3. Wire Tailwind 4 in `app.config.ts`
+
+```ts
+import { defineConfig } from "@tanstack/start/config";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});
+```
+
+## 4. Wire tokens
+
+Create `app/styles/globals.css`:
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+Import it from `app/routes/__root.tsx`:
+
+```tsx
+import "../styles/globals.css";
+```
+
+If you prefer asset-URL imports the way Remix does it, use `import css from "../styles/globals.css?url"` and add `<link rel="stylesheet" href={css} />` to the `<head>` returned by `__root.tsx`.
+
+## 5. Theme toggle
+
+Create `public/theme-bootstrap.js` (a static asset served verbatim):
+
+```js
+(function () {
+  try {
+    var stored = localStorage.getItem("theme");
+    var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+    if (stored === "dark" || (!stored && prefersDark)) {
+      document.documentElement.classList.add("dark");
+    }
+  } catch (e) {}
+})();
+```
+
+Reference it from `app/routes/__root.tsx`:
+
+```tsx
+import { createRootRoute, Outlet } from "@tanstack/react-router";
+
+export const Route = createRootRoute({
+  component: () => (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script src="/theme-bootstrap.js" />
+      </head>
+      <body>
+        <Outlet />
+      </body>
+    </html>
+  ),
+});
+```
+
+For runtime toggling, use the `useColorMode` hook — see [install-vite.md § 5](./install-vite.md#5-theme-toggle-no-next-themes-here).
+
+## 6. Toaster (optional)
+
+Mount in `__root.tsx` next to `<Outlet />`:
+
+```tsx
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+
+// inside <body>
+<>
+  <Outlet />
+  <Toaster />
+</>
+```
+
+## 7. Verify
+
+Create or replace `app/routes/index.tsx`:
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { Button } from "@devalok/shilp-sutra/ui/button";
+import { Stack } from "@devalok/shilp-sutra/ui/stack";
+import { Text } from "@devalok/shilp-sutra/ui/text";
+
+export const Route = createFileRoute("/")({
+  component: () => (
+    <Stack className="p-ds-08" gap="ds-04">
+      <Text variant="heading-2xl">Hello, Shilp Sutra</Text>
+      <Stack direction="row" gap="ds-03">
+        <Button>Primary</Button>
+        <Button variant="soft">Soft</Button>
+      </Stack>
+    </Stack>
+  ),
+});
+```
+
+Run `pnpm dev` and open the URL.
+
+## 8. TanStack Start specifics
+
+- **Server functions** (`createServerFn`) — do not import shilp-sutra components inside server functions; they run server-only.
+- **Streaming SSR** is the default. All shilp-sutra components SSR cleanly because they have no client-only side effects at module top-level.
+- **`framer-motion` SSR** — animations gracefully degrade on the initial render.
+- **CSP.** The static `theme-bootstrap.js` asset complies with strict CSP (no inline scripts required).
+
+## 9. What NOT to do
+
+- ❌ Add `tailwind.config.{ts,js}` — Tailwind 4 is CSS-first.
+- ❌ Mount `<Toaster />` inside route components — it should live once at the `__root`.
+- ❌ Mix `@tailwindcss/postcss` and `@tailwindcss/vite` — pick one (Vite plugin recommended for TanStack Start).