@byline/admin 6.2.0 → 6.3.0

package/dist/forms/use-form-submission.d.ts

@@ -0,0 +1,74 @@
+import type { Field } from '@byline/core';
+import type { DocumentPatch } from '@byline/core/patches';
+/**
+ * Payload emitted by the form on Save. Carries the content (field data +
+ * patches) alongside the document-grain system fields (path / advertised
+ * locales) and per-bucket dirty flags so the host can route each piece to the
+ * right write path — versioned for content, immediate/non-versioned for the
+ * system fields. See docs/08-internationalization/index.md.
+ */
+export interface SystemFieldsSubmitPayload {
+    data: any;
+    patches: DocumentPatch[];
+    contentDirty: boolean;
+    pathDirty: boolean;
+    systemPath?: string | null;
+    availableLocalesDirty: boolean;
+    systemAvailableLocales?: string[];
+}
+/**
+ * Where a save has got to. Mutually exclusive by construction: the form cannot
+ * be validating and uploading at once, which two independent booleans allowed.
+ */
+export type SubmissionPhase = {
+    kind: 'idle';
+} | {
+    kind: 'validating';
+} | {
+    kind: 'uploading';
+} | {
+    kind: 'confirmingSystemFields';
+    payload: SystemFieldsSubmitPayload;
+} | {
+    kind: 'submitting';
+};
+export interface UseFormSubmissionOptions {
+    mode: 'create' | 'edit';
+    fields: Field[];
+    /** Persisted document id (edit mode only); feeds server-side upload hooks. */
+    documentId?: string;
+    /**
+     * Only collections that opted into the advertised-locale widget emit the
+     * locale set, so the write path never touches
+     * `byline_document_available_locales` for the others.
+     */
+    advertiseLocales?: boolean;
+    onSubmit: (payload: SystemFieldsSubmitPayload) => void | Promise<void>;
+    /** Mutations blocked (stale/lock/discarding). Read synchronously, per call. */
+    isBlocked: () => boolean;
+    /**
+     * Called immediately before the form becomes `inert` — once before uploads
+     * and once before submission — so the caller can record the focused element
+     * and restore it when busy ends. The DOM refs stay in the component; the
+     * hook only signals the transition.
+     */
+    onBeforeBusy?: () => void;
+}
+export interface UseFormSubmissionResult {
+    phase: SubmissionPhase;
+    isBusy: boolean;
+    submit: () => Promise<void>;
+    confirmSystemFields: () => Promise<void>;
+    cancelSystemFields: () => void;
+}
+/**
+ * Owns one save: validate → upload → (confirm) → submit.
+ *
+ * Admission is decided by a ref, not by `phase`. Rendered state is not a
+ * re-entry guard: two `submit()` calls in the same turn both observe
+ * `phase.kind === 'idle'` because React has not rerendered between them. The
+ * ref is set synchronously at the top of `submit()` and cleared in `finally`,
+ * spanning validation through submission — the whole window, not just the
+ * final request. `phase` drives the UI; the ref decides admission.
+ */
+export declare function useFormSubmission(options: UseFormSubmissionOptions): UseFormSubmissionResult;

package/dist/forms/use-form-submission.js

