@byline/host-tanstack-start 4.19.0 → 5.0.0

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

@@ -33,11 +33,11 @@ import {
   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'
@@ -51,7 +51,7 @@ type EditState = {
 export const EditView = ({
   collectionDefinition,
   adminConfig,
-  initialData,
+  initialData: loadedData,
   locale,
   contentLocales,
   defaultContentLocale,
@@ -66,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>({
@@ -131,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 }),
@@ -153,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 }),
@@ -181,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'),
@@ -196,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
@@ -207,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'),
@@ -221,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
@@ -232,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
@@ -252,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
@@ -275,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 }),
@@ -294,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 }),
@@ -314,8 +378,13 @@ 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()
@@ -352,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 }),
@@ -378,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,
@@ -387,6 +465,7 @@ export const EditView = ({
           overwrite,
         },
       })
+      mutation.adopt(result)
       if (hasCommittedDocumentHookFailure(result)) {
         notifyCommittedHookFailure()
         notifyScheduleSuspended()
@@ -438,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 }),
@@ -458,13 +544,16 @@ 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()
@@ -501,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 }),
@@ -521,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 })
@@ -552,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 }),
@@ -593,41 +715,24 @@ export const EditView = ({
     systemAvailableLocales?: string[]
   }) => {
     try {
-      let hookFailed = false
-      // 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) {
-        const result = await updateCollectionDocumentWithPatches({
-          data: {
-            collection: path,
-            id: String(initialData.id),
-            patches,
-            versionId: initialData.versionId as string | undefined,
-            locale,
-          },
-        })
-        hookFailed = hasCommittedDocumentHookFailure(result)
-      }
-
-      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()
       }
 
@@ -662,6 +767,13 @@ export const EditView = ({
         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({
@@ -687,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}

package/src/admin-shell/collections/restore-version-modal.tsx

@@ -26,6 +26,8 @@ import { hasCommittedDocumentHookFailure } from '../../server-fns/collections/sa
 import styles from './restore-version-modal.module.css'
 
 interface RestoreVersionModalProps {
+  disabled?: boolean
+  onMutationError?: (error: unknown) => unknown
   versionLabel: string
   versionNumber: number
   restoreStatusLabel: string
@@ -35,6 +37,8 @@ interface RestoreVersionModalProps {
 }
 
 export function RestoreVersionModal({
+  disabled = false,
+  onMutationError,
   versionLabel,
   versionNumber,
   restoreStatusLabel,
@@ -48,7 +52,7 @@ export function RestoreVersionModal({
   const [pending, setPending] = useState(false)
 
   async function handleRestore() {
-    if (pending) return
+    if (pending || disabled) return
     setPending(true)
     setError(null)
     try {
@@ -63,6 +67,11 @@ export function RestoreVersionModal({
       onClose()
       await onRestoreComplete()
     } catch (err) {
+      if (onMutationError?.(err)) {
+        setPending(false)
+        onClose()
+        return
+      }
       const code = getErrorCode(err)
       if (code === 'ERR_INVALID_TRANSITION') {
         setError(t('collections.restore.errors.alreadyCurrent'))
@@ -113,7 +122,7 @@ export function RestoreVersionModal({
           intent="noeffect"
           size="sm"
           onClick={onClose}
-          disabled={pending}
+          disabled={pending || disabled}
           className={cx('byline-coll-restore-button', styles.button)}
         >
           {t('common.actions.cancel')}
@@ -123,7 +132,7 @@ export function RestoreVersionModal({
           intent="primary"
           onClick={handleRestore}
           style={{ minWidth: '80px' }}
-          disabled={pending}
+          disabled={pending || disabled}
           className={cx('byline-coll-restore-button', styles.button)}
         >
           {pending === true ? (