Ribir Documentation

The Ribir Gallery is an interactive showroom and learning resource for the Ribir declarative GUI framework. It is organized into four sections to help developers progress from seeing results to understanding core engineering concepts:

1. Showcase: Demonstrates complex, real-world applications (e.g., Wordle Game, Messages App, Pomodoro Timer) to highlight state management ($state), complex layouts, and performance.
2. Widgets: An interactive dictionary of built-in UI components (Inputs, Data Display, Navigation, Layouts, etc.) based on Material Design principles. Each component includes interactive previews and copy-pasteable declarative code snippets.
3. Animations: Showcases Ribir's zero-boilerplate approach to animations, including transitions, state-driven motion, and easing curves using minimal Transition configurations.
4. Concepts: Deep dives into Ribir's core pillars, such as reactivity (granular updates without a Virtual DOM), 'Fat Objects' (applying styles like margin or radius directly), and the fn_widget! declarative macro.

Variant is a wrapper around the Provider system that unifies the API for consuming both static values and dynamic/reactive states.

Instead of choosing between Provider::of (for static) and Provider::state_of (for reactive), you use Variant. It automatically detects if a provider is a watcher provider (reactive) or a value provider (static).

Key Advantages

• Unified API: Use Variant::new regardless of the underlying data type.
• Automatic Reactivity: If the provider is a watcher, the widget automatically updates when the value changes.
• Easy Mapping: Use .map() to transform values while preserving reactivity.
• Built-in Fallbacks: Use new_or(), new_or_default(), or new_or_else() to handle missing providers.

// Automatically gets Color from provider (static or reactive)
let color = Variant::<Color>::new(BuildCtx::get()).unwrap();

@Container {
    size: Size::new(100., 100.),
    background: color,
}

The watch! macro creates a subscribable rxRust stream that monitors all $-marked states in an expression.

Difference between pipe! and watch!:

• pipe! = (initial value + rxRust stream). Use this to initialize widget properties.
• watch! = rxRust stream only. Use this when you need to manually subscribe to changes to perform side effects (like manual state writes).

Lifecycle Management: When you call .subscribe() on a watch! macro, you must manage the subscription lifecycle:

1. Manual Unsubscribe: If the subscription's lifecycle is shorter than the state it listens to (e.g., using external state in a widget), call .unsubscribe() in the widget's on_disposed handler.
2. Circular References: If the downstream of a watch! subscription performs a write operation on the state being watched, you must manually call .unsubscribe() to prevent memory leaks caused by circular references.

// Example: Manual subscription with lifecycle management
fn show_name(name: Stateful<String>) -> Widget<'static> {
  fn_widget!{
    let mut text = @Text { text: "Hi, Guest!" };
    let u = watch!($read(name).to_string()).subscribe(move |name| {
      $write(text).text = format!("Hi, {}!", name).into();
    });

    // Unsubscribe when the widget is destroyed to avoid leaks
    @(text) { on_disposed: move |_| u.unsubscribe() }
  }
  .into_widget()
}

To make widgets interactive, you must use State, which makes data watchable and shareable.

The State Lifecycle

1. Initialize: Convert data into state using Stateful::new(value).
2. Map: Declare how state maps to the view.
3. Interact: Modify data through state (e.g., in event handlers).
4. Update: Ribir automatically updates the view when state changes.

$ Syntactic Sugar

• $read(state): Returns a read reference to the state.
• $write(state): Returns a write reference to the state.

When used inside a move closure, $read and $write automatically handle state cloning (e.g., $write(count) expands to using a clone_writer()), allowing for easy state sharing across event handlers.

use ribir::prelude::*;

fn main() {
  App::run(fn_widget! {
    // 1. Initialize state
    let count = Stateful::new(0);
    
    @Button {
      // 2. Modify state on interaction
      on_tap: move |_| *$write(count) += 1,
      
      // 3. Map state to view (using pipe! for transformations)
      @ pipe!($read(count).to_string())
    }
  });
}

Ribir distinguishes between live interaction and finalized data through two primary event types:

| Event | Trigger | Behavior | | :--- | :--- | : | | on_change | User interaction (drag, type, click) | Fires frequently (every tick/keystroke). Represents live intent. | | on_submit | Explicit commit (Enter, Blur) | Fires once on completion. Represents finalized data. |

Choosing the right event for your widget category

Immediate Feedback Widgets (e.g., Slider, Checkbox, Switch, Tabs):

• These widgets have meaning at every intermediate step.
• Use on_change as the primary event.

Submit-Confirm Widgets (e.g., Input, TextArea):

• The value is often in-progress until committed.
• Use on_submit for committing finalized data (e.g., form submission, search query).
• Use on_change for real-time feedback (e.g., live validation, search-as-you-type, password strength).