dirvi-lib 0.11.0-beta.6 → 0.11.0-beta.7

package/dist/{trees → state-and-nav}/fold-node/fold-node.types.d.ts

@@ -1,4 +1,4 @@
-import type { SerializableKey } from '../tree-node/index.js';
+import type { SerializableKey } from '../tree/index.js';
 import type { FoldSlotModel, FoldsModel } from './fold-node.model.js';
 declare const foldsBrand: unique symbol;
 /**
@@ -39,7 +39,7 @@ export type Folds<Id extends SerializableKey> = {
         readonly id: Id;
     };
 };
-export type FoldsApi<Id extends SerializableKey> = Readonly<{
+export type FoldMethods<Id extends SerializableKey> = Readonly<{
     /**
      * Creates Folds with its required primary fold tree in slot zero.
      *

package/dist/state-and-nav/fold-node/fold-node.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold-node.types.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/fold-node/fold-node.types.ts"],"names":[],"mappings":"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"}

package/dist/state-and-nav/fold-node/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/fold-node/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC"}

package/dist/state-and-nav/index.d.ts

@@ -0,0 +1,16 @@
+export type { SerializableKey } from './tree/index.js';
+export type { TreeNode } from './tree/index.js';
+export type { Folds } from './fold-node/index.js';
+export type { Cursor } from './cursor.js';
+export type { TreeMethods } from './tree/index.js';
+export { createTreeMethods } from './tree/index.js';
+export type { FoldIndex, FoldMethods } from './fold-node/index.js';
+export { createFoldMethods } from './fold-node/index.js';
+export type { CursorMethods } from './cursor.js';
+export { createCursorMethods } from './cursor.js';
+export type { State, StateApi } from './state/state.types.js';
+export { createStateApi } from './state/state.impl.js';
+export type { NavNode, NavMethods, NavBranch } from './nav/nav.types.js';
+export { createOrderedNavMethods } from './nav/nav.ordered.impl.js';
+export { createUnorderedNavMethods } from './nav/nav.unordered.impl.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/state-and-nav/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state-and-nav/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAIvD,YAAY,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIlD,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACzE,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/state-and-nav/index.js

@@ -0,0 +1,6 @@
+export { createTreeMethods } from './tree/index.js';
+export { createFoldMethods } from './fold-node/index.js';
+export { createCursorMethods } from './cursor.js';
+export { createStateApi } from './state/state.impl.js';
+export { createOrderedNavMethods } from './nav/nav.ordered.impl.js';
+export { createUnorderedNavMethods } from './nav/nav.unordered.impl.js';

package/dist/state-and-nav/nav/nav.ordered.impl.d.ts

@@ -0,0 +1,12 @@
+import type { SerializableKey, TreeMethods } from '../tree/index.js';
+import type { FoldMethods } from '../fold-node/index.js';
+import type { CursorMethods } from '../cursor.js';
+import type { NavMethods } from './nav.types.js';
+/**
+ * Creates an ordered navigation projection.
+ *
+ * Source sibling order is preserved. Each maximal contiguous run of hidden
+ * direct children becomes one inline fold marker.
+ */
+export declare function createOrderedNavMethods<Id extends SerializableKey, Value>(treeMethods: TreeMethods<Id, Value>, foldMethods: FoldMethods<Id>, cursorMethods: CursorMethods<Id>): NavMethods<Id, Value>;
+//# sourceMappingURL=nav.ordered.impl.d.ts.map

package/dist/state-and-nav/nav/nav.ordered.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.ordered.impl.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/nav/nav.ordered.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAY,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAS,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAIV,UAAU,EAEX,MAAM,gBAAgB,CAAC;AAGxB;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACvE,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC,EAC5B,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC,GAC/B,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAmGvB"}

package/dist/state-and-nav/nav/nav.ordered.impl.js

