@lukekaalim/act-backstage 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @lukekaalim/act-backstage
 
+## 3.0.0
+
+### Major Changes
+
+- 6658c01: Internal Refactor!
+- afd247e: Another major refactor! So everything is broken. Good luck!
+- b3f6c49: Added debug capabilities and protocol
+
+### Patch Changes
+
+- Updated dependencies [6658c01]
+- Updated dependencies [fdf1557]
+- Updated dependencies [ccb3900]
+- Updated dependencies [afd247e]
+- Updated dependencies [2984273]
+- Updated dependencies [b3f6c49]
+- Updated dependencies [c5e8775]
+  - @lukekaalim/act-recon@3.0.0
+  - @lukekaalim/act@4.0.0
+
+## 3.0.0-alpha.0
+
+### Major Changes
+
+- b3f6c49: Added debug capabilities and protocol
+
+### Patch Changes
+
+- Updated dependencies [b3f6c49]
+  - @lukekaalim/act-recon@3.0.0-alpha.0
+
 ## 2.0.0
 
 ### Major Changes

package/README.md

@@ -0,0 +1,19 @@
+# @lukekaalim/act-backstage
+
+Backstage is a collection of utilities for creating Act renderers
+fairly simply. Most renderers in Act are just composed
+of one or more "RenderSpace"'s, which are the systems
+that keep track of which HTML/ThreeJs/SVG nodes correspond
+to which commit.
+
+## API
+
+<TypeDoc project="@lukekaalim/act-backstage" name="NodeBuilder" />
+
+<TypeDoc project="@lukekaalim/act-backstage" name="RenderSpace2" />
+
+<TypeDoc project="@lukekaalim/act-backstage" name="setPropObject" />
+
+## Guide
+
+We're going to build a classic render function

package/builder.ts

@@ -0,0 +1,24 @@
+import { Element } from "@lukekaalim/act";
+
+/**
+ * This type describes an implementation
+ * that can be provided to a RenderSpace
+ * in order to produce a fully-featured renderer.
+ */
+export type NodeBuilder<TNode, TRoot = string | symbol> = {
+  roots: Set<TRoot>,
+
+  create: (element: Element, root: TRoot) => null | TNode,
+  destroy?: (el: TNode) => unknown, 
+
+  linkRoot?: (child: TNode) => unknown,
+  unlinkRoot?: (child: TNode) => unknown,
+  link?: (child: TNode, parent: TNode) => unknown,
+  unlink?: (child: TNode, parent: TNode) => unknown,
+
+  sort?: (el: TNode, children: readonly TNode[]) => unknown,
+  update?: (el: TNode, next: Element, prev: null | Element) => unknown,
+
+  suspend?: (el: TNode, parent: TNode) => void,
+  unsuspend?: (el: TNode, parent: TNode) => void,
+};

package/mod.ts

@@ -1,3 +1,3 @@
-export * from './space.ts';
 export * from './props.ts';
-export * from './render.ts';
+export * from './space2.ts';
+export * from './builder.ts';

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@lukekaalim/act-backstage",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "main": "mod.ts",
   "dependencies": {
-    "@lukekaalim/act": "^3.2.0",
-    "@lukekaalim/act-recon": "^2.0.0"
+    "@lukekaalim/act": "^4.0.0",
+    "@lukekaalim/act-recon": "^3.0.0"
   }
 }

package/props.ts

@@ -1,6 +1,6 @@
 /**
  * Generically attempt to apply props to a target either by assigning them,
- * or letting a specialied function handle it.
+ * or letting a specialized function handle it.
  * 
  * Iterate across props from as to present, setting removed props to "undefined"
  */
@@ -24,4 +24,4 @@ export const setPropObject = (
       }
     }
   }
-}
+}

package/space2.ts

