@devalok/shilp-sutra 0.18.1 → 0.18.2

package/docs/components/ui/accordion.md

@@ -0,0 +1,48 @@
+# Accordion
+
+- Import: @devalok/shilp-sutra/ui/accordion
+- Server-safe: No
+- Category: ui
+
+## Props
+    type: "single" | "multiple" (REQUIRED)
+    defaultValue: string (single) | string[] (multiple)
+    value: string | string[] (controlled)
+    onValueChange: (value) => void
+    collapsible: boolean (only valid when type="single")
+
+## Compound Components
+    Accordion (root)
+      AccordionItem (value: string, REQUIRED)
+        AccordionTrigger (clickable header, chevron auto-renders)
+        AccordionContent (collapsible body)
+
+## Defaults
+    none (type is required)
+
+## Example
+```jsx
+<Accordion type="single" defaultValue="item-1" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Question?</AccordionTrigger>
+    <AccordionContent>Answer.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Gotchas
+- type is REQUIRED — omitting it causes runtime error
+- collapsible only works with type="single"
+
+## Changes
+### v0.18.0
+- **Changed** Accordion content fade animation migrated to Framer Motion (height animation still uses CSS keyframes)
+
+### v0.13.0
+- **Added** `accordion-down` and `accordion-up` keyframes added to Tailwind preset using Radix CSS custom properties
+
+### v0.4.2
+- **Added** `AccordionItemProps`, `AccordionTriggerProps`, `AccordionContentProps` type exports
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/alert-dialog.md

@@ -0,0 +1,58 @@
+# AlertDialog
+
+- Import: @devalok/shilp-sutra/ui/alert-dialog
+- Server-safe: No
+- Category: ui
+
+## Props
+    open: boolean (controlled)
+    onOpenChange: (open: boolean) => void
+    defaultOpen: boolean
+
+## Compound Components
+    AlertDialog (root)
+      AlertDialogTrigger
+      AlertDialogContent
+        AlertDialogHeader
+          AlertDialogTitle
+          AlertDialogDescription
+        AlertDialogFooter
+          AlertDialogCancel
+          AlertDialogAction
+
+## Defaults
+    none
+
+## Example
+```jsx
+<AlertDialog>
+  <AlertDialogTrigger asChild>
+    <Button color="error">Delete</Button>
+  </AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Gotchas
+- AlertDialogAction does NOT have color="error" styling — add it yourself via className or wrap a Button
+
+## Changes
+### v0.18.0
+- **Changed** Overlay animations migrated to Framer Motion (physics-based springs)
+- **Added** `AlertDialogContentProps`, `AlertDialogActionProps`, `AlertDialogCancelProps` type exports
+- **Fixed** Context provider value wrapped in `useMemo` for performance
+
+### v0.4.2
+- **Fixed** AlertDialogHeader/Footer now wrapped in `React.forwardRef` (matches Dialog/Sheet pattern)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/alert.md

@@ -0,0 +1,43 @@
+# Alert
+
+- Import: @devalok/shilp-sutra/ui/alert
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: "subtle" | "filled" | "outline"
+    color: "info" | "success" | "warning" | "error" | "neutral"
+    title: string (optional)
+    onDismiss: () => void (optional, shows X button when provided)
+    children: ReactNode (body text)
+
+## Defaults
+    variant="subtle", color="info"
+
+## Example
+```jsx
+<Alert color="error" title="Save failed" onDismiss={() => setError(null)}>
+  Your changes could not be saved.
+</Alert>
+```
+
+## Gotchas
+- NOT a compound component — use title prop, NOT <AlertTitle>
+- DO NOT use variant="destructive" — use color="error"
+- Renders role="alert" automatically
+- Icon is auto-selected by color (info=circle, success=check, warning=triangle, error=alert)
+
+## Changes
+### v0.18.0
+- **Changed** Exit animation migrated to Framer Motion
+- **Fixed** `onDismiss` JSDoc documenting it fires after exit animation completes
+- **Changed** OKLCH color token migration
+
+### v0.3.1
+- **Fixed** AlertProps 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/aspect-ratio.md

@@ -0,0 +1,25 @@
+# AspectRatio
+
+- Import: @devalok/shilp-sutra/ui/aspect-ratio
+- Server-safe: No
+- Category: ui
+
+## Props
+    ratio: number (e.g. 16/9, 4/3, 1)
+
+## Defaults
+    none
+
+## Example
+```jsx
+<AspectRatio ratio={16 / 9}>
+  <img src="/photo.jpg" alt="Photo" className="object-cover w-full h-full" />
+</AspectRatio>
+```
+
+## Gotchas
+- ratio is a number, not a string — use `16/9` not `"16/9"`
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/autocomplete.md

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

package/docs/components/ui/avatar.md

