@canvas-commons/2d 0.2.0

package/src/lib/components/Shape.ts

@@ -0,0 +1,322 @@
+import {
+  BBox,
+  SignalValue,
+  SimpleSignal,
+  createSignal,
+  easeOutExpo,
+  linear,
+  map,
+  threadable,
+  useRandom,
+} from '@canvas-commons/core';
+import {computed, initial, nodeName, signal} from '../decorators';
+import {
+  CanvasStyleSignal,
+  canvasStyleSignal,
+} from '../decorators/canvasStyleSignal';
+import {PossibleCanvasStyle, RoughFillStyle} from '../partials';
+import {createRoughConfig, drawRoughPath, resolveCanvasStyle} from '../utils';
+import {Layout, LayoutProps} from './Layout';
+
+export interface ShapeProps extends LayoutProps {
+  fill?: SignalValue<PossibleCanvasStyle>;
+  stroke?: SignalValue<PossibleCanvasStyle>;
+  strokeFirst?: SignalValue<boolean>;
+  lineWidth?: SignalValue<number>;
+  lineJoin?: SignalValue<CanvasLineJoin>;
+  lineCap?: SignalValue<CanvasLineCap>;
+  lineDash?: SignalValue<number[]>;
+  lineDashOffset?: SignalValue<number>;
+  antialiased?: SignalValue<boolean>;
+
+  /**
+   * Enable rough.js rendering.
+   */
+  rough?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc RoughConfig.roughness}
+   */
+  roughness?: SignalValue<number>;
+  /**
+   * {@inheritDoc RoughConfig.bowing}
+   */
+  bowing?: SignalValue<number>;
+  /**
+   * {@inheritDoc RoughConfig.fillStyle}
+   */
+  roughFillStyle?: SignalValue<RoughFillStyle>;
+  /**
+   * {@inheritDoc RoughConfig.fillWeight}
+   */
+  roughFillWeight?: SignalValue<number>;
+  /**
+   * {@inheritDoc RoughConfig.hachureAngle}
+   */
+  roughHachureAngle?: SignalValue<number>;
+  /**
+   * {@inheritDoc RoughConfig.hachureGap}
+   */
+  roughHachureGap?: SignalValue<number>;
+  /**
+   * {@inheritDoc RoughConfig.seed}
+   */
+  roughSeed?: SignalValue<number>;
+  /**
+   * {@inheritDoc RoughConfig.disableMultiStroke}
+   */
+  roughDisableMultiStroke?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc RoughConfig.disableMultiStrokeFill}
+   */
+  roughDisableMultiStrokeFill?: SignalValue<boolean>;
+}
+
+@nodeName('Shape')
+export abstract class Shape extends Layout {
+  @canvasStyleSignal()
+  declare public readonly fill: CanvasStyleSignal<this>;
+  @canvasStyleSignal()
+  declare public readonly stroke: CanvasStyleSignal<this>;
+  @initial(false)
+  @signal()
+  declare public readonly strokeFirst: SimpleSignal<boolean, this>;
+  @initial(0)
+  @signal()
+  declare public readonly lineWidth: SimpleSignal<number, this>;
+  @initial('miter')
+  @signal()
+  declare public readonly lineJoin: SimpleSignal<CanvasLineJoin, this>;
+  @initial('butt')
+  @signal()
+  declare public readonly lineCap: SimpleSignal<CanvasLineCap, this>;
+  @initial([])
+  @signal()
+  declare public readonly lineDash: SimpleSignal<number[], this>;
+  @initial(0)
+  @signal()
+  declare public readonly lineDashOffset: SimpleSignal<number, this>;
+  @initial(true)
+  @signal()
+  declare public readonly antialiased: SimpleSignal<boolean, this>;
+
+  // Rough.js signals
+  /**
+   * Enable rough.js rendering.
+   */
+  @initial(false)
+  @signal()
+  declare public readonly rough: SimpleSignal<boolean, this>;
+  /**
+   * {@inheritDoc RoughConfig.roughness}
+   */
+  @initial(1)
+  @signal()
+  declare public readonly roughness: SimpleSignal<number, this>;
+  /**
+   * {@inheritDoc RoughConfig.bowing}
+   */
+  @initial(1)
+  @signal()
+  declare public readonly bowing: SimpleSignal<number, this>;
+  /**
+   * {@inheritDoc RoughConfig.fillStyle}
+   */
+  @initial('hachure')
+  @signal()
+  declare public readonly roughFillStyle: SimpleSignal<RoughFillStyle, this>;
+  /**
+   * {@inheritDoc RoughConfig.fillWeight}
+   */
+  @signal()
+  declare public readonly roughFillWeight: SimpleSignal<
+    number | undefined,
+    this
+  >;
+  /**
+   * {@inheritDoc RoughConfig.hachureAngle}
+   */
+  @initial(-41)
+  @signal()
+  declare public readonly roughHachureAngle: SimpleSignal<number, this>;
+  /**
+   * {@inheritDoc RoughConfig.hachureGap}
+   */
+  @initial(4)
+  @signal()
+  declare public readonly roughHachureGap: SimpleSignal<number, this>;
+  /**
+   * {@inheritDoc RoughConfig.seed}
+   */
+  @signal()
+  declare public readonly roughSeed: SimpleSignal<number | undefined, this>;
+  /**
+   * {@inheritDoc RoughConfig.disableMultiStroke}
+   */
+  @initial(false)
+  @signal()
+  declare public readonly roughDisableMultiStroke: SimpleSignal<boolean, this>;
+  /**
+   * {@inheritDoc RoughConfig.disableMultiStrokeFill}
+   */
+  @initial(false)
+  @signal()
+  declare public readonly roughDisableMultiStrokeFill: SimpleSignal<
+    boolean,
+    this
+  >;
+
+  protected readonly rippleStrength = createSignal<number, this>(0);
+
+  @computed()
+  protected rippleSize() {
+    return easeOutExpo(this.rippleStrength(), 0, 50);
+  }
+
+  public constructor(props: ShapeProps) {
+    super(props);
+    if (props.roughSeed === undefined) {
+      this.roughSeed(useRandom().nextInt(0, Number.MAX_SAFE_INTEGER));
+    }
+  }
+
+  protected applyText(context: CanvasRenderingContext2D) {
+    context.direction = this.textDirection();
+    this.element.dir = this.textDirection();
+  }
+
+  protected applyStyle(context: CanvasRenderingContext2D) {
+    context.fillStyle = resolveCanvasStyle(this.fill(), context);
+    context.strokeStyle = resolveCanvasStyle(this.stroke(), context);
+    context.lineWidth = this.lineWidth();
+    context.lineJoin = this.lineJoin();
+    context.lineCap = this.lineCap();
+    context.setLineDash(this.lineDash());
+    context.lineDashOffset = this.lineDashOffset();
+    if (!this.antialiased()) {
+      // from https://stackoverflow.com/a/68372384
+      context.filter =
+        'url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxmaWx0ZXIgaWQ9ImZpbHRlciIgeD0iMCIgeT0iMCIgd2lkdGg9IjEwMCUiIGhlaWdodD0iMTAwJSIgY29sb3ItaW50ZXJwb2xhdGlvbi1maWx0ZXJzPSJzUkdCIj48ZmVDb21wb25lbnRUcmFuc2Zlcj48ZmVGdW5jUiB0eXBlPSJpZGVudGl0eSIvPjxmZUZ1bmNHIHR5cGU9ImlkZW50aXR5Ii8+PGZlRnVuY0IgdHlwZT0iaWRlbnRpdHkiLz48ZmVGdW5jQSB0eXBlPSJkaXNjcmV0ZSIgdGFibGVWYWx1ZXM9IjAgMSIvPjwvZmVDb21wb25lbnRUcmFuc2Zlcj48L2ZpbHRlcj48L3N2Zz4=#filter)';
+    }
+  }
+
+  protected override draw(context: CanvasRenderingContext2D) {
+    this.drawShape(context);
+    if (this.clip()) {
+      context.clip(this.getPath());
+    }
+    this.drawChildren(context);
+  }
+
+  protected drawShape(context: CanvasRenderingContext2D) {
+    if (this.rough()) {
+      this.drawShapeRough(context);
+    } else {
+      const path = this.getPath();
+      const hasStroke = this.lineWidth() > 0 && this.stroke() !== null;
+      const hasFill = this.fill() !== null;
+      context.save();
+      this.applyStyle(context);
+      this.drawRipple(context);
+      if (this.strokeFirst()) {
+        hasStroke && context.stroke(path);
+        hasFill && context.fill(path);
+      } else {
+        hasFill && context.fill(path);
+        hasStroke && context.stroke(path);
+      }
+      context.restore();
+    }
+  }
+
+  protected drawShapeRough(context: CanvasRenderingContext2D) {
+    const pathData = this.getPathData();
+    if (!pathData) {
+      return;
+    }
+
+    context.save();
+
+    if (!this.antialiased()) {
+      context.filter =
+        'url(data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjxmaWx0ZXIgaWQ9ImZpbHRlciIgeD0iMCIgeT0iMCIgd2lkdGg9IjEwMCUiIGhlaWdodD0iMTAwJSIgY29sb3ItaW50ZXJwb2xhdGlvbi1maWx0ZXJzPSJzUkdCIj48ZmVDb21wb25lbnRUcmFuc2Zlcj48ZmVGdW5jUiB0eXBlPSJpZGVudGl0eSIvPjxmZUZ1bmNHIHR5cGU9ImlkZW50aXR5Ii8+PGZlRnVuY0IgdHlwZT0iaWRlbnRpdHkiLz48ZmVGdW5jQSB0eXBlPSJkaXNjcmV0ZSIgdGFibGVWYWx1ZXM9IjAgMSIvPjwvZmVDb21wb25lbnRUcmFuc2Zlcj48L2ZpbHRlcj48L3N2Zz4=#filter)';
+    }
+
+    const seed = this.roughSeed();
+    if (seed === undefined) {
+      context.restore();
+      return;
+    }
+
+    const roughConfig = createRoughConfig(
+      this.roughness(),
+      this.bowing(),
+      this.roughFillStyle(),
+      this.roughFillWeight(),
+      this.roughHachureAngle(),
+      this.roughHachureGap(),
+      seed,
+      this.roughDisableMultiStroke(),
+      this.roughDisableMultiStrokeFill(),
+    );
+
+    drawRoughPath(
+      context,
+      pathData,
+      roughConfig,
+      this.fill(),
+      this.stroke(),
+      this.lineWidth(),
+    );
+
+    context.restore();
+  }
+
+  protected override getCacheBBox(): BBox {
+    return super.getCacheBBox().expand(this.lineWidth() / 2);
+  }
+
+  @computed()
+  protected getPath(): Path2D {
+    return new Path2D();
+  }
+
+  /**
+   * Get the SVG path data string for this shape.
+   *
+   * @remarks
+   * This method returns an SVG path data string that represents the shape's
+   * geometry. The default implementation returns an empty string. Subclasses
+   * should override this method to provide their actual path data.
+   *
+   * The path data can be used to create Path2D objects, passed to Rough.js,
+   * or used for SVG export.
+   *
+   * @returns An SVG path data string (e.g., "M 0 0 L 100 100 Z")
+   */
+  @computed()
+  protected getPathData(): string {
+    return '';
+  }
+
+  protected getRipplePath(): Path2D {
+    return new Path2D();
+  }
+
+  protected drawRipple(context: CanvasRenderingContext2D) {
+    const rippleStrength = this.rippleStrength();
+    if (rippleStrength > 0) {
+      const ripplePath = this.getRipplePath();
+      context.save();
+      context.globalAlpha *= map(0.54, 0, rippleStrength);
+      context.fill(ripplePath);
+      context.restore();
+    }
+  }
+
+  @threadable()
+  public *ripple(duration = 1) {
+    this.rippleStrength(0);
+    yield* this.rippleStrength(1, duration, linear);
+    this.rippleStrength(0);
+  }
+}

