@anyblades/buildawesome-kit-plugin 1.3.0-alpha

package/filters/attr_concat.test.js

@@ -0,0 +1,205 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import attrConcat from "./attr_concat.js";
+
+describe("attrConcat", () => {
+  it("should concatenate array values to existing array attribute", () => {
+    const obj = { classes: ["foo", "bar"] };
+    const result = attrConcat(obj, "classes", ["baz", "qux"]);
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar", "baz", "qux"],
+    });
+  });
+
+  it("should parse JSON array string", () => {
+    const obj = { classes: ["foo", "bar"] };
+    const result = attrConcat(obj, "classes", '["baz", "qux", "quux"]');
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar", "baz", "qux", "quux"],
+    });
+  });
+
+  it("should handle single string value (not JSON)", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", "bar baz");
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar baz"],
+    });
+  });
+
+  it("should create new array if attribute doesn't exist", () => {
+    const obj = { name: "test" };
+    const result = attrConcat(obj, "classes", ["foo", "bar"]);
+
+    assert.deepStrictEqual(result, {
+      name: "test",
+      classes: ["foo", "bar"],
+    });
+  });
+
+  it("should handle empty object", () => {
+    const obj = {};
+    const result = attrConcat(obj, "classes", ["foo", "bar"]);
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar"],
+    });
+  });
+
+  it("should handle null object", () => {
+    const result = attrConcat(null, "classes", ["foo", "bar"]);
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar"],
+    });
+  });
+
+  it("should handle single value (non-array, non-string)", () => {
+    const obj = { ids: [1, 2] };
+    const result = attrConcat(obj, "ids", 3);
+
+    assert.deepStrictEqual(result, {
+      ids: [1, 2, 3],
+    });
+  });
+
+  it("should not mutate original object", () => {
+    const obj = { classes: ["foo", "bar"] };
+    const result = attrConcat(obj, "classes", ["baz"]);
+
+    assert.deepStrictEqual(obj, { classes: ["foo", "bar"] });
+    assert.deepStrictEqual(result, { classes: ["foo", "bar", "baz"] });
+    assert.notStrictEqual(obj, result);
+  });
+
+  it("should preserve other attributes", () => {
+    const obj = { classes: ["foo"], id: "test", data: { value: 42 } };
+    const result = attrConcat(obj, "classes", ["bar"]);
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar"],
+      id: "test",
+      data: { value: 42 },
+    });
+  });
+
+  it("should handle empty array values", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", []);
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo"],
+    });
+  });
+
+  it("should handle empty string values", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", "");
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", ""],
+    });
+  });
+
+  it("should handle multiline strings as single value (not JSON)", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", "bar\n\nbaz\n\n\nqux");
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar\n\nbaz\n\n\nqux"],
+    });
+  });
+
+  it("should remove duplicate values from existing array", () => {
+    const obj = { classes: ["foo", "bar"] };
+    const result = attrConcat(obj, "classes", ["bar", "baz"]);
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar", "baz"],
+    });
+  });
+
+  it("should remove duplicate values from new array", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", ["bar", "bar", "baz", "baz"]);
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar", "baz"],
+    });
+  });
+
+  it("should handle duplicates in JSON array strings", () => {
+    const obj = { classes: ["foo", "bar"] };
+    const result = attrConcat(obj, "classes", '["bar", "baz", "bar", "qux"]');
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar", "baz", "qux"],
+    });
+  });
+
+  it("should preserve order and remove only duplicates", () => {
+    const obj = { classes: ["a", "b", "c"] };
+    const result = attrConcat(obj, "classes", ["b", "d", "e", "a"]);
+
+    assert.deepStrictEqual(result, {
+      classes: ["a", "b", "c", "d", "e"],
+    });
+  });
+
+  it("should parse valid JSON array string", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", '["bar", "baz", "qux"]');
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar", "baz", "qux"],
+    });
+  });
+
+  it("should treat non-JSON string as single value", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", "bar\nbaz\nqux");
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", "bar\nbaz\nqux"],
+    });
+  });
+
+  it("should keep plain string as single value", () => {
+    const obj = { tags: ["existing"] };
+    const result = attrConcat(obj, "tags", "single value");
+
+    assert.deepStrictEqual(result, {
+      tags: ["existing", "single value"],
+    });
+  });
+
+  it("should parse JSON with numbers", () => {
+    const obj = { ids: [1, 2] };
+    const result = attrConcat(obj, "ids", "[3, 4, 5]");
+
+    assert.deepStrictEqual(result, {
+      ids: [1, 2, 3, 4, 5],
+    });
+  });
+
+  it("should treat invalid JSON as single string value", () => {
+    const obj = { classes: ["foo"] };
+    const result = attrConcat(obj, "classes", '["bar", "baz"'); // Invalid JSON
+
+    assert.deepStrictEqual(result, {
+      classes: ["foo", '["bar", "baz"'],
+    });
+  });
+
+  it("should treat JSON non-array as single value", () => {
+    const obj = { tags: ["foo"] };
+    const result = attrConcat(obj, "tags", '{"key": "value"}');
+
+    assert.deepStrictEqual(result, {
+      tags: ["foo", '{"key": "value"}'],
+    });
+  });
+});