@@ -0,0 +1,264 @@
+import { primitiveNodeTypes, specialNodeTypes, SuspendProps } from "@lukekaalim/act";
+import { Commit2, CommitID, CommitRef2, CommitTree2, Delta, ReconcilerEventBus } from "@lukekaalim/act-recon"
+import { NodeBuilder } from "./builder";
+
+type ParentSearchResult<TNode> = {
+  /**
+   * You might not have a parent - no
+   * commit means there are no Nodes above you - just Root.
+   */
+  commit: Commit2 | null,
+  /**
+   * Your parent might be a valid node,
+   * or it might be "null"
+   */
+  node: TNode | null,
+
+  attachable: boolean,
+}
+
+/**
+ * The RenderSpace class
+ */
+export class RenderSpace2<TNode, TRoot extends string | symbol> {
+  /** The CommitTree this render space is connected to */
+  tree: CommitTree2;
+
+  /** A reverse map to look up Commits given just the node they represent */
+  nodeByCommit: Map<CommitID, TNode> = new Map();
+  /** A reverse map to look up Commits given just the node they represent */
+  commitByNode: Map<TNode, Commit2> = new Map();
+
+  /** For a given CommitID, find it's closest "real" parent (a ancestor with a non-null TNode) */
+  parentByNode: Map<CommitID, Commit2> = new Map();
+
+  /**
+   * A set of all special Root element IDs in the tree.
+   * A Root element helps tell a renderer what kind of element
+   * to render, based on it's closest Root.
+   */
+  roots: Map<CommitID, Commit2> = new Map();
+  bus: ReconcilerEventBus;
+  builder: NodeBuilder<TNode, TRoot>;
+
+  constructor(tree: CommitTree2, builder: NodeBuilder<TNode, TRoot>) {
+    this.tree = tree;
+    this.bus = {
+      render: (delta) => {
+        this.create(delta);
+        this.update(delta);
+      },
+    }
+    this.builder = builder;
+  }
+
+  findChildren(id: CommitID, ignoreFirst = false, ignoreSuspended = true): TNode[] {
+    const node = this.nodeByCommit.get(id);
+    if (node && !ignoreFirst)
+      return [node];
+
+    const commit = this.tree.commits.get(id);
+    if (!commit)
+      return [];
+    if (commit.element.type === primitiveNodeTypes.null)
+      return [];
+    // suspended nodes don't count as children
+    if (ignoreSuspended && commit.isSuspended())
+      return [];
+
+    return commit.children.map(c => this.findChildren(c.id)).flat(1);
+  }
+
+  /**
+   * "find parent" can return 3 types of results:
+   *  - An ancestor has a node! we return that.
+   *  - An ancestor is a "null" node - we return the special form of "commit but no node"
+   *  - No ancestor has a node - you might be near the root
+   * @param ref 
+   * @returns 
+   */
+  findParent(ref: CommitRef2): ParentSearchResult<TNode> {
+    let ancestor: CommitRef2 | null = ref;
+    let attachable = true;
+
+    while (ancestor) {
+      if (ancestor.id !== ref.id) {
+        const commit = this.tree.commits.get(ancestor.id) || null;
+
+        // Early exit out of parent lookup if someone on the path is null;
+        if (commit && commit.element.type === primitiveNodeTypes.null)
+          return { commit, node: null, attachable: false };
+
+        // maybe a bad idea... we'll see
+        if (commit && commit.isSuspended())
+          attachable = false;
+
+        const node = this.nodeByCommit.get(ancestor.id);
+        // If you find an element with a node
+        if (node)
+          return { commit, node, attachable }
+      }
+      ancestor = ancestor.parent;
+    }
+
+    // this element has no "node" parents - it is probably a "root" commit
+    return { commit: null, node: null, attachable };
+  }
+
+  findRoot(ref: CommitRef2) {
+    let ancestor: CommitRef2 | null = ref;
+
+    while (ancestor) {
+      const root = this.roots.get(ancestor.id);
+      if (root)
+        return root;
+      ancestor = ancestor.parent;
+    }
+
+    return null;
+  }
+
+  newNodes: Set<[Commit2, TNode]> = new Set();
+  needsReorder: Set<CommitID> = new Set();
+
+  create(deltas: Delta) {
+    this.newNodes.clear();
+    this.needsReorder.clear();
+
+    for (const next of deltas.fresh.values()) {
+      if (next.element.type === specialNodeTypes.render) {
+        // add render boundary
+        this.roots.set(next.ref.id, next);
+        continue;
+      }
+      const root = this.findRoot(next.ref);
+      if (!root)
+        continue;
+
+      const rootType = root.element.props['type'] as TRoot;
+
+      // test to see if this element
+      // belongs to this 
+      if (this.builder.roots.has(rootType) ) {
+        // Try to create a <T> for every new commit
+        const node = this.builder.create(next.element, rootType);
+        // Not all commits have a corresponding node
+        if (node) {
+          this.newNodes.add([next, node]);
+          this.nodeByCommit.set(next.ref.id, node);
+          this.commitByNode.set(node, next);
+        }
+      }
+    }
+  }
+
+  update(deltas: Delta) {
+    const {
+      link,
+      unlink,
+      linkRoot,
+      sort,
+      update,
+      destroy,
+      unlinkRoot,
+      suspend = unlink,
+      unsuspend = link
+    } = this.builder;
+
+    if (link || sort) {
+      // Loop through newly created nodes
+      for (const [next, node] of this.newNodes) {
+        const result = this.findParent(next.ref);
+
+        if (next.element.type === specialNodeTypes.suspend)
+          console.log(`Creating suspense node`, result)
+
+        if (result.commit && result.node && result.attachable) {
+          this.needsReorder.add(result.commit.ref.id)
+
+          if (link)
+            link(node, result.node);
+        }
+
+        if (linkRoot && !result.commit && result.attachable)
+          linkRoot(node);
+      }
+    }
+
+    if (update) {
+      for (const { prev, next, moved } of deltas.changed.values()) {
+
+        // suspense code
+        if (next.element.type === specialNodeTypes.suspend) {
+          const result = this.findParent(next.ref);
+
+          const wasSuspended = !!prev.props.suspended;
+          const isSuspended = !!next.element.props.suspended;
+
+          const suspenseChanged = wasSuspended !== isSuspended;
+          if (suspenseChanged && result.commit && result.node) {
+            this.needsReorder.add(result.commit.ref.id);
+
+            const children = this.findChildren(next.ref.id, true, false);
+            for (const child of children) {
+              if (isSuspended && suspend) {
+                suspend(child, result.node);
+              }
+              
+              if (!isSuspended && unsuspend) {
+                unsuspend(child, result.node);
+              }
+            }
+          }
+          continue;
+        }
+
+        const node = this.nodeByCommit.get(next.ref.id);
+        if (!node)
+          continue;
+
+        update(node, next.element, prev);
+
+        if (moved) {
+          const result = this.findParent(next.ref);
+          
+          if (result.commit) {
+            this.needsReorder.add(result.commit.ref.id);
+          }
+        }
+      }
+      for (const next of deltas.fresh.values()) {
+        const node = this.nodeByCommit.get(next.ref.id);
+        if (node)
+          update(node, next.element, null);
+      }
+    }
+    for (const prev of deltas.removed.values()) {
+      const node = this.nodeByCommit.get(prev.ref.id);
+      if (node) {
+        this.nodeByCommit.delete(prev.ref.id);
+        const parent = this.findParent(prev.ref);
+        if (parent.commit && parent.node)
+          this.needsReorder.add(parent.commit.ref.id)
+
+        this.commitByNode.delete(node);
+        if (unlink && parent.node)
+          unlink(node, parent.node);
+        if (unlinkRoot && !parent.commit)
+          unlinkRoot(node)
+        if (destroy)
+          destroy(node);
+      }
+    }
+
+    if (sort) {
+      for (const id of this.needsReorder) {
+        const node = this.nodeByCommit.get(id);
+        if (node) {
+          const children = this.findChildren(id, true, true);
+          sort(node, children);
+        }
+      }
+    }
+  }
+}

