@zaip-ai/cli 2.2.0 → 2.6.0

package/templates/.agents/dashboard/apps/frontend/src/use-app-work-board.ts

@@ -0,0 +1,397 @@
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import { type Dispatch, type RefObject, type SetStateAction, useCallback, useEffect } from "react";
+import { isAbortError, mergeBoardPages } from "./AppRequestGuards.js";
+import {
+  type BoardStageState,
+  initialWorkBoardStages,
+  type OverviewClassification,
+  type OverviewClassificationPages,
+  type OverviewStatusKind,
+  type OverviewStatusPages,
+  overviewClassificationPageKey,
+  overviewStatusPageKey,
+} from "./AppWorkBoard.js";
+import type {
+  DashboardApiClient,
+  OperationsBoardPage,
+  OperationsPageFilters,
+  WorkBoardStage,
+} from "./dashboard-api.js";
+import { type OperationsPeriodState, requestPeriodForOperations } from "./operations-period.js";
+
+type StateSetter<T> = Dispatch<SetStateAction<T>>;
+
+export function useAppWorkBoard({
+  api,
+  boardAbortControllersRef,
+  boardFilterKeyRef,
+  boardFiltersRef,
+  boardInFlightRef,
+  boardInitialPageRef,
+  boardLoadedRef,
+  boardRequestVersionRef,
+  dashboardView,
+  operations,
+  operationsPeriod,
+  operationsPeriodRef,
+  overviewStatusInFlightRef,
+  quickOverviewMetricsRef,
+  setBoardKindTotals,
+  setBoardStates,
+  setBoardTotals,
+  setOperations,
+  setOverviewClassificationPages,
+  setOverviewStatusPages,
+}: {
+  api: DashboardApiClient;
+  boardAbortControllersRef: RefObject<Map<WorkBoardStage, AbortController>>;
+  boardFilterKeyRef: RefObject<string>;
+  boardFiltersRef: RefObject<OperationsPageFilters>;
+  boardInFlightRef: RefObject<Set<WorkBoardStage>>;
+  boardInitialPageRef: RefObject<Set<WorkBoardStage>>;
+  boardLoadedRef: RefObject<Partial<Record<WorkBoardStage, number>>>;
+  boardRequestVersionRef: RefObject<number>;
+  dashboardView: "operations" | "cost-monitor" | "traceability" | null;
+  operations: OperationsProjection | null;
+  operationsPeriod: OperationsPeriodState;
+  operationsPeriodRef: RefObject<OperationsPeriodState>;
+  overviewStatusInFlightRef: RefObject<Set<string>>;
+  quickOverviewMetricsRef: RefObject<OperationsProjection["summary"]["overview_metrics"]>;
+  setBoardKindTotals: StateSetter<
+    Partial<Record<WorkBoardStage, OperationsBoardPage["totals_by_kind"]>>
+  >;
+  setBoardStates: StateSetter<Partial<Record<WorkBoardStage, BoardStageState>>>;
+  setBoardTotals: StateSetter<Partial<Record<WorkBoardStage, number>>>;
+  setOperations: StateSetter<OperationsProjection | null>;
+  setOverviewClassificationPages: StateSetter<OverviewClassificationPages>;
+  setOverviewStatusPages: StateSetter<OverviewStatusPages>;
+}) {
+  const resetBoard = useCallback(() => {
+    boardRequestVersionRef.current += 1;
+    for (const controller of boardAbortControllersRef.current.values()) controller.abort();
+    boardAbortControllersRef.current.clear();
+    boardInFlightRef.current.clear();
+    boardInitialPageRef.current.clear();
+    boardLoadedRef.current = {};
+    setBoardTotals({});
+    setBoardKindTotals({});
+    setBoardStates({});
+    setOverviewStatusPages({});
+    setOverviewClassificationPages({});
+  }, [
+    boardAbortControllersRef,
+    boardInFlightRef,
+    boardInitialPageRef,
+    boardLoadedRef,
+    boardRequestVersionRef,
+    setBoardKindTotals,
+    setBoardStates,
+    setBoardTotals,
+    setOverviewClassificationPages,
+    setOverviewStatusPages,
+  ]);
+
+  const loadMoreBoard = useCallback(
+    async (stage: WorkBoardStage) => {
+      if (operations === null || boardInFlightRef.current.has(stage)) return;
+      boardInFlightRef.current.add(stage);
+      boardAbortControllersRef.current.get(stage)?.abort();
+      const controller = new AbortController();
+      boardAbortControllersRef.current.set(stage, controller);
+      const requestVersion = boardRequestVersionRef.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      setBoardStates((previous) => ({ ...previous, [stage]: { loading: true, error: null } }));
+      const loaded = boardLoadedRef.current[stage] ?? 0;
+      try {
+        const page = await api.operationsBoard(
+          period,
+          stage,
+          loaded,
+          boardFiltersRef.current,
+          controller.signal,
+          10,
+        );
+        if (
+          controller.signal.aborted ||
+          requestVersion !== boardRequestVersionRef.current ||
+          period.from !== requestPeriodForOperations(operationsPeriodRef.current).from ||
+          period.to !== requestPeriodForOperations(operationsPeriodRef.current).to
+        )
+          return;
+        setOperations((previous) =>
+          previous === null
+            ? previous
+            : { ...mergeBoardPages(previous, [page]), summary: previous.summary },
+        );
+        setBoardTotals((previous) => ({ ...previous, [stage]: page.total }));
+        setBoardKindTotals((previous) => ({ ...previous, [stage]: page.totals_by_kind }));
+        boardLoadedRef.current = {
+          ...boardLoadedRef.current,
+          [stage]: loaded + page.prds.length + page.specs.length + page.tasks.length,
+        };
+      } catch (cause) {
+        if (
+          controller.signal.aborted ||
+          requestVersion !== boardRequestVersionRef.current ||
+          isAbortError(cause)
+        )
+          return;
+        setBoardStates((previous) => ({
+          ...previous,
+          [stage]: {
+            loading: false,
+            error: cause instanceof Error ? cause.message : String(cause),
+          },
+        }));
+      } finally {
+        if (requestVersion === boardRequestVersionRef.current) {
+          boardInFlightRef.current.delete(stage);
+          if (boardAbortControllersRef.current.get(stage) === controller)
+            boardAbortControllersRef.current.delete(stage);
+          setBoardStates((previous) =>
+            previous[stage]?.error === null
+              ? { ...previous, [stage]: { loading: false, error: null } }
+              : previous,
+          );
+        }
+      }
+    },
+    [
+      api,
+      boardAbortControllersRef,
+      boardFiltersRef,
+      boardInFlightRef,
+      boardLoadedRef,
+      boardRequestVersionRef,
+      operations,
+      operationsPeriod,
+      operationsPeriodRef,
+      setBoardKindTotals,
+      setBoardStates,
+      setBoardTotals,
+      setOperations,
+    ],
+  );
+
+  const loadFilteredBoard = useCallback(
+    (filters: OperationsPageFilters) => {
+      const normalizedFilters = {
+        ...filters,
+        kind: filters.kind ?? boardFiltersRef.current.kind ?? "",
+      };
+      const filterKey = `${normalizedFilters.query}|${normalizedFilters.status}|${normalizedFilters.risk}|${normalizedFilters.origin ?? ""}|${normalizedFilters.kind}`;
+      if (filterKey === boardFilterKeyRef.current) return;
+      boardFilterKeyRef.current = filterKey;
+      boardFiltersRef.current = normalizedFilters;
+      resetBoard();
+      setOperations((current) =>
+        current === null
+          ? current
+          : {
+              ...current,
+              prds: [],
+              specs: [],
+              tasks: [],
+              changes: [],
+              summary:
+                filterKey === "||||" && quickOverviewMetricsRef.current !== undefined
+                  ? { ...current.summary, overview_metrics: quickOverviewMetricsRef.current }
+                  : current.summary,
+            },
+      );
+    },
+    [boardFilterKeyRef, boardFiltersRef, quickOverviewMetricsRef, resetBoard, setOperations],
+  );
+
+  const loadOverviewStatusPage = useCallback(
+    async (stage: WorkBoardStage, kind: OverviewStatusKind, offset: number) => {
+      const key = overviewStatusPageKey(stage, kind);
+      const inFlight = overviewStatusInFlightRef.current;
+      if (inFlight.has(key)) return;
+      inFlight.add(key);
+      const requestVersion = boardRequestVersionRef.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      setOverviewStatusPages((previous) => ({
+        ...previous,
+        [key]: {
+          items: offset === 0 ? [] : (previous[key]?.items ?? []),
+          total: previous[key]?.total ?? 0,
+          loading: true,
+          error: null,
+        },
+      }));
+      try {
+        const page = await api.operationsBoard(period, stage, offset, {
+          kind: kind === "task" ? "all-tasks" : kind,
+        });
+        if (
+          requestVersion !== boardRequestVersionRef.current ||
+          period.from !== requestPeriodForOperations(operationsPeriodRef.current).from ||
+          period.to !== requestPeriodForOperations(operationsPeriodRef.current).to
+        )
+          return;
+        const items = kind === "task" ? page.tasks : kind === "spec" ? page.specs : page.prds;
+        setOverviewStatusPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: offset === 0 ? items : [...(previous[key]?.items ?? []), ...items],
+            total: page.total,
+            loading: false,
+            error: null,
+          },
+        }));
+      } catch (cause) {
+        if (requestVersion !== boardRequestVersionRef.current || isAbortError(cause)) return;
+        setOverviewStatusPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: previous[key]?.items ?? [],
+            total: previous[key]?.total ?? 0,
+            loading: false,
+            error: cause instanceof Error ? cause.message : String(cause),
+          },
+        }));
+      } finally {
+        inFlight.delete(key);
+      }
+    },
+    [
+      api,
+      boardRequestVersionRef,
+      operationsPeriod,
+      operationsPeriodRef,
+      overviewStatusInFlightRef,
+      setOverviewStatusPages,
+    ],
+  );
+
+  const loadOverviewClassificationPage = useCallback(
+    async (kind: OverviewStatusKind, classification: OverviewClassification, offset: number) => {
+      const key = overviewClassificationPageKey(kind, classification);
+      const inFlight = overviewStatusInFlightRef.current;
+      if (inFlight.has(key)) return;
+      inFlight.add(key);
+      const requestVersion = boardRequestVersionRef.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      setOverviewClassificationPages((previous) => ({
+        ...previous,
+        [key]: {
+          items: offset === 0 ? [] : (previous[key]?.items ?? []),
+          total: previous[key]?.total ?? 0,
+          loading: true,
+          error: null,
+        },
+      }));
+      try {
+        const page = await api.operationsClassification(period, kind, classification, offset);
+        if (
+          requestVersion !== boardRequestVersionRef.current ||
+          period.from !== requestPeriodForOperations(operationsPeriodRef.current).from ||
+          period.to !== requestPeriodForOperations(operationsPeriodRef.current).to
+        )
+          return;
+        const items = kind === "task" ? page.tasks : kind === "spec" ? page.specs : page.prds;
+        setOverviewClassificationPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: offset === 0 ? items : [...(previous[key]?.items ?? []), ...items],
+            total: page.total,
+            loading: false,
+            error: null,
+          },
+        }));
+      } catch (cause) {
+        if (requestVersion !== boardRequestVersionRef.current || isAbortError(cause)) return;
+        setOverviewClassificationPages((previous) => ({
+          ...previous,
+          [key]: {
+            items: previous[key]?.items ?? [],
+            total: previous[key]?.total ?? 0,
+            loading: false,
+            error: cause instanceof Error ? cause.message : String(cause),
+          },
+        }));
+      } finally {
+        inFlight.delete(key);
+      }
+    },
+    [
+      api,
+      boardRequestVersionRef,
+      operationsPeriod,
+      operationsPeriodRef,
+      overviewStatusInFlightRef,
+      setOverviewClassificationPages,
+    ],
+  );
+
+  const boardExportSource = useCallback(
+    (selectedFilters: { query: string; status: string; risk: string; origin: string }) => {
+      const filters = { ...boardFiltersRef.current, ...selectedFilters };
+      const period = requestPeriodForOperations(operationsPeriod);
+      return {
+        prepare: async () => {
+          const firstPages = await Promise.all(
+            initialWorkBoardStages.map((stage) => api.operationsBoard(period, stage, 0, filters)),
+          );
+          const rowsFor = (page: OperationsBoardPage) => [
+            ...page.prds.map(({ kind: _kind, ...row }) => ({ kind: "prd", ...row })),
+            ...page.specs.map(({ kind: _kind, ...row }) => ({ kind: "spec", ...row })),
+            ...page.tasks.map((row) => ({ kind: "task", ...row })),
+          ];
+          return {
+            totalRows: firstPages.reduce((sum, page) => sum + page.total, 0),
+            pages: async function* () {
+              for (const firstPage of firstPages) {
+                let page = firstPage;
+                let offset = 0;
+                while (true) {
+                  const rows = rowsFor(page);
+                  if (rows.length === 0) break;
+                  offset += rows.length;
+                  yield rows;
+                  if (offset >= page.total) break;
+                  page = await api.operationsBoard(period, page.stage, offset, filters);
+                }
+              }
+            },
+          };
+        },
+      };
+    },
+    [api, boardFiltersRef, operationsPeriod],
+  );
+
+  useEffect(() => {
+    if (dashboardView !== "operations" || operations === null) return;
+    let cancelled = false;
+    const hydrateBoard = async () => {
+      const pending = initialWorkBoardStages.filter(
+        (stage) => !boardInitialPageRef.current.has(stage) && !boardInFlightRef.current.has(stage),
+      );
+      for (let offset = 0; offset < pending.length && !cancelled; offset += 3) {
+        const batch = pending.slice(offset, offset + 3);
+        for (const stage of batch) boardInitialPageRef.current.add(stage);
+        await Promise.all(batch.map((stage) => loadMoreBoard(stage)));
+      }
+    };
+    const idle =
+      typeof window.requestIdleCallback === "function"
+        ? { kind: "idle" as const, id: window.requestIdleCallback(() => void hydrateBoard()) }
+        : { kind: "timeout" as const, id: window.setTimeout(() => void hydrateBoard(), 0) };
+    return () => {
+      cancelled = true;
+      if (idle.kind === "idle") window.cancelIdleCallback(idle.id);
+      else window.clearTimeout(idle.id);
+    };
+  }, [boardInFlightRef, boardInitialPageRef, dashboardView, loadMoreBoard, operations]);
+
+  return {
+    boardExportSource,
+    loadFilteredBoard,
+    loadMoreBoard,
+    loadOverviewClassificationPage,
+    loadOverviewStatusPage,
+    resetBoard,
+  };
+}