@devalok/shilp-sutra 0.37.1 → 0.38.0

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 (63) hide show
  1. package/MIGRATION.md +67 -0
  2. package/dist/_chunks/tiptap.js +977 -968
  3. package/dist/_chunks/tiptap.js.map +1 -1
  4. package/dist/composed/index.d.ts +0 -2
  5. package/dist/composed/index.d.ts.map +1 -1
  6. package/dist/composed/index.js +5 -6
  7. package/dist/hooks/index.d.ts +2 -2
  8. package/dist/hooks/index.d.ts.map +1 -1
  9. package/dist/hooks/index.js +0 -1
  10. package/dist/ui/alert.d.ts +1 -2
  11. package/dist/ui/alert.d.ts.map +1 -1
  12. package/dist/ui/alert.js +1 -27
  13. package/dist/ui/alert.js.map +1 -1
  14. package/dist/ui/banner.d.ts +3 -5
  15. package/dist/ui/banner.d.ts.map +1 -1
  16. package/dist/ui/banner.js +13 -13
  17. package/dist/ui/banner.js.map +1 -1
  18. package/dist/ui/index.d.ts +1 -1
  19. package/dist/ui/index.d.ts.map +1 -1
  20. package/dist/ui/index.js +2 -2
  21. package/dist/ui/index.js.map +1 -1
  22. package/dist/ui/input.d.ts +1 -9
  23. package/dist/ui/input.d.ts.map +1 -1
  24. package/dist/ui/input.js +26 -27
  25. package/dist/ui/input.js.map +1 -1
  26. package/dist/ui/segmented-control.d.ts +1 -1
  27. package/dist/ui/segmented-control.d.ts.map +1 -1
  28. package/dist/ui/segmented-control.js +2 -4
  29. package/dist/ui/segmented-control.js.map +1 -1
  30. package/docs/components/_header.md +1 -1
  31. package/docs/components/ui/alert.md +4 -1
  32. package/docs/components/ui/banner.md +3 -1
  33. package/docs/components/ui/input.md +4 -2
  34. package/docs/components/ui/segmented-control.md +13 -6
  35. package/docs/recipes/customize-brand.md +216 -0
  36. package/docs/recipes/index.md +51 -0
  37. package/docs/recipes/install-astro.md +178 -0
  38. package/docs/recipes/install-next-app-router.md +230 -0
  39. package/docs/recipes/install-next-pages.md +123 -0
  40. package/docs/recipes/install-remix.md +171 -0
  41. package/docs/recipes/install-tanstack-start.md +143 -0
  42. package/docs/recipes/install-vite.md +170 -0
  43. package/docs/recipes/server-components.md +209 -0
  44. package/docs/recipes/troubleshoot.md +217 -0
  45. package/llms-full.txt +26 -53
  46. package/llms.txt +33 -16
  47. package/package.json +45 -35
  48. package/dist/composed/responsive-overlay.d.ts +0 -23
  49. package/dist/composed/responsive-overlay.d.ts.map +0 -1
  50. package/dist/composed/responsive-overlay.js +0 -40
  51. package/dist/composed/responsive-overlay.js.map +0 -1
  52. package/dist/hooks/use-toast.d.ts +0 -17
  53. package/dist/hooks/use-toast.d.ts.map +0 -1
  54. package/dist/hooks/use-toast.js +0 -3
  55. package/dist/tailwind/index.cjs +0 -41
  56. package/dist/tailwind/index.d.ts +0 -2
  57. package/dist/tailwind/index.d.ts.map +0 -1
  58. package/dist/tailwind/index.js +0 -2
  59. package/dist/tailwind/preset.d.ts +0 -25
  60. package/dist/tailwind/preset.d.ts.map +0 -1
  61. package/dist/tailwind/preset.js +0 -17
  62. package/dist/tailwind/preset.js.map +0 -1
  63. package/docs/components/composed/responsive-overlay.md +0 -41
package/docs/recipes/troubleshoot.md ADDED
@@ -0,0 +1,217 @@
1
+ # Troubleshoot
2
+
3
+ A decision tree for the most common shilp-sutra setup breakages. Read symptoms top-to-bottom; the first match is usually the right diagnosis.
4
+
5
+ ## Symptom: Tailwind utilities don't apply (no styling at all)
6
+
7
+ **Diagnosis:** Tailwind is not detecting design-system source classes, OR the CSS imports are out of order.
8
+
9
+ Check 1 — import order. Open the global CSS file. The order MUST be:
10
+
11
+ ```css
12
+ @import "tailwindcss"; /* FIRST */
13
+ @import "@devalok/shilp-sutra/css"; /* SECOND */
14
+ ```
15
+
16
+ If reversed, swap them.
17
+
18
+ Check 2 — both imports present. Some setups accidentally drop `@import "tailwindcss"` after a refactor. Both imports are required.
19
+
20
+ Check 3 — file is actually loaded. In Next.js, `globals.css` must be imported from `app/layout.tsx` (App Router) or `pages/_app.tsx` (Pages Router). In Vite, from `src/main.tsx`. In Remix, via `links` export. In Astro, from a layout file.
21
+
22
+ ## Symptom: Spacing utilities like `p-4` don't work but `p-ds-04` does
23
+
24
+ **Diagnosis:** Working as designed.
25
+
26
+ Shilp Sutra uses the `--spacing-ds-*` namespace to avoid colliding with consumer numeric spacing. Use `p-ds-04`, `gap-ds-03`, `mx-ds-08`, etc. Plain `p-4` is the consumer's own spacing (Tailwind's default scale) — it works but is unrelated to the design system.
27
+
28
+ If `p-ds-*` does NOT work, you have the styling-not-applying issue above.
29
+
30
+ ## Symptom: Console error or weird animation glitches involving `MotionConfig`, `LayoutGroup`, or `AnimatePresence`
31
+
32
+ **Diagnosis:** Multiple copies of `framer-motion` are resolved.
33
+
34
+ Run:
35
+
36
+ ```bash
37
+ pnpm why framer-motion
38
+ # or
39
+ npm ls framer-motion
40
+ ```
41
+
42
+ If more than one version is listed, fix with overrides:
43
+
44
+ **pnpm:**
45
+ ```jsonc
46
+ // package.json
47
+ {
48
+ "pnpm": {
49
+ "overrides": {
50
+ "framer-motion": "^12"
51
+ }
52
+ }
53
+ }
54
+ ```
55
+
56
+ **npm:**
57
+ ```jsonc
58
+ // package.json
59
+ {
60
+ "overrides": {
61
+ "framer-motion": "^12"
62
+ }
63
+ }
64
+ ```
65
+
66
+ **yarn (berry):**
67
+ ```jsonc
68
+ // package.json
69
+ {
70
+ "resolutions": {
71
+ "framer-motion": "^12"
72
+ }
73
+ }
74
+ ```
75
+
76
+ **bun:**
77
+ ```jsonc
78
+ // package.json
79
+ {
80
+ "overrides": {
81
+ "framer-motion": "^12"
82
+ }
83
+ }
84
+ ```
85
+
86
+ After editing, delete the lockfile + `node_modules` and reinstall.
87
+
88
+ ## Symptom: Next.js error: `Cannot find module '@devalok/shilp-sutra/...'` or `Module parse failed: Unexpected token`
89
+
90
+ **Diagnosis:** `transpilePackages` is missing from `next.config.{ts,js,mjs}`.
91
+
92
+ Add:
93
+
94
+ ```ts
95
+ transpilePackages: ["@devalok/shilp-sutra", "@devalok/shilp-sutra-brand"],
96
+ ```
97
+
98
+ If `@devalok/shilp-sutra-brand` is not installed, list only `@devalok/shilp-sutra`.
99
+
100
+ ## Symptom: Hydration warning on every page load (Next.js)
101
+
102
+ **Diagnosis:** `next-themes` writes the `class` attribute on `<html>` before React hydrates, causing a server/client class mismatch.
103
+
104
+ Add `suppressHydrationWarning` to `<html>` in `app/layout.tsx` (App Router) or `pages/_document.tsx` (Pages Router):
105
+
106
+ ```tsx
107
+ <html lang="en" suppressHydrationWarning>
108
+ ```
109
+
110
+ This warning is specific to the `class` attribute on `<html>` — it does NOT suppress hydration warnings on other elements.
111
+
112
+ ## Symptom: Dark mode toggle does nothing
113
+
114
+ **Diagnosis:** The `.dark` class is not being applied to `<html>` (or any ancestor of the components).
115
+
116
+ Quick verification — open the browser console and run:
117
+
118
+ ```js
119
+ document.documentElement.classList.add("dark");
120
+ ```
121
+
122
+ If components now render in dark mode, the toggle wiring is broken (not the design system). Check:
123
+
124
+ - `next-themes` is installed and `<ThemeProvider attribute="class">` wraps the app
125
+ - For Vite/Remix/Astro/TanStack: the `theme-bootstrap.js` script runs before any React mount
126
+
127
+ If `.dark` IS on `<html>` and components still look light, the CSS imports are out of order — see the first symptom above.
128
+
129
+ ## Symptom: RSC error — `You're importing a component that needs useState. It only works in a Client Component`
130
+
131
+ **Diagnosis:** A client-only shilp-sutra component is being imported into a Server Component via the barrel.
132
+
133
+ Switch to per-component imports:
134
+
135
+ ```tsx
136
+ // ❌ pulls client code into RSC
137
+ import { Button } from "@devalok/shilp-sutra/ui";
138
+
139
+ // ✅ component-scoped, declares "use client" only where needed
140
+ import { Button } from "@devalok/shilp-sutra/ui/button";
141
+ ```
142
+
143
+ For the full RSC-safety matrix, see [server-components.md](./server-components.md).
144
+
145
+ ## Symptom: Fonts render in browser default (Times/Arial), not Inter/Ranade
146
+
147
+ **Diagnosis:** Either the CSS import did not load (see first symptom), or the consumer is overriding `--font-sans` / `--font-display` and pointing at a font that isn't loaded.
148
+
149
+ Check the computed value of `--font-sans` on `<html>` in DevTools. It should be `"Inter Variable", system-ui, ...`. If the override variable points at a font that isn't loaded, the browser falls back.
150
+
151
+ The font files ship inside the package — no `next/font` configuration is required for the defaults to work.
152
+
153
+ ## Symptom: Bare `shadow` class produces no visible shadow
154
+
155
+ **Diagnosis:** Working as designed. Tailwind 4 has no default `--shadow` token, so the `shadow` utility no longer exists.
156
+
157
+ Use the explicit shadow variants:
158
+
159
+ - `shadow-raised` — cards, buttons
160
+ - `shadow-overlay` — popovers, dropdowns
161
+ - `shadow-floating` — modals, dialogs
162
+ - `shadow-brand` — accent emphasis
163
+
164
+ ## Symptom: `<Toaster />` is mounted but `toast()` doesn't show anything
165
+
166
+ **Diagnosis:** Either `sonner` is not installed, or two `<Toaster />` instances are mounted at different positions and they're stacking off-screen.
167
+
168
+ Check 1 — `pnpm list sonner` shows `^2.0.0` or higher.
169
+
170
+ Check 2 — only ONE `<Toaster />` is mounted in the app. Search the project: `grep -r "<Toaster" src/ app/`.
171
+
172
+ In dev mode, calling `toast()` without a mounted `<Toaster />` logs a one-time console warning pointing to the fix (since v0.36.0).
173
+
174
+ ## Symptom: Build error mentioning `use-sync-external-store`
175
+
176
+ **Diagnosis:** Should not happen since v0.37.0 — `use-sync-external-store` was moved to runtime dependencies and is auto-installed transitively.
177
+
178
+ If it still happens, install it explicitly:
179
+
180
+ ```bash
181
+ pnpm add use-sync-external-store
182
+ ```
183
+
184
+ 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.
185
+
186
+ ## Symptom: Storybook MCP server `localhost:6006/mcp` returns 404
187
+
188
+ **Diagnosis:** Storybook dev server isn't running, OR the MCP plugin is not enabled in this Storybook version.
189
+
190
+ Check 1 — `pnpm dev` is running and `http://localhost:6006/` shows the Storybook UI.
191
+ Check 2 — the MCP endpoint requires Storybook 9+ with the MCP plugin enabled. Older versions of this repo's Storybook setup may need an upgrade.
192
+
193
+ The MCP server is a development convenience for AI agents — `llms.txt` and `llms-full.txt` are the authoritative docs and do not require a running server.
194
+
195
+ ## Still stuck
196
+
197
+ Open an issue with this template:
198
+
199
+ ```md
200
+ ## Environment
201
+ - Framework + version (Next.js 15.x / Vite 5.x / Remix 2.x / Astro 5.x / TanStack Start ...)
202
+ - Package manager + version (pnpm 10.x / npm 11.x / yarn / bun)
203
+ - Node version
204
+ - @devalok/shilp-sutra version
205
+ - Other peer deps (framer-motion, sonner, tailwindcss versions)
206
+
207
+ ## What I tried
208
+ [Recipe followed, step where it broke]
209
+
210
+ ## What happened
211
+ [Exact error message, stack trace, screenshot]
212
+
213
+ ## What I expected
214
+ [Behavior described in the recipe]
215
+ ```
216
+
217
+ File at: <https://github.com/devalok-design/shilp-sutra/issues/new>
package/llms-full.txt CHANGED
@@ -5,7 +5,7 @@
5
5
  > All variant values and props verified from source CVA definitions.
