@twick/2d 0.11.0

package/src/lib/components/Img.ts

@@ -0,0 +1,319 @@
+import type {
+  PossibleVector2,
+  SerializedVector2,
+  SignalValue,
+  SimpleSignal,
+} from '@twick/core';
+import {
+  BBox,
+  Color,
+  DependencyContext,
+  DetailedError,
+  Vector2,
+  useLogger,
+} from '@twick/core';
+import {computed, initial, nodeName, signal} from '../decorators';
+import type {DesiredLength} from '../partials';
+import {drawImage} from '../utils';
+import type {RectProps} from './Rect';
+import {Rect} from './Rect';
+
+const imageWithoutSource = `
+The image won't be visible unless you specify a source:
+
+\`\`\`tsx
+import myImage from './example.png';
+// ...
+<Img src={myImage} />;
+\`\`\`
+
+If you did this intentionally, and don't want to see this warning, set the \`src\`
+property to \`null\`:
+
+\`\`\`tsx
+<Img src={null} />
+\`\`\`
+
+[Learn more](https://motioncanvas.io/docs/media#images) about working with
+images.
+`;
+
+export interface ImgProps extends RectProps {
+  /**
+   * {@inheritDoc Img.src}
+   */
+  src?: SignalValue<string | null>;
+  /**
+   * {@inheritDoc Img.alpha}
+   */
+  alpha?: SignalValue<number>;
+  /**
+   * {@inheritDoc Img.smoothing}
+   */
+  smoothing?: SignalValue<boolean>;
+}
+
+/**
+ * A node for displaying images.
+ *
+ * @preview
+ * ```tsx editor
+ * import {Img} from '@twick/2d';
+ * import {all, waitFor} from '@twick/core';
+ * import {createRef} from '@twick/core';
+ * import {makeScene2D} from '@twick/2d';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const ref = createRef<Img>();
+ *   yield view.add(
+ *     <Img
+ *       ref={ref}
+ *       src="https://images.unsplash.com/photo-1679218407381-a6f1660d60e9"
+ *       width={300}
+ *       radius={20}
+ *     />,
+ *   );
+ *
+ *   // set the background using the color sampled from the image:
+ *   ref().fill(ref().getColorAtPoint(0));
+ *
+ *   yield* all(
+ *     ref().size([100, 100], 1).to([300, null], 1),
+ *     ref().radius(50, 1).to(20, 1),
+ *     ref().alpha(0, 1).to(1, 1),
+ *   );
+ *   yield* waitFor(0.5);
+ * });
+ * ```
+ */
+@nodeName('Img')
+export class Img extends Rect {
+  private static pool: Record<string, HTMLImageElement> = {};
+
+  static {
+    if (import.meta.hot) {
+      import.meta.hot.on('twick:assets', ({urls}) => {
+        for (const url of urls) {
+          if (Img.pool[url]) {
+            delete Img.pool[url];
+          }
+        }
+      });
+    }
+  }
+
+  /**
+   * The source of this image.
+   *
+   * @example
+   * Using a local image:
+   * ```tsx
+   * import image from './example.png';
+   * // ...
+   * view.add(<Img src={image} />)
+   * ```
+   * Loading an image from the internet:
+   * ```tsx
+   * view.add(<Img src="https://example.com/image.png" />)
+   * ```
+   */
+  @signal()
+  public declare readonly src: SimpleSignal<string, this>;
+
+  /**
+   * The alpha value of this image.
+   *
+   * @remarks
+   * Unlike opacity, the alpha value affects only the image itself, leaving the
+   * fill, stroke, and children intact.
+   */
+  @initial(1)
+  @signal()
+  public declare readonly alpha: SimpleSignal<number, this>;
+
+  /**
+   * Whether the image should be smoothed.
+   *
+   * @remarks
+   * When disabled, the image will be scaled using the nearest neighbor
+   * interpolation with no smoothing. The resulting image will appear pixelated.
+   *
+   * @defaultValue true
+   */
+  @initial(true)
+  @signal()
+  public declare readonly smoothing: SimpleSignal<boolean, this>;
+
+  public constructor(props: ImgProps) {
+    super(props);
+    if (!('src' in props)) {
+      useLogger().warn({
+        message: 'No source specified for the image',
+        remarks: imageWithoutSource,
+        inspect: this.key,
+      });
+    }
+  }
+
+  protected override desiredSize(): SerializedVector2<DesiredLength> {
+    const custom = super.desiredSize();
+    if (custom.x === null && custom.y === null) {
+      const image = this.image();
+      return {
+        x: image.naturalWidth,
+        y: image.naturalHeight,
+      };
+    }
+
+    return custom;
+  }
+
+  @computed()
+  protected image(): HTMLImageElement {
+    const src = this.src();
+    const url = new URL(src, window.location.origin);
+    if (url.origin === window.location.origin) {
+      const hash = this.view().assetHash();
+      url.searchParams.set('asset-hash', hash);
+    }
+
+    let image = Img.pool[src];
+    if (!image) {
+      image = document.createElement('img');
+      image.crossOrigin = 'anonymous';
+      image.src = src;
+      Img.pool[src] = image;
+    }
+
+    if (!image.complete) {
+      DependencyContext.collectPromise(
+        new Promise((resolve, reject) => {
+          image.addEventListener('load', resolve);
+          image.addEventListener('error', () =>
+            // TODO: example for error handling inside DependencyContext (this shouldn't be UI specific)
+            reject(
+              new DetailedError({
+                message: `Failed to load an image`,
+                remarks: `\
+The <code>src</code> property was set to:
+<pre><code>${src}</code></pre>
+Make sure that source is correct and that the image exists.<br/>
+<a target='_blank' href='https://motioncanvas.io/docs/media#images'>Learn more</a>
+about working with images.`,
+                inspect: this.key,
+              }),
+            ),
+          );
+        }),
+      );
+    }
+
+    return image;
+  }
+
+  @computed()
+  protected imageCanvas(): CanvasRenderingContext2D {
+    const canvas = document
+      .createElement('canvas')
+      .getContext('2d', {willReadFrequently: true});
+    if (!canvas) {
+      throw new Error('Could not create an image canvas');
+    }
+
+    return canvas;
+  }
+
+  @computed()
+  protected filledImageCanvas() {
+    const context = this.imageCanvas();
+    const image = this.image();
+    context.canvas.width = image.naturalWidth;
+    context.canvas.height = image.naturalHeight;
+    context.imageSmoothingEnabled = this.smoothing();
+    context.drawImage(image, 0, 0);
+
+    return context;
+  }
+
+  protected override async draw(context: CanvasRenderingContext2D) {
+    this.drawShape(context);
+    const alpha = this.alpha();
+    if (alpha > 0) {
+      const box = BBox.fromSizeCentered(this.computedSize());
+      context.save();
+      context.clip(this.getPath());
+      if (alpha < 1) {
+        context.globalAlpha *= alpha;
+      }
+      context.imageSmoothingEnabled = this.smoothing();
+      drawImage(context, this.image(), box);
+      context.restore();
+    }
+
+    if (this.clip()) {
+      context.clip(this.getPath());
+    }
+
+    await this.drawChildren(context);
+  }
+
+  protected override applyFlex() {
+    super.applyFlex();
+    const image = this.image();
+    this.element.style.aspectRatio = (
+      this.ratio() ?? image.naturalWidth / image.naturalHeight
+    ).toString();
+  }
+
+  /**
+   * Get color of the image at the given position.
+   *
+   * @param position - The position in local space at which to sample the color.
+   */
+  public getColorAtPoint(position: PossibleVector2): Color {
+    const size = this.computedSize();
+    const naturalSize = this.naturalSize();
+
+    const pixelPosition = new Vector2(position)
+      .add(this.computedSize().scale(0.5))
+      .mul(naturalSize.div(size).safe);
+
+    return this.getPixelColor(pixelPosition);
+  }
+
+  /**
+   * The natural size of this image.
+   *
+   * @remarks
+   * The natural size is the size of the source image unaffected by the size
+   * and scale properties.
+   */
+  @computed()
+  public naturalSize() {
+    const image = this.image();
+    return new Vector2(image.naturalWidth, image.naturalHeight);
+  }
+
+  /**
+   * Get color of the image at the given pixel.
+   *
+   * @param position - The pixel's position.
+   */
+  public getPixelColor(position: PossibleVector2): Color {
+    const context = this.filledImageCanvas();
+    const vector = new Vector2(position);
+    const data = context.getImageData(vector.x, vector.y, 1, 1).data;
+
+    return new Color({
+      r: data[0],
+      g: data[1],
+      b: data[2],
+      a: data[3] / 255,
+    });
+  }
+
+  protected override collectAsyncResources() {
+    super.collectAsyncResources();
+    this.image();
+  }
+}

