@drawnagency/primitives 0.1.96 → 0.1.97

package/src/hooks/useSortableNavRow.ts

@@ -0,0 +1,139 @@
+import { useEffect, useRef, useState } from "react";
+import { computeNavDropTarget } from "../lib/reorder";
+import type { NavLocation, NavRow } from "../lib/nav-tree";
+
+interface Options {
+  /** This row's identity — supplies the source location and the drop container. */
+  row: NavRow;
+  /** The row's index in the TOP-LEVEL entry list (a member row: its group's index). */
+  entryIndex: number;
+  kind: "page" | "group";
+  onMove: (from: NavLocation, to: NavLocation) => void;
+  enabled?: boolean;
+}
+
+const DRAG_TYPE = "nav-tree-row";
+
+/**
+ * Closest-edge drag wiring for one Pages-modal nav row. A sibling of
+ * useSortableRow that speaks NavLocation instead of a flat index; the section
+ * modal keeps using the original, so this cannot regress it.
+ *
+ * Loads the atlaskit adapter lazily, matching useSortableRow, so it stays out
+ * of the SSR and initial bundles.
+ */
+export function useSortableNavRow<R extends HTMLElement, H extends HTMLElement>({
+  row, entryIndex, kind, onMove, enabled = true,
+}: Options) {
+  const rowRef = useRef<R>(null);
+  const handleRef = useRef<H>(null);
+  const [isDragging, setIsDragging] = useState(false);
+  const [closestEdge, setClosestEdge] = useState<"top" | "bottom" | null>(null);
+  const [isDropTarget, setIsDropTarget] = useState(false);
+
+  // Read through a ref so the atlaskit effect doesn't re-subscribe every render.
+  const latest = useRef({ row, entryIndex, kind, onMove });
+  latest.current = { row, entryIndex, kind, onMove };
+
+  // MUST be a pure helper reading from `latest.current`, never a render-scope
+  // closure. The effect deliberately does not re-subscribe when the row's
+  // position changes, so a closure captured at mount would make every drag
+  // AFTER the first reorder report a stale `from` — and moveNavEntry would
+  // splice the wrong slot. Silent wrong-item moves, no error anywhere.
+  // (`useSortableRow` avoids this by re-subscribing on `[index, …]`; this hook
+  // cannot, because its identity is a NavLocation rather than a single number.)
+  const locationOf = (r: NavRow, ei: number): NavLocation =>
+    r.kind === "group"
+      ? { groupId: null, index: ei }
+      : r.kind === "page"
+        ? { groupId: r.groupId, index: r.index }
+        : r.kind === "empty-group"
+          ? { groupId: r.groupId, index: 0 }
+          : { groupId: null, index: ei };
+
+  useEffect(() => {
+    if (!enabled) return;
+    const element = rowRef.current;
+    const handle = handleRef.current;
+    if (!element) return;
+    // Only draggable rows need a handle; empty-group and tail rows are drop-only.
+    const dropOnly = row.kind === "empty-group" || row.kind === "tail";
+    if (!dropOnly && !handle) return;
+
+    let cleanup: (() => void) | undefined;
+    let cancelled = false;
+
+    Promise.all([
+      import("@atlaskit/pragmatic-drag-and-drop/element/adapter"),
+      import("@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge"),
+    ]).then(([{ draggable, dropTargetForElements }, { attachClosestEdge, extractClosestEdge }]) => {
+      if (cancelled) return;
+      const cleanups: (() => void)[] = [];
+
+      if (!dropOnly && handle) {
+        cleanups.push(draggable({
+          element, dragHandle: handle,
+          getInitialData: () => ({
+            dragType: DRAG_TYPE,
+            kind,
+            from: locationOf(latest.current.row, latest.current.entryIndex),
+          }),
+          onGenerateDragPreview: () => {
+            element.style.opacity = "0.4";
+            requestAnimationFrame(() => { element.style.opacity = ""; });
+          },
+          onDragStart: () => setIsDragging(true),
+          onDrop: () => setIsDragging(false),
+        }));
+      }
+
+      const resolve = (source: Record<string, unknown>, edge: "top" | "bottom" | null) =>
+        computeNavDropTarget({
+          from: source.from as NavLocation,
+          fromKind: source.kind as "page" | "group",
+          over: latest.current.row,
+          overEntryIndex: latest.current.entryIndex,
+          edge,
+        });
+
+      cleanups.push(dropTargetForElements({
+        element,
+        canDrop: ({ source }) => source.data.dragType === DRAG_TYPE,
+        getData: ({ input, element: el }) =>
+          attachClosestEdge({}, { input, element: el, allowedEdges: ["top", "bottom"] }),
+        onDragEnter: ({ self, source }) => {
+          const raw = extractClosestEdge(self.data);
+          const edge = raw === "top" || raw === "bottom" ? raw : null;
+          // Show an indicator only where the drop would actually land, so a
+          // rejected target reads as inert rather than as a silent failure.
+          const target = resolve(source.data, edge);
+          setClosestEdge(target ? edge : null);
+          setIsDropTarget(!!target);
+        },
+        onDrag: ({ self, source }) => {
+          const raw = extractClosestEdge(self.data);
+          const edge = raw === "top" || raw === "bottom" ? raw : null;
+          const target = resolve(source.data, edge);
+          setClosestEdge(target ? edge : null);
+          setIsDropTarget(!!target);
+        },
+        onDragLeave: () => { setClosestEdge(null); setIsDropTarget(false); },
+        onDrop: ({ self, source }) => {
+          setClosestEdge(null);
+          setIsDropTarget(false);
+          const raw = extractClosestEdge(self.data);
+          const edge = raw === "top" || raw === "bottom" ? raw : null;
+          const target = resolve(source.data, edge);
+          if (target) latest.current.onMove(source.data.from as NavLocation, target);
+        },
+      }));
+
+      cleanup = () => cleanups.forEach((c) => c());
+    });
+
+    return () => { cancelled = true; cleanup?.(); };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, row.kind, kind]);
+
+  return { rowRef, handleRef, isDragging, closestEdge, isDropTarget };
+}

