@caperjs/solid 0.7.0

package/src/asComponent.test.ts

@@ -0,0 +1,168 @@
+import { Application, Container } from '@caperjs/core';
+import { Graphics, Sprite } from 'pixi.js';
+import { createSignal } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { asComponent } from './asComponent';
+import { ComposableContainer, type Composes } from './Composable';
+import { createElement, type PixiNode, render } from './renderer';
+
+/**
+ * Caper's `Container` reaches for the Application singleton on `added`,
+ * `removed` and `destroy`. Only the members those paths touch are stubbed.
+ */
+function stubApplication() {
+  const ticker = { add: vi.fn(), remove: vi.fn(), addOnce: vi.fn() };
+  const layout = { update: vi.fn(), _updateSize: vi.fn(), updateLayout: vi.fn() };
+  const onResize = { connect: vi.fn(() => ({ disconnect: vi.fn() })), disconnect: vi.fn() };
+  (Application as any).instance = {
+    config: { useLayout: true },
+    ticker,
+    onResize,
+    animation: { killAll: vi.fn() },
+    renderer: { layout },
+  };
+  return { ticker, layout, onResize };
+}
+
+beforeEach(() => {
+  stubApplication();
+});
+
+afterEach(() => {
+  (Application as any).instance = undefined;
+});
+
+/** Mount a component the way JSX would: into a host node, inside a solid root. */
+function mount<T extends PixiNode>(component: () => T) {
+  const root = createElement('container');
+  const dispose = render(() => component(), root);
+  return { root, node: root.children[0] as T, dispose };
+}
+
+/** An ordinary imperative display class that knows nothing about Solid. */
+class Widget extends Container {}
+
+/** Builds its own look up front — the case `skipChildren` protects. */
+class SelfBuilt extends Container {
+  constructor(config?: any) {
+    super(config);
+    this.add.graphics();
+  }
+}
+
+describe('asComponent', () => {
+  it('mounts the constructed instance and applies props', () => {
+    const Widget$ = asComponent(Widget);
+    const { root, node } = mount(() => Widget$({ x: 5, alpha: 0.5 }));
+
+    expect(root.children).toHaveLength(1);
+    expect(node).toBeInstanceOf(Widget);
+    expect(node.x).toBe(5);
+    expect(node.alpha).toBe(0.5);
+  });
+
+  it('keeps props reactive after mount', () => {
+    const [x, setX] = createSignal(0);
+    const Widget$ = asComponent(Widget);
+    const { node, dispose } = mount(() =>
+      Widget$({
+        get x() {
+          return x();
+        },
+      }),
+    );
+
+    expect(node.x).toBe(0);
+    setX(25);
+    expect(node.x).toBe(25);
+
+    dispose();
+    setX(99);
+    expect(node.x).toBe(25);
+  });
+
+  it('constructs once, untracked — a signal read in the constructor is not a dependency', () => {
+    const [label, setLabel] = createSignal('one');
+    const built: string[] = [];
+
+    class Reader extends Container {
+      constructor() {
+        super();
+        built.push(label());
+      }
+    }
+
+    const Reader$ = asComponent(Reader);
+    const { node } = mount(() => Reader$({}));
+
+    setLabel('two');
+
+    expect(built).toEqual(['one']);
+    expect(node).toBeInstanceOf(Reader);
+  });
+
+  it('hands the defaults to the constructor', () => {
+    let received: unknown;
+
+    class Configured extends Container {
+      constructor(config?: { label?: string }) {
+        super(config as any);
+        received = config;
+      }
+    }
+
+    const Configured$ = asComponent(Configured, { label: 'hp' });
+    mount(() => Configured$({ x: 1 }));
+
+    expect(received).toEqual({ label: 'hp' });
+  });
+
+  it('calls a ref prop with the instance', () => {
+    let captured: Widget | undefined;
+    const Widget$ = asComponent(Widget);
+    const { node } = mount(() => Widget$({ ref: (el: Widget) => (captured = el) }));
+
+    expect(captured).toBe(node);
+  });
+
+  describe('children', () => {
+    it('leaves the class’s own children alone when no JSX children are passed', () => {
+      const SelfBuilt$ = asComponent(SelfBuilt);
+      const { node } = mount(() => SelfBuilt$({ x: 1 }));
+
+      // `skipChildren` is what keeps solid's children pass — an
+      // `insertExpression(node, undefined, …)` that ends in `cleanChildren` —
+      // away from what the class built for itself. (solid 1.9 happens to also
+      // bail out of that pass early when both values are `undefined`; the guard
+      // is what the contract rests on, not that detail.)
+      expect(node.children).toHaveLength(1);
+      expect(node.children[0]).toBeInstanceOf(Graphics);
+      expect(node.children[0].destroyed).toBe(false);
+    });
+
+    it('inserts JSX children when they are passed', () => {
+      const Widget$ = asComponent(Widget);
+      const child = createElement('sprite');
+      const { node } = mount(() => Widget$({ children: child }));
+
+      expect(node.children).toEqual([child]);
+    });
+  });
+
+  it('still mounts a composed class’s own tree', () => {
+    class Bar extends ComposableContainer implements Composes {
+      public compose() {
+        return createElement('sprite');
+      }
+    }
+
+    const Bar$ = asComponent(Bar);
+    const { node } = mount(() => Bar$({ x: 3 }));
+
+    expect(node).toBeInstanceOf(Bar);
+    expect(node.x).toBe(3);
+    expect(node.children).toHaveLength(1);
+    expect(node.children[0]).toBeInstanceOf(Sprite);
+  });
+});

