@thi.ng/hiccup 5.2.24 → 5.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-01-04T21:07:38Z
+- **Last updated**: 2025-01-22T08:39:43Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,15 @@ 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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/hiccup@5.3.0) (2025-01-22)
+
+#### 🚀 Features
+
+- add special `INLINE` tag & `__escape` behavior attrib ([42e7717](https://github.com/thi-ng/umbrella/commit/42e7717))
+  - add `INLINE` tag & handling for embedded markup
+  - add `__escape` control attrib to enable/disable entity escaping (per element)
+  - add tests
+
 ### [5.2.11](https://github.com/thi-ng/umbrella/tree/@thi.ng/hiccup@5.2.11) (2024-08-23)
 
 #### 🩹 Bug fixes

package/README.md

@@ -37,6 +37,7 @@
   - [Component objects](#component-objects)
   - [Behavior control attributes](#behavior-control-attributes)
   - [Comments](#comments)
+  - [Inlined/embedded markup](#inlinedembedded-markup)
   - [XML / DTD processing instructions](#xml--dtd-processing-instructions)
 - [API](#api)
   - [serialize()](#serialize)
@@ -183,7 +184,7 @@ For Node.js REPL:
 const h = await import("@thi.ng/hiccup");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.20 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.24 KB
 
 ## Dependencies
 
@@ -391,7 +392,9 @@ serialize([div, {id: "foo"}, "bar"]);
 
 Also see
 [@thi.ng/hiccup-svg](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup-svg)
-for related functionality.
+and
+[@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom)
+for related (and more advanced) functionality.
 
 ```ts tangle:export/readme-circles.js
 import { serialize } from "@thi.ng/hiccup";
@@ -554,11 +557,10 @@ Re-formatted HTML output:
 
 The sibling library
 [@thi.ng/hdom](https://github.com/thi-ng/umbrella/tree/develop/packages/hdom)
-supports components with basic life cycle methods (init, render,
-release). In order to support serialization of hdom component trees,
-hiccup too supports such components since version 2.0.0. However, for
-static serialization only the `render` method is of interest and others
-are ignored.
+supports components with basic life cycle methods (init, render, release). To
+support serialization of hdom component trees, hiccup too supports such
+components since version 2.0.0. For static serialization only the `render`
+method is of interest and others are ignored.
 
 ```js
 const component = {
@@ -573,6 +575,7 @@ serialize([component, "Hello world", "Body"]);
 The following attributes can be used to control the serialization
 behavior of individual elements / tree branches:
 
+- **`__escape`** - boolean flag to enable/disable entity escaping
 - **`__skip`** - if true, skips serialization (also used by
   [@thi.ng/hdom](https://github.com/thi-ng/umbrella/tree/develop/packages/hdom))
 - **`__serialize`** - if false, skips serialization (hiccup only)
@@ -585,7 +588,7 @@ serialize(["div.container", ["div", { __skip: true }, "ignore me"]]);
 ### Comments
 
 Single or multiline comments can be included using the special `COMMENT`
-tag (`__COMMENT__`) (always WITHOUT attributes!).
+tag (or `__COMMENT__`, always WITHOUT attributes!).
 
 ```ts
 import { COMMENT } from "@thi.ng/hiccup";
@@ -601,6 +604,22 @@ import { COMMENT } from "@thi.ng/hiccup";
 // -->
 ```
 
+### Inlined/embedded markup
+
+Pre-serialized markup can be inlined without any further processing using the
+special `INLINE` tag (or `__INLINE__`, always WITHOUT attributes!):
+
+```js
+import { INLINE, serialize } from "@thi.ng/hiccup";
+
+serialize(
+    ["div", {}
+        [INLINE, "<h3>Inlined &amp; Embedded</h3><p>Lorem ipsum...</p>"]
+    ]
+);
+// <div><h3>Inlined &amp; Embedded</h3><p>Lorem ipsum...</p></div>
+```
+
 ### XML / DTD processing instructions
 
 Currently, the only processing / DTD instructions supported are:

package/api.d.ts

@@ -7,6 +7,8 @@ export declare const RE_TAG: RegExp;
 /** @internal */
 export declare const COMMENT = "__COMMENT__";
 /** @internal */
+export declare const INLINE = "__INLINE__";
+/** @internal */
 export declare const CDATA = "!CDATA";
 /** @internal */
 export declare const DOCTYPE = "!DOCTYPE";

package/api.js

@@ -7,6 +7,7 @@ const PROC_TAGS = {
 };
 const RE_TAG = /^([^\s.#]+)(?:#([^\s.#]+))?(?:\.([^\s#]+))?$/;
 const COMMENT = "__COMMENT__";
+const INLINE = "__INLINE__";
 const CDATA = "!CDATA";
 const DOCTYPE = "!DOCTYPE";
 const XML_PROC = ["?xml", { version: "1.0", encoding: "UTF-8" }];
@@ -42,6 +43,7 @@ export {
   COMMENT,
   DOCTYPE,
   DOCTYPE_HTML,
+  INLINE,
   NO_CLOSE_EMPTY,
   NO_SPANS,
   PROC_TAGS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/hiccup",
-  "version": "5.2.24",
+  "version": "5.3.0",
   "description": "HTML/SVG/XML serialization of nested data structures, iterables & closures",
   "type": "module",
   "module": "./index.js",
@@ -40,14 +40,14 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.16",
-    "@thi.ng/checks": "^3.6.19",
-    "@thi.ng/errors": "^2.5.22",
-    "@thi.ng/strings": "^3.9.1"
+    "@thi.ng/api": "^8.11.17",
+    "@thi.ng/checks": "^3.6.20",
+    "@thi.ng/errors": "^2.5.23",
+    "@thi.ng/strings": "^3.9.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.48.1",
-    "@thi.ng/atom": "^5.3.17",
+    "@thi.ng/atom": "^5.3.18",
     "esbuild": "^0.24.2",
     "typedoc": "^0.27.6",
     "typescript": "^5.7.2"
@@ -132,5 +132,5 @@
     ],
     "year": 2016
   },
-  "gitHead": "56e7a1724e7b0cb5c41119f60320b6ff0e8a3c1c\n"
+  "gitHead": "363db3998a14ddfd7a82f3039d8ca9681581e284\n"
 }

package/serialize.js

@@ -11,6 +11,7 @@ import {
   ATTRIB_JOIN_DELIMS,
   CDATA,
   COMMENT,
+  INLINE,
   NO_CLOSE_EMPTY,
   NO_SPANS,
   PROC_TAGS,
@@ -38,13 +39,14 @@ const __serializeElement = (tree, opts, path) => {
     tag.render.apply(null, [opts.ctx, ...tree.slice(1)]),
     opts,
     path
-  ) : tag === COMMENT ? __serializeComment(tree) : tag == CDATA ? __serializeCData(tree) : isString(tag) ? __serializeTag(tree, opts, path) : isNotStringAndIterable(tree) ? __serializeIter(tree, opts, path) : illegalArgs(`invalid tree node: ${tree}`);
+  ) : tag === COMMENT ? __serializeComment(tree) : tag === INLINE ? __serializeInline(tree) : tag == CDATA ? __serializeCData(tree) : isString(tag) ? __serializeTag(tree, opts, path) : isNotStringAndIterable(tree) ? __serializeIter(tree, opts, path) : illegalArgs(`invalid tree node: ${tree}`);
 };
 const __serializeTag = (tree, opts, path) => {
   tree = normalize(tree);
   const attribs = tree[1];
   if (attribs.__skip || attribs.__serialize === false) return "";
   opts.keys && attribs.key === void 0 && (attribs.key = path.join("-"));
+  if (attribs.__escape != null) opts = { ...opts, escape: attribs.__escape };
   const tag = tree[0];
   const body = tree[2] ? __serializeBody(tag, tree[2], opts, path) : !VOID_TAGS[tag] && !NO_CLOSE_EMPTY[tag] ? `></${tag}>` : PROC_TAGS[tag] || "/>";
   return `<${tag}${__serializeAttribs(attribs, opts)}${body}`;
@@ -93,6 +95,7 @@ ${tree.slice(1).map((x) => "    " + x).join("\n")}
 ` : `
 <!-- ${tree[1]} -->
 `;
+const __serializeInline = (tree) => tree.slice(1).join("");
 const __serializeCData = (tree) => `<![CDATA[
 ${tree.slice(1).join("\n")}
 ]]>`;