@byline/admin 6.2.0 → 6.3.0

package/src/forms/use-form-submission.ts

@@ -0,0 +1,293 @@
+'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 { useCallback, useRef, useState } from 'react'
+
+import type { Field } from '@byline/core'
+import type { DocumentPatch } from '@byline/core/patches'
+import { useTranslation } from '@byline/i18n/react'
+
+import { useBylineFieldServices } from '../fields/field-services-context'
+import { useFormContext } from './form-context'
+import { executeUploadsWithProgress } from './upload-executor'
+
+/**
+ * Payload emitted by the form on Save. Carries the content (field data +
+ * patches) alongside the document-grain system fields (path / advertised
+ * locales) and per-bucket dirty flags so the host can route each piece to the
+ * right write path — versioned for content, immediate/non-versioned for the
+ * system fields. See docs/08-internationalization/index.md.
+ */
+export interface SystemFieldsSubmitPayload {
+  // biome-ignore lint/suspicious/noExplicitAny: data is collection-specific
+  data: any
+  patches: DocumentPatch[]
+  contentDirty: boolean
+  pathDirty: boolean
+  systemPath?: string | null
+  availableLocalesDirty: boolean
+  systemAvailableLocales?: string[]
+}
+
+/**
+ * Where a save has got to. Mutually exclusive by construction: the form cannot
+ * be validating and uploading at once, which two independent booleans allowed.
+ */
+export type SubmissionPhase =
+  | { kind: 'idle' }
+  | { kind: 'validating' }
+  | { kind: 'uploading' }
+  | { kind: 'confirmingSystemFields'; payload: SystemFieldsSubmitPayload }
+  | { kind: 'submitting' }
+
+export interface UseFormSubmissionOptions {
+  mode: 'create' | 'edit'
+  fields: Field[]
+  /** Persisted document id (edit mode only); feeds server-side upload hooks. */
+  documentId?: string
+  /**
+   * Only collections that opted into the advertised-locale widget emit the
+   * locale set, so the write path never touches
+   * `byline_document_available_locales` for the others.
+   */
+  advertiseLocales?: boolean
+  onSubmit: (payload: SystemFieldsSubmitPayload) => void | Promise<void>
+  /** Mutations blocked (stale/lock/discarding). Read synchronously, per call. */
+  isBlocked: () => boolean
+  /**
+   * Called immediately before the form becomes `inert` — once before uploads
+   * and once before submission — so the caller can record the focused element
+   * and restore it when busy ends. The DOM refs stay in the component; the
+   * hook only signals the transition.
+   */
+  onBeforeBusy?: () => void
+}
+
+export interface UseFormSubmissionResult {
+  phase: SubmissionPhase
+  isBusy: boolean
+  submit: () => Promise<void>
+  confirmSystemFields: () => Promise<void>
+  cancelSystemFields: () => void
+}
+
+const IDLE: SubmissionPhase = { kind: 'idle' }
+
+/**
+ * Owns one save: validate → upload → (confirm) → submit.
+ *
+ * Admission is decided by a ref, not by `phase`. Rendered state is not a
+ * re-entry guard: two `submit()` calls in the same turn both observe
+ * `phase.kind === 'idle'` because React has not rerendered between them. The
+ * ref is set synchronously at the top of `submit()` and cleared in `finally`,
+ * spanning validation through submission — the whole window, not just the
+ * final request. `phase` drives the UI; the ref decides admission.
+ */
+export function useFormSubmission(options: UseFormSubmissionOptions): UseFormSubmissionResult {
+  const { mode, fields, documentId, advertiseLocales, onSubmit, isBlocked, onBeforeBusy } = options
+
+  const {
+    getFieldValues,
+    runFieldHooks,
+    validateForm,
+    resetHasChanges,
+    getPatches,
+    getDirtyBreakdown,
+    getSystemPath,
+    getSystemAvailableLocales,
+    setFieldValue,
+    setFieldError,
+    getPendingUploads,
+    clearPendingUploads,
+    setFieldUploading,
+  } = useFormContext()
+  const { t } = useTranslation('byline-admin')
+  const { uploadField } = useBylineFieldServices()
+
+  const [phase, setPhase] = useState<SubmissionPhase>(IDLE)
+  const inFlightRef = useRef(false)
+
+  const isBusy = phase.kind === 'uploading' || phase.kind === 'submitting'
+
+  // Await the host handler. Resolution means the save succeeded and the clean
+  // baseline can be committed; rejection preserves dirty state so the editor
+  // does not lose work and the navigation guard keeps blocking. Host handlers
+  // that surface their own toast MUST rethrow afterwards.
+  const deliver = useCallback(
+    async (payload: SystemFieldsSubmitPayload) => {
+      // Settle before returning. `runUploads` may have left the phase at
+      // `uploading`, and this is the only reset on the delivery path: returning
+      // without it strands the form busy and inert with nothing in flight.
+      // Dirty state is deliberately untouched, so the save can be retried once
+      // the block clears.
+      if (isBlocked() || typeof onSubmit !== 'function') {
+        setPhase(IDLE)
+        return
+      }
+      onBeforeBusy?.()
+      setPhase({ kind: 'submitting' })
+      try {
+        await onSubmit(payload)
+        resetHasChanges()
+      } catch {
+        // Intentionally swallowed here — the host has already reported the
+        // failure to the user. Dirty state is preserved by not resetting.
+      } finally {
+        setPhase(IDLE)
+      }
+    },
+    [isBlocked, onBeforeBusy, onSubmit, resetHasChanges]
+  )
+
+  const runUploads = useCallback(async (): Promise<boolean> => {
+    const pendingUploads = getPendingUploads()
+    if (pendingUploads.size === 0) return true
+
+    onBeforeBusy?.()
+    setPhase({ kind: 'uploading' })
+    try {
+      const uploadResult = await executeUploadsWithProgress(
+        pendingUploads,
+        uploadField,
+        ({ fieldPath, status }) => {
+          setFieldUploading(fieldPath, status === 'uploading')
+        },
+        {
+          // Document context for server-side upload hooks: the persisted
+          // document id (edit mode only) plus any `upload.context` form
+          // values declared on the schema field. See UploadConfig.context
+          // in @byline/core.
+          documentId: mode === 'edit' ? documentId : undefined,
+          fields,
+          getFormValues: getFieldValues,
+        }
+      )
+
+      if (!uploadResult.allSucceeded) {
+        for (const [fieldPath, errorMessage] of uploadResult.errors.entries()) {
+          setFieldError(fieldPath, t('forms.uploadFailedFieldError', { message: errorMessage }))
+        }
+        console.error('One or more uploads failed:', uploadResult.errors)
+        return false
+      }
+
+      // Replace pending StoredFileValues with real ones in form data
+      for (const [fieldPath, storedFile] of uploadResult.successful.entries()) {
+        setFieldValue(fieldPath, storedFile)
+      }
+
+      // Clear pending uploads (blob URLs already revoked by clearPendingUploads)
+      clearPendingUploads()
+      return true
+    } catch (err) {
+      console.error('Upload execution error:', err)
+      return false
+    }
+  }, [
+    clearPendingUploads,
+    documentId,
+    fields,
+    getFieldValues,
+    getPendingUploads,
+    mode,
+    onBeforeBusy,
+    setFieldError,
+    setFieldUploading,
+    setFieldValue,
+    t,
+    uploadField,
+  ])
+
+  const buildPayload = useCallback((): { payload: SystemFieldsSubmitPayload; reason: string } => {
+    const { contentDirty, pathDirty, availableLocalesDirty, reason } = getDirtyBreakdown()
+    return {
+      reason,
+      payload: {
+        data: getFieldValues(),
+        patches: getPatches(),
+        contentDirty,
+        pathDirty,
+        systemPath: getSystemPath(),
+        availableLocalesDirty,
+        systemAvailableLocales: advertiseLocales ? getSystemAvailableLocales() : undefined,
+      },
+    }
+  }, [
+    advertiseLocales,
+    getDirtyBreakdown,
+    getFieldValues,
+    getPatches,
+    getSystemAvailableLocales,
+    getSystemPath,
+  ])
+
+  const submit = useCallback(async () => {
+    if (isBlocked()) return
+    if (inFlightRef.current) return
+    inFlightRef.current = true
+    try {
+      setPhase({ kind: 'validating' })
+
+      // Run field-level beforeValidate hooks (submit-time), then validate
+      const hookErrors = await runFieldHooks(fields)
+      const formErrors = validateForm(fields)
+      const allErrors = [...hookErrors, ...formErrors]
+
+      if (allErrors.length > 0) {
+        console.error('Form validation failed:', allErrors)
+        setPhase(IDLE)
+        return
+      }
+
+      if (isBlocked()) {
+        setPhase(IDLE)
+        return
+      }
+
+      if (!(await runUploads())) {
+        setPhase(IDLE)
+        return
+      }
+
+      const { payload, reason } = buildPayload()
+
+      // Editing the document-grain system fields (path / advertised locales) is
+      // an immediate, non-versioned write that does NOT reset workflow status,
+      // so confirm it before saving. Create mode writes everything as part of
+      // the initial version, so no confirmation applies there.
+      if (mode === 'edit' && (reason === 'direct-write' || reason === 'both')) {
+        setPhase({ kind: 'confirmingSystemFields', payload })
+        return
+      }
+
+      await deliver(payload)
+    } finally {
+      inFlightRef.current = false
+    }
+  }, [buildPayload, deliver, fields, isBlocked, mode, runUploads, runFieldHooks, validateForm])
+
+  const confirmSystemFields = useCallback(async () => {
+    if (phase.kind !== 'confirmingSystemFields') return
+    if (inFlightRef.current) return
+    inFlightRef.current = true
+    const { payload } = phase
+    try {
+      await deliver(payload)
+    } finally {
+      inFlightRef.current = false
+    }
+  }, [deliver, phase])
+
+  const cancelSystemFields = useCallback(() => {
+    setPhase((current) => (current.kind === 'confirmingSystemFields' ? IDLE : current))
+  }, [])
+
+  return { phase, isBusy, submit, confirmSystemFields, cancelSystemFields }
+}

