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

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

SSR safety — LoadingTracker uses globalThis.setInterval; dispose() method clears timers.
pause() / resume() / restart() on LoadingTracker for paused progress.
useLoading tests — full coverage of subscribe/unsubscribe lifecycle.
Storybook — stories for every component + hook.

File layout

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

2.7 KiB Raw Blame History