@devalok/shilp-sutra 0.34.0 → 0.36.0

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

package/docs/components/composed/schedule-view.md

@@ -1,39 +1,39 @@
-# ScheduleView
-
-- Import: @devalok/shilp-sutra/composed/schedule-view
-- Server-safe: No
-- Category: composed
-
-## Props
-    view: "day" | "week" (REQUIRED)
-    date: Date (REQUIRED — current day or any date in target week)
-    events: ScheduleEvent[] (REQUIRED) — { id, title, start: Date, end: Date, color? }
-    onEventClick?: (event: ScheduleEvent) => void
-    onSlotClick?: (start: Date, end: Date) => void
-    startHour: number (default: 8)
-    endHour: number (default: 18, exclusive)
-    slotDuration: number (minutes, default: 30)
-
-Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
-
-## Defaults
-    startHour=8, endHour=18, slotDuration=30
-
-## Example
-```jsx
-<ScheduleView
-  view="week"
-  date={new Date()}
-  events={calendarEvents}
-  onEventClick={(e) => openEvent(e.id)}
-/>
-```
-
-## Gotchas
-- `endHour` is exclusive — `endHour=18` means the last visible slot starts at 17:30 (with default 30min slots)
-- `onSlotClick` fires when clicking an empty time slot — useful for creating new events
-- Events that span outside `startHour`/`endHour` may be clipped
-
-## Changes
-### v0.1.0
-- **Added** Initial release
+# ScheduleView
+
+- Import: @devalok/shilp-sutra/composed/schedule-view
+- Server-safe: No
+- Category: composed
+
+## Props
+    view: "day" | "week" (REQUIRED)
+    date: Date (REQUIRED — current day or any date in target week)
+    events: ScheduleEvent[] (REQUIRED) — { id, title, start: Date, end: Date, color? }
+    onEventClick?: (event: ScheduleEvent) => void
+    onSlotClick?: (start: Date, end: Date) => void
+    startHour: number (default: 8)
+    endHour: number (default: 18, exclusive)
+    slotDuration: number (minutes, default: 30)
+
+Event colors: "primary" | "success" | "warning" | "error" | "info" | "neutral"
+
+## Defaults
+    startHour=8, endHour=18, slotDuration=30
+
+## Example
+```jsx
+<ScheduleView
+  view="week"
+  date={new Date()}
+  events={calendarEvents}
+  onEventClick={(e) => openEvent(e.id)}
+/>
+```
+
+## Gotchas
+- `endHour` is exclusive — `endHour=18` means the last visible slot starts at 17:30 (with default 30min slots)
+- `onSlotClick` fires when clicking an empty time slot — useful for creating new events
+- Events that span outside `startHour`/`endHour` may be clipped
+
+## Changes
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/simple-tooltip.md

@@ -1,33 +1,33 @@
-# SimpleTooltip
-
-- Import: @devalok/shilp-sutra/composed/simple-tooltip
-- Server-safe: No
-- Category: composed
-
-## Props
-    content: ReactNode (REQUIRED — tooltip content)
-    side: "top" | "right" | "bottom" | "left" (default: "top")
-    align: "start" | "center" | "end" (default: "center")
-    delayDuration: number (ms, default: 300)
-    children: ReactNode (trigger element)
-
-## Defaults
-    side="top", align="center", delayDuration=300
-
-## Example
-```jsx
-<SimpleTooltip content="Edit this item">
-  <IconButton icon={<IconEdit />} aria-label="Edit" />
-</SimpleTooltip>
-```
-
-## Gotchas
-- Wraps the full Tooltip compound (Provider + Tooltip + Trigger + Content) into one component — no need for TooltipProvider
-- Unlike the low-level Tooltip, SimpleTooltip does not require wrapping in a TooltipProvider
-
-## Changes
-### v0.18.0
-- **Fixed** Type definition corrected
-
-### v0.1.0
-- **Added** Initial release
+# SimpleTooltip
+
+- Import: @devalok/shilp-sutra/composed/simple-tooltip
+- Server-safe: No
+- Category: composed
+
+## Props
+    content: ReactNode (REQUIRED — tooltip content)
+    side: "top" | "right" | "bottom" | "left" (default: "top")
+    align: "start" | "center" | "end" (default: "center")
+    delayDuration: number (ms, default: 300)
+    children: ReactNode (trigger element)
+
+## Defaults
+    side="top", align="center", delayDuration=300
+
+## Example
+```jsx
+<SimpleTooltip content="Edit this item">
+  <IconButton icon={<IconEdit />} aria-label="Edit" />
+</SimpleTooltip>
+```
+
+## Gotchas
+- Wraps the full Tooltip compound (Provider + Tooltip + Trigger + Content) into one component — no need for TooltipProvider
+- Unlike the low-level Tooltip, SimpleTooltip does not require wrapping in a TooltipProvider
+
+## Changes
+### v0.18.0
+- **Fixed** Type definition corrected
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/composed/status-badge.md

