Triplex-next

Версионирование

• Разработка версии для React 18 ведется в ветке main. Релизы с версии 1.0.0 до 2.0.0(не включительно).
• Разработка версии для React 17 ведется в ветке release-0. Релизы с версии 0.10.0 до 1.0.0(не включительно).

🚀 Установка

npm install @sberbusiness/triplex-next @sberbusiness/icons-next

Импортировать стили

import '@sberbusiness/triplex-next/styles/triplex-next.css';
import '@sberbusiness/icons-next/styles/icons.css';

🔤 Шрифты

Компоненты Typography используют шрифты SBSansDisplay, SBSansText и SBSansTextMono. Для корректного отображения необходимо подключить шрифты в вашем проекте:

@font-face {
    font-family: 'SBSansDisplay';
    src: url('node_modules/@sberbusiness/triplex-next/assets/fonts/SBSansDisplay-Regular.woff2') format('woff2');
    font-weight: normal;
    font-style: normal;
}

@font-face {
    font-family: 'SBSansDisplayMedium';
    src: url('node_modules/@sberbusiness/triplex-next/assets/fonts/SBSansDisplay-Medium.woff2') format('woff2');
    font-weight: 500;
    font-style: normal;
}

@font-face {
    font-family: 'SBSansDisplaySemibold';
    src: url('node_modules/@sberbusiness/triplex-next/assets/fonts/SBSansDisplay-SemiBold.woff2') format('woff2');
    font-weight: 600;
    font-style: normal;
}

@font-face {
    font-family: 'SBSansDisplayBold';
    src: url('node_modules/@sberbusiness/triplex-next/assets/fonts/SBSansDisplay-Bold.woff2') format('woff2');
    font-weight: 700;
    font-style: normal;
}

@font-face {
    font-family: 'SBSansText';
    src: url('node_modules/@sberbusiness/triplex-next/assets/fonts/SBSansText-Regular.woff2') format('woff2');
    font-weight: normal;
    font-style: normal;
}

@font-face {
    font-family: 'SBSansTextSemibold';
    src: url('node_modules/@sberbusiness/triplex-next/assets/fonts/SBSansText-Semibold.woff2') format('woff2');
    font-weight: 600;
    font-style: normal;
}

@font-face {
    font-family: 'SBSansTextMono';
    src: url('node_modules/@sberbusiness/triplex-next/assets/fonts/SBSansTextMono-Regular.woff2') format('woff2');
    font-weight: normal;
    font-style: normal;
}

📁 Структура

src/
  components/
    ComponentName/
      index.ts
      ComponentName.tsx
      styles/ComponentName.module.less
      __tests__/ComponentName.test.tsx

Каждый компонент должен иметь собственный index.ts, чтобы поддерживать генерацию exports в package.json.

📜 Скрипты

| Скрипт | Назначение | |-------|------------| | npm run build | Сборка компонентов и style.css в dist/ | | npm run storybook | Локальный просмотр компонентов | | npm run storybook:build | Сборка Storybook в storybook-static/ | | npm run test-visual:docker | Визуальные тесты в Docker-контейнере (сборка + запуск) | | npm run test-visual:docker:update | Обновить baseline-скриншоты в Docker-контейнере | | npm run test-visual:debug | Отладка визуальных тестов локально (Storybook должен быть запущен) | | npm run test-visual:ci | Визуальные тесты — используется в CI и Docker | | npm run test-visual:ci:update | Обновление baseline — используется в CI и Docker |

🧱 Добавление нового компонента

1. Создать каталог:

src/components/Alert/

2. Добавить файлы:

Alert.tsx
styles/Alert.module.less
index.ts         ← обязательный!

3. Указать экспорт в src/index.ts:

export * from './components/Alert';

🧪 Тестирование

Проект использует Vitest для unit-тестирования и Testing Library для тестирования компонентов.

Визуальное регрессионное тестирование

Для визуального тестирования используется @storybook/test-runner + jest-image-snapshot.

Скриншоты снимаются на двух viewport'ах: XS (575px) и XL (1200px). Baseline-скриншоты хранятся в папке __screenshots__/ и коммитятся в git. Diff-изображения при падении сохраняются в __screenshots__/__diff__/ и игнорируются git'ом.

Важно: baseline-скриншоты создаются и обновляются только через Docker или CI (Linux). Локальные скриншоты на macOS несовместимы из-за разного рендеринга шрифтов.

Как обновить baseline-скриншоты

Через Docker (рекомендуется):

npm run test-visual:docker:update

Через CI:

1. Запушить ветку с изменениями
2. В GitHub → Actions → Update Visual Snapshots → Run workflow → выбрать ветку
3. Воркфлоу пересоздаст скриншоты и сделает коммит в ту же ветку

Как запустить визуальные тесты

npm run test-visual:docker           # Проверка через Docker
npm run test-visual:docker:update    # Обновление baseline через Docker

Как запустить тесты только для одного компонента

test-storybook не поддерживает фильтрацию по имени стори. Единственный способ — временно сузить glob в .storybook/main.ts:

// Временно, только для одного компонента:
stories: ["../stories/Link/**/*.stories.@(ts|tsx|mdx)"],

// Вернуть обратно после:
stories: ["../stories/**/*.stories.@(ts|tsx|mdx)", "../stories/**/*.mdx"],

Затем запустить тесты, как обычно:

npm run test-visual:docker           # через Docker
npm run test-visual:debug            # локально (Storybook должен быть запущен)

Не забудьте вернуть glob обратно перед коммитом.

CI воркфлоу

Визуальные тесты в CI работают на собранной (build) версии Storybook, а не на dev-сервере — это исключает race conditions при загрузке модулей.

| Воркфлоу | Триггер | Что делает | |---|---|---| | visual-test.yml | Каждый PR | Прогоняет тесты, загружает диффы как артефакты при падении | | visual-update.yml | Ручной запуск (workflow_dispatch) | Пересоздаёт baselines и коммитит их в ветку |

Как отлаживать локально

npm run storybook             # в одном терминале
npm run test-visual:debug     # в другом (с PWDEBUG=1)

Для отладки одного компонента — сузить glob как описано выше.

Как исключить story из тестирования

// Конкретную story
export const MyStory: Story = {
    parameters: {
        testRunner: { skip: true },
    },
};

// Все stories компонента (в default export / meta)
const meta: Meta<typeof Button> = {
    component: Button,
    parameters: {
        testRunner: { skip: true },
    },
};

Как запустить тесты локально

npm run test-e2e                     # Запуск e2e тестов
npm run test-unit                    # Запуск unit тестов
npm run test-unit:watch              # Запуск unit тестов в режиме наблюдения
npm run test-unit:coverage           # Запуск unit тестов с отчётом о покрытии
npm run test-visual:docker           # Визуальные регрессионные тесты (Docker)
npm run test-visual:docker:update    # Обновить baseline-скриншоты (Docker)