@byline/admin 6.2.1 → 6.4.0

package/src/forms/form-dom-scope.test.tsx

@@ -0,0 +1,213 @@
+/**
+ * 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 { createRoot, hydrateRoot, type Root } from 'react-dom/client'
+import { renderToString } from 'react-dom/server'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { FormProvider } from './form-context'
+import { useFormDomScope, useScopedDomId } from './form-dom-scope'
+
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+describe('form DOM scope', () => {
+  let container: HTMLDivElement
+  let root: Root
+
+  beforeEach(() => {
+    container = document.createElement('div')
+    document.body.appendChild(container)
+    root = createRoot(container)
+  })
+
+  afterEach(() => {
+    act(() => {
+      root.unmount()
+    })
+    container.remove()
+  })
+
+  const render = (node: React.ReactNode) => {
+    act(() => {
+      root.render(node)
+    })
+  }
+
+  it('gives two concurrently mounted providers different scopes', () => {
+    const scopes: string[] = []
+    const Probe = () => {
+      scopes.push(useFormDomScope())
+      return null
+    }
+
+    render(
+      <>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+      </>
+    )
+
+    expect(scopes).toHaveLength(2)
+    expect(new Set(scopes).size).toBe(2)
+  })
+
+  it('derives a stable id for the same base across re-renders', () => {
+    const seen: string[] = []
+    const Probe = () => {
+      seen.push(useScopedDomId('title'))
+      return null
+    }
+
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    expect(seen.length).toBeGreaterThanOrEqual(2)
+    expect(new Set(seen).size).toBe(1)
+  })
+
+  it('scopes the base so two forms derive different ids from one field name', () => {
+    const ids: string[] = []
+    const Probe = () => {
+      ids.push(useScopedDomId('title'))
+      return null
+    }
+
+    render(
+      <>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+      </>
+    )
+
+    expect(new Set(ids).size).toBe(2)
+    for (const id of ids) expect(id.endsWith('title')).toBe(true)
+  })
+
+  it('returns a caller-supplied id unchanged rather than scoping it twice', () => {
+    let derived = ''
+    const Probe = () => {
+      derived = useScopedDomId('title', 'explicit-id')
+      return null
+    }
+
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    expect(derived).toBe('explicit-id')
+  })
+
+  /**
+   * Field widgets render outside a form provider in places — the admin user and
+   * role screens compose them directly — so the hook has to degrade to the bare
+   * base rather than throw or invent a scope.
+   */
+  it('falls back to the bare base outside a provider', () => {
+    let derived = ''
+    let scope = 'unset'
+    const Probe = () => {
+      scope = useFormDomScope()
+      derived = useScopedDomId('title')
+      return null
+    }
+
+    render(<Probe />)
+
+    expect(scope).toBe('')
+    expect(derived).toBe('title')
+  })
+
+  it('produces a non-empty scope inside a provider', () => {
+    const scopes: string[] = []
+    const Probe = () => {
+      scopes.push(useFormDomScope())
+      return null
+    }
+
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    expect(scopes[0]).not.toBe('')
+  })
+
+  /**
+   * The reason the scope comes from `useId` rather than a counter or a random
+   * value: the server render and the hydration pass must agree. If they do not,
+   * React discards the server-rendered attributes and every `for` and
+   * `aria-labelledby` written during SSR points at an id that no longer exists.
+   *
+   * This renders on the server for real and hydrates that markup, rather than
+   * inspecting the shape of the generated string.
+   */
+  it('derives the same id on the server render and on hydration', async () => {
+    let renderedId = ''
+    const Probe = () => {
+      const id = useScopedDomId('title')
+      renderedId = id
+      return <span id={id}>title</span>
+    }
+    const tree = (
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    const html = renderToString(tree)
+    const serverId = /id="([^"]+)"/.exec(html)?.[1]
+    expect(serverId).toBeTruthy()
+
+    const host = document.createElement('div')
+    host.innerHTML = html
+    document.body.appendChild(host)
+
+    // React reports a hydration mismatch through console.error rather than by
+    // throwing, so silence alone is not evidence — collect and assert on it.
+    const consoleErrors: unknown[][] = []
+    const spy = vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+      consoleErrors.push(args)
+    })
+
+    let hydrated: Root | undefined
+    await act(async () => {
+      hydrated = hydrateRoot(host, tree)
+    })
+    spy.mockRestore()
+
+    expect(consoleErrors).toEqual([])
+    expect(renderedId).toBe(serverId)
+    expect(host.querySelector('span')?.id).toBe(serverId)
+
+    act(() => {
+      hydrated?.unmount()
+    })
+    host.remove()
+  })
+})

package/src/forms/form-dom-scope.tsx