package/filters/attr_includes.js

@@ -0,0 +1,41 @@
+/*<!--section:docs-->
+
+A filter that filters a list of items by checking if an attribute array includes a target value. Supports nested attribute names using dot notation.
+
+<!--section:code-->```js */
+import lodash from "@11ty/lodash-custom";
+const { get } = lodash;
+
+export default function (collection, attrName, targetValue) {
+  // If no targetValue, return original collection
+  if (!targetValue) {
+    return collection;
+  }
+
+  return collection.filter((item) => {
+    // Get the attribute value from the item (supports nested paths like "data.tags")
+    const attrValue = get(item, attrName);
+
+    // If the attribute is an array, check if it includes the target value
+    if (Array.isArray(attrValue)) {
+      return attrValue.includes(targetValue);
+    }
+
+    // Otherwise skip this item
+    return false;
+  });
+}
+/*```<!--section:docs-->
+
+### Examples
+
+Get all posts that include `#javascript` tag
+
+```jinja2 {data-caption="in .njk:"}
+{% set js_posts = collections.all | attr_includes('data.tags', '#javascript') %}
+
+{% for post in js_posts %}
+  <h2>{{ post.data.title }}</h2>
+{% endfor %}
+```
+*/

package/filters/attr_includes.test.js

@@ -0,0 +1,125 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import attrIncludes from "./attr_includes.js";
+
+describe("attrIncludes", () => {
+  it("should only work with array attributes, not exact matches", () => {
+    const collection = [
+      { category: "blog", title: "Post 1" },
+      { category: "news", title: "Post 2" },
+      { category: "blog", title: "Post 3" },
+    ];
+
+    // Non-array attributes are skipped
+    const result = attrIncludes(collection, "category", "blog");
+    assert.strictEqual(result.length, 0);
+  });
+
+  it("should filter items when attribute is an array (includes check)", () => {
+    const collection = [
+      { tags: ["javascript", "tutorial"], title: "Post 1" },
+      { tags: ["python", "tutorial"], title: "Post 2" },
+      { tags: ["javascript", "advanced"], title: "Post 3" },
+    ];
+
+    const result = attrIncludes(collection, "tags", "javascript");
+    assert.strictEqual(result.length, 2);
+    assert.strictEqual(result[0].title, "Post 1");
+    assert.strictEqual(result[1].title, "Post 3");
+  });
+
+  it("should throw error when collection is not an array", () => {
+    assert.throws(() => {
+      attrIncludes(null, "category", "blog");
+    }, TypeError);
+  });
+
+  it("should filter out items without array attributes", () => {
+    const collection = [
+      { tags: ["javascript"], title: "Post 1" },
+      { title: "Post 2" },
+      { tags: ["javascript"], title: "Post 3" },
+    ];
+
+    const result = attrIncludes(collection, "tags", "javascript");
+    assert.strictEqual(result.length, 2);
+  });
+
+  it("should work with array attribute directly on item (not in data)", () => {
+    const collection = [
+      { tags: ["blog"], title: "Post 1" },
+      { tags: ["news"], title: "Post 2" },
+      { tags: ["blog"], title: "Post 3" },
+    ];
+
+    const result = attrIncludes(collection, "tags", "blog");
+    assert.strictEqual(result.length, 2);
+  });
+
+  it("should handle array that does not include target value", () => {
+    const collection = [
+      { tags: ["python", "tutorial"], title: "Post 1" },
+      { tags: ["ruby", "guide"], title: "Post 2" },
+    ];
+
+    const result = attrIncludes(collection, "tags", "javascript");
+    assert.strictEqual(result.length, 0);
+  });
+
+  it("should handle different value types in arrays", () => {
+    const collection = [
+      { priorities: [1, 3], title: "Post 1" },
+      { priorities: [2, 4], title: "Post 2" },
+      { priorities: [1, 5], title: "Post 3" },
+    ];
+
+    const result = attrIncludes(collection, "priorities", 1);
+    assert.strictEqual(result.length, 2);
+  });
+
+  it("should support nested array attributes with dot notation", () => {
+    const collection = [
+      { data: { categories: ["blog"] }, title: "Post 1" },
+      { data: { categories: ["news"] }, title: "Post 2" },
+      { data: { categories: ["blog"] }, title: "Post 3" },
+    ];
+
+    const result = attrIncludes(collection, "data.categories", "blog");
+    assert.strictEqual(result.length, 2);
+    assert.strictEqual(result[0].title, "Post 1");
+    assert.strictEqual(result[1].title, "Post 3");
+  });
+
+  it("should support nested arrays with dot notation", () => {
+    const collection = [
+      { data: { tags: ["javascript", "tutorial"] }, title: "Post 1" },
+      { data: { tags: ["python", "tutorial"] }, title: "Post 2" },
+      { data: { tags: ["javascript", "advanced"] }, title: "Post 3" },
+    ];
+
+    const result = attrIncludes(collection, "data.tags", "javascript");
+    assert.strictEqual(result.length, 2);
+    assert.strictEqual(result[0].title, "Post 1");
+    assert.strictEqual(result[1].title, "Post 3");
+  });
+
+  it("should handle deeply nested array paths", () => {
+    const collection = [
+      { data: { meta: { statuses: ["published"] } }, title: "Post 1" },
+      { data: { meta: { statuses: ["draft"] } }, title: "Post 2" },
+      { data: { meta: { statuses: ["published"] } }, title: "Post 3" },
+    ];
+
+    const result = attrIncludes(collection, "data.meta.statuses", "published");
+    assert.strictEqual(result.length, 2);
+    assert.strictEqual(result[0].title, "Post 1");
+    assert.strictEqual(result[1].title, "Post 3");
+  });
+
+  it("should return empty array when nested array path does not exist", () => {
+    const collection = [{ data: { tags: ["blog"] }, title: "Post 1" }, { title: "Post 2" }];
+
+    const result = attrIncludes(collection, "data.nonexistent.path", "value");
+    assert.strictEqual(result.length, 0);
+  });
+});

