@devalok/shilp-sutra 0.53.0 → 0.55.0

package/docs/components/composed/rich-chat-input.md

@@ -9,19 +9,24 @@ Compact rich text chat input for unified human+AI workspaces. Built on TipTap.
 ## Props
 
 ### RichChatInputProps
-    onSubmit: (html: string, plainText: string) => void (REQUIRED)
+    onSubmit: (message: RichChatInputMessage) => void (REQUIRED)
     placeholder: string (default: "Type a message...")
     disabled: boolean (default: false)
-    variant: 'compact' | 'expanded' | 'minimal' (default: 'compact')
-    maxRows: number
+    content: string — initial HTML (not reactive; use for message editing)
+    variant: 'compact' | 'expanded' | 'minimal' | 'inline' (default: 'compact')
     enterBehavior: 'send' | 'newline' (default: 'send')
     maxLength: number — enables character counter
+    charCountDisplay: 'always' | 'focus' | 'near-limit' | 'hidden' (default: 'near-limit')
     mentions: MentionItem[] — static list for @mention autocomplete
     onMentionSearch: (query: string) => Promise<MentionItem[]> — async search
     onMentionSelect: (item: MentionItem) => void
     onFileUpload: (file: File) => Promise<{ url: string; name: string; size: number }>
     onImageUpload: (file: File) => Promise<string>
     slashCommands: SlashCommandGroup[] — enables / command palette
+    onVoiceRecord: (audio: Blob, duration: number) => void
+    onTranscribe: (blob: Blob, duration: number) => Promise<string | null> — transcribe after recording; return null to attach as a voice note
+    maxDuration: number — max voice-recording seconds
+    replyTo: { id: string; author: string; preview: string; onDismiss: () => void } — reply banner above the input
     onTyping: (isTyping: boolean) => void — typing indicator callback
     onEmpty: (isEmpty: boolean) => void
     isStreaming: boolean (default: false) — shows stop button instead of send
@@ -29,9 +34,15 @@ Compact rich text chat input for unified human+AI workspaces. Built on TipTap.
     leadingSlot: ReactNode — rendered above the editor
     trailingSlot: ReactNode — rendered below the toolbar
     disclaimer: string — small text below the input
-    toolbar: boolean | ChatToolbarItem[] (default: true)
+    toolbar: boolean | ChatToolbarItem[] | ReactNode (default: true) — true = default toolbar, array = whitelist, ReactNode = custom, false = hidden
+    actionButton: ReactNode | false — custom left-side button (replaces the default attach button; false hides it)
+    emojiSet: 'native' | 'apple' | 'google' | 'twitter' | 'facebook' (default: 'native')
+    onSchedule: (message: RichChatInputMessage, scheduledAt: Date) => void — if set, a schedule button appears next to send
+    sendOptions: Array<{ label: string; icon?: ComponentType<{ className?: string }>; onSelect: () => void }> — split-send dropdown options
 
-ChatToolbarItem: 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'code' | 'bulletList' | 'orderedList' | 'mention' | 'emoji' | 'attach' | 'slash'
+RichChatInputMessage: { html: string; plainText: string; attachments?: Array<{ url: string; name: string; size: number; type: string }>; voiceNote?: { blob: Blob; duration: number } }
+
+ChatToolbarItem: 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'code' | 'bulletList' | 'orderedList' | 'blockquote' | 'link' | 'mention' | 'emoji' | 'slash'
 
 MentionItem: { id: string; label: string; avatar?: string }
 
@@ -43,11 +54,12 @@ SlashCommandGroup: { label: string; commands: SlashCommand[] }
 - `compact` (default) — 2-3 lines, inline toolbar
 - `expanded` — 5+ lines, always-visible toolbar, suited for AI prompts
 - `minimal` — single line, toolbar appears on focus