@@ -1,55 +1,55 @@
-# StatusBadge
-
-- Import: @devalok/shilp-sutra/composed/status-badge
-- Server-safe: No
-- Category: composed
-
-Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe due to Framer Motion dependency.
-
-## Props
-    status: "active" | "pending" | "approved" | "rejected" | "completed" | "blocked" | "in-progress" | "review" | "cancelled" | "draft"
-    color: "success" | "warning" | "error" | "info" | "neutral" (overrides status styling when set)
-    size: "sm" | "md"
-    label: string (auto-derived from status/color if omitted)
-    hideDot: boolean (default: false)
-    onClick: () => void (makes badge clickable — renders as button with chevron)
-    icon: ReactNode (custom trailing icon — replaces default chevron when clickable)
-
-## Defaults
-    size="md", hideDot=false
-    When neither status nor color is passed, defaults to status='pending' styling
-
-## Example
-```jsx
-<StatusBadge status="active" />
-<StatusBadge status="in-progress" />
-<StatusBadge status="review" label="Needs Review" />
-<StatusBadge color="warning" label="In Review" size="sm" />
-<StatusBadge status="active" onClick={() => openStatusPicker()} />
-```
-
-## Gotchas
-- When `color` is set, it takes priority over `status` for styling
-- Props use a discriminated union — pass either `status` or `color`, not both
-- As of v0.18.0, StatusBadge is NOT server-safe (Framer Motion dependency)
-- When `onClick` is provided, badge renders as a `<button>` with a trailing chevron icon
-- Pass `icon` to replace the default chevron with a custom trailing icon
-
-## Changes
-### v0.29.0
-- **Added** `in-progress` status (accent/blue styling)
-- **Added** `review` status (info styling)
-- **Added** `onClick` prop — renders as a `<button>` with trailing chevron and hover opacity
-- **Added** `icon` prop — custom trailing icon (replaces the default chevron when clickable)
-
-### v0.18.0
-- **Changed** No longer server-safe due to Framer Motion dependency
-
-### v0.8.0
-- **Changed** Props now use discriminated union — pass either `status` or `color`, not both
-
-### v0.2.0
-- **Added** Identified as server-safe component (later reverted in v0.18.0)
-
-### v0.1.0
-- **Added** Initial release
+# StatusBadge
+
+- Import: @devalok/shilp-sutra/composed/status-badge
+- Server-safe: No
+- Category: composed
+
+Note: StatusBadge was server-safe prior to v0.18.0 but is NO LONGER server-safe due to Framer Motion dependency.
+
+## Props
+    status: "active" | "pending" | "approved" | "rejected" | "completed" | "blocked" | "in-progress" | "review" | "cancelled" | "draft"
+    color: "success" | "warning" | "error" | "info" | "neutral" (overrides status styling when set)
+    size: "sm" | "md"
+    label: string (auto-derived from status/color if omitted)
+    hideDot: boolean (default: false)
+    onClick: () => void (makes badge clickable — renders as button with chevron)
+    icon: ReactNode (custom trailing icon — replaces default chevron when clickable)
+
+## Defaults
+    size="md", hideDot=false
+    When neither status nor color is passed, defaults to status='pending' styling
+
+## Example
+```jsx
+<StatusBadge status="active" />
+<StatusBadge status="in-progress" />
+<StatusBadge status="review" label="Needs Review" />
+<StatusBadge color="warning" label="In Review" size="sm" />
+<StatusBadge status="active" onClick={() => openStatusPicker()} />
+```
+
+## Gotchas
+- When `color` is set, it takes priority over `status` for styling
+- Props use a discriminated union — pass either `status` or `color`, not both
+- As of v0.18.0, StatusBadge is NOT server-safe (Framer Motion dependency)
+- When `onClick` is provided, badge renders as a `<button>` with a trailing chevron icon
+- Pass `icon` to replace the default chevron with a custom trailing icon
+
+## Changes
+### v0.29.0
+- **Added** `in-progress` status (accent/blue styling)
+- **Added** `review` status (info styling)
+- **Added** `onClick` prop — renders as a `<button>` with trailing chevron and hover opacity
+- **Added** `icon` prop — custom trailing icon (replaces the default chevron when clickable)
+
+### v0.18.0
+- **Changed** No longer server-safe due to Framer Motion dependency
+
+### v0.8.0
+- **Changed** Props now use discriminated union — pass either `status` or `color`, not both
+
+### v0.2.0
+- **Added** Identified as server-safe component (later reverted in v0.18.0)
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/shell/app-command-palette.md