package/filters/attr_set.js

@@ -0,0 +1,22 @@
+/*<!--section:docs-->
+
+A filter that creates a new object with an overridden attribute value. This is useful for modifying data objects in templates without mutating the original. Or even constructing an object from scratch.
+
+<!--section:code-->```js */
+export default function (obj, key, value) {
+  return {
+    ...obj,
+    [key]: value,
+  };
+}
+/*```<!--section:docs-->
+
+### Examples
+
+How to pass object(s) as argument(s) to a filter in `.liquid`?
+
+```liquid {data-caption="trick for '| renderContent' filter"}
+{% assign _ctx = null | attr_set: 'collections', collections %}
+{{ ... | renderContent: 'liquid,md', _ctx }}
+```
+*/

package/filters/attr_set.test.js

@@ -0,0 +1,71 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import attrSet from "./attr_set.js";
+
+test("attrSet - sets a single attribute", () => {
+  const result = attrSet({ a: 1 }, "b", 2);
+  assert.deepStrictEqual(result, { a: 1, b: 2 });
+});
+
+test("attrSet - overrides an existing attribute", () => {
+  const result = attrSet({ a: 1, b: 2 }, "b", 3);
+  assert.deepStrictEqual(result, { a: 1, b: 3 });
+});
+
+test("attrSet - sets attribute on empty object", () => {
+  const result = attrSet({}, "key", "value");
+  assert.deepStrictEqual(result, { key: "value" });
+});
+
+test("attrSet - does not modify original object", () => {
+  const original = { a: 1, b: 2 };
+  const result = attrSet(original, "c", 3);
+
+  assert.deepStrictEqual(original, { a: 1, b: 2 });
+  assert.deepStrictEqual(result, { a: 1, b: 2, c: 3 });
+});
+
+test("attrSet - works with different value types", () => {
+  const obj = { name: "test" };
+
+  // String
+  assert.deepStrictEqual(attrSet(obj, "str", "value"), { name: "test", str: "value" });
+
+  // Number
+  assert.deepStrictEqual(attrSet(obj, "num", 42), { name: "test", num: 42 });
+
+  // Boolean
+  assert.deepStrictEqual(attrSet(obj, "bool", true), { name: "test", bool: true });
+
+  // Array
+  assert.deepStrictEqual(attrSet(obj, "arr", [1, 2, 3]), { name: "test", arr: [1, 2, 3] });
+
+  // Object
+  assert.deepStrictEqual(attrSet(obj, "nested", { x: 1 }), { name: "test", nested: { x: 1 } });
+
+  // Null
+  assert.deepStrictEqual(attrSet(obj, "nil", null), { name: "test", nil: null });
+
+  // Undefined
+  assert.deepStrictEqual(attrSet(obj, "undef", undefined), { name: "test", undef: undefined });
+});
+
+test("attrSet - can chain multiple calls", () => {
+  const original = { a: 1 };
+  const step1 = attrSet(original, "b", 2);
+  const step2 = attrSet(step1, "c", 3);
+  const step3 = attrSet(step2, "d", 4);
+
+  assert.deepStrictEqual(original, { a: 1 });
+  assert.deepStrictEqual(step3, { a: 1, b: 2, c: 3, d: 4 });
+});
+
+test("attrSet - handles special characters in keys", () => {
+  const result = attrSet({}, "data-id", 123);
+  assert.deepStrictEqual(result, { "data-id": 123 });
+});
+
+test("attrSet - works with numeric keys", () => {
+  const result = attrSet({ a: 1 }, "0", "zero");
+  assert.deepStrictEqual(result, { a: 1, 0: "zero" });
+});

