@devalok/shilp-sutra 0.18.0 → 0.18.2

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

package/docs/components/ui/collapsible.md

@@ -0,0 +1,40 @@
+# Collapsible
+
+- Import: @devalok/shilp-sutra/ui/collapsible
+- Server-safe: No
+- Category: ui
+
+## Props
+    open: boolean (controlled)
+    onOpenChange: (open: boolean) => void
+    defaultOpen: boolean
+
+## Compound Components
+    Collapsible (root)
+      CollapsibleTrigger
+      CollapsibleContent
+
+## Defaults
+    none
+
+## Example
+```jsx
+<Collapsible>
+  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+  <CollapsibleContent>Hidden content</CollapsibleContent>
+</Collapsible>
+```
+
+## Gotchas
+- Standard Radix Collapsible API
+
+## Changes
+### v0.13.0
+- **Changed** Default animation changed from fade-only to height-based expand/collapse using `animate-collapsible-down`/`animate-collapsible-up`
+- **Added** `collapsible-down` and `collapsible-up` keyframes added to Tailwind preset
+
+### v0.4.2
+- **Added** `CollapsibleProps` type export
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/color-input.md

@@ -0,0 +1,37 @@
+# ColorInput
+
+- Import: @devalok/shilp-sutra/ui/color-input
+- Server-safe: No
+- Category: ui
+
+## Props
+    value: string (hex color, e.g. "#d33163")
+    onChange: (value: string) => void
+    presets: string[] (optional preset color swatches)
+    disabled: boolean
+    className: string
+
+## Defaults
+    value="#000000", disabled=false
+
+## Example
+```jsx
+<ColorInput
+  value={color}
+  onChange={setColor}
+  presets={['#d33163', '#2563eb', '#16a34a']}
+/>
+```
+
+## Gotchas
+- Uses native color picker under the hood; value must be a valid hex string
+
+## Changes
+### v0.15.0
+- **Changed** `md` size font standardized to `text-ds-md` (14px) from mixed values
+
+### v0.8.0
+- **Fixed** Added `aria-label` to hex color input
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/combobox.md

@@ -0,0 +1,54 @@
+# Combobox
+
+- Import: @devalok/shilp-sutra/ui/combobox
+- Server-safe: No
+- Category: ui
+
+## Props
+    options: ComboboxOption[] (REQUIRED) — { value: string, label: string, description?: string, icon?: ReactNode, disabled?: boolean }
+    DISCRIMINATED UNION — type depends on `multiple` flag:
+    Single (default): multiple?: false, value: string, onValueChange: (value: string) => void
+    Multiple: multiple: true, value: string[], onValueChange: (value: string[]) => void
+    placeholder: string (default: "Select...")
+    searchPlaceholder: string (default: "Search...")
+    emptyMessage: string (default: "No results found")
+    disabled: boolean
+    triggerClassName: string
+    accessibleLabel: string (custom aria-label for trigger, falls back to placeholder)
+    maxVisible: number (default: 6, max dropdown items before scroll)
+    renderOption: (option, selected) => ReactNode
+
+## Defaults
+    placeholder="Select...", searchPlaceholder="Search...", emptyMessage="No results found", maxVisible=6
+
+## Example
+```jsx
+<Combobox
+  multiple
+  options={tagOptions}
+  value={selectedTags}
+  onValueChange={setSelectedTags}
+  placeholder="Select tags..."
+/>
+```
+
+## Gotchas
+- Enforces selection from list (unlike Autocomplete which allows free text)
+- In multi mode, selected items appear as pills with "+N more" overflow
+
+## Changes
+### v0.18.0
+- **Added** `accessibleLabel` prop — custom aria-label for trigger, falls back to placeholder
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes dropdown rendering behind Sheet/Dialog overlays
+
+### v0.8.0
+- **Changed** (BREAKING) Props now use discriminated union — `multiple: true` requires `value: string[]` and `onValueChange: (value: string[]) => void`
+
+### v0.3.0
+- **Changed** (BREAKING) `onChange` renamed to `onValueChange`
+- **Changed** Now extends HTMLAttributes — accepts all standard HTML props
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/container.md

@@ -0,0 +1,26 @@
+# Container
+
+- Import: @devalok/shilp-sutra/ui/container
+- Server-safe: Yes
+- Category: ui
+
+## Props
+    maxWidth: "default" | "body" | "full"
+    as: ElementType (default: "div")
+
+## Defaults
+    maxWidth="default"
+
+## Example
+```jsx
+<Container maxWidth="body">
+  <p>Centered content</p>
+</Container>
+```
+
+## Gotchas
+- Server-safe component — can be imported directly in Next.js Server Components
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/context-menu.md

@@ -0,0 +1,43 @@
+# ContextMenu
+
+- Import: @devalok/shilp-sutra/ui/context-menu
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    ContextMenu (root)
+      ContextMenuTrigger (right-click target)
+      ContextMenuContent
+        ContextMenuItem
+        ContextMenuCheckboxItem
+        ContextMenuRadioGroup > ContextMenuRadioItem
+        ContextMenuLabel
+        ContextMenuSeparator
+        ContextMenuSub > ContextMenuSubTrigger, ContextMenuSubContent
+
+## Defaults
+    none
+
+## Example
+```jsx
+<ContextMenu>
+  <ContextMenuTrigger>Right-click me</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Edit</ContextMenuItem>
+    <ContextMenuItem>Delete</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Gotchas
+- Triggered by right-click (or long-press on touch devices)
+
+## Changes
+### v0.18.0
+- **Added** `ContextMenuContentProps`, `ContextMenuItemProps` type exports
+
+### v0.14.0
+- **Changed** z-index promoted from `z-dropdown` (1000) to `z-popover` (1400) — fixes dropdown rendering behind Sheet/Dialog overlays
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/data-table-toolbar.md

@@ -0,0 +1,44 @@
+# DataTableToolbar
+
+- Import: @devalok/shilp-sutra/ui/data-table-toolbar
+- Server-safe: No
+- Category: ui
+
+## Props
+    table: Table<TData> (TanStack table instance)
+    globalFilter: boolean
+    globalFilterValue: string
+    onGlobalFilterChange: (value: string) => void
+    density: 'compact' | 'standard' | 'comfortable'
+    onDensityChange: (density: Density) => void
+    enableExport: boolean
+
+## Defaults
+    none
+
+## Example
+```jsx
+import { DataTableToolbar } from '@devalok/shilp-sutra/ui/data-table-toolbar'
+
+<DataTableToolbar
+  table={table}
+  globalFilter
+  globalFilterValue={filterValue}
+  onGlobalFilterChange={setFilterValue}
+  density={density}
+  onDensityChange={setDensity}
+  enableExport
+/>
+```
+
+## Gotchas
+- Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table-toolbar`, NOT the `ui` barrel
+- Companion to DataTable — provides column visibility, density toggle, and CSV export controls
+- Requires @tanstack/react-table as a peer dependency
+
+## Changes
+### v0.5.0
+- **Changed** (BREAKING) Removed from `@devalok/shilp-sutra/ui` barrel export — must use `@devalok/shilp-sutra/ui/data-table-toolbar`
+
+### v0.1.0
+- **Added** Initial release