@devalok/shilp-sutra 0.34.1 → 0.36.0

package/docs/components/ui/autocomplete.md

@@ -1,48 +1,48 @@
-# Autocomplete
-
-- Import: @devalok/shilp-sutra/ui/autocomplete
-- Server-safe: No
-- Category: ui
-
-## Props
-    options: AutocompleteOption[] (REQUIRED) — { value: string, label: string }
-    value: AutocompleteOption | null
-    onValueChange?: (option: AutocompleteOption) => void
-    placeholder: string
-    emptyText: string (default: "No options")
-    disabled: boolean
-    className: string
-    id: string
-
-## Defaults
-    emptyText="No options"
-
-## Example
-```jsx
-<Autocomplete
-  options={[{ value: 'mumbai', label: 'Mumbai' }]}
-  value={selectedCity}
-  onValueChange={setSelectedCity}
-  placeholder="Search cities..."
-/>
-```
-
-## Gotchas
-- Allows free-text input (no forced selection) — use Combobox for forced selection
-- value is an object { value, label }, NOT just a string
-
-## Changes
-### v0.18.0
-- **Fixed** Added `useEffect` to sync query when external value changes
-
-### v0.14.0
-- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes dropdown rendering behind Sheet/Dialog overlays
-
-### v0.3.0
-- **Changed** (BREAKING) `onChange` renamed to `onValueChange`
-
-### v0.1.1
-- **Fixed** `focus:ring` changed to `focus-visible:ring` — focus ring no longer shows on mouse click
-
-### v0.1.0
-- **Added** Initial release
+# Autocomplete
+
+- Import: @devalok/shilp-sutra/ui/autocomplete
+- Server-safe: No
+- Category: ui
+
+## Props
+    options: AutocompleteOption[] (REQUIRED) — { value: string, label: string }
+    value: AutocompleteOption | null
+    onValueChange?: (option: AutocompleteOption) => void
+    placeholder: string
+    emptyText: string (default: "No options")
+    disabled: boolean
+    className: string
+    id: string
+
+## Defaults
+    emptyText="No options"
+
+## Example
+```jsx
+<Autocomplete
+  options={[{ value: 'mumbai', label: 'Mumbai' }]}
+  value={selectedCity}
+  onValueChange={setSelectedCity}
+  placeholder="Search cities..."
+/>
+```
+
+## Gotchas
+- Allows free-text input (no forced selection) — use Combobox for forced selection
+- value is an object { value, label }, NOT just a string
+
+## Changes
+### v0.18.0
+- **Fixed** Added `useEffect` to sync query when external value changes
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes dropdown rendering behind Sheet/Dialog overlays
+
+### v0.3.0
+- **Changed** (BREAKING) `onChange` renamed to `onValueChange`
+
+### v0.1.1
+- **Fixed** `focus:ring` changed to `focus-visible:ring` — focus ring no longer shows on mouse click
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/avatar.md

