@devalok/shilp-sutra 0.34.0 → 0.36.0

package/docs/components/ui/toast.md

@@ -1,65 +1,65 @@
-# Toast
-
-- Import: @devalok/shilp-sutra/ui/toast
-- Server-safe: No
-- Category: ui
-
-## API
-    toast('Plain message')                    // no icon, no accent bar
-    toast.message('Same as plain')            // alias for toast()
-    toast.success('Saved!')                   // green accent, check icon
-    toast.error('Failed', { description })    // red accent, X icon
-    toast.warning('Disk low')                 // yellow accent, triangle icon
-    toast.info('New version')                 // blue accent, info icon
-    toast.loading('Saving...')                // interactive accent, spinner, no timer bar, duration: Infinity
-    toast.promise(asyncFn, { loading, success, error })  // dynamic messages
-    toast.undo('Item deleted', { onUndo, duration? })    // 8s default, Undo action button
-    toast.upload({ files, id?, onRetry?, onRemove? })    // upload toast with per-file progress
-    toast.custom((id) => <MyComponent />, options)       // escape hatch
-    toast.dismiss(id?)                                   // specific or all
-
-## Options (all methods accept)
-    id?: string
-    description?: ReactNode
-    action?: { label: string, onClick: () => void }
-    cancel?: { label: string, onClick: () => void }
-    duration?: number (ms, default 5000)
-
-## Types
-    UploadFile: { id, name, size (bytes), progress? (0-100), status: 'pending' | 'uploading' | 'processing' | 'complete' | 'error', error?, previewUrl? }
-
-## Utility
-    formatFileSize(bytes) => string (B, KB, MB, GB)
-
-## Example
-```jsx
-// Mount <Toaster /> once at root layout
-import { toast } from '@devalok/shilp-sutra/ui/toast'
-
-toast.success('Changes saved!')
-toast.error('Upload failed', { description: 'File too large' })
-toast.undo('Task deleted', { onUndo: () => restoreTask(id) })
-```
-
-## Gotchas
-- DO NOT use useToast() hook — it is deprecated, use imperative toast.* methods
-- DO NOT use toast({ title, color }) object syntax — use toast.success('message') etc.
-- DO NOT call toast() without <Toaster /> mounted at layout root
-- Timer bar animates auto-dismiss countdown (hidden on loading toasts)
-- Upload toast replaces the old UploadProgress composed component
-
-## Changes
-### v0.18.0
-- **Changed** (BREAKING) Complete rewrite to Sonner-based imperative API
-- **Fixed** Accent bar colors from step 7 to step 9 (decorative fills use solid step)
-
-### v0.4.2
-- **Changed** (BREAKING) `color="default"` renamed to `color="neutral"`
-
-### v0.3.0
-- **Changed** (BREAKING) `variant` prop renamed to `color` for semantic intent
-- **Fixed** Close button now always visible (was hidden until hover)
-
-### v0.1.0
-- **Added** Initial release
-- **Fixed** Toast now announces to screen readers (`role="status"`, `aria-live`)
+# Toast
+
+- Import: @devalok/shilp-sutra/ui/toast
+- Server-safe: No
+- Category: ui
+
+## API
+    toast('Plain message')                    // no icon, no accent bar
+    toast.message('Same as plain')            // alias for toast()
+    toast.success('Saved!')                   // green accent, check icon
+    toast.error('Failed', { description })    // red accent, X icon
+    toast.warning('Disk low')                 // yellow accent, triangle icon
+    toast.info('New version')                 // blue accent, info icon
+    toast.loading('Saving...')                // interactive accent, spinner, no timer bar, duration: Infinity
+    toast.promise(asyncFn, { loading, success, error })  // dynamic messages
+    toast.undo('Item deleted', { onUndo, duration? })    // 8s default, Undo action button
+    toast.upload({ files, id?, onRetry?, onRemove? })    // upload toast with per-file progress
+    toast.custom((id) => <MyComponent />, options)       // escape hatch
+    toast.dismiss(id?)                                   // specific or all
+
+## Options (all methods accept)
+    id?: string
+    description?: ReactNode
+    action?: { label: string, onClick: () => void }
+    cancel?: { label: string, onClick: () => void }
+    duration?: number (ms, default 5000)
+
+## Types
+    UploadFile: { id, name, size (bytes), progress? (0-100), status: 'pending' | 'uploading' | 'processing' | 'complete' | 'error', error?, previewUrl? }
+
+## Utility
+    formatFileSize(bytes) => string (B, KB, MB, GB)
+
+## Example
+```jsx
+// Mount <Toaster /> once at root layout
+import { toast } from '@devalok/shilp-sutra/ui/toast'
+
+toast.success('Changes saved!')
+toast.error('Upload failed', { description: 'File too large' })
+toast.undo('Task deleted', { onUndo: () => restoreTask(id) })
+```
+
+## Gotchas
+- DO NOT use useToast() hook — it is deprecated, use imperative toast.* methods
+- DO NOT use toast({ title, color }) object syntax — use toast.success('message') etc.
+- DO NOT call toast() without <Toaster /> mounted at layout root
+- Timer bar animates auto-dismiss countdown (hidden on loading toasts)
+- Upload toast replaces the old UploadProgress composed component
+
+## Changes
+### v0.18.0
+- **Changed** (BREAKING) Complete rewrite to Sonner-based imperative API
+- **Fixed** Accent bar colors from step 7 to step 9 (decorative fills use solid step)
+
+### v0.4.2
+- **Changed** (BREAKING) `color="default"` renamed to `color="neutral"`
+
+### v0.3.0
+- **Changed** (BREAKING) `variant` prop renamed to `color` for semantic intent
+- **Fixed** Close button now always visible (was hidden until hover)
+
+### v0.1.0
+- **Added** Initial release
+- **Fixed** Toast now announces to screen readers (`role="status"`, `aria-live`)

