exploration v1.6.0

Exploration

Primitives for creating high performance file explorers with React

npm i exploration

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

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

UseVirtualizeConfig

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

⇗ Back to top

useNode()

A plugin that creates and memoizes node-specific props.

Arguments

useVisibleNodes()

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

Arguments

⇗ 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

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

⇗ 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

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

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

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

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

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

⇗ 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

⇗ Back to top

Low-level API

FileTree()

Properties

Methods

FileTreeData

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

⇗ Back to top

Dir()

A class for creating a directory node.

Arguments

Properties

Methods

⇗ Back to top

File()

A class for creating a file node.

Arguments

Properties

⇗ Back to top

Prompt()

A class for creating a prompt node.

Arguments

Properties

⇗ Back to top

isDir()

Returns true if the given node is a directory

Arguments

⇗ Back to top

isFile()

Returns true if the given node is a file

Arguments

⇗ Back to top

isPrompt()

Returns true if the given node is a prompt

Arguments

⇗ Back to top

subject()

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

Arguments

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

⇗ Back to top

retryWithBackoff()

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

Arguments

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

⇗ Back to top

pathFx.relative()

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

Arguments

⇗ Back to top

pathFx.split()

Splits a path into an array of path segments.

Arguments

⇗ Back to top

pathFx.normalize()

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

Arguments

⇗ Back to top

pathFx.depth()

Get the depth of a path.

Arguments

⇗ Back to top

pathFx.basename()

Return the last fragment of a path.

Arguments

⇗ Back to top

pathFx.dirname()

Return the directory name of a path.

Arguments

⇗ 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

⇗ Back to top

pathFx.isRelative()

Returns true if the path is relative.

Arguments

⇗ Back to top

pathFx.isPathInside()

Returns true if path is inside dir.

Arguments

⇗ Back to top

pathFx.removeTrailingSlashes()

Remove any trailing slashes from a path.

Arguments

⇗ Back to top

LICENSE

MIT