@sberbusiness/triplex-next-mcp-server 0.24.0-beta2 → 1.40.0-beta

package/bundle/components/Col.md

@@ -1,9 +1,7 @@
 ---
 component: Col
 category: Layout
-figma-node: ""
-figma-file: ""
-related: [Row, Page, Gap]
+related: [Row, Gap]
 tokens: []
 stories: stories/Col/Col.stories.tsx
 version: "1.0"
@@ -13,209 +11,360 @@ version: "1.0"
 
 ## Назначение
 
-Ячейка responsive-grid, реализованная в духе Bootstrap 4 (12-колоночная
-сетка). Управляет шириной колонки, offset'ом и видимостью через
-breakpoint-префиксы (base / sm / md / lg / xl). Всегда используется
-внутри `Row` (который создаёт flex-контейнер с отрицательными margin'ами
-для компенсации padding'ов Col).
+Колонка адаптивной 12-колоночной сетки (по модели Bootstrap 4). Задаёт ширину,
+отступ слева и видимость содержимого на разных диапазонах экранов. Используется
+только внутри `Row` — горизонтальный отступ между колонками (gutter) получает из
+`RowContext`.
 
-`Col` — FC-обёртка над `<div>` с композицией CSS-классов по пропсам.
-Сами CSS-классы генерируются LESS-миксином `createCol` для всех
-breakpoint-префиксов.
+Используй когда: нужно разместить контент в адаптивной сетке — распределить
+блоки по ширине страницы, менять раскладку по breakpoint'ам, скрывать колонки
+на отдельных диапазонах экранов.
 
-Используй когда: нужна responsive-сетка страницы/формы с точным контролем
-ширины колонок на разных разрешениях.
-Не используй когда: простой flex/grid вручную проще — брать Col только
-ради одной колонки не нужно; для фиксированных отступов между блоками —
-бери `Gap`.
-
----
-
-## Файловая структура
-
-```text
-src/components/Col/
-├── Col.tsx                             # React.FC, нет forwardRef
-├── index.ts                            # Barrel
-├── styles/Col.module.less              # LESS миксин createCol(), генерирует классы
-└── __tests__/
-```
-
-Особенности:
-- **Нет forwardRef** — FC без ref-форвардинга. Это известный AI-ready debt.
-  Не добавлять точечно.
-- **LESS-миксин `createCol(@resolutionType)`** — генерирует 12 column-классов
-  и 12 offset-классов для каждого breakpoint'а. Добавление нового breakpoint —
-  одна строка в LESS.
-- **Bootstrap-подобный API**: `col-1..12`, `col-sm-1..12`, `col-md-*`, `col-lg-*`, `col-xl-*`,
-  `offset-*`, `d-none`, `d-block`.
+Не используй когда:
+- Колонка находится вне `Row` — без контекста применится дефолтный gutter, а
+  flex-раскладка родителя не гарантируется.
+- Нужен вертикальный отступ между блоками — используй `Gap`.
+- Нужна произвольная (не кратная 1/12) ширина — управляй стилями контейнера
+  напрямую.
 
 ---
 
 ## Варианты и props
 
-### `IColProps extends React.HTMLAttributes<HTMLDivElement>`
-
-**Base (применяется на всех разрешениях):**
+Обязательных props нет — `<Col>` без props занимает всю ширину (`size` по
+умолчанию `12`).
 
-| Prop | Тип | Default | Описание |
-|---|---|---|---|
-| `size` | `TColumnSize` (1..12) | `12` | Ширина колонки в 12-ти колоночной сетке. |
-| `offset` | `TOffsetSize` (0..11) | — | Отступ слева в колонках. |
-| `hidden` | `boolean` | — | `display: none !important`. |
-| `block` | `boolean` | — | `display: block !important`. |
-
-**Responsive (каждый breakpoint-префикс дублирует все 4):**
+### Группы props
 
-| Breakpoint | Size prop | Offset prop | Hidden prop | Block prop | Media |
-|---|---|---|---|---|---|
-| sm | `sizeSm` | `offsetSm` | `hiddenSm` | `blockSm` | `(min-width: @screen-sm)` |
-| md | `sizeMd` | `offsetMd` | `hiddenMd` | `blockMd` | `(min-width: @screen-md)` |
-| lg | `sizeLg` | `offsetLg` | `hiddenLg` | `blockLg` | `(min-width: @screen-lg)` |
-| xl | `sizeXl` | `offsetXl` | `hiddenXl` | `blockXl` | `(min-width: @screen-xl)` |
+Каждая группа существует в пяти вариантах: базовый (все экраны, mobile-first) и
+breakpoint-модификаторы `*Sm`, `*Md`, `*Lg`, `*Xl`, действующие «от breakpoint
+и шире». Более узкий breakpoint перекрывается более широким.
 
-**Стандартные:**
-
-| Prop | Тип | Описание |
-|---|---|---|
-| `children` | `ReactNode` | Контент колонки. |
-| `className` | `string` | Доп. класс. |
-| `...HTMLDivAttributes` | — | Все стандартные. |
+| Группа | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `size`, `sizeSm/Md/Lg/Xl` | `TColumnSize` (1–12) | `size = 12` | Ширина колонки в долях сетки: `flex-basis`/`max-width` = N/12 |
+| `offset`, `offsetSm/Md/Lg/Xl` | `TOffsetSize` (0–11) | — | Отступ слева (`margin-left`) в долях сетки; `0` — валидное значение, сбрасывает отступ на breakpoint'е |
+| `hidden`, `hiddenSm/Md/Lg/Xl` | `boolean` | — | Скрывает колонку (`display: none !important`) от breakpoint'а и шире |
+| `block`, `blockSm/Md/Lg/Xl` | `boolean` | — | Принудительно показывает колонку (`display: block !important`) от breakpoint'а и шире; в паре с `hidden` даёт диапазонную видимость |
+| `...HTMLDivAttributes` | — | — | Все стандартные атрибуты `<div>`, включая `className` (мерджится с grid-классами через `clsx`) |
 
-### Types
+### Breakpoint'ы
 
-- `TColumnSize = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12`
-- `TOffsetSize = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11`
+Значения из `src/helpers/less/breakpoints.less` (media query `min-width`,
+mobile-first):
 
-Offset — до 11 (12 offset занял бы всю строку, колонки бы не было).
+| Суффикс | Диапазон |
+|---|---|
+| — (базовый) | все экраны, от 0 |
+| `Sm` | ≥576px |
+| `Md` | ≥768px |
+| `Lg` | ≥992px |
+| `Xl` | ≥1200px |
+
+### Особенности поведения
+
+- Паттерн диапазонной видимости: `hidden` + `blockMd` = колонка скрыта на
+  xs/sm и видима с md и шире.
+- `hidden` **переопределяет одноимённый нативный HTML-атрибут** с другой
+  семантикой: prop добавляет CSS-класс `d-none`, а не атрибут `hidden` на div.
+  Выставить нативный атрибут через Col нельзя — это исторический публичный
+  контракт.
+- Gutter (горизонтальный `padding` колонки) задаётся не props, а `Row`:
+  `RowContext.gridHorizontalGap` (`EComponentSize.SM` = 8px,
+  `EComponentSize.MD` = 12px; дефолт контекста — SM). Col лишь применяет
+  соответствующий класс, устанавливающий `--grid-horizontal-gap`.
 
 ---
 
-## Ключевые особенности реализации
-
-### `getClassNames` helper
-
-```ts
-function getClassNames({ block, hidden, offset, prefix, size }) {
-    const prefixAsPart = prefix ? `${prefix}-` : "";
-    const prefixVisibility = prefix ? `-${prefix}` : "";
-    // ...
-    if (size) classes.push(`col-${prefixAsPart}${size}`);
-    if (offset !== undefined) classes.push(`offset-${prefixAsPart}${offset}`);
-    if (block) classes.push(`d-block${prefixVisibility}`);
-    if (hidden) classes.push(`d-none${prefixVisibility}`);
-}
-```
-
-**Асимметрия префиксов**: `col-sm-6` (префикс в середине), но `d-block-sm`
-(префикс в конце). Это Bootstrap-ная конвенция, повторённая один-в-один.
-Не менять без миграции пользователей.
-
-### Классы собираются в массив → `styles[...]`
-
-```ts
-const mappedClasses = classNames.map((c) => styles[c]).filter(Boolean);
-```
-
-Имена классов — это ключи в LESS module объекте. `filter(Boolean)`
-защищает от опечаток (если бы класс не существовал → `undefined`).
+## Дизайн-токены
 
-### `size = 12` по умолчанию
+Собственных CSS-переменных дизайн-темы (`--triplex-next-*`) компонент не
+использует. Ширины и отступы вычисляются в LESS как доли `100% / 12`; gutter —
+локальная переменная `--grid-horizontal-gap`, значение которой берётся из LESS-
+переменных `@grid-horizontal-gap-SM` (8px) / `@grid-horizontal-gap-MD` (12px)
+в `src/styles/components/grid.less`.
 
-Если size не задан — колонка занимает всю ширину. Это конвенция Bootstrap.
-На узких экранах (без sm/md/lg overrides) колонка всегда full-width,
-что даёт mobile-first сетку.
+---
 
-### `.d-none` / `.d-block` с `!important`
+## Инварианты
 
-```less
-.d-none { display: none !important; }
-.d-block { display: block !important; }
-```
+- **`forwardRef`** — обязателен, не убирать. `ref` пробрасывается на корневой
+  `<div>`.
+- **Имена всех 20 responsive-props** (`size*`, `offset*`, `hidden*`, `block*`)
+  и типы **`TColumnSize`**, **`TOffsetSize`** — публичное API, экспортируются
+  из barrel. Изменение перечня значений — breaking change.
+- **Дефолт `size = 12`** — колонка без props занимает всю ширину.
+- **Корневой элемент `<div>`** и мердж `className` потребителя с
+  grid-классами — не менять.
+- **Схема генерации классов** `col-{prefix}-N` / `offset-{prefix}-N` /
+  `d-none-{prefix}` / `d-block-{prefix}` в `Col.module.less` — классы
+  резолвятся через `styles[c]`-маппинг; переименование селекторов ломает
+  раскладку и тесты.
+- **Зависимость от `RowContext`** — источник gutter'а. Не заменять на prop.
+- Breakpoint-значения (576/768/992/1200) — общие для библиотеки
+  (`breakpoints.less`), не задавать локальные.
 
-`!important` нужен, потому что `.col-*` уже имеет `display` (через flex
-item родителя). Без important не переопределяли бы.
+---
 
-### LESS `each` + `range` генерируют классы
+## Accessibility
 
-```less
-each(range(12), {
-    .col-@{resolutionType}@{value} { ... flex: 0 0 (@base-col * @value); max-width: (...); }
-});
-```
+- Неинтерактивный layout-контейнер: без ARIA-роли, keyboard navigation и
+  focus management не применимы.
+- Скрытие через `hidden*` использует `display: none` — контент скрытой колонки
+  недоступен и для screen reader'ов (в отличие от visually-hidden паттернов).
+  Это ожидаемое поведение адаптивной сетки.
+- Потребитель может передать `role`, `aria-*`, `data-*` через spread.
 
-Один миксин — 12 col- + 12 offset-. Вызывается для каждого breakpoint'а.
-**Если добавить XXL** — одна строка `.createCol(xxl-);` в media-query.
+---
 
-### `@grid-horizontal-gap` — не токен, а LESS-переменная
+## Связанные компоненты
 
-В `src/styles/style.less`. Часть grid-системы (не в список токенов
-компонента). Должен быть синхронизирован с Row'ом (у которого
-отрицательный margin).
+- `Row` (`src/components/Row/`) — обязательный родитель: flex-контейнер строки,
+  провайдер `RowContext.gridHorizontalGap`.
+- `Gap` (`src/components/Gap/`) — вертикальный отступ между блоками; используй
+  вместо сетки, когда нужен только отступ.
 
 ---
 
-## Инварианты
+## Stories
+
+Основные истории: `stories/Col/Col.stories.tsx`
+Файлы примеров: `stories/Col/examples/`
 
-- **`size` default = 12** — полная ширина, mobile-first поведение. Не менять.
-- **`TColumnSize` ограничен 1..12** — не расширять. 12 — bootstrap-константа.
-- **`TOffsetSize` ограничен 0..11** — offset=12 бессмыслен.
-- **LESS миксин `createCol`** — источник истины для имён классов. Если
-  переименовывать схему — обновлять **и** миксин, **и** `getClassNames`.
-- **Асимметричные префиксы** `col-sm-*` vs `d-block-sm` — Bootstrap
-  конвенция. Не унифицировать.
-- **`!important` на `.d-none` / `.d-block`** — не удалять.
-- **`Col` всегда внутри `Row`** — работает flex-сеткой. Col без Row
-  получает полную ширину и нет gap-компенсации.
-- **Нет forwardRef** — документированный debt. Не добавлять точечно.
+| Story | Example file | Что демонстрирует |
+|---|---|---|
+| `Playground` | `PlaygroundExample.tsx` | Интерактивный контроль `size`, `offset`, `hidden`, `block` |
+| `Default` | `DefaultExample.tsx` | Колонка без props — ширина по умолчанию (12/12) |
+| `DifferentSizes` | `DifferentSizesExample.tsx` | Разные значения `size`, включая дефолтный |
+| `ResponsiveSizes` | `ResponsiveSizesExample.tsx` | Адаптивные ширины `sizeSm/Md/Lg/Xl` |
+| `WithOffsets` | `WithOffsetsExample.tsx` | Отступы слева через `offset` |
+| `ResponsiveOffsets` | `ResponsiveOffsetsExample.tsx` | Адаптивные отступы `offsetSm/Md/Lg/Xl` |
+| `HiddenColumns` | `HiddenColumnsExample.tsx` | Скрытие колонок на диапазонах экранов (`hidden*` + `block*`) |
+| `VisualTests` | `VisualTestsExample.tsx` | Скриншот-регрессия основных состояний |
 
 ---
 
