@phis/ui 0.1.0

package/plugins/runtime-modules/builder/navigation-folder-address.d.ts

@@ -0,0 +1,46 @@
+import type { PhiBuilderNavigationItem } from "../../../helpers/cms-navigation-catalog";
+import type { PhiCmsNavigationFolderTarget } from "../../../types/cms-module-descriptors";
+/**
+ * The Area-relative path a link leads to, package namespace included -- the form a request for a folder
+ * address carries -- or null for a link that has none, such as an external one.
+ */
+export type PhiBuilderNavigationLinkPathResolver = (item: PhiBuilderNavigationItem) => string | null;
+/**
+ * The folder a container's direct children share (TODOS.md, "Folder addresses"). Each child contributes
+ * the folder it lies in: `/docs/a` and the container `/docs/guides` both contribute `/docs`. Children
+ * from different folders, or only from the Area root, which is a slot and no folder, give no address.
+ */
+export declare function resolvePhiBuilderNavigationFolderAddress(container: PhiBuilderNavigationItem, resolveLinkPath: PhiBuilderNavigationLinkPathResolver): string | null;
+export type PhiBuilderNavigationFolderChoice = {
+    /** A stable key for the target, usable as a Select value. */
+    value: string;
+    /** The Area-relative path the child stands for. */
+    label: string;
+    target: PhiCmsNavigationFolderTarget;
+};
+export declare function encodePhiBuilderNavigationFolderTarget(target: PhiCmsNavigationFolderTarget): string;
+/**
+ * The targets a container can lead to: what each of its direct children stands for. Two children that
+ * stand for the same target are offered once.
+ */
+export declare function listPhiBuilderNavigationFolderChoices(container: PhiBuilderNavigationItem, resolveLinkPath: PhiBuilderNavigationLinkPathResolver): PhiBuilderNavigationFolderChoice[];
+/**
+ * The choice a container's stored target matches among its children now, or null -- which reads as 404:
+ * the target another Navigation carried over, or one a child no longer stands for.
+ */
+export declare function findPhiBuilderNavigationFolderChoice(container: PhiBuilderNavigationItem, resolveLinkPath: PhiBuilderNavigationLinkPathResolver): PhiBuilderNavigationFolderChoice | null;
+/**
+ * Brings every container's stored folder address in line with its children as they are now. A container
+ * that has an address keeps it even without a target, so a target chosen for the same folder in another
+ * Navigation finds it; one with neither carries no folder. The target is left alone: a target no child
+ * stands for any more reads as 404.
+ */
+export declare function refreshPhiBuilderNavigationFolderAddresses<TItems extends readonly PhiBuilderNavigationItem[]>(items: TItems, resolveLinkPath: PhiBuilderNavigationLinkPathResolver): TItems;
+/**
+ * Sets the given targets on every container whose folder address they name: the same folder holds one
+ * target, within one Navigation as across Navigations.
+ */
+export declare function applyPhiBuilderNavigationFolderTargets<TItems extends readonly PhiBuilderNavigationItem[]>(items: TItems, folders: readonly {
+    address: string;
+    target: PhiCmsNavigationFolderTarget | null;
+}[]): TItems;

package/plugins/runtime-modules/builder/navigation-folder-address.js

@@ -0,0 +1,129 @@
+import { createPhiPageReference } from "../../../types/references";
+function parentFolder(path) {
+    const index = path.lastIndexOf("/");
+    return index > 0 ? path.slice(0, index) : "/";
+}
+/**
+ * The path a direct child stands for in its container: a link its target's path, a container its own
+ * folder address. Separators and links without a path stand for nothing.
+ */
+function resolveChildPath(child, resolveLinkPath) {
+    if (child.kind === "container")
+        return resolvePhiBuilderNavigationFolderAddress(child, resolveLinkPath);
+    if (child.kind === "link")
+        return resolveLinkPath(child);
+    return null;
+}
+/**
+ * The folder a container's direct children share (TODOS.md, "Folder addresses"). Each child contributes
+ * the folder it lies in: `/docs/a` and the container `/docs/guides` both contribute `/docs`. Children
+ * from different folders, or only from the Area root, which is a slot and no folder, give no address.
+ */
+export function resolvePhiBuilderNavigationFolderAddress(container, resolveLinkPath) {
+    if (container.kind !== "container")
+        return null;
+    const folders = new Set(container.children.flatMap((child) => {
+        const path = resolveChildPath(child, resolveLinkPath);
+        return path ? [parentFolder(path)] : [];
+    }));
+    const [only] = folders;
+    return folders.size === 1 && only !== "/" ? only : null;
+}
+export function encodePhiBuilderNavigationFolderTarget(target) {
+    return target.kind === "page" ? `page:${target.reference}` : `folder:${target.address}`;
+}
+/** What a direct child stands for as a folder target: a Page by reference, a sub-container by address. */
+function resolveChildTarget(child, resolveLinkPath) {
+    const path = resolveChildPath(child, resolveLinkPath);
+    if (!path)
+        return null;
+    if (child.kind === "container") {
+        const target = { kind: "folder", address: path };
+        return { value: encodePhiBuilderNavigationFolderTarget(target), label: path, target };
+    }
+    const reference = child.targetReference ??
+        (child.targetPreset ? createPhiPageReference({ kind: "module", ...child.targetPreset }) : null);
+    if (!reference)
+        return null;
+    const target = { kind: "page", reference };
+    return { value: encodePhiBuilderNavigationFolderTarget(target), label: path, target };
+}
+/**
+ * The targets a container can lead to: what each of its direct children stands for. Two children that
+ * stand for the same target are offered once.
+ */
+export function listPhiBuilderNavigationFolderChoices(container, resolveLinkPath) {
+    if (container.kind !== "container")
+        return [];
+    const seen = new Set();
+    return container.children.flatMap((child) => {
+        const choice = resolveChildTarget(child, resolveLinkPath);
+        if (!choice || seen.has(choice.value))
+            return [];
+        seen.add(choice.value);
+        return [choice];
+    });
+}
+/**
+ * The choice a container's stored target matches among its children now, or null -- which reads as 404:
+ * the target another Navigation carried over, or one a child no longer stands for.
+ */
+export function findPhiBuilderNavigationFolderChoice(container, resolveLinkPath) {
+    if (!container.folder?.target)
+        return null;
+    const value = encodePhiBuilderNavigationFolderTarget(container.folder.target);
+    return listPhiBuilderNavigationFolderChoices(container, resolveLinkPath).find((choice) => choice.value === value) ?? null;
+}
+/**
+ * Brings every container's stored folder address in line with its children as they are now. A container
+ * that has an address keeps it even without a target, so a target chosen for the same folder in another
+ * Navigation finds it; one with neither carries no folder. The target is left alone: a target no child
+ * stands for any more reads as 404.
+ */
+export function refreshPhiBuilderNavigationFolderAddresses(items, resolveLinkPath) {
+    let changed = false;
+    const refreshed = items.map((item) => {
+        const children = refreshPhiBuilderNavigationFolderAddresses(item.children, resolveLinkPath);
+        let next = children === item.children ? item : { ...item, children };
+        if (item.kind === "container") {
+            const address = resolvePhiBuilderNavigationFolderAddress(next, resolveLinkPath);
+            const target = item.folder?.target ?? null;
+            if (address == null && target == null) {
+                if (item.folder)
+                    next = { ...next, folder: null };
+            }
+            else if (address !== (item.folder?.address ?? null) || !item.folder) {
+                next = { ...next, folder: { address, target } };
+            }
+        }
+        if (next !== item)
+            changed = true;
+        return next;
+    });
+    // Unchanged trees keep their identity, so a store that compares by reference sees no edit.
+    return (changed ? refreshed : items);
+}
+/**
+ * Sets the given targets on every container whose folder address they name: the same folder holds one
+ * target, within one Navigation as across Navigations.
+ */
+export function applyPhiBuilderNavigationFolderTargets(items, folders) {
+    const targets = new Map(folders.map((folder) => [folder.address, folder.target]));
+    let changed = false;
+    const applied = items.map((item) => {
+        const children = applyPhiBuilderNavigationFolderTargets(item.children, folders);
+        let next = children === item.children ? item : { ...item, children };
+        const address = item.folder?.address;
+        if (item.kind === "container" && address && targets.has(address)) {
+            const target = targets.get(address) ?? null;
+            const same = (item.folder?.target ? encodePhiBuilderNavigationFolderTarget(item.folder.target) : "") ===
+                (target ? encodePhiBuilderNavigationFolderTarget(target) : "");
+            if (!same)
+                next = { ...next, folder: { address, target } };
+        }
+        if (next !== item)
+            changed = true;
+        return next;
+    });
+    return (changed ? applied : items);
+}