@@ -1,44 +1,44 @@
-# AppCommandPalette
-
-- Import: @devalok/shilp-sutra/shell/app-command-palette
-- Server-safe: No
-- Category: shell
-
-## Props
-    user?: AppCommandPaletteUser | null — { name, role? } (optional)
-    isAdmin?: boolean (shows admin command groups regardless of user.role; takes precedence over role-based detection)
-    extraGroups?: CommandGroup[]
-    onNavigate?: (path: string) => void
-    onSearch?: (query: string) => void
-    searchResults?: SearchResult[]
-    isSearching?: boolean (shows loading state while search is in progress)
-    onSearchResultSelect?: (result: SearchResult) => void
-
-SearchResult: { id: string, title: string, snippet?: string, entityType: string, projectId?: string | null, metadata?: Record<string, unknown> }
-AppCommandPaletteUser: { name: string, role?: string }
-
-## Defaults
-    None
-
-## Example
-```jsx
-<AppCommandPalette
-  user={{ name: 'John', role: 'admin' }}
-  isAdmin={true}
-  onNavigate={(path) => router.push(path)}
-  searchResults={results}
-  onSearchResultSelect={(r) => router.push(`/${r.entityType}/${r.id}`)}
-/>
-```
-
-## Gotchas
-- Uses CommandRegistry context for page navigation items (see CommandRegistryProvider)
-- `isAdmin` takes precedence over `user.role` for showing admin command groups
-- Should be placed at the app root level, typically alongside TopBar
-
-## Changes
-### v0.3.0
-- **Fixed** Added missing `'use client'` directive
-
-### v0.1.0
-- **Added** Initial release
+# AppCommandPalette
+
+- Import: @devalok/shilp-sutra/shell/app-command-palette
+- Server-safe: No
+- Category: shell
+
+## Props
+    user?: AppCommandPaletteUser | null — { name, role? } (optional)
+    isAdmin?: boolean (shows admin command groups regardless of user.role; takes precedence over role-based detection)
+    extraGroups?: CommandGroup[]
+    onNavigate?: (path: string) => void
+    onSearch?: (query: string) => void
+    searchResults?: SearchResult[]
+    isSearching?: boolean (shows loading state while search is in progress)
+    onSearchResultSelect?: (result: SearchResult) => void
+
+SearchResult: { id: string, title: string, snippet?: string, entityType: string, projectId?: string | null, metadata?: Record<string, unknown> }
+AppCommandPaletteUser: { name: string, role?: string }
+
+## Defaults
+    None
+
+## Example
+```jsx
+<AppCommandPalette
+  user={{ name: 'John', role: 'admin' }}
+  isAdmin={true}
+  onNavigate={(path) => router.push(path)}
+  searchResults={results}
+  onSearchResultSelect={(r) => router.push(`/${r.entityType}/${r.id}`)}
+/>
+```
+
+## Gotchas
+- Uses CommandRegistry context for page navigation items (see CommandRegistryProvider)
+- `isAdmin` takes precedence over `user.role` for showing admin command groups
+- Should be placed at the app root level, typically alongside TopBar
+
+## Changes
+### v0.3.0
+- **Fixed** Added missing `'use client'` directive
+
+### v0.1.0
+- **Added** Initial release

