stage-js 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stage-js",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "2D HTML5 Rendering and Layout",
   "homepage": "http://piqnt.com/stage.js/",
   "author": "Ali Shakiba",
@@ -22,7 +22,7 @@
     "mobile"
   ],
   "engines": {
-    "node": ">=18.0"
+    "node": ">=24.0"
   },
   "type": "module",
   "module": "./dist/stage.js",
@@ -55,7 +55,10 @@
     "change": "changeset",
     "version": "changeset version",
     "publish": "changeset publish",
-    "typedoc": "typedoc --options typedoc.json && mv ./docs/pages/api/README.md ./docs/pages/api/index.md && ./node_modules/.bin/replace-in-files ./docs/pages/api/* --string '.md' --replacement ''"
+    "typedoc": "typedoc --options typedoc.json && mv ./docs/pages/api/README.md ./docs/pages/api/index.md",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.11",
@@ -68,16 +71,16 @@
     "expect.js": "^0.3.1",
     "mocha": "^6.2.3",
     "prettier": "^3.2.5",
-    "replace-in-files-cli": "^3.0.0",
     "rollup-plugin-license": "^3.3.1",
     "sandboxed-module": "^2.0.0",
     "sinon": "^9.0.2",
-    "typedoc": "^0.26.11",
-    "typedoc-plugin-markdown": "^4.2.10",
+    "typedoc": "^0.28.18",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.6.3",
-    "vite": "^5.4.11",
-    "vite-plugin-dts-bundle-generator": "^2.0.5",
-    "vite-plugin-pages": "^0.32.3",
-    "vite-plugin-typescript": "^1.0.4"
+    "unplugin-dts-bundle-generator": "^3.4.1",
+    "vite": "^6.4.1",
+    "vite-plugin-pages": "^0.33.3",
+    "vite-plugin-typescript": "^1.0.4",
+    "vitepress": "^2.0.0-alpha.16"
   }
 }

package/src/core/component.ts

@@ -1,10 +1,11 @@
 import stats from "../common/stats";
-import { Vec2Value } from "../common/matrix";
+import { Matrix, Vec2Value } from "../common/matrix";
 import { uid } from "../common/uid";
 import { getDevicePixelRatio } from "../common/browser";
 
 import { Pin, FitMode, SetPinType, SetPinKeys, GetPinKeys } from "./pin";
 import { Transition, TransitionOptions } from "./transition";
+import { renderAxis, renderPoint } from "./debug";
 
 // todo: why there are two iids (other in pin)?
 /** @internal */
@@ -130,6 +131,12 @@ export class Component {
   /** @internal */ _mo_seqAlign: number;
   /** @internal */ _mo_box: number;
 
+  /** @hidden Set to true to enable debug rendering */
+  _debug: boolean;
+
+  /** @internal */
+  _xf: Matrix;
+
   constructor() {
     stats.create++;
     if (this instanceof Component) {
@@ -144,25 +151,30 @@ export class Component {
     return this._pin.absoluteMatrix();
   }
 
-  /** @hidden @deprecated */
+  /** @hidden @deprecated Use getLogicalPixelRatio */
   getPixelRatio() {
     // todo: remove this function
-    const m = this._parent?.matrix();
-    const pixelRatio = !m ? 1 : Math.max(Math.abs(m.a), Math.abs(m.b)) / getDevicePixelRatio();
-    return pixelRatio;
+    return this.getLogicalPixelRatio();
   }
 
-  /** @hidden This is not accurate before first tick */
+  /**
+   * @hidden
+   * Physical-pixel per unit of parent component.
+   * This is not accurate before first tick.
+   */
   getDevicePixelRatio() {
     // todo: parent matrix is not available in the first call
     const parentMatrix = this._parent?.matrix();
-    const pixelRatio = !parentMatrix
-      ? 1
-      : Math.max(Math.abs(parentMatrix.a), Math.abs(parentMatrix.b));
+    if (!parentMatrix) return 1;
+    const pixelRatio = Math.max(Math.abs(parentMatrix.a), Math.abs(parentMatrix.b));
     return pixelRatio;
   }
 
-  /** @hidden This is not accurate before first tick */
+  /**
+   * @hidden
+   * Logical-pixel per unit of parent component.
+   * This is not accurate before first tick.
+   */
   getLogicalPixelRatio() {
     return this.getDevicePixelRatio() / getDevicePixelRatio();
   }
@@ -656,6 +668,9 @@ export class Component {
     stats.component++;
 
     const m = this.matrix();
+
+    this.renderDebug(context, m);
+
     context.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
 
     // move this elsewhere!
@@ -1199,6 +1214,33 @@ export class Component {
     this._spacing = space;
     return this;
   }
+
+  renderDebug(ctx: CanvasRenderingContext2D, xf: Matrix) {
+    if (!this._debug) return;
+    const ppu = this.getLogicalPixelRatio();
+
+    ctx.lineWidth = 1 / ppu;
+    ctx.lineCap = "round";
+    ctx.lineJoin = "round";
+
+    renderAxis(ctx, 1);
+
+    const pin = this._pin;
+    if (pin._pivoted) {
+      ctx.strokeStyle = "orange";
+      renderPoint(ctx, pin._pivotX * pin._width, pin._pivotY * pin._height);
+    }
+
+    if (pin._aligned) {
+      ctx.strokeStyle = "green";
+      renderPoint(ctx, pin._alignX * pin._width, pin._alignY * pin._height);
+    }
+
+    if (pin._handled) {
+      ctx.strokeStyle = "yellow";
+      renderPoint(ctx, pin._handleX * pin._width, pin._handleY * pin._height);
+    }
+  }
 }
 
 /** @hidden @deprecated Node is renamed to Component */

package/src/core/debug.ts

@@ -0,0 +1,33 @@
+export function renderAxis(this: unknown, ctx: CanvasRenderingContext2D, size: number) {
+  ctx.strokeStyle = "rgba(93, 173, 226)";
+  ctx.beginPath();
+  ctx.moveTo(0, 0);
+  ctx.lineTo(0, 0.8 * size);
+  ctx.lineTo(-0.2 * size, 0.8 * size);
+  ctx.lineTo(0, size);
+  ctx.lineTo(+0.2 * size, 0.8 * size);
+  ctx.lineTo(0, 0.8 * size);
+  ctx.stroke();
+
+  ctx.strokeStyle = "rgba(236, 112, 99)";
+  ctx.beginPath();
+  ctx.moveTo(0, 0);
+  ctx.lineTo(0.8 * size, 0);
+  ctx.lineTo(0.8 * size, -0.2 * size);
+  ctx.lineTo(size, 0);
+  ctx.lineTo(0.8 * size, +0.2 * size);
+  ctx.lineTo(0.8 * size, 0);
+  ctx.stroke();
+}
+
+export function renderPoint(this: unknown, ctx: CanvasRenderingContext2D, px: number, py: number) {
+  ctx.beginPath();
+  ctx.beginPath();
+  ctx.moveTo(px - 0.2, py - 0.2);
+  ctx.lineTo(px + 0.2, py + 0.2);
+  ctx.stroke();
+  ctx.beginPath();
+  ctx.moveTo(px - 0.2, py + 0.2);
+  ctx.lineTo(px + 0.2, py - 0.2);
+  ctx.stroke();
+}

package/src/core/easing.ts

@@ -78,7 +78,7 @@ const initEasing = (query: string, params?: number[]): EasingFunction => {
         : 7.5625 * (t -= 2.625 / 2.75) * t + 0.984375;
 
 /** @internal */ const poly =
-  (e: number): EasingFunction =>
+  (e: number = 3): EasingFunction =>
   (t: number) =>
     Math.pow(t, e);
 

package/src/core/pin.ts

@@ -1,4 +1,4 @@
-import { Matrix, Vec2Value } from "../common/matrix";
+import { Matrix } from "../common/matrix";
 import { uid } from "../common/uid";
 
 import type { Component } from "./component";
@@ -35,6 +35,10 @@ export function isValidFitMode(value: string) {
 
 /** @internal */ let iid = 0;
 
+/** @internal */ export function getIID() {
+  return iid++;
+}
+
 export class Pin {
   /** @internal */ uid = "pin:" + uid();
 
@@ -194,6 +198,7 @@ export class Pin {
     abs.reset(this.relativeMatrix());
 
     this._parent && abs.concat(this._parent._absoluteMatrix);
+    this._owner._xf && abs.concat(this._owner._xf);
 
     this._ts_matrix = ++iid;
 
@@ -344,6 +349,51 @@ export class Pin {
   }
 }
 
+/** @internal */
+const fitted = {};
+
+/** @internal */
+export function fit(
+  this: unknown,
+  inWidth: number,
+  inHeight: number,
+  outWidth: number | null,
+  outHeight: number | null,
+  mode?: FitMode,
+) {
+  if (mode === "contain") mode = "in-pad";
+  if (mode === "cover") mode = "out-crop";
+
+  let scaleX: number;
+  let scaleY: number;
+
+  let width: number;
+  let height: number;
+
+  if (typeof outWidth === "number") {
+    scaleX = outWidth / inWidth;
+    width = inWidth;
+  }
+  if (typeof outHeight === "number") {
+    scaleY = outHeight / inHeight;
+    height = inHeight;
+  }
+  if (typeof outWidth === "number" && typeof outHeight === "number" && typeof mode === "string") {
+    if (mode === "fill") {
+    } else if (mode === "out" || mode === "out-crop") {
+      scaleX = scaleY = Math.max(scaleX, scaleY);
+    } else if (mode === "in" || mode === "in-pad") {
+      scaleX = scaleY = Math.min(scaleX, scaleY);
+    }
+    if (mode === "out-crop" || mode === "in-pad") {
+      width = outWidth / scaleX;
+      height = outHeight / scaleY;
+    }
+  }
+
+  return { scaleX, scaleY, width, height };
+}
+
 /** @internal */ const getters = {
   alpha: function (pin: Pin) {
     return pin._alpha;
@@ -652,11 +702,11 @@ export interface SetPinType {
 
   rotation?: number;
 
-  /** Center of scale/skew/rotate  */
+  /** Center of scale/skew/rotate, 0 is start, 1 is end  */
   pivot?: number;
-  /** Center of scale/skew/rotate  */
+  /** Center of scale/skew/rotate, 0 is start, 1 is end  */
   pivotX?: number;
-  /** Center of scale/skew/rotate  */
+  /** Center of scale/skew/rotate, 0 is start, 1 is end  */
   pivotY?: number;
 
   /** Offset in parent coordination */
@@ -666,18 +716,18 @@ export interface SetPinType {
   /** Offset in parent coordination */
   offsetY?: number;
 
-  /** A point on parent where this component is offset from, 0 is top/left, 1 is bottom/right  */
+  /** A point on parent where this component is offset from, 0 is start, 1 is end  */
   align?: number;
-  /** A point on parent where this component is offset from, 0 is top/left, 1 is bottom/right */
+  /** A point on parent where this component is offset from, 0 is start, 1 is end */
   alignX?: number;
-  /** A point on parent where this component is offset from, 0 is top/left, 1 is bottom/right */
+  /** A point on parent where this component is offset from, 0 is start, 1 is end */
   alignY?: number;
 
-  /** A point on this component which is offset from parent, 0 is top/left, 1 is bottom/right */
+  /** A point on this component which is offset from parent, 0 is start, 1 is end */
   handle?: number;
-  /** A point on this component which is offset from parent, 0 is top/left, 1 is bottom/right */
+  /** A point on this component which is offset from parent, 0 is start, 1 is end */
   handleX?: number;
-  /** A point on this component which is offset from parent, 0 is top/left, 1 is bottom/right */
+  /** A point on this component which is offset from parent, 0 is start, 1 is end */
   handleY?: number;
 
   /** @hidden @deprecated Use component.fit() */

package/src/core/pointer.ts

@@ -18,6 +18,12 @@ export const POINTER_START = "touchstart mousedown";
 /** @hidden @deprecated */
 export const POINTER_END = "touchend mouseup";
 
+export interface PointerEvent {
+  x: number;
+  y: number;
+  raw: UIEvent;
+}
+
 class EventPoint {
   x: number;
   y: number;

package/src/core/root.ts

@@ -1,9 +1,10 @@
 import stats from "../common/stats";
 import { Matrix } from "../common/matrix";
 
+import { renderAxis } from "./debug";
 import { Component } from "./component";
 import { Pointer } from "./pointer";
-import { FitMode, isValidFitMode } from "./pin";
+import { fit, FitMode, getIID, isValidFitMode } from "./pin";
 
 /** @internal */ const ROOTS: Root[] = [];
 
@@ -59,11 +60,11 @@ export class Root extends Component {
   dom: HTMLCanvasElement | null = null;
   context: CanvasRenderingContext2D | null = null;
 
-  /** @internal */ pixelWidth = -1;
-  /** @internal */ pixelHeight = -1;
+  /** @internal */ clientWidth = -1;
+  /** @internal */ clientHeight = -1;
   /** @internal */ pixelRatio = 1;
-  /** @internal */ drawingWidth = 0;
-  /** @internal */ drawingHeight = 0;
+  /** @internal */ canvasWidth = 0;
+  /** @internal */ canvasHeight = 0;
 
   mounted = false;
   paused = false;
@@ -76,7 +77,6 @@ export class Root extends Component {
 
   /** @internal */ _viewport: Viewport;
   /** @internal */ _viewbox: Viewbox;
-  /** @internal */ _camera: Matrix;
 
   constructor() {
     super();
@@ -168,6 +168,62 @@ export class Root extends Component {
   /** @internal */ _lastFrameTime = 0;
   /** @internal */ _mo_touch: number | null = null; // monitor touch
 
+  resizeCanvas() {
+    const newClientWidth = this.canvas.clientWidth;
+    const newClientHeight = this.canvas.clientHeight;
+
+    // canvas display size is not changed
+    if (this.clientWidth === newClientWidth && this.clientHeight === newClientHeight) return;
+
+    this.clientWidth = newClientWidth;
+    this.clientHeight = newClientHeight;
+
+    const notStyled =
+      this.canvas.clientWidth === this.canvas.width &&
+      this.canvas.clientHeight === this.canvas.height;
+
+    let pixelRatio: number;
+
+    if (notStyled) {
+      // If element is not styled, changing canvas rendering size will change its display size,
+      // which creates a loop of resizing. So we ignore pixel ratio and keep current rendering size.
+      pixelRatio = 1;
+      this.canvasWidth = this.canvas.width;
+      this.canvasHeight = this.canvas.height;
+    } else {
+      pixelRatio = this.pixelRatio;
+      this.canvasWidth = this.clientWidth * pixelRatio;
+      this.canvasHeight = this.clientHeight * pixelRatio;
+
+      if (this.canvas.width !== this.canvasWidth || this.canvas.height !== this.canvasHeight) {
+        // canvas rendering size is changed
+        this.canvas.width = this.canvasWidth;
+        this.canvas.height = this.canvasHeight;
+      }
+    }
+
+    console.debug &&
+      console.debug(
+        "Resize: [" +
+          this.canvasWidth +
+          ", " +
+          this.canvasHeight +
+          "] = " +
+          pixelRatio +
+          " x [" +
+          this.clientWidth +
+          ", " +
+          this.clientHeight +
+          "]",
+      );
+
+    this.viewport({
+      width: this.canvasWidth,
+      height: this.canvasHeight,
+      ratio: pixelRatio,
+    });
+  }
+
   /** @internal */
   onFrame = (now: number) => {
     this.frameRequested = false;
@@ -177,45 +233,7 @@ export class Root extends Component {
     }
 
     this.requestFrame();
-
-    const newPixelWidth = this.canvas.clientWidth;
-    const newPixelHeight = this.canvas.clientHeight;
-
-    if (this.pixelWidth !== newPixelWidth || this.pixelHeight !== newPixelHeight) {
-      // viewport pixel size is not the same as last time
-      this.pixelWidth = newPixelWidth;
-      this.pixelHeight = newPixelHeight;
-
-      this.drawingWidth = newPixelWidth * this.pixelRatio;
-      this.drawingHeight = newPixelHeight * this.pixelRatio;
-
-      if (this.canvas.width !== this.drawingWidth || this.canvas.height !== this.drawingHeight) {
-        // canvas size doesn't math
-        this.canvas.width = this.drawingWidth;
-        this.canvas.height = this.drawingHeight;
-
-        console.debug &&
-          console.debug(
-            "Resize: [" +
-              this.drawingWidth +
-              ", " +
-              this.drawingHeight +
-              "] = " +
-              this.pixelRatio +
-              " x [" +
-              this.pixelWidth +
-              ", " +
-              this.pixelHeight +
-              "]",
-          );
-
-        this.viewport({
-          width: this.drawingWidth,
-          height: this.drawingHeight,
-          ratio: this.pixelRatio,
-        });
-      }
-    }
+    this.resizeCanvas();
 
     const last = this._lastFrameTime || now;
     const elapsed = now - last;
@@ -234,12 +252,9 @@ export class Root extends Component {
       this._mo_touch = this._ts_touch;
       this.sleep = false;
 
-      if (this.drawingWidth > 0 && this.drawingHeight > 0) {
+      if (this.canvasWidth > 0 && this.canvasHeight > 0) {
         this.context.setTransform(1, 0, 0, 1, 0, 0);
-        this.context.clearRect(0, 0, this.drawingWidth, this.drawingHeight);
-        if (this.debugDrawAxis > 0) {
-          this.renderDebug(this.context);
-        }
+        this.context.clearRect(0, 0, this.canvasWidth, this.canvasHeight);
         this.render(this.context);
       }
     } else if (tickRequest) {
@@ -253,40 +268,11 @@ export class Root extends Component {
     stats.fps = elapsed ? 1000 / elapsed : 0;
   };
 
-  /** @hidden */
-  debugDrawAxis = 0;
-
-  private renderDebug(context: CanvasRenderingContext2D): void {
-    const size = typeof this.debugDrawAxis === "number" ? this.debugDrawAxis : 10;
-    const m = this.matrix();
-    context.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
-    const lineWidth = 3 / m.a;
-
-    context.beginPath();
-    context.moveTo(0, 0);
-    context.lineTo(0, 0.8 * size);
-    context.lineTo(-0.2 * size, 0.8 * size);
-    context.lineTo(0, size);
-    context.lineTo(+0.2 * size, 0.8 * size);
-    context.lineTo(0, 0.8 * size);
-    context.strokeStyle = "rgba(93, 173, 226)";
-    context.lineJoin = "round";
-    context.lineCap = "round";
-    context.lineWidth = lineWidth;
-    context.stroke();
-
-    context.beginPath();
-    context.moveTo(0, 0);
-    context.lineTo(0.8 * size, 0);
-    context.lineTo(0.8 * size, -0.2 * size);
-    context.lineTo(size, 0);
-    context.lineTo(0.8 * size, +0.2 * size);
-    context.lineTo(0.8 * size, 0);
-    context.strokeStyle = "rgba(236, 112, 99)";
-    context.lineJoin = "round";
-    context.lineCap = "round";
-    context.lineWidth = lineWidth;
-    context.stroke();
+  renderDebug(ctx: CanvasRenderingContext2D, m: Matrix) {
+    if (!this._debug) return;
+    ctx.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
+    ctx.lineWidth = 3 / m.a;
+    renderAxis(ctx, 10);
   }
 
   resume() {
@@ -362,7 +348,7 @@ export class Root extends Component {
         height: height,
         ratio: typeof ratio === "number" ? ratio : 1,
       };
-      this.viewbox();
+      this.rescale();
       const data = Object.assign({}, this._viewport);
       this.visit({
         start: function (component) {
@@ -384,7 +370,6 @@ export class Root extends Component {
   viewbox(width?: number, height?: number, mode?: FitMode): this;
   viewbox(width?: number | Viewbox, height?: number, mode?: FitMode): this {
     // TODO: static/fixed viewbox
-    // TODO: use css object-fit values
     if (typeof width === "number" && typeof height === "number") {
       this._viewbox = {
         width,
@@ -402,9 +387,11 @@ export class Root extends Component {
     return this;
   }
 
+  /** @hidden */
   camera(matrix: Matrix) {
-    this._camera = matrix;
-    this.rescale();
+    this._xf = matrix.clone();
+    this._pin._ts_transform = getIID();
+    this.touch();
     return this;
   }
 
@@ -412,36 +399,23 @@ export class Root extends Component {
   rescale() {
     const viewbox = this._viewbox;
     const viewport = this._viewport;
-    const camera = this._camera;
     if (viewport && viewbox) {
-      const viewportWidth = viewport.width;
-      const viewportHeight = viewport.height;
       const viewboxMode = isValidFitMode(viewbox.mode) ? viewbox.mode : "in-pad";
-      const viewboxWidth = viewbox.width;
-      const viewboxHeight = viewbox.height;
-
+      const fitted = fit(
+        viewbox.width,
+        viewbox.height,
+        viewport.width,
+        viewport.height,
+        viewboxMode,
+      );
       this.pin({
-        width: viewboxWidth,
-        height: viewboxHeight,
+        width: fitted.width,
+        height: fitted.height,
+        scaleX: fitted.scaleX,
+        scaleY: fitted.scaleY,
+        offsetX: -(viewbox.x || 0) * fitted.scaleX,
+        offsetY: -(viewbox.y || 0) * fitted.scaleY,
       });
-      this.fit(viewportWidth, viewportHeight, viewboxMode);
-
-      const viewboxX = viewbox.x || 0;
-      const viewboxY = viewbox.y || 0;
-
-      const cameraZoomX = camera?.a || 1;
-      const cameraZoomY = camera?.d || 1;
-      const cameraX = camera?.e || 0;
-      const cameraY = camera?.f || 0;
-
-      const scaleX = this.pin("scaleX");
-      const scaleY = this.pin("scaleY");
-
-      this.pin("scaleX", scaleX * cameraZoomX);
-      this.pin("scaleY", scaleY * cameraZoomY);
-
-      this.pin("offsetX", cameraX - viewboxX * scaleX * cameraZoomX);
-      this.pin("offsetY", cameraY - viewboxY * scaleY * cameraZoomY);
     } else if (viewport) {
       this.pin({
         width: viewport.width,