@flighthq/node 0.1.0

package/src/traversal.test.ts

@@ -0,0 +1,233 @@
+import type { Node, NodeTraits } from '@flighthq/types';
+import { NodeKind } from '@flighthq/types';
+
+import { addNodeChild } from './hierarchy';
+import { createNode } from './node';
+import {
+  findNode,
+  findNodeByName,
+  forEachNodeAncestor,
+  forEachNodeDescendant,
+  getNodeChildren,
+  getNodeDepth,
+  getNodeNextSibling,
+  getNodePreviousSibling,
+  walkNodeDescendants,
+} from './traversal';
+
+let root: Node<NodeTraits>;
+let childA: Node<NodeTraits>;
+let childB: Node<NodeTraits>;
+let grandchild: Node<NodeTraits>;
+
+beforeEach(() => {
+  root = createNode(NodeKind);
+  root.name = 'root';
+  childA = createNode(NodeKind);
+  childA.name = 'childA';
+  childB = createNode(NodeKind);
+  childB.name = 'childB';
+  grandchild = createNode(NodeKind);
+  grandchild.name = 'grandchild';
+
+  addNodeChild(root, childA);
+  addNodeChild(root, childB);
+  addNodeChild(childA, grandchild);
+});
+
+describe('findNode', () => {
+  it('returns null for a leaf with no children', () => {
+    expect(findNode(grandchild, () => true)).toBeNull();
+  });
+
+  it('returns null when predicate never matches', () => {
+    expect(findNode(root, () => false)).toBeNull();
+  });
+
+  it('finds a direct child matching the predicate', () => {
+    const result = findNode(root, (n) => n.name === 'childA');
+    expect(result).toBe(childA);
+  });
+
+  it('finds a deep descendant matching the predicate', () => {
+    const result = findNode(root, (n) => n.name === 'grandchild');
+    expect(result).toBe(grandchild);
+  });
+
+  it('returns the first matching descendant in depth-first order', () => {
+    childB.name = 'childA'; // duplicate name
+    const result = findNode(root, (n) => n.name === 'childA');
+    // childA appears before childB in DFS
+    expect(result).toBe(childA);
+  });
+
+  it('does not include the source node itself', () => {
+    const result = findNode(root, (n) => n === root);
+    expect(result).toBeNull();
+  });
+});
+
+describe('findNodeByName', () => {
+  it('returns null when no descendant has the given name', () => {
+    expect(findNodeByName(root, 'missing')).toBeNull();
+  });
+
+  it('finds a direct child by name', () => {
+    expect(findNodeByName(root, 'childA')).toBe(childA);
+  });
+
+  it('finds a deep descendant by name', () => {
+    expect(findNodeByName(root, 'grandchild')).toBe(grandchild);
+  });
+
+  it('does not find the source node itself', () => {
+    expect(findNodeByName(root, 'root')).toBeNull();
+  });
+});
+
+describe('forEachNodeAncestor', () => {
+  it('does not call callback for a root node', () => {
+    const visited: Node<NodeTraits>[] = [];
+    forEachNodeAncestor(root, (n) => {
+      visited.push(n);
+      return true;
+    });
+    expect(visited).toHaveLength(0);
+  });
+
+  it('visits ancestors from parent toward root', () => {
+    const visited: Node<NodeTraits>[] = [];
+    forEachNodeAncestor(grandchild, (n) => {
+      visited.push(n);
+      return true;
+    });
+    expect(visited).toEqual([childA, root]);
+  });
+
+  it('stops early when callback returns false', () => {
+    const visited: Node<NodeTraits>[] = [];
+    forEachNodeAncestor(grandchild, (n) => {
+      visited.push(n);
+      return false; // stop after first
+    });
+    expect(visited).toEqual([childA]);
+  });
+});
+
+describe('forEachNodeDescendant', () => {
+  it('does not call callback for a leaf node', () => {
+    const visited: Node<NodeTraits>[] = [];
+    forEachNodeDescendant(grandchild, (n) => visited.push(n));
+    expect(visited).toHaveLength(0);
+  });
+
+  it('visits all descendants in depth-first pre-order', () => {
+    const visited: Node<NodeTraits>[] = [];
+    forEachNodeDescendant(root, (n) => visited.push(n));
+    expect(visited).toEqual([childA, grandchild, childB]);
+  });
+
+  it('does not include the source node', () => {
+    const visited: Node<NodeTraits>[] = [];
+    forEachNodeDescendant(root, (n) => visited.push(n));
+    expect(visited).not.toContain(root);
+  });
+});
+
+describe('getNodeChildren', () => {
+  it('returns an empty array for a node with no children', () => {
+    expect(getNodeChildren(grandchild)).toEqual([]);
+  });
+
+  it('returns a snapshot of direct children', () => {
+    const children = getNodeChildren(root);
+    expect(children).toEqual([childA, childB]);
+  });
+
+  it('returns a copy that does not reflect subsequent mutations', () => {
+    const snapshot = getNodeChildren(root);
+    const extra = createNode(NodeKind);
+    addNodeChild(root, extra);
+    expect(snapshot).toHaveLength(2);
+  });
+});
+
+describe('getNodeDepth', () => {
+  it('returns 0 for a root node', () => {
+    expect(getNodeDepth(root)).toBe(0);
+  });
+
+  it('returns 1 for a direct child of the root', () => {
+    expect(getNodeDepth(childA)).toBe(1);
+  });
+
+  it('returns the correct depth for a deeper node', () => {
+    expect(getNodeDepth(grandchild)).toBe(2);
+  });
+});
+
+describe('getNodeNextSibling', () => {
+  it('returns null for a root node', () => {
+    expect(getNodeNextSibling(root)).toBeNull();
+  });
+
+  it('returns null for the last child', () => {
+    expect(getNodeNextSibling(childB)).toBeNull();
+  });
+
+  it('returns the next sibling', () => {
+    expect(getNodeNextSibling(childA)).toBe(childB);
+  });
+});
+
+describe('getNodePreviousSibling', () => {
+  it('returns null for a root node', () => {
+    expect(getNodePreviousSibling(root)).toBeNull();
+  });
+
+  it('returns null for the first child', () => {
+    expect(getNodePreviousSibling(childA)).toBeNull();
+  });
+
+  it('returns the previous sibling', () => {
+    expect(getNodePreviousSibling(childB)).toBe(childA);
+  });
+});
+
+describe('walkNodeDescendants', () => {
+  it('returns true when no children are present', () => {
+    expect(walkNodeDescendants(grandchild, () => true)).toBe(true);
+  });
+
+  it('visits all descendants in depth-first pre-order when visitor always returns true', () => {
+    const visited: Node<NodeTraits>[] = [];
+    const result = walkNodeDescendants(root, (n) => {
+      visited.push(n);
+      return true;
+    });
+    expect(result).toBe(true);
+    expect(visited).toEqual([childA, grandchild, childB]);
+  });
+
+  it('stops early and returns false when visitor returns false', () => {
+    const visited: Node<NodeTraits>[] = [];
+    const result = walkNodeDescendants(root, (n) => {
+      visited.push(n);
+      return false; // stop at first node
+    });
+    expect(result).toBe(false);
+    expect(visited).toHaveLength(1);
+    expect(visited[0]).toBe(childA);
+  });
+
+  it('does not visit subtree when visitor returns false for a parent', () => {
+    const visited: Node<NodeTraits>[] = [];
+    walkNodeDescendants(root, (n) => {
+      visited.push(n);
+      // Stop when we reach childA — its subtree (grandchild) should be skipped
+      return n !== childA;
+    });
+    expect(visited).not.toContain(grandchild);
+    expect(visited).not.toContain(childB);
+  });
+});

