@gravity-ui/querieskit 1.0.4 → 1.2.0

package/plans/navigation-architecture.md

@@ -0,0 +1,262 @@
+# Архитектура навигации: концепты
+
+Обобщение серии планов по навигационному стеку (`QueriesNavigation` и модули `Navigation*`).
+Документ описывает **принципы и контракты**, а не пошаговые задачи: конкретные шаги реализации
+и разбор отдельных коммитов исчерпаны. Продуктовые/доменные привязки сознательно убраны —
+библиотека остаётся нейтральной к системе-источнику данных.
+
+## Состав стека
+
+По правилам `AGENTS.md` навигация разложена на три уровня:
+
+```text
+widgets/
+    QueriesNavigation           — готовый виджет: список кластеров/элементов + detail-панель
+modules/
+    NavigationHeader            — хлебные крошки, редактор пути, действия
+    ClustersList                — список кластеров
+    NavigationItemsList         — список элементов текущего пути (+ синтетическая строка «..»)
+    NavigationDetail            — панель детали: заголовок, вкладки, общий поиск
+    NavigationSchema            — вкладка со структурой полей (табличная)
+    NavigationPreview           — вкладка с данными (табличная)
+    NavigationMeta              — вкладка с метаданными (пары «ключ → значение»)
+components/
+    DataTable, LazyList, PathEditor, Breadcrumbs,
+    SearchWithButtons, FieldsSelector, FieldsSearchToolbar,
+    EmptyContent, ListSpinner
+helpers/
+    useVisibleColumns, useLoadMoreSentinel, getParentPath, getDefaultNavigationIcon
+types/
+    navigation.ts, pathEditor.ts — публичные контракты
+```
+
+Импорты идут строго в одну сторону: `widgets → modules → components`.
+
+## Базовые принципы
+
+1. **Нормализованные данные на входе.** Библиотека не парсит и не форматирует доменные
+   структуры источника. Значения приходят уже приведёнными к строке или `ReactNode`; схема,
+   строки данных и метаданные — плоские нормализованные объекты. Никаких зависимостей от
+   форматов сериализации конкретной системы.
+2. **Минимальный дефолт + расширяемость.** Каждый контракт содержит минимальный набор
+   обязательных полей, а расширение делается через индексную подпись (`[key: string]: unknown`)
+   и дженерик, протянутый до рендера. Консюмер добавляет свои поля и типобезопасно использует
+   их в кастомных колонках/строках.
+3. **Два уровня кастомизации.** Везде, где есть дефолтный вид, доступны оба варианта:
+   *добавление* к дефолту (`view.extraColumns`, `view.extraContent`) и *полная замена*
+   (`view.tableColumns`, `view.render`, `renderRowItem`). Дефолтные билдеры и дефолтные строки
+   экспортируются публично, чтобы сценарий «то же, что дефолт, плюс своё» не требовал
+   копирования кода.
+4. **Единая форма пропсов у модулей детали:** `{data, view?, ...сквозные}`, где `data` —
+   единственный источник правды по данным и состоянию (совпадает с публичным типом конфига,
+   который отдаёт резолвер), `view` — изолированная группа кастомизации отображения, а наверху
+   остаются только инфраструктурные пропсы (`search`, `className` и пр.). Это не даёт разрастись
+   плоскому списку пропсов и убирает ручную раскладку полей конфига в местах интеграции.
+5. **Controlled/uncontrolled для любого состояния.** Активная вкладка, значение поиска, набор
+   видимых колонок работают в обоих режимах: если проп задан — модуль полностью следует ему,
+   иначе держит внутреннее состояние. Внутренний стейт не обновляется в контролируемом режиме,
+   чтобы не заводить «мертвое» состояние.
+6. **Дженерики с дефолтом** вместо фиксированных типов — обратная совместимость сохраняется
+   для тех, кто не расширяет модель.
+
+## Модель данных
+
+```text
+NavigationLocation   = {cluster?, path?}
+NavigationCluster    = {id, title, icon?, color?, backgroundColor?, description?}
+NavigationItemKind   = 'folder' | 'file' | 'table' | 'link' | 'unknown'
+NavigationItem       = {path, title, icon?, kind?, hasChildren?, targetPathBroken?, disabled?}
+NavigationSortOrder  = 'asc' | 'desc'
+```
+
+Навигация «внутрь» против открытия детали определяется по `hasChildren`, а не по `kind`:
+элемент с детьми — переход по пути, без детей — открытие detail-панели.
+
+Виджет группирует сквозные настройки в конфиг-объекты (`header`, `search`, `sort`, `listState`,
+`detail`) вместо плоского списка пропсов.
+
+## Detail-панель и вкладки
+
+Набор вкладок не зашит в виджет, а вычисляется резолвером по элементу:
+
+```text
+ResolveNavigationDetail<T> = (item: T) => NavigationDetailConfig | undefined
+
+NavigationDetailConfig = {
+    tabs: NavigationDetailTab[];
+    defaultTab?: string;
+    hasSearch?: boolean;
+    searchPlaceholder?: string;
+    actions?: NavigationHeaderAction[];
+}
+
+NavigationDetailTab = {
+    id; title;
+    content?: ReactNode;                                  // статический контент
+    renderContent?: (ctx) => ReactNode;                   // приоритетнее content
+    hidden?; disabled?;
+}
+
+NavigationDetailTabRenderContext = {search, onSearchUpdate?, searchPlaceholder?}
+```
+
+Ключевые решения:
+
+- **Реестр по виду элемента.** Резолвер собирается из реестра `Partial<Record<NavigationItemKind,
+  factory>>` плюс `fallback`. Это даёт кастомное отображение для любого вида элемента, а не только
+  для табличного. Дефолт из коробки есть только для табличного вида; для остальных без
+  собственной фабрики показывается заглушка.
+- **Search-aware контент.** Статический `content` не может реагировать на поиск, поэтому у вкладки
+  есть `renderContent(ctx)`, получающий актуальное значение поиска, колбэк его обновления и
+  плейсхолдер. Правило: задан `renderContent` — используется он, иначе `content`.
+- **Кто рендерит строку поиска.** Табличные вкладки рендерят собственный тулбар (поиск + выбор
+  колонок), поэтому фабрика встроенных вкладок ставит `hasSearch: false`, а общий ряд поиска в
+  `NavigationDetail` остаётся механизмом для кастомных наборов вкладок. Побочный эффект —
+  на вкладках без тулбара (метаданные и т.п.) поиска нет, что и требовалось: поиск семантически
+  относится к полям, а не к метаданным.
+
+```mermaid
+flowchart TD
+    Item[NavigationItem] --> Resolver[resolve detail by kind]
+    Resolver --> Config[NavigationDetailConfig tabs]
+    Config --> Detail[NavigationDetail]
+    Detail -->|renderContent ctx| Tab[active tab]
+    Tab --> Schema[NavigationSchema]
+    Tab --> Preview[NavigationPreview]
+    Tab --> Meta[NavigationMeta]
+```
+
+## Табличные вкладки: структура полей и данные
+
+Обе вкладки построены на общем компоненте `DataTable` (скелетон-загрузка, пустые состояния) и
+имеют одинаковый каркас.
+
+Контракты:
+
+```text
+NavigationSchemaColumn = {
+    name: string;                                   // имя поля
+    type?: string;                                  // тип готовой строкой
+    sortOrder?: 'ascending' | 'descending';         // участие в ключе + направление
+    required?: boolean;
+    [key: string]: unknown;                         // расширение
+}
+NavigationSchemaConfig<TColumn>  = {columns: TColumn[]; loading?; loaded?; errorContent?}
+
+NavigationPreviewCell   = ReactNode                 // готовое к отображению значение
+NavigationPreviewRow    = Record<string, NavigationPreviewCell>
+NavigationPreviewConfig<TRow> = {columns: string[]; rows: TRow[]; loading?; loaded?; errorContent?}
+```
+
+Терминологическая тонкость: в схеме `columns` — это **строки** таблицы (поля описываемой
+сущности), а `view.tableColumns` — **колонки** отображающей таблицы. В превью `columns` задают
+состав и порядок колонок данных.
+
+Поведение модулей:
+
+- `view.tableColumns` заданы → используются как есть (полная замена вида).
+- Иначе строится дефолт билдером (`buildSchemaColumns` / `buildPreviewColumns`) и к нему
+  добавляются `view.extraColumns`. Билдеры экспортируются публично.
+- Данные фильтруются по значению поиска: в схеме — по имени и типу поля, в превью — по подстроке
+  в видимых колонках. Пустой результат поиска даёт состояние «ничего не найдено», пустые
+  исходные данные — «нет данных».
+- Индексная колонка отключена (`displayIndices: false`).
+
+### Тулбар: поиск + выбор видимых колонок
+
+Над таблицей рендерится общий тулбар (`FieldsSearchToolbar`): инпут поиска плюс кнопка выбора
+видимых полей в `endButtons`. Состав опций селектора берётся из отображаемых колонок; по умолчанию
+видимы все. Набор видимых колонок живёт в модуле (uncontrolled) через общий хук
+`useVisibleColumns`, но переопределяется извне парой `visibleColumns` / `onVisibleColumnsChange`
+плюс `defaultVisibleColumns` для стартового набора. Тулбар и сам селектор можно скрыть
+(`hideToolbar`, `hideFieldsSelector`).
+
+## Вкладка метаданных
+
+Модель — **массив групп пар «ключ → значение»**, а не таблица: для метаданных это семантически
+точнее.
+
+```text
+NavigationMetaItem  = {name: string; value: ReactNode; [key: string]: unknown}
+NavigationMetaGroup = {title?: string; items: NavigationMetaItem[]}
+NavigationMetaConfig = {groups: NavigationMetaGroup[]; loading?; loaded?; errorContent?}
+
+NavigationMetaViewConfig = {
+    render?: (data) => ReactNode;   // полная замена содержимого вкладки
+    extraContent?: ReactNode;       // блок после дефолтных групп
+}
+```
+
+Дефолт рендерит по блоку на группу: необязательный заголовок группы и список пар с прочерком
+на месте пустого значения. Полная замена вида (`view.render`) имеет приоритет над всем, включая
+обработку ошибок, — это осознанный «сырой» хук для консюмера. Тулбар и поиск на этой вкладке
+не рендерятся.
+
+## Переопределение строк списков
+
+Паттерн повторяет уже принятый в списке истории: модуль принимает необязательный
+`renderRowItem?: (data) => ReactNode`, и если он задан — используется вместо дефолтной строки.
+
+```text
+NavigationItemRowRenderData<T>    = {item: T; index; isActive; isParentRow}
+NavigationClusterRowRenderData<T> = {cluster: T; index; isActive}
+```
+
+Особенности:
+
+- Флаг `isParentRow` отличает синтетическую строку «..» (создаётся внутри модуля и не несёт
+  дополнительных полей `T`), чтобы консюмер мог отрендерить её иначе или оставить дефолт.
+- Строка «..» рендерится в двух местах — в основном списке и над пустым состоянием, — поэтому
+  кастомный рендер прокидывается и в пустое состояние.
+- Дженерики `TItem` / `TCluster` протянуты через виджет и модули (`items`, `onItemClick`,
+  `renderRowItem`), поэтому дополнительные поля видны в типах внутри рендера. Виджет из-за этого
+  объявляется обычной дженерик-функцией, а не через `React.FC`.
+- Дефолтные строки остаются в `internal/`, но реэкспортируются через `index.ts` модулей и
+  попадают в публичное API — для сценария «дефолт плюс своё».
+- На уровне виджета пропсы называются `renderNavigationItem` / `renderClusterItem`, на уровне
+  модулей — `renderRowItem` (консистентно с остальными списками библиотеки).
+
+## Состояния
+
+Единая схема для всех модулей детали:
+
+- `errorContent` — ранний возврат с текстом ошибки; в конфиге состояния списка ошибка сведена к
+  одному полю `error?: boolean | ReactNode` (`true` — дефолтное сообщение, `ReactNode` — свой
+  контент), чтобы не было двух полей под одно состояние.
+- `loading` без `loaded` — скелетон.
+- `loaded` при пустых данных — пустое состояние (`EmptyContent` с вариантом `no-data`).
+- Непустой поиск без совпадений — вариант `nothing-found`.
+
+## i18n
+
+Каждый модуль/виджет с собственным сценарием держит локализацию в `i18n/` (`en.json`, `ru.json`,
+`dicts.ts`, `index.ts`) и регистрирует keyset вида `qp:navigation-schema`, `qp:navigation-preview`,
+`qp:navigation-meta`. Ключи — по формату `<контекст>_<содержимое>` (`title_column-name`,
+`value_sort-ascending`, `value_empty`, `context_empty`, `field_detail-search-placeholder`,
+`action_configure-visible-fields`). Дублирование мелких ключей вроде `value_empty` между
+keyset'ами допустимо; общая логика вроде «прочерк вместо пустого значения» лучше жила бы в одном
+хелпере.
+
+## Публичный экспорт
+
+- `index.ts` каждого уровня явно реэкспортирует публичные единицы уровня (включая дефолтные
+  строки списков и дефолтные билдеры колонок).
+- Публичные типы контрактов лежат в `src/types/navigation.ts` и реэкспортируются из корневого
+  `index.ts`, чтобы консюмер мог типизировать свои данные.
+
+## Известные пробелы и договорённости
+
+Зафиксировано по итогам ревью навигационного стека; часть закрыта, часть осознанно оставлена.
+
+| Тема | Состояние |
+|------|-----------|
+| Источник действий detail-панели | Сведён к одному управляемому полю в конфиге панели; действия из резолвера домёрживаются внутри `NavigationDetail` |
+| Ошибка в состоянии списка | Сведена к одному полю `error?: boolean \| ReactNode` |
+| Внутренний стейт при controlled-режиме | Явно различаются controlled/uncontrolled для вкладки и поиска |
+| Пустая вкладка «просмотр» | Остаётся заглушкой в публичном API: либо скрывать, либо дать резолвер/рендер |
+| Точечное переопределение одной встроенной вкладки | Нельзя заменить одну вкладку, не пересобрав весь массив; есть только полная замена вида внутри модуля |
+| Контекст рендера вкладки | Содержит только поиск; элемент и локацию консюмер вынужден замыкать в фабрике |
+| Дефолты по видам элементов | Дефолтная фабрика есть только для табличного вида, остальные — заглушка до своей фабрики |
+| Дублирование каркаса трёх модулей детали | Повторяются рендер ошибки, сборка колонок и обёртка над таблицей; кандидаты на общий хелпер, общий тип `view` для табличных модулей и общий `isEmptyValue` |
+| Клик по строке «..» в непустом списке | Обработка «вверх» опирается на признак наличия детей у синтетической строки — поведение требует проверки |
+| Презентационные поля модели кластера | `color` / `backgroundColor` / `description` в данных дублируют возможности кастомного рендера строки |

