Add new utils indentHTML and indentLines

jlukic · jlukic · commit 0eda787e94a8 · 2025-11-14T16:48:51.000-05:00
diff --git a/packages/utils/src/html.js b/packages/utils/src/html.js
@@ -0,0 +1,75 @@
+import { isString } from './types.js';
+
+/*-------------------
+        HTML
+--------------------*/
+
+export const indentLines = (text, spaces = 2) => {
+  if (!isString(text)) {
+    return '';
+  }
+  const indent = ' '.repeat(spaces);
+  return text.split('\n').map(line => `${indent}${line}`).join('\n');
+};
+
+export const indentHTML = (html, options = {}) => {
+  const {
+    indent = '  ',
+    startLevel = 0,
+    trimEmptyLines = true,
+  } = options;
+
+  if (!isString(html)) {
+    return '';
+  }
+
+  // Void elements that don't have closing tags
+  const voidElements = new Set([
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
+  ]);
+
+  let depth = startLevel;
+  const lines = html
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => !trimEmptyLines || line.length > 0);
+
+  return lines
+    .map(line => {
+      // Handle closing tags - decrease depth before indenting
+      if (line.startsWith('</')) {
+        depth = Math.max(0, depth - 1);
+      }
+
+      const indented = indent.repeat(depth) + line;
+
+      // Handle opening tags - increase depth after indenting
+      if (line.startsWith('<') && !line.startsWith('</') && !line.startsWith('<!--')) {
+        const isSelfClosing = line.endsWith('/>');
+        const tagMatch = line.match(/<(\w+)/);
+        const tag = tagMatch?.[1];
+        const isVoid = tag && voidElements.has(tag);
+        const hasClosingTag = tag && line.includes(`</${tag}>`);
+
+        if (!isSelfClosing && !isVoid && !hasClosingTag) {
+          depth++;
+        }
+      }
+
+      return indented;
+    })
+    .join('\n');
+};
diff --git a/packages/utils/src/index.js b/packages/utils/src/index.js
@@ -9,6 +9,7 @@ export * from './debug.js';
 export * from './environment.js';
 export * from './equality.js';
 export * from './functions.js';
+export * from './html.js';
 export * from './loops.js';
 export * from './numbers.js';
 export * from './objects.js';
