@webspatial/react-sdk 1.2.1 → 1.4.0

package/dist/default/index.d.ts

@@ -1,7 +1,8 @@
-import { SpatialSceneCreationOptions, SpatialSceneType, SpatialTapEvent as SpatialTapEvent$1, SpatialDragStartEvent as SpatialDragStartEvent$1, SpatialDragEvent as SpatialDragEvent$1, SpatialDragEndEvent as SpatialDragEndEvent$1, SpatialRotateEvent as SpatialRotateEvent$1, SpatialRotateEndEvent as SpatialRotateEndEvent$1, SpatialMagnifyEvent as SpatialMagnifyEvent$1, SpatialMagnifyEndEvent as SpatialMagnifyEndEvent$1, SpatializedElement, Point3D, SpatialObject, SpatialSession, SpatializedDynamic3DElement, Vec3, SpatialEntity, SpatialBoxGeometryOptions, SpatialUnlitMaterialOptions, SpatialSphereGeometryOptions, SpatialConeGeometryOptions, SpatialCylinderGeometryOptions, SpatialPlaneGeometryOptions } from '@webspatial/core-sdk';
+import * as _webspatial_core_sdk from '@webspatial/core-sdk';
+import { SpatialSceneCreationOptions, SpatialSceneType, SpatialTapEvent as SpatialTapEvent$1, SpatialDragStartEvent as SpatialDragStartEvent$1, SpatialDragEvent as SpatialDragEvent$1, SpatialDragEndEvent as SpatialDragEndEvent$1, SpatialRotateEvent as SpatialRotateEvent$1, SpatialRotateEndEvent as SpatialRotateEndEvent$1, SpatialMagnifyEvent as SpatialMagnifyEvent$1, SpatialMagnifyEndEvent as SpatialMagnifyEndEvent$1, SpatializedElement, Vec3, SpatialObject, SpatialSession, SpatializedDynamic3DElement, SpatialEntity, Quaternion, SpatialBoxGeometryOptions, SpatialUnlitMaterialOptions, SpatialSphereGeometryOptions, SpatialConeGeometryOptions, SpatialCylinderGeometryOptions, SpatialPlaneGeometryOptions, PhysicalMetrics } from '@webspatial/core-sdk';
 export { Point3D, Vec3 } from '@webspatial/core-sdk';
 import * as React$1 from 'react';
-import React__default, { ElementType, ForwardedRef } from 'react';
+import React__default, { ElementType, ForwardedRef, createElement as createElement$1 } from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
 declare function enableDebugTool(): void;
