@gravity-ui/querieskit 1.3.0 → 1.3.1

package/eslint.config.mjs

@@ -1,53 +0,0 @@
-// eslint.config.mjs
-import baseConfig from "@gravity-ui/eslint-config";
-import prettierConfig from "@gravity-ui/eslint-config/prettier";
-import reactConfig from "@gravity-ui/eslint-config/react";
-import typescriptEslint from "@typescript-eslint/eslint-plugin";
-
-export default [
-    {
-        ignores: [
-            "build/**",
-            "storybook-static/**",
-            "node_modules/**",
-            "dist/**",
-            "*.config.mjs",
-        ],
-    },
-    ...baseConfig,
-    ...prettierConfig,
-    ...reactConfig,
-    {
-        settings: {
-            "import/resolver": {
-                typescript: true,
-                node: true
-            }
-        },
-        plugins: {
-            "@typescript-eslint": typescriptEslint,
-        },
-        rules: {
-            curly: "off",
-            "@typescript-eslint/explicit-member-accessibility": [
-                "error",
-                {
-                    accessibility: "explicit",
-                    overrides: {
-                        accessors: "explicit",
-                        constructors: "no-public",
-                        methods: "explicit",
-                        properties: "off",
-                        parameterProperties: "explicit",
-                    },
-                },
-            ],
-        },
-    },
-    {
-        files: ["src/stories/**/*.{ts,tsx}"],
-        rules: {
-            "import/no-extraneous-dependencies": "off",
-        },
-    },
-];

package/plans/i18n-rules.md

