@webspatial/core-sdk 1.0.4 → 1.1.0

package/src/types/types.ts

@@ -0,0 +1,380 @@
+import type { SpatialEntity } from '..'
+import { SpatialGeometry } from '../reality/geometry/SpatialGeometry'
+import { SpatialMaterial } from '../reality/material/SpatialMaterial'
+import type { SpatializedDynamic3DElement } from '../SpatializedDynamic3DElement'
+
+export interface Vec3 {
+  x: number
+  y: number
+  z: number
+}
+
+export type Point3D = Vec3
+
+/**
+ * Material type for SpatialDiv or HTML document.
+ *
+ * This type defines the background material options for both SpatialDiv elements and HTML documents.
+ *
+ * - `'none'`: This is the default value.
+ *   - For HTML documents, the web page window will have the default native background.
+ *   - For SpatialDiv, the window will have a transparent background.
+ * - `'translucent'`: Represents a glass-like material in AVP (Apple Vision Pro).
+ * - `'thick'`: Represents a thick material in AVP.
+ * - `'regular'`: Represents a regular material in AVP.
+ * - `'thin'`: Represents a thin material in AVP.
+ * - `'transparent'`: Represents a fully transparent background.
+ */
+export type BackgroundMaterialType =
+  | 'none'
+  | 'translucent'
+  | 'thick'
+  | 'regular'
+  | 'thin'
+  | 'transparent'
+
+export type CornerRadius = {
+  topLeading: number
+  bottomLeading: number
+  topTrailing: number
+  bottomTrailing: number
+}
+
+export interface SpatialSceneProperties {
+  cornerRadius: CornerRadius
+  material: BackgroundMaterialType
+  opacity: number
+}
+
+export enum SpatializedElementType {
+  Spatialized2DElement,
+  SpatializedStatic3DElement,
+  SpatializedDynamic3DElement,
+}
+
+export interface SpatializedElementProperties {
+  name: string
+  clientX: number
+  clientY: number
+  width: number
+  height: number
+  depth: number
+  opacity: number
+  visible: boolean
+  scrollWithParent: boolean
+  zIndex: number
+  backOffset: number
+  rotationAnchor: Point3D
+  enableTapGesture: boolean
+  enableDragStartGesture: boolean
+  enableDragGesture: boolean
+  enableDragEndGesture: boolean
+  enableRotateStartGesture: boolean
+  enableRotateGesture: boolean
+  enableRotateEndGesture: boolean
+  enableMagnifyStartGesture: boolean
+  enableMagnifyGesture: boolean
+  enableMagnifyEndGesture: boolean
+}
+
+export interface Spatialized2DElementProperties
+  extends SpatializedElementProperties {
+  scrollPageEnabled: boolean
+  cornerRadius: CornerRadius
+  material: BackgroundMaterialType
+  scrollEdgeInsetsMarginRight: number
+}
+
+export interface SpatializedStatic3DElementProperties
+  extends SpatializedElementProperties {
+  modelURL: string
+  modelTransform?: number[]
+}
+
+export interface SpatialSceneCreationOptions {
+  defaultSize?: {
+    width: number | string // Initial width of the window
+    height: number | string // Initial height of the window
+    depth?: number | string // Initial depth of the window, only for volume
+  }
+
+  resizability?: {
+    minWidth?: number | string // Minimum width of the window
+    minHeight?: number | string // Minimum height of the window
+    maxWidth?: number | string // Maximum width of the window
+    maxHeight?: number | string // Maximum height of the window
+  }
+  worldScaling?: WorldScalingType
+  worldAlignment?: WorldAlignmentType
+
+  baseplateVisibility?: BaseplateVisibilityType
+}
+
+export const BaseplateVisibilityValues = [
+  'automatic',
+  'visible',
+  'hidden',
+] as const
+export type BaseplateVisibilityType = (typeof BaseplateVisibilityValues)[number]
+
+export function isValidBaseplateVisibilityType(type: string): Boolean {
+  return BaseplateVisibilityValues.includes(type as BaseplateVisibilityType)
+}
+
+export const WorldScalingValues = ['automatic', 'dynamic'] as const
+export type WorldScalingType = (typeof WorldScalingValues)[number]
+
+export function isValidWorldScalingType(type: string): Boolean {
+  return WorldScalingValues.includes(type as WorldScalingType)
+}
+
+export const WorldAlignmentValues = [
+  'adaptive',
+  'automatic',
+  'gravityAligned',
+] as const
+export type WorldAlignmentType = (typeof WorldAlignmentValues)[number]
+
+export function isValidWorldAlignmentType(type: string): Boolean {
+  return WorldAlignmentValues.includes(type as WorldAlignmentType)
+}
+
+export const SpatialSceneValues = ['window', 'volume'] as const
+export type SpatialSceneType = (typeof SpatialSceneValues)[number]
+
+export function isValidSpatialSceneType(type: string): Boolean {
+  return SpatialSceneValues.includes(type as SpatialSceneType)
+}
+
+/**
+ * check px,m and number, number must be >= 0
+ *
+ * */
+export function isValidSceneUnit(val: string | number): boolean {
+  // only support number or string with unit px or m
+  // rpx cm mm not allowed
+  if (typeof val === 'number') {
+    return val >= 0
+  }
+  if (typeof val === 'string') {
+    if (val.endsWith('px')) {
+      // check if number
+      if (isNaN(Number(val.slice(0, -2)))) {
+        return false
+      }
+      return Number(val.slice(0, -2)) >= 0
+    }
+    if (val.endsWith('m')) {
+      // check if number
+      if (isNaN(Number(val.slice(0, -1)))) {
+        return false
+      }
+      return Number(val.slice(0, -1)) >= 0
+    }
+  }
+  return false
+}
+
+export interface SpatialEntityProperties {
+  position: Vec3
+  rotation: Vec3
+  scale: Vec3
+}
+
+export type SpatialEntityEventType = 'spatialtap' //| 'drag' | 'rotate' | 'scale'
+
+export type SpatialGeometryType =
+  | 'BoxGeometry'
+  | 'PlaneGeometry'
+  | 'SphereGeometry'
+  | 'CylinderGeometry'
+  | 'ConeGeometry'
+
+export interface SpatialBoxGeometryOptions {
+  width?: number
+  height?: number
+  depth?: number
+  cornerRadius?: number
+  splitFaces?: boolean
+}
+
+export interface SpatialPlaneGeometryOptions {
+  width?: number
+  height?: number
+  cornerRadius?: number
+}
+
+export interface SpatialSphereGeometryOptions {
+  radius?: number
+}
+
+export interface SpatialConeGeometryOptions {
+  radius?: number
+  height?: number
+}
+
+export interface SpatialCylinderGeometryOptions {
+  radius?: number
+  height?: number
+}
+
+export type SpatialGeometryOptions =
+  | SpatialBoxGeometryOptions
+  | SpatialPlaneGeometryOptions
+  | SpatialSphereGeometryOptions
+  | SpatialCylinderGeometryOptions
+  | SpatialConeGeometryOptions
+
+export type SpatialMaterialType = 'unlit'
+
+export interface SpatialUnlitMaterialOptions {
+  color?: string
+  textureId?: string
+  transparent?: boolean
+  opacity?: number
+}
+
+export interface ModelComponentOptions {
+  mesh: SpatialGeometry
+  materials: SpatialMaterial[]
+}
+
+export interface SpatialEntityUserData {
+  id?: string
+  name?: string
+}
+
+export interface SpatialModelEntityCreationOptions {
+  modelAssetId: string
+  name?: string
+}
+
+export interface ModelAssetOptions {
+  url: string
+}
+
+export enum SpatialSceneState {
+  idle = 'idle',
+  pending = 'pending',
+  willVisible = 'willVisible',
+  visible = 'visible',
+  fail = 'fail',
+}
+
+/**
+ * Translate event, matching similar behavior to https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/drag_event
+ */
+export type SpatialModelDragEvent = {
+  eventType: 'dragstart' | 'dragend' | 'drag'
+  translation3D: Vec3
+  startLocation3D: Vec3
+}
+
+export interface Size {
+  width: number
+  height: number
+}
+
+export interface Size3D extends Size {
+  depth: number
+}
+
+export class CubeInfo {
+  constructor(
+    public size: Size3D,
+    public origin: Vec3,
+  ) {
+    this.size = size
+    this.origin = origin
+  }
+
+  get x() {
+    return this.origin.x
+  }
+
+  get y() {
+    return this.origin.y
+  }
+
+  get z() {
+    return this.origin.z
+  }
+
+  get width() {
+    return this.size.width
+  }
+
+  get height() {
+    return this.size.height
+  }
+
+  get depth() {
+    return this.size.depth
+  }
+
+  get left() {
+    return this.x
+  }
+
+  get top() {
+    return this.y
+  }
+
+  get right() {
+    return this.x + this.width
+  }
+
+  get bottom() {
+    return this.y + this.height
+  }
+
+  get back() {
+    return this.z
+  }
+
+  get front() {
+    return this.z + this.depth
+  }
+}
+
+export interface SpatialTapEventDetail {
+  location3D: Point3D
+}
+
+export type SpatialTapEvent = CustomEvent<SpatialTapEventDetail>
+
+export interface SpatialDragEventDetail {
+  location3D: Point3D
+  startLocation3D: Point3D
+  translation3D: Vec3
+  predictedEndTranslation3D: Vec3
+  predictedEndLocation3D: Point3D
+  velocity: Size
+}
+
+export type SpatialDragEvent = CustomEvent<SpatialDragEventDetail>
+
+export type SpatialDragEndEvent = SpatialDragEvent
+
+export interface SpatialRotateEventDetail {
+  rotation: { vector: [number, number, number, number] }
+  startAnchor3D: Vec3
+  startLocation3D: Point3D
+}
+
+export type SpatialRotateEvent = CustomEvent<SpatialRotateEventDetail>
+
+export type SpatialRotateEndEvent = SpatialRotateEvent
+
+export interface SpatialMagnifyEventDetail {
+  magnification: number
+  velocity: number
+  startAnchor3D: Vec3
+  startLocation3D: Point3D
+}
+
+export type SpatialMagnifyEvent = CustomEvent<SpatialMagnifyEventDetail>
+
+export type SpatialMagnifyEndEvent = SpatialMagnifyEvent
+
+export type SpatialEntityOrReality = SpatialEntity | SpatializedDynamic3DElement