@@ -0,0 +1,77 @@
+import { createNavTraversalMethods } from './nav.traversal.js';
+/**
+ * Creates an ordered navigation projection.
+ *
+ * Source sibling order is preserved. Each maximal contiguous run of hidden
+ * direct children becomes one inline fold marker.
+ */
+export function createOrderedNavMethods(treeMethods, foldMethods, cursorMethods) {
+    /**
+     * Projects loaded direct children without changing their source order.
+     */
+    function createNavNode(entries, foldRoot, parentPath) {
+        const visibleEntries = [];
+        let foldedEntries;
+        for (const entry of entries) {
+            const entryId = treeMethods.id(entry);
+            const entryPath = [...parentPath, entryId];
+            const navigationEntry = createNavEntry(entry, foldRoot, entryPath);
+            const isFolded = foldMethods.isEntryHiddenAtPath(foldRoot, parentPath, entryId);
+            if (isFolded) {
+                /*
+                 * Append a marker when a hidden run begins. Subsequent hidden
+                 * siblings extend that same marker until a visible sibling ends it.
+                 */
+                if (foldedEntries === undefined) {
+                    foldedEntries = {
+                        folded: [],
+                    };
+                    visibleEntries.push(foldedEntries);
+                }
+                /*
+                 * Retain the complete projection for later fold inspection.
+                 * Ordinary traversal never descends into this hidden projection.
+                 */
+                foldedEntries.folded.push(navigationEntry);
+                continue;
+            }
+            foldedEntries = undefined;
+            visibleEntries.push(navigationEntry);
+        }
+        return {
+            entries: visibleEntries,
+        };
+    }
+    function createNavEntry(entry, foldRoot, entryPath) {
+        return treeMethods.matchByKind(entry, {
+            leaf: ({ id }) => ({
+                id,
+            }),
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, entryPath),
+            }),
+        });
+    }
+    function createRootNavBranch(root, foldRoot) {
+        return treeMethods.matchByKind(root, {
+            leaf: () => undefined,
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, []),
+            }),
+        });
+    }
+    return {
+        ...createNavTraversalMethods(cursorMethods, true),
+        from: createRootNavBranch,
+    };
+}

package/dist/state-and-nav/nav/nav.traversal.d.ts

@@ -0,0 +1,11 @@
+import type { CursorMethods } from '../cursor.js';
+import type { SerializableKey } from '../tree/index.js';
+import type { NavMethods } from './nav.types.js';
+/**
+ * Shared navigation operations over both projection styles.
+ *
+ * Fold summaries exist in either projection, but only ordered navigation
+ * exposes them as cursor destinations.
+ */
+export declare function createNavTraversalMethods<Id extends SerializableKey, Value>(cursorMethods: CursorMethods<Id>, navigateFolds: boolean): Omit<NavMethods<Id, Value>, 'from'>;
+//# sourceMappingURL=nav.traversal.d.ts.map

package/dist/state-and-nav/nav/nav.traversal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.traversal.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/nav/nav.traversal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,aAAa,EAAc,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAIV,UAAU,EAEX,MAAM,gBAAgB,CAAC;AAExB;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACzE,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC,EAChC,aAAa,EAAE,OAAO,GACrB,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,CA0SrC"}

package/dist/state-and-nav/nav/nav.traversal.js

