8.9 KiB
UI-каталог Storybook
Storybook 10.6.0 показывает реальные компоненты и композиции WealthLedger на общей визуальной основе приложения без входа и подключения backend.
Запуск и сборка
Из frontend/ выберите Node 22 и установите зависимости из lockfile:
nvm use --silent
npm ci
npm run dev:catalog
Storybook запускается на localhost:6006; браузер автоматически не открывается. Отдельная статическая сборка и её preview:
npm run build:catalog
npm run preview:catalog
Результат находится в frontend/storybook-static/, вход — index.html.
Команда preview выводит адрес статической витрины в терминале. Обычный
npm run build сохраняет приложение в frontend/dist/; stories не входят
в его entrypoint и продуктовые маршруты. Публикация отдельным сервисом не настроена.
Компоненты и работа с примерами
В дереве Storybook доступны шесть групп:
| Группа | Что показывает |
|---|---|
BrokerageAccountList |
Счета со сводкой по нескольким валютам, недоступной или пустой сводкой и длинным названием. |
PositionCard |
Акцию с положительным результатом, облигацию с отрицательным, прочий инструмент и позицию без оценки. |
RecentEvents |
Полученные события, загрузку, ошибку, пустой результат и неизвестную ожидаемую сумму. |
PortfolioRefreshState с PortfolioTotals |
Сохранённые суммы при фоновом обновлении и его ошибке, локальный retry. |
StateView |
Пустое состояние и ошибку, с действием и без него. |
AccountPageLoading через LoadingSkeleton |
Реальный skeleton заголовка, сводки и строк страницы счёта. |
Стандартные Mantine primitives видны внутри этих компонентов. Отдельных копий библиотечных demos или обёрток ради каталога нет. Каталог не заявляет полноту: отсутствие компонента не запрещает его использование в приложении.
Выберите историю в дереве, чтобы открыть её состояние в Canvas. Docs описывает
назначение, ограничения и свойства группы, а также её примеры. Controls меняют
разрешённые свойства; синтетические объекты и callbacks недоступны для редактирования.
Например, kind у PositionCard меняет вариант представления фиксированной позиции,
а разные данные инструмента выбираются отдельной историей. Actions регистрирует
локальные callbacks кнопок и retry.
Для возврата изменённых свойств используйте штатный reset args в Controls; для повторного монтирования примера — remount в панели Canvas. Размер preview можно менять без сброса args. Изолированный iframe позволяет отдельно проверить компонент на узком экране; навигацией самой витрины управляет Storybook.
Preview использует экспортируемую app theme, Mantine CSS, application styles, русскую i18n и фиксированную светлую схему без чтения сохранённой темы. Stories находятся рядом с существующими presentation components и импортируют их реализации. Отдельных tokens нет. Error StateView сохраняет alert semantics, skeleton — busy-область с декоративными фигурами без фокуса. Проверяйте доступность действий и ссылок с клавиатуры вместе с визуальным состоянием.
Границы и сопровождение
Все счета, позиции, события и суммы вымышлены. Stories не читают application storage, cookies, секреты или реальные пользовательские данные. Внешние логотипы не загружаются: примеры используют буквенный fallback существующего компонента. Storybook manager может сохранять собственные настройки витрины; telemetry отключена.
Stories не подключают AuthProvider, QueryClient, API clients и исполняемые VM. Действия не обращаются к application API. Ссылки меняют только локальный маршрут MemoryRouter: страница назначения не отображается, URL приложения не меняется. Retry демонстрирует локальный callback и не доказывает восстановление API или полный пользовательский сценарий. Loading/error относятся к выбранному примеру.
Композиция сохранённых сумм показывает представление Client Cached Snapshot; сам query lifecycle не исполняется. Для запросных экранов действует UI Pattern: сохранение данных при refetch, structural skeleton для initial loading и контекстный индикатор mutation. Skeleton конкретной страницы остаётся ответственностью страницы.
При изменении включённого компонента проверяйте вместе с ним его пример,
описание и ограничения. npm run verify включает Storybook в strict TypeScript,
Biome, Vitest, Knip и dependency-cruiser, затем собирает приложение и статическую
витрину. Основная проверка FSD сохраняется; отдельный deps:storybook проверяет
runtime graph stories и preview, запрещая достижимость application data.
Type-only ссылки на типы VM и API стираются и не запускают запросы.
Declarative stories не требуют искусственного unit coverage, а продуктовые
coverage floors сохраняются. Клавиатура, реальные размеры и визуальное
соответствие проверяются в браузере; автоматической visual regression нет.
Использование в UI change
Каталог помогает выбрать существующий компонент, его состояние и ограничения. Затем в Design своего change зафиксируйте применимость UI/UX, выбранную конфигурацию, затронутые экраны, состояния, взаимодействия и адаптивное поведение. Ссылка на текущую story помогает исследовать реализацию; согласованную версию решения сохраняет единый пакет Design. Его материалы получает Implementation и независимый reviewer через OpenSpec lifecycle.
Каталог и этот процесс доступны для совместного использования в отдельном небольшом UI change. Его выбирает владелец; он проходит собственные planning approvals. Это готовность к пилоту: продуктовая фича автоматически не назначена, сквозной продуктовый пилот не проводился и его успешность не заявляется.