@devalok/shilp-sutra 0.39.0 → 0.40.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (220) hide show
  1. package/AGENTS.md +156 -0
  2. package/MIGRATION.md +149 -0
  3. package/README.md +4 -1
  4. package/dist/_chunks/badge-group.js +75 -74
  5. package/dist/_chunks/badge-group.js.map +1 -1
  6. package/dist/_chunks/chart-container.js +50 -0
  7. package/dist/_chunks/chart-container.js.map +1 -0
  8. package/dist/_chunks/chat.js +231 -223
  9. package/dist/_chunks/chat.js.map +1 -1
  10. package/dist/_chunks/colors.js +30 -0
  11. package/dist/_chunks/colors.js.map +1 -0
  12. package/dist/_chunks/emoji-data.js +45 -0
  13. package/dist/_chunks/emoji-data.js.map +1 -0
  14. package/dist/_chunks/grid-lines.js +72 -0
  15. package/dist/_chunks/grid-lines.js.map +1 -0
  16. package/dist/_chunks/mention-suggestion.js +31 -259
  17. package/dist/_chunks/mention-suggestion.js.map +1 -1
  18. package/dist/_chunks/normalize-icon.js +18 -0
  19. package/dist/_chunks/normalize-icon.js.map +1 -0
  20. package/dist/_chunks/oauth-button.js +227 -0
  21. package/dist/_chunks/oauth-button.js.map +1 -0
  22. package/dist/_chunks/primitives.js +107 -107
  23. package/dist/_chunks/primitives.js.map +1 -1
  24. package/dist/_chunks/{text.js → success.js} +24 -61
  25. package/dist/_chunks/success.js.map +1 -0
  26. package/dist/_chunks/tiptap.js +1952 -1949
  27. package/dist/_chunks/tiptap.js.map +1 -1
  28. package/dist/_chunks/tooltip.js +58 -0
  29. package/dist/_chunks/tooltip.js.map +1 -0
  30. package/dist/_chunks/tree-view.js +101 -96
  31. package/dist/_chunks/tree-view.js.map +1 -1
  32. package/dist/ai/ai-command-provider.d.ts +3 -2
  33. package/dist/ai/ai-command-provider.d.ts.map +1 -1
  34. package/dist/ai/ai-command-provider.js.map +1 -1
  35. package/dist/ai/block-renderer.js +11 -9
  36. package/dist/ai/block-renderer.js.map +1 -1
  37. package/dist/ai/blocks/error.js +31 -0
  38. package/dist/ai/blocks/error.js.map +1 -0
  39. package/dist/ai/blocks/index.d.ts +0 -2
  40. package/dist/ai/blocks/index.d.ts.map +1 -1
  41. package/dist/ai/blocks/index.js +2 -2
  42. package/dist/ai/blocks/text.js +19 -0
  43. package/dist/ai/blocks/text.js.map +1 -0
  44. package/dist/ai/command-bar.d.ts.map +1 -1
  45. package/dist/ai/command-bar.js +192 -187
  46. package/dist/ai/command-bar.js.map +1 -1
  47. package/dist/ai/conversation.d.ts +2 -1
  48. package/dist/ai/conversation.d.ts.map +1 -1
  49. package/dist/ai/conversation.js +88 -83
  50. package/dist/ai/conversation.js.map +1 -1
  51. package/dist/ai/index.d.ts +0 -4
  52. package/dist/ai/index.d.ts.map +1 -1
  53. package/dist/ai/index.js +45 -46
  54. package/dist/ai/index.js.map +1 -1
  55. package/dist/composed/activity-feed.d.ts +2 -1
  56. package/dist/composed/activity-feed.d.ts.map +1 -1
  57. package/dist/composed/activity-feed.js.map +1 -1
  58. package/dist/composed/bulk-action-bar.d.ts +2 -2
  59. package/dist/composed/bulk-action-bar.d.ts.map +1 -1
  60. package/dist/composed/bulk-action-bar.js +11 -11
  61. package/dist/composed/bulk-action-bar.js.map +1 -1
  62. package/dist/composed/command-palette.d.ts +2 -1
  63. package/dist/composed/command-palette.d.ts.map +1 -1
  64. package/dist/composed/command-palette.js +103 -98
  65. package/dist/composed/command-palette.js.map +1 -1
  66. package/dist/composed/date-picker/index.js +747 -3
  67. package/dist/composed/date-picker/index.js.map +1 -0
  68. package/dist/composed/empty-state.d.ts +3 -3
  69. package/dist/composed/empty-state.d.ts.map +1 -1
  70. package/dist/composed/empty-state.js +40 -31
  71. package/dist/composed/empty-state.js.map +1 -1
  72. package/dist/composed/extensions/emoji-node.js +81 -0
  73. package/dist/composed/extensions/emoji-node.js.map +1 -0
  74. package/dist/composed/extensions/emoji-suggestion.js +117 -0
  75. package/dist/composed/extensions/emoji-suggestion.js.map +1 -0
  76. package/dist/composed/file-preview.js +498 -2
  77. package/dist/{_chunks → composed}/file-preview.js.map +1 -1
  78. package/dist/composed/index.d.ts +0 -15
  79. package/dist/composed/index.d.ts.map +1 -1
  80. package/dist/composed/index.js +16 -24
  81. package/dist/composed/rich-chat-input.js +2073 -2
  82. package/dist/{_chunks → composed}/rich-chat-input.js.map +1 -1
  83. package/dist/composed/rich-text-editor.js +64 -61
  84. package/dist/composed/rich-text-editor.js.map +1 -1
  85. package/dist/composed/status-badge.d.ts +3 -2
  86. package/dist/composed/status-badge.d.ts.map +1 -1
  87. package/dist/composed/status-badge.js +58 -53
  88. package/dist/composed/status-badge.js.map +1 -1
  89. package/dist/shell/app-command-palette.d.ts +2 -1
  90. package/dist/shell/app-command-palette.d.ts.map +1 -1
  91. package/dist/shell/app-command-palette.js.map +1 -1
  92. package/dist/shell/bottom-navbar.d.ts +3 -1
  93. package/dist/shell/bottom-navbar.d.ts.map +1 -1
  94. package/dist/shell/bottom-navbar.js +90 -82
  95. package/dist/shell/bottom-navbar.js.map +1 -1
  96. package/dist/shell/command-registry.d.ts +2 -1
  97. package/dist/shell/command-registry.d.ts.map +1 -1
  98. package/dist/shell/command-registry.js.map +1 -1
  99. package/dist/shell/sidebar.d.ts +7 -4
  100. package/dist/shell/sidebar.d.ts.map +1 -1
  101. package/dist/shell/sidebar.js +143 -129
  102. package/dist/shell/sidebar.js.map +1 -1
  103. package/dist/shell/top-bar.d.ts +4 -3
  104. package/dist/shell/top-bar.d.ts.map +1 -1
  105. package/dist/shell/top-bar.js +114 -106
  106. package/dist/shell/top-bar.js.map +1 -1
  107. package/dist/ui/badge.d.ts +3 -2
  108. package/dist/ui/badge.d.ts.map +1 -1
  109. package/dist/ui/button.d.ts +3 -2
  110. package/dist/ui/button.d.ts.map +1 -1
  111. package/dist/ui/button.js +54 -53
  112. package/dist/ui/button.js.map +1 -1
  113. package/dist/ui/charts/area-chart.js +177 -0
  114. package/dist/ui/charts/area-chart.js.map +1 -0
  115. package/dist/ui/charts/bar-chart.js +127 -0
  116. package/dist/ui/charts/bar-chart.js.map +1 -0
  117. package/dist/ui/charts/chart-container.js +3 -0
  118. package/dist/ui/charts/gauge-chart.js +72 -0
  119. package/dist/ui/charts/gauge-chart.js.map +1 -0
  120. package/dist/ui/charts/index.js +10 -1035
  121. package/dist/ui/charts/line-chart.js +135 -0
  122. package/dist/ui/charts/line-chart.js.map +1 -0
  123. package/dist/ui/charts/pie-chart.js +111 -0
  124. package/dist/ui/charts/pie-chart.js.map +1 -0
  125. package/dist/ui/charts/radar-chart.js +170 -0
  126. package/dist/ui/charts/radar-chart.js.map +1 -0
  127. package/dist/ui/charts/sparkline.js +119 -0
  128. package/dist/ui/charts/sparkline.js.map +1 -0
  129. package/dist/ui/chat/message.d.ts +3 -3
  130. package/dist/ui/chat/message.d.ts.map +1 -1
  131. package/dist/ui/chat/system-message.d.ts +2 -1
  132. package/dist/ui/chat/system-message.d.ts.map +1 -1
  133. package/dist/ui/combobox.d.ts +2 -1
  134. package/dist/ui/combobox.d.ts.map +1 -1
  135. package/dist/ui/combobox.js +97 -92
  136. package/dist/ui/combobox.js.map +1 -1
  137. package/dist/ui/container.d.ts +6 -1
  138. package/dist/ui/container.d.ts.map +1 -1
  139. package/dist/ui/container.js +2 -1
  140. package/dist/ui/container.js.map +1 -1
  141. package/dist/ui/icon-button.d.ts +9 -2
  142. package/dist/ui/icon-button.d.ts.map +1 -1
  143. package/dist/ui/icon-button.js +14 -13
  144. package/dist/ui/icon-button.js.map +1 -1
  145. package/dist/ui/index.d.ts +1 -3
  146. package/dist/ui/index.d.ts.map +1 -1
  147. package/dist/ui/index.js +31 -33
  148. package/dist/ui/index.js.map +1 -1
  149. package/dist/ui/lib/icon-input.d.ts +42 -0
  150. package/dist/ui/lib/icon-input.d.ts.map +1 -0
  151. package/dist/ui/lib/normalize-icon.d.ts +39 -0
  152. package/dist/ui/lib/normalize-icon.d.ts.map +1 -0
  153. package/dist/ui/oauth-button/index.d.ts +3 -0
  154. package/dist/ui/oauth-button/index.d.ts.map +1 -0
  155. package/dist/ui/oauth-button/index.js +3 -0
  156. package/dist/ui/oauth-button/oauth-button.d.ts +208 -0
  157. package/dist/ui/oauth-button/oauth-button.d.ts.map +1 -0
  158. package/dist/ui/progress.js +1 -1
  159. package/dist/ui/segmented-control.d.ts +3 -4
  160. package/dist/ui/segmented-control.d.ts.map +1 -1
  161. package/dist/ui/segmented-control.js +53 -45
  162. package/dist/ui/segmented-control.js.map +1 -1
  163. package/dist/ui/stack.d.ts +6 -1
  164. package/dist/ui/stack.d.ts.map +1 -1
  165. package/dist/ui/stack.js +2 -1
  166. package/dist/ui/stack.js.map +1 -1
  167. package/dist/ui/stat-card.d.ts +2 -3
  168. package/dist/ui/stat-card.d.ts.map +1 -1
  169. package/dist/ui/stat-card.js +117 -115
  170. package/dist/ui/stat-card.js.map +1 -1
  171. package/dist/ui/stepper.d.ts +2 -1
  172. package/dist/ui/stepper.d.ts.map +1 -1
  173. package/dist/ui/stepper.js +74 -69
  174. package/dist/ui/stepper.js.map +1 -1
  175. package/dist/ui/text.d.ts +7 -2
  176. package/dist/ui/text.d.ts.map +1 -1
  177. package/dist/ui/text.js +2 -1
  178. package/dist/ui/text.js.map +1 -1
  179. package/dist/ui/toaster.d.ts +11 -2
  180. package/dist/ui/toaster.d.ts.map +1 -1
  181. package/dist/ui/toaster.js.map +1 -1
  182. package/dist/ui/tooltip.js +12 -12
  183. package/dist/ui/tree-view/tree-item.d.ts +3 -2
  184. package/dist/ui/tree-view/tree-item.d.ts.map +1 -1
  185. package/dist/ui/tree-view/use-tree.d.ts +2 -1
  186. package/dist/ui/tree-view/use-tree.d.ts.map +1 -1
  187. package/docs/components/ui/oauth-button.md +86 -0
  188. package/docs/recipes/customize-brand.md +15 -0
  189. package/docs/recipes/index.md +6 -1
  190. package/docs/recipes/install-astro.md +15 -0
  191. package/docs/recipes/install-next-app-router.md +20 -10
  192. package/docs/recipes/install-next-pages.md +2 -0
  193. package/docs/recipes/install-remix.md +15 -0
  194. package/docs/recipes/install-tanstack-start.md +15 -0
  195. package/docs/recipes/install-vite.md +15 -0
  196. package/docs/recipes/troubleshoot.md +24 -2
  197. package/docs/recipes/upgrading.md +52 -0
  198. package/llms-full.txt +87 -1
  199. package/llms-quick.txt +249 -0
  200. package/llms.txt +110 -3
  201. package/package.json +79 -2
  202. package/scripts/welcome.mjs +252 -0
  203. package/skill/SKILL.md +29 -7
  204. package/skill/references/components-full.md +87 -1
  205. package/skill/references/components.md +110 -3
  206. package/skill/references/customize-brand.md +15 -0
  207. package/skill/references/setup-astro.md +15 -0
  208. package/skill/references/setup-next-app-router.md +20 -10
  209. package/skill/references/setup-next-pages.md +2 -0
  210. package/skill/references/setup-remix.md +15 -0
  211. package/skill/references/setup-tanstack-start.md +15 -0
  212. package/skill/references/setup-vite.md +15 -0
  213. package/skill/references/troubleshoot.md +24 -2
  214. package/skill/references/upgrading.md +54 -0
  215. package/dist/_chunks/date-picker.js +0 -748
  216. package/dist/_chunks/date-picker.js.map +0 -1
  217. package/dist/_chunks/file-preview.js +0 -499
  218. package/dist/_chunks/rich-chat-input.js +0 -2071
  219. package/dist/_chunks/text.js.map +0 -1
  220. package/dist/ui/charts/index.js.map +0 -1
