Skip to content

Commit

Permalink
feat: support fileExtension as array
Browse files Browse the repository at this point in the history
  • Loading branch information
@cossssmin
cossssmin committed Nov 29, 2024
1 parent bcd80ef commit 5175272
Show file tree
Hide file tree
Showing 6 changed files with 189 additions and 105 deletions.
93 changes: 49 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Init PostHTML:
```js
// index.js
const posthtml = require('posthtml')
const components = require('posthtml-components')
const components = require('posthtml-component')
const { readFileSync, writeFileSync } = require('node:fs')

posthtml([
Expand Down Expand Up @@ -117,47 +117,47 @@ You can clone this repo and run `npm run build` to compile them.

## Options

| Name | Type | Default | Description |
|--------------------------|-------------------|----------------------------------------------|-----------------------------------------------------------------------------------------|
| **root** | `String` | `'./'` | Root path for components lookup. |
| **folders** | `String[]` | `['']` | Array of paths relative to `options.root` or defined namespaces. |
| **tagPrefix** | `String` | `'x-'` | Tag prefix. |
| **tag** | `String\|Boolean` | `false` | Component tag. Use with `options.attribute`. Boolean only `false`. |
| **attribute** | `String` | `'src'` | Component attribute for setting path. |
| **namespaces** | `String[]` | `[]` | Array of namespace root paths, fallback paths, and custom override paths. |
| **namespaceSeparator** | `String` | `'::'` | Namespace separator for tag names. |
| **fileExtension** | `String` | `'html'` | File extension for component files. |
| **yield** | `String` | `'yield'` | Tag name for injecting main component content. |
| **slot** | `String` | `'slot'` | Tag name for slots. |
| **fill** | `String` | `'fill'` | Tag name for filling slots. |
| **slotSeparator** | `String` | `':'` | Name separator for `<slot>` and `<fill>` tags. |
| **push** | `String` | `'push'` | Tag name for `<push>`. |
| **stack** | `String` | `'stack'` | Tag name for `<stack>`. |
| **propsScriptAttribute** | `String` | `'props'` | Attribute in `<script props>` for retrieving component props. |
| **propsContext** | `String` | `'props'` | Name of the object inside the script for processing props. |
| **propsAttribute** | `String` | `'props'` | Attribute to define props as JSON. |
| **propsSlot** | `String` | `'props'` | Used to retrieve props passed to slot via `$slots.slotName.props`. |
| **parserOptions** | `Object` | `{recognizeSelfClosing: true}` | Pass options to `posthtml-parser`. |
| **expressions** | `Object` | `{}` | Pass options to `posthtml-expressions`. |
| **plugins** | `Array` | `[]` | PostHTML plugins to apply to every parsed component. |
| **matcher** | `Object` | `[{tag: options.tagPrefix}]` | Array of objects used to match tags. |
| **attrsParserRules** | `Object` | `{}` | Additional rules for attributes parser plugin. |
| **strict** | `Boolean` | `true` | Toggle exception throwing. |
| **mergeCustomizer** | `Function` | `function` | Callback for lodash `mergeWith` to merge `options.expressions.locals` and props. |
| **utilities** | `Object` | `{merge: _.mergeWith, template: _.template}` | Utility methods passed to `<script props>`. |
| **elementAttributes** | `Object` | `{}` | Object with tag names and function modifiers of `valid-attributes.js`. |
| **safelistAttributes** | `String[]` | `['data-*']` | Array of attribute names to add to default valid attributes. |
| **blocklistAttributes** | `String[]` | `[]` | Array of attribute names to remove from default valid attributes. |
| Name | Type | Default | Description |
|--------------------------|--------------------|----------------------------------------------|----------------------------------------------------------------------------------|
| **root** | `String` | `'./'` | Root path where to look for components. |
| **folders** | `String[]` | `['']` | Array of paths relative to `options.root` or defined namespaces. |
| **fileExtension** | `String\|String[]` | `'html'` | Component file extensions to look for. |
| **tagPrefix** | `String` | `'x-'` | Tag prefix. |
| **tag** | `String\|Boolean` | `false` | Component tag. Use with `options.attribute`. Boolean only `false`. |
| **attribute** | `String` | `'src'` | Attribute to use for defining path to component file. |
| **namespaces** | `String[]` | `[]` | Array of namespace root paths, fallback paths, and custom override paths. |
| **namespaceSeparator** | `String` | `'::'` | Namespace separator for tag names. |
| **yield** | `String` | `'yield'` | Tag name for injecting main component content. |
| **slot** | `String` | `'slot'` | Tag name for [slots](#slots) |
| **fill** | `String` | `'fill'` | Tag name for filling slots. |
| **slotSeparator** | `String` | `':'` | Name separator for `<slot>` and `<fill>` tags. |
| **stack** | `String` | `'stack'` | Tag name for [`<stack>`](#stacks). |
| **push** | `String` | `'push'` | Tag name for `<push>`. |
| **propsScriptAttribute** | `String` | `'props'` | Attribute in `<script props>` for retrieving [component props](#props). |
| **propsContext** | `String` | `'props'` | Name of the object inside the script for processing props. |
| **propsAttribute** | `String` | `'props'` | Attribute name to define props as JSON on a component tag. |
| **propsSlot** | `String` | `'props'` | Used to retrieve props passed to slot via `$slots.slotName.props`. |
| **parserOptions** | `Object` | `{recognizeSelfClosing: true}` | Pass options to `posthtml-parser`. |
| **expressions** | `Object` | `{}` | Pass options to `posthtml-expressions`. |
| **plugins** | `Array` | `[]` | PostHTML plugins to apply to every parsed component. |
| **matcher** | `Object` | `[{tag: options.tagPrefix}]` | Array of objects used to match tags. |
| **attrsParserRules** | `Object` | `{}` | Additional rules for attributes parser plugin. |
| **strict** | `Boolean` | `true` | Toggle exception throwing. |
| **mergeCustomizer** | `Function` | `function` | Callback for lodash `mergeWith` to merge `options.expressions.locals` and props. |
| **utilities** | `Object` | `{merge: _.mergeWith, template: _.template}` | Utility methods passed to `<script props>`. |
| **elementAttributes** | `Object` | `{}` | Object with tag names and function modifiers of `valid-attributes.js`. |
| **safelistAttributes** | `String[]` | `['data-*']` | Array of attribute names to add to default valid attributes. |
| **blocklistAttributes** | `String[]` | `[]` | Array of attribute names to remove from default valid attributes. |

## Features

### Tag names and x-tags

You can use the components in multiple ways, or also a combination of them.

If you to use components as 'includes', you may define a tag and src attribute name.
If you want to use components as 'includes', you can define tag and `src` attribute names.

Using our previous button component example, we can define the tag and attribute names and then use it in this way:
Using our previous button component example, we can define the tag and attribute names and then use it like this:

```hbs
<!-- src/index.html -->
Expand All @@ -174,7 +174,7 @@ Init PostHTML:
// index.js

