create-html-element 5.0.0 → 6.0.0

package/index.d.ts

@@ -29,7 +29,43 @@ export type TextOptions = {
 	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,8 +92,26 @@ 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;
 
-export {HTMLAttributes} from 'stringify-attributes';
+export type {HTMLAttributes} from 'stringify-attributes';

package/index.js

@@ -4,24 +4,57 @@ import {htmlEscape} from 'escape-goat';
 
 const voidHtmlTags = new Set(voidHtmlTagsArray);
 
-export default function createHtmlElement(
-	{
-		name = 'div',
-		attributes = {},
-		html = '',
-		text,
-	} = {},
-) {
-	if (html && text) {
-		throw new Error('The `html` and `text` options are mutually exclusive');
+// Matches a valid HTML tag name (a letter followed by letters, digits, hyphens, underscores, or periods).
+const tagNamePattern = /^[a-z][\w\-.]*$/iv;
+
+export default function createHtmlElement({
+	name = 'div',
+	attributes = {},
+	html,
+	text,
+	children,
+} = {}) {
+	if (!tagNamePattern.test(name)) {
+		throw new Error(`Invalid tag name: ${JSON.stringify(name)}`);
+	}
+
+	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');
 	}
 
-	const content = text ? htmlEscape(text) : html;
-	let result = `<${name}${stringifyAttributes(attributes)}>`;
+	const openingTag = `<${name}${stringifyAttributes(attributes)}>`;
+
+	if (voidHtmlTags.has(name)) {
+		return openingTag;
+	}
+
+	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);
+			}
 
-	if (!voidHtmlTags.has(name)) {
-		result += `${content}</${name}>`;
+			throw new TypeError('Children must be strings or objects');
+		}).join('');
+	} else if (hasText) {
+		content = htmlEscape(text);
+	} else if (hasHtml) {
+		content = html;
 	}
 
-	return result;
+	return `${openingTag}${content}</${name}>`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-html-element",
-	"version": "5.0.0",
+	"version": "6.0.0",
 	"description": "Create a HTML element string",
 	"license": "MIT",
 	"repository": "sindresorhus/create-html-element",
@@ -17,7 +17,7 @@
 	},
 	"sideEffects": false,
 	"engines": {
-		"node": "^18.20.0 || >=20.10.0"
+		"node": ">=22"
 	},
 	"scripts": {
 		"test": "xo && ava && tsd"
@@ -37,13 +37,13 @@
 	],
 	"dependencies": {
 		"escape-goat": "^4.0.0",
-		"html-tags": "^4.0.0",
-		"stringify-attributes": "^4.0.0",
-		"type-fest": "^4.27.0"
+		"html-tags": "^5.1.0",
+		"stringify-attributes": "^5.0.0",
+		"type-fest": "^5.7.0"
 	},
 	"devDependencies": {
-		"ava": "^6.2.0",
-		"tsd": "^0.31.2",
-		"xo": "^0.59.3"
+		"ava": "^8.0.1",
+		"tsd": "^0.33.0",
+		"xo": "^3.0.2"
 	}
 }

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