@byline/admin 6.0.3 → 6.2.0

package/src/forms/form-renderer.tsx

@@ -11,8 +11,8 @@
 import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import type {
+  AdminResourceConfig,
   Field,
-  FormAdminConfig,
   GroupDefinition,
   RowDefinition,
   TabSetDefinition,
@@ -29,7 +29,7 @@ import { FieldRenderer } from '../fields/field-renderer'
 import { useBylineFieldServices } from '../fields/field-services-context'
 import { AdminGroup } from '../presentation/group'
 import { AdminRow } from '../presentation/row'
-import { AdminTabs } from '../presentation/tabs'
+import { AdminTabs, tabPanelId, tabTriggerId } from '../presentation/tabs'
 import { AvailableLocalesWidget } from './available-locales-widget'
 import { DocumentActions, type DocumentActionsLocaleOption } from './document-actions'
 import { FormProvider, useFieldValue, useFormContext } from './form-context'
@@ -133,7 +133,13 @@ export interface FormRendererProps {
   workflowStatuses?: WorkflowStatus[]
   publishedVersion?: PublishedVersionInfo | null
   initialData?: Record<string, any>
-  adminConfig?: FormAdminConfig
+  /**
+   * Presentation configuration for the resource being edited — a collection
+   * or a singleton. Typed as the union rather than the shared
+   * `FormAdminConfig` base so the renderer can read collection-only members
+   * such as `lockPath`.
+   */
+  adminConfig?: AdminResourceConfig
   /**
    * Name of the schema field to render as the live form heading.
    * Sourced from `CollectionDefinition.useAsTitle` by the caller.
@@ -665,11 +671,13 @@ const FormContent = ({
         ? (visibleTabs[0]?.name ?? requested)
         : requested
     const activeTab = visibleTabs.find((t) => t.name === resolvedActive)
+    const idBase = `tabset:${set.name}`
 
     return (
-      <div key={`tabset:${set.name}`} className={cx('byline-form-tabset', styles.tabset)}>
+      <div key={idBase} className={cx('byline-form-tabset', styles.tabset)}>
         {visibleTabs.length > 0 && (
           <AdminTabs
+            idBase={idBase}
             tabs={visibleTabs}
             activeTab={resolvedActive}
             onChange={(tabName) => handleTabChange(set.name, tabName)}
@@ -678,7 +686,12 @@ const FormContent = ({
           />
         )}
         {activeTab && (
-          <div className={cx('byline-form-tabset-fields', styles['tabset-fields'])}>
+          <div
+            role="tabpanel"
+            id={tabPanelId(idBase, activeTab.name)}
+            aria-labelledby={tabTriggerId(idBase, activeTab.name)}
+            className={cx('byline-form-tabset-fields', styles['tabset-fields'])}
+          >
             {activeTab.fields.map((name) => renderItem(name))}
           </div>
         )}
@@ -952,8 +965,13 @@ const FormContent = ({
               {layout.main.map((name) => renderItem(name))}
             </div>
             <div className={cx('byline-form-sidebar', styles.sidebar)}>
+              {/* A locked collection's widget renders even with no `useAsPath`
+                  and nothing stored yet: its path is managed, and the editor
+                  needs to see that. `showPath: false` still wins — it marks a
+                  path that must never be presented at all. */}
               {showPath &&
                 (useAsPath ||
+                  adminConfig?.lockPath === true ||
                   (typeof initialData?.path === 'string' && initialData.path.length > 0)) && (
                   <PathWidget
                     disabled={mutationsBlocked || discarding}
@@ -964,6 +982,7 @@ const FormContent = ({
                     mode={mode}
                     slugifier={pathSlugifier}
                     sourceLocked={pathSourceLocked}
+                    lockPath={adminConfig?.lockPath}
                   />
                 )}
               {tree && mode === 'edit' && typeof initialData?.id === 'string' && (

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

@@ -110,6 +110,7 @@ describe('PathWidget', () => {
       activeLocale: string
       slugifier: (value: string, ctx: { locale: string; collectionPath: string }) => string
       sourceLocked: boolean
+      lockPath: boolean
     }> = {}
   ) => {
     act(() => {
@@ -124,13 +125,14 @@ describe('PathWidget', () => {
           localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
         >
           <PathWidget
-            useAsPath={props.useAsPath ?? 'title'}
+            useAsPath={'useAsPath' in props ? props.useAsPath : 'title'}
             collectionPath="pages"
             defaultLocale="en"
             activeLocale={props.activeLocale ?? 'en'}
             mode={props.mode ?? 'create'}
             slugifier={props.slugifier}
             sourceLocked={props.sourceLocked}
+            lockPath={props.lockPath}
           />
         </I18nProvider>
       )
@@ -228,7 +230,7 @@ describe('PathWidget', () => {
   })
 
   it('does not render the Regenerate button when there is no useAsPath', () => {
-    setFixture({ systemPath: 'whatever', sourceValue: '' })
+    setFixture({ systemPath: 'whatever', sourceValue: 'Hello World' })
     render({ mode: 'edit', useAsPath: undefined })
     expect(container.querySelector('button')).toBeNull()
   })
@@ -245,6 +247,27 @@ describe('PathWidget', () => {
     expect(input.getAttribute('placeholder')).toBe('Will be saved as "0000001"')
   })
 
+  it('shows the translation-locale hint when editing a translation unlocked', () => {
+    setFixture({ systemPath: 'my-path', sourceValue: 'My Path' })
+    render({ mode: 'edit', activeLocale: 'fr' })
+
+    const input = getInput()
+    expect(input.readOnly).toBe(true)
+    expect(container.querySelector('[data-testid="help-text"]')?.textContent).toBe(
+      'Path is set in the default locale ("en") and applies across translations.'
+    )
+  })
+
+  it('shows the suggested-slug hint for an un-slugified stored value', () => {
+    setFixture({ systemPath: 'Not A Slug', sourceValue: 'My Path' })
+    render({ mode: 'edit' })
+
+    expect(getInput().readOnly).toBe(false)
+    expect(container.querySelector('[data-testid="help-text"]')?.textContent).toBe(
+      'Suggested: "not-a-slug"'
+    )
+  })
+
   it('suppresses the create-mode placeholder preview when the source is locked', () => {
     setFixture({ systemPath: null, sourceValue: 1 })
     render({ mode: 'create', sourceLocked: true })
@@ -259,4 +282,75 @@ describe('PathWidget', () => {
     render({ mode: 'edit', sourceLocked: true })
     expect(container.querySelector('button')).toBeNull()
   })
+
+  it('renders read-only and empty when creating in a locked collection', () => {
+    setFixture({ systemPath: null, sourceValue: 'Hello World' })
+    render({ mode: 'create', lockPath: true })
+
+    const input = getInput()
+    expect(input.readOnly).toBe(true)
+    expect(input.value).toBe('')
+    expect(input.getAttribute('placeholder')).toBeNull()
+    expect(container.querySelector('button')).toBeNull()
+    expect(container.querySelector('[data-testid="help-text"]')?.textContent).toBe(
+      'Assigned automatically when this document is saved.'
+    )
+  })
+
+  it('renders read-only and shows the stored path when editing a locked collection', () => {
+    setFixture({ systemPath: 'catalogue-item', sourceValue: 'Hello World' })
+    render({ mode: 'edit', lockPath: true })
+
+    const input = getInput()
+    expect(input.readOnly).toBe(true)
+    expect(input.value).toBe('catalogue-item')
+    // The stored path differs from what the source would derive, so an
+    // unlocked widget would offer Regenerate here.
+    expect(container.querySelector('button')).toBeNull()
+    expect(container.querySelector('[data-testid="help-text"]')?.textContent).toBe(
+      'This path is managed and cannot be edited here.'
+    )
+  })
+
+  it('prefers the locked hint over the translation-locale hint', () => {
+    setFixture({ systemPath: 'catalogue-item', sourceValue: 'Hello World' })
+    render({ mode: 'edit', lockPath: true, activeLocale: 'fr' })
+
+    expect(getInput().readOnly).toBe(true)
+    expect(container.querySelector('[data-testid="help-text"]')?.textContent).toBe(
+      'This path is managed and cannot be edited here.'
+    )
+  })
+
+  it('ignores a change event while locked — the lock is not merely visual', () => {
+    setFixture({ systemPath: 'catalogue-item', sourceValue: 'Hello World' })
+    render({ mode: 'edit', lockPath: true })
+
+    // Drive the input through the native prototype setter, exactly as the
+    // two typing tests above do. A direct `input.value = …` updates React's
+    // value tracker, which then suppresses onChange on its own — the
+    // assertion below would pass whether or not the guard exists.
+    const input = getInput()
+    act(() => {
+      const setter = Object.getOwnPropertyDescriptor(
+        window.HTMLInputElement.prototype,
+        'value'
+      )?.set
+      setter?.call(input, 'typed-over')
+      input.dispatchEvent(new Event('input', { bubbles: true }))
+    })
+
+    expect(fixture.setSystemPath).not.toHaveBeenCalled()
+  })
+
+  it('leaves a counter-sourced collection editable when lockPath is not set', () => {
+    // The explicit guard against reintroducing inference: a locked *source*
+    // suppresses the preview and Regenerate, but never the input itself.
+    setFixture({ systemPath: '0000448', sourceValue: 448 })
+    render({ mode: 'edit', sourceLocked: true })
+
+    const input = getInput()
+    expect(input.readOnly).toBe(false)
+    expect(container.querySelector('button')).toBeNull()
+  })
 })

package/src/forms/path-widget.tsx

@@ -66,6 +66,14 @@ export interface PathWidgetProps {
    * persisted path. Defaults to `false`.
    */
   sourceLocked?: boolean
+  /**
+   * When `true`, the collection declares its paths managed
+   * (`CollectionAdminConfig.lockPath`): the input renders read-only in both
+   * modes and the preview placeholder and "Regenerate" action are
+   * suppressed. Independent of `sourceLocked`, which answers whether the
+   * form can derive a preview at all. Defaults to `false`.
+   */
+  lockPath?: boolean
 }
 
 /**
@@ -92,6 +100,7 @@ export const PathWidget = ({
   mode,
   slugifier,
   sourceLocked = false,
+  lockPath = false,
   disabled = false,
 }: PathWidgetProps) => {
   const { setSystemPath } = useFormContext()
@@ -105,11 +114,15 @@ export const PathWidget = ({
   // with what the server persists.
   const runSlugify = slugifier ?? slugify
 
-  // 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
+  // Phase 1: paths are written/edited only under the default content locale,
+  // so editing a translation locks the widget down.
+  const translationLocked = activeLocale !== defaultLocale
+
+  // A collection may also declare its paths managed. Both conditions produce
+  // the same read-only surface, so the placeholder, the Regenerate
+  // affordance, the `readOnly` attribute and the change guard all key off the
+  // combined flag.
+  const isReadOnly = lockPath || translationLocked
 
   // Live preview — what the server would derive from the current source
   // field value if no override were set. Used as placeholder in create
@@ -127,12 +140,14 @@ export const PathWidget = ({
 
   const handleChange = useCallback(
     (next: string) => {
-      if (disabled) return
+      // `readOnly` stops real typing; a programmatic change event still
+      // reaches this handler. Refuse the write so the lock holds in the form.
+      if (disabled || isReadOnly) return
       // Empty string clears the override — server falls back to derive
       // (create) or sticky (update).
       setSystemPath(next.length === 0 ? null : next)
     },
-    [disabled, setSystemPath]
+    [disabled, isReadOnly, setSystemPath]
   )
 
   const handleRegenerate = useCallback(() => {
@@ -154,13 +169,18 @@ export const PathWidget = ({
       ? 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
+  // Hint precedence: locked, then translation, then live validation.
+  const lockedHint = lockPath
+    ? mode === 'create'
+      ? t('pathWidget.lockedCreateHint')
+      : t('pathWidget.lockedHint')
+    : undefined
+
+  const translationHint = translationLocked
     ? t('pathWidget.readOnlyHint', { locale: defaultLocale })
     : undefined
 
-  const hint = readOnlyHint ?? validationHint
+  const hint = lockedHint ?? translationHint ?? validationHint
 
   const placeholder =
     !isReadOnly && mode === 'create' && livePreview.length > 0

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
+}