package/src/utils.ts

@@ -0,0 +1,61 @@
+import { Vec3 } from './types/types'
+
+function parseBorderRadius(borderProperty: string, width: number) {
+  if (borderProperty === '') {
+    return 0
+  }
+  if (borderProperty.endsWith('%')) {
+    return (width * parseFloat(borderProperty)) / 100
+  }
+  return parseFloat(borderProperty)
+}
+
+export function parseCornerRadius(computedStyle: CSSStyleDeclaration) {
+  const width = parseFloat(computedStyle.getPropertyValue('width'))
+
+  const topLeftPropertyValue = computedStyle.getPropertyValue(
+    'border-top-left-radius',
+  )
+  const topRightPropertyValue = computedStyle.getPropertyValue(
+    'border-top-right-radius',
+  )
+  const bottomLeftPropertyValue = computedStyle.getPropertyValue(
+    'border-bottom-left-radius',
+  )
+  const bottomRightPropertyValue = computedStyle.getPropertyValue(
+    'border-bottom-right-radius',
+  )
+
+  const cornerRadius = {
+    topLeading: parseBorderRadius(topLeftPropertyValue, width),
+    bottomLeading: parseBorderRadius(bottomLeftPropertyValue, width),
+    topTrailing: parseBorderRadius(topRightPropertyValue, width),
+    bottomTrailing: parseBorderRadius(bottomRightPropertyValue, width),
+  }
+
+  return cornerRadius
+}
+
+/**
+ *
+ * compose SRT matrix
+ * @export
+ * @param {Vec3} position meter
+ * @param {Vec3} rotation degree
+ * @param {Vec3} scale
+ * @return {*}  {DOMMatrix}
+ */
+export function composeSRT(position: Vec3, rotation: Vec3, scale: Vec3) {
+  const { x: px, y: py, z: pz } = position
+  const { x: rx, y: ry, z: rz } = rotation
+  const { x: sx, y: sy, z: sz } = scale
+
+  let m = new DOMMatrix()
+  // https://drafts.fxtf.org/geometry/#immutable-transformation-methods
+  // as these methods are post-multiplication, the order of transformations is reversed
+  // we want SRT = T * R * S
+  m = m.translate(px, py, pz)
+  m = m.rotate(rx, ry, rz)
+  m = m.scale(sx, sy, sz)
+  return m
+}

