31:T622,md`## Views Views are main UI concept on Observable. Views *usually* wrap a value with an interactive DOM representation of that value. There is lots of existing documentation on the mechanics of them e.g. [introduction to views](https://observablehq.com/@observablehq/introduction-to-views). This document is about how we use and combine them for a scalable development workflow. Because Observablehq has formalized the view interface, we can write a helper that takes multiple views and combines them together to create new views. This is one way we can scale UI development -- hierarchical composition of views. We discuss using the _view-literal_ which embeds multiple sub-views within plain HTML to construct composite views. It is a powerful technique that allows divide and conquer UI development problem solving. To show the technique in a practical settings, we have a annoteted example of porting a fully featured React calculator by Michael Jackson (Redux, UNPKG) _'one step at a time'_. Views do not have to be visual though! Views are able to listen, manipulate and update their inner value, as such, views are logically **a pointer to mutable data**. We can use this framing to build non-visual Data APIs out of views. Multiple views can be connected into a data processing graph using _bind_, and we can exploit this to factor out common business logic into pluggable Data APIs. Data APIs help us delivery cross cutting features to views "from the outside" and avoid repetition inside our UI implementations, further scaling UI development. `32:T642,md`### Nesting views with the [view literal](https://observablehq.com/@tomlarkworthy/view) We should strive to build custom things out of high quality reusable base pieces. This scales because we get to amortize the development cost of the base pieces, and so, we can afford to spend more time polishing them because they will be used a lot. As a result, overall quality increases. This is the heirarchical approach. We can create custom views by composing nested child views. Furthermore, this is recursive, a custom view is itself a view, and there can participate as a child view in an another composed view. But what properties should a composite view have? 1. You should be able to read/write the values of the child views via an index. 3. Emitted events by the child views update the containing view too. (propagation) 4. The containing view itself is read/write too, and its value is the composition of its children. The view literal uses the _'Object'_ as the abstraction for containing child views. Each child view has a key to index its logical position in the whole. This defines the data access model. But the other important thing is defining the layout. How should child components be arranged in the DOM? For this we reuse HTML. The position of child views is specified within a DOM using template tagging. The view literal is a wrapper around the hypertext-literal. So, using the view literal, you can make custom views by nesting simpler views using the view literal. It supports layout with HTML, and supports binding to nested subviews interpolating _[key, view]_ arguments. `33:T1154,controlling_views = md`--- ### Controlling Views Another scalability feature of views is that you can automate them from adjacent cells. This means you can can add features to views with code hosted *outside* of the view implementation. This is a powerful technique for reusability, as generic features can be added to *all* views in existence, even those not authored by the feature developer. View have several nice properties for orchistration. 1. reference a value 2. provide a visual read/write interface to it 3. provide a programmatic read/write interface to it Features (think making a network call) could be implemented both inside and outside of a view implementation. If you have a feature that could be applied to *all* views, like persistence, or animation, consider implementing it externally. Views are very flexible on how you can read/write from them, supporting event driven and polling paradigms. Here are some of the ways. ${htl.html`

