The transform is disabled by default, you will need to use the useTransform option to enable it.
@@ -183,137 +181,233 @@ export default function (eleventyConfig) {
-WebC Example
+
WebC Example
+
+
+
+
+{% codetitle "index.webc" %}
-Expand for Example
+When WebC **does not** find ` +{%- endset %} +{{ codeBlock | highlight("html") | safe }} +{% codetitle "index.webc" %} +{%- set codeBlock %}Hello possum.
+{% codetitle "_components/my-component.webc" %}
+{%- set codeBlock %}
+WebC Example
+
+WebC Example
+
- Components don’t need a root element, y’all.
+ `](#slots) for use in a client-side custom element.
+Keeps a `` element in the output for a client-side custom element to fill. Read more at [Slots](#slots).
### `webc:nokeep`
-With an CSS/JS component (not an [HTML-only component](#html-only-components)), you can use `webc:nokeep` on the host component to drop the tag:
+Drops the host tag of a [component with CSS or JavaScript](#asset-bundling) from the output.
+
+{% codetitle "index.webc" %}
```html
-
```
-This uses the component tag name (`syntax-highlight`) to look for a WebC component at `node_modules/@11ty/eleventy-plugin-syntaxhighlight/syntax-highlight.webc` and imports it for use on this node. This works with a tag name override via `webc:is` too.
+{% addedin "@11ty/webc@0.6.2" %}With the `npm:` prefix, WebC uses the tag name (`syntax-highlight`) to look for a component at `node_modules/@11ty/eleventy-plugin-syntaxhighlight/syntax-highlight.webc`. This also works with a tag name override via [`webc:is`](#webcis). Eleventy plugins can supply WebC components this way. See the [Syntax Highlighter plugin](/docs/plugins/syntaxhighlight/) (`4.2.0` or newer) for an example.
-### `webc:if`
+## Attributes, props and slots
+
+{% include "webc-attribute-guide.njk" %}
-{% addedin "@11ty/webc@0.7.1" %}
+### Attributes and `webc:root`
+
+Attributes on a host component are available inside the component definition. `webc:root` merges the element’s attributes onto the host component tag, and keeps that tag in the output even for an [HTML-only component](#html-only-components). WebC _merges_ the `class` and `style` attribute values from both.
-Use `webc:if` to conditionally render elements. Accepts arbitrary JavaScript (and is async-friendly). Similar to dynamic attributes, this also has access to component attributes and properties.
+{% codetitle "_components/my-component.webc" %}
```html
-Hello possum.
```
-### `webc:for` Loops
-
-{% addedin "@11ty/webc@0.10.0" %}
+**Note:** The `webc:root` element must be at the top level of the component definition. Nested inside another element, it has no effect.
-Use `webc:for` to loop over data with HTML. It works with Objects and any [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators#built-in_iterables) (String, Array, Map, Set, etc).
+#### Override the host component tag
-The syntax should feel similar to JavaScript’s `for` statement.
+`webc:root="override"` replaces the host component tag with the element itself, with the attributes merged.
-#### Arrays (or any other Iterable)
+{% codetitle "_components/my-component.webc" %}
```html
-
-
+
+```
-
-
+{% codetitle "index.webc" %}
-
-
-
+```html
+` and `[slot]` too. This example is using an [HTML-only component](#html-only-components).
+This example extends the [props example](#props-properties): the `title` prop and the `href` attribute now read from page data.
-{% codetitle "page.webc" %}
+{% codetitle "_components/story-card.webc" %}
```html
-This is the default slot
+` tag in the compiled markup (for use in client JavaScript), use the [`webc:keep` attribute](#webckeep) (e.g. ``).
+- {% addedin "@11ty/webc@0.9.0" %}The `:@` prefix for dynamic props.
+- WebC converts names with dashes to camelCase, as with [props](#props-properties).
+- [`webc:bucket`](#asset-bucketing) is currently the only `webc:*` attribute that accepts a dynamic value. Follow [#143](https://github.com/11ty/webc/issues/143) and [#148](https://github.com/11ty/webc/issues/148) for more.
-{% callout "info", "md" %}Per web component standard conventions, if your component file contains _no content markup_ (e.g. empty or only `
+
+` element in the compiled markup (for use in client JavaScript), add the [`webc:keep` attribute](#webckeep) to it (e.g. ``).
+
+{% callout "info", "md" %}If your component file contains _no content markup_ (it is empty, or has only `
+
+
+
```
-This outputs:
+{% codetitle "index.webc" %}
```html
-Default slot
+WebC Example
+
+
+
+ 
+```
-### Using Template Syntax to Generate Content
+{% codetitle "_site/index.html", "Output example" %}
-The [Custom Transforms feature](https://github.com/11ty/webc#custom-transforms) (e.g. `webc:type`) in the Eleventy WebC plugin has been wired up to the [Eleventy Render plugin](/docs/plugins/render/) to allow you to use existing Eleventy template syntax inside of WebC.
+```html
+
+```
-{% callout "info", "md" %}**Note:** The `webc:type="11ty"` feature is exclusive to the **Eleventy** WebC plugin and is not available in non-Eleventy independent WebC.{% endcallout %}
+#### `webc:type="11ty"` and `11ty:type`
-Use `webc:type="11ty"` with the `11ty:type` attribute to specify a [valid template syntax](/docs/plugins/render/#rendertemplate-paired-shortcode).
+Renders the content with the Eleventy template syntax, or comma-separated chain of syntaxes, named in `11ty:type`. The Eleventy WebC plugin wires the WebC [custom transforms feature](https://github.com/11ty/webc#custom-transforms) to the [Eleventy Render plugin](/docs/plugins/render/) to make this possible.
-{% codetitle "my-page.webc" %}
+{% callout "info", "md" %}**Note:** The `webc:type="11ty"` feature is exclusive to the **Eleventy** WebC plugin and is not available in standalone WebC.{% endcallout %}
+
+`11ty:type` accepts any [valid template syntax](/docs/plugins/render/#rendertemplate-paired-shortcode).
+
+{% codetitle "index.webc" %}
{% raw %}
```liquid
---
-frontmatterdata: "Hello from Front Matter"
+title: Top 10 Fashionable Possums
---
-{% assign t = "Liquid in WebC" %}
-## {{ t }}
+{% assign publication = "Possum Times" %}
+## {{ title }}
-_{{ frontmatterdata }}_
+_{{ publication }}_
```
{% endraw %}
-- You have full access to the data cascade here (note `frontmatterdata` is [set in front matter](#front-matter) above).
-- {% addedin "@11ty/webc@0.5.0" %}Content returned from custom transforms on `` (or `webc:is="template"`) nodes will be processed as WebC—return any WebC content here!
+{% codetitle "_site/index.html", "Output example" %}
-### Using JavaScript to Generate Content
+```html
+WebC Example
+
+WebC Example
+
+
+
+
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+
+ Hello possum.
-``` - -Outputs: - -{% codetitle "_site/page.html" %} - -```html +{%- endset %} +{{ codeBlock | highlight("html") | safe }} +{% codetitle "index.webc" %} +{%- set codeBlock %} + +Hello possum.
-``` - - - -Eleventy runs WebC in Bundler mode. That means that when it finds ` - + + + ``` -You can also use `webc:keep` to save a [`This will render
-This will not render
-
- If the helper promise resolves to a truthy value, this will render
-
+Hello possum.
```
-You can use `webc:type="js"` _(WebC v0.7.1+)_ to use JavaScript for more complex conditional logic (read more below).
-
-### `webc:elseif` and `webc:else`
+{% codetitle "index.webc" %}
-{% addedin "@11ty/webc@0.10.0" %}
+```html
+This will not render
-
-This will render
-This will not render
+
+
+
+
+```
-
-
+{% codetitle "index.webc" %}
-
-
+```html
+
+
```
-#### Nesting `webc:for`
+In the HTML specification, attribute names are lower-case. {% addedin "@11ty/webc@0.8.0" %}WebC converts attribute and prop names with dashes (i.e. `@author-name`) to camelCase for JavaScript (i.e. `authorName`), so `Top 10 Fashionable Possums
+Possum Times
+
+
+
+ Read more
+
```
-{% codetitle "components/my-component.webc" %}
+{% codetitle "top-ten.webc" %}
```html
-Fallback slot content
-This is the default slot
+ ``` -If your WebC component wants to _output_ a `This text will replace slot.
+ + +This text is the default fallback.
``` -- {% addedin "@11ty/webc@0.9.0" %}Previously, the above used to be accomplished by using `webc:root` and `webc:keep` together on an element. +To output a `Hello Susan, do you enjoy being strong?
+Hello Finn, do you enjoy dungeon crawling?
``` - +Works with `var`, `let`, `const`, `function`, and Array and Object [destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment). Uses the [`node-retrieve-globals` package](https://github.com/zachleat/node-retrieve-globals/). -{% callout "info", "md" -%} -_**CSS bundling opinion alert**:_ Some folks recommend using Declarative Shadow DOM for component style encapsulation. This is a great method! It has 2 major drawbacks: +### `webc:type` -1. The progressive enhancement story requires [ubiquitous browser support](https://caniuse.com/declarative-shadow-dom) before using it for content in the critical rendering path. -2. It requires ` +Hello possum.
+``` - function alwaysBlue() { - return "blue"; +{% codetitle "_site/index.html", "Output example" %} + +```html + + + +Hello possum.
+ + +``` + +The same component with the superseded `webc:type="render"`: + +{% codetitle "_components/possum-theme.webc" %} + +```html + +``` + +Notes: + +- To generate scoped CSS with JavaScript, add [`webc:scoped`](#webcscoped) to the element as well (` ``` -Works with `var`, `let`, `const`, `function`, `Array`, and `Object` [destructuring assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment). +{% codetitle "index.webc" %} -- Uses the [`node-retrieve-globals` package](https://github.com/zachleat/node-retrieve-globals/). +```html +
+```
-### Using Template Syntax to Generate Content
+{% codetitle "_site/index.html", "Output example" %}
-The [Custom Transforms feature](https://github.com/11ty/webc#custom-transforms) (e.g. `webc:type`) in the Eleventy WebC plugin has been wired up to the [Eleventy Render plugin](/docs/plugins/render/) to allow you to use existing Eleventy template syntax inside of WebC.
+```html
+
+```
-{% callout "info", "md" %}**Note:** The `webc:type="11ty"` feature is exclusive to the **Eleventy** WebC plugin and is not available in non-Eleventy independent WebC.{% endcallout %}
+#### `webc:type="11ty"` and `11ty:type`
-Use `webc:type="11ty"` with the `11ty:type` attribute to specify a [valid template syntax](/docs/plugins/render/#rendertemplate-paired-shortcode).
+Renders the content with the Eleventy template syntax, or comma-separated chain of syntaxes, named in `11ty:type`. The Eleventy WebC plugin wires the WebC [custom transforms feature](https://github.com/11ty/webc#custom-transforms) to the [Eleventy Render plugin](/docs/plugins/render/) to make this possible.
-{% codetitle "my-page.webc" %}
+{% callout "info", "md" %}**Note:** The `webc:type="11ty"` feature is exclusive to the **Eleventy** WebC plugin and is not available in standalone WebC.{% endcallout %}
+
+`11ty:type` accepts any [valid template syntax](/docs/plugins/render/#rendertemplate-paired-shortcode).
+
+{% codetitle "index.webc" %}
{% raw %}
```liquid
---
-frontmatterdata: "Hello from Front Matter"
+title: Top 10 Fashionable Possums
---
-{% assign t = "Liquid in WebC" %}
-## {{ t }}
+{% assign publication = "Possum Times" %}
+## {{ title }}
-_{{ frontmatterdata }}_
+_{{ publication }}_
```
{% endraw %}
-- You have full access to the data cascade here (note `frontmatterdata` is [set in front matter](#front-matter) above).
-- {% addedin "@11ty/webc@0.5.0" %}Content returned from custom transforms on `` (or `webc:is="template"`) nodes will be processed as WebC—return any WebC content here!
+{% codetitle "_site/index.html", "Output example" %}
-### Using JavaScript to Generate Content
+```html
+Top 10 Fashionable Possums
+Possum Times
+``` -You can also transform individual element content using `webc:type`. In addition to `webc:type="11ty"`, there are three more bundled types: +- The template has full access to the data cascade, including `title` [set in front matter](#front-matter). +- {% addedin "@11ty/webc@0.5.0" %}WebC processes content returned on `` (or `webc:is="template"`) elements as WebC, so you can return any WebC content here. +- You can [add your own custom template engine](/docs/languages/custom/), which is then available here too (e.g. ` -``` +Top 10 Fashionable Possums
+Hello possum.
+{%- endset %} +{{ codeBlock | highlight("html") | safe }} +{% codetitle "index.webc" %} +{%- set codeBlock %} + +Top 10 Fashionable Possums
+Hello possum.
+
+{% codetitle "_components/my-component.webc" %}
+{%- set codeBlock %}
+
+WebC Example
+
+WebC Example
+
+
+
+
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+
+
+
-{% codetitle "components/add-banner-to-css.webc" %}
+{% callout "info", "md" -%}
+Declarative Shadow DOM is another way to encapsulate component styles, and you can use both methods in WebC. It has two tradeoffs:
-```html
-
-
- Top 10 Fashionable Possums
+Hello possum.
+{%- endset %} +{{ codeBlock | highlight("html") | safe }} +{% codetitle "index.webc" %} +{%- set codeBlock %} + +Top 10 Fashionable Possums
+Hello possum.
+
-Expand to see another example of a more complex conditional using
+```html
+
+WebC Example
+
+
+
+
+
+```
-Note that you can also use `webc:if`!
+{% codetitle "_site/index.html", "Output example" %}
```html
-
+
+
+
+ WebC Example
+
+
+
+
+
+
+
+
+
+
+
+
+
```
-Bonus tips:
+### `webc:bucket`
-- You can use `webc:scoped webc:is="style" webc:type="js"` (or `webc:type="render"`) to generate scoped CSS using JavaScript! Read more at [`webc:scoped`](#webcscoped).
-- You have access to the component attributes and props in the render function (which is covered in another section!).
-- {% addedin "@11ty/webc@0.9.0" %}Using `webc:type="js"` has an implied `webc:is="template"` to return content that will be reprocessed as WebC (HTML). You can override this with your own `webc:is` attribute to generate a different tag (e.g. `webc:is="script"` or `webc:is="style"`).
-- {% addedin "@11ty/webc@0.9.0" %}Using `webc:type="js"` has an implied `webc:nokeep` to skip outputting the outer node. You can add `webc:keep` to override this behavior.
+Sends the element’s bundled CSS or JavaScript to a named asset bucket instead of the default one, so you can output it somewhere else on the page, for example at the end of `` instead of in ``. Output a bucket with `getBundle(type, name)`. Read more at [Asset bucketing](#asset-bucketing).
-#### Extra data for JavaScript Render Functions
-
-- `webc.attributes`: {% addedin "@11ty/webc@0.9.0" %} an object literal representing the current element’s attributes.
-- `webc.renderAttributes`: {% addedin "@11ty/webc@0.9.0" %} a method to render _public_ attributes to a string.
-- `webc.filterPublicAttributes`: {% addedin "@11ty/webc@0.10.1" %} a method to filter `webc.attributes`, returning an object with only _public_ attributes. Usage: `webc.filterPublicAttributes(webc.attributes)`
-- `webc.escapeText`: {% addedin "@11ty/webc@0.10.1" %} encodes all characters that have to be escaped in HTML text (via the [`entities` package](https://github.com/fb55/entities/blob/b6cd547c8088b55a18b2ef449bc9dc8f9c294f0c/src/escape.ts#L126))
-- `webc.escapeAttribute`: {% addedin "@11ty/webc@0.10.1" %} encodes all characters that have to be escaped in HTML attributes (via the [`entities` package](https://github.com/fb55/entities/blob/b6cd547c8088b55a18b2ef449bc9dc8f9c294f0c/src/escape.ts#L111))
+Expand to see another example of a more complex conditional using webc:type="js"
+```html
+
+Top 10 Fashionable Possums
+Hello possum.
+Top 10 Fashionable Possums
+ +Hello possum.
+ +
+{% codetitle "_components/my-footer.webc" %}
+{%- set codeBlock %}
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+{% codetitle "index.webc" %}
+{%- set codeBlock %}
+
+WebC Example
+
+WebC Example
+
+
+
+
+
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+{% codetitle "_site/index.html", "Output example" %}
+{%- set codeBlock %}
+
+
+
+
+
+
+
+
+
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+
+{% codetitle "_components/my-footer.webc" %}
+{%- set codeBlock %}
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+{% codetitle "index.webc" %}
+{%- set codeBlock %}
+
+WebC Example
+
+WebC Example
+
+
+
+
+
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+{% codetitle "_site/index.html", "Output example" %}
+{%- set codeBlock %}
+
+
+
+
+
+
+
+
+
+
+
+
+{%- endset %}
+{{ codeBlock | highlight("html") | safe }}
+
-Expand to see an
+## Opting out of WebC processing
-One might imagine an `![]()
` component definition that merges and re-uses all host component attributes correctly like this:
+### `webc:raw`
-{% codetitle "components/img.webc" %}
+Skips WebC processing for everything inside the element, so components, `@` and `:` attributes are output as written. Attributes on the element itself are still processed. This works well with the `` element, which WebC leaves in the output.
-{% raw %}
+{% codetitle "_components/my-component.webc" %}
```html
-
+
+
-
-### `webc:raw`
+{% codetitle "index.webc" %}
-Use `webc:raw` to opt-out of WebC template processing for all child content of the current node. Notably, attributes on the current node will be processed. This works well with ``!
+```html
+Expand to see an img component example
+## Opting out of WebC processing
-One might imagine an `
+
+
```
-### Server-only comments
-
-{% addedin "@11ty/webc@0.10.0" %}
-
-Instead of an HTML comment that will show up in rendered output, you can add one or more dashes to the beginning/end to tell WebC to strip this from the output. Great for server-side comments.
-
-{% codetitle "components/my-component.webc" %}
+{% codetitle "index.webc" %}
```html
-
-
-
+