85 lines
2.7 KiB
Markdown
85 lines
2.7 KiB
Markdown
# OpenSpec Change: enterprise-react-skeleton
|
|
|
|
- **Change ID**: enterprise-react-skeleton
|
|
- **Package**: `@suaveplan/react-skeleton`
|
|
- **Category**: react
|
|
- **Target path**: `react/ui/react-skeleton`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-skeleton.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/react-skeleton` on genesis from scratch at enterprise quality. Content loading skeleton / shimmer components: `Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonTable`, and a headless `useSkeleton` hook. Every primitive has a per-subpath export for tree-shaking. Styles published as `./styles/skeleton.css`. Genesis adds a `useSkeleton` playground story, Playwright visual-regression snapshots, `prefers-reduced-motion` shimmer freeze, and 100% test coverage.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/react-translate` (`workspace:^`) | i18n for aria-labels |
|
|
| `zod` (`catalog:forms`) | Options schemas |
|
|
|
|
External: `clsx catalog:ui`, `tailwind-merge catalog:ui`, `tslib catalog:build`. React 18 peer.
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
### Components
|
|
|
|
`Skeleton`, `SkeletonText`, `SkeletonAvatar`, `SkeletonCard`, `SkeletonTable`
|
|
|
|
### Hooks
|
|
|
|
`useSkeleton`
|
|
|
|
### Types
|
|
|
|
`SkeletonAnimation`, `SkeletonProps`, `SkeletonAvatarProps`, `SkeletonAvatarShape`, `SkeletonAvatarSize`, `SkeletonCardProps`, `SkeletonTableProps`, `SkeletonTextProps`, `UseSkeletonOptions`, `UseSkeletonReturn`
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
1. **`prefers-reduced-motion` freeze** — when reduced motion is detected, `animation: none` overrides the shimmer keyframe. Documented in CSS and tested.
|
|
2. **`useSkeleton` playground story** — exercises `isLoading` toggle, custom shape prop.
|
|
3. **Playwright visual-regression snapshots** — `e2e/skeleton.spec.ts` captures snapshots of every component in loading + loaded states.
|
|
4. **Zod `UseSkeletonOptionsSchema`** — validates hook options at runtime.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
react/ui/react-skeleton/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
components/
|
|
skeleton/ (tsx + types + md + test + stories + index)
|
|
skeleton-text/ (tsx + types + md + test + stories + index)
|
|
skeleton-avatar/ (tsx + types + md + test + stories + index)
|
|
skeleton-card/ (tsx + types + md + test + stories + index)
|
|
skeleton-table/ (tsx + types + md + test + stories + index)
|
|
hooks/
|
|
use-skeleton/ (ts + types + md + test + stories + index)
|
|
utils/
|
|
cn.ts
|
|
styles/
|
|
skeleton.css
|
|
e2e/
|
|
skeleton.spec.ts
|
|
```
|