@@ -0,0 +1,207 @@
+/**
+ * Shared navigation operations over both projection styles.
+ *
+ * Fold summaries exist in either projection, but only ordered navigation
+ * exposes them as cursor destinations.
+ */
+export function createNavTraversalMethods(cursorMethods, navigateFolds) {
+    function entryIsBranch(entry) {
+        return 'children' in entry;
+    }
+    function entryIsFold(entry) {
+        return 'folded' in entry;
+    }
+    function foldCursor(entry, parentPath) {
+        const firstEntry = entry.folded[0];
+        /*
+         * Projected folds are nonempty and contain direct source entries.
+         * Keep the guard because NavFold also permits richer future contents.
+         */
+        if (firstEntry === undefined || entryIsFold(firstEntry)) {
+            return undefined;
+        }
+        return {
+            parentPath: [...parentPath],
+            firstId: firstEntry.id,
+        };
+    }
+    function getNodeAtPath(navigation, path) {
+        let node = navigation;
+        for (const id of path) {
+            const entry = node.entries.find((candidate) => !entryIsFold(candidate) && candidate.id === id);
+            /*
+             * Paths cannot pass through leaves, folds, or unloaded branches.
+             * Hidden entries inside fold summaries are deliberately not searched.
+             */
+            if (entry === undefined ||
+                !entryIsBranch(entry) ||
+                entry.children === null) {
+                return undefined;
+            }
+            node = entry.children;
+        }
+        // An empty path identifies the current navigation node.
+        return node;
+    }
+    function getEntryAtPath(navigation, path) {
+        /*
+         * A NavNode does not itself correspond to a NavEntry. Therefore [] does
+         * not resolve to an entry.
+         */
+        if (path.length === 0) {
+            return undefined;
+        }
+        const parent = getNodeAtPath(navigation, path.slice(0, -1));
+        const id = path[path.length - 1];
+        return parent?.entries.find((candidate) => !entryIsFold(candidate) && candidate.id === id);
+    }
+    function cursors(navigation, parentPath = []) {
+        const positions = [];
+        for (const entry of navigation.entries) {
+            if (entryIsFold(entry)) {
+                if (navigateFolds) {
+                    const cursor = foldCursor(entry, parentPath);
+                    if (cursor !== undefined) {
+                        positions.push(cursor);
+                    }
+                }
+                // Hidden descendants are never separately navigable.
+                continue;
+            }
+            const entryPath = [...parentPath, entry.id];
+            positions.push({ path: entryPath });
+            if (entryIsBranch(entry) && entry.children !== null) {
+                positions.push(...cursors(entry.children, entryPath));
+            }
+        }
+        return positions;
+    }
+    function rootCursors(rootNode) {
+        return [
+            { path: [] },
+            ...(rootNode.children === null ? [] : cursors(rootNode.children)),
+        ];
+    }
+    function nextCursor(rootNode, cursor) {
+        const positions = rootCursors(rootNode);
+        const currentIndex = positions.findIndex((candidate) => cursorMethods.equal(candidate, cursor));
+        if (currentIndex === -1) {
+            return undefined;
+        }
+        return positions[currentIndex + 1];
+    }
+    function previousCursor(rootNode, cursor) {
+        const positions = rootCursors(rootNode);
+        const currentIndex = positions.findIndex((candidate) => cursorMethods.equal(candidate, cursor));
+        if (currentIndex <= 0) {
+            return undefined;
+        }
+        return positions[currentIndex - 1];
+    }
+    function cursorAfterFold(rootNode, cursor) {
+        if (!cursorMethods.isNodeCursor(cursor) ||
+            cursor.path.length === 0 ||
+            rootNode.children === null) {
+            // Folding root is disallowed. Fold markers are already folded.
+            return undefined;
+        }
+        if (navigateFolds) {
+            const parentPath = cursor.path.slice(0, -1);
+            const parent = getNodeAtPath(rootNode.children, parentPath);
+            const id = cursor.path[cursor.path.length - 1];
+            if (parent === undefined) {
+                return undefined;
+            }
+            const currentIndex = parent.entries.findIndex((entry) => !entryIsFold(entry) && entry.id === id);
+            if (currentIndex === -1) {
+                return undefined;
+            }
+            const entry = parent.entries[currentIndex];
+            if (entry === undefined || entryIsFold(entry)) {
+                return undefined;
+            }
+            const previousEntry = parent.entries[currentIndex - 1];
+            /*
+             * Folding next to an existing preceding run merges into that run.
+             * A following run also merges, but does not determine the first ID.
+             */
+            if (previousEntry !== undefined && entryIsFold(previousEntry)) {
+                const previousFoldCursor = foldCursor(previousEntry, parentPath);
+                if (previousFoldCursor !== undefined) {
+                    return previousFoldCursor;
+                }
+            }
+            return {
+                parentPath,
+                firstId: entry.id,
+            };
+        }
+        const positions = rootCursors(rootNode);
+        const currentIndex = positions.findIndex((candidate) => cursorMethods.equal(candidate, cursor));
+        if (currentIndex === -1) {
+            return undefined;
+        }
+        for (let index = currentIndex + 1; index < positions.length; index += 1) {
+            const candidate = positions[index];
+            if (candidate === undefined) {
+                continue;
+            }
+            // Skip entries that are children of the entry about to be folded.
+            if (cursorMethods.cursorBelongsToSubtree(candidate, cursor.path)) {
+                continue;
+            }
+            return candidate;
+        }
+        /*
+         * No following position survives the fold. Move before the subtree,
+         * rather than into one of its soon-to-be-hidden descendants.
+         */
+        return positions[currentIndex - 1];
+    }
+    function parentCursor(_navigation, cursor) {
+        if (cursorMethods.isFoldCursor(cursor)) {
+            return {
+                path: [...cursor.parentPath],
+            };
+        }
+        if (cursor.path.length === 0) {
+            return undefined;
+        }
+        return {
+            path: cursor.path.slice(0, -1),
+        };
+    }
+    function visibleLeavesPaths(navigation, parentPath = []) {
+        const paths = [];
+        for (const entry of navigation.entries) {
+            if (entryIsFold(entry)) {
+                continue;
+            }
+            const entryPath = [...parentPath, entry.id];
+            if (!entryIsBranch(entry)) {
+                paths.push(entryPath);
+                continue;
+            }
+            /*
+             * A null value means the source branch is not loaded/opened. It has no
+             * currently visible descendants.
+             */
+            if (entry.children !== null) {
+                paths.push(...visibleLeavesPaths(entry.children, entryPath));
+            }
+        }
+        return paths;
+    }
+    return {
+        entryIsBranch,
+        entryIsFold,
+        getNodeAtPath,
+        getEntryAtPath,
+        nextCursor,
+        previousCursor,
+        cursorAfterFold,
+        parentCursor,
+        cursors,
+        visibleLeavesPaths,
+    };
+}

