@sberbusiness/triplex-next-mcp-server 1.43.0-beta → 1.45.0-beta

package/bundle/components/Suggest.md

@@ -1,11 +1,9 @@
 ---
 component: Suggest
-category: Form Controls (base)
-figma-node: ""
-figma-file: ""
-related: [SuggestField, SelectField, Dropdown]
+category: Suggest
+related: [SuggestField, Chip, Dropdown]
 tokens: []
-stories: ""
+stories: stories/Suggest/Suggest.stories.tsx
 version: "1.0"
 ---
 
@@ -13,143 +11,171 @@ version: "1.0"
 
 ## Назначение
 
-Headless-примитив для построения autocomplete/suggest-полей. Управляет
-состоянием `inputValue`, `dropdownOpen`, `activeDescendant`, синхронизацией
-с внешним `value`, обработкой ESC и outside-click. Рендер UI — полностью на
-потребителе через children + Context.
+Headless-основа выпадающего списка с фильтрацией по введённому значению. Собственной
+разметки не добавляет: рендерит `<div>`-обёртку и раздаёт потомкам через `SuggestContext`
+значение поля ввода, видимость выпадающего списка и обработчики выбора, фильтрации и
+клавиатуры. Управляющий элемент (поле ввода, чипс, кнопка) и сам выпадающий список пишет
+потребитель — хук `useSuggestContext` отдаёт всё нужное состояние.
 
-Используй когда: нужен кастомный autocomplete поверх базовой логики.
-Для готового UI-компонента — `SuggestField`.
+Внутри библиотеки на этой основе построен `ChipSuggest`. `SuggestField` решает ту же
+задачу, но собственной реализацией состояния — на `Suggest` он пока не переведён
+(в `SuggestField.tsx` стоит `TODO: Переписать через useSuggest`).
 
----
+Используй когда: нужен suggest с нестандартным управляющим элементом или нестандартным
+выпадающим списком, а готовые `SuggestField` / `ChipSuggest` не подходят по разметке.
 
-## Файловая структура
-
-```text
-src/components/Suggest/
-├── Suggest.tsx                       # forwardRef, корень + Provider
-├── SuggestContext.ts
-├── types.ts                          # ISuggestProps, ISuggestOption, ISuggestTargetProps...
-├── useSuggest.ts                     # весь state + колбэки
-├── SuggestMobileDropdownContent.tsx  # mobile-вариант списка
-├── index.ts
-└── styles/
-```
+Не используй когда:
+- Нужно обычное поле-suggest с лейблом, статусами и кнопкой очистки — возьми
+  `SuggestField`, он уже собран.
+- Нужен suggest-фильтр в ряду чипсов — возьми `ChipSuggest`.
+- Список не фильтруется вводом — возьми `SelectField` или `Dropdown` напрямую.
 
 ---
 
-## Публичный API
+## Варианты и props
 
-### `Suggest<T extends ISuggestOption>` (forwardRef)
-
-Generic по типу опции. Корневой `<div>` с `onKeyDown` и ref.
+### Обязательные props
 
 | Prop | Тип | Описание |
 |---|---|---|
-| `value` | `T \| undefined` | Выбранная опция. |
-| `options` | `T[]` | Список опций. |
-| `size` | `EComponentSize` | Размер (прокидывается детям). |
-| `onSelect` | `(value: T \| undefined) => void` | Колбэк выбора. Вызывается после `closeDropdown`. |
-| `onFilter` | `(value: string) => void` | Колбэк ввода в input. |
-| `onScrollEnd?` | `() => void` | Вызов при скролле до конца списка (пагинация). |
-| `placeholder?` | `string` | Передаётся в Context. |
-| `noOptionsText?` | `string` | Текст «ничего не найдено». |
-| `loading?` | `boolean` | Флаг загрузки корневого уровня. |
-| `dropdownListLoading?` | `boolean` | Флаг загрузки списка (пагинация). |
-| `tooltipOpen?` | `boolean` | Контролируемое открытие Tooltip (в потребителях). |
-| `clearInputOnFocus?` | `boolean` | Очищать input при focus. |
-| `children` | `ReactNode` | Слои UI (Target/Dropdown потребителя). |
-| `...HTMLAttributes<HTMLDivElement>` | — | Прокидываются на корневой div (кроме `onSelect`). |
-
-### `ISuggestOption`
-
-```ts
-{ id: string; label: string; content?: ReactNode; showNotificationIcon?: boolean }
-```
+| `value` | `T \| undefined` | Выбранная опция. Контролируемое значение: при его смене поле ввода перезаписывается на `value.label` |
+| `options` | `T[]` | Список опций. Фильтрацию делает потребитель в `onFilter` — компонент список не фильтрует |
+| `size` | `EComponentSize` | Размер. Suggest его **не отображает и не кладёт в контекст** — свойство существует, чтобы не попасть в DOM атрибутом; раздавай размер управляющему элементу и списку сам |
+| `onSelect` | `(value: T \| undefined) => void` | Вызывается после выбора опции. Перед вызовом список закрывается, а в поле ввода подставляется `label` выбранной опции |
+| `onFilter` | `(value: string) => void` | Вызывается на каждое изменение поля ввода. Ответ — обновлённый `options` |
 
-`label` используется как текст в inputValue по умолчанию.
+### Опциональные props
 
----
+| Prop | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `placeholder` | `string` | — | Текст подсказки. Только раздаётся через контекст, компонент его не рендерит |
+| `noOptionsText` | `string` | — | Текст при пустом `options`. Рендерится в мобильном наполнении, в десктопном — потребителем |
+| `loading` | `boolean` | — | Флаг загрузки. В мобильном наполнении рисует лоадер в шапке, в десктопном — на усмотрение потребителя |
+| `dropdownListLoading` | `boolean` | — | Флаг догрузки списка: лоадер под уже загруженными опциями |
+| `tooltipOpen` | `boolean` | — | Управление видимостью Tooltip у потребителя. Suggest только раздаёт значение через контекст |
+| `clearInputOnFocus` | `boolean` | — | Очищать поле ввода при получении фокуса. Обработчик `onFocus` пишет потребитель — Suggest ничего не слушает |
+| `onScrollEnd` | `() => void` | — | Доступные опции закончились при скролле списка. В мобильном наполнении вызывается автоматически |
+| `onKeyDown` | `React.KeyboardEventHandler` | — | Обработчик клавиатуры на корневом `<div>`. Вызывается после внутренней обработки `Escape` |
 
-## Хук `useSuggest`
+Все остальные `React.HTMLAttributes<HTMLDivElement>` (кроме `onSelect`) попадают на
+корневой `<div>`: `className`, `id`, `data-*`, `aria-*`, `style`.
 
-Вся логика. Выставляет в контекст:
-- `inputValue`, `setInputValue`
-- `activeDescendant`, `setActiveDescendant`
-- `dropdownOpen`, `setDropdownOpen`
-- `dropdownListId` (уникальный `dropdown-list-<n>`)
-- `closeDropdown(newInputValue?)` — закрытие с восстановлением значения из `latestValueRef`
-- `onSelect` — вызывает `closeDropdown(label)` + `props.onSelect`
-- `onFilter` — вызывает `setInputValue` + `props.onFilter`
-- `onKeyDown` — Escape закрывает dropdown (с `stopPropagation`), остальные — прокидывает в props.onKeyDown.
+### Что даёт `useSuggestContext`
 
-### Синхронизация value → inputValue
+Помимо перечисленных выше props потребитель получает состояние, которого нет во внешнем API:
 
-```
-if (value !== prevValue) {
-    setPrevValue(value);
-    setInputValue(value?.label || "");
-}
-```
+| Поле | Описание |
+|---|---|
+| `inputValue` / `setInputValue` | Текущий текст поля ввода. `setInputValue` не вызывает `onFilter` |
+| `dropdownOpen` / `setDropdownOpen` | Видимость списка. `setDropdownOpen(false)` не сбрасывает поле ввода |
+| `closeDropdown(newInputValue?)` | Закрывает список и возвращает в поле `newInputValue` либо `label` текущего `value` |
+| `activeDescendant` / `setActiveDescendant` | Идентификатор элемента, выделенного клавиатурой, для `aria-activedescendant`. Библиотека его не выставляет — клавиатурную навигацию по списку реализует потребитель. `setActiveDescendant` приходит в контекст из `useSuggest` в рантайме, но в типе значения контекста не объявлен — типизация поля меняет публичный тип `SuggestContext`, решение за мейнтейнером |
+| `dropdownListId` | Сгенерированный `dropdown-list-{n}` для `id` списка и `aria-controls` на управляющем элементе |
+| `suggestRef` | Ссылка на корневой `<div>`. Годится как `targetRef` для `Dropdown` |
+| `dropdownRef` | Ссылку **обязан заполнить потребитель**, повесив её на выпадающий список. По ней Suggest отличает клик внутри списка от клика вне компонента |
+| `onSelect` / `onFilter` | Обёртки над одноимёнными props: дополнительно обновляют `inputValue` и закрывают список |
 
-Синхронизация через «derived state pattern» (сравнение в render'е, не в useEffect).
+### Опция (`ISuggestOption`)
 
-### `latestValueRef`
+`id` (уникальный, используется как ключ и для сравнения с `value`), `label` (текст в поле
+ввода и в списке), `content` (кастомная разметка опции в списке вместо `label`),
+`showNotificationIcon` (значок новых уведомлений).
 
-`useLayoutEffect` обновляет ref после каждого рендера — чтобы `closeDropdown`
-(создаваемый в useCallback один раз) всегда читал актуальный `value`
-при восстановлении `inputValue`.
+Тип опции расширяется дженериком: `<Suggest<IMyOption> ...>` протаскивает `IMyOption`
+в `value`, `options` и `onSelect`.
 
 ---
 
-## Context (`SuggestContext`)
+## Дизайн-токены
 
-Полное расширение возврата useSuggest + публичные props:
-`value`, `options`, `placeholder`, `noOptionsText`, `loading`, `dropdownListLoading`,
-`tooltipOpen`, `clearInputOnFocus`, `onScrollEnd`, `suggestRef`, `dropdownRef` + state/колбэки из useSuggest.
+Собственных токенов нет: единственный стиль компонента —
+`styles/SuggestDropdown.module.less` — задаёт высоту и отступы мобильного наполнения
+фиксированными значениями. Внешний вид определяют компоненты, которыми потребитель
+собирает управляющий элемент и список (`TextField`, `Chip`, `Dropdown`), — их токены
+переопределяются через `ThemeProvider` в соответствующих AI.md.
 
 ---
 
-## Поведение outside-click
-
-`useEffect` на `dropdownOpen`: вешает `mousedown`-listener на `document`,
-закрывает dropdown, если клик не попал ни в `suggestRef`, ни в `dropdownRef`.
+## Инварианты
 
-`dropdownRef` — заполняется потребителем (например, `SuggestField` прокидывает ref на Dropdown-контейнер).
+- `forwardRef` на `Suggest` — не убирать. Ref указывает на корневой `<div>`, тот же элемент
+  попадает в `suggestRef` контекста.
+- Корневой элемент — `<div>`. На него же вешается внутренний `onKeyDown`, поэтому событие
+  клавиатуры от любого потомка проходит через обработчик `Escape`.
+- `size`, `onSelect`, `onFilter` и `onKeyDown` намеренно исключаются из `...restProps` —
+  иначе React отрендерит невалидные атрибуты на `<div>` и потеряет внутреннюю обработку.
+- Закрытие по клику вне работает только если потребитель заполнил `dropdownRef`. Список
+  обычно живёт в портале и корневым `<div>` не покрывается.
+- `Escape` останавливает всплытие **только когда список открыт** — на этом строится
+  вложенность suggest'а в модальные окна: закрытым suggest'ом `Escape` пробрасывается выше.
+- Имена полей контекста — публичный API: `SuggestContext` и `useSuggestContext`
+  экспортируются из barrel и используются вне папки компонента (`ChipSuggest`).
+- `SuggestMobileDropdownContent` из barrel **не экспортируется**, но импортируется
+  `ChipSuggest` по прямому пути. Переименование файла ломает `ChipSuggest`.
 
 ---
 
-## Инварианты
+## Accessibility
 
-- **`forwardRef<HTMLDivElement>`** + **generic `<T extends ISuggestOption>`** — сохранять оба. Тип результата — кастомный через `as` cast из-за generic'а.
-- **`SuggestContext` — единственный источник состояния** для детей. Не создавать параллельные useState в target/dropdown компонентах потребителя.
-- **ESC закрывает dropdown с `stopPropagation()`** — чтобы не всплывало в `Overlay`/`Modal`.
-- **Синхронизация `value` → `inputValue`** через render-сравнение (`value !== prevValue`). Не переписывать на `useEffect` без обсуждения — появятся «мерцания».
-- **`closeDropdown` использует `latestValueRef`, не `value`** — чтобы closure в listener'ах отдавал актуальное значение.
-- **`dropdownListId` — один на инстанс** (через `uniqueId()` в `useState` initializer).
-- **`onSelect(undefined)`** — допустимо (сбрасывает выбор). Потребитель должен это учесть.
+Собственных ARIA-атрибутов Suggest не выставляет — разметку управляющего элемента и
+списка пишет потребитель. Компонент даёт для этого:
 
----
+- `dropdownListId` — общий идентификатор для `id` списка и `aria-controls` на управляющем
+  элементе;
+- `dropdownOpen` — значение для `aria-expanded`;
+- `activeDescendant` / `setActiveDescendant` — для `aria-activedescendant` при клавиатурной
+  навигации по списку.
 
-## Accessibility
+Клавиатура: обработан только `Escape` — при открытом списке он закрывает список,
+возвращает в поле ввода `label` текущего `value` и останавливает всплытие события.
+Стрелки и `Enter` обрабатывает список потребителя (`DropdownList` / `DropdownListItem`
+делают это сами). Возврат фокуса на управляющий элемент после закрытия Suggest не делает —
+в `ChipSuggest` это решается `FocusTrap` вокруг содержимого дропдауна.
 
-- Компонент не навязывает ARIA — роли (`combobox`, `listbox`, `option`), `aria-controls`, `aria-expanded`, `aria-activedescendant` задаёт потребитель (напр. `SuggestField`).
-- `dropdownListId` доступен через контекст — потребитель должен повесить его на `<ul role="listbox">` и использовать как `aria-controls` на input'е.
-- Escape-handling реализован на корневом div — потребитель не должен дублировать его на input.
+Мобильное наполнение (`SuggestMobileDropdownContent`) рендерит список с `role="listbox"`
+и опциями `role="option"` с `aria-selected`, поле ввода получает автофокус при открытии.
 
 ---
 
 ## Связанные компоненты
 
-- `SuggestField` — готовый UI поверх Suggest.
-- `Dropdown` — используется внутри SuggestField для выпадающего списка.
-- `SelectField` — для статического списка без фильтрации.
+- `SuggestField` — готовое поле-suggest с лейблом, статусами, префиксом/постфиксом и
+  очисткой. Решает ту же задачу «из коробки»; на `Suggest` не построен и дублирует его
+  состояние своей реализацией.
+- `Chip` — родитель `ChipSuggest`, единственного компонента библиотеки, собранного на
+  `Suggest`. `ChipSuggest` опирается не только на barrel, но и на внутренний
+  `SuggestMobileDropdownContent`.
+- `Dropdown` — мобильное наполнение Suggest рендерится из его частей
+  (`DropdownMobileHeader`, `DropdownMobileInput`, `DropdownMobileList`, …); в десктопной
+  композиции `Dropdown` обычно и служит выпадающим списком.
+- `SuggestMobileDropdownContent` — внутреннее наполнение полноэкранного мобильного
+  дропдауна: поле ввода, список опций, лоадер и текст при пустом списке. Данные берёт из
+  `SuggestContext`, поэтому рендерится только внутри `Suggest`. Отдельного AI.md не имеет,
+  из barrel не экспортируется.
 
 ---
 
 ## Stories
 
-Отдельных stories нет — демонстрируется через `SuggestField`.
+Основные истории: `stories/Suggest/Suggest.stories.tsx`
+Файлы примеров: `stories/Suggest/examples/`
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `Playground.tsx` | Интерактивный контроль `size`, `placeholder`, `noOptionsText`, `clearInputOnFocus`, `dropdownListLoading` |
+| `Default` | `Default.tsx` | Минимальная композиция: Suggest + управляющий элемент на `TextField` + список на `Dropdown` |
+| `Sizes` | `Sizes.tsx` | Размеры SM / MD / LG — размер раздаётся потребителем |
+| `DropdownListLoading` | `DropdownListLoading.tsx` | Догрузка опций: лоадер под уже загруженным списком |
+| `VisualTests` | `VisualTests.tsx` | Скриншот-регрессия: размеры, заполненное значение, открытый дропдаун. Пустой список в кадр не попадает — открыт может быть только один дропдаун |
+| `VisualTestsDropdownListLoading` | `VisualTestsDropdownListLoading.tsx` | Скриншот-регрессия: открытый дропдаун с лоадером догрузки. Отдельная стори — два Suggest'а не могут быть открыты одновременно |
+
+Скриншот-тестами покрыты только `VisualTests` и `VisualTestsDropdownListLoading`:
+набор исключён из скриншотов на уровне `meta` (`testRunner: { skip: true }`), а эти две
+стори включены обратно через `testRunner: { skip: false }` — как в `ModalWindow`.
+Suggest headless: собственной разметки он не рендерит, поэтому в кадре закрытых стори
+только обвязка примеров (`TextField`, `Dropdown`), у которых своё визуальное покрытие,
+а baseline `Default` и `DropdownListLoading` совпадали побайтово. Ценность есть лишь
+у кадров с открытым списком, которые ставит `play`-функция.
 
 ---
 
@@ -157,4 +183,414 @@ if (value !== prevValue) {
 
 | Дата | Изменение |
 |---|---|
-| 2026-04-18 | Создан документ |
+| 2026-09-02 | Создан документ |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Suggest/examples/Default.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    Dropdown,
+    DropdownList,
+    DropdownListItem,
+    EComponentSize,
+    EDropdownWidth,
+    Suggest,
+    TextField,
+    useSuggestContext,
+    type ISuggestOption,
+} from "@sberbusiness/triplex-next";
+
+const FRUITS: ISuggestOption[] = [
+    { id: "1", label: "Apple" },
+    { id: "2", label: "Banana" },
+    { id: "3", label: "Cherry" },
+    { id: "4", label: "Grapes" },
+    { id: "5", label: "Melon" },
+];
+
+const SIZE = EComponentSize.LG;
+
+/** Управляющий элемент. Значение поля ввода и состояние списка берутся из SuggestContext. */
+const SuggestTarget = () => {
+    const { inputValue, dropdownOpen, dropdownListId, setDropdownOpen, onFilter } = useSuggestContext();
+
+    return (
+        <TextField
+            label="Fruit"
+            size={SIZE}
+            inputProps={{
+                value: inputValue,
+                placeholder: "Type to proceed",
+                role: "combobox",
+                "aria-expanded": dropdownOpen,
+                "aria-controls": dropdownListId,
+                onChange: (event) => {
+                    onFilter(event.target.value);
+                    setDropdownOpen(true);
+                },
+                onClick: () => setDropdownOpen(true),
+            }}
+        />
+    );
+};
+
+/** Выпадающий список. dropdownRef обязателен: по нему Suggest отличает клик внутри списка от клика вне компонента. */
+const SuggestDropdown = () => {
+    const {
+        value,
+        options,
+        noOptionsText,
+        dropdownOpen,
+        dropdownListId,
+        suggestRef,
+        dropdownRef,
+        setDropdownOpen,
+        closeDropdown,
+        onSelect,
+    } = useSuggestContext();
+
+    return (
+        <Dropdown
+            ref={dropdownRef}
+            size={SIZE}
+            targetRef={suggestRef}
+            width={EDropdownWidth.TARGET}
+            opened={dropdownOpen}
+            setOpened={(opened) => (opened ? setDropdownOpen(true) : closeDropdown())}
+        >
+            {options.length === 0 ? (
+                // id остаётся на контейнере и в пустом состоянии — иначе aria-controls
+                // управляющего элемента ссылается на несуществующий элемент.
+                <div id={dropdownListId} style={{ padding: "12px 16px" }}>
+                    {noOptionsText}
+                </div>
+            ) : (
+                <DropdownList id={dropdownListId} size={SIZE} dropdownOpened={dropdownOpen}>
+                    {options.map((option) => (
+                        <DropdownListItem
+                            key={option.id}
+                            id={option.id}
+                            selected={option.id === value?.id}
+                            onSelect={() => onSelect(option)}
+                        >
+                            {option.label}
+                        </DropdownListItem>
+                    ))}
+                </DropdownList>
+            )}
+        </Dropdown>
+    );
+};
+
+export const Default = () => {
+    const [value, setValue] = useState<ISuggestOption>();
+    const [options, setOptions] = useState<ISuggestOption[]>(FRUITS);
+
+    const handleFilter = (inputValue: string) =>
+        setOptions(FRUITS.filter(({ label }) => label.toLowerCase().includes(inputValue.toLowerCase())));
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <Suggest
+                value={value}
+                options={options}
+                size={SIZE}
+                noOptionsText="No matches found."
+                onSelect={setValue}
+                onFilter={handleFilter}
+            >
+                <SuggestTarget />
+                <SuggestDropdown />
+            </Suggest>
+        </div>
+    );
+};
+```
+
+### Sizes
+
+`stories/Suggest/examples/Sizes.tsx`
+
+```tsx
+import React, { useState } from "react";
+import {
+    Dropdown,
+    DropdownList,
+    DropdownListItem,
+    EComponentSize,
+    EDropdownWidth,
+    Suggest,
+    TextField,
+    useSuggestContext,
+    type ISuggestOption,
+} from "@sberbusiness/triplex-next";
+
+const FRUITS: ISuggestOption[] = [
+    { id: "1", label: "Apple" },
+    { id: "2", label: "Banana" },
+    { id: "3", label: "Cherry" },
+    { id: "4", label: "Grapes" },
+    { id: "5", label: "Melon" },
+];
+
+const SIZES = Object.values(EComponentSize);
+
+interface ISuggestPartProps {
+    size: EComponentSize;
+}
+
+/** Управляющий элемент. Suggest сам размер не отображает — прокидывайте его в поле ввода и список. */
+const SuggestTarget = ({ size }: ISuggestPartProps) => {
+    const { inputValue, dropdownOpen, dropdownListId, setDropdownOpen, onFilter } = useSuggestContext();
+
+    return (
+        <TextField
+            label="Fruit"
+            size={size}
+            inputProps={{
+                value: inputValue,
+                placeholder: "Type to proceed",
+                role: "combobox",
+                "aria-expanded": dropdownOpen,
+                "aria-controls": dropdownListId,
+                onChange: (event) => {
+                    onFilter(event.target.value);
+                    setDropdownOpen(true);
+                },
+                onClick: () => setDropdownOpen(true),
+            }}
+        />
+    );
+};
+
+/** Выпадающий список. dropdownRef обязателен: по нему Suggest отличает клик внутри списка от клика вне компонента. */
+const SuggestDropdown = ({ size }: ISuggestPartProps) => {
+    const {
+        value,
+        options,
+        noOptionsText,
+        dropdownOpen,
+        dropdownListId,
+        suggestRef,
+        dropdownRef,
+        setDropdownOpen,
+        closeDropdown,
+        onSelect,
+    } = useSuggestContext();
+
+    return (
+        <Dropdown
+            ref={dropdownRef}
+            size={size}
+            targetRef={suggestRef}
+            width={EDropdownWidth.TARGET}
+            opened={dropdownOpen}
+            setOpened={(opened) => (opened ? setDropdownOpen(true) : closeDropdown())}
+        >
+            {options.length === 0 ? (
+                // id остаётся на контейнере и в пустом состоянии — иначе aria-controls
+                // управляющего элемента ссылается на несуществующий элемент.
+                <div id={dropdownListId} style={{ padding: "12px 16px" }}>
+                    {noOptionsText}
+                </div>
+            ) : (
+                <DropdownList id={dropdownListId} size={size} dropdownOpened={dropdownOpen}>
+                    {options.map((option) => (
+                        <DropdownListItem
+                            key={option.id}
+                            id={option.id}
+                            selected={option.id === value?.id}
+                            onSelect={() => onSelect(option)}
+                        >
+                            {option.label}
+                        </DropdownListItem>
+                    ))}
+                </DropdownList>
+            )}
+        </Dropdown>
+    );
+};
+
+const SizeItem = ({ size }: ISuggestPartProps) => {
+    const [value, setValue] = useState<ISuggestOption>();
+    const [options, setOptions] = useState<ISuggestOption[]>(FRUITS);
+
+    const handleFilter = (inputValue: string) =>
+        setOptions(FRUITS.filter(({ label }) => label.toLowerCase().includes(inputValue.toLowerCase())));
+
+    return (
+        <div>
+            <div style={{ marginBottom: "8px", fontSize: "16px", fontWeight: "700" }}>{size.toUpperCase()}</div>
+            <Suggest
+                value={value}
+                options={options}
+                size={size}
+                noOptionsText="No matches found."
+                onSelect={setValue}
+                onFilter={handleFilter}
+            >
+                <SuggestTarget size={size} />
+                <SuggestDropdown size={size} />
+            </Suggest>
+        </div>
+    );
+};
+
+export const Sizes = () => (
+    <div style={{ maxWidth: "300px", display: "flex", flexDirection: "column", gap: "16px" }}>
+        {SIZES.map((size) => (
+            <SizeItem key={size} size={size} />
+        ))}
+    </div>
+);
+```
+
+### DropdownListLoading
+
+`stories/Suggest/examples/DropdownListLoading.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import {
+    Dropdown,
+    DropdownList,
+    DropdownListItem,
+    EComponentSize,
+    EDropdownWidth,
+    Suggest,
+    TextField,
+    useSuggestContext,
+    type ISuggestOption,
+} from "@sberbusiness/triplex-next";
+
+const FRUITS: ISuggestOption[] = [
+    { id: "1", label: "Apple" },
+    { id: "2", label: "Banana" },
+    { id: "3", label: "Cherry" },
+    { id: "4", label: "Grapes" },
+    { id: "5", label: "Melon" },
+];
+
+const SIZE = EComponentSize.LG;
+const REQUEST_DELAY = 700;
+
+/** Управляющий элемент. Значение поля ввода и состояние списка берутся из SuggestContext. */
+const SuggestTarget = () => {
+    const { inputValue, dropdownOpen, dropdownListId, setDropdownOpen, onFilter } = useSuggestContext();
+
+    return (
+        <TextField
+            label="Fruit"
+            size={SIZE}
+            inputProps={{
+                value: inputValue,
+                placeholder: "Type to proceed",
+                role: "combobox",
+                "aria-expanded": dropdownOpen,
+                "aria-controls": dropdownListId,
+                onChange: (event) => {
+                    onFilter(event.target.value);
+                    setDropdownOpen(true);
+                },
+                onClick: () => setDropdownOpen(true),
+            }}
+        />
+    );
+};
+
+/** Выпадающий список. dropdownListLoading дорисовывает лоадер под уже загруженными опциями. */
+const SuggestDropdown = () => {
+    const {
+        value,
+        options,
+        noOptionsText,
+        dropdownOpen,
+        dropdownListId,
+        dropdownListLoading,
+        suggestRef,
+        dropdownRef,
+        setDropdownOpen,
+        closeDropdown,
+        onSelect,
+    } = useSuggestContext();
+
+    return (
+        <Dropdown
+            ref={dropdownRef}
+            size={SIZE}
+            targetRef={suggestRef}
+            width={EDropdownWidth.TARGET}
+            opened={dropdownOpen}
+            setOpened={(opened) => (opened ? setDropdownOpen(true) : closeDropdown())}
+        >
+            {options.length === 0 && !dropdownListLoading ? (
+                // id остаётся на контейнере и в пустом состоянии — иначе aria-controls
+                // управляющего элемента ссылается на несуществующий элемент.
+                <div id={dropdownListId} style={{ padding: "12px 16px" }}>
+                    {noOptionsText}
+                </div>
+            ) : (
+                <DropdownList
+                    id={dropdownListId}
+                    size={SIZE}
+                    dropdownOpened={dropdownOpen}
+                    loading={dropdownListLoading}
+                >
+                    {options.map((option) => (
+                        <DropdownListItem
+                            key={option.id}
+                            id={option.id}
+                            selected={option.id === value?.id}
+                            onSelect={() => onSelect(option)}
+                        >
+                            {option.label}
+                        </DropdownListItem>
+                    ))}
+                </DropdownList>
+            )}
+        </Dropdown>
+    );
+};
+
+export const DropdownListLoading = () => {
+    const [value, setValue] = useState<ISuggestOption>();
+    const [options, setOptions] = useState<ISuggestOption[]>(FRUITS);
+    const [loading, setLoading] = useState(false);
+    const requestRef = useRef<ReturnType<typeof setTimeout>>();
+
+    const handleFilter = (inputValue: string) => {
+        clearTimeout(requestRef.current);
+        setLoading(true);
+
+        requestRef.current = setTimeout(() => {
+            setOptions(FRUITS.filter(({ label }) => label.toLowerCase().includes(inputValue.toLowerCase())));
+            setLoading(false);
+        }, REQUEST_DELAY);
+    };
+
+    return (
+        <div style={{ maxWidth: "300px" }}>
+            <Suggest
+                value={value}
+                options={options}
+                size={SIZE}
+                noOptionsText="No matches found."
+                dropdownListLoading={loading}
+                onSelect={setValue}
+                onFilter={handleFilter}
+            >
+                <SuggestTarget />
+                <SuggestDropdown />
+            </Suggest>
+        </div>
+    );
+};
+```
+