Skip to content

feat: deck keyboard navigation shortcuts (j/k/c//Esc) - #66

Merged
aaronjmars merged 1 commit into
mainfrom
feat/deck-keyboard-nav
Jun 9, 2026
Merged

aaronjmars merged 1 commit into
mainfrom
feat/deck-keyboard-nav

Conversation

@aaronjmars

Copy link
Copy Markdown
Collaborator

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 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. 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 single keydown listener at the DeckBoard level 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

  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. Clicking any column body (button bubble included) sets that column as focused. Tooltips and dialog triggers still run their normal action on top of focus assignment.
  4. Pinned-first / tab-filtered order is the focus order — visibleColumnIds is reused directly (the same array 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 already 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.

pendingSearchOpen is the one-shot bridge to ColumnCard's local searchOpen state. It's a column id (not a boolean) so a fast j / 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)]/60 on the focused column's wrapper on both the expanded and collapsed render paths. Co-exists with the existing isDragging ring.

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 + pendingSearchOpen fields, setFocusedColumn / requestSearchOpen / clearPendingSearchOpen actions, cleanup in deleteDeck + removeColumn
  • components/deck/deck-board.tsx (+117) — keyboard listener useEffect routing j/k/c/// Escape, with the input-guard + modifier guard
  • components/column/column-card.tsx (+25) — focus-ring class on both wrappers, click-to-focus handlers, useEffect reacting to pendingSearchOpen to open + focus the inline search input

Not changed

  • No DB schema, no migration, no server action change
  • No plugin contract touched
  • No version bump on DECK_EXPORT_VERSION (view-state-only)
  • Could NOT run Next 16 build/typecheck (offline sandbox — same constraint as the per-column UX PR chain)

Built autonomously by Aeon

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
aaronjmars merged commit 9702d8c into main Jun 9, 2026
1 check passed
@aaronjmars
aaronjmars deleted the feat/deck-keyboard-nav branch June 9, 2026 12:02
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant