@devalok/shilp-sutra-karm 0.18.0 → 0.18.1

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

@@ -0,0 +1,51 @@
+# 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.18.0
+- **Added** Initial release

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

@@ -0,0 +1,49 @@
+# 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 (optional)
+
+## 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.18.0
+- **Added** Initial release

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

@@ -0,0 +1,56 @@
+# 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.
+- Empty state: "No subtasks".
+- Forwards ref to outer div.
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/task-detail-panel.md

@@ -0,0 +1,103 @@
+# TaskDetailPanel
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    task: FullTask | null (REQUIRED)
+    loading: boolean (default: false)
+    open: boolean (REQUIRED)
+    onOpenChange: (open: boolean) => void (REQUIRED)
+    columns: Column[] (REQUIRED)
+    members: Member[] (REQUIRED)
+    activities: AuditLogEntry[] (default: [])
+    enrichedComments: Comment[] | null (override comments from separate API)
+    clientMode: boolean (default: false) — hides staff-only tabs/fields
+    clientEditableFields: string[] (default: ['priority', 'dueDate'])
+    headerSlot: ReactNode (content between title and properties)
+    extraTabs: ExtraTab[] (default: []) — additional tab panels alongside built-in tabs
+    onTitleUpdate: (title: string) => void
+    onPropertyUpdate: (field: string, value: unknown) => void
+    onAssign: (userId: string) => void
+    onUnassign: (userId: string) => void
+    onCreateSubtask: (title: string) => void
+    onToggleSubtask: (taskId: string, isComplete: boolean) => void
+    onRequestReview: (reviewerId: string) => void
+    onUpdateReviewStatus: (reviewId: string, status: string, feedback?: string) => void
+    onPostComment: (content: string, authorType: 'INTERNAL' | 'CLIENT') => void
+    onUploadFile: (file: File, title?: string) => void
+    onUploadDeliverable: (file: File, deliverableId?: string) => void
+    onDeleteFile: (fileId: string) => void
+    onTabChange: (tab: string) => void
+    renderEditor: (props: { content: string; onChange: (content: string) => void; placeholder: string }) => ReactNode
+    renderViewer: (props: { content: string; className?: string }) => ReactNode
+    renderPriorityIndicator: (props: { priority: string }) => ReactNode
+    renderDatePicker: (props: { value: Date | null; onChange: (date: Date | null) => void; placeholder: string; className?: string }) => ReactNode
+    isUploading: boolean (default: false)
+
+## FullTask Shape
+    id: string
+    title: string
+    description: string | null
+    projectId: string
+    columnId: string
+    column: { id: string; name: string }
+    ownerId: string | null
+    owner: Member | null
+    priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
+    dueDate: string | null
+    labels: string[]
+    visibility: 'INTERNAL' | 'EVERYONE'
+    parentTaskId: string | null
+    depth: number
+    order: number
+    isBlocked: boolean
+    assignees: { user: Member }[]
+    subtasks: Subtask[]
+    reviewRequests: ReviewRequest[]
+    comments: Comment[] (optional)
+    files: TaskFile[]
+    createdAt: string
+    updatedAt: string
+    metadata: Record<string, unknown> (optional)
+
+## ExtraTab Shape
+    id: string
+    label: string
+    icon: ReactNode (optional)
+    content: ReactNode
+    position: 'before' | 'after' (default: 'after')
+
+## Built-in Tabs
+    subtasks, review, conversation, files, activity
+
+## Defaults
+    loading=false, clientMode=false, clientEditableFields=['priority','dueDate'], activities=[], extraTabs=[], isUploading=false
+
+## Example
+```jsx
+<TaskDetailPanel
+  task={selectedTask}
+  open={isPanelOpen}
+  onOpenChange={setIsPanelOpen}
+  columns={projectColumns}
+  members={teamMembers}
+  activities={auditLog}
+  onPropertyUpdate={(field, value) => updateTask(field, value)}
+  onPostComment={(content, type) => postComment(content, type)}
+/>
+```
+
+## Gotchas
+- Renders as a Sheet (side panel) on the right, 40% width (min 380px).
+- In clientMode, only the Conversation tab is shown. Staff-only tabs (subtasks, review, files, activity) are hidden.
+- In clientMode, title editing is disabled and properties respect clientEditableFields.
+- Title is editable by clicking on it (staff mode only).
+- enrichedComments takes priority over task.comments when both are provided.
+- extraTabs with position="before" render before built-in tabs; default "after" appends them.
+- Forwards ref to SheetContent.
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/docs/components/tasks/task-properties.md

