nntc-ui 0.2.6 → 0.2.7

package/wiki/VirtualTable.md

@@ -1,660 +0,0 @@
-### Общая информация
-Компонент разрабатывался в рамках проекта Геолжурнал, затем был перенесён в UI-kit **nntc-ui**. В настоящий момент компонент используется в ГЖ (проект **geoljournal**) и в Атрибутивном поиске (проект **map**).
-
-### Данные для таблицы
-В данном подразделе описывается структура данных для отображения таблицы и способ подготовки данных по заданным шаблонам.
-
-Основная структура таблицы - колонки(заголовки) и строки. Эта структура используется именно для передачи в компонент. Формироваться она может различными способами. Например, на текущий момент есть один способ - через специальные шаблоны, хранящиеся в виде JSON-объекта где-нибудь в базе (например, в scheme-group).
-
-#### Колонки
-```
-type ColumnAlign = 'Left' | 'Right' | 'Center';
-type SortType = 'alphanumeric' | 'locale';
-type VerticalAlign = 'FlexStart' | 'Center' | 'FlexEnd';
-
-interface TableColumn {
-  /** Уникальный идентификатор столбца */
-  id: string;
-  /** Ключ доступа к данным строки (по какому полю брать значение для ячейки) */
-  accessorKey?: string;
-  /** Заголовок столбца, отображаемый пользователю */
-  label: string;
-
-  /** Дочерние столбцы (для группировки столбцов под общим заголовком) */
-  columns?: TableColumn[];
-  /** Можно ли редактировать значения ячеек в этом столбце */
-  editable?: boolean;
-  /** Можно ли сортировать таблицу по этому столбцу */
-  sortable?: boolean;
-  /** Тип сортировки (например, по числу, строке или дате) */
-  sortType?: SortType;
-  /** Альтернативное имя поля, используемое при сортировке (если отличается от accessorKey). Очень специфичная логика, поэтому если не нужно, то не используйте. */
-  sortAnotherName?: string;
-  /** Включить фильтрацию по числовому диапазону */
-  filtrationByNumber?: boolean;
-  /** Включить фильтрацию по дате */
-  filtrationByDate?: boolean;
-  /** Включить фильтрацию по значению */
-  filtrationByValue?: boolean;
-  /** Показывать в фильтре только уникальные значения для выбора */
-  selectUnique?: boolean;
-  /** Ширина столбца в пикселях */
-  width?: number;
-  /** Горизонтальное выравнивание содержимого в заголовке столбца */
-  headerAlign?: ColumnAlign;
-  /** Горизонтальное выравнивание содержимого в ячейках столбца */
-  rowsAlign?: ColumnAlign;
-  /** Функция форматирования значения перед отображением */
-  valueFormat?: (value: string | number | undefined) => string;
-  /** Показывать ли этот столбец в модальном окне */
-  showInModal?: boolean;
-  /** Обработчик клика по ячейке столбца (получает payload ячейки) */
-  onClick?: (payload: { [key: string]: string }) => void;
-  /** Вертикальное выравнивание содержимого в ячейках столбца */
-  verticalAlign?: VerticalAlign;
-  /** Количество знаков после запятой для округления числовых значений */
-  toFixed?: number;
-  /** Тип HTML-поля ввода при редактировании ячейки (text, number, date и т.д.) */
-  inputType?: HTMLInputTypeAttribute;
-}
-```
-
-#### Строки
-```
-interface TableCell {
-  /** Отображаемое значение ячейки */
-  value?: string | number;
-  /** Дополнительные произвольные данные ячейки (например, для обработчиков событий) */
-  payload?: { [key: string]: string };
-  /** Текст всплывающей подсказки при наведении на ячейку */
-  tooltip?: string;
-  /** Цветовая заливка ячейки: ошибка (красный) или успех (зелёный) */
-  fill?: 'error' | 'success';
-  /** Количество строк, которые объединяет ячейка по вертикали */
-  rowspan?: number;
-}
-
-interface TableRow {
-  /** Строка таблицы: ключ — идентификатор столбца, значение — ячейка этого столбца */
-  [keys: string]: TableCell;
-}
-```
-
-Специальное поле **`isNew`** (не колонка, а служебная ячейка строки): `{ value: 1 }` — строка подсвечивается, не фильтруется и по умолчанию сортируется первой. Подробнее — в разделе «Сортировка».
-
-#### Структура шаблона таблицы
-В настоящий момент используется в Атрибутивном поиске. Из такого шаблона данные приводятся к виду TableColumn выше через специальный метод prepareData. Шаблоны необходимы для формирования таблицы неопытным пользователем, зная только структуру.
-```
-interface TableTemplate {
-  /** Название шаблона. */
-  name: string;
-  /** Количество строк в заголовке. */
-  rowsCount?: number;
-  /** Высоты строк в заголовке. По умолчанию 32 px. */
-  rowsHeights?: number[];
-  /** Массив колонок. Массив - т.к. используется специальный плагин, принимающий на вход массив, а т.к. у нас таблица виртуальная, обходимся одной колонкой, а потом специальными инструментами объединяем колонки по горизонтали. */
-  header: TableTemplateHeader[];
-  /** Показывать оставшиеся столбцы из набора данных, если их нет в шаблоне. */
-  showRemainingColumns?: boolean;
-  /** Выравнивание данных оставшихся столбцов по горизонтали. Если не указано, по умолчанию Left. */
-  remainingRowsAlign?: ColumnAlign;
-  /** Выравнивание заголовков оставшихся столбцов по горизонтали. Если не указано, по умолчанию Left. */
-  remainingHeaderAlign?: ColumnAlign;
-  /** Название для группировки по горизонтали оставшихся столбцов. Если не указано, то группировку не делать. */
-  remainingGroupName?: string;
-}
-
-interface TableTemplateHeader {
-  /** Название свойства из полученных данных. На основе наличия данного свойства определяется, главная ли это строка, или строка для группировок. */
-  propertyName?: string;
-  /** Индивидуальное название колонки. Указывается только при наличии propertyName. */
-  customName?: string;
-  /** ID строки. Указывается при отсутствии propertyName. Если не планируется объединение по горизонтали, то задаётся просто случайное значение (например, UID). Если необходима группировка по горизонтали с соседними колонками, то для этих колонок необходимо указать один и тот же ID. */
-  id?: string;
-  /** Заголовок строки. Указывается при отсутствии propertyName. При объединении по горизонтали указывается одинаковое значение. При объединении по вертикали указывается пустая строка. */
-  label?: string;
-  /** Порядок колонки. Указывается при отсутствии propertyName. Указывается только для самого верхнего уровня. */
-  position?: number;
-  /** Ширина колонки. Указывается при отсутствии propertyName, для каждой строки, иначе не будет работать объединение по горизонтали. Можно указать при наличии propertyName, если не подразумевается вложенность строк. */
-  width?: number;
-  /** Включить сортировку по столбцу. Указывается только при наличии propertyName. */
-  sortable?: boolean;
-  /** Тип сортировки: alphanumeric или locale. По умолчанию - locale. */
-  sortType?: SortType;
-  /** Включить фильтрацию по числам. Указывается только при наличии propertyName. */
-  filtrationByNumber?: boolean;
-  /** Включить фильтрацию по датам. Указывается только при наличии propertyName. */
-  filtrationByDate?: boolean;
-  /** Включить фильтрацию по точному названию. Указывается только при наличии propertyName. */
-  filtrationByValue?: boolean;
-  /** Особый тип данных - дата или большой текст. Указывается только при наличии propertyName. По умолчанию не указывается. Если date, то данные будут указаны в формате DD.MM.YYYY HH:mm. Если longText, то данные будут отображаться в несколько строк, а при нажатии на ячейку будет открываться модальное окно с полным текстом. */
-  dataType?: 'date' | 'dateTime' | 'longText';
-  /** Выбрать уникальные значения. Указывается только при наличии propertyName. По умолчанию false. */
-  selectUnique?: boolean;
-  /** Выравнивание данных по горизонтали. Указывается только при наличии propertyName.  Если не указано, по умолчанию Left. */
-  rowsAlign?: ColumnAlign;
-  /** Выравнивание заголовка по горизонтали. Указывается только при наличии propertyName. Если не указано, по умолчанию Left. */
-  headerAlign?: ColumnAlign;
-  /** Рекурсия текущего типа для следующей строки колонки. */
-  columns?: TableTemplateHeader[];
-  /** Выравнивание данных в ячейках по вертикали. Указывается только при наличии propertyName. Если не указано, по умолчанию center. */
-  verticalAlign?: VerticalAlign;
-  /** Кол-во знаков для округления. */
-  toFixed?: number;
-  /** Синхронизировать с картой. В заголовке появляется кнопка с глазиком. */
-  synchWithMap?: boolean;
-}
-```
-
-#### Пример шаблона
-```
-{
-  "name": "Системный",
-  "header": [
-    {
-      "width": 260,
-      "position": 0,
-      "sortable": true,
-      "rowsAlign": "Left",
-      "customName": "ДО/ДЗО",
-      "headerAlign": "Left",
-      "propertyName": "Entity",
-      "selectUnique": "true",
-      "filtrationByValue": true
-    },
-    {
-      "width": 300,
-      "position": 1,
-      "sortable": true,
-      "rowsAlign": "Left",
-      "customName": "Лицензионный участок",
-      "headerAlign": "Left",
-      "propertyName": "LicenseArea",
-      "selectUnique": "true",
-      "filtrationByValue": true
-    },
-    {
-      "width": 300,
-      "position": 2,
-      "sortable": true,
-      "rowsAlign": "Left",
-      "customName": "Месторождение",
-      "headerAlign": "Left",
-      "propertyName": "Field",
-      "selectUnique": "true",
-      "filtrationByValue": true
-    },
-    {
-      "width": 160,
-      "position": 3,
-      "sortType": "alphanumeric",
-      "sortable": true,
-      "rowsAlign": "Left",
-      "customName": "Куст",
-      "headerAlign": "Left",
-      "propertyName": "Pad",
-      "selectUnique": "true",
-      "filtrationByValue": true
-    },
-    {
-      "width": 195,
-      "position": 4,
-      "sortType": "alphanumeric",
-      "sortable": true,
-      "rowsAlign": "Left",
-      "customName": "Скважина",
-      "headerAlign": "Left",
-      "propertyName": "Well",
-      "selectUnique": "true",
-      "filtrationByValue": true
-    },
-    {
-      "width": 143,
-      "position": 7,
-      "sortType": "alphanumeric",
-      "sortable": true,
-      "rowsAlign": "Left",
-      "customName": "Ствол",
-      "headerAlign": "Left",
-      "propertyName": "Bore",
-      "filtrationByValue": true
-    }
-  ],
-  "rowsCount": 1,
-  "rowsHeights": [
-    32
-  ]
-}
-```
-
-#### Пример окончательного варианта данных для таблицы
-```
-{
-  templateData: {
-    headers: [
-      {
-        property: {
-          name: 'Entity',
-          alias: 'ДО/ДЗО'
-        },
-        position: 0
-      },
-      {
-        property: {
-          name: 'LicenseArea',
-          alias: 'Лицензионный участок'
-        },
-        position: 0
-      },
-      {
-        property: {
-          name: 'Field',
-          alias: 'Месторождение'
-        },
-        position: 0
-      },
-      {
-        property: {
-          name: 'Pad',
-          alias: 'Куст'
-        },
-        position: 0
-      },
-      {
-        property: {
-          name: 'Well',
-          alias: 'Скважина'
-        },
-        position: 0
-      },
-      {
-        property: {
-          name: 'Bore',
-          alias: 'Ствол'
-        },
-        position: 0
-      }
-    ],
-    rows: [
-      {
-        Bore: {
-          value: '1',
-          payload: {
-            id: 'f7865807-2768-412f-a676-213071e84f3d'
-          }
-        },
-        Well: {
-          value: '101',
-          payload: {
-            id: 'f4c673e0-13da-4e97-82ab-6575b3722ea8'
-          }
-        },
-        LicenseArea: {
-          value: 'Салмановский (Утренний) л.у.',
-          payload: {
-            id: 'dfbd9885-3de5-44d2-8950-1a6131aa78bf'
-          }
-        },
-        Entity: {
-          value: 'Арктик СПГ 2',
-          payload: {
-            id: '20fc4832-a69a-4e9c-9100-acc08a184394'
-          }
-        },
-        Field: {
-          value: 'Салмановское (Утреннее) НГКМ (SAL)',
-          payload: {
-            id: '00000000-0000-0000-0000-000000011167'
-          }
-        },
-        Pad: {
-          value: '1',
-          payload: {
-            id: '394f16a5-fcd4-4b99-92c9-98fa73bcec23'
-          }
-        }
-      },
-      {
-        Bore: {
-          value: '1',
-          payload: {
-            id: 'f7865807-2768-412f-a676-213071e84f3d'
-          }
-        },
-        Well: {
-          value: '101',
-          payload: {
-            id: 'f4c673e0-13da-4e97-82ab-6575b3722ea8'
-          }
-        },
-        LicenseArea: {
-          value: 'Салмановский (Утренний) л.у.',
-          payload: {
-            id: 'dfbd9885-3de5-44d2-8950-1a6131aa78bf'
-          }
-        },
-        Entity: {
-          value: 'Арктик СПГ 2',
-          payload: {
-            id: '20fc4832-a69a-4e9c-9100-acc08a184394'
-          }
-        },
-        Field: {
-          value: 'Салмановское (Утреннее) НГКМ (SAL)',
-          payload: {
-            id: '00000000-0000-0000-0000-000000011167'
-          }
-        }
-      },
-      {
-        Bore: {
-          value: '1',
-          payload: {
-            id: 'f7865807-2768-412f-a676-213071e84f3d'
-          }
-        },
-        Well: {
-          value: '101',
-          payload: {
-            id: 'f4c673e0-13da-4e97-82ab-6575b3722ea8'
-          }
-        },
-        LicenseArea: {
-          value: 'Салмановский (Утренний) л.у.',
-          payload: {
-            id: 'dfbd9885-3de5-44d2-8950-1a6131aa78bf'
-          }
-        },
-        Entity: {
-          value: 'Арктик СПГ 2',
-          payload: {
-            id: '20fc4832-a69a-4e9c-9100-acc08a184394'
-          }
-        },
-        Field: {
-          value: 'Салмановское (Утреннее) НГКМ (SAL)',
-          payload: {
-            id: '00000000-0000-0000-0000-000000011167'
-          }
-        },
-        Pad: {
-          value: '1',
-          payload: {
-            id: '394f16a5-fcd4-4b99-92c9-98fa73bcec23'
-          }
-        }
-      }
-    ]
-  }
-}
-```
-
-#### Пример фильтрации данных для таблицы
-
-Ниже — пример **сохранённого состояния** фильтров и сортировок на стороне приложения (например, в localStorage или на бэкенде). Ключ верхнего уровня — идентификатор набора данных или вкладки; внутри — массивы `filters` и `sorts` в формате, который принимает компонент через пропсы `globalFilters` и `globalSorts`.
-
-```
-{
-  '6ac284d5-92b9-4444-8957-39fe1e3a0b28': {
-    filters: [
-      {
-        columnName: 'Pad',
-        type: 'value',
-        values: [
-          '1'
-        ]
-      },
-      {
-        columnName: 'Petrophysics',
-        type: 'value',
-        values: [
-          'Петро_07.05'
-        ]
-      },
-      {
-        columnName: 'Field',
-        type: 'value',
-        values: [],
-        uniqueFirstPerValue: true
-      },
-      {
-        columnName: 'Top',
-        type: 'numberRange',
-        values: [
-          12,
-          40
-        ]
-      },
-      {
-        columnName: 'CreatedAt',
-        type: 'dateRange',
-        values: [
-          '2026-06-10T00:00:00+07:00',
-          '2026-06-18T00:00:00+07:00'
-        ]
-      }
-    ],
-    sorts: [
-      {
-        columnName: 'Well',
-        direction: 'asc',
-        sortType: 'alphanumeric'
-      },
-      {
-        columnName: 'Correlations',
-        direction: 'desc'
-      }
-    ]
-  }
-}
-```
-
-### Фильтрация
-
-Фильтры настраиваются **на уровне колонок** (см. `filtrationByValue`, `filtrationByNumber`, `filtrationByDate` в `TableColumn`) и применяются через массив активных фильтров `FilterBy[]`.
-
-#### Связь свойств колонки и типов фильтра
-
-| Свойство колонки | Что появляется в UI | Тип фильтра (`FilterBy.type`) |
-|---|---|---|
-| `filtrationByValue` | Чеклист со значениями из данных | `'value'` |
-| `filtrationByNumber` | Поля «от» и «до» для чисел | `'numberRange'` |
-| `filtrationByDate` | Выбор диапазона дат | `'dateRange'` |
-| `selectUnique` | Пункт меню «Только уникальные» (не отдельный тип, работает поверх `'value'`) | `'value'` + `uniqueFirstPerValue: true` |
-
-Для одной колонки можно включить несколько типов фильтрации одновременно — в выпадающем меню заголовка они отображаются вместе.
-
-Имя столбца в фильтре (`columnName`) совпадает с `id` колонки. Если задан `sortAnotherName`, используется он — это же правило действует для сортировки.
-
-#### Активный фильтр
-
-```
-interface FilterBy {
-  /** Имя столбца (id колонки или sortAnotherName) */
-  columnName: string;
-  /** Тип фильтра */
-  type: 'value' | 'numberRange' | 'dateRange';
-  /** Значения фильтра — зависят от type (см. ниже) */
-  values: (string | number)[];
-  /** Только для type='value': оставить первую строку для каждого уникального значения */
-  uniqueFirstPerValue?: boolean;
-}
-```
-
-**`type: 'value'`** — фильтр по точному значению ячейки. `values` — массив выбранных строковых значений. Пустая строка `''` соответствует ячейкам без значения (`< нет значения >` в UI). Если `uniqueFirstPerValue: true` и `values` пустой, фильтр не отсекает строки, а после остальных фильтров оставляет только первое вхождение каждого уникального значения столбца.
-
-**`type: 'numberRange'`** — числовой диапазон. `values: [min, max]`. Значения `-Infinity` / `Infinity` означают «без ограничения» с соответствующей стороны; если оба — фильтр сбрасывается.
-
-**`type: 'dateRange'`** — диапазон дат. `values: [startISO, endISO]` — строки в формате ISO 8601. Сравнение идёт по дням (время игнорируется). `undefined` в значениях означает сброс фильтра.
-
-#### Поведение при применении
-
-- Активные фильтры **комбинируются через AND**: строка должна удовлетворять всем фильтрам одновременно.
-- Строки с `isNew.value === 1` **всегда проходят** через фильтры (используется для подсветки «новых»/выбранных строк).
-- При смене набора данных (`rows`) фильтры, для которых больше нет подходящих строк, автоматически удаляются — кроме `uniqueFirstPerValue` с пустым `values`.
-- Список значений в чеклисте для колонки строится с учётом фильтров по **другим** колонкам (каскадная фильтрация).
-- При изменении фильтров компонент диспатчит событие `filteringRows` на `window` с отфильтрованными строками в `detail`.
-
-### Сортировка
-
-Сортировка настраивается **на уровне колонок** через `sortable` и `sortType`, а применяется через массив `SortBy[]`.
-
-#### Связь свойств колонки и сортировки
-
-| Свойство колонки | Назначение |
-|---|---|
-| `sortable` | Показать пункты «По возрастанию» / «По убыванию» в меню заголовка |
-| `sortType: 'alphanumeric'` | Сравнение с учётом чисел внутри строк (например, «Скв.2» < «Скв.10») |
-| `sortType: 'locale'` (по умолчанию) | Лексикографическое сравнение через `localeCompare` |
-| `sortAnotherName` | Сортировать/фильтровать по другому ключу строки, отличному от `id` колонки |
-
-#### Активная сортировка
-
-```
-interface SortBy {
-  /** Имя столбца (id колонки или sortAnotherName) */
-  columnName: string;
-  /** Направление: asc — по возрастанию, desc — по убыванию */
-  direction: 'asc' | 'desc';
-  /** Тип сравнения; если не указан — locale */
-  sortType?: 'alphanumeric' | 'locale';
-}
-```
-
-#### Поведение при применении
-
-- Сортировки применяются **каскадно**: первый элемент массива — главный ключ, последующие — tie-breaker.
-- Внутри компонента всегда добавлена скрытая сортировка `{ columnName: 'isNew', direction: 'desc' }`, чтобы строки с `isNew.value === 1` оставались наверху. Она **не попадает** в `onSortsChange`.
-- Повторный клик по активному направлению снимает сортировку по этому столбцу.
-- Смена направления для уже отсортированного столбца заменяет направление, не добавляя вторую запись.
-
-#### Специальное поле строки `isNew`
-
-```
-// Пример строки, выделенной как «новая» / выбранная
-{
-  isNew: { value: 1 },
-  Well: { value: '101' },
-  // ...
-}
-```
-
-- Строка подсвечивается фоном `selected`.
-- Не отфильтровывается активными фильтрами.
-- По умолчанию сортируется первой (desc по `isNew`).
-
-### Выделение строк
-
-Включается пропом `enableSelectRows`. Пока режим активен, выделение текста в таблице отключено, чтобы можно было провести мышью по строкам и выделить диапазон.
-
-| Действие | Результат |
-|---|---|
-| Клик по ячейке-ссылке (`onClick` колонки) | Срабатывает действие ячейки, выделение не меняется |
-| Ctrl/Shift + клик по ячейке-ссылке | Строка выделяется, действие ячейки не вызывается |
-| Клик по единственной выбранной строке | Выделение снимается |
-| Клик по пустой области таблицы (не шапка, не попап, не скроллбар) | Снимается всё выделение |
-| Ctrl/Cmd + клик | Строка добавляется к выделению или снимается, если уже была выделена |
-| Shift + клик | Выделяются все строки от последней выбранной до текущей |
-| Ctrl/Cmd + Shift + клик | Диапазон добавляется к уже выделенным строкам |
-| Провести мышью с зажатой кнопкой | Выделяются все строки от начальной до текущей |
-| Ctrl/Cmd + провести мышью | Диапазон добавляется к выделению, которое было до начала жеста |
-
-На тач-устройствах drag не перехватывается (чтобы не мешать прокрутке): одиночный тап выделяет строку. Клики по кнопкам, ссылкам и полям ввода выделение не меняют. Клик по ячейке с собственным обработчиком (`onClick` колонки, редактирование, открытие модалки) срабатывает как действие ячейки и не меняет выделение; Ctrl/Shift+клик по такой ячейке выделяет строку.
-
-При изменении фильтров/сортировки выделение сохраняется по ссылке на объект строки: исчезнувшие из выборки строки убираются, оставшиеся пересчитываются. После каждого изменения вызывается `onSelectRowsChange` с массивом `TableRow[]` в текущем порядке отображения.
-
-Начальное выделение задаётся пропом `globalSelectedRows` — массив тех же объектов строк, что переданы в `rows` (как `globalFilters` / `globalSorts`). Дальше состояние живёт внутри таблицы, наружу уходит через `onSelectRowsChange`.
-
-### Параметры компонента
-
-Компонент принимает пропсы через `UiProps<Props>` — помимо перечисленных ниже, доступен стандартный `classes` для кастомизации CSS-классов корневого элемента.
-
-#### Данные
-
-| Проп | Тип | Обязательный | По умолчанию | Описание |
-|---|---|---|---|---|
-| `rows` | `TableRow[]` | да | — | Строки таблицы |
-| `columns` | `TableColumn[]` | да | — | Описание колонок |
-
-#### Редактирование и кастомный рендер
-
-| Проп | Тип | По умолчанию | Описание |
-|---|---|---|---|
-| `additionalColumnsViews` | `(id, value, payload) => { edit, view }` | — | Кастомный рендер ячеек в режимах просмотра и редактирования |
-| `onChangeCell` | `(rowIndex, columnId, value, original?) => void` | — | Колбэк при изменении значения редактируемой ячейки |
-
-#### Размеры и виртуализация
-
-| Проп | Тип | По умолчанию | Описание |
-|---|---|---|---|
-| `height` | `number` | — | Фиксированная высота контейнера таблицы (px) |
-| `headerRowHeight` | `number[]` | `[32]` | Высота строк заголовка по уровням вложенности (px) |
-| `bodyRowHeight` | `number` | `32` | Высота строки тела таблицы (px) |
-| `dynamicRowHeight` | `boolean` | `false` | Автоизмерение высоты строк по содержимому |
-| `cellWidth` | `(columnIndex) => number` | `meta.width` или `200` | Расчёт ширины колонки |
-| `scrollToBottom` | `boolean` | — | Прокрутка к последней строке при монтировании |
-
-#### Закрепление и действия строк
-
-| Проп | Тип | По умолчанию | Описание |
-|---|---|---|---|
-| `fixedColumnsCount` | `number` | `0` | Количество левых колонок, закреплённых при горизонтальной прокрутке |
-| `showRowsNumbers` | `boolean` | — | Добавить закреплённую колонку «#» с порядковым номером |
-| `rowButtons` | `(original) => AdditionalButton[]` | — | Кнопки действий справа от каждой строки |
-| `rowActionWidth` | `number` | `77` | Ширина колонки с кнопками действий (px) |
-| `enableSelectRows` | `boolean` | `false` | Включить выделение строк мышью |
-| `globalSelectedRows` | `TableRow[]` | `[]` | Начальное выделение (те же объекты, что в `rows`) |
-| `onSelectRowsChange` | `(rows: TableRow[]) => void` | — | Колбэк при изменении выделения; передаются полные данные выделенных строк в порядке отображения |
-
-```
-interface AdditionalButton {
-  /** Текст тултипа кнопки */
-  title: string;
-  /** Обработчик клика: индекс строки и исходные данные */
-  onClick?: (rowIndex: number, original: TableRow) => void;
-  /** Иконка кнопки */
-  icon: ReactNode;
-  /** Полностью кастомный рендер вместо стандартной кнопки */
-  template?: (props: AdditionalButton) => ReactNode;
-}
-```
-
-#### Фильтрация и сортировка
-
-| Проп | Тип | По умолчанию | Описание |
-|---|---|---|---|
-| `globalFilters` | `FilterBy[]` | `[]` | Начальные фильтры |
-| `globalSorts` | `SortBy[]` | `[]` | Начальные сортировки |
-| `onFiltersChange` | `(filters: FilterBy[]) => void` | — | Колбэк при изменении фильтров |
-| `onSortsChange` | `(sorts: SortBy[]) => void` | — | Колбэк при изменении сортировок (без `isNew`) |
-| `showUniqueValuesCount` | `boolean` | `false` | Показывать в заголовке количество уникальных значений |
-
-#### Внешний вид
-
-| Проп | Тип | По умолчанию | Описание |
-|---|---|---|---|
-| `componentSize` | `'small' \| 'medium' \| 'large'` | `'small'` | Размер компонента |
-| `borders` | `'all' \| 'horizontal' \| 'vertical' \| 'none'` | `'horizontal'` | Стиль границ ячеек |
-| `stripedRows` | `boolean` | `true` | Чередование фона строк (zebra) |
-
-#### Заголовок и попапы
-
-| Проп | Тип | По умолчанию | Описание |
-|---|---|---|---|
-| `leftAdditionalHeaderContent` | `(headerName) => ReactNode` | — | Контент слева от заголовка колонки |
-| `rightAdditionalHeaderContent` | `(headerName) => ReactNode` | — | Контент справа от заголовка, перед кнопкой фильтра |
-| `useTableContainerAsRootForPopup` | `boolean` | — | Рендерить попапы внутри контейнера таблицы (для overflow/вкладок) |
-
-#### Ref (`VirtualTableRef`)
-
-| Метод | Описание |
-|---|---|
-| `resetFilters()` | Сбросить все активные фильтры |
-| `resetSorts()` | Сбросить пользовательские сортировки |
-
-#### События
-
-| Событие | Где | Описание |
-|---|---|---|
-| `filteringRows` | `window` (CustomEvent) | Срабатывает при изменении отфильтрованных строк; `event.detail` — массив `TableRow[]` |
-