@byline/admin 6.2.1 → 6.4.0

package/src/forms/form-submit-isolation.test.tsx

@@ -0,0 +1,247 @@
+/**
+ * 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 { act } from 'react'
+
+import { defineAdminConfig } from '@byline/core'
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createPortal } from 'react-dom'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { BylineFieldServicesProvider } from '../fields/field-services-context'
+import { FormRenderer } from './form-renderer'
+
+const globalWithAct = globalThis as any
+globalWithAct.IS_REACT_ACT_ENVIRONMENT = true
+
+defineAdminConfig({
+  i18n: {
+    admin: { defaultLocale: 'en', locales: ['en'] },
+    content: { defaultLocale: 'en', locales: ['en'] },
+  },
+  collections: [
+    {
+      path: 'pages',
+      labels: { singular: 'Page', plural: 'Pages' },
+      fields: [{ name: 'title', label: 'Title', type: 'text' }],
+    },
+  ],
+  slugifier: (value: string) => value.toLowerCase().trim().replace(/\s+/g, '-'),
+})
+
+const fieldServices = {
+  getCollectionDocuments: async () => ({ docs: [], total: 0 }),
+  uploadField: async () => ({}),
+} as any
+
+// Optional so submission is not blocked by validation: this file tests which
+// form a submit event belongs to, not what the form does with it.
+const fields = [{ name: 'title', label: 'Title', type: 'text' as const, optional: true }]
+
+let container: HTMLDivElement
+let root: Root
+let portalHost: HTMLDivElement
+
+beforeEach(() => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  portalHost = document.createElement('div')
+  document.body.appendChild(portalHost)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => {
+    root.unmount()
+  })
+  container.remove()
+  portalHost.remove()
+})
+
+/**
+ * A nested form rendered through a portal: outside the parent `<form>` in the
+ * DOM, so no invalid nested-form markup arises, but still a descendant in the
+ * *React* tree — which is what React propagates synthetic events along.
+ */
+const PortalledInnerForm = ({
+  stopPropagation,
+  onInnerSubmit,
+}: {
+  stopPropagation: boolean
+  onInnerSubmit: () => void
+}) =>
+  createPortal(
+    <form
+      data-testid="inner-form"
+      onSubmit={(event) => {
+        event.preventDefault()
+        if (stopPropagation) event.stopPropagation()
+        onInnerSubmit()
+      }}
+    >
+      <input name="innerTitle" defaultValue="" />
+      <button type="submit">Save inner</button>
+    </form>,
+    portalHost
+  )
+
+const renderWithInnerForm = ({
+  parentSubmit,
+  onInnerSubmit = () => {},
+  stopPropagation = false,
+}: {
+  parentSubmit: () => Promise<void>
+  onInnerSubmit?: () => void
+  stopPropagation?: boolean
+}) => {
+  act(() => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        <BylineFieldServicesProvider services={fieldServices}>
+          <FormRenderer
+            mode="create"
+            fields={fields}
+            collectionPath="pages"
+            onCancel={() => {}}
+            onSubmit={parentSubmit}
+            headerSlot={
+              <PortalledInnerForm stopPropagation={stopPropagation} onInnerSubmit={onInnerSubmit} />
+            }
+          />
+        </BylineFieldServicesProvider>
+      </I18nProvider>
+    )
+  })
+}
+
+const parentForm = () => {
+  const form = container.querySelector('form')
+  if (form == null) throw new Error('parent form not found')
+  return form
+}
+
+const innerForm = () => {
+  const form = portalHost.querySelector<HTMLFormElement>('[data-testid="inner-form"]')
+  if (form == null) throw new Error('inner form not found')
+  return form
+}
+
+const submit = async (form: HTMLFormElement) => {
+  await act(async () => {
+    form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+  })
+}
+
+describe('submit isolation across a portal', () => {
+  /**
+   * The inner form here deliberately does **not** call `stopPropagation`, so
+   * these two cases exercise the parent's own guard. With the child-side defence
+   * in place as well, a broken parent guard would be invisible.
+   */
+  it('does not run the parent submit handler when a portalled inner form submits', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    renderWithInnerForm({ parentSubmit })
+
+    await submit(innerForm())
+
+    expect(parentSubmit).not.toHaveBeenCalled()
+  })
+
+  it('still runs the inner form’s own handler', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    const onInnerSubmit = vi.fn()
+    renderWithInnerForm({ parentSubmit, onInnerSubmit })
+
+    await submit(innerForm())
+
+    expect(onInnerSubmit).toHaveBeenCalledTimes(1)
+    expect(parentSubmit).not.toHaveBeenCalled()
+  })
+
+  it('still submits normally from the parent form itself', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    renderWithInnerForm({ parentSubmit })
+
+    await submit(parentForm())
+
+    expect(parentSubmit).toHaveBeenCalledTimes(1)
+  })
+
+  it('leaves the parent form submitting on repeat after an inner submit', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    renderWithInnerForm({ parentSubmit })
+
+    await submit(innerForm())
+    await submit(parentForm())
+    await submit(parentForm())
+
+    expect(parentSubmit).toHaveBeenCalledTimes(2)
+  })
+})
+
+/**
+ * The child-side defence, proved without the parent guard in the picture. If this
+ * were asserted against `FormRenderer`, a working parent guard would satisfy it
+ * whether or not the child stopped propagation, and the test would prove nothing
+ * about the child.
+ */
+describe('the child-side stopPropagation defence', () => {
+  const PlainParent = ({
+    onParentSubmit,
+    stopPropagation,
+  }: {
+    onParentSubmit: () => void
+    stopPropagation: boolean
+  }) => (
+    <form
+      data-testid="plain-parent"
+      onSubmit={(event) => {
+        event.preventDefault()
+        onParentSubmit()
+      }}
+    >
+      <PortalledInnerForm stopPropagation={stopPropagation} onInnerSubmit={() => {}} />
+    </form>
+  )
+
+  const renderPlain = (props: { onParentSubmit: () => void; stopPropagation: boolean }) => {
+    act(() => {
+      root.render(<PlainParent {...props} />)
+    })
+  }
+
+  it('keeps an unguarded parent handler from running when the child stops propagation', async () => {
+    const onParentSubmit = vi.fn()
+    renderPlain({ onParentSubmit, stopPropagation: true })
+
+    await submit(innerForm())
+
+    expect(onParentSubmit).not.toHaveBeenCalled()
+  })
+
+  /**
+   * The control: the same unguarded parent, with the child defence removed. It
+   * fails in exactly the way the feature is meant to prevent, which is what makes
+   * the assertion above meaningful.
+   */
+  it('runs an unguarded parent handler when the child does not stop propagation', async () => {
+    const onParentSubmit = vi.fn()
+    renderPlain({ onParentSubmit, stopPropagation: false })
+
+    await submit(innerForm())
+
+    expect(onParentSubmit).toHaveBeenCalledTimes(1)
+  })
+})

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)