@byline/host-tanstack-start 4.18.0 → 5.0.0

package/src/admin-shell/collections/version-history.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
@@ -55,6 +57,7 @@ interface VersionHistoryRowContext {
   actionLabel: string
   restoreStatusLabel: string
   openCompare: () => void
+  mutationsBlocked: boolean
   openRestore: () => void
 }
 
@@ -126,9 +129,10 @@ export function VersionHistoryCore({
   rowPresentation: VersionHistoryRowPresentation
   loadHistoricalVersion: HistoricalVersionLoader
   onPageSizeChange: (pageSize: number) => void
-  restoreVersion: (versionId: string) => Promise<unknown>
+  restoreVersion: (versionId: string, expectedRevision: number) => Promise<unknown>
   onRestoreComplete: () => void | Promise<void>
 }) {
+  const mutation = useDocumentMutationState(currentDocument)
   const { t } = useTranslation('byline-admin')
   const [selectedVersion, setSelectedVersion] = useState<{
     versionId: string
@@ -150,6 +154,7 @@ export function VersionHistoryCore({
 
   return (
     <>
+      <DocumentMutationNotice issue={mutation.issue} />
       <div className={cx('byline-coll-history-options', styles.options)}>
         <RouterPager
           page={data.meta.page}
@@ -195,7 +200,7 @@ export function VersionHistoryCore({
                 setSelectedVersion({ versionId, label: versionLabel })
               }
               const openRestore = () => {
-                if (versionId == null || versionId === currentVersionId) return
+                if (mutation.blocked || versionId == null || versionId === currentVersionId) return
                 setRestoreTarget({ versionId, label: versionLabel, versionNumber })
               }
 
@@ -228,6 +233,7 @@ export function VersionHistoryCore({
                       actionLabel,
                       restoreStatusLabel,
                       openCompare,
+                      mutationsBlocked: mutation.blocked,
                       openRestore,
                     })}
                   </Table.Row>
@@ -334,11 +340,15 @@ export function VersionHistoryCore({
           </Modal.Header>
           {restoreTarget ? (
             <RestoreVersionModal
+              disabled={mutation.blocked}
+              onMutationError={mutation.report}
               versionLabel={restoreTarget.label}
               versionNumber={restoreTarget.versionNumber}
               restoreStatusLabel={restoreStatusLabel}
               onClose={() => setRestoreTarget(null)}
-              restoreVersion={() => restoreVersion(restoreTarget.versionId)}
+              restoreVersion={() =>
+                restoreVersion(restoreTarget.versionId, mutation.expectedRevision())
+              }
               onRestoreComplete={onRestoreComplete}
             />
           ) : null}

package/src/admin-shell/document-mutation-notice.tsx

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from 'react'
+
+import { useTranslation } from '@byline/i18n/react'
+import { Alert, Button } from '@byline/ui/react'
+
+import { getAdminRoutePath } from '../routes/admin-path.js'
+import type { DocumentMutationIssue } from './document-mutation-state.js'
+
+/** Persistent recovery for list, history and schedule views without local form drafts. */
+export function DocumentMutationNotice({
+  issue,
+  scheduleNotice = false,
+}: {
+  issue: DocumentMutationIssue | null
+  scheduleNotice?: boolean
+}) {
+  const { t } = useTranslation('byline-admin')
+  const warning = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    if (issue) warning.current?.focus()
+  }, [issue])
+  if (!issue && !scheduleNotice) return null
+  return (
+    <div ref={warning} tabIndex={-1} role="alert" aria-live="assertive">
+      {issue && (
+        <Alert close={false} intent="warning" title={t(`documentConcurrency.${issue}Title`)}>
+          <p>{t(`documentConcurrency.${issue}`)}</p>
+          {issue !== 'committed' && (
+            <Button type="button" onClick={() => window.location.reload()}>
+              {t('documentConcurrency.reloadAction')}
+            </Button>
+          )}
+        </Alert>
+      )}
+      {scheduleNotice && (
+        <Alert close={false} intent="warning" title={t('documentConcurrency.schedulesTitle')}>
+          <p>{t('documentConcurrency.schedules')}</p>
+          <a href={getAdminRoutePath('scheduled-publications')}>
+            {t('documentConcurrency.reviewSchedules')}
+          </a>
+        </Alert>
+      )}
+    </div>
+  )
+}

package/src/admin-shell/document-mutation-state.test.tsx

@@ -0,0 +1,146 @@
+import { act } from 'react'
+
+import {
+  ERR_DOCUMENT_HOOK_COMMITTED,
+  ERR_DOCUMENT_STALE,
+  ERR_LOCK_CONFLICT,
+  ERR_VALIDATION,
+} from '@byline/core'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { useDocumentMutationState } from './document-mutation-state.js'
+
+type Observation = { id: string; versionId: string; revision?: number; fields: { title: string } }
+let state: ReturnType<typeof useDocumentMutationState<Observation>>
+let root: Root
+let container: HTMLDivElement
+function Probe({ observation }: { observation: Observation | null }) {
+  state = useDocumentMutationState(observation)
+  return null
+}
+const original: Observation = {
+  id: 'doc',
+  versionId: 'v1',
+  revision: 7,
+  fields: { title: 'Opened' },
+}
+const render = (observation: Observation | null) =>
+  act(() => root.render(<Probe observation={observation} />))
+beforeEach(() => {
+  Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true })
+  container = document.createElement('div')
+  root = createRoot(container)
+  render(original)
+})
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  Reflect.deleteProperty(globalThis, 'IS_REACT_ACT_ENVIRONMENT')
+})
+const stale = ERR_DOCUMENT_STALE({
+  message: 'Test failure',
+  details: {
+    reason: 'revision_mismatch',
+    documentId: 'doc',
+    expectedRevision: 7,
+    currentRevision: 8,
+  },
+})
+
+describe('editor observation ownership', () => {
+  it('does not attach a background metadata revision to the opened fields', () => {
+    render({ ...original, revision: 8 })
+    expect(state.document).toBe(original)
+    expect(state.expectedRevision()).toBe(7)
+  })
+  it('adopts its own structural receipt without discarding fields and surfaces schedule suspension', () => {
+    act(() =>
+      state.adopt({ documentId: 'doc', revision: 8, scheduledPublicationsNeedReconfirmation: true })
+    )
+    expect(state.document).toBe(original)
+    expect(state.expectedRevision()).toBe(8)
+    expect(state.scheduleNotice).toBe(true)
+    const refreshed = { ...original, revision: 8 }
+    render(refreshed)
+    expect(state.document).toBe(refreshed)
+  })
+  it.each([
+    ['stale', stale],
+    [
+      'reload',
+      ERR_VALIDATION({ message: 'Test failure', details: { reason: 'missing_document_revision' } }),
+    ],
+    [
+      'lock',
+      ERR_LOCK_CONFLICT({
+        message: 'Test failure',
+        details: { reason: 'lock_conflict', rolledBack: true, retryable: true },
+      }),
+    ],
+    ['unavailable', { code: 'ERR_NOT_FOUND' }],
+  ])(
+    'blocks every later call after %s without adopting fresh data or a late receipt',
+    (issue, error) => {
+      act(() => {
+        expect(state.report(error)).toBe('blocked')
+      })
+      render({ ...original, revision: 9 })
+      act(() => state.adopt({ documentId: 'doc', revision: 8 }))
+      expect(state.issue).toBe(issue)
+      expect(state.blocked).toBe(true)
+      expect(state.document).toBe(original)
+      expect(state.revision).toBe(7)
+      expect(() => state.assertWritable()).toThrow()
+      expect(() => state.expectedRevision()).toThrow()
+    }
+  )
+  it('keeps a rejected empty singleton empty until a new editor session', () => {
+    act(() => root.unmount())
+    root = createRoot(container)
+    render(null)
+    const error = ERR_DOCUMENT_STALE({
+      message: 'Test failure',
+      details: {
+        reason: 'singleton_slot_changed',
+        singletonPath: 'settings',
+        expectedState: 'empty',
+        currentState: 'document',
+      },
+    })
+    act(() => {
+      state.report(error)
+    })
+    render(original)
+    expect(state.document).toBeNull()
+    expect(state.blocked).toBe(true)
+  })
+  it('keeps committed hook failures distinct and advances only to the committed revision', () => {
+    const error = ERR_DOCUMENT_HOOK_COMMITTED({
+      message: 'Test failure',
+      details: {
+        phase: 'afterUpdate',
+        documentId: 'doc',
+        documentVersionId: 'v2',
+        revision: 8,
+        sideEffectCode: 'ERR_UNHANDLED',
+      },
+    })
+    act(() => {
+      expect(state.report(error)).toBe('committed')
+    })
+    expect(state.issue).toBe('committed')
+    expect(state.blocked).toBe(false)
+    expect(state.expectedRevision()).toBe(8)
+  })
+  it('does not classify arbitrary conflicts or uncertain driver failures as safe rollback', () => {
+    for (const error of [
+      { code: 'ERR_CONFLICT' },
+      new Error('deadlock SQL secret'),
+      { code: 'ECONNRESET' },
+    ]) {
+      expect(state.report(error)).toBeNull()
+    }
+    expect(state.blocked).toBe(false)
+  })
+})

package/src/admin-shell/document-mutation-state.ts

@@ -0,0 +1,95 @@
+import { useRef, useState } from 'react'
+
+import {
+  ErrorCodes,
+  getDocumentRevisionValidationDetails,
+  getDocumentStaleDetails,
+  getLockConflictDetails,
+  parseDocumentRevision,
+} from '@byline/core'
+import { getDocumentHookCommittedDetails } from '@byline/core/services'
+
+import { committedTreeReceipt, structuralReceipt } from '../server-fns/structural-receipt.js'
+
+export type DocumentMutationIssue = 'stale' | 'reload' | 'lock' | 'unavailable' | 'committed'
+
+function documentMutationIssue(error: unknown): DocumentMutationIssue | null {
+  if (getDocumentStaleDetails(error)) return 'stale'
+  if (getDocumentRevisionValidationDetails(error)) return 'reload'
+  if (getLockConflictDetails(error)) return 'lock'
+  if (getDocumentHookCommittedDetails(error) || committedTreeReceipt(error)) return 'committed'
+  if (
+    typeof error === 'object' &&
+    error !== null &&
+    Reflect.get(error, 'code') === ErrorCodes.NOT_FOUND
+  )
+    return 'unavailable'
+  return null
+}
+
+/** A rejected observation stays frozen until an explicit editor reload. */
+export function useDocumentMutationState<
+  T extends { id?: unknown; versionId?: unknown; revision?: unknown },
+>(document: T | null | undefined) {
+  const [issue, setIssue] = useState<DocumentMutationIssue | null>(null)
+  const [scheduleNotice, setScheduleNotice] = useState(false)
+  const [, setReceiptRevision] = useState<number | undefined>()
+  const blockedError = useRef<unknown>(undefined)
+  const observation = useRef({ identity: document, revision: document?.revision })
+  if (
+    observation.current.identity !== document &&
+    blockedError.current === undefined &&
+    document?.revision === observation.current.revision
+  ) {
+    observation.current = { identity: document, revision: document?.revision }
+  }
+  const assertWritable = () => {
+    if (blockedError.current !== undefined) throw blockedError.current
+  }
+  const expectedRevision = () => {
+    assertWritable()
+    return parseDocumentRevision(observation.current.revision)
+  }
+  const adopt = (receipt: {
+    documentId: string
+    revision: number
+    scheduledPublicationsNeedReconfirmation?: boolean
+  }) => {
+    if (blockedError.current !== undefined) return
+    if (document?.id != null && receipt.documentId !== document.id) return
+    observation.current.revision = parseDocumentRevision(receipt.revision)
+    setReceiptRevision(receipt.revision)
+    if (receipt.scheduledPublicationsNeedReconfirmation) setScheduleNotice(true)
+  }
+  const reportStructure = (result: unknown) => {
+    const receipt = structuralReceipt(result)
+    if (receipt) adopt(receipt)
+  }
+  const report = (error: unknown): 'blocked' | 'committed' | null => {
+    const kind = documentMutationIssue(error)
+    if (kind === null) return null
+    if (kind === 'committed') {
+      if (blockedError.current !== undefined) return 'blocked'
+      const details = getDocumentHookCommittedDetails(error) ?? committedTreeReceipt(error)
+      if (details) adopt(details)
+      setIssue(kind)
+      return 'committed'
+    }
+    blockedError.current = error
+    setIssue(kind)
+    return 'blocked'
+  }
+  return {
+    issue,
+    blocked: issue !== null && issue !== 'committed',
+    scheduleNotice,
+    document: observation.current.identity,
+    revision:
+      typeof observation.current.revision === 'number' ? observation.current.revision : undefined,
+    expectedRevision,
+    assertWritable,
+    adopt,
+    report,
+    reportStructure,
+  }
+}

package/src/admin-shell/scheduled-publications/list.tsx

@@ -1,4 +1,7 @@
-'use client'
+import { DocumentMutationNotice } from '../document-mutation-notice.js'
+import { useDocumentMutationState } from '../document-mutation-state.js'
+
+;('use client')
 
 /**
  * This Source Code is subject to the terms of the Mozilla Public
@@ -60,6 +63,7 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
     state?: 'armed' | 'needs_reconfirm'
     page?: number
   }
+  const mutation = useDocumentMutationState(undefined)
   const [cancelling, setCancelling] = useState<string | null>(null)
 
   const applySearch = (patch: Record<string, unknown>) => {
@@ -69,11 +73,13 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
     })
   }
 
-  const cancel = async (collection: string, documentId: string) => {
+  const cancel = async (collection: string, documentId: string, expectedRevision: number) => {
+    if (mutation.blocked || cancelling) return
     setCancelling(documentId)
     try {
+      mutation.assertWritable()
       const result = await cancelCollectionDocumentScheduledPublish({
-        data: { collection, id: documentId },
+        data: { collection, id: documentId, expectedRevision },
       })
       const cancelled = result.status === 'cancelled'
       toastManager.add({
@@ -95,9 +101,10 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
         search: location.search as Record<string, unknown>,
       })
     } catch (error) {
+      if (mutation.report(error)) return
       toastManager.add({
         title: t('scheduledPublication.toast.failedTitle'),
-        description: (error as Error).message,
+        description: t('documentConcurrency.failed'),
         data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
       })
     } finally {
@@ -110,6 +117,7 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
   return (
     <Section>
       <Container>
+        <DocumentMutationNotice issue={mutation.issue} />
         <div className={cx('byline-scheduled-list-head', styles.head)}>
           <h1 className={styles.title}>{t('scheduledPublication.list.title')}</h1>
           <p className={styles.intro}>{t('scheduledPublication.list.intro')}</p>
@@ -257,13 +265,15 @@ export function ScheduledPublicationsView({ data }: { data: ScheduledPublication
                           size="xs"
                           type="button"
                           intent="danger"
-                          disabled={cancelling === schedule.documentId}
+                          disabled={mutation.blocked || cancelling !== null}
                           // The column header already says Actions and the row
                           // is a schedule, so the short label carries here —
                           // unlike the editor's menu, where "Cancel schedule"
                           // has to distinguish itself from cancelling an edit.
                           aria-label={t('scheduledPublication.actions.cancel')}
-                          onClick={() => cancel(schedule.collectionPath, schedule.documentId)}
+                          onClick={() =>
+                            cancel(schedule.collectionPath, schedule.documentId, schedule.revision)
+                          }
                         >
                           {t('common.actions.cancel')}
                         </Button>

package/src/admin-shell/singletons/history.test.tsx

@@ -21,6 +21,7 @@ const mocks = vi.hoisted(() => ({
   findSingletonByVersion: vi.fn(async () => ({})),
   pagerProps: [] as Array<{ componentName: string; page: number; count: number }>,
   diffModalProps: [] as Array<Record<string, unknown>>,
+  toast: vi.fn(),
   location: {
     pathname: '/admin/singletons/site-settings/history',
     search: {} as Record<string, unknown>,
@@ -103,6 +104,7 @@ vi.mock('@byline/ui/react', () => {
     Section: Div,
     Select: () => <select aria-label="page size" />,
     Table,
+    useToastManager: () => ({ add: mocks.toast }),
   }
 })
 
@@ -192,6 +194,7 @@ const data: VersionHistoryData = {
 }
 
 const currentDocument = {
+  revision: 7,
   id: 'document-settings',
   versionId: 'version-current',
   status: 'published',
@@ -264,7 +267,7 @@ describe('singleton version history', () => {
     await act(async () => confirm?.click())
 
     expect(mocks.restoreSingleton).toHaveBeenCalledWith({
-      data: { singleton: 'site-settings', versionId: 'version-old' },
+      data: { singleton: 'site-settings', versionId: 'version-old', expectedRevision: 7 },
     })
     expect(mocks.invalidate).toHaveBeenCalledTimes(1)
     expect(mocks.navigate).toHaveBeenLastCalledWith({
@@ -393,6 +396,7 @@ describe('singleton version history', () => {
 
     expect(mocks.restoreCollection).toHaveBeenCalledWith({
       data: {
+        expectedRevision: 7,
         collection: 'articles',
         id: 'document-article',
         versionId: 'version-old',
@@ -404,4 +408,45 @@ describe('singleton version history', () => {
     })
     dispose()
   })
+
+  it('closes and refreshes after a restore whose afterSave hook failed post-commit', async () => {
+    mocks.restoreSingleton.mockResolvedValueOnce({
+      status: 'committed-hook-failed',
+      documentId: 'document-settings',
+      documentVersionId: 'version-restored',
+      sideEffectFailure: { phase: 'afterSave', code: 'ERR_UNHANDLED' },
+    })
+    render(
+      <SingletonHistoryView
+        singletonDefinition={singletonDefinition}
+        data={data}
+        currentDocument={currentDocument}
+        contentLocales={[]}
+        defaultContentLocale="en"
+        workflowStatuses={[]}
+      />
+    )
+
+    const restore = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent === 'Restore'
+    )
+    await act(async () => restore?.click())
+    const confirm = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent === 'Restore as Published'
+    )
+    await act(async () => confirm?.click())
+
+    expect(mocks.toast).toHaveBeenCalledWith({
+      title: 'collections.save.hookFailedToast',
+      description: 'collections.save.hookFailedDescription',
+      data: { intent: 'warning', iconType: 'warning', icon: true, close: true },
+    })
+    expect(mocks.invalidate).toHaveBeenCalledOnce()
+    expect(mocks.navigate).toHaveBeenLastCalledWith({
+      to: '/admin/singletons/$singleton',
+      params: { singleton: 'site-settings' },
+      search: {},
+    })
+    dispose()
+  })
 })

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

@@ -89,6 +89,7 @@ export function SingletonHistoryView({
       currentVersionId,
       actorLabel,
       restoreStatusLabel,
+      mutationsBlocked,
       openRestore,
     }) => (
       <>
@@ -106,6 +107,7 @@ export function SingletonHistoryView({
               variant="outlined"
               size="xs"
               intent="noeffect"
+              disabled={mutationsBlocked}
               onClick={openRestore}
               className={cx('byline-coll-history-restore-button', historyStyles.restoreButton)}
               title={t('collections.history.restoreButtonTitle', {
@@ -166,8 +168,14 @@ export function SingletonHistoryView({
               return historical as unknown as Record<string, unknown>
             }}
             onPageSizeChange={handlePageSizeChange}
-            restoreVersion={(versionId) =>
-              restoreSingletonVersion({ data: { singleton, versionId } })
+            restoreVersion={(versionId, expectedRevision) =>
+              restoreSingletonVersion({
+                data: {
+                  expectedRevision,
+                  singleton,
+                  versionId,
+                },
+              })
             }
             onRestoreComplete={async () => {
               await router.invalidate()