1d:{"title":"Hello and Welcome!","cells":[{"id":111,"value":"md`# Hello and Welcome!\n\nThis interactive, editable document introduces you to Observable notebooks. You can edit any code you see: type Shift-Return to run your changes! (Your changes aren’t be saved, so if something goes horribly wrong, just reload.)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1,"value":"md`## Notebooks are comprised of cells.\n\nA notebook is a list of *cells*, and each cell is defined by a snippet of JavaScript. The runtime evaluates these snippets and displays their values.\n\nThis cell—the one you are currently reading—is defined as a Markdown string. The Markdown is parsed by a JavaScript library, [marked](https://github.com/chjj/marked), to generate the corresponding HTML DOM elements, which are then inserted into the page. You can see the code for this cell by clicking on the caret in the left margin.\n\nMarkdown cells are common for prose, but you can also compute and display arbitrary JavaScript values. For example, here we compute the answer to the ultimate question of life, the universe, and everything:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":62,"value":"answer = 2 * 3 * 7","pinned":true,"hidden":false,"mode":"ojs"},{"id":67,"value":"md`As you might expect, you can inspect nested data structures here just as you can in your browser’s developer console. The inspected value below is initially collapsed (\\`▸\\`); click on it to expand (\\`▾\\`):`","pinned":false,"hidden":false,"mode":"ojs"},{"id":70,"value":"({\"subjects\": [\"life\", \"the universe\", \"everything\"]})","pinned":true,"hidden":false,"mode":"ojs"},{"id":135,"value":"md`The object literal above is wrapped in parens \\`({…})\\` to distinguish it from a block statement \\`{…}\\`. Block statements are used for complex cell definitions when a simple expression isn’t sufficient. (Cell definitions are similar to the bodies of [arrow functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions).) A block statement typically has one or more \\`return\\` statements. For example, here is a \\`for\\` loop to compute the sum of the integers 1 to 10:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":139,"value":"{\n let sum = 0;\n for (let i = 1; i <= 10; ++i) sum += i;\n return sum;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":213,"value":"md`If you forget to \\`return\\`, just as with a normal function, the value of the cell is \\`undefined\\`. It can sometimes be useful to define cells that only have side-effects (where you don’t care about the return value), but this technique should be used with care.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":253,"value":"md`## Cells are tiny programs.\n\nIn conventional code editors, we edit large text files that are compiled or interpreted into complex programs; a single typo can cause the whole program not to run due to invalid syntax. These notebooks work a bit differently: each cell is parsed individually, so one broken cell does not prevent other cells from running.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":281,"value":"42, // Oops, a SyntaxError!","pinned":true,"hidden":false,"mode":"ojs"},{"id":307,"value":"md`Since the content of each cell is edited individually, a notebook is more akin to a spreadsheet than a conventional program. If you edit a cell and Command-A to select all, for example, it just selects the text of the current cell rather than the entire notebook. (In the future, the editor will also support bulk operations on cells, such as moving, deleting, and copy-paste.)\n\nYou can split the current cell by typing Option-Return. You can move the current cell up or down using Option-Command-Up and Option-Command-Down, respectively. For more keyboard shortcuts, see the [Editor Cheatsheet](https://d3.express/@mbostock/editor-cheatsheet).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":193,"value":"md`## Cells can generate DOM.\n\nWhen a cell evaluates to a DOM element, the element is displayed directly, rather than using the inspector. For example, you can create DOM using the standard W3C API:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":27,"value":"document.createTextNode(\"Hello, I am text!\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":37,"value":"md`Or using the \\`html\\` built-in:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":132,"value":"html`Hello, I am italicized!`","pinned":true,"hidden":false,"mode":"ojs"},{"id":1103,"value":"md`Or the \\`md\\` built-in:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1105,"value":"md`Hello, I am *Markdown*!`","pinned":true,"hidden":false,"mode":"ojs"},{"id":224,"value":"md`You can likewise generate SVG:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":225,"value":"html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":229,"value":"md`And even canvas!`","pinned":false,"hidden":false,"mode":"ojs"},{"id":231,"value":"{\n const canvas = document.createElement(\"canvas\");\n canvas.width = 50;\n canvas.height = 50;\n const context = canvas.getContext(\"2d\");\n context.arc(25, 25, 20, 0, 2 * Math.PI);\n context.fillStyle = \"blue\";\n context.fill();\n return canvas;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":604,"value":"md`Because DOM elements are displayed natively by the browser, there’s no overhead or limitation on the content you can generate from a cell. If you want to, you can put your entire program into a single cell; this makes editing a notebook similar to a live-reload editor such as JSFiddle or CodePen. But, if you break your code up into separate cells, it’s easier to observe the state of your program as it runs and to implement dynamic, animated and interactive elements.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":144,"value":"md`## Cells can have names.\n\nIn addition to *values*, cells can have *names*. Names allow you to refer to the current value of a cell from another cell, and so to compose more complex programs from cells. For example these two cells define \\`x\\` and \\`y\\`:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2,"value":"x = 2","pinned":true,"hidden":false,"mode":"ojs"},{"id":5,"value":"y = 3","pinned":true,"hidden":false,"mode":"ojs"},{"id":327,"value":"md`Now this cell can compute the sum \\`x + y\\`:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":7,"value":"x + y","pinned":true,"hidden":false,"mode":"ojs"},{"id":329,"value":"md`Try editing the definition of \\`x\\` or \\`y\\` above. When you Shift-Return to commit your edit, notice that the sum updates automatically.\n\nA cell’s references are determined by static analysis: the code is parsed by the editor to find out-of-scope identifiers. Normal JavaScript scope rules apply, so an in-scope identifier can mask one that is out-of-scope. In the following cell, \\`x\\` refers to a local variable rather than the cell above:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":384,"value":"{\n const x = 1337; // This defines a local x, masking the cell above.\n return x;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":657,"value":"md`Cells can be defined in any order: you don’t have to define a cell before you reference it. (This is similar to [hoisting](https://developer.mozilla.org/en-US/docs/Glossary/Hoisting) in JavaScript.) So you can compute \\`z * z\\` here, before:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":620,"value":"z * z","pinned":true,"hidden":false,"mode":"ojs"},{"id":622,"value":"md`Even though \\`z\\` is defined here, after:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":626,"value":"z = 8","pinned":true,"hidden":false,"mode":"ojs"},{"id":631,"value":"md`A consequence of order-independent evaluation is that names must be unique. Giving the same name to multiple cells will prevent those cells (and any cell that references that name) from being evaluated.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":635,"value":"doop = 1","pinned":true,"hidden":false,"mode":"ojs"},{"id":637,"value":"doop = 2 // doop is not a unique name! 💥","pinned":true,"hidden":false,"mode":"ojs"},{"id":668,"value":"doop + 1 // doop is not defined 💥","pinned":true,"hidden":false,"mode":"ojs"},{"id":681,"value":"md`Likewise, you must avoid circular references in cells. Cycles can’t be evaluated:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":406,"value":"a = b + 1 // a depends on b","pinned":true,"hidden":false,"mode":"ojs"},{"id":410,"value":"b = a + 1 // b depends on a 💥","pinned":true,"hidden":false,"mode":"ojs"},{"id":683,"value":"md`While not yet implemented, we’d like to surface some of this program structure in the editor to aid understanding. For example, we’re considering ways to visualize the directed acyclic graph of cell references, and to use syntax highlighting to link references with their definition and *vice versa*.\n\n

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":404,"value":"$1f","pinned":false,"hidden":false,"mode":"ojs"},{"id":714,"value":"function k(x, y) {\n return x / y;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":712,"value":"md`The runtime calls these functions automatically whenever their inputs change. As long as each function is *pure*, the program is deterministic. So, you *can* use side-effects, but your code will be more readable if you stick to pure functions.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":152,"value":"md`## Cells can be promises.\n\nJavaScript is often asynchronous—for example, when loading third-party libraries or datasets, or when communicating with an external host. To reduce the complexity of asynchronous code, notebooks have first-class support for [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise): when a cell evaluates to a promise, the *value* of the promise is exposed to referencing cells when the promise is resolved.\n\nFor example, this promise is defined using a simple timeout, such that its value is available three seconds after the page loads:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":916,"value":"message = new Promise(resolve => {\n setTimeout(() => {\n resolve(\"I am asynchronous!\");\n }, 3000);\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":924,"value":"md`But in other cells, we can reference the \\`message\\` without caring that it is defined asynchronously:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":919,"value":"message.toUpperCase()","pinned":true,"hidden":false,"mode":"ojs"},{"id":926,"value":"md`(This is similar to having an implicit \\`await\\` whenever you reference the value of another cell. However, unlike \\`await\\`, a cell is not evaluated until *all* of the values it references have been resolved—the awaited values are thus computed in parallel rather than in series.)`","pinned":false,"hidden":false,"mode":"ojs"},{"id":913,"value":"md`Here’s a slightly more complex example using the Fetch API. It involves two promises: one that yields a Response, and a second that yields the response body. The yielded value is the *Les Misérables* graph dataset, containing ${miserables.nodes.length} nodes and ${miserables.links.length} links.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":426,"value":"miserables = {\n const response = await fetch(\"https://gist.githubusercontent.com\"\n + \"/mbostock/4062045\"\n + \"/raw/94d1b56d1e6c0d4bcc1edd86a41385a14ed4c1b3\"\n + \"/miserables.json\");\n return response.json();\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":438,"value":"md`Even though \\`miserables\\` is defined asynchronously, I can reference it statically in other cells. This reduces the complexity of dynamic programs: you can reference a value without caring how the value is defined. You can switch between hard-coded values, values fetched from a remote server, values driven by a graphical user interface, or dynamically-computed values, all without affecting downstream code.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":154,"value":"md`## Cells can be generators.\n\nPromises are useful when you have a constant value that must be resolved asynchronously. But what if you have a value that changes over time, like the temperature outside or a stock price? Enter [generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Iterators_and_Generators), which define a potentially-infinite sequence of values. For example, here’s a standard JavaScript generator function that returns a generator that yields numbers from [0, 1, 2 … *n* - 1]:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":459,"value":"function* range(n) {\n for (let i = 0; i < n; ++i) {\n yield i;\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":461,"value":"md`Calling this function returns a generator, and the notebook displays the values of the generator in animated sequence:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":462,"value":"button, range(100)","pinned":true,"hidden":false,"mode":"ojs"},{"id":814,"value":"viewof button = html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":467,"value":"md`The value above most likely reads \\`99\\` because this is the last value yielded by the generator. If you focus the code for the cell above and hit Shift-Return, you’ll see it quickly cycle through the numbers again. Or hit the restart button.\n\nYou can define a cell as a generator using \\`yield\\` statements. For example:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":472,"value":"{\n for (let i = 0; i < 100; ++i) {\n yield i;\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":477,"value":"md`(Be careful to avoid infinite loops without \\`yield\\`. An infinite loop that yields is fine—the loop will iterate up to sixty times a second; an infinite loop that doesn’t yield will hang the browser, and you’ll need to reload the page. The user experience around hangs might improve if browser vendors implement [OOPIFs](https://www.chromium.org/developers/design-documents/oop-iframes).)\n\nCombining promises with generators enables *asynchronous* iteration. Normally the runtime will pull a new value off a generator at sixty times a second; however, if a generator yields a promise, the next value won’t be pulled until the promise resolves. For example, here’s a counter that increments only about once per second:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":482,"value":"seconds = {\n let i = -1;\n while (true) {\n yield new Promise(resolve => {\n setTimeout(() => {\n resolve(++i);\n }, 1000);\n });\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":485,"value":"md`(Did you know you’ve been reading this notebook for ${seconds} seconds? Well, now you do.) There’s also a builtin \\`Promises\\` object for common promise implementations. For example, the above can be rewritten like so:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":486,"value":"{\n let i = -1;\n while (true) {\n yield Promises.delay(1000, ++i);\n }\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":456,"value":"md`## Implementing user interfaces with generators.\n\nA powerful application of asynchronous generators is to represent the state of a user interface: for example, a range input (a slider) can be represented as an asynchronous sequence of values where a new value is yielded whenever the slider is moved.\n\nHowever, a challenge in implementing these generators is that DOM events are *push*-based: elements emit events whenever they like. Generators in contrast are *pull*-based: the runtime demands the next value in the sequence from the generator. Fortunately we can easily adapt push-based emitters (or “observables”) to pull-based generators using the built-in Generators.observe.\n\nHere’s a counter using an interval:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":501,"value":"Generators.observe(change => {\n let i = -1;\n let interval = setInterval(() => change(++i), 1000);\n return () => clearInterval(interval);\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":504,"value":"md`Similarly, here’s a range input followed by a generator observing its value:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":505,"value":"input = html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":507,"value":"Generators.observe(change => {\n const listener = () => change(input.valueAsNumber);\n input.addEventListener(\"input\", listener);\n change(input.valueAsNumber); // Report the initial value.\n return () => input.removeEventListener(\"input\", listener);\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":512,"value":"md`Since observing input elements is so common, there’s a built-in Generators.input that is a generalization of the above pattern. It works with a variety of input types, including drop-down menus, textareas, checkboxes and buttons. You can also use it on arbitrary DOM elements by dispatching custom events. For example, here’s a slider that shows its current value directly:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":833,"value":"hue = {\n const form = html`

\n \n`;\n form.oninput = () => form.value = form.out.value = +form.in.value;\n form.oninput(); // Set the initial value.\n return form;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":513,"value":"Generators.input(hue)","pinned":true,"hidden":false,"mode":"ojs"},{"id":157,"value":"md`Custom inputs can yield arbitrary values too—not just strings and numbers. For example, a histogram chart might allow brushing, where the brushed data is then exposed to other cells to drive coordinated views. Go nuts!\n\nIn the above examples, separate cells are used to define the user interface (such as a slider) and the corresponding value that is exposed to the notebook. Since this is such a common need, the \\`viewof\\` operator provides convenient syntax for simultaneously defining both the user and programming interface of a cell. It is simply shorthand for Generators.input.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":525,"value":"viewof foo = html``","pinned":true,"hidden":false,"mode":"ojs"},{"id":526,"value":"foo","pinned":true,"hidden":false,"mode":"ojs"},{"id":1004,"value":"md`If needed, you can reference the user interface from another cell as \\`viewof foo\\`. For example:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1005,"value":"(viewof foo).tagName","pinned":true,"hidden":false,"mode":"ojs"},{"id":176,"value":"md`## Notebooks can import other notebooks.\n\nTODO \\`import\\` syntax.\n\nTODO \\`import {…} with\\` syntax.`","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W20","stdlib":"1"}

\n \n ° hue\n