package/src/asComponent.ts

@@ -0,0 +1,37 @@
+// Lifting existing imperative display classes into JSX — the escape hatch that
+// keeps the intrinsic catalog small.
+
+import { untrack } from 'solid-js';
+
+import type { PixiNode } from './renderer';
+import { spread } from './renderer';
+
+/**
+ * Lift an existing imperative display class into a JSX component.
+ *
+ * The instance is constructed once (untracked, so constructor reads don't
+ * subscribe to anything) and every prop is then applied through the renderer's
+ * own `spread`, which gives them the same reactivity as an intrinsic element —
+ * including `ref`.
+ *
+ * ```tsx
+ * const Orbiter$ = asComponent(Orbiter);
+ * <Orbiter$ x={40} y={80} />
+ * ```
+ *
+ * @param Ctor - The display class to lift. Called as `new Ctor(defaults)`.
+ * @param defaults - Config handed to the constructor on every mount.
+ */
+export function asComponent<TNode extends PixiNode, TConfig>(
+  Ctor: new (config?: TConfig) => TNode,
+  defaults?: TConfig,
+): (props: Record<string, any>) => TNode {
+  return (props) => {
+    const node = untrack(() => new Ctor(defaults));
+    // Skip the children pass when none were passed — otherwise Solid's spread
+    // "clears" the node, which would wipe anything the class built for itself
+    // (in `added()`, its own `compose()`, or the constructor).
+    spread(node, props as any, !('children' in props));
+    return node;
+  };
+}

package/src/catalog.ts

