feat(editor): recursive tree mode for the subpages node (#150)

The `subpages` node showed only one level of direct children. Add a `recursive`
attribute that renders the FULL descendant tree of the current page — fully
expanded, unlimited depth. Default `false`, so every previously-inserted node
stays flat (backward compatible). No backend changes: `POST /pages/tree` (via the
`getSpaceTree` wrapper) already returns the whole subtree as a flat `IPage[]`
(recursive CTE, permission-filtered); the nested tree is built on the client by
`parentPageId`.

- editor-ext `subpages.ts`: `recursive` attribute (parse/render `data-recursive`),
  shared by client + server so the collab ProseMirror schema keeps the attribute.
- `getSpaceTree`: arg loosened to `{ spaceId?; pageId? }` (the endpoint accepts
  either); new `useGetPageTreeQuery(pageId)` react-query hook.
- `subpages-view.tsx`: split into `FlatSubpages` (unchanged) and
  `RecursiveSubpages`; `buildSubtree` assembles the nested tree (cycle/self-parent
  guard, `sortPositionKeys` per level, root excluded) and a recursive `TreeNode`
  renders it (16px indent per depth, soft "showing N" note past 300 — data never
  capped). Shared/public context reads the already-nested shared tree, no
  `/pages/tree` request.
- toggles: bubble-menu flat⇄tree button + a second slash-menu item "Page tree".

Review follow-ups folded in: invalidate `["page-tree"]` from the create / update /
move / delete cache helpers so an open recursive tree refreshes (no stale data);
mode icon made reactive on editor transactions; `t` threaded into `TreeNode`
(no per-node useTranslation); shared-subtree hook deduped to a thin alias.

editor-ext build + client `tsc --noEmit` both clean. Backend untouched.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/client/src/features/editor/components/slash-menu/menu-items.ts

@@ -524,6 +524,29 @@ const CommandGroups: SlashMenuGroupedItemsType = {
         editor.chain().focus().deleteRange(range).insertSubpages().run();
       },
     },
+    {
+      title: "Page tree (child pages, recursive)",
+      description: "Render the full nested tree of all descendant pages",
+      searchTerms: [
+        "subpages",
+        "child",
+        "children",
+        "nested",
+        "hierarchy",
+        "tree",
+        "recursive",
+        "toc",
+      ],
+      icon: IconSitemap,
+      command: ({ editor, range }: CommandProps) => {
+        editor
+          .chain()
+          .focus()
+          .deleteRange(range)
+          .insertSubpages({ recursive: true })
+          .run();
+      },
+    },
     {
       title: "Synced block",
       description: "Create a block that stays in sync across pages.",

apps/client/src/features/editor/components/subpages/subpages-menu.tsx

@@ -1,9 +1,9 @@
 import { BubbleMenu as BaseBubbleMenu } from "@tiptap/react/menus";
 import { posToDOMRect, findParentNode } from "@tiptap/react";
 import { Node as PMNode } from "@tiptap/pm/model";
-import React, { useCallback } from "react";
-import { ActionIcon, Tooltip } from "@mantine/core";
-import { IconTrash } from "@tabler/icons-react";
+import React, { useCallback, useEffect, useState } from "react";
+import { ActionIcon, Group, Tooltip } from "@mantine/core";
+import { IconTrash, IconList, IconSitemap } from "@tabler/icons-react";
 import { useTranslation } from "react-i18next";
 import { Editor } from "@tiptap/core";
 import { isEditorReady } from "@docmost/editor-ext";
@@ -47,6 +47,13 @@ export const SubpagesMenu = React.memo(
       return posToDOMRect(editor.view, selection.from, selection.to);
     }, [editor]);
 
