@byline/admin 2.5.2 → 2.6.0

package/dist/forms/form-context.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 React from 'react';
+import type { Field } from '@byline/core';
+import type { DocumentPatch } from '@byline/core/patches';
+interface FormError {
+    field: string;
+    message: string;
+}
+/**
+ * Represents a file that has been selected but not yet uploaded.
+ * The file is held locally until form submission.
+ */
+export interface PendingUpload {
+    /** The actual File object to upload */
+    file: File;
+    /** Blob URL for local preview (must be revoked on cleanup) */
+    previewUrl: string;
+    /** The collection path for the upload endpoint */
+    collectionPath: string;
+}
+type FieldListener = (value: any) => void;
+type ErrorsListener = (errors: FormError[]) => void;
+type MetaListener = () => void;
+type SystemPathListener = (value: string | null) => void;
+type FieldUploadingListener = (uploading: boolean) => void;
+interface FormContextType {
+    setFieldValue: (name: string, value: any) => void;
+    setFieldStore: (name: string, value: any) => void;
+    getFieldValue: (name: string) => any;
+    getFieldValues: () => Record<string, any>;
+    getPatches: () => DocumentPatch[];
+    appendPatch: (patch: DocumentPatch) => void;
+    resetPatches: () => void;
+    hasChanges: () => boolean;
+    resetHasChanges: () => void;
+    runFieldHooks: (fields: Field[]) => Promise<FormError[]>;
+    validateForm: (fields: Field[]) => FormError[];
+    errors: FormError[];
+    getErrors: () => FormError[];
+    clearErrors: () => void;
+    setFieldError: (field: string, message: string) => void;
+    clearFieldError: (field: string) => void;
+    isDirty: (fieldName: string) => boolean;
+    subscribeField: (name: string, listener: FieldListener) => () => void;
+    subscribeErrors: (listener: ErrorsListener) => () => void;
+    subscribeMeta: (listener: MetaListener) => () => void;
+    addPendingUpload: (fieldPath: string, upload: PendingUpload) => void;
+    removePendingUpload: (fieldPath: string) => void;
+    getPendingUploads: () => Map<string, PendingUpload>;
+    hasPendingUploads: () => boolean;
+    clearPendingUploads: () => void;
+    setFieldUploading: (fieldPath: string, uploading: boolean) => void;
+    getIsFieldUploading: (fieldPath: string) => boolean;
+    subscribeFieldUploading: (fieldPath: string, listener: FieldUploadingListener) => () => void;
+    getSystemPath: () => string | null;
+    setSystemPath: (value: string | null) => void;
+    subscribeSystemPath: (listener: SystemPathListener) => () => void;
+}
+export declare const useFormContext: () => FormContextType;
+export declare const FormProvider: ({ children, initialData, }: {
+    children: React.ReactNode;
+    initialData?: Record<string, any>;
+}) => React.JSX.Element;
+/**
+ * Subscribe to the system `path` slot edited by the path widget.
+ * Returns the current value (or `null` when no override is set).
+ */
+export declare const useSystemPath: () => string | null;
+export declare const useFormStore: () => FormContextType;
+export declare const useFieldError: (name: string) => string | undefined;
+export declare const useFormMeta: () => {
+    hasChanges: boolean;
+};
+export declare const useIsDirty: (name: string) => boolean;
+export declare const useFieldValue: <T = any>(name: string) => T | undefined;
+/**
+ * Subscribe to a single field's upload-in-flight state. Returns `true` while
+ * the form orchestrator is actively transporting this field's pending upload
+ * (between the `setFieldUploading(path, true)` and the matching `false`
+ * emitted by the upload executor's progress callback).
+ */
+export declare const useIsFieldUploading: (fieldPath: string) => boolean;
+export {};

package/dist/forms/form-context.js

