# Suggestions

A Suggestions component displays a group of clickable suggestion buttons arranged in either horizontal (grid) or vertical (list) layout.

## Features

- **Flexible layout**: Display suggestions in grid (horizontal) or list (vertical) layout
- **Item support**: Each suggestion can have an optional ID, optional `data` payload, and required title
- **Optional title**: Display a section title above suggestions
- **Click handling**: Callback receives `title`, optional `id`, and optional `data`
- **Text alignment**: Control text alignment inside buttons (left, center, right)
- **Icon support**: Add ChevronLeft or ChevronRight icons to suggestion buttons
- **Tooltips**: Automatic tooltips displaying the suggestion title on hover (disabled when `wrapText` is enabled)

## Usage

```tsx
import {Suggestions} from '@/components/molecules/Suggestions';

// With list layout (vertical)
<Suggestions
  items={[
    {id: '1', title: 'First suggestion'},
    {id: '2', title: 'Second suggestion'},
  ]}
  onClick={(content, id) => {
    console.log('Clicked:', content, id);
  }}
  layout="list"
/>

// With grid layout (horizontal)
<Suggestions
  items={[
    {id: '1', title: 'Option 1'},
    {id: '2', title: 'Option 2'},
  ]}
  onClick={(content, id) => {
    console.log('Clicked:', content, id);
  }}
  layout="grid"
/>

// With text alignment
<Suggestions
  items={[
    {id: '1', title: 'Centered text'},
    {id: '2', title: 'Another centered suggestion'},
  ]}
  textAlign="center"
  onClick={(content, id) => {
    console.log('Clicked:', content, id);
  }}
/>

// Without IDs
<Suggestions
  items={[
    {title: 'First item'},
    {title: 'Second item'},
  ]}
  onClick={(content) => {
    console.log('Clicked:', content);
  }}
/>

// With icons
<Suggestions
  items={[
    {id: '1', title: 'Previous page', icon: 'left'},
    {id: '2', title: 'Next page', icon: 'right'},
  ]}
  onClick={(content, id) => {
    console.log('Clicked:', content, id);
  }}
/>

// Mixed icons and no icons
<Suggestions
  items={[
    {id: '1', title: 'Back', icon: 'left'},
    {id: '2', title: 'Home'},
    {id: '3', title: 'Forward', icon: 'right'},
  ]}
  layout="grid"
  onClick={(content, id) => {
    console.log('Clicked:', content, id);
  }}
/>

// With text wrapping enabled
<Suggestions
  items={[
    {id: '1', title: 'This is a very long suggestion text that will wrap to multiple lines'},
    {id: '2', title: 'Another long text that demonstrates text wrapping behavior'},
  ]}
  wrapText={true}
  onClick={(content, id) => {
    console.log('Clicked:', content, id);
  }}
/>

// With section title
<Suggestions
  title="Try asking about:"
  items={[
    {id: '1', title: 'What is AI?'},
    {id: '2', title: 'How does machine learning work?'},
  ]}
  onClick={(content, id) => {
    console.log('Clicked:', content, id);
  }}
/>
```

## Props

| Prop        | Type                            | Required | Default                        | Description                                                                                                            |
| ----------- | ------------------------------- | -------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| `items`     | `SuggestionsItem[]`             | Yes      | -                              | Array of suggestion items to display                                                                                   |
| `onClick`   | `SuggestionClickHandler`        | Yes      | -                              | Callback function called when a suggestion is clicked                                                                  |
| `title`     | `string`                        | No       | -                              | Title to display above suggestions                                                                                     |
| `layout`    | `'grid' \| 'list'`              | No       | `'list'`                       | Layout orientation: 'grid' for horizontal, 'list' for vertical                                                         |
| `textAlign` | `'left' \| 'center' \| 'right'` | No       | `'left'`                       | Text alignment inside buttons; applies only when the item has no icon. A non-default value disables the mobile chevron |
| `size`      | `ButtonButtonProps['size']`     | No       | `'m'` desktop, `'xl'` mobile   | Size of suggestion buttons; an explicit value also opts out of the rest of the mobile appearance                       |
| `wrapText`  | `boolean`                       | No       | `false` desktop, `true` mobile | Wrap text inside buttons instead of truncating with ellipsis; also disables the per-item tooltip                       |
| `className` | `string`                        | No       | -                              | Additional CSS class                                                                                                   |
| `qa`        | `string`                        | No       | -                              | QA/test identifier                                                                                                     |

On mobile (`useMobile()` from uikit) each item shows a right chevron unless `icon: 'none'` is set.

Mobile mode changes the size, the `normal` view, text wrapping, `body-2` typography and the
chevron as one package. Passing an explicit `size` turns the whole package off and keeps only
the size you asked for, so a consumer can fall back to the desktop appearance with a single prop.

### SuggestionsItem

| Prop      | Type                          | Required | Default                                 | Description                                                                                              |
| --------- | ----------------------------- | -------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `id`      | `string`                      | No       | -                                       | Optional unique identifier for the item                                                                  |
| `title`   | `string`                      | Yes      | -                                       | Title text to display on the button                                                                      |
| `data`    | `Record<string, unknown>`     | No       | -                                       | Optional custom payload passed through to click handlers                                                 |
| `view`    | `ButtonButtonProps['view']`   | No       | `'outlined'` desktop, `'normal'` mobile | Button view style                                                                                        |
| `icon`    | `'left' \| 'right' \| 'none'` | No       | `'right'` on mobile                     | Icon position: 'left' for ChevronLeft, 'right' for ChevronRight, 'none' to opt out of the mobile chevron |
| `onClick` | `SuggestionClickHandler`      | No       | -                                       | Additional callback invoked before the component-level `onClick` callback                                |

## Styling

The component uses CSS variables for theming and integrates with ButtonGroup for layout management.

### CSS Variables

```css
--g-spacing-2 /* Gap size between suggestion buttons and title spacing */
--g-border-radius-l /* Border radius for buttons on hover */
--g-aikit-suggestions-box-shadow /* Box shadow for buttons on hover */
```

### Container

The component uses a flex container with configurable orientation based on the `layout` prop.

### Button styling

Buttons have hover effects with shadow and border radius transitions.

### SuggestionClickHandler

```tsx
type SuggestionClickHandler = (
  content: string,
  id?: string,
  data?: Record<string, unknown>,
) => void | Promise<void>;
```

The handler receives the suggestion `title` as `content`, the optional `id`, and the optional `data` payload from `SuggestionsItem`.