create-html-element 4.0.1 → 5.1.0

package/index.d.ts

@@ -1,7 +1,7 @@
-import {MergeExclusive} from 'type-fest';
-import stringifyAttributes, {HTMLAttributes} from 'stringify-attributes';
+import {type MergeExclusive} from 'type-fest';
+import stringifyAttributes, {type HTMLAttributes} from 'stringify-attributes';
 
-export interface BaseOptions {
+export type BaseOptions = {
 	/**
 	HTML tag attributes.
 	*/
@@ -13,23 +13,59 @@ export interface BaseOptions {
 	@default 'div'
 	*/
 	readonly name?: string;
-}
+};
 
-export interface HtmlOptions {
+export type HtmlOptions = {
 	/**
 	HTML tag value in unescaped HTML.
 	*/
 	readonly html?: string;
-}
+};
 
-export interface TextOptions {
+export type TextOptions = {
 	/**
 	HTML tag value in escaped HTML.
 	*/
 	readonly text?: string;
-}
+};
 
-export type Options = BaseOptions & MergeExclusive<HtmlOptions, TextOptions>;
+export type ChildrenOptions = {
+	/**
+	HTML tag children.
+
+	Strings are escaped, objects are passed to `createHtmlElement`.
+
+	This option is mutually exclusive with the `html` and `text` options.
+
+	@example
+	```
+	import createHtmlElement from 'create-html-element';
+
+	createHtmlElement({
+		name: 'div',
+		children: [
+			'<unsafe>',
+			{
+				name: 'iframe',
+				attributes: {
+					src: 'https://example.com'
+				}
+			},
+			{
+				name: 'span',
+				text: 'Label here <em>plz</em>'
+			}
+		]
+	});
+	//=> '<div>&lt;unsafe&gt;<iframe src="https://example.com"></iframe><span>Label here &lt;em&gt;plz&lt;/em&gt;</span></div>'
+	```
+	*/
+	readonly children?: readonly Child[];
+};
+
+export type Child = string | (Options & {readonly length?: never});
+
+export type Options = BaseOptions & MergeExclusive<HtmlOptions, MergeExclusive<TextOptions, ChildrenOptions>>;
 
 /**
 Create a HTML element string.
@@ -56,6 +92,24 @@ createHtmlElement({
 
 createHtmlElement({text: 'Hello <em>World</em>'});
 //=> '<div>Hello &lt;em&gt;World&lt;/em&gt;</div>'
+
+createHtmlElement({
+	name: 'div',
+	children: [
+		'<unsafe>',
+		{
+			name: 'iframe',
+			attributes: {
+				src: 'https://example.com'
+			}
+		},
+		{
+			name: 'span',
+			text: 'Label here <em>plz</em>'
+		}
+	]
+});
+//=> '<div>&lt;unsafe&gt;<iframe src="https://example.com"></iframe><span>Label here &lt;em&gt;plz&lt;/em&gt;</span></div>'
 ```
 */
 export default function createHtmlElement(options?: Options): string;

package/index.js

@@ -1,22 +1,50 @@
 import stringifyAttributes from 'stringify-attributes';
-import htmlTags from 'html-tags/void.js';
+import {voidHtmlTags as voidHtmlTagsArray} from 'html-tags';
 import {htmlEscape} from 'escape-goat';
 
-const voidHtmlTags = new Set(htmlTags);
+const voidHtmlTags = new Set(voidHtmlTagsArray);
 
 export default function createHtmlElement(
 	{
 		name = 'div',
 		attributes = {},
-		html = '',
+		html,
 		text,
+		children,
 	} = {},
 ) {
-	if (html && text) {
-		throw new Error('The `html` and `text` options are mutually exclusive');
+	const hasHtml = html !== undefined;
+	const hasText = text !== undefined;
+	const hasChildren = children !== undefined;
+
+	if ([hasHtml, hasText, hasChildren].filter(Boolean).length > 1) {
+		throw new Error('The `html`, `text`, and `children` options are mutually exclusive');
+	}
+
+	if (hasChildren && !Array.isArray(children)) {
+		throw new TypeError('The `children` option must be an array');
+	}
+
+	let content = '';
+
+	if (hasChildren) {
+		content = children.map(child => {
+			if (typeof child === 'string') {
+				return htmlEscape(child);
+			}
+
+			if (typeof child === 'object' && child !== null && !Array.isArray(child)) {
+				return createHtmlElement(child);
+			}
+
+			throw new TypeError('Children must be strings or objects');
+		}).join('');
+	} else if (hasText) {
+		content = htmlEscape(text);
+	} else if (hasHtml) {
+		content = html;
 	}
 
-	const content = text ? htmlEscape(text) : html;
 	let result = `<${name}${stringifyAttributes(attributes)}>`;
 
 	if (!voidHtmlTags.has(name)) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-html-element",
-	"version": "4.0.1",
+	"version": "5.1.0",
 	"description": "Create a HTML element string",
 	"license": "MIT",
 	"repository": "sindresorhus/create-html-element",
@@ -11,9 +11,13 @@
 		"url": "https://sindresorhus.com"
 	},
 	"type": "module",
-	"exports": "./index.js",
+	"exports": {
+		"types": "./index.d.ts",
+		"default": "./index.js"
+	},
+	"sideEffects": false,
 	"engines": {
-		"node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+		"node": "^18.20.0 || >=20.10.0"
 	},
 	"scripts": {
 		"test": "xo && ava && tsd"
@@ -33,13 +37,13 @@
 	],
 	"dependencies": {
 		"escape-goat": "^4.0.0",
-		"html-tags": "^3.1.0",
-		"stringify-attributes": "^3.0.0",
-		"type-fest": "^2.5.0"
+		"html-tags": "^4.0.0",
+		"stringify-attributes": "^4.0.0",
+		"type-fest": "^4.27.0"
 	},
 	"devDependencies": {
-		"ava": "^3.15.0",
-		"tsd": "^0.18.0",
-		"xo": "^0.45.0"
+		"ava": "^6.2.0",
+		"tsd": "^0.31.2",
+		"xo": "^0.59.3"
 	}
 }

package/readme.md

@@ -58,13 +58,45 @@ HTML tag attributes.
 
 HTML tag value in unescaped HTML.
 
-This option is mutually exclusive with the `text` option.
+This option is mutually exclusive with the `text` and `children` options.
 
 ##### text
 
 HTML tag value in escaped HTML.
 
-This option is mutually exclusive with the `html` option.
+This option is mutually exclusive with the `html` and `children` options.
+
+##### children
+
+Type: `Array<string|object>`
+
+HTML tag children.
+
+Strings are escaped, objects are passed to `createHtmlElement`.
+
+This option is mutually exclusive with the `html` and `text` options.
+
+```js
+import createHtmlElement from 'create-html-element';
+
+createHtmlElement({
+	name: 'div',
+	children: [
+		'<unsafe>',
+		{
+			name: 'iframe',
+			attributes: {
+				src: 'https://example.com'
+			}
+		},
+		{
+			name: 'span',
+			text: 'Label here <em>plz</em>'
+		}
+	]
+});
+//=> '<div>&lt;unsafe&gt;<iframe src="https://example.com"></iframe><span>Label here &lt;em&gt;plz&lt;/em&gt;</span></div>'
+```
 
 ## Related