@tooee/choose 0.1.22 → 0.2.1

package/src/ChooseList.tsx

@@ -0,0 +1,137 @@
+import { useEffect, useRef, type ReactNode } from "react"
+import type { ScrollBoxRenderable } from "@opentui/core"
+import { useTheme } from "@tooee/themes"
+import { ChooseHighlightedText } from "./ChooseHighlightedText.js"
+import type { FuzzyMatch } from "./fuzzy.js"
+import type { ChooseItem } from "./types.js"
+import type { UseChooseResult } from "./use-choose.js"
+
+export interface ChooseItemRenderContext {
+  item: ChooseItem
+  match: FuzzyMatch
+  index: number
+  originalIndex: number
+  positions: number[]
+  isActive: boolean
+  isSelected: boolean
+  defaultContent: ReactNode
+}
+
+export interface ChooseListProps {
+  choose: UseChooseResult
+  /** Fullscreen defaults to activate; picker overlays default to submit. */
+  rowClick?: "activate" | "submit" | "none"
+  renderItem?: (context: ChooseItemRenderContext) => ReactNode
+  loadingContent?: ReactNode
+  errorContent?: (error: string) => ReactNode
+  emptyContent?: ReactNode
+  /** Mouse guard for visible rows covered by another surface. */
+  suspended?: boolean
+}
+
+function ThemedLine({ content, color }: { content: ReactNode; color: string }) {
+  return (
+    <box height={1} style={{ paddingLeft: 2 }}>
+      {typeof content === "string" ? <text content={content} fg={color} /> : content}
+    </box>
+  )
+}
+
+function defaultErrorContent(error: string): ReactNode {
+  return `Error: ${error}`
+}
+
+/** Scrollable chooser rows plus loading/error/empty presentation. */
+export function ChooseList({
+  choose,
+  rowClick = "activate",
+  renderItem,
+  loadingContent = "Loading...",
+  errorContent = defaultErrorContent,
+  emptyContent,
+  suspended,
+}: ChooseListProps) {
+  const { theme } = useTheme()
+  const scrollRef = useRef<ScrollBoxRenderable>(null)
+  const { state, controller } = choose
+  const interactionSuspended = choose.view.suspended || (suspended ?? false)
+
+  useEffect(() => {
+    if (scrollRef.current && state.matches.length > 0) {
+      scrollRef.current.scrollTop = Math.max(0, state.activeIndex - 5)
+    }
+  }, [state.activeIndex, state.matches.length])
+
+  return (
+    <scrollbox ref={scrollRef} flexDirection="column" style={{ flexGrow: 1 }} focused={false}>
+      {state.loading && <ThemedLine content={loadingContent} color={theme.textMuted} />}
+
+      {!state.loading && state.error && (
+        <ThemedLine content={errorContent(state.error)} color={theme.error} />
+      )}
+
+      {!state.loading && !state.error && state.matches.length === 0 && emptyContent != null && (
+        <ThemedLine content={emptyContent} color={theme.textMuted} />
+      )}
+
+      {state.matches.map((match, index) => {
+        const isActive = index === state.activeIndex
+        const isSelected = state.selectedOriginalIndices.has(match.originalIndex)
+        const defaultContent = (
+          <>
+            {state.multi && (
+              <text
+                content={isSelected ? "✓ " : "  "}
+                fg={isSelected ? theme.accent : theme.textMuted}
+              />
+            )}
+            {match.item.icon && <text content={`${match.item.icon} `} fg={theme.textMuted} />}
+            <text fg={isActive ? theme.primary : theme.text}>
+              <ChooseHighlightedText
+                text={match.item.text}
+                positions={match.positions}
+                highlightColor={theme.warning}
+              />
+            </text>
+            {match.item.description && (
+              <text content={`  ${match.item.description}`} fg={theme.textMuted} />
+            )}
+          </>
+        )
+        const context: ChooseItemRenderContext = {
+          item: match.item,
+          match,
+          index,
+          originalIndex: match.originalIndex,
+          positions: match.positions,
+          isActive,
+          isSelected,
+          defaultContent,
+        }
+
+        return (
+          <box
+            key={match.originalIndex}
+            flexDirection="row"
+            height={1}
+            backgroundColor={isActive ? theme.backgroundElement : undefined}
+            style={{ paddingLeft: 1 }}
+            onMouseDown={(event) => {
+              if (interactionSuspended || event.button !== 0 || rowClick === "none") return
+              if (rowClick === "submit") {
+                event.preventDefault()
+                event.stopPropagation()
+                controller.setActiveIndex(index)
+                controller.submit()
+              } else {
+                controller.setActiveIndex(index)
+              }
+            }}
+          >
+            {renderItem ? renderItem(context) : defaultContent}
+          </box>
+        )
+      })}
+    </scrollbox>
+  )
+}

