@byline/admin 6.1.0 → 6.2.1

package/src/forms/form-page-chrome.tsx

@@ -0,0 +1,460 @@
+'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
+ */
+
+/**
+ * Page-level chrome for the full-page document editor: the parts that frame a
+ * form rather than render it. The embedded creation view renders none of this.
+ *
+ * Each component takes only the props it needs — deliberately not a
+ * `FormRendererProps` pass-through, so what a region actually depends on stays
+ * visible at its call site.
+ */
+
+import type { ReactNode, RefObject } from 'react'
+
+import type { SlugifierFn, StructuralMutationReceipt, WorkflowStatus } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Alert, Button, ComboButton, LoaderEllipsis } from '@byline/ui/react'
+import cx from 'clsx'
+
+import { AvailableLocalesWidget } from './available-locales-widget'
+import { DocumentActions, type DocumentActionsLocaleOption } from './document-actions'
+import styles from './form-renderer.module.css'
+import { FormStatusDisplay } from './form-status-display'
+import { PathWidget } from './path-widget'
+import {
+  ScheduledPublicationCell,
+  ScheduledPublicationNotice,
+  type UseScheduledPublicationReturn,
+} from './scheduled-publication-control'
+import { TreePlacementWidget } from './tree-placement-widget'
+import type { PublishedVersionInfo } from './form-renderer'
+import type { StatusTransitions } from './status-transitions'
+
+export interface FormHeadingRowProps {
+  heading: ReactNode
+  /** Host-supplied controls rendered beside the heading (locale switcher, …). */
+  headerSlot?: ReactNode
+}
+
+export const FormHeadingRow = ({ heading, headerSlot }: FormHeadingRowProps): ReactNode => (
+  <div className={cx('byline-form-heading-row', styles['heading-row'])}>
+    <h1 className={cx('byline-form-heading', styles.heading)}>{heading}</h1>
+    {/* Source-locale anchor indicator removed pending heading-layout work.
+        To re-enable: render `<SourceLocaleBadge locale={sourceLocale} />`
+        here from `initialData.sourceLocale` (mismatch-only is the intended
+        end state). See docs/08-internationalization/index.md. */}
+    {headerSlot}
+  </div>
+)
+
+export interface FormStatusBarProps {
+  /** Mutations blocked or a discard in flight. */
+  disabled: boolean
+  // biome-ignore lint/suspicious/noExplicitAny: document shape is collection-specific
+  initialData?: any
+  workflowStatuses?: WorkflowStatus[]
+  publishedVersion?: PublishedVersionInfo | null
+  scheduling: UseScheduledPublicationReturn
+  hasChanges: boolean
+  isUploading: boolean
+  isSubmitting: boolean
+  onCancel: () => void
+  /** Status transitions, already computed for the current workflow position. */
+  transitions: StatusTransitions
+  statusBusy: boolean
+  onStatusBusyChange: (busy: boolean) => void
+  onStatusChange?: (nextStatus: string) => Promise<void>
+  onMutationError?: (error: unknown) => 'blocked' | 'committed' | null | void
+  /** Read synchronously at click time, not at render time. */
+  isBlocked: () => boolean
+  /** A guarded action was attempted while the form is dirty. */
+  onUnsavedChanges: () => void
+  onUnpublish?: () => Promise<void>
+  onDelete?: () => Promise<void>
+  onDuplicate?: () => Promise<void>
+  onCopyToLocale?: (args: { targetLocale: string; overwrite: boolean }) => Promise<void>
+  onDeleteLocale?: (args: { targetLocale: string }) => Promise<void>
+  useAsTitle?: string
+  contentLocale: string
+  contentLocales?: ReadonlyArray<DocumentActionsLocaleOption>
+  defaultLocale: string
+}
+
+export const FormStatusBar = ({
+  disabled,
+  initialData,
+  workflowStatuses,
+  publishedVersion,
+  scheduling,
+  hasChanges,
+  isUploading,
+  isSubmitting,
+  onCancel,
+  transitions,
+  statusBusy,
+  onStatusBusyChange,
+  onStatusChange,
+  onMutationError,
+  isBlocked,
+  onUnsavedChanges,
+  onUnpublish,
+  onDelete,
+  onDuplicate,
+  onCopyToLocale,
+  onDeleteLocale,
+  useAsTitle,
+  contentLocale,
+  contentLocales,
+  defaultLocale,
+}: FormStatusBarProps): ReactNode => {
+  const { t } = useTranslation('byline-admin')
+  const { primaryStatus, secondaryStatuses, isTerminal } = transitions
+
+  return (
+    <div className={cx('byline-form-status-bar', styles['status-bar'])}>
+      <div className={cx('byline-form-status-details', styles['status-details'])}>
+        <FormStatusDisplay
+          disabled={disabled}
+          initialData={initialData}
+          workflowStatuses={workflowStatuses}
+          publishedVersion={publishedVersion}
+          onUnpublish={onUnpublish}
+          afterStatusCells={
+            <ScheduledPublicationCell state={scheduling.state} timeZone={scheduling.timeZone} />
+          }
+        />
+      </div>
+      <div className={cx('byline-form-actions', styles.actions)}>
+        <Button
+          className={cx('byline-form-actions-button', styles['actions-button'])}
+          size="sm"
+          intent="noeffect"
+          type="button"
+          onClick={onCancel}
+        >
+          {hasChanges === false ? t('common.actions.close') : t('common.actions.cancel')}
+        </Button>
+        <Button
+          className={cx('byline-form-actions-button', styles['actions-button'])}
+          size="sm"
+          type="submit"
+          disabled={disabled || hasChanges === false || isUploading || isSubmitting}
+          aria-label={isSubmitting ? t('common.actions.save') : undefined}
+        >
+          {isUploading ? (
+            t('forms.actions.uploading')
+          ) : (
+            <span className={cx('byline-form-save-content', styles['save-content'])}>
+              <span
+                className={cx(
+                  'byline-form-save-label',
+                  styles['save-label'],
+                  isSubmitting && styles['save-label-hidden']
+                )}
+              >
+                {t('common.actions.save')}
+              </span>
+              {isSubmitting ? (
+                <span className={cx('byline-form-save-loader', styles['save-loader'])}>
+                  <LoaderEllipsis size={28} aria-hidden="true" />
+                </span>
+              ) : null}
+            </span>
+          )}
+        </Button>
+        {primaryStatus && onStatusChange && (
+          <div className={cx('byline-form-actions-status-wrap', styles['actions-status-wrap'])}>
+            <ComboButton
+              buttonClassName={cx(
+                'byline-form-actions-combo-button',
+                styles['actions-combo-button']
+              )}
+              triggerClassName={cx(
+                'byline-form-actions-combo-trigger',
+                styles['actions-combo-trigger']
+              )}
+              options={secondaryStatuses.map((s) => ({
+                label: isTerminal
+                  ? t('forms.actions.revertTo', { label: s.label ?? s.name })
+                  : (s.verb ?? s.label ?? s.name),
+                value: s.name,
+              }))}
+              sideOffset={5}
+              size="sm"
+              type="button"
+              intent={isTerminal ? 'info' : 'success'}
+              disabled={disabled || statusBusy}
+              onOptionSelect={async (value: string) => {
+                if (isBlocked()) return
+                if (hasChanges) {
+                  onUnsavedChanges()
+                  return
+                }
+                onStatusBusyChange(true)
+                try {
+                  await onStatusChange(value)
+                } catch (error) {
+                  onMutationError?.(error)
+                } finally {
+                  onStatusBusyChange(false)
+                }
+              }}
+              onButtonClick={
+                isTerminal
+                  ? undefined
+                  : async () => {
+                      if (isBlocked()) return
+                      if (hasChanges) {
+                        onUnsavedChanges()
+                        return
+                      }
+                      onStatusBusyChange(true)
+                      try {
+                        await onStatusChange(primaryStatus.name)
+                      } catch (error) {
+                        onMutationError?.(error)
+                      } finally {
+                        onStatusBusyChange(false)
+                      }
+                    }
+              }
+            >
+              {statusBusy
+                ? '...'
+                : isTerminal
+                  ? (primaryStatus.label ?? primaryStatus.name)
+                  : (primaryStatus.verb ?? primaryStatus.label ?? primaryStatus.name)}
+            </ComboButton>
+          </div>
+        )}
+        <DocumentActions
+          disabled={disabled}
+          publishedVersion={publishedVersion}
+          onUnpublish={onUnpublish}
+          onDelete={onDelete}
+          onDuplicate={onDuplicate}
+          sourceTitle={
+            useAsTitle != null && initialData != null
+              ? ((initialData as Record<string, unknown>)[useAsTitle] as string | null | undefined)
+              : null
+          }
+          onCopyToLocale={onCopyToLocale}
+          sourceLocale={contentLocale}
+          contentLocales={contentLocales}
+          hasUnsavedChanges={hasChanges}
+          onUnsavedChanges={() => onUnsavedChanges()}
+          onDeleteLocale={onDeleteLocale}
+          defaultLocale={defaultLocale}
+          availableLocales={initialData?._availableVersionLocales as string[] | undefined}
+          scheduledPublicationState={scheduling.state}
+          onSchedulePublication={scheduling.openSchedule}
+          onConfirmScheduledPublication={scheduling.confirm}
+          onCancelScheduledPublication={scheduling.cancel}
+        />
+      </div>
+    </div>
+  )
+}
+
+export interface FormConcurrencyNoticesProps {
+  /** Mutations blocked or a discard in flight. */
+  disabled: boolean
+  mutationIssue?: 'stale' | 'reload' | 'lock' | 'unavailable' | 'committed' | null
+  scheduledPublicationsNeedReconfirmation?: boolean
+  scheduledPublicationsHref?: string
+  /**
+   * Focus target when a mutation issue appears. The ref belongs to the form
+   * component, which restores focus after a save; this region only attaches it.
+   */
+  warningRef: RefObject<HTMLDivElement | null>
+  discarding: boolean
+  reloadFailed: boolean
+  onDiscardRequested: () => void
+  scheduling: UseScheduledPublicationReturn
+  restoreWarnings?: string[]
+}
+
+export const FormConcurrencyNotices = ({
+  disabled,
+  mutationIssue,
+  scheduledPublicationsNeedReconfirmation,
+  scheduledPublicationsHref,
+  warningRef,
+  discarding,
+  reloadFailed,
+  onDiscardRequested,
+  scheduling,
+  restoreWarnings,
+}: FormConcurrencyNoticesProps): ReactNode => {
+  const { t } = useTranslation('byline-admin')
+
+  return (
+    <>
+      {(mutationIssue || scheduledPublicationsNeedReconfirmation) && (
+        <div
+          ref={warningRef}
+          tabIndex={-1}
+          role="alert"
+          aria-live="assertive"
+          className={cx('byline-document-concurrency', styles.concurrency)}
+        >
+          {mutationIssue && (
+            <Alert
+              intent="warning"
+              icon
+              close={false}
+              title={t(`documentConcurrency.${mutationIssue}Title`)}
+            >
+              <p>{t(`documentConcurrency.${mutationIssue}`)}</p>
+              {mutationIssue !== 'committed' && (
+                <Button type="button" disabled={discarding} onClick={onDiscardRequested}>
+                  {t('documentConcurrency.reloadAction')}
+                </Button>
+              )}
+              {reloadFailed && <p>{t('documentConcurrency.reloadFailed')}</p>}
+            </Alert>
+          )}
+          {scheduledPublicationsNeedReconfirmation && (
+            <Alert
+              intent="warning"
+              icon
+              close={false}
+              title={t('documentConcurrency.schedulesTitle')}
+            >
+              <p>{t('documentConcurrency.schedules')}</p>
+              {scheduledPublicationsHref && (
+                <a href={scheduledPublicationsHref}>{t('documentConcurrency.reviewSchedules')}</a>
+              )}
+            </Alert>
+          )}
+        </div>
+      )}
+      <ScheduledPublicationNotice
+        state={scheduling.state}
+        timeZone={scheduling.timeZone}
+        busy={disabled || scheduling.busy}
+        onConfirm={scheduling.confirm}
+        onReschedule={scheduling.openSchedule}
+        onCancel={scheduling.cancel}
+      />
+      {scheduling.modal}
+      {restoreWarnings && restoreWarnings.length > 0 && (
+        <Alert
+          className="m-0 mt-4"
+          intent="warning"
+          icon={true}
+          close={false}
+          title={t('forms.restoreWarnings.title')}
+        >
+          <p>{t('forms.restoreWarnings.body', { count: restoreWarnings.length })}</p>
+          <ul>
+            {restoreWarnings.map((w) => (
+              <li key={w}>{w}</li>
+            ))}
+          </ul>
+        </Alert>
+      )}
+    </>
+  )
+}
+
+export interface FormSidebarWidgetsProps {
+  /** Mutations blocked or a discard in flight. */
+  disabled: boolean
+  mode: 'create' | 'edit'
+  // biome-ignore lint/suspicious/noExplicitAny: document shape is collection-specific
+  initialData?: any
+  collectionPath?: string
+  defaultLocale: string
+  contentLocale: string
+  contentLocales?: ReadonlyArray<DocumentActionsLocaleOption>
+  showPath: boolean
+  useAsPath?: string
+  lockPath?: boolean
+  pathSlugifier?: SlugifierFn
+  pathSourceLocked?: boolean
+  tree?: boolean
+  useAsTitle?: string
+  advertiseLocales?: boolean
+  observedRevision?: number
+  onMutationError?: (error: unknown) => 'blocked' | 'committed' | null | void
+  onTreeMutationCommitted?: (receipt: StructuralMutationReceipt) => void
+}
+
+/**
+ * The page-level widgets in the editor's sidebar: path, tree placement and
+ * advertised locales. They are page concerns rather than schema fields, so they
+ * reach `FormLayout` through its `sidebarSlot` and the embedded creation view
+ * passes none of them.
+ */
+export const FormSidebarWidgets = ({
+  disabled,
+  mode,
+  initialData,
+  collectionPath,
+  defaultLocale,
+  contentLocale,
+  contentLocales,
+  showPath,
+  useAsPath,
+  lockPath,
+  pathSlugifier,
+  pathSourceLocked,
+  tree,
+  useAsTitle,
+  advertiseLocales,
+  observedRevision,
+  onMutationError,
+  onTreeMutationCommitted,
+}: FormSidebarWidgetsProps): ReactNode => (
+  <>
+    {/* 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 ||
+        lockPath === true ||
+        (typeof initialData?.path === 'string' && initialData.path.length > 0)) && (
+        <PathWidget
+          disabled={disabled}
+          useAsPath={useAsPath}
+          collectionPath={collectionPath ?? ''}
+          defaultLocale={defaultLocale}
+          activeLocale={contentLocale}
+          mode={mode}
+          slugifier={pathSlugifier}
+          sourceLocked={pathSourceLocked}
+          lockPath={lockPath}
+        />
+      )}
+    {tree && mode === 'edit' && typeof initialData?.id === 'string' && (
+      <TreePlacementWidget
+        disabled={disabled}
+        onMutationError={onMutationError}
+        onCommitted={onTreeMutationCommitted}
+        expectedRevision={observedRevision ?? initialData.revision}
+        collectionPath={collectionPath ?? ''}
+        documentId={initialData.id as string}
+        useAsTitle={useAsTitle}
+      />
+    )}
+    {advertiseLocales && (
+      <AvailableLocalesWidget
+        disabled={disabled}
+        contentLocales={contentLocales ?? []}
+        availableVersionLocales={
+          (initialData?._availableVersionLocales as string[] | undefined) ?? []
+        }
+      />
+    )}
+  </>
+)

package/src/forms/form-renderer-submit.test.tsx

@@ -211,6 +211,46 @@ describe('FormRenderer submit contract', () => {
     expect(saveButton?.querySelector('.byline-loader-ellipsis')).toBeNull()
   })
 
+  it('restores focus to the control that had it before the form went busy', async () => {
+    // `inert` drops the active control out of the tab order mid-save. The hook
+    // signals the transition through onBeforeBusy; the component owns the DOM
+    // refs. Drop that signal and focus silently lands on <body>.
+    //
+    // This covers the KEYBOARD path only: focus is in a field and the form is
+    // submitted from there, so the captured element is still focusable when the
+    // form comes back. Clicking Save is different -- the captured element is the
+    // Save button, which is disabled once the save succeeds -- and that path is
+    // broken in a real browser. See issue #98. Do not read this passing test as
+    // "focus recovery works" in general.
+    const submission = deferred()
+    render({ ...baseProps, onSubmit: () => submission.promise })
+    typeIntoTitle('Hello')
+
+    const input = container.querySelector<HTMLInputElement>('input[name="title"]')
+    if (input == null) throw new Error('title input not found')
+    act(() => {
+      input.focus()
+    })
+    expect(document.activeElement).toBe(input)
+
+    submitForm()
+    await act(async () => {})
+
+    // jsdom does not implement `inert`, so the browser's own focus removal has
+    // to be stood in for here. What is under test is the recovery afterwards.
+    act(() => {
+      input.blur()
+    })
+    expect(document.activeElement).not.toBe(input)
+
+    await act(async () => {
+      submission.resolve()
+      await submission.promise
+    })
+
+    expect(document.activeElement).toBe(input)
+  })
+
   it('hides the busy indicator when onSubmit rejects', async () => {
     const submission = deferred()
     render({ ...baseProps, onSubmit: () => submission.promise })

package/src/forms/form-renderer-tab-persistence.test.tsx

@@ -0,0 +1,145 @@
+/**
+ * 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 { defineAdminConfig } from '@byline/core'
+import { adminTranslations } from '@byline/i18n/admin'
+import { I18nProvider } from '@byline/i18n/react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import { BylineFieldServicesProvider } from '../fields/field-services-context'
+import { FormRenderer } from './form-renderer'
+
+const globalWithAct = globalThis as any
+globalWithAct.IS_REACT_ACT_ENVIRONMENT = true
+
+defineAdminConfig({
+  i18n: {
+    admin: { defaultLocale: 'en', locales: ['en'] },
+    content: { defaultLocale: 'en', locales: ['en', 'fr'] },
+  },
+  collections: [
+    {
+      path: 'pages',
+      labels: { singular: 'Page', plural: 'Pages' },
+      fields: [{ name: 'title', label: 'Title', type: 'text' }],
+    },
+  ],
+  slugifier: (value: string) => value.toLowerCase().trim().replace(/\s+/g, '-'),
+})
+
+const fields = [
+  { name: 'title', label: 'Title', type: 'text' as const },
+  { name: 'seoTitle', label: 'SEO title', type: 'text' as const },
+]
+
+const adminConfig = {
+  layout: { main: ['content'] },
+  tabSets: [
+    {
+      name: 'content',
+      tabs: [
+        { name: 'general', label: 'General', fields: ['title'] },
+        { name: 'seo', label: 'SEO', fields: ['seoTitle'] },
+      ],
+    },
+  ],
+}
+
+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 mount = (locale: string, versionId: string) => {
+  act(() => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        <BylineFieldServicesProvider
+          services={
+            {
+              getCollectionDocuments: async () => ({ docs: [], total: 0 }),
+              uploadField: async () => ({}),
+            } as any
+          }
+        >
+          <FormRenderer
+            mode="edit"
+            fields={fields as any}
+            initialLocale={locale}
+            initialData={{
+              id: 'doc1',
+              versionId,
+              fields: { title: locale, seoTitle: `${locale} SEO` },
+            }}
+            adminConfig={adminConfig as any}
+            collectionPath="pages"
+            onSubmit={() => {}}
+            onCancel={() => {}}
+          />
+        </BylineFieldServicesProvider>
+      </I18nProvider>
+    )
+  })
+}
+
+const selectedTabLabel = () =>
+  container.querySelector('[role="tab"][aria-selected="true"]')?.textContent
+
+describe('FormRenderer tab persistence across keyed remounts', () => {
+  // FormProvider is keyed on `${initialLocale}-${versionId}`, so changing either
+  // remounts the whole subtree. Tab selection is lifted above that key on
+  // purpose; this asserts the wiring, which a controlled-prop test on
+  // FormLayout alone cannot reach.
+  //
+  // Adopted from the reviewer's Checkpoint 2 regression fixture.
+  it('retains the selected tab through locale and version remounts', () => {
+    mount('en', 'v1')
+
+    const seoTab = [...container.querySelectorAll('[role="tab"]')].find(
+      (t) => t.textContent === 'SEO'
+    )
+    if (seoTab == null) throw new Error('SEO tab not found')
+    act(() => {
+      ;(seoTab as HTMLElement).click()
+    })
+    const first = container.querySelector<HTMLInputElement>('input[name="seoTitle"]')
+    expect(first).not.toBeNull()
+
+    mount('fr', 'v1') // locale change remounts FormProvider via its key
+    const french = container.querySelector<HTMLInputElement>('input[name="seoTitle"]')
+    expect(french).not.toBeNull()
+    expect(french).not.toBe(first)
+    expect(french?.value).toBe('fr SEO')
+    expect(selectedTabLabel()).toBe('SEO')
+
+    mount('fr', 'v2') // version change remounts it again
+    const versioned = container.querySelector<HTMLInputElement>('input[name="seoTitle"]')
+    expect(versioned).not.toBeNull()
+    expect(versioned).not.toBe(french)
+    expect(selectedTabLabel()).toBe('SEO')
+  })
+})

package/src/forms/form-renderer.module.css

@@ -304,6 +304,24 @@
   }
 }
 
+/* One column at every width. The split layout above becomes a two-column grid
+   at >=60rem; a stacked form must not inherit that, or it reserves an empty
+   second track and narrows its only content column. */
+.layout-stacked,
+:global(.byline-form-layout-stacked) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-12);
+  padding-top: var(--spacing-32);
+}
+
+@media (min-width: 60rem) {
+  .layout-stacked,
+  :global(.byline-form-layout-stacked) {
+    gap: var(--spacing-32);
+  }
+}
+
 .content,
 :global(.byline-form-content) {
   display: flex;