@ohos-ports/html2canvas-pro 0.0.0-stage → 2.3.2-beta.0

package/dist/types/render/canvas/text/text-decoration-renderer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Text Decoration Renderer
+ *
+ * Handles rendering of text-decoration lines:
+ * - underline, overline, line-through
+ * - solid, double, dotted, dashed, wavy styles
+ * Extracted from TextRenderer to reduce file size.
+ */
+import { Bounds } from '../../../css/layout/bounds';
+import { CSSParsedDeclaration } from '../../../css';
+export declare class TextDecorationRenderer {
+    private readonly ctx;
+    constructor(ctx: CanvasRenderingContext2D);
+    render(bounds: Bounds, styles: CSSParsedDeclaration): void;
+    private draw;
+    private drawPattern;
+    private drawWavy;
+}

package/dist/types/render/canvas/text-renderer.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Text Renderer
+ *
+ * Handles rendering of text content including:
+ * - Text with letter spacing
+ * - Text decorations (underline, overline, line-through)
+ * - Text shadows
+ * - Webkit line clamp
+ * - Text overflow ellipsis
+ * - Paint order (fill/stroke)
+ * - Font styles
+ */
+import { TextContainer } from '../../dom/text-container';
+import { CSSParsedDeclaration } from '../../css';
+import { Bounds } from '../../css/layout/bounds';
+import { TextBounds } from '../../css/layout/text';
+import { WRITING_MODE } from '../../css/property-descriptors/writing-mode';
+/**
+ * Dependencies required for TextRenderer
+ */
+export interface TextRendererDependencies {
+    ctx: CanvasRenderingContext2D;
+    options: {
+        scale: number;
+    };
+}
+export declare const hasCJKCharacters: (text: string) => boolean;
+/**
+ * Text Renderer
+ *
+ * Specialized renderer for text content.
+ * Extracted from CanvasRenderer to improve code organization and maintainability.
+ */
+export declare class TextRenderer {
+    private readonly ctx;
+    private readonly options;
+    private readonly decorationRenderer;
+    /**
+     * Per-render glyph width cache. Keyed by glyph + font string,
+     * avoids redundant `measureText` calls when letter-spacing is non-zero.
+     * Cleared at the start of each renderTextNode call.
+     */
+    private glyphWidthCache;
+    constructor(deps: TextRendererDependencies);
+    /**
+     * Returns the cached width for a glyph+font pair, measuring via
+     * measureText if not yet cached. Only used when letterSpacing !== 0
+     * (the `canRenderWholeText` fast path handles the zero-spacing case).
+     */
+    private cachedMeasureText;
+    /**
+     * Iterate grapheme clusters one-by-one, applying correct letter-spacing and
+     * per-script baseline for each character.
+     *
+     * Issue #73: When letter-spacing is non-zero, text must be rendered character by
+     * character. This helper centralises two fixes applied during that iteration:
+     *   1. Add `letterSpacing` to each character's advance width (was previously
+     *      omitted, causing characters to render without any spacing).
+     *   2. Switch to the ideographic baseline for CJK glyphs so their vertical
+     *      position matches how browsers lay them out in the DOM.
+     *
+     * The `renderFn` callback receives (letter, x, y) and performs the actual draw
+     * call (fillText or strokeText), allowing fill and stroke paths to share one
+     * implementation.
+     */
+    private iterateLettersWithLetterSpacing;
+    private iterateVerticalGlyphs;
+    /**
+     * Render text with letter-spacing applied (fill pass).
+     * When letterSpacing is 0 the whole string is drawn in one call; otherwise each
+     * grapheme is drawn individually so spacing and CJK baseline are applied correctly.
+     */
+    renderTextWithLetterSpacing(text: TextBounds, letterSpacing: number, baseline: number, writingMode?: WRITING_MODE): void;
+    private canRenderWholeText;
+    private renderFillText;
+    private renderStrokeText;
+    private renderTextStrokeWithStyle;
+    private renderTextFillWithShadows;
+    /**
+     * Helper method to render text with paint order support
+     * Reduces code duplication in line-clamp and normal rendering
+     */
+    private renderTextBoundWithPaintOrder;
+    private renderTextDecoration;
+    private truncateTextWithEllipsis;
+    /**
+     * Create font style array
+     * Public method used by list rendering
+     */
+    createFontStyle(styles: CSSParsedDeclaration): string[];
+    /**
+     * Render text with -webkit-line-clamp truncation.
+     * Groups text bounds by their Y position into visual lines, then renders
+     * only the first N-1 complete lines followed by an ellipsis on the Nth line.
+     */
+    private renderLineClampedText;
+    /**
+     * Render single-line text with text-overflow: ellipsis.
+     * Returns true if ellipsis was applied (caller should skip normal rendering).
+     */
+    private renderEllipsisText;
+    renderTextNode(text: TextContainer, styles: CSSParsedDeclaration, containerBounds?: Bounds): Promise<void>;
+}