package/plugins/runtime-modules/builder/navigation-folder-drop.d.ts

@@ -0,0 +1,19 @@
+import type { PhiBuilderNavigationItem } from "../../../helpers/cms-navigation-catalog";
+import type { PhiPresetPageNode } from "../../../helpers/cms-page-catalog";
+/** A Page the Navigation can point at: it has a stable reference and has not been deleted. */
+export declare function isPhiBuilderNavigablePage(node: PhiPresetPageNode): boolean;
+/** Whether a catalog node would give the Navigation anything: a live Page, or one somewhere beneath it. */
+export declare function hasPhiBuilderNavigableContent(node: PhiPresetPageNode): boolean;
+export declare function findPhiBuilderCatalogNode(nodes: readonly PhiPresetPageNode[], key: string): PhiPresetPageNode | null;
+export type PhiBuilderCatalogNavigationFactory = {
+    /** Called in document order, a container before its children, so ids follow the tree. */
+    allocateId: () => Promise<PhiBuilderNavigationItem["id"]>;
+    createPageItem: (id: PhiBuilderNavigationItem["id"], page: PhiPresetPageNode) => PhiBuilderNavigationItem | null;
+    createContainerItem: (id: PhiBuilderNavigationItem["id"], label: string, children: PhiBuilderNavigationItem[]) => PhiBuilderNavigationItem;
+};
+/**
+ * A catalog folder dropped onto a Navigation: a container named after the folder, holding what the
+ * folder holds -- Pages as links, sub-folders as nested containers. A folder has no route of its own,
+ * which is exactly what a container is. Returns null when nothing beneath it can be linked.
+ */
+export declare function buildPhiBuilderNavigationContainerFromCatalogFolder(folder: PhiPresetPageNode, factory: PhiBuilderCatalogNavigationFactory): Promise<PhiBuilderNavigationItem | null>;

package/plugins/runtime-modules/builder/navigation-folder-drop.js

@@ -0,0 +1,54 @@
+/** A Page the Navigation can point at: it has a stable reference and has not been deleted. */
+export function isPhiBuilderNavigablePage(node) {
+    return Boolean(node.reference) && node.tombstoned !== true;
+}
+/** Whether a catalog node would give the Navigation anything: a live Page, or one somewhere beneath it. */
+export function hasPhiBuilderNavigableContent(node) {
+    return isPhiBuilderNavigablePage(node) || (node.children ?? []).some(hasPhiBuilderNavigableContent);
+}
+export function findPhiBuilderCatalogNode(nodes, key) {
+    for (const node of nodes) {
+        if (node.key === key)
+            return node;
+        const nested = findPhiBuilderCatalogNode(node.children ?? [], key);
+        if (nested)
+            return nested;
+    }
+    return null;
+}
+async function buildItems(nodes, factory) {
+    const items = [];
+    for (const node of nodes) {
+        items.push(...await buildNodeItems(node, factory));
+    }
+    return items;
+}
+async function buildNodeItems(node, factory) {
+    if (!hasPhiBuilderNavigableContent(node))
+        return [];
+    const children = node.children ?? [];
+    if (isPhiBuilderNavigablePage(node)) {
+        /*
+         * A Page is never a folder, so a Page is always a link. A catalog written before that rule may still
+         * hang Pages beneath one; they are not dropped, they follow it as siblings.
+         */
+        const item = factory.createPageItem(await factory.allocateId(), node);
+        return [...(item ? [item] : []), ...await buildItems(children, factory)];
+    }
+    if (node.reference) {
+        // A deleted Page is not carried over; what lives beneath it still is, one level up.
+        return buildItems(children, factory);
+    }
+    const containerId = await factory.allocateId();
+    return [factory.createContainerItem(containerId, node.title, await buildItems(children, factory))];
+}
+/**
+ * A catalog folder dropped onto a Navigation: a container named after the folder, holding what the
+ * folder holds -- Pages as links, sub-folders as nested containers. A folder has no route of its own,
+ * which is exactly what a container is. Returns null when nothing beneath it can be linked.
+ */
+export async function buildPhiBuilderNavigationContainerFromCatalogFolder(folder, factory) {
+    if (folder.reference)
+        return null;
+    return (await buildNodeItems(folder, factory))[0] ?? null;
+}

