payload-nested-docs-page-tree 1.2.3 → 1.4.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 WLF Studios
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 WLF Studios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,16 @@
-# Payload Nested Docs Page Tree
+# payload-nested-docs-page-tree
 
 Companion admin plugin for [`@payloadcms/plugin-nested-docs`](https://payloadcms.com/docs/plugins/nested-docs).
 
-<p align="center">
-  <img alt="Page tree demo" src="assets/page-tree.gif" width="100%" />
-</p>
+<p align="center">
+  <img alt="Page tree admin overview" src="assets/page-tree-admin-overview.png" width="100%" />
+</p>
 
-Adds a nested tree list view for nested docs collections in Payload admin, with drag-and-drop parent changes and status badges for published / changed / draft documents.
+Adds a nested tree list view for nested docs collections in Payload admin, with visual hierarchy shading, live URL path previews, separate reorder and parent-move interactions, and status badges for published / changed / draft documents.
 
 It works alongside `@payloadcms/plugin-nested-docs`. It does not replace nested docs persistence, breadcrumbs generation, or routing.
 
-Tested with Payload `3.84.1` and Next.js `16.2`.
+Tested with Payload `3.81` and Next.js `16.2`.
 
 
 ## Install
@@ -43,23 +43,67 @@ export const plugins = [
 ]
 ```
 
-If needed, refresh the admin import map:
+Refresh the admin import map:
 
 ```bash
 payload generate:importmap
 ```
 
-## What It Adds
-
-- replaces the collection list view with a nested tree table
-- preserves sorting, filters, pagination, bulk selection, and row actions
-- adds `POST /:id/move` for drag-and-drop parent changes
-- marks the root page with slug `home` using a home icon on the title link
-- hides the read-only breadcrumbs field by default
-
-## Home Indicator
-
-By default, the home icon is enabled only for the `pages` collection.
+## What It Adds
+
+- replaces the collection list view with a nested tree table
+- adds visual hierarchy shading for nested pages
+- shows the live URL path for each page
+- preserves sorting, filters, pagination, bulk selection, and row actions
+- adds `POST /:id/move` for intentional parent changes
+- adds `POST /:id/reorder` for orderable-only sibling reordering
+- keeps reorder drags scoped to the same parent or root level
+- marks the root page with slug `home` using a home icon on the title link
+- hides the read-only breadcrumbs field by default
+
+## Feature Preview
+
+### Visual hierarchy shading
+
+<p align="center">
+  <img alt="Visual hierarchy shading for nested pages" src="assets/visual-hierarchy-shading.png" width="100%" />
+</p>
+
+### Homepage icon
+
+<p align="center">
+  <img alt="Homepage icon in the page tree" src="assets/homepage-icon.png" width="100%" />
+</p>
+
+### Live URL path preview
+
+<p align="center">
+  <img alt="Live URL path preview in the page tree" src="assets/live-url-path-preview.png" width="100%" />
+</p>
+
+## Drag-And-Drop Modes
+
+Parent moves and orderable reordering are separate interactions.
+
+For collections using Payload `orderable`, the reorder handle is shown only when the current sort is the orderable field. Reordering only changes the order key and is limited to documents under the same parent, or documents at the root level. A reorder drag cannot change a document's parent.
+
+[Watch the orderable-only reorder handle demo](assets/orderable-reorder-handle.mp4)
+
+Parent moves are hidden by default because they change the page hierarchy. Editors can enable the parent-move handle with the `Edit Hierarchy` button when they intentionally want to move pages between parents. Drag a page onto another page to make it a child of that page. Drag it between root pages to move it back to the root level.
+
+[Watch the edit hierarchy mode demo](assets/edit-hierarchy-mode.mp4)
+
+[Watch the parent move to child demo](assets/parent-move-to-child.mp4)
+
+[Watch the parent move back to root demo](assets/parent-move-to-root.mp4)
+
+[Watch the same-parent reorder guard demo](assets/reorder-same-parent-only.mp4)
+
+Internally, parent moves call this plugin's `/:id/move` endpoint. That endpoint updates the nested docs parent field through Payload's local API, while `@payloadcms/plugin-nested-docs` continues to own parent and breadcrumb behavior through its normal fields and hooks.
+
+## Home Indicator
+
+By default, the home icon is enabled only for the `pages` collection.
 
 ```ts
 nestedDocsPageTreePlugin({
@@ -95,35 +139,90 @@ The tree view supports three document states:
 - `changed`: live, but has unpublished changes
 - `draft`: not published
 
-To override badge labels or colors, pass a `badges` object:
-
-```ts
-nestedDocsPageTreePlugin({
+Badge colors use Payload theme colors by default. To override badge labels or status colors, pass a `badges` object. Custom colors are treated as one base color per status and are adapted for both light and dark Payload themes:
+
+<p align="center">
+  <img alt="Custom status badges in the page tree" src="assets/custom-status-badges.png" width="100%" />
+</p>
+
+```ts
+nestedDocsPageTreePlugin({
   collections: ['pages'],
   badges: {
-    labels: {
-      published: 'Live',
-      changed: 'Has Changes',
-      draft: 'Draft Only',
-    },
     colors: {
-      published: '#1e90ff',
-      changed: '#9333ea',
-      draft: '#dc2626',
+      // Example: use a custom green / blue / orange palette.
+      published: '#bbf3b0',
+      changed: '#b9eaf3',
+      draft: '#f8d5a7',
+    },
+    labels: {
+      // Example: use custom labels for states.
+      published: 'Live',
+      changed: 'Has Changes',
+      draft: 'Draft Only',
     },
   },
 }),
 ```
 
-`labels` and `colors` are optional partial overrides. Missing entries fall back to the built-in defaults.
+`labels` and `colors` are optional partial overrides. Missing entries fall back to the built-in Payload-themed defaults for published, changed, and draft states.
+
+## Configuration
+
+- `collections`: target collection slugs
+- `parentFieldSlug`: defaults to `'parent'`
+- `breadcrumbsFieldSlug`: defaults to `'breadcrumbs'`
+- `defaultLimit`: defaults to `100`
+- `hideBreadcrumbs`: defaults to `true`
+- `disabled`: defaults to `false`
+- `homeIndicator`: defaults to `{ collections: ['pages'] }`; set to `false` to disable
+- `badges`: optional label and color overrides for `published`, `changed`, and `draft`
+- `diagnostics`: defaults to `false`. Enables structured diagnostic logging for tree-related publish/draft regressions; see below.
+
+## Diagnostics Mode
+
+If a page-tree move or reorder is doing something unexpected, enable diagnostics and reproduce. Each page-tree-triggered write emits one or more structured events on the dev server stdout:
+
+<p align="center">
+  <img alt="Diagnostics mode structured logs" src="assets/diagnostics-mode-logs.png" width="100%" />
+</p>
+
+```ts
+nestedDocsPageTreePlugin({
+  collections: ['pages'],
+  diagnostics: true,
+})
+```
+
+Or with a custom sink:
+
+```ts
+nestedDocsPageTreePlugin({
+  collections: ['pages'],
+  diagnostics: {
+    enabled: true,
+    logger: (event) => req.payload.logger.info({ pageTree: event }),
+  },
+})
+```
+
+Each event is one line tagged `[payload-nested-docs-page-tree]` followed by the event source (`move-endpoint:enter`, `move-endpoint:ok`, `move-endpoint:error`, `reorder-endpoint:enter`, `reorder-endpoint:ok`, `reorder-endpoint:error`, `page-tree-change:after`, `page-tree-change:status-flip`) and a JSON payload that includes:
+
+- `flow`: id shared by every event for one logical operation
+- `publishedMainRowBefore` / `publishedMainRowAfter`: fresh reads of the public/published row (`draft: false`)
+- `before` / `after` / `changed`: projected diffs for `_status`, the parent field, and the orderable field when present
+
+If the published main row goes from `published` to anything else as a result of a page-tree change, the plugin additionally emits a `page-tree-change:status-flip` WARN line.
+
+Diagnostics is opt-in and adds extra reads per operation. Leave it off in production unless you are actively investigating.
 
 ## Drag-And-Drop Is Triggering A Deploy?
 
-A drag-and-drop move calls `payload.update()` on the draft only. The published version of the live site is never touched. So in most setups, dragging a page does not trigger any rebuild and you can skip this section.
+A drag-and-drop parent move calls `payload.update()` on the draft only. The published version of the live site is never touched. So in most setups, dragging a page does not trigger any rebuild and you can skip this section.
 
 ### When you can skip this section
 
-- The default Payload website template on Vercel (or any host using Next.js ISR), with drafts and autosave on. The template's `afterChange` hook only calls `revalidatePath` and `revalidateTag` from `next/cache`. Those just clear the edge cache. They do not trigger a Vercel build, do not consume build minutes, and do not change what visitors see when the published HTML hasn't changed.
+- The default Payload website template on Vercel (or any host using Next.js ISR), with drafts and autosave on. The template's `afterChange` hook only calls `revalidatePath` and `revalidateTag` from `next/cache`. Those just clear the edge cache. They do not trigger a Vercel build, do not consume build minutes, and do not change what visitors see when the published HTML has not changed.
 - Any setup where your `afterChange` hooks only do in-process cache work (`revalidatePath`, `revalidateTag`, in-memory caches, etc.).
 
 ### When you need the one-line fix
@@ -136,11 +235,11 @@ You need the fix if **you** wrote an `afterChange` hook that calls something ext
 - **Publish notifications** (email, Slack) on status transitions.
 - **Heavy search reindex jobs** (Algolia, Meilisearch full-document push).
 
-Why a tree move trips these: a typical deploy hook fires when `previousDoc?._status === 'published'` so that it catches unpublish events too. A tree move on a published doc matches that condition (the previous draft state was published) - but the live site hasn't actually changed. Without the fix, every drag fires your deploy.
+Why a tree move trips these: a typical deploy hook fires when `previousDoc?._status === 'published'` so that it catches unpublish events too. A tree move on a published doc can match that condition, but the live site has not actually changed. Without the fix, every drag can fire your deploy.
 
 ### The fix
 
-Add one line at the top of your hook. The plugin sets a flag on Payload's [hook context](https://payloadcms.com/docs/hooks/context) for every move, and your hook reads it to bail out early:
+Add one line at the top of your hook. The plugin sets a flag on Payload's [hook context](https://payloadcms.com/docs/hooks/context) for every page-tree parent move, and your hook reads it to bail out early:
 
 ```ts
 import { pageTreeMoveContextKey } from 'payload-nested-docs-page-tree'
@@ -155,6 +254,7 @@ Full example:
 
 ```ts
 import type { CollectionAfterChangeHook } from 'payload'
+
 import { pageTreeMoveContextKey } from 'payload-nested-docs-page-tree'
 
 export const triggerDeployOnPublishedChange: CollectionAfterChangeHook = async ({
@@ -173,18 +273,7 @@ export const triggerDeployOnPublishedChange: CollectionAfterChangeHook = async (
 }
 ```
 
-See `dev/lib/rebuild.ts` for the full reference example.
-
-## Configuration
-
-- `collections`: target collection slugs
-- `parentFieldSlug`: defaults to `'parent'`
-- `breadcrumbsFieldSlug`: defaults to `'breadcrumbs'`
-- `defaultLimit`: defaults to `100`
-- `hideBreadcrumbs`: defaults to `true`
-- `homeIndicator`: defaults to `{ collections: ['pages'] }`; set to `false` to disable
-- `disabled`: defaults to `false`
-- `badges`: optional label and color overrides for `published`, `changed`, and `draft`
+See `dev/lib/rebuild.ts` for the full Cloudflare deploy hook example used by the dev playground.
 
 ## Development
 

package/dist/components/PageTreeContext.d.ts

@@ -1,15 +1,27 @@
+import type { DraggableAttributes, DraggableSyntheticListeners } from '@dnd-kit/core';
 import React from 'react';
 type PageTreeContextValue = {
     activeDragRowID: null | string;
     canMoveDocs: boolean;
     collapsedIDs: ReadonlySet<string>;
-    disableMoveDrag?: boolean;
+    parentMoveEnabled: boolean;
     pendingMoveRowID: null | string;
     toggleRow: (rowID: string) => void;
 };
+type PageTreeRowDndContextValue = {
+    isOrderDragging: boolean;
+    orderHandleAttributes: DraggableAttributes;
+    orderHandleListeners: DraggableSyntheticListeners;
+    orderHandleRef: (element: HTMLElement | null) => void;
+};
 export declare function PageTreeProvider({ children, value, }: {
     children: React.ReactNode;
     value: PageTreeContextValue;
 }): import("react/jsx-runtime").JSX.Element;
+export declare function PageTreeRowDndProvider({ children, value, }: {
+    children: React.ReactNode;
+    value: PageTreeRowDndContextValue;
+}): import("react/jsx-runtime").JSX.Element;
 export declare function usePageTree(): PageTreeContextValue;
+export declare function usePageTreeRowDnd(): null | PageTreeRowDndContextValue;
 export {};

package/dist/components/PageTreeContext.js

@@ -2,12 +2,19 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React from 'react';
 const PageTreeContext = /*#__PURE__*/ React.createContext(null);
+const PageTreeRowDndContext = /*#__PURE__*/ React.createContext(null);
 export function PageTreeProvider({ children, value }) {
     return /*#__PURE__*/ _jsx(PageTreeContext.Provider, {
         value: value,
         children: children
     });
 }
+export function PageTreeRowDndProvider({ children, value }) {
+    return /*#__PURE__*/ _jsx(PageTreeRowDndContext.Provider, {
+        value: value,
+        children: children
+    });
+}
 export function usePageTree() {
     const context = React.useContext(PageTreeContext);
     if (!context) {
@@ -15,12 +22,15 @@ export function usePageTree() {
             activeDragRowID: null,
             canMoveDocs: false,
             collapsedIDs: new Set(),
-            disableMoveDrag: false,
+            parentMoveEnabled: false,
             pendingMoveRowID: null,
             toggleRow: ()=>{}
         };
     }
     return context;
 }
+export function usePageTreeRowDnd() {
+    return React.useContext(PageTreeRowDndContext);
+}
 
 //# sourceMappingURL=PageTreeContext.js.map

package/dist/components/PageTreeContext.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/PageTreeContext.tsx"],"sourcesContent":["'use client'\n\nimport React from 'react'\n\ntype PageTreeContextValue = {\n  activeDragRowID: null | string\n  canMoveDocs: boolean\n  collapsedIDs: ReadonlySet<string>\n  disableMoveDrag?: boolean\n  pendingMoveRowID: null | string\n  toggleRow: (rowID: string) => void\n}\n\nconst PageTreeContext = React.createContext<null | PageTreeContextValue>(null)\n\nexport function PageTreeProvider({\n  children,\n  value,\n}: {\n  children: React.ReactNode\n  value: PageTreeContextValue\n}) {\n  return <PageTreeContext.Provider value={value}>{children}</PageTreeContext.Provider>\n}\n\nexport function usePageTree(): PageTreeContextValue {\n  const context = React.useContext(PageTreeContext)\n\n  if (!context) {\n    return {\n      activeDragRowID: null,\n      canMoveDocs: false,\n      collapsedIDs: new Set<string>(),\n      disableMoveDrag: false,\n      pendingMoveRowID: null,\n      toggleRow: () => {},\n    }\n  }\n\n  return context\n}\n"],"names":["React","PageTreeContext","createContext","PageTreeProvider","children","value","Provider","usePageTree","context","useContext","activeDragRowID","canMoveDocs","collapsedIDs","Set","disableMoveDrag","pendingMoveRowID","toggleRow"],"mappings":"AAAA;;AAEA,OAAOA,WAAW,QAAO;AAWzB,MAAMC,gCAAkBD,MAAME,aAAa,CAA8B;AAEzE,OAAO,SAASC,iBAAiB,EAC/BC,QAAQ,EACRC,KAAK,EAIN;IACC,qBAAO,KAACJ,gBAAgBK,QAAQ;QAACD,OAAOA;kBAAQD;;AAClD;AAEA,OAAO,SAASG;IACd,MAAMC,UAAUR,MAAMS,UAAU,CAACR;IAEjC,IAAI,CAACO,SAAS;QACZ,OAAO;YACLE,iBAAiB;YACjBC,aAAa;YACbC,cAAc,IAAIC;YAClBC,iBAAiB;YACjBC,kBAAkB;YAClBC,WAAW,KAAO;QACpB;IACF;IAEA,OAAOR;AACT"}
+{"version":3,"sources":["../../src/components/PageTreeContext.tsx"],"sourcesContent":["'use client'\r\n\r\nimport type { DraggableAttributes, DraggableSyntheticListeners } from '@dnd-kit/core'\r\n\r\nimport React from 'react'\r\n\r\ntype PageTreeContextValue = {\r\n  activeDragRowID: null | string\r\n  canMoveDocs: boolean\r\n  collapsedIDs: ReadonlySet<string>\r\n  parentMoveEnabled: boolean\r\n  pendingMoveRowID: null | string\r\n  toggleRow: (rowID: string) => void\r\n}\r\n\r\ntype PageTreeRowDndContextValue = {\r\n  isOrderDragging: boolean\r\n  orderHandleAttributes: DraggableAttributes\r\n  orderHandleListeners: DraggableSyntheticListeners\r\n  orderHandleRef: (element: HTMLElement | null) => void\r\n}\r\n\r\nconst PageTreeContext = React.createContext<null | PageTreeContextValue>(null)\r\nconst PageTreeRowDndContext = React.createContext<null | PageTreeRowDndContextValue>(null)\r\n\r\nexport function PageTreeProvider({\r\n  children,\r\n  value,\r\n}: {\r\n  children: React.ReactNode\r\n  value: PageTreeContextValue\r\n}) {\r\n  return <PageTreeContext.Provider value={value}>{children}</PageTreeContext.Provider>\r\n}\r\n\r\nexport function PageTreeRowDndProvider({\r\n  children,\r\n  value,\r\n}: {\r\n  children: React.ReactNode\r\n  value: PageTreeRowDndContextValue\r\n}) {\r\n  return <PageTreeRowDndContext.Provider value={value}>{children}</PageTreeRowDndContext.Provider>\r\n}\r\n\r\nexport function usePageTree(): PageTreeContextValue {\r\n  const context = React.useContext(PageTreeContext)\r\n\r\n  if (!context) {\r\n    return {\r\n      activeDragRowID: null,\r\n      canMoveDocs: false,\r\n      collapsedIDs: new Set<string>(),\r\n      parentMoveEnabled: false,\r\n      pendingMoveRowID: null,\r\n      toggleRow: () => {},\r\n    }\r\n  }\r\n\r\n  return context\r\n}\r\n\r\nexport function usePageTreeRowDnd(): null | PageTreeRowDndContextValue {\r\n  return React.useContext(PageTreeRowDndContext)\r\n}\r\n"],"names":["React","PageTreeContext","createContext","PageTreeRowDndContext","PageTreeProvider","children","value","Provider","PageTreeRowDndProvider","usePageTree","context","useContext","activeDragRowID","canMoveDocs","collapsedIDs","Set","parentMoveEnabled","pendingMoveRowID","toggleRow","usePageTreeRowDnd"],"mappings":"AAAA;;AAIA,OAAOA,WAAW,QAAO;AAkBzB,MAAMC,gCAAkBD,MAAME,aAAa,CAA8B;AACzE,MAAMC,sCAAwBH,MAAME,aAAa,CAAoC;AAErF,OAAO,SAASE,iBAAiB,EAC/BC,QAAQ,EACRC,KAAK,EAIN;IACC,qBAAO,KAACL,gBAAgBM,QAAQ;QAACD,OAAOA;kBAAQD;;AAClD;AAEA,OAAO,SAASG,uBAAuB,EACrCH,QAAQ,EACRC,KAAK,EAIN;IACC,qBAAO,KAACH,sBAAsBI,QAAQ;QAACD,OAAOA;kBAAQD;;AACxD;AAEA,OAAO,SAASI;IACd,MAAMC,UAAUV,MAAMW,UAAU,CAACV;IAEjC,IAAI,CAACS,SAAS;QACZ,OAAO;YACLE,iBAAiB;YACjBC,aAAa;YACbC,cAAc,IAAIC;YAClBC,mBAAmB;YACnBC,kBAAkB;YAClBC,WAAW,KAAO;QACpB;IACF;IAEA,OAAOR;AACT;AAEA,OAAO,SAASS;IACd,OAAOnB,MAAMW,UAAU,CAACR;AAC1B"}

package/dist/components/PageTreeListView.client.d.ts

@@ -1,7 +1,7 @@
 import type { Column, ListQuery, ListViewClientProps } from 'payload';
-import { type NestedDocsPageTreePluginResolvedBadgeConfig, type PageTreeSourceDoc } from '../types.js';
+import type { NestedDocsPageTreePluginResolvedBadgeConfig, PageTreeSourceDoc } from '../types.js';
 import { type PageTreeDoc } from '../utilities/pageTree.js';
-type PageTreeListViewClientOwnProps = {
+type PageTreeListViewClientProps = {
     allDocs: PageTreeDoc[];
     badgeConfig: NestedDocsPageTreePluginResolvedBadgeConfig;
     canMoveDocs: boolean;
@@ -12,7 +12,6 @@ type PageTreeListViewClientOwnProps = {
     query: ListQuery;
     sourceDocs: PageTreeSourceDoc[];
     useAsTitle: string;
-};
-type PageTreeListViewClientProps = Omit<ListViewClientProps, 'columnState' | 'Table'> & PageTreeListViewClientOwnProps;
+} & Omit<ListViewClientProps, 'columnState' | 'Table'>;
 export default function PageTreeListViewClient({ allDocs, badgeConfig, canMoveDocs, columnState, homeIndicatorEnabled, orderableFieldName, parentFieldSlug, query, sourceDocs, useAsTitle, ...props }: PageTreeListViewClientProps): import("react/jsx-runtime").JSX.Element;
 export {};