@anchrd/intel-ui 0.16.1 → 0.18.0

package/src/board/board-data/board-data.types.ts

@@ -0,0 +1,63 @@
+import type {
+  AddBoardTaskInput,
+  BoardStatus,
+  BoardStatusInput,
+  BoardTask,
+  BoardTaskResult,
+  ConfigureBoardResult,
+  DeleteBoardTaskResult,
+  MoveBoardTaskInput,
+  NodeBoard,
+  UpdateBoardTaskInput,
+} from "@anchrd/intel-contract";
+import type { UseMutationResult, UseQueryResult } from "@tanstack/react-query";
+
+// What a caller hands over, minus what the data layer fills in for it: the node it is on and the
+// idempotency key. Neither is a decision any view makes, and a view that could get them wrong is a
+// view that could write to the wrong board.
+export type AddTask = Omit<AddBoardTaskInput, "nodeId" | "idempotencyKey">;
+export type UpdateTask = Omit<UpdateBoardTaskInput, "nodeId" | "idempotencyKey">;
+export type MoveTask = Omit<MoveBoardTaskInput, "nodeId" | "idempotencyKey">;
+
+/**
+ * The board, and every way to change it — the one thing a view is handed (anchrd/intel#286).
+ *
+ * ⚠️ No view loads and no view writes. Five of them draw the same list, the last of which (Gantt,
+ * anchrd/intel#293) arrived as a renderer rather than a rebuild — which only holds while the
+ * loading, the cache and the five operations live in exactly one place. A view that reached for
+ * `useQuery` itself would be a second cache entry for the same board: two readers, one stale, the
+ * same task in two states on one screen.
+ */
+export interface BoardHandle {
+  nodeId: string;
+  query: UseQueryResult<NodeBoard>;
+  // The status list in the order it is drawn, `archived` included. A view that wants the columns a
+  // person works in filters it with `visibleStatuses`.
+  statuses: BoardStatus[];
+  // Every task of the board, ordered by status and then by `order`. Archived ones are in here too:
+  // hiding them is the KANBAN's switch, not a fact about the data, and a view that never saw them
+  // could not offer to show them.
+  tasks: BoardTask[];
+  byId: Map<string, BoardTask>;
+  // The direct children of a task, keyed by parent. Built once for every view that asks, and each
+  // building its own map would walk the whole board again.
+  childrenOf: Map<string, BoardTask[]>;
+  /**
+   * Whether something this task waits for is still open.
+   *
+   * ⚠️ "Open" is the status list's own `terminal` flag and nothing else (anchrd/intel#311). It is
+   * not a position: reading it as "the last column before `archived`" made a board configured to
+   * `… done → blocked → archived` treat "blocked" as finished, silently, with a wrong marker as the
+   * only symptom.
+   */
+  blockedBy(task: BoardTask): BoardTask[];
+  // The other half of the same question: a task nobody is waiting for any more. It is what a subtask
+  // counter counts and what `blockedBy` measures its dependencies against, so both come from one
+  // definition rather than two that can drift apart.
+  settled(task: BoardTask): boolean;
+  add: UseMutationResult<BoardTaskResult, Error, AddTask>;
+  update: UseMutationResult<BoardTaskResult, Error, UpdateTask>;
+  move: UseMutationResult<BoardTaskResult, Error, MoveTask>;
+  remove: UseMutationResult<DeleteBoardTaskResult, Error, { taskId: string }>;
+  configure: UseMutationResult<ConfigureBoardResult, Error, BoardStatusInput[]>;
+}