@byline/host-tanstack-start 6.7.2 → 6.9.0

package/src/admin-shell/collections/api.test.tsx

@@ -0,0 +1,223 @@
+/**
+ * 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 { ComponentProps, ReactNode } from 'react'
+import { act } from 'react'
+
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createRoot } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+const mocks = vi.hoisted(() => ({ toast: vi.fn(), writeText: vi.fn() }))
+vi.mock('@byline/ui/react', () => ({
+  Container: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+  Section: ({ children }: { children: ReactNode }) => <section>{children}</section>,
+  IconButton: ({
+    size: _size,
+    variant: _variant,
+    ...props
+  }: ComponentProps<'button'> & {
+    size?: string
+    variant?: string
+  }) => <button {...props} />,
+  Tooltip: ({ children }: { children: ReactNode }) => children,
+  CopyIcon: () => null,
+  DownloadIcon: () => null,
+  useToastManager: () => ({ add: mocks.toast }),
+}))
+vi.mock('./view-menu.js', () => ({
+  ViewMenu: ({ dataActions }: { dataActions?: ReactNode }) => <div>{dataActions}</div>,
+}))
+
+import { ApiView } from './api.js'
+
+const payload = {
+  id: 'document-1',
+  fields: {
+    title: 'Sample document',
+    content: [{ _type: 'text', children: [{ text: 'Hidden nested content' }] }],
+    related: { fields: { title: 'Populated relation' } },
+  },
+} as ComponentProps<typeof ApiView>['initialData']
+
+let container: HTMLDivElement
+let root: ReturnType<typeof createRoot>
+const originalURL = globalThis.URL
+const createObjectURL = vi.fn((_blob: Blob) => 'blob:test-json')
+const revokeObjectURL = vi.fn()
+
+// `locale: null` renders as a route without a locale search param.
+function render(data = payload, locale: string | null = 'en', depth = 0) {
+  act(() =>
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        <ApiView
+          collectionDefinition={{
+            path: 'docs',
+            labels: { singular: 'Doc', plural: 'Docs' },
+            fields: [],
+          }}
+          initialData={data}
+          locale={locale ?? undefined}
+          depth={depth}
+          contentLocales={[
+            { code: 'en', label: 'English' },
+            { code: 'fr', label: 'French' },
+          ]}
+          defaultContentLocale="fr"
+        />
+      </I18nProvider>
+    )
+  )
+}
+
+async function click(label: string) {
+  const button = container.querySelector<HTMLButtonElement>(`button[aria-label="${label}"]`)
+  if (!button) throw new Error(`Button not found: ${label}`)
+  await act(async () => button.click())
+}
+
+function readBlob(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => resolve(String(reader.result))
+    reader.onerror = () => reject(reader.error)
+    reader.readAsText(blob)
+  })
+}
+
+beforeEach(() => {
+  vi.stubGlobal('IS_REACT_ACT_ENVIRONMENT', true)
+  vi.stubGlobal(
+    'URL',
+    Object.assign(class extends originalURL {}, { createObjectURL, revokeObjectURL })
+  )
+  vi.stubGlobal('navigator', { clipboard: { writeText: mocks.writeText } })
+  mocks.writeText.mockResolvedValue(undefined)
+  container = document.createElement('div')
+  document.body.append(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => root.unmount())
+  container.remove()
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+  vi.unstubAllGlobals()
+  vi.clearAllMocks()
+})
+
+describe('API document exports', () => {
+  it('copies the complete payload without expanding or mounting nested content', async () => {
+    render()
+    expect(container.textContent).not.toContain('Hidden nested content')
+    await click('Copy JSON')
+    expect(JSON.parse(mocks.writeText.mock.calls[0]?.[0])).toEqual(payload)
+    expect(container.textContent).not.toContain('Hidden nested content')
+    expect(mocks.toast).toHaveBeenCalledWith(expect.objectContaining({ title: 'JSON copied' }))
+  })
+
+  it('copies new data after a locale and population-depth reload', async () => {
+    render()
+    const reloaded = {
+      ...payload,
+      fields: { title: 'Français', related: { title: 'Relation française' } },
+    }
+    render(reloaded, 'fr', 2)
+    await click('Copy JSON')
+    expect(JSON.parse(mocks.writeText.mock.calls[0]?.[0])).toEqual(reloaded)
+  })
+
+  it('reports clipboard rejection without claiming success', async () => {
+    mocks.writeText.mockRejectedValue(new Error('Permission denied'))
+    render()
+    await click('Copy JSON')
+    expect(mocks.toast).toHaveBeenCalledTimes(1)
+    expect(mocks.toast).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'Could not copy JSON. Try Download JSON.',
+      })
+    )
+    expect(container.querySelector('button')?.disabled).toBe(false)
+  })
+
+  it('offers download when the clipboard API is unavailable', async () => {
+    vi.stubGlobal('navigator', {})
+    render()
+    await click('Copy JSON')
+    expect(mocks.toast).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'Could not copy JSON. Try Download JSON.',
+      })
+    )
+    expect(mocks.writeText).not.toHaveBeenCalled()
+  })
+
+  it('names a download after the default locale when the route has none', async () => {
+    vi.useFakeTimers()
+    let filename = ''
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(function (
+      this: HTMLAnchorElement
+    ) {
+      filename = this.download
+    })
+    render(payload, null)
+    await click('Download JSON')
+    expect(filename).toBe('docs-document-1-fr.json')
+  })
+
+  it('reports a download failure and releases the allocated URL', async () => {
+    vi.useFakeTimers()
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(() => {
+      throw new Error('Download unavailable')
+    })
+    render()
+    await click('Download JSON')
+    expect(mocks.toast).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: 'Could not download JSON.',
+      })
+    )
+    expect(document.querySelector('a[download]')).toBeNull()
+    vi.advanceTimersByTime(1000)
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:test-json')
+  })
+
+  it('downloads complete current JSON and releases the temporary link and URL', async () => {
+    vi.useFakeTimers()
+    let filename = ''
+    vi.spyOn(HTMLAnchorElement.prototype, 'click').mockImplementation(function (
+      this: HTMLAnchorElement
+    ) {
+      filename = this.download
+      expect(this.isConnected).toBe(true)
+      expect(this.href).toBe('blob:test-json')
+    })
+    render()
+    const reloaded = { ...payload, fields: { title: 'Français', content: payload.fields.content } }
+    render(reloaded, 'fr', 2)
+    await click('Download JSON')
+    const blob = createObjectURL.mock.calls[0]?.[0] as Blob
+    expect(blob.type).toBe('application/json;charset=utf-8')
+    expect(filename).toBe('docs-document-1-fr-depth2.json')
+    expect(document.querySelector('a[download]')).toBeNull()
+    expect(revokeObjectURL).not.toHaveBeenCalled()
+    vi.advanceTimersByTime(1000)
+    expect(revokeObjectURL).toHaveBeenCalledWith('blob:test-json')
+    vi.useRealTimers()
+    expect(JSON.parse(await readBlob(blob))).toEqual(reloaded)
+    expect(container.textContent).not.toContain('Hidden nested content')
+  })
+})

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

@@ -6,10 +6,20 @@
  * Copyright (c) Infonomic Company Limited
  */
 
