@anyblades/buildawesome-kit-plugin 1.3.0-alpha

package/filters/merge.js

@@ -0,0 +1,51 @@
+/*<!--section:docs-->
+
+A filter that shallow-merges objects together, similar to Twig's merge filter. Later values override earlier ones. Non-object arguments are ignored.
+
+<!--section:code-->```js */
+export default function (first, ...rest) {
+  // If first argument is null or undefined, treat as empty object
+  if (first === null || first === undefined) {
+    first = {};
+  }
+
+  // Only support objects
+  if (typeof first === "object" && !Array.isArray(first)) {
+    // Merge objects using spread operator (shallow merge)
+    return rest.reduce(
+      (acc, item) => {
+        if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+          return { ...acc, ...item };
+        }
+        return acc;
+      },
+      { ...first },
+    );
+  }
+
+  // If first is not an object, return empty object
+  return {};
+}
+/*```<!--section:docs-->
+
+### Examples <!-- @TODO: better examples -->
+
+```jinja2
+{# Merge configuration objects #}
+{% set defaultConfig = { theme: 'light', lang: 'en' } %}
+{% set userConfig = { theme: 'dark' } %}
+{% set finalConfig = defaultConfig | merge(userConfig) %}
+
+{# Result: { theme: 'dark', lang: 'en' } #}
+```
+
+```jinja2
+{# Merge page metadata with defaults #}
+{% set defaultMeta = {
+  author: 'Site Admin',
+  category: 'general',
+  comments: false
+} %}
+{% set pageMeta = defaultMeta | merge(page.data) %}
+```
+*/

package/filters/merge.test.js

@@ -0,0 +1,51 @@
+import { test } from 'node:test';
+import assert from 'node:assert';
+import merge from './merge.js';
+
+test('merge - merges two objects', () => {
+  const result = merge({ a: 1, b: 2 }, { c: 3, d: 4 });
+  assert.deepStrictEqual(result, { a: 1, b: 2, c: 3, d: 4 });
+});
+
+test('merge - merges objects with override', () => {
+  const result = merge({ a: 1, b: 2 }, { b: 3, c: 4 });
+  assert.deepStrictEqual(result, { a: 1, b: 3, c: 4 });
+});
+
+test('merge - merges multiple objects', () => {
+  const result = merge({ a: 1 }, { b: 2 }, { c: 3 });
+  assert.deepStrictEqual(result, { a: 1, b: 2, c: 3 });
+});
+
+test('merge - handles null first argument', () => {
+  const result = merge(null, { a: 1 });
+  assert.deepStrictEqual(result, { a: 1 });
+});
+
+test('merge - handles undefined first argument', () => {
+  const result = merge(undefined, { a: 1 });
+  assert.deepStrictEqual(result, { a: 1 });
+});
+
+test('merge - does not modify original objects', () => {
+  const original = { a: 1 };
+  const result = merge(original, { b: 2 });
+
+  assert.deepStrictEqual(original, { a: 1 });
+  assert.deepStrictEqual(result, { a: 1, b: 2 });
+});
+
+test('merge - returns empty object for arrays', () => {
+  const result = merge([1, 2], [3, 4]);
+  assert.deepStrictEqual(result, {});
+});
+
+test('merge - returns empty object for primitives', () => {
+  const result = merge('string', { a: 1 });
+  assert.deepStrictEqual(result, {});
+});
+
+test('merge - ignores non-object arguments in rest', () => {
+  const result = merge({ a: 1 }, 'string', { b: 2 }, null, { c: 3 });
+  assert.deepStrictEqual(result, { a: 1, b: 2, c: 3 });
+});

package/filters/remove_tag.js

@@ -0,0 +1,42 @@
+/*<!--section:docs-->
+
+A filter that removes a specified HTML element from provided HTML content. It removes the tag along with its content, including self-closing tags.
+
+**Security note:** While this filter can help sanitize HTML content, it should not be relied upon as the sole security measure. For critical security requirements, use a dedicated HTML sanitization library on the server side before content reaches your templates.
+
+<!--section:code-->```js */
+export default function (html, tagName) {
+  if (!html || typeof html !== "string") {
+    return html;
+  }
+
+  if (typeof tagName !== "string" || !tagName) {
+    return html;
+  }
+
+  // Escape special regex characters in tag name
+  const escapedTag = tagName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+  // Remove opening and closing tags along with their content
+  // This regex matches: <tag attributes>content</tag>
+  const regex = new RegExp(`<${escapedTag}(?:\\s[^>]*)?>.*?<\\/${escapedTag}>`, "gis");
+  let result = html.replace(regex, "");
+
+  // Also remove self-closing tags: <tag />
+  const selfClosingRegex = new RegExp(`<${escapedTag}(?:\\s[^>]*)?\\s*\\/?>`, "gi");
+  result = result.replace(selfClosingRegex, "");
+
+  return result;
+}
+/*```<!--section:docs-->
+
+### Examples <!-- @TODO: better examples -->
+
+Remove all script tags from content
+
+```jinja2
+{% set cleanContent = htmlContent | remove_tag('script') %}
+
+{{ cleanContent | safe }}
+```
+*/