@@ -0,0 +1,28 @@
+import { FlexContainer } from '@caperjs/core';
+import { Container, Graphics, Sprite, Text } from 'pixi.js';
+
+/**
+ * The intrinsic elements JSX can name. Every entry is a zero-arg-constructible
+ * Pixi display object; the renderer applies props to the instance afterwards.
+ */
+export const catalog = {
+  container: Container,
+  sprite: Sprite,
+  text: Text,
+  graphics: Graphics,
+  // Caper UI primitive. Its layout props (`gap`, `flexDirection`, …) are plain
+  // accessors that re-run its deferred layout pass, so `setProperty`'s default
+  // assignment is all it needs.
+  flexContainer: FlexContainer,
+} as const;
+
+export type CatalogTag = keyof typeof catalog;
+
+/** Construct the display object for an intrinsic tag. Throws on unknown tags. */
+export function createCatalogNode(tag: string): Container {
+  const Ctor = catalog[tag as CatalogTag] as unknown as (new () => Container) | undefined;
+  if (!Ctor) {
+    throw new Error(`[@caperjs/solid] Unknown element <${tag}>. Known elements: ${Object.keys(catalog).join(', ')}.`);
+  }
+  return new Ctor();
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+import { version } from './version';
+
+export const VERSION = version;
+
+export * from './animated';
+export * from './AnimatedShow';
+export * from './asComponent';
+export * from './catalog';
+export * from './Composable';
+export * from './renderer';
+export * from './useTick';

package/src/renderer.test.ts

@@ -0,0 +1,272 @@
+import { Application, FlexContainer } from '@caperjs/core';
+import { Container, Graphics, Sprite, Text } from 'pixi.js';
+import { createRoot, createSignal } from 'solid-js';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { catalog } from './catalog';
+import { createElement, createTextNode, insert, insertNode, render, setProp, spread } from './renderer';
+
+/**
+ * FlexContainer and the flex re-measure workaround both read the Application
+ * singleton. Only the handful of members they touch are stubbed.
+ */
+function stubApplication() {
+  const ticker = { add: vi.fn(), remove: vi.fn(), addOnce: vi.fn() };
+  const layout = { update: vi.fn(), _updateSize: vi.fn(), updateLayout: vi.fn() };
+  (Application as any).instance = {
+    config: { useLayout: true },
+    ticker,
+    renderer: { layout },
+  };
+  return { ticker, layout };
+}
+
+let app: ReturnType<typeof stubApplication>;
+
+beforeEach(() => {
+  app = stubApplication();
+});
+
+afterEach(() => {
+  (Application as any).instance = undefined;
+});
+
+describe('createElement', () => {
+  it('constructs every catalog tag', () => {
+    expect(createElement('container')).toBeInstanceOf(Container);
+    expect(createElement('sprite')).toBeInstanceOf(Sprite);
+    expect(createElement('text')).toBeInstanceOf(Text);
+    expect(createElement('graphics')).toBeInstanceOf(Graphics);
+    expect(createElement('flexContainer')).toBeInstanceOf(FlexContainer);
+  });
+
+  it('throws on an unknown tag, listing the known ones', () => {
+    expect(() => createElement('nope')).toThrow(/Unknown element <nope>/);
+    for (const tag of Object.keys(catalog)) {
+      expect(() => createElement('nope')).toThrow(new RegExp(tag));
+    }
+  });
+
+  it('creates text with events off', () => {
+    expect(createElement('text').eventMode).toBe('none');
+  });
+});
+
+describe('insertNode / removeNode', () => {
+  it('appends when there is no anchor', () => {
+    const parent = createElement('container');
+    const a = createElement('sprite');
+    const b = createElement('sprite');
+    insertNode(parent, a);
+    insertNode(parent, b);
+    expect(parent.children).toEqual([a, b]);
+  });
+
+  it('inserts before the anchor', () => {
+    const parent = createElement('container');
+    const a = createElement('sprite');
+    const b = createElement('sprite');
+    const c = createElement('sprite');
+    insertNode(parent, a);
+    insertNode(parent, b);
+    insertNode(parent, c, b);
+    expect(parent.children).toEqual([a, c, b]);
+  });
+
+  it('schedules a flex re-measure when the parent is a FlexContainer', () => {
+    const parent = createElement('flexContainer');
+    const child = createElement('text');
+    insertNode(parent, child);
+
+    // FlexContainer defers its own layout pass through the ticker too, so drain
+    // everything that got queued rather than assuming a single callback.
+    expect(app.ticker.addOnce).toHaveBeenCalled();
+    expect(app.layout._updateSize).not.toHaveBeenCalled();
+    for (const [fn] of app.ticker.addOnce.mock.calls) fn();
+
+    expect(app.layout._updateSize).toHaveBeenCalledWith(parent);
+    expect(app.layout.updateLayout).toHaveBeenCalledWith(parent);
+  });
+
+  it('removes and destroys the child', () => {
+    const parent = createElement('container');
+    const child = createElement('container');
+    const grandchild = createElement('sprite');
+    insertNode(child, grandchild);
+    insertNode(parent, child);
+
+    // `removeNode` is not part of the exported runtime; it is reached through the
+    // reconciler, so drive it with a signal that swaps the child out.
+    const [show, setShow] = createSignal(true);
+    const holder = createElement('container');
+    createRoot(() => insert(holder, () => (show() ? child : null)));
+    expect(holder.children).toEqual([child]);
+
+    setShow(false);
+    expect(holder.children).toEqual([]);
+    expect(child.destroyed).toBe(true);
+    expect(grandchild.destroyed).toBe(true);
+  });
+});
+
+describe('setProperty', () => {
+  it('expands a number into both axes of a point prop', () => {
+    const node = createElement('sprite');
+    setProp(node, 'scale', 2);
+    expect(node.scale.x).toBe(2);
+    expect(node.scale.y).toBe(2);
+  });
+
+  it('accepts { x, y } objects', () => {
+    const node = createElement('sprite');
+    setProp(node, 'position', { x: 10, y: 20 });
+    setProp(node, 'scale', { x: 3, y: 4 });
+    setProp(node, 'pivot', { x: 5, y: 6 });
+    expect([node.x, node.y]).toEqual([10, 20]);
+    expect([node.scale.x, node.scale.y]).toEqual([3, 4]);
+    expect([node.pivot.x, node.pivot.y]).toEqual([5, 6]);
+  });
+
+  it('sets anchor on sprites and text', () => {
+    const sprite = createElement('sprite') as Sprite;
+    const text = createElement('text') as Text;
+    setProp(sprite, 'anchor', 0.5);
+    setProp(text, 'anchor', { x: 0, y: 1 });
+    expect([sprite.anchor.x, sprite.anchor.y]).toEqual([0.5, 0.5]);
+    expect([text.anchor.x, text.anchor.y]).toEqual([0, 1]);
+  });
+
+  it('passes unknown props straight through', () => {
+    const node = createElement('container');
+    setProp(node, 'alpha', 0.25);
+    setProp(node, 'visible', false);
+    setProp(node, 'x', 12);
+    expect(node.alpha).toBe(0.25);
+    expect(node.visible).toBe(false);
+    expect(node.x).toBe(12);
+  });
+
+  it('re-measures a flex child when a plain prop changes', () => {
+    const parent = createElement('flexContainer');
+    const child = createElement('text');
+    insertNode(parent, child);
+    app.layout._updateSize.mockClear();
+
+    setProp(child, 'text', 'hello');
+
+    expect(app.layout._updateSize).toHaveBeenCalledWith(parent);
+    expect(app.layout.updateLayout).toHaveBeenCalledWith(parent);
+  });
+
+  it('wires on* props as listeners and enables events', () => {
+    const node = createElement('text');
+    const first = vi.fn();
+    setProp(node, 'onPointerTap', first);
+
+    expect(node.listenerCount('pointertap')).toBe(1);
+    expect(node.eventMode).toBe('static');
+
+    node.emit('pointertap' as any, 'evt' as any);
+    expect(first).toHaveBeenCalledTimes(1);
+
+    const second = vi.fn();
+    setProp(node, 'onPointerTap', second, first);
+    expect(node.listenerCount('pointertap')).toBe(1);
+
+    node.emit('pointertap' as any, 'evt' as any);
+    expect(first).toHaveBeenCalledTimes(1);
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+
+  it('lets an explicit eventMode prop win over the text default', () => {
+    const node = createElement('text');
+    setProp(node, 'eventMode', 'static');
+    expect(node.eventMode).toBe('static');
+  });
+
+  describe('draw', () => {
+    it('invokes the callback with the graphics node', () => {
+      const node = createElement('graphics') as Graphics;
+      const draw = vi.fn();
+      setProp(node, 'draw', draw);
+      expect(draw).toHaveBeenCalledWith(node);
+    });
+
+    it('clears before re-running a changed callback', () => {
+      const node = createElement('graphics') as Graphics;
+      const clear = vi.spyOn(node, 'clear');
+      const first = vi.fn();
+      const second = vi.fn();
+
+      setProp(node, 'draw', first);
+      setProp(node, 'draw', second, first);
+
+      expect(clear).toHaveBeenCalledTimes(2);
+      expect(first).toHaveBeenCalledTimes(1);
+      expect(second).toHaveBeenCalledWith(node);
+    });
+
+    it('throws when the target is not a graphics node', () => {
+      const node = createElement('container');
+      expect(() => setProp(node, 'draw', () => {})).toThrow(/only valid on <graphics>/);
+    });
+  });
+});
+
+describe('text nodes', () => {
+  it('creates JSX text nodes with events off and updates them in place', () => {
+    const node = createTextNode('hello') as Text;
+    expect(node).toBeInstanceOf(Text);
+    expect(node.text).toBe('hello');
+    expect(node.eventMode).toBe('none');
+  });
+
+  it('distinguishes JSX text nodes from <text> elements', () => {
+    expect((createTextNode('hello') as any).__isTextNode).toBe(true);
+    expect((createElement('text') as any).__isTextNode).toBeUndefined();
+  });
+
+  it('replaces the text of an existing JSX text node rather than remounting', () => {
+    const parent = createElement('container');
+    const [label, setLabel] = createSignal('one');
+    createRoot(() => insert(parent, () => label()));
+
+    const node = parent.children[0] as Text;
+    expect(node.text).toBe('one');
+
+    setLabel('two');
+    expect(parent.children[0]).toBe(node);
+    expect(node.text).toBe('two');
+  });
+});
+
+describe('render', () => {
+  it('keeps props reactive and stops updating after dispose', () => {
+    const root = createElement('container');
+    const [alpha, setAlpha] = createSignal(0.25);
+
+    const dispose = render(() => {
+      const node = createElement('sprite');
+      spread(
+        node,
+        {
+          get alpha() {
+            return alpha();
+          },
+        },
+        true,
+      );
+      return node;
+    }, root);
+
+    const node = root.children[0] as Sprite;
+    expect(node.alpha).toBe(0.25);
+
+    setAlpha(0.5);
+    expect(node.alpha).toBe(0.5);
+
+    dispose();
+    setAlpha(1);
+    expect(node.alpha).toBe(0.5);
+  });
+});

package/src/renderer.ts

@@ -0,0 +1,155 @@
+// A SolidJS "universal renderer" whose host nodes are Pixi display objects.
+//
+// This file plays the role of framework internals, so raw Pixi is fine here.
+
+import {
+  Application,
+  FlexContainer,
+  resolveAnchor,
+  resolvePivot,
+  resolvePosition,
+  resolveScale,
+  resolveUnknownKeys,
+} from '@caperjs/core';
+import { Container, Graphics, Text } from 'pixi.js';
+import { createRenderer } from 'solid-js/universal';
+
+import { createCatalogNode } from './catalog';
+
+export type PixiNode = Container;
+
+/**
+ * Re-measure and relayout a FlexContainer child whose content just changed.
+ *
+ * Solid inserts a node first and sets `text` / `style` after, so yoga measures
+ * the child while it is still empty and caches a zero-width intrinsic size — the
+ * child then renders scaled to nothing. `FlexContainer.updateLayout()` alone
+ * doesn't fix it: `@pixi/layout` throttles its intrinsic-size pass to 100ms, and
+ * caper runs the layout system with `autoUpdate: false`, so nothing ever
+ * re-measures. Drive that pass directly instead.
+ */
+function invalidateFlexChild(node: any) {
+  const parent = node.parent;
+  if (!(parent instanceof FlexContainer)) return;
+  node.layout?.forceUpdate?.();
+  const layoutSystem = Application.getInstance().renderer.layout as any;
+  layoutSystem._updateSize(parent);
+  layoutSystem.updateLayout(parent);
+}
+
+const renderer = createRenderer<PixiNode>({
+  createElement(tag: string): PixiNode {
+    const node = createCatalogNode(tag);
+    // Text is decoration by default — opting into events is what `on*` props (or
+    // an explicit `eventMode` prop, applied after creation) are for.
+    if (node instanceof Text) node.eventMode = 'none';
+    return node;
+  },
+
+  createTextNode(value: string): PixiNode {
+    const node = new Text({ text: String(value) });
+    node.eventMode = 'none';
+    // Marks this as a JSX text node so `<text>` elements aren't mistaken for one.
+    (node as any).__isTextNode = true;
+    return node;
+  },
+
+  replaceText(node: PixiNode, value: string) {
+    (node as Text).text = String(value);
+  },
+
+  isTextNode(node: PixiNode) {
+    return node instanceof Text && (node as any).__isTextNode === true;
+  },
+
+  setProperty(node: any, name: string, value: any, prev?: any) {
+    if (name === 'draw') {
+      if (!(node instanceof Graphics)) {
+        throw new Error(
+          `[@caperjs/solid] The \`draw\` prop is only valid on <graphics>, received it on ${node?.constructor?.name}.`,
+        );
+      }
+      node.clear();
+      value?.(node);
+      return;
+    }
+
+    if (name.startsWith('on') && typeof value === 'function') {
+      const ev = name.slice(2).toLowerCase();
+      if (prev) node.off(ev, prev);
+      node.on(ev, value);
+      node.eventMode = 'static';
+      return;
+    }
+
+    // Point-like props go through the same resolvers `this.add.*` uses, so
+    // `scale={2}`, `scale={{ x, y }}` and `scale={[x, y]}` behave identically in
+    // JSX and in factory config.
+    switch (name) {
+      case 'position':
+        resolvePosition({ position: value }, node);
+        return;
+      case 'scale':
+        resolveScale({ scale: value }, node);
+        return;
+      case 'pivot':
+        resolvePivot(value, node);
+        return;
+      case 'anchor':
+        resolveAnchor(value, node);
+        return;
+    }
+
+    resolveUnknownKeys({ [name]: value }, node);
+    invalidateFlexChild(node);
+  },
+
+  insertNode(parent: PixiNode, node: PixiNode, anchor?: PixiNode) {
+    if (anchor) {
+      parent.addChildAt(node, parent.getChildIndex(anchor));
+    } else {
+      parent.addChild(node);
+    }
+
+    // Solid may set a node's props before inserting it, so re-measure on the next
+    // tick — by then the whole tree has been built and every prop is applied.
+    if (parent instanceof FlexContainer) {
+      Application.getInstance().ticker.addOnce(() => invalidateFlexChild(node));
+    }
+  },
+
+  removeNode(parent: PixiNode, node: PixiNode) {
+    parent.removeChild(node);
+    node.destroy({ children: true });
+  },
+
+  getParentNode(node: PixiNode) {
+    return node.parent ?? undefined;
+  },
+
+  getFirstChild(node: PixiNode) {
+    return node.children[0] as PixiNode | undefined;
+  },
+
+  getNextSibling(node: PixiNode) {
+    const parent = node.parent;
+    if (!parent) return undefined;
+    return parent.children[parent.getChildIndex(node) + 1] as PixiNode | undefined;
+  },
+});
+
+// The babel universal transform imports its runtime from this module.
+export const {
+  render,
+  effect,
+  memo,
+  createComponent,
+  createElement,
+  createTextNode,
+  insertNode,
+  insert,
+  spread,
+  setProp,
+  mergeProps,
+  use,
+} = renderer;

package/src/useTick.test.ts

@@ -0,0 +1,28 @@
+import { Application } from '@caperjs/core';
+import { createRoot } from 'solid-js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { useTick } from './useTick';
+
+afterEach(() => {
+  (Application as any).instance = undefined;
+});
+
+describe('useTick', () => {
+  it('adds the callback to the ticker and removes it on cleanup', () => {
+    const ticker = { add: vi.fn(), remove: vi.fn(), addOnce: vi.fn() };
+    (Application as any).instance = { config: {}, ticker };
+
+    const fn = vi.fn();
+    const dispose = createRoot((d) => {
+      useTick(fn);
+      return d;
+    });
+
+    expect(ticker.add).toHaveBeenCalledWith(fn);
+    expect(ticker.remove).not.toHaveBeenCalled();
+
+    dispose();
+    expect(ticker.remove).toHaveBeenCalledWith(fn);
+  });
+});