@byline/admin 3.12.1 → 3.13.0

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/forms/use-form-layout.d.ts

@@ -0,0 +1,35 @@
+import type { CollectionAdminConfig, Field, GroupDefinition, LayoutDefinition, RowDefinition, TabSetDefinition } from '@byline/core';
+/** Which tab set + tab a schema field is placed under. */
+export interface TabPath {
+    tabSetName: string;
+    tabName: string;
+}
+/**
+ * Derived lookup tables that drive the form's layout walk and per-tab error
+ * badges. All are pure derivations of `adminConfig` + `fields`; the startup
+ * validator guarantees every reachable name resolves and every schema field is
+ * placed at most once, so the consuming render-time lookups stay unguarded.
+ */
+export interface FormLayout {
+    /** Schema field name → field definition. */
+    fieldByName: Map<string, Field>;
+    tabSetByName: Map<string, TabSetDefinition>;
+    rowByName: Map<string, RowDefinition>;
+    groupByName: Map<string, GroupDefinition>;
+    /** Region placement; synthesised to `{ main: <all fields> }` when omitted. */
+    layout: LayoutDefinition;
+    /** Reverse index: schema field name → which tab set + tab it lives in. */
+    fieldToTabPath: Map<string, TabPath>;
+}
+/**
+ * Build the reverse index from schema field name to its enclosing tab set +
+ * tab. Fields not under any tab set (e.g. raw-field placement directly in
+ * `layout.main`) are absent from the map. Rows and groups are recursed into;
+ * the `seen` set guards against a config that references a row/group cycle.
+ */
+export declare function buildFieldToTabPath(adminConfig: CollectionAdminConfig | undefined, fieldByName: Map<string, Field>, rowByName: Map<string, RowDefinition>, groupByName: Map<string, GroupDefinition>): Map<string, TabPath>;
+/**
+ * Memoise the layout primitives + lookup tables the form renderer walks.
+ * Rebuilt only when `adminConfig` / `fields` change.
+ */
+export declare function useFormLayout(adminConfig: CollectionAdminConfig | undefined, fields: Field[]): FormLayout;

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

@@ -0,0 +1,77 @@
+"use client";
+import { useMemo } from "react";
+function buildFieldToTabPath(adminConfig, fieldByName, rowByName, groupByName) {
+    const map = new Map();
+    const visit = (names, tabSetName, tabName, seen)=>{
+        for (const name of names)if (fieldByName.has(name)) map.set(name, {
+            tabSetName,
+            tabName
+        });
+        else if (seen.has(name)) ;
+        else if (rowByName.has(name)) {
+            const row = rowByName.get(name);
+            const next = new Set(seen).add(name);
+            visit(row.fields, tabSetName, tabName, next);
+        } else if (groupByName.has(name)) {
+            const group = groupByName.get(name);
+            const next = new Set(seen).add(name);
+            visit(group.fields, tabSetName, tabName, next);
+        }
+    };
+    for (const set of adminConfig?.tabSets ?? [])for (const tab of set.tabs)visit(tab.fields, set.name, tab.name, new Set());
+    return map;
+}
+function useFormLayout(adminConfig, fields) {
+    const fieldByName = useMemo(()=>{
+        const map = new Map();
+        for (const field of fields)if ('name' in field) map.set(field.name, field);
+        return map;
+    }, [
+        fields
+    ]);
+    const tabSetByName = useMemo(()=>{
+        const map = new Map();
+        for (const set of adminConfig?.tabSets ?? [])map.set(set.name, set);
+        return map;
+    }, [
+        adminConfig
+    ]);
+    const rowByName = useMemo(()=>{
+        const map = new Map();
+        for (const row of adminConfig?.rows ?? [])map.set(row.name, row);
+        return map;
+    }, [
+        adminConfig
+    ]);
+    const groupByName = useMemo(()=>{
+        const map = new Map();
+        for (const group of adminConfig?.groups ?? [])map.set(group.name, group);
+        return map;
+    }, [
+        adminConfig
+    ]);
+    const layout = useMemo(()=>{
+        if (adminConfig?.layout) return adminConfig.layout;
+        return {
+            main: fields.filter((f)=>'name' in f).map((f)=>f.name)
+        };
+    }, [
+        adminConfig,
+        fields
+    ]);
+    const fieldToTabPath = useMemo(()=>buildFieldToTabPath(adminConfig, fieldByName, rowByName, groupByName), [
+        adminConfig,
+        fieldByName,
+        rowByName,
+        groupByName
+    ]);
+    return {
+        fieldByName,
+        tabSetByName,
+        rowByName,
+        groupByName,
+        layout,
+        fieldToTabPath
+    };
+}
+export { buildFieldToTabPath, useFormLayout };

