mi-element 0.6.7 → 0.8.0

package/docs/element.md

@@ -28,44 +28,32 @@ from the `static attributes` object. From there setters and getters for property
 changes using `.[name] = newValue` instead of `setAttribute(name, newValue)` are
 applied.
 
-Direct properties can also made observable with `static properties` as long as
-not yet being defined within attributes.
 
 ```js
 class extends MiElement {
   /**
-   * Declare observable attributes and their default values with this getter.
-   * Do not use `static attribute = { text: 'Hi' }` as components attributes 
+   * Declare observable attributes with this getter. 
+   * Use `true` to define boolean attributes!
+   * Do not use `static attribute = { text: false }` as components attributes 
    * will use a shallow copy only. With the getter we always get a real "deep" 
    * copy.
    * 
-   * For yet to defined numbers, boolean or strings use `Number`, `Boolean`, 
-   * `String`. Attributes are accessible via `.[name]` or `.getAttribute(name)`.
    * Avoid using attributes which are HTMLElement properties e.g. `className`.
+   * camelCased attributes will be made observable using its kebab-cased name.
    */
-  static get attributes () {
+  static get properties () {
     return {
-      text: 'Hi',
-      // A yet to be defined boolean value
-      focus: Boolean
+      text: {},
+      focus: { type: Boolean },
+      // define property only
+      numberPropOnly: { attribute: false, type: Number }
     }
   }
+
   /**
-   * Declare observable properties and their default values.
-   * Any changed value of a property, using `.[name] = nextValue` assignment, 
-   * will cause a rerender. 
-   * In case of objects or arrays consider changing the reference with the 
-   * spread operator like `{...obj}` or `[...arr]` creating a new reference.
-   * If name is already declared in `attributes` it will be ignored. 
+   * optionally declare "non observable" or internal properties
    */
-  static get properties () {
-    return { prop: 0 }
-  }
-  constructor() {
-    super()
-    // optionally declare "non observable" and internal properties
-    this.foo = 'foo'
-  }
+  foo = 'foo'
 }
 ```
 
