inquirerjs-checkbox-search 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Texarkanine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,289 @@
+# inquirerjs-checkbox-search
+
+A multi-select prompt with text filtering/search capability for [inquirer.js](https://github.com/SBoudrias/Inquirer.js).
+
+This prompt combines the functionality of `@inquirer/checkbox` and `@inquirer/search`, allowing you to:
+
+- ✅ **Multi-select** multiple options with checkboxes
+- 🔍 **Search/filter** options in real-time as you type
+- ⌨️ **Navigate** with arrow keys through filtered results
+
+## Installation
+
+<table>
+<tr>
+  <th>npm</th>
+  <th>yarn</th>
+  <th>pnpm</th>
+</tr>
+<tr>
+<td>
+
+```sh
+npm install inquirerjs-checkbox-search
+```
+
+</td>
+<td>
+
+```sh
+yarn add inquirerjs-checkbox-search
+```
+
+</td>
+<td>
+
+```sh
+pnpm add inquirerjs-checkbox-search
+```
+
+</td>
+</tr>
+</table>
+
+## Usage
+
+### Quick Start
+
+```typescript
+import checkboxSearch from 'inquirerjs-checkbox-search';
+
+const selected = await checkboxSearch({
+  message: 'Which frameworks do you use?',
+  choices: [
+    { value: 'react', name: 'React' },
+    { value: 'vue', name: 'Vue.js' },
+    { value: 'angular', name: 'Angular' },
+  ],
+});
+
+console.log('Selected:', selected);
+// => ['react', 'vue']
+```
+
+## API
+
+### Options
+
+| Property       | Type                                                                                | Required | Description                                            |
+| -------------- | ----------------------------------------------------------------------------------- | -------- | ------------------------------------------------------ |
+| `message`      | `string`                                                                            | Yes      | The question to ask                                    |
+| `choices`      | `Array<Choice \| string \| Separator>`                                              | No\*     | Static list of choices                                 |
+| `source`       | `(term?: string, opt: { signal: AbortSignal }) => Promise<Array<Choice \| string>>` | No\*     | Async function for dynamic choices                     |
+| `pageSize`     | `number`                                                                            | No       | Number of choices to display per page (default: 7)     |
+| `loop`         | `boolean`                                                                           | No       | Whether to loop around when navigating (default: true) |
+| `required`     | `boolean`                                                                           | No       | Require at least one selection (default: false)        |
+| `validate`     | `(selection: Array<Choice>) => boolean \| string \| Promise<string \| boolean>`     | No       | Custom validation function                             |
+| `instructions` | `string \| boolean`                                                                 | No       | Custom instructions text or false to hide              |
+| `theme`        | `Theme`                                                                             | No       | Custom theme configuration                             |
+| `default`      | `Array<Value>`                                                                      | No       | Initially selected values                              |
+| `filter`       | `(items: Array<Choice>, term: string) => Array<Choice>`                             | No       | Custom filter function                                 |
+
+\*Either `choices` or `source` must be provided.
+
+### Choice Object
+
+```typescript
+type Choice<Value = any> = {
+  value: Value; // The value returned when selected
+  name?: string; // Display text (defaults to value)
+  description?: string; // Additional description shown below
+  short?: string; // Shorter text for final answer
+  disabled?: boolean | string; // Whether choice is selectable
+  checked?: boolean; // Initially selected
+};
+```
+
+### Theme Options
+
+```typescript
+type CheckboxSearchTheme = {
+  icon: {
+    checked: string | ((text: string) => string);
+    unchecked: string | ((text: string) => string);
+    cursor: string | ((text: string) => string);
+  };
+  style: {
+    answer: (text: string) => string;
+    message: (text: string) => string;
+    error: (text: string) => string;
+    help: (text: string) => string;
+    highlight: (text: string) => string;
+    searchTerm: (text: string) => string;
+    description: (text: string) => string;
+    disabled: (text: string) => string;
+  };
+  helpMode: 'always' | 'never' | 'auto';
+};
+```
+
+## Keyboard Controls
+
+| Key                       | Action                             |
+| ------------------------- | ---------------------------------- |
+| <kbd>Type</kbd>           | Filter/search options              |
+| <kbd>↑</kbd>/<kbd>↓</kbd> | Navigate through options           |
+| <kbd>Tab</kbd>            | Toggle selection of current option |
+| <kbd>Escape</kbd>         | Clear search filter                |
+| <kbd>Enter</kbd>          | Confirm selection                  |
+
+## Advanced Features
+
+For detailed examples of advanced features, see the [`examples/`](./examples/) directory:
+
+- **[Basic Multi-Select](./examples/basic.js)** - Simple multi-select functionality
+- **[Search Filtering](./examples/search-filtering.js)** - Real-time search with larger lists
+- **[Async Source](./examples/async-source.js)** - Dynamic loading with mock API
+- **[Custom Theme](./examples/custom-theme.js)** - Custom icons and styling
+- **[Validation](./examples/validation.js)** - Input validation and pre-selection
+- **[Custom Filter](./examples/custom-filter.js)** - Fuzzy matching filter
+
+**To run examples:**
+
+1. Build the package: `npm run build`
+2. Run any example: `node examples/basic.js`
+
+See the [examples README](./examples/README.md) for detailed instructions.
+
+Each example includes detailed comments and demonstrates real-world usage patterns.
+
+## Developer Guide
+
+This section covers the tools and workflows used in this project for contributors and maintainers.
+
+### Tools Overview
+
+#### Build System
+
+- **[tshy](https://github.com/isaacs/tshy)** - Modern TypeScript build tool that generates both ESM and CommonJS outputs
+  - Configuration in `package.json` under `tshy` field
+  - Builds to `dist/esm/` and `dist/commonjs/`
+  - Automatically handles dual exports
+
+#### Package Management
+
+- **npm** - Package manager (npm 9+ required)
+- **Node.js 18+** - Runtime requirement
+- **package.json** - Standard npm configuration with dual exports
+
+#### Code Quality
+
+- **[ESLint](https://eslint.org/)** - Linting with TypeScript support
+  - Configuration: `eslint.config.js`
+  - Rules: TypeScript ESLint recommended + Prettier integration
+- **[Prettier](https://prettier.io/)** - Code formatting
+  - Configuration: `.prettierrc`
+- **[TypeScript](https://www.typescriptlang.org/)** - Type checking and compilation
+  - Configuration: `tsconfig.json`, `tsconfig.test.json`
+
+#### Testing
+
+- **[Vitest](https://vitest.dev/)** - Fast testing framework
+  - Configuration: `vitest.config.ts`
+  - Features: TypeScript support, coverage, UI mode, watch mode
+- **[@inquirer/testing](https://www.npmjs.com/package/@inquirer/testing)** - Testing utilities for inquirer prompts
+- **[@vitest/coverage-v8](https://www.npmjs.com/package/@vitest/coverage-v8)** - Coverage reporting
+
+#### Development Tools
+
+- **[@arethetypeswrong/cli](https://github.com/arethetypeswrong/arethetypeswrong.github.io)** - Package validation for dual exports
+- **[rimraf](https://github.com/isaacs/rimraf)** - Cross-platform file deletion
+
+### Development Workflows
+
+#### Setup & Installation
+
+```bash
+# Clone and install
+git clone https://github.com/texarkanine/inquirerjs-checkbox-search.git
+cd inquirerjs-checkbox-search
+npm install
+```
+
+#### Development Commands
+
+```bash
+# Development (watch mode)
+npm run dev                # Build in watch mode with tshy
+
+# Building
+npm run build             # Build for production
+npm run clean             # Clean build artifacts
+
+# Code Quality
+npm run lint              # Run ESLint (with --fix)
+npm run format            # Format code with Prettier
+npm run typecheck         # TypeScript type checking
+
+# Testing
+npm test                  # Run all code quality checks + tests
+npm run test:unit         # Run unit tests only
+npm run test:coverage     # Run tests with coverage report
+npm run test:ui           # Run tests with Vitest UI
+npm run test:unit -- --watch   # Run tests in watch mode
+
+# Package Validation
+npm run attw              # Validate package exports with arethetypeswrong
+
+# Pre-publish
+npm run prepublishOnly    # Full build + test + validation pipeline
+```
+
+#### File Structure
+
+```
+├── src/
+│   ├── index.ts          # Main prompt implementation
+│   └── *.test.ts         # Test files (excluded from build)
+├── dist/                 # Built output (generated by tshy)
+│   ├── esm/             # ES modules
+│   └── commonjs/        # CommonJS
+├── .github/
+│   └── workflows/       # CI/CD workflows
+├── node_modules/        # Dependencies
+├── package.json         # Package config with tshy setup
+├── tsconfig.json        # TypeScript config
+├── vitest.config.ts     # Test config
+├── eslint.config.js     # Linting config
+└── .prettierrc          # Formatting config
+```
+
+#### Quality Assurance Workflow
+
+1. **Before Committing**
+
+   ```bash
+   npm test                  # Run all quality checks + tests
+   ```
+
+2. **Before Publishing**
+   ```bash
+   npm run prepublishOnly    # Full validation pipeline
+   ```
+
+#### Build & Release Workflow
+
+1. **Development Build**
+
+   ```bash
+   npm run build             # One-time build
+   npm run dev               # Watch mode for development
+   ```
+
+2. **Package Validation**
+
+   ```bash
+   npm run attw              # Validate dual exports work correctly
+   ```
+
+3. **Release Process** (Automated)
+   - Push changes to `main` branch
+   - Release Please creates/updates release PR
+   - Merge release PR to trigger:
+     - GitHub release creation
+     - npm package publication
+     - Version tag creation
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.

package/dist/commonjs/index.d.ts

@@ -0,0 +1,82 @@
+import { Separator, type Theme } from '@inquirer/core';
+import type { PartialDeep } from '@inquirer/type';
+/**
+ * Theme configuration for the checkbox-search prompt
+ */
+type CheckboxSearchTheme = {
+    icon: {
+        checked: string | ((text: string) => string);
+        unchecked: string | ((text: string) => string);
+        cursor: string | ((text: string) => string);
+    };
+    style: {
+        answer: (text: string) => string;
+        message: (text: string) => string;
+        error: (text: string) => string;
+        help: (text: string) => string;
+        highlight: (text: string) => string;
+        searchTerm: (text: string) => string;
+        description: (text: string) => string;
+        disabled: (text: string) => string;
+    };
+    helpMode: 'always' | 'never' | 'auto';
+};
+/**
+ * Choice object for the checkbox-search prompt
+ */
+export type Choice<Value> = {
+    value: Value;
+    name?: string;
+    description?: string;
+    short?: string;
+    disabled?: boolean | string;
+    checked?: boolean;
+    type?: never;
+};
+/**
+ * Normalized choice object used internally
+ */
+export type NormalizedChoice<Value> = {
+    value: Value;
+    name: string;
+    description?: string;
+    short: string;
+    disabled: boolean | string;
+    checked: boolean;
+};
+/**
+ * Main checkbox-search prompt implementation
+ *
+ * A multi-select prompt with text filtering/search capability that combines
+ * the functionality of checkbox and search prompts from inquirer.js.
+ *
+ * Features:
+ * - Real-time search/filtering of options
+ * - Multi-selection with checkboxes
+ * - Keyboard navigation and shortcuts
+ * - Support for both static and async data sources
+ * - Customizable themes and validation
+ *
+ * @param config - Configuration options for the prompt
+ * @param done - Callback function called when prompt completes
+ */
+declare const _default: <Value>(config: {
+    message: string;
+    prefix?: string | undefined;
+    pageSize?: number | undefined;
+    instructions?: string | boolean | undefined;
+    choices?: readonly (string | Separator)[] | readonly (Separator | Choice<Value>)[] | undefined;
+    source?: ((term: string | undefined, opt: {
+        signal: AbortSignal;
+    }) => readonly (string | Separator)[] | readonly (Separator | Choice<Value>)[] | Promise<readonly (string | Separator)[]> | Promise<readonly (Separator | Choice<Value>)[]>) | undefined;
+    filter?: ((items: readonly NormalizedChoice<Value>[], term: string) => readonly NormalizedChoice<Value>[]) | undefined;
+    loop?: boolean | undefined;
+    required?: boolean | undefined;
+    validate?: ((choices: readonly NormalizedChoice<Value>[]) => boolean | string | Promise<string | boolean>) | undefined;
+    theme?: PartialDeep<Theme<CheckboxSearchTheme>> | undefined;
+    default?: readonly Value[] | undefined;
+}, context?: import("@inquirer/type").Context) => Promise<Value[]> & {
+    cancel: () => void;
+};
+export default _default;
+export { Separator } from '@inquirer/core';