package/dist/forms/use-form-layout.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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
+ */
+export {};

package/dist/forms/use-tracked-slot.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 RefObject } from 'react';
+/**
+ * A dirty-tracked, ref-backed form slot with its own listener set — the shared
+ * machinery behind the document-grain system fields (`path`, advertised
+ * `availableLocales`, …). Each slot holds the current value, the value it was
+ * loaded with, and a set of subscribers; a `set` that moves the value away from
+ * its loaded baseline registers the slot's `dirtyKey` in the form's shared
+ * dirty set (and clears it again when the value returns to baseline), so the
+ * single Save button can branch on which buckets changed.
+ *
+ * Adding a new system slot is then a one-liner at the call site rather than a
+ * copy of ref + initial-ref + listener-set + get/set/subscribe.
+ */
+export interface TrackedSlot<T> {
+    /** Current value (live ref read — not React state). */
+    get: () => T;
+    /** Write a value; toggles `dirtyKey` against the loaded baseline. */
+    set: (value: T) => void;
+    /** Subscribe to value changes; returns an unsubscribe fn. */
+    subscribe: (listener: (value: T) => void) => () => void;
+    /** Re-baseline: adopt the current value as the new "clean" baseline (called on save). */
+    commitInitial: () => void;
+}
+export interface UseTrackedSlotConfig<T> {
+    /** Initial / loaded value. */
+    initial: T;
+    /** Key registered in the shared dirty set while this slot diverges from baseline. */
+    dirtyKey: string;
+    /** The form's shared dirty-key set. */
+    dirtyFields: RefObject<Set<string>>;
+    /** Notify the form's meta listeners (drives hasChanges → Save button). */
+    notifyMeta: () => void;
+    /** Equality against the baseline. Defaults to `===` (identity). */
+    isEqual?: (a: T, b: T) => boolean;
+    /** Defensive copy on read-in / write. Defaults to identity (fine for immutables). */
+    clone?: (value: T) => T;
+}
+export declare function useTrackedSlot<T>(config: UseTrackedSlotConfig<T>): TrackedSlot<T>;

package/dist/forms/use-tracked-slot.js

@@ -0,0 +1,46 @@
+"use client";
+import { useCallback, useRef } from "react";
+function useTrackedSlot(config) {
+    const cfgRef = useRef(config);
+    cfgRef.current = config;
+    const clone = useCallback((value)=>{
+        const fn = cfgRef.current.clone;
+        return fn ? fn(value) : value;
+    }, []);
+    const valueRef = useRef(clone(config.initial));
+    const initialRef = useRef(clone(config.initial));
+    const listeners = useRef(new Set());
+    const get = useCallback(()=>valueRef.current, []);
+    const set = useCallback((value)=>{
+        const { dirtyKey, dirtyFields, notifyMeta, isEqual } = cfgRef.current;
+        const next = clone(value);
+        valueRef.current = next;
+        const equal = isEqual ? isEqual(next, initialRef.current) : next === initialRef.current;
+        if (equal) dirtyFields.current.delete(dirtyKey);
+        else dirtyFields.current.add(dirtyKey);
+        listeners.current.forEach((listener)=>{
+            listener(next);
+        });
+        notifyMeta();
+    }, [
+        clone
+    ]);
+    const subscribe = useCallback((listener)=>{
+        listeners.current.add(listener);
+        return ()=>{
+            listeners.current.delete(listener);
+        };
+    }, []);
+    const commitInitial = useCallback(()=>{
+        initialRef.current = clone(valueRef.current);
+    }, [
+        clone
+    ]);
+    return {
+        get,
+        set,
+        subscribe,
+        commitInitial
+    };
+}
+export { useTrackedSlot };

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.1",
+  "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.1",
-    "@byline/i18n": "3.12.1",
-    "@byline/core": "3.12.1",
-    "@byline/ui": "3.12.1"
+    "@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
 }