Jolt Flutter

A Flutter integration package for Jolt reactive state management.

Jolt Flutter provides Flutter-specific widgets and utilities for working with Jolt signals, computed values, and reactive state. It includes widgets like JoltBuilder for reactive UI updates and seamless integration with Flutter's ValueNotifier system.

Features

• 🎯 Reactive Widgets: JoltBuilder and JoltSelector for automatic UI updates
• 🔄 ValueNotifier Integration: Seamless bridge between Jolt signals and Flutter's ValueNotifier
• ⚡ Performance Optimized: Fine-grained rebuilds with selector-based updates
• 🎨 Flutter Native: Works with all Flutter widgets and animations
• 🛠️ Resource Management: Automatic cleanup and disposal
• 📦 Collection Support: Reactive List, Map, Set widgets
• 🔄 Async Support: Built-in async state handling

For full API reference and detailed usage examples, check the inline comments in the source code and the Documentation.

Quick Start

import 'package:flutter/material.dart';
import 'package:jolt_flutter/jolt_flutter.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  final counter = Signal(0);

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: JoltBuilder(
          builder: (context) => Text('Count: ${counter.value}'),
        ),
        floatingActionButton: FloatingActionButton(
          onPressed: () => counter.value++,
          child: Icon(Icons.add),
        ),
      ),
    );
  }
}

Core Widgets

JoltBuilder

Automatically rebuilds when any signal accessed in its builder changes:

final counter = Signal(0);
final name = Signal('Flutter');

JoltBuilder(
  builder: (context) => Column(
    children: [
      Text('Hello ${name.value}'),
      Text('Count: ${counter.value}'),
      ElevatedButton(
        onPressed: () => counter.value++,
        child: Text('Increment'),
      ),
    ],
  ),
)

JoltSelector

Rebuilds only when a specific selector function's result changes:

final user = Signal(User(name: 'John', age: 30));

// Only rebuilds when the user's name changes, not age
JoltSelector(
  selector: () => user.value.name,
  builder: (context) => Text('Hello ${user.value.name}'),
)

JoltResource

A widget that provides local component state management with lifecycle callbacks:

class CounterStore implements JoltState {
  final counter = Signal(0);
  Timer? _timer;

  CounterStore(BuildContext context) : super(context);

  @override
  void onMount() {
    _timer = Timer.periodic(Duration(seconds: 1), (_) {
      counter.value++;
    });
  }

  @override
  void onUnmount() {
    _timer?.cancel();
  }
}

JoltResource<CounterStore>(
  create: (context) => CounterStore(context),
  builder: (context, store) => Text('Count: ${store.counter.value}'),
)

Simple Builder

For cases without state management:

JoltResource.builder(
  builder: (context) => Text('Value: ${signal.value}'),
)

ValueNotifier Integration

JoltValueNotifier

Bridge Jolt signals with Flutter's ValueNotifier system:

final counter = Signal(0);
final notifier = counter.notifier; // Returns JoltValueNotifier

// Use with AnimatedBuilder
AnimatedBuilder(
  animation: notifier,
  builder: (context, child) => Text('Count: ${counter.value}'),
)

// Use with ValueListenableBuilder
ValueListenableBuilder<int>(
  valueListenable: notifier,
  builder: (context, value, child) => Text('Count: $value'),
)

Automatic Synchronization

ValueNotifier automatically syncs with Jolt signal changes:

final signal = Signal(0);
final notifier = signal.notifier;

// Changes to signal automatically update notifier
signal.value = 42; // notifier.value is now 42

Flutter Integration Examples

With Async Operations

final userSignal = AsyncSignal.fromFuture(fetchUser());

JoltBuilder(
  builder: (context) {
    final state = userSignal.value;
    if (state.isLoading) return CircularProgressIndicator();
    if (state.isError) return Text('Error: ${state.error}');
    return Text('User: ${state.data}');
  },
)

With Collections

final items = ListSignal(['apple', 'banana']);

JoltBuilder(
  builder: (context) => ListView.builder(
    itemCount: items.length,
    itemBuilder: (context, index) => ListTile(
      title: Text(items[index]),
    ),
  ),
)

Performance Tips

Use JoltSelector for Fine-Grained Updates

final user = Signal(User(name: 'John', age: 30));

// Only rebuilds when name changes
JoltSelector(
  selector: () => user.value.name,
  builder: (context) => Text('Hello ${user.value.name}'),
)

Flutter Widget Integration

With AnimatedBuilder

final counter = Signal(0);

AnimatedBuilder(
  animation: counter.notifier,
  builder: (context, child) => Text('Count: ${counter.value}'),
)

With ValueListenableBuilder

final counter = Signal(0);

ValueListenableBuilder<int>(
  valueListenable: counter.notifier,
  builder: (context, value, child) => Text('Count: $value'),
)

Important Notes

Widget Lifecycle

• JoltBuilder automatically tracks signal dependencies
• Widgets rebuild only when tracked signals change
• Use JoltSelector for performance optimization

Memory Management

• Signals are automatically disposed when widgets are disposed
• Use JoltResource for manual resource management
• ValueNotifier integration handles cleanup automatically

Performance Tips

• Use JoltSelector for fine-grained updates
• Batch multiple signal updates with batch()
• Avoid accessing signals in widget constructors

License

This project is licensed under the MIT License - see the LICENSE file for details.