30:T1390,dot`digraph "" { node [fontname="var(--sans-serif)" fontsize=12]; edge [fontname="var(--sans-serif)" fontsize=12]; data [shape = doublecircle] data -> "tag open" [label = "<"] data -> data [label = "*"] "tag open" "tag open" -> "markup declaration open" [label = "!"] "tag open" -> "end tag open" [label = "/"] "tag open" -> "tag name" [label = "ASCII alpha"] "tag open" -> "bogus comment" [label = "?"] "tag open" -> "data" [label = "*"] "end tag open" "end tag open" -> "tag name" [label = "ASCII alpha"] "end tag open" -> "data" [label = ">"] "end tag open" -> "bogus comment" [label = "*"] "tag name" "tag name" -> "before attribute name" [label = "space"] "tag name" -> "self-closing start tag" [label = "/"] "tag name" -> "data" [label = ">"] "tag name" -> "tag name" [label = "*"] "self-closing start tag" "self-closing start tag" -> data [label = ">"] "self-closing start tag" -> "before attribute name" [label = "*"] "before attribute name" "before attribute name" -> "after attribute name" [label = "/"] "before attribute name" -> "after attribute name" [label = ">"] "before attribute name" -> "attribute name" [label = "*"] "attribute name" "attribute name" -> "after attribute name" [label = space] "attribute name" -> "after attribute name" [label = "/"] "attribute name" -> "after attribute name" [label = ">"] "attribute name" -> "before attribute value" [label = "="] "attribute name" -> "attribute name" [label = "*"] "after attribute name" "after attribute name" -> "self-closing start tag" [label = "/"] "after attribute name" -> "before attribute value" [label = "="] "after attribute name" -> "data" [label = ">"] "after attribute name" -> "attribute name" [label = "*"] "before attribute value" "before attribute value" -> "before attribute value" [label = space] "before attribute value" -> "attribute value (double-quoted)" [label = "double-quote"] "before attribute value" -> "attribute value (single-quoted)" [label = "single-quote"] "before attribute value" -> "data" [label = ">"] "before attribute value" -> "attribute value (unquoted)" [label = "*"] "attribute value (double-quoted)" "attribute value (double-quoted)" -> "after attribute value (quoted)" [label = "double-quote"] "attribute value (double-quoted)" -> "attribute value (double-quoted)" [label = "*"] "attribute value (single-quoted)" "attribute value (single-quoted)" -> "after attribute value (quoted)" [label = "single-quote"] "attribute value (single-quoted)" -> "attribute value (single-quoted)" [label = "*"] "attribute value (unquoted)" "attribute value (unquoted)" -> "before attribute name" [label = space] "attribute value (unquoted)" -> "data" [label = ">"] "attribute value (unquoted)" -> "attribute value (unquoted)" [label = "*"] "after attribute value (quoted)" "after attribute value (quoted)" -> "self-closing start tag" [label = "/"] "after attribute value (quoted)" -> "data" [label = ">"] "after attribute value (quoted)" -> "before attribute name" [label = "*"] "bogus comment" "bogus comment" -> data [label = ">"] "bogus comment" -> "bogus comment" [label = "*"] "markup declaration open" "markup declaration open" -> "comment start" [label = "--"] "markup declaration open" -> "bogus comment" [label = "*"] "comment start" "comment start" -> "comment start dash" [label = "-"] "comment start" -> "data" [label = ">"] "comment start" -> "comment" [label = "*"] "comment start dash" "comment start dash" -> "comment end" [label = "-"] "comment start dash" -> "data" [label = ">"] "comment start dash" -> "comment" [label = "*"] "comment" "comment" -> "comment less-than sign" [label = "<"] "comment" -> "comment end dash" [label = "-"] "comment" -> "comment" [label = "*"] "comment less-than sign" "comment less-than sign" -> "comment less-than sign bang" [label = "!"] "comment less-than sign" -> "comment" [label = "*"] "comment less-than sign bang" "comment less-than sign bang" -> "comment less-than sign bang dash" [label = "-"] "comment less-than sign bang" -> "comment" [label = "*"] "comment less-than sign bang dash" "comment less-than sign bang dash" -> "comment less-than sign bang dash dash" [label = "-"] "comment less-than sign bang dash" -> "comment end dash" [label = "*"] "comment less-than sign bang dash dash" "comment less-than sign bang dash dash" -> "comment end" [label = "*"] "comment end dash" "comment end dash" -> "comment end" [label = "-"] "comment end dash" -> "comment" [label = "*"] "comment end" "comment end" -> "data" [label = ">"] "comment end" -> "comment end bang" [label = "!"] "comment end" -> "comment end" [label = "-"] "comment end" -> "comment" [label = "*"] "comment end bang" "comment end bang" -> "comment end dash" [label = "-"] "comment end bang" -> "data" [label = ">"] "comment end bang" -> "comment" [label = "*"] }`31:[] 2e:{"title":"Hypertext Literal","cells":[{"id":378,"value":"md`# Hypertext Literal\n\nInspired by [lit-html](https://lit-html.polymer-project.org/) and [HTM](https://github.com/developit/htm), and referencing the fantastically precise [HTML5 spec](https://html.spec.whatwg.org/multipage/parsing.html#tokenization), we built [hypertext literal](https://github.com/observablehq/htl): a tagged template literal for HTML which interpolates values *based on context*, allowing automatic escaping and the interpolation of non-serializable values, such as event listeners, style objects, and other DOM nodes.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":821,"value":"installing = md`Hypertext literal is [open-source](https://github.com/observablehq/htl), small (2KB), has no dependencies, and is available [on npm](https://www.npmjs.com/package/htl). To use hypertext literal in Observable, use htl.**html** or htl.**svg** instead of **html** or **svg**.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":881,"value":"why = md`## Why not concatenate?\n\nSurely the simplest way to generate web content is to write [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML). Modern JavaScript makes it easier than ever to interpolate values into literal HTML thanks to [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":159,"value":"value1 = \"world\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":143,"value":"`

Hello ${value1}

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":197,"value":"md`Yet simple concatenation has two significant drawbacks.\n\nFirst, it confounds markup with text and other content. If an interpolated value happens to include characters that are meaningful markup, the result may render unexpectedly. An ampersand (&) can be interpreted as a character entity reference, for instance.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":209,"value":"value2 = \"dollars£s\"","pinned":true,"hidden":false,"mode":"ojs"},{"id":199,"value":"unsafe_html`My favorite currencies are ${value2}.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":269,"value":"md`This can be fixed by escaping (say replacing ampersands with the corresponding entity, ${document.createTextNode(\"&\")}). But you must remember to escape every time you interpolate, which is tedious! And it’s easy to forget when many values work as intended without it.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":286,"value":"safe_value2 = \"dollars£s\".replace(/&/g, \"&\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":259,"value":"unsafe_html`My favorite currencies are ${safe_value2}.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":179,"value":"md`Second, concatenation impedes composition: interpolated content must be serialized as markup. You cannot combine literal HTML with content created by the DOM API, or a library such as React or D3. And some content, such as event listeners implemented as closures, can’t be serialized!`","pinned":false,"hidden":false,"mode":"ojs"},{"id":456,"value":"features = md`## Features\n\nHypertext literal is a tagged template literal that renders the specified markup as an element, text node, or null as appropriate.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":595,"value":"html`I’m an element!`","pinned":true,"hidden":false,"mode":"ojs"},{"id":597,"value":"html`I’m simply text.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":604,"value":"html`` // I’m null!","pinned":true,"hidden":false,"mode":"ojs"},{"id":619,"value":"md`If multiple top-level nodes are given, the nodes are implicitly wrapped in a SPAN element.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":622,"value":"html`I’m an implicit span.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":1094,"value":"md`If you’d prefer a [document fragment](https://developer.mozilla.org/en-US/docs/Web/API/DocumentFragment) instead, as when composing hypertext literal fragments, call html.fragment. (Observable doesn’t display fragments because it would dissolve them!)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1092,"value":"html.fragment`I’m a document fragment.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":486,"value":"md`### Automatic escaping\n\nIf a value is interpolated into an attribute value or data, it is escaped appropriately so as to not change the structure of the surrounding markup.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":471,"value":"html`Look, Ma, ${\"automatic escaping\"}!`","pinned":true,"hidden":false,"mode":"ojs"},{"id":483,"value":"html`This text has color.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":1138,"value":"md`In cases where it is not possible to interpolate safely, namely with script and style elements where the interpolated value contains the corresponding end tag, an error is thrown.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1141,"value":"html`\"}`","pinned":true,"hidden":false,"mode":"ojs"},{"id":534,"value":"md`### Styles\n\nYou can safely interpolate into style properties, too, by specifying the style attribute as an object literal.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":548,"value":"html`It’s all yellow!`","pinned":true,"hidden":false,"mode":"ojs"},{"id":1058,"value":"md`You can interpolate into a style attribute as a string, too, but use caution: automatic escaping will still allow you to set multiple style properties this way, or to generate invalid CSS.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1061,"value":"html`It’s yellow (and italic).`","pinned":true,"hidden":false,"mode":"ojs"},{"id":511,"value":"md`### Function attributes\n\nIf an attribute value is a function, it is assigned as a property. This can be used to register event listeners.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":520,"value":"html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":521,"value":"mutable clicks = 0","pinned":true,"hidden":false,"mode":"ojs"},{"id":491,"value":"md`### Boolean attributes\n\nIf an attribute value is false, it’s as if the attribute hadn’t been specified. If an attribute value is true, it’s equivalent to the empty string.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":494,"value":"html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":498,"value":"md`### Optional values\n\nIf an attribute value is null or undefined, it’s as if the attribute hadn’t been specified. If a data value is null or undefined, nothing is embedded.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":497,"value":"html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":508,"value":"html`There’s no ${null} here.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":645,"value":"html`${html``}` // It’s nulls all the way down!","pinned":true,"hidden":false,"mode":"ojs"},{"id":550,"value":"md`### Spread attributes\n\nYou can set multiple attributes (or styles, or event listeners) by interpolating an object in place of attributes.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":553,"value":"html`whoa`","pinned":true,"hidden":false,"mode":"ojs"},{"id":556,"value":"html`hover me`","pinned":true,"hidden":false,"mode":"ojs"},{"id":526,"value":"md`### Node values\n\nIf an interpolated data value is a node, it is inserted into the result at the corresponding location. So if you have a function that generates a node (say itself using hypertext literal), you can embed the result into another hypertext literal.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":670,"value":"function emphasize(text) {\n return html`${text}`;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":660,"value":"html`This is ${emphasize(\"really\")} important.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":529,"value":"md`### Iterable values\n\nYou can interpolate iterables into data, too, even iterables of nodes. This is useful for mapping data to content via [*array*.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) or [Array.from](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/from). Typically, you should use html.fragment for the embedded expressions.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":680,"value":"html`\n \n ${d3.schemeCategory10.map((color, i) => html.fragment`\n \n \n \n `)}\n

#	Color	Swatch
${i}	${color}

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":699,"value":"html`It’s as easy as ${new Set([1, 2, 3])}.`","pinned":true,"hidden":false,"mode":"ojs"},{"id":568,"value":"md`### SVG\n\nYou can create contextual SVG fragments using hypertext literals, too.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":574,"value":"svg``","pinned":true,"hidden":false,"mode":"ojs"},{"id":558,"value":"md`### Errors on invalid bindings\n\nHypertext literal tolerates malformed input—per the HTML5 specification—but it still tries to be helpful by throwing an error if you interpolate a value into an unexpected place. For instance, it doesn’t allow dynamic tag names.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":565,"value":"html`<${\"button\"}>Does this work?` // Nope!","pinned":true,"hidden":false,"mode":"ojs"},{"id":454,"value":"md`## How it works\n\nUnder the hood, hypertext literal implements a subset of the [HTML5 tokenizer](https://html.spec.whatwg.org/multipage/parsing.html#tokenization) state machine. This allows it to distinguish between tags, attributes, and the like. And so wherever an embedded expression occurs, it can be interpreted correctly.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":743,"value":"$30","pinned":false,"hidden":false,"mode":"ojs"},{"id":759,"value":"md`Our approach is more formal (and, if you like, more precise) than lit-html, which uses regular expressions to search for “attribute-like sequences” in markup. And while our approach requires scanning the input, the state machine is pretty fast.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":768,"value":"md`Also unlike lit-html, hypertext literal directly creates content rather than reusable templates. Hypertext literal is thus well-suited to Observable, where our [dataflow runtime](/@observablehq/how-observable-runs) runs cells automatically when inputs change. If you want incremental updates for performance (or transitions), you can opt-in, but it’s nice to keep things simple by default.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":790,"value":"md`We also wanted to minimize new syntax. We were inspired by [HTM](https://github.com/developit/htm), but HTM emulates JSX—not HTML5—requiring closing tags for every element. HTM’s approach would also need to be adapted for contextual namespaces, such as SVG, since it creates content bottom-up.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":816,"value":"md`For a closer look at our implementation, please [view the source](https://github.com/observablehq/htl) and let us know what you think! We welcome your contributions and bug reports on GitHub.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":45,"value":"md`---\n\n## Appendix`","pinned":false,"hidden":false,"mode":"ojs"},{"id":23,"value":"html = htl.html","pinned":true,"hidden":false,"mode":"ojs"},{"id":24,"value":"svg = htl.svg","pinned":true,"hidden":false,"mode":"ojs"},{"id":27,"value":"function unsafe_html() {\n const span = document.createElement(\"span\");\n span.innerHTML = String.raw.apply(this, arguments);\n return span;\n}","pinned":true,"hidden":false,"mode":"ojs"}],"files":"$W31","stdlib":"1","titling":"auto"}