Merge pull request #35 from buiapp/feature/reactive-model

Feature/reactive model

Author: buiapp

.github/workflows/ci.yml

@@ -45,4 +45,21 @@ jobs:
         run: |
           uv venv .test-venv --python 3.9
           uv pip install --python .test-venv/bin/python dist/*.whl
-          .test-venv/bin/python -c "import reaktiv"
+          .test-venv/bin/python -c "import reaktiv"
+
+  docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5.3.1
+        with:
+          python-version: "3.12"
+
+      - name: Test interactive examples
+        run: uv run --group docs python docs/check_examples.py
+
+      - name: Build documentation
+        run: uv run --group docs mkdocs build --strict

README.md

@@ -32,6 +32,7 @@ uv pip install reaktiv
 - ⚡ **Better performance**: Only recalculates what actually changed (fine-grained reactivity)
 - 🔄 **Automatic updates**: Dependencies are tracked and updated automatically
 - 🎯 **Python-native**: Built for Python's patterns with full async support
+- 🧩 **Application-ready models**: Group state, derived values, effects, resources, and cleanup
 - 🔒 **Type safe**: Full type hint support with automatic inference
 - 🚀 **Lazy evaluation**: Computed values are only calculated when needed
 - 💾 **Smart memoization**: Results are cached and only recalculated when dependencies change
@@ -347,6 +348,69 @@ def increment_age(current: int) -> int:
 age.update(increment_age)  # Type checked!
 ```
 
+## ReactiveModel For Application State
+
+`ReactiveModel` groups a related signal graph into a reusable Python object.
+Each model instance owns independent fields, derived values, effects, and async
+resources.
+
+- `field(...)` declares per-instance writable signals.
+- `@computed` derives cached values.
+- `@linked` creates editable derived state.
+- `@effect` runs model-owned side effects.
+- `@resource` loads asynchronous data from reactive parameters.
+- `dispose()` cleans up all effects and resources owned by the instance.
+
+```python
+from reaktiv import ReactiveModel, computed, effect, field
+
+
+class ShoppingCart(ReactiveModel):
+    unit_price = field(12.50)
+    quantity = field(1)
+    discount = field(0.0)
+
+    @computed
+    def subtotal(self) -> float:
+        return self.unit_price() * self.quantity()
+
+    @computed
+    def total(self) -> float:
+        return self.subtotal() * (1 - self.discount())
+
+    @effect
+    def show_total(self) -> None:
+        print(f"{self.quantity()} item(s): ${self.total():.2f}")
+
+
+cart = ShoppingCart()       # Prints: 1 item(s): $12.50
+cart.quantity.set(3)        # Prints: 3 item(s): $37.50
+cart.discount.set(0.10)     # Prints: 3 item(s): $33.75
+
+cart.dispose()
+```
+
+Each declared field creates a separate `Signal` for every model instance. Use a
+factory for mutable defaults and `field[T]` when the intended type is not clear
+from the value:
+
+```python
+from typing import Optional
+
+
+class SearchModel(ReactiveModel):
+    query = field("")
+    selected_id = field[Optional[str]](None)
+    history = field[list[str]](factory=list)
+```
+
+Read the [ReactiveModel API guide](https://reaktiv.bui.app/docs/api/reactive-model/)
+for fields, typing, linked state, async resources, cleanup, inheritance, and
+mixin patterns. Complete examples:
+
+- [`reactive_model_cart.py`](examples/reactive_model_cart.py)
+- [`reactive_model_linked_resource.py`](examples/reactive_model_linked_resource.py)
+
 ## Why This Pattern?
 
 ```mermaid

docs/advanced-features.md

@@ -6,7 +6,7 @@ This page covers advanced features and techniques in reaktiv for building more s
 
 By default, reaktiv uses identity comparison (`is`) to determine if a signal's value has changed. For more complex types, you can provide custom equality functions:
 
-```python
+```pyodide install="reaktiv" height="22" theme="github_light_default,github_dark"
 from reaktiv import Signal
 
 # Custom equality for dictionaries
@@ -25,6 +25,8 @@ user.set({"name": "Alice", "age": 30})
 
 # This will trigger updates because the "age" value is different
 user.set({"name": "Alice", "age": 31})
+
+print(user())
 ```
 
 Custom equality functions are especially useful for:
@@ -38,7 +40,7 @@ Custom equality functions are especially useful for:
 
 Effects can register cleanup functions that will run before the next execution or when the effect is disposed:
 
-```python
+```pyodide install="reaktiv" assets="no" height="30" theme="github_light_default,github_dark"
 from reaktiv import Signal, Effect
 
 counter = Signal(0)
@@ -83,7 +85,7 @@ This pattern is useful for:
 
 The `to_async_iter` utility lets you use signals with `async for` loops:
 
-```python
+```pyodide install="reaktiv" assets="no" height="25" theme="github_light_default,github_dark"
 import asyncio
 from reaktiv import Signal, to_async_iter
 
@@ -93,7 +95,7 @@ async def main():
     # Start a task that increments the counter
     async def increment_counter():
         for i in range(1, 5):
-            await asyncio.sleep(1)
+            await asyncio.sleep(0.05)
             counter.set(i)
     
     asyncio.create_task(increment_counter())
@@ -104,7 +106,7 @@ async def main():
         if value >= 4:
             break
 
-asyncio.run(main())
+await main()
 ```
 
 Output:
@@ -127,7 +129,7 @@ This is useful for:
 
 You can selectively control which signals create dependencies using `untracked`:
 
-```python
+```pyodide install="reaktiv" assets="no" height="28" theme="github_light_default,github_dark"
 from reaktiv import Signal, Effect, untracked
 
 user_id = Signal(123)
@@ -153,4 +155,7 @@ user_id.set(456)
 
 # This update won't trigger the effect, even though it changes the output
 show_details.set(True)
-```
+
+user_data.set({"name": "Grace"})  # Now tracked because details are visible
+display.dispose()
+```

docs/api/compute-signal.md

@@ -1,12 +1,74 @@
 # Computed Signal API
 
-::: reaktiv.Computed
-    options:
-      show_source: false
-      heading_level: 2
-      show_root_heading: true
-      show_bases: false
-      members_order: source
+`Computed` and `computed` create computed signals: reactive values that derive
+from other signals, recompute lazily, and cache their latest value until a
+dependency changes.
+
+`Computed` is kept as the uppercase constructor-style API. `computed` is the
+preferred lowercase decorator/factory spelling for new code, especially inside
+`ReactiveModel` classes.
+
+## Computed / computed Factory
+
+Create a computed signal from a callable:
+
+```pyodide install="reaktiv" height="12" theme="github_light_default,github_dark"
+from reaktiv import Computed, Signal
+
+price = Signal(10)
+quantity = Signal(2)
+
+total = Computed(lambda: price() * quantity())
+
+print(total())  # 20
+```
+
+Use lowercase decorator syntax for new code:
+
+```pyodide install="reaktiv" assets="no" height="14" theme="github_light_default,github_dark"
+from reaktiv import Signal, computed
+
+price = Signal(10)
+quantity = Signal(2)
+
+@computed
+def total() -> int:
+    return price() * quantity()
+
+print(total())  # 20
+```
+
+When omitting a return annotation, use typed decorator syntax so type checkers
+can preserve the returned signal type:
+
+```pyodide install="reaktiv" assets="no" height="12" theme="github_light_default,github_dark"
+from reaktiv import Signal, computed
+
+name = Signal("Ada")
+
+@computed[str]
+def normalized_name():
+    return name().strip().lower()
+
+print(normalized_name())  # ada
+```
+
+Custom equality can suppress downstream updates when two computed values should
+be treated as equivalent:
+
+```pyodide install="reaktiv" assets="no" height="14" theme="github_light_default,github_dark"
+from reaktiv import Signal, computed
+
+temperature = Signal(21.04)
+
+@computed[float](equal=lambda left, right: round(left, 1) == round(right, 1))
+def rounded_temperature():
+    return temperature()
+
+print(rounded_temperature())
+temperature.set(21.05)
+print(rounded_temperature())
+```
 
 ::: reaktiv.ComputeSignal
     options: