@rafaelaugusto/jolt 0.1.0-beta.0 → 0.1.0-beta.10

package/src/motion-scope.ts

@@ -0,0 +1,279 @@
+import { animate, decay } from './animate.js'
+import { press } from './press.js'
+import { drag } from './drag.js'
+import { animateLayout, type LayoutOptions } from './layout.js'
+import type { SpringName } from './transition.js'
+import { sequence } from './sequence.js'
+import {
+  motionStates,
+  type MotionState,
+  type MotionDefinitions,
+  type MotionStates,
+  type MotionStatesOptions,
+} from './motion-states.js'
+import type { Target } from './types.js'
+
+/** A cleanup function or a handle owned exclusively by one scope. */
+export type MotionResource = (() => void) | { stop(): void } | { dispose(): void }
+type Controlled = {
+  pause?: () => void
+  play?: () => void
+  readonly paused?: boolean
+  readonly finished?: Promise<unknown>
+}
+interface Entry {
+  resource?: MotionResource
+  setup?: () => MotionResource
+  resume: boolean
+}
+const owners = new WeakMap<object, object>()
+
+export interface MotionScope {
+  readonly disposed: boolean
+  readonly suspended: boolean
+  /** Owned handles/subscriptions, including suspended subscription factories. */
+  readonly size: number
+  animateLayout: typeof animateLayout
+  animate: typeof animate
+  decay: typeof decay
+  sequence: typeof sequence
+  press: typeof press
+  drag: typeof drag
+  states<
+    T extends Record<string, Target>,
+    const S extends Record<string, MotionState<keyof T>>,
+  >(
+    targets: T,
+    definitions: MotionDefinitions<T, S>,
+    options?: Omit<MotionStatesOptions, 'scope'>,
+  ): MotionStates<Extract<keyof S, string>>
+  /** Adopt an existing handle. Completed animations are released automatically. */
+  add<T extends MotionResource>(resource: T): T
+  /** Attach a subscription, detach on suspension, and recreate on resume. */
+  use(setup: () => MotionResource): () => void
+  /** Pause playable handles; cancel non-playable ones; detach subscriptions. */
+  suspend(): void
+  resume(): void
+  /** Cancel all owned work without destroying the scope, e.g. when recycling a cell. */
+  reset(): void
+  dispose(): void
+}
+
+/** Framework-independent ownership. Native unload never permanently destroys a scope. */
+export function motionScope(): MotionScope {
+  const entries = new Set<Entry>()
+  const adopted = new Map<MotionResource, Entry>()
+  const identity = {}
+  let disposed = false
+  let suspended = false
+  let clearing = false
+  const assertAlive = () => {
+    if (disposed) throw new Error('Motion scope is disposed.')
+    if (clearing) throw new Error('Motion scope is resetting.')
+  }
+  const assertActive = () => {
+    assertAlive()
+    if (suspended)
+      throw new Error('Motion scope is suspended; resume it before starting work.')
+  }
+  const validate = (resource: MotionResource) => {
+    if (
+      typeof resource !== 'function' &&
+      (!resource ||
+        (typeof (resource as { dispose?: unknown }).dispose !== 'function' &&
+          typeof (resource as { stop?: unknown }).stop !== 'function'))
+    )
+      throw new TypeError(
+        'A motion resource must be a cleanup function or expose stop()/dispose().',
+      )
+    const finished = (resource as Controlled).finished
+    if (finished && typeof finished.then !== 'function')
+      throw new TypeError('Resource finished must be a promise.')
+    if (owners.has(resource) && owners.get(resource) !== identity)
+      throw new Error('Motion resource already belongs to another scope.')
+  }
+  const forget = (entry: Entry) => {
+    const resource = entry.resource
+    if (resource) {
+      owners.delete(resource)
+      adopted.delete(resource)
+      entry.resource = undefined
+    }
+    entry.resume = false
+  }
+  const disposeResource = (resource: MotionResource) => {
+    if (typeof resource === 'function') resource()
+    else if (typeof (resource as { dispose?: unknown }).dispose === 'function')
+      (resource as { dispose(): void }).dispose()
+    else (resource as { stop(): void }).stop()
+  }
+  const release = (entry: Entry) => {
+    const resource = entry.resource
+    forget(entry)
+    if (!resource) return
+    disposeResource(resource)
+  }
+  const remove = (entry: Entry) => {
+    entries.delete(entry)
+    release(entry)
+  }
+  const attach = (entry: Entry, resource: MotionResource) => {
+    validate(resource)
+    if (adopted.has(resource))
+      throw new Error('Subscription factory returned an already owned resource.')
+    entry.resource = resource
+    adopted.set(resource, entry)
+    owners.set(resource, identity)
+    const finished = (resource as Controlled).finished
+    if (!entry.setup && finished) {
+      const settled = () => {
+        if (entry.resource !== resource) return
+        forget(entry)
+        entries.delete(entry)
+      }
+      void finished.then(settled, settled)
+    }
+  }
+  const startSubscription = (entry: Entry) => {
+    const resource = entry.setup!()
+    validate(resource)
+    // Setup may synchronously navigate away, suspend or remove its own scope.
+    if (disposed || suspended || !entries.has(entry)) {
+      if (!owners.has(resource)) disposeResource(resource)
+      return
+    }
+    attach(entry, resource)
+  }
+  // One bad cleanup must not strand the other subscriptions.
+  const visit = (action: (entry: Entry) => void) => {
+    const errors: unknown[] = []
+    for (const entry of [...entries]) {
+      if (!entries.has(entry)) continue
+      try {
+        action(entry)
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+    if (errors.length)
+      throw new AggregateError(errors, 'Motion scope cleanup/lifecycle failed.')
+  }
+  const startOwned = <T extends MotionResource>(factory: () => T): T => {
+    assertActive()
+    const resource = factory()
+    try {
+      return scope.add(resource)
+    } catch (error) {
+      if (!owners.has(resource)) disposeResource(resource)
+      throw error
+    }
+  }
+  const scope: MotionScope = {
+    get disposed() {
+      return disposed
+    },
+    get suspended() {
+      return suspended
+    },
+    get size() {
+      return entries.size
+    },
+    animateLayout(
+      container: Target,
+      changeOrOptions?: (() => void) | LayoutOptions | SpringName,
+      options?: LayoutOptions | SpringName,
+    ) {
+      return startOwned(() =>
+        typeof changeOrOptions === 'function'
+          ? animateLayout(container, changeOrOptions, options)
+          : animateLayout(container, changeOrOptions),
+      )
+    },
+    animate(...args) {
+      return startOwned(() => animate(...args))
+    },
+    decay(...args) {
+      return startOwned(() => decay(...args))
+    },
+    sequence(...args) {
+      return startOwned(() => sequence(...args))
+    },
+    press(...args) {
+      return scope.use(() => press(...args))
+    },
+    drag(...args) {
+      return startOwned(() => drag(...args))
+    },
+    states(targets, definitions, options) {
+      return startOwned(() => motionStates(targets, definitions, options))
+    },
+    add(resource) {
+      assertActive()
+      validate(resource)
+      if (adopted.has(resource)) return resource
+      const entry: Entry = { resume: false }
+      attach(entry, resource)
+      entries.add(entry)
+      return resource
+    },
+    use(setup) {
+      assertAlive()
+      if (typeof setup !== 'function')
+        throw new TypeError('Motion subscription needs a factory.')
+      const entry: Entry = { setup, resume: false }
+      entries.add(entry)
+      try {
+        if (!suspended) startSubscription(entry)
+      } catch (error) {
+        remove(entry)
+        throw error
+      }
+      return () => remove(entry)
+    },
+    suspend() {
+      if (disposed || suspended) return
+      suspended = true
+      visit((entry) => {
+        if (entry.setup) {
+          release(entry)
+          return
+        }
+        const resource = entry.resource as Controlled | undefined
+        if (
+          typeof resource?.pause === 'function' &&
+          typeof resource.play === 'function'
+        ) {
+          entry.resume = resource.paused !== true
+          if (entry.resume) resource.pause()
+        } else remove(entry)
+      })
+    },
+    resume() {
+      if (disposed || !suspended) return
+      suspended = false
+      visit((entry) => {
+        if (disposed || suspended) return
+        if (entry.setup) startSubscription(entry)
+        else if (entry.resume) {
+          entry.resume = false
+          ;(entry.resource as Controlled).play?.()
+        }
+      })
+    },
+    reset() {
+      if (disposed || clearing) return
+      clearing = true
+      try {
+        visit(remove)
+      } finally {
+        clearing = false
+      }
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      visit(remove)
+    },
+  }
+  return scope
+}

package/src/motion-states.ts

@@ -0,0 +1,215 @@
+import { prepareAnimation, toView } from './animate.js'
+import { isColorProperty, type ColorValue } from './color.js'
+import { isProperty } from './properties.js'
+import type { Animation } from './engine.js'
+import type { PlaybackAnimation } from './playback.js'
+import type { KeyframeProperty, Keyframes, Target } from './types.js'
+import type { Spring, Tween, SpringName } from './transition.js'
+import type { MotionScope } from './motion-scope.js'
+
+/** Absolute endpoints only; keyframe arrays, paths and relative offsets are not states. */
+export type MotionValues = {
+  [K in KeyframeProperty]?: K extends 'color' | 'backgroundColor' | 'borderColor'
+    ? ColorValue
+    : number
+}
+export type MotionState<K extends PropertyKey = string> = Partial<Record<K, MotionValues>>
+/** Preserve inference while rejecting unknown target/property keys. */
+export type MotionDefinitions<T, S> = S & {
+  [N in keyof S]: Record<Exclude<keyof S[N], keyof T>, never> & {
+    [K in keyof S[N]]: Record<Exclude<keyof S[N][K], KeyframeProperty>, never>
+  }
+}
+export type StateTransition =
+  | SpringName
+  | Omit<Spring, 'repeat' | 'repeatType'>
+  | Omit<Tween, 'repeat' | 'repeatType'>
+export interface MotionStatesOptions {
+  transition?: StateTransition
+  scope?: MotionScope
+}
+export interface MotionStates<S extends string = string> {
+  /** Latest requested state, not a claim that playback has finished. */
+  readonly current: S | undefined
+  readonly settled: S | undefined
+  readonly disposed: boolean
+  readonly paused: boolean
+  to(state: S, transition?: StateTransition): Animation
+  pause(): void
+  play(): void
+  stop(): void
+  dispose(): void
+}
+
+/** Coordinated named targets. Omitted properties freeze when leaving their previous state. */
+export function motionStates<
+  T extends Record<string, Target>,
+  const S extends Record<string, MotionState<keyof T>>,
+>(
+  targets: T,
+  definitions: MotionDefinitions<T, S>,
+  options: MotionStatesOptions = {},
+): MotionStates<Extract<keyof S, string>> {
+  type Name = Extract<keyof S, string>
+  const views = new Map(
+    Object.entries(targets).map(([name, target]) => [name, toView(target)]),
+  )
+  if (new Set(views.values()).size !== views.size)
+    throw new TypeError('Motion state targets must refer to distinct views.')
+  const states = new Map<string, [Target, Keyframes][]>()
+  const defaults = normalize(options.transition)
+  for (const [name, state] of Object.entries(definitions)) {
+    if (!state || typeof state !== 'object' || Array.isArray(state))
+      throw new TypeError(`Invalid motion state "${name}".`)
+    const rows: [Target, Keyframes][] = []
+    for (const [target, values] of Object.entries(state)) {
+      const view = views.get(target)
+      if (!view) throw new TypeError(`Unknown motion target "${target}".`)
+      if (!values || typeof values !== 'object' || Array.isArray(values))
+        throw new TypeError(`Invalid motion values for "${target}".`)
+      const frames: Keyframes = {}
+      for (const [property, value] of Object.entries(values)) {
+        if (value === undefined) continue
+        if (property !== 'scale' && !isProperty(property))
+          throw new TypeError(`Invalid motion state property "${property}".`)
+        if (
+          !isColorProperty(property) &&
+          (typeof value !== 'number' || !Number.isFinite(value))
+        )
+          throw new TypeError(`Motion state "${property}" requires a finite endpoint.`)
+        if (Array.isArray(value) || value === null)
+          throw new TypeError(`Motion state "${property}" requires a single endpoint.`)
+        Object.assign(frames, { [property]: value })
+      }
+      // Validate every definition up front without claiming any native property.
+      prepareAnimation(view, frames, defaults)
+      rows.push([view, frames])
+    }
+    states.set(name, rows)
+  }
+  let current: Name | undefined
+  let settled: Name | undefined
+  let disposed = false
+  let paused = false
+  let active: { handle: Animation; children: PlaybackAnimation[] } | undefined
+  const controller: MotionStates<Name> = {
+    get current() {
+      return current
+    },
+    get settled() {
+      return settled
+    },
+    get disposed() {
+      return disposed
+    },
+    get paused() {
+      return paused
+    },
+    to(name, transition) {
+      if (disposed) throw new Error('Motion states controller is disposed.')
+      const rows = states.get(name)
+      if (!rows) throw new TypeError(`Unknown motion state "${name}".`)
+      const timing = transition === undefined ? defaults : normalize(transition)
+      const prepared = rows.map(([view, frames]) =>
+        prepareAnimation(view, frames, timing),
+      )
+      const previous = active
+      const children: PlaybackAnimation[] = []
+      // Start replacements first: the engine transfers visible position AND velocity.
+      try {
+        for (const start of prepared) {
+          const child = start()
+          children.push(child)
+          if (paused) child.pause()
+        }
+      } catch (error) {
+        children.forEach((child) => child.stop())
+        previous?.handle.stop()
+        active = undefined
+        throw error
+      }
+      let cancelled = false
+      const finished = Promise.all(children.map((child) => child.finished)).then(
+        (results) => {
+          const completed =
+            !cancelled && !disposed && active?.handle === handle && results.every(Boolean)
+          if (active?.handle === handle) {
+            active = undefined
+            if (completed) settled = name
+          }
+          return completed
+        },
+      )
+      const handle: Animation = {
+        finished,
+        stop() {
+          cancelled = true
+          children.forEach((child) => child.stop())
+        },
+        then: (resolve, reject) => finished.then(resolve, reject),
+      }
+      active = { handle, children }
+      current = name
+      // Also cancels old, omitted properties, without touching the new owners.
+      previous?.handle.stop()
+      return handle
+    },
+    pause() {
+      if (disposed || paused) return
+      paused = true
+      active?.children.forEach((child) => child.pause())
+    },
+    play() {
+      if (disposed || !paused) return
+      paused = false
+      active?.children.forEach((child) => child.play())
+    },
+    stop() {
+      active?.handle.stop()
+      active = undefined
+    },
+    dispose() {
+      if (disposed) return
+      disposed = true
+      controller.stop()
+    },
+  }
+  return options.scope ? options.scope.add(controller) : controller
+}
+
+function normalize(transition: StateTransition | undefined): StateTransition {
+  if (transition === undefined) return 'snappy'
+  if (typeof transition === 'string') {
+    if (!['smooth', 'snappy', 'bouncy'].includes(transition))
+      throw new TypeError('Unknown state spring.')
+    return transition
+  }
+  if (!transition || typeof transition !== 'object')
+    throw new TypeError('Invalid state transition.')
+  const allowed = new Set([
+    'type',
+    'delay',
+    'duration',
+    'ease',
+    'times',
+    'stiffness',
+    'damping',
+    'mass',
+    'bounce',
+    'velocity',
+  ])
+  for (const key of Object.keys(transition))
+    if (!allowed.has(key))
+      throw new TypeError(`State transitions do not support "${key}".`)
+  if (
+    transition.duration !== undefined &&
+    (!Number.isFinite(transition.duration) || transition.duration < 0)
+  )
+    throw new RangeError('State transition duration must be finite and nonnegative.')
+  if (
+    transition.delay !== undefined &&
+    (!Number.isFinite(transition.delay) || transition.delay < 0)
+  )
+    throw new RangeError('State transition delay must be finite and nonnegative.')
+  return { ...transition }
+}