package/filters/remove_tag.test.js

@@ -0,0 +1,60 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import removeTag from './remove_tag.js';
+
+describe('removeTag', () => {
+  it('should remove a single tag with content', () => {
+    const html = '<div>Keep this</div><script>Remove this</script><p>Keep this too</p>';
+    const result = removeTag(html, 'script');
+
+    assert.strictEqual(result, '<div>Keep this</div><p>Keep this too</p>');
+  });
+
+  it('should remove multiple instances of the same tag', () => {
+    const html = '<p>First</p><script>One</script><p>Second</p><script>Two</script><p>Third</p>';
+    const result = removeTag(html, 'script');
+
+    assert.strictEqual(result, '<p>First</p><p>Second</p><p>Third</p>');
+  });
+
+  it('should handle tags with attributes', () => {
+    const html = '<div>Keep</div><script type="text/javascript" src="file.js">Code</script><p>Keep</p>';
+    const result = removeTag(html, 'script');
+
+    assert.strictEqual(result, '<div>Keep</div><p>Keep</p>');
+  });
+
+  it('should handle self-closing tags', () => {
+    const html = '<div>Keep</div><br /><p>Keep</p>';
+    const result = removeTag(html, 'br');
+
+    assert.strictEqual(result, '<div>Keep</div><p>Keep</p>');
+  });
+
+  it('should return original HTML if tag does not exist', () => {
+    const html = '<div>Keep this</div><p>Keep this too</p>';
+    const result = removeTag(html, 'script');
+
+    assert.strictEqual(result, html);
+  });
+
+  it('should handle empty or null input', () => {
+    assert.strictEqual(removeTag('', 'script'), '');
+    assert.strictEqual(removeTag(null, 'script'), null);
+    assert.strictEqual(removeTag(undefined, 'script'), undefined);
+  });
+
+  it('should be case-insensitive', () => {
+    const html = '<div>Keep</div><SCRIPT>Remove</SCRIPT><Script>Remove</Script><p>Keep</p>';
+    const result = removeTag(html, 'script');
+
+    assert.strictEqual(result, '<div>Keep</div><p>Keep</p>');
+  });
+
+  it('should handle nested content', () => {
+    const html = '<div>Keep</div><script><div>Nested</div></script><p>Keep</p>';
+    const result = removeTag(html, 'script');
+
+    assert.strictEqual(result, '<div>Keep</div><p>Keep</p>');
+  });
+});

package/filters/section.js

@@ -0,0 +1,82 @@
+/*<!--section:docs-->
+
+A filter that extracts a named section from content marked with HTML comments. This is useful for splitting a single content file (like a Markdown post) into multiple parts that can be displayed and styled independently in your templates.
+
+<!--section:code-->```js */
+export default function (content, sectionName) {
+  if (!content || typeof content !== "string") {
+    return content;
+  }
+
+  if (typeof sectionName !== "string" || !sectionName) {
+    return "";
+  }
+
+  // Normalize section name for comparison (trim whitespace)
+  const targetName = sectionName.trim().toLowerCase();
+
+  // Regex to match section markers with content up to the next section or end of string
+  // Captures: (1) section names, (2) content until next section marker or end
+  const sectionRegex = /<!--section:([^>]+)-->([\s\S]*?)(?=<!--section|$)/g;
+
+  let results = [];
+  let match;
+
+  // Find all sections
+  while ((match = sectionRegex.exec(content)) !== null) {
+    const namesStr = match[1];
+    const sectionContent = match[2];
+    const names = namesStr.split(",").map((n) => n.trim().toLowerCase());
+
+    // Check if any of the names match the target
+    if (names.includes(targetName)) {
+      results.push(sectionContent);
+    }
+  }
+
+  // Join all matching sections
+  return results.join("");
+}
+/*```<!--section:docs-->
+
+## Usage <!-- @TODO: better examples -->
+
+1. Mark sections in your content file (e.g., `post.md`):
+
+⚠️ `NOTE:` The `¡` symbol is used instead of `!` only to give examples below. Use `!` in your actual content files.
+
+```markdown
+# My Post
+
+<¡--section:intro-->
+
+This is the introduction that appears at the top of the page.
+
+<¡--section:main-->
+
+This is the main body of the post with all the details.
+
+<¡--section:summary,sidebar-->
+
+This content appears in both the summary and the sidebar!
+```
+
+2. Use the filter in your templates:
+
+```jinja2
+{# Get the intro section #}
+<div class="page-intro">
+  {{ content | section('intro') | safe }}
+</div>
+
+{# Get the main section #}
+<article>
+  {{ content | section('main') | safe }}
+</article>
+
+{# Get the sidebar section #}
+<aside>
+  {{ content | section('sidebar') | safe }}
+</aside>
+```
+*/

