elastic-input 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ A syntax-aware smart autocomplete input for building structured queries. Support
 
 Built with React functional components and hooks (compatible with React 16.8+), zero runtime dependencies beyond React/ReactDOM, and fully inline-styled (no CSS imports required).
 
-Vibe-coded as a proof of concept with Claude Code
+**[Live Demo](https://krtools.github.io/elastic-input/)**
 
 ## Features
 
@@ -19,6 +19,12 @@ Vibe-coded as a proof of concept with Claude Code
 - **Fully configurable** — colors, structural styles, fonts, and layout are all customizable via props
 - **Dark mode ready** — ships with `DARK_COLORS` and `DARK_STYLES` presets
 
+## Installation
+
+```bash
+npm install elastic-input
+```
+
 ## Quick Start
 
 ```tsx
@@ -30,8 +36,8 @@ const fields: FieldConfig[] = [
     name: 'status',
     label: 'Status',
     type: 'string',
-    suggestions: ['active', 'inactive', 'pending'],
     description: 'Account status',
+    placeholder: 'Search statuses...',
   },
   {
     name: 'created',
@@ -103,33 +109,36 @@ Implicit AND is supported — `status:active level:ERROR` is equivalent to `stat
 | `onValidationChange` | `(errors) => void` | — | Called when validation errors change |
 | `value` | `string` | — | Controlled input value |
 | `defaultValue` | `string` | — | Initial uncontrolled value |
-| `savedSearches` | `SavedSearch[] \| () => Promise<SavedSearch[]>` | — | Saved search definitions (sync or async) |
-| `searchHistory` | `HistoryEntry[] \| () => Promise<HistoryEntry[]>` | — | Search history entries (sync or async) |
-| `fetchSuggestions` | `(field, partial) => Promise<SuggestionItem[]>` | — | Async suggestion provider for field values |
+| `savedSearches` | `SavedSearch[] \| (partial) => Promise<SavedSearch[]>` | — | Saved search definitions (sync array or async callback with partial) |
+| `searchHistory` | `HistoryEntry[] \| (partial) => Promise<HistoryEntry[]>` | — | Search history entries (sync array or async callback with partial) |
+| `fetchSuggestions` | `(field, partial) => Promise<SuggestionItem[]>` | — | Async suggestion provider for field values (called for all non-boolean fields) |
 | `colors` | `ColorConfig` | `DEFAULT_COLORS` | Syntax highlighting and UI colors |
 | `styles` | `StyleConfig` | `DEFAULT_STYLES` | Structural/layout style overrides |
 | `placeholder` | `string` | `"Search..."` | Placeholder text |
 | `className` | `string` | — | CSS class for the outer container |
+| `classNames` | `ClassNamesConfig` | — | Custom CSS classes for sub-elements (editor, dropdown, tokens, etc.) |
 | `style` | `CSSProperties` | — | Inline styles for the outer container |
 | `inputRef` | `(api) => void` | — | Receive an imperative API handle |
-| `dropdown` | `DropdownConfig` | `{}` | Dropdown behavior and rendering (mode, triggers, renderers) |
+| `dropdown` | `DropdownConfig` | `{}` | Dropdown behavior and rendering (open, triggers, renderers) |
 | `features` | `FeaturesConfig` | `{}` | Feature toggles (multiline, smartSelectAll, expandSelection, wildcardWrap, savedSearches, historySearch) |
 | `onKeyDown` | `(e) => void` | — | Called before internal keyboard handling |
 | `onFocus` | `() => void` | — | Called when the input gains focus |
 | `onBlur` | `() => void` | — | Called when the input loses focus |
 | `onTab` | `(context) => TabActionResult` | — | Override Tab key behavior (accept/blur/submit) |
 | `validateValue` | `(ctx) => ValidateReturn` | — | Custom validation for all value types |
+| `parseDate` | `(value: string) => Date \| null` | — | Custom date parser for validation and date picker init |
 
 ## Field Configuration
 
 ```typescript
 interface FieldConfig {
-  name: string;          // Field identifier used in queries
-  label?: string;        // Display label (used in autocomplete)
-  type: FieldType;       // 'string' | 'number' | 'date' | 'boolean' | 'ip'
-  suggestions?: string[];// Autocomplete values (any field type can have suggestions)
-  operators?: string[];  // Allowed operators (future use)
-  description?: string;  // Shown in autocomplete dropdown
+  name: string;           // Field identifier used in queries
+  label?: string;         // Display label (used in autocomplete)
+  type: FieldType;        // 'string' | 'number' | 'date' | 'boolean' | 'ip'
+  aliases?: string[];     // Alternative names that resolve to this field
+  operators?: string[];   // Allowed operators (future use)
+  description?: string;   // Shown in autocomplete dropdown
+  placeholder?: string | false; // Hint shown while typing a value (false to suppress)
 }
 ```
 
@@ -233,12 +242,15 @@ const savedSearches = [
 
 Type `#` in the input to see saved search suggestions. Selecting one replaces the `#token` with the saved query text.
 
-Supports async loading:
+Supports async loading with per-keystroke filtering:
 
 ```tsx
 <ElasticInput
   fields={fields}
-  savedSearches={() => fetch('/api/saved-searches').then(r => r.json())}
+  savedSearches={async (partial) => {
+    const res = await fetch(`/api/saved-searches?q=${partial}`);
+    return res.json();
+  }}
 />
 ```
 
@@ -260,9 +272,21 @@ const history = [
 
 Type `!` to see history suggestions. Selecting one inserts the query (wrapped in parentheses if it contains boolean operators).
 
+Supports async loading with per-keystroke filtering:
+
+```tsx
+<ElasticInput
+  fields={fields}
+  searchHistory={async (partial) => {
+    const res = await fetch(`/api/history?q=${partial}`);
+    return res.json();
+  }}
+/>
+```
+
 ## Async Suggestions
 
-Provide dynamic suggestions for field values:
+Provide dynamic suggestions for field values. Called for all non-boolean field value contexts when provided:
 
 ```tsx
 <ElasticInput
@@ -395,7 +419,7 @@ const ast = parser.parse();
 
 // Validate
 const fields: FieldConfig[] = [
-  { name: 'status', type: 'string', suggestions: ['active', 'inactive'] },
+  { name: 'status', type: 'string' },
   { name: 'price', type: 'number' },
 ];
 const validator = new Validator(fields);

package/dist/autocomplete/AutocompleteEngine.d.ts

@@ -12,6 +12,10 @@ export interface AutocompleteResult {
 export interface AutocompleteOptions {
     showSavedSearchHint?: boolean;
     showHistoryHint?: boolean;
+    /** Set to true when a savedSearches callback is provided (for hints even when no sync data). */
+    hasSavedSearchProvider?: boolean;
+    /** Set to true when a searchHistory callback is provided (for hints even when no sync data). */
+    hasHistoryProvider?: boolean;
 }
 export declare class AutocompleteEngine {
     private fields;
@@ -33,4 +37,10 @@ export declare class AutocompleteEngine {
     private getSpecialHints;
     private getSavedSearchSuggestions;
     private getHistorySuggestions;
+    /**
+     * Wraps a history query in parens if the top-level AST node is a BooleanExpr
+     * (explicit AND/OR or implicit adjacency). Already-grouped expressions
+     * like -(a AND b) or (a OR b)^2 don't need extra wrapping.
+     */
+    static wrapHistoryQuery(query: string): string;
 }

package/dist/components/AutocompleteDropdown.d.ts

@@ -19,6 +19,12 @@ interface AutocompleteDropdownProps {
     renderSavedSearchItem?: (search: SavedSearch, isSelected: boolean) => React.ReactNode | null | undefined;
     renderDropdownHeader?: (context: CursorContext) => React.ReactNode | null | undefined;
     cursorContext?: CursorContext | null;
+    /** Custom class names for dropdown elements. */
+    classNames?: {
+        dropdown?: string;
+        dropdownHeader?: string;
+        dropdownItem?: string;
+    };
 }
-export declare function AutocompleteDropdown({ suggestions, selectedIndex, onSelect, position, colors, styles, visible, fixedWidth, renderHistoryItem, renderSavedSearchItem, renderDropdownHeader, cursorContext, }: AutocompleteDropdownProps): React.ReactPortal | null;
+export declare function AutocompleteDropdown({ suggestions, selectedIndex, onSelect, position, colors, styles, visible, fixedWidth, renderHistoryItem, renderSavedSearchItem, renderDropdownHeader, cursorContext, classNames, }: AutocompleteDropdownProps): React.ReactPortal | null;
 export {};

package/dist/components/DateRangePicker.d.ts

@@ -11,6 +11,8 @@ interface DateRangePickerProps {
         label: string;
         value: string;
     }[];
+    /** Custom class name for the date picker container. */
+    className?: string;
 }
-export declare function DateRangePicker({ onSelect, colors, styles: styleConfig, initialMode, initialStart, initialEnd, presets: presetsProp }: DateRangePickerProps): React.JSX.Element;
+export declare function DateRangePicker({ onSelect, colors, styles: styleConfig, initialMode, initialStart, initialEnd, presets: presetsProp, className }: DateRangePickerProps): React.JSX.Element;
 export {};

package/dist/components/ElasticInput.d.ts

@@ -16,7 +16,7 @@ export declare function computeDatePickerInit(context: {
     token?: {
         value: string;
     };
-}): DatePickerInit | null;
+}, parseDateFn?: (value: string) => Date | null): DatePickerInit | null;
 /**
  * Determine whether the date picker needs to be unmounted and remounted.
  * This is necessary when initial state changes because DateRangePicker

package/dist/components/HighlightedContent.d.ts

@@ -3,5 +3,7 @@ import { ColorConfig } from '../types';
 
 export interface HighlightOptions {
     cursorOffset?: number;
+    /** Custom class name appended to every token span. */
+    tokenClassName?: string;
 }
 export declare function buildHighlightedHTML(tokens: Token[], colorConfig?: ColorConfig, options?: HighlightOptions): string;

package/dist/components/ValidationSquiggles.d.ts

@@ -8,6 +8,11 @@ interface ValidationSquigglesProps {
     colors?: ColorConfig;
     styles?: StyleConfig;
     containerRef?: HTMLDivElement | null;
+    /** Custom class names for squiggly and tooltip elements. */
+    classNames?: {
+        squiggly?: string;
+        tooltip?: string;
+    };
 }
-export declare function ValidationSquiggles({ errors, editorRef, cursorOffset, colors, styles, containerRef }: ValidationSquigglesProps): React.JSX.Element | null;
+export declare function ValidationSquiggles({ errors, editorRef, cursorOffset, colors, styles, containerRef, classNames }: ValidationSquigglesProps): React.JSX.Element | null;
 export {};