@byline/host-tanstack-start 4.18.0 → 5.0.0

package/src/admin-shell/collections/edit.tsx

@@ -29,28 +29,29 @@ import {
   deleteDocument,
   deleteDocumentLocale,
   duplicateCollectionDocument,
+  hasCommittedDocumentHookFailure,
   hasDeleteSideEffectFailures,
   scheduleCollectionDocumentPublish,
   unpublishDocument,
-  updateCollectionDocumentSystemFields,
   updateCollectionDocumentWithPatches,
   updateDocumentStatus,
 } from '../../server-fns/collections/index.js'
 import { useNavigate } from '../chrome/loose-router.js'
+import { useDocumentMutationState } from '../document-mutation-state.js'
 import { useTanStackNavigationGuard } from './tanstack-navigation-guard.js'
 import { ViewMenu } from './view-menu.js'
 import type { SerializedDocumentPublishSchedule } from '../../server-fns/collections/index.js'
 import type { ContentLocaleOption } from './view-menu.js'
 
 type EditState = {
-  status: 'success' | 'failed' | 'busy' | 'idle'
+  status: 'success' | 'warning' | 'failed' | 'busy' | 'idle'
   message: string
 }
 
 export const EditView = ({
   collectionDefinition,
   adminConfig,
-  initialData,
+  initialData: loadedData,
   locale,
   contentLocales,
   defaultContentLocale,
@@ -65,6 +66,8 @@ export const EditView = ({
   /** URL-encoded list search state to return to on close — see list-return-state.ts. */
   returnSearch?: Record<string, unknown>
 }) => {
+  const mutation = useDocumentMutationState(loadedData)
+  const initialData = mutation.document ?? loadedData
   const toastManager = useToastManager()
   const { t } = useTranslation('byline-admin')
   const [_editState, setEditState] = useState<EditState>({
@@ -110,6 +113,16 @@ export const EditView = ({
     })
   }
 
+  const notifyCommittedHookFailure = () => {
+    const description = t('collections.save.hookFailedDescription')
+    toastManager.add({
+      title: t('collections.save.hookFailedToast'),
+      description,
+      data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+    })
+    setEditState({ status: 'warning', message: description })
+  }
+
   const handleLocaleChange = (newLocale: string) => {
     navigate({
       to: getAdminRoutePath('collections', '$collection', '$id'),
@@ -120,9 +133,16 @@ export const EditView = ({
 
   const handleStatusChange = async (status: string) => {
     try {
-      await updateDocumentStatus({
-        data: { collection: path, id: String(initialData.id), status },
+      mutation.assertWritable()
+      const result = await updateDocumentStatus({
+        data: {
+          expectedRevision: mutation.expectedRevision(),
+          collection: path,
+          id: String(initialData.id),
+          status,
+        },
       })
+      mutation.adopt(result)
       const description = t('collections.edit.statusChangedDescription', { status })
       toastManager.add({
         title: t('collections.edit.statusUpdateTitle', { label: singular }),
@@ -142,9 +162,16 @@ export const EditView = ({
         search: (prev: Record<string, unknown>) => ({ ...prev }),
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       console.error('Status change error:', err)
       const description = t('collections.edit.statusChangeFailedDescription', {
-        message: (err as Error).message,
+        message: t('documentConcurrency.failed'),
       })
       toastManager.add({
         title: t('collections.edit.statusUpdateTitle', { label: singular }),
@@ -170,14 +197,17 @@ export const EditView = ({
 
   const handleSchedulePublication = async ({ publishAt }: { publishAt: string }) => {
     try {
-      await scheduleCollectionDocumentPublish({
+      mutation.assertWritable()
+      const result = await scheduleCollectionDocumentPublish({
         data: {
+          expectedRevision: mutation.expectedRevision(),
           collection: path,
           id: String(initialData.id),
           publishAt,
           expectedVersionId: String(initialData.versionId),
         },
       })
+      mutation.adopt(result)
       toastManager.add({
         title: t('scheduledPublication.toast.scheduledTitle'),
         description: t('scheduledPublication.toast.scheduledDescription'),
@@ -185,9 +215,16 @@ export const EditView = ({
       })
       reloadDocument()
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       toastManager.add({
         title: t('scheduledPublication.toast.failedTitle'),
-        description: (err as Error).message,
+        description: t('documentConcurrency.failed'),
         data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
       })
       throw err
@@ -196,13 +233,16 @@ export const EditView = ({
 
   const handleConfirmScheduledPublication = async () => {
     try {
-      await confirmCollectionDocumentScheduledPublish({
+      mutation.assertWritable()
+      const result = await confirmCollectionDocumentScheduledPublish({
         data: {
+          expectedRevision: mutation.expectedRevision(),
           collection: path,
           id: String(initialData.id),
           expectedVersionId: String(initialData.versionId),
         },
       })
+      mutation.adopt(result)
       toastManager.add({
         title: t('scheduledPublication.toast.confirmedTitle'),
         description: t('scheduledPublication.toast.confirmedDescription'),
@@ -210,9 +250,16 @@ export const EditView = ({
       })
       reloadDocument()
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       toastManager.add({
         title: t('scheduledPublication.toast.failedTitle'),
-        description: (err as Error).message,
+        description: t('documentConcurrency.failed'),
         data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
       })
       throw err
@@ -221,9 +268,15 @@ export const EditView = ({
 
   const handleCancelScheduledPublication = async () => {
     try {
+      mutation.assertWritable()
       const result = await cancelCollectionDocumentScheduledPublish({
-        data: { collection: path, id: String(initialData.id) },
+        data: {
+          expectedRevision: mutation.expectedRevision(),
+          collection: path,
+          id: String(initialData.id),
+        },
       })
+      mutation.adopt({ ...result, documentId: String(initialData.id) })
       const cancelled = result.status === 'cancelled'
       toastManager.add({
         title: cancelled
@@ -241,9 +294,16 @@ export const EditView = ({
       })
       reloadDocument()
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       toastManager.add({
         title: t('scheduledPublication.toast.failedTitle'),
-        description: (err as Error).message,
+        description: t('documentConcurrency.failed'),
         data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
       })
       throw err
@@ -264,7 +324,15 @@ export const EditView = ({
 
   const handleUnpublish = async () => {
     try {
-      await unpublishDocument({ data: { collection: path, id: String(initialData.id) } })
+      mutation.assertWritable()
+      const result = await unpublishDocument({
+        data: {
+          expectedRevision: mutation.expectedRevision(),
+          collection: path,
+          id: String(initialData.id),
+        },
+      })
+      mutation.adopt(result)
       const description = t('collections.edit.unpublishedDescription')
       toastManager.add({
         title: t('collections.edit.unpublishTitle', { label: singular }),
@@ -283,9 +351,16 @@ export const EditView = ({
         search: (prev: Record<string, unknown>) => ({ ...prev }),
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       console.error('Unpublish error:', err)
       const description = t('collections.edit.unpublishFailedDescription', {
-        message: (err as Error).message,
+        message: t('documentConcurrency.failed'),
       })
       toastManager.add({
         title: t('collections.edit.unpublishTitle', { label: singular }),
@@ -303,9 +378,23 @@ export const EditView = ({
 
   const handleDuplicate = async () => {
     try {
+      mutation.assertWritable()
       const result = await duplicateCollectionDocument({
-        data: { collection: path, id: String(initialData.id) },
+        data: {
+          expectedRevision: mutation.expectedRevision(),
+          collection: path,
+          id: String(initialData.id),
+        },
       })
+      if (hasCommittedDocumentHookFailure(result)) {
+        notifyCommittedHookFailure()
+        navigate({
+          to: getAdminRoutePath('collections', '$collection', '$id'),
+          params: { collection: path, id: result.documentId },
+          search: (prev: Record<string, unknown>) => ({ ...prev }),
+        })
+        return
+      }
       const description = result.pathRetried
         ? t('collections.edit.duplicatedAutoPathDescription', { path: result.newPath })
         : t('collections.edit.duplicatedPathDescription', { path: result.newPath })
@@ -332,9 +421,16 @@ export const EditView = ({
         search: (prev: Record<string, unknown>) => ({ ...prev }),
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       console.error('Duplicate error:', err)
       const description = t('collections.edit.duplicateFailedDescription', {
-        message: (err as Error).message,
+        message: t('documentConcurrency.failed'),
       })
       toastManager.add({
         title: t('collections.edit.duplicateTitle', { label: singular }),
@@ -358,8 +454,10 @@ export const EditView = ({
     overwrite: boolean
   }) => {
     try {
+      mutation.assertWritable()
       const result = await copyDocumentToLocale({
         data: {
+          expectedRevision: mutation.expectedRevision(),
           collection: path,
           id: String(initialData.id),
           sourceLocale: locale ?? defaultContentLocale,
@@ -367,6 +465,17 @@ export const EditView = ({
           overwrite,
         },
       })
+      mutation.adopt(result)
+      if (hasCommittedDocumentHookFailure(result)) {
+        notifyCommittedHookFailure()
+        notifyScheduleSuspended()
+        navigate({
+          to: getAdminRoutePath('collections', '$collection', '$id'),
+          params: { collection: path, id: String(initialData.id) },
+          search: (prev: Record<string, unknown>) => ({ ...prev, locale: targetLocale }),
+        })
+        return
+      }
       const sourceLabel =
         contentLocales.find((l) => l.code === result.sourceLocale)?.label ?? result.sourceLocale
       const targetLabel =
@@ -408,9 +517,16 @@ export const EditView = ({
         search: (prev: Record<string, unknown>) => ({ ...prev, locale: targetLocale }),
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       console.error('Copy to locale error:', err)
       const description = t('collections.edit.copyFailedDescription', {
-        message: (err as Error).message,
+        message: t('documentConcurrency.failed'),
       })
       toastManager.add({
         title: t('collections.edit.copyToLocaleTitle', { label: singular }),
@@ -428,13 +544,26 @@ export const EditView = ({
 
   const handleDeleteLocale = async ({ targetLocale }: { targetLocale: string }) => {
     try {
+      mutation.assertWritable()
       const result = await deleteDocumentLocale({
         data: {
+          expectedRevision: mutation.expectedRevision(),
           collection: path,
           id: String(initialData.id),
           locale: targetLocale,
         },
       })
+      mutation.adopt(result)
+      if (hasCommittedDocumentHookFailure(result)) {
+        notifyCommittedHookFailure()
+        notifyScheduleSuspended()
+        navigate({
+          to: getAdminRoutePath('collections', '$collection', '$id'),
+          params: { collection: path, id: String(initialData.id) },
+          search: (prev: Record<string, unknown>) => ({ ...prev, locale: defaultContentLocale }),
+        })
+        return
+      }
       const targetLabel =
         contentLocales.find((l) => l.code === result.locale)?.label ?? result.locale
       const description = t('collections.edit.deletedLocaleDescription', {
@@ -461,9 +590,16 @@ export const EditView = ({
         search: (prev: Record<string, unknown>) => ({ ...prev, locale: defaultContentLocale }),
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       console.error('Delete locale error:', err)
       const description = t('collections.edit.deleteLocaleFailedDescription', {
-        message: (err as Error).message,
+        message: t('documentConcurrency.failed'),
       })
       toastManager.add({
         title: t('collections.edit.deleteLocaleTitle', { label: singular }),
@@ -481,9 +617,28 @@ export const EditView = ({
 
   const handleDelete = async () => {
     try {
+      mutation.assertWritable()
       const result = await deleteDocument({
-        data: { collection: path, id: String(initialData.id) },
+        data: {
+          expectedRevision: mutation.expectedRevision(),
+          collection: path,
+          id: String(initialData.id),
+        },
       })
+      if (result.scheduledPublicationsNeedReconfirmation) {
+        toastManager.add({
+          title: t('documentConcurrency.schedulesTitle'),
+          description: (
+            <>
+              <p>{t('documentConcurrency.schedules')}</p>
+              <a href={getAdminRoutePath('scheduled-publications')}>
+                {t('documentConcurrency.reviewSchedules')}
+              </a>
+            </>
+          ),
+          data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+        })
+      }
       const hasSideEffectFailures = hasDeleteSideEffectFailures(result)
       const description = hasSideEffectFailures
         ? t('collections.edit.deletedWithWarningsDescription', { label: singular })
@@ -498,7 +653,10 @@ export const EditView = ({
           close: true,
         },
       })
-      setEditState({ status: 'success', message: description })
+      setEditState({
+        status: hasSideEffectFailures ? 'warning' : 'success',
+        message: description,
+      })
       // Navigate back to the collection list after deletion. The return
       // target has now been consumed — clear the stored fallback so a later
       // visit doesn't resurrect a stale list position.
@@ -509,9 +667,16 @@ export const EditView = ({
         search: returnSearch,
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       console.error('Delete error:', err)
       const description = t('collections.edit.deleteFailedDescription', {
-        message: (err as Error).message,
+        message: t('documentConcurrency.failed'),
       })
       toastManager.add({
         title: t('collections.edit.deleteTitle', { label: singular }),
@@ -550,65 +715,65 @@ export const EditView = ({
     systemAvailableLocales?: string[]
   }) => {
     try {
-      // Document-grain system fields write first via their own non-versioned
-      // path — so a path conflict surfaces before we mint a content version,
-      // and these immediate writes never reset workflow status. See
-      // docs/08-internationalization/index.md.
-      if (pathDirty || availableLocalesDirty) {
-        await updateCollectionDocumentSystemFields({
-          data: {
-            collection: path,
-            id: String(initialData.id),
-            locale,
-            ...(pathDirty ? { path: systemPath ?? null } : {}),
-            ...(availableLocalesDirty ? { availableLocales: systemAvailableLocales ?? [] } : {}),
-          },
-        })
-      }
-
-      // Content (field data / patches) follows the normal versioned path —
-      // mints a new draft version. Skipped entirely when only the system
-      // fields changed, so a path/advertising edit never creates an empty
-      // content version.
-      if (contentDirty) {
-        await updateCollectionDocumentWithPatches({
-          data: {
-            collection: path,
-            id: String(initialData.id),
-            patches,
-            versionId: initialData.versionId as string | undefined,
-            locale,
-          },
-        })
-      }
-
-      if (contentDirty && scheduledPublication?.state === 'armed') {
+      mutation.assertWritable()
+      const result = await updateCollectionDocumentWithPatches({
+        data: {
+          collection: path,
+          id: String(initialData.id),
+          expectedRevision: mutation.expectedRevision(),
+          patches: contentDirty ? patches : [],
+          locale,
+          ...(pathDirty ? { path: systemPath ?? null } : {}),
+          ...(availableLocalesDirty ? { availableLocales: systemAvailableLocales ?? [] } : {}),
+        },
+      })
+      mutation.adopt(result)
+      const hookFailed = hasCommittedDocumentHookFailure(result)
+      if (
+        (contentDirty || pathDirty || availableLocalesDirty) &&
+        scheduledPublication?.state === 'armed'
+      ) {
         notifyScheduleSuspended()
       }
 
-      const description = t('collections.edit.updatedDescription', { label: singularLower })
+      const description = hookFailed
+        ? t('collections.save.hookFailedDescription')
+        : t('collections.edit.updatedDescription', { label: singularLower })
       toastManager.add({
-        title: t('collections.edit.updateTitle', { label: singular }),
+        title: hookFailed
+          ? t('collections.save.hookFailedToast')
+          : t('collections.edit.updateTitle', { label: singular }),
         description,
         data: {
-          intent: 'success',
-          iconType: 'success',
+          intent: hookFailed ? 'warning' : 'success',
+          iconType: hookFailed ? 'warning' : 'success',
           icon: true,
           close: true,
         },
       })
 
-      setEditState({ status: 'success', message: description })
+      setEditState({ status: hookFailed ? 'warning' : 'success', message: description })
 
       // Re-navigate to the same route so the loader re-fetches the document.
-      // The new version will have a fresh version ID, draft status, and
-      // updated publishedVersion metadata.
+      // The new version will have a fresh version ID, the collection's default
+      // workflow status, and updated publishedVersion metadata.
       navigate({
         to: getAdminRoutePath('collections', '$collection', '$id'),
         params: { collection: path, id: String(initialData.id) },
         search: (prev: Record<string, unknown>) => ({ ...prev }),
+        // Every write above has succeeded. FormRenderer clears its dirty
+        // baseline after this handler returns, so bypass the guard during the
+        // intentional post-save refresh rather than racing that state update.
+        ignoreBlocker: true,
       })
     } catch (err) {
+      const handled = mutation.report(err)
+      if (handled === 'blocked') throw err
+      if (handled === 'committed') {
+        notifyCommittedHookFailure()
+        reloadDocument()
+        return
+      }
       console.error('Network error:', err)
       const description = t('collections.edit.updateFailedDescription', { label: singularLower })
       toastManager.add({
@@ -634,6 +799,13 @@ export const EditView = ({
     <Section>
       <Container>
         <FormRenderer
+          mutationIssue={mutation.issue}
+          mutationsBlocked={mutation.blocked}
+          observedRevision={mutation.revision}
+          onMutationError={mutation.report}
+          onTreeMutationCommitted={mutation.adopt}
+          scheduledPublicationsNeedReconfirmation={mutation.scheduleNotice}
+          scheduledPublicationsHref={getAdminRoutePath('scheduled-publications')}
           mode="edit"
           fields={fields}
           onSubmit={handleSubmit}

package/src/admin-shell/collections/history.tsx

@@ -155,6 +155,7 @@ export const HistoryView = ({
       currentVersionId,
       restoreStatusLabel,
       openCompare,
+      mutationsBlocked,
       openRestore,
     }) =>
       columns.flatMap((column) => {
@@ -213,6 +214,7 @@ export const HistoryView = ({
                     variant="outlined"
                     size="xs"
                     intent="noeffect"
+                    disabled={mutationsBlocked}
                     onClick={openRestore}
                     className={cx('byline-coll-history-restore-button', styles.restoreButton)}
                     title={t('collections.history.restoreButtonTitle', {
@@ -279,8 +281,15 @@ export const HistoryView = ({
               rowPresentation={rowPresentation}
               loadHistoricalVersion={getCollectionDocumentVersion}
               onPageSizeChange={handlePageSizeChange}
-              restoreVersion={(versionId) =>
-                restoreDocumentVersion({ data: { collection, id, versionId } })
+              restoreVersion={(versionId, expectedRevision) =>
+                restoreDocumentVersion({
+                  data: {
+                    expectedRevision,
+                    collection,
+                    id,
+                    versionId,
+                  },
+                })
               }
               onRestoreComplete={async () => {
                 await router.invalidate()

package/src/admin-shell/collections/list.tsx

@@ -1,3 +1,5 @@
+import { DocumentMutationNotice } from '../document-mutation-notice.js'
+import { useDocumentMutationState } from '../document-mutation-state.js'
 /**
  * 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
@@ -178,6 +180,7 @@ export const ListView = ({
   const navigate = useNavigate()
   const router = useRouter()
   const toastManager = useToastManager()
+  const mutation = useDocumentMutationState(undefined)
   const { t } = useTranslation('byline-admin')
   const location = useRouterState({ select: (s) => s.location })
 
@@ -191,10 +194,10 @@ export const ListView = ({
   const [localDocs, setLocalDocs] = useState(data.docs)
   const [isReordering, setIsReordering] = useState(false)
   useEffect(() => {
-    if (!isReordering) {
+    if (!isReordering && !mutation.blocked) {
       setLocalDocs(data.docs)
     }
-  }, [data.docs, isReordering])
+  }, [data.docs, isReordering, mutation.blocked])
 
   // Drag is only meaningful in the canonical view: the default order_key
   // sort, no search, no status filter. Otherwise the visible order isn't
@@ -209,7 +212,7 @@ export const ListView = ({
   }
   const isCanonicalView =
     !searchParams.order && !searchParams.desc && !searchParams.query && !searchParams.status
-  const dragEnabled = orderable && isCanonicalView && !!onReorder
+  const dragEnabled = orderable && isCanonicalView && !!onReorder && !mutation.blocked
 
   // The *effective* sort for the header indicators: explicit URL params win;
   // otherwise the server echoes a configured `defaultSort` (admin config)
@@ -226,7 +229,7 @@ export const ListView = ({
 
   const handleDragEnd = async (event: DragEndEvent) => {
     const { active, over } = event
-    if (!over || active.id === over.id || !onReorder) return
+    if (mutation.blocked || isReordering || !over || active.id === over.id || !onReorder) return
     const oldIndex = localDocs.findIndex((d) => d.id === active.id)
     const newIndex = localDocs.findIndex((d) => d.id === over.id)
     if (oldIndex < 0 || newIndex < 0 || oldIndex === newIndex) return
@@ -242,14 +245,26 @@ export const ListView = ({
     const before = next[newIndex - 1]?.id ?? null
     const after = next[newIndex + 1]?.id ?? null
     try {
-      await onReorder({
+      mutation.assertWritable()
+      const receipt = await onReorder({
         documentId: String(active.id),
         beforeDocumentId: before,
         afterDocumentId: after,
       })
-      await router.invalidate()
+      mutation.reportStructure(receipt)
+      try {
+        await router.invalidate()
+      } catch {
+        // The mutation committed; a failed refresh must not undo its UI receipt.
+        toastManager.add({
+          title: t('collections.list.treeRefreshFailedToast'),
+          description: t('collections.list.treeRefreshFailedDescription'),
+          data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+        })
+      }
     } catch (_err) {
       setLocalDocs(previousDocs)
+      if (mutation.report(_err)) return
       toastManager.add({
         title: t('collections.list.reorderFailedToast'),
         description: t('collections.list.reorderFailedDescription'),
@@ -359,6 +374,7 @@ export const ListView = ({
   return (
     <Section>
       <Container>
+        <DocumentMutationNotice issue={mutation.issue} scheduleNotice={mutation.scheduleNotice} />
         <div className={cx('byline-coll-list-head', styles.head)}>
           <h1 className={cx('byline-coll-list-title', styles.title)}>
             {data.included.collection.labels.plural as string}