Natural Language Sync Widget

[tharropoulos]

TLDR

Adds natural language search widget for automatic UI state synchronization and proper module exports for widgets.

Change summary

Added Features:

1. New Widget in src/widgets/naturalLanguageSync.js:

   • connectNaturalLanguageSync(): Connector function that handles natural language UI state synchronization logic
   • naturalLanguageSync(): Headless widget that automatically applies natural language search results to InstantSearch UI state
   • Advanced filter expression parser with tokenization support for complex Typesense filter syntax
   • Mapping system that converts parsed filters to InstantSearch refinementList, numericMenu, and sortBy states

2. Widget Export System:

   • widgets.js: Main export file for all widgets at package root
   • src/widgets/index.js: Internal widget aggregation file
   • Updated src/TypesenseInstantsearchAdapter.js to re-export widgets for easy access

Code Changes:

1. In package.json:

   • Added new exports configuration with dedicated /widgets entry point
   • Updated files array to include widgets.js and widgets.d.ts
   • Bumped typesense-js dependency from ^2.1.0-8 to ^2.1.0-13

2. In src/widgets/index.d.ts:

   • Complete TypeScript definitions for natural language search interfaces
   • NaturalLanguageUiState, NaturalLanguageSearchResults, and widget parameter types
   • Proper InstantSearch.js connector and widget type integration

Test Coverage:

1. In test/natural_language_search.test.js:
   • Unit tests for filter parsing with complex expressions
   • Widget integration tests with mock InstantSearch instances
   • Token-based parser validation for various filter formats
   • Edge case handling for malformed filters and empty states

Documentation and Examples:

1. In test/support/testground/natural_language_search.html:

   • Interactive demo page showcasing natural language search capabilities
   • Example queries like "best rated phones under 500 dollars"
   • Real-time display of parsed natural language parameters

2. In test/support/testground/src/natural_language_search.js:

   • Complete implementation example using the natural language widget
   • Integration with existing InstantSearch widgets
   • Debug logging and state change monitoring

Build System Updates:

1. In test/support/testground/package.json:
   • Migrated from Parcel v1 to v2 for better module support
   • Updated build scripts to include natural language search demo
   • Updated dependencies for modern bundling

The natural language search widget automatically detects when search results contain parsed natural language data and applies the corresponding UI state changes to InstantSearch widgets without requiring manual intervention from developers.