@byline/ui 0.9.3

package/src/forms/navigation-guard.tsx

@@ -0,0 +1,98 @@
+/**
+ * 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
+ */
+
+/**
+ * Framework-agnostic navigation guard adapter.
+ *
+ * Different router frameworks (TanStack Router, Next.js, React Router, etc.)
+ * each have their own mechanism for blocking navigation when a form has unsaved
+ * changes.  This module defines a common interface so that `FormRenderer` can
+ * remain framework-independent — the consuming application injects the
+ * appropriate adapter via a prop or React context.
+ */
+
+import { createContext, useContext, useEffect } from 'react'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** The result returned by a `UseNavigationGuard` hook. */
+export interface NavigationGuardResult {
+  /** Whether a navigation attempt is currently being blocked (show confirmation UI). */
+  isBlocked: boolean
+  /** Cancel the pending navigation — stay on the current page. */
+  stay: () => void
+  /** Confirm the pending navigation — leave the page. */
+  proceed: () => void
+}
+
+/**
+ * A hook that blocks in-app navigation and (optionally) browser unload when
+ * `shouldBlock` is `true`.
+ *
+ * Each framework adapter implements this signature.
+ */
+export type UseNavigationGuard = (shouldBlock: boolean) => NavigationGuardResult
+
+// ---------------------------------------------------------------------------
+// Default (no-op) implementation  — browser `beforeunload` only
+// ---------------------------------------------------------------------------
+
+/**
+ * Fallback navigation guard that only handles the browser's native
+ * `beforeunload` event.  In-app (client-side) route changes are **not**
+ * intercepted — `isBlocked` will never become `true`.
+ *
+ * This is used when no framework-specific adapter has been provided.
+ */
+export const useBeforeUnloadGuard: UseNavigationGuard = (shouldBlock) => {
+  useEffect(() => {
+    if (!shouldBlock) return
+    const handler = (e: BeforeUnloadEvent) => {
+      e.preventDefault()
+    }
+    window.addEventListener('beforeunload', handler)
+    return () => window.removeEventListener('beforeunload', handler)
+  }, [shouldBlock])
+
+  return { isBlocked: false, stay: () => {}, proceed: () => {} }
+}
+
+// ---------------------------------------------------------------------------
+// React context — allows setting the adapter once at the app shell level
+// ---------------------------------------------------------------------------
+
+const NavigationGuardContext = createContext<UseNavigationGuard>(useBeforeUnloadGuard)
+
+/**
+ * Provide a framework-specific `UseNavigationGuard` hook to all descendant
+ * `FormRenderer` instances.
+ *
+ * ```tsx
+ * import { NavigationGuardProvider } from './navigation-guard'
+ * import { useTanStackNavigationGuard } from './tanstack-navigation-guard'
+ *
+ * function App() {
+ *   return (
+ *     <NavigationGuardProvider value={useTanStackNavigationGuard}>
+ *       <Outlet />
+ *     </NavigationGuardProvider>
+ *   )
+ * }
+ * ```
+ */
+export const NavigationGuardProvider = NavigationGuardContext.Provider
+
+/**
+ * Consume the current `UseNavigationGuard` hook from context.
+ * Falls back to `useBeforeUnloadGuard` when no provider is present.
+ */
+export const useNavigationGuardAdapter = (): UseNavigationGuard => {
+  return useContext(NavigationGuardContext)
+}

package/src/forms/path-widget.module.css

