@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" /> <link rel="stylesheet" href="./assets/main.css" /> <script type="module" src="./assets/main.js"></script> </head> <body class=""> <context-router> <header class="content-grid"> <h1 class="content"> UIElement Docs Version 0.13.3 </h1> <section-menu> <nav> <h2 class="visually-hidden">Main Menu</h2> <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="components.html"> 🏗️ Components Anatomy, lifecycle, signals, effects </a> </li> <li> <a href="styling.html"> 🎨 Styling Scoped styles, CSS custom properties </a> </li> <li> <a href="data-flow.html"> 🔄 Data Flow Passing state, events, context </a> </li> <li> <a href="examples.html"> 🍽️ Examples Common use cases and demos </a> </li> <li> <a href="blog.html"> 📜 Blog Latest articles and updates </a> </li> <li> <a href="api.html"> 📚 API Reference Functions, types, and constants </a> </li> <li> <a href="about.html"> 🤝 About License, versioning, getting involved </a> </li> </ol> </nav> </section-menu> <card-callout class="content danger" hidden> </card-callout> </header> <main class="content-grid"><section-hero> <h1 id="data-flow"> <a name="data-flow" class="anchor" href="#data-flow"> 🔗 </a> 🔄 Data Flow </h1> <div> Learn how UIElement components can work together seamlessly. Start with simple parent-child relationships, then explore advanced patterns like custom events and shared state. Build modular, loosely coupled components that communicate efficiently. <module-toc> <nav> <h2>In this Page</h2> <ol> <li><a href="#component-coordination">Component Coordination</a></li> <li><a href="#custom-events">Custom Events</a></li> <li><a href="#providing-context">Providing Context</a></li> <li><a href="#consuming-context">Consuming Context</a></li> <li><a href="#next-steps">Next Steps</a></li> </ol> </nav> </module-toc> </div> </section-hero> <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>ModuleCatalog</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>BasicButton</code>.</li> </ul> </li> <li><code>BasicButton</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>FormSpinbutton</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>BasicButton</code> and <code>FormSpinbutton</code> are completely independent, they need to work together. So <code>ModuleCatalog</code> coordinates the data flow between them. <h3 id="parent-component-modulecatalog"> <a name="parent-component-modulecatalog" class="anchor" href="#parent-component-modulecatalog"> 🔗 </a> Parent Component: ModuleCatalog </h3> The parent component (<code>ModuleCatalog</code>) knows about its children, meaning it can read state from and pass state to them. First, we need to observe the quantities of all <code>FormSpinbutton</code> components. For this, we create a signal of all children matching the <code>form-spinbutton</code> selector: <module-codeblock 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( 'module-catalog', { total: fromDescendants( 'form-spinbutton', (sum, item) => sum + item.value, 0, ), }, () => [], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> The <code>fromDescendants()</code> function returns a signal of the reduced array of all matching elements. In contrast to a static <code>querySelectorAll()</code> call, the <code>fromDescendants()</code> function is reactive and updates whenever new elements are added or removed from the DOM. Then, we need to convert the total of all product quantities to a string and pass it on to the <code>BasicButton</code> component. In UIElement we use the <code>pass()</code> function to share state across components: <module-codeblock 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( 'module-catalog', { total: fromDescendants( 'form-spinbutton', (sum, item) => sum + item.value, 0, ), }, (el, { first }) => [ first( 'basic-button', pass({ badge: () => (el.total > 0 ? String(el.total) : ''), disabled: () => !el.total, }), ), ], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> Allright, that's it! <ul> <li>Whenever one of the <code>value</code> signals of a <code><form-spinbutton></code> updates, the total in the badge of <code><basic-button></code> automatically updates.</li> <li>No need for event listeners or manual updates!</li> </ul> <h3 id="child-component-basicbutton"> <a name="child-component-basicbutton" class="anchor" href="#child-component-basicbutton"> 🔗 </a> Child Component: BasicButton </h3> The <code>BasicButton</code> component displays a badge when needed – it does not know about any other component nor track state itself. It just exposes a reactive properties <code>badge</code> of type <code>string</code> and <code>disabled</code> of type <code>boolean</code> and has effects to react to state changes that updates the DOM subtree. <module-codeblock 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( 'basic-button', { disabled: asBoolean(), badge: asString(), }, (_, { first }) => [ first('button', setProperty('disabled')), first('.badge', setText('badge')), ], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <ul> <li>Whenever the <code>disabled</code> property is updated by a parent component, the button is disabled or enabled.</li> <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="child-component-formspinbutton"> <a name="child-component-formspinbutton" class="anchor" href="#child-component-formspinbutton"> 🔗 </a> Child Component: FormSpinbutton </h3> The <code>FormSpinbutton</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. <module-codeblock 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( 'form-spinbutton', { value: asInteger(), }, (el, { all, first }) => { const zeroLabel = el.getAttribute('zero-label') || 'Add to Cart' const incrementLabel = el.getAttribute('increment-label') || 'Increment' const max = asInteger(9)(el, el.getAttribute('max')) const nonZero = () => el.value !== 0 return [ first('.value', setText('value'), show(nonZero)), first( '.decrement', show(nonZero), on('click', () => { el.value-- }), ), first( '.increment', setText(() => (nonZero() ? '+' : zeroLabel)), setProperty('ariaLabel', () => nonZero() ? incrementLabel : zeroLabel, ), 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> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <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>FormSpinbutton</code> tracks its own value.</li> <li>The <code>ModuleCatalog</code> sums all quantities and passes the total to <code>BasicButton</code>.</li> <li>The <code>BasicButton</code> displays the total if it's greater than zero.</li> </ul> No custom events are needed – state flows naturally! <module-demo> <div class="preview"> <module-catalog> <header> Shop <basic-button disabled> <button type="button" disabled> 🛒 Shopping Cart </button> </basic-button> </header> <ul> <li> Product 1 <form-spinbutton 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> </form-spinbutton> </li> <li> Product 2 <form-spinbutton 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> </form-spinbutton> </li> <li> Product 3 <form-spinbutton 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> </form-spinbutton> </li> </ul> </module-catalog> </div> <details> <summary>ModuleCatalog Source Code</summary> <module-lazy src="./examples/module-catalog.html"> <card-callout> Loading... </card-callout> </module-lazy> </details> <details> <summary>BasicButton Source Code</summary> <module-lazy src="./examples/basic-button.html"> <card-callout> Loading... </card-callout> </module-lazy> </details> <details> <summary>FormSpinbutton Source Code</summary> <module-lazy src="./examples/form-spinbutton.html"> <card-callout> Loading... </card-callout> </module-lazy> </details> </module-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. Custom events are perfect for this - they allow components to communicate upward through the DOM tree without tight coupling. <h3 id="typescript-support-for-components-and-events"> <a name="typescript-support-for-components-and-events" class="anchor" href="#typescript-support-for-components-and-events"> 🔗 </a> TypeScript Support for Components and Events </h3> To get full TypeScript support, declare your components and custom events globally: <module-codeblock collapsed language="typescript" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> typescript <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>// In your component file export type ProductCardProps = { productId: string quantity: number } declare global { interface HTMLElementTagNameMap { 'product-card': Component<ProductCardProps> 'shopping-cart': Component<ShoppingCartProps> } interface HTMLElementEventMap { itemAdded: CustomEvent<{ id: string; quantity: number }> cartUpdated: CustomEvent<{ total: number }> } } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> This enables full type checking, autocompletion, and access to UIElement component methods like <code>.getSignal()</code> and <code>.setSignal()</code>. <h3 id="example-shopping-cart-events"> <a name="example-shopping-cart-events" class="anchor" href="#example-shopping-cart-events"> 🔗 </a> Example: Shopping Cart Events </h3> Consider a product card that needs to notify its parent when an item is added: <module-codeblock 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>// Child component dispatches custom event component( 'product-card', { productId: asString(), quantity: asInteger(), }, (el, { first }) => [ first( '.add-button', on('click', () => { // Dispatch custom event with product details el.dispatchEvent( new CustomEvent('itemAdded', { detail: { id: el.productId, quantity: el.quantity, }, bubbles: true, }), ) }), ), ], ) </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <module-codeblock 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>// Parent component listens for custom events component( 'shopping-cart', { items: fromEvent( 'product-card', 'itemAdded', ({ event, source, value }) => { // TypeScript knows 'source' is Component<ProductCardProps> // Can access UIElement methods like source.getSignal('quantity') const newItem = { id: event.detail.id, quantity: event.detail.quantity, addedAt: Date.now(), } return [...value, newItem] }, [], ), total: () => el.items.reduce((sum, item) => sum + item.quantity, 0), }, (el, { first }) => [ first('.cart-count', setText('total')), first( '.items-list', setText(() => el.items.map(item => `${item.id}: ${item.quantity}`).join(', '), ), ), ], ) declare global { interface HTMLElementTagNameMap { 'shopping-cart': Component<ShoppingCartProps> } } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> <h3 id="benefits-of-custom-events"> <a name="benefits-of-custom-events" class="anchor" href="#benefits-of-custom-events"> 🔗 </a> Benefits of Custom Events </h3> <ul> <li>Decoupling: Child components don't need to know about parent implementation</li> <li>Reusability: Components can be used in different contexts</li> <li>Standard DOM: Uses native event system, works with any framework</li> <li>Bubbling: Events naturally flow up the DOM tree</li> <li>Cancellable: Parent can prevent default behavior if needed</li> </ul> <h3 id="when-to-use-custom-events"> <a name="when-to-use-custom-events" class="anchor" href="#when-to-use-custom-events"> 🔗 </a> When to Use Custom Events </h3> <ul> <li>User Actions: Button clicks, form submissions, gestures</li> <li>State Changes: When a component's internal state affects others</li> <li>Lifecycle Events: Component initialization, destruction, errors</li> <li>Data Flow: When child needs to send data upward without direct coupling</li> </ul> <h3 id="component-type-safety-best-practices"> <a name="component-type-safety-best-practices" class="anchor" href="#component-type-safety-best-practices"> 🔗 </a> Component Type Safety Best Practices </h3> Each UIElement component should declare its own <code>HTMLElementTagNameMap</code> extension: <module-codeblock collapsed language="ts" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> ts <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code>// In my-component.ts export type MyComponentProps = { value: string count: number } export default component( 'my-component', { /* ... */ }, () => [], ) declare global { interface HTMLElementTagNameMap { 'my-component': Component<MyComponentProps> } } </code></pre> <basic-button class="copy"> <button type="button" class="secondary small"> Copy </button> </basic-button> <button type="button" class="overlay">Expand</button> </module-codeblock> This enables: <ul> <li>Full type safety when using signal producers like <code>fromDescendants('my-component', ...)</code></li> <li>Access to UIElement methods like <code>.getSignal()</code> and <code>.setSignal()</code></li> <li>IntelliSense for component properties and methods</li> <li>Compile-time validation of component interactions</li> </ul> </section> <section> <h2 id="providing-context"> <a name="providing-context" class="anchor" hre