AiFieldInput

AiFieldInput — поле ввода сообщения в чате с агентом и в любом разговоре, которому нужны вложения и ряд действий. Поле принимает текст с чипами скиллов, команд и упоминаний, показывает приложенные файлы и собирает действия перед отправкой. Что произойдёт после отправки, решает потребитель.

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

  • Ввод сообщения в чате с агентом.
  • Ввод ответа в разговоре, где нужны вложения, вызов скиллов по / и упоминания по @.

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

  • Однострочный ввод без вложений и действий:
    • используйте FieldText из @cloud-ru/ds-fields.
  • Многострочный текст без чипов и футера:
    • используйте FieldTextArea из @cloud-ru/ds-fields.

Анатомия

Поле собрано сверху вниз из четырёх частей, в состоянии ошибки — из пяти:

  • кнопка прокрутки к последнему сообщению (scrollButton) — над полем, с точкой непрочитанного;
  • слот баннера (banner) — AiFieldBanner или AiFieldNotice; пока открыт список по / или @, баннер скрыт, но держит своё место; на мобильной раскладке баннер берёт размер m из своего пресета адаптивности;
  • рамка поля — ряд вложений (attachments, плитки AiAttachment из @cloud-ru/ds-ai-attachment), текстовая область и футер;
  • строка ошибки (error) — только в состоянии ошибки, между рамкой и дисклеймером;
  • дисклеймер (disclaimer) — текст под рамкой.

Футер состоит из двух слотов (footerLeftActions, footerRightActions) и кнопки отправки, которая стоит справа всегда. Кнопки футера экспортируются отдельно: AiFieldInputPlusButton, AiFieldInputSettingsButton, AiFieldInputModelButton, AiFieldInputEffortButton, AiFieldInputContextButton, AiFieldInputVoiceButton, AiFieldInputSendButton. У AiFieldInputPlusButton, AiFieldInputSettingsButton, AiFieldInputModelButton и AiFieldInputEffortButton есть встроенный выпадающий список:

  • items — пункты { id, label, description? };
  • onSelect — выбор пункта, получает id.

На desktop список открывается над кнопкой, на mobile — в шторке снизу. Пока список открыт, кнопка остаётся в состоянии Pressed. Поиск по названию в списке моделей включается пропом searchable у AiFieldInputModelButton, по умолчанию его нет. На mobile с поиском шторка раскрывается на весь экран, без него — по высоте списка. Выбранный пункт в списке не отмечается: текущее значение показывает подпись кнопки (label). Без items кнопка только сообщает о нажатии через onClick.

Значение

Содержимое поля — массив сегментов AiFieldInputValue:

  • text — текст, \n — перенос строки;
  • skill — чип скилла или команды. Параметры — обычный текст сообщения за чипом; пока за чипом в строке ничего нет, в нём видна подсказка paramsPlaceholder (её задаёт строка списка skills);
  • mention — чип упоминания;
  • search — знак / или @ с набранным запросом, пока значение не выбрано.

Ввод / или @ создаёт сегмент search, если для этого знака передан список (skills или mentions) и знак стоит в начале строки, после пробела или сразу за чипом; внутри слова (e@mail) поиск не открывается. Подсказку в поиске задаёт searchPlaceholder — отдельно для / (skill) и @ (mention); не заданный ключ берёт текст из локали. Подсказка видна, пока запрос пуст и сразу за знаком нет текста.

Строки списка передаются пропсами:

  • skills — команды и скиллы, открываются по /;
  • mentions — ресурсы и сущности, открываются по @.

Поле само показывает список над полем и фильтрует строки по набранному тексту. Список стоит поверх содержимого выше поля и не меняет высоту компонента: баннер на это время скрыт, но держит место. Если совпадений нет — строка «Ничего не найдено». Выбор строки заменяет сегмент search на чип skill или mention, вызывает onActionSelect и возвращает баннер. Пока список открыт, кнопка прокрутки скрыта.

Строка drillDown с вложенными items открывает следующий уровень: первой стоит строка возврата («Назад» или backLabel), при переходе на уровень и обратно набранный запрос стирается, и фильтрация начинается заново. Список закрывают Escape и клик вне списка и текста поля, в том числе по кнопкам футера, — набранный текст остаётся в поле обычным текстом. Клик внутри текста список не закрывает.

Список можно открыть и без знака в тексте — например, пунктом «Добавить скилл» в меню кнопки добавления. Для этого компоненты в слотах поля берут хук useAiFieldInputActions и вызывают openActionList('/') (или '@' для упоминаний):

