# Tasks: enterprise-react-loading

**Change ID**: enterprise-react-loading
**Package**: `@suaveplan/react-loading`
**Target path**: `react/ui/react-loading`
**Prerequisite packages on Verdaccio**: `@suaveplan/events`, `@suaveplan/error`, `@suaveplan/react-translate`

---

## 0. Pre-flight (non-negotiable)

- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.

## 1. Scaffold

- [ ] Create directory tree per proposal layout.
- [ ] Write `package.json` at `0.1.0` with `"sideEffects": false`, exports map.
- [ ] Dependencies: `@suaveplan/events workspace:^`, `@suaveplan/error workspace:^`, `@suaveplan/react-translate workspace:^`, `zod catalog:forms`, `tslib catalog:build`.
- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.

---

## 2. Types

- [ ] Define `LoadingTask`: `{ id: string; label: string; weight: number; status: 'pending' | 'loading' | 'complete' | 'error' }`.
- [ ] Define `LoadingState`: `{ tasks: LoadingTask[]; progress: number; isComplete: boolean; currentTip: string | null }`.
- [ ] Define `LoadingConfig`: `{ tips?: string[]; tipIntervalMs?: number; minDisplayMs?: number }`.

---

## 3. Core — `LoadingTracker`

- [ ] Extend `EventEmitter` from `@suaveplan/events`.
- [ ] Methods: `addTask(task)`, `updateTask(id, partial)`, `completeTask(id)`, `errorTask(id, error?)`, `pause()`, `resume()`, `restart()`, `dispose()`.
- [ ] `progress` getter — weighted aggregate: `sum(complete.weight) / sum(all.weight)`.
- [ ] Tip rotation via `globalThis.setInterval` with `tipIntervalMs`; `dispose()` clears it.
- [ ] Emits `'change'` event on any state mutation; `'tipChange'` on tip rotation.
- [ ] Write `loading-tracker.test.ts` (≤500 lines): add/complete/error tasks, weighted progress, pause/resume/restart, dispose clears timer, SSR (no `window`). `{ timeout: 10000 }`.
- [ ] Write `loading-tracker.md`.

---

## 4. Hook — `useLoading`

- [ ] Binds `LoadingTracker` via `useSyncExternalStore` — subscribes to `'change'` event, snapshot returns current `LoadingState`.
- [ ] Write `use-loading.test.tsx`: initial state, task completion updates progress, subscribe fires re-render, unsubscribe on unmount. `{ timeout: 10000 }`.
- [ ] Write `use-loading.stories.tsx`: playground (add/complete tasks in story), default with pre-configured tracker.
- [ ] Write `use-loading.md`.

---

## 5. Components

### ProgressBar

- [ ] Animated progress fill (CSS transition); `prefers-reduced-motion` disables animation.
- [ ] Write test, stories (determinate, indeterminate, animated, reduced-motion), md.

### TipCarousel

- [ ] Displays `currentTip` from `LoadingState`; fade transition between tips.
- [ ] `prefers-reduced-motion` disables fade.
- [ ] Write test, stories, md.

### TaskList

- [ ] Lists tasks with status icons (pending/loading spinner/complete/error).
- [ ] Write test, stories (all-statuses, empty, loading), md.

### LoadingScreen

- [ ] Full-viewport overlay: accepts `tracker` prop; renders `ProgressBar`, `TipCarousel`, `TaskList` (optional per prop flags).
- [ ] Auto-hides when `isComplete` + optional `hideDelayMs`.
- [ ] Write test, stories (default, with-tasks, with-tips, playground), md.

---

## 6. Integration

- [ ] `tests/integration.test.tsx` — create `LoadingTracker`, add 3 weighted tasks, render `LoadingScreen`, complete tasks one by one, verify `ProgressBar` value and eventual hide.

---

## 7. Verify and publish

- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-loading` — green.
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-loading` — 100%.
- [ ] `bun scripts/publish.ts --package @suaveplan/react-loading`.
- [ ] Archive change folder.