@devalok/shilp-sutra-karm 0.18.1 → 0.20.0

package/docs/components/dashboard/project-health-card.md

@@ -0,0 +1,90 @@
+# ProjectHealthCard
+
+Props-driven card showing project completion progress, status badge, sparkline trend, and context line.
+
+- Import: @devalok/shilp-sutra-karm/dashboard
+- Server-safe: No
+- Category: dashboard
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| project | ProjectHealthData | REQUIRED | Project data object |
+| onClick | () => void | — | Makes card clickable with hover state and keyboard activation |
+| loading | boolean | false | Shows skeleton placeholder when true |
+| className | string | — | Additional CSS classes |
+
+## Related Types
+
+```typescript
+interface ProjectHealthData {
+  id: string
+  name: string
+  completed: number
+  total: number
+  overdue?: number
+  urgent?: number
+  contextLine?: string
+  /** 7 values (0-1) for sparkline trend chart */
+  trend?: number[]
+}
+```
+
+## Status Badge Severity
+
+| Condition | Badge |
+|-----------|-------|
+| urgent > 0 | `solid` / `error` — "{urgent} urgent" |
+| overdue > 0 (no urgent) | `subtle` / `warning` — "{overdue} overdue" |
+| neither | `subtle` / `success` — "on track" |
+
+## Progress Bar Color
+
+| Percentage | Color |
+|------------|-------|
+| > 75% | success |
+| 25%–75% | warning |
+| < 25% | error |
+
+## Sparkline
+
+- Rendered as an inline SVG (48x20) when `trend` has >= 2 values
+- Uses Catmull-Rom spline interpolation for smooth curves
+- Color determined by comparing average of first 3 vs last 3 values:
+  - Improving (diff > 0.05): success stroke/fill
+  - Declining (diff < -0.05): error stroke/fill
+  - Flat: warning stroke/fill
+- Fewer than 6 data points always renders warning color
+
+## Defaults
+    loading=false
+
+## Example
+
+```tsx
+<ProjectHealthCard
+  project={{
+    id: 'proj-1',
+    name: 'Website Redesign',
+    completed: 12,
+    total: 20,
+    overdue: 3,
+    contextLine: 'Sprint 4 of 6',
+    trend: [0.3, 0.4, 0.5, 0.55, 0.6, 0.65, 0.7],
+  }}
+  onClick={() => navigateToProject('proj-1')}
+/>
+```
+
+## Gotchas
+- Extends `Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick'>` — native onClick is replaced by the typed onClick prop
+- When `onClick` is provided, the card gets `role="button"`, `tabIndex={0}`, and keyboard activation (Enter/Space)
+- When `onClick` is provided, the card uses `whileTap={{ scale: 0.98 }}` for press feedback
+- `loading=true` renders a skeleton with no project data — use for async loading states
+- The sparkline is `aria-hidden="true"` — it is decorative only
+- `contextLine` and overdue count are combined in a third row separated by a middot
+
+## Changes
+### v0.20.0
+- **Added** Initial release — project health card with progress bar, status badge, sparkline, and loading skeleton

package/docs/components/dashboard/scratchpad-widget.md

@@ -10,6 +10,9 @@
     onToggle: (id: string, done: boolean) => void (REQUIRED)
     onAdd: (text: string) => void (REQUIRED)
     onDelete: (id: string) => void (REQUIRED)
+    onEdit: (id: string, text: string) => void — enables inline editing (double-click)
+    onReorder: (items: ScratchpadItem[]) => void — enables drag-to-reorder via @dnd-kit
+    onPromote: (id: string) => void — enables promote-to-task button on items
     title: string (default: "My Scratchpad")
     resetLabel: string
     emptyText: string (default: "Nothing here yet. Add a task!")
@@ -30,6 +33,9 @@
   onToggle={(id, done) => toggleItem(id, done)}
   onAdd={(text) => addItem(text)}
   onDelete={(id) => deleteItem(id)}