-## Accessibility
+## История изменений
 
-- **Нет ARIA** — div без семантики.
-- **`hidden`** через `display: none` полностью убирает элемент из
-  доступности (screen reader не читает, клавиатура пропускает). Это
-  ожидаемо для скрытия элементов по breakpoint'у.
-- **Порядок DOM = порядок источника**. Если нужно визуально переставить
-  колонки (order), использовать `order` CSS — Col этого не делает сам.
+| Дата | Изменение |
+|---|---|
+| 2026-07-28 | Создан документ. AI-рефакторинг (TRI-28): добавлен `forwardRef` на корневой `<div>`, JSDoc на `TColumnSize`/`TOffsetSize`/все props `IColProps`, rest-props переименован в `htmlDivAttributes`, расширены unit-тесты (49 кейсов: forwardRef, полный перебор size/offset, falsy-ветки). Публичный API не менялся. |
 
 ---
 
-## Дизайн-токены
+## Примеры использования
 
-Нет — компонент использует LESS-переменные сетки (`@grid-horizontal-gap`,
-`@screen-sm/md/lg/xl`), не CSS-токены.
+### Default
 
----
+`stories/Col/examples/DefaultExample.tsx`
 
-## Связанные компоненты
+```tsx
+import React from "react";
+import { Col, Row } from "@sberbusiness/triplex-next";
 
-- `Row` (`src/components/Row`) — обязательный родитель. Создаёт flex-контейнер
-  с отрицательными margin'ами для Col.
-- `Page` (`src/components/Page`) — страничный layout, часто использует
-  Col/Row внутри для структуры.
-- `Gap` (`src/components/Gap`) — для вертикальных отступов между блоками
-  (Col — горизонтальные колонки).
-
----
+export const DefaultExample = () => (
+    <Row style={{ width: "600px" }}>
+        <Col>
+            <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                default size (size-12)
+            </div>
+        </Col>
+    </Row>
+);
+```
 
