feat(registry): seed components — grain-overlay, shimmer-sweep, grid-pixelate-wipe (#260)

## What

Three reusable effect components for the registry, each with a snippet HTML and companion `demo.html`:

| Component | Description |
|-----------|-------------|
| `grain-overlay` | Animated film grain texture overlay (CSS keyframes, extracted from warm-grain example) |
| `shimmer-sweep` | CSS gradient light sweep across text/elements, driven by GSAP custom property animation |
| `grid-pixelate-wipe` | Grid-based dissolve transition — screen breaks into 16×9 squares that scale in/out with stagger |

Establishes the `demo.html` convention in `CONTRIBUTING.md`.

## Why

Phase B of the catalog plan — seed the first components in the registry. Components are effect snippets that get merged into existing compositions (vs. blocks which are standalone sub-compositions).

## How

- **grain-overlay**: Extracted the grain texture pattern from the warm-grain example. Uses a 200% oversized tiled texture with `steps(1)` keyframe animation for the random-noise effect.
- **shimmer-sweep**: Original implementation using CSS custom properties (`--shimmer-pos`) animated by GSAP. The gradient mask uses `mix-blend-mode: overlay` for a natural light sweep. Auto-injects `.shimmer-mask` elements into `.shimmer-sweep-target` wrappers.
- **grid-pixelate-wipe**: Creates a 16×9 CSS Grid of cells, animated with GSAP stagger. Users drive `.grid-cell` `scale` directly in their timeline.

Simplify review addressed: scoped `.grain-texture` under `#grain-overlay`, scoped `.grid-cell` under `#grid-pixelate-overlay`, removed `window.gridPixelateIn/Out` globals in favor of direct GSAP patterns.

Each component ships a `demo.html` — a standalone composition that previews the effect and doubles as a fixture for the CI preview pipeline (PR 8).

## Test plan

- [x] `hyperframes add grain-overlay` installs to `compositions/components/grain-overlay.html`
- [x] `hyperframes add shimmer-sweep` installs to `compositions/components/shimmer-sweep.html`
- [x] `hyperframes add grid-pixelate-wipe` installs to `compositions/components/grid-pixelate-wipe.html`
- [x] All three return correct `--json` output with snippet and type info
- [x] `registry-item.json` files validate against the JSON Schema
- [x] `demo.html` files are self-contained with correct `data-composition-id` and `window.__timelines` registration
- [x] `oxfmt --check` and `oxlint` pass on all files
- [x] `CONTRIBUTING.md` documents the `demo.html` convention and registry item checklist
This commit is contained in:
James Russo
2026-04-14 16:18:22 -07:00
committed by GitHub
parent 4685e5cd74
commit b0f754a7f7
11 changed files with 811 additions and 0 deletions
@@ -0,0 +1,65 @@
<!--
Shimmer Sweep — animated light pass across text or elements.
Usage: wrap your text element with class="shimmer-sweep-target" and
paste this snippet into your composition. The GSAP timeline drives
the sweep position for deterministic frame-by-frame rendering.
Customize:
- --shimmer-color: highlight color (default rgba(255,255,255,0.6))
- --shimmer-width: highlight band width as % (default 20%)
- --shimmer-angle: sweep angle (default 120deg)
- Timeline duration/ease: adjust in the script below
-->
<style>
.shimmer-sweep-target {
position: relative;
display: inline-block;
}
.shimmer-sweep-target .shimmer-mask {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
pointer-events: none;
background: linear-gradient(
var(--shimmer-angle, 120deg),
transparent 0%,
transparent calc(var(--shimmer-pos, -20%) - var(--shimmer-width, 20%) / 2),
var(--shimmer-color, rgba(255, 255, 255, 0.6)) var(--shimmer-pos, -20%),
transparent calc(var(--shimmer-pos, -20%) + var(--shimmer-width, 20%) / 2),
transparent 100%
);
mix-blend-mode: overlay;
}
</style>
<script>
(function () {
// Auto-inject .shimmer-mask into every .shimmer-sweep-target
document.querySelectorAll(".shimmer-sweep-target").forEach((el) => {
if (!el.querySelector(".shimmer-mask")) {
const mask = document.createElement("div");
mask.className = "shimmer-mask";
el.appendChild(mask);
}
});
})();
</script>
<!--
Timeline integration example (add to your composition's GSAP timeline):
// Single sweep from left to right
tl.fromTo(".shimmer-sweep-target", {
"--shimmer-pos": "-20%",
}, {
"--shimmer-pos": "120%",
duration: 1.2,
ease: "power2.inOut",
stagger: 0.15,
}, startTime);
-->