### Turnstone Usage - Barebones Example

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

A basic example of how to use the Turnstone component with minimal configuration.

```APIDOC
## Usage - Barebones Example

This example demonstrates a barebones, unstyled Turnstone component.

### Code

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const App = () => {
  const listbox = {
    data: ['Peach', 'Pear', 'Pineapple', 'Plum', 'Pomegranate', 'Prune']
  }

  return (
    <Turnstone listbox={listbox} />
  )
}
```
```

--------------------------------

### Turnstone Installation

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Install Turnstone using npm.

```APIDOC
## Installation

Install Turnstone using npm:

```bash
$ npm install --save turnstone
```
```

--------------------------------

### Implement Production Search Component with Turnstone

Source: https://context7.com/tomsouthall/turnstone/llms.txt

This example demonstrates a full-featured Turnstone implementation, including asynchronous data fetching from multiple sources, custom styling via Tailwind CSS classes, and event handling for selection and submission. It utilizes React hooks for state management and provides a robust configuration for search behavior.

```jsx
import React, { useState, useCallback, useRef } from 'react'
import Turnstone from 'turnstone'

const styles = {
  container: 'relative w-full max-w-xl',
  input: 'w-full h-12 px-4 text-lg border border-gray-300 rounded-lg focus:outline-none focus:ring-2 focus:ring-blue-500',
  listbox: 'absolute w-full mt-1 bg-white border border-gray-200 rounded-lg shadow-lg max-h-80 overflow-y-auto z-50',
  groupHeading: 'px-4 py-2 text-xs font-semibold text-gray-500 uppercase bg-gray-50',
  item: 'px-4 py-3 cursor-pointer hover:bg-gray-100',
  highlightedItem: 'px-4 py-3 cursor-pointer bg-blue-50',
  clearButton: 'absolute right-3 top-1/2 -translate-y-1/2 text-gray-400 hover:text-gray-600',
  noItems: 'px-4 py-3 text-gray-500 italic'
}

const App = () => {
  const ref = useRef()
  const [selected, setSelected] = useState(null)

  const listbox = [
    {
      id: 'cities',
      name: 'Cities',
      ratio: 7,
      displayField: 'name',
      data: async (query) => {
        const response = await fetch(`/api/cities?q=${encodeURIComponent(query)}&limit=10`)
        if (!response.ok) throw new Error('API Error')
        return response.json()
      },
      searchType: 'startswith'
    },
    {
      id: 'airports',
      name: 'Airports',
      ratio: 3,
      displayField: 'name',
      data: async (query) => {
        const response = await fetch(`/api/airports?q=${encodeURIComponent(query)}&limit=10`)
        if (!response.ok) throw new Error('API Error')
        return response.json()
      },
      searchType: 'contains'
    }
  ]

  const defaultListbox = [
    {
      name: 'Popular Destinations',
      displayField: 'name',
      data: [
        { name: 'New York, USA', code: 'NYC' },
        { name: 'London, UK', code: 'LON' },
        { name: 'Paris, France', code: 'PAR' },
        { name: 'Tokyo, Japan', code: 'TYO' }
      ]
    }
  ]

  const handleSelect = useCallback((item, displayField) => {
    if (item) {
      setSelected(item)
      console.log('Selected:', item[displayField])
    }
  }, [])

  const handleEnter = useCallback((query, selectedItem) => {
    if (selectedItem) {
      console.log('Search submitted:', selectedItem.name)
    }
  }, [])

  return (
    <div className="p-8">
      <Turnstone
        ref={ref}
        id="location-search"
        name="location"
        listbox={listbox}
        defaultListbox={defaultListbox}
        defaultListboxIsImmutable={true}
        listboxIsImmutable={true}
        autoFocus={false}
        clearButton={true}
        cancelButton={true}
        debounceWait={250}
        disabled={false}
        enterKeyHint="search"
        errorMessage="Unable to fetch results. Please try again."
        matchText={true}
        maxItems={10}
        minQueryLength={1}
        noItemsMessage="No locations found matching your search"
        onSelect={handleSelect}
        onEnter={handleEnter}
        placeholder="Where are you going?"
        styles={styles}
        tabIndex={0}
        typeahead={true}
      />
      {selected && (
        <div className="mt-4 p-4 bg-green-50 rounded">
          Selected: {selected.name}
        </div>
      )}
    </div>
  )
}

export default App
```

--------------------------------

### Turnstone Usage - Styled Example with Grouped Results

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

An example of a styled Turnstone component fetching grouped search results from two API sources.

```APIDOC
## Usage - Styled Example with Grouped Results

This example shows a styled Turnstone component configured to fetch and display grouped search results from multiple API endpoints.

### Code

