docs

Author: bea4dev

src/lib/animation.ts

@@ -5,8 +5,38 @@ import type { Easing } from "./animation/functions"
 
 type Lerp<T> = (from: T, to: T, t: number) => T
 
+/**
+ * 2D vector type.
+ *
+ * 2 次元ベクトル型。
+ *
+ * @example
+ * ```ts
+ * const v: Vec2 = { x: 10, y: 20 }
+ * ```
+ */
 export type Vec2 = { x: number; y: number }
+/**
+ * 3D vector type.
+ *
+ * 3 次元ベクトル型。
+ *
+ * @example
+ * ```ts
+ * const v: Vec3 = { x: 1, y: 2, z: 3 }
+ * ```
+ */
 export type Vec3 = { x: number; y: number; z: number }
+/**
+ * Supported variable value types for animation.
+ *
+ * アニメーション変数で使える値の型。
+ *
+ * @example
+ * ```ts
+ * const value: VariableType = { x: 0, y: 0 }
+ * ```
+ */
 export type VariableType = number | Vec2 | Vec3
 
 type VariableKind = "number" | "vec2" | "vec3"
@@ -27,6 +57,17 @@ type VariableStateBase = {
   ownerId: number | null
 }
 
+/**
+ * Animation variable with timeline-aware sampling.
+ *
+ * タイムラインに応じた値取得ができるアニメーション変数。
+ *
+ * @example
+ * ```tsx
+ * const pos = useVariable({ x: 0, y: 0 })
+ * const value = pos.use()
+ * ```
+ */
 export type Variable<T> = {
   use: () => T
   get: (frame: number) => T
@@ -196,6 +237,17 @@ const sampleVariable = (state: VariableStateBase, frame: number) => {
   return value
 }
 
+/**
+ * Thenable handle returned by animation commands.
+ *
+ * アニメーション操作が返す thenable ハンドル。
+ *
+ * @example
+ * ```tsx
+ * const handle = ctx.move(position).to({ x: 100, y: 0 }, seconds(1))
+ * await handle
+ * ```
+ */
 export class AnimationHandle {
   private resolved = false
   public readonly endFrame: number
@@ -219,6 +271,17 @@ export class AnimationHandle {
   }
 }
 
+/**
+ * Creates an animatable variable.
+ *
+ * アニメーション可能な変数を作成します。
+ *
+ * @example
+ * ```tsx
+ * const opacity = useVariable(0)
+ * const pos = useVariable({ x: 0, y: 0 })
+ * ```
+ */
 export function useVariable(initial: number): Variable<number>
 export function useVariable(initial: Vec2): Variable<Vec2>
 export function useVariable(initial: Vec3): Variable<Vec3>
@@ -260,6 +323,19 @@ export function useVariable<T extends VariableType>(initial: T): Variable<T> {
   return { use: useValue, get, _state: state }
 }
 
+/**
+ * Defines an animation sequence and reports its duration to the current clip.
+ *
+ * アニメーションシーケンスを定義し、クリップへ長さを報告します。
+ *
+ * @example
+ * ```tsx
+ * useAnimation(async (ctx) => {
+ *   await ctx.sleep(seconds(0.5))
+ *   await ctx.move(pos).to({ x: 200, y: 0 }, seconds(1))
+ * }, [])
+ * ```
+ */
 export const useAnimation = (
   run: (ctx: AnimationContext) => Promise<void> | void,
   deps: DependencyList = [run],

src/lib/animation/functions.ts

@@ -1,10 +1,50 @@
+/**
+ * Easing function type (0..1 -> 0..1).
+ *
+ * イージング関数の型 (0..1 -> 0..1)。
+ *
+ * @example
+ * ```ts
+ * const ease: Easing = (t) => t * t
+ * ```
+ */
 export type Easing = (t: number) => number
 
+/**
+ * Clamps a value to the given range.
+ *
+ * 値を指定した範囲に収めます。
+ *
+ * @example
+ * ```ts
+ * const v = clamp(1.2, 0, 1)
+ * ```
+ */
 export const clamp = (value: number, min: number, max: number) =>
   Math.min(max, Math.max(min, value))
 
+/**
+ * Linear interpolation between two numbers.
+ *
+ * 2 つの数値を線形補間します。
+ *
+ * @example
+ * ```ts
+ * const v = lerp(0, 10, 0.5)
+ * ```
+ */
 export const lerp = (a: number, b: number, t: number) => a + (b - a) * t
 
+/**
+ * Creates a cubic-bezier easing function.
+ *
+ * cubic-bezier のイージング関数を生成します。
+ *
+ * @example
+ * ```ts
+ * const ease = cubicBezier(0.42, 0, 0.58, 1)
+ * ```
+ */
 export const cubicBezier = (x1: number, y1: number, x2: number, y2: number): Easing => {
   if (x1 === y1 && x2 === y2) {
     return (t) => clamp(t, 0, 1)
@@ -87,29 +127,189 @@ export const cubicBezier = (x1: number, y1: number, x2: number, y2: number): Eas
   }
 }
 
+/**
+ * Preset cubic-bezier easing (CSS "ease").
+ *
+ * 既定の cubic-bezier（CSS の "ease"）。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_EASE
+ * ```
+ */
 export const BEZIER_EASE = cubicBezier(0.25, 0.1, 0.25, 1)
+/**
+ * Preset cubic-bezier easing for ease-in.
+ *
+ * ease-in 用のプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_EASE_IN
+ * ```
+ */
 export const BEZIER_EASE_IN = cubicBezier(0.42, 0, 1, 1)
+/**
+ * Preset cubic-bezier easing for ease-out.
+ *
+ * ease-out 用のプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_EASE_OUT
+ * ```
+ */
 export const BEZIER_EASE_OUT = cubicBezier(0, 0, 0.58, 1)
+/**
+ * Preset cubic-bezier easing for ease-in-out.
+ *
+ * ease-in-out 用のプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_EASE_IN_OUT
+ * ```
+ */
 export const BEZIER_EASE_IN_OUT = cubicBezier(0.42, 0, 0.58, 1)
+/**
+ * Preset cubic-bezier easing for smooth motion.
+ *
+ * なめらかな動き向けのプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_SMOOTH
+ * ```
+ */
 export const BEZIER_SMOOTH = cubicBezier(0.4, 0, 0.2, 1)
+/**
+ * Preset cubic-bezier easing for sharper motion.
+ *
+ * 切れ味のある動き向けのプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_SHARP
+ * ```
+ */
 export const BEZIER_SHARP = cubicBezier(0.4, 0, 0.6, 1)
+/**
+ * Preset cubic-bezier easing for acceleration.
+ *
+ * 加速を強めるプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_ACCELERATE
+ * ```
+ */
 export const BEZIER_ACCELERATE = cubicBezier(0.4, 0, 1, 1)
+/**
+ * Preset cubic-bezier easing for deceleration.
+ *
+ * 減速を強めるプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_DECELERATE
+ * ```
+ */
 export const BEZIER_DECELERATE = cubicBezier(0, 0, 0.2, 1)
+/**
+ * Preset cubic-bezier easing for snappy motion.
+ *
+ * 俊敏な動き向けのプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_SNAPPY
+ * ```
+ */
 export const BEZIER_SNAPPY = cubicBezier(0.2, 0.9, 0.2, 1)
+/**
+ * Preset cubic-bezier easing with overshoot.
+ *
+ * オーバーシュート向けのプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_OVERSHOOT
+ * ```
+ */
 export const BEZIER_OVERSHOOT = cubicBezier(0.16, 1.25, 0.3, 1)
+/**
+ * Soft overshoot cubic-bezier preset.
+ *
+ * 柔らかいオーバーシュートのプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_OVERSHOOT_SOFT
+ * ```
+ */
 export const BEZIER_OVERSHOOT_SOFT = cubicBezier(0.12, 1.1, 0.3, 1)
+/**
+ * Hard overshoot cubic-bezier preset.
+ *
+ * 強めのオーバーシュートのプリセット。
+ *
+ * @example
+ * ```ts
+ * const ease = BEZIER_OVERSHOOT_HARD
+ * ```
+ */
 export const BEZIER_OVERSHOOT_HARD = cubicBezier(0.18, 1.35, 0.2, 1)
 
+/**
+ * Ease-out cubic easing.
+ *
+ * cubic の ease-out。
+ *
+ * @example
+ * ```ts
+ * const ease = easeOutCubic
+ * ```
+ */
 export const easeOutCubic: Easing = (t) => 1 - Math.pow(1 - clamp(t, 0, 1), 3)
+/**
+ * Ease-in-out cubic easing.
+ *
+ * cubic の ease-in-out。
+ *
+ * @example
+ * ```ts
+ * const ease = easeInOutCubic
+ * ```
+ */
 export const easeInOutCubic: Easing = (t) => {
   const x = clamp(t, 0, 1)
   return x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2
 }
+/**
+ * Ease-out exponential easing.
+ *
+ * 指数関数の ease-out。
+ *
+ * @example
+ * ```ts
+ * const ease = easeOutExpo
+ * ```
+ */
 export const easeOutExpo: Easing = (t) => {
   const x = clamp(t, 0, 1)
   return x === 1 ? 1 : 1 - Math.pow(2, -10 * x)
 }
 
+/**
+ * Normalized progress between start/end frames.
+ *
+ * 開始/終了フレームから 0..1 の進捗を返します。
+ *
+ * @example
+ * ```ts
+ * const t = frameProgress(frame, 0, 60, easeOutCubic)
+ * ```
+ */
 export const frameProgress = (
   frame: number,
   startFrame: number,
@@ -121,6 +321,16 @@ export const frameProgress = (
   return easing(t)
 }
 
+/**
+ * Convenience fade curve with optional in/out lengths.
+ *
+ * フェードイン/アウトの簡易カーブを返します。
+ *
+ * @example
+ * ```ts
+ * const opacity = fadeInOut(frame, durationFrames)
+ * ```
+ */
 export const fadeInOut = (frame: number, durationFrames: number, opts?: { in?: number; out?: number }) => {
   const total = Math.max(1, durationFrames)
   const fadeIn = Math.max(0, Math.floor(opts?.in ?? Math.min(18, total / 6)))
@@ -131,5 +341,15 @@ export const fadeInOut = (frame: number, durationFrames: number, opts?: { in?: n
   return Math.min(tIn, tOut)
 }
 
+/**
+ * Returns a staggered start frame offset.
+ *
+ * スタガーの開始フレームを返します。
+ *
+ * @example
+ * ```ts
+ * const start = stagger(index, seconds(0.1))
+ * ```
+ */
 export const stagger = (index: number, eachFrames: number, base = 0) =>
   base + index * Math.max(0, eachFrames)