docs: readme improvement

Author: mattrltrent

README.md

@@ -1,16 +1,6 @@
-# example
 
-A new Flutter project.
+# Simple Weather App Source Code
 
-## Getting Started
+This is the source code for the simple weather app using the [`trent`](https://pub.dev/packages/trent) package.
 
-This project is a starting point for a Flutter application.
-
-A few resources to get you started if this is your first Flutter project:
-
-- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
-
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+<img src="https://raw.githubusercontent.com/mattrltrent/random_assets/refs/heads/main/trent_weather.gif" height="500px"/>

example/README.md

@@ -1,5 +1,6 @@
 import 'dart:math';
 
+import 'package:flutter/cupertino.dart';
 import 'package:flutter/material.dart';
 import 'package:trent/trent.dart';
 
@@ -48,15 +49,14 @@ class _HomeScreenState extends State<HomeScreen> {
 
     return Scaffold(
       appBar: AppBar(
-        title: map<WeatherTrent, WeatherTypes>(context, (mapper) {
+        title: watchMap<WeatherTrent, WeatherTypes>(context, (mapper) {
           mapper
-            ..as<Data>((state) => Text("Weather for lat/long: ${state.location}"))
             ..as<NoData>((state) => const Text("Enter Location"))
             ..as<Loading>((state) => const Text("Fetching Weather..."))
             ..orElse((state) => const Text("Weather App"));
         }),
       ),
-      floatingActionButton: watch<WeatherTrent>(context).currState is Data
+      floatingActionButton: watch<WeatherTrent>(context).state is Data
           ? FloatingActionButton(
               onPressed: () => weatherTrent.clear(),
               child: const Icon(Icons.clear),
@@ -75,6 +75,7 @@ class _HomeScreenState extends State<HomeScreen> {
             }),
           listenStates: (mapper) => mapper
             ..as<NoData>((state) {
+              print("HELLO!");
               _latitudeController.clear();
               _longitudeController.clear();
             }),
@@ -115,17 +116,20 @@ class _HomeScreenState extends State<HomeScreen> {
                   child: const Text("Fetch Weather"),
                 ),
                 const SizedBox(height: 16),
-                Digester<WeatherTrent, WeatherTypes>(
-                  child: (mapper) {
-                    mapper
-                      ..as<NoData>((state) => const Text("Please enter location to fetch weather."))
-                      ..as<Loading>((state) => const CircularProgressIndicator())
-                      ..as<Data>((state) => Text(
-                            "${state.location} has temperature ${state.temperature}°C",
-                            style: const TextStyle(fontSize: 18),
-                          ))
-                      ..orElse((state) => const Text("Unknown state"));
-                  },
+                Container(
+                  constraints: BoxConstraints(minHeight: 200),
+                  child: Digester<WeatherTrent, WeatherTypes>(
+                    child: (mapper) {
+                      mapper
+                        ..as<NoData>((state) => const Text("Please enter location to fetch weather."))
+                        ..as<Loading>((state) => const CupertinoActivityIndicator())
+                        ..as<Data>((state) => Text(
+                              "${state.location} has temperature ${state.temperature}°C",
+                              style: const TextStyle(fontSize: 18),
+                            ))
+                        ..orElse((state) => const Text("Unknown state"));
+                    },
+                  ),
                 ),
               ],
             ),
@@ -138,9 +142,14 @@ class _HomeScreenState extends State<HomeScreen> {
 
 // ====== trents/weather_trent.dart ======
 
-class WeatherTypes extends Equatable {
+class WeatherTypes extends EquatableCopyable<WeatherTypes> {
   @override
   List<Object> get props => [];
+
+  @override
+  WeatherTypes copyWith() {
+    return this;
+  }
 }
 
 class NoData extends WeatherTypes {}
@@ -153,6 +162,11 @@ class Error extends WeatherTypes {
 
   @override
   List<Object> get props => [message];
+
+  @override
+  Error copyWith({String? message}) {
+    return Error(message ?? this.message);
+  }
 }
 
 class Data extends WeatherTypes {

example/lib/main.dart

@@ -13,10 +13,10 @@ T watch<T extends Trents>(BuildContext context) {
   return Provider.of<T>(context, listen: true);
 }
 
-/// Retrieve a widget for the current state of a Trent reactively.
-Widget map<T extends Trents<S>, S>(BuildContext context, void Function(WidgetSubtypeMapper<S>) configure) {
+/// Retrieve a map over the current state of a Trent reactively.
+Widget watchMap<T extends Trents<S>, S>(BuildContext context, void Function(WidgetSubtypeMapper<S>) configure) {
   final trent = Provider.of<T>(context, listen: true);
-  final mapper = WidgetSubtypeMapper<S>(trent.currState);
+  final mapper = WidgetSubtypeMapper<S>(trent.state);
 
   // Configure the mapper with handlers
   configure(mapper);

lib/src/logic/accessors.dart

@@ -29,10 +29,10 @@ abstract class Trents<Base> extends ChangeNotifier {
   final Map<Type, Option<Base>> _lastStates = {};
 
   /// Getter method for the current state.
-  Base get currState => _state;
+  Base get state => _state;
 
   /// Getter method for the current state by type.
-  LogicSubTypeMapper<Base> get currStateMapper => LogicSubTypeMapper<Base>(_state);
+  LogicSubTypeMapper<Base> get stateMap => LogicSubTypeMapper<Base>(_state);
 
   /// Getter method for the state stream. Usually not used directly.
   Stream<Base> get stateStream => _stateSubject.stream;
@@ -122,9 +122,13 @@ abstract class Trents<Base> extends ChangeNotifier {
   }
 }
 
+abstract class EquatableCopyable<T> extends Equatable implements Copyable<T> {}
+
+abstract class Copyable<T> {
+  T copyWith();
+}
+
 /// A generic Trent that manages state transitions.
-abstract class Trent<Base extends Equatable> extends Trents<Base> {
-  Trent(
-    super.state,
-  );
+abstract class Trent<Base extends EquatableCopyable<Base>> extends Trents<Base> {
+  Trent(super.state);
 }

lib/src/logic/trent.dart

@@ -35,12 +35,13 @@ class AlerterState<TrentType extends Trents<StateType>, StateType> extends State
   late final TrentType sm = get<TrentType>(context);
   late StateType _previousAlert; // Tracks the previous alert state
   late StateType _previousState; // Tracks the previous normal state
+  bool _hasInitialStateTriggered = false; // Tracks if the initial state has been emitted
 
   @override
   void initState() {
     super.initState();
-    _previousAlert = sm.currState;
-    _previousState = sm.currState;
+    _previousAlert = sm.state;
+    _previousState = sm.state;
 
     // Listen to the alert stream
     sm.alertStream.listen((alert) {
@@ -56,6 +57,11 @@ class AlerterState<TrentType extends Trents<StateType>, StateType> extends State
 
     // Listen to the state stream
     sm.stateStream.listen((state) {
+      if (!_hasInitialStateTriggered) {
+        _hasInitialStateTriggered = true; // Skip the first seeded state
+        return;
+      }
+
       if (widget.listenStates != null) {
         final shouldTrigger = widget.listenStatesIf?.call(_previousState, state) ?? true;
         if (shouldTrigger) {

lib/src/widgets/alerter.dart

@@ -15,15 +15,15 @@ class Digester<TrentType extends Trents<StateType>, StateType> extends Stateless
   @override
   Widget build(BuildContext context) {
     // Retrieve the Trent instance dynamically from the context
-    final sm = get<TrentType>(context);
-    final mapper = WidgetSubtypeMapper<StateType>(sm.currState);
+    final sm = watch<TrentType>(context);
+    final mapper = WidgetSubtypeMapper<StateType>(sm.state);
 
     // Register handlers for each state type
     child(mapper);
 
     return StreamBuilder<StateType>(
       stream: sm.stateStream, // Plug into the Trent's state stream
-      initialData: sm.currState, // Provide the initial state
+      initialData: sm.state, // Provide the initial state
       builder: (context, snapshot) {
         // Resolve the widget for the current state
         return mapper.resolve();

lib/src/widgets/digester.dart

@@ -15,7 +15,6 @@ dependencies:
   flutter:
     sdk: flutter
   equatable: ^2.0.7
-  get_it: ^8.0.3
   rxdart: ^0.28.0
   provider: ^6.1.2