MingaEditor.State.FileTree (Minga v0.1.0)

File tree sub-state: tree data, focus, and backing buffer.

Wraps the file-tree-related fields from EditorState into a single struct with query and mutation helpers. Includes inline editing state for new file, new folder, and rename operations.

Summary

Types

clipboard_mark()

clipboard_operation()

editing()

editing_type()

Inline editing state for creating files/folders or renaming entries.

filter_request()

Identity of the latest admitted filter request.

t()

File tree sub-state.

tree_status()

Explicit presentation state for the file tree sidebar.

Functions

accept_filter(ft)

Accepts the current filter and leaves the narrowed tree visible.

accept_filter_result(ft, root, filter, token, result)

Installs a current filter result prepared by a scheduler worker.

accept_refresh_result(ft, root, token, refreshed_tree)

Atomically accepts a current refresh result or identifies why it cannot apply.

accept_watcher_result(ft, token, target)

Collapses watcher lineage only for the latest exact successful request.

begin_root_scan(ft, tree, kind)

Publishes an immediate loading tree for a root scan without resolving entries.

cancel_editing(ft)

Cancels inline editing, clearing the editing state back to nil.

cleanup_watchers(ft)

Changes the watcher target to cleanup-only while retaining all known roots.

clear_clipboard(ft)

Clears a pending file tree clipboard operation.

clear_filter_loading(ft, disposition)

Publishes an unfiltered loading tree while preserving filter-input disposition.

close(ft)

Closes the tree and clears the buffer.

editing?(file_tree)

Returns true when inline editing is active.

error(ft, reason)

Marks the sidebar as failed with a displayable reason.

exhaust_watcher_retry(ft)

Terminalizes watcher retry correlation after the bounded attempt budget.

filter_failed(ft, reason)

Reports a current filter failure while preserving recovery on the next query.

finish_filter(ft, root, filter, token)

Finishes a current failed or canceled filter request without installing rows.

finish_refresh(ft, root, token)

Finishes a failed or canceled current request without changing tree content.

finish_watcher_request(ft, token)

Finishes watcher work without discarding cleanup candidates.

focus(ft)

Marks the file tree as focused.

focused?(file_tree)

Returns true when the file tree is open and focused.

hide(ft)

Hides the sidebar while keeping the loaded tree, backing buffer, and watchers.

hide_help(ft)

Hides the file tree help overlay.

loaded?(file_tree)

Returns true when the file tree has loaded data.

loading(ft)

Marks the sidebar as loading.

mark_clipboard(ft, path, name, dir?, operation)

Stores a pending file tree clipboard operation.

open(ft, tree, buffer)

Opens the tree with the given data, buffer, and focused state.

refresh_debounce_elapsed(ft, token)

Consumes a correlated debounce message and focuses the result on the live tree.

refresh_failed(ft, reason)

Reports a refresh failure while preserving the open tree interaction state.

replace_tree(ft, tree)

Replaces the backing tree and refreshes the presentation status.

replace_tree_metadata(ft, tree)

Replaces metadata on the current tree without changing topology status or refresh correlation.

request_refresh_debounce(ft, token)

Records one debounced request to refresh the open tree.

root_generation(ft)

Returns the monotonic generation of the current root and watcher lineage.

root_scan_failed(ft, reason)

Installs an empty failed root scan while retaining the requested root.

schedule_watcher_retry(ft, token)

Correlates a bounded watcher synchronization retry.

set_project_root(ft, root)

Updates the project root associated with the file tree.

set_tree(ft, tree)

Replaces the tree data.

show(ft)

Reveals a previously hidden tree and refocuses it.

start_editing(ft, index, type, initial_text \\ "")

Enters inline editing mode at the given index.

start_filtering(ft)

Starts inline file tree filtering without resolving any rows.

status(ft)

Returns the explicit presentation status for the file tree.

toggle_help(ft)

Toggles the file tree help overlay.

