v0.26.0

0.25.0

New features:

• New format argument on mutableString() extension methods.

  Example:

  final germanFormat = NumberFormat("#,##0.00", "de_DE");
  
  final a = MutableCell(1.0);
  final strA = a.mutableString(format: germanFormat);
  
  a.value = 2.5;
  print(strA.value); // 2,50
  
  strA.value = '12,30';
  print(a.value); // 12.3

v0.25.4

New features:

• coalesce extension method on MutableCells.

  When coalesce is called on a MutableCell, a MutableCell is now returned. This allows
  assigning the value of the cell on which the method is called via the cell returned by coalesce.

  Example:

  final a = MutableCell<int?>(null);
  final b = MutableCell(-1);
  
  // c is a MutableCell
  final c = a.coalesce(b);
  
  ValueCell.watch(() {
    print('A = ${a()}');
  });
  
  ValueCell.watch(() {
    print('C = ${c()}');
  });
  
  b.value = 1; // Prints 'A = 1' and 'C = 1'
  
  // Assigning value of 'c' assigns value of 'a'
  c.value = 2; // Prints 'A = 2' and 'C = 2'
  
  // Doesn't print anything since the value of 'a' is not null
  b.value = 3;

v0.25.3

Fix issue with cell state restoration in widgets.

v0.25.2

Breaking changes:

• The minimum Flutter version has been increased to 3.24.3.

• The live_cells_widgets library is deprecated. Use the live_cells_ui library.

• The live_cells_ui library provides the same functionality as live_cells_widgets
  with the following differences:

  • The widgets are prefixed with Live instead of Cell, e.g. LiveTextField from live_cells_ui
    is the equivalent to CellTextField from live_cell_widgets

  • Only those properties which represent user input are cells, the rest are regular values. For example
    in LiveSwitch only the value and enabled properties are cells.

  • live_cells_ui does not provide wrappers for widgets which do not take input from the user,
    for example there is no LiveText equivalent to CellText. Wrap a regular Text widget in a
    CellWidget.builder or a CellWidget subclass for reactivity.

v0.23.0

New features:

• Watch function keys.

  Watch functions can now be identified by keys, like cells, provided in the ValueCell.watch and
  Watch constructor.

  final w1 = ValueCell.watch(() { ... }, key: 'key1');
  final w2 = ValueCell.watch(() { ... }, key: 'key2');
  
  w1 == w2; // true
  
  // Stops both w1 and w2 since they have the same keys
  w1.stop();

• Watch functions can now be defined directly in the build method of a CellWidget without
  CellHooks:

  CellWidget.builder((_) {
    final cell = MutableCell(...);
  
    ValueCell.watch(() {
      final c = cell();
      ...
    })
    ...
  });

Breaking Changes:

• ValueCell.observe no longer returns the value of the cell. Additionally, this eliminates the need
  to catch exceptions originating from the cell when the caller is only interested in being notified
  when the value of the cell changes, but is not interested in the actual value.

v0.22.0

New Features:

• Watch

  Registers a watch function that has access to its own handle.

  This can be used to 1) stop a watch function directly from within the watch function and 2)
  prevent code from running on the first call of the watch function.

  final watch = Watch((state) {
    final value = a();
    
    state.afterInit();
  
    // The following is only run after the first call
    print('A = $value');
    
    if (value > 10) {
      state.stop();
    }
  });

v0.21.0

New features:

• .asyncState for creating a cell that evaluates to the state of a cell holding a Future.

  .asyncState evaluates to an AsyncState which is a sealed union of:

  • AsyncStateLoading
  • AsyncStateData
  • AsyncStateError

Changes:

• Convert Maybe to a sealed union of:

  • MaybeValue
  • MaybeError

  This change does not break existing code.

v0.20.0

New features:

• SelfCell

  A computed cell which can access it's own value via the self argument:

  final increment = ActionCell();
  final cell = SelfCell((self) {
    increment.observe();
    return self() + 1;
  });

• Action cell chaining with .chain(...)

  .chain(...) creates an action cell that calls a user provided function when triggered. This
  function can decide whether to trigger the chained action or not.

• Null checking utilities:

  • .notNull

    Returns a cell with a value guaranteed to be non-null. If the value of the cell, on which the
    property is used, is null, a NullCellError exception is thrown.

  • .coalesce(...)

    Returns a cell that replaces null values in the cell, on which the method is used, with the value
    of another cell.

New widgets:

• CellBanner
• CellBlockSemantics
• CellVisibility

v0.19.0

New features:

• Effect Cells

  These can be created with .effect() on an action cell (ValueCell<void>). An effect cell
  is guaranteed to only be run once per trigger of the action cell on which the .effect() method
  is called. This is useful for running side effects, while still being able to observe the result
  of the effect as a cell.

  Example:

  final result = action.effect(() async {
      return await submitForm();
  });

• Combining Action Cells:

  Multiple action cells can now be combined into a single cell, which notifies its observers, whenever
  any of the actions trigger, using List.combined

  Example:

  final a1 = ActionCell();
  final a2 = ActionCell();
  
  final all = [a1, a2].combined;

Breaking Changes:

• Async cells created with .wait, .waitLast, .awaited now throw an PendingAsyncValueError
  instead of UninitializedCellError when the cell value is referenced while the future is pending.

  This does not affect code which uses .initialValue to handle these errors.

• Renamed onPressed and onLongPress of cell Material buttons to press and longPress,
  respectively.

  The purpose of this change, is to later allow callback based event handlers to be added using
  onPressed and onLongPress

Other Changes:

• Computed cells no longer run the computation function on initialization. Instead the first run
  of the computation function is deferred to the first time the cell value is referenced.

  NOTE: This changes slightly the semantics of computed cells, especially dynamic computed cells
  which are now dormant until their value is referenced at least once.

• Clarify semantics of ValueCell.none:

  If a null default value is given and ValueCell.none is used during the computation of the
  initial value of a cell, UninitializedCellError is thrown.

• Bug fix: Unhandled exceptions in a ValueCell.watch no longer propagate out of the watch function.

v0.18.0

New features from core:

• Meta Cells

  A meta cell (MetaCell) is a cell that points to another cell. The value of a meta cell is the
  value of the pointed to cell, and its observers are notified when the pointed to cell's value
  changes.

  The pointed to cell can be changed multiple times.

  Example:

  final a = MutableCell(0);
  final b = MutableCell(1);
  
  final meta = MetaCell<int>();
  
  meta.setCell(a);
  print(meta.value); // 0
  
  meta.setCell(b);
  print(meta.value); // 1

• A .hold() method for keeping a cell active until it is released with .release()

  final a = MutableCell(0, key: aKey);
  
  // Ensure that a is active
  final hold = a.hold();
  ...
  // Allow a to be disposed
  hold.release();

New widgets:

• CellElevatedButton
• CellFilledButton
• CellOutlinedButton
• CellTextButton

Breaking Changes:

• Removed dispose() method from MutableCell interface.

• Reading/writing the value of a keyed MutableCell while it is inactive now throws an
  InactivePersistentStatefulCellError.

  Use .hold() to ensure a keyed MutableCell is active before using it.