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>