@devalok/shilp-sutra 0.34.1 → 0.36.0

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

@@ -1,62 +1,62 @@
-# 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
-    groupBy?: 'time' | 'none' — group items by time buckets (today, yesterday, this week, older)
-    groupLabels?: GroupLabels — custom labels for time groups: { today?, yesterday?, thisWeek?, older? }
-    renderItem?: (item: ActivityItem, index: number) => ReactNode | undefined — custom renderer per item; return undefined to fall back to default ActivityEntry
-
-## Defaults
-    loading=false, compact=false, hasMore=false, groupBy='none'
-
-## 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
-/>
-```
-
-## Exported Utilities
-    groupItemsByTime(items: ActivityItem[], labels?: GroupLabels) — pure function that buckets items into time groups; returns { label: string, items: ActivityItem[] }[]
-
-## 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
-- `maxInitialItems` applies to the flat list BEFORE grouping — items are sliced first, then grouped
-- Empty time groups are automatically skipped
-- `renderItem` receives the item and index; return `undefined` to use the default ActivityEntry rendering
-- Custom `renderItem` content is wrapped in the same dot + layout container as default entries for consistent vertical rhythm
-
-## Changes
-### v0.29.0
-- **Added** `renderItem` prop — custom render function per item; return ReactNode for custom rendering, return `undefined` to fall back to default ActivityEntry
-- **Added** Internal `CustomEntry` wrapper that keeps dot + layout consistent with default entries
-
-### v0.20.0
-- **Added** `groupBy="time"` prop — groups items into Today, Yesterday, This Week, Older with section headers
-- **Added** `groupLabels` prop for custom group label text
-- **Added** `groupItemsByTime()` exported pure utility function
-
-### 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
+# 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
+    groupBy?: 'time' | 'none' — group items by time buckets (today, yesterday, this week, older)
+    groupLabels?: GroupLabels — custom labels for time groups: { today?, yesterday?, thisWeek?, older? }
+    renderItem?: (item: ActivityItem, index: number) => ReactNode | undefined — custom renderer per item; return undefined to fall back to default ActivityEntry
+
+## Defaults
+    loading=false, compact=false, hasMore=false, groupBy='none'
+
+## 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
+/>
+```
+
+## Exported Utilities
+    groupItemsByTime(items: ActivityItem[], labels?: GroupLabels) — pure function that buckets items into time groups; returns { label: string, items: ActivityItem[] }[]
+
+## 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
+- `maxInitialItems` applies to the flat list BEFORE grouping — items are sliced first, then grouped
+- Empty time groups are automatically skipped
+- `renderItem` receives the item and index; return `undefined` to use the default ActivityEntry rendering
+- Custom `renderItem` content is wrapped in the same dot + layout container as default entries for consistent vertical rhythm
+
+## Changes
+### v0.29.0
+- **Added** `renderItem` prop — custom render function per item; return ReactNode for custom rendering, return `undefined` to fall back to default ActivityEntry
+- **Added** Internal `CustomEntry` wrapper that keeps dot + layout consistent with default entries
+
+### v0.20.0
+- **Added** `groupBy="time"` prop — groups items into Today, Yesterday, This Week, Older with section headers
+- **Added** `groupLabels` prop for custom group label text
+- **Added** `groupItemsByTime()` exported pure utility function
+
+### 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