package/plugins/runtime-modules/builder/navigation-path-context.d.ts

@@ -0,0 +1,25 @@
+import type { PhiBuilderNavigationItem } from "../../../helpers/cms-navigation-catalog";
+import { type PhiPresetPageNode } from "../../../helpers/cms-page-catalog";
+import type { PhiDeveloperBuilderWorkspaceState } from "./developer-workspace-types";
+type NavigationPageTarget = {
+    /** What the table shows, with the Area prefix the Builder addresses the Page by. */
+    path: string;
+    /** Area-relative, package namespace included: the form a folder address takes. */
+    address: string;
+    deleted: boolean;
+};
+/**
+ * The page catalog as the Navigation table needs it: each Page's shown path and address, the choices a
+ * Site page link offers, and how a link resolves to the path a folder address is built from.
+ */
+export declare function createPhiBuilderNavigationPathContext(state: Pick<PhiDeveloperBuilderWorkspaceState, "area" | "modulePresetPagesByArea" | "customPages" | "persistedPageCatalogByArea">): {
+    pages: PhiPresetPageNode[];
+    pagePaths: Map<string, NavigationPageTarget>;
+    pageOptions: {
+        value: import("../../../references").PhiPageReference;
+        label: string;
+    }[];
+    resolveLinkPath: (item: PhiBuilderNavigationItem) => string | null;
+    displayAddress: (address: string) => string;
+};
+export {};

package/plugins/runtime-modules/builder/navigation-path-context.js

@@ -0,0 +1,34 @@
+import { normalizePhiBuilderCmsCatalogPath, resolvePhiBuilderActivePageCatalog, } from "../../../helpers/cms-page-catalog";
+import { resolvePhiBuilderCmsStoragePath, resolvePhiBuilderNavigationTargetPath } from "../../../helpers/cms-paths";
+function flattenPages(pages) {
+    return pages.flatMap((page) => [page, ...flattenPages(page.children ?? [])]);
+}
+/**
+ * The page catalog as the Navigation table needs it: each Page's shown path and address, the choices a
+ * Site page link offers, and how a link resolves to the path a folder address is built from.
+ */
+export function createPhiBuilderNavigationPathContext(state) {
+    const pages = resolvePhiBuilderActivePageCatalog(state.area, state.modulePresetPagesByArea, state.customPages, state.persistedPageCatalogByArea);
+    const referenced = flattenPages(pages).filter((page) => page.reference);
+    const pagePaths = new Map(referenced.map((page) => [page.reference, {
+            path: resolvePhiBuilderNavigationTargetPath(state.area, page.key, pages),
+            address: normalizePhiBuilderCmsCatalogPath(resolvePhiBuilderCmsStoragePath(state.area, page.key, pages)),
+            deleted: page.tombstoned === true,
+        }]));
+    const pageOptions = referenced
+        .filter((page) => page.tombstoned !== true)
+        .map((page) => ({ value: page.reference, label: pagePaths.get(page.reference).path }));
+    const resolveLinkPath = (item) => {
+        if (item.kind !== "link" || item.external === true)
+            return null;
+        if (item.targetReference) {
+            const target = pagePaths.get(item.targetReference);
+            return target && !target.deleted ? target.address : null;
+        }
+        // A Module link's target path is its route path: Area-relative, package namespace included.
+        return item.href;
+    };
+    // Folder addresses are Area-relative; the table shows them with the same prefix as a page link's path.
+    const displayAddress = (address) => state.area === "public" ? `/public${address}` : `/${state.area}${address}`;
+    return { pages, pagePaths, pageOptions, resolveLinkPath, displayAddress };
+}

