@devalok/shilp-sutra-karm 0.18.1 → 0.20.0

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

@@ -0,0 +1,37 @@
+# TaskPriorityPicker
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Popover-based picker for task priority. Each priority level has a distinct icon and color.
+
+## Props
+    value: Priority (REQUIRED — 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT')
+    onChange: (priority: Priority) => void (REQUIRED)
+    readOnly?: boolean (default: false — renders as non-interactive indicator)
+    className?: string
+
+## Priority Icons
+    URGENT: IconAlertTriangleFilled (text-error-9)
+    HIGH: IconArrowUp (text-warning-9)
+    MEDIUM: IconMinus (text-surface-fg-muted)
+    LOW: IconArrowDown (text-surface-fg-subtle)
+
+## Example
+```jsx
+<TaskPriorityPicker
+  value={task.priority}
+  onChange={(priority) => updateTask({ priority })}
+/>
+```
+
+## Gotchas
+- Icon-per-level design: each priority has a unique icon and semantic color, not just a label.
+- Priority labels are sourced from the shared `PRIORITY_LABELS` constant in `task-constants`.
+- The selected priority row has a highlighted background and check icon.
+- Forwards ref to the trigger button.
+
+## Changes
+### v0.19.0
+- **Added** Initial release

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

@@ -72,8 +72,13 @@
 - 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.
+- Priority and Due Date rows are always rendered as interactive popovers regardless of readOnly. Enforcement of readOnly for these fields is done at the callback level. If using TaskProperties standalone in readOnly mode, supply a no-op onUpdate to prevent unintended changes.
 - Forwards ref to outer div.
 
 ## Changes
+### v0.19.0
+- **Added** Property logic extracted into 7 standalone pickers: `TaskColumnPicker`, `TaskPriorityPicker`, `TaskMemberPicker`, `TaskAssigneePicker`, `TaskDatePicker`, `TaskLabelEditor`, `TaskVisibilityPicker`
+- TaskProperties remains as a pre-assembled default; use individual pickers with `TaskPanel.Property` for custom layouts
+
 ### v0.18.0
 - **Added** Initial release

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

@@ -0,0 +1,38 @@
+# TaskVisibilityPicker
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Popover-based picker for task visibility with an optional confirmation dialog when switching to public ("Everyone") visibility.
+
+## Props
+    value: Visibility (REQUIRED — 'INTERNAL' | 'EVERYONE')
+    onChange: (visibility: Visibility) => void (REQUIRED)
+    confirmOnPublic?: boolean (default: false — when true, shows a confirmation dialog before switching to EVERYONE)
+    readOnly?: boolean (default: false — renders as non-interactive display)
+    className?: string
+
+## Visibility Options
+    INTERNAL: IconLock — "Internal" — "Only team members"
+    EVERYONE: IconWorld — "Everyone" — "Visible to clients"
+
+## Example
+```jsx
+<TaskVisibilityPicker
+  value={task.visibility}
+  onChange={(visibility) => updateTask({ visibility })}
+  confirmOnPublic
+/>
+```
+
+## Gotchas
+- When `confirmOnPublic` is true and the user selects "Everyone", a confirmation Dialog appears warning that the task will become visible to clients. The change only applies after the user clicks "Confirm".
+- Switching to "Internal" never requires confirmation.
+- Selecting the already-active option closes the popover without calling onChange.
+- Each option row shows an icon, label, and description. The selected option has a highlighted background and check icon.
+- Forwards ref to the trigger button.
+
+## Changes
+### v0.19.0
+- **Added** Initial release

package/llms.txt

@@ -10,14 +10,14 @@ pnpm add @devalok/shilp-sutra-karm
 
 // Per-module imports (recommended):
 import { KanbanBoard } from '@devalok/shilp-sutra-karm/board'
-import { TaskDetailPanel } from '@devalok/shilp-sutra-karm/tasks'
+import { TaskPanel, TaskColumnPicker, SubtasksTab } from '@devalok/shilp-sutra-karm/tasks'
 import { ChatPanel } from '@devalok/shilp-sutra-karm/chat'
 import { AttendanceCTA, DailyBrief } from '@devalok/shilp-sutra-karm/dashboard'
 import { AccentProvider, ClientPortalHeader, ProjectCard } from '@devalok/shilp-sutra-karm/client'
 import { AdminDashboard, BreakAdmin } from '@devalok/shilp-sutra-karm/admin'
 
 // Or from root barrel:
-import { KanbanBoard, TaskDetailPanel, ChatPanel } from '@devalok/shilp-sutra-karm'
+import { KanbanBoard, TaskPanel, ChatPanel } from '@devalok/shilp-sutra-karm'
 
 ## Module Reference
 
@@ -50,17 +50,42 @@ and state updates. Example wiring a custom column header action:
   />
 
 ### Tasks (`/tasks`)
+
+**TaskPanel (v2 composition API — recommended)**
+Headless compound component. Shell subcomponents:
+- TaskPanel (root): children, className — flex column container
+- TaskPanel.Header: children, className — top section with border
+- TaskPanel.Title: value, editable?, onUpdate?, subtask?, className — inline-editable heading
+- TaskPanel.Properties: children, className — property rows container
+- TaskPanel.Property: icon, label, children, className — single property row (120px label + flex value)
+- TaskPanel.Tabs: defaultTab, onTabChange?, children — tab system (children must be TaskPanel.Tab)
+- TaskPanel.Tab: id, label, icon?, children — declarative tab definition
+- TaskPanel.Loading: className — skeleton placeholder
+
+**Pickers (7)** — all support readOnly?, className?, forwardRef
+- TaskColumnPicker: columns[], value(string), onChange(id)
+- TaskPriorityPicker: value(Priority), onChange(priority)
+- TaskMemberPicker: members[], value(string|null), onChange(id|null), placeholder?
+- TaskAssigneePicker: members[], value(Member[]), onAssign(id), onUnassign(id)
+- TaskDatePicker: value(Date|string|null), onChange(date|null), presets?(default:true)
+- TaskLabelEditor: value(string[]), onChange(labels), availableLabels?(LabelOption[])
+- TaskVisibilityPicker: value(Visibility), onChange(v), confirmOnPublic?
+
+**Tab Pieces (16)** — for custom tab layouts
+Subtasks: SubtaskProgress(completed,total), SubtaskList(children), SubtaskItem(subtask,isComplete,onToggle?,onClick?), SubtaskAddForm(onCreate)
+Conversation: MessageList(children,autoScroll?), MessageBubble(comment,clientMode?,renderViewer?), MessageInput(onSubmit,renderEditor?,clientMode?), VisibilityWarning
+Files: FileDropZone(onUpload,isUploading?,accept?), FileList(children), FileItem(file,onDelete?,readOnly?)
+Review: ReviewCard(review,onUpdateStatus?), ReviewResponseForm(reviewId,onSubmit), ReviewRequestButton(members,onRequest)
+Activity: ActivityTimeline(children), ActivityEntry(entry)
+
+**Pre-assembled tabs** (unchanged from v0.18.0, usable inside TaskPanel.Tab):
+- SubtasksTab, ConversationTab, FilesTab, ReviewTab, ActivityTab
+
+**TaskDetailPanel (deprecated)** — monolithic v0.18.0 component, still exported. Migrate to TaskPanel.
 - TaskDetailPanel: task(FullTask|null), open, onOpenChange, columns[], members[], activities[], clientMode?, onTitleUpdate, onPropertyUpdate, onAssign, onUnassign, onCreateSubtask, onToggleSubtask, onRequestReview, onUpdateReviewStatus + more callbacks
 - TaskProperties: task, columns[], members[], onUpdate, onAssign, onUnassign, readOnly?, editableFields?, renderPriorityIndicator?, renderDatePicker?
-- ActivityTab: activities(AuditLogEntry[])
-- ConversationTab: comments[], taskVisibility, onPostComment, clientMode?, renderEditor?, renderViewer?
-- FilesTab: files[], onUpload, onDelete, isUploading?, readOnly?
-- ReviewTab: reviews[], members[], onRequestReview, onUpdateStatus
-- SubtasksTab: subtasks[], onCreateSubtask, onToggleSubtask, onClickSubtask?, readOnly?
-
-Type: ExtraTab = { id: string, label: string, icon?: ReactNode, content: ReactNode, position?: 'before' | 'after' }
-TaskDetailPanel opens as a Sheet with tabs: Properties, Subtasks, Review, Conversation, Files, Activity. Supports extraTabs?: ExtraTab[] for custom tabs.
-Supports clientMode for read-only client portal views.
+
+Shared types: Priority, Visibility, CommentAuthorType, LabelOption, Member, Column, Subtask, ReviewRequest, Comment, TaskFile, AuditLogEntry
 Priority values: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
 Visibility: 'INTERNAL' | 'EVERYONE'
 
@@ -128,7 +153,7 @@ BreakRequestStatus: 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED'
 
 - All components are callback-driven (emit updates via on* props, no internal state management)
 - Admin components use compound pattern with React Context (AdminDashboard.Root provides context to children)
-- Client mode: TaskDetailPanel, TaskProperties, FilesTab support readOnly + editableFields for client portal
+- Client mode: All pickers support readOnly. TaskDetailPanel (deprecated), TaskProperties, FilesTab support readOnly + editableFields for client portal. With TaskPanel v2, control client mode by choosing which pickers/tabs to render.
 - Chat supports streaming: pass isStreaming + streamingText for live AI responses
 - Board uses dnd-kit: KanbanBoard handles all drag state, emits onTaskMove with final position
 - All dates default to IST (Asia/Kolkata) timezone in admin utilities
@@ -136,7 +161,9 @@ BreakRequestStatus: 'PENDING' | 'APPROVED' | 'REJECTED' | 'CANCELLED'
 ## Common Mistakes -- DO NOT
 
 - DO NOT manage DnD state outside KanbanBoard — it handles sensors, collision detection, and sorting internally
-- DO NOT forget to pass both open AND onOpenChange to TaskDetailPanel (it's a controlled Sheet)
+- DO NOT use TaskDetailPanel for new code — use TaskPanel composition API instead
+- DO NOT forget to pass both open AND onOpenChange to TaskDetailPanel if still using the deprecated API (it's a controlled Sheet)
+- DO NOT use TaskPanel.Tab outside TaskPanel.Tabs — Tabs extracts props from Tab children
 - DO NOT use AdminDashboard sub-components outside AdminDashboard.Root — they depend on context
 - DO NOT use BreakAdmin sub-components outside BreakAdmin.Root — same compound pattern
 - DO NOT pass raw Date objects for task dates — use ISO strings (the components parse them internally)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devalok/shilp-sutra-karm",
-  "version": "0.18.1",
+  "version": "0.20.0",
   "description": "Domain components for Karm — board, tasks, chat, dashboard, client, and admin",
   "license": "MIT",
   "type": "module",