From 32fd7e0cd8b472573cc9e2d49934245fb279d412 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Sat, 24 Oct 2026 13:48:41 -0300 Subject: Docs for window mode's d and c and the delayed Del hint: Help, cheatsheet, guide, reference, tutor, helix-keys --- docs/helix-keys.md | 4 +-- docs/next-winmode.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++ docs/typ/builtins-gui.json | 2 +- docs/typ/builtins-tty.json | 2 +- docs/typ/cheatsheet.typ | 4 +-- docs/typ/guide.typ | 7 +++-- docs/typ/reference.typ | 6 ++-- src/CHANGELOG.md | 9 ++++++ src/builtins.zig | 2 +- src/tutor.txt | 2 +- 10 files changed, 95 insertions(+), 12 deletions(-) create mode 100644 docs/next-winmode.md diff --git a/docs/helix-keys.md b/docs/helix-keys.md index fa06c9a6..d47f3051 100644 --- a/docs/helix-keys.md +++ b/docs/helix-keys.md @@ -128,7 +128,7 @@ language-backend queries, and the shell pipe. | `Tab` (normal) | acme **execute** chord | pardes-specific, keep; explicit-selection rule as Enter | pardes-specific | | `:` (normal, body or tag) | in the body, focuses the pane's tag in normal mode at its remembered cursor (the first time, on `Save`); in the tag, goes back to the body; in a column or workspace tag, back to the active pane. The tag's normal and insert modes ARE the body's: every motion, selection, edit and undo works there, and `0` goes to the line's start, the path's. Tab runs the word under the cursor or the selection and Enter looks it up (in a column or workspace tag Enter runs it too), and either hands the keyboard back to the body first. Clicks choose a new cursor position and type into the tag. | Each tag keeps its own cursor during the session. The computed path/marker/page is reachable and yankable but read-only: an edit into it is refused, and typing into a file's path drafts a new name. File-name changes are staged as described in [editable tags](typ/guide.typ). | pardes-specific | | `Ctrl-w k` / `SPC w k` (window mode, pane with nothing above) | focuses its column's tag, then the workspace tag. `Ctrl-w j` walks back to the panes, `Ctrl-w h`/`l` walk the column tags. Headers edit exactly as a pane tag does. | Column commands target that column's active pane, or its first pane when coming from elsewhere. Workspace and column text are independently editable and persist in dumps. See [editable tags](typ/guide.typ). | pardes-specific | -| `Ctrl-w` / `SPC w`, then `h/j/k/l`/arrows | window mode (`Window`): an outline moves between panes, `Enter`/`Esc` focuses it, a pane's label letter focuses that pane — editor normal mode only | pardes' own window handling (helix window mode skipped, section C). On a header `Ctrl-w` stays a prefix for the `Left`/`Down`/`Up`/`Right` header walk; Raw **tty** mode forwards Ctrl-w to the child. Insert mode owns `Ctrl-w` = delete-word-back, so a tag being TYPED into swallows it; from a tag in normal mode it moves focus to the neighbour's BODY, as from a body, and from the top pane `Up` reaches the column and workspace tags | pardes-specific | +| `Ctrl-w` / `SPC w`, then `h/j/k/l`/arrows, `d`, `c` | window mode (`Window`): an outline moves between panes, `Enter`/`Esc` focuses it, a pane's label letter focuses that pane, `d` is `Del` on the outlined pane (its `k`/`j` answer between two panes, the outline moving to the pane that took the rows), `c` is `Collapse`; the mode stays on — editor normal mode only | pardes' own window handling (helix window mode skipped, section C). On a header `Ctrl-w` stays a prefix for the `Left`/`Down`/`Up`/`Right` header walk; Raw **tty** mode forwards Ctrl-w to the child. Insert mode owns `Ctrl-w` = delete-word-back, so a tag being TYPED into swallows it; from a tag in normal mode it moves focus to the neighbour's BODY, as from a body, and from the top pane `Up` reaches the column and workspace tags | pardes-specific | | `Alt-n` | new terminal below (outside raw tty) | shadows helix `Alt-n` (select next sibling), which pardes spells `Alt-right` alone | pardes-specific | | `Alt-c` | move active terminal to a fresh column (outside raw tty) | helix `Alt-c` is change-noyank; the pardes window op wins (do-not-touch contract). `Alt-d` + `i` covers the behavior | waived (`alt-c-window-op`) | | `Space` (normal, body) | starts the pardes LEADER: a key path runs the same builtin words used by tags and the topbar. The main groups are `f` files, `h` docs, `c` columns, `t` toggles/effects, `a` panel animations, `s` session, `j` jumps, `l` language, and `w` directional focus; `SPC ?` lists every path and ` ?` lists one group in `+Help`. Neither `Exit` (quits the editor, acme's Exit) nor `Kill` (stops the commands pardes typed into terminals, acme's Kill) has a leader path: both are the topbar's and the root `ctl`'s. The pending path appears on the active pane's transient body/message row. Esc or an unmapped key abandons it. Paths, Help rows, and dispatch are all generated from the builtin registry at comptime; the leader applies only to a BODY in normal mode because tags and tty programs own their input | pardes-specific; helix spends Space on pickers/LSP (section C), while pardes uses acme-style executable words | @@ -358,7 +358,7 @@ text. | Popup `Ctrl-u`/`Ctrl-d`, Completion menu, Signature help tables | LSP popups | LSP | | Picker table (all rows), Prompt table (all rows) | picker / prompt internals | pickers — pardes' tag line is its own one-line editor | | `gn` `gp` `ga` `gm` | next/prev/alternate buffer | buffer nav — pardes panes aren't a buffer list | -| Window mode table: `Ctrl-w` + `w v s t f F h j k l q o H J K L ns nv` (+ Ctrl variants) | splits/window management | window mode — pardes has its own Ctrl-w focus + Alt-n/Alt-c + mouse layout drags | +| Window mode table: `Ctrl-w` + `w v s t f F h j k l q o H J K L ns nv` (+ Ctrl variants) | splits/window management | window mode — pardes has its own Ctrl-w focus + Alt-n/Alt-c + mouse layout drags; of helix's table it keeps `h j k l`, and closes with `d` (`Del`, which asks `k`/`j`) where helix has `q`, `c` collapsing | | `]g [g ]G [G` | git change jumps | **deferred by decision**: needs a diff base per file (jj `@-` or git HEAD, fetched by the host on open and save) and line hunks from diffz; the design is written up, the work waits | | insert `Ctrl-x` | completion menu | completion exists, but not as a popup: insert-mode Tab straight after a `.` opens a buffer of candidate DECLARATIONS (section A). helix's menu itself is skipped | | `Ctrl-s` (normal) | save jumplist position | jumplist itself is implemented (`Ctrl-o`/`Ctrl-i`, section A); only the explicit save point is skipped | diff --git a/docs/next-winmode.md b/docs/next-winmode.md new file mode 100644 index 00000000..c2a01da8 --- /dev/null +++ b/docs/next-winmode.md @@ -0,0 +1,69 @@ +# winmode: d and c in window mode, the Del question as a hint + +> The window mode should have d for deleting and c for collapsing too, the +> deletion should keep that j/k movement. The current spc d j/k should only +> show the message after a timeout so that a user that does this fast won't +> even see it, it will be more like a hint for users that tried to delete +> and nothing happenend. + +## As built + +- `layout.windowKey`: `c` runs `Collapse` on the outlined pane; `d` makes + the outlined pane active and runs `Del` on it, exactly the keyboard Del + (`can_ask` is set: it is a key). With panes above and below, Del asks + and the next key is its answer (`Pardes.answerQuestion`, which already + runs before window mode sees keys); with one neighbour it closes at once. + Either way, once the pane is gone the outline moves to `p.active`, which + `removePane` already sets to the pane that grew into the rows. The mode + stays on: `Ctrl-w d j d` closes two panes. A refused Del (unsaved text) + leaves the outline where it is, the refusal on the message row. +- Keys: `config.window_delete` (`d`) and `config.window_collapse` (`c`), + apart from `window_keys`, because those are also the header walk under + `Ctrl-w` on a tag, where `d`/`c` mean nothing. +- Labels: `layout.window_labels` loses `d` and `c` (22 -> 20 letters). +- The hint: Del sets `Pane.question_due_ns = clock + 400 ms` when it asks; + `Messages.collectNotices` leaves the prompt band out while + `question_due_ns > now_ns`; `nextWake` wakes once at that time (while + `question_due_ns > stepped_ns`, so stepping past it ends the wake and a + tick draws the frame). Same pattern as the REPL's `repl_enter_due_ns`. + The question exists from the first moment: keys answer it, the 9P log + says `ask` at once, a script's `answer` works; only the band waits. + +## Why 400 ms + +Typed in one go, the `j` after `SPC d` lands 100-250 ms after the `d` +(a leader sequence's inter-key gap). Above ~300 ms it is a pause, the hand +waiting to see something happen. 400 ms clears a relaxed typist with margin +and is still quick enough to read as "it is asking", not "it is broken". +Key-hint popups elsewhere (which-key) wait a few hundred ms for the same reason. It is a compile-time +constant beside `del_question` (keys are compiled in); a Runtime setting +would be one line in config if the author wants to tune it live. + +## Tests + +- `window mode d deletes the outlined pane and asks k or j, c collapses + it, and the mode stays` (pardes.zig): c twice restores the height; d asks, + Esc keeps it, d j gives the rows below and the outline follows; d with one + neighbour closes at once onto it; labels hold none of h j k l d c. +- `the Del question shows only once its delay is up: a quick SPC d j never + sees it`: no prompt band before the due time, nextWake at it and not + past one frame, the band after, no wake once stepped past; a fast + `SPC d j` closes with the band never showing it. +- The old Del test moves the clock to the due time before looking at the + band. `test/snapshots/delask.snap` waits out the delay (`settle 700`) + before `snap asked`; its golden is unchanged (it raced otherwise: the + first `stable 400` saw no change and captured the band empty). + +## Open questions, positions + +- Should `d` leave window mode after closing? Position: no. The point of a + mode is a run of layout edits (`Ctrl-w d j d c`), and the outline landing + on the pane that grew says where you are; Enter/Esc end it as ever. +- `d`/`c` taken from the labels: the 21st and 22nd panes lose a letter. + Position: fine; past 20 panes you move anyway. The alternative (labels + only after a prefix) costs a key on every jump. +- Del's question from a click or 9P never asks, so the delay touches only + the keyboard paths that ask today. +- Pushback: the hint could be the message row's own lingering text instead + of the prompt band, but the band is where the answer's keys are named and + the caret logic already knows it; kept. diff --git a/docs/typ/builtins-gui.json b/docs/typ/builtins-gui.json index 88c9d864..db1031a0 100644 --- a/docs/typ/builtins-gui.json +++ b/docs/typ/builtins-gui.json @@ -154,7 +154,7 @@ {"name": "Up", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane above, and from a column's top pane to its tag."}, {"name": "Verbose", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A builtin says its own name on the message row as it runs, on or off."}, {"name": "Vignette", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off, 0-3", "doc": "The window's corners fall into shade: a level, 0 (off) through 3."}, - {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one."}, + {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one; d is Del on it (then k or j between two), c Collapse."}, {"name": "WindowOpacity", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": null, "doc": "The window's opacity, a percentage."}, {"name": "Wrap", "leader": "SPC t w", "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "Long lines wrap onto the next row, on or off."}, {"name": "WsDiagnostics", "leader": "SPC l D", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the workspace's diagnostics from the language server."}, diff --git a/docs/typ/builtins-tty.json b/docs/typ/builtins-tty.json index 01ae6bc5..6bdca598 100644 --- a/docs/typ/builtins-tty.json +++ b/docs/typ/builtins-tty.json @@ -136,7 +136,7 @@ {"name": "Unmount", "leader": null, "also": [], "arg": true, "scope": "root", "setting": false, "choices": null, "doc": "Unmount the 9P tree mounted under /n/."}, {"name": "Up", "leader": null, "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Move the keyboard to the pane above, and from a column's top pane to its tag."}, {"name": "Verbose", "leader": null, "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "A builtin says its own name on the message row as it runs, on or off."}, - {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one."}, + {"name": "Window", "leader": "SPC w", "also": ["C-w"], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "Window mode: h/j/k/l move an outline between the panes; Enter or Esc focuses the outlined pane, `:` its tag, the letter shown on a pane that one; d is Del on it (then k or j between two), c Collapse."}, {"name": "Wrap", "leader": "SPC t w", "also": [], "arg": true, "scope": "root", "setting": true, "choices": "on, off", "doc": "Long lines wrap onto the next row, on or off."}, {"name": "WsDiagnostics", "leader": "SPC l D", "also": [], "arg": false, "scope": "pane", "setting": false, "choices": null, "doc": "List the workspace's diagnostics from the language server."}, {"name": "WsSymbols", "leader": "SPC l S", "also": [], "arg": true, "scope": "pane", "setting": false, "choices": null, "doc": "Search the workspace's symbols for its argument."}, diff --git a/docs/typ/cheatsheet.typ b/docs/typ/cheatsheet.typ index 76f4b866..d8939c4c 100644 --- a/docs/typ/cheatsheet.typ +++ b/docs/typ/cheatsheet.typ @@ -29,7 +29,7 @@ One button: Alt/Option-click is #btn("B2"), Cmd/Super-click #btn("B3"), sweeps t #tag("Save Tty Collapse Del", path: "/home/me/notes.txt") #tag("Tty+bash Save Mode Filter Collapse Del", path: "/home/me/src") #tag("Tty PdfSections PdfTint Collapse Del", path: "manual.pdf [1/12]") -- #word("Del") over unsaved text refuses once; again discards. #word("Del") `j`: rows below. +- #word("Del") over unsaved text refuses once; again discards. #word("Del") `j`: rows below. #key("SPC d") between two panes takes #key("k") (rows above) or #key("j") (below), asking only if you pause. - #word("Undo") #word("Redo") #word("Edit") #word("Mode") work typed anywhere. #doc("tags") == #word("Look") addresses @@ -71,7 +71,7 @@ Helix-style: motions *select*, then an edit acts on the selection. Mode box: bla == Keys: panes #pairs( - [#key("Ctrl-w")], [window mode: #keys("h", "j", "k", "l") move the outline, #key("Enter")/#key("Esc") or a pane's letter focuses (not in insert or raw `$`)], + [#key("Ctrl-w")], [window mode: #keys("h", "j", "k", "l") move the outline, #key("d") deletes it (then #key("k")/#key("j") between two), #key("c") collapses it, #key("Enter")/#key("Esc") or a pane's letter focuses (not in insert or raw `$`)], [#key("Esc")], [back to the previous pane (insert: to normal)], [#key("Shift-Esc")], [back to the previous pane from any mode but raw, where it is the program's Esc; needs the kitty keyboard protocol or the GUI, elsewhere a plain Esc], [#keys("Ctrl-o", "Ctrl-i")], [jump history back, forward; this file first. #key("Ctrl-i") is #key("Tab") without the kitty protocol: #key("SPC j i")], diff --git a/docs/typ/guide.typ b/docs/typ/guide.typ index 65c7334d..9fd33e60 100644 --- a/docs/typ/guide.typ +++ b/docs/typ/guide.typ @@ -54,7 +54,7 @@ it is a plain Esc. The previous pane is the last one you jumped from, else the next pane down the column. #pairs( - [#key("Ctrl-w") or #key("SPC w")], [window mode (#word("Window")): each pane's tag box shows a letter instead of its mode, and the focused pane's tag is outlined; #keys("h", "j", "k", "l") move the outline, #key("Enter") or #key("Esc") gives that pane the keyboard, #key(":") its tag, a pane's letter gives it that one. #key("k") past a column's top pane goes on to its tag], + [#key("Ctrl-w") or #key("SPC w")], [window mode (#word("Window")): each pane's tag box shows a letter instead of its mode, and the focused pane's tag is outlined; #keys("h", "j", "k", "l") move the outline, #key("Enter") or #key("Esc") gives that pane the keyboard, #key(":") its tag, a pane's letter gives it that one. #key("k") past a column's top pane goes on to its tag. #key("d") is #word("Del") on the outlined pane (between two panes it waits for #key("k") or #key("j"), as #key("SPC d") does) and the outline moves to the pane that took its rows; #key("c") is #word("Collapse"). The mode stays on for the next key], [#keys("Ctrl-o", "Ctrl-i")], [back and forward through the places you jumped to (the jump list), this file's first: another file's only once it has none left that way (#word("JumpScope") `all`: every place in order). #key("Ctrl-i") needs the kitty keyboard protocol or the GUI, being #key("Tab") elsewhere: there use #key("SPC j i") and #key("SPC j o"), or the mouse's side buttons], ) @@ -214,7 +214,10 @@ and a terminal's #key("/") still ask on the message row and list a in `+Unsaved`; #word("Del") again discards it. #word("Exit") (or #key("SPC q")), #word("Restore") and #word("Delcol") refuse once the same way. #key("SPC d") between two panes also asks which -takes the rows: #key("k") above, #key("j") below. +takes the rows: #key("k") above, #key("j") below. Typed straight on, +#key("SPC d") then #key("j") just closes the pane; the question shows on its notice band +only if no answer has come after a moment, a hint for a Del that seemed to +do nothing. = Terminals diff --git a/docs/typ/reference.typ b/docs/typ/reference.typ index 386b9f0f..3ddcd881 100644 --- a/docs/typ/reference.typ +++ b/docs/typ/reference.typ @@ -593,7 +593,8 @@ no newline, as acme's has none (`cat ctl; echo`). It takes: - the pane builtins: #word("Del") (from the keyboard between two panes it - asks which takes the rows; a click, a ctl write or an `init` line never + asks which takes the rows, the question on the notice band after 400 ms + and in the log at once as `ask`; a click, a ctl write or an `init` line never asks and gives them to the pane above; #word("Del") `k`/#word("Del") `j`, or #word("DelAbove")/#word("DelBelow"), give its rows to the pane above or below), #word("Save") `[path]` (bare, on a `+`-named pane that is no output, @@ -605,7 +606,8 @@ takes: keyboard to the pane beside it that way, up from a column's top pane to its tag; #word("Window") (#key("Ctrl-w"), #key("SPC w")) picks the pane first: #keys("h", "j", "k", "l") move an outline, #key("Enter") or - #key("Esc") or a pane's letter focuses. + #key("Esc") or a pane's letter focuses, #key("d") is #word("Del") and + #key("c") #word("Collapse") on the outlined pane. - `get`: reload from the file (refused once over unsaved edits, `: Modified (get again to discard)`). It is an undo step, so #word("Undo") brings back what was there: the sure way back to the file on disk. - `lock`/`unlock` (acme's). The lock binds only clients that take it and belongs to the open that wrote it: `exec 3>$pane/ctl; echo lock >&3; ...; exec 3>&-`. A `lock` another open holds fails at once, `file in use` diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index efccc785..c2e0f3f7 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -2,6 +2,15 @@ ## Unreleased +- Window mode (Ctrl-w, SPC w) takes `d` and `c`: `d` is Del on the + outlined pane, asking k or j between two panes as SPC d does, and the + outline moves to the pane that took the rows; `c` collapses it. The mode + stays on, so `Ctrl-w d j d` closes two panes. `d` and `c` are no longer + pane labels. +- Del's question (`give space to k above j below`) shows only once 400 ms + have passed with no answer: SPC d j typed straight on closes the pane + without the band flashing, and a hand that stops after SPC d gets it as + a hint. - Callstack (gc or Space l b) opens a readable static call hierarchy with outermost callers first, tree-sitter signatures, depth guides and clickable call sites. `gc` replaces the old move-to-viewport-center binding. diff --git a/src/builtins.zig b/src/builtins.zig index 4fb933b0..1f1e674e 100644 --- a/src/builtins.zig +++ b/src/builtins.zig @@ -1844,7 +1844,7 @@ pub const Right = struct { }; /// Window mode: h/j/k/l move an outline between the panes; Enter or Esc -/// focuses the outlined pane, `:` its tag, the letter shown on a pane that one. +/// focuses the outlined pane, `:` its tag, the letter shown on a pane that one; d is Del on it (then k or j between two), c Collapse. pub const Window = struct { pub fn run(c: Ctx) void { tagline.exitHeader(c.p); diff --git a/src/tutor.txt b/src/tutor.txt index 188a485d..a1e887fa 100644 --- a/src/tutor.txt +++ b/src/tutor.txt @@ -290,7 +290,7 @@ typed SPC d `Del` SPC q `Exit` SPC f s `Save` SPC f f `Find` SPC f n `New` SPC y yank to the clipboard SPC p paste from it - SPC w window mode: h/j/k/l, Enter + SPC w window mode: h/j/k/l, Enter; d Del, c Collapse SPC j j `Last` SPC j o / SPC j i back / forward SPC s a `Attach` SPC s D `Detach` SPC t ... the toggles SPC l ... the language -- cgit v1.3