@canvas-commons/2d 0.2.0

package/src/lib/components/Circle.ts

@@ -0,0 +1,310 @@
+import {
+  BBox,
+  DEG2RAD,
+  SerializedVector2,
+  SignalValue,
+  SimpleSignal,
+} from '@canvas-commons/core';
+import {CurveProfile, getCircleProfile} from '../curves';
+import {computed, initial, nodeName, signal} from '../decorators';
+import {DesiredLength} from '../partials';
+import {PathDataBuilder} from '../utils';
+import {Curve, CurveProps} from './Curve';
+
+export interface CircleProps extends CurveProps {
+  /**
+   * {@inheritDoc Circle.startAngle}
+   */
+  startAngle?: SignalValue<number>;
+  /**
+   * {@inheritDoc Circle.endAngle}
+   */
+  endAngle?: SignalValue<number>;
+  /**
+   * {@inheritDoc Circle.counterclockwise}
+   */
+  counterclockwise?: SignalValue<boolean>;
+  /**
+   * {@inheritDoc Circle.closed}
+   */
+  closed?: SignalValue<boolean>;
+}
+
+/**
+ * A node for drawing circular shapes.
+ *
+ * @remarks
+ * This node can be used to render shapes such as: circle, ellipse, arc, and
+ * sector (pie chart).
+ *
+ * @preview
+ * ```tsx editor
+ * // snippet Simple circle
+ * import {makeScene2D, Circle} from '@canvas-commons/2d';
+ *
+ * export default makeScene2D(function* (view) {
+ *   view.add(
+ *     <Circle
+ *       size={160}
+ *       fill={'lightseagreen'}
+ *     />
+ *    );
+ * });
+ *
+ * // snippet Ellipse
+ * import {makeScene2D, Circle} from '@canvas-commons/2d';
+ *
+ * export default makeScene2D(function* (view) {
+ *   view.add(
+ *     <Circle
+ *       width={160}
+ *       height={80}
+ *       fill={'lightseagreen'}
+ *     />
+ *   );
+ * });
+ *
+ * // snippet Sector (pie chart):
+ * import {makeScene2D, Circle} from '@canvas-commons/2d';
+ * import {createRef} from '@canvas-commons/core';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const ref = createRef<Circle>();
+ *   view.add(
+ *     <Circle
+ *       ref={ref}
+ *       size={160}
+ *       fill={'lightseagreen'}
+ *       startAngle={30}
+ *       endAngle={270}
+ *       closed={true}
+ *     />
+ *   );
+ *
+ *   yield* ref().startAngle(270, 2).to(30, 2);
+ * });
+ *
+ * // snippet Arc:
+ * import {makeScene2D, Circle} from '@canvas-commons/2d';
+ * import {createRef} from '@canvas-commons/core';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const ref = createRef<Circle>();
+ *   view.add(
+ *     <Circle
+ *       ref={ref}
+ *       size={160}
+ *       stroke={'lightseagreen'}
+ *       lineWidth={8}
+ *       startAngle={-90}
+ *       endAngle={90}
+ *     />
+ *   );
+ *
+ *   yield* ref().startAngle(-270, 2).to(-90, 2);
+ * });
+ *
+ * // snippet Curve properties:
+ * import {makeScene2D, Circle} from '@canvas-commons/2d';
+ * import {all, createRef, easeInCubic, easeOutCubic} from '@canvas-commons/core';
+ *
+ * export default makeScene2D(function* (view) {
+ *   const ref = createRef<Circle>();
+ *   view.add(
+ *     <Circle
+ *       ref={ref}
+ *       size={160}
+ *       stroke={'lightseagreen'}
+ *       lineWidth={8}
+ *       endAngle={270}
+ *       endArrow
+ *     />,
+ *   );
+ *
+ *   yield* all(ref().start(1, 1), ref().rotation(180, 1, easeInCubic));
+ *   ref().start(0).end(0);
+ *   yield* all(ref().end(1, 1), ref().rotation(360, 1, easeOutCubic));
+ * });
+ * ```
+ */
+@nodeName('Circle')
+export class Circle extends Curve {
+  /**
+   * The starting angle in degrees for the circle sector.
+   *
+   * @remarks
+   * This property can be used together with {@link startAngle} to turn this
+   * circle into a sector (when using fill) or an arc (when using stroke).
+   *
+   * @defaultValue 0
+   */
+  @initial(0)
+  @signal()
+  declare public readonly startAngle: SimpleSignal<number, this>;
+
+  /**
+   * The ending angle in degrees for the circle sector.
+   *
+   * @remarks
+   * This property can be used together with {@link endAngle} to turn this
+   * circle into a sector (when using fill) or an arc (when using stroke).
+   *
+   * @defaultValue 360
+   */
+  @initial(360)
+  @signal()
+  declare public readonly endAngle: SimpleSignal<number, this>;
+
+  /**
+   * Whether the circle sector should be drawn counterclockwise.
+   *
+   * @remarks
+   * By default, the circle begins at {@link startAngle} and is drawn clockwise
+   * until reaching {@link endAngle}. Setting this property to true will reverse
+   * this direction.
+   */
+  @initial(false)
+  @signal()
+  declare public readonly counterclockwise: SimpleSignal<boolean, this>;
+
+  /**
+   * Whether the path of this circle should be closed.
+   *
+   * @remarks
+   * When set to true, the path of this circle will start and end at the center.
+   * This can be used to fine-tune how sectors are rendered.
+   *
+   * @example
+   * A closed circle will look like a pie chart:
+   * ```tsx
+   * <Circle
+   *   size={300}
+   *   fill={'lightseagreen'}
+   *   endAngle={230}
+   *   closed={true}
+   * />
+   * ```
+   * An open one will look like an arc:
+   * ```tsx
+   * <Circle
+   *   size={300}
+   *   stroke={'lightseagreen'}
+   *   lineWidth={8}
+   *   endAngle={230}
+   *   closed={false}
+   * />
+   * ```
+   *
+   * @defaultValue false
+   */
+  declare public readonly closed: SimpleSignal<boolean, this>;
+
+  public constructor(props: CircleProps) {
+    super(props);
+  }
+
+  @computed()
+  public profile(): CurveProfile {
+    return getCircleProfile(
+      this.size().scale(0.5),
+      this.startAngle() * DEG2RAD,
+      this.endAngle() * DEG2RAD,
+      this.closed(),
+      this.counterclockwise(),
+    );
+  }
+
+  protected override desiredSize(): SerializedVector2<DesiredLength> {
+    return {
+      x: this.width.context.getter(),
+      y: this.height.context.getter(),
+    };
+  }
+
+  protected override offsetComputedLayout(box: BBox): BBox {
+    return box;
+  }
+
+  protected override childrenBBox(): BBox {
+    return BBox.fromSizeCentered(this.computedSize());
+  }
+
+  @computed()
+  protected override getPathData(): string {
+    const builder = new PathDataBuilder();
+    const start = this.startAngle() * DEG2RAD;
+    let end = this.endAngle() * DEG2RAD;
+    const size = this.size().scale(0.5);
+    const closed = this.closed();
+
+    if (end > start + Math.PI * 2) {
+      const loops = Math.floor((end - start) / (Math.PI * 2));
+      end -= Math.PI * 2 * loops;
+    }
+
+    if (closed) {
+      builder.moveTo(0, 0);
+    }
+
+    builder.ellipse(
+      0,
+      0,
+      size.x,
+      size.y,
+      0,
+      start,
+      end,
+      this.counterclockwise(),
+    );
+
+    if (closed) {
+      builder.closePath();
+    }
+
+    return builder.toString();
+  }
+
+  protected override getPath(): Path2D {
+    if (this.requiresProfile()) {
+      return this.curveDrawingInfo().path;
+    }
+
+    const pathData = this.getPathData();
+    if (pathData) {
+      return new Path2D(pathData);
+    }
+
+    return this.createPath();
+  }
+
+  protected override getRipplePath(): Path2D {
+    return this.createPath(this.rippleSize());
+  }
+
+  protected override getCacheBBox(): BBox {
+    return super.getCacheBBox().expand(this.rippleSize());
+  }
+
+  protected createPath(expand = 0) {
+    const path = new Path2D();
+    const start = this.startAngle() * DEG2RAD;
+    let end = this.endAngle() * DEG2RAD;
+    const size = this.size().scale(0.5).add(expand);
+    const closed = this.closed();
+
+    if (end > start + Math.PI * 2) {
+      const loops = Math.floor((end - start) / (Math.PI * 2));
+      end -= Math.PI * 2 * loops;
+    }
+
+    if (closed) {
+      path.moveTo(0, 0);
+    }
+    path.ellipse(0, 0, size.x, size.y, 0, start, end, this.counterclockwise());
+    if (closed) {
+      path.closePath();
+    }
+
+    return path;
+  }
+}