@devalok/shilp-sutra-karm 0.19.0 → 0.20.0

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/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

package/package.json

@@ -1,82 +1,82 @@
-{
-  "name": "@devalok/shilp-sutra-karm",
-  "version": "0.19.0",
-  "description": "Domain components for Karm — board, tasks, chat, dashboard, client, and admin",
-  "license": "MIT",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "sideEffects": [
-    "**/*.css"
-  ],
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "default": "./dist/index.js",
-      "types": "./dist/index.d.ts"
-    },
-    "./board": {
-      "import": "./dist/board/index.js",
-      "default": "./dist/board/index.js",
-      "types": "./dist/board/index.d.ts"
-    },
-    "./tasks": {
-      "import": "./dist/tasks/index.js",
-      "default": "./dist/tasks/index.js",
-      "types": "./dist/tasks/index.d.ts"
-    },
-    "./chat": {
-      "import": "./dist/chat/index.js",
-      "default": "./dist/chat/index.js",
-      "types": "./dist/chat/index.d.ts"
-    },
-    "./dashboard": {
-      "import": "./dist/dashboard/index.js",
-      "default": "./dist/dashboard/index.js",
-      "types": "./dist/dashboard/index.d.ts"
-    },
-    "./client": {
-      "import": "./dist/client/index.js",
-      "default": "./dist/client/index.js",
-      "types": "./dist/client/index.d.ts"
-    },
-    "./admin": {
-      "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"
-  ],
-  "scripts": {
-    "build": "vite build && node scripts/inject-use-client.mjs",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "prepublishOnly": "pnpm build"
-  },
-  "peerDependencies": {
-    "@devalok/shilp-sutra": ">=0.18.0",
-    "@tabler/icons-react": "^3.0.0",
-    "framer-motion": "^12.0.0",
-    "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
-  },
-  "devDependencies": {
-    "@devalok/shilp-sutra": "workspace:*",
-    "@dnd-kit/core": "^6.3.1",
-    "@dnd-kit/sortable": "^10.0.0",
-    "@dnd-kit/utilities": "^3.2.2",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "date-fns": "^4.1.0",
-    "framer-motion": "^12.36.0",
-    "react-markdown": "^10.1.0",
-    "tailwind-merge": "^3.0.1"
-  }
-}
+{
+  "name": "@devalok/shilp-sutra-karm",
+  "version": "0.20.0",
+  "description": "Domain components for Karm — board, tasks, chat, dashboard, client, and admin",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "default": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./board": {
+      "import": "./dist/board/index.js",
+      "default": "./dist/board/index.js",
+      "types": "./dist/board/index.d.ts"
+    },
+    "./tasks": {
+      "import": "./dist/tasks/index.js",
+      "default": "./dist/tasks/index.js",
+      "types": "./dist/tasks/index.d.ts"
+    },
+    "./chat": {
+      "import": "./dist/chat/index.js",
+      "default": "./dist/chat/index.js",
+      "types": "./dist/chat/index.d.ts"
+    },
+    "./dashboard": {
+      "import": "./dist/dashboard/index.js",
+      "default": "./dist/dashboard/index.js",
+      "types": "./dist/dashboard/index.d.ts"
+    },
+    "./client": {
+      "import": "./dist/client/index.js",
+      "default": "./dist/client/index.js",
+      "types": "./dist/client/index.d.ts"
+    },
+    "./admin": {
+      "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"
+  ],
+  "scripts": {
+    "build": "vite build && node scripts/inject-use-client.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "prepublishOnly": "pnpm build"
+  },
+  "peerDependencies": {
+    "@devalok/shilp-sutra": ">=0.18.0",
+    "@tabler/icons-react": "^3.0.0",
+    "framer-motion": "^12.0.0",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19"
+  },
+  "devDependencies": {
+    "@devalok/shilp-sutra": "workspace:*",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "framer-motion": "^12.36.0",
+    "react-markdown": "^10.1.0",
+    "tailwind-merge": "^3.0.1"
+  }
+}