Skip to content

jaredLunde/exploration

Repository files navigation


Exploration

Primitives for creating high performance file explorers with React

npm i exploration

Supported by FlexStack


Bundlephobia Types Code coverage NPM Version MIT License

Features

  • Zero-recursion, expandable tree
  • Virtualization, only render what is visible
  • Create/delete/move/rename actions
  • Drag and drop
  • Hotkeys
  • Multiselect
  • Traits, add class names to selections, focused elements, anything
  • Filtering/search
  • Tree snapshot restoration for persisting the expanded state of the tree between refreshes
  • Strongly typed so you can engineer with confidence
  • Concurrent mode safe, ready for React 18

The problem

File explorers in React tend to be large, slow, and opinionated. They usually peter out at a hundred nodes and aren't suitable for building a complex file explorer in the browser. Other solutions like Aspen aimed to solve this problem by using typed arrays (which don't seem to offer much benefit in performance) and event-driven models. They did a pretty job, however, the documentation was sparse and the code was verbose. All that said, Aspen and Monaco's tree were huge inspirations.

The solution

With this library I tried to solve all of those problems. It's built on plain JavaScript arrays, well-designed data structures, an event-driven model, and concurrent mode-safe React hooks. It does just enough to be extremely powerful without being opinionated about styles, hotkeys, or traits. It's also performant enough to be used in browser integrated development environments. It makes sure React only renders what changes without render thrashing.

Most importantly - it's easy to use. So check out the recipes below and give it a try!


Recipes

☀︎ Coming soon

  1. How to create a new file or directory to the tree
  2. How to delete a file or directory from the tree
  3. How to rename a file
  4. How to implement drag 'n drop with multiselect
  5. How to add traits to files/directories
  6. How to add your own hotkeys
  7. How to do perfom an action when a file is selected (opened)
  8. How to filter the list of visible files/directories
  9. How to write your own file tree plugin
  10. How to restore the state of the file tree from local storage

React API

createFileTree()

Create a file tree that can be used with the React API.

Arguments

Name Type Required? Description
getNodes GetNodes<Meta> Yes A function that returns the nodes of the file tree.
config FileTreeConfig<Meta> No Configuration options for the file tree.

GetNodes

type GetNodes<Meta> = {
  /**
   * Get the nodes for a given directory
   *
   * @param parent - The parent directory to get the nodes for
   * @param factory - A factory to create nodes (file/dir) with
   */
  (parent: Dir<Meta>, factory: Omit<FileTreeFactory<Meta>, "createPrompt">):
    | Promise<FileTreeNode<Meta>[]>
    | FileTreeNode<Meta>[];
};

FileTreeConfig

type FileTreeConfig<Meta> = {
  /**
   * A function that compares two nodes for sorting.
   */
  comparator?: FileTree["comparator"];
  /**
   * The root node data
   */
  root?: Omit<FileTreeData<Meta>, "type">;
  /**
   * Restore the tree from a snapshot
   */
  restoreFromSnapshot?: FileTreeSnapshot;
};

Returns FileTree

⇗ Back to top


useVirtualize()

A hook similar to react-window's FixedSizeList component. It allows you to render only enough components to fill a viewport, solving some important performance bottlenecks when rendering large lists.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
config UseVirtualizeConfig Yes Configuration options

UseVirtualizeConfig

Name Type Required? Description
windowRef WindowRef Yes A React ref created by useRef() or an HTML element for the container viewport you're rendering the list inside of.
nodeHeight number Yes The fixed height (in px) of each node in your list.
nodeGap number No Optionally set a gap (in px) between each node in your list.
nodes number[] No When using a hook like useFilter you can supply the filtered list of nodes to this option. By default, useVirtualize() uses the nodes returned by useVisibleNodes()
overscanBy number No This number is used for determining the number of nodes outside of the visible window to render. The default value is 2 which means "render 2 windows worth (2 * height) of content before and after the items in the visible window". A value of 3 would be 3 windows worth of grid cells, so it's a linear relationship. Overscanning is important for preventing tearing when scrolling through items in the grid, but setting too high of a value may create too much work for React to handle, so it's best that you tune this value accordingly.
ResizeObserver ResizeObserver No This hook uses a ResizeObserver for tracking the size of the viewport. If you need to polyfill ResizeObserver you can provide that polyfill here. By default, we use the ResizeObserver from the window global.

