@byline/admin 2.5.2 → 2.6.1

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('@byline/ui/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,183 @@
+'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, useMemo } from 'react'
+
+import { slugify } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Input, Label } from '@byline/ui/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
+  /**
+   * The locale currently being edited in the form. When this differs
+   * from `defaultLocale` (i.e. the editor is editing a translation),
+   * the widget renders read-only — phase 1 paths are default-locale
+   * territory, and the lifecycle drops translation-locale path changes
+   * with a warn. Locking the input prevents the warn path being hit
+   * through the admin form and gives editors a clear cue.
+   */
+  activeLocale: string
+  /** `'create'` shows the live derived preview as placeholder text. */
+  mode: 'create' | 'edit'
+}
+
+/**
+ * System-managed `path` widget.
+ *
+ * Edits the path stored in `byline_document_paths` for the current
+ * (document, locale) row. Displays the current persisted/overridden
+ * value 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,
+  activeLocale,
+  mode,
+}: PathWidgetProps) => {
+  const { setSystemPath } = useFormContext()
+  const { t } = useTranslation('byline-admin')
+  const systemPath = useSystemPath()
+  const sourceValue = useFieldValue<unknown>(useAsPath ?? '')
+
+  // Phase 1: paths are written/edited only under the default content
+  // locale. When editing a translation, the widget locks down — the
+  // input is read-only, the Regenerate action is suppressed, and a
+  // helpText line explains why.
+  const isReadOnly = activeLocale !== defaultLocale
+
+  // 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 validationHint =
+    inputValue.length > 0 && formatted !== inputValue
+      ? t('pathWidget.suggestedHint', { formatted })
+      : undefined
+
+  // When read-only, replace the live validation hint with a fixed
+  // explanatory line so editors understand why the field is locked.
+  const readOnlyHint = isReadOnly
+    ? t('pathWidget.readOnlyHint', { locale: defaultLocale })
+    : undefined
+
+  const hint = readOnlyHint ?? validationHint
+
+  const placeholder =
+    !isReadOnly && mode === 'create' && livePreview.length > 0
+      ? t('pathWidget.willBeSavedAs', { preview: 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, or read-only explainer)
+  // currently applies. The visible helpText/placeholder cover sighted
+  // users; this element makes the same information addressable via
+  // aria-describedby for AT.
+  const srDescription = [t('pathWidget.srDescription'), placeholder, hint].filter(Boolean).join(' ')
+
+  const showRegenerate =
+    !isReadOnly && useAsPath && livePreview.length > 0 && livePreview !== systemPath
+
+  return (
+    <div className="byline-form-path">
+      <div className={cx('byline-form-path-header', styles.header)}>
+        <Label id="system-path-label" htmlFor="system-path" label={t('pathWidget.label')} />
+        {showRegenerate && (
+          <button
+            type="button"
+            onClick={handleRegenerate}
+            className={cx('byline-form-path-regenerate', styles.regenerate)}
+            aria-label={t('pathWidget.regenerateAriaLabel', { field: useAsPath })}
+          >
+            {t('pathWidget.regenerateButton', { field: useAsPath })}
+          </button>
+        )}
+      </div>
+      <Input
+        id="system-path"
+        name="__systemPath__"
+        value={inputValue}
+        placeholder={placeholder}
+        onChange={(e) => handleChange(e.target.value)}
+        helpText={hint}
+        readOnly={isReadOnly}
+        aria-describedby="system-path-description"
+      />
+      <span
+        id="system-path-description"
+        className={cx('byline-form-path-sr-only', styles['sr-only'])}
+      >
+        {srDescription}
+      </span>
+    </div>
+  )
+}