lunchboxjs 2.1.10 → 2.1.11

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "lunchboxjs",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "main": "./dist/lunchboxjs.umd.cjs",
   "module": "./dist/lunchboxjs.js",
@@ -9,12 +10,12 @@
     ".": {
       "import": "./dist/lunchboxjs.js",
       "require": "./dist/lunchboxjs.umd.cjs",
-      "types": "./dist/src/index.d.ts"
+      "types": "./src/types.d.ts"
     }
   },
-  "version": "2.1.10",
+  "version": "2.1.11",
   "type": "module",
-  "types": "./dist/src/index.d.ts",
+  "types": "./src/types.d.ts",
   "scripts": {
     "dev": "vite",
     "build": "tsc && vite build",
@@ -37,7 +38,6 @@
     "three": "^0.164.1",
     "typescript": "^5.2.2",
     "vite": "^5.2.0",
-    "vite-plugin-dts": "^3.9.1",
     "vitest": "^3.0.5"
   }
 }

package/src/auto-components.ts

@@ -0,0 +1,94 @@
+import * as THREE from 'three';
+
+/** All components that will automatically be registered when Lunchbox is initialized. */
+export const autoComponents: Partial<keyof typeof THREE>[] = [
+    // ORDER MATTERS HERE!
+    // Place the objects most likely to wrap other objects at the beginning of the list.
+
+    // Main wrappers
+    'WebGLRenderer',
+    'Scene',
+    'Group',
+
+    // Secondary wrappers (objects, meshes, etc)
+    'Object3D',
+    'Mesh',
+    'Sprite',
+
+    // Tertiary items (individual geometries, materials, etc)
+    // Geometries
+    'BoxGeometry',
+    'BufferGeometry',
+    'CircleGeometry',
+    'ConeGeometry',
+    'CylinderGeometry',
+    'DodecahedronGeometry',
+    'ExtrudeGeometry',
+    'IcosahedronGeometry',
+    'InstancedBufferGeometry',
+    'LatheGeometry',
+    'OctahedronGeometry',
+    'PlaneGeometry',
+    'PolyhedronGeometry',
+    'RingGeometry',
+    'ShapeGeometry',
+    'SphereGeometry',
+    'TetrahedronGeometry',
+    'TorusGeometry',
+    'TorusKnotGeometry',
+    'TubeGeometry',
+    'WireframeGeometry',
+    // Materials
+    'PointsMaterial',
+    'ShaderMaterial',
+    'ShadowMaterial',
+    'SpriteMaterial',
+    'MeshToonMaterial',
+    'MeshBasicMaterial',
+    'MeshDepthMaterial',
+    'MeshPhongMaterial',
+    'LineBasicMaterial',
+    'RawShaderMaterial',
+    'MeshMatcapMaterial',
+    'MeshNormalMaterial',
+    'LineDashedMaterial',
+    'MeshLambertMaterial',
+    'MeshStandardMaterial',
+    'MeshDistanceMaterial',
+    'MeshPhysicalMaterial',
+    // Lights
+    'Light',
+    'SpotLight',
+    'SpotLightHelper',
+    'PointLight',
+    'PointLightHelper',
+    'AmbientLight',
+    'RectAreaLight',
+    'HemisphereLight',
+    'HemisphereLightHelper',
+    'DirectionalLight',
+    'DirectionalLightHelper',
+    // Cameras
+    'CubeCamera',
+    'ArrayCamera',
+    'StereoCamera',
+    'PerspectiveCamera',
+    'OrthographicCamera',
+    // Textures
+    'Texture',
+    'CubeTexture',
+    'DataTexture',
+    'DepthTexture',
+    'VideoTexture',
+    'CanvasTexture',
+    'CompressedTexture',
+    // Misc
+    'CatmullRomCurve3',
+    'Points',
+    'Raycaster',
+    'CameraHelper',
+    'Color',
+
+    // Loaders
+    'TextureLoader',
+];

package/src/html-anchor.ts