require('posthtml')(
require('posthtml-components')({
require('posthtml-component')({
root: './src',
tag: 'component',
attribute: 'src'
Expand All @@ -183,16 +183,20 @@ require('posthtml')(
.then(/* ... */)
```

If you need more control over tag matching, you can pass an array of matcher or single object via `options.matcher` like this:
If you need more control over tag matching, you may pass an array of matcher or single object via `options.matcher`:

```js
// index.js
const options = {
root: './src',
matcher: [{tag: 'a-tag'}, {tag: 'another-one'}, {tag: new RegExp(`^app-`, 'i')}]
matcher: [
{tag: 'a-tag'},
{tag: 'another-one'},
{tag: new RegExp(`^app-`, 'i')},
]
};

require('posthtml')(require('posthtml-components')(options))
require('posthtml')(require('posthtml-component')(options))
.process(/* ... */)
.then(/* ... */)
```
Expand All @@ -208,7 +212,7 @@ const options = {
tagPrefix: 'x-'
};

require('posthtml')(require('posthtml-components')(options))
require('posthtml')(require('posthtml-component')(options))
.process(/* ... */)
.then(/* ... */)
```
Expand Down Expand Up @@ -254,20 +258,21 @@ const options = {
parserOptions: { decodeEntities: true }
};

require('posthtml')(require('posthtml-components')(options))
require('posthtml')(require('posthtml-component')(options))
.process('some HTML', options.parserOptions)
.then(/* ... */)
```

Important: as you can see, whatever `parserOptions` you pass to the plugin, must also be passed in the `process` method in your code, otherwise your PostHTML build will use `posthtml-parser` defaults and will override anything you've passed to `posthtml-component`.
> [!IMPORTANT]
> The `parserOptions` that you pass to the plugin must also be passed in the `process` method in your code, otherwise your PostHTML build will use `posthtml-parser` defaults and will override anything you've passed to `posthtml-component`.
#### Self-closing tags

The plugin supports self-closing tags by default, but you need to make sure to enable them in the `process` method in your code too, by passing `recognizeSelfClosing: true` in the options object:

```js
// index.js
require('posthtml')(require('posthtml-components')({root: './src'}))
require('posthtml')(require('posthtml-component')({root: './src'}))
.process('your HTML...', {recognizeSelfClosing: true})
.then(/* ... */)
```
Expand All @@ -287,7 +292,7 @@ const options = {
folders: ['components', 'layouts']
};

require('posthtml')(require('posthtml-components')(options))
require('posthtml')(require('posthtml-component')(options))
.process(/* ... */)
.then(/* ... */)
```
Expand Down Expand Up @@ -826,7 +831,7 @@ If default configurations for valid attributes are not right for you, you may co
const { readFileSync, writeFileSync } = require('fs')

const posthtml = require('posthtml')
const components = require('posthtml-components')
const components = require('posthtml-component')

const options = {
root: './src',
Expand Down
Loading

0 comments on commit 5175272

Please sign in to comment.