package/plugins/runtime-modules/builder/navigation-persistence.d.ts

@@ -0,0 +1,44 @@
+import { type PhiBuilderNavigationItem, type PhiBuilderNavigationTree } from "../../../helpers/cms-navigation-catalog";
+import type { PhiCmsNavigationFolderTarget, PhiCmsNavigationOverlay, PhiCmsResolvedNavigationSurface } from "../../../types/cms-module-descriptors";
+export declare function loadPhiBuilderNavigationDraft(navKey: string, descriptorSurface: PhiCmsResolvedNavigationSurface): Promise<{
+    revisionId: number | null;
+    navigation: {
+        draftAllocation: {
+            revisionId: number;
+            nextNodeSequence: number;
+        };
+        key: string;
+        label: string | null;
+        items: PhiBuilderNavigationItem[];
+        descriptorSurface: PhiCmsResolvedNavigationSurface;
+        diagnostics: readonly string[];
+    };
+} | null>;
+export declare function loadPhiBuilderNavigationScope(navKey: string, descriptorSurface: PhiCmsResolvedNavigationSurface): Promise<{
+    draftRevisionId: number | null;
+    navigation: PhiBuilderNavigationTree;
+}>;
+export declare function buildPhiBuilderNavigationOverlay(navigation: PhiBuilderNavigationTree): PhiCmsNavigationOverlay;
+export declare function savePhiBuilderNavigationDraft(navigation: PhiBuilderNavigationTree): Promise<{
+    key: string;
+    revisionId: number;
+    nextNodeSequence: number;
+    carriedOver: PhiBuilderNavigationFolderCarry[];
+}>;
+export type PhiBuilderNavigationFolderCarry = {
+    key: string;
+    revisionId: number;
+    nextNodeSequence: number;
+    folders: {
+        address: string;
+        target: PhiCmsNavigationFolderTarget | null;
+    }[];
+};
+export declare function publishPhiBuilderNavigationDraft(navigation: PhiBuilderNavigationTree, revisionId?: number | null): Promise<{
+    key: string;
+    revisionId: number;
+    carriedOver: PhiBuilderNavigationFolderCarry[];
+}>;
+export declare function deletePhiBuilderNavigationDraft(navKey: string): Promise<{
+    key: string;
+}>;

package/plugins/runtime-modules/builder/navigation-persistence.js

@@ -0,0 +1,253 @@
+"use client";
+import { materializePhiBuilderNavigationSurface, requirePhiBuilderNavigationScopeKey, } from "../../../helpers/cms-navigation-catalog";
+async function readJson(response) {
+    return (await response.json().catch(() => null));
+}
+async function fetchNavigation(url, init) {
+    const response = await fetch(url, { cache: "no-store", ...init });
+    const body = (await readJson(response));
+    if (response.status === 404) {
+        return null;
+    }
+    if (!response.ok) {
+        throw new Error(body?.error ?? `Navigation request failed (${response.status}).`);
+    }
+    return body;
+}
+async function loadPhiBuilderNavigationOverlay(navKey, kind) {
+    const normalized = requirePhiBuilderNavigationScopeKey(navKey);
+    const suffix = kind === "draft" ? "/draft" : "";
+    const payload = await fetchNavigation(`/api/site/cms/navigation${suffix}?key=${encodeURIComponent(normalized)}`);
+    if (!payload?.overlay) {
+        return null;
+    }
+    return {
+        revisionId: Number.isInteger(payload.revisionId) ? payload.revisionId : null,
+        nextNodeSequence: Number.isInteger(payload.nextNodeSequence) ? payload.nextNodeSequence : null,
+        overlay: payload.overlay,
+    };
+}
+export async function loadPhiBuilderNavigationDraft(navKey, descriptorSurface) {
+    const draft = await loadPhiBuilderNavigationOverlay(navKey, "draft");
+    if (draft && draft.revisionId == null) {
+        throw new Error("Navigation draft response is missing its revision id.");
+    }
+    if (draft && (draft.nextNodeSequence == null || draft.nextNodeSequence < 1)) {
+        throw new Error("Navigation draft response is missing its next node sequence.");
+    }
+    return draft
+        ? {
+            revisionId: draft.revisionId,
+            navigation: {
+                ...materializePhiBuilderNavigationSurface(descriptorSurface, draft.overlay),
+                draftAllocation: {
+                    revisionId: draft.revisionId,
+                    nextNodeSequence: draft.nextNodeSequence,
+                },
+            },
+        }
+        : null;
+}
+export async function loadPhiBuilderNavigationScope(navKey, descriptorSurface) {
+    const draft = await loadPhiBuilderNavigationDraft(navKey, descriptorSurface);
+    if (draft) {
+        return {
+            draftRevisionId: draft.revisionId,
+            navigation: draft.navigation,
+        };
+    }
+    const published = await loadPhiBuilderNavigationOverlay(navKey, "published");
+    return {
+        draftRevisionId: null,
+        navigation: materializePhiBuilderNavigationSurface(descriptorSurface, published?.overlay ?? null),
+    };
+}
+function collectItemPositions(items, parentId, target = new Map()) {
+    items.forEach((item, index) => {
+        if (target.has(item.id)) {
+            throw new Error(`Navigation contains duplicate item id "${item.id}".`);
+        }
+        target.set(item.id, {
+            item,
+            parentId,
+            index,
+        });
+        collectItemPositions(item.children, item.id, target);
+    });
+    return target;
+}
+export function buildPhiBuilderNavigationOverlay(navigation) {
+    const base = materializePhiBuilderNavigationSurface(navigation.descriptorSurface, null);
+    const baseByKey = collectItemPositions(base.items, null);
+    const currentByKey = collectItemPositions(navigation.items, null);
+    for (const [id, current] of currentByKey) {
+        if (!baseByKey.has(id) && current.item.source !== "custom") {
+            throw new Error(`Navigation item "${id}" is not owned by an active module.`);
+        }
+        if (baseByKey.has(id) && current.item.source !== "module") {
+            throw new Error(`Navigation custom item "${id}" conflicts with an active module item.`);
+        }
+    }
+    const tombstones = [...baseByKey.keys()].filter((itemKey) => {
+        const current = currentByKey.get(itemKey);
+        return !current || current.item.hidden;
+    });
+    const itemOverrides = [];
+    const customItems = [];
+    const buildPlacement = (current) => ({
+        parentId: current.parentId,
+        index: current.index,
+    });
+    for (const [id, current] of currentByKey) {
+        const baseline = baseByKey.get(id);
+        if (!baseline) {
+            if (current.item.source !== "custom") {
+                continue;
+            }
+            if (current.item.hidden) {
+                throw new Error(`Navigation custom item "${id}" cannot be tombstoned.`);
+            }
+            customItems.push({
+                id: current.item.id,
+                kind: current.item.kind,
+                label: current.item.label,
+                ...(current.item.icon !== undefined ? { icon: current.item.icon } : {}),
+                ...(current.item.kind === "link" && current.item.external === true && current.item.href
+                    ? { target: { kind: "external", href: current.item.href } }
+                    : current.item.kind === "link" && current.item.targetReference
+                        ? { target: { kind: "page", reference: current.item.targetReference } }
+                        : {}),
+                ...(current.item.newTab === true ? { newTab: true } : {}),
+                placement: buildPlacement(current),
+                ...(current.item.kind === "container" && current.item.folder ? { folder: current.item.folder } : {}),
+            });
+            continue;
+        }
+        const override = { id: current.item.id };
+        if (current.item.label !== baseline.item.label) {
+            override.label = current.item.label;
+        }
+        if ((current.item.icon ?? null) !== (baseline.item.icon ?? null)) {
+            override.icon = current.item.icon ?? null;
+        }
+        if (current.parentId !== baseline.parentId ||
+            current.index !== baseline.index) {
+            override.placement = {
+                ...buildPlacement(current),
+            };
+        }
+        // A Module container's folder is Site-authored; its descriptor never declares one.
+        if (current.item.kind === "container" && current.item.folder) {
+            override.folder = current.item.folder;
+        }
+        if (override.label !== undefined || override.icon !== undefined || override.placement || override.folder) {
+            itemOverrides.push(override);
+        }
+    }
+    return {
+        navKey: requirePhiBuilderNavigationScopeKey(navigation.key),
+        ...(navigation.label && navigation.label !== base.label ? { label: navigation.label } : {}),
+        itemOverrides,
+        customItems,
+        tombstones,
+    };
+}
+export async function savePhiBuilderNavigationDraft(navigation) {
+    const normalizedKey = requirePhiBuilderNavigationScopeKey(navigation.key);
+    const persistedDraft = await loadPhiBuilderNavigationOverlay(normalizedKey, "draft");
+    const source = persistedDraft ?? await loadPhiBuilderNavigationOverlay(normalizedKey, "published");
+    const requestedNextNodeSequence = Math.max(navigation.draftAllocation?.nextNodeSequence ?? 1, source?.nextNodeSequence ?? 1);
+    const response = await fetch("/api/site/cms/navigation", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            key: normalizedKey,
+            overlay: buildPhiBuilderNavigationOverlay(navigation),
+            nextNodeSequence: requestedNextNodeSequence,
+            // What this state was loaded from, so a folder target carried in since is not taken for a change.
+            baseRevisionId: navigation.draftAllocation?.revisionId ?? null,
+        }),
+    });
+    const body = (await readJson(response));
+    if (!response.ok) {
+        throw new Error(body?.error ?? `Failed to save navigation draft (${response.status}).`);
+    }
+    const revisionId = Number.isInteger(body?.revisionId) ? body?.revisionId : null;
+    if (revisionId == null || revisionId <= 0) {
+        throw new Error("Navigation draft save did not return a revision.");
+    }
+    const nextNodeSequence = Number.isInteger(body?.nextNodeSequence)
+        ? body?.nextNodeSequence
+        : null;
+    if (nextNodeSequence == null || nextNodeSequence < 1) {
+        throw new Error("Navigation draft save did not return its next node sequence.");
+    }
+    return { key: normalizedKey, revisionId, nextNodeSequence, carriedOver: readPhiBuilderNavigationCarriedOver(body) };
+}
+/**
+ * The other Navigations a save carried a folder target into. A generic reader of a server answer: an
+ * entry that does not read is dropped, since the save itself succeeded either way.
+ */
+function readPhiBuilderNavigationCarriedOver(body) {
+    const entries = body && typeof body === "object" ? body.carriedOver : null;
+    if (!Array.isArray(entries))
+        return [];
+    return entries.flatMap((entry) => {
+        if (!entry || typeof entry !== "object")
+            return [];
+        const record = entry;
+        if (typeof record.key !== "string" || !Number.isInteger(record.revisionId) ||
+            !Number.isInteger(record.nextNodeSequence) || !Array.isArray(record.folders))
+            return [];
+        const folders = record.folders.flatMap((folder) => {
+            if (!folder || typeof folder !== "object")
+                return [];
+            const { address, target } = folder;
+            if (typeof address !== "string")
+                return [];
+            if (target === null)
+                return [{ address, target: null }];
+            const candidate = target;
+            if (candidate?.kind === "page" && typeof candidate.reference === "string") {
+                return [{ address, target: { kind: "page", reference: candidate.reference } }];
+            }
+            if (candidate?.kind === "folder" && typeof candidate.address === "string") {
+                return [{ address, target: { kind: "folder", address: candidate.address } }];
+            }
+            return [];
+        });
+        return [{ key: record.key, revisionId: record.revisionId, nextNodeSequence: record.nextNodeSequence, folders }];
+    });
+}
+export async function publishPhiBuilderNavigationDraft(navigation, revisionId) {
+    const normalizedKey = requirePhiBuilderNavigationScopeKey(navigation.key);
+    const saved = revisionId != null && Number.isInteger(revisionId) && revisionId > 0
+        ? null
+        : await savePhiBuilderNavigationDraft(navigation);
+    const savedRevisionId = saved?.revisionId ?? revisionId;
+    const response = await fetch("/api/site/cms/navigation/publish", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ key: normalizedKey, revisionId: savedRevisionId }),
+    });
+    const body = (await readJson(response));
+    if (!response.ok) {
+        throw new Error(body?.error ?? `Failed to publish navigation draft (${response.status}).`);
+    }
+    const publishedRevisionId = Number.isInteger(body?.revisionId) ? body?.revisionId : null;
+    if (publishedRevisionId == null || publishedRevisionId <= 0) {
+        throw new Error("Navigation publish did not return a revision.");
+    }
+    return { key: normalizedKey, revisionId: publishedRevisionId, carriedOver: saved?.carriedOver ?? [] };
+}
+export async function deletePhiBuilderNavigationDraft(navKey) {
+    const normalized = requirePhiBuilderNavigationScopeKey(navKey);
+    const response = await fetch(`/api/site/cms/navigation?key=${encodeURIComponent(normalized)}`, {
+        method: "DELETE",
+    });
+    const body = (await readJson(response));
+    if (!response.ok) {
+        throw new Error(body?.error ?? `Failed to reset navigation draft (${response.status}).`);
+    }
+    return { key: normalized };
+}

