From 52a087f1db4a0c612ffd48707fd07da6937c287b Mon Sep 17 00:00:00 2001 From: Cosmin Popovici Date: Thu, 25 Jul 2024 16:38:30 +0300 Subject: [PATCH] chore: rename files --- changelog.md => CHANGELOG.md | 0 license => LICENSE | 0 readme.md => README.md | 2086 +++++++++++++++++----------------- 3 files changed, 1043 insertions(+), 1043 deletions(-) rename changelog.md => CHANGELOG.md (100%) rename license => LICENSE (100%) rename readme.md => README.md (96%) diff --git a/changelog.md b/CHANGELOG.md similarity index 100% rename from changelog.md rename to CHANGELOG.md diff --git a/license b/LICENSE similarity index 100% rename from license rename to LICENSE diff --git a/readme.md b/README.md similarity index 96% rename from readme.md rename to README.md index 4d66b3d..10eb7a6 100644 --- a/readme.md +++ b/README.md @@ -1,1043 +1,1043 @@ -[![NPM][npm]][npm-url] -[![Coverage][cover]][cover-badge] -[![XO code style][style]][style-url] - -
- -

PostHTML Components

-

A PostHTML plugin for create components with HTML-friendly syntax inspired by Laravel Blade. Slots, stack/push, props, custom tag and much more.