@@ -0,0 +1,70 @@
+'use client'
+
+/**
+ * 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 type { ReactNode } from 'react'
+import { createContext, useContext, useId } from 'react'
+
+/**
+ * Per-form-instance prefix for derived DOM ids.
+ *
+ * Field widgets derive an element id from the field's path, and tab strips derive
+ * theirs from the tab-set name. Both are unique within one form and identical
+ * between two forms editing the same collection. Mount a second form — the
+ * relationship picker's creation view does exactly that — and every `label`'s
+ * `for`, every `aria-describedby` and every `aria-labelledby` resolves to whichever
+ * element the browser happens to see first, which is the parent form's. The reader
+ * then gets the wrong label announced and a click on a label focuses a field in a
+ * different form.
+ *
+ * `null` rather than `''` as the default so `useFormDomScope` can tell "no provider
+ * above me" from "a provider that produced an empty scope", even though both
+ * currently degrade to the same unprefixed id.
+ */
+const FormDomScopeContext = createContext<string | null>(null)
+
+/**
+ * Establishes one DOM id scope. `FormProvider` wraps its children in this, so a
+ * scope exists wherever form state does and no caller has to opt in.
+ */
+export const FormDomScopeProvider = ({ children }: { children: ReactNode }): ReactNode => {
+  // `useId` is the only generator that agrees between the server render and
+  // hydration. A counter or a random value produces different ids on each side,
+  // React discards the server-rendered attributes, and the `for`/`aria-*` pairings
+  // written during SSR are left pointing at ids that no longer exist.
+  const scope = useId()
+  return <FormDomScopeContext.Provider value={scope}>{children}</FormDomScopeContext.Provider>
+}
+
+/**
+ * The active scope, or `''` when rendered outside a form. Field widgets are also
+ * composed directly by the admin user and role screens, which have no
+ * `FormProvider`, so an absent scope degrades to the unprefixed id rather than
+ * throwing.
+ */
+export function useFormDomScope(): string {
+  return useContext(FormDomScopeContext) ?? ''
+}
+
+/**
+ * Scope a derived DOM id.
+ *
+ * A caller-supplied `id` is returned untouched: it is the author's identifier, it
+ * may already be referenced from outside the form, and scoping it would break that
+ * reference as well as double-prefix ids that pass through here twice.
+ *
+ * The result is a valid HTML id and a valid `for` / `aria-*` reference, but React's
+ * generated scope contains characters that need escaping in a CSS selector. Resolve
+ * these with `document.getElementById`, not `querySelector('#…')`.
+ */
+export function useScopedDomId(base: string, explicit?: string): string {
+  const scope = useFormDomScope()
+  if (explicit != null) return explicit
+  return scope === '' ? base : `${scope}${base}`
+}

package/src/forms/form-layout.tsx