package/dist/types/render/effects.d.ts

@@ -0,0 +1,112 @@
+import { Matrix } from '../css/property-descriptors/transform';
+import { MixBlendMode } from '../css/property-descriptors/mix-blend-mode';
+import { Path } from './path';
+export declare const enum EffectType {
+    TRANSFORM = 0,
+    CLIP = 1,
+    OPACITY = 2,
+    CLIP_PATH = 3,
+    BLEND = 4,
+    FILTER = 5
+}
+export declare const enum EffectTarget {
+    BACKGROUND_BORDERS = 2,
+    CONTENT = 4
+}
+export interface IElementEffect {
+    readonly type: EffectType;
+    readonly target: number;
+}
+export declare class TransformEffect implements IElementEffect {
+    readonly offsetX: number;
+    readonly offsetY: number;
+    readonly matrix: Matrix;
+    readonly type: EffectType;
+    readonly target: number;
+    constructor(offsetX: number, offsetY: number, matrix: Matrix);
+}
+export declare class ClipEffect implements IElementEffect {
+    readonly path: Path[];
+    readonly target: EffectTarget;
+    readonly type: EffectType;
+    constructor(path: Path[], target: EffectTarget);
+}
+export declare class OpacityEffect implements IElementEffect {
+    readonly opacity: number;
+    readonly type: EffectType;
+    readonly target: number;
+    constructor(opacity: number);
+}
+/**
+ * Clips the element and all its descendants to an arbitrary canvas-drawn shape.
+ * The `applyClip` callback is responsible for calling beginPath, the shape
+ * operations, and ctx.clip() — giving each shape type full control over how
+ * the path is constructed (arc, ellipse, lineTo, Path2D, etc.).
+ */
+export declare class ClipPathEffect implements IElementEffect {
+    readonly applyClip: (ctx: CanvasRenderingContext2D) => void;
+    readonly type: EffectType;
+    readonly target: number;
+    constructor(applyClip: (ctx: CanvasRenderingContext2D) => void);
+}
+export declare class BlendEffect implements IElementEffect {
+    readonly mixBlendMode: MixBlendMode;
+    readonly type: EffectType;
+    readonly target: number;
+    readonly compositeOperation: GlobalCompositeOperation;
+    constructor(mixBlendMode: MixBlendMode);
+}
+export declare class FilterEffect implements IElementEffect {
+    readonly type: EffectType;
+    readonly target: number;
+    /** CSS filter string with drop-shadow() stripped (safe for ctx.filter). */
+    readonly safeFilterString: string;
+    /** Shadow params for drop-shadow(), if present and successfully parsed. */
+    readonly shadow?: {
+        offsetX: number;
+        offsetY: number;
+        blur: number;
+        color: string;
+    };
+    constructor(filterString: string);
+    /**
+     * Parse a CSS filter string, extracting drop-shadow() parameters for
+     * rendering via ctx.shadow* (which avoids canvas taint), and producing
+     * a safe filter string with all drop-shadow() calls removed.
+     *
+     * Uses paren-depth tracking to correctly handle nested function
+     * arguments — e.g. rgba() / hsla() inside drop-shadow() — which
+     * the previous regex-based approach ([^)]+) could not handle.
+     *
+     * Per CSS spec the shadow value is: <color>? && <length>{2,3}
+     * (components can appear in any order).
+     */
+    private static parseDropShadow;
+    /**
+     * Find all drop-shadow() function calls in a CSS filter string.
+     * Uses paren-depth tracking to correctly skip over nested
+     * parentheses (e.g. rgba(0, 0, 0, 0.15)).
+     */
+    private static findDropShadows;
+    /**
+     * Parse the body of a single drop-shadow() function.
+     * Body format (order-independent): <offsetX> <offsetY> [<blur>] [<color>?]
+     */
+    private static parseDropShadowBody;
+    /**
+     * Split whitespace-separated tokens while keeping parenthesised
+     * expressions intact.
+     *
+     * e.g. "rgba(0, 0, 0, 0.15) 0px 1px 2px"
+     *   → ["rgba(0, 0, 0, 0.15)", "0px", "1px", "2px"]
+     */
+    private static tokenizeFilterArgs;
+    /** True when token looks like a CSS length: number with optional unit. */
+    private static isCSSLength;
+}
+export declare const isTransformEffect: (effect: IElementEffect) => effect is TransformEffect;
+export declare const isClipEffect: (effect: IElementEffect) => effect is ClipEffect;
+export declare const isOpacityEffect: (effect: IElementEffect) => effect is OpacityEffect;
+export declare const isClipPathEffect: (effect: IElementEffect) => effect is ClipPathEffect;
+export declare const isBlendEffect: (effect: IElementEffect) => effect is BlendEffect;
+export declare const isFilterEffect: (effect: IElementEffect) => effect is FilterEffect;