+- `inline` — 40px min-height, no toolbar; for tight inline composers
 
 ## Example
 ```jsx
 <RichChatInput
-  onSubmit={(html, text) => sendMessage(html)}
+  onSubmit={(message) => sendMessage(message.html)}
   mentions={teamMembers}
   onFileUpload={uploadFile}
   slashCommands={[{ label: 'Actions', commands: [...] }]}

package/docs/components/composed/simple-tooltip.md

@@ -24,7 +24,7 @@
 ## Composability
 - **One-liner Tooltip** — wraps TooltipProvider + Tooltip + TooltipTrigger + TooltipContent so consumers don't have to manually compose them for a simple label.
 - **When to use:** 90% of tooltip use cases (icon-only button labels, abbreviated text expansions, secondary info). Use the ui/Tooltip compound for advanced cases (controlled open, nested triggers, custom animations).
-- **Auto-provides its own TooltipProvider** — safe to drop anywhere. You can still wrap a broader TooltipProvider at layout level for shared `delayDuration`; SimpleTooltip respects it if present.
+- **Always mounts its own TooltipProvider** — safe to drop anywhere. Note it does NOT inherit an ancestor `TooltipProvider`'s `delayDuration`; its own `delayDuration` prop (default 300ms) always wins. Set it per-tooltip via the prop.
 - **Content must be inert** — same rule as ui/Tooltip. For interactive popped content, use Popover or HoverCard.
 - **Pairs with IconButton** — the canonical pattern for labeled icon buttons.
 

package/docs/components/shell/app-command-palette.md

@@ -23,7 +23,7 @@ AppCommandPaletteUser: { name: string, role?: string }
 ## Example
 ```jsx
 <AppCommandPalette
-  user={{ name: 'John', role: 'admin' }}
+  user={{ name: 'John', role: 'Admin' }}
   isAdmin={true}
   onNavigate={(path) => router.push(path)}
   searchResults={results}
@@ -42,6 +42,7 @@ AppCommandPaletteUser: { name: string, role?: string }
 ## Gotchas
 - Uses CommandRegistry context for page navigation items (see CommandRegistryProvider)
 - `isAdmin` takes precedence over `user.role` for showing admin command groups
+- **Role detection is case-sensitive:** `user.role` only auto-enables admin groups when it is exactly `'Admin'` or `'SuperAdmin'`. `'admin'` (lowercase) silently shows nothing — pass `isAdmin` explicitly if your role strings differ.
 - Should be placed at the app root level, typically alongside TopBar
 
 ## Changes

package/docs/components/shell/bottom-navbar.md

@@ -36,11 +36,11 @@ BottomNavbarUser: { name: string, role?: string }
 ```
 
 ## Composability
-- **Mobile-only bottom nav** — fixed to bottom of viewport. Desktop should use AppSidebar instead.
-- **Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render AppSidebar (desktop) or BottomNavbar (mobile). Example:
+- **Mobile-only bottom nav** — fixed to bottom of viewport. Desktop should use Sidebar instead.
+- **Responsive switch pattern:** Use `useIsMobile()` hook to conditionally render Sidebar (desktop) or BottomNavbar (mobile). Example:
   ```jsx
   const isMobile = useIsMobile()