```jsx
import React, { useState } from 'react'
import Turnstone from 'turnstone'

const styles = {
  input,
  inputFocus,
  query,
  typeahead,
  cancelButton,
  clearButton,
  listbox,
  groupHeading,
  item,
  highlightedItem
}

const maxItems = 10

const listbox = [
  {
    id: 'cities',
    name: 'Cities',
    ratio: 8,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/cities?q=${encodeURIComponent(query)}&limit=${maxItems}`).then(response => response.json()),
    searchType: 'startswith'
  },
  {
    id: 'airports',
    name: 'Airports',
    ratio: 2,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/airports?q=${encodeURIComponent(query)}&limit=${maxItems}`).then(response => response.json()),
    searchType: 'contains'
  }
]

export default function Example() {
  return (
    <Turnstone
      cancelButton={true}
      debounceWait={250}
      id="search"
      listbox={listbox}
      listboxIsImmutable={true}
      matchText={true}
      maxItems={maxItems}
      name="search"
      noItemsMessage="We found no places that match your search"
      placeholder="Enter a city or airport"
      styles={styles}
      typeahead={true}
    />
  )
}
```
```

--------------------------------

### Dynamic Listbox with Function in Turnstone

Source: https://context7.com/tomsouthall/turnstone/llms.txt

This example shows how to use a function to dynamically generate the listbox content in Turnstone. This is useful for scenarios involving GraphQL or when combining results from multiple API endpoints, allowing for complex data structuring.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const listbox = (query) => {
  return fetch(`/api/search/locations?q=${encodeURIComponent(query)}`)
    .then(response => response.json())
    .then(locations => {
      const { cities, airports, hotels } = locations

      return [
        {
          id: 'cities',
          name: 'Cities',
          ratio: 5,
          displayField: 'name',
          data: cities,
          searchType: 'startswith'
        },
        {
          id: 'airports',
          name: 'Airports',
          ratio: 3,
          displayField: 'name',
          data: airports,
          searchType: 'contains'
        },
        {
          id: 'hotels',
          name: 'Hotels',
          ratio: 2,
          displayField: 'name',
          data: hotels,
          searchType: 'contains'
        }
      ]
    })
}

const App = () => (
  <Turnstone
    listbox={listbox}
    maxItems={10}
    debounceWait={300}
    placeholder="Search cities, airports, or hotels..."
    noItemsMessage="No results found"
    errorMessage="Search failed. Please try again."
  />
)

export default App
```

--------------------------------

### Install Turnstone via NPM

Source: https://context7.com/tomsouthall/turnstone/llms.txt

The command to install the Turnstone package into your React project using the npm package manager.

```bash
npm install --save turnstone
```

--------------------------------

### Using Turnstone Component Methods in React

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

This snippet demonstrates how to use the `useRef` hook in React to get a reference to the Turnstone component and call its methods like `query` and `clear`. It shows how to attach event handlers to buttons to trigger these methods.

```jsx
import React, { useRef } from 'react'
import Turnstone from 'turnstone'
import data from './data'

const App = () => {
  const listbox = { data }

  const turnstoneRef = useRef()

  const handleQuery = () => {
    turnstoneRef.current?.query('new')
  }

  const handleClear = () => {
    turnstoneRef.current?.clear()
  }

  return (
    <>
      <Turnstone ref={turnstoneRef} listbox={listbox} />
      <button onClick={handleQuery}>Perform Query</button>
      <button onClick={handleClear}>Clear Contents</button>
    </>
  )
}
```

--------------------------------

### Customizing Clear and Cancel Buttons in Turnstone

Source: https://context7.com/tomsouthall/turnstone/llms.txt

This example demonstrates how to replace the default clear and cancel buttons in Turnstone with custom React components. It shows how to define custom SVG components and pass them as props to the Turnstone component for a personalized UI.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const CustomClearButton = () => (
  <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
    <path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z"/>
  </svg>
)

const CustomCancelButton = () => (
  <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor">
    <path d="M20 11H7.83l5.59-5.59L12 4l-8 8 8 8 1.41-1.41L7.83 13H20v-2z"/>
  </svg>
)

const listbox = {
  data: ['Apple', 'Banana', 'Cherry', 'Date'],
  searchType: 'contains'
}

const App = () => (
  <Turnstone
    listbox={listbox}
    clearButton={true}
    cancelButton={true}
    clearButtonAriaLabel="Clear search"
    cancelButtonAriaLabel="Go back"
    Clear={CustomClearButton}
    Cancel={CustomCancelButton}
    placeholder="Search fruits..."
  />
)

export default App
```

--------------------------------

### Configure Turnstone Element Styles with Tailwind CSS

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

This snippet demonstrates how to define custom CSS classes for different Turnstone UI elements using Tailwind CSS. It shows an example object where keys map to specific elements like 'input', 'listbox', and 'item', and values are strings of Tailwind class names to style these elements. This allows for extensive visual customization of the search input and dropdown.

```jsx
{
  input: 'w-full h-12 border border-slate-300 py-2 pl-10 pr-7 text-xl outline-none rounded',
  inputFocus: 'w-full h-12 border-x-0 border-t-0 border-b border-blue-300 py-2 pl-10 pr-7 text-xl outline-none sm:rounded sm:border',
  query: 'text-slate-800 placeholder-slate-400',
  typeahead: 'text-blue-300 border-white',
  cancelButton: `absolute w-10 h-12 inset-y-0 left-0 items-center justify-center z-10 text-blue-400 inline-flex sm:hidden`,
  clearButton: 'absolute inset-y-0 right-0 w-8 inline-flex items-center justify-center text-slate-400 hover:text-rose-400',
  listbox: 'w-full bg-white sm:border sm:border-blue-300 sm:rounded text-left sm:mt-2 p-2 sm:drop-shadow-xl',
  groupHeading: 'cursor-default mt-2 mb-0.5 px-1.5 uppercase text-sm text-rose-300',
  item: 'cursor-pointer p-1.5 text-lg overflow-ellipsis overflow-hidden text-slate-700',
  highlightedItem: 'cursor-pointer p-1.5 text-lg overflow-ellipsis overflow-hidden text-slate-700 rounded bg-blue-50'
}
```

--------------------------------

### Implement Basic Static Autocomplete

Source: https://context7.com/tomsouthall/turnstone/llms.txt

Demonstrates the simplest implementation of Turnstone using a static array of strings for local filtering.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const App = () => {
  const listbox = {
    data: ['Peach', 'Pear', 'Pineapple', 'Plum', 'Pomegranate', 'Prune'],
    searchType: 'startswith'
  }

  return <Turnstone listbox={listbox} />
}

export default App
```

--------------------------------

### Configure Turnstone Plugins

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Demonstrates how to register plugins for the Turnstone component. Plugins can be passed as simple strings or as arrays containing the plugin name and an options object.

```jsx
[
  ['plugin1', { option1: true, option2: 'foo' }],
  'plugin2'
]
```

--------------------------------

### Basic Turnstone Usage in React

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Demonstrates a barebones, unstyled implementation of the Turnstone search component in a React application. It shows the basic import and rendering of the component with a simple list of data.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const App = () => {
  const listbox = {
    data: ['Peach', 'Pear', 'Pineapple', 'Plum', 'Pomegranate', 'Prune']
  }

  return (
    <Turnstone listbox={listbox} />
  )
}
```

--------------------------------

### Configuring Listbox Data Source

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

This section explains how to provide data to the listbox, either as a static array or dynamically via a function.

```APIDOC
## Providing Data to the Listbox

### Description
Configure the listbox's data source. This can be a static object for ungrouped items or a function for dynamic data fetching.

### Method
Configuration Object

### Endpoint
N/A

### Parameters
#### Request Body
- **`displayField`** (string) - Required - The field to display for each item.
- **`data`** (array | function) - Required - An array of items or a function that returns a promise resolving to an array of items.
- **`searchType`** (string) - Optional - The type of search to perform ('startswith' or 'contains'). Defaults to 'startswith'.

### Request Example (Ungrouped Items)
```json
{
  "displayField": "name",
  "data": (query) =>
    fetch(`/api/cities?q=${encodeURIComponent(query)}&limit=10`).then(res => res.json()),
  "searchType": "startswith"
}
```

### Request Example (Grouped Items via Function)
```javascript
(query) => fetch(`/api/locations?q=${encodeURIComponent(query)}`)
  .then(res => res.json())
  .then(locations => {
    const {cities, airports} = locations;

    return [
      {
        id: 'cities',
        name: 'Cities',
        ratio: 8,
        displayField: 'name',
        data: cities,
        searchType: 'startswith'
      },
      {
        id: 'airports',
        name: 'Airports',
        ratio: 2,
        displayField: 'name',
        data: airports,
        searchType: 'contains'
      }
    ];
  });
```

### Response
#### Success Response (200)
An array of items or an array of group objects, each containing an array of items.

#### Response Example (Ungrouped)
```json
[
  {"id": 1, "name": "New York"},
  {"id": 2, "name": "Los Angeles"}
]
```

#### Response Example (Grouped)
```json
[
  {
    "id": "cities",
    "name": "Cities",
    "ratio": 8,
    "displayField": "name",
    "data": [
      {"id": 1, "name": "New York"},
      {"id": 2, "name": "Los Angeles"}
    ],
    "searchType": "startswith"
  },
  {
    "id": "airports",
    "name": "Airports",
    "ratio": 2,
    "displayField": "name",
    "data": [
      {"id": 101, "name": "JFK"},
      {"id": 102, "name": "LAX"}
    ],
    "searchType": "contains"
  }
]
```
```

--------------------------------

### Configure Default Listbox with Popular Items

Source: https://context7.com/tomsouthall/turnstone/llms.txt

Demonstrates how to define a default listbox that displays popular or recent items when the search input is focused but empty. It uses a combination of static data and asynchronous local storage lookups.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const defaultListbox = [
  {
    name: 'Recent Searches',
    displayField: 'name',
    id: 'recent',
    ratio: 1,
    data: () => Promise.resolve(JSON.parse(localStorage.getItem('recent')) || [])
  },
  {
    name: 'Popular Cities',
    displayField: 'name',
    id: 'popular',
    ratio: 1,
    data: [
      { name: 'Paris, France', coords: '48.86425, 2.29416' },
      { name: 'Rome, Italy', coords: '41.89205, 12.49209' },
      { name: 'Orlando, Florida, United States', coords: '28.53781, -81.38592' },
      { name: 'London, England', coords: '51.50420, -0.12426' },
      { name: 'Barcelona, Spain', coords: '41.40629, 2.17555' }
    ]
  }
]

const listbox = {
  displayField: 'name',
  data: (query) => fetch(`/api/cities?q=${encodeURIComponent(query)}`).then(res => res.json()),
  searchType: 'startswith'
}

const App = () => (
  <Turnstone
    listbox={listbox}
    defaultListbox={defaultListbox}
    defaultListboxIsImmutable={false}
    autoFocus={true}
    placeholder="Search cities..."
  />
)

export default App
```

--------------------------------

### Control Turnstone Programmatically via Refs

Source: https://context7.com/tomsouthall/turnstone/llms.txt

Demonstrates how to use React refs to access internal Turnstone methods like focus, blur, clear, and query. This is useful for building custom UI controls that interact with the search component.

```jsx
import React, { useRef } from 'react'
import Turnstone from 'turnstone'

const App = () => {
  const turnstoneRef = useRef()

  const listbox = {
    data: ['New York', 'Los Angeles', 'Chicago', 'Houston', 'Phoenix'],
    searchType: 'contains'
  }

  return (
    <div>
      <Turnstone
        ref={turnstoneRef}
        listbox={listbox}
        placeholder="Search cities..."
      />
      <div style={{ marginTop: '16px' }}>
        <button onClick={() => turnstoneRef.current?.focus()}>Focus</button>
        <button onClick={() => turnstoneRef.current?.blur()}>Blur</button>
        <button onClick={() => turnstoneRef.current?.clear()}>Clear</button>
        <button onClick={() => turnstoneRef.current?.query('New')}>Query "New"</button>
        <button onClick={() => turnstoneRef.current?.select()}>Select Text</button>
      </div>
    </div>
  )
}

export default App
```

--------------------------------

### Configure Grouped API Results

Source: https://context7.com/tomsouthall/turnstone/llms.txt

Shows how to fetch and display results from multiple API endpoints with weighted display ratios and custom selection handling.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const maxItems = 10

const listbox = [
  {
    id: 'cities',
    name: 'Cities',
    ratio: 8,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/cities?q=${encodeURIComponent(query)}&limit=${maxItems}`)
        .then(response => response.json()),
    searchType: 'startswith'
  },
  {
    id: 'airports',
    name: 'Airports',
    ratio: 2,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/airports?q=${encodeURIComponent(query)}&limit=${maxItems}`)
        .then(response => response.json()),
    searchType: 'contains'
  }
]

