{"name":"motion-hooks","entry":"component","title":"MotionHooks","description":"Remotion timing hooks in seconds: elapsed time, a spring entrance, a cubic-out fade, and an eased progress value.","category":"Foundations","capabilities":["replay","player"],"needsRemotion":true,"registryDependencies":[],"install":"npx shadcn@latest add @jbm/motion-hooks","installName":"motion-hooks","page":"https://jbm-ui.bns.studio/c/motion-hooks","registryItem":"https://jbm-ui.bns.studio/r/motion-hooks.json","sourcePath":"registry/jbm/motion/hooks.ts","files":[{"source":"registry/jbm/motion/hooks.ts","target":"src/jbm/motion/hooks.ts","import":"@/jbm/motion/hooks","type":"registry:hook"}],"endpoints":{"markdown":"https://jbm-ui.bns.studio/catalog/motion-hooks.md","json":"https://jbm-ui.bns.studio/catalog/motion-hooks.json"},"snippet":"import { useSec, useIn, useFade, useProgress } from \"@/jbm/motion/hooks\"\n\n// Render inside a Remotion <Composition> or <Player>: hooks run in the component body.\nexport function TimelineReadout() {\n  const seconds = useSec()\n  const entrance = useIn(0.2)\n  const opacity = useFade(0.2)\n  const progress = useProgress(0.2, 100, 1.5)\n  return (\n    <div style={{ opacity, transform: `translateY(${(1 - entrance) * 30}px)` }}>\n      {progress.toFixed(0)}% at {seconds.toFixed(2)}s\n    </div>\n  )\n}","api":[{"export":"useSec","kind":"hook","summary":"Seconds elapsed since the start of the enclosing Remotion Sequence (current frame ÷ fps).","params":[],"returns":"Elapsed seconds as a number; fractional between frames."},{"export":"useIn","kind":"hook","summary":"Spring entrance that starts at `startSec` (rounded to the nearest frame) with mass 0.8. Stays 0 before the start and settles near 1; it can overshoot 1 slightly while settling.","params":[{"name":"startSec","type":"number","required":true,"default":null,"description":"Start time in seconds relative to the enclosing Sequence."},{"name":"opts","type":"{ damping?: number; stiffness?: number }","required":false,"default":null,"description":"Optional spring config: `damping` (default 14) and `stiffness` (default 120). Lower damping bounces more."}],"returns":"Spring value from 0 toward 1, for opacity, scale, or translate progress."},{"export":"useFade","kind":"hook","summary":"Cubic-out interpolation from 0 to 1 over `dur` seconds starting at `startSec`, clamped at both ends.","params":[{"name":"startSec","type":"number","required":true,"default":null,"description":"Start time in seconds relative to the enclosing Sequence."},{"name":"dur","type":"number","required":false,"default":"0.4","description":"Fade length in seconds."}],"returns":"Opacity-style value clamped to 0–1."},{"export":"useProgress","kind":"hook","summary":"Cubic-out interpolation from 0 to `target` over `dur` seconds starting at `startSec`, clamped at both ends. Use for bar fills, counters, and draw-on strokes.","params":[{"name":"startSec","type":"number","required":true,"default":null,"description":"Start time in seconds relative to the enclosing Sequence."},{"name":"target","type":"number","required":false,"default":"1","description":"Value reached at `startSec + dur` and held afterwards (e.g. 1, 100, or a probability)."},{"name":"dur","type":"number","required":false,"default":"0.7","description":"Seconds taken to reach `target`."}],"returns":"Number between 0 and `target`."}],"stage":{"mode":"n/a","reason":"Hooks only; they render nothing. The gallery preview is a demo component built on them."},"examples":[{"title":"Entrance, fade, and a counting value","code":"import { useSec, useIn, useFade, useProgress } from \"@/jbm/motion/hooks\"\n\n// Render inside a Remotion <Composition> or <Player>: hooks run in the component body.\nexport function TimelineReadout() {\n  const seconds = useSec()\n  const entrance = useIn(0.2)\n  const opacity = useFade(0.2)\n  const progress = useProgress(0.2, 100, 1.5)\n  return (\n    <div style={{ opacity, transform: `translateY(${(1 - entrance) * 30}px)` }}>\n      {progress.toFixed(0)}% at {seconds.toFixed(2)}s\n    </div>\n  )\n}"}],"qa":["Step to the first frame, the middle of the 1.5 s window, and the last frame: the percentage reads 0, an intermediate value, then exactly 100; useSec matches frame ÷ fps.","Check that times are relative to the enclosing Sequence: a component inside a Sequence that starts later still enters at its own `startSec`.","When changing spring defaults, re-check every consumer (Pop, ProbBar, RebuildScreens, Catalog) and the gallery preview durations measured from the same spring config."],"related":[{"name":"pop","relation":"installed-by"},{"name":"counter","relation":"installed-by"},{"name":"prob-bar","relation":"installed-by"},{"name":"captions","relation":"installed-by"},{"name":"rebuild-screens","relation":"installed-by"},{"name":"catalog","relation":"installed-by"},{"name":"propagate","relation":"installed-by"},{"name":"shelf","relation":"installed-by"}],"galleryPreview":{"about":"Cue times are seconds on the gallery preview's timeline, which renders the demo below; the Usage examples may use other timings. Map a cue to your own props by its place in the demo.","fps":30,"durationInFrames":52,"lastFrame":51,"strip":"https://jbm-ui.bns.studio/c/motion-hooks?view=strip","frames":[{"label":"Empty stage","frame":0,"at":0},{"label":"Counting up","frame":15,"at":0.5,"note":"The percentage is mid-count while the block is still rising into place."},{"label":"End","frame":51,"at":1.7}],"demo":[{"code":"const entrance = useIn(0.2)\nconst opacity = useFade(0.2)\nconst progress = useProgress(0.2, 100, 1.5)\n// A Big number shows progress.toFixed(0) + \"%\", fading and rising in with opacity and entrance."}],"code":"const entrance = useIn(0.2)\nconst opacity = useFade(0.2)\nconst progress = useProgress(0.2, 100, 1.5)\n// A Big number shows progress.toFixed(0) + \"%\", fading and rising in with opacity and entrance."},"setup":{"namespace":"@jbm","componentsJson":{"registries":{"@jbm":"https://jbm-ui.bns.studio/r/{name}.json"}},"command":"npx shadcn@latest add @jbm/<name>","target":"src/jbm/","importAlias":"@/jbm/…","tsconfigPaths":{"@/*":["./src/*"]}},"rules":["Install through the @jbm namespace: each registry item JSON (/r/<name>.json) carries its files' contents and each guide is served at /docs/<slug>.md, so agents never need the source repository (it is public on GitHub for people browsing the code).","Files install to src/jbm/ and import as @/jbm/…, which needs the @/* → ./src/* path alias in tsconfig.json.","Items marked needsRemotion require the remotion package and must render inside a Remotion composition or Player; every other item works in any React page.","Use one vermilion accent per composition; accent2 is for annotations only and soft is for dark surfaces only.","Stages are 1920×1080 landscape and 1080×1920 vertical with declared safe areas; each item's stage field declares its size in stage pixels, and scenes compose from YAML-shaped specs with @jbm/scene-spec."],"links":{"catalog":"https://jbm-ui.bns.studio/catalog.json","llms":"https://jbm-ui.bns.studio/llms.txt"}}