@byline/admin 6.2.0 → 6.3.0

package/src/fields/text/text-field.tsx

@@ -13,6 +13,7 @@ import { Input, Label } from '@byline/ui/react'
 import cx from 'clsx'
 
 import { useFieldError, useFieldValue } from '../../forms/form-context'
+import { useScopedDomId } from '../../forms/form-dom-scope'
 import { LocaleBadge } from '../locale-badge'
 import styles from './text-field.module.css'
 
@@ -41,7 +42,7 @@ export const TextField = ({
   const fieldError = useFieldError(fieldPath)
   const fieldValue = useFieldValue<string | undefined>(fieldPath)
   const incomingValue = value ?? fieldValue ?? defaultValue ?? ''
-  const htmlId = id ?? fieldPath
+  const htmlId = useScopedDomId(fieldPath, id)
 
   const handleChange = useCallback(
     (value: string) => {

package/src/fields/text-area/text-area-field.tsx

@@ -13,6 +13,7 @@ import { Label, TextArea } from '@byline/ui/react'
 import cx from 'clsx'
 
 import { useFieldError, useFieldValue } from '../../forms/form-context'
+import { useScopedDomId } from '../../forms/form-dom-scope'
 import { LocaleBadge } from '../locale-badge'
 import styles from './text-area-field.module.css'
 
@@ -41,7 +42,7 @@ export const TextAreaField = ({
   const fieldError = useFieldError(fieldPath)
   const fieldValue = useFieldValue<string | undefined>(fieldPath)
   const incomingValue = value ?? fieldValue ?? defaultValue ?? ''
-  const htmlId = id ?? fieldPath
+  const htmlId = useScopedDomId(fieldPath, id)
 
   const handleChange = useCallback(
     (value: string) => {

package/src/forms/form-context.tsx

@@ -15,6 +15,7 @@ import type { Field, FieldBeforeChangeResult, FieldHookContext } from '@byline/c
 import { normalizeHooks } from '@byline/core'
 import type { DocumentPatch, FieldSetPatch } from '@byline/core/patches'
 
+import { FormDomScopeProvider } from './form-dom-scope'
 // Vendored nested get/set (see ./nested-path) — removes the lodash-es dep
 // outright. A bare `from 'lodash-es'` import otherwise pools into a single
 // ~85KB chunk that leaks onto the public frontend bundle (form-context is
@@ -749,7 +750,7 @@ export const FormProvider = ({
         subscribeSystemAvailableLocales: availableLocalesSlot.subscribe,
       }}
     >
-      {children}
+      <FormDomScopeProvider>{children}</FormDomScopeProvider>
     </FormContext.Provider>
   )
 }

package/src/forms/form-dom-scope.test.tsx

@@ -0,0 +1,213 @@
+/**
+ * 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, hydrateRoot, type Root } from 'react-dom/client'
+import { renderToString } from 'react-dom/server'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { FormProvider } from './form-context'
+import { useFormDomScope, useScopedDomId } from './form-dom-scope'
+
+;(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true
+
+describe('form DOM scope', () => {
+  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 = (node: React.ReactNode) => {
+    act(() => {
+      root.render(node)
+    })
+  }
+
+  it('gives two concurrently mounted providers different scopes', () => {
+    const scopes: string[] = []
+    const Probe = () => {
+      scopes.push(useFormDomScope())
+      return null
+    }
+
+    render(
+      <>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+      </>
+    )
+
+    expect(scopes).toHaveLength(2)
+    expect(new Set(scopes).size).toBe(2)
+  })
+
+  it('derives a stable id for the same base across re-renders', () => {
+    const seen: string[] = []
+    const Probe = () => {
+      seen.push(useScopedDomId('title'))
+      return null
+    }
+
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    expect(seen.length).toBeGreaterThanOrEqual(2)
+    expect(new Set(seen).size).toBe(1)
+  })
+
+  it('scopes the base so two forms derive different ids from one field name', () => {
+    const ids: string[] = []
+    const Probe = () => {
+      ids.push(useScopedDomId('title'))
+      return null
+    }
+
+    render(
+      <>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+        <FormProvider initialData={{}}>
+          <Probe />
+        </FormProvider>
+      </>
+    )
+
+    expect(new Set(ids).size).toBe(2)
+    for (const id of ids) expect(id.endsWith('title')).toBe(true)
+  })
+
+  it('returns a caller-supplied id unchanged rather than scoping it twice', () => {
+    let derived = ''
+    const Probe = () => {
+      derived = useScopedDomId('title', 'explicit-id')
+      return null
+    }
+
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    expect(derived).toBe('explicit-id')
+  })
+
+  /**
+   * Field widgets render outside a form provider in places — the admin user and
+   * role screens compose them directly — so the hook has to degrade to the bare
+   * base rather than throw or invent a scope.
+   */
+  it('falls back to the bare base outside a provider', () => {
+    let derived = ''
+    let scope = 'unset'
+    const Probe = () => {
+      scope = useFormDomScope()
+      derived = useScopedDomId('title')
+      return null
+    }
+
+    render(<Probe />)
+
+    expect(scope).toBe('')
+    expect(derived).toBe('title')
+  })
+
+  it('produces a non-empty scope inside a provider', () => {
+    const scopes: string[] = []
+    const Probe = () => {
+      scopes.push(useFormDomScope())
+      return null
+    }
+
+    render(
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    expect(scopes[0]).not.toBe('')
+  })
+
+  /**
+   * The reason the scope comes from `useId` rather than a counter or a random
+   * value: the server render and the hydration pass must agree. If they do not,
+   * React discards the server-rendered attributes and every `for` and
+   * `aria-labelledby` written during SSR points at an id that no longer exists.
+   *
+   * This renders on the server for real and hydrates that markup, rather than
+   * inspecting the shape of the generated string.
+   */
+  it('derives the same id on the server render and on hydration', async () => {
+    let renderedId = ''
+    const Probe = () => {
+      const id = useScopedDomId('title')
+      renderedId = id
+      return <span id={id}>title</span>
+    }
+    const tree = (
+      <FormProvider initialData={{}}>
+        <Probe />
+      </FormProvider>
+    )
+
+    const html = renderToString(tree)
+    const serverId = /id="([^"]+)"/.exec(html)?.[1]
+    expect(serverId).toBeTruthy()
+
+    const host = document.createElement('div')
+    host.innerHTML = html
+    document.body.appendChild(host)
+
+    // React reports a hydration mismatch through console.error rather than by
+    // throwing, so silence alone is not evidence — collect and assert on it.
+    const consoleErrors: unknown[][] = []
+    const spy = vi.spyOn(console, 'error').mockImplementation((...args: unknown[]) => {
+      consoleErrors.push(args)
+    })
+
+    let hydrated: Root | undefined
+    await act(async () => {
+      hydrated = hydrateRoot(host, tree)
+    })
+    spy.mockRestore()
+
+    expect(consoleErrors).toEqual([])
+    expect(renderedId).toBe(serverId)
+    expect(host.querySelector('span')?.id).toBe(serverId)
+
+    act(() => {
+      hydrated?.unmount()
+    })
+    host.remove()
+  })
+})

package/src/forms/form-dom-scope.tsx

@@ -0,0 +1,70 @@
+'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 type { ReactNode } from 'react'
+import { createContext, useContext, useId } from 'react'
+
+/**
+ * Per-form-instance prefix for derived DOM ids.
+ *
+ * Field widgets derive an element id from the field's path, and tab strips derive
+ * theirs from the tab-set name. Both are unique within one form and identical
+ * between two forms editing the same collection. Mount a second form — the
+ * relationship picker's creation view does exactly that — and every `label`'s
+ * `for`, every `aria-describedby` and every `aria-labelledby` resolves to whichever
+ * element the browser happens to see first, which is the parent form's. The reader
+ * then gets the wrong label announced and a click on a label focuses a field in a
+ * different form.
+ *
+ * `null` rather than `''` as the default so `useFormDomScope` can tell "no provider
+ * above me" from "a provider that produced an empty scope", even though both
+ * currently degrade to the same unprefixed id.
+ */
+const FormDomScopeContext = createContext<string | null>(null)
+
+/**
+ * Establishes one DOM id scope. `FormProvider` wraps its children in this, so a
+ * scope exists wherever form state does and no caller has to opt in.
+ */
+export const FormDomScopeProvider = ({ children }: { children: ReactNode }): ReactNode => {
+  // `useId` is the only generator that agrees between the server render and
+  // hydration. A counter or a random value produces different ids on each side,
+  // React discards the server-rendered attributes, and the `for`/`aria-*` pairings
+  // written during SSR are left pointing at ids that no longer exist.
+  const scope = useId()
+  return <FormDomScopeContext.Provider value={scope}>{children}</FormDomScopeContext.Provider>
+}
+
+/**
+ * The active scope, or `''` when rendered outside a form. Field widgets are also
+ * composed directly by the admin user and role screens, which have no
+ * `FormProvider`, so an absent scope degrades to the unprefixed id rather than
+ * throwing.
+ */
+export function useFormDomScope(): string {
+  return useContext(FormDomScopeContext) ?? ''
+}
+
+/**
+ * Scope a derived DOM id.
+ *
+ * A caller-supplied `id` is returned untouched: it is the author's identifier, it
+ * may already be referenced from outside the form, and scoping it would break that
+ * reference as well as double-prefix ids that pass through here twice.
+ *
+ * The result is a valid HTML id and a valid `for` / `aria-*` reference, but React's
+ * generated scope contains characters that need escaping in a CSS selector. Resolve
+ * these with `document.getElementById`, not `querySelector('#…')`.
+ */
+export function useScopedDomId(base: string, explicit?: string): string {
+  const scope = useFormDomScope()
+  if (explicit != null) return explicit
+  return scope === '' ? base : `${scope}${base}`
+}

package/src/forms/form-layout-styles.test.node.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+// jsdom applies no stylesheet, so the one-column guarantee of the stacked
+// variant cannot be asserted by rendering. This reads the stylesheet directly:
+// the class has to exist, and it must not be swept into the two-column grid
+// rule that the split layout gets at >=60rem.
+const css = readFileSync(join(__dirname, 'form-renderer.module.css'), 'utf8')
+
+describe('stacked form layout styles', () => {
+  it('defines the stacked layout class', () => {
+    expect(css).toMatch(/\.layout-stacked\b/)
+    expect(css).toMatch(/:global\(\.byline-form-layout-stacked\)/)
+  })
+
+  it('does not put the stacked class in the two-column grid rule', () => {
+    const desktop = css.slice(css.indexOf('@media (min-width: 60rem)'))
+    const gridRule = desktop.slice(0, desktop.indexOf('}\n}') + 3)
+    expect(gridRule).toContain('grid-template-columns')
+    expect(gridRule).not.toContain('layout-stacked')
+  })
+})

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