package/src/lib/components/Spline.ts

@@ -0,0 +1,318 @@
+import {
+  BBox,
+  PossibleVector2,
+  SerializedVector2,
+  SignalValue,
+  SimpleSignal,
+  Vector2,
+  unwrap,
+  useLogger,
+} from '@canvas-commons/core';
+import {
+  CubicBezierSegment,
+  CurveProfile,
+  KnotInfo,
+  getBezierSplineProfile,
+} from '../curves';
+import {PolynomialSegment} from '../curves/PolynomialSegment';
+import {computed, initial, signal} from '../decorators';
+import {DesiredLength} from '../partials';
+import {
+  arc,
+  bezierCurveTo,
+  drawLine,
+  drawPivot,
+  lineTo,
+  moveTo,
+  quadraticCurveTo,
+} from '../utils';
+import splineWithInsufficientKnots from './__logs__/spline-with-insufficient-knots';
+import {Curve, CurveProps} from './Curve';
+import {Knot} from './Knot';
+import {Node} from './Node';
+
+export interface SplineProps extends CurveProps {
+  /**
+   * {@inheritDoc Spline.smoothness}
+   */
+  smoothness?: SignalValue<number>;
+
+  /**
+   * {@inheritDoc Spline.points}
+   */
+  points?: SignalValue<SignalValue<PossibleVector2[]>>;
+}
+
+/**
+ * A node for drawing a smooth line through a number of points.
+ *
+ * @remarks
+ * This node uses Bézier curves for drawing each segment of the spline.
+ *
+ * @example
+ * Defining knots using the `points` property. This will automatically
+ * calculate the handle positions for each knot do draw a smooth curve. You
+ * can control the smoothness of the resulting curve via the
+ * {@link Spline.smoothness} property:
+ *
+ * ```tsx
+ * <Spline
+ *   lineWidth={4}
+ *   stroke={'white'}
+ *   smoothness={0.4}
+ *   points={[
+ *     [-400, 0],
+ *     [-200, -300],
+ *     [0, 0],
+ *     [200, -300],
+ *     [400, 0],
+ *   ]}
+ * />
+ * ```
+ *
+ * Defining knots with {@link Knot} nodes:
+ *
+ * ```tsx
+ * <Spline lineWidth={4} stroke={'white'}>
+ *   <Knot position={[-400, 0]} />
+ *   <Knot position={[-200, -300]} />
+ *   <Knot
+ *     position={[0, 0]}
+ *     startHandle={[-100, 200]}
+ *     endHandle={[100, 200]}
+ *   />
+ *   <Knot position={[200, -300]} />
+ *   <Knot position={[400, 0]} />
+ * </Spline>
+ * ```
+ */
+export class Spline extends Curve {
+  /**
+   * The smoothness of the spline when using auto-calculated handles.
+   *
+   * @remarks
+   * This property is only applied to knots that don't use explicit handles.
+   *
+   * @defaultValue 0.4
+   */
+  @initial(0.4)
+  @signal()
+  declare public readonly smoothness: SimpleSignal<number>;
+
+  /**
+   * The knots of the spline as an array of knots with auto-calculated handles.
+   *
+   * @remarks
+   * You can control the smoothness of the resulting curve
+   * via the {@link smoothness} property.
+   */
+  @initial(null)
+  @signal()
+  declare public readonly points: SimpleSignal<
+    SignalValue<PossibleVector2>[] | null,
+    this
+  >;
+
+  public constructor(props: SplineProps) {
+    super(props);
+
+    if (
+      (props.children === undefined ||
+        !Array.isArray(props.children) ||
+        props.children.length < 2) &&
+      (props.points === undefined ||
+        (typeof props.points !== 'function' && props.points.length < 2)) &&
+      props.spawner === undefined
+    ) {
+      useLogger().warn({
+        message:
+          'Insufficient number of knots specified for spline. A spline needs at least two knots.',
+        remarks: splineWithInsufficientKnots,
+        inspect: this.key,
+      });
+    }
+  }
+
+  @computed()
+  public override profile(): CurveProfile {
+    return getBezierSplineProfile(
+      this.knots(),
+      this.closed(),
+      this.smoothness(),
+    );
+  }
+
+  @computed()
+  public knots(): KnotInfo[] {
+    const points = this.points();
+
+    if (points) {
+      return points.map(signal => {
+        const point = new Vector2(unwrap(signal));
+
+        return {
+          position: point,
+          startHandle: point,
+          endHandle: point,
+          auto: {start: 1, end: 1},
+        };
+      });
+    }
+
+    return this.children()
+      .filter(this.isKnot)
+      .map(knot => knot.points());
+  }
+
+  @computed()
+  protected childrenBBox() {
+    const points = (this.profile().segments as PolynomialSegment[]).flatMap(
+      segment => segment.points,
+    );
+    return BBox.fromPoints(...points);
+  }
+
+  protected override lineWidthCoefficient(): number {
+    const join = this.lineJoin();
+
+    let coefficient = super.lineWidthCoefficient();
+
+    if (join !== 'miter') {
+      return coefficient;
+    }
+
+    const {minSin} = this.profile();
+    if (minSin > 0) {
+      coefficient = Math.max(coefficient, 0.5 / minSin);
+    }
+
+    return coefficient;
+  }
+
+  protected override desiredSize(): SerializedVector2<DesiredLength> {
+    return this.getTightBBox().size;
+  }
+
+  protected override offsetComputedLayout(box: BBox): BBox {
+    box.position = box.position.sub(this.getTightBBox().center);
+    return box;
+  }
+
+  @computed()
+  private getTightBBox(): BBox {
+    const bounds = (this.profile().segments as PolynomialSegment[]).map(
+      segment => segment.getBBox(),
+    );
+    return BBox.fromBBoxes(...bounds);
+  }
+
+  public override drawOverlay(
+    context: CanvasRenderingContext2D,
+    matrix: DOMMatrix,
+  ) {
+    const size = this.computedSize();
+    const box = this.childrenBBox().transformCorners(matrix);
+    const offset = size.mul(this.anchor()).scale(0.5).transformAsPoint(matrix);
+    const segments = this.profile().segments as PolynomialSegment[];
+
+    context.lineWidth = 1;
+    context.strokeStyle = 'white';
+    context.fillStyle = 'white';
+
+    const splinePath = new Path2D();
+
+    // Draw the actual spline first so that all control points get drawn on top of it.
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      const [from, startHandle, endHandle, to] =
+        segment.transformPoints(matrix);
+
+      moveTo(splinePath, from);
+      if (segment instanceof CubicBezierSegment) {
+        bezierCurveTo(splinePath, startHandle, endHandle, to as Vector2);
+      } else {
+        quadraticCurveTo(splinePath, startHandle, endHandle);
+      }
+    }
+    context.stroke(splinePath);
+
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i];
+      context.fillStyle = 'white';
+
+      const [from, startHandle, endHandle, to] =
+        segment.transformPoints(matrix);
+
+      const handlePath = new Path2D();
+
+      context.globalAlpha = 0.5;
+      // Line from p0 to p1
+      moveTo(handlePath, from);
+      lineTo(handlePath, startHandle);
+
+      if (segment instanceof CubicBezierSegment) {
+        // Line from p2 to p3
+        moveTo(handlePath, endHandle);
+        lineTo(handlePath, to as Vector2);
+        context.beginPath();
+        context.stroke(handlePath);
+      } else {
+        // Line from p1 to p2
+        lineTo(handlePath, endHandle);
+        context.beginPath();
+        context.stroke(handlePath);
+      }
+
+      context.globalAlpha = 1;
+      context.lineWidth = 2;
+
+      // Draw first point of segment
+      moveTo(context, from);
+      context.beginPath();
+      arc(context, from, 4);
+      context.closePath();
+      context.stroke();
+      context.fill();
+
+      // Draw final point of segment only if we're on the last segment.
+      // Otherwise, it will get drawn as the start point of the next segment.
+      if (i === segments.length - 1) {
+        if (to !== undefined) {
+          moveTo(context, to);
+          context.beginPath();
+          arc(context, to, 4);
+          context.closePath();
+          context.stroke();
+          context.fill();
+        }
+      }
+
+      // Draw the control points
+      context.fillStyle = 'black';
+      for (const point of [startHandle, endHandle]) {
+        if (point.magnitude > 0) {
+          moveTo(context, point);
+          context.beginPath();
+          arc(context, point, 4);
+          context.closePath();
+          context.fill();
+          context.stroke();
+        }
+      }
+    }
+
+    context.lineWidth = 1;
+    context.beginPath();
+    drawPivot(context, offset);
+    context.stroke();
+
+    context.beginPath();
+    drawLine(context, box);
+    context.closePath();
+    context.stroke();
+  }
+
+  private isKnot(node: Node): node is Knot {
+    return node instanceof Knot;
+  }
+}

