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

Some additional refactoring and documentation updates have also been
applied.

src/app.zig

@@ -27,8 +27,8 @@ const log = std.log.scoped(.app);
 ///       union(enum) {},
 ///   );
 ///   // later on create an `App` instance and start the event loop
-///   var app: App = .{};
-///   try app.start(null);
+///   var app: App = .init;
+///   try app.start();
 ///   defer app.stop() catch unreachable;
 /// ```
 pub fn App(comptime E: type) type {
@@ -38,19 +38,29 @@ pub fn App(comptime E: type) type {
     return struct {
         pub const Event = mergeTaggedUnions(event.SystemEvent, E);
         pub const Container = @import("container.zig").Container(Event);
+        pub const Element = @import("element.zig").Element(Event);
 
-        queue: Queue(Event, 256) = .{},
-        thread: ?std.Thread = null,
-        quit_event: std.Thread.ResetEvent = .{},
+        queue: Queue(Event, 256),
+        thread: ?std.Thread,
+        quit_event: std.Thread.ResetEvent,
         termios: ?std.posix.termios = null,
         attached_handler: bool = false,
-        prev_size: Size = .{ .cols = 0, .rows = 0 },
+        prev_size: Size,
 
         pub const SignalHandler = struct {
             context: *anyopaque,
             callback: *const fn (context: *anyopaque) void,
         };
 
+        pub const init: @This() = .{
+            .queue = .{},
+            .thread = null,
+            .quit_event = .{},
+            .termios = null,
+            .attached_handler = false,
+            .prev_size = .{},
+        };
+
         pub fn start(this: *@This()) !void {
             if (this.thread) |_| return;
 

src/container.zig

@@ -27,17 +27,12 @@ pub const Border = packed struct {
         left: bool = false,
         right: bool = false,
 
-        pub fn all() @This() {
-            return .{ .top = true, .bottom = true, .left = true, .right = true };
-        }
-
-        pub fn horizontal() @This() {
-            return .{ .left = true, .right = true };
-        }
-
-        pub fn vertical() @This() {
-            return .{ .top = true, .bottom = true };
-        }
+        /// Enable border sides for all four sides
+        pub const all: @This() = .{ .top = true, .bottom = true, .left = true, .right = true };
+        /// Enable border sides for the left and right sides
+        pub const horizontal: @This() = .{ .left = true, .right = true };
+        /// Enable border sides for the top and bottom sides
+        pub const vertical: @This() = .{ .top = true, .bottom = true };
     } = .{},
     /// Configure separator borders between child element to added to the layout
     separator: packed struct {
@@ -235,10 +230,12 @@ pub fn Container(comptime Event: type) type {
     if (!isTaggedUnion(Event)) {
         @compileError("Provided user event `Event` for `Container(comptime Event: type)`");
     }
+    const Element = @import("element.zig").Element(Event);
     return struct {
         allocator: std.mem.Allocator,
         size: Size,
         properties: Properties,
+        element: Element,
         elements: std.ArrayList(@This()),
 
         /// Properties for each `Container` to configure their layout,
@@ -251,11 +248,16 @@ pub fn Container(comptime Event: type) type {
             layout: Layout = .{},
         };
 
-        pub fn init(allocator: std.mem.Allocator, properties: Properties) !@This() {
+        pub fn init(
+            allocator: std.mem.Allocator,
+            properties: Properties,
+            element: Element,
+        ) !@This() {
             return .{
                 .allocator = allocator,
                 .size = .{},
                 .properties = properties,
+                .element = element,
                 .elements = std.ArrayList(@This()).init(allocator),
             };
         }
@@ -273,7 +275,6 @@ pub fn Container(comptime Event: type) type {
 
         pub fn handle(this: *@This(), event: Event) !void {
             switch (event) {
-                .init => log.debug(".init event", .{}),
                 .resize => |size| resize: {
                     log.debug("Event .resize: {{ .anchor = {{ .col = {d}, .row = {d} }}, .cols = {d}, .rows = {d} }}", .{
                         size.anchor.col,
@@ -384,29 +385,29 @@ pub fn Container(comptime Event: type) type {
                         }
 
                         // border resizing
-                        if (sides.top) {
-                            element_size.anchor.row += 1;
-                        }
-                        if (sides.left) {
-                            element_size.anchor.col += 1;
-                        }
-
-                        // padding resizing
+                        if (sides.top) element_size.anchor.row += 1;
+                        if (sides.left) element_size.anchor.col += 1;
 
                         try element.handle(.{ .resize = element_size });
                     }
                 },
-                else => for (this.elements.items) |*element| try element.handle(event),
+                else => {
+                    try this.element.handle(event);
+                    for (this.elements.items) |*element| try element.handle(event);
+                },
             }
         }
 
         pub fn contents(this: *const @This()) ![]const Cell {
             const cells = try this.allocator.alloc(Cell, @as(usize, this.size.cols) * @as(usize, this.size.rows));
             @memset(cells, .{});
+            errdefer this.allocator.free(cells);
 
             this.properties.border.contents(cells, this.size, this.properties.layout, @truncate(this.elements.items.len));
             this.properties.rectangle.contents(cells, this.size);
 
+            try this.element.content(cells, this.size);
+
             return cells;
         }
     };

src/element.zig

@@ -0,0 +1,23 @@
+//! Interface for Element's which describe the contents of a `Container`.
+const Cell = @import("cell.zig");
+const Size = @import("size.zig").Size;
+
+pub fn Element(Event: type) type {
+    return struct {
+        ptr: *anyopaque = undefined,
+        vtable: *const VTable = &.{},
+
+        pub const VTable = struct {
+            handle: ?*const fn (ctx: *anyopaque, event: Event) anyerror!void = null,
+            content: ?*const fn (ctx: *anyopaque, cells: []Cell, size: Size) anyerror!void = null,
+        };
+
+        pub inline fn handle(this: @This(), event: Event) !void {
+            if (this.vtable.handle) |handle_fn| try handle_fn(this.ptr, event);
+        }
+
+        pub inline fn content(this: @This(), cells: []Cell, size: Size) !void {
+            if (this.vtable.content) |content_fn| try content_fn(this.ptr, cells, size);
+        }
+    };
+}

src/zterm.zig

@@ -5,6 +5,9 @@ const size = @import("size.zig");
 
 // public exports
 pub const App = @import("app.zig").App;
+// App also exports further types once initialized with the user events at compile time:
+// `App.Container`
+// `App.Element`
 pub const Renderer = @import("render.zig");
 
 // Container Configurations