@canvas-commons/2d 0.2.0

package/src/lib/components/__tests__/children.test.tsx

@@ -0,0 +1,142 @@
+import {createRef, createSignal, range} from '@canvas-commons/core';
+import {describe, expect, it} from 'vitest';
+import {useScene2D} from '../../scenes';
+import {Node} from '../Node';
+import {mockScene2D} from './mockScene2D';
+
+describe('children', () => {
+  mockScene2D();
+
+  it('Append children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = createRef<Node>();
+    const childB = createRef<Node>();
+
+    view.add(
+      <Node ref={parent}>
+        <Node ref={childA} />
+        <Node ref={childB} />
+      </Node>,
+    );
+
+    expect(childA().parent()).toBe(parent());
+    expect(childB().parent()).toBe(parent());
+    expect(parent().children()).toEqual([childA(), childB()]);
+  });
+
+  it('Clear children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = createRef<Node>();
+    const childB = createRef<Node>();
+
+    view.add(
+      <Node ref={parent}>
+        <Node ref={childA} />
+        <Node ref={childB} />
+      </Node>,
+    );
+
+    parent().removeChildren();
+
+    expect(childA().parent()).toBe(null);
+    expect(childB().parent()).toBe(null);
+    expect(parent().children()).toEqual([]);
+  });
+
+  it('Replace children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = <Node />;
+    const childB = <Node />;
+
+    view.add(<Node ref={parent}>{childA}</Node>);
+
+    parent().children(childB);
+
+    expect(childA.parent()).toBe(null);
+    expect(childB.parent()).toBe(parent());
+    expect(parent().children()).toEqual([childB]);
+  });
+
+  it('Take a child from another node', () => {
+    const view = useScene2D().getView();
+    const parentA = createRef<Node>();
+    const parentB = createRef<Node>();
+    const child = createRef<Node>();
+
+    view.add(
+      <>
+        <Node ref={parentA}>
+          <Node ref={child} />
+        </Node>
+        <Node ref={parentB} />
+      </>,
+    );
+
+    expect(parentA().children()).toEqual([child()]);
+    expect(parentB().children()).toEqual([]);
+    expect(child().parent()).toBe(parentA());
+
+    parentB().children(child());
+
+    expect(parentA().children()).toEqual([]);
+    expect(parentB().children()).toEqual([child()]);
+    expect(child().parent()).toBe(parentB());
+  });
+
+  it('Append children conditionally', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = <Node />;
+    const childB = <Node />;
+    const predicate = createSignal(false);
+
+    view.add(<Node ref={parent}>{() => (predicate() ? childA : childB)}</Node>);
+
+    expect(parent().children()).toEqual([childB]);
+    expect(childA.parent()).toBe(null);
+    expect(childB.parent()).toBe(parent());
+
+    predicate(true);
+
+    expect(parent().children()).toEqual([childA]);
+    expect(childA.parent()).toBe(parent());
+    expect(childB.parent()).toBe(null);
+  });
+
+  it('Spawn reactive children', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const count = createSignal(3);
+
+    view.add(
+      <Node ref={parent}>{() => range(count()).map(() => <Node />)}</Node>,
+    );
+
+    expect(parent().children().length).toBe(3);
+
+    count(5);
+
+    expect(parent().children().length).toBe(5);
+  });
+
+  it('Replace a spawner', () => {
+    const view = useScene2D().getView();
+    const parent = createRef<Node>();
+    const childA = <Node />;
+    const childB = <Node />;
+
+    view.add(<Node ref={parent}>{() => childA}</Node>);
+
+    expect(parent().children()).toEqual([childA]);
+    expect(childA.parent()).toBe(parent());
+
+    parent().children(childB);
+
+    expect(childA.parent()).toBe(null);
+    expect(childB.parent()).toBe(parent());
+    expect(parent().children()).toEqual([childB]);
+  });
+});

package/src/lib/components/__tests__/clone.test.tsx