@@ -1,116 +0,0 @@
-# Правила работы с i18n
-
-Подробные правила именования кейсетов и ключей для агентов, работающих с локализацией в `@gravity-ui/querieskit`. Краткая выжимка — в разделе [`## i18n`](../AGENTS.md) файла `AGENTS.md`, здесь — полный справочник с примерами.
-
-## Техническая структура
-
-Каждый виджет хранит свою локализацию в подпапке `i18n/`:
-
-```text
-widgets/
-  WidgetName/
-    i18n/
-      en.json
-      ru.json
-      dicts.ts
-      index.ts
-```
-
-- [`dicts.ts`](../src/widgets/QueriesHistory/i18n/dicts.ts:1) — собирает словари по языкам: `export default {en, ru}`.
-- [`index.ts`](../src/widgets/QueriesHistory/i18n/index.ts:1) — регистрирует кейсет через [`addI18Keysets`](../src/i18n/index.ts:11) и экспортирует типизированную функцию `t`:
-
-  ```ts
-  import {addI18Keysets} from '../../../i18n';
-
-  import dicts from './dicts';
-
-  export default addI18Keysets('qp:widget-name', dicts);
-  ```
-
-- Имя кейсета всегда начинается с префикса `qp:` (namespace библиотеки) — тип `addI18Keysets` требует `` `qp:${string}` ``.
-- В компоненте используется как `i18n('key_name')`, см. [`QueriesHistory.tsx`](../src/widgets/QueriesHistory/QueriesHistory.tsx:41).
-- `modules` и `components`, у которых есть собственный переиспользуемый сценарий, также могут заводить свою папку `i18n/` по этой же схеме — правило применяется на всех трёх уровнях (`components` / `modules` / `widgets`).
-
-## Кейсеты
-
-Кейсеты делятся на 4 типа:
-
-1. **Общие для всей системы** — используются во многих разделах, часто повторяются. Например: `common`, `common.units`, `common.actions`.
-2. **Общие для раздела** — часто повторяются на страницах одного раздела. Например: `queries.common`.
-3. **Специфичные для страниц раздела**. Например: `queries.editor`.
-4. **Для переиспользуемых компонентов**. Например: `queries.status-icon`.
-
-В контексте `qp:` namespace эквивалент раздела — виджет/модуль/компонент, например `qp:queries-history`, `qp:queries-history.history-list`.
-
-### Рекомендации по кейсетам
-
-- Для каждого кейсета обязательно указывать его контекст (для чего он и где используется — в комментарии рядом с регистрацией или в PR/документации).
-- Не злоупотреблять гранулярностью: не создавать кейсет на несколько ключей без необходимости — объединять с существующим кейсетом раздела/виджета.
-- Для секций или попапов одного раздела не заводить несколько кейсетов — использовать общий кейсет раздела.
-- Называть кейсеты как можно короче: не `queries.history.filters`, а `queries.filters`.
-- Для переиспользуемых компонентов не начинать нейминг со слова `component.` — начинать с раздела/сущности, к которой относится компонент: не `component.queries.status-icon`, а `queries.status-icon`.
-
-## Ключи
-
-Формат: `<контекст-элемента>_<содержание-текста>`.
-
-- Контекст стараться брать из готового списка ниже; если не подходит — придумать свой короткий и понятный; если контекст определить не получается — не писать его вовсе.
-- Не использовать контекст `label_`.
-- Содержание текста в имени должно однозначно и лаконично отражать смысл (для длинных фраз — краткое описание сути, а не дословный текст).
-
-### Примеры
-
-| Текст | Ключ |
-|---|---|
-| Нотификация, заголовок: «Не удалось выполнить запрос» | `alert_query-execution-error` |
-| Нотификация, сообщение: «Запрос выполняется дольше обычного, результат появится позже» | `alert_query-long-running` |
-| «История запросов будет очищена через 30 дней после создания» | `alert_history-retention-notice` |
-| Описание секции про сохранение и повторный запуск сценариев запросов | `context_reuse-saved-queries` |
-| Активное действие «Повторить запрос» | `action_query-rerun` |
-
-### Рекомендуемые контексты
-
-- `context` — контекстная информация: подсказки, абзацы с пояснением назначения раздела/элемента.
-- `alert` — обратная связь системы: нотификации по завершению запроса к серверу, предупреждения в обзоре ресурса (например, скорая блокировка аккаунта).
-- `action` — действия пользователя: кнопки, ссылки, пункты действий в таблице, действия в правом верхнем углу обзора ресурсов.
-- `field` — названия полей ресурса: колонки таблиц, формы редактирования, обзор.
-- `title` — заголовок секции, страницы, попапа, компонента подтверждения (confirm), пункт меню.
-- `confirm` — призыв к действию, например описание подтверждения операции.
-- `value` — значения radio/switch, статус или другое переводимое значение поля.
-
-## Технические префиксы
-
-- **`raw_`** — если нужно избежать прогона текста через типограф.
-- **`md_`** — если нужно выделить текст жирным/курсивом или добавить ссылку. Текст прогоняется через YFM и превращается в HTML-теги; на стороне компонента нужно подключать через `Yfm`-компонент. Атрибуты ссылки задаются так:
-
-  ```json
-  {
-      "md_query-syntax-help": "Подробнее о синтаксисе смотрите в [документации](https://example.com/docs/query-syntax){target=_blank rel=\"noreferrer noopener\"}"
-  }
-  ```
-
-- **Не использовать HTML-разметку в тексте напрямую** — для форматирования есть только `md_` + YFM.
-
-## Допустимые символы
-
-Каждый текст проверяется на отсутствие неразрешённых символов:
-
-```ts
-/**
- * [\u0400-\u04ff] – Кириллица
- * \u00a0 – Неразрывный пробел
- */
-export const SAFE_SYMBOLS_REGEX = /^[a-z0-9\u0400-\u04ff[\](){}<>!@#$%^&*~_\-−–—+='"`«»„”‘’“?.,:;|\\/ ₽™®©№\u00a0]*$/i;
-```
-
-Перед добавлением новых строк в `en.json`/`ru.json` проверять их на соответствие этому регулярному выражению.
-
-## Чек-лист при добавлении новых текстов
-
-1. Определить, в какой кейсет должен попасть ключ (существующий кейсет виджета/модуля/компонента или общий — не плодить новые без необходимости).
-2. Подобрать короткий контекст ключа из списка (`context`, `alert`, `action`, `field`, `title`, `confirm`, `value`) либо не указывать его, если не подходит.
-3. Сформулировать лаконичное однозначное содержание в имени ключа (kebab-case после `_`).
-4. Добавить перевод в `en.json` и `ru.json` одновременно.
-5. Проверить текст на допустимые символы (`SAFE_SYMBOLS_REGEX`).
-6. Если нужна разметка (ссылка/жирный/курсив) — использовать `md_`-префикс и YFM, не HTML.
-7. Если нужно отключить типограф — использовать `raw_`-префикс.

package/plans/navigation-architecture.md

@@ -1,262 +0,0 @@
-# Архитектура навигации: концепты
-
-Обобщение серии планов по навигационному стеку (`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-history-structure.md

