@byline/admin 6.1.0 → 6.2.1

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-strip-drag.test.node.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 { describe, expect, it } from 'vitest'
+
+import {
+  advanceDrag,
+  CLICK_SUPPRESSION_MS,
+  DRAG_THRESHOLD_PX,
+  shouldStartDrag,
+  shouldSuppressClick,
+} from './tab-strip-drag'
+
+describe('shouldStartDrag', () => {
+  const mouseDown = { pointerType: 'mouse', button: 0, overflowing: true }
+
+  it('starts on a primary mouse button over an overflowing strip', () => {
+    expect(shouldStartDrag(mouseDown)).toBe(true)
+  })
+
+  /**
+   * Touch already scrolls the viewport natively, with momentum and rubber-band
+   * behaviour no hand-rolled drag reproduces. Intercepting it would replace a
+   * good interaction with a worse one.
+   */
+  it('leaves touch to the browser', () => {
+    expect(shouldStartDrag({ ...mouseDown, pointerType: 'touch' })).toBe(false)
+  })
+
+  it('leaves pen to the browser', () => {
+    expect(shouldStartDrag({ ...mouseDown, pointerType: 'pen' })).toBe(false)
+  })
+
+  it('ignores the middle button', () => {
+    expect(shouldStartDrag({ ...mouseDown, button: 1 })).toBe(false)
+  })
+
+  it('ignores the secondary button, which opens the context menu', () => {
+    expect(shouldStartDrag({ ...mouseDown, button: 2 })).toBe(false)
+  })
+
+  it('does nothing when the strip has no overflow to scroll', () => {
+    expect(shouldStartDrag({ ...mouseDown, overflowing: false })).toBe(false)
+  })
+})
+
+describe('advanceDrag', () => {
+  const origin = { pointerX: 200, scrollLeft: 100 }
+  const idle = { origin, dragging: false }
+  const maxScroll = 400
+
+  /**
+   * Below the threshold the gesture is still a click. Scrolling here would
+   * make every click on a tab nudge the strip, and suppressing the click that
+   * follows would stop tabs selecting at all.
+   */
+  it('does not scroll before the threshold is crossed', () => {
+    const next = advanceDrag(idle, 200 + (DRAG_THRESHOLD_PX - 1), maxScroll)
+
+    expect(next).toEqual({ dragging: false, scrollLeft: null })
+  })
+
+  it('begins dragging once the pointer reaches the threshold', () => {
+    const next = advanceDrag(idle, 200 + DRAG_THRESHOLD_PX, maxScroll)
+
+    expect(next.dragging).toBe(true)
+  })
+
+  it('crosses the threshold in either direction', () => {
+    const next = advanceDrag(idle, 200 - DRAG_THRESHOLD_PX, maxScroll)
+
+    expect(next.dragging).toBe(true)
+  })
+
+  /** Dragging right pulls the content right, so the scroll offset decreases. */
+  it('scrolls the content with the pointer when dragged right', () => {
+    const next = advanceDrag({ origin, dragging: true }, 230, maxScroll)
+
+    expect(next.scrollLeft).toBe(70)
+  })
+
+  it('scrolls the content with the pointer when dragged left', () => {
+    const next = advanceDrag({ origin, dragging: true }, 170, maxScroll)
+
+    expect(next.scrollLeft).toBe(130)
+  })
+
+  it('clamps at the start of the strip', () => {
+    const next = advanceDrag({ origin, dragging: true }, 400, maxScroll)
+
+    expect(next.scrollLeft).toBe(0)
+  })
+
+  it('clamps at the end of the strip', () => {
+    const next = advanceDrag({ origin, dragging: true }, -400, maxScroll)
+
+    expect(next.scrollLeft).toBe(maxScroll)
+  })
+
+  /**
+   * A drag that wanders back past the threshold is still a drag — otherwise
+   * returning to the origin would hand the gesture back to the click handler
+   * and select whichever tab the pointer happened to end on.
+   */
+  it('stays a drag once it has started, even back within the threshold', () => {
+    const next = advanceDrag({ origin, dragging: true }, 201, maxScroll)
+
+    expect(next).toEqual({ dragging: true, scrollLeft: 99 })
+  })
+})
+
+describe('shouldSuppressClick', () => {
+  it('lets a click through when no drag has happened', () => {
+    expect(shouldSuppressClick(null, 1000)).toBe(false)
+  })
+
+  /** The click the browser synthesises at the end of a drag. */
+  it('suppresses the click that immediately follows a drag', () => {
+    expect(shouldSuppressClick(1000, 1000)).toBe(true)
+  })
+
+  it('suppresses a click just inside the window', () => {
+    expect(shouldSuppressClick(1000, 1000 + CLICK_SUPPRESSION_MS - 1)).toBe(true)
+  })
+
+  /**
+   * The suppression expires on its own rather than waiting to be consumed.
+   * A drag released outside the strip produces no click at all, and a flag
+   * left armed would swallow the reader's next deliberate click on a tab.
+   */
+  it('expires rather than waiting for a click that may never come', () => {
+    expect(shouldSuppressClick(1000, 1000 + CLICK_SUPPRESSION_MS)).toBe(false)
+  })
+
+  it('has long since expired by the time of a deliberate later click', () => {
+    expect(shouldSuppressClick(1000, 3000)).toBe(false)
+  })
+})