`} #### Listen to changes ~~~js // Adds a dependancy on the dataflow graph which will // auto-reevaluate the containing cell if myData changes myData ~~~ #### Read the value ~~~js // Read the value imperatively viewof myData.value ~~~ #### Listen to an input event from the view ~~~js // Get notified of changes but outside of dataflow viewof myData.addEventListener('input', (evt) => ...) ~~~ #### Write the value ~~~js // Writes but does not trigger dataflow viewof myData.value = newValue ~~~ #### Notify Dataflow engine of change ~~~js // Writes but does not trigger dataflow viewof myData.dispatchEvent(new Event('input', { bubbles: true })) ~~~ As you can see you have many different ways of reading and writing to the data in a view. You can choose to participate or not in Dataflow when doing so. It is the variety of semantics that give views special powers in Observable. Views are strictly more powerful than cells connected with dataflow, for example, they can be connected in cycles. (of course, no free lunch, they are harder to work with and debug than dataflow cells) However, there is also some other important functional constructs that are available when reading from one view and writing to another view. #### 2-way binding for synchronization Two views can be [synchronized](https://observablehq.com/@mbostock/synchronized-views) with a 2-way binding. ~~~js Inputs.bind(target, source, [optional]invalidation) ~~~ Its not totally symmetrical because input events are not raised on target when the source changes. The intent is that their is some global authority called source, which you must base all dataflow off of, like so: ${dot`digraph G { s[label="source"]; t1[label="target1"]; t2[label="target2"]; t3[label="target3"]; s -> t1 s -> t2 s -> t3 }`} So if a single target changes, source is notified and it raises its own event and radiates the changes to all targets. If source is directly manipulated all targets update too. Thus everything stays syncronized. You might want to do this if each _target_ offers a different way of presenting or manipulating some common underlying data. I often think of keyboard vs. mouse controls or visual vs. textual diagram representation as situations where I might use a 2-way bind. If you have two (or more) "peer" visualizations that need syncronizing, you may need to create a synthetic ancestor to be the common data holder. [Inputs.input](https://github.com/observablehq/inputs#inputsinputvalue) is a good choice as it non-visual. #### 1-way binding for chaining I found when composing views a drawback of the 1.5-way binding is it cannot do *partial* binding. The source has to be the complete truth and the targets are isomorphic to that truth. In reality, when building views up heirarchically, views become about one segment of a thing, and its useful to propagate mutated changes between them. So I added another type of bind intended for application wiring ~~~ bindOneWay(target, source, {invalidation, transform}) ~~~ This has a clear direction of data flow and the ability to transform allows dissimilar views to be combined with a type converter (e.g. toggling visibility, a boolean, from a radio button) ${dot`digraph G { v0; v1; v2; v0 -> v1 [label="transform"]; v1 -> v2 [label="transform"]; }`} `34:T4d6,md`### Creating Reusable Views Views are only composable if they are built in a certain way. There is a notebook dedicated to the rules required [(@tomlarkworthy/ui-guidelines)](https://observablehq.com/@tomlarkworthy/ui-guidelines). I draw attention to two of the commonly forgotten features here though. #### Back-writability *Input.bind* only works if the views support *back writability*. That is, that writing the value back into the component updates the UI. The following code should visually update the view, but not trigger Dataflow. ~~~js viewof myView.value = newValue; ~~~ The following code should trigger Dataflow with a freshly written value ~~~js viewof myView.dispatchEvent(new Event('input', {bubbles: true})); ~~~ _*Back writability enables external orchistration, binding and composing into views-as-services.*_ #### _input_ events should bubble When dispatching _input_ events, you should set \`{bubbles: true}\`. This is because native \`\` do this, and it allows the even to propogate up the DOM hierarchy. This feature is exploited by the view literal to detect changes in subviews (which are DOM children). Event bubbling is essential for view reuse through nesting. `35:T9ac,md`### State based views In addition to composing views *heirarchically* but there is another important class of UI which changes based on state. For example, you might want a login form to be foremost when the user is not logged in, otherwise let them access the application. Or you might only want to show the contents of the menu tab that is currently 'active'. One common approach in HTML is to switch content with \`display: none\`, but this requires knowing all your content permutations upfront, which is often not possible. We can do that style of state based UI using techniques described with *[showable](https://observablehq.com/@tomlarkworthy/ui-development#showableText)*. Flipping \`display: none\` does not scale to complex UIs though, for these we need a way of lazily updating the DOM based on some state. #### mutable prevents composition One common pattern in Observable is extracting the state into a \`mutable\` variable, but this has several drawbacks. - Mutating the mutable causes a Dataflow cascade to rebuild the DOM, and in turn, any dependents of the viewof are also invalidated, so it can be quite computationally intensive and impossible to contain afterwards. - If the mutable is manipulated via other cells, they need to be imported too by dependent notebooks otherwise the logic does not work. I made this mistake with [oauth](/@tomlarkworthy/oauth). If you look at the [oauth-examples](/@tomlarkworthy/oauth-examples) each has to import two things for the state machine to work. Because dataflow is acyclic it is not possible for a mutable to depend on its downstream logic... there is no way of simplifying this. All-in-all, mutables end up constraining long term. 🤮 #### [viewroutines](https://observablehq.com/@tomlarkworthy/viewroutine) (coroutines) _Viewroutines_ are a solution for lazily updating a DOM node without involving dataflow. They are a _view_ that holds a reference to another _view_ called _current_. Their presentation is a \`span\` but whose value is the _current value_ and the \`span\` only child is current presentation. So basically they just delegate all state to their child view. The novel thing is how _current_ is updated. Unlike a normal view, whose internals are mutated externally, a viewroutine is instantiated with an async generator. It yields either 'events' or 'view' which are dispatch or grafted on the DOM. The amazing thing about generators is they can be composed and hold state. `36:T6f9,md`#### AutoScalingText View The calculator display is quite interesting in that the font gets smaller *when needed* so the text fits. Michael Jackson isolated the text resizing behavior into its own reusable component (AutoScalingText) for use in the Calculator Display. Lets follow those same design decisions. Here is the original source code ~~~js class AutoScalingText extends React.Component { state = { scale: 1 }; componentDidUpdate() { const { scale } = this.state const node = this.node const parentNode = node.parentNode const availableWidth = parentNode.offsetWidth const actualWidth = node.offsetWidth const actualScale = availableWidth / actualWidth if (scale === actualScale) return if (actualScale < 1) { this.setState({ scale: actualScale }) } else if (scale < 1) { this.setState({ scale: 1 }) } } render() { const { scale } = this.state return (

this.node = node} >{this.props.children}

) } } ~~~ Michael Jackson's scale is a state, we create a "variable" to hold this extra degree of freedom. This lets us test our scaling code by assigning to scale manually. A variable has a special event when it is assigned to, allowing you to update appearances without side effects for dataflow (that an input event would). When our scale variable changes, we make sure to adjust the DOM's transform attribute. We also want the scale to update when the child text node updates. We create a TextNodeView whose value is the text. And we bind text changes to scale changes, where we fit in the rescaling logic. `37:T62f,autoScalingText = ({ child } = {}) => { const scale = variable(1, { name: "scale" }); const node = view`

${['scale', scale]} ${['child', child]}

`; // If we change scale we want the div style.transform changed scale.addEventListener("assign", evt => { node.style.transform = `scale(${scale.value},${scale.value})`; }); scale.value = 1; const updateScale = () => { const parentNode = node.parentNode; if (!parentNode) return 1; const availableWidth = parentNode.offsetWidth; const actualWidth = node.offsetWidth; const actualScale = availableWidth / actualWidth; // In mjackson example there is a case that returns with no value to avoid a call to setState. // This is coz this code is executed in React's ComponentDidUpdate which is done after // placing the DOM node. This path is for concluding there is nothing to be done, otherwise, // it calls setState causing another DOM adjsut and place loop // Because in Observable we have to call dispatchEvent after setting the component, this code // executes after placement kinda naturally. if (actualScale < 1) { return actualScale; } else if (scale <= 1) { return 1; } }; // When the child updates we want to change the scale, so we bind child -> scale with a transform bindOneWay(scale, child, { transform: updateScale }); return node; }38:T6d7,md`#### Calculator Display View Micheal's calculator display wraps an AutoFormattingText field and - applies additional locale specific formatting to give you easy-to-read numbers. - Truncates the digits to a sane level to sidestep some floating point weirdness. - Adds a trailing 0 for decimals. So the input is a floating point value and the output is a formatted string written to a child AutoScalingText custom component (which we developed earlier). Here is the React source: ~~~js class CalculatorDisplay extends React.Component { render() { const { value, ...props } = this.props const language = navigator.language || 'en-US' let formattedValue = parseFloat(value).toLocaleString(language, { useGrouping: true, maximumFractionDigits: 6 }) // Add back missing .0 in e.g. 12.0 const match = value.match(/\\.\\d*?(0*)$/) if (match) formattedValue += (/[1-9]/).test(match[0]) ? match[1] : match[0] return (

{formattedValue}

) } } ~~~ Our general strategy is similar to the implementation to AutoFormattingText, we need a variable to hold the 'value' parameter, then we oneWayBind to the underlying AutoFormattingText field after making the required business logic modifications. Michael's CalculatorDisplay uses information hiding so the only accessible parameter is the DOM value of the custom component, which is a string type. We will follow this pattern and hide the AutoFormattingText input from the API too, though as we are not creating custom components we will not be insisting the value parameter to be a string (though it can be). `39:Tfb5,calculatorLogic = calculatorView => { // Internal state let value = null; let operator = null; let waitingForOperand = false; const calculatorOperations = { '/': (prevValue, nextValue) => prevValue / nextValue, '*': (prevValue, nextValue) => prevValue * nextValue, '+': (prevValue, nextValue) => prevValue + nextValue, '-': (prevValue, nextValue) => prevValue - nextValue, '=': (prevValue, nextValue) => nextValue }; // To reduce the amount of code we need to change for the port, we supply our own setState // and have our handlers use function syntax so "this" works, although it would not be the // style I would choose doing it fresh. function setState(state) { if (state.displayValue) { calculatorView.displayValue.value = state.displayValue; calculatorView.displayValue.dispatchEvent( new Event('input', { bubbles: true }) ); } if (state.value) value = state.value; if (state.operator) operator = state.operator; if (state.waitingForOperand !== undefined) waitingForOperand = state.waitingForOperand; } function clearAll() { setState({ value: null, displayValue: '0', operator: null, waitingForOperand: false }); } function clearDisplay() { setState({ displayValue: '0' }); } function clearLastChar() { const displayValue = `${calculatorView.value.displayValue}`; setState({ displayValue: displayValue.substring(0, displayValue.length - 1) || '0' }); } function toggleSign() { const displayValue = `${calculatorView.value.displayValue}`; const newValue = parseFloat(displayValue) * -1; setState({ displayValue: String(newValue) }); } function inputPercent() { const displayValue = `${calculatorView.value.displayValue}`; const currentValue = parseFloat(displayValue); if (currentValue === 0) return; const fixedDigits = displayValue.replace(/^-?\d*\.?/, ''); const newValue = parseFloat(displayValue) / 100; setState({ displayValue: String(newValue.toFixed(fixedDigits.length + 2)) }); } function inputDot() { const displayValue = `${calculatorView.value.displayValue}`; if (!/\./.test(displayValue)) { setState({ displayValue: displayValue + '.', waitingForOperand: false }); } } function inputDigit(digit) { const displayValue = `${calculatorView.value.displayValue}`; if (waitingForOperand) { setState({ displayValue: String(digit), waitingForOperand: false }); } else { setState({ displayValue: displayValue === '0' ? String(digit) : displayValue + digit }); } } function performOperation(nextOperator) { const inputValue = Number.parseFloat(calculatorView.value.displayValue); if (value == null) { setState({ value: inputValue }); } else if (operator) { const currentValue = value || 0; const newValue = calculatorOperations[operator](currentValue, inputValue); setState({ value: newValue, displayValue: String(newValue) }); } setState({ waitingForOperand: true, operator: nextOperator }); } const handleKeyDown = event => { let { key } = event; if (key === 'Enter') key = '='; if (/\d/.test(key)) { inputDigit(parseInt(key, 10)); } else if (key in calculatorOperations) { performOperation(key); } else if (key === '.') { inputDot(); } else if (key === '%') { inputPercent(); } else if (key === 'Backspace') { clearLastChar(); } else if (key === 'Clear') { if (this.state.displayValue !== '0') { clearDisplay(); } else { clearAll(); } } }; return { setState, clearAll, clearDisplay, clearLastChar, toggleSign, inputPercent, inputDot, inputDigit, performOperation, handleKeyDown }; }3a:Tb0c,calculator = ({ className = '', displayValue = '0' } = {}) => { // We will bind all keys to lastKey, so we can have a single handler const lastKey = variable(undefined, { name: "lastKey" }); const placeKey = (className, label) => { const key = calculatorKey({ className, label }); // To have a single handler we will bind everthing to lastKey bindOneWay(lastKey, key, { transform: d => { return d; } }); return key; }; const ui = view`