+  onEdit={(id, text) => editItem(id, text)}
+  onReorder={(items) => reorderItems(items)}
+  onPromote={(id) => promoteToTask(id)}
   maxItems={5}
 />
 ```
@@ -46,7 +52,18 @@
 - resetLabel renders as footer text below the item list (e.g., "Resets daily at midnight")
 - When loading=true, shows a shimmer skeleton placeholder
 - Uses framer-motion AnimatePresence for item enter/exit animations
+- Internally uses the composable Scratchpad compound component — see scratchpad.md for details
+- onEdit, onReorder, onPromote are optional; features auto-enable when callbacks are provided
+- onEdit: double-click item text to enter inline edit mode; Enter confirms, Escape cancels
+- onReorder: items become draggable with @dnd-kit; drag handle appears on hover
+- onPromote: arrow-up button appears on each item on hover
 
 ## Changes
+### v0.20.0
+- **Added** `onEdit` prop — inline editing via double-click
+- **Added** `onReorder` prop — drag-to-reorder via @dnd-kit
+- **Added** `onPromote` prop — promote-to-task button on items
+- **Changed** Internally rebuilt on composable Scratchpad compound component
+
 ### v0.18.0
 - **Added** Initial release

package/docs/components/dashboard/scratchpad.md

@@ -0,0 +1,151 @@
+# Scratchpad (Composable)
+
+Compound component for building custom scratchpad UIs with drag-to-reorder, inline editing, promote-to-task, and filter completed toggle.
+
+- Import: @devalok/shilp-sutra-karm/dashboard
+- Server-safe: No
+- Category: dashboard
+
+## Compound Parts
+
+| Part | Description |
+|------|-------------|
+| `Scratchpad.Root` | Context provider + layout div. All other parts must be children. |
+| `Scratchpad.Header` | Title bar with optional children slot (e.g. ProgressRing, FilterToggle) |
+| `Scratchpad.List` | Item list with optional @dnd-kit drag-to-reorder and AnimatePresence |
+| `Scratchpad.Item` | Single item row: checkbox, text, inline edit, drag handle, promote/delete buttons |
+| `Scratchpad.AddInput` | "Add a task" trigger that expands to an inline input + Add button |
+| `Scratchpad.EmptyState` | Empty placeholder shown when visibleItems is empty |
+| `Scratchpad.ProgressRing` | SVG ring showing items.length / maxItems with completion pulse |
+| `Scratchpad.FilterToggle` | Eye icon button toggling show/hide completed items |
+| `Scratchpad.Collapse` | Collapsible section with chevron header, CSS grid-rows transition, badge count |
+
+## Props (Root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| items | ScratchpadItem[] | REQUIRED | Full item list |
+| onToggle | (id: string, done: boolean) => void | REQUIRED | Toggle item completion |
+| onAdd | (text: string) => void | — | Enables AddInput when provided |
+| onDelete | (id: string) => void | — | Enables delete button on items |
+| onEdit | (id: string, text: string) => void | — | Enables inline editing (double-click) |
+| onReorder | (items: ScratchpadItem[]) => void | — | Enables drag-to-reorder via @dnd-kit |
+| onPromote | (id: string) => void | — | Enables promote-to-task button on items |
+| maxItems | number | 20 | Maximum item count; AddInput hides when reached |
+| defaultShowCompleted | boolean | true | Initial filter toggle state |
+| className | string | — | Additional CSS classes |
+
+## Props (Header)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| title | string | "Scratchpad" | Header title text |
+| children | ReactNode | — | Slot for ProgressRing, FilterToggle, etc. |
+
+## Props (List)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| compact | boolean | false | Compact layout passed to each item |
+
+## Props (Item)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| item | ScratchpadItem | REQUIRED | The item data |
+| compact | boolean | false | Compact sizing |
+| sortable | boolean | false | Whether dnd-kit drag is active |
+
+## Props (AddInput)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| placeholder | string | "What needs doing?" | Input placeholder |
+| triggerLabel | string | "+ Add a task..." | Button label before expanding |
+
+## Props (EmptyState)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| icon | React.ComponentType<{ className?: string }> | — | Icon shown above message |
+| message | string | "Nothing here yet. Add a task!" | Empty state text |
+
+## Props (ProgressRing)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| size | "sm" \| "md" | "md" | Ring diameter: sm=16px, md=20px |
+
+## Props (FilterToggle)
+
+No custom props. Extends `Omit<ButtonHTMLAttributes, 'children'>`.
+
+## Props (Collapse)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| label | string | "Scratchpad" | Header label text |
+| defaultOpen | boolean | true | Whether expanded initially |
+| badgeCount | number | — | Badge pill count in header (hidden when 0 or undefined) |
+| headerClassName | string | — | Override header text styling |
+
+## Related Types
+
+```typescript
+interface ScratchpadItem {
+  id: string
+  text: string
+  done: boolean
+}
+```
+
+## Context-Driven Feature Visibility
+
+Features auto-enable based on which callbacks are provided to Root:
+
+| Callback | Enables |
+|----------|---------|
+| onAdd | AddInput component renders |
+| onDelete | Delete (X) button on each item |
+| onEdit | Double-click inline editing on items |
+| onReorder | Drag handles + @dnd-kit SortableContext on List |
+| onPromote | Promote (arrow-up) button on each item |
+
+## Example
+
+```tsx
+<Scratchpad.Root
+  items={items}
+  onToggle={toggle}
+  onAdd={add}
+  onDelete={del}
+  onEdit={edit}
+  onReorder={reorder}
+  onPromote={promote}
+>
+  <Scratchpad.Header title="My Scratchpad">
+    <Scratchpad.FilterToggle />
+    <Scratchpad.ProgressRing />
+  </Scratchpad.Header>
+  <Scratchpad.EmptyState />
+  <Scratchpad.List />
+  <Scratchpad.AddInput />
+</Scratchpad.Root>
+```
+
+## Gotchas
+- All sub-components must be inside `Scratchpad.Root` — they use React context
+- Root extends `Omit<HTMLDivElement, 'onToggle'>` to avoid conflict with native onToggle
+- Drag-to-reorder uses @dnd-kit with PointerSensor (5px activation distance) and KeyboardSensor
+- When sortable, List does NOT render `role="list"` because dnd-kit adds `role="button"` to items
+- Inline editing activates on double-click; Enter confirms, Escape cancels, blur confirms
+- AddInput auto-hides when items.length >= maxItems
+- EmptyState auto-hides when visibleItems.length > 0
+- FilterToggle shows IconEye when completed shown, IconEyeOff when hidden
+- ProgressRing pulses (scale animation) when all items are done
+- Items animate in/out with framer-motion (opacity + x slide)
+- Collapse uses CSS `grid-template-rows` transition for smooth open/close
+
+## Changes
+### v0.20.0
+- **Added** Initial release — 9-part composable scratchpad: Root, Header, List, Item, AddInput, EmptyState, ProgressRing, FilterToggle, Collapse

package/docs/components/dashboard/sidebar-scratchpad.md

@@ -7,33 +7,57 @@
 ## Props
     items: ScratchpadItem[] (REQUIRED)
     onToggle: (id: string, done: boolean) => void (REQUIRED)
+    onAdd: (text: string) => void — enables quick-add input
+    onDelete: (id: string) => void — enables delete button on items
+    onEdit: (id: string, text: string) => void — enables inline editing (double-click)
+    onReorder: (items: ScratchpadItem[]) => void — enables drag-to-reorder
+    onPromote: (id: string) => void — enables promote-to-task button
+    maxItems: number (default: 20)
     defaultOpen: boolean (default: true)
     badgeCount: number
     className: string
 
 ## Related Types
-    ScratchpadItem: { id: string; text: string; done: boolean } (imported from scratchpad-widget)
+    ScratchpadItem: { id: string; text: string; done: boolean }
 
 ## Defaults
-    defaultOpen=true
+    maxItems=20, defaultOpen=true
 
 ## Example
 ```jsx
 <SidebarScratchpad
   items={scratchpadItems}
   onToggle={(id, done) => toggleItem(id, done)}
