Skip to content

Commit

Permalink
Refactor valid attributes to use HTML5 valid attributes
Browse files Browse the repository at this point in the history
  • Loading branch information
@thewebartisan7
thewebartisan7 committed Mar 7, 2023
1 parent db5fcf0 commit fb5d3f6
Show file tree
Hide file tree
Showing 14 changed files with 5,633 additions and 223 deletions.
7 changes: 7 additions & 0 deletions docs-src/md/changelog.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
## 1.0.0-RC.1 (2023-03-08)

First Release Candidate

* Prevent attributes used for passing props from being added to first node
* Updated docs

## 1.0.0-beta.16 (2022-11-06)

* Fix aware props propagation
Expand Down
152 changes: 102 additions & 50 deletions docs-src/md/introduction.md
View file

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion docs-src/pages/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ <h1 class="display-1 fw-bold mb-4">Build the web with PostHTML</h1>
</div>

<p class="text-muted">
Currently <strong>v1.0.0-beta.16</strong>
Currently <strong>v1.0.0-RC.1</strong>
<span class="px-1">·</span>
<a href="#" class="link-secondary" data-bs-toggle="modal" data-bs-target="#modalWithComponents">Changelog</a>
</p>
Expand Down
11 changes: 10 additions & 1 deletion docs/demo.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ <h1 class="display-1 fw-bold mb-4">Demo</h1>
</div>
</div>
</main>
<footer>
<footer class="footer mt-auto py-3">
<div class="container-lg">
<div class="text-muted text-center">
Handcrafted with
Expand All @@ -77,6 +77,15 @@ <h5 class="modal-title" id="modalWithComponentsLabel">Changelog</h5>
</div>
<!-- /.modal-header -->
<div class="modal-body">
<h2 id="1.0.0-rc.1-(2023-03-08)" tabindex="-1">
<a class="header-anchor" href="#1.0.0-rc.1-(2023-03-08)">#</a>
1.0.0-RC.1 (2023-03-08)
</h2>
<p>First Release Candidate</p>
<ul>
<li>Prevent attributes used for passing props from being added to first node</li>
<li>Updated docs</li>
</ul>
<h2 id="1.0.0-beta.16-(2022-11-06)" tabindex="-1">
<a class="header-anchor" href="#1.0.0-beta.16-(2022-11-06)">#</a>
1.0.0-beta.16 (2022-11-06)
Expand Down
164 changes: 130 additions & 34 deletions docs/docs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,9 @@
<li class="nav-item">
<a class="nav-link" href="#attributes">Attributes</a>
</li>
<li class="nav-item">
<a class="nav-link" href="#advanced-attributes-configurations">Advanced attributes configurations</a>
</li>
</ul>
</li>
<li class="nav-item">
Expand All @@ -183,11 +186,6 @@
</li>
</ul>
</nav>
<blockquote>
<p>
This plugin is still in early stage of development and the current API may change.
</p>
</blockquote>
<h2 id="installation" tabindex="-1">
<a class="header-anchor" href="#installation">#</a>
Installation
Expand All @@ -199,7 +197,7 @@ <h2 id="introduction" tabindex="-1">
</h2>
<p>
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 is inspired by it.
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.
</p>
<p>
Expand Down Expand Up @@ -245,15 +243,19 @@ <h2 id="basic-example" tabindex="-1">
&lt;/body&gt;
&lt;/html&gt;</code></pre>
<p>
You may notice that our
You may notice that the
<code>src/button.html</code>
component has a
<code>type</code>
and
<code>class</code>
attribute, and when we use the component in
<code>src/index.html</code>
we add type and class attribute.
we pass
<code>type</code>
and
<code>class</code>
attribute.
The result is that
<code>type</code>
is override, and
Expand All @@ -266,7 +268,11 @@ <h2 id="basic-example" tabindex="-1">
and
<code>style</code>
attributes are merged, while all others attribute are override.
You can also override class and style attribute by prepending
You can also override
<code>class</code>
and
<code>style</code>
attributes by prepending
<code>override:</code>
to the class attribute. Example:
</p>
Expand All @@ -282,20 +288,25 @@ <h2 id="basic-example" tabindex="-1">
<code>props</code>
via
<code>&lt;script props&gt;</code>
. More details on this in
or if they are not in the following file
<a href="https://github.com/thewebartisan7/posthtml-components/blob/main/src/valid-attributes.js">valid-attributes.js</a>
.
You can also manage valid attributes via options.
More details on this in
<a href="#attributes">Attributes</a>
section.
</p>
<p>
The
<code>&lt;yield&gt;</code>
tag is where your content will be injected.
In next section you can find all available options and then examples for each features.
In next section you can find all available options and then examples for each feature.
</p>
<p>
See also the
<code>docs-src</code>
folder where you can find more examples. You can run
folder where you can find more examples.
You can run
<code>npm run build</code>
to compile them.
</p>
Expand Down Expand Up @@ -612,6 +623,33 @@ <h2 id="options" tabindex="-1">
.
</td>
</tr>
<tr>
<td style="text-align:center">
<strong>elementAttributes</strong>
</td>
<td style="text-align:center">
<code>{}</code>
</td>
<td style="text-align:left">An object with tag name and a function modifier of valid-attributes.js.</td>
</tr>
<tr>
<td style="text-align:center">
<strong>safelistAttributes</strong>
</td>
<td style="text-align:center">
<code>['data-*']</code>
</td>
<td style="text-align:left">An array of attributes name to be added to default valid attributes.</td>
</tr>
<tr>
<td style="text-align:center">
<strong>blacklistAttributes</strong>
</td>
<td style="text-align:center">
<code>[]</code>
</td>
<td style="text-align:left">An array of attributes name to be removed from default valid attributes.</td>
</tr>
</tbody>
</table>
<h2 id="features" tabindex="-1">
Expand Down Expand Up @@ -718,7 +756,7 @@ <h3 id="multiple-folders" tabindex="-1">
and
<code>./src/layouts</code>
.
You can setup the plugin like below:
You can set up the plugin like below:
</p>
<pre><code class="language-js">// index.js
const options = {
Expand All @@ -734,7 +772,7 @@ <h3 id="namespaces" tabindex="-1">
Namespaces
</h3>
<p>
With namespaces you can define a top level root path to your components like shown in below example.
With namespaces, you can define a top level root path to your components like shown in below example.
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,
and a custom root for override, something like a child theme.
</p>
Expand Down Expand Up @@ -896,7 +934,7 @@ <h3 id="slots" tabindex="-1">
&lt;/div&gt;
&lt;/div&gt;</code></pre>
<p>
By default the content is replaced, but you can also prepend or append the content, or keep the default content by not filling the slot.
By default, the content is replaced, but you can also prepend or append the content, or keep the default content by not filling the slot.
</p>
<p>Add some default content in the component:</p>
<pre><code class="language-html">&lt;!-- src/modal.html --&gt;
Expand Down Expand Up @@ -1022,7 +1060,7 @@ <h3 id="stacks" tabindex="-1">
&lt;script src=&quot;https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js&quot;&gt;&lt;/script&gt;
&lt;/push&gt;</code></pre>
<p>
By default the content is pushed in the stack in the given order.
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
<code>prepend</code>
attribute:
Expand Down Expand Up @@ -1084,15 +1122,7 @@ <h3 id="props" tabindex="-1">
Default prop value
&lt;/div&gt;</code></pre>
<p>
If you don't add the props in
<code>&lt;script props&gt;</code>
inside your component, all props will be added as attributes to the first node of your component or to the node with attribute
<code>attributes</code>
.
More details on this in the next section.
</p>
<p>
So in the
In the
<code>&lt;script props&gt;</code>
you have access to passed props via object
<code>props</code>
Expand Down Expand Up @@ -1134,7 +1164,7 @@ <h3 id="props" tabindex="-1">
<code>class</code>
attribute is merged with
<code>class</code>
attribute of the first node. Let's see in next section more about this.
attribute of the first node. In the next section you will know more about this.
</p>
<p>
You can change how attributes are merged with global props defined via options by passing a callback function used by lodash method
Expand Down Expand Up @@ -1199,10 +1229,17 @@ <h3 id="attributes" tabindex="-1">
Attributes
</h3>
<p>
Your 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
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
<code>attributes</code>
. If you are familiar with VueJS this is the same as so called
<a href="https://vuejs.org/guide/components/attrs.html">fallthrough attribute</a>
, or with Laravel Blade is
<a href="https://laravel.com/docs/10.x/blade#component-attributes">component-attributes</a>
.
By default
</p>
<p>
By default
<code>class</code>
and
<code>style</code>
Expand All @@ -1212,9 +1249,13 @@ <h3 id="attributes" tabindex="-1">
<code>style</code>
attribute.
All others attributes are override by default.
Only attribute not defined as
Only attributes defined in
<a href="https://github.com/thewebartisan7/posthtml-components/blob/main/src/valid-attributes.js">valid-attributes.js</a>
or not defined as
<code>props</code>
will be used.
in the
<code>&lt;script props&gt;</code>
.
</p>
<p>As already seen in basic example:</p>
<pre><code class="language-html">&lt;!-- src/button.html --&gt;
Expand All @@ -1239,7 +1280,6 @@ <h3 id="attributes" tabindex="-1">
<code>props</code>
.
</p>
<p>If you are familiar with Laravel Blade, this is also how Blade handle this.</p>
<p>
As said early,
<code>class</code>
Expand All @@ -1255,7 +1295,7 @@ <h3 id="attributes" tabindex="-1">
<pre><code class="language-html">&lt;!-- dist/index.html --&gt;
&lt;button type=&quot;submit&quot; class=&quot;btn-custom&quot;&gt;My button&lt;/button&gt;</code></pre>
<p>
If you want to use another node for add such attributes, then you can add the attribute
If you want to use another node and not the first one, then you can add the attribute
<code>attributes</code>
like shown below.
</p>
Expand All @@ -1280,6 +1320,53 @@ <h3 id="attributes" tabindex="-1">
<a href="https://github.com/posthtml/posthtml-attrs-parser">posthtml-attrs-parser</a>
plugin.
</p>
<h3 id="advanced-attributes-configurations" tabindex="-1">
<a class="header-anchor" href="#advanced-attributes-configurations">#</a>
Advanced attributes configurations
</h3>
<p>
If default configurations for valid attributes are not right for you, then you can configure them as explained below.
</p>
<pre><code class="language-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) =&gt; {
/* Add new one */
defaultAttributes.push('custom-attribute-name');

return defaultAttributes;
},
DIV: (defaultAttributes) =&gt; {
/* 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) =&gt; writeFileSync('dist/index.html', result.html, 'utf8'))</code></pre>
<h2 id="examples" tabindex="-1">
<a class="header-anchor" href="#examples">#</a>
Examples
Expand All @@ -1289,7 +1376,7 @@ <h2 id="examples" tabindex="-1">
<code>&lt;slot&gt;</code>
and
<code>&lt;fill&gt;</code>
or you can create component for each &quot;block&quot; of your component, and you can also support both of them.
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
<code>docs-src/components/modal</code>
. Below is a short explanation about the both approach.
Expand Down Expand Up @@ -1470,7 +1557,7 @@ <h2 id="migration" tabindex="-1">
</div>
</div>
</main>
<footer>
<footer class="footer mt-auto py-3">
<div class="container-lg">
<div class="text-muted text-center">
Handcrafted with
Expand All @@ -1496,6 +1583,15 @@ <h5 class="modal-title" id="modalWithComponentsLabel">Changelog</h5>
</div>
<!-- /.modal-header -->
<div class="modal-body">
<h2 id="1.0.0-rc.1-(2023-03-08)" tabindex="-1">
<a class="header-anchor" href="#1.0.0-rc.1-(2023-03-08)">#</a>
1.0.0-RC.1 (2023-03-08)
</h2>
<p>First Release Candidate</p>
<ul>
<li>Prevent attributes used for passing props from being added to first node</li>
<li>Updated docs</li>
</ul>
<h2 id="1.0.0-beta.16-(2022-11-06)" tabindex="-1">
<a class="header-anchor" href="#1.0.0-beta.16-(2022-11-06)">#</a>
1.0.0-beta.16 (2022-11-06)
Expand Down
Loading

0 comments on commit fb5d3f6

Please sign in to comment.