@byline/host-tanstack-start 4.16.0 → 4.17.0

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

@@ -0,0 +1,407 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import type React from 'react'
+import { act } from 'react'
+
+import type { MultiCollectionDefinition, SingletonDefinition } from '@byline/core'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterAll, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({
+  navigate: vi.fn(),
+  invalidate: vi.fn(async () => {}),
+  restoreSingleton: vi.fn(async () => ({})),
+  restoreCollection: vi.fn(async () => ({})),
+  findSingletonByVersion: vi.fn(async () => ({})),
+  pagerProps: [] as Array<{ componentName: string; page: number; count: number }>,
+  diffModalProps: [] as Array<Record<string, unknown>>,
+  location: {
+    pathname: '/admin/singletons/site-settings/history',
+    search: {} as Record<string, unknown>,
+  },
+}))
+
+vi.mock('@tanstack/react-router', () => ({
+  useRouter: () => ({ invalidate: mocks.invalidate }),
+  useRouterState: ({ select }: { select: (state: unknown) => unknown }) =>
+    select({ location: mocks.location }),
+  useParams: () => ({ collection: 'articles', id: 'document-article' }),
+}))
+
+vi.mock('@byline/admin/react', () => ({
+  AdminTabs: ({ tabs }: { tabs: Array<{ name: string; label: string }> }) => (
+    <div data-testid="admin-tabs">
+      {tabs.map((tab) => (
+        <span key={tab.name}>{tab.label}</span>
+      ))}
+    </div>
+  ),
+  renderFormatted: (value: unknown) => String(value ?? ''),
+  StatusBadge: ({ status }: { status: string }) => <span>{status}</span>,
+  DiffModal: (props: Record<string, unknown>) => {
+    mocks.diffModalProps.push(props)
+    return <div data-testid="diff-modal" />
+  },
+}))
+
+vi.mock('@byline/admin/services', () => ({
+  useBylineAdminServices: () => ({
+    getCollectionDocumentVersion: vi.fn(async () => ({})),
+  }),
+}))
+
+vi.mock('@byline/i18n/react', () => ({
+  useTranslation: () => ({
+    t: (key: string, values?: Record<string, string | number>) => {
+      if (key === 'collections.history.restoreButton') return 'Restore'
+      if (key === 'collections.history.restoreButtonTitle')
+        return `Restore this version as ${values?.status}`
+      if (key === 'collections.restore.warning') return `New version status: ${values?.status}`
+      if (key === 'collections.restore.confirmButton') return `Restore as ${values?.status}`
+      if (key === 'collections.history.title') return `${values?.label} History`
+      if (key === 'collections.history.audit.createdBy') return `by ${values?.label}`
+      return key
+    },
+  }),
+}))
+
+vi.mock('@byline/ui/react', () => {
+  type Props = React.HTMLAttributes<HTMLElement> & { children?: React.ReactNode }
+  const Div = ({ children, ...props }: Props) => <div {...props}>{children}</div>
+  const Button = ({ children, ...props }: React.ButtonHTMLAttributes<HTMLButtonElement>) => (
+    <button {...props}>{children}</button>
+  )
+  const Modal = ({ isOpen, children }: { isOpen: boolean; children?: React.ReactNode }) =>
+    isOpen ? <div data-testid="modal">{children}</div> : null
+  Modal.Container = Div
+  Modal.Header = Div
+  Modal.Content = Div
+  const Table = ({ children }: { children?: React.ReactNode }) => <table>{children}</table>
+  Table.Container = Div
+  Table.Header = ({ children }: { children?: React.ReactNode }) => <thead>{children}</thead>
+  Table.Body = ({ children }: { children?: React.ReactNode }) => <tbody>{children}</tbody>
+  Table.Row = ({ children, ...props }: React.HTMLAttributes<HTMLTableRowElement>) => (
+    <tr {...props}>{children}</tr>
+  )
+  Table.Cell = ({ children, ...props }: React.TdHTMLAttributes<HTMLTableCellElement>) => (
+    <td {...props}>{children}</td>
+  )
+  return {
+    Alert: Div,
+    Button,
+    CloseIcon: () => null,
+    Container: Div,
+    IconButton: Button,
+    LoaderEllipsis: () => <span>loading</span>,
+    Modal,
+    Section: Div,
+    Select: () => <select aria-label="page size" />,
+    Table,
+  }
+})
+
+vi.mock('../../routes/admin-path.js', () => ({
+  getAdminRouteId: () => '/admin/collections/$collection/$id/history',
+  getAdminRoutePath: (...parts: string[]) => `/admin/${parts.join('/')}`,
+}))
+
+vi.mock('../../server-fns/singletons/index.js', () => ({
+  findSingletonByVersion: mocks.findSingletonByVersion,
+  restoreSingletonVersion: mocks.restoreSingleton,
+}))
+
+vi.mock('../../server-fns/collections/index.js', () => ({
+  restoreDocumentVersion: mocks.restoreCollection,
+}))
+
+vi.mock('../chrome/loose-router.js', () => ({
+  Link: ({ children, ...props }: React.AnchorHTMLAttributes<HTMLAnchorElement>) => (
+    <a {...props}>{children}</a>
+  ),
+  useNavigate: () => mocks.navigate,
+}))
+
+vi.mock('../chrome/router-pager.js', () => ({
+  RouterPager: (props: { componentName: string; page: number; count: number }) => {
+    mocks.pagerProps.push(props)
+    return <div data-pager={props.componentName} />
+  },
+}))
+
+vi.mock('../chrome/th-sortable.js', () => ({
+  TableHeadingCellSortable: ({ label }: { label: string }) => <th>{label}</th>,
+}))
+
+vi.mock('../collections/document-history.js', () => ({
+  DocumentHistoryView: () => <div data-testid="document-audit-log" />,
+}))
+vi.mock('../collections/view-menu.js', () => ({ ViewMenu: () => <div /> }))
+vi.mock('./view-menu.js', () => ({ SingletonViewMenu: () => <div /> }))
+
+import { HistoryView } from '../collections/history.js'
+import { SingletonHistoryView } from './history.js'
+import type { VersionHistoryData } from '../collections/version-history.js'
+
+const singletonDefinition = {
+  singleton: true,
+  path: 'site-settings',
+  label: 'Site settings',
+  workflow: { statuses: [{ name: 'published', label: 'Published' }], defaultStatus: 'published' },
+  fields: [],
+} as unknown as SingletonDefinition
+
+const collectionDefinition = {
+  path: 'articles',
+  labels: { singular: 'Article', plural: 'Articles' },
+  useAsTitle: 'title',
+  fields: [{ name: 'title', label: 'Title', type: 'text' }],
+} as MultiCollectionDefinition
+
+const data: VersionHistoryData = {
+  docs: [
+    {
+      id: 'document-settings',
+      versionId: 'version-old',
+      status: 'draft',
+      createdAt: '2026-08-25T10:00:00.000Z',
+      createdBy: 'actor-1',
+      eventType: 'update',
+      fields: { title: 'Old' },
+    },
+    {
+      id: 'document-settings',
+      versionId: 'version-current',
+      status: 'published',
+      createdAt: '2026-08-26T10:00:00.000Z',
+      createdBy: 'actor-2',
+      eventType: 'update',
+      fields: { title: 'Current' },
+    },
+  ],
+  meta: { total: 2, page: 1, pageSize: 15, totalPages: 1, desc: false },
+  actors: {
+    'actor-1': { label: 'Ada Editor' },
+    'actor-2': { label: 'Grace Editor' },
+  },
+}
+
+const currentDocument = {
+  id: 'document-settings',
+  versionId: 'version-current',
+  status: 'published',
+  fields: { title: 'Current' },
+}
+
+let container: HTMLDivElement
+let root: Root
+
+function render(element: React.ReactNode) {
+  container = document.createElement('div')
+  document.body.append(container)
+  root = createRoot(container)
+  act(() => root.render(element))
+}
+
+function dispose() {
+  act(() => root.unmount())
+  container.remove()
+}
+
+afterAll(() => {
+  delete (globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean })
+    .IS_REACT_ACT_ENVIRONMENT
+})
+
+describe('singleton version history', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    ;(
+      globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+    ).IS_REACT_ACT_ENVIRONMENT = true
+    mocks.location.pathname = '/admin/singletons/site-settings/history'
+    mocks.location.search = {}
+    mocks.pagerProps.length = 0
+    mocks.diffModalProps.length = 0
+  })
+
+  it('renders an explicit singleton restore column without collection title configuration', async () => {
+    render(
+      <SingletonHistoryView
+        singletonDefinition={singletonDefinition}
+        data={data}
+        currentDocument={currentDocument}
+        contentLocales={[]}
+        defaultContentLocale="en"
+        workflowStatuses={[]}
+      />
+    )
+
+    expect(container.textContent).toContain('draft')
+    expect(container.textContent).toContain('published')
+    expect(
+      [...container.querySelectorAll('.byline-singleton-history-actor-cell')].map(
+        (cell) => cell.textContent
+      )
+    ).toEqual(['Ada Editor', 'Grace Editor'])
+    expect(container.textContent).not.toContain('collections.history.tabs.document')
+    const restoreButtons = [...container.querySelectorAll('button')].filter(
+      (button) => button.textContent === 'Restore'
+    )
+    expect(restoreButtons).toHaveLength(1)
+    expect(restoreButtons[0]?.title).toBe('Restore this version as Published')
+
+    await act(async () => restoreButtons[0]?.click())
+    expect(container.textContent).toContain('New version status: Published')
+    const confirm = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent === 'Restore as Published'
+    )
+    await act(async () => confirm?.click())
+
+    expect(mocks.restoreSingleton).toHaveBeenCalledWith({
+      data: { singleton: 'site-settings', versionId: 'version-old' },
+    })
+    expect(mocks.invalidate).toHaveBeenCalledTimes(1)
+    expect(mocks.navigate).toHaveBeenLastCalledWith({
+      to: '/admin/singletons/$singleton',
+      params: { singleton: 'site-settings' },
+      search: {},
+    })
+    dispose()
+  })
+
+  it('wires the requested page and total pages into both shared pagers', () => {
+    render(
+      <SingletonHistoryView
+        singletonDefinition={singletonDefinition}
+        data={{
+          ...data,
+          meta: { ...data.meta, page: 3, pageSize: 30, total: 95, totalPages: 4 },
+        }}
+        currentDocument={currentDocument}
+        contentLocales={[]}
+        defaultContentLocale="en"
+        workflowStatuses={[]}
+      />
+    )
+
+    expect(mocks.pagerProps).toEqual([
+      expect.objectContaining({ componentName: 'pagerTop', page: 3, count: 4 }),
+      expect.objectContaining({ componentName: 'pagerBottom', page: 3, count: 4 }),
+    ])
+    dispose()
+  })
+
+  it('opens comparison with the singleton-bound historical version loader', async () => {
+    render(
+      <SingletonHistoryView
+        singletonDefinition={singletonDefinition}
+        data={data}
+        currentDocument={currentDocument}
+        contentLocales={[]}
+        defaultContentLocale="en"
+        workflowStatuses={[]}
+      />
+    )
+
+    const compare = container.querySelector<HTMLButtonElement>(
+      'button[aria-label="collections.history.compareAriaLabel"]'
+    )
+    await act(async () => {
+      compare?.click()
+      await Promise.resolve()
+    })
+
+    expect(container.querySelector('[data-testid="diff-modal"]')).not.toBeNull()
+    expect(mocks.diffModalProps).toHaveLength(1)
+    expect(mocks.diffModalProps[0]).toMatchObject({
+      collection: 'site-settings',
+      documentId: 'document-settings',
+      versionId: 'version-old',
+      currentDocument,
+    })
+
+    const loadHistoricalVersion = mocks.diffModalProps[0]?.loadHistoricalVersion as (
+      resourcePath: string,
+      documentId: string,
+      versionId: string,
+      locale?: string
+    ) => Promise<Record<string, unknown>>
+    await loadHistoricalVersion('site-settings', 'document-settings', 'version-old', 'fr')
+    expect(mocks.findSingletonByVersion).toHaveBeenCalledWith({
+      data: { singleton: 'site-settings', versionId: 'version-old', locale: 'fr' },
+    })
+    dispose()
+  })
+
+  it('renders an empty unmaterialised history without an audit-log tab or restore action', () => {
+    render(
+      <SingletonHistoryView
+        singletonDefinition={singletonDefinition}
+        data={{
+          docs: [],
+          meta: { total: 0, page: 3, pageSize: 30, totalPages: 0 },
+          actors: {},
+        }}
+        currentDocument={null}
+        contentLocales={[]}
+        defaultContentLocale="en"
+        workflowStatuses={[]}
+      />
+    )
+
+    expect(container.textContent).toContain('Site settings History')
+    expect(container.textContent).not.toContain('collections.history.tabs.document')
+    expect(container.querySelectorAll('button')).toHaveLength(0)
+    dispose()
+  })
+
+  it('keeps the collection audit tab and title-driven restore behavior', async () => {
+    mocks.location.pathname = '/admin/collections/articles/document-article/history'
+    render(
+      <HistoryView
+        collectionDefinition={collectionDefinition}
+        adminConfig={{
+          slug: 'articles',
+          columns: [{ fieldName: 'title', label: 'Title' }],
+        }}
+        data={data as never}
+        auditLog={{ entries: [], meta: { total: 0, page: 1, pageSize: 100, totalPages: 0 } }}
+        currentDocument={{ ...currentDocument, id: 'document-article' }}
+        contentLocales={[]}
+        defaultContentLocale="en"
+      />
+    )
+
+    expect(container.textContent).toContain('collections.history.tabs.document')
+    const restore = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent === 'Restore'
+    )
+    expect(restore).toBeDefined()
+    expect(restore?.title).toBe('Restore this version as Draft')
+    await act(async () => restore?.click())
+    expect(container.textContent).toContain('New version status: Draft')
+    const confirm = [...container.querySelectorAll('button')].find(
+      (button) => button.textContent === 'Restore as Draft'
+    )
+    await act(async () => confirm?.click())
+
+    expect(mocks.restoreCollection).toHaveBeenCalledWith({
+      data: {
+        collection: 'articles',
+        id: 'document-article',
+        versionId: 'version-old',
+      },
+    })
+    expect(mocks.navigate).toHaveBeenLastCalledWith({
+      to: '/admin/collections/$collection/$id',
+      params: { collection: 'articles', id: 'document-article' },
+    })
+    dispose()
+  })
+})

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

