@byline/admin 3.12.2 → 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-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;

package/dist/forms/form-renderer.js

@@ -18,9 +18,10 @@ import { FormStatusDisplay } from "./form-status-display.js";
 import { useNavigationGuardAdapter } from "./navigation-guard.js";
 import { PathWidget } from "./path-widget.js";
 import { computeStatusTransitions } from "./status-transitions.js";
+import { TreePlacementWidget } from "./tree-placement-widget.js";
 import { executeUploadsWithProgress } from "./upload-executor.js";
 import { useFormLayout } from "./use-form-layout.js";
-const FormContent = ({ 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 = 'en', useNavigationGuard: useNavigationGuardProp, restoreWarnings, _activeTabBySet, _onTabChange })=>{
+const FormContent = ({ 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 = 'en', useNavigationGuard: useNavigationGuardProp, restoreWarnings, _activeTabBySet, _onTabChange })=>{
     const { getFieldValues, runFieldHooks, validateForm, errors: initialErrors, hasChanges: hasChangesFn, resetHasChanges, getPatches, getDirtyBreakdown, getSystemPath, getSystemAvailableLocales, subscribeErrors, subscribeMeta, setFieldValue, setFieldError, getPendingUploads, clearPendingUploads, setFieldUploading } = useFormContext();
     const { t } = useTranslation('byline-admin');
     const [errors, setErrors] = useState(initialErrors);
@@ -346,6 +347,11 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
                                 activeLocale: contentLocale,
                                 mode: mode
                             }),
+                            tree && 'edit' === mode && 'string' == typeof initialData?.id && /*#__PURE__*/ jsx(TreePlacementWidget, {
+                                collectionPath: collectionPath ?? '',
+                                documentId: initialData.id,
+                                useAsTitle: useAsTitle
+                            }),
                             advertiseLocales && /*#__PURE__*/ jsx(AvailableLocalesWidget, {
                                 contentLocales: contentLocales ?? [],
                                 availableVersionLocales: initialData?._availableVersionLocales ?? []
@@ -376,7 +382,7 @@ const FormContent = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpub
         ]
     });
 };
