feat(29.6): add useScheduleMutations; route Schedule 1 through guarded run()

Story 1.6 (tech hardening). New useScheduleMutations({path, millId, year,
isCurrent}) composes useScheduleBanners and exposes save/remove/checkStatus
that dispatch through run() — so pages get the isCurrent() stale-response
guard (no more stale repaint on a mid-flight mill/year switch) and stop
re-hand-rolling the request/error/lock scaffolding.

Schedule 1 converted as the exemplar: save/delete/check-status now go through
the hook. The old separate `checking` lock folds into the single `saving`
lock (both write actions gate together while any write is in flight). Delete
keeps its in-place empty-state at the call site (a re-GET would 404 for a
single-doc schedule) per the agreed convergence. Behavior preserved: 85/85
Schedule 1 tests pass, tsc + eslint clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: gpascucci

frontend/src/components/schedule1/index.tsx

@@ -3,7 +3,7 @@ import type Schedule1Response from '@/interfaces/Schedule1Response'
 import type { LineItem } from '@/interfaces/Schedule1Response'
 import type Schedule1Request from '@/interfaces/Schedule1Request'
 import type CheckStatusResponse from '@/interfaces/CheckStatusResponse'
-import { useCallback, useState } from 'react'
+import { useState } from 'react'
 import { useNavigate } from '@tanstack/react-router'
 import {
   Button,
@@ -21,11 +21,10 @@ import {
   TextArea,
   TextInput,
 } from '@carbon/react'
-import apiService from '@/service/api-service'
 import { WRITABLE_LINE_ITEM_CODES } from '@/interfaces/Schedule1Request'
-import useMillYear from '@/context/millYear/useMillYear'
+import { useScheduleContextGuard } from '@/hooks/useScheduleContextGuard'
 import { useScheduleDocument } from '@/hooks/useScheduleDocument'
-import { extractDetail } from '@/utils/error'
+import { useScheduleMutations } from '@/hooks/useScheduleMutations'
 import { fmtCurrency, fmtNumber, groupInput, numStrGroup, toNum } from '@/utils/number'
 import LoadingScreen from '@/components/core/LoadingScreen'
 import NotificationColumn from '@/components/core/NotificationColumn'
@@ -123,25 +122,30 @@ function buildRequest(doc: Schedule1Response, form: FieldValues): Schedule1Reque
 }
 
 const Schedule1: FC = () => {
-  const { millId, year } = useMillYear()
+  const { millId, year, contextMissing, isCurrent } = useScheduleContextGuard()
   const navigate = useNavigate()
-  const contextMissing = millId === null || year === null
 
-  const [saving, setSaving] = useState(false)
-  const [saveMessage, setSaveMessage] = useState<string | null>(null)
-  const [saveError, setSaveError] = useState<string | null>(null)
+  // Save/delete/check-status all run through the shared hook's guarded run() (Story 29.6): a stale
+  // in-flight write can no longer repaint a newly-switched mill/year. `saving` is the single in-flight
+  // lock for every write (it also gates Check Status), replacing the old separate save/checking locks.
+  const {
+    saving,
+    message: saveMessage,
+    actionError: saveError,
+    checkResult,
+    setMessage: setSaveMessage,
+    setActionError: setSaveError,
+    setCheckResult,
+    clearBanners,
+    resetBanners,
+    save,
+    remove,
+    checkStatus,
+  } = useScheduleMutations<CheckStatusResponse>({ path: '/v1/schedule1', millId, year, isCurrent })
+
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false)
   const [confirmNavOpen, setConfirmNavOpen] = useState(false)
   const [otherCostsBlockedOpen, setOtherCostsBlockedOpen] = useState(false)