track_filter_request(ft, root, filter, token)

Correlates the latest admitted filter request with its exact root and query.

track_refresh_request(ft, root, token)

Correlates an admitted typed refresh request with the root it scans.

track_refresh_retry(ft, token)

Re-arms one pending refresh intent after scheduler admission pressure.

track_watcher_request(ft, token)

Correlates the latest admitted watcher synchronization request.

unfocus(ft)

Marks the file tree as unfocused.

update_editing_text(ft, new_text)

Updates the text being typed in the inline editor.

update_filter(ft, filter)

Publishes a loading filter transition without cache or filesystem calls.

visible?(ft)

Returns true when the sidebar is currently visible (loaded and not hidden).

visible_status?(arg1)

Returns true when the explicit tree status should occupy the sidebar.

watcher_intent(ft)

Returns the immutable watcher intent owned by this file tree.

watcher_retry_elapsed(ft, token)

Consumes only the current watcher retry timer.

width(file_tree)

Returns the tree width, preserving the last sidebar width while state-only payloads are visible.

Types

clipboard_mark()

@type clipboard_mark() :: MingaEditor.State.FileTree.ClipboardMark.t()

clipboard_operation()

@type clipboard_operation() :: MingaEditor.State.FileTree.ClipboardMark.operation()

editing()

@type editing() :: %{
  index: non_neg_integer(),
  text: String.t(),
  type: editing_type(),
  original_name: String.t() | nil
}

editing_type()

@type editing_type() :: :new_file | :new_folder | :rename

Inline editing state for creating files/folders or renaming entries.

When non-nil, the user is actively typing a filename in the tree. The index is the visual position in the visible entry list where the editing row appears. For new file/folder, this is the insertion point. For rename, this is the entry being renamed.

filter_request()

@type filter_request() :: %{root: String.t(), filter: String.t(), token: reference()}

Identity of the latest admitted filter request.

t()

@type t() :: %MingaEditor.State.FileTree{
  buffer: pid() | nil,
  clipboard_mark: clipboard_mark() | nil,
  editing: editing() | nil,
  filter_request: filter_request() | nil,
  filtering: boolean(),
  focused: boolean(),
  help_visible: boolean(),
  hidden: boolean(),
  original_root: String.t() | nil,
  project_root: String.t() | nil,
  refresh: MingaEditor.State.FileTree.Refresh.t(),
  tree: Minga.Project.FileTree.t() | nil,
  tree_status: tree_status(),
  tree_width: pos_integer(),
  watchers: MingaEditor.State.FileTree.Watchers.t()
}

File tree sub-state.

tree_status()

@type tree_status() :: :hidden | :loading | :empty | :ready | {:error, String.t()}

Explicit presentation state for the file tree sidebar.

Functions

accept_filter(ft)

@spec accept_filter(t()) :: t()

Accepts the current filter and leaves the narrowed tree visible.

accept_filter_result(ft, root, filter, token, result)

@spec accept_filter_result(
  t(),
  String.t(),
  String.t(),
  reference(),
  MingaEditor.FileTree.FilterWalk.Result.t()
) :: {:accepted | :closed | :rerooted | :stale, t()}

Installs a current filter result prepared by a scheduler worker.

accept_refresh_result(ft, root, token, refreshed_tree)

@spec accept_refresh_result(
  t(),
  String.t(),
  MingaEditor.State.FileTree.Refresh.request_token(),
  Minga.Project.FileTree.t()
) :: {:accepted | :closed | :rerooted | :stale, t()}

Atomically accepts a current refresh result or identifies why it cannot apply.

accept_watcher_result(ft, token, target)

@spec accept_watcher_result(t(), reference(), String.t() | nil) ::
  {:current | :stale, t()}

Collapses watcher lineage only for the latest exact successful request.

begin_root_scan(ft, tree, kind)

@spec begin_root_scan(t(), Minga.Project.FileTree.t(), :project | :reroot) :: t()

