open-index/open-npm huggingface dataset:
npm package: @frctl/app
Description: Fractal application class
Author: Mark Perkins
Latest version: 2.0.0-beta.1

# Fractal App

Base class for a filesystem-parsing application.

[![NPM Version](https://img.shields.io/npm/v/@frctl/support.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/app)

## Installation

```bash
npm i @frctl/app --save
```

## Requirements

Node >= v7.6 is required.
npm package: @frctl/consolidate-adapter
Description: Generic template engine adapter for Fractal, powered by consolidate.js
Author: Clearleft
Latest version: 0.4.2

# Consolidate Adapter

Generic template engine adapter for [Fractal](http://frctl.github.io), powered by [consolidate.js](https://github.com/tj/consolidate.js).

If a specific Fractal template engine adapter for your desired language is available then it is recommended to **use that instead** as it will likely be easier to use and configure than this generic handler.

Currently specific template engine adapters have been implemented for:

* [Handlebars](https://github.com/frctl/handlebars-adapter)
* [Nunjucks](https://github.com/frctl/nunjucks-adapter)
* [Mustache](https://github.com/frctl/mustache-adapter)

> Note: Due to the way that Consolidate handles loading of templates, this engine cannot be used for rendering pages, only components.

## Usage

#### 1. Install the consolidate engine adapter

```shell
npm i @frctl/consolidate-adapter --save
```

#### 2. Install the template language parser

As an example, to use [Swig templates](http://paularmstrong.github.io/swig/), first you need to install Swig:

```shell
npm i swig --save
```

#### 2. Add configuration details

You then need to add the configuration details into your `fractal.js` file:

```js
var fractal = require('@frctl/fractal');

fractal.engine('consolidate', '@frctl/consolidate-adapter', {
    engine: 'swig' // The template language to use
});

fractal.set('components.engine', 'consolidate'); // use the consolidate handler
fractal.set('components.ext', '.swig'); // look for files with a .swig file extension
```

You can see a full list of supported template languages on the [Consolidate documentation](https://github.com/tj/consolidate.js).

## Template Engine Instances

You can customise the [template engine instance](https://github.com/tj/consolidate.js#template-engine-instances) in your `fractal.js` file if you want to add filters, globals, mixins etc before templates are rendered.

For example, to extend the above example to use a customised instance of Swig you could do the following:

```js
const swig    = require('swig');
const fractal = require('@frctl/fractal');

// Add a custom Swig filter
swig.setFilter('join', function (input, char) {
  return input.join(char);
});

fractal.engine('consolidate', '@frctl/consolidate-adapter', {
    engine: 'swig',
    instance: swig // Pass in the custom Swig instance
});
fractal.set('components.engine', 'consolidate');
fractal.set('components.ext', '.swig');
```
npm package: @frctl/consolidate-engine
Description: Generic template engine handler for Fractal, powered by consolidate.js
Author: Clearleft
Latest version: 0.4.0
Deprecated: This package has been renamed. Please use @frctl/consolidate-adapter instead

# Consolidate Engine

Generic template engine handler for [Fractal](http://frctl.github.io), powered by [consolidate.js](https://github.com/tj/consolidate.js).

**This engine is currently very experimental.** If a specific Fractal template engine handler for your desired language is available then it is recommended to **use that instead of this one** as it will likely be easier to use and configure than this generic handler.

Currently specific template engine handlers have been implemented for:

* [Handlebars](https://github.com/frctl/handlebars-engine)
* [Nunjucks](https://github.com/frctl/nunjucks-engine)

> Note: Due to the way that Consolidate handles loading of templates, this engine cannot be used for rendering pages, only components.

## Usage

This engine comes pre-installed with Fractal, so there is no need to install it separately. However **you will need to install whichever template engine you want to use** via NPM.

As an example, to use [Swig templates](http://paularmstrong.github.io/swig/), first install swig:

```bash
npm i swig --save
```

Then add configuration details into your `fractal.js` file:

```js
const fractal = require('@frctl/fractal');

fractal.engine('consolidate', '@frctl/consolidate-engine', {
    engine: 'swig' // The template language to use
});

fractal.set('components.engine', 'consolidate'); // use the consolidate handler
fractal.set('components.ext', '.swig'); // look for files with a .swig file extension
```

You can see a full list of supported template languages on the [Consolidate documentation](https://github.com/tj/consolidate.js).

## Template Engine Instances

You can customise the [template engine instance](https://github.com/tj/consolidate.js#template-engine-instances) in your `fractal.js` file if you want to add filters, globals, mixins etc before templates are rendered.

For example, to extend the above example to use a customised instance of Swig you could do the following:

```js
const swig    = require('swig');
const fractal = require('@frctl/fractal');

// Add a custom Swig filter
swig.setFilter('join', function (input, char) {
  return input.join(char);
});

fractal.engine('consolidate', '@frctl/consolidate-engine', {
    engine: 'swig',
    instance: swig // Pass in the custom Swig instance
});
fractal.set('components.engine', 'consolidate');
fractal.set('components.ext', '.swig');
```
npm package: @frctl/core
Description: Core module of Fractal.
Latest version: 0.3.5

# @frctl/core

The core module of [Fractal](http://github.com/frctl/fractal).

[![NPM Version](https://img.shields.io/npm/v/@frctl/core)](https://www.npmjs.com/package/@frctl/core)

## License

[MIT](https://github.com/frctl/fractal/blob/main/LICENSE)
npm package: @frctl/dayglo
Description: An adapter-based data file loader/parser for NodeJS.
Author: Mark Perkins
Latest version: 1.0.1

# Dayglo

> Adapter-based data file loader/parser for Node.

[![Build Status](https://img.shields.io/travis/frctl/dayglo/master.svg?style=flat-square)](https://travis-ci.org/frctl/dayglo)
[![NPM Version](https://img.shields.io/npm/v/@frctl/dayglo.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/dayglo)

Dayglo provides a simple, promise-based API to load and parse config/data files from the filesystem.

```js
const dayglo = require('@frctl/dayglo');

dayglo('/path/to/data.tml').then(data => console.log(data)); // { foo: "bar" }
```

It comes with a set of loaders for some common config file formats (JSON/JSON5, YAML, TOML, CommonJS-style modules) but it's also very easy to define your own if you have other requirements.

## Install

```
npm install @frctl/dayglo --save
```

> Dayglo requires Node >= v6.0.

## Usage

The default export is a standalone loader function with the default adapters pre-registered for the following file extensions:

* JSON/JSON5 - `.json, .json5`
* YAML - `.yml, .yaml`
* TOML - `.tml, .toml`
* CommonJS-style modules - `.js`

```js
const dayglo = require('@frctl/dayglo');

dayglo('/path/to/data.json').then(data => {
    console.log(data);
});

dayglo('/path/to/data.yml').then(data => {
    console.log(data);
});
```

You can also create a new Loader instance and register your own adapters, if you prefer:

```js
const Loader = require('@frctl/dayglo').Loader;
const yamlAdapter = require('@frctl/dayglo').yaml;

const loader = new Loader();

// use one of the bundled adapters
loader.addAdapter(['.yml', '.yaml'], yamlAdapter);

// use a custom adapter to parse .ini files
// via the `ini` package - https://github.com/npm/ini
loader.addAdapter('.ini', function(contents, filename){
    return require('ini').parse(contents);
});

loader.load('/path/to/data.yml').then(data => {
    console.log(data);
});

loader.load('/path/to/data.ini').then(data => {
    console.log(data);
});
```
npm package: @frctl/eslint-config-frctl
Description: ESLint configuration to be shared across all Fractal Repositories
Latest version: 0.1.3

# eslint-config-frctl

ESLint configuration to be shared across all Fractal repositories.

[![NPM Version](https://img.shields.io/npm/v/@frctl/eslint-config-frctl.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/eslint-config-frctl)

## Overview

This package is an [ESLint shareable config](http://eslint.org/docs/developer-guide/shareable-configs) which can be used in conjunction with an ESLint based plugin such as [xo](https://github.com/sindresorhus/xo), in order to help maintain consistent styles across a codebase.

```
"xo": {
  "extends": "@frctl/eslint-config-frctl"
}
```

## Installation

Installation is via [npm](https://www.npmjs.com/).

`npm i @frctl/eslint-config-frctl`


## Usage
To use with `xo`, first ensure the package has been installed (see above) and then pass the package name to the the [`extends`](https://github.com/sindresorhus/xo#extends) option in `package.json`:

```
{
  "name": "repo-name",
  ...
  },
  "devDependencies": {
    "@frctl/eslint-config-frctl": "0.1.0"
  },
  "xo": {
    "extends": "@frctl/eslint-config-frctl"
  }
}
```

## Requirements
Node: >= 6.0.0
npm package: @frctl/ffs
Description: Fractal filesystem utilities
Latest version: 0.2.1

# ffs

Fractal filesystem utilities.

[![Build Status](https://img.shields.io/travis/frctl/ffs/master.svg?style=flat-square)](https://travis-ci.org/frctl/ffs)
[![NPM Version](https://img.shields.io/npm/v/@frctl/ffs.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/ffs)

## API

### .readDir(src)

Reads a directory (or directories) of files and represents them as [File objects](https://github.com/frctl/file). Returns a Promise.

* `src`: Directory path (or array of paths) to read from [required]

```js
const fs = require('@frctl/fs');

fs.readDir('path/to/files').then(files => {
  console.log(files);
});
```

### .cloneFile(file[, props])

Clone a [File](https://github.com/frctl/file), optionally overwriting it's properties with those from `props`.

* `file`: Instance of `File` that should be cloned [required]
* `props`: Set of properties to overwrite on the cloned file

```js
const fs = require('@frctl/fs');

const file = new fs.File({
  path: '/path/to/file.js',
  contents: Buffer.from('The file contents')
});

const cloned = fs.cloneFile(file, {
  path: '/path/to/foo.js'
});
```

## Installation

```bash
npm i @frctl/ffs --save
```

## Requirements

Node >= v6.0 is required.
npm package: @frctl/file
Description: Fractal file metadata format
Latest version: 0.5.0

# File

File metadata object for use in [Fractal](https://github.com/frctl/fractal)

[![Build Status](https://img.shields.io/travis/frctl/file/master.svg?style=flat-square)](https://travis-ci.org/frctl/file)
[![NPM Version](https://img.shields.io/npm/v/@frctl/file.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/file)

```js
const File = require('@frctl/file');

const file = new File({
  base: '/components',
  path: '/components/patterns/_04-button--large.hbs',
  contents: new Buffer('<button class="button button--large">{{ buttonText }}</button>')
});

console.log(file.stem); // '_04-button--large'
console.log(file.relative); // 'patterns/_04-button--large.hbs

const fromRealFile = File.from('/path/to/file.js', {base: '/path'}).then(file => {
  console.log(file.contents);
});

```

## Install

```
npm i @frctl/file --save
```

## Requirements

`@frctl/file` requires Node >= v6.0
npm package: @frctl/fractal
Description: A tool to help you build and document website component libraries and then integrate them into your projects.
Author: Mark Perkins
Latest version: 1.5.15

<!-- markdownlint-disable MD033 MD041 -->
<p align=center>
  <a href="https://fractal.build/" align=center>
    <img
        src="https://d33wubrfki0l68.cloudfront.net/5d2e88eb1e2b69f3f8b3a3372b6e4b3b4f095130/2159b/hero.png"
        alt=""
        width="110px">
  </a>
  <h1 align="center">Fractal</h1>
</p>

<br />
<div align="center">
  <!-- Github Actions -->
  <a href="https://github.com/frctl/fractal/actions" title="Build status">
    <img src="https://img.shields.io/github/workflow/status/frctl/fractal/test/main" alt="">
  </a>
  <!-- NPM Version -->
  <a href="https://www.npmjs.com/package/@frctl/fractal" title="Current version">
    <img src="https://img.shields.io/npm/v/@frctl/fractal.svg" alt="">
  </a>
  <!-- Discord -->
  <a href="https://discord.gg/vuRz4Yx" title="Chat with us on Discord">
    <img src="https://img.shields.io/badge/discord-join-7289DA" alt="">
  </a>
  <!-- NPM Downloads -->
  <a href="https://www.npmjs.com/package/@frctl/fractal" title="NPM monthly downloads">
    <img src="https://img.shields.io/npm/dm/@frctl/fractal" alt="">
  </a>
  <!-- License -->
  <a href="https://github.com/frctl/fractal/blob/main/LICENSE" title="MIT license">
    <img alt="GitHub" src="https://img.shields.io/github/license/frctl/fractal">
  </a>
</div>

<br />

Fractal is a tool to help you **build** and **document** website component libraries and design systems.

[Read more here](https://github.com/frctl/fractal#readme)

## License

[MIT](https://github.com/frctl/fractal/blob/main/LICENSE)
npm package: @frctl/fractal-extension-blueprint
Description: Component-aware static site builder for Fractal
Latest version: 0.1.0

# fractal-extension-blueprint

Component-aware static site builder for Fractal

[![Build Status](https://img.shields.io/travis/frctl/fractal-extension-blueprint/master.svg?style=flat-square)](https://travis-ci.org/frctl/fractal-extension-blueprint)
[![NPM Version](https://img.shields.io/npm/v/@frctl/fractal-extension-blueprint.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/fractal-extension-blueprint)

## Installation

```bash
npm i @frctl/fractal-extension-blueprint --save
```

## Requirements

Node >= v6.0 is required.
npm package: @frctl/fractal-plugin-files-name
Description: Adds a name property to file objects
Author: Mark Perkins
Latest version: 2.0.0-alpha.7

# @frctl/fractal-plugin-files-name

Adds a name property to files objects.

[![NPM Version](https://img.shields.io/npm/v/@frctl/fractal-plugin-files-name.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/fractal-plugin-files-name)

## Installation

```
npm install @frctl/fractal-plugin-files-name
```

## Usage

### Via config

```js
{
  "plugins": {
    "files": [
      "@frctl/fractal-plugin-files-name"
    ]
  }
}
```

### Via Node API

```js
const fractal = require('@frctl/fractal')();

const plugin = require('@frctl/fractal-plugin-files-name')({
  /* options */
});

fractal.getTransformer('files').addPlugin(plugin);
```
npm package: @frctl/fractal-transform-components
Description: Core component transform for Fractal
Author: Mark Perkins
Latest version: 2.0.0-beta.1

# Fractal component transform

Core component transform for Fractal.

Bundled as part of the Fractal core library so you probably don't need to install this directly.

## Requirements

* Node >= v7.6
* Fractal >= v2.0
npm package: @frctl/handlebars
Description: Use Handlebars templates with Fractal.
Author: Mark Perkins
Latest version: 1.2.15

# @frctl/handlebars

[Handlebars](https://handlebarsjs.com/) template engine adapter for [Fractal](http://github.com/frctl/fractal).

[![NPM Version](https://img.shields.io/npm/v/@frctl/handlebars)](https://www.npmjs.com/package/@frctl/handlebars)

See the Fractal [view templates guide](http://fractal.build/guide/core-concepts/views) for details on customisation and usage.

## License

[MIT](https://github.com/frctl/fractal/blob/main/LICENSE)
npm package: @frctl/handlebars-adapter
Description: Use Handlebars templates with Fractal.
Author: Mark Perkins
Latest version: 0.4.9

# Handlebars Adapter

Use Handlebars templates with Fractal.

This is the default template engine adapter for Fractal and does not need to be installed separately. See the Fractal [template engine documentation](https://github.com/frctl/fractal/blob/master/docs/engines/overview.md) for details on use and customisation.
npm package: @frctl/handlebars-helpers
Description: A collection of Handlebars helpers for Fractal projects.
Author: Mark Perkins
Latest version: 0.3.0

# Fractal Handlebars Helpers

A collection of Handlebars helpers for [Fractal](https://github.com/frctl/fractal) projects.

You must be using the (default) [Handlebars adapter](https://github.com/frctl/handlebars-adapter) for your components and/or pages to make use of these helpers.

## Installation and Usage

### Loading all helpers

If you wish to load *all* helpers into the template engine instance, you can auto-load them via the adapter:

```js
// fractal.js
const fractal = require('@frctl/fractal');

fractal.engine('handlebars', '@frctl/handlebars-adapter', {
    loadHelpers: true
});
```

### Loading individual helpers

If you want to load individual helpers, you will first need to install this library:

```shell
npm i @frctl/handlebars-helpers --save
```

You can then initialise the helpers and pick the the ones you want to use

```js
// fractal.js
const fractal = require('@frctl/fractal');
const helpers = require('@frctl/handlebars-helpers'); // require the helpers

helpers.use(fractal); // initialise the helpers with the fractal instance

fractal.engine('handlebars', '@frctl/handlebars-adapter', {
    helpers: {
        'render': helpers.require('helpers/render') // use the 'render' helper
    }
});
```

## Helpers

### {{ render }}

The `render` helper renders a component (referenced by it's handle) using the context data provided to it. If no data is provided, it will use the context data defined within the component's configuration file, if it has one.

**This can be very useful as an alternative to using the regular partial `{{> @name }}` helper to import sub-components.** Partials do not pull in their own context so using the `render` helper instead can help prevent repetition of context data in the configuration files of components that include sub-components.

```handlebars
<!-- pass in data for rendering -->
{{render '@example' someData}}
{{render '@example--variant' otherData}}

<!-- use the config file data for rendering -->
{{render '@example'}}
{{render '@example--variant'}}
```

You can also pass in a *partial* data object (i.e. containing only some of the properties the component expects) and then set the `merge` property to true 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.

```handlebars
{{render '@example' partialData merge=true}}
```

### {{ context }}

Outputs the resolved context data for a component.

```handlebars
{{context '@example'}}

<!-- Outputs:
{
    "foo": "bar",
    "baz": "bar"
}
-->
```

### {{ view }}

Outputs the raw view template contents for the specified component.

```handlebars
{{view '@example'}}

<!-- Outputs:
<p>{{ text }}</p>
-->
```
npm package: @frctl/internals
Description: Core source/parser/api classes for Fractal.
Latest version: 0.4.2

# Internals

Core parser and api builder classes for Fractal.

[![Build Status](https://img.shields.io/travis/frctl/internals/master.svg?style=flat-square)](https://travis-ci.org/frctl/internals)
[![NPM Version](https://img.shields.io/npm/v/@frctl/internals.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/internals)

## Installation

```
npm i @frctl/internals
```

### Parser

Stateless plugin-based data processor.

```js
const Parser = require('@frctl/internals/parser');

const myParser = new Parser();

myParser.addPlugin((data, done) => {
  //... manipulate objects in data array
  done();
});

myParser.process([/* input data */], function(err, output){
  //... do stuff with output
});
```

## ApiBuilder

Programmatic API builder.

```js
const ApiBuilder = require('@frctl/internals/api');

const api = new ApiBuilder();

api.addMethod('logAllData', function(){
  console.log(this.data);
});

const myApi = api.generate({
  data: { /* data object */ }
});

myApi.logAllData();

```
npm package: @frctl/json-schema
Description: Parser to convert condensed JSON schemas to standard ones.
Latest version: 0.1.0

# JSON Schema

Parser to convert condensed JSON schemas to standard ones.

[![Build Status](https://img.shields.io/travis/frctl/json-schema/master.svg?style=flat-square)](https://travis-ci.org/frctl/json-schema)
[![NPM Version](https://img.shields.io/npm/v/@frctl/json-schema.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/json-schema)

## Overview

This is a parser that generates a fully qualified [JSON Schema](http://json-schema.org/) based on 'condensed' JSON schema input. From [Understanding JSON Schema](https://spacetelescope.github.io/understanding-json-schema/):
> JSON Schema is a powerful tool for validating the structure of JSON data.

### Rationale
[JSON Schema](http://json-schema.org/) is extremely useful for validation purposes; however, in some use cases it may also be more verbose than necessary. This tool was created to allow users of [Fractal](https://github.com/frctl/v2) to add specifications to their components, whilst hiding some of the complexity of the full specification.

```js

const schemaExpander = require('@frctl/json-schema');

const schema = schemaExpander.expand({ title: 'string', modifier: 'string' });

console.log(schema);

/*
Outputs:

{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "modifier": {
      "type": "string"
    }
  }
}

*/
```

## Installation

```bash
npm i @frctl/json-schema --save
```

## API

### .expand(schema)

Returns a fully qualified JSON schema.

* `schema`: A [Condensed JSON schema](/docs/schema.md)


```js
const schema = jsonSchema.parse({ title: 'string', modifier: 'string' });
```

- If a valid condensed schema is provided, a converted, fully qualified schema will be returned.
- If an already fully qualified schema is provided, it will return that.
- If an invalid schema is provided, it will return an empty schema (i.e. all data will validate).


## Resources
* [Condensed JSON Schema specification](/docs/schema.md)
* [JSON Schema Validator](http://www.jsonschemavalidator.net/)
* [Understanding JSON Schema](https://spacetelescope.github.io/understanding-json-schema/)

## Requirements

Node >= v6.0 is required.
npm package: @frctl/list
Description: Simple immutable object collections.
Author: Mark Perkins
Latest version: 2.1.1

# List

List is an array-like object collection class for NodeJS, with flexible find/filter/sortBy/difference methods and more.

[![Build Status](https://img.shields.io/travis/frctl/list/master.svg?style=flat-square)](https://travis-ci.org/frctl/list)
[![NPM Version](https://img.shields.io/npm/v/@frctl/list.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/list)

The `.push()`,`.pop()`,`.shift()`, and `.unshift()` methods all mutate the list itself. All other methods (including sort methods) return a new copy of the list.

```js
const List = require('@frctl/list');

const characters = new List([
    {name: 'mickey', type: 'mouse', disney: true},
    {name: 'jerry', type: 'mouse', disney: false},
    {name: 'mighty', type: 'mouse', disney: false},
    {name: 'pluto', type: 'dog', disney: true},
    {name: 'odie', type: 'dog', disney: false},
]);

const mice = characters.filter('type', 'mouse');

const disneyDogs = characters.filter({
    type: 'dog',
    disney: true,
});

const mickey = characters.find(char => char.name === 'mickey');

const otherDogs = characters.difference(disneyDogs);

```

## Install

```
npm i @frctl/list --save
```

## Usage

Full API docs to come. For now see the tests for further usage info.

## Install

Installation using [Yarn](http://yarnpkg.com) is recommended.

```
yarn add @frctl/list
```

## Requirements

List requires Node >= v6.0
npm package: @frctl/mustache-adapter
Description: Use Mustache templates with Fractal.
Author: Clearleft
Latest version: 0.2.2

# Mustache Adapter

Use Mustache templates with [Fractal](http://frctl.github.io).

## Usage

Install via NPM:

```bash
npm i @frctl/mustache-adapter --save
```

Then add configuration details into your fractal.js file:

```js
const fractal = require('@frctl/fractal');

fractal.engine('mustache', '@frctl/mustache-adapter'); // register the mustache engine adapter

fractal.set('components.engine', 'mustache'); // use the mustache handler
fractal.set('components.ext', '.mustache'); // look for files with a .mustache file extension
```
npm package: @frctl/mustache-engine
Description: Use Mustache templates with Fractal.
Author: Clearleft
Latest version: 0.2.0
Deprecated: This package has been renamed. Please use @frctl/mustache-adapter instead

# Mustache Engine

Use Mustache templates with [Fractal](http://frctl.github.io).

## Usage

Install via NPM:

```bash
npm i @frctl/mustache-engine --save
```

Then add configuration details into your fractal.js file:

```js
const fractal = require('@frctl/fractal');

fractal.engine('mustache', '@frctl/mustache-engine'); // register the mustache engine

fractal.set('components.engine', 'mustache'); // use the mustache handler
fractal.set('components.ext', '.mustache'); // look for files with a .mustache file extension
```
npm package: @frctl/nunjucks-helpers
Description: A collection of Nunjucks helpers for Fractal.
Author: Mark Perkins
Latest version: 0.3.0

# Fractal Nunjucks Helpers

A collection of Nunjucks helpers for [Fractal](https://github.com/frctl/fractal) projects.

Requires use of the [Nunjucks adapter](https://github.com/frctl/nunjucks-adapter) (or similar) to enable Nunjucks templates in Fractal.

## Installation and Usage

### Loading all helpers

If you wish to load *all* helpers into the template engine instance, you can auto-load them via the adapter:

```js
// fractal.js
const fractal = require('@frctl/fractal');

fractal.engine('nunjucks', '@frctl/nunjucks-adapter', {
    loadHelpers: true
});
```

### Loading individual helpers

If you want to load individual helpers, you will first need to install this library:

```shell
npm i @frctl/nunjucks-helpers --save
```

You can then initialise the helpers and pick the the ones you want to use

```js
// fractal.js
const fractal = require('@frctl/fractal');
const helpers = require('@frctl/nunjucks-helpers'); // require the helpers

helpers.use(fractal); // initialise the helpers with the fractal instance

fractal.engine('nunjucks', '@frctl/nunjucks-adapter', {
    extensions: {
        'render': helpers.require('extensions/render') // use the 'render' extension
    }
});
```

## Extensions

### 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.

```handlebars
{% context '@example' %}

<!-- Outputs:
{
    "foo": "bar",
    "baz": "bar"
}
-->
```

### view

Outputs the raw view template contents for the specified component.

```handlebars
{% view '@example' %}

<!-- Outputs:
<p>{{ text }}</p>
-->
```
npm package: @frctl/pages
Description: Static site builder extension for Fractal
Latest version: 2.0.0-alpha.7

# @frctl/pages

Component aware, static site builder extension for Fractal.

[![NPM Version](https://img.shields.io/npm/v/@frctl/pages.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/pages)

## Installation

```
npm install @frctl/pages
```

## Usage

### Via config

```js
{
  "extensions": [
    "@frctl/pages"
  ]
}
```

### Via Node API

```js
const fractal = require('@frctl/fractal')();

const styleguide = require('@frctl/pages')({
  /* options */
});

fractal.addExtension(styleguide);
```
npm package: @frctl/presets
Description: Collection of presets for Fractal
Latest version: 0.2.1

# Fractal presets

Collection of presets for Fractal.

[![Build Status](https://img.shields.io/travis/frctl/presets/master.svg?style=flat-square)](https://travis-ci.org/frctl/presets)
[![NPM Version](https://img.shields.io/npm/v/@frctl/presets.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/presets)

## Installation

```bash
npm i @frctl/presets --save
```

## Requirements

Node >= v6.0 is required.
npm package: @frctl/react-adapter
Description: Use React components with Fractal.
Author: Mark Perkins
Latest version: 0.2.2
Deprecated: This adapter has been deprecated in favor of @frctl/react.

# React Adapter

This adapter has been deprecated. A [new one](https://www.npmjs.com/package/@frctl/react) exists in the Fractal main repository, see [packages/react](https://github.com/frctl/fractal/tree/main/packages/react).
npm package: @frctl/readr
Description: Recursively list all files and directories within a target directory.
Author: Mark Perkins
Latest version: 0.2.1

# readr

Recursively list all files and directories within a target directory.

Similar to [recursive-readdir](https://github.com/jergason/recursive-readdir) but it includes paths of subdirectories in the files list (and it returns a Promise instead of using a callback).

[![Build Status](https://img.shields.io/travis/frctl/readr/master.svg?style=flat-square)](https://travis-ci.org/frctl/readr)
[![NPM Version](https://img.shields.io/npm/v/@frctl/readr.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/readr)

## Install

Installation using [Yarn](http://yarnpkg.com) is recommended.

```
yarn add @frctl/readr
```

## Usage

`readr` returns a `Promise` that is resolved with an array of file/directory paths.

```js
const readr = require('@frctl/readr');

readr('path/to/files').then(files => {
    // do something with the files list.
});
```

You can also provide a filter function to ignore certain files:

```js
const readr = require('@frctl/readr');

const filter = (path, stat) => stat.isFile(); // filter out directories

readr('path/to/files', filter).then(files => {
    console.log(files); // no directories here!
});
```

## Requirements

`@frctl/readr` requires Node >= v6.0
npm package: @frctl/resolve
Description: Data object property value resolver
Author: Mark Perkins
Latest version: 0.1.0

# Object property value resolver

Utility to recursively iterate over an object and use the provided `handler` to asynchronously resolve/convert property values.

Can be used to allow runtime-resolution of properties for values that cannot be determined when the object is created, via functions, 'macro' strings or any other strategy provided by the handler.

A contrived example may look something like:

```js

const data = {
    first: '#0',
    anArray: ['five','eight','#3'],
    nested: {
        value: '#2'
    },
    dynamic: function(items) {
        // Can return promises here if needed!
        return `The best is ${items[2]}`;
    }
};

function handler(value) {

    let choices = ['one','two','three','four'];

    if (typeof value === 'function') {
        return value(choices);
    }

    if (typeof value === 'string') {
         // Strings starting with a '#' character are treated as 'macros'
         // and will be replaced by the value in the choices array
         // at the specified index.
        if (value.startsWith('#')) {
            const index = value.replace('#','');
            return choices[index];
        }
    }

    return value;
}

resolve(data, handler).then(result => {

    console.log(result);

    // Output:
    // {
    //   first: 'one',
    //   anArray: [ 'five', 'eight', 'four' ],
    //   nested: { value: 'three' },
    //   dynamic: 'The best is three'
    // }

});

```

## Install

Installation using [Yarn](http://yarnpkg.com) is recommended.

```
yarn add @frctl/resolve
```

## Requirements

`@frctl/resolve` requires Node >= v6.0
npm package: @frctl/surveyor
Description: Extensible filesystem parser.
Author: Mark Perkins
Latest version: 2.0.0-alpha.7

# @frctl/surveyor

An extensible filesystem parser.

[![Build Status](https://img.shields.io/travis/frctl/@frctl/surveyor/master.svg?style=flat-square)](https://travis-ci.org/frctl/@frctl/surveyor)
[![NPM Version](https://img.shields.io/npm/v/@frctl/surveyor.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/surveyor)

## Installation

```bash
npm i @frctl/surveyor --save
```

## Requirements

Node >= v6.0 is required.
npm package: @frctl/utils
Description: Utilities and helpers for Fractal.
Author: Mark Perkins
Latest version: 0.5.2

# Fractal utilities

Package utilities and helpers for [Fractal](http://github.com/frctl/fractal) development.

[![Build Status](https://img.shields.io/travis/frctl/utils/master.svg?style=flat-square)](https://travis-ci.org/frctl/utils)
[![NPM Version](https://img.shields.io/npm/v/@frctl/utils.svg?style=flat-square)](https://www.npmjs.com/package/@frctl/utils)

## Installation

Installation using [Yarn](http://yarnpkg.com) is recommended:

```
yarn add @frctl/utils
```

## Requirements

`@frctl/utils` requires Node >= v7.0
npm package: @frctl/vash
Description: Use Vash templates with Fractal.
Author: Matt Chapman
Latest version: 1.0.0

# Vash Adapter

Use [Vash](https://www.npmjs.com/package/vash) templates with Fractal.

## Installation

`npm install @frctl/vash`

or

`yarn add @frctl/vash`

## Usage

In your `fractal.config.js` file:

```javascript
const vashAdapter = require('@frctl/vash')();
fractal.components.engine(vashAdapter);
fractal.components.set('ext', '.vash');
```
npm package: @frctl/web
Description: Web module of Fractal.
Latest version: 0.1.12

# @frctl/web

The web module of [Fractal](http://github.com/frctl/fractal).

[![NPM Version](https://img.shields.io/npm/v/@frctl/web)](https://www.npmjs.com/package/@frctl/web)

## License

[MIT](https://github.com/frctl/fractal/blob/main/LICENSE)