package/src/lib/components/Knot.ts

@@ -0,0 +1,157 @@
+import type {
+  PossibleVector2,
+  Signal,
+  SignalValue,
+  Vector2Signal,
+} from '@twick/core';
+import {transformVectorAsPoint, Vector2} from '@twick/core';
+import type {KnotInfo} from '../curves';
+import {
+  cloneable,
+  compound,
+  computed,
+  initial,
+  parser,
+  signal,
+  wrapper,
+} from '../decorators';
+import type {NodeProps} from './Node';
+import {Node} from './Node';
+
+export interface KnotProps extends NodeProps {
+  /**
+   * {@inheritDoc Knot.startHandle}
+   */
+  startHandle?: SignalValue<PossibleVector2>;
+  /**
+   * {@inheritDoc Knot.endHandle}
+   */
+  endHandle?: SignalValue<PossibleVector2>;
+  /**
+   * {@inheritDoc Knot.auto}
+   */
+  auto?: SignalValue<PossibleKnotAuto>;
+  startHandleAuto?: SignalValue<number>;
+  endHandleAuto?: SignalValue<number>;
+}
+
+export type KnotAuto = {startHandle: number; endHandle: number};
+export type PossibleKnotAuto = KnotAuto | number | [number, number];
+export type KnotAutoSignal<TOwner> = Signal<
+  PossibleKnotAuto,
+  KnotAuto,
+  TOwner
+> & {
+  endHandle: Signal<number, number, TOwner>;
+  startHandle: Signal<number, number, TOwner>;
+};
+
+/**
+ * A node representing a knot of a {@link Spline}.
+ */
+export class Knot extends Node {
+  /**
+   * The position of the knot's start handle. The position is provided relative
+   * to the knot's position.
+   *
+   * @remarks
+   * By default, the position of the start handle will be the mirrored position
+   * of the {@link endHandle}.
+   *
+   * If neither an end handle nor a start handle is provided, the positions of
+   * the handles gets calculated automatically to create smooth curve through
+   * the knot. The smoothness of the resulting curve can be controlled via the
+   * {@link Spline.smoothness} property.
+   *
+   * It is also possible to blend between a user-defined position and the
+   * auto-calculated position by using the {@link auto} property.
+   *
+   * @defaultValue Mirrored position of the endHandle.
+   */
+  @wrapper(Vector2)
+  @signal()
+  public declare readonly startHandle: Vector2Signal<this>;
+
+  /**
+   * The position of the knot's end handle. The position is provided relative
+   * to the knot's position.
+   *
+   * @remarks
+   * By default, the position of the end handle will be the mirrored position
+   * of the {@link startHandle}.
+   *
+   * If neither an end handle nor a start handle is provided, the positions of
+   * the handles gets calculated automatically to create smooth curve through
+   * the knot. The smoothness of the resulting curve can be controlled via the
+   * {@link Spline.smoothness} property.
+   *
+   * It is also possible to blend between a user-defined position and the
+   * auto-calculated position by using the {@link auto} property.
+   *
+   * @defaultValue Mirrored position of the startHandle.
+   */
+  @wrapper(Vector2)
+  @signal()
+  public declare readonly endHandle: Vector2Signal<this>;
+
+  /**
+   * How much to blend between the user-provided handles and the auto-calculated
+   * handles.
+   *
+   * @remarks
+   * This property has no effect if no explicit handles are provided for the
+   * knot.
+   *
+   * @defaultValue 0
+   */
+  @cloneable(false)
+  @initial(() => ({startHandle: 0, endHandle: 0}))
+  @parser((value: PossibleKnotAuto) => {
+    if (typeof value === 'object' && !Array.isArray(value)) {
+      return value;
+    }
+    if (typeof value === 'number') {
+      value = [value, value];
+    }
+    return {startHandle: value[0], endHandle: value[1]};
+  })
+  @compound({startHandle: 'startHandleAuto', endHandle: 'endHandleAuto'})
+  public declare readonly auto: KnotAutoSignal<this>;
+  public get startHandleAuto() {
+    return this.auto.startHandle;
+  }
+  public get endHandleAuto() {
+    return this.auto.endHandle;
+  }
+
+  public constructor(props: KnotProps) {
+    super(
+      props.startHandle === undefined && props.endHandle === undefined
+        ? {auto: 1, ...props}
+        : props,
+    );
+  }
+
+  @computed()
+  public points(): KnotInfo {
+    const hasExplicitHandles =
+      !this.startHandle.isInitial() || !this.endHandle.isInitial();
+    const startHandle = hasExplicitHandles ? this.startHandle() : Vector2.zero;
+    const endHandle = hasExplicitHandles ? this.endHandle() : Vector2.zero;
+
+    return {
+      position: this.position(),
+      startHandle: transformVectorAsPoint(startHandle, this.localToParent()),
+      endHandle: transformVectorAsPoint(endHandle, this.localToParent()),
+      auto: {start: this.startHandleAuto(), end: this.endHandleAuto()},
+    };
+  }
+
+  private getDefaultEndHandle() {
+    return this.startHandle().flipped;
+  }
+
+  private getDefaultStartHandle() {
+    return this.endHandle().flipped;
+  }
+}

