@tooee/shell 0.1.11 → 0.1.12

package/dist/search-hook.js

@@ -0,0 +1,120 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import { useCommand, useMode, useSetMode } from "@tooee/commands";
+const EMPTY = [];
+const CURSOR_MODES = ["cursor"];
+const ALL_MODES = ["cursor", "select", "insert"];
+export function useSearch({ match, onJump }) {
+    const mode = useMode();
+    const setMode = useSetMode();
+    const [searchQuery, setSearchQuery] = useState("");
+    const [searchActive, setSearchActive] = useState(false);
+    const [currentMatchIndex, setCurrentMatchIndex] = useState(0);
+    const [committedQuery, setCommittedQuery] = useState("");
+    const preSearchModeRef = useRef("cursor");
+    const matchRef = useRef(match);
+    matchRef.current = match;
+    const onJumpRef = useRef(onJump);
+    onJumpRef.current = onJump;
+    const activeQuery = searchActive ? searchQuery : committedQuery;
+    const matchingLines = useMemo(() => {
+        if (!activeQuery)
+            return EMPTY;
+        return matchRef.current(activeQuery);
+    }, [activeQuery]);
+    const matchingLinesRef = useRef(matchingLines);
+    matchingLinesRef.current = matchingLines;
+    // Imperatively set search query, reset match index, and jump to first match.
+    const updateSearchQuery = useCallback((query) => {
+        setSearchQuery(query);
+        setCurrentMatchIndex(0);
+        const matches = query ? matchRef.current(query) : [];
+        if (matches[0] != null) {
+            onJumpRef.current(matches[0]);
+        }
+    }, []);
+    useCommand({
+        id: "cursor-search-start",
+        title: "Search",
+        hotkey: "/",
+        modes: CURSOR_MODES,
+        handler: () => {
+            preSearchModeRef.current = mode;
+            setSearchActive(true);
+            setSearchQuery("");
+            setMode("insert");
+        },
+    });
+    useCommand({
+        id: "cursor-search-next",
+        title: "Next match",
+        hotkey: "n",
+        modes: CURSOR_MODES,
+        when: () => !searchActive,
+        handler: () => {
+            const matches = matchingLinesRef.current;
+            if (matches.length === 0)
+                return;
+            setCurrentMatchIndex((index) => {
+                const nextIndex = (index + 1) % matches.length;
+                const nextMatch = matches[nextIndex];
+                if (nextMatch != null) {
+                    onJumpRef.current(nextMatch);
+                }
+                return nextIndex;
+            });
+        },
+    });
+    useCommand({
+        id: "cursor-search-prev",
+        title: "Previous match",
+        hotkey: "shift+n",
+        modes: CURSOR_MODES,
+        when: () => !searchActive,
+        handler: () => {
+            const matches = matchingLinesRef.current;
+            if (matches.length === 0)
+                return;
+            setCurrentMatchIndex((index) => {
+                const nextIndex = (index - 1 + matches.length) % matches.length;
+                const nextMatch = matches[nextIndex];
+                if (nextMatch != null) {
+                    onJumpRef.current(nextMatch);
+                }
+                return nextIndex;
+            });
+        },
+    });
+    useCommand({
+        id: "search-cancel",
+        title: "Cancel search",
+        hotkey: "escape",
+        modes: ALL_MODES,
+        when: () => searchActive,
+        handler: () => {
+            setSearchActive(false);
+            setSearchQuery("");
+            setCommittedQuery("");
+            setCurrentMatchIndex(0);
+            setMode(preSearchModeRef.current);
+        },
+    });
+    const submitSearch = useCallback(() => {
+        setCommittedQuery(searchQuery);
+        setSearchActive(false);
+        setCurrentMatchIndex(0);
+        const matches = searchQuery ? matchRef.current(searchQuery) : [];
+        if (matches[0] != null) {
+            onJumpRef.current(matches[0]);
+        }
+        setMode(preSearchModeRef.current);
+    }, [searchQuery, setMode]);
+    return {
+        searchQuery,
+        searchActive,
+        setSearchQuery: updateSearchQuery,
+        matchingLines,
+        currentMatchIndex,
+        submitSearch,
+    };
+}
+//# sourceMappingURL=search-hook.js.map

