@emberai-engg/task-board 0.3.6 → 0.4.1

package/README.md

@@ -1,6 +1,8 @@
 # @emberai-engg/task-board
 
-Reusable Kanban task board component with built-in create/detail UI.
+Reusable Kanban task board component with built-in create/detail UI, threaded
+discussions with highlight-to-comment, structured outstanding questions, file
+attachments backed by Google Cloud Storage, and a WYSIWYG markdown editor.
 
 ## Installation
 
@@ -8,9 +10,21 @@ Reusable Kanban task board component with built-in create/detail UI.
 npm install @emberai-engg/task-board
 ```
 
-## Quick Start
+Then import the bundled stylesheet once at app start (e.g. in `app/layout.tsx`):
 
-No render props needed. The package ships with a complete UI out of the box:
+```ts
+import '@emberai-engg/task-board/styles.css';
+```
+
+That's it. The stylesheet is self-contained — Tailwind utilities used by the
+package are pre-compiled into it, so you don't need to add anything to your own
+Tailwind config or `@source` paths. The bundled CSS deliberately omits the
+Tailwind preflight so it won't trample your app's own resets.
+
+## Quick Start — list page only (slide-over detail)
+
+The default `<TaskBoard>` ships with a built-in `<TaskDetailPanel>` slide-over
+that opens when a task card is clicked.
 
 ```tsx
 import { TaskBoardProvider, TaskBoard } from '@emberai-engg/task-board';
