@byline/admin 3.12.1 → 3.13.0

package/dist/fields/field-services-types.d.ts

@@ -57,7 +57,57 @@ export interface UploadedFileResult {
     storedFile: StoredFileValue;
 }
 export type UploadFieldFn = (collection: string, formData: FormData, createDocument?: boolean) => Promise<UploadedFileResult>;
+/** One hydrated ancestor in a document's breadcrumb trail (root-first). */
+export interface TreeAncestor {
+    id: string;
+    title: string;
+    path?: string;
+}
+export interface PlaceTreeNodeInput {
+    collection: string;
+    documentId: string;
+    /** The new parent; `null` makes the document a root node. */
+    parentDocumentId: string | null;
+    /** Optional sibling neighbours (left = land after, right = land before). */
+    beforeDocumentId?: string | null;
+    afterDocumentId?: string | null;
+}
+/** Place / move a document within its collection's tree. */
+export type PlaceTreeNodeFn = (input: PlaceTreeNodeInput) => Promise<{
+    orderKey: string;
+}>;
+/** Remove a document from the tree (back to the unplaced state). */
+export type RemoveFromTreeFn = (input: {
+    collection: string;
+    documentId: string;
+}) => Promise<void>;
+/** Resolve a document's ancestor chain, root-first, hydrated with titles. */
+export type GetTreeAncestorsFn = (input: {
+    collection: string;
+    documentId: string;
+}) => Promise<TreeAncestor[]>;
+/**
+ * Resolve a document's placement state — the tri-state (unplaced / root / child)
+ * that `getTreeAncestors` cannot express (it returns `[]` for both root and
+ * unplaced). `placed: false` = unplaced; `placed: true` + null parent = root.
+ */
+export type GetTreeParentFn = (input: {
+    collection: string;
+    documentId: string;
+}) => Promise<{
+    placed: boolean;
+    parentDocumentId: string | null;
+}>;
 export interface BylineFieldServices {
     getCollectionDocuments: GetCollectionDocumentsFn;
     uploadField: UploadFieldFn;
+    /**
+     * Document-tree operations, consumed by the sidebar tree-placement widget.
+     * Optional — only hosts that serve `tree: true` collections need to wire
+     * them; the widget guards on their presence.
+     */
+    placeTreeNode?: PlaceTreeNodeFn;
+    removeFromTree?: RemoveFromTreeFn;
+    getTreeAncestors?: GetTreeAncestorsFn;
+    getTreeParent?: GetTreeParentFn;
 }

package/dist/forms/form-context.js

@@ -3,6 +3,7 @@ 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_nested_path_js_set } from "./nested-path.js";
+import { useTrackedSlot } from "./use-tracked-slot.js";
 const sameLocaleSet = (a, b)=>{
     if (a.length !== b.length) return false;
     const sa = [
@@ -33,16 +34,6 @@ const FormProvider = ({ children, initialData = {} })=>{
     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 systemAvailableLocalesRef = useRef(Array.isArray(initialData?.availableLocales) ? [
-        ...initialData.availableLocales
-    ] : []);
-    const initialSystemAvailableLocales = useRef([
-        ...systemAvailableLocalesRef.current
-    ]);
-    const systemAvailableLocalesListeners = 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);
@@ -82,6 +73,24 @@ const FormProvider = ({ children, initialData = {} })=>{
             listener();
         });
     }, []);