package/tsconfig.json

@@ -21,6 +21,6 @@
     "outDir": "./dist",
     "allowSyntheticDefaultImports": true
   },
-  "include": ["src/index.ts", "src/types/*.d.ts"],
+  "include": ["src/**/*.ts", "src/types/*.d.ts"],
   "references": []
 }

package/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom', // provide window / document
+  },
+})

package/src/core/Spatial.ts

@@ -1,50 +0,0 @@
-import { SpatialSession } from './SpatialSession'
-
-/**
- * Base object designed to be placed on navigator.spatial to mirror navigator.xr for webxr
- */
-export class Spatial {
-  /**
-   * Requests a session object from the browser
-   * @returns The session or null if not availible in the current browser
-   * [TODO] discuss implications of this not being async
-   */
-  requestSession() {
-    if (
-      this.isSupported() &&
-      this.getNativeVersion() === this.getClientVersion()
-    ) {
-      return new SpatialSession()
-    } else {
-      return null
-    }
-  }
-
-  /**
-   * @returns true if web spatial is supported by this webpage
-   */
-  isSupported() {
-    return this.getNativeVersion() === this.getClientVersion()
-  }
-
-  /**
-   * Gets the native version, format is "x.x.x"
-   * @returns native version string
-   */
-  getNativeVersion() {
-    if (window.__WebSpatialData && window.__WebSpatialData.getNativeVersion) {
-      return window.__WebSpatialData.getNativeVersion()
-    }
-    return window.WebSpatailNativeVersion === 'PACKAGE_VERSION'
-      ? this.getClientVersion()
-      : window.WebSpatailNativeVersion
-  }
-
-  /**
-   * Gets the client version, format is "x.x.x"
-   * @returns client version string
-   */
-  getClientVersion() {
-    return __WEBSPATIAL_CORE_SDK_VERSION__
-  }
-}

