Merge pull request #47 from zeixcom/feature/cause-effect-v0.12.0

feat: cleanup of API for version 1.0rc1 (0.11.0) using Cause & Effect 0.12.4, bugfixes, alignment of examples in docs and tests

Author: estherbrunner

README.md

@@ -1,10 +1,10 @@
 # UIElement
 
-Version 0.10.1
+Version 0.11.0
 
 **UIElement** - transform reusable markup, styles and behavior into powerful, reactive, and maintainable Web Components.
 
-`UIElement` is a base class for Web Components with reactive states and UI effects. UIElement is tiny, around 3kB gzipped JS code, of which unused functions can be tree-shaken by build tools. It uses [Cause & Effect](https://github.com/zeixcom/cause-effect) internally for state management with signals and [Pulse](https://github.com/zeixcom/pulse) for scheduled DOM updates.
+`UIElement` 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 [Cause & Effect](https://github.com/zeixcom/cause-effect) internally for state management with signals and for scheduled DOM updates.
 
 ## Key Features
 
@@ -24,8 +24,6 @@ npm install @zeix/ui-element
 bun add @zeix/ui-element
 ```
 
-For the functional core of your application we recommend [FlowSure](https://github.com/zeixcom/flow-sure) to create a robust and expressive data flow, supporting error handling and async processing with `Result` monads.
-
 ## Documentation
 
 The full documentation is still work in progress. The following chapters are already reasonably complete:
@@ -62,10 +60,12 @@ class ShowAppreciation extends UIElement {
 
     connectedCallback() {
         // Initialize count state
-        this.set(this.#count, asInteger(this.querySelector('.count').textContent) ?? 0)
+        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))
+        this.first('button').on('click', () => {
+            this.set(this.#count, v => ++v)
+        })
 
         // Update .count text when count changes
         this.first('.count').sync(setText(this.#count))
@@ -121,22 +121,22 @@ An example demonstrating how to pass states from one component to another. Serve
 ```html
 <tab-list>
     <menu>
-        <li><button type="button">Tab 1</button></li>
+        <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>
-    <tab-panel open>
-        <h2>Tab 1</h2>
+    <details open>
+        <summary>Tab 1</summary>
         <p>Content of tab panel 1</p>
-    </tab-panel>
-    <tab-panel>
-        <h2>Tab 2</h2>
+    </details>
+    <details>
+        <summary>Tab 2</summary>
         <p>Content of tab panel 2</p>
-    </tab-panel>
-    <tab-panel>
-        <h2>Tab 3</h2>
+    </details>
+    <details>
+        <summary>Tab 3</summary>
         <p>Content of tab panel 3</p>
-    </tab-panel>
+    </details>
 </tab-list>
 ```
 
@@ -146,60 +146,98 @@ UIElement components:
 import { UIElement, setAttribute, toggleAttribute } from '@zeix/ui-element'
 
 class TabList extends UIElement {
-    connectedCallback() {
-
-        // Set inital active tab by querying tab-panel[open]
-        let openPanelIndex = 0;
-        this.querySelectorAll('tab-panel').forEach((el, index) => {
-            if (el.hasAttribute('open')) openPanelIndex = index
-        })
-        this.set('active', openPanelIndex)
+    static localName = 'tab-list'
+    static observedAttributes = ['accordion']
 
-        // Handle click events on menu buttons and update active tab index
-        this.all('menu button')
-            .on('click', (_el, index) => () => this.set('active', index))
-            .sync((host, target, index) => {
-				setAttribute(
-					'aria-pressed',
-					() => host.get('active') === index ? 'true' : 'false'
-				)(host, target)
-			})
-
-        // Pass open attribute to tab-panel elements based on active tab index
-        this.all('tab-panel').pass((_el, index) => ({
-            open: () => index === this.get('active')
-        }))
+    init = {
+        active: 0,
+        accordion: asBoolean,
     }
-}
-TabList.define('tab-list')
 
-class TabPanel extends UIElement {
     connectedCallback() {
-        this.self.sync(toggleAttribute('open'))
+        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')
+        ))
     }
 }
-TabPanel.define('tab-panel')
+TabList.define()
 ```
 
 Example styles:
 
 ```css
-tab-list menu {
-    list-style: none;
-    display: flex;
-    gap: 0.2rem;
-    padding: 0;
-
-    & button[aria-pressed="true"] {
-        color: red;
+tab-list {
+
+    > menu {
+        list-style: none;
+        display: flex;
+        gap: 0.2rem;
+        padding: 0;
+
+        & button[aria-pressed="true"] {
+            color: purple;
+        }
     }
-}
 
-tab-panel {
-    display: none;
+    > details {
+
+        &:not([open]) {
+            display: none;
+        }
+
+        &[aria-disabled] {
+            pointer-events: none;
+        }
+    }
+
+    &[accordion] {
 
-    &[open] {
-        display: block;
+        > menu {
+            display: none;
+        }
+
+        > details:not([open]) {
+            display: block;
+        }
     }
 }
 ```
@@ -210,70 +248,64 @@ A more complex component demonstrating async fetch from the server:
 
 ```html
 <lazy-load src="/lazy-load/snippet.html">
-    <div class="loading">Loading...</div>
-    <div class="error"></div>
+    <div class="loading" role="status">Loading...</div>
+    <div class="error" role="alert" aria-live="polite"></div>
 </lazy-load>
 ```
 
 ```js
-import { UIElement, setText, setProperty, effect, enqueue } from '@zeix/ui-element'
+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']
-    states = {
-        src: v => {
-                let url = ''
-                try {
-                    url = new URL(v, location.href) // ensure 'src' attribute is a valid URL
-                    if (url.origin !== location.origin) // sanity check for cross-origin URLs
-                        throw new TypeError('Invalid URL origin')
-                } catch (error) {
-                    console.error(error, url)
-                    url = ''
-                }
+
+    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()
-            },
-        error: ''
+            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()
 
-        // Show / hide loading message
-        this.first('.loading')
-            .sync(setProperty('hidden', () => !!this.get('error')))
-
-        // Set and show / hide error message
-        this.first('.error')
-            .sync(setText('error'))
-            .sync(setProperty('hidden', () => !this.get('error')))
+        // Effect to set error message
+        this.first('.error').sync(
+            setProperty('hidden', () => !this.get('error')),
+            setText('error'),
+        )
 
-        // Load content from provided URL
-        effect(async () => {
-            const src = this.get('src')
-            if (!src) return // silently fail if no valid URL is provided
-            try {
-                const response = await fetch(src)
-                if (response.ok) {
-                    const content = await response.text()
-                    enqueue(() => {
-                        // UNSAFE!, use only trusted sources in 'src' attribute
-                        this.root.innerHTML = content
-                        this.root.querySelectorAll('script').forEach(script => {
-                            const newScript = document.createElement('script')
-                            newScript.appendChild(document.createTextNode(script.textContent))
-                            this.root.appendChild(newScript)
-                            script.remove()
-                        })
-                    }, [this.root, 'h'])
-                    this.set('error', '')
-                } else {
-                    this.set('error', response.status + ':'+ response.statusText)
-                }
-            } catch (error) {
-                this.set('error', 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('lazy-load')
+LazyLoad.define()
 ```

bun.lockb

@@ -7,7 +7,7 @@ export class AccordionPanel extends UIElement<{
 	static readonly localName = 'accordion-panel'
 	static observedAttributes = ['open', 'collapsible']
 
-	states = {
+	init = {
         open: asBoolean,
         collapsible: asBoolean
     }

docs-src/components/accordion-panel/accordion-panel.ts

@@ -10,7 +10,7 @@ export class CodeBlock extends UIElement<{ collapsed: boolean }> {
 	static readonly localName = 'code-block'
 	static observedAttributes = ['collapsed']
 
-	states = {
+	init = {
 		collapsed: asBoolean
 	}
 

docs-src/components/code-block/code-block.ts

@@ -1,6 +1,6 @@
 import { setText, UIElement, RESET } from "../../../"
 
-export class HelloWorld extends UIElement<{ name?: string }> {
+export class HelloWorld extends UIElement {
 	static localName = 'hello-world'
 
 	connectedCallback() {

docs-src/components/hello-world/hello-world.ts

@@ -1,14 +1,10 @@
-import { asBoolean, setProperty, setText, UIElement } from "../../../"
+import { UIElement, asBoolean, setProperty, setText } from "../../../"
 
-export class InputButton extends UIElement<{
-    disabled: boolean,
-	label?: string,
-    badge?: string,
-}> {
+export class InputButton extends UIElement<{ disabled: boolean }> {
 	static localName = 'input-button'
 	static observedAttributes = ['disabled']
 
-	states = {
+	init = {
         disabled: asBoolean,
     }
 

docs-src/components/input-button/input-button.ts

@@ -4,7 +4,7 @@ export class InputCheckbox extends UIElement<{ checked: boolean }> {
 	static localName = 'input-checkbox'
 	static observedAttributes = ['checked']
 
-	states = {
+	init = {
 		checked: asBoolean
 	}