natxocc/sigpro
1
1
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update Funcions

Browse Source
This commit is contained in:
natxocc
2026-04-06 18:28:07 +02:00
parent 5bbd2adf82
commit bf3069d439
24 changed files with 793 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
docs/api/for.md
View File

@@ -1,11 +1,11 @@
# Reactive Lists: `$for( )`
# Reactive Lists: `For( )`
The `$for` function is a high-performance list renderer. It maps an array (or a Signal containing an array) to DOM nodes. Unlike a simple `.map()`, `$for` is **keyed**, meaning it only updates, moves, or deletes the specific items that changed.
The `For` function is a high-performance list renderer. It maps an array (or a Signal containing an array) to DOM nodes. Unlike a simple `.map()`, `For` is **keyed**, meaning it only updates, moves, or deletes the specific items that changed.
## Function Signature
```typescript
$for(
For(
source: Signal<any[]> | Function | any[],
render: (item: any, index: number) => HTMLElement,
keyFn?: (item: any, index: number) => string | number
@@ -34,7 +34,7 @@ const users = $([
]);
Ul({ class: "list" }, [
$for(users,
For(users,
(user) => Li({ class: "p-2" }, user.name),
(user) => user.id // Stable and unique key
)
@@ -42,14 +42,14 @@ Ul({ class: "list" }, [
```
### 2. Simplified Usage (Automatic Key)
If you omit the third parameter, `$for` will automatically use the array index as the key. This is ideal for simple lists that don't change order frequently.
If you omit the third parameter, `For` will automatically use the array index as the key. This is ideal for simple lists that don't change order frequently.
```javascript
const tags = $(["Tech", "JS", "Web"]);
// No need to pass keyFn if the index is sufficient
Div({ class: "flex gap-1" }, [
$for(tags, (tag) => Badge(tag))
For(tags, (tag) => Badge(tag))
]);
```
@@ -57,7 +57,7 @@ Div({ class: "flex gap-1" }, [
## How it Works (The Reconciliation)
When the `source` signal changes, `$for` performs the following steps:
When the `source` signal changes, `For` performs the following steps:
1. **Key Diffing**: It compares the new keys with the previous ones stored in an internal `Map`.
2. **Node Reuse**: If a key already exists, the DOM node is **reused** and moved to its new position. No new elements are created.
@@ -68,13 +68,13 @@ When the `source` signal changes, `$for` performs the following steps:
## Performance Tips
* **Stable Keys**: Never use `Math.random()` as a key. This will force SigPro to destroy and recreate the entire list on every update, killing performance.
* **State Preservation**: If your list items have internal state (like an input with text), `$for` ensures that state is preserved even if the list is reordered, as long as the key (`id`) remains the same.
* **State Preservation**: If your list items have internal state (like an input with text), `For` ensures that state is preserved even if the list is reordered, as long as the key (`id`) remains the same.
---
## Summary Comparison
| Feature | Standard `Array.map` | SigPro `$for` |
| Feature | Standard `Array.map` | SigPro `For` |
| :--- | :--- | :--- |
| **Re-render** | Re-renders everything | Only updates changes |
| **DOM Nodes** | Re-created every time | **Reused via Keys** |