package/src/lib/components/Latex.ts

@@ -0,0 +1,122 @@
+import type {SignalValue, SimpleSignal} from '@twick/core';
+import {DependencyContext, useLogger} from '@twick/core';
+import type {LiteAdaptor} from 'mathjax-full/js/adaptors/liteAdaptor';
+import {liteAdaptor} from 'mathjax-full/js/adaptors/liteAdaptor';
+import type {MathDocument} from 'mathjax-full/js/core/MathDocument';
+import {RegisterHTMLHandler} from 'mathjax-full/js/handlers/html';
+import {TeX} from 'mathjax-full/js/input/tex';
+import {AllPackages} from 'mathjax-full/js/input/tex/AllPackages';
+import {mathjax} from 'mathjax-full/js/mathjax';
+import {SVG} from 'mathjax-full/js/output/svg';
+import type {OptionList} from 'mathjax-full/js/util/Options';
+import {initial, signal} from '../decorators';
+import type {ImgProps} from './Img';
+import {Img} from './Img';
+
+export interface LatexProps extends ImgProps {
+  tex?: SignalValue<string>;
+  renderProps?: SignalValue<OptionList>;
+}
+
+/**
+ * A node for rendering equations with LaTeX.
+ *
+ * @preview
+ * ```tsx editor
+ * import {Latex, makeScene2D} from '@twick/2d';
+ *
+ * export default makeScene2D(function* (view) {
+ *   view.add(
+ *     <Latex
+ *       // Note how this uses \color to set the color.
+ *       tex="{\color{white} ax^2+bx+c=0 \implies x=\frac{-b \pm \sqrt{b^2-4ac}}{2a}}"
+ *       width={600} // height and width can calculate based on each other
+ *     />,
+ *   );
+ * });
+ * ```
+ */
+export class Latex extends Img {
+  private static svgContentsPool: Record<string, string> = {};
+  private static mathJaxInitialized = false;
+  private static adaptor: LiteAdaptor;
+  private static jaxDocument: MathDocument<unknown, unknown, unknown>;
+
+  private static initializeMathJax() {
+    if (this.mathJaxInitialized) {
+      return;
+    }
+    this.adaptor = liteAdaptor();
+    RegisterHTMLHandler(this.adaptor);
+    this.jaxDocument = mathjax.document('', {
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      InputJax: new TeX({packages: AllPackages}),
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      OutputJax: new SVG({fontCache: 'local'}),
+    });
+    this.mathJaxInitialized = true;
+  }
+
+  private readonly imageElement = document.createElement('img');
+
+  @initial({})
+  @signal()
+  public declare readonly options: SimpleSignal<OptionList, this>;
+
+  @signal()
+  public declare readonly tex: SimpleSignal<string, this>;
+
+  public constructor(props: LatexProps) {
+    super({...props, src: null});
+    Latex.initializeMathJax();
+  }
+
+  protected override image(): HTMLImageElement {
+    // Render props may change the look of the TeX, so we need to cache both
+    // source and render props together.
+    const src = `${this.tex()}::${JSON.stringify(this.options())}`;
+    if (Latex.svgContentsPool[src]) {
+      this.imageElement.src = Latex.svgContentsPool[src];
+      if (!this.imageElement.complete) {
+        DependencyContext.collectPromise(
+          new Promise((resolve, reject) => {
+            this.imageElement.addEventListener('load', resolve);
+            this.imageElement.addEventListener('error', reject);
+          }),
+        );
+      }
+      return this.imageElement;
+    }
+
+    // Convert to TeX, look for any errors
+    const tex = this.tex();
+    const svg = Latex.adaptor.innerHTML(
+      Latex.jaxDocument.convert(tex, this.options()) as any,
+    );
+    if (svg.includes('data-mjx-error')) {
+      const errors = svg.match(/data-mjx-error="(.*?)"/);
+      if (errors && errors.length > 0) {
+        useLogger().error(`Invalid MathJax: ${errors[1]}`);
+      }
+    }
+
+    // Encode to raw base64 image format
+    const text = `data:image/svg+xml;base64,${btoa(
+      `<?xml version="1.0" encoding="UTF-8" standalone="no" ?>\n${svg}`,
+    )}`;
+    Latex.svgContentsPool[src] = text;
+    const image = document.createElement('img');
+    image.src = text;
+    image.src = text;
+    if (!image.complete) {
+      DependencyContext.collectPromise(
+        new Promise((resolve, reject) => {
+          image.addEventListener('load', resolve);
+          image.addEventListener('error', reject);
+        }),
+      );
+    }
+
+    return image;
+  }
+}