rooibos 0.6.2 → 0.7.0

data/doc/contributors/design/mvu_tea_implementations_research.md

@@ -1,373 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
-
-SPDX-License-Identifier: CC-BY-SA-4.0
--->
-
-# MVU/TEA Implementation Research
-
-## Summary
-
-Research on Model-View-Update (MVU) / The Elm Architecture (TEA) implementations across 15+ frameworks and languages, focusing on initialization patterns.
-
-## Complete List of MVU/TEA Implementations
-
-### 1. **Elm** (Original - JavaScript/Web)
-- **Language**: Elm
-- **Domain**: Web applications
-- **Init Pattern**: `init : () -> (Model, Cmd Msg)`
-  - Takes no arguments (unit type)
-  - Returns tuple of `(Model, Cmd Msg)`
-  - The `Model` is the initial state
-  - The `Cmd Msg` is an initial command/effect
-
-### 2. **Bubble Tea** (Go/TUI)
-- **Language**: Go
-- **Domain**: Terminal UIs
-- **Repository**: charmbracelet/bubbletea
-- **Init Pattern**: `func (m Model) Init() tea.Cmd`
-  - Method on model struct
-  - Returns initial command (`tea.Cmd`)
-  - Model itself is initialized before `Init()` is called
-  - Can return `nil` if no initial command needed
-
-### 3. **TCA (The Composable Architecture)** (Swift)
-- **Language**: Swift
-- **Domain**: iOS/macOS apps
-- **Repository**: pointfreeco/swift-composable-architecture
-- **Init Pattern**: `Store(initialState: State, reducer:)`
-  - Initial state passed to Store constructor
-  - Reducers handle all state transitions
-  - Heavy use of property wrappers for integration with SwiftUI
-
-### 4. **Flutter Bloc** (Dart/Flutter)
-- **Language**: Dart
-- **Domain**: Mobile (iOS/Android), Web, Desktop
-- **Init Pattern**: Constructor-based
-  ```dart
-  class MyBloc extends Bloc<Event, State> {
-    MyBloc() : super(InitialState()) { ... }
-  }
-  ```
-  - Initial state passed to `super()` in constructor
-  - Can dispatch events in constructor for async initialization
-  - Often uses separate `Initial` state class
-
-### 5. **Android MVI** (Kotlin/Android)
-- **Language**: Kotlin
-- **Domain**: Android apps
-- **Init Pattern**: ViewModel with StateFlow
-  ```kotlin
-  private val _state = MutableStateFlow(UiState.initial())
-  val state: StateFlow<UiState> = _state
-  ```
-  - Initial state typically from a factory method or default constructor
-  - ViewModel initializes `StateFlow` with initial state
-  - Intents sent to ViewModel via Channel or SharedFlow
-
-### 6. **Redux** (JavaScript/React)
-- **Language**: JavaScript/TypeScript
-- **Domain**: Web (primarily React, but library-agnostic)
-- **Init Pattern**: Reducer default state
-  ```javascript
-  // Redux Toolkit
-  const slice = createSlice({
-    name: 'counter',
-    initialState: { value: 0 },
-    reducers: { ... }
-  })
-  ```
-  - Initial state defined in slice or as reducer default parameter
-  - Not strictly MVU (no built-in effects), but similar
-  - Redux Thunk/Saga add effect handling
-
-### 7. **Iced** (Rust/GUI)
-- **Language**: Rust
-- **Domain**: Cross-platform GUI
-- **Init Pattern**: `Application::new()` trait method
-  ```rust
-  impl Application for MyApp {
-    fn new(_flags: Flags) -> (Self, Command<Message>) {
-      (initial_state, initial_command)
-    }
-  }
-  ```
-  - Returns tuple `(State, Command)`
-  - Accepts `flags` parameter for runtime context
-  - **NOTABLE**: Flags pattern allows parameterization!
-
-### 8. **Elmish** (F#/Fable)
-- **Language**: F#
-- **Domain**: Web (compiles to JavaScript via Fable)
-- **Init Pattern**: `init : unit -> Model * Cmd<Msg>`
-  - F# implementation of Elm Architecture
-  - Returns tuple of Model and Cmd
-  - Often used with React for rendering
-
-### 9. **Hyperapp** (JavaScript/Web)
-- **Language**: JavaScript
-- **Domain**: Web
-- **Init Pattern**: 
-  ```javascript
-  app({
-    init: initialState,  // or [state, ...effects]
-    view: ...,
-    node: ...
-  })
-  ```
-  - Can be plain object for state only
-  - Can be array `[state, ...effects]` to run effects on startup
-  - Very lightweight (1KB)
-
-### 10. **Meiosis** (JavaScript/Web)
-- **Language**: JavaScript
-- **Domain**: Web (view-library agnostic)
-- **Init Pattern**: 
-  ```javascript
-  meiosis.run({
-    initialModel: { ... },
-    renderer: ...,
-    rootComponent: ...
-  })
-  ```
-  - Emphasizes plain functions and objects
-  - Works with Flyd or Mithril Stream
-  - Very flexible, minimal abstraction
-
-### 11. **SAM Pattern** (JavaScript)
-- **Language**: JavaScript
-- **Domain**: Web
-- **Init Pattern**: State predicate initializes state machine
-  - Based on TLA+ (Temporal Logic of Actions)
-  - Model holds data, State is representation
-  - Init is a state predicate for initial conditions
-
-### 12. **Fabulous** (F#/MAUI)
-- **Language**: F#
-- **Domain**: Mobile (via .NET MAUI)
-- **Init Pattern**: MVU pattern for F#
-  - Similar to Elmish
-  - `init : unit -> Model * Cmd<Msg>`
-
-### 13. **BlazorMVU** (.NET/Blazor)
-- **Language**: C#
-- **Domain**: Web (Blazor)
-- **Init Pattern**: Inspired by Elm and F# MVU
-  - Brings MVU to C# ecosystem
-  - Initial state typically in component initialization
-
-### 14. **MauiReactor** (.NET/MAUI)
-- **Language**: C#
-- **Domain**: Cross-platform mobile/desktop
-- **Init Pattern**: MVU for .NET MAUI
-  - State-driven UI updates
-  - Functional approach to MAUI development
-
-### 15. **MVUX** (.NET)
-- **Language**: C#
-- **Domain**: Cross-platform (Uno Platform)
-- **Init Pattern**: Model-View-Update eXtended
-  - Extends MVU with data binding
-  - Immutable models
-  - Feed-based reactive updates
-
-### 16. **ngx-mvu (Angular MVU)** (TypeScript/Angular)
-- **Language**: TypeScript
-- **Domain**: Web (Angular)
-- **Init Pattern**: Applies Elm Architecture to Angular
-  - Structured approach to Angular apps
-  - Similar update/model/view separation
-
-## Initialization Patterns Analysis
-
-### Pattern 1: Tuple Return (Most Common)
-**Frameworks**: Elm, Bubble Tea, Iced, Elmish, Hyperapp (array variant)
-
-```
-init : Flags -> (Model, Command)
-```
-
-**Characteristics**:
-- Returns both initial state AND initial effect/command
-- Highly composable (can combine child inits)
-- **Flags/context parameter** for runtime initialization
-
-**Example (Iced - Rust)**:
-```rust
-fn new(flags: Flags) -> (MyApp, Command<Message>) {
-  let initial_state = MyApp { count: flags.initial_count };
-  let initial_cmd = Command::none();
-  (initial_state, initial_cmd)
-}
-```
-
-### Pattern 2: Method on Model
-**Frameworks**: Bubble Tea
-
-```go
-func (m Model) Init() tea.Cmd {
-  return fetchDataCmd()
-}
-```
-
-**Characteristics**:
-- Model constructed first, then `Init()` called
-- Only returns command, state already set
-- Less composable (harder to combine states)
-
-### Pattern 3: Constructor/Factory
-**Frameworks**: Flutter Bloc, Android MVI, Redux, TCA
-
-```dart
-MyBloc() : super(InitialState()) {
-  // optional: dispatch initial events
-}
-```
-
-**Characteristics**:
-- Initial state in constructor parameter
-- Effects/commands dispatched separately (if at all)
-- OOP-style initialization
-
-### Pattern 4: Property/Config Object
-**Frameworks**: Hyperapp, Meiosis
-
-```javascript
-app({
-  init: { count: 0 },  // or [state, effect1, effect2]
-  view: ...,
-  update: ...
-})
-```
-
-**Characteristics**:
-- Declarative initialization
-- Can combine state + effects in array format
-- Very flexible
-
-## Key Findings for Rooibos
-
-### ✅ **Flags/Props Pattern is Proven**
-**Iced (Rust)** explicitly uses a `flags` parameter in `new()`:
-```rust
-fn new(flags: Flags) -> (State, Command) { ... }
-```
-
-This directly supports your proposal for:
-- Root fragments: `Init.(argv:, env:)`
-- Child fragments: `Init.(theme: :dark, debug: true)`
-
-### ✅ **Tuple Return (Model, Command) is Standard**
-Almost all functional MVU implementations return `(state, command)`:
-- Elm: `(Model, Cmd Msg)`
-- Iced: `(State, Command<Message>)`
-- Elmish: `(Model, Cmd<Msg>)`
-- Hyperapp: `[state, ...effects]` (array variant)
-
-Your proposal aligns perfectly: `Init = ->(flags) { [model, command] }`
-
-### ✅ **DWIM Return Values**
-Hyperapp allows both:
-- `init: state` (no command)
-- `init: [state, cmd1, cmd2]` (with effects)
-
-This supports your DWIM proposal:
-```ruby
-Init = -> { Model.new(...) }                  # Just model
-Init = -> { [Model.new(...), some_cmd] }      # With command
-```
-
-### ⚠️ **Composition is Critical**
-The OOP frameworks (Bloc, MVI, TCA) struggle with composition:
-- Hard to combine child states in parent's init
-- Usually rely on dependency injection or external configuration
-
-Functional MVU frameworks excel here:
-```elm
--- Elm example
-init flags =
-  let
-    (childModel1, childCmd1) = Child1.init flags.theme
-    (childModel2, childCmd2) = Child2.init flags.debug
-  in
-    ( { child1 = childModel1, child2 = childModel2 }
-    , Cmd.batch [Cmd.map Child1Msg childCmd1, Cmd.map Child2Msg childCmd2]
-    )
-```
-
-Your proposal enables this exact pattern in Ruby!
-
-### 📊 **No Framework Uses Static Constants**
-**CRITICAL**: Not a single MVU framework uses a static constant for initial state in the way we currently do with `INITIAL` or `MODEL`.
-
-All use one of:
-1. **Callable with flags** (Elm, Iced, Elmish)
-2 **Method on instance** (Bubble Tea)
-3. **Constructor parameter** (Bloc, MVI, TCA)
-4. **Config property** (Hyperapp, Meiosis)
-
-The static constant pattern appears to be **unique to our current implementation** and is unsupported by the broader MVU ecosystem.
-
-## Recommendations
-
-### 1. **Adopt `Init` Callable with Flags**
-Most aligned with functional MVU tradition (Elm, Iced, Elmish).
-
-```ruby
-Init = ->(theme: :dark, env: {}) do
-  [Model.new(theme: theme), nil]
-end
-```
-
-### 2. **Support Tuple Return**
-Follow Elm/Iced pattern: `[model, command]`
-
-### 3. **Enable DWIM**
-Like Hyperapp, support both:
-- `Model.new(...)` (no command)
-- `[Model.new(...), cmd]` (with command)
-
-### 4. **Fractal Composition Example**
-From Elm/Iced patterns:
-
-```ruby
-
-module Dashboard
-  Init = ->(theme: :dark) do
-    stats_model, stats_cmd = StatsPanel::Init.(theme: theme)
-    network_model, network_cmd = NetworkPanel::Init.(theme: theme)
-
-    model = Model.new(stats: stats_model, network: network_model)
-    command = Command.batch(
-            Rooibos.route(stats_cmd, :stats),
-            Rooibos.route(network_cmd, :network)
-    )
-
-    [model, command]
-  end
-end
-```
-
-### 5. **Runtime Integration**
-From Iced/Elm patterns:
-
-```ruby
-Rooibos.run(
-        fragment: App,
-        argv: ARGV,
-        env: ENV
-)
-# Internally calls: model, cmd = App::Init.(argv: ARGV, env: ENV)
-```
-
-## Conclusion
-
-Your `Init` callable proposal is **strongly validated** by existing MVU/TEA implementations:
-
-1. ✅ Flags/props for parameterization (Iced, Elm)
-2. ✅ Tuple return of `(model, command)` (Elm, Iced, Elmish)
-3. ✅ DWIM flexibility (Hyperapp)
-4. ✅ Composition-first (all functional MVU)
-5. ❌ Static constants are **not used** by any major framework
-
-The pattern is battle-tested across **15+ implementations** in production systems ranging from web apps to mobile to desktop GUIs.