@@ -0,0 +1,88 @@
+import { html, LitElement } from "lit";
+import { Lunchbox, ThreeLunchbox } from ".";
+import * as THREE from "three";
+import { closestPassShadow } from "./utils";
+
+export class HtmlAnchor extends LitElement {
+  private parentLunchbox: Lunchbox<THREE.Object3D> | null = null;
+  private frame = -1;
+  private scratchV3 = new THREE.Vector3();
+
+  /** Try attaching the update function to pass the parent's position to children. */
+  tryAttachUpdate() {
+    const instance = this.parentLunchbox?.instance;
+    if (!instance) return false;
+    if (!instance.isObject3D) throw new Error('html-anchor must be the child of an Object3D');
+
+    // const lunchboxParent = closestPassShadow(this, 'three-lunchbox') as ThreeLunchbox | null;
+    const lunchboxParent = closestPassShadow(this, (el) => {
+      return !!(el as ThreeLunchbox)?.three?.renderer;
+    }) as Pick<ThreeLunchbox, 'three'> | null;
+
+    if (!lunchboxParent) {
+      console.error('three-lunchbox parent required for html-anchor');
+      return false;
+    }
+    const camera = lunchboxParent.three.camera;
+    if (!camera) {
+      console.error('camera required for html-anchor');
+      return false;
+    }
+    const renderer = lunchboxParent.three.renderer;
+    if (!renderer?.domElement) {
+      console.error('renderer and DOM element required for html-anchor');
+      return false;
+    }
+
+    const update = () => {
+      this.frame = requestAnimationFrame(update);
+      instance.getWorldPosition(this.scratchV3);
+      this.scratchV3.project(camera);
+      this.scratchV3.multiplyScalar(0.5).addScalar(0.5);
+      this.scratchV3.y = 1 - this.scratchV3.y;
+      const rendererSize = this.scratchV3.clone().set(renderer.domElement.width, renderer.domElement.height, 1);
+      rendererSize.divideScalar(devicePixelRatio);
+      this.scratchV3.multiply(rendererSize);
+      Array.from(this.children).forEach(child => {
+        (child as unknown as HTMLElement).style.setProperty('--left', `${this.scratchV3.x}px`);
+        (child as unknown as HTMLElement).style.setProperty('--top', `${this.scratchV3.y}px`);
+      })
+    }
+    update();
+
+    return true;
+  }
+
+  // Setup - save local parent and try adding update
+  connectedCallback() {
+    super.connectedCallback();
+
+    const parent = this.parentNode as Lunchbox<THREE.Object3D>;
+    if (!parent) {
+      throw new Error('html-anchor requires a 3D parent');
+    }
+    this.parentLunchbox = parent;
+    const attached = this.tryAttachUpdate();
+    if (!attached) {
+      this.parentLunchbox.addEventListener('instanceadded', () => {
+        const attachedAfterInstanceCreated = this.tryAttachUpdate();
+        if (!attachedAfterInstanceCreated) throw new Error('error attaching html-anchor to Object3D')
+      }, { once: true });
+    }
+
+  }
+
+  // Teardown
+  disconnectedCallback(): void {
+    if (this.frame !== -1) cancelAnimationFrame(this.frame);
+  }
+
+
+  protected render(): unknown {
+    return html`<slot></slot>`
+  }
+
+  protected createRenderRoot() {
+    return this;
+  }
+}

package/src/index.ts