package/llms-quick.txt ADDED
@@ -0,0 +1,249 @@
1
+ # @devalok/shilp-sutra — quick reference for AI agents
2
+
3
+ > Tailwind 4 + React 19 + CVA design system. 110+ components, OKLCH tokens, framer-motion. **Not shadcn/ui** — APIs diverge in ways noted below.
4
+ >
5
+ > This file is the ≤15K-token fast-path summary. Reach for `llms.txt` (~27K tokens) or `llms-full.txt` (~140K tokens) only when this isn't enough.
6
+
7
+ ## SETUP (consumer install, ~5 min)
8
+
9
+ ```bash
10
+ pnpm add @devalok/shilp-sutra framer-motion next-themes
11
+ pnpm add -D tailwindcss@^4 @tailwindcss/postcss # or @tailwindcss/vite
12
+ ```
13
+
14
+ Then 4 files:
15
+
16
+ ```css
17
+ /* globals.css — order matters */
18
+ @import "tailwindcss";
19
+ @import "@devalok/shilp-sutra/css";
20
+ ```
21
+
22
+ ```ts
23
+ // next.config.ts — only if Next.js
24
+ transpilePackages: ["@devalok/shilp-sutra"]
25
+ ```
26
+
27
+ ```tsx
28
+ // app/layout.tsx — Next App Router
29
+ <html lang="en" suppressHydrationWarning> {/* required for next-themes */}
30
+ <body><Providers>{children}</Providers></body>
31
+ </html>
32
+ ```
33
+
34
+ ```tsx
35
+ // app/providers.tsx
36
+ 'use client'
37
+ import { ThemeProvider } from 'next-themes'
38
+ import { Toaster } from '@devalok/shilp-sutra/ui/toaster'
39
+ export function Providers({ children }) {
40
+ return <ThemeProvider attribute="class" defaultTheme="system" enableSystem>{children}<Toaster /></ThemeProvider>
41
+ }
42
+ ```
43
+
44
+ Per-framework recipes: `node_modules/@devalok/shilp-sutra/docs/recipes/install-<framework>.md` (six recipes — Next App Router, Next Pages, Vite, Astro, Remix, TanStack Start).
45
+
46
+ **Theme it in 30 seconds:** https://shilp-sutra.devalok.in/themer — outputs a copy-pasteable CSS block (12-step OKLCH ramp + role tokens). Paste *after* the `@devalok/shilp-sutra/css` import.
47
+
48
+ **Lint + migrate:** `pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`. Catches deprecated APIs, peer-cliff barrel imports, TW3 classes — most autofixable. Use the `migration` preset (`pnpm eslint --fix`) when upgrading across breaking versions.
49
+
50
+ ## OPTIONAL PEER DEPENDENCIES (install BEFORE first import)
51
+
52
+ | When you import… | Install |
53
+ |-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
54
+ | `@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` |
55
+ | `@devalok/shilp-sutra/ui/data-table` | `pnpm add @tanstack/react-table @tanstack/react-virtual` |
56
+ | `@devalok/shilp-sutra/composed/date-picker` (+ DateRange, DateTime, Calendar) | `pnpm add date-fns` |
57
+ | `@devalok/shilp-sutra/composed/rich-text-editor` (+ RichChatInput, RichTextViewer) | `pnpm add @tiptap/react @tiptap/starter-kit @tiptap/extension-placeholder` |
58
+ | `@devalok/shilp-sutra/ui/input-otp` | `pnpm add input-otp` |
59
+ | `@devalok/shilp-sutra/composed/file-preview` | `pnpm add react-pdf react-zoom-pan-pinch` |
60
+ | `@devalok/shilp-sutra/composed/markdown-viewer` | `pnpm add react-markdown react-syntax-highlighter remark-gfm` |
61
+ | `@devalok/shilp-sutra/ui/toaster` or `…/ui/toast` | `pnpm add sonner` |
62
+ | Tabler icons in `<Icon>`, `<Button startIcon>`, etc. | `pnpm add @tabler/icons-react` |
63
+
64
+ ## HARD CONSTRAINTS
65
+
66
+ 1. **Tailwind 4 only.** No `tailwind.config.ts presets: [shilpSutra]` — that was removed in 0.38. CSS-only setup as above.
67
+ 2. **`framer-motion@^12` required peer.** Single copy — configure pnpm/yarn overrides if you see duplicates.
68
+ 3. **`sonner@^2`** required only when you render `<Toaster />` or call `toast.*`. Optional otherwise.
69
+ 4. **Per-component imports keep RSC fast AND avoid peer-dep cliffs.** Barrel `@devalok/shilp-sutra/ui` works in client contexts but inflates client bundle and forces optional peers to be installed. Prefer `…/ui/text`, `…/ui/dialog`, etc. The barrel **no longer** re-exports peer-cliff symbols (`Toaster`, `toast`, `InputOTP`, `DatePicker`, `RichTextEditor`, `EmojiPicker`, `FilePreview`, `MarkdownViewer`, `BlockRenderer`, `ErrorBlock`, `TextBlock`) as of 0.40.0 — import per-component.
70
+ 5. **Spacing namespace is `--spacing-ds-*`.** `p-ds-04`, `gap-ds-03` — these DO NOT replace TW4 default `p-4`, `gap-2`. Both coexist by design. Pick `p-ds-*` for values that should track DS theme changes, `p-N` for one-off layout values.
71
+ 6. **Bare `shadow` class renders no shadow in TW4.** Use `shadow-raised` (cards), `shadow-floating` (dropdowns), `shadow-overlay` (dialogs), `shadow-ring` (focus).
72
+ 7. **Variant names must match CVA source exactly** — invented variant names silently no-op (CVA falls back to defaults). Grep `packages/core/src/ui/<component>.tsx` if in doubt.
73
+ 8. **Default to `variant="soft"`** over `variant="outline"` for non-primary Button actions. Outline only on colored backgrounds or where primary/secondary hierarchy needs a hard border.
74
+
75
+ ## ICON API (one shape across every component, v0.40.0+)
76
+
77
+ Every icon-accepting prop (`startIcon`, `endIcon`, `icon`, …) takes `IconInput`:
78
+
79
+ ```tsx
80
+ import { IconPlus } from '@tabler/icons-react'
81
+ import { Icon } from '@devalok/shilp-sutra/ui/icon'
82
+
83
+ <Button startIcon={<Icon icon={IconPlus} />}>Add</Button> // canonical
84
+ <Button startIcon={<IconPlus />}>Add</Button> // raw Tabler element
85
+ <Button startIcon={IconPlus}>Add</Button> // component ref
86
+ <Button startIcon={<span>+</span>}>Add</Button> // custom node
87
+ ```
88
+
89
+ All four work. Size flows from `<IconProvider>` context — don't pass `className="h-4 w-4"`. On 22 components: Button, IconButton, Badge, Combobox, SegmentedControl, Stepper, StatCard, TreeItem, OAuthButton, Chat.Message.*, AIConversation, EmptyState, BulkActionBar, ActivityFeed, CommandPalette, TopBar, Sidebar, BottomNavbar, AppCommandPalette, CommandRegistry.
90
+
91
+ ## IMPORT PATH CHEATSHEET (don't guess)
92
+
93
+ | Component / API | Exact import path |
94
+ |------------------------------------------------|----|
95
+ | `FormField`, `FormHelperText`, `useFormField` | `@devalok/shilp-sutra/ui/form` (NOT `ui/form-field`)|
96
+ | `Label` | `@devalok/shilp-sutra/ui/label`|
97
+ | `AppSidebar` | `@devalok/shilp-sutra/shell/sidebar` (NOT `shell/app-sidebar`)|
98
+ | `TopBar`, `TopBar.*` | `@devalok/shilp-sutra/shell/top-bar`|
99
+ | `BottomNavbar` | `@devalok/shilp-sutra/shell/bottom-navbar`|
100
+ | `AppCommandPalette` | `@devalok/shilp-sutra/shell/app-command-palette`|
101
+ | `NotificationCenter` | `@devalok/shilp-sutra/shell/notification-center`|
102
+ | `CommandPalette` (lower-level) | `@devalok/shilp-sutra/composed/command-palette`|
103
+ | `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `GaugeChart`, `Sparkline`, `ChartContainer`, `Legend` | `@devalok/shilp-sutra/ui/charts` (or per-chart subpath `…/ui/charts/bar-chart`) |
104
+ | `DataTable` | `@devalok/shilp-sutra/ui/data-table`|
105
+ | **`DatePicker`** family | `@devalok/shilp-sutra/composed/date-picker` **(per-component required since 0.40)** |
106
+ | **`Toaster`** | `@devalok/shilp-sutra/ui/toaster` **(per-component required since 0.40, pulls `sonner`)** |
107
+ | **`toast`** | `@devalok/shilp-sutra/ui/toast` **(per-component required since 0.40)** |
108
+ | **`InputOTP`** family | `@devalok/shilp-sutra/ui/input-otp` **(per-component required since 0.40)** |
109
+ | **`EmojiPicker`** | `@devalok/shilp-sutra/composed/emoji-picker` **(per-component since 0.40)** |
110
+ | **`FilePreview`** | `@devalok/shilp-sutra/composed/file-preview` **(per-component since 0.40)** |
111
+ | **`MarkdownViewer`** | `@devalok/shilp-sutra/composed/markdown-viewer` **(per-component since 0.40)** |
112
+ | **`RichTextEditor`** / **`RichChatInput`** | `@devalok/shilp-sutra/composed/rich-{text-editor,chat-input}` **(per-component since 0.40)** |
113
+ | **`BlockRenderer`**, **`ErrorBlock`**, **`TextBlock`** | `@devalok/shilp-sutra/ai/{block-renderer,blocks/error,blocks/text}` **(per-component since 0.40)** |
114
+ | `useColorMode` | `@devalok/shilp-sutra/hooks/use-color-mode`|
115
+ | `MotionProvider`, `springs`, `tweens` | `@devalok/shilp-sutra/motion`|
116
+
117
+ Components whose import path is the kebab-case of their name (`Button` → `ui/button`, `Card` → `ui/card`, `Avatar` → `ui/avatar`, `Stack` → `ui/stack`, `Text` → `ui/text`) follow the obvious rule. The table above lists the ones that DON'T.
118
+
119
+ ## TWO-AXIS VARIANT SYSTEM (vs shadcn's one-axis)
120
+
121
+ Many components take BOTH `variant` (shape/surface) AND `color` (intent/semantics):
122
+
123
+ ```tsx
124
+ <Button variant="solid" color="error">Delete</Button> // red solid
125
+ <Button variant="soft" color="warning">Pending</Button> // amber tinted
126
+ <Button variant="outline" color="accent">Cancel</Button> // bordered
127
+ <Badge variant="solid" color="success">Active</Badge> // green solid
128
+ <Alert variant="subtle" color="info" title="Note" /> // tinted blue
129
+ ```
130
+
131
+ Components with the two-axis system: **Button, Badge, Alert, Banner, Progress, StatusBadge**.
132
+
133
+ ## TOP DIFFERENCES FROM SHADCN/UI (will trip you up)
134
+
135
+ | shadcn pattern | shilp-sutra equivalent |
136
+ |---|---|
137
+ | `variant="destructive"` | `color="error"` |
138
+ | `size="default"` | `size="md"` (always — never "default") |
139
+ | `<Select size="lg">` | `<SelectTrigger size="lg">` (size on trigger, NOT root) |
140
+ | `<Chip>` | `<Badge onClick={...}>` (Chip removed 0.32) |
141
+ | `useToast() + toast({variant})` | `import { toast }`, then `toast.success('msg')` |
142
+ | `Badge variant="destructive"` | `Badge variant="solid" color="error"` |
143
+ | `Alert + AlertTitle + AlertDescription` | `<Alert title="..." color="error">` (single component) |
144
+ | `Form + FormField + FormItem + FormLabel + FormControl + …` | `<FormField>` + `<Label>` + `<Input>` + `<FormHelperText>` + `useFormField()` hook |
145
+
146
+ ## COMMON MISTAKES — DO NOT
147
+
148
+ - DO NOT use `variant="destructive"` — use `color="error"`
149
+ - DO NOT use `variant="default"` on Button — use `variant="solid"`
150
+ - DO NOT use `size="default"` — use `size="md"`
151
+ - DO NOT put `size` on `<Select>` — put it on `<SelectTrigger size="md">`
152
+ - DO NOT use `<Chip>` — use `<Badge onClick={...}>`
153
+ - DO NOT call `useToast()` hook — use `import { toast } from '@devalok/shilp-sutra/ui/toast'`
154
+ - DO NOT call `toast({title, color})` object form — use `toast.success('message', { description })`
155
+ - DO NOT call `toast()` without `<Toaster />` mounted
156
+ - DO NOT use `<Alert><AlertTitle>...</AlertTitle></Alert>` — use `<Alert title="..." />`
157
+ - DO NOT codemod `p-4` → `p-ds-04` — both coexist by design
158
+ - DO NOT use bare `shadow` class — pick `shadow-raised` / `shadow-floating` / `shadow-overlay`
159
+ - DO NOT use `tailwind.config.ts presets: [shilpSutra]` — JS preset removed 0.38
160
+ - DO NOT use `bg-surface-1..4` — renamed to `bg-surface-{base,raised,raised-hover,raised-active}` in 0.23
161
+ - DO NOT use `shadow-01..05` — renamed to `shadow-{raised,raised-hover,floating,overlay}` in 0.23
162
+ - DO NOT use TW3 `bg-gradient-to-*` — use TW4 `bg-linear-to-*` (since 0.37)
163
+ - DO NOT use TW3 `w-[--var]` — use TW4 `w-(--var)` (since 0.37)
164
+ - DO NOT pass `children` to `<IconButton>` — use the `icon` prop
165
+
166
+ ## TOP 30 COMPONENTS QUICK-REF
167
+
168
+ ### Inputs & buttons
169
+ - **Button**: variant(solid|soft|outline|ghost|link) color(accent|error|success|warning|neutral) size(xs|sm|md|lg|compact-xs|compact-sm|compact-md|icon-xs|icon-sm|icon-md|icon-lg) shape(default|pill) + loading, startIcon, endIcon, asChild, processing, onClickAsync
170
+ - **IconButton**: icon(IconInput, required) shape(square|circle) size(sm|md|lg) + aria-label required. Children rejected by type.
171
+ - **SplitButton**: `[Action | ▼]` with dropdown. triggerSide, dropdownContent.
172
+ - **Input**: size(xs|sm|md|lg) state(default|error|warning|success) + startSection, endSection (auto-typed icon vs label).
173
+ - **NumberInput**: value + onValueChange + min/max/step.
174
+ - **Textarea**, **SearchInput**, **ColorInput**.
175
+ - **Checkbox**: checked, onCheckedChange, indeterminate, error, size.
176
+ - **Switch**: checked, onCheckedChange, error, size, color, thumbIcon.
177
+ - **RadioGroup > RadioGroupItem**.
178
+ - **Select > SelectTrigger(size) > SelectValue; SelectContent > SelectItem**.
179
+ - **Combobox**: discriminated union — `multiple?: false` (value: string) | `multiple: true` (value: string[]).
180
+ - **Autocomplete**, **Slider**, **Toggle**, **ToggleGroup**, **SegmentedControl**.
181
+ - **FormField + Label + Input + FormHelperText + useFormField()** — replaces shadcn's Form + FormItem + FormControl + FormDescription + FormMessage.
182
+
183
+ ### Display
184
+ - **Text**: variant(heading-2xl..xs, body-lg..xs, label-lg..xs, caption, overline, code). Polymorphic `as` prop.
185
+ - **Stack**: direction(vertical|horizontal) gap(SpacingToken) align/justify/wrap.
186
+ - **Container**, **Separator**.
187
+ - **Card**: variant(default|elevated|outline|flat) accent(left|top|right|bottom). Compound: CardHeader > CardTitle, CardDescription; CardContent; CardFooter.
188
+ - **Badge**: variant(subtle|solid|outline|soft) color(default|accent|error|success|warning|info|neutral + 7 categories + custom) size(xs|sm|md|lg) + onClick, onDismiss, dot, startIcon, endIcon, truncate. Compound: Badge.Indicator, Badge.Group.
189
+ - **Avatar**: size(xs|sm|md|lg|xl) shape(circle|square|rounded) status, ring, badge.
190
+ - **Spinner**, **Progress** (autoColor!), **Skeleton**, **StatCard**, **StatusDot**, **ColorSwatch**.
191
+ - **Alert**: variant(subtle|solid|outline) color(info|success|warning|error|neutral) + title, onDismiss. Single component, not compound.
192
+ - **Banner**: color(...) + actions, onDismiss. Mobile-responsive.
193
+ - **Toast**: imperative `toast.success('msg')` / `.error/.warning/.info/.loading/.message/.promise/.upload/.custom`. Requires `<Toaster />`.
194
+
195
+ ### Overlays
196
+ - **Dialog**: compound (DialogTrigger; DialogContent > DialogHeader > DialogTitle; …; DialogFooter). Mobile auto-fullscreens.
197
+ - **AlertDialog**: same compound, mobile bottom-sheet via `responsive` prop.
198
+ - **Sheet**: side(top|bottom|left|right). Mobile auto-bottom + swipe-to-dismiss.
199
+ - **Popover**, **Tooltip** (auto-wraps Provider), **HoverCard**, **Collapsible**.
200
+
201
+ ### Navigation
202
+ - **Tabs**: TabsList(variant: line|contained) > TabsTrigger; TabsContent. color, size, orientation.
203
+ - **Accordion**: AccordionItem > AccordionTrigger; AccordionContent.
204
+ - **Breadcrumb**, **PaginationRoot**, **DropdownMenu**, **ContextMenu**, **Menubar**, **NavigationMenu**.
205
+
206
+ ### Composed (per-component subpaths)
207
+ - **DatePicker**, **DateRangePicker**, **DateTimePicker**, **TimePicker**, **CalendarGrid** — `@devalok/shilp-sutra/composed/date-picker`. Needs `date-fns` peer.
208
+ - **EmptyState**: icon(IconInput) + title, description, action, compact, iconSize.
209
+ - **CommandPalette**, **AppCommandPalette**, **MultiSelectPopover**, **MemberPicker**, **MasterDetail**, **ActivityFeed**, **PageHeader**, **InlineEdit**, **FormSection**, **BulkActionBar**, **DeadlineIndicator**.
210
+ - **RichTextEditor**, **RichTextViewer**, **RichChatInput** — needs `@tiptap/*` peers.
211
+ - **FilePreview**, **MarkdownViewer**, **EmojiPicker**.
212
+
213
+ ### Shell
214
+ - **TopBar**: Composition-based. `TopBar.Left/Center/Right/Section/IconButton/Title/UserMenu`.
215
+ - **AppSidebar**: `NavItem[]` + `NavGroup[]` + `footer.{links,version,promo,slot}`.
216
+ - **BottomNavbar**: mobile.
217
+ - **NotificationCenter**, **NotificationPreferences**, **LinkProvider**.
218
+
219
+ ### AI module
220
+ - **CommandBar**, **AIConversation**, **BlockRenderer** (per-component, pulls `react-markdown`), **AICommandProvider**, **DevadootIcon**.
221
+ - AI blocks (barrel-safe): BlockTable, ConfirmBlock, DividerBlock, InfoBlock, LoadingBlock, StatRowBlock, SuccessBlock.
222
+ - AI blocks (per-component required): ErrorBlock (`/ai/blocks/error`), TextBlock (`/ai/blocks/text`).
223
+
224
+ ## SERVER-SAFE COMPONENTS (`@server-safe` annotation in source)
225
+
226
+ UI: `Text`, `Skeleton`, `Stack`, `Container`, `Table` (+ sub), `Code`, `VisuallyHidden`.
227
+ Composed: `ContentCard`, `PageHeader`, `LoadingSkeleton`, `PageSkeletons`, `PriorityIndicator`.
228
+
229
+ Use per-component subpaths in Server Components: `import { Text } from '@devalok/shilp-sutra/ui/text'`.
230
+
231
+ ## TROUBLESHOOTING
232
+
233
+ 13 symptoms with diagnosis + fix at `node_modules/@devalok/shilp-sutra/docs/recipes/troubleshoot.md`. Most common:
234
+
235
+ - **`Cannot find module 'sonner'` / `'input-otp'` / `'date-fns'`** → missing optional peer; install per the matrix above.
236
+ - **Spacing utilities don't apply** → Tailwind not seeing `node_modules/@devalok/shilp-sutra/dist`; ensure `transpilePackages` in `next.config` OR Tailwind 4 auto-discovery.
237
+ - **`<Toaster />` mounted but `toast()` silent** → check sonner peer installed + Toaster mounted ONCE at layout root.
238
+ - **Hydration warning on every page** → add `suppressHydrationWarning` to `<html>` (needed for next-themes).
239
+ - **Bare `shadow` produces no shadow** → TW4 has no `--shadow-DEFAULT`; pick `shadow-raised`/`-floating`/`-overlay`.
240
+
241
+ ## NEED MORE?
242
+
243
+ - `llms.txt` — full ~27K-token reference (this file is the slice)
244
+ - `llms-full.txt` — exhaustive per-component prop tables (~140K tokens)
245
+ - `docs/recipes/install-<framework>.md` — per-framework setup with edge cases
246
+ - `docs/recipes/customize-brand.md` — token override cookbook
247
+ - `MIGRATION.md` — every breaking change since 0.18
248
+
249
+ This file regenerates from `llms.txt` when component APIs change; expect it to track v0.40+ closely.
package/llms.txt CHANGED
@@ -26,8 +26,34 @@ Other recipes:
26
26
  - `server-components.md` — RSC-safety matrix and import patterns
27
27
  - `troubleshoot.md` — decision tree for the 8 most common breakages
28
28
 
29
+ ## The Themer (fast path for branding)
30
+
31
+ Before hand-writing CSS variables, point the user at **https://shilp-sutra.devalok.in/themer** — one funnel, four doors. Each door drops the user at a result page with install commands + a copy-pasteable CSS block (role tokens + 12-step OKLCH accent ramp) + a shareable URL.
32
+
33
+ | User context | URL |
34
+ |---|---|
35
+ | "Make it look like Linear / Stripe / Apple / Material / Notion / Vercel / Devalok" | `/themer/archetypes` |
36
+ | "Here's our brand color: `#…`" | `/themer/brand` |
37
+ | "Not sure" | `/themer/wizard` |
38
+ | "Show me a sample result" | `/themer/result?archetype=devalok` |
39
+
40
+ Paste the snippet *after* `@import "@devalok/shilp-sutra/css";` in the global stylesheet. No `tailwind.config.ts`, no theme provider, no JS bundle. Fall through to `customize-brand.md` only for tokens the Themer doesn't expose yet (font stack, spacing scale, focus ring).
41
+
29
42
  The repo URL for these files is `https://github.com/devalok-design/shilp-sutra/tree/main/packages/core/docs/recipes`. Consumer projects should also have an `AGENTS.md` at their root with the rules above pre-loaded — read that first if it exists.
30
43
 
44
+ ## NEW (v0.40.0)
45
+
46
+ - **OAuthButton.** Brand-aware social/login buttons. Subpath: `@devalok/shilp-sutra/ui/oauth-button`. 13 providers (`google` `apple` `github` `microsoft` `x` `linkedin` `facebook` `discord` `slack` `gitlab` `sso` `email` `passkey`). Props: `provider`, `intent` (`continue|signin|signup`), `appearance` (`brand|outline|dark`), `icon` (override default glyph), `iconOnly`, `compact` (renders just "Google" instead of "Continue with Google"; aria-label keeps long form), `lastUsed` (inline right-edge pill inside button), `helperText`. Inherits Button async/loading/sizes. Siblings: `OAuthGroup` (with `reorderLastUsedFirst` for Stripe-style ordering), `OAuthDivider`, `OAuthConnectionRow` (settings-page linked state). Default glyphs from Tabler peer dep; pass `icon` to drop in a brand's official multicolour SVG. In dark mode every brand appearance lands on the same DS surface — brand identity comes from the glyph, not the bg, so rows stay visually coherent.
47
+ - **Icon API unification.** Every icon-accepting prop (`startIcon`, `endIcon`, `icon`, `leftIcon`, `rightIcon`) across 22 components now takes one type: **`IconInput`**. Pass a rendered element (`<Icon icon={IconPlus} />` or `<IconPlus />`), a component ref (`IconPlus`), or any custom node — all four shapes work interchangeably. **Mostly non-breaking, one narrowing:** for the 14 components whose `icon` prop was previously `React.ReactNode`, `IconInput` excludes `string`/`number`/iterables — if you pass icons from a `Record<string, React.ReactNode>` map or `?: React.ReactNode` field, retype the source to `React.ReactElement` (`tsc`-only; affects `CommandItem.icon`, `ActivityItem.icon`, `Chat.Message.Avatar`). Helpers exported for your own wrappers: `import type { IconInput } from '@devalok/shilp-sutra/ui/lib/icon-input'` + `import { normalizeIcon } from '@devalok/shilp-sutra/ui/lib/normalize-icon'`. `IconProvider` now sizes icons via context — delete `className="h-4 w-4"` overrides.
48
+ - **Polymorphic `Text` / `Stack` / `Container`.** The `as` prop now widens accepted attributes to the rendered element: `<Text as="label" htmlFor="email">`, `<Text as="a" href="/x">`, `<Stack as="ul" role="list">`, `<Container as="main" aria-label>` all typecheck. Default element behavior unchanged.
49
+ - **Agent-friendly install experience.** `AGENTS.md` now ships in the tarball (`node_modules/@devalok/shilp-sutra/AGENTS.md`), discoverable by 25+ agent tools. `package.json` declares an `agents` field (npm-agentskills convention) so `pnpm dlx @codemcp/agentskills export` auto-installs the bundled skill. New postinstall welcome banner (silent in CI / non-TTY / `SHILP_SUTRA_NO_WELCOME=1`). `troubleshoot.md` gained peer-cliff symptom entries.
50
+ - **`llms-quick.txt`.** New ≤15K-token fast-path summary in the tarball — fits in one Read on any agent. Read order is now `llms-quick.txt` → `llms.txt` → `llms-full.txt`.
51
+ - **Companion package `@devalok/eslint-plugin-shilp-sutra`** (first release). 12 rules — deprecated-API catches, peer-cliff barrel-import detection, TW3→TW4 classname autofixes. `pnpm add -D @devalok/eslint-plugin-shilp-sutra`, then `shilpSutra.configs['flat/recommended']`. Three presets: `recommended`, `strict`, `migration` (one-shot codemod).
52
+
53
+ ## BREAKING CHANGES (v0.40.0)
54
+
55
+ - **Barrel peer-cliff cleanup.** 12 symbols that statically import optional peers were removed from their parent barrels (`/ui`, `/composed`, `/ai`, `/ai/blocks`) — they now import ONLY via per-component subpath. Affected: `Toaster`/`toast` (→ `/ui/toaster`, `/ui/toast`), `InputOTP*` (→ `/ui/input-otp`), `DatePicker*` (→ `/composed/date-picker`), `EmojiPicker*` (→ `/composed/emoji-picker`), `FilePreview` (→ `/composed/file-preview`), `MarkdownViewer` (→ `/composed/markdown-viewer`), `RichTextEditor*`/`RichChatInput*` (→ their subpaths), `BlockRenderer`/`ErrorBlock`/`TextBlock` (→ `/ai/*`). Fixes `Module not found: Can't resolve 'sonner'`/etc. at consumer build time. Full before/after table in `MIGRATION.md → v0.40.0`. Per-chart subpaths (`/ui/charts/bar-chart`, etc.) added non-breaking alongside.
56
+
31
57
  ## NEW (v0.39.0)
32
58
 
33
59
  - **Shape presets (`[data-shape]`).** Set on `<html>` (or any subtree) to re-skin roundness across the whole UI. Three ship by default: `sharp` (technical, 2/4/6 px), `slightly-rounded` (default, 6/10/16 px), `rounded` (consumer, 10/16/24 px). Pill shapes (Badge, Switch, Radio, Avatar circle) stay pill regardless.
@@ -415,7 +441,7 @@ pnpm add @devalok/shilp-sutra
415
441
 
416
442
  Add to next.config.js:
417
443
  ```js
418
- transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"]
444
+ transpilePackages: ["@devalok/shilp-sutra"]
419
445
  ```
420
446
 
421
447
  // Import components (barrel):
@@ -441,6 +467,87 @@ import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
441
467
  // CSS tokens (import once at app root — already included in /css):
442
468
  import '@devalok/shilp-sutra/css'
443
469
 
470
+ ## IMPORT PATH CHEATSHEET (don't guess — these subpaths are NOT always the kebab-case of the component name)
471
+
472
+ > **0.40.0 — barrel peer-cliff cleanup.** Components below marked `MANDATORY per-component` were removed from their parent barrel (`/ui`, `/composed`, `/ai`, `/ai/blocks`) because they statically import optional peers (`input-otp`, `sonner`, `date-fns`, `@emoji-mart/*`, `react-pdf`, `react-zoom-pan-pinch`, `react-markdown`, `remark-gfm`, `react-syntax-highlighter`, `@tiptap/*`). Fresh consumers using the barrel were getting `Module not found` at build time. The per-component subpath is now the ONLY way to import them. See MIGRATION.md → "v0.40.0 — barrel peer-cliff cleanup" for the full before/after.
473
+
474
+ Common confusions to memorize:
475
+
476
+ | Component / API | Exact import path |
477
+ |------------------------------------------------|----------------------------------------------------------------|
478
+ | `FormField`, `FormHelperText`, `useFormField` | `@devalok/shilp-sutra/ui/form` (NOT `ui/form-field`)|
479
+ | `Label` | `@devalok/shilp-sutra/ui/label` |
480
+ | `AppSidebar` | `@devalok/shilp-sutra/shell/sidebar` (NOT `shell/app-sidebar`)|
481
+ | `TopBar`, `TopBar.*` | `@devalok/shilp-sutra/shell/top-bar` |
482
+ | `BottomNavbar` | `@devalok/shilp-sutra/shell/bottom-navbar` |
483
+ | `AppCommandPalette` | `@devalok/shilp-sutra/shell/app-command-palette` |
484
+ | `CommandRegistryProvider`, `useCommandRegistry`| `@devalok/shilp-sutra/shell/command-registry` |
485
+ | `NotificationCenter` | `@devalok/shilp-sutra/shell/notification-center` |
486
+ | `NotificationPreferences` | `@devalok/shilp-sutra/shell/notification-preferences` |
487
+ | `LinkProvider`, `useLink` | `@devalok/shilp-sutra/shell/link-context` |
488
+ | `CommandPalette` (lower-level palette) | `@devalok/shilp-sutra/composed/command-palette` |
489
+ | `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `GaugeChart`, `Sparkline`, `ChartContainer`, `Legend` | `@devalok/shilp-sutra/ui/charts` (full barrel, pulls all 9 d3-\* peers) — **prefer per-chart subpath when possible: `/ui/charts/bar-chart`, `/ui/charts/line-chart`, `/ui/charts/area-chart`, `/ui/charts/pie-chart`, `/ui/charts/radar-chart`, `/ui/charts/gauge-chart`, `/ui/charts/sparkline`, `/ui/charts/chart-container`** (each pulls only the d3-\* peers it needs — BarChart needs `d3-scale` + `d3-axis` + `d3-selection`; PieChart/RadarChart need only `d3-shape`) |
490
+ | `DataTable` | `@devalok/shilp-sutra/ui/data-table` |
491
+ | `DataTableToolbar` | `@devalok/shilp-sutra/ui/data-table-toolbar` |
492
+ | `DatePicker`, `DateRangePicker`, `DateTimePicker`, `TimePicker`, `CalendarGrid`, `YearPicker`, `MonthPicker`, `Presets`, `useCalendar` | `@devalok/shilp-sutra/composed/date-picker` **MANDATORY per-component (0.40.0+)** — pulls `date-fns` |
493
+ | `Toaster` | `@devalok/shilp-sutra/ui/toaster` **MANDATORY per-component (0.40.0+)** — pulls `sonner` |
494
+ | `toast` | `@devalok/shilp-sutra/ui/toast` **MANDATORY per-component (0.40.0+)** — pulls `sonner` |
495
+ | `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot` | `@devalok/shilp-sutra/ui/input-otp` **MANDATORY per-component (0.40.0+)** — pulls `input-otp` |
496
+ | `EmojiPicker`, `EmojiPickerPopover`, `EmojiData`, `EmojiSet` | `@devalok/shilp-sutra/composed/emoji-picker` **MANDATORY per-component (0.40.0+)** — pulls `@emoji-mart/data` + `@emoji-mart/react` |
497
+ | `EmojiNode`, `EmojiNodeAttrs` | `@devalok/shilp-sutra/composed/extensions/emoji-node` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
498
+ | `createEmojiSuggestion` | `@devalok/shilp-sutra/composed/extensions/emoji-suggestion` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
499
+ | `FilePreview`, `FilePreviewProps` | `@devalok/shilp-sutra/composed/file-preview` **MANDATORY per-component (0.40.0+)** — pulls `react-pdf` + `react-zoom-pan-pinch` |
500
+ | `MarkdownViewer` | `@devalok/shilp-sutra/composed/markdown-viewer` **MANDATORY per-component (0.40.0+)** — pulls `react-markdown` + `react-syntax-highlighter` + `remark-gfm` |
501
+ | `RichChatInput`, `AudioPlayer`, `AudioWaveform`, `useVoiceRecorder` | `@devalok/shilp-sutra/composed/rich-chat-input` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
502
+ | `RichTextEditor`, `RichTextViewer`, `MentionItem`, `ToolbarItem` | `@devalok/shilp-sutra/composed/rich-text-editor` **MANDATORY per-component (0.40.0+)** — pulls `@tiptap/*` |
503
+ | `MessageList`, `Message`, `SystemMessage`, `MessageInput`, `DateSeparator`, `UnreadSeparator`, `TypingIndicator` | `@devalok/shilp-sutra/ui/chat` |
504
+ | `CommandBar` | `@devalok/shilp-sutra/ai/command-bar` (also re-exported from `/ai`) |
505
+ | `AIConversation` | `@devalok/shilp-sutra/ai/conversation` |
506
+ | `BlockRenderer` | `@devalok/shilp-sutra/ai/block-renderer` **MANDATORY per-component (0.40.0+)** — transitively pulls `react-markdown` + `remark-gfm` via ErrorBlock/TextBlock |
507
+ | `AICommandProvider` | `@devalok/shilp-sutra/ai/ai-command-provider` |
508
+ | `DevadootIcon` | `@devalok/shilp-sutra/ai` |
509
+ | `ErrorBlock` | `@devalok/shilp-sutra/ai/blocks/error` **MANDATORY per-component (0.40.0+)** — pulls `react-markdown` + `remark-gfm` |
510
+ | `TextBlock` | `@devalok/shilp-sutra/ai/blocks/text` **MANDATORY per-component (0.40.0+)** — pulls `react-markdown` + `remark-gfm` |
511
+ | `BlockTable`, `ConfirmBlock`, `DividerBlock`, `InfoBlock`, `LoadingBlock`, `StatRowBlock`, `SuccessBlock` | `@devalok/shilp-sutra/ai/blocks` (barrel — these 7 are peer-cliff-free) |
512
+ | `useColorMode` | `@devalok/shilp-sutra/hooks/use-color-mode` |
513
+ | `useMobile` | `@devalok/shilp-sutra/hooks/use-mobile` |
514
+ | `MotionProvider`, `springs`, `tweens`, `stagger`, `useMotion` | `@devalok/shilp-sutra/motion` |
515
+ | `MotionFade`, `MotionScale`, `MotionPop`, `MotionSlide`, `MotionCollapse`, `MotionStagger`, `MotionStaggerItem` | `@devalok/shilp-sutra/motion/primitives` |
516
+
517
+ Components named directly after their file (`Button` → `ui/button`, `Card` → `ui/card`, `Avatar` → `ui/avatar`, `Stack` → `ui/stack`, `Text` → `ui/text`, etc.) follow the kebab-case-of-name rule. The table above is for the ones that DON'T.
518
+
519
+ **When in doubt:** `cat node_modules/@devalok/shilp-sutra/package.json | jq '.exports | keys'` lists every available subpath in the installed version.
520
+
521
+ ## ICON API — one shape across every component (v0.40.0+)
522
+
523
+ Every icon-accepting prop in the design system (`startIcon`, `endIcon`, `icon`, etc. — see list below) takes the **`IconInput`** type. Pass any of these four shapes interchangeably:
524
+
525
+ ```tsx
526
+ import { IconPlus } from '@tabler/icons-react'
527
+ import { Icon } from '@devalok/shilp-sutra/ui/icon'
528
+
529
+ <Button startIcon={<Icon icon={IconPlus} />}>Add</Button> // canonical
530
+ <Button startIcon={<IconPlus />}>Add</Button> // raw Tabler element
531
+ <Button startIcon={IconPlus}>Add</Button> // component ref
532
+ <Button startIcon={<span>+</span>}>Add</Button> // custom node
533
+ ```
534
+
535
+ All four work identically at the call site. The component wraps its icon slot in `<IconProvider size={...}>` so size + stroke flow via React context — no `className="h-4 w-4"` overrides needed.
536
+
537
+ **Upgrading 0.39→0.40 — one narrowing:** `IconInput` (`ReactElement | ComponentType | null | undefined`) excludes `string`/`number`/iterables that `React.ReactNode` allows. The 14 components previously typed `React.ReactNode` (Combobox, Stepper, TreeItem, OAuthButton, AppCommandPalette, CommandRegistry, BottomNavbar, Sidebar nav items, TopBar, Chat.Message.Avatar, SystemMessage, AIConversation, ActivityFeed, CommandPalette) now accept less. If you feed them icons from a `Record<string, React.ReactNode>` map or `?: React.ReactNode` field, `tsc` fails — retype the source to `React.ReactElement`. Build-time only; runtime JSX is unaffected.
538
+
539
+ **Components on the unified API:** Button, IconButton, Badge, Combobox, SegmentedControl, Stepper, StatCard, TreeItem (TreeNode.icon), OAuthButton (icon + linkedIcon), Chat.Message.Avatar, Chat.Message.Action, Chat.SystemMessage, AIConversation (agent.icon), AICommandProvider (agent.icon), CommandBar (item.icon), EmptyState (kills the dual ReactNode|ComponentType signature), BulkActionBar (action.icon), ActivityFeed (item.icon), CommandPalette (item.icon), TopBar (UserMenuItem.icon, TopBar.IconButton.icon), Sidebar (NavItem.icon, NavSubItem.icon, footer.promo.icon), BottomNavbar (item.icon), AppCommandPalette (SearchResult.icon), CommandRegistry (CommandPageItem.icon).
540
+
541
+ **Internals** (`<Toaster>`, `<Toast>`'s success/error icons) use Sonner's own type contract and don't accept consumer-passed icons — that's by design.
542
+
543
+ **When to use which shape:**
544
+ - `<Icon icon={IconX} />` when you want explicit size/stroke control (size flows from context if not set)
545
+ - `<IconX />` when you trust the surrounding `IconProvider` and don't need stroke control
546
+ - `IconX` (raw ref) when you want the helper to do the wrapping for you (auto-wraps to `<Icon icon={IconX} />`)
547
+ - Custom node when the "icon" is actually `<span>$</span>` or an emoji
548
+
549
+ **Migration:** zero consumer changes needed if you were already passing valid React content. Components that previously took strict `IconProps['icon']` (BulkActionBar, Message.Action) or `ComponentType<{className}>` (SegmentedControl) now also accept the other three shapes. Strict-to-loose type widening — no breaking calls.
550
+
444
551
  ## CRITICAL: Differences from shadcn/ui
445
552
 
446
553
  If you have shadcn/ui knowledge, these are the differences that WILL trip you up:
@@ -478,7 +585,7 @@ Components with two-axis system: Button, Badge, Alert, Banner, Progress, StatusB
478
585
 
479
586
  ### Inputs & Controls
480
587
  - Button: variant(solid|soft|outline|ghost|link) color(accent|error|success|warning|neutral) size(xs|sm|md|lg|compact-xs|compact-sm|compact-md|icon-xs|icon-sm|icon-md|icon-lg) shape(default|pill) weight(semibold|normal) + loading, startIcon, endIcon, asChild, processing?('ambient'|'working'|'urgent'|boolean — marching ants SVG border, forces soft variant), processingColor?('accent'|'error'|'success'|'warning'|'neutral'), processingDisabled?(boolean, default true — set false for cancel-by-click). onClickAsync auto-activates processing='working' during loading phase. Layout animation always on. Deprecated aliases still work: variant="default"→solid, variant="destructive"→solid+error, color="default"→accent
481
- - IconButton: icon(ReactNode, required) shape(square|circle) size(sm|md|lg) + aria-label required
588
+ - IconButton: icon(ReactNode, required as PROP — NOT children) shape(square|circle) size(sm|md|lg) + aria-label required. **Children rejected by type** (`Omit<ButtonProps, 'children'>`); pass the icon via `icon=` prop. Correct: `<IconButton icon={<Icon icon={IconArrowRight} />} aria-label="Submit" />`. Wrong: `<IconButton><Icon icon={IconArrowRight} /></IconButton>` (TS error). Wrap with `<Icon icon={…} />` (not raw Tabler `<IconX />`) so the size context cascades.
482
589
  - SplitButton: [Action | ▼] button with dropdown. Props: variant(solid|soft|outline), color, size(xs|sm|md|icon-xs|icon-sm|icon-md), triggerSide(left|right, default right), triggerWidth?(number|string), placement?(Floating UI Placement, default top-end), dropdownContent(ReactNode), open?, onOpenChange?, dropdownLabel?, dropdownIcon?. ARIA: role="group", aria-haspopup="menu", aria-expanded.
483
590
  - ButtonGroup: Visually merges adjacent Buttons. Props: variant, color, size, disabled (propagates), orientation(horizontal|vertical), attached(true|false, default true), fullWidth. Compound pattern: Button reads position from context, applies radius + border-removal inline. Tonal dividers for solid/soft/ghost. Focus z-index isolation.
484
591
  - Icon: `<Icon icon={IconPlus} />` — context-aware wrapper for Tabler icons. Size tiers: xs(14px) sm(16px) md(18px) lg(20px) xl(24px) 2xl(32px). Default: md. Stroke: light(1.5) regular(2) bold(2.5). Default: regular. Scales per size tier. Reads size from parent Button/IconGroup via IconContext. Explicit props override. Accessibility: aria-hidden by default. Pass label="Add item" for accessible icons. Animation: animate="spin|pulse|bounce|draw". `draw` renders SVG path-draw animation (check/X icons draw progressively via pathLength; other icons fall back to static). State machine: state="idle|loading|success|error". Button integration: startIcon={<Icon icon={IconPlus} />} (NOT raw <IconPlus />). IconGroup: <IconGroup size="sm" gap="tight"> for toolbar patterns.
@@ -636,7 +743,7 @@ Import: `@devalok/shilp-sutra/ui/chat`
636
743
  - Old Fade/Collapse/Grow/Slide from @devalok/shilp-sutra/ui/transitions are REMOVED — use Motion* equivalents
637
744
 
638
745
  ### Hooks
639
- - toast: imperative API — import { toast } from '@devalok/shilp-sutra/ui/toast'. Methods: toast.success/error/warning/info/loading/message/undo/promise/upload/custom/dismiss. useToast() is deprecated.
746
+ - toast: imperative API — import { toast } from '@devalok/shilp-sutra/ui/toast'. **Signature is `(message: string, options?: { description?, duration?, action?, … })`** (sonner-style positional, NOT object-first). Examples: `toast.success('Saved')`, `toast.error('Failed to fetch', { description: 'Check your network', duration: 7000 })`, `toast.promise(fn, { loading: '…', success: '…', error: '…' })`, `toast.upload(file, { onProgress, onComplete })`. Methods: toast.success/error/warning/info/loading/message/undo/promise/upload/custom/dismiss. useToast() is deprecated. Mount `<Toaster />` at layout root or `toast()` calls are no-ops + log a dev warning.
640
747
  - useColorMode(): returns { colorMode, setColorMode, toggleColorMode }
641
748
  - useMobile(): returns boolean (true if viewport < 768px)
642
749
  - useLink(): returns router-agnostic Link component from LinkProvider context (shell/link-context)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@devalok/shilp-sutra",
3
- "version": "0.39.0",
3
+ "version": "0.40.1",
4
4
  "description": "Devalok Design System — accessible React components, OKLCH design tokens, and Tailwind 4 CSS-first setup. Ships with AI-agent setup recipes.",
5
5
  "license": "MIT",
6
6
  "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",
@@ -275,6 +275,11 @@
275
275
  "import": "./dist/ui/number-input.js",
276
276
  "default": "./dist/ui/number-input.js"
277
277
  },
278
+ "./ui/oauth-button": {
279
+ "types": "./dist/ui/oauth-button/index.d.ts",
280
+ "import": "./dist/ui/oauth-button/index.js",
281
+ "default": "./dist/ui/oauth-button/index.js"
282
+ },
278
283
  "./ui/pagination": {
279
284
  "types": "./dist/ui/pagination.d.ts",
280
285
  "import": "./dist/ui/pagination.js",
@@ -435,6 +440,46 @@
435
440
  "import": "./dist/ui/charts/index.js",
436
441
  "default": "./dist/ui/charts/index.js"
437
442
  },
443
+ "./ui/charts/area-chart": {
444
+ "types": "./dist/ui/charts/area-chart.d.ts",
445
+ "import": "./dist/ui/charts/area-chart.js",
446
+ "default": "./dist/ui/charts/area-chart.js"
447
+ },
448
+ "./ui/charts/bar-chart": {
449
+ "types": "./dist/ui/charts/bar-chart.d.ts",
450
+ "import": "./dist/ui/charts/bar-chart.js",
451
+ "default": "./dist/ui/charts/bar-chart.js"
452
+ },
453
+ "./ui/charts/chart-container": {
454
+ "types": "./dist/ui/charts/chart-container.d.ts",
455
+ "import": "./dist/ui/charts/chart-container.js",
456
+ "default": "./dist/ui/charts/chart-container.js"
457
+ },
458
+ "./ui/charts/gauge-chart": {
459
+ "types": "./dist/ui/charts/gauge-chart.d.ts",
460
+ "import": "./dist/ui/charts/gauge-chart.js",
461
+ "default": "./dist/ui/charts/gauge-chart.js"
462
+ },
463
+ "./ui/charts/line-chart": {
464
+ "types": "./dist/ui/charts/line-chart.d.ts",
465
+ "import": "./dist/ui/charts/line-chart.js",
466
+ "default": "./dist/ui/charts/line-chart.js"
467
+ },
468
+ "./ui/charts/pie-chart": {
469
+ "types": "./dist/ui/charts/pie-chart.d.ts",
470
+ "import": "./dist/ui/charts/pie-chart.js",
471
+ "default": "./dist/ui/charts/pie-chart.js"
472
+ },
473
+ "./ui/charts/radar-chart": {
474
+ "types": "./dist/ui/charts/radar-chart.d.ts",
475
+ "import": "./dist/ui/charts/radar-chart.js",
476
+ "default": "./dist/ui/charts/radar-chart.js"
477
+ },
478
+ "./ui/charts/sparkline": {
479
+ "types": "./dist/ui/charts/sparkline.d.ts",
480
+ "import": "./dist/ui/charts/sparkline.js",
481
+ "default": "./dist/ui/charts/sparkline.js"
482
+ },
438
483
  "./ui/tree-view": {
439
484
  "types": "./dist/ui/tree-view/index.d.ts",
440
485
  "import": "./dist/ui/tree-view/index.js",
@@ -515,6 +560,16 @@
515
560
  "import": "./dist/composed/file-preview.js",
516
561
  "default": "./dist/composed/file-preview.js"
517
562
  },
563
+ "./composed/extensions/emoji-node": {
564
+ "types": "./dist/composed/extensions/emoji-node.d.ts",
565
+ "import": "./dist/composed/extensions/emoji-node.js",
566
+ "default": "./dist/composed/extensions/emoji-node.js"
567
+ },
568
+ "./composed/extensions/emoji-suggestion": {
569
+ "types": "./dist/composed/extensions/emoji-suggestion.d.ts",
570
+ "import": "./dist/composed/extensions/emoji-suggestion.js",
571
+ "default": "./dist/composed/extensions/emoji-suggestion.js"
572
+ },
518
573
  "./composed/filter-bar": {
519
574
  "types": "./dist/composed/filter-bar.d.ts",
520
575
  "import": "./dist/composed/filter-bar.js",
@@ -721,6 +776,16 @@
721
776
  "import": "./dist/ai/blocks/index.js",
722
777
  "default": "./dist/ai/blocks/index.js"
723
778
  },
779
+ "./ai/blocks/error": {
780
+ "types": "./dist/ai/blocks/error.d.ts",
781
+ "import": "./dist/ai/blocks/error.js",
782
+ "default": "./dist/ai/blocks/error.js"
783
+ },
784
+ "./ai/blocks/text": {
785
+ "types": "./dist/ai/blocks/text.d.ts",
786
+ "import": "./dist/ai/blocks/text.js",
787
+ "default": "./dist/ai/blocks/text.js"
788
+ },
724
789
  "./ai/types": {
725
790
  "types": "./dist/ai/types.d.ts",
726
791
  "import": "./dist/ai/types.js",
@@ -735,11 +800,22 @@
735
800
  "docs/rollback.md",
736
801
  "fonts",
737
802
  "skill",
803
+ "scripts/welcome.mjs",
804
+ "AGENTS.md",
738
805
  "MIGRATION.md",
739
806
  "README.md",
740
807
  "llms.txt",
808
+ "llms-quick.txt",
741
809
  "llms-full.txt"
742
810
  ],
811
+ "agents": {
812
+ "skills": [
813
+ {
814
+ "name": "shilp-sutra",
815
+ "path": "./skill"
816
+ }
817
+ ]
818
+ },
743
819
  "peerDependencies": {
744
820
  "@emoji-mart/data": "^1.0.0",
745
821
  "@emoji-mart/react": "^1.0.0",
@@ -890,6 +966,7 @@
890
966
  "typecheck": "tsc --noEmit",
891
967
  "lint": "eslint src/",
892
968
  "test": "vitest run",
893
- "test:coverage": "vitest run --coverage"
969
+ "test:coverage": "vitest run --coverage",
970
+ "postinstall": "node scripts/welcome.mjs || true"
894
971
  }
895
972
  }