package/dist/search-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-hook.js","sourceRoot":"","sources":["../src/search-hook.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@tooee/shell",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Composition layer wiring Tooee apps together",
+  "keywords": [
+    "cli",
+    "opentui",
+    "terminal",
+    "tui"
+  ],
+  "homepage": "https://github.com/gingerhendrix/tooee",
+  "bugs": "https://github.com/gingerhendrix/tooee/issues",
   "license": "MIT",
   "author": "Gareth Andrew",
   "repository": {
@@ -9,13 +17,9 @@
     "url": "https://github.com/gingerhendrix/tooee.git",
     "directory": "packages/shell"
   },
-  "homepage": "https://github.com/gingerhendrix/tooee",
-  "bugs": "https://github.com/gingerhendrix/tooee/issues",
-  "keywords": [
-    "tui",
-    "terminal",
-    "cli",
-    "opentui"
+  "files": [
+    "dist",
+    "src"
   ],
   "type": "module",
   "exports": {
@@ -26,22 +30,18 @@
       }
     }
   },
-  "files": [
-    "dist",
-    "src"
-  ],
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@tooee/commands": "0.1.11",
-    "@tooee/config": "0.1.11",
-    "@tooee/clipboard": "0.1.11",
-    "@tooee/toasts": "0.1.11",
-    "@tooee/layout": "0.1.11",
-    "@tooee/overlays": "0.1.11",
-    "@tooee/renderers": "0.1.11",
-    "@tooee/themes": "0.1.11"
+    "@tooee/clipboard": "0.1.12",
+    "@tooee/commands": "0.1.12",
+    "@tooee/config": "0.1.12",
+    "@tooee/layout": "0.1.12",
+    "@tooee/overlays": "0.1.12",
+    "@tooee/renderers": "0.1.12",
+    "@tooee/themes": "0.1.12",
+    "@tooee/toasts": "0.1.12"
   },
   "devDependencies": {
     "@opentui/core": "^0.1.86",

package/src/command-palette-provider.tsx

@@ -0,0 +1,39 @@
+import { useCallback, useRef, type ReactNode } from "react"
+import { createElement } from "react"
+import { useCommand, useMode } from "@tooee/commands"
+import type { Mode } from "@tooee/commands"
+import { useOverlay } from "@tooee/overlays"
+import type { OverlayCloseReason } from "@tooee/overlays"
+import { CommandPaletteOverlay } from "./CommandPaletteOverlay.js"
+
+const OVERLAY_ID = "command-palette"
+
+export function CommandPaletteProvider({ children }: { children: ReactNode }) {
+  const mode = useMode()
+  const overlay = useOverlay()
+  const launchModeRef = useRef<Mode>(mode)
+
+  const open = useCallback(() => {
+    launchModeRef.current = mode
+    overlay.open(
+      OVERLAY_ID,
+      ({ close }: { close: (reason?: OverlayCloseReason) => void }) =>
+        createElement(CommandPaletteOverlay, {
+          launchMode: mode,
+          close: () => close(),
+        }),
+      null,
+      { mode: "insert", dismissOnEscape: true },
+    )
+  }, [overlay, mode])
+
+  useCommand({
+    id: "command-palette",
+    title: "Command Palette",
+    hotkey: ":",
+    modes: ["cursor", "select"],
+    handler: open,
+  })
+
+  return <>{children}</>
+}

package/src/commands.ts

@@ -1,5 +1,5 @@
 import { useRenderer } from "@opentui/react"
-import { copyToClipboard } from "@tooee/clipboard"
+import { copyToClipboard, readClipboardText, readPrimaryText } from "@tooee/clipboard"
 import { useCommand, type CommandWhen } from "@tooee/commands"
 import { useToast } from "@tooee/toasts"
 import { useThemePicker, type ThemePickerState } from "./theme-picker.js"
@@ -73,6 +73,60 @@ export function useCopyCommand(opts: { getText: () => string | undefined; when?:
   })
 }
 