-  return isMobile ? <BottomNavbar ... /> : <AppSidebar ... />
+  return isMobile ? <BottomNavbar ... /> : <Sidebar ... />
   ```
 - **Primary vs overflow:** `primaryItems` (max 4) for the always-visible slots; `moreItems` go into a "More" sheet that opens on tap. Don't exceed 4 primary — the bar becomes cramped.
 - **Router integration via LinkProvider:** Each nav item is rendered using the framework-specific Link component registered in LinkProvider. Without LinkProvider, you get full-page reloads on tap.
@@ -54,7 +54,7 @@ BottomNavbarUser: { name: string, role?: string }
 ## Gotchas
 - Designed for mobile viewports — fixed to bottom of screen
 - Max 4 `primaryItems` recommended; overflow goes in `moreItems` shown in a "More" sheet
-- Use with `useIsMobile()` hook to conditionally render instead of AppSidebar
+- Use with `useIsMobile()` hook to conditionally render instead of Sidebar
 - Requires LinkProvider for framework-specific link components (e.g., Next.js Link)
 
 ## Changes

package/docs/components/shell/command-registry.md

@@ -13,7 +13,7 @@ Exports: CommandRegistryProvider, useCommandRegistry
     registry: CommandRegistry (REQUIRED)
 
 CommandRegistry: { pages: CommandPageItem[], adminPages: CommandPageItem[] }
-CommandPageItem: { id: string, label: string, icon: ReactNode, path: string, keywords?: string[] }
+CommandPageItem: { id: string, label: string, icon: IconInput, path: string, keywords?: string[] }
 
 ### useCommandRegistry hook
     Returns: CommandRegistry | null
@@ -41,7 +41,7 @@ CommandPageItem: { id: string, label: string, icon: ReactNode, path: string, key
 ## Composability
 - **Context provider for AppCommandPalette.** Registers page-level navigation items that the command palette surfaces as commands.
 - **Place at app root** — wrap both AppCommandPalette and the rest of the app inside `<CommandRegistryProvider>`. Positioning matters: any AppCommandPalette outside the provider gets `useCommandRegistry() === null` and falls back to minimal functionality.
-- **Separation of pages vs adminPages** — the palette filters based on user role / `isAdmin` flag. Keep admin-only routes in the adminPages array to avoid leaking them to regular users.
+- **Separation of pages vs adminPages** — this is an ORGANIZATIONAL split, not access control. The component does NOT enforce anything: YOU populate `adminPages` conditionally (e.g. only when the signed-in user is an admin). Anything you put in `adminPages` is still shipped to the client — do real authorization on the server, not here.
 - **useCommandRegistry()** is the consumer hook — returns the full registry or null. Use in your own command-aware components (e.g. a Spotlight-style keyboard-search embed elsewhere in the app).
 - **Works with LinkProvider** — CommandPaletteItems navigate via `onNavigate` prop on AppCommandPalette, which routes to your framework's Link component.
 

package/docs/components/shell/link-context.md

@@ -23,13 +23,13 @@ Exports: LinkProvider, useLink
 import Link from 'next/link'
 
 <LinkProvider component={Link}>
-  <AppSidebar ... />
+  <Sidebar ... />
   <BottomNavbar ... />
 </LinkProvider>
 ```
 
 ## Composability
