@byline/admin 6.1.0 → 6.2.1

package/src/forms/form-layout.test.tsx

@@ -0,0 +1,276 @@
+/**
+ * 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 type { AdminResourceConfig, Field } from '@byline/core'
+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, vi } from 'vitest'
+
+import { BylineFieldServicesProvider } from '../fields/field-services-context'
+import { FormProvider } from './form-context'
+import { FormLayout } from './form-layout'
+
+// Deliberately not the `;(globalThis as any)` idiom used elsewhere in this
+// suite: Biome's import sorting can move an import across that leading
+// semicolon, and without semicolons the result parses as a call on the import.
+const globalWithAct = globalThis as any
+globalWithAct.IS_REACT_ACT_ENVIRONMENT = true
+
+defineAdminConfig({
+  i18n: {
+    admin: { defaultLocale: 'en', locales: ['en'] },
+    content: { defaultLocale: 'en', locales: ['en'] },
+  },
+  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: Field[] = [
+  { name: 'title', label: 'Title', type: 'text' },
+  { name: 'featured', label: 'Featured', type: 'text' },
+  { name: 'seoTitle', label: 'SEO title', type: 'text' },
+]
+
+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<React.ComponentProps<typeof FormLayout>> = {}) => {
+  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
+          }
+        >
+          <FormProvider initialData={{ fields: {} }} collectionPath="pages">
+            <FormLayout
+              fields={fields}
+              activeTabBySet={{}}
+              onTabChange={() => {}}
+              {...(props as any)}
+            />
+          </FormProvider>
+        </BylineFieldServicesProvider>
+      </I18nProvider>
+    )
+  })
+}
+
+const config = (c: Partial<AdminResourceConfig>) => c as AdminResourceConfig
+
+describe('FormLayout regions', () => {
+  it('renders main-region fields', () => {
+    render({ adminConfig: config({ layout: { main: ['title'] } }) })
+    expect(container.querySelector('input[name="title"]')).not.toBeNull()
+  })
+
+  it('renders layout.sidebar schema fields', () => {
+    render({ adminConfig: config({ layout: { main: ['title'], sidebar: ['featured'] } }) })
+    const sidebar = container.querySelector('.byline-form-sidebar')
+    expect(sidebar?.querySelector('input[name="featured"]')).not.toBeNull()
+    expect(container.querySelector('.byline-form-content input[name="featured"]')).toBeNull()
+  })
+
+  it('omits a region that was not requested', () => {
+    render({
+      adminConfig: config({ layout: { main: ['title'], sidebar: ['featured'] } }),
+      regions: ['main'],
+    })
+    expect(container.querySelector('.byline-form-sidebar')).toBeNull()
+    expect(container.querySelector('input[name="title"]')).not.toBeNull()
+  })
+
+  it('renders both regions in one column in the stacked variant', () => {
+    render({
+      adminConfig: config({ layout: { main: ['title'], sidebar: ['featured'] } }),
+      variant: 'stacked',
+    })
+    expect(container.querySelector('input[name="title"]')).not.toBeNull()
+    expect(container.querySelector('input[name="featured"]')).not.toBeNull()
+    expect(container.querySelector('.byline-form-sidebar')).toBeNull()
+  })
+})
+
+describe('FormLayout region order', () => {
+  // The prop is an ordered list, and both the interface and the plan promise
+  // order. Reducing it to membership checks silently always renders main first.
+  const both = config({ layout: { main: ['title'], sidebar: ['featured'] } })
+
+  const fieldOrder = () =>
+    [...container.querySelectorAll('input')].map((i) => i.getAttribute('name'))
+
+  it('honours a reversed region order in the split variant', () => {
+    render({ adminConfig: both, regions: ['sidebar', 'main'] })
+    expect(fieldOrder()).toEqual(['featured', 'title'])
+  })
+
+  it('honours a reversed region order in the stacked variant', () => {
+    render({ adminConfig: both, regions: ['sidebar', 'main'], variant: 'stacked' })
+    expect(fieldOrder()).toEqual(['featured', 'title'])
+  })
+
+  it('keeps the slot ahead of the schema fields within the sidebar', () => {
+    render({
+      adminConfig: both,
+      regions: ['sidebar', 'main'],
+      sidebarSlot: <div data-testid="path-widget" />,
+    })
+    const marks = [...container.querySelectorAll('input, [data-testid="path-widget"]')].map(
+      (n) => n.getAttribute('data-testid') ?? n.getAttribute('name')
+    )
+    expect(marks).toEqual(['path-widget', 'featured', 'title'])
+  })
+})
+
+describe('FormLayout stacked variant', () => {
+  // The split layout's own class becomes a two-column grid at >=60rem
+  // (form-renderer.module.css). Carrying it on a stacked form reserves an empty
+  // second track, which defeats the one-column variant. jsdom cannot measure
+  // that, so the guard is that the split class is not applied at all.
+  it('does not carry the two-column split layout class', () => {
+    render({
+      adminConfig: config({ layout: { main: ['title'], sidebar: ['featured'] } }),
+      variant: 'stacked',
+    })
+    const root = container.querySelector('[class*="layout"]')
+    expect(root?.className).toContain('byline-form-layout-stacked')
+    expect(root?.classList.contains('byline-form-layout')).toBe(false)
+  })
+
+  it('keeps the split class on the split variant', () => {
+    render({ adminConfig: config({ layout: { main: ['title'] } }) })
+    const root = container.querySelector('.byline-form-layout')
+    expect(root).not.toBeNull()
+    expect(root?.className).not.toContain('stacked')
+  })
+})
+
+describe('FormLayout sidebar slot', () => {
+  it('renders page-level widgets before the sidebar schema fields', () => {
+    // Deliberate deviation from the plan's Task 2 test, decided by Tony:
+    // the current editor renders page widgets first, and Phase 1's acceptance
+    // is behaviour preservation. Reversing the order here would visibly move
+    // `publishedOn` above the path widget in the shipped docs collection.
+    render({
+      adminConfig: config({ layout: { main: ['title'], sidebar: ['featured'] } }),
+      sidebarSlot: <div data-testid="path-widget" />,
+    })
+    const sidebar = container.querySelector('.byline-form-sidebar')
+    const order = [...(sidebar?.children ?? [])].map(
+      (n) => n.getAttribute('data-testid') ?? n.querySelector('input')?.getAttribute('name') ?? '?'
+    )
+    expect(order).toEqual(['path-widget', 'featured'])
+  })
+
+  it('renders a sidebar for the slot even when no sidebar fields are declared', () => {
+    render({
+      adminConfig: config({ layout: { main: ['title'] } }),
+      sidebarSlot: <div data-testid="path-widget" />,
+    })
+    expect(container.querySelector('[data-testid="path-widget"]')).not.toBeNull()
+  })
+})
+
+describe('FormLayout tabs', () => {
+  const tabbed = config({
+    layout: { main: ['content'] },
+    tabSets: [
+      {
+        name: 'content',
+        tabs: [
+          { name: 'general', label: 'General', fields: ['title'] },
+          { name: 'seo', label: 'SEO', fields: ['seoTitle'] },
+        ],
+      },
+    ],
+  })
+
+  it('renders the tab named by the controlled activeTabBySet prop', () => {
+    render({ adminConfig: tabbed, activeTabBySet: { content: 'seo' } })
+    expect(container.querySelector('input[name="seoTitle"]')).not.toBeNull()
+    expect(container.querySelector('input[name="title"]')).toBeNull()
+  })
+
+  it('falls back to the first tab when the set has no selection', () => {
+    render({ adminConfig: tabbed, activeTabBySet: {} })
+    expect(container.querySelector('input[name="title"]')).not.toBeNull()
+  })
+
+  it('reports a tab change upward rather than selecting it itself', () => {
+    // Selection stays owned above the keyed FormProvider so tab choices
+    // survive the locale-change remount. FormLayout must not self-select.
+    const onTabChange = vi.fn()
+    render({ adminConfig: tabbed, activeTabBySet: { content: 'general' }, onTabChange })
+
+    const seoTab = [...container.querySelectorAll('button')].find((b) => b.textContent === 'SEO')
+    if (seoTab == null) throw new Error('SEO tab not found')
+    act(() => {
+      seoTab.click()
+    })
+
+    expect(onTabChange).toHaveBeenCalledWith('content', 'seo')
+    expect(container.querySelector('input[name="seoTitle"]')).toBeNull()
+  })
+
+  it('hides a tab whose condition is unmet and falls back to a visible one', () => {
+    const conditional = config({
+      layout: { main: ['content'] },
+      tabSets: [
+        {
+          name: 'content',
+          tabs: [
+            { name: 'general', label: 'General', fields: ['title'] },
+            {
+              name: 'seo',
+              label: 'SEO',
+              fields: ['seoTitle'],
+              condition: (data: Record<string, any>) => data.title === 'show-seo',
+            },
+          ],
+        },
+      ],
+    })
+    render({ adminConfig: conditional, activeTabBySet: { content: 'seo' } })
+
+    const tabLabels = [...container.querySelectorAll('button')].map((b) => b.textContent)
+    expect(tabLabels).not.toContain('SEO')
+    expect(container.querySelector('input[name="title"]')).not.toBeNull()
+  })
+})

package/src/forms/form-layout.tsx

@@ -0,0 +1,198 @@
+'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 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)
+
+  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 = `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>
+  )
+}