-
- -## Installation - -```bash -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, React, Vue or similar, you will find familiar syntax as this plugin is inspired by them. -See below a basic example, as code is worth a thousand words. - -**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).** - -## Basic example - -Create the component: - -``` html - - -``` - -Use the component: - -``` html - - - - Submit - - -``` - -Init PostHTML: - -```js -// index.js -const { readFileSync, writeFileSync } = require('fs') - -const posthtml = require('posthtml') -const components = require('posthtml-components') - -posthtml(components({ root: './src' })) - .process(readFileSync('src/index.html', 'utf8')) - .then((result) => writeFileSync('dist/index.html', result.html, 'utf8')) -``` - -Result: - -``` html - - - - - - -``` - -You may notice that the `src/button.html` component has a `type` and `class` attribute, and when we use the component in `src/index.html` we pass `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` attributes by prepending `override:` to the class attribute. Example: - -```html -Submit - - - -``` - -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 ` - -``` - -The output will be: - -```html - - - - - - -
-
- Header content -
-
- Body content -
-
- Footer content -
-
- - - -``` - -The `once` attribute allows you to push content only once per rendering cycle. For example, if you are rendering a given component within a loop, you may wish to only push the JavaScript and CSS the first time the component is rendered. - -Example. - -```html - -
- -
- - - - - - - - - - -``` - -By default, the content is pushed in the stack in the given order. -If you would like to prepend content onto the beginning of a stack, you should use the `prepend` attribute: - -```html - - - - - - - - - - - -``` - -### Props - -Behind the `props` there is powerful [posthtml-expressions](https://github.com/posthtml/posthtml-expressions) plugin, with feature to pass `props` (locals) via attributes and manipulate them via ` -
- {{ prop }} -
-``` - -Use: - -```html - -``` - -The output will be: - -```html -
- Hello world! -
-``` - -Without passing `prop` via attribute then the output would be `Default prop value`, as shown below. - -Use component without passing prop: - -```html - -``` - -The output will be: - -```html -
- Default prop value -
-``` - -In the ` -
-
- {{ title }} -
-
- {{ item }} -
-
-``` - -Use: - -```html - -``` - -The output will be: - -```html -
-
- My modal title -
-
- first - second - third - fourth -
-
-``` - -You can also notice how the `class` attribute is merged with `class` attribute of the first node. In the next section you will know more about this. - -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. - -Create a component: - -```html - - -
- Prop in child: {{ prop }} -
-``` - -Create another component that use the first one: - - -```html - - -
- Prop in parent: {{ prop }} - -
-``` - -Use: - -```html - -``` - -The output will be: - -```html -
- Prop in parent: My prop -
- Prop in child: Default prop value -
-
-``` - -As you can see `prop` in `x-child` component are default value and not the one set via `x-parent`. Prepend `aware:` to the attribute name to pass the props to nested components. - - -```html - -``` - -The output now will be: - -```html -
- Prop in parent: My prop -
- Prop in child: My prop -
-
-``` - -### Attributes - -You can pass any attributes to your components and this will be added to the first node of your component, -or to the node with an attribute named `attributes`. If you are familiar with VueJS this is the same as so called -[fallthrough attribute](https://vuejs.org/guide/components/attrs.html), or with Laravel Blade is -[component-attributes](https://laravel.com/docs/10.x/blade#component-attributes). - -By default `class` and `style` are merged with existing `class` and `style` attribute. -All others attributes are override by default. -Only attributes defined in [valid-attributes.js](https://github.com/thewebartisan7/posthtml-components/blob/main/src/valid-attributes.js) -or not defined as `props` in the ` - -``` - -Use the component: - -```html - - -``` - -Result: - -```html - - -``` - -As you may notice the `label` attribute is not added as attribute, since it's defined as a `props`. - -As said early, `class` and `style` are merged by default, if you want to override them, just prepend `override:` to the attribute name: - -```html - - -``` - -Result: - -```html - - -``` - -If you want to use another node and not the first one, then you can add the attribute `attributes` like shown below. - -```html - -
-
- Hello world! -
-
-``` - -Use the component: - -```html - - -``` - -Result: - -```html - -
-
- Hello world! -
-
-``` - -You can add custom rules how attributes are parsed, as behind the scene it's used [posthtml-attrs-parser](https://github.com/posthtml/posthtml-attrs-parser) plugin. - -### Advanced attributes configurations - -If default configurations for valid attributes are not right for you, then you can configure them as explained below. - -```js -// index.js -const { readFileSync, writeFileSync } = require('fs') - -const posthtml = require('posthtml') -const components = require('posthtml-components') - -const options = { - root: './src', - - // Add attributes to specific tag or override defaults - elementAttributes: { - DIV: (defaultAttributes) => { - /* Add new one */ - defaultAttributes.push('custom-attribute-name'); - - return defaultAttributes; - }, - DIV: (defaultAttributes) => { - /* Override all */ - defaultAttributes = ['custom-attribute-name', 'another-one']; - - return defaultAttributes; - }, - }, - - // Add attributes to all tags, use '*' as wildcard for attribute name that starts with - safelistAttributes: [ - 'custom-attribute-name', - 'attribute-name-start-with-*' - ], - - // Remove attributes from all tags that support it - blacklistAttributes: [ - 'role' - ] -} - -posthtml(components(options)) - .process(readFileSync('src/index.html', 'utf8')) - .then((result) => writeFileSync('dist/index.html', result.html, 'utf8')) -``` - -## Examples - -You can work with `` and `` 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 `docs-src/components/modal`. Below is a short explanation about the both approach. - -### Using slots - -Let's suppose we want to create a component for [bootstrap modal](https://getbootstrap.com/docs/5.2/components/modal/). The code required is: - -```html - - -``` - -There is almost three block of code: the header, the body and the footer. -So we could create our component with three slot like below: - -```html - - -``` - -In this case we can use it like: - -```html - - - - - - - Modal body content goes here... - - - - - - -``` - -### Splitting component in small component - -Another way is to split the component in small component, my preferred way, because you can pass attributes to each of them. -So we create the component with a main component and then three different small component: - -```html - - -``` - -```html - -
- -
-``` - -```html - -
- -
-``` - -```html - -
- -
-``` - -And then you can use it like below example: - -```html - - - - - - - Modal body content goes here... - - - - - - -``` - -As said in this way you can pass attributes to each of them, without defining props. - -### Combine slots and small component - -You can also combine both way, and then use them with slots or with small component: - -```html - - - -``` - -Now you can use your component with slots or with small components. -As you may notice, by using slots, you already can use also your small components, and so you can also pass props -via `$slots` which has all the `props` passed via slot, and as well check if slot is filled. - -## Migration - -If you are migrating from `posthtml-extend` and/or `posthtml-modules` please to follow updates here: -[posthtml-components/issues/16](https://github.com/thewebartisan7/posthtml-components/issues/16). - -## Contributing - -See [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs) and [contribution guide](CONTRIBUTING.md). - -[npm]: https://img.shields.io/npm/v/posthtml-component.svg -[npm-url]: https://www.npmjs.com/package/posthtml-component - -[style]: https://img.shields.io/badge/code_style-XO-5ed9c7.svg -[style-url]: https://github.com/sindresorhus/xo - -[cover]: https://coveralls.io/repos/thewebartisan7/posthtml-components/badge.svg?branch=main -[cover-badge]: https://coveralls.io/r/thewebartisan7/posthtml-components?branch=main - -## Credits - -Thanks to all PostHTML contributors and especially to `posthtml-extend` and `posthtml-modules` contributors, as part of code are ~~stolen~~ inspired from these plugins. -Huge thanks also to Laravel Blade template engine. +[![NPM][npm]][npm-url] +[![Coverage][cover]][cover-badge] +[![XO code style][style]][style-url] + +
+ +

PostHTML Components

+

A PostHTML plugin for create components with HTML-friendly syntax inspired by Laravel Blade. Slots, stack/push, props, custom tag and much more.

+
+ +## Installation + +```bash +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, React, Vue or similar, you will find familiar syntax as this plugin is inspired by them. +See below a basic example, as code is worth a thousand words. + +**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).** + +## Basic example + +Create the component: + +``` html + + +``` + +Use the component: + +``` html + + + + Submit + + +``` + +Init PostHTML: + +```js +// index.js +const { readFileSync, writeFileSync } = require('fs') + +const posthtml = require('posthtml') +const components = require('posthtml-components') + +posthtml(components({ root: './src' })) + .process(readFileSync('src/index.html', 'utf8')) + .then((result) => writeFileSync('dist/index.html', result.html, 'utf8')) +``` + +Result: + +``` html + + + + + + +``` + +You may notice that the `src/button.html` component has a `type` and `class` attribute, and when we use the component in `src/index.html` we pass `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` attributes by prepending `override:` to the class attribute. Example: + +```html +Submit + + + +``` + +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 ` + +``` + +The output will be: + +```html + + + + + + +
+
+ Header content +
+
+ Body content +
+
+ Footer content +
+
+ + + +``` + +The `once` attribute allows you to push content only once per rendering cycle. For example, if you are rendering a given component within a loop, you may wish to only push the JavaScript and CSS the first time the component is rendered. + +Example. + +```html + +
+ +
+ + + + + + + + + + +``` + +By default, the content is pushed in the stack in the given order. +If you would like to prepend content onto the beginning of a stack, you should use the `prepend` attribute: + +```html + + + + + + + + + + + +``` + +### Props + +Behind the `props` there is powerful [posthtml-expressions](https://github.com/posthtml/posthtml-expressions) plugin, with feature to pass `props` (locals) via attributes and manipulate them via ` +
+ {{ prop }} +
+``` + +Use: + +```html + +``` + +The output will be: + +```html +
+ Hello world! +
+``` + +Without passing `prop` via attribute then the output would be `Default prop value`, as shown below. + +Use component without passing prop: + +```html + +``` + +The output will be: + +```html +
+ Default prop value +
+``` + +In the ` +
+
+ {{ title }} +
+
+ {{ item }} +
+
+``` + +Use: + +```html + +``` + +The output will be: + +```html +
+
+ My modal title +
+
+ first + second + third + fourth +
+
+``` + +You can also notice how the `class` attribute is merged with `class` attribute of the first node. In the next section you will know more about this. + +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. + +Create a component: + +```html + + +
+ Prop in child: {{ prop }} +
+``` + +Create another component that use the first one: + + +```html + + +
+ Prop in parent: {{ prop }} + +
+``` + +Use: + +```html + +``` + +The output will be: + +```html +
+ Prop in parent: My prop +
+ Prop in child: Default prop value +
+
+``` + +As you can see `prop` in `x-child` component are default value and not the one set via `x-parent`. Prepend `aware:` to the attribute name to pass the props to nested components. + + +```html + +``` + +The output now will be: + +```html +
+ Prop in parent: My prop +
+ Prop in child: My prop +
+
+``` + +### Attributes + +You can pass any attributes to your components and this will be added to the first node of your component, +or to the node with an attribute named `attributes`. If you are familiar with VueJS this is the same as so called +[fallthrough attribute](https://vuejs.org/guide/components/attrs.html), or with Laravel Blade is +[component-attributes](https://laravel.com/docs/10.x/blade#component-attributes). + +By default `class` and `style` are merged with existing `class` and `style` attribute. +All others attributes are override by default. +Only attributes defined in [valid-attributes.js](https://github.com/thewebartisan7/posthtml-components/blob/main/src/valid-attributes.js) +or not defined as `props` in the ` + +``` + +Use the component: + +```html + + +``` + +Result: + +```html + + +``` + +As you may notice the `label` attribute is not added as attribute, since it's defined as a `props`. + +As said early, `class` and `style` are merged by default, if you want to override them, just prepend `override:` to the attribute name: + +```html + + +``` + +Result: + +```html + + +``` + +If you want to use another node and not the first one, then you can add the attribute `attributes` like shown below. + +```html + +
+
+ Hello world! +
+
+``` + +Use the component: + +```html + + +``` + +Result: + +```html + +
+
+ Hello world! +
+
+``` + +You can add custom rules how attributes are parsed, as behind the scene it's used [posthtml-attrs-parser](https://github.com/posthtml/posthtml-attrs-parser) plugin. + +### Advanced attributes configurations + +If default configurations for valid attributes are not right for you, then you can configure them as explained below. + +```js +// index.js +const { readFileSync, writeFileSync } = require('fs') + +const posthtml = require('posthtml') +const components = require('posthtml-components') + +const options = { + root: './src', + + // Add attributes to specific tag or override defaults + elementAttributes: { + DIV: (defaultAttributes) => { + /* Add new one */ + defaultAttributes.push('custom-attribute-name'); + + return defaultAttributes; + }, + DIV: (defaultAttributes) => { + /* Override all */ + defaultAttributes = ['custom-attribute-name', 'another-one']; + + return defaultAttributes; + }, + }, + + // Add attributes to all tags, use '*' as wildcard for attribute name that starts with + safelistAttributes: [ + 'custom-attribute-name', + 'attribute-name-start-with-*' + ], + + // Remove attributes from all tags that support it + blacklistAttributes: [ + 'role' + ] +} + +posthtml(components(options)) + .process(readFileSync('src/index.html', 'utf8')) + .then((result) => writeFileSync('dist/index.html', result.html, 'utf8')) +``` + +## Examples + +You can work with `` and `` 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 `docs-src/components/modal`. Below is a short explanation about the both approach. + +### Using slots + +Let's suppose we want to create a component for [bootstrap modal](https://getbootstrap.com/docs/5.2/components/modal/). The code required is: + +```html + + +``` + +There is almost three block of code: the header, the body and the footer. +So we could create our component with three slot like below: + +```html + + +``` + +In this case we can use it like: + +```html + + + + + + + Modal body content goes here... + + + + + + +``` + +### Splitting component in small component + +Another way is to split the component in small component, my preferred way, because you can pass attributes to each of them. +So we create the component with a main component and then three different small component: + +```html + + +``` + +```html + +
+ +
+``` + +```html + +
+ +
+``` + +```html + +
+ +
+``` + +And then you can use it like below example: + +```html + + + + + + + Modal body content goes here... + + + + + + +``` + +As said in this way you can pass attributes to each of them, without defining props. + +### Combine slots and small component + +You can also combine both way, and then use them with slots or with small component: + +```html + + + +``` + +Now you can use your component with slots or with small components. +As you may notice, by using slots, you already can use also your small components, and so you can also pass props +via `$slots` which has all the `props` passed via slot, and as well check if slot is filled. + +## Migration + +If you are migrating from `posthtml-extend` and/or `posthtml-modules` please to follow updates here: +[posthtml-components/issues/16](https://github.com/thewebartisan7/posthtml-components/issues/16). + +## Contributing + +See [PostHTML Guidelines](https://github.com/posthtml/posthtml/tree/master/docs) and [contribution guide](CONTRIBUTING.md). + +[npm]: https://img.shields.io/npm/v/posthtml-component.svg +[npm-url]: https://www.npmjs.com/package/posthtml-component + +[style]: https://img.shields.io/badge/code_style-XO-5ed9c7.svg +[style-url]: https://github.com/sindresorhus/xo + +[cover]: https://coveralls.io/repos/thewebartisan7/posthtml-components/badge.svg?branch=main +[cover-badge]: https://coveralls.io/r/thewebartisan7/posthtml-components?branch=main + +## Credits + +Thanks to all PostHTML contributors and especially to `posthtml-extend` and `posthtml-modules` contributors, as part of code are ~~stolen~~ inspired from these plugins. +Huge thanks also to Laravel Blade template engine.