@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>Introduction – UIElement Docs</title> <meta name="description" content="Overview and key benefits of UIElement" /> <base href="./index.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" class="active"> 📖 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"> 🔄 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="introduction"> <a name="introduction" class="anchor" href="#introduction"> 🔗 </a> 📖 Introduction </h1>Web development doesn't need to be complicated. UIElement offers a refreshingly simple approach to create reactive Web Components that enhance your existing HTML. </section> <section> <h2 id="what-is-uielement"> <a name="what-is-uielement" class="anchor" href="#what-is-uielement"> 🔗 </a> What is UIElement? </h2>UIElement is a lightweight TypeScript library (approximately 4kB gzipped) that brings signal-based reactivity to Web Components. It serves as a thin layer between standard web technologies and modern reactivity patterns, empowering you to: <ul> <li>Transform ordinary HTML elements into reactive components</li> <li>Bind UI updates directly to state changes with minimal boilerplate</li> <li>Create reusable component patterns without complex abstractions</li> <li>Progressively enhance server-rendered content with client-side interactivity</li> </ul> <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>import { asInteger, component, first, on, RESET, setText } from "@zeix/ui-element"; component("show-appreciation", { count: asInteger(RESET) // Get initial value from .count element }, el => [ // Update count display when state changes first(".count", setText("count")), // Handle click events to change state first("button", on("click", () => { el.count++ })) ]); </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> UIElement augments what the platform already provides. It leverages the Web Components standard while adding just enough convenience functions to make reactive UI behaviors easy to implement. </section> <section> <h2 id="philosophy-amp-design-goals"> <a name="philosophy-amp-design-goals" class="anchor" href="#philosophy-amp-design-goals"> 🔗 </a> Philosophy & Design Goals </h2> <h3 id="html-first-approach"> <a name="html-first-approach" class="anchor" href="#html-first-approach"> 🔗 </a> HTML-First Approach </h3>While many frameworks start with JavaScript and generate HTML, UIElement takes the opposite approach. It assumes you already have HTML (usually server-rendered) and want to enhance it with behavior: <code-block language="html" copy-success="Copied!" copy-error="Error trying to copy to clipboard!"> html <pre class="shiki monokai" style="background-color:#272822;color:#F8F8F2" tabindex="0"><code> <show-appreciation aria-label="Show appreciation"> <button type="button"> <span class="emoji">💐</span> <span class="count">5</span> </button> </show-appreciation> </code></pre> <input-button class="copy"> <button type="button" class="secondary small"> Copy </button> </input-button> </code-block> This philosophy means: <ul> <li>Better SEO and initial page load performance</li> <li>Progressive enhancement for resilient UIs</li> <li>Less client-side rendering overhead</li> <li>Simpler accessibility implementation</li> </ul> <h3 id="performance-by-design"> <a name="performance-by-design" class="anchor" href="#performance-by-design"> 🔗 </a> Performance By Design </h3>UIElement avoids the overhead of virtual DOM diffing, instead using precise, targeted DOM updates through a fine-grained reactivity system: <ul> <li>Efficient signal propagation that updates only what changed</li> <li>Batch processing and scheduling of updates to minimize browser reflows</li> <li>Minimal abstraction layers between your code and the browser</li> </ul> <h3 id="developer-experience-without-compromise"> <a name="developer-experience-without-compromise" class="anchor" href="#developer-experience-without-compromise"> 🔗 </a> Developer Experience Without Compromise </h3>UIElement is designed to be intuitive and easy to use. It's built with type safety in mind, ensuring that your code is correct and that you don't miss any potential bugs. <ul> <li>Type Safety: Get early warnings when types don't match, improving code quality and reducing bugs.</li> <li>Minimal Boilerplate: Write less code to achieve the same result.</li> <li>Declarative Syntax: Define component behavior by composing small, reusable functions (attribute parsers and effects).</li> <li>Customizable: UIElement is designed to be easily customizable and extensible. You can create your own custom attribute parsers and effects to suit your specific needs.</li> </ul> </section> <section> <h2 id="why-uielement"> <a name="why-uielement" class="anchor" href="#why-uielement"> 🔗 </a> Why UIElement? </h2>While there are many excellent JavaScript frameworks out there, UIElement embraces web standards without proprietary extensions. It deliberately eschews abstractions like HTML-in-JS (client-side rendering) or JS-in-HTML (logic in framework-specific attributes) in favor of directness. While it does state management and view updates the hard way internally, it provides the benefits of declarative reactivity with only a few functions to compose complex behavior for developers. UIElement differentiates itself through: <ul> <li>Simplicity: Few, clear concepts (components, signals, element selectors, effects) allow developers to quickly build interactive components.</li> <li>Performance: Fine-grained, direct DOM manipulation outperforms virtual DOM approaches with re-rendering.</li> <li>Minimalism: As a thin layer over native web standards, it has no dependencies and minimal footprint with tree-shakable functions.</li> </ul> UIElement shines when: <ul> <li>You're working with server-rendered content that needs client-side enhancements</li> <li>Performance is critical, especially on lower-powered devices</li> <li>You want component reusability without framework lock-in</li> <li>You prefer working with future-proof standard web technologies</li> <li>You need to integrate with diverse tech stacks and existing codebases</li> </ul> </section> <section> <h2 id="next-steps"> <a name="next-steps" class="anchor" href="#next-steps"> 🔗 </a> Next Steps </h2>Now that you understand what UIElement is and its core philosophy, you're ready to: <ul> <li>Move on to <a href="getting-started.html">Getting Started</a> to install the library and build your first component</li> <li>Learn more about <a href="building-components.html">Building Components</a> to create reusable UI patterns</li> <li>Explore <a href="data-flow.html">Data Flow</a> to understand how to manage component communication</li> </ul> </section> </main> <footer class="content-grid"> <div class="content"> <h2 class="visually-hidden">Footer</h2> © 2024 – 2025 Zeix AG </div> </footer> </body> </html>