@@ -0,0 +1,185 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { useRouter, useRouterState } from '@tanstack/react-router'
+
+import { StatusBadge } from '@byline/admin/react'
+import type {
+  SingletonAdminConfig,
+  SingletonDefinition,
+  SingletonPreviewDocument,
+  WorkflowStatus,
+} from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Button, Container, Section, Table } from '@byline/ui/react'
+import cx from 'clsx'
+
+import { getAdminRoutePath } from '../../routes/admin-path.js'
+import {
+  findSingletonByVersion,
+  restoreSingletonVersion,
+} from '../../server-fns/singletons/index.js'
+import { useNavigate } from '../chrome/loose-router.js'
+import historyStyles from '../collections/history.module.css'
+import {
+  HistoryStats,
+  VersionHistoryCore,
+  type VersionHistoryData,
+  type VersionHistoryRowPresentation,
+} from '../collections/version-history.js'
+import { SingletonViewMenu } from './view-menu.js'
+import type { ContentLocaleOption } from '../collections/view-menu.js'
+
+export function SingletonHistoryView({
+  singletonDefinition,
+  adminConfig,
+  data,
+  currentDocument,
+  contentLocales,
+  defaultContentLocale,
+  workflowStatuses,
+}: {
+  singletonDefinition: SingletonDefinition
+  adminConfig?: SingletonAdminConfig
+  data: VersionHistoryData
+  currentDocument?: Record<string, unknown> | null
+  contentLocales: ReadonlyArray<ContentLocaleOption>
+  defaultContentLocale: string
+  workflowStatuses: WorkflowStatus[]
+}) {
+  const singleton = singletonDefinition.path
+  const navigate = useNavigate()
+  const router = useRouter()
+  const location = useRouterState({ select: (state) => state.location })
+  const locale = (location.search as { locale?: string }).locale
+  const { t } = useTranslation('byline-admin')
+
+  function handlePageSizeChange(pageSize: number): void {
+    const params = structuredClone(location.search)
+    delete params.page
+    params.page_size = pageSize
+    navigate({
+      to: getAdminRoutePath('singletons', '$singleton', 'history'),
+      params: { singleton },
+      search: params,
+    })
+  }
+
+  const rowPresentation: VersionHistoryRowPresentation = {
+    headers: (
+      <>
+        <th scope="col">{t('collections.history.statusColumn')}</th>
+        <th scope="col">{t('collections.documentHistory.colWhen')}</th>
+        <th scope="col">{t('collections.documentHistory.colActor')}</th>
+        <th
+          scope="col"
+          className={cx('byline-coll-history-col-restore', historyStyles.colRestore)}
+        />
+      </>
+    ),
+    auditColSpan: 4,
+    renderCells: ({
+      document,
+      versionId,
+      currentVersionId,
+      actorLabel,
+      restoreStatusLabel,
+      openRestore,
+    }) => (
+      <>
+        <Table.Cell className="byline-singleton-history-status-cell">
+          <StatusBadge status={document.status} workflowStatuses={workflowStatuses} />
+        </Table.Cell>
+        <Table.Cell className="byline-singleton-history-created-cell">
+          {new Date(document.createdAt).toLocaleString()}
+        </Table.Cell>
+        <Table.Cell className="byline-singleton-history-actor-cell">{actorLabel}</Table.Cell>
+        <Table.Cell className={cx('byline-coll-history-restore-cell', historyStyles.restoreCell)}>
+          {versionId && versionId !== currentVersionId ? (
+            <Button
+              type="button"
+              variant="outlined"
+              size="xs"
+              intent="noeffect"
+              onClick={openRestore}
+              className={cx('byline-coll-history-restore-button', historyStyles.restoreButton)}
+              title={t('collections.history.restoreButtonTitle', {
+                status: restoreStatusLabel,
+              })}
+            >
+              {t('collections.history.restoreButton')}
+            </Button>
+          ) : null}
+        </Table.Cell>
+      </>
+    ),
+  }
+
+  const documentId =
+    currentDocument && typeof currentDocument.id === 'string' ? currentDocument.id : ''
+
+  return (
+    <>
+      <Section>
+        <Container>
+          <div className={cx('byline-coll-history-head', historyStyles.head)}>
+            <h2 className={cx('byline-coll-history-title', historyStyles.title)}>
+              {t('collections.history.title', { label: singletonDefinition.label })}{' '}
+              <HistoryStats total={data.meta.total} />
+            </h2>
+            <SingletonViewMenu
+              singleton={singleton}
+              activeView="history"
+              locale={locale}
+              contentLocales={contentLocales}
+              defaultContentLocale={defaultContentLocale}
+              adminConfig={adminConfig}
+              doc={
+                currentDocument == null
+                  ? undefined
+                  : (currentDocument as unknown as SingletonPreviewDocument)
+              }
+            />
+          </div>
+        </Container>
+      </Section>
+      <Section>
+        <Container>
+          <VersionHistoryCore
+            data={data}
+            resourceDefinition={singletonDefinition}
+            resourcePath={singleton}
+            documentId={documentId}
+            currentDocument={currentDocument}
+            locale={locale}
+            rowPresentation={rowPresentation}
+            loadHistoricalVersion={async (_path, _documentId, versionId, versionLocale) => {
+              const historical = await findSingletonByVersion({
+                data: { singleton, versionId, locale: versionLocale },
+              })
+              if (historical == null) throw new Error('Singleton version not found')
+              return historical as unknown as Record<string, unknown>
+            }}
+            onPageSizeChange={handlePageSizeChange}
+            restoreVersion={(versionId) =>
+              restoreSingletonVersion({ data: { singleton, versionId } })
+            }
+            onRestoreComplete={async () => {
+              await router.invalidate()
+              navigate({
+                to: getAdminRoutePath('singletons', '$singleton'),
+                params: { singleton },
+                search: locale ? { locale } : {},
+              })
+            }}
+          />
+        </Container>
+      </Section>
+    </>
+  )
+}