package/src/lib/dexie.ts

@@ -1,6 +1,7 @@
 import Dexie from "dexie";
 import type { SectionContent } from "../schemas/sections";
 import type { SiteIndex, SectionMeta, SiteConfig, Page } from "../schemas/site-config";
+import type { NavEntry } from "../schemas/nav";
 import type { LoadedSection } from "./loader";
 import type { MediaManifest, MediaItem } from "../media/types";
 
@@ -15,6 +16,8 @@ interface SiteIndexRow {
   key: string;
   pages: Page[];
   sections: Record<string, SectionMeta>;
+  /** Optional: rows written before page groups shipped have no nav. */
+  nav?: NavEntry[];
   deletedSections: string[];
   updatedAt: string;
 }
@@ -237,7 +240,7 @@ export async function restoreLocalChanges(): Promise<{
     const siteId = metaRow?.siteId ?? "";
     return {
       sections,
-      siteIndex: { siteId, pages: indexRow.pages, sections: indexRow.sections },
+      siteIndex: { siteId, pages: indexRow.pages, sections: indexRow.sections, nav: indexRow.nav },
       siteConfig: configRow?.config,
       deletedSections: indexRow.deletedSections ?? [],
     };
@@ -266,6 +269,7 @@ export async function persistSiteIndex(index: SiteIndex, deletedSections: string
       key: "current",
       pages: index.pages,
       sections: index.sections,
+      nav: index.nav,
       deletedSections,
       updatedAt: now,
     });
@@ -389,6 +393,7 @@ export async function persistAll(
           key: "current",
           pages: siteIndex.pages,
           sections: siteIndex.sections,
+          nav: siteIndex.nav,
           deletedSections: [],
           updatedAt: now,
         });

package/src/lib/index.ts

@@ -3,6 +3,7 @@ export { cn } from "./cn";
 export { audiencePasses } from "./pages";
 export { resolveChatbotName, resolveThinkingPhrases, DEFAULT_CHATBOT_NAME } from "./chatbot";
 export { generateNavLinks, toSectionId, type NavItem } from "./nav";
