posthtml-component 2.1.0-beta.1 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +56 -36
- package/package.json +1 -1
- package/src/index.d.ts +1 -1
package/README.md
CHANGED
|
@@ -31,6 +31,40 @@ If you are familiar with Blade, React, Vue or similar, you will find the syntax
|
|
|
31
31
|
|
|
32
32
|
**See also the first [PostHTML Bootstrap UI](https://github.com/thewebartisan7/posthtml-bootstrap-ui) using this plugin and check also the [starter template here](https://github.com/thewebartisan7/posthtml-bootstrap-ui-starter).**
|
|
33
33
|
|
|
34
|
+
## Options
|
|
35
|
+
|
|
36
|
+
| Name | Type | Default | Description |
|
|
37
|
+
|--------------------------|--------------------|----------------------------------------------|----------------------------------------------------------------------------------|
|
|
38
|
+
| **root** | `String` | `'./'` | Root path where to look for components. |
|
|
39
|
+
| **folders** | `String[]` | `['']` | Array of paths relative to `options.root` or defined namespaces. |
|
|
40
|
+
| **fileExtension** | `String\|String[]` | `'html'` | Component file extensions to look for. |
|
|
41
|
+
| **tagPrefix** | `String` | `'x-'` | Tag prefix. |
|
|
42
|
+
| **tag** | `String\|Boolean` | `false` | Component tag. Use with `options.attribute`. Boolean only `false`. |
|
|
43
|
+
| **attribute** | `String` | `'src'` | Attribute to use for defining path to component file. |
|
|
44
|
+
| **namespaces** | `String[]` | `[]` | Array of namespace root paths, fallback paths, and custom override paths. |
|
|
45
|
+
| **namespaceSeparator** | `String` | `'::'` | Namespace separator for tag names. |
|
|
46
|
+
| **yield** | `String` | `'yield'` | Tag name for injecting main component content. |
|
|
47
|
+
| **slot** | `String` | `'slot'` | Tag name for [slots](#slots) |
|
|
48
|
+
| **fill** | `String` | `'fill'` | Tag name for filling slots. |
|
|
49
|
+
| **slotSeparator** | `String` | `':'` | Name separator for `<slot>` and `<fill>` tags. |
|
|
50
|
+
| **stack** | `String` | `'stack'` | Tag name for [`<stack>`](#stacks). |
|
|
51
|
+
| **push** | `String` | `'push'` | Tag name for `<push>`. |
|
|
52
|
+
| **propsScriptAttribute** | `String` | `'props'` | Attribute in `<script props>` for retrieving [component props](#props). |
|
|
53
|
+
| **propsContext** | `String` | `'props'` | Name of the object inside the script for processing props. |
|
|
54
|
+
| **propsAttribute** | `String` | `'props'` | Attribute name to define props as JSON on a component tag. |
|
|
55
|
+
| **propsSlot** | `String` | `'props'` | Used to retrieve props passed to slot via `$slots.slotName.props`. |
|
|
56
|
+
| **parserOptions** | `Object` | `{recognizeSelfClosing: true}` | Pass options to `posthtml-parser`. |
|
|
57
|
+
| **expressions** | `Object` | `{}` | Pass options to `posthtml-expressions`. |
|
|
58
|
+
| **plugins** | `Array` | `[]` | PostHTML plugins to apply to every parsed component. |
|
|
59
|
+
| **matcher** | `Object` | `[{tag: options.tagPrefix}]` | Array of objects used to match tags. |
|
|
60
|
+
| **attrsParserRules** | `Object` | `{}` | Additional rules for attributes parser plugin. |
|
|
61
|
+
| **strict** | `Boolean` | `true` | Toggle exception throwing. |
|
|
62
|
+
| **mergeCustomizer** | `Function` | `function` | Callback for lodash `mergeWith` to merge `options.expressions.locals` and props. |
|
|
63
|
+
| **utilities** | `Object` | `{merge: _.mergeWith, template: _.template}` | Utility methods passed to `<script props>`. |
|
|
64
|
+
| **elementAttributes** | `Object` | `{}` | Object with tag names and function modifiers of `valid-attributes.js`. |
|
|
65
|
+
| **safelistAttributes** | `String[]` | `['data-*']` | Array of attribute names to add to default valid attributes. |
|
|
66
|
+
| **blocklistAttributes** | `String[]` | `[]` | Array of attribute names to remove from default valid attributes. |
|
|
67
|
+
|
|
34
68
|
## Basic example
|
|
35
69
|
|
|
36
70
|
Create the component:
|
|
@@ -101,54 +135,40 @@ You can also define which attributes are considered to be valid, via the plugin'
|
|
|
101
135
|
|
|
102
136
|
More details on this in [Attributes](#attributes) section.
|
|
103
137
|
|
|
104
|
-
### yield
|
|
138
|
+
### yield
|
|
105
139
|
|
|
106
|
-
The `<yield
|
|
140
|
+
The `<yield>` tag is where content that you pass to a component will be injected.
|
|
107
141
|
|
|
108
142
|
The plugin configures the PostHTML parser to recognize self-closing tags, so you can also just write is as `<yield />`.
|
|
109
143
|
|
|
110
144
|
For brevity, we will use self-closing tags in the examples.
|
|
111
145
|
|
|
146
|
+
### fileExtension
|
|
147
|
+
|
|
148
|
+
By default, the plugin looks for components with the `.html` extension. You can change this by passing an array of extensions to the `fileExtension` option.
|
|
149
|
+
|
|
150
|
+
When using an array, if two files with the same name match both extensions, the file matching the first extension in the array will be used.
|
|
151
|
+
|
|
152
|
+
```js
|
|
153
|
+
const posthtml = require('posthtml')
|
|
154
|
+
const components = require('posthtml-component')
|
|
155
|
+
|
|
156
|
+
posthtml([
|
|
157
|
+
components({
|
|
158
|
+
root: './src', // contains layout.html and layout.md
|
|
159
|
+
fileExtension: ['html', 'md']
|
|
160
|
+
})
|
|
161
|
+
])
|
|
162
|
+
.process(`<x-layout />`)
|
|
163
|
+
.then(result => console.log(result.html)) // layout.html content
|
|
164
|
+
```
|
|
165
|
+
|
|
112
166
|
### More examples
|
|
113
167
|
|
|
114
168
|
See also the `docs-src` folder where you can find more examples.
|
|
115
169
|
|
|
116
170
|
You can clone this repo and run `npm run build` to compile them.
|
|
117
171
|
|
|
118
|
-
## Options
|
|
119
|
-
|
|
120
|
-
| Name | Type | Default | Description |
|
|
121
|
-
|--------------------------|--------------------|----------------------------------------------|----------------------------------------------------------------------------------|
|
|
122
|
-
| **root** | `String` | `'./'` | Root path where to look for components. |
|
|
123
|
-
| **folders** | `String[]` | `['']` | Array of paths relative to `options.root` or defined namespaces. |
|
|
124
|
-
| **fileExtension** | `String\|String[]` | `'html'` | Component file extensions to look for. |
|
|
125
|
-
| **tagPrefix** | `String` | `'x-'` | Tag prefix. |
|
|
126
|
-
| **tag** | `String\|Boolean` | `false` | Component tag. Use with `options.attribute`. Boolean only `false`. |
|
|
127
|
-
| **attribute** | `String` | `'src'` | Attribute to use for defining path to component file. |
|
|
128
|
-
| **namespaces** | `String[]` | `[]` | Array of namespace root paths, fallback paths, and custom override paths. |
|
|
129
|
-
| **namespaceSeparator** | `String` | `'::'` | Namespace separator for tag names. |
|
|
130
|
-
| **yield** | `String` | `'yield'` | Tag name for injecting main component content. |
|
|
131
|
-
| **slot** | `String` | `'slot'` | Tag name for [slots](#slots) |
|
|
132
|
-
| **fill** | `String` | `'fill'` | Tag name for filling slots. |
|
|
133
|
-
| **slotSeparator** | `String` | `':'` | Name separator for `<slot>` and `<fill>` tags. |
|
|
134
|
-
| **stack** | `String` | `'stack'` | Tag name for [`<stack>`](#stacks). |
|
|
135
|
-
| **push** | `String` | `'push'` | Tag name for `<push>`. |
|
|
136
|
-
| **propsScriptAttribute** | `String` | `'props'` | Attribute in `<script props>` for retrieving [component props](#props). |
|
|
137
|
-
| **propsContext** | `String` | `'props'` | Name of the object inside the script for processing props. |
|
|
138
|
-
| **propsAttribute** | `String` | `'props'` | Attribute name to define props as JSON on a component tag. |
|
|
139
|
-
| **propsSlot** | `String` | `'props'` | Used to retrieve props passed to slot via `$slots.slotName.props`. |
|
|
140
|
-
| **parserOptions** | `Object` | `{recognizeSelfClosing: true}` | Pass options to `posthtml-parser`. |
|
|
141
|
-
| **expressions** | `Object` | `{}` | Pass options to `posthtml-expressions`. |
|
|
142
|
-
| **plugins** | `Array` | `[]` | PostHTML plugins to apply to every parsed component. |
|
|
143
|
-
| **matcher** | `Object` | `[{tag: options.tagPrefix}]` | Array of objects used to match tags. |
|
|
144
|
-
| **attrsParserRules** | `Object` | `{}` | Additional rules for attributes parser plugin. |
|
|
145
|
-
| **strict** | `Boolean` | `true` | Toggle exception throwing. |
|
|
146
|
-
| **mergeCustomizer** | `Function` | `function` | Callback for lodash `mergeWith` to merge `options.expressions.locals` and props. |
|
|
147
|
-
| **utilities** | `Object` | `{merge: _.mergeWith, template: _.template}` | Utility methods passed to `<script props>`. |
|
|
148
|
-
| **elementAttributes** | `Object` | `{}` | Object with tag names and function modifiers of `valid-attributes.js`. |
|
|
149
|
-
| **safelistAttributes** | `String[]` | `['data-*']` | Array of attribute names to add to default valid attributes. |
|
|
150
|
-
| **blocklistAttributes** | `String[]` | `[]` | Array of attribute names to remove from default valid attributes. |
|
|
151
|
-
|
|
152
172
|
## Features
|
|
153
173
|
|
|
154
174
|
### Tag names and x-tags
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "posthtml-component",
|
|
3
|
-
"version": "2.1.0
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"description": "Laravel Blade-inspired components for PostHTML with slots, attributes as props, custom tags and more.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": "posthtml/posthtml-components",
|
package/src/index.d.ts
CHANGED