@zeix/ui-element

<!doctype html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Data Flow – UIElement Docs</title> <meta name="description" content="Passing state, events, context" /> <base href="./data-flow.html" /> <link rel="stylesheet" href="assets/main.css" /> <script type="module" src="assets/main.js"></script> </head> <body> <header class="content-grid"> <h1 class="content"> UIElement Docs Version 0.12.2 </h1> <nav class="breakout"> <ol> <li> <a href="index.html"> 📖 Introduction Overview and key benefits of UIElement </a> </li> <li> <a href="getting-started.html"> 🚀 Getting Started Installation, setup, and first steps </a> </li> <li> <a href="building-components.html"> 🏗️ Building Components Anatomy, lifecycle, signals, effects </a> </li> <li> <a href="styling-components.html"> 🎨 Styling Components Scoped styles, CSS custom properties </a> </li> <li> <a href="data-flow.html" class="active"> 🔄 Data Flow Passing state, events, context </a> </li> <li> <a href="patterns-techniques.html"> 💡 Patterns & Techniques Composition, scheduling, best practices </a> </li> <li> <a href="examples-recipes.html"> 🍽️ Examples & Recipes Common use cases and demos </a> </li> <li> <a href="api-reference.html"> 📚 API Reference Detailed documentation of classes and functions </a> </li> <li> <a href="about-community.html"> 🤝 About & Community License, versioning, getting involved </a> </li> </ol> </nav> </header> <main><section class="hero"> <h1 id="data-flow"> <a name="data-flow" class="anchor" href="#data-flow"> 🔗 </a> 🔄 Data Flow </h1>UIElement enables smooth data flow between components using signals, events, and context. State can be passed down to child components, events can bubble up to notify parents of changes, and context can propagate across the component tree to share global state efficiently. This page explores different patterns for structuring data flow, helping you create modular, loosely coupled components that work seamlessly together. </section> <section> <h2 id="component-coordination"> <a name="component-coordination" class="anchor" href="#component-coordination"> 🔗 </a> Component Coordination </h2>Let's consider a product catalog where users can add items to a shopping cart. We have three independent components that work together: <ul> <li><code>ProductCatalog</code> (Parent):<ul> <li>Tracks all <code>SpinButton</code> components in its subtree and calculates the total count of items in the shopping cart.</li> <li>Passes that total to a <code>InputButton</code>.</li> </ul> </li> <li><code>InputButton</code> (Child):<ul> <li>Displays a badge in the top-right corner when the <code>badge</code> property is set.</li> <li>Does not track any state – it simply renders whatever value is passed to it.</li> </ul> </li> <li><code>SpinButton</code> (Child):<ul> <li>Displays an Add to Cart button initially.</li> <li>When an item is added, it transforms into a stepper (increment/decrement buttons).</li> </ul> </li> </ul> Although <code>InputButton</code> and <code>SpinButton</code> are completely independent, they need to work together. So <code>ProductCatalog</code> coordinates the data flow between them. <h3 id="parent-component-productcatalog"> <a name="parent-component-productcatalog" class="anchor" href="#parent-component-productcatalog"> 🔗 </a> Parent Component: ProductCatalog </h3>The parent component (<code>ProductCatalog</code>) knows about its children, meaning it can retrieve state from and pass state to them. First, we need to observe the quantities of all <code>SpinButton</code> components. For this, we create a signal of all children matching the <code>spin-button</code> selector: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>component("product-catalog", { total: (el) => () => selection(el, "spin-button") .get() .reduce((sum, item) => sum + item.value, 0), }, () => []); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> The <code>selection()</code> function returns a signal that emits an array of all matching elements. In contrast to a static <code>querySelectorAll()</code> call, the <code>selection()</code> function is reactive and updates whenever new elements are added or removed from the DOM. Then, we need to calculate the total of all product quantities and pass it on to the <code>InputButton</code> component. In UIElement we use the <code>pass()</code> function to share state across components: <code-block collapsed language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>component("product-catalog", { total: (el) => () => selection(el, "spin-button") .get() .reduce((sum, item) => sum + item.value, 0), }, (el) => [ first("input-button", pass({ badge: () => (el.total > 0 ? String(el.total) : ""), disabled: () => !el.total, }), ), ]); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> Allright, that's it! <ul> <li>✅ Whenever one of the <code>value</code> signals of a <code><spin-button></code> updates, the total in the badge of <code><input-button></code> automatically updates.</li> <li>✅ No need for event listeners or manual updates!</li> </ul> <h3 id="child-component-inputbutton"> <a name="child-component-inputbutton" class="anchor" href="#child-component-inputbutton"> 🔗 </a> Child Component: InputButton </h3>The <code>InputButton</code> component displays a badge when needed – it does not know about any other component nor track state itself. It just exposes a reactive property <code>badge</code> of type <code>string</code> and has an effect to react to state changes that updates the DOM subtree. <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>component("input-button", { badge: asString(RESET), }, () => [ first(".badge", setText("badge")), ]) </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <ul> <li>✅ Whenever the <code>badge</code> property is updated by a parent component, the badge text updates.</li> <li>✅ If <code>badge</code> is an empty string, the badge indicator is hidden (via CSS).</li> </ul> <h3 id="childcomponent-spinbutton"> <a name="childcomponent-spinbutton" class="anchor" href="#childcomponent-spinbutton"> 🔗 </a> ChildComponent: SpinButton </h3>The <code>SpinButton</code> component reacts to user interactions and exposes a reactive property <code>value</code> of type <code>number</code>. It updates its own internal DOM subtree, but doesn't know about any other component nor where the value is used. <code-block collapsed language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>component("spin-button", { value: asInteger(), }, (el) => { const max = asInteger(9)(el, el.getAttribute("max")); const isZero = () => el.value === 0; return [ first(".value", setText("value"), setProperty("hidden", isZero), ), first(".decrement", setProperty("hidden", isZero), on("click", () => { el.value--; }), ), first(".increment", setProperty("disabled", () => el.value >= max), on("click", () => { el.value++; }), ), all("button", on("keydown", (e) => { const { key } = e; if (["ArrowUp", "ArrowDown", "-", "+"].includes(key)) { e.stopPropagation(); e.preventDefault(); if (key === "ArrowDown" || key === "-") el.value--; if (key === "ArrowUp" || key === "+") el.value++; } }), ), ]; }); </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> <ul> <li>✅ Whenever the user clicks a button or presses a handled key, the value property is updated.</li> <li>✅ The component sets hidden and disabled states of buttons and updates the text of the <code>.value</code> element.</li> </ul> <h3 id="full-example"> <a name="full-example" class="anchor" href="#full-example"> 🔗 </a> Full Example </h3>Here's how everything comes together: <ul> <li>Each <code>SpinButton</code> tracks its own value.</li> <li>The <code>ProductCatalog</code> sums all quantities and passes the total to <code>InputButton</code>.</li> <li>The <code>InputButton</code> displays the total if it's greater than zero.</li> </ul> No custom events are needed – state flows naturally! <component-demo> <div class="preview"> <product-catalog> <header> Shop <input-button disabled> <button type="button" disabled> 🛒 Shopping Cart </button> </input-button> </header> <ul> <li> Product 1 <spin-button value="0" zero-label="Add to Cart" increment-label="Increment"> <button type="button" class="decrement" aria-label="Decrement" hidden>−</button> 0 <button type="button" class="increment">Add to Cart</button> </spin-button> </li> <li> Product 2 <spin-button value="0" zero-label="Add to Cart" increment-label="Increment"> <button type="button" class="decrement" aria-label="Decrement" hidden>−</button> 0 <button type="button" class="increment">Add to Cart</button> </spin-button> </li> <li> Product 3 <spin-button value="0" zero-label="Add to Cart" increment-label="Increment"> <button type="button" class="decrement" aria-label="Decrement" hidden>−</button> 0 <button type="button" class="increment">Add to Cart</button> </spin-button> </li> </ul> </product-catalog> </div> <details> <summary>ProductCatalog Source Code</summary> <lazy-load src="./examples/product-catalog.html"> Loading... </lazy-load> </details> <details> <summary>InputButton Source Code</summary> <lazy-load src="./examples/input-button.html"> Loading... </lazy-load> </details> <details> <summary>SpinButton Source Code</summary> <lazy-load src="./examples/spin-button.html"> Loading... </lazy-load> </details> </component-demo> </section> <section> <h2 id="custom-events"> <a name="custom-events" class="anchor" href="#custom-events"> 🔗 </a> Custom Events </h2>Passing state down works well when a parent component can directly observe child state, but sometimes a child needs to notify its parent about an action without managing shared state itself. Let's consider a Todo App, where users can add tasks: <ul> <li><code>TodoApp</code> (Parent):<ul> <li>Holds the list of todos as a state signal.</li> <li>Listens for an <code>add-todo</code> event from the child (<code>TodoForm</code>).</li> <li>Updates the state when a new todo is submitted.</li> </ul> </li> <li><code>TodoForm</code> (Child):<ul> <li>Handles user input but does not store todos.</li> <li>Emits an <code>add-todo</code> event when the user submits the form.</li> <li>Lets the parent decide what to do with the data.</li> </ul> </li> </ul> <h3 id="why-use-events-here"> <a name="why-use-events-here" class="anchor" href="#why-use-events-here"> 🔗 </a> Why use events here? </h3><ul> <li>The child doesn't need to know where the data goes – it just emits an event.</li> <li>The parent decides what to do with the new todo (e.g., adding it to a list).</li> <li>This keeps <code>TodoForm</code> reusable – it could work in different apps without modification.</li> </ul> <h3 id="parent-component-todoapp"> <a name="parent-component-todoapp" class="anchor" href="#parent-component-todoapp"> 🔗 </a> Parent Component: TodoApp </h3>The parent (<code>TodoApp</code>) listens for events and calls the <code>.addItem()</code> method on <code>TodoList</code> when a new todo is added: <code-block language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>this.self.on('add-todo', e => { this.querySelector('todo-list').addItem(e.detail) }) </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> <ul> <li>✅ Whenever <code>TodoForm</code> emits an <code>'add-todo'</code> event, a new task is appended to the todo list.</li> <li>✅ The event carries data (<code>e.detail</code>), so the parent knows what was submitted.</li> </ul> <h3 id="child-component-todoform"> <a name="child-component-todoform" class="anchor" href="#child-component-todoform"> 🔗 </a> Child Component: TodoForm </h3>The child (<code>TodoForm</code>) collects user input and emits an event when the form is submitted: <code-block collapsed language="js" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> js <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>const input = this.querySelector('input-field') this.first('form').on('submit', e => { e.preventDefault() // Wait for microtask to ensure the input field value is updated before dispatching the event queueMicrotask(() => { const value = input?.get('value')?.trim() if (value) { this.self.emit('add-todo', value) input?.clear() } }) }) </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> <button type="button" class="overlay">Expand</button> </code-block> <ul> <li>✅ The form does NOT store the todo – it just emits an event.</li> <li>✅ The parent (<code>TodoApp</code>) decides what happens next.</li> <li>✅ The event includes data (value), making it easy to handle.</li> </ul> <h3 id="full-example"> <a name="full-example" class="anchor" href="#full-example"> 🔗 </a> Full Example </h3>Here's how everything comes together: <ul> <li>User types a task into input field in <code>TodoForm</code>.</li> <li>On submit, <code>TodoForm</code> emits <code>'add-todo'</code> with the new task as event detail.</li> <li><code>TodoApp</code> listens for <code>'add-todo'</code> and updates the todo list.</li> </ul> <component-demo> <div class="preview"> <todo-app> <form action="#"> <input-field> <label for="add-todo">What needs to be done?</label> <div class="row"> <div class="group auto"> <input id="add-todo" type="text" value="" required> </div> </div> </input-field> <input-button class="submit"> <button type="submit" class="constructive" disabled>Add Todo</button> </input-button> </form> <ol filter="all"></ol> <template> <li> <input-checkbox class="todo"> <label> <input type="checkbox" class="visually-hidden" /> <slot></slot> </label> </input-checkbox> <input-button class="delete"> <button type="button" class="destructive small">Delete</button> </input-button> </li> </template> <footer> <div class="todo-count"> Well done, all done! task tasks remaining </div> <input-radiogroup value="all" class="split-button"> <fieldset> <legend class="visually-hidden">Filter</legend> <label class="selected"> <input type="radio" class="visually-hidden" name="filter" value="all" checked> All </label> <label> <input type="radio" class="visually-hidden" name="filter" value="active"> Active </label> <label> <input type="radio" class="visually-hidden" name="filter" value="completed"> Completed </label> </fieldset> </input-radiogroup> <input-button class="clear-completed"> <button type="button" class="destructive"> Clear Completed </button> </input-button> </footer> </todo-app> </div> <details> <summary>TodoApp Source Code</summary> <lazy-load src="./examples/todo-app.html"> Loading... </lazy-load> </details> <details> <summary>InputField Source Code</summary> <lazy-load src="./examples/input-field.html"> Loading... </lazy-load> </details> <details> <summary>InputButton Source Code</summary> <lazy-load src="./examples/input-button.html"> Loading... </lazy-load> </details> <details> <summary>InputCheckbox Source Code</summary> <lazy-load src="./examples/input-checkbox.html"> Loading... </lazy-load> </details> <details> <summary>InputRadiogroup Source Code</summary> <lazy-load src="./examples/input-radiogroup.html"> Loading... </lazy-load> </details> </component-demo> </section> <section> <h2 id="providing-context"> <a name="providing-context" class="anchor" href="#providing-context"> 🔗 </a> Providing Context </h2></section> <section> <h2 id="consuming-context"> <a name="consuming-context" class="anchor" href="#consuming-context"> 🔗 </a> Consuming Context </h2></section> <section> <h2 id="next-steps"> <a name="next-steps" class="anchor" href="#next-steps"> 🔗 </a> Next Steps </h2></section> </main> <footer class="content-grid"> <div class="content"> <h2 class="visually-hidden">Footer</h2> © 2024 – 2025 Zeix AG </div> </footer> </body> </html>