mathbox-react 0.0.9-dev-3 → 0.0.11-rc

package/src/components/Mathbox.tsx

@@ -3,12 +3,12 @@ import React, {
   useState,
   forwardRef,
   useImperativeHandle,
-  useMemo,
 } from "react"
 import { Color } from "three"
 import { mathBox, RootProps, MathboxSelection, MathBoxOptions } from "mathbox"
 import MathboxAPIContext from "./MathboxNodeContext"
 import { WithChildren } from "./types"
+import { useDeepCompareMemo } from "./util"
 
 type Props = WithChildren<
   {
@@ -22,7 +22,7 @@ const Mathbox = (
   ref: React.Ref<MathboxSelection<"root"> | null>
 ) => {
   const { container, children, options, ...rootProps } = props
-  const mathboxOptions = useMemo(() => options ?? {}, [options])
+  const mathboxOptions = useDeepCompareMemo(options ?? {}, {})
   const [selection, setSelection] = useState<MathboxSelection<"root"> | null>(
     null
   )
@@ -39,6 +39,7 @@ const Mathbox = (
      * TODO: Should Mathbox component allow setting these more easily?
      */
     mathbox.three.renderer.setClearColor(new Color(0xffffff), 1.0)
+    mathbox.three.camera.position.set(1, 1, 2)
     return () => {
       mathbox.select("*").remove()
       mathbox.three.destroy()

package/src/components/{Cartesian.spec.tsx → components.spec.tsx}

@@ -3,7 +3,7 @@ import { render, act } from "@testing-library/react"
 import { MathboxSelection } from "mathbox"
 import ContainedMathbox from "./ContainedMathbox"
 import Mathbox from "./Mathbox"
-import { Cartesian, Grid } from "./components"
+import { Cartesian, Grid, Voxel } from "./components"
 import { MathboxRef } from "./types"
 
 function assertNotNil<T>(value: T): asserts value is NonNullable<T> {
@@ -27,6 +27,24 @@ const assertSelectionsEqual = (s1: MathboxSelection, s2: MathboxSelection) => {
     })
 }
 
+describe("ContainedMathbox", () => {
+  it("makes a new mathbox instance only if the options have changed", () => {
+    const mbRef: MathboxRef<"root"> = { current: null }
+    const { rerender } = render(<ContainedMathbox options={{}} ref={mbRef} />)
+
+    const mb0 = mbRef.current
+    assertNotNil(mb0)
+    rerender(<ContainedMathbox options={{}} ref={mbRef} />)
+    const mb1 = mbRef.current
+    expect(mb1).toBe(mb0)
+    assertNotNil(mb1)
+    rerender(<ContainedMathbox options={{ plugins: ["core"] }} ref={mbRef} />)
+    const mb2 = mbRef.current
+    assertNotNil(mb2)
+    expect(mb2).not.toBe(mb1)
+  })
+})
+
 describe("Cartesian", () => {
   it("exposes Mathbox instance via ref", () => {
     const mbRef: MathboxRef<"root"> = { current: null }
@@ -116,6 +134,41 @@ describe("Cartesian", () => {
     expect(cartesian.get("visible")).toBe(false)
   })
 
+  it("updates liveProps on its mathbox instance when rerendered", async () => {
+    const mbRef: MathboxRef<"root"> = { current: null }
+    const { rerender } = render(
+      <ContainedMathbox ref={mbRef}>
+        <Cartesian>
+          <Grid
+            liveProps={{
+              width: (t) => 1 + t,
+            }}
+          />
+        </Cartesian>
+      </ContainedMathbox>
+    )
+    const grid = mbRef.current?.select<"grid">("grid")
+    assertNotNil(grid)
+
+    const w1 = grid.get("width")
+    await new Promise((resolve) => {
+      setTimeout(resolve, 500)
+    })
+    const w2 = grid.get("width")
+    expect(w1).toBe(1)
+    // Mathbox uses seconds
+    expect(w2 - w1).toBeGreaterThan(0.45)
+    expect(w2 - w1).toBeLessThanOrEqual(0.5)
+    rerender(
+      <ContainedMathbox ref={mbRef}>
+        <Cartesian>
+          <Grid width={10} />
+        </Cartesian>
+      </ContainedMathbox>
+    )
+    expect(grid.get("width")).toBe(10)
+  })
+
   it("re-renders inside new instance when root changes", () => {
     const mbRef: MathboxRef<"root"> = { current: null }
     const cartesianRef: MathboxRef<"cartesian"> = { current: null }
@@ -145,7 +198,7 @@ describe("Cartesian", () => {
      * When re-rendered, this will create a new mathBox since the options
      * object prop will have changed.
      */
-    const options2 = {}
+    const options2 = { plugins: ["core"] }
     expect(options1).not.toBe(options2)
 
     rerender(
@@ -163,7 +216,7 @@ describe("Cartesian", () => {
     assertNotNil(cartesian2)
     assertNotNil(grid2)
 
-    // It creates a new instance b/c the options prop has changed by reference
+    // The options have changed (via deep equal) so a new instance is created
     expect(mb1).not.toBe(mb2)
 
     expect(cartesian2).toHaveLength(1)
@@ -238,3 +291,21 @@ describe("Cartesian", () => {
     expect(mbRef.current.select("grid").length).toBe(0)
   })
 })
+
+describe("<Voxel />", () => {
+  it("throws a runtime error if it has children", () => {
+    const willThrow = () =>
+      render(
+        <ContainedMathbox>
+          <Cartesian>
+            {/* eslint-disable-next-line @typescript-eslint/ban-ts-comment  */}
+            {/* @ts-expect-error */}
+            <Voxel>
+              <Grid />
+            </Voxel>
+          </Cartesian>
+        </ContainedMathbox>
+      )
+    expect(willThrow).toThrow("Component <Voxel /> cannot have children.")
+  })
+})

package/src/components/components.tsx

@@ -9,33 +9,49 @@ import React, {
 import { Props, NodeType, MathboxSelection } from "mathbox"
 import MathboxAPIContext from "./MathboxNodeContext"
 import { WithChildren } from "./types"
-import { isRootDestroyed, isSelectionParent } from "./util"
-
+import {
+  isRootDestroyed,
+  isSelectionParent,
+  canNodeHaveChildren,
+  ParentNodeTypes,
+  capitalize,
+} from "./util"
+
+type LiveProps<P> = {
+  [K in keyof P]: (t: number, dt: number) => P[K]
+}
 type MathboxComponent<T extends NodeType> = React.ForwardRefExoticComponent<
-  WithChildren<Props[T]> & React.RefAttributes<MathboxSelection<T>>
+  (T extends ParentNodeTypes ? WithChildren<Props[T]> : Props[T]) &
+    React.RefAttributes<MathboxSelection<T>> & {
+      liveProps?: LiveProps<Props[T]>
+    }
 >
 
 const mathboxComponentFactory = <T extends NodeType>(
   type: T
 ): MathboxComponent<T> => {
+  const canHaveChildren = canNodeHaveChildren(type)
+  const componentName = capitalize(type)
   const Comp = (
-    props: WithChildren<Props[T]>,
+    props: WithChildren<Props[T]> & { liveProps?: LiveProps<Props[T]> },
     ref: React.Ref<MathboxSelection<T> | null>
   ) => {
     const [_ignored, forceUpdate] = useReducer((x) => x + 1, 0)
     const parent = useContext(MathboxAPIContext)
     const selection = useRef<MathboxSelection<T> | null>(null)
+    const prevLiveProps = useRef<LiveProps<Props[T]> | undefined>(undefined)
     useEffect(
       () => () => {
         if (selection.current) {
           selection.current.remove()
+          selection.current = null
         }
       },
       []
     )
     useImperativeHandle(ref, () => selection.current)
 
-    const { children, ...others } = props
+    const { children, liveProps, ...others } = props
     useEffect(() => {
       if (!parent) return
       if (isRootDestroyed(parent)) {
@@ -51,14 +67,37 @@ const mathboxComponentFactory = <T extends NodeType>(
       }
       if (!selection.current) {
         // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        selection.current = parent[type](others)
+        // @ts-expect-error
+        selection.current = parent[type](others, liveProps)
         forceUpdate()
       } else {
+        /**
+         * If liveProps have changed, remove all the old liveProps.
+         * (The same prop cannot be re-assigned live without being un-assigned
+         * first.)
+         *
+         * We could unbind just the ones that have changed, but simpler to
+         * unbind them all.
+         */
+        if (prevLiveProps.current && liveProps !== prevLiveProps.current) {
+          Object.keys(prevLiveProps.current).forEach((key) => {
+            // @ts-expect-error this is not in ts yet
+            selection.current.unbind(key)
+          })
+        }
+        if (liveProps && liveProps !== prevLiveProps.current) {
+          selection.current.bind(liveProps)
+        }
         selection.current.set(others)
       }
-    }, [parent, others])
-
+      prevLiveProps.current = liveProps
+    }, [parent, others, liveProps])
+    if (!canHaveChildren) {
+      if (props.children) {
+        throw new Error(`Component <${componentName} /> cannot have children.`)
+      }
+      return null
+    }
     return (
       <MathboxAPIContext.Provider value={selection.current}>
         {props.children}

package/src/components/util.ts

@@ -1,5 +1,7 @@
 /* eslint-disable no-underscore-dangle */
-import { MathboxSelection } from "mathbox"
+import isEqual from "lodash/isEqual"
+import { useRef, useMemo } from "react"
+import { MathboxSelection, NodeType } from "mathbox"
 
 type WithPrivateUp = MathboxSelection & { _up?: WithPrivateUp }
 
@@ -41,3 +43,64 @@ export const isSelectionParent = (
   const selectionParentNode = (selection as WithPrivateUp)._up?.[0]
   return selectionParentNode === parent[0]
 }
+
+const CAN_HAVE_CHILDREN = [
+  "view",
+  "cartesian",
+  "cartesian4",
+  "polar",
+  "spherical",
+  "stereographic",
+  "stereographic4",
+  "transform",
+  "transform4",
+  "vertex",
+  "fragment",
+  "layer",
+  "mask",
+  "group",
+  "inherit",
+  "root",
+  "unit",
+  "rtt",
+  "clock",
+  "now",
+  "move",
+  "present",
+  "reveal",
+  "slide",
+] as const
+
+export type ParentNodeTypes = typeof CAN_HAVE_CHILDREN[number]
+
+export const canNodeHaveChildren = (type: NodeType) =>
+  (CAN_HAVE_CHILDREN as readonly string[]).includes(type)
+
+export const capitalize = (s: string) => {
+  if (!s) return ""
+  return s[0].toLocaleUpperCase() + s.slice(1)
+}
+
+/**
+ * Returns the same reference to `value` as long as the the given values are
+ * deep equal.
+ *
+ * This is, in general, not a great idea. See
+ * https://github.com/facebook/react/issues/14476#issuecomment-471199055
+ *
+ * This should work OK for mathbox options because the objects in question are
+ * either shallow, or are deep equal at a fairly shallow level.
+ * E.g., OrbitControls may not be a shall object, but if it's not, it will at
+ * least be deep equal between renders.
+ *
+ * But should work OK for mathbox options.
+ */
+export const useDeepCompareMemo = <T>(value: T, initial: T): T => {
+  const oldValue = useRef<T>(initial)
+  const memoOptions = useMemo(() => {
+    if (isEqual(value, oldValue.current)) return oldValue.current
+    oldValue.current = value
+    return value
+  }, [value])
+  return memoOptions
+}

package/src/stories/Point.stories.tsx

@@ -29,7 +29,7 @@ export default {
 
 const Template: Story<React.ComponentProps<typeof Point>> = (args) => {
   const { points, ...otherArgs } = args
-  const [data, setData] = useState<MathboxSelection<"array">>()
+  const [data, setData] = useState<MathboxSelection<"array"> | null>(null)
   return (
     <Mathbox containerStyle={{ height: 450 }}>
       <Cartesian
@@ -66,3 +66,10 @@ const Template: Story<React.ComponentProps<typeof Point>> = (args) => {
 
 export const DefaultPoint = Template.bind({})
 DefaultPoint.args = {}
+
+export const LiveProps = Template.bind({})
+LiveProps.args = {
+  liveProps: {
+    size: (t: number) => 20 * (1 + 0.5 * Math.sin(t)),
+  },
+}

package/build/cjs/types/components/MathboxNodeContext.d.ts

@@ -1,4 +0,0 @@
-/// <reference types="react" />
-import { MathboxSelection } from "mathbox";
-declare const MathboxAPIContext: import("react").Context<MathboxSelection<keyof import("mathbox").Props> | null>;
-export default MathboxAPIContext;

package/build/cjs/types/components/util.d.ts

@@ -1,18 +0,0 @@
-import { MathboxSelection } from "mathbox";
-export declare const isRootDestroyed: (selection: MathboxSelection) => boolean;
-/**
- * Check that parent is actually the selection's parent.
- * The mathbox components occasionally render with a selection value whose
- * parent does not match the parent specified in MathboxContext.
- *
- * I believe this fundamentally this is happening because
- * - we store parent value in context...
- * - we update the context parent value using useEffect hooks..
- * - useEffect hooks are called children before parents.
- *
- * One wonders whether we really need to be using useEffect hooks for the
- * mathbox components, or if we can just put all the node creation/removal stuff
- * in a render function. Hooks seem nice for dependencies, but mathbox is pretty
- * smart about diffing out the actual changes.
- */
-export declare const isSelectionParent: (selection: MathboxSelection, parent: MathboxSelection) => boolean;

package/build/esm/types/components/MathboxNodeContext.d.ts

@@ -1,4 +0,0 @@
-/// <reference types="react" />
-import { MathboxSelection } from "mathbox";
-declare const MathboxAPIContext: import("react").Context<MathboxSelection<keyof import("mathbox").Props> | null>;
-export default MathboxAPIContext;

package/build/esm/types/components/util.d.ts

@@ -1,18 +0,0 @@
-import { MathboxSelection } from "mathbox";
-export declare const isRootDestroyed: (selection: MathboxSelection) => boolean;
-/**
- * Check that parent is actually the selection's parent.
- * The mathbox components occasionally render with a selection value whose
- * parent does not match the parent specified in MathboxContext.
- *
- * I believe this fundamentally this is happening because
- * - we store parent value in context...
- * - we update the context parent value using useEffect hooks..
- * - useEffect hooks are called children before parents.
- *
- * One wonders whether we really need to be using useEffect hooks for the
- * mathbox components, or if we can just put all the node creation/removal stuff
- * in a render function. Hooks seem nice for dependencies, but mathbox is pretty
- * smart about diffing out the actual changes.
- */
-export declare const isSelectionParent: (selection: MathboxSelection, parent: MathboxSelection) => boolean;

package/scratch.js

@@ -1,149 +0,0 @@
-const classDescriptions = {
-  axis: ["draw", "Draw an axis", {}, { end: "true", zBias: "-1" }],
-  face: ["draw", "Draw polygon faces"],
-  grid: ["draw", "Draw a 2D line grid", {}, { width: "1", zBias: "-2" }],
-  line: ["draw", "Draw lines"],
-  point: ["draw", "Draw points"],
-  strip: ["draw", "Draw triangle strips"],
-  surface: ["draw", "Draw surfaces", {}, { lineX: "false", lineY: "false" }],
-  ticks: ["draw", "Draw ticks"],
-  vector: ["draw", "Draw vectors"],
-
-  view: ["view", "Adjust view range"],
-  cartesian: ["view", "Apply cartesian view"],
-  cartesian4: ["view", "Apply 4D cartesian view"],
-  polar: ["view", "Apply polar view"],
-  spherical: ["view", "Apply spherical view"],
-  stereographic: ["view", "Apply stereographic projection"],
-  stereographic4: ["view", "Apply 4D stereographic projection"],
-
-  transform: ["transform", "Transform geometry in 3D"],
-  transform4: ["transform", "Transform geometry in 4D"],
-  vertex: ["transform", "Apply custom vertex shader pass"],
-  fragment: ["transform", "Apply custom fragment shader pass"],
-  layer: ["transform", "Independent 2D layer/overlay"],
-  mask: ["transform", "Apply custom mask pass"],
-
-  array: [
-    "data",
-    "1D array",
-    { expr: "function (emit, i, time, delta) { ... }" },
-  ],
-  interval: [
-    "data",
-    "1D sampled array",
-    { expr: "function (emit, x, i, time, delta) { ... }" },
-  ],
-  matrix: [
-    "data",
-    "2D matrix",
-    { expr: "function (emit, i, j, time, delta) { ... }" },
-  ],
-  area: [
-    "data",
-    "2D sampled matrix",
-    { expr: "function (emit, x, y, i, j, time, delta) { ... }" },
-  ],
-  voxel: [
-    "data",
-    "3D voxels",
-    { expr: "function (emit, i, j, k, time, delta) { ... }" },
-  ],
-  volume: [
-    "data",
-    "3D sampled voxels",
-    { expr: "function (emit, x, y, z, i, j, k, time, delta) { ... }" },
-  ],
-  scale: ["data", "Human-friendly divisions on an axis, subdivided as needed"],
-
-  html: ["overlay", "HTML element source"],
-  dom: ["overlay", "HTML DOM injector"],
-
-  text: [
-    "text",
-    "GL text source",
-    {},
-    { minFilter: '"linear"', magFilter: '"linear"' },
-  ],
-  format: [
-    "text",
-    "Text formatter",
-    { expr: "function (x, y, z, w, i, j, k, l, time, delta) { ... }" },
-    { minFilter: '"linear"', magFilter: '"linear"' },
-  ],
-  retext: ["text", "Text atlas resampler"],
-  label: ["text", "Draw GL labels"],
-
-  clamp: ["operator", "Clamp out-of-bounds samples to the nearest data point"],
-  grow: ["operator", "Scale data relative to reference data point"],
-  join: [
-    "operator",
-    "Join two array dimensions into one by concatenating rows/columns/stacks",
-  ],
-  lerp: ["operator", "Linear interpolation of data"],
-  memo: ["operator", "Memoize data to an array/texture"],
-  readback: [
-    "operator",
-    "Read data back to a binary JavaScript array",
-    { expr: "function (x, y, z, w, i, j, k, l) { ... }" },
-  ],
-  resample: ["operator", "Resample data to new dimensions with a shader"],
-  repeat: ["operator", "Repeat data in one or more dimensions"],
-  swizzle: ["operator", "Swizzle data values"],
-  spread: ["operator", "Spread data values according to array indices"],
-  split: [
-    "operator",
-    "Split one array dimension into two by splitting rows/columns/etc",
-  ],
-  slice: ["operator", "Select one or more rows/columns/stacks"],
-  subdivide: ["operator", "Subdivide data points evenly or with a bevel"],
-  transpose: ["operator", "Transpose array dimensions"],
-
-  group: ["base", "Group elements for visibility and activity"],
-  inherit: ["base", "Inherit and inject a trait from another element"],
-  root: ["base", "Tree root"],
-  unit: ["base", "Change unit sizing for drawing ops"],
-
-  shader: ["shader", "Custom shader snippet"],
-
-  camera: ["camera", "Camera instance or proxy"],
-
-  rtt: [
-    "rtt",
-    "Render objects to a texture",
-    {},
-    { minFilter: '"linear"', magFilter: '"linear"', type: '"unsignedByte"' },
-  ],
-  compose: [
-    "rtt",
-    "Full-screen render pass",
-    {},
-    { zWrite: "false", zTest: "false", color: '"white"' },
-  ],
-
-  clock: ["time", "Relative clock that starts from zero."],
-  now: ["time", "Absolute UNIX time in seconds since 01/01/1970"],
-
-  move: ["present", "Move elements in/out on transition"],
-  play: ["present", "Play a sequenced animation"],
-  present: ["present", "Present a tree of slides"],
-  reveal: ["present", "Reveal/hide elements on transition"],
-  slide: ["present", "Presentation slide"],
-  step: ["present", "Step through a sequenced animation"],
-}
-
-const capitalize = (s) => `${s[0].toUpperCase()}${s.slice(1)}`
-
-const makeDef = (name) => {
-  const [group] = classDescriptions[name]
-  const Name = capitalize(name)
-  const dest = `https://gitgud.io/unconed/mathbox/-/blob/master/docs/primitives.md#${group}${name}`
-  const def = `
-/**
- * Component wrapper for mathbox [\`${name}\`](${dest}).
- */
-export const ${Name} = mathboxComponentFactory('${name}');`
-  console.log(def)
-}
-
-Object.keys(classDescriptions).sort().forEach(makeDef)