const App = () => {
  const handleSelect = (selectedItem, displayField) => {
    console.log('Selected:', selectedItem[displayField])
  }

  return (
    <Turnstone
      id="search"
      listbox={listbox}
      maxItems={maxItems}
      placeholder="Enter a city or airport"
      onSelect={handleSelect}
    />
  )
}

export default App
```

--------------------------------

### Apply Custom Styles with Tailwind CSS

Source: https://context7.com/tomsouthall/turnstone/llms.txt

Demonstrates how to customize the component's appearance using the styles prop with Tailwind CSS utility classes.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const styles = {
  input: 'w-full h-12 border border-slate-300 py-2 pl-10 pr-7 text-xl outline-none rounded',
  inputFocus: 'w-full h-12 border-x-0 border-t-0 border-b border-blue-300 py-2 pl-10 pr-7 text-xl outline-none sm:rounded sm:border',
  query: 'text-slate-800 placeholder-slate-400',
  typeahead: 'text-blue-300 border-white',
  cancelButton: 'absolute w-10 h-12 inset-y-0 left-0 items-center justify-center z-10 text-blue-400 inline-flex sm:hidden',
  clearButton: 'absolute inset-y-0 right-0 w-8 inline-flex items-center justify-center text-slate-400 hover:text-rose-400',
  listbox: 'w-full bg-white sm:border sm:border-blue-300 sm:rounded text-left sm:mt-2 p-2 sm:drop-shadow-xl',
  groupHeading: 'cursor-default mt-2 mb-0.5 px-1.5 uppercase text-sm text-rose-300',
  item: 'cursor-pointer p-1.5 text-lg overflow-ellipsis overflow-hidden text-slate-700',
  highlightedItem: 'cursor-pointer p-1.5 text-lg overflow-ellipsis overflow-hidden text-slate-700 rounded bg-blue-50',
  match: 'font-bold'
}

const listbox = {
  data: ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'],
  searchType: 'contains'
}

const App = () => (
  <Turnstone
    listbox={listbox}
    styles={styles}
    clearButton={true}
    cancelButton={true}
    typeahead={true}
    matchText={true}
    placeholder="Search fruits..."
  />
)

export default App
```

