@anyblades/eleventy-blades 0.28.0-beta.2

package/src/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/src/filters/attr_includes.js

@@ -0,0 +1,65 @@
+// <!--section:code-->```js
+import lodash from "@11ty/lodash-custom";
+const { get } = lodash;
+
+/**
+ * Core logic for filtering collection items by attribute value
+ *
+ * This function takes a collection, an attribute name, and a target value,
+ * and returns items where the attribute matches the target value.
+ * If the attribute is an array, it checks if the array includes the target value.
+ *
+ * Supports nested attribute names using dot notation (e.g., "data.tags").
+ *
+ * @param {Array} collection - The collection to filter
+ * @param {string} attrName - The attribute name to check (supports dot notation for nested properties)
+ * @param {*} targetValue - The value to match against
+ * @returns {Array} Filtered collection
+ */
+export function attrIncludes(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;
+  });
+}
+
+/**
+ * Registers the attr_includes filter with Eleventy
+ *
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ */
+export function attrIncludesFilter(eleventyConfig) {
+  eleventyConfig.addFilter("attr_includes", attrIncludes);
+}
+/*```
+
+<!--section:docs-->
+### `attr_includes`
+
+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.
+
+**Why use this?** When working with Eleventy collections, you often need to filter items based on tags or other array attributes in front matter. The `attr_includes` filter provides a flexible way to filter by any array attribute, with support for nested properties using dot notation.
+
+#### Example: 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 %}
+```
+<!--section--> */

package/src/filters/attr_includes.test.js

@@ -0,0 +1,145 @@
+import { describe, it } from "node:test";
+import assert from "node:assert";
+import { attrIncludes, attrIncludesFilter } from "./attr_includes.js";
+
+describe("attrIncludes (core logic)", () => {
+  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);
+  });
+});
+
+describe("attrIncludesFilter (Eleventy integration)", () => {
+  it("should register the filter with eleventyConfig", () => {
+    let registeredName;
+    let registeredFn;
+
+    const mockEleventyConfig = {
+      addFilter(name, fn) {
+        registeredName = name;
+        registeredFn = fn;
+      },
+    };
+
+    attrIncludesFilter(mockEleventyConfig);
+
+    assert.strictEqual(registeredName, "attr_includes");
+    assert.strictEqual(typeof registeredFn, "function");
+    assert.strictEqual(registeredFn, attrIncludes);
+  });
+});

package/src/filters/attr_set.js

@@ -0,0 +1,42 @@
+// <!--section:code-->```js
+/**
+ * attr_set filter - Override an attribute and return the object
+ *
+ * This filter takes an object, a key, and a value, and returns a new object
+ * with the specified attribute set to the given value.
+ *
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ */
+
+/**
+ * Core attr_set function - Override an attribute and return a new object
+ *
+ * @param {Object} obj - The object to modify
+ * @param {string} key - The attribute name to set
+ * @param {*} value - The value to set for the attribute
+ * @returns {Object} A new object with the specified attribute set to the given value
+ */
+export function attrSet(obj, key, value) {
+  return {
+    ...obj,
+    [key]: value,
+  };
+}
+
+export function attrSetFilter(eleventyConfig) {
+  eleventyConfig.addFilter("attr_set", attrSet);
+}
+/*```
+
+<!--section:docs-->
+### `attr_set`
+
+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.
+
+#### Example: 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 }}
+```
+<!--section--> */

package/src/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/src/filters/fetch.js

@@ -0,0 +1,118 @@
+// <!--section:code-->```js
+import EleventyFetch from "@11ty/eleventy-fetch";
+import path from "path";
+import fs from "fs/promises";
+
+/**
+ * fetch filter - Fetch a URL or local file and return its raw content
+ *
+ * This filter takes a URL or local file path. For URLs, it downloads them
+ * using eleventy-fetch to the input directory's _downloads folder.
+ * For local paths, it reads them relative to the input directory.
+ *
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ */
+export function fetchFilter(eleventyConfig) {
+  eleventyConfig.addFilter("fetch", 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-->
+### `fetch`
+
+A filter that fetches content from remote URLs or local files. For remote URLs, it uses `@11ty/eleventy-fetch` to download and cache files. For local paths, it reads files relative to the input directory.
+
+**Why use this?** When building static sites, you often need to include content from external sources or reuse content from local files. The `fetch` filter provides a unified way to retrieve content from both remote URLs and local files, with automatic caching for remote resources to improve build performance.
+
+**Requirements:** This filter requires the `@11ty/eleventy-fetch` package to be installed:
+
+```bash
+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.
+
+**Features:**
+
+- Supports a URL (starting with `http://` or `https://`) or a local file path (relative to the input directory):
+  - **Remote URLs**: Downloads and caches content using `@11ty/eleventy-fetch`
+    - Caches files for 1 day by default
+    - Stores cached files in `[input-dir]/_downloads/` directory
+    - Automatically revalidates after cache expires
+  - **Local files**: Reads files relative to the Eleventy input directory
+    - No caching needed for local files
+    - Supports any file type that can be read as text
+- **Error handling**: Throws descriptive errors if fetching fails
+- **Conditional loading**: Only available when `@11ty/eleventy-fetch` is installed
+
+**Use Cases:**
+
+- Fetch content from external APIs during build time
+- Include README files from GitHub repositories
+- Reuse content from local files across multiple pages
+- Download and inline external CSS or JavaScript
+- Fetch data from headless CMS or external data sources
+- Include shared content snippets without using Eleventy's include syntax
+
+> `NOTE:` The filter returns raw text content. Use Eleventy's built-in filters like `| safe`, `| markdown`, or `| fromJson` to process the content as needed.
+
+**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 }}
+```
+<!--section--> */