@zeix/ui-element

Version:

UIElement - minimal reactive framework based on Web Components

56 lines (48 loc) • 61.4 kB

HTML

<!DOCTYPE html><html class="default" lang="en" data-base="."><head><meta charset="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@zeix/ui-element</title><meta name="description" content="Documentation for @zeix/ui-element"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script defer src="assets/main.js"></script><script async src="assets/icons.js" id="tsd-icons-script"></script><script async src="assets/search.js" id="tsd-search-script"></script><script async src="assets/navigation.js" id="tsd-nav-script"></script></head><body><script>document.documentElement.dataset.theme = localStorage.getItem("tsd-theme") || "os";document.body.style.display="none";setTimeout(() => app?app.showPage():document.body.style.removeProperty("display"),500)</script><header class="tsd-page-toolbar"><div class="tsd-toolbar-contents container"><div class="table-cell" id="tsd-search"><div class="field"><label for="tsd-search-field" class="tsd-widget tsd-toolbar-icon search no-caption"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-search"></use></svg></label><input type="text" id="tsd-search-field" aria-label="Search"/></div><div class="field"><div id="tsd-toolbar-links"></div></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">@zeix/ui-element</a></div><div class="table-cell" id="tsd-widgets"><a href="#" class="tsd-widget tsd-toolbar-icon menu no-caption" data-toggle="menu" aria-label="Menu"><svg width="16" height="16" viewBox="0 0 16 16" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-menu"></use></svg></a></div></div></header><div class="container container-main"><div class="col-content"><div class="tsd-page-title"><h1>@zeix/ui-element</h1></div><div class="tsd-panel tsd-typography"><a id="uielement" class="tsd-anchor"></a><h1 class="tsd-anchor-link">UIElement<a href="#uielement" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h1>Version 0.12.2 UIElement - the HTML-first microframework bringing reactivity to Web Components. UIElement is a set of functions to build reusable, loosely coupled Web Components with reactive properties. It provides structure through components and simplifies state management and DOM synchronization using declarative signals and effects, leading to more organized and maintainable code without a steep learning curve. Unlike SPA frameworks (React, Vue, Svelte, etc.) UIElement takes a HTML-first approach, progressively enhancing sever-rendered HTML rather than recreating (rendering) it using JavaScript. UIElement achieves the same result as SPA frameworks with SSR, but with a simpler, more efficient approach. It works with a backend written in any language or with any static site generator. <a id="key-features" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Key Features<a href="#key-features" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><ul> <li>🧱 HTML Web Components: Build on standard HTML and enhance it with encapsulated, reusable Web Components. No virtual DOM – UIElement works directly with the real DOM.</li> <li>🚦 Reactive Properties: Define reactive properties for fine-grained, efficient state management (signals). Changes automatically propagate only to the parts of the DOM that need updating, avoiding unnecessary re-renders.</li> <li>🧩 Function Composition: Declare component behavior by composing small, reusable functions (attribute parsers and effects). This promotes cleaner code compared to spaghetti code problems that commonly occur when writing low-level imperative code.</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> <li>🌐 Context Support: Share global states across components without prop drilling or tightly coupling logic.</li> <li>🪶 Tiny footprint: Minimal core (~4kB gzipped) with tree-shaking support, adding only the necessary JavaScript to enhance your HTML.</li> <li>🛡️ Type Safety: Get early warnings when types don't match, improving code quality and reducing bugs.</li> </ul> UIElement uses <a href="https://github.com/zeixcom/cause-effect">Cause & Effect</a> internally for state management with signals and for scheduled DOM updates. But you could easily rewrite the <code>component()</code> function to use a signals library of your choice or to produce something else than Web Components. <a id="installation" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Installation<a href="#installation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><pre><code class="bash"># with npm npm install @zeix/ui-element # or with bun bun add @zeix/ui-element </code><button type="button">Copy</button></pre> <a id="documentation" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Documentation<a href="#documentation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2>The full documentation is still work in progress. The following chapters are already reasonably complete: <ul> <li><a href="https://zeixcom.github.io/ui-element/index.html">Introduction</a></li> <li><a href="https://zeixcom.github.io/ui-element/getting-started.html">Getting Started</a></li> <li><a href="https://zeixcom.github.io/ui-element/building-components.html">Building Components</a></li> <li><a href="https://zeixcom.github.io/ui-element/styling-components.html">Styling Components</a></li> <li><a href="https://zeixcom.github.io/ui-element/data-flow.html">Data Flow</a></li> <li><a href="https://zeixcom.github.io/ui-element/about-community.html">About & Community</a></li> </ul> <a id="basic-usage" class="tsd-anchor"></a><h2 class="tsd-anchor-link">Basic Usage<a href="#basic-usage" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h2><a id="show-appreciation" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Show Appreciation<a href="#show-appreciation" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>Server-rendered markup: <pre><code class="html"><show-appreciation aria-label="Show appreciation"> <button type="button"> <span class="emoji">💐</span> <span class="count">5</span> </button> </show-appreciation> </code><button type="button">Copy</button></pre> UIElement component: <pre><code class="js">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><button type="button">Copy</button></pre> Example styles: <pre><code class="css">show-appreciation { display: inline-block; & button { display: flex; flex-direction: row; gap: var(--space-s); border: 1px solid var(--color-border); border-radius: var(--space-xs); background-color: var(--color-secondary); color: var(--color-text); padding: var(--space-xs) var(--space-s); cursor: pointer; font-size: var(--font-size-m); line-height: var(--line-height-xs); transition: transform var(--transition-short) var(--easing-inout); &:hover { background-color: var(--color-secondary-hover); } &:active { background-color: var(--color-secondary-active); .emoji { transform: scale(1.1); } } } } </code><button type="button">Copy</button></pre> <a id="tab-group" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Tab Group<a href="#tab-group" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>An example demonstrating how to create a fully accessible tab navigation. Server-rendered markup: <pre><code class="html"><tab-group> <div role="tablist"> <button type="button" role="tab" id="trigger1" aria-controls="panel1" aria-selected="true" tabindex="0" > Tab 1 </button> <button type="button" role="tab" id="trigger2" aria-controls="panel2" aria-selected="false" tabindex="-1" > Tab 2 </button> <button type="button" role="tab" id="trigger3" aria-controls="panel3" aria-selected="false" tabindex="-1" > Tab 3 </button> </div> <div role="tabpanel" id="panel1" aria-labelledby="trigger1"> Tab 1 content </div> <div role="tabpanel" id="panel2" aria-labelledby="trigger2" hidden> Tab 2 content </div> <div role="tabpanel" id="panel3" aria-labelledby="trigger3" hidden> Tab 3 content </div> </tab-group> </code><button type="button">Copy</button></pre> UIElement component: <pre><code class="js">import { all, component, first, on, setProperty } from "@zeix/ui-element" // Function to create event handler for arrow key focus management const manageArrowKeyFocus = (elements, index) => e => { if (!(e instanceof KeyboardEvent)) throw new TypeError("Event is not a KeyboardEvent") const handledKeys = ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End"] if (handledKeys.includes(e.key)) { e.preventDefault() switch (e.key) { case "ArrowLeft": case "ArrowUp": index = index < 1 ? elements.length - 1 : index - 1 break case "ArrowRight": case "ArrowDown": index = index >= elements.length - 1 ? 0 : index + 1 break case "Home": index = 0 break case "End": index = elements.length - 1 break } if (elements[index]) elements[index].focus() } } // Component component("tab-group", { selected: "" }, el => { el.selected = el.querySelector("[role=tab][aria-selected=true]")?.getAttribute("aria-controls") ?? ""; const isSelected = target => el.selected === target.getAttribute("aria-controls"); const tabs = Array.from(el.querySelectorAll("[role=tab]")); let focusIndex = 0; return [ first("[role=tablist]", on("keydown", manageArrowKeyFocus(tabs, focusIndex)), ), all("[role=tab]", on("click", e => { el.selected = e.currentTarget.getAttribute("aria-controls") ?? ""; focusIndex = tabs.findIndex(tab => isSelected(tab)); }), setProperty("ariaSelected", target => String(isSelected(target))), setProperty("tabIndex", target => isSelected(target) ? 0 : -1), ), all("[role=tabpanel]", setProperty("hidden", target => el.selected !== target.id), ) ]; }); </code><button type="button">Copy</button></pre> Example styles: <pre><code class="css">tab-group { display: block; margin-bottom: var(--space-l); > [role="tablist"] { display: flex; border-bottom: 1px solid var(--color-gray-50); padding: 0; margin-bottom: 0; & button { border: 0; border-top: 2px solid transparent; border-bottom-width: 0; font-family: var(--font-family-sans); font-size: var(--font-size-s); font-weight: var(--font-weight-bold); padding: var(--space-s) var(--space-m); color: var(--color-text-soft); background-color: var(--color-secondary); cursor: pointer; transition: all var(--transition-short) var(--easing-inout); &:hover, &:focus { color: var(--color-text); background-color: var(--color-secondary-hover); } &:active { color: var(--color-text); background-color: var(--color-secondary-active); } &[aria-selected="true"] { color: var(--color-primary-active); border-top: 3px solid var(--color-primary); background-color: var(--color-background); margin-bottom: -1px; } } } > [role="tabpanel"] { font-family: sans-serif; font-size: var(--font-size-m); background: var(--color-background); margin-block: var(--space-l); } } </code><button type="button">Copy</button></pre> <a id="lazy-load" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Lazy Load<a href="#lazy-load" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3>An example demonstrating how to use a custom attribute parser (sanitize an URL) and a signal producer (async fetch) to implement lazy loading. <pre><code class="html"><lazy-load src="/lazy-load/snippet.html"> <div class="loading" role="status">Loading...</div> <div class="error" role="alert" aria-live="polite"></div> </lazy-load> </code><button type="button">Copy</button></pre> <pre><code class="js">import { setProperty, setText, dangerouslySetInnerHTML, component, first } from "@zeix/ui-element"; // Attribute Parser uses current element to detect recursion and set error message const asURL = (el, v) => { let value = ""; let error = ""; if (!v) { error = "No URL provided in src attribute"; } else if ( (el.parentElement || (el.getRootNode() as ShadowRoot).host)?.closest( `${el.localName}[src="${v}"]`, ) <span class=