@tooee/choose 0.7.3 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tooee/choose",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "description": "Terminal selection with fuzzy filtering",
   "keywords": [
     "cli",
@@ -40,16 +40,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@tooee/commands": "0.7.3",
-    "@tooee/fuzzy": "0.7.3",
-    "@tooee/layout": "0.7.3",
-    "@tooee/overlays": "0.7.3",
-    "@tooee/shell": "0.7.3",
-    "@tooee/themes": "0.7.3"
+    "@tooee/commands": "0.8.0",
+    "@tooee/fuzzy": "0.8.0",
+    "@tooee/layout": "0.8.0",
+    "@tooee/overlays": "0.8.0",
+    "@tooee/shell": "0.8.0",
+    "@tooee/themes": "0.8.0",
+    "@xstate/store": "^4",
+    "@xstate/store-react": "^2"
   },
   "devDependencies": {
     "@opentui/core": "^0.5.1",
     "@opentui/react": "^0.5.1",
+    "@tooee/test-support": "0.7.3",
     "@types/bun": "^1.3.10",
     "@types/react": "^19.2.14",
     "typescript": "^5.9.3"

package/src/choose-filter.tsx

@@ -1,5 +1,6 @@
 import type { ReactNode } from "react";
-import { CloseButton, useTheme } from "@tooee/themes";
+import { CloseButton, decodeReactContent } from "@tooee/layout";
+import { useTheme } from "@tooee/themes";
 import type { UseChooseResult } from "./use-choose.js";
 
 export interface ChooseFilterProps {
@@ -22,10 +23,17 @@ export const ChooseFilter = function ChooseFilter({
   const { state, view } = choose;
   const handleFilterInput = view.onFilterInput;
   const handleFilterKeyDown = view.onFilterKeyDown;
+  const promptContent = decodeReactContent(prompt);
+  let renderedPrompt: ReactNode = null;
+  if (promptContent.kind === "string") {
+    renderedPrompt = <text content={promptContent.value} fg={theme.accent} />;
+  } else if (promptContent.kind === "node") {
+    renderedPrompt = promptContent.value;
+  }
 
   return (
     <box flexDirection="row" height={1} style={{ paddingLeft: 1, paddingRight: 1 }}>
-      {typeof prompt === "string" ? <text content={prompt} fg={theme.accent} /> : prompt}
+      {renderedPrompt}
       <input
         ref={view.filterRef}
         focused={view.filterFocused}

package/src/choose-list.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useRef } from "react";
 import type { ReactNode } from "react";
+import { decodeReactContent } from "@tooee/layout";
 import type { ScrollBoxRenderable } from "@opentui/core";
 import { useTheme } from "@tooee/themes";
 import { ChooseHighlightedText } from "./choose-highlighted-text.js";
@@ -37,9 +38,16 @@ const ThemedLine = function ThemedLine({
   content: ReactNode;
   color: string;
 }): ReactNode {
+  const decoded = decodeReactContent(content);
+  let rendered: ReactNode = null;
+  if (decoded.kind === "string") {
+    rendered = <text content={decoded.value} fg={color} />;
+  } else if (decoded.kind === "node") {
+    rendered = decoded.value;
+  }
   return (
     <box height={1} style={{ paddingLeft: 2 }}>
-      {typeof content === "string" ? <text content={content} fg={color} /> : content}
+      {rendered}
     </box>
   );
 };

package/src/choose-panel.tsx

@@ -1,7 +1,9 @@
 import type { ReactNode } from "react";
+import type { MouseEvent } from "@opentui/core";
 import { useMode } from "@tooee/commands";
 import type { Mode } from "@tooee/commands";
-import { CloseButton, useTheme } from "@tooee/themes";
+import { OverlayPanel } from "@tooee/layout";
+import type { PanelInset, PanelInsetValue } from "@tooee/layout";
 
 export const buildChooseHints = function buildChooseHints(
   mode: Mode,
@@ -25,14 +27,8 @@ export const buildChooseHints = function buildChooseHints(
   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 type ChoosePanelInsetValue = PanelInsetValue;
+export type ChoosePanelInset = PanelInset;
 
 export interface ChoosePanelProps {
   title?: ReactNode;
@@ -44,9 +40,10 @@ export interface ChoosePanelProps {
   footer?: ReactNode;
   onClose?: () => void;
   inset?: ChoosePanelInset;
+  onMouseDown?: (event: MouseEvent) => void;
 }
 
-/** Bordered chooser chrome with filter, content, hint/status, and footer slots. */
+/** Chooser-specific overlay panel with mode-aware default hints. */
 export const ChoosePanel = function ChoosePanel({
   title,
   filter,
@@ -57,74 +54,24 @@ export const ChoosePanel = function ChoosePanel({
   footer,
   onClose,
   inset,
+  onMouseDown,
 }: ChoosePanelProps): ReactNode {
-  const { theme } = useTheme();
   const mode = useMode();
   const defaults = buildChooseHints(mode, { multi });
   const hintContent = hints ? hints({ defaults, mode }) : 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}
+    <OverlayPanel
+      title={title}
+      prompt={filter}
+      hints={hintContent}
+      statusRight={statusRight}
+      footer={footer}
+      onClose={onClose}
+      inset={inset}
+      onMouseDown={onMouseDown}
     >
-      {title !== null && title !== undefined && (
-        <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 && footer !== undefined && (
-        <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 &&
-          statusRight !== undefined &&
-          (typeof statusRight === "string" ? (
-            <text content={statusRight} fg={theme.textMuted} />
-          ) : (
-            statusRight
-          ))}
-      </box>
-    </box>
+    </OverlayPanel>
   );
 };

package/src/choose-store.ts

@@ -0,0 +1,146 @@
+import { createStore } from "@xstate/store";
+import { fuzzyFilter } from "./fuzzy.js";
+import type { FuzzyMatch } from "./fuzzy.js";
+import type { ChooseItem } from "./types.js";
+
+export interface ChooseStoreContext {
+  items: ChooseItem[];
+  matches: FuzzyMatch[];
+  filterQuery: string;
+  activeIndex: number;
+  selectedOriginalIndices: ReadonlySet<number>;
+  loading: boolean;
+  error: string | null;
+  requestId: number;
+  reloadRevision: number;
+}
+
+interface ChooseStoreEventDefinitions {
+  filterChanged: { query: string };
+  activeIndexSet: { index: number };
+  moved: { delta: number };
+  activeToggled: Record<never, never>;
+  requestStarted: Record<never, never>;
+  loadingStarted: { requestId: number };
+  loadSucceeded: { requestId: number; items: ChooseItem[] };
+  loadFailed: { requestId: number; error: string };
+  reloadRequested: Record<never, never>;
+}
+
+export type ChooseStoreEvents = {
+  [EventName in keyof ChooseStoreEventDefinitions]: ChooseStoreEventDefinitions[EventName];
+};
+
+const replaceItems = function replaceItems(
+  ctx: ChooseStoreContext,
+  items: ChooseItem[],
+): ChooseStoreContext {
+  return {
+    ...ctx,
+    activeIndex: 0,
+    items,
+    matches: fuzzyFilter(items, ctx.filterQuery),
+    selectedOriginalIndices: new Set(),
+  };
+};
+
+const clampActiveIndex = function clampActiveIndex(index: number, matchCount: number): number {
+  return Math.min(Math.max(0, matchCount - 1), Math.max(0, index));
+};
+
+export const createChooseStore = function createChooseStore(options: {
+  items?: ChooseItem[];
+  initialFilter?: string;
+  loading?: boolean;
+}) {
+  const items = options.items ?? [];
+  const filterQuery = options.initialFilter ?? "";
+
+  return createStore<ChooseStoreContext, ChooseStoreEvents>({
+    context: {
+      activeIndex: 0,
+      error: null,
+      filterQuery,
+      items,
+      loading: options.loading ?? false,
+      matches: fuzzyFilter(items, filterQuery),
+      reloadRevision: 0,
+      requestId: 0,
+      selectedOriginalIndices: new Set(),
+    },
+    on: {
+      activeIndexSet: (ctx, event) => {
+        const activeIndex = clampActiveIndex(event.index, ctx.matches.length);
+        return activeIndex === ctx.activeIndex ? ctx : { ...ctx, activeIndex };
+      },
+      activeToggled: (ctx) => {
+        const originalIndex = ctx.matches[ctx.activeIndex]?.originalIndex;
+        if (originalIndex === undefined) {
+          return ctx;
+        }
+        const selectedOriginalIndices = new Set(ctx.selectedOriginalIndices);
+        if (selectedOriginalIndices.has(originalIndex)) {
+          selectedOriginalIndices.delete(originalIndex);
+        } else {
+          selectedOriginalIndices.add(originalIndex);
+        }
+        return { ...ctx, selectedOriginalIndices };
+      },
+      filterChanged: (ctx, event) => {
+        if (event.query === ctx.filterQuery) {
+          return ctx;
+        }
+        return {
+          ...ctx,
+          activeIndex: 0,
+          filterQuery: event.query,
+          matches: fuzzyFilter(ctx.items, event.query),
+        };
+      },
+      loadFailed: (ctx, event) => {
+        if (event.requestId !== ctx.requestId) {
+          return ctx;
+        }
+        return {
+          ...replaceItems(ctx, []),
+          error: event.error,
+          loading: false,
+        };
+      },
+      loadSucceeded: (ctx, event) => {
+        if (event.requestId !== ctx.requestId) {
+          return ctx;
+        }
+        return {
+          ...replaceItems(ctx, event.items),
+          error: null,
+          loading: false,
+        };
+      },
+      loadingStarted: (ctx, event) =>
+        event.requestId === ctx.requestId && !ctx.loading ? { ...ctx, loading: true } : ctx,
+      moved: (ctx, event) => {
+        const activeIndex = clampActiveIndex(ctx.activeIndex + event.delta, ctx.matches.length);
+        return activeIndex === ctx.activeIndex ? ctx : { ...ctx, activeIndex };
+      },
+      reloadRequested: (ctx) => ({ ...ctx, reloadRevision: ctx.reloadRevision + 1 }),
+      requestStarted: (ctx) => ({
+        ...ctx,
+        error: null,
+        requestId: ctx.requestId + 1,
+      }),
+    },
+  });
+};
+
+export type ChooseStore = ReturnType<typeof createChooseStore>;
+
+export const selectItems = (ctx: ChooseStoreContext): ChooseItem[] => ctx.items;
+export const selectMatches = (ctx: ChooseStoreContext): FuzzyMatch[] => ctx.matches;
+export const selectFilterQuery = (ctx: ChooseStoreContext): string => ctx.filterQuery;
+export const selectActiveIndex = (ctx: ChooseStoreContext): number => ctx.activeIndex;
+export const selectSelectedOriginalIndices = (ctx: ChooseStoreContext): ReadonlySet<number> =>
+  ctx.selectedOriginalIndices;
+export const selectLoading = (ctx: ChooseStoreContext): boolean => ctx.loading;
+export const selectError = (ctx: ChooseStoreContext): string | null => ctx.error;
+export const selectReloadRevision = (ctx: ChooseStoreContext): number => ctx.reloadRevision;

package/src/choose.tsx

@@ -1,10 +1,10 @@
 import { useImperativeHandle } from "react";
-import type { Ref } from "react";
+import type { ReactNode, 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 { useSurfaceInvoke } from "@tooee/commands";
 import type { ActionDefinition } from "@tooee/commands";
 import { ChooseFilter } from "./choose-filter.js";
 import { ChooseList } from "./choose-list.js";
@@ -14,12 +14,12 @@ import type { ChooseContentProvider, ChooseOptions, ChooseResult } from "./types
 import { useChoose } from "./use-choose.js";
 import type { ChooseController } from "./use-choose.js";
 
-export interface ChooseProps {
+export interface ChooseProps extends ChooseOptions {
   contentProvider: ChooseContentProvider;
+  /** @deprecated Pass chooser options as top-level props. This alias will be removed in 0.9.0. */
   options?: ChooseOptions;
-  /** Legacy name retained for source compatibility. */
   actions?: ActionDefinition[];
-  /** Additive alias used by new chooser compositions. */
+  /** @deprecated Use `actions`. This alias will be removed in 0.9.0. */
   commands?: ActionDefinition[];
   controllerRef?: Ref<ChooseController>;
   renderItem?: ChooseListProps["renderItem"];
@@ -36,20 +36,37 @@ export interface ChooseProps {
   onCancel?: () => void;
 }
 
-export const Choose = function Choose({
-  contentProvider,
-  options,
-  actions,
-  commands,
-  controllerRef,
-  renderItem,
-  onConfirm,
-  onCancel,
-}: ChooseProps): React.ReactNode {
+interface ResolvedChooseProps extends ChooseOptions {
+  actions?: ActionDefinition[];
+}
+
+const resolveChooseProps = function resolveChooseProps(props: ChooseProps): ResolvedChooseProps {
+  // oxlint-disable-next-line typescript/no-deprecated -- compatibility alias remains supported until 0.9.0
+  const { options } = props;
+  // oxlint-disable-next-line typescript/no-deprecated -- compatibility alias remains supported until 0.9.0
+  const { commands } = props;
+  return {
+    actions: props.actions ?? commands,
+    emptyMessage: props.emptyMessage ?? options?.emptyMessage,
+    multi: props.multi ?? options?.multi,
+    placeholder: props.placeholder ?? options?.placeholder,
+    prompt: props.prompt ?? options?.prompt,
+    title: props.title ?? options?.title,
+  };
+};
+
+export const Choose = function Choose(props: ChooseProps): ReactNode {
+  const { contentProvider, controllerRef, renderItem, onConfirm, onCancel } = props;
+  const {
+    actions: effectiveActions,
+    emptyMessage,
+    multi = false,
+    placeholder,
+    prompt,
+    title,
+  } = resolveChooseProps(props);
   const { theme } = useTheme();
-  const { invoke } = useCommandContext();
-  const effectiveCommands = commands ?? actions;
-  const multi = options?.multi ?? false;
+  const { invoke } = useSurfaceInvoke();
 
   const { name: themeName } = useThemeCommands();
   useQuitCommand({ onQuit: () => onCancel?.() });
@@ -58,13 +75,13 @@ export const Choose = function Choose({
   const hasModalOverlay = useHasModalOverlay();
 
   const choose = useChoose({
-    commands: effectiveCommands,
+    commands: effectiveActions,
     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) {
+      if (effectiveActions?.some((action) => action.id === "submit") === true) {
         invoke("submit");
         return;
       }
@@ -98,10 +115,10 @@ export const Choose = function Choose({
 
   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 };
+  if (title !== undefined && title !== "") {
+    titleBar = { title };
+  } else if (prompt !== undefined && prompt !== "") {
+    titleBar = { title: prompt };
   }
 
   return (
@@ -125,15 +142,14 @@ export const Choose = function Choose({
           { label: "", value: hints.join("  ") },
         ],
       }}
-      scrollProps={{ focused: false }}
     >
       <box flexDirection="column" style={{ flexGrow: 1 }}>
-        <ChooseFilter choose={choose} placeholder={options?.placeholder} />
+        <ChooseFilter choose={choose} placeholder={placeholder} />
         <ChooseList
           choose={choose}
           rowClick="activate"
           renderItem={renderItem}
-          emptyContent={options?.emptyMessage}
+          emptyContent={emptyMessage}
           suspended={hasModalOverlay}
         />
       </box>

package/src/fuzzy.ts

@@ -1,4 +1,4 @@
-import { fuzzyMatchPositions } from "@tooee/fuzzy";
+import { rankBy } from "@tooee/fuzzy";
 import type { ChooseItem } from "./types.js";
 
 export interface FuzzyMatch {
@@ -9,20 +9,5 @@ export interface FuzzyMatch {
 }
 
 export const fuzzyFilter = function fuzzyFilter(items: ChooseItem[], query: string): FuzzyMatch[] {
-  if (!query) {
-    return items.map((item, i) => ({ item, originalIndex: i, positions: [], score: 0 }));
-  }
-
-  const results: FuzzyMatch[] = [];
-
-  for (let i = 0; i < items.length; i += 1) {
-    const item = items[i];
-    const match = fuzzyMatchPositions(query, item.text);
-    if (match) {
-      results.push({ item, originalIndex: i, positions: match.positions, score: match.score });
-    }
-  }
-
-  results.sort((a, b) => b.score - a.score);
-  return results;
+  return rankBy(items, query, (item) => item.text);
 };

package/src/launch.tsx

@@ -2,6 +2,7 @@ import { runCliSession } from "@tooee/shell";
 import type { ActionDefinition } from "@tooee/commands";
 import { Choose } from "./choose.js";
 import type { ChooseContentProvider, ChooseOptions, ChooseResult } from "./types.js";
+import type { ReactNode } from "react";
 
 export interface ChooseLaunchOptions {
   contentProvider: ChooseContentProvider;
@@ -13,10 +14,14 @@ export const launch = async function launch(
   opts: ChooseLaunchOptions,
 ): Promise<ChooseResult | null> {
   const result = await runCliSession<ChooseResult>(
-    ({ resolve, cancel }): React.ReactNode => (
+    ({ resolve, cancel }): ReactNode => (
       <Choose
         contentProvider={opts.contentProvider}
-        options={opts.options}
+        title={opts.options?.title}
+        prompt={opts.options?.prompt}
+        placeholder={opts.options?.placeholder}
+        multi={opts.options?.multi}
+        emptyMessage={opts.options?.emptyMessage}
         actions={opts.actions}
         onConfirm={resolve}
         onCancel={cancel}

package/src/source.ts

@@ -1,18 +1,36 @@
-import type { ChooseItem, ChooseSource } from "./types.js";
+import type { ChooseContentProvider, ChooseItem, ChooseSource } from "./types.js";
+
+type DecodedChooseSource =
+  | { kind: "items"; items: ChooseItem[] }
+  | { kind: "loader"; load: () => ChooseItem[] | Promise<ChooseItem[]> }
+  | { kind: "provider"; provider: ChooseContentProvider };
+
+const decodeChooseSource = function decodeChooseSource(source: ChooseSource): DecodedChooseSource {
+  if (Array.isArray(source)) {
+    return { items: source, kind: "items" };
+  }
+  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- public source boundary distinguishes the documented loader callback from a provider
+  if (typeof source === "function") {
+    return { kind: "loader", load: source };
+  }
+  return { kind: "provider", provider: source };
+};
 
 /** Resolve every public Choose source shape through one compatibility boundary. */
 export const loadChooseSource = function loadChooseSource(
   source: ChooseSource,
 ): ChooseItem[] | Promise<ChooseItem[]> {
-  if (Array.isArray(source)) {
-    return source;
+  const decoded = decodeChooseSource(source);
+  if (decoded.kind === "items") {
+    return decoded.items;
   }
-  if (typeof source === "function") {
-    return source();
+  if (decoded.kind === "loader") {
+    return decoded.load();
   }
-  return source.load();
+  return decoded.provider.load();
 };
 
+// oxlint-disable-next-line anti-slop/no-unknown-parameters -- caught loader failures enter here before conversion to display text
 export const chooseSourceError = function chooseSourceError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 };