+export { navEntries, pagesInNavOrder, groupOfPage, groupDisplayLabel, reconcileNav } from "./nav-tree";
 export {
   deriveContrast,
   contrastColor,

package/src/lib/loader.ts

@@ -3,6 +3,7 @@ import { IndexSchema, type SiteIndex, type SectionMeta } from "../schemas/site-c
 import { getAllSchemas } from "./registry";
 import { blockDepth, MAX_BLOCK_DEPTH } from "../schemas/block";
 import { upgradeLegacySection } from "./migrate-sections-transform";
+import { NavFileSchema, type NavEntry } from "../schemas/nav";
 
 export interface LoadedSection {
   section: Section;
@@ -14,6 +15,21 @@ export interface SiteContent {
   index: SiteIndex;
 }
 
+/**
+ * Parse the nav.json sidecar defensively. A malformed sidecar must degrade to a
+ * flat nav, never brick the site — nav.json is optional content, and the whole
+ * point of the sidecar is that it tolerates writers that don't understand it.
+ */
+function parseNavFile(navFile: unknown): NavEntry[] {
+  if (!navFile) return [];
+  const result = NavFileSchema.safeParse(navFile);
+  if (!result.success) {
+    console.warn("Invalid nav.json, falling back to a flat navigation");
+    return [];
+  }
+  return result.data.entries;
+}
+
 /**
  * Merge a validated index with raw section file contents.
  * Validates each section file against its Zod schema.
@@ -21,7 +37,8 @@ export interface SiteContent {
  */
 export function mergeSiteContent(
   index: SiteIndex,
-  sectionFiles: Record<string, unknown>
+  sectionFiles: Record<string, unknown>,
+  navFile?: unknown,
 ): SiteContent {
   const sections: LoadedSection[] = [];
 
@@ -66,7 +83,7 @@ export function mergeSiteContent(
     }
   }
 
-  return { sections, index };
+  return { sections, index: { ...index, nav: parseNavFile(navFile) } };
 }
 
 /**
@@ -77,6 +94,7 @@ export function mergeSiteContent(
 export function loadStaticSiteContent(
   index: SiteIndex,
   sectionGlob: Record<string, unknown>,
+  navFile?: unknown,
 ): SiteContent {
   const sectionFiles: Record<string, unknown> = {};
   for (const [path, data] of Object.entries(sectionGlob)) {
@@ -84,7 +102,7 @@ export function loadStaticSiteContent(
     const id = filename.replace(".json", "");
     sectionFiles[id] = data;
   }
-  return mergeSiteContent(index, sectionFiles);
+  return mergeSiteContent(index, sectionFiles, navFile);
 }
 
 /**
@@ -105,5 +123,14 @@ export async function loadSiteContent(contentDir: string): Promise<SiteContent>
     sectionFiles[id] = JSON.parse(await fs.readFile(sectionPath, "utf-8"));
   }
 
-  return mergeSiteContent(index, sectionFiles);
+  // nav.json is an optional sidecar — absent (every portal predating page
+  // groups) or unreadable must degrade to a flat nav, never fail the load.
+  let navFile: unknown;
+  try {
+    navFile = JSON.parse(await fs.readFile(path.join(contentDir, "nav.json"), "utf-8"));
+  } catch {
+    navFile = undefined;
+  }
+
+  return mergeSiteContent(index, sectionFiles, navFile);
 }

package/src/lib/nav-tree.ts

@@ -0,0 +1,192 @@
+import type { NavEntry, NavGroupEntry } from "../schemas/nav";
+import type { Page, SiteIndex } from "../schemas/site-config";
+
+/**
+ * Repair an authored nav against the current page set.
+ *
+ * Total, pure, and idempotent: every possible input maps to a valid nav in
+ * which each page appears exactly once. This is what lets the sidecar tolerate
+ * an older writer editing index.json without knowing about nav.json — the worst
+ * case is a page drifting to the bottom of the nav, never a hard failure. It is
+ * deliberately NOT a schema refinement: parse-rejecting content leaves viewer
+ * and editor both refusing to load, with no in-product repair path.
+ *
+ * "Total" is meant literally, so the shape guards below are load-bearing rather
+ * than paranoia: callers include agent-authored JSON and live editor state, and
+ * `pages` is not id-unique (IndexSchema checks slug uniqueness, not page ids).
+ * Every entry is cloned on the way out — the editor holds this in React state,
+ * where a returned-by-reference entry would let a later mutation silently edit
+ * prior state and defeat identity-based re-render checks.
+ */
+export function reconcileNav(entries: NavEntry[], pages: Page[]): NavEntry[] {
+  const entryList = Array.isArray(entries) ? entries : [];
+  const pageList = Array.isArray(pages) ? pages : [];
+
+  const validIds = new Set<string>();
+  for (const p of pageList) {
+    if (p?.id) validIds.add(p.id);
+  }
+
+  const placed = new Set<string>();
+  const seenGroupIds = new Set<string>();
+  const result: NavEntry[] = [];
+
+  for (const entry of entryList) {
+    if (entry?.kind === "page") {
+      if (!validIds.has(entry.pageId) || placed.has(entry.pageId)) continue;
+      placed.add(entry.pageId);
+      result.push({ ...entry });
+      continue;
+    }
+
+    if (entry?.kind !== "group") continue;
+    if (seenGroupIds.has(entry.id)) continue;
+    seenGroupIds.add(entry.id);
+
+    const claimed = Array.isArray(entry.pageIds) ? entry.pageIds : [];
+    const pageIds = claimed.filter((id) => {
+      if (!validIds.has(id) || placed.has(id)) return false;
+      placed.add(id);
+      return true;
+    });
+    const group: NavGroupEntry = { ...entry, pageIds };
+    result.push(group);
+  }
+
+  for (const p of pageList) {
+    if (!p?.id || placed.has(p.id)) continue;
+    placed.add(p.id);
+    result.push({ kind: "page", pageId: p.id });
+  }
+
+  return result;
+}
+
+/**
+ * The ONLY sanctioned way to read the nav. Always reconciles, so callers never
+ * have to reason about whether index.nav is present, stale, or authored by an
+ * older writer. Cheap and idempotent — call it freely.
+ */
+export function navEntries(index: SiteIndex): NavEntry[] {
+  return reconcileNav(index.nav ?? [], index.pages);
+}
+
+/** Pages in authored nav order. Use this anywhere user-visible sequence matters. */
+export function pagesInNavOrder(index: SiteIndex): Page[] {
+  const byId = new Map(index.pages.map((p) => [p.id, p]));
+  const out: Page[] = [];
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "page") {
+      const p = byId.get(entry.pageId);
+      if (p) out.push(p);
+    } else {
+      for (const id of entry.pageIds) {
+        const p = byId.get(id);
+        if (p) out.push(p);
+      }
+    }
+  }
+  return out;
+}
+
+export function groupOfPage(index: SiteIndex, pageId: string): NavGroupEntry | null {
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "group" && entry.pageIds.includes(pageId)) return entry;
+  }
+  return null;
+}
+
+/** Display fallback for blank group labels — mirrors pageDisplayTitle in lib/pages.ts. */
+export function groupDisplayLabel(label: string): string {
+  return label || "Untitled group";
+}
+
+/** A position in the nav: inside a group, or at the top level when groupId is null. */
+export interface NavLocation {
+  groupId: string | null;
+  index: number;
+}
+
+export type NavRow =
+  | { kind: "page"; pageId: string; groupId: string | null; index: number }
+  | { kind: "group"; groupId: string; index: number }
+  | { kind: "empty-group"; groupId: string }
+  // The trailing drop target. Without it a page can never land AFTER a group
+  // that sits last in the nav: the group's header-bottom edge and every member
+  // edge all resolve to positions INSIDE it.
+  | { kind: "tail" };
+
+function withNav(index: SiteIndex, entries: NavEntry[]): SiteIndex {
+  return { ...index, nav: entries };
+}
+
+export function addGroup(index: SiteIndex, groupId: string): SiteIndex {
+  return withNav(index, [
+    ...navEntries(index),
+    { kind: "group", id: groupId, label: "", startCollapsed: false, pageIds: [] },
+  ]);
+}
+
+export function renameGroup(index: SiteIndex, groupId: string, label: string): SiteIndex {
+  return withNav(index, navEntries(index).map((e) =>
+    e.kind === "group" && e.id === groupId ? { ...e, label } : e,
+  ));
+}
+
+export function setGroupStartCollapsed(index: SiteIndex, groupId: string, startCollapsed: boolean): SiteIndex {
+  return withNav(index, navEntries(index).map((e) =>
+    e.kind === "group" && e.id === groupId ? { ...e, startCollapsed } : e,
+  ));
+}
+
+/** Removes the group; its members become top-level entries at the group's slot. */
+export function deleteGroup(index: SiteIndex, groupId: string): SiteIndex {
+  const out: NavEntry[] = [];
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "group" && entry.id === groupId) {
+      for (const pageId of entry.pageIds) out.push({ kind: "page", pageId });
+    } else {
+      out.push(entry);
+    }
+  }
+  return withNav(index, out);
+}
+
+/**
+ * The single reorder+reparent primitive. `from` and `to` are both NavLocations,
+ * so moving within a container, between containers, and promoting/demoting a
+ * page are all the same operation.
+ */
+export function moveNavEntry(index: SiteIndex, from: NavLocation, to: NavLocation): SiteIndex {
+  const entries = navEntries(index).map((e) => (e.kind === "group" ? { ...e, pageIds: [...e.pageIds] } : { ...e }));
+
+  // Lift the moved item out of its source container.
+  let moved: NavEntry | string | undefined;
+  if (from.groupId === null) {
+    if (from.index < 0 || from.index >= entries.length) return index;
+    [moved] = entries.splice(from.index, 1);
+  } else {
+    const group = entries.find((e) => e.kind === "group" && e.id === from.groupId);
+    if (!group || group.kind !== "group") return index;
+    if (from.index < 0 || from.index >= group.pageIds.length) return index;
+    [moved] = group.pageIds.splice(from.index, 1);
+  }
+  if (moved === undefined) return index;
+
+  // A group can only ever live at the top level — one level of nesting, enforced.
+  const movedIsGroup = typeof moved !== "string" && moved.kind === "group";
+  if (movedIsGroup && to.groupId !== null) return index;
+
+  if (to.groupId === null) {
+    const entry: NavEntry = typeof moved === "string" ? { kind: "page", pageId: moved } : moved;
+    entries.splice(Math.max(0, Math.min(to.index, entries.length)), 0, entry);
+  } else {
+    const group = entries.find((e) => e.kind === "group" && e.id === to.groupId);
+    if (!group || group.kind !== "group") return index;
+    const pageId = typeof moved === "string" ? moved : moved.kind === "page" ? moved.pageId : null;
+    if (pageId === null) return index;
+    group.pageIds.splice(Math.max(0, Math.min(to.index, group.pageIds.length)), 0, pageId);
+  }
+
+  return withNav(index, entries);
+}

