posthtml-component 1.0.0-beta.10 → 1.0.0-beta.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "posthtml-component",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.11",
   "description": "PostHTML Components Blade-like with slots, attributes as props and custom tag",
   "license": "MIT",
   "repository": "thewebartisan7/posthtml-components",
@@ -13,7 +13,7 @@
     "version": "conventional-changelog -i changelog.md -s -r 0 && git add changelog.md",
     "test": "c8 ava",
     "pretest": "clinton && xo",
-    "build-examples": "node ./examples"
+    "build": "node ./docs-src"
   },
   "keywords": [
     "posthtml",

package/readme.md

@@ -17,7 +17,7 @@ npm i -D posthtml-component
 ## Introduction
 
 This PostHTML plugin provides an HTML-friendly syntax for write components in your templates.
-If you are familiar with Blade, you will find similar syntax as this plugin was inspired by it.
+If you are familiar with Blade, you will find similar syntax as this plugin is inspired by it.
 See below a basic example, as code is worth a thousand words.
 
 > This plugin is still in early stage of development and the current API may change.
@@ -69,13 +69,11 @@ Result:
 </html>
 ```
 
-You may ask yourself many questions about this basic examples, and you will find most if not all answers in this readme. In case is missing something, feel free to ask via discussions.
+You may notice that our `src/button.html` component has a `type` and `class` attribute, and when we use the component in `src/index.html` we add type and class attribute. 
+The result is that `type` is override, and `class` is merged. 
 
-But I want to explain a few things now.
-
-First you may notice that our `src/button.html` component has a `type` and `class` attribute, and when we use the component in `src/index.html` we add type and class attribute. The result is that `type` is override, and `class` is merged. 
-
-By default `class` and `style` attributes are merged, while all others attribute are override. You can also override class and style attribute by prepending `override:` to the class attribute. Example:
+By default `class` and `style` attributes are merged, while all others attribute are override. 
+You can also override class and style attribute by prepending `override:` to the class attribute. Example:
 
 ```html
 <x-button override:class="btn-custom">Submit</x-button>
@@ -84,41 +82,43 @@ By default `class` and `style` attributes are merged, while all others attribute
 <button type="button" class="btn-custom">Submit</button>
 ```
 
-All attributes you pass to the component will be added to the first root element of your component, and only if they are not defined as `props` via `<script props>`. More details on this later.
-
-Second you may notice a `<yield>` tag.
-
-This is where your content will be injected.
+All attributes you pass to the component will be added to the first node of your component or to the node with an attribute names `attributes`, 
+and only if they are not defined as `props` via `<script props>`. More details on this in [Attributes](#attributes) section.
 
-In next section you can find all available options and then more examples.
+The `<yield>` tag is where your content will be injected.
+In next section you can find all available options and then examples for each features.
 
-See also the `examples` folder. You can run `npm run build-examples` to compile them.
+See also the `docs-src` folder where you can find more examples. You can run `npm run build` to compile them.
 
 ## Options
 
-|         Option         |           Default            | Description                                                                                                                     |
-|:----------------------:|:----------------------------:|:--------------------------------------------------------------------------------------------------------------------------------|
-|        **root**        |            `'./'`            | String value as root path for components lookup.                                                                                |
-|      **folders**       |            `['']`            | Array of additional multi folders path from `options.root` or any defined namespaces root, fallback or custom.                  |
-|     **tagPrefix**      |             `x-`             | String for tag prefix. The plugin will use RegExp with this string.                                                             |
-|        **tag**         |           `false`            | String or boolean value for component tag. Use this with `options.attribute`. Boolean only false.                               |
-|     **attribute**      |            `src`             | String value for component attribute for set path.                                                                              |
-|     **namespaces**     |             `[]`             | Array of namespace's root path, fallback path and custom path for override.                                                     |
-| **namespaceSeparator** |             `::`             | String value for namespace separator to be used with tag name. Example `<x-namespace::button>`                                  |
-|   **fileExtension**    |            `html`            | String value for file extension of the components used for retrieve x-tag file.                                                 |
-|       **yield**        |           `yield`            | String value for `<yield>` tag name. Where main content of component is injected.                                               |
-|        **slot**        |            `slot`            | String value for `<slot>` tag name. Used with RegExp by appending `:` (example `<slot:slot-name>`).                             |
-|        **fill**        |            `fill`            | String value for `<fill>` tag name. Used with RegExp by appending `:` (example `<fill:slot-name>`).                             |
-|   **slotSeparator**    |             `:`              | String value used for separate `<slot>` and `<fill>` tag from their names.                                                      |
-|        **push**        |            `push`            | String value for `<push>` tag name.                                                                                             |
-|       **stack**        |           `stack`            | String value for `<stack>` tag name.                                                                                            |
-|     **localsAttr**     |           `props`            | String value used in `<script props>` parsed by the plugin to retrieve locals in the components.                                |
-|    **expressions**     |             `{}`             | Object to configure `posthtml-expressions`. You can pre-set locals or customize the delimiters for example.                     |
-|      **plugins**       |             `[]`             | PostHTML plugins to apply for every parsed components.                                                                          |
-|      **matcher**       | `[{tag: options.tagPrefix}]` | Array of object used to match the tags.                                                                                         |
-|  **attrsParserRules**  |             `{}`             | Additional rules for attributes parser plugin.                                                                                  |
-|       **strict**       |            `true`            | Boolean value for enable or disable throw an exception.                                                                         |
-|  **mergeCustomizer**   |          `function`          | Function callback passed to lodash `mergeWith` for merge `options.expressions.locals` and locals passed via attribute `locals`. |
+|          Option          |                   Default                    | Description                                                                                                                   |
+|:------------------------:|:--------------------------------------------:|:------------------------------------------------------------------------------------------------------------------------------|
+|         **root**         |                    `'./'`                    | String value as root path for components lookup.                                                                              |
+|       **folders**        |                    `['']`                    | Array of additional multi folders path from `options.root` or any defined namespaces root, fallback or custom.                |
+|      **tagPrefix**       |                     `x-`                     | String for tag prefix. The plugin will use RegExp with this string.                                                           |
+|         **tag**          |                   `false`                    | String or boolean value for component tag. Use this with `options.attribute`. Boolean only false.                             |
+|      **attribute**       |                    `src`                     | String value for component attribute for set path.                                                                            |
+|      **namespaces**      |                     `[]`                     | Array of namespace's root path, fallback path and custom path for override.                                                   |
+|  **namespaceSeparator**  |                     `::`                     | String value for namespace separator to be used with tag name. Example `<x-namespace::button>`                                |
+|    **fileExtension**     |                    `html`                    | String value for file extension of the components used for retrieve x-tag file.                                               |
+|        **yield**         |                   `yield`                    | String value for `<yield>` tag name. Where main content of component is injected.                                             |
+|         **slot**         |                    `slot`                    | String value for `<slot>` tag name. Used with RegExp by appending `:` (example `<slot:slot-name>`).                           |
+|         **fill**         |                    `fill`                    | String value for `<fill>` tag name. Used with RegExp by appending `:` (example `<fill:slot-name>`).                           |
+|    **slotSeparator**     |                     `:`                      | String value used for separate `<slot>` and `<fill>` tag from their names.                                                    |
+|         **push**         |                    `push`                    | String value for `<push>` tag name.                                                                                           |
+|        **stack**         |                   `stack`                    | String value for `<stack>` tag name.                                                                                          |
+| **propsScriptAttribute** |                   `props`                    | String value used as attribute in `<script props>` parsed by the plugin to retrieve props of the component.                   |
+|     **propsContext**     |                   `props`                    | String value used as object name inside the script to process process before passed to the component.                         |
+|    **propsAttribute**    |                   `props`                    | String value for props attribute to define props as JSON.                                                                     |
+|      **propsSlot**       |                   `props`                    | String value used to retrieve the props passed to slot via `$slots.slotName.props`.                                           |
+|     **expressions**      |                     `{}`                     | Object to configure `posthtml-expressions`. You can pre-set locals or customize the delimiters for example.                   |
+|       **plugins**        |                     `[]`                     | PostHTML plugins to apply for every parsed components.                                                                        |
+|       **matcher**        |         `[{tag: options.tagPrefix}]`         | Array of object used to match the tags.                                                                                       |
+|   **attrsParserRules**   |                     `{}`                     | Additional rules for attributes parser plugin.                                                                                |
+|        **strict**        |                    `true`                    | Boolean value for enable or disable throw an exception.                                                                       |
+|   **mergeCustomizer**    |                  `function`                  | Function callback passed to lodash `mergeWith` for merge `options.expressions.locals` and props passed via attribute `props`. |
+|      **utilities**       | `{merge: _.mergeWith, template: _.template}` | Object of utilities methods to be passed to `<script props>`. By default lodash `mergeWith` and `template`.                   |
 
 ## Features
 
@@ -515,7 +515,7 @@ Create the component:
 <!-- src/my-component.html -->
 <script props>
   module.exports = {
-    prop: locals.prop || 'Default prop value'
+    prop: props.prop || 'Default prop value'
   }
 </script>
 <div>
@@ -556,7 +556,7 @@ The output will be:
 If you don't add the props in `<script props>` inside your component, all props will be added as attributes to the first node of your component or to the node with attribute `attributes`. 
 More details on this in the next section.
 
-So in the `<script props>` you have access to passed props via object `locals`, and you can add any logic you need inside of it.
+So in the `<script props>` you have access to passed props via object `props`, and you can add any logic you need inside it.
 
 Create the component:
 
@@ -564,9 +564,9 @@ Create the component:
 <!-- src/modal.html -->
 <script props>
   module.exports = {
-    title: locals.title || 'Default title', 
-    size: locals.size ? `modal-${locals.size}` : '', 
-    items: Array.isArray(locals.items) ? locals.items.concat(['first', 'second']) : ['first', 'second']
+    title: props.title || 'Default title', 
+    size: props.size ? `modal-${props.size}` : '', 
+    items: Array.isArray(props.items) ? props.items.concat(['first', 'second']) : ['first', 'second']
   }
 </script>
 <div class="modal {{ size }}">
@@ -603,7 +603,7 @@ The output will be:
 
 You can also notice how the `class` attribute is merged with `class` attribute of the first node. Let's see in next section more about this.
 
-You can change how attributes are merged with global locals defined via options by passing a callback function used by lodash method [mergeWith](https://lodash.com/docs/4.17.15#mergeWith).
+You can change how attributes are merged with global props defined via options by passing a callback function used by lodash method [mergeWith](https://lodash.com/docs/4.17.15#mergeWith).
 
 By default, all props are scoped to the component, and are not available to nested components. You can however change this accordingly to your need.
 Let's see below example.
@@ -614,7 +614,7 @@ Create a component:
 <!-- src/child.html -->
 <script props>
   module.exports = {
-    prop: locals.prop || 'Default prop value'
+    prop: props.prop || 'Default prop value'
   }
 </script>
 <div>
@@ -629,7 +629,7 @@ Create another component that use the first one:
 <!-- src/parent.html -->
 <script props>
   module.exports = {
-    prop: locals.prop || 'Default prop value'
+    prop: props.prop || 'Default prop value'
   }
 </script>
 <div>
@@ -686,7 +686,7 @@ As already seen in basic example:
 <!-- src/button.html -->
 <script props>
   module.exports = {
-    label: locals.label || 'A button'
+    label: props.label || 'A button'
   }
 </script>
 <button type="button" class="btn">
@@ -760,7 +760,7 @@ You can add custom rules how attributes are parsed, as behind the scene it's use
 ## Examples
 
 You can work with `<slot>` and `<fill>` or you can create component for each "block" of your component, and you can also support both of them.
-You can find an example of this inside `examples/components/modal`. Below is a short explanation about the both approach.
+You can find an example of this inside `docs-src/components/modal`. Below is a short explanation about the both approach.
 
 ### Using slots
 
@@ -919,7 +919,7 @@ You can also combine both way, and then use them with slots or with small compon
           </x-modal.body>
       </if>
       <if condition="$slots.footer?.filled">
-          <x-modal.footer close="{{ $slots.footer?.locals.close }}">
+          <x-modal.footer close="{{ $slots.footer?.props.close }}">
               <slot:footer></slot:footer>
           </x-modal.footer>
       </if>

package/src/index.js

@@ -6,10 +6,12 @@ const {parser} = require('posthtml-parser');
 const {match} = require('posthtml/lib/api');
 const expressions = require('posthtml-expressions');
 const findPathFromTag = require('./find-path');
-const processLocals = require('./locals');
-const processAttributes = require('./attributes');
-const {processPushes, processStacks} = require('./stacks');
-const {setFilledSlots, processSlotContent, processFillContent} = require('./slots');
+const processProps = require('./process-props');
+const processAttributes = require('./process-attributes');
+const {processPushes, processStacks} = require('./process-stacks');
+const {setFilledSlots, processSlotContent, processFillContent} = require('./process-slots');
+const mergeWith = require('lodash/mergeWith');
+const template = require('lodash/template');
 
 // const {inspect} = require('util');
 // const debug = true;
@@ -35,14 +37,18 @@ module.exports = (options = {}) => tree => {
   options.slotSeparator = options.slotSeparator || ':';
   options.push = options.push || 'push';
   options.stack = options.stack || 'stack';
-  options.localsAttr = options.localsAttr || 'props';
+  options.propsScriptAttribute = options.propsScriptAttribute || 'props';
+  options.propsContext = options.propsContext || 'props';
+  options.propsAttribute = options.propsAttribute || 'props';
+  options.propsSlot = options.propsSlot || 'props';
   options.expressions = options.expressions || {};
   options.plugins = options.plugins || [];
   options.attrsParserRules = options.attrsParserRules || {};
   options.strict = typeof options.strict === 'undefined' ? true : options.strict;
+  options.utilities = options.utilities || {merge: mergeWith, template};
 
   // Merge customizer callback passed to lodash mergeWith
-  //  for merge attribute `locals` and all attributes starting with `merge:`
+  //  for merge attribute `props` and all attributes starting with `merge:`
   //  @see https://lodash.com/docs/4.17.15#mergeWith
   options.mergeCustomizer = options.mergeCustomizer || ((objectValue, sourceValue) => {
     if (Array.isArray(objectValue)) {
@@ -86,7 +92,7 @@ module.exports = (options = {}) => tree => {
     }
   });
 
-  options.locals = {...options.expressions.locals};
+  options.props = {...options.expressions.locals};
   options.aware = {};
 
   const pushedContent = {};
@@ -140,10 +146,10 @@ function processTree(options) {
       setFilledSlots(currentNode, filledSlots, options);
       // setFilledSlots(nextNode, filledSlots, options);
 
-      // Reset previous locals with passed global and keep aware locals
-      options.expressions.locals = {...options.locals, ...options.aware};
+      // Reset options.expressions.locals and keep aware locals
+      options.expressions.locals = {...options.props, ...options.aware};
 
-      const {attributes, locals} = processLocals(currentNode, nextNode, filledSlots, options);
+      const {attributes, props} = processProps(currentNode, nextNode, filledSlots, options, componentPath);
 
       options.expressions.locals = attributes;
       options.expressions.locals.$slots = filledSlots;
@@ -172,11 +178,11 @@ function processTree(options) {
       currentNode.tag = false;
       currentNode.content = content;
 
-      processAttributes(currentNode, attributes, locals, options);
+      processAttributes(currentNode, attributes, props, options);
 
       // log(currentNode, 'currentNode', 'currentNode')
       // currentNode.attrs.counter = processCounter;
-      // currentNode.attrs.data = JSON.stringify({ attributes, locals });
+      // currentNode.attrs.data = JSON.stringify({ attributes, props });
 
       // messages.push({
       //   type: 'dependency',

package/src/{attributes.js → process-attributes.js}

@@ -11,15 +11,15 @@ const has = require('lodash/has');
 const extend = require('lodash/extend');
 
 /**
- * Map component attributes that it's not defined as locals to first element of node
+ * Map component attributes that it's not defined as props to first element of node
  *
  * @param {Object} currentNode
  * @param {Object} attributes
- * @param {Object} locals
+ * @param {Object} props
  * @param {Object} options
  * @return {void}
  */
-module.exports = (currentNode, attributes, locals, options) => {
+module.exports = (currentNode, attributes, props, options) => {
   let mainNode;
   match.call(currentNode, {attrs: {attributes: ''}}, node => {
     delete node.attrs.attributes;
@@ -40,7 +40,7 @@ module.exports = (currentNode, attributes, locals, options) => {
 
   const nodeAttrs = parseAttrs(mainNode.attrs, options.attrsParserRules);
 
-  const mainNodeAttributes = omit(attributes, union(keys(locals), [options.attribute], keys(options.aware), keys(options.locals), ['$slots']));
+  const mainNodeAttributes = omit(attributes, union(keys(props), [options.attribute], keys(options.aware), keys(options.props), ['$slots']));
 
   each(mainNodeAttributes, (value, key) => {
     if (['class', 'style'].includes(key)) {

package/src/{locals.js → process-props.js}

@@ -1,6 +1,6 @@
 'use strict';
 
-const scriptDataLocals = require('posthtml-expressions/lib/locals');
+const processScript = require('./process-script');
 const pick = require('lodash/pick');
 const each = require('lodash/each');
 const assign = require('lodash/assign');
@@ -9,15 +9,16 @@ const mergeWith = require('lodash/mergeWith');
 const attributeTypes = ['aware', 'merge'];
 
 /**
- * Parse locals from attributes, globals and via script
+ * Parse props from attributes, globals and via script
  *
  * @param {Object} currentNode - PostHTML tree
  * @param {Array} nextNode - PostHTML tree
- * @param {Object} filledSlots - Slot locals
+ * @param {Object} filledSlots - Filled slots
  * @param {Object} options - Plugin options
- * @return {Object} - Attribute locals and script locals
+ * @param {string} componentPath - Component path
+ * @return {Object} - Attribute props and script props
  */
-module.exports = (currentNode, nextNode, filledSlots, options) => {
+module.exports = (currentNode, nextNode, filledSlots, options, componentPath) => {
   let attributes = {...currentNode.attrs};
 
   const attributesByTypeName = {};
@@ -47,26 +48,26 @@ module.exports = (currentNode, nextNode, filledSlots, options) => {
     } catch {}
   });
 
-  // Merge or extend attribute locals
-  if (attributes.locals) {
-    if (attributesByTypeName.merge.includes('locals')) {
-      attributesByTypeName.merge.splice(attributesByTypeName.merge.indexOf('locals'), 1);
-      mergeWith(attributes, attributes.locals, options.mergeCustomizer);
+  // Merge or extend attribute props
+  if (attributes[options.propsAttribute]) {
+    if (attributesByTypeName.merge.includes(options.propsAttribute)) {
+      attributesByTypeName.merge.splice(attributesByTypeName.merge.indexOf(options.propsAttribute), 1);
+      mergeWith(attributes, attributes[options.propsAttribute], options.mergeCustomizer);
     } else {
-      assign(attributes, attributes.locals);
+      assign(attributes, attributes[options.propsAttribute]);
     }
 
-    delete attributes.locals;
+    delete attributes[options.propsAttribute];
   }
 
   // Merge with global
   attributes = mergeWith({}, options.expressions.locals, attributes, options.mergeCustomizer);
 
-  // Retrieve default locals from <script props> for merge with attributes
-  const {locals} = scriptDataLocals(nextNode, {localsAttr: options.localsAttr, removeScriptLocals: true, locals: {...attributes, $slots: filledSlots}});
+  // Process props from <script props>
+  const {props} = processScript(nextNode, {props: {...attributes}, $slots: filledSlots, propsScriptAttribute: options.propsScriptAttribute, propsContext: options.propsContext, utilities: options.utilities}, componentPath.replace(`.${options.fileExtension}`, '.js'));
 
-  if (locals) {
-    assign(attributes, locals);
+  if (props) {
+    assign(attributes, props);
     // if (attributesByTypeName.merge.length > 0) {
     //   assign(attributes, mergeWith(pick(locals, attributesByTypeName.merge), pick(attributes, attributesByTypeName.merge), options.mergeCustomizer));
     // }
@@ -77,5 +78,5 @@ module.exports = (currentNode, nextNode, filledSlots, options) => {
     options.aware = pick(attributes, attributesByTypeName.aware);
   }
 
-  return {attributes, locals};
+  return {attributes, props};
 };

package/src/process-script.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const vm = require('vm');
+const {existsSync, readFileSync} = require('fs');
+const {render} = require('posthtml-render');
+const {match} = require('posthtml/lib/api');
+
+const ctx = vm.createContext({module, require});
+
+/**
+ * Get the script tag with props from a node list and return process props.
+ * Custom posthtml-expressions/lib/locals.
+ *
+ * @param {Array} tree Nodes
+ * @param {Object} options Options
+ * @param {string} scriptPath - Component path
+ * @return {Object} {} Locals
+ */
+module.exports = (tree, options, scriptPath) => {
+  const props = {};
+  const propsContext = options.props;
+  const utilities = {...options.utilities};
+  const context = {...utilities, ...ctx, [options.propsContext]: propsContext, $slots: options.$slots};
+
+  const runInContext = code => {
+    try {
+      const parsedContext = vm.createContext(context);
+      const parsedProps = vm.runInContext(code, parsedContext);
+
+      Object.assign(props, parsedProps);
+    } catch {}
+  };
+
+  if (existsSync(scriptPath)) {
+    runInContext(readFileSync(scriptPath, 'utf8'));
+  }
+
+  match.call(tree, {tag: 'script', attrs: {[options.propsScriptAttribute]: ''}}, node => {
+    if (node.content) {
+      runInContext(render(node.content));
+    }
+
+    return '';
+  });
+
+  return {
+    props
+  };
+};

package/src/{slots.js → process-slots.js}

@@ -14,7 +14,7 @@ const omit = require('lodash/omit');
  * @param  {String} slotSeparator Slot separator
  * @return {void}
  */
-function setFilledSlots(currentNode, filledSlots, {fill, slotSeparator}) {
+function setFilledSlots(currentNode, filledSlots, {fill, slotSeparator, propsSlot}) {
   match.call(currentNode, {tag: fill}, fillNode => {
     if (!fillNode.attrs) {
       fillNode.attrs = {};
@@ -22,10 +22,10 @@ function setFilledSlots(currentNode, filledSlots, {fill, slotSeparator}) {
 
     const name = fillNode.tag.split(slotSeparator)[1];
 
-    const locals = omit(fillNode.attrs, ['append', 'prepend', 'aware']);
+    const props = omit(fillNode.attrs, ['append', 'prepend', 'aware']);
 
-    if (locals) {
-      each(locals, (value, key, attrs) => {
+    if (props) {
+      each(props, (value, key, attrs) => {
         try {
           attrs[key] = JSON.parse(value);
         } catch {}
@@ -39,7 +39,7 @@ function setFilledSlots(currentNode, filledSlots, {fill, slotSeparator}) {
       attrs: fillNode.attrs,
       content: fillNode.content,
       source: render(fillNode.content),
-      locals
+      [propsSlot]: props
     };
 
     return fillNode;