@burdenoff/planmagnet-fe-sdk 2026.706.7 → 2026.708.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { HTMLAttributes, ReactNode, ComponentType, DragEvent } from 'react';
+import { HTMLAttributes, ReactNode, ComponentType, DragEvent, Ref } from 'react';
 import { ApolloClient } from '@apollo/client/core';
 import * as graphql from 'graphql';
 import * as class_variance_authority_types from 'class-variance-authority/types';
@@ -64,6 +64,14 @@ interface Task {
     storyPoints?: number | null;
     dueDate?: string | null;
     labels: string[];
+    /**
+     * Board ordering within a status column (SDL `WorkItem.sortOrder`, backed by
+     * the Prisma `position` column via a read field resolver — safe to SELECT on
+     * query paths). Drives drag-to-reorder-within-a-column; the board sorts cards
+     * by this ascending so a persisted reorder survives refetch. Optional so older
+     * mocks/hosts that don't select it still type-check.
+     */
+    sortOrder?: number | null;
 }
 /**
  * A work item with the full field set from `WorkItemFields` — used by the
@@ -410,6 +418,12 @@ interface TaskCardProps {
     draggable?: boolean;
     onDragStart?: (task: Task, e: DragEvent<HTMLDivElement>) => void;
     onDragEnd?: (task: Task, e: DragEvent<HTMLDivElement>) => void;
+    /**
+     * Native drag-over on the card — the board uses this to compute a
+     * within-column reorder drop index (before/after this card). Only wired when
+     * `draggable`.
+     */
+    onDragOver?: (e: DragEvent<HTMLDivElement>) => void;
     /** True while this card is the one being dragged. */
     dragging?: boolean;
     resolveAssignee?: ResolveAssignee;