-- **The framework router bridge for all shell components.** Without LinkProvider, AppSidebar / BottomNavbar / TopBar.UserMenu / AppCommandPalette render plain `<a>` tags — that means full page reloads instead of client-side navigation.
+- **The framework router bridge for all shell components.** Without LinkProvider, Sidebar / BottomNavbar / TopBar.UserMenu / AppCommandPalette render plain `<a>` tags — that means full page reloads instead of client-side navigation.
 - **Required setup:**
   ```tsx
   // Next.js

package/docs/components/shell/top-bar.md

@@ -120,7 +120,7 @@ UserMenuItem fields:
 - **NotificationCenter lives inside TopBar.Right** — it's a complete bell+popover component. Drop it in a TopBar.Section next to other icon buttons.
 - **UserMenu is composable:** `userMenuItems` inserts custom items between the built-in Profile and the color-mode toggle. Each item can navigate (href), run an action (onClick), or show a separator/badge/color decoration.
 - **Responsive hiding:** Actions that shouldn't appear on mobile use `className="hidden md:flex"` on the IconButton — the component doesn't enforce mobile hiding; that's layout responsibility.
-- **Pairs with AppSidebar** — desktop app shell is typically `<TopBar>` + `<AppSidebar>` + main content region.
+- **Pairs with Sidebar** — desktop app shell is typically `<TopBar>` + `<Sidebar>` + main content region.
 
 ## Gotchas
 - Without `TopBar.Center`, layout is flex (two-zone). With it, layout switches to CSS grid `1fr auto 1fr` for true centering.

package/docs/components/ui/search-input.md

@@ -5,7 +5,7 @@
 - Category: ui
 
 ## Props
-    size: "sm" | "md" | "lg"
+    size: "xs" | "sm" | "md" | "lg"
     loading: boolean (shows spinner instead of clear button)
     onClear: () => void (shows X button when value is non-empty)
     value: string
@@ -31,7 +31,7 @@
 - **`onClear` makes the X button appear** only when `value` is non-empty. Pair them so users can reset.
 - **`loading={true}` swaps the clear button for a spinner** with `aria-busy="true"` on the input — useful for debounced/async search.
 - Doesn't auto-consume FormField (no `state` prop) — wrap a regular Input inside FormField for validated search fields.
-- Keyboard: Escape auto-triggers `onClear` when wired (handled via `type="search"`'s native behavior on most browsers).
+- Keyboard: Escape is NOT wired to clear (the input is not `type="search"`). Reset via the X button, or handle Escape yourself and call your `value` setter.
 
 ## Gotchas
 - HTML native "size" attribute is excluded — use CSS width instead

package/docs/components/ui/slider.md

@@ -22,14 +22,14 @@
 - Radix Slider primitive — keyboard navigation (arrow keys, Home/End, PageUp/PageDown) pre-wired.
 - **Value is always an array** — single-thumb: `[50]`; range: `[25, 75]`. Don't pass a plain number.
 - **Multi-thumb range:** Pass `[start, end]` — renders two thumbs that can cross each other by default. Use `minStepsBetweenThumbs` to enforce a gap.
-- **FormField:** Slider does NOT auto-consume FormField state. No validation UX — sliders usually don't need it (values are always valid by construction).
+- **FormField:** Slider consumes FormField for a11y wiring (`aria-invalid` / `aria-describedby` / `aria-required`) but renders no visual validation treatment — values are valid by construction, so there's no error UX to hand-wire.
 - **No label pairing via Label** — use `aria-label` or `aria-labelledby` directly on the Slider. The thumb is the focusable/labeled element.
 - Not portal-rendered — inline; overflow rules of parents apply.
 
 ## Gotchas
 - value is number[] (array), not a single number
 - Multi-thumb: Pass array `defaultValue={[25, 75]}` for range sliders — renders one thumb per value
-- Slider does NOT auto-consume FormField — sliders don't have validation state visuals by design
+- Slider consumes FormField for a11y wiring (aria-invalid/describedby/required) but shows no validation visuals by design — don't hand-wire what it already does
 
 ## Changes
 ### v0.18.0

package/docs/components/ui/split-button.md

@@ -37,9 +37,9 @@ import { SplitButton } from '@devalok/shilp-sutra'
 
 ## Composability
 - **Two-in-one button:** visually unified `[Action | ▼]` with the left half being the primary click and the right half opening a dropdown. Use for actions that have a most-common choice plus alternatives (Save vs. Save-As-Draft, Send vs. Schedule).
-- **Built on Button + Popover internally** — inherits Button's variant/color/size vocabulary and Popover's placement prop (`top-end` default works for most top-of-page toolbars).
+- **Composes the DS Popover internally** and shares the `color` type + a `variant`/`size` subset with Button (currently `solid`/`soft`/`outline` × the Button colors; no `ghost`/`link`/`lg`). Note: the half styling is implemented locally, not inherited from `Button` — a few Button niceties (e.g. `solid`'s `hover:shadow-brand`) don't apply. Popover placement via `top-end` default suits most top-of-page toolbars.
 - **Dropdown content is consumer-provided** — pass any JSX via `dropdownContent` (typically a DropdownMenu, list of actions, a custom panel, or a small form). Don't try to shove a full-featured menu into the chevron; keep it focused on 2–5 alternatives.
-- **ButtonGroup compatibility:** Put SplitButton inside a `<ButtonGroup>` — it inherits variant/color/size from the group context just like Button does. Position-aware corners work too.
+- **ButtonGroup:** SplitButton does NOT consume `ButtonGroup` context — set its `variant`/`color`/`size` explicitly to match a surrounding group.
 - **Controlled dropdown:** Pass `open` + `onOpenChange` for controlled state; omit for uncontrolled. Useful when the dropdown must close programmatically after a selection.
 
 ## Gotchas
@@ -49,7 +49,7 @@ import { SplitButton } from '@devalok/shilp-sutra'
 ## Changes
 
 ### v0.44.2
-- **Fixed** The dropdown is now keyboard-accessible. It previously used a hand-rolled floating panel (`role="menu"`) with no focus management, arrow keys, or Escape — keyboard users couldn't reach or dismiss it. It now composes the DS **Popover** primitive: focus moves in on open, Escape and outside-click close, focus returns to the trigger, and on mobile it opens as a bottom sheet. (Full menu semantics with arrow-key item navigation via DropdownMenu are planned for 0.45.0.)
+- **Fixed** The dropdown is now keyboard-accessible. It previously used a hand-rolled floating panel (`role="menu"`) with no focus management, arrow keys, or Escape — keyboard users couldn't reach or dismiss it. It now composes the DS **Popover** primitive: focus moves in on open, Escape and outside-click close, focus returns to the trigger, and on mobile it opens as a bottom sheet.
 
 ### v0.33.0
 - **Added** Initial release

package/docs/recipes/install-astro.md

@@ -38,6 +38,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@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 remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

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

@@ -51,6 +51,8 @@ Some components depend on third-party libraries that ship as optional peers. **I
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@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 remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

package/docs/recipes/install-remix.md

@@ -34,6 +34,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@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 remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

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

@@ -43,6 +43,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@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 remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

package/docs/recipes/install-vite.md

@@ -49,6 +49,8 @@ Some components ship hard peers as optional. **Install BEFORE first import.**
 | `@devalok/shilp-sutra/composed/date-picker` | `pnpm add date-fns` |
 | `@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 remark-gfm` |
+| `@devalok/shilp-sutra/composed/rich-chat-input` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
+| `@devalok/shilp-sutra/composed/rich-text-editor` | `pnpm add -D @tiptap/pm @tiptap/react` *(types only — the runtime is bundled)* |
 | `@devalok/shilp-sutra/composed/schedule-view` | `pnpm add date-fns` |
 | `@devalok/shilp-sutra/ui/charts` | `pnpm add d3-axis d3-scale d3-selection d3-shape` |
 | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |

package/docs/recipes/troubleshoot.md

@@ -196,6 +196,8 @@ In dev mode, calling `toast()` without a mounted `<Toaster />` logs a one-time c
 
 **Diagnosis:** Should not happen since v0.37.0 — `use-sync-external-store` was moved to runtime dependencies and is auto-installed transitively.
 
+**Why this dependency exists at all** (it is a hook built into React 18+, so it looks redundant): we do not use the shim ourselves. It is a TipTap transitive. TipTap's code is bundled into our `dist`, and that bundled chunk imports `use-sync-external-store/shim`. We externalize the shim rather than bundling it, because bundling forced a `createRequire` bridge into our Rollup runtime chunk that broke every Turbopack consumer. Externalized code must be resolvable from the consumer's tree, hence the declaration.
+
 If it still happens, install it explicitly:
 
 ```bash
