@devalok/shilp-sutra 0.18.0 → 0.18.2

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

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +1,71 @@
+# 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
+    onMentionSelect?: (item: MentionItem) => void — called when a mention is selected
+
+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.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

@@ -0,0 +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

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

@@ -0,0 +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

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

@@ -0,0 +1,41 @@
+# 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" | "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)
+
+## Defaults
+    size="md", hideDot=false
+
+## Example
+```jsx
+<StatusBadge status="active" />
+<StatusBadge color="warning" label="In Review" size="sm" />
+```
+
+## 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)
+
+## Changes
+### 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

@@ -0,0 +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