@zeix/ui-element

Version:

UIElement - minimal reactive framework based on Web Components

54 lines (45 loc) • 51.3 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-1" class="tsd-anchor"></a><h1 class="tsd-anchor-link">UIElement<a href="#uielement-1" 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.11.0 UIElement - transform reusable markup, styles and behavior into powerful, reactive, and maintainable Web Components. <code>UIElement</code> is a base class for Web Components with reactive states and UI effects. UIElement is tiny, around 4kB gzipped JS code, of which unused functions can be tree-shaken by build tools. It uses <a href="https://github.com/zeixcom/cause-effect">Cause & Effect</a> internally for state management with signals and for scheduled DOM updates. <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>Reusable Components: Create highly modular and reusable components to encapsulate styles and behavior.</li> <li>Declarative States: Bring static, server-rendered content to life with dynamic interactivity and state management.</li> <li>Signal-Based Reactivity: Employ signals for efficient state propagation, ensuring your components react instantly to changes.</li> <li>Declarative Effects: Use granular effects to automatically synchronize UI states with minimal code.</li> <li>Context Support: Share global states across your component tree without tightly coupling logic.</li> </ul> <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 { UIElement, asInteger, setText } from '@zeix/ui-element' class ShowAppreciation extends UIElement { #count = Symbol() // Use a private Symbol as state key connectedCallback() { // Initialize count state this.set(this.#count, asInteger(0)(this.querySelector('.count').textContent)) // Bind click event to increment count this.first('button').on('click', () => { this.set(this.#count, v => ++v) }) // Update .count text when count changes this.first('.count').sync(setText(this.#count)) } // Expose read-only property for count get count() { return this.get(this.#count) } } ShowAppreciation.define('show-appreciation') </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-list-and-panels" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Tab List and Panels<a href="#tab-list-and-panels" 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 pass states from one component to another. Server-rendered markup: <pre><code class="html"><tab-list> <menu> <li><button type="button" aria-pressed="true">Tab 1</button></li> <li><button type="button">Tab 2</button></li> <li><button type="button">Tab 3</button></li> </menu> <details open> <summary>Tab 1</summary> <p>Content of tab panel 1</p> </details> <details> <summary>Tab 2</summary> <p>Content of tab panel 2</p> </details> <details> <summary>Tab 3</summary> <p>Content of tab panel 3</p> </details> </tab-list> </code><button type="button">Copy</button></pre> UIElement components: <pre><code class="js">import { UIElement, setAttribute, toggleAttribute } from '@zeix/ui-element' class TabList extends UIElement { static localName = 'tab-list' static observedAttributes = ['accordion'] init = { active: 0, accordion: asBoolean, } connectedCallback() { super.connectedCallback() // Set inital active tab by querying details[open] const getInitialActive = () => { const panels = Array.from(this.querySelectorAll('details')) for (let i = 0; i < panels.length; i++) { if (panels[i].hasAttribute('open')) return i } return 0 } this.set('active', getInitialActive()) // Reflect accordion attribute (may be used for styling) this.self.sync(toggleAttribute('accordion')) // Update active tab state and bind click handlers this.all('menu button') .on('click', (_, index) => () => { this.set('active', index) }) .sync(setProperty( 'ariaPressed', (_, index) => String(this.get('active') === index) )) // Update details panels open, hidden and disabled states this.all('details').sync( setProperty( 'open', (_, index) => !!(this.get('active') === index) ), setAttribute( 'aria-disabled', () => String(!this.get('accordion')) ) ) // Update summary visibility this.all('summary').sync(toggleClass( 'visually-hidden', () => !this.get('accordion') )) } } TabList.define() </code><button type="button">Copy</button></pre> Example styles: <pre><code class="css">tab-list { > menu { list-style: none; display: flex; gap: 0.2rem; padding: 0; & button[aria-pressed="true"] { color: purple; } } > details { &:not([open]) { display: none; } &[aria-disabled] { pointer-events: none; } } &[accordion] { > menu { display: none; } > details:not([open]) { display: block; } } } </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>A more complex component demonstrating async fetch from the server: <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 { UIElement, setProperty, setText, dangerouslySetInnerHTML } from '@zeix/ui-element' class LazyLoad extends UIElement { static localName = 'lazy-load' // Remove the following line if you don't want to listen to changes in 'src' attribute static observedAttributes = ['src'] init = { src: v => { // Custom attribute parser if (!v) { this.set('error', 'No URL provided in src attribute') return '' } else if ((this.parentElement || this.getRootNode().host)?.closest(`${this.localName}[src="${v}"]`)) { this.set('error', 'Recursive loading detected') return '' } const url = new URL(v, location.href) // Ensure 'src' attribute is a valid URL if (url.origin === location.origin) // Sanity check for cross-origin URLs return url.toString() this.set('error', 'Invalid URL origin') return '' }, content: async () => { // Async Computed callback const url = this.get('src') if (!url) return '' try { const response = await fetch(this.get('src')) this.querySelector('.loading')?.remove() if (response.ok) return response.text() else this.set('error', response.statusText) } catch (error) { this.set('error', error.message) } return '' }, error: '', } connectedCallback() { super.connectedCallback() // Effect to set error message this.first('.error').sync( setProperty('hidden', () => !this.get('error')), setText('error'), ) // Effect to set content in shadow root // Remove the second argument (for shadowrootmode) if you prefer light DOM this.self.sync(dangerouslySetInnerHTML('content', 'open')) } } LazyLoad.define() </code><button type="button">Copy</button></pre> </div></div><div class="col-sidebar"><div class="page-menu"><div class="tsd-navigation settings"><details class="tsd-accordion"><summary class="tsd-accordion-summary"><h3><svg width="20" height="20" viewBox="0 0 24 24" fill="none" aria-hidden="true"><use href="assets/icons.svg#icon-chevronDown"></use></svg>Settings</h3></summary><div class="tsd-accordion-details"><div class="tsd-filter-visibility">Member Visibility<ul id="tsd-filter-options"><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-protected" name="protected"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Protected</label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-inherited" name="inherited" checked/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>Inherited</label></li><li class="tsd-filter-item"><label class="tsd-filter-input"><input type="checkbox" id="tsd-filter-external" name="external"/><svg width="32" height="32" viewBox="0 0 32 32" aria-hidden="true"><rect class="tsd-checkbox-background" width="30" height="30" x="1" y="1" rx="6" fill="none"></rect><path class="tsd-checkbox-checkmark" d="M8.35422 16.8214L13.2143 21.75L24.6458 10.25" stroke="none" stroke-width="3.5" stroke-linejoin="round" fill="none"></path></svg>External</label></li></ul></div><div class="tsd-theme-toggle"><label class="settings-label" for="tsd-theme">Theme</label><select id="tsd-theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">D