@twick/2d 0.11.0

package/src/lib/components/Curve.ts

@@ -0,0 +1,455 @@
+import type {
+  BBox,
+  SerializedVector2,
+  SignalValue,
+  SimpleSignal,
+} from '@twick/core';
+import {Vector2, clamp} from '@twick/core';
+import type {CurveDrawingInfo} from '../curves/CurveDrawingInfo';
+import type {CurvePoint} from '../curves/CurvePoint';
+import type {CurveProfile} from '../curves/CurveProfile';
+import {getPointAtDistance} from '../curves/getPointAtDistance';
+import {computed, initial, nodeName, signal} from '../decorators';
+import type {DesiredLength} from '../partials';
+import {lineTo, moveTo, resolveCanvasStyle} from '../utils';
+import type {ShapeProps} from './Shape';
+import {Shape} from './Shape';
+
+export interface CurveProps extends ShapeProps {
+  /**
+   * {@inheritDoc Curve.closed}
+   */
+  closed?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc Curve.start}
+   */
+  start?: SignalValue<number>;
+  /**
+   * {@inheritDoc Curve.startOffset}
+   */
+  startOffset?: SignalValue<number>;
+  /**
+   * {@inheritDoc Curve.startArrow}
+   */
+  startArrow?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc Curve.end}
+   */
+  end?: SignalValue<number>;
+  /**
+   * {@inheritDoc Curve.endOffset}
+   */
+  endOffset?: SignalValue<number>;
+  /**
+   * {@inheritDoc Curve.endArrow}
+   */
+  endArrow?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc Curve.arrowSize}
+   */
+  arrowSize?: SignalValue<number>;
+}
+
+@nodeName('Curve')
+export abstract class Curve extends Shape {
+  /**
+   * Whether the curve should be closed.
+   *
+   * @remarks
+   * Closed curves have their start and end points connected.
+   */
+  @initial(false)
+  @signal()
+  public declare readonly closed: SimpleSignal<boolean, this>;
+
+  /**
+   * A percentage from the start before which the curve should be clipped.
+   *
+   * @remarks
+   * The portion of the curve that comes before the given percentage will be
+   * made invisible.
+   *
+   * This property is usefully for animating the curve appearing on the screen.
+   * The value of `0` means the very start of the curve (accounting for the
+   * {@link startOffset}) while `1` means the very end (accounting for the
+   * {@link endOffset}).
+   */
+  @initial(0)
+  @signal()
+  public declare readonly start: SimpleSignal<number, this>;
+
+  /**
+   * The offset in pixels from the start of the curve.
+   *
+   * @remarks
+   * This property lets you specify where along the defined curve the actual
+   * visible portion starts. For example, setting it to `20` will make the first
+   * 20 pixels of the curve invisible.
+   *
+   * This property is useful for trimming the curve using a fixed distance.
+   * If you want to animate the curve appearing on the screen, use {@link start}
+   * instead.
+   */
+  @initial(0)
+  @signal()
+  public declare readonly startOffset: SimpleSignal<number, this>;
+
+  /**
+   * Whether to display an arrow at the start of the visible curve.
+   *
+   * @remarks
+   * Use {@link arrowSize} to control the size of the arrow.
+   */
+  @initial(false)
+  @signal()
+  public declare readonly startArrow: SimpleSignal<boolean, this>;
+
+  /**
+   * A percentage from the start after which the curve should be clipped.
+   *
+   * @remarks
+   * The portion of the curve that comes after the given percentage will be
+   * made invisible.
+   *
+   * This property is usefully for animating the curve appearing on the screen.
+   * The value of `0` means the very start of the curve (accounting for the
+   * {@link startOffset}) while `1` means the very end (accounting for the
+   * {@link endOffset}).
+   */
+  @initial(1)
+  @signal()
+  public declare readonly end: SimpleSignal<number, this>;
+
+  /**
+   * The offset in pixels from the end of the curve.
+   *
+   * @remarks
+   * This property lets you specify where along the defined curve the actual
+   * visible portion ends. For example, setting it to `20` will make the last
+   * 20 pixels of the curve invisible.
+   *
+   * This property is useful for trimming the curve using a fixed distance.
+   * If you want to animate the curve appearing on the screen, use {@link end}
+   * instead.
+   */
+  @initial(0)
+  @signal()
+  public declare readonly endOffset: SimpleSignal<number, this>;
+
+  /**
+   * Whether to display an arrow at the end of the visible curve.
+   *
+   * @remarks
+   * Use {@link arrowSize} to control the size of the arrow.
+   */
+  @initial(false)
+  @signal()
+  public declare readonly endArrow: SimpleSignal<boolean, this>;
+
+  /**
+   * Controls the size of the end and start arrows.
+   *
+   * @remarks
+   * To make the arrows visible make sure to enable {@link startArrow} and/or
+   * {@link endArrow}.
+   */
+  @initial(24)
+  @signal()
+  public declare readonly arrowSize: SimpleSignal<number, this>;
+
+  protected canHaveSubpath = false;
+
+  protected override desiredSize(): SerializedVector2<DesiredLength> {
+    return this.childrenBBox().size;
+  }
+
+  public constructor(props: CurveProps) {
+    super(props);
+  }
+
+  protected abstract childrenBBox(): BBox;
+
+  public abstract profile(): CurveProfile;
+
+  /**
+   * Convert a percentage along the curve to a distance.
+   *
+   * @remarks
+   * The returned distance is given in relation to the full curve, not
+   * accounting for {@link startOffset} and {@link endOffset}.
+   *
+   * @param value - The percentage along the curve.
+   */
+  public percentageToDistance(value: number): number {
+    return clamp(
+      0,
+      this.baseArcLength(),
+      this.startOffset() + this.offsetArcLength() * value,
+    );
+  }
+
+  /**
+   * Convert a distance along the curve to a percentage.
+   *
+   * @remarks
+   * The distance should be given in relation to the full curve, not
+   * accounting for {@link startOffset} and {@link endOffset}.
+   *
+   * @param value - The distance along the curve.
+   */
+  public distanceToPercentage(value: number): number {
+    return (value - this.startOffset()) / this.offsetArcLength();
+  }
+
+  /**
+   * The base arc length of this curve.
+   *
+   * @remarks
+   * This is the entire length of this curve, not accounting for
+   * {@link startOffset | the offsets}.
+   */
+  public baseArcLength() {
+    return this.profile().arcLength;
+  }
+
+  /**
+   * The offset arc length of this curve.
+   *
+   * @remarks
+   * This is the length of the curve that accounts for
+   * {@link startOffset | the offsets}.
+   */
+  public offsetArcLength() {
+    const startOffset = this.startOffset();
+    const endOffset = this.endOffset();
+    const baseLength = this.baseArcLength();
+    return clamp(0, baseLength, baseLength - startOffset - endOffset);
+  }
+
+  /**
+   * The visible arc length of this curve.
+   *
+   * @remarks
+   * This arc length accounts for both the offset and the {@link start} and
+   * {@link end} properties.
+   */
+  @computed()
+  public arcLength() {
+    return this.offsetArcLength() * Math.abs(this.start() - this.end());
+  }
+
+  /**
+   * The percentage of the curve that's currently visible.
+   *
+   * @remarks
+   * The returned value is the ratio between the visible length (as defined by
+   * {@link start} and {@link end}) and the offset length of the curve.
+   */
+  public completion(): number {
+    return Math.abs(this.start() - this.end());
+  }
+
+  protected processSubpath(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _path: Path2D,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _startPoint: Vector2 | null,
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    _endPoint: Vector2 | null,
+  ) {
+    // do nothing
+  }
+
+  @computed()
+  protected curveDrawingInfo(): CurveDrawingInfo {
+    const path = new Path2D();
+    let subpath = new Path2D();
+    const profile = this.profile();
+
+    let start = this.percentageToDistance(this.start());
+    let end = this.percentageToDistance(this.end());
+    if (start > end) {
+      [start, end] = [end, start];
+    }
+
+    const distance = end - start;
+    const arrowSize = Math.min(distance / 2, this.arrowSize());
+
+    if (this.startArrow()) {
+      start += arrowSize / 2;
+    }
+
+    if (this.endArrow()) {
+      end -= arrowSize / 2;
+    }
+
+    let length = 0;
+    let startPoint = null;
+    let startTangent = null;
+    let endPoint = null;
+    let endTangent = null;
+    for (const segment of profile.segments) {
+      const previousLength = length;
+      length += segment.arcLength;
+      if (length < start) {
+        continue;
+      }
+
+      const relativeStart = (start - previousLength) / segment.arcLength;
+      const relativeEnd = (end - previousLength) / segment.arcLength;
+
+      const clampedStart = clamp(0, 1, relativeStart);
+      const clampedEnd = clamp(0, 1, relativeEnd);
+
+      if (
+        this.canHaveSubpath &&
+        endPoint &&
+        !segment.getPoint(0).position.equals(endPoint)
+      ) {
+        path.addPath(subpath);
+        this.processSubpath(subpath, startPoint, endPoint);
+        subpath = new Path2D();
+        startPoint = null;
+      }
+
+      const [startCurvePoint, endCurvePoint] = segment.draw(
+        subpath,
+        clampedStart,
+        clampedEnd,
+        startPoint === null,
+      );
+
+      if (startPoint === null) {
+        startPoint = startCurvePoint.position;
+        startTangent = startCurvePoint.normal.flipped.perpendicular;
+      }
+
+      endPoint = endCurvePoint.position;
+      endTangent = endCurvePoint.normal.flipped.perpendicular;
+      if (length > end) {
+        break;
+      }
+    }
+
+    if (
+      this.closed() &&
+      this.start.isInitial() &&
+      this.end.isInitial() &&
+      this.startOffset.isInitial() &&
+      this.endOffset.isInitial()
+    ) {
+      subpath.closePath();
+    }
+    this.processSubpath(subpath, startPoint, endPoint);
+    path.addPath(subpath);
+
+    return {
+      startPoint: startPoint ?? Vector2.zero,
+      startTangent: startTangent ?? Vector2.right,
+      endPoint: endPoint ?? Vector2.zero,
+      endTangent: endTangent ?? Vector2.right,
+      arrowSize,
+      path,
+      startOffset: start,
+    };
+  }
+
+  protected getPointAtDistance(value: number): CurvePoint {
+    return getPointAtDistance(this.profile(), value + this.startOffset());
+  }
+
+  public getPointAtPercentage(value: number): CurvePoint {
+    return getPointAtDistance(this.profile(), this.percentageToDistance(value));
+  }
+
+  protected override getComputedLayout(): BBox {
+    return this.offsetComputedLayout(super.getComputedLayout());
+  }
+
+  protected offsetComputedLayout(box: BBox): BBox {
+    box.position = box.position.sub(this.childrenBBox().center);
+    return box;
+  }
+
+  protected override getPath(): Path2D {
+    return this.curveDrawingInfo().path;
+  }
+
+  protected override getCacheBBox(): BBox {
+    const box = this.childrenBBox();
+    const arrowSize =
+      this.startArrow() || this.endArrow() ? this.arrowSize() : 0;
+    const lineWidth = this.lineWidth();
+
+    const coefficient = this.lineWidthCoefficient();
+
+    return box.expand(Math.max(0, arrowSize, lineWidth * coefficient));
+  }
+
+  protected lineWidthCoefficient(): number {
+    return this.lineCap() === 'square' ? 0.5 * 1.4143 : 0.5;
+  }
+
+  /**
+   * Check if the path requires a profile.
+   *
+   * @remarks
+   * The profile is only required if certain features are used. Otherwise, the
+   * profile generation can be skipped, and the curve can be drawn directly
+   * using the 2D context.
+   */
+  protected requiresProfile(): boolean {
+    return (
+      !this.start.isInitial() ||
+      !this.startOffset.isInitial() ||
+      !this.startArrow.isInitial() ||
+      !this.end.isInitial() ||
+      !this.endOffset.isInitial() ||
+      !this.endArrow.isInitial()
+    );
+  }
+
+  protected override drawShape(context: CanvasRenderingContext2D) {
+    super.drawShape(context);
+    if (this.startArrow() || this.endArrow()) {
+      this.drawArrows(context);
+    }
+  }
+
+  private drawArrows(context: CanvasRenderingContext2D) {
+    const {startPoint, startTangent, endPoint, endTangent, arrowSize} =
+      this.curveDrawingInfo();
+    if (arrowSize < 0.001) {
+      return;
+    }
+
+    context.save();
+    context.beginPath();
+    if (this.endArrow()) {
+      this.drawArrow(context, endPoint, endTangent.flipped, arrowSize);
+    }
+    if (this.startArrow()) {
+      this.drawArrow(context, startPoint, startTangent, arrowSize);
+    }
+    context.fillStyle = resolveCanvasStyle(this.stroke(), context);
+    context.closePath();
+    context.fill();
+    context.restore();
+  }
+
+  private drawArrow(
+    context: CanvasRenderingContext2D | Path2D,
+    center: Vector2,
+    tangent: Vector2,
+    arrowSize: number,
+  ) {
+    const normal = tangent.perpendicular;
+    const origin = center.add(tangent.scale(-arrowSize / 2));
+
+    moveTo(context, origin);
+    lineTo(context, origin.add(tangent.add(normal).scale(arrowSize)));
+    lineTo(context, origin.add(tangent.sub(normal).scale(arrowSize)));
+    lineTo(context, origin);
+    context.closePath();
+  }
+}

