@devalok/shilp-sutra 0.18.0 → 0.18.2

package/docs/components/ui/stepper.md

@@ -0,0 +1,49 @@
+# Stepper / Step
+
+- Import: @devalok/shilp-sutra/ui/stepper
+- Server-safe: No
+- Category: ui
+
+## Props
+### Stepper
+    activeStep: number (REQUIRED, 0-indexed)
+    orientation: "horizontal" | "vertical"
+    children: <Step> elements
+
+### Step
+    label: string (REQUIRED)
+    description: string
+    icon: ReactNode (overrides default number/checkmark)
+
+## Defaults
+    orientation: "horizontal"
+
+### StepperContent
+    activeStep: number (REQUIRED, 0-indexed — matches Stepper's activeStep)
+    children: ReactNode (one child per step, only the active one is visible)
+    className: string
+
+## Compound Components
+    Stepper (root)
+      Step (label, description, icon)
+    StepperContent (content panel, animates active step)
+
+## Example
+```jsx
+<Stepper activeStep={1}>
+  <Step label="Account" description="Create credentials" />
+  <Step label="Profile" description="Add details" />
+  <Step label="Review" />
+</Stepper>
+```
+
+## Gotchas
+- Steps before activeStep are "completed", at activeStep is "active", after is "pending"
+
+## Changes
+### v0.18.0
+- **Fixed** `bg-interactive` changed to `bg-accent-9` (OKLCH migration)
+- **Fixed** Wrapped Stepper context provider value in `useMemo` for performance
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/switch.md

@@ -0,0 +1,34 @@
+# Switch
+
+- Import: @devalok/shilp-sutra/ui/switch
+- Server-safe: No
+- Category: ui
+
+## Props
+    checked: boolean
+    onCheckedChange: (checked: boolean) => void
+    error: boolean (shows red border/bg)
+    disabled: boolean
+
+## Example
+```jsx
+<Switch checked={enabled} onCheckedChange={setEnabled} />
+```
+
+## Gotchas
+- Use error prop for validation states (matches Checkbox API)
+
+## Changes
+### v0.18.0
+- **Changed** Migrated to Framer Motion spring thumb animation
+- **Fixed** Added visible border on unchecked state (`border-surface-border-strong`) — was borderless, making unchecked state hard to see
+
+### v0.4.2
+- **Fixed** `React.ComponentRef` changed to `React.ElementRef` for consistency
+
+### v0.3.0
+- **Added** `SwitchProps` type export
+- **Added** `error` prop (matches Checkbox API)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/table.md

@@ -0,0 +1,47 @@
+# Table
+
+- Import: @devalok/shilp-sutra/ui/table
+- Server-safe: Yes
+- Category: ui
+
+## Compound Components
+    Table (root <table>)
+      TableHeader (<thead>)
+        TableRow (<tr>)
+          TableHead (<th>)
+      TableBody (<tbody>)
+        TableRow (<tr>)
+          TableCell (<td>)
+      TableFooter (<tfoot>)
+      TableCaption (<caption>)
+
+## Example
+```jsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>Project Alpha</TableCell>
+      <TableCell><Badge color="success">Active</Badge></TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Gotchas
+- Table headers automatically have scope="col" for screen reader navigation
+
+## Changes
+### v0.18.0
+- **Added** `TableProps`, `TableRowProps`, `TableCellProps` type exports
+
+### v0.17.0
+- **Fixed** TableCell: Added `px-ds-03` horizontal padding — was `px-0`, causing content to hug container edges
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/tabs.md

@@ -0,0 +1,56 @@
+# Tabs
+
+- Import: @devalok/shilp-sutra/ui/tabs
+- Server-safe: No
+- Category: ui
+
+## Props
+### Tabs (root)
+    defaultValue: string
+    value: string
+    onValueChange: (value: string) => void
+
+### TabsList
+    variant: "line" | "contained"
+
+### TabsTrigger
+    value: string (REQUIRED)
+    variant: (inherits from TabsList)
+
+### TabsContent
+    value: string (REQUIRED)
+
+## Compound Components
+    Tabs (root)
+      TabsList (variant)
+        TabsTrigger (value)
+      TabsContent (value)
+
+## Defaults
+    TabsList variant: "line"
+
+## Example
+```jsx
+<Tabs defaultValue="overview">
+  <TabsList variant="contained">
+    <TabsTrigger value="overview">Overview</TabsTrigger>
+    <TabsTrigger value="activity">Activity</TabsTrigger>
+  </TabsList>
+  <TabsContent value="overview">Overview content</TabsContent>
+  <TabsContent value="activity">Activity content</TabsContent>
+</Tabs>
+```
+
+## Gotchas
+- variant goes on TabsList, NOT on individual TabsTrigger (propagates via context)
+- DO NOT put variant on TabsTrigger — it inherits from TabsList
+
+## Changes
+### v0.18.0
+- **Fixed** Wrapped TabsList context provider value in `useMemo` for performance
+
+### v0.14.0
+- **Changed** TabsTrigger: Added `gap-ds-02` (4px) between icon and label for better spacing
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/text.md

@@ -0,0 +1,37 @@
+# Text
+
+- Import: @devalok/shilp-sutra/ui/text
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    variant: TextVariant
+    as: ElementType (override the auto-selected HTML element)
+
+## Types
+    TextVariant = 'heading-2xl' | 'heading-xl' | 'heading-lg' | 'heading-md' | 'heading-sm' | 'heading-xs' | 'body-lg' | 'body-md' | 'body-sm' | 'body-xs' | 'label-lg' | 'label-md' | 'label-sm' | 'label-xs' | 'caption' | 'overline'
+
+## Defaults
+    variant: "body-md"
+
+## Default Element Mapping
+    heading-2xl -> h1, heading-xl -> h2, heading-lg -> h3, heading-md -> h4, heading-sm -> h5, heading-xs -> h6
+    body-* -> p, label-* -> span, caption -> span, overline -> span
+
+## Example
+```jsx
+<Text variant="heading-2xl">Page Title</Text>
+<Text variant="body-sm" as="span">Inline text</Text>
+<Text variant="label-sm" className="text-text-secondary">SECTION LABEL</Text>
+```
+
+## Gotchas
+- label-* and overline variants are automatically uppercase
+- Use "as" prop to override the HTML element when needed
+
+## Changes
+### v0.2.0
+- **Fixed** `as` prop widened to accept any `React.ElementType` — `<Text as="h1">` no longer causes TypeScript errors
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/textarea.md

@@ -0,0 +1,39 @@
+# Textarea
+
+- Import: @devalok/shilp-sutra/ui/textarea
+- Server-safe: No
+- Category: ui
+
+## Props
+    size: "sm" | "md" | "lg"
+    state: "default" | "error" | "warning" | "success"
+    (plus standard textarea attributes except native "size")
+
+## Defaults
+    size: "md"
+
+## Example
+```jsx
+<Textarea size="lg" state="error" placeholder="Describe the issue..." />
+```
+
+## Gotchas
+- state="error" sets aria-invalid automatically; all sizes are vertically resizable
+- Inside FormField: auto-inherits state, aria-describedby, aria-required from context (explicit props override)
+
+## Changes
+### v0.15.0
+- **Changed** `lg` size font changed from `text-ds-lg` (18px) to `text-ds-md` (14px) — all input sizes now use 14px for consistency
+- **Changed** `md` size font standardized to `text-ds-md` (14px)
+
+### v0.8.0
+- **Fixed** Now consumes FormField context automatically (`aria-describedby`, `aria-invalid`, `aria-required`)
+
+### v0.4.2
+- **Added** `textareaVariants` export
+
+### v0.1.1
+- **Fixed** Added `aria-invalid` for error state (matching Input pattern)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/toast.md

@@ -0,0 +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`)

package/docs/components/ui/toaster.md

@@ -0,0 +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

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

@@ -0,0 +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

package/docs/components/ui/toggle.md

@@ -0,0 +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

package/docs/components/ui/tooltip.md

@@ -0,0 +1,33 @@
+# 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.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

@@ -0,0 +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

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

@@ -0,0 +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