@@ -204,6 +206,84 @@ 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: `Cannot find package 'sonner'` when you only imported a hook (or `'react-markdown'` from the AI barrel)
+
+**Diagnosis:** you imported a *barrel* rather than the component itself, and the barrel re-exports something with an optional peer.
+
+- `@devalok/shilp-sutra/hooks` re-exports `toast`, which needs `sonner`.
+- `@devalok/shilp-sutra/ai` re-exports the block renderer, which needs `react-markdown`.
+
+A bundler tree-shakes the unused branch away, so this is invisible in a client build. It bites at **runtime in Node** — SSR, a route handler, a test — where the import is evaluated for real.
+
+Fix — import the specific module instead of the barrel:
+
+```ts
+// needs sonner installed, because the barrel also exports toast
+import { useIsMobile } from '@devalok/shilp-sutra/hooks'
+
+// no optional peers at all
+import { useIsMobile } from '@devalok/shilp-sutra/hooks/use-mobile'
+```
+
+Every hook has its own subpath: `use-mobile`, `use-color-mode`, `use-touch-device`, `use-viewport-height`. Same rule applies across the library — a deep import never costs you more than that component needs.
+
+## Symptom: `error TS2305: Module '"react"' has no exported member 'ReactSVG'`
+
+**This is an upstream `@tabler/icons-react` bug, not a shilp-sutra one** — but you will hit it following our install instructions, so it is documented here.
+
+`@tabler/icons-react` (through 3.45.0, the current release) opens its type declarations with:
+
+```ts
+import { ReactSVG, … } from 'react'
+```
+
+React 18's types exported `ReactSVG`; React 19's removed it, keeping only `ReactSVGElement`. So on React 19 the icon package's own `.d.ts` fails to compile.
+
+You only see it with **all three**: React 19, `skipLibCheck: false`, and a direct `@tabler/icons-react` import in your own code. React 18 is unaffected, and the default `skipLibCheck: true` suppresses it.
+
+Workarounds, in order of preference:
+
+1. Leave `skipLibCheck: true` (the default in every framework scaffold). It suppresses errors inside dependency declarations — including this one.
+2. Import icons through our re-export instead of directly, so the broken declaration is never loaded into your program.
+3. Pin `@types/react` to 18 if your app is still on React 18.
+
+There is nothing to fix on our side: we neither wrap nor re-declare Tabler's types. Track it upstream at <https://github.com/tabler/tabler-icons/issues>.
+
+## Symptom: `error TS2307: Cannot find module '@devalok/shilp-sutra/ui/button'` under `"moduleResolution": "node"`
+
+**Diagnosis:** You are on TypeScript's legacy resolution mode, which predates and ignores the `exports` field in `package.json`. Our files live under `dist/`, and every public path is mapped through `exports` — legacy resolution looks for a literal `node_modules/@devalok/shilp-sutra/ui/button.js` and finds nothing.
+
+**Supported resolution modes:**
+
+| `moduleResolution` | Supported | Notes |
+|---|---|---|
+| `bundler` | ✅ | Recommended. Vite, Next.js, and most modern setups default to this. |
+| `node16` / `nodenext` | ✅ | Fully supported since 0.55.0. |
+| `node` (legacy) | ❌ | Cannot read `exports`. No subpath resolves. |
+
+Fix — in your `tsconfig.json`:
+
+```jsonc
+{ "compilerOptions": { "moduleResolution": "bundler" } }
+```
+
+## Symptom: `require('@devalok/shilp-sutra')` throws `ERR_REQUIRE_ESM`
+
+**Diagnosis:** The package is ESM-only — we ship no CommonJS build. Whether `require()` works depends on your Node version:
+
+| Node | `require('@devalok/shilp-sutra/ui/button')` |
+|---|---|
+| 22.12+ / 23+ | ✅ Works — `require(esm)` is supported and unflagged. Verified against every entry point, including the full `./ui` barrel. |
+| < 22.12 | ❌ `ERR_REQUIRE_ESM` |
+
+On older Node, use a dynamic import:
+
+```js
+const { Button } = await import('@devalok/shilp-sutra/ui/button')
+```
+
+Or move the consuming file to ESM (`"type": "module"`, or a `.mjs` extension). Every supported framework target — Next.js, Vite, Remix, Astro, TanStack Start — handles the ESM entry natively; this only affects hand-written CJS scripts.
+
 ## 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.

