@byline/admin 6.2.0 → 6.3.0

package/src/forms/form-layout.tsx

@@ -0,0 +1,204 @@
+'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 { Fragment, type ReactNode } from 'react'
+
+import type {
+  AdminResourceConfig,
+  Field,
+  GroupDefinition,
+  RowDefinition,
+  TabSetDefinition,
+} from '@byline/core'
+import cx from 'clsx'
+
+import { sliceFieldAdmin } from '../fields/field-admin'
+import { FieldRenderer } from '../fields/field-renderer'
+import { AdminGroup } from '../presentation/group'
+import { AdminRow } from '../presentation/row'
+import { AdminTabs, tabPanelId, tabTriggerId } from '../presentation/tabs'
+import { useFormDomScope } from './form-dom-scope'
+import styles from './form-renderer.module.css'
+import { useFormLayout } from './use-form-layout'
+import { useFormTabs } from './use-form-tabs'
+
+export interface FormLayoutProps {
+  fields: Field[]
+  adminConfig?: AdminResourceConfig
+  /** Which regions to render, in order. Default: both. */
+  regions?: ReadonlyArray<'main' | 'sidebar'>
+  /** 'split' = two columns (full page); 'stacked' = one column (embedded). */
+  variant?: 'split' | 'stacked'
+  collectionPath?: string
+  /** Content locale passed through to every field renderer. */
+  activeLocale?: string
+  /** Initial document, for field default values. */
+  // biome-ignore lint/suspicious/noExplicitAny: document shape is collection-specific
+  initialData?: any
+  /**
+   * Controlled active-tab state. Owned above the keyed `FormProvider` so tab
+   * choices survive the remount a locale change triggers — see `useFormTabs`.
+   */
+  activeTabBySet: Record<string, string>
+  onTabChange: (tabSetName: string, tabName: string) => void
+  /**
+   * Page-level sidebar widgets (path, tree placement, available locales),
+   * rendered in the same sidebar column as the sidebar schema fields. The
+   * embedded creation view passes nothing.
+   */
+  sidebarSlot?: ReactNode
+}
+
+const BOTH_REGIONS = ['main', 'sidebar'] as const
+
+/**
+ * The layout walk: recursively dispatches each name in a region to the
+ * appropriate primitive renderer or to `<FieldRenderer>`.
+ */
+export const FormLayout = ({
+  fields,
+  adminConfig,
+  regions = BOTH_REGIONS,
+  variant = 'split',
+  activeLocale,
+  initialData,
+  activeTabBySet,
+  onTabChange,
+  sidebarSlot,
+}: FormLayoutProps): ReactNode => {
+  const { fieldByName, tabSetByName, rowByName, groupByName, layout, fieldToTabPath } =
+    useFormLayout(adminConfig, fields)
+  const tabs = useFormTabs(fieldToTabPath, activeTabBySet)
+  // Two forms over one collection share its admin configuration, so their tab
+  // sets carry the same name and would otherwise derive the same trigger and
+  // panel ids. `aria-labelledby` resolves document-wide, so the second form's
+  // panel would name the first form's trigger.
+  const domScope = useFormDomScope()
+
+  const renderField = (fieldName: string): ReactNode => {
+    const field = fieldByName.get(fieldName)
+    if (!field) return null
+    return (
+      <FieldRenderer
+        key={field.name}
+        field={field}
+        defaultValue={initialData?.fields?.[field.name]}
+        contentLocale={activeLocale}
+        components={adminConfig?.fields?.[field.name]?.components}
+        editor={adminConfig?.fields?.[field.name]?.editor}
+        fieldAdmin={sliceFieldAdmin(adminConfig?.fields, field.name)}
+      />
+    )
+  }
+
+  const renderItem = (name: string): ReactNode => {
+    const tabSet = tabSetByName.get(name)
+    if (tabSet) return renderTabSet(tabSet)
+
+    const group = groupByName.get(name)
+    if (group) return renderGroup(group)
+
+    const row = rowByName.get(name)
+    if (row) return renderRow(row)
+
+    return renderField(name)
+  }
+
+  const renderRow = (row: RowDefinition): ReactNode => (
+    <AdminRow key={`row:${row.name}`}>{row.fields.map((name) => renderField(name))}</AdminRow>
+  )
+
+  const renderGroup = (group: GroupDefinition): ReactNode => (
+    <AdminGroup key={`group:${group.name}`} label={group.label}>
+      {group.fields.map((name) => renderItem(name))}
+    </AdminGroup>
+  )
+
+  const renderTabSet = (set: TabSetDefinition): ReactNode => {
+    const { visibleTabs, activeTabName, activeTab, errorCounts } = tabs.resolve(set)
+    const idBase = `${domScope}tabset:${set.name}`
+
+    return (
+      <div key={idBase} className={cx('byline-form-tabset', styles.tabset)}>
+        {visibleTabs.length > 0 && (
+          <AdminTabs
+            idBase={idBase}
+            tabs={visibleTabs}
+            activeTab={activeTabName}
+            onChange={(tabName) => onTabChange(set.name, tabName)}
+            errorCounts={errorCounts}
+            className={cx('byline-form-tabset-tabs', styles['tabset-tabs'])}
+          />
+        )}
+        {activeTab && (
+          <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>
+        )}
+      </div>
+    )
+  }
+
+  const sidebarNames = layout.sidebar ?? []
+
+  // Page-level widgets come first, matching the current editor. The plan's
+  // Task 2 sketch had them after the schema fields; that would visibly reorder
+  // a shipped collection's sidebar during a refactor whose acceptance is
+  // behaviour preservation.
+  const sidebarContents = (
+    <>
+      {sidebarSlot}
+      {sidebarNames.map((name) => renderItem(name))}
+    </>
+  )
+
+  // `regions` is an ordered list, not a set: iterate it in sequence rather than
+  // testing membership, or a caller asking for ['sidebar', 'main'] silently
+  // still gets main first.
+  const renderRegion = (region: 'main' | 'sidebar'): ReactNode =>
+    region === 'main' ? (
+      <div key="main" className={cx('byline-form-content', styles.content)}>
+        {layout.main.map((name) => renderItem(name))}
+      </div>
+    ) : (
+      <div key="sidebar" className={cx('byline-form-sidebar', styles.sidebar)}>
+        {sidebarContents}
+      </div>
+    )
+
+  // Stacked: one column, both regions inline, and deliberately **not** the
+  // split layout class - that class becomes a two-column grid at >=60rem, so
+  // carrying it here would reserve an empty second track and narrow the only
+  // column. Removing the sidebar element does not remove the grid track.
+  if (variant === 'stacked') {
+    return (
+      <div className={cx('byline-form-layout-stacked', styles['layout-stacked'])}>
+        <div className={cx('byline-form-content', styles.content)}>
+          {regions.map((region) => (
+            <Fragment key={region}>
+              {region === 'main' ? layout.main.map((name) => renderItem(name)) : sidebarContents}
+            </Fragment>
+          ))}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className={cx('byline-form-layout', styles.layout)}>
+      {regions.map((region) => renderRegion(region))}
+    </div>
+  )
+}

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) ?? []
+        }
+      />
+    )}
+  </>
+)