@devalok/shilp-sutra-karm 0.18.0 → 0.19.0

package/docs/components/other/karm-command-registry.md

@@ -0,0 +1,61 @@
+# karmCommandRegistry
+
+- Import: @devalok/shilp-sutra-karm (top-level export)
+- Server-safe: No
+- Category: shell
+
+Pre-configured command registry for the Karm app's AppCommandPalette. Contains all page routes and admin routes.
+
+Exports: karmCommandRegistry
+
+## Type
+```ts
+const karmCommandRegistry: CommandRegistry
+```
+
+Where `CommandRegistry` is `{ pages: CommandPageItem[], adminPages: CommandPageItem[] }` from `@devalok/shilp-sutra/shell/command-registry`.
+
+## Pages
+| id | label | path | keywords |
+|----|-------|------|----------|
+| nav-dashboard | Dashboard | / | home |
+| nav-attendance | Attendance | /attendance | clock, time |
+| nav-breaks | Breaks | /breaks | leave, vacation |
+| nav-projects | Projects | /projects | board, kanban |
+| nav-my-tasks | My Tasks | /my-tasks | todo |
+| nav-devsabha | Devsabha | /devsabha | standup, meeting |
+| nav-adjustments | Adjustments | /adjustments | corrections |
+| nav-profile | Profile | /profile | account, settings |
+
+## Admin Pages
+| id | label | path | keywords |
+|----|-------|------|----------|
+| nav-admin-dashboard | Admin Dashboard | /admin | admin, overview |
+| nav-admin-breaks | Manage Breaks | /admin/breaks | admin, leave |
+| nav-admin-attendance | Manage Attendance | /admin/attendance | admin, time |
+| nav-admin-lokwasi | Lokwasi | /admin/lokwasi | admin, onboarding |
+| nav-admin-onboarding | Onboarding | /admin/onboarding | admin, new hire |
+| nav-admin-config | System Config | /admin/system-config | admin, settings, configuration |
+
+## Example
+```jsx
+import { CommandRegistryProvider } from '@devalok/shilp-sutra/shell/command-registry'
+import { karmCommandRegistry } from '@devalok/shilp-sutra-karm'
+
+<CommandRegistryProvider registry={karmCommandRegistry}>
+  <AppCommandPalette
+    user={user}
+    onNavigate={(path) => router.push(path)}
+  />
+</CommandRegistryProvider>
+```
+
+## Gotchas
+- Each entry includes a Tabler icon (e.g. `IconLayoutDashboard`, `IconUmbrella`) — these are bundled, not tree-shaken
+- The registry is a plain object, not a React component — pass it to `CommandRegistryProvider`
+- Admin pages are only shown in the command palette when the user has admin role (handled by AppCommandPalette)
+- To add new routes, extend the registry object in your app rather than modifying this export
+
+## Changes
+### v0.9.0
+- **Added** Initial release with 8 pages and 6 admin pages

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

@@ -0,0 +1,52 @@
+# Page Skeletons (Karm)
+
+- Import: @devalok/shilp-sutra-karm
+- Server-safe: No
+- Category: other
+
+Domain-specific loading skeleton components for Karm pages.
+
+Exports: DevsabhaSkeleton, BandwidthSkeleton
+
+## Props
+
+### DevsabhaSkeleton
+    ...HTMLDivElement attributes (className, etc.)
+
+Renders a 5-section skeleton grid mimicking the Devsabha (standup) page layout:
+1. Main large card (lg:col-span-2) with 4 rows
+2. Side card with 3 avatar rows
+3. Full-width card (lg:col-span-3) with 3 sub-cards
+4. Stats row (lg:col-span-2) with 4 stat blocks
+5. Timeline card with 3 entries
+
+### BandwidthSkeleton
+    ...HTMLDivElement attributes (className, etc.)
+
+Renders a skeleton mimicking the Bandwidth page layout:
+1. 3 summary cards (sm:grid-cols-3) with progress bars
+2. Table with 5-column header and 6 rows with avatar + name
+
+## Defaults
+    None
+
+## Example
+```jsx
+import { DevsabhaSkeleton, BandwidthSkeleton } from '@devalok/shilp-sutra-karm'
+
+// Use while data loads
+if (isLoading) return <DevsabhaSkeleton />
+
+// Bandwidth page loading
+if (isLoading) return <BandwidthSkeleton className="p-6" />
+```
+
+## Gotchas
+- These are top-level exports from the karm package, not from the admin sub-path
+- Both use the core `Skeleton` component internally
+- Layout uses `gap-ds-06` spacing and `rounded-ds-xl` border radius
+- Pass `className` to customize outer container styles
+
+## Changes
+### v0.9.0
+- **Added** Initial release

package/docs/components/tasks/activity-tab.md