@@ -12,6 +13,13 @@ declare function initScene(name: string, callback: (pre: SpatialSceneCreationOpt
 
 declare const SpatialID = "data-spatial-id";
 
+/** Options for spatial pointer/gesture behavior (not DOM attributes). */
+type SpatialEventOptions = {
+    /**
+     * Direction vector for rotate gesture constraint. `[0, 0, 0]` or omit = unconstrained.
+     */
+    constrainedToAxis?: Vec3 | readonly [number, number, number];
+};
 type SpatialEventProps<T extends SpatializedElementRef> = {
     onSpatialTap?: (event: SpatialTapEvent<T>) => void;
     onSpatialDragStart?: (event: SpatialDragStartEvent<T>) => void;
@@ -27,22 +35,12 @@ interface StandardSpatializedContainerProps extends React__default.ComponentProp
     inStandardSpatializedContainer?: boolean;
     [SpatialID]: string;
 }
-type RealityForbiddenSpatialEventProps = {
-    onSpatialTap?: never;
-    onSpatialDragStart?: never;
-    onSpatialDrag?: never;
-    onSpatialDragEnd?: never;
-    onSpatialRotate?: never;
-    onSpatialRotateEnd?: never;
-    onSpatialMagnify?: never;
-    onSpatialMagnifyEnd?: never;
-};
-type RealityProps = React__default.ComponentPropsWithRef<'div'> & RealityForbiddenSpatialEventProps;
 type PortalSpatializedContainerProps<T extends SpatializedElementRef> = SpatialEventProps<T> & React__default.ComponentPropsWithoutRef<'div'> & {
     component: ElementType;
     spatializedContent: ElementType;
     createSpatializedElement: () => Promise<SpatializedElement>;
     getExtraSpatializedElementProperties?: (computedStyle: CSSStyleDeclaration) => Record<string, any>;
+    spatialEventOptions?: SpatialEventOptions;
     [SpatialID]: string;
 };
 type SpatializedContainerProps<T extends SpatializedElementRef> = Omit<StandardSpatializedContainerProps & PortalSpatializedContainerProps<T>, typeof SpatialID | 'onLoad' | 'onError'> & {
@@ -50,11 +48,13 @@ type SpatializedContainerProps<T extends SpatializedElementRef> = Omit<StandardS
 };
 type Spatialized2DElementContainerProps<P extends ElementType> = SpatialEventProps<SpatializedElementRef> & React__default.ComponentPropsWithRef<'div'> & {
     component: P;
+    spatialEventOptions?: SpatialEventOptions;
 };
 type SpatializedStatic3DContainerProps = SpatialEventProps<SpatializedStatic3DElementRef> & Omit<React__default.ComponentPropsWithoutRef<'div'>, 'onLoad' | 'onError'> & {
     src?: string;
     onLoad?: (event: ModelLoadEvent) => void;
     onError?: (event: ModelLoadEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
 };
 type SpatializedElementRef<T extends HTMLElement = HTMLElement> = T;
 type SpatializedDivElementRef = SpatializedElementRef<HTMLDivElement>;
@@ -70,17 +70,31 @@ type SpatialTapEvent<T extends SpatializedElementRef = SpatializedElementRef> =
     readonly offsetX: number;
     readonly offsetY: number;
     readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
 };
 type SpatialDragStartEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialDragStartEvent$1 & CurrentTarget<T> & {
     readonly offsetX: number;
     readonly offsetY: number;
     readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
+};
+type SpatialDragEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialDragEvent$1 & CurrentTarget<T> & {
+    readonly translationX: number;
+    readonly translationY: number;
+    readonly translationZ: number;
 };
-type SpatialDragEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialDragEvent$1 & CurrentTarget<T>;
 type SpatialDragEndEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialDragEndEvent$1 & CurrentTarget<T>;
-type SpatialRotateEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialRotateEvent$1 & CurrentTarget<T>;
+type SpatialRotateEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialRotateEvent$1 & CurrentTarget<T> & {
+    readonly quaternion: _webspatial_core_sdk.Quaternion;
+};
 type SpatialRotateEndEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialRotateEndEvent$1 & CurrentTarget<T>;
-type SpatialMagnifyEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialMagnifyEvent$1 & CurrentTarget<T>;
+type SpatialMagnifyEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialMagnifyEvent$1 & CurrentTarget<T> & {
+    readonly magnification: number;
+};
 type SpatialMagnifyEndEvent<T extends SpatializedElementRef = SpatializedElementRef> = SpatialMagnifyEndEvent$1 & CurrentTarget<T>;
 type ModelSpatialTapEvent = SpatialTapEvent<SpatializedStatic3DElementRef>;
 type ModelSpatialDragStartEvent = SpatialDragStartEvent<SpatializedStatic3DElementRef>;
@@ -115,13 +129,11 @@ declare const SpatializedStatic3DElementContainer: React$1.ForwardRefExoticCompo
     src?: string;
     onLoad?: (event: ModelLoadEvent) => void;
     onError?: (event: ModelLoadEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
 } & React$1.RefAttributes<SpatializedStatic3DElementRef>>;
 
 declare function withSpatialized2DElementContainer<P extends ElementType>(Component: P): P | React$1.ForwardRefExoticComponent<Omit<Spatialized2DElementContainerProps<P>, "ref"> & React$1.RefAttributes<HTMLElement>>;
 
-declare function toSceneSpatial(point: Point3D, spatializedElement: SpatializedElementRef): DOMPoint;
-declare function toLocalSpace(point: Point3D, spatializedElement: SpatializedElementRef): DOMPoint;
-
 declare function initPolyfill(): void;
 
 declare function withSpatialMonitor(El: React__default.ElementType): any;
@@ -140,10 +152,27 @@ declare class ResourceRegistry {
     destroy(): void;
 }
 
+type ContainerEntry = {
+    instanceId: string;
+    container: HTMLElement;
+};
+type ContainersChangeCallback = (containers: ContainerEntry[]) => void;
+declare class AttachmentRegistry {
+    private containers;
+    private listeners;
+    addContainer(name: string, instanceId: string, container: HTMLElement): void;
+    removeContainer(name: string, instanceId: string): void;
+    getContainers(name: string): ContainerEntry[];
+    onContainersChange(name: string, cb: ContainersChangeCallback): () => void;
+    private notifyListeners;
+    destroy(): void;
+}
+
 type RealityContextValue = {
     session: SpatialSession;
     reality: SpatializedDynamic3DElement;
     resourceRegistry: ResourceRegistry;
+    attachmentRegistry: AttachmentRegistry;
 } | null;
 
 interface EntityRefShape {
@@ -175,6 +204,7 @@ type EntityProps = {
     position?: Vec3;
     rotation?: Vec3;
     scale?: Vec3;
+    enableInput?: boolean;
 };
 type allTarget<T extends EntityRefShape> = {
     target: T;
@@ -184,23 +214,38 @@ type SpatialTapEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialT
     readonly offsetX: number;
     readonly offsetY: number;
     readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
 };
 type SpatialDragStartEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialDragStartEvent$1 & allTarget<T> & {
     readonly offsetX: number;
     readonly offsetY: number;
     readonly offsetZ: number;
+    readonly clientX: number;
+    readonly clientY: number;
+    readonly clientZ: number;
+};
+type SpatialDragEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialDragEvent$1 & allTarget<T> & {
+    readonly translationX: number;
+    readonly translationY: number;
+    readonly translationZ: number;
 };
-type SpatialDragEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialDragEvent$1 & allTarget<T>;
 type SpatialDragEndEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialDragEndEvent$1 & allTarget<T>;
-type SpatialRotateEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialRotateEvent$1 & allTarget<T>;
+type SpatialRotateEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialRotateEvent$1 & allTarget<T> & {
+    readonly quaternion: Quaternion;
+};
 type SpatialRotateEndEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialRotateEndEvent$1 & allTarget<T>;
-type SpatialMagnifyEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialMagnifyEvent$1 & allTarget<T>;
+type SpatialMagnifyEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialMagnifyEvent$1 & allTarget<T> & {
+    readonly magnification: number;
+};
 type SpatialMagnifyEndEntityEvent<T extends EntityRefShape = EntityRefShape> = SpatialMagnifyEndEvent$1 & allTarget<T>;
 type EntityEventHandler = {
     onSpatialTap?: (event: SpatialTapEntityEvent) => void;
     onSpatialDragStart?: (event: SpatialDragStartEntityEvent) => void;
     onSpatialDrag?: (event: SpatialDragEntityEvent) => void;
     onSpatialDragEnd?: (event: SpatialDragEndEntityEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
     onSpatialRotate?: (event: SpatialRotateEntityEvent) => void;
     onSpatialRotateEnd?: (event: SpatialRotateEndEntityEvent) => void;
     onSpatialMagnify?: (event: SpatialMagnifyEntityEvent) => void;
@@ -211,45 +256,43 @@ declare const eventMap: {
     readonly onSpatialDragStart: "spatialdragstart";
     readonly onSpatialDrag: "spatialdrag";
     readonly onSpatialDragEnd: "spatialdragend";
-    readonly onSpatialRotateStart: "spatialrotatestart";
     readonly onSpatialRotate: "spatialrotate";
     readonly onSpatialRotateEnd: "spatialrotateend";
-    readonly onSpatialMagnifyStart: "spatialmagnifystart";
     readonly onSpatialMagnify: "spatialmagnify";
     readonly onSpatialMagnifyEnd: "spatialmagnifyend";
 };
 
-declare const Entity: React__default.ForwardRefExoticComponent<EntityProps & EntityEventHandler & {
+declare const Entity: React__default.ForwardRefExoticComponent<EntityProps & {
     children?: React__default.ReactNode;
 } & React__default.RefAttributes<EntityRefShape>>;
 
-declare const BoxEntity: React__default.ForwardRefExoticComponent<EntityProps & EntityEventHandler & {
+declare const BoxEntity: React__default.ForwardRefExoticComponent<EntityProps & {
     children?: React__default.ReactNode;
     materials?: string[];
 } & SpatialBoxGeometryOptions & React__default.RefAttributes<EntityRefShape>>;
 
-type Props$2 = {
+type UnlitMaterialProps = {
     children?: React__default.ReactNode;
     id: string;
 } & SpatialUnlitMaterialOptions;
-declare const UnlitMaterial: React__default.FC<Props$2>;
+declare const UnlitMaterial: React__default.FC<UnlitMaterialProps>;
 
-declare const SphereEntity: React__default.ForwardRefExoticComponent<EntityProps & EntityEventHandler & {
+declare const SphereEntity: React__default.ForwardRefExoticComponent<EntityProps & {
     children?: React__default.ReactNode;
     materials?: string[];
 } & SpatialSphereGeometryOptions & React__default.RefAttributes<EntityRefShape>>;
 
-declare const ConeEntity: React__default.ForwardRefExoticComponent<EntityProps & EntityEventHandler & {
+declare const ConeEntity: React__default.ForwardRefExoticComponent<EntityProps & {
     children?: React__default.ReactNode;
     materials?: string[];
 } & SpatialConeGeometryOptions & React__default.RefAttributes<EntityRefShape>>;
 
-declare const CylinderEntity: React__default.ForwardRefExoticComponent<EntityProps & EntityEventHandler & {
+declare const CylinderEntity: React__default.ForwardRefExoticComponent<EntityProps & {
     children?: React__default.ReactNode;
     materials?: string[];
 } & SpatialCylinderGeometryOptions & React__default.RefAttributes<EntityRefShape>>;
 
-declare const PlaneEntity: React__default.ForwardRefExoticComponent<EntityProps & EntityEventHandler & {
+declare const PlaneEntity: React__default.ForwardRefExoticComponent<EntityProps & {
     children?: React__default.ReactNode;
     materials?: string[];
 } & SpatialPlaneGeometryOptions & React__default.RefAttributes<EntityRefShape>>;
@@ -270,12 +313,34 @@ declare const ModelAsset: React__default.FC<Props>;
 
 declare const ModelEntity: React__default.ForwardRefExoticComponent<EntityProps & {
     model: string;
-} & EntityEventHandler & {
+} & {
     children?: React__default.ReactNode;
 } & React__default.RefAttributes<EntityRefShape>>;
 
+type RealityProps = React__default.ComponentPropsWithRef<'div'> & EntityEventHandler;
 declare const Reality: React__default.ForwardRefExoticComponent<Omit<RealityProps, "ref"> & React__default.RefAttributes<HTMLElement>>;
 
+type AttachmentAssetProps = {
+    name: string;
+    children?: React__default.ReactNode;
+};
+declare const AttachmentAsset: React__default.FC<AttachmentAssetProps>;
+
+type AttachmentEntityProps = {
+    attachment: string;
+    position?: [number, number, number];
+    size: {
+        width: number;
+        height: number;
+    };
+};
+declare const AttachmentEntity: React__default.FC<AttachmentEntityProps>;
+
+type MaterialProps = {
+    type: 'unlit';
+} & UnlitMaterialProps;
+declare const Material: React__default.FC<MaterialProps>;
+
 type ModelProps = SpatializedStatic3DContainerProps & {
     'enable-xr'?: boolean;
 };
@@ -293,6 +358,7 @@ declare const Model: React$1.ForwardRefExoticComponent<Omit<{
     src?: string;
     onLoad?: (event: ModelLoadEvent) => void;
     onError?: (event: ModelLoadEvent) => void;
+    spatialEventOptions?: SpatialEventOptions;
 } & {
     'enable-xr'?: boolean;
 } & React$1.RefAttributes<SpatializedStatic3DElementRef>, "ref"> & React$1.RefAttributes<any>>;
@@ -302,6 +368,26 @@ declare const SSRProvider: ({ isSSR: initialIsSSR, children, }: {
     children: React__default.ReactNode;
 }) => react_jsx_runtime.JSX.Element;
 
+declare function useMetrics(): {
+    pointToPhysical: typeof PhysicalMetrics.pointToPhysical;
+    physicalToPoint: typeof PhysicalMetrics.physicalToPoint;
+};
+
+declare function createElement(...args: Parameters<typeof createElement$1>): React$1.DetailedReactHTMLElement<React$1.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>;
+
+/**
+ * const e2e = await convertCoordinate(position, { from: elementOrEntity, to: elementOrEntity })
+const e2w = await convertCoordinate(position, { from: elementOrEntity, to: window })
+const w2e = await convertCoordinate(position, { from: window, to: elementOrEntity })
+ *
+ */
+
+type CoordinateConvertible = Window | SpatializedElementRef<any> | EntityRef | ModelRef;
+declare function convertCoordinate(position: Vec3, { from, to }: {
+    from: CoordinateConvertible;
+    to: CoordinateConvertible;
+}): Promise<Vec3>;
+
 declare const version: string;
 
-export { BoxEntity, ConeEntity, CylinderEntity, Entity, type EntityEventHandler, type EntityProps, EntityRef, Model, ModelAsset, ModelEntity, type ModelLoadEvent, type ModelProps, type ModelRef, type ModelSpatialDragEndEvent, type ModelSpatialDragEvent, type ModelSpatialDragStartEvent, type ModelSpatialMagnifyEndEvent, type ModelSpatialMagnifyEvent, type ModelSpatialRotateEndEvent, type ModelSpatialRotateEvent, type ModelSpatialTapEvent, PlaneEntity, Reality, SSRProvider, SceneGraph, type SpatialDragEndEntityEvent, type SpatialDragEndEvent, type SpatialDragEntityEvent, type SpatialDragEvent, type SpatialDragStartEntityEvent, type SpatialDragStartEvent, type SpatialMagnifyEndEntityEvent, type SpatialMagnifyEndEvent, type SpatialMagnifyEntityEvent, type SpatialMagnifyEvent, SpatialMonitor, type SpatialRotateEndEntityEvent, type SpatialRotateEndEvent, type SpatialRotateEntityEvent, type SpatialRotateEvent, type SpatialTapEntityEvent, type SpatialTapEvent, Spatialized2DElementContainer, type Spatialized2DElementContainerProps, SpatializedContainer, type SpatializedElementRef, type SpatializedStatic3DContainerProps, SpatializedStatic3DElementContainer, type SpatializedStatic3DElementRef, SphereEntity, UnlitMaterial, enableDebugTool, eventMap, initPolyfill, initScene, toLocalSpace, toSceneSpatial, version, withSpatialMonitor, withSpatialized2DElementContainer };
+export { AttachmentAsset, AttachmentEntity, BoxEntity as Box, BoxEntity, ConeEntity as Cone, ConeEntity, CylinderEntity as Cylinder, CylinderEntity, Entity, type EntityEventHandler, type EntityProps, EntityRef, Material, type MaterialProps, Model, ModelAsset, ModelEntity, type ModelLoadEvent, type ModelProps, type ModelRef, type ModelSpatialDragEndEvent, type ModelSpatialDragEvent, type ModelSpatialDragStartEvent, type ModelSpatialMagnifyEndEvent, type ModelSpatialMagnifyEvent, type ModelSpatialRotateEndEvent, type ModelSpatialRotateEvent, type ModelSpatialTapEvent, PlaneEntity as Plane, PlaneEntity, Reality, type RealityProps, SSRProvider, SceneGraph, type SpatialDragEndEntityEvent, type SpatialDragEndEvent, type SpatialDragEntityEvent, type SpatialDragEvent, type SpatialDragStartEntityEvent, type SpatialDragStartEvent, type SpatialEventOptions, type SpatialMagnifyEndEntityEvent, type SpatialMagnifyEndEvent, type SpatialMagnifyEntityEvent, type SpatialMagnifyEvent, SpatialMonitor, type SpatialRotateEndEntityEvent, type SpatialRotateEndEvent, type SpatialRotateEntityEvent, type SpatialRotateEvent, type SpatialTapEntityEvent, type SpatialTapEvent, Spatialized2DElementContainer, type Spatialized2DElementContainerProps, SpatializedContainer, type SpatializedElementRef, type SpatializedStatic3DContainerProps, SpatializedStatic3DElementContainer, type SpatializedStatic3DElementRef, SphereEntity as Sphere, SphereEntity, UnlitMaterial, type UnlitMaterialProps, SceneGraph as World, convertCoordinate, createElement, enableDebugTool, eventMap, initPolyfill, initScene, useMetrics, version, withSpatialMonitor, withSpatialized2DElementContainer };