package/src/ChooseOverlay.tsx

@@ -1,322 +1,88 @@
-import { useState, useEffect, useRef, useCallback, useMemo } from "react"
-import type { ScrollBoxRenderable } from "@opentui/core"
-import { useTheme, CloseButton } from "@tooee/themes"
-import { useCommand, useMode, useSetMode } from "@tooee/commands"
-import type { ChooseItem } from "./types.js"
-import { fuzzyFilter } from "./fuzzy.js"
-
-export interface ChooseOverlayProps {
-  items: ChooseItem[] | (() => Promise<ChooseItem[]>)
+import { useImperativeHandle, type ReactNode, type Ref } from "react"
+import type { ActionDefinition } from "@tooee/commands"
+import { ChooseFilter } from "./ChooseFilter.js"
+import { ChooseList, type ChooseListProps } from "./ChooseList.js"
+import { ChoosePanel, type ChoosePanelProps } from "./ChoosePanel.js"
+import type { ChooseItem, ChooseResult, ChooseSource } from "./types.js"
+import { useChoose, type ChooseController } from "./use-choose.js"
+
+interface ChooseOverlayBaseProps {
+  items: ChooseSource
   prompt?: string
   placeholder?: string
   emptyMessage?: string
-  onSelect: (item: ChooseItem) => void | Promise<void>
   onCancel: () => void
+  commands?: ActionDefinition[]
+  controllerRef?: Ref<ChooseController>
+  renderItem?: ChooseListProps["renderItem"]
+  hints?: ChoosePanelProps["hints"]
+  statusRight?: ReactNode
+  footer?: ReactNode
+  inset?: ChoosePanelProps["inset"]
+  /** Nested modal content rendered above the chooser panel. */
+  children?: ReactNode
+  /** Explicit interaction guard for legacy child overlays without a command surface. */
+  suspended?: boolean
 }
 
-export function ChooseOverlay({
-  items: itemsOrLoader,
-  prompt,
-  placeholder,
-  emptyMessage,
-  onSelect,
-  onCancel,
-}: ChooseOverlayProps) {
-  const { theme } = useTheme()
-  const mode = useMode()
-  const setMode = useSetMode()
-
-  const [items, setItems] = useState<ChooseItem[]>(
-    Array.isArray(itemsOrLoader) ? itemsOrLoader : [],
-  )
-  const [loading, setLoading] = useState(!Array.isArray(itemsOrLoader))
-  const [error, setError] = useState<string | null>(null)
-  const [filterQuery, setFilterQuery] = useState("")
-  const [activeIndex, setActiveIndex] = useState(0)
-  const scrollRef = useRef<ScrollBoxRenderable>(null)
-
-  // Load items if async loader provided
-  useEffect(() => {
-    if (typeof itemsOrLoader === "function") {
-      let active = true
-      setLoading(true)
-      setError(null)
-      itemsOrLoader()
-        .then((loaded) => {
-          // Ignore stale results after itemsOrLoader changed
-          if (!active) return
-          setItems(loaded)
-          setLoading(false)
-        })
-        .catch((err: unknown) => {
-          if (!active) return
-          setItems([])
-          setError(err instanceof Error ? err.message : String(err))
-          setLoading(false)
-        })
-      return () => {
-        active = false
+export type ChooseOverlayProps = ChooseOverlayBaseProps &
+  (
+    | {
+        multi?: false
+        onSelect: (item: ChooseItem) => void | Promise<void>
+        onSubmit?: never
       }
-    }
-  }, [itemsOrLoader])
-
-  // Filtered items via fuzzy matching
-  const filteredItems = useMemo(() => fuzzyFilter(items, filterQuery), [items, filterQuery])
-
-  // Reset activeIndex when filter changes
-  const [prevFilterQuery, setPrevFilterQuery] = useState("")
-  if (filterQuery !== prevFilterQuery) {
-    setPrevFilterQuery(filterQuery)
-    setActiveIndex(0)
-  }
-
-  const moveUp = useCallback(() => {
-    setActiveIndex((i) => Math.max(0, i - 1))
-  }, [])
-
-  const moveDown = useCallback(() => {
-    setActiveIndex((i) => Math.min(filteredItems.length - 1, i + 1))
-  }, [filteredItems.length])
-
-  const confirm = useCallback(() => {
-    const match = filteredItems[activeIndex]
-    if (match) {
-      onSelect(match.item)
-    }
-  }, [filteredItems, activeIndex, onSelect])
-
-  const leaveInsertModeOrCancel = useCallback(() => {
-    if (mode === "insert") {
-      setMode("cursor")
-    } else {
-      onCancel()
-    }
-  }, [mode, onCancel, setMode])
-
-  const enterInsertMode = useCallback(() => {
-    setMode("insert")
-  }, [setMode])
+    | {
+        multi: true
+        onSubmit: (result: ChooseResult) => void | Promise<void>
+        onSelect?: never
+      }
+  )
 
-  useCommand({
-    id: "choose-overlay:escape",
-    title: "Back / cancel",
-    hotkey: "Escape",
-    modes: ["insert", "cursor"],
-    hidden: true,
-    handler: leaveInsertModeOrCancel,
-  })
-  useCommand({
-    id: "choose-overlay:insert-mode-i",
-    title: "Insert mode",
-    hotkey: "i",
-    modes: ["cursor"],
-    hidden: true,
-    handler: enterInsertMode,
-  })
-  useCommand({
-    id: "choose-overlay:insert-mode-a",
-    title: "Insert mode",
-    hotkey: "a",
-    modes: ["cursor"],
-    hidden: true,
-    handler: enterInsertMode,
-  })
-  useCommand({
-    id: "choose-overlay:move-down-vim",
-    title: "Move down",
-    hotkey: "j",
-    modes: ["cursor"],
-    hidden: true,
-    handler: moveDown,
-  })
-  useCommand({
-    id: "choose-overlay:move-up-vim",
-    title: "Move up",
-    hotkey: "k",
-    modes: ["cursor"],
-    hidden: true,
-    handler: moveUp,
-  })
-  useCommand({
-    id: "choose-overlay:confirm",
-    title: "Confirm",
-    hotkey: "Enter",
-    modes: ["insert", "cursor"],
-    hidden: true,
-    handler: confirm,
+/**
+ * Composed picker surface. Hosts should mount it on an owned modal command
+ * surface (as Tooee's overlay manager does) so nested surfaces suspend it.
+ */
+export function ChooseOverlay(props: ChooseOverlayProps) {
+  const multi = props.multi === true
+  const choose = useChoose({
+    source: props.items,
+    multi,
+    onSubmit: (result) => {
+      if (multi) return props.onSubmit(result)
+      const item = result.items[0]
+      if (item) return props.onSelect(item)
+    },
+    onCancel: props.onCancel,
+    commands: props.commands,
+    commandScope: "choose-overlay",
+    suspended: props.suspended,
   })
-  useCommand({
-    id: "choose-overlay:move-up",
-    title: "Move up",
-    hotkey: "up",
-    modes: ["insert", "cursor"],
-    hidden: true,
-    handler: moveUp,
-  })
-  useCommand({
-    id: "choose-overlay:move-up-ctrl-p",
-    title: "Move up",
-    hotkey: "ctrl+p",
-    modes: ["insert", "cursor"],
-    hidden: true,
-    handler: moveUp,
-  })
-  useCommand({
-    id: "choose-overlay:move-down",
-    title: "Move down",
-    hotkey: "down",
-    modes: ["insert", "cursor"],
-    hidden: true,
-    handler: moveDown,
-  })
-  useCommand({
-    id: "choose-overlay:move-down-ctrl-n",
-    title: "Move down",
-    hotkey: "ctrl+n",
-    modes: ["insert", "cursor"],
-    hidden: true,
-    handler: moveDown,
-  })
-
-  // Auto-scroll to keep active item visible
-  useEffect(() => {
-    if (scrollRef.current && filteredItems.length > 0) {
-      scrollRef.current.scrollTop = Math.max(0, activeIndex - 5)
-    }
-  }, [activeIndex, filteredItems.length])
 
-  const hintText =
-    mode === "insert" ? "Enter confirm  Esc commands" : "j/k navigate  i insert  Esc cancel"
+  useImperativeHandle(props.controllerRef, () => choose.controller, [choose.controller])
 
   return (
-    <box
-      position="absolute"
-      left="20%"
-      right="20%"
-      top="20%"
-      bottom="20%"
-      flexDirection="column"
-      backgroundColor={theme.backgroundPanel}
-      border
-      borderColor={theme.borderActive}
-    >
-      {/* Title bar */}
-      {prompt && (
-        <box height={1} paddingLeft={1} paddingRight={1} backgroundColor={theme.backgroundElement}>
-          <text content={prompt} fg={theme.accent} />
-        </box>
-      )}
-
-      {/* Filter input row */}
-      <box flexDirection="row" height={1} style={{ paddingLeft: 1, paddingRight: 1 }}>
-        <text content="> " fg={theme.accent} />
-        <input
-          focused={mode === "insert"}
-          placeholder={placeholder ?? "Filter..."}
-          onInput={setFilterQuery}
-          backgroundColor="transparent"
-          textColor={theme.text}
-          placeholderColor={theme.textMuted}
-          cursorColor={theme.primary}
-          style={{ flexGrow: 1 }}
+    <>
+      <ChoosePanel
+        title={props.prompt}
+        filter={
+          <ChooseFilter choose={choose} placeholder={props.placeholder} onClose={props.onCancel} />
+        }
+        multi={multi}
+        hints={props.hints}
+        statusRight={props.statusRight}
+        footer={props.footer}
+        inset={props.inset}
+      >
+        <ChooseList
+          choose={choose}
+          rowClick="submit"
+          renderItem={props.renderItem}
+          emptyContent={props.emptyMessage}
+          suspended={props.suspended}
         />
-        <text content={` ${filteredItems.length}/${items.length}`} fg={theme.textMuted} />
-        <CloseButton onClose={onCancel} />
-      </box>
-
-      {/* Scrollable item list */}
-      <scrollbox ref={scrollRef} flexDirection="column" style={{ flexGrow: 1 }} focused={false}>
-        {loading && (
-          <box height={1} style={{ paddingLeft: 2 }}>
-            <text content="Loading..." fg={theme.textMuted} />
-          </box>
-        )}
-
-        {!loading && error && (
-          <box height={1} style={{ paddingLeft: 2 }}>
-            <text content={`Error: ${error}`} fg={theme.error} />
-          </box>
-        )}
-
-        {!loading && !error && filteredItems.length === 0 && emptyMessage && (
-          <box height={1} style={{ paddingLeft: 2 }}>
-            <text content={emptyMessage} fg={theme.textMuted} />
-          </box>
-        )}
-
-        {filteredItems.map((match, idx) => {
-          const isActive = idx === activeIndex
-          return (
-            <box
-              key={match.originalIndex}
-              flexDirection="row"
-              height={1}
-              backgroundColor={isActive ? theme.backgroundElement : undefined}
-              style={{ paddingLeft: 1 }}
-              onMouseDown={(event) => {
-                // Left-click picks the item — same code path as Enter confirm.
-                // (Standalone Choose keeps click-to-highlight; a modal picker
-                // overlay follows menu semantics like ContextMenu instead.)
-                if (event.button !== 0) return
-                event.preventDefault()
-                event.stopPropagation()
-                onSelect(match.item)
-              }}
-            >
-              {match.item.icon && <text content={`${match.item.icon} `} fg={theme.textMuted} />}
-              <text fg={isActive ? theme.primary : theme.text}>
-                {renderHighlightedText(match.item.text, match.positions, theme.warning)}
-              </text>
-              {match.item.description && (
-                <text content={`  ${match.item.description}`} fg={theme.textMuted} />
-              )}
-            </box>
-          )
-        })}
-      </scrollbox>
-
-      {/* Hint line */}
-      <box height={1} paddingLeft={1} paddingRight={1} backgroundColor={theme.backgroundElement}>
-        <text content={hintText} fg={theme.textMuted} />
-      </box>
-    </box>
-  )
-}
-
-function renderHighlightedText(text: string, positions: number[], highlightColor: string) {
-  if (positions.length === 0) {
-    return text
-  }
-
-  const posSet = new Set(positions)
-  const parts: Array<{ text: string; highlight: boolean }> = []
-  let current = ""
-  let currentHighlight = false
-
-  for (let i = 0; i < text.length; i++) {
-    const isHighlight = posSet.has(i)
-    if (i === 0) {
-      currentHighlight = isHighlight
-      current = text[i]
-    } else if (isHighlight === currentHighlight) {
-      current += text[i]
-    } else {
-      parts.push({ text: current, highlight: currentHighlight })
-      current = text[i]
-      currentHighlight = isHighlight
-    }
-  }
-  if (current) {
-    parts.push({ text: current, highlight: currentHighlight })
-  }
-
-  return parts.map((part, i) =>
-    part.highlight ? (
-      <span key={i} fg={highlightColor}>
-        {part.text}
-      </span>
-    ) : (
-      part.text
-    ),
+      </ChoosePanel>
+      {props.children}
+    </>
   )
 }

package/src/ChoosePanel.tsx

@@ -0,0 +1,123 @@
+import type { ReactNode } from "react"
+import { useMode, type Mode } from "@tooee/commands"
+import { CloseButton, useTheme } from "@tooee/themes"
+
+export function buildChooseHints(
+  mode: Mode,
+  options: { multi?: boolean; extra?: string[] } = {},
+): string[] {
+  const base =
+    mode === "insert"
+      ? ["↑↓ navigate", "Enter confirm", ...(options.multi ? ["Tab toggle"] : []), "Esc commands"]
+      : [
+          "j/k navigate",
+          "i insert",
+          ...(options.multi ? ["Tab toggle"] : []),
+          "Esc/q cancel",
+          "Enter confirm",
+        ]
+  return options.extra ? [...base, ...options.extra] : base
+}
+
+export type ChoosePanelInsetValue = number | "auto" | `${number}%`
+
+export interface ChoosePanelInset {
+  left?: ChoosePanelInsetValue
+  right?: ChoosePanelInsetValue
+  top?: ChoosePanelInsetValue
+  bottom?: ChoosePanelInsetValue
+}
+
+export interface ChoosePanelProps {
+  title?: ReactNode
+  filter: ReactNode
+  children: ReactNode
+  multi?: boolean
+  hints?: (context: { mode: Mode; defaults: string[] }) => ReactNode
+  statusRight?: ReactNode
+  footer?: ReactNode
+  onClose?: () => void
+  inset?: ChoosePanelInset
+}
+
+/** Bordered chooser chrome with filter, content, hint/status, and footer slots. */
+export function ChoosePanel({
+  title,
+  filter,
+  children,
+  multi,
+  hints,
+  statusRight,
+  footer,
+  onClose,
+  inset,
+}: ChoosePanelProps) {
+  const { theme } = useTheme()
+  const mode = useMode()
+  const defaults = buildChooseHints(mode, { multi })
+  const hintContent = hints ? hints({ mode, defaults }) : defaults.join("  ")
+
+  return (
+    <box
+      position="absolute"
+      left={inset?.left ?? "20%"}
+      right={inset?.right ?? "20%"}
+      top={inset?.top ?? "20%"}
+      bottom={inset?.bottom ?? "20%"}
+      flexDirection="column"
+      backgroundColor={theme.backgroundPanel}
+      border
+      borderColor={theme.borderActive}
+    >
+      {title != null && (
+        <box
+          flexDirection="row"
+          height={1}
+          paddingLeft={1}
+          paddingRight={1}
+          backgroundColor={theme.backgroundElement}
+        >
+          {typeof title === "string" ? (
+            <text content={title} fg={theme.accent} style={{ flexGrow: 1 }} />
+          ) : (
+            <box flexDirection="row" style={{ flexGrow: 1 }}>
+              {title}
+            </box>
+          )}
+          {onClose && <CloseButton onClose={onClose} />}
+        </box>
+      )}
+
+      {filter}
+      {children}
+
+      {footer != null && (
+        <box height={1} paddingLeft={1} paddingRight={1}>
+          {footer}
+        </box>
+      )}
+
+      <box
+        flexDirection="row"
+        height={1}
+        paddingLeft={1}
+        paddingRight={1}
+        backgroundColor={theme.backgroundElement}
+      >
+        <box flexDirection="row" style={{ flexGrow: 1 }}>
+          {typeof hintContent === "string" ? (
+            <text content={hintContent} fg={theme.textMuted} />
+          ) : (
+            hintContent
+          )}
+        </box>
+        {statusRight != null &&
+          (typeof statusRight === "string" ? (
+            <text content={statusRight} fg={theme.textMuted} />
+          ) : (
+            statusRight
+          ))}
+      </box>
+    </box>
+  )
+}

package/src/index.ts

@@ -1,9 +1,34 @@
 export { Choose } from "./Choose.js"
+export type { ChooseProps } from "./Choose.js"
 export { ChooseOverlay } from "./ChooseOverlay.js"
 export type { ChooseOverlayProps } from "./ChooseOverlay.js"
+export { ChoosePanel, buildChooseHints } from "./ChoosePanel.js"
+export type { ChoosePanelProps, ChoosePanelInset, ChoosePanelInsetValue } from "./ChoosePanel.js"
+export { ChooseFilter } from "./ChooseFilter.js"
+export type { ChooseFilterProps } from "./ChooseFilter.js"
+export { ChooseList } from "./ChooseList.js"
+export type { ChooseItemRenderContext, ChooseListProps } from "./ChooseList.js"
+export { ChooseHighlightedText } from "./ChooseHighlightedText.js"
+export type { ChooseHighlightedTextProps } from "./ChooseHighlightedText.js"
+export { useChoose } from "./use-choose.js"
+export type {
+  ChooseCommandGroup,
+  ChooseController,
+  ChooseState,
+  ChooseViewModel,
+  UseChooseOptions,
+  UseChooseResult,
+} from "./use-choose.js"
+export { loadChooseSource } from "./source.js"
 export { launch } from "./launch.js"
 export type { ChooseLaunchOptions } from "./launch.js"
 export { createStdinChooseProvider, createStaticProvider } from "./default-provider.js"
 export { fuzzyFilter } from "./fuzzy.js"
 export type { FuzzyMatch } from "./fuzzy.js"
-export type { ChooseItem, ChooseContentProvider, ChooseResult, ChooseOptions } from "./types.js"
+export type {
+  ChooseItem,
+  ChooseContentProvider,
+  ChooseSource,
+  ChooseResult,
+  ChooseOptions,
+} from "./types.js"