@devalok/shilp-sutra 0.18.1 → 0.19.0

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,44 @@
+# 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
+- `color="primary"` will be renamed to `color="brand"` in v1.0 — use `color="primary"` for now
+
+## 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

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

@@ -0,0 +1,91 @@
+# DataTable
+
+- Import: @devalok/shilp-sutra/ui/data-table
+- Server-safe: No
+- Category: ui
+
+## Props
+    columns: ColumnDef<TData>[] (TanStack column definitions)
+    data: TData[]
+    sortable: boolean — enable column sorting
+    onSort: (key: string, dir: 'asc' | 'desc' | false) => void — server-side sort callback (enables manualSorting)
+    filterable: boolean — enable per-column filters
+    globalFilter: boolean — enable global search
+    paginated: boolean — enable client-side pagination
+    pagination: { page: number, pageSize: number, total: number, onPageChange: (page: number) => void } — server-side pagination (1-based page)
+    pageSize: number (default 10)
+    selectable: boolean — enable row selection with checkboxes
+    selectedIds: Set<string> — controlled selection state
+    selectableFilter: (row: TData) => boolean — disable selection on certain rows
+    getRowId: (row: TData) => string — custom row ID accessor
+    onSelectionChange: (selectedRows: TData[]) => void
+    expandable: boolean — enable row expansion
+    renderExpanded: (row: TData) => ReactNode — expanded row content
+    singleExpand: boolean — only one row expanded at a time
+    loading: boolean — show skeleton shimmer rows
+    emptyState: ReactNode — custom empty state (takes precedence over noResultsText)
+    noResultsText: string (default "No results.")
+    stickyHeader: boolean — sticky table header
+    onRowClick: (row: TData) => void — row click handler (excludes interactive element clicks)
+    bulkActions: BulkAction<TData>[] — floating action bar on selection — { label, onClick, color?: 'default'|'error', disabled? }
+    toolbar: boolean — show DataTableToolbar (column visibility, density, CSV export)
+    editable: boolean — enable double-click cell editing
+    virtualRows: boolean — virtualize rows for large datasets
+    columnPinning: { left?: string[], right?: string[] }
+    defaultDensity: 'compact' | 'standard' | 'comfortable'
+
+## Defaults
+    pageSize=10, noResultsText="No results."
+
+## Example
+```jsx
+import { DataTable } from '@devalok/shilp-sutra/ui/data-table'
+
+<DataTable
+  columns={[
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'email', header: 'Email' },
+  ]}
+  data={users}
+  sortable
+  onSort={(key, dir) => handleSort(key, dir)}
+  pagination={{ page, pageSize: 20, total: totalCount, onPageChange: setPage }}
+  loading={isLoading}
+  emptyState={<EmptyState title="No users" />}
+/>
+```
+
+## Gotchas
+- Barrel-isolated since v0.5.0 — must use `@devalok/shilp-sutra/ui/data-table`, NOT the `ui` barrel
+- Requires @tanstack/react-table and @tanstack/react-virtual as peer dependencies
+- When onSort is provided, sorting is manual (server-side) — rows stay in data order
+- When pagination prop is provided, pagination is manual — pass total count
+- selectedIds syncs via useEffect — provide getRowId for custom row IDs
+- onRowClick does NOT fire when clicking checkboxes, buttons, links, or inputs
+- Use defaultDensity="compact" for Karm-style h-9 rows
+
+## Changes
+### v0.16.1
+- **Fixed** `serverPagination` object reference in `useCallback` dependency caused stale closure — now uses stable ref for `onPageChange`
+- **Fixed** `onSelectionChange` effect fired every render due to `table` in dependency array — now derives selected rows directly
+- **Fixed** `selectedRows` useMemo for bulk actions had same `table` dependency issue
+
+### v0.16.0
+- **Added** `onSort` callback for server-side sorting
+- **Added** `emptyState` ReactNode slot
+- **Added** `loading` prop with shimmer skeleton rows
+- **Added** `selectedIds` + `selectableFilter` for controlled selection
+- **Added** `pagination` prop for server-side pagination
+- **Added** `singleExpand` prop
+- **Added** `stickyHeader` prop
+- **Added** `onRowClick` handler
+- **Added** `bulkActions` floating action bar
+
+### v0.5.0
+- **Changed** (BREAKING) Removed from `@devalok/shilp-sutra/ui` barrel export — must use `@devalok/shilp-sutra/ui/data-table`
+
+### v0.1.1
+- **Fixed** `useEffect` exhaustive-deps with proper dependency array
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/ui/dialog.md

@@ -0,0 +1,51 @@
+# Dialog
+
+- Import: @devalok/shilp-sutra/ui/dialog
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    Dialog (root)
+      DialogTrigger
+      DialogContent
+        DialogHeader
+          DialogTitle
+          DialogDescription
+        [body content]
+        DialogFooter
+      DialogClose
+
+## Defaults
+    none
+
+## Example
+```jsx
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Edit Profile</DialogTitle>
+      <DialogDescription>Make changes to your profile.</DialogDescription>
+    </DialogHeader>
+    <div>Form fields here</div>
+    <DialogFooter>
+      <Button>Save</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Gotchas
+- DialogTitle is required for accessibility — screen readers announce it when the dialog opens
+
+## Changes
+### v0.18.0
+- **Changed** Overlay animations migrated to Framer Motion (physics-based springs)
+- **Added** `DialogContentProps`, `DialogTitleProps` type exports
+- **Fixed** Context provider value wrapped in `useMemo` for performance
+
+### v0.3.0
+- **Fixed** DialogHeader/Footer now support ref forwarding
+
+### v0.1.0
+- **Added** Initial release

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

@@ -0,0 +1,45 @@
+# DropdownMenu
+
+- Import: @devalok/shilp-sutra/ui/dropdown-menu
+- Server-safe: No
+- Category: ui
+
+## Compound Components
+    DropdownMenu (root)
+      DropdownMenuTrigger
+      DropdownMenuContent
+        DropdownMenuLabel
+        DropdownMenuSeparator
+        DropdownMenuItem (+ DropdownMenuShortcut for keyboard hints)
+        DropdownMenuCheckboxItem
+        DropdownMenuRadioGroup > DropdownMenuRadioItem
+        DropdownMenuGroup
+        DropdownMenuSub > DropdownMenuSubTrigger, DropdownMenuSubContent
+
+## Defaults
+    none
+
+## Example
+```jsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild><Button variant="ghost">Menu</Button></DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Profile</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Logout</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Gotchas
+- Use `asChild` on DropdownMenuTrigger to render your own button element
+
+## Changes
+### v0.18.0
+- **Added** `DropdownMenuContentProps`, `DropdownMenuItemProps` 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