package/src/admin-shell/singletons/preview-link.tsx

@@ -0,0 +1,75 @@
+'use client'
+
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+
+import { useState } from 'react'
+
+import type { SingletonAdminConfig, SingletonPreviewDocument } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { ExternalLinkIcon, IconButton, useToastManager } from '@byline/ui/react'
+import cx from 'clsx'
+
+import { enablePreviewModeFn } from '../../server-fns/preview/index.js'
+
+/**
+ * Explicit-preview-only singleton affordance. A singleton's stored path is
+ * internal identity metadata, so unlike collection previews there is no
+ * schema or conventional path fallback.
+ */
+export function SingletonPreviewLink({
+  doc,
+  adminConfig,
+  locale,
+  className,
+}: {
+  doc: SingletonPreviewDocument
+  adminConfig: SingletonAdminConfig
+  locale?: string
+  className?: string
+}) {
+  const toastManager = useToastManager()
+  const { t } = useTranslation('byline-admin')
+  const [busy, setBusy] = useState(false)
+  const url = adminConfig.preview?.url(doc, { locale }) ?? null
+
+  if (url == null) return null
+
+  const handleClick = async () => {
+    if (busy) return
+    setBusy(true)
+    try {
+      await enablePreviewModeFn()
+      window.location.assign(url)
+    } catch (err) {
+      toastManager.add({
+        title: t('collections.preview.toastTitle'),
+        description: t('collections.preview.failedDescription', {
+          message: (err as Error).message,
+        }),
+        data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
+      })
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <IconButton
+      className={cx('byline-preview-link', className)}
+      size="xs"
+      variant="text"
+      disabled={busy}
+      onClick={handleClick}
+      aria-label={t('collections.preview.openAriaLabel')}
+      title={t('collections.preview.title')}
+    >
+      <ExternalLinkIcon width="20px" height="20px" className="byline-preview-link-icon" />
+    </IconButton>
+  )
+}