package/dist/{trees/nav-node/nav-node.types.d.ts → state-and-nav/nav/nav.types.d.ts}

@@ -1,47 +1,47 @@
-import type { SerializableKey, TreeNode } from '../tree-node/index.js';
+import type { SerializableKey, TreeNode } from '../tree/index.js';
 import type { Cursor } from '../cursor.js';
 import type { Folds } from '../fold-node/index.js';
 export type NavNode<Id extends SerializableKey> = {
     /**
-     * Synthetic UI entry representing folded children.
+     * Projected direct children, including fold summaries.
      *
-     * It is absent when this directory has no folded children.
-     */
-    folded: NavFoldEntry<Id> | null;
-    /**
-     * Loaded entries that are not folded at this directory, corresponding to
-     * navigable rows.
-     *
-     * Their order is the sibling iteration order supplied by the TreeNode API.
-     */
-    entries: NavEntry<Id>[];
-};
-export type NavFoldEntry<Id extends SerializableKey> = {
-    /**
-     * Folded entries that are present in the loaded TreeNode.
+     * Ordered navigation preserves source sibling order and inserts inline folds.
+     * Unordered navigation uses presentation order and places its optional fold
+     * summary first.
      *
-     * This is information for rendering the folded row.
+     * Not every entry is therefore necessarily a cursor destination: in ordered
+     * trees, the fold summary is not navigable and the NavMethod implementation
+     * should skip it.
      */
     entries: NavEntry<Id>[];
 };
-export type NavEntry<Id extends SerializableKey> = NavLeaf<Id> | NavBranch<Id>;
+export type NavEntry<Id extends SerializableKey> = NavLeaf<Id> | NavBranch<Id> | NavFold<Id>;
 export type NavLeaf<Id extends SerializableKey> = {
     id: Id;
 };
 export type NavBranch<Id extends SerializableKey> = {
     id: Id;
     /**
-     * `null` means this branch's children have not been loaded or opened.
+     * `null` means this branch's children have not been loaded.
      */
     children: NavNode<Id> | null;
 };
