@hegemonart/get-design-done 1.16.0 → 1.18.0

package/reference/motion-easings.md

@@ -0,0 +1,381 @@
+<!-- Source: React Native — Libraries/Animated/Easing.js (MIT License) -->
+<!-- Attribution: Facebook, Inc. and its affiliates — see https://github.com/facebook/react-native/blob/main/Libraries/Animated/Easing.js -->
+
+# Motion Easings
+
+Canonical easing curve presets derived from React Native's `Easing` module, adapted for CSS and web animation contexts.
+
+## Quick Reference
+
+| Token | CSS `cubic-bezier` | Character | Settle (spring/bounce) |
+|---|---|---|---|
+| `--ease-linear` | `cubic-bezier(0,0,1,1)` | Constant rate | — |
+| `--ease-quad-in` | `cubic-bezier(0.55,0,1,1)` | Slow start | — |
+| `--ease-quad-out` | `cubic-bezier(0,0,0.45,1)` | Slow end | — |
+| `--ease-quad-in-out` | `cubic-bezier(0.455,0.03,0.515,0.955)` | Slow both | — |
+| `--ease-cubic-in` | `cubic-bezier(0.55,0.055,0.675,0.19)` | Aggressive start | — |
+| `--ease-cubic-out` | `cubic-bezier(0.215,0.61,0.355,1)` | Aggressive end | — |
+| `--ease-cubic-in-out` | `cubic-bezier(0.645,0.045,0.355,1)` | Strong S-curve | — |
+| `--ease-sin-in` | `cubic-bezier(0.47,0,0.745,0.715)` | Gentle start | — |
+| `--ease-sin-out` | `cubic-bezier(0.39,0.575,0.565,1)` | Gentle end | — |
+| `--ease-sin-in-out` | `cubic-bezier(0.445,0.05,0.55,0.95)` | Smooth S-curve | — |
+| `--ease-circle-in` | `cubic-bezier(0.6,0.04,0.98,0.335)` | Circular arc start | — |
+| `--ease-circle-out` | `cubic-bezier(0.075,0.82,0.165,1)` | Circular arc end | — |
+| `--ease-exp-in` | `cubic-bezier(0.95,0.05,0.795,0.035)` | Explosive start | — |
+| `--ease-exp-out` | `cubic-bezier(0.19,1,0.22,1)` | Explosive end | — |
+| `--ease-elastic` | `linear(...)` baked | Overshoot + settle | ~500ms |
+| `--ease-back-in` | `cubic-bezier(0.6,-0.28,0.735,0.045)` | Anticipation | — |
+| `--ease-back-out` | `cubic-bezier(0.175,0.885,0.32,1.275)` | Overshoot | — |
+| `--ease-bounce-out` | `linear(...)` baked | Bounces at end | ~420ms |
+
+---
+
+## Preset Groups
+
+### `linear`
+
+Motion at a constant rate. No acceleration or deceleration.
+
+- **Human name:** Linear
+- **Character:** Mechanical, robotic. Use only for opacity fades or loading bars where constant rate is intentional.
+- **CSS custom property:** `--ease-linear`
+- **CSS equivalent:** `cubic-bezier(0, 0, 1, 1)` (also the CSS keyword `linear`)
+
+```css
+:root {
+  --ease-linear: cubic-bezier(0, 0, 1, 1);
+}
+
+.fade {
+  transition: opacity 200ms var(--ease-linear);
+}
+```
+
+```js
+// React Native Easing
+Easing.linear
+```
+
+---
+
+### `quad`
+
+Quadratic — acceleration proportional to `t²`.
+
+- **Human name:** Quad (ease-in-out)
+- **Character:** Subtle, polished. Most common choice for UI transitions.
+- **CSS custom property:** `--ease-quad-in-out`
+
+```css
+:root {
+  --ease-quad-in:     cubic-bezier(0.55, 0, 1, 1);
+  --ease-quad-out:    cubic-bezier(0, 0, 0.45, 1);
+  --ease-quad-in-out: cubic-bezier(0.455, 0.03, 0.515, 0.955);
+}
+```
+
+```js
+Easing.quad          // base: t * t
+Easing.in(Easing.quad)
+Easing.out(Easing.quad)
+Easing.inOut(Easing.quad)
+```
+
+---
+
+### `cubic`
+
+Cubic — acceleration proportional to `t³`. More pronounced than quad.
+
+- **Human name:** Cubic (ease-in-out)
+- **Character:** Snappy, decisive. Good for panels, drawers, menus.
+- **CSS custom property:** `--ease-cubic-in-out`
+
+```css
+:root {
+  --ease-cubic-in:     cubic-bezier(0.55, 0.055, 0.675, 0.19);
+  --ease-cubic-out:    cubic-bezier(0.215, 0.61, 0.355, 1);
+  --ease-cubic-out:    cubic-bezier(0.215, 0.61, 0.355, 1); /* "ease-out-cubic" */
+  --ease-cubic-in-out: cubic-bezier(0.645, 0.045, 0.355, 1);
+}
+```
+
+```js
+Easing.cubic         // base: t * t * t
+Easing.inOut(Easing.cubic)
+```
+
+---
+
+### `poly(n)`
+
+Generalised polynomial — `t^n`. Quad is `poly(2)`, cubic is `poly(3)`.
+
+- **Human name:** Poly-n
+- **Character:** Tunable. Higher `n` = harder snap.
+- **CSS custom property:** No single token; bake to `cubic-bezier` per n.
+
+```js
+Easing.poly(4)   // quartic
+Easing.poly(5)   // quintic
+Easing.in(Easing.poly(4))
+```
+
+No direct CSS equivalent — approximate with a `cubic-bezier` or bake to `linear()`.
+
+---
+
+### `sin`
+
+Sinusoidal — easing shaped by the sine function. Smooth and natural.
+
+- **Human name:** Sine
+- **Character:** Organic, gentle. Works well for ambient or breathing animations.
+- **CSS custom property:** `--ease-sin-in-out`
+
+```css
+:root {
+  --ease-sin-in:     cubic-bezier(0.47, 0, 0.745, 0.715);
+  --ease-sin-out:    cubic-bezier(0.39, 0.575, 0.565, 1);
+  --ease-sin-in-out: cubic-bezier(0.445, 0.05, 0.55, 0.95);
+}
+```
+
+```js
+Easing.sin
+// Internally: 1 - Math.cos(t * Math.PI / 2)
+```
+
+---
+
+### `circle`
+
+Circular arc — based on `sqrt(1 - t²)`. Sharp acceleration at the end of its range.
+
+- **Human name:** Circ
+- **Character:** Abrupt, dramatic. Use sparingly for emphasis.
+- **CSS custom property:** `--ease-circle-out`
+
+```css
+:root {
+  --ease-circle-in:  cubic-bezier(0.6, 0.04, 0.98, 0.335);
+  --ease-circle-out: cubic-bezier(0.075, 0.82, 0.165, 1);
+}
+```
+
+```js
+Easing.circle
+// Internally: 1 - Math.sqrt(1 - t * t)
+```
+
+---
+
+### `exp`
+
+Exponential — `2^(10 * (t - 1))`. Starts near-zero, ends explosively.
+
+- **Human name:** Expo
+- **Character:** High-impact. Good for reveal animations, hero entrances.
+- **CSS custom property:** `--ease-exp-out`
+
+```css
+:root {
+  --ease-exp-in:  cubic-bezier(0.95, 0.05, 0.795, 0.035);
+  --ease-exp-out: cubic-bezier(0.19, 1, 0.22, 1);
+}
+```
+
+```js
+Easing.exp
+// Internally: Math.pow(2, 10 * (t - 1))
+```
+
+---
+
+### `elastic(bounciness, speed)`
+
+Spring-like oscillation past the target before settling.
+
+- **Human name:** Elastic
+- **Character:** Playful, bouncy. Overshoots final value one or more times.
+- **Default params:** `bounciness = 1`, `speed = 1`
+- **60fps settle time:** ~500ms at defaults
+- **CSS custom property:** `--ease-elastic` (must be baked to `linear()`)
+
+```css
+/* Baked approximation for CSS linear() — default elastic */
+:root {
+  --ease-elastic-out: linear(
+    0, 0.009, 0.035 2.1%, 0.141, 0.281 6.7%, 0.723 12.9%,
+    0.938, 1.017, 1.048, 1.056, 1.046 20.1%, 0.999 24.3%,
+    0.984, 0.983, 0.988 29.9%, 1.001 35.5%, 1.004 40.1%, 1 100%
+  );
+}
+```
+
+```js
+Easing.elastic(1, 1)           // default
+Easing.out(Easing.elastic(1, 1))
+```
+
+**Parameter guide:**
+- `bounciness`: amplitude of overshoot (0 = no overshoot, higher = more)
+- `speed`: controls oscillation frequency (higher = faster settle)
+
+---
+
+### `back(s)`
+
+Anticipation curve — slightly retracts before moving forward (or overshoots then settles).
+
+- **Human name:** Back
+- **Character:** Mechanical delight. Communicates intentionality.
+- **Default param:** `s = 1.70158`
+- **CSS custom property:** `--ease-back-out`
+
+```css
+:root {
+  /* s = 1.70158 (default) */
+  --ease-back-in:  cubic-bezier(0.6, -0.28, 0.735, 0.045);
+  --ease-back-out: cubic-bezier(0.175, 0.885, 0.32, 1.275);
+}
+```
+
+```js
+Easing.back(1.70158)           // default overshoot
+Easing.out(Easing.back(2.5))   // stronger overshoot
+```
+
+---
+
+### `bounce`
+
+Simulates a physical bounce — the value bounces off the endpoint.
+
+- **Human name:** Bounce
+- **Character:** Playful, energetic. Use for game-like or informal UIs.
+- **60fps settle time:** ~420ms
+- **CSS custom property:** `--ease-bounce-out` (must be baked to `linear()`)
+
+```css
+:root {
+  /* Baked CSS linear() approximation */
+  --ease-bounce-out: linear(
+    0, 0.004, 0.016, 0.035, 0.063, 0.098, 0.141, 0.191, 0.25,
+    0.316, 0.391, 0.469, 0.563, 0.656, 0.765, 0.875, 0.891,
+    0.906 45.7%, 0.922, 0.938, 0.953 50%, 0.984, 1.016, 1.031,
+    1.047, 1.063, 1.016, 1 100%
+  );
+}
+```
+
+```js
+Easing.bounce
+// Internally: piecewise quadratic with 4 bounces
+```
+
+---
+
+### `bezier(x1, y1, x2, y2)`
+
+Raw cubic Bézier — the same primitive that powers all CSS `cubic-bezier()` calls.
+
+- **Human name:** Custom Bézier
+- **Character:** Whatever you specify.
+
+```js
+Easing.bezier(0.25, 0.1, 0.25, 1.0)   // CSS ease
+Easing.bezier(0.42, 0, 1, 1)           // CSS ease-in
+Easing.bezier(0, 0, 0.58, 1)           // CSS ease-out
+Easing.bezier(0.42, 0, 0.58, 1)        // CSS ease-in-out
+```
+
+```css
+/* Direct mapping */
+transition-timing-function: cubic-bezier(0.25, 0.1, 0.25, 1.0);
+```
+
+---
+
+## Higher-Order Wrappers: `in`, `out`, `inOut`
+
+React Native's `Easing` module exposes three composition functions that transform any base curve into its directional variant. This is the correct pattern for producing all six canonical easing directions from any single base function.
+
+### How it works
+
+Given a base easing function `f(t)` where `t ∈ [0, 1]`:
+
+| Wrapper | Formula | Effect |
+|---|---|---|
+| `in(f)` | `f(t)` | Acceleration at start — slow → fast |
+| `out(f)` | `1 - f(1 - t)` | Deceleration at end — fast → slow |
+| `inOut(f)` | `t < 0.5 ? f(2t)/2 : 1 - f(2(1-t))/2` | Slow start and end |
+
+### Examples
+
+```js
+import { in as easeIn, out as easeOut, inOut, cubic } from './lib/easings.cjs';
+
+const easeInCubic  = easeIn(cubic);    // t => t³
+const easeOutCubic = easeOut(cubic);   // t => 1 - (1-t)³
+const easeInOutCubic = inOut(cubic);   // smooth S-curve
+
+// Works identically with any base:
+const easeInBounce  = easeIn(bounce);
+const easeInElastic = easeIn(elastic(1, 1));
+```
+
+```css
+/* CSS does the same thing natively for cubic-bezier: */
+/* ease-in  = cubic-bezier(x1,y1, x2,y2) with control points in lower-left */
+/* ease-out = cubic-bezier(x1,y1, x2,y2) with control points in upper-right */
+/* inOut    = symmetric control points */
+```
+
+### Design rule
+
+- Use `out` for **enter** transitions (element arrives, decelerates into place).
+- Use `in` for **exit** transitions (element departs, accelerates away).
+- Use `inOut` for **state changes** (element moves from one state to another, both ends cushioned).
+
+---
+
+## CSS Custom Properties — Full Token Set
+
+```css
+:root {
+  /* Linear */
+  --ease-linear: cubic-bezier(0, 0, 1, 1);
+
+  /* Sine */
+  --ease-sin-in:     cubic-bezier(0.47, 0, 0.745, 0.715);
+  --ease-sin-out:    cubic-bezier(0.39, 0.575, 0.565, 1);
+  --ease-sin-in-out: cubic-bezier(0.445, 0.05, 0.55, 0.95);
+
+  /* Quad */
+  --ease-quad-in:     cubic-bezier(0.55, 0, 1, 1);
+  --ease-quad-out:    cubic-bezier(0, 0, 0.45, 1);
+  --ease-quad-in-out: cubic-bezier(0.455, 0.03, 0.515, 0.955);
+
+  /* Cubic */
+  --ease-cubic-in:     cubic-bezier(0.55, 0.055, 0.675, 0.19);
+  --ease-cubic-out:    cubic-bezier(0.215, 0.61, 0.355, 1);
+  --ease-cubic-in-out: cubic-bezier(0.645, 0.045, 0.355, 1);
+
+  /* Circ */
+  --ease-circle-in:  cubic-bezier(0.6, 0.04, 0.98, 0.335);
+  --ease-circle-out: cubic-bezier(0.075, 0.82, 0.165, 1);
+
+  /* Expo */
+  --ease-exp-in:  cubic-bezier(0.95, 0.05, 0.795, 0.035);
+  --ease-exp-out: cubic-bezier(0.19, 1, 0.22, 1);
+
+  /* Back (default s=1.70158) */
+  --ease-back-in:  cubic-bezier(0.6, -0.28, 0.735, 0.045);
+  --ease-back-out: cubic-bezier(0.175, 0.885, 0.32, 1.275);
+
+  /* Elastic and Bounce — baked linear() — see above for full values */
+  --ease-elastic-out: linear(0, 0.009, 0.035 2.1%, 0.141, 0.281 6.7%, 0.723 12.9%, 0.938, 1.017, 1.048, 1.056, 1.046 20.1%, 0.999 24.3%, 0.984, 0.983, 0.988 29.9%, 1.001 35.5%, 1.004 40.1%, 1 100%);
+  --ease-bounce-out:  linear(0, 0.004, 0.016, 0.035, 0.063, 0.098, 0.141, 0.191, 0.250, 0.316, 0.391, 0.469, 0.563, 0.656, 0.765, 0.875, 0.891, 0.906 45.7%, 0.922, 0.938, 0.953 50%, 0.984, 1.016, 1.031, 1.047, 1.063, 1.016, 1 100%);
+}
+```