@@ -0,0 +1,126 @@
+import {Vector2, createSignal, range} from '@canvas-commons/core';
+import {describe, expect, it} from 'vitest';
+import {Circle} from '../Circle';
+import {Node} from '../Node';
+import {mockScene2D} from './mockScene2D';
+
+describe('clone', () => {
+  mockScene2D();
+
+  it('Normal clone', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    const clone = template.clone({end: 0});
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.end()).toBe(0);
+    expect(clone.startArrow.context.isInitial()).toBe(true);
+
+    signal(90);
+
+    expect(clone.startAngle()).toBe(90);
+  });
+
+  it('Reactive clone', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    const clone = template.reactiveClone({end: 0});
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.end()).toBe(0);
+    expect(clone.startArrow.context.isInitial()).toBe(false);
+
+    template.lineWidth(16);
+    template.startArrow(true);
+    template.end(0.25);
+    signal(90);
+
+    expect(clone.lineWidth()).toBe(16);
+    expect(clone.startAngle()).toBe(90);
+    expect(clone.startArrow()).toBe(true);
+    expect(clone.end()).toBe(0);
+  });
+
+  it('Snapshot clone', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    const clone = template.snapshotClone({end: 0});
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.end()).toBe(0);
+    expect(clone.startArrow.context.isInitial()).toBe(true);
+
+    template.lineWidth(16);
+    template.startArrow(true);
+    signal(90);
+
+    expect(clone.lineWidth()).toBe(8);
+    expect(clone.startAngle()).toBe(45);
+    expect(clone.startArrow()).toBe(false);
+  });
+
+  it('Clone compound signal', () => {
+    const signal = Vector2.createSignal(200);
+    const template = (<Circle anchor={1} position={signal} />) as Circle;
+    const clone = template.clone({x: 100, anchorY: -1});
+
+    expect(clone.x()).toBe(100);
+    expect(clone.y()).toBe(200);
+    expect(clone.anchor.x()).toBe(1);
+    expect(clone.anchor.y()).toBe(-1);
+
+    signal([300, 400]);
+
+    expect(clone.x()).toBe(100);
+    expect(clone.y()).toBe(400);
+  });
+
+  it('Clone children', () => {
+    const signal = createSignal(45);
+    const template = (
+      <Node>
+        <Circle lineWidth={8} startAngle={signal} />
+      </Node>
+    );
+    const clone = template.clone();
+
+    expect(clone.children().length).toBe(1);
+    expect(clone.childAs(0)).not.toBe(template.childAs(0));
+    expect(clone.childAs<Circle>(0)!.lineWidth()).toBe(8);
+    expect(clone.childAs<Circle>(0)!.startAngle()).toBe(45);
+
+    signal(90);
+
+    expect(clone.childAs<Circle>(0)!.startAngle()).toBe(90);
+  });
+
+  it('Clone spawner', () => {
+    const count = createSignal(3);
+    const template = (
+      <Node>
+        {() =>
+          range(count()).map(() => (
+            <Circle lineWidth={8} startAngle={count} end={0.5} />
+          ))
+        }
+      </Node>
+    );
+    const clone = template.clone();
+
+    expect(clone.children().length).toBe(3);
+    expect(clone.childAs(0)).not.toBe(template.childAs(0));
+
+    count(5);
+
+    expect(clone.children().length).toBe(5);
+  });
+});

package/src/lib/components/__tests__/fontInheritance.test.tsx