package/src/forms/use-form-tabs.ts

@@ -0,0 +1,89 @@
+'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 { useEffect, useMemo, useState } from 'react'
+
+import type { TabDefinition, TabSetDefinition } from '@byline/core'
+
+import { useFormContext } from './form-context'
+
+/** One tab set, resolved against live form data and current errors. */
+export interface ResolvedTabSet {
+  /** Tabs whose `condition` is satisfied, in declaration order. */
+  visibleTabs: TabDefinition[]
+  /** The tab that should render, after falling back off a hidden selection. */
+  activeTabName: string
+  activeTab: TabDefinition | undefined
+  /** Error count per tab name, for the tab bar's badges. */
+  errorCounts: Record<string, number> | undefined
+}
+
+export interface UseFormTabsResult {
+  resolve: (set: TabSetDefinition) => ResolvedTabSet
+  errorCountsBySet: Record<string, Record<string, number>>
+}
+
+/**
+ * Tab visibility, per-tab error counts, and fallback when the selected tab is
+ * hidden.
+ *
+ * It deliberately does **not** own the selection. `FormRenderer` lifts that
+ * above the keyed `FormProvider` so the editor's tab choices survive the
+ * remount a locale change triggers; a hook living inside that subtree would
+ * lose them on every switch. The selection arrives as `activeTabBySet` and
+ * changes are reported upward.
+ */
+export function useFormTabs(
+  fieldToTabPath: Map<string, { tabSetName: string; tabName: string }>,
+  activeTabBySet: Record<string, string>
+): UseFormTabsResult {
+  const { errors: initialErrors, subscribeErrors, subscribeMeta, getFieldValues } = useFormContext()
+
+  const [errors, setErrors] = useState(initialErrors)
+  useEffect(() => {
+    return subscribeErrors((newErrors) => setErrors(newErrors))
+  }, [subscribeErrors])
+
+  // Live form data, so TabDefinition.condition re-evaluates per keystroke.
+  const [formData, setFormData] = useState<Record<string, any>>(() => getFieldValues())
+  useEffect(() => {
+    return subscribeMeta(() => setFormData(getFieldValues()))
+  }, [subscribeMeta, getFieldValues])
+
+  // Per-tab-set error counts: { [tabSetName]: { [tabName]: count } }.
+  // Each tab bar consumes its own slice.
+  const errorCountsBySet = useMemo<Record<string, Record<string, number>>>(() => {
+    const result: Record<string, Record<string, number>> = {}
+    for (const err of errors) {
+      const path = fieldToTabPath.get(err.field)
+      if (!path) continue
+      result[path.tabSetName] ??= {}
+      result[path.tabSetName]![path.tabName] = (result[path.tabSetName]?.[path.tabName] ?? 0) + 1
+    }
+    return result
+  }, [errors, fieldToTabPath])
+
+  const resolve = (set: TabSetDefinition): ResolvedTabSet => {
+    const visibleTabs = set.tabs.filter((tab) => !tab.condition || tab.condition(formData))
+    const requested = activeTabBySet[set.name] ?? ''
+    const activeTabName =
+      visibleTabs.length > 0 && !visibleTabs.some((t) => t.name === requested)
+        ? (visibleTabs[0]?.name ?? requested)
+        : requested
+    return {
+      visibleTabs,
+      activeTabName,
+      activeTab: visibleTabs.find((t) => t.name === activeTabName),
+      errorCounts: errorCountsBySet[set.name],
+    }
+  }
+
+  return { resolve, errorCountsBySet }
+}