package/filters/section.test.js

@@ -0,0 +1,174 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import section from "./section.js";
+
+describe("section", () => {
+  it("should extract a single named section", () => {
+    const content = `Before
+<!--section:intro-->
+This is the intro
+<!--section:main-->
+This is the main`;
+
+    const result = section(content, "intro");
+    assert.strictEqual(result, "\nThis is the intro\n");
+  });
+
+  it("should extract section up to the next section marker", () => {
+    const content = `<!--section:first-->
+First content
+<!--section:second-->
+Second content
+<!--section:third-->
+Third content`;
+
+    const result = section(content, "second");
+    assert.strictEqual(result, "\nSecond content\n");
+  });
+
+  it("should extract section up to EOF when no next marker", () => {
+    const content = `<!--section:intro-->
+Intro content
+<!--section:main-->
+Main content that goes to the end`;
+
+    const result = section(content, "main");
+    assert.strictEqual(result, "\nMain content that goes to the end");
+  });
+
+  it("should handle section with multiple names", () => {
+    const content = `<!--section:header,nav-->
+Shared content
+<!--section:main-->
+Main content`;
+
+    const resultHeader = section(content, "header");
+    const resultNav = section(content, "nav");
+
+    assert.strictEqual(resultHeader, "\nShared content\n");
+    assert.strictEqual(resultNav, "\nShared content\n");
+  });
+
+  it("should handle section with multiple names (spaces around commas)", () => {
+    const content = `<!--section:header, nav , top-->
+Shared content
+<!--section:main-->
+Main content`;
+
+    const resultHeader = section(content, "header");
+    const resultNav = section(content, "nav");
+    const resultTop = section(content, "top");
+
+    assert.strictEqual(resultHeader, "\nShared content\n");
+    assert.strictEqual(resultNav, "\nShared content\n");
+    assert.strictEqual(resultTop, "\nShared content\n");
+  });
+
+  it("should return empty string for non-existent section", () => {
+    const content = `<!--section:intro-->
+Content here
+<!--section:main-->
+More content`;
+
+    const result = section(content, "footer");
+    assert.strictEqual(result, "");
+  });
+
+  it("should handle empty or null input", () => {
+    assert.strictEqual(section("", "test"), "");
+    assert.strictEqual(section(null, "test"), null);
+    assert.strictEqual(section(undefined, "test"), undefined);
+  });
+
+  it("should handle missing section name", () => {
+    const content = `<!--section:intro-->Content`;
+
+    assert.strictEqual(section(content, ""), "");
+    assert.strictEqual(section(content, null), "");
+    assert.strictEqual(section(content, undefined), "");
+  });
+
+  it("should be case-insensitive for section names", () => {
+    const content = `<!--section:INTRO-->
+Content here
+<!--section:Main-->
+More content`;
+
+    const result1 = section(content, "intro");
+    const result2 = section(content, "INTRO");
+    const result3 = section(content, "main");
+    const result4 = section(content, "MAIN");
+
+    assert.strictEqual(result1, "\nContent here\n");
+    assert.strictEqual(result2, "\nContent here\n");
+    assert.strictEqual(result3, "\nMore content");
+    assert.strictEqual(result4, "\nMore content");
+  });
+
+  it("should handle multiple sections with the same name", () => {
+    const content = `<!--section:note-->
+First note
+<!--section:main-->
+Main content
+<!--section:note-->
+Second note
+<!--section:footer-->
+Footer`;
+
+    const result = section(content, "note");
+    assert.strictEqual(result, "\nFirst note\n\nSecond note\n");
+  });
+
+  it("should handle sections with no content", () => {
+    const content = `<!--section:empty--><!--section:main-->
+Main content`;
+
+    const result = section(content, "empty");
+    assert.strictEqual(result, "");
+  });
+
+  it("should handle content before first section", () => {
+    const content = `Some preamble
+<!--section:intro-->
+Intro content`;
+
+    const result = section(content, "intro");
+    assert.strictEqual(result, "\nIntro content");
+  });
+
+  it("should handle complex real-world example", () => {
+    const content = `# Document Title
+
+<!--section:summary,abstract-->
+This is a summary that can be used as an abstract.
+<!--section:introduction-->
+This is the introduction.
+<!--section:methods-->
+These are the methods.
+<!--section:conclusion,summary-->
+This is the conclusion and also part of summary.`;
+
+    const summary = section(content, "summary");
+    const introduction = section(content, "introduction");
+    const methods = section(content, "methods");
+    const conclusion = section(content, "conclusion");
+
+    assert.strictEqual(
+      summary,
+      "\nThis is a summary that can be used as an abstract.\n\nThis is the conclusion and also part of summary.",
+    );
+    assert.strictEqual(introduction, "\nThis is the introduction.\n");
+    assert.strictEqual(methods, "\nThese are the methods.\n");
+    assert.strictEqual(conclusion, "\nThis is the conclusion and also part of summary.");
+  });
+
+  it("should handle section markers with extra whitespace", () => {
+    const content = `<!--section: intro -->
+Content
+<!--section: main -->
+More`;
+
+    const result = section(content, "intro");
+    assert.strictEqual(result, "\nContent\n");
+  });
+});

