+ A component within a component within a component. Each
+ <tick-counter> lives inside a
+ <counter-row>, which lives inside a
+ <counter-board> — three levels, all light DOM.
+
+
+
Style objects
Computed, conditional inline styles.
diff --git a/docs/src/content/docs/guides/template-vs-render.md b/docs/src/content/docs/guides/template-vs-render.md
index e603746..4cca073 100644
--- a/docs/src/content/docs/guides/template-vs-render.md
+++ b/docs/src/content/docs/guides/template-vs-render.md
@@ -12,3 +12,35 @@ This mental model attempts to reduce the cognitive complexity of authoring compo
1. Overriding the `render()` function for handling a custom `template` is also possible. Here's an example of using `lit-html`: [View on CodePen ↗](https://codepen.io/ayoayco-the-styleful/pen/ZEwNJBR?editors=1010)
See it live: [Templating demo ↗](https://demo.webcomponent.io/examples/templating/) for the two template kinds, and [Render reconciliation demo ↗](https://demo.webcomponent.io/examples/render-reconciliation/) for what an in-place re-render preserves — focus, caret position and an uncommitted input value all survive.
+
+## Composing components
+
+A component's `template` can contain other components, nested as deep as you like:
+
+```js
+class CounterBoard extends WebComponent {
+ static props = { title: 'Board' }
+ get template() {
+ return html`
+ ${this.props.title}
+ `, so the
+parent keeps reconciling those. A light-DOM component, by contrast, renders over
+its own children, so pass data to it through attributes rather than as projected
+children.
diff --git a/package.json b/package.json
index dcef9e8..eded804 100644
--- a/package.json
+++ b/package.json
@@ -109,7 +109,7 @@
"size-limit": [
{
"path": "./dist/WebComponent.js",
- "limit": "2 KB"
+ "limit": "2.05 KB"
},
{
"path": "./dist/html.js",
diff --git a/size-change-log.md b/size-change-log.md
index 260bd40..66db927 100644
--- a/size-change-log.md
+++ b/size-change-log.md
@@ -13,3 +13,4 @@ A running record of how each correctness/feature change affects the `WebComponen
| Reconcile `render()` in place instead of `replaceChildren` (WCB-REQ-06) | 1.81 kB (+0.43 kB) | 1.4 → 1.85 kB | **Re-renders no longer destroy DOM state.** The vnode path rebuilt the whole subtree and swapped it on every prop change, so focus, caret/selection, an uncommitted `${this.props.n} `
+ }
+ }
+ class Middle extends WebComponent {
+ static props = { n: 0 }
+ get template() {
+ return html`
`
+ }
+ }
+ class Root extends WebComponent {
+ static props = { n: 0, banner: 'hi' }
+ get template() {
+ return html`
+
+ ${this.props.banner}
+
+ `
+ }
+ }
+ beforeAll(() => {
+ customElements.define('c-leaf', Leaf)
+ customElements.define('c-middle', Middle)
+ customElements.define('c-root', Root)
+ })
+
+ it('renders all three levels on first connect', () => {
+ const root = mount('c-root')
+ expect(root.querySelector('.banner').textContent).toBe('hi')
+ expect(root.querySelector('c-leaf .leaf').textContent).toBe('0')
+ })
+
+ it('propagates a prop down every level on re-render', () => {
+ const root = mount('c-root')
+ root.props.n = 5
+ expect(root.querySelector('c-middle').getAttribute('n')).toBe('5')
+ expect(root.querySelector('c-leaf').getAttribute('n')).toBe('5')
+ expect(root.querySelector('c-leaf .leaf').textContent).toBe('5')
+ })
+
+ it('does not wipe a nested subtree when an unrelated ancestor prop changes', () => {
+ const root = mount('c-root')
+ const leaf = root.querySelector('c-leaf')
+ // the leaf's own rendered content is present...
+ expect(leaf.querySelector('.leaf').textContent).toBe('0')
+ // ...and an ancestor re-render for an unrelated reason leaves it in place
+ root.props.banner = 'changed'
+ expect(root.querySelector('c-leaf')).toBe(leaf)
+ expect(leaf.querySelector('.leaf')).not.toBeNull()
+ expect(leaf.querySelector('.leaf').textContent).toBe('0')
+ })
+
+ it('preserves a nested component’s own internal state across ancestor re-renders', () => {
+ const root = mount('c-root')
+ const leaf = root.querySelector('c-leaf')
+ // the leaf mutates its own state, independent of any parent prop
+ leaf.props.n = 99
+ expect(leaf.querySelector('.leaf').textContent).toBe('99')
+ // unrelated ancestor re-render must not reset it
+ root.props.banner = 'again'
+ expect(leaf.querySelector('.leaf').textContent).toBe('99')
+ // ...and the leaf node itself was reused, not rebuilt
+ expect(root.querySelector('c-leaf')).toBe(leaf)
+ })
+
+ it('reuses the nested element instance rather than rebuilding it', () => {
+ const root = mount('c-root')
+ const leaf = root.querySelector('c-leaf')
+ root.props.n = 1
+ root.props.n = 2
+ root.props.banner = 'x'
+ expect(root.querySelector('c-leaf')).toBe(leaf)
+ expect(leaf.querySelector('.leaf').textContent).toBe('2')
+ })
+})
+
+describe('conditional nesting', () => {
+ class Inner extends WebComponent {
+ static props = { n: 0 }
+ get template() {
+ return html`${this.props.n} `
+ }
+ }
+ class Toggle extends WebComponent {
+ static props = { show: false }
+ get template() {
+ return this.props.show
+ ? html`
`
+ : html`empty
`
+ }
+ }
+ beforeAll(() => {
+ customElements.define('t-inner', Inner)
+ customElements.define('t-toggle', Toggle)
+ })
+
+ it('adds, removes and re-adds a nested component cleanly', () => {
+ const t = mount('t-toggle')
+ expect(t.querySelector('t-inner')).toBeNull()
+ t.props.show = true
+ expect(t.querySelector('t-inner .inner').textContent).toBe('7')
+ t.props.show = false
+ expect(t.querySelector('t-inner')).toBeNull()
+ expect(t.querySelector('div').textContent).toBe('empty')
+ t.props.show = true
+ expect(t.querySelector('t-inner .inner').textContent).toBe('7')
+ })
+})
+
+describe('shadow-DOM nesting is unaffected', () => {
+ class SLeaf extends WebComponent {
+ static props = { n: 0 }
+ static shadowRootInit = { mode: 'open' }
+ get template() {
+ return html`${this.props.n} `
+ }
+ }
+ class SRoot extends WebComponent {
+ static props = { n: 0, banner: 'hi' }
+ get template() {
+ return html`${this.props.banner}
+
`
+ }
+ }
+ class SlotParent extends WebComponent {
+ static props = { label: 'a' }
+ get template() {
+ return html`${this.props.label}