@@ -0,0 +1,45 @@
+# ActivityTab
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    activities: AuditLogEntry[] (REQUIRED)
+    ...HTMLAttributes<HTMLDivElement>
+
+## AuditLogEntry Shape
+    id: string
+    timestamp: string
+    actorType: 'USER' | 'CLIENT' | 'SYSTEM' | 'AGENT'
+    actorId: string | null
+    action: string
+    entityType: string
+    entityId: string
+    projectId: string | null
+    metadata: Record<string, unknown> | null
+
+## Supported Actions
+    task.created, task.updated, task.moved, task.assigned, task.unassigned,
+    task.commented, task.file_uploaded, task.review_requested, task.review_completed,
+    task.visibility_changed, task.priority_changed, task.labels_changed, task.due_date_changed
+
+## Example
+```jsx
+<ActivityTab activities={auditLogEntries} />
+```
+
+## Gotchas
+- Renders a vertical timeline with colored dots and icons per action type.
+- Unknown actions fall back to a generic icon and use entry.action as the description.
+- Actor name is derived from metadata.actorName, falling back to "System", "AI Agent", or "Someone".
+- Empty state uses EmptyState component: "No activity yet".
+- Forwards ref to outer div.
+
+## Changes
+### v0.19.0
+- **Added** Decomposed into composable pieces: `ActivityTimeline`, `ActivityEntry` — importable from `@devalok/shilp-sutra-karm/tasks`
+- ActivityTab remains as a pre-assembled default; use the pieces for custom layouts
+
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/conversation-tab.md

@@ -0,0 +1,56 @@
+# ConversationTab
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    comments: Comment[] (REQUIRED)
+    taskVisibility: 'INTERNAL' | 'EVERYONE' (REQUIRED)
+    onPostComment: (content: string, authorType: 'INTERNAL' | 'CLIENT') => void (REQUIRED)
+    clientMode: boolean (default: false)
+    richText: boolean (default: true) — enable built-in RichTextEditor/Viewer
+    renderEditor: (props: { content: string; onChange: (content: string) => void; placeholder: string }) => ReactNode
+    renderViewer: (props: { content: string; className?: string }) => ReactNode
+    ...HTMLAttributes<HTMLDivElement>
+
+## Comment Shape
+    id: string
+    taskId: string
+    authorType: 'INTERNAL' | 'CLIENT'
+    authorId: string
+    content: string
+    createdAt: string
+    updatedAt: string
+    internalAuthor: { id: string; name: string; email?: string; image?: string | null } | null (optional)
+    clientAuthor: { id: string; name: string; email: string } | null (optional)
+
+## Defaults
+    clientMode=false, richText=true
+
+## Example
+```jsx
+<ConversationTab
+  comments={task.comments}
+  taskVisibility={task.visibility}
+  onPostComment={(content, type) => postComment(content, type)}
+/>
+```
+
+## Gotchas
+- In clientMode, comments are posted with authorType='CLIENT'. In staff mode, authorType='INTERNAL'.
+- When taskVisibility='EVERYONE' and not clientMode, a warning is shown: "Comments may be seen by external users."
+- In clientMode, staff comments show a "Team" badge. In staff mode, client comments show a "Client" badge.
+- Editor resolution priority: renderEditor prop > built-in RichTextEditor (when richText=true) > plain textarea fallback.
+- Viewer resolution priority: renderViewer prop > built-in RichTextViewer (when richText=true) > plain text with HTML stripped.
+- Auto-scrolls to bottom when new comments arrive.
+- Empty state: "No comments yet".
+- Forwards ref to outer div.
+
+## Changes
+### v0.19.0
+- **Added** Decomposed into composable pieces: `MessageList`, `MessageBubble`, `MessageInput`, `VisibilityWarning` — importable from `@devalok/shilp-sutra-karm/tasks`
+- ConversationTab remains as a pre-assembled default; use the pieces for custom layouts
+
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/files-tab.md