+import { useState } from 'react'
+
 import type { MultiCollectionDefinition } from '@byline/core'
 import type { AnyCollectionSchemaTypes } from '@byline/core/zod-schemas'
 import { useTranslation } from '@byline/i18n/react'
-import { Container, Section } from '@byline/ui/react'
+import {
+  Container,
+  CopyIcon,
+  DownloadIcon,
+  IconButton,
+  Section,
+  Tooltip,
+  useToastManager,
+} from '@byline/ui/react'
 import cx from 'clsx'
 import { darkStyles, JsonView } from 'react-json-view-lite'
 
@@ -36,8 +46,12 @@ const expandToFirstLevel = (level: number): boolean => level < 2
 /**
  * JSON inspector view for a collection document.
  *
+ * Copy JSON and Download JSON render in the view menu's data group, beside the
+ * locale and depth controls whose selection they export.
+ *
  * Stable override handles: `.byline-api-section`, `.byline-api-container`,
- * `.byline-api-head`, `.byline-api-title`, `.byline-api-viewer`.
+ * `.byline-api-head`, `.byline-api-title`, `.byline-api-action`,
+ * `.byline-api-viewer`.
  */
 export const ApiView = ({
   collectionDefinition,
@@ -49,7 +63,7 @@ export const ApiView = ({
 }: {
   collectionDefinition: MultiCollectionDefinition
   initialData: AnyCollectionSchemaTypes['UpdateType']
-  /** Currently active locale from the route search param (undefined → all). */
+  /** Locale from the route search param (undefined → the default content locale). */
   locale?: string
   /** Populate depth from the route search param (undefined → 0, no populate). */
   depth?: number
@@ -58,6 +72,58 @@ export const ApiView = ({
 }) => {
   const { labels, path } = collectionDefinition
   const { t } = useTranslation('byline-admin')
+  const toastManager = useToastManager()
+  const [copyPending, setCopyPending] = useState(false)
+
+  // Serialize only on demand, from the complete loaded payload rather than
+  // the mounted tree. Collapsed branches remain part of both exports.
+  const copyJson = async () => {
+    setCopyPending(true)
+    try {
+      await navigator.clipboard.writeText(JSON.stringify(initialData, null, 2))
+      toastManager.add({
+        title: t('collections.api.copied'),
+        data: { intent: 'success', iconType: 'success', icon: true, close: true },
+      })
+    } catch {
+      toastManager.add({
+        title: t('collections.api.copyFailed'),
+        data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
+      })
+    } finally {
+      setCopyPending(false)
+    }
+  }
+
+  const downloadJson = () => {
+    try {
+      const blob = new Blob([JSON.stringify(initialData, null, 2)], {
+        type: 'application/json;charset=utf-8',
+      })
+      const url = URL.createObjectURL(blob)
+      const link = document.createElement('a')
+      try {
+        link.href = url
+        // Name the selection, so exports of one document in different locales
+        // or population depths do not collide.
+        const selection = [path, String(initialData.id), locale ?? defaultContentLocale]
+        if (depth != null && depth > 0) selection.push(`depth${depth}`)
+        const filename = selection.join('-').replace(/[^a-zA-Z0-9_-]/g, '-')
+        link.download = `${filename}.json`
+        document.body.appendChild(link)
+        link.click()
+      } finally {
+        link.remove()
+        // Let the browser acquire the download before releasing its URL.
+        setTimeout(() => URL.revokeObjectURL(url), 1000)
+      }
+    } catch {
+      toastManager.add({
+        title: t('collections.api.downloadFailed'),
+        data: { intent: 'danger', iconType: 'danger', icon: true, close: true },
+      })
+    }
+  }
 
   return (
     <Section className={cx('byline-api-section', styles.section)}>
@@ -74,6 +140,35 @@ export const ApiView = ({
             depth={depth}
             contentLocales={contentLocales}
             defaultContentLocale={defaultContentLocale}
+            dataActions={
+              <>
+                <Tooltip text={t('collections.api.copyJson')} side="bottom" delay={0}>
+                  <IconButton
+                    type="button"
+                    size="xs"
+                    variant="text"
+                    className="byline-view-menu-icon-button byline-api-action"
+                    aria-label={t('collections.api.copyJson')}
+                    disabled={copyPending}
+                    onClick={copyJson}
+                  >
+                    <CopyIcon width="18px" height="18px" />
+                  </IconButton>
+                </Tooltip>
+                <Tooltip text={t('collections.api.downloadJson')} side="bottom" delay={0}>
+                  <IconButton
+                    type="button"
+                    size="xs"
+                    variant="text"
+                    className="byline-view-menu-icon-button byline-api-action"
+                    aria-label={t('collections.api.downloadJson')}
+                    onClick={downloadJson}
+                  >
+                    <DownloadIcon width="20px" height="20px" />
+                  </IconButton>
+                </Tooltip>
+              </>
+            }
           />
         </div>
         <div className={cx('byline-api-viewer', styles.viewer)}>

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

@@ -9,7 +9,11 @@
 import { useState } from 'react'
 
 import { FormRenderer } from '@byline/admin/react'
-import type { CollectionAdminConfig, MultiCollectionDefinition } from '@byline/core'
+import type {
+  CollectionAdminConfig,
+  MultiCollectionDefinition,
+  UnavailableBlock,
+} from '@byline/core'
 import {
   getDefaultStatus,
   getWorkflow,
@@ -321,6 +325,9 @@ export const EditView = ({
   // orphan row was skipped because the collection schema has moved on
   // since the document was written.
   // biome-ignore lint/suspicious/noExplicitAny: storage shape
+  const unavailableBlocks = (initialData as any)?._unavailableBlocks as
+    | UnavailableBlock[]
+    | undefined
   const restoreWarnings = (initialData as any)?._restoreWarnings as string[] | undefined
 
   const handleUnpublish = async () => {
@@ -854,6 +861,7 @@ export const EditView = ({
           contentLocales={contentLocales}
           publishedVersion={publishedVersion}
           restoreWarnings={restoreWarnings}
+          unavailableBlocks={unavailableBlocks}
           nextStatus={nextStatus}
           workflowStatuses={workflowStatuses}
           onCancel={() => {

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

@@ -47,7 +47,7 @@ import { useState } from 'react'
 
 import type { CollectionAdminConfig, PreviewDocument } from '@byline/core'
 import { useTranslation } from '@byline/i18n/react'
-import { ExternalLinkIcon, IconButton, useToastManager } from '@byline/ui/react'
+import { ExternalLinkIcon, IconButton, Tooltip, useToastManager } from '@byline/ui/react'
 import cx from 'clsx'
 
 import { enablePreviewModeFn } from '../../server-fns/preview/index.js'
@@ -110,16 +110,17 @@ export const PreviewLink = ({
   }
 
   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>
+    <Tooltip text={t('collections.preview.title')} side="bottom" delay={0}>
+      <IconButton
+        className={cx('byline-preview-link', className)}
+        size="xs"
+        variant="text"
+        disabled={busy}
+        onClick={handleClick}
+        aria-label={t('collections.preview.openAriaLabel')}
+      >
+        <ExternalLinkIcon width="20px" height="20px" className="byline-preview-link-icon" />
+      </IconButton>
+    </Tooltip>
   )
 }

package/src/admin-shell/collections/view-menu.module.css

@@ -2,21 +2,47 @@
  * ViewMenu — mini-nav bar for document-level views (Edit, History, API).
  *
  * Override handles:
- *   .byline-view-menu        — outer flex row
+ *   .byline-view-menu        — outer row; wraps between its two groups
+ *   .byline-view-menu-data   — locale/depth selects and the data actions that
+ *                              act on them (API view: Copy / Download JSON)
+ *   .byline-view-menu-nav    — preview link and view navigation
  *   .byline-view-menu-label  — locale/depth label (lg-only)
  *   .byline-view-menu-button — primary view buttons (Edit/API)
- *   .byline-view-menu-icon-button — history icon button
+ *   .byline-view-menu-icon-button — preview, history, and data-action icon buttons
  */
 
+/* Groups wrap as units, so a narrow viewport breaks the row between "what
+ * you are looking at" and "where you can go" rather than mid-group. The
+ * wider column gap marks the boundary when both groups share a line. */
 .root,
 :global(.byline-view-menu) {
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
-  gap: 0.5rem;
+  gap: 0.5rem 1.25rem;
   margin-top: 0.5rem;
   margin-bottom: 0.5rem;
 }
 
+/* Beside the heading (every host switches to a row at 40rem), keep a wrapped
+ * second line flush with the right edge rather than stranded under the
+ * heading's side of the menu. */
+@media (min-width: 40rem) {
+  .root,
+  :global(.byline-view-menu) {
+    justify-content: flex-end;
+  }
+}
+
+.group,
+:global(.byline-view-menu-data),
+:global(.byline-view-menu-nav) {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+}
+
 .label,
 :global(.byline-view-menu-label) {
   display: none;