@devalok/shilp-sutra 0.18.1 → 0.18.2

package/docs/components/ui/skeleton.md

@@ -0,0 +1,77 @@
+# Skeleton
+
+- Import: @devalok/shilp-sutra/ui/skeleton
+- Server-safe: Yes
+- Category: ui
+
+## Props
+### Skeleton (base)
+    variant: "rectangle" | "circle" | "text"
+    animation: "pulse" | "shimmer" | "none"
+
+### SkeletonAvatar
+    size: "sm" | "md" | "lg" | "xl"
+    animation: "pulse" | "shimmer" | "none"
+
+### SkeletonText
+    lines: number (default: 3)
+    lastLineWidth: "full" | "three-quarter" | "half" (default: "three-quarter")
+    spacing: "sm" | "md" (default: "md")
+    animation: "pulse" | "shimmer" | "none"
+
+### SkeletonButton
+    size: "sm" | "md" | "lg"
+    width: "auto" | "full" | "icon"
+    animation: "pulse" | "shimmer" | "none"
+
+### SkeletonInput
+    size: "sm" | "md" | "lg"
+    animation: "pulse" | "shimmer" | "none"
+
+### SkeletonChart
+    bars: number (default: 7)
+    height: string (default: "h-40")
+    animation: "pulse" | "shimmer" | "none"
+
+### SkeletonImage
+    width: string (default: "w-full")
+    height: string (default: "h-40")
+    animation: "pulse" | "shimmer" | "none"
+
+### SkeletonGroup
+    label: string (default: "Loading") — accessible label for the loading state
+
+## Defaults
+    Skeleton: variant="rectangle", animation="pulse"
+    SkeletonAvatar: size="md", animation="pulse"
+    SkeletonText: lines=3, lastLineWidth="three-quarter", spacing="md", animation="pulse"
+    SkeletonButton: size="md", width="auto", animation="pulse"
+    SkeletonInput: size="md", animation="pulse"
+    SkeletonChart: bars=7, height="h-40", animation="pulse"
+    SkeletonImage: width="w-full", height="h-40", animation="pulse"
+    SkeletonGroup: label="Loading"
+
+## Example
+```jsx
+<Skeleton variant="text" className="w-3/4" />
+<Skeleton variant="circle" className="h-12 w-12" />
+<Skeleton variant="rectangle" animation="shimmer" className="h-48 w-full" />
+
+<SkeletonGroup label="Loading user profile">
+  <SkeletonAvatar size="lg" />
+  <SkeletonText lines={2} />
+  <SkeletonButton />
+</SkeletonGroup>
+
+<SkeletonChart bars={5} height="h-32" />
+<SkeletonImage height="h-64" />
+```
+
+## Gotchas
+- shimmer respects prefers-reduced-motion
+- SkeletonGroup adds role="status" and aria-busy="true" — wrap multiple skeletons for a11y
+- All sub-components accept className for custom sizing
+
+## Changes
+### v0.1.0
+- **Added** Initial release with `shape` variants (text, circular, rectangular) and shimmer animation

package/docs/components/ui/slider.md

@@ -0,0 +1,29 @@
+# Slider
+
+- Import: @devalok/shilp-sutra/ui/slider
+- Server-safe: No
+- Category: ui
+
+## Props
+    Standard Radix Slider props (value, onValueChange, defaultValue, min, max, step, aria-label)
+
+## Example
+```jsx
+<Slider defaultValue={[50]} max={100} step={1} aria-label="Volume" />
+<Slider defaultValue={[25, 75]} max={100} step={1} /> {/* range slider */}
+```
+
+## Gotchas
+- value is number[] (array), not a single number
+- Multi-thumb: Pass array `defaultValue={[25, 75]}` for range sliders — renders one thumb per value
+
+## Changes
+### v0.18.0
+- **Fixed** Multi-thumb support added
+
+### v0.3.0
+- **Added** `SliderProps` type export
+
+### v0.1.0
+- **Added** Initial release
+- **Fixed** `aria-label` now forwarded to thumb element (was only on root container)

package/docs/components/ui/spinner.md