@@ -1,143 +0,0 @@
-# План трёхуровневой структуры QueriesKit
-
-## Контекст
-
-Текущая структура держит почти всё внутри [`src/components/QueriesHistory`](src/components/QueriesHistory). Из-за этого [`QueriesHistory`](src/components/QueriesHistory/QueriesHistory.tsx:28) одновременно выглядит и как публичный виджет, и как контейнер для всех внутренних частей: [`HistoryList`](src/components/QueriesHistory/HistoryList.tsx:26), [`HistoryHeader`](src/components/QueriesHistory/HistoryHeader/HistoryHeader.tsx:13), [`HistoryRow`](src/components/QueriesHistory/HistoryRow/HistoryRow.tsx:17), [`HistoryRowHeader`](src/components/QueriesHistory/HistoryRow/HistoryRowHeader.tsx:19), [`HistoryDuration`](src/components/QueriesHistory/HistoryRow/HistoryDuration.tsx), [`QueryStatusIcon`](src/components/QueriesHistory/HistoryRow/QueryStatusIcon.tsx:27), [`HistoryRowContent`](src/components/QueriesHistory/HistoryRowContent.tsx:1), [`HistoryGroupHeader`](src/components/QueriesHistory/HistoryGroupHeader.tsx:1).
-
-Библиотека `@gravity-ui/querieskit` находится в начале развития: сейчас в ней один публичный виджет ([`QueriesHistory`](src/components/QueriesHistory/QueriesHistory.tsx:28)), но в дальнейшем планируется добавление ещё многих виджетов. Это подтверждает целесообразность трёхуровневого деления сразу, а не откладывания его "на потом".
-
-Также обнаружен реальный баг: [`src/components/index.ts`](src/components/index.ts:1) содержит самоссылающийся экспорт `export * from '.'`, который не реэкспортирует ничего полезного из [`src/components/QueriesHistory/index.ts`](src/components/QueriesHistory/index.ts:1). Это нужно исправить в рамках реструктуризации.
-
-Цель — сделать структуру библиотеки читаемой для потребителей: отдельно базовые building blocks, отдельно сборки из них, отдельно готовые виджеты — с расчётом на рост числа виджетов.
-
-## Модель трёх уровней
-
-1. [`src/components`](src/components) — базовые атомарные или малые доменные компоненты.
-2. [`src/modules`](src/modules) — компоненты, собирающие несколько базовых компонентов в переиспользуемый сценарный блок внутри одного виджета.
-3. [`src/widgets`](src/widgets) — готовые продуктовые виджеты, которые можно поставить в приложение как цельный feature.
-
-### Почему `modules`, а не `compositions`/`blocks`
-
-- `compositions` точно передаёт смысл, но менее привычно в JS/React-экосистеме.
-- `blocks` короче и привычнее для UI-библиотек в целом, но в этом проекте уже активно используется BEM через `bem-cn-lite` (`const block = cn('qp-history-row')` в [`HistoryRow.tsx`](src/components/QueriesHistory/HistoryRow/HistoryRow.tsx:15), [`HistoryList.tsx`](src/components/QueriesHistory/HistoryList.tsx:24) и др.) — термин "block" уже занят под BEM-блок в CSS-классах, и папка `src/blocks` создавала бы двусмысленность.
-- `modules` — нейтральный и привычный термин, не конфликтует с BEM-терминологией проекта и не тянет за собой чужую методологию (Atomic Design, Feature-Sliced Design), названия которой не совсем подходят под текущие сущности.
-
-Главное ограничение: не нужно автоматически выносить каждую маленькую внутреннюю часть в публичный атом. Атом должен попадать в [`src/components`](src/components), только если потребитель библиотеки действительно может использовать его отдельно и если у него есть стабильный props-контракт.
-
-## Классификация текущих компонентов
-
-### Базовые компоненты
-
-В [`src/components`](src/components) стоит держать малые компоненты, которые не управляют большим сценарием:
-
-- [`QueryStatusIcon`](src/components/QueriesHistory/HistoryRow/QueryStatusIcon.tsx:27) — хороший кандидат в base component.
-- [`QueryDuration`](src/components/QueryDuration/QueryDuration.tsx) — base component для отображения длительности запроса. Переименован из `HistoryDuration` — может переиспользоваться за пределами `QueriesHistory`. Использует хук [`useQueryDuration`](src/components/QueryDuration/useQueryDuration.ts), который лежит рядом.
-- [`HistoryRowMenu`](src/components/QueriesHistory/HistoryRow/HistoryRowMenu.tsx) — скорее малый доменный component, но его можно оставить рядом с [`HistoryRow`](src/modules/HistoryRow), если самостоятельного использования почти нет.
-- [`HistoryRowHeader`](src/components/QueriesHistory/HistoryRow/HistoryRowHeader.tsx:19) — пограничный случай: если header нужен отдельно, он может быть component; если только как часть строки, лучше держать внутри [`src/modules/HistoryRow`](src/modules/HistoryRow).
-- [`HistoryGroupHeader`](src/components/QueriesHistory/HistoryGroupHeader.tsx:1) — маленький визуальный компонент заголовка группы, физически сейчас лежит в корне `QueriesHistory/`, используется только из [`HistoryRowContent`](src/components/QueriesHistory/HistoryRowContent.tsx:1).
-
-### Модули
-
-В [`src/modules`](src/modules) стоит держать блоки, которые собирают несколько components и задают сценарий взаимодействия внутри конкретного виджета:
-
-- [`HistoryHeader`](src/components/QueriesHistory/HistoryHeader/HistoryHeader.tsx:13) — сборка поиска, фильтра и действий над историей.
-- [`HistoryList`](src/components/QueriesHistory/HistoryList.tsx:26) — сборка списка, групп, строк, selection, editing и render pipeline. Включает внутренние [`HistoryRowContent`](src/components/QueriesHistory/HistoryRowContent.tsx:1) и хелпер [`prepareRowData`](src/components/QueriesHistory/helpers/prepareRowData.ts).
-- [`HistoryRow`](src/components/QueriesHistory/HistoryRow/HistoryRow.tsx:17) — сборка строки из статуса, title/header, duration, metadata, checkbox и меню.
-
-### Виджеты
-
-В [`src/widgets`](src/widgets) стоит держать законченные feature-блоки:
-
-- [`QueriesHistory`](src/components/QueriesHistory/QueriesHistory.tsx:28) — готовый виджет истории запросов, который собирает [`HistoryHeader`](src/modules/HistoryHeader), [`HistoryList`](src/modules/HistoryList), i18n и widget-level настройки.
-- В будущем сюда же будут добавляться новые виджеты библиотеки (например, редактор запроса, результат запроса и т.п.) по той же трёхуровневой схеме.
-
-## Рекомендуемая целевая структура
-
-```text
-src/
-  components/
-    QueryStatusIcon/
-      QueryStatusIcon.tsx
-      QueryStatusIcon.scss
-      index.ts
-    QueryDuration/
-      QueryDuration.tsx
-      QueryDuration.scss
-      useQueryDuration.ts
-      index.ts
-    HistoryGroupHeader/
-      HistoryGroupHeader.tsx
-      HistoryGroupHeader.scss
-      index.ts
-  modules/
-    HistoryHeader/
-      HistoryHeader.tsx
-      internal/
-        HistorySearch.tsx
-        HistoryFilter.tsx
-      index.ts
-    HistoryRow/
-      HistoryRow.tsx
-      HistoryRowHeader.tsx
-      HistoryRowMenu.tsx
-      HistoryRow.scss
-      index.ts
-    HistoryList/
-      HistoryList.tsx
-      internal/
-        HistoryRowContent.tsx
-      helpers/
-        prepareRowData.ts
-      index.ts
-  widgets/
-    QueriesHistory/
-      QueriesHistory.tsx
-      i18n/
-      index.ts
-  types/
-    history.ts
-  helpers/
-    time.ts
-  index.ts
-```
-
-## Почему не слишком мелко
-
-Это не слишком мелко, потому что деление идёт по уровню ответственности:
-
-- [`src/components`](src/components) отвечает за малые визуальные building blocks.
-- [`src/modules`](src/modules) отвечает за переиспользуемые сценарные блоки внутри виджета.
-- [`src/widgets`](src/widgets) отвечает за готовые feature-пакеты.
-
-Но будет слишком мелко, если вынести [`HistorySearch`](src/components/QueriesHistory/HistoryHeader/HistorySearch.tsx:16), [`HistoryFilter`](src/components/QueriesHistory/HistoryHeader/HistoryFilter.tsx:16), [`HistoryRowHeader`](src/components/QueriesHistory/HistoryRow/HistoryRowHeader.tsx:19), [`HistoryRowMenu`](src/components/QueriesHistory/HistoryRow/HistoryRowMenu.tsx) в top-level components только ради симметрии. Если эти части не имеют самостоятельного сценария использования, лучше оставить их в [`internal`](src/modules/HistoryHeader/internal) или рядом с модулем [`HistoryRow`](src/modules/HistoryRow).
-
-## Публичные entrypoints
-
-Минимальный публичный API:
-
-- [`src/index.ts`](src/index.ts:1) — общий экспорт библиотеки.
-- [`src/components/index.ts`](src/components/index.ts:1) — базовые components.
-- [`src/modules/index.ts`](src/modules/index.ts) — модули.
-- [`src/widgets/index.ts`](src/widgets/index.ts) — готовые виджеты.
-
-Если package exports будут настраиваться отдельно, можно дать потребителям импортировать уровни напрямую:
-
-- [`src/components/index.ts`](src/components/index.ts:1) для base components.
-- [`src/modules/index.ts`](src/modules/index.ts) для modules.
-- [`src/widgets/index.ts`](src/widgets/index.ts) для widgets.
-
-## Предлагаемый порядок реализации
-
-1. Создать папки [`src/components`](src/components), [`src/modules`](src/modules), [`src/widgets`](src/widgets) как публичные уровни библиотеки.
-2. Перенести [`QueriesHistory`](src/components/QueriesHistory/QueriesHistory.tsx:28) и его i18n в [`src/widgets/QueriesHistory`](src/widgets/QueriesHistory).
-3. Перенести [`HistoryHeader`](src/components/QueriesHistory/HistoryHeader/HistoryHeader.tsx:13), [`HistoryList`](src/components/QueriesHistory/HistoryList.tsx:26) (вместе с [`HistoryRowContent`](src/components/QueriesHistory/HistoryRowContent.tsx:1) и [`prepareRowData`](src/components/QueriesHistory/helpers/prepareRowData.ts)), [`HistoryRow`](src/components/QueriesHistory/HistoryRow/HistoryRow.tsx:17) в [`src/modules`](src/modules).
-4. Вынести [`QueryStatusIcon`](src/components/QueryStatusIcon/QueryStatusIcon.tsx:27), [`QueryDuration`](src/components/QueryDuration/QueryDuration.tsx) (вместе с хуком [`useQueryDuration`](src/components/QueryDuration/useQueryDuration.ts)) и [`HistoryGroupHeader`](src/components/HistoryGroupHeader/HistoryGroupHeader.tsx:1) в [`src/components`](src/components).
-5. Оставить [`HistorySearch`](src/components/QueriesHistory/HistoryHeader/HistorySearch.tsx:16), [`HistoryFilter`](src/components/QueriesHistory/HistoryHeader/HistoryFilter.tsx:16), [`HistoryRowHeader`](src/components/QueriesHistory/HistoryRow/HistoryRowHeader.tsx:19), [`HistoryRowMenu`](src/components/QueriesHistory/HistoryRow/HistoryRowMenu.tsx) внутри соответствующих modules, пока нет явной потребности в самостоятельном использовании.
-6. Обновить imports между уровнями: widgets импортируют modules и components, modules импортируют components, components не импортируют modules или widgets.
-7. Исправить сломанный barrel-экспорт [`src/components/index.ts`](src/components/index.ts:1) (сейчас там `export * from '.'` — самоссылающийся экспорт) и создать корректные `index.ts` для всех трёх уровней.
-8. Реэкспортировать публичные типы из [`src/types/history.ts`](src/types/history.ts:3) через [`src/index.ts`](src/index.ts:1), если они являются частью контракта.
-9. Проверить сборку и storybook после переноса файлов (сейчас `.stories.tsx` файлов в проекте нет — добавить их отдельной задачей при необходимости).
-
-## Итоговая рекомендация
-
-Трёхуровневая структура [`components`](src/components) / [`modules`](src/modules) / [`widgets`](src/widgets) оправдана, так как библиотека находится в начале развития и в неё планируется добавление многих новых виджетов — закладывать деление по уровню абстракции нужно сразу, а не переделывать структуру повторно в будущем. При этом не стоит выносить каждую внутреннюю часть в top-level atom: маленькие детали должны становиться base components только при наличии самостоятельного публичного сценария использования.