package/src/core/SpatialEntity.ts

@@ -1,147 +0,0 @@
-import { SpatialObject } from './SpatialObject'
-import { SpatialTransform } from './SpatialTransform'
-import { SpatialWindowContainer } from './SpatialWindowContainer'
-import { WebSpatial } from './private/WebSpatial'
-import { SpatialComponent } from './component'
-
-/**
- * Entity used to describe an object that can be added to the scene
- */
-export class SpatialEntity extends SpatialObject {
-  /**
-   * Transform corresponding to the entity
-   * note: updateTransform must be called for transform to be synced to rendering
-   */
-  transform = new SpatialTransform()
-
-  /** @hidden */
-  private _destroyed = false
-  /** @hidden */
-  private get _entity() {
-    return this._resource
-  }
-
-  /**
-   * Syncs the transform with the renderer, must be called to observe updates
-   */
-  async updateTransform() {
-    await WebSpatial.updateResource(this._entity, this.transform)
-  }
-
-  /**
-   * Syncs the zIndex with the renderer
-   */
-  async updateZIndex(zIndex: number) {
-    await WebSpatial.updateResource(this._entity, { zIndex })
-  }
-
-  private components: Map<Function, SpatialComponent> = new Map()
-
-  /**
-   * Attaches a component to the entity to be displayed
-   * [TODO] review pass by value vs ref and ownership model for this
-   */
-  async setComponent(component: SpatialComponent) {
-    await WebSpatial.setComponent(this._entity, component._resource)
-    this.components.set(component.constructor, component)
-  }
-
-  /**
-   * Removes a component from the entity
-   */
-  async removeComponent<T extends SpatialComponent>(
-    type: new (...args: any[]) => T,
-  ) {
-    var c = this.getComponent(type)
-    if (c != undefined) {
-      await WebSpatial.removeComponent(this._entity, c._resource)
-      this.components.delete(c.constructor)
-    }
-  }
-
-  /**
-   * Gets a component from the entity
-   */
-  getComponent<T extends SpatialComponent>(
-    type: new (...args: any[]) => T,
-  ): T | undefined {
-    return this.components.get(type) as T | undefined
-  }
-
-  /**
-   * @hidden
-   * Sets the window container that this entity should be rendered by (this does not effect resource ownership)
-   * @param wg the window container that should render this entity
-   */
-  async _setParentWindowContainer(wg: SpatialWindowContainer) {
-    await WebSpatial.updateResource(this._entity, {
-      setParentWindowContainerID: wg._wg.id,
-    })
-  }
-
-  /**
-   * Sets a parent entity, if that entity or its parents are attached to a window container, this entity will be displayed
-   * @param e parent entity or null to remove current parent
-   */
-  async setParent(e: SpatialEntity | null) {
-    await WebSpatial.updateResource(this._entity, {
-      setParent: e ? e._entity.id : '',
-    })
-  }
-
-  /**
-   * Sets the coordinate space of this entity (Default: App)
-   * "App" = game engine style coordinates in meters
-   * "Dom" = Windowing coordinates in dom units (eg. 0,0,0 is top left of window)
-   * "Root" = Coordinate space is ignored and content is displayed and updated as window container's root object, window containers can only have one root entity
-   * [TODO] review this api
-   * @param space coordinate space mode
-   */
-  async setCoordinateSpace(space: 'App' | 'Dom' | 'Root') {
-    await WebSpatial.updateResource(this._entity, { setCoordinateSpace: space })
-  }
-
-  /**
-   * Query the 3d boudning box of the entity
-   * @returns The bounding box of the entity
-   */
-  async getBoundingBox() {
-    var res: any = await WebSpatial.updateResource(this._entity, {
-      getBoundingBox: true,
-    })
-    return res.data as {
-      center: { x: number; y: number; z: number }
-      extents: { x: number; y: number; z: number }
-    }
-  }
-
-  /**
-   * Sets if the entity should be visible (default: True)
-   * @param visible
-   */
-  async setVisible(visible: boolean) {
-    await WebSpatial.updateResource(this._entity, { visible })
-  }
-
-  /**
-   * Removes a reference to the entity by the renderer and this object should no longer be used. [TODO] Attached components will not be destroyed
-   */
-  async destroy() {
-    this._destroyed = true
-    await WebSpatial.destroyResource(this._entity)
-  }
-
-  /**
-   * Check if destroy has been called
-   */
-  isDestroyed() {
-    return this._destroyed
-  }
-
-  // Set Entity name. Currently for debugging only.
-  /** @hidden */
-  async _setName(name: string) {
-    this.name = name
-    return WebSpatial.updateResource(this._entity, { name })
-  }
-}