${['displayValue', calculatorDisplay()]}

${['lastKey', lastKey]}

${placeKey("key-clear", "AC")} ${placeKey('key-sign', "±")} ${placeKey('key-percent', "%")}

${placeKey('key-0', "0")} ${placeKey('key-dot', "●")} ${placeKey('key-1', "1")} ${placeKey('key-2', "2")} ${placeKey('key-3', "3")} ${placeKey('key-4', "4")} ${placeKey('key-5', "5")} ${placeKey('key-6', "6")} ${placeKey('key-7', "7")} ${placeKey('key-8', "8")} ${placeKey('key-9', "9")}

${placeKey('key-divide', "÷")} ${placeKey('key-multiply', "×")} ${placeKey('key-subtract', "-")} ${placeKey('key-add', "+")} ${placeKey('key-equals', "=")}

`; // Now add business logic const logic = calculatorLogic(ui); lastKey.addEventListener('input', () => { let match = undefined; if ((match = /^key-(\d)$/.exec(lastKey.value))) { logic.inputDigit(Number.parseInt(match[1])); } switch (lastKey.value) { case 'key-dot': return logic.inputDot(); case 'key-clear': return logic.clearAll(); case 'key-sign': return logic.toggleSign(); case 'key-percent': return logic.inputPercent(); case 'key-divide': return logic.performOperation('/'); case 'key-multiply': return logic.performOperation('*'); case 'key-subtract': return logic.performOperation('-'); case 'key-add': return logic.performOperation('+'); case 'key-equals': return logic.performOperation('='); } }); // Add keyboard document.addEventListener('keydown', logic.handleKeyDown); invalidation.then(() => document.removeEventListener('keydown', logic.handleKeyDown) ); // initialize logic.setState({ displayValue: displayValue }); return ui; }3b:T9f8,styledCalculator = value => { return view`