@@ -1,56 +1,56 @@
-# Avatar
-
-- Import: @devalok/shilp-sutra/ui/avatar
-- Server-safe: No
-- Category: ui
-
-## Props
-    size: "xs" | "sm" | "md" | "lg" | "xl"
-    shape: "circle" | "square" | "rounded"
-    status: "online" | "offline" | "busy" | "away"
-    ring: "none" | "lead" | "admin" | "client" (default: "none") — Role ring with semantic colors
-    badge: number | "dot" | ReactNode — Badge overlay at top-right
-    loading: boolean (default: false) — Skeleton shimmer state
-
-## Compound Components
-    Avatar (root with size/shape/status/ring/badge/loading)
-      AvatarImage (src, alt)
-      AvatarFallback (children = initials text, colorSeed?: string)
-
-## AvatarFallback Props
-    colorSeed: string — Deterministic color seed for consistent background color across renders
-
-## Defaults
-    size="md", shape="circle", ring="none", loading=false
-
-## Example
-```jsx
-<Avatar size="lg" status="online" ring="lead" badge={3}>
-  <AvatarImage src={user.photoUrl} alt={user.name} />
-  <AvatarFallback colorSeed={user.id}>JD</AvatarFallback>
-</Avatar>
-```
-
-## Gotchas
-- Status dot renders with role="img" and aria-label (accessible, not decorative)
-- Dot size scales automatically with avatar size
-- AvatarFallback font size scales automatically with avatar size (via AvatarSizeContext)
-- Ring offset color matches the surface context — ensure it sits on the expected background
-- Badge is hidden when value is `0` (falsy); use `"dot"` for presence without a count
-- Online status dot pulses with a CSS animation
-
-## Changes
-### v0.22.3
-- **Fixed** AvatarFallback text now auto-scales with avatar size — xs gets `text-[9px]`, sm `text-ds-xs`, md `text-ds-sm`, lg `text-ds-md`, xl `text-ds-lg`
-
-### v0.22.0
-- **Fixed** Fallback always rendered `rounded-ds-full` regardless of `shape` prop. Now uses `AvatarShapeContext` to inherit the correct border-radius from `shape="square"` or `shape="rounded"`.
-
-### v0.21.0
-- **Added** `ring` prop with semantic role colors (`lead`, `admin`, `client`)
-- **Added** `badge` prop for numeric, dot, or custom ReactNode overlay at top-right
-- **Added** `loading` prop for skeleton shimmer placeholder state
-- **Added** `AvatarFallback.colorSeed` for deterministic fallback background colors
-
-### v0.1.0
-- **Added** Initial release with CVA size variants (xs-xl) and status indicator badge
+# Avatar
+
+- Import: @devalok/shilp-sutra/ui/avatar
+- Server-safe: No
+- Category: ui
+
+## Props
+    size: "xs" | "sm" | "md" | "lg" | "xl"
+    shape: "circle" | "square" | "rounded"
+    status: "online" | "offline" | "busy" | "away"
+    ring: "none" | "lead" | "admin" | "client" (default: "none") — Role ring with semantic colors
+    badge: number | "dot" | ReactNode — Badge overlay at top-right
+    loading: boolean (default: false) — Skeleton shimmer state
+
+## Compound Components
+    Avatar (root with size/shape/status/ring/badge/loading)
+      AvatarImage (src, alt)
+      AvatarFallback (children = initials text, colorSeed?: string)
+
+## AvatarFallback Props
+    colorSeed: string — Deterministic color seed for consistent background color across renders
+
+## Defaults
+    size="md", shape="circle", ring="none", loading=false
+
+## Example
+```jsx
+<Avatar size="lg" status="online" ring="lead" badge={3}>
+  <AvatarImage src={user.photoUrl} alt={user.name} />
+  <AvatarFallback colorSeed={user.id}>JD</AvatarFallback>
+</Avatar>
+```
+
+## Gotchas
+- Status dot renders with role="img" and aria-label (accessible, not decorative)
+- Dot size scales automatically with avatar size
+- AvatarFallback font size scales automatically with avatar size (via AvatarSizeContext)
+- Ring offset color matches the surface context — ensure it sits on the expected background
+- Badge is hidden when value is `0` (falsy); use `"dot"` for presence without a count
+- Online status dot pulses with a CSS animation
+
+## Changes
+### v0.22.3
+- **Fixed** AvatarFallback text now auto-scales with avatar size — xs gets `text-[9px]`, sm `text-ds-xs`, md `text-ds-sm`, lg `text-ds-md`, xl `text-ds-lg`
+
+### v0.22.0
+- **Fixed** Fallback always rendered `rounded-ds-full` regardless of `shape` prop. Now uses `AvatarShapeContext` to inherit the correct border-radius from `shape="square"` or `shape="rounded"`.
+
+### v0.21.0
+- **Added** `ring` prop with semantic role colors (`lead`, `admin`, `client`)
+- **Added** `badge` prop for numeric, dot, or custom ReactNode overlay at top-right
+- **Added** `loading` prop for skeleton shimmer placeholder state
+- **Added** `AvatarFallback.colorSeed` for deterministic fallback background colors
+
+### v0.1.0
+- **Added** Initial release with CVA size variants (xs-xl) and status indicator badge

package/docs/components/ui/badge.md

@@ -1,82 +1,83 @@
-# Badge
-
-- Import: @devalok/shilp-sutra/ui/badge
-- Server-safe: No
-- Category: ui
-
-## Props
-    variant: "subtle" | "solid" | "outline" | "soft"
-    color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" | "teal" | "amber" | "slate" | "indigo" | "cyan" | "orange" | "emerald" | "custom"
-    size: "xs" | "sm" | "md" | "lg"
-    startIcon: ReactElement | null
-    endIcon: ReactElement | null
-    dot: boolean (shows animated leading dot indicator)
-    onClick: () => void (makes badge interactive as button)
-    selected: boolean (toggle state — shows check icon when true)
-    disabled: boolean
-    onDismiss: () => void (shows dismiss X button)
-    maxWidth: number (enables truncation with title tooltip)
-    circle: boolean (square aspect-ratio, centered content)
-    asChild: boolean
-    children: ReactNode
-
-## Compound Components
-    Badge.Indicator — status indicator sub-component
-    Badge.Group — layout wrapper for badge collections
-
-## Defaults
-    variant="subtle", color="default", size="md"
-
-## Example
-```jsx
-<Badge variant="solid" color="success">Active</Badge>
-<Badge color="teal" onDismiss={() => removeFilter('teal')}>Teal team</Badge>
-<Badge onClick={() => toggle()} selected={isSelected}>Filterable</Badge>
-<Badge color="custom" style={{ '--badge-color': '#8b5cf6' }}>Custom</Badge>
-```
-
-## Gotchas
-- DO NOT use variant="destructive" — use variant="solid" color="error"
-- Badge is now interactive when `onClick` is provided (renders as `<button>`)
-- When both `onClick` and `onDismiss` are provided, renders as `div[role="button"]` to avoid nested buttons
-- Chip is deprecated — use Badge with `onClick` for interactive tags
-- `color="custom"` requires `--badge-color` CSS variable (and optionally `--badge-fg-color` for solid variant)
-
-## Changes
-### v0.31.0
-- **Added** `truncate` prop — enables ellipsis truncation without requiring maxWidth
-
-### v0.29.0
-- **Changed** (BREAKING) v2 rewrite — Badge is now a full interactive component
-- **Added** `soft` variant (tinted bg, no border — completes the 4-variant set: subtle/solid/outline/soft)
-- **Added** `custom` color with CSS variable `--badge-color` (and `--badge-fg-color` for solid)
-- **Added** Interactive mode: `onClick` makes Badge a clickable button, `selected` shows animated check icon
-- **Added** `disabled` prop with reduced opacity and pointer-events-none
-- **Added** `startIcon` / `endIcon` props (auto-sized per badge size)
-- **Added** `maxWidth` prop for truncation with title tooltip
-- **Added** `circle` prop for square aspect-ratio badges
-- **Added** `asChild` prop for Slot composition
-- **Added** `Badge.Indicator` and `Badge.Group` compound sub-components
-- **Deprecated** Chip component — use Badge with `onClick` instead
-- **Changed** Dot animation now uses Framer Motion spring entrance + continuous pulse
-
-### v0.18.0
-- **Changed** Pulse-ring animation migrated to Framer Motion
-- **Fixed** Accent color variants — `text-accent-9` changed to `text-accent-11`, `border-accent-9` changed to `border-accent-7`
-- **Changed** OKLCH color token migration
-
-### v0.8.0
-- **Fixed** `text-[10px]` changed to `text-ds-xs` for token consistency
-
-### v0.4.2
-- **Fixed** `Omit<HTMLAttributes, 'color'>` resolves TS2320 conflict with CVA color prop
-
-### v0.3.1
-- **Fixed** Dismiss button added 24px touch target
-
-### v0.3.0
-- **Changed** (BREAKING) Single `variant` axis split into `variant` (subtle/solid/outline) + `color` (default/info/success/error/...)
-- **Fixed** Solid variant phantom token `text-on-interactive` changed to `text-on-color`
-
-### v0.1.0
-- **Added** Initial release
+# Badge
+
+- Import: @devalok/shilp-sutra/ui/badge
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: "subtle" | "solid" | "outline" | "soft"
+    color: "default" | "accent" | "error" | "success" | "warning" | "info" | "neutral" | "teal" | "amber" | "slate" | "indigo" | "cyan" | "orange" | "emerald" | "custom"
+    size: "xs" | "sm" | "md" | "lg"
+    startIcon: ReactElement | null
+    endIcon: ReactElement | null
+    dot: boolean (shows animated leading dot indicator)
+    onClick: () => void (makes badge interactive as button)
+    selected: boolean (toggle state — shows check icon when true)
+    disabled: boolean
+    onDismiss: () => void (shows dismiss X button)
+    maxWidth: number (enables truncation with title tooltip)
+    truncate: boolean (ellipsis overflow — pair with a width/maxWidth; adds title tooltip)
+    circle: boolean (square aspect-ratio, centered content)
+    asChild: boolean
+    children: ReactNode
+
+## Compound Components
+    Badge.Indicator — status indicator sub-component
+    Badge.Group — layout wrapper for badge collections
+
+## Defaults
+    variant="subtle", color="default", size="md"
+
+## Example
+```jsx
+<Badge variant="solid" color="success">Active</Badge>
+<Badge color="teal" onDismiss={() => removeFilter('teal')}>Teal team</Badge>
+<Badge onClick={() => toggle()} selected={isSelected}>Filterable</Badge>
+<Badge color="custom" style={{ '--badge-color': '#8b5cf6' }}>Custom</Badge>
+```
+
+## Gotchas
+- DO NOT use variant="destructive" — use variant="solid" color="error"
+- Badge is now interactive when `onClick` is provided (renders as `<button>`)
+- When both `onClick` and `onDismiss` are provided, renders as `div[role="button"]` to avoid nested buttons
+- Chip is deprecated — use Badge with `onClick` for interactive tags
+- `color="custom"` requires `--badge-color` CSS variable (and optionally `--badge-fg-color` for solid variant)
+
+## Changes
+### v0.31.0
+- **Added** `truncate` prop — enables ellipsis truncation without requiring maxWidth
+
+### v0.29.0
+- **Changed** (BREAKING) v2 rewrite — Badge is now a full interactive component
+- **Added** `soft` variant (tinted bg, no border — completes the 4-variant set: subtle/solid/outline/soft)
+- **Added** `custom` color with CSS variable `--badge-color` (and `--badge-fg-color` for solid)
+- **Added** Interactive mode: `onClick` makes Badge a clickable button, `selected` shows animated check icon
+- **Added** `disabled` prop with reduced opacity and pointer-events-none
+- **Added** `startIcon` / `endIcon` props (auto-sized per badge size)
+- **Added** `maxWidth` prop for truncation with title tooltip
+- **Added** `circle` prop for square aspect-ratio badges
+- **Added** `asChild` prop for Slot composition
+- **Added** `Badge.Indicator` and `Badge.Group` compound sub-components
+- **Deprecated** Chip component — use Badge with `onClick` instead
+- **Changed** Dot animation now uses Framer Motion spring entrance + continuous pulse
+
+### v0.18.0
+- **Changed** Pulse-ring animation migrated to Framer Motion
+- **Fixed** Accent color variants — `text-accent-9` changed to `text-accent-11`, `border-accent-9` changed to `border-accent-7`
+- **Changed** OKLCH color token migration
+
+### v0.8.0
+- **Fixed** `text-[10px]` changed to `text-ds-xs` for token consistency
+
+### v0.4.2
+- **Fixed** `Omit<HTMLAttributes, 'color'>` resolves TS2320 conflict with CVA color prop
+
+### v0.3.1
+- **Fixed** Dismiss button added 24px touch target
+
+### v0.3.0
+- **Changed** (BREAKING) Single `variant` axis split into `variant` (subtle/solid/outline) + `color` (default/info/success/error/...)
+- **Fixed** Solid variant phantom token `text-on-interactive` changed to `text-on-color`
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/banner.md

