@byline/admin 6.3.0 → 6.4.0

package/src/forms/form-renderer.tsx

@@ -33,7 +33,8 @@ import {
   useScheduledPublication,
 } from './scheduled-publication-control'
 import { computeStatusTransitions } from './status-transitions'
-import { useFormSubmission } from './use-form-submission'
+import { useDocumentReloadRecovery } from './use-document-reload-recovery'
+import { type SystemFieldsSubmitPayload, useFormSubmission } from './use-form-submission'
 import type { DocumentActionsLocaleOption } from './document-actions'
 import type { UseNavigationGuard } from './navigation-guard'
 
@@ -63,7 +64,7 @@ export interface FormRendererProps {
   onReloadDocument?: () => void | Promise<void>
   mode: 'create' | 'edit'
   fields: Field[]
-  onSubmit: (data: any) => void | Promise<void>
+  onSubmit: (data: SystemFieldsSubmitPayload) => void | Promise<void>
   onCancel: () => void
   onStatusChange?: (nextStatus: string) => Promise<void>
   onUnpublish?: () => Promise<void>
@@ -238,9 +239,6 @@ const FormContent = ({
 
   const [hasChanges, setHasChanges] = useState(hasChangesFn())
   const [statusBusy, setStatusBusy] = useState(false)
-  const formRef = useRef<HTMLFormElement>(null)
-  const focusBeforeBusyRef = useRef<HTMLElement | null>(null)
-  const restoreFocusAfterBusyRef = useRef(false)
   // Block-only "save first" guard. Set true when the editor triggers a
   // guarded action (status change, duplicate, copy-to-locale) while the form
   // is dirty — those actions operate on the saved version, so unsaved edits
@@ -332,26 +330,6 @@ const FormContent = ({
   // The guard hook is injected by the consuming framework (prop > context > no-op fallback).
   const guardFromContext = useNavigationGuardAdapter()
   const useGuard = useNavigationGuardProp ?? guardFromContext
-  const [discarding, setDiscarding] = useState(false)
-  const [reloadFailed, setReloadFailed] = useState(false)
-  const warningRef = useRef<HTMLDivElement>(null)
-  const mutationBlockedRef = useRef(mutationsBlocked)
-  mutationBlockedRef.current = mutationsBlocked || discarding
-  const guard = useGuard(hasChanges && !discarding)
-  useEffect(() => {
-    if (mutationIssue) warningRef.current?.focus()
-  }, [mutationIssue])
-  useEffect(() => {
-    if (!discarding) return
-    // Let the guard's beforeunload listener detach before the explicit discard.
-    Promise.resolve()
-      .then(() => (onReloadDocument ? onReloadDocument() : window.location.reload()))
-      .catch(() => {
-        setDiscarding(false)
-        setReloadFailed(true)
-      })
-  }, [discarding, onReloadDocument])
-
   // Compute available status transitions
   const currentStatus = initialData?.status
   const { primaryStatus, secondaryStatuses, isTerminal } = computeStatusTransitions(
@@ -364,14 +342,6 @@ const FormContent = ({
     return subscribeMeta(() => setHasChanges(hasChangesFn()))
   }, [subscribeMeta, hasChangesFn])
 
-  const captureFocusBeforeBusy = useCallback(() => {
-    if (focusBeforeBusyRef.current != null) return
-    const activeElement = document.activeElement
-    if (!(activeElement instanceof HTMLElement) || !formRef.current?.contains(activeElement)) return
-    focusBeforeBusyRef.current = activeElement
-    restoreFocusAfterBusyRef.current = true
-  }, [])
-
   // One save at a time: validate -> upload -> (confirm) -> submit. Admission is
   // decided synchronously inside the hook, so two Saves in the same turn cannot
   // both get through. `phase` is what the UI renders.
@@ -381,40 +351,24 @@ const FormContent = ({
     documentId: mode === 'edit' && typeof initialData?.id === 'string' ? initialData.id : undefined,
     advertiseLocales,
     onSubmit,
-    isBlocked: () => mutationBlockedRef.current,
-    onBeforeBusy: captureFocusBeforeBusy,
+    isBlocked: (): boolean => recovery.mutationBlockedRef.current,
+    onBeforeBusy: (): void => recovery.captureFocusBeforeBusy(),
+  })
+  const recovery = useDocumentReloadRecovery({
+    mutationsBlocked,
+    mutationIssue,
+    onReloadDocument,
+    isBusy: submission.isBusy,
   })
+  const { formRef, warningRef, mutationBlockedRef, discarding, reloadFailed, requestDiscard } =
+    recovery
+  const guard = useGuard(hasChanges && !discarding)
   const isUploading = submission.phase.kind === 'uploading'
   const isSubmitting = submission.phase.kind === 'submitting'
   const isBusy = submission.isBusy
   const pendingSystemFieldsSubmit =
     submission.phase.kind === 'confirmingSystemFields' ? submission.phase.payload : null
 
-  // `inert` removes the active control from the tab order while a save is in
-  // flight. Restore the editor's position after React has removed `inert`;
-  // when the original control became disabled, fall back to the first usable
-  // form control instead of leaving focus on <body>.
-  useEffect(() => {
-    if (isBusy || !restoreFocusAfterBusyRef.current) return
-    restoreFocusAfterBusyRef.current = false
-
-    if (mutationIssue) {
-      warningRef.current?.focus()
-      focusBeforeBusyRef.current = null
-      return
-    }
-    const original = focusBeforeBusyRef.current
-    focusBeforeBusyRef.current = null
-    const originalCanReceiveFocus =
-      original?.isConnected === true && !original.matches(':disabled, [aria-disabled="true"]')
-    const target = originalCanReceiveFocus
-      ? original
-      : formRef.current?.querySelector<HTMLElement>(
-          'input:not(:disabled), textarea:not(:disabled), select:not(:disabled), button:not(:disabled), [tabindex]:not([tabindex="-1"])'
-        )
-    target?.focus({ preventScroll: true })
-  }, [isBusy, mutationIssue])
-
   const handleCancel = () => {
     if (onCancel && typeof onCancel === 'function') {
       onCancel()
@@ -498,10 +452,7 @@ const FormContent = ({
             warningRef={warningRef}
             discarding={discarding}
             reloadFailed={reloadFailed}
-            onDiscardRequested={() => {
-              setReloadFailed(false)
-              setDiscarding(true)
-            }}
+            onDiscardRequested={requestDiscard}
             scheduling={scheduling}
             restoreWarnings={restoreWarnings}
           />

package/src/forms/nested-path.ts

@@ -146,3 +146,38 @@ export function set<T extends object>(object: T, path: string, value: unknown):
   setWithResult(object, path, value)
   return object
 }
+
+/** Clone only the containers along a write path, preserving other snapshots. */
+export function withValue<T extends object>(
+  object: T,
+  path: string,
+  value: unknown
+): T | undefined {
+  const parsed = parseInstancePath(path)
+  if (!parsed.ok || !hasExistingIdTargets(object, path)) return undefined
+  const result: any = Array.isArray(object) ? [...object] : { ...object }
+  let current = result
+  for (const [index, segment] of parsed.segments.entries()) {
+    const key =
+      segment.kind === 'field'
+        ? segment.name
+        : segment.kind === 'index'
+          ? segment.index
+          : segment.kind === 'id'
+            ? selectId(current, segment.id)
+            : undefined
+    if (key === undefined || key === -1) return undefined
+    if (index === parsed.segments.length - 1) {
+      current[key] = value
+      return result
+    }
+    const existing = current[key]
+    current[key] = Array.isArray(existing)
+      ? [...existing]
+      : existing != null && typeof existing === 'object'
+        ? { ...existing }
+        : newContainer(parsed.segments[index + 1])
+    current = current[key]
+  }
+  return undefined
+}

package/src/forms/use-document-reload-recovery.ts

@@ -0,0 +1,92 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/** Reload admission and focus recovery remain synchronous at event boundaries. */
+export function useDocumentReloadRecovery({
+  mutationsBlocked,
+  mutationIssue,
+  onReloadDocument,
+  isBusy,
+}: {
+  mutationsBlocked: boolean
+  mutationIssue?: string | null
+  onReloadDocument?: () => void | Promise<void>
+  isBusy: boolean
+}) {
+  const formRef = useRef<HTMLFormElement>(null)
+  const focusBeforeBusyRef = useRef<HTMLElement | null>(null)
+  const restoreFocusAfterBusyRef = useRef(false)
+  const [discarding, setDiscarding] = useState(false)
+  const [reloadFailed, setReloadFailed] = useState(false)
+  const warningRef = useRef<HTMLDivElement>(null)
+  const mutationBlockedRef = useRef(mutationsBlocked)
+  mutationBlockedRef.current = mutationsBlocked || discarding
+  useEffect(() => {
+    if (mutationIssue) warningRef.current?.focus()
+  }, [mutationIssue])
+  useEffect(() => {
+    if (!discarding) return
+    // Let the guard's beforeunload listener detach before the explicit discard.
+    Promise.resolve()
+      .then(() => (onReloadDocument ? onReloadDocument() : window.location.reload()))
+      .catch(() => {
+        setDiscarding(false)
+        setReloadFailed(true)
+      })
+  }, [discarding, onReloadDocument])
+
+  const captureFocusBeforeBusy = useCallback(() => {
+    if (focusBeforeBusyRef.current != null) return
+    const activeElement = document.activeElement
+    if (!(activeElement instanceof HTMLElement) || !formRef.current?.contains(activeElement)) return
+    focusBeforeBusyRef.current = activeElement
+    restoreFocusAfterBusyRef.current = true
+  }, [])
+
+  // `inert` removes the active control from the tab order while a save is in
+  // flight. Restore the editor's position after React has removed `inert`;
+  // when the original control became disabled, fall back to the first usable
+  // form control instead of leaving focus on <body>.
+  useEffect(() => {
+    if (isBusy || !restoreFocusAfterBusyRef.current) return
+    restoreFocusAfterBusyRef.current = false
+
+    if (mutationIssue) {
+      warningRef.current?.focus()
+      focusBeforeBusyRef.current = null
+      return
+    }
+    const original = focusBeforeBusyRef.current
+    focusBeforeBusyRef.current = null
+    const originalCanReceiveFocus =
+      original?.isConnected === true && !original.matches(':disabled, [aria-disabled="true"]')
+    const target = originalCanReceiveFocus
+      ? original
+      : formRef.current?.querySelector<HTMLElement>(
+          'input:not(:disabled), textarea:not(:disabled), select:not(:disabled), button:not(:disabled), [tabindex]:not([tabindex="-1"])'
+        )
+    target?.focus({ preventScroll: true })
+  }, [isBusy, mutationIssue])
+
+  const requestDiscard = useCallback(() => {
+    mutationBlockedRef.current = true
+    setReloadFailed(false)
+    setDiscarding(true)
+  }, [])
+  return {
+    formRef,
+    warningRef,
+    mutationBlockedRef,
+    discarding,
+    reloadFailed,
+    requestDiscard,
+    captureFocusBeforeBusy,
+  }
+}

package/src/forms/use-form-submission.ts

@@ -10,7 +10,7 @@
 
 import { useCallback, useRef, useState } from 'react'
 
-import type { Field } from '@byline/core'
+import { type Field, getDocumentFieldValidationDetails } from '@byline/core'
 import type { DocumentPatch } from '@byline/core/patches'
 import { useTranslation } from '@byline/i18n/react'
 
@@ -105,7 +105,9 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
     setFieldValue,
     setFieldError,
     getPendingUploads,
-    clearPendingUploads,
+    removePendingUpload,
+    clearFieldError,
+    waitForFieldChanges,
     setFieldUploading,
   } = useFormContext()
   const { t } = useTranslation('byline-admin')
@@ -113,6 +115,7 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
 
   const [phase, setPhase] = useState<SubmissionPhase>(IDLE)
   const inFlightRef = useRef(false)
+  const confirmationRef = useRef<SystemFieldsSubmitPayload | null>(null)
 
   const isBusy = phase.kind === 'uploading' || phase.kind === 'submitting'
 
@@ -136,14 +139,16 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
       try {
         await onSubmit(payload)
         resetHasChanges()
-      } catch {
+      } catch (error) {
+        const validation = getDocumentFieldValidationDetails(error)
+        for (const issue of validation?.issues ?? []) setFieldError(issue.field, issue.message)
         // Intentionally swallowed here — the host has already reported the
         // failure to the user. Dirty state is preserved by not resetting.
       } finally {
         setPhase(IDLE)
       }
     },
-    [isBlocked, onBeforeBusy, onSubmit, resetHasChanges]
+    [isBlocked, onBeforeBusy, onSubmit, resetHasChanges, setFieldError]
   )
 
   const runUploads = useCallback(async (): Promise<boolean> => {
@@ -170,28 +175,31 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
         }
       )
 
+      // Adopt each success before reporting partial failure, so retries only
+      // transport failed files. Do not overwrite a selection replaced in flight.
+      for (const [fieldPath, storedFile] of uploadResult.successful) {
+        if (getPendingUploads().get(fieldPath) !== pendingUploads.get(fieldPath)) continue
+        setFieldValue(fieldPath, storedFile)
+        clearFieldError(fieldPath)
+        removePendingUpload(fieldPath)
+      }
       if (!uploadResult.allSucceeded) {
-        for (const [fieldPath, errorMessage] of uploadResult.errors.entries()) {
-          setFieldError(fieldPath, t('forms.uploadFailedFieldError', { message: errorMessage }))
+        for (const [fieldPath, errorMessage] of uploadResult.errors) {
+          if (getPendingUploads().get(fieldPath) === pendingUploads.get(fieldPath)) {
+            setFieldError(fieldPath, t('forms.uploadFailedFieldError', { message: errorMessage }))
+          }
         }
-        console.error('One or more uploads failed:', uploadResult.errors)
         return false
       }
-
-      // Replace pending StoredFileValues with real ones in form data
-      for (const [fieldPath, storedFile] of uploadResult.successful.entries()) {
-        setFieldValue(fieldPath, storedFile)
-      }
-
-      // Clear pending uploads (blob URLs already revoked by clearPendingUploads)
-      clearPendingUploads()
+      if (getPendingUploads().size > 0) return false
       return true
     } catch (err) {
       console.error('Upload execution error:', err)
       return false
     }
   }, [
-    clearPendingUploads,
+    removePendingUpload,
+    clearFieldError,
     documentId,
     fields,
     getFieldValues,
@@ -210,8 +218,8 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
     return {
       reason,
       payload: {
-        data: getFieldValues(),
-        patches: getPatches(),
+        data: structuredClone(getFieldValues()),
+        patches: structuredClone(getPatches()),
         contentDirty,
         pathDirty,
         systemPath: getSystemPath(),
@@ -230,21 +238,28 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
 
   const submit = useCallback(async () => {
     if (isBlocked()) return
-    if (inFlightRef.current) return
+    if (inFlightRef.current || confirmationRef.current) return
     inFlightRef.current = true
     try {
       setPhase({ kind: 'validating' })
 
       // Run field-level beforeValidate hooks (submit-time), then validate
-      const hookErrors = await runFieldHooks(fields)
-      const formErrors = validateForm(fields)
-      const allErrors = [...hookErrors, ...formErrors]
-
-      if (allErrors.length > 0) {
-        console.error('Form validation failed:', allErrors)
+      await waitForFieldChanges()
+      if (isBlocked()) {
         setPhase(IDLE)
         return
       }
+      // Metadata-only saves do not create a content version and must remain
+      // available even when an older document lacks newly required fields.
+      if (mode !== 'edit' || getDirtyBreakdown().reason !== 'direct-write') {
+        const hookErrors = await runFieldHooks(fields)
+        const formErrors = validateForm(fields, hookErrors)
+        if (formErrors.length > 0) {
+          console.error('Form validation failed:', formErrors)
+          setPhase(IDLE)
+          return
+        }
+      }
 
       if (isBlocked()) {
         setPhase(IDLE)
@@ -263,6 +278,7 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
       // so confirm it before saving. Create mode writes everything as part of
       // the initial version, so no confirmation applies there.
       if (mode === 'edit' && (reason === 'direct-write' || reason === 'both')) {
+        confirmationRef.current = payload
         setPhase({ kind: 'confirmingSystemFields', payload })
         return
       }
@@ -271,13 +287,25 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
     } finally {
       inFlightRef.current = false
     }
-  }, [buildPayload, deliver, fields, isBlocked, mode, runUploads, runFieldHooks, validateForm])
+  }, [
+    buildPayload,
+    getDirtyBreakdown,
+    deliver,
+    fields,
+    isBlocked,
+    mode,
+    runUploads,
+    runFieldHooks,
+    validateForm,
+    waitForFieldChanges,
+  ])
 
   const confirmSystemFields = useCallback(async () => {
-    if (phase.kind !== 'confirmingSystemFields') return
+    if (phase.kind !== 'confirmingSystemFields' || confirmationRef.current !== phase.payload) return
     if (inFlightRef.current) return
     inFlightRef.current = true
     const { payload } = phase
+    confirmationRef.current = null
     try {
       await deliver(payload)
     } finally {
@@ -286,6 +314,7 @@ export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSub
   }, [deliver, phase])
 
   const cancelSystemFields = useCallback(() => {
+    confirmationRef.current = null
     setPhase((current) => (current.kind === 'confirmingSystemFields' ? IDLE : current))
   }, [])
 

package/src/forms/use-form-tabs.ts

@@ -8,9 +8,9 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import { useEffect, useMemo, useState } from 'react'
+import { useCallback, useMemo, useSyncExternalStore } from 'react'
 
-import type { TabDefinition, TabSetDefinition } from '@byline/core'
+import { parseInstancePath, type TabDefinition, type TabSetDefinition } from '@byline/core'
 
 import { useFormContext } from './form-context'
 
@@ -42,27 +42,35 @@ export interface UseFormTabsResult {
  */
 export function useFormTabs(
   fieldToTabPath: Map<string, { tabSetName: string; tabName: string }>,
-  activeTabBySet: Record<string, string>
+  activeTabBySet: Record<string, string>,
+  tabSets: TabSetDefinition[]
 ): UseFormTabsResult {
-  const { errors: initialErrors, subscribeErrors, subscribeMeta, getFieldValues } = useFormContext()
-
-  const [errors, setErrors] = useState(initialErrors)
-  useEffect(() => {
-    return subscribeErrors((newErrors) => setErrors(newErrors))
-  }, [subscribeErrors])
-
-  // Live form data, so TabDefinition.condition re-evaluates per keystroke.
-  const [formData, setFormData] = useState<Record<string, any>>(() => getFieldValues())
-  useEffect(() => {
-    return subscribeMeta(() => setFormData(getFieldValues()))
-  }, [subscribeMeta, getFieldValues])
+  const { getErrors, subscribeErrors, subscribeMeta, getFieldValues } = useFormContext()
+  const errors = useSyncExternalStore(subscribeErrors, getErrors, getErrors)
+  const conditionalTabs = useMemo(
+    () => tabSets.flatMap((set) => set.tabs.filter((tab) => tab.condition)),
+    [tabSets]
+  )
+  const snapshot = useCallback(
+    () => JSON.stringify(conditionalTabs.map((tab) => Boolean(tab.condition?.(getFieldValues())))),
+    [conditionalTabs, getFieldValues]
+  )
+  const subscribe = useCallback(
+    (notify: () => void) => (conditionalTabs.length ? subscribeMeta(notify) : () => {}),
+    [conditionalTabs, subscribeMeta]
+  )
+  useSyncExternalStore(subscribe, snapshot, snapshot)
 
   // Per-tab-set error counts: { [tabSetName]: { [tabName]: count } }.
   // Each tab bar consumes its own slice.
   const errorCountsBySet = useMemo<Record<string, Record<string, number>>>(() => {
     const result: Record<string, Record<string, number>> = {}
     for (const err of errors) {
-      const path = fieldToTabPath.get(err.field)
+      const parsed = parseInstancePath(err.field)
+      const root = parsed.ok ? parsed.segments[0] : undefined
+      const path =
+        fieldToTabPath.get(err.field) ??
+        (root?.kind === 'field' ? fieldToTabPath.get(root.name) : undefined)
       if (!path) continue
       result[path.tabSetName] ??= {}
       result[path.tabSetName]![path.tabName] = (result[path.tabSetName]?.[path.tabName] ?? 0) + 1
@@ -71,7 +79,7 @@ export function useFormTabs(
   }, [errors, fieldToTabPath])
 
   const resolve = (set: TabSetDefinition): ResolvedTabSet => {
-    const visibleTabs = set.tabs.filter((tab) => !tab.condition || tab.condition(formData))
+    const visibleTabs = set.tabs.filter((tab) => !tab.condition || tab.condition(getFieldValues()))
     const requested = activeTabBySet[set.name] ?? ''
     const activeTabName =
       visibleTabs.length > 0 && !visibleTabs.some((t) => t.name === requested)