Initial Commit
This commit is contained in:
86
openspec/changes/enterprise-react-loading/proposal.md
Normal file
86
openspec/changes/enterprise-react-loading/proposal.md
Normal file
@@ -0,0 +1,86 @@
|
||||
# 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
|
||||
```
|
||||
91
openspec/changes/enterprise-react-loading/tasks.md
Normal file
91
openspec/changes/enterprise-react-loading/tasks.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user