@@ -0,0 +1,138 @@
+import { autoComponents } from './auto-components';
+import { buildClass } from './three-base';
+import { ThreeLunchbox } from './three-lunchbox';
+import { IsClass } from './utils';
+import * as THREE from '../node_modules/@types/three';
+import { HtmlAnchor } from './html-anchor';
+
+export * from './three-lunchbox';
+export * from './html-anchor';
+export { ThreeBase } from './three-base';
+
+/** Every component in a Lunchbox scene is of the Lunchbox type - it contains its ThreeJS instance
+ * as a property called `instance`. 
+ * 
+ * 
+ * ## Basic example
+ * 
+ * HTML:
+ * 
+ * ```html
+ * <three-mesh></three-mesh>
+ * ```
+ * 
+ * TS:
+ * 
+ * ```ts
+ * const mesh = document.querySelector<Lunchbox<THREE.Mesh>>('three-mesh');
+ * mesh?.instance; // this is typed as a THREE.Mesh, so you can do things like move it up:
+ * mesh?.instance.position.set(0, 1, 0); // - or anything else you can do with a mesh
+ * ```
+ */
+export type Lunchbox<T = THREE.Object3D> = Element & LunchboxProperties<T>
+
+export type LunchboxProperties<T = THREE.Object3D> = {
+    instance: T;
+}
+
+/** Options for initializing Lunchbox. */
+interface LunchboxOptions {
+    /** Add THREE class names that should be registered first here. */
+    prependList?: string[];
+}
+
+/** Initialize Lunchbox. Required to register Lunchbox components. */
+export const initLunchbox = ({
+    prependList = [],
+}: LunchboxOptions = {}) => {
+    const toDefine = {
+        'three-lunchbox': ThreeLunchbox,
+        'html-anchor': HtmlAnchor,
+    }
+
+    Object.entries(toDefine).forEach(([k, v]) => {
+        if (!customElements.get(k)){
+            customElements.define(k, v);
+        }
+    });
+
+    // define components
+    [...prependList, ...autoComponents].forEach(className => {
+        const kebabCase = convertThreeClassToWebComponent(className);
+
+        // ignore if already defined
+        if (customElements.get(kebabCase)) {
+            return;
+        }
+
+        const result = buildClass(className as keyof typeof THREE);
+        if (result) {
+            customElements.define(kebabCase, result);
+        }
+    });
+};
+
+/** Create and register a custom Lunchbox component. For example:
+ * 
+ * ```ts
+ * import { CustomGeometry } from 'your-custom-geometry-source';
+ * import { extend } from 'lunchboxjs';
+ * 
+ * extend('custom-geometry', CustomGeometry);
+ * ```
+ * 
+ * Now in your HTML, you can do:
+ * 
+ * ```html
+ * <three-lunchbox>
+ *      <custom-geometry args="[0, 1, 2]"></custom-geometry>
+ * </three-lunchbox>
+ * ```
+ */
+export const extend = (name: string, classDefinition: IsClass, targetWindow = window) => {
+    if (targetWindow.customElements.get(name)) {
+        console.log(`${name} already registered as a custom element. Try a different name if registering is still required.`);
+        return;
+    }
+
+    const result = buildClass(classDefinition);
+    if (result) {
+        targetWindow.customElements.define(name, result);
+    } else {
+        throw new Error(`Could not extend ${name}. The second paramater must be a class.`);
+    }
+};
+
+// Utilities
+// ==================
+export const THREE_POINTER_MOVE_EVENT_NAME = 'threepointermove';
+export const THREE_MOUSE_MOVE_EVENT_NAME = 'threemousemove';
+export const THREE_CLICK_EVENT_NAME = 'threeclick';
+export const BEFORE_RENDER_EVENT_NAME = 'beforerender';
+export const AFTER_RENDER_EVENT_NAME = 'afterrender';
+export type ThreeIntersectEvent = {
+    intersect: THREE.Intersection<THREE.Object3D<THREE.Object3DEventMap>>;
+    element: Element | null;
+}
+export interface InstanceEvent<T = unknown> {
+    instance: T;
+}
+export type InstanceAddedEvent<T = unknown> = InstanceEvent<T> & {
+    parent: THREE.Scene | THREE.Object3D
+}
+export interface LoadedEvent<T = unknown> {
+    loaded: T;
+}
+
+// Components
+export { autoComponents };
+const convertThreeClassToWebComponent = (className: string) => {
+    // convert name to kebab-case; prepend `three-` if needed; `-g-l-` becomes `-gl-`
+    let kebabCase = className.split(/\.?(?=[A-Z])/).join('-').toLowerCase().replace(/-g-l-/, '-gl-');
+    if (!kebabCase.includes('-')) {
+        kebabCase = `three-${kebabCase}`;
+    }
+    return kebabCase;
+};
+/** The kebab-cased name of the ThreeJS web components automatically registered in Lunchbox. */
+export const webComponentNames = autoComponents.map(convertThreeClassToWebComponent);

