@devalok/shilp-sutra-karm 0.18.1 → 0.19.0

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

@@ -1,10 +1,238 @@
-# TaskDetailPanel
+# TaskDetailPanel (deprecated) / TaskPanel (v2)
 
 - Import: @devalok/shilp-sutra-karm/tasks
 - Server-safe: No
 - Category: tasks
 
-## Props
+## TaskPanel — Composition API (v0.19.0)
+
+TaskPanel is a headless compound component for building task detail panels.
+It provides the **shell** (layout slots); you fill it with pickers, tab pieces,
+or pre-assembled tabs as needed.
+
+### Shell Subcomponents
+
+| Subcomponent | Props | Description |
+|---|---|---|
+| `TaskPanel` (root) | `children`, `className` | Flex column container, `h-full` |
+| `TaskPanel.Header` | `children`, `className` | Top section with bottom border |
+| `TaskPanel.Title` | `value`, `editable?`, `onUpdate?`, `subtask?`, `className` | Inline-editable heading. Click to edit (staff), Enter to commit, Escape to cancel |
+| `TaskPanel.Properties` | `children`, `className` | Property rows container with bottom border |
+| `TaskPanel.Property` | `icon`, `label`, `children`, `className` | Single property row: 120 px icon+label, flex-1 value |
+| `TaskPanel.Tabs` | `defaultTab`, `onTabChange?`, `children`, `className` | Tab system. Children must be `TaskPanel.Tab` |
+| `TaskPanel.Tab` | `id`, `label`, `icon?`, `children` | Declarative tab definition (does not render on its own) |
+| `TaskPanel.Loading` | `className` | Skeleton placeholder (title + 6 property rows + 5 tab triggers + 3 content lines) |
+
+### Pickers (7)
+
+All pickers support `readOnly?: boolean` and `className?: string`. Forwards ref.
+
+| Picker | Key Props | Description |
+|---|---|---|
+| `TaskColumnPicker` | `columns: Column[]`, `value: string`, `onChange: (id) => void` | Popover column selector |
+| `TaskPriorityPicker` | `value: Priority`, `onChange: (p) => void` | Popover with colored icons per priority |
+| `TaskMemberPicker` | `members: Member[]`, `value: string \| null`, `onChange: (id \| null) => void`, `placeholder?` | Single-member picker (owner). Uses core MemberPicker |
+| `TaskAssigneePicker` | `members: Member[]`, `value: Member[]`, `onAssign: (id) => void`, `onUnassign: (id) => void` | Multi-select assignee chips with add/remove. Uses core MemberPicker |
+| `TaskDatePicker` | `value: Date \| string \| null`, `onChange: (date \| null) => void`, `presets?: boolean` | Date popover with quick-select presets (Today, Tomorrow, Next Monday, +7d, +14d, Clear) |
+| `TaskLabelEditor` | `value: string[]`, `onChange: (labels) => void`, `availableLabels?: LabelOption[]` | Label chips with inline add input + autocomplete from availableLabels |
+| `TaskVisibilityPicker` | `value: Visibility`, `onChange: (v) => void`, `confirmOnPublic?: boolean` | Internal/Everyone popover. When `confirmOnPublic=true`, shows a confirmation dialog before switching to EVERYONE |
+
+### Tab Pieces (16)
+
+Grouped by the pre-assembled tab they belong to.
+
+**Subtasks (4)**
+
+| Piece | Key Props |
+|---|---|
+| `SubtaskProgress` | `completed: number`, `total: number` — progress bar |
+| `SubtaskList` | `children` — wrapper div |
+| `SubtaskItem` | `subtask: Subtask`, `isComplete: boolean`, `onToggle?`, `onClick?` |
+| `SubtaskAddForm` | `onCreate: (title) => void`, `placeholder?` |
+
+**Conversation (4)**
+
+| Piece | Key Props |
+|---|---|
+| `MessageList` | `children`, `autoScroll?: boolean` — auto-scrolls to bottom on new children |
+| `MessageBubble` | `comment: Comment`, `clientMode?`, `renderViewer?` |
+| `MessageInput` | `onSubmit: (content, authorType) => void`, `renderEditor?`, `placeholder?`, `clientMode?` |
+| `VisibilityWarning` | (no custom props) — renders "Comments may be seen by external users" |
+
+**Files (3)**
+
+| Piece | Key Props |
+|---|---|
+| `FileDropZone` | `onUpload: (file, title?) => void`, `isUploading?`, `accept?` |
+| `FileList` | `children` — wrapper div |
+| `FileItem` | `file: TaskFile`, `onDelete?`, `readOnly?` |
+
+**Review (3)**
+
+| Piece | Key Props |
+|---|---|
+| `ReviewCard` | `review: ReviewRequest`, `onUpdateStatus?` |
+| `ReviewResponseForm` | `reviewId: string`, `onSubmit: (id, status, feedback?) => void` |
+| `ReviewRequestButton` | `members: Member[]`, `onRequest: (reviewerId) => void` |
+
+**Activity (2)**
+
+| Piece | Key Props |
+|---|---|
+| `ActivityTimeline` | `children` — vertical timeline wrapper |
+| `ActivityEntry` | `entry: AuditLogEntry` — single entry with icon, dot, timestamp, description |
+
+### Pre-Assembled Tab Defaults
+
+These are the v0.18.0 tab components, still exported and usable inside `TaskPanel.Tab`:
+
+| Tab | Import |
+|---|---|
+| `SubtasksTab` | `@devalok/shilp-sutra-karm/tasks` |
+| `ConversationTab` | `@devalok/shilp-sutra-karm/tasks` |
+| `FilesTab` | `@devalok/shilp-sutra-karm/tasks` |
+| `ReviewTab` | `@devalok/shilp-sutra-karm/tasks` |
+| `ActivityTab` | `@devalok/shilp-sutra-karm/tasks` |
+
+Their props are unchanged from v0.18.0 (see individual docs).
+
+### Shared Types
+
+All shared types are exported from `@devalok/shilp-sutra-karm/tasks`:
+
+    Priority: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
+    Visibility: 'INTERNAL' | 'EVERYONE'
+    CommentAuthorType: 'INTERNAL' | 'CLIENT'
+    LabelOption: { name: string; color?: string }
+    Member: { id: string; name: string; email?: string; image?: string | null }
+    Column: { id: string; name: string; isDefault?: boolean; isTerminal?: boolean }
+    Subtask, ReviewRequest, Comment, TaskFile, AuditLogEntry — see task-types.ts
+
+## Usage: Quick Drop-In (Pre-Assembled Tabs)
+
+```jsx
+import {
+  TaskPanel,
+  SubtasksTab,
+  ConversationTab,
+  FilesTab,
+  ReviewTab,
+  ActivityTab,
+  TaskColumnPicker,
+  TaskPriorityPicker,
+  TaskMemberPicker,
+  TaskAssigneePicker,
+  TaskDatePicker,
+  TaskLabelEditor,
+  TaskVisibilityPicker,
+} from '@devalok/shilp-sutra-karm/tasks'
+
+function MyTaskPanel({ task, columns, members, activities }) {
+  if (!task) return <TaskPanel><TaskPanel.Loading /></TaskPanel>
+
+  return (
+    <TaskPanel>
+      <TaskPanel.Header>
+        <TaskPanel.Title
+          value={task.title}
+          editable
+          onUpdate={(title) => updateTitle(task.id, title)}
+          subtask={!!task.parentTaskId}
+        />
+      </TaskPanel.Header>
+
+      <TaskPanel.Properties>
+        <TaskPanel.Property icon={<ColumnsIcon />} label="Column">
+          <TaskColumnPicker columns={columns} value={task.columnId} onChange={(id) => update('columnId', id)} />
+        </TaskPanel.Property>
+        <TaskPanel.Property icon={<UserIcon />} label="Priority">
+          <TaskPriorityPicker value={task.priority} onChange={(p) => update('priority', p)} />
+        </TaskPanel.Property>
+        {/* ...more properties */}
+      </TaskPanel.Properties>
+
+      <TaskPanel.Tabs defaultTab="subtasks">
+        <TaskPanel.Tab id="subtasks" label="Subtasks">
+          <SubtasksTab
+            subtasks={task.subtasks}
+            projectId={task.projectId}
+            parentTaskId={task.id}
+            defaultColumnId={columns[0]?.id ?? ''}
+            onCreateSubtask={(title) => createSubtask(title)}
+            onToggleSubtask={(id, done) => toggleSubtask(id, done)}
+          />
+        </TaskPanel.Tab>
+        <TaskPanel.Tab id="conversation" label="Conversation">
+          <ConversationTab
+            comments={task.comments ?? []}
+            taskVisibility={task.visibility}
+            onPostComment={(content, type) => postComment(content, type)}
+          />
+        </TaskPanel.Tab>
+        {/* ...more tabs */}
+      </TaskPanel.Tabs>
+    </TaskPanel>
+  )
+}
+```
+
+## Usage: Custom Composition (Individual Pieces)
+
+```jsx
+import {
+  TaskPanel,
+  SubtaskProgress,
+  SubtaskList,
+  SubtaskItem,
+  SubtaskAddForm,
+  MessageList,
+  MessageBubble,
+  MessageInput,
+} from '@devalok/shilp-sutra-karm/tasks'
+
+function CustomSubtasksContent({ task }) {
+  const terminalId = columns.find(c => c.isTerminal)?.id
+
+  return (
+    <>
+      <SubtaskProgress completed={doneCount} total={task.subtasks.length} />
+      <SubtaskList>
+        {task.subtasks.map(st => (
+          <SubtaskItem
+            key={st.id}
+            subtask={st}
+            isComplete={st.column?.isTerminal || st.columnId === terminalId}
+            onToggle={(id, done) => toggleSubtask(id, done)}
+            onClick={(id) => navigateToTask(id)}
+          />
+        ))}
+      </SubtaskList>
+      <SubtaskAddForm onCreate={(title) => createSubtask(title)} />
+    </>
+  )
+}
+```
+
+## TaskDetailPanel (deprecated)
+
+`TaskDetailPanel` is the v0.18.0 monolithic component. It is still exported
+and functional but is **deprecated** in favour of the TaskPanel composition API.
+
+### Migration Guide
+
+| Old (TaskDetailPanel) | New (TaskPanel) |
+|---|---|
+| Single component with 30+ props | Compose shell + pickers + tab pieces |
+| `task`, `columns`, `members` passed once | Pass data directly to each picker/tab |
+| `clientMode` hides tabs/fields automatically | You control which tabs/properties to render |
+| `headerSlot` render prop | Put any content inside `TaskPanel.Header` |
+| `extraTabs` array | Add more `TaskPanel.Tab` children |
+| `renderEditor`/`renderViewer` | Pass to `MessageBubble`/`MessageInput` or `ConversationTab` |
+| `renderPriorityIndicator` | Use `TaskPriorityPicker` directly |
+| `renderDatePicker` | Use `TaskDatePicker` directly |
+
+### Old Props (for reference)
+
     task: FullTask | null (REQUIRED)
     loading: boolean (default: false)
     open: boolean (REQUIRED)