package/src/lib/components/Grid.ts

@@ -0,0 +1,135 @@
+import type {
+  PossibleVector2,
+  SignalValue,
+  SimpleSignal,
+  Vector2Signal,
+} from '@twick/core';
+import {map} from '@twick/core';
+import {initial, nodeName, signal, vector2Signal} from '../decorators';
+import type {ShapeProps} from './Shape';
+import {Shape} from './Shape';
+
+export interface GridProps extends ShapeProps {
+  /**
+   * {@inheritDoc Grid.spacing}
+   */
+  spacing?: SignalValue<PossibleVector2>;
+  /**
+   * {@inheritDoc Grid.start}
+   */
+  start?: SignalValue<number>;
+  /**
+   * {@inheritDoc Grid.end}
+   */
+  end?: SignalValue<number>;
+}
+
+/**
+ * A node for drawing a two-dimensional grid.
+ *
+ * @preview
+ * ```tsx editor
+ * import {Grid, makeScene2D} from '@twick/2d';
+ * import {all, createRef} from '@twick/core';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const grid = createRef<Grid>();
+ *
+ *   view.add(
+ *     <Grid
+ *       ref={grid}
+ *       width={'100%'}
+ *       height={'100%'}
+ *       stroke={'#666'}
+ *       start={0}
+ *       end={1}
+ *     />,
+ *   );
+ *
+ *   yield* all(
+ *     grid().end(0.5, 1).to(1, 1).wait(1),
+ *     grid().start(0.5, 1).to(0, 1).wait(1),
+ *   );
+ * });
+ * ```
+ */
+@nodeName('Grid')
+export class Grid extends Shape {
+  /**
+   * The spacing between the grid lines.
+   */
+  @initial(80)
+  @vector2Signal('spacing')
+  public declare readonly spacing: Vector2Signal<this>;
+
+  /**
+   * The percentage that should be clipped from the beginning of each grid line.
+   *
+   * @remarks
+   * The portion of each grid line that comes before the given percentage will
+   * be made invisible.
+   *
+   * This property is useful for animating the grid appearing on-screen.
+   */
+  @initial(0)
+  @signal()
+  public declare readonly start: SimpleSignal<number, this>;
+
+  /**
+   * The percentage that should be clipped from the end of each grid line.
+   *
+   * @remarks
+   * The portion of each grid line that comes after the given percentage will
+   * be made invisible.
+   *
+   * This property is useful for animating the grid appearing on-screen.
+   */
+  @initial(1)
+  @signal()
+  public declare readonly end: SimpleSignal<number, this>;
+
+  public constructor(props: GridProps) {
+    super(props);
+  }
+
+  protected override drawShape(context: CanvasRenderingContext2D) {
+    context.save();
+    this.applyStyle(context);
+    this.drawRipple(context);
+
+    const spacing = this.spacing();
+    const size = this.computedSize().scale(0.5);
+    const steps = size.div(spacing).floored;
+
+    for (let x = -steps.x; x <= steps.x; x++) {
+      const [from, to] = this.mapPoints(-size.height, size.height);
+
+      context.beginPath();
+      context.moveTo(spacing.x * x, from);
+      context.lineTo(spacing.x * x, to);
+      context.stroke();
+    }
+
+    for (let y = -steps.y; y <= steps.y; y++) {
+      const [from, to] = this.mapPoints(-size.width, size.width);
+
+      context.beginPath();
+      context.moveTo(from, spacing.y * y);
+      context.lineTo(to, spacing.y * y);
+      context.stroke();
+    }
+
+    context.restore();
+  }
+
+  private mapPoints(start: number, end: number): [number, number] {
+    let from = map(start, end, this.start());
+    let to = map(start, end, this.end());
+
+    if (to < from) {
+      [from, to] = [to, from];
+    }
+
+    return [from, to];
+  }
+}