6
6
  >
7
7
  > Package: @devalok/shilp-sutra
8
- > Version: 0.37.1
8
+ > Version: 0.38.0
9
9
  >
10
10
  > **If you are an AI agent reading this file top-to-bottom:** the Setup
11
11
  > section below is authoritative. If any later per-component doc or a
@@ -39,7 +39,7 @@ pnpm add sonner
39
39
  transpilePackages: ['@devalok/shilp-sutra', '@devalok/shilp-sutra-brand'],
40
40
  ```
41
41
 
42
- **Do NOT** import `@devalok/shilp-sutra/tailwind` in a `tailwind.config.ts`. That export is a deprecated no-op stub and logs a dev-mode `console.warn`. It is scheduled for removal in 0.38.
42
+ **Do NOT** import `@devalok/shilp-sutra/tailwind`. That export was removed in 0.38.0. Use the CSS-first setup (`@import "tailwindcss"; @import "@devalok/shilp-sutra/css";`) — no `tailwind.config.ts` is required.
43
43
 
44
44
  ### Peer dependencies (0.37.0)
45
45
 
@@ -256,7 +256,7 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
256
256
  - Category: ui
257
257
 
258
258
  ## Props
259
- variant: "subtle" | "solid" | "outline" | "filled" (deprecated alias for "solid")
259
+ variant: "subtle" | "solid" | "outline"
260
260
  color: "info" | "success" | "warning" | "error" | "neutral"
261
261
  size: "sm" | "md" | "lg"
262
262
  title: string (optional)
@@ -287,6 +287,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
287
287
  - Icon is auto-selected by color (info=circle, success=check, warning=triangle, error=alert)
288
288
 
289
289
  ## Changes
290
+ ### v0.38.0
291
+ - **Removed** (BREAKING) `variant="filled"` deprecated alias. Use `variant="solid"`.
292
+
290
293
  ### v0.31.0
291
294
  - **Added** `size` prop: `sm | md | lg`. Default `md` (non-breaking).
292
295
 
@@ -722,7 +725,6 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
722
725
  ## Props
723
726
  color: "info" | "success" | "warning" | "error" | "neutral"
724
727
  actions: ReactNode (optional action slot for one or more buttons; wraps on narrow viewports)
725
- action: ReactNode (DEPRECATED — use `actions` instead)
726
728
  onDismiss: () => void (optional, shows X button)
727
729
  children: ReactNode (message text)
728
730
 
@@ -749,6 +751,9 @@ Note: getFormFieldA11y() was removed in favor of useFormField() hook.
749
751
  - `onDismiss` fires after the exit animation completes, not immediately on dismiss button click
750
752
 
751
753
  ## Changes
754
+ ### v0.38.0
755
+ - **Removed** (BREAKING) deprecated singular `action` prop. Use `actions={[...]}` (plural).
756
+
752
757
  ### v0.20.0
753
758
  - **Added** `actions` prop (plural) for multiple action buttons with mobile-friendly flex-wrap
754
759
  - **Deprecated** `action` prop — use `actions` instead (both still work; `actions` takes priority)
@@ -2576,8 +2581,6 @@ const { size, stroke } = useIconContext()
2576
2581
  startSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
2577
2582
  endSectionType: 'icon' | 'label' (section display type — auto-inferred from content)
2578
2583
  wrapperClassName: string (classes for the wrapper div — border, bg, ring)
2579
- startIcon: ReactNode (@deprecated — use startSection)
2580
- endIcon: ReactNode (@deprecated — use endSection)
2581
2584
  (plus all standard HTML input attributes except native "size")
2582
2585
 
2583
2586
  ## Types
@@ -2612,6 +2615,10 @@ const { size, stroke } = useIconContext()
2612
2615
  - Section type is auto-inferred: strings default to `'label'` (tinted bg + border), React elements default to `'icon'` (fixed-width centered). Override with `startSectionType`/`endSectionType`.
2613
2616
 
2614
2617
  ## Changes
2618
+ ### v0.38.0
2619
+ - **Removed** (BREAKING) deprecated `startIcon` / `endIcon` props. Use `startSection` / `endSection`.
2620
+ - **Removed** (BREAKING) deprecated `inputVariants` export. Use `inputWrapperVariants`.
2621
+
2615
2622
  ### v0.29.0
2616
2623
  - **Changed** v2 rewrite: container-first architecture with wrapper div holding focus ring
2617
2624
  - **Added** `xs` size (28px height)
@@ -3239,8 +3246,8 @@ const { size, stroke } = useIconContext()
3239
3246
  - Category: ui
3240
3247
 
3241
3248
  ## Props
3242
- size: "sm" | "md" | "lg" (REQUIRED) — also accepts legacy "small" | "medium" | "big"
3243
- variant: "filled" | "tonal" (REQUIRED)
3249
+ size: "sm" | "md" | "lg"
3250
+ variant: "default" | "solid"
3244
3251
  options: SegmentedControlOption[] (REQUIRED)
3245
3252
  selectedId: string (REQUIRED)
3246
3253
  onSelect: (id: string) => void (REQUIRED)
@@ -3248,14 +3255,18 @@ const { size, stroke } = useIconContext()
3248
3255
 
3249
3256
  ## Types
3250
3257
  SegmentedControlOption = { id: string, text: string, icon?: ComponentType<{ className?: string }> }
3251
- SegmentedControlSize = 'sm' | 'md' | 'lg' | 'small' | 'medium' | 'big' (legacy aliases)
3252
- SegmentedControlVariant = 'filled' | 'tonal'
3258
+ SegmentedControlSize = 'sm' | 'md' | 'lg'
3259
+ SegmentedControlVariant = 'default' | 'solid'
3260
+
3261
+ ## Defaults
3262
+ size: "md"
3263
+ variant: "default"
3253
3264
 
3254
3265
  ## Example
3255
3266
  ```jsx
