@burdenoff/planmagnet-fe-sdk 2026.703.1 → 2026.703.2

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import * as react from 'react';
-import { ReactNode, HTMLAttributes } from 'react';
+import { DragEvent, ReactNode, HTMLAttributes, ComponentType } from 'react';
 import { ApolloClient } from '@apollo/client/core';
 import * as graphql from 'graphql';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
+import { LucideProps } from 'lucide-react';
 import { ClassValue } from 'clsx';
 
 /**
@@ -178,23 +179,64 @@ declare const TASK_STATUSES: TaskStatus[];
  */
 declare function enumLabel(value: string): string;
 
+/**
+ * Optional host hook: resolve an assignee id to a display name (the SDK has no
+ * user directory). When omitted the avatar falls back to id-initials.
+ */
+type ResolveAssignee = (assigneeId: string) => {
+    name?: string | null;
+} | null | undefined;
+interface TaskCardProps {
+    task: Task;
+    /** Field names to hide (key/type/priority/labels/storyPoints/assignee/dueDate). */
+    hidden?: ReadonlySet<string>;
+    onClick?: (task: Task) => void;
+    /** Enable native drag (board wires this to move-between-columns). */
+    draggable?: boolean;
+    onDragStart?: (task: Task, e: DragEvent<HTMLDivElement>) => void;
+    onDragEnd?: (task: Task, e: DragEvent<HTMLDivElement>) => void;
+    /** True while this card is the one being dragged. */
+    dragging?: boolean;
+    resolveAssignee?: ResolveAssignee;
+    className?: string;
+}
+/**
+ * TaskCard — a Linear-style board card. Presentational + prop-driven; renders
+ * only real fields (no invented assignee names or entity links). Semantic
+ * tokens only.
+ */
+declare function TaskCard({ task, hidden, onClick, draggable, onDragStart, onDragEnd, dragging, resolveAssignee, className, }: TaskCardProps): react.JSX.Element;
+
 interface TaskBoardCoreProps {
     /** Scope the board to one project (client-side filter for Phase 1). */
     projectId?: string;
     /** Board columns to render (defaults to DEFAULT_BOARD_COLUMNS). */
     columns?: BoardColumn[];
-    /** Read-only mode — hides interactive affordances (no create/drag in Phase 1 either way). */
+    /** Read-only mode — disables drag-to-move. */
     readonly?: boolean;
-    /** Hide the board header (title + count). */
+    /** Hide the board's own header (title + count). */
     hideHeader?: boolean;
-    /** Hide the priority/type filter bar. */
+    /**
+     * @deprecated Filtering is now controlled by the parent toolbar via the
+     * `priority`/`type`/`search` props. Accepted for backward compatibility; the
+     * board no longer renders its own filter chips.
+     */
     hideFilters?: boolean;
+    /** Controlled priority filter ("ALL" or a specific priority). */
+    priority?: TaskPriority | "ALL";
+    /** Controlled type filter ("ALL" or a specific type). */
+    type?: TaskType | "ALL";
+    /** Controlled free-text search (matches title/key/labels). */
+    search?: string;
+    /** Controlled assignee filter (actor id). */
+    assigneeId?: string;
     /**
-     * Field names to hide on each task card. Product-agnostic hook so hosts can
-     * suppress fields that don't apply. Supported: 'key' | 'priority' | 'type' |
-     * 'labels' | 'storyPoints' | 'assignee' | 'dueDate'.
+     * Field names to hide on each task card. Supported: 'key' | 'priority' |
+     * 'type' | 'labels' | 'storyPoints' | 'assignee' | 'dueDate'.
      */
     hiddenFields?: string[];
+    /** Optional host hook to resolve an assignee id → display name. */
+    resolveAssignee?: ResolveAssignee;
     /** Called when a task card is clicked. */
     onTaskClick?: (task: Task) => void;
     /** Extra classes on the root container. */
@@ -208,12 +250,14 @@ interface TaskBoardCoreProps {
 /**
  * TaskBoardCore — provider-less, prop-driven, product-agnostic Kanban board.
  *
- * - Reads Apollo via the ambient `<ApolloProvider>` (BYO). It never creates a
- *   client and never assumes a router.
+ * - Reads Apollo via the ambient `<ApolloProvider>` (BYO). Never creates a
+ *   client, never assumes a router.
  * - `workspaceId` comes from a prop or the PlanMagnetProvider context.
- * - Read-only in Phase 1 (no drag/create). Farm-free: no Field/Crop logic.
+ * - Linear-style columns + cards, with native drag-to-move between columns
+ *   (optimistic cache update + `UPDATE_WORK_ITEM`; reverts on error). Filtering
+ *   is controlled by the parent toolbar. Farm-free, semantic-token only.
  */
-declare function TaskBoardCore({ projectId, columns, readonly: _readonly, hideHeader, hideFilters, hiddenFields, onTaskClick, className, workspaceId: workspaceIdProp, }: TaskBoardCoreProps): react.JSX.Element;
+declare function TaskBoardCore({ projectId, columns, readonly, hideHeader, priority, type, search, assigneeId, hiddenFields, resolveAssignee, onTaskClick, className, workspaceId: workspaceIdProp, }: TaskBoardCoreProps): react.JSX.Element;
 
 interface TaskBoardProps extends TaskBoardCoreProps {
     /** Workspace API gateway URL (URL mode). */
@@ -368,14 +412,16 @@ interface TaskListCoreProps {
     search?: string;
     /** Columns to render (order preserved). */
     columns?: TaskListColumn[];
-    /** Sort key (client-side). */
+    /** Initial sort key. */
     sortBy?: TaskListSort;
-    /** Sort direction. Defaults to ascending. */
+    /** Initial sort direction. Defaults to ascending. */
     sortDir?: "asc" | "desc";
     /** Hide the header (title + count). */
     hideHeader?: boolean;
     /** Called with the work-item id when a row is clicked. */
     onSelect?: (id: string) => void;
+    /** Optional host hook to resolve an assignee id → display name. */
+    resolveAssignee?: ResolveAssignee;
     /** Max items to fetch (pagination.first). Defaults to 200. */
     limit?: number;
     /** Extra classes on the root container. */
@@ -386,11 +432,12 @@ interface TaskListCoreProps {
 /**
  * TaskListCore — provider-less, prop-driven compact list/table of work items.
  *
- * Same data source as TaskBoardCore (`LIST_WORK_ITEMS`) but a dense table
- * layout instead of a kanban. Filters map to the server-side `WorkItemFilter`;
- * sort is applied client-side. BYO-Apollo, semantic-token only, farm-free.
+ * Same data source as TaskBoardCore (`LIST_WORK_ITEMS`) but a dense, Linear-style
+ * table: status pills, priority signal bars, assignee avatars, click-to-sort
+ * headers. Filters map to the server-side filter; sort is client-side.
+ * BYO-Apollo, semantic-token only, farm-free.
  */
-declare function TaskListCore({ projectId, status, type, priority, assigneeId, search, columns, sortBy, sortDir, hideHeader, onSelect, limit, className, workspaceId: workspaceIdProp, }: TaskListCoreProps): react.JSX.Element;
+declare function TaskListCore({ projectId, status, type, priority, assigneeId, search, columns, sortBy, sortDir, hideHeader, onSelect, resolveAssignee, limit, className, workspaceId: workspaceIdProp, }: TaskListCoreProps): react.JSX.Element;
 
 interface TaskListProps extends TaskListCoreProps {
     /** Workspace API gateway URL (URL mode). */
@@ -431,6 +478,62 @@ interface TaskListProps extends TaskListCoreProps {
  */
 declare function TaskList({ apiGatewayUrl, authToken, workspaceToken, workspaceId, tenantId, organizationId, trustedOrigins, onAuthError, workspaceClient, ...coreProps }: TaskListProps): react.JSX.Element;
 
+type TimelineMode = "week" | "month";
+interface TaskTimelineCoreProps {
+    /** Scope the timeline to one project (client-side filter). */
+    projectId?: string;
+    /** Controlled priority filter ("ALL" or a specific priority). */
+    priority?: TaskPriority | "ALL";
+    /** Controlled type filter ("ALL" or a specific type). */
+    type?: TaskType | "ALL";
+    /** Controlled free-text search (matches title/key/labels). */
+    search?: string;
+    /** Controlled assignee filter (actor id). */
+    assigneeId?: string;
+    /** Default mode. */
+    defaultMode?: TimelineMode;
+    /** Called with the work-item id when a task chip is clicked. */
+    onSelect?: (id: string) => void;
+    /** Optional host hook to resolve an assignee id → display name. */
+    resolveAssignee?: ResolveAssignee;
+    className?: string;
+    workspaceId?: string;
+}
+/**
+ * TaskTimelineCore — a week/month schedule of work items by due date.
+ *
+ * The spec's "week/month timeline that shows when work is scheduled and what's
+ * due". We only have a single `dueDate` per work item (no start/end), so this is
+ * an agenda-style schedule (chip on its due day) rather than a span Gantt —
+ * honest to the data. Overdue and undated work is surfaced explicitly so nothing
+ * hides. BYO-Apollo, semantic-token only, farm-free.
+ */
+declare function TaskTimelineCore({ projectId, priority, type, search, assigneeId, defaultMode, onSelect, resolveAssignee, className, workspaceId: workspaceIdProp, }: TaskTimelineCoreProps): react.JSX.Element;
+
+/** The three task views the toolbar can switch between. */
+type TaskView = "board" | "list" | "timeline";
+interface TaskToolbarProps {
+    view: TaskView;
+    onViewChange: (view: TaskView) => void;
+    /** Which views to offer (order preserved). Defaults to all three. */
+    views?: TaskView[];
+    search: string;
+    onSearchChange: (search: string) => void;
+    priority: TaskPriority | "ALL";
+    onPriorityChange: (priority: TaskPriority | "ALL") => void;
+    type: TaskType | "ALL";
+    onTypeChange: (type: TaskType | "ALL") => void;
+    onNewTask?: () => void;
+    canCreate?: boolean;
+    className?: string;
+}
+/**
+ * TaskToolbar — the single Linear-style control bar for the Tasks experience:
+ * view tabs (Board / List / Timeline) + search + priority/type filters + a
+ * "New task" action. Fully controlled; semantic-token only.
+ */
+declare function TaskToolbar({ view, onViewChange, views, search, onSearchChange, priority, onPriorityChange, type, onTypeChange, onNewTask, canCreate, className, }: TaskToolbarProps): react.JSX.Element;
+
 /** Fields that can be hidden / suppressed on the detail view + edit form. */
 type TaskDetailField = "description" | "type" | "status" | "priority" | "assignee" | "dueDate" | "labels" | "storyPoints";
 interface TaskDetailCoreProps {
@@ -519,22 +622,27 @@ interface TasksPageCoreProps {
      * omitted the board still renders read-only-ish (create is disabled).
      */
     projectId?: string;
-    /** Scope the board to a single project (client-side filter). */
+    /** Scope the views to a single project (client-side filter). */
     boardProjectId?: string;
     /** Board columns to render (defaults to DEFAULT_BOARD_COLUMNS). */
     columns?: BoardColumn[];
-    /** Read-only — hides the "New task" button and disables detail editing. */
+    /** Read-only — hides the "New task" button, disables drag + detail editing. */
     readonly?: boolean;
     /**
      * Field names to hide across the board cards, create form, and detail view.
      * A product-agnostic hook so hosts can suppress fields that don't apply.
      */
     hiddenFields?: TasksPageField[];
-    /** Hide the board's priority/type filter bar. */
-    hideFilters?: boolean;
+    /** Which views to offer (order preserved). Defaults to all three. */
+    views?: TaskView[];
+    /** Initial view. Defaults to "board". */
+    defaultView?: TaskView;
+    /** Optional host hook to resolve an assignee id → display name. */
+    resolveAssignee?: ResolveAssignee;
     /**
-     * Header/title slot. Pass a string for the default heading, or any node to
-     * fully own the header area. Omit for no header.
+     * Header/title slot rendered ABOVE the toolbar. Pass a string for the default
+     * heading, or any node to fully own the title area. Omit for no title (e.g.
+     * when the host shell already renders the page title).
      */
     header?: ReactNode;
     /** Called after a successful create OR update (board is refetched first). */
@@ -548,20 +656,14 @@ interface TasksPageCoreProps {
 }
 /**
  * TasksPageCore — a complete, provider-less, BYO-Apollo Tasks experience in a
- * single mount. Composes the existing `TaskBoardCore`, `CreateTaskCore`, and
- * `TaskDetailCore` so a host app (e.g. HealthyBowl) doesn't have to wire the
- * three together itself:
+ * single mount. A Linear-style shell: one toolbar (Board / List / Timeline tabs
+ * + search + priority/type filters + "New task"), the selected view, a create
+ * modal, and a click-to-open detail drawer.
  *
- *  - renders the kanban `TaskBoardCore`,
- *  - a "New task" button opens `CreateTaskCore` (modal or inline),
- *  - clicking a card opens `TaskDetailCore` (drawer or inline) with inline edit,
- *  - `CreateTaskCore.onCreated` + `TaskDetailCore.onUpdated` refetch the board.
- *
- * BYO-Apollo like the sibling cores: reads the ambient `<ApolloProvider>` and
- * takes `workspaceId` from a prop or the PlanMagnetProvider context. Semantic
- * tokens only, farm-free, strict TS.
+ * BYO-Apollo: reads the ambient `<ApolloProvider>` and takes `workspaceId` from
+ * a prop or the PlanMagnetProvider context. Semantic tokens only, farm-free.
  */
-declare function TasksPageCore({ workspaceId: workspaceIdProp, projectId, boardProjectId, columns, readonly, hiddenFields, hideFilters, header, onTaskSaved, createSurface, detailSurface, className, }: TasksPageCoreProps): react.JSX.Element;
+declare function TasksPageCore({ workspaceId: workspaceIdProp, projectId, boardProjectId, columns, readonly, hiddenFields, views, defaultView, resolveAssignee, header, onTaskSaved, createSurface, detailSurface, className, }: TasksPageCoreProps): react.JSX.Element;
 
 interface TasksPageProps extends TasksPageCoreProps {
     /** Workspace API gateway URL (URL mode). */
@@ -816,6 +918,82 @@ interface BadgeProps extends HTMLAttributes<HTMLSpanElement>, VariantProps<typeo
  */
 declare function Badge({ className, variant, ...props }: BadgeProps): react.JSX.Element;
 
+declare const SIZES: {
+    readonly sm: "h-5 w-5 text-[9px]";
+    readonly md: "h-6 w-6 text-[10px]";
+    readonly lg: "h-8 w-8 text-xs";
+};
+interface AvatarProps {
+    /** Assignee actor id (used for the deterministic tint + fallback initials). */
+    id?: string | null;
+    /** Resolved display name, if the host has a directory. */
+    name?: string | null;
+    size?: keyof typeof SIZES;
+    className?: string;
+}
+declare function Avatar({ id, name, size, className }: AvatarProps): react.JSX.Element;
+
+/**
+ * Linear-style task indicators — status, priority, type.
+ *
+ * A hard rule of the codebase is "semantic tokens only, never raw colors". The
+ * default token palette only exposes a handful of hues (primary / secondary /
+ * muted / accent / destructive), which is not enough to give each of the six
+ * statuses its own distinct color like a raw-palette design would.
+ *
+ * So — exactly like Linear — status is differentiated primarily by icon SHAPE
+ * (dashed → empty → dotted → filled → check), with a subtle muted→primary tone
+ * progression, and priority by a filled-BAR count. This reads as a polished PM
+ * tool while staying 100% within the semantic-token contract.
+ */
+interface StatusMeta {
+    icon: ComponentType<LucideProps>;
+    /** Icon tone (semantic token). */
+    tone: string;
+}
+/**
+ * Per-status icon + tone. Shape carries the meaning; tone progresses from muted
+ * (not started) toward primary (in flight / done). Overridable by hosts only
+ * via the column labels, never by raw color.
+ */
+declare const STATUS_META: Record<TaskStatus, StatusMeta>;
+interface StatusIconProps {
+    status: TaskStatus;
+    className?: string;
+}
+/** A single status glyph — shape-differentiated, token-toned. */
+declare function StatusIcon({ status, className }: StatusIconProps): react.JSX.Element;
+interface StatusPillProps {
+    status: TaskStatus;
+    className?: string;
+}
+/** Status as a compact bordered pill (icon + label) — used in the list view. */
+declare function StatusPill({ status, className }: StatusPillProps): react.JSX.Element;
+interface PriorityMeta {
+    /** Number of filled bars (0–3). */
+    level: number;
+    /** Fill tone (semantic token) applied to the filled bars + label. */
+    tone: string;
+}
+declare const PRIORITY_META: Record<TaskPriority, PriorityMeta>;
+interface PriorityIndicatorProps {
+    priority: TaskPriority;
+    /** Show the text label next to the bars. */
+    showLabel?: boolean;
+    className?: string;
+}
+/**
+ * Linear-style priority signal — three bars, filled by level. NONE renders all
+ * bars faint (its own recognizable "no priority" look).
+ */
+declare function PriorityIndicator({ priority, showLabel, className, }: PriorityIndicatorProps): react.JSX.Element;
+interface TypeBadgeProps {
+    type: TaskType;
+    className?: string;
+}
+/** Work-item type as a subtle badge. */
+declare function TypeBadge({ type, className }: TypeBadgeProps): react.JSX.Element;
+
 interface ModalProps {
     open: boolean;
     onClose: () => void;
@@ -837,4 +1015,4 @@ declare function Drawer(props: DrawerProps): react.JSX.Element;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { Badge, type BadgeProps, type BoardColumn, CREATE_WORK_ITEM, CreateTask, CreateTaskCore, type CreateTaskCoreProps, type CreateTaskField, type CreateTaskInput, type CreateTaskProps, DEFAULT_BOARD_COLUMNS, Drawer, type DrawerProps, GET_PROJECTS, GET_WORK_ITEM, LIST_WORK_ITEMS, type ListTasksInput, MOVE_WORK_ITEM, Modal, type ModalProps, PROJECT_SUMMARY_FIELDS, type PlanMagnetClientConfig, type PlanMagnetConfig, PlanMagnetProvider, type PlanMagnetProviderProps, type Project, type ProjectList, TASK_PRIORITIES, TASK_STATUSES, TASK_TYPES, type Task, TaskBoard, TaskBoardCore, type TaskBoardCoreProps, type TaskBoardProps, TaskDetail, TaskDetailCore, type TaskDetailCoreProps, type TaskDetailField, type TaskDetailProps, TaskList, type TaskListColumn, TaskListCore, type TaskListCoreProps, type TaskListProps, type TaskListSort, type TaskPageInfo, type TaskPaginationInput, type TaskPriority, type TaskSavedResult, type TaskStatus, type TaskType, TasksPage, TasksPageCore, type TasksPageCoreProps, type TasksPageField, type TasksPageProps, type TasksPageSaved, UPDATE_WORK_ITEM, type UpdateTaskInput, WORK_ITEM_FIELDS, WORK_ITEM_SUMMARY_FIELDS, type WorkItemDetail, type WorkItemLinkRelation, type WorkItemList, badgeVariants, cn, config, createPlanMagnetClient, enumLabel, getGraphQLEndpoint, getPlanMagnetClient, getPlanMagnetClientSafe, getPlanMagnetConfig, isPlanMagnetClientReady, resetPlanMagnetClient, resetPlanMagnetConfig, setPlanMagnetClient, setPlanMagnetConfig, usePlanMagnetContext, usePlanMagnetContextSafe, validateTrustedOrigin, waitForPlanMagnetClient };
+export { Avatar, type AvatarProps, Badge, type BadgeProps, type BoardColumn, CREATE_WORK_ITEM, CreateTask, CreateTaskCore, type CreateTaskCoreProps, type CreateTaskField, type CreateTaskInput, type CreateTaskProps, DEFAULT_BOARD_COLUMNS, Drawer, type DrawerProps, GET_PROJECTS, GET_WORK_ITEM, LIST_WORK_ITEMS, type ListTasksInput, MOVE_WORK_ITEM, Modal, type ModalProps, PRIORITY_META, PROJECT_SUMMARY_FIELDS, type PlanMagnetClientConfig, type PlanMagnetConfig, PlanMagnetProvider, type PlanMagnetProviderProps, PriorityIndicator, type PriorityIndicatorProps, type Project, type ProjectList, type ResolveAssignee, STATUS_META, StatusIcon, type StatusIconProps, StatusPill, type StatusPillProps, TASK_PRIORITIES, TASK_STATUSES, TASK_TYPES, type Task, TaskBoard, TaskBoardCore, type TaskBoardCoreProps, type TaskBoardProps, TaskCard, type TaskCardProps, TaskDetail, TaskDetailCore, type TaskDetailCoreProps, type TaskDetailField, type TaskDetailProps, TaskList, type TaskListColumn, TaskListCore, type TaskListCoreProps, type TaskListProps, type TaskListSort, type TaskPageInfo, type TaskPaginationInput, type TaskPriority, type TaskSavedResult, type TaskStatus, TaskTimelineCore, type TaskTimelineCoreProps, TaskToolbar, type TaskToolbarProps, type TaskType, type TaskView, TasksPage, TasksPageCore, type TasksPageCoreProps, type TasksPageField, type TasksPageProps, type TasksPageSaved, TypeBadge, type TypeBadgeProps, UPDATE_WORK_ITEM, type UpdateTaskInput, WORK_ITEM_FIELDS, WORK_ITEM_SUMMARY_FIELDS, type WorkItemDetail, type WorkItemLinkRelation, type WorkItemList, badgeVariants, cn, config, createPlanMagnetClient, enumLabel, getGraphQLEndpoint, getPlanMagnetClient, getPlanMagnetClientSafe, getPlanMagnetConfig, isPlanMagnetClientReady, resetPlanMagnetClient, resetPlanMagnetConfig, setPlanMagnetClient, setPlanMagnetConfig, usePlanMagnetContext, usePlanMagnetContextSafe, validateTrustedOrigin, waitForPlanMagnetClient };