+export type NavFold<Id extends SerializableKey> = {
+    /**
+     * Folded entries that are present in the loaded TreeNode.
+     *
+     * For unordered trees, there is at most one folded entry, and it is the first
+     * in nav node's `entries`.
+     */
+    folded: NavEntry<Id>[];
+};
 /**
  * Operations for creating and navigating a UI-oriented projection of a tree.
  *
  * @typeParam Id - The type identifying a node among its direct siblings.
  * @typeParam Value - Application-owned data stored in each source TreeNode.
  */
-export type NavNodeApi<Id extends SerializableKey, Value> = {
+export type NavMethods<Id extends SerializableKey, Value> = {
     /**
      * Tests whether a navigation entry represents a branch.
      *
@@ -50,6 +50,10 @@ export type NavNodeApi<Id extends SerializableKey, Value> = {
      * opened.
      */
     entryIsBranch(entry: NavEntry<Id>): entry is NavBranch<Id>;
+    /**
+     * Tests whether a navigation entry represents a branch.
+     */
+    entryIsFold(entry: NavEntry<Id>): entry is NavFold<Id>;
     /**
      * Creates a navigation projection rooted at `root`.
      *
@@ -71,7 +75,7 @@ export type NavNodeApi<Id extends SerializableKey, Value> = {
      * express that fact statically. This method returns `undefined` if `root`
      * is a leaf.
      *
-     * A closed root branch produces a NavBranch whose `children` is `null`.
+     * An unloaded branch produces a NavBranch whose `children` is `null`.
      *
      * @param root - Source tree node from which to create navigation.
      * @param folds - Fold definitions corresponding to `root`. All active fold
@@ -102,7 +106,13 @@ export type NavNodeApi<Id extends SerializableKey, Value> = {
      * @param cursor
      */
     parentCursor(navigation: NavNode<Id>, cursor: Cursor<Id>): Cursor<Id> | undefined;
+    /**
+     * Enumerates navigable positions in depth-first display order.
+     *
+     * Unordered navigation skips fold summaries.
+     * Ordered navigation includes inline folds as fold cursors.
+     */
     cursors(navigation: NavNode<Id>, parentPath?: readonly Id[]): Cursor<Id>[];
     visibleLeavesPaths(navigation: NavNode<Id>, parentPath?: readonly Id[]): Id[][];
 };
-//# sourceMappingURL=nav-node.types.d.ts.map
+//# sourceMappingURL=nav.types.d.ts.map

package/dist/state-and-nav/nav/nav.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.types.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/nav/nav.types.ts"],"names":[],"mappings":"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"}

package/dist/state-and-nav/nav/nav.unordered.impl.d.ts

@@ -0,0 +1,13 @@
+import type { SerializableKey, TreeMethods } from '../tree/index.js';
+import type { FoldMethods } from '../fold-node/index.js';
+import type { CursorMethods } from '../cursor.js';
+import type { NavMethods } from './nav.types.js';
+/**
+ * Creates operations for projecting an opaque tree into a navigation model.
+ *
+ * Sibling order has no semantic meaning in this navigation system.
+ * This projection preserves source sibling order among visible entries and
+ * collects hidden entries into one leading, non-navigable fold summary.
+ */
+export declare function createUnorderedNavMethods<Id extends SerializableKey, Value>(treeMethods: TreeMethods<Id, Value>, foldMethods: FoldMethods<Id>, cursorMethods: CursorMethods<Id>): NavMethods<Id, Value>;
+//# sourceMappingURL=nav.unordered.impl.d.ts.map

package/dist/state-and-nav/nav/nav.unordered.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav.unordered.impl.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/nav/nav.unordered.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAY,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/E,OAAO,KAAK,EAAS,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAKV,UAAU,EACX,MAAM,gBAAgB,CAAC;AAGxB;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EACzE,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,WAAW,EAAE,WAAW,CAAC,EAAE,CAAC,EAC5B,aAAa,EAAE,aAAa,CAAC,EAAE,CAAC,GAC/B,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CA+FvB"}

package/dist/state-and-nav/nav/nav.unordered.impl.js

@@ -0,0 +1,77 @@
+import { createNavTraversalMethods } from './nav.traversal.js';
+/**
+ * Creates operations for projecting an opaque tree into a navigation model.
+ *
+ * Sibling order has no semantic meaning in this navigation system.
+ * This projection preserves source sibling order among visible entries and
+ * collects hidden entries into one leading, non-navigable fold summary.
+ */
+export function createUnorderedNavMethods(treeMethods, foldMethods, cursorMethods) {
+    /**
+     * Projects loaded children into navigation entries.
+     *
+     * Folded source entries are collected into one leading, non-navigable
+     * fold summary. Their complete projections are retained inside it.
+     */
+    function createNavNode(entries, foldRoot, parentPath) {
+        const visibleEntries = [];
+        const foldedEntries = [];
+        for (const entry of entries) {
+            const entryId = treeMethods.id(entry);
+            const entryPath = [...parentPath, entryId];
+            const isFolded = foldMethods.isEntryHiddenAtPath(foldRoot, parentPath, entryId);
+            const navigationEntry = createNavEntry(entry, foldRoot, entryPath);
+            if (isFolded) {
+                /*
+                 * Retain the complete projection for later fold inspection.
+                 * Ordinary traversal never descends into this hidden projection.
+                 */
+                foldedEntries.push(navigationEntry);
+            }
+            else {
+                visibleEntries.push(navigationEntry);
+            }
+        }
+        return {
+            /*
+             * Fold state may contain entries that are not currently available in the
+             * loaded source tree. Do not render an empty synthetic row for them.
+             */
+            entries: foldedEntries.length === 0
+                ? visibleEntries
+                : [{ folded: foldedEntries }, ...visibleEntries],
+        };
+    }
+    function createNavEntry(entry, foldRoot, entryPath) {
+        return treeMethods.matchByKind(entry, {
+            leaf: ({ id }) => ({
+                id,
+            }),
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, entryPath),
+            }),
+        });
+    }
+    function createRootNavBranch(root, foldRoot) {
+        return treeMethods.matchByKind(root, {
+            leaf: () => undefined,
+            unloadedBranch: ({ id }) => ({
+                id,
+                children: null,
+            }),
+            loadedBranch: ({ id, children }) => ({
+                id,
+                children: createNavNode(children, foldRoot, []),
+            }),
+        });
+    }
+    return {
+        ...createNavTraversalMethods(cursorMethods, false),
+        from: createRootNavBranch,
+    };
+}

