@rtd/use-suggestions

use-suggestions

A React hook for fetching search suggestions from a Fastify API. This package includes a custom hook, types, and constants to simplify integration with your React/TypeScript projects.

Installation

To install the package locally, you can use yarn add or npm install with a local file path:

yarn add @rtd/use-suggestions

or

npm install @rtd/use-suggestions

Using as a Submodule

To add this package as a submodule in your project, use the following commands:

git submodule add -b <tag> https://github.com/your-username/use-suggestions.git src/hooks/use-suggestions
git submodule update --init --recursive
cd src/hooks/use-suggestions
git checkout <tag>

Replace <tag> with the tag of the latest release you want to use.

Ignore the Submodule in Project ESLint

cd ../../..

Add the following line to your .eslintignore | .eslintrc.json file:

  "ignorePatterns": ["node_modules/", "src/hooks/useSuggestions/**/*"],

Add the submodule as a dependency in your package.json

  "dependencies": {
    "use-suggestions": "file:src/hooks/use-suggestions"
  }

Usage

Importing the Hook

Import the useSuggestions hook, types, and constants in your React component:

import React, { useState } from 'react'
import {
  useSuggestions,
  DEBOUNCE_TIME_IN_MS,
  SuggestionsOptions,
  ConfigObject,
  SearchableSuggestion,
} from '@rtd/use-suggestions'

Example Component

Here’s an example of how to use the useSuggestions hook in a React component:

const SuggestionComponent: React.FC = () => {
  const [query, setQuery] = useState('')
  const options: SuggestionsOptions = {
    includeStops: true,
    debounceTime: DEBOUNCE_TIME_IN_MS,
  }
  const baseUrl = 'https://your-api-base-url.com'
  const namespace = 'api/v1'
  const { suggestions, isLoading, error } = useSuggestions(
    query,
    options,
    { baseUrl, namespace }
  )

  return (
    <div>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Search for suggestions"
      />
      {isLoading && <p>Loading...</p>}
      {error && <p>Error: {error.message}</p>}
      <ul>
        {suggestions.map((suggestion: SearchableSuggestion) => (
          <li key={suggestion.id}>{suggestion.name}</li>
        ))}
      </ul>
    </div>
  )
}

export default SuggestionComponent

Hook API

useSuggestions

Fetches search suggestions from the API.

Parameters:

• rawQuery: string - The search query string.
• options: SuggestionsOptions - Configuration options for the suggestions.
• config: ConfigObject - Object that contains the base URL for the API and namespace (optional).

Returns:

• suggestions: SearchableSuggestion[] - An array of suggestions.
• isLoading: boolean - Loading state.
• error: Error | null - Error state.

Types

The package includes several types to help with type safety in your project:

SuggestionsOptions

Configuration options for the suggestions.

interface SuggestionsOptions {
  includeStops?: boolean
  includeRoutes?: boolean
  includeLocations?: boolean
  includeDestinations?: boolean
  includeConcerts?: boolean
  location?: {
    lat: number
    lng: number
  }
  debounceTime?: number
}

SearchableSuggestion

Base interface for a searchable suggestion.

interface SearchableSuggestion {
  suggestionType: SuggestionType
  name: string
  label: string
  slug: string
  lat: number
  lng: number
  searchTerms: string[]
}

Constants

The package includes the following constants:

DEBOUNCE_TIME_IN_MS

Default debounce time for the search query.

export const DEBOUNCE_TIME_IN_MS = 432

Building the Package

To build the package, run:

yarn build

This will compile the TypeScript files and output the results in the dist directory.

License

This project is licensed under the MIT License.