+    const toggleRecursive = useCallback(() => {
+      const current = editor.getAttributes("subpages")?.recursive ?? false;
+      editor.commands.updateAttributes("subpages", {
+        recursive: !current,
+      });
+    }, [editor]);
+
     const deleteNode = useCallback(() => {
       const { selection } = editor.state;
       editor
@@ -57,6 +64,25 @@ export const SubpagesMenu = React.memo(
         .run();
     }, [editor]);
 
+    // The component is memoized on `editor` (a stable reference), so reading the
+    // attribute at render time would leave the mode icon/tooltip stale right
+    // after toggling. Track it in state synced on editor transactions; setState
+    // bails when the value is unchanged, so this does not re-render per keystroke.
+    const [isRecursive, setIsRecursive] = useState<boolean>(
+      () => editor.getAttributes("subpages")?.recursive ?? false,
+    );
+    useEffect(() => {
+      const sync = () => {
+        const value = editor.getAttributes("subpages")?.recursive ?? false;
+        setIsRecursive((prev) => (prev === value ? prev : value));
+      };
+      sync();
+      editor.on("transaction", sync);
+      return () => {
+        editor.off("transaction", sync);
+      };
+    }, [editor]);
+
     return (
       <BaseBubbleMenu
         editor={editor}
@@ -64,17 +90,41 @@ export const SubpagesMenu = React.memo(
         updateDelay={0}
         shouldShow={shouldShow}
       >
-        <Tooltip position="top" label={t("Delete")}>
-          <ActionIcon
-            onClick={deleteNode}
-            variant="default"
-            size="lg"
-            color="red"
-            aria-label={t("Delete")}
+        <Group gap={4} wrap="nowrap">
+          <Tooltip
+            position="top"
+            label={
+              isRecursive
+                ? t("Switch to flat list")
+                : t("Switch to tree")
+            }
           >
-            <IconTrash size={18} />
-          </ActionIcon>
-        </Tooltip>
+            <ActionIcon
+              onClick={toggleRecursive}
+              variant="default"
+              size="lg"
+              aria-label={t("Toggle subpages display mode")}
+            >
+              {isRecursive ? (
+                <IconList size={18} />
+              ) : (
+                <IconSitemap size={18} />
+              )}
+            </ActionIcon>
+          </Tooltip>
+
+          <Tooltip position="top" label={t("Delete")}>
+            <ActionIcon
+              onClick={deleteNode}
+              variant="default"
+              size="lg"
+              color="red"
+              aria-label={t("Delete")}
+            >
+              <IconTrash size={18} />
+            </ActionIcon>
+          </Tooltip>
+        </Group>
       </BaseBubbleMenu>
     );
   }

apps/client/src/features/editor/components/subpages/subpages-view.tsx

@@ -1,7 +1,10 @@
 import { NodeViewProps, NodeViewWrapper } from "@tiptap/react";
 import { Stack, Text, Anchor, ActionIcon } from "@mantine/core";
 import { IconFileDescription } from "@tabler/icons-react";
-import { useGetSidebarPagesQuery } from "@/features/page/queries/page-query";
+import {
+  useGetSidebarPagesQuery,
+  useGetPageTreeQuery,
+} from "@/features/page/queries/page-query";
 import { useMemo } from "react";
 import { Link, useParams } from "react-router-dom";
 import classes from "./subpages.module.css";
@@ -12,16 +15,194 @@ import {
 } from "@/features/page/page.utils.ts";
 import { useTranslation } from "react-i18next";
 import { sortPositionKeys } from "@/features/page/tree/utils/utils";
-import { useSharedPageSubpages } from "@/features/share/hooks/use-shared-page-subpages";
+import {
+  useSharedPageSubpages,
+  useSharedPageSubtree,
+} from "@/features/share/hooks/use-shared-page-subpages";
+import { IPage } from "@/features/page/types/page.types";
+import { SharedPageTreeNode } from "@/features/share/utils";
+
+// Threshold above which the recursive tree shows a small count note. We never
+// cap the data — this is only an informational hint for very large trees.
+const LARGE_TREE_THRESHOLD = 300;
+
+// Normalized node shared by the flat and recursive renderers so the same
+// link/icon markup works for both API pages and shared-tree nodes.
+interface SubpageNode {
+  id: string;
+  slugId: string;
+  title: string;
+  icon?: string;
+  children: SubpageNode[];
+}
+
+// Subpage node carrying `position` so each level can be sorted in place.
+type SubpageNodeWithPos = SubpageNode & {
+  position: string;
+  children: SubpageNodeWithPos[];
+};
+
+// Build a nested subtree from the flat IPage[] returned by /pages/tree.
+function buildSubtree(pages: IPage[], rootId: string): SubpageNode[] {
+  const byId = new Map<string, SubpageNodeWithPos>(
+    pages.map((p) => [
+      p.id,
+      {
+        id: p.id,
+        slugId: p.slugId,
+        title: p.title,
+        icon: p.icon,
+        position: p.position,
+        children: [],
+      },
+    ]),
+  );
+
+  for (const p of pages) {
+    const node = byId.get(p.id);
+    const parent = p.parentPageId ? byId.get(p.parentPageId) : undefined;
+    // Guard against cycles / self-parenting: never attach a node to itself or
+    // to the root, and only attach when the parent is actually present.
+    if (node && parent && p.id !== rootId) {
+      parent.children.push(node);
+    }
+  }
+
+  const sortRecursive = (nodes: SubpageNodeWithPos[]) => {
+    const sorted = sortPositionKeys(nodes) as SubpageNodeWithPos[];
+    sorted.forEach((n) => sortRecursive(n.children));
+    return sorted;
+  };
+
+  const root = byId.get(rootId);
+  return root ? sortRecursive(root.children) : [];
+}
+
+// Map shared-tree nodes (already nested) onto the normalized SubpageNode shape.
+function mapSharedNodes(nodes: SharedPageTreeNode[]): SubpageNode[] {
+  return nodes.map((node) => ({
+    id: node.value,
+    slugId: node.slugId,
+    title: node.name,
+    icon: node.icon,
+    children: node.children ? mapSharedNodes(node.children) : [],
+  }));
+}
+
+// Count every descendant in a normalized subtree.
+function countNodes(nodes: SubpageNode[]): number {
+  return nodes.reduce((acc, n) => acc + 1 + countNodes(n.children), 0);
+}
+
+interface TreeNodeProps {
+  node: SubpageNode;
+  depth: number;
+  shareId?: string;
+  spaceSlug?: string;
+  // Threaded down from the variant component so a large tree does not create one
+  // i18n subscription (useTranslation) per rendered node.
+  t: (key: string) => string;
+}
+
+// Recursive renderer for a single node and its descendants. Indents each level
+// by depth * 16px and reuses the same link/icon markup as the flat list.
+function TreeNode({ node, depth, shareId, spaceSlug, t }: TreeNodeProps) {
+  return (
+    <>
+      <Anchor
+        component={Link}
+        fw={500}
+        to={
+          shareId
+            ? buildSharedPageUrl({
+                shareId,
+                pageSlugId: node.slugId,
+                pageTitle: node.title,
+              })
+            : buildPageUrl(spaceSlug, node.slugId, node.title)
+        }
+        underline="never"
+        className={styles.pageMentionLink}
+        draggable={false}
+        style={{ paddingLeft: depth * 16 }}
+      >
+        {node?.icon ? (
+          <span style={{ marginRight: "4px" }}>{node.icon}</span>
+        ) : (
+          <ActionIcon
+            variant="transparent"
+            color="gray"
+            component="span"
+            size={18}
+            style={{ verticalAlign: "text-bottom" }}
+          >
+            <IconFileDescription size={18} />
+          </ActionIcon>
+        )}
+
+        <span className={styles.pageMentionText}>
+          {node?.title || t("untitled")}
+        </span>
+      </Anchor>
+
+      {node.children.map((child) => (
+        <TreeNode
+          key={child.id}
+          node={child}
+          depth={depth + 1}
+          shareId={shareId}
+          spaceSlug={spaceSlug}
+          t={t}
+        />
+      ))}
+    </>
+  );
+}
 
 export default function SubpagesView(props: NodeViewProps) {
   const { editor } = props;
   const { spaceSlug, shareId } = useParams();
   const { t } = useTranslation();
 
+  const recursive: boolean = props.node.attrs.recursive ?? false;
+
   //@ts-ignore
   const currentPageId = editor.storage.pageId;
 
+  if (recursive) {
+    return (
+      <RecursiveSubpages
+        currentPageId={currentPageId}
+        shareId={shareId}
+        spaceSlug={spaceSlug}
+        t={t}
+      />
+    );
+  }
+
+  return (
+    <FlatSubpages
+      currentPageId={currentPageId}
+      shareId={shareId}
+      spaceSlug={spaceSlug}
+      t={t}
+    />
+  );
+}
+
+interface SubpagesVariantProps {
+  currentPageId: string;
+  shareId?: string;
+  spaceSlug?: string;
+  t: (key: string) => string;
+}
+
+function FlatSubpages({
+  currentPageId,
+  shareId,
+  spaceSlug,
+  t,
+}: SubpagesVariantProps) {
   // Get subpages from shared tree if we're in a shared context
   const sharedSubpages = useSharedPageSubpages(currentPageId);
 
@@ -119,3 +300,78 @@ export default function SubpagesView(props: NodeViewProps) {
     </NodeViewWrapper>
   );
 }
+
+function RecursiveSubpages({
+  currentPageId,
+  shareId,
+  spaceSlug,
+  t,
+}: SubpagesVariantProps) {
+  // In a shared/public context reuse the already-loaded nested shared tree
+  // instead of issuing a /pages/tree request.
+  const sharedSubtree = useSharedPageSubtree(currentPageId);
+
+  const { data, isLoading, error } = useGetPageTreeQuery(
+    shareId ? "" : currentPageId,
+  );
+
+  const tree = useMemo<SubpageNode[]>(() => {
+    if (shareId) {
+      return mapSharedNodes(sharedSubtree);
+    }
+    if (!data) return [];
+    return buildSubtree(data, currentPageId);
+  }, [data, shareId, sharedSubtree, currentPageId]);
+
+  const total = useMemo(() => countNodes(tree), [tree]);
+
+  if (isLoading && !shareId) {
+    return null;
+  }
+
+  if (error && !shareId) {
+    return (
+      <NodeViewWrapper data-drag-handle>
+        <Text c="dimmed" size="md" py="md">
+          {t("Failed to load subpages")}
+        </Text>
+      </NodeViewWrapper>
+    );
+  }
+
+  if (tree.length === 0) {
+    return (
+      <NodeViewWrapper data-drag-handle>
+        <div className={classes.container}>
+          <Text c="dimmed" size="md" py="md">
+            {t("No subpages")}
+          </Text>
+        </div>
+      </NodeViewWrapper>
+    );
+  }
+
+  return (
+    <NodeViewWrapper data-drag-handle>
+      <div className={classes.container}>
+        <Stack gap={5}>
+          {tree.map((node) => (
+            <TreeNode
+              key={node.id}
+              node={node}
+              depth={0}
+              shareId={shareId}
+              spaceSlug={spaceSlug}
+              t={t}
+            />
+          ))}
+        </Stack>
+        {total > LARGE_TREE_THRESHOLD && (
+          <Text c="dimmed" size="xs" pt="xs">
+            {t("Showing")} {total} {t("subpages")}
+          </Text>
+        )}
+      </div>
+    </NodeViewWrapper>
+  );
+}

apps/client/src/features/page/queries/page-query.ts

@@ -21,6 +21,7 @@ import {
   getAllSidebarPages,
   getDeletedPages,
   restorePage,
+  getSpaceTree,
 } from "@/features/page/services/page-service";
 import {
   IMovePage,
@@ -303,6 +304,15 @@ export function useGetRootSidebarPagesQuery(data: SidebarPagesParams) {
   });
 }
 