@@ -1,65 +1,65 @@
-# AvatarGroup
-
-- Import: @devalok/shilp-sutra/composed/avatar-group
-- Server-safe: No
-- Category: composed
-
-## Props
-    users: AvatarUser[] (REQUIRED) — { name: string, image?: string | null, ring?: AvatarRing }
-    max: number (default: 4, overflow shows "+N" badge)
-    size: "xs" | "sm" | "md" | "lg" | "xl"
-    showTooltip: boolean (default: true)
-    borderColor: "surface-base" | "surface-raised" (default: "surface-raised") — overlap border color
-    onOverflowClick: () => void — makes the "+N" badge interactive (button)
-    renderAvatar: (user: AvatarUser, index: number) => ReactNode — custom avatar render
-    expandDirection: "left" | "right" (default: "right") — direction group expands on hover
-    expandAmount: "compact" | "default" | "wide" (default: "default") — how far group spreads
-
-## AvatarUser Type
-    name: string (REQUIRED)
-    image?: string | null
-    ring?: "none" | "lead" | "admin" | "client" — role ring per user in group
-    indicator?: "lead" | "admin" | ReactNode — small dot indicator at top-right of avatar
-
-## Defaults
-    size="md", max=4, showTooltip=true, borderColor="surface-raised", expandDirection="right", expandAmount="default"
-
-## Example
-```jsx
-<AvatarGroup
-  users={[
-    { name: 'Alice', image: '/alice.jpg', ring: 'lead' },
-    { name: 'Bob', ring: 'admin' },
-  ]}
-  max={3}
-  size="md"
-  borderColor="surface-base"
-  onOverflowClick={() => setShowAll(true)}
-/>
-```
-
-## 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`
-- Hover expand animation uses CSS `group-hover` — parent must not clip overflow
-- `borderColor` should match the surface the group sits on (`surface-base` on page bg, `surface-raised` on cards)
-- `renderAvatar` wrapper is positioning-only — pass `size` directly to your Avatar (do NOT use `className="h-full w-full"`)
-
-## Changes
-### v0.29.0
-- **Added** `indicator` prop on AvatarUser: `"lead"` (warning dot) | `"admin"` (accent dot) | ReactNode (custom indicator) — animated dot at the top-right corner of each avatar
-
-### v0.22.3
-- **Fixed** `renderAvatar` wrapper no longer clips consumer Avatar content (removed overflow-hidden, border, and size classes from wrapper)
-- **Fixed** Removed redundant text-size classes from wrapper — Avatar handles font scaling internally
-
-### v0.21.0
-- **Added** `xs` and `xl` size variants
-- **Added** `borderColor` prop for overlap border matching surface context
-- **Added** `onOverflowClick` prop making the overflow badge an interactive button
-- **Added** `renderAvatar` prop for custom per-avatar rendering
-- **Added** `AvatarUser.ring` field for per-user role rings in groups
-
-### v0.1.0
-- **Added** Initial release
+# AvatarGroup
+
+- Import: @devalok/shilp-sutra/composed/avatar-group
+- Server-safe: No
+- Category: composed
+
+## Props
+    users: AvatarUser[] (REQUIRED) — { name: string, image?: string | null, ring?: AvatarRing }
+    max: number (default: 4, overflow shows "+N" badge)
+    size: "xs" | "sm" | "md" | "lg" | "xl"
+    showTooltip: boolean (default: true)
+    borderColor: "surface-base" | "surface-raised" (default: "surface-raised") — overlap border color
+    onOverflowClick: () => void — makes the "+N" badge interactive (button)
+    renderAvatar: (user: AvatarUser, index: number) => ReactNode — custom avatar render
+    expandDirection: "left" | "right" (default: "right") — direction group expands on hover
+    expandAmount: "compact" | "default" | "wide" (default: "default") — how far group spreads
+
+## AvatarUser Type
+    name: string (REQUIRED)
+    image?: string | null
+    ring?: "none" | "lead" | "admin" | "client" — role ring per user in group
+    indicator?: "lead" | "admin" | ReactNode — small dot indicator at top-right of avatar
+
+## Defaults
+    size="md", max=4, showTooltip=true, borderColor="surface-raised", expandDirection="right", expandAmount="default"
+
+## Example
+```jsx
+<AvatarGroup
+  users={[
+    { name: 'Alice', image: '/alice.jpg', ring: 'lead' },
+    { name: 'Bob', ring: 'admin' },
+  ]}
+  max={3}
+  size="md"
+  borderColor="surface-base"
+  onOverflowClick={() => setShowAll(true)}
+/>
+```
+
+## 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`
+- Hover expand animation uses CSS `group-hover` — parent must not clip overflow
+- `borderColor` should match the surface the group sits on (`surface-base` on page bg, `surface-raised` on cards)
+- `renderAvatar` wrapper is positioning-only — pass `size` directly to your Avatar (do NOT use `className="h-full w-full"`)
+
+## Changes
+### v0.29.0
+- **Added** `indicator` prop on AvatarUser: `"lead"` (warning dot) | `"admin"` (accent dot) | ReactNode (custom indicator) — animated dot at the top-right corner of each avatar
+
+### v0.22.3
+- **Fixed** `renderAvatar` wrapper no longer clips consumer Avatar content (removed overflow-hidden, border, and size classes from wrapper)
+- **Fixed** Removed redundant text-size classes from wrapper — Avatar handles font scaling internally
+
+### v0.21.0
+- **Added** `xs` and `xl` size variants
+- **Added** `borderColor` prop for overlap border matching surface context
+- **Added** `onOverflowClick` prop making the overflow badge an interactive button
+- **Added** `renderAvatar` prop for custom per-avatar rendering
+- **Added** `AvatarUser.ring` field for per-user role rings in groups
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/bulk-action-bar.md

