feat: added doc on events

sidebar.ts

@@ -22,6 +22,10 @@ export const sidebar = [
       'guides/project-structure',
       'guides/using-plugins',
       'guides/adding-packages',
+      {
+        slug: 'guides/events',
+        badge: { text: 'New', variant: 'note' },
+      },
       {
         label: 'CMS',
         items: [

src/content/docs/guides/events.mdx

@@ -0,0 +1,163 @@
+---
+title: Events
+description:
+  Events are a way to get notified of important lifecycle events in the Vyuh
+  Framework as well to communicate between features.
+---
+
+import { Aside } from '@astrojs/starlight/components'
+
+Events are a way to get notified of important lifecycle events in the Vyuh
+Framework as well to communicate between features.
+
+The framework leverages a built-in `EventPlugin` to handle the propagation of
+events. It is a global event system that even allows features to communicate
+with each other. The event plugin can be referenced with `vyuh.event`.
+
+## Listening for Events
+
+To listen for an event, you can use the `on` method on `vyuh.event`. The
+`on<T>()` method is a generic method based on the type of the Event and takes a
+typed-listener that matches the generic type. The method returns a disposer
+function that be invoked at a later point to cancel the event listener.
+
+A typical place to set up an event-listener would be in the `init` method of a
+feature.
+
+```dart title="feature.dart" showLineNumbers {6-8}
+final feature = FeatureDescriptor(
+  name: 'root',
+  title: 'Vyuh Root Feature',
+  description: 'The root feature for the Vyuh Demo app',
+  init: () async {
+    final disposer = vyuh.event.on<SystemReadyEvent>((event) {
+      print('System is ready');
+    });
+
+    // At a later point, invoke the subscription disposer to cancel the event listener
+    disposer();
+  },
+
+  // rest of the feature configuration
+);
+
+```
+
+<Aside type="tip">
+With the `on` method, you can listen for multiple events by skipping the Type
+specifier.
+
+```dart
+final disposer = vyuh.event.on((event) {
+  print('${event.runtimeType} event received');
+});
+
+```
+
+</Aside>
+
+### Listening for Events Once
+
+You can listen to the events just once with the `once` method. This will remove
+the listener after the first time the event is triggered. Using the previous
+example of the `SystemReadyEvent`:
+
+```dart
+vyuh.event.once<SystemReadyEvent>((event) {
+  print('System is ready');
+});
+```
+
+The once methods also support listening to multiple events without specifying a
+type.
+
+```dart
+vyuh.event.once((event) {
+  print('${event.runtimeType} event received');
+});
+```
+
+## Triggering Events
+
+To trigger an event, you can use the `emit` method on `vyuh.event`. The `emit`
+method emits a type-safe event that is a subclass of `VyuhEvent`. Here is a
+simple example where the SystemReadyEvent is emitted:
+
+```dart
+vyuh.event.emit(SystemReadyEvent());
+```
+
+Elsewhere in the framework, the `SystemReadyEvent` is defined like so:
+
+```dart
+final class SystemReadyEvent extends VyuhEvent<void> {
+  SystemReadyEvent() : super(name: 'vyuh.event.systemReady');
+}
+```
+
+### `VyuhEvent`
+
+The `VyuhEvent` class is the base class for all events in the Vyuh Framework. It
+is a generic class that takes a type parameter that represents the payload of
+the event. The payload can be any type or `void` if the event does not have a
+payload.
+
+The `name` of the event is a string that uniquely identifies the event. It is
+very common to use a reverse domain name notation for the event name.
+Additionally, the event class has a `timestamp` that represents the time when
+the event was created.
+
+```dart
+class VyuhEvent<T> {
+  final String name;
+  final DateTime timestamp;
+  final T? data;
+
+  VyuhEvent({
+    required this.name,
+    this.data,
+  }) : timestamp = DateTime.now();
+}
+```
+
+### Standard Events
+
+Currently, there is only one standard event in the Vyuh Framework:
+
+- **`SystemReadyEvent`**: This event is triggered when the system is ready to
+  start the application. It is a good place to initialize the application
+  features.
+
+### Custom Events
+
+You can create custom events by extending the `VyuhEvent` class. Here is an
+example of a custom event that carries a payload of type `String`:
+
+```dart
+class CustomEvent extends VyuhEvent<String> {
+  CustomEvent(required super.data) : super(name: 'com.example.customEvent');
+}
+```
+
+The custom event can be triggered like so:
+
+```dart
+vyuh.event.emit(CustomEvent('Hello, World!'));
+```
+
+## Event Propagation
+
+The event system in the Vyuh Framework is a global event system. The event
+propagation is synchronous and happens in the order of the event registration.
+
+When an event is emitted, the event plugin iterates through all the event
+listeners and invokes them in the order they were registered. As mentioned
+earlier, you can cancel the event listener by invoking the disposer function
+returned by the `on` method.
+
+## Summary
+
+Events are a powerful way to communicate between features in the Vyuh Framework.
+The event system is a global event system that allows features to listen to
+events and communicate with each other. The event system is synchronous and
+propagates events in the order of registration.