@@ -0,0 +1,79 @@
+# TaskProperties
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Props
+    task: TaskData (REQUIRED)
+    columns: Column[] (REQUIRED)
+    members: Member[] (REQUIRED)
+    onUpdate: (field: string, value: unknown) => void (REQUIRED)
+    onAssign: (userId: string) => void (REQUIRED)
+    onUnassign: (userId: string) => void (REQUIRED)
+    readOnly: boolean (default: false)
+    editableFields: string[] (field names the client can still edit when readOnly=true)
+    renderPriorityIndicator: (props: { priority: string }) => ReactNode
+    renderDatePicker: (props: { value: Date | null; onChange: (date: Date | null) => void; placeholder: string; className?: string }) => ReactNode
+    onConfirmVisibilityChange: () => void (called when switching to EVERYONE; if omitted, change applies immediately)
+    ...HTMLAttributes<HTMLDivElement>
+
+## TaskData Shape
+    id: string
+    columnId: string
+    column: { id: string; name: string }
+    ownerId: string | null
+    owner: Member | null
+    assignees: { user: Member }[]
+    priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
+    dueDate: string | null
+    labels: string[]
+    visibility: 'INTERNAL' | 'EVERYONE'
+
+## Member Shape
+    id: string
+    name: string
+    email: string (optional)
+    image: string | null (optional)
+
+## Column Shape
+    id: string
+    name: string
+    isDefault: boolean (optional)
+    isTerminal: boolean (optional)
+
+## Property Rows
+    Column — popover picker
+    Owner — MemberPicker (hidden in readOnly mode)
+    Assignees — MemberPicker (multi-select), pill chips with remove
+    Priority — popover picker with dot color indicators
+    Due Date — native date input or custom renderDatePicker
+    Labels — pill chips with add/remove inline input
+    Visibility — toggle button (Internal / Everyone, hidden in readOnly mode)
+
+## Defaults
+    readOnly=false
+
+## Example
+```jsx
+<TaskProperties
+  task={taskData}
+  columns={columns}
+  members={members}
+  onUpdate={(field, value) => updateTask(field, value)}
+  onAssign={(userId) => assignUser(userId)}
+  onUnassign={(userId) => unassignUser(userId)}
+/>
+```
+
+## Gotchas
+- In readOnly mode, Owner and Visibility rows are completely hidden.
+- editableFields only applies when readOnly=true (e.g. ['priority', 'dueDate'] lets clients change those).
+- onUpdate field values: 'columnId', 'ownerId', 'priority', 'dueDate', 'labels', 'visibility'.
+- Uses MemberPicker from core composed library for owner/assignee selection.
+- onConfirmVisibilityChange is a guard hook: when provided and user switches to EVERYONE, it is called instead of onUpdate, allowing a confirmation dialog.
+- Forwards ref to outer div.
+
+## Changes
+### v0.18.0
+- **Added** Initial release

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra-karm",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Domain components for Karm — board, tasks, chat, dashboard, client, and admin",
   "license": "MIT",
   "type": "module",
@@ -45,10 +45,12 @@
       "import": "./dist/admin/index.js",
       "default": "./dist/admin/index.js",
       "types": "./dist/admin/index.d.ts"
-    }
+    },
+    "./docs/*": "./docs/components/*"
   },
   "files": [
     "dist",
+    "docs/components",
     "README.md",
     "llms.txt"
   ],