github-search-cli 9.9.0 → 9.10.0

package/docs/HOW-TO.md

@@ -141,8 +141,9 @@ ghfind "cli" --sort forks
 ghfind "cli" --sort best-match # GitHub's own relevance order
 ```
 
-In the TUI, `Space` opens the leader menu, where **Sort** cycles the same
-strategies without leaving the results.
+In the TUI, `Esc` opens the leader menu (or click the <kbd>☰ menu</kbd> button in
+the bottom-right corner), where **Sort** cycles the same strategies without
+leaving the results.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "github-search-cli",
-  "version": "9.9.0",
-  "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard-driven TUI + pipeable CLI.",
+  "version": "9.10.0",
+  "description": "Search GitHub from your terminal — repo search, trending repos, npm package search, bookmarks, deep-dive, compare, export. Keyboard + mouse TUI + pipeable CLI.",
   "type": "module",
   "packageManager": "bun@1",
   "volta": {

package/release-notes/9.10.0.md

@@ -0,0 +1,137 @@
+# v9.10.0
+
+ghfind's TUI has always been keyboard-only — and, quietly, half-broken for the
+mouse. OpenTUI was already emitting SGR mouse tracking and hit-testing every
+event into a target renderable. Nothing in ghfind consumed any of it. The
+events were parsed, dispatched, and thrown away. This release makes the TUI
+clickable, and fixes the two keyboard rough edges that were hiding behind it.
+
+## The TUI is now fully clickable
+
+Click a result and the detail pane updates. Click it again and your browser
+opens. Scroll to move through results. Click outside an overlay to close it.
+
+Every list, card, tab and button responds: the results list, the landing mode
+cards, trending tabs, the update dialog's buttons, and every overlay list
+(history, bookmarks, saved searches, topics, export, share, and the command
+menu itself).
+
+The important detail is that clicks do not reimplement anything. A click calls
+`setSelectedIndex`, which emits the same `selectionChanged` event `↑`/`↓`
+already emitted, so the detail pane, the detail graph and the packages view all
+work identically without a parallel code path. A double-click calls the same
+activation path as `Enter`. There is no mouse branch to keep in sync — the
+keyboard and the mouse converge on one implementation, which is also why they
+cannot drift.
+
+## The wheel scrolled the wrong pane
+
+Worth calling out, because it predates this release and was a real bug rather
+than a missing feature.
+
+When a scroll event hit nothing, OpenTUI falls back to delivering it to
+whatever renderable currently holds focus. In ghfind that was almost always the
+results list. So opening the README viewer and scrolling would move the
+_result selection_ instead of the README — the one thing you were trying to do.
+
+Every scrollable region now claims the wheel explicitly, and the list's wheel
+handler steps the selection through `moveUp`/`moveDown`, so wheel navigation
+and `↑`/`↓` navigation cannot diverge either.
+
+## Text that swallowed clicks
+
+`TextRenderable` defaults to OpenTUI's `selectable: true`, and a left-press on
+a selectable renderable is consumed as a text-selection drag _before_ the app's
+own handlers run. The detail pane, comparison table, tab bar and other read-only
+text are all `TextRenderable`s, so clicks landing on them did nothing at all.
+
+They now opt out of text selection. The query input deliberately keeps it, so
+clicking into the input still places your cursor.
+
+## A hover highlight that painted the list magenta
+
+Small one, but it would have been immediately obvious to anyone using it.
+OpenTUI's colour parser accepts `"transparent"`, CSS colour names, and 3/4/6/8
+digit hex — nothing else. An `rgba(255,255,255,0.06)` hover tint failed that
+check and fell through to its magenta fallback, so hovering a list would have
+flashed it magenta. Now written as `#ffffff0f`.
+
+Found because the test harness prints that warning. Worth noting the class of
+bug: OpenTUI degrades an invalid colour to magenta rather than throwing, so this
+fails silently and visibly at the same time.
+
+## `Space` opened the menu only if you had clicked something first
+
+The subtlest problem in this release, and it was not caused by mouse support —
+it was exposed by it.
+
+The query input is focused by default. The command menu was bound to `Space`,
+gated on the input _not_ being focused, so that spaces could still be typed into
+a query. That gate meant `Space` opened the menu only when focus had moved
+somewhere else. The one way focus moved was clicking a result row: OpenTUI's
+auto-focus-on-press walks up from the pressed renderable to the nearest
+focusable ancestor, finds the results list, and focuses it — blurring the input
+as a side effect.
+
+So on a fresh launch, `Space` typed a space. Click any row, and `Space` opened
+the menu. Same key, same screen, different behaviour depending on invisible
+state.
+
+A regression test now pins this down from both directions: with `keepFocus` a row
+click does not move focus, and without it one does.
+
+The resolution is that **`Esc` opens the command menu**, and `Space` always
+types. `Esc` already closed every overlay, so this adds a meaning rather than
+replacing one. For anyone who prefers not to reach for `Esc`, there is now a
+<kbd>☰ menu</kbd> button in the bottom-right corner — clickable, it floats above
+the layout, and it hides while an overlay is open so it never sits on top of one.
+
+## Added
+
+- Full mouse support: click to select, double-click to open, wheel to scroll,
+  click-outside to dismiss, hover feedback with a pointer cursor.
+- <kbd>☰ menu</kbd> button in the bottom-right corner to open the command menu.
+- A "Mouse" section in the in-app help, documenting every binding.
+- README keybinding tables gained a mouse table; the command-menu references
+  across the README and `docs/HOW-TO.md` now say `Esc` instead of `Space`.
+
+## Fixed
+
+- The scroll wheel scrolled the focused renderable rather than the pane under
+  the pointer, so long-pane scrolling moved the result selection instead.
+- Non-interactive text consumed left-presses as text-selection drags, so clicks
+  over the detail pane and comparison table did nothing.
+- The hover tint used an `rgba()` string that OpenTUI's colour parser rejects,
+  rendering the list magenta.
+- `Space` could not open the command menu on a fresh launch, because it was
+  gated on focus that only moved after a mouse click.
+
+## Verification
+
+The suite grew by 33 tests, to 657.
+
+- **15 unit tests** on the click→row geometry: scroll offsets, multi-line rows
+  (overlay lists render a description line, so each option is two lines tall),
+  `itemSpacing`, clicks past the last row, unmeasured renderables, and empty
+  lists. OpenTUI keeps `scrollOffset` and `linesPerItem` private, so this
+  arithmetic is read through a single narrow cast — the tests are what keep that
+  cast honest.
+- **12 integration tests** driving the real handlers with OpenTUI's mock mouse
+  against a live renderer: click-selects, double-click-opens, the double-click
+  window expiring, click-outside dismissal, row clicks _not_ leaking to the
+  enclosing panel, focus behaviour with and without `keepFocus`, and wheel
+  stepping including both ends of the list.
+- **4 button tests** asserting the corner button actually lands in the
+  bottom-right, that hidden buttons neither render nor take clicks, and that its
+  click does not bubble.
+
+The first two geometry tests failed on the run that wrote them, and caught a
+real off-by-one: the empty area below a short list returned "no row" instead of
+resolving to the last row, which would have dismissed an overlay instead of
+selecting its final entry. That is the exact class of bug that would have been
+very annoying and very hard to report.
+
+`test`, `format:check`, `lint` (Biome) and `typecheck` (tsc) are all green, and
+`bun run build` succeeds. The TUI was also driven end-to-end in a pty to confirm
+the menu opens from both `Esc` and the corner button, since the mock mouse does
+not exercise a real terminal's mouse reporting.

