@devalok/shilp-sutra 0.18.1 → 0.19.0

package/dist/ui/sidebar.js

@@ -98,7 +98,7 @@ const te = i(
       "div",
       {
         className: r(
-          "flex h-full w-[--sidebar-width] flex-col bg-surface-1 text-surface-fg",
+          "flex h-full w-[--sidebar-width] flex-col bg-surface-2 text-surface-fg",
           d
         ),
         ref: u,
@@ -110,7 +110,7 @@ const te = i(
       {
         "data-sidebar": "sidebar",
         "data-mobile": "true",
-        className: "w-[--sidebar-width] bg-surface-1 p-0 text-surface-fg [&>button]:hidden",
+        className: "w-[--sidebar-width] bg-surface-2 p-0 text-surface-fg [&>button]:hidden",
         style: {
           "--sidebar-width": Q
         },
@@ -152,7 +152,7 @@ const te = i(
                 "div",
                 {
                   "data-sidebar": "sidebar",
-                  className: "flex h-full w-full flex-col bg-surface-1 group-data-[variant=floating]:rounded-ds-lg group-data-[variant=floating]:border group-data-[variant=floating]:border-surface-border group-data-[variant=floating]:shadow",
+                  className: "flex h-full w-full flex-col bg-surface-2 group-data-[variant=floating]:rounded-ds-lg group-data-[variant=floating]:border group-data-[variant=floating]:border-surface-border group-data-[variant=floating]:shadow",
                   children: o
                 }
               )
@@ -202,7 +202,7 @@ const re = i(
           "hover:after:bg-surface-border-strong absolute inset-y-0 z-raised hidden w-4 -translate-x-1/2 transition-colors ease-linear after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] group-data-[side=left]:-right-4 group-data-[side=right]:left-0 sm:flex",
           "[[data-side=left]_&]:cursor-w-resize [[data-side=right]_&]:cursor-e-resize",
           "[[data-side=left][data-state=collapsed]_&]:cursor-e-resize [[data-side=right][data-state=collapsed]_&]:cursor-w-resize",
-          "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full group-data-[collapsible=offcanvas]:hover:bg-surface-2",
+          "group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full group-data-[collapsible=offcanvas]:hover:bg-surface-3",
           "[[data-side=left][data-collapsible=offcanvas]_&]:-right-2",
           "[[data-side=right][data-collapsible=offcanvas]_&]:-left-2",
           a
@@ -234,7 +234,7 @@ const de = i(({ className: a, ...e }, t) => /* @__PURE__ */ s(
     ref: t,
     "data-sidebar": "input",
     className: r(
-      "h-ds-sm w-full bg-surface-1 shadow-none focus-visible:ring-2 focus-visible:ring-accent-9",
+      "h-ds-sm w-full bg-surface-2 shadow-none focus-visible:ring-2 focus-visible:ring-accent-9",
       a
     ),
     ...e
@@ -325,7 +325,7 @@ const pe = i(({ className: a, asChild: e = !1, ...t }, d) => /* @__PURE__ */ s(
     ref: d,
     "data-sidebar": "group-action",
     className: r(
-      "hover:bg-surface-2 absolute right-ds-04 top-ds-04 flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
+      "hover:bg-surface-3 absolute right-ds-04 top-ds-04 flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
       "after:absolute after:-inset-2 after:md:hidden",
       "group-data-[collapsible=icon]:hidden",
       a
@@ -371,12 +371,12 @@ const ge = i(
 );
 ge.displayName = "SidebarMenuItem";
 const he = T(
-  "peer/menu-button hover:bg-surface-2 active:bg-accent-2 data-[active=true]:bg-accent-2 data-[state=open]:hover:bg-surface-2 flex w-full items-center gap-ds-03 overflow-hidden rounded-ds-md p-ds-03 text-left outline-none ring-accent-9 transition-[width,height,padding] hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled group-has-[[data-sidebar=menu-action]]/menu-item:pr-ds-07 aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled data-[active=true]:font-medium data-[active=true]:text-surface-fg data-[state=open]:hover:text-surface-fg group-data-[collapsible=icon]:!size-8 group-data-[collapsible=icon]:!p-ds-03 [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
+  "peer/menu-button hover:bg-surface-3 active:bg-accent-2 data-[active=true]:bg-accent-2 data-[state=open]:hover:bg-surface-3 flex w-full items-center gap-ds-03 overflow-hidden rounded-ds-md p-ds-03 text-left outline-none ring-accent-9 transition-[width,height,padding] hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled group-has-[[data-sidebar=menu-action]]/menu-item:pr-ds-07 aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled data-[active=true]:font-medium data-[active=true]:text-surface-fg data-[state=open]:hover:text-surface-fg group-data-[collapsible=icon]:!size-8 group-data-[collapsible=icon]:!p-ds-03 [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
   {
     variants: {
       variant: {
-        default: "hover:bg-surface-2 hover:text-surface-fg",
-        outline: "hover:bg-surface-2 bg-surface-1 shadow-[0_0_0_1px_var(--color-surface-border)] hover:text-surface-fg hover:shadow-[0_0_0_1px_var(--color-surface-border-strong)]"
+        default: "hover:bg-surface-3 hover:text-surface-fg",
+        outline: "hover:bg-surface-3 bg-surface-2 shadow-[0_0_0_1px_var(--color-surface-border)] hover:text-surface-fg hover:shadow-[0_0_0_1px_var(--color-surface-border-strong)]"
       },
       size: {
         md: "h-ds-sm text-ds-md",
@@ -445,7 +445,7 @@ const xe = i(({ className: a, asChild: e = !1, showOnHover: t = !1, ...d }, o) =
     ref: o,
     "data-sidebar": "menu-action",
     className: r(
-      "hover:bg-surface-2 absolute right-ds-02 top-ds-02b flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 peer-hover/menu-button:text-surface-fg [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
+      "hover:bg-surface-3 absolute right-ds-02 top-ds-02b flex aspect-square w-5 items-center justify-center rounded-ds-md p-0 text-surface-fg outline-none ring-accent-9 transition-transform hover:text-surface-fg focus-visible:ring-2 peer-hover/menu-button:text-surface-fg [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0",
       "after:absolute after:-inset-2 after:md:hidden",
       "peer-data-[size=sm]/menu-button:top-1",
       "peer-data-[size=md]/menu-button:top-ds-02b",
@@ -538,7 +538,7 @@ const Me = i(({ asChild: a = !1, size: e = "md", isActive: t, className: d, ...o
     "data-size": e,
     "data-active": t,
     className: r(
-      "hover:bg-surface-2 active:bg-accent-2 flex h-ds-xs-plus min-w-0 -translate-x-px items-center gap-ds-03 overflow-hidden rounded-ds-md px-ds-03 text-surface-fg outline-none ring-accent-9 hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0 [&>svg]:text-surface-fg",
+      "hover:bg-surface-3 active:bg-accent-2 flex h-ds-xs-plus min-w-0 -translate-x-px items-center gap-ds-03 overflow-hidden rounded-ds-md px-ds-03 text-surface-fg outline-none ring-accent-9 hover:text-surface-fg focus-visible:ring-2 active:text-surface-fg disabled:pointer-events-none disabled:opacity-action-disabled aria-disabled:pointer-events-none aria-disabled:opacity-action-disabled [&>span:last-child]:truncate [&>svg]:h-ico-sm [&>svg]:w-ico-sm [&>svg]:shrink-0 [&>svg]:text-surface-fg",
       "data-[active=true]:bg-accent-2 data-[active=true]:text-surface-fg",
       e === "sm" && "text-ds-sm",
       e === "md" && "text-ds-md",

package/docs/components/_header.md

@@ -0,0 +1,85 @@
+# @devalok/shilp-sutra — Full Component Reference
+
+> Exhaustive API reference for AI coding agents.
+> For a concise cheatsheet, see llms.txt instead.
+> All variant values and props verified from source CVA definitions.
+>
+> Package: @devalok/shilp-sutra
+> Version: {{VERSION}}
+
+---
+
+## Architecture Notes
+
+### The Two-Axis Variant System
+
+Many components use TWO props where shadcn/ui uses one:
+- `variant` controls SHAPE/SURFACE: solid, outline, ghost, subtle, filled, etc.
+- `color` controls INTENT/SEMANTICS: default, error, success, warning, info, etc.
+
+Components with two-axis system: Button, Badge, Alert, Chip, Banner, Progress, StatusBadge
+
+### Server-Safe Components (no "use client")
+
+These can be imported directly in Next.js Server Components:
+- UI: Text, Skeleton, Stack, Container, Table (and sub-components), Code, VisuallyHidden
+- Composed: ContentCard, PageHeader, LoadingSkeleton, PageSkeletons, PriorityIndicator
+- NOTE (v0.18.0): Spinner, EmptyState, StatusBadge are NO LONGER server-safe (Framer Motion dependency)
+
+Use per-component imports for server components:
+  import { Text } from '@devalok/shilp-sutra/ui/text'
+  import { PageHeader } from '@devalok/shilp-sutra/composed/page-header'
+
+DO NOT use barrel imports in Server Components — they include "use client" components.
+
+### Token Architecture — OKLCH 12-Step System
+
+Color tokens use OKLCH (perceptually uniform) with 12 functional steps per palette:
+
+| Step | Purpose | Example usage |
+|------|---------|---------------|
+| 1 | App background | Page bg, body |
+| 2 | Subtle background | Sidebar, card alt |
+| 3 | Component bg | Input bg, badge bg |
+| 4 | Component bg hover | Button hover state |
+| 5 | Border subtle | Semantic `surface-border` in light mode |
+| 6 | Border default | Semantic `surface-border-strong` in light mode |
+| 7 | Border strong | Focus rings, emphasis borders |
+| 8 | Border emphasis | High-contrast outlines |
+| 9 | Solid / accent | Button bg, primary CTA |
+| 10 | Solid hover | Button hover bg |
+| 11 | Low-contrast text | Secondary accent text |
+| 12 | High-contrast text | Headings on light bg |
+
+Semantic layer:
+- Accent (swappable): --color-accent-{1-12} + --color-accent-fg
+- Secondary: --color-secondary-{1-12} + --color-secondary-fg
+- Surface: --color-surface-{1-4} + --color-surface-fg / fg-muted / fg-subtle / border / border-strong
+  - Border mapping: light mode border=step5, border-strong=step6; dark mode border=step3, border-strong=step4
+  - Shell chrome (sidebar, topbar, bottom nav) uses surface-2 for elevation above surface-1 app background
+- Status: --color-{error,success,warning,info}-{3,7,9,11}
+- Category: --color-category-{teal,amber,slate,indigo,cyan,orange,emerald}
+
+Consumer rebranding: Override accent scale CSS vars or use generateScale(options) utility.
+
+Tailwind utilities: accent-1..12, secondary-1..12, surface-1..4, plus fg/border variants.
+
+### Toast Setup Pattern
+
+1. Mount <Toaster /> once at your root layout.
+2. Import { toast } from '@devalok/shilp-sutra/ui/toast' and call toast.success(), toast.error(), etc.
+3. Types: 'success' | 'error' | 'warning' | 'info' | 'loading' | 'message'
+
+### Form Accessibility Pattern
+
+Use <FormField> + useFormField() hook:
+  <FormField state="error">
+    <Label htmlFor="email">Email</Label>
+    <Input id="email" state="error" />
+    <FormHelperText>Error message here.</FormHelperText>
+  </FormField>
+
+useFormField() returns { state, helperTextId, required } from context.
+Wire manually: <Input aria-describedby={helperTextId} aria-invalid={state === 'error'} />
+
+Note: getFormFieldA11y() was removed in favor of useFormField() hook.

package/docs/components/composed/activity-feed.md

@@ -0,0 +1,43 @@
+# ActivityFeed
+
+- Import: @devalok/shilp-sutra/composed/activity-feed
+- Server-safe: No
+- Category: composed
+
+## Props
+    items: ActivityItem[] (REQUIRED) — { id, actor?: { name, image? }, action: string|ReactNode, timestamp: Date|string, icon?, color?: 'default'|'success'|'warning'|'error'|'info', detail?: ReactNode }
+    onLoadMore?: () => void — "Load more" button callback
+    loading: boolean — skeleton shimmer
+    hasMore?: boolean — shows "Load more" button
+    emptyState?: ReactNode — empty state content
+    compact: boolean — tighter spacing, no avatars, smaller text
+    maxInitialItems: number — truncate with "Show all (N)" toggle
+
+## Defaults
+    loading=false, compact=false, hasMore=false
+
+## Example
+```jsx
+<ActivityFeed
+  items={[
+    { id: '1', actor: { name: 'Alice' }, action: 'completed task', timestamp: new Date(), color: 'success' },
+    { id: '2', action: 'System backup completed', timestamp: new Date(), detail: <pre>Details...</pre> },
+  ]}
+  hasMore
+  onLoadMore={() => fetchMore()}
+  compact
+/>
+```
+
+## Gotchas
+- `items` is required — passing an empty array renders the `emptyState` content
+- `color` on each item controls the timeline dot color
+- `actor.image` is optional — falls back to initials from `actor.name`
+- `maxInitialItems` truncates with a "Show all (N)" toggle button
+
+## Changes
+### v0.18.0
+- **Fixed** `bg-accent-9` changed to `bg-info-9` (info color, not accent)
+
+### v0.16.0
+- **Added** Initial release — vertical timeline with colored dots, actor avatars, expandable detail, compact mode, load more, maxInitialItems truncation

package/docs/components/composed/avatar-group.md

@@ -0,0 +1,32 @@
+# AvatarGroup
+
+- Import: @devalok/shilp-sutra/composed/avatar-group
+- Server-safe: No
+- Category: composed
+
+## Props
+    users: AvatarUser[] (REQUIRED) — { name: string, image?: string | null }
+    max: number (default: 4, overflow shows "+N" badge)
+    size: "sm" | "md" | "lg"
+    showTooltip: boolean (default: true)
+
+## Defaults
+    size="md", max=4, showTooltip=true
+
+## Example
+```jsx
+<AvatarGroup
+  users={[{ name: 'Alice', image: '/alice.jpg' }, { name: 'Bob' }]}
+  max={3}
+  size="md"
+/>
+```
+
+## Gotchas
+- Wraps TooltipProvider internally — no need to add one yourself
+- Users beyond `max` are collapsed into a "+N" overflow badge
+- Missing `image` falls back to initials derived from `name`
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/command-palette.md

@@ -0,0 +1,40 @@
+# CommandPalette
+
+- Import: @devalok/shilp-sutra/composed/command-palette
+- Server-safe: No
+- Category: composed
+
+## Props
+    groups?: CommandGroup[] (default: []) — { label: string, items: CommandItem[] }
+    placeholder: string (default: "Search or jump to...")
+    onSearch: (query: string) => void
+    emptyMessage: string (default: "No results found.")
+
+CommandItem shape: { id, label, description?, icon?, shortcut?, onSelect: () => void }
+
+## Defaults
+    placeholder="Search or jump to...", emptyMessage="No results found.", groups=[]
+
+## Example
+```jsx
+<CommandPalette
+  groups={[{
+    label: 'Navigation',
+    items: [{ id: 'dash', label: 'Dashboard', onSelect: () => navigate('/') }],
+  }]}
+/>
+```
+
+## Gotchas
+- Opens with Ctrl+K / Cmd+K by default
+- Items animate in with staggered slide-up (30ms delay cascade); groups fade in; active item icon/shortcut highlight in interactive color (v0.15.0)
+
+## Changes
+### v0.15.0
+- **Added** Staggered slide-up entrance animations for items, fade-in for groups/empty state/footer, scale-in for search icon, active item icon/shortcut color transitions
+
+### v0.8.0
+- **Added** Full ARIA combobox pattern (`role="combobox"`, `aria-expanded`, `aria-activedescendant`)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/confirm-dialog.md

@@ -0,0 +1,46 @@
+# ConfirmDialog
+
+- Import: @devalok/shilp-sutra/composed/confirm-dialog
+- Server-safe: No
+- Category: composed
+
+## Props
+    open: boolean (REQUIRED, controlled)
+    onOpenChange: (open: boolean) => void (REQUIRED)
+    title: string (REQUIRED)
+    description: string (REQUIRED)
+    confirmText: string (default: "Confirm")
+    cancelText: string (default: "Cancel")
+    color: "default" | "error" (controls confirm button color)
+    loading: boolean (default: false, disables buttons and replaces confirm button text with 'Processing...')
+    onConfirm: () => void | Promise<void> (REQUIRED)
+
+## Defaults
+    confirmText="Confirm", cancelText="Cancel", color="default", loading=false
+
+## Example
+```jsx
+const [open, setOpen] = useState(false)
+<ConfirmDialog
+  open={open}
+  onOpenChange={setOpen}
+  title="Delete project?"
+  description="This action cannot be undone."
+  color="error"
+  confirmText="Delete"
+  loading={isDeleting}
+  onConfirm={async () => { await deleteProject(); setOpen(false) }}
+/>
+```
+
+## Gotchas
+- Dialog stays open after confirm — consumer must close it via `onOpenChange`
+- Built on AlertDialog internally
+- Fully controlled — `open` and `onOpenChange` are required
+
+## Changes
+### v0.18.0
+- **Fixed** Converted to `forwardRef` pattern
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/content-card.md

@@ -0,0 +1,36 @@
+# ContentCard
+
+- Import: @devalok/shilp-sutra/composed/content-card
+- Server-safe: Yes
+- Category: composed
+
+## Props
+    variant: "default" | "outline" | "ghost"
+    padding: "default" | "compact" | "spacious" | "none"
+    header: ReactNode (custom header content)
+    headerTitle: string (simple text header)
+    headerActions: ReactNode (actions in header area)
+    footer: ReactNode
+    children: ReactNode (body)
+
+## Defaults
+    variant="default", padding="default"
+
+## Example
+```jsx
+<ContentCard headerTitle="Team Members" headerActions={<Button size="sm">Add</Button>}>
+  <p>Member list here</p>
+</ContentCard>
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- Use `headerTitle` for simple text headers; use `header` for custom header content
+- `header` takes precedence over `headerTitle` if both are provided
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/date-picker.md

@@ -0,0 +1,130 @@
+# DatePicker
+
+- Import: @devalok/shilp-sutra/composed/date-picker
+- Server-safe: No
+- Category: composed
+
+## Props
+
+### DatePicker
+    value?: Date | null
+    onChange?: (date: Date | null) => void
+    placeholder: string (default: "Pick a date")
+    formatStr: string (default: "MMM d, yyyy")
+    minDate: Date
+    maxDate: Date
+    disabledDates: (date: Date) => boolean
+    className: string
+
+### DateRangePicker
+    startDate?: Date | null
+    endDate?: Date | null
+    onChange?: (range: { start: Date | null, end: Date | null }) => void
+    placeholder: string (default: "Pick a date range")
+    formatStr: string (default: "MMM d, yyyy")
+    minDate: Date
+    maxDate: Date
+    disabledDates: (date: Date) => boolean
+    presets: PresetKey[] (shows quick-select sidebar)
+    numberOfMonths: number (default: 1)
+
+### DateTimePicker
+    value: Date | null
+    onChange: (date: Date | null) => void
+    minDate: Date
+    maxDate: Date
+    disabledDates: (date: Date) => boolean
+    timeFormat: "12h" | "24h"
+    minuteStep: number
+    placeholder: string
+    className: string
+
+### TimePicker
+    value?: Date | null (time stored as a Date object)
+    onChange?: (date: Date) => void
+    format: "12h" | "24h" (default: "12h")
+    minuteStep: number (default: 1)
+    secondStep: number (default: 1)
+    showSeconds: boolean (default: false)
+    placeholder: string (default: "Pick a time")
+    disabled: boolean (default: false)
+    className: string
+
+### CalendarGrid
+    currentMonth: Date (REQUIRED)
+    selected?: Date | null
+    rangeStart?: Date | null
+    rangeEnd?: Date | null
+    hoverDate?: Date | null
+    onSelect: (date: Date) => void (REQUIRED)
+    onHover?: (date: Date | null) => void
+    onMonthChange: (date: Date) => void (REQUIRED)
+    onHeaderClick?: () => void
+    disabledDates: (date: Date) => boolean
+    minDate: Date
+    maxDate: Date
+    hidePrevNav: boolean
+    hideNextNav: boolean
+    events: CalendarEvent[] — { date: Date, color?: string, label?: string }
+
+### YearPicker
+    currentYear: number (REQUIRED)
+    selectedYear: number
+    onYearSelect: (year: number) => void (REQUIRED)
+    minDate: Date
+    maxDate: Date
+
+### MonthPicker
+    currentYear: number (REQUIRED)
+    selectedMonth: number (0-11)
+    onMonthSelect: (month: number) => void (REQUIRED)
+    minDate: Date
+    maxDate: Date
+
+### Presets
+    presets: PresetKey[] (REQUIRED)
+    onSelect: (start: Date, end: Date) => void (REQUIRED)
+    className: string
+
+PresetKey: 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisMonth' | 'lastMonth' | 'thisYear'
+
+### useCalendar hook
+    useCalendar(initialMonth?: Date) => { currentMonth, setCurrentMonth, goToPreviousMonth, goToNextMonth, goToMonth, goToYear }
+
+## Defaults
+    DatePicker: placeholder="Pick a date", formatStr="MMM d, yyyy"
+    DateRangePicker: placeholder="Pick a date range", formatStr="MMM d, yyyy", numberOfMonths=1
+    TimePicker: format="12h", minuteStep=1, secondStep=1, showSeconds=false
+
+## Example
+```jsx
+<DatePicker value={date} onChange={setDate} placeholder="Select date" />
+
+<DateRangePicker
+  startDate={start}
+  endDate={end}
+  onChange={({ start, end }) => { setStart(start); setEnd(end); }}
+/>
+
+<DateTimePicker value={dateTime} onChange={setDateTime} timeFormat="12h" minuteStep={15} />
+
+<TimePicker value={time} onChange={setTime} format="24h" minuteStep={15} />
+```
+
+## Gotchas
+- TimePicker stores time inside a Date object — only hours/minutes/seconds are meaningful
+- CalendarGrid is a low-level building block — prefer DatePicker/DateRangePicker for most use cases
+- MonthPicker month values are 0-indexed (Jan=0, Dec=11) — same as JavaScript `Date.getMonth()`
+- YearPicker displays a 12-year grid based on the decade of `currentYear`
+- CalendarGrid supports up to 3 event dots per day cell
+- useCalendar is a convenience hook for managing calendar month state
+
+## Changes
+### v0.18.0
+- **Fixed** Added `aria-label` to DatePicker/DateRangePicker trigger buttons
+
+### v0.4.2
+- **Changed** DateRangePicker default `formatStr` from `'MMM d'` to `'MMM d, yyyy'`
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/empty-state.md

@@ -0,0 +1,53 @@
+# EmptyState
+
+- Import: @devalok/shilp-sutra/composed/empty-state
+- Server-safe: No
+- Category: composed
+
+Note: EmptyState was server-safe prior to v0.18.0 but is NO LONGER server-safe due to Framer Motion dependency.
+
+## Props
+    title: string (REQUIRED)
+    description: string
+    icon: ReactNode | ComponentType<{ className?: string }> (default: Devalok chakra icon)
+    action: ReactNode (e.g. a Button)
+    compact: boolean (smaller layout)
+    iconSize: 'sm' | 'md' | 'lg' (default 'md', compact defaults to 'sm') — sm=h-ico-sm, md=h-ico-lg, lg=h-ico-xl
+
+## Defaults
+    iconSize="md" (compact defaults to "sm")
+
+## Example
+```jsx
+<EmptyState
+  title="No tasks found"
+  description="Create your first task to get started."
+  action={<Button>Create Task</Button>}
+  iconSize="lg"
+/>
+```
+
+## Gotchas
+- `icon` accepts both JSX elements (`<IconFolder />`) and component references (`IconFolder`). Component references are auto-instantiated with correct sizing classes.
+- `iconSize` controls icon dimensions regardless of icon type. When `compact=true` and no `iconSize`, defaults to `'sm'`.
+- As of v0.18.0, EmptyState is NOT server-safe (Framer Motion dependency). Use per-component import in client components.
+
+## Changes
+### v0.18.0
+- **Changed** No longer server-safe due to Framer Motion dependency
+
+### v0.16.0
+- **Added** `iconSize?: 'sm' | 'md' | 'lg'` — control icon dimensions
+
+### v0.13.0
+- **Changed** `icon` prop now accepts `React.ComponentType<{ className?: string }>` in addition to `ReactNode` — component references are auto-instantiated
+
+### v0.5.0
+- **Changed** `icon` prop changed from `TablerIcon` (component ref) to `React.ReactNode` — use `icon={<MyIcon />}` instead of `icon={MyIcon}`
+- **Changed** Default icon is now the Devalok swadhisthana chakra (inline SVG)
+
+### v0.2.0
+- **Added** Identified as server-safe component (later reverted in v0.18.0)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/error-boundary.md

@@ -0,0 +1,29 @@
+# ErrorDisplay
+
+- Import: @devalok/shilp-sutra/composed/error-boundary
+- Server-safe: No
+- Category: composed
+
+## Props
+    error: unknown (REQUIRED — Error object, status object, or string)
+    onReset: () => void (optional retry button)
+
+## Defaults
+    None
+
+## Example
+```jsx
+<ErrorDisplay error={error} onReset={() => refetch()} />
+```
+
+## Gotchas
+- Auto-detects HTTP status codes (404, 403, 500) and shows appropriate icon/message
+- Shows stack trace in development mode only
+- The import path is `error-boundary` but the component is named `ErrorDisplay`
+
+## Changes
+### v0.18.0
+- **Added** ErrorBoundary tests (13 new tests)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/global-loading.md

@@ -0,0 +1,27 @@
+# GlobalLoading
+
+- Import: @devalok/shilp-sutra/composed/global-loading
+- Server-safe: No
+- Category: composed
+
+## Props
+    isLoading: boolean (REQUIRED)
+
+## Defaults
+    None
+
+## Example
+```jsx
+<GlobalLoading isLoading={isNavigating} />
+```
+
+## Gotchas
+- Fixed-position bar at top of viewport (z-toast layer)
+- Renders nothing when `isLoading` is false
+
+## Changes
+### v0.18.0
+- **Fixed** Track `setTimeout` with ref, add cleanup on unmount
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/loading-skeleton.md

@@ -0,0 +1,51 @@
+# LoadingSkeleton
+
+- Import: @devalok/shilp-sutra/composed/loading-skeleton
+- Server-safe: Yes
+- Category: composed
+
+Exports: CardSkeleton, TableSkeleton, BoardSkeleton, ListSkeleton
+
+## Props
+
+### CardSkeleton
+    className: string
+
+### TableSkeleton
+    rows: number (default: 5)
+    columns: number (default: 4)
+    className: string
+
+### BoardSkeleton
+    columns: number (default: 4)
+    cardsPerColumn: number (default: 3)
+    className: string
+
+### ListSkeleton
+    rows: number (default: 6)
+    showAvatar: boolean (default: true)
+    className: string
+
+## Defaults
+    TableSkeleton: rows=5, columns=4
+    BoardSkeleton: columns=4, cardsPerColumn=3
+    ListSkeleton: rows=6, showAvatar=true
+
+## Example
+```jsx
+<CardSkeleton />
+<TableSkeleton rows={8} columns={5} />
+<BoardSkeleton columns={3} cardsPerColumn={4} />
+<ListSkeleton rows={10} showAvatar={false} />
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- These are pre-composed skeleton layouts — for individual skeleton shapes, use the `Skeleton` UI component
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release