feat: enforce non-nullability at runtime, update docs

Author: estherbrunner

docs-src/components/todo-app/todo-app.ts

@@ -1,4 +1,4 @@
-import { UIElement, logMessage, setAttribute, setProperty, setText } from "../../.."
+import { UIElement, setAttribute, setProperty, setText } from "../../.."
 import type { InputCheckbox } from "../input-checkbox/input-checkbox"
 
 export class TodoApp extends UIElement<{

docs-src/pages/building-components.md

@@ -35,6 +35,20 @@ Every UIElement component must be registered with a valid custom tag name (two o
 MyComponent.define('my-component');
 ```
 
+<callout-box class="tip">
+
+**Alternative**: If you prefer you can also declare the custom element tag within the component and call `.define()` without arguments.
+
+```js
+class MyComponent extends UIElement {
+	static localName = 'my-component';
+	/* component definition */
+}
+MyComponent.define()
+```
+
+</callout-box>
+
 ### Using the Custom Element in HTML
 
 Once registered, the component can be used like any native HTML element:
@@ -79,14 +93,18 @@ If your component initializes states from `states` or provides or consumes conte
 ```js
 class HelloUser extends UIElement {
 	static consumedContexts = ['display-name']; // Signal provided by a parent component
+
 	states = {
 		greeting: 'Hello', // Initial value of 'greeting' signal
+		upper: () => this.get('display-name').toUpperCase(), // Compute function for transformation on 'display-name' signal
 	}
 
 	connectedCallback() {
-		super.connectedCallback();
+		super.connectedCallback(); // Initializes state signals from values, attributes, context or creates computed signals from functions 
+
 		this.first('.greeting').sync(setText('greeting'));
 		this.first('.user').sync(setText('display-name'));
+		this.first('.profile h2').sync(setText('upper'));
 	}
 }
 ```
@@ -103,11 +121,11 @@ class MyComponent extends UIElement {
 	connectedCallback() {
 		this.intersectionObserver = new IntersectionObserver(([entry]) => {
 			// Do something
-		}).observe(this)
+		}).observe(this);
 	}
 
 	disconnentedCallback() {
-		super.disconnectedCallback();
+		super.disconnectedCallback(); // Automatically removes event listeners bound with `.on()`
 		if (this.intersectionObserver) this.intersectionObserver.disconnect();
 	}
 }
@@ -141,6 +159,18 @@ if (this.has('count')) { /* Do something */ }
 this.delete('count'); // Removes the signal and its dependencies
 ```
 
+### Characteristics and Special Values
+
+Signals in UIElement are of a **fixed type** and **non-nullable**. This allows to **simplify the logic** as you will never have to check the type or perform null-checks.
+
+* If you use **TypeScript** (recommended), **you will be warned** that `null` or `undefined` cannot be assigned to a signal or if you try to assign a value of a wrong type.
+* If you use vanilla **JavaScript** without a build step, setting a signal to `null` or `undefined` **will log an error to the console and abort**. However, strict type checking is not enforced at runtime.
+
+Because of the **non-nullable nature of signals** in UIElement, we need two special values that can be assigned to any signal type:
+
+* **`RESET`**: Will **reset to the server-rendered version** that was there before UIElement took control. This is what you want to do most of the times when a signal lacks a specific value.
+* **`UNSET`**: Will **delete the signal**, **unsubscribe its watchers** and also **delete related attributes or style properties** in effects. Use this with special care!
+
 ### Why Signals with a Map Interface?
 
 UIElement **uses signals** instead of standard properties or attributes because it **ensures reactivity, loose coupling, and avoids common pitfalls with the DOM API**.
@@ -175,16 +205,28 @@ states = {
 };
 ```
 
+<callout-box class="caution">
+
+**Careful**: Attributes **may not be present** on the element or **parsing to the desired type may fail**. To ensure **non-nullability** of signals, UIElement falls back to neutral defaults:
+
+* `''` (empty string) for `string`
+* `0` for `number`
+* `{}` (empty object) for objects of any kind
+
+Pre-defined parsers (see next section) come with a variant `*WithDefault()` that allow you to set custom fallback values for attribute parsers.
+
+</callout-box>
+
 ### Pre-defined Parsers in UIElement
 
 | Function     | Description |
 | ------------ | ----------- |
 | `asBoolean`  | Converts `"true"` / `"false"` to a **boolean** (`true` / `false`). Also treats empty attributes (`checked`) as `true`. |
-| `asInteger`  | Converts a numeric string (e.g., `"42"`) to an **integer** (`42`). |
-| `asNumber`   | Converts a numeric string (e.g., `"3.14"`) to a **floating-point number** (`3.14`). |
-| `asString`   | Returns the attribute value as a **string** (unchanged). |
+| `asInteger`, `asIntegerWithDefault(1)` | Converts a numeric string (e.g., `"42"`) to an **integer** (`42`). |
+| `asNumber`, `asNumberWithDefault(0.1)` | Converts a numeric string (e.g., `"3.14"`) to a **floating-point number** (`3.14`). |
+| `asString`, `asStringwithDefault('foo')` | Returns the attribute value as a **string** (unchanged). |
 | `asEnum([...])` | Ensures the string matches **one of the allowed values**. Example: `asEnum(['small', 'medium', 'large'])`. If the value is not in the list, it defaults to the first option. |
-| `asJSON`     | Parses a JSON string (e.g., `'["a", "b", "c"]'`) into an **array** or **object**. If invalid, returns `null`. |
+| `asJSON`, `asJSONWithDefault({ theme: 'dark' })` | Parses a JSON string (e.g., `'["a", "b", "c"]'`) into an **array** or **object**. If invalid, returns `{}`. |
 
 </section>
 
@@ -258,14 +300,20 @@ this.first('.count').sync(
 | Function            | Description |
 | ------------------- | ----------- |
 | `setText()`         | Updates **text content** with a `string` signal value (while preserving comment nodes). |
-| `setProperty()`     | Updates a given **property** with any signal value. |
+| `setProperty()`     | Updates a given **property** with any signal value.* |
 | `setAttribute()`    | Updates a given **attribute** with a `string` signal value. |
 | `toggleAttribute()` | Toggles a given **boolean attribute** with a `boolean` signal value. |
 | `toggleClass()`     | Toggles a given **CSS class** with a `boolean` signal value. |
 | `setStyle()`        | Updates a given **CSS property** with a `string` signal value. |
 | `createElement()`   | Inserts a **new element** with a given tag name with a `Record<string, string>` signal value for attributes. |
 | `removeElement()`   | Removes an element if the `boolean` signal value is `true`. |
 
+<callout-box class="tip">
+
+**Tip**: TypeScript will check whether a value of a given type is assignable to a certain element type. You might have to specify a type hint for the queried element type. Prefer `setProperty()` over `setAttribute()` for increased type safety. Setting string attributes is possible for all elements, but will have an effect only on some.
+
+</callout-box>
+
 ### Simplifying Effect Notation
 
 For effects that take two arguments, **the second argument can be omitted** if the signal key matches the targeted property name, attribute, class, or style property.

docs-src/pages/data-flow.md

@@ -18,16 +18,16 @@ description: "Passing state, events, context"
 Let's consider a **product catalog** where users can add items to a shopping cart. We have **three independent components** that work together:
 
 * `ProductCatalog` **(Parent)**:
-	- **Tracks all `SpinButton` components** in its subtree and derives the **total count** of items in the shopping cart.
-	- **Passes that total** to a `BadgeButton`, which displays the number of items in the cart.
-* `BadgeButton` **(Child)**:
+	- **Tracks all `SpinButton` components** in its subtree and calculates the **total count** of items in the shopping cart.
+	- **Passes that total** to a `InputButton`, which displays the number of items in the cart.
+* `InputButton` **(Child)**:
 	- Displays a **cart badge** when the `'badge'` signal is set.
 	- **Does not track any state** – it simply renders whatever value is passed down.
 * `SpinButton` **(Child)**:
 	- Displays an **“Add to Cart”** button initially.
 	- When an item is added, it transforms into a **stepper** (increment/decrement buttons).
 
-Although `BadgeButton` **and** `SpinButton` are completely independent, they need to work together.
+Although `InputButton` **and** `SpinButton` are completely independent, they need to work together.
 So `ProductCatalog` **coordinates the data flow between them**.
 
 ### Parent Component: ProductCatalog
@@ -36,22 +36,22 @@ The **parent component (`ProductCatalog`) knows about its children**, meaning it
 
 Use the `.pass()` method to send values to child components. It takes an object where:
 
-* **Keys** = Signal names in the **child** (`BadgeButton`)
+* **Keys** = Signal names in the **child** (`InputButton`)
 * **Values** = Signal names in the parent (`ProductCatalog`) or functions returning computed values
 
 ```js
 this.first('input-button').pass({
-	badge: () => {
-		const total = this.get('total');
-		return typeof total === 'number' && total > 0 ? String(total) : '';
-	}
+	badge: () => asPositiveIntegerString(
+		this.all('spin-button').targets
+			.reduce((sum, item) => sum + item.get('value'), 0)
+	)
 });
 ```
 
-* ✅ **Whenever the `total` signal updates, `<input-button>` automatically updates.**
+* ✅ **Whenever one of the `value` signals of a `<spin-button>` updates, the total in the badge of `<input-button>` automatically updates.**
 * ✅ **No need for event listeners or manual updates!**
 
-### Child Component: BadgeButton
+### Child Component: InputButton
 
 The `InputButton` component **displays a badge when needed** – it does not track state itself.
 
@@ -68,88 +68,88 @@ class InputButton extends UIElement {
 * ✅ The `setText('badge')` effect **keeps the badge in sync** with the `'badge'` signal.
 * ✅ If badge is an **empty string**, the badge is **hidden**.
 
-The `BadgeButton` **doesn’t care how the badge value is calculated** – just that it gets one!
+The `InputButton` **doesn't care how the badge value is calculated** – just that it gets one!
 
 ### Full Example
 
 Here's how everything comes together:
 
 * Each `SpinButton` **tracks its own count**.
-* The `ProductCatalog` **sums all counts and passes the total to `BadgeButton`**.
-* The `BadgeButton` **displays the total** if it's greater than zero.
+* The `ProductCatalog` **sums all counts and passes the total to `InputButton`**.
+* The `InputButton` **displays the total** if it's greater than zero.
 
 **No custom events are needed – state flows naturally!**
 
 <component-demo>
-<div class="preview">
-<product-catalog>
-<header>
-<p>Shop</p>
-<input-button>
-<button type="button">
-<span class="label">🛒 Shopping Cart</span>
-<span class="badge"></span>
-</button>
-</input-button>
-</header>
-<ul>
-<li>
-<p>Product 1</p>
-<spin-button value="0" zero-label="Add to Cart" increment-label="Increment">
-<button type="button" class="decrement" aria-label="Decrement" hidden>−</button>
-<p class="value" hidden>0</p>
-<button type="button" class="increment primary">Add to Cart</button>
-</spin-button>
-</li>
-<li>
-<p>Product 2</p>
-<spin-button value="0" zero-label="Add to Cart" increment-label="Increment">
-<button type="button" class="decrement" aria-label="Decrement" hidden>−</button>
-<p class="value" hidden>0</p>
-<button type="button" class="increment primary">Add to Cart</button>
-</spin-button>
-</li>
-<li>
-<p>Product 3</p>
-<spin-button value="0" zero-label="Add to Cart" increment-label="Increment">
-<button type="button" class="decrement" aria-label="Decrement" hidden>−</button>
-<p class="value" hidden>0</p>
-<button type="button" class="increment primary">Add to Cart</button>
-</spin-button>
-</li>
-</ul>
-</product-catalog>
-</div>
-<accordion-panel collapsible>
-<details>
-<summary>
-<div class="summary">ProductCatalog Source Code</div>
-</summary>
-<lazy-load src="./examples/product-catalog.html">
-<p class="loading">Loading...</p>
-</lazy-load>
-</details>
-</accordion-panel>
-<accordion-panel collapsible>
-<details>
-<summary>
-<div class="summary">InputButton Source Code</div>
-</summary>
-<lazy-load src="./examples/input-button.html">
-<p class="loading">Loading...</p>
-</lazy-load>
-</details>
-</accordion-panel>
-<accordion-panel collapsible>
-<details>
-<summary>
-<div class="summary">SpinButton Source Code</div>
-</summary>
-<lazy-load src="./examples/spin-button.html">
-<p class="loading">Loading...</p>
-</lazy-load>
-</details>
-</accordion-panel>
+	<div class="preview">
+		<product-catalog>
+			<header>
+				<p>Shop</p>
+				<input-button>
+					<button type="button">
+						<span class="label">🛒 Shopping Cart</span>
+						<span class="badge"></span>
+					</button>
+				</input-button>
+			</header>
+			<ul>
+				<li>
+					<p>Product 1</p>
+					<spin-button value="0" zero-label="Add to Cart" increment-label="Increment">
+						<button type="button" class="decrement" aria-label="Decrement" hidden>−</button>
+						<p class="value" hidden>0</p>
+						<button type="button" class="increment">Add to Cart</button>
+					</spin-button>
+				</li>
+				<li>
+					<p>Product 2</p>
+					<spin-button value="0" zero-label="Add to Cart" increment-label="Increment">
+						<button type="button" class="decrement" aria-label="Decrement" hidden>−</button>
+						<p class="value" hidden>0</p>
+						<button type="button" class="increment">Add to Cart</button>
+					</spin-button>
+				</li>
+				<li>
+					<p>Product 3</p>
+					<spin-button value="0" zero-label="Add to Cart" increment-label="Increment">
+						<button type="button" class="decrement" aria-label="Decrement" hidden>−</button>
+						<p class="value" hidden>0</p>
+						<button type="button" class="increment">Add to Cart</button>
+					</spin-button>
+				</li>
+			</ul>
+		</product-catalog>
+	</div>
+	<accordion-panel collapsible>
+		<details>
+		<summary>
+			<div class="summary">ProductCatalog Source Code</div>
+		</summary>
+		<lazy-load src="./examples/product-catalog.html">
+			<p class="loading">Loading...</p>
+		</lazy-load>
+		</details>
+	</accordion-panel>
+	<accordion-panel collapsible>
+		<details>
+		<summary>
+			<div class="summary">InputButton Source Code</div>
+		</summary>
+		<lazy-load src="./examples/input-button.html">
+			<p class="loading">Loading...</p>
+		</lazy-load>
+		</details>
+	</accordion-panel>
+	<accordion-panel collapsible>
+		<details>
+		<summary>
+			<div class="summary">SpinButton Source Code</div>
+		</summary>
+		<lazy-load src="./examples/spin-button.html">
+			<p class="loading">Loading...</p>
+		</lazy-load>
+		</details>
+	</accordion-panel>
 </component-demo>
 
 </section>