package/src/lib/nav.ts

@@ -1,6 +1,7 @@
 import type { LoadedSection } from "./loader";
 import { getSection, type SectionRegistry } from "./registry";
 import { audiencePasses, homePage, pageDisplayTitle } from "./pages";
+import { navEntries } from "./nav-tree";
 import type { SiteIndex } from "../schemas/site-config";
 
 export interface NavItem {
@@ -93,9 +94,20 @@ export interface PageNavItem {
   headings: NavItem[];
 }
 
-export interface SiteNav {
+export interface GroupNavItem {
+  kind: "group";
+  id: string;
+  label: string;
+  startCollapsed: boolean;
   pages: PageNavItem[];
-  /** Live pages with showInNav off — editor-only group, like the archive. */
+}
+
+export type SiteNavEntry = ({ kind: "page" } & PageNavItem) | GroupNavItem;
+
+export interface SiteNav {
+  /** The authored tree: loose pages and groups, in nav order. */
+  entries: SiteNavEntry[];
+  /** Live pages with showInNav off — editor-only flat bucket, like the archive. */
   hidden: PageNavItem[];
   archive: PageNavItem[];
 }
@@ -114,6 +126,7 @@ export function generateSiteNav(opts: {
 }): SiteNav {
   const { index, activeSections, activePageId, mode, audience, registry } = opts;
   const active = activePageId ?? homePage(index).id;
+  const byId = new Map(index.pages.map((p) => [p.id, p]));
 
   const toNavItem = (p: (typeof index.pages)[number]): PageNavItem => ({
     id: p.id,
@@ -124,19 +137,39 @@ export function generateSiteNav(opts: {
     headings: p.id === active ? generateNavLinks(activeSections, registry) : [],
   });
 
+  // Tree membership: live + shown in nav, and for viewers also audience-passing.
+  // Hidden and archived pages keep their nav slot in the data but render in the
+  // flat editor buckets instead, so a group never appears in two places.
+  const inTree = (p: (typeof index.pages)[number]) =>
+    p.status === "live" && p.showInNav && (mode === "editor" || audiencePasses(p.access, audience));
+
+  const entries: SiteNavEntry[] = [];
+  for (const entry of navEntries(index)) {
+    if (entry.kind === "page") {
+      const p = byId.get(entry.pageId);
+      if (p && inTree(p)) entries.push({ kind: "page", ...toNavItem(p) });
+      continue;
+    }
+    const pages = entry.pageIds
+      .map((id) => byId.get(id))
+      .filter((p): p is NonNullable<typeof p> => !!p && inTree(p))
+      .map(toNavItem);
+    // A group with nothing visible is noise for viewers; editors keep it so an
+    // empty group they just created doesn't disappear out from under them.
+    if (pages.length === 0 && mode === "viewer") continue;
+    entries.push({
+      kind: "group", id: entry.id, label: entry.label,
+      startCollapsed: entry.startCollapsed, pages,
+    });
+  }
+
   if (mode === "editor") {
     return {
-      pages: index.pages.filter((p) => p.status === "live" && p.showInNav).map(toNavItem),
+      entries,
       hidden: index.pages.filter((p) => p.status === "live" && !p.showInNav).map(toNavItem),
       archive: index.pages.filter((p) => p.status === "archived").map(toNavItem),
     };
   }
 
-  return {
-    pages: index.pages
-      .filter((p) => p.status === "live" && p.showInNav && audiencePasses(p.access, audience))
-      .map(toNavItem),
-    hidden: [],
-    archive: [],
-  };
+  return { entries, hidden: [], archive: [] };
 }

package/src/lib/pages.ts

@@ -4,6 +4,7 @@ import { RESERVED_SLUGS } from "../schemas/site-config";
 // is allowed to reach into its engine to write the page-level document options
 // block (mirrors the same sanctioned import in schemas/site-config.ts).
 import { documentOptionsSchema, type DocumentOptions } from "../document/engine/settings";
+import { navEntries } from "./nav-tree";
 
 /**
  * Display fallback for blank page titles. addPage creates pages with an empty
@@ -59,16 +60,11 @@ export function addPage(index: SiteIndex, id: string): SiteIndex {
   const page: Page = {
     id, title: "", slug, isHome: false, showInNav: true, status: "live", access: [], order: [],
   };
-  return { ...index, pages: [...index.pages, page] };
-}
-
-export function reorderPages(index: SiteIndex, fromIndex: number, toIndex: number): SiteIndex {
-  const len = index.pages.length;
-  if (fromIndex < 0 || fromIndex >= len || toIndex < 0 || toIndex >= len) return index;
-  const pages = [...index.pages];
-  const [moved] = pages.splice(fromIndex, 1);
-  pages.splice(toIndex, 0, moved);
-  return { ...index, pages };
+  return {
+    ...index,
+    pages: [...index.pages, page],
+    nav: [...navEntries(index), { kind: "page", pageId: id }],
+  };
 }
 
 export function setHomePage(index: SiteIndex, pageId: string): SiteIndex {
@@ -152,7 +148,14 @@ export function deletePage(
   const nextSections: Record<string, SectionMeta> = { ...index.sections };
   for (const id of removedSectionIds) delete nextSections[id];
   return {
-    index: { ...index, pages: index.pages.filter((p) => p.id !== pageId), sections: nextSections },
+    index: {
+      ...index,
+      pages: index.pages.filter((p) => p.id !== pageId),
+      sections: nextSections,
+      nav: navEntries(index)
+        .filter((e) => !(e.kind === "page" && e.pageId === pageId))
+        .map((e) => (e.kind === "group" ? { ...e, pageIds: e.pageIds.filter((id) => id !== pageId) } : e)),
+    },
     removedSectionIds,
   };
 }

package/src/lib/reorder.ts

@@ -1,3 +1,5 @@
+import type { NavLocation, NavRow } from "./nav-tree";
+
 /**
  * Compute the destination index for a closest-edge drag-to-reorder drop.
  *
@@ -18,3 +20,57 @@ export function computeReorderTarget(
   if (fromIndex < toIndex) toIndex--;
   return fromIndex === toIndex ? null : toIndex;
 }
+
+/**
+ * Resolve a closest-edge drop over a nav row into a destination NavLocation.
+ *
+ * With one level of nesting a target's own identity determines its container,
+ * so page drags need no depth inference. Group drags DO need remapping: a group
+ * can only live at the top level, so hovering a member row is reinterpreted as
+ * "next to that member's group" rather than rejected — otherwise every member
+ * row of every expanded group is an inert dead zone during a group drag.
+ *
+ * `overEntryIndex` is the row's index in the TOP-LEVEL entry list: its own index
+ * for a top-level page or group row, its enclosing group's index for a member
+ * row, and the total entry count for the tail row. Group-drag remapping targets
+ * it directly.
+ *
+ * Returns null when the drop would not move anything, or is not permitted.
+ */
+export function computeNavDropTarget(args: {
+  from: NavLocation;
+  fromKind: "page" | "group";
+  over: NavRow;
+  overEntryIndex: number;
+  edge: "top" | "bottom" | null;
+}): NavLocation | null {
+  const { from, fromKind, over, overEntryIndex, edge } = args;
+  const after = edge === "bottom";
+
+  let to: NavLocation;
+  if (over.kind === "tail") {
+    // A container-level target for both kinds. `overEntryIndex` for the tail row
+    // is the top-level entry count, so this appends. The shared decrement below
+    // makes "drag the last top-level row onto the tail" a correct no-op.
+    to = { groupId: null, index: overEntryIndex };
+  } else if (fromKind === "group") {
+    // Groups are top-level only. Empty-group rows have no top-level meaning here.
+    if (over.kind === "empty-group") return null;
+    to = { groupId: null, index: overEntryIndex + (after ? 1 : 0) };
+  } else if (over.kind === "empty-group") {
+    to = { groupId: over.groupId, index: 0 };
+  } else if (over.kind === "group") {
+    // Top edge = before the group at the top level; bottom edge = first slot
+    // INSIDE it. The header's lower boundary is visually the group's interior.
+    to = after ? { groupId: over.groupId, index: 0 } : { groupId: null, index: overEntryIndex };
+  } else {
+    to = { groupId: over.groupId, index: over.index + (after ? 1 : 0) };
+  }
+
+  // Removing the dragged item before re-inserting shifts later slots in the
+  // SAME container only — mirrors computeReorderTarget's decrement.
+  if (to.groupId === from.groupId && from.index < to.index) to = { ...to, index: to.index - 1 };
+
+  if (to.groupId === from.groupId && to.index === from.index) return null;
+  return to;
+}

package/src/schemas/index.ts

@@ -1,6 +1,7 @@
 export * from "./shared";
 export * from "./sections";
 export * from "./site-config";
+export * from "./nav";
 export * from "./media";
 export * from "./audience";
 export * from "./media-grid-options";