package/docs/components/ui/toaster.md

@@ -1,47 +1,47 @@
-# Toaster
-
-- Import: @devalok/shilp-sutra/ui/toaster
-- Server-safe: No
-- Category: ui
-
-## Props
-    position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
-    closeButton: boolean
-    duration: number (ms)
-    hotkey: string[]
-    visibleToasts: number
-
-## Defaults
-    position: "bottom-right"
-    closeButton: false
-    duration: 5000
-    hotkey: ['altKey', 'KeyT']
-    visibleToasts: 3
-
-## Example
-```jsx
-// Mount once at root layout
-import { Toaster } from '@devalok/shilp-sutra/ui/toaster'
-
-export default function RootLayout({ children }) {
-  return (
-    <>
-      {children}
-      <Toaster />
-    </>
-  )
-}
-```
-
-## Gotchas
-- Must be mounted once at the layout root for toast notifications to work
-- Use the `toast` import from `@devalok/shilp-sutra/ui/toast` to trigger toasts
-
-## Changes
-### v0.18.0
-- **Changed** (BREAKING) Rewritten to Sonner-based engine with custom ToastContent rendering
-- **Added** `ToasterProps` type export
-- **Added** Visual: neutral bg-layer-01 base, colored left accent bar per type, status icon, timer bar
-
-### v0.1.0
-- **Added** Initial release
+# Toaster
+
+- Import: @devalok/shilp-sutra/ui/toaster
+- Server-safe: No
+- Category: ui
+
+## Props
+    position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right'
+    closeButton: boolean
+    duration: number (ms)
+    hotkey: string[]
+    visibleToasts: number
+
+## Defaults
+    position: "bottom-right"
+    closeButton: false
+    duration: 5000
+    hotkey: ['altKey', 'KeyT']
+    visibleToasts: 3
+
+## Example
+```jsx
+// Mount once at root layout
+import { Toaster } from '@devalok/shilp-sutra/ui/toaster'
+
+export default function RootLayout({ children }) {
+  return (
+    <>
+      {children}
+      <Toaster />
+    </>
+  )
+}
+```
+
+## Gotchas
+- Must be mounted once at the layout root for toast notifications to work
+- Use the `toast` import from `@devalok/shilp-sutra/ui/toast` to trigger toasts
+
+## Changes
+### v0.18.0
+- **Changed** (BREAKING) Rewritten to Sonner-based engine with custom ToastContent rendering
+- **Added** `ToasterProps` type export
+- **Added** Visual: neutral bg-layer-01 base, colored left accent bar per type, status icon, timer bar
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/toggle-group.md