package/plans/queries-navigation-architecture-review.md

@@ -0,0 +1,217 @@
+# Архитектурный анализ `QueriesNavigation` и дочерних компонент
+
+Область анализа: состояние кода после коммита `bcaa6e4c` (анализировалось текущее
+состояние рабочей директории — прямого доступа к git-diff в среде нет).
+
+Затронутые единицы:
+
+- Виджет [`QueriesNavigation`](src/widgets/QueriesNavigation/QueriesNavigation.tsx:51) + хелперы
+  [`createNavigationDetailResolver`](src/widgets/QueriesNavigation/helpers/createNavigationDetailResolver.ts:13),
+  [`createTableDetailConfig`](src/widgets/QueriesNavigation/helpers/createTableDetailConfig.tsx:45),
+  [`createEmptyDetailConfig`](src/widgets/QueriesNavigation/helpers/createEmptyDetailConfig.ts:5).
+- Модули: [`NavigationDetail`](src/modules/NavigationDetail/NavigationDetail.tsx:39),
+  [`NavigationHeader`](src/modules/NavigationHeader/NavigationHeader.tsx:15),
+  [`ClustersList`](src/modules/ClustersList/ClustersList.tsx:23),
+  [`NavigationItemsList`](src/modules/NavigationItemsList/NavigationItemsList.tsx:31),
+  [`NavigationSchema`](src/modules/NavigationSchema/NavigationSchema.tsx:36),
+  [`NavigationPreview`](src/modules/NavigationPreview/NavigationPreview.tsx:34),
+  [`NavigationMeta`](src/modules/NavigationMeta/NavigationMeta.tsx:25),
+  [`NavigationView`](src/modules/NavigationView/NavigationView.tsx:24).
+- Типы: [`src/types/navigation.ts`](src/types/navigation.ts:1).
+
+Общая оценка: архитектура зрелая и последовательная. Уровни `components → modules → widgets`
+выдержаны, generic-типизация сквозная, controlled/uncontrolled паттерн реализован. Ниже —
+конкретные замечания, сгруппированные по 7 пунктам задачи.
+
+---
+
+## 1. Соответствие стилю проекта и Gravity UI
+
+Что хорошо:
+
+- Везде используется `bem-cn-lite` с префиксом `qp-*`, компоновка через `Flex`, spacing через
+  `gap`, что совпадает с остальным проектом.
+- Detail-табы построены на `SegmentedRadioGroup`, meta-скелетоны на `Skeleton`, секции на
+  `Disclosure` — всё нативные примитивы Gravity UI, без самописных аналогов.
+
+Замечания:
+
+- **Инлайн-стили вместо SCSS/токенов в продакшн-коде.** В [`buildSchemaColumns`](src/modules/NavigationSchema/helpers/buildSchemaColumns.tsx:22)
+  используется `style={{display:'inline-flex', alignItems:'center', gap:4}}`. По стилю проекта
+  раскладка/отступы задаются через `Flex gap` или `--g-spacing-*` в `.scss`. Инлайн-`gap:4` стоит
+  заменить на `Flex gap` или CSS-класс с токеном. (Инлайн-стили и текстовые заглушки в сторибуках
+  оставляем как есть — для демо это допустимо.)
+- **Пустой `title: ''` в конфиге таба.** В [`createEmptyDetailConfig`](src/widgets/QueriesNavigation/helpers/createEmptyDetailConfig.ts:9)
+  создаётся таб с пустым заголовком — формально валидация i18n не срабатывает (строка не идёт
+  через `t`), но семантически это «фейковый» таб только ради контейнера. См. п.4.
+
+## 2. Размещение новых компонент по уровням
+
+В целом соответствует правилам из [`AGENTS.md`](AGENTS.md:1):
+
+- Списковые/скомпонованные блоки (`ClustersList`, `NavigationItemsList`, `NavigationDetail`,
+  `NavigationSchema/Preview/Meta/View`) корректно лежат в `modules`.
+- Внутренние части (`ClusterRow`, `NavigationItemRow`, `NavigationDetailTabs`,
+  `NavigationViewSectionItem`) — в `internal/`, что верно.
+- Хелперы конфигов (`createTableDetailConfig` и пр.) — на уровне виджета, т.к. содержат
+  widget-specific i18n. Это оправданно.
+
+Замечания:
+
+- **`ClusterRow` и `NavigationItemRow` реэкспортируются как публичные из
+  [`src/modules/index.ts`](src/modules/index.ts:17), но физически лежат в `internal/`.**
+  Противоречие: либо это публичный API (тогда вынести из `internal/` на уровень модуля или в
+  `components`, т.к. они атомарны и переиспользуются в сторибуке `CustomRows`), либо это внутренняя
+  деталь (тогда убрать из barrel). Судя по использованию в кастомном рендере — это публичный
+  контракт, и их правильнее поднять до `components` (у них стабильный props-контракт, отдельное
+  использование есть).
+- **`NavigationDetailTabs` в `internal/` — ок**, но у него нет `index.ts` и он импортируется по
+  прямому пути. По правилу «каждая единица — папка с `index.ts`» это допустимо для internal, но
+  стоит свериться на консистентность с другими internal-частями.
+- **`NavigationDetail` не экспортирует `NavigationDetailConfig`-фабрики** из своего `index.ts`,
+  тогда как связанные типы живут в `types/navigation`. Это нормально, но стоит проверить, что
+  потребитель может собрать конфиг детали без импортов из `widgets`.
+
+## 3. Кандидаты на вынос в хелперы
+
+- **`visibleActions`-рендер дублируется.** Логика «отфильтровать по `hidden` → отрисовать список
+  `Button view=flat size=s` с `title/aria-label/disabled/qa`» повторяется в
+  [`NavigationHeader`](src/modules/NavigationHeader/NavigationHeader.tsx:22) и
+  [`NavigationViewSectionItem`](src/modules/NavigationView/internal/NavigationViewSectionItem.tsx:29).
+  Кандидат на общий компонент `ActionButtons`/`NavigationActions` (в `components`) с generic-типом
+  экшена, чтобы `NavigationHeaderAction` и `NavigationViewSectionAction` покрывались одним рендером.
+- **Единый тип «action».** См. п.6 — `NavigationHeaderAction` и `NavigationViewSectionAction`
+  отличаются только сигнатурой `onClick`. Можно ввести generic `NavigationAction<TCtx>`.
+- **`getInitialTab` / фильтр видимых табов.** В [`NavigationDetail`](src/modules/NavigationDetail/NavigationDetail.tsx:30)
+  `config.tabs.filter(t => !t.hidden)` считается дважды (в `getInitialTab` и в `useMemo`). Можно
+  вынести хелпер `getVisibleTabs`/`resolveInitialTab` в `NavigationDetail/helpers/`.
+- **SKELETON-заглушка.** Блок «N `Skeleton` в колонку» полностью повторяется в
+  [`NavigationMeta`](src/modules/NavigationMeta/NavigationMeta.tsx:47) и
+  [`NavigationView`](src/modules/NavigationView/NavigationView.tsx:40) (одна и та же
+  `SKELETON_ROWS_COUNT = 4`). Кандидат на общий `ListSkeleton`/`SkeletonRows` в `components`.
+
+## 4. Удобство использования, гибкость переопределения и типизация
+
+Сильные стороны:
+
+- Сквозные дженерики `<TItem, TCluster>`, `<TColumn>`, `<TRow>` дают типобезопасное расширение
+  строк/колонок.
+- Паттерн `renderRowItem` + fallback на дефолтный ряд (`ClustersList`, `NavigationItemsList`) —
+  гибкий и предсказуемый.
+- Controlled/uncontrolled в [`NavigationDetail`](src/modules/NavigationDetail/NavigationDetail.tsx:51)
+  реализован аккуратно (search и activeTab независимо).
+- `view`-проп у detail-модулей (`tableColumns`/`extraColumns`/`render`) — хороший механизм
+  переопределения таблиц.
+
+Замечания:
+
+- **Дженерик теряется в detail-резолверах.** В [`createTableDetailConfig`](src/widgets/QueriesNavigation/helpers/createTableDetailConfig.tsx:19)
+  резолверы типизированы как `NavigationSchemaResolver<T>`, но возвращают `NavigationSchemaConfig`
+  без `<TColumn>`. Из-за этого `extraColumns`-типизация кастомных колонок в конфиге таблицы теряется.
+  Стоит пробросить `TColumn`/`TRow` до `NavigationSchema data`.
+- **`createEmptyDetailConfig` через `React.createElement`.** Файл `.ts`, поэтому используется
+  `createElement` вместо JSX. Логичнее переименовать в `.tsx` и вернуть JSX, а «пустое состояние»
+  моделировать не фейковым табом с `title:''`, а отдельной веткой в `NavigationDetail`
+  (например, `config.empty?: ReactNode` или рендер `EmptyContent`, когда `tabs` пуст).
+- **`[key: string]: unknown` в типах.** `NavigationSchemaColumn` и `NavigationMetaItem` имеют
+  индексную сигнатуру `[key: string]: unknown`. Это ослабляет типизацию расширений (лучше решать
+  через дженерик `T extends ...`, который и так есть). Возможная избыточность — см. п.6.
+- **`resolvedDetailActions = detailActions ?? actions`** в
+  [`QueriesNavigation`](src/widgets/QueriesNavigation/QueriesNavigation.tsx:86): fallback header-экшенов
+  на detail неочевиден. Стоит задокументировать поведение в типе `NavigationDetailPanelConfig`.
+
+## 5. Дублирование кода
+
+- **`buildPreviewColumns` и `buildViewColumns` идентичны.**
+  [`buildPreviewColumns`](src/modules/NavigationPreview/helpers/buildPreviewColumns.tsx:5) и
+  [`buildViewColumns`](src/modules/NavigationView/helpers/buildViewColumns.tsx:5) — побайтово
+  одинаковая функция (маппинг `columns → Column` с заглушкой `value_empty`). Разнесены только по
+  разным i18n. Кандидат на общий хелпер (например, `buildStringColumns` в `src/helpers/` или
+  `components`), принимающий функцию перевода/`emptyText`.
+- **Логика «пустого значения» повторяется трижды.** `value === undefined || null || ''` есть в
+  `buildPreviewColumns`, `buildViewColumns`, [`buildMetaGroups`](src/modules/NavigationMeta/helpers/buildMetaGroups.tsx:15)
+  (`isEmptyValue`). Вынести единый `isEmptyValue` в `src/helpers/`.
+- **Скелетоны и action-рендер** — дублирование описано в п.3.
+- **Блок `errorContent → <Text color="danger">`** повторяется в Schema/Preview/Meta/View. Можно
+  ввести общий `DetailError`/использовать существующий паттерн вывода ошибки.
+
+## 6. Оценка новых типов (избыточность/дублирование)
+
+Файл [`src/types/navigation.ts`](src/types/navigation.ts:1) большой и в целом хорошо
+структурирован, но есть избыточность:
+
+- **`NavigationViewRow = NavigationPreviewRow`** ([`строка 109`](src/types/navigation.ts:109)) — псевдоним.
+  А `NavigationViewConfig`/`NavigationPreviewConfig` очень близки (secions vs rows). Стоит оценить,
+  не свести ли preview к частному случаю view, либо явно задокументировать, что это осознанно разные
+  сущности.
+- **`NavigationHeaderAction` vs `NavigationViewSectionAction`** — отличаются только типом аргумента
+  `onClick` (`NavigationLocation` против `NavigationViewSection`). Кандидат на generic
+  `NavigationAction<TArg>` c общими полями `id/title/content/hidden/disabled/qa`.
+- **Четыре почти одинаковых `*Config`** (`Schema/Preview/Meta/View`) с общими полями
+  `loading/loaded/errorContent`. Можно ввести базовый `NavigationAsyncConfig` и расширять его
+  (`& {columns}`, `& {rows}`, `& {groups}`, `& {sections}`).
+- **`ResolveNavigationDetail` vs `NavigationDetailConfigFactory`** — обе `(item) => Config`,
+  различие только в `| undefined`. Возможно, достаточно одного типа с опциональностью на месте
+  использования.
+- **`NavigationPreviewCell = ReactNode` и `NavigationMetaValue = ReactNode`** — псевдонимы одного
+  и того же. Либо один общий `NavigationCellValue`, либо убрать псевдонимы.
+- **Индексные сигнатуры `[key: string]: unknown`** в `NavigationSchemaColumn`/`NavigationMetaItem`
+  дублируют возможности дженериков — стоит выбрать один механизм расширения.
+
+## 7. Оценка сторибуков (избыточность, объединение)
+
+Наблюдения:
+
+- **Повторяющиеся `Loading/Empty/Error`-стори у 4 detail-модулей.** У Schema, Preview, Meta, View
+  практически идентичные state-стори. Их можно оставить (они полезны для autodocs), но mock-данные
+  дублируются между сторибуками и [`QueriesNavigation.stories`](src/widgets/QueriesNavigation/QueriesNavigation.stories.tsx:148)
+  (`TABLE_SCHEMA_COLUMNS`, `TABLE_PREVIEW_ROWS`, `TABLE_META_GROUPS`, `TABLE_VIEW_SECTIONS`
+  повторяют данные модульных сторибуков). Кандидат на общий `story/mockData.ts`
+  (как уже сделано в `DashboardCharts/story/mockData.ts` и `ChartEditor/story/mockData.ts`).
+- **`CustomColumns`-стори у Schema и Preview идентичны** (тот же `lock`-паттерн с `Label`+`LockIcon`).
+  Можно объединить логически или вынести общий пример.
+- **Кандидат на объединение в одно демо.** Отдельные `Loading`/`Empty`/`Error` можно объединить в
+  одну «States»-стори через controls/args-матрицу, оставив `Default` и `Custom*` отдельными. Это
+  сократит число стори без потери покрытия.
+- **Несогласованность с гайдом структуры сторибуков.** Часть модулей (`ChartEditor`,
+  `DashboardCharts`) держат стори в подпапке `story/` с `mockData.ts`, а Navigation-модули — рядом
+  с компонентом. Стоит привести к единому подходу (вероятно `story/` + вынесенные моки).
+- **Мелочь:** опечатки в mock-данных `QueriesNavigation.stories` (`tesdting`, `Prestable`) —
+  косметика, но заметна в autodocs.
+
+---
+
+## Приоритизация правок (для последующей реализации в Code mode)
+
+Высокий приоритет (дублирование/типобезопасность):
+
+1. Объединить [`buildPreviewColumns`](src/modules/NavigationPreview/helpers/buildPreviewColumns.tsx:5)
+   и [`buildViewColumns`](src/modules/NavigationView/helpers/buildViewColumns.tsx:5) в один хелпер.
+2. Вынести общий `isEmptyValue` в `src/helpers/`.
+3. Пробросить дженерики `TColumn`/`TRow` в резолверах
+   [`createTableDetailConfig`](src/widgets/QueriesNavigation/helpers/createTableDetailConfig.tsx:45).
+4. Решить статус `ClusterRow`/`NavigationItemRow`: поднять в `components` либо убрать из
+   публичного barrel.
+
+Средний приоритет (переиспользование/типы):
+
+5. Ввести generic `NavigationAction<TArg>` и общий рендер экшенов
+   (`NavigationHeader` + `NavigationViewSectionItem`).
+6. Ввести базовый `NavigationAsyncConfig` (`loading/loaded/errorContent`) и общий `SkeletonRows`.
+7. Убрать псевдонимы-дубликаты типов (`NavigationPreviewCell`/`NavigationMetaValue`,
+   `NavigationViewRow`) и пересмотреть индексные сигнатуры.
+
+Низкий приоритет (стиль/сторибуки):
+
+8. Вынести mock-данные detail-модулей в общий `story/mockData.ts`, объединить state-стори,
+   унифицировать расположение сторибуков.
+9. Заменить инлайн-стиль `gap:4` в продакшн-хелпере [`buildSchemaColumns`](src/modules/NavigationSchema/helpers/buildSchemaColumns.tsx:22)
+   на `Flex gap` / CSS-класс с токеном (сторибуков не касается).
+10. Переосмыслить `createEmptyDetailConfig` (JSX + отдельная ветка пустого состояния вместо
+    таба с `title:''`).
+
+---
+
+Примечание по процессу: анализ выполнен по текущему состоянию файлов. Если нужно строго сверить
+именно diff коммита `bcaa6e4c` (какие строки добавлены/удалены), это удобнее сделать в среде с
+доступом к `git`/`arc` — тогда часть замечаний можно будет привязать к конкретным ханкам.

package/src/components/AddChartButton/AddChartButton.scss

@@ -0,0 +1,12 @@
+.qp-add-chart-button {
+    flex-shrink: 0;
+
+    &__menu {
+        inline-size: 360px;
+        max-inline-size: calc(100vw - var(--g-spacing-8));
+    }
+
+    &__option-icon {
+        color: var(--g-color-text-brand);
+    }
+}

package/src/components/AddChartButton/AddChartButton.stories.tsx

@@ -0,0 +1,34 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {action} from 'storybook/actions';
+
+import {AddChartButton} from './AddChartButton';
+
+const meta: Meta<typeof AddChartButton> = {
+    title: 'Components/AddChartButton',
+    component: AddChartButton,
+    tags: ['autodocs'],
+    parameters: {
+        layout: 'padded',
+    },
+    args: {
+        onSelect: action('onSelect'),
+        onOpenToggle: action('onOpenToggle'),
+    },
+};
+
+export default meta;
+type Story = StoryObj<typeof AddChartButton>;
+
+export const Default: Story = {};
+
+export const Opened: Story = {
+    args: {
+        open: true,
+    },
+};
+
+export const CustomText: Story = {
+    args: {
+        text: 'Add visualization',
+    },
+};