@@ -1,42 +1,42 @@
-# Banner
-
-- Import: @devalok/shilp-sutra/ui/banner
-- Server-safe: No
-- Category: ui
-
-## Props
-    color: "info" | "success" | "warning" | "error" | "neutral"
-    actions: ReactNode (optional action slot for one or more buttons; wraps on narrow viewports)
-    action: ReactNode (DEPRECATED — use `actions` instead)
-    onDismiss: () => void (optional, shows X button)
-    children: ReactNode (message text)
-
-## Defaults
-    color="info"
-
-## Example
-```jsx
-<Banner color="warning" onDismiss={() => dismiss()}>
-  Scheduled maintenance on Sunday.
-</Banner>
-```
-
-## Gotchas
-- Banner is full-width (spans container). Alert is inline.
-- Renders role="alert" automatically
-- `onDismiss` fires after the exit animation completes, not immediately on dismiss button click
-
-## Changes
-### v0.20.0
-- **Added** `actions` prop (plural) for multiple action buttons with mobile-friendly flex-wrap
-- **Deprecated** `action` prop — use `actions` instead (both still work; `actions` takes priority)
-- **Changed** Root layout uses `flex-wrap` and children wrapper uses `min-w-0` for better text truncation
-
-### v0.3.1
-- **Fixed** BannerProps uses `Omit<HTMLAttributes, 'color'>` to resolve TypeScript conflict with CVA `color` variant
-
-### v0.3.0
-- **Changed** (BREAKING) `variant` prop renamed to `color` for semantic intent
-
-### v0.1.0
-- **Added** Initial release
+# Banner
+
+- Import: @devalok/shilp-sutra/ui/banner
+- Server-safe: No
+- Category: ui
+
+## Props
+    color: "info" | "success" | "warning" | "error" | "neutral"
+    actions: ReactNode (optional action slot for one or more buttons; wraps on narrow viewports)
+    action: ReactNode (DEPRECATED — use `actions` instead)
+    onDismiss: () => void (optional, shows X button)
+    children: ReactNode (message text)
+
+## Defaults
+    color="info"
+
+## Example
+```jsx
+<Banner color="warning" onDismiss={() => dismiss()}>
+  Scheduled maintenance on Sunday.
+</Banner>
+```
+
+## Gotchas
+- Banner is full-width (spans container). Alert is inline.
+- Renders role="alert" automatically
+- `onDismiss` fires after the exit animation completes, not immediately on dismiss button click
+
+## Changes
+### v0.20.0
+- **Added** `actions` prop (plural) for multiple action buttons with mobile-friendly flex-wrap
+- **Deprecated** `action` prop — use `actions` instead (both still work; `actions` takes priority)
+- **Changed** Root layout uses `flex-wrap` and children wrapper uses `min-w-0` for better text truncation
+
+### v0.3.1
+- **Fixed** BannerProps uses `Omit<HTMLAttributes, 'color'>` to resolve TypeScript conflict with CVA `color` variant
+
+### v0.3.0
+- **Changed** (BREAKING) `variant` prop renamed to `color` for semantic intent
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/breadcrumb.md

