@burdenoff/planmagnet-fe-sdk 2026.703.1

package/README.md

@@ -0,0 +1,162 @@
+# @burdenoff/planmagnet-fe-sdk
+
+Embeddable, **product-agnostic** PlanMagnet task UI. Mirrors the
+`@burdenoff/fluidgrids-fe-sdk` embed contract: a standalone component that can
+self-provision an Apollo client from a URL **or** accept a host-injected client
+(BYO-Apollo), plus a provider-less core for shells that already own an
+`ApolloProvider`.
+
+Phase 1 ships a **read-only task board** (`TaskBoard` / `TaskBoardCore`) over
+`wspace-planmagnet-svc`. It is farm-free — no HealthyBowl Field/Crop logic; that
+glue is layered by the host app later.
+
+## Install
+
+```bash
+bun add @burdenoff/planmagnet-fe-sdk
+```
+
+Peer deps (provided by the host): `react`, `react-dom`, and optionally
+`@burdenoff/fe-libs` (used for the `Card` primitive; externalized, never bundled).
+
+Import the stylesheet once (skip if your host already ships fe-libs tokens):
+
+```ts
+import "@burdenoff/planmagnet-fe-sdk/styles.css";
+```
+
+## Embed contract
+
+Three mount patterns:
+
+### 1. Standalone (URL mode) — SDK builds its own client
+
+```tsx
+import { TaskBoard } from "@burdenoff/planmagnet-fe-sdk";
+
+<TaskBoard
+  apiGatewayUrl="https://graphqlworkspaces.burdenoff.com"
+  authToken={platformToken}
+  workspaceToken={workspaceToken}
+  workspaceId="ws-123"
+  tenantId="tenant-abc"
+  onTaskClick={(task) => console.log(task)}
+/>;
+```
+
+The SDK appends `/workspaces/graphql` to `apiGatewayUrl` (unless it already ends
+in `/graphql`) and sends the dual-token workspace headers:
+
+| Header | Source |
+| --- | --- |
+| `authorization: Bearer <authToken>` | platform identity |
+| `x-workspace-authorization: Bearer <workspaceToken>` | workspace access |
+| `x-workspace-id` | `workspaceId` |
+| `x-tenant-id` | `tenantId` (optional) |
+
+### 2. BYO-Apollo (host injects its authed client)
+
+```tsx
+<TaskBoard workspaceClient={hostApolloClient} workspaceId="ws-123" readonly />
+```
+
+`workspaceClient` takes priority over `apiGatewayUrl`. This is the path for
+microfe / HealthyBowl shells that already have an authed workspace client.
+
+### 3. Provider + Core (share a client across several SDK components)
+
+```tsx
+import { PlanMagnetProvider, TaskBoardCore } from "@burdenoff/planmagnet-fe-sdk";
+
+<PlanMagnetProvider apiGatewayUrl={url} authToken={token} workspaceId="ws-123">
+  <TaskBoardCore projectId="proj-1" onTaskClick={openTask} />
+</PlanMagnetProvider>;
+```
+
+`TaskBoardCore` reads Apollo from the ambient `ApolloProvider` and never creates
+a client or assumes a router. `PlanMagnetProvider` **always** mounts its own
+`ApolloProvider`, so an embedded board works inside any host page.
+
+## Component props
+
+### `TaskBoardCoreProps`
+
+| Prop | Type | Notes |
+| --- | --- | --- |
+| `projectId?` | `string` | Client-side project scope (Phase 1). |
+| `columns?` | `BoardColumn[]` | Defaults to `DEFAULT_BOARD_COLUMNS`. |
+| `readonly?` | `boolean` | Reserved; Phase 1 board is read-only regardless. |
+| `hideHeader?` | `boolean` | Hide title + count. |
+| `hideFilters?` | `boolean` | Hide priority/type filter bar. |
+| `hiddenFields?` | `string[]` | Suppress card fields: `key`, `priority`, `type`, `labels`, `storyPoints`, `assignee`, `dueDate`. |
+| `onTaskClick?` | `(task: Task) => void` | Card click. |
+| `className?` | `string` | Root container classes. |
+| `workspaceId?` | `string` | Explicit override; else from provider context. |
+
+`TaskBoardProps` extends the above with the client-provisioning props
+(`apiGatewayUrl`, `authToken`, `workspaceToken`, `workspaceId` (required),
+`tenantId`, `organizationId`, `trustedOrigins`, `onAuthError`, `workspaceClient`).
+
+## Client injection API
+
+```ts
+import {
+  createPlanMagnetClient,
+  setPlanMagnetClient,
+  getPlanMagnetClient,
+  getPlanMagnetClientSafe,
+  isPlanMagnetClientReady,
+  waitForPlanMagnetClient,
+  resetPlanMagnetClient,
+} from "@burdenoff/planmagnet-fe-sdk";
+```
+
+`PlanMagnetProvider` publishes the active client to a module singleton so
+non-hook code can reach it via `getPlanMagnetClient()`.
+
+## GraphQL
+
+Bundled operation documents: `LIST_WORK_ITEMS`, `GET_PROJECTS`,
+`CREATE_WORK_ITEM`, `UPDATE_WORK_ITEM`, `MOVE_WORK_ITEM`. They target the
+prefixed gateway roots (`planmagnetWorkItems`, …) with un-prefixed input names to
+match the local codegen SDL.
+
+> Phase 1 hand-writes these docs + the domain types so the SDK compiles without a
+> live `schema:pull`. Phase 2 replaces them with codegen output
+> (`bun run schema:pull && bun run codegen` against a wspace gateway on `:4003`)
+> and adds the `WorkItemLink` cross-product ops.
+
+## Local development
+
+```bash
+bun install
+bun run build        # tsup → dist/ (+ copies styles.css)
+bun run type:check   # tsc --noEmit
+bun run dev          # tsup --watch
+```
+
+Embed-test harness (renders `TaskBoard` against an Apollo `MockedProvider`, no
+backend needed):
+
+```bash
+cd dev && bun install && bun run dev   # Vite on :5174
+```
+
+## Status (Phase 1)
+
+- [x] Package scaffold mirroring fluidgrids-fe-sdk
+- [x] `PlanMagnetProvider` with client-injection (URL / BYO)
+- [x] `createPlanMagnetClient` + module-singleton set/get/reset
+- [x] `TaskBoard` (standalone) + `TaskBoardCore` (BYO), semantic-token themed
+- [x] Bundled list/project GraphQL ops
+- [x] Mocked embed-test harness
+- [ ] `CreateTask` form (Phase 2 — needs a project selector; the microfe stub is broken)
+- [ ] `TaskList` / `TaskDetail`
+- [ ] Drag-to-move (`MOVE_WORK_ITEM`) + write mutations wired to UI
+- [ ] `WorkItemLink` cross-product ops (needs `schema:pull`)
+- [ ] Codegen-generated types (replace hand-written slices)
+- [ ] Unit tests (Vitest / bun test) ≥ 80%
+
+## License
+
+Proprietary — Burdenoff Consultancy Services Pvt. Ltd.