@@ -0,0 +1,55 @@
+# FilesTab
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    files: TaskFile[] (REQUIRED)
+    onUpload: (file: File, title?: string) => void (REQUIRED)
+    onDelete: (fileId: string) => void (REQUIRED)
+    isUploading: boolean (default: false)
+    readOnly: boolean (default: false) — hides upload/delete controls
+    ...HTMLAttributes<HTMLDivElement>
+
+## TaskFile Shape
+    id: string
+    taskId: string
+    title: string
+    fileUrl: string
+    downloadUrl: string (optional)
+    fileType: string | null
+    uploadedBy: { id: string; name: string; image: string | null }
+    createdAt: string
+    externalUrl: string (optional, e.g. Google Drive link)
+    externalLabel: string (optional, tooltip for external link, default: "Open externally")
+
+## Defaults
+    isUploading=false, readOnly=false
+
+## Example
+```jsx
+<FilesTab
+  files={task.files}
+  onUpload={(file) => uploadFile(file)}
+  onDelete={(fileId) => deleteFile(fileId)}
+  isUploading={uploading}
+/>
+```
+
+## Gotchas
+- Supports drag-and-drop upload zone and click-to-upload.
+- File icons are auto-detected from fileType: images, documents, code, spreadsheets, archives.
+- Delete triggers a confirmation Dialog before calling onDelete.
+- In readOnly mode, upload zone and delete buttons are hidden; download/external links remain.
+- externalUrl is validated to start with https?:// before rendering as a link.
+- Empty state: "No files attached".
+- Forwards ref to outer div.
+
+## Changes
+### v0.19.0
+- **Added** Decomposed into composable pieces: `FileDropZone`, `FileList`, `FileItem` — importable from `@devalok/shilp-sutra-karm/tasks`
+- FilesTab remains as a pre-assembled default; use the pieces for custom layouts
+
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/review-tab.md

@@ -0,0 +1,53 @@
+# ReviewTab
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    reviews: ReviewRequest[] (REQUIRED)
+    members: Member[] (REQUIRED)
+    onRequestReview: (reviewerId: string) => void (REQUIRED)
+    onUpdateStatus: (reviewId: string, status: ReviewRequest['status'], feedback?: string) => void (REQUIRED)
+    ...HTMLAttributes<HTMLDivElement>
+
+## ReviewRequest Shape
+    id: string
+    taskId: string
+    status: 'PENDING' | 'APPROVED' | 'CHANGES_REQUESTED' | 'REJECTED'
+    feedback: string | null
+    requestedBy: { id: string; name: string; image: string | null }
+    reviewer: { id: string; name: string; image: string | null }
+    createdAt: string
+    updatedAt: string
+
+## Member Shape
+    id: string
+    name: string
+    image?: string | null
+
+## Example
+```jsx
+<ReviewTab
+  reviews={task.reviewRequests}
+  members={teamMembers}
+  onRequestReview={(reviewerId) => requestReview(reviewerId)}
+  onUpdateStatus={(id, status, feedback) => updateReview(id, status, feedback)}
+/>
+```
+
+## Gotchas
+- Each review card shows reviewer avatar, name, requested-by name, and status badge.
+- PENDING reviews have a "Respond" button that expands to show feedback textarea and three response buttons: Approve (success), Request Changes (warning), Reject (error).
+- "Request Review" button at the bottom uses MemberPicker from core.
+- Status badge colors are defined in task-constants.ts via REVIEW_STATUS_MAP.
+- Empty state: "No reviews yet".
+- Forwards ref to outer div.
+
+## Changes
+### v0.19.0
+- **Added** Decomposed into composable pieces: `ReviewCard`, `ReviewResponseForm`, `ReviewRequestButton` — importable from `@devalok/shilp-sutra-karm/tasks`
+- ReviewTab remains as a pre-assembled default; use the pieces for custom layouts
+
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/subtasks-tab.md

@@ -0,0 +1,61 @@
+# SubtasksTab
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    subtasks: Subtask[] (REQUIRED)
+    terminalColumnId: string (optional — column ID that marks tasks as complete)
+    projectId: string (REQUIRED)
+    parentTaskId: string (REQUIRED)
+    defaultColumnId: string (REQUIRED)
+    onCreateSubtask: (title: string) => void (REQUIRED)
+    onToggleSubtask: (taskId: string, isComplete: boolean) => void (REQUIRED)
+    onClickSubtask: (taskId: string) => void
+    readOnly: boolean (default: false) — hides create/toggle controls
+    ...HTMLAttributes<HTMLDivElement>
+
+## Subtask Shape
+    id: string
+    title: string
+    priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
+    columnId: string
+    column: { id: string; name: string; isTerminal?: boolean } (optional)
+    assignees: { user: { id: string; name: string; image?: string | null } }[]
+
+## Defaults
+    readOnly=false
+
+## Example
+```jsx
+<SubtasksTab
+  subtasks={task.subtasks}
+  terminalColumnId="done-col"
+  projectId={task.projectId}
+  parentTaskId={task.id}
+  defaultColumnId="todo-col"
+  onCreateSubtask={(title) => createSubtask(title)}
+  onToggleSubtask={(id, complete) => toggleSubtask(id, complete)}
+  onClickSubtask={(id) => navigateToTask(id)}
+/>
+```
+
+## Gotchas
+- A subtask is considered "complete" when column.isTerminal is true OR columnId matches terminalColumnId.
+- Progress bar shows completed/total count at the top.
+- Each subtask row shows: checkbox, priority dot, title (strikethrough when complete), first assignee avatar.
+- Clicking a subtask row triggers onClickSubtask (if provided).
+- In readOnly mode, checkboxes are non-interactive and the "Add subtask" button is hidden.
+- "Add subtask" inline form with Enter to submit, Escape to cancel.
+- projectId, parentTaskId, and defaultColumnId are defined in the interface and required by the type but are not currently used in the component's rendering logic. They are reserved for future navigation/creation features.
+- Empty state: "No subtasks".
+- Forwards ref to outer div.
+
+## Changes
+### v0.19.0
+- **Added** Decomposed into composable pieces: `SubtaskProgress`, `SubtaskList`, `SubtaskItem`, `SubtaskAddForm` — importable from `@devalok/shilp-sutra-karm/tasks`
+- SubtasksTab remains as a pre-assembled default; use the pieces for custom layouts
+
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/task-assignee-picker.md

