Repository navigation
feat: deck keyboard navigation shortcuts (j/k/c//Esc) - #66
Merged
Merged
Conversation
Adds a keyboard nav layer for the deck. With 10–15 columns per deck
becoming routine after the recent UX rungs (tab groups, collapse,
search, pin, duplicate, color, width, deck DnD), every action was
hunt-and-click — focus a column, open its menu, dismiss. Four shortcuts
cover the daily flow:
- j / ArrowRight → focus next visible column (wraps)
- k / ArrowLeft → focus previous visible column (wraps)
- / → open the focused column's inline search + focus input
- c → toggle collapse on the focused column
- Escape → clear the focused column's search, then clear focus
Mirrors muscle memory operators already have from Linear, GitHub issues,
and most terminal dashboards. j/k wraps so they're cheap to mash without
glancing at the edges. Plain-key only — modifier presses (Ctrl/Cmd/Alt)
are left to the browser/OS so ⌘K and friends still work.
Six key design decisions
1. **`/` is no-op when nothing is focused**, by design. Pressing `/`
first then `j` would surface a search bar on a column the operator
hasn't picked — the wrong direction. They press `j` to pick, then `/`
to search it.
2. **j/k wrap** (last → first, first → last). For an 8-column deck the
alternative is a focus ring that gets stuck at the edges and demands
a mouse to reset. Wrapping keeps the keyboard self-contained.
3. **Click sets focus too**, so mouse and keyboard agree on what's
focused. A click on any column body (button bubble included) sets
that column as focused. Tooltips and dialogs trigger their normal
action on top of focus assignment.
4. **Pinned-first / tab-filtered order** is the focus order. Reuses
`visibleColumnIds` directly — the same array the SortableContext
renders — so j/k walk in the order the operator sees, not the
stored `columnIds` order.
5. **Two-step Escape**: when a column is focused and has an active
search query, the first Escape press clears the query (matching what
the column's own Esc handler does inside the input), the second
clears the focus ring entirely. Lets the operator stay on a column
while exiting search mode.
6. **Listener attached to `window`** so it's alive regardless of where
focus lands inside the deck — but bails the instant the active
element is an input/textarea/select/contenteditable. Typing into a
search box, configure dialog, or rename field never gets intercepted.
State + cleanup
`focusedColumnId: string | null` and `pendingSearchOpen: string | null`
are added to use-deck-store.ts as view-state-only fields (NOT persisted,
same lifetime as `collapsedColumnIds`/`searchByColumn`/`widthByColumn`).
Both are scrubbed in `deleteDeck` and `removeColumn` so the keyboard
listener can never operate on a stale id pointing at a deleted column.
The `pendingSearchOpen` field is the one-shot bridge to ColumnCard's
local `searchOpen` state. It's a column id (not a boolean) so a fast
sequence of `j` `/` `j` `/` lands on the second column's search box,
not the first. ColumnCard reads it in a useEffect, opens the search
row + focuses the input, then immediately clears the signal so a
subsequent `/` re-fires cleanly.
Visual
`ring-2 ring-[color:var(--brand)]/60` applied to the focused column's
wrapper on both the expanded and collapsed render paths. Co-exists with
the existing isDragging ring (same opacity layer, no collision).
scrollIntoView after j/k
`requestAnimationFrame(() => element.scrollIntoView({inline: "nearest"}))`
after j/k so the focus ring stays visible when the operator presses past
the right or left edge of the horizontal scroller. Smooth + nearest so
it's quiet on short hops and only kicks in when the focused column
would actually be off-screen.
NOT changed: no DB schema, no migration, no server action change, no
plugin contract touched, no version bump on DECK_EXPORT_VERSION. Could
NOT run Next 16 build/typecheck (offline sandbox — same constraint as
the per-column UX PR chain).
aaronjmars
added a commit
that referenced
this pull request
Jun 9, 2026
…drag (#67) #66's window-level j/k/c//Esc handler bails when a text field is focused, but a dnd-kit keyboard drag (#65) is driven from a <button> drag handle — so during an active keyboard reorder the same ArrowLeft/ArrowRight/Escape keys were handled by BOTH the KeyboardSensor and the column-nav handler. Track drag state in a ref (set on onDragStart, cleared on onDragEnd / onDragCancel) and bail the key handler while a drag is in progress, so the KeyboardSensor exclusively owns arrows/Escape until the column drops or the drag cancels. A merely-focused (not dragging) handle still allows nav, since arrows don't start a drag — only Space/Enter does. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
aaronjmars
added a commit
that referenced
this pull request
Jun 10, 2026
* feat: deck-level refresh-all button + r/Shift-R keyboard shortcuts 11th rung on the per-column/deck UX axis. The previous 10 (tab groups, collapse, JSON export, search, pin, duplicate, color, deck color, width, deck DnD, keyboard nav) all targeted individual-column or single-deck ergonomics; this one is the first dashboard-level batch verb. At 10+ columns per deck the manual hunt-and-click on each per-column refresh button was the friction the keyboard nav (PR #66) made half a solution to: j/k/c// gave the operator a way to focus a column without the mouse, but every fresh-feed action still needed a click. What ships: - Deck-view top-bar Refresh-all button next to the column count. Tooltip Refresh all columns; brand-hover styling matches the existing column-card per-column refresh button. Visible whenever the active deck has at least one column. Spins while any pendingRefreshIds id belongs to the active deck — the visual confirmation 12+ off-screen columns need so the operator knows the action took effect. - r shortcut: refresh the focused column. Quiet, surgical — pair with j/k to walk a deck and freshen one stale feed without touching the others. - Shift-R shortcut: refresh every visible column in the active tab. Same set the deck-header button hits when no tab filter is active, scoped down when one is. Collapsed columns in the active tab are visibleColumnIds and get refreshed; columns hidden by a different tab filter do not. - New pendingRefreshIds: Set<string> on the deck store. Populated by requestRefreshColumns(ids), drained by each ColumnCard's useEffect via clearPendingRefresh(id) the moment it fires its own onRefresh(). Three design decisions: 1. **Set, not boolean.** A parallel sweep across 15 columns lands on every column exactly once, not just the last one rendered. Same lifetime as pendingSearchOpen / focusedColumnId — view-state only, clears on reload. 2. **In-flight refresh blocks the signal, doesn't drop it.** When a column is already mid-fetch (isFetching=true), the useEffect sees the pending id but doesn't re-fire; once the in-flight fetch completes the effect re-runs and the new refresh kicks off. The Set already guards against double-enqueue from a hot click. Result: clicking Refresh-all mid-fetch always gives the operator a fresh fetch on every column, never a no-op. 3. **r refreshes focused, Shift-R refreshes visible, button refreshes deck.** Three intentions, three verbs. r without focus is a no-op (same rationale as / without focus). Shift-R works without focus because the implicit target is the deck the operator is looking at. The button works without focus because that's the deck-level action. Cleanup: deleteDeck and removeColumn scrub the deleted ids from pendingRefreshIds so a stale signal can't make a freshly-deleted column keep firing onRefresh in the next render tick. NO DB schema, NO migration, NO server round-trip, NO plugin contract touched, NO version bump on DECK_EXPORT_VERSION. Pure view-state + UI. Could NOT run Next 16 build/typecheck (offline sandbox — same constraint as PRs #49-#66). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * fix(deck): refresh-all review fixes — Base UI trigger, visible-only scope, settle-time drain, quiet sweep toasts - deck-view: style TooltipTrigger as the button itself instead of asChild + nested <button> — the repo's tooltip is Base UI, which has no asChild prop (build typecheck failed) and renders its own <button>, so the old markup nested buttons. Mirrors every trigger in column-card. - Refresh-all now enqueues only columns the deck-board actually mounts: the button and Shift-R share getVisibleColumnIds (extracted from deck-board's memo into the store module next to TAB_GROUP_ALL). Enqueueing all deck columnIds stranded pending ids for columns a non-"All" tab filter keeps unmounted — the header spinner never stopped and switching tabs later fired surprise refreshes. Chose enqueue-side scoping over store-side draining because visibility is already a pure derivation of store state; sharing the exact computation guarantees "what refreshes" can never drift from "what mounts", whereas a store-side GC would have to duplicate the same tab/pin rules. Unregistered column types (card renders the error shell and returns before the drain effect) are filtered centrally in requestRefreshColumns. - column-card: store-routed refreshes call onRefresh({ quiet: true }) to suppress per-column success toasts — a 12-column sweep stacked 13+ toasts on top of the deck-header's aggregate "Refreshing N columns" toast. Error toasts stay loud (unlike the fully-silent interval auto-refresh, the operator explicitly asked for this fetch). - column-card: drain the pending id when the fetch settles (.finally) instead of before it fires, so pendingRefreshIds tracks real in-flight state and the header spinner spins for the duration of the sweep instead of one frame. The .finally closure survives unmount, so a column that leaves the screen mid-flight still drains its id; an in-flight ref guards re-entry in the window before isFetching re-renders true. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: aeonframework <aeon@aeonframework.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
aaronjmars
added a commit
that referenced
this pull request
Jun 18, 2026
minitor had no CI. This adds a single Build job that runs `npm ci` followed by `next build` on push-to-main and every pull request, with a concurrency group that cancels superseded runs. `next build` compiles the production bundle and runs the TypeScript checker — the same gate that would have caught the recent build breaks (#66, #70, #71). It needs no secrets: with DATABASE_URL unset the app uses the bundled PGlite driver, so the build runs on forks and external PRs too. Lint is intentionally left out of this gate for now: `npm run lint` currently reports pre-existing violations across the plugin files, so a lint job would be red from day one. Worth a focused follow-up. Co-authored-by: aaronjmars <aaronjmars@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds a keyboard nav layer for the deck. With 10–15 columns per deck becoming routine after the recent UX rungs (tab groups, collapse, search, pin, duplicate, color, width, deck DnD), every action was hunt-and-click. Four shortcuts cover the daily flow:
j/→— focus next visible column (wraps)k/←— focus previous visible column (wraps)/— open the focused column's inline search + focus the inputc— toggle collapse on the focused columnEscape— clear the focused column's search, then clear focusMirrors muscle memory operators already have from Linear, GitHub issues, and most terminal dashboards. Plain-key only — modifier presses (Ctrl/⌘/Alt) are left to the browser/OS so existing shortcuts (⌘K, browser back/forward, etc.) still work.
Why
Yesterday's
repo-actions(#3) flagged this as the next natural rung — every per-column UX improvement in the last 11 days raises the column count an operator wants to keep open, and at 10+ columns per deck the keyboard becomes the bottleneck, not the affordance on each column. A singlekeydownlistener at theDeckBoardlevel routes events to actions that already exist (toggleColumnCollapsed,setColumnSearch, the inline search-open UI). No new components, no new DB fields, no migration.Six key design decisions
/is no-op when nothing is focused, by design. Pressing/first thenjwould surface a search bar on a column the operator hasn't picked — the wrong direction. They pressjto pick, then/to search it.j/kwrap (last → first, first → last). For an 8-column deck the alternative is a focus ring that gets stuck at the edges and demands a mouse to reset. Wrapping keeps the keyboard self-contained.visibleColumnIdsis reused directly (the same arraySortableContextrenders), so j/k walk in the order the operator sees, not the storedcolumnIdsorder.Escape: when a column is focused and has an active search query, the firstEscapepress clears the query (matching what the column's own Esc handler already does inside the input), the second clears the focus ring entirely. Lets the operator stay on a column while exiting search mode.windowso it's alive regardless of where focus lands inside the deck — but bails the instant the active element is aninput/textarea/select/[contenteditable]. Typing into a search box, configure dialog, or rename field never gets intercepted.State + cleanup
focusedColumnId: string | nullandpendingSearchOpen: string | nullare added touse-deck-store.tsas view-state-only fields (NOT persisted, same lifetime ascollapsedColumnIds/searchByColumn/widthByColumn). Both are scrubbed indeleteDeckandremoveColumnso the keyboard listener can never operate on a stale id pointing at a deleted column.pendingSearchOpenis the one-shot bridge to ColumnCard's localsearchOpenstate. It's a column id (not a boolean) so a fastj/j/sequence lands on the second column's search box, not the first. ColumnCard reads it in a useEffect, opens the search row + focuses the input, then immediately clears the signal so a subsequent/re-fires cleanly.Visual
ring-2 ring-[color:var(--brand)]/60on the focused column's wrapper on both the expanded and collapsed render paths. Co-exists with the existingisDraggingring.scrollIntoView after j/k
requestAnimationFrame(() => element.scrollIntoView({behavior: \"smooth\", block: \"nearest\", inline: \"nearest\"}))after j/k so the focus ring stays visible when the operator presses past the right or left edge of the horizontal scroller. Smooth + nearest so it's quiet on short hops and only kicks in when the focused column would actually be off-screen.Changes
lib/store/use-deck-store.ts(+68) —focusedColumnId+pendingSearchOpenfields,setFocusedColumn/requestSearchOpen/clearPendingSearchOpenactions, cleanup indeleteDeck+removeColumncomponents/deck/deck-board.tsx(+117) — keyboard listeneruseEffectrouting j/k/c/// Escape, with the input-guard + modifier guardcomponents/column/column-card.tsx(+25) — focus-ring class on both wrappers, click-to-focus handlers,useEffectreacting topendingSearchOpento open + focus the inline search inputNot changed
DECK_EXPORT_VERSION(view-state-only)Built autonomously by Aeon