Publishes an immediate loading tree for a root scan without resolving entries.

cancel_editing(ft)

@spec cancel_editing(t()) :: t()

Cancels inline editing, clearing the editing state back to nil.

cleanup_watchers(ft)

@spec cleanup_watchers(t()) :: t()

Changes the watcher target to cleanup-only while retaining all known roots.

clear_clipboard(ft)

@spec clear_clipboard(t()) :: t()

Clears a pending file tree clipboard operation.

clear_filter_loading(ft, disposition)

@spec clear_filter_loading(t(), :keep_open | :dismiss) :: t()

Publishes an unfiltered loading tree while preserving filter-input disposition.

close(ft)

@spec close(t()) :: t()

Closes the tree and clears the buffer.

editing?(file_tree)

@spec editing?(t()) :: boolean()

Returns true when inline editing is active.

error(ft, reason)

@spec error(t(), term()) :: t()

Marks the sidebar as failed with a displayable reason.

exhaust_watcher_retry(ft)

@spec exhaust_watcher_retry(t()) :: t()

Terminalizes watcher retry correlation after the bounded attempt budget.

filter_failed(ft, reason)

@spec filter_failed(t(), term()) :: t()

Reports a current filter failure while preserving recovery on the next query.

finish_filter(ft, root, filter, token)

@spec finish_filter(t(), String.t(), String.t(), reference()) ::
  {:current | :closed | :rerooted | :stale, t()}

Finishes a current failed or canceled filter request without installing rows.

finish_refresh(ft, root, token)

@spec finish_refresh(
  t(),
  String.t(),
  MingaEditor.State.FileTree.Refresh.request_token()
) ::
  {:current | :closed | :rerooted | :stale, t()}

Finishes a failed or canceled current request without changing tree content.

finish_watcher_request(ft, token)

@spec finish_watcher_request(t(), reference()) :: {:current | :stale, t()}

Finishes watcher work without discarding cleanup candidates.

focus(ft)

@spec focus(t()) :: t()

Marks the file tree as focused.

focused?(file_tree)

@spec focused?(t()) :: boolean()

Returns true when the file tree is open and focused.

hide(ft)

@spec hide(t()) :: t()

Hides the sidebar while keeping the loaded tree, backing buffer, and watchers.

