opencode-skills-collection 3.0.35 → 3.0.37

package/bundled-skills/vercel-react-view-transitions/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: vercel-react-view-transitions
+description: "Guide React and Next.js view transitions, shared element animations, route transitions, transition types, and reduced-motion-safe UI state animation."
+risk: safe
+source: "https://github.com/vercel-labs/agent-skills"
+date_added: "2026-06-02"
+---
+
+# React View Transitions
+
+Animate between UI states using the browser's native `document.startViewTransition`. Declare *what* with `<ViewTransition>`, trigger *when* with `startTransition` / `useDeferredValue` / `Suspense`, control *how* with CSS classes. Unsupported browsers skip animations gracefully.
+
+## When to Use
+- Use this skill when the task matches this description: Guide React and Next.js view transitions, shared element animations, route transitions, transition types, and reduced-motion-safe UI state animation.
+
+## When to Animate
+
+Every `<ViewTransition>` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.
+
+Implement **all** applicable patterns from this list, in this order:
+
+| Priority | Pattern | What it communicates |
+|----------|---------|---------------------|
+| 1 | **Shared element** (`name`) | "Same thing — going deeper" |
+| 2 | **Suspense reveal** | "Data loaded" |
+| 3 | **List identity** (per-item `key`) | "Same items, new arrangement" |
+| 4 | **State change** (`enter`/`exit`) | "Something appeared/disappeared" |
+| 5 | **Route change** (layout-level) | "Going to a new place" |
+
+This is an implementation order, not a "pick one" list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.
+
+### Choosing Animation Style
+
+| Context | Animation | Why |
+|---------|-----------|-----|
+| Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth |
+| Lateral navigation (tab-to-tab) | Bare `<ViewTransition>` (fade) or `default="none"` | No depth to communicate |
+| Suspense reveal | `enter`/`exit` string props | Content arriving |
+| Revalidation / background refresh | `default="none"` | Silent — no animation needed |
+
+Reserve directional slides for hierarchical navigation (list → detail) and ordered sequences (prev/next photo, carousel, paginated results). For ordered sequences, the direction communicates position: "next" slides from right, "previous" from left. Lateral/unordered navigation (tab-to-tab) should not use directional slides — it falsely implies spatial depth.
+
+---
+
+## Availability
+
+- **Next.js:** Do **not** install `react@canary` — the App Router already bundles React canary internally. `ViewTransition` works out of the box. `npm ls react` may show a stable-looking version; this is expected.
+- **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
+- Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.
+
+---
+
+## Implementation Workflow
+
+When adding view transitions to an existing app, **follow `references/implementation.md` step by step.** Start with the audit — do not skip it. Copy the CSS recipes from `references/css-recipes.md` into the global stylesheet — do not write your own animation CSS.
+
+---
+
+## Core Concepts
+
+### The `<ViewTransition>` Component
+
+```jsx
+import { ViewTransition } from 'react';
+
+<ViewTransition>
+  <Component />
+</ViewTransition>
+```
+
+React auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself.
+
+### Animation Triggers
+
+| Trigger | When it fires |
+|---------|--------------|
+| **enter** | `<ViewTransition>` first inserted during a Transition |
+| **exit** | `<ViewTransition>` first removed during a Transition |
+| **update** | DOM mutations inside a `<ViewTransition>`. With nested VTs, mutation applies to the innermost one |
+| **share** | Named VT unmounts and another with same `name` mounts in the same Transition |
+
+Only `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate.
+
+### Critical Placement Rule
+
+`<ViewTransition>` only activates enter/exit if it appears **before any DOM nodes**:
+
+```jsx
+// Works
+<ViewTransition enter="auto" exit="auto">
+  <div>Content</div>
+</ViewTransition>
+
+// Broken — div wraps the VT, suppressing enter/exit
+<div>
+  <ViewTransition enter="auto" exit="auto">
+    <div>Content</div>
+  </ViewTransition>
+</div>
+```
+
+---
+
+## Styling with View Transition Classes
+
+### Props
+
+Values: `"auto"` (browser cross-fade), `"none"` (disabled), `"class-name"` (custom CSS), or `{ [type]: value }` for type-specific animations.
+
+```jsx
+<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
+```
+
+If `default` is `"none"`, all triggers are off unless explicitly listed.
+
+### CSS Pseudo-Elements
+
+- `::view-transition-old(.class)` — outgoing snapshot
+- `::view-transition-new(.class)` — incoming snapshot
+- `::view-transition-group(.class)` — container
+- `::view-transition-image-pair(.class)` — old + new pair
+
+See `references/css-recipes.md` for ready-to-use animation recipes.
+
+---
+
+## Transition Types
+
+Tag transitions with `addTransitionType` so VTs can pick different animations based on context. Call it multiple times to stack types — different VTs in the tree react to different types:
+
+```jsx
+startTransition(() => {
+  addTransitionType('nav-forward');
+  addTransitionType('select-item');
+  router.push('/detail/1');
+});
+```
+
+Pass an object to map types to CSS classes. Works on `enter`, `exit`, **and** `share`:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
+  exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
+  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
+  default="none"
+>
+  <Page />
+</ViewTransition>
+```
+
+`enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally:
+
+```jsx
+<ViewTransition
+  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
+  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+  default="none"
+>
+```
+
+**TypeScript:** `ViewTransitionClassPerType` requires a `default` key in the object.
+
+For apps with multiple pages, extract the type-keyed VT into a reusable wrapper:
+
+```jsx
+export function DirectionalTransition({ children }: { children: React.ReactNode }) {
+  return (
+    <ViewTransition
+      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
+      default="none"
+    >
+      {children}
+    </ViewTransition>
+  );
+}
+```
+
+### `router.back()` and Browser Back Button
+
+`router.back()` and the browser's back/forward buttons do **not** trigger view transitions (`popstate` is synchronous, incompatible with `startViewTransition`). Use `router.push()` with an explicit URL instead.
+
+### Types and Suspense
+
+Types are available during navigation but **not** during subsequent Suspense reveals (separate transitions, no type). Use type maps for page-level enter/exit; use simple string props for Suspense reveals.
+
+---
+
+## Shared Element Transitions
+
+Same `name` on two VTs — one unmounting, one mounting — creates a shared element morph:
+
+```jsx
+<ViewTransition name="hero-image">
+  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
+</ViewTransition>
+
+// On the other view — same name
+<ViewTransition name="hero-image">
+  <img src="/full.jpg" />
+</ViewTransition>
+```
+
+- Only one VT with a given `name` can be mounted at a time — use unique names (`photo-${id}`). Watch for reusable components: if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Either make the name conditional (via a prop) or move the named VT out of the shared component into the specific consumer.
+- `share` takes precedence over `enter`/`exit`. Think through each navigation path: when no matching pair forms (e.g., the target page doesn't have the same name), `enter`/`exit` fires instead. Consider whether the element needs a fallback animation for those paths.
+- Never use a fade-out exit on pages with shared morphs — use a directional slide instead.
+
+---
+
+## Common Patterns
+
+### Enter/Exit
+
+```jsx
+{show && (
+  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
+)}
+```
+
+### List Reorder
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
+))}
+```
+
+Trigger inside `startTransition`. Avoid wrapper `<div>`s between list and VT.
+
+### Composing Shared Elements with List Identity
+
+Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element (e.g., an image that morphs into a detail view), use two nested `<ViewTransition>` boundaries:
+
+```jsx
+{items.map(item => (
+  <ViewTransition key={item.id}>                                      {/* list identity */}
+    <Link href={`/items/${item.id}`}>
+      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* shared element */}
+        <Image src={item.image} />
+      </ViewTransition>
+      <p>{item.name}</p>
+    </Link>
+  </ViewTransition>
+))}
+```
+
+The outer VT handles list reorder/enter animations. The inner VT handles the cross-route shared element morph. Missing either layer means that animation silently doesn't happen.
+
+### Force Re-Enter with `key`
+
+```jsx
+<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
+  <ResultsGrid />
+</ViewTransition>
+```
+
+**Caution:** If wrapping `<Suspense>`, changing `key` remounts the boundary and refetches.
+
+### Suspense Fallback to Content
+
+Simple cross-fade:
+```jsx
+<ViewTransition>
+  <Suspense fallback={<Skeleton />}><Content /></Suspense>
+</ViewTransition>
+```
+
+Directional reveal:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
+</Suspense>
+```
+
+For more patterns, see `references/patterns.md`.
+
+---
+
+## How Multiple VTs Interact
+
+Every VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions (navigation vs later Suspense resolve) don't compete.
+
+### Use `default="none"` Liberally
+
+Without it, every VT fires the browser cross-fade on **every** transition — Suspense resolves, `useDeferredValue` updates, background revalidations. Always use `default="none"` and explicitly enable only desired triggers.
+
+### Two Patterns Coexist
+
+**Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation.
+**Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type).
+
+They coexist because they fire at different moments. `default="none"` on both prevents cross-interference. Always pair `enter` with `exit`. Place directional VTs in page components, not layouts.
+
+### Nested VT Limitation
+
+When a parent VT exits, nested VTs inside it do **not** fire their own enter/exit — only the outermost VT animates. Per-item staggered animations during page navigation are not possible today. See [react#36135](https://github.com/facebook/react/pull/36135) for an experimental opt-in fix.
+
+---
+
+## Next.js Integration
+
+For Next.js setup (`experimental.viewTransition` flag, `transitionTypes` prop on `next/link`, App Router patterns, Server Components), see `references/nextjs.md`.
+
+---
+
+## Accessibility
+
+Always add the reduced motion CSS from `references/css-recipes.md` to your global stylesheet.
+
+---
+
+## Reference Files
+
+- **`references/implementation.md`** — Step-by-step implementation workflow.
+- **`references/patterns.md`** — Patterns, animation timing, events API, troubleshooting.
+- **`references/css-recipes.md`** — Ready-to-use CSS animation recipes.
+- **`references/nextjs.md`** — Next.js App Router patterns and Server Component details.
+
+## Full Compiled Document
+
+For the complete guide with all reference files expanded: `AGENTS.md`
+
+## Limitations
+- Use this skill only when the task clearly matches the scope described above.
+- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

package/bundled-skills/vercel-react-view-transitions/references/css-recipes.md

@@ -0,0 +1,242 @@
+# CSS Animation Recipes
+
+Ready-to-use CSS for `<ViewTransition>` props. Copy into your global stylesheet.
+
+---
+
+## Timing Variables
+
+```css
+:root {
+  --duration-exit: 150ms;
+  --duration-enter: 210ms;
+  --duration-move: 400ms;
+}
+```
+
+### Shared Keyframes
+
+```css
+@keyframes fade {
+  from { filter: blur(3px); opacity: 0; }
+  to { filter: blur(0); opacity: 1; }
+}
+
+@keyframes slide {
+  from { translate: var(--slide-offset); }
+  to { translate: 0; }
+}
+
+@keyframes slide-y {
+  from { transform: translateY(var(--slide-y-offset, 10px)); }
+  to { transform: translateY(0); }
+}
+```
+
+---
+
+## Fade
+
+```css
+::view-transition-old(.fade-out) {
+  animation: var(--duration-exit) ease-in fade reverse;
+}
+::view-transition-new(.fade-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both fade;
+}
+```
+
+Usage: `<ViewTransition enter="fade-in" exit="fade-out" />`
+
+---
+
+## Slide (Vertical)
+
+```css
+::view-transition-old(.slide-down) {
+  animation:
+    var(--duration-exit) ease-out both fade reverse,
+    var(--duration-exit) ease-out both slide-y reverse;
+}
+::view-transition-new(.slide-up) {
+  animation:
+    var(--duration-enter) ease-in var(--duration-exit) both fade,
+    var(--duration-move) ease-in both slide-y;
+}
+```
+
+Usage:
+```jsx
+<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
+  <ViewTransition default="none" enter="slide-up"><Content /></ViewTransition>
+</Suspense>
+```
+
+---
+
+## Directional Navigation
+
+### Separate Enter/Exit Classes
+
+```css
+::view-transition-new(.slide-from-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+
+::view-transition-new(.slide-from-left) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+::view-transition-old(.slide-to-right) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+```
+
+### Single-Class Approach
+
+```css
+::view-transition-old(.nav-forward) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-forward) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+
+::view-transition-old(.nav-back) {
+  --slide-offset: 60px;
+  animation:
+    var(--duration-exit) ease-in both fade reverse,
+    var(--duration-move) ease-in-out both slide reverse;
+}
+::view-transition-new(.nav-back) {
+  --slide-offset: -60px;
+  animation:
+    var(--duration-enter) ease-out var(--duration-exit) both fade,
+    var(--duration-move) ease-in-out both slide;
+}
+```
+
+---
+
+## Shared Element Morph
+
+```css
+::view-transition-group(.morph) {
+  animation-duration: var(--duration-move);
+}
+
+::view-transition-image-pair(.morph) {
+  animation-name: via-blur;
+}
+
+@keyframes via-blur {
+  30% { filter: blur(3px); }
+}
+```
+
+Usage: `<ViewTransition name={`product-${id}`} share="morph" />`
+
+**Note:** Shared element transitions take raster snapshots. For text with significant size differences (e.g., `<h3>` → `<h1>`), the old snapshot gets scaled up, producing a visible ghost artifact. Use `text-morph` for text shared elements.
+
+## Text Morph
+
+Avoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:
+
+```css
+::view-transition-group(.text-morph) {
+  animation-duration: var(--duration-move);
+}
+::view-transition-old(.text-morph) {
+  display: none;
+}
+::view-transition-new(.text-morph) {
+  animation: none;
+  object-fit: none;
+  object-position: left top;
+}
+```
+
+Usage: `<ViewTransition name={`title-${id}`} share="text-morph" />`
+
+---
+
+## Scale
+
+```css
+::view-transition-old(.scale-out) {
+  animation: var(--duration-exit) ease-in scale-down;
+}
+::view-transition-new(.scale-in) {
+  animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;
+}
+
+@keyframes scale-down {
+  from { transform: scale(1); opacity: 1; }
+  to { transform: scale(0.85); opacity: 0; }
+}
+@keyframes scale-up {
+  from { transform: scale(0.85); opacity: 0; }
+  to { transform: scale(1); opacity: 1; }
+}
+```
+
+Usage: `<ViewTransition enter="scale-in" exit="scale-out" />`
+
+---
+
+## Persistent Element Isolation
+
+```css
+::view-transition-group(persistent-nav) {
+  animation: none;
+  z-index: 100;
+}
+```
+
+### Backdrop-Blur Workaround
+
+For elements with `backdrop-filter`, hide the old snapshot to avoid flash:
+
+```css
+::view-transition-old(persistent-nav) {
+  display: none;
+}
+::view-transition-new(persistent-nav) {
+  animation: none;
+}
+```
+
+---
+
+## Reduced Motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-old(*),
+  ::view-transition-new(*),
+  ::view-transition-group(*) {
+    animation-duration: 0s !important;
+    animation-delay: 0s !important;
+  }
+}
+```