@webspatial/core-sdk 1.6.1 → 2.0.0

package/src/motion/AnimationObject.ts

@@ -0,0 +1,208 @@
+import {
+  ControlSpatializedElementAnimationJSBCommand,
+  CreateSpatializedElementAnimationJSBCommand,
+} from '../JSBCommand'
+import { SpatialObject } from '../SpatialObject'
+import { SpatialWebEvent } from '../SpatialWebEvent'
+import type {
+  ControlSpatializedElementAnimationCommand,
+  SpatialAnimationStateChangedDetail,
+  SpatialAnimationStateChangedMsg,
+} from '../types/motion/spatializedElementMotion'
+import type { SpatializedPlaybackError } from '../types/motion/spatializedPlayback'
+import type { SpatializedVisualValues } from '../types/motion/spatializedVisual'
+import type {
+  SpatializedMotionTimeline,
+  SpatializedPlaybackApi,
+  SpatializedMotionPlayState,
+} from '../types/motion/spatializedMotion'
+
+export interface AnimationObjectCreateOptions {
+  elementId: string
+  timeline: SpatializedMotionTimeline
+}
+
+export interface AnimationObjectCallbacks {
+  onStart?: () => void
+  onComplete?: (values: SpatializedVisualValues) => void
+  onStop?: (values: SpatializedVisualValues) => void
+  onReset?: (values: SpatializedVisualValues) => void
+  onError?: (error: SpatializedPlaybackError) => void
+  onValuesChange?: (values: SpatializedVisualValues) => void
+  onStateChange?: () => void
+}
+
+export class AnimationObject
+  extends SpatialObject
+  implements SpatializedPlaybackApi
+{
+  readonly elementId: string
+  readonly timeline: SpatializedMotionTimeline
+
+  private callbacks: AnimationObjectCallbacks = {}
+  private _playState: SpatializedMotionPlayState = 'idle'
+  private _finished = false
+  private started = false
+
+  constructor(id: string, options: AnimationObjectCreateOptions) {
+    super(id)
+    this.elementId = options.elementId
+    this.timeline = options.timeline
+
+    SpatialWebEvent.addEventReceiver(id, data => this.onReceiveEvent(data))
+  }
+
+  static async create(options: AnimationObjectCreateOptions) {
+    const ret = await new CreateSpatializedElementAnimationJSBCommand({
+      elementId: options.elementId,
+      timeline: options.timeline,
+    }).execute()
+    if (!ret.success) {
+      throw new Error(
+        ret.errorMessage ?? 'CreateSpatializedElementAnimation command failed',
+      )
+    }
+
+    const data = ret.data as { id?: string } | undefined
+    const id = data?.id
+    if (!id) {
+      throw new Error('CreateSpatializedElementAnimation did not return an id')
+    }
+
+    return new AnimationObject(id, options)
+  }
+
+  setCallbacks(callbacks: AnimationObjectCallbacks): void {
+    this.callbacks = callbacks
+  }
+
+  get playState() {
+    return this._playState
+  }
+
+  get isAnimating() {
+    return this._playState === 'running' || this._playState === 'queued'
+  }
+
+  get isPaused() {
+    return this._playState === 'paused'
+  }
+
+  get finished() {
+    return this._finished
+  }
+
+  play(): Promise<void> {
+    return this.control('play')
+  }
+
+  pause(): Promise<void> {
+    return this.control('pause')
+  }
+
+  stop(): Promise<void> {
+    return this.control('stop')
+  }
+
+  reset(): Promise<void> {
+    return this.control('reset')
+  }
+
+  finish(): Promise<void> {
+    return this.control('finish')
+  }
+
+  protected override onDestroy(): void {
+    SpatialWebEvent.removeEventReceiver(this.id)
+  }
+
+  private async control(
+    type: ControlSpatializedElementAnimationCommand['type'],
+  ): Promise<void> {
+    if (this.isDestroyed) return
+
+    const ret = await new ControlSpatializedElementAnimationJSBCommand({
+      animationId: this.id,
+      type,
+    }).execute()
+
+    if (!ret.success) {
+      throw new Error(
+        ret.errorMessage ??
+          `ControlSpatializedElementAnimation(${type}) command failed`,
+      )
+    }
+  }
+
+  onReceiveEvent(data: SpatialAnimationStateChangedMsg | { detail?: unknown }) {
+    const detail = data?.detail ?? data
+    if (!this.isSpatialAnimationStateChangedDetail(detail)) return
+    if (detail.animationId !== this.id) return
+
+    this._playState = detail.playState
+    this._finished = detail.finished
+
+    if (detail.values) {
+      this.callbacks.onValuesChange?.(detail.values)
+    }
+    if (detail.action !== 'start') {
+      this.callbacks.onStateChange?.()
+    }
+
+    if (detail.error) {
+      this.started = false
+      // Native currently emits asynchronous errors only when play cannot acquire the ownership mask.
+      this.callbacks.onError?.({
+        command: 'play',
+        code: detail.error.code,
+        reason: detail.error.message,
+      })
+      return
+    }
+
+    if (detail.action === 'start') {
+      if (!this.started) {
+        this.started = true
+        this.callbacks.onStart?.()
+      }
+      return
+    }
+
+    if (detail.action === 'complete' || detail.action === 'finish') {
+      this.started = false
+      this.callbacks.onComplete?.(detail.values ?? {})
+      return
+    }
+
+    if (detail.action === 'stop') {
+      this.started = false
+      this.callbacks.onStop?.(detail.values ?? {})
+      return
+    }
+
+    if (detail.action === 'reset') {
+      this.started = false
+      this.callbacks.onReset?.(detail.values ?? {})
+      return
+    }
+
+    if (detail.action === 'destroy') {
+      this.started = false
+      this.isDestroyed = true
+      this.onDestroy()
+    }
+  }
+
+  private isSpatialAnimationStateChangedDetail(
+    detail: unknown,
+  ): detail is SpatialAnimationStateChangedDetail {
+    if (!detail || typeof detail !== 'object') return false
+    const candidate = detail as Partial<SpatialAnimationStateChangedDetail>
+    return (
+      typeof candidate.animationId === 'string' &&
+      typeof candidate.action === 'string' &&
+      typeof candidate.playState === 'string' &&
+      typeof candidate.finished === 'boolean'
+    )
+  }
+}

package/src/motion/compute/index.ts

@@ -0,0 +1,10 @@
+export { setMotionPropertyValue } from './motionPropertyValues'
+export {
+  validateNormalizedMotionConfig,
+  validateSpatializedMotionConfig,
+} from './validate'
+export {
+  desugarTimelineConfig,
+  normalizeMotionConfig,
+  segmentConfigToMotionConfig,
+} from './normalize'

package/src/motion/compute/motionPropertyValues.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'vitest'
+import type { SpatializedMotionProperty } from '../../types/motion/spatializedMotion'
+import { setMotionPropertyValue } from './motionPropertyValues'
+
+describe('setMotionPropertyValue', () => {
+  test('writes opacity', () => {
+    const values = {}
+
+    setMotionPropertyValue(values, 'opacity', 0.5)
+
+    expect(values).toEqual({ opacity: 0.5 })
+  })
+
+  test.each([
+    ['transform.translate.x', { transform: { translate: { x: 1 } } }],
+    ['transform.translate.y', { transform: { translate: { y: 2 } } }],
+    ['transform.translate.z', { transform: { translate: { z: 3 } } }],
+    ['transform.rotate.x', { transform: { rotate: { x: 4 } } }],
+    ['transform.rotate.y', { transform: { rotate: { y: 5 } } }],
+    ['transform.rotate.z', { transform: { rotate: { z: 6 } } }],
+    ['transform.scale.x', { transform: { scale: { x: 7 } } }],
+    ['transform.scale.y', { transform: { scale: { y: 8 } } }],
+    ['transform.scale.z', { transform: { scale: { z: 9 } } }],
+  ] as const)('writes %s', (motionProperty, expected) => {
+    const values = {}
+    const sampledValue = Object.values(
+      Object.values(expected.transform ?? {})[0] ?? {},
+    )[0] as number
+
+    setMotionPropertyValue(
+      values,
+      motionProperty as SpatializedMotionProperty,
+      sampledValue,
+    )
+
+    expect(values).toEqual(expected)
+  })
+
+  test('preserves existing transform groups while writing another property', () => {
+    const values = {
+      transform: {
+        translate: { x: 10 },
+      },
+    }
+
+    setMotionPropertyValue(values, 'transform.rotate.y', 20)
+
+    expect(values).toEqual({
+      transform: {
+        translate: { x: 10 },
+        rotate: { y: 20 },
+      },
+    })
+  })
+})

package/src/motion/compute/motionPropertyValues.ts

@@ -0,0 +1,70 @@
+import type { SpatializedVisualValues } from '../../types/motion/spatializedVisual'
+import type { SpatializedMotionProperty } from '../../types/motion/spatializedMotion'
+
+function getTranslate(
+  visualValues: SpatializedVisualValues,
+): NonNullable<NonNullable<SpatializedVisualValues['transform']>['translate']> {
+  const transform = (visualValues.transform ??= {})
+  return (transform.translate ??= {})
+}
+
+function getRotate(
+  visualValues: SpatializedVisualValues,
+): NonNullable<NonNullable<SpatializedVisualValues['transform']>['rotate']> {
+  const transform = (visualValues.transform ??= {})
+  return (transform.rotate ??= {})
+}
+
+function getScale(
+  visualValues: SpatializedVisualValues,
+): NonNullable<NonNullable<SpatializedVisualValues['transform']>['scale']> {
+  const transform = (visualValues.transform ??= {})
+  return (transform.scale ??= {})
+}
+
+/**
+ * Writes a sampled numeric track value into the corresponding
+ * SpatializedVisualValues field.
+ *
+ * @param visualValues Visual value object being populated for the sampled time.
+ * @param motionProperty Motion property path for the sampled track.
+ * @param sampledValue Numeric value sampled from the track at the current time.
+ */
+export function setMotionPropertyValue(
+  visualValues: SpatializedVisualValues,
+  motionProperty: SpatializedMotionProperty,
+  sampledValue: number,
+): void {
+  switch (motionProperty) {
+    case 'opacity':
+      visualValues.opacity = sampledValue
+      return
+    case 'transform.translate.x':
+      getTranslate(visualValues).x = sampledValue
+      return
+    case 'transform.translate.y':
+      getTranslate(visualValues).y = sampledValue
+      return
+    case 'transform.translate.z':
+      getTranslate(visualValues).z = sampledValue
+      return
+    case 'transform.rotate.x':
+      getRotate(visualValues).x = sampledValue
+      return
+    case 'transform.rotate.y':
+      getRotate(visualValues).y = sampledValue
+      return
+    case 'transform.rotate.z':
+      getRotate(visualValues).z = sampledValue
+      return
+    case 'transform.scale.x':
+      getScale(visualValues).x = sampledValue
+      return
+    case 'transform.scale.y':
+      getScale(visualValues).y = sampledValue
+      return
+    case 'transform.scale.z':
+      getScale(visualValues).z = sampledValue
+      return
+  }
+}

package/src/motion/compute/normalize.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, test, vi } from 'vitest'
+import { normalizeMotionConfig } from './normalize'
+
+describe('normalizeMotionConfig', () => {
+  test('normalizes mixed timeline entries into numeric tracks', () => {
+    expect(
+      normalizeMotionConfig({
+        duration: 2,
+        timeline: {
+          from: { opacity: 0, transform: { translate: { x: 0 } } },
+          '50%': { opacity: 0.5 },
+          to: { opacity: 1, transform: { translate: { x: 10 } } },
+        },
+      }),
+    ).toMatchObject({
+      duration: 2,
+      tracks: [
+        {
+          property: 'opacity',
+          keyframes: [
+            { at: 0, value: 0 },
+            { at: 1, value: 0.5 },
+            { at: 2, value: 1 },
+          ],
+        },
+        {
+          property: 'transform.translate.x',
+          keyframes: [
+            { at: 0, value: 0 },
+            { at: 2, value: 10 },
+          ],
+        },
+      ],
+    })
+  })
+
+  test('uses only timeline values when top-level boundaries are present', () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    expect(
+      normalizeMotionConfig({
+        from: { opacity: 0.25 },
+        to: { opacity: 0.75 },
+        timeline: {
+          from: { opacity: 0 },
+          to: { opacity: 1 },
+        },
+      }),
+    ).toMatchObject({
+      duration: 0.3,
+      tracks: [
+        {
+          property: 'opacity',
+          keyframes: [
+            { at: 0, value: 0 },
+            { at: 0.3, value: 1 },
+          ],
+        },
+      ],
+    })
+    expect(warnSpy).toHaveBeenCalledWith(
+      expect.stringContaining('top-level from/to are ignored'),
+    )
+    warnSpy.mockRestore()
+  })
+
+  test('preserves sparse property keyframe ranges', () => {
+    expect(
+      normalizeMotionConfig({
+        duration: 2,
+        timeline: {
+          '0%': { transform: { rotate: { z: -20 } } },
+          '50%': {
+            opacity: 0,
+            transform: { rotate: { z: 80 } },
+          },
+          '100%': { opacity: 1 },
+        },
+      }),
+    ).toMatchObject({
+      duration: 2,
+      tracks: [
+        {
+          property: 'transform.rotate.z',
+          keyframes: [
+            { at: 0, value: -20 },
+            { at: 1, value: 80 },
+          ],
+        },
+        {
+          property: 'opacity',
+          keyframes: [
+            { at: 1, value: 0 },
+            { at: 2, value: 1 },
+          ],
+        },
+      ],
+    })
+  })
+})