package/src/help.ts

@@ -30,7 +30,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "↑ ↓ / j k", action: "Move selection" },
         { keys: "Enter", action: "Open repo in browser" },
         { keys: "/", action: "Focus search input" },
-        { keys: "Space", action: "Open command menu" },
+        { keys: "Esc", action: "Open command menu" },
         { keys: "? / Ctrl+H", action: "Toggle this help screen" },
         { keys: "q", action: "Quit" },
       ],
@@ -65,6 +65,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "1-5", action: "Switch tab: Today → Week → Month → …" },
         { keys: "← → / h l", action: "Navigate tabs" },
       ],
+      note: "Tabs are also clickable.",
     },
     {
       title: " Packages Mode ",
@@ -73,12 +74,12 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "/", action: "Search npm packages" },
         { keys: "↑ ↓ / j k", action: "Move selection" },
         { keys: "Enter", action: "View package details" },
-        { keys: "Space", action: "Open command menu" },
+        { keys: "Esc", action: "Open command menu" },
       ],
       note: "Search by name, description, or tags. Sort by downloads or score.",
     },
     {
-      title: " Command Menu (Space)",
+      title: " Command Menu (Esc)",
       titleColor: "purple",
       rows: [
         { keys: "Sort", action: "Cycle sort: best-match → stars → …" },
@@ -103,7 +104,7 @@ export function buildHelpSections(): HelpSection[] {
         { keys: "History", action: "View search history" },
         { keys: "Help", action: "Show this help screen" },
       ],
-      note: "Navigate menu with ↑ ↓, select with Enter, back with ← / Esc",
+      note: "Navigate menu with ↑ ↓, select with Enter, back with ← / Esc. Clicking a row runs it directly. Esc (or the ☰ menu button) opens this menu; Space types a space in the query.",
     },
     {
       title: " Bookmarks Page ",
@@ -116,6 +117,22 @@ export function buildHelpSections(): HelpSection[] {
       ],
       note: "A full page, not an overlay — Esc returns to the mode menu.",
     },
+    {
+      title: " Mouse ",
+      titleColor: "green",
+      rows: [
+        { keys: "Click", action: "Select a row / card / tab" },
+        { keys: "Double-click", action: "Open the repo or run the action" },
+        { keys: "Scroll wheel", action: "Move the selection / scroll a pane" },
+        { keys: "Click outside", action: "Dismiss an open overlay" },
+        { keys: "Click query box", action: "Focus the search input" },
+        {
+          keys: "☰ menu button",
+          action: "Open the command menu (bottom-right)",
+        },
+      ],
+      note: "Every list is fully clickable; keyboard and mouse are interchangeable.",
+    },
     {
       title: " Overlay Keys ",
       titleColor: "teal",

package/src/tui/mouse.ts

@@ -0,0 +1,349 @@
+/**
+ * Mouse support for the ghfind TUI.
+ *
+ * OpenTUI already emits SGR mouse tracking and hit-tests every event into a
+ * `MouseEvent` whose `target` is the deepest renderable under the pointer
+ * (`Renderable.processMouseEvent`). Nothing in the shell consumed them, so the
+ * renderer threw the events away. This module turns them into the same
+ * affordances the keyboard already offers.
+ *
+ * Design notes (all verified against @opentui/core 0.4.5):
+ *
+ *  - `SelectRenderable` has no `onMouseEvent` override and no public row
+ *    geometry, so `hitIndexForY` reads `scrollOffset` / `linesPerItem` through
+ *    ONE narrow cast (see `selectRowGeometry`). If a future release renames
+ *    those fields the helper degrades to "no row" — clicks no-op instead of
+ *    throwing. Single choke point, easy to re-point.
+ *  - `setSelectedIndex` / `selectCurrent` both emit `selectionChanged` /
+ *    `itemSelected`, so clicks reuse the handlers the keyboard path already
+ *    drives (`src/tui.ts`) with zero duplicated logic.
+ *  - `dispatchMouseEvent` auto-focuses the nearest `focusable` ancestor on
+ *    left-press *unless the event is `defaultPrevented`*. `keepFocus: true`
+ *    calls `preventDefault()` so clicking a row never steals focus from the
+ *    query input.
+ *  - `processMouseEvent` bubbles to the parent unless `stopPropagation()` is
+ *    called, so every row handler stops it — otherwise a click would also fire
+ *    the enclosing panel's dismiss handler.
+ *  - Every `TextRenderable` defaults to `selectable: true`, and a left-press on
+ *    a selectable renderable is swallowed into a text-selection drag before the
+ *    shell ever sees it. `isInteractiveText()` marks the ones that must opt out.
+ */
+import type {
+  BoxRenderable,
+  CliRenderer,
+  SelectRenderable,
+} from "@opentui/core";
+
+/** Two clicks closer together than this count as a double-click. */
+export const DOUBLE_CLICK_MS = 400;
+
+/**
+ * Row geometry the hit test needs. `SelectRenderable` keeps all three fields
+ * private, so this is the structural shape `selectRowGeometry` projects onto.
+ */
+export interface SelectRowGeometry {
+  /** Row's screen-space top edge (`Renderable.screenY`). */
+  readonly screenY: number;
+  /** Visible viewport height in rows. */
+  readonly height: number;
+  /** Current option count. */
+  readonly optionCount: number;
+  /** Index of the first visible row (private `scrollOffset`). */
+  readonly scrollOffset: number;
+  /** Row pitch in terminal lines (private `linesPerItem`). */
+  readonly linesPerItem: number;
+}
+
+/** Public stand-in used by the tests — no OpenTUI renderer required. */
+export type SelectGeometryLike = SelectRowGeometry;
+
+/**
+ * Map a screen-space y coordinate to an option index, or -1 when the click
+ * misses every row (empty list, click below the last row, click past the
+ * viewport). Pure — no renderer state, so the off-by-one surface at scroll
+ * boundaries is directly testable.
+ */
+export function hitIndexForY(
+  geometry: SelectGeometryLike,
+  screenY: number,
+): number {
+  const pitch = geometry.linesPerItem;
+  // A zero/negative pitch means the renderable is unmeasured or malformed;
+  // treat every click as a miss rather than dividing by zero.
+  if (pitch <= 0) return -1;
+  if (geometry.optionCount <= 0) return -1;
+
+  const localY = screenY - geometry.screenY;
+  // Above the first row, or at/below the viewport's bottom edge.
+  if (localY < 0 || localY >= geometry.height) return -1;
+
+  const row = Math.floor(localY / pitch);
+  const index = geometry.scrollOffset + row;
+  // The last page of options is usually shorter than the viewport, leaving
+  // empty rows below it. Clamp those onto the final option rather than
+  // treating the click as a miss — a user aiming at the last row should land on
+  // it even when their pointer drifts a line or two.
+  const last = geometry.optionCount - 1;
+  if (index < 0) return 0;
+  return index > last ? last : index;
+}
+
+/**
+ * Project a `SelectRenderable` onto `SelectRowGeometry`.
+ *
+ * The single narrow cast in this module: `scrollOffset` and `linesPerItem` are
+ * declared `private` in OpenTUI's `.d.ts` but are plain instance fields at
+ * runtime (verified in `index.node.js`). A rename in a future release yields
+ * `undefined` → `pitch <= 0` → every click misses, which is a visible no-op
+ * rather than a crash.
+ */
+export function selectRowGeometry(select: SelectRenderable): SelectRowGeometry {
+  const internal = select as unknown as {
+    scrollOffset?: number;
+    linesPerItem?: number;
+  };
+  return {
+    screenY: select.screenY,
+    height: select.height,
+    optionCount: select.options.length,
+    scrollOffset: internal.scrollOffset ?? 0,
+    linesPerItem: internal.linesPerItem ?? 0,
+  };
+}
+
+export interface ClickToSelectOptions {
+  /**
+   * Runs the list's Enter-equivalent (open the URL, run the export, ...).
+   * Called on the second click of a double-click, and only when the row is
+   * already selected.
+   */
+  onOpen?: () => void;
+  /**
+   * Called when a click lands on the list but resolves to no row — the empty
+   * area under the last option. Full-screen overlays use it to dismiss on a
+   * click below their content.
+   */
+  onClickMiss?: () => void;
+  /**
+   * `true` for the main results list: `preventDefault()` the press so OpenTUI
+   * does not auto-focus the list away from the query input. Overlays leave it
+   * `false` so ↑↓ / Enter keep working right after a click.
+   */
+  keepFocus?: boolean;
+  /** Rows per wheel notch. Defaults to 3. */
+  wheelStep?: number;
+  /** Called with the row index as the pointer moves over the list. */
+  onHoverRow?: (index: number) => void;
+}
+
+export interface AttachedSelect {
+  /** Forget the pending double-click (call when the list's options change). */
+  reset(): void;
+  /** Row index the pointer last selected, or -1. Exposed for tests/status. */
+  readonly lastHovered: number;
+}
+
+/**
+ * Wire click-to-select, double-click-to-open, wheel scrolling, and hover
+ * feedback onto one `SelectRenderable`.
+ */
+export function attachClickToSelect(
+  renderer: CliRenderer,
+  select: SelectRenderable,
+  options: ClickToSelectOptions = {},
+): AttachedSelect {
+  const wheelStep = options.wheelStep ?? 3;
+  let lastClickIndex = -1;
+  let lastClickAt = 0;
+  let lastHovered = -1;
+
+  select.onMouseDown = (event) => {
+    // A click on the list must not also reach the enclosing overlay panel's
+    // dismiss handler, and must not steal focus from the query input.
+    event.stopPropagation();
+    if (options.keepFocus) event.preventDefault();
+
+    const index = hitIndexForY(selectRowGeometry(select), event.y);
+    if (index < 0) {
+      lastClickIndex = -1;
+      options.onClickMiss?.();
+      return;
+    }
+
+    const now = Date.now();
+    const alreadySelected = select.getSelectedIndex() === index;
+    const isDouble =
+      alreadySelected &&
+      index === lastClickIndex &&
+      now - lastClickAt < DOUBLE_CLICK_MS;
+
+    lastClickIndex = index;
+    lastClickAt = now;
+
+    if (isDouble) {
+      lastClickIndex = -1;
+      options.onOpen?.();
+      return;
+    }
+
+    // Emits `selectionChanged`, which the shell already uses to refresh the
+    // detail pane — the click path and the keyboard path converge here.
+    select.setSelectedIndex(index);
+  };
+
+  select.onMouseScroll = (event) => {
+    // Claim the wheel: without stopPropagation the renderer's focused-renderable
+    // fallback would also scroll whatever happens to hold focus.
+    event.stopPropagation();
+    const direction = event.scroll?.direction;
+    if (direction === "up") select.moveUp(wheelStep);
+    else if (direction === "down") select.moveDown(wheelStep);
+    // "left"/"right" belong to the scrollbar, not the list.
+    else return;
+    renderer.requestRender();
+  };
+
+  attachHoverHighlight(renderer, select, {
+    onHover: (index) => {
+      lastHovered = index;
+      options.onHoverRow?.(index);
+    },
+    // A stale row must never outlive the options it pointed at.
+    onLeave: () => {
+      lastHovered = -1;
+    },
+  });
+
+  return {
+    reset() {
+      lastClickIndex = -1;
+      lastClickAt = 0;
+    },
+    get lastHovered() {
+      return lastHovered;
+    },
+  };
+}
+
+export interface HoverOptions {
+  /** Row under the pointer, or -1 when the pointer left the list / missed. */
+  onHover?: (index: number) => void;
+  /** Called once when the pointer leaves the list. */
+  onLeave?: () => void;
+}
+
+/**
+ * Give a list a pointer cursor and a subtle background tint while hovered.
+ *
+ * A `SelectRenderable` can only tint its whole background (the selected row
+ * owns `selectedBackgroundColor`), so the hover state is a list-wide lift —
+ * enough to read as "this is live", without pretending to be per-row.
+ */
+export function attachHoverHighlight(
+  renderer: CliRenderer,
+  select: SelectRenderable,
+  options: HoverOptions = {},
+): void {
+  const idleBackground = select.backgroundColor;
+  // OpenTUI's `parseColor` only understands "transparent", CSS colour names,
+  // and 3/4/6/8-digit hex — an `rgba(...)` string silently resolves to magenta.
+  // A white tint at 6% alpha is the 8-digit-hex form of that.
+  const hoverBackground = "#ffffff0f";
+  let hovered = -1;
+
+  select.onMouseOver = () => {
+    renderer.setMousePointer("pointer");
+    select.backgroundColor = hoverBackground;
+    renderer.requestRender();
+  };
+
+  select.onMouseOut = () => {
+    renderer.setMousePointer("default");
+    select.backgroundColor = idleBackground;
+    if (hovered !== -1) {
+      hovered = -1;
+      options.onLeave?.();
+    }
+    renderer.requestRender();
+  };
+
+  // Report the row under the pointer, resolved exactly like a click — but only
+  // when it changed, so a stationary pointer does not re-render every frame.
+  select.onMouseMove = (event) => {
+    const index = hitIndexForY(selectRowGeometry(select), event.y);
+    if (index === hovered) return;
+    hovered = index;
+    options.onHover?.(index);
+  };
+}
+
+/**
+ * Dismiss a full-screen overlay when the click lands on the panel itself
+ * rather than on its content (border, padding, or a sibling region). Children
+ * that handle their own clicks call `stopPropagation()`, so this only fires for
+ * genuine outside-clicks.
+ */
+export function attachClickOutside(
+  target: BoxRenderable,
+  onDismiss: () => void,
+): void {
+  target.onMouseDown = (event) => {
+    event.stopPropagation();
+    onDismiss();
+  };
+}
+
+/**
+ * Make a non-list Box clickable: click runs `onActivate`, hovering swaps the
+ * border to the accent colour and shows a pointer cursor.
+ *
+ * `setBorder`/`getBorder` are passed in rather than imported so the unit tests
+ * can drive this with a plain object.
+ */
+export function attachClickableBox(
+  renderer: CliRenderer,
+  box: BoxRenderable,
+  handlers: {
+    onActivate: () => void;
+    /** Border colour while not hovered. */
+    idleBorder: string;
+    /** Border colour while hovered / selected. */
+    activeBorder: string;
+    onStateChange?: () => void;
+  },
+): void {
+  box.onMouseDown = (event) => {
+    event.stopPropagation();
+    handlers.onActivate();
+  };
+  box.onMouseOver = () => {
+    renderer.setMousePointer("pointer");
+    box.borderColor = handlers.activeBorder;
+    handlers.onStateChange?.();
+    renderer.requestRender();
+  };
+  box.onMouseOut = () => {
+    renderer.setMousePointer("default");
+    box.borderColor = handlers.idleBorder;
+    handlers.onStateChange?.();
+    renderer.requestRender();
+  };
+}
+
+/**
+ * Option-key that keeps a non-interactive `TextRenderable` from swallowing
+ * left-presses as a text-selection drag.
+ *
+ * Every `TextRenderable` (and `BoxRenderable`) defaults to `selectable: true`,
+ * and a left-press on a selectable renderable is turned into a selection drag
+ * *before* the shell's handlers run — so a click over such text does nothing.
+ * Pass this to every purely decorative renderable:
+ *
+ * ```ts
+ * new TextRenderable(renderer, { content: "", selectable: false })
+ * ```
+ *
+ * The query input keeps the default (`true`) so clicking into it still places
+ * the cursor.
+ */
+export const NON_INTERACTIVE_TEXT = { selectable: false } as const;