@@ -0,0 +1,50 @@
+# Spinner
+
+- Import: @devalok/shilp-sutra/ui/spinner
+- Server-safe: No
+- Category: ui
+
+## Props
+    size: "sm" | "md" | "lg"
+    state: "spinning" | "success" | "error"
+    variant: "filled" | "bare"
+    delay: number (ms — render delay to avoid flicker on fast operations)
+    onComplete: () => void (callback after success/error state transition)
+
+## Defaults
+    size: "md"
+    state: "spinning"
+    variant: "filled"
+
+## Example
+```jsx
+<Spinner size="lg" />
+<Spinner state="success" /> {/* green checkmark */}
+<Spinner variant="bare" /> {/* uses currentColor, for embedding in buttons */}
+```
+
+## Gotchas
+- Renders role="status" with sr-only "Loading..." text — no need for aria-label
+- Button has built-in loading prop — prefer that over manual Spinner composition
+- `bare` variant inherits text color — useful inside buttons and toolbars
+- `delay` prevents flicker: spinner only appears after delay ms (good for fast API calls)
+- No longer server-safe as of v0.18.0 (uses Framer Motion)
+
+## Changes
+### v0.18.0
+- **Changed** (BREAKING) Complete rewrite with Framer Motion arc animation and state transitions
+- **Added** `state` prop: 'spinning' | 'success' | 'error'
+- **Added** `variant` prop: 'filled' | 'bare'
+- **Added** `delay` prop for flicker prevention
+- **Added** `onComplete` callback for state transitions
+- **Changed** No longer server-safe (Framer Motion dependency)
+- **Fixed** Fade out track circle in bare mode, use larger icons for bare variant
+
+### v0.3.0
+- **Fixed** Animations respect `prefers-reduced-motion`
+
+### v0.2.0
+- **Added** Identified as server-safe (no longer true as of v0.18.0)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/stack.md

@@ -0,0 +1,39 @@
+# Stack
+
+- Import: @devalok/shilp-sutra/ui/stack
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    direction: "vertical" | "horizontal" | "row" | "column"
+    gap: SpacingToken | number — tokens: "ds-01".."ds-13", or numbers 0-13
+    align: "start" | "center" | "end" | "stretch" | "baseline"
+    justify: "start" | "center" | "end" | "between" | "around" | "evenly"
+    wrap: boolean
+    as: ElementType (default: "div")
+
+## Defaults
+    direction: "vertical"
+
+## Example
+```jsx
+<Stack direction="horizontal" gap="ds-04" align="center">
+  <Avatar size="sm" />
+  <Text variant="body-md">User Name</Text>
+</Stack>
+```
+
+## Gotchas
+- "row" and "column" are aliases for "horizontal" and "vertical"
+- gap accepts both token strings and numeric values
+
+## Changes
+### v0.2.0
+- **Added** `direction` prop now accepts `"row"` / `"column"` as aliases for `"horizontal"` / `"vertical"`
+- **Added** `gap` prop now accepts numeric values (e.g., `gap={4}` -> `gap-ds-04`) in addition to token strings
+
+### v0.1.1
+- **Fixed** Replaced dynamic `gap-${N}` with static lookup map (Tailwind JIT safety)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/stat-card.md

@@ -0,0 +1,61 @@
+# StatCard
+
+- Import: @devalok/shilp-sutra/ui/stat-card
+- Server-safe: No
+- Category: ui
+
+## Props
+    label: string (heading text)
+    title: string (alias for label)
+    value: string | number (REQUIRED)
+    prefix: string (before value, e.g. "$")
+    suffix: string (after value, e.g. "users")
+    delta: { value: string, direction: "up" | "down" | "neutral" }
+    icon: ReactNode | ComponentType<{ className?: string }>
+    loading: boolean (renders skeleton)
+    comparisonLabel: string (shown after delta, e.g. "vs last month")
+    secondaryLabel: string (below main value, e.g. "of $50,000 target")
+    progress: number (0-100, renders thin progress bar below value)
+    accent: "default" | "success" | "warning" | "error" | "info" (left border color)
+    sparkline: number[] (renders mini SVG line chart)
+    onClick: () => void (makes card clickable with hover state)
+    href: string (makes card a link via LinkContext)
+    footer: ReactNode (below card body, e.g. "View details →")
+
+## Defaults
+    none (all props are optional except value)
+
+## Example
+```jsx
+<StatCard
+  label="Revenue"
+  value="$48,200"
+  prefix="$"
+  delta={{ value: "+12%", direction: "up" }}
+  comparisonLabel="vs last month"
+  icon={<IconCurrencyDollar />}
+  accent="success"
+/>
+
+<StatCard
+  label="Storage"
+  value="4.2 GB"
+  secondaryLabel="of 10 GB"
+  progress={42}
+  sparkline={[10, 25, 18, 30, 42]}
+  footer={<a href="/storage">Manage storage →</a>}
+/>
+```
+
+## Gotchas
+- delta.direction "up" = green, "down" = red, "neutral" = grey
+- `label` and `title` are aliases — use either, not both
+- `onClick` and `href` are mutually exclusive — href takes precedence
+- `sparkline` needs at least 2 data points to render
+
+## Changes
+### v0.2.0
+- **Added** `icon` prop now accepts `React.ComponentType` (e.g., `icon={IconBolt}`) in addition to `ReactNode`
+
+### v0.1.0
+- **Added** Initial release

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