Upd changelog and package info, added documentation

CHANGELOG.md

@@ -1,3 +1,10 @@
+## 3.1.0
+
+- Added DebugLogger interface and default implementation for it
+- Extend UIDriver API
+- Extend UIElementController API
+- Models of actions and events and some models for animations have been moved to the kernel 
+
 ## 3.0.0
 
 - Rename: DuitScript -> ScriptDefinition

lib/src/action_api/action.dart

@@ -1,5 +1,6 @@
 import 'package:duit_kernel/duit_kernel.dart';
 
+/// The [ServerAction] class represents an action that was sent by the server.
 base class ServerAction {
   static late final Parser<ServerAction> _actionParser;
 
@@ -35,6 +36,10 @@ base class ServerAction {
       _actionParser.parse(json);
 }
 
+/// An unknown action is an action that the framework does not know how to parse.
+///
+/// This can happen if the framework is not configured correctly or if the
+/// server sends an action that is not recognized.
 final class UnknownAction extends ServerAction {
   UnknownAction()
       : super(
@@ -43,6 +48,11 @@ final class UnknownAction extends ServerAction {
         );
 }
 
+/// A local action is an action that is executed locally in the client.
+///
+/// A local action is an action that is not sent to the server and is executed
+/// immediately in the client. A local action is typically used to execute a
+/// local event handler.
 final class LocalAction extends ServerAction {
   final ServerEvent event;
 
@@ -60,6 +70,11 @@ final class LocalAction extends ServerAction {
   }
 }
 
+/// A dependent action is an action that has dependencies.
+///
+/// A dependent action is an action that requires other actions to be executed
+/// before it can be executed. The dependencies are specified in the
+/// [dependsOn] property.
 abstract interface class DependentAction {
   final Iterable<ActionDependency> dependsOn;
 
@@ -68,6 +83,14 @@ abstract interface class DependentAction {
   });
 }
 
+/// A transport action represents an action that is executed using a transport mechanism.
+///
+/// A transport action is an action that requires communication with the server
+/// to be executed. It implements the [DependentAction] interface, which means it
+/// has dependencies that need to be resolved before execution. The action can also
+/// include optional metadata, represented by the [meta] property, which may contain
+/// additional information required for execution.
+
 final class TransportAction extends ServerAction implements DependentAction {
   final HttpActionMetainfo? meta;
 
@@ -90,6 +113,12 @@ final class TransportAction extends ServerAction implements DependentAction {
   }
 }
 
+/// A script action represents an action that is executed using a script.
+///
+/// A script action is an action that requires the execution of a script to be
+/// executed. It implements the [DependentAction] interface, which means it
+/// has dependencies that need to be resolved before execution. The script
+/// to be executed is represented by the [script] property.
 final class ScriptAction extends ServerAction implements DependentAction {
   final ScriptDefinition script;
 

lib/src/action_api/action_parser.dart

@@ -1,5 +1,9 @@
 import 'package:duit_kernel/duit_kernel.dart';
 
+/// The [DefaultActionParser] is a default parser for [ServerAction] objects.
+///
+/// It uses a [ServerActionJsonView] to parse the JSON map into a concrete action
+/// object based on the [ExecutionType] of the action.
 final class DefaultActionParser implements Parser<ServerAction> {
   @override
   ServerAction parse(Map<String, dynamic> json) {

lib/src/action_api/event_parser.dart

@@ -1,5 +1,12 @@
 import 'package:duit_kernel/duit_kernel.dart';
 
+/// The [DefaultEventParser] is a default parser for [ServerEvent] objects.
+///
+/// It uses a simple switch statement to parse the JSON map into a concrete event
+/// object based on the value of the "type" property of the JSON map.
+///
+/// The [DefaultEventParser] is used by the [DefaultEventResolver] to parse events
+/// from the server.
 final class DefaultEventParser implements Parser<ServerEvent> {
   @override
   ServerEvent parse(Map<String, dynamic> json) {

lib/src/driver_api/ui_controller.dart

@@ -41,7 +41,12 @@ abstract interface class UIElementController<T> {
   /// It can be used to categorize or identify the controller.
   abstract String? tag;
 
-  abstract Map<String, StreamController<AnimationCommand>> commandChannel;
+  /// A stream of animation commands.
+  ///
+  /// The [commandChannel] property represents a stream of animation commands
+  /// that are sent to the controller. The commands are processed by the controller
+  /// in order to perform the desired animation.
+  abstract StreamController<AnimationCommand> commandChannel;
 
   /// Perform the related action.
   ///
@@ -82,9 +87,27 @@ abstract interface class UIElementController<T> {
   /// RemoveListener the [ChangeNotifier].
   void removeListener(VoidCallback listener);
 
+  /// Listen for animation commands.
+  ///
+  /// This method allows you to register a callback function that will be
+  /// triggered whenever an [AnimationCommand] is received. The callback
+  /// function should be a [Future<void> Function(AnimationCommand command)]
+  /// and will be executed with the received command as its argument.
   void listenCommand(Future<void> Function(AnimationCommand command) callback);
 
+  /// Emit an animation command.
+  ///
+  /// This method can be used to emit an animation command to any widgets that
+  /// are listening for commands. The command will be sent to all widgets that
+  /// are listening.
+  ///
+  /// The method takes a single parameter of type [AnimationCommand] which is
+  /// the command to be emitted.
   FutureOr<void> emitCommand(AnimationCommand command);
 
+  /// Remove the command listener.
+  ///
+  /// This method is used to remove the listener that was previously registered
+  /// with the [listenCommand] method.
   void removeCommandListener();
 }

lib/src/driver_api/ui_driver.dart

@@ -3,7 +3,6 @@ import 'dart:async';
 import 'package:duit_kernel/duit_kernel.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter/services.dart';
-import 'package:meta/meta.dart';
 
 abstract interface class UIDriver {
   /// The source url of the UI driver.
@@ -105,9 +104,9 @@ abstract interface class UIDriver {
   /// Set the BuildContext.
   set context(BuildContext value);
 
-  @internal
+  /// Prepares the payload for a server action.
   Map<String, dynamic> preparePayload(Iterable<ActionDependency> dependencies);
 
-  @internal
+  /// Updates the attributes of a controller.
   Future<void> updateAttributes(String controllerId, Map<String, dynamic> json);
 }

lib/src/index.dart

@@ -6,4 +6,3 @@ export 'view_attributes/index.dart';
 export 'misc/index.dart';
 export 'animation_api/index.dart';
 export 'action_api/index.dart';
-export 'package:meta/meta.dart' show internal, experimental, mustBeOverridden;

pubspec.yaml

@@ -1,6 +1,6 @@
 name: duit_kernel
 description: "Core library for flutter_duit package.  Contains reusable models for developing third-party packages."
-version: 3.0.0
+version: 3.1.0
 repository: https://github.com/lesleysin/duit_kernel
 
 environment:
@@ -11,7 +11,6 @@ dependencies:
   ansicolor: ^2.0.3
   flutter:
     sdk: flutter
-  meta: ^1.15.0
 
 dev_dependencies:
   flutter_test: