@devalok/shilp-sutra 0.34.1 → 0.36.0

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

@@ -1,35 +1,35 @@
-# MemberPicker
-
-- Import: @devalok/shilp-sutra/composed/member-picker
-- Server-safe: No
-- Category: composed
-
-## Props
-    members: MemberPickerMember[] (REQUIRED) — { id, name, avatar? }
-    selectedIds: string[] (REQUIRED)
-    onSelect: (memberId: string) => void (REQUIRED)
-    multiple: boolean (default: false)
-    placeholder: string (default: "Search members...")
-    children: ReactNode (trigger element)
-
-## Defaults
-    multiple=false, placeholder="Search members..."
-
-## Example
-```jsx
-<MemberPicker members={teamMembers} selectedIds={assignees} onSelect={toggleAssignee} multiple>
-  <Button variant="outline">Assign Members</Button>
-</MemberPicker>
-```
-
-## Gotchas
-- `children` is used as the trigger element (e.g., a Button)
-- `onSelect` is called with a single `memberId` — toggle logic is up to the consumer
-- When `multiple=false`, selecting a new member replaces the previous selection
-
-## Changes
-### v0.18.0
-- **Fixed** Added `aria-label` to search input
-
-### v0.1.0
-- **Added** Initial release
+# MemberPicker
+
+- Import: @devalok/shilp-sutra/composed/member-picker
+- Server-safe: No
+- Category: composed
+
+## Props
+    members: MemberPickerMember[] (REQUIRED) — { id, name, avatar? }
+    selectedIds: string[] (REQUIRED)
+    onSelect: (memberId: string) => void (REQUIRED)
+    multiple: boolean (default: false)
+    placeholder: string (default: "Search members...")
+    children: ReactNode (trigger element)
+
+## Defaults
+    multiple=false, placeholder="Search members..."
+
+## Example
+```jsx
+<MemberPicker members={teamMembers} selectedIds={assignees} onSelect={toggleAssignee} multiple>
+  <Button variant="outline">Assign Members</Button>
+</MemberPicker>
+```
+
+## Gotchas
+- `children` is used as the trigger element (e.g., a Button)
+- `onSelect` is called with a single `memberId` — toggle logic is up to the consumer
+- When `multiple=false`, selecting a new member replaces the previous selection
+
+## Changes
+### v0.18.0
+- **Fixed** Added `aria-label` to search input
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/multi-select-popover.md

