add onMount (#34)

* add onMount
* bump coverage

src/html.d.ts

···
 export function html(statics: TemplateStringsArray, ...dynamics: unknown[]): BoundTemplateInstance
 export function keyed<T extends Displayable & object>(value: T, key: Key): T
 export function invalidate(renderable: Renderable): Promise<void>
+export function onMount(renderable: Renderable, callback: () => void | (() => void)): void
 export function onUnmount(renderable: Renderable, callback: () => void): void
 export function getParentNode(renderable: Renderable): Node
 

src/html.js

···
 
 const singlePartTemplate = part => html`${part}`
 
+/* v8 ignore start */
 /** @return {asserts value} */
 const assert = (value, message = 'assertion failed') => {
 	if (!DEV) return
 	if (!value) throw new Error(message)
 }
+/* v8 ignore stop */
 
 /** @implements {SpanInstance} */
 class Span {
···
 }
 
 /** @type {WeakMap<object, {
+  _mounted: boolean 
 	_invalidateQueued: Promise<void> | null
 	_invalidate: () => void
-	_unmountCallbacks: Set<() => void> | null
+	_unmountCallbacks: Set<void | (() => void)> | null
 	_parentNode: Node
 }>} */
 const controllers = new WeakMap()
+
 export function invalidate(renderable) {
 	const controller = controllers.get(renderable)
-	// TODO: if no controller, check again in a microtask?
-	// just in case the renderable was created between invalidation and rerendering
 	assert(controller, 'the renderable has not been rendered')
-
-	// TODO: cancel this invalidation if a higher up one comes along
 	return (controller._invalidateQueued ??= Promise.resolve().then(() => {
 		controller._invalidateQueued = null
 		controller._invalidate()
 	}))
 }
-export function onUnmount(renderable, callback) {
+
+/** @type {WeakMap<Renderable, Set<() => void | (() => void)>>} */
+const mountCallbacks = new WeakMap()
+
+export function onMount(renderable, callback) {
+	DEV: assert(isRenderable(renderable), 'expected a renderable')
+
 	const controller = controllers.get(renderable)
-	assert(controller, 'the renderable has not been rendered')
+	if (controller?._mounted) {
+		;(controller._unmountCallbacks ??= new Set()).add(callback())
+		return
+	}
+
+	let cb = mountCallbacks.get(renderable)
+	if (!cb) mountCallbacks.set(renderable, (cb = new Set()))
+	cb.add(callback)
+}
 
-	controller._unmountCallbacks ??= new Set()
-	controller._unmountCallbacks.add(callback)
+export function onUnmount(renderable, callback) {
+	onMount(renderable, () => callback)
 }
+
 export function getParentNode(renderable) {
 	const controller = controllers.get(renderable)
 	assert(controller, 'the renderable has not been rendered')
-
 	return controller._parentNode
 }
 
···
 	#switchRenderable(next) {
 		if (this.#renderable && this.#renderable !== next) {
 			const controller = controllers.get(this.#renderable)
-			if (controller?._unmountCallbacks) for (const callback of controller._unmountCallbacks) callback()
+			if (controller?._unmountCallbacks) for (const callback of controller._unmountCallbacks) callback?.()
 			controllers.delete(this.#renderable)
 		}
 		this.#renderable = next
···
 
 			if (!controllers.has(renderable))
 				controllers.set(renderable, {
+					_mounted: false,
 					_invalidateQueued: null,
 					_invalidate: () => {
 						DEV: assert(this.#renderable === renderable, 'could not invalidate an outdated renderable')
···
 			}
 
 			this.#span._end = end
+
+			const controller = controllers.get(this.#renderable)
+			if (controller) {
+				controller._mounted = true
+				// @ts-expect-error -- WeakMap lookups of null always return undefined, which is fine
+				for (const callback of mountCallbacks.get(this.#renderable) ?? []) {
+					;(controller._unmountCallbacks ??= new Set()).add(callback())
+				}
+				// @ts-expect-error -- WeakMap lookups of null always return undefined, which is fine
+				mountCallbacks.delete(this.#renderable)
+			}
+
 			if (endsWereEqual) this.#parentSpan._end = this.#span._end
 
 			return
···
 			}
 		}
 
-		if (endsWereEqual) this.#parentSpan._end = this.#span._end
+		this.#value = value
+
+		const controller = controllers.get(this.#renderable)
+		if (controller) {
+			controller._mounted = true
+			// @ts-expect-error -- WeakMap lookups of null always return undefined, which is fine
+			for (const callback of mountCallbacks.get(this.#renderable) ?? []) {
+				;(controller._unmountCallbacks ??= new Set()).add(callback())
+			}
+			// @ts-expect-error -- WeakMap lookups of null always return undefined, which is fine
+			mountCallbacks.delete(this.#renderable)
+		}
 
-		this.#value = value
+		if (endsWereEqual) this.#parentSpan._end = this.#span._end
 	}
 
 	detach() {

test/attributes.test.ts

···
 		expect(el.querySelector('h1')).toHaveAttribute('style', 'color: red')
 	})
 
+	it('can toggle attributes', () => {
+		const { root, el } = setup()
+
+		let hidden: unknown = false
+		const template = () => html`<h1 hidden=${hidden}>Hello, world!</h1>`
+
+		root.render(template())
+		expect(el.querySelector('h1')).not.toHaveAttribute('hidden')
+
+		hidden = true
+		root.render(template())
+		expect(el.querySelector('h1')).toHaveAttribute('hidden')
+
+		hidden = null
+		root.render(template())
+		expect(el.querySelector('h1')).not.toHaveAttribute('hidden')
+	})
+
 	it('supports property attributes', () => {
 		const { root, el } = setup()
 

test/basic.test.ts

···
 import { html, type Displayable } from 'dhtml'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { setup } from './setup'
 
 describe('basic', () => {
···
 
 		root.render(html`<h1>Hello, world!</h1>`)
 		expect(el.innerHTML).toMatchInlineSnapshot(`"<div>before</div><h1>Hello, world!</h1><div>after</div>"`)
-	})
-
-	it('user errors', { skip: import.meta.env.PROD }, () => {
-		const { root, el } = setup()
-
-		let thrown
-		try {
-			root.render(html`<button @click=${123}></button>`)
-		} catch (error) {
-			thrown = error as Error
-		}
-
-		expect(el.innerHTML).toBe('<button></button>')
-		expect(thrown).toBeInstanceOf(Error)
-		expect(thrown!.message).toMatch(/expected a function/i)
 	})
 
 	it('update identity', () => {
···
 		expect((el.firstChild as Text).data).toBe('abc')
 	})
 })
+
+const console = {
+	warn: vi.fn(),
+}
+vi.stubGlobal('console', console)
+
+describe('errors', () => {
+	it('throws on non-function event handlers', { skip: import.meta.env.PROD }, () => {
+		const { root, el } = setup()
+
+		let thrown
+		try {
+			root.render(html`<button @click=${123}></button>`)
+		} catch (error) {
+			thrown = error as Error
+		}
+
+		expect(el.innerHTML).toBe('<button></button>')
+		expect(thrown).toBeInstanceOf(Error)
+		expect(thrown!.message).toMatch(/expected a function/i)
+	})
+
+	it('throws cleanly', () => {
+		const { root, el } = setup()
+
+		const oops = new Error('oops')
+		let thrown
+		try {
+			root.render(
+				html`${{
+					render() {
+						throw oops
+					},
+				}}`,
+			)
+		} catch (error) {
+			thrown = error
+		}
+		expect(thrown).toBe(oops)
+
+		// on an error, don't leave any visible artifacts
+		expect(el.innerHTML).toBe('<!---->')
+	})
+
+	it('warns on invalid part placement', () => {
+		const { root, el } = setup()
+
+		expect(console.warn).not.toHaveBeenCalled()
+
+		root.render(html`<${'div'}>${'text'}</${'div'}>`)
+		expect(el.innerHTML).toMatchInlineSnapshot(`"<dyn-$0>text</dyn-$0>"`)
+
+		expect(console.warn).toHaveBeenCalledWith('dynamic value detected in static location')
+	})
+
+	it('does not warn parts in comments', () => {
+		const { root, el } = setup()
+
+		expect(console.warn).not.toHaveBeenCalled()
+
+		root.render(html`<!-- ${'text'} -->`)
+		expect(el.innerHTML).toMatchInlineSnapshot(`"<!-- dyn-$0 -->"`)
+
+		expect(console.warn).not.toHaveBeenCalled()
+	})
+})

test/lists.test.ts

···
 		root.render([2])
 		expect(el.innerHTML).toBe('2')
 	})
+
+	it('can disappear', () => {
+		const { root, el } = setup()
+
+		const app = {
+			show: true,
+			render() {
+				if (!this.show) return null
+				return [1, 2, 3].map(i => html`<div>${i}</div>`)
+			},
+		}
+
+		root.render(app)
+		expect(el.innerHTML).toMatchInlineSnapshot(`"<div>1</div><div>2</div><div>3</div>"`)
+
+		app.show = false
+		root.render(app)
+		expect(el.innerHTML).toMatchInlineSnapshot(`""`)
+	})
 })
 
 describe('list reordering', () => {
···
 		expect(el.innerHTML).toBe(items.map(([, html]) => html).join(''))
 	})
 })
+
+describe('list with keys', () => {
+	it("can't key something twice", () => {
+		expect(() => keyed(html``, 1)).not.toThrow()
+		expect(() => keyed(keyed(html``, 1), 1)).toThrow()
+	})
+})

test/renderable.test.ts

···
-import { getParentNode, html, invalidate, onUnmount, type Renderable } from 'dhtml'
+import { getParentNode, html, invalidate, onMount, onUnmount, type Renderable } from 'dhtml'
 import { describe, expect, it, vi } from 'vitest'
 import { setup } from './setup'
 
-describe('renderable', () => {
-	it('basic', async () => {
+describe('renderables', () => {
+	it('works', async () => {
 		const { root, el } = setup()
 
 		root.render(
···
 		expect(app.i).toBe(4)
 	})
 
-	it('throws', () => {
+	it('handles undefined', () => {
+		const { root, el } = setup()
+
+		root.render({
+			// @ts-expect-error
+			render() {},
+		})
+
+		expect(el.innerHTML).toBe('')
+	})
+})
+
+describe('onMount', () => {
+	it('calls in the right order', () => {
 		const { root, el } = setup()
 
-		const oops = new Error('oops')
-		let thrown
-		try {
-			root.render(
-				html`${{
-					render() {
-						throw oops
-					},
-				}}`,
-			)
-		} catch (error) {
-			thrown = error
+		const sequence: string[] = []
+
+		const inner = {
+			attached: false,
+			render() {
+				sequence.push('inner render')
+				if (!this.attached) {
+					this.attached = true
+					onMount(this, () => {
+						sequence.push('inner mount')
+						return () => {
+							sequence.push('inner cleanup')
+						}
+					})
+				}
+				return 'inner'
+			},
+		}
+
+		const outer = {
+			attached: false,
+			show: true,
+			render() {
+				sequence.push('outer render')
+				if (!this.attached) {
+					this.attached = true
+					onMount(this, () => {
+						sequence.push('outer mount')
+						return () => {
+							sequence.push('outer cleanup')
+						}
+					})
+				}
+				if (!this.show) return null
+				return inner
+			},
+		}
+
+		outer.show = true
+		root.render(outer)
+		expect(el.innerHTML).toBe('inner')
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner render",
+			  "inner mount",
+			  "outer mount",
+			]
+		`)
+		sequence.length = 0
+
+		outer.show = false
+		root.render(outer)
+		expect(el.innerHTML).toBe('')
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner cleanup",
+			]
+		`)
+		sequence.length = 0
+
+		outer.show = true
+		root.render(outer)
+		expect(el.innerHTML).toBe('inner')
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner render",
+			]
+		`)
+		sequence.length = 0
+	})
+
+	it('registers multiple callbacks', () => {
+		const { root } = setup()
+
+		const sequence: string[] = []
+
+		const app = {
+			render() {
+				onMount(this, () => {
+					sequence.push('mount 1')
+					return () => sequence.push('cleanup 1')
+				})
+
+				onMount(this, () => {
+					sequence.push('mount 2')
+					return () => sequence.push('cleanup 2')
+				})
+
+				return 'app'
+			},
+		}
+
+		root.render(app)
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "mount 1",
+			  "mount 2",
+			]
+		`)
+		sequence.length = 0
+
+		root.render(null)
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "cleanup 1",
+			  "cleanup 2",
+			]
+		`)
+	})
+
+	it('registers a fixed callback once', () => {
+		const { root } = setup()
+
+		const sequence: string[] = []
+
+		function callback() {
+			sequence.push('mount')
+			return () => sequence.push('cleanup')
+		}
+
+		const app = {
+			render() {
+				onMount(this, callback)
+				onMount(this, callback)
+				return 'app'
+			},
+		}
+
+		root.render(app)
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "mount",
+			]
+		`)
+		sequence.length = 0
+
+		root.render(null)
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "cleanup",
+			]
+		`)
+	})
+
+	it('registers callbacks outside of render', () => {
+		const { root } = setup()
+
+		const sequence: string[] = []
+
+		const app = {
+			render() {
+				sequence.push('render')
+				return 'app'
+			},
+		}
+
+		onMount(app, () => {
+			sequence.push('mount')
+			return () => sequence.push('cleanup')
+		})
+
+		expect(sequence).toMatchInlineSnapshot(`[]`)
+
+		root.render(app)
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "render",
+			  "mount",
+			]
+		`)
+		sequence.length = 0
+
+		root.render(null)
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "cleanup",
+			]
+		`)
+	})
+
+	it('can access the dom in callback', () => {
+		const { root } = setup()
+
+		const app = {
+			render() {
+				onMount(this, () => {
+					const parent = getParentNode(this) as Element
+					expect(parent.firstElementChild).toBeInstanceOf(HTMLParagraphElement)
+				})
+				return html`<p>Hello, world!</p>`
+			},
 		}
-		expect(thrown).toBe(oops)
 
-		// on an error, don't leave any visible artifacts
-		expect(el.innerHTML).toBe('<!---->')
+		root.render(app)
 	})
 
+	it('works after render', () => {
+		const { root } = setup()
+
+		const app = {
+			render() {
+				return 'app'
+			},
+		}
+
+		root.render(app)
+
+		const mounted = vi.fn()
+		onMount(app, mounted)
+		expect(mounted).toHaveBeenCalledOnce()
+	})
+})
+
+describe('onUnmount', () => {
 	it('unmount deep', () => {
 		const { root, el } = setup()
 
···
 		outer.show = true
 		root.render(outer)
 		expect(el.innerHTML).toBe('inner')
-		expect(sequence).toEqual(['outer render', 'inner render'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner render",
+			]
+		`)
 		sequence.length = 0
 
 		outer.show = false
 		root.render(outer)
 		expect(el.innerHTML).toBe('')
-		expect(sequence).toEqual(['outer render', 'inner abort'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner abort",
+			]
+		`)
 		sequence.length = 0
 
 		outer.show = true
 		root.render(outer)
 		expect(el.innerHTML).toBe('inner')
-		expect(sequence).toEqual(['outer render', 'inner render'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner render",
+			]
+		`)
 		sequence.length = 0
 
 		outer.show = false
 		root.render(outer)
 		expect(el.innerHTML).toBe('')
-		expect(sequence).toEqual(['outer render', 'inner abort'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner abort",
+			]
+		`)
 		sequence.length = 0
 	})
 
···
 		outer.show = true
 		root.render(outer)
 		expect(el.innerHTML).toBe('inner')
-		expect(sequence).toEqual(['outer render', 'inner render'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner render",
+			]
+		`)
 		sequence.length = 0
 
 		outer.show = false
 		root.render(outer)
 		expect(el.innerHTML).toBe('')
-		expect(sequence).toEqual(['outer render', 'inner abort'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner abort",
+			]
+		`)
 		sequence.length = 0
 
 		outer.show = true
 		root.render(outer)
 		expect(el.innerHTML).toBe('inner')
-		expect(sequence).toEqual(['outer render', 'inner render'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner render",
+			]
+		`)
 		sequence.length = 0
 
 		outer.show = false
 		root.render(outer)
 		expect(el.innerHTML).toBe('')
-		expect(sequence).toEqual(['outer render', 'inner abort'])
+		expect(sequence).toMatchInlineSnapshot(`
+			[
+			  "outer render",
+			  "inner abort",
+			]
+		`)
 		sequence.length = 0
+	})
+
+	it('works externally', async () => {
+		const { root, el } = setup()
+
+		const app = {
+			render() {
+				return [1, 2, 3].map(i => html`<div>${i}</div>`)
+			},
+		}
+
+		const unmounted = vi.fn()
+		onUnmount(app, unmounted)
+
+		root.render(app)
+		expect(el.innerHTML).toMatchInlineSnapshot(`"<div>1</div><div>2</div><div>3</div>"`)
+		expect(unmounted).not.toHaveBeenCalled()
+
+		root.render(null)
+		expect(unmounted).toHaveBeenCalledOnce()
 	})
 })
 

vitest.config.js

···
 		DHTML_PROD: prod,
 	},
 	test: {
+		clearMocks: true,
 		coverage: {
 			enabled: ci,
 			reporter: ['text', 'json-summary', 'json'],