@@ -1,37 +1,37 @@
-# Breadcrumb
-
-- Import: @devalok/shilp-sutra/ui/breadcrumb
-- Server-safe: No
-- Category: ui
-
-## Compound Components
-    Breadcrumb (root nav)
-      BreadcrumbList (ol)
-        BreadcrumbItem (li)
-          BreadcrumbLink (for clickable items) | BreadcrumbPage (for current page)
-        BreadcrumbSeparator (auto-rendered or custom)
-        BreadcrumbEllipsis (for collapsed items)
-
-## Defaults
-    none
-
-## Example
-```jsx
-<Breadcrumb>
-  <BreadcrumbList>
-    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
-    <BreadcrumbSeparator />
-    <BreadcrumbItem><BreadcrumbPage>Settings</BreadcrumbPage></BreadcrumbItem>
-  </BreadcrumbList>
-</Breadcrumb>
-```
-
-## Gotchas
-- Use BreadcrumbPage for the current (non-clickable) page, BreadcrumbLink for navigable items
-
-## Changes
-### v0.18.0
-- **Added** `BreadcrumbProps`, `BreadcrumbLinkProps` type exports
-
-### v0.1.0
-- **Added** Initial release
+# Breadcrumb
+
+- Import: @devalok/shilp-sutra/ui/breadcrumb
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    Breadcrumb (root nav)
+      BreadcrumbList (ol)
+        BreadcrumbItem (li)
+          BreadcrumbLink (for clickable items) | BreadcrumbPage (for current page)
+        BreadcrumbSeparator (auto-rendered or custom)
+        BreadcrumbEllipsis (for collapsed items)
+
+## Defaults
+    none
+
+## Example
+```jsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbPage>Settings</BreadcrumbPage></BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+## Gotchas
+- Use BreadcrumbPage for the current (non-clickable) page, BreadcrumbLink for navigable items
+
+## Changes
+### v0.18.0
+- **Added** `BreadcrumbProps`, `BreadcrumbLinkProps` type exports
+
+### v0.1.0
+- **Added** Initial release

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

@@ -1,41 +1,41 @@
-# ButtonGroup
-
-- Import: @devalok/shilp-sutra/ui/button-group
-- Server-safe: No
-- Category: ui
-
-## Props
-    variant: ButtonProps['variant'] (propagated to children)
-    color: ButtonProps['color'] (propagated to children)
-    size: ButtonProps['size'] (propagated to children)
-    orientation: "horizontal" | "vertical" (default: "horizontal")
-
-## Defaults
-    orientation="horizontal"
-
-## Example
-```jsx
-<ButtonGroup variant="outline" size="sm">
-  <Button>Bold</Button>
-  <Button>Italic</Button>
-</ButtonGroup>
-```
-
-## Gotchas
-- Children can override variant/size individually
-
-## Changes
-### v0.33.0
-- **Rebuilt** with compound component pattern — Button reads position from ButtonGroup context and applies border-radius inline
-- **Added** `disabled` prop (propagates to all children via context)
-- **Added** `attached` prop (default true; false = spaced with gap)
-- **Added** `fullWidth` prop (stretch to fill container)
-- **Added** Tonal divider elements between buttons for solid/soft/ghost variants
-- **Added** Focus z-index isolation (focused button rises above siblings)
-- **Fixed** Border-radius not working with custom `rounded-ds-*` design tokens
-
-### v0.4.2
-- **Fixed** `Omit<HTMLAttributes, 'color'>` resolves TS2320 conflict with CVA color prop
-
-### v0.1.0
-- **Added** Initial release
+# ButtonGroup
+
+- Import: @devalok/shilp-sutra/ui/button-group
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: ButtonProps['variant'] (propagated to children)
+    color: ButtonProps['color'] (propagated to children)
+    size: ButtonProps['size'] (propagated to children)
+    orientation: "horizontal" | "vertical" (default: "horizontal")
+
+## Defaults
+    orientation="horizontal"
+
+## Example
+```jsx
+<ButtonGroup variant="outline" size="sm">
+  <Button>Bold</Button>
+  <Button>Italic</Button>
+</ButtonGroup>
+```
+
+## Gotchas
+- Children can override variant/size individually
+
+## Changes
+### v0.33.0
+- **Rebuilt** with compound component pattern — Button reads position from ButtonGroup context and applies border-radius inline
+- **Added** `disabled` prop (propagates to all children via context)
+- **Added** `attached` prop (default true; false = spaced with gap)
+- **Added** `fullWidth` prop (stretch to fill container)
+- **Added** Tonal divider elements between buttons for solid/soft/ghost variants
+- **Added** Focus z-index isolation (focused button rises above siblings)
+- **Fixed** Border-radius not working with custom `rounded-ds-*` design tokens
+
+### v0.4.2
+- **Fixed** `Omit<HTMLAttributes, 'color'>` resolves TS2320 conflict with CVA color prop
+
+### v0.1.0
+- **Added** Initial release