payload-nested-docs-page-tree 1.1.0

package/LICENSE

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,132 @@
+# 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>
+
+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.
+
+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`.
+
+
+## Install
+
+```bash
+pnpm add payload-nested-docs-page-tree
+```
+
+## Quick Setup
+
+`@payloadcms/plugin-nested-docs` should already be installed, and each target collection should already have:
+
+- a nested docs parent field
+- a nested docs breadcrumbs field
+- a top-level `admin.useAsTitle` field
+
+Add `nestedDocsPageTreePlugin(...)` right after `nestedDocsPlugin(...)`:
+
+```ts
+import { nestedDocsPlugin } from '@payloadcms/plugin-nested-docs'
+import { nestedDocsPageTreePlugin } from 'payload-nested-docs-page-tree'
+
+export const plugins = [
+  nestedDocsPlugin({
+    // your existing nested docs config
+  }),
+  nestedDocsPageTreePlugin({
+    collections: ['pages'],
+  }),
+]
+```
+
+If needed, 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
+- hides the read-only breadcrumbs field by default
+
+## Status Badges
+
+The tree view supports three document states:
+
+- `published`: live and up to date
+- `changed`: live, but has unpublished changes
+- `draft`: not published
+
+To override badge labels or colors, pass a `badges` object:
+
+```ts
+nestedDocsPageTreePlugin({
+  collections: ['pages'],
+  badges: {
+    labels: {
+      published: 'Live',
+      changed: 'Has Changes',
+      draft: 'Draft Only',
+    },
+    colors: {
+      published: '#1e90ff',
+      changed: '#9333ea',
+      draft: '#dc2626',
+    },
+  },
+}),
+```
+
+`labels` and `colors` are optional partial overrides. Missing entries fall back to the built-in defaults.
+
+## 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`
+- `badges`: optional label and color overrides for `published`, `changed`, and `draft`
+
+## Development
+
+For local plugin development, use the internal `dev/` app:
+
+```bash
+pnpm install
+pnpm dev
+pnpm generate:types
+pnpm generate:importmap
+```
+
+Plugin source is in `src/`. The internal test app is in `dev/`.
+
+For checks:
+
+```bash
+pnpm test:int
+pnpm exec tsc --noEmit
+```
+
+## Test in Another Project
+
+For release validation, test the packed artifact instead of a live source-folder dependency:
+
+```bash
+pnpm build
+pnpm pack
+```
+
+Then in the external consumer app:
+
+```bash
+pnpm add /path/payload-nested-docs-page-tree-*.tgz
+```

package/dist/components/PageTreeContext.d.ts

@@ -0,0 +1,15 @@
+import React from 'react';
+type PageTreeContextValue = {
+    activeDragRowID: null | string;
+    canMoveDocs: boolean;
+    collapsedIDs: ReadonlySet<string>;
+    disableMoveDrag?: boolean;
+    pendingMoveRowID: null | string;
+    toggleRow: (rowID: string) => void;
+};
+export declare function PageTreeProvider({ children, value, }: {
+    children: React.ReactNode;
+    value: PageTreeContextValue;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function usePageTree(): PageTreeContextValue;
+export {};

package/dist/components/PageTreeContext.js

@@ -0,0 +1,26 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+const PageTreeContext = /*#__PURE__*/ React.createContext(null);
+export function PageTreeProvider({ children, value }) {
+    return /*#__PURE__*/ _jsx(PageTreeContext.Provider, {
+        value: value,
+        children: children
+    });
+}
+export function usePageTree() {
+    const context = React.useContext(PageTreeContext);
+    if (!context) {
+        return {
+            activeDragRowID: null,
+            canMoveDocs: false,
+            collapsedIDs: new Set(),
+            disableMoveDrag: false,
+            pendingMoveRowID: null,
+            toggleRow: ()=>{}
+        };
+    }
+    return context;
+}
+
+//# sourceMappingURL=PageTreeContext.js.map

package/dist/components/PageTreeContext.js.map

@@ -0,0 +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"}

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

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