# 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
```