add(element): interface for injecting user behavior to containers

Some additional refactoring and documentation updates have also been
applied.

examples/container.zig

@@ -6,23 +6,65 @@ const Key = zterm.Key;
 
 const log = std.log.scoped(.example);
 
+// TODO: maybe inlining the functions should be done as well to reduce the call
+//       stacks (might be important for more complex structures)
+
+pub const ExampleElement = struct {
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .handle = handle,
+                .content = content,
+            },
+        };
+    }
+
+    // example function to render contents for a `Container`
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+        _ = ctx;
+        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+
+        // NOTE: error should only be returned here in case an in-recoverable exception has occured
+        const row = size.rows / 2;
+        const col = size.cols / 2 -| 3;
+
+        for (0..5) |c| {
+            cells[(row * size.cols) + col + c].style.fg = .black;
+            cells[(row * size.cols) + col + c].cp = '-';
+        }
+    }
+
+    // example function to handle events for a `Container`
+    fn handle(ctx: *anyopaque, event: App.Event) !void {
+        _ = ctx;
+        switch (event) {
+            .init => log.debug(".init event", .{}),
+            else => {},
+        }
+    }
+};
+
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
     // TODO: maybe create own allocator as some sort of arena allocator to have consistent memory usage
-    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
+    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
     defer {
         const deinit_status = gpa.deinit();
         if (deinit_status == .leak) {
-            log.err("memory lead", .{});
+            log.err("memory leak", .{});
         }
     }
     const allocator = gpa.allocator();
 
-    var app: App = .{};
+    var app: App = .init;
     var renderer = zterm.Renderer.Buffered.init(allocator);
     defer renderer.deinit();
 
+    var element_wrapper = ExampleElement{};
+    const element = element_wrapper.element();
+
     var container = try App.Container.init(allocator, .{
         .border = .{ .separator = .{ .enabled = true } },
         .layout = .{
@@ -30,7 +72,7 @@ pub fn main() !void {
             .padding = .all(5),
             .direction = .horizontal,
         },
-    });
+    }, element);
     var box = try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .blue },
         .layout = .{
@@ -38,29 +80,28 @@ pub fn main() !void {
             .direction = .vertical,
             .padding = .vertical(1),
         },
-    });
+    }, .{});
     try box.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .light_green },
-    }));
+    }, element));
     try box.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .light_green },
-    }));
+    }, .{}));
     try box.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .light_green },
-    }));
+    }, element));
     try container.append(box);
     try container.append(try App.Container.init(allocator, .{
         .border = .{
             .color = .light_blue,
-            .sides = .vertical(),
+            .sides = .vertical,
         },
-    }));
+    }, .{}));
     try container.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .blue },
-    }));
-    defer container.deinit();
+    }, .{}));
+    defer container.deinit(); // also de-initializes the children
 
-    // NOTE: should the min-size here be required?
     try app.start();
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
 
@@ -91,13 +132,18 @@ pub fn main() !void {
                     });
                 }
             },
-            .err => |err| {
-                log.err("Received {any} with message: {s}", .{ @errorName(err.err), err.msg });
-            },
+            // NOTE: errors could be displayed in another container in case one was received, etc. to provide the user with feedback
+            .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
         }
 
-        try container.handle(event);
+        // NOTE: returned errors should be propagated back to the application
+        container.handle(event) catch |err| app.postEvent(.{
+            .err = .{
+                .err = err,
+                .msg = "Container Event handling failed",
+            },
+        });
         try renderer.render(@TypeOf(container), &container);
         try renderer.flush();
     }