mod: example shows how dynamic sizing is achived that can be independent form the reported terminal size

Setting the cursor with the `Direct` handler will cause the rendering
to halt at that point and leave the cursor at point.

Due to not enabling *raw mode* with the newly introduced `App.start`
configuration options corresponding inputs are only visible to `zterm`
once the input has been completed with a newline. With this it is not
necessary for the renderer to know nothing more than the width of the
terminal (which is implied through the `Container` sizes). Making it
very trivial to implement.

examples/direct.zig

@@ -1,3 +1,75 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .minSize = minSize,
+                .content = content,
+            },
+        };
+    }
+
+    fn minSize(_: *anyopaque, _: *const App.Model, size: zterm.Point) zterm.Point {
+        return .{ .x = size.x, .y = 10 }; // this includes the border
+    }
+
+    pub fn content(ctx: *anyopaque, _: *const App.Model, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const y = 0;
+        const x = size.x / 2 -| (text.len / 2);
+        const anchor = (y * size.x) + x;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.emphasis = &.{.bold};
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+const Prompt = struct {
+    len: u16 = 5,
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                // .minSize = minSize,
+                .content = content,
+            },
+        };
+    }
+
+    // fn minSize(ctx: *anyopaque, _: *const App.Model, _: zterm.Point) zterm.Point {
+    //     const this: *@This() = @ptrCast(@alignCast(ctx));
+    //     return .{ .x = this.len, .y = 1 };
+    // }
+
+    pub fn content(ctx: *anyopaque, _: *const App.Model, cells: []zterm.Cell, size: zterm.Point) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        assert(cells.len > 2); // expect at least two cells
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        for (0..this.len) |idx| {
+            cells[idx].style.bg = .red;
+            cells[idx].style.fg = .black;
+            cells[idx].style.emphasis = &.{.bold};
+        }
+        cells[this.len - 1].style.cursor = true; // marks the actual end of the rendering!
+
+        const anchor = 1;
+        cells[anchor + 0].cp = 'N';
+        cells[anchor + 1].cp = 'O';
+        cells[anchor + 2].cp = 'R';
+    }
+};
+
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
@@ -11,29 +83,42 @@ pub fn main() !void {
     defer renderer.deinit();
 
     var container: App.Container = try .init(gpa, .{
-        .border = .{
-            .sides = .all,
-        },
         .layout = .{
-            .direction = .horizontal,
-            .separator = .{ .enabled = true },
+            .direction = .vertical,
         },
         .size = .{
-            .dim = .{ .y = 30 },
             .grow = .horizontal_only,
         },
     }, .{});
     defer container.deinit();
 
-    try container.append(try .init(gpa, .{
+    var quit_text: QuitText = .{};
+    var intermediate: App.Container = try .init(gpa, .{
+        .border = .{
+            .sides = .all,
+        },
+        .layout = .{
+            .direction = .horizontal,
+        },
+    }, quit_text.element());
+    try intermediate.append(try .init(gpa, .{
         .rectangle = .{ .fill = .blue },
     }, .{}));
 
-    try container.append(try .init(gpa, .{
+    try intermediate.append(try .init(gpa, .{
         .rectangle = .{ .fill = .green },
     }, .{}));
+    try container.append(intermediate);
 
-    try app.start(); // needs to become configurable, as what should be enabled / disabled (i.e. show cursor, hide cursor, use alternate screen, etc.)
+    var prompt: Prompt = .{};
+    try container.append(try .init(gpa, .{
+        .rectangle = .{ .fill = .red },
+        .size = .{
+            .dim = .{ .y = 1 },
+        },
+    }, prompt.element()));
+
+    try app.start(.direct); // needs to become configurable, as what should be enabled / disabled (i.e. show cursor, hide cursor, use alternate screen, etc.)
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
 
     // event loop
@@ -49,14 +134,15 @@ pub fn main() !void {
         // handle events
         for (0..len) |_| {
             const event = app.queue.pop();
-            //log.debug("received event: {s}", .{@tagName(event)});
+            log.debug("received event: {s}", .{@tagName(event)});
 
             // pre event handling
             switch (event) {
                 // NOTE maybe I want to decouple the `key`s from the user input too? i.e. this only makes sense if the output is not echoed!
                 // otherwise just use gnu's `readline`?
                 .key => |key| {
-                    if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit();
+                    // if (key.eql(.{ .cp = 'q' })) app.quit();
+                    _ = key;
                 },
                 // 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 }),