package/render.ts

@@ -1,32 +0,0 @@
-import { CommitTree, createReconciler, Scheduler, WorkThread } from "@lukekaalim/act-recon";
-import { RenderSpace } from "./space";
-import * as act from '@lukekaalim/act';
-
-export type RenderFunction<T> = (node: act.Node, root: T) => { stop: () => void }
-
-export const createRenderFunction = <T>(
-  scheduler: Scheduler,
-  createSpace: (tree: CommitTree, root: T) => RenderSpace
-): RenderFunction<T> => {
-
-  const render: RenderFunction<T> = (node: act.Node, root: T) => {
-    const onThreadComplete = (thread: WorkThread) => {
-      space.create(thread.deltas).configure();
-    };
-
-    const reconciler = createReconciler(scheduler);
-    const threadCompleteSub = reconciler.on('on-thread-complete', onThreadComplete);
-
-    const space = createSpace(reconciler.tree, root);
-    
-    reconciler.mount(node);
-
-    return {
-      stop() {
-        threadCompleteSub.cancel();
-      },
-    }
-  };
-
-  return render;
-}

package/space.ts

@@ -1,222 +0,0 @@
-import * as act from '@lukekaalim/act';
-import * as recon from '@lukekaalim/act-recon';
-
-/**
- * A "RenderSpace" is a service that manages
- * a subtree of a particular type (T). Its broken
- * down into two phases, "create" & "configure".
- * 
- * This needs to be done in two phases, because
- * often configuring elements requires references to
- * children and parents, and if they haven't been
- * created yet (or if the order of their creation is
- * uncertain), then these functions cant act properly.
- * 
- * #### Create
- * The create phase is responsible for the assignment
- * of CommitIds to T.
- * 
- * #### Configure
- * This is where props are assigned, and children +
- * heirarchial elements can be setup.
- */
-export type RenderSpace = {
-  create(deltas: recon.DeltaSet): { configure: () => unknown },
-};
-
-export type SimpleRenderSpaceArgs<T, R extends string | Symbol> = {
-  rootTypes: Set<R>,
-
-  create: (element: act.Element, rootType: R) => null | T,
-  link?: (el: T, parent: null | T) => unknown,
-  unlink?: (el: T, parent: null | T) => unknown,
-
-  sort?: (el: T, children: readonly T[]) => unknown,
-  update?: (el: T, next: act.Element, prev: null | act.Element) => unknown,
-  destroy?: (el: T) => unknown, 
-};
-
-export type NodeRef<T> = {
-  id: recon.CommitID,
-  node: T,
-}
-
-/**
- * A "simple" render space is just a conventional
- * render space where we keep track of each commit
- * in a map - and take a "SimpleRenderSpaceArgs"
- * args object that tells us how we make, link,
- * sort, and update our nodes.
- * 
- * @param tree 
- * @param args 
- * @param nodeByCommit 
- * @returns 
- */
-export const createSimpleRenderSpace = <T, R extends string | Symbol>(
-  tree: recon.CommitTree,
-  args: SimpleRenderSpaceArgs<T, R>,
-  nodeByCommit: Map<recon.CommitID, T | null> = new Map(),
-): RenderSpace => {
-  const commitByNode = new Map<T, recon.CommitID>();
-
-  const rootIds = new Set<recon.CommitID>();
-
-  /**
-   * Find all the nodes that belong children (in commit order!)
-   * for a particular commit.
-   */
-  const findChildren = (id: recon.CommitID, ignoreFirst = false): readonly T[] => {
-    const node = nodeByCommit.get(id);
-    if (node && !ignoreFirst)
-      return [node];
-    const commit = tree.commits.get(id);
-    if (!commit)
-      return [];
-    if (commit.element.type === act.primitiveNodeTypes.null)
-      return [];
-    return commit.children.map(c => findChildren(c.id)).flat(1);
-  };
-  const findParent = (ref: recon.CommitRef): null | NodeRef<T | null> => {
-    for (let i = 1; i < ref.path.length; i++) {
-      const id = ref.path[ref.path.length - i - 1];
-
-      const commit = tree.commits.get(id) as recon.Commit;
-      // Early exit out of parent lookup if someone on the path is null;
-      if (commit.element.type === act.primitiveNodeTypes.null)
-        return { id, node: null };
-
-      const node = nodeByCommit.get(id);
-      // If you find an element with a node
-      if (node)
-        return { id, node }
-    }
-    // this element has no "node" parents - it is probably a "root" commit
-    return null;
-  }
-  const findRootId = (ref: recon.CommitRef) => {
-    for (let i = ref.path.length - 1; i >= 0; i--) {
-      const id = ref.path[i];
-      if (rootIds.has(id))
-        return id;
-    }
-    return null;
-  }
-
-  const space: RenderSpace =  {
-    create(deltas) {
-      const newNodes: Set<{ delta: recon.CreateDelta, node: T }> = new Set();
-      const needsReorder = new Set<recon.CommitID>();
-
-      for (const delta of deltas.created) {
-        if (delta.next.element.type === act.renderNodeType) {
-          // add render boundary
-          rootIds.add(delta.ref.id);
-          continue;
-        }
-        const rootId = findRootId(delta.ref);
-        const root = rootId && tree.commits.get(rootId) || null;
-        if (!root)
-          continue;
-
-        const rootType = root.element.props['type'] as R;
-
-        // test to see if this element
-        // belongs to this 
-        if (args.rootTypes.has(rootType) ) {
-          // Try to create a <T> for every new commit
-          const node = args.create(delta.next.element, rootType);
-          // Not all commits have a corresponding node
-          if (node) {
-            newNodes.add({ node, delta });
-            nodeByCommit.set(delta.ref.id, node);
-            commitByNode.set(node, delta.ref.id)
-          }
-        }
-      }
-
-      return {
-        configure() {
-          if (args.link || args.sort) {
-            // Loop through newly created nodes
-            for (const { delta, node } of newNodes) {
-              const parent = findParent(delta.ref);
-              const parentNode = parent && parent.node;
-              if (parentNode) {
-                needsReorder.add(parent.id)
-              }
-              if (args.link && (!parent || parentNode)) {
-                args.link(node, parentNode);
-              }
-            }
-          }
-
-          if (args.update) {
-            for (const delta of deltas.updated) {
-              const node = nodeByCommit.get(delta.ref.id);
-              if (!node)
-                continue;
-              args.update(node, delta.next.element, delta.prev.element);
-              if (delta.moved) {
-                const parent = findParent(delta.ref);
-                const parentNode = parent && parent.node;
-                if (parentNode) {
-                  needsReorder.add(parent.id)
-                }
-              }
-            }
-            for (const delta of deltas.created) {
-              const node = nodeByCommit.get(delta.ref.id);
-              if (node)
-                args.update(node, delta.next.element, null);
-            }
-          }
-          for (const delta of deltas.removed) {
-            const prevResult = nodeByCommit.get(delta.ref.id);
-            if (prevResult) {
-              nodeByCommit.delete(delta.ref.id);
-              const parentId = delta.ref.path.find(id => nodeByCommit.get(id));
-              if (parentId)
-                needsReorder.add(parentId)
-
-              commitByNode.delete(prevResult);
-              if (args.destroy)
-                args.destroy(prevResult);
-            }
-          }
-
-          if (args.sort) {
-            for (const id of needsReorder) {
-              const node = nodeByCommit.get(id);
-              if (node) {
-                const children = findChildren(id, true);
-                args.sort(node, children);
-              }
-            }
-          }
-        },
-      }
-    },
-  }
-
-  return space;
-};
-
-
-
-
-export const RenderSpace = {
-  combine(subspaces: RenderSpace[]) {
-    const create = (deltas: recon.DeltaSet) => {
-      const results = subspaces.map(ss => ss.create(deltas));
-  
-      const configure = () => {
-        results.map(result => result.configure());
-      }
-      return { configure }
-    };
-  
-    return { create };
-  },
-  simple: createSimpleRenderSpace
-}