Toggling visibility off is a pure layout change: the render model still carries the full tree data so showing it again does not rebuild anything (#2626).

hide_help(ft)

@spec hide_help(t()) :: t()

Hides the file tree help overlay.

loaded?(file_tree)

@spec loaded?(t()) :: boolean()

Returns true when the file tree has loaded data.

A hidden-but-loaded tree is still loaded: the data, buffer, and watchers stay alive so refresh handlers keep it fresh. This is intentionally NOT "is the sidebar visible" — use visible?/1 for that. Mixing the two leaks the backing buffer (see #2626).

loading(ft)

@spec loading(t()) :: t()

Marks the sidebar as loading.

mark_clipboard(ft, path, name, dir?, operation)

@spec mark_clipboard(t(), String.t(), String.t(), boolean(), clipboard_operation()) ::
  t()

Stores a pending file tree clipboard operation.

open(ft, tree, buffer)

@spec open(t(), Minga.Project.FileTree.t(), pid() | nil) :: t()

Opens the tree with the given data, buffer, and focused state.

refresh_debounce_elapsed(ft, token)

@spec refresh_debounce_elapsed(
  t(),
  MingaEditor.State.FileTree.Refresh.debounce_token()
) ::
  {:ready, Minga.Project.FileTree.t(), t()} | {:closed | :stale, t()}

Consumes a correlated debounce message and focuses the result on the live tree.

refresh_failed(ft, reason)

@spec refresh_failed(t(), term()) :: t()

Reports a refresh failure while preserving the open tree interaction state.

replace_tree(ft, tree)

@spec replace_tree(t(), Minga.Project.FileTree.t()) :: t()

Replaces the backing tree and refreshes the presentation status.

replace_tree_metadata(ft, tree)

@spec replace_tree_metadata(t(), Minga.Project.FileTree.t()) :: t()

Replaces metadata on the current tree without changing topology status or refresh correlation.

request_refresh_debounce(ft, token)

@spec request_refresh_debounce(
  t(),
  MingaEditor.State.FileTree.Refresh.debounce_token()
) ::
  {:scheduled | :already_scheduled, t()}

Records one debounced request to refresh the open tree.

root_generation(ft)

@spec root_generation(t()) :: non_neg_integer()

Returns the monotonic generation of the current root and watcher lineage.

root_scan_failed(ft, reason)

@spec root_scan_failed(t(), term()) :: t()

Installs an empty failed root scan while retaining the requested root.

schedule_watcher_retry(ft, token)

@spec schedule_watcher_retry(t(), reference()) :: {pos_integer(), t()}

Correlates a bounded watcher synchronization retry.

set_project_root(ft, root)

@spec set_project_root(t(), String.t() | nil) :: t()

Updates the project root associated with the file tree.

set_tree(ft, tree)

@spec set_tree(t(), Minga.Project.FileTree.t() | nil) :: t()

Replaces the tree data.

show(ft)

@spec show(t()) :: t()

Reveals a previously hidden tree and refocuses it.

start_editing(ft, index, type, initial_text \\ "")

@spec start_editing(t(), non_neg_integer(), editing_type(), String.t()) :: t()

Enters inline editing mode at the given index.

For new file/folder, initial_text is empty. For rename, initial_text is the current entry name.

start_filtering(ft)

@spec start_filtering(t()) :: t()

Starts inline file tree filtering without resolving any rows.

status(ft)

@spec status(t()) :: tree_status()

Returns the explicit presentation status for the file tree.

toggle_help(ft)

@spec toggle_help(t()) :: t()

Toggles the file tree help overlay.

track_filter_request(ft, root, filter, token)

@spec track_filter_request(t(), String.t(), String.t(), reference()) :: t()

Correlates the latest admitted filter request with its exact root and query.

track_refresh_request(ft, root, token)

@spec track_refresh_request(
  t(),
  String.t(),
  MingaEditor.State.FileTree.Refresh.request_token()
) :: t()

Correlates an admitted typed refresh request with the root it scans.

track_refresh_retry(ft, token)

@spec track_refresh_retry(t(), MingaEditor.State.FileTree.Refresh.debounce_token()) ::
  {pos_integer(), t()}

Re-arms one pending refresh intent after scheduler admission pressure.

track_watcher_request(ft, token)

@spec track_watcher_request(t(), reference()) :: t()

Correlates the latest admitted watcher synchronization request.

unfocus(ft)

@spec unfocus(t()) :: t()

Marks the file tree as unfocused.

update_editing_text(ft, new_text)

@spec update_editing_text(t(), String.t()) :: t()

Updates the text being typed in the inline editor.

update_filter(ft, filter)

@spec update_filter(t(), String.t()) :: t()

Publishes a loading filter transition without cache or filesystem calls.

visible?(ft)

@spec visible?(t()) :: boolean()

Returns true when the sidebar is currently visible (loaded and not hidden).

visible_status?(arg1)

@spec visible_status?(tree_status()) :: boolean()

Returns true when the explicit tree status should occupy the sidebar.

watcher_intent(ft)

@spec watcher_intent(t()) :: MingaEditor.State.FileTree.Watchers.t()

Returns the immutable watcher intent owned by this file tree.

watcher_retry_elapsed(ft, token)

@spec watcher_retry_elapsed(t(), reference()) :: {:current | :stale, t()}

Consumes only the current watcher retry timer.

width(file_tree)

@spec width(t()) :: pos_integer()

Returns the tree width, preserving the last sidebar width while state-only payloads are visible.