@@ -1,62 +1,62 @@
-# MultiSelectPopover
-
-- Import: @devalok/shilp-sutra/composed/multi-select-popover
-- Server-safe: No
-- Category: composed
-
-## Props
-    items: MultiSelectItem[] (flat list — use `groups` for grouped rendering)
-    groups: MultiSelectGroup[] (grouped items with section headers)
-    value: string[] (currently selected item IDs)
-    onValueChange: (ids: string[]) => void
-    searchPlaceholder: string
-    onSearch: (query: string) => Promise<MultiSelectItem[]> (async search — replaces local filter)
-    searchDebounce: number (debounce for async search in ms)
-    renderItem: (item: MultiSelectItem, selected: boolean) => ReactNode (custom item renderer)
-    emptyMessage: string (message when no items match)
-    maxSelections: number (cap on selections)
-    align: "start" | "center" | "end"
-    width: string | number (popover width)
-    children: ReactNode (trigger element)
-
-### MultiSelectItem
-    id: string
-    label: string
-    image?: string
-    description?: string
-    disabled?: boolean
-
-### MultiSelectGroup
-    label: string
-    items: MultiSelectItem[]
-
-## Defaults
-    searchPlaceholder="Search...", searchDebounce={300}, emptyMessage="No results found", align="start", width={240}
-
-## Example
-```jsx
-<MultiSelectPopover
-  items={[
-    { id: '1', label: 'Alice', image: '/alice.jpg' },
-    { id: '2', label: 'Bob' },
-  ]}
-  value={selected}
-  onValueChange={setSelected}
->
-  <Button>Assign members</Button>
-</MultiSelectPopover>
-```
-
-## Gotchas
-- Supply either `items` (flat) or `groups` (sectioned), not both
-- When `onSearch` is provided, local filtering is disabled — the callback must return results
-- Search state resets when the popover closes
-- `maxSelections: 1` acts as single-select — clicking a new item replaces the current one
-
-## Changes
-
-### v0.27.2
-- **Fixed** `maxSelections` at limit now replaces oldest selection instead of blocking. Single-select (`maxSelections: 1`) swaps in the new value.
-
-### v0.26.0
-- **Added** Initial release
+# MultiSelectPopover
+
+- Import: @devalok/shilp-sutra/composed/multi-select-popover
+- Server-safe: No
+- Category: composed
+
+## Props
+    items: MultiSelectItem[] (flat list — use `groups` for grouped rendering)
+    groups: MultiSelectGroup[] (grouped items with section headers)
+    value: string[] (currently selected item IDs)
+    onValueChange: (ids: string[]) => void
+    searchPlaceholder: string
+    onSearch: (query: string) => Promise<MultiSelectItem[]> (async search — replaces local filter)
+    searchDebounce: number (debounce for async search in ms)
+    renderItem: (item: MultiSelectItem, selected: boolean) => ReactNode (custom item renderer)
+    emptyMessage: string (message when no items match)
+    maxSelections: number (cap on selections)
+    align: "start" | "center" | "end"
+    width: string | number (popover width)
+    children: ReactNode (trigger element)
+
+### MultiSelectItem
+    id: string
+    label: string
+    image?: string
+    description?: string
+    disabled?: boolean
+
+### MultiSelectGroup
+    label: string
+    items: MultiSelectItem[]
+
+## Defaults
+    searchPlaceholder="Search...", searchDebounce={300}, emptyMessage="No results found", align="start", width={240}
+
+## Example
+```jsx
+<MultiSelectPopover
+  items={[
+    { id: '1', label: 'Alice', image: '/alice.jpg' },
+    { id: '2', label: 'Bob' },
+  ]}
+  value={selected}
+  onValueChange={setSelected}
+>
+  <Button>Assign members</Button>
+</MultiSelectPopover>
+```
+
+## Gotchas
+- Supply either `items` (flat) or `groups` (sectioned), not both
+- When `onSearch` is provided, local filtering is disabled — the callback must return results
+- Search state resets when the popover closes
+- `maxSelections: 1` acts as single-select — clicking a new item replaces the current one
+
+## Changes
+
+### v0.27.2
+- **Fixed** `maxSelections` at limit now replaces oldest selection instead of blocking. Single-select (`maxSelections: 1`) swaps in the new value.
+
+### v0.26.0
+- **Added** Initial release

package/docs/components/composed/page-header.md