package/src/lib/components/Icon.ts

@@ -0,0 +1,96 @@
+import type {
+  ColorSignal,
+  PossibleColor,
+  SignalValue,
+  SimpleSignal,
+} from '@twick/core';
+import {useLogger} from '@twick/core';
+import {colorSignal, computed, initial, signal} from '../decorators';
+import type {ImgProps} from './Img';
+import {Img} from './Img';
+
+export interface IconProps extends ImgProps {
+  /**
+   * {@inheritDoc Icon.icon}
+   */
+  icon: SignalValue<string>;
+
+  /**
+   * {@inheritDoc Icon.color}
+   */
+  color?: SignalValue<PossibleColor>;
+}
+
+/**
+ * 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 Img {
+  /**
+   * 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()
+  public declare 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()
+  public declare color: ColorSignal<this>;
+
+  public constructor(props: IconProps) {
+    super({
+      ...props,
+      src: null,
+    });
+  }
+
+  /**
+   * Create the URL that will be used as the Image source
+   * @returns Address to Iconify API for the requested Icon.
+   */
+  @computed()
+  protected svgUrl(): string {
+    const iconPathSegment = this.icon().replace(':', '/');
+    const encodedColorValue = encodeURIComponent(this.color().hex());
+    // Iconify API is documented here: https://docs.iconify.design/api/svg.html#color
+    return `https://api.iconify.design/${iconPathSegment}.svg?color=${encodedColorValue}`;
+  }
+
+  /**
+   * overrides `Image.src` getter
+   */
+  protected getSrc(): string {
+    return this.svgUrl();
+  }
+
+  /**
+   * overrides `Image.src` setter to warn the user that the value
+   * is not used
+   */
+  protected setSrc(src: string | null) {
+    if (src === null) {
+      return;
+    }
+    useLogger().warn(
+      "The Icon Component does not accept setting the `src`. If you need access to `src`, use '<Img/>` instead.",
+    );
+  }
+}