Initial Commit

openspec/changes/enterprise-react-loading/tasks.md

@@ -0,0 +1,91 @@
+# 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.