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

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

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 (7) hide show

package/README.md CHANGED Viewed

@@ -48,9 +48,10 @@ Import only the specific helpers you need without using the plugin:
 **ES Modules:**
 ```javascript
-import { autoRaw } from "@anydigital/11ty-bricks";
+import { bricksRegistry, autoRaw } from "@anydigital/11ty-bricks";
 export default function(eleventyConfig) {
+  bricksRegistry(eleventyConfig);
   autoRaw(eleventyConfig);
   // Your other configuration...
@@ -59,9 +60,10 @@ export default function(eleventyConfig) {
 **CommonJS:**
 ```javascript
-const { autoRaw } = require("@anydigital/11ty-bricks");
+const { bricksRegistry, autoRaw } = require("@anydigital/11ty-bricks");
 module.exports = function(eleventyConfig) {
+  bricksRegistry(eleventyConfig);
   autoRaw(eleventyConfig);
   // Your other configuration...
@@ -74,17 +76,122 @@ 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 |
 **Example:**
 ```javascript
 eleventyConfig.addPlugin(eleventyBricks, {
+  bricksRegistry: true,
   autoRaw: true
 });
 ```
 ## Available 11ty Helpers
+### bricksRegistry
+A dependency management system for Eleventy that automatically collects and injects CSS and JavaScript dependencies (both external and inline) per page. This allows brick components to declare their dependencies, and the system will inject them in the correct location in your HTML.
+**Why use this?**
+When building reusable components (bricks) in Eleventy, you often need to include CSS and JavaScript dependencies. Instead of manually adding these to every page, `bricksRegistry` automatically:
+- Collects dependencies from all bricks used on a page
+- Categorizes them (external CSS, external JS, inline styles, inline scripts)
+- Injects them in the correct location in your HTML output
+**How it works:**
+1. Use the `rootBrick` 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
+**Usage:**
+1. Enable `bricksRegistry` in your Eleventy config:
+```javascript
+import { bricksRegistry } from "@anydigital/11ty-bricks";
+export default function(eleventyConfig) {
+  bricksRegistry(eleventyConfig);
+  // Or use as plugin:
+  // eleventyConfig.addPlugin(eleventyBricks, { bricksRegistry: true });
+}
+```
+2. Add the `rootBrick` shortcode in your base template (typically in the `<head>` section):
+```njk
+<head>
+  <meta charset="UTF-8">
+  <title>My Site</title>
+  {% rootBrick %}
+  <!-- Other head content -->
+</head>
+```
+3. Create brick components that declare their dependencies:
+```javascript
+// myBrick.js
+export default {
+  dependencies: [
+    'https://cdn.example.com/library.css',
+    'https://cdn.example.com/library.js'
+  ],
+  style: `
+    .my-component { color: blue; }
+  `,
+  script: `
+    console.log('Component initialized');
+  `,
+  render: function() {
+    return '<div class="my-component">Hello World</div>';
+  }
+};
+```
+4. Use the `brick` shortcode in your templates:
+```njk
+{% set myBrick = require('./myBrick.js') %}
+{% brick myBrick %}
+```
+**Brick Component Structure:**
+A brick component is a JavaScript object with the following optional properties:
+- `dependencies`: Array of URLs to external CSS or JavaScript files (e.g., `['https://cdn.example.com/style.css', 'https://cdn.example.com/script.js']`)
+- `style`: String containing inline CSS
+- `script`: String containing inline JavaScript
+- `render`: Function that returns the HTML markup for the component
+**Output:**
+The system will automatically inject all dependencies in the order they were registered:
+```html
+<head>
+  <meta charset="UTF-8">
+  <title>My Site</title>
+  <link rel="stylesheet" href="https://cdn.example.com/library.css">
+  <style>.my-component { color: blue; }</style>
+  <script src="https://cdn.example.com/library.js"></script>
+  <script>console.log('Component initialized');</script>
+  <!-- Other head content -->
+</head>
+```
+**Features:**
+- Automatic dependency collection per page
+- Categorizes dependencies (CSS vs JS, external vs inline)
+- Deduplicates dependencies (using Sets internally)
+- Works with both external URLs and inline code
+- Clears registry before each build to prevent stale data
 ### autoRaw
 Prevents Nunjucks syntax from being processed in Markdown files by automatically wrapping `{{`, `}}`, `{%`, and `%}` with `{% raw %}` tags.
@@ -102,6 +209,85 @@ Use {{ variable }} to output variables.
 Would try to process `{{ variable }}` as a template variable. With `autoRaw`, it displays exactly as written.
+## Available Bricks (Components)
+### Navigation Macro (`_nav.njk`)
+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/).
+**Usage:**
+1. Import the macro in your template:
+```njk
+{% from "bricks/_nav.njk" import render as renderNav %}
+```
+2. Call the macro with your navigation data:
+```njk
+{{ renderNav(collections.all | eleventyNavigation, page) }}
+```
+**Parameters:**
+- `navPages`: Array of navigation entries (typically from `eleventyNavigation` filter)
+- `curPage`: Current page object (use Eleventy's `page` variable)
+**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
+**Example Output:**
+```html
+<nav>
+  <a href="/">Home</a>
+  <a href="/about/">About</a>
+  <a href="/contact/" aria-current="page">Contact</a>
+</nav>
+```
+### Google Tag Manager Macro (`_gtm.njk`)
+A reusable Nunjucks macro for integrating Google Tag Manager (GTM) into your site. Provides separate macros for the head and body GTM snippets.
+**Usage:**
+1. Import the macros in your base template:
+```njk
+{% import 'bricks/_gtm.njk' as gtm %}
+```
+2. Call the macros in the appropriate locations:
+```njk
+<head>
+  <!-- Other head content -->
+  {{ gtm.renderHead('GTM-XXXXXXX') }}
+</head>
+<body>
+  {{ gtm.renderBody('GTM-XXXXXXX') }}
+  <!-- Rest of body content -->
+</body>
+```
+**Parameters:**
+Both macros accept the same parameter:
+- `gtmId`: Your Google Tag Manager container ID (e.g., `'GTM-XXXXXXX'`)
+**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
 ## CLI Helper Commands
 After installing this package, the `download-files` command becomes available:

package/package.json CHANGED Viewed

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

package/src/bricks/_gtm.njk ADDED Viewed

@@ -0,0 +1,16 @@
+{% 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 ADDED Viewed

@@ -0,0 +1,10 @@
+{% 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 %}

package/src/bricksRegistry.js ADDED Viewed

@@ -0,0 +1,125 @@
+export function bricksRegistry(eleventyConfig) {
+  // Brick Registry System
+  // Global registry to track dependencies per page
+  const brickRegistry = new Map();
+  // Helper to get or create page registry
+  function getPageRegistry(page) {
+    const pageUrl = page.url || page.outputPath || 'default';
+    if (!brickRegistry.has(pageUrl)) {
+      brickRegistry.set(pageUrl, {
+        dependencies: new Set(),  // Raw dependencies (URLs) - categorized later
+        inlineStyles: new Set(),
+        inlineScripts: new Set()
+      });
+    }
+    return brickRegistry.get(pageUrl);
+  }
+  // Clear registry before each build
+  eleventyConfig.on("eleventy.before", async () => {
+    brickRegistry.clear();
+  });
+  // brick shortcode: registers and renders a brick component
+  eleventyConfig.addShortcode("brick", function(brickModule) {
+    const registry = getPageRegistry(this.page);
+    if (!brickModule) return '';
+    // Register external dependencies (categorized later in transform)
+    if (brickModule.dependencies) {
+      brickModule.dependencies.forEach(dep => {
+        registry.dependencies.add(dep);
+      });
+    }
+    // Register inline styles directly from style variable
+    if (brickModule.style && brickModule.style.trim()) {
+      registry.inlineStyles.add(brickModule.style);
+    }
+    // Register inline scripts directly from script variable
+    if (brickModule.script && brickModule.script.trim()) {
+      registry.inlineScripts.add(brickModule.script);
+    }
+    // Render the brick using render() macro
+    if (brickModule.render && typeof brickModule.render === 'function') {
+      return brickModule.render();
+    }
+    return '';
+  });
+  // rootBrick shortcode: outputs placeholder and base dependencies
+  eleventyConfig.addShortcode("rootBrick", function(options = {}) {
+    const registry = getPageRegistry(this.page);
+    // Register root dependencies if provided (categorized later in transform)
+    if (options.dependencies) {
+      options.dependencies.forEach(dep => {
+        registry.dependencies.add(dep);
+      });
+    }
+    // Return placeholder comment that will be replaced by transform
+    return '<!-- BRICK_DEPENDENCIES_PLACEHOLDER -->';
+  });
+  // Transform to inject collected dependencies
+  eleventyConfig.addTransform("injectBrickDependencies", function(content, outputPath) {
+    if (!outputPath || !outputPath.endsWith(".html")) {
+      return content;
+    }
+    const pageUrl = this.page?.url || this.page?.outputPath || outputPath;
+    const registry = brickRegistry.get(pageUrl);
+    if (!registry || !content.includes('<!-- BRICK_DEPENDENCIES_PLACEHOLDER -->')) {
+      return content;
+    }
+    // Categorize dependencies by type
+    const externalStyles = [];
+    const externalScripts = [];
+    registry.dependencies.forEach(dep => {
+      // Categorize by type
+      if (dep.endsWith('.css') || dep.includes('.css?')) {
+        externalStyles.push(dep);
+      } else if (dep.endsWith('.js') || dep.includes('.js?')) {
+        externalScripts.push(dep);
+      }
+    });
+    // Build HTML for dependencies
+    let dependenciesHtml = '\n';
+    // Add external CSS links
+    externalStyles.forEach(href => {
+      dependenciesHtml += `  <link rel="stylesheet" href="${href}">\n`;
+    });
+    // Add inline styles
+    registry.inlineStyles.forEach(style => {
+      dependenciesHtml += `  <style>${style}</style>\n`;
+    });
+    // Add external script links
+    externalScripts.forEach(src => {
+      dependenciesHtml += `  <script src="${src}"></script>\n`;
+    });
+    // Add inline scripts
+    registry.inlineScripts.forEach(script => {
+      dependenciesHtml += `  <script>${script}</script>\n`;
+    });
+    dependenciesHtml += '  ';
+    // Replace placeholder with actual dependencies
+    return content.replace('<!-- BRICK_DEPENDENCIES_PLACEHOLDER -->', dependenciesHtml);
+  });
+}

package/src/index.cjs CHANGED Viewed

@@ -10,8 +10,11 @@ module.exports = async function eleventyBricksPlugin(eleventyConfig, options) {
 };
 // Export individual helpers
+module.exports.bricksRegistry = async function(eleventyConfig) {
+  const { bricksRegistry } = await import('./index.js');
+  return bricksRegistry(eleventyConfig);
+};
 module.exports.autoRaw = async function(eleventyConfig) {
   const { autoRaw } = await import('./index.js');
   return autoRaw(eleventyConfig);
 };

package/src/index.js CHANGED Viewed

@@ -1,3 +1,4 @@
+import { bricksRegistry } from "./bricksRegistry.js";
 import { autoRaw } from "./autoRaw.js";
 /**
@@ -8,17 +9,18 @@ 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)
  */
 export default function eleventyBricksPlugin(eleventyConfig, options = {}) {
-  const { autoRaw: enableAutoRaw = false } = options;
-  // Register helpers based on options
-  if (enableAutoRaw) {
+  if (options.bricksRegistry) {
+    bricksRegistry(eleventyConfig);
+  }
+  if (options.autoRaw) {
     autoRaw(eleventyConfig);
   }
 }
 // Export individual helpers for granular usage
+export { bricksRegistry };
 export { autoRaw };