Cursor rule

1---
2description: Writing JavaScript inside `.js` files, or within the `{% javascript %}` or `{% script %}` tags in `.liquid` files.
3globs:
4alwaysApply: false
5---
6# JavaScript Standards
7 
8## General Principles
9 
10- **Zero external dependencies** - Use native browser APIs
11- **Avoid mutation** - Use `const` over `let` unless necessary
12- **Use `for (const item of items)`** over `items.forEach()`
13- **Add new lines before blocks** with `{` and `}`
14- **Use the component framework** - See [the framework code](mdc:assets/component.js) and the [component documentation](mdc:codex/component-framework.md)
15 
16## Async/Await Syntax
17 
18**Always use async/await over .then() chaining:**
19 
20```javascript
21const fetchProducts = async () => {
22  try {
23    const response = await fetch('/products.json');
24    const data = await response.json();
25    return data.products;
26  } catch (error) {
27    console.error('Failed to fetch products:', error);
28    return [];
29  }
30};
31 
32## Web Components Pattern
33 
34**Initialize JavaScript components using the Component framework:**
35 
36```javascript
37import { Component } from '@theme/component';
38 
39/**
40 * @typedef {Object} ProductCardRefs
41 * @property {HTMLButtonElement} addButton - Add to cart button
42 * @property {HTMLElement} priceDisplay - Price display element
43 * @property {HTMLImageElement} [productImage] - Optional product image
44 */
45 
46/**
47 * @extends {Component<ProductCardRefs>}
48 */
49class ProductCard extends Component {
50  constructor() {
51    super();
52    this.cache = new Map();
53  }
54 
55  connectedCallback() {
56    super.connectedCallback();
57    this.#initializeCard();
58  }
59 
60  disconnectedCallback() {
61    super.disconnectedCallback();
62    this.#cleanup();
63  }
64 
65  // Public method for external use
66  updatePrice(newPrice) {
67    if (!this.refs.priceDisplay) return;
68    this.refs.priceDisplay.textContent = newPrice;
69  }
70 
71  // Event handler for add to cart button
72  async handleAddToCart(event) {
73    event.preventDefault();
74 
75    const productId = this.cache.get('productId');
76    this.refs.addButton.disabled = true;
77    this.refs.addButton.textContent = 'Adding...';
78 
79    try {
80      await addToCart(productId);
81      this.refs.addButton.textContent = 'Added!';
82 
83      // Dispatch custom event for cart updates
84      this.dispatchEvent(new CustomEvent('cart:item-added', {
85        detail: { productId },
86        bubbles: true
87      }));
88    } catch (error) {
89      this.refs.addButton.textContent = 'Try again';
90      console.error('Add to cart error:', error);
91    } finally {
92      setTimeout(() => {
93        this.refs.addButton.disabled = false;
94        this.refs.addButton.textContent = 'Add to cart';
95      }, 2000);
96    }
97  }
98 
99  // Private method requiring instance access
100  #initializeCard() {
101    const productId = this.dataset.productId;
102    this.cache.set('productId', productId);
103  }
104 
105  #cleanup() {
106    this.cache.clear();
107  }
108}
109 
110// Module-scoped utility - no instance access needed
111const addToCart = async (productId) => {
112  const formData = new FormData();
113  formData.append('id', productId);
114  formData.append('quantity', 1);
115 
116  try {
117    const response = await fetch('/cart/add.js', {
118      method: 'POST',
119      body: formData
120    });
121 
122    if (!response.ok) {
123      throw new Error('Failed to add to cart');
124    }
125 
126    const cartData = await response.json();
127    return cartData;
128  } catch (error) {
129    console.error('Add to cart error:', error);
130    throw error;
131  }
132};
133 
134customElements.define('product-card', ProductCard);
135```
136 
137**HTML usage with the Component framework:**
138 
139```liquid
140<product-card data-product-id="{{ product.id }}">
141  <img ref="productImage" src="{{ product.featured_image | image_url }}" alt="{{ product.title }}">
142  <h3>{{ product.title }}</h3>
143  <div ref="priceDisplay" class="product-card__price">{{ product.price | money }}</div>
144  <button ref="addButton" on:click="/handleAddToCart" data-add-to-cart>
145    Add to cart
146  </button>
147</product-card>
148```
149 
150## Early Returns and Conditional Logic
151 
152**Use early returns over nested conditionals:**
153 
154```javascript
155// Good
156const processOrder = (order) => {
157  if (!order) return;
158  if (!order.items.length) return;
159  if (order.status !== 'pending') return;
160 
161  // Process the order
162  updateOrderStatus(order.id, 'processing');
163  sendConfirmationEmail(order.email);
164};
165 
166// Avoid
167const processOrder = (order) => {
168  if (order) {
169    if (order.items.length) {
170      if (order.status === 'pending') {
171        updateOrderStatus(order.id, 'processing');
172        sendConfirmationEmail(order.email);
173      }
174    }
175  }
176};
177```
178 
179**Optional chaining guidelines:**
180 
181```javascript
182// Multiple chains - use early return
183const updateButton = (product) => {
184  const button = product.querySelector('[data-ref="button"]');
185  if (!button) return;
186 
187  button.disabled = false;
188  button.textContent = 'Add to cart';
189};
190 
191// Single chain is fine
192const updateButton = (product) => {
193  const button = product.querySelector('[data-ref="button"]');
194  button?.enable();
195};
196```
197 
198## Simplification Patterns
199 
200**Ternary operators for simple conditions:**
201```javascript
202const buttonText = isLoading ? 'Loading...' : 'Add to cart';
203element.textContent = buttonText;
204```
205 
206**One-liner conditionals:**
207```javascript
208if (isOutOfStock) return;
209```
210 
211**Return boolean comparisons directly:**
212```javascript
213const isAvailable = product.available && product.price > 0;
214return isAvailable;
215```
216 
217## Event-Driven Architecture
218 
219**Use events for component communication:**
220 
221```javascript
222import { Component } from '@theme/component';
223 
224/**
225 * @typedef {Object} CartDrawerRefs
226 * @property {HTMLElement} itemCountDisplay - Element showing item count
227 * @property {HTMLButtonElement} closeButton - Close button
228 */
229 
230/**
231 * @extends {Component<CartDrawerRefs>}
232 */
233class CartDrawer extends Component {
234  handleCartUpdate() {
235    const itemCount = this.getItemCount();
236 
237    // Update local display
238    if (this.refs.itemCountDisplay) {
239      this.refs.itemCountDisplay.textContent = itemCount;
240    }
241 
242    // Dispatch custom event for other components
243    this.dispatchEvent(new CustomEvent('cart:updated', {
244      bubbles: true,
245      detail: { itemCount }
246    }));
247  }
248 
249  getItemCount() {
250    // Implementation to get cart item count
251    return this.querySelectorAll('.cart-item').length;
252  }
253}
254 
255/**
256 * @typedef {Object} CartCounterRefs
257 * @property {HTMLElement} countDisplay - The count display element
258 */
259 
260/**
261 * @extends {Component<CartCounterRefs>}
262 */
263class CartCounter extends Component {
264  connectedCallback() {
265    super.connectedCallback();
266    // Listen for cart updates
267    document.addEventListener('cart:updated', this.#handleCartUpdate.bind(this));
268  }
269 
270  #handleCartUpdate(event) {
271    if (this.refs.countDisplay) {
272      this.refs.countDisplay.textContent = event.detail.itemCount;
273    }
274  }
275}
276```
277 
278## JavaScript in Liquid Files
279 
280**Use `{% javascript %}` tags for component-specific scripts:**
281 
282```liquid
283{% javascript %}
284import { Component } from '@theme/component';
285 
286/**
287 * @typedef {Object} FeaturedCollectionRefs
288 * @property {HTMLElement} productGrid - The product grid container
289 * @property {HTMLButtonElement[]} filterButtons - Filter button elements
290 * @property {HTMLElement} [loadingIndicator] - Optional loading indicator
291 */
292 
293/**
294 * @extends {Component<FeaturedCollectionRefs>}
295 */
296class FeaturedCollection extends Component {
297  async handleFilter(filterValue, event) {
298    event.preventDefault();
299 
300    const url = new URL(window.location.href);
301    url.searchParams.set('filter', filterValue);
302 
303    // Show loading state
304    if (this.refs.loadingIndicator) {
305      this.refs.loadingIndicator.hidden = false;
306    }
307 
308    try {
309      const response = await fetch(url.toString());
310      const html = await response.text();
311      const parser = new DOMParser();
312      const doc = parser.parseFromString(html, 'text/html');
313 
314      const newGrid = doc.querySelector('.product-grid');
315 
316      if (newGrid && this.refs.productGrid) {
317        this.refs.productGrid.replaceWith(newGrid);
318        // Update the ref after replacement
319        this.#updateRefs();
320      }
321 
322      // Update URL without page reload
323      history.pushState({ filter: filterValue }, '', url.toString());
324    } catch (error) {
325      console.error('Filter error:', error);
326    } finally {
327      if (this.refs.loadingIndicator) {
328        this.refs.loadingIndicator.hidden = true;
329      }
330    }
331  }
332}
333 
334customElements.define('featured-collection', FeaturedCollection);
335{% endjavascript %}
336```
337 
338**HTML usage in Liquid template:**
339 
340```liquid
341<featured-collection>
342  <div class="filters">
343    <button ref="filterButtons[]" on:click="/handleFilter/new" data-filter="new">
344      New Arrivals
345    </button>
346    <button ref="filterButtons[]" on:click="/handleFilter/sale" data-filter="sale">
347      On Sale
348    </button>
349    <button ref="filterButtons[]" on:click="/handleFilter/best-selling" data-filter="best-selling">
350      Best Sellers
351    </button>
352  </div>
353 
354  <div ref="loadingIndicator" class="loading" hidden>Loading...</div>
355 
356  <div ref="productGrid" class="product-grid">
357    {% for product in collection.products %}
358      {% render 'product-card', product: product %}
359    {% endfor %}
360  </div>
361</featured-collection>
362```
363 
364## File Structure
365 
366**Group scripts by feature area:**
367- `product.js` - All product-related classes
368- `cart.js` - Cart functionality
369- `collection.js` - Collection and filtering
370- `search.js` - Search functionality
371 
372**Co-locate related classes:**
373```javascript
374// collection.js
375class CollectionFilters extends HTMLElement { }
376class CollectionGrid extends HTMLElement { }
377class CollectionSort extends HTMLElement { }
378```
379 
380## Optimistic UI Patterns
381 
382**Update UI before server response for high-certainty actions:**
383 
384```javascript
385import { Component } from '@theme/component';
386 
387/**
388 * @typedef {Object} AddToCartButtonRefs
389 * @property {HTMLElement} buttonText - The button text element
390 * @property {HTMLElement} [loadingSpinner] - Optional loading spinner
391 */
392 
393/**
394 * @extends {Component<AddToCartButtonRefs>}
395 */
396class AddToCartButton extends Component {
397  async handleAddToCart(event) {
398    event.preventDefault();
399 
400    // Optimistic UI update
401    this.#updateButtonState('adding');
402    this.#updateCartCount(1);
403 
404    try {
405      const result = await this.#addToCart();
406      this.#updateButtonState('added');
407    } catch (error) {
408      // Revert optimistic changes
409      this.#updateButtonState('error');
410      this.#updateCartCount(-1);
411      console.error('Add to cart failed:', error);
412    }
413  }
414 
415  #updateButtonState(state) {
416    const states = {
417      adding: 'Adding...',
418      added: 'Added!',
419      error: 'Try again'
420    };
421 
422    if (this.refs.buttonText) {
423      this.refs.buttonText.textContent = states[state] || 'Add to cart';
424    }
425 
426    // Toggle loading spinner if available
427    if (this.refs.loadingSpinner) {
428      this.refs.loadingSpinner.hidden = state !== 'adding';
429    }
430  }
431 
432  #updateCartCount(delta) {
433    const counter = document.querySelector('cart-counter-component');
434    if (!counter || typeof counter.updateCount !== 'function') return;
435 
436    // Call public method on cart counter component
437    counter.updateCount(delta);
438  }
439 
440  async #addToCart() {
441    // Implementation for adding to cart
442    const formData = new FormData();
443    formData.append('id', this.dataset.variantId);
444    formData.append('quantity', '1');
445 
446    const response = await fetch('/cart/add.js', {
447      method: 'POST',
448      body: formData
449    });
450 
451    if (!response.ok) {
452      throw new Error('Failed to add to cart');
453    }
454 
455    return response.json();
456  }
457}
458 
459customElements.define('add-to-cart-button', AddToCartButton);
460```
461 
462## Error Handling
463 
464**Always handle errors gracefully:**
465 
466```javascript
467const fetchData = async (url) => {
468  try {
469    const response = await fetch(url);
470 
471    if (!response.ok) {
472      throw new Error(`HTTP error! status: ${response.status}`);
473    }
474 
475    return await response.json();
476  } catch (error) {
477    console.error('Fetch error:', error);
478    // Return fallback data or empty state
479    return null;
480  }
481};
482```
483 
484## Type Safety with JSDoc
485 
486**Always annotate function parameters, return types, and complex objects:**
487 
488```javascript
489/**
490 * @typedef {Object} ProductData
491 * @property {string} id - Product identifier
492 * @property {number} price - Product price
493 * @property {boolean} [available] - Availability status (optional)
494 */
495 
496/**
497 * Updates product pricing display
498 * @param {ProductData} product - The product to update
499 * @param {HTMLElement} container - Target container element
500 * @returns {Promise<void>}
501 * @throws {Error} If container element is invalid
502 */
503const updateProductDisplay = async (product, container) => {
504  if (!(container instanceof HTMLElement)) {
505    throw new Error('Invalid container element');
506  }
507  // Implementation
508};
509```
510 
511### 2. **Enhance Component Communication Patterns**
512 
513Your current rules mention custom events but lack the detailed parent-child communication patterns. Expand the "Event-Driven Architecture" section:
514 
515```javascript
516## Component Communication Patterns
517 
518### Parent-to-Child Communication
519**Parents may invoke public methods on child components:**
520 
521```javascript
522import { Component } from '@theme/component';
523 
524/**
525 * @typedef {Object} ProductGalleryRefs
526 * @property {HTMLImageElement[]} images - Gallery images
527 * @property {HTMLElement} mainImage - Main display image
528 */
529 
530/**
531 * @extends {Component<ProductGalleryRefs>}
532 */
533class ProductGallery extends Component {
534  /**
535   * Selects a specific image by index
536   * @param {number} index - Image index to select
537   */
538  selectImage(index) {
539    const targetImage = this.refs.images[index];
540    if (targetImage && this.refs.mainImage) {
541      this.refs.mainImage.src = targetImage.dataset.fullSrc || targetImage.src;
542      this.#updateActiveState(index);
543    }
544  }
545 
546  #updateActiveState(activeIndex) {
547    this.refs.images.forEach((img, idx) => {
548      img.classList.toggle('active', idx === activeIndex);
549    });
550  }
551}
552 
553/**
554 * @typedef {Object} ProductPageRefs
555 * @property {ProductGallery} productGallery - Product gallery component
556 * @property {HTMLSelectElement} variantSelector - Variant selector
557 */
558 
559/**
560 * @extends {Component<ProductPageRefs>}
561 */
562class ProductPage extends Component {
563  handleVariantChange(event) {
564    const variantId = event.target.value;
565 
566    // Direct method invocation is acceptable from parent to child
567    if (this.refs.productGallery) {
568      this.refs.productGallery.selectImage(0);
569    }
570  }
571}
572```
573 
574### Child-to-Parent Communication
575**Children should emit custom events with typed details:**
576 
577```javascript
578/**
579 * @typedef {Object} VariantSelectDetail
580 * @property {string} variantId - Selected variant ID
581 * @property {number} price - Variant price
582 * @property {boolean} available - Variant availability
583 */
584 
585/**
586 * @typedef {Object} VariantSelectorRefs
587 * @property {HTMLSelectElement} variantSelect - Variant dropdown
588 * @property {HTMLElement} priceDisplay - Price display element
589 */
590 
591/**
592 * @extends {Component<VariantSelectorRefs>}
593 */
594class VariantSelector extends Component {
595  handleSelection(event) {
596    const selectedOption = event.target.selectedOptions[0];
597    const variantId = selectedOption.value;
598    const price = Number(selectedOption.dataset.price);
599    const available = selectedOption.dataset.available === 'true';
600 
601    /**
602     * @type {CustomEvent<VariantSelectDetail>}
603     */
604    const customEvent = new CustomEvent('variant:select', {
605      detail: { variantId, price, available },
606      bubbles: true
607    });
608 
609    this.dispatchEvent(customEvent);
610 
611    // Update local UI
612    if (this.refs.priceDisplay) {
613      this.refs.priceDisplay.textContent = this.#formatPrice(price);
614    }
615  }
616 
617  #formatPrice(price) {
618    return new Intl.NumberFormat('en-US', {
619      style: 'currency',
620      currency: 'USD'
621    }).format(price / 100);
622  }
623}
624```
625 
626### 3. **Add URL Handling Best Practices**
627 
628This is completely missing from your current rules and should be a dedicated section:
629 
630```javascript
631## URL Manipulation
632 
633**Always use URL and URLSearchParams APIs over string manipulation:**
634 
635```javascript
636// Good - Type-safe URL manipulation
637const updateFilters = (filters) => {
638  const url = new URL(window.location.href);
639
640  for (const [key, value] of Object.entries(filters)) {
641    if (value) {
642      url.searchParams.set(key, value);
643    } else {
644      url.searchParams.delete(key);
645    }
646  }
647
648  return url;
649};
650
651// Navigation with proper state management
652const navigateToFilters = (filters) => {
653  const url = updateFilters(filters);
654  const params = url.searchParams.toString();
655
656  history.pushState({ urlParameters: params }, '', url.toString());
657  updateProductGrid(url.searchParams);
658};
659
660// Avoid - String manipulation
661const updateFilters = (filters) => {
662  let url = window.location.pathname + '?';
663  url += Object.entries(filters)
664    .map(([key, value]) => `${key}=${encodeURIComponent(value)}`)
665    .join('&');
666  return url;
667};
668```
669 
670### 4. **Enhance Error Handling Section**
671 
672Your current error handling is basic. Expand it with defensive programming patterns:
673 
674```javascript
675## Defensive Programming and Error Handling
676 
677**Always validate DOM elements before use:**
678 
679```javascript
680/**
681 * @param {string} selector - CSS selector
682 * @returns {HTMLElement}
683 * @throws {Error} If element not found or invalid type
684 */
685const getRequiredElement = (selector) => {
686  const element = document.querySelector(selector);
687  if (!(element instanceof HTMLElement)) {
688    throw new Error(`Required element not found: ${selector}`);
689  }
690  return element;
691};
692
693**Handle async operations with proper cleanup:**
694
695```javascript
696import { Component } from '@theme/component';
697 
698/**
699 * @typedef {Object} DataLoaderRefs
700 * @property {HTMLElement} content - Content container
701 * @property {HTMLElement} [errorMessage] - Error display element
702 * @property {HTMLElement} [loadingIndicator] - Loading indicator
703 */
704 
705/**
706 * @extends {Component<DataLoaderRefs>}
707 */
708class DataLoader extends Component {
709  /** @type {AbortController|null} */
710  #abortController = null;
711 
712  async loadData(url) {
713    // Cancel previous request
714    this.#abortController?.abort();
715    this.#abortController = new AbortController();
716 
717    // Show loading state
718    this.#setLoadingState(true);
719 
720    try {
721      const response = await fetch(url, {
722        signal: this.#abortController.signal
723      });
724 
725      if (!response.ok) {
726        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
727      }
728 
729      const data = await response.json();
730      this.#displayData(data);
731      return data;
732    } catch (error) {
733      if (error.name === 'AbortError') {
734        console.log('Request cancelled');
735        return null;
736      }
737 
738      this.#displayError(error.message);
739      throw error;
740    } finally {
741      this.#setLoadingState(false);
742    }
743  }
744 
745  disconnectedCallback() {
746    super.disconnectedCallback();
747    this.#abortController?.abort();
748  }
749 
750  #setLoadingState(loading) {
751    if (this.refs.loadingIndicator) {
752      this.refs.loadingIndicator.hidden = !loading;
753    }
754    if (this.refs.content) {
755      this.refs.content.setAttribute('aria-busy', loading);
756    }
757  }
758 
759  #displayData(data) {
760    if (this.refs.content) {
761      // Implementation specific to data type
762      this.refs.content.textContent = JSON.stringify(data, null, 2);
763    }
764  }
765 
766  #displayError(message) {
767    if (this.refs.errorMessage) {
768      this.refs.errorMessage.textContent = message;
769      this.refs.errorMessage.hidden = false;
770    }
771  }
772}
773```
774 
775### 5. **Strengthen Web Components Pattern**
776 
777Your current web components section is good but could benefit from the new guidance on refs and type safety:
778 
779```javascript
780import { Component } from '@theme/component';
781 
782/**
783 * @typedef {Object} ProductCardRefs
784 * @property {HTMLButtonElement} addButton - Add to cart button
785 * @property {HTMLElement} priceDisplay - Price display element
786 * @property {HTMLImageElement} productImage - Product image
787 * @property {HTMLElement} [stockIndicator] - Optional stock indicator
788 */
789 
790/**
791 * @extends {Component<ProductCardRefs>}
792 */
793class ProductCard extends Component {
794  /** @type {AbortController|null} */
795  #addToCartController = null;
796 
797  // Specify required refs for this component
798  requiredRefs = ['addButton', 'priceDisplay'];
799 
800  connectedCallback() {
801    super.connectedCallback();
802    // Refs are automatically managed by Component base class
803    // No need to manually cache or update them
804  }
805 
806  disconnectedCallback() {
807    super.disconnectedCallback();
808    this.#addToCartController?.abort();
809  }
810 
811  /**
812   * Public method for external control
813   * @param {boolean} disabled - Whether to disable the card
814   */
815  setDisabled(disabled) {
816    this.refs.addButton.disabled = disabled;
817    this.classList.toggle('product-card--disabled', disabled);
818 
819    // Update optional elements if they exist
820    if (this.refs.stockIndicator) {
821      this.refs.stockIndicator.hidden = disabled;
822    }
823  }
824 
825  async handleAddToCart(event) {
826    event.preventDefault();
827 
828    // Cancel any pending requests
829    this.#addToCartController?.abort();
830    this.#addToCartController = new AbortController();
831 
832    try {
833      const response = await fetch('/cart/add.js', {
834        method: 'POST',
835        signal: this.#addToCartController.signal,
836        body: new FormData(event.target.form)
837      });
838 
839      if (!response.ok) throw new Error('Failed to add to cart');
840 
841      const result = await response.json();
842      this.#handleSuccess(result);
843    } catch (error) {
844      if (error.name !== 'AbortError') {
845        this.#handleError(error);
846      }
847    }
848  }
849 
850  #handleSuccess(result) {
851    this.refs.addButton.textContent = 'Added!';
852    this.dispatchEvent(new CustomEvent('product:added', {
853      detail: result,
854      bubbles: true
855    }));
856  }
857 
858  #handleError(error) {
859    this.refs.addButton.textContent = 'Error - Try again';
860    console.error('Add to cart error:', error);
861  }
862}
863 
864customElements.define('product-card', ProductCard);
865```
866 
867### 6. **Add Performance Optimization Section**
868 
869**Use debouncing for expensive operations:**
870 
871```javascript
872/**
873 * @param {Function} func - Function to debounce
874 * @param {number} wait - Wait time in milliseconds
875 * @returns {Function} Debounced function
876 */
877const debounce = (func, wait) => {
878  let timeout;
879  return function executedFunction(...args) {
880    const later = () => {
881      clearTimeout(timeout);
882      func.apply(this, args);
883    };
884    clearTimeout(timeout);
885    timeout = setTimeout(later, wait);
886  };
887};
888 
889class SearchInput extends Component {
890  constructor() {
891    super();
892    this.#debouncedSearch = debounce(this.performSearch.bind(this), 300);
893  }
894 
895  handleInput(event) {
896    const query = event.target.value.trim();
897 
898    if (query.length < 2) {
899      this.#clearResults();
900      return;
901    }
902 
903    this.#debouncedSearch(query);
904  }
905 
906  async performSearch(query) {
907    if (this.refs.loadingSpinner) {
908      this.refs.loadingSpinner.hidden = false;
909    }
910 
911    try {
912      const url = new URL('/search/suggest', window.location.origin);
913      url.searchParams.set('q', query);
914      url.searchParams.set('limit', '5');
915 
916      const response = await fetch(url);
917      const results = await response.json();
918 
919      this.#displayResults(results);
920    } catch (error) {
921      console.error('Search error:', error);
922      this.#clearResults();
923    } finally {
924      if (this.refs.loadingSpinner) {
925        this.refs.loadingSpinner.hidden = true;
926      }
927    }
928  }
929 
930  #displayResults(results) {
931    if (!this.refs.resultsContainer) return;
932 
933    // Implementation specific to your search results format
934    this.refs.resultsContainer.innerHTML = results
935      .map(result => `<div class="search-result">${result.title}</div>`)
936      .join('');
937  }
938 
939  #clearResults() {
940    if (this.refs.resultsContainer) {
941      this.refs.resultsContainer.innerHTML = '';
942    }
943  }
944 
945  /** @type {Function} */
946  #debouncedSearch;
947}
948 
949customElements.define('search-input', SearchInput);
950```
951