@@ -8,7 +8,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 
-import { Fragment, type ReactNode } from 'react'
+import { Fragment, type ReactNode, useMemo } from 'react'
 
 import type {
   AdminResourceConfig,
@@ -24,6 +24,7 @@ import { FieldRenderer } from '../fields/field-renderer'
 import { AdminGroup } from '../presentation/group'
 import { AdminRow } from '../presentation/row'
 import { AdminTabs, tabPanelId, tabTriggerId } from '../presentation/tabs'
+import { useFormDomScope } from './form-dom-scope'
 import styles from './form-renderer.module.css'
 import { useFormLayout } from './use-form-layout'
 import { useFormTabs } from './use-form-tabs'
@@ -74,7 +75,13 @@ export const FormLayout = ({
 }: FormLayoutProps): ReactNode => {
   const { fieldByName, tabSetByName, rowByName, groupByName, layout, fieldToTabPath } =
     useFormLayout(adminConfig, fields)
-  const tabs = useFormTabs(fieldToTabPath, activeTabBySet)
+  const tabSets = useMemo(() => [...tabSetByName.values()], [tabSetByName])
+  const tabs = useFormTabs(fieldToTabPath, activeTabBySet, tabSets)
+  // Two forms over one collection share its admin configuration, so their tab
+  // sets carry the same name and would otherwise derive the same trigger and
+  // panel ids. `aria-labelledby` resolves document-wide, so the second form's
+  // panel would name the first form's trigger.
+  const domScope = useFormDomScope()
 
   const renderField = (fieldName: string): ReactNode => {
     const field = fieldByName.get(fieldName)
@@ -117,7 +124,7 @@ export const FormLayout = ({
 
   const renderTabSet = (set: TabSetDefinition): ReactNode => {
     const { visibleTabs, activeTabName, activeTab, errorCounts } = tabs.resolve(set)
-    const idBase = `tabset:${set.name}`
+    const idBase = `${domScope}tabset:${set.name}`
 
     return (
       <div key={idBase} className={cx('byline-form-tabset', styles.tabset)}>

package/src/forms/form-page-chrome.tsx

@@ -117,6 +117,21 @@ export const FormStatusBar = ({
 }: FormStatusBarProps): ReactNode => {
   const { t } = useTranslation('byline-admin')
   const { primaryStatus, secondaryStatuses, isTerminal } = transitions
+  const runTransition = async (status: string) => {
+    if (isBlocked() || !onStatusChange) return
+    if (hasChanges) {
+      onUnsavedChanges()
+      return
+    }
+    onStatusBusyChange(true)
+    try {
+      await onStatusChange(status)
+    } catch (error) {
+      onMutationError?.(error)
+    } finally {
+      onStatusBusyChange(false)
+    }
+  }
 
   return (
     <div className={cx('byline-form-status-bar', styles['status-bar'])}>
@@ -192,40 +207,8 @@ export const FormStatusBar = ({
               type="button"
               intent={isTerminal ? 'info' : 'success'}
               disabled={disabled || statusBusy}
-              onOptionSelect={async (value: string) => {
-                if (isBlocked()) return
-                if (hasChanges) {
-                  onUnsavedChanges()
-                  return
-                }
-                onStatusBusyChange(true)
-                try {
-                  await onStatusChange(value)
-                } catch (error) {
-                  onMutationError?.(error)
-                } finally {
-                  onStatusBusyChange(false)
-                }
-              }}
-              onButtonClick={
-                isTerminal
-                  ? undefined
-                  : async () => {
-                      if (isBlocked()) return
-                      if (hasChanges) {
-                        onUnsavedChanges()
-                        return
-                      }
-                      onStatusBusyChange(true)
-                      try {
-                        await onStatusChange(primaryStatus.name)
-                      } catch (error) {
-                        onMutationError?.(error)
-                      } finally {
-                        onStatusBusyChange(false)
-                      }
-                    }
-              }
+              onOptionSelect={runTransition}
+              onButtonClick={isTerminal ? undefined : () => runTransition(primaryStatus.name)}
             >
               {statusBusy
                 ? '...'

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

@@ -306,6 +306,42 @@ describe('FormRenderer submit contract', () => {
     document.body.removeAttribute('tabindex')
   })
 
+  it('starts a clean baseline after a successful save installs a new document version', async () => {
+    const onSubmit = vi.fn(async () => {})
+    const props = {
+      ...baseProps,
+      mode: 'edit',
+      onSubmit,
+      initialData: { id: 'doc', versionId: 'v1', revision: 1, fields: { title: 'Original' } },
+    }
+    render(props)
+    typeIntoTitle('Saved')
+    submitForm()
+    await act(async () => {})
+    expect(onSubmit.mock.calls).toHaveLength(1)
+    render({
+      ...props,
+      initialData: {
+        ...props.initialData,
+        versionId: 'v2',
+        revision: 2,
+        fields: { title: 'Saved' },
+      },
+    })
+    expect(container.querySelector<HTMLInputElement>('input[name="title"]')?.value).toBe('Saved')
+    typeIntoTitle('Next edit')
+    submitForm()
+    await act(async () => {})
+    const payload = (onSubmit.mock.calls as unknown as Array<[any]>)[1]?.[0]
+    expect(payload.data.title).toBe('Next edit')
+    expect(payload.patches).toHaveLength(1)
+    expect(payload.patches[0]).toMatchObject({
+      kind: 'field.set',
+      path: 'title',
+      value: 'Next edit',
+    })
+  })
+
   it('ignores a second submit while the first is still in flight', async () => {
     const submission = deferred()
     const onSubmit = vi.fn(async () => {

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()
@@ -422,6 +376,17 @@ const FormContent = ({
   }
 
   const handleSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
+    // A form rendered into a portal is not a DOM descendant of this one, so no
+    // invalid nested-form markup arises — but React propagates synthetic events
+    // along the *React* tree, so its submit still reaches this handler. Nothing
+    // about `currentTarget` reveals that: it is always this form while the
+    // handler runs, bubbled event or not. The event's origin is what
+    // distinguishes them.
+    //
+    // Deliberately no `preventDefault()` on the way out: the submit belongs to
+    // the inner form, and suppressing its default here would take that decision
+    // away from the handler that owns it.
+    if (e.target !== e.currentTarget) return
     e.preventDefault()
     if (mutationBlockedRef.current) return
     void submission.submit()
@@ -487,10 +452,7 @@ const FormContent = ({
             warningRef={warningRef}
             discarding={discarding}
             reloadFailed={reloadFailed}
-            onDiscardRequested={() => {
-              setReloadFailed(false)
-              setDiscarding(true)
-            }}
+            onDiscardRequested={requestDiscard}
             scheduling={scheduling}
             restoreWarnings={restoreWarnings}
           />