package/plugins/runtime-modules/builder/navigation-signals.d.ts

@@ -0,0 +1,36 @@
+import type { PhiSignal } from "../../../types";
+import type { PhiSignalDispatch } from "../../../components/runtime/runtime-signal-bus";
+import type { PhiBuilderPageCatalogArea } from "../../../helpers/cms-page-catalog";
+export type PhiBuilderNavigationDragEventValue = {
+    area?: PhiBuilderPageCatalogArea;
+    navKey?: string;
+    dragType: string;
+    sourceKey: string;
+    targetKey?: string | null;
+    dropMode?: "before" | "after" | "child" | "append" | null;
+    accepted?: boolean | null;
+};
+export type PhiBuilderNavigationDragStateValue = {
+    area: PhiBuilderPageCatalogArea;
+    navKey: string;
+    dragging: boolean;
+};
+export declare function resolvePhiBuilderNavigationDragEvent(signal: PhiSignal): PhiBuilderNavigationDragEventValue | null;
+export declare function resolvePhiBuilderNavigationDragging(signal: PhiSignal): boolean | null;
+export declare function emitPhiBuilderNavigationDragStateSignal(input: {
+    emitSignal: PhiSignalDispatch;
+    area: PhiBuilderPageCatalogArea;
+    navKey: string;
+    dragging: boolean;
+    sourceObjectKey: string;
+    targetObjectKey?: string | null;
+}): void;
+export declare function emitPhiBuilderNavigationDragEventSignal(input: {
+    emitSignal: PhiSignalDispatch;
+    kind: "drag" | "drop";
+    area: PhiBuilderPageCatalogArea;
+    navKey: string;
+    sourceObjectKey: string;
+    targetObjectKey?: string | null;
+    value: PhiBuilderNavigationDragEventValue;
+}): void;