@ersbeth/picoflow 2.0.2 → 2.1.0

package/docs/guide/advanced/solidjs.md

@@ -1,135 +0,0 @@
-# Use with SolidJS
-
-PicoFlow provides seamless integration with SolidJS through the `@ersbeth/picoflow/solid` module. This integration allows you to use PicoFlow's reactive primitives within SolidJS components, combining PicoFlow's explicit tracking model with SolidJS's automatic dependency tracking.
-
-## Why Use PicoFlow with SolidJS?
-
-PicoFlow and SolidJS complement each other well:
-
-- **PicoFlow** provides explicit control over reactivity with fine-grained tracking
-- **SolidJS** offers automatic dependency tracking within components
-- **Together** you get the best of both worlds: explicit control in your business logic and automatic reactivity in your UI
-
-### When to Use This Integration
-
-Use PicoFlow with SolidJS when:
-
-- ✅ You want explicit control over reactivity in shared business logic
-- ✅ You need fine-grained tracking (e.g., specific array operations)
-- ✅ You're building a library that should work with multiple frameworks
-- ✅ You want to share reactive logic between different UI frameworks
-- ✅ You prefer PicoFlow's explicit tracking model for complex state management
-
-Use pure SolidJS when:
-
-- ✅ Your reactive logic is tightly coupled to components
-- ✅ You prefer automatic dependency tracking everywhere
-- ✅ You don't need fine-grained control over reactivity
-
-## Installation
-
-First, ensure you have both PicoFlow and SolidJS installed:
-
-::: code-group
-
-```bash [pnpm]
-pnpm add @ersbeth/picoflow solid-js
-```
-
-```bash [npm]
-npm install @ersbeth/picoflow solid-js
-```
-
-```bash [yarn]
-yarn add @ersbeth/picoflow solid-js
-```
-
-:::
-
-Then import the integration utilities:
-
-```typescript
-import { from } from '@ersbeth/picoflow/solid'
-import { state, derivation, resource } from '@ersbeth/picoflow'
-```
-
-## PicoFlow to SolidJS
-
-The `from()` function converts PicoFlow observables into SolidJS primitives that work seamlessly in Solid components.
-
-### Basic Conversion
-
-Convert any PicoFlow observable to a Solid primitive:
-
-```typescript
-import { from } from '@ersbeth/picoflow/solid'
-import { state } from '@ersbeth/picoflow'
-
-// Create PicoFlow state
-const $count = state(0)
-
-
-// Use in Solid component
-function Counter() {
-  // Convert to Solid primitive
-  const count = from($count)
-  return <div>Count: {count()}</div>
-}
-```
-
-The `from()` function uses SolidJS's `onMount` and `onCleanup` to properly dispose of the internal PicoFlow effects when the component unmounts. You don't need to manually dispose of converted primitives.
-
-### Conversion Rules
-
-The `from()` function automatically determines the right Solid primitive based on the value type:
-
-| PicoFlow Input | Solid Output | When |
-|----------------|--------------|------|
-| `FlowObservable<T>` (non-Promise) | `SolidDerivation<T>` | Synchronous values |
-| `FlowObservable<Promise<T>>` | `SolidResource<T>` | Asynchronous values |
-| `(t) => T` (getter function) | `SolidDerivation<T>` | Synchronous computation |
-| `(t) => Promise<T>` (getter function) | `SolidResource<T>` | Asynchronous computation |
-
-
-## Complete Examples
-
-```typescript
-import { from } from '@ersbeth/picoflow/solid'
-import { state, derivation } from '@ersbeth/picoflow'
-
-// Create PicoFlow global state and derivation
-const $count = state(0)
-const $isEven = derivation((t) => $count.get(t) % 2 === 0)
-
-// Use in component
-function Counter() {
-
-  // Convert to Solid primitives
-  const count = from($count)
-  const isEven = from($isEven)
-  
-  return (
-    <div>
-      <p>Count: {count()}</p>
-      <p>{isEven.get() ? 'Even' : 'Odd'}</p>
-      <button onClick={() => $count.set(prev => prev + 1)}>Increment</button>
-      <button onClick={() => $count.set(prev => prev - 1)}>Decrement</button>
-    </div>
-  )
-}
-```
-
-## Best Practices
-
-### When to Convert vs Use Directly
-
-**Convert PicoFlow observables (`from()`) when:**
-- ✅ You have existing PicoFlow state/logic to reuse
-- ✅ You want to share reactive logic between frameworks
-- ✅ You need fine-grained PicoFlow features (arrays, maps, streams)
-- ✅ Your business logic is framework-agnostic
-
-**Use Solid primitives directly when:**
-- ✅ The state is only used in Solid components
-- ✅ You don't need PicoFlow's advanced features
-- ✅ You prefer SolidJS's automatic tracking for simple cases

package/docs/guide/introduction/concepts.md

@@ -1,57 +0,0 @@
-# Concepts
-
-Understand the fundamentals of reactive programming and how it simplifies managing your application's state and behavior.
-
-## What is Reactive Programming?
-
-Imagine a **spreadsheet** where you write `=A1 + B1` in cell C1. When you change A1 or B1, C1 automatically updates. That's reactive programming - values that automatically update when their dependencies change.
-
-## Imperative Approach
-
-In traditional programming, you manually update everything:
-
-```typescript
-// Imperative approach
-let count = 0
-let doubledCount = count * 2
-
-function increment() {
-  count++
-  doubledCount = count * 2 // Must remember to update!
-  updateUI(count, doubledCount) // Must remember to update UI!
-}
-```
-
-
-```mermaid
-flowchart LR
-    A[count = 5] --> B[Manually update doubled]
-    B --> C[Manually update UI]
-```
-
-## Reactive Approach
-
-With reactive programming, dependencies update automatically:
-
-```typescript
-// Reactive approach with PicoFlow
-const $count = state(0)
-const $doubled = derivation((t) => $count.get(t) * 2)
-
-subscribe(
-  (t) => ({ count: $count.get(t), doubled: $doubled.get(t) }),
-  (data) => updateUI(data.count, data.doubled) // Runs automatically!
-)
-
-function increment() {
-  $count.set(n => n + 1) // Everything else updates automatically!
-}
-```
-
-```mermaid
-flowchart LR
-    A2[$count.set 5] --> C2[$doubled updates]
-    C2 --> D2[UI effect runs]
-```
-
-**The benefit:** You define relationships once, and they stay synchronized automatically!