@@ -12,92 +240,36 @@
     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
+    enrichedComments: Comment[] | null
+    clientMode: boolean (default: false)
     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
+    headerSlot: ReactNode
+    extraTabs: ExtraTab[]
+    onTitleUpdate, onPropertyUpdate, onAssign, onUnassign,
+    onCreateSubtask, onToggleSubtask, onRequestReview,
+    onUpdateReviewStatus, onPostComment, onUploadFile,
+    onUploadDeliverable, onDeleteFile, onTabChange
+    renderEditor, renderViewer, renderPriorityIndicator, renderDatePicker
     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.
+- TaskPanel is a **layout shell** only — it does not render inside a Sheet. Wrap it in a Sheet yourself if you need a side panel.
+- TaskDetailPanel (deprecated) still renders as a Sheet (right side panel, 40% width, min 380 px).
+- TaskPanel.Tab renders nothing on its own; TaskPanel.Tabs extracts props from Tab children.
+- TaskPanel.Title auto-selects text on edit activation for quick replacement.
+- All pickers fall back to a read-only display when `readOnly=true`.
+- TaskVisibilityPicker with `confirmOnPublic` shows a Dialog before switching to EVERYONE.
+- TaskDatePicker accepts both `Date` and ISO string for the `value` prop.
+- TaskLabelEditor supports both free-text entry and autocomplete from `availableLabels`.
 
 ## Changes