@@ -0,0 +1,166 @@
+"use client";
+import { useCallback, useRef, useState } from "react";
+import { useTranslation } from "@byline/i18n/react";
+import { useBylineFieldServices } from "../fields/field-services-context.js";
+import { useFormContext } from "./form-context.js";
+import { executeUploadsWithProgress } from "./upload-executor.js";
+const IDLE = {
+    kind: 'idle'
+};
+function useFormSubmission(options) {
+    const { mode, fields, documentId, advertiseLocales, onSubmit, isBlocked, onBeforeBusy } = options;
+    const { getFieldValues, runFieldHooks, validateForm, resetHasChanges, getPatches, getDirtyBreakdown, getSystemPath, getSystemAvailableLocales, setFieldValue, setFieldError, getPendingUploads, clearPendingUploads, setFieldUploading } = useFormContext();
+    const { t } = useTranslation('byline-admin');
+    const { uploadField } = useBylineFieldServices();
+    const [phase, setPhase] = useState(IDLE);
+    const inFlightRef = useRef(false);
+    const isBusy = 'uploading' === phase.kind || 'submitting' === phase.kind;
+    const deliver = useCallback(async (payload)=>{
+        if (isBlocked() || 'function' != typeof onSubmit) return void setPhase(IDLE);
+        onBeforeBusy?.();
+        setPhase({
+            kind: 'submitting'
+        });
+        try {
+            await onSubmit(payload);
+            resetHasChanges();
+        } catch  {} finally{
+            setPhase(IDLE);
+        }
+    }, [
+        isBlocked,
+        onBeforeBusy,
+        onSubmit,
+        resetHasChanges
+    ]);
+    const runUploads = useCallback(async ()=>{
+        const pendingUploads = getPendingUploads();
+        if (0 === pendingUploads.size) return true;
+        onBeforeBusy?.();
+        setPhase({
+            kind: 'uploading'
+        });
+        try {
+            const uploadResult = await executeUploadsWithProgress(pendingUploads, uploadField, ({ fieldPath, status })=>{
+                setFieldUploading(fieldPath, 'uploading' === status);
+            }, {
+                documentId: 'edit' === mode ? documentId : void 0,
+                fields,
+                getFormValues: getFieldValues
+            });
+            if (!uploadResult.allSucceeded) {
+                for (const [fieldPath, errorMessage] of uploadResult.errors.entries())setFieldError(fieldPath, t('forms.uploadFailedFieldError', {
+                    message: errorMessage
+                }));
+                console.error('One or more uploads failed:', uploadResult.errors);
+                return false;
+            }
+            for (const [fieldPath, storedFile] of uploadResult.successful.entries())setFieldValue(fieldPath, storedFile);
+            clearPendingUploads();
+            return true;
+        } catch (err) {
+            console.error('Upload execution error:', err);
+            return false;
+        }
+    }, [
+        clearPendingUploads,
+        documentId,
+        fields,
+        getFieldValues,
+        getPendingUploads,
+        mode,
+        onBeforeBusy,
+        setFieldError,
+        setFieldUploading,
+        setFieldValue,
+        t,
+        uploadField
+    ]);
+    const buildPayload = useCallback(()=>{
+        const { contentDirty, pathDirty, availableLocalesDirty, reason } = getDirtyBreakdown();
+        return {
+            reason,
+            payload: {
+                data: getFieldValues(),
+                patches: getPatches(),
+                contentDirty,
+                pathDirty,
+                systemPath: getSystemPath(),
+                availableLocalesDirty,
+                systemAvailableLocales: advertiseLocales ? getSystemAvailableLocales() : void 0
+            }
+        };
+    }, [
+        advertiseLocales,
+        getDirtyBreakdown,
+        getFieldValues,
+        getPatches,
+        getSystemAvailableLocales,
+        getSystemPath
+    ]);
+    const submit = useCallback(async ()=>{
+        if (isBlocked()) return;
+        if (inFlightRef.current) return;
+        inFlightRef.current = true;
+        try {
+            setPhase({
+                kind: 'validating'
+            });
+            const hookErrors = await runFieldHooks(fields);
+            const formErrors = validateForm(fields);
+            const allErrors = [
+                ...hookErrors,
+                ...formErrors
+            ];
+            if (allErrors.length > 0) {
+                console.error('Form validation failed:', allErrors);
+                setPhase(IDLE);
+                return;
+            }
+            if (isBlocked()) return void setPhase(IDLE);
+            if (!await runUploads()) return void setPhase(IDLE);
+            const { payload, reason } = buildPayload();
+            if ('edit' === mode && ('direct-write' === reason || 'both' === reason)) return void setPhase({
+                kind: 'confirmingSystemFields',
+                payload
+            });
+            await deliver(payload);
+        } finally{
+            inFlightRef.current = false;
+        }
+    }, [
+        buildPayload,
+        deliver,
+        fields,
+        isBlocked,
+        mode,
+        runUploads,
+        runFieldHooks,
+        validateForm
+    ]);
+    const confirmSystemFields = useCallback(async ()=>{
+        if ('confirmingSystemFields' !== phase.kind) return;
+        if (inFlightRef.current) return;
+        inFlightRef.current = true;
+        const { payload } = phase;
+        try {
+            await deliver(payload);
+        } finally{
+            inFlightRef.current = false;
+        }
+    }, [
+        deliver,
+        phase
+    ]);
+    const cancelSystemFields = useCallback(()=>{
+        setPhase((current)=>'confirmingSystemFields' === current.kind ? IDLE : current);
+    }, []);
+    return {
+        phase,
+        isBusy,
+        submit,
+        confirmSystemFields,
+        cancelSystemFields
+    };
+}
+export { useFormSubmission };

