@devalok/shilp-sutra 0.34.0 → 0.36.0

package/docs/components/ui/skeleton.md

@@ -1,77 +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
+# 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

@@ -1,29 +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)
+# 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

@@ -1,54 +1,54 @@
-# 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)
-    className: string
-
-## 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.29.0
-- **Changed** `bare` variant spinning state now uses `currentColor` instead of `var(--color-accent-9)` — inherits text color from parent for seamless embedding in buttons/toolbars
-
-### 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
+# 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)
+    className: string
+
+## 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.29.0
+- **Changed** `bare` variant spinning state now uses `currentColor` instead of `var(--color-accent-9)` — inherits text color from parent for seamless embedding in buttons/toolbars
+
+### 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

@@ -1,39 +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
+# 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

@@ -1,61 +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
+# 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/status-dot.md

@@ -1,26 +1,26 @@
-# StatusDot
-
-- Import: @devalok/shilp-sutra/ui/status-dot
-- Server-safe: Yes
-- Category: ui
-
-## Props
-    status: "healthy" | "warning" | "critical" | "neutral" | "inactive"
-    size: "sm" | "md" | "lg"
-    pulse: boolean (ping animation; defaults to true for "healthy", false for others)
-    label: string (inline text rendered after the dot)
-    labelClassName: string (extra classes on the label span)
-
-## Defaults
-    size="md", pulse={status === "healthy"}
-
-## Example
-```jsx
-<StatusDot status="healthy" />
-<StatusDot status="critical" label="Service down" pulse />
-<StatusDot status="warning" size="lg" label="Elevated load" />
-```
-
-## Gotchas
-- The `pulse` prop auto-enables for "healthy" status — pass `pulse={false}` to suppress
-- Status type is exported as `StatusDotStatus` if you need it in consumer code
+# StatusDot
+
+- Import: @devalok/shilp-sutra/ui/status-dot
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    status: "healthy" | "warning" | "critical" | "neutral" | "inactive"
+    size: "sm" | "md" | "lg"
+    pulse: boolean (ping animation; defaults to true for "healthy", false for others)
+    label: string (inline text rendered after the dot)
+    labelClassName: string (extra classes on the label span)
+
+## Defaults
+    size="md", pulse={status === "healthy"}
+
+## Example
+```jsx
+<StatusDot status="healthy" />
+<StatusDot status="critical" label="Service down" pulse />
+<StatusDot status="warning" size="lg" label="Elevated load" />
+```
+
+## Gotchas
+- The `pulse` prop auto-enables for "healthy" status — pass `pulse={false}` to suppress
+- Status type is exported as `StatusDotStatus` if you need it in consumer code