${[ '...', calculator({ className: "styledCalculator", displayValue: value }) ]}`; }3c:[{"id":"b39d31ad383fa10c5763b3b1b84aee160c158b195cea2db64c6008f9f2d9b802da46b6de1795d7f8017fc64c1a326585ee23e760cbad50a200a05d61475916ee","href":"https://static.observableusercontent.com/files/b39d31ad383fa10c5763b3b1b84aee160c158b195cea2db64c6008f9f2d9b802da46b6de1795d7f8017fc64c1a326585ee23e760cbad50a200a05d61475916ee","name":"Dataflow Vs. Views.png","type":"image/png","lastModified":1626460785824.81,"size":205268},{"id":"6ec72184962d04f326bab431bf484211e5a5d9c187700871d886b1943c768d25c7b32a9137d78824871947afbde7517759b22129f1e6f579ea30fd37bcaa02d7","href":"https://static.observableusercontent.com/files/6ec72184962d04f326bab431bf484211e5a5d9c187700871d886b1943c768d25c7b32a9137d78824871947afbde7517759b22129f1e6f579ea30fd37bcaa02d7","name":"image.png","type":"image/png","lastModified":1625680566366.556,"size":741226},{"id":"9d28efebbcee6072d3b0107451061c7f40e2781298345c5405e1f230226868cd108fdb684f55f544e8b4eb4cc7c987aaca7d253106829a93ac904fa2cd4995e6","href":"https://static.observableusercontent.com/files/9d28efebbcee6072d3b0107451061c7f40e2781298345c5405e1f230226868cd108fdb684f55f544e8b4eb4cc7c987aaca7d253106829a93ac904fa2cd4995e6","name":"image@1.png","type":"image/png","lastModified":1626690493024.72,"size":11221}] 2f:{"title":"Scaling User Interface Development","cells":[{"id":0,"value":"md`# Scaling User Interface Development\n\nBackend development is [_rapid_](https://observablehq.com/@tomlarkworthy/saas-tutorial), and yet... custom user interface development is *still* a huge timesink. UI development is a project bottleneck.\n\n