@@ -1,43 +1,43 @@
-# ToggleGroup
-
-- Import: @devalok/shilp-sutra/ui/toggle-group
-- Server-safe: No
-- Category: ui
-
-## Props
-### ToggleGroup
-    type: "single" | "multiple"
-    variant: "default" | "outline" (propagated to items)
-    size: "sm" | "md" | "lg" (propagated to items)
-    value: string | string[]
-    onValueChange: (value) => void
-
-### ToggleGroupItem
-    value: string
-
-## Compound Components
-    ToggleGroup (root)
-      ToggleGroupItem (value: string)
-
-## Example
-```jsx
-<ToggleGroup type="single" variant="outline" size="sm" value={alignment} onValueChange={setAlignment}>
-  <ToggleGroupItem value="left"><IconAlignLeft /></ToggleGroupItem>
-  <ToggleGroupItem value="center"><IconAlignCenter /></ToggleGroupItem>
-  <ToggleGroupItem value="right"><IconAlignRight /></ToggleGroupItem>
-</ToggleGroup>
-```
-
-## Gotchas
-- type is required — "single" or "multiple"
-- variant and size propagate from ToggleGroup to items
-
-## Changes
-### v0.18.0
-- **Fixed** Wrapped ToggleGroup context provider value in `useMemo` for performance
-
-### v0.4.2
-- **Added** `ToggleGroupProps`, `ToggleGroupItemProps` type exports
-
-### v0.1.0
-- **Added** Initial release
+# ToggleGroup
+
+- Import: @devalok/shilp-sutra/ui/toggle-group
+- Server-safe: No
+- Category: ui
+
+## Props
+### ToggleGroup
+    type: "single" | "multiple"
+    variant: "default" | "outline" (propagated to items)
+    size: "sm" | "md" | "lg" (propagated to items)
+    value: string | string[]
+    onValueChange: (value) => void
+
+### ToggleGroupItem
+    value: string
+
+## Compound Components
+    ToggleGroup (root)
+      ToggleGroupItem (value: string)
+
+## Example
+```jsx
+<ToggleGroup type="single" variant="outline" size="sm" value={alignment} onValueChange={setAlignment}>
+  <ToggleGroupItem value="left"><IconAlignLeft /></ToggleGroupItem>
+  <ToggleGroupItem value="center"><IconAlignCenter /></ToggleGroupItem>
+  <ToggleGroupItem value="right"><IconAlignRight /></ToggleGroupItem>
+</ToggleGroup>
+```
+
+## Gotchas
+- type is required — "single" or "multiple"
+- variant and size propagate from ToggleGroup to items
+
+## Changes
+### v0.18.0
+- **Fixed** Wrapped ToggleGroup context provider value in `useMemo` for performance
+
+### v0.4.2
+- **Added** `ToggleGroupProps`, `ToggleGroupItemProps` type exports
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/toggle.md

@@ -1,37 +1,37 @@
-# Toggle
-
-- Import: @devalok/shilp-sutra/ui/toggle
-- Server-safe: No
-- Category: ui
-
-## Props
-    variant: "default" | "outline"
-    size: "sm" | "md" | "lg"
-    pressed: boolean
-    onPressedChange: (pressed: boolean) => void
-    defaultPressed: boolean
-
-## Defaults
-    variant: "default"
-    size: "md"
-
-## Example
-```jsx
-<Toggle aria-label="Toggle bold" pressed={isBold} onPressedChange={setIsBold}>
-  <IconBold />
-</Toggle>
-```
-
-## Gotchas
-- Always provide aria-label for accessibility
-
-## Changes
-### v0.18.0
-- **Changed** Migrated to Framer Motion press spring animation
-
-### v0.4.2
-- **Fixed** `className` was passed inside CVA (silently dropped) — now separate `cn()` argument
-- **Added** `ToggleProps` type export
-
-### v0.1.0
-- **Added** Initial release
+# Toggle
+
+- Import: @devalok/shilp-sutra/ui/toggle
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: "default" | "outline"
+    size: "sm" | "md" | "lg"
+    pressed: boolean
+    onPressedChange: (pressed: boolean) => void
+    defaultPressed: boolean
+
+## Defaults
+    variant: "default"
+    size: "md"
+
+## Example
+```jsx
+<Toggle aria-label="Toggle bold" pressed={isBold} onPressedChange={setIsBold}>
+  <IconBold />
+</Toggle>
+```
+
+## Gotchas
+- Always provide aria-label for accessibility
+
+## Changes
+### v0.18.0
+- **Changed** Migrated to Framer Motion press spring animation
+
+### v0.4.2
+- **Fixed** `className` was passed inside CVA (silently dropped) — now separate `cn()` argument
+- **Added** `ToggleProps` type export
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/tooltip.md

