Initial Commit
This commit is contained in:
84
openspec/changes/enterprise-react-skeleton/proposal.md
Normal file
84
openspec/changes/enterprise-react-skeleton/proposal.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 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
|
||||
```
|
||||
84
openspec/changes/enterprise-react-skeleton/tasks.md
Normal file
84
openspec/changes/enterprise-react-skeleton/tasks.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# Tasks: enterprise-react-skeleton
|
||||
|
||||
**Change ID**: enterprise-react-skeleton
|
||||
**Package**: `@suaveplan/react-skeleton`
|
||||
**Target path**: `react/ui/react-skeleton`
|
||||
**Prerequisite packages on Verdaccio**: `@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": ["**/*.css"]`, exports map (barrel + per-component subpaths + `./styles/skeleton.css`).
|
||||
- [ ] Dependencies: `@suaveplan/react-translate workspace:^`, `clsx catalog:ui`, `tailwind-merge catalog:ui`, `zod catalog:forms`, `tslib catalog:build`.
|
||||
- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
|
||||
|
||||
---
|
||||
|
||||
## 2. Utilities
|
||||
|
||||
- [ ] `src/utils/cn.ts` — `cn` helper (`clsx` + `twMerge`).
|
||||
- [ ] `src/styles/skeleton.css` — `@keyframes shimmer` + `.skeleton-animate` class; `@media (prefers-reduced-motion: reduce) { .skeleton-animate { animation: none; } }`.
|
||||
|
||||
---
|
||||
|
||||
## 3. Hook — `useSkeleton`
|
||||
|
||||
- [ ] Implement `useSkeleton(options: UseSkeletonOptions): UseSkeletonReturn` — manages `isLoading` state with optional `minDisplayMs` (prevents flash), exposes `startLoading()`, `stopLoading()`, `isLoading`.
|
||||
- [ ] Write `UseSkeletonOptionsSchema` Zod schema.
|
||||
- [ ] Write `use-skeleton.test.ts`: initial state, `startLoading`, `stopLoading`, `minDisplayMs` delay, SSR safety. `{ timeout: 5000 }`.
|
||||
- [ ] Write `use-skeleton.stories.tsx`: `default`, `playground` (toggle isLoading), `with-min-display`.
|
||||
- [ ] Write `use-skeleton.md` (≥200 words).
|
||||
|
||||
---
|
||||
|
||||
## 4. Components
|
||||
|
||||
### `Skeleton`
|
||||
|
||||
- [ ] Base shimmer block: `width`, `height`, `borderRadius` props, `cn` for class merge, `aria-hidden="true"`. Write test, stories (default, custom-size, rounded, playground), md.
|
||||
|
||||
### `SkeletonText`
|
||||
|
||||
- [ ] N-line text shimmer: `lines`, `lastLineWidth` props. Write test, stories, md.
|
||||
|
||||
### `SkeletonAvatar`
|
||||
|
||||
- [ ] Circle/rect avatar placeholder with `shape: 'circle' | 'square'`, `size: 'xs' | 'sm' | 'md' | 'lg' | 'xl'`. Write test, stories, md.
|
||||
|
||||
### `SkeletonCard`
|
||||
|
||||
- [ ] Card with image placeholder + 3-line text placeholder. Write test, stories, md.
|
||||
|
||||
### `SkeletonTable`
|
||||
|
||||
- [ ] Table grid placeholder: `rows`, `columns` props. Write test, stories, md.
|
||||
|
||||
---
|
||||
|
||||
## 5. E2E
|
||||
|
||||
- [ ] `e2e/skeleton.spec.ts` — Playwright: render each component, take screenshot snapshot (loading state); compare with baseline. Also render with `prefers-reduced-motion: reduce` and assert no `animation` style is applied.
|
||||
|
||||
---
|
||||
|
||||
## 6. Docs
|
||||
|
||||
- [ ] All co-located `.md` files per component and hook.
|
||||
- [ ] Root `README.md`: purpose, install, CSS import note, component inventory, API summary.
|
||||
|
||||
---
|
||||
|
||||
## 7. Verify and publish
|
||||
|
||||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-skeleton` — green.
|
||||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-skeleton` — 100%.
|
||||
- [ ] `bun scripts/publish.ts --package @suaveplan/react-skeleton`.
|
||||
- [ ] Archive change folder.
|
||||
Reference in New Issue
Block a user