-## Stories
+### DifferentSizes
+
+`stories/Col/examples/DifferentSizesExample.tsx`
+
+```tsx
+import React from "react";
+import { Col, Row } from "@sberbusiness/triplex-next";
+
+export const DifferentSizesExample = () => (
+    <>
+        <Row style={{ width: "600px" }}>
+            <Col>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    default size (size-12)
+                </div>
+            </Col>
+        </Row>
+
+        <Row style={{ width: "600px" }}>
+            <Col size={2}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-2
+                </div>
+            </Col>
+            <Col size={3}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-3
+                </div>
+            </Col>
+            <Col size={6}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-6
+                </div>
+            </Col>
+        </Row>
+    </>
+);
+```
 
-`stories/Col/Col.stories.tsx`
-Примеры: `stories/Col/examples/`
+### ResponsiveSizes
+
+`stories/Col/examples/ResponsiveSizesExample.tsx`
+
+```tsx
+import React from "react";
+import { Col, Gap, Row } from "@sberbusiness/triplex-next";
+
+export const ResponsiveSizesExample = () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+        <Row>
+            <Col sizeSm={6} sizeMd={5} sizeLg={4} sizeXl={3}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    <div>Размеры колонки на разных экранах: sm - 6, md - 5, lg - 4, xl - 3</div>
+                </div>
+                <Gap size={16} />
+            </Col>
+
+            <Col sizeSm={7} sizeMd={8} sizeLg={9} sizeXl={10}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    <div>Размеры колонки на разных экранах: sm - 7, md - 8, lg - 9, xl - 10</div>
+                </div>
+            </Col>
+        </Row>
+    </div>
+);
+```
 
