observablehq / htl

A tagged template literal that allows safe interpolation of values into HTML, following the HTML5 spec
https://observablehq.com/@observablehq/htl
ISC License
305 stars 24 forks source link

Add info about interpolating reference-equal nodes #49

Closed lionel-rowe closed 1 year ago

mootari commented 1 year ago

The accompanying Observable notebook is a better place for these examples. I'll share your feedback with the team to discuss how we can improve the documentation there.

mbostock commented 1 year ago

FWIW I don’t see any harm in including this additional clarification in the README (as well as the notebook).

However, I do think the language should be generalized somewhat, since this isn’t just about interpolating reference-equal nodes; it’s also about interpolating a node that already exists (elsewhere) in the DOM, and knowing that HTL will remove that node from its existing location as a side-effect of interpolating it into its new location. And it’s also useful to know that the node that you interpolate is the same node that ends up in the DOM, say if you want to do things to that node subsequently (e.g., add or remove event listeners, or mutate a previously-inteprolated node’s contents).

lionel-rowe commented 1 year ago

FWIW I don’t see any harm in including this additional clarification in the README (as well as the notebook).

However, I do think the language should be generalized somewhat, since this isn’t just about interpolating reference-equal nodes; it’s also about interpolating a node that already exists (elsewhere) in the DOM, and knowing that HTL will remove that node from its existing location as a side-effect of interpolating it into its new location. And it’s also useful to know that the node that you interpolate is the same node that ends up in the DOM, say if you want to do things to that node subsequently (e.g., add or remove event listeners, or mutate a previously-inteprolated node’s contents).

Sure, makes sense — I'll leave the exact wording up to you folks rather than making another PR.

While you're here, TS definitions and allowing setting the window object would both be super useful too 😉