-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 })=>{
+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 })=>{
     const savedTabsRef = useRef({});
     return /*#__PURE__*/ jsx(FormProvider, {
         initialData: initialData,
@@ -400,6 +406,7 @@ const FormRenderer = ({ mode, fields, onSubmit, onCancel, onStatusChange, onUnpu
             useAsTitle: useAsTitle,
             useAsPath: useAsPath,
             advertiseLocales: advertiseLocales,
+            tree: tree,
             headingLabel: headingLabel,
             headerSlot: headerSlot,
             collectionPath: collectionPath,

package/dist/forms/tree-placement-widget.d.ts

@@ -0,0 +1,23 @@
+export interface TreePlacementWidgetProps {
+    /** The collection path (`tree: true`). */
+    collectionPath: string;
+    /** The logical id of the document being edited. */
+    documentId: string;
+    /** The collection's `useAsTitle` field, used to label the chosen parent. */
+    useAsTitle?: string;
+}
+/**
+ * Sidebar widget for placing the current document within its collection's
+ * single-parent document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md).
+ *
+ * The tree is document-grain and **unversioned**, so changes here write
+ * immediately (independent of the form's content save). The editor picks a
+ * parent through the collection's own relation picker — same search / columns
+ * UX as a relation field — or moves the document to the top level; the server
+ * enforces the cycle / same-collection invariants and fires the
+ * structural-change invalidation event.
+ *
+ * Renders only in edit mode (placement needs a persisted document) and only when
+ * the host wires the tree services. Stable override handle: `.byline-form-tree`.
+ */
+export declare const TreePlacementWidget: ({ collectionPath, documentId, useAsTitle, }: TreePlacementWidgetProps) => import("react").JSX.Element | null;

package/dist/forms/tree-placement-widget.js

@@ -0,0 +1,176 @@
+"use client";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from "react";
+import { getCollectionDefinition } from "@byline/core";
+import { useTranslation } from "@byline/i18n/react";
+import { Button } from "@byline/ui/react";
+import classnames from "classnames";
+import { useBylineFieldServices } from "../fields/field-services-context.js";
+import { RelationPicker } from "../fields/relation/relation-picker.js";
+import tree_placement_widget_module from "./tree-placement-widget.module.js";
+const TreePlacementWidget = ({ collectionPath, documentId, useAsTitle })=>{
+    const { t } = useTranslation('byline-admin');
+    const { getTreeAncestors, getTreeParent, placeTreeNode } = useBylineFieldServices();
+    const targetDefinition = getCollectionDefinition(collectionPath);
+    const [parent, setParent] = useState(null);
+    const [placed, setPlaced] = useState(true);
+    const [loading, setLoading] = useState(true);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const [pickerOpen, setPickerOpen] = useState(false);
+    const treeServicesReady = null != getTreeAncestors && null != placeTreeNode;
+    useEffect(()=>{
+        if (null == getTreeAncestors) return;
+        let cancelled = false;
+        setLoading(true);
+        Promise.all([
+            getTreeAncestors({
+                collection: collectionPath,
+                documentId
+            }),
+            getTreeParent?.({
+                collection: collectionPath,
+                documentId
+            }) ?? Promise.resolve({
+                placed: true,
+                parentDocumentId: null
+            })
+        ]).then(([ancestors, placement])=>{
+            if (cancelled) return;
+            const immediate = ancestors.at(-1);
+            setParent(immediate ? {
+                id: immediate.id,
+                title: immediate.title
+            } : null);
+            setPlaced(placement.placed);
+        }).catch(()=>{
+            if (!cancelled) setError(t('treeWidget.error'));
+        }).finally(()=>{
+            if (!cancelled) setLoading(false);
+        });
+        return ()=>{
+            cancelled = true;
+        };
+    }, [
+        getTreeAncestors,
+        getTreeParent,
+        collectionPath,
+        documentId,
+        t
+    ]);
+    const place = useCallback(async (parentDocumentId, optimistic)=>{
+        if (null == placeTreeNode || busy) return;
+        const previousParent = parent;
+        const previousPlaced = placed;
+        setError(null);
+        setBusy(true);
+        setParent(optimistic);
+        setPlaced(true);
+        try {
+            await placeTreeNode({
+                collection: collectionPath,
+                documentId,
+                parentDocumentId
+            });
+        } catch  {
+            setParent(previousParent);
+            setPlaced(previousPlaced);
+            setError(t('treeWidget.error'));
+        } finally{
+            setBusy(false);
+        }
+    }, [
+        placeTreeNode,
+        busy,
+        parent,
+        placed,
+        collectionPath,
+        documentId,
+        t
+    ]);
+    const handlePick = useCallback((selection)=>{
+        setPickerOpen(false);
+        const title = useAsTitle ? selection.record?.[useAsTitle] : void 0;
+        place(selection.targetDocumentId, {
+            id: selection.targetDocumentId,
+            title: 'string' == typeof title && title.length > 0 ? title : selection.targetDocumentId
+        });
+    }, [
+        place,
+        useAsTitle
+    ]);
+    if (!treeServicesReady) return null;
+    return /*#__PURE__*/ jsxs("div", {
+        className: classnames('byline-form-tree', tree_placement_widget_module.tree),
+        children: [
+            /*#__PURE__*/ jsx("span", {
+                className: classnames('byline-form-tree-heading', tree_placement_widget_module.heading),
+                children: t('treeWidget.label')
+            }),
+            /*#__PURE__*/ jsxs("div", {
+                className: classnames('byline-form-tree-current', tree_placement_widget_module.current),
+                children: [
+                    /*#__PURE__*/ jsx("span", {
+                        className: tree_placement_widget_module.parentLabel,
+                        children: t('treeWidget.parentPrefix')
+                    }),
+                    ' ',
+                    placed ? parent ? /*#__PURE__*/ jsx("span", {
+                        className: tree_placement_widget_module.parentValue,
+                        children: parent.title
+                    }) : /*#__PURE__*/ jsx("span", {
+                        className: classnames(tree_placement_widget_module.parentValue, tree_placement_widget_module.root),
+                        children: t('treeWidget.rootOption')
+                    }) : /*#__PURE__*/ jsx("span", {
+                        className: classnames(tree_placement_widget_module.parentValue, tree_placement_widget_module.root),
+                        children: t('treeWidget.notInTree')
+                    })
+                ]
+            }),
+            /*#__PURE__*/ jsxs("div", {
+                className: classnames('byline-form-tree-actions', tree_placement_widget_module.actions),
+                children: [
+                    /*#__PURE__*/ jsx(Button, {
+                        type: "button",
+                        size: "xs",
+                        variant: "outlined",
+                        intent: "noeffect",
+                        disabled: loading || busy,
+                        onClick: ()=>setPickerOpen(true),
+                        children: t('treeWidget.choose')
+                    }),
+                    placed ? null != parent && /*#__PURE__*/ jsx("button", {
+                        type: "button",
+                        className: classnames('byline-form-tree-link', tree_placement_widget_module.link),
+                        disabled: busy,
+                        onClick: ()=>place(null, null),
+                        children: t('treeWidget.makeRoot')
+                    }) : /*#__PURE__*/ jsx("button", {
+                        type: "button",
+                        className: classnames('byline-form-tree-link', tree_placement_widget_module.link),
+                        disabled: loading || busy,
+                        onClick: ()=>place(null, null),
+                        children: t('treeWidget.addToTree')
+                    })
+                ]
+            }),
+            null != error && /*#__PURE__*/ jsx("p", {
+                className: classnames('byline-form-tree-error', tree_placement_widget_module.error),
+                children: error
+            }),
+            null != targetDefinition && /*#__PURE__*/ jsx(RelationPicker, {
+                targetCollectionPath: collectionPath,
+                targetDefinition: targetDefinition,
+                displayField: useAsTitle,
+                isOpen: pickerOpen,
+                onSelect: handlePick,
+                onDismiss: ()=>setPickerOpen(false)
+            }),
+            /*#__PURE__*/ jsx("span", {
+                className: tree_placement_widget_module["sr-only"],
+                children: t("treeWidget.srDescription")
+            })
+        ]
+    });
+};
+export { TreePlacementWidget };

package/dist/forms/tree-placement-widget.module.js

@@ -0,0 +1,15 @@
+import "./tree-placement-widget_module.css";
+const tree_placement_widget_module = {
+    tree: "tree-QTfVWc",
+    heading: "heading-kMlzJM",
+    current: "current-V4s8B9",
+    parentLabel: "parentLabel-AOKJXk",
+    parentValue: "parentValue-EzOVWx",
+    root: "root-mvHqUc",
+    actions: "actions-e3yRzc",
+    link: "link-hHX4SE",
+    error: "error-SXo8E4",
+    "sr-only": "sr-only-iZPr5G",
+    srOnly: "sr-only-iZPr5G"
+};
+export default tree_placement_widget_module;

package/dist/forms/tree-placement-widget_module.css

@@ -0,0 +1,69 @@
+:is(.tree-QTfVWc, .byline-form-tree) {
+  gap: var(--spacing-8);
+  flex-direction: column;
+  display: flex;
+}
+
+:is(.heading-kMlzJM, .byline-form-tree-heading) {
+  font-size: .875rem;
+  font-weight: 600;
+}
+
+:is(.current-V4s8B9, .byline-form-tree-current) {
+  font-size: .875rem;
+}
+
+.parentLabel-AOKJXk {
+  color: var(--gray-500);
+}
+
+.parentValue-EzOVWx {
+  font-weight: 500;
+}
+
+.root-mvHqUc {
+  color: var(--gray-500);
+  font-style: italic;
+  font-weight: 400;
+}
+
+:is(.actions-e3yRzc, .byline-form-tree-actions) {
+  flex-wrap: wrap;
+  align-items: center;
+  gap: .75rem;
+  display: flex;
+}
+
+:is(.link-hHX4SE, .byline-form-tree-link) {
+  color: inherit;
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: 0;
+  font-size: .8rem;
+  text-decoration: underline;
+}
+
+:is(.link-hHX4SE:disabled, .byline-form-tree-link:disabled) {
+  opacity: .5;
+  cursor: default;
+}
+
+:is(.error-SXo8E4, .byline-form-tree-error) {
+  color: var(--danger-600, #c0392b);
+  margin: 0;
+  font-size: .8rem;
+}
+
+.sr-only-iZPr5G {
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  position: absolute;
+  overflow: hidden;
+}
+

package/dist/react.d.ts

@@ -64,4 +64,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, UploadedFileResult, UploadFieldFn, } from './fields/field-services-types.js';
+export type { BylineFieldServices, CollectionListDoc, CollectionListParams, CollectionListResponse, GetCollectionDocumentsFn, 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": "3.12.2",
+  "version": "3.13.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -151,10 +151,10 @@
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
     "zod-form-data": "^3.0.1",
-    "@byline/auth": "3.12.2",
-    "@byline/ui": "3.12.2",
-    "@byline/core": "3.12.2",
-    "@byline/i18n": "3.12.2"
+    "@byline/auth": "3.13.0",
+    "@byline/ui": "3.13.0",
+    "@byline/i18n": "3.13.0",
+    "@byline/core": "3.13.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/fields/field-services-types.ts

@@ -62,7 +62,57 @@ export type UploadFieldFn = (
   createDocument?: boolean
 ) => Promise<UploadedFileResult>
 
+// --- Document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md) -----
+
+/** 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/src/forms/form-renderer.tsx

@@ -37,6 +37,7 @@ import { FormStatusDisplay } from './form-status-display'
 import { useNavigationGuardAdapter } from './navigation-guard'
 import { PathWidget } from './path-widget'
 import { computeStatusTransitions } from './status-transitions'
+import { TreePlacementWidget } from './tree-placement-widget'
 import { executeUploadsWithProgress } from './upload-executor'
 import { useFormLayout } from './use-form-layout'
 import type { UseNavigationGuard } from './navigation-guard'
@@ -129,6 +130,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'`). */
@@ -179,6 +187,7 @@ const FormContent = ({
   useAsTitle,
   useAsPath,
   advertiseLocales,
+  tree,
   headingLabel,
   headerSlot,
   collectionPath,
@@ -665,6 +674,13 @@ const FormContent = ({
               mode={mode}
             />
           )}
+          {tree && mode === 'edit' && typeof initialData?.id === 'string' && (
+            <TreePlacementWidget
+              collectionPath={collectionPath ?? ''}
+              documentId={initialData.id as string}
+              useAsTitle={useAsTitle}
+            />
+          )}
           {advertiseLocales && (
             <AvailableLocalesWidget
               contentLocales={contentLocales ?? []}
@@ -715,6 +731,7 @@ export const FormRenderer = ({
   useAsTitle,
   useAsPath,
   advertiseLocales,
+  tree,
   headingLabel,
   headerSlot,
   collectionPath,
@@ -753,6 +770,7 @@ export const FormRenderer = ({
         useAsTitle={useAsTitle}
         useAsPath={useAsPath}
         advertiseLocales={advertiseLocales}
+        tree={tree}
         headingLabel={headingLabel}
         headerSlot={headerSlot}
         collectionPath={collectionPath}

package/src/forms/tree-placement-widget.module.css

@@ -0,0 +1,87 @@
+/**
+ * TreePlacementWidget — sidebar widget for placing a document within its
+ * collection's single-parent tree (the `tree: true` primitive).
+ *
+ * Override handles:
+ *   .byline-form-tree           — wrapper div
+ *   .byline-form-tree-current   — current-parent line
+ *   .byline-form-tree-actions   — actions row
+ *   .byline-form-tree-link      — text-button actions (move to top level / remove)
+ *   .byline-form-tree-error     — inline error
+ */
+
+.tree,
+:global(.byline-form-tree) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-8);
+}
+
+.heading,
+:global(.byline-form-tree-heading) {
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+.current,
+:global(.byline-form-tree-current) {
+  font-size: 0.875rem;
+}
+
+.parentLabel {
+  color: var(--gray-500);
+}
+
+.parentValue {
+  font-weight: 500;
+}
+
+.root {
+  font-style: italic;
+  font-weight: 400;
+  color: var(--gray-500);
+}
+
+.actions,
+:global(.byline-form-tree-actions) {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 0.75rem;
+}
+
+.link,
+:global(.byline-form-tree-link) {
+  background: none;
+  border: none;
+  padding: 0;
+  color: inherit;
+  font-size: 0.8rem;
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.link:disabled,
+:global(.byline-form-tree-link):disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+.error,
+:global(.byline-form-tree-error) {
+  margin: 0;
+  font-size: 0.8rem;
+  color: var(--danger-600, #c0392b);
+}
+
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}

package/src/forms/tree-placement-widget.tsx

@@ -0,0 +1,202 @@
+'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 { useCallback, useEffect, useState } from 'react'
+
+import { getCollectionDefinition } from '@byline/core'
+import { useTranslation } from '@byline/i18n/react'
+import { Button } from '@byline/ui/react'
+import cx from 'classnames'
+
+import { useBylineFieldServices } from '../fields/field-services-context.js'
+import { RelationPicker } from '../fields/relation/relation-picker.js'
+import styles from './tree-placement-widget.module.css'
+
+export interface TreePlacementWidgetProps {
+  /** The collection path (`tree: true`). */
+  collectionPath: string
+  /** The logical id of the document being edited. */
+  documentId: string
+  /** The collection's `useAsTitle` field, used to label the chosen parent. */
+  useAsTitle?: string
+}
+
+/**
+ * Sidebar widget for placing the current document within its collection's
+ * single-parent document tree (the `tree: true` primitive — docs/DOCUMENT-TREE.md).
+ *
+ * The tree is document-grain and **unversioned**, so changes here write
+ * immediately (independent of the form's content save). The editor picks a
+ * parent through the collection's own relation picker — same search / columns
+ * UX as a relation field — or moves the document to the top level; the server
+ * enforces the cycle / same-collection invariants and fires the
+ * structural-change invalidation event.
+ *
+ * Renders only in edit mode (placement needs a persisted document) and only when
+ * the host wires the tree services. Stable override handle: `.byline-form-tree`.
+ */
+export const TreePlacementWidget = ({
+  collectionPath,
+  documentId,
+  useAsTitle,
+}: TreePlacementWidgetProps) => {
+  const { t } = useTranslation('byline-admin')
+  const { getTreeAncestors, getTreeParent, placeTreeNode } = useBylineFieldServices()
+  const targetDefinition = getCollectionDefinition(collectionPath)
+
+  const [parent, setParent] = useState<{ id: string; title: string } | null>(null)
+  // Whether the document has an edge row at all. `false` = *unplaced* (no row);
+  // `true` with a null `parent` = a *root*. Distinguishing the two drives the
+  // "Add to tree" (unplaced) vs "Top level" (root) display. Hosts that don't
+  // wire `getTreeParent` fall back to `true` — the pre-tri-state behaviour.
+  const [placed, setPlaced] = useState(true)
+  const [loading, setLoading] = useState(true)
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [pickerOpen, setPickerOpen] = useState(false)
+
+  const treeServicesReady = getTreeAncestors != null && placeTreeNode != null
+
+  // Load the document's placement state and current parent on mount. The parent
+  // title comes from the (hydrated) ancestor chain; `getTreeParent` (when wired)
+  // tells unplaced from root, which the ancestor chain alone cannot.
+  useEffect(() => {
+    if (getTreeAncestors == null) return
+    let cancelled = false
+    setLoading(true)
+    Promise.all([
+      getTreeAncestors({ collection: collectionPath, documentId }),
+      getTreeParent?.({ collection: collectionPath, documentId }) ??
+        Promise.resolve({ placed: true, parentDocumentId: null }),
+    ])
+      .then(([ancestors, placement]) => {
+        if (cancelled) return
+        const immediate = ancestors.at(-1)
+        setParent(immediate ? { id: immediate.id, title: immediate.title } : null)
+        setPlaced(placement.placed)
+      })
+      .catch(() => {
+        if (!cancelled) setError(t('treeWidget.error'))
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [getTreeAncestors, getTreeParent, collectionPath, documentId, t])
+
+  // Place (or re-parent) the node, optimistically updating the current-parent
+  // display and reverting on a server rejection (e.g. a cycle). Any successful
+  // placement (including making the node a root) leaves it placed.
+  const place = useCallback(
+    async (parentDocumentId: string | null, optimistic: { id: string; title: string } | null) => {
+      if (placeTreeNode == null || busy) return
+      const previousParent = parent
+      const previousPlaced = placed
+      setError(null)
+      setBusy(true)
+      setParent(optimistic)
+      setPlaced(true)
+      try {
+        await placeTreeNode({ collection: collectionPath, documentId, parentDocumentId })
+      } catch {
+        setParent(previousParent)
+        setPlaced(previousPlaced)
+        setError(t('treeWidget.error'))
+      } finally {
+        setBusy(false)
+      }
+    },
+    [placeTreeNode, busy, parent, placed, collectionPath, documentId, t]
+  )
+
+  const handlePick = useCallback(
+    (selection: { targetDocumentId: string; record?: Record<string, any> }) => {
+      setPickerOpen(false)
+      const title = useAsTitle ? selection.record?.[useAsTitle] : undefined
+      place(selection.targetDocumentId, {
+        id: selection.targetDocumentId,
+        title: typeof title === 'string' && title.length > 0 ? title : selection.targetDocumentId,
+      })
+    },
+    [place, useAsTitle]
+  )
+
+  if (!treeServicesReady) return null
+
+  return (
+    <div className={cx('byline-form-tree', styles.tree)}>
+      <span className={cx('byline-form-tree-heading', styles.heading)}>
+        {t('treeWidget.label')}
+      </span>
+
+      <div className={cx('byline-form-tree-current', styles.current)}>
+        <span className={styles.parentLabel}>{t('treeWidget.parentPrefix')}</span>{' '}
+        {!placed ? (
+          <span className={cx(styles.parentValue, styles.root)}>{t('treeWidget.notInTree')}</span>
+        ) : parent ? (
+          <span className={styles.parentValue}>{parent.title}</span>
+        ) : (
+          <span className={cx(styles.parentValue, styles.root)}>{t('treeWidget.rootOption')}</span>
+        )}
+      </div>
+
+      <div className={cx('byline-form-tree-actions', styles.actions)}>
+        <Button
+          type="button"
+          size="xs"
+          variant="outlined"
+          intent="noeffect"
+          disabled={loading || busy}
+          onClick={() => setPickerOpen(true)}
+        >
+          {t('treeWidget.choose')}
+        </Button>
+        {!placed ? (
+          <button
+            type="button"
+            className={cx('byline-form-tree-link', styles.link)}
+            disabled={loading || busy}
+            onClick={() => place(null, null)}
+          >
+            {t('treeWidget.addToTree')}
+          </button>
+        ) : (
+          parent != null && (
+            <button
+              type="button"
+              className={cx('byline-form-tree-link', styles.link)}
+              disabled={busy}
+              onClick={() => place(null, null)}
+            >
+              {t('treeWidget.makeRoot')}
+            </button>
+          )
+        )}
+      </div>
+
+      {error != null && <p className={cx('byline-form-tree-error', styles.error)}>{error}</p>}
+
+      {targetDefinition != null && (
+        <RelationPicker
+          targetCollectionPath={collectionPath}
+          targetDefinition={targetDefinition}
+          displayField={useAsTitle}
+          isOpen={pickerOpen}
+          onSelect={handlePick}
+          onDismiss={() => setPickerOpen(false)}
+        />
+      )}
+
+      <span className={styles['sr-only']}>{t('treeWidget.srDescription')}</span>
+    </div>
+  )
+}

package/src/react.ts

@@ -80,6 +80,12 @@ export type {
   CollectionListParams,
   CollectionListResponse,
   GetCollectionDocumentsFn,
+  GetTreeAncestorsFn,
+  GetTreeParentFn,
+  PlaceTreeNodeFn,
+  PlaceTreeNodeInput,
+  RemoveFromTreeFn,
+  TreeAncestor,
   UploadedFileResult,
   UploadFieldFn,
 } from './fields/field-services-types.js'