@rezi-ui/core 0.1.0-alpha.1

package/dist/widgets/tree.d.ts

@@ -0,0 +1,207 @@
+/**
+ * packages/core/src/widgets/tree.ts — Tree widget core algorithms.
+ *
+ * Why: Implements the core logic for tree widgets including node flattening,
+ * NodeState computation, tree line rendering, and lazy loading state.
+ *
+ * Algorithms:
+ *   - Node flattening: DFS traversal respecting expanded state
+ *   - NodeState: computed state for each visible node
+ *   - Tree lines: ├── └── │ characters for visual hierarchy
+ *   - Lazy loading: async children loading with loading state
+ *
+ * @see docs/widgets/tree.md
+ */
+import type { NodeState } from "./types.js";
+/** A flattened node with depth and sibling information. */
+export type FlattenedNode<T> = Readonly<{
+    /** The original node data. */
+    node: T;
+    /** Depth in the tree (0 = root). */
+    depth: number;
+    /** Index in siblings array. */
+    siblingIndex: number;
+    /** Total siblings count. */
+    siblingCount: number;
+    /** Key of the node. */
+    key: string;
+    /** Key of parent node (null for roots). */
+    parentKey: string | null;
+    /** Whether this node has children. */
+    hasChildren: boolean;
+    /** Ancestor expanded states for tree line rendering. */
+    ancestorIsLast: readonly boolean[];
+}>;
+/**
+ * Flatten a tree into a list of visible nodes.
+ *
+ * Only includes nodes whose ancestors are all expanded.
+ * Order is depth-first pre-order traversal.
+ *
+ * @param data - Root node(s)
+ * @param getKey - Function to get node key
+ * @param getChildren - Function to get node children
+ * @param hasChildrenFn - Function to check if node has children
+ * @param expanded - Set of expanded node keys
+ * @returns Array of flattened nodes
+ */
+export declare function flattenTree<T>(data: T | readonly T[], getKey: (node: T) => string, getChildren: ((node: T) => readonly T[] | undefined) | undefined, hasChildrenFn: ((node: T) => boolean) | undefined, expanded: readonly string[], expandedSet?: ReadonlySet<string>): readonly FlattenedNode<T>[];
+/**
+ * Compute NodeState for a flattened node.
+ *
+ * @param flatNode - The flattened node
+ * @param expanded - Set of expanded node keys
+ * @param selected - Currently selected node key
+ * @param focused - Currently focused node key
+ * @param loading - Set of loading node keys
+ * @returns NodeState for the node
+ */
+export declare function computeNodeState<T>(flatNode: FlattenedNode<T>, expanded: readonly string[], selected: string | undefined, focused: string | undefined, loading: ReadonlySet<string>, expandedSet?: ReadonlySet<string>): NodeState;
+/** Tree line character set. */
+export declare const TREE_CHARS: Readonly<{
+    /**
+     * NOTE: Keep these ASCII.
+     *
+     * Some terminals/fonts render box-drawing characters with fallback glyphs or
+     * ambiguous widths, which can produce "blocky" artifacts and break the visual
+     * structure. ASCII is the most compatible and still reads well.
+     */
+    vertical: "|";
+    branch: "+--";
+    lastBranch: "\\--";
+    horizontal: "--";
+    space: "   ";
+}>;
+/**
+ * Generate tree line prefix for a node.
+ *
+ * @param flatNode - The flattened node
+ * @param showLines - Whether to show tree lines
+ * @param indentSize - Characters per indent level
+ * @returns String prefix for the node
+ */
+export declare function getTreeLinePrefix<T>(flatNode: FlattenedNode<T>, showLines: boolean, indentSize: number): string;
+/**
+ * Find the index of a node in the flattened list by key.
+ *
+ * @param flatNodes - Flattened node list
+ * @param key - Node key to find
+ * @returns Index or -1 if not found
+ */
+export declare function findNodeIndex<T>(flatNodes: readonly FlattenedNode<T>[], key: string): number;
+/**
+ * Find the parent node in the flattened list.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns Parent node index or -1 if at root
+ */
+export declare function findParentIndex<T>(flatNodes: readonly FlattenedNode<T>[], currentIndex: number): number;
+/**
+ * Find the first child node in the flattened list.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns First child index or -1 if no children visible
+ */
+export declare function findFirstChildIndex<T>(flatNodes: readonly FlattenedNode<T>[], currentIndex: number): number;
+/**
+ * Add a key to the expanded set.
+ *
+ * @param expanded - Current expanded keys
+ * @param key - Key to add
+ * @returns New expanded set
+ */
+export declare function expandNode(expanded: readonly string[], key: string): readonly string[];
+/**
+ * Remove a key from the expanded set.
+ *
+ * @param expanded - Current expanded keys
+ * @param key - Key to remove
+ * @returns New expanded set
+ */
+export declare function collapseNode(expanded: readonly string[], key: string): readonly string[];
+/**
+ * Toggle a node's expanded state.
+ *
+ * @param expanded - Current expanded keys
+ * @param key - Key to toggle
+ * @returns New expanded set and whether it's now expanded
+ */
+export declare function toggleExpanded(expanded: readonly string[], key: string): {
+    expanded: readonly string[];
+    isExpanded: boolean;
+};
+/**
+ * Expand all siblings of a node (nodes at the same depth with same parent).
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @param expanded - Current expanded keys
+ * @returns New expanded set with all siblings expanded
+ */
+export declare function expandAllSiblings<T>(flatNodes: readonly FlattenedNode<T>[], currentIndex: number, expanded: readonly string[]): readonly string[];
+/**
+ * Create a loading state tracker.
+ */
+export type LoadingState = Readonly<{
+    /** Set of node keys currently loading. */
+    loading: ReadonlySet<string>;
+    /** Add a key to loading state. */
+    startLoading: (key: string) => LoadingState;
+    /** Remove a key from loading state. */
+    finishLoading: (key: string) => LoadingState;
+    /** Check if a key is loading. */
+    isLoading: (key: string) => boolean;
+}>;
+/**
+ * Create a new loading state.
+ *
+ * @param initial - Initial loading keys
+ * @returns LoadingState object
+ */
+export declare function createLoadingState(initial?: readonly string[]): LoadingState;
+/** Expand/collapse indicator characters. */
+export declare const EXPAND_INDICATORS: Readonly<{
+    /** Expanded indicator ▼ */
+    expanded: "▼";
+    /** Collapsed indicator ▶ */
+    collapsed: "▶";
+    /** Leaf (no children) indicator */
+    leaf: " ";
+    /** Loading indicator */
+    loading: "◌";
+}>;
+/**
+ * Get expand/collapse indicator for a node.
+ *
+ * @param hasChildren - Whether node has children
+ * @param isExpanded - Whether node is expanded
+ * @param isLoading - Whether node is loading
+ * @returns Indicator character
+ */
+export declare function getExpandIndicator(hasChildren: boolean, isExpanded: boolean, isLoading: boolean): string;
+/**
+ * Count total visible nodes for virtualization.
+ *
+ * @param flatNodes - Flattened node list
+ * @returns Total count
+ */
+export declare function getTotalVisibleNodes<T>(flatNodes: readonly FlattenedNode<T>[]): number;
+/**
+ * Find the next sibling node.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns Next sibling index or -1 if none
+ */
+export declare function findNextSiblingIndex<T>(flatNodes: readonly FlattenedNode<T>[], currentIndex: number): number;
+/**
+ * Find the previous sibling node.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns Previous sibling index or -1 if none
+ */
+export declare function findPrevSiblingIndex<T>(flatNodes: readonly FlattenedNode<T>[], currentIndex: number): number;
+//# sourceMappingURL=tree.d.ts.map

package/dist/widgets/tree.d.ts.map

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

package/dist/widgets/tree.js

@@ -0,0 +1,393 @@
+/**
+ * packages/core/src/widgets/tree.ts — Tree widget core algorithms.
+ *
+ * Why: Implements the core logic for tree widgets including node flattening,
+ * NodeState computation, tree line rendering, and lazy loading state.
+ *
+ * Algorithms:
+ *   - Node flattening: DFS traversal respecting expanded state
+ *   - NodeState: computed state for each visible node
+ *   - Tree lines: ├── └── │ characters for visual hierarchy
+ *   - Lazy loading: async children loading with loading state
+ *
+ * @see docs/widgets/tree.md
+ */
+/* ========== Node Flattening ========== */
+/**
+ * Flatten a tree into a list of visible nodes.
+ *
+ * Only includes nodes whose ancestors are all expanded.
+ * Order is depth-first pre-order traversal.
+ *
+ * @param data - Root node(s)
+ * @param getKey - Function to get node key
+ * @param getChildren - Function to get node children
+ * @param hasChildrenFn - Function to check if node has children
+ * @param expanded - Set of expanded node keys
+ * @returns Array of flattened nodes
+ */
+export function flattenTree(data, getKey, getChildren, hasChildrenFn, expanded, expandedSet) {
+    const result = [];
+    const expandedLookup = expandedSet ?? new Set(expanded);
+    // Normalize to array of roots
+    const roots = Array.isArray(data) ? data : [data];
+    function traverse(nodes, depth, parentKey, ancestorIsLast) {
+        const siblingCount = nodes.length;
+        for (let i = 0; i < siblingCount; i++) {
+            const node = nodes[i];
+            if (node === undefined)
+                continue;
+            const key = getKey(node);
+            const children = getChildren?.(node);
+            const hasChildren = hasChildrenFn ? hasChildrenFn(node) : (children?.length ?? 0) > 0;
+            const isLast = i === siblingCount - 1;
+            const flatNode = Object.freeze({
+                node,
+                depth,
+                siblingIndex: i,
+                siblingCount,
+                key,
+                parentKey,
+                hasChildren,
+                ancestorIsLast: Object.freeze([...ancestorIsLast, isLast]),
+            });
+            result.push(flatNode);
+            // Recurse into children if expanded
+            if (hasChildren && expandedLookup.has(key) && children && children.length > 0) {
+                traverse(children, depth + 1, key, flatNode.ancestorIsLast);
+            }
+        }
+    }
+    traverse(roots, 0, null, []);
+    return Object.freeze(result);
+}
+/* ========== NodeState Computation ========== */
+/**
+ * Compute NodeState for a flattened node.
+ *
+ * @param flatNode - The flattened node
+ * @param expanded - Set of expanded node keys
+ * @param selected - Currently selected node key
+ * @param focused - Currently focused node key
+ * @param loading - Set of loading node keys
+ * @returns NodeState for the node
+ */
+export function computeNodeState(flatNode, expanded, selected, focused, loading, expandedSet) {
+    const expandedLookup = expandedSet ?? new Set(expanded);
+    return Object.freeze({
+        expanded: expandedLookup.has(flatNode.key),
+        selected: flatNode.key === selected,
+        focused: flatNode.key === focused,
+        loading: loading.has(flatNode.key),
+        depth: flatNode.depth,
+        isFirst: flatNode.siblingIndex === 0,
+        isLast: flatNode.siblingIndex === flatNode.siblingCount - 1,
+        hasChildren: flatNode.hasChildren,
+    });
+}
+/* ========== Tree Line Characters ========== */
+/** Tree line character set. */
+export const TREE_CHARS = Object.freeze({
+    /**
+     * NOTE: Keep these ASCII.
+     *
+     * Some terminals/fonts render box-drawing characters with fallback glyphs or
+     * ambiguous widths, which can produce "blocky" artifacts and break the visual
+     * structure. ASCII is the most compatible and still reads well.
+     */
+    vertical: "|",
+    branch: "+--",
+    lastBranch: "\\--",
+    horizontal: "--",
+    space: "   ",
+});
+/**
+ * Generate tree line prefix for a node.
+ *
+ * @param flatNode - The flattened node
+ * @param showLines - Whether to show tree lines
+ * @param indentSize - Characters per indent level
+ * @returns String prefix for the node
+ */
+export function getTreeLinePrefix(flatNode, showLines, indentSize) {
+    if (flatNode.depth === 0) {
+        return "";
+    }
+    if (!showLines) {
+        // Simple indentation without lines
+        return " ".repeat(flatNode.depth * indentSize);
+    }
+    // Build tree line prefix
+    const parts = [];
+    // Add ancestor lines (excluding the last which is for current node)
+    for (let i = 0; i < flatNode.depth - 1; i++) {
+        const isLast = flatNode.ancestorIsLast[i];
+        if (isLast) {
+            // Ancestor was last child, no continuing line
+            parts.push(TREE_CHARS.space);
+        }
+        else {
+            // Ancestor has siblings below, show continuing line
+            parts.push(`${TREE_CHARS.vertical}  `);
+        }
+    }
+    // Add branch for current node
+    const isLast = flatNode.siblingIndex === flatNode.siblingCount - 1;
+    parts.push(isLast ? TREE_CHARS.lastBranch : TREE_CHARS.branch);
+    return parts.join("");
+}
+/* ========== Navigation ========== */
+/**
+ * Find the index of a node in the flattened list by key.
+ *
+ * @param flatNodes - Flattened node list
+ * @param key - Node key to find
+ * @returns Index or -1 if not found
+ */
+export function findNodeIndex(flatNodes, key) {
+    for (let i = 0; i < flatNodes.length; i++) {
+        const node = flatNodes[i];
+        if (node?.key === key) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Find the parent node in the flattened list.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns Parent node index or -1 if at root
+ */
+export function findParentIndex(flatNodes, currentIndex) {
+    const current = flatNodes[currentIndex];
+    if (!current || current.parentKey === null) {
+        return -1;
+    }
+    return findNodeIndex(flatNodes, current.parentKey);
+}
+/**
+ * Find the first child node in the flattened list.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns First child index or -1 if no children visible
+ */
+export function findFirstChildIndex(flatNodes, currentIndex) {
+    const current = flatNodes[currentIndex];
+    if (!current)
+        return -1;
+    const nextIndex = currentIndex + 1;
+    const next = flatNodes[nextIndex];
+    // Check if next node is a child (depth is current + 1 and has current as parent)
+    if (next && next.parentKey === current.key && next.depth === current.depth + 1) {
+        return nextIndex;
+    }
+    return -1;
+}
+/* ========== Expand/Collapse Operations ========== */
+/**
+ * Add a key to the expanded set.
+ *
+ * @param expanded - Current expanded keys
+ * @param key - Key to add
+ * @returns New expanded set
+ */
+export function expandNode(expanded, key) {
+    if (expanded.includes(key)) {
+        return expanded;
+    }
+    return Object.freeze([...expanded, key]);
+}
+/**
+ * Remove a key from the expanded set.
+ *
+ * @param expanded - Current expanded keys
+ * @param key - Key to remove
+ * @returns New expanded set
+ */
+export function collapseNode(expanded, key) {
+    const index = expanded.indexOf(key);
+    if (index === -1) {
+        return expanded;
+    }
+    const result = expanded.filter((k) => k !== key);
+    return Object.freeze(result);
+}
+/**
+ * Toggle a node's expanded state.
+ *
+ * @param expanded - Current expanded keys
+ * @param key - Key to toggle
+ * @returns New expanded set and whether it's now expanded
+ */
+export function toggleExpanded(expanded, key) {
+    const isCurrentlyExpanded = expanded.includes(key);
+    if (isCurrentlyExpanded) {
+        return {
+            expanded: collapseNode(expanded, key),
+            isExpanded: false,
+        };
+    }
+    return {
+        expanded: expandNode(expanded, key),
+        isExpanded: true,
+    };
+}
+/**
+ * Expand all siblings of a node (nodes at the same depth with same parent).
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @param expanded - Current expanded keys
+ * @returns New expanded set with all siblings expanded
+ */
+export function expandAllSiblings(flatNodes, currentIndex, expanded) {
+    const current = flatNodes[currentIndex];
+    if (!current)
+        return expanded;
+    const siblingKeys = [];
+    // Find all siblings (same parentKey and depth)
+    for (let i = 0; i < flatNodes.length; i++) {
+        const node = flatNodes[i];
+        if (node &&
+            node.parentKey === current.parentKey &&
+            node.depth === current.depth &&
+            node.hasChildren) {
+            siblingKeys.push(node.key);
+        }
+    }
+    // Add all siblings to expanded set
+    const expandedSet = new Set(expanded);
+    const originalSize = expandedSet.size;
+    for (const key of siblingKeys) {
+        expandedSet.add(key);
+    }
+    // Return same reference if nothing changed
+    if (expandedSet.size === originalSize) {
+        return expanded;
+    }
+    return Object.freeze([...expandedSet]);
+}
+/**
+ * Create a new loading state.
+ *
+ * @param initial - Initial loading keys
+ * @returns LoadingState object
+ */
+export function createLoadingState(initial = []) {
+    const loading = new Set(initial);
+    const state = Object.freeze({
+        loading: loading,
+        startLoading: (key) => {
+            if (loading.has(key)) {
+                return state;
+            }
+            return createLoadingState([...loading, key]);
+        },
+        finishLoading: (key) => {
+            if (!loading.has(key)) {
+                return state;
+            }
+            return createLoadingState([...loading].filter((k) => k !== key));
+        },
+        isLoading: (key) => loading.has(key),
+    });
+    return state;
+}
+/* ========== Expand/Collapse Indicators ========== */
+/** Expand/collapse indicator characters. */
+export const EXPAND_INDICATORS = Object.freeze({
+    /** Expanded indicator ▼ */
+    expanded: "▼",
+    /** Collapsed indicator ▶ */
+    collapsed: "▶",
+    /** Leaf (no children) indicator */
+    leaf: " ",
+    /** Loading indicator */
+    loading: "◌",
+});
+/**
+ * Get expand/collapse indicator for a node.
+ *
+ * @param hasChildren - Whether node has children
+ * @param isExpanded - Whether node is expanded
+ * @param isLoading - Whether node is loading
+ * @returns Indicator character
+ */
+export function getExpandIndicator(hasChildren, isExpanded, isLoading) {
+    if (isLoading) {
+        return EXPAND_INDICATORS.loading;
+    }
+    if (!hasChildren) {
+        return EXPAND_INDICATORS.leaf;
+    }
+    return isExpanded ? EXPAND_INDICATORS.expanded : EXPAND_INDICATORS.collapsed;
+}
+/* ========== Total Visible Nodes ========== */
+/**
+ * Count total visible nodes for virtualization.
+ *
+ * @param flatNodes - Flattened node list
+ * @returns Total count
+ */
+export function getTotalVisibleNodes(flatNodes) {
+    return flatNodes.length;
+}
+/* ========== Navigate to Sibling ========== */
+/**
+ * Find the next sibling node.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns Next sibling index or -1 if none
+ */
+export function findNextSiblingIndex(flatNodes, currentIndex) {
+    const current = flatNodes[currentIndex];
+    if (!current)
+        return -1;
+    // Scan forward for a sibling (same parent and depth)
+    for (let i = currentIndex + 1; i < flatNodes.length; i++) {
+        const node = flatNodes[i];
+        if (!node)
+            continue;
+        // Stop if we go back up to a shallower depth
+        if (node.depth < current.depth) {
+            break;
+        }
+        // Found sibling
+        if (node.depth === current.depth && node.parentKey === current.parentKey) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Find the previous sibling node.
+ *
+ * @param flatNodes - Flattened node list
+ * @param currentIndex - Current node index
+ * @returns Previous sibling index or -1 if none
+ */
+export function findPrevSiblingIndex(flatNodes, currentIndex) {
+    const current = flatNodes[currentIndex];
+    if (!current)
+        return -1;
+    // Scan backward for a sibling (same parent and depth)
+    for (let i = currentIndex - 1; i >= 0; i--) {
+        const node = flatNodes[i];
+        if (!node)
+            continue;
+        // Found sibling
+        if (node.depth === current.depth && node.parentKey === current.parentKey) {
+            return i;
+        }
+        // Stop if we encounter a node at a shallower depth
+        if (node.depth < current.depth) {
+            break;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=tree.js.map

package/dist/widgets/tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree.js","sourceRoot":"","sources":["../../src/widgets/tree.ts"],"names":[],"mappings":"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"}