@@ -424,7 +438,7 @@ interface TaskCardProps {
  * only real fields (no invented assignee names or entity links). Semantic
  * tokens only.
  */
-declare function TaskCard({ task, hidden, onClick, draggable, onDragStart, onDragEnd, dragging, resolveAssignee, links, renderLinkIcon, className, }: TaskCardProps): react.JSX.Element;
+declare function TaskCard({ task, hidden, onClick, draggable, onDragStart, onDragEnd, onDragOver, dragging, resolveAssignee, links, renderLinkIcon, className, }: TaskCardProps): react.JSX.Element;
 
 interface TaskBoardCoreProps {
     /** Scope the board to one project (client-side filter for Phase 1). */
@@ -793,6 +807,11 @@ interface TaskToolbarProps {
     views?: TaskView[];
     search: string;
     onSearchChange: (search: string) => void;
+    /**
+     * Optional ref to the search `<input>` — lets a host focus it programmatically
+     * (e.g. the `/` keyboard shortcut on the composed Tasks page).
+     */
+    searchInputRef?: Ref<HTMLInputElement>;
     priority: TaskPriority | "ALL";
     onPriorityChange: (priority: TaskPriority | "ALL") => void;
     type: TaskType | "ALL";
@@ -802,6 +821,11 @@ interface TaskToolbarProps {
     /** "My tasks" toggle — only rendered when `onMineChange` is provided. */
     mine?: boolean;
     onMineChange?: (mine: boolean) => void;
+    /**
+     * Extra controls rendered at the LEADING edge of the right-hand action group
+     * (before search) — e.g. the Saved Views dropdown. Omit for none.
+     */
+    leadingActions?: ReactNode;
     className?: string;
 }
 /**
@@ -809,7 +833,7 @@ interface TaskToolbarProps {
  * 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, mine, onMineChange, className, }: TaskToolbarProps): react.JSX.Element;
+declare function TaskToolbar({ view, onViewChange, views, search, onSearchChange, searchInputRef, priority, onPriorityChange, type, onTypeChange, onNewTask, canCreate, mine, onMineChange, leadingActions, 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";
@@ -965,6 +989,22 @@ interface TaskLabels {
     allTypes: string;
     newTask: string;
     myTasks: string;
+    savedViews: string;
+    saveView: string;
+    viewName: string;
+    saveViewAction: string;
+    deleteView: string;
+    noSavedViews: string;
+    defaultViewName: string;
+    keyboardShortcuts: string;
+    shortcutNewTask: string;
+    shortcutSearch: string;
+    shortcutBoardView: string;
+    shortcutListView: string;
+    shortcutTimelineView: string;
+    shortcutMyTasks: string;
+    shortcutHelp: string;
+    shortcutClose: string;
     noTasks: string;
     noTasksFound: string;
     dropHere: string;
@@ -1053,6 +1093,7 @@ interface TaskLabels {
     projectRequired: string;
     errorLoading: string;
     moveFailed: string;
+    reorderFailed: string;
     failedToCreate: string;
     failedToSave: string;
     failedToDelete: string;
@@ -1180,6 +1221,33 @@ interface TasksPageCoreProps {
     createSurface?: "modal" | "inline";
     /** How the detail view is surfaced. Defaults to "drawer". */
     detailSurface?: "drawer" | "inline";
+    /**
+     * Opt-in "Saved Views". When true, the toolbar state (view tab, priority /
+     * type filters, search, "my tasks", and the list column config) is persisted
+     * to `localStorage` (keyed per workspace) and restored on the next mount, and
+     * a compact "Views" dropdown lets the user save / switch / delete named
+     * views. OFF by default — existing embeds are unchanged. Client-only, no
+     * backend; all storage access is SSR-/failure-safe.
+     */
+    enableSavedViews?: boolean;
+    /**
+     * Optional storage-key suffix so multiple independent Tasks surfaces in the
+     * same workspace (e.g. two boards on one page) don't clobber each other's
+     * persisted state. Implies `enableSavedViews` when set. The storage key is
+     * `planmagnet:views:<workspaceId>[:<persistViewKey>]`.
+     */
+    persistViewKey?: string;
+    /**
+     * Opt-in Linear-style keyboard shortcuts. When true, a scoped `keydown`
+     * listener (active only while this page is mounted, ignored while typing in a
+     * form field and for modifier combos) enables:
+     * `c` new task, `/` focus search, `b`/`l`/`g` switch Board/List/Timeline
+     * (only among the enabled views), `m` toggle "My tasks" (needs
+     * `currentActorId`), `?` toggle a dismissible help overlay, and `Escape` to
+     * close the create / detail / help surfaces. OFF by default — existing embeds
+     * are byte-for-byte unchanged.
+     */
+    enableShortcuts?: boolean;
     /** Extra classes on the root container. */
     className?: string;
 }
@@ -1192,7 +1260,7 @@ interface TasksPageCoreProps {
  * 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, canCreateMilestone, locale, hiddenFields, views, defaultView, confirmMove, resolveAssignee, linkSourceProduct, renderLinkIcon, assigneeOptions, currentActorId, commentsEntityType, onMention, labels, openItemId, header, onTaskSaved, createSurface, detailSurface, className, }: TasksPageCoreProps): react.JSX.Element;
+declare function TasksPageCore({ workspaceId: workspaceIdProp, projectId, boardProjectId, columns, readonly, canCreateMilestone, locale, hiddenFields, views, defaultView, confirmMove, resolveAssignee, linkSourceProduct, renderLinkIcon, assigneeOptions, currentActorId, commentsEntityType, onMention, labels, openItemId, header, onTaskSaved, createSurface, detailSurface, enableSavedViews, persistViewKey, enableShortcuts, className, }: TasksPageCoreProps): react.JSX.Element;
 
 interface TasksPageProps extends TasksPageCoreProps {
     /** Workspace API gateway URL (URL mode). */
@@ -1345,6 +1413,110 @@ declare function useMilestones(workspaceId: string | undefined, opts?: {
     limit?: number;
 }): UseMilestonesResult;
 
+/**
+ * The user-controlled toolbar/view state the Saved Views feature persists and
+ * restores. Product-agnostic: the same shape drives Board / List / Timeline.
+ */
+interface ViewState {
+    /** Active view tab. */
+    view: TaskView;
+    /** Priority quick-filter ("ALL" = no filter). */
+    priority: TaskPriority | "ALL";
+    /** Type quick-filter ("ALL" = no filter). */
+    type: TaskType | "ALL";
+    /** Free-text search. */
+    search: string;
+    /** "My tasks" toggle. */
+    mine: boolean;
+    /**
+     * List column config (order preserved). `null` = use the page default
+     * (which itself may depend on `linkSourceProduct`).
+     */
+    listColumns: TaskListColumn[] | null;
+}
+/** A user-named snapshot of a {@link ViewState}. */
+interface SavedView {
+    /** Stable id (nanoid-ish; generated client-side). */
+    id: string;
+    /** Display name the user typed. */
+    name: string;
+    /** The captured filter/view state. */
+    state: ViewState;
+}
+/**
+ * Compose the storage key for a workspace — `planmagnet:views:<workspaceId>`,
+ * optionally suffixed (`:<suffix>`) so multiple independent Tasks surfaces in
+ * one workspace don't clobber each other.
+ */
+declare function makeStorageKey(workspaceId: string, suffix?: string): string;
+interface UseSavedViewsArgs {
+    /**
+     * Fully-composed localStorage key (see {@link makeStorageKey}). All reads and
+     * writes target this key.
+     */
+    storageKey: string;
+    /** Feature master switch — when false the hook is a no-op passthrough. */
+    enabled: boolean;
+    /** The live toolbar state to persist (debounced). */
+    current: ViewState;
+}
+interface UseSavedViewsResult {
+    /**
+     * The state restored from storage on the first mount, or `null` if there was
+     * nothing to restore (or the feature is disabled). Consumers apply this once
+     * to seed their controlled inputs.
+     */
+    restored: ViewState | null;
+    /** All saved named views for this workspace. */
+    views: SavedView[];
+    /** The id of the currently-applied saved view (or null for an ad-hoc state). */
+    activeViewId: string | null;
+    /** Persist the current toolbar state as a new named view; returns its id. */
+    saveView: (name: string) => string | null;
+    /** Apply a saved view — returns its state so the caller can seed inputs. */
+    applyView: (id: string) => ViewState | null;
+    /** Delete a saved view by id. */
+    deleteView: (id: string) => void;
+    /** Clear the "active saved view" pointer (e.g. after a manual filter edit). */
+    clearActiveView: () => void;
+}
+/**
+ * useSavedViews — client-side (localStorage) persistence of the Tasks toolbar
+ * state, keyed per workspace, plus optional user-named views. No backend.
+ *
+ * - Restores the last-active toolbar state on mount (`restored`, applied once).
+ * - Debounces writes of the live `current` state.
+ * - Manages a list of named views (save / apply / delete).
+ * - Fully guarded: SSR-safe and resilient to disabled/quota-limited storage.
+ *
+ * When `enabled` is false the hook does nothing (no reads, no writes) and
+ * returns empty results, so callers stay non-breaking by default.
+ */
+declare function useSavedViews({ storageKey, enabled, current, }: UseSavedViewsArgs): UseSavedViewsResult;
+
+interface SavedViewsMenuProps {
+    /** All saved named views for the workspace. */
+    views: SavedView[];
+    /** The id of the currently-applied saved view (null = ad-hoc/default). */
+    activeViewId: string | null;
+    /** Save the current filter set as a new named view. */
+    onSaveView: (name: string) => void;
+    /** Apply a saved view by id. */
+    onApplyView: (id: string) => void;
+    /** Delete a saved view by id. */
+    onDeleteView: (id: string) => void;
+    className?: string;
+}
+/**
+ * SavedViewsMenu — a compact toolbar dropdown to save the current filter set as
+ * a named view, switch between saved views, and delete one. Client-only (the
+ * persistence lives in `useSavedViews`); semantic-token styled; farm-free.
+ *
+ * Self-contained dropdown (no fe-libs / portal dependency) so it renders in any
+ * host and in happy-dom tests. Closes on outside-click and Escape.
+ */
+declare function SavedViewsMenu({ views, activeViewId, onSaveView, onApplyView, onDeleteView, className, }: SavedViewsMenuProps): react.JSX.Element;
+
 interface PlanMagnetClientConfig {
     /** Workspace API gateway base URL (e.g. https://graphqlworkspaces.burdenoff.com). */
     apiGatewayUrl: string;
@@ -1495,4 +1667,4 @@ declare function getGraphQLEndpoint(baseUrl?: string): string;
 
 declare function cn(...inputs: ClassValue[]): string;
 
-export { type AssigneeOption, Avatar, type AvatarProps, BULK_UPDATE_WORK_ITEMS, Badge, type BadgeProps, type BoardColumn, CREATE_WORK_ITEM, CREATE_WORK_ITEM_LINK, CreateTask, CreateTaskCore, type CreateTaskCoreProps, type CreateTaskField, type CreateTaskInput, type CreateTaskProps, type CreateWorkItemLinkInput, DEFAULT_BOARD_COLUMNS, DEFAULT_TASK_LABELS, DELETE_WORK_ITEM, DELETE_WORK_ITEM_LINK, Drawer, type DrawerProps, GET_PROJECTS, GET_WORK_ITEM, LIST_MILESTONES, LIST_WORK_ITEMS, LIST_WORK_ITEM_LINKS, LinkChip, type LinkChipProps, type ListMilestonesInput, type ListTasksInput, type ListWorkItemLinksInput, MILESTONE_FIELDS, MOVE_WORK_ITEM, type Milestone, type MilestoneList, type MilestoneStatus, Modal, type ModalProps, PRIORITY_META, PROJECT_SUMMARY_FIELDS, type PartialTaskLabels, type PlanMagnetClientConfig, type PlanMagnetConfig, PlanMagnetProvider, type PlanMagnetProviderProps, PriorityIndicator, type PriorityIndicatorProps, type Project, type ProjectList, type RenderLinkIcon, 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, TaskCommentsCore, type TaskCommentsCoreProps, TaskDetail, TaskDetailCore, type TaskDetailCoreProps, type TaskDetailField, type TaskDetailProps, type TaskLabels, TaskLabelsProvider, 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, type UseMilestonesResult, type UseWorkItemLinksResult, WORK_ITEM_FIELDS, WORK_ITEM_LINK_FIELDS, WORK_ITEM_SUMMARY_FIELDS, type WorkItemDetail, type WorkItemLink, type WorkItemLinkList, type WorkItemLinkRelation, type WorkItemList, badgeVariants, cn, config, createPlanMagnetClient, enumLabel, getGraphQLEndpoint, getPlanMagnetClient, getPlanMagnetClientSafe, getPlanMagnetConfig, isPlanMagnetClientReady, mergeTaskLabels, resetPlanMagnetClient, resetPlanMagnetConfig, setPlanMagnetClient, setPlanMagnetConfig, useMilestones, usePlanMagnetContext, usePlanMagnetContextSafe, useTaskLabels, useWorkItemLinks, validateTrustedOrigin, waitForPlanMagnetClient };
+export { type AssigneeOption, Avatar, type AvatarProps, BULK_UPDATE_WORK_ITEMS, Badge, type BadgeProps, type BoardColumn, CREATE_WORK_ITEM, CREATE_WORK_ITEM_LINK, CreateTask, CreateTaskCore, type CreateTaskCoreProps, type CreateTaskField, type CreateTaskInput, type CreateTaskProps, type CreateWorkItemLinkInput, DEFAULT_BOARD_COLUMNS, DEFAULT_TASK_LABELS, DELETE_WORK_ITEM, DELETE_WORK_ITEM_LINK, Drawer, type DrawerProps, GET_PROJECTS, GET_WORK_ITEM, LIST_MILESTONES, LIST_WORK_ITEMS, LIST_WORK_ITEM_LINKS, LinkChip, type LinkChipProps, type ListMilestonesInput, type ListTasksInput, type ListWorkItemLinksInput, MILESTONE_FIELDS, MOVE_WORK_ITEM, type Milestone, type MilestoneList, type MilestoneStatus, Modal, type ModalProps, PRIORITY_META, PROJECT_SUMMARY_FIELDS, type PartialTaskLabels, type PlanMagnetClientConfig, type PlanMagnetConfig, PlanMagnetProvider, type PlanMagnetProviderProps, PriorityIndicator, type PriorityIndicatorProps, type Project, type ProjectList, type RenderLinkIcon, type ResolveAssignee, STATUS_META, type SavedView, SavedViewsMenu, type SavedViewsMenuProps, StatusIcon, type StatusIconProps, StatusPill, type StatusPillProps, TASK_PRIORITIES, TASK_STATUSES, TASK_TYPES, type Task, TaskBoard, TaskBoardCore, type TaskBoardCoreProps, type TaskBoardProps, TaskCard, type TaskCardProps, TaskCommentsCore, type TaskCommentsCoreProps, TaskDetail, TaskDetailCore, type TaskDetailCoreProps, type TaskDetailField, type TaskDetailProps, type TaskLabels, TaskLabelsProvider, 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, type UseMilestonesResult, type UseSavedViewsArgs, type UseSavedViewsResult, type UseWorkItemLinksResult, type ViewState, WORK_ITEM_FIELDS, WORK_ITEM_LINK_FIELDS, WORK_ITEM_SUMMARY_FIELDS, type WorkItemDetail, type WorkItemLink, type WorkItemLinkList, type WorkItemLinkRelation, type WorkItemList, badgeVariants, cn, config, createPlanMagnetClient, enumLabel, getGraphQLEndpoint, getPlanMagnetClient, getPlanMagnetClientSafe, getPlanMagnetConfig, isPlanMagnetClientReady, makeStorageKey, mergeTaskLabels, resetPlanMagnetClient, resetPlanMagnetConfig, setPlanMagnetClient, setPlanMagnetConfig, useMilestones, usePlanMagnetContext, usePlanMagnetContextSafe, useSavedViews, useTaskLabels, useWorkItemLinks, validateTrustedOrigin, waitForPlanMagnetClient };