useTree ​

function useTree<T>(options: UseTreeOptions<T>): UseTreeReturn<T>;

interface UseTreeOptions<T> {
  /**
   * The flat list or hierarchical tree of items in the collection.
   */
  items: MaybeRefOrGetter<T[]>;

  /**
   * Function to extract a unique string identifier from an item.
   */
  getItemId: (item: T) => string;

  /**
   * Optional function to determine if an item is disabled (cannot be navigated).
   */
  isItemDisabled?: (item: T) => boolean;

  /**
   * Optional function to extract children from an item, turning a 1D list into a 2D tree.
   */
  getItemChildren?: (item: T) => T[] | null | undefined;
}

interface TreeBranch<T> {
  /**
   * The parent node's value, or `null` for the root branch.
   */
  parentValue: string | null;

  /**
   * The direct children items at this branch level.
   */
  items: ComputedRef<T[]>;

  /**
   * Projected active value — only non-null when the tree's active value
   * belongs to this specific branch.
   */
  activeValue: Ref<string | null>;

  /**
   * Set the active value directly. Rejects disabled items.
   */
  setActiveValue: (value: string | null) => void;

  /**
   * Navigate to the next enabled item within this branch.
   */
  setNext: (options?: { loop?: boolean }) => void;

  /**
   * Navigate to the previous enabled item within this branch.
   */
  setPrevious: (options?: { loop?: boolean }) => void;

  /**
   * Navigate to the first enabled item within this branch.
   */
  setFirst: () => void;

  /**
   * Navigate to the last enabled item within this branch.
   */
  setLast: () => void;

  /**
   * Check if a specific value is disabled.
   */
  isItemDisabled: (value: string) => boolean;
}

interface UseTreeReturn<T> {
  /**
   * The currently active value across the entire tree.
   */
  activeValue: Ref<string | null>;

  /**
   * Set of item values whose branches are currently expanded.
   */
  expandedValues: Ref<ReadonlySet<string>>;

  /**
   * DFS-order flattened array of currently visible items based on expansion state.
   */
  flattenedItems: ComputedRef<T[]>;

  /**
   * Set the active value directly. Rejects disabled items.
   */
  setActiveValue: (value: string | null) => void;

  /**
   * Expand a branch by its parent item value. No-op for leaf nodes.
   */
  expandBranch: (value: string) => void;

  /**
   * Collapse a branch by its parent item value.
   */
  collapseBranch: (value: string) => void;

  /**
   * Collapse all branches.
   */
  collapseAll: () => void;

  /**
   * Check if a specific value's branch is currently expanded.
   */
  isExpanded: (value: string) => boolean;

  /**
   * Look up the original item by its value. Returns `null` if not found.
   */
  getItem: (value: string) => T | null;

  /**
   * Check if a node has children (i.e., is a branch parent).
   */
  hasChildren: (value: string) => boolean;

  /**
   * Check if a specific value is disabled.
   */
  isItemDisabled: (value: string) => boolean;

  /**
   * Get the parent value for a given item value. Returns `null` for root items.
   */
  getParentValue: (value: string) => string | null;

  /**
   * Get the depth of a node in the tree. Root items are depth 0.
   * Returns -1 if the value is not found.
   */
  getDepth: (value: string) => number;

  /**
   * Get all ancestor values from parent to root (closest first).
   */
  getAncestorValues: (value: string) => string[];

  /**
   * Get sibling values (same-level items, excluding the item itself).
   */
  getSiblingValues: (value: string) => string[];

  /**
   * Get the first enabled descendant value via DFS. Returns `null` if none found.
   */
  getFirstEnabledDescendantValue: (value: string) => string | null;

  /**
   * The root-level branch containing all top-level items.
   */
  rootBranch: TreeBranch<T>;

  /**
   * Get the branch for a specific parent node. Returns `null` for leaf nodes.
   * Branch instances are cached — same parent always returns the same reference.
   */
  getBranch: (parentValue: string) => TreeBranch<T> | null;
}