package/dist/types/render/font-metrics.d.ts

@@ -0,0 +1,11 @@
+export interface FontMetric {
+    baseline: number;
+    middle: number;
+}
+export declare class FontMetrics {
+    private readonly _data;
+    private readonly _document;
+    constructor(document: Document);
+    private parseMetrics;
+    getMetrics(fontFamily: string, fontSize: string): FontMetric;
+}

package/dist/types/render/object-fit.d.ts

@@ -0,0 +1,19 @@
+import { ObjectFit } from '../css/property-descriptors/object-fit';
+import { LengthPercentage } from '../css/types/length-percentage';
+export interface ObjectFitBox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+export interface ObjectFitRendering {
+    sx: number;
+    sy: number;
+    sw: number;
+    sh: number;
+    dx: number;
+    dy: number;
+    dw: number;
+    dh: number;
+}
+export declare const calculateObjectFitRendering: (intrinsicWidth: number, intrinsicHeight: number, box: ObjectFitBox, objectFit: ObjectFit, objectPosition?: [LengthPercentage, LengthPercentage]) => ObjectFitRendering;

package/dist/types/render/path.d.ts

@@ -0,0 +1,13 @@
+import { BezierCurve } from './bezier-curve';
+import { Vector } from './vector';
+export declare const enum PathType {
+    VECTOR = 0,
+    BEZIER_CURVE = 1
+}
+export interface IPath {
+    type: PathType;
+    add(deltaX: number, deltaY: number): IPath;
+}
+export declare const equalPath: (a: Path[], b: Path[]) => boolean;
+export declare const transformPath: (path: Path[], deltaX: number, deltaY: number, deltaW: number, deltaH: number) => Path[];
+export type Path = Vector | BezierCurve;

package/dist/types/render/renderer-interface.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Base interface for all specialized renderers.
+ * Each renderer is responsible for rendering a specific aspect of an element.
+ *
+ * @internal This interface is a structural contract; prefer using concrete
+ *           renderer classes (BackgroundRenderer, BorderRenderer, etc.)
+ *           directly rather than relying on the generic IRenderer shape.
+ */
+export interface IRenderer {
+    render(...args: unknown[]): void | Promise<void>;
+}
+/**
+ * Common dependencies required by renderers.
+ * RenderConfigurations from canvas-renderer.ts provides a concrete type.
+ */
+export interface RendererDependencies {
+    ctx: CanvasRenderingContext2D;
+    scale: number;
+    options: Record<string, unknown>;
+}
+/**
+ * Performance tracking for renderers.
+ */
+export interface RenderMetrics {
+    renderCount: number;
+    totalTime: number;
+    averageTime: number;
+}

package/dist/types/render/stacking-context.d.ts