@@ -0,0 +1,102 @@
+import {createRef} from '@canvas-commons/core';
+import {describe, expect, it} from 'vitest';
+import {useScene2D} from '../../scenes';
+import {Layout} from '../Layout';
+import {Txt} from '../Txt';
+import {mockScene2D} from './mockScene2D';
+
+describe('font inheritance', () => {
+  mockScene2D();
+
+  it('inherits fontSize from the view to a direct Txt child', () => {
+    const view = useScene2D().getView();
+    view.fontSize(100);
+    const txt = createRef<Txt>();
+
+    view.add(<Txt ref={txt}>hello</Txt>);
+
+    expect(txt().fontSize()).toBe(100);
+  });
+
+  it('inherits fontFamily from the view to a direct Txt child', () => {
+    const view = useScene2D().getView();
+    view.fontFamily('Comic Sans');
+    const txt = createRef<Txt>();
+
+    view.add(<Txt ref={txt}>hello</Txt>);
+
+    expect(txt().fontFamily()).toBe('Comic Sans');
+  });
+
+  it('inherits fontSize through a non-layout Layout wrapper', () => {
+    const view = useScene2D().getView();
+    view.fontSize(72);
+    const txt = createRef<Txt>();
+
+    view.add(
+      <Layout>
+        <Txt ref={txt}>hello</Txt>
+      </Layout>,
+    );
+
+    expect(txt().fontSize()).toBe(72);
+  });
+
+  it('inherits fontSize through a layout-enabled Layout wrapper', () => {
+    const view = useScene2D().getView();
+    view.fontSize(64);
+    const txt = createRef<Txt>();
+
+    view.add(
+      <Layout layout>
+        <Txt ref={txt}>hello</Txt>
+      </Layout>,
+    );
+
+    expect(txt().fontSize()).toBe(64);
+  });
+
+  it('explicit fontSize on child overrides inherited value', () => {
+    const view = useScene2D().getView();
+    view.fontSize(100);
+    const txt = createRef<Txt>();
+
+    view.add(
+      <Txt ref={txt} fontSize={25}>
+        hello
+      </Txt>,
+    );
+
+    expect(txt().fontSize()).toBe(25);
+  });
+
+  it('layout={false} on a Layout disables inheritance and falls back to initial', () => {
+    const view = useScene2D().getView();
+    view.fontSize(100);
+    const layout = createRef<Layout>();
+
+    view.add(<Layout ref={layout} layout={false} />);
+
+    expect(layout().fontSize()).toBe(48);
+  });
+
+  it('inherits the full set of text properties from the view', () => {
+    const view = useScene2D().getView();
+    view.fontWeight(800);
+    view.fontStyle('italic');
+    view.lineHeight(42);
+    view.letterSpacing(3);
+    view.textAlign('center');
+    view.textWrap(true);
+    const txt = createRef<Txt>();
+
+    view.add(<Txt ref={txt}>hello</Txt>);
+
+    expect(txt().fontWeight()).toBe(800);
+    expect(txt().fontStyle()).toBe('italic');
+    expect(txt().lineHeight()).toBe(42);
+    expect(txt().letterSpacing()).toBe(3);
+    expect(txt().textAlign()).toBe('center');
+    expect(txt().textWrap()).toBe(true);
+  });
+});

package/src/lib/components/__tests__/generatorTest.ts

@@ -0,0 +1,27 @@
+import {ThreadGeneratorFactory, threads} from '@canvas-commons/core';
+import {useScene2D} from '../../scenes';
+import {View2D} from '../View2D';
+
+/**
+ * Turn a generator factory into a test function.
+ *
+ * @example
+ * ```ts
+ * it(
+ *   'Example test',
+ *   generatorTest(function* () {
+ *     yield* waitFor(1);
+ *     expect(useTime()).toBe(1);
+ *   }),
+ * );
+ * ```
+ *
+ * @param factory - The generator factory to test.
+ */
+export function generatorTest(factory: ThreadGeneratorFactory<View2D>) {
+  return () => {
+    const view = useScene2D().getView();
+    const tasks = threads(() => factory(view));
+    [...tasks];
+  };
+}

package/src/lib/components/__tests__/mockScene2D.ts