3256
3267
  <SegmentedControl
3257
3268
  size="md"
3258
- variant="tonal"
3269
+ variant="default"
3259
3270
  options={[
3260
3271
  { id: 'list', text: 'List' },
3261
3272
  { id: 'grid', text: 'Grid' },
@@ -3278,11 +3289,14 @@ const { size, stroke } = useIconContext()
3278
3289
  - Use Tabs (not SegmentedControl) when you need associated content panels per option
3279
3290
 
3280
3291
  ## Changes
3292
+ ### v0.38.0
3293
+ - **Removed** (BREAKING) deprecated `variant="accent"` alias. Use `variant="solid"`.
3294
+
3281
3295
  ### v0.18.0
3282
3296
  - **Fixed** `bg-interactive` changed to `bg-accent-9`, `bg-field` changed to `bg-surface-3` (OKLCH migration)
3283
3297
 
3284
3298
  ### v0.4.2
3285
- - **Changed** (BREAKING) `color` prop renamed to `variant` (values `filled`/`tonal` unchanged)
3299
+ - **Changed** (BREAKING) `color` prop renamed to `variant`
3286
3300
 
3287
3301
  ### v0.1.1
3288
3302
  - **Fixed** `tabIndex={0}` changed to `tabIndex={-1}` on tablist wrapper — fixes double-focus keyboard navigation bug
@@ -5932,47 +5946,6 @@ Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'u
5932
5946
 
5933
5947
  ### v0.1.0
5934
5948
  - **Added** Initial release
5935
- # ResponsiveOverlay
5936
-
5937
- - Import: @devalok/shilp-sutra/composed/responsive-overlay
5938
- - Server-safe: No
5939
- - Category: composed
5940
-
5941
- ## Props
5942
- open: boolean
5943
- onOpenChange: (open: boolean) => void
5944
- title: string
5945
- description: string
5946
- breakpoint: "sm" | "md" (below this renders as bottom Sheet; above as Dialog)
5947
- children: ReactNode
5948
- className: string
5949
-
5950
- ## Defaults
5951
- breakpoint="md"
5952
-
5953
- ## Example
5954
- ```jsx
5955
- <ResponsiveOverlay
5956
- open={open}
5957
- onOpenChange={setOpen}
5958
- title="Edit task"
5959
- description="Update the task details"
5960
- >
5961
- <TaskForm />
5962
- </ResponsiveOverlay>
5963
- ```
5964
-
5965
- ## Composability
5966
- - **One component, two containers.** Above `breakpoint`: centered Dialog. Below: bottom-anchored Sheet. Same content slot, different surface treatment per viewport.
5967
- - **Standard controlled model** — `open` + `onOpenChange` (same shape as Dialog/Sheet).
5968
- - **title + description pattern** — matches Dialog/Sheet's requirement for an accessible heading. Omit both only when the surrounding context makes the purpose obvious (rare).
5969
- - **SSR caveat:** `window.matchMedia` reads on mount — initial SSR render defaults to desktop (Dialog). Hydration flips to Sheet on mobile. Acceptable for most flows; visible layout shift on low-spec devices.
5970
- - **When to use:** Any modal that needs to behave differently on mobile (edit dialogs, filter panels, quick-action menus). For always-the-same behavior, use Dialog or Sheet directly.
5971
-
5972
- ## Gotchas
5973
- - Renders a centered Dialog on desktop and a bottom Sheet on mobile — same content, different container
5974
- - Uses `window.matchMedia` internally — SSR defaults to desktop (Dialog) until hydration
5975
- - Title and description are optional; if omitted, no header is rendered in either mode
5976
5949
  # RichChatInput
5977
5950
 
5978
5951
  - Import: @devalok/shilp-sutra/composed/rich-chat-input
package/llms.txt CHANGED
@@ -4,6 +4,30 @@
4
4
  > Built on the same primitives as shadcn/ui but with key API differences.
5
5
  > Read this file BEFORE writing any UI code. Do NOT guess from shadcn/ui knowledge.
6
6
 
7
+ ## QUICK SETUP (AI agents — start here)
8
+
9
+ If you are setting up shilp-sutra in a consumer project for the first time, **do not improvise**. Use a recipe.
10
+
11
+ When the package is installed, recipes ship at `node_modules/@devalok/shilp-sutra/docs/recipes/`. Pick one based on the consumer's framework:
12
+
13
+ | Framework | Recipe file |
14
+ |---|---|
15
+ | Next.js (App Router) | `install-next-app-router.md` |
16
+ | Next.js (Pages Router) | `install-next-pages.md` |
17
+ | Vite + React | `install-vite.md` |
18
+ | Astro | `install-astro.md` |
19
+ | Remix | `install-remix.md` |
20
+ | TanStack Start | `install-tanstack-start.md` |
21
+ | Other React + Tailwind | start from `install-vite.md` and adapt |
22
+
23
+ Other recipes:
24
+
25
+ - `customize-brand.md` — token override cookbook (color, radius, font, spacing)
26
+ - `server-components.md` — RSC-safety matrix and import patterns
27
+ - `troubleshoot.md` — decision tree for the 8 most common breakages
28
+
29
+ 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
+
7
31
  ## BREAKING CHANGES (v0.37.0 — Tailwind 4 CSS-first)
8
32
 
9
33
  **Setup migration only — component APIs unchanged.** See `MIGRATION.md` at the root of this package (or https://github.com/devalok-design/shilp-sutra/blob/main/MIGRATION.md#v0370--tailwind-4-css-first-migration) for the full guide.
@@ -13,7 +37,7 @@
13
37
  @import "tailwindcss";
14
38
  @import "@devalok/shilp-sutra/css";
15
39
  ```
16
- The old `./tailwind` export is a deprecated no-op stub; importing it logs a dev-mode `console.warn` and is scheduled for removal in 0.38.
40
+ The `./tailwind` export has been removed in 0.38. Delete any `tailwind.config.ts` that referenced the preset and switch to the CSS import above.
17
41
  - **framer-motion is now a required peer dep.** Previously bundled. Install: `pnpm add framer-motion`. Module-scoped React contexts (MotionConfig, LayoutGroup, AnimatePresence) must be single-copy — the peer declaration forces pnpm to dedupe against the consumer's version.
18
42
  - **sonner is now an optional peer dep.** Install only if you render `<Toaster />`: `pnpm add sonner`.
19
43
  - **tailwindcss peer tightened to `^4.0.0`.** No more `^3.4.0 || ^4.0.0`.
@@ -48,8 +72,6 @@
48
72
  - **MessageList:** `isLoadingMore` renamed to `loadingMore`.
49
73
  - **AppCommandPalette:** Default Karm routes removed. Use `CommandRegistryProvider` for page registration. `SearchResult` type adds optional `href` field.
50
74
  - **NumberInput:** Shape changed from pill to rounded rectangle.
51
- - **Alert:** `variant="filled"` deprecated → use `"solid"` (alias still works).
52
- - **SegmentedControl:** `variant="accent"` deprecated → use `"solid"` (alias still works).
53
75
  - **Dependencies:** `@floating-ui/dom`, `@tiptap/*`, `prosemirror-state` moved to devDeps (bundled; consumers no longer install them).
54
76
 
55
77
  ## NEW (v0.35.0)
@@ -100,14 +122,13 @@
100
122
 
101
123
  - **Button:** `variant="default"` removed (use `"solid"`), `variant="destructive"` removed (use `variant="solid" color="error"`), `color="default"` removed (use `"accent"`).
102
124
  - **Chip:** Removed. Use `Badge` instead.
103
- - **SegmentedControl:** Rewritten. `variant="filled"` → `"accent"`, `variant="tonal"` → `"default"`. `SegmentedControlItem` no longer exported. Legacy sizes `small`/`medium`/`big` removed.
125
+ - **SegmentedControl:** Rewritten. Variants are `"default"` (white pill) and `"solid"` (brand pill). `SegmentedControlItem` no longer exported.
104
126
  - **TopBar:** Now renders as `<header>` (was `<div>`).
105
127
  - **Sidebar:** Now renders as `<aside>` (was `<div>`).
106
128
  - **InfoBlock:** `role="status"` (was `role="alert"`).
107
129
  - **Border tokens:** One step darker system-wide.
108
130
  - **Dark mode button text:** Pure white `neutral-0` (#fff) on brand-colored buttons.
109
131
  - **BottomNavbar:** Bottom padding is now `pb-safe` (safe-area-inset).
110
- - **ResponsiveOverlay:** Deprecated. Use Dialog or Sheet directly.
111
132
  - **iOS inputs:** Forced to `font-size: max(16px, 1em)` on mobile via preset.
112
133
 
113
134
  ## CHANGES (v0.32.0)
@@ -124,7 +145,7 @@
124
145
  - **DataTable `mobileView="card"`** — Rows render as stacked cards below 640px. First column = card title, rest = label-value pairs.
125
146
  - **DataTable `aria-sort`** — Sortable column headers include `aria-sort`.
126
147
  - **Charts `ariaLabel` prop** — Configurable screen reader label on all chart components.
127
- - **SegmentedControl** — Redesigned: `variant="default"` (white pill + shadow-sm) | `variant="accent"` (brand pill). Inset radius, snappy spring animation.
148
+ - **SegmentedControl** — Redesigned: `variant="default"` (white pill + shadow-raised) | `variant="solid"` (brand pill). Inset radius, snappy spring animation.
128
149
  - **`--shadow-kbd` token** — Keyboard shortcut badge shadow. Use `shadow-kbd` utility.
129
150
  - **Checkbox/Radio `size` prop** — `sm | md (default) | lg`.
130
151
 
@@ -409,11 +430,8 @@ import { toast } from '@devalok/shilp-sutra/ui/toast'
409
430
  // Hooks:
410
431
  import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
411
432
 
412
- // CSS tokens (import once at app root):
413
- import '@devalok/shilp-sutra/tokens'
414
-
415
- // Tailwind preset (in tailwind.config):
416
- import shilpSutra from '@devalok/shilp-sutra/tailwind'
433
+ // CSS tokens (import once at app root — already included in /css):
434
+ import '@devalok/shilp-sutra/css'
417
435
 
418
436
  ## CRITICAL: Differences from shadcn/ui
419
437
 
@@ -456,7 +474,7 @@ Components with two-axis system: Button, Badge, Alert, Banner, Progress, StatusB
456
474
  - 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.
457
475
  - 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.
458
476
  - 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.
459
- - Input: size(xs|sm|md|lg) state(InputState) + startSection(ReactNode), endSection(ReactNode), startSectionClickable(bool), endSectionClickable(bool), startSectionType('icon'|'label'), endSectionType('icon'|'label'), wrapperClassName(string). Container-level focus ring wraps input + sections as one unit. Sections are pointer-events-none by default; use *SectionClickable for interactive content (clear buttons, toggles). Section type auto-inferred: strings→'label' (tinted bg + border separator), React elements→'icon' (fixed-width centered). Override with *SectionType. Flexbox section layout. Icons auto-size via IconProvider per input size. className targets <input>, wrapperClassName targets wrapper div. Deprecated aliases: startIcon→startSection, endIcon→endSection, inputVariants→inputWrapperVariants. Type: InputState = 'default' | 'error' | 'warning' | 'success'
477
+ - Input: size(xs|sm|md|lg) state(InputState) + startSection(ReactNode), endSection(ReactNode), startSectionClickable(bool), endSectionClickable(bool), startSectionType('icon'|'label'), endSectionType('icon'|'label'), wrapperClassName(string). Container-level focus ring wraps input + sections as one unit. Sections are pointer-events-none by default; use *SectionClickable for interactive content (clear buttons, toggles). Section type auto-inferred: strings→'label' (tinted bg + border separator), React elements→'icon' (fixed-width centered). Override with *SectionType. Flexbox section layout. Icons auto-size via IconProvider per input size. className targets <input>, wrapperClassName targets wrapper div. Type: InputState = 'default' | 'error' | 'warning' | 'success'
460
478
  - SearchInput: size(xs|sm|md|lg) + loading, onClear. Delegates to Input v2 sections internally.
461
479
  - NumberInput: value + onValueChange, min, max, step (controlled only)
462
480
  - Textarea: size(xs|sm|md|lg) state(default|error|warning|success)
@@ -467,12 +485,12 @@ Components with two-axis system: Button, Badge, Alert, Banner, Progress, StatusB
467
485
  - Select > SelectTrigger(size: xs|sm|md|lg) > SelectValue; SelectContent > SelectItem(value)
468
486
  - Toggle: variant(default|outline) size(sm|md|lg)
469
487
  - ToggleGroup > ToggleGroupItem (variant/size propagate from root)
470
- - SegmentedControl > SegmentedControlItem: variant(filled|tonal) size(sm|md|lg). Types: SegmentedControlOption = { id, text, icon? }, SegmentedControlSize = 'sm' | 'md' | 'lg', SegmentedControlVariant = 'filled' | 'tonal'
488
+ - SegmentedControl: variant(default|solid) size(sm|md|lg) options selectedId onSelect. Types: SegmentedControlOption = { id, text, icon? }, SegmentedControlSize = 'sm' | 'md' | 'lg', SegmentedControlVariant = 'default' | 'solid'
471
489
  - Slider: standard Radix slider
472
490
 
473
491
  ### Feedback & Notifications
474
- - Alert: variant(subtle|filled|outline) color(info|success|warning|error|neutral) + title, onDismiss
475
- - Banner: color(info|success|warning|error|neutral) + actions?(ReactNode), onDismiss. `action` (singular) deprecated, use `actions`. Mobile flex-wrap for multiple buttons.
492
+ - Alert: variant(subtle|solid|outline) color(info|success|warning|error|neutral) size(sm|md|lg) + title, onDismiss
493
+ - Banner: color(info|success|warning|error|neutral) + actions?(ReactNode), onDismiss. Mobile flex-wrap for multiple buttons.
476
494
  - Toast: imperative API via toast.success/error/warning/info/loading/message/undo/promise/upload/custom — REQUIRES <Toaster> at layout root
477
495
  - Spinner: size(sm|md|lg) — renders with role="status"
478
496
  - Progress: track size(sm|md|lg), indicator color(default|success|warning|error), autoColor(boolean, auto-shifts color by value: 0-59=default, 60-84=warning, 85-100=success, >100=error)
@@ -568,7 +586,6 @@ Import: `@devalok/shilp-sutra/ui/chat`
568
586
  - BulkActionBar: show, count, onClearSelection, actions[{label,icon?,onClick,color?,disabled?}]. Fixed bottom floating bar for multi-select contexts.
569
587
  - DeadlineIndicator: deadline(Date|string), warningThreshold?(1440min), criticalThreshold?(240min), format(relative|absolute), showIcon. Color transitions: green→yellow→red→overdue.
570
588
  - MasterDetail: selected, onBack, masterWidth, breakpoint(sm|md|lg). Compound: MasterDetail.List, MasterDetail.Detail, MasterDetail.ListItem(active). Desktop=grid, mobile=stacked with back button.
571
- - ResponsiveOverlay: open, onOpenChange, title, description, breakpoint(sm|md). Dialog on desktop, bottom Sheet on mobile.
572
589
  - MarkdownViewer: content(string), compact?, allowHtml?(false), linkTarget?('_blank'). Renders markdown with design system tokens.
573
590
  - EmojiPicker: onSelect(emoji), set?(native|apple|google|twitter|facebook), theme(auto|light|dark). EmojiPickerPopover wraps in Popover. Lazy-loads emoji-mart with set-specific data.
574
591
  - EmojiNode: TipTap inline atom node for spritesheet emoji rendering. Attrs: id, native, set, x, y. Use createEmojiSuggestion(set) to wire :shortcode: autocomplete. Export: EmojiNode, EmojiNodeAttrs, createEmojiSuggestion.
package/package.json CHANGED
@@ -1,13 +1,44 @@
1
1
  {
2
2
  "name": "@devalok/shilp-sutra",
3
- "version": "0.37.1",
4
- "description": "Devalok Design System — tokens, components, and patterns for Next.js",
3
+ "version": "0.38.0",
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
+ "author": "Devalok Design & Strategy Studios <shilp-sutra@devalok.in>",
7
+ "homepage": "https://devalok-design.github.io/shilp-sutra/",
6
8
  "repository": {
7
9
  "type": "git",
8
10
  "url": "https://github.com/devalok-design/shilp-sutra",
9
11
  "directory": "packages/core"
10
12
  },
13
+ "bugs": {
14
+ "url": "https://github.com/devalok-design/shilp-sutra/issues"
15
+ },
16
+ "keywords": [
17
+ "react",
18
+ "design-system",
19
+ "components",
20
+ "ui",
21
+ "ui-library",
22
+ "tailwindcss",
23
+ "tailwind-v4",
24
+ "typescript",
25
+ "accessible",
26
+ "a11y",
27
+ "wcag",
28
+ "radix-ui",
29
+ "headless",
30
+ "cva",
31
+ "design-tokens",
32
+ "oklch",
33
+ "framer-motion",
34
+ "dark-mode",
35
+ "nextjs",
36
+ "vite",
37
+ "astro",
38
+ "remix",
39
+ "ai-agent",
40
+ "llms-txt"
41
+ ],
11
42
  "type": "module",
12
43
  "main": "./dist/ui/index.js",
13
44
  "module": "./dist/ui/index.js",
@@ -554,11 +585,6 @@
554
585
  "import": "./dist/composed/status-badge.js",
555
586
  "default": "./dist/composed/status-badge.js"
556
587
  },
557
- "./composed/responsive-overlay": {
558
- "types": "./dist/composed/responsive-overlay.d.ts",
559
- "import": "./dist/composed/responsive-overlay.js",
560
- "default": "./dist/composed/responsive-overlay.js"
561
- },
562
588
  "./composed/schedule-view": {
563
589
  "types": "./dist/composed/schedule-view.d.ts",
564
590
  "import": "./dist/composed/schedule-view.js",
@@ -629,23 +655,6 @@
629
655
  "import": "./dist/hooks/use-mobile.js",
630
656
  "default": "./dist/hooks/use-mobile.js"
631
657
  },
632
- "./hooks/use-toast": {
633
- "types": "./dist/hooks/use-toast.d.ts",
634
- "import": "./dist/hooks/use-toast.js",
635
- "default": "./dist/hooks/use-toast.js"
636
- },
637
- "./tailwind": {
638
- "types": "./dist/tailwind/index.d.ts",
639
- "require": "./dist/tailwind/index.cjs",
640
- "import": "./dist/tailwind/index.js",
641
- "default": "./dist/tailwind/index.js"
642
- },
643
- "./tailwind/preset": {
644
- "types": "./dist/tailwind/preset.d.ts",
645
- "require": "./dist/tailwind/index.cjs",
646
- "import": "./dist/tailwind/preset.js",
647
- "default": "./dist/tailwind/preset.js"
648
- },
649
658
  "./utils": {
650
659
  "types": "./dist/ui/lib/utils.d.ts",
651
660
  "import": "./dist/ui/lib/utils.js",
@@ -722,6 +731,7 @@
722
731
  "files": [
723
732
  "dist",
724
733
  "docs/components",
734
+ "docs/recipes",
725
735
  "docs/rollback.md",
726
736
  "fonts",
727
737
  "MIGRATION.md",
@@ -830,19 +840,19 @@
830
840
  "@emoji-mart/react": "^1.1.1",
831
841
  "@floating-ui/dom": "^1.7.6",
832
842
  "@floating-ui/react-dom": "^2.1.8",
833
- "@tabler/icons-react": "^3.41.1",
843
+ "@tabler/icons-react": "^3.42.0",
834
844
  "@tanstack/react-table": "^8.21.3",
835
845
  "@tanstack/react-virtual": "^3.13.23",
836
- "@tiptap/core": "^3.22.3",
837
- "@tiptap/extension-highlight": "^3.22.3",
838
- "@tiptap/extension-image": "^3.22.3",
839
- "@tiptap/extension-list": "^3.22.3",
840
- "@tiptap/extension-mention": "^3.22.3",
841
- "@tiptap/extension-text-align": "^3.22.3",
842
- "@tiptap/extensions": "^3.22.3",
843
- "@tiptap/react": "^3.22.3",
844
- "@tiptap/starter-kit": "^3.22.3",
845
- "@tiptap/suggestion": "^3.22.3",
846
+ "@tiptap/core": "^3.22.5",
847
+ "@tiptap/extension-highlight": "^3.22.5",
848
+ "@tiptap/extension-image": "^3.22.5",
849
+ "@tiptap/extension-list": "^3.22.5",
850
+ "@tiptap/extension-mention": "^3.22.5",
851
+ "@tiptap/extension-text-align": "^3.22.5",
852
+ "@tiptap/extensions": "^3.22.5",
853
+ "@tiptap/react": "^3.22.5",
854
+ "@tiptap/starter-kit": "^3.22.5",
855
+ "@tiptap/suggestion": "^3.22.5",
846
856
  "@types/react-syntax-highlighter": "^15.5.13",
847
857
  "aria-hidden": "^1.2.6",
848
858
  "class-variance-authority": "^0.7.1",
package/dist/composed/responsive-overlay.d.ts DELETED
@@ -1,23 +0,0 @@
1
- "use client";
2
- import * as React from 'react';
3
- /**
4
- * @deprecated Dialog and Sheet now auto-adapt to mobile viewports.
5
- * Use Dialog directly (fullScreens on mobile) or Sheet directly (becomes bottom sheet on mobile).
6
- * This component will be removed in a future major version.
7
- */
8
- export interface ResponsiveOverlayProps {
9
- open: boolean;
10
- onOpenChange: (open: boolean) => void;
11
- title?: string;
12
- description?: string;
13
- /** Below this breakpoint renders as bottom Sheet @default 'md' */
14
- breakpoint?: 'sm' | 'md';
15
- children: React.ReactNode;
16
- className?: string;
17
- }
18
- /**
19
- * @deprecated Use Dialog or Sheet directly — they are now individually mobile-responsive.
20
- */
21
- declare function ResponsiveOverlay({ open, onOpenChange, title, description, breakpoint, children, className, }: ResponsiveOverlayProps): import("react/jsx-runtime").JSX.Element;
22
- export { ResponsiveOverlay };
23
- //# sourceMappingURL=responsive-overlay.d.ts.map
package/dist/composed/responsive-overlay.d.ts.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"responsive-overlay.d.ts","sourceRoot":"","sources":["../../src/composed/responsive-overlay.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAqB9B;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,OAAO,CAAA;IACb,YAAY,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,CAAA;IACrC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;IACxB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;IACzB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AA8BD;;GAEG;AACH,iBAAS,iBAAiB,CAAC,EACzB,IAAI,EACJ,YAAY,EACZ,KAAK,EACL,WAAW,EACX,UAAiB,EACjB,QAAQ,EACR,SAAS,GACV,EAAE,sBAAsB,2CAgCxB;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAA"}