@byline/admin 4.19.0 → 5.0.0

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

@@ -46,8 +46,8 @@ vi.mock('@byline/ui/react', async (importOriginal) => {
       Separator: () => <hr />,
     },
     Modal,
-    Input: ({ name, value, onChange }: any) => (
-      <input name={name} value={value ?? ''} onChange={onChange} />
+    Input: ({ id, name, value, onChange, disabled }: React.ComponentProps<'input'>) => (
+      <input id={id} name={name} disabled={disabled} value={value ?? ''} onChange={onChange} />
     ),
   }
 })
@@ -286,3 +286,132 @@ describe('FormRenderer submit contract', () => {
     expect(onSubmit).toHaveBeenCalledTimes(1)
   })
 })
+
+describe('persistent document concurrency recovery', () => {
+  const original = {
+    id: 'doc',
+    versionId: 'v1',
+    revision: 7,
+    path: 'opened',
+    status: 'draft',
+    fields: { title: 'Opened' },
+    _availableVersionLocales: ['en'],
+  }
+  const props = {
+    mode: 'edit' as const,
+    fields,
+    initialData: original,
+    collectionPath: 'pages',
+    useAsPath: 'title',
+    advertiseLocales: true,
+    contentLocales: [{ code: 'en', label: 'English' }],
+    workflowStatuses: [
+      { name: 'draft', label: 'Draft' },
+      { name: 'published', label: 'Published' },
+    ],
+  }
+  it.each(['stale', 'reload', 'lock', 'unavailable'] as const)(
+    'retains dirty fields and blocks mutations for %s',
+    async (mutationIssue) => {
+      const onSubmit = vi.fn()
+      const onDelete = vi.fn()
+      const onStatusChange = vi.fn()
+      const guard = vi.fn(() => ({ isBlocked: false, stay() {}, proceed() {} }))
+      const render = (blocked: boolean) =>
+        renderInProvider(
+          <FormRenderer
+            {...props}
+            onSubmit={onSubmit}
+            onDelete={onDelete}
+            onStatusChange={onStatusChange}
+            mutationsBlocked={blocked}
+            mutationIssue={blocked ? mutationIssue : null}
+            useNavigationGuard={guard}
+          />
+        )
+      render(false)
+      typeIntoTitle('Unsaved text to copy')
+      render(true)
+      expect(container.querySelector<HTMLInputElement>('input[name="title"]')?.value).toBe(
+        'Unsaved text to copy'
+      )
+      expect(container.querySelector<HTMLInputElement>('input[name="title"]')?.disabled).toBe(false)
+      expect(guard).toHaveBeenLastCalledWith(true)
+      expect(container.querySelector<HTMLButtonElement>('button[type="submit"]')?.disabled).toBe(
+        true
+      )
+      expect(container.querySelector<HTMLInputElement>('#system-path')?.disabled).toBe(true)
+      expect(container.querySelector<HTMLInputElement>('#available-locale-en')?.disabled).toBe(true)
+      const warning = container.querySelector('.byline-document-concurrency')
+      expect(warning?.getAttribute('role')).toBe('alert')
+      expect(document.activeElement).toBe(warning)
+      submitForm()
+      await act(async () => {})
+      expect(onSubmit).not.toHaveBeenCalled()
+      expect(onDelete).not.toHaveBeenCalled()
+      expect(onStatusChange).not.toHaveBeenCalled()
+    }
+  )
+  it('disables the dirty navigation guard only after explicit discard and retains it on reload failure', async () => {
+    const guard = vi.fn(() => ({ isBlocked: false, stay() {}, proceed() {} }))
+    const reload = vi.fn(async () => {
+      throw new Error('reload failed')
+    })
+    const render = (blocked: boolean) =>
+      renderInProvider(
+        <FormRenderer
+          {...props}
+          onSubmit={async () => {}}
+          mutationsBlocked={blocked}
+          mutationIssue={blocked ? 'stale' : null}
+          useNavigationGuard={guard}
+          onReloadDocument={reload}
+        />
+      )
+    render(false)
+    typeIntoTitle('Keep until I discard')
+    render(true)
+    expect(reload).not.toHaveBeenCalled()
+    expect(guard).toHaveBeenLastCalledWith(true)
+    const reloadButton = Array.from(container.querySelectorAll('button')).find(
+      (button) => button.textContent === 'Reload and discard my changes'
+    )
+    expect(reloadButton).toBeDefined()
+    await act(async () => {
+      reloadButton?.click()
+    })
+    expect(reload).toHaveBeenCalledTimes(1)
+    expect(guard).toHaveBeenCalledWith(false)
+    expect(guard).toHaveBeenLastCalledWith(true)
+    expect(container.textContent).toContain('Reload failed. Your unsaved changes are still here.')
+    expect(container.querySelector<HTMLInputElement>('input[name="title"]')?.value).toBe(
+      'Keep until I discard'
+    )
+  })
+  it('shows structural schedule suspension separately without marking the form stale or clearing edits', () => {
+    const render = (notice: boolean) =>
+      renderInProvider(
+        <FormRenderer
+          {...props}
+          onSubmit={async () => {}}
+          scheduledPublicationsNeedReconfirmation={notice}
+          scheduledPublicationsHref="/admin/scheduled-publications"
+        />
+      )
+    render(false)
+    typeIntoTitle('Draft retained after tree move')
+    render(true)
+    expect(container.textContent).toContain('The structure was saved.')
+    expect(
+      container.querySelector<HTMLAnchorElement>('a[href="/admin/scheduled-publications"]')
+        ?.textContent
+    ).toBe('Review scheduled publications')
+    expect(container.textContent).not.toContain('Your changes were not saved.')
+    expect(container.querySelector<HTMLButtonElement>('button[type="submit"]')?.disabled).toBe(
+      false
+    )
+    expect(container.querySelector<HTMLInputElement>('input[name="title"]')?.value).toBe(
+      'Draft retained after tree move'
+    )
+  })
+})