--------------------------------

### Extending Turnstone with Plugins

Source: https://context7.com/tomsouthall/turnstone/llms.txt

This snippet illustrates how to extend Turnstone's functionality using plugins, specifically the 'turnstone-recent-searches' plugin. It demonstrates how to integrate plugins to add features like storing and displaying recent search history.

```jsx
import React from 'react'
import Turnstone from 'turnstone'
import recentSearchesPlugin from 'turnstone-recent-searches'

const listbox = {
  displayField: 'name',
  data: (query) => fetch(`/api/cities?q=${query}`).then(res => res.json()),
  searchType: 'startswith'
}

const defaultListbox = [
  {
    name: 'Popular Cities',
    displayField: 'name',
    data: [
      { name: 'Paris, France' },
      { name: 'London, England' },
      { name: 'Tokyo, Japan' }
    ]
  }
]

const App = () => (
  <Turnstone
    listbox={listbox}
    defaultListbox={defaultListbox}
    maxItems={10}
    plugins={[
      [recentSearchesPlugin, {
        ratio: 2,
        name: 'Recent Searches',
        limit: 5
      }]
    ]}
    placeholder="Search cities..."
  />
)

export default App
```

--------------------------------

### Configure Listbox with Multiple Data Groups (JavaScript/JSX)

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

This snippet demonstrates how to configure the 'listbox' prop using an array of objects. Each object represents a group of search results, specifying its data source (as a function returning a Promise), display field, search type, ratio, and name. This allows for multiple, distinct groups of results to be displayed in the search listbox, drawing from different API endpoints.

```jsx
[ 
  {
    id: 'cities',
    name: 'Cities',
    ratio: 8,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/cities?q=${encodeURIComponent(query)}&limit=10`).then(res => res.json()),
    searchType: 'startswith'
  },
  {
    id: 'airports',
    name: 'Airports',
    ratio: 2,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/airports?q=${encodeURIComponent(query)}&limit=10`).then(res => res.json()),
    searchType: 'contains'
  }
]
```

--------------------------------

### Implement Custom Item Component

Source: https://context7.com/tomsouthall/turnstone/llms.txt

Shows how to create a custom Item component to render search results with specific styling, icons, and conditional formatting. This allows for rich visual representation of data within the Turnstone dropdown.

```jsx
import React from 'react'
import Turnstone from 'turnstone'

const CustomItem = (props) => {
  const { groupId, item, query } = props

  const highlightMatch = (text) => {
    if (!query) return text
    const regex = new RegExp(`(${query})`, 'gi')
    return text.split(regex).map((part, i) =>
      regex.test(part) ? <strong key={i}>{part}</strong> : part
    )
  }

  return (
    <div style={{ display: 'flex', alignItems: 'center', padding: '8px' }}>
      <span style={{ marginRight: '8px' }}>
        {groupId === 'cities' ? '🏙️' : '✈️'}
      </span>
      <div>
        <div>{highlightMatch(item.name)}</div>
        {item.country && (
          <div style={{ fontSize: '12px', color: '#666' }}>{item.country}</div>
        )}
      </div>
    </div>
  )
}

const listbox = [
  {
    id: 'cities',
    name: 'Cities',
    ratio: 7,
    displayField: 'name',
    data: (query) => fetch(`/api/cities?q=${query}`).then(res => res.json()),
    searchType: 'startswith'
  },
  {
    id: 'airports',
    name: 'Airports',
    ratio: 3,
    displayField: 'name',
    data: (query) => fetch(`/api/airports?q=${query}`).then(res => res.json()),
    searchType: 'contains'
  }
]

const App = () => (
  <Turnstone
    listbox={listbox}
    maxItems={10}
    Item={CustomItem}
    matchText={false}
    placeholder="Search locations..."
  />
)

export default App
```

--------------------------------

### Handling User Events in Turnstone

Source: https://context7.com/tomsouthall/turnstone/llms.txt

This snippet demonstrates how to handle various user interaction events in Turnstone, such as select, change, enter, tab, focus, and blur. It logs these events to the console, allowing developers to react to user input and selections.

```jsx
import React, { useState, useCallback } from 'react'
import Turnstone from 'turnstone'

const App = () => {
  const [events, setEvents] = useState([])

  const logEvent = (name, data) => {
    setEvents(prev => [...prev, { name, data, time: new Date().toISOString() }])
  }

  const listbox = {
    displayField: 'name',
    data: (query) => fetch(`/api/cities?q=${query}`).then(res => res.json()),
    searchType: 'startswith'
  }

  const onSelect = useCallback((item, displayField) => {
    logEvent('onSelect', item ? item[displayField] : null)
  }, [])

  const onChange = useCallback((query) => {
    logEvent('onChange', query)
  }, [])

  const onEnter = useCallback((query, selectedItem) => {
    logEvent('onEnter', { query, selected: selectedItem?.name })
  }, [])

  const onTab = useCallback((query, selectedItem) => {
    logEvent('onTab', { query, selected: selectedItem?.name })
  }, [])

  const onFocus = useCallback(() => {
    logEvent('onFocus', null)
  }, [])

  const onBlur = useCallback(() => {
    logEvent('onBlur', null)
  }, [])

  return (
    <div>
      <Turnstone
        listbox={listbox}
        onSelect={onSelect}
        onChange={onChange}
        onEnter={onEnter}
        onTab={onTab}
        onFocus={onFocus}
        onBlur={onBlur}
        placeholder="Search and watch events..."
      />
      <div style={{ marginTop: '16px' }}>
        <h4>Events:</h4>
        <ul>
          {events.slice(-5).map((e, i) => (
            <li key={i}>{e.name}: {JSON.stringify(e.data)}</li>
          ))}
        </ul>
      </div>
    </div>
  )
}

export default App
```

--------------------------------

### Turnstone Component Methods API

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

This section lists and describes the available methods for the Turnstone component. These methods allow for programmatic control over the component's state and behavior, such as managing focus, clearing input, and performing searches.

```javascript
blur(): Removes keyboard focus from the search box.
clear(): Clears the contents of the search box.
focus(): Sets keyboard focus on the search box.
query(<string>): Sets the search box contents to the string argument supplied to the function.
select(): Selects the contents of the search box.
```

--------------------------------

### Configure Default Listbox with Object Data

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Sets up the default listbox with a single, ungrouped list of items. This configuration is suitable when you have a flat data structure or a single source for your default suggestions. The data is typically fetched from an API endpoint.

```jsx
{ displayField: 'name', data: () => fetch(`/api/cities/popular`).then(res => res.json()) }
```

--------------------------------

### Listbox Behavior Props

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Configuration options that control the behavior and appearance of the listbox.

```APIDOC
## Listbox Behavior Properties

### Description
These properties allow fine-grained control over the listbox's behavior, including immutability, text matching, item limits, and event handling.

### Method
Configuration Props

### Endpoint
N/A

### Parameters
#### Query Parameters
- **`listboxIsImmutable`** (boolean) - Optional - Default: `true` - If `true`, listbox contents never change between queries. Set to `false` if results can vary for the same query.
- **`matchText`** (boolean) - Optional - Default: `false` - If `true`, matching text in list items is wrapped in `<strong>` tags. Behavior depends on `searchType`.
- **`maxItems`** (number) - Optional - Default: `10` - Maximum number of items to display in the listbox. Applies to total items across all groups.
- **`minQueryLength`** (number) - Optional - Default: `1` - Minimum characters required in the search box before results are fetched. Must be greater than 0.
- **`name`** (string) - Optional - Default: `undefined` - The HTML `name` attribute for the search box.
- **`noItemsMessage`** (string) - Optional - Default: `undefined` - Message displayed when no items match the query. If not provided, the listbox is hidden.

#### Event Handlers
- **`onBlur`** (function) - Optional - Default: `undefined` - Callback executed when the search box loses focus. No arguments.
- **`onChange`** (function) - Optional - Default: `undefined` - Callback executed when the search box value changes. Receives `query` (string) as an argument.
- **`onEnter`** (function) - Optional - Default: `undefined` - Callback executed when the Enter key is pressed in the search box. Receives `query` (string) and `selectedItem` as arguments.
- **`onFocus`** (function) - Optional - Default: `undefined` - Callback executed when the search box gains focus. No arguments.

### Request Example
```javascript
{
  listboxIsImmutable: false,
  matchText: true,
  maxItems: 15,
  minQueryLength: 2,
  name: "citySearch",
  noItemsMessage: "No cities found.",
  onBlur: () => console.log('Blurred'),
  onChange: (query) => console.log(`Query changed: ${query}`),
  onEnter: (query, selectedItem) => console.log(`Entered: ${query}, Selected: ${selectedItem}`),
  onFocus: () => console.log('Focused')
}
```

### Response
#### Success Response (200)
N/A (These are configuration props, not an API endpoint response)

#### Response Example
N/A
```

--------------------------------

### Configure Dynamic Grouped Listbox Data Source

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Uses a function to dynamically build grouped listbox contents. This is useful for complex data sources like GraphQL where results are returned in categories.

```jsx
(query) => fetch(`/api/locations?q=${encodeURIComponent(query)}`)
  .then(res => res.json())
  .then(locations => {
    const {cities, airports} = locations

    return [
      {
        id: 'cities',
        name: 'Cities',
        ratio: 8,
        displayField: 'name',
        data: cities,
        searchType: 'startswith'
      },
      {
        id: 'airports',
        name: 'Airports',
        ratio: 2,
        displayField: 'name',
        data: airports,
        searchType: 'contains'
      }
    ]
  })
```

--------------------------------

### Custom Renderable Components

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Details on how to provide custom React components for rendering elements within the Turnstone component, such as cancel buttons, clear buttons, list items, and group names.

```APIDOC
## Custom Components

The following custom components can also be supplied as props:

### `Cancel`

- Type: React component
- Default: `() => 'Cancel'`
- This component is rendered within the cancel `<button>` element. It receives no props.

### `Clear`

- Type: React component
- Default: `() => '\u00d7'`
- This component is rendered within the clear `<button>` element. It receives no props.

### `Item`

- Type: React component
- Default: `undefined`
- If supplied, this component is rendered within the listbox item `<div>` element.
- The `Item` component gives you huge flexibility to format and style listbox items however you like. They can be as rich as required, containing images, icons, multiple fields, etc.
- The `Item` component receives the following props when rendered:
  - **`appearsInDefaultListbox`** (boolean) If `true` indicates that the item appears in the default listbox rather than the listbox. This allows default listbox items to be styled completely differently to listbox items if required.
  - **`groupId`** (string) The `id` of the group supplied in the `listbox` or `defaultListbox` prop.
  - **`groupIndex`** (number) The index of the group. Matches the order supplied in the `listbox` or `defaultListbox` prop. Zero-indexed.
  - **`groupName`** (string) The `name` of the group supplied in the `listbox` or `defaultListbox` prop.
  - **`index`** (number) The index of the item within the listbox. Zero-indexed. This allows you to style, say, the first item differently to all the rest in the listbox.
  - **`isHighlighted`** (boolean) If `true` indicates that the item is currently in a highlighted state
  - **`item`** The item in the same format as supplied by the `listbox` or `defaultListbox` prop.
  - **`query`** The text currently entered in the search box. This can be used to show matched text in the item.
  - **`searchType`** (string) Either `"startswith"` or `"contains"`. Indicates how the item was matched to the query.
  - **`setSelected`** (function) If executed, sets the selected item to whatever is passed to the function. This allows sub-items to be displayed within an item. For example, you may wish to provide selectable neighbourhoods or attractions within a city item. The function receives two arguments:
    1. `value` (object / array / string) The value of the item to select
    1. `displayField` (string / number / undefined) The key or index of the field inside `value` that represents the text to display in the search box once selected. If the `value` argument is a string, this must be set to `undefined`.
  - **`totalItems`** The total number of items currently displayed inside the listbox.

### `GroupName`

- Type: React component
- Default: `undefined`
- If supplied, this component is rendered within the group heading `<div>` element.
- By default the group name is simply a text string. This component allows you to supply custom styling, for example adding an icon.
- The `GroupName` component receives the following props when rendered:
  - **`children`** (string) The `name` of the group supplied in the `listbox` or `defaultListbox` prop.
  - **`id`** (string) The `id` of the group supplied in the `listbox` or `defaultListbox` prop.
  - **`index`** (number) The index of the group. Matches the order supplied in the `listbox` or `defaultListbox` prop. Zero-indexed.
```

--------------------------------

### Configure Default Listbox with Dynamic Function

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Allows for dynamic generation of default listbox content using a function. This function receives a query and must return a promise that resolves to an array of group objects, similar to the array data structure. This is ideal for complex data sources or when results need to be structured on the fly.

```jsx
(query) => fetch(`/api/default-locations`).then(res => res.json()).then(locations => { const {recentSearches, popularCities} = locations; return [ { name: 'Recent Searches', displayField: 'name', data: recentSearches, id: 'recent', ratio: 1 }, { name: 'Popular Cities', displayField: 'name', data: popularCities, id: 'popular', ratio: 1 } ] })
```

--------------------------------

### Turnstone Component Props

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Configuration options for the Turnstone component, including item highlighting, matching text display, and search behavior.

```APIDOC
## Component Props

### `highlightedItem`

Note that `item` and `highlightedItem` are mutually exclusive. An item `<div>` has the `highlightedItem` styling applied when it is highlighted either via a `mouseover` event or via use of the up and down arrow keys.

### `match`

The `<strong>` element that wraps any item text that matches the text entered into the search box. A common approach is to invert the styling so that the matched text is at a normal font weight and the remaining text is displayed in bold.

### `tabIndex`

- Type: `number`
- Default: `undefined`
- The HTML `tabindex` attribute applied to the search box.

### `text`

- Type: `string`
- Default: `undefined`
- Text appearing in the search box when first rendered
- Will cause `onSelect` to fire automatically if there is a matching result

### `typeahead`

- Type: `string`
- Default: `true`
- If `true` shows typeahead text as the user enters text into the search box. This matches the currently highlighted item in the listbox, so long as the item starts with the search box text.
```

--------------------------------

### Turnstone Component Props

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

This section details the available props for the Turnstone component, explaining their types, default values, and functionality.

```APIDOC
## Turnstone Component Props

### `autoFocus`
- Type: `boolean`
- Default: `false`
- If `true` the search input automatically receives focus
- Note: If `defaultListbox` prop is supplied, setting `autoFocus` to true causes the default listbox to be automatically opened.

### `cancelButton`
- Type: `boolean`
- Default: `false`
- If `true` a cancel button is rendered. The cancel button is displayed only when the search box receives focus. It is particularly useful for mobile screen sizes where a "back" button is required
in order to exit the focused state of the search box.

### `cancelButtonAriaLabel`
- Type: `string`
- Default: `"Cancel"`
- The value of the `aria-label` attribute on the cancel button element.

### `clearButton`
- Type: `boolean`
- Default: `false`
- If `true` a clear button is rendered whenever the user has entered at least one character into the search box.
- Clicking the clear button has the same effect as pressing the Esc key while entering text into the search box. The contents of the searchbox are cleared and focus is retained.
- Suggested styling for the clear button is to position it absolutely overlaying the right of the search box, for example:
  ```css
  .clearButton {
    display: block;
    width: 2rem;
    right: 0px;
    top: 0px;
    bottom: 0px;
    position: absolute;
    color: #a8a8a8;
    cursor: pointer;
    border: none;
    background: transparent;
    padding:0;
  }
  ```

### `clearButtonAriaLabel`
- Type: `string`
- Default: `"Clear contents"`
- The value of the `aria-label` attribute on the clear button element.

### `debounceWait`
- Type: `number`
- Default: `250`
- The wait time in milliseconds after the user finishes typing before the search query is sent to the fetch function.
- This reduces the number of API calls made by the fetch function
- Set to `0` if you want no wait at all (e.g. if your listbox data is not fetched asynchronously)
```

--------------------------------

### Configure Default Listbox with Array Data

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Defines the default listbox content using an array of objects, where each object represents a group of items. This is useful for displaying multiple categorized lists, such as recent searches and popular locations. Data can be provided directly or fetched asynchronously.

```jsx
[{ name: 'Recent Searches', displayField: 'name', data: () => Promise.resolve(JSON.parse(localStorage.getItem('recent')) || []), id: 'recent', ratio: 1 }, { name: 'Popular Cities', displayField: 'name', data: [ { name: 'Paris, France', coords: '48.86425, 2.29416' }, { name: 'Rome, Italy', coords: '41.89205, 12.49209' }, { name: 'Orlando, Florida, United States', coords: '28.53781, -81.38592' }, { name: 'London, England', coords: '51.50420, -0.12426' }, { name: 'Barcelona, Spain', coords: '41.40629, 2.17555' }, { name: 'New Orleans, Louisiana, United States', coords: '29.95465,-90.07507' }, { name: 'Chicago, Illinois, United States', coords: '41.85003,-87.65005' }, { name: 'Manchester, England', coords: '53.48095,-2.23743' } ], id: 'popular', ratio: 1 }]
```

--------------------------------

### Styled Turnstone with Grouped API Results in React

Source: https://github.com/tomsouthall/turnstone/blob/main/README.md

Illustrates a styled Turnstone component fetching and displaying grouped search results from two different API sources (cities and airports). It includes configuration for debouncing, maximum items, and custom styling.

```jsx
import React, { useState } from 'react'
import Turnstone from 'turnstone'

const styles = {
  input,
  inputFocus,
  query,
  typeahead,
  cancelButton,
  clearButton,
  listbox,
  groupHeading,
  item,
  highlightedItem
}

const maxItems = 10

const listbox = [
  {
    id: 'cities',
    name: 'Cities',
    ratio: 8,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/cities?q=${encodeURIComponent(query)}&limit=${maxItems}`)
        .then(response => response.json()),
    searchType: 'startswith'
  },
  {
    id: 'airports',
    name: 'Airports',
    ratio: 2,
    displayField: 'name',
    data: (query) =>
      fetch(`/api/airports?q=${encodeURIComponent(query)}&limit=${maxItems}`)
        .then(response => response.json()),
    searchType: 'contains'
  }
]

export default function Example() {
  return (
    <Turnstone
      cancelButton={true}
      debounceWait={250}
      id="search"
      listbox={listbox}
      listboxIsImmutable={true}
      matchText={true}
      maxItems={maxItems}
      name="search"
      noItemsMessage="We found no places that match your search"
      placeholder="Enter a city or airport"
      styles={styles}
      typeahead={true}
    />
  )
}
```