@byline/ui 2.5.1 → 2.6.0

package/src/forms/navigation-guard.tsx

@@ -1,98 +0,0 @@
-/**
- * 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

@@ -1,41 +0,0 @@
-/**
- * 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

@@ -1,217 +0,0 @@
-/**
- * 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

@@ -1,181 +0,0 @@
-'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 cx from 'classnames'
-
-import { Input, Label } from '../uikit.js'
-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 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 ? `Suggested: "${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
-    ? `Path is set in the default locale ("${defaultLocale}") and applies across translations.`
-    : undefined
-
-  const hint = readOnlyHint ?? validationHint
-
-  const placeholder =
-    !isReadOnly && 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, 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 = ['System-managed URL path for this document.', 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="Path" />
-        {showRegenerate && (
-          <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}
-        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>
-  )
-}