@@ -1,41 +1,41 @@
-# PageHeader
-
-- Import: @devalok/shilp-sutra/composed/page-header
-- Server-safe: Yes
-- Category: composed
-
-## Props
-    title: string (falls back to last breadcrumb label if omitted)
-    subtitle: string
-    actions: ReactNode (action buttons)
-    breadcrumbs: Breadcrumb[] — { label: string, href?: string }
-    titleClassName: string
-
-## Defaults
-    None
-
-## Example
-```jsx
-<PageHeader
-  title="Project Settings"
-  subtitle="Configure your project preferences"
-  breadcrumbs={[
-    { label: 'Home', href: '/' },
-    { label: 'Projects', href: '/projects' },
-    { label: 'Settings' },
-  ]}
-  actions={<Button>Save</Button>}
-/>
-```
-
-## Gotchas
-- Server-safe: can be imported directly in Next.js Server Components
-- If `title` is omitted, the last breadcrumb's `label` is used as the page title
-- The last breadcrumb should not have an `href` (it represents the current page)
-
-## Changes
-### v0.2.0
-- **Added** Identified as server-safe component
-
-### v0.1.0
-- **Added** Initial release
+# PageHeader
+
+- Import: @devalok/shilp-sutra/composed/page-header
+- Server-safe: Yes
+- Category: composed
+
+## Props
+    title: string (falls back to last breadcrumb label if omitted)
+    subtitle: string
+    actions: ReactNode (action buttons)
+    breadcrumbs: Breadcrumb[] — { label: string, href?: string }
+    titleClassName: string
+
+## Defaults
+    None
+
+## Example
+```jsx
+<PageHeader
+  title="Project Settings"
+  subtitle="Configure your project preferences"
+  breadcrumbs={[
+    { label: 'Home', href: '/' },
+    { label: 'Projects', href: '/projects' },
+    { label: 'Settings' },
+  ]}
+  actions={<Button>Save</Button>}
+/>
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- If `title` is omitted, the last breadcrumb's `label` is used as the page title
+- The last breadcrumb should not have an `href` (it represents the current page)
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/page-skeletons.md

@@ -1,32 +1,32 @@
-# PageSkeletons
-
-- Import: @devalok/shilp-sutra/composed/page-skeletons
-- Server-safe: Yes
-- Category: composed
-
-Exports: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton
-
-## Props
-    className?: string (plus all standard HTML div attributes via React.ComponentPropsWithoutRef<'div'>)
-
-## Defaults
-    None
-
-## Example
-```jsx
-<DashboardSkeleton />
-<ProjectListSkeleton />
-<TaskDetailSkeleton />
-```
-
-## Gotchas
-- Server-safe: can be imported directly in Next.js Server Components
-- These are full-page skeleton layouts — for smaller skeleton sections, use LoadingSkeleton components
-- Accept `className` and standard div attributes but render fixed layout structures
-
-## Changes
-### v0.2.0
-- **Added** Identified as server-safe component
-
-### v0.1.0
-- **Added** Initial release
+# PageSkeletons
+
+- Import: @devalok/shilp-sutra/composed/page-skeletons
+- Server-safe: Yes
+- Category: composed
+
+Exports: DashboardSkeleton, ProjectListSkeleton, TaskDetailSkeleton
+
+## Props
+    className?: string (plus all standard HTML div attributes via React.ComponentPropsWithoutRef<'div'>)
+
+## Defaults
+    None
+
+## Example
+```jsx
+<DashboardSkeleton />
+<ProjectListSkeleton />
+<TaskDetailSkeleton />
+```
+
+## Gotchas
+- Server-safe: can be imported directly in Next.js Server Components
+- These are full-page skeleton layouts — for smaller skeleton sections, use LoadingSkeleton components
+- Accept `className` and standard div attributes but render fixed layout structures
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/priority-indicator.md

@@ -1,32 +1,32 @@
-# PriorityIndicator
-
-- Import: @devalok/shilp-sutra/composed/priority-indicator
-- Server-safe: Yes
-- Category: composed
-
-## Props
-    priority: Priority
-    display: "compact" | "full" (default: "full")
-
-Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'urgent'
-
-## Defaults
-    display="full"
-
-## Example
-```jsx
-<PriorityIndicator priority="HIGH" />
-<PriorityIndicator priority="low" display="compact" />
-```
-
-## Gotchas
-- Case-insensitive — "low" and "LOW" both work
-- Server-safe: can be imported directly in Next.js Server Components
-- `compact` display shows only the icon; `full` shows icon + text label
-
-## Changes
-### v0.2.0
-- **Added** Identified as server-safe component
-
-### v0.1.0
-- **Added** Initial release
+# PriorityIndicator
+
+- Import: @devalok/shilp-sutra/composed/priority-indicator
+- Server-safe: Yes
+- Category: composed
+
+## Props
+    priority: Priority
+    display: "compact" | "full" (default: "full")
+
+Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT' | 'low' | 'medium' | 'high' | 'urgent'
+
+## Defaults
+    display="full"
+
+## Example
+```jsx
+<PriorityIndicator priority="HIGH" />
+<PriorityIndicator priority="low" display="compact" />
+```
+
+## Gotchas
+- Case-insensitive — "low" and "LOW" both work
+- Server-safe: can be imported directly in Next.js Server Components
+- `compact` display shows only the icon; `full` shows icon + text label
+
+## Changes
+### v0.2.0
+- **Added** Identified as server-safe component
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/responsive-overlay.md

@@ -1,34 +1,34 @@
-# ResponsiveOverlay
-
-- Import: @devalok/shilp-sutra/composed/responsive-overlay
-- Server-safe: No
-- Category: composed
-
-## Props
-    open: boolean
-    onOpenChange: (open: boolean) => void
-    title: string
-    description: string
-    breakpoint: "sm" | "md" (below this renders as bottom Sheet; above as Dialog)
-    children: ReactNode
-    className: string
-
-## Defaults
-    breakpoint="md"
-
-## Example
-```jsx
-<ResponsiveOverlay
-  open={open}
-  onOpenChange={setOpen}
-  title="Edit task"
-  description="Update the task details"
->
-  <TaskForm />
-</ResponsiveOverlay>
-```
-
-## Gotchas
-- Renders a centered Dialog on desktop and a bottom Sheet on mobile — same content, different container
-- Uses `window.matchMedia` internally — SSR defaults to desktop (Dialog) until hydration
-- Title and description are optional; if omitted, no header is rendered in either mode
+# ResponsiveOverlay
+
+- Import: @devalok/shilp-sutra/composed/responsive-overlay
+- Server-safe: No
+- Category: composed
+
+## Props
+    open: boolean
+    onOpenChange: (open: boolean) => void
+    title: string
+    description: string
+    breakpoint: "sm" | "md" (below this renders as bottom Sheet; above as Dialog)
+    children: ReactNode
+    className: string
+
+## Defaults
+    breakpoint="md"
+
+## Example
+```jsx
+<ResponsiveOverlay
+  open={open}
+  onOpenChange={setOpen}
+  title="Edit task"
+  description="Update the task details"
+>
+  <TaskForm />
+</ResponsiveOverlay>
+```
+
+## Gotchas
+- Renders a centered Dialog on desktop and a bottom Sheet on mobile — same content, different container
+- Uses `window.matchMedia` internally — SSR defaults to desktop (Dialog) until hydration
+- Title and description are optional; if omitted, no header is rendered in either mode

package/docs/components/composed/rich-text-editor.md

@@ -1,82 +1,82 @@
-# RichTextEditor
-
-- Import: @devalok/shilp-sutra/composed/rich-text-editor
-- Server-safe: No
-- Category: composed
-
-Exports: RichTextEditor, RichTextViewer
-
-## Props
-
-### RichTextEditor
-    content: string (HTML string)
-    placeholder: string (default: "Start writing...")
-    onChange: (html: string) => void
-    className: string
-    editable: boolean (default: true)
-    onImageUpload?: (file: File) => Promise<string> — return URL. If omitted, images paste as base64
-    onFileUpload?: (file: File) => Promise<{ url: string; name: string; size: number }> — enables file attachments
-    mentions?: MentionItem[] — static list for @mention autocomplete
-    onMentionSearch?: (query: string) => Promise<MentionItem[]> — async search, takes precedence over static mentions
-    toolbar?: ToolbarItem[] — whitelist of toolbar items to show. Omit to show all.
-    onMentionSelect?: (item: MentionItem) => void — called when a mention is selected
-
-ToolbarItem: 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'h2' | 'h3' | 'blockquote' | 'bulletList' | 'orderedList' | 'taskList' | 'codeBlock' | 'link' | 'image' | 'file' | 'hr' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'emoji' | 'undo' | 'redo'
-
-MentionItem: { id: string; label: string; avatar?: string }
-
-### RichTextViewer
-    content: string (REQUIRED, HTML string)
-    className: string
-
-## Defaults
-    RichTextEditor: placeholder="Start writing...", editable=true
-
-## Example
-```jsx
-<RichTextEditor content={html} onChange={setHtml} placeholder="Write your message..." />
-
-<RichTextEditor
-  content={html}
-  onChange={setHtml}
-  mentions={[{ id: '1', label: 'Aarav' }]}
-  onImageUpload={async (file) => uploadAndReturnUrl(file)}
-  onFileUpload={async (file) => ({ url: uploadUrl, name: file.name, size: file.size })}
-/>
-
-<RichTextViewer content={savedHtml} />
-```
-
-## Gotchas
-- Tiptap is bundled — no need to install `@tiptap/*` packages separately
-- Emoji picker requires `@emoji-mart/react` + `@emoji-mart/data` peers
-- Images without `onImageUpload` are stored as base64 in HTML — large images bloat content
-- Mention rendering in viewer always works (no mention props needed, just the HTML)
-- Features: bold, italic, underline, strikethrough, highlight, headings, blockquote, lists, task lists, code, links, images, file attachments, mentions, emoji, text alignment, horizontal rule
-
-## Changes
-### v0.33.0
-- **Added** `emojiSet` prop — `EmojiSet` type for consistent emoji art style rendering
-- **Changed** TipTap v2 → v3 upgrade (useEditorState, immediatelyRender: false for SSR, ListKit)
-- **Added** EmojiNode + createEmojiSuggestion(set) registered internally
-
-### v0.30.0
-- **Added** `toolbar` prop — whitelist of `ToolbarItem` names to control which toolbar buttons appear. Dividers render only between groups that have visible items. `ToolbarItem` type exported from barrel.
-
-### v0.18.0
-- **Fixed** Use ref to track internal changes, prevent update loop
-
-### v0.9.0
-- **Changed** All `@tiptap/*` packages moved from peerDependencies to bundled build-time dependencies — consumers no longer need to install tiptap separately
-
-### v0.8.0
-- **Fixed** Emoji picker now renders above the editor (not clipped by overflow)
-- **Fixed** Link/image URL injection prevented via protocol validation
-- **Fixed** Escape key in emoji picker no longer closes parent dialogs
-- **Fixed** Tiptap peer deps tightened to `>=2.27.2 <3.0.0`
-
-### v0.7.0
-- **Added** Initial release — full-featured tiptap-based rich text editing with toolbar, mentions, emoji, image, alignment
-
-### v0.1.1
-- **Fixed** Added content sync effect so editor updates when `content` prop changes externally
+# RichTextEditor
+
+- Import: @devalok/shilp-sutra/composed/rich-text-editor
+- Server-safe: No
+- Category: composed
+
+Exports: RichTextEditor, RichTextViewer
+
+## Props
+
+### RichTextEditor
+    content: string (HTML string)
+    placeholder: string (default: "Start writing...")
+    onChange: (html: string) => void
+    className: string
+    editable: boolean (default: true)
+    onImageUpload?: (file: File) => Promise<string> — return URL. If omitted, images paste as base64
+    onFileUpload?: (file: File) => Promise<{ url: string; name: string; size: number }> — enables file attachments
+    mentions?: MentionItem[] — static list for @mention autocomplete
+    onMentionSearch?: (query: string) => Promise<MentionItem[]> — async search, takes precedence over static mentions
+    toolbar?: ToolbarItem[] — whitelist of toolbar items to show. Omit to show all.
+    onMentionSelect?: (item: MentionItem) => void — called when a mention is selected
+
+ToolbarItem: 'bold' | 'italic' | 'underline' | 'strike' | 'highlight' | 'h2' | 'h3' | 'blockquote' | 'bulletList' | 'orderedList' | 'taskList' | 'codeBlock' | 'link' | 'image' | 'file' | 'hr' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'emoji' | 'undo' | 'redo'
+
+MentionItem: { id: string; label: string; avatar?: string }
+
+### RichTextViewer
+    content: string (REQUIRED, HTML string)
+    className: string
+
+## Defaults
+    RichTextEditor: placeholder="Start writing...", editable=true
+
+## Example
+```jsx
+<RichTextEditor content={html} onChange={setHtml} placeholder="Write your message..." />
+
+<RichTextEditor
+  content={html}
+  onChange={setHtml}
+  mentions={[{ id: '1', label: 'Aarav' }]}
+  onImageUpload={async (file) => uploadAndReturnUrl(file)}
+  onFileUpload={async (file) => ({ url: uploadUrl, name: file.name, size: file.size })}
+/>
+
+<RichTextViewer content={savedHtml} />
+```
+
+## Gotchas
+- Tiptap is bundled — no need to install `@tiptap/*` packages separately
+- Emoji picker requires `@emoji-mart/react` + `@emoji-mart/data` peers
+- Images without `onImageUpload` are stored as base64 in HTML — large images bloat content
+- Mention rendering in viewer always works (no mention props needed, just the HTML)
+- Features: bold, italic, underline, strikethrough, highlight, headings, blockquote, lists, task lists, code, links, images, file attachments, mentions, emoji, text alignment, horizontal rule
+
+## Changes
+### v0.33.0
+- **Added** `emojiSet` prop — `EmojiSet` type for consistent emoji art style rendering
+- **Changed** TipTap v2 → v3 upgrade (useEditorState, immediatelyRender: false for SSR, ListKit)
+- **Added** EmojiNode + createEmojiSuggestion(set) registered internally
+
+### v0.30.0
+- **Added** `toolbar` prop — whitelist of `ToolbarItem` names to control which toolbar buttons appear. Dividers render only between groups that have visible items. `ToolbarItem` type exported from barrel.
+
+### v0.18.0
+- **Fixed** Use ref to track internal changes, prevent update loop
+
+### v0.9.0
+- **Changed** All `@tiptap/*` packages moved from peerDependencies to bundled build-time dependencies — consumers no longer need to install tiptap separately
+
+### v0.8.0
+- **Fixed** Emoji picker now renders above the editor (not clipped by overflow)
+- **Fixed** Link/image URL injection prevented via protocol validation
+- **Fixed** Escape key in emoji picker no longer closes parent dialogs
+- **Fixed** Tiptap peer deps tightened to `>=2.27.2 <3.0.0`
+
+### v0.7.0
+- **Added** Initial release — full-featured tiptap-based rich text editing with toolbar, mentions, emoji, image, alignment
+
+### v0.1.1
+- **Fixed** Added content sync effect so editor updates when `content` prop changes externally