87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
# OpenSpec Change: enterprise-react-loading
|
|
|
|
- **Change ID**: enterprise-react-loading
|
|
- **Package**: `@suaveplan/react-loading`
|
|
- **Category**: react
|
|
- **Target path**: `react/ui/react-loading`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-loading.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/react-loading` on genesis from scratch at enterprise quality. Weighted loading-progress state management for loading-screen UX: `LoadingTracker` (extends `@suaveplan/events` EventEmitter), `useLoading` hook (`useSyncExternalStore`), and a full set of presentational components (`LoadingScreen`, `ProgressBar`, `TaskList`, `TipCarousel`). Genesis adds the missing UI components, `useLoading` hook tests, SSR safety, `prefers-reduced-motion` support, and Storybook coverage.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/events` (`workspace:^`) | `EventEmitter` base for `LoadingTracker` |
|
|
| `@suaveplan/error` (`workspace:^`) | `LoadingError` |
|
|
| `@suaveplan/react-translate` (`workspace:^`) | i18n for tip/loading copy |
|
|
| `zod` (`catalog:forms`) | Config schemas |
|
|
|
|
External: `tslib catalog:build`. React 18 peer.
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
```ts
|
|
LoadingTracker — EventEmitter subclass with task management + tip rotation
|
|
useLoading — useSyncExternalStore binding → LoadingState
|
|
LoadingConfig, LoadingState, LoadingTask
|
|
```
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
### Presentational components (new)
|
|
|
|
- `LoadingScreen` — full-viewport overlay with spinner/progress/tip
|
|
- `ProgressBar` — weighted aggregate progress bar
|
|
- `TaskList` — shows each task + its status badge
|
|
- `TipCarousel` — rotating tip display
|
|
|
|
### Fixes
|
|
|
|
1. **SSR safety** — `LoadingTracker` uses `globalThis.setInterval`; `dispose()` method clears timers.
|
|
2. **`pause()` / `resume()` / `restart()`** on `LoadingTracker` for paused progress.
|
|
3. **`useLoading` tests** — full coverage of subscribe/unsubscribe lifecycle.
|
|
4. **Storybook** — stories for every component + hook.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
react/ui/react-loading/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
core/
|
|
loading-tracker/ (ts + types + md + test + index)
|
|
hooks/
|
|
use-loading/ (ts + types + md + test + stories + index)
|
|
components/
|
|
loading-screen/ (tsx + types + md + test + stories + index)
|
|
progress-bar/ (tsx + types + md + test + stories + index)
|
|
task-list/ (tsx + types + md + test + stories + index)
|
|
tip-carousel/ (tsx + types + md + test + stories + index)
|
|
tests/
|
|
integration.test.tsx
|
|
```
|