package/src/presentation/tab-strip-drag.ts

@@ -0,0 +1,114 @@
+/**
+ * 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
+ */
+
+/**
+ * Pure state for click-and-drag scrolling of the tab strip.
+ *
+ * The DOM plumbing — pointer capture, the click suppression, the cursor —
+ * lives in `tabs.tsx`; the rules it follows are here so they can be tested
+ * without a pointer.
+ */
+
+/**
+ * How far the pointer must travel before the gesture stops being a click and
+ * becomes a drag.
+ *
+ * Without a threshold every click on a tab would nudge the strip by a pixel or
+ * two, and the click suppression that follows a drag would swallow the very
+ * clicks that select tabs.
+ */
+export const DRAG_THRESHOLD_PX = 5
+
+/**
+ * How long after a drag a click is treated as that drag's own click.
+ *
+ * A window rather than a consume-once flag, because the click is not
+ * guaranteed to arrive: a drag released outside the strip produces none, and
+ * a flag left armed would swallow the reader's next deliberate click on a tab.
+ * Far longer than the browser's synthetic click takes to arrive, far shorter
+ * than anyone can release and deliberately click again.
+ */
+export const CLICK_SUPPRESSION_MS = 100
+
+/** Where a gesture began. An internal part of `DragState`, not a public type. */
+interface DragOrigin {
+  /** Pointer x at the moment the button went down. */
+  pointerX: number
+  /** The viewport's scroll offset at that same moment. */
+  scrollLeft: number
+}
+
+export interface DragState {
+  origin: DragOrigin
+  /** Whether the threshold has already been crossed. */
+  dragging: boolean
+}
+
+export interface DragAdvance {
+  dragging: boolean
+  /** The offset to scroll to, or `null` while the gesture is still a click. */
+  scrollLeft: number | null
+}
+
+/**
+ * Whether a `pointerdown` should begin a potential drag.
+ *
+ * Mouse only. Touch and pen already scroll the viewport natively, with
+ * momentum and rubber-banding that a hand-rolled drag does not reproduce, so
+ * taking the gesture over would trade a good interaction for a worse one.
+ */
+export function shouldStartDrag({
+  pointerType,
+  button,
+  overflowing,
+}: {
+  pointerType: string
+  button: number
+  overflowing: boolean
+}): boolean {
+  if (pointerType !== 'mouse') return false
+  // Primary button only: the middle button is paste-scroll on some platforms
+  // and the secondary opens the context menu.
+  if (button !== 0) return false
+  return overflowing
+}
+
+/**
+ * Advance a gesture given the pointer's current x.
+ *
+ * Returns `scrollLeft: null` while the pointer is still within the threshold,
+ * so the caller leaves the viewport alone and lets the click through.
+ */
+export function advanceDrag(
+  { origin, dragging }: DragState,
+  pointerX: number,
+  maxScroll: number
+): DragAdvance {
+  const delta = pointerX - origin.pointerX
+
+  // Once a drag, always a drag: a gesture that wanders back inside the
+  // threshold must not hand itself back to the click handler and select
+  // whichever tab the pointer happens to be over.
+  const isDragging = dragging || Math.abs(delta) >= DRAG_THRESHOLD_PX
+  if (isDragging === false) return { dragging: false, scrollLeft: null }
+
+  // Subtracted, not added: the content follows the pointer, so dragging right
+  // reveals what is to the left and the offset falls.
+  const next = origin.scrollLeft - delta
+
+  return { dragging: true, scrollLeft: Math.min(Math.max(next, 0), maxScroll) }
+}
+
+/**
+ * Whether a click arriving now belongs to a drag that has just ended, and
+ * should therefore not reach the tab underneath.
+ */
+export function shouldSuppressClick(dragEndedAt: number | null, now: number): boolean {
+  if (dragEndedAt == null) return false
+  return now - dragEndedAt < CLICK_SUPPRESSION_MS
+}