@@ -0,0 +1,466 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from "react";
+import { normalizeHooks } from "@byline/core";
+import { get, set as external_lodash_es_set } from "lodash-es";
+const FormContext = /*#__PURE__*/ createContext(null);
+const useFormContext = ()=>{
+    const context = useContext(FormContext);
+    if (null == context) throw new Error('useFormContext must be used within a FormProvider');
+    return context;
+};
+const FormProvider = ({ children, initialData = {} })=>{
+    const fieldValues = useRef(JSON.parse(JSON.stringify(initialData?.fields ?? initialData)));
+    const initialValues = useRef(initialData?.fields ?? initialData);
+    const errorsRef = useRef([]);
+    const dirtyFields = useRef(new Set());
+    const patchesRef = useRef([]);
+    const pendingUploadsRef = useRef(new Map());
+    const uploadingFieldsRef = useRef(new Set());
+    const uploadingListenersRef = useRef(new Map());
+    const fieldListeners = useRef(new Map());
+    const errorListeners = useRef(new Set());
+    const metaListeners = useRef(new Set());
+    const systemPathRef = useRef('string' == typeof initialData?.path && initialData.path.length > 0 ? initialData.path : null);
+    const initialSystemPath = useRef(systemPathRef.current);
+    const systemPathListeners = useRef(new Set());
+    const subscribeField = useCallback((name, listener)=>{
+        if (!fieldListeners.current.has(name)) fieldListeners.current.set(name, new Set());
+        fieldListeners.current.get(name)?.add(listener);
+        return ()=>{
+            const listeners = fieldListeners.current.get(name);
+            if (listeners) {
+                listeners.delete(listener);
+                if (0 === listeners.size) fieldListeners.current.delete(name);
+            }
+        };
+    }, []);
+    const subscribeErrors = useCallback((listener)=>{
+        errorListeners.current.add(listener);
+        return ()=>{
+            errorListeners.current.delete(listener);
+        };
+    }, []);
+    const subscribeMeta = useCallback((listener)=>{
+        metaListeners.current.add(listener);
+        return ()=>{
+            metaListeners.current.delete(listener);
+        };
+    }, []);
+    const notifyFieldListeners = useCallback((name, value)=>{
+        const listeners = fieldListeners.current.get(name);
+        if (listeners) listeners.forEach((listener)=>{
+            listener(value);
+        });
+    }, []);
+    const notifyErrorListeners = useCallback(()=>{
+        errorListeners.current.forEach((listener)=>{
+            listener(errorsRef.current);
+        });
+    }, []);
+    const notifyMetaListeners = useCallback(()=>{
+        metaListeners.current.forEach((listener)=>{
+            listener();
+        });
+    }, []);
+    const updateFieldStoreInternal = useCallback((name, value)=>{
+        const newFieldValues = {
+            ...fieldValues.current
+        };
+        external_lodash_es_set(newFieldValues, name, value);
+        fieldValues.current = newFieldValues;
+        dirtyFields.current.add(name);
+        notifyFieldListeners(name, value);
+        notifyMetaListeners();
+    }, [
+        notifyFieldListeners,
+        notifyMetaListeners
+    ]);
+    const setFieldStore = useCallback((name, value)=>{
+        updateFieldStoreInternal(name, value);
+    }, [
+        updateFieldStoreInternal
+    ]);
+    const setFieldValue = useCallback((name, value)=>{
+        updateFieldStoreInternal(name, value);
+        const patch = {
+            kind: 'field.set',
+            path: name,
+            value
+        };
+        const lastPatch = patchesRef.current[patchesRef.current.length - 1];
+        if (lastPatch && 'field.set' === lastPatch.kind && lastPatch.path === name) {
+            const newPatches = [
+                ...patchesRef.current
+            ];
+            newPatches[newPatches.length - 1] = patch;
+            patchesRef.current = newPatches;
+        } else patchesRef.current = [
+            ...patchesRef.current,
+            patch
+        ];
+        if (errorsRef.current.some((error)=>error.field === name)) {
+            errorsRef.current = errorsRef.current.filter((error)=>error.field !== name);
+            notifyErrorListeners();
+        }
+    }, [
+        updateFieldStoreInternal,
+        notifyErrorListeners
+    ]);
+    const getFieldValues = useCallback(()=>fieldValues.current, []);
+    const getPatches = useCallback(()=>patchesRef.current, []);
+    const appendPatch = useCallback((patch)=>{
+        patchesRef.current = [
+            ...patchesRef.current,
+            patch
+        ];
+        dirtyFields.current.add('__patch__');
+        notifyMetaListeners();
+        if ('production' !== process.env.NODE_ENV) console.debug('FormContext.appendPatch', {
+            patch,
+            dirtyCount: dirtyFields.current.size
+        });
+    }, [
+        notifyMetaListeners
+    ]);
+    const getFieldValue = useCallback((name)=>{
+        const dirty = dirtyFields.current.has(name);
+        const currentValue = get(fieldValues.current, name);
+        if (void 0 !== currentValue) return currentValue;
+        if (!dirty) return get(initialValues.current, name);
+    }, []);
+    const hasChanges = useCallback(()=>dirtyFields.current.size > 0, []);
+    const resetHasChanges = useCallback(()=>{
+        dirtyFields.current.clear();
+        patchesRef.current = [];
+        initialSystemPath.current = systemPathRef.current;
+        notifyMetaListeners();
+    }, [
+        notifyMetaListeners
+    ]);
+    const isDirty = useCallback((fieldName)=>dirtyFields.current.has(fieldName), []);
+    const getSystemPath = useCallback(()=>systemPathRef.current, []);
+    const setSystemPath = useCallback((value)=>{
+        systemPathRef.current = value;
+        if (value !== initialSystemPath.current) dirtyFields.current.add('__systemPath__');
+        else dirtyFields.current.delete('__systemPath__');
+        systemPathListeners.current.forEach((listener)=>{
+            listener(value);
+        });
+        notifyMetaListeners();
+    }, [
+        notifyMetaListeners
+    ]);
+    const subscribeSystemPath = useCallback((listener)=>{
+        systemPathListeners.current.add(listener);
+        return ()=>{
+            systemPathListeners.current.delete(listener);
+        };
+    }, []);
+    const addPendingUpload = useCallback((fieldPath, upload)=>{
+        const existing = pendingUploadsRef.current.get(fieldPath);
+        if (existing) URL.revokeObjectURL(existing.previewUrl);
+        pendingUploadsRef.current.set(fieldPath, upload);
+        dirtyFields.current.add(fieldPath);
+        notifyMetaListeners();
+    }, [
+        notifyMetaListeners
+    ]);
+    const removePendingUpload = useCallback((fieldPath)=>{
+        const existing = pendingUploadsRef.current.get(fieldPath);
+        if (existing) {
+            URL.revokeObjectURL(existing.previewUrl);
+            pendingUploadsRef.current.delete(fieldPath);
+            notifyMetaListeners();
+        }
+    }, [
+        notifyMetaListeners
+    ]);
+    const getPendingUploads = useCallback(()=>new Map(pendingUploadsRef.current), []);
+    const hasPendingUploads = useCallback(()=>pendingUploadsRef.current.size > 0, []);
+    const clearPendingUploads = useCallback(()=>{
+        for (const upload of pendingUploadsRef.current.values())URL.revokeObjectURL(upload.previewUrl);
+        pendingUploadsRef.current.clear();
+    }, []);
+    const setFieldUploading = useCallback((fieldPath, uploading)=>{
+        if (uploading) {
+            if (uploadingFieldsRef.current.has(fieldPath)) return;
+            uploadingFieldsRef.current.add(fieldPath);
+        } else {
+            if (!uploadingFieldsRef.current.has(fieldPath)) return;
+            uploadingFieldsRef.current.delete(fieldPath);
+        }
+        uploadingListenersRef.current.get(fieldPath)?.forEach((listener)=>{
+            listener(uploading);
+        });
+    }, []);
+    const getIsFieldUploading = useCallback((fieldPath)=>uploadingFieldsRef.current.has(fieldPath), []);
+    const subscribeFieldUploading = useCallback((fieldPath, listener)=>{
+        let listeners = uploadingListenersRef.current.get(fieldPath);
+        if (!listeners) {
+            listeners = new Set();
+            uploadingListenersRef.current.set(fieldPath, listeners);
+        }
+        listeners.add(listener);
+        return ()=>{
+            const set = uploadingListenersRef.current.get(fieldPath);
+            if (set) {
+                set.delete(listener);
+                if (0 === set.size) uploadingListenersRef.current.delete(fieldPath);
+            }
+        };
+    }, []);
+    useEffect(()=>()=>{
+            for (const upload of pendingUploadsRef.current.values())URL.revokeObjectURL(upload.previewUrl);
+        }, []);
+    const validateForm = useCallback((fields)=>{
+        const formErrors = [];
+        const data = getFieldValues();
+        for (const field of fields){
+            const value = getFieldValue(field.name);
+            if (!field.optional && (null == value || '' === value)) formErrors.push({
+                field: field.name,
+                message: `${field.label} is required`
+            });
+            if (null != value && '' !== value) switch(field.type){
+                case 'text':
+                    if ('string' != typeof value) formErrors.push({
+                        field: field.name,
+                        message: `${field.label} must be text`
+                    });
+                    break;
+                case 'checkbox':
+                    if ('boolean' != typeof value) formErrors.push({
+                        field: field.name,
+                        message: `${field.label} must be true or false`
+                    });
+                    break;
+                case 'select':
+                    if ('options' in field && field.options) {
+                        const validValues = field.options.map((opt)=>opt.value);
+                        if (!validValues.includes(value)) formErrors.push({
+                            field: field.name,
+                            message: `${field.label} must be one of: ${validValues.join(', ')}`
+                        });
+                    }
+                    break;
+                case 'datetime':
+                    if (value instanceof Date === false && 'string' != typeof value) formErrors.push({
+                        field: field.name,
+                        message: `${field.label} must be a valid date`
+                    });
+                    break;
+            }
+            if (field.validate) {
+                const error = field.validate(value, data);
+                if (error) formErrors.push({
+                    field: field.name,
+                    message: error
+                });
+            }
+        }
+        errorsRef.current = formErrors;
+        notifyErrorListeners();
+        return formErrors;
+    }, [
+        getFieldValue,
+        getFieldValues,
+        notifyErrorListeners
+    ]);
+    const clearErrors = useCallback(()=>{
+        errorsRef.current = [];
+        notifyErrorListeners();
+    }, [
+        notifyErrorListeners
+    ]);
+    const setFieldError = useCallback((field, message)=>{
+        const filtered = errorsRef.current.filter((e)=>e.field !== field);
+        filtered.push({
+            field,
+            message
+        });
+        errorsRef.current = filtered;
+        notifyErrorListeners();
+    }, [
+        notifyErrorListeners
+    ]);
+    const clearFieldError = useCallback((field)=>{
+        if (errorsRef.current.some((e)=>e.field === field)) {
+            errorsRef.current = errorsRef.current.filter((e)=>e.field !== field);
+            notifyErrorListeners();
+        }
+    }, [
+        notifyErrorListeners
+    ]);
+    const runFieldHooks = useCallback(async (fields)=>{
+        const hookErrors = [];
+        const data = {
+            ...fieldValues.current
+        };
+        for (const field of fields){
+            const fns = normalizeHooks(field.hooks?.beforeValidate);
+            if (0 === fns.length) continue;
+            const path = field.name;
+            const value = getFieldValue(path);
+            const ctx = {
+                value,
+                previousValue: value,
+                data,
+                path,
+                field,
+                operation: 'submit'
+            };
+            try {
+                for (const fn of fns){
+                    const result = await fn(ctx);
+                    if (result?.error) hookErrors.push({
+                        field: path,
+                        message: result.error
+                    });
+                    if (result?.value !== void 0) {
+                        setFieldValue(path, result.value);
+                        ctx.value = result.value;
+                        data[path] = result.value;
+                    }
+                }
+            } catch (err) {
+                const message = err instanceof Error ? err.message : 'Unexpected hook error';
+                hookErrors.push({
+                    field: path,
+                    message
+                });
+            }
+        }
+        if (hookErrors.length > 0) {
+            errorsRef.current = [
+                ...errorsRef.current,
+                ...hookErrors
+            ];
+            notifyErrorListeners();
+        }
+        return hookErrors;
+    }, [
+        getFieldValue,
+        setFieldValue,
+        notifyErrorListeners
+    ]);
+    return /*#__PURE__*/ jsx(FormContext.Provider, {
+        value: {
+            setFieldValue,
+            setFieldStore,
+            getFieldValue,
+            getFieldValues,
+            getPatches,
+            appendPatch,
+            resetPatches: ()=>{
+                patchesRef.current = [];
+            },
+            hasChanges,
+            resetHasChanges,
+            runFieldHooks,
+            validateForm,
+            errors: errorsRef.current,
+            getErrors: ()=>errorsRef.current,
+            clearErrors,
+            setFieldError,
+            clearFieldError,
+            isDirty,
+            subscribeField,
+            subscribeErrors,
+            subscribeMeta,
+            addPendingUpload,
+            removePendingUpload,
+            getPendingUploads,
+            hasPendingUploads,
+            clearPendingUploads,
+            setFieldUploading,
+            getIsFieldUploading,
+            subscribeFieldUploading,
+            getSystemPath,
+            setSystemPath,
+            subscribeSystemPath
+        },
+        children: children
+    });
+};
+const useSystemPath = ()=>{
+    const { getSystemPath, subscribeSystemPath } = useFormContext();
+    const [value, setValue] = useState(()=>getSystemPath());
+    useEffect(()=>subscribeSystemPath((next)=>setValue(next)), [
+        subscribeSystemPath
+    ]);
+    return value;
+};
+const useFormStore = ()=>useFormContext();
+const useFieldError = (name)=>{
+    const { getErrors, subscribeErrors } = useFormContext();
+    const [error, setError] = useState(()=>getErrors().find((e)=>e.field === name)?.message);
+    useEffect(()=>{
+        const unsubscribe = subscribeErrors((currentErrors)=>{
+            const fieldError = currentErrors.find((e)=>e.field === name);
+            setError(fieldError?.message);
+        });
+        return unsubscribe;
+    }, [
+        subscribeErrors,
+        name
+    ]);
+    return error;
+};
+const useFormMeta = ()=>{
+    const { hasChanges, subscribeMeta } = useFormContext();
+    const [hasChangesValue, setHasChangesValue] = useState(hasChanges());
+    useEffect(()=>{
+        const unsubscribe = subscribeMeta(()=>{
+            setHasChangesValue(hasChanges());
+        });
+        return unsubscribe;
+    }, [
+        subscribeMeta,
+        hasChanges
+    ]);
+    return {
+        hasChanges: hasChangesValue
+    };
+};
+const useIsDirty = (name)=>{
+    const { isDirty, subscribeMeta } = useFormContext();
+    const [dirty, setDirty] = useState(isDirty(name));
+    useEffect(()=>{
+        const unsubscribe = subscribeMeta(()=>{
+            setDirty(isDirty(name));
+        });
+        return unsubscribe;
+    }, [
+        subscribeMeta,
+        isDirty,
+        name
+    ]);
+    return dirty;
+};
+const useFieldValue = (name)=>{
+    const { getFieldValue, subscribeField } = useFormContext();
+    const [value, setValue] = useState(()=>getFieldValue(name));
+    useEffect(()=>{
+        const unsubscribe = subscribeField(name, (nextValue)=>{
+            setValue(nextValue);
+        });
+        return unsubscribe;
+    }, [
+        subscribeField,
+        name
+    ]);
+    return value;
+};
+const useIsFieldUploading = (fieldPath)=>{
+    const { getIsFieldUploading, subscribeFieldUploading } = useFormContext();
+    const [uploading, setUploading] = useState(()=>getIsFieldUploading(fieldPath));
+    useEffect(()=>subscribeFieldUploading(fieldPath, (next)=>{
+            setUploading(next);
+        }), [
+        subscribeFieldUploading,
+        fieldPath
+    ]);
+    return uploading;
+};
+export { FormProvider, useFieldError, useFieldValue, useFormContext, useFormMeta, useFormStore, useIsDirty, useIsFieldUploading, useSystemPath };