Returns UseVirtualizeResult

interface UseVirtualizeResult<Meta> {
  /**
   * The current scroll position of the viewport
   */
  scrollTop: number;
  /**
   * `true` if the viewport is currently scrolling
   */
  isScrolling: boolean;
  /**
   * Scroll to the viewport a given position
   * @param scrollTop - The new scroll position
   * @param config - Configuration options
   */
  scrollTo(
    scrollTop: number,
    config: Pick<ScrollToNodeConfig, "behavior">
  ): void;
  /**
   * Scroll to a given node by its ID
   * @param nodeId - The node ID to scroll to
   * @param config - Configuration options
   */
  scrollToNode(nodeId: number, config?: ScrollToNodeConfig): void;
  /**
   * Props that should be applied to the container you're mapping your virtualized
   * nodes into.
   */
  props: VirtualizeContainerProps;
  /**
   * Calls a defined render function on each node and returns an array that
   * contains the resulting React elements.
   *
   * @param render - A callback that renders a node.
   */
  map(
    render: (config: VirtualizeRenderProps<Meta>) => React.ReactElement
  ): React.ReactElement[];
}

interface VirtualizeRenderProps<Meta> {
  /**
   * A stable key as required by React elements that are included in arrays
   */
  key: number;
  /**
   * The index of the node within the list of visible nodes
   */
  index: number;
  /**
   * A file tree node
   */
  node: FileTreeNode<Meta>;
  /**
   * The file tree that contains the node
   */
  tree: FileTree<Meta>;
  /**
   * Styles that need to be applied to the node element
   */
  style: React.CSSProperties;
}

⇗ Back to top


<Node>

A React component that renders a node in a file tree with plugins. This can be directly paired with the useVirtualize() hook.

Node Props

Name Type Required? Description
as React.ComponentType<React.HTMLAttributes<HTMLElement>> No Render the node as this component. Defaults to "div".
node FileTreeNode<Meta> Yes A file tree node
index number Yes The index of the node within the file tree list of visible nodes
tree FileTree<Meta> Yes The file tree that contains the node
style React.CSSProperties Yes Styles to apply to the <div> element
children React.ReactNode Yes Children to render within the node

⇗ Back to top


useNode()

A plugin that creates and memoizes node-specific props.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
config Pick<NodeProps<Meta>, "node" | "index" | "style"> Yes Options to generate node-specific props from

useVisibleNodes()

A hook that observes to updates to the file tree and returns the nodes that are currently visible in the file tree.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree

⇗ Back to top


useNodePlugins()

A hook that observes to plugins and retrieves props that should be applied to a given node. An example of a plugin wouuld be the useTraits() hook. The <Node> component uses this under the hood.

Arguments

Name Type Required? Description
nodeId number Yes The node ID used to retrieve props from a plugin
plugins NodePlugin[] Yes A list of file tree plugins

NodePlugin

type NodePlugin<T = unknown> = {
  /**
   * A subject that the `useNodePlugins()` hook will observe to.
   */
  didChange: Subject<T>;
  /**
   * A function that returns React props based on a node ID.
   *
   * @param nodeId - The ID of a node in the file tree.
   */
  getProps(nodeId: number): React.HTMLAttributes<HTMLElement>;
};

⇗ Back to top


useFilter()

A hook that returns filtered visible nodes based on a filter function.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
filter ((node: FileTreeNode<Meta>, i: number) => boolean) | null Yes A stable callback (e.g. useCallback(() => {}, [])) that returns true if the node should be visible. This needs to be memoized or hoisted to the top level to ensure the filtered nodes only get re-generated when the filter changes or the file tree's visible nodes change.

⇗ Back to top


useTraits()

A plugin hook that allows you to arbitrarily apply traits/decorations to nodes in the file tree. For example, if you wanted to add a class name to a node in the tree if it were selected, focused, et. al. you could use this hook to do that. Another example would be the M modified decorations in VSCode.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
traits string[] Yes The list of available traits that can be applied to nodes

Returns UseTraitsPlugin