package/src/forms/form-renderer.module.css

@@ -265,6 +265,26 @@
   min-height: 28px;
 }
 
+/*
+ * Concurrency alerts (stale document, lock conflict, schedule reconfirmation).
+ * Separated from the status bar above and from the form layout below, which
+ * otherwise carries its standing top padding on top of the alert's own gap.
+ */
+.concurrency,
+:global(.byline-document-concurrency) {
+  margin-top: var(--spacing-16);
+}
+
+.concurrency button,
+:global(.byline-document-concurrency) button {
+  margin-top: var(--spacing-12);
+}
+
+.concurrency ~ .layout,
+:global(.byline-document-concurrency) ~ :global(.byline-form-layout) {
+  padding-top: var(--spacing-16);
+}
+
 .layout,
 :global(.byline-form-layout) {
   display: flex;

package/src/forms/form-renderer.tsx

@@ -80,6 +80,15 @@ export interface SystemFieldsSubmitPayload {
 
 /** Props shared by both the public FormRenderer and its internal FormContent component. */
 export interface FormRendererProps {
+  mutationIssue?: 'stale' | 'reload' | 'lock' | 'unavailable' | 'committed' | null
+  mutationsBlocked?: boolean
+  observedRevision?: number
+  onMutationError?: (error: unknown) => 'blocked' | 'committed' | null | void
+  onTreeMutationCommitted?: (receipt: import('@byline/core').StructuralMutationReceipt) => void
+  scheduledPublicationsNeedReconfirmation?: boolean
+  scheduledPublicationsHref?: string
+  /** Explicit discard action; defaults to a complete server reload. */
+  onReloadDocument?: () => void | Promise<void>
   mode: 'create' | 'edit'
   fields: Field[]
   onSubmit: (data: any) => void | Promise<void>
@@ -196,6 +205,14 @@ export interface FormRendererProps {
 
 const FormContent = ({
   mode,
+  mutationIssue,
+  mutationsBlocked = false,
+  observedRevision,
+  onMutationError,
+  onTreeMutationCommitted,
+  scheduledPublicationsNeedReconfirmation = false,
+  scheduledPublicationsHref,
+  onReloadDocument,
   fields,
   onSubmit,
   onCancel,
@@ -283,6 +300,7 @@ const FormContent = ({
   // escalated notice, and the schedule modal — so its state lives here and the
   // surfaces are rendered where each belongs.
   const scheduling = useScheduledPublication({
+    disabled: mutationsBlocked,
     schedule: scheduledPublication ?? null,
     onSchedule: onSchedulePublication,
     onConfirm: onConfirmScheduledPublication,
@@ -373,7 +391,25 @@ const FormContent = ({
   // The guard hook is injected by the consuming framework (prop > context > no-op fallback).
   const guardFromContext = useNavigationGuardAdapter()
   const useGuard = useNavigationGuardProp ?? guardFromContext
-  const guard = useGuard(hasChanges)
+  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
@@ -404,6 +440,11 @@ const FormContent = ({
     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 =
@@ -414,7 +455,7 @@ const FormContent = ({
           'input:not(:disabled), textarea:not(:disabled), select:not(:disabled), button:not(:disabled), [tabindex]:not([tabindex="-1"])'
         )
     target?.focus({ preventScroll: true })
-  }, [isBusy])
+  }, [isBusy, mutationIssue])
 
   const captureFocusBeforeBusy = useCallback(() => {
     if (focusBeforeBusyRef.current != null) return
@@ -438,7 +479,7 @@ const FormContent = ({
   // mid-flight; the mirrored state drives the Save button's disabled prop.
   const submitPayload = useCallback(
     async (payload: SystemFieldsSubmitPayload) => {
-      if (typeof onSubmit !== 'function') return
+      if (mutationBlockedRef.current || typeof onSubmit !== 'function') return
       if (submittingRef.current) return
       submittingRef.current = true
       captureFocusBeforeBusy()
@@ -458,6 +499,10 @@ const FormContent = ({
   )
 
   const handleSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
+    if (mutationBlockedRef.current) {
+      e.preventDefault()
+      return
+    }
     e.preventDefault()
 
     // Run field-level beforeValidate hooks (submit-time), then validate
@@ -471,6 +516,8 @@ const FormContent = ({
         return
       }
 
+      if (mutationBlockedRef.current) return
+
       // Execute any pending uploads before submitting
       const pendingUploads = getPendingUploads()
       if (pendingUploads.size > 0) {
@@ -674,6 +721,7 @@ const FormContent = ({
           <div className={cx('byline-form-status-bar', styles['status-bar'])}>
             <div className={cx('byline-form-status-details', styles['status-details'])}>
               <FormStatusDisplay
+                disabled={mutationsBlocked || discarding}
                 initialData={initialData}
                 workflowStatuses={workflowStatuses}
                 publishedVersion={publishedVersion}
@@ -700,7 +748,13 @@ const FormContent = ({
                 className={cx('byline-form-actions-button', styles['actions-button'])}
                 size="sm"
                 type="submit"
-                disabled={hasChanges === false || isUploading || isSubmitting}
+                disabled={
+                  mutationsBlocked ||
+                  discarding ||
+                  hasChanges === false ||
+                  isUploading ||
+                  isSubmitting
+                }
                 aria-label={isSubmitting ? t('common.actions.save') : undefined}
               >
                 {isUploading ? (
@@ -747,8 +801,9 @@ const FormContent = ({
                     size="sm"
                     type="button"
                     intent={isTerminal ? 'info' : 'success'}
-                    disabled={statusBusy}
+                    disabled={mutationsBlocked || discarding || statusBusy}
                     onOptionSelect={async (value: string) => {
+                      if (mutationBlockedRef.current) return
                       if (hasChanges) {
                         setShowUnsavedModal(true)
                         return
@@ -756,6 +811,8 @@ const FormContent = ({
                       setStatusBusy(true)
                       try {
                         await onStatusChange(value)
+                      } catch (error) {
+                        onMutationError?.(error)
                       } finally {
                         setStatusBusy(false)
                       }
@@ -764,6 +821,7 @@ const FormContent = ({
                       isTerminal
                         ? undefined
                         : async () => {
+                            if (mutationBlockedRef.current) return
                             if (hasChanges) {
                               setShowUnsavedModal(true)
                               return
@@ -771,6 +829,8 @@ const FormContent = ({
                             setStatusBusy(true)
                             try {
                               await onStatusChange(primaryStatus.name)
+                            } catch (error) {
+                              onMutationError?.(error)
                             } finally {
                               setStatusBusy(false)
                             }
@@ -786,6 +846,7 @@ const FormContent = ({
                 </div>
               )}
               <DocumentActions
+                disabled={mutationsBlocked || discarding}
                 publishedVersion={publishedVersion}
                 onUnpublish={onUnpublish}
                 onDelete={onDelete}
@@ -813,10 +874,58 @@ const FormContent = ({
               />
             </div>
           </div>
+          {(mutationIssue || scheduledPublicationsNeedReconfirmation) && (
+            <div
+              ref={warningRef}
+              tabIndex={-1}
+              role="alert"
+              aria-live="assertive"
+              className={cx('byline-document-concurrency', styles.concurrency)}
+            >
+              {mutationIssue && (
+                <Alert
+                  intent="warning"
+                  icon
+                  close={false}
+                  title={t(`documentConcurrency.${mutationIssue}Title`)}
+                >
+                  <p>{t(`documentConcurrency.${mutationIssue}`)}</p>
+                  {mutationIssue !== 'committed' && (
+                    <Button
+                      type="button"
+                      disabled={discarding}
+                      onClick={() => {
+                        setReloadFailed(false)
+                        setDiscarding(true)
+                      }}
+                    >
+                      {t('documentConcurrency.reloadAction')}
+                    </Button>
+                  )}
+                  {reloadFailed && <p>{t('documentConcurrency.reloadFailed')}</p>}
+                </Alert>
+              )}
+              {scheduledPublicationsNeedReconfirmation && (
+                <Alert
+                  intent="warning"
+                  icon
+                  close={false}
+                  title={t('documentConcurrency.schedulesTitle')}
+                >
+                  <p>{t('documentConcurrency.schedules')}</p>
+                  {scheduledPublicationsHref && (
+                    <a href={scheduledPublicationsHref}>
+                      {t('documentConcurrency.reviewSchedules')}
+                    </a>
+                  )}
+                </Alert>
+              )}
+            </div>
+          )}
           <ScheduledPublicationNotice
             state={scheduling.state}
             timeZone={scheduling.timeZone}
-            busy={scheduling.busy}
+            busy={mutationsBlocked || discarding || scheduling.busy}
             onConfirm={scheduling.confirm}
             onReschedule={scheduling.openSchedule}
             onCancel={scheduling.cancel}
@@ -847,6 +956,7 @@ const FormContent = ({
                 (useAsPath ||
                   (typeof initialData?.path === 'string' && initialData.path.length > 0)) && (
                   <PathWidget
+                    disabled={mutationsBlocked || discarding}
                     useAsPath={useAsPath}
                     collectionPath={collectionPath ?? ''}
                     defaultLocale={defaultLocale}
@@ -858,6 +968,10 @@ const FormContent = ({
                 )}
               {tree && mode === 'edit' && typeof initialData?.id === 'string' && (
                 <TreePlacementWidget
+                  disabled={mutationsBlocked || discarding}
+                  onMutationError={onMutationError}
+                  onCommitted={onTreeMutationCommitted}
+                  expectedRevision={observedRevision ?? initialData.revision}
                   collectionPath={collectionPath ?? ''}
                   documentId={initialData.id as string}
                   useAsTitle={useAsTitle}
@@ -865,6 +979,7 @@ const FormContent = ({
               )}
               {advertiseLocales && (
                 <AvailableLocalesWidget
+                  disabled={mutationsBlocked || discarding}
                   contentLocales={contentLocales ?? []}
                   availableVersionLocales={
                     (initialData?._availableVersionLocales as string[] | undefined) ?? []
@@ -875,7 +990,7 @@ const FormContent = ({
             </div>
           </div>
           {showUnsavedModal && <UnsavedChangesModal onClose={() => setShowUnsavedModal(false)} />}
-          {pendingSystemFieldsSubmit != null && (
+          {!mutationsBlocked && !discarding && pendingSystemFieldsSubmit != null && (
             <SystemFieldsConfirmModal
               contentDirty={pendingSystemFieldsSubmit.contentDirty}
               pathDirty={pendingSystemFieldsSubmit.pathDirty}

package/src/forms/form-status-display.tsx

@@ -23,12 +23,14 @@ import type { PublishedVersionInfo } from './form-renderer'
  * Unpublish action when a previously-published version is still live.
  */
 export const FormStatusDisplay = ({
+  disabled = false,
   initialData,
   workflowStatuses,
   publishedVersion,
   onUnpublish,
   afterStatusCells,
 }: {
+  disabled?: boolean
   initialData?: Record<string, any>
   workflowStatuses?: WorkflowStatus[]
   publishedVersion?: PublishedVersionInfo | null
@@ -106,7 +108,10 @@ export const FormStatusDisplay = ({
               {' '}
               <button
                 type="button"
-                onClick={onUnpublish}
+                disabled={disabled}
+                onClick={() => {
+                  if (!disabled) void onUnpublish().catch(() => {})
+                }}
                 className={cx('byline-form-status-unpublish', styles['status-unpublish'])}
               >
                 {t('common.actions.unpublish')}

package/src/forms/path-widget.tsx

@@ -31,6 +31,7 @@ function coerceToString(value: unknown): string {
 }
 
 export interface PathWidgetProps {
+  disabled?: boolean
   /** The collection's `useAsPath` source field name, when configured. */
   useAsPath: string | undefined
   /** Collection path, forwarded to the slugifier as context. */
@@ -91,6 +92,7 @@ export const PathWidget = ({
   mode,
   slugifier,
   sourceLocked = false,
+  disabled = false,
 }: PathWidgetProps) => {
   const { setSystemPath } = useFormContext()
   const { t } = useTranslation('byline-admin')
@@ -125,18 +127,19 @@ export const PathWidget = ({
 
   const handleChange = useCallback(
     (next: string) => {
+      if (disabled) return
       // Empty string clears the override — server falls back to derive
       // (create) or sticky (update).
       setSystemPath(next.length === 0 ? null : next)
     },
-    [setSystemPath]
+    [disabled, setSystemPath]
   )
 
   const handleRegenerate = useCallback(() => {
-    if (livePreview.length > 0) {
+    if (!disabled && livePreview.length > 0) {
       setSystemPath(livePreview)
     }
-  }, [livePreview, setSystemPath])
+  }, [disabled, livePreview, setSystemPath])
 
   // Validate live: if the typed value differs from its slugified form,
   // surface an inline hint without blocking input (mirrors the previous
@@ -184,6 +187,7 @@ export const PathWidget = ({
             type="button"
             onClick={handleRegenerate}
             className={cx('byline-form-path-regenerate', styles.regenerate)}
+            disabled={disabled}
             aria-label={t('pathWidget.regenerateAriaLabel', { field: useAsPath })}
           >
             {t('pathWidget.regenerateButton', { field: useAsPath })}
@@ -191,6 +195,7 @@ export const PathWidget = ({
         )}
       </div>
       <Input
+        disabled={disabled}
         id="system-path"
         name="__systemPath__"
         value={inputValue}

package/src/forms/scheduled-publication-control.tsx

@@ -110,6 +110,7 @@ function seedScheduleInstant(schedule: ScheduledPublicationInfo | null): Date {
 }
 
 export interface UseScheduledPublicationArgs {
+  disabled?: boolean
   schedule: ScheduledPublicationInfo | null
   onSchedule?: (input: SchedulePublicationInput) => Promise<void>
   onConfirm?: () => Promise<void>
@@ -132,6 +133,7 @@ export interface UseScheduledPublicationReturn {
 }
 
 export function useScheduledPublication({
+  disabled = false,
   schedule,
   onSchedule,
   onConfirm,
@@ -171,15 +173,16 @@ export function useScheduledPublication({
   // to be resolved before any of these operations can name a version. Cancel
   // is exempt: withdrawing a schedule says nothing about content.
   const openSchedule = useCallback(() => {
+    if (disabled) return
     if (hasUnsavedChanges) {
       onUnsavedChanges()
       return
     }
     setShowSchedule(true)
-  }, [hasUnsavedChanges, onUnsavedChanges])
+  }, [disabled, hasUnsavedChanges, onUnsavedChanges])
 
   const confirm = useCallback(async () => {
-    if (onConfirm == null) return
+    if (disabled || onConfirm == null) return
     if (hasUnsavedChanges) {
       onUnsavedChanges()
       return
@@ -187,37 +190,43 @@ export function useScheduledPublication({
     setBusy(true)
     try {
       await onConfirm()
+    } catch {
+      // The host reports the failure; keep this view open.
     } finally {
       setBusy(false)
     }
-  }, [onConfirm, hasUnsavedChanges, onUnsavedChanges])
+  }, [disabled, onConfirm, hasUnsavedChanges, onUnsavedChanges])
 
   const cancel = useCallback(async () => {
-    if (onCancel == null) return
+    if (disabled || onCancel == null) return
     setBusy(true)
     try {
       await onCancel()
+    } catch {
+      // The host reports the failure; keep this view open.
     } finally {
       setBusy(false)
     }
-  }, [onCancel])
+  }, [disabled, onCancel])
 
   const modal = showSchedule ? (
     <ScheduleModal
       schedule={schedule}
       timeZone={timeZone}
       onSubmit={async (input) => {
-        if (onSchedule == null) return
+        if (disabled || onSchedule == null) return
         setBusy(true)
         try {
           await onSchedule(input)
           setShowSchedule(false)
+        } catch {
+          // The host reports the failure; keep this view open.
         } finally {
           setBusy(false)
         }
       }}
       onDismiss={() => setShowSchedule(false)}
-      busy={busy}
+      busy={disabled || busy}
     />
   ) : null