docs(quick-1): plan arrow key navigation and directory descriptions

2026-03-01 11:37:19 +01:00
parent 2e0c9d2277
commit 67509c3863
1 changed files with 149 additions and 0 deletions
@@ -0,0 +1,149 @@
+---
+phase: quick-1
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - src/app.rs
+  - src/vault.rs
+autonomous: true
+requirements: [ARROW-NAV, DIR-DESC]
+
+must_haves:
+  truths:
+    - "Bare Left arrow navigates back in history (same as Backspace)"
+    - "Bare Right arrow navigates forward in history (same as Alt+Right)"
+    - "Up/Down arrows already scroll (no change needed, just verify)"
+    - "Directory listing shows description text beside each file entry"
+    - "Descriptions come from YAML frontmatter 'description' field in .md files"
+    - "Descriptions are truncated to fit available terminal width"
+  artifacts:
+    - path: "src/app.rs"
+      provides: "Arrow key bindings + description display in build_directory_lines"
+      contains: "KeyCode::Left"
+    - path: "src/vault.rs"
+      provides: "DirEntry with description field, frontmatter parsing"
+      contains: "description"
+  key_links:
+    - from: "src/vault.rs"
+      to: "src/app.rs"
+      via: "DirEntry.description field consumed by build_directory_lines()"
+      pattern: "entry\\.description"
+---
+
+<objective>
+Add bare arrow key navigation (Left=back, Right=forward) and show YAML frontmatter descriptions beside files in the directory listing.
+
+Purpose: Better keyboard ergonomics and richer directory browsing experience.
+Output: Updated app.rs and vault.rs
+</objective>
+
+<execution_context>
+@.planning/STATE.md
+</execution_context>
+
+<context>
+@src/app.rs
+@src/vault.rs
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Add bare arrow key navigation and directory descriptions</name>
+  <files>src/vault.rs, src/app.rs</files>
+  <action>
+**Part A: Arrow keys in app.rs handle_key()**
+
+In `handle_key()`, add bare Left and Right arrow cases. These must go AFTER the existing `Alt+Left` / `Alt+Right` matches (lines ~495-500) but BEFORE the scroll keys. Add these two arms:
+
+```rust
+KeyCode::Left => {
+    self.navigate_back();
+}
+KeyCode::Right => {
+    self.navigate_forward();
+}
+```
+
+Place them right after the `KeyCode::Right if key.modifiers.contains(KeyModifiers::ALT)` arm (around line 500), before the scroll section comment. The match order matters: Alt+Left is checked first (guard), then bare Left falls through to the unguarded arm.
+
+Up/Down already work for scrolling (line 502-506, paired with j/k). No changes needed there.
+
+Update the doc comment on `handle_key()` to mention Left/Right arrow keys for back/forward.
+
+**Part B: Frontmatter parsing in vault.rs**
+
+Add a `description` field to `DirEntry`:
+```rust
+pub struct DirEntry {
+    pub depth: usize,
+    pub name: String,
+    pub is_dir: bool,
+    pub vault_path: Option<String>,
+    pub description: Option<String>,  // NEW
+}
+```
+
+Add a helper function `extract_frontmatter_description(path: &Path) -> Option<String>` in vault.rs:
+- Read the first ~20 lines of the file (use `BufReader` + `lines().take(20)` to avoid reading entire large files)
+- Check if line 1 is exactly `---`
+- Scan for `description:` line (case-sensitive key, value after colon, trimmed)
+- Stop scanning at the closing `---` line
+- Return `Some(description_string)` or `None`
+- Handle both bare `description: some text` and quoted `description: "some text"` (strip outer quotes if present)
+
+Call `extract_frontmatter_description` in `list_vault_files()` for each .md file entry, passing the full path from `entry.path()`. Set `description: None` for directory entries.
+
+**Part C: Display descriptions in build_directory_lines() in app.rs**
+
+Modify the file entry rendering in `build_directory_lines()` to show descriptions. For each file entry that has a description:
+
+```
+  [filename]  description text here, truncated...
+```
+
+Use a dimmed/dark gray style for the description (Color::DarkGray) to visually separate it from the link text. Truncate the description so the total line width does not exceed 78 characters (or a reasonable fixed width). If the description would overflow, truncate and append "...".
+
+The format should be:
+- `{indent}[{name}]  {description}` where description is in DarkGray
+- Two spaces between the bracketed name and the description
+- Description truncated to fit within ~78 char total line width
+
+For entries without a description, display as before (just the bracketed name).
+
+Note: The `span_len` in `LinkRecord` must still only cover the `[name]` portion, NOT the description. The description span is separate and not part of the link. Adjust `col_offset` to remain correct (it's the indent width, unchanged).
+  </action>
+  <verify>
+Run `cargo build` from the project root. Expect clean compilation with no errors and no new warnings.
+Run `cargo clippy` to check for lint issues.
+  </verify>
+  <done>
+- Bare Left arrow calls navigate_back, bare Right arrow calls navigate_forward
+- Alt+Left and Alt+Right still work as before (matched first due to guard)
+- Up/Down still scroll as before (unchanged)
+- DirEntry has a description field populated from YAML frontmatter
+- Directory listing shows descriptions in DarkGray beside file entries
+- Descriptions are truncated to avoid line overflow
+- All existing functionality preserved (no regressions)
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+1. `cargo build` succeeds
+2. `cargo clippy` passes
+3. Manual test: run the app, navigate to directory listing, verify descriptions appear
+4. Manual test: press Left arrow to go back, Right arrow to go forward
+5. Manual test: Up/Down arrows still scroll content
+</verification>
+
+<success_criteria>
+Arrow keys provide full navigation: Up/Down scroll, Left goes back, Right goes forward. Directory listing shows frontmatter descriptions beside each file entry in a subdued style.
+</success_criteria>
+
+<output>
+After completion, create `.planning/quick/1-arrow-key-navigation-and-directory-descr/1-SUMMARY.md`
+</output>