interface UseTraitsPlugin<Trait> {
  /**
   * A subject that you can use to observe to changes to traits.
   */
  didChange: Subject<Map<string, Set<number>>>;
  /**
   * Get the React props for a given node ID.
   *
   * @param nodeId - A node ID
   */
  getProps(nodeId: number): TraitsProps;
  /**
   * Adds a trait to given node IDs
   *
   * @param trait - The trait to apply to the given node IDs
   * @param nodeIds - Node IDs to add the traits to
   */
  add(trait: Extract<Trait, string>, ...nodeIds: number[]): void;
  /**
   * Sets node IDs to a given trait. This is different from add in
   * that it replaces any exist node IDs assigned to the trait.
   *
   * @param trait - The trait to apply to the given node IDs
   * @param nodeIds - Node IDs to add the traits to
   */
  set(trait: Extract<Trait, string>, nodeIds: number[]): void;
  /**
   * Deletes a node ID from a given trait
   *
   * @param trait - The trait
   * @param nodeId - The node ID to delete a trait for
   */
  delete(trait: Extract<Trait, string>, nodeId: number): void;
  /**
   * Clears all of the node IDs assigned to a given trait
   *
   * @param trait - The trait
   */
  clear(trait: Extract<Trait, string>): void;
  /**
   * Clears all of the node IDs assigned to all traits
   */
  clearAll(): void;
  /**
   * Clears the traits assigned to a given node ID
   *
   * @param nodeId - A node ID
   */
  clearNode(nodeId: number): void;
}

⇗ Back to top


useSelections()

A plugin hook for adding select and multi-select to the file tree.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
nodes number[] No When using a hook like useFilter you can supply the filtered list of nodes to this option. By default, useVirtualize() uses the nodes returned by useVisibleNodes()

Returns UseSelectionsPlugin

interface UseSelectionsPlugin {
  /**
   * A subject that you can use to observe to changes to selections.
   */
  didChange: Subject<Set<number>>;
  /**
   * Get the React props for a given node ID.
   *
   * @param nodeId - A node ID
   */
  getProps(nodeId: number): SelectionsProps;
  /**
   * The head of the selections list
   */
  get head(): number | null;
  /**
   * The tail of the selections list
   */
  get tail(): number | null;
  /**
   * Select given node ids
   *
   * @param nodeIds - Node IDs
   */
  select(...nodeIds: number[]): void;
  /**
   * Deselect given node ids
   *
   * @param nodeIds - Node IDs
   */
  deselect(...nodeIds: number[]): void;
  /**
   * Clear all of the selections
   */
  clear(): void;
  /**
   * A utility function that yields nodes from a set of selections if they
   * don't have a parent node in the set.
   *
   * @yields {number} - A node id
   */
  narrow(): Generator<number, void, unknown>;
}

⇗ Back to top


useDnd()

A plugin hook for adding drag and drop to the file tree.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
config UseDndConfig Yes A configuration object for the drag and drop plugin

Returns UseDndPlugin

interface UseDndPlugin {
  /**
   * A subject that emits drag 'n drop events.
   */
  didChange: Subject<DndEvent<any> | null>;
  /**
   * Get the drag 'n drop props for a given node ID.
   */
  getProps: (nodeId: number) => DndProps | React.HTMLAttributes<HTMLElement>;
}

UseDndConfig

interface UseDndConfig {
  /**
   * Timeout for expanding a directory when a draggable element enters it.
   */
  dragOverExpandTimeout?: number;
  /**
   * A React ref created by useRef() or an HTML element for the container viewport
   * you're rendering the list inside of.
   */
  windowRef: WindowRef;
}

⇗ Back to top


useRovingFocus()

A plugin hook for adding roving focus to file tree nodes.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree

Returns UseRovingFocusPlugin

interface UseRovingFocusPlugin {
  /**
   * A subject that you can use to observe to changes to the focused node.
   */
  didChange: Subject<number>;
  /**
   * Get the React props for a given node ID.
   *
   * @param nodeId - A node ID
   */
  getProps: (nodeId: number) => RovingFocusProps;
}

⇗ Back to top


useHotkeys()

A hook for adding standard hotkeys to the file tree.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
config UseHotkeysConfig No A configuration object for the hotkeys plugin

UseHotkeysConfig

interface UseHotkeysConfig {
  /**
   * When using a hook like `useFilter` you can supply the filtered list of
   * nodes to this option. By default, `useVirtualize()` uses the nodes returned
   * by `useVisibleNodes()`
   */
  nodes?: number[];
  /**
   * A React ref created by useRef() or an HTML element for the container viewport
   * you're rendering the list inside of.
   */
  windowRef: WindowRef;
  /**
   * The returned value of the `useRovingFocus()` plugin
   */
  rovingFocus: ReturnType<typeof useRovingFocus>;
  /**
   * The returned value of the `useSelections()` plugin
   */
  selections: ReturnType<typeof useSelections>;
  /**
   * A pattern to use for selecting the elements in the list. Must contain an
   * `{index}` placeholder for the index of the element to select.
   */
  querySelectorPattern?: string;
}

⇗ Back to top


useObserver()

A hook for observing changes to the value of a subject.

Arguments

Name Type Required? Description
subject Subject Yes A subject to observe
observer (value: T) => void | (() => void) Yes A callback that is invoked when the subject changes

⇗ Back to top


useFileTreeSnapshot()

Take a snapshot of the expanded and buried directories of a file tree. This snapshot can be used to restore the expanded/collapsed state of the file tree when you initially load it.

Arguments

Name Type Required? Description
fileTree FileTree<Meta> Yes A file tree
observer (state: FileTreeSnapshot) => Promise<void> | void Yes A callback that handles the file tree snapshot

⇗ Back to top


Low-level API

FileTree()

Properties

Name Type Description
root number The root directory of the file tree.
comparator Dir<Meta> The comparator used for sorting the file tree.
visibleNodes FileTreeNode<Meta> The nodes that are currently visible.

Methods

Name Description
getById Get a node by its ID.
getByPath Get a node by its path. Note that this requires walking the tree, which has O(n) complexity.
walk Walks the tree starting at a given directory and calls a visitor function for each node.
expand Expand a directory in the tree.
collapse Collapse a directory in the tree.
remove Remove a node and its descendants from the tree.
invalidate Invalidate the list of visible nodes. This is useful for re-rendering your tree when node data changes.
produce Produce a new tree with the given function applied to the given node. This is similar to immer's produce function as you're working on a draft and can freely mutate the object.
move Move a node to a new parent.
newFile Create a new file in a given directory.
newDir Create a new directory in a given directory.
newPrompt Create a new prompt in a given directory.
rename Rename a node.
isExpanded A more accurate and real-time representation of whether a branch is expanded. Dir#expanded represents the "optimistic" expansion state of the branch in question not the actual status, because the child nodes might still need to be loaded before the change can be seen in the tree.
isVisible Returns true if the node and its parents are visible in the tree.
loadNodes You can use this method to manually trigger a reload of a directory in the tree.

FileTreeData

type FileTreeData<Meta = {}> = {
  name: string;
  meta?: Meta;
};

⇗ Back to top


Dir()

A class for creating a directory node.

Arguments

Name Type Required? Description
parent Dir<Meta> Yes The parent node
data FileTreeData<Meta> Yes The node data
expanded boolean No Whether the node is expanded or not, defaults to false. This is an optimistic property, so when it is true its descendants may not be fully loaded yet. To get the more accurate representation, use FileTree#isExpanded.

Properties

Name Type Description
parentId number The ID of the parent node.
parent Dir<Meta> The parent node.
basename string The basename of the directory.
path string The full path of the directory.
expanded boolean true if the directory is expanded.
data FileTreeData<Meta> The node data

Methods

Name Description
contains Returns true if the node is a descendant of this directory.

⇗ Back to top


File()

A class for creating a file node.

Arguments

Name Type Required? Description
parent Dir<NodeData> Yes The parent node
data FileTreeData<Meta> Yes The node data

Properties

Name Type Description
parentId number The ID of the parent node.
parent Dir<Meta> The parent node.
basename string The basename of the directory.
path string The full path of the directory.
data FileTreeData<Meta> The node data

⇗ Back to top


Prompt()

A class for creating a prompt node.

Arguments

Name Type Required? Description
parent Dir<NodeData> Yes The parent node

Properties

Name Type Description
parentId number The ID of the parent node.
parent Dir<Meta> The parent node.
path string The full path of the prompt.
basename string The base name of prompts is always an empty string.

⇗ Back to top


isDir()

Returns true if the given node is a directory

Arguments