-Типовые stories:
-- `Default` — колонки равной ширины
-- `Sizes` — разные size на разных breakpoint'ах
-- `Offsets` — с отступами
-- `Hidden/Block` — responsive visibility
-- `Playground` — интерактив
+### WithOffsets
+
+`stories/Col/examples/WithOffsetsExample.tsx`
+
+```tsx
+import React from "react";
+import { Col, Row } from "@sberbusiness/triplex-next";
+
+export const WithOffsetsExample = () => (
+    <div style={{ display: "flex", flexDirection: "column" }}>
+        <Row style={{ flexWrap: "nowrap" }}>
+            <Col size={4}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-4
+                </div>
+            </Col>
+            <Col size={4} offset={3}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-4 offset-3
+                </div>
+            </Col>
+        </Row>
+
+        <Row style={{ flexWrap: "nowrap" }}>
+            <Col size={3} offset={3}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-3 offset-3
+                </div>
+            </Col>
+            <Col size={3} offset={1}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-3 offset-1
+                </div>
+            </Col>
+        </Row>
+
+        <Row>
+            <Col size={6} offset={2}>
+                <div style={{ padding: "16px", textAlign: "center", backgroundColor: "rgb(255, 217, 160)" }}>
+                    size-6 offset-2
+                </div>
+            </Col>
+        </Row>
+    </div>
+);
+```
 
----
+### ResponsiveOffsets
+
+`stories/Col/examples/ResponsiveOffsetsExample.tsx`
+
+```tsx
+import React from "react";
+import { Col, Row } from "@sberbusiness/triplex-next";
+
+export const ResponsiveOffsetsExample = () => (
+    <div style={{ display: "flex", flexDirection: "column" }}>
+        <Row>
+            <Col sizeMd={6} offsetMd={3}>
+                <div style={{ padding: "16px", backgroundColor: "rgb(255, 217, 160)", textAlign: "center" }}>
+                    <div>sizeMd=6</div>
+                    <div>offsetMd=3</div>
+                </div>
+            </Col>
+        </Row>
+
+        <Row>
+            <Col sizeSm={6} offsetSm={4}>
+                <div style={{ padding: "16px", backgroundColor: "rgb(255, 217, 160)", textAlign: "center" }}>
+                    <div>sizeSm=6</div>
+                    <div>offsetSm=4</div>
+                </div>
+            </Col>
+        </Row>
+    </div>
+);
+```
 
-## История изменений
+### HiddenColumns
+
+`stories/Col/examples/HiddenColumnsExample.tsx`
+
+```tsx
+import React from "react";
+import { Col, Gap, Row } from "@sberbusiness/triplex-next";
+
+export const HiddenColumnsExample = () => (
+    <div style={{ display: "flex", flexDirection: "column" }}>
+        <Row>
+            <Col>
+                <div style={{ padding: "16px", backgroundColor: "rgb(255, 217, 160)", textAlign: "center" }}>
+                    Свойство hidden не установлено
+                </div>
+            </Col>
+        </Row>
+
+        <Row>
+            <Col hiddenSm>
+                <div style={{ padding: "16px", backgroundColor: "rgb(255, 217, 160)", textAlign: "center" }}>
+                    Свойство hidden установлено для экрана sm
+                </div>
+                <Gap size={16} />
+            </Col>
+
+            <Col hiddenMd>
+                <div style={{ padding: "16px", backgroundColor: "rgb(255, 217, 160)", textAlign: "center" }}>
+                    Свойство hidden установлено для экрана md
+                </div>
+                <Gap size={16} />
+            </Col>
+
+            <Col hiddenLg>
+                <div style={{ padding: "16px", backgroundColor: "rgb(255, 217, 160)", textAlign: "center" }}>
+                    Свойство hidden установлено для экрана lg
+                </div>
+                <Gap size={16} />
+            </Col>
+
+            <Col hiddenXl>
+                <div style={{ padding: "16px", backgroundColor: "rgb(255, 217, 160)", textAlign: "center" }}>
+                    Свойство hidden установлено для экрана xl
+                </div>
+            </Col>
+        </Row>
+    </div>
+);
+```
 
-| Дата | Изменение |
-|---|---|
-| 2026-04-18 | Создан документ |