@@ -0,0 +1,49 @@
+import { ElementContainer } from '../dom/element-container';
+import { BoundCurves } from './bound-curves';
+import { ClipPathEffect, EffectTarget, IElementEffect } from './effects';
+import { Bounds } from '../css/layout/bounds';
+import { ClipPathValue, ShapeRadius } from '../css/property-descriptors/clip-path';
+export declare class StackingContext {
+    element: ElementPaint;
+    negativeZIndex: StackingContext[];
+    zeroOrAutoZIndexOrTransformedOrOpacity: StackingContext[];
+    positiveZIndex: StackingContext[];
+    nonPositionedFloats: StackingContext[];
+    nonPositionedInlineLevel: StackingContext[];
+    inlineLevel: ElementPaint[];
+    nonInlineLevel: ElementPaint[];
+    constructor(container: ElementPaint);
+}
+export declare class ElementPaint {
+    readonly container: ElementContainer;
+    readonly parent: ElementPaint | null;
+    readonly effects: IElementEffect[];
+    readonly curves: BoundCurves;
+    listValue?: string;
+    constructor(container: ElementContainer, parent: ElementPaint | null);
+    getEffects(target: EffectTarget): IElementEffect[];
+}
+/** @internal – exported for testing only. */
+export declare const hasOverflowClip: (styles: ElementContainer["styles"]) => boolean;
+/**
+ * Resolve a `closest-side` or `farthest-side` shape-radius keyword to pixels
+ * for a single axis. Used by both `circle()` (per-axis) and `ellipse()`.
+ *
+ * @param r       - The ShapeRadius (keyword or length-percentage).
+ * @param center  - Absolute center coordinate on this axis (cx or cy).
+ * @param start   - Absolute start of the reference box on this axis.
+ * @param end     - Absolute end of the reference box on this axis.
+ * @param dimRef  - Reference dimension for resolving a length-percentage value.
+ * @internal – exported for testing only.
+ */
+export declare const resolveAxisRadius: (r: ShapeRadius, center: number, start: number, end: number, dimRef: number) => number;
+/**
+ * Convert a parsed ClipPathValue + element bounds into a ClipPathEffect whose
+ * `applyClip` callback draws the clip shape directly onto the canvas context.
+ *
+ * All coordinates are computed in page-absolute space at construction time so
+ * the callback itself is allocation-free and executes synchronously.
+ * @internal – exported for testing only.
+ */
+export declare const buildClipPathEffect: (clipPath: ClipPathValue, bounds: Bounds) => ClipPathEffect | null;
+export declare const parseStackingContexts: (container: ElementContainer) => StackingContext;

package/dist/types/render/vector.d.ts

@@ -0,0 +1,9 @@
+import { IPath, Path, PathType } from './path';
+export declare class Vector implements IPath {
+    type: PathType;
+    x: number;
+    y: number;
+    constructor(x: number, y: number);
+    add(deltaX: number, deltaY: number): Vector;
+}
+export declare const isVector: (path: Path) => path is Vector;

package/package.json