package/src/parseAttributeValue.ts

@@ -0,0 +1,43 @@
+import { ThreeLunchbox } from "./three-lunchbox";
+import * as THREE from 'three';
+
+const valueShortcuts = {
+    '$scene': (element: HTMLElement) => {
+        // TODO: allow non-wrapper scene
+        const el = element.closest('three-lunchbox') as unknown as ThreeLunchbox | null;
+        return el?.three.scene;
+    },
+    '$camera': (element: HTMLElement) => {
+        // TODO: allow non-wrapper camera
+        const el = element.closest('three-lunchbox') as unknown as ThreeLunchbox | null;
+        return el?.three.camera;
+    },
+    '$renderer': (element: HTMLElement) => {
+        // TODO: allow non-wrapper renderer
+        const el = element.closest('three-lunchbox') as unknown as ThreeLunchbox | null;
+        return el?.three.renderer;
+    },
+    '$domElement': (element: HTMLElement) => {
+        // TODO: allow non-wrapper dom element
+        const el = element.closest('three-lunchbox') as unknown as ThreeLunchbox | null;
+        return el?.three.renderer?.domElement;
+    },
+};
+
+export const parseAttributeOrPropertyValue = (targetValue: unknown, element: HTMLElement) => {
+    // leave as-is if this isn't a string
+    if (typeof targetValue !== 'string') return targetValue;
+
+    // return `true` for blank values
+    if (targetValue === '') return true;
+
+    // look for Lunchbox-specific shortcuts
+    // TODO: allow extending these
+    const result = valueShortcuts[targetValue as keyof typeof valueShortcuts]?.(element);
+
+    // Color support
+    if (CSS.supports('color', targetValue)) return new THREE.Color(targetValue);
+
+    // default - return target value
+    return result ?? targetValue;
+};

package/src/setThreeProperty.ts

@@ -0,0 +1,50 @@
+import { get, isNumber, set } from "./utils";
+import * as THREE from 'three';
+
+export const setThreeProperty = <T extends object>(target: T, split: string[], parsedValue: unknown) => {
+    const property: {
+        setScalar?: (n: number) => unknown,
+        set?: (...args: unknown[]) => unknown,
+    } | undefined = get(target, split);
+
+    if (isNumber(parsedValue) && property?.setScalar) {
+        // Set scalar
+        property.setScalar(+parsedValue);
+    } else if (property?.set) {
+        if (typeof parsedValue === 'string') {
+            const asNumbers = parsedValue.split(',');
+            const isAllNumbers = asNumbers.every(n => !n.match(/^[^\d,]+$/));
+
+            // handle hash hex numbers
+            if (parsedValue.toLowerCase().trim().match(/^#[\dabcdef]{3,6}$/)?.length) {
+                if (parsedValue.length === 4) {
+                    const str = [parsedValue[1], parsedValue[1], parsedValue[2], parsedValue[2], parsedValue[3], parsedValue[3]].join('');
+                    property.set(+`0x${str}`);
+                } else {
+                    property.set(+`0x${parsedValue.slice(1)}`);
+                }
+            } else if (asNumbers?.length && isAllNumbers) {
+                // assume this is a string like `1,2,3`
+                // and try converting to an array of numbers
+                // (we get arrays as strings like this from Vue, for example)
+                property.set(...asNumbers.map(n => +n));
+            } else {
+                property.set(parsedValue);
+            }
+        }
+        else {
+            // Set as values in an array
+            const parsedValueAsArray = Array.isArray(parsedValue) ? parsedValue : [parsedValue];
+            property.set(...parsedValueAsArray);
+        }
+    } else {
+        // Manually set
+        set(target, split, parsedValue);
+    }
+
+    // handle common update functions
+    const targetAsMaterial = target as THREE.Material;
+    if (typeof targetAsMaterial.type === 'string' && targetAsMaterial.type?.toLowerCase().endsWith('material')) {
+        targetAsMaterial.needsUpdate = true;
+    }
+};