package/dist/forms/use-form-tabs.d.ts

@@ -0,0 +1,29 @@
+import type { TabDefinition, TabSetDefinition } from '@byline/core';
+/** One tab set, resolved against live form data and current errors. */
+export interface ResolvedTabSet {
+    /** Tabs whose `condition` is satisfied, in declaration order. */
+    visibleTabs: TabDefinition[];
+    /** The tab that should render, after falling back off a hidden selection. */
+    activeTabName: string;
+    activeTab: TabDefinition | undefined;
+    /** Error count per tab name, for the tab bar's badges. */
+    errorCounts: Record<string, number> | undefined;
+}
+export interface UseFormTabsResult {
+    resolve: (set: TabSetDefinition) => ResolvedTabSet;
+    errorCountsBySet: Record<string, Record<string, number>>;
+}
+/**
+ * Tab visibility, per-tab error counts, and fallback when the selected tab is
+ * hidden.
+ *
+ * It deliberately does **not** own the selection. `FormRenderer` lifts that
+ * above the keyed `FormProvider` so the editor's tab choices survive the
+ * remount a locale change triggers; a hook living inside that subtree would
+ * lose them on every switch. The selection arrives as `activeTabBySet` and
+ * changes are reported upward.
+ */
+export declare function useFormTabs(fieldToTabPath: Map<string, {
+    tabSetName: string;
+    tabName: string;
+}>, activeTabBySet: Record<string, string>): UseFormTabsResult;

package/dist/forms/use-form-tabs.js

@@ -0,0 +1,45 @@
+"use client";
+import { useEffect, useMemo, useState } from "react";
+import { useFormContext } from "./form-context.js";
+function useFormTabs(fieldToTabPath, activeTabBySet) {
+    const { errors: initialErrors, subscribeErrors, subscribeMeta, getFieldValues } = useFormContext();
+    const [errors, setErrors] = useState(initialErrors);
+    useEffect(()=>subscribeErrors((newErrors)=>setErrors(newErrors)), [
+        subscribeErrors
+    ]);
+    const [formData, setFormData] = useState(()=>getFieldValues());
+    useEffect(()=>subscribeMeta(()=>setFormData(getFieldValues())), [
+        subscribeMeta,
+        getFieldValues
+    ]);
+    const errorCountsBySet = useMemo(()=>{
+        const result = {};
+        for (const err of errors){
+            const path = fieldToTabPath.get(err.field);
+            if (path) {
+                result[path.tabSetName] ??= {};
+                result[path.tabSetName][path.tabName] = (result[path.tabSetName]?.[path.tabName] ?? 0) + 1;
+            }
+        }
+        return result;
+    }, [
+        errors,
+        fieldToTabPath
+    ]);
+    const resolve = (set)=>{
+        const visibleTabs = set.tabs.filter((tab)=>!tab.condition || tab.condition(formData));
+        const requested = activeTabBySet[set.name] ?? '';
+        const activeTabName = visibleTabs.length > 0 && !visibleTabs.some((t)=>t.name === requested) ? visibleTabs[0]?.name ?? requested : requested;
+        return {
+            visibleTabs,
+            activeTabName,
+            activeTab: visibleTabs.find((t)=>t.name === activeTabName),
+            errorCounts: errorCountsBySet[set.name]
+        };
+    };
+    return {
+        resolve,
+        errorCountsBySet
+    };
+}
+export { useFormTabs };