package/filters/date.js

@@ -0,0 +1,11 @@
+/*<!--section:docs-->
+
+Format a date value as an ISO 8601 date string (YYYY-MM-DD).
+Accepts any value accepted by the Date constructor and returns
+the date portion of the resulting ISO string.
+
+<!--section:code-->```js */
+export default function (dateVal) {
+  return new Date(dateVal).toISOString().split("T")[0];
+}
+//```

package/filters/date.test.js

@@ -0,0 +1,33 @@
+import { test } from "node:test";
+import assert from "node:assert";
+import date from "./date.js";
+
+test("date - formats a date string as YYYY-MM-DD", () => {
+  assert.strictEqual(date("2024-03-15"), "2024-03-15");
+});
+
+test("date - formats a Date object", () => {
+  assert.strictEqual(date(new Date("2024-03-15T00:00:00Z")), "2024-03-15");
+});
+
+test("date - formats a timestamp number", () => {
+  // 2024-01-01T00:00:00.000Z in ms
+  assert.strictEqual(date(1704067200000), "2024-01-01");
+});
+
+test("date - strips time portion from a datetime string", () => {
+  assert.strictEqual(date("2024-06-21T23:59:59Z"), "2024-06-21");
+});
+
+test("date - handles year boundaries (Dec 31)", () => {
+  assert.strictEqual(date("2023-12-31T23:59:59Z"), "2023-12-31");
+});
+
+test("date - handles leap day", () => {
+  assert.strictEqual(date("2024-02-29T00:00:00Z"), "2024-02-29");
+});
+
+test("date - returns NaN string for invalid date", () => {
+  // Invalid Date produces "Invalid Date" whose ISO string throws; just assert it throws
+  assert.throws(() => date("not-a-date"));
+});