package/filters/split.js

@@ -0,0 +1,9 @@
+/*<!--section:docs-->
+
+Split a string into an array by a separator.
+
+<!--section:code-->```js */
+export default function (str, sep) {
+  return String(str ?? "").split(sep);
+}
+//```

package/filters/split.test.js

@@ -0,0 +1,39 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import split from "./split.js";
+
+test("split - splits by a single character separator", () => {
+  assert.deepStrictEqual(split("a,b,c", ","), ["a", "b", "c"]);
+});
+
+test("split - splits by a string separator", () => {
+  assert.deepStrictEqual(split("foo::bar::baz", "::"), ["foo", "bar", "baz"]);
+});
+
+test("split - splits by empty string into characters", () => {
+  assert.deepStrictEqual(split("abc", ""), ["a", "b", "c"]);
+});
+
+test("split - returns full string in array when separator not found", () => {
+  assert.deepStrictEqual(split("hello", ","), ["hello"]);
+});
+
+test("split - handles empty string input", () => {
+  assert.deepStrictEqual(split("", ","), [""]);
+});
+
+test("split - handles null input", () => {
+  assert.deepStrictEqual(split(null, ","), [""]);
+});
+
+test("split - handles undefined input", () => {
+  assert.deepStrictEqual(split(undefined, ","), [""]);
+});
+
+test("split - splits on whitespace", () => {
+  assert.deepStrictEqual(split("foo bar baz", " "), ["foo", "bar", "baz"]);
+});
+
+test("split - splits newlines", () => {
+  assert.deepStrictEqual(split("line1\nline2\nline3", "\n"), ["line1", "line2", "line3"]);
+});

package/filters/strip_tag.js

@@ -0,0 +1,39 @@
+/*<!--section:docs-->
+
+A filter that strips a specified HTML element from content while keeping its inner content intact. Only the opening and closing tags are removed; everything inside the tag is preserved in place.
+
+<!--section:code-->```js */
+export default function (html, tagName) {
+  if (!html || typeof html !== "string") {
+    return html;
+  }
+
+  if (typeof tagName !== "string" || !tagName) {
+    return html;
+  }
+
+  // Escape special regex characters in tag name
+  const escapedTag = tagName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+  // Remove opening tags (with optional attributes): <tag> or <tag attr="val">
+  const openingRegex = new RegExp(`<${escapedTag}(?:\\s[^>]*)?>`, "gi");
+  let result = html.replace(openingRegex, "");
+
+  // Remove closing tags: </tag>
+  const closingRegex = new RegExp(`<\\/${escapedTag}>`, "gi");
+  result = result.replace(closingRegex, "");
+
+  return result;
+}
+/*```<!--section:docs-->
+
+### Examples
+
+Unwrap a wrapping `<div>` from content:
+
+```jinja2
+{% set unwrapped = htmlContent | strip_tag('div') %}
+
+{{ unwrapped | safe }}
+```
+*/