+  onAdd={(text) => addItem(text)}
+  onDelete={(id) => deleteItem(id)}
+  onEdit={(id, text) => editItem(id, text)}
+  onReorder={(items) => reorderItems(items)}
+  onPromote={(id) => promoteToTask(id)}
+  maxItems={20}
   badgeCount={scratchpadItems.filter(i => !i.done).length}
 />
 ```
 
 ## Gotchas
-- This is a compact, read-only version of ScratchpadWidget designed for the app sidebar
-- Does NOT support adding or deleting items — use ScratchpadWidget for full CRUD
-- Only supports toggling done state via checkboxes
+- Compact sidebar layout built on the composable Scratchpad compound component
+- Renders Scratchpad.Collapse > Scratchpad.List (compact) + Scratchpad.AddInput
 - Collapsible header with chevron; uses CSS grid-rows transition for smooth collapse
 - badgeCount shows a pill badge in the header; hidden when badgeCount is undefined, null, or 0
 - Extends React.HTMLAttributes<HTMLDivElement>
+- onAdd, onDelete, onEdit, onReorder, onPromote are all optional; features auto-enable when callbacks are provided
+- AddInput uses compact placeholders: "Quick add..." and "+ Add..."
+- List renders in compact mode (smaller text and spacing)
 
 ## Changes
+### v0.20.0
+- **Added** `onAdd` prop — enables quick-add input
+- **Added** `onDelete` prop — enables delete button on items
+- **Added** `onEdit` prop — inline editing via double-click
+- **Added** `onReorder` prop — drag-to-reorder via @dnd-kit
+- **Added** `onPromote` prop — promote-to-task button
+- **Added** `maxItems` prop (default: 20)
+- **Changed** Internally rebuilt on composable Scratchpad compound component
+- **Changed** No longer read-only — supports full CRUD when callbacks provided
+
 ### v0.18.0
 - **Added** Initial release

package/docs/components/dashboard/week-heatmap.md

@@ -0,0 +1,95 @@
+# WeekHeatmap
+
+Composable weekly task-completion heatmap with day cells, streak indicator, summary stats, and progress bar.
+
+- Import: @devalok/shilp-sutra-karm/dashboard
+- Server-safe: No
+- Category: dashboard
+
+## Compound Parts
+
+| Part | Description |
+|------|-------------|
+| `WeekHeatmap` | Props shorthand — renders Root + DayStrip + Streak + Summary + ProgressBar |
+| `WeekHeatmap.Root` | Context provider + layout wrapper |
+| `WeekHeatmap.DayStrip` | 7-column grid of Day cells with keyboard navigation and MotionStagger animation |
+| `WeekHeatmap.Day` | Individual day cell with tooltip, status color, and click/keyboard activation |
+| `WeekHeatmap.Summary` | Text line showing completed/remaining/overdue counts |
+| `WeekHeatmap.ProgressBar` | Progress bar colored by success, driven by totalCompleted/totalTasks |
+| `WeekHeatmap.Streak` | Streak badge (hidden when streak <= 1) |
+
+## Props (Root / Shorthand)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| days | WeekDay[] | REQUIRED | Array of 7 day objects |
+| onDayClick | (date: string) => void | — | Called when a past or today day cell is clicked |
+| overdue | number | — | Overdue task count shown in Summary |
+| today | string | — | ISO date override for "today" (defaults to actual today) |
+| className | string | — | Additional CSS classes |
+
+## Props (DayStrip)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| className | string | — | Additional CSS classes |
+
+## Props (Summary, ProgressBar, Streak)
+
+All accept `className` and standard `HTMLDivElement` attributes. They read data from context.
+
+## Related Types
+
+```typescript
+interface WeekDay {
+  date: string       // ISO date string (YYYY-MM-DD)
+  completed: number
+  total: number
+}
+
+type DayStatus = 'complete' | 'partial' | 'none' | 'today' | 'future' | 'empty'
+```
+
+## Day Status Colors
+
+| Status | Condition | Color |
+|--------|-----------|-------|
+| complete | Past day, completed === total | success-9 |
+| partial | Past day, completed > 0 but < total | warning-9 |
+| none | Past day, completed === 0 | error-9 |
+| today | date === today | info-9 with ring |
+| future | date > today | surface-3 |
+| empty | total === 0 | surface-2 dashed border |
+
+## Defaults
+    today = new Date().toISOString().split('T')[0]
+
+## Example
+
+```tsx
+// Props shorthand
+<WeekHeatmap days={days} onDayClick={(date) => navigate(date)} overdue={2} />
+
+// Composable — custom arrangement
+<WeekHeatmap.Root days={days} onDayClick={fn}>
+  <WeekHeatmap.DayStrip />
+  <WeekHeatmap.Streak />
+  <WeekHeatmap.Summary />
+  <WeekHeatmap.ProgressBar />
+</WeekHeatmap.Root>
+```
+
+## Gotchas
+- DayStrip uses `role="grid"` with `role="row"` and `role="gridcell"` for a11y
+- Keyboard navigation: ArrowLeft/ArrowRight moves focus between days, Home/End jump to first/last, Enter/Space activates onDayClick
+- Uses roving tabIndex pattern — only the focused day has tabIndex=0
+- Today's cell gets a MotionPop bounce animation; other days use MotionStagger fade-in
+- Clicking a future or empty day does nothing (no onDayClick fired)
+- Streak counts consecutive past days where completed === total; hidden when streak <= 1
+- ProgressBar uses core Progress component with `color="success"` and `size="sm"`
+- Each Day cell shows a Tooltip with full date and completion count on hover
+- Extends `React.HTMLAttributes<HTMLDivElement>` (Root omits `onDayClick` from native HTML)
+
+## Changes
+### v0.20.0
+- **Added** Initial release — composable WeekHeatmap with Root, DayStrip, Day, Summary, ProgressBar, Streak

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

@@ -37,5 +37,9 @@
 - 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

@@ -48,5 +48,9 @@
 - 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

@@ -47,5 +47,9 @@
 - 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

@@ -24,7 +24,7 @@
 ## Member Shape
     id: string
     name: string
-    image: string | null (optional)
+    image?: string | null
 
 ## Example
 ```jsx
