files-explorer-tree

name	files-explorer-tree
description	Practical guide for the current Files sidebar (`@headless-tree` + Convex) implementation. Use this when implementing or modifying sidebar behavior (search, selection, drag/drop, rename, archive/unarchive, create file/folder, and root-drop-zone interactions).

Source Of Truth Files

Primary:

• ../../../packages/app/src/routes/w/$workspaceName/$projectName/files/-components/files-sidebar.tsx
• ../../../packages/app/src/routes/w/$workspaceName/$projectName/files/-components/files-sidebar.css
• ../../../packages/app/src/routes/w/$workspaceName/$projectName/files/index.tsx
• ../../../packages/app/convex/files_nodes.ts
• ../../../packages/app/shared/files.ts
• ../../../packages/app/src/lib/files.ts
• ../../../packages/app/vendor/headless-tree/packages/core/src/index.ts
• ../../../packages/app/vendor/headless-tree/packages/react/src/index.ts
• ../../../packages/app/vendor/headless-tree/packages/react/src/react-compiler/index.tsx

Architecture Overview

The Files sidebar is implemented in files-sidebar.tsx on top of @headless-tree with Convex-backed data.

• Tree engine: @headless-tree/core + @headless-tree/react
• Backend data: Convex files query/mutations
• Primary data source: files.get_tree_nodes_list
• Local state is UI-only (expandedItems, search/selection, busy/pending flags) plus derived indexes from query data
• Prefer Convex mutation optimisticUpdate over ad-hoc local mirrored tree state
• Backend item types: "root" | "node"
• Node kinds: "folder" | "file"
• Placeholder rows are UI-only render artifacts

Data Model And Contracts

• files_TreeItem shape is defined in ../../../packages/app/convex/files_nodes.ts.
• files_ROOT_ID and files_create_tree_root are in ../../../packages/app/shared/files.ts and re-exported by ../../../packages/app/src/lib/files.ts.
• Backend returns root/node items only; placeholder rows are client-rendered.
• Folder nodes can have children, expand/collapse, and receive drops.
• File nodes are leaves and open in the editor.
• Clicking a folder opens its folder screen. FileNodeView decides whether the selected node renders the folder explorer or the file editor, and folder screens embed an editable child README.md when present.

Main Components

Main component:

• FilesSidebar (name retained to avoid a large route/component rename)
• FileNodeView owns the files route shell, sidebar panel, app-header breadcrumb, folder explorer branch, and file editor branch.

Main sections:

• FilesSidebarHeader
• FilesSidebarSearch
• FilesSidebarTree

Tree-item components:

• FilesSidebarTreeItem
• FilesSidebarTreeItemArrow
• FilesSidebarTreeItemTitle
• FilesSidebarTreeItemIcon
• FilesSidebarTreeItemPrimaryContent
• FilesSidebarTreeItemPrimaryAction
• FilesSidebarTreeItemMetaLabel
• FilesSidebarTreeItemActions
• FilesSidebarTreeItemSecondaryAction
• FilesSidebarTreeItemSecondaryActionCreateFile
• FilesSidebarTreeItemMoreAction
• FilesSidebarTreeItemTrack
• FilesSidebarTreeItemPlaceholder

State And Behavior Flows

Server-Driven Data

• Sidebar queries files.get_tree_nodes_list.
• Tree collection maps/sets are derived from query results (useMemo) and rebuilt from server data.
• Loading/empty states are derived from query presence and visible IDs.

Search

• Search input is debounced and consumed through a deferred query value.
• Visible IDs are computed from title matches plus ancestor chain inclusion.
• Ancestors of matched files/folders remain visible.
• Search-open snapshots expansion state and auto-expands relevant parents; search-close restores prior expansion.

Selection And Primary Action

• Primary click implements single select, toggle-select, and shift-range.
• Non-modifier click runs primary action for node items.
• File primary action navigates to the file.
• Folder primary action navigates to the folder screen.
• In multi-select mode, selection anchor files active track highlighting.

Create, Rename, Archive, Unarchive

• Root actions create New File and New Folder.
• Folder row actions can create child files and folders.
• File rows do not show child-creation actions.
• Default generated names are sibling-aware: new-file.md, new-file-2.md, new-folder, new-folder-2.
• File and folder create support path-like names: missing parent folders are created first, then the final file/folder is created at that path.
• File create/rename input canonicalizes path segments in the frontend; backend path creation trusts those segments and only rejects an empty path.
• Rename input filters draft typing/paste/composition through shared live-name normalization: files allow lowercase letters, digits, /, ., -, _; folders allow lowercase letters, digits, /, -, _; adjacent separators are blocked while typing; special file-name casing remains submit-time only.
• File and folder create/rename reject double-dot names; file names with a non-empty basename and a trailing dot are treated as missing the extension, while invalid extension text such as separators inside the final extension is rejected.
• File create/rename then applies the Markdown storage contract: extensionless file names get .md, and explicit alternate extensions are replaced with .md.
• File create/rename applies special file-name casing after normalization: readme, readme.md, and README.md store as README.md.
• File rename selects the basename by default so .md is not included in the initial edit selection.
• Rename uses files.rename_node with Convex optimisticUpdate for immediate title feedback.
• The selected file/folder path auto-expands in the sidebar after route changes and path-based create/rename moves so the focused row stays visible.
• Archive/unarchive uses files.archive_nodes / files.unarchive_nodes.

Drag And Drop

• In-tree DnD uses headless-tree onDrop -> files.move_nodes.
• canDrop guards target kind, self-drop, and descendant-drop.
• Root and folders can receive drops.
• Files cannot receive drops.

Headless-Tree Configuration Highlights

useTree<files_TreeItem> configuration includes:

• rootItemId: files_ROOT_ID
• controlled expandedItems + setExpandedItems
• canReorder: false
• sync data loader + selection + hotkeys + DnD + renaming + expand-all + click behavior + prop memoization features
• node-only canDrag and canRename
• folder-only isItemFolder
• guarded canDrop

Architectural Invariants

1. Keep placeholder behavior client-only and non-mutable.
2. Keep tree record data server-driven from Convex query; do not introduce local mirror/fallback state.
3. Preserve ancestor-aware search visibility and search expansion-restore behavior.
4. Preserve custom selection semantics and selection-anchor behavior.
5. Keep DnD safety guards (self/descendant/kind) and root-zone feedback behavior.
6. Keep pending state split (isBusy and pendingActionNodeIds) for correct UI gating.
7. Prefer Convex optimistic updates over manual local tree patching.
8. Do not let file nodes act as folders.

Verification Checklist

• Tree updates come from get_tree_nodes_list.
• Search keeps ancestor chain for matching files/folders.
• Search-open expands relevant branches and search-close restores prior expansion.
• Selection modes and anchor behavior are correct.
• Root create can create a file and a folder.
• Folder create can create child files/folders.
• File rows do not show child creation actions and are not expandable.
• Rename guards and optimistic rename behavior are correct.
• Archive/unarchive and archived filter/toggle behavior is correct.
• DnD allows legal moves, blocks drops onto files, and root-zone feedback works.
• Placeholder nodes are never sent to mutations.