@@ -74,10 +62,10 @@ class extends MiElement {
 Invoked when a component is being added to the document's DOM.
 
 Micro components create `this.renderRoot` (typically same as `this.shadowRoot`
-for open components) using `this.attachShadow(shadowRootOptions)`. Shadow root
-options are taken from the components `static shadowRootOptions = { mode: 'open'
+for open components) using `this.attachShadow(shadowRootInit)`. Shadow root
+options are taken from the components `static shadowRootInit = { mode: 'open'
 }`. In advanced cases where no shadow root is desired, set `static
-shadowRootOptions = null`
+shadowRootInit = null`
 
 The most common use case is adding event listeners to external nodes in
 `connectedCallback()`. Typically, anything done in `connectedCallback()` should
@@ -90,7 +78,7 @@ Then the first `render()` is issued with a `requestUpdate()`
 class extends MiElement {
   // { mode: 'open' } is the default shadow root option 
   // use `null` for no shadow root or { mode: 'closed' } for closed mode
-  static shadowRootOptions = { mode: 'open' }
+  static shadowRootInit = { mode: 'open' }
 
   connectedCallback() {
     super.connectedCallback() // don't forget to call the super method
@@ -160,24 +148,19 @@ flowchart TD
   disconnectedCallback("disconnectedCallback()")
   render("render()")
   requestUpdate("requestUpdate()")
-  shouldUpdate("shouldUpdate(changedAttributes)")
   update("update(changedAttributes)")
 
-  setAttribute("setAttribute(name, newVale)")
-  setProperty(".[name] = newValue")
+  setAttribute("el.setAttribute(name, newVale)")
+  setProperty("el.[name] = newValue")
 
   START --> constructoR
   constructoR -.->|"mount to DOM"| connectedCallback
   connectedCallback --> render
   render --> requestUpdate
-  requestUpdate -.->|async| shouldUpdate
-  shouldUpdate -->|true| update
-
-  setAttribute -->|"attributeChangedCallback"| requestUpdate
-  setProperty --> requestUpdate
+  requestUpdate -.->|async| update
 
-  update -.->|change| setAttribute
-  update -.->|change| setProperty
+  setAttribute -->|"attributeChangedCallback()"| requestUpdate
+  setProperty -->requestUpdate
 
   connectedCallback -.->|"unmount from DOM"| disconnectedCallback
   disconnectedCallback --> END
@@ -189,8 +172,8 @@ A micro component usually implements `render()` and `update()`:
 import { define, MiElement, refsBySelector } from 'mi-element'
 
 class Counter extends MiElement {
-  static get attributes() {
-    return { value: 0 }
+  static get properties() {
+    return { value: { type: Number } }
   }
 
   // define the innerHTML template for the component
@@ -226,20 +209,19 @@ class Counter extends MiElement {
 ## render()
 
 Initial rendering of the component. Try to render the component only once!
-If you need re-rendering by recrating the DOM do this outside of `render()`
 
 Within the `render()` method, bear in mind to:
 
 - Avoid changing the component's state.
 - Avoid producing any side effects.
-- Use only the component's attributes as input.
+- Use only the component's properties as input.
 
 !!! WARNING XSS - Cross-Site Scripting
     
     Using [`innerHTML`][innerHTML] to create the components DOM is susceptible to
     [XSS][XSS] attacks in case that user-supplied data contains valid HTML markup.
 
-In all other cases you may consider the <code>esc``</code> template literal or
+In all other cases you may consider the <code>html``</code> template literal or
 `escHtml()` from the "mi-element" import, which escapes user-supplied data.
 
 [innerHTML]: https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML
@@ -287,19 +269,19 @@ adding `id` attributes to the nodes where updates shall happen or event
 listeners must be applied.
 
 ```js
-import { MiElement, define, refsById } from 'mi-element'
+import { MiElement, define } from 'mi-element'
 
 class Counter extends MiElement {
   static template = `
   <button id>Count</button>
-  <p>Counter value: <span id="count">0</span></p>
+  <p>Counter value: <span>0</span></p>
   `
 
   render() {
     // template is already rendered on `this.renderRoot`
 
-    // get refs though `refsById` of `refsBySelector`
-    this.refs = refsById(this.renderRoot)
+    // get refs though `refsBySelector`
+    this.refs = this.refsBySelector({ button: 'button', count: 'p > span'})
     // this.refs == {button: <button>, count: <span>}
   }
 }
@@ -315,6 +297,11 @@ rendered elements as much as possible.
 
 ```js
 class Counter extends MiElement {
+  render() {
+    // ...
+    this.update()
+  }
+
   // ...
   update() {
     this.refs.count.textContent = this.value
@@ -327,18 +314,18 @@ any changed attributes are passed.
 
 To mitigate [XSS][] attacks prefer the use of `.textContent` and avoid
 ~~`.innerHTML`~~. For attribute changes use `.setAttribute(name, newValue)`.
-Both `.textContent` and `setAttribute()` provide escaping for you. 
-
 
 For finer control on updates the use of signals is encouraged. With this there
-is no need to add logic to `shouldUpdate()` or `update()`.
+is no need to add logic to `update()`.
 
 ```js
 import { MiElement, Signal } from 'mi-element'
 
 class Counter extends MiElement {
-  static get attributes() {
-    return { value: 0 }
+  static get properties() {
+    return { 
+      value: { type: Number } 
+     }
   }
 
   static template = `
@@ -346,8 +333,15 @@ class Counter extends MiElement {
   <p>Counter value: <span>0</span></p>
   `
 
+  constructor() {
+    super()
+    // set initial values
+    this.value = 0
+  }
+
+
   render() {
-    const refs = refsBySelector(this.renderRoot, {
+    const refs = this.refsBySelector({
       button: 'button',
       count: 'span'
     })
@@ -365,13 +359,6 @@ class Counter extends MiElement {
 }
 ```
 
-## shouldUpdate(changedAttributes)
-
-Convenience method in order to be able to decide on the changed attributes,
-whether `update()` should be called or not.
-
-Return `true` if component should be updated. 
-
 ## on(eventName, listener, \[node\])
 
 Adds listener function for eventName. listener is removed before component

package/docs/reactivity.md

@@ -16,9 +16,9 @@ import { html, render } from 'mi-html'
 define(
   'mi-counter',
   class extends MiElement {
-    static get attributes() {
+    static get properties() {
       return {
-        count: 1 //<< this.count is already a signal
+        count: { type: Number } //<< this.count is already a signal
       }
     }
 

package/docs/render.md

@@ -0,0 +1,357 @@
+**Table of contents**
+
+<!-- !toc (minlevel=2) -->
+
+- [html Tagged Template Literal](#html-tagged-template-literal)
+  - [Basic Usage](#basic-usage)
+  - [Working with Arrays](#working-with-arrays)
+  - [Nested Templates](#nested-templates)
+  - [Unsafe HTML](#unsafe-html)
+- [render() Function](#render-function)
+  - [Signature](#signature)
+  - [Basic Example](#basic-example)
+- [Special Attributes](#special-attributes)
+  - [Boolean Attributes (`?attr`)](#boolean-attributes-attr)
+  - [Property Binding (`.prop`)](#property-binding-prop)
+  - [Event Listeners (`@event`)](#event-listeners-event)
+  - [Element References (`ref`)](#element-references-ref)
+  - [Spread Properties (`...`)](#spread-properties-)
+- [Complete Example](#complete-example)
+- [Security](#security)
+- [Best Practices](#best-practices)
+- [Custom Elements](#custom-elements)
+
+<!-- toc! -->
+
+# HTML Templating and Rendering
+
+MiElement offers a lightweight templating system for properly escaping HTML to
+prevent XSS attacks. The `html` tagged template literal combined with the
+`render()` function provides a safe and convenient way to create dynamic HTML
+with event handlers, property bindings, and element references.
+
+## html Tagged Template Literal
+
+The `html` function is a tagged template literal that automatically escapes all
+interpolated values to prevent XSS attacks.
+
+### Basic Usage
+
+```js
+import { html } from '@mi-element/mi-element'
+
+// Simple text escaping
+const userInput = '<script>alert("xss")</script>'
+const safe = html`<div>${userInput}</div>`
+// Result: <div>&lt;script&gt;alert("xss")&lt;/script&gt;</div>
+```
+
+### Working with Arrays
+
+Arrays are automatically joined and each item is escaped:
+
+```js
+const items = ['Apple', 'Banana', 'Cherry']
+const list = html`<ul>
+  ${items.map((item) => html`<li>${item}</li>`)}
+</ul>`
+```
+
+### Nested Templates
+
+HTML templates can be nested safely without double-escaping:
+
+```js
+const header = html`<h1>${'<Title>'}</h1>`
+const page = html`
+  <div>
+    ${header}
+    <p>${'<content>'}</p>
+  </div>
+`
+// The header content remains escaped, not double-escaped
+```
+
+### Unsafe HTML
+
+When you need to render raw HTML (use with caution):
+
+```js
+import { unsafeHtml } from '@mi-element/mi-element'
+
+const trustedHtml = '<strong>Bold</strong>'
+const template = html`<div>${unsafeHtml(trustedHtml)}</div>`
+// Result: <div><strong>Bold</strong></div>
+```
+
+## render() Function
+
+The `render()` function takes an HTML template and renders it into a DOM node,
+with support for special attributes for event handling, property binding, and
+element references.
+
+### Signature
+
+```js
+render(node, template, (handlers = {}))
+```
+
+- `node`: Target DOM element to render into
+- `template`: HTML template string (typically from `html` tagged template)
+- `handlers`: Optional object containing event handler functions or HTMLElement
+  for method lookup
+- **Returns**: Object with collected element references
+
+### Basic Example
+
+```js
+import { html, render } from '@mi-element/mi-element'
+
+const container = document.querySelector('#app')
+const template = html`
+  <div>
+    <h1>Hello World</h1>
+    <p>Welcome to MiElement</p>
+  </div>
+`
+
+render(container, template)
+```
+
+## Special Attributes
+
+Special attributes provide powerful features for dynamic behavior. All special
+attributes are removed from the DOM after processing.
+
+### Boolean Attributes (`?attr`)
+
+Use the `?` prefix for boolean attributes:
+
+```js
+const isDisabled = true
+const template = html`
+  <input ?disabled=${isDisabled} />
+  <button ?hidden=${false}>Click</button>
+`
+
+render(container, template)
+// Result: <input disabled=""> <button>Click</button>
+```
+
+### Property Binding (`.prop`)
+
+Use the `.` prefix to set properties directly on DOM elements (not attributes):
+
+```js
+const inputValue = 'Hello'
+const userData = { name: 'John', age: 30 }
+
+const template = html`
+  <input .value=${inputValue} />
+  <my-component .data=${userData}></my-component>
+`
+
+render(container, template)
+// The input.value property is set, but not visible as an attribute
+```
+
+**Note**: Use kebab-case for property names - they will be automatically
+converted to camelCase:
+
+```js
+html`<div .some-property=${'value'}></div>`
+// Sets element.someProperty = 'value'
+```
+
+### Event Listeners (`@event`)
+
+Use the `@` prefix for event listeners:
+
+#### Inline Functions
+
+```js
+const template = html`
+  <button @click=${(e) => console.log('Clicked!', e)}>Click Me</button>
+`
+
+render(container, template)
+```
+
+#### Named Handlers
+
+```js
+const handlers = {
+  handleClick(e) {
+    console.log('Button clicked:', e.target)
+  },
+  handleInput(e) {
+    console.log('Input value:', e.target.value)
+  }
+}
+
+const template = html`
+  <button @click="handleClick">Click</button>
+  <input @input="handleInput" />
+`
+
+render(container, template, handlers)
+```
+
+#### Using HTMLElement Methods
+
+```js
+class MyComponent extends HTMLElement {
+  handleClick(e) {
+    console.log('Clicked in component')
+  }
+
+  connectedCallback() {
+    const template = html` <button @click="handleClick">Click</button> `
+    render(this, template, this)
+  }
+}
+```
+
+### Element References (`ref`)
+
+Collect references to rendered elements:
+
+```js
+const template = html`
+  <div>
+    <input ref="nameInput" type="text" />
+    <button ref="submitBtn">Submit</button>
+  </div>
+`
+
+const refs = render(container, template)
+// refs.nameInput -> the input element
+// refs.submitBtn -> the button element
+
+refs.nameInput.focus()
+refs.submitBtn.addEventListener('click', () => {
+  console.log(refs.nameInput.value)
+})
+```
+
+### Spread Properties (`...`)
+
+Spread multiple properties from an object:
+
+```js
+const inputProps = {
+  value: 'Default text',
+  disabled: true,
+  placeholder: 'Enter text'
+}
+
+const template = html`<input ...=${inputProps} />`
+
+render(container, template)
+// Sets all properties: value, disabled, and placeholder
+```
+
+## Complete Example
+
+```js
+import { html, render, MiElement, define } from '@mi-element/mi-element'
+import { MiElement } from '@mi-element/mi-element'
+
+class TodoList extends MiElement {
+  todos = [
+    { id: 1, text: 'Learn MiElement', done: false },
+    { id: 2, text: 'Build something', done: false }
+  ]
+
+  toggleTodo(id) {
+    const todo = this.todos.find((t) => t.id === id)
+    if (todo) todo.done = !todo.done
+    this.requestUpdate()
+  }
+
+  // first time render
+  render() {
+    const template = html`
+      <div>
+        <h2>My Todos</h2>
+        <ul ref="list"></ul>
+      </div>
+    `
+    this.refs = render(this.renderRoot, template)
+  }
+
+  // any updates
+  update() {
+    const template = this.todos.map(
+      (todo) => html`
+        <li>
+          <input
+            type="checkbox"
+            ?checked=${todo.done}
+            @change=${() => this.toggleTodo(todo.id)}
+          />
+          <span>${todo.text}</span>
+        </li>
+      `
+    )
+    // clear all children first
+    this.refs.list.innerHTML = ''
+    // then rerender
+    render(this.refs.list, template)
+  }
+}
+
+define('todo-list', TodoList)
+```
+
+## Security
+
+The `html` tagged template automatically escapes all values to prevent XSS
+attacks:
+
+- Strings are HTML-escaped
+- Objects and functions are stored in a temporary cache and referenced by key
+- Only use `unsafeHtml()` when you have trusted HTML content
+
+```js
+// Safe - user input is escaped
+const userInput = '<script>alert("xss")</script>'
+html`<div>${userInput}</div>`
+// Result: <div>&lt;script&gt;alert("xss")&lt;/script&gt</div>;
+
+// Unsafe - only use with trusted content
+const trustedHtml = '<strong>Safe HTML</strong>'
+html`<div>${unsafeHtml(trustedHtml)}</div>`
+```
+
+## Best Practices
+
+1. **Always use `html` for dynamic content** to ensure proper escaping
+2. **Use kebab-case** for all attribute and event names
+3. **Collect refs** instead of using `querySelector` when possible
+4. **Avoid `unsafeHtml`** unless absolutely necessary with trusted content
+5. **Use property binding** (`.prop`) for complex data structures
+6. **Leverage event delegation** for dynamic lists with many items
+7. **Keep handlers object** or use class methods for better organization
+
+## Custom Elements
+
+The render system automatically skips processing children of custom elements,
+allowing them to manage their own content:
+
+```js
+class MyElement extends HTMLElement {
+  connectedCallback() {
+    // This element controls its own rendering
+    this.innerHTML = `<input ref="inside" />`
+  }
+}
+
+customElements.define('my-element', MyElement)
+
+// The render function will process my-element's attributes
+// but won't process its children
+const template = html`
+  <my-element .data=${{ test: true }} ref="custom"></my-element>
+`
+```

package/docs/signal.md

@@ -24,7 +24,7 @@ For convenience there is a `createSignal(initialValue<T>): State<T>` function to
 create a signal.
 
 ```js
-import { createSignal, State } from 'mi-element'
+import { createSignal, State } from 'mi-signal'
 
 const signal = createSignal(1)
 // same as
@@ -58,7 +58,7 @@ signals state as well as to update on any change through
 _synchronously_!
 
 ```js
-import { createSignal, effect } from 'mi-element'
+import { createSignal, effect } from 'mi-signal'
 
 const signal = createSignal(1)
 
@@ -157,14 +157,15 @@ MiElement attributes are backed by signals. To subscribe to reactive changes a
 `Signal.effect` callback can be used on all observed attributes.
 
 ```js
-import { effect, define, MiElement, refByIds } from 'mi-element'
+import { effect, define, MiElement } from 'mi-element'
+import { createSignal } from 'mi-signal'
 
 define(
   'mi-counter',
   class extends MiElement {
     static template = `
-      <button id> + </button>
-      <div id></div>
+      <button> + </button>
+      <div></div>
     `
 
     static get attributes() {
@@ -174,8 +175,14 @@ define(
       }
     }
 
+    // define the signal to make all properties reactive
+    static createSignal = createSignal
+
     render() {
-      this.refs = refsById(this.renderRoot)
+      // define initial value
+      this.count = this.count ?? 0
+
+      this.refs = this.refsBySelector({ button: 'button', div: 'div' })
       this.refs.button.addEventListener('click', () => {
         // change observed and reactive attribute...
         this.count++

package/docs/store.md

@@ -62,4 +62,5 @@ const actions = {
     (by = 1) =>
     (state) => ({ ...state, count: state.count + by })
 }
+const store = new Store(actions, initialValue)
 ```

package/docs/styling.md

@@ -2,7 +2,7 @@
 
 <!-- !toc (minlevel=2) -->
 
-- [classMap](#classmap)
+- [classNames](#classnames)
 - [styleMap](#stylemap)
 - [addGlobalStyles](#addglobalstyles)
 
@@ -10,16 +10,16 @@
 
 # Styling
 
-## classMap
+## classNames
 
 Obtain a class string from an object. Only class-names with trueish values are
 returned.
 
 ```js
-import { classMap } from 'mi-element'
+import { classNames } from 'mi-element'
 
-const className = classMap({ enabled: true, hidden: '', number: 1 })
-//> className == 'enabled number'
+const className = classNames({ enabled: true, hidden: '', number: 1 }, 'always')
+//> className == 'enabled number always'
 ```
 
 ## styleMap
@@ -74,4 +74,16 @@ customElements.define(
     }
   }
 )
+
+// with MiElement 
+import { define, MiElement } from 'mi-element'
+
+define('x-with-global-styles', class extends MiElement {
+  static useGlobalStyles() {
+    return true
+  }
+
+  static template = '<h1>Hello World</h1>'
+})
+
 ```