Name Type Required? Description
treeNode FileTreeNode<T> Yes A file tree node

⇗ Back to top


isFile()

Returns true if the given node is a file

Arguments

Name Type Required? Description
treeNode FileTreeNode<T> Yes A file tree node

⇗ Back to top


isPrompt()

Returns true if the given node is a prompt

Arguments

Name Type Required? Description
treeNode FileTreeNode<T> Yes A file tree node

⇗ Back to top


subject()

A utility for creating a subject as part of the observer pattern.

Arguments

Name Type Required? Description
initialState T Yes The initial state of the subject.

Returns Subject

export type Subject<T> = {
  /**
   * Emit a new state.
   *
   * @param state - The new state
   */
  setState(state: T): void;
  /**
   * Get the current state.
   */
  getState(): T;
  /**
   * Observe changes to the state.
   *
   * @param observer - A callback that is invoked when the value changes
   */
  observe(observer: Observer<T>): () => void;
  /**
   * Remove a observer from the list of observers
   *
   * @param observer - A callback that is invoked when the value changes
   */
  unobserve(observer: Observer<T>): void;
};

type Observer<T> = {
  (state: T): void;
};

⇗ Back to top


mergeProps()

Merges multiple props objects together. Event handlers are chained, classNames are combined, and styles are combined.

For all other props, the last prop object overrides all previous ones.

Arguments

Name Type Required? Description
args {[key: string]: any;}[] Yes Multiple sets of props to merge together.

⇗ Back to top


retryWithBackoff()

Retry a promise until it resolves or the max number of retries is reached.

Arguments

Name Type Required? Description
promiseFn () => Promise<T> Yes A function that returns a promise to retry when it fails
config RetryWithBackoffConfig No Configuration options

RetryWithBackoffConfig

interface RetryWithBackoffConfig {
  /**
   * Max number of retries
   *
   * @default 4
   */
  maxRetries?: number;
  /**
   * Initial delay before first retry
   *
   * @default 100
   */
  initialDelay?: number;
  /**
   * Multiplier for each subsequent retry
   *
   * @default 2
   */
  delayMultiple?: number;
  /**
   * A function that should return `false` to stop retrying
   *
   * @param error - The error that caused the retry
   */
  shouldRetry?: (error: unknown) => boolean;
}

⇗ Back to top


Path utilities

Utilities for unix-style paths

pathFx.join()

Join all arguments together and normalize the resulting path.

Arguments

Name Type Required? Description
paths string[] Yes Paths to join

⇗ Back to top


pathFx.relative()

Solve the relative path from from to to. Paths must be absolute.

Arguments

Name Type Required? Description
from string Yes The absolute path to start from
to string Yes The absolute path to solve to

⇗ Back to top


pathFx.split()

Splits a path into an array of path segments.

Arguments

Name Type Required? Description
path string Yes The path to split.

⇗ Back to top


pathFx.normalize()

Normalize a path, taking care of .. and ., and removing redundant slashes while preserving trailing slashes.

Arguments

Name Type Required? Description
path string Yes The path to normalize.

⇗ Back to top


pathFx.depth()

Get the depth of a path.

Arguments

Name Type Required? Description
path string Yest The path to split.

⇗ Back to top


pathFx.basename()

Return the last fragment of a path.

Arguments

Name Type Required? Description
path string Yes The path to get the basename of.

⇗ Back to top


pathFx.dirname()

Return the directory name of a path.

Arguments

Name Type Required? Description
path string Yes The path to get the directory name of.

⇗ Back to top


pathFx.extname()

Returns the extension of a file path, which is the part of the path after the last .. If the path has no extension, returns an empty string.

Arguments

Name Type Required? Description
path string Yes The path to get the extension of.

⇗ Back to top


pathFx.isRelative()

Returns true if the path is relative.

Arguments

Name Type Required? Description
path string Yes The path to check.

⇗ Back to top


pathFx.isPathInside()

Returns true if path is inside dir.

Arguments

Name Type Required? Description
path string Yes The path to check
dir string Yes The directory to check if the path is inside of

⇗ Back to top


pathFx.removeTrailingSlashes()

Remove any trailing slashes from a path.

Arguments

Name Type Required? Description
path string Yes The path to remove trailing slashes from.

⇗ Back to top


LICENSE

MIT