function PlusButton() {
  const { openActionList } = useAiFieldInputActions();

  return (
    <AiFieldInputPlusButton
      items={[{ id: 'skills', label: 'Добавить скилл' }]}
      onSelect={id => id === 'skills' && openActionList(SEARCH_TRIGGER.Skill)}
    />
  );
}

В таком режиме поле не меняется, фокус встаёт на панель списка, и набранные буквы ничего не делают. Как и при поиске по /, строки сначала не выделены: стрелка вниз выделяет первую, стрелка вверх — последнюю, Enter выбирает первую. Выбранная строка встаёт чипом туда, где стоял курсор, или в конец текста, если поле ещё не фокусировали. После выбора или закрытия (Escape, клик вне списка) фокус возвращается в поле.

Баннер — обычный слот: крестик появляется, если передать onClose в AiFieldBanner; по нему потребитель убирает баннер из пропа banner.

Клавиатура

  • Enter — отправка (onSubmit); при открытом поиске — выбор первой строки списка.
  • Shift+Enter — перенос строки.
  • ↓ / ↑ при открытом поиске — переход в список.
  • Esc при открытом поиске — закрытие списка, знак и запрос остаются текстом.
  • Backspace сразу за чипом выделяет его (Pressed), повторный — удаляет. Delete сразу перед чипом — так же. Ввод при выделенном чипе снимает выделение и печатает за чипом.

Состояния

  • Default — рамка с нейтральной обводкой.
  • Focus — акцентная обводка рамки.
  • Disabled (disabled) — ввод недоступен, ряд вложений скрыт, кнопки футера выключены, кнопка контекста остаётся активной.
  • Secure (secure) — ввод пароля, API-ключа или токена. Вместо редактора — однострочное поле пароля: значение скрыто, не копируется и не вырезается, длинное значение обрезается по ширине. Кнопка «глаз» в начале левого футера показывает и снова скрывает значение, каретка остаётся в поле. После отправки значение снова скрыто. Чипов нет, «/» и «@» вводятся как обычный текст. При включении secure чипы убираются из значения, текст остаётся. При выключении secure значение очищается; в controlled-режиме редактор не показывает секрет, пока родитель не пришлёт новое значение.
  • Error (error) — мягкая красная заливка рамки, в фокусе красная обводка, под рамкой строка ошибки с текстом из error. Счётчик current/max в строке ошибки задаёт length — для ошибок, связанных с длиной значения. Ошибка не блокирует ввод и отправку: доступностью кнопки отправки управляет send. Снимается снаружи — когда значение исправлено или отправлено снова. На выключенном поле ошибка не показывается. В режиме secure текст ошибки не повторяет значение.

Кнопка отправки (default — по содержимому)

  • disabled — пустое поле.
  • active — в поле есть содержимое.
  • loading — сообщение отправляется.
  • stop — агент генерирует ответ, нажатие останавливает генерацию.

Состояния loading и stop задаёт потребитель через send.state. Нажатие на кнопку в состоянии active вызывает onSubmit так же, как Enter; send.onClick получает состояние и содержимое поля. Пока кнопка в loading или stop, Enter не отправляет.

Установка

pnpm add @cloud-ru/ds-ai-field-input @cloud-ru/ds-ai-attachment

@cloud-ru/ds-ai-attachment нужен для плиток вложений, сам пакет поля от него не зависит.

import { AiFieldInput } from '@cloud-ru/ds-ai-field-input'

Примеры использования

Базовое поле

Базовое полеEnter отправляет, Shift+Enter переносит строку
The agent can make mistakes. Please double-check responses
tsx
import { AiFieldInput, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';

export function Basic() {
  const [value, setValue] = useState<AiFieldInputValue>([]);
  const [lastSent, setLastSent] = useState('');

  return (
    <AiFieldInput
      value={value}
      onChange={setValue}
      onSubmit={current => {
        setLastSent(current.map(segment => (segment.type === 'text' ? segment.text : '')).join(''));
        setValue([]);
      }}
      placeholder='Спросите что-нибудь'
      disclaimer={lastSent ? `Отправлено: ${lastSent}` : undefined}
    />
  );
}

Скиллы и упоминания

Скиллы и упоминания«/» и «@» открывают список над полем, крестик закрывает баннер
Агент работает в режиме чтения
The agent can make mistakes. Please double-check responses
tsx
import { AiFieldBanner } from '@cloud-ru/ds-ai-field-banner';
import { ACTION_LIST_ITEM_TYPE, AiFieldInput, AiFieldInputActionListItem, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';

const SKILLS: AiFieldInputActionListItem[] = [
  { id: 'summarize', label: 'summarize', caption: 'Краткое содержание', shortcut: '⌘ S' },
  { id: 'translate', label: 'translate', caption: 'Перевод текста' },
  {
    id: 'agents',
    label: 'Агенты',
    caption: '2',
    type: ACTION_LIST_ITEM_TYPE.DrillDown,
    backLabel: 'К списку команд',
    items: [
      { id: 'hermes', label: 'Гермес' },
      { id: 'analyst', label: 'Аналитик' },
    ],
  },
];

const MENTIONS: AiFieldInputActionListItem[] = [
  { id: 'team', label: 'команде', caption: 'Группа' },
  { id: 'docs', label: 'документация', caption: 'Пространство' },
];

export function SlashCommands() {
  const [value, setValue] = useState<AiFieldInputValue>([]);
  const [bannerVisible, setBannerVisible] = useState(true);

  return (
    <AiFieldInput
      value={value}
      onChange={setValue}
      onSubmit={() => setValue([])}
      placeholder='Введите / для скиллов или @ для упоминаний'
      skills={SKILLS}
      mentions={MENTIONS}
      banner={
        bannerVisible ? (
          <AiFieldBanner content='Агент работает в режиме чтения' onClose={() => setBannerVisible(false)} />
        ) : undefined
      }
    />
  );
}

Вложения

ВложенияУдаление и повтор загрузки; на desktop ряд листается стрелками
report.pdfreport.pdf
budget.xlsxbudget.xlsx
notes.txtnotes.txt
design.figdesign.fig
contract.docxcontract.docx
roadmap.pdfroadmap.pdf
The agent can make mistakes. Please double-check responses
tsx
import { AiAttachment, ATTACHMENT_STATE, ATTACHMENT_TYPE } from '@cloud-ru/ds-ai-attachment';
import { AiFieldInput } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';

const INITIAL_FILES = ['report.pdf', 'budget.xlsx', 'notes.txt', 'design.fig', 'contract.docx', 'roadmap.pdf'];

export function Attachments() {
  const [files, setFiles] = useState(INITIAL_FILES);
  const [failed, setFailed] = useState('budget.xlsx');

  return (
    <AiFieldInput
      placeholder='Опишите, что сделать с файлами'
      attachments={
        files.length > 0
          ? files.map(file => (
              <AiAttachment
                key={file}
                type={ATTACHMENT_TYPE.File}
                state={file === failed ? ATTACHMENT_STATE.Error : ATTACHMENT_STATE.Default}
                fileName={file}
                tooltip={file === failed ? 'Не удалось загрузить' : file}
                onRemove={() => setFiles(prev => prev.filter(name => name !== file))}
                onRetry={() => setFailed('')}
              />
            ))
          : undefined
      }
    />
  );
}

Футер

ФутерКнопки из макета, выбор модели и уровня усилий, переключение отправки в остановку
The agent can make mistakes. Please double-check responses
tsx
import {
  AiFieldInput,
  AiFieldInputContextButton,
  AiFieldInputEffortButton,
  AiFieldInputModelButton,
  AiFieldInputPlusButton,
  AiFieldInputSettingsButton,
  AiFieldInputVoiceButton,
  SEND_STATE,
  SendState,
} from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';

const PLUS_ITEMS = [
  { id: 'files', label: 'Файлы', description: 'Загрузить с устройства' },
  { id: 'skills', label: 'Скиллы', description: 'Добавить скилл в запрос' },
  { id: 'connectors', label: 'Коннекторы', description: 'Внешние источники данных' },
];

const SETTINGS_ITEMS = [
  { id: 'chat', label: 'Настройки чата', description: 'Название, папка и доступ' },
  { id: 'memory', label: 'Память', description: 'Что агент помнит о вас' },
];

const MODELS = [
  { id: 'gigachat-2-max', label: 'GigaChat 2 Max' },
  { id: 'gigachat-2-pro', label: 'GigaChat 2 Pro' },
  { id: 'gigachat-2-lite', label: 'GigaChat 2 Lite' },
];

const EFFORTS = [
  { id: 'low', label: 'Низкий' },
  { id: 'medium', label: 'Средний' },
  { id: 'high', label: 'Высокий' },
];

export function FooterActions() {
  const [state, setState] = useState<SendState | undefined>(undefined);
  const [model, setModel] = useState(MODELS[0]);
  const [effort, setEffort] = useState(EFFORTS[2]);

  const handleModelSelect = (id: string) => setModel(MODELS.find(item => item.id === id) ?? MODELS[0]);
  const handleEffortSelect = (id: string) => setEffort(EFFORTS.find(item => item.id === id) ?? EFFORTS[2]);

  return (
    <AiFieldInput
      defaultValue={[{ type: 'text', text: 'Сгенерируй план релиза' }]}
      footerLeftActions={
        <>
          <AiFieldInputPlusButton
            items={PLUS_ITEMS}
            tooltip={{ content: 'Файлы, скиллы и коннекторы', shortcut: '⌘ /' }}
          />
          <AiFieldInputSettingsButton items={SETTINGS_ITEMS} tooltip={{ content: 'Настройки' }} />
          <AiFieldInputModelButton
            label={model.label}
            items={MODELS}
            tooltip={{ content: 'Выбор модели' }}
            onSelect={handleModelSelect}
          />
          <AiFieldInputEffortButton
            label={effort.label}
            items={EFFORTS}
            tooltip={{ content: 'Уровень усилий' }}
            onSelect={handleEffortSelect}
          />
        </>
      }
      footerRightActions={
        <>
          <AiFieldInputContextButton value={82} tooltip={{ content: 'Лимит: 82%' }} />
          <AiFieldInputVoiceButton tooltip={{ content: 'Голосовой ввод' }} />
        </>
      }
      send={{
        state,
        onClick: current => setState(current === SEND_STATE.Stop ? undefined : SEND_STATE.Stop),
      }}
    />
  );
}

Выключенное поле

Выключенное полеВвод и кнопки футера недоступны
The agent can make mistakes. Please double-check responses
tsx
import { AiFieldInput } from '@cloud-ru/ds-ai-field-input';

export function Disabled() {
  return <AiFieldInput disabled placeholder='Отправка сообщений недоступна' />;
}

Ввод секрета

Ввод секретаТекст скрыт точками, «глаз» в футере показывает его
The agent can make mistakes. Please double-check responses
tsx
import { AiFieldInput, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';

export function Secure() {
  const [value, setValue] = useState<AiFieldInputValue>([]);
  const [saved, setSaved] = useState(false);

  return (
    <AiFieldInput
      secure
      value={value}
      onChange={setValue}
      onSubmit={() => {
        setSaved(true);
        setValue([]);
      }}
      placeholder='Вставьте API-ключ'
      disclaimer={saved ? 'Ключ отправлен' : undefined}
    />
  );
}

Ошибка

ОшибкаПревышен лимит длины: строка ошибки со счётчиком, отправка выключена продуктом
Сообщение слишком длинное
45/40
The agent can make mistakes. Please double-check responses
tsx
import { AiFieldInput, AiFieldInputValue } from '@cloud-ru/ds-ai-field-input';
import { useState } from 'react';

const MAX_LENGTH = 40;

function getLength(value: AiFieldInputValue) {
  return value.reduce((sum, segment) => sum + ('text' in segment ? segment.text.length : 0), 0);
}

export function ErrorState() {
  const [value, setValue] = useState<AiFieldInputValue>([
    { type: 'text', text: 'Сообщение длиннее допустимого лимита символов' },
  ]);
  const length = getLength(value);
  const tooLong = length > MAX_LENGTH;

  return (
    <AiFieldInput
      value={value}
      onChange={setValue}
      onSubmit={() => setValue([])}
      error={tooLong ? 'Сообщение слишком длинное' : undefined}
      length={{ current: length, max: MAX_LENGTH }}
      send={tooLong ? { state: 'disabled' } : undefined}
    />
  );
}

Props

AiFieldInput

Types

PropsAiFieldInputProps
PropTypeDefaultRequiredDescription
attachmentsReactNode—noПлитки вложений (`AiAttachment` из `@cloud-ru/ds-ai-attachment`). Ряд не рендерится, если слот пуст.
attachmentsScrollStepnumber92noШаг сдвига ряда вложений стрелкой, px. По умолчанию — одна плитка с зазором (92).
bannerReactNode—noСлот над полем: `AiFieldBanner` или `AiFieldNotice`. Пока открыт список по `/` или `@`, на месте баннера стоит список.
classNamestring—noДоп. класс корня.
data-test-idstringai-field-inputno
defaultValueAiFieldInputValue—noНачальное содержимое (uncontrolled).
disabledbooleanfalsenoВыключенное поле: ввод недоступен, кнопки футера выключены, ряд вложений скрыт.
disclaimerReactNode—noТекст под полем. По умолчанию — дисклеймер из локали; `null` скрывает текст, отступ сохраняется.
errorstring—noТекст ошибки. Непустой — поле в состоянии ошибки: красная заливка рамки, в фокусе красная обводка, под рамкой строка ошибки. Ввод и отправку не блокирует: доступностью отправки управляет `send`. На выключенном поле (`disabled`) ошибка не показывается. В режиме `secure` текст не должен повторять значение.
footerLeftActionsReactNode—noСлот левых действий футера.
footerRightActionsReactNode—noСлот дополнительных правых действий футера (перед кнопкой отправки).
lengthFieldLength—noСчётчик `current/max` в строке ошибки, например `3002/3000`. Показывается только вместе с `error`, когда ошибка связана с длиной значения.
mentions(AiFieldInputActionListItem | AiFieldInputActionListGroup)[]—noСтроки списка по `@`: ресурсы и сущности. Не заданы — список по `@` не открывается.
onActionSelect((item: AiFieldInputActionListItem, trigger: SearchTrigger) => void)—noВыбор строки списка по `/` или `@`: строка уже стоит в поле чипом.
onChange((value: AiFieldInputValue) => void)—noИзменение содержимого.
onSubmit((value: AiFieldInputValue) => void)—noОтправка: Enter без Shift, когда поиск по `/` или `@` не активен, или нажатие кнопки в состоянии `active`. Пока кнопка в `loading` или `stop`, не вызывается.
placeholderstring—noПодсказка в пустом поле.
scrollButtonAiFieldInputScrollButton—noКнопка прокрутки к последнему сообщению над полем. Не задана — кнопки нет.
searchPlaceholderAiFieldInputSearchPlaceholder—noПодсказки в поиске после `/` и `@`. Не заданный ключ — текст из локали («Введите название» / «Type a name»).
securebooleanfalsenoВвод чувствительных данных: пароля, API-ключа, токена. Вместо редактора — однострочное поле `type="password"`: значение скрыто, не копируется и не вырезается. В футере слева — кнопка «глаз», которая показывает и снова скрывает значение; после отправки значение снова скрыто. Чипов, проверки орфографии, автозамены и списков по `/` и `@` нет: эти знаки вводятся как обычный текст. При включении `secure` из значения убираются чипы, остаётся текст. При выключении значение очищается: пока родитель не пришлёт новое значение, редактор секрет не показывает. По умолчанию `false`.
sendAiFieldInputSend—noКнопка отправки: состояние и нажатие.
skills(AiFieldInputActionListItem | AiFieldInputActionListGroup)[]—noСтроки списка по `/`: команды и скиллы. Не заданы — список по `/` не открывается.
valueAiFieldInputValue—noСодержимое поля (controlled).

Types

AiFieldInputProps

AiFieldInputActionList

Types

PropsAiFieldInputActionListProps
PropTypeDefaultRequiredDescription
classNamestring—noДоп. класс корня.
data-test-idstring—no
items(AiFieldInputActionListItem | AiFieldInputActionListGroup)[]—yesСтроки и группы строк.
onClose(() => void)—noНажатие Escape.
paddingboolean—noОтступ 8 со всех сторон; без него — только сверху и снизу. По умолчанию `false`.

Types

AiFieldInputActionListProps

Плитки вложений — AiAttachment из @cloud-ru/ds-ai-attachment.

Адаптивность

Раскладка берётся из AdaptiveProvider (@cloud-ru/ds-adaptive), пропа раскладки нет.

ЧастьDesktopMobile
Ряд вложенийстрелки при переполнении, полоса скрытасвайп, полоса видна при листании
Крестик плиткиxs с подложкой, при наведении или фокусеs с подложкой, виден всегда
Подсказка плиткипри наведениинет
Высота текстадо 10 строк, дальше прокруткадо 5 строк, дальше прокрутка
Списки кнопок футеравыпадающий список над кнопкойшторка снизу по высоте списка; со searchable у кнопки модели — на весь экран
/ и @ в текстеоткрывают список над полемпечатаются как обычный текст
openActionList из пункта меню кнопкисписок над полемсписок заменяет пункты в той же шторке; первая строка — возврат «Назад»
openActionList из своей кнопкисписок над полемсписок в отдельной шторке

Размер баннера в слоте выбирает потребитель.

На mobile скиллы и упоминания добавляются только через openActionList, например из пунктов меню кнопки добавления. Строки с переходом открывают следующий уровень в той же шторке, первой строкой уровня стоит возврат («Назад» или backLabel). Высота шторки подстраивается под список. Выбор строки закрывает шторку, ставит чип и курсор за ним.

Storybook

Figma