package/reference/motion-interpolate.md

@@ -0,0 +1,282 @@
+<!-- Source: React Native — Libraries/Animated/AnimatedInterpolation.js (MIT License) -->
+<!-- Attribution: Facebook, Inc. and its affiliates -->
+
+# Motion Interpolation
+
+Interpolation is the mechanism that maps any changing value — progress, scroll position, pointer delta, elapsed time — into any animated output range. Every animation in a system can be decomposed into a single canonical form.
+
+---
+
+## Core Concept
+
+Any animation decomposes into four parameters:
+
+```
+interpolate(inputValue, inputRange, outputRange, extrapolationConfig?)
+```
+
+| Parameter | Type | Description |
+|---|---|---|
+| `inputValue` | `number` | The driver value (a scalar that changes over time) |
+| `inputRange` | `number[]` | Ordered list of input breakpoints |
+| `outputRange` | `number \| string[]` | Corresponding output values at each breakpoint |
+| `extrapolationConfig` | `object?` | What to do when input is outside `inputRange` |
+
+Between any two adjacent breakpoints, the output is linearly interpolated by default. An `easing` function can be applied per-segment to shape the curve. See [motion-easings.md](./motion-easings.md) for the `easing` parameter.
+
+**Principle:** The driver value is always a plain number. The animation is a pure function of that number. This separates *what drives the animation* from *what the animation does*, making it composable and testable.
+
+---
+
+## Extrapolation Modes
+
+When `inputValue` falls outside `inputRange`, the behavior is controlled by the extrapolation config. React Native defines four named modes:
+
+### `extend` (default)
+
+Continues the linear trend of the first/last segment past the range boundary. Output keeps growing (or shrinking) indefinitely.
+
+```js
+interpolate(scrollY, [0, 100], [0, 1], { extrapolate: 'extend' })
+// scrollY = 200 → output = 2.0
+```
+
+**Use when:** The animation should track the input continuously beyond the defined range (e.g., parallax that keeps moving as you scroll past a section).
+
+---
+
+### `clamp`
+
+Pins the output to the boundary value once the input leaves the range.
+
+```js
+interpolate(scrollY, [0, 100], [0, 1], { extrapolate: 'clamp' })
+// scrollY = 200 → output = 1.0  (clamped at top)
+// scrollY = -50 → output = 0.0  (clamped at bottom)
+```
+
+**Use when:** An element should be fully visible/hidden after a threshold and not go further (e.g., a header that fades in and stays visible after scrolling 100px).
+
+---
+
+### `identity`
+
+Returns the raw input value itself once outside the range, ignoring the output mapping.
+
+```js
+interpolate(t, [0, 1], [0, 100], { extrapolate: 'identity' })
+// t = 1.5 → output = 1.5  (not 150 — raw input echoed)
+```
+
+**Use when:** You need the value to revert to unscaled behavior outside a zone. Uncommon; most interpolation uses `clamp` or `extend`.
+
+---
+
+### `wrap`
+
+Wraps the input cyclically around the input range before applying the mapping. Produces looping output.
+
+```js
+interpolate(t, [0, 1], [0, 360], { extrapolate: 'wrap' })
+// t = 1.5 → maps to t=0.5 → output = 180
+// t = 2.0 → maps to t=0.0 → output = 0
+```
+
+**Use when:** Rotation, looping progress indicators, repeating carousel positions.
+
+---
+
+## Taxonomy of Animation Types
+
+### Progress-linked (`0 → 1`)
+
+The driver is a normalized progress value from 0 to 1. Most explicit animations and transitions fall here.
+
+```
+inputRange:  [0, 1]
+outputRange: [startValue, endValue]
+```
+
+**Examples:** mount/unmount transition, tab indicator position, wizard step progress.
+
+```js
+// Framer Motion
+const opacity = useTransform(progress, [0, 1], [0, 1]);
+const x       = useTransform(progress, [0, 1], ['-100%', '0%']);
+```
+
+---
+
+### Scroll-linked (px scroll position)
+
+The driver is the raw pixel scroll offset from a scroll container. Common range is `[0, containerHeight]` or a sub-range for reveal effects.
+
+```
+inputRange:  [0, 300]   // px from top of scroll container
+outputRange: [1, 0]     // opacity fades out as user scrolls 300px
+```
+
+```js
+// Framer Motion — scroll-linked opacity
+const { scrollY } = useScroll();
+const opacity = useTransform(scrollY, [0, 300], [1, 0], { clamp: true });
+```
+
+```css
+/* CSS Scroll Timeline equivalent */
+@keyframes fade-header {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
+.header {
+  animation: fade-header linear both;
+  animation-timeline: scroll(root);
+  animation-range: 0px 300px;
+}
+```
+
+---
+
+### Gesture-linked (pointer delta)
+
+The driver is the cumulative pointer displacement in pixels (e.g., drag distance). Input range is typically anchored at 0 with a resistance model at the extremes.
+
+```
+inputRange:  [-200, 0, 200]
+outputRange: ['-100%', '0%', '100%']
+```
+
+**Key difference from scroll-linked:** gesture-linked animations are often bidirectional and involve velocity projection for throw/release behavior.
+
+```js
+// Framer Motion — drag with spring release
+<motion.div
+  drag="x"
+  dragConstraints={{ left: -200, right: 200 }}
+  style={{ x: dragX }}
+/>
+
+// Manual lerp pattern for custom gesture handling
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+
+function interpolateGesture(delta, inputRange, outputRange) {
+  const [inMin, inMax] = inputRange;
+  const [outMin, outMax] = outputRange;
+  const t = Math.max(0, Math.min(1, (delta - inMin) / (inMax - inMin)));
+  return lerp(outMin, outMax, t);
+}
+```
+
+---
+
+### Time-linked (`Date.now()`)
+
+The driver is wall-clock time in milliseconds. Used for ambient animations, looping effects, and time-based sequencing where a spring or tween is not driving the value.
+
+```
+inputRange:  [startTime, startTime + durationMs]
+outputRange: [0, 1]
+extrapolate: 'clamp'
+```
+
+```js
+// Manual time-linked animation loop
+function useTimeLinked(durationMs) {
+  const [progress, setProgress] = useState(0);
+  const startTime = useRef(Date.now());
+
+  useAnimationFrame(() => {
+    const elapsed = Date.now() - startTime.current;
+    const t = Math.min(1, elapsed / durationMs);
+    setProgress(t);
+  });
+
+  return progress;
+}
+```
+
+---
+
+## Using Easing with Interpolation
+
+The `easing` parameter shapes the interpolation curve within a segment. It accepts any `t → value` function from [motion-easings.md](./motion-easings.md).
+
+```js
+import { inOut, cubic } from '../scripts/lib/easings.cjs';
+
+// Framer Motion with easing
+const y = useTransform(scrollY, [0, 400], [0, -100], {
+  ease: inOut(cubic),  // or any easing function
+});
+```
+
+```css
+/* CSS animation-timing-function applies per-keyframe segment */
+@keyframes slide-up {
+  from { transform: translateY(0);    animation-timing-function: var(--ease-cubic-out); }
+  to   { transform: translateY(-100px); }
+}
+```
+
+---
+
+## Manual `lerp` Pattern
+
+When you need to interpolate outside a framework, the bare pattern is:
+
+```js
+/**
+ * Linear interpolation between two values.
+ * @param {number} a  - Start value (at t=0)
+ * @param {number} b  - End value (at t=1)
+ * @param {number} t  - Progress in [0, 1]
+ * @returns {number}
+ */
+function lerp(a, b, t) {
+  return a + (b - a) * t;
+}
+
+/**
+ * Map inputValue from inputRange to outputRange with optional easing and clamping.
+ */
+function interpolate(inputValue, [inMin, inMax], [outMin, outMax], {
+  easing = (t) => t,
+  extrapolate = 'clamp',
+} = {}) {
+  let t = (inputValue - inMin) / (inMax - inMin);
+
+  if (extrapolate === 'clamp') t = Math.max(0, Math.min(1, t));
+  // extend: t is unbounded
+  // identity: return inputValue if out of range
+  // wrap: t = ((t % 1) + 1) % 1
+
+  return lerp(outMin, outMax, easing(t));
+}
+```
+
+---
+
+## Multi-segment Interpolation
+
+Passing more than two breakpoints produces piecewise interpolation. Each adjacent pair is a separate segment.
+
+```js
+// Framer Motion multi-segment
+const background = useTransform(
+  scrollY,
+  [0, 200, 400, 600],
+  ['#ffffff', '#f0f0f0', '#e0e0e0', '#000000']
+);
+```
+
+This is equivalent to three separate interpolations chained by range.
+
+---
+
+## Cross-references
+
+- Easing functions for the `easing` / `ease` parameter: [motion-easings.md](./motion-easings.md)
+- Spring-based animation (an alternative driver to progress/scroll): [motion-spring.md](./motion-spring.md)