@tooee/choose 0.2.3 → 0.3.0

package/src/choose-highlighted-text.tsx

@@ -0,0 +1,49 @@
+import { Fragment } from "react";
+import type { ReactNode } from "react";
+
+export interface ChooseHighlightedTextProps {
+  text: string;
+  positions: number[];
+  highlightColor: string;
+}
+
+/** Render fuzzy-match characters with one shared segmentation implementation. */
+export const ChooseHighlightedText = function ChooseHighlightedText({
+  text,
+  positions,
+  highlightColor,
+}: ChooseHighlightedTextProps): ReactNode {
+  if (positions.length === 0) {
+    return text;
+  }
+
+  const positionSet = new Set(positions);
+  const parts: { text: string; highlighted: boolean }[] = [];
+  let current = "";
+  let currentHighlighted = false;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const highlighted = positionSet.has(index);
+    if (index === 0) {
+      current = text[index];
+      currentHighlighted = highlighted;
+    } else if (highlighted === currentHighlighted) {
+      current += text[index];
+    } else {
+      parts.push({ highlighted: currentHighlighted, text: current });
+      current = text[index];
+      currentHighlighted = highlighted;
+    }
+  }
+  if (current) {
+    parts.push({ highlighted: currentHighlighted, text: current });
+  }
+
+  return parts.map(
+    (part, index): ReactNode => (
+      <Fragment key={index}>
+        {part.highlighted ? <span fg={highlightColor}>{part.text}</span> : part.text}
+      </Fragment>
+    ),
+  );
+};

package/src/{ChooseList.tsx → choose-list.tsx}

@@ -1,48 +1,55 @@
-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"
+import { useEffect, useRef } from "react";
+import type { ReactNode } from "react";
+import type { ScrollBoxRenderable } from "@opentui/core";
+import { useTheme } from "@tooee/themes";
+import { ChooseHighlightedText } from "./choose-highlighted-text.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
+  item: ChooseItem;
+  match: FuzzyMatch;
+  index: number;
+  originalIndex: number;
+  positions: number[];
+  isActive: boolean;
+  isSelected: boolean;
+  defaultContent: ReactNode;
 }
 
 export interface ChooseListProps {
-  choose: UseChooseResult
+  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
+  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
+  suspended?: boolean;
 }
 
-function ThemedLine({ content, color }: { content: ReactNode; color: string }) {
+const ThemedLine = function ThemedLine({
+  content,
+  color,
+}: {
+  content: ReactNode;
+  color: string;
+}): ReactNode {
   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}`
-}
+const defaultErrorContent = function defaultErrorContent(error: string): ReactNode {
+  return `Error: ${error}`;
+};
 
 /** Scrollable chooser rows plus loading/error/empty presentation. */
-export function ChooseList({
+export const ChooseList = function ChooseList({
   choose,
   rowClick = "activate",
   renderItem,
@@ -50,33 +57,35 @@ export function ChooseList({
   errorContent = defaultErrorContent,
   emptyContent,
   suspended,
-}: ChooseListProps) {
-  const { theme } = useTheme()
-  const scrollRef = useRef<ScrollBoxRenderable>(null)
-  const { state, controller } = choose
-  const interactionSuspended = choose.view.suspended || (suspended ?? false)
+}: ChooseListProps): ReactNode {
+  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)
+      scrollRef.current.scrollTop = Math.max(0, state.activeIndex - 5);
     }
-  }, [state.activeIndex, state.matches.length])
+  }, [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 && (
+      {!state.loading && state.error !== null && 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.loading &&
+        (state.error?.length ?? 0) === 0 &&
+        state.matches.length === 0 &&
+        emptyContent !== null &&
+        emptyContent !== undefined && <ThemedLine content={emptyContent} color={theme.textMuted} />}
 
-      {state.matches.map((match, index) => {
-        const isActive = index === state.activeIndex
-        const isSelected = state.selectedOriginalIndices.has(match.originalIndex)
+      {state.matches.map((match, index): ReactNode => {
+        const isActive = index === state.activeIndex;
+        const isSelected = state.selectedOriginalIndices.has(match.originalIndex);
         const defaultContent = (
           <>
             {state.multi && (
@@ -85,7 +94,9 @@ export function ChooseList({
                 fg={isSelected ? theme.accent : theme.textMuted}
               />
             )}
-            {match.item.icon && <text content={`${match.item.icon} `} fg={theme.textMuted} />}
+            {(match.item.icon?.length ?? 0) > 0 && (
+              <text content={`${match.item.icon} `} fg={theme.textMuted} />
+            )}
             <text fg={isActive ? theme.primary : theme.text}>
               <ChooseHighlightedText
                 text={match.item.text}
@@ -93,21 +104,21 @@ export function ChooseList({
                 highlightColor={theme.warning}
               />
             </text>
-            {match.item.description && (
+            {(match.item.description?.length ?? 0) > 0 && (
               <text content={`  ${match.item.description}`} fg={theme.textMuted} />
             )}
           </>
-        )
+        );
         const context: ChooseItemRenderContext = {
+          defaultContent,
+          index,
+          isActive,
+          isSelected,
           item: match.item,
           match,
-          index,
           originalIndex: match.originalIndex,
           positions: match.positions,
-          isActive,
-          isSelected,
-          defaultContent,
-        }
+        };
 
         return (
           <box
@@ -117,21 +128,23 @@ export function ChooseList({
             backgroundColor={isActive ? theme.backgroundElement : undefined}
             style={{ paddingLeft: 1 }}
             onMouseDown={(event) => {
-              if (interactionSuspended || event.button !== 0 || rowClick === "none") return
+              if (interactionSuspended || event.button !== 0 || rowClick === "none") {
+                return;
+              }
               if (rowClick === "submit") {
-                event.preventDefault()
-                event.stopPropagation()
-                controller.setActiveIndex(index)
-                controller.submit()
+                event.preventDefault();
+                event.stopPropagation();
+                controller.setActiveIndex(index);
+                controller.submit();
               } else {
-                controller.setActiveIndex(index)
+                controller.setActiveIndex(index);
               }
             }}
           >
             {renderItem ? renderItem(context) : defaultContent}
           </box>
-        )
+        );
       })}
     </scrollbox>
-  )
-}
+  );
+};

package/src/choose-overlay.tsx

@@ -0,0 +1,96 @@
+import { useImperativeHandle } from "react";
+import type { ReactNode, Ref } from "react";
+import type { ActionDefinition } from "@tooee/commands";
+import { ChooseFilter } from "./choose-filter.js";
+import { ChooseList } from "./choose-list.js";
+import type { ChooseListProps } from "./choose-list.js";
+import { ChoosePanel } from "./choose-panel.js";
+import type { ChoosePanelProps } from "./choose-panel.js";
+import type { ChooseItem, ChooseResult, ChooseSource } from "./types.js";
+import { useChoose } from "./use-choose.js";
+import type { ChooseController } from "./use-choose.js";
+
+interface ChooseOverlayBaseProps {
+  items: ChooseSource;
+  prompt?: string;
+  placeholder?: string;
+  emptyMessage?: string;
+  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 type ChooseOverlayProps = ChooseOverlayBaseProps &
+  (
+    | {
+        multi?: false;
+        onSelect: (item: ChooseItem) => void | Promise<void>;
+        onSubmit?: never;
+      }
+    | {
+        multi: true;
+        onSubmit: (result: ChooseResult) => void | Promise<void>;
+        onSelect?: never;
+      }
+  );
+
+/**
+ * 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 const ChooseOverlay = function ChooseOverlay(props: ChooseOverlayProps): ReactNode {
+  const multi = props.multi === true;
+  const choose = useChoose({
+    commandScope: "choose-overlay",
+    commands: props.commands,
+    multi,
+    onCancel: props.onCancel,
+    onSubmit: (result): void | Promise<void> => {
+      if (multi) {
+        return props.onSubmit(result);
+      }
+      const [item] = result.items;
+      if (item !== undefined) {
+        return props.onSelect(item);
+      }
+    },
+    source: props.items,
+    suspended: props.suspended,
+  });
+
+  useImperativeHandle(props.controllerRef, () => choose.controller, [choose.controller]);
+
+  return (
+    <>
+      <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}
+        />
+      </ChoosePanel>
+      {props.children}
+    </>
+  );
+};

package/src/{ChoosePanel.tsx → choose-panel.tsx}

@@ -1,47 +1,53 @@
-import type { ReactNode } from "react"
-import { useMode, type Mode } from "@tooee/commands"
-import { CloseButton, useTheme } from "@tooee/themes"
+import type { ReactNode } from "react";
+import { useMode } from "@tooee/commands";
+import type { Mode } from "@tooee/commands";
+import { CloseButton, useTheme } from "@tooee/themes";
 
-export function buildChooseHints(
+export const buildChooseHints = function buildChooseHints(
   mode: Mode,
   options: { multi?: boolean; extra?: string[] } = {},
 ): string[] {
   const base =
     mode === "insert"
-      ? ["↑↓ navigate", "Enter confirm", ...(options.multi ? ["Tab toggle"] : []), "Esc commands"]
+      ? [
+          "↑↓ navigate",
+          "Enter confirm",
+          ...(options.multi === true ? ["Tab toggle"] : []),
+          "Esc commands",
+        ]
       : [
           "j/k navigate",
           "i insert",
-          ...(options.multi ? ["Tab toggle"] : []),
+          ...(options.multi === true ? ["Tab toggle"] : []),
           "Esc/q cancel",
           "Enter confirm",
-        ]
-  return options.extra ? [...base, ...options.extra] : base
-}
+        ];
+  return options.extra ? [...base, ...options.extra] : base;
+};
 
-export type ChoosePanelInsetValue = number | "auto" | `${number}%`
+export type ChoosePanelInsetValue = number | "auto" | `${number}%`;
 
 export interface ChoosePanelInset {
-  left?: ChoosePanelInsetValue
-  right?: ChoosePanelInsetValue
-  top?: ChoosePanelInsetValue
-  bottom?: ChoosePanelInsetValue
+  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
+  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({
+export const ChoosePanel = function ChoosePanel({
   title,
   filter,
   children,
@@ -51,11 +57,11 @@ export function ChoosePanel({
   footer,
   onClose,
   inset,
-}: ChoosePanelProps) {
-  const { theme } = useTheme()
-  const mode = useMode()
-  const defaults = buildChooseHints(mode, { multi })
-  const hintContent = hints ? hints({ mode, defaults }) : defaults.join("  ")
+}: ChoosePanelProps): ReactNode {
+  const { theme } = useTheme();
+  const mode = useMode();
+  const defaults = buildChooseHints(mode, { multi });
+  const hintContent = hints ? hints({ defaults, mode }) : defaults.join("  ");
 
   return (
     <box
@@ -69,7 +75,7 @@ export function ChoosePanel({
       border
       borderColor={theme.borderActive}
     >
-      {title != null && (
+      {title !== null && title !== undefined && (
         <box
           flexDirection="row"
           height={1}
@@ -91,7 +97,7 @@ export function ChoosePanel({
       {filter}
       {children}
 
-      {footer != null && (
+      {footer !== null && footer !== undefined && (
         <box height={1} paddingLeft={1} paddingRight={1}>
           {footer}
         </box>
@@ -111,7 +117,8 @@ export function ChoosePanel({
             hintContent
           )}
         </box>
-        {statusRight != null &&
+        {statusRight !== null &&
+          statusRight !== undefined &&
           (typeof statusRight === "string" ? (
             <text content={statusRight} fg={theme.textMuted} />
           ) : (
@@ -119,5 +126,5 @@ export function ChoosePanel({
           ))}
       </box>
     </box>
-  )
-}
+  );
+};

package/src/choose.tsx

@@ -0,0 +1,142 @@
+import { useImperativeHandle } from "react";
+import type { Ref } from "react";
+import { AppLayout } from "@tooee/layout";
+import { useHasOverlay, useHasModalOverlay } from "@tooee/overlays";
+import { useTheme } from "@tooee/themes";
+import { useThemeCommands, useQuitCommand } from "@tooee/shell";
+import { useCommandContext } from "@tooee/commands";
+import type { ActionDefinition } from "@tooee/commands";
+import { ChooseFilter } from "./choose-filter.js";
+import { ChooseList } from "./choose-list.js";
+import type { ChooseListProps } from "./choose-list.js";
+import { buildChooseHints } from "./choose-panel.js";
+import type { ChooseContentProvider, ChooseOptions, ChooseResult } from "./types.js";
+import { useChoose } from "./use-choose.js";
+import type { ChooseController } from "./use-choose.js";
+
+export interface ChooseProps {
+  contentProvider: ChooseContentProvider;
+  options?: ChooseOptions;
+  /** Legacy name retained for source compatibility. */
+  actions?: ActionDefinition[];
+  /** Additive alias used by new chooser compositions. */
+  commands?: ActionDefinition[];
+  controllerRef?: Ref<ChooseController>;
+  renderItem?: ChooseListProps["renderItem"];
+  /**
+   * Called with the selection when the chooser is submitted. This is the
+   * component-level equivalent of `useChoose`'s `onSubmit` and is how a host
+   * (including `launch()`) receives a `ChooseResult`. A registered command with
+   * the id `submit` still takes precedence, because a command can express its
+   * own submit behaviour — but commands receive a `CommandContext`, not a
+   * result, so they are not a replacement for this callback.
+   */
+  onConfirm?: (result: ChooseResult) => void;
+  /** Called when the chooser is cancelled (quit, or submit with no selection). */
+  onCancel?: () => void;
+}
+
+export const Choose = function Choose({
+  contentProvider,
+  options,
+  actions,
+  commands,
+  controllerRef,
+  renderItem,
+  onConfirm,
+  onCancel,
+}: ChooseProps): React.ReactNode {
+  const { theme } = useTheme();
+  const { invoke } = useCommandContext();
+  const effectiveCommands = commands ?? actions;
+  const multi = options?.multi ?? false;
+
+  const { name: themeName } = useThemeCommands();
+  useQuitCommand({ onQuit: () => onCancel?.() });
+
+  const hasOverlay = useHasOverlay();
+  const hasModalOverlay = useHasModalOverlay();
+
+  const choose = useChoose({
+    commands: effectiveCommands,
+    multi,
+    onCancel,
+    onSubmit: (result) => {
+      // Standalone behaviour: a command named `submit` wins over `onConfirm`, so
+      // action-driven CLIs keep their own submit semantics.
+      if (effectiveCommands?.some((action) => action.id === "submit") === true) {
+        invoke("submit");
+        return;
+      }
+      if (multi || result.items.length > 0) {
+        onConfirm?.(result);
+      } else {
+        onCancel?.();
+      }
+    },
+    source: contentProvider,
+    suspended: hasOverlay,
+  });
+
+  useImperativeHandle(controllerRef, () => choose.controller, [choose.controller]);
+
+  if (choose.state.loading) {
+    return (
+      <box>
+        <text content="Loading..." fg={theme.textMuted} />
+      </box>
+    );
+  }
+
+  if ((choose.state.error?.length ?? 0) > 0) {
+    return (
+      <box>
+        <text content={`Error: ${choose.state.error}`} fg={theme.error} />
+      </box>
+    );
+  }
+
+  const hints = buildChooseHints(choose.view.mode, { multi });
+  let titleBar: { title: string } | undefined;
+  if (options?.title !== undefined && options.title !== "") {
+    titleBar = { title: options.title };
+  } else if (options?.prompt !== undefined && options.prompt !== "") {
+    titleBar = { title: options.prompt };
+  }
+
+  return (
+    <AppLayout
+      titleBar={titleBar}
+      statusBar={{
+        items: [
+          {
+            label: "Matches:",
+            value: `${choose.state.matches.length}/${choose.state.items.length}`,
+          },
+          ...(multi
+            ? [
+                {
+                  label: "Selected:",
+                  value: String(choose.state.selectedOriginalIndices.size),
+                },
+              ]
+            : []),
+          { label: "Theme:", value: themeName },
+          { label: "", value: hints.join("  ") },
+        ],
+      }}
+      scrollProps={{ focused: false }}
+    >
+      <box flexDirection="column" style={{ flexGrow: 1 }}>
+        <ChooseFilter choose={choose} placeholder={options?.placeholder} />
+        <ChooseList
+          choose={choose}
+          rowClick="activate"
+          renderItem={renderItem}
+          emptyContent={options?.emptyMessage}
+          suspended={hasModalOverlay}
+        />
+      </box>
+    </AppLayout>
+  );
+};

package/src/default-provider.ts

@@ -1,19 +1,22 @@
-import type { ChooseItem, ChooseContentProvider } from "./types.js"
+import type { ChooseItem, ChooseContentProvider } from "./types.js";
 
-export function createStdinChooseProvider(): ChooseContentProvider {
-  return {
-    async load(): Promise<ChooseItem[]> {
-      const text = await new Response(Bun.stdin.stream() as unknown as ReadableStream).text()
-      return text
-        .split("\n")
-        .filter((line) => line.length > 0)
-        .map((line) => ({ text: line }))
-    },
-  }
-}
+export const createStdinChooseProvider =
+  function createStdinChooseProvider(): ChooseContentProvider {
+    return {
+      async load(): Promise<ChooseItem[]> {
+        const text = await new Response(Bun.stdin.stream()).text();
+        return text
+          .split("\n")
+          .filter((line) => line.length > 0)
+          .map((line) => ({ text: line }));
+      },
+    };
+  };
 
-export function createStaticProvider(items: ChooseItem[]): ChooseContentProvider {
+export const createStaticProvider = function createStaticProvider(
+  items: ChooseItem[],
+): ChooseContentProvider {
   return {
     load: () => items,
-  }
-}
+  };
+};