Document portable SDD workflow and Storybook catalog
This commit is contained in:
@@ -0,0 +1,99 @@
|
||||
# UI-каталог Storybook
|
||||
|
||||
Storybook 10.6.0 показывает реальные компоненты и композиции WealthLedger
|
||||
на общей визуальной основе приложения без входа и подключения backend.
|
||||
|
||||
## Запуск и сборка
|
||||
|
||||
Из `frontend/` выберите Node 22 и установите зависимости из lockfile:
|
||||
|
||||
```bash
|
||||
nvm use --silent
|
||||
npm ci
|
||||
npm run dev:catalog
|
||||
```
|
||||
|
||||
Storybook запускается на [localhost:6006](http://localhost:6006); браузер
|
||||
автоматически не открывается. Отдельная статическая сборка и её preview:
|
||||
|
||||
```bash
|
||||
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](../../frontend/docs/UI-PATTERN.md): сохранение данных при 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/UX. Новый contract
|
||||
визуального пакета Design пока не поставлен: он ожидает завершения
|
||||
`optimize-session-oriented-sdd-v2` и сверки с его authority. Совместная готовность
|
||||
каталога и обновлённого процесса к пилоту ещё не подтверждена; продуктовый пилот
|
||||
не проводился. Действующий процесс описан в
|
||||
[OpenSpec lifecycle](openspec-authority-and-lifecycle.md).
|
||||
Reference in New Issue
Block a user