[Research] Autocomplete Patterns in Web Components

Research Objective

Investigate best practices for implementing autocomplete functionality in Web Components for Search component migration.

Current State (Search.svelte)

• Custom autocomplete with keyboard navigation
• Suggestions from thesaurus/knowledge graph
• Support for AND/OR operators
• Position-aware dropdown
• Term chips with highlighting
• SSE for real-time updates
• Local storage persistence

Reference: desktop/src/lib/Search/Search.svelte:373-468

Research Questions

1. How to implement accessible autocomplete in Web Components?
2. Best libraries/patterns for dropdown positioning in Shadow DOM?
3. Keyboard navigation (arrow keys, Tab, Enter, Esc) patterns?
4. How to integrate with knowledge graph suggestions?
5. Performance optimization for large suggestion lists?

Autocomplete Patterns to Evaluate

1. Native <datalist> Element

Pros:

• Built-in browser support
• Accessible by default
• No JavaScript needed

Cons:

• Limited styling
• No custom rendering
• Basic functionality only

2. ARIA Combobox Pattern

Pros:

• Accessible
• Flexible
• Standard pattern

Cons:

• Manual implementation
• Complexity

Reference: WAI-ARIA Authoring Practices

3. Autocomplete Libraries for Web Components

a) @lion/ui combobox

• Pros: Web Components native, accessible
• Cons: Heavy framework

b) Shoelace <sl-select>

• Pros: Well-designed, accessible, themeable
• Cons: General select, not specialized autocomplete

c) Custom Implementation

• Pros: Full control, optimized
• Cons: Accessibility burden, testing

4. Virtual Scrolling for Large Lists

• Use @lit-labs/virtualizer or custom solution
• Essential for 1000+ suggestions

Key Features to Maintain

From Current Implementation:

• Fuzzy matching
• Keyboard navigation (↑↓←→, Tab, Enter, Esc)
• Highlight current selection
• Click to select
• Clear on Esc
• Support for operators (AND/OR)
• Term chips visualization
• Knowledge graph highlighting
• Debounced suggestions
• Position-aware dropdown

New Requirements:

• Shadow DOM compatibility
• Accessible (ARIA labels, roles, live regions)
• Touch-friendly (mobile)
• Theme-aware styling

Technical Challenges

Challenge 1: Dropdown Positioning in Shadow DOM

Problem: position: absolute scoped to Shadow DOM
Solutions:

• Use Floating UI / Popper.js
• Position in Light DOM with slot
• Use CSS top-layer (Popover API)

Challenge 2: Event Handling Across Shadow Boundary

Problem: Events don't bubble from Shadow to Light DOM naturally
Solutions:

• Re-dispatch CustomEvents with composed: true
• Use event delegation patterns
• Communication via properties/methods

Challenge 3: Integrating with Knowledge Graph

Problem: Async suggestions from backend
Solutions:

• Promise-based suggestion provider
• AbortController for request cancellation
• Caching layer

Acceptance Criteria

• Accessible autocomplete pattern selected
• Keyboard navigation fully functional
• Dropdown positioning solution
• Performance benchmark (1000+ suggestions)
• Integration pattern with KG backend
• Code example/prototype
• Migration path from current implementation

References

• Current Search component: desktop/src/lib/Search/Search.svelte
• Autocomplete utils: desktop/src/lib/Search/searchUtils.ts
• Knowledge graph integration: desktop/src/lib/services/novelAutocompleteService.ts

Documentation

Findings will be documented in: .docs/research-autocomplete-patterns.md

Start by reading desktop/src/lib/Search/Search.svelte:373-468, desktop/src/lib/Search/searchUtils.ts, and desktop/src/lib/services/novelAutocompleteService.ts to understand the current behavior and integration points. Compare the listed Web Components patterns, accessibility approaches, positioning options, and performance strategies. Done means documenting a selected pattern, prototype or code example, benchmark approach, knowledge-graph integration, and migration path in .docs/research-autocomplete-patterns.md.