@thi.ng/hiccup-svg 4.3.39 → 5.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-14T13:27:19Z
+- **Last updated**: 2023-04-08T11:09:50Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,26 @@ 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.
 
+# [5.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/hiccup-svg@5.0.0) (2023-04-08)
+
+#### 🛑 Breaking changes
+
+- update svgDoc() conversion handling ([f0e9092](https://github.com/thi-ng/umbrella/commit/f0e9092))
+- BREAKING CHANGE: update svgDoc(), rename `convert` attrib => `__convert`
+  - for consistency, keep all control attribs prefixed as `__xxx`
+
+#### 🚀 Features
+
+- add support for precision attribute ([f81d0d8](https://github.com/thi-ng/umbrella/commit/f81d0d8))
+  - update convertTree() to allow dynamic floating point precision
+    handling via `__prec` control attrib
+  - update docs
+  - add tests
+
+#### 🩹 Bug fixes
+
+- update ff() to always return string ([ae1d844](https://github.com/thi-ng/umbrella/commit/ae1d844))
+
 ## [4.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/hiccup-svg@4.3.0) (2022-06-20)
 
 #### 🚀 Features

package/README.md

@@ -159,7 +159,7 @@ For Node.js REPL:
 const hiccupSvg = await import("@thi.ng/hiccup-svg");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.31 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.36 KB
 
 ## Dependencies
 

package/convert.d.ts

@@ -1,10 +1,20 @@
 /**
- * Takes a normalized hiccup tree of [`thi.ng/geom`](https://thi.ng/geom) or
+ * Takes a normalized hiccup tree of [`thi.ng/geom`](https://thi.ng/geom) and/or
  * [thi.ng/hdom-canvas](https://thi.ng/hdom-canvas) shape definitions and
- * recursively converts it into an hiccup flavor which is compatible for SVG
- * serialization. This conversion also involves translation & reorg of various
- * attributes. Returns new tree. The original remains untouched, as will any
- * unrecognized tree/shape nodes.
+ * recursively converts it into an hiccup flavor which is compatible for direct
+ * SVG serialization. This conversion also involves translation, stringification
+ * & reorg of various attributes. The function returns new tree. The original
+ * remains untouched, as will any unrecognized tree/shape nodes.
+ *
+ * @remarks
+ * The `__prec` control attribute can be used (on a per-shape basis) to control
+ * the formatting used for various floating point values (except color
+ * conversions). See {@link setPrecision}. Child shapes (of a group) inherit the
+ * precision setting of their parent.
+ *
+ * To control the formatting precision for colors, use [the relevant function in
+ * the thi.ng/color
+ * package](https://docs.thi.ng/umbrella/color/functions/setPrecision.html).
  *
  * @param tree - shape tree
  */

package/convert.js

@@ -2,7 +2,7 @@ import { implementsFunction } from "@thi.ng/checks/implements-function";
 import { isArray } from "@thi.ng/checks/is-array";
 import { circle } from "./circle.js";
 import { ellipse } from "./ellipse.js";
-import { fattribs } from "./format.js";
+import { PRECISION, fattribs, setPrecision } from "./format.js";
 import { linearGradient, radialGradient } from "./gradients.js";
 import { image } from "./image.js";
 import { hline, line, vline } from "./line.js";
@@ -32,13 +32,24 @@ const BASE_LINE = {
     top: "text-top",
     bottom: "text-bottom",
 };
+const precisionStack = [];
 /**
- * Takes a normalized hiccup tree of [`thi.ng/geom`](https://thi.ng/geom) or
+ * Takes a normalized hiccup tree of [`thi.ng/geom`](https://thi.ng/geom) and/or
  * [thi.ng/hdom-canvas](https://thi.ng/hdom-canvas) shape definitions and
- * recursively converts it into an hiccup flavor which is compatible for SVG
- * serialization. This conversion also involves translation & reorg of various
- * attributes. Returns new tree. The original remains untouched, as will any
- * unrecognized tree/shape nodes.
+ * recursively converts it into an hiccup flavor which is compatible for direct
+ * SVG serialization. This conversion also involves translation, stringification
+ * & reorg of various attributes. The function returns new tree. The original
+ * remains untouched, as will any unrecognized tree/shape nodes.
+ *
+ * @remarks
+ * The `__prec` control attribute can be used (on a per-shape basis) to control
+ * the formatting used for various floating point values (except color
+ * conversions). See {@link setPrecision}. Child shapes (of a group) inherit the
+ * precision setting of their parent.
+ *
+ * To control the formatting precision for colors, use [the relevant function in
+ * the thi.ng/color
+ * package](https://docs.thi.ng/umbrella/color/functions/setPrecision.html).
  *
  * @param tree - shape tree
  */
@@ -53,63 +64,86 @@ export const convertTree = (tree) => {
         return tree.map(convertTree);
     }
     let attribs = convertAttribs(tree[1]);
+    if (attribs.__prec) {
+        precisionStack.push(PRECISION);
+        setPrecision(attribs.__prec);
+    }
+    let result;
     switch (tree[0]) {
         case "svg":
         case "defs":
         case "a":
-        case "g": {
-            const res = [type, fattribs(attribs)];
+        case "g":
+            result = [type, fattribs(attribs)];
             for (let i = 2, n = tree.length; i < n; i++) {
                 const c = convertTree(tree[i]);
-                c != null && res.push(c);
+                c != null && result.push(c);
             }
-            return res;
-        }
+            break;
         case "linearGradient":
-            return linearGradient(attribs.id, attribs.from, attribs.to, tree[2], {
+            result = linearGradient(attribs.id, attribs.from, attribs.to, tree[2], {
                 gradientUnits: attribs.gradientUnits || "userSpaceOnUse",
                 ...(attribs.gradientTransform
                     ? { gradientTransform: attribs.gradientTransform }
                     : null),
             });
+            break;
         case "radialGradient":
-            return radialGradient(attribs.id, attribs.from, attribs.to, attribs.r1, attribs.r2, tree[2], {
+            result = radialGradient(attribs.id, attribs.from, attribs.to, attribs.r1, attribs.r2, tree[2], {
                 gradientUnits: attribs.gradientUnits || "userSpaceOnUse",
                 ...(attribs.gradientTransform
                     ? { gradientTransform: attribs.gradientTransform }
                     : null),
             });
+            break;
         case "circle":
-            return circle(tree[2], tree[3], attribs, ...tree.slice(4));
+            result = circle(tree[2], tree[3], attribs, ...tree.slice(4));
+            break;
         case "ellipse":
-            return ellipse(tree[2], tree[3][0], tree[3][1], attribs, ...tree.slice(4));
+            result = ellipse(tree[2], tree[3][0], tree[3][1], attribs, ...tree.slice(4));
+            break;
         case "rect": {
             const r = tree[5] || 0;
-            return roundedRect(tree[2], tree[3], tree[4], r, r, attribs, ...tree.slice(6));
+            result = roundedRect(tree[2], tree[3], tree[4], r, r, attribs, ...tree.slice(6));
+            break;
         }
         case "line":
-            return line(tree[2], tree[3], attribs, ...tree.slice(4));
+            result = line(tree[2], tree[3], attribs, ...tree.slice(4));
+            break;
         case "hline":
-            return hline(tree[2], attribs);
+            result = hline(tree[2], attribs);
+            break;
         case "vline":
-            return vline(tree[2], attribs);
+            result = vline(tree[2], attribs);
+            break;
         case "polyline":
-            return polyline(tree[2], attribs, ...tree.slice(3));
+            result = polyline(tree[2], attribs, ...tree.slice(3));
+            break;
         case "polygon":
-            return polygon(tree[2], attribs, ...tree.slice(3));
+            result = polygon(tree[2], attribs, ...tree.slice(3));
+            break;
         case "path":
-            return path(tree[2], attribs, ...tree.slice(3));
+            result = path(tree[2], attribs, ...tree.slice(3));
+            break;
         case "text":
-            return text(tree[2], tree[3], attribs, ...tree.slice(4));
+            result = text(tree[2], tree[3], attribs, ...tree.slice(4));
+            break;
         case "img":
-            return image(tree[3], tree[2].src, attribs, ...tree.slice(4));
+            result = image(tree[3], tree[2].src, attribs, ...tree.slice(4));
+            break;
         case "points":
-            return points(tree[2], attribs.shape, attribs.size, attribs, ...tree.slice(3));
+            result = points(tree[2], attribs.shape, attribs.size, attribs, ...tree.slice(3));
+            break;
         case "packedPoints":
-            return packedPoints(tree[2], attribs.shape, attribs.size, attribs, ...tree.slice(3));
+            result = packedPoints(tree[2], attribs.shape, attribs.size, attribs, ...tree.slice(3));
+            break;
         default:
-            return tree;
+            result = tree;
+    }
+    if (attribs.__prec) {
+        setPrecision(precisionStack.pop());
     }
+    return result;
 };
 const convertAttribs = (attribs) => {
     const res = {};

package/format.d.ts

@@ -1,7 +1,15 @@
 import type { Vec2Like } from "./api.js";
+export declare let PRECISION: number;
+/**
+ * Sets the number of fractional digits used for formatting various floating
+ * point values in the serialized SVG. The current value can be read via
+ * {@link PRECISION}.
+ *
+ * @param n
+ */
 export declare const setPrecision: (n: number) => number;
 /** @internal */
-export declare const ff: (x: number) => string | number;
+export declare const ff: (x: number) => string;
 /** @internal */
 export declare const fpoint: (p: Vec2Like) => string;
 /** @internal */
@@ -27,7 +35,7 @@ export declare const fpoints: (pts: Vec2Like[], sep?: string) => string;
  * number or an
  * [`IColor`](https://docs.thi.ng/umbrella/color/interfaces/IColor.html)
  * instance, it will be converted into a CSS color string using
- * [`asCSS()`](https://docs.thi.ng/umbrella/color/functions/asCSS.html).
+ * [`css()`](https://docs.thi.ng/umbrella/color/functions/css.html).
  *
  * String color attribs prefixed with `$` are replaced with `url(#...)` refs
  * (used for referencing gradients).
@@ -46,7 +54,9 @@ export declare const fpoints: (pts: Vec2Like[], sep?: string) => string;
 export declare const fattribs: (attribs: any, ...numericIDs: string[]) => any;
 /**
  * Attempts to convert a single color attrib value. If `col` is prefixed with
- * `$`, the value will be converted into a `url(#...)` reference.
+ * `$`, the value will be converted into a `url(#...)` reference. If not a
+ * string already, it will be converted into a CSS color string using
+ * [`css()`](https://docs.thi.ng/umbrella/color/functions/css.html)
  *
  * {@link fattribs}
  *

package/format.js

@@ -1,10 +1,17 @@
 import { isArrayLike } from "@thi.ng/checks/is-arraylike";
 import { isString } from "@thi.ng/checks/is-string";
 import { css } from "@thi.ng/color/css/css";
-let PRECISION = 3;
+export let PRECISION = 3;
+/**
+ * Sets the number of fractional digits used for formatting various floating
+ * point values in the serialized SVG. The current value can be read via
+ * {@link PRECISION}.
+ *
+ * @param n
+ */
 export const setPrecision = (n) => (PRECISION = n);
 /** @internal */
-export const ff = (x) => (x === (x | 0) ? x : x.toFixed(PRECISION));
+export const ff = (x) => x === (x | 0) ? String(x) : x.toFixed(PRECISION);
 /** @internal */
 export const fpoint = (p) => ff(p[0]) + "," + ff(p[1]);
 /** @internal */
@@ -52,7 +59,7 @@ const numericAttribs = (attribs, ids) => {
  * number or an
  * [`IColor`](https://docs.thi.ng/umbrella/color/interfaces/IColor.html)
  * instance, it will be converted into a CSS color string using
- * [`asCSS()`](https://docs.thi.ng/umbrella/color/functions/asCSS.html).
+ * [`css()`](https://docs.thi.ng/umbrella/color/functions/css.html).
  *
  * String color attribs prefixed with `$` are replaced with `url(#...)` refs
  * (used for referencing gradients).
@@ -132,7 +139,9 @@ const buildTransform = (attribs) => {
 };
 /**
  * Attempts to convert a single color attrib value. If `col` is prefixed with
- * `$`, the value will be converted into a `url(#...)` reference.
+ * `$`, the value will be converted into a `url(#...)` reference. If not a
+ * string already, it will be converted into a CSS color string using
+ * [`css()`](https://docs.thi.ng/umbrella/color/functions/css.html)
  *
  * {@link fattribs}
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/hiccup-svg",
-  "version": "4.3.39",
+  "version": "5.0.0",
   "description": "SVG element functions for @thi.ng/hiccup & related tooling",
   "type": "module",
   "module": "./index.js",
@@ -34,17 +34,17 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/checks": "^3.3.10",
-    "@thi.ng/color": "^5.4.5",
-    "@thi.ng/prefixes": "^2.1.20"
+    "@thi.ng/checks": "^3.3.12",
+    "@thi.ng/color": "^5.4.7",
+    "@thi.ng/prefixes": "^2.1.22"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.4",
-    "@thi.ng/testament": "^0.3.13",
-    "rimraf": "^4.4.0",
+    "@thi.ng/testament": "^0.3.15",
+    "rimraf": "^4.4.1",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.26",
-    "typescript": "^4.9.5"
+    "typedoc": "^0.23.28",
+    "typescript": "^5.0.4"
   },
   "keywords": [
     "arc",
@@ -135,5 +135,5 @@
     "parent": "@thi.ng/hiccup",
     "year": 2016
   },
-  "gitHead": "1359645f3af8a7d0d43fe7944ea5cd865832f8ee\n"
+  "gitHead": "abcedd9e4e06a4b631f363610eec572f79b571c1\n"
 }

package/svg.d.ts

@@ -4,9 +4,10 @@
  * legacy tooling.
  *
  * @remarks
- * If the `convert: true` attrib is given, all body elements will be
- * automatically converted using {@link convertTree}. The `convert` attrib is
- * NOT going to be serialized in the final output.
+ * If the `__convert` boolean attrib is enabled, all body elements will be
+ * automatically converted using {@link convertTree}. The `__convert` attrib
+ * will be removed afterward and is NOT going to be serialized in the final
+ * output.
  *
  * @param attribs - attributes object
  * @param body - shape primitives

package/svg.js

@@ -7,9 +7,10 @@ import { fattribs } from "./format.js";
  * legacy tooling.
  *
  * @remarks
- * If the `convert: true` attrib is given, all body elements will be
- * automatically converted using {@link convertTree}. The `convert` attrib is
- * NOT going to be serialized in the final output.
+ * If the `__convert` boolean attrib is enabled, all body elements will be
+ * automatically converted using {@link convertTree}. The `__convert` attrib
+ * will be removed afterward and is NOT going to be serialized in the final
+ * output.
  *
  * @param attribs - attributes object
  * @param body - shape primitives
@@ -21,8 +22,8 @@ export const svg = (attribs, ...body) => {
         "xmlns:xlink": XML_XLINK,
         ...attribs,
     }, "width", "height", "stroke-width");
-    if (attribs.convert) {
-        delete attribs.convert;
+    if (attribs.__convert) {
+        delete attribs.__convert;
         body = body.map(convertTree);
     }
     return ["svg", attribs, ...body];