+export function usePasteCommands(opts: {
+  getTarget: () => { insertText: (text: string) => void } | null
+  when?: CommandWhen
+}) {
+  useCommand({
+    id: "paste-clipboard",
+    title: "Paste from clipboard",
+    hotkey: "p",
+    when: opts.when,
+    handler: (ctx) => {
+      const target = opts.getTarget()
+      if (!target) return
+      void readClipboardText().then((text) => {
+        if (text) {
+          target.insertText(text)
+        } else {
+          ctx.toast.toast({ message: "Clipboard empty", level: "warning" })
+        }
+      })
+    },
+  })
+
+  useCommand({
+    id: "paste-primary",
+    title: "Paste from selection",
+    when: opts.when,
+    handler: (ctx) => {
+      const target = opts.getTarget()
+      if (!target) return
+      void readPrimaryText().then((text) => {
+        if (text) {
+          target.insertText(text)
+        } else {
+          ctx.toast.toast({ message: "Selection empty", level: "warning" })
+        }
+      })
+    },
+  })
+}
+
+export function useDebugConsoleCommand(opts?: { when?: CommandWhen }) {
+  const renderer = useRenderer()
+
+  useCommand({
+    id: "toggle-debug-console",
+    title: "Toggle debug console",
+    hotkey: "ctrl+shift+j",
+    when: opts?.when,
+    handler: () => {
+      renderer.console.toggle()
+    },
+  })
+}
+
 export function useToggleLineNumbersCommand(opts: {
   showLineNumbers: boolean
   onToggle: () => void

package/src/copy-hook.ts

@@ -0,0 +1,45 @@
+import { useCommand, useSetMode } from "@tooee/commands"
+import { copyToClipboard } from "@tooee/clipboard"
+import type { Position } from "./navigation.js"
+
+export interface UseCopyOptions {
+  getRowText: (index: number) => string
+  cursor: Position | null
+  selection: { start: Position; end: Position } | null
+  toggledIndices: Set<number>
+}
+
+export function useCopy({ getRowText, cursor, selection, toggledIndices }: UseCopyOptions): void {
+  const setMode = useSetMode()
+
+  useCommand({
+    id: "select-copy",
+    title: "Copy selection",
+    hotkey: "y",
+    modes: ["select"],
+    handler: () => {
+      let text = ""
+
+      if (toggledIndices.size > 0) {
+        text = Array.from(toggledIndices)
+          .sort((left, right) => left - right)
+          .map((index) => getRowText(index))
+          .join("\n")
+      } else if (selection) {
+        const rows: string[] = []
+        for (let index = selection.start.line; index <= selection.end.line; index++) {
+          rows.push(getRowText(index))
+        }
+        text = rows.join("\n")
+      } else if (cursor) {
+        text = getRowText(cursor.line)
+      }
+
+      if (text) {
+        void copyToClipboard(text)
+      }
+
+      setMode("cursor")
+    },
+  })
+}

package/src/copy-on-select.ts

@@ -13,10 +13,7 @@ export function useCopyOnSelect() {
     const copyOnSelect = config.view?.copyOnSelect
 
     // Default: on for Linux, off elsewhere
-    const effective =
-      copyOnSelect === undefined
-        ? platform() === "linux"
-        : copyOnSelect
+    const effective = copyOnSelect === undefined ? platform() === "linux" : copyOnSelect
 
     if (!effective) return
 

package/src/index.ts

@@ -1,11 +1,21 @@
-export { useThemeCommands, useQuitCommand, useCopyCommand, useToggleLineNumbersCommand } from "./commands.js"
-export { useModalNavigationCommands } from "./modal.js"
-export type { ModalNavigationState, ModalNavigationOptions, Position } from "./modal.js"
+export {
+  useThemeCommands,
+  useQuitCommand,
+  useCopyCommand,
+  usePasteCommands,
+  useToggleLineNumbersCommand,
+  useDebugConsoleCommand,
+} from "./commands.js"
+export { useNavigation } from "./navigation.js"
+export type { UseNavigationOptions, NavigationState, Position } from "./navigation.js"
+export { useSearch } from "./search-hook.js"
+export type { UseSearchOptions, SearchState } from "./search-hook.js"
+export { useCopy } from "./copy-hook.js"
+export type { UseCopyOptions } from "./copy-hook.js"
 export { findMatchingLines } from "./search.js"
 export { TooeeProvider } from "./provider.js"
 export { launchCli, guardTerminalHealth } from "./launch.js"
-export { useCommandPalette } from "./command-palette.js"
-export type { CommandPaletteState } from "./command-palette.js"
+export { CommandPaletteProvider } from "./command-palette-provider.js"
 export { useThemePicker } from "./theme-picker.js"
 export type { ThemePickerState, ThemePickerEntry } from "./theme-picker.js"
 export { OverlayProvider } from "./overlay.js"

package/src/navigation.ts

@@ -0,0 +1,297 @@
+import { useCallback, useMemo, useRef, useState } from "react"
+import { useTerminalDimensions } from "@opentui/react"
+import { useCommand, useMode, useSetMode, type Mode } from "@tooee/commands"
+
+export interface Position {
+  line: number
+  col: number
+}
+
+const CURSOR_MODES: Mode[] = ["cursor"]
+const SELECT_MODES: Mode[] = ["select"]
+
+export interface UseNavigationOptions {
+  rowCount: number
+  isSelectable?: (index: number) => boolean
+  viewportHeight?: number
+  multiSelect?: boolean
+}
+
+export interface NavigationState {
+  mode: Mode
+  setMode: (mode: Mode) => void
+  cursor: Position | null
+  setCursor: (line: number) => void
+  selection: { start: Position; end: Position } | null
+  toggledIndices: Set<number>
+}
+
+function defaultIsSelectable(): boolean {
+  return true
+}
+
+export function useNavigation({
+  rowCount,
+  isSelectable = defaultIsSelectable,
+  viewportHeight,
+  multiSelect = false,
+}: UseNavigationOptions): NavigationState {
+  const { height: terminalHeight } = useTerminalDimensions()
+  const effectiveViewportHeight = viewportHeight ?? Math.max(1, terminalHeight - 2)
+  const mode = useMode()
+  const setMode = useSetMode()
+
+  const maxIndex = Math.max(0, rowCount - 1)
+
+  const clampIndex = useCallback(
+    (index: number) => Math.max(0, Math.min(index, maxIndex)),
+    [maxIndex],
+  )
+
+  const findSelectable = useCallback(
+    (start: number, direction: 1 | -1) => {
+      if (rowCount <= 0) return null
+      const initial = Math.max(0, Math.min(start, maxIndex))
+      for (
+        let index = initial;
+        direction === 1 ? index <= maxIndex : index >= 0;
+        index += direction
+      ) {
+        if (isSelectable(index)) return index
+      }
+      return null
+    },
+    [rowCount, maxIndex, isSelectable],
+  )
+
+  const resolveSelectable = useCallback(
+    (target: number, preferredDirection: 1 | -1 = 1) => {
+      if (rowCount <= 0) return null
+      const clamped = Math.max(0, Math.min(target, maxIndex))
+      if (isSelectable(clamped)) return clamped
+      return preferredDirection === 1
+        ? findSelectable(clamped, 1) ?? findSelectable(clamped, -1)
+        : findSelectable(clamped, -1) ?? findSelectable(clamped, 1)
+    },
+    [rowCount, maxIndex, isSelectable, findSelectable],
+  )
+
+  const [rawCursor, setRawCursor] = useState<Position | null>(() => {
+    const line = resolveSelectable(0, 1)
+    return line == null ? null : { line, col: 0 }
+  })
+
+  // Derive valid cursor from raw cursor + constraints
+  const cursor = useMemo(() => {
+    if (rowCount <= 0) return null
+    if (!rawCursor) {
+      if (mode !== "cursor") return null
+      const line = resolveSelectable(0, 1)
+      return line == null ? null : { line, col: 0 }
+    }
+    const preferredDirection: 1 | -1 = rawCursor.line > maxIndex ? -1 : 1
+    const resolved = resolveSelectable(rawCursor.line, preferredDirection)
+    if (resolved == null) return null
+    if (resolved === rawCursor.line) return rawCursor
+    return { line: resolved, col: 0 }
+  }, [rawCursor, rowCount, maxIndex, mode, resolveSelectable])
+
+  const cursorRef = useRef(cursor)
+  cursorRef.current = cursor
+  const [selectionAnchor, setSelectionAnchor] = useState<Position | null>(null)
+  const [rawToggledIndices, setRawToggledIndices] = useState<Set<number>>(new Set())
+
+  // Derive valid toggled indices (filter out-of-bounds)
+  const toggledIndices = useMemo(() => {
+    if (rowCount <= 0) return new Set<number>()
+    let needsFilter = false
+    for (const i of rawToggledIndices) {
+      if (i >= rowCount) { needsFilter = true; break }
+    }
+    if (!needsFilter) return rawToggledIndices
+    return new Set(Array.from(rawToggledIndices).filter(i => i < rowCount))
+  }, [rawToggledIndices, rowCount])
+
+  const setCursor = useCallback(
+    (line: number) => {
+      setRawCursor((current) => {
+        const preferredDirection: 1 | -1 = current && line < current.line ? -1 : 1
+        const nextLine = resolveSelectable(line, preferredDirection)
+        if (nextLine == null) return null
+        if (current && nextLine === current.line) return current
+        return { line: nextLine, col: 0 }
+      })
+    },
+    [resolveSelectable],
+  )
+
+  const moveCursor = useCallback(
+    (delta: number) => {
+      setRawCursor((current) => {
+        if (!current) return current
+        const target = clampIndex(current.line + delta)
+        const preferredDirection: 1 | -1 = delta < 0 ? -1 : 1
+        const nextLine = resolveSelectable(target, preferredDirection)
+        if (nextLine == null) return current
+        if (nextLine === current.line) return current
+        return { line: nextLine, col: 0 }
+      })
+    },
+    [clampIndex, resolveSelectable],
+  )
+
+  const jumpCursor = useCallback(
+    (target: number, preferredDirection: 1 | -1) => {
+      const nextLine = resolveSelectable(target, preferredDirection)
+      setRawCursor(nextLine == null ? null : { line: nextLine, col: 0 })
+    },
+    [resolveSelectable],
+  )
+
+  const toggleCurrent = useCallback(() => {
+    const cur = cursorRef.current
+    if (!cur) return
+    setRawToggledIndices((prev) => {
+      const next = new Set(prev)
+      if (next.has(cur.line)) {
+        next.delete(cur.line)
+      } else {
+        next.add(cur.line)
+      }
+      return next
+    })
+  }, [])
+
+  useCommand({
+    id: "cursor-down",
+    title: "Cursor down",
+    hotkey: "j",
+    modes: CURSOR_MODES,
+    handler: () => moveCursor(1),
+  })
+
+  useCommand({
+    id: "cursor-up",
+    title: "Cursor up",
+    hotkey: "k",
+    modes: CURSOR_MODES,
+    handler: () => moveCursor(-1),
+  })
+
+  useCommand({
+    id: "cursor-half-down",
+    title: "Cursor half page down",
+    hotkey: "ctrl+d",
+    modes: CURSOR_MODES,
+    handler: () => moveCursor(Math.floor(effectiveViewportHeight / 2) || 1),
+  })
+
+  useCommand({
+    id: "cursor-half-up",
+    title: "Cursor half page up",
+    hotkey: "ctrl+u",
+    modes: CURSOR_MODES,
+    handler: () => moveCursor(-(Math.floor(effectiveViewportHeight / 2) || 1)),
+  })
+
+  useCommand({
+    id: "cursor-top",
+    title: "Cursor to top",
+    hotkey: "g g",
+    modes: CURSOR_MODES,
+    handler: () => jumpCursor(0, 1),
+  })
+
+  useCommand({
+    id: "cursor-bottom",
+    title: "Cursor to bottom",
+    hotkey: "shift+g",
+    modes: CURSOR_MODES,
+    handler: () => jumpCursor(maxIndex, -1),
+  })
+
+  useCommand({
+    id: "enter-select",
+    title: "Enter select mode",
+    hotkey: "v",
+    modes: CURSOR_MODES,
+    handler: () => {
+      setSelectionAnchor(cursorRef.current ? { ...cursorRef.current } : null)
+      setMode("select")
+    },
+  })
+
+  useCommand({
+    id: "cursor-toggle",
+    title: "Toggle selection",
+    hotkey: "tab",
+    modes: CURSOR_MODES,
+    when: () => multiSelect,
+    handler: toggleCurrent,
+  })
+
+  useCommand({
+    id: "cursor-toggle-up",
+    title: "Toggle and move up",
+    hotkey: "shift+tab",
+    modes: CURSOR_MODES,
+    when: () => multiSelect,
+    handler: () => {
+      toggleCurrent()
+      moveCursor(-1)
+    },
+  })
+
+  useCommand({
+    id: "select-down",
+    title: "Extend selection down",
+    hotkey: "j",
+    modes: SELECT_MODES,
+    handler: () => moveCursor(1),
+  })
+
+  useCommand({
+    id: "select-up",
+    title: "Extend selection up",
+    hotkey: "k",
+    modes: SELECT_MODES,
+    handler: () => moveCursor(-1),
+  })
+
+  useCommand({
+    id: "select-toggle",
+    title: "Toggle selection",
+    hotkey: "tab",
+    modes: SELECT_MODES,
+    when: () => multiSelect,
+    handler: toggleCurrent,
+  })
+
+  useCommand({
+    id: "select-cancel",
+    title: "Cancel selection",
+    hotkey: "escape",
+    modes: SELECT_MODES,
+    handler: () => {
+      setSelectionAnchor(null)
+      setMode("cursor")
+    },
+  })
+
+  const selection =
+    mode === "select" && selectionAnchor && cursor
+      ? {
+          start: selectionAnchor.line <= cursor.line ? selectionAnchor : cursor,
+          end: selectionAnchor.line <= cursor.line ? cursor : selectionAnchor,
+        }
+      : null
+
+  return {
+    mode,
+    setMode,
+    cursor,
+    setCursor,
+    selection,
+    toggledIndices,
+  }
+}