@sberbusiness/triplex-next-mcp-server 1.53.0 → 1.54.0

package/bundle/components/ChipSuggestTarget.md

@@ -0,0 +1,506 @@
+---
+component: ChipSuggestTarget
+category: Chips
+related: [ChipSuggest, ChipSelectTarget, Chip, Suggest]
+tokens: []
+stories: stories/Chips/ChipSuggest.stories.tsx
+version: "1.0"
+---
+
+# ChipSuggestTarget
+
+## Назначение
+
+Публичный target для `ChipSuggest`: рендерит `Chip` с подписью и стрелкой либо
+очисткой, открывает и закрывает список через `SuggestContext`.
+Выбранное значение и открытость берёт из ближайшего `Suggest`.
+
+Используй когда: собираешь свою композицию `Suggest` с чипсом вместо поля.
+Для готового поиска со списком используй `ChipSuggest`; для target с открытостью
+через props вместо контекста — `ChipSelectTarget`.
+
+Публичные импорты:
+
+```tsx
+import { ChipSuggestTarget, type IChipSuggestTargetProps, type ISuggestOption } from "@sberbusiness/triplex-next";
+```
+
+Компонент и интерфейс сохраняют generic-параметр `<T extends ISuggestOption>`.
+Рендери target внутри `Suggest<T>`: вне provider он получает пустое значение,
+закрытый список и setter-заглушку; самостоятельной работы со списком нет.
+
+---
+
+## Варианты и props
+
+`IChipSuggestTargetProps<T>` наследует `IChipProps` без `prefix` / `postfix`
+и добавляет опциональный `clearSelected`. Обязательных custom-props нет.
+
+| Prop | По умолчанию | Назначение и ограничения |
+|---|---|---|
+| `children` | — | Подпись. Target не подставляет `value.label`: это делает `ChipSuggest` либо потребитель своей композиции |
+| `clearSelected` | — | Вызывается без аргументов встроенной очисткой. Значение `Suggest.value` обновляет потребитель; без callback кнопка остаётся без действия |
+| `onClick` | — | Получает React mouse event после `setDropdownOpen(!dropdownOpen)` |
+| `onKeyDown` | — | Получает все дошедшие до target события клавиатуры, кроме Enter / Space на встроенной очистке; Enter / Space — после переключения |
+| `size` | `EComponentSize.MD` | SM / MD / LG; передаётся в `Chip`, стрелку и очистку |
+| `type` | `EChipType.TYPE_1` | Визуальный тип `Chip`; при использовании через `ChipSuggest` задаётся на родителе |
+| `disabled` | `false` | Отключает target и встроенную очистку; ограничения — в Accessibility |
+| `showNotificationIcon` | `false` | Значок `Badge.Dot` через `Chip` |
+| `className`, `style`, `id`, `data-*`, `aria-*`, прочие span-атрибуты | — | Передаются в корневой `<span>`; `className` объединяется с классами `Chip` |
+| `ref` | — | Указывает на `HTMLSpanElement` чипса, а не на корень `Suggest` или dropdown |
+
+### Состояние из контекста
+
+- При `value === undefined` отображается стрелка с `rotated={dropdownOpen}`.
+  Любое выбранное значение включает очистку и исходное `selected`-оформление.
+- Клик, Enter и Space переключают открытость в обе стороны. В отличие от
+  `ChipSelectTarget`, уже открытый список по Enter / Space закрывается.
+- Переключение target вызывает именно `setDropdownOpen`, а не `closeDropdown`:
+  дополнительный сброс строки фильтрации принадлежит другим частям `Suggest`.
+
+Spread унаследованных props находится после внутренних `selected` и
+`aria-expanded`: они могут быть переопределены потребителем. Выбор автоматического
+postfix при этом зависит только от `value` в контексте.
+`prefix` / `postfix` исключены из TypeScript API target.
+
+---
+
+## Дизайн-токены
+
+Собственных стилей и токенов у target нет, поэтому `tokens: []`.
+Внешний вид наследуется от `Chip`: см. [Chip-ai.md](Chip-ai.md#дизайн-токены).
+
+---
+
+## Инварианты
+
+- Сохраняются именованные экспорты `ChipSuggestTarget` и `IChipSuggestTargetProps`
+  через `Chip/ChipSuggest/index.ts` и `Chip/index.ts`, generic-сигнатура и тип ref.
+- `forwardRef` обязателен. Ref-target и корневой элемент — `<span>` `Chip`.
+  `displayName` — `"ChipSuggestTarget"`.
+- `ChipSuggestTargetWithRef` сохраняет React forwardRef-объект, а assertion
+  восстанавливает generic-вызов: не убирать параметр `T` из публичной сигнатуры.
+- `value`, `dropdownOpen` и setter читаются из `useSuggestContext<T>`;
+  не добавлять параллельный локальный state.
+- Сначала переключается открытость, затем вызывается пользовательский callback.
+  `preventDefault()` в нём не отменяет уже вызванный setter.
+- Клик и Enter / Space встроенной очистки не всплывают в target;
+  `clearSelected` вызывается без DOM-события.
+- Сохраняются порядок spread, внешний вид, размеры, типы, имена токенов и story IDs.
+  Код остаётся совместимым с React 17.
+
+---
+
+## Accessibility
+
+- По умолчанию корень — `<span role="button" tabIndex={0}>` с `aria-expanded`,
+  не combobox. Имя задают `children` или ARIA-атрибуты потребителя.
+- Enter / Space переключают список; Space не прокручивает страницу благодаря
+  `preventDefault()` в `Chip`. Синтетический click на самом span не создаётся.
+- Escape, клик вне компонента и состояние фильтра обрабатывает `Suggest`.
+  Сам target не переносит фокус: поле ввода, `FocusTrap` и возврат фокуса
+  принадлежат dropdown-композиции `ChipSuggest`.
+- Встроенная очистка — нативная кнопка: Enter / Space активируют её нативный
+  click и вызывают `clearSelected`.
+- У встроенной очистки нет доступного имени и отдельного prop для него
+  (TRI-139). ARIA-имя самого target на вложенную кнопку не передаётся.
+- `disabled` означает CSS `pointer-events: none` и `tabIndex=-1` у `Chip`
+  и нативный `disabled` у встроенной очистки. В обработчиках target флаг
+  не проверяется: программно отправленные события не защищены.
+  Не передавай `tabIndex`: он перекрывает `-1`, target снова получит фокус,
+  и Enter / Space переключат список.
+- `aria-controls`, `aria-haspopup` и `aria-pressed` автоматически не создаются.
+  Фокус оформляется через `Chip.Shadow_Focus`.
+
+---
+
+## Связанные компоненты
+
+- [ChipSuggest](ChipSuggest-ai.md) — готовый родитель, формирует подпись,
+  передаёт `targetProps` и рендерит target внутри `Suggest`.
+- [ChipSelectTarget](ChipSelectTarget-ai.md) — альтернатива с `opened` /
+  `setOpened` через props и другими правилами Enter / Space / Tab.
+- [Chip](Chip-ai.md) — непосредственно рендерится внутри; источник унаследованных
+  props, span-семантики и визуальных состояний.
+- [Suggest](../Suggest/Suggest-ai.md) — источник значения, открытости и setter
+  через контекст; его provider обязателен для рабочей композиции.
+- `ChipClearButton` и `ChipDropdownArrow` — автоматические варианты postfix;
+  собственного AI.md для этих обёрток нет.
+
+---
+
+## Stories
+
+Основные истории: `stories/Chips/ChipSuggest.stories.tsx`
+Файлы примеров: `stories/Chips/examples/ChipSuggest/`
+
+Используются истории родителя: отдельный stories-файл атому не нужен.
+
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Тип, размер, подпись и targetProps |
+| `Default` | `DefaultExample.tsx` | Target в готовой композиции поиска и очистки |
+| `Types` | `TypesExample.tsx` | TYPE_1 / TYPE_2 target |
+| `Sizes` | `SizesExample.tsx` | SM / MD / LG |
+| `States` | `StatesExample.tsx` | Выбор с очисткой и disabled target без выбора |
+| `WithNotificationIcon` | `WithNotificationIconExample.tsx` | Значок у опции списка, не у target; скриншот-прогон пропущен |
+| `VisualTests` | `VisualTestsExample.tsx` | Три размера и открытые списки; раскрытие выполняет useLayoutEffect примера |
+
+`Default`, `Types`, `Sizes`, `States` и `VisualTests` имеют Linux/CI baseline
+на `xs` / `xl` в `__screenshots__/`. Фокус базового чипса проверяет
+`VisualTests` в stories `Chip`.
+
+Контракт target покрывает `src/components/Chip/__tests__/ChipSuggestTarget.test.tsx`,
+интеграцию со списком — `ChipSuggest.test.tsx`.
+
+---
+
+## История изменений
+
+| Дата | Изменение |
+|---|---|
+| 2026-10-29 | Создан документ. |
+
+---
+
+## Примеры использования
+
+### Default
+
+`stories/Chips/examples/ChipSuggest/DefaultExample.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { ChipSuggest, EComponentSize, type ISuggestFieldOption } from "@sberbusiness/triplex-next";
+import { mapFruitsToSuggestOptions, SUGGEST_STORY_FRUITS } from "./storyConstants";
+
+export const DefaultExample = () => {
+    const initialOptions = mapFruitsToSuggestOptions([...SUGGEST_STORY_FRUITS]);
+
+    const [value, setValue] = useState<ISuggestFieldOption>();
+    const [options, setOptions] = useState<ISuggestFieldOption[]>([]);
+    const [tooltipOpen, setTooltipOpen] = useState(false);
+    const initialOptionsRef = useRef<ISuggestFieldOption[]>(initialOptions);
+
+    const handleDropdownOpen = () => {
+        setOptions(initialOptionsRef.current);
+        setTooltipOpen(false);
+    };
+
+    const handleFilter = (inputValue: string) => {
+        if (inputValue.length === 0) {
+            setOptions(initialOptionsRef.current);
+            setTooltipOpen(false);
+            return;
+        }
+
+        const filteredOptions = initialOptionsRef.current.filter(({ label }) =>
+            String(label).toLowerCase().includes(inputValue.toLowerCase()),
+        );
+
+        setOptions(filteredOptions);
+        setTooltipOpen(filteredOptions.length === 0);
+    };
+
+    return (
+        <ChipSuggest
+            value={value}
+            options={options}
+            tooltipOpen={tooltipOpen}
+            onSelect={setValue}
+            onFilter={handleFilter}
+            targetProps={{ clearSelected: () => setValue(undefined) }}
+            dropdownProps={{ onOpen: handleDropdownOpen }}
+            label="Suggest label"
+            placeholder="Type to proceed"
+            noOptionsText="No matches found."
+            size={EComponentSize.MD}
+        />
+    );
+};
+```
+
+### Types
+
+`stories/Chips/examples/ChipSuggest/TypesExample.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { ChipSuggest, EChipType, EComponentSize, type ISuggestFieldOption } from "@sberbusiness/triplex-next";
+import { mapFruitsToSuggestOptions, SUGGEST_STORY_FRUITS } from "./storyConstants";
+
+type TypeItemProps = {
+    type: EChipType;
+    label: string;
+};
+
+const initialOptions = mapFruitsToSuggestOptions([...SUGGEST_STORY_FRUITS]);
+
+const TypeItem = ({ type, label }: TypeItemProps) => {
+    const [value, setValue] = useState<ISuggestFieldOption>();
+    const [options, setOptions] = useState<ISuggestFieldOption[]>([]);
+    const [tooltipOpen, setTooltipOpen] = useState(false);
+    const initialOptionsRef = useRef<ISuggestFieldOption[]>(initialOptions);
+
+    const handleDropdownOpen = () => {
+        setOptions(initialOptionsRef.current);
+        setTooltipOpen(false);
+    };
+
+    const handleFilter = (inputValue: string) => {
+        if (inputValue.length === 0) {
+            setOptions(initialOptionsRef.current);
+            setTooltipOpen(false);
+            return;
+        }
+
+        const filteredOptions = initialOptionsRef.current.filter(({ label }) =>
+            String(label).toLowerCase().includes(inputValue.toLowerCase()),
+        );
+
+        setOptions(filteredOptions);
+        setTooltipOpen(filteredOptions.length === 0);
+    };
+
+    const handleClearSelected = () => setValue(undefined);
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipSuggest
+                type={type}
+                size={EComponentSize.MD}
+                label="Suggest label"
+                placeholder="Type to proceed"
+                noOptionsText="No matches found."
+                value={value}
+                options={options}
+                tooltipOpen={tooltipOpen}
+                onSelect={setValue}
+                onFilter={handleFilter}
+                targetProps={{ clearSelected: handleClearSelected }}
+                dropdownProps={{ onOpen: handleDropdownOpen }}
+            />
+        </div>
+    );
+};
+
+const typeOptions = Object.values(EChipType).map((type) => ({
+    value: type,
+    label: type.toUpperCase(),
+}));
+
+export const TypesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {typeOptions.map(({ value, label }) => (
+            <TypeItem key={value} type={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### Sizes
+
+`stories/Chips/examples/ChipSuggest/SizesExample.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { ChipSuggest, EComponentSize, type ISuggestFieldOption } from "@sberbusiness/triplex-next";
+import { mapFruitsToSuggestOptions, SUGGEST_STORY_FRUITS } from "./storyConstants";
+
+type SizeItemProps = {
+    size: EComponentSize;
+    label: string;
+};
+
+const initialOptions = mapFruitsToSuggestOptions([...SUGGEST_STORY_FRUITS]);
+
+const SizeItem = ({ size, label }: SizeItemProps) => {
+    const [value, setValue] = useState<ISuggestFieldOption>();
+    const [options, setOptions] = useState<ISuggestFieldOption[]>([]);
+    const [tooltipOpen, setTooltipOpen] = useState(false);
+    const initialOptionsRef = useRef<ISuggestFieldOption[]>(initialOptions);
+
+    const handleDropdownOpen = () => {
+        setOptions(initialOptionsRef.current);
+        setTooltipOpen(false);
+    };
+
+    const handleFilter = (inputValue: string) => {
+        if (inputValue.length === 0) {
+            setOptions(initialOptionsRef.current);
+            setTooltipOpen(false);
+            return;
+        }
+
+        const filteredOptions = initialOptionsRef.current.filter(({ label }) =>
+            String(label).toLowerCase().includes(inputValue.toLowerCase()),
+        );
+
+        setOptions(filteredOptions);
+        setTooltipOpen(filteredOptions.length === 0);
+    };
+
+    const handleClearSelected = () => setValue(undefined);
+
+    return (
+        <div>
+            <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{label}</div>
+            <ChipSuggest
+                size={size}
+                label="Suggest label"
+                placeholder="Type to proceed"
+                noOptionsText="No matches found."
+                value={value}
+                options={options}
+                tooltipOpen={tooltipOpen}
+                onSelect={setValue}
+                onFilter={handleFilter}
+                targetProps={{ clearSelected: handleClearSelected }}
+                dropdownProps={{ onOpen: handleDropdownOpen }}
+            />
+        </div>
+    );
+};
+
+const sizeOptions = Object.values(EComponentSize).map((size) => ({
+    value: size,
+    label: size.toUpperCase(),
+}));
+
+export const SizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+        {sizeOptions.map(({ value, label }) => (
+            <SizeItem key={value} size={value} label={label} />
+        ))}
+    </div>
+);
+```
+
+### States
+
+`stories/Chips/examples/ChipSuggest/StatesExample.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { ChipSuggest, EComponentSize, type ISuggestFieldOption } from "@sberbusiness/triplex-next";
+import { mapFruitsToSuggestOptions, SUGGEST_STORY_FRUITS } from "./storyConstants";
+
+const states = [
+    { id: "selected", label: "SELECTED" },
+    { id: "disabled", label: "DISABLED", targetProps: { disabled: true } },
+];
+
+export const StatesExample = () => {
+    const initialOptions = mapFruitsToSuggestOptions([...SUGGEST_STORY_FRUITS]);
+
+    const [valueSelected, setValueSelected] = useState<ISuggestFieldOption | undefined>(initialOptions[0]);
+    const [valueDisabled, setValueDisabled] = useState<ISuggestFieldOption>();
+    const [options, setOptions] = useState<ISuggestFieldOption[]>([]);
+    const [tooltipOpen, setTooltipOpen] = useState(false);
+    const initialOptionsRef = useRef<ISuggestFieldOption[]>(initialOptions);
+
+    const handleDropdownOpen = () => {
+        setOptions(initialOptionsRef.current);
+        setTooltipOpen(false);
+    };
+
+    const handleFilter = (inputValue: string) => {
+        if (inputValue.length === 0) {
+            setOptions(initialOptionsRef.current);
+            setTooltipOpen(false);
+            return;
+        }
+
+        const filteredOptions = initialOptionsRef.current.filter(({ label }) =>
+            String(label).toLowerCase().includes(inputValue.toLowerCase()),
+        );
+
+        setOptions(filteredOptions);
+        setTooltipOpen(filteredOptions.length === 0);
+    };
+
+    return (
+        <div style={{ display: "flex", flexDirection: "column", gap: 12 }}>
+            {states.map((state) => (
+                <div key={state.id}>
+                    <div style={{ marginBottom: 8, fontSize: 16, fontWeight: 700 }}>{state.label}</div>
+                    <ChipSuggest
+                        label="Suggest label"
+                        size={EComponentSize.MD}
+                        placeholder="Type to proceed"
+                        noOptionsText="No matches found."
+                        value={state.id === "selected" ? valueSelected : valueDisabled}
+                        options={options}
+                        tooltipOpen={tooltipOpen}
+                        onSelect={state.id === "selected" ? setValueSelected : setValueDisabled}
+                        onFilter={handleFilter}
+                        targetProps={{
+                            clearSelected: () =>
+                                state.id === "selected" ? setValueSelected(undefined) : setValueDisabled(undefined),
+                            ...state.targetProps,
+                        }}
+                        dropdownProps={{ onOpen: handleDropdownOpen }}
+                    />
+                </div>
+            ))}
+        </div>
+    );
+};
+```
+
+### WithNotificationIcon
+
+`stories/Chips/examples/ChipSuggest/WithNotificationIconExample.tsx`
+
+```tsx
+import React, { useRef, useState } from "react";
+import { ChipSuggest, EComponentSize, type ISuggestFieldOption } from "@sberbusiness/triplex-next";
+import { mapFruitsToOptionsWithNotification, SUGGEST_STORY_FRUITS_SHORT } from "./storyConstants";
+
+export const WithNotificationIconExample = () => {
+    const initialOptions = mapFruitsToOptionsWithNotification([...SUGGEST_STORY_FRUITS_SHORT], 2);
+
+    const [value, setValue] = useState<ISuggestFieldOption>();
+    const [options, setOptions] = useState<ISuggestFieldOption[]>([]);
+    const [tooltipOpen, setTooltipOpen] = useState(false);
+    const initialOptionsRef = useRef<ISuggestFieldOption[]>(initialOptions);
+
+    const handleDropdownOpen = () => {
+        setOptions(initialOptionsRef.current);
+        setTooltipOpen(false);
+    };
+
+    const handleFilter = (inputValue: string) => {
+        if (inputValue.length === 0) {
+            setOptions(initialOptionsRef.current);
+            setTooltipOpen(false);
+            return;
+        }
+
+        const filteredOptions = initialOptionsRef.current.filter(({ label }) =>
+            String(label).toLowerCase().includes(inputValue.toLowerCase()),
+        );
+
+        setOptions(filteredOptions);
+        setTooltipOpen(filteredOptions.length === 0);
+    };
+
+    return (
+        <ChipSuggest
+            value={value}
+            options={options}
+            tooltipOpen={tooltipOpen}
+            onSelect={setValue}
+            onFilter={handleFilter}
+            targetProps={{ clearSelected: () => setValue(undefined) }}
+            dropdownProps={{ onOpen: handleDropdownOpen }}
+            label="Suggest label"
+            placeholder="Type to proceed"
+            noOptionsText="No matches found."
+            size={EComponentSize.MD}
+        />
+    );
+};
+```
+

package/bundle/components/Dropdown.md

@@ -103,7 +103,7 @@ DropdownList.Background_Selected
 - `forwardRef` на `Dropdown`, `DropdownDesktop`, `DropdownListItem` — не убирать. Ref `Dropdown` указывает на корневой `<div>` десктопного меню, а в мобильном режиме — на контентный `<div>` `Puller` (`.puller`).
 - Меню в закрытом состоянии не рендерит ничего (`DropdownDesktop` возвращает `null`) — на это опираются потребители, монтирующие `Dropdown` безусловно.
 - Компонент управляемый: не добавлять внутренний state открытости, иначе сломается контракт `opened` / `setOpened`.
-- `Dropdown` рендерится в `document.body` через `Portal`. Смена контейнера портала — breaking change для потребителей, которые ищут меню в DOM.
+- `Dropdown` рендерится в `document.body` через `Portal`. Смена контейнера портала — breaking change для потребителей, которые ищут меню в DOM. Мобильная версия рендерится туда же, если не задан `pullerProps.renderContainer`.
 - Публичные barrel-экспорты `src/components/Dropdown/index.ts`, `desktop/index.ts` должны сохраняться: компонент используется внутри `ButtonDropdown`, `SelectField`, `SelectExtendedField`, `SuggestField`, `MultiselectField`, `TabsLine`, `DatePickerExtended`, `Chip`, `List`.
 - `DropdownList` проставляет дочерним элементам `active`, `size`, `ref`, `onMouseOver` и `onMouseOut` через `cloneElement` — эти props у `DropdownList.Item` нельзя считать «пользовательскими».
 - Пока десктопное меню открыто, на `document.body` висит класс блокировки скролла, а на документе — обработчики `wheel` и `keydown`. Снятие обработчиков в cleanup эффекта обязательно. Класс вешается только через `lockBodyScroll` (`src/utils/scroll/bodyScrollLock.ts`): прямой `classList.remove` снял бы блокировку при другом открытом меню.
@@ -194,6 +194,7 @@ DropdownList.Background_Selected
 | 2026-09-29 | Аудит симметрии `related` (TRI-156): из `related` убраны имена без строки в `docs/ai/ROADMAP.md` (`OverlayBase`) и потребители `SelectField` / `SelectExtendedField` / `SuggestField` / `MultiselectField` / `TabsLine` — по `docs/ai/CONTEXT.md` ссылка стоит с их стороны; добавлен `LoaderSmall` — контракт по рендеру в верную сторону. Пояснения к убранным именам сохранены прозой в «Связанные компоненты»; публичный API и поведение не затронуты. |
 | 2026-10-21 | **Breaking** (TRIPLEX-961): мобильная версия выделена в компонент `Puller`, `DropdownMobile*` удалены без алиасов. Prop `mobileViewProps` переименован в `pullerProps`, группы токенов `DropdownMobile` / `DropdownMobileList` — в `Puller` / `PullerList` (ключ `Content_Background` → `Body_Background`). |
 | 2026-10-23 | Исправлено: закрытие одного из открытых `DropdownDesktop` снимало блокировку скролла страницы при другом открытом меню. **Breaking:** класс блокировки на `body` переименован `.dropdownDesktopOverflowHidden` → `.dropdownDesktopScrollLock`. |
+| 2026-10-31 | Мобильная версия рендерится в `pullerProps.renderContainer`, если он задан, иначе в `document.body` (TRIPLEX-961). |
 
 ---