package/src/presentation/tab-dom-ids.test.tsx

@@ -0,0 +1,153 @@
+/**
+ * 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 { act } from 'react'
+
+import type { AdminResourceConfig, Field } from '@byline/core'
+import { defineAdminConfig } from '@byline/core'
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { BylineFieldServicesProvider } from '../fields/field-services-context'
+import { FormProvider } from '../forms/form-context'
+import { FormLayout } from '../forms/form-layout'
+
+// Deliberately not the `;(globalThis as any)` idiom used elsewhere in this
+// suite: Biome's import sorting can move an import across that leading
+// semicolon, and without semicolons the result parses as a call on the import.
+const globalWithAct = globalThis as any
+globalWithAct.IS_REACT_ACT_ENVIRONMENT = true
+
+defineAdminConfig({
+  i18n: {
+    admin: { defaultLocale: 'en', locales: ['en'] },
+    content: { defaultLocale: 'en', locales: ['en'] },
+  },
+  collections: [
+    {
+      path: 'pages',
+      labels: { singular: 'Page', plural: 'Pages' },
+      fields: [{ name: 'title', label: 'Title', type: 'text' }],
+    },
+  ],
+  slugifier: (value: string) => value.toLowerCase().trim().replace(/\s+/g, '-'),
+})
+
+const fields: Field[] = [
+  { name: 'title', label: 'Title', type: 'text' },
+  { name: 'seoTitle', label: 'SEO title', type: 'text' },
+]
+
+/**
+ * Both forms declare a tab set under the same name, which is the ordinary case:
+ * two forms over one collection share its admin configuration verbatim.
+ */
+const adminConfig = {
+  layout: { main: ['main'] },
+  tabSets: [
+    {
+      name: 'main',
+      tabs: [
+        { name: 'general', label: 'General', fields: ['title'] },
+        { name: 'seo', label: 'SEO', fields: ['seoTitle'] },
+      ],
+    },
+  ],
+} as unknown as AdminResourceConfig
+
+let container: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => {
+    root.unmount()
+  })
+  container.remove()
+})
+
+const Form = ({ name }: { name: string }) => (
+  <form aria-label={name}>
+    <FormProvider initialData={{ fields: {} }} collectionPath="pages">
+      <FormLayout
+        fields={fields}
+        adminConfig={adminConfig}
+        activeTabBySet={{ main: 'general' }}
+        onTabChange={() => {}}
+      />
+    </FormProvider>
+  </form>
+)
+
+const renderTwoForms = () => {
+  act(() => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        <BylineFieldServicesProvider
+          services={
+            {
+              getCollectionDocuments: async () => ({ docs: [], total: 0 }),
+              uploadField: async () => ({}),
+            } as any
+          }
+        >
+          <Form name="parent" />
+          <Form name="child" />
+        </BylineFieldServicesProvider>
+      </I18nProvider>
+    )
+  })
+}
+
+describe('tab DOM ids across concurrently mounted forms', () => {
+  it('keeps tab trigger ids distinct across two forms with a "main" tab set', () => {
+    renderTwoForms()
+
+    const triggers = Array.from(container.querySelectorAll('[role="tab"]')).map((n) => n.id)
+
+    expect(triggers.length).toBeGreaterThan(0)
+    expect(triggers.every((id) => id !== '')).toBe(true)
+    expect(new Set(triggers).size).toBe(triggers.length)
+  })
+
+  it('labels each tab panel from a trigger in its own form', () => {
+    renderTwoForms()
+
+    const panels = Array.from(container.querySelectorAll('[role="tabpanel"]'))
+    expect(panels).toHaveLength(2)
+
+    for (const panel of panels) {
+      const owner = document.getElementById(panel.getAttribute('aria-labelledby') as string)
+      expect(owner).not.toBeNull()
+      // Resolution is document-wide, so an unscoped id points the second form's
+      // panel at the first form's trigger.
+      expect(owner?.closest('form')).toBe(panel.closest('form'))
+    }
+  })
+
+  it('keeps panel ids distinct so aria-controls cannot cross forms', () => {
+    renderTwoForms()
+
+    const panelIds = Array.from(container.querySelectorAll('[role="tabpanel"]')).map((n) => n.id)
+
+    expect(panelIds.every((id) => id !== '')).toBe(true)
+    expect(new Set(panelIds).size).toBe(panelIds.length)
+  })
+})