@@ -1,40 +1,40 @@
-# BulkActionBar
-
-- Import: @devalok/shilp-sutra/composed/bulk-action-bar
-- Server-safe: No
-- Category: composed
-
-## Props
-    show: boolean (controls visibility)
-    count: number (number of selected items — displayed in badge)
-    onClearSelection: () => void
-    actions: BulkActionBarAction[]
-    className: string
-
-### BulkActionBarAction
-    label: string
-    icon: ComponentType<{ className?: string }> (optional icon component)
-    onClick: () => void
-    color: "default" | "error"
-    disabled: boolean
-
-## Defaults
-    (no optional props with defaults)
-
-## Example
-```jsx
-<BulkActionBar
-  show={selected.length > 0}
-  count={selected.length}
-  onClearSelection={() => setSelected([])}
-  actions={[
-    { label: 'Archive', icon: IconArchive, onClick: archiveSelected },
-    { label: 'Delete', icon: IconTrash, onClick: deleteSelected, color: 'error' },
-  ]}
-/>
-```
-
-## Gotchas
-- Renders via `createPortal` into `document.body` — will not appear during SSR (mounts only client-side)
-- Positioned fixed at bottom-center with `z-50`; ensure no other fixed elements conflict
-- Uses Framer Motion AnimatePresence for slide-in/out animation
+# BulkActionBar
+
+- Import: @devalok/shilp-sutra/composed/bulk-action-bar
+- Server-safe: No
+- Category: composed
+
+## Props
+    show: boolean (controls visibility)
+    count: number (number of selected items — displayed in badge)
+    onClearSelection: () => void
+    actions: BulkActionBarAction[]
+    className: string
+
+### BulkActionBarAction
+    label: string
+    icon: ComponentType<{ className?: string }> (optional icon component)
+    onClick: () => void
+    color: "default" | "error"
+    disabled: boolean
+
+## Defaults
+    (no optional props with defaults)
+
+## Example
+```jsx
+<BulkActionBar
+  show={selected.length > 0}
+  count={selected.length}
+  onClearSelection={() => setSelected([])}
+  actions={[
+    { label: 'Archive', icon: IconArchive, onClick: archiveSelected },
+    { label: 'Delete', icon: IconTrash, onClick: deleteSelected, color: 'error' },
+  ]}
+/>
+```
+
+## Gotchas
+- Renders via `createPortal` into `document.body` — will not appear during SSR (mounts only client-side)
+- Positioned fixed at bottom-center with `z-50`; ensure no other fixed elements conflict
+- Uses Framer Motion AnimatePresence for slide-in/out animation

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

@@ -1,40 +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
+# 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

@@ -1,46 +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
+# 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

@@ -1,36 +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
+# 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