@@ -0,0 +1,34 @@
+# 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"
+
+## Compound Components
+    Avatar (root with size/shape/status)
+      AvatarImage (src, alt)
+      AvatarFallback (children = initials text)
+
+## Defaults
+    size="md", shape="circle"
+
+## Example
+```jsx
+<Avatar size="lg" status="online">
+  <AvatarImage src={user.photoUrl} alt={user.name} />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+## Gotchas
+- Status dot renders with role="img" and aria-label (accessible, not decorative)
+- Dot size scales automatically with avatar size
+
+## Changes
+### v0.1.0
+- **Added** Initial release with CVA size variants (xs-xl) and status indicator badge

package/docs/components/ui/badge.md

@@ -0,0 +1,48 @@
+# Badge
+
+- Import: @devalok/shilp-sutra/ui/badge
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: "subtle" | "solid" | "outline" | "secondary" (alias->subtle) | "destructive" (alias->solid+error)
+    color: "default" | "info" | "success" | "error" | "warning" | "brand" | "accent" | "teal" | "amber" | "slate" | "indigo" | "cyan" | "orange" | "emerald"
+    size: "xs" | "sm" | "md" | "lg"
+    dot: boolean (shows leading dot indicator)
+    onDismiss: () => void (shows X button when provided)
+    children: ReactNode
+
+## 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>
+```
+
+## Gotchas
+- DO NOT use variant="destructive" — use variant="solid" color="error"
+- Badge is display-only; for interactive tags use Chip
+
+## Changes
+### 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

@@ -0,0 +1,35 @@
+# Banner
+
+- Import: @devalok/shilp-sutra/ui/banner
+- Server-safe: No
+- Category: ui
+
+## Props
+    color: "info" | "success" | "warning" | "error" | "neutral"
+    action: ReactNode (optional action slot, typically a ghost Button)
+    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
+
+## Changes
+### 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

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

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

@@ -0,0 +1,32 @@
+# 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.4.2
+- **Fixed** `Omit<HTMLAttributes, 'color'>` resolves TS2320 conflict with CVA color prop
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/button.md

@@ -0,0 +1,55 @@
+# Button
+
+- Import: @devalok/shilp-sutra/ui/button
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: "solid" | "default" (alias->solid) | "outline" | "ghost" | "link" | "destructive" (alias->solid+error)
+    color: "default" | "error"
+    size: "sm" | "md" | "lg" | "icon" | "icon-sm" | "icon-md" | "icon-lg"
+    startIcon: ReactNode
+    endIcon: ReactNode
+    loading: boolean (disables button, shows spinner)
+    loadingPosition: "start" | "end" | "center" (default: "start")
+    fullWidth: boolean
+    asChild: boolean
+    onClickAsync: (e: MouseEvent) => Promise<void> (auto loading->success/error->idle)
+    asyncFeedbackDuration: number (ms, default 1500)
+
+## Defaults
+    variant="solid", color="default", size="md"
+
+## Example
+```jsx
+<Button variant="solid" color="error" startIcon={<IconTrash />} loading={isDeleting}>
+  Delete project
+</Button>
+```
+
+## Gotchas
+- DO NOT use variant="destructive" — use variant="solid" color="error"
+- DO NOT use variant="secondary" — use variant="outline" or variant="ghost"
+- DO NOT use size="default" — use size="md"
+- DO NOT use color="danger" — use color="error"
+- Inherits variant/color/size from ButtonGroup context if present
+- onClickAsync overrides onClick and loading when active
+
+## Changes
+### v0.18.0
+- **Added** `onClickAsync` prop — promise-driven loading -> success/error state machine
+- **Added** `asyncFeedbackDuration` prop (default 1500ms)
+- **Changed** whileTap scale animation added via Framer Motion
+- **Fixed** Async feedback colors — `bg-success text-text-on-color` changed to `bg-success-9 text-accent-fg`
+- **Fixed** `onClickAsync` added `isMountedRef` guard to prevent set-state-after-unmount
+
+### v0.4.2
+- **Fixed** `Omit<HTMLAttributes, 'color'>` resolves TS2320 conflict with CVA color prop
+- **Fixed** `className` was passed inside `buttonVariants()` (silently dropped by CVA) — now separate `cn()` argument
+
+### v0.3.0
+- **Changed** (BREAKING) `variant="primary"` renamed to `variant="solid"`, `variant="secondary"` renamed to `variant="outline"`, `variant="error"` moved to `color="error"`
+- **Fixed** All dismiss/close buttons now meet WCAG 2.5.8 minimum 24px touch target
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/card.md

@@ -0,0 +1,48 @@
+# Card
+
+- Import: @devalok/shilp-sutra/ui/card
+- Server-safe: No
+- Category: ui
+
+## Props
+    variant: "default" | "elevated" | "outline" | "flat"
+    interactive: boolean (enables hover shadow lift + pointer cursor)
+
+## Compound Components
+    Card (root)
+      CardHeader
+        CardTitle
+        CardDescription
+      CardContent
+      CardFooter
+
+## Defaults
+    variant="default"
+
+## Example
+```jsx
+<Card variant="elevated" interactive onClick={() => navigate(url)}>
+  <CardHeader>
+    <CardTitle>Project</CardTitle>
+    <CardDescription>Last updated 2h ago</CardDescription>
+  </CardHeader>
+  <CardContent><p>Content here</p></CardContent>
+</Card>
+```
+
+## Gotchas
+- Use `interactive` prop for clickable cards — adds hover lift and pointer cursor
+
+## Changes
+### v0.18.0
+- **Changed** Interactive card hover lift animation migrated to Framer Motion
+
+### v0.4.2
+- **Changed** (BREAKING) `variant="outlined"` renamed to `variant="outline"`
+- **Added** `cardVariants` export
+
+### v0.1.1
+- **Fixed** `leading-none tracking-tight` changed to `leading-ds-none tracking-ds-tight` for token compliance
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/charts.md

@@ -0,0 +1,43 @@
+# Charts
+
+- Import: @devalok/shilp-sutra/ui/charts
+- Server-safe: No
+- Category: ui
+
+## Props
+    Charts is a collection of chart components. Each accepts data-specific props.
+
+    Exported components:
+      ChartContainer — wrapper with responsive sizing
+      BarChart
+      LineChart
+      AreaChart
+      PieChart
+      Sparkline
+      GaugeChart
+      RadarChart
+      Legend — chart legend with LegendItem[]
+
+## Defaults
+    none
+
+## Example
+```jsx
+import { BarChart } from '@devalok/shilp-sutra/ui/charts'
+
+<BarChart data={salesData} />
+```
+
+## Gotchas
+- Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/charts`, NOT the `ui` barrel
+- Requires D3 as an optional peer dependency
+
+## Changes
+### v0.18.0
+- **Changed** All 8 chart types migrated to Framer Motion entrance animations
+
+### v0.5.0
+- **Changed** (BREAKING) All chart components removed from `@devalok/shilp-sutra/ui` barrel export. Must use `@devalok/shilp-sutra/ui/charts` import path.
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/checkbox.md

@@ -0,0 +1,31 @@
+# Checkbox
+
+- Import: @devalok/shilp-sutra/ui/checkbox
+- Server-safe: No
+- Category: ui
+
+## Props
+    checked: boolean | "indeterminate"
+    onCheckedChange: (checked: boolean | "indeterminate") => void
+    error: boolean (shows red border)
+    indeterminate: boolean (overrides checked, shows dash icon)
+    disabled: boolean
+
+## Defaults
+    none
+
+## Example
+```jsx
+<Checkbox checked={agreed} onCheckedChange={(v) => setAgreed(v === true)} />
+```
+
+## Gotchas
+- indeterminate overrides checked visually
+
+## Changes
+### v0.18.0
+- **Changed** Bouncy check indicator animation migrated to Framer Motion
+- **Fixed** Icon sizing uses design tokens consistently
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/chip.md

@@ -0,0 +1,43 @@
+# Chip
+
+- Import: @devalok/shilp-sutra/ui/chip
+- Server-safe: No
+- Category: ui
+
+## Props
+    label: string (REQUIRED — use this, NOT children)
+    variant: "subtle" | "outline"
+    color: "default" | "primary" | "success" | "error" | "warning" | "info" | "teal" | "amber" | "slate" | "indigo" | "cyan" | "orange" | "emerald"
+    size: "sm" | "md" | "lg"
+    icon: ReactNode
+    onClick: MouseEventHandler (renders as <button> when provided)
+    onDismiss: () => void (shows X button)
+    disabled: boolean
+
+## Defaults
+    variant="subtle", size="md", color="default"
+
+## Example
+```jsx
+<Chip label="In Progress" color="warning" />
+<Chip label="React" color="info" onDismiss={() => removeFilter('react')} />
+```
+
+## Additional Exports
+    ChipGroup — re-exported AnimatePresence from framer-motion; wrap a list of Chips for coordinated exit animations
+
+## Gotchas
+- MUST use label prop — children are NOT rendered
+- `<Chip>text</Chip>` is WRONG — use `<Chip label="text" />`
+- Wrap dynamic chip lists in `<ChipGroup>` for exit animations
+
+## Changes
+### v0.4.2
+- **Changed** (BREAKING) `variant="filled"` renamed to `"subtle"`, `variant="outlined"` renamed to `"outline"`, `onDelete` renamed to `onDismiss`
+
+### v0.1.1
+- **Fixed** `opacity-[var(--action-disabled-opacity,0.38)]` replaced with `opacity-action-disabled`
+- **Fixed** Converted from `React.createElement` to JSX syntax
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/code.md

@@ -0,0 +1,28 @@
+# Code
+
+- Import: @devalok/shilp-sutra/ui/code
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    variant: "inline" | "block"
+    children: ReactNode
+
+## Defaults
+    variant="inline"
+
+## Example
+```jsx
+<Code>onClick</Code>
+<Code variant="block">{`const x = 1;\nconsole.log(x);`}</Code>
+```
+
+## Gotchas
+- "block" renders as `<pre><code>`, "inline" renders as `<code>`
+
+## Changes
+### v0.1.1
+- **Fixed** `leading-[150%]` replaced with `leading-ds-relaxed` for token compliance
+
+### v0.1.0
+- **Added** Initial release