+    const pathSlot = useTrackedSlot({
+        initial: 'string' == typeof initialData?.path && initialData.path.length > 0 ? initialData.path : null,
+        dirtyKey: SYSTEM_PATH_DIRTY_KEY,
+        dirtyFields,
+        notifyMeta: notifyMetaListeners
+    });
+    const availableLocalesSlot = useTrackedSlot({
+        initial: Array.isArray(initialData?.availableLocales) ? [
+            ...initialData.availableLocales
+        ] : [],
+        dirtyKey: SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY,
+        dirtyFields,
+        notifyMeta: notifyMetaListeners,
+        isEqual: sameLocaleSet,
+        clone: (value)=>[
+                ...value
+            ]
+    });
     const updateFieldStoreInternal = useCallback((name, value)=>{
         const newFieldValues = {
             ...fieldValues.current
@@ -152,13 +161,13 @@ const FormProvider = ({ children, initialData = {} })=>{
     const resetHasChanges = useCallback(()=>{
         dirtyFields.current.clear();
         patchesRef.current = [];
-        initialSystemPath.current = systemPathRef.current;
-        initialSystemAvailableLocales.current = [
-            ...systemAvailableLocalesRef.current
-        ];
+        pathSlot.commitInitial();
+        availableLocalesSlot.commitInitial();
         notifyMetaListeners();
     }, [
-        notifyMetaListeners
+        notifyMetaListeners,
+        pathSlot.commitInitial,
+        availableLocalesSlot.commitInitial
     ]);
     const isDirty = useCallback((fieldName)=>dirtyFields.current.has(fieldName), []);
     const getDirtyBreakdown = useCallback(()=>{
@@ -179,45 +188,6 @@ const FormProvider = ({ children, initialData = {} })=>{
             availableLocalesDirty
         };
     }, []);
-    const getSystemPath = useCallback(()=>systemPathRef.current, []);
-    const setSystemPath = useCallback((value)=>{
-        systemPathRef.current = value;
-        if (value !== initialSystemPath.current) dirtyFields.current.add(SYSTEM_PATH_DIRTY_KEY);
-        else dirtyFields.current.delete(SYSTEM_PATH_DIRTY_KEY);
-        systemPathListeners.current.forEach((listener)=>{
-            listener(value);
-        });
-        notifyMetaListeners();
-    }, [
-        notifyMetaListeners
-    ]);
-    const subscribeSystemPath = useCallback((listener)=>{
-        systemPathListeners.current.add(listener);
-        return ()=>{
-            systemPathListeners.current.delete(listener);
-        };
-    }, []);
-    const getSystemAvailableLocales = useCallback(()=>systemAvailableLocalesRef.current, []);
-    const setSystemAvailableLocales = useCallback((value)=>{
-        const next = [
-            ...value
-        ];
-        systemAvailableLocalesRef.current = next;
-        if (sameLocaleSet(next, initialSystemAvailableLocales.current)) dirtyFields.current.delete(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY);
-        else dirtyFields.current.add(SYSTEM_AVAILABLE_LOCALES_DIRTY_KEY);
-        systemAvailableLocalesListeners.current.forEach((listener)=>{
-            listener(next);
-        });
-        notifyMetaListeners();
-    }, [
-        notifyMetaListeners
-    ]);
-    const subscribeSystemAvailableLocales = useCallback((listener)=>{
-        systemAvailableLocalesListeners.current.add(listener);
-        return ()=>{
-            systemAvailableLocalesListeners.current.delete(listener);
-        };
-    }, []);
     const addPendingUpload = useCallback((fieldPath, upload)=>{
         const existing = pendingUploadsRef.current.get(fieldPath);
         if (existing) URL.revokeObjectURL(existing.previewUrl);
@@ -438,12 +408,12 @@ const FormProvider = ({ children, initialData = {} })=>{
             setFieldUploading,
             getIsFieldUploading,
             subscribeFieldUploading,
-            getSystemPath,
-            setSystemPath,
-            subscribeSystemPath,
-            getSystemAvailableLocales,
-            setSystemAvailableLocales,
-            subscribeSystemAvailableLocales
+            getSystemPath: pathSlot.get,
+            setSystemPath: pathSlot.set,
+            subscribeSystemPath: pathSlot.subscribe,
+            getSystemAvailableLocales: availableLocalesSlot.get,
+            setSystemAvailableLocales: availableLocalesSlot.set,
+            subscribeSystemAvailableLocales: availableLocalesSlot.subscribe
         },
         children: children
     });

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

@@ -0,0 +1,30 @@
+/**
+ * Shown when the editor triggers a guarded action (status change, duplicate,
+ * copy-to-locale) while the form is dirty. Those actions operate on the saved
+ * version, so the editor must save first.
+ */
+export declare const UnsavedChangesModal: ({ onClose }: {
+    onClose: () => void;
+}) => import("react").JSX.Element;
+/**
+ * Confirms an immediate, non-versioned write of the document-grain system
+ * fields (path / advertised locales) — which does NOT reset workflow status.
+ * When content is also dirty, the copy reassures that content edits still
+ * follow the normal revision + publish workflow. See docs/I18N.md.
+ */
+export declare const SystemFieldsConfirmModal: ({ contentDirty, pathDirty, availableLocalesDirty, onCancel, onConfirm, }: {
+    contentDirty: boolean;
+    pathDirty: boolean;
+    availableLocalesDirty: boolean;
+    onCancel: () => void;
+    onConfirm: () => void;
+}) => import("react").JSX.Element;
+/**
+ * Blocks router navigation / browser unload while the form is dirty. Driven by
+ * the navigation-guard adapter's `isBlocked` state; `onStay` keeps the editor
+ * on the page, `onProceed` discards and continues.
+ */
+export declare const NavigationGuardModal: ({ onStay, onProceed, }: {
+    onStay: () => void;
+    onProceed: () => void;
+}) => import("react").JSX.Element;

package/dist/forms/form-modals.js

@@ -0,0 +1,189 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useTranslation } from "@byline/i18n/react";
+import { Button, CloseIcon, IconButton, Modal } from "@byline/ui/react";
+import classnames from "classnames";
+import form_renderer_module from "./form-renderer.module.js";
+const UnsavedChangesModal = ({ onClose })=>{
+    const { t } = useTranslation('byline-admin');
+    return /*#__PURE__*/ jsx(Modal, {
+        isOpen: true,
+        closeOnOverlayClick: true,
+        onDismiss: onClose,
+        children: /*#__PURE__*/ jsxs(Modal.Container, {
+            style: {
+                maxWidth: '460px'
+            },
+            children: [
+                /*#__PURE__*/ jsx(Modal.Header, {
+                    className: classnames('byline-form-guard-modal-head', form_renderer_module["guard-modal-head"]),
+                    children: /*#__PURE__*/ jsx("h3", {
+                        className: classnames('byline-form-guard-modal-title', form_renderer_module["guard-modal-title"]),
+                        children: t('forms.unsavedChanges.title')
+                    })
+                }),
+                /*#__PURE__*/ jsx(Modal.Content, {
+                    children: /*#__PURE__*/ jsx("p", {
+                        className: classnames('byline-form-guard-modal-text', form_renderer_module["guard-modal-text"]),
+                        children: t('forms.unsavedChanges.message')
+                    })
+                }),
+                /*#__PURE__*/ jsx(Modal.Actions, {
+                    children: /*#__PURE__*/ jsx(Button, {
+                        size: "sm",
+                        style: {
+                            minWidth: '60px'
+                        },
+                        intent: "primary",
+                        type: "button",
+                        onClick: onClose,
+                        children: t('forms.unsavedChanges.okButton')
+                    })
+                })
+            ]
+        })
+    });
+};
+const SystemFieldsConfirmModal = ({ contentDirty, pathDirty, availableLocalesDirty, onCancel, onConfirm })=>{
+    const { t } = useTranslation('byline-admin');
+    return /*#__PURE__*/ jsx(Modal, {
+        isOpen: true,
+        closeOnOverlayClick: true,
+        onDismiss: onCancel,
+        children: /*#__PURE__*/ jsxs(Modal.Container, {
+            style: {
+                maxWidth: '520px'
+            },
+            children: [
+                /*#__PURE__*/ jsxs(Modal.Header, {
+                    className: classnames('byline-form-guard-modal-head', form_renderer_module["guard-modal-head"]),
+                    children: [
+                        /*#__PURE__*/ jsx("h3", {
+                            className: classnames('byline-form-guard-modal-title', form_renderer_module["guard-modal-title"]),
+                            children: contentDirty ? t('forms.systemFieldsConfirm.bothTitle') : t('forms.systemFieldsConfirm.title')
+                        }),
+                        /*#__PURE__*/ jsx(IconButton, {
+                            "aria-label": t('common.actions.close'),
+                            size: "xs",
+                            onClick: onCancel,
+                            children: /*#__PURE__*/ jsx(CloseIcon, {
+                                width: "16px",
+                                height: "16px",
+                                svgClassName: "white-icon"
+                            })
+                        })
+                    ]
+                }),
+                /*#__PURE__*/ jsxs(Modal.Content, {
+                    className: "prose",
+                    children: [
+                        contentDirty && /*#__PURE__*/ jsx("p", {
+                            className: classnames('byline-form-system-fields-content-note', 'm-0 mt-2'),
+                            children: t('forms.systemFieldsConfirm.contentNote')
+                        }),
+                        /*#__PURE__*/ jsx("p", {
+                            className: "m-0 mt-2",
+                            style: contentDirty ? {
+                                marginTop: 'var(--spacing-8)',
+                                paddingTop: 'var(--spacing-12)',
+                                borderTop: '1px solid var(--border-color)'
+                            } : void 0,
+                            children: t('forms.systemFieldsConfirm.intro')
+                        }),
+                        /*#__PURE__*/ jsxs("ul", {
+                            className: classnames('byline-form-system-fields-list', form_renderer_module["guard-modal-text"], 'm-0'),
+                            children: [
+                                pathDirty && /*#__PURE__*/ jsx("li", {
+                                    children: t('forms.systemFieldsConfirm.bulletPath')
+                                }),
+                                availableLocalesDirty && /*#__PURE__*/ jsx("li", {
+                                    children: t('forms.systemFieldsConfirm.bulletLocales')
+                                })
+                            ]
+                        }),
+                        /*#__PURE__*/ jsx("p", {
+                            className: classnames('byline-form-system-fields-effect', form_renderer_module["guard-modal-text"]),
+                            style: {
+                                marginTop: 'var(--spacing-4)',
+                                marginBottom: 0,
+                                color: 'var(--text-subtle)'
+                            },
+                            children: t('forms.systemFieldsConfirm.effectLine')
+                        })
+                    ]
+                }),
+                /*#__PURE__*/ jsxs(Modal.Actions, {
+                    children: [
+                        /*#__PURE__*/ jsx(Button, {
+                            size: "sm",
+                            style: {
+                                minWidth: '80px'
+                            },
+                            intent: "noeffect",
+                            type: "button",
+                            onClick: onCancel,
+                            children: t('common.actions.cancel')
+                        }),
+                        /*#__PURE__*/ jsx(Button, {
+                            size: "sm",
+                            style: {
+                                minWidth: '80px'
+                            },
+                            intent: "primary",
+                            type: "button",
+                            onClick: onConfirm,
+                            children: t('forms.systemFieldsConfirm.confirmButton')
+                        })
+                    ]
+                })
+            ]
+        })
+    });
+};
+const NavigationGuardModal = ({ onStay, onProceed })=>{
+    const { t } = useTranslation('byline-admin');
+    return /*#__PURE__*/ jsx(Modal, {
+        isOpen: true,
+        closeOnOverlayClick: false,
+        onDismiss: onStay,
+        children: /*#__PURE__*/ jsxs(Modal.Container, {
+            style: {
+                maxWidth: '460px'
+            },
+            children: [
+                /*#__PURE__*/ jsx(Modal.Header, {
+                    className: classnames('byline-form-guard-modal-head', form_renderer_module["guard-modal-head"]),
+                    children: /*#__PURE__*/ jsx("h3", {
+                        className: classnames('byline-form-guard-modal-title', form_renderer_module["guard-modal-title"]),
+                        children: t('forms.navigationGuard.title')
+                    })
+                }),
+                /*#__PURE__*/ jsx(Modal.Content, {
+                    children: /*#__PURE__*/ jsx("p", {
+                        className: classnames('byline-form-guard-modal-text', form_renderer_module["guard-modal-text"]),
+                        children: t('forms.navigationGuard.message')
+                    })
+                }),
+                /*#__PURE__*/ jsxs(Modal.Actions, {
+                    children: [
+                        /*#__PURE__*/ jsx(Button, {
+                            size: "sm",
+                            intent: "noeffect",
+                            type: "button",
+                            onClick: onStay,
+                            children: t('forms.navigationGuard.stayButton')
+                        }),
+                        /*#__PURE__*/ jsx(Button, {
+                            size: "sm",
+                            intent: "danger",
+                            type: "button",
+                            onClick: onProceed,
+                            children: t('forms.navigationGuard.leaveButton')
+                        })
+                    ]
+                })
+            ]
+        })
+    });
+};
+export { NavigationGuardModal, SystemFieldsConfirmModal, UnsavedChangesModal };

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

@@ -100,6 +100,13 @@ export interface FormRendererProps {
      * against the document's `_availableVersionLocales` ledger fact.
      */
     advertiseLocales?: boolean;
+    /**
+     * Opts the document-tree placement widget into the sidebar (above the
+     * available-locales widget). Sourced from `CollectionDefinition.tree` by the
+     * caller. Renders only in edit mode (placement needs a persisted document)
+     * and only when the host wires the tree services. See docs/DOCUMENT-TREE.md.
+     */
+    tree?: boolean;
     headingLabel?: string;
     headerSlot?: ReactNode;
     /** Collection path forwarded to upload-capable fields (e.g. `'media'`). */
@@ -129,4 +136,4 @@ export interface FormRendererProps {
      */
     useNavigationGuard?: UseNavigationGuard;
 }
-export declare const FormRenderer: ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, onDeleteLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, advertiseLocales, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale, useNavigationGuard, restoreWarnings, }: FormRendererProps) => import("react").JSX.Element;
+export declare const FormRenderer: ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpublish, onDelete, onDuplicate, onCopyToLocale, onDeleteLocale, contentLocales, nextStatus, workflowStatuses, publishedVersion, initialData, adminConfig, useAsTitle, useAsPath, advertiseLocales, tree, headingLabel, headerSlot, collectionPath, initialLocale, onLocaleChange, defaultLocale, useNavigationGuard, restoreWarnings, }: FormRendererProps) => import("react").JSX.Element;