@canvas-commons/2d 0.2.0

package/src/lib/components/Icon.ts

@@ -0,0 +1,153 @@
+import {
+  ColorSignal,
+  DependencyContext,
+  PossibleColor,
+  SignalValue,
+  SimpleSignal,
+  TimingFunction,
+  isReactive,
+  threadable,
+  useLogger,
+} from '@canvas-commons/core';
+import {colorSignal, computed, initial, signal} from '../decorators';
+import {SVG, SVGProps} from './SVG';
+
+export interface IconProps extends Omit<SVGProps, 'svg'> {
+  /**
+   * {@inheritDoc Icon.icon}
+   */
+  icon: SignalValue<string>;
+
+  /**
+   * {@inheritDoc Icon.color}
+   */
+  color?: SignalValue<PossibleColor>;
+}
+
+const PLACEHOLDER_SVG =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24" fill="none"/></svg>';
+
+/**
+ * An Icon Component that provides easy access to over 150k icons.
+ * See https://icones.js.org/collection/all for all available Icons.
+ */
+export class Icon extends SVG {
+  private static iconSvgCache: Map<string, string> = new Map();
+  private static pendingFetches: Map<string, Promise<string>> = new Map();
+
+  /**
+   * The identifier of the icon.
+   *
+   * @remarks
+   * You can find identifiers on [Icônes](https://icones.js.org).
+   * They can look like this:
+   * * `mdi:language-typescript`
+   * * `ph:anchor-simple-bold`
+   * * `ph:activity-bold`
+   */
+  @signal()
+  declare public readonly icon: SimpleSignal<string, this>;
+
+  /**
+   * The color of the icon
+   *
+   * @remarks
+   * Provide the color in one of the following formats:
+   * * named color like `red`, `darkgray`, …
+   * * hexadecimal string with # like `#bada55`, `#141414`
+   *   Value can be either RGB or RGBA: `#bada55`, `#bada55aa` (latter is partially transparent)
+   *   The shorthand version (e.g. `#abc` for `#aabbcc` is also possible.)
+   *
+   * @defaultValue 'white'
+   */
+  @initial('white')
+  @colorSignal()
+  declare public readonly color: ColorSignal<this>;
+
+  public constructor(props: IconProps) {
+    super({
+      ...props,
+      svg: () => this.iconSvg(),
+    });
+  }
+
+  protected override collectAsyncResources(): void {
+    super.collectAsyncResources();
+    this.iconSvg();
+  }
+
+  @computed()
+  protected iconSvg(): string {
+    const iconId = this.icon();
+    const color = this.color().hex();
+    const cacheKey = `${iconId}::${color}`;
+
+    const cached = Icon.iconSvgCache.get(cacheKey);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    if (iconId === null || iconId === undefined) {
+      return PLACEHOLDER_SVG;
+    }
+
+    const fetchPromise = this.fetchIconSvg(iconId, color);
+    DependencyContext.collectPromise(fetchPromise);
+
+    return PLACEHOLDER_SVG;
+  }
+
+  private async fetchIconSvg(iconId: string, color: string): Promise<string> {
+    const cacheKey = `${iconId}::${color}`;
+
+    const cached = Icon.iconSvgCache.get(cacheKey);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const pending = Icon.pendingFetches.get(cacheKey);
+    if (pending !== undefined) {
+      return pending;
+    }
+
+    const iconPath = iconId.replace(':', '/');
+    const encodedColor = encodeURIComponent(color);
+    const url = `https://api.iconify.design/${iconPath}.svg?color=${encodedColor}`;
+
+    const fetchPromise = fetch(url)
+      .then(response => {
+        if (!response.ok) {
+          throw new Error(`Failed to fetch icon: ${iconId}`);
+        }
+        return response.text();
+      })
+      .then(svg => {
+        Icon.iconSvgCache.set(cacheKey, svg);
+        Icon.pendingFetches.delete(cacheKey);
+        return svg;
+      })
+      .catch(error => {
+        Icon.pendingFetches.delete(cacheKey);
+        useLogger().error(`Error fetching icon ${iconId}: ${error}`);
+        return PLACEHOLDER_SVG;
+      });
+
+    Icon.pendingFetches.set(cacheKey, fetchPromise);
+    return fetchPromise;
+  }
+
+  @threadable()
+  protected *tweenIcon(
+    value: SignalValue<string>,
+    time: number,
+    timingFunction: TimingFunction,
+  ) {
+    const newIconId = isReactive(value) ? value() : value;
+    const color = this.color().hex();
+
+    const newSvg: string = yield this.fetchIconSvg(newIconId, color);
+
+    yield* this.svg(newSvg, time, timingFunction);
+    this.icon.context.setter(newIconId);
+  }
+}