package/filters/fetch.js

@@ -0,0 +1,80 @@
+/*<!--section:docs-->
+
+A filter that fetches content from remote URLs or local files. For local paths, it reads files relative to the input directory.
+
+For remote URLs, it uses `@11ty/eleventy-fetch` to download and cache files:
+
+```sh
+npm install @11ty/eleventy-fetch
+```
+
+> `NOTE:` If `@11ty/eleventy-fetch` is not installed, this filter will not be available. The plugin automatically detects whether the package is installed and only enables the filter if it's present.
+
+<!--section:code-->```js */
+import EleventyFetch from "@11ty/eleventy-fetch";
+import path from "path";
+import fs from "fs/promises";
+
+export default async function (url) {
+  if (!url) {
+    throw new Error("fetch filter requires a URL or path");
+  }
+
+  // Get the input directory from Eleventy config
+  const inputDir = this.eleventy.directories.input;
+
+  // Check if it's a URL or local path
+  const isUrl = url.startsWith("http://") || url.startsWith("https://");
+
+  try {
+    if (isUrl) {
+      // Handle remote URLs with eleventy-fetch
+      const cacheDirectory = path.join(inputDir, "_downloads");
+      const content = await EleventyFetch(url, {
+        duration: "1d", // Cache for 1 day by default
+        type: "text", // Return as text
+        directory: cacheDirectory,
+      });
+      return content.toString(); // toString() handles bytes cache (inside eleventyComputed)
+    } else {
+      // Handle local file paths relative to input directory
+      const filePath = path.join(inputDir, url);
+      const content = await fs.readFile(filePath, "utf-8");
+      return content;
+    }
+  } catch (error) {
+    throw new Error(`Failed to fetch ${url}: ${error.message}`);
+  }
+}
+/*```<!--section:docs-->
+
+### Examples
+
+```jinja2
+{# Fetch and display remote content #}
+{% set readme = "https://raw.githubusercontent.com/user/repo/main/README.md" | fetch %}
+<div class="readme">
+  {{ readme | markdown | safe }}
+</div>
+
+{# Fetch JSON data from API #}
+{% set data = "https://api.example.com/data.json" | fetch %}
+{% set items = data | fromJson %}
+{% for item in items %}
+  <p>{{ item.title }}</p>
+{% endfor %}
+
+{# Include local file content #}
+{% set changelog = "CHANGELOG.md" | fetch %}
+{{ changelog | markdown | safe }}
+
+{# Fetch CSS from CDN and inline it #}
+<style>
+  {{ "https://cdn.example.com/styles.css" | fetch }}
+</style>
+
+{# Reuse content across pages #}
+{% set sharedContent = "_includes/shared/footer.html" | fetch %}
+{{ sharedContent | safe }}
+```
+*/

package/filters/if.js

@@ -0,0 +1,24 @@
+/*<!--section:docs-->
+
+An inline conditional/ternary operator filter that returns one value if a condition is truthy, and another if it's falsy. Similar to Nunjucks' inline if syntax, it is especially useful in `.liquid` templates.
+
+<!--section:code-->```js */
+export default function (trueValue, condition, falseValue = "") {
+  // Treat empty objects {} as falsy
+  if (condition && typeof condition === "object" && !Array.isArray(condition) && Object.keys(condition).length === 0) {
+    return falseValue;
+  }
+  return !!condition ? trueValue : falseValue;
+}
+/*```<!--section:docs-->
+
+### Examples <!-- @TODO: better examples -->
+
+```liquid
+<button class="{{ 'btn-primary' | if: isPrimary | default: 'btn-secondary' }}">
+  Click me
+</button>
+
+<input type="checkbox" {{ 'checked' | if: isChecked }}>
+```
+<!--section--> */

package/filters/if.test.js

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert";
+import iff from "./if.js";
+
+test("iff returns trueValue when condition is truthy", () => {
+  assert.strictEqual(iff("yes", true, "no"), "yes");
+  assert.strictEqual(iff("yes", 1, "no"), "yes");
+  assert.strictEqual(iff("yes", "truthy", "no"), "yes");
+  assert.strictEqual(iff("yes", { a: 1 }, "no"), "yes"); // non-empty object is truthy
+  assert.strictEqual(iff("yes", [], "no"), "yes");
+});
+
+test("iff returns falseValue when condition is falsy", () => {
+  assert.strictEqual(iff("yes", false, "no"), "no");
+  assert.strictEqual(iff("yes", 0, "no"), "no");
+  assert.strictEqual(iff("yes", "", "no"), "no");
+  assert.strictEqual(iff("yes", null, "no"), "no");
+  assert.strictEqual(iff("yes", undefined, "no"), "no");
+});
+
+test("iff treats empty objects as falsy", () => {
+  assert.strictEqual(iff("yes", {}, "no"), "no");
+  assert.strictEqual(iff("yes", {}, ""), "");
+  assert.strictEqual(iff(100, {}, 200), 200);
+
+  // Non-empty objects should still be truthy
+  assert.strictEqual(iff("yes", { a: 1 }, "no"), "yes");
+  assert.strictEqual(iff("yes", { nested: {} }, "no"), "yes");
+});
+
+test("iff returns falseValue when condition is undefined", () => {
+  assert.strictEqual(iff("yes", undefined, "no"), "no");
+  assert.strictEqual(iff("yes", undefined), "");
+  assert.strictEqual(iff(100, undefined, 200), 200);
+});
+
+test("iff returns empty string as default falseValue", () => {
+  assert.strictEqual(iff("yes", false), "");
+  assert.strictEqual(iff("yes", 0), "");
+  assert.strictEqual(iff("yes", null), "");
+});
+
+test("iff works with various value types", () => {
+  assert.strictEqual(iff(100, true, 200), 100);
+  assert.strictEqual(iff(100, false, 200), 200);
+
+  const obj1 = { a: 1 };
+  const obj2 = { b: 2 };
+  assert.strictEqual(iff(obj1, true, obj2), obj1);
+  assert.strictEqual(iff(obj1, false, obj2), obj2);
+
+  const arr1 = [1, 2];
+  const arr2 = [3, 4];
+  assert.strictEqual(iff(arr1, true, arr2), arr1);
+  assert.strictEqual(iff(arr1, false, arr2), arr2);
+});
+
+test("iff evaluates condition correctly without type coercion confusion", () => {
+  // Common edge cases
+  assert.strictEqual(iff("yes", "false", "no"), "yes"); // string 'false' is truthy
+  assert.strictEqual(iff("yes", "0", "no"), "yes"); // string '0' is truthy
+  assert.strictEqual(iff("yes", NaN, "no"), "no"); // NaN is falsy
+});