docs(workspace): document lazy tree loading
This commit is contained in:
parent
ab545ef18b
commit
1801f44f86
2 changed files with 35 additions and 3 deletions
|
|
@ -18,7 +18,7 @@ Sapling is organized as a Swift Package with an executable app target and focuse
|
|||
|
||||
The Git layer is protocol-first because macOS and iOS need different implementations. `MacGitProvider` uses the system `git` binary behind the `GitProvider` and `Repository` protocols. `EmbeddedGitProvider` is intentionally stubbed as the future iOS-compatible implementation point. `MockGitProvider` is used by the initial app shell and previews/tests so UI work is not coupled to local repositories.
|
||||
|
||||
Workspaces are local containers and are not versioned. Projects are Git repositories, while subprojects model Git submodules. Workspace contents are derived from the filesystem rather than a Sapling-owned manifest or database. This distinction is represented in `SaplingCore` so business rules remain shared across macOS and future iOS targets.
|
||||
Workspaces are local containers and are not versioned. Projects are Git repositories, while subprojects model Git submodules. Workspace contents are derived lazily from the filesystem rather than a Sapling-owned manifest or database. This distinction is represented in `SaplingCore` so business rules remain shared across macOS and future iOS targets.
|
||||
|
||||
The editor follows an MVVM shape. `HybridMarkdownEditorViewModel` owns document editing state, while `HybridMarkdownEditor` renders the active line as source and inactive lines as rendered Markdown. `DocumentSessionStore` keeps open document sessions separate from the workspace tree so opening the same file activates the existing editor state instead of creating a duplicate. The renderer is injected through `MarkdownRendering` so the current lightweight parser can later be replaced with a richer Markdown/LaTeX/Mermaid pipeline.
|
||||
|
||||
|
|
|
|||
|
|
@ -8,11 +8,11 @@ A workspace is a folder on disk.
|
|||
|
||||
Sapling does not create workspace manifests, project registries, content databases, or any other authoritative copy of workspace contents. The application may persist UI and application settings, such as the last opened workspace path, but the filesystem remains the source of truth for folders, files, and projects.
|
||||
|
||||
Workspace contents are discovered by scanning the selected root directory and building an in-memory tree. That tree can be rebuilt at any time from the filesystem.
|
||||
Workspace contents are discovered from the selected root directory and kept as an in-memory presentation tree. That tree can be rebuilt from the filesystem.
|
||||
|
||||
## Filesystem Scanning
|
||||
|
||||
`LocalWorkspaceManager` recursively scans the workspace root and derives:
|
||||
`LocalWorkspaceManager` scans one directory level at a time and derives:
|
||||
|
||||
- folders from directories
|
||||
- files from regular filesystem items
|
||||
|
|
@ -22,6 +22,24 @@ Hidden files and `.git` internals are excluded from the visible tree. Project di
|
|||
|
||||
The scanner performs no Git operations. Repository detection is based only on filesystem metadata.
|
||||
|
||||
## Lazy Discovery
|
||||
|
||||
Workspace opening loads only the root directory level. Folder and project children are loaded when the user expands that tree node.
|
||||
|
||||
```text
|
||||
Open Workspace
|
||||
-> scan root directory only
|
||||
-> display root items
|
||||
-> expand folder
|
||||
-> scan that folder only
|
||||
```
|
||||
|
||||
Collapsed folders do no filesystem work. Previously, eager recursive scanning made initial workspace opening and large folder expansion feel slow because large portions of the workspace were discovered before the user asked to see them. The lazy strategy keeps initial display bounded by the size of the root directory and moves deeper discovery to explicit expansion.
|
||||
|
||||
The application model stores loaded children by standardized folder URL. This cache is UI state, not authoritative workspace metadata. If the tree needs to be refreshed, it can be rebuilt from the filesystem.
|
||||
|
||||
Filesystem scanning is dispatched away from the main actor so the UI can show loading feedback immediately.
|
||||
|
||||
## Workspace Tree
|
||||
|
||||
The workspace tree answers:
|
||||
|
|
@ -32,6 +50,20 @@ It represents the current filesystem hierarchy and should not own editor state,
|
|||
|
||||
The sidebar uses the derived tree to display folders, Markdown files, other files, and Git-backed projects. Folder and project nodes are collapsible so large hierarchies can be browsed incrementally.
|
||||
|
||||
Expanding a folder shows a lightweight loading row while that directory is scanned. Tree insertion animations are disabled because large animated insertions made expansion feel slower and visually noisy.
|
||||
|
||||
Rows are sorted with folders and projects first, then files. Each group uses localized alphabetical ordering. Git repositories participate in folder ordering but keep project styling.
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
Docs
|
||||
Sapling
|
||||
Tests
|
||||
README.md
|
||||
ROADMAP.md
|
||||
```
|
||||
|
||||
## Document Sessions
|
||||
|
||||
Document sessions answer:
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue