@devalok/shilp-sutra 0.38.0 → 0.40.0

package/skill/references/setup-remix.md

@@ -0,0 +1,188 @@
+<!-- Source: packages/core/docs/recipes/install-remix.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
+
+# 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 />
+```
+
+### 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
+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/skill/references/setup-tanstack-start.md

@@ -0,0 +1,160 @@
+<!-- Source: packages/core/docs/recipes/install-tanstack-start.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
+
+# 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 />
+```
+
+### 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
+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).

package/skill/references/setup-vite.md

@@ -0,0 +1,187 @@
+<!-- Source: packages/core/docs/recipes/install-vite.md — do not edit directly. Regenerate with `node scripts/build-skill.mjs`. -->
+
+# Install: Vite + React
+
+> Setup recipe for adding `@devalok/shilp-sutra` to a Vite + React SPA.
+
+## 1. Detect
+
+You are in this recipe if:
+
+- `vite.config.{ts,js,mjs}` exists at the project root
+- `package.json` lists `"vite"` and `"react"`
+- `src/main.{tsx,jsx}` is the entry that calls `createRoot(...).render(<App />)`
+
+This recipe also covers Vite + React + React Router (any version) — the design system is router-agnostic.
+
+If you are using Remix (which now runs on Vite), use [install-remix.md](./install-remix.md). If you are using TanStack Start, use [install-tanstack-start.md](./install-tanstack-start.md).
+
+## 2. Install dependencies
+
+```bash
+# pnpm
+pnpm add @devalok/shilp-sutra framer-motion
+pnpm add -D tailwindcss@^4 @tailwindcss/vite
+
+# npm
+npm install @devalok/shilp-sutra framer-motion
+npm install -D tailwindcss@^4 @tailwindcss/vite
+
+# yarn
+yarn add @devalok/shilp-sutra framer-motion
+yarn add -D tailwindcss@^4 @tailwindcss/vite
+
+# bun
+bun add @devalok/shilp-sutra framer-motion
+bun add -d tailwindcss@^4 @tailwindcss/vite
+```
+
+Add only if rendering `<Toaster />`:
+
+```bash
+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):
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tailwindcss from "@tailwindcss/vite";
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+If the project already uses PostCSS for other reasons, you can use `@tailwindcss/postcss` instead — see [install-next-app-router.md § 3](./install-next-app-router.md#3-configure-postcss). Stick with one approach; do not load both.
+
+## 4. Wire tokens in the global CSS
+
+Common CSS entry paths in priority order:
+
+- `src/index.css`
+- `src/main.css`
+- `src/styles/globals.css`
+- `src/App.css`
+
+If none exists, create `src/index.css`. Set or merge:
+
+```css
+@import "tailwindcss";
+@import "@devalok/shilp-sutra/css";
+```
+
+Import it once from the entry (`src/main.tsx`):
+
+```tsx
+import "./index.css";
+```
+
+## 5. Theme toggle (no `next-themes` here)
+
+Vite has no built-in theme provider. Use the design system's `useColorMode` hook with a small bootstrap script to avoid a flash of wrong theme.
+
+Add the bootstrap to `index.html` (in `<head>`, before any stylesheet):
+
+```html
+<script>
+  (function () {
+    try {
+      var stored = localStorage.getItem("theme");
+      var prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+      var dark = stored === "dark" || (!stored && prefersDark);
+      if (dark) document.documentElement.classList.add("dark");
+    } catch (e) {}
+  })();
+</script>
+```
+
+Wire the runtime hook from anywhere in the app (e.g., a header button):
+
+```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. Mount Toaster (optional)
+
+If you installed `sonner`, mount the Toaster once near the app root:
+
+```tsx
+// src/main.tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { Toaster } from "@devalok/shilp-sutra/ui/toaster";
+import { App } from "./App";
+import "./index.css";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+    <Toaster />
+  </StrictMode>,
+);
+```
+
+## 7. Verify
+
+Replace `src/App.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 function App() {
+  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 printed Vite URL. Expected output matches [Next App Router § 7](./install-next-app-router.md#7-verify-the-install).
+
+## 8. Gotchas (Vite-specific)
+
+- **`@tailwindcss/vite` and `@tailwindcss/postcss` together.** Pick one — running both causes utilities to be processed twice and CSS bloat.
+- **CSS import paths in HMR.** Vite is strict about case-sensitivity even on macOS. `@devalok/shilp-sutra/CSS` will not resolve; use the lowercase `/css`.
+- **Multiple framer-motion copies.** Same fix as Next — see [install-next-app-router.md § 8](./install-next-app-router.md#8-common-gotchas).
+- **Spacing utilities.** Use `p-ds-04` (not `p-4`). Tailwind composite text utilities: `text-heading-xl`, `text-body-md`, `text-code`.
+
+## 9. What NOT to do
+
+- ❌ Add `@devalok/shilp-sutra/tailwind` — the export was removed in 0.38.
+- ❌ Add a `tailwind.config.{ts,js}` with `presets: [shilpSutra]` — JS preset removed.
+- ❌ Try to use `next-themes` here — it requires Next. Use the bootstrap script + `useColorMode` shown in § 5.