Docs: Document new indent utils

Author: jlukic

CHANGELOG.md

@@ -21,6 +21,8 @@ xx.xx.xxxx
 * **Feature** - Added [`addAttr()`](https://next.semantic-ui.com/api/query/attributes#addattr) method for adding one or more attributes with empty string values. Useful shorthand for boolean attributes common in web components.
 
 ### Utils
+* **Feature** - Added [`indentHTML()`](https://next.semantic-ui.com/docs/api/utils/html#indenthtml) for intelligently indenting HTML markup with proper nesting awareness. Handles void elements, self-closing tags, and comments correctly. Perfect for cleaning up HTML extracted from template literals.
+* **Feature** - Added [`indentLines()`](https://next.semantic-ui.com/docs/api/utils/html#indentlines) for adding consistent indentation to every line of text. Useful for formatting code snippets and template processing.
 * **Feature** - Added `reverseString()` for reversing strings with Unicode grapheme cluster handling using Intl.Segmenter. Preserves emojis, flag sequences, skin tone modifiers, and combined diacritics.
 * **Bug** - Fixed `weightedObjectSearch()` regex pattern escaping where multi-word queries with `matchAllWords: false` returned no results. Template string was using `\W` (literal 'W') instead of `\\W` (non-word character class), breaking word boundary matching.
 * **Enhancement** - `remove()` now removes all matching instances from an array instead of just the first. Uses an optimized two-pointer approach for O(n) performance. Returns the count of removed elements for backward compatibility.

docs/src/content/examples/utils-indenthtml.mdx

@@ -0,0 +1,11 @@
+---
+title: 'indentHTML'
+id: 'utils-indenthtml'
+exampleType: 'log'
+category: 'Utils'
+subcategory: 'HTML'
+description: 'Intelligently indent HTML markup with proper nesting awareness'
+tags: ['utils', 'html', 'indenthtml', 'formatting', 'markup']
+selectedFile: 'index.js'
+tip: 'Cleans up HTML from template literals. For simple line indentation, use [indentLines](/examples/utils-indentlines)'
+---

docs/src/content/examples/utils-indentlines.mdx

@@ -0,0 +1,11 @@
+---
+title: 'indentLines'
+id: 'utils-indentlines'
+exampleType: 'log'
+category: 'Utils'
+subcategory: 'HTML'
+description: 'Add consistent indentation to every line of text'
+tags: ['utils', 'html', 'indentlines', 'formatting', 'text']
+selectedFile: 'index.js'
+tip: 'For HTML-specific indentation with nesting awareness, use [indentHTML](/examples/utils-indenthtml)'
+---

docs/src/examples/utils/html/utils-indenthtml/index.js

@@ -0,0 +1,25 @@
+import { indentHTML } from '@semantic-ui/utils';
+
+// basic usage
+const simple = '<div>\n<p>Content</p>\n</div>';
+console.log(indentHTML(simple));
+
+// nested structures
+const button = `<ui-button animated>
+<span slot="visible">Hover Me</span>
+<span slot="hidden">Hidden</span>
+</ui-button>`;
+
+console.log(indentHTML(button));
+
+// custom indentation with tabs
+const withTabs = '<div>\n<p>Content</p>\n</div>';
+console.log(indentHTML(withTabs, { indent: '\t' }));
+
+// starting at nesting level
+const atLevel = '<div>\n<p>Content</p>\n</div>';
+console.log(indentHTML(atLevel, { startLevel: 1 }));
+
+// handles void elements
+const voidElements = '<div>\n<img src="test.jpg">\n<br>\n<input type="text">\n</div>';
+console.log(indentHTML(voidElements));

docs/src/examples/utils/html/utils-indentlines/index.js

@@ -0,0 +1,18 @@
+import { indentLines } from '@semantic-ui/utils';
+
+// basic usage with default 2 spaces
+const code = 'function test() {\n  return true;\n}';
+console.log(indentLines(code));
+
+// custom indentation
+console.log(indentLines(code, 4));
+
+// single line
+console.log(indentLines('single line', 2));
+
+// useful for template processing
+const template = `const greeting = 'Hello';
+const name = 'World';
+console.log(greeting, name);`;
+
+console.log(indentLines(template, 2));

docs/src/helpers/injections.js

@@ -321,17 +321,33 @@ function createTableHTML(data) {
   return formatValue(data);
 }
 
+// Helper to escape HTML to prevent XSS
+function escapeHTML(string) {
+  const htmlEscapes = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;'
+  };
+  const htmlRegExp = /[&<>"']/g;
+  const hasHTML = RegExp(htmlRegExp.source);
+  return (string && hasHTML.test(string))
+    ? string.replace(htmlRegExp, (chr) => htmlEscapes[chr])
+    : (string || '');
+}
+
 function formatValue(value, skipFormat = false, inTable = false) {
   if (skipFormat) {
-    return String(value);
+    return escapeHTML(String(value));
   }
-  
+
   if (value === null) {
     return \`<span class="json-null">null</span>\`;
   } else if (value === undefined) {
     return \`<span class="json-undefined">undefined</span>\`;
   } else if (typeof value === 'string') {
-    return \`<span class="json-string">"\${value}"</span>\`;
+    return \`<span class="json-string">"\${escapeHTML(value)}"</span>\`;
   } else if (typeof value === 'number') {
     if (Number.isNaN(value)) {
       return \`<span class="json-nan">NaN</span>\`;
@@ -346,17 +362,17 @@ function formatValue(value, skipFormat = false, inTable = false) {
   } else if (typeof value === 'function') {
     const funcStr = value.toString();
     const isArrow = funcStr.includes('=>');
-    const funcName = value.name || 'anonymous';
+    const funcName = escapeHTML(value.name || 'anonymous');
     if (inTable) {
       return \`<span class="json-function">ƒ \${funcName}()</span>\`;
     }
-    return \`<span class="json-function">ƒ \${funcName}() { \${isArrow ? funcStr : '...'} }</span>\`;
+    return \`<span class="json-function">ƒ \${funcName}() { \${isArrow ? escapeHTML(funcStr) : '...'} }</span>\`;
   } else if (value instanceof Date) {
-    return \`<span class="json-date">\${value.toISOString()}</span>\`;
+    return \`<span class="json-date">\${escapeHTML(value.toISOString())}</span>\`;
   } else if (value instanceof RegExp) {
-    return \`<span class="json-regexp">\${value.toString()}</span>\`;
+    return \`<span class="json-regexp">\${escapeHTML(value.toString())}</span>\`;
   } else if (value instanceof Error) {
-    return \`<span class="json-error">\${value.name}: \${value.message}</span>\`;
+    return \`<span class="json-error">\${escapeHTML(value.name)}: \${escapeHTML(value.message)}</span>\`;
   } else if (Array.isArray(value)) {
     if (inTable) {
       return \`<span class="json-array">Array(\${value.length})</span>\`;
@@ -369,9 +385,9 @@ function formatValue(value, skipFormat = false, inTable = false) {
   } else if (typeof value === 'object' && value !== null) {
     // Handle DOM elements
     if (value.nodeType) {
-      const tagName = value.tagName?.toLowerCase() || 'node';
-      const id = value.id ? \`#\${value.id}\` : '';
-      const className = value.className ? \`.\${value.className.split(' ').join('.')}\` : '';
+      const tagName = escapeHTML(value.tagName?.toLowerCase() || 'node');
+      const id = value.id ? \`#\${escapeHTML(value.id)}\` : '';
+      const className = value.className ? \`.\${escapeHTML(value.className.split(' ').join('.'))}\` : '';
       return \`<span class="json-dom">&lt;\${tagName}\${id}\${className}&gt;</span>\`;
     }
     
@@ -380,7 +396,7 @@ function formatValue(value, skipFormat = false, inTable = false) {
     const isCustomClass = constructor && constructor !== Object && constructor.name !== 'Object';
     
     if (isCustomClass) {
-      const className = constructor.name;
+      const className = escapeHTML(constructor.name);
       const keys = Object.keys(value);
       if (inTable) {
         return \`<span class="json-class">\${className} {...}</span>\`;
@@ -389,7 +405,7 @@ function formatValue(value, skipFormat = false, inTable = false) {
         return \`<span class="json-class">\${className} {}</span>\`;
       }
       const formattedObject = keys.slice(0, 3).map(key => {
-        return \`<span class="json-key">"\${key}"</span>: \${formatValue(value[key])}\`;
+        return \`<span class="json-key">"\${escapeHTML(key)}"</span>: \${formatValue(value[key])}\`;
       }).join(', ');
       const more = keys.length > 3 ? ', ...' : '';
       return \`<span class="json-class">\${className}</span> {\${formattedObject}\${more}}\`;
@@ -404,12 +420,12 @@ function formatValue(value, skipFormat = false, inTable = false) {
       return \`<span class="json-object">{}</span>\`;
     }
     const formattedObject = keys.slice(0, 3).map(key => {
-      return \`<span class="json-key">"\${key}"</span>: \${formatValue(value[key])}\`;
+      return \`<span class="json-key">"\${escapeHTML(key)}"</span>: \${formatValue(value[key])}\`;
     }).join(', ');
     const more = keys.length > 3 ? ', ...' : '';
     return \`<span class="json-object">{\${formattedObject}\${more}}</span>\`;
   } else {
-    return \`<span class="json-unknown">\${String(value)}</span>\`;
+    return \`<span class="json-unknown">\${escapeHTML(String(value))}</span>\`;
   }
 }
 ${hideMarkerEnd}`;
@@ -509,6 +525,7 @@ export const logCSS = `
       border-top: var(--border);
       padding: 4px 0;
       word-wrap: break-word;
+      white-space: pre;
     }
     .log-entry:first-child {
       border-top: none;

docs/src/pages/docs/api/utils/html.mdx

@@ -0,0 +1,145 @@
+---
+layout: '@layouts/Guide.astro'
+pageType: 'API Reference'
+title: HTML Utilities
+icon: code
+description: API reference for HTML and text formatting utility functions
+---
+
+The HTML utilities provide functions for indenting text and HTML markup. These functions are useful for formatting code snippets, cleaning up HTML extracted from template literals, and preparing markup for documentation.
+
+## Functions
+
+### indentLines
+
+```javascript
+function indentLines(text, spaces = 2)
+```
+
+Adds consistent indentation to every line of text.
+
+#### Parameters
+
+| Name   | Type   | Description |
+|--------|--------|-------------|
+| text   | string | The text to indent |
+| spaces | number | Number of spaces to indent each line (default: 2) |
+
+#### Returns
+
+The indented text. Returns empty string for non-string input.
+
+#### Example
+
+```javascript
+import { indentLines } from '@semantic-ui/utils';
+
+const code = 'line 1\nline 2\nline 3';
+console.log(indentLines(code)); // '  line 1\n  line 2\n  line 3'
+console.log(indentLines(code, 4)); // '    line 1\n    line 2\n    line 3'
+
+// useful for template processing
+const template = `function example() {
+  return true;
+}`;
+console.log(indentLines(template, 2));
+```
+
+### indentHTML
+
+```javascript
+function indentHTML(html, { indent = '  ', startLevel = 0, trimEmptyLines = true } = {})
+```
+
+Intelligently indents HTML markup with proper nesting awareness. Handles void elements, self-closing tags, and comments correctly.
+
+> **Use Case** Perfect for cleaning up HTML extracted from JavaScript template literals where indentation gets messy, or for formatting documentation examples.
+
+#### Parameters
+
+| Name    | Type   | Description |
+|---------|--------|-------------|
+| html    | string | The HTML string to indent |
+| options | object | Optional configuration |
+
+##### Options
+
+| Name           | Type    | Default | Description |
+|----------------|---------|---------|-------------|
+| indent         | string  | '  '    | String to use for each level of indentation |
+| startLevel     | number  | 0       | Initial nesting level to start indentation from |
+| trimEmptyLines | boolean | true    | Whether to remove empty lines from the output |
+
+#### Returns
+
+The properly indented HTML. Returns empty string for non-string input.
+
+#### Features
+
+- **Nesting-aware** - Tracks depth and indents accordingly
+- **Void elements** - Handles `img`, `br`, `hr`, `input`, etc. without increasing depth
+- **Self-closing tags** - Recognizes `<component />` syntax
+- **Comments** - Preserves `<!-- -->` comments without affecting depth
+- **Same-line tags** - Detects `<tag>content</tag>` patterns on single lines
+
+#### Limitations
+
+- Works best with one tag per line (typical documentation format)
+- Multiple tags on same line are not split
+- Designed for well-formed HTML snippets, not error correction
+
+#### Example
+
+```javascript
+import { indentHTML } from '@semantic-ui/utils';
+
+// basic usage
+const html = '<div>\n<p>Content</p>\n</div>';
+console.log(indentHTML(html));
+// <div>
+//   <p>Content</p>
+// </div>
+
+// nested structures
+const nested = `<div class="ui segment">
+<div class="ui header">Title</div>
+<p>Content here</p>
+<div class="ui list">
+<div class="item">
+<img src="image.jpg" />
+<div class="content">Item 1</div>
+</div>
+</div>
+</div>`;
+
+console.log(indentHTML(nested));
+// <div class="ui segment">
+//   <div class="ui header">Title</div>
+//   <p>Content here</p>
+//   <div class="ui list">
+//     <div class="item">
+//       <img src="image.jpg" />
+//       <div class="content">Item 1</div>
+//     </div>
+//   </div>
+// </div>
+
+// custom indentation
+console.log(indentHTML(html, { indent: '    ' })); // 4 spaces
+console.log(indentHTML(html, { indent: '\t' })); // tabs
+
+// start at nesting level
+console.log(indentHTML(html, { startLevel: 1 }));
+//   <div>
+//     <p>Content</p>
+//   </div>
+
+// void elements
+const voidElements = '<div>\n<img src="test.jpg">\n<br>\n<input type="text">\n</div>';
+console.log(indentHTML(voidElements));
+// <div>
+//   <img src="test.jpg">
+//   <br>
+//   <input type="text">
+// </div>
+```