# Composants de recherche

Là où les tables déclarent _ce qui_ est cherchable et où les moteurs déclarent _comment_ une requête s'exécute (voir [search-overview](/fr/docs/search-overview)), les composants sont l'_endroit_ où la recherche apparaît sur la page. Sovrium fournit cinq pièces complémentaires : un `searchInput` qui pilote une requête, une `list` qui affiche les résultats, un `pageSearch` qui indexe le contenu des pages statiques, une palette `command` pour la navigation au clavier, et la recherche de barre d'outils intégrée aux composants de données.

| Composant                   | Objectif                                                                                              |
| --------------------------- | ----------------------------------------------------------------------------------------------------- |
| `searchInput`               | Champ de recherche autonome qui pilote un autre composant via `dataSource.bindTo`.                    |
| `list`                      | Affichage de résultats orienté recherche avec modèles d'élément, surlignage et pagination.            |
| `pageSearch`                | Recherche statique à l'échelle du site sur le contenu des pages publiques (index au build/démarrage). |
| `command`                   | Palette de commandes (style ⌘K) pour des actions groupées et pilotées au clavier.                     |
| recherche de barre d'outils | Barre de recherche intégrée au composant sur `data-table`, kanban, calendrier, etc.                   |

## `searchInput`

Un champ de recherche autonome. Seul, il affiche une saisie accessible ; lié à une source de données, il devient le pilote de requête pour un composant frère. Associez-le à une `list` (ou `data-table`) dont la source de données définit `bindTo` sur l'`id` de la saisie.

| Propriété    | Description                                                                |
| ------------ | -------------------------------------------------------------------------- |
| `id`         | Identifiant que les autres composants référencent via `dataSource.bindTo`. |
| `visibility` | Contrôles de visibilité standard (partagés entre composants).              |
| `i18n`       | Champs d'internationalisation standard (libellé/placeholder traduisibles). |

```yaml
components:
  # 1. The input drives the query
  - type: searchInput
    id: product-query

  # 2. The list consumes it via bindTo
  - type: list
    dataSource:
      table: products
      mode: search
      searchFields: [name, description]
      searchEngine: hybrid
      debounceMs: 300
      bindTo: product-query
    listDisplay:
      itemTemplate:
        title: '$record.name'
        subtitle: '$record.description'
      highlight: true
```

:::callout
`debounceMs` réside sur la **source de données** du composant consommateur, pas sur `searchInput` — la saisie émet les frappes et la source de données liée les anti-rebondit avant d'interroger. Voir [search-overview](/fr/docs/search-overview#the-search-data-source-mode).
:::

## `list` — affichage de résultats

Le composant `list` est conçu comme un affichage orienté recherche : le compagnon naturel de `searchInput`. Il affiche chaque enregistrement via un modèle d'élément avec surlignage optionnel, séparateurs et pagination « charger plus ».

| Propriété               | Description                                                                                                                    |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `itemTemplate.title`    | Texte principal via une référence `$record.*` (par ex. `$record.name`).                                                        |
| `itemTemplate.subtitle` | Texte secondaire (par ex. `$record.description`).                                                                              |
| `itemTemplate.image`    | URL d'image (par ex. `$record.thumbnail`).                                                                                     |
| `itemTemplate.badge`    | Texte de badge (par ex. `$record.category`).                                                                                   |
| `itemTemplate.metadata` | Tableau de `{ field, format }` affiché dans le pied de l'élément (`currency`, `relative-date`, `badge`, `text`, `short-date`). |
| `emptyMessage`          | Message affiché lorsqu'aucun résultat ne correspond.                                                                           |
| `loadMore`              | `button` (bouton Charger plus) ou `infinite` (charger au défilement).                                                          |
| `highlight`             | Booléen. Surligne les termes de recherche correspondants dans le texte de l'élément (par défaut `false`).                      |
| `divider`               | Booléen. Affiche des séparateurs visuels entre les éléments (par défaut `false`).                                              |
| `maxItems`              | Nombre maximal d'éléments à afficher (entier ≥ 1).                                                                             |

```yaml
- type: list
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    bindTo: product-query
  listDisplay:
    itemTemplate:
      title: '$record.name'
      subtitle: '$record.description'
      image: '$record.thumbnail'
      badge: '$record.category'
      metadata:
        - field: price
          format: currency
    emptyMessage: No products found
    loadMore: infinite
    highlight: true
    divider: true
    maxItems: 50
```