package/dist/presentation/tabs.js

@@ -30,6 +30,7 @@ const AdminTabs = ({ tabs, activeTab, onChange, idBase, errorCounts, className }
     const tabRefs = useRef(new Map());
     const focusAfterChange = useRef(null);
     const [strip, setStrip] = useState(INITIAL_STRIP_STATE);
+    const tabsKey = tabs.map((tab)=>`${tab.name}:${tab.label}`).join('\u0000');
     const measure = useCallback(()=>{
         const container = containerRef.current;
         const row = rowRef.current;
@@ -54,7 +55,7 @@ const AdminTabs = ({ tabs, activeTab, onChange, idBase, errorCounts, className }
         return ()=>observer.disconnect();
     }, [
         measure,
-        tabs
+        tabsKey
     ]);
     const reveal = useCallback((name)=>{
         const viewport = viewportRef.current;

package/dist/react.d.ts

@@ -67,4 +67,4 @@ export * from './presentation/tabs.js';
 export * from './widgets/diff-viewer/diff-modal.js';
 export * from './widgets/source-locale-badge/source-locale-badge.js';
 export * from './widgets/status-badge/status-badge.js';
-export type { BylineFieldServices, CollectionListDoc, CollectionListParams, CollectionListResponse, GetCollectionDocumentsFn, GetTreeAncestorsFn, GetTreeParentFn, PlaceTreeNodeFn, PlaceTreeNodeInput, RemoveFromTreeFn, TreeAncestor, UploadedFileResult, UploadFieldFn, } from './fields/field-services-types.js';
+export type { BylineFieldServices, CanCreateInCollectionFn, CollectionListDoc, CollectionListParams, CollectionListResponse, GetCollectionDocumentsFn, GetCreateDocumentUrlFn, GetTreeAncestorsFn, GetTreeParentFn, PlaceTreeNodeFn, PlaceTreeNodeInput, RemoveFromTreeFn, TreeAncestor, UploadedFileResult, UploadFieldFn, } from './fields/field-services-types.js';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/admin",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.2.0",
+  "version": "6.3.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -183,12 +183,12 @@
     "react-diff-viewer-continued": "^4.4.0",
     "uuid": "^14.0.2",
     "zod": "^4.6.2",
-    "@byline/analytics": "6.2.0",
-    "@byline/analytics-agent": "6.2.0",
-    "@byline/core": "6.2.0",
-    "@byline/auth": "6.2.0",
-    "@byline/i18n": "6.2.0",
-    "@byline/ui": "6.2.0"
+    "@byline/analytics": "6.3.0",
+    "@byline/core": "6.3.0",
+    "@byline/i18n": "6.3.0",
+    "@byline/auth": "6.3.0",
+    "@byline/ui": "6.3.0",
+    "@byline/analytics-agent": "6.3.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

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

@@ -10,6 +10,7 @@ import type { CheckboxField as FieldType } from '@byline/core'
 import { Checkbox } from '@byline/ui/react'
 
 import { useFieldError, useFieldValue } from '../../forms/form-context'
+import { useScopedDomId } from '../../forms/form-dom-scope'
 import styles from './checkbox-field.module.css'
 
 export const CheckboxField = ({
@@ -28,6 +29,7 @@ export const CheckboxField = ({
   path?: string
 }) => {
   const fieldPath = path ?? field.name
+  const htmlId = useScopedDomId(fieldPath, id)
   const fieldError = useFieldError(fieldPath)
   const fieldValue = useFieldValue<boolean | undefined>(fieldPath)
   const checked = value ?? fieldValue ?? defaultValue ?? false
@@ -35,7 +37,7 @@ export const CheckboxField = ({
   return (
     <div className={`byline-field-checkbox ${field.name} ${styles['field-checkbox']}`}>
       <Checkbox
-        id={id ?? fieldPath}
+        id={htmlId}
         name={field.name}
         label={field.label}
         checked={checked}

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

@@ -13,6 +13,7 @@ import { ErrorText, HelpText, 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 './code-field.module.css'
 
@@ -57,7 +58,7 @@ export const CodeField = ({
   const fieldError = useFieldError(fieldPath)
   const fieldValue = useFieldValue<string | undefined>(fieldPath)
   const incomingValue = value ?? fieldValue ?? defaultValue ?? ''
-  const htmlId = id ?? fieldPath
+  const htmlId = useScopedDomId(fieldPath, id)
 
   // Effective highlight language: a sibling `languageField` selection (e.g.
   // a `select` next to the code field) wins over the schema's static

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

@@ -11,6 +11,7 @@ import { DatePicker, ErrorText } from '@byline/ui/react'
 import cx from 'clsx'
 
 import { useFieldError, useFieldValue, useIsDirty } from '../../forms/form-context'
+import { useScopedDomId } from '../../forms/form-dom-scope'
 import styles from './datetime-field.module.css'
 
 export const DateTimeField = ({
@@ -29,6 +30,7 @@ export const DateTimeField = ({
   path?: string
 }) => {
   const fieldPath = path ?? field.name
+  const htmlId = useScopedDomId(fieldPath, id)
   const fieldError = useFieldError(fieldPath)
   const isDirty = useIsDirty(fieldPath)
   const fieldValue = useFieldValue<Date | null | undefined>(fieldPath)
@@ -37,7 +39,7 @@ export const DateTimeField = ({
   return (
     <div className={`byline-field-datetime ${field.name}`}>
       <DatePicker
-        id={id ?? fieldPath}
+        id={htmlId}
         name={field.name}
         label={field.label}
         required={!field.optional}
@@ -48,7 +50,7 @@ export const DateTimeField = ({
         onDateChange={(date) => onChange?.(date)}
         className={cx(isDirty && ['byline-field-datetime-dirty', styles.dirty])}
       />
-      {fieldError && <ErrorText id={`${field.name}-error`} text={fieldError} />}
+      {fieldError && <ErrorText id={`${htmlId}-error`} text={fieldError} />}
     </div>
   )
 }

package/src/fields/direct-widget-dom-ids.test.tsx

@@ -0,0 +1,142 @@
+/**
+ * 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 { Field } 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 { FormProvider } from '../forms/form-context'
+import { CheckboxField } from './checkbox/checkbox-field'
+import { DateTimeField } from './datetime/datetime-field'
+import { TextField } from './text/text-field'
+
+const globalWithAct = globalThis as any
+globalWithAct.IS_REACT_ACT_ENVIRONMENT = true
+
+let container: HTMLDivElement
+let root: Root
+
+beforeEach(() => {
+  container = document.createElement('div')
+  document.body.appendChild(container)
+  root = createRoot(container)
+})
+
+afterEach(() => {
+  act(() => {
+    root.unmount()
+  })
+  container.remove()
+})
+
+/**
+ * These widgets are re-exported from `@byline/admin/react`, so a host can compose
+ * them directly rather than through `FieldRenderer`. Going through `FieldRenderer`
+ * would hand them an already-scoped `id` and prove nothing about their own
+ * fallback, which is the path a direct consumer takes.
+ */
+const renderDirect = (node: (formName: string) => React.ReactNode) => {
+  act(() => {
+    root.render(
+      <I18nProvider
+        bundle={adminTranslations({ locales: ['en'] })}
+        activeLocale="en"
+        defaultLocale="en"
+        localeDefinitions={[{ code: 'en', nativeName: 'English' }]}
+      >
+        {['parent', 'child'].map((formName) => (
+          <form aria-label={formName} key={formName}>
+            <FormProvider initialData={{ fields: {} }} collectionPath="pages">
+              {node(formName)}
+            </FormProvider>
+          </form>
+        ))}
+      </I18nProvider>
+    )
+  })
+}
+
+const controlIds = (selector: string) =>
+  Array.from(container.querySelectorAll(selector)).map((node) => node.id)
+
+describe('widgets composed directly under two form providers', () => {
+  it('gives a text field distinct ids without FieldRenderer supplying one', () => {
+    const field = { name: 'title', label: 'Title', type: 'text' } as Field
+    renderDirect(() => <TextField field={field as any} />)
+
+    const ids = controlIds('input')
+    expect(ids).toHaveLength(2)
+    expect(ids.every((id) => id !== '')).toBe(true)
+    expect(new Set(ids).size).toBe(2)
+  })
+
+  it('gives a checkbox distinct ids', () => {
+    const field = { name: 'featured', label: 'Featured', type: 'checkbox' } as Field
+    renderDirect(() => <CheckboxField field={field as any} />)
+
+    const ids = Array.from(container.querySelectorAll('[role="checkbox"], input[type="checkbox"]'))
+      .map((node) => node.id)
+      .filter((id) => id !== '')
+
+    expect(ids).toHaveLength(2)
+    expect(new Set(ids).size).toBe(2)
+  })
+
+  it('gives a datetime control distinct ids on the control itself', () => {
+    const field = { name: 'publishedOn', label: 'Published on', type: 'datetime' } as Field
+    renderDirect(() => <DateTimeField field={field as any} />)
+
+    // The scoped id must reach the control the label points at, not only the
+    // error element — the first revision scoped the error and left the input.
+    const ids = controlIds('input').filter((id) => id !== '')
+    expect(ids.length).toBeGreaterThanOrEqual(2)
+    expect(new Set(ids).size).toBe(ids.length)
+  })
+
+  it('associates each directly composed label with the control in its own form', () => {
+    const field = { name: 'title', label: 'Title', type: 'text' } as Field
+    renderDirect(() => <TextField field={field as any} />)
+
+    const labels = Array.from(container.querySelectorAll('label[for]'))
+    expect(labels.length).toBeGreaterThanOrEqual(2)
+
+    for (const label of labels) {
+      const target = document.getElementById(label.getAttribute('for') as string)
+      expect(target).not.toBeNull()
+      expect(target?.closest('form')).toBe(label.closest('form'))
+    }
+  })
+
+  /**
+   * An explicit id belongs to the caller: it may already be referenced from
+   * outside the form, and scoping it would break that reference. Two forms given
+   * the same explicit id therefore still collide — that is the caller's choice,
+   * and the test records it as intended rather than accidental.
+   */
+  it('passes a caller-supplied id through unchanged in every direct widget', () => {
+    const text = { name: 'title', label: 'Title', type: 'text' } as Field
+    renderDirect(() => <TextField field={text as any} id="explicit-text" />)
+    expect(controlIds('input')).toEqual(['explicit-text', 'explicit-text'])
+
+    const checkbox = { name: 'featured', label: 'Featured', type: 'checkbox' } as Field
+    renderDirect(() => <CheckboxField field={checkbox as any} id="explicit-checkbox" />)
+    expect(
+      Array.from(container.querySelectorAll('[id="explicit-checkbox"]')).length
+    ).toBeGreaterThanOrEqual(2)
+
+    const datetime = { name: 'publishedOn', label: 'On', type: 'datetime' } as Field
+    renderDirect(() => <DateTimeField field={datetime as any} id="explicit-datetime" />)
+    expect(
+      Array.from(container.querySelectorAll('[id="explicit-datetime"]')).length
+    ).toBeGreaterThanOrEqual(2)
+  })
+})