@byline/admin 6.2.1 → 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.tsx

@@ -24,6 +24,7 @@ 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'
@@ -75,6 +76,11 @@ export const FormLayout = ({
   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)
@@ -117,7 +123,7 @@ export const FormLayout = ({
 
   const renderTabSet = (set: TabSetDefinition): ReactNode => {
     const { visibleTabs, activeTabName, activeTab, errorCounts } = tabs.resolve(set)
-    const idBase = `tabset:${set.name}`
+    const idBase = `${domScope}tabset:${set.name}`
 
     return (
       <div key={idBase} className={cx('byline-form-tabset', styles.tabset)}>

package/src/forms/form-renderer.tsx

@@ -422,6 +422,17 @@ const FormContent = ({
   }
 
   const handleSubmit = (e: React.SubmitEvent<HTMLFormElement>) => {
+    // A form rendered into a portal is not a DOM descendant of this one, so no
+    // invalid nested-form markup arises — but React propagates synthetic events
+    // along the *React* tree, so its submit still reaches this handler. Nothing
+    // about `currentTarget` reveals that: it is always this form while the
+    // handler runs, bubbled event or not. The event's origin is what
+    // distinguishes them.
+    //
+    // Deliberately no `preventDefault()` on the way out: the submit belongs to
+    // the inner form, and suppressing its default here would take that decision
+    // away from the handler that owns it.
+    if (e.target !== e.currentTarget) return
     e.preventDefault()
     if (mutationBlockedRef.current) return
     void submission.submit()

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

@@ -0,0 +1,247 @@
+/**
+ * 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 { createPortal } from 'react-dom'
+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 { 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'] },
+  },
+  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 fieldServices = {
+  getCollectionDocuments: async () => ({ docs: [], total: 0 }),
+  uploadField: async () => ({}),
+} as any
+
+// Optional so submission is not blocked by validation: this file tests which
+// form a submit event belongs to, not what the form does with it.
+const fields = [{ name: 'title', label: 'Title', type: 'text' as const, optional: true }]
+
+let container: HTMLDivElement
+let root: Root
+let portalHost: HTMLDivElement
+
+beforeEach(() => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  portalHost = document.createElement('div')
+  document.body.appendChild(portalHost)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => {
+    root.unmount()
+  })
+  container.remove()
+  portalHost.remove()
+})
+
+/**
+ * A nested form rendered through a portal: outside the parent `<form>` in the
+ * DOM, so no invalid nested-form markup arises, but still a descendant in the
+ * *React* tree — which is what React propagates synthetic events along.
+ */
+const PortalledInnerForm = ({
+  stopPropagation,
+  onInnerSubmit,
+}: {
+  stopPropagation: boolean
+  onInnerSubmit: () => void
+}) =>
+  createPortal(
+    <form
+      data-testid="inner-form"
+      onSubmit={(event) => {
+        event.preventDefault()
+        if (stopPropagation) event.stopPropagation()
+        onInnerSubmit()
+      }}
+    >
+      <input name="innerTitle" defaultValue="" />
+      <button type="submit">Save inner</button>
+    </form>,
+    portalHost
+  )
+
+const renderWithInnerForm = ({
+  parentSubmit,
+  onInnerSubmit = () => {},
+  stopPropagation = false,
+}: {
+  parentSubmit: () => Promise<void>
+  onInnerSubmit?: () => void
+  stopPropagation?: boolean
+}) => {
+  act(() => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        <BylineFieldServicesProvider services={fieldServices}>
+          <FormRenderer
+            mode="create"
+            fields={fields}
+            collectionPath="pages"
+            onCancel={() => {}}
+            onSubmit={parentSubmit}
+            headerSlot={
+              <PortalledInnerForm stopPropagation={stopPropagation} onInnerSubmit={onInnerSubmit} />
+            }
+          />
+        </BylineFieldServicesProvider>
+      </I18nProvider>
+    )
+  })
+}
+
+const parentForm = () => {
+  const form = container.querySelector('form')
+  if (form == null) throw new Error('parent form not found')
+  return form
+}
+
+const innerForm = () => {
+  const form = portalHost.querySelector<HTMLFormElement>('[data-testid="inner-form"]')
+  if (form == null) throw new Error('inner form not found')
+  return form
+}
+
+const submit = async (form: HTMLFormElement) => {
+  await act(async () => {
+    form.dispatchEvent(new Event('submit', { bubbles: true, cancelable: true }))
+  })
+}
+
+describe('submit isolation across a portal', () => {
+  /**
+   * The inner form here deliberately does **not** call `stopPropagation`, so
+   * these two cases exercise the parent's own guard. With the child-side defence
+   * in place as well, a broken parent guard would be invisible.
+   */
+  it('does not run the parent submit handler when a portalled inner form submits', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    renderWithInnerForm({ parentSubmit })
+
+    await submit(innerForm())
+
+    expect(parentSubmit).not.toHaveBeenCalled()
+  })
+
+  it('still runs the inner form’s own handler', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    const onInnerSubmit = vi.fn()
+    renderWithInnerForm({ parentSubmit, onInnerSubmit })
+
+    await submit(innerForm())
+
+    expect(onInnerSubmit).toHaveBeenCalledTimes(1)
+    expect(parentSubmit).not.toHaveBeenCalled()
+  })
+
+  it('still submits normally from the parent form itself', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    renderWithInnerForm({ parentSubmit })
+
+    await submit(parentForm())
+
+    expect(parentSubmit).toHaveBeenCalledTimes(1)
+  })
+
+  it('leaves the parent form submitting on repeat after an inner submit', async () => {
+    const parentSubmit = vi.fn(async () => {})
+    renderWithInnerForm({ parentSubmit })
+
+    await submit(innerForm())
+    await submit(parentForm())
+    await submit(parentForm())
+
+    expect(parentSubmit).toHaveBeenCalledTimes(2)
+  })
+})
+
+/**
+ * The child-side defence, proved without the parent guard in the picture. If this
+ * were asserted against `FormRenderer`, a working parent guard would satisfy it
+ * whether or not the child stopped propagation, and the test would prove nothing
+ * about the child.
+ */
+describe('the child-side stopPropagation defence', () => {
+  const PlainParent = ({
+    onParentSubmit,
+    stopPropagation,
+  }: {
+    onParentSubmit: () => void
+    stopPropagation: boolean
+  }) => (
+    <form
+      data-testid="plain-parent"
+      onSubmit={(event) => {
+        event.preventDefault()
+        onParentSubmit()
+      }}
+    >
+      <PortalledInnerForm stopPropagation={stopPropagation} onInnerSubmit={() => {}} />
+    </form>
+  )
+
+  const renderPlain = (props: { onParentSubmit: () => void; stopPropagation: boolean }) => {
+    act(() => {
+      root.render(<PlainParent {...props} />)
+    })
+  }
+
+  it('keeps an unguarded parent handler from running when the child stops propagation', async () => {
+    const onParentSubmit = vi.fn()
+    renderPlain({ onParentSubmit, stopPropagation: true })
+
+    await submit(innerForm())
+
+    expect(onParentSubmit).not.toHaveBeenCalled()
+  })
+
+  /**
+   * The control: the same unguarded parent, with the child defence removed. It
+   * fails in exactly the way the feature is meant to prevent, which is what makes
+   * the assertion above meaningful.
+   */
+  it('runs an unguarded parent handler when the child does not stop propagation', async () => {
+    const onParentSubmit = vi.fn()
+    renderPlain({ onParentSubmit, stopPropagation: false })
+
+    await submit(innerForm())
+
+    expect(onParentSubmit).toHaveBeenCalledTimes(1)
+  })
+})