+### v0.19.0
+- **Added** TaskPanel composition API (shell: Root, Header, Title, Properties, Property, Tabs, Tab, Loading)
+- **Added** 7 standalone pickers: TaskColumnPicker, TaskPriorityPicker, TaskMemberPicker, TaskAssigneePicker, TaskDatePicker, TaskLabelEditor, TaskVisibilityPicker
+- **Added** 16 tab pieces: SubtaskProgress, SubtaskList, SubtaskItem, SubtaskAddForm, MessageList, MessageBubble, MessageInput, VisibilityWarning, FileDropZone, FileList, FileItem, ReviewCard, ReviewResponseForm, ReviewRequestButton, ActivityTimeline, ActivityEntry
+- **Added** Shared domain types exported from task-types.ts
+- **Deprecated** TaskDetailPanel — use TaskPanel composition API instead
+- **Breaking** Import path unchanged (`@devalok/shilp-sutra-karm/tasks`), but consumers using TaskDetailPanel should migrate to TaskPanel for new features
+
 ### v0.18.0
-- **Added** Initial release
+- **Added** Initial release (monolithic TaskDetailPanel)

package/docs/components/tasks/task-label-editor.md

@@ -0,0 +1,42 @@
+# TaskLabelEditor
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Inline label editor with autocomplete suggestions and color dot support. Displays labels as removable chips and provides a "+" button to add new labels by typing.
+
+## Props
+    value: string[] (REQUIRED — currently applied label names)
+    onChange: (labels: string[]) => void (REQUIRED — full updated label array)
+    availableLabels?: LabelOption[] (default: [] — autocomplete options, each { name, color? })
+    readOnly?: boolean (default: false — hides remove buttons and add input)
+    className?: string
+
+## Example
+```jsx
+<TaskLabelEditor
+  value={task.labels}
+  onChange={(labels) => updateTask({ labels })}
+  availableLabels={[
+    { name: 'Bug', color: '#ef4444' },
+    { name: 'Feature', color: '#3b82f6' },
+    { name: 'Design', color: '#8b5cf6' },
+  ]}
+/>
+```
+
+## Gotchas
+- Supports both selecting from `availableLabels` and creating new labels by typing a name not in the list.
+- Autocomplete popover appears as you type, filtered to labels matching the input that are not already applied.
+- Enter key: selects the first matching suggestion if available, otherwise creates a new label from the typed text.
+- Escape key closes the input without adding.
+- On blur, the typed value is committed as a label (if non-empty).
+- Color dots appear on chips and in autocomplete suggestions when a label has a `color` value.
+- Duplicate labels are prevented — adding an already-applied label is a no-op.
+- In readOnly mode with no labels, displays "None".
+- Forwards ref to the outer `<div>`.
+
+## Changes
+### v0.19.0
+- **Added** Initial release

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

@@ -0,0 +1,35 @@
+# TaskMemberPicker
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Single-select member picker for assigning a task owner. Wraps the core MemberPicker composed component with task-specific styling.
+
+## Props
+    members: Member[] (REQUIRED — array of { id, name, email?, image? })
+    value: string | null (REQUIRED — selected member id, or null for none)
+    onChange: (memberId: string | null) => void (REQUIRED — returns null when deselecting)
+    placeholder?: string (default: 'No owner')
+    readOnly?: boolean (default: false — renders as non-interactive display)
+    className?: string
+
+## Example
+```jsx
+<TaskMemberPicker
+  members={projectMembers}
+  value={task.ownerId}
+  onChange={(memberId) => updateTask({ ownerId: memberId })}
+  placeholder="Assign owner"
+/>
+```
+
+## Gotchas
+- Selecting the already-selected member deselects them (toggles to null).
+- Uses core Avatar with initials fallback via `getInitials()`.
+- In readOnly mode with no selection, shows the placeholder text in muted style.
+- Forwards ref to the trigger button.
+
+## Changes
+### v0.19.0
+- **Added** Initial release

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

@@ -0,0 +1,89 @@
+# TaskPanel
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+Compound component shell for the task detail panel. Container-agnostic — works in sidebars, modals, or full-page layouts. Compose the sub-components to build a complete task view.
+
+## Sub-components
+
+### TaskPanel (root)
+    children: ReactNode (REQUIRED)
+    className?: string
+
+### TaskPanel.Header
+    children: ReactNode (REQUIRED)
+    className?: string
+
+### TaskPanel.Title
+    value: string (REQUIRED — current title text)
+    editable?: boolean (default: false — enables inline editing)
+    onUpdate?: (title: string) => void (called when user commits a title change)
+    subtask?: boolean (default: false — shows a "Subtask" label above the title)
+    className?: string
+
+### TaskPanel.Properties
+    children: ReactNode (REQUIRED — should contain TaskPanel.Property rows)
+    className?: string
+
+### TaskPanel.Property
+    icon: ReactNode (REQUIRED — icon element for the label area)
+    label: string (REQUIRED — human-readable property name)
+    children: ReactNode (REQUIRED — property value or control)
+    className?: string
+
+### TaskPanel.Tabs
+    defaultTab: string (REQUIRED — id of the initially active tab)
+    onTabChange?: (tab: string) => void
+    children: ReactNode (REQUIRED — must contain TaskPanel.Tab children)
+    className?: string
+
+### TaskPanel.Tab
+    id: string (REQUIRED — unique tab identifier)
+    icon?: ReactNode (optional icon in the tab trigger)
+    label: string (REQUIRED — tab trigger label)
+    children: ReactNode (REQUIRED — tab panel content)
+
+### TaskPanel.Loading
+    className?: string
+
+## Example
+```jsx
+<TaskPanel>
+  <TaskPanel.Header>
+    <TaskPanel.Title value={task.title} editable onUpdate={handleTitleUpdate} />
+  </TaskPanel.Header>
+
+  <TaskPanel.Properties>
+    <TaskPanel.Property icon={<IconColumns />} label="Status">
+      <TaskColumnPicker columns={columns} value={task.columnId} onChange={handleColumnChange} />
+    </TaskPanel.Property>
+    <TaskPanel.Property icon={<IconFlag />} label="Priority">
+      <TaskPriorityPicker value={task.priority} onChange={handlePriorityChange} />
+    </TaskPanel.Property>
+  </TaskPanel.Properties>
+
+  <TaskPanel.Tabs defaultTab="comments">
+    <TaskPanel.Tab id="comments" label="Comments" icon={<IconMessage />}>
+      {/* comments content */}
+    </TaskPanel.Tab>
+    <TaskPanel.Tab id="subtasks" label="Subtasks" icon={<IconSubtask />}>
+      {/* subtasks content */}
+    </TaskPanel.Tab>
+  </TaskPanel.Tabs>
+</TaskPanel>
+```
+
+## Gotchas
+- TaskPanel is container-agnostic. It renders as a flex column with `overflow-hidden h-full` — the parent must provide height constraints.
+- TaskPanel.Tab does not render anything on its own. TaskPanel.Tabs extracts props from Tab children declaratively.
+- TaskPanel.Title in editable mode: Enter commits, Escape cancels, blur commits. Empty titles revert to the previous value.
+- TaskPanel.Title with `subtask` shows a small uppercase "Subtask" label above the heading.
+- TaskPanel.Tabs uses a sticky tab bar. The content area scrolls independently.
+- TaskPanel.Loading renders a skeleton placeholder with 6 property rows and 5 tab stubs.
+- The label area in TaskPanel.Property has a fixed 120px width.
+
+## Changes
+### v0.19.0
+- **Added** Initial release

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