@@ -0,0 +1,41 @@
+/**
+ * PathWidget — system-managed `documentVersions.path` form widget.
+ *
+ * Override handles:
+ *   .byline-form-path                  — wrapper div
+ *   .byline-form-path-header           — label + regenerate-button row
+ *   .byline-form-path-regenerate       — regenerate-link button
+ *   .byline-form-path-sr-only          — visually-hidden screen-reader hint
+ */
+
+.header,
+:global(.byline-form-path-header) {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-8);
+}
+
+.regenerate,
+:global(.byline-form-path-regenerate) {
+  background: none;
+  border: none;
+  padding: 0;
+  color: inherit;
+  font-size: 0.8rem;
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.sr-only,
+:global(.byline-form-path-sr-only) {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/forms/path-widget.test.tsx

@@ -0,0 +1,217 @@
+/**
+ * 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 { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+// Lightweight uikit stubs — we don't care about the visual rendering, only
+// that the Input forwards props and the Label renders its htmlFor.
+vi.mock('@infonomic/uikit/react', () => ({
+  Label: ({ id, htmlFor, label }: { id?: string; htmlFor?: string; label?: string }) => (
+    <label id={id} htmlFor={htmlFor}>
+      {label}
+    </label>
+  ),
+  Input: ({
+    id,
+    name,
+    value,
+    placeholder,
+    onChange,
+    helpText,
+    ...rest
+  }: {
+    id?: string
+    name?: string
+    value?: string
+    placeholder?: string
+    onChange?: (e: { target: { value: string } }) => void
+    helpText?: string
+    [key: string]: any
+  }) => (
+    <>
+      <input
+        id={id}
+        name={name}
+        value={value ?? ''}
+        placeholder={placeholder}
+        onChange={onChange}
+        {...rest}
+      />
+      {helpText ? <span data-testid="help-text">{helpText}</span> : null}
+    </>
+  ),
+}))
+
+// Mutable mocks controlled per-test via the setFixture helper below.
+const fixture: {
+  systemPath: string | null
+  sourceValue: unknown
+  setSystemPath: ReturnType<typeof vi.fn>
+} = {
+  systemPath: null,
+  sourceValue: '',
+  setSystemPath: vi.fn(),
+}
+
+vi.mock('./form-context', () => ({
+  useFormContext: () => ({ setSystemPath: fixture.setSystemPath }),
+  useSystemPath: () => fixture.systemPath,
+  useFieldValue: () => fixture.sourceValue,
+}))
+
+// Import AFTER the mocks so PathWidget picks them up.
+// biome-ignore lint/correctness/useImportExtensions: webapp TS resolves via tsconfig paths
+import { PathWidget } from './path-widget'
+
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+interface Fixture {
+  systemPath?: string | null
+  sourceValue?: unknown
+}
+
+function setFixture(next: Fixture = {}) {
+  fixture.systemPath = next.systemPath ?? null
+  fixture.sourceValue = next.sourceValue ?? ''
+  fixture.setSystemPath = vi.fn()
+}
+
+describe('PathWidget', () => {
+  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 render = (
+    props: Partial<{
+      useAsPath: string | undefined
+      mode: 'create' | 'edit'
+    }> = {}
+  ) => {
+    act(() => {
+      root.render(
+        <PathWidget
+          useAsPath={props.useAsPath ?? 'title'}
+          collectionPath="pages"
+          defaultLocale="en"
+          mode={props.mode ?? 'create'}
+        />
+      )
+    })
+  }
+
+  const getInput = () => container.querySelector('#system-path') as HTMLInputElement
+
+  it('shows the live-derived preview as placeholder when creating with an empty override', () => {
+    setFixture({ systemPath: null, sourceValue: 'Hello World' })
+    render({ mode: 'create' })
+
+    const input = getInput()
+    expect(input).toBeTruthy()
+    expect(input.value).toBe('')
+    expect(input.getAttribute('placeholder')).toBe('Will be saved as "hello-world"')
+  })
+
+  it('shows the persisted path in edit mode (no placeholder preview)', () => {
+    setFixture({ systemPath: 'existing-path', sourceValue: 'Hello World' })
+    render({ mode: 'edit' })
+
+    const input = getInput()
+    expect(input.value).toBe('existing-path')
+    // livePreview === 'hello-world' differs from persisted 'existing-path',
+    // so the regenerate button is rendered.
+    const regenerate = container.querySelector('button')
+    expect(regenerate).toBeTruthy()
+    expect(regenerate?.textContent).toContain('Regenerate from title')
+  })
+
+  it('"Regenerate" writes the live preview into the systemPath slot', () => {
+    setFixture({ systemPath: 'stale-path', sourceValue: 'Brand New Title' })
+    render({ mode: 'edit' })
+
+    const regenerate = container.querySelector('button') as HTMLButtonElement
+    expect(regenerate).toBeTruthy()
+
+    act(() => {
+      regenerate.click()
+    })
+
+    expect(fixture.setSystemPath).toHaveBeenCalledWith('brand-new-title')
+  })
+
+  it('clearing the input reverts the slot to null (sticky-from-previous)', () => {
+    setFixture({ systemPath: 'my-path', sourceValue: 'My Path' })
+    render({ mode: 'edit' })
+
+    const input = getInput()
+    act(() => {
+      const setter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        'value'
+      )?.set
+      setter?.call(input, '')
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+    })
+
+    expect(fixture.setSystemPath).toHaveBeenCalledWith(null)
+  })
+
+  it('typing a non-empty value writes a string override', () => {
+    setFixture({ systemPath: null, sourceValue: 'Anything' })
+    render({ mode: 'create' })
+
+    const input = getInput()
+    act(() => {
+      const setter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        'value'
+      )?.set
+      setter?.call(input, 'custom-slug')
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+    })
+
+    expect(fixture.setSystemPath).toHaveBeenCalledWith('custom-slug')
+  })
+
+  it('links the input to an sr-only description via aria-describedby', () => {
+    setFixture({ systemPath: null, sourceValue: 'Hi' })
+    render({ mode: 'create' })
+
+    const input = getInput()
+    expect(input.getAttribute('aria-describedby')).toBe('system-path-description')
+    const description = container.querySelector('#system-path-description')
+    expect(description).toBeTruthy()
+    expect(description?.textContent).toContain('System-managed URL path')
+  })
+
+  it('does not render the Regenerate button when livePreview equals systemPath', () => {
+    setFixture({ systemPath: 'hello-world', sourceValue: 'Hello World' })
+    render({ mode: 'edit' })
+    expect(container.querySelector('button')).toBeNull()
+  })
+
+  it('does not render the Regenerate button when there is no useAsPath', () => {
+    setFixture({ systemPath: 'whatever', sourceValue: '' })
+    render({ mode: 'edit', useAsPath: undefined })
+    expect(container.querySelector('button')).toBeNull()
+  })
+})

package/src/forms/path-widget.tsx

@@ -0,0 +1,141 @@
+/**
+ * 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, useMemo } from 'react'
+
+import { slugify } from '@byline/core'
+import { Input, Label } from '@infonomic/uikit/react'
+import cx from 'classnames'
+
+import { useFieldValue, useFormContext, useSystemPath } from './form-context'
+import styles from './path-widget.module.css'
+
+/**
+ * Coerce an arbitrary source-field value (string, Date, or other) into
+ * a string suitable for slugification. Mirrors the lifecycle's coercion
+ * so the live preview matches what the server will store.
+ */
+function coerceToString(value: unknown): string {
+  if (value == null) return ''
+  if (value instanceof Date) return value.toISOString()
+  return String(value)
+}
+
+export interface PathWidgetProps {
+  /** The collection's `useAsPath` source field name, when configured. */
+  useAsPath: string | undefined
+  /** Collection path, forwarded to the slugifier as context. */
+  collectionPath: string
+  /** Default content locale, forwarded to the slugifier as context. */
+  defaultLocale: string
+  /** `'create'` shows the live derived preview as placeholder text. */
+  mode: 'create' | 'edit'
+}
+
+/**
+ * System-managed `documentVersions.path` widget.
+ *
+ * Displays the current persisted/overridden path as an editable input.
+ * In create mode, when the user hasn't supplied an override, the input
+ * shows the live-derived preview (slugified `useAsPath` source field) as
+ * a placeholder so the user sees what will be saved. The "Regenerate"
+ * action explicitly writes the current live preview into the override
+ * slot so the user can re-anchor a path against the source field after
+ * editing the title.
+ *
+ * Stable override handles: `.byline-form-path`, `.byline-form-path-header`,
+ * `.byline-form-path-regenerate`.
+ */
+export const PathWidget = ({ useAsPath, collectionPath, defaultLocale, mode }: PathWidgetProps) => {
+  const { setSystemPath } = useFormContext()
+  const systemPath = useSystemPath()
+  const sourceValue = useFieldValue<unknown>(useAsPath ?? '')
+
+  // Live preview — what the server would derive from the current source
+  // field value if no override were set. Used as placeholder in create
+  // mode and as the target of the "Regenerate" action.
+  const livePreview = useMemo(() => {
+    if (!useAsPath) return ''
+    const asString = coerceToString(sourceValue)
+    if (asString.length === 0) return ''
+    return slugify(asString, { locale: defaultLocale, collectionPath })
+  }, [useAsPath, sourceValue, defaultLocale, collectionPath])
+
+  const inputValue = systemPath ?? ''
+
+  const handleChange = useCallback(
+    (next: string) => {
+      // Empty string clears the override — server falls back to derive
+      // (create) or sticky (update).
+      setSystemPath(next.length === 0 ? null : next)
+    },
+    [setSystemPath]
+  )
+
+  const handleRegenerate = useCallback(() => {
+    if (livePreview.length > 0) {
+      setSystemPath(livePreview)
+    }
+  }, [livePreview, setSystemPath])
+
+  // Validate live: if the typed value differs from its slugified form,
+  // surface an inline hint without blocking input (mirrors the previous
+  // field-hook advisory behaviour).
+  const formatted = useMemo(() => {
+    if (inputValue.length === 0) return ''
+    return slugify(inputValue, { locale: defaultLocale, collectionPath })
+  }, [inputValue, defaultLocale, collectionPath])
+
+  const hint =
+    inputValue.length > 0 && formatted !== inputValue ? `Suggested: "${formatted}"` : undefined
+
+  const placeholder =
+    mode === 'create' && livePreview.length > 0 ? `Will be saved as "${livePreview}"` : undefined
+
+  // Screen-reader description. The input's base purpose ("System-managed
+  // URL path") plus whichever of the visible hints (placeholder preview
+  // in create mode, "Suggested" validation hint) currently applies. The
+  // visible helpText/placeholder cover sighted users; this element makes
+  // the same information addressable via aria-describedby for AT.
+  const srDescription = ['System-managed URL path for this document.', placeholder, hint]
+    .filter(Boolean)
+    .join(' ')
+
+  return (
+    <div className="byline-form-path">
+      <div className={cx('byline-form-path-header', styles.header)}>
+        <Label id="system-path-label" htmlFor="system-path" label="Path" />
+        {useAsPath && livePreview.length > 0 && livePreview !== systemPath && (
+          <button
+            type="button"
+            onClick={handleRegenerate}
+            className={cx('byline-form-path-regenerate', styles.regenerate)}
+            aria-label={`Regenerate path from ${useAsPath} field`}
+          >
+            Regenerate from {useAsPath}
+          </button>
+        )}
+      </div>
+      <Input
+        id="system-path"
+        name="__systemPath__"
+        value={inputValue}
+        placeholder={placeholder}
+        onChange={(e) => handleChange(e.target.value)}
+        helpText={hint}
+        aria-describedby="system-path-description"
+      />
+      <span
+        id="system-path-description"
+        className={cx('byline-form-path-sr-only', styles['sr-only'])}
+      >
+        {srDescription}
+      </span>
+    </div>
+  )
+}

package/src/forms/upload-executor.ts

@@ -0,0 +1,190 @@
+/**
+ * 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
+ */
+
+/**
+ * Upload Executor
+ *
+ * Handles batch execution of pending file uploads at form submission time.
+ * This enables "deferred uploads" — files are selected/previewed immediately
+ * but only uploaded when the user clicks Save.
+ */
+
+import type { StoredFileValue } from '@byline/core'
+
+import type { UploadFieldFn } from '../services/field-services-types'
+import type { PendingUpload } from './form-context'
+
+export interface UploadResult {
+  fieldPath: string
+  success: boolean
+  storedFile?: StoredFileValue
+  error?: string
+}
+
+export interface ExecuteUploadsResult {
+  /** All upload results (both successful and failed) */
+  results: UploadResult[]
+  /** Map of field path to StoredFileValue for successful uploads */
+  successful: Map<string, StoredFileValue>
+  /** Map of field path to error message for failed uploads */
+  errors: Map<string, string>
+  /** Whether all uploads succeeded */
+  allSucceeded: boolean
+}
+
+/**
+ * Execute all pending uploads sequentially.
+ * Returns a result object with successful uploads and any errors.
+ *
+ * @param pendingUploads - Map of field path to PendingUpload
+ * @param uploadField - Host-provided upload transport (resolved via
+ *                         `useBylineFieldServices()` in the calling React tree)
+ * @returns Promise resolving to ExecuteUploadsResult
+ */
+export async function executeUploads(
+  pendingUploads: Map<string, PendingUpload>,
+  uploadField: UploadFieldFn
+): Promise<ExecuteUploadsResult> {
+  const results: UploadResult[] = []
+  const successful = new Map<string, StoredFileValue>()
+  const errors = new Map<string, string>()
+
+  for (const [fieldPath, upload] of pendingUploads.entries()) {
+    const formData = new FormData()
+    formData.append('file', upload.file)
+    // Tell the server which upload-capable field this file belongs to.
+    // With per-field upload config a collection can have multiple
+    // image/file fields, each with its own constraints; the server's
+    // unique-default fallback covers the single-field case but rejects
+    // multi-field collections without an explicit selector.
+    formData.append('field', uploadFieldName(fieldPath))
+
+    try {
+      // Pass createDocument=false — we're uploading for an embedded field,
+      // the form's save action handles document creation/update.
+      const result = await uploadField(upload.collectionPath, formData, false)
+
+      results.push({
+        fieldPath,
+        success: true,
+        storedFile: result.storedFile,
+      })
+      successful.set(fieldPath, result.storedFile)
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Upload failed'
+      results.push({
+        fieldPath,
+        success: false,
+        error: message,
+      })
+      errors.set(fieldPath, message)
+    }
+  }
+
+  return {
+    results,
+    successful,
+    errors,
+    allSucceeded: errors.size === 0,
+  }
+}
+
+/**
+ * Extract the leaf field name from a `fieldPath`. Top-level upload
+ * fields (`'image'`, `'avatar'`) pass through unchanged; nested paths
+ * (`'profile.avatar'`) reduce to their last segment, since the
+ * server-side resolver matches against top-level field names today.
+ * Nested upload fields would need a richer transport selector when
+ * they land — the host resolver is the natural place to extend.
+ */
+function uploadFieldName(fieldPath: string): string {
+  const dot = fieldPath.lastIndexOf('.')
+  return dot === -1 ? fieldPath : fieldPath.slice(dot + 1)
+}
+
+/**
+ * Progress callback type for upload execution with progress tracking.
+ */
+export type UploadProgressCallback = (info: {
+  current: number
+  total: number
+  fieldPath: string
+  status: 'uploading' | 'done' | 'error'
+}) => void
+
+/**
+ * Execute uploads with progress callbacks.
+ * Useful for showing upload progress in the UI.
+ */
+export async function executeUploadsWithProgress(
+  pendingUploads: Map<string, PendingUpload>,
+  uploadField: UploadFieldFn,
+  onProgress?: UploadProgressCallback
+): Promise<ExecuteUploadsResult> {
+  const results: UploadResult[] = []
+  const successful = new Map<string, StoredFileValue>()
+  const errors = new Map<string, string>()
+
+  const entries = Array.from(pendingUploads.entries())
+  const total = entries.length
+
+  for (let i = 0; i < entries.length; i++) {
+    const [fieldPath, upload] = entries[i]
+
+    onProgress?.({
+      current: i + 1,
+      total,
+      fieldPath,
+      status: 'uploading',
+    })
+
+    const formData = new FormData()
+    formData.append('file', upload.file)
+    formData.append('field', uploadFieldName(fieldPath))
+
+    try {
+      const result = await uploadField(upload.collectionPath, formData, false)
+
+      results.push({
+        fieldPath,
+        success: true,
+        storedFile: result.storedFile,
+      })
+      successful.set(fieldPath, result.storedFile)
+
+      onProgress?.({
+        current: i + 1,
+        total,
+        fieldPath,
+        status: 'done',
+      })
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Upload failed'
+      results.push({
+        fieldPath,
+        success: false,
+        error: message,
+      })
+      errors.set(fieldPath, message)
+
+      onProgress?.({
+        current: i + 1,
+        total,
+        fieldPath,
+        status: 'error',
+      })
+    }
+  }
+
+  return {
+    results,
+    successful,
+    errors,
+    allSucceeded: errors.size === 0,
+  }
+}