## `pageSearch` — index de pages statiques

Un composant de recherche à l'échelle du site qui indexe les **pages publiques** (`access` absent ou `access: 'all'`) au moment de `sovrium build` et au démarrage de `sovrium start`. L'index est un fichier JSON plus un minuscule runtime client sous `<outputDir>/sovrium-search/`, servi par la route de répertoire public. C'est une couche différente de la recherche d'enregistrements — il recherche le _contenu_ des pages, pas les lignes de table.

| Propriété     | Description                                              |
| ------------- | -------------------------------------------------------- |
| `placeholder` | Texte indicatif affiché dans la saisie de recherche.     |
| `maxResults`  | Nombre maximal de résultats à afficher (entier positif). |
| `visibility`  | Contrôles de visibilité standard.                        |
| `i18n`        | Champs d'internationalisation standard.                  |

```yaml
pages:
  - id: home
    name: home
    path: /
    components:
      - type: pageSearch
        placeholder: Search the site...
        maxResults: 10
```

:::callout
`pageSearch` est **auto-activant** : dès qu'un composant `type: 'pageSearch'` apparaît n'importe où dans `app.pages[].components[]`, `sovrium build` et `sovrium start` émettent l'index de recherche statique. Pas de variable d'environnement, pas de configuration `app.search` de premier niveau. L'indexeur n'explore que les pages publiques — les pages avec `access: 'authenticated'`, des tableaux de rôles, ou un accès basé sur `require` sont exclues de l'index.
:::

## `command` — palette de commandes

Une palette de commandes de style ⌘K pour la navigation et les actions pilotées au clavier. Les commandes sont organisées en groupes, chacun faisant surgir des entrées cherchables que l'utilisateur filtre en tapant.

| Propriété       | Description                                                    |
| --------------- | -------------------------------------------------------------- |
| `commandGroups` | Tableau (≥ 1) de commandes groupées affichées dans la palette. |
| `visibility`    | Contrôles de visibilité standard.                              |
| `i18n`          | Champs d'internationalisation standard.                        |

```yaml
- type: command
  commandGroups:
    - heading: Navigation
      commands:
        - label: Go to Dashboard
          href: /dashboard
        - label: Go to Settings
          href: /settings
    - heading: Actions
      commands:
        - label: New Product
          href: /products/new
```

## Recherche de barre d'outils

Les composants de données exposent une barre de recherche intégrée au composant via leur barre d'outils. Sur un `data-table`, définissez `toolbar.search: true` pour afficher une saisie de recherche globale sur les lignes liées — un filtre rapide sans `searchInput` distinct.

| Indicateur de barre d'outils | Description                             |
| ---------------------------- | --------------------------------------- |
| `search`                     | Affiche la saisie de recherche globale. |
| `filters`                    | Affiche le constructeur de filtres.     |
| `sort`                       | Affiche le constructeur de tri.         |

```yaml
- type: data-table
  dataSource:
    table: orders
    mode: search
    searchFields: [customer, reference]
  toolbar:
    search: true
    filters: true
    sort: true
```

Les composants kanban et calendrier partagent une configuration `search` pour leur propre barre de recherche intégrée via le même modèle.

## Surlignage et anti-rebond

- **Surlignage** — définissez `highlight: true` sur `list` (`listDisplay.highlight`) pour entourer les termes correspondants dans le texte des résultats. Désactivé par défaut.
- **Anti-rebond** — définissez `debounceMs` sur la source de données (par ex. `300`) afin que la requête ne se déclenche qu'après une pause de saisie de l'utilisateur, évitant une requête par frappe.

Ces fonctionnalités fonctionnent ensemble : un `searchInput` émet des frappes, la source de données liée anti-rebondit et interroge, et la `list` surligne les correspondances dans les résultats affichés.

## Associé

- [Présentation de la recherche](/fr/docs/search-overview) — les moteurs et le mode de source de données `search`.
- [Recherche plein texte](/fr/docs/full-text-search) — `indexed`, `searchWeight` et `fullTextSearch` au niveau du champ.
- [Composants de données](/fr/docs/data-components) — `data-table`, kanban, calendrier et leurs barres d'outils.
- [Composants de contenu](/fr/docs/content-components) — texte, média et contenu de page structurel.
- [Enregistrements : filtrage et tri](/fr/docs/records-filtering-sorting) — filtrage et ordonnancement de listes hors recherche.