package/llms.txt

@@ -1,6 +1,6 @@
 # @devalok/shilp-sutra
 
-> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.53.0.
+> Radix UI + Tailwind 4 (CSS-first) + CVA design system for Devalok apps, v0.55.0.
 > Built on the same primitives as shadcn/ui but with DIFFERENT prop APIs — never guess from shadcn knowledge; verify every prop.
 > This file is a ROUTER: it tells you what exists and where to get details. Do not look for prop tables here — fetch them per component (MCP tool or per-component doc file below).
 
@@ -92,6 +92,7 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 - [select](docs/components/ui/select.md)
 - [separator](docs/components/ui/separator.md)
 - [sheet](docs/components/ui/sheet.md)
+- [sidebar](docs/components/ui/sidebar.md)
 - [skeleton](docs/components/ui/skeleton.md)
 - [slider](docs/components/ui/slider.md)
 - [spinner](docs/components/ui/spinner.md)
@@ -156,7 +157,6 @@ Format: `[name](doc path): summary`. Import paths follow `@devalok/shilp-sutra/<
 - [link-context](docs/components/shell/link-context.md): Exports: LinkProvider, useLink
 - [notification-center](docs/components/shell/notification-center.md)
 - [notification-preferences](docs/components/shell/notification-preferences.md)
-- [sidebar](docs/components/shell/sidebar.md)
 - [top-bar](docs/components/shell/top-bar.md)
 
 ### ai

package/make-kit/Guidelines.md

@@ -34,7 +34,7 @@ These are not preferences. Generated code that violates them is wrong.
 
 ## Workflow — before generating any screen
 
-1. **Identify the layout shell.** AppSidebar + TopBar for product pages. Container + Stack for marketing. Dialog/Sheet for modal flows.
+1. **Identify the layout shell.** Sidebar + TopBar for product pages. Container + Stack for marketing. Dialog/Sheet for modal flows.
 2. **Pick the surface for each region.** Read `foundations/surfaces.md`. Default page bg is `surface-base`; everything else stacks up from there.
 3. **Pick components from `components/overview.md`.** That file has decision trees for the common confusions (Button variant, Input vs Combobox vs Autocomplete, Dialog vs Sheet vs Popover).
 4. **Lay things out with `<Stack>` + `<Container>`.** Use `gap-ds-03/05/07`. Don't reach for arbitrary flex divs.

package/make-kit/components/overview.md

@@ -116,7 +116,7 @@ Top of every page?
   → <TopBar> (shell)
 
 Side nav (product)?
-  → <AppSidebar> (shell) — collapsible, with sections, footer
+  → <Sidebar> primitives (ui) — or the sidebar-app preset (shilp-sutra.devalok.in/presets)
 
 Tabs within a page?
   → <Tabs>            — horizontal default
@@ -279,7 +279,7 @@ Code?
 | Pagination | `/ui/pagination` |
 | Stepper | `/ui/stepper` |
 | NavigationMenu | `/ui/navigation-menu` |
-| Sidebar (AppSidebar) | `/shell/sidebar` |
+| Sidebar | `/ui/sidebar` |
 | TopBar | `/shell/top-bar` |
 | BottomNavbar | `/shell/bottom-navbar` |
 

package/make-kit/foundations/surfaces.md

@@ -109,7 +109,7 @@ In dark mode the kit lightens surfaces with elevation (so `surface-overlay` is *
 </div>
 ```
 
-(In practice you wouldn't write the `bg-*` / `shadow-*` directly — `<Card>`, `<DialogContent>`, `<AppSidebar>` apply them. This is just the layer model.)
+(In practice you wouldn't write the `bg-*` / `shadow-*` directly — `<Card>`, `<DialogContent>`, `<Sidebar>` apply them. This is just the layer model.)
 
 ## Rules