package/src/presentation/tabs.test.tsx

@@ -51,7 +51,7 @@ import { AdminTabs } from './tabs'
  * report overflow. Drive the two widths the component reads off its stable
  * override handles.
  */
-const layout = { container: 0, row: 0 }
+const layout = { container: 0, row: 0, rowReads: 0 }
 
 function installPointerStubs() {
   // jsdom implements neither pointer capture nor scrollTo; the component guards
@@ -96,7 +96,11 @@ function installLayoutStubs() {
   Object.defineProperty(HTMLElement.prototype, 'scrollWidth', {
     configurable: true,
     get(this: HTMLElement) {
-      return this.classList.contains('byline-admin-tablist') ? layout.row : 0
+      if (!this.classList.contains('byline-admin-tablist')) return 0
+      // Counted, not just answered: in a browser this getter is what forces
+      // the synchronous layout, so the count is the cost under test.
+      layout.rowReads += 1
+      return layout.row
     },
   })
 }
@@ -135,6 +139,7 @@ describe('AdminTabs', () => {
     observed.length = 0
     layout.container = 1000
     layout.row = 400
+    layout.rowReads = 0
     onChange = vi.fn()
     container = document.createElement('div')
     document.body.appendChild(container)
@@ -367,6 +372,48 @@ describe('AdminTabs', () => {
     expect(observedClasses.some((c) => c.includes('byline-admin-tabs '))).toBe(true)
   })
 
+  /**
+   * The tab array arrives with a fresh identity on every render of the form
+   * layout: `useFormTabs.resolve()` filters `set.tabs` each time it is called,
+   * and the live form data it filters against updates per keystroke. Keying the
+   * measurement effect on that identity made every unrelated render tear down
+   * the ResizeObserver and force a synchronous layout read — measured in Chrome
+   * against a seeded `pages` document as one forced read per keystroke, and two
+   * on an editor mount.
+   */
+  it('does not re-measure when the parent re-renders with an equal tab array', () => {
+    render()
+    const readsAfterMount = layout.rowReads
+    const observedAfterMount = observed.length
+
+    render({ tabs: TABS.map((tab) => ({ ...tab })) })
+
+    expect(layout.rowReads).toBe(readsAfterMount)
+    expect(observed.length).toBe(observedAfterMount)
+  })
+
+  it('re-measures when a tab is added or removed', () => {
+    render()
+    const readsAfterMount = layout.rowReads
+
+    render({ tabs: [...TABS, { name: 'indexing', label: 'Indexing' }] })
+
+    expect(layout.rowReads).toBeGreaterThan(readsAfterMount)
+  })
+
+  /**
+   * A label carries the width, so a translation change has to re-measure even
+   * though the tab names are untouched.
+   */
+  it('re-measures when a label changes', () => {
+    render()
+    const readsAfterMount = layout.rowReads
+
+    render({ tabs: TABS.map((tab, i) => (i === 0 ? { ...tab, label: 'Détails' } : tab)) })
+
+    expect(layout.rowReads).toBeGreaterThan(readsAfterMount)
+  })
+
   // ─── Drag-to-scroll (desktop) ─────────────────────────────────────────
 
   const viewport = () =>

package/src/presentation/tabs.tsx

@@ -124,6 +124,16 @@ export const AdminTabs = ({
 
   const [strip, setStrip] = useState<StripState>(INITIAL_STRIP_STATE)
 
+  // The measurement effect is keyed on what the tabs *are*, not on the identity
+  // of the array carrying them. A form layout rebuilds that array on every
+  // render — `useFormTabs.resolve()` filters `set.tabs` against live form data,
+  // so a new array arrives per keystroke — and re-running the effect for one of
+  // those renders would disconnect the observer and force a synchronous layout
+  // read on a tree the browser has just invalidated. Labels are part of the key
+  // because the label is what carries the width: a translation change has to
+  // re-measure, a keystroke elsewhere in the form does not.
+  const tabsKey = tabs.map((tab) => `${tab.name}:${tab.label}`).join('\u0000')
+
   const measure = useCallback(() => {
     const container = containerRef.current
     const row = rowRef.current
@@ -162,7 +172,7 @@ export const AdminTabs = ({
     observer.observe(container)
     observer.observe(row)
     return () => observer.disconnect()
-  }, [measure, tabs])
+  }, [measure, tabsKey])
 
   const reveal = useCallback((name: string) => {
     const viewport = viewportRef.current

package/src/react.ts

@@ -81,10 +81,12 @@ export * from './widgets/status-badge/status-badge.js'
 // Field-side service contract types.
 export type {
   BylineFieldServices,
+  CanCreateInCollectionFn,
   CollectionListDoc,
   CollectionListParams,
   CollectionListResponse,
   GetCollectionDocumentsFn,
+  GetCreateDocumentUrlFn,
   GetTreeAncestorsFn,
   GetTreeParentFn,
   PlaceTreeNodeFn,