npm - @anydigital/11ty-bricks - Versions diffs - 1.0.0-alpha.5 → 1.0.0-alpha.7 - Mend

@anydigital/11ty-bricks 1.0.0-alpha.5 → 1.0.0-alpha.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.md CHANGED Viewed

@@ -22,7 +22,7 @@ import eleventyBricks from "@anydigital/11ty-bricks";
 export default function(eleventyConfig) {
   eleventyConfig.addPlugin(eleventyBricks, {
-    autoRaw: true  // Enable autoRaw preprocessor (default: false)
+    autoRawPreprocessor: true  // Enable autoRaw preprocessor (default: false)
   });
   // Your other configuration...
@@ -35,7 +35,7 @@ const eleventyBricks = require("@anydigital/11ty-bricks");
 module.exports = function(eleventyConfig) {
   eleventyConfig.addPlugin(eleventyBricks, {
-    autoRaw: true  // Enable autoRaw preprocessor (default: false)
+    autoRawPreprocessor: true  // Enable autoRaw preprocessor (default: false)
   });
   // Your other configuration...
@@ -76,14 +76,18 @@ When using the plugin (Option 1), you can configure which helpers to enable:
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `bricksRegistry` | boolean | `false` | Enable the bricksRegistry system for dependency management |
-| `autoRaw` | boolean | `false` | Enable the autoRaw preprocessor for Markdown files |
+| `bricks` | boolean | `false` | Enable the bricks system for dependency management |
+| `autoRawPreprocessor` | boolean | `false` | Enable the autoRaw preprocessor for Markdown files |
+| `fragments` | boolean | `false` | Enable the fragment shortcode for including content from fragments |
+| `setAttrFilter` | boolean | `false` | Enable the setAttr filter for overriding object attributes |
+| `byAttrFilter` | boolean | `false` | Enable the byAttr filter for filtering collections by attribute values |
 **Example:**
 ```javascript
 eleventyConfig.addPlugin(eleventyBricks, {
-  bricksRegistry: true,
-  autoRaw: true
+  bricks: true,
+  autoRawPreprocessor: true,
+  byAttrFilter: true
 });
 ```
@@ -102,7 +106,7 @@ When building reusable components (bricks) in Eleventy, you often need to includ
 **How it works:**
-1. Use the `rootBrick` shortcode in your base template to mark where dependencies should be injected
+1. Use the `bricksRegistry` shortcode in your base template to mark where dependencies should be injected
 2. Use the `brick` shortcode to register and render brick components that declare their dependencies
 3. The system automatically collects all dependencies and injects them when the page is built
@@ -120,13 +124,15 @@ export default function(eleventyConfig) {
 }
 ```
-2. Add the `rootBrick` shortcode in your base template (typically in the `<head>` section):
+2. Add the `bricksDependencies` shortcode in your base template (typically in the `<head>` section):
 ```njk
 <head>
   <meta charset="UTF-8">
   <title>My Site</title>
-  {% rootBrick %}
+  {% bricksDependencies [
+    ... (global dependencies can be set here) ...
+  ] %}
   <!-- Other head content -->
 </head>
 ```
@@ -209,84 +215,238 @@ Use {{ variable }} to output variables.
 Would try to process `{{ variable }}` as a template variable. With `autoRaw`, it displays exactly as written.
-## Available Bricks (Components)
+### fragment
-### Navigation Macro (`_nav.njk`)
+A shortcode that includes content from fragment files stored in the `_fragments` directory. The content will be processed by the template engine.
-A reusable Nunjucks macro for rendering navigation menus with proper accessibility attributes. This macro works seamlessly with the [11ty Navigation Plugin](https://www.11ty.dev/docs/plugins/navigation/).
+**Why use this?**
+Fragments allow you to organize reusable content snippets in a dedicated directory and include them in your templates. This is useful for:
+- Reusable content blocks
+- Shared template sections
+- Component-like content organization
 **Usage:**
-1. Import the macro in your template:
+1. Enable `fragment` in your Eleventy config:
-```njk
-{% from "bricks/_nav.njk" import render as renderNav %}
+```javascript
+import { fragment } from "@anydigital/11ty-bricks";
+export default function(eleventyConfig) {
+  fragment(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { fragments: true });
+}
+```
+2. Create fragment files in the `_fragments` directory (relative to your input directory):
+```
+your-project/
+  _fragments/
+    header.njk
+    footer.njk
+    callout.md
 ```
-2. Call the macro with your navigation data:
+3. Use the `fragment` shortcode in your templates:
 ```njk
-{{ renderNav(collections.all | eleventyNavigation, page) }}
+{% fragment "header.njk" %}
+<main>
+  <!-- Your content -->
+</main>
+{% fragment "footer.njk" %}
 ```
 **Parameters:**
-- `navPages`: Array of navigation entries (typically from `eleventyNavigation` filter)
-- `curPage`: Current page object (use Eleventy's `page` variable)
+- `path`: The path to the fragment file relative to the `_fragments` directory
 **Features:**
-- Renders a semantic `<nav>` element
-- Automatically adds `aria-current="page"` to the current page link for accessibility
-- Clean, minimal markup ready for styling
-- Works with nested navigation structures from the 11ty Navigation Plugin
+- Reads files from `_fragments` directory in your input directory
+- Content is processed by the template engine
+- Supports any template language that Eleventy supports
+- Shows helpful error comment if fragment is not found
+**Example:**
-**Example Output:**
+Create `_fragments/callout.njk`:
+```njk
+<div class="callout callout-{{ type | default('info') }}">
+  {{ content }}
+</div>
+```
-```html
-<nav>
-  <a href="/">Home</a>
-  <a href="/about/">About</a>
-  <a href="/contact/" aria-current="page">Contact</a>
-</nav>
+Use it in your template:
+```njk
+{% set type = "warning" %}
+{% set content = "This is important!" %}
+{% fragment "callout.njk" %}
 ```
-### Google Tag Manager Macro (`_gtm.njk`)
+### setAttr
-A reusable Nunjucks macro for integrating Google Tag Manager (GTM) into your site. Provides separate macros for the head and body GTM snippets.
+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.
+**Why use this?**
+When working with Eleventy data, you sometimes need to modify an object's properties for a specific use case. The `setAttr` filter provides a clean way to create a modified copy of an object without affecting the original.
 **Usage:**
-1. Import the macros in your base template:
+1. Enable `setAttr` in your Eleventy config:
+```javascript
+import { setAttr } from "@anydigital/11ty-bricks";
+export default function(eleventyConfig) {
+  setAttr(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { setAttrFilter: true });
+}
+```
+2. Use the filter in your templates:
 ```njk
-{% import 'bricks/_gtm.njk' as gtm %}
+{# Create a modified version of a page object #}
+{% set modifiedPage = page | setAttr('title', 'New Title') %}
+<h1>{{ modifiedPage.title }}</h1>
+<p>Original title: {{ page.title }}</p>
 ```
-2. Call the macros in the appropriate locations:
+**Parameters:**
+- `obj`: The object to modify
+- `key`: The attribute name to set (string)
+- `value`: The value to set for the attribute (any type)
+**Returns:**
+A new object with the specified attribute set to the given value. The original object is not modified.
+**Features:**
+- Non-mutating: Creates a new object, leaving the original unchanged
+- Works with any object type
+- Supports any attribute name and value type
+- Can be chained with other filters
+**Examples:**
 ```njk
-<head>
-  <!-- Other head content -->
-  {{ gtm.renderHead('GTM-XXXXXXX') }}
-</head>
-<body>
-  {{ gtm.renderBody('GTM-XXXXXXX') }}
-  <!-- Rest of body content -->
-</body>
+{# Override a single attribute #}
+{% set updatedPost = post | setAttr('featured', true) %}
+{# Chain multiple setAttr filters #}
+{% set modifiedPost = post
+  | setAttr('category', 'blog')
+  | setAttr('priority', 1)
+%}
+{# Use in loops #}
+{% for item in collection %}
+  {% set enhancedItem = item | setAttr('processed', true) %}
+  {# ... use enhancedItem ... #}
+{% endfor %}
+```
+### byAttr
+A filter that filters collection items by attribute value. It checks if an item's attribute matches a target value. If the attribute is an array, it checks if the array includes the target value.
+**Why use this?**
+When working with Eleventy collections, you often need to filter items based on front matter data. The `byAttr` filter provides a flexible way to filter by any attribute, with special handling for array attributes (like tags).
+**Usage:**
+1. Enable `byAttr` in your Eleventy config:
+```javascript
+import { byAttr } from "@anydigital/11ty-bricks";
+export default function(eleventyConfig) {
+  byAttr(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { byAttrFilter: true });
+}
+```
+2. Use the filter in your templates:
+**Filter by exact attribute match:**
+```njk
+{# Get all posts with category 'blog' #}
+{% set blogPosts = collections.all | byAttr('category', 'blog') %}
+{% for post in blogPosts %}
+  <h2>{{ post.data.title }}</h2>
+{% endfor %}
+```
+**Filter by array attribute (tags):**
+```njk
+{# Get all posts that include 'javascript' tag #}
+{% set jsPosts = collections.all | byAttr('tags', 'javascript') %}
+{% for post in jsPosts %}
+  <h2>{{ post.data.title }}</h2>
+{% endfor %}
 ```
 **Parameters:**
-Both macros accept the same parameter:
-- `gtmId`: Your Google Tag Manager container ID (e.g., `'GTM-XXXXXXX'`)
+- `collection`: The collection to filter (array of items)
+- `attrName`: The attribute name to check (string)
+- `targetValue`: The value to match against (any type)
 **Features:**
-- Separate macros for head and body placement as recommended by Google
-- Clean, standard GTM implementation
-- Easy to maintain and update across your site
-- Works with all GTM features including noscript fallback
+- Works with any attribute in front matter
+- Handles both `item.data.attrName` and `item.attrName` patterns
+- Special handling for array attributes (uses `includes()` check)
+- Returns empty array if collection is invalid
+- Filters out items without the specified attribute
+**Examples:**
+Front matter:
+```yaml
+---
+title: My Post
+category: blog
+tags: [javascript, tutorial, beginner]
+priority: 1
+---
+```
+Template usage:
+```njk
+{# Filter by category #}
+{% set blogPosts = collections.all | byAttr('category', 'blog') %}
+{# Filter by tag (array) #}
+{% set jsTutorials = collections.all | byAttr('tags', 'javascript') %}
+{# Filter by numeric value #}
+{% set highPriority = collections.all | byAttr('priority', 1) %}
+{# Chain filters #}
+{% set recentBlogPosts = collections.all | byAttr('category', 'blog') | reverse | limit(5) %}
+```
+### Additional Exports
+The plugin also exports the following for advanced usage:
+- `transformAutoRaw(content)`: The transform function used by `autoRaw` preprocessor. Can be used programmatically to wrap Nunjucks syntax with raw tags.
 ## CLI Helper Commands

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@anydigital/11ty-bricks",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.7",
   "description": "A collection of helpful utilities and filters for Eleventy (11ty)",
   "type": "module",
   "main": "./src/index.js",

package/src/bricksRegistry.js CHANGED Viewed

@@ -23,7 +23,7 @@ export function bricksRegistry(eleventyConfig) {
   });
   // brick shortcode: registers and renders a brick component
-  eleventyConfig.addShortcode("brick", function(brickModule) {
+  eleventyConfig.addShortcode("brick", function(brickModule, ...args) {
     const registry = getPageRegistry(this.page);
     if (!brickModule) return '';
@@ -47,19 +47,19 @@ export function bricksRegistry(eleventyConfig) {
     // Render the brick using render() macro
     if (brickModule.render && typeof brickModule.render === 'function') {
-      return brickModule.render();
+      return brickModule.render(...args);
     }
     return '';
   });
-  // rootBrick shortcode: outputs placeholder and base dependencies
-  eleventyConfig.addShortcode("rootBrick", function(options = {}) {
+  // bricksRegistry shortcode: outputs placeholder and base dependencies
+  eleventyConfig.addShortcode("bricksDependencies", function(dependencies = []) {
     const registry = getPageRegistry(this.page);
     // Register root dependencies if provided (categorized later in transform)
-    if (options.dependencies) {
-      options.dependencies.forEach(dep => {
+    if (dependencies && Array.isArray(dependencies)) {
+      dependencies.forEach(dep => {
         registry.dependencies.add(dep);
       });
     }

package/src/byAttr.js ADDED Viewed

@@ -0,0 +1,35 @@
+/**
+ * byAttr filter - Filter collection items by attribute value
+ *
+ * This filter 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.
+ *
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ */
+export function byAttr(eleventyConfig) {
+  eleventyConfig.addFilter("byAttr", function(collection, attrName, targetValue) {
+    if (!collection || !Array.isArray(collection)) {
+      return [];
+    }
+    return collection.filter(item => {
+      // Get the attribute value from the item's data
+      const attrValue = item?.data?.[attrName] ?? item?.[attrName];
+      // If attribute doesn't exist, skip this item
+      if (attrValue === undefined || attrValue === null) {
+        return false;
+      }
+      // If the attribute is an array, check if it includes the target value
+      if (Array.isArray(attrValue)) {
+        return attrValue.includes(targetValue);
+      }
+      // Otherwise, do a direct comparison
+      return attrValue === targetValue;
+    });
+  });
+}

package/src/byAttr.test.js ADDED Viewed

@@ -0,0 +1,105 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { byAttr } from './byAttr.js';
+describe('byAttr filter', () => {
+  let filterFn;
+  // Mock eleventyConfig to capture the filter function
+  const mockEleventyConfig = {
+    addFilter(name, fn) {
+      if (name === 'byAttr') {
+        filterFn = fn;
+      }
+    }
+  };
+  // Register the filter
+  byAttr(mockEleventyConfig);
+  it('should filter items by exact attribute match', () => {
+    const collection = [
+      { data: { category: 'blog' }, title: 'Post 1' },
+      { data: { category: 'news' }, title: 'Post 2' },
+      { data: { category: 'blog' }, title: 'Post 3' }
+    ];
+    const result = filterFn(collection, 'category', 'blog');
+    assert.strictEqual(result.length, 2);
+    assert.strictEqual(result[0].title, 'Post 1');
+    assert.strictEqual(result[1].title, 'Post 3');
+  });
+  it('should filter items when attribute is an array (includes check)', () => {
+    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 = filterFn(collection, 'tags', 'javascript');
+    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 collection is not an array', () => {
+    const result = filterFn(null, 'category', 'blog');
+    assert.strictEqual(result.length, 0);
+  });
+  it('should filter out items without the specified attribute', () => {
+    const collection = [
+      { data: { category: 'blog' }, title: 'Post 1' },
+      { data: {}, title: 'Post 2' },
+      { data: { category: 'blog' }, title: 'Post 3' }
+    ];
+    const result = filterFn(collection, 'category', 'blog');
+    assert.strictEqual(result.length, 2);
+  });
+  it('should work with attribute directly on item (not in data)', () => {
+    const collection = [
+      { category: 'blog', title: 'Post 1' },
+      { category: 'news', title: 'Post 2' },
+      { category: 'blog', title: 'Post 3' }
+    ];
+    const result = filterFn(collection, 'category', 'blog');
+    assert.strictEqual(result.length, 2);
+  });
+  it('should handle mixed data structures', () => {
+    const collection = [
+      { data: { category: 'blog' }, title: 'Post 1' },
+      { category: 'blog', title: 'Post 2' },
+      { data: { category: 'news' }, title: 'Post 3' }
+    ];
+    const result = filterFn(collection, 'category', 'blog');
+    assert.strictEqual(result.length, 2);
+  });
+  it('should handle array that does not include target value', () => {
+    const collection = [
+      { data: { tags: ['python', 'tutorial'] }, title: 'Post 1' },
+      { data: { tags: ['ruby', 'guide'] }, title: 'Post 2' }
+    ];
+    const result = filterFn(collection, 'tags', 'javascript');
+    assert.strictEqual(result.length, 0);
+  });
+  it('should handle different value types', () => {
+    const collection = [
+      { data: { priority: 1 }, title: 'Post 1' },
+      { data: { priority: 2 }, title: 'Post 2' },
+      { data: { priority: 1 }, title: 'Post 3' }
+    ];
+    const result = filterFn(collection, 'priority', 1);
+    assert.strictEqual(result.length, 2);
+  });
+});

package/src/fragment.js ADDED Viewed

@@ -0,0 +1,34 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+/**
+ * fragment shortcode - Include content from fragments
+ *
+ * This shortcode reads a file from the _fragments directory and includes
+ * its content. The content will be processed by the template engine.
+ *
+ * @param {Object} eleventyConfig - The Eleventy configuration object
+ */
+export function fragment(eleventyConfig) {
+  eleventyConfig.addShortcode("fragment", function(path) {
+    // Get the input directory from Eleventy's context
+    const inputDir = this.page?.inputPath
+      ? join(process.cwd(), eleventyConfig.dir?.input || ".")
+      : process.cwd();
+    // Construct the full path to the fragment file
+    const fragmentPath = join(inputDir, "_fragments", path);
+    try {
+      // Read the fragment file
+      const content = readFileSync(fragmentPath, "utf8");
+      // Return content to be processed by the template engine
+      return content;
+    } catch (error) {
+      console.error(`Error reading fragment at ${fragmentPath}:`, error.message);
+      return `<!-- Fragment not found: ${path} -->`;
+    }
+  });
+}

package/src/index.cjs CHANGED Viewed

@@ -18,3 +18,15 @@ module.exports.autoRaw = async function(eleventyConfig) {
   const { autoRaw } = await import('./index.js');
   return autoRaw(eleventyConfig);
 };
+module.exports.fragment = async function(eleventyConfig) {
+  const { fragment } = await import('./index.js');
+  return fragment(eleventyConfig);
+};
+module.exports.setAttr = async function(eleventyConfig) {
+  const { setAttr } = await import('./index.js');
+  return setAttr(eleventyConfig);
+};
+module.exports.byAttr = async function(eleventyConfig) {
+  const { byAttr } = await import('./index.js');
+  return byAttr(eleventyConfig);
+};

package/src/index.js CHANGED Viewed

@@ -1,5 +1,8 @@
 import { bricksRegistry } from "./bricksRegistry.js";
 import { autoRaw } from "./autoRaw.js";
+import { fragment } from "./fragment.js";
+import { setAttr } from "./setAttr.js";
+import { byAttr } from "./byAttr.js";
 /**
  * 11ty Bricks Plugin
@@ -9,18 +12,33 @@ import { autoRaw } from "./autoRaw.js";
  *
  * @param {Object} eleventyConfig - The Eleventy configuration object
  * @param {Object} options - Plugin options
- * @param {boolean} options.bricksRegistry - Enable bricksRegistry (default: false)
- * @param {boolean} options.autoRaw - Enable autoRaw preprocessor (default: false)
+ * @param {boolean} options.bricks - Enable bricks system with dependencies injection (default: false)
+ * @param {boolean} options.autoRawPreprocessor - Enable autoRaw preprocessor (default: false)
+ * @param {boolean} options.fragments - Enable fragment shortcode (default: false)
+ * @param {boolean} options.setAttrFilter - Enable setAttr filter (default: false)
+ * @param {boolean} options.byAttrFilter - Enable byAttr filter (default: false)
  */
 export default function eleventyBricksPlugin(eleventyConfig, options = {}) {
-  if (options.bricksRegistry) {
+  if (options.bricks) {
     bricksRegistry(eleventyConfig);
   }
-  if (options.autoRaw) {
+  if (options.autoRawPreprocessor) {
     autoRaw(eleventyConfig);
   }
+  if (options.fragments) {
+    fragment(eleventyConfig);
+  }
+  if (options.setAttrFilter) {
+    setAttr(eleventyConfig);
+  }
+  if (options.byAttrFilter) {
+    byAttr(eleventyConfig);
+  }
 }
 // Export individual helpers for granular usage
 export { bricksRegistry };
 export { autoRaw };
+export { fragment };
+export { setAttr };
+export { byAttr };

package/src/setAttr.js ADDED Viewed

@@ -0,0 +1,17 @@
+/**
+ * setAttr 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
+ */
+export function setAttr(eleventyConfig) {
+  eleventyConfig.addFilter("setAttr", function(obj, key, value) {
+    return {
+      ...obj,
+      [key]: value
+    };
+  });
+}

package/src/bricks/_gtm.njk DELETED Viewed

@@ -1,16 +0,0 @@
-{% macro renderHead(gtmId) %}
-<!-- Google Tag Manager -->
-<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
-new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
-j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
-'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
-})(window,document,'script','dataLayer','{{ gtmId }}');</script>
-<!-- End Google Tag Manager -->
-{% endmacro %}
-{% macro renderBody(gtmId) %}
-<!-- Google Tag Manager (noscript) -->
-<noscript><iframe src="https://www.googletagmanager.com/ns.html?id={{ gtmId }}"
-height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
-<!-- End Google Tag Manager (noscript) -->
-{% endmacro %}

package/src/bricks/_nav.njk DELETED Viewed

@@ -1,10 +0,0 @@
-{% macro render(navPages, curPage) %}
-{# https://www.11ty.dev/docs/plugins/navigation/#bring-your-own-html-render-the-menu-items-manually #}
-<nav>
-  {%- for entry in navPages %}
-  <a href="{{ entry.url }}" {{ 'aria-current="page"' | safe if entry.url == curPage.url }}>
-    {{- entry.title -}}
-  </a>
-  {%- endfor %}
-</nav>
-{% endmacro %}