lunchboxjs 0.2.1001-beta.0 → 0.2.1001-beta.301

package/src/core/update.ts

@@ -1,18 +1,7 @@
-// import {
-//ensureRenderer,
-// ensuredScene,
-// ensuredCamera,
-// } from '.'
-import { Lunch } from '..'
-import { inject, toRaw, watch, WatchStopHandle } from 'vue'
+import type { Lunch } from '..'
+import { inject, toRaw, watch } from 'vue'
 import * as Keys from '../keys'
 
-// let frameID: number
-// let watchStopHandle: WatchStopHandle
-
-// export const beforeRender = [] as Lunch.UpdateCallback[]
-// export const afterRender = [] as Lunch.UpdateCallback[]
-
 const requestUpdate = (opts: Lunch.UpdateCallbackProperties) => {
     if (typeof opts.app.config.globalProperties.lunchbox.frameId === 'number') {
         cancelAnimationFrame(opts.app.config.globalProperties.lunchbox.frameId)
@@ -49,7 +38,7 @@ export const update: Lunch.UpdateCallback = (opts) => {
     }
 
     // prep options
-    const { app, renderer, scene, camera } = opts
+    const { app, renderer, scene } = opts
 
     // BEFORE RENDER
     app.config.globalProperties.lunchbox.beforeRender.forEach((cb) => {
@@ -57,14 +46,14 @@ export const update: Lunch.UpdateCallback = (opts) => {
     })
 
     // RENDER
-    if (renderer && scene && camera) {
+    if (renderer && scene && opts.app.config.globalProperties.lunchbox.camera) {
         if (app.customRender) {
             app.customRender(opts)
         } else {
             renderer.render(
                 toRaw(scene),
-                // opts.app.config.globalProperties.lunchbox.camera!
-                toRaw(camera)
+                opts.app.config.globalProperties.lunchbox.camera
+                // toRaw(camera)
             )
         }
     }
@@ -77,7 +66,7 @@ export const update: Lunch.UpdateCallback = (opts) => {
 
 // before render
 // ====================
-// TODO: document
+/** Obtain callback methods for `onBeforeRender` and `offBeforeRender`. Usually used internally by Lunchbox. */
 export const useBeforeRender = () => {
     return {
         onBeforeRender: inject<typeof onBeforeRender>(Keys.onBeforeRenderKey),
@@ -87,19 +76,25 @@ export const useBeforeRender = () => {
     }
 }
 
-// TODO: document
+/** Run a function before every render.
+ *
+ * Note that if `updateSource` is set in the Lunchbox wrapper component, this will **only** run
+ * before a render triggered by that `updateSource`. Normally, the function should run every frame.
+ */
 export const onBeforeRender = (cb: Lunch.UpdateCallback, index = Infinity) => {
     useBeforeRender().onBeforeRender?.(cb, index)
 }
 
-// TODO: document
+/** Remove a function from the `beforeRender` callback list. Useful for tearing down functions added
+ * by `onBeforeRender`.
+ */
 export const offBeforeRender = (cb: Lunch.UpdateCallback | number) => {
     useBeforeRender().offBeforeRender?.(cb)
 }
 
 // after render
 // ====================
-// TODO: document
+/** Obtain callback methods for `onAfterRender` and `offAfterRender`. Usually used internally by Lunchbox. */
 export const useAfterRender = () => {
     return {
         onAfterRender: inject<typeof onAfterRender>(Keys.onBeforeRenderKey),
@@ -107,34 +102,25 @@ export const useAfterRender = () => {
     }
 }
 
-// TODO: document
+/** Run a function after every render.
+ *
+ * Note that if `updateSource` is set in the Lunchbox wrapper component, this will **only** run
+ * after a render triggered by that `updateSource`. Normally, the function should run every frame.
+ */
 export const onAfterRender = (cb: Lunch.UpdateCallback, index = Infinity) => {
     useBeforeRender().onBeforeRender?.(cb, index)
 }
 
-// TODO: document
+/** Remove a function from the `afterRender` callback list. Useful for tearing down functions added
+ * by `onAfterRender`.
+ */
 export const offAfterRender = (cb: Lunch.UpdateCallback | number) => {
     useBeforeRender().offBeforeRender?.(cb)
 }
 
-// export const onAfterRender = (cb: Lunch.UpdateCallback, index = Infinity) => {
-//     if (index === Infinity) {
-//         afterRender.push(cb)
-//     } else {
-//         afterRender.splice(index, 0, cb)
-//     }
-// }
-
-// export const offAfterRender = (cb: Lunch.UpdateCallback | number) => {
-//     if (isFinite(cb as number)) {
-//         afterRender.splice(cb as number, 1)
-//     } else {
-//         const idx = afterRender.findIndex((v) => v == cb)
-//         afterRender.splice(idx, 1)
-//     }
-// }
-
-// TODO: document
+/** Obtain a function used to cancel the current update frame. Use `cancelUpdate` if you wish
+ * to immediately invoke the cancellation function. Usually used internally by Lunchbox.
+ */
 export const useCancelUpdate = () => {
     const frameId = inject<number>(Keys.frameIdKey)
     return () => {
@@ -142,12 +128,14 @@ export const useCancelUpdate = () => {
     }
 }
 
-// TODO: document
+/** Cancel the current update frame. Usually used internally by Lunchbox. */
 export const cancelUpdate = () => {
     useCancelUpdate()?.()
 }
 
-// TODO: document
+/** Obtain a function used to cancel an update source. Use `cancelUpdateSource` if you wish to
+ * immediately invoke the cancellation function. Usually used internally by Lunchbox.
+ */
 export const useCancelUpdateSource = () => {
     const cancel = inject<
         Lunch.App['config']['globalProperties']['watchStopHandle']
@@ -155,7 +143,7 @@ export const useCancelUpdateSource = () => {
     return () => cancel?.()
 }
 
-// TODO: document
+/** Cancel an update source. Usually used internally by Lunchbox. */
 export const cancelUpdateSource = () => {
     useCancelUpdateSource()?.()
 }

package/src/core/updateObjectProp.ts

@@ -1,34 +1,25 @@
 import { isEventKey, isLunchboxStandardNode } from '../utils'
 import { addEventListener } from './interaction'
 import { get, isNumber, set } from 'lodash'
-import { Lunch } from '..'
-
-/** Update the given node so all of its props are current. */
-export function updateAllObjectProps({ node }: { node: Lunch.Node }) {
-    // set props
-    const props = node.props || {}
-    let output = node
-    Object.keys(props).forEach((key) => {
-        output = updateObjectProp({ node, key, value: props[key] })
-    })
-
-    return output
-}
+import type { Lunch } from '..'
+import type { Ref } from 'vue'
 
 /** Update a single prop on a given node. */
 export function updateObjectProp({
     node,
     key,
+    interactables,
     value,
 }: {
     node: Lunch.Node
     key: string
+    interactables: Ref<Lunch.Node[]>
     value: any
 }) {
     // handle and return early if prop is an event
     // (event list from react-three-fiber)
     if (isEventKey(key)) {
-        return addEventListener({ node, key, value })
+        return addEventListener({ node, key, interactables, value })
     }
 
     // update THREE property
@@ -67,6 +58,7 @@ export function updateObjectProp({
     }
 
     // change property
+    // first, save as array in case we need to spread it
     if (liveProperty && isNumber(value) && liveProperty.setScalar) {
         // if value is a number and the property has a `setScalar` method, use that
         liveProperty.setScalar(value)
@@ -75,8 +67,21 @@ export function updateObjectProp({
         const nextValueAsArray = Array.isArray(value) ? value : [value]
         ;(target as any)[finalKey].set(...nextValueAsArray)
     } else if (typeof liveProperty === 'function') {
-        // if property is a function, let's try calling it
-        liveProperty.bind(node.instance)(...value)
+        // some function properties are set rather than called, so let's handle them
+        if (
+            finalKey.toLowerCase() === 'onbeforerender' ||
+            finalKey.toLowerCase() === 'onafterrender'
+        ) {
+            ;(target as any)[finalKey] = value
+        } else {
+            if (!Array.isArray(value)) {
+                throw new Error(
+                    'Arguments on a declarative method must be wrapped in an array.\nWorks:\n<example :methodCall="[256]" />\nDoesn\'t work:\n<example :methodCall="256" />'
+                )
+            }
+            // if property is a function, let's try calling it
+            liveProperty.bind(node.instance)(...value)
+        }
 
         // pass the result to the parent
         // const parent = node.parentNode

package/src/index.ts

@@ -2,22 +2,17 @@ import {
     computed,
     createRenderer,
     Component,
+    ComputedRef,
     inject,
     watch,
     reactive,
+    Ref,
 } from 'vue'
-import { nodeOps } from './nodeOps'
-import {
-    ensuredCamera,
-    ensureRenderer,
-    ensuredScene,
-    extend,
-    MiniDom,
-} from './core'
+import { createNodeOps } from './nodeOps'
+import { extend, MiniDom } from './core'
 import { components } from './components'
 import { Lunch } from './types'
 
-// export { lunchboxRootNode as lunchboxTree } from './core'
 export * from './core'
 export * from './types'
 
@@ -27,28 +22,58 @@ export * from './keys'
 // Utilities
 export * from './utils/find'
 
-/** The current camera. Often easier to use `useCamera` instead of this. */
-// TODO: update docs
-export const camera = ensuredCamera
-// TODO: update docs
-export const useCamera = () => ensuredCamera()
+/** The current camera as a computed value. */
+export const useCamera = <T extends THREE.Camera = THREE.Camera>() =>
+    inject<ComputedRef<T>>(Keys.appCameraKey)!
+/** Run a function using the current camera when it's present. */
+export const onCameraReady = <T extends THREE.Camera = THREE.Camera>(
+    cb: (camera?: T) => void
+) => {
+    const stopWatch = watch(
+        useCamera<T>(),
+        (newVal) => {
+            if (newVal) {
+                cb(newVal)
+                stopWatch()
+            }
+        },
+        { immediate: true }
+    )
+}
 
-/** The current renderer as a computed value. Often easier to use `useRenderer` instead of this. */
-export const renderer = ensureRenderer
+/** The current renderer as a computed value. */
+export const useRenderer = <T extends THREE.Renderer = THREE.WebGLRenderer>() =>
+    inject<ComputedRef<T>>(Keys.appRenderersKey)!
 /** Run a function using the current renderer when it's present. */
-export const useRenderer = () => ensureRenderer()!
+export const onRendererReady = <T extends THREE.Renderer = THREE.Renderer>(
+    cb: (renderer?: T) => void
+) => {
+    const stopWatch = watch(
+        useRenderer<T>(),
+        (newVal) => {
+            if (newVal) {
+                cb(newVal)
+                stopWatch()
+            }
+        },
+        { immediate: true }
+    )
+}
 
-/** The current scene. Often easier to use `useScene` instead of this. */
-// TODO: update docs
-export const scene = ensuredScene
+/** The current scene as a computed value. */
+export const useScene = <T extends THREE.Scene = THREE.Scene>() =>
+    inject<ComputedRef<T>>(Keys.appSceneKey)!
 /** Run a function using the current scene when it's present. */
-// TODO: update docs
-export function useScene(callback: (newScene: THREE.Scene) => void) {
-    return watch(
-        scene,
+export const onSceneReady = <T extends THREE.Scene = THREE.Scene>(
+    cb: (scene?: T) => void
+) => {
+    const stopWatch = watch(
+        useScene<T>(),
         (newVal) => {
-            if (!newVal) return
-            callback(newVal.value)
+            if (newVal) {
+                cb(newVal)
+                stopWatch()
+            }
         },
         { immediate: true }
     )
@@ -116,18 +141,15 @@ export const updateGlobals = (newValue: Partial<Lunch.AppGlobals>) => {
     useUpdateGlobals()?.(newValue)
 }
 
-// TODO: document
-export const useRootNode = () =>
-    inject<MiniDom.RendererRootNode>(Keys.appRootNodeKey)
-
-// TODO: document
+/** Use the current Lunchbox app. Usually used internally by Lunchbox. */
 export const useApp = () => inject<Lunch.App>(Keys.appKey)
 
-// TODO: document
+/** Obtain a list of the start callback functions. Usually used internally by Lunchbox. */
 export const useStartCallbacks = () =>
-    inject<Lunch.UpdateCallback[]>(Keys.startCallbackKey) //[] as Lunch.UpdateCallback[]
+    inject<Lunch.UpdateCallback[]>(Keys.startCallbackKey)
 
-// TODO: document
+/** Run a given callback once when the Lunchbox app starts. Include an index to
+ * splice the callback at that index in the callback queue. */
 export const onStart = (cb: Lunch.UpdateCallback, index = Infinity) => {
     const callbacks = useStartCallbacks()
     if (index === Infinity) {
@@ -137,11 +159,20 @@ export const onStart = (cb: Lunch.UpdateCallback, index = Infinity) => {
     }
 }
 
+/** Obtain a list of interactable objects (registered via onClick, onHover, etc events). Usually used internally by Lunchbox. */
+export const useLunchboxInteractables = () =>
+    inject<Ref<Lunch.Node[]>>(Keys.lunchboxInteractables)
+
 // CREATE APP
 // ====================
 export const createApp = (root: Component) => {
+    const { nodeOps, interactables } = createNodeOps()
     const app = createRenderer(nodeOps).createApp(root) as Lunch.App
 
+    // provide Lunchbox interaction handlers flag (modified when user references events via
+    // @click, etc)
+    app.provide(Keys.lunchboxInteractables, interactables)
+
     // register all components
     // ====================
     Object.keys(components).forEach((key) => {

package/src/keys.ts

@@ -20,5 +20,6 @@ export const appKey = Symbol()
 export const appRenderersKey = Symbol()
 export const appSceneKey = Symbol()
 export const appCameraKey = Symbol()
+export const lunchboxInteractables = Symbol()
 
 export const startCallbackKey = Symbol()

package/src/nodeOps/index.ts

@@ -1,70 +1,83 @@
-import { RendererOptions } from 'vue'
+import { RendererOptions, ref } from 'vue'
 import { createElement } from './createElement'
 import { insert } from './insert'
 import { remove } from './remove'
 import { isLunchboxDomComponent, isLunchboxRootNode } from '../utils'
-import {
-    createCommentNode,
-    createTextNode,
-    MiniDom,
-    updateObjectProp,
-} from '../core'
-import { Lunch } from '..'
+import { createCommentNode, createTextNode, updateObjectProp } from '../core'
+import type { MiniDom } from '../core'
+import type { Lunch } from '..'
 
 /*
     Elements are `create`d from the outside in, then `insert`ed from the inside out.
 */
 
-export const nodeOps: RendererOptions<
-    MiniDom.RendererBaseNode,
-    MiniDom.RendererBaseNode
-> = {
-    createElement,
-    createText(text) {
-        return createTextNode({ text })
-    },
-    createComment(text) {
-        return createCommentNode({ text })
-    },
-    insert,
-    nextSibling(node) {
-        const result = node.nextSibling
-        // console.log('found', result)
-        if (!result) return null
-        return result as MiniDom.RendererBaseNode
-    },
-    parentNode(node) {
-        const result = node.parentNode
-        if (!result) return null
-        return result as MiniDom.RendererBaseNode
-    },
-    patchProp(node, key, prevValue, nextValue) {
-        if (isLunchboxDomComponent(node)) {
-            // handle DOM node
-            if (key === 'style') {
-                // special handling for style
-                Object.keys(nextValue).forEach((k) => {
-                    ;(node.domElement.style as any)[k] = nextValue[k]
-                })
-            } else {
-                node.domElement.setAttribute(key, nextValue)
+export const createNodeOps = () => {
+    // APP-LEVEL GLOBALS
+    // ====================
+    // These need to exist at the app level in a place where the node ops can access them.
+    // It'd be better to set these via `app.provide` at app creation, but the node ops need access
+    // to these values before the app is instantiated, so this is the next-best place for them to exist.
+    const interactables = ref([] as Lunch.Node[])
+
+    // NODE OPS
+    // ====================
+    const nodeOps: RendererOptions<
+        MiniDom.RendererBaseNode,
+        MiniDom.RendererBaseNode
+    > = {
+        createElement,
+        createText(text) {
+            return createTextNode({ text })
+        },
+        createComment(text) {
+            return createCommentNode({ text })
+        },
+        insert,
+        nextSibling(node) {
+            const result = node.nextSibling
+            if (!result) return null
+            return result as MiniDom.RendererBaseNode
+        },
+        parentNode(node) {
+            const result = node.parentNode
+            if (!result) return null
+            return result as MiniDom.RendererBaseNode
+        },
+        patchProp(node, key, prevValue, nextValue) {
+            if (isLunchboxDomComponent(node)) {
+                // handle DOM node
+                if (key === 'style') {
+                    // special handling for style
+                    Object.keys(nextValue).forEach((k) => {
+                        ;(node.domElement.style as any)[k] = nextValue[k]
+                    })
+                } else {
+                    node.domElement.setAttribute(key, nextValue)
+                }
+                return
+            }
+
+            // ignore if root node, or Lunchbox internal prop
+            if (isLunchboxRootNode(node) || key.startsWith('$')) {
+                return
             }
-            return
-        }
 
-        // ignore if root node, or Lunchbox internal prop
-        if (isLunchboxRootNode(node) || key.startsWith('$')) {
-            return
-        }
+            // otherwise, update prop
+            updateObjectProp({
+                node: node as Lunch.Node,
+                key,
+                interactables,
+                value: nextValue,
+            })
+        },
+        remove,
+        setElementText() {
+            // noop
+        },
+        setText() {
+            // noop
+        },
+    }
 
-        // otherwise, update prop
-        updateObjectProp({ node: node as Lunch.Node, key, value: nextValue })
-    },
-    remove,
-    setElementText() {
-        // noop
-    },
-    setText() {
-        // noop
-    },
+    return { nodeOps, interactables }
 }

package/src/types.ts

@@ -36,10 +36,6 @@ export declare namespace Lunch {
         update: UpdateCallback
     }
 
-    // type AppGlobals = {
-    //     /** Device pixel resolution */
-    //     dpr: number
-    // }
     type AppGlobals = App['config']['globalProperties']['lunchbox']
 
     type AppGlobalsUpdate = (newValue: Partial<AppGlobals>) => void
@@ -159,10 +155,6 @@ export declare namespace Lunch {
         renderer?: THREE.Renderer | null
         camera?: THREE.Camera | null
         updateSource?: WatchSource | null
-
-        // sceneNode: Node<THREE.Scene> | null
-        // rendererNode: Node<THREE.Renderer> | null
-        // cameraNode: Node<THREE.Camera> | null
     }
 
     /** Universally unique identifier. */

package/src/utils/index.ts

@@ -43,3 +43,13 @@ export const isLunchboxStandardNode = (
 export const isLunchboxRootNode = (node: any): node is Lunch.RootMeta => {
     return node.isLunchboxRootNode
 }
+
+export const waitFor = async (get: () => any) => {
+    let output = get()
+    while (!output) {
+        await new Promise((resolve) => requestAnimationFrame(resolve))
+        output = get()
+        console.log(output)
+    }
+    return output
+}

package/src/components/catalogue.ts

@@ -1,3 +0,0 @@
-import { Lunch } from '..'
-
-export const catalogue: Lunch.Catalogue = {}

package/src/core/ensure.ts

@@ -1,16 +0,0 @@
-import { ComputedRef, inject } from 'vue'
-import * as Keys from '../keys'
-
-export const ensuredCamera = <T extends THREE.Camera = THREE.Camera>() =>
-    inject<ComputedRef<T>>(Keys.appCameraKey)!
-
-// ENSURE RENDERER
-// ====================
-export const ensureRenderer = <
-    T extends THREE.Renderer = THREE.WebGLRenderer
->() => inject<ComputedRef<T>>(Keys.appRenderersKey)
-
-// ENSURE SCENE
-// ====================
-export const ensuredScene = <T extends THREE.Scene = THREE.Scene>() =>
-    inject<ComputedRef<T>>(Keys.appSceneKey)