-  const [checking, setChecking] = useState(false)
-  const [checkResult, setCheckResult] = useState<CheckStatusResponse | null>(null)
-
-  // Clear the save/check notifications whenever a fresh document loads (mill/year change).
-  const resetMessages = useCallback(() => {
-    setSaveMessage(null)
-    setSaveError(null)
-    setCheckResult(null)
-  }, [])
 
   const { data, setData, form, setForm, setField, errorDetail, isLoading } =
     useScheduleDocument<Schedule1Response>({
@@ -151,7 +155,7 @@ const Schedule1: FC = () => {
       contextMissing,
       seedForm,
       mapLoadError: mapLoadErrorDetail,
-      onReset: resetMessages,
+      onReset: resetBanners,
     })
 
   // Re-group a numeric field's value on blur, so it reads like the plain-text cells beside it. Only
@@ -177,44 +181,30 @@ const Schedule1: FC = () => {
       setSaveError('Please correct the highlighted fields before saving.')
       return
     }
-    setSaving(true)
-    setSaveMessage(null)
-    setSaveError(null)
-    setCheckResult(null) // a prior Check Status result is stale once the data changes
-    apiService
-      .getAxiosInstance()
-      .put<Schedule1Response>(
-        `/v1/schedule1?millId=${millId}&year=${year}`,
-        buildRequest(data, form),
-      )
-      .then((response) => {
-        setData(response.data)
-        setForm(seedForm(response.data))
+    clearBanners() // drop any prior banners incl. a now-stale Check Status result
+    save<Schedule1Response>(buildRequest(data, form), {
+      fallback: 'Schedule could not be saved.',
+      onSuccess: (doc) => {
+        setData(doc)
+        setForm(seedForm(doc))
         // SUC-001 verbatim from the API message field (AD-8), never hardcoded.
-        setSaveMessage(response.data.message?.text ?? null)
-      })
-      .catch((error: unknown) => {
-        // Keep the entered values (S23/S24); surface the API's verbatim ProblemDetail.detail.
-        setSaveError(extractDetail(error) || 'Schedule could not be saved.')
-      })
-      .finally(() => setSaving(false))
+        setSaveMessage(doc.message?.text ?? null)
+      },
+    })
   }
 
   const handleDelete = () => {
     if (saving) {
       return
     }
     setConfirmDeleteOpen(false)
-    setSaving(true)
-    setSaveMessage(null)
-    setSaveError(null)
-    setCheckResult(null) // the deleted schedule's check result is stale
-    apiService
-      .getAxiosInstance()
-      .delete<{ message?: { text?: string } }>(`/v1/schedule1?millId=${millId}&year=${year}`)
-      .then((response) => {
-        // Delete removed the summary; a re-GET would 404, so reset to an empty schedule in place
-        // (no re-fetch) and show SUC-002 from the API message.
+    clearBanners() // the deleted schedule's check result / save banner are stale
+    remove<{ message?: { text?: string } }>({
+      fallback: 'Unable to delete Schedule 1.',
+      // Delete removed the summary; a re-GET would 404, so reset to an empty schedule in place (no
+      // re-fetch) and show SUC-002 from the API message. This per-page empty-state lives at the call
+      // site (Story 29.6): single-doc Schedules 1/3 reset in place; list pages re-seed from a reload.
+      onSuccess: (resp) => {
         setData((prev) =>
           prev
             ? {
@@ -236,32 +226,20 @@ const Schedule1: FC = () => {
             : prev,
         )
         setForm({})
-        setSaveMessage(response.data?.message?.text ?? null)
-      })
-      .catch((error: unknown) => {
-        setSaveError(extractDetail(error) || 'Unable to delete Schedule 1.')
-      })
-      .finally(() => setSaving(false))
+        setSaveMessage(resp?.message?.text ?? null)
+      },
+    })
   }
 
   const handleCheckStatus = () => {
-    if (!data || checking || saving) {
+    if (!data || saving) {
       return
     }
-    setChecking(true)
-    setCheckResult(null)
-    setSaveError(null)
-    setSaveMessage(null) // don't leave a stale Save success banner beside a new check result
-    apiService
-      .getAxiosInstance()
-      .post<CheckStatusResponse>(`/v1/schedule1/check-status?millId=${millId}&year=${year}`)
-      .then((response) => {
-        setCheckResult(response.data)
-      })
-      .catch((error: unknown) => {
-        setSaveError(extractDetail(error) || 'Unable to check status.')
-      })
-      .finally(() => setChecking(false))
+    clearBanners() // don't leave a stale Save success banner beside a new check result
+    checkStatus<CheckStatusResponse>({
+      fallback: 'Unable to check status.',
+      onSuccess: setCheckResult,
+    })
   }
 
   const handleOtherCosts = () => {
@@ -541,7 +519,9 @@ const Schedule1: FC = () => {
       className="schedule-1__actions"
       editable={editable}
       saving={saving}
-      checking={checking}
+      // Check Status now shares the single `saving` lock (it runs through the same run()); there is no
+      // separate checking flag, so both Save and Check disable together while any write is in flight.
+      checking={false}
       onSave={handleSave}
       onCheckStatus={handleCheckStatus}
       onDelete={() => setConfirmDeleteOpen(true)}

frontend/src/hooks/useScheduleMutations.ts

@@ -0,0 +1,78 @@
+import apiService from '@/service/api-service'
+import { useScheduleBanners } from '@/hooks/useScheduleBanners'
+
+const api = () => apiService.getAxiosInstance()
+
+type UseScheduleMutationsOptions = {
+  /** API base path, e.g. {@code '/v1/schedule1'}; mill/year are appended as query params. */
+  readonly path: string
+  readonly millId: number | null
+  readonly year: number | null
+  /** True while the render's mill/year still matches the live context — the stale-response guard. */
+  readonly isCurrent: () => boolean
+}
+
+type MutationOptions<T> = {
+  /** Applied only when the request resolves under the still-current context (see {@code run}). */
+  readonly onSuccess: (data: T) => void
+  /** Shown only when the rejection carries no ProblemDetail detail of its own (AD-8). */
+  readonly fallback: string
+  /** Appended to the base path before the mill/year query, e.g. {@code '/records/12'} for a by-id write. */
+  readonly suffix?: string
+}
+
+/**
+ * The shared save / delete / check-status concern for the schedule pages. Composes
+ * {@link useScheduleBanners} — so a page gets the banner + in-flight state AND the mutation helpers
+ * from one hook — and routes every write through its {@code run()}, which already carries the
+ * {@code isCurrent()} guard that stops a stale in-flight write from repainting a newly-switched
+ * mill/year context (proven on Schedules 7A/7B/9).
+ *
+ * <p>Pages supply only their {@code path} (and, per call, their {@code validateScheduleN} + the
+ * {@code onSuccess} that applies the echoed document). The request/error/lock scaffolding lives here
+ * and in {@code run()}, not re-hand-rolled per page. Delete deliberately takes its {@code onSuccess}
+ * at the call site: single-document pages whose re-GET would 404 (Schedules 1/3) reset to an empty
+ * read-only shape in place, while list pages (4/5/8) re-seed from the reload — a genuine per-page
+ * empty-state difference documented at the call site rather than forked into this hook.
+ *
+ * <p>Like {@code run()}, this hook is intentionally NOT memoized: its helpers close over the render's
+ * mill/year so each dispatch carries the current {@code isCurrent}.
+ */
+export function useScheduleMutations<TCheckResult>({
+  path,
+  millId,
+  year,
+  isCurrent,
+}: UseScheduleMutationsOptions) {
+  const banners = useScheduleBanners<TCheckResult>(isCurrent)
+
+  const query = `?millId=${String(millId)}&year=${String(year)}`
+  const url = (suffix = '') => `${path}${suffix}${query}`
+
+  /** PUT (default) or POST a body, then apply {@code onSuccess} under the guarded {@code run()}. */
+  const save = <T>(
+    body: unknown,
+    {
+      onSuccess,
+      fallback,
+      suffix,
+      method = 'put',
+    }: MutationOptions<T> & { method?: 'put' | 'post' },
+  ) =>
+    banners.run<T>(
+      method === 'post' ? api().post<T>(url(suffix), body) : api().put<T>(url(suffix), body),
+      { fallback, onSuccess },
+    )
+
+  /** DELETE, then apply the page's {@code onSuccess} (its own post-delete empty-state) under {@code run()}. */
+  const remove = <T>({ onSuccess, fallback, suffix }: MutationOptions<T>) =>
+    banners.run<T>(api().delete<T>(url(suffix)), { fallback, onSuccess })
+
+  /** POST the check-status endpoint (default suffix {@code '/check-status'}). */
+  const checkStatus = <T>({ onSuccess, fallback, suffix = '/check-status' }: MutationOptions<T>) =>
+    banners.run<T>(api().post<T>(url(suffix)), { fallback, onSuccess })
+
+  return { ...banners, query, url, save, remove, checkStatus }
+}
+
+export default useScheduleMutations