@@ -45,5 +45,9 @@
 - 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

@@ -48,9 +48,14 @@
 - 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-action-row.md

@@ -0,0 +1,159 @@
+# TaskActionRow
+
+Composable task row for action lists, "my tasks", and dashboard views. Shows checkbox, priority, title, labels, project badge, due date, status badge, and navigate button.
+
+- Import: @devalok/shilp-sutra-karm/tasks
+- Server-safe: No
+- Category: tasks
+
+## Compound Parts
+
+| Part | Description |
+|------|-------------|
+| `TaskActionRow` | Props shorthand — renders selected sub-components via show* flags |
+| `TaskActionRow.Root` | Context provider + row wrapper with separator, click, and keyboard activation |
+| `TaskActionRow.Checkbox` | Completion checkbox; stops propagation to avoid triggering row click |
+| `TaskActionRow.Priority` | PriorityIndicator in compact display mode |
+| `TaskActionRow.Title` | Task title text with optional truncation |
+| `TaskActionRow.Labels` | Label badges with overflow count (+N) |
+| `TaskActionRow.ProjectBadge` | Project name badge with optional click handler |
+| `TaskActionRow.DueDate` | Formatted short date with overdue/today color coding |
+| `TaskActionRow.StatusBadge` | StatusBadge mapped from task.stage |
+| `TaskActionRow.Navigate` | Hover-reveal chevron button for opening the task |
+
+## Props (Shorthand)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| task | TaskActionRowTask | REQUIRED | Task data object |
+| onClick | () => void | — | Row click handler; adds role="button" and keyboard activation |
+| onComplete | (taskId: string) => void \| Promise<void> | — | Checkbox completion callback |
+| onContextMenu | (e: React.MouseEvent) => void | — | Right-click handler |
+| showCheckbox | boolean | — | Show completion checkbox |
+| showPriority | boolean | — | Show priority indicator |
+| showLabels | boolean | — | Show label badges |
+| showProject | boolean | — | Show project name badge |
+| showDueDate | boolean | — | Show due date |
+| showNavigate | boolean | — | Show navigate chevron button |
+| showStatusBadge | boolean | — | Show stage status badge |
+| truncateTitle | boolean | — | Truncate long titles with ellipsis |
+| showSeparator | boolean | true | Show bottom border separator |
+| maxLabels | number | 2 | Max visible labels before +N overflow |
+| navigateHref | string | — | URL for navigate button |
+| onProjectClick | (e: React.MouseEvent) => void | — | Project badge click handler |
+| onNavigateClick | (e: React.MouseEvent) => void | — | Navigate button click handler |
+| className | string | — | Additional CSS classes |
+
+## Props (Root)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| task | TaskActionRowTask | REQUIRED | Task data object |
+| children | ReactNode | REQUIRED | Sub-components |
+| onClick | () => void | — | Row click handler |
+| onContextMenu | (e: React.MouseEvent) => void | — | Right-click handler |
+| showSeparator | boolean | true | Show bottom border |
+| className | string | — | Additional CSS classes |
+
+## Props (Checkbox)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| onComplete | (taskId: string) => void \| Promise<void> | — | Called when checkbox is checked |
+
+## Props (Title)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| truncate | boolean | — | Enable text truncation |
+| className | string | — | Additional CSS classes |
+
+## Props (Labels)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| max | number | — | Max visible labels; overflow shows +N badge |
+
+## Props (ProjectBadge)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| onClick | (e: React.MouseEvent) => void | — | Click handler; stops propagation |
+
+## Props (Navigate)
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| href | string | — | URL to navigate to on click |
+| onClick | (e: React.MouseEvent) => void | — | Click handler (takes priority over href) |
+
+## Related Types
+
+```typescript
+type Priority = 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT'
+
+interface TaskActionRowTask {
+  id: string
+  title: string
+  priority: Priority
+  dueDate?: string | null
+  projectName?: string
+  projectId?: string
+  stage?: string
+  isOverdue?: boolean
+  labels?: string[]
+}
+```
+
+## Due Date Colors
+
+| Condition | Color |
+|-----------|-------|
+| isOverdue | error-11 + font-medium |
+| today | warning-11 |
+| default | surface-fg-muted |
+
+## Defaults
+    showSeparator=true, maxLabels=2
+
+## Example
+
+```tsx
+// Props shorthand
+<TaskActionRow
+  task={task}
+  onClick={() => openTask(task.id)}
+  onComplete={(id) => completeTask(id)}
+  showCheckbox
+  showPriority
+  showLabels
+  showDueDate
+  showNavigate
+  truncateTitle
+/>
+
+// Composable — custom layout
+<TaskActionRow.Root task={task} onClick={() => openTask(task.id)}>
+  <TaskActionRow.Checkbox onComplete={completeTask} />
+  <TaskActionRow.Priority />
+  <TaskActionRow.Title truncate />
+  <TaskActionRow.Labels max={3} />
+  <TaskActionRow.DueDate />
+  <TaskActionRow.Navigate onClick={(e) => handleNav(e)} />
+</TaskActionRow.Root>
+```
+
+## Gotchas
+- Root adds `role="button"` and `tabIndex={0}` only when `onClick` is provided
+- Keyboard activation: Enter or Space triggers onClick on Root
+- Checkbox stops click propagation to avoid triggering the row's onClick
+- Navigate button is hover-reveal (opacity-0 by default, visible on group-hover/group-focus-within)
+- ProjectBadge stops propagation on click to avoid triggering row onClick
+- Navigate button stops propagation; if both href and onClick are provided, onClick takes priority
+- Labels, ProjectBadge, DueDate, StatusBadge return null when their data is missing from the task
+- StatusBadge maps task.stage (case-insensitive) to StatusBadge status values; unrecognized stages return null
+- Priority, DueDate, and StatusBadge sub-components accept no custom props
+
+## Changes
+### v0.20.0
+- **Added** Initial release — composable TaskActionRow with Root, Checkbox, Priority, Title, Labels, ProjectBadge, DueDate, StatusBadge, Navigate