@@ -23,17 +37,8 @@ function App() {
   return (
     <TaskBoardProvider
       apiClient={apiClient}
-      user={{
-        username: user.username,
-        name: user.name,
-        email: user.email,
-        apps: user.apps,
-        is_internal: user.is_internal,
-        is_reviewer: user.is_reviewer,
-      }}
-      projects={[
-        { slug: 'my-project', name: 'My Project' },
-      ]}
+      user={user}
+      projects={[{ slug: 'my-project', name: 'My Project' }]}
     >
       <TaskBoard onShareFeedback={() => router.push('/feedback')} />
     </TaskBoardProvider>
@@ -41,14 +46,63 @@ function App() {
 }
 ```
 
-This gives you:
-- Kanban board with drag-and-drop
-- Built-in **CreateTaskModal** (two-column layout with title, structured description, priority, status, tags)
-- Built-in **TaskDetailPanel** (slide-over with properties grid, description sections, activity timeline, comments with @mentions)
-- Notification bell with polling
-- Tag filtering
-- Share links
-- Loading skeletons and empty states
+## Quick Start — list + dedicated detail route
+
+For larger workflows (description sections, outstanding questions, attachments,
+threads with highlight-to-comment), pair `<TaskBoard>` on the list route with
+`<TaskDetailView>` on a separate detail route.
+
+```tsx
+// app/task-board/page.tsx
+function TaskBoardPage() {
+  const router = useRouter();
+  return (
+    <TaskBoardProvider apiClient={apiClient} user={user} projects={projects}>
+      <TaskBoard
+        onTaskOpen={(task) => router.push(`/task-board/${task.id}?project=${task.project_slug}`)}
+      />
+    </TaskBoardProvider>
+  );
+}
+
+// app/task-board/[taskId]/page.tsx
+function TaskDetailPage({ params }: { params: { taskId: string } }) {
+  const router = useRouter();
+  return (
+    <TaskBoardProvider apiClient={apiClient} user={user} projects={projects}>
+      <TaskDetailView
+        taskId={params.taskId}
+        onBack={() => router.push('/task-board')}
+        onNavigateToTask={(id, slug) => router.push(`/task-board/${id}?project=${slug}`)}
+        onDeleted={() => router.push('/task-board')}
+      />
+    </TaskBoardProvider>
+  );
+}
+```
+
+When `onTaskOpen` is set, `<TaskBoard>` skips its built-in slide-over panel —
+the consumer owns navigation.
+
+## What the detail page gives you
+
+- **Inline-editable title**, click-to-edit
+- **Status / priority / share / delete** in the header
+- **Four description sections** (Problem, User Story, Proposed Behavior,
+  Acceptance Criteria), each with a Draft/Approved toggle
+- **WYSIWYG markdown editor** — bold/italic, H2, bullet/numbered lists with
+  multi-line support and auto-incrementing numbers, blockquote, inline code,
+  @mentions. Stores markdown on disk via `mdToHtml`/`htmlToMd` round-trip.
+- **Outstanding Questions** — structured list with awaiting/answered status,
+  per-question replies, mark-answered/reopen, author-only delete
+- **Attachments** — three groups (Images / Files / Links & recordings), GCS
+  upload, signed read URLs, hover-to-delete
+- **Threads panel** — Threads + Activity tabs, collapse toggle (persisted),
+  active/completed filter, per-thread title and complete/reopen, thread
+  composer with attachments and public/internal toggle
+- **Highlight-to-comment** — select text in a description section to attach a
+  thread anchor; clicking the anchor pill scrolls back to the section and
+  pulses it
 
 ## Props / Config Reference
 
@@ -63,6 +117,7 @@ This gives you:
 | `priorities` | `PriorityConfig[]` | No | Priority levels |
 | `tags` | `TagConfig[]` | No | Predefined tags |
 | `apiBasePath` | `string` | No | API prefix (defaults to `/api/v1/taskboard`) |
+| `internalLabel` | `string` | No | Label on internal-only comment chips. Defaults to `"Internal"`. |
 | `features` | `object` | No | Feature flags for enabling/disabling features |
 | `onTaskCreate` | `(task) => void` | No | Callback on task creation |
 | `onTaskUpdate` | `(task) => void` | No | Callback on task update |
@@ -76,52 +131,32 @@ This gives you:
 | `className` | `string` | CSS class for the outer container |
 | `headerActions` | `ReactNode` | Additional buttons in the header |
 | `onShareFeedback` | `() => void` | Callback for Share Feedback button. Hidden if omitted. |
-| `onTaskOpen` | `(task) => void` | Callback when a task is clicked |
-| `renderTaskDetail` | `function` | Override for task detail panel (built-in used if omitted) |
+| `onTaskOpen` | `(task) => void` | When provided, the built-in slide-over panel is suppressed and the consumer owns navigation. |
+| `renderTaskDetail` | `function` | Override for task detail panel (built-in slide-over used if omitted) |
 | `renderCreateTask` | `function` | Override for create task modal (built-in used if omitted) |
 
-### Overriding built-in UI
-
-If you need custom create/detail UI, pass render props:
-
-```tsx
-<TaskBoard
-  renderCreateTask={({ projectSlug, defaultStatus, onClose, onCreate }) => (
-    <MyCustomCreateModal ... />
-  )}
-  renderTaskDetail={({ task, onClose, onUpdate }) => (
-    <MyCustomDetailPanel ... />
-  )}
-/>
-```
+### `TaskDetailView`
 
-## Using Individual Components
-
-```tsx
-import {
-  TaskCard, PriorityBadge, UserAvatar,
-  CreateTaskModal, TaskDetailPanel,
-  useTaskActions,
-} from '@emberai-engg/task-board';
-
-// Use hooks independently
-function MyCustomUI() {
-  const { createTask, moveTask } = useTaskActions(tasks, setTasks, fetchTasks);
-  // ...
-}
-
-// Use small components
-<PriorityBadge priority="high" />
-<UserAvatar name="John Smith" size="sm" showTooltip />
-```
+| Prop | Type | Description |
+|------|------|-------------|
+| `taskId` | `string` | Required. The task to show. |
+| `onBack` | `() => void` | Callback for the back link. Use this for SPA routing. |
+| `backHref` | `string` | href for the back link if `onBack` is omitted. |
+| `breadcrumb` | `ReactNode` | Slot rendered above the main content (e.g. consumer breadcrumb bar). |
+| `onDeleted` | `(task) => void` | Called after successful delete; consumer should navigate away. |
+| `onNavigateToTask` | `(id, projectSlug) => void` | Provide to enable prev/next buttons. |
+| `buildShareUrl` | `(task) => string` | Override the share URL. Defaults to `${origin}/task-board/${id}?project=${slug}`. |
 
 ## Hooks API
 
 | Hook | Purpose |
 |------|---------|
 | `useTaskBoard()` | Board state: projects, tasks, loading, pagination |
-| `useTaskActions(tasks, setTasks, fetchTasks)` | CRUD: create, update, delete, move tasks |
+| `useTaskActions(...)` | CRUD: create, update, delete, move tasks |
 | `useTaskDetail(taskId)` | Single task: comments, activity, field updates |
+| `useTaskQuestions(taskId, initial?)` | Outstanding Questions for a task: list + create / update / delete / reply |
+| `useTaskAttachments(taskId, initial?)` | Attachments: list + uploadFile / addLink / remove |
+| `useHighlightAnchor()` | Selection-driven anchor flow: bubble + pendingAnchor + focusAnchor |
 | `useShareLink()` | Copy shareable task URLs |
 
 ## Feature Flags
@@ -129,19 +164,49 @@ function MyCustomUI() {
 ```tsx
 <TaskBoardProvider
   features={{
-    dragAndDrop: true,      // Drag-and-drop between columns
-    comments: true,         // Comment system
-    mentions: true,         // @mention users
-    notifications: true,    // Notification bell
-    internalComments: true, // Internal-only comments
-    tags: true,             // Tag system
-    sharing: true,          // Shareable task links
-    filters: true,          // Tag filtering
-    unreadIndicators: true, // Unread dots on cards
+    dragAndDrop: true,
+    comments: true,
+    mentions: true,
+    notifications: true,
+    internalComments: true,
+    tags: true,
+    sharing: true,
+    filters: true,
+    unreadIndicators: true,
   }}
 />
 ```
 
+## Backwards-compatibility notes (v0.3 → v0.4)
+
+- The `StructuredDescription.open_questions` field still exists and is preserved
+  on existing tasks, but is no longer rendered in the description editor — the
+  Outstanding Questions feature replaces it. Tasks created before v0.4 keep
+  their content; new tasks have an empty `open_questions` field.
+- `Comment` gained optional `parent_id`, `title`, `thread_status`, `anchor`,
+  `attachment_ids`. Existing comments without these fields render the same as
+  before.
+
+## Backend
+
+The `backend-reference/` folder contains a Python FastAPI reference implementation:
+
+- `models/taskboard.py` — Pydantic models (Tasks / Comments / Threads /
+  Questions / Attachments + the `ThreadAnchor` schema)
+- `api/taskboard.py` — full FastAPI router covering all v0.4 endpoints,
+  including the threads, questions, and attachments routes
+- `services/gcs_storage.py` — Google Cloud Storage helper for file uploads.
+  Supports inline service-account env vars, `GOOGLE_APPLICATION_CREDENTIALS`,
+  and Application Default Credentials
+- `services/config_snippet.py` — settings fields and sample `.env` values
+
+Add `google-cloud-storage>=2.18.0` to `requirements.txt`. Without
+`GCP_STORAGE_BUCKET` set, link attachments still work but image/file uploads
+return a clean 503.
+
+See [`backend-reference/README.md`](backend-reference/README.md) for the
+adaptation guide.
+
 ## Development
 
 ```bash
@@ -151,10 +216,6 @@ npm run build  # Production build
 npm test       # Run tests
 ```
 
-## Backend
-
-The `backend-reference/` folder contains a Python FastAPI reference implementation for the task board API. Copy it into your app's backend and adapt the auth and database setup to match your app. See [`backend-reference/README.md`](backend-reference/README.md) for details.
-
 ## License
 
 Private — internal use only.