+export function useGetPageTreeQuery(pageId: string) {
+  return useQuery({
+    queryKey: ["page-tree", pageId],
+    queryFn: () => getSpaceTree({ pageId }),
+    enabled: !!pageId,
+    staleTime: 30 * 1000,
+  });
+}
+
 export function usePageBreadcrumbsQuery(
   pageId: string,
 ): UseQueryResult<Partial<IPage[]>, Error> {
@@ -363,7 +373,18 @@ export function useDeletedPagesQuery(
   });
 }
 
+/**
+ * Invalidate every cached page-subtree (the recursive `subpages` node, issue
+ * #150). Called from each tree-structure cache helper below so a create / move /
+ * rename / delete (local OR websocket-echoed) refreshes any open recursive tree.
+ * Keyed loosely (`["page-tree"]` prefix) so all subtrees are caught.
+ */
+function invalidatePageTree() {
+  queryClient.invalidateQueries({ queryKey: ["page-tree"] });
+}
+
 export function invalidateOnCreatePage(data: Partial<IPage>) {
+  invalidatePageTree();
   const newPage: Partial<IPage> = {
     creatorId: data.creatorId,
     hasChildren: data.hasChildren,
@@ -478,6 +499,7 @@ export function invalidateOnUpdatePage(
   title: string,
   icon: string,
 ) {
+  invalidatePageTree();
   let queryKey: QueryKey = null;
   if (parentPageId === null) {
     queryKey = ["root-sidebar-pages", spaceId];
@@ -516,6 +538,7 @@ export function updateCacheOnMovePage(
   newParentId: string | null,
   pageData: Partial<IPage>,
 ) {
+  invalidatePageTree();
   // Remove page from old parent's cache
   const oldQueryKey =
     oldParentId === null
@@ -633,6 +656,7 @@ export function updateCacheOnMovePage(
 }
 
 export function invalidateOnDeletePage(pageId: string) {
+  invalidatePageTree();
   //update all sidebar pages
   const allSideBarMatches = queryClient.getQueriesData({
     predicate: (query) =>

apps/client/src/features/page/services/page-service.ts

@@ -93,7 +93,7 @@ export async function getAllSidebarPages(
 }
 
 export async function getSpaceTree(params: {
-  spaceId: string;
+  spaceId?: string;
   pageId?: string;
 }): Promise<IPage[]> {
   const req = await api.post<{ items: IPage[] }>("/pages/tree", params);

apps/client/src/features/share/hooks/use-shared-page-subpages.ts

@@ -27,3 +27,11 @@ export function useSharedPageSubpages(pageId: string | undefined) {
     return findSubpages(treeData);
   }, [treeData, pageId]);
 }
+
+// Recursive variant for the subpages node in a shared/public context. The shared
+// tree (`sharedTreeDataAtom`) is ALREADY fully nested, so a page's `children`
+// each carry their own nested `children` — exactly what the recursive renderer
+// needs. The data is therefore identical to the flat hook; only the rendering
+// differs (the recursive view walks `children` instead of showing one level).
+// Thin alias to avoid duplicating the lookup. No `/pages/tree` request here.
+export const useSharedPageSubtree = useSharedPageSubpages;

packages/editor-ext/src/lib/subpages/subpages.ts

@@ -6,7 +6,9 @@ export interface SubpagesOptions {
   view: any;
 }
 
-export interface SubpagesAttributes {}
+export interface SubpagesAttributes {
+  recursive?: boolean;
+}
 
 declare module "@tiptap/core" {
   interface Commands<ReturnType> {
@@ -31,6 +33,18 @@ export const Subpages = Node.create<SubpagesOptions>({
   draggable: true,
   isolating: true,
 
+  addAttributes() {
+    return {
+      recursive: {
+        // Existing nodes stay flat -> backward compatible.
+        default: false,
+        parseHTML: (el) => el.getAttribute("data-recursive") === "true",
+        renderHTML: (attrs) =>
+          attrs.recursive ? { "data-recursive": "true" } : {},
+      },
+    };
+  },
+
   parseHTML() {
     return [
       {