Merge pull request #326 from knockout/component/children-as-template

Component children-as-template: skip the <template id=> when colocating

Author: brianmhunt

builds/knockout/spec/components/componentBindingBehaviors.js

@@ -68,14 +68,30 @@ describe('Components: Component binding', function () {
     }).to.throw("Unknown component 'test-component'")
   })
 
-  it('Throws if the component definition has no template', function () {
+  it('Throws if neither a template nor children are provided', function () {
     ko.components.register(testComponentName, {})
     expect(function () {
       ko.applyBindings(outerViewModel, testNode)
       clock.tick(1)
     }).to.throw("Component 'test-component' has no template")
   })
 
+  it('Uses the element children as template when no template is configured', function () {
+    const inner = ko.observable('hello')
+    ko.components.register(testComponentName, {
+      viewModel: function () {
+        return { greeting: inner }
+      }
+    })
+    testNode.innerHTML =
+      '<div data-bind="component: testComponentBindingValue">' + '<span data-bind="text: greeting"></span>' + '</div>'
+    ko.applyBindings(outerViewModel, testNode)
+    clock.tick(1)
+    expectText(testNode.children[0], 'hello')
+    inner('world')
+    expectText(testNode.children[0], 'world')
+  })
+
   it('Controls descendant bindings', function () {
     ko.components.register(testComponentName, { template: 'x' })
     testNode.innerHTML = '<div data-bind="if: true, component: $data"></div>'

package.json

@@ -8,8 +8,8 @@
   },
   "scripts": {
     "build": "bun run --filter './packages/*' build && bun run --filter './builds/*' build",
-    "test": "bunx vitest run",
-    "test:ff": "VITEST_BROWSERS=firefox bunx vitest run",
+    "test": "bunx @biomejs/biome ci . && bun run build && bunx vitest run",
+    "test:ff": "bunx @biomejs/biome ci . && bun run build && VITEST_BROWSERS=firefox bunx vitest run",
     "tsc": "bunx tsc",
     "dts": "bunx tsc --build tsconfig.dts.json",
     "format": "bunx @biomejs/biome format .",

packages/binding.component/spec/componentBindingBehaviors.ts

@@ -9,6 +9,8 @@ import { DataBindProvider } from '@tko/provider.databind'
 import { VirtualProvider } from '@tko/provider.virtual'
 import { ComponentProvider } from '@tko/provider.component'
 import { NativeProvider } from '@tko/provider.native'
+import { AttributeProvider } from '@tko/provider.attr'
+import { TextMustacheProvider, AttributeMustacheProvider } from '@tko/provider.mustache'
 
 import { applyBindings, dataFor } from '@tko/bind'
 
@@ -53,7 +55,15 @@ describe('Components: Component binding', function () {
     testNode.innerHTML = '<div data-bind="component: testComponentBindingValue"></div>'
 
     const provider = new MultiProvider({
-      providers: [new ComponentProvider(), new DataBindProvider(), new VirtualProvider(), new NativeProvider()]
+      providers: [
+        new ComponentProvider(),
+        new DataBindProvider(),
+        new VirtualProvider(),
+        new NativeProvider(),
+        new AttributeProvider(),
+        new TextMustacheProvider(),
+        new AttributeMustacheProvider()
+      ]
     })
     options.bindingProviderInstance = provider
 
@@ -93,12 +103,169 @@ describe('Components: Component binding', function () {
     }).to.throw("Unknown component 'test-component'")
   })
 
-  it('Throws if the component definition has no template', function () {
-    components.register(testComponentName, {})
+  it('Uses the element children as template when no template is configured', function () {
+    const inner = observable('hello')
+    components.register('hello-world', {
+      viewModel: function () {
+        return { greeting: inner }
+      }
+    })
+    cleanups.push(() => components.unregister('hello-world'))
+    testNode.innerHTML = '<hello-world><span ko-text="greeting"></span></hello-world>'
+    applyBindings(outerViewModel, testNode)
+    clock.tick(1)
+    expectContainText(testNode.children[0], 'hello')
+    inner('world')
+    expectContainText(testNode.children[0], 'world')
+  })
+
+  it('Throws if neither a template nor children are provided', function () {
+    components.register('hello-world', {
+      viewModel: function () {
+        return {}
+      }
+    })
+    cleanups.push(() => components.unregister('hello-world'))
+    testNode.innerHTML = '<hello-world></hello-world>'
     expect(function () {
       applyBindings(outerViewModel, testNode)
       clock.tick(1)
-    }).to.throw("Component 'test-component' has no template")
+    }).to.throw("Component 'hello-world' has no template")
+  })
+
+  it('Each instance gets an independent template clone — mutations to one do not bleed into siblings or subsequent instances', function () {
+    components.register('hello-world', {
+      template: '<p class="pristine">hello</p>'
+    })
+    cleanups.push(() => components.unregister('hello-world'))
+
+    testNode.innerHTML = '<hello-world></hello-world><hello-world></hello-world>'
+    applyBindings(outerViewModel, testNode)
+    clock.tick(1)
+
+    const [firstHost, secondHost] = Array.from(testNode.children)
+    const first = firstHost.querySelector('p')!
+    const second = secondHost.querySelector('p')!
+
+    first.className = 'mutated'
+    first.textContent = 'MUTATED'
+    expect(second.className).to.equal('pristine')
+    expect(second.textContent).to.equal('hello')
+
+    const thirdHost = document.createElement('hello-world')
+    testNode.appendChild(thirdHost)
+    applyBindings(outerViewModel, thirdHost)
+    clock.tick(1)
+
+    const third = thirdHost.querySelector('p')!
+    expect(third.className).to.equal('pristine')
+    expect(third.textContent).to.equal('hello')
+  })
+
+  it('Uses children as template with mixed text and {{ }} mustache interpolation', function () {
+    const name = observable('world')
+    components.register('hello-world', {
+      viewModel: function () {
+        return { name }
+      }
+    })
+    cleanups.push(() => components.unregister('hello-world'))
+    testNode.innerHTML = '<hello-world>Hello, <strong>{{ name }}</strong>!</hello-world>'
+    applyBindings(outerViewModel, testNode)
+    clock.tick(1)
+    expectContainText(testNode.children[0], 'Hello, world!')
+    name('TKO')
+    expectContainText(testNode.children[0], 'Hello, TKO!')
+  })
+
+  it('Configured template wins — inline children are discarded', function () {
+    components.register('hello-world', {
+      template: '<p class="from-config">from template config</p>'
+    })
+    cleanups.push(() => components.unregister('hello-world'))
+    testNode.innerHTML = '<hello-world><p class="from-children">from inline</p></hello-world>'
+    applyBindings(outerViewModel, testNode)
+    clock.tick(1)
+    expectContainText(testNode.children[0], 'from template config')
+    expect(testNode.children[0].querySelector('.from-children')).to.equal(null)
+  })
+
+  it('Exposes $component, $data, and $parent inside children-as-template', function () {
+    const parentFlag = observable('parent')
+    components.register('hello-world', {
+      viewModel: function () {
+        return { greeting: 'ello' }
+      }
+    })
+    cleanups.push(() => components.unregister('hello-world'))
+    testNode.innerHTML =
+      '<hello-world>' +
+      '<span class="component" data-bind="text: $component.greeting"></span>' +
+      '<span class="data" data-bind="text: $data.greeting"></span>' +
+      '<span class="parent" data-bind="text: $parent.parentFlag"></span>' +
+      '</hello-world>'
+    applyBindings({ ...outerViewModel, parentFlag }, testNode)
+    clock.tick(1)
+    expect(testNode.children[0].querySelector('.component')!.textContent).to.equal('ello')
+    expect(testNode.children[0].querySelector('.data')!.textContent).to.equal('ello')
+    expect(testNode.children[0].querySelector('.parent')!.textContent).to.equal('parent')
+  })
+
+  it('Nested components both use children-as-template', function () {
+    components.register('outer-comp', {
+      viewModel: function () {
+        return { outerMsg: 'outer' }
+      }
+    })
+    components.register('inner-comp', {
+      viewModel: function () {
+        return { innerMsg: 'inner' }
+      }
+    })
+    cleanups.push(() => {
+      components.unregister('outer-comp')
+      components.unregister('inner-comp')
+    })
+    testNode.innerHTML =
+      '<outer-comp>' +
+      '<span class="outer" ko-text="outerMsg"></span>' +
+      '<inner-comp><span class="inner" ko-text="innerMsg"></span></inner-comp>' +
+      '</outer-comp>'
+    applyBindings(outerViewModel, testNode)
+    clock.tick(1)
+    expect(testNode.children[0].querySelector('.outer')!.textContent).to.equal('outer')
+    expect(testNode.children[0].querySelector('.inner')!.textContent).to.equal('inner')
+  })
+
+  it('Rebuild via observable component name restores original children for the new component', function () {
+    class CompB {
+      msg = 'from-children'
+    }
+    components.register('comp-a', { template: '<span class="from-a">A</span>' })
+    components.register('comp-b', { viewModel: CompB })
+    cleanups.push(() => {
+      components.unregister('comp-a')
+      components.unregister('comp-b')
+    })
+
+    const compName = observable('comp-a')
+    testNode.innerHTML =
+      '<div data-bind="component: { name: compName }">' +
+      '<span class="from-children" data-bind="text: msg"></span>' +
+      '</div>'
+    applyBindings({ compName }, testNode)
+    clock.tick(1)
+
+    expect(testNode.children[0].querySelector('.from-a')).to.not.equal(null)
+    expect(testNode.children[0].querySelector('.from-children')).to.equal(null)
+
+    compName('comp-b')
+    clock.tick(1)
+
+    expect(testNode.children[0].querySelector('.from-a')).to.equal(null)
+    const rendered = testNode.children[0].querySelector('.from-children')
+    expect(rendered).to.not.equal(null)
+    expect(rendered!.textContent).to.equal('from-children')
   })
 
   it('Controls descendant bindings', function () {

packages/binding.component/src/componentBinding.ts

@@ -33,6 +33,17 @@ export default class ComponentBinding extends DescendantBindingHandler {
     this.computed('computeApplyComponent')
   }
 
+  /**
+   * True when originalChildNodes contain at least one element or a text
+   * node with non-whitespace content. Whitespace-only children are treated
+   * as "no children" so `<my-comp>   </my-comp>` still errors.
+   */
+  hasMeaningfulChildren(): boolean {
+    return this.originalChildNodes.some(
+      n => n.nodeType === Node.ELEMENT_NODE || (n.nodeType === Node.TEXT_NODE && (n.nodeValue ?? '').trim().length > 0)
+    )
+  }
+
   cloneTemplateIntoElement(componentName: string, template: any, element: Node) {
     if (!template) {
       throw new Error("Component '" + componentName + "' has no template")
@@ -147,12 +158,14 @@ export default class ComponentBinding extends DescendantBindingHandler {
 
     const viewTemplate = componentViewModel && componentViewModel.template
 
-    if (!viewTemplate && !componentDefinition.template) {
-      throw new Error("Component '" + componentName + "' has no template")
-    }
-
     if (!componentDefinition.template) {
-      this.cloneTemplateIntoElement(componentName, viewTemplate, element)
+      if (viewTemplate) {
+        this.cloneTemplateIntoElement(componentName, viewTemplate, element)
+      } else if (!this.hasMeaningfulChildren()) {
+        throw new Error("Component '" + componentName + "' has no template")
+      } else {
+        this.cloneTemplateIntoElement(componentName, this.originalChildNodes, element)
+      }
     }
 
     if (componentViewModel instanceof LifeCycle) {

packages/utils.component/spec/ComponentABCBehaviors.ts

@@ -58,18 +58,18 @@ describe('ComponentABC', function () {
     components.unregister(testComponentName)
   })
 
-  it("throws when there's no overloading", function () {
+  it('registers without overloading (children-as-template mode)', function () {
     class CX extends ComponentABC {}
-    expect(() => (CX as any).register()).to.throw('overload')
+    expect(() => (CX as any).register()).to.not.throw()
   })
 
-  it('throws when template or element is not overloaded', function () {
-    class CX extends ComponentABC {
-      customElementName() {
+  it('registers when neither template nor element is overloaded (children-as-template mode)', function () {
+    class CXTwo extends ComponentABC {
+      static get customElementName() {
         return 'a-b'
       }
     }
-    expect(() => (CX as any).register()).to.throw('overload')
+    expect(() => (CXTwo as any).register()).to.not.throw()
   })
 
   it('uses the class name kebab-case elementName is not overloaded', function () {

packages/utils.component/src/ComponentABC.ts

@@ -45,23 +45,29 @@ export class ComponentABC extends LifeCycle {
    * 2. An array of DOM nodes
    * 3. A document fragment
    * 4. An AMD module (with `{require: 'some/template'}`)
+   * If neither this nor `element` is overloaded, the component's own
+   * children serve as its template (children-as-template mode).
    * @return {mixed} One of the accepted template types for the ComponentBinding.
    */
   static get template(): any {
     if ('template' in this.prototype) {
       return undefined
     }
-    return { element: this.element }
+    const element = this.element
+    return element ? { element } : undefined
   }
 
   /**
-   * This is called by the default `template`.  Overload this to return:
+   * Overload this to return:
    * 1. The element ID
    * 2. A DOM node itself
-   * @return {string|HTMLElement} either the element ID or actual element.
+   * Leave unset to use children-as-template mode — the component's own
+   * instance children become its template.
+   * @return {string|HTMLElement|undefined} the element ID, actual element,
+   *   or undefined to opt into children-as-template.
    */
-  static get element() {
-    throw new Error('[ComponentABC] `element` must be overloaded.')
+  static get element(): string | HTMLElement | undefined {
+    return undefined
   }
 
   /**