package/docs/components/shell/bottom-navbar.md

@@ -1,52 +1,52 @@
-# BottomNavbar
-
-- Import: @devalok/shilp-sutra/shell/bottom-navbar
-- Server-safe: No
-- Category: shell
-
-## Props
-    currentPath?: string (optional)
-    user?: BottomNavbarUser | null (optional)
-    primaryItems?: BottomNavItem[] (max 4 recommended, optional)
-    moreItems?: BottomNavItem[] (overflow items in "More" menu, optional)
-    className?: string
-
-BottomNavItem: { title: string, href: string, icon: ReactNode, exact?: boolean, badge?: number }
-BottomNavbarUser: { name: string, role?: string }
-
-## Defaults
-    None
-
-## Example
-```jsx
-<BottomNavbar
-  currentPath="/dashboard"
-  primaryItems={[
-    { title: 'Home', href: '/', icon: <IconHome /> },
-    { title: 'Tasks', href: '/tasks', icon: <IconChecklist /> },
-  ]}
-/>
-```
-
-## Gotchas
-- Designed for mobile viewports — fixed to bottom of screen
-- Max 4 `primaryItems` recommended; overflow goes in `moreItems` shown in a "More" sheet
-- Use with `useIsMobile()` hook to conditionally render instead of AppSidebar
-- Requires LinkProvider for framework-specific link components (e.g., Next.js Link)
-
-## Changes
-### v0.19.0
-- **Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background
-- **Changed** "More" menu and interactive items bumped accordingly
-
-### v0.18.0
-- **Fixed** Removed incorrect `role="button"` and `tabIndex` from overlay
-
-### v0.16.0
-- **Added** `badge?: number` on `BottomNavItem` — notification count badge (red dot, 99+ cap)
-
-### v0.1.1
-- **Changed** Decoupled from Next.js via LinkProvider
-
-### v0.1.0
-- **Added** Initial release
+# BottomNavbar
+
+- Import: @devalok/shilp-sutra/shell/bottom-navbar
+- Server-safe: No
+- Category: shell
+
+## Props
+    currentPath?: string (optional)
+    user?: BottomNavbarUser | null (optional)
+    primaryItems?: BottomNavItem[] (max 4 recommended, optional)
+    moreItems?: BottomNavItem[] (overflow items in "More" menu, optional)
+    className?: string
+
+BottomNavItem: { title: string, href: string, icon: ReactNode, exact?: boolean, badge?: number }
+BottomNavbarUser: { name: string, role?: string }
+
+## Defaults
+    None
+
+## Example
+```jsx
+<BottomNavbar
+  currentPath="/dashboard"
+  primaryItems={[
+    { title: 'Home', href: '/', icon: <IconHome /> },
+    { title: 'Tasks', href: '/tasks', icon: <IconChecklist /> },
+  ]}
+/>
+```
+
+## Gotchas
+- Designed for mobile viewports — fixed to bottom of screen
+- Max 4 `primaryItems` recommended; overflow goes in `moreItems` shown in a "More" sheet
+- Use with `useIsMobile()` hook to conditionally render instead of AppSidebar
+- Requires LinkProvider for framework-specific link components (e.g., Next.js Link)
+
+## Changes
+### v0.19.0
+- **Changed** Background elevated from `bg-surface-1` to `bg-surface-2` for visual hierarchy above app background
+- **Changed** "More" menu and interactive items bumped accordingly
+
+### v0.18.0
+- **Fixed** Removed incorrect `role="button"` and `tabIndex` from overlay
+
+### v0.16.0
+- **Added** `badge?: number` on `BottomNavItem` — notification count badge (red dot, 99+ cap)
+
+### v0.1.1
+- **Changed** Decoupled from Next.js via LinkProvider
+
+### v0.1.0
+- **Added** Initial release