@thi.ng/text-canvas 2.3.6 → 2.4.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-06-09T16:14:01Z
+- **Last updated**: 2022-07-08T18:20:19Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,24 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/text-canvas@2.4.0) (2022-07-08)
+
+#### 🚀 Features
+
+- add canvasFromText(), update Canvas ([e8baa0b](https://github.com/thi-ng/umbrella/commit/e8baa0b))
+  - update deps
+  - add canvasFromText() factory fn
+  - add ICopy impl for Canvas
+- add clearFormat() ([83f04cc](https://github.com/thi-ng/umbrella/commit/83f04cc))
+- add blitMask() & docs ([a6cf74a](https://github.com/thi-ng/umbrella/commit/a6cf74a))
+
+### [2.3.8](https://github.com/thi-ng/umbrella/tree/@thi.ng/text-canvas@2.3.8) (2022-06-28)
+
+#### ♻️ Refactoring
+
+- update/simplify formatCanvas() ([e2f3ab9](https://github.com/thi-ng/umbrella/commit/e2f3ab9))
+  - re-use new single-line formatting fns from [@thi.ng/text-format](https://github.com/thi-ng/umbrella/tree/main/packages/text-format)
+
 ## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/text-canvas@2.3.0) (2022-04-07)
 
 #### 🚀 Features

package/README.md

@@ -70,7 +70,7 @@ node --experimental-repl-await
 > const textCanvas = await import("@thi.ng/text-canvas");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 5.36 KB
+Package sizes (gzipped, pre-treeshake): ESM: 5.24 KB
 
 ## Dependencies
 

package/canvas.d.ts

@@ -1,6 +1,6 @@
-import { Fn0, IGrid2D, NumOrString } from "@thi.ng/api";
+import { Fn0, ICopy, IGrid2D, NumOrString } from "@thi.ng/api";
 import { ClipRect, StrokeStyle } from "./api.js";
-export declare class Canvas implements IGrid2D<Uint32Array, number> {
+export declare class Canvas implements ICopy<Canvas>, IGrid2D<Uint32Array, number> {
     data: Uint32Array;
     size: [number, number];
     stride: [number, number];
@@ -13,6 +13,7 @@ export declare class Canvas implements IGrid2D<Uint32Array, number> {
     get height(): number;
     get offset(): number;
     get dim(): 2;
+    copy(): Canvas;
     order(): number[];
     includes(d0: number, d1: number): boolean;
     indexAt(d0: number, d1: number): number;
@@ -23,6 +24,19 @@ export declare class Canvas implements IGrid2D<Uint32Array, number> {
     setAtUnsafe(x: number, y: number, col: number): boolean;
 }
 export declare const canvas: (width: number, height: number, format?: number, style?: StrokeStyle) => Canvas;
+/**
+ * Creates and returns a new {@link Canvas} from given string/lines array and
+ * optional default `format` and/or initial `fill` value.
+ *
+ * @remarks
+ * The canvas will use the longest line width as its width and the length of the
+ * source array as height.
+ *
+ * @param lines
+ * @param format
+ * @param fill
+ */
+export declare const canvasFromText: (lines: string[], format?: number, fill?: NumOrString) => Canvas;
 export declare const beginClip: (canvas: Canvas, x: number, y: number, w: number, h: number) => void;
 export declare const endClip: (canvas: Canvas) => any;
 export declare const withClip: (canvas: Canvas, x: number, y: number, w: number, h: number, fn: Fn0<any>) => void;

package/canvas.js

@@ -1,12 +1,17 @@
+var Canvas_1;
 import { __decorate } from "tslib";
 import { nomixin } from "@thi.ng/api";
 import { IGrid2DMixin } from "@thi.ng/api/mixins/igrid";
 import { peek } from "@thi.ng/arrays/peek";
+import { assert } from "@thi.ng/errors/assert";
 import { clamp } from "@thi.ng/math/interval";
-import { NONE } from "@thi.ng/text-format/api";
+import { NONE } from "@thi.ng/text-format";
+import { map } from "@thi.ng/transducers/map";
+import { max } from "@thi.ng/transducers/max";
+import { transduce } from "@thi.ng/transducers/transduce";
 import { STYLE_ASCII } from "./api.js";
 import { charCode, intersectRect } from "./utils.js";
-let Canvas = class Canvas {
+let Canvas = Canvas_1 = class Canvas {
     constructor(width, height, format = NONE, style = STYLE_ASCII) {
         this.size = [width, height];
         this.stride = [1, this.width];
@@ -29,6 +34,14 @@ let Canvas = class Canvas {
     get dim() {
         return 2;
     }
+    copy() {
+        const res = new Canvas_1(this.width, this.height, this.format);
+        res.data.set(this.data);
+        res.stride = this.stride.slice();
+        res.styles = this.styles.slice();
+        res.clipRects = this.clipRects.slice();
+        return res;
+    }
     // @ts-ignore mixin
     order() { }
     // @ts-ignore mixin
@@ -53,11 +66,38 @@ let Canvas = class Canvas {
 __decorate([
     nomixin
 ], Canvas.prototype, "setAt", null);
-Canvas = __decorate([
+Canvas = Canvas_1 = __decorate([
     IGrid2DMixin
 ], Canvas);
 export { Canvas };
 export const canvas = (width, height, format, style) => new Canvas(width, height, format, style);
+/**
+ * Creates and returns a new {@link Canvas} from given string/lines array and
+ * optional default `format` and/or initial `fill` value.
+ *
+ * @remarks
+ * The canvas will use the longest line width as its width and the length of the
+ * source array as height.
+ *
+ * @param lines
+ * @param format
+ * @param fill
+ */
+export const canvasFromText = (lines, format = NONE, fill) => {
+    const height = lines.length;
+    assert(height > 0, "require at least 1 line of text");
+    const width = transduce(map((x) => x.length), max(), lines);
+    const res = canvas(width, height, format);
+    fill !== undefined && res.data.fill(charCode(fill, format));
+    format <<= 16;
+    for (let y = 0; y < height; y++) {
+        const line = lines[y];
+        for (let x = 0, i = y * width, n = Math.min(width, line.length); x < n; x++, i++) {
+            res.data[i] = line.charCodeAt(x) | format;
+        }
+    }
+    return res;
+};
 export const beginClip = (canvas, x, y, w, h) => {
     x |= 0;
     y |= 0;

package/format.d.ts

@@ -6,7 +6,7 @@ import type { Canvas } from "./canvas.js";
  * any character format data.
  *
  * @param canvas -
- * @param format -
+ * @param fmt -
  */
-export declare const formatCanvas: (canvas: Canvas, format?: StringFormat) => string;
+export declare const formatCanvas: (canvas: Canvas, fmt?: StringFormat) => string;
 //# sourceMappingURL=format.d.ts.map

package/format.js

@@ -1,43 +1,24 @@
+import { format, formatNone } from "@thi.ng/text-format/format";
 /**
  * Returns string representation of canvas, optionally using given string
  * formatter. If none is given, returns plain string representation, ignoring
  * any character format data.
  *
  * @param canvas -
- * @param format -
+ * @param fmt -
  */
-export const formatCanvas = (canvas, format) => {
+export const formatCanvas = (canvas, fmt) => {
     const { data, width, height } = canvas;
     const res = [];
-    if (format) {
-        const { start, end, prefix, suffix, zero } = format;
-        let prevID, ch, id;
-        const check = zero ? () => prevID !== -1 : () => prevID !== 0;
-        for (let y = 0, i = 0; y < height; y++) {
-            prevID = zero ? -1 : 0;
-            res.push(prefix);
-            for (let x = 0; x < width; x++, i++) {
-                ch = data[i];
-                id = ch >>> 16;
-                if (id != prevID) {
-                    check() && res.push(end);
-                    (zero || id) && res.push(start(id));
-                    prevID = id;
-                }
-                res.push(String.fromCharCode(ch & 0xffff));
-            }
-            check() && res.push(end);
-            res.push(suffix);
+    if (fmt) {
+        for (let y = 0; y < height; y++) {
+            res.push(format(fmt, data, width, y * width));
         }
-        return res.join("");
     }
     else {
-        for (let y = 0, i = 0; y < height; y++) {
-            for (let x = 0; x < width; x++, i++) {
-                res.push(String.fromCharCode(data[i] & 0xffff));
-            }
-            res.push("\n");
+        for (let y = 0; y < height; y++) {
+            res.push(formatNone(data, width, y * width));
         }
-        return res.join("");
     }
+    return res.join("");
 };

package/image.d.ts

@@ -1,7 +1,51 @@
-import type { UIntArray } from "@thi.ng/api";
+import type { NumOrString, UIntArray } from "@thi.ng/api";
 import { ImageOpts } from "./api.js";
 import { Canvas } from "./canvas.js";
-export declare const blit: (canvas: Canvas, x: number, y: number, src: Canvas) => void;
+export declare const blit: (dest: Canvas, x: number, y: number, src: Canvas) => void;
+/**
+ * Similar to {@link blit}. Pastes `src` {@link Canvas} into `dest` at given
+ * position and uses `mask` to exclude pixels from being copied (and therefore
+ * achieve a form of 1bit transparency, similar to GIFs), i.e. only non-`mask`
+ * pixels/chars will be copied. Supports region clipping.
+ *
+ * @example
+ * ```ts
+ * // source canvas
+ * const a = canvasFromText([
+ *   "###==###",
+ *   "##====##",
+ *   "#======#",
+ *   "##====##",
+ *   "###==###",
+ * ]);
+ *
+ * // destination canvas (filled w/ "-")
+ * const b = canvas(12,7);
+ * clear(b, true, "-");
+ *
+ * // paste `a` several times into `b` using "#" as mask
+ * blitMask(b, -4, -2, a, "#"); // top-left (partially outside)
+ * blitMask(b, 2, 1, a, "#");   // center
+ * blitMask(b, 8, 4, a, "#");   // bottom-right (part outside)
+ *
+ * // show result
+ * console.log(formatCanvas(b))
+ * // ===---------
+ * // ==---==-----
+ * // =---====----
+ * // ---======---
+ * // ----====---=
+ * // -----==---==
+ * // ---------===
+ * ```
+ *
+ * @param dest
+ * @param x
+ * @param y
+ * @param src
+ * @param mask
+ */
+export declare const blitMask: (dest: Canvas, x: number, y: number, src: Canvas, mask?: NumOrString) => void;
 export declare const resize: (canvas: Canvas, newWidth: number, newHeight: number) => void;
 export declare const extract: (canvas: Canvas, x: number, y: number, w: number, h: number) => Canvas;
 /**

package/image.js

@@ -1,3 +1,4 @@
+import { blit1d } from "@thi.ng/arrays/blit";
 import { peek } from "@thi.ng/arrays/peek";
 import { isNumber } from "@thi.ng/checks/is-number";
 import { clamp0 } from "@thi.ng/math/interval";
@@ -6,12 +7,12 @@ import { SHADES_BLOCK } from "./api.js";
 import { canvas, Canvas } from "./canvas.js";
 import { formatCanvas } from "./format.js";
 import { charCode, intersectRect } from "./utils.js";
-export const blit = (canvas, x, y, src) => {
+export const blit = (dest, x, y, src) => {
     x |= 0;
     y |= 0;
     const { data: sbuf, width: sw, height: sh } = src;
-    const { data: dbuf, width: dw } = canvas;
-    const { x1, y1, y2, w: iw, h: ih, } = intersectRect({ x1: x, y1: y, x2: x + sw, y2: y + sh, w: sw, h: sh }, peek(canvas.clipRects));
+    const { data: dbuf, width: dw } = dest;
+    const { x1, y1, y2, w: iw, h: ih, } = intersectRect({ x1: x, y1: y, x2: x + sw, y2: y + sh, w: sw, h: sh }, peek(dest.clipRects));
     if (!iw || !ih)
         return;
     const sx = clamp0(x1 - x);
@@ -22,6 +23,66 @@ export const blit = (canvas, x, y, src) => {
         dbuf.set(sbuf.subarray(sidx, sidx + iw), didx);
     }
 };
+/**
+ * Similar to {@link blit}. Pastes `src` {@link Canvas} into `dest` at given
+ * position and uses `mask` to exclude pixels from being copied (and therefore
+ * achieve a form of 1bit transparency, similar to GIFs), i.e. only non-`mask`
+ * pixels/chars will be copied. Supports region clipping.
+ *
+ * @example
+ * ```ts
+ * // source canvas
+ * const a = canvasFromText([
+ *   "###==###",
+ *   "##====##",
+ *   "#======#",
+ *   "##====##",
+ *   "###==###",
+ * ]);
+ *
+ * // destination canvas (filled w/ "-")
+ * const b = canvas(12,7);
+ * clear(b, true, "-");
+ *
+ * // paste `a` several times into `b` using "#" as mask
+ * blitMask(b, -4, -2, a, "#"); // top-left (partially outside)
+ * blitMask(b, 2, 1, a, "#");   // center
+ * blitMask(b, 8, 4, a, "#");   // bottom-right (part outside)
+ *
+ * // show result
+ * console.log(formatCanvas(b))
+ * // ===---------
+ * // ==---==-----
+ * // =---====----
+ * // ---======---
+ * // ----====---=
+ * // -----==---==
+ * // ---------===
+ * ```
+ *
+ * @param dest
+ * @param x
+ * @param y
+ * @param src
+ * @param mask
+ */
+export const blitMask = (dest, x, y, src, mask = 0x20) => {
+    x |= 0;
+    y |= 0;
+    const { data: sbuf, width: sw, height: sh } = src;
+    const { data: dbuf, width: dw } = dest;
+    const { x1, y1, y2, w: iw, h: ih, } = intersectRect({ x1: x, y1: y, x2: x + sw, y2: y + sh, w: sw, h: sh }, peek(dest.clipRects));
+    if (!iw || !ih)
+        return;
+    const sx = clamp0(x1 - x);
+    const sy = clamp0(y1 - y);
+    mask = charCode(mask, 0);
+    for (let yy = sy, dy = y1; dy < y2; yy++, dy++) {
+        let sidx = sx + yy * sw;
+        let didx = x1 + dy * dw;
+        blit1d(dbuf, didx, sbuf.subarray(sidx, sidx + iw), mask);
+    }
+};
 export const resize = (canvas, newWidth, newHeight) => {
     if (canvas.width === newWidth && canvas.height === newHeight)
         return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/text-canvas",
-  "version": "2.3.6",
+  "version": "2.4.0",
   "description": "Text based canvas, drawing, tables with arbitrary formatting (incl. ANSI/HTML)",
   "type": "module",
   "module": "./index.js",
@@ -35,13 +35,14 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.3.7",
-    "@thi.ng/arrays": "^2.2.5",
+    "@thi.ng/arrays": "^2.3.0",
     "@thi.ng/checks": "^3.2.1",
-    "@thi.ng/geom-clip-line": "^2.1.15",
+    "@thi.ng/errors": "^2.1.7",
+    "@thi.ng/geom-clip-line": "^2.1.18",
     "@thi.ng/math": "^5.3.3",
     "@thi.ng/strings": "^3.3.5",
-    "@thi.ng/text-format": "^1.1.7",
-    "@thi.ng/transducers": "^8.3.5"
+    "@thi.ng/text-format": "^1.2.0",
+    "@thi.ng/transducers": "^8.3.6"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.25.0",
@@ -138,5 +139,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "f50e292ecc7dc74a6705b07fc739bf827cc5efd7\n"
+  "gitHead": "e64b1ab39ae9bcc494ef006f6329e5182fa2a326\n"
 }

package/rect.d.ts

@@ -10,6 +10,13 @@ import type { Canvas } from "./canvas.js";
  * @param code -
  */
 export declare const clear: (canvas: Canvas, reset?: boolean, code?: NumOrString) => void;
+/**
+ * Clears or resets format of entire canvas.
+ *
+ * @param canvas -
+ * @param format -
+ */
+export declare const clearFormat: ({ data }: Canvas, format?: number) => void;
 /**
  * Fills given rect with char, taking currect clip rect and format into
  * account.

package/rect.js

@@ -1,4 +1,5 @@
 import { peek } from "@thi.ng/arrays/peek";
+import { NONE } from "@thi.ng/text-format/api";
 import { hline, vline } from "./hvline.js";
 import { charCode } from "./utils.js";
 /**
@@ -25,6 +26,17 @@ export const clear = (canvas, reset = false, code = 0x20) => {
         canvas.data.fill(code);
     }
 };
+/**
+ * Clears or resets format of entire canvas.
+ *
+ * @param canvas -
+ * @param format -
+ */
+export const clearFormat = ({ data }, format = NONE) => {
+    format <<= 16;
+    for (let i = data.length; i-- > 0;)
+        data[i] = (data[i] & 0xffff) | format;
+};
 /**
  * Fills given rect with char, taking currect clip rect and format into
  * account.