package/dist/forms/form-renderer.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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 type { CollectionAdminConfig, Field, WorkflowStatus } from '@byline/core';
+import { type DocumentActionsLocaleOption } from './document-actions';
+import type { UseNavigationGuard } from './navigation-guard';
+/** Metadata about a previously published version that is still live. */
+export interface PublishedVersionInfo {
+    id: string;
+    versionId: string;
+    status: string;
+    createdAt: string | Date;
+    updatedAt: string | Date;
+}
+/** Props shared by both the public FormRenderer and its internal FormContent component. */
+export interface FormRendererProps {
+    mode: 'create' | 'edit';
+    fields: Field[];
+    onSubmit: (data: any) => void;
+    onCancel: () => void;
+    onStatusChange?: (nextStatus: string) => Promise<void>;
+    onUnpublish?: () => Promise<void>;
+    onDelete?: () => Promise<void>;
+    /**
+     * Called when the editor confirms the duplicate modal in
+     * `DocumentActions`. Edit views provide a handler that invokes the
+     * `duplicateCollectionDocument` server fn and navigates to the new doc.
+     * When omitted, the Duplicate menu item is hidden.
+     */
+    onDuplicate?: () => Promise<void>;
+    /**
+     * Called when the editor confirms the Copy-to-Locale modal in
+     * `DocumentActions`. Edit views provide a handler that invokes the
+     * `copyDocumentToLocale` server fn and navigates to the target-locale
+     * view. When omitted (or when fewer than two `contentLocales` are
+     * configured), the Copy-to-Locale menu item is hidden.
+     */
+    onCopyToLocale?: (args: {
+        targetLocale: string;
+        overwrite: boolean;
+    }) => Promise<void>;
+    /**
+     * All configured content locales (code + display label) — required for
+     * the Copy-to-Locale modal's target Select. Threaded as an opaque list
+     * through to `DocumentActions`.
+     */
+    contentLocales?: ReadonlyArray<DocumentActionsLocaleOption>;
+    nextStatus?: WorkflowStatus;
+    workflowStatuses?: WorkflowStatus[];
+    publishedVersion?: PublishedVersionInfo | null;
+    initialData?: Record<string, any>;
+    adminConfig?: CollectionAdminConfig;
+    /**
+     * Name of the schema field to render as the live form heading.
+     * Sourced from `CollectionDefinition.useAsTitle` by the caller.
+     */
+    useAsTitle?: string;
+    /**
+     * Name of the schema field that initialises the system path.
+     * Sourced from `CollectionDefinition.useAsPath` by the caller. When
+     * present the path widget renders in the sidebar.
+     */
+    useAsPath?: string;
+    headingLabel?: string;
+    headerSlot?: ReactNode;
+    /** Collection path forwarded to upload-capable fields (e.g. `'media'`). */
+    collectionPath?: string;
+    /** The active content locale — initialised from the route query string. */
+    initialLocale?: string;
+    /** Called when the user picks a different content locale. */
+    onLocaleChange?: (locale: string) => void;
+    /**
+     * Schema-mismatch warnings produced by a "best-effort" reconstruction
+     * of the document (`findById({ lenient: true })`). When present, the
+     * form renders an inline Alert telling the editor that fields from a
+     * previous schema have been dropped — saving the form will overwrite
+     * them with the new shape.
+     */
+    restoreWarnings?: string[];
+    /**
+     * Default content locale used when no `initialLocale` is supplied and as the
+     * fallback inside `PathWidget`. Hosts typically pass their app-wide
+     * `i18n.content.defaultLocale`. Defaults to `'en'`.
+     */
+    defaultLocale?: string;
+    /**
+     * Framework-specific navigation guard hook.
+     * When provided, this overrides the adapter from `NavigationGuardProvider` context.
+     * If neither is set, a no-op `beforeunload`-only guard is used.
+     */
+    useNavigationGuard?: UseNavigationGuard;
+}
+export declare const FormRenderer: ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale, useNavigationGuard, restoreWarnings, }: FormRendererProps) => import("react").JSX.Element;