package/src/viewport.test.ts

@@ -0,0 +1,228 @@
+import { createMatrix } from '@flighthq/geometry';
+import type { HasBoundsRectangleRuntime } from '@flighthq/types';
+
+import { createNode, getNodeRuntime } from './node';
+import {
+  computeViewportAlignX,
+  computeViewportAlignY,
+  computeViewportFillScale,
+  computeViewportFitScale,
+  computeViewportRenderTransform,
+  createViewport,
+} from './viewport';
+
+const TestNodeKind = 'TestNode';
+
+function makeNodeWithBounds(width: number, height: number) {
+  const node = createNode(TestNodeKind);
+  const runtime = getNodeRuntime(node) as unknown as HasBoundsRectangleRuntime;
+  runtime.computeLocalBoundsRectangle = (out) => {
+    out.width = width;
+    out.height = height;
+  };
+  return node;
+}
+
+describe('computeViewportAlignX', () => {
+  it('returns 0 for left-anchored alignments', () => {
+    expect(computeViewportAlignX(400, 800, 'left')).toBe(0);
+    expect(computeViewportAlignX(400, 800, 'topleft')).toBe(0);
+    expect(computeViewportAlignX(400, 800, 'bottomleft')).toBe(0);
+  });
+
+  it('returns viewWidth - scaledWidth for right-anchored alignments', () => {
+    expect(computeViewportAlignX(400, 800, 'right')).toBe(400);
+    expect(computeViewportAlignX(400, 800, 'topright')).toBe(400);
+    expect(computeViewportAlignX(400, 800, 'bottomright')).toBe(400);
+  });
+
+  it('returns centered offset for top/bottom alignments', () => {
+    expect(computeViewportAlignX(400, 800, 'top')).toBe(200);
+    expect(computeViewportAlignX(400, 800, 'bottom')).toBe(200);
+  });
+});
+
+describe('computeViewportAlignY', () => {
+  it('returns 0 for top-anchored alignments', () => {
+    expect(computeViewportAlignY(300, 600, 'top')).toBe(0);
+    expect(computeViewportAlignY(300, 600, 'topleft')).toBe(0);
+    expect(computeViewportAlignY(300, 600, 'topright')).toBe(0);
+  });
+
+  it('returns viewHeight - scaledHeight for bottom-anchored alignments', () => {
+    expect(computeViewportAlignY(300, 600, 'bottom')).toBe(300);
+    expect(computeViewportAlignY(300, 600, 'bottomleft')).toBe(300);
+    expect(computeViewportAlignY(300, 600, 'bottomright')).toBe(300);
+  });
+
+  it('returns centered offset for left/right alignments', () => {
+    expect(computeViewportAlignY(300, 600, 'left')).toBe(150);
+    expect(computeViewportAlignY(300, 600, 'right')).toBe(150);
+  });
+});
+
+describe('computeViewportFillScale', () => {
+  it('returns max of width and height ratios', () => {
+    expect(computeViewportFillScale(400, 300, 800, 600)).toBe(2);
+  });
+
+  it('uses the larger ratio when width ratio wins', () => {
+    expect(computeViewportFillScale(400, 300, 800, 400)).toBeCloseTo(2);
+  });
+
+  it('uses the larger ratio when height ratio wins', () => {
+    expect(computeViewportFillScale(400, 300, 400, 600)).toBe(2);
+  });
+});
+
+describe('computeViewportFitScale', () => {
+  it('returns min of width and height ratios', () => {
+    expect(computeViewportFitScale(400, 300, 800, 600)).toBe(2);
+  });
+
+  it('uses the smaller ratio when width ratio wins', () => {
+    expect(computeViewportFitScale(400, 300, 400, 600)).toBe(1);
+  });
+
+  it('uses the smaller ratio when height ratio wins', () => {
+    expect(computeViewportFitScale(400, 300, 800, 400)).toBeCloseTo(400 / 300);
+  });
+});
+
+describe('computeViewportRenderTransform', () => {
+  it('sets identity when root is null', () => {
+    const m = createMatrix();
+    computeViewportRenderTransform(m, createViewport(), 800, 600);
+    expect(m.a).toBe(1);
+    expect(m.b).toBe(0);
+    expect(m.c).toBe(0);
+    expect(m.d).toBe(1);
+    expect(m.tx).toBe(0);
+    expect(m.ty).toBe(0);
+  });
+
+  it('sets identity when root has no bounds capability', () => {
+    const m = createMatrix();
+    const root = createNode(TestNodeKind);
+    computeViewportRenderTransform(m, createViewport({ root }), 800, 600);
+    expect(m.a).toBe(1);
+    expect(m.d).toBe(1);
+    expect(m.tx).toBe(0);
+    expect(m.ty).toBe(0);
+  });
+
+  it('sets identity when root computeLocalBoundsRectangle returns zero size', () => {
+    const m = createMatrix();
+    const root = makeNodeWithBounds(0, 0);
+    computeViewportRenderTransform(m, createViewport({ root }), 800, 600);
+    expect(m.a).toBe(1);
+    expect(m.d).toBe(1);
+  });
+
+  it('noscale with topleft: identity scale at origin', () => {
+    const m = createMatrix();
+    computeViewportRenderTransform(
+      m,
+      createViewport({ root: makeNodeWithBounds(400, 300), scaleMode: 'noscale', align: 'topleft' }),
+      800,
+      600,
+    );
+    expect(m.a).toBe(1);
+    expect(m.d).toBe(1);
+    expect(m.tx).toBe(0);
+    expect(m.ty).toBe(0);
+  });
+
+  it('noscale with top alignment: centers horizontally', () => {
+    const m = createMatrix();
+    computeViewportRenderTransform(
+      m,
+      createViewport({ root: makeNodeWithBounds(400, 300), scaleMode: 'noscale', align: 'top' }),
+      800,
+      600,
+    );
+    expect(m.a).toBe(1);
+    expect(m.d).toBe(1);
+    expect(m.tx).toBe(200);
+    expect(m.ty).toBe(0);
+  });
+
+  it('exactfit: scales to fill viewport exactly', () => {
+    const m = createMatrix();
+    computeViewportRenderTransform(
+      m,
+      createViewport({ root: makeNodeWithBounds(400, 300), scaleMode: 'exactfit', align: 'topleft' }),
+      800,
+      600,
+    );
+    expect(m.a).toBe(2);
+    expect(m.d).toBe(2);
+    expect(m.tx).toBe(0);
+    expect(m.ty).toBe(0);
+  });
+
+  it('exactfit: uses independent x/y scales', () => {
+    const m = createMatrix();
+    computeViewportRenderTransform(
+      m,
+      createViewport({ root: makeNodeWithBounds(400, 300), scaleMode: 'exactfit', align: 'topleft' }),
+      800,
+      450,
+    );
+    expect(m.a).toBe(2);
+    expect(m.d).toBe(1.5);
+  });
+
+  it('showall: fits content within viewport with uniform scale', () => {
+    const m = createMatrix();
+    // viewport 800x400, content 400x300: min(2, 400/300) = 400/300
+    computeViewportRenderTransform(
+      m,
+      createViewport({ root: makeNodeWithBounds(400, 300), scaleMode: 'showall', align: 'topleft' }),
+      800,
+      400,
+    );
+    expect(m.a).toBeCloseTo(400 / 300);
+    expect(m.d).toBeCloseTo(400 / 300);
+  });
+
+  it('noborder: fills viewport with uniform scale', () => {
+    const m = createMatrix();
+    // viewport 800x400, content 400x300: max(2, 400/300) = 2
+    computeViewportRenderTransform(
+      m,
+      createViewport({ root: makeNodeWithBounds(400, 300), scaleMode: 'noborder', align: 'topleft' }),
+      800,
+      400,
+    );
+    expect(m.a).toBe(2);
+    expect(m.d).toBe(2);
+  });
+
+  it('sets b and c to 0', () => {
+    const m = createMatrix();
+    computeViewportRenderTransform(
+      m,
+      createViewport({ root: makeNodeWithBounds(400, 300), scaleMode: 'showall', align: 'topleft' }),
+      800,
+      600,
+    );
+    expect(m.b).toBe(0);
+    expect(m.c).toBe(0);
+  });
+});
+
+describe('createViewport', () => {
+  it('returns default values', () => {
+    const scene = createViewport();
+    expect(scene.root).toBeNull();
+    expect(scene.scaleMode).toBe('noscale');
+    expect(scene.align).toBe('topleft');
+  });
+
+  it('accepts overrides', () => {
+    const scene = createViewport({ scaleMode: 'showall', align: 'top' });
+    expect(scene.scaleMode).toBe('showall');
+    expect(scene.align).toBe('top');
+  });
+});