package/filters/strip_tag.test.js

@@ -0,0 +1,74 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import stripTag from "./strip_tag.js";
+
+describe("stripTag", () => {
+  it("should strip a tag but keep its inner content", () => {
+    const html = "<div><p>Keep this</p></div>";
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, "<p>Keep this</p>");
+  });
+
+  it("should strip multiple instances of the same tag", () => {
+    const html = "<div>First</div><p>Middle</p><div>Second</div>";
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, "First<p>Middle</p>Second");
+  });
+
+  it("should handle tags with attributes", () => {
+    const html = '<div class="wrapper" id="main">Content</div>';
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, "Content");
+  });
+
+  it("should only strip the specified tag, leaving others intact", () => {
+    const html = "<div><span>Keep span</span><em>Keep em</em></div>";
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, "<span>Keep span</span><em>Keep em</em>");
+  });
+
+  it("should handle nested content with the same tag", () => {
+    const html = "<div>outer <div>inner</div> text</div>";
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, "outer inner text");
+  });
+
+  it("should return original HTML if tag does not exist", () => {
+    const html = "<p>Some text</p>";
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, html);
+  });
+
+  it("should handle empty or null input", () => {
+    assert.strictEqual(stripTag("", "div"), "");
+    assert.strictEqual(stripTag(null, "div"), null);
+    assert.strictEqual(stripTag(undefined, "div"), undefined);
+  });
+
+  it("should handle missing or invalid tagName", () => {
+    const html = "<div>Content</div>";
+    assert.strictEqual(stripTag(html, ""), html);
+    assert.strictEqual(stripTag(html, null), html);
+    assert.strictEqual(stripTag(html, undefined), html);
+  });
+
+  it("should be case-insensitive", () => {
+    const html = '<DIV class="foo">Content</DIV>';
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, "Content");
+  });
+
+  it("should preserve whitespace and newlines inside the tag", () => {
+    const html = "<div>\n  <p>Line 1</p>\n  <p>Line 2</p>\n</div>";
+    const result = stripTag(html, "div");
+
+    assert.strictEqual(result, "\n  <p>Line 1</p>\n  <p>Line 2</p>\n");
+  });
+});

package/filters/unindent.js

@@ -0,0 +1,11 @@
+/*<!--section:docs-->
+
+Remove the minimal common indentation from a multi-line string.
+
+<!--section:code-->```js */
+export default function (content) {
+  const lines = String(content ?? "").split("\n");
+  const minIndent = Math.min(...lines.filter((l) => l.trim()).map((l) => l.match(/^(\s*)/)[1].length));
+  return lines.map((l) => l.slice(minIndent)).join("\n");
+}
+//```

package/filters/unindent.test.js

@@ -0,0 +1,49 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import unindent from "./unindent.js";
+
+test("unindent - removes common leading spaces", () => {
+  const input = "    hello\n    world";
+  assert.strictEqual(unindent(input), "hello\nworld");
+});
+
+test("unindent - removes common leading tabs", () => {
+  const input = "\tfoo\n\tbar";
+  assert.strictEqual(unindent(input), "foo\nbar");
+});
+
+test("unindent - preserves relative indentation", () => {
+  const input = "    if true\n      inner\n    end";
+  assert.strictEqual(unindent(input), "if true\n  inner\nend");
+});
+
+test("unindent - ignores blank lines when computing min indent", () => {
+  const input = "    line1\n\n    line2";
+  assert.strictEqual(unindent(input), "line1\n\nline2");
+});
+
+test("unindent - does nothing when already at zero indent", () => {
+  const input = "hello\nworld";
+  assert.strictEqual(unindent(input), "hello\nworld");
+});
+
+test("unindent - handles single line", () => {
+  assert.strictEqual(unindent("  hello"), "hello");
+});
+
+test("unindent - handles null input", () => {
+  assert.strictEqual(unindent(null), "");
+});
+
+test("unindent - handles undefined input", () => {
+  assert.strictEqual(unindent(undefined), "");
+});
+
+test("unindent - handles empty string", () => {
+  assert.strictEqual(unindent(""), "");
+});
+
+test("unindent - mixed indent levels, strips only the minimum", () => {
+  const input = "  a\n    b\n  c";
+  assert.strictEqual(unindent(input), "a\n  b\nc");
+});