inquirerjs-checkbox-search 0.2.1 → 0.4.0

package/README.md

@@ -2,6 +2,8 @@
 
 A multi-select prompt with text filtering/search capability for [inquirer.js](https://github.com/SBoudrias/Inquirer.js).
 
+<img src="docs/img/header.gif" alt="Demo showing inquirerjs-checkbox-search in action" width="100%">
+
 This prompt combines the functionality of `@inquirer/checkbox` and `@inquirer/search`, allowing you to:
 
 - ✅ **Multi-select** multiple options with checkboxes
@@ -38,19 +40,19 @@ console.log('Selected:', selected);
 
 ### 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       | Fixed number of choices to display. If not specified, auto-sizes based on terminal height (fallback: 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                                                                                  |
+| 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 \| PageSizeConfig`                                                          | No       | Page size configuration. Can be a number (fixed size) or PageSizeConfig object for advanced control. If not specified, auto-sizes based on terminal height (fallback: 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.
 
@@ -67,6 +69,33 @@ type Choice<Value = any> = {
 };
 ```
 
+### PageSize Configuration
+
+The `pageSize` property accepts either a number (for simple fixed sizing) or a `PageSizeConfig` object for advanced control:
+
+```typescript
+type PageSizeConfig = {
+  base?: number; // Starting page size (if not specified, auto-calculated from terminal)
+  max?: number; // Maximum page size (absolute constraint)
+  min?: number; // Minimum page size (absolute constraint, defaults to 1)
+  buffer?: number; // Fixed buffer lines to subtract from page size
+  autoBufferDescriptions?: boolean; // Auto-reserve space for descriptions
+  autoBufferCountsLineWidth?: boolean; // Consider terminal width when counting description lines
+  minBuffer?: number; // Minimum buffer lines (applied after auto/manual buffer)
+};
+```
+
+**Buffer Calculation Process:**
+
+1. Start with base page size (from `base` or auto-calculated)
+2. Calculate buffer:
+   - If `autoBufferDescriptions` is true: Add lines needed for largest description
+   - Otherwise: Add `buffer` value (if specified)
+   - Ensure buffer is at least `minBuffer` (if specified)
+3. Subtract buffer from base page size
+4. Apply `min`/`max` constraints
+5. Ensure final result is at least 1
+
 ### Theme Options
 
 ```typescript
@@ -102,21 +131,7 @@ type CheckboxSearchTheme = {
 
 ## 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.
+For detailed examples of advanced features, see the [`examples/`](./examples/) directory.
 
 Each example includes detailed comments and demonstrates real-world usage patterns.
 

package/dist/commonjs/index.d.ts

@@ -44,6 +44,43 @@ export type NormalizedChoice<Value> = {
     disabled: boolean | string;
     checked: boolean;
 };
+/**
+ * Configuration options for the checkbox-search prompt
+ */
+export type PageSizeConfig = {
+    base?: number;
+    max?: number;
+    min?: number;
+    autoBufferDescriptions?: boolean;
+    buffer?: number;
+    minBuffer?: number;
+    autoBufferCountsLineWidth?: boolean;
+};
+export type PageSize = number | PageSizeConfig;
+/**
+ * Internal item type (choice or separator)
+ */
+type Item<Value> = NormalizedChoice<Value> | Separator;
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+export declare function validatePageSizeConfig(config: PageSizeConfig): void;
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+export declare function calculateDescriptionLines<Value>(items: readonly Item<Value>[], countLineWidth: boolean): number;
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+export declare function resolvePageSize<Value>(pageSize: PageSize, items: readonly Item<Value>[]): number;
 /**
  * Calculate dynamic page size based on terminal height
  * @param fallbackPageSize - Default page size to use if terminal height is not available
@@ -69,7 +106,7 @@ export declare function calculateDynamicPageSize(fallbackPageSize: number): numb
 declare const _default: <Value>(config: {
     message: string;
     prefix?: string | undefined;
-    pageSize?: number | undefined;
+    pageSize?: PageSize | undefined;
     instructions?: string | boolean | undefined;
     choices?: readonly (string | Separator)[] | readonly (Separator | Choice<Value>)[] | undefined;
     source?: ((term: string | undefined, opt: {

package/dist/commonjs/index.js

@@ -4,6 +4,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Separator = void 0;
+exports.validatePageSizeConfig = validatePageSizeConfig;
+exports.calculateDescriptionLines = calculateDescriptionLines;
+exports.resolvePageSize = resolvePageSize;
 exports.calculateDynamicPageSize = calculateDynamicPageSize;
 const core_1 = require("@inquirer/core");
 const yoctocolors_cjs_1 = __importDefault(require("yoctocolors-cjs"));
@@ -105,6 +108,108 @@ function defaultFilter(items, term) {
             value.includes(searchTerm));
     });
 }
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+function validatePageSizeConfig(config) {
+    if (config.min !== undefined && config.min < 1) {
+        throw new Error('PageSize min cannot be less than 1');
+    }
+    if (config.base !== undefined && config.base < 1) {
+        throw new Error('PageSize base cannot be less than 1');
+    }
+    if (config.buffer !== undefined && config.buffer < 0) {
+        throw new Error('PageSize buffer cannot be negative');
+    }
+    if (config.minBuffer !== undefined && config.minBuffer < 0) {
+        throw new Error('PageSize minBuffer cannot be negative');
+    }
+    if (config.min !== undefined &&
+        config.max !== undefined &&
+        config.min > config.max) {
+        throw new Error(`PageSize min (${config.min}) cannot be greater than max (${config.max})`);
+    }
+}
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+function calculateDescriptionLines(items, countLineWidth) {
+    let maxLines = 0;
+    for (const item of items) {
+        if (core_1.Separator.isSeparator(item) || !item.description) {
+            continue;
+        }
+        let lines;
+        if (countLineWidth) {
+            // Consider terminal width for wrapping
+            const terminalWidth = process.stdout.columns || 80;
+            const descriptionLines = item.description.split('\n');
+            lines = descriptionLines.reduce((total, line) => {
+                return total + (Math.ceil(line.length / terminalWidth) || 1);
+            }, 0);
+        }
+        else {
+            // Simple newline counting
+            lines = item.description.split('\n').length;
+        }
+        maxLines = Math.max(maxLines, lines);
+    }
+    return maxLines;
+}
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+function resolvePageSize(pageSize, items) {
+    // Handle simple number case (backward compatibility)
+    if (typeof pageSize === 'number') {
+        return pageSize;
+    }
+    // Validate the configuration
+    validatePageSizeConfig(pageSize);
+    // Step 1: Determine base page size
+    let basePageSize;
+    if (pageSize.base !== undefined) {
+        basePageSize = pageSize.base;
+    }
+    else {
+        // Auto-calculate using existing logic
+        basePageSize = calculateDynamicPageSize(7);
+    }
+    // Step 2: Calculate buffer reduction
+    let buffer = 0;
+    // 2a: Start at 0 ✓
+    // 2b: If autoBufferDescriptions, add max description lines
+    if (pageSize.autoBufferDescriptions) {
+        buffer += calculateDescriptionLines(items, pageSize.autoBufferCountsLineWidth || false);
+    }
+    else {
+        // 2c: Add buffer value (only if not auto-buffering)
+        buffer += pageSize.buffer || 0;
+    }
+    // 2d: Ensure at least minBuffer
+    if (pageSize.minBuffer !== undefined) {
+        buffer = Math.max(buffer, pageSize.minBuffer);
+    }
+    // Step 3: Subtract buffer from base
+    let finalPageSize = basePageSize - buffer;
+    // Step 4: Apply min/max constraints
+    if (pageSize.min !== undefined) {
+        finalPageSize = Math.max(finalPageSize, pageSize.min);
+    }
+    if (pageSize.max !== undefined) {
+        finalPageSize = Math.min(finalPageSize, pageSize.max);
+    }
+    // Ensure minimum of 1
+    return Math.max(1, finalPageSize);
+}
 /**
  * Calculate dynamic page size based on terminal height
  * @param fallbackPageSize - Default page size to use if terminal height is not available
@@ -160,14 +265,6 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
     const emptyArray = (0, core_1.useMemo)(() => [], []);
     // Configuration with defaults
     const { pageSize: configPageSize, loop = true, required, validate = () => true, default: defaultValues = emptyArray, } = config;
-    // Calculate effective page size (memoized with terminal size tracking)
-    // If pageSize is specified, use it as fixed size
-    // If not specified, use auto-sizing that recalculates when terminal resizes
-    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
-    const pageSize = (0, core_1.useMemo)(() => configPageSize !== undefined
-        ? configPageSize // Fixed page size
-        : calculateDynamicPageSize(7), // Auto page size with fallback 7
-    [configPageSize, terminalHeight]);
     const theme = (0, core_1.makeTheme)(checkboxSearchTheme, config.theme);
     // State management hooks
     const [status, setStatus] = (0, core_1.useState)('idle');
@@ -190,6 +287,18 @@ exports.default = (0, core_1.createPrompt)((config, done) => {
         }
         return [];
     });
+    // Calculate effective page size (memoized with terminal size tracking)
+    // Use new resolvePageSize function to handle both number and PageSizeConfig
+    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
+    const pageSize = (0, core_1.useMemo)(() => {
+        if (configPageSize !== undefined) {
+            return resolvePageSize(configPageSize, allItems);
+        }
+        else {
+            // Default behavior - auto-calculate
+            return calculateDynamicPageSize(7);
+        }
+    }, [configPageSize, terminalHeight, allItems]);
     // Store the active item value instead of active index
     const [activeItemValue, setActiveItemValue] = (0, core_1.useState)(null);
     // Compute filtered items based on search term and filtering logic

package/dist/esm/index.d.ts

@@ -44,6 +44,43 @@ export type NormalizedChoice<Value> = {
     disabled: boolean | string;
     checked: boolean;
 };
+/**
+ * Configuration options for the checkbox-search prompt
+ */
+export type PageSizeConfig = {
+    base?: number;
+    max?: number;
+    min?: number;
+    autoBufferDescriptions?: boolean;
+    buffer?: number;
+    minBuffer?: number;
+    autoBufferCountsLineWidth?: boolean;
+};
+export type PageSize = number | PageSizeConfig;
+/**
+ * Internal item type (choice or separator)
+ */
+type Item<Value> = NormalizedChoice<Value> | Separator;
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+export declare function validatePageSizeConfig(config: PageSizeConfig): void;
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+export declare function calculateDescriptionLines<Value>(items: readonly Item<Value>[], countLineWidth: boolean): number;
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+export declare function resolvePageSize<Value>(pageSize: PageSize, items: readonly Item<Value>[]): number;
 /**
  * Calculate dynamic page size based on terminal height
  * @param fallbackPageSize - Default page size to use if terminal height is not available
@@ -69,7 +106,7 @@ export declare function calculateDynamicPageSize(fallbackPageSize: number): numb
 declare const _default: <Value>(config: {
     message: string;
     prefix?: string | undefined;
-    pageSize?: number | undefined;
+    pageSize?: PageSize | undefined;
     instructions?: string | boolean | undefined;
     choices?: readonly (string | Separator)[] | readonly (Separator | Choice<Value>)[] | undefined;
     source?: ((term: string | undefined, opt: {

package/dist/esm/index.js

@@ -98,6 +98,108 @@ function defaultFilter(items, term) {
             value.includes(searchTerm));
     });
 }
+/**
+ * Validate PageSizeConfig object for correctness
+ * @param config - PageSizeConfig to validate
+ * @throws Error if validation fails
+ */
+export function validatePageSizeConfig(config) {
+    if (config.min !== undefined && config.min < 1) {
+        throw new Error('PageSize min cannot be less than 1');
+    }
+    if (config.base !== undefined && config.base < 1) {
+        throw new Error('PageSize base cannot be less than 1');
+    }
+    if (config.buffer !== undefined && config.buffer < 0) {
+        throw new Error('PageSize buffer cannot be negative');
+    }
+    if (config.minBuffer !== undefined && config.minBuffer < 0) {
+        throw new Error('PageSize minBuffer cannot be negative');
+    }
+    if (config.min !== undefined &&
+        config.max !== undefined &&
+        config.min > config.max) {
+        throw new Error(`PageSize min (${config.min}) cannot be greater than max (${config.max})`);
+    }
+}
+/**
+ * Calculate the maximum number of lines needed for descriptions across all items
+ * @param items - Array of items to analyze
+ * @param countLineWidth - Whether to consider terminal width for line wrapping
+ * @returns Maximum lines needed by any description
+ */
+export function calculateDescriptionLines(items, countLineWidth) {
+    let maxLines = 0;
+    for (const item of items) {
+        if (Separator.isSeparator(item) || !item.description) {
+            continue;
+        }
+        let lines;
+        if (countLineWidth) {
+            // Consider terminal width for wrapping
+            const terminalWidth = process.stdout.columns || 80;
+            const descriptionLines = item.description.split('\n');
+            lines = descriptionLines.reduce((total, line) => {
+                return total + (Math.ceil(line.length / terminalWidth) || 1);
+            }, 0);
+        }
+        else {
+            // Simple newline counting
+            lines = item.description.split('\n').length;
+        }
+        maxLines = Math.max(maxLines, lines);
+    }
+    return maxLines;
+}
+/**
+ * Resolve PageSize configuration to a final numeric page size
+ * @param pageSize - PageSize configuration (number or PageSizeConfig)
+ * @param items - Current items to consider for auto-buffering
+ * @returns Final resolved page size
+ */
+export function resolvePageSize(pageSize, items) {
+    // Handle simple number case (backward compatibility)
+    if (typeof pageSize === 'number') {
+        return pageSize;
+    }
+    // Validate the configuration
+    validatePageSizeConfig(pageSize);
+    // Step 1: Determine base page size
+    let basePageSize;
+    if (pageSize.base !== undefined) {
+        basePageSize = pageSize.base;
+    }
+    else {
+        // Auto-calculate using existing logic
+        basePageSize = calculateDynamicPageSize(7);
+    }
+    // Step 2: Calculate buffer reduction
+    let buffer = 0;
+    // 2a: Start at 0 ✓
+    // 2b: If autoBufferDescriptions, add max description lines
+    if (pageSize.autoBufferDescriptions) {
+        buffer += calculateDescriptionLines(items, pageSize.autoBufferCountsLineWidth || false);
+    }
+    else {
+        // 2c: Add buffer value (only if not auto-buffering)
+        buffer += pageSize.buffer || 0;
+    }
+    // 2d: Ensure at least minBuffer
+    if (pageSize.minBuffer !== undefined) {
+        buffer = Math.max(buffer, pageSize.minBuffer);
+    }
+    // Step 3: Subtract buffer from base
+    let finalPageSize = basePageSize - buffer;
+    // Step 4: Apply min/max constraints
+    if (pageSize.min !== undefined) {
+        finalPageSize = Math.max(finalPageSize, pageSize.min);
+    }
+    if (pageSize.max !== undefined) {
+        finalPageSize = Math.min(finalPageSize, pageSize.max);
+    }
+    // Ensure minimum of 1
+    return Math.max(1, finalPageSize);
+}
 /**
  * Calculate dynamic page size based on terminal height
  * @param fallbackPageSize - Default page size to use if terminal height is not available
@@ -153,14 +255,6 @@ export default createPrompt((config, done) => {
     const emptyArray = useMemo(() => [], []);
     // Configuration with defaults
     const { pageSize: configPageSize, loop = true, required, validate = () => true, default: defaultValues = emptyArray, } = config;
-    // Calculate effective page size (memoized with terminal size tracking)
-    // If pageSize is specified, use it as fixed size
-    // If not specified, use auto-sizing that recalculates when terminal resizes
-    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
-    const pageSize = useMemo(() => configPageSize !== undefined
-        ? configPageSize // Fixed page size
-        : calculateDynamicPageSize(7), // Auto page size with fallback 7
-    [configPageSize, terminalHeight]);
     const theme = makeTheme(checkboxSearchTheme, config.theme);
     // State management hooks
     const [status, setStatus] = useState('idle');
@@ -183,6 +277,18 @@ export default createPrompt((config, done) => {
         }
         return [];
     });
+    // Calculate effective page size (memoized with terminal size tracking)
+    // Use new resolvePageSize function to handle both number and PageSizeConfig
+    const terminalHeight = process.stdout.rows; // Track terminal size for memoization
+    const pageSize = useMemo(() => {
+        if (configPageSize !== undefined) {
+            return resolvePageSize(configPageSize, allItems);
+        }
+        else {
+            // Default behavior - auto-calculate
+            return calculateDynamicPageSize(7);
+        }
+    }, [configPageSize, terminalHeight, allItems]);
     // Store the active item value instead of active index
     const [activeItemValue, setActiveItemValue] = useState(null);
     // Compute filtered items based on search term and filtering logic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inquirerjs-checkbox-search",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "A multi-select prompt with text filtering for inquirer.js",
   "keywords": [
     "answer",
@@ -70,15 +70,22 @@
     "lint:check": "eslint . --ext .ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "test": "npm run format && npm run lint && npm run typecheck && npm run test:unit",
-    "test:ci": "npm run format:check && npm run lint:check && npm run typecheck && npm run test:unit",
+    "quality": "npm run format && npm run lint && npm run typecheck",
+    "quality:check": "npm run format:check && npm run lint:check && npm run typecheck",
+    "test": "npm run quality && npm run test:unit",
+    "test:ci": "npm run quality:check && npm run test:coverage",
     "test:unit": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:ui": "vitest --ui",
     "typecheck": "tsc --noEmit",
     "attw": "attw --pack",
     "pkg:inspect": "rimraf package-inspect *.tgz && npm run build && npm pack && mkdir package-inspect && tar -xzf *.tgz -C package-inspect && echo '\\n📦 Package extracted to package-inspect/ for inspection'",
-    "prepublishOnly": "npm run clean && npm run build && npm run test:ci && npm run attw"
+    "prepublishOnly": "npm run clean && npm run build && npm run test:ci && npm run attw",
+    "demo:docker:build": "docker build -f demos/Dockerfile -t vhs-node-demo .",
+    "demo:docker:run": "docker run --rm -v $PWD/docs/img:/workspace/docs/img vhs-node-demo",
+    "demo:generate:basic": "npm run demo:docker:build && npm run demo:docker:run demos/basic.tape",
+    "demo:generate:all": "npm run demo:generate:basic",
+    "demo:generate": "npm run demo:generate:basic"
   },
   "dependencies": {
     "@inquirer/core": "^10.1.13",