diff --git a/packages/utils/test/html.test.js b/packages/utils/test/html.test.js
@@ -0,0 +1,212 @@
+import { indentHTML, indentLines } from '@semantic-ui/utils';
+
+import { describe, expect, it } from 'vitest';
+
+describe('HTML Utilities', () => {
+  describe('indentLines', () => {
+    it('should add 2 spaces of indentation by default', () => {
+      const input = 'line 1\nline 2\nline 3';
+      const expected = '  line 1\n  line 2\n  line 3';
+      expect(indentLines(input)).toBe(expected);
+    });
+
+    it('should add custom number of spaces', () => {
+      const input = 'line 1\nline 2';
+      const expected = '    line 1\n    line 2';
+      expect(indentLines(input, 4)).toBe(expected);
+    });
+
+    it('should handle single line text', () => {
+      expect(indentLines('single line')).toBe('  single line');
+      expect(indentLines('single line', 4)).toBe('    single line');
+    });
+
+    it('should handle empty string', () => {
+      expect(indentLines('')).toBe('  ');
+      expect(indentLines('', 4)).toBe('    ');
+    });
+
+    it('should handle non-string input', () => {
+      expect(indentLines(null)).toBe('');
+      expect(indentLines(undefined)).toBe('');
+      expect(indentLines(123)).toBe('');
+    });
+
+    it('should preserve existing indentation', () => {
+      const input = '  already indented\n  line 2';
+      const expected = '    already indented\n    line 2';
+      expect(indentLines(input)).toBe(expected);
+    });
+
+    it('should work with tabs', () => {
+      const input = 'line 1\nline 2';
+      expect(indentLines(input, 0)).toBe('line 1\nline 2');
+    });
+  });
+
+  describe('indentHTML', () => {
+    it('should properly indent nested HTML with default 2 spaces', () => {
+      const input = '<div>\n<p>Content</p>\n</div>';
+      const expected = '<div>\n  <p>Content</p>\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should handle multiple levels of nesting', () => {
+      const input = '<div>\n<div>\n<p>Content</p>\n</div>\n</div>';
+      const expected = '<div>\n  <div>\n    <p>Content</p>\n  </div>\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should handle void elements without increasing depth', () => {
+      const input = '<div>\n<img src="test.jpg">\n<br>\n<input type="text">\n</div>';
+      const expected = '<div>\n  <img src="test.jpg">\n  <br>\n  <input type="text">\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should handle self-closing tags', () => {
+      const input = '<div>\n<img src="test.jpg" />\n<component />\n</div>';
+      const expected = '<div>\n  <img src="test.jpg" />\n  <component />\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should handle elements with opening and closing tags on same line', () => {
+      const input = '<div>\n<p>Title</p>\n<span>Text</span>\n</div>';
+      const expected = '<div>\n  <p>Title</p>\n  <span>Text</span>\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should handle HTML comments', () => {
+      const input = '<div>\n<!-- Comment -->\n<p>Content</p>\n</div>';
+      const expected = '<div>\n  <!-- Comment -->\n  <p>Content</p>\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should use custom indent string', () => {
+      const input = '<div>\n<p>Content</p>\n</div>';
+      const expected = '<div>\n    <p>Content</p>\n</div>';
+      expect(indentHTML(input, { indent: '    ' })).toBe(expected);
+    });
+
+    it('should use custom indent with tabs', () => {
+      const input = '<div>\n<p>Content</p>\n</div>';
+      const expected = '<div>\n\t<p>Content</p>\n</div>';
+      expect(indentHTML(input, { indent: '\t' })).toBe(expected);
+    });
+
+    it('should respect startLevel option', () => {
+      const input = '<div>\n<p>Content</p>\n</div>';
+      const expected = '  <div>\n    <p>Content</p>\n  </div>';
+      expect(indentHTML(input, { startLevel: 1 })).toBe(expected);
+    });
+
+    it('should remove empty lines by default', () => {
+      const input = '<div>\n\n<p>Content</p>\n\n</div>';
+      const expected = '<div>\n  <p>Content</p>\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should preserve empty lines when trimEmptyLines is false', () => {
+      const input = '<div>\n\n<p>Content</p>\n\n</div>';
+      const expected = '<div>\n  \n  <p>Content</p>\n  \n</div>';
+      expect(indentHTML(input, { trimEmptyLines: false })).toBe(expected);
+    });
+
+    it('should handle messy indentation from template literals', () => {
+      const input = `<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>`;
+
+      const expected = `<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>`;
+
+      expect(indentHTML(input)).toBe(expected);
+    });
+
+    it('should handle all void elements', () => {
+      const voidTags = [
+        'area',
+        'base',
+        'br',
+        'col',
+        'embed',
+        'hr',
+        'img',
+        'input',
+        'link',
+        'meta',
+        'param',
+        'source',
+        'track',
+        'wbr',
+      ];
+
+      voidTags.forEach(tag => {
+        const input = `<div>\n<${tag}>\n</div>`;
+        const expected = `<div>\n  <${tag}>\n</div>`;
+        expect(indentHTML(input)).toBe(expected);
+      });
+    });
+
+    it('should handle complex real-world HTML', () => {
+      const input = `<div class="ui segment">
+<div class="ui header">
+Product List
+</div>
+<div class="ui list">
+<div class="item">
+<img src="product1.jpg" />
+<div class="content">
+<div class="header">Product 1</div>
+<div class="description">Description here</div>
+</div>
+</div>
+<div class="item">
+<img src="product2.jpg" />
+<div class="content">
+<div class="header">Product 2</div>
+</div>
+</div>
+</div>
+</div>`;
+
+      const result = indentHTML(input);
+
+      // Verify structure by checking key lines
+      expect(result).toContain('  <div class="ui header">');
+      expect(result).toContain('    <div class="item">');
+      expect(result).toContain('      <img src="product1.jpg" />');
+      expect(result).toContain('        <div class="header">Product 1</div>');
+    });
+
+    it('should handle non-string input', () => {
+      expect(indentHTML(null)).toBe('');
+      expect(indentHTML(undefined)).toBe('');
+      expect(indentHTML(123)).toBe('');
+    });
+
+    it('should handle empty string', () => {
+      expect(indentHTML('')).toBe('');
+    });
+
+    it('should not break on attributes with angle brackets in values', () => {
+      const input = '<div>\n<input placeholder="Enter <value>">\n</div>';
+      const expected = '<div>\n  <input placeholder="Enter <value>">\n</div>';
+      expect(indentHTML(input)).toBe(expected);
+    });
+  });
+});
diff --git a/packages/utils/types/html.d.ts b/packages/utils/types/html.d.ts
@@ -0,0 +1,69 @@
+/**
+ * HTML and text formatting utility functions
+ * @see {@link https://next.semantic-ui.com/docs/api/utils/html HTML Utilities Documentation}
+ */
+
+/**
+ * Adds consistent indentation to every line of text
+ * @see {@link https://next.semantic-ui.com/docs/api/utils/html#indentlines indentLines}
+ * @see {@link https://next.semantic-ui.com/examples/utils-indentlines Example}
+ *
+ * @param text - The text to indent
+ * @param spaces - Number of spaces to indent each line
+ * @returns The indented text. Returns empty string for non-string input
+ *
+ * @example
+ * ```ts
+ * indentLines('line 1\nline 2', 2) // returns '  line 1\n  line 2'
+ * indentLines('line 1\nline 2', 4) // returns '    line 1\n    line 2'
+ * indentLines('code', 0) // returns 'code'
+ * ```
+ */
+export function indentLines(text: string, spaces?: number): string;
+
+/**
+ * Options for the `indentHTML` function.
+ */
+interface IndentHTMLOptions {
+  /**
+   * String to use for each level of indentation.
+   * @default '  ' (two spaces)
+   */
+  indent?: string;
+  /**
+   * Initial nesting level to start indentation from.
+   * @default 0
+   */
+  startLevel?: number;
+  /**
+   * Whether to remove empty lines from the output.
+   * @default true
+   */
+  trimEmptyLines?: boolean;
+}
+
+/**
+ * Intelligently indents HTML markup with proper nesting
+ * @see {@link https://next.semantic-ui.com/docs/api/utils/html#indenthtml indentHTML}
+ * @see {@link https://next.semantic-ui.com/examples/utils-indenthtml Example}
+ *
+ * @param html - The HTML string to indent
+ * @param options - Options for indentation behavior
+ * @returns The properly indented HTML. Returns empty string for non-string input
+ *
+ * @example
+ * ```ts
+ * indentHTML('<div>\n<p>Content</p>\n</div>')
+ * // returns '<div>\n  <p>Content</p>\n</div>'
+ *
+ * indentHTML('<div>\n<p>Content</p>\n</div>', { indent: '\t' })
+ * // returns '<div>\n\t<p>Content</p>\n</div>'
+ *
+ * indentHTML('<div>\n<p>Content</p>\n</div>', { startLevel: 1 })
+ * // returns '  <div>\n    <p>Content</p>\n  </div>'
+ *
+ * indentHTML('<div>\n<img src="test.jpg">\n<br>\n</div>')
+ * // returns '<div>\n  <img src="test.jpg">\n  <br>\n</div>'
+ * ```
+ */
+export function indentHTML(html: string, options?: IndentHTMLOptions): string;
diff --git a/packages/utils/types/index.d.ts b/packages/utils/types/index.d.ts
@@ -9,6 +9,7 @@ export * from './environment';
 export * from './equality';
 export * from './errors';
 export * from './functions';
+export * from './html';
 export * from './loops';
 export * from './numbers';
 export * from './objects';