@@ -0,0 +1,50 @@
+import {
+  FullSceneDescription,
+  PlaybackManager,
+  PlaybackStatus,
+  ReadOnlyTimeEvents,
+  ThreadGeneratorFactory,
+  ValueDispatcher,
+  Vector2,
+  endPlayback,
+  endScene,
+  startPlayback,
+  startScene,
+} from '@canvas-commons/core';
+import {afterAll, beforeAll, beforeEach} from 'vitest';
+import {Scene2D, makeScene2D} from '../../scenes';
+import {View2D} from '../View2D';
+
+/**
+ * Set up the test environment to support creating nodes.
+ *
+ * @remarks
+ * Should be called inside a `describe()` block.
+ * Due to js-dom limitations, layouts are not correctly computed.
+ */
+export function mockScene2D() {
+  const playback = new PlaybackManager();
+  const status = new PlaybackStatus(playback);
+  const description = {
+    ...makeScene2D(function* () {
+      // do nothing
+    }),
+    name: 'test',
+    size: new Vector2(1920, 1080),
+    resolutionScale: 1,
+    timeEventsClass: ReadOnlyTimeEvents,
+    playback: status,
+  } as unknown as FullSceneDescription<ThreadGeneratorFactory<View2D>>;
+  description.onReplaced = new ValueDispatcher(description);
+  const scene = new Scene2D(description);
+
+  beforeAll(() => {
+    startScene(scene);
+    startPlayback(status);
+  });
+  afterAll(() => {
+    endPlayback(status);
+    endScene(scene);
+  });
+  beforeEach(() => scene.reset());
+}

package/src/lib/components/__tests__/query.test.tsx

@@ -0,0 +1,122 @@
+import {createRef, createRefArray} from '@canvas-commons/core';
+import {describe, expect, it} from 'vitest';
+import {useScene2D} from '../../scenes';
+import {is} from '../../utils';
+import {Circle} from '../Circle';
+import {Rect} from '../Rect';
+import {mockScene2D} from './mockScene2D';
+
+describe('query', () => {
+  mockScene2D();
+
+  it('Query items based on their type', () => {
+    const view = useScene2D().getView();
+    const circles = createRefArray<Circle>();
+    view.add(
+      <>
+        <Rect />
+        <Circle ref={circles} />
+        <Rect />
+        <Circle ref={circles} />
+        <Rect />
+      </>,
+    );
+
+    const query = view.findAll(is(Circle));
+    expect(query.length).toBe(2);
+    expect(query).toEqual([...circles]);
+  });
+
+  it('Query items based on a custom predicate', () => {
+    const view = useScene2D().getView();
+    const nodes = createRefArray<Node>();
+    view.add(
+      <>
+        <Rect ref={nodes} scale={2} />
+        <Rect />
+        <Circle />
+        <Circle ref={nodes} scale={2} />
+      </>,
+    );
+
+    const query = view.findAll(node => node.scale.x() === 2);
+    expect(query.length).toBe(2);
+    expect(query).toEqual([...nodes]);
+  });
+
+  it('Query the first matching child', () => {
+    const view = useScene2D().getView();
+    const match = createRef<Circle>();
+    view.add(
+      <>
+        <Rect />
+        <Rect>
+          <Rect />
+          <Circle ref={match} />
+        </Rect>
+        <Circle />
+        <Rect />
+      </>,
+    );
+
+    const query = view.findFirst(is(Circle));
+    expect(query).toBe(match());
+  });
+
+  it('Query the last matching child', () => {
+    const view = useScene2D().getView();
+    const match = createRef<Circle>();
+    view.add(
+      <>
+        <Rect />
+        <Circle />
+        <Circle>
+          <Circle />
+          <Rect />
+          <Circle ref={match} />
+        </Circle>
+        <Rect />
+      </>,
+    );
+
+    const query = view.findLast(is(Circle));
+    expect(query?.key).toBe(match().key);
+  });
+
+  it('Query the first matching ancestor', () => {
+    const view = useScene2D().getView();
+    const child = createRef<Circle>();
+    const match = createRef<Circle>();
+    view.add(
+      <Circle>
+        <Circle ref={match}>
+          <Rect>
+            <Circle />
+            <Circle ref={child} />
+            <Circle />
+          </Rect>
+        </Circle>
+      </Circle>,
+    );
+
+    const query = child().findAncestor(is(Circle));
+    expect(query).toBe(match());
+  });
+
+  it('Retrieve a node by its key', () => {
+    const view = useScene2D().getView();
+    const match = createRef<Circle>();
+    view.add(
+      <>
+        <Circle>
+          <Rect />
+          <Circle ref={match} key="test-key" />
+        </Circle>
+        <Rect />
+      </>,
+    );
+
+    const query = view.findKey('test-key');
+    expect(query).toBe(match());
+  });
+});