package/docs/guide/introduction/conventions.md

@@ -1,30 +0,0 @@
-# Naming Convention
-
-You'll see variables prefixed with `$` throughout PicoFlow examples:
-
-```typescript
-const $count = state(0)
-const $double = derivation((t) => $count.get(t) * 2)
-```
-
-This is a **naming convention** to make reactive values stand out. It helps you quickly identify:
-- Which values are reactive
-- Which values will cause re-executions when changed
-- Where your state lives
-
-Think of `$` as a visual marker: "This value is special - it's reactive!"
-
-### Examples
-
-```typescript
-// Reactive values - use $ prefix
-const $userName = state('Alice')
-const $userAge = state(25)
-const $isAdult = derivation((t) => $userAge.get(t) >= 18)
-
-// Plain values - no $ prefix
-const currentName = await $userName.pick()  // Snapshot of current value
-const maxAge = 100                     // Constant
-```
-
-

package/docs/guide/introduction/getting-started.md

@@ -1,139 +0,0 @@
-# Getting Started
-
-Welcome to PicoFlow! This guide will help you install PicoFlow and build your first reactive application in just a few minutes.
-
-## Why PicoFlow?
-
-PicoFlow is a lightweight reactive library with a focus on **explicit control** and **simplicity**. Unlike some reactive libraries that track everything automatically, PicoFlow gives you precise control over what is reactive and what isn't.
-
-### Key Philosophy
-
-1. **Explicit Tracking** - You decide what to track with `.get(t)`
-2. **Fine-grained Control** - React to specific operations, not just "something changed"
-3. **No Magic** - Simple, predictable behavior
-4. **TypeScript First** - Full type safety and inference
-
-## Installation
-
-Install PicoFlow using your preferred package manager:
-
-::: code-group
-
-```bash [pnpm]
-pnpm add @ersbeth/picoflow
-```
-
-```bash [npm]
-npm install @ersbeth/picoflow
-```
-
-```bash [yarn]
-yarn add @ersbeth/picoflow
-```
-
-:::
-
-If you plan to use the SolidJS integration, install SolidJS as a peer dependency:
-
-::: code-group
-
-```bash [pnpm]
-pnpm add solid-js
-```
-
-```bash [npm]
-npm install solid-js
-```
-
-```bash [yarn]
-yarn add solid-js
-```
-
-:::
-
-Import the primitives you need:
-
-```typescript
-import { state, derivation, subscribe } from '@ersbeth/picoflow'
-```
-
-For SolidJS integration:
-
-```typescript
-import { from } from '@ersbeth/picoflow'
-```
-
-## Your First PicoFlow App
-
-Let's build a simple counter with PicoFlow:
-
-```typescript
-import { state, derivation, subscribe } from '@ersbeth/picoflow'
-
-// Create reactive state (prefix with $ by convention)
-const $count = state(0)
-
-// Create a computed value
-const $isEven = derivation((t) => {
-  return $count.get(t) % 2 === 0
-})
-
-// React to changes
-subscribe(
-  (t) => ({ count:$count.get(t), even:$isEven.get(t)}),
-  (data) => {
-    console.log(`Count is ${data.count}, which is ${data.even ? 'even' : 'odd'}`)
-  }
-)
-// Logs "Count is 0, which is even"
-
-// Update the state
-$count.set(1) // Logs: "Count is 1, which is odd"
-$count.set(2) // Logs: "Count is 2, which is even"
-$count.set(3) // Logs: "Count is 3, which is odd"
-```
-
-### What Just Happened?
-
-1. **State** (`$count`) - Holds a mutable value
-2. **Derivation** (`$isEven`) - Computes a value based on state
-3. **Subscribe** - Creates an effect that runs automatically when dependencies change
-4. **Data function** `(t) => ...` - Tracks dependencies and returns data
-5. **Callback** `(data) => ...` - Performs side effects with the data
-6. **`.get(t)`** - Reads a value AND creates a dependency
-7. **`.set()`** - Updates state, triggering subscribers
-
-### Data Flow
-
-Here's what happens when you call `$count.set(1)`:
-
-```mermaid
-sequenceDiagram
-    participant User
-    participant $count
-    participant $isEven
-    participant Subscribe
-    
-    User->>$count: set(1)
-    activate $count
-    Note over $count: Updates value 0 → 1
-    $count->>$isEven: notify()
-    Note over $isEven: Marks as dirty (lazy recompute)
-    $count->>Subscribe: notify()
-    deactivate $count
-    
-    activate Subscribe
-    Note over Subscribe: Execute data function
-    Subscribe->>$count: get(t)
-    $count-->>Subscribe: 1
-    Subscribe->>$isEven: get(t)
-    activate $isEven
-    Note over $isEven: Recomputes because dirty
-    $isEven->>$count: get(t)
-    $count-->>$isEven: 1
-    $isEven-->>Subscribe: false
-    deactivate $isEven
-    Note over Subscribe: Call callback with {count: 1, even: false}
-    Note over Subscribe: Logs: "Count is 1, which is odd"
-    deactivate Subscribe
-```