@devalok/shilp-sutra-karm 0.18.1 → 0.20.0

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

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