package/src/lib/components/Img.ts

@@ -0,0 +1,328 @@
+import {
+  BBox,
+  Color,
+  DependencyContext,
+  DetailedError,
+  PossibleVector2,
+  SerializedVector2,
+  SignalValue,
+  SimpleSignal,
+  TimingFunction,
+  Vector2,
+  easeInOutCubic,
+  isReactive,
+  threadable,
+  tween,
+  useLogger,
+  viaProxy,
+} from '@canvas-commons/core';
+import {computed, initial, nodeName, signal} from '../decorators';
+import {DesiredLength} from '../partials';
+import {drawImage} from '../utils';
+import {Rect, RectProps} from './Rect';
+import imageWithoutSource from './__logs__/image-without-source';
+
+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 '@canvas-commons/2d';
+ * import {all, waitFor} from '@canvas-commons/core';
+ * import {createRef} from '@canvas-commons/core';
+ * import {makeScene2D} from '@canvas-commons/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('canvas-commons: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()
+  declare public 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()
+  declare public 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()
+  declare public 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 rawSrc = this.src();
+    let src = '';
+    let key = '';
+    if (rawSrc) {
+      key = viaProxy(rawSrc);
+      const url = new URL(key, window.location.origin);
+      if (url.origin === window.location.origin) {
+        const hash = this.view().assetHash();
+        url.searchParams.set('asset-hash', hash);
+      }
+      src = url.toString();
+    }
+
+    let image = Img.pool[key];
+    if (!image) {
+      image = document.createElement('img');
+      image.crossOrigin = 'anonymous';
+      image.src = src;
+      Img.pool[key] = image;
+    }
+
+    if (!image.complete) {
+      DependencyContext.collectPromise(
+        new Promise((resolve, reject) => {
+          image.addEventListener('load', resolve);
+          image.addEventListener('error', () =>
+            reject(
+              new DetailedError({
+                message: `Failed to load an image`,
+                remarks: `\
+The <code>src</code> property was set to:
+<pre><code>${rawSrc}</code></pre>
+...which resolved to the following url:
+<pre><code>${src}</code></pre>
+Make sure that source is correct and that the image exists.<br/>
+<a target='_blank' href='https://canvascommons.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 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());
+    }
+
+    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,
+    });
+  }
+
+  @threadable()
+  protected *tweenSrc(
+    value: SignalValue<string>,
+    time: number,
+    timingFunction: TimingFunction = easeInOutCubic,
+  ) {
+    const newSrc = isReactive(value) ? value() : value;
+    const currentOpacity = this.opacity();
+    const halfTime = time / 2;
+    yield* tween(halfTime, v => {
+      this.opacity(currentOpacity * (1 - timingFunction(v)));
+    });
+    this.src.context.setter(newSrc);
+    yield* tween(halfTime, v => {
+      this.opacity(currentOpacity * timingFunction(v));
+    });
+  }
+
+  protected override collectAsyncResources() {
+    super.collectAsyncResources();
+    this.image();
+  }
+}

package/src/lib/components/Knot.ts

@@ -0,0 +1,156 @@
+import {
+  PossibleVector2,
+  Signal,
+  SignalValue,
+  Vector2,
+  Vector2Signal,
+} from '@canvas-commons/core';
+import {KnotInfo} from '../curves';
+import {
+  cloneable,
+  compound,
+  computed,
+  initial,
+  parser,
+  signal,
+  wrapper,
+} from '../decorators';
+import {Node, NodeProps} 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()
+  declare public 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()
+  declare public 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'})
+  declare public 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: startHandle.transformAsPoint(this.localToParent()),
+      endHandle: endHandle.transformAsPoint(this.localToParent()),
+      auto: {start: this.startHandleAuto(), end: this.endHandleAuto()},
+    };
+  }
+
+  private getDefaultEndHandle() {
+    return this.startHandle().flipped;
+  }
+
+  private getDefaultStartHandle() {
+    return this.endHandle().flipped;
+  }
+}