# @cloud-ru/ds-ai-chain-of-thoughts

> Цепочка рассуждений AI-агента (Chain of Thoughts) — сворачиваемый заголовок «Размышляю» с длительностью и список строк-инструментов.

Docs: /snack-v2/components/ai-chain-of-thoughts/

## Установка

```sh
pnpm add @cloud-ru/ds-ai-chain-of-thoughts
```

## Когда использовать

- Показ процесса рассуждения агента в чате: заголовок со статусом и список выполненных шагов-инструментов.
- Потоковое отображение размышлений (стриминг) — заголовок остаётся, контент дополняется по мере поступления шагов.

### Когда не нужен

- Одиночный шаг reasoning без заголовка-цепочки:
  - используйте `@cloud-ru/ds-ai-reasoning`.
- Отдельный вызов инструмента вне цепочки:
  - используйте `AiTool` / `AiToolSimple` из `@cloud-ru/ds-ai-tool`.

## API

### AiChainOfThoughts
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `broken` | `boolean` | `false` | no | Поток рассуждения прерван. Заголовок показывает сообщение `brokenMessage`, контент-цепочка не раскрывается. По умолчанию `false`. |
| `brokenMessage` | `ReactNode` | — | no | Текст сообщения о прерванном потоке (показывается при `broken`). |
| `children` | `ReactNode` | — | no | Контент-цепочка рассуждения — строки `AiTool` / `AiToolSimple`. Рендерится под заголовком в раскрытом состоянии. |
| `className` | `string` | — | no | Доп. класс корня. |
| `data-test-id` | `string` | `ai-chain-of-thoughts` | no |  |
| `defaultOpened` | `boolean` | `false` | no | Начальное раскрытое состояние (uncontrolled). По умолчанию `false`. |
| `duration` | `number` | — | no | Длительность рассуждения в секундах. Форматируется в д/ч/м/с. Скрыта в состоянии `broken`. |
| `inProgress` | `boolean` | `true` | no | Идёт ли рассуждение прямо сейчас. `true` — иконка GigaChat и подпись «Размышляю»; `false` — без иконки и «Размышлял». По умолчанию `true`. |
| `label` | `ReactNode` | — | no | Подпись заголовка. По умолчанию «Размышляю» / «Размышлял» — по `inProgress`. |
| `onToggle` | `((opened: boolean) => void)` | — | no | Переключение раскрытия. Получает новое значение `opened`. |
| `opened` | `boolean` | — | no | Раскрытое состояние (controlled). Для uncontrolled-режима — `defaultOpened`. |

### AiChainOfThoughtsHeadline
| Prop | Type | Default | Required | Description |
|------|------|---------|----------|-------------|
| `broken` | `boolean` | `false` | no | Поток рассуждения прерван. Вместо длительности и chevron'а под подписью показывается сообщение `brokenMessage`. По умолчанию `false`. |
| `brokenMessage` | `ReactNode` | — | no | Текст сообщения о прерванном потоке (показывается при `broken`). |
| `className` | `string` | — | no | Доп. класс корня. |
| `collapsible` | `boolean` | `false` | no | Рендерить ли chevron-кнопку раскрытия. Управляется родителем (`AiChainOfThoughts` ставит `true`, когда есть раскрываемый контент). В состоянии `broken` chevron не рендерится. По умолчанию `false`. |
| `data-test-id` | `string` | `ai-chain-of-thoughts-headline` | no |  |
| `duration` | `number` | — | no | Длительность рассуждения в секундах. Форматируется в д/ч/м/с (ведущие нулевые единицы опускаются, секунды показываются всегда). Скрыта в состоянии `broken`. |
| `inProgress` | `boolean` | `true` | no | Идёт ли рассуждение прямо сейчас. `true` — слева иконка GigaChat и подпись «Размышляю» (настоящее время); `false` — без иконки и «Размышлял» (прошедшее время). По умолчанию `true`. |
| `label` | `ReactNode` | — | no | Подпись заголовка. По умолчанию «Размышляю» / «Размышлял» — по `inProgress`. |
| `onToggle` | `((opened: boolean) => void)` | — | no | Клик по chevron'у. Получает новое значение `opened`. |
| `opened` | `boolean` | `false` | no | Раскрытое состояние — задаёт направление chevron'а. По умолчанию `false`. |

## Примеры

### Broken

```tsx
import { AiChainOfThoughts } from '@cloud-ru/ds-ai-chain-of-thoughts';

export function Broken() {
  return <AiChainOfThoughts broken />;
}
```

### Default

```tsx
import { AiChainOfThoughts } from '@cloud-ru/ds-ai-chain-of-thoughts';
import { AI_TOOL_ICON_TYPE, AI_TOOL_STATUS_STATE, AiTool, AiToolSimple } from '@cloud-ru/ds-ai-tool';

export function Default() {
  return (
    <AiChainOfThoughts inProgress duration={31568949} defaultOpened>
      <AiToolSimple name='status_for_users' icon={AI_TOOL_ICON_TYPE.Search} connector />
      <AiTool
        name='status_for_users'
        icon={AI_TOOL_ICON_TYPE.Search}
        state={AI_TOOL_STATUS_STATE.Success}
        duration={9}
        call='{ "user_ids": [1, 2, 3] }'
      />
    </AiChainOfThoughts>
  );
}
```

### HeadlineStates

```tsx
import { AiChainOfThoughtsHeadline } from '@cloud-ru/ds-ai-chain-of-thoughts';

export function HeadlineStates() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column', gap: 12 }}>
      <AiChainOfThoughtsHeadline inProgress duration={31568949} />
      <AiChainOfThoughtsHeadline inProgress={false} duration={31568949} />
    </div>
  );
}
```