@@ -1,38 +1,38 @@
-# Tooltip
-
-- Import: @devalok/shilp-sutra/ui/tooltip
-- Server-safe: No
-- Category: ui
-
-## Compound Components
-    TooltipProvider (REQUIRED at layout root or wrapping tooltip usage, controls delay)
-      Tooltip (root)
-        TooltipTrigger
-        TooltipContent
-
-## Example
-```jsx
-<TooltipProvider>
-  <Tooltip>
-    <TooltipTrigger asChild><Button>Hover me</Button></TooltipTrigger>
-    <TooltipContent>Tooltip text</TooltipContent>
-  </Tooltip>
-</TooltipProvider>
-```
-
-## Gotchas
-- TooltipProvider is REQUIRED — without it, tooltips won't show
-
-## Changes
-### v0.22.0
-- **Added** Auto-provider: `<Tooltip>` now auto-wraps with `<TooltipProvider>` when no ancestor provider exists. No more "tooltip doesn't appear" issues.
-- **Fixed** Content children not rendering — `motion.div` was self-closing (`/>`), so children were never passed through.
-- **Fixed** Text invisible in dark mode — `text-accent-fg` resolves to same value as `bg-surface-fg` in dark mode. Changed to `text-surface-1`.
-
-### v0.18.0
-- **Changed** Migrated to Framer Motion for enter/exit animations
-- **Added** `TooltipContentProps` type export
-- **Fixed** Wrapped Tooltip context provider value in `useMemo` for performance
-
-### v0.1.0
-- **Added** Initial release
+# Tooltip
+
+- Import: @devalok/shilp-sutra/ui/tooltip
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    TooltipProvider (REQUIRED at layout root or wrapping tooltip usage, controls delay)
+      Tooltip (root)
+        TooltipTrigger
+        TooltipContent
+
+## Example
+```jsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild><Button>Hover me</Button></TooltipTrigger>
+    <TooltipContent>Tooltip text</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+## Gotchas
+- TooltipProvider is REQUIRED — without it, tooltips won't show
+
+## Changes
+### v0.22.0
+- **Added** Auto-provider: `<Tooltip>` now auto-wraps with `<TooltipProvider>` when no ancestor provider exists. No more "tooltip doesn't appear" issues.
+- **Fixed** Content children not rendering — `motion.div` was self-closing (`/>`), so children were never passed through.
+- **Fixed** Text invisible in dark mode — `text-accent-fg` resolves to same value as `bg-surface-fg` in dark mode. Changed to `text-surface-1`.
+
+### v0.18.0
+- **Changed** Migrated to Framer Motion for enter/exit animations
+- **Added** `TooltipContentProps` type export
+- **Fixed** Wrapped Tooltip context provider value in `useMemo` for performance
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/tree-view.md

@@ -1,65 +1,65 @@
-# TreeView / TreeItem
-
-- Import: @devalok/shilp-sutra/ui/tree-view
-- Server-safe: No
-- Category: ui
-
-## Props
-### TreeView
-    items: TreeNode[] (data-driven mode) — { id, label, icon?, disabled?, children? }
-    defaultExpanded: string[]
-    defaultSelected: string[]
-    multiSelect: boolean
-    checkboxes: boolean
-    onSelect: (ids: string[]) => void
-    onExpand: (ids: string[]) => void
-    children: ReactNode (declarative mode)
-
-### TreeItem
-    itemId: string (REQUIRED)
-    label: ReactNode
-    secondaryLabel: ReactNode
-    icon: ReactNode
-    actions: ReactNode
-    disabled: boolean
-    depth: number
-    children: ReactNode (nested TreeItems)
-
-## Hook
-    useTree({ defaultExpanded, defaultSelected, multiSelect, onSelect, onExpand })
-
-## Example (data-driven)
-```jsx
-<TreeView
-  items={[
-    { id: '1', label: 'Folder', children: [
-      { id: '1.1', label: 'File A' },
-      { id: '1.2', label: 'File B' },
-    ]},
-  ]}
-  defaultExpanded={['1']}
-  onSelect={(ids) => console.log(ids)}
-/>
-```
-
-## Example (declarative)
-```jsx
-<TreeView>
-  <TreeItem itemId="1" label="Folder">
-    <TreeItem itemId="1.1" label="File A" />
-  </TreeItem>
-</TreeView>
-```
-
-## Gotchas
-- Supports both data-driven (items prop) and declarative (children) modes
-
-## Changes
-### v0.4.2
-- **Added** TreeItem now accepts `className` prop
-
-### v0.3.0
-- **Added** Per-component export: `./ui/tree-view`
-
-### v0.1.0
-- **Added** Initial release
+# TreeView / TreeItem
+
+- Import: @devalok/shilp-sutra/ui/tree-view
+- Server-safe: No
+- Category: ui
+
+## Props
+### TreeView
+    items: TreeNode[] (data-driven mode) — { id, label, icon?, disabled?, children? }
+    defaultExpanded: string[]
+    defaultSelected: string[]
+    multiSelect: boolean
+    checkboxes: boolean
+    onSelect: (ids: string[]) => void
+    onExpand: (ids: string[]) => void
+    children: ReactNode (declarative mode)
+
+### TreeItem
+    itemId: string (REQUIRED)
+    label: ReactNode
+    secondaryLabel: ReactNode
+    icon: ReactNode
+    actions: ReactNode
+    disabled: boolean
+    depth: number
+    children: ReactNode (nested TreeItems)
+
+## Hook
+    useTree({ defaultExpanded, defaultSelected, multiSelect, onSelect, onExpand })
+
+## Example (data-driven)
+```jsx
+<TreeView
+  items={[
+    { id: '1', label: 'Folder', children: [
+      { id: '1.1', label: 'File A' },
+      { id: '1.2', label: 'File B' },
+    ]},
+  ]}
+  defaultExpanded={['1']}
+  onSelect={(ids) => console.log(ids)}
+/>
+```
+
+## Example (declarative)
+```jsx
+<TreeView>
+  <TreeItem itemId="1" label="Folder">
+    <TreeItem itemId="1.1" label="File A" />
+  </TreeItem>
+</TreeView>
+```
+
+## Gotchas
+- Supports both data-driven (items prop) and declarative (children) modes
+
+## Changes
+### v0.4.2
+- **Added** TreeItem now accepts `className` prop
+
+### v0.3.0
+- **Added** Per-component export: `./ui/tree-view`
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/visually-hidden.md

@@ -1,21 +1,21 @@
-# VisuallyHidden
-
-- Import: @devalok/shilp-sutra/ui/visually-hidden
-- Server-safe: Yes
-- Category: ui
-
-## Props
-    standard span attributes
-
-## Example
-```jsx
-<VisuallyHidden>Screen reader only text</VisuallyHidden>
-```
-
-## Gotchas
-- Content is visually hidden but accessible to screen readers
-- Useful for providing accessible labels without visual UI
-
-## Changes
-### v0.1.0
-- **Added** Initial release
+# VisuallyHidden
+
+- Import: @devalok/shilp-sutra/ui/visually-hidden
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    standard span attributes
+
+## Example
+```jsx
+<VisuallyHidden>Screen reader only text</VisuallyHidden>
+```
+
+## Gotchas
+- Content is visually hidden but accessible to screen readers
+- Useful for providing accessible labels without visual UI
+
+## Changes
+### v0.1.0
+- **Added** Initial release