@webspatial/core-sdk 1.7.0 → 2.0.0

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 },
+          ],
+        },
+      ],
+    })
+  })
+})

package/src/motion/compute/normalize.ts

@@ -0,0 +1,289 @@
+import type { SpatializedVisualValues } from '../../types/motion/spatializedVisual'
+import type { TimingFunction } from '../../types/animation'
+import type {
+  NormalizedSpatializedMotionConfig,
+  SpatializedMotionConfig,
+  SpatializedMotionProperty,
+  SpatializedMotionSegmentConfig,
+  SpatializedMotionTrack,
+  SpatializedMotionTimelineConfig,
+} from '../../types/motion/spatializedMotion'
+
+/**
+ * Flattens visual values into motion-property/value pairs.
+ *
+ * @param values Visual values to inspect.
+ * @param out Collector for discovered motion property samples.
+ */
+function collectScalars(
+  values: SpatializedVisualValues,
+  out: Array<{ property: SpatializedMotionProperty; value: number }>,
+): void {
+  if (values.opacity !== undefined) {
+    out.push({ property: 'opacity', value: values.opacity })
+  }
+  const tr = values.transform
+  if (!tr) return
+  for (const group of ['translate', 'rotate', 'scale'] as const) {
+    const part = tr[group]
+    if (!part) continue
+    for (const axis of ['x', 'y', 'z'] as const) {
+      const v = part[axis]
+      if (v !== undefined) {
+        out.push({
+          property: `transform.${group}.${axis}` as SpatializedMotionProperty,
+          value: v,
+        })
+      }
+    }
+  }
+}
+
+/**
+ * Converts `0%`-style timeline keys into [0, 1] ratios.
+ *
+ * @param key Percentage key from the timeline config.
+ * @returns The normalized ratio represented by the key.
+ */
+function parsePercentageKey(key: string): number {
+  if (!/^\d+(\.\d+)?%$/.test(key)) {
+    throw new Error(`[SpatializedMotion] invalid timeline key "${key}"`)
+  }
+  const ratio = Number(key.slice(0, -1))
+  if (!Number.isFinite(ratio) || ratio < 0 || ratio > 100) {
+    throw new Error(`[SpatializedMotion] invalid timeline key "${key}"`)
+  }
+  return ratio / 100
+}
+
+/**
+ * Desugars shorthand from/to motion config into canonical tracks.
+ *
+ * @param simple Shorthand segment config.
+ * @returns Canonical track-based motion config.
+ */
+export function segmentConfigToMotionConfig(
+  simple: SpatializedMotionSegmentConfig,
+): NormalizedSpatializedMotionConfig {
+  if (!simple.from || !simple.to) {
+    throw new Error(
+      '[SpatializedMotion] top-level from and to are both required',
+    )
+  }
+  const duration = simple.duration ?? 0.3
+  const fromScalars: Array<{
+    property: SpatializedMotionProperty
+    value: number
+  }> = []
+  const toScalars: Array<{
+    property: SpatializedMotionProperty
+    value: number
+  }> = []
+
+  collectScalars(simple.from, fromScalars)
+  collectScalars(simple.to, toScalars)
+
+  const trackMap = new Map<SpatializedMotionProperty, SpatializedMotionTrack>()
+  const properties = new Set([
+    ...fromScalars.map(entry => entry.property),
+    ...toScalars.map(entry => entry.property),
+  ])
+
+  for (const property of properties) {
+    const fromEntry = fromScalars.find(f => f.property === property)
+    const toEntry = toScalars.find(f => f.property === property)
+    if (!fromEntry) {
+      throw new Error(
+        `[SpatializedMotion] missing start boundary for "${property}"`,
+      )
+    }
+    if (!toEntry) {
+      throw new Error(
+        `[SpatializedMotion] missing end boundary for "${property}"`,
+      )
+    }
+    trackMap.set(property, {
+      property,
+      timingFunction: simple.timingFunction,
+      keyframes: [
+        { at: 0, value: fromEntry.value },
+        { at: duration, value: toEntry.value },
+      ],
+    })
+  }
+
+  const tracks = [...trackMap.values()]
+  if (tracks.length === 0) {
+    throw new Error(
+      '[SpatializedMotion.simple] to must include at least one animatable field',
+    )
+  }
+
+  return {
+    duration,
+    tracks,
+    timingFunction: simple.timingFunction,
+    delay: simple.delay,
+    autoStart: simple.autoStart,
+    loop: simple.loop,
+    playbackRate: simple.playbackRate,
+    onStart: simple.onStart,
+    onComplete: simple.onComplete,
+    onStop: simple.onStop,
+    onReset: simple.onReset,
+    onError: simple.onError,
+  }
+}
+
+/**
+ * Desugars percentage-key timeline config into canonical tracks.
+ *
+ * @param config Timeline config using percentage keys.
+ * @returns Canonical track-based motion config.
+ */
+export function desugarTimelineConfig(
+  config: SpatializedMotionTimelineConfig,
+): NormalizedSpatializedMotionConfig {
+  if (Array.isArray(config.timeline) || !config.timeline) {
+    throw new Error('[SpatializedMotion] timeline must be an object')
+  }
+
+  const entries = Object.entries(config.timeline)
+  let hasPercentageKey = false
+  const frames = entries
+    .map(([key, values]) => {
+      if (!values || typeof values !== 'object' || Array.isArray(values)) {
+        throw new Error(`[SpatializedMotion] invalid timeline frame "${key}"`)
+      }
+      if (key === 'from') return { key, atRatio: 0, values }
+      if (key === 'to') return { key, atRatio: 1, values }
+      hasPercentageKey = true
+      return { key, atRatio: parsePercentageKey(key), values }
+    })
+    .sort((a, b) => a.atRatio - b.atRatio)
+
+  // Dev warn: top-level from/to are ignored once a timeline is present.
+  if (config.from !== undefined || config.to !== undefined) {
+    console.warn(
+      '[SpatializedMotion] top-level from/to are ignored because timeline is present',
+    )
+  }
+
+  // Start/end boundary frames are required; this change does not fill missing
+  // boundaries from underlying element style.
+  const hasStartFrame = frames.some(frame => frame.atRatio === 0)
+  const hasEndFrame = frames.some(frame => frame.atRatio === 1)
+  if (!hasStartFrame) {
+    throw new Error(
+      '[SpatializedMotion] timeline must define a start frame (from or 0%)',
+    )
+  }
+  if (!hasEndFrame) {
+    throw new Error(
+      '[SpatializedMotion] timeline must define an end frame (to or 100%)',
+    )
+  }
+
+  if (hasPercentageKey && config.duration === undefined) {
+    throw new Error(
+      '[SpatializedMotion] duration is required when timeline uses percentage keys',
+    )
+  }
+  const duration = config.duration ?? 0.3
+
+  const trackMap = new Map<
+    SpatializedMotionProperty,
+    Array<{
+      at: number
+      value: number
+      timingFunction?: TimingFunction
+    }>
+  >()
+  const fromProperties = new Set<SpatializedMotionProperty>()
+  const zeroProperties = new Set<SpatializedMotionProperty>()
+  const toProperties = new Set<SpatializedMotionProperty>()
+  const hundredProperties = new Set<SpatializedMotionProperty>()
+
+  for (const frame of frames) {
+    const at = frame.atRatio * duration
+    const scalars: Array<{
+      property: SpatializedMotionProperty
+      value: number
+    }> = []
+    collectScalars(frame.values, scalars)
+    for (const scalar of scalars) {
+      if (frame.key === 'from') fromProperties.add(scalar.property)
+      if (frame.key !== 'from' && frame.atRatio === 0) {
+        zeroProperties.add(scalar.property)
+      }
+      if (frame.key === 'to') toProperties.add(scalar.property)
+      if (frame.key !== 'to' && frame.atRatio === 1) {
+        hundredProperties.add(scalar.property)
+      }
+      const keyframes = trackMap.get(scalar.property) ?? []
+      const keyframe = {
+        at,
+        value: scalar.value,
+        ...(frame.values.timingFunction !== undefined
+          ? { timingFunction: frame.values.timingFunction }
+          : {}),
+      }
+      keyframes.push(keyframe)
+      trackMap.set(scalar.property, keyframes)
+    }
+  }
+
+  const tracks = [...trackMap.entries()].map(([property, keyframes]) => {
+    const startCount =
+      Number(fromProperties.has(property)) +
+      Number(zeroProperties.has(property))
+    const endCount =
+      Number(toProperties.has(property)) +
+      Number(hundredProperties.has(property))
+    if (startCount > 1) {
+      throw new Error(
+        `[SpatializedMotion] duplicate start boundary for "${property}"`,
+      )
+    }
+    if (endCount > 1) {
+      throw new Error(
+        `[SpatializedMotion] duplicate end boundary for "${property}"`,
+      )
+    }
+    return {
+      property,
+      timingFunction: config.timingFunction,
+      keyframes,
+    }
+  })
+
+  return {
+    duration,
+    tracks,
+    timingFunction: config.timingFunction,
+    delay: config.delay,
+    autoStart: config.autoStart,
+    loop: config.loop,
+    playbackRate: config.playbackRate,
+    onStart: config.onStart,
+    onComplete: config.onComplete,
+    onStop: config.onStop,
+    onReset: config.onReset,
+    onError: config.onError,
+  }
+}
+
+/**
+ * Normalizes any supported motion config shape into canonical tracks.
+ *
+ * @param config Motion config in shorthand, timeline, or canonical form.
+ * @returns Canonical track-based motion config.
+ */
+export function normalizeMotionConfig(
+  config: SpatializedMotionConfig,
+): NormalizedSpatializedMotionConfig {
+  if (config.timeline !== undefined) {
+    return desugarTimelineConfig(config as SpatializedMotionTimelineConfig)
+  }
+  return segmentConfigToMotionConfig(config as SpatializedMotionSegmentConfig)
+}