package/dist/state-and-nav/state/state.impl.d.ts

@@ -0,0 +1,9 @@
+import type { SerializableKey, TreeMethods } from '../tree/index.js';
+import type { FoldMethods } from '../fold-node/index.js';
+import type { CursorMethods } from '../cursor.js';
+import type { StateApi } from './state.types.js';
+/**
+ * Creates operations for navigating and resynchronizing tree-surfer state.
+ */
+export declare function createStateApi<Id extends SerializableKey, Value>(treeNodeApi: TreeMethods<Id, Value>, foldsApi: FoldMethods<Id>, cursorApi: CursorMethods<Id>): StateApi<Id, Value>;
+//# sourceMappingURL=state.impl.d.ts.map

package/dist/state-and-nav/state/state.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.impl.d.ts","sourceRoot":"","sources":["../../../src/state-and-nav/state/state.impl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EAEf,WAAW,EACZ,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAS,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAU,aAAa,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,QAAQ,EAAS,MAAM,kBAAkB,CAAC;AA4CxD;;GAEG;AACH,wBAAgB,cAAc,CAAC,EAAE,SAAS,eAAe,EAAE,KAAK,EAC9D,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,KAAK,CAAC,EACnC,QAAQ,EAAE,WAAW,CAAC,EAAE,CAAC,EACzB,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC,GAC3B,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC,CA2PrB"}