\n\nThis living document is a growing list of techniques I have learnt trying to overcome the UI development bottleneck. When I create complex applications, I need contextually sensitive user interfaces. However, building these custom UIs felt like starting from scratch everytime and the effort required was too high!\n\nSo I embarked on a journey, distilling the learnings taken from the community, trying to figure out the best way to build UIs in a scalable way on the ObservableHQ platform. And here is what I have learnt so far.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":63,"value":"toc()","pinned":false,"hidden":false,"mode":"ojs"},{"id":122,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":1956,"value":"viewof output = {\n // we will make this construction 🎵sing🎵\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1430,"value":"md`### Off the shelf views\n\nYou can save time by reusing what the community has already built. Don't reinvent the wheel! There are some great input collections already authored, though note, for inputs to be truly flexible they need to be [back-writable](https://observablehq.com/@tomlarkworthy/ui-guidelines#backwritable). Thiss unfortunately excludes [@jashkenas/inputs](/@jashkenas/inputs) and [@bartok32/diy-inputs](/@bartok32/diy-inputs) UI packs.\n\n- [Observable Inputs](https://observablehq.com/@observablehq/inputs) is the goto for a large range of use cases\n- [Data Editor](https://observablehq.com/@tomlarkworthy/dataeditor) is also very hackable for data entry\n\n\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1473,"value":"md`However, even the best UI components on Observable are, by default, not contextually sensitive. To build compelling user experiences you need to simplify and minimize unnecessary information... In other words, you need the minimal user interface that makes sense for where the user currently is. At a minimum, you at least need to hide controls when they are not relevant, but also you want to help the user prioritize through styling, and it should be driven by what the user is currently doing.\n\nThis is not possible with default **off-the-shelf components**. However, we **can** reuse the components as **building blocks** in contextually sensitive UIs. So its very important to memorize the off-the-shelf components as they will save a lot of time and help you scale your development budget further. \n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2161,"value":"#### Customizing with *juice*\n\nJuice is a higher order function that helps existing UI components go a little further. A common issue is that Inputs.select does not have dynamic options, with juice you can move configuration parameters like *options* into the value, enabling you to drive the select options from other components without dataflow and therefore within a single cell.\n","pinned":false,"hidden":false,"mode":"md"},{"id":2177,"value":"import { juice } from \"@tomlarkworthy/juice\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":2173,"value":"dynamicSelect = juice(Inputs.select, {\n options: \"[0]\", // \"range\" is first arg (index 0), the min is the 1st arg of the range array\n result: \"[1].value\" // \"result\" can be set in the options.value, options being the 2nd arg (index 0)\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":2180,"value":"viewof exampleSelect = dynamicSelect([], { label: \"play a card\" })","pinned":false,"hidden":false,"mode":"ojs"},{"id":2174,"value":"Inputs.button(\"deal\", {\n reduce: () => {\n const rndCard = () => {\n const card = Math.floor(Math.random() * 52);\n return (\n [\"1\", \"2\", \"3\", \"4\", \"5\", \"6\", \"7\", \"8\", \"9\", \"10\", \"J\", \"Q\", \"K\", \"A\"][\n card % 14\n ] + [\"♠\", \"♥\", \"♦\", \"♣\"][Math.floor(card / 14)]\n );\n };\n viewof exampleSelect.options.value = [rndCard(), rndCard()];\n viewof exampleSelect.options.dispatchEvent(new Event(\"input\"));\n }\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":175,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":185,"value":"viewof combinedView = view`

\n \n

Simple Nested View Example

\n \n \n ${['x', Inputs.range([-10, 10], { label: \"x\" })]}\n ${['y', Inputs.range([-10, 10], { label: \"y\" })]}\n \n \n ${['a', Inputs.button(\"a\")]} \n ${['b', Inputs.button(\"b\")]}\n \n

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":221,"value":"md`The differene data binds tell the view how to assemble its composite value. Note this is a reactive two way binding!`","pinned":false,"hidden":false,"mode":"ojs"},{"id":225,"value":"combinedView","pinned":true,"hidden":false,"mode":"ojs"},{"id":227,"value":"md`If you need to access the subviews (e.g. to bind to, or to dispatch events), the view itself is also a composite component`","pinned":false,"hidden":false,"mode":"ojs"},{"id":229,"value":"viewof combinedView","pinned":true,"hidden":false,"mode":"ojs"},{"id":231,"value":"md`So you can demultiplex the composite at any time if needed`","pinned":false,"hidden":false,"mode":"ojs"},{"id":234,"value":"Inputs.bind(\n Inputs.range([-10, 10], {\n label: \"This is bound to just part of the UI above\"\n }),\n viewof combinedView.x\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":246,"value":"md`Note you can nest this view in another view-literal and build up components hierarchically. If I am doing it this way I usually create views builder functions so its reusable.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1267,"value":"md`#### Wrapping existing views with a singleton\n\nSometimes you want to just add some custom HTML to an existing view, because it nearly does what you want - but not quite. For example, with \\`Inputs.range\\` I really like the hidden arrow buttons and keyboard controls, but the slider part can add too much horizontal when I embed it in a table. I want the range but without a slider!\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1525,"value":"Inputs.range()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1519,"value":"md`In this case we want to put some custom HTML around a single view but otherwise leave the logic in place. We don't want to create a new view by nesting, so instead of binding a subview to a named key, we use a special _spread_ key to tell the enclosing view to pull the child's value up.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1738,"value":"md`##### Natural Number Singleton Example\n\nFor our example, lets modify the default _range_ to remove the slider with some CSS, and fix its step to be in increments of 1. If course, this new view works like a normal view so you can bind to it. It is currently: **${naturalNumExample}**`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1274,"value":"naturalNumber = options =>\n view`

${[\n '...', // Note the '...' moves the binding up to not being a child view\n Inputs.range([0, 999999999], { value: 0, ...options, step: 1 })\n ]}`","pinned":true,"hidden":false,"mode":"ojs"},{"id":1278,"value":"viewof naturalNumExample = naturalNumber()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1741,"value":"naturalNumExample","pinned":true,"hidden":false,"mode":"ojs"},{"id":1748,"value":"md`#### Adding collections of child views\n\nFor some controls the number of children is not fixed (e.g. a list or table). The view-literal supports passing an array of views as its 2nd arg e.g. _[\"key\", [...]]_ for constructing collections\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1775,"value":"md`##### Simple Row Component\n\nLets start by creating a simple row component that is wrapped in a \\`

\\`. As we only have one control in this simple example it doesn't make sense binding to a subview key and so instead we create a singleton using the spread key (see previous section)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1764,"value":"row = value => view`

${[\"...\", Inputs.text({ value })]}

`","pinned":true,"hidden":false,"mode":"ojs"},{"id":1767,"value":"viewof exampleRow = row()","pinned":true,"hidden":false,"mode":"ojs"},{"id":1773,"value":"exampleRow","pinned":true,"hidden":false,"mode":"ojs"},{"id":1788,"value":"md`##### Static list of children views\n\nYou can create an array of row components you can assign the whole array a property name and this is bidirectionally attached to the parent\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1794,"value":"viewof staticListExample = view`

${c1 /*Vanilla htl binding, does not link the subview*/}

${c2}${c3}

\n ${[\n '_...', // Binding children via an object collection, but not changing their DOM location\n {\n a: c1,\n b: c2,\n c: c3\n }\n ]}

${[\"show\", showVariable]}${[\"child\", child]}`;\n\n // The showable logic is to toggle the visibility of the enclosing div based\n // on the show variable state\n const updateDisplay = () => {\n if (showVariable.value) {\n showable.style.display = \"inline\";\n } else {\n showable.style.display = \"none\";\n }\n };\n // Variables have additional assign event so presentation can be\n // updated as soon as variables change but before dataflow\n // because this is a pure presentation state it makes sense not to trigger\n // dataflow so we do not use 'input' event\n showVariable.addEventListener(\"assign\", updateDisplay);\n\n updateDisplay();\n return showable;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1170,"value":"viewof exampleShowable = createShowable(Inputs.text())","pinned":true,"hidden":false,"mode":"ojs"},{"id":2071,"value":"Inputs.button(\"toggle show\", {\n reduce: () => {\n // note changing this updates immediately and without dataflow because of assign event\n exampleShowable.show = !exampleShowable.show;\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1192,"value":"md`Now we can build a custom view that has a radio to reveal the text box, and we will wire the textbox to a result variable which will be the only output of the entire view`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1227,"value":"yesAnd","pinned":false,"hidden":false,"mode":"ojs"},{"id":1198,"value":"viewof yesAnd = {\n const prompt = Inputs.radio([\"no\", \"yes\"], { label: \"answer?\", value: \"no\" });\n const answer = createShowable(\n Inputs.text({ placeholder: \"well write your answer here\" })\n );\n const result = variable(undefined);\n\n bindOneWay(answer.show, prompt, {\n transform: ans => ans === 'yes' // Convert radio text to boolean\n });\n\n // The result needs to update if the toggle or the text changes\n bindOneWay(result, answer.child, {\n transform: text => (answer.show.value ? text : \"no answer\")\n });\n bindOneWay(result, answer.show, {\n transform: show => (show ? answer.child.value : \"no answer\")\n });\n\n return view`

\n ${prompt}\n ${answer}\n \n ${[\"...\", result]} \n `;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1294,"value":"### Views-as-services\n\nViews do not need to be UI. They can also be used to supply services.\n\nNote that\n- Views can be synced with other views very easily using _bind_\n- Views do not need to be DOM nodes, only an eventEmitter\n- Views are readable and writable holders of data\n\nI sometimes think that views are pointers-like, they hold a named reference to a fixed read/write data address. They have a uniform API for read/write, listen/notify and are dynamically typed. \n\nThus, they can be quite general service abstractors, supporting bidireciton dataflow, event driven interfaces or polling based interfaces.\n\nYou can use views to adapt other APIs for use within Observable. Furthermore, because there is a generic method for binding views together, you can plugin data driven features without modifying the data owner.\n","pinned":false,"hidden":false,"mode":"md"},{"id":1318,"value":"md`#### Example: Web Storage API as a View \n\nYou can often take an existing API, such as the Web Storage API, and wrap it in a view. This can adapt that service to work idiomatically with Observable. \n\nIf pointers/addresses to data, it makes sense that a storage key in the Web API should map to a unique view.\n\nThis leads us to be able to create an Observable view for a local storage location, if a key is provided.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1344,"value":"md`##### createStorageView`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1327,"value":"createStorageView = key => {\n const ui = htl.html`

${key}\n

`;\n return Object.defineProperty(ui, 'value', {\n get: () => localStorage.getItem(key),\n set: value => {\n localStorage.setItem(key, value);\n },\n enumerable: true\n });\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1348,"value":"md`When we create a storage view we say what key to use`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1333,"value":"viewof exampleStorageView = createStorageView(\"exampleStorageKey\")","pinned":true,"hidden":false,"mode":"ojs"},{"id":1337,"value":"exampleStorageView","pinned":true,"hidden":false,"mode":"ojs"},{"id":1351,"value":"md`And we can manually write into it in a generic way and the value updates. More interestingly, if we refresh the page the last value written is remembered.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1341,"value":"Inputs.button(\"write random value\", {\n reduce: () => {\n viewof exampleStorageView.value = Math.random();\n viewof exampleStorageView.dispatchEvent(\n new Event('input', { bubbles: true })\n );\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1357,"value":"md`##### Binding views to services\n\nThe power of services-as-views is that you can very neatly add these services to existing views through bind composition.\n\nSo if we want a range slider's value to be persisted through refreshes, we bind it to our storage view.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1365,"value":"viewof persistedRange = Inputs.bind(\n Inputs.range(),\n createStorageView(\"rangeStoragekey\")\n)","pinned":true,"hidden":false,"mode":"ojs"},{"id":1367,"value":"persistedRange","pinned":true,"hidden":false,"mode":"ojs"},{"id":1369,"value":"md`Note the above value survives page refreshes!\n\n#### Summary of views-as-services\n\nSo note we have taken an existing view, *range*, and added persistence, without modifying the original (which was developed by a different person). \n\nThe views-as-a-service paradigm is another way to **scale** UI development. We can avoid trying to create god UI components that have every feature. Instead, we can build orthogonal features that can be mixed and matched.\n\n

\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1381,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":1503,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":1575,"value":"import { viewroutine, ask } from '@tomlarkworthy/viewroutine'","pinned":false,"hidden":false,"mode":"ojs"},{"id":1608,"value":"md`Lets start simple with an n-sided dice. The generator returns random presentations, but its not until the final yield a DOM object is returned with a value.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1578,"value":"rollDice = (sides, andThen) =>\n async function*() {\n const start = Date.now();\n let val = undefined;\n while (Date.now() < start + 1000) {\n val = Math.floor(Math.random() * sides) + 1;\n yield md`${val}`; // Not a view so its value is \"undefined\"\n await Promises.delay(16); // 16ms\n }\n // final value should be the dice AND the value\n const final = md`${val}`;\n final.value = val;\n yield final;\n yield new Event('input', { bubbles: true }); // Notify the value has changed\n await andThen;\n }","pinned":true,"hidden":false,"mode":"ojs"},{"id":1620,"value":"viewof reroll = Inputs.button(\"roll again\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":1582,"value":"viewof diceVal = (reroll, viewroutine(rollDice(6, invalidation)))","pinned":true,"hidden":false,"mode":"ojs"},{"id":1613,"value":"diceVal","pinned":true,"hidden":false,"mode":"ojs"},{"id":1627,"value":"md`#### Composing viewroutines\n\nWhats nice about generators is that they compose with _\\yield\\*_, so we can take our simple dice primitive and turn it into a loop. There is a helper shipped with _viewroutine_ called _ask_ which is a generator that wraps a view, and waits until the view emits a value before returning. Its a useful primitive for blocking from user input. We will use *ask* and *dice* generators, and off-the-shelf input *radio*, to create a view of a general purpose dice roller.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1634,"value":"viewof nDice = viewroutine(async function*() {\n let sides = 6;\n while (true) {\n sides = Number.parseInt(\n yield* ask(\n Inputs.radio([\"2\", \"4\", \"6\", \"8\", \"10\", \"20\"], {\n label: \"Roll a dice with how many sides?\"\n })\n )\n );\n yield* rollDice(sides)();\n await Promises.delay(1000);\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":1667,"value":"nDice","pinned":true,"hidden":false,"mode":"ojs"},{"id":1676,"value":"md`As you can see a viewroutine composes and can be mixed with pre-existing views quite easily. It provides us with an orthogonal tool to the view-literal by composing reusable views temporally. Read more about it in its own [notebook](https://observablehq.com/@tomlarkworthy/viewroutine).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":254,"value":"md`## Porting Micheal Jackson's React Calculator\n\nIn this section we make a non-trivial application in testable small peices that are joined together later. This demonstrates a scalable development workflow. We predominantly use the heirarchical approach.\n\nMicheal Jackson (creator of Redux, Unpkg) has a fairly stellar implementation of a [calculator using React on Codepen](https://codepen.io/mjijackson/pen/xOzyGX). So we can reimplement that and see how it differs to React. \n\n${tweet(\"759039237412958209\")}\n\nHopefully you will see that in many ways, Observeble has a better workflow. Lets go!\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":288,"value":"md`#### Calculator Key\n\nIn the React example a custom Element is used with a custom event type _press_. \n\n~~~html\n this.inputDigit(0)}>0\n~~~\n\nThis allows the container to bind unique handler for each key that calls a common parameterized handler: _inputDigit(...)_.\n\nIn Observable idioms we don't really want to be thinking of event handlers, rather, we prefer dataflow. We want on a key press that a key's value is emitted as a value of a cell.\n\nThe tricky bit is how to aggregate multiple keys and write to a common handler. We will get to that much later\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":250,"value":"calculatorKey = ({ className, label } = {}) => {\n const view = htl.html``;\n return view;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":1727,"value":"md`#### Test of Calculator Key`","pinned":false,"hidden":false,"mode":"ojs"},{"id":344,"value":"md`So now we instanciate it and check the value is returned as expected in isolation`","pinned":false,"hidden":false,"mode":"ojs"},{"id":275,"value":"viewof multiplyKey = calculatorKey({\n className: \"key-multiply\",\n value: \"MUL\",\n label: \"×\"\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":324,"value":"multiplyKey","pinned":true,"hidden":false,"mode":"ojs"},{"id":351,"value":"$36","pinned":false,"hidden":false,"mode":"ojs"},{"id":359,"value":"$37","pinned":true,"hidden":false,"mode":"ojs"},{"id":589,"value":"md`##### Test of AutoScalingText`","pinned":false,"hidden":false,"mode":"ojs"},{"id":593,"value":"md`We need a very basic view of a text node, its so simple we can do it without special libraries.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":443,"value":"textNodeView = (value = '') => {\n const node = document.createTextNode(value);\n return Object.defineProperty(node, 'value', {\n get: () => node.textContent,\n set: val => (node.textContent = val),\n enumerable: true\n });\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":596,"value":"md`Then we can instanciate an AutoScalingText wrapper around a textNodeView, demonstrating three levels of nesting\n1. The view with a top level DIV of class \"example\", with bound view child \"example\"\n2. The autoScalingText view with two children: 'scale' and 'child'\n3. the textNodeView\n\nThe main power of the view-literal is that the heirarchy retain back-writability. So we can traverse the tree of views, and assign values, and the views will update.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":369,"value":"viewof exampleAutoScalingTextContainer = view`

\n \n ${[\n 'example',\n autoScalingText({\n child: textNodeView(\"press random number below\")\n })\n ]}`","pinned":true,"hidden":false,"mode":"ojs"},{"id":599,"value":"md`We can test the autoscaling behaviour by generating long numbers.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":525,"value":"Inputs.button(\"generate a random long number\", {\n reduce: () => {\n const digits = Math.floor(Math.random() * 100);\n const num = Array(digits)\n .fill(null)\n .reduce(str => str + Math.floor(Math.random() * 10), \"\");\n viewof exampleAutoScalingTextContainer.example.child.value = num;\n viewof exampleAutoScalingTextContainer.example.child.dispatchEvent(\n new Event('input'),\n { bubbles: true }\n );\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":602,"value":"$38","pinned":false,"hidden":false,"mode":"ojs"},{"id":618,"value":"calculatorDisplay = ({ value } = {}) => {\n const valueVariable = variable(value, { name: \"value\" });\n\n const format = val => {\n // Coz in react the value is passed in as an attribute to the component its a string.\n // But we can be flexible and accept both\n const valStr = `${val}`;\n const language = navigator.language || 'en-US';\n let formattedValue = parseFloat(valStr).toLocaleString(language, {\n useGrouping: true,\n maximumFractionDigits: 6\n });\n\n // Add back missing .0 in e.g. 12.0\n const match = valStr.match(/\\.\\d*?(0*)$/);\n\n if (match) formattedValue += /[1-9]/.test(match[0]) ? match[1] : match[0];\n return formattedValue;\n };\n const text = textNodeView();\n\n const ui = view`

\n ${['...', valueVariable]}\n ${autoScalingText({\n child: text\n })}\n

`;\n bindOneWay(text, valueVariable, {\n transform: format\n });\n\n return ui;\n}","pinned":true,"hidden":false,"mode":"ojs"},{"id":977,"value":"md`###### Test of Calculator Display`","pinned":false,"hidden":false,"mode":"ojs"},{"id":619,"value":"viewof testDisplay = view`

\n \n \n ${['...', calculatorDisplay({ value: \"100.0000\" })]}\n`","pinned":true,"hidden":false,"mode":"ojs"},{"id":685,"value":"testDisplay","pinned":true,"hidden":false,"mode":"ojs"},{"id":690,"value":"md`We create a button to set the display value and dispatch an event. We want to check the value is a number (well it ends up stored as a string, but this is consistent with the React example), but the display is formatted in the locale, and that it resizes based on the length of the number`","pinned":false,"hidden":false,"mode":"ojs"},{"id":643,"value":"Inputs.button(\"random value\", {\n reduce: () => {\n const digits = Math.floor(Math.random() * 100);\n const num = Array(digits)\n .fill(null)\n .reduce(str => str + Math.floor(Math.random() * 10), \"\");\n viewof testDisplay.value = num;\n viewof testDisplay.dispatchEvent(new Event('input'), { bubbles: true });\n }\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":348,"value":"md`#### Calculator View\n\nIn the React version the parsing business logic is put inside the Calculator component, but this would result in a huge cell for us so we separate out the parsing and operands first into a business logic SDK (this is almost a copy and paste from the example).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":706,"value":"$39","pinned":false,"hidden":false,"mode":"ojs"},{"id":927,"value":"md`The ui component wraps the business logic. If designing from scratch I would embrace seperation of business logic from presentation by adding the calculator logic via a view-as-a-service. We might consider extracting the calculator logic into its own view as being superior becuase we could then plug calculator logic into very differently organized views and reuse it.\n\nHowever, here I will stick closely to the React example so its easier to make line-to-line corespondances.\n\nThe interesting challange for us is aggregating some of the keys so they can share a handler. \n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":727,"value":"$3a","pinned":true,"hidden":false,"mode":"ojs"},{"id":858,"value":"md`##### Test of Calculator\n\nNote its wired into keyboard too so backspace works\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":714,"value":"viewof testCalculator = calculator({\n displayValue: '0'\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":736,"value":"testCalculator","pinned":true,"hidden":false,"mode":"ojs"},{"id":863,"value":"md`#### The Completed Styled Calculator View\n\nFinally we get to put it all together, we nest it in another view so we can add Michaels CSS inline too (of course this could be hosted in a different cell too). Note how the text resizes as the number gets large.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":874,"value":"$3b","pinned":false,"hidden":false,"mode":"ojs"},{"id":876,"value":"viewof exampleStyledCalculator = styledCalculator(\"1.337\")","pinned":false,"hidden":false,"mode":"ojs"},{"id":898,"value":"exampleStyledCalculator","pinned":false,"hidden":false,"mode":"ojs"},{"id":941,"value":"exampleStyledCalculator","pinned":true,"hidden":false,"mode":"ojs"},{"id":993,"value":"md`##### Backwriting into the Calculator`","pinned":false,"hidden":false,"mode":"ojs"},{"id":905,"value":"md`Note the styled calculator is still backwritable, and therefore scriptable by adjacent cells. Becuase the logic is driven by view binding, the real business logic is able to compute with synthetically injected values!`","pinned":false,"hidden":false,"mode":"ojs"},{"id":908,"value":"Inputs.button(\"set display to random number\", {\n reduce: () => {\n const digits = Math.floor(Math.random() * 20);\n const num = Array(digits)\n .fill(null)\n .reduce(str => str + Math.floor(Math.random() * 10), \"\");\n viewof exampleStyledCalculator.singleton.displayValue.value = num;\n viewof exampleStyledCalculator.singleton.displayValue.dispatchEvent(\n new Event('input'),\n { bubbles: true }\n );\n }\n})","pinned":true,"hidden":false,"mode":"ojs"},{"id":36,"value":"md`## Other techniques\n\nViews are not the only stratergy for building UI.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":39,"value":"md`### Pulling from the React Ecosystem\n\nYou can build a React application from scratch using [@j-f1/react](/@j-f1/react). Unfortunately its not word-for-word React syntax, so you can't trivially copy and paste from the web, and unfortunately, the React ecosystem uses idioms to distribute code, so you can't easily pull in the existing ecosystem.\n\nFurthermore, React has its own dataflow paradigms, which cannot exploit Observable idioms, so sometimes it feels like you have two layers of stuff going on where you should just have one and its very confusing trying to figure out whether a cell is updating becuase of dataflow or React. So overall I feel React is not a great fit technically.\n\nHowever, there are some wonderful react components already built, and sometimes they can save *a ton* of time. With a custom webpack config and some work, *you can import them*, see [@tomlarkworthy/howto-import-react-component](/@tomlarkworthy/howto-import-react-component).\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1708,"value":"md`### Exporting UI components to the web\n\n... TBD\n\nIdeas welcome. I think with some investments we could hide views and the observable runtime behind a web component.\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":61,"value":"import { toc } from '@bryangingechen/toc'","pinned":false,"hidden":false,"mode":"ojs"},{"id":149,"value":"import { view, variable, bindOneWay, cautious } from \"@tomlarkworthy/view\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":265,"value":"import { tweet } from '@mbostock/tweet'","pinned":false,"hidden":false,"mode":"ojs"},{"id":2186,"value":"import { footer } from \"@endpointservices/endpoint-services-footer\"","pinned":false,"hidden":false,"mode":"ojs"},{"id":2192,"value":"footer","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W3c","stdlib":"1","titling":"auto"}