@@ -0,0 +1,36 @@
+# TaskAssigneePicker
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Multi-select assignee picker. Displays assigned members as removable chips with avatars and provides a "+" button to add more via the core MemberPicker.
+
+## Props
+    members: Member[] (REQUIRED — full list of available members)
+    value: Member[] (REQUIRED — currently assigned members)
+    onAssign: (userId: string) => void (REQUIRED — called when a member is added)
+    onUnassign: (userId: string) => void (REQUIRED — called when a member is removed)
+    readOnly?: boolean (default: false — hides remove buttons and add button)
+    className?: string
+
+## Example
+```jsx
+<TaskAssigneePicker
+  members={projectMembers}
+  value={task.assignees}
+  onAssign={(userId) => assignUser(task.id, userId)}
+  onUnassign={(userId) => unassignUser(task.id, userId)}
+/>
+```
+
+## Gotchas
+- Unlike TaskMemberPicker (single-select), this is multi-select with separate onAssign/onUnassign callbacks.
+- Each assignee chip shows first name only (splits on space).
+- The "+" button opens a MemberPicker with `multiple` mode. Toggling an already-assigned member calls onUnassign.
+- In readOnly mode with no assignees, displays "None".
+- Forwards ref to the outer `<div>`, not a button.
+
+## Changes
+### v0.19.0
+- **Added** Initial release

package/docs/components/tasks/task-column-picker.md

@@ -0,0 +1,37 @@
+# TaskColumnPicker
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Popover-based picker for selecting a board column (status). Displays the current column name and opens a dropdown with all available columns.
+
+## Props
+    columns: Column[] (REQUIRED — array of { id, name, isDefault?, isTerminal? })
+    value: string (REQUIRED — currently selected column id)
+    onChange: (columnId: string) => void (REQUIRED)
+    readOnly?: boolean (default: false — renders as plain text)
+    className?: string
+
+## Example
+```jsx
+<TaskColumnPicker
+  columns={[
+    { id: 'todo', name: 'To Do' },
+    { id: 'in-progress', name: 'In Progress' },
+    { id: 'done', name: 'Done', isTerminal: true },
+  ]}
+  value={task.columnId}
+  onChange={(columnId) => updateTask({ columnId })}
+/>
+```
+
+## Gotchas
+- If `value` does not match any column id, the trigger displays "Select column".
+- The selected column is highlighted with `text-accent-11` and shows a check icon.
+- Forwards ref to the trigger button.
+- In readOnly mode, renders a plain `<span>` instead of a button.
+
+## Changes
+### v0.19.0
+- **Added** Initial release

package/docs/components/tasks/task-date-picker.md

@@ -0,0 +1,49 @@
+# TaskDatePicker
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Date picker with optional quick-select presets. Uses a native `<input type="date">` inside a popover, with preset buttons for common due dates.
+
+## Props
+    value: Date | string | null (REQUIRED — current date value)
+    onChange: (date: Date | null) => void (REQUIRED — null means cleared)
+    presets?: boolean (default: true — show quick-select preset buttons)
+    readOnly?: boolean (default: false — renders as plain text)
+    className?: string
+
+## Presets
+When `presets` is true, the popover includes a "Quick select" section with:
+- Today
+- Tomorrow
+- Next Monday
+- +7 days
+- +14 days
+- Clear
+
+## Example
+```jsx
+<TaskDatePicker
+  value={task.dueDate}
+  onChange={(date) => updateTask({ dueDate: date })}
+/>
+
+{/* Without presets */}
+<TaskDatePicker
+  value={task.startDate}
+  onChange={(date) => updateTask({ startDate: date })}
+  presets={false}
+/>
+```
+
+## Gotchas
+- Accepts both `Date` objects and ISO date strings as `value`. Internally normalizes to `Date`.
+- An inline clear button (X icon) appears next to the trigger when a date is set.
+- The popover contains a native date input as the primary selector, with presets below it.
+- Date display format: "Mar 14, 2026" (en-US, short month).
+- Forwards ref to the trigger button.
+
+## Changes
+### v0.19.0
+- **Added** Initial release