package/src/lib/components/__tests__/state.test.tsx

@@ -0,0 +1,60 @@
+import {createSignal, join, waitFor} from '@canvas-commons/core';
+import {describe, expect, it} from 'vitest';
+import {Circle} from '../Circle';
+import {generatorTest} from './generatorTest';
+import {mockScene2D} from './mockScene2D';
+
+describe('state', () => {
+  mockScene2D();
+
+  it('Restoring state', () => {
+    const signal = createSignal(45);
+    const circle = (
+      <Circle lineWidth={8} startAngle={signal} end={0.5} />
+    ) as Circle;
+    circle.save();
+
+    circle.lineWidth(16);
+    circle.startAngle(90);
+    circle.end(0.25);
+
+    circle.restore();
+
+    expect(circle.lineWidth()).toBe(8);
+    expect(circle.startAngle()).toBe(45);
+    expect(circle.end()).toBe(0.5);
+
+    signal(180);
+
+    expect(circle.startAngle()).toBe(45);
+    expect(circle.startArrow.context.isInitial()).toBe(true);
+  });
+
+  it(
+    'Tweening state',
+    generatorTest(function* () {
+      const signal = createSignal(20);
+      const circle = (
+        <Circle lineWidth={8} startAngle={signal} end={0.5} />
+      ) as Circle;
+      circle.save();
+
+      circle.lineWidth(16);
+      circle.startAngle(40);
+      circle.end(0.3);
+
+      const task = yield circle.restore(2);
+      yield* waitFor(1);
+
+      expect(circle.lineWidth()).closeTo(12, 0.0001);
+      expect(circle.startAngle()).closeTo(30, 0.0001);
+      expect(circle.end()).closeTo(0.4, 0.0001);
+
+      yield* join(task);
+
+      expect(circle.lineWidth()).toBe(8);
+      expect(circle.startAngle()).toBe(20);
+      expect(circle.end()).toBe(0.5);
+    }),
+  );
+});

package/src/lib/components/index.ts

@@ -0,0 +1,26 @@
+export * from './Bezier';
+export * from './Camera';
+export * from './Circle';
+export * from './Code';
+export * from './CubicBezier';
+export * from './Curve';
+export * from './Grid';
+export * from './Icon';
+export * from './Img';
+export * from './Knot';
+export * from './Latex';
+export * from './Layout';
+export * from './Line';
+export * from './Node';
+export * from './Path';
+export * from './Polygon';
+export * from './QuadBezier';
+export * from './Ray';
+export * from './Rect';
+export * from './Shape';
+export * from './Spline';
+export * from './SVG';
+export * from './Txt';
+export * from './types';
+export * from './Video';
+export * from './View2D';

package/src/lib/components/types.ts

@@ -0,0 +1,35 @@
+import type {ReferenceReceiver} from '@canvas-commons/core';
+import type {Node} from './Node';
+
+export type ComponentChild =
+  | Node
+  | object
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined;
+
+export type ComponentChildren = ComponentChild | ComponentChild[];
+export type NodeChildren = Node | Node[];
+
+export type PropsOf<T> =
+  T extends NodeConstructor<infer P>
+    ? P
+    : T extends FunctionComponent<infer P>
+      ? P
+      : never;
+
+export interface JSXProps {
+  children?: ComponentChildren;
+  ref?: ReferenceReceiver<Node>;
+}
+
+export interface FunctionComponent<T = any> {
+  (props: T): Node | null;
+}
+
+export interface NodeConstructor<TProps = any, TNode = Node> {
+  new (props: TProps): TNode;
+}