package/src/lib/components/Txt.test.tsx

@@ -0,0 +1,81 @@
+import {linear, waitFor} from '@canvas-commons/core';
+import {describe, expect, it, vi} from 'vitest';
+import {Txt} from './Txt';
+import {TxtLeaf} from './TxtLeaf';
+import {generatorTest} from './__tests__/generatorTest';
+import {mockScene2D} from './__tests__/mockScene2D';
+
+describe('Txt', () => {
+  mockScene2D();
+
+  it('Handle plain text', () => {
+    const node = (<Txt lineWidth={8}>test</Txt>) as Txt;
+
+    const parseSpy = vi.spyOn(node as any, 'parseChildren');
+    const leaf = node.childAs<TxtLeaf>(0);
+
+    expect(node.text()).toBe('test');
+    expect(node.lineWidth()).toBe(8);
+    expect(node.children().length).toBe(1);
+    expect(leaf).toBeInstanceOf(TxtLeaf);
+    expect(leaf!.text()).toBe('test');
+    expect(leaf!.lineWidth()).toBe(8);
+
+    node.lineWidth(16);
+    node.text('changed');
+
+    expect(node.childAs(0)).toBe(leaf);
+    expect(leaf!.lineWidth()).toBe(16);
+    expect(leaf!.text()).toBe('changed');
+
+    // Parsing should not happen when operating exclusively on simple text
+    expect(parseSpy).toHaveBeenCalledTimes(0);
+  });
+
+  it('Handle complex text', () => {
+    const node = (
+      <Txt lineWidth={8}>
+        Apple <Txt>Banana</Txt> Cherry
+      </Txt>
+    ) as Txt;
+
+    const first = node.childAs<TxtLeaf>(0);
+    const second = node.childAs<Txt>(1);
+    const third = node.childAs<TxtLeaf>(2);
+
+    expect(node.text()).toBe('Apple Banana Cherry');
+    expect(node.lineWidth()).toBe(8);
+    expect(node.children().length).toBe(3);
+    expect(first).toBeInstanceOf(TxtLeaf);
+    expect(first!.text()).toBe('Apple ');
+    expect(first!.lineWidth()).toBe(8);
+
+    expect(second).toBeInstanceOf(Txt);
+    expect(second!.text()).toBe('Banana');
+    expect(second!.lineWidth()).toBe(8);
+
+    expect(third).toBeInstanceOf(TxtLeaf);
+    expect(third!.text()).toBe(' Cherry');
+    expect(third!.lineWidth()).toBe(8);
+  });
+
+  it(
+    'Tween complex to simple text',
+    generatorTest(function* () {
+      const node = (
+        <Txt>
+          <Txt>Apple</Txt> Banana
+        </Txt>
+      ) as Txt;
+
+      yield node.text('Simple', 2, linear);
+      yield* waitFor(1);
+
+      const leaf = node.childAs<TxtLeaf>(0)!;
+
+      expect(node.children().length).toBe(1);
+      expect(node.text()).toBe('Apple Ban');
+      expect(leaf.text()).toBe('Apple Ban');
+    }),
+  );
+});