fst 0.1.1

Perfect cohabitation of Widget and State trees.

Flutter State Tree

Perfect cohabitation of Widget and State trees.

Documentation

• state<T>(T Function() stateFn, [Record? dependencies])

state

Appends a state leaf to this node. Returns a tuple of the value and a setter to update it.

StateTreeBuilder((context, n) {
   final (value, setValue) = n.state(() => 0);

   return Column(
      children: [
        Text(value.toString()),
        ElevatedButton(
           child: Text('Increment'),
           onPressed: () => setValue(value + 1),
        ),
      ],
   );
});

state takes a record with dependencies, which will be used to determine whether the state function should be called again and returned value used to override current value.

StateTreeBuilder((context, n) {
  final (dependency, setDependency) = n.state(() => 0);
  final (value, setValue) = n.state(() => 0, (dependency,));

  return Column(
    children: [
      Text(value.toString()),
      ElevatedButton(
        child: Text('Increment'),
        onPressed: () => setValue(value + 1),
      ),
      ElevatedButton(
        child: Text('Reset'),
        onPressed: () => setDependency(dependency + 1),
      ),
    ],
  );
});

// Press "Increment": value is 1
// Press "Increment": value is 2
// Press "Increment": value is 3
// Press "Reset": value is 0

effect

Calls a function on first build. Calls a function when dependency changes.

StateTreeBuilder((context, n) {
  final (dependency, setDependency) = n.state(() => 0);
  n.effect(() => print('effect called'), (dependency,));

  return Column(
    children: [
      Text(value.toString()),
      ElevatedButton(
        child: Text('Increment'),
        onPressed: () => setDependency(dependency + 1),
      ),
    ],
  );
});

// Prints "effect called" on first build
// Prints "effect called" on every "Increment" press

provide

Provides a value to the descendants. Provided value could be read by consume or query.

StateTreeBuilder((context, n) {
  final (value, setValue) = n.state(() => 0);
  n.provide(value);

  return Column(
    children: [
      Text(value.toString()),
      ElevatedButton(
        child: Text('Increment'),
        onPressed: () => setValue(value + 1),
      ),
      Counter(),
    ],
  );
});

class Counter extends StateTreeWidget {
  const Counter({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context, StateTreeNode n) {
    // rebuilds on every "Increment" press
    final value = n.consume<int>();
    return Text(value.toString());
  }
}

Provider shadowing

When multiple values are provided with the same type, the closest one is used.

StateTreeBuilder((context, n) {
  n.provide(42);

  // ...
  return StateTreeBuilder((context, n) {
    n.provide(15);

    return StateTreeBuilder((context, n) {
      final value = n.consume<int>(); // 15

      return Text(value.toString());
    });
  });
});

To distinguish between values of the same type, use token parameter.

StateTreeBuilder((context, n) {
  n.provide(42, token: #outer);

  // ...
  return StateTreeBuilder((context, n) {
    n.provide(15, token: #inner);

    return StateTreeBuilder((context, n) {
      final outer = n.consume<int>(token: #outer); // 42
      final inner = n.consume<int>(token: #inner); // 15

      return Text(value.toString());
    });
  });
});

License

MIT