@fractality/nunjucks 2.2.0

package/CHANGELOG.md

@@ -0,0 +1,114 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# 2.2.0 (2024-09-20)
+
+### Bug Fixes
+
+-   **engine:** update to remove deprecated flatten behaviour ([b89be05](https://github.com/frctl/fractal/commit/b89be05f091c9eb61b14c510b91eb3c548b849cd))
+-   fetch request context for README.md ([#13](https://github.com/frctl/fractal/issues/13)) ([dec6fea](https://github.com/frctl/fractal/commit/dec6feae727801f5a61291cd8cd1e167b37bee18))
+
+### Features
+
+-   **partials:** support new handle-based import syntax ([2719df7](https://github.com/frctl/fractal/commit/2719df71a1e385b21a5c8d0cfb5be173e68269ad))
+-   replace bluebird with native promises ([1c8daa0](https://github.com/frctl/fractal/commit/1c8daa09a70962211ce550eff9a930ee3d9a9323))
+
+# 2.1.0 (2024-03-19)
+
+### Bug Fixes
+
+-   **engine:** update to remove deprecated flatten behaviour ([b89be05](https://github.com/frctl/fractal/commit/b89be05f091c9eb61b14c510b91eb3c548b849cd))
+-   fetch request context for README.md ([#13](https://github.com/frctl/fractal/issues/13)) ([dec6fea](https://github.com/frctl/fractal/commit/dec6feae727801f5a61291cd8cd1e167b37bee18))
+
+### Features
+
+-   **partials:** support new handle-based import syntax ([2719df7](https://github.com/frctl/fractal/commit/2719df71a1e385b21a5c8d0cfb5be173e68269ad))
+-   replace bluebird with native promises ([1c8daa0](https://github.com/frctl/fractal/commit/1c8daa09a70962211ce550eff9a930ee3d9a9323))
+
+## [2.0.15](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.14...@frctl/nunjucks@2.0.15) (2022-08-17)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.14](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.13...@frctl/nunjucks@2.0.14) (2022-01-26)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.13](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.12...@frctl/nunjucks@2.0.13) (2021-07-20)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.12](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.11...@frctl/nunjucks@2.0.12) (2021-07-19)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.11](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.10...@frctl/nunjucks@2.0.11) (2021-05-20)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.10](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.9...@frctl/nunjucks@2.0.10) (2021-03-23)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.9](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.8...@frctl/nunjucks@2.0.9) (2021-03-20)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.8](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.7...@frctl/nunjucks@2.0.8) (2021-02-14)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.7](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.6...@frctl/nunjucks@2.0.7) (2021-02-07)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.6](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.5...@frctl/nunjucks@2.0.6) (2020-12-22)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.5](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.4...@frctl/nunjucks@2.0.5) (2020-11-03)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.4](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.3...@frctl/nunjucks@2.0.4) (2020-10-19)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## [2.0.3](https://github.com/frctl/fractal/compare/@frctl/nunjucks@2.0.2...@frctl/nunjucks@2.0.3) (2020-10-15)
+
+**Note:** Version bump only for package @frctl/nunjucks
+
+## 2.0.2
+
+### Bug Fixes
+
+-   fetch request context for component notes file (#13)
+
+### Chores
+
+-   bump lodash from 4.17.11 to 4.17.13 (#14)
+
+## 2.0.1
+
+-   Fix issue with `render`and `view` tag output being escaped
+
+## 2.0
+
+-   Update Nunjucks to v3.x
+-   Prevent array merging in `render` tag context data
+-   Enable autoescaping by default
+-   Add ability to provide environment configuration options
+
+## 1.0.2
+
+-   [FIX] Fix issue with path filter in components rendered using the `render` extension.
+
+## 1.0.1
+
+-   Provide support for future changes to `_` ('special') variables setting
+-   Update Nunjucks 2.3.0 -> 2.4.2
+
+## 1.0.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Mark Perkins <mark@clearleft.com>
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# @fractality/nunjucks
+
+[Nunjucks](http://mozilla.github.io/nunjucks/) template engine adapter for [Fractal](http://github.com/fractality/fractality).
+
+[![NPM Version](https://img.shields.io/npm/v/@fractality/nunjucks)](https://www.npmjs.com/package/@fractality/nunjucks)
+
+## 🚨 Breaking changes in v2.0
+
+-   `render` tag - Arrays in context data are **no longer merged** with those in the default component context
+-   **Autoescaping** - this is now **disabled by default**. Preview templates will need to be updated to mark the `yield` output as safe using the Nunjucks `safe` filter: `{{ yield | safe }}`. Alternatively this can be enabled globally again using the environment options when [configuring the adapter](#customisation) (not recommended).
+-   **Nunjucks version** - bumped to 3.x
+
+## Installation
+
+```bash
+npm i @fractality/nunjucks --save
+```
+
+## Usage
+
+```javascript
+fractal.components.engine('@fractality/nunjucks'); // register the Nunjucks adapter for your components
+fractal.components.set('ext', '.njk'); // look for files with a .njk file extension
+```
+
+## Customisation
+
+If you want to register custom [filters](https://mozilla.github.io/nunjucks/api.html#custom-filters), global variables or [extensions](https://mozilla.github.io/nunjucks/api.html#custom-tags) to the underlying Nunjucks engine then you can configure an instance as follows:
+
+```javascript
+import nunjucksAdapter from '@fractality/nunjucks';
+const nunj = nunjucksAdapter({
+    env: {
+        // Nunjucks environment opts: https://mozilla.github.io/nunjucks/api.html#configure
+    },
+    filters: {
+        // filter-name: function filterFunc(){}
+    },
+    globals: {
+        // global-name: global-val
+    },
+    extensions: {
+        // extension-name: function extensionFunc(){}
+    },
+});
+
+fractal.components.engine(nunj); /* set as the default template engine for components */
+```
+
+For example, to register the 'shorten' filter example from the [Nujucks docs](https://mozilla.github.io/nunjucks/api.html#custom-filters):
+
+```javascript
+import nunjucksAdapter from '@fractality/nunjucks';
+const nunj = nunjucksAdapter({
+    filters: {
+        shorten: function (str, count) {
+            return str.slice(0, count || 5);
+        },
+    },
+});
+```
+
+Which you could then use in your component or documentation views as follows:
+
+```nunjucks
+{# Show the first 5 characters #}
+A message for you: {{ message|shorten }}
+
+{# Show the first 20 characters #}
+A message for you: {{ message|shorten(20) }}
+```
+
+## Including and extending non-component view templates
+
+By default, the Nunjucks adapter expects you to use the Fractality component `@handle` syntax to refer to components to include or extend in your templates.
+
+However, if you wish to include (or extend) non-component templates, you can also specify a path (or an array of paths) of directories for Nunjucks to search in for non-component templates when configuring your Nunjucks instance. For example:
+
+```javascript
+import nunjucksAdapter from '@fractality/nunjucks';
+const nunj = nunjucksAdapter({
+    paths: ['path/to/files'],
+});
+```
+
+```html
+{% include 'foo.html' %}
+```
+
+In this example the file `foo.html` would be searched for in the `path/to/files` directory and included if found.
+
+> Using additional search paths in this manner **does not** prevent standard `@handle` syntax includes working as well.
+
+## Extensions
+
+The following Nunjucks extensions come **automatically pre-installed**. These are often useful when building or documenting Fractal-based component libraries.
+
+If you **do not wish** to include these extensions, set `pristine: true` when configuring your Nunjucks adapter instance.
+
+### render
+
+The `render` extension renders a component (referenced by it's handle) using the context data provided to it in the template. If no data is provided, it will use the context data defined within it's configuration file, if present.
+
+**This can be very useful as an alternative to using an `include` to import sub-components.** `Include`'d components do not pull in their own context so using `render` instead can help prevent repetition of context data in the configuration files of components that include sub-components.
+
+```html
+<!-- pass in data for rendering -->
+{% render '@example', {title: 'An Example'} %} {% render '@example', someData %}
+
+<!-- use the config file data for rendering -->
+{% render '@example' %}
+```
+
+You can also pass in a _partial_ data object (i.e. containing only some of the properties the component expects) and then pass a third argument of `true` to the tag to populate the missing items from the default context data. This allows you to override only the items you need to for this instance of the rendered component.
+
+```html
+<!-- will get any missing properties from the component context data -->
+{% render '@another-example', {title: 'Another Example'}, true %}
+```
+
+### context
+
+Outputs the resolved context data for a component.
+
+```html
+{% context '@example' %}
+
+<!--
+  Outputs:
+  {
+      "foo": "bar",
+      "baz": "bar"
+  }
+-->
+```
+
+### view
+
+Outputs the raw view template contents for the specified component.
+
+```html
+{% view '@example' %}
+
+<!--
+  Outputs:
+  <p>{{ text }}</p>
+-->
+```
+
+## Filters
+
+The following Nunjucks filters come **automatically pre-installed**. As with the extensions, setting `pristine: true` in the Nunjucks adapter instance config will prevent them being added.
+
+### path
+
+Takes a root-relative path and re-writes it if required to make it work in static HTML exports.
+
+**It is strongly recommended to use this filter whenever you need to link to any static assets from your templates.**
+
+```html
+{{ '/css/my-stylesheet.css' | path }}
+```
+
+The path argument should begin with a slash and be relative to the web root. During a static HTML export this path will then be re-written to be relative to the current page.
+
+## Special variables
+
+The Nunjucks adapter also makes a few special variables available to your templates. They all have names prefixed with an underscore to help prevent clashes with any context data variables that are set by the user.
+
+Note that using these may tie your templates a little more tightly into Fractality so you may choose not to use them for that reason.
+
+### \_config
+
+Contains the full Fractality configuration object. Useful for when you want to refer to a configuration item in your documentation (or components).
+
+```html
+{{ _config.project.title }}
+<!-- outputs the project title -->
+{{ _config.components.ext }}
+<!-- outputs the extension used for components -->
+```
+
+### \_self
+
+Contains a simple data object representation of the top-level item (i.e. component or page) being rendered.
+
+```html
+{{ _self.title }}
+<!-- outputs 'Button' -->
+```
+
+### \_target
+
+This variable is only set in component preview layouts, and contains a simple data object representation of the item (i.e. component or page) being rendered _within_ the preview layout.
+
+```html
+{{ _target.title }}
+<!-- outputs 'Button' -->
+```

package/index.js

@@ -0,0 +1,3 @@
+'use strict';
+import NunjucksAdapter from './src/adapter.js';
+export default NunjucksAdapter;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@fractality/nunjucks",
+  "version": "2.2.0",
+  "type": "module",
+  "description": "Nunjucks template adapter for Fractal.",
+  "main": "index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/frctl/fractal.git",
+    "directory": "packages/nunjucks"
+  },
+  "author": "Mark Perkins <mark@clearleft.com> (http://clearleft.com/)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/frctl/fractal/issues"
+  },
+  "homepage": "https://github.com/frctl/fractal/tree/main/packages/nunjucks",
+  "peerDependencies": {
+    "@fractality/fractality": ">= 1.1.0-alpha.0 < 2"
+  },
+  "dependencies": {
+    "@fractality/core": "^0.5.0",
+    "lodash": "^4.17.21",
+    "nunjucks": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "2a5ad3e079ce7a9a418642377a6b6e07bb243c71"
+}

package/src/AsyncNunjucksEnvironment.js

@@ -0,0 +1,33 @@
+import { Environment } from 'nunjucks';
+
+export class AsyncNunjucksEnvironment extends Environment {
+    render(path, context) {
+        return new Promise((resolve, reject) =>
+            super.render(path, context, (err, res) => {
+                if (err) {
+                    reject(err);
+                }
+                resolve(res);
+            }),
+        );
+    }
+
+    renderString(path, context) {
+        return new Promise((resolve, reject) =>
+            super.renderString(path, context, (err, res) => {
+                if (err) {
+                    reject(err);
+                }
+                resolve(res);
+            }),
+        );
+    }
+
+    renderAsync(path, context) {
+        return this.render(path, context);
+    }
+
+    renderStringAsync(path, context) {
+        return this.renderString(path, context);
+    }
+}

package/src/adapter.js

@@ -0,0 +1,143 @@
+'use strict';
+
+import _ from 'lodash';
+import nunjucks from 'nunjucks';
+import path from 'path';
+import fs from 'fs';
+import { Adapter } from '@fractality/core';
+import extensions from './extensions/index.js';
+import filters from './filters/index.js';
+import { AsyncNunjucksEnvironment } from './AsyncNunjucksEnvironment.js';
+
+class NunjucksAdapter extends Adapter {
+    constructor(source, config, app) {
+        super(null, source);
+
+        const loaders = [];
+        const self = this;
+
+        this._app = app;
+
+        /**
+         * Create a custom string loader and instantiate a new Nunjucks environment object with it.
+         * We don't want to use the FileSystemLoader as we already have
+         * the contents of all files cached in the component file tree.
+         */
+
+        const StringLoader = nunjucks.Loader.extend({
+            getSource(handle) {
+                if (handle.indexOf('@') !== 0) {
+                    return;
+                }
+                const view = self.getView(handle);
+                if (view) {
+                    return {
+                        src: view.content,
+                        path: view.content,
+                        noCache: true,
+                    };
+                }
+            },
+        });
+        loaders.push(new StringLoader());
+
+        /**
+         * If the user has specified any paths for directly loading templates,
+         *  include a FileSystemLoader instance.
+         */
+
+        if (config.paths) {
+            const FileSystemLoader = nunjucks.Loader.extend({
+                init(searchPaths) {
+                    this.searchPaths = [].concat(searchPaths);
+                },
+
+                getSource(name) {
+                    let fullpath = null;
+                    const paths = this.searchPaths;
+
+                    for (let i = 0; i < paths.length; i++) {
+                        const basePath = path.resolve(paths[i]);
+                        const p = path.resolve(paths[i], name);
+
+                        if (p.indexOf(basePath) === 0 && fs.existsSync(p)) {
+                            fullpath = p;
+                            break;
+                        }
+                    }
+
+                    if (!fullpath) {
+                        return null;
+                    }
+
+                    return {
+                        src: fs.readFileSync(fullpath, 'utf-8'),
+                        path: fullpath,
+                        noCache: true,
+                    };
+                },
+            });
+            loaders.push(new FileSystemLoader(config.paths));
+        }
+
+        /**
+         * Instantiate the Nunjucks environment instance.
+         */
+        this._engine = new AsyncNunjucksEnvironment(loaders, config.env || {});
+    }
+
+    render(path, str, context, meta) {
+        meta = meta || {};
+        setEnv('_self', meta.self, context);
+        setEnv('_target', meta.target, context);
+        setEnv('_env', meta.env, context);
+        setEnv('_config', this._app.config(), context);
+        return this.engine.renderStringAsync(str, context);
+    }
+}
+
+function setEnv(key, value, context) {
+    if (_.isUndefined(context[key]) && !_.isUndefined(value)) {
+        context[key] = value;
+    }
+}
+
+export default function (config) {
+    config = config || {};
+
+    return {
+        register(source, app) {
+            const adapter = new NunjucksAdapter(source, config, app);
+            const nj = adapter.engine;
+
+            if (!config.pristine) {
+                _.each(filters(app) || {}, function (filter, name) {
+                    addFilter(name, filter);
+                });
+                _.each(extensions(app) || {}, function (ext, name) {
+                    nj.addExtension(name, ext);
+                });
+            }
+
+            _.each(config.filters || {}, function (filter, name) {
+                addFilter(name, filter);
+            });
+            _.each(config.extensions || {}, function (ext, name) {
+                nj.addExtension(name, ext);
+            });
+            _.each(config.globals || {}, function (value, name) {
+                nj.addGlobal(name, value);
+            });
+
+            function addFilter(name, filter) {
+                if (typeof filter === 'function') {
+                    nj.addFilter(name, filter);
+                } else if (typeof filter === 'object') {
+                    nj.addFilter(name, filter.filter, filter.async);
+                }
+            }
+
+            return adapter;
+        },
+    };
+}

package/src/extensions/context.js

@@ -0,0 +1,37 @@
+'use strict';
+
+export default function (fractal) {
+    function ContextExtension() {
+        this.tags = ['context'];
+
+        this.parse = function (parser, nodes) {
+            var tok = parser.nextToken();
+            var args = parser.parseSignature(null, true);
+            parser.advanceAfterBlockEnd(tok.value);
+            return new nodes.CallExtensionAsync(this, 'run', args);
+        };
+
+        this.run = function () {
+            const source = fractal.components;
+            const args = Array.from(arguments);
+            const callback = args.pop();
+            args.shift();
+            const handle = args[0];
+            const entity = source.find(handle);
+            if (!entity) {
+                throw new Error(`Could not render component '${handle}' - component not found.`);
+            }
+            const context = entity.isComponent ? entity.variants().default().context : entity.context;
+            source
+                .resolve(context)
+                .then((ctx) => {
+                    callback(null, JSON.stringify(ctx, null, 4));
+                })
+                .catch((err) => {
+                    callback(err);
+                });
+        };
+    }
+
+    return new ContextExtension();
+}

package/src/extensions/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+import _render from './render.js';
+import _view from './view.js';
+import _context from './context.js';
+
+export default function (fractal) {
+    return {
+        render: _render(fractal),
+        view: _view(fractal),
+        context: _context(fractal),
+    };
+}

package/src/extensions/render.js

@@ -0,0 +1,54 @@
+'use strict';
+
+import nunjucks from 'nunjucks';
+import { utils } from '@fractality/core';
+
+export default function (fractal) {
+    function RenderExtension() {
+        this.tags = ['render'];
+
+        this.parse = function (parser, nodes) {
+            var tok = parser.nextToken();
+            var args = parser.parseSignature(null, true);
+            parser.advanceAfterBlockEnd(tok.value);
+            return new nodes.CallExtensionAsync(this, 'run', args);
+        };
+
+        this.run = function () {
+            const source = fractal.components;
+            const args = Array.from(arguments);
+            const rootContext = args[0].ctx;
+            const callback = args.pop();
+            args.shift();
+            const handle = args[0];
+            let context = args[1];
+            const merge = args[2] || false;
+            const entity = source.find(handle);
+            if (!entity) {
+                throw new Error(`Could not render component '${handle}' - component not found.`);
+            }
+            const defaultContext = entity.isComponent ? entity.variants().default().context : entity.context;
+            if (!context) {
+                context = defaultContext;
+            } else if (merge) {
+                context = utils.defaultsDeep(context, defaultContext);
+            }
+
+            source.resolve(context).then((context) => {
+                // fix env for rendered components
+                let env = JSON.parse(JSON.stringify(rootContext._env));
+                context._env = env;
+                entity
+                    .render(context)
+                    .then((html) => {
+                        callback(null, new nunjucks.runtime.SafeString(html));
+                    })
+                    .catch((err) => {
+                        callback(err);
+                    });
+            });
+        };
+    }
+
+    return new RenderExtension();
+}

package/src/extensions/view.js

@@ -0,0 +1,41 @@
+'use strict';
+
+import nunjucks from 'nunjucks';
+
+export default function (fractal) {
+    function ViewExtension() {
+        this.tags = ['view'];
+
+        this.parse = function (parser, nodes) {
+            var tok = parser.nextToken();
+            var args = parser.parseSignature(null, true);
+            parser.advanceAfterBlockEnd(tok.value);
+            return new nodes.CallExtensionAsync(this, 'run', args);
+        };
+
+        this.run = function () {
+            const source = fractal.components;
+            const args = Array.from(arguments);
+            const callback = args.pop();
+            args.shift();
+            const handle = args[0];
+            let entity = source.find(handle);
+            if (!entity) {
+                throw new Error(`Could not render component '${handle}' - component not found.`);
+            }
+            if (entity.isComponent) {
+                entity = entity.variants().default();
+            }
+            entity
+                .getContent()
+                .then((content) => {
+                    callback(null, new nunjucks.runtime.SafeString(content));
+                })
+                .catch((err) => {
+                    callback(err);
+                });
+        };
+    }
+
+    return new ViewExtension();
+}

package/src/filters/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+import pathFilter from './path.js';
+
+export default function (fractal) {
+    return {
+        path: pathFilter(fractal),
+    };
+}

package/src/filters/path.js

@@ -0,0 +1,15 @@
+'use strict';
+
+import _ from 'lodash';
+import { utils } from '@fractality/core';
+
+export default function (fractal) {
+    return function (path) {
+        let env = this.lookup('_env');
+        let request = env.request || this.lookup('_request') || this.ctx.request;
+
+        return !env || env.server
+            ? path
+            : utils.relUrlPath(path, _.get(request, 'path', '/'), fractal.web.get('builder.urls'));
+    };
+}