@aiquants/select-box 0.1.0 → 0.2.0

package/README.md

@@ -1,375 +1,154 @@
-# @aiquants/directory-tree
+# @aiquants/select-box
 
-A high-performance React directory tree component with virtualization, file selection, and theming support.
+A high-performance React select box component with virtual scrolling, fuzzy search, and multi-selection support.
 
 ## Features
 
-- **🚀 High Performance**: Built with [@aiquants/virtualscroll](../virtualscroll) to handle large directory structures efficiently with O(log n) operations
-- **🌀 Ultrafast Scrolling**: Inherits adaptive tap scroll circle from VirtualScroll for navigating massive datasets
-- **📁 File Selection**: Interactive file selection with visual feedback and multiple selection modes
-- **🎨 Theming**: Customizable line colors with external theme control support
-- **♿ Accessibility**: Full keyboard navigation and screen reader support
-- **📱 Responsive**: Optimized for both desktop and mobile interfaces
-- **🔧 TypeScript**: Complete TypeScript support with comprehensive type definitions
-- **💾 State Persistence**: Automatic localStorage persistence for expansion states
-- **🎯 Flexible Selection**: Support for none, single, or multiple selection modes
+- **Virtual Scrolling**: Built with `@aiquants/virtualscroll` to handle 1,000+ options smoothly
+- **Fuzzy Search**: Built with `@aiquants/fuzzy-search` using Web Workers for non-blocking search
+- **Single & Multi Select**: Unified API for both modes via the `multiple` prop
+- **Clearable**: Optional clear button for single-select mode
+- **Resizable Dropdown**: Drag the bottom-right handle to resize (100px - 600px)
+- **Keyboard Navigation**: Backspace to remove last tag, external click to close
+- **TypeScript**: Complete type definitions included
 
 ## Installation
 
 ```bash
-npm install @aiquants/directory-tree
-# or
-yarn add @aiquants/directory-tree
-# or
-pnpm add @aiquants/directory-tree
+pnpm add @aiquants/select-box
 ```
 
 ## Peer Dependencies
 
-This package requires the following peer dependencies:
-
 ```bash
-npm install react react-dom @aiquants/virtualscroll tailwind-variants tailwind-merge
+pnpm add react react-dom
 ```
 
 ## Quick Start
 
 ```tsx
-import React from 'react';
-import { DirectoryTree, useDirectoryTreeState } from '@aiquants/directory-tree';
-import { useTheme } from './hooks/useTheme'; // Your theme hook
-import type { DirectoryEntry } from '@aiquants/directory-tree';
-
-const sampleData: DirectoryEntry[] = [
-  {
-    name: 'src',
-    absolutePath: '/src',
-    relativePath: 'src',
-    children: [
-      {
-        name: 'components',
-        absolutePath: '/src/components',
-        relativePath: 'src/components',
-        children: [
-          {
-            name: 'App.tsx',
-            absolutePath: '/src/components/App.tsx',
-            relativePath: 'src/components/App.tsx',
-            children: null
-          }
-        ]
-      }
-    ]
-  }
-];
-
-export default function App() {
-  const { theme } = useTheme();
-  const {
-    toggle,
-    isExpanded,
-    expandMultiple,
-    collapseMultiple,
-    isPending
-  } = useDirectoryTreeState({
-    storageKey: 'my-directory-tree'
-  });
-
-  // Calculate line color based on theme
-  const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";
-
-  const handleFileSelect = (absolutePath: string, relativePath: string) => {
-    console.log(`File selected: ${absolutePath} (${relativePath})`);
-  };
+import { useState, useMemo } from "react"
+import { SelectBox, type Option } from "@aiquants/select-box"
+// Required: Vite environments need explicit Worker URLs
+import indexWorkerUrl from "@aiquants/fuzzy-search/worker/indexWorker?url"
+import levenshteinWorkerUrl from "@aiquants/fuzzy-search/worker/levenshteinWorker?url"
+
+const options: Option[] = [
+  { label: "Apple", value: "apple" },
+  { label: "Banana", value: "banana" },
+  { label: "Cherry", value: "cherry" },
+]
+
+function SingleSelect() {
+  const [value, setValue] = useState<Option | null>(null)
+  const workerUrls = useMemo(() => ({
+    indexWorker: indexWorkerUrl,
+    levenshteinWorker: levenshteinWorkerUrl,
+  }), [])
 
   return (
-    <div className="h-96 w-full border rounded-lg">
-      <DirectoryTree
-        entries={sampleData}
-        expansion={{
-          toggle,
-          isExpanded,
-          expandMultiple,
-          collapseMultiple,
-          isPending
-        }}
-        selection={{
-          onFileSelect: handleFileSelect,
-          selectedPath: null
-        }}
-        visual={{
-          lineColor,
-          className: "h-full"
-        }}
-      />
-    </div>
-  );
+    <SelectBox
+      options={options}
+      value={value}
+      onChange={(val) => setValue(val as Option | null)}
+      placeholder="Select a fruit..."
+      workerUrls={workerUrls}
+    />
+  )
 }
-```
-
-## API Reference
-
-### DirectoryTree Component
-
-The main component for rendering the directory tree.
-
-#### Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `entries` | `DirectoryEntry[]` | Yes | Array of root directory entries to display |
-| `expansion` | `object` | Yes | Configuration for tree expansion state and behavior |
-| `selection` | `object` | Yes | Configuration for item selection |
-| `visual` | `object` | No | Visual customization options |
-| `virtualScroll` | `DirectoryTreeVirtualScrollOptions` | No | Pass-through options for the underlying VirtualScroll component |
-
-#### Expansion Options (`expansion`)
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `toggle` | `(path: string, relativePath: string) => void` | Yes | - | Function to toggle directory expansion state |
-| `isExpanded` | `(path: string) => boolean` | Yes | - | Function to check if a directory is expanded |
-| `expandMultiple` | `(paths: string[]) => void` | Yes | - | Function to expand multiple directories |
-| `collapseMultiple` | `(paths: string[]) => void` | Yes | - | Function to collapse multiple directories |
-| `isPending` | `boolean` | No | `false` | Whether the tree is in a pending state |
-| `alwaysExpanded` | `boolean` | No | `false` | If true, all directories are always expanded |
-| `doubleClickAction` | `'recursive' \| 'toggle'` | No | `'recursive'` | Action on double-clicking a directory |
-
-#### Selection Options (`selection`)
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `onFileSelect` | `(absolutePath: string, relativePath: string) => void` | Yes | - | Callback function triggered when a file is selected |
-| `selectedPath` | `string \| null` | No | - | The currently selected file path |
-| `mode` | `'none' \| 'single' \| 'multiple'` | No | `'none'` | Selection mode for items |
-| `selectedItems` | `Set<string>` | No | - | Set of paths for currently selected items |
-| `onSelectionChange` | `(path: string, isSelected: boolean) => void` | No | - | Callback when item selection changes |
-
-#### Visual Options (`visual`)
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `className` | `string` | No | - | Optional CSS class name for the container |
-| `style` | `React.CSSProperties` | No | - | Optional inline styles for the container |
-| `lineColor` | `string` | No | `'#A0AEC0'` | The color of the tree lines |
-| `showTreeLines` | `boolean` | No | `true` | Flag indicating whether to render tree connector lines |
-| `showExpandIcons` | `boolean` | No | `true` | Flag indicating whether to render directory expand icons |
-| `showDirectoryIcons` | `boolean` | No | `true` | Flag indicating whether to render directory type icons |
-| `showFileIcons` | `boolean` | No | `true` | Flag indicating whether to render file type icons |
-| `iconOverrides` | `DirectoryTreeIconOverrides` | No | - | Icon overrides applied globally |
-| `expandIconSize` | `number` | No | - | Size of the expand icon |
-| `removeRootIndent` | `boolean` | No | `false` | If true, removes the indentation and connector lines for root-level items |
-
-### Virtual Scroll Options
-
-`virtualScroll` lets you customize the embedded `@aiquants/virtualscroll` instance without re-implementing list rendering. Every option is optional and mirrors the VirtualScroll API.
-
-- `overscanCount`: Adjust how many items render beyond the viewport for smoother scrolling (default: `10`).
-- `tapScrollCircleOptions`: Forward tap circle customization such as radius or visual renderer.
-- `scrollBarWidth`: Override the custom scrollbar width.
-- `enableThumbDrag`, `enableTrackClick`, `enableArrowButtons`, `enablePointerDrag`: Toggle individual scrollbar interactions.
-- `inertiaOptions`: Fine-tune inertial scrolling parameters.
-- `onScroll`, `onRangeChange`, `className`, `background`, `initialScrollIndex`, `initialScrollOffset`: Hook into scroll lifecycle or provide bespoke styling.
-
-Example:
-
-```tsx
-<DirectoryTree
-  {...commonProps}
-  virtualScroll={{
-    overscanCount: 6,
-    enablePointerDrag: false,
-    scrollBarWidth: 14,
-    tapScrollCircleOptions: {
-      radius: 32
-    }
-  }}
-/>;
-```
-
-### useDirectoryTreeState Hook
-
-A hook for managing directory tree state with localStorage persistence.
-
-#### Parameters
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `options` | `UseDirectoryTreeStateProps` | Configuration options |
-
-#### Options
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `initialExpanded` | `Set<string>` | Initially expanded directories |
-| `storageKey` | `string` | localStorage key for persistence (default: 'directory-tree-state') |
-
-#### Returns
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `expanded` | `Set<string>` | Currently expanded directories |
-| `toggle` | `(path: string, relativePath: string) => void` | Toggle directory expansion |
-| `isExpanded` | `(path: string) => boolean` | Check if directory is expanded |
-| `expand` | `(path: string) => void` | Expand a directory |
-| `collapse` | `(path: string) => void` | Collapse a directory |
-| `expandMultiple` | `(paths: string[]) => void` | Expand multiple directories |
-| `collapseMultiple` | `(paths: string[]) => void` | Collapse multiple directories |
-| `collapseAll` | `() => void` | Collapse all directories |
-| `isPending` | `boolean` | Whether a transition is pending |
-
-### DirectoryEntry Type
-
-```typescript
-type DirectoryEntry = {
-  name: string;
-  absolutePath: string;
-  relativePath: string;
-  children: DirectoryEntry[] | null;
-};
-```
-
-## Styling
-
-The component uses Tailwind CSS for styling. Make sure you have Tailwind CSS configured in your project. The component supports both light and dark themes, but theme control is managed by the calling component.
-
-### Theme Control
-
-The `lineColor` prop allows you to control the tree line color based on your application's theme:
-
-```tsx
-import { useTheme } from './hooks/useTheme';
-
-function MyComponent() {
-  const { theme } = useTheme();
-
-  // Calculate line color based on theme
-  const lineColor = theme === "dark" ? "#4A5568" : "#A0AEC0";
+function MultiSelect() {
+  const [values, setValues] = useState<Option[]>([])
+  const workerUrls = useMemo(() => ({
+    indexWorker: indexWorkerUrl,
+    levenshteinWorker: levenshteinWorkerUrl,
+  }), [])
 
   return (
-    <DirectoryTree
-      // ... other props
-      visual={{
-        lineColor: lineColor
-      }}
+    <SelectBox
+      options={options}
+      value={values}
+      onChange={(val) => setValues(Array.isArray(val) ? val : [])}
+      multiple
+      placeholder="Select multiple..."
+      workerUrls={workerUrls}
     />
-  );
+  )
 }
 ```
 
-### Custom Styling
-
-You can customize the appearance by overriding the default Tailwind classes:
+## CSS Setup
 
-```tsx
-<DirectoryTree
-  visual={{
-    className: "custom-directory-tree",
-    style: { height: '400px' }
-  }}
-  // ... other props
-/>
-```
+Import the CSS in your application's stylesheet:
 
 ```css
-.custom-directory-tree {
-  /* Your custom styles */
-}
+@import "@aiquants/select-box/styles/select-box.css" layer(components);
 ```
 
-## Advanced Usage
+## API Reference
 
-### Large Datasets
+### SelectBox Props
 
-The component is optimized for large datasets through virtualization:
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `options` | `Option[]` | Yes | - | Array of selectable options |
+| `value` | `Option \| Option[]` | No | `undefined` | Current selection (controlled) |
+| `onChange` | `(value: Option \| Option[] \| null) => void` | No | `undefined` | Selection change callback |
+| `placeholder` | `string` | No | `"Select..."` | Placeholder text when nothing is selected |
+| `multiple` | `boolean` | No | `false` | Enable multi-select mode |
+| `className` | `string` | No | `""` | Additional CSS class for the container |
+| `disabled` | `boolean` | No | `false` | Disable the component |
+| `clearable` | `boolean` | No | `false` | Show a clear button (single-select) |
+| `autoFocus` | `boolean` | No | `false` | Auto-focus the input on mount |
+| `workerUrls` | `{ indexWorker?: string; levenshteinWorker?: string }` | No | `undefined` | Explicit Web Worker URLs (see below) |
+
+### Option Type
 
-```tsx
-import { DirectoryTree } from '@aiquants/directory-tree';
-
-// Handle thousands of entries efficiently
-<DirectoryTree
-  entries={largeDataset}
-  // ... other required props
-  visual={{
-    style: { height: '600px' }
-  }}
-/>
+```typescript
+interface Option {
+  label: string           // Display text (search target)
+  value: string | number  // Unique identifier
+  [key: string]: any      // Custom metadata
+}
 ```
 
-### Multiple Selection Mode
+## Web Worker URLs (Important)
 
-Enable multiple selection for batch operations:
+The fuzzy search uses Web Workers internally. In **Vite development mode**, the default `import.meta.url`-based Worker resolution may fail, causing errors like:
 
-```tsx
-const [selectedItems, setSelectedItems] = useState(new Set<string>());
-
-const handleSelectionChange = (path: string, isSelected: boolean) => {
-  setSelectedItems(prev => {
-    const newSet = new Set(prev);
-    if (isSelected) {
-      newSet.add(path);
-    } else {
-      newSet.delete(path);
-    }
-    return newSet;
-  });
-};
-
-<DirectoryTree
-  // ... other props
-  selection={{
-    mode: "multiple",
-    selectedItems: selectedItems,
-    onSelectionChange: handleSelectionChange,
-    onFileSelect: handleFileSelect // Required prop
-  }}
-/>
+```text
+[fuzzy-search] Index Worker Error
+[fuzzy-search] Index Worker: Ping timeout
+[fuzzy-search] Failed to rebuild index: Error: Index build timeout
 ```
 
-### Custom Double-Click Behavior
-
-Control how directories behave on double-click:
+To fix this, pass `workerUrls` with Vite's `?url` import:
 
 ```tsx
-<DirectoryTree
-  // ... other props
-  expansion={{
-    // ... required expansion props
-    doubleClickAction: "toggle" // Only toggle the clicked directory
-    // or
-    doubleClickAction: "recursive" // Expand/collapse all children (default)
+import indexWorkerUrl from "@aiquants/fuzzy-search/worker/indexWorker?url"
+import levenshteinWorkerUrl from "@aiquants/fuzzy-search/worker/levenshteinWorker?url"
+
+<SelectBox
+  options={options}
+  workerUrls={{
+    indexWorker: indexWorkerUrl,
+    levenshteinWorker: levenshteinWorkerUrl,
   }}
 />
 ```
 
-### State Persistence
+## Dependencies
 
-The `useDirectoryTreeState` hook automatically persists expansion state to localStorage:
+| Package | Purpose |
+|---------|---------|
+| `@aiquants/fuzzy-search` | Web Worker-based fuzzy search engine |
+| `@aiquants/virtualscroll` | Virtual scrolling for large lists |
+| `tailwind-merge` | Tailwind CSS class conflict resolution |
 
-```tsx
-const { toggle, isExpanded, expandMultiple, collapseMultiple } = useDirectoryTreeState({
-  storageKey: 'myapp-directory-tree',
-  initialExpanded: new Set(['/src', '/docs'])
-});
-```
-
-## TypeScript Support
-
-This package is written in TypeScript and provides comprehensive type definitions. All components and hooks are fully typed for the best development experience.
-
-## Contributing
+## Documentation
 
-We welcome contributions! Please feel free to submit issues and pull requests.
+See the [docs/specs/](docs/specs/) directory for detailed specifications.
 
 ## License
 
-MIT License - see the [LICENSE](LICENSE) file for details.
-
-## Author
-
-- **GitHub**: [fehde-k](https://github.com/fehde-k)
-- **X (formerly Twitter)**: [@fehdek](https://x.com/fehdek)
-
----
-
-Made with ❤️ by the AIQuants team.
+MIT