Skip to content

Commit e15411d

Browse files
thewebartisan7thewebartisan7
committed
Cleaner find-path.js and more readme about namespace
1 parent b5d9f86 commit e15411d

File tree

9 files changed

+810
-252
lines changed

9 files changed

+810
-252
lines changed

‎examples/dist/docs.html

+332-32
Large diffs are not rendered by default.

‎examples/index.js

+20-13
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ const md = './examples/src/md';
1616
const plugins = [
1717
components({
1818
root: './examples/src',
19-
roots: ['components', 'layouts'],
19+
folders: ['components', 'layouts'],
2020
strict: true,
2121
expressions: {
2222
locals: {
@@ -76,29 +76,36 @@ readdirSync(src).forEach(file => {
7676
});
7777
});
7878

79-
function processCodeTags () {
80-
return function(tree) {
81-
tree.match.call(tree, {tag: 'pre'}, function(node) {
82-
node.content = Array.from(node.content).map(content => {
83-
if (typeof content === 'string') {
84-
content = '';
85-
} else if (content.tag === 'code' && content.attrs?.class?.startsWith('language-')) {
86-
Array.from(content.content).forEach((c, i) => {
87-
content.content[i] = c.trim()
79+
function processCodeTags() {
80+
return function (tree) {
81+
tree.match({tag: 'pre'}, node => {
82+
if (!Array.isArray(node.content)) {
83+
return node;
84+
}
85+
86+
// Clear whitespaces before and after <pre> and <code>
87+
node.content = node.content.map(contentNode => {
88+
if (typeof contentNode === 'string') {
89+
contentNode = '';
90+
} else if (contentNode.tag === 'code' && contentNode.attrs?.class?.startsWith('language-') && Array.isArray(contentNode.content)) {
91+
contentNode.content.forEach((c, i) => {
92+
contentNode.content[i] = c.trim();
8893
});
8994
}
90-
return content;
95+
96+
return contentNode;
9197
});
98+
9299
return node;
93100
});
94101

95-
// tree.match.call(tree, {tag: 'code'}, function(node) {
102+
// tree.match({tag: 'code'}, function(node) {
96103
// if (Array.isArray(node.content)) {
97104
// node.content = hljs.highlight(render(node.content), {language: 'html'}).value
98105
// } else {
99106
// node.content = hljs.highlightAuto(node.content).value
100107
// }
101108
// return node;
102109
// });
103-
}
110+
};
104111
}

‎examples/src/md/introduction.md

+260-29
Large diffs are not rendered by default.

‎readme.md

+83-29
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<p>HTML-friendly syntax component with slots, attributes as locals and more!</p>
99
</div>
1010

11-
## Install
11+
## Installation
1212

1313
```bash
1414
npm i -D posthtml-components
@@ -96,28 +96,27 @@ See also the `examples` folder. You can run `npm run build-examples` to compile
9696

9797
## Options
9898

99-
| Option | Default | Description |
100-
|:----------------------:|:----------------------------:|:------------------------------------------------------------------------------------------------------------|
101-
| **root** | `'./'` | String value as root path for components lookup. |
102-
| **roots** | `['']` | Array of additional multi roots path from `options.root`. |
103-
| **tagPrefix** | `x-` | String for tag prefix. |
104-
| **tag** | `false` | String or boolean value for component tag. Use this with `options.attribute`. Boolean only false. |
105-
| **attribute** | `src` | String value for component attribute for set path. |
106-
| **namespaces** | `[]` | Array of namespace's root path, fallback path and custom path for override. |
107-
| **namespaceSeparator** | `::` | String value for namespace separator to be used with tag name. Example `<x-namespace::button>` |
108-
| **namespaceFallback** | `false` | Boolean value for use fallback path to defined roots in `options.roots`. |
109-
| **fileExtension** | `html` | String value for file extension of the components used for retrieve x-tag file. |
110-
| **yield** | `yield` | String value for `<yield>` tag name. Where main content of component is injected. |
111-
| **slot** | `slot` | String value for `<slot>` tag name. |
112-
| **fill** | `fill` | String value for `<fill>` tag name. |
113-
| **push** | `push` | String value for `<push>` tag name. |
114-
| **stack** | `stack` | String value for `<stack>` tag name. |
115-
| **localsAttr** | `props` | String value used in `<script props>` parsed by the plugin to retrieve locals in the components. |
116-
| **expressions** | `{}` | Object to configure `posthtml-expressions`. You can pre-set locals or customize the delimiters for example. |
117-
| **plugins** | `[]` | PostHTML plugins to apply for every parsed components. |
118-
| **matcher** | `[{tag: options.tagPrefix}]` | Array of object used to match the tags. |
119-
| **attrsParserRules** | `{}` | Additional rules for attributes parser plugin. |
120-
| **strict** | `true` | Boolean value for enable or disable throw an exception. |
99+
| Option | Default | Description |
100+
|:----------------------:|:----------------------------:|:---------------------------------------------------------------------------------------------------------------|
101+
| **root** | `'./'` | String value as root path for components lookup. |
102+
| **folders** | `['']` | Array of additional multi folders path from `options.root` or any defined namespaces root, fallback or custom. |
103+
| **tagPrefix** | `x-` | String for tag prefix. The plugin will use RegExp with this string. |
104+
| **tag** | `false` | String or boolean value for component tag. Use this with `options.attribute`. Boolean only false. |
105+
| **attribute** | `src` | String value for component attribute for set path. |
106+
| **namespaces** | `[]` | Array of namespace's root path, fallback path and custom path for override. |
107+
| **namespaceSeparator** | `::` | String value for namespace separator to be used with tag name. Example `<x-namespace::button>` |
108+
| **fileExtension** | `html` | String value for file extension of the components used for retrieve x-tag file. |
109+
| **yield** | `yield` | String value for `<yield>` tag name. Where main content of component is injected. |
110+
| **slot** | `slot` | String value for `<slot>` tag name. Used with RegExp by appending `:` (example `<slot:slot-name>`). |
111+
| **fill** | `fill` | String value for `<fill>` tag name. Used with RegExp by appending `:` (example `<fill:slot-name>`). |
112+
| **push** | `push` | String value for `<push>` tag name. |
113+
| **stack** | `stack` | String value for `<stack>` tag name. |
114+
| **localsAttr** | `props` | String value used in `<script props>` parsed by the plugin to retrieve locals in the components. |
115+
| **expressions** | `{}` | Object to configure `posthtml-expressions`. You can pre-set locals or customize the delimiters for example. |
116+
| **plugins** | `[]` | PostHTML plugins to apply for every parsed components. |
117+
| **matcher** | `[{tag: options.tagPrefix}]` | Array of object used to match the tags. |
118+
| **attrsParserRules** | `{}` | Additional rules for attributes parser plugin. |
119+
| **strict** | `true` | Boolean value for enable or disable throw an exception. |
121120

122121
## Features
123122

@@ -208,18 +207,17 @@ Please see below example to understand better.
208207
<x-modal>Submit</x-modal>
209208
```
210209

211-
### Multiple roots
210+
### Multiple folders
212211

213-
You have full control where to place your components. Once you set the main root path of your components, you can then set multiple roots.
212+
You have full control where to place your components. Once you set the base root path of your components, you can then set multiple folders.
214213
For example let's suppose your main root is `./src` and then you have several folders where you have your components, for example `./src/components` and `./src/layouts`.
215214
You can setup the plugin like below:
216215

217216
```js
218217
// index.js
219-
220218
const options = {
221219
root: './src',
222-
roots: ['components', 'layouts']
220+
folders: ['components', 'layouts']
223221
};
224222

225223
require('posthtml')(require('posthtml-components')(options))
@@ -229,7 +227,60 @@ require('posthtml')(require('posthtml-components')(options))
229227

230228
### Namespaces
231229

232-
With namespaces you can define a top level root path to your components like shown in below example:
230+
With namespaces you can define a top level root path to your components like shown in below example.
231+
It can be useful for handle custom theme, where you define a specific top level root, with fallback root when component it's not found,
232+
and a custom root for override, something like a child theme.
233+
234+
Thanks to namespace, you can create folders structure like below:
235+
236+
- `src` (base root folder)
237+
- `components` (folder for components like modal, button, etc.)
238+
- `layouts` (folder for layout components like base layout, header, footer, etc.)
239+
- `theme-dark` (namespace folder for theme-dark)
240+
- `components` (folder for components for theme dark)
241+
- `layouts` (folder for layout components for dark theme)
242+
- `theme-light` (namespace folder for theme-light)
243+
- `components` (folder for components for light theme)
244+
- `layouts` (folder for layout components for dark theme)
245+
- `custom` (custom folder for override your namespace themes)
246+
- `theme-dark` (custom folder for override dark theme)
247+
- `components` (folder for override components of theme dark)
248+
- `layouts` (folder for override layout components of dark theme)
249+
- `theme-light` (custom folder for override light theme)
250+
- `components` (folder for override components of theme dark)
251+
- `layouts` (folder for override layout components of dark theme)
252+
253+
And the options would be like:
254+
255+
```js
256+
// index.js
257+
const options = {
258+
// Main root for component without namespace
259+
root: './src',
260+
// Folders is always appended in 'root' or any defined namespace's folders (base, fallback or custom)
261+
folders: ['components', 'layouts'],
262+
namespaces: [{
263+
// Namespace name will be prepend to tag name (example <x-theme-dark::button>)
264+
name: 'theme-dark',
265+
// Base root of the namespace
266+
root: './src/theme-dark',
267+
// Fallback root when a component it's not found in namespace
268+
fallback: './src',
269+
// Custom root for override, the lookup happen first here
270+
custom: './src/custom/theme-dark'
271+
}, {
272+
// Light theme
273+
name: 'theme-light',
274+
root: './src/theme-light',
275+
fallback: './src',
276+
custom: './src/custom/theme-light'
277+
}, {
278+
/* ... */
279+
}]
280+
};
281+
```
282+
283+
Use the component namespace:
233284

234285
``` html
235286
<!-- src/index.html -->
@@ -241,6 +292,8 @@ With namespaces you can define a top level root path to your components like sho
241292
</html>
242293
```
243294

295+
Of course, you can change this folder structure as you prefer according to your project requirements.
296+
244297
### Slots
245298

246299
Your components can inject code in specific slots you define, and then you can fill this content when you use the component.
@@ -734,7 +787,8 @@ via `$slots` which has all the `props` passed via slot, and as well check if slo
734787
## Migration
735788

736789
If you are migrating from `posthtml-extend` and/or `posthtml-modules` then you can continue to keep them until you migrate all of your components.
737-
For continue to use current code without changing it, at the moment it's not yet fully supported, but it maybe come in near future.
790+
For continue to use current code with this plugin without changing it, at the moment it's not yet fully supported, but it maybe comes in near future.
791+
This because the new version has different logic to handle slots and locals, as well the yield content.
738792

739793
## Contributing
740794

‎src/find-path-in-namespaces.js

-75
This file was deleted.

‎src/find-path-in-roots.js

-37
This file was deleted.

0 commit comments

Comments
 (0)