@@ -1,6 +1,141 @@
 {
   "name": "@ohos-ports/html2canvas-pro",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Screenshots with JavaScript. Next generation!",
+  "type": "module",
+  "main": "dist/html2canvas-pro.cjs",
+  "module": "dist/html2canvas-pro.esm.js",
+  "typings": "dist/types/index.d.ts",
+  "browser": "dist/html2canvas-pro.esm.js",
+  "sideEffects": false,
+  "files": [
+    "dist/",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/html2canvas-pro.esm.js",
+      "require": "./dist/html2canvas-pro.cjs",
+      "default": "./dist/html2canvas-pro.esm.js"
+    }
+  },
+  "version": "2.3.2-beta.0",
+  "author": {
+    "name": "yorickshan",
+    "email": "yorickshan@gmail.com",
+    "url": "https://github.com/yorickshan"
+  },
+  "license": "MIT",
+  "keywords": [
+    "html2canvas",
+    "screenshot"
+  ],
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "homepage": "https://yorickshan.github.io/html2canvas-pro/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ohos-ports/ohos-ports.git",
+    "directory": "ports/html2canvas-pro/2.3.2"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.2.0",
+    "@types/chai": "^5.2.3",
+    "@types/express": "^5.0.6",
+    "@types/karma": "^6.3.0",
+    "@types/mocha": "^10.0.7",
+    "@types/node": "^25.0.3",
+    "@types/platform": "^1.3.4",
+    "@types/pngjs": "^6.0.5",
+    "@types/serve-index": "^1.9.4",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "appium-ios-simulator": "^8.0.9",
+    "base64-arraybuffer": "1.0.2",
+    "body-parser": "^2.2.1",
+    "chai": "6.2.2",
+    "change-case": "^5.4.4",
+    "conventional-changelog": "^7.2.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "cors": "^2.8.5",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^9.13.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "express": "^5.2.1",
+    "filenamify-url": "4.0.0",
+    "glob": "^13.0.0",
+    "husky": "^9.1.7",
+    "jsdom": "^29.1.1",
+    "karma": "^6.3.2",
+    "karma-chrome-launcher": "^3.1.0",
+    "karma-edge-launcher": "^0.4.2",
+    "karma-firefox-launcher": "^2.1.0",
+    "karma-ie-launcher": "^1.0.0",
+    "karma-junit-reporter": "^2.0.1",
+    "karma-mocha": "^2.0.1",
+    "karma-safarinative-launcher": "^1.1.0",
+    "lint-staged": "^16.2.7",
+    "mocha": "^11.7.5",
+    "node-simctl": "^8.1.2",
+    "pixelmatch": "^7.2.0",
+    "platform": "^1.3.6",
+    "pngjs": "^7.0.0",
+    "prettier": "^3.3.3",
+    "puppeteer": "^25.6.0-beta.0",
+    "replace-in-file": "^8.4.0",
+    "rimraf": "^6.0.1",
+    "rolldown": "^1.2.6-beta.4",
+    "serve-index": "^1.9.1",
+    "slash": "5.1.0",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.22.4-beta.4",
+    "typedoc": "^0.28.19",
+    "typescript": "^5.5.4",
+    "vitepress": "^1.6.4",
+    "vitest": "^5.0.1-beta.0",
+    "yargs": "^18.0.0"
+  },
+  "dependencies": {
+    "css-line-break": "^2.1.0",
+    "text-segmentation": "^1.0.3"
+  },
+  "lint-staged": {
+    "{src,tests}/**/*.ts": [
+      "prettier --write",
+      "eslint --fix"
+    ]
+  },
+  "scripts": {
+    "prebuild": "rimraf dist/ && rimraf build/ && mkdir -p dist && mkdir -p build",
+    "build": "tsc --module commonjs -p tsconfig.build.json && rolldown -c rolldown.config.ts && pnpm build:create-reftest-list && rolldown -c tests/rolldown.testrunner.config.ts",
+    "build:testrunner": "rolldown -c tests/rolldown.testrunner.config.ts",
+    "build:reftest-result-list": "tsx scripts/create-reftest-result-list.ts",
+    "build:create-reftest-list": "tsx scripts/create-reftest-list.ts tests/reftests/ignore.txt build/reftests.js",
+    "release": "sh scripts/version-upgrade.sh",
+    "format": "prettier --write \"{src,tests,scripts}/**/*.ts\"",
+    "lint": "eslint src/**/*.ts --max-warnings 0",
+    "test": "pnpm lint && pnpm unittest && pnpm karma",
+    "unittest": "vitest run",
+    "unittest:coverage": "vitest run --coverage",
+    "bench:css-parse": "tsx scripts/benchmarks/css-parse.bench.ts",
+    "reftests-diff": "mkdir -p tmp/snapshots && vitest run --config vitest.reftest.config.ts",
+    "prekarma": "node scripts/ensure-karma-prereqs.mjs",
+    "karma": "tsx tests/karma",
+    "watch": "rolldown -w",
+    "watch:unittest": "vitest",
+    "start": "tsx tests/server --port=8080 --cors=8081",
+    "commitlint": "commitlint --config .commitlintrc.json -e -V",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "docs:api": "typedoc",
+    "docs:api:watch": "typedoc --watch"
+  },
+  "bugs": {
+    "url": "https://github.com/ohos-ports/ohos-ports/issues"
+  }
+}