feat(element/alignment): alignment Element implementation

You can now align a `Container` using the Alignment `Element` similar to
how you make a `Container` scrollable. For usage details please see the
example and the corresponding tests.

build.zig

@@ -6,6 +6,7 @@ pub fn build(b: *std.Build) void {
         all,
         demo,
         // elements:
+        alignment,
         button,
         input,
         scrollable,
@@ -54,6 +55,7 @@ pub fn build(b: *std.Build) void {
             .root_source_file = b.path(switch (@as(Examples, @enumFromInt(e.value))) {
                 .demo => "examples/demo.zig",
                 // elements:
+                .alignment => "examples/elements/alignment.zig",
                 .button => "examples/elements/button.zig",
                 .input => "examples/elements/input.zig",
                 .scrollable => "examples/elements/scrollable.zig",

examples/elements/alignment.zig

@@ -0,0 +1,98 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
+    const allocator = gpa.allocator();
+
+    var app: App = .init;
+    var renderer = zterm.Renderer.Buffered.init(allocator);
+    defer renderer.deinit();
+
+    var container: App.Container = try .init(allocator, .{}, .{});
+    defer container.deinit();
+
+    var quit_text: QuitText = .{};
+    const quit_container = try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .blue },
+        .layout = .{
+            .direction = .vertical,
+            .padding = .all(5),
+        },
+        .size = .{
+            .dim = .{ .x = 25, .y = 5 },
+            .grow = .fixed,
+        },
+    }, quit_text.element());
+
+    var alignment: App.Alignment = .init(quit_container, .center);
+    try container.append(try .init(allocator, .{}, alignment.element()));
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    // event loop
+    while (true) {
+        const event = app.nextEvent();
+        log.debug("received event: {s}", .{@tagName(event)});
+
+        // pre event handling
+        switch (event) {
+            .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
+            .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+            else => {},
+        }
+
+        container.handle(event) catch |err| app.postEvent(.{
+            .err = .{
+                .err = err,
+                .msg = "Container Event handling failed",
+            },
+        });
+
+        // post event handling
+        switch (event) {
+            .quit => break,
+            else => {},
+        }
+
+        container.resize(try renderer.resize());
+        container.reposition(.{});
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}
+
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {});

src/app.zig

@@ -397,6 +397,7 @@ pub fn App(comptime E: type) type {
         pub const Event = mergeTaggedUnions(event.SystemEvent, E);
         pub const Container = @import("container.zig").Container(Event);
         pub const Element = element.Element(Event);
+        pub const Alignment = element.Alignment(Event);
         pub const Scrollable = element.Scrollable(Event);
         pub const Exec = element.Exec(Event, Queue);
         pub const Queue = queue.Queue(Event, 256);

src/element.zig

@@ -67,6 +67,103 @@ pub fn Element(Event: type) type {
     };
 }
 
+pub fn Alignment(Event: type) type {
+    return struct {
+        /// `Size` of the actual contents that should be aligned.
+        size: Point = .{},
+        /// Alignment Configuration to use for aligning the associated contents of this `Element`.
+        configuration: Configuration,
+        /// `Container` to render in alignment. It needs to use the sizing options accordingly to be effective.
+        container: Container(Event),
+
+        /// Configuration for Alignment
+        pub const Configuration = packed struct {
+            h: Align = .start,
+            v: Align = .start,
+
+            /// Alignment Options for configuration for vertical and horizontal orientations
+            pub const Align = enum(u2) { start, center, end };
+
+            /// Configuration for vertical alignment
+            pub fn vertical(a: Align) @This() {
+                return .{ .v = a };
+            }
+            /// Configuration for horizontal alignment
+            pub fn horizontal(a: Align) @This() {
+                return .{ .h = a };
+            }
+
+            pub const center: @This() = .{ .v = .center, .h = .center };
+        };
+
+        pub fn init(container: Container(Event), configuration: Configuration) @This() {
+            return .{
+                .container = container,
+                .configuration = configuration,
+            };
+        }
+
+        pub fn element(this: *@This()) Element(Event) {
+            return .{
+                .ptr = this,
+                .vtable = &.{
+                    .resize = resize,
+                    .reposition = reposition,
+                    .handle = handle,
+                    .content = content,
+                },
+            };
+        }
+
+        fn resize(ctx: *anyopaque, size: Point) void {
+            const this: *@This() = @ptrCast(@alignCast(ctx));
+            this.size = size;
+            this.container.resize(size);
+        }
+
+        fn reposition(ctx: *anyopaque, anchor: Point) void {
+            const this: *@This() = @ptrCast(@alignCast(ctx));
+            var origin = anchor;
+            origin.x = switch (this.configuration.h) {
+                .start => origin.x,
+                .center => origin.x + (this.size.x / 2) -| (this.container.size.x / 2),
+                .end => this.size.x -| this.container.size.x,
+            };
+            origin.y = switch (this.configuration.v) {
+                .start => origin.y,
+                .center => origin.y + (this.size.y / 2) -| (this.container.size.y / 2),
+                .end => this.size.y -| this.container.size.y,
+            };
+            this.container.reposition(origin);
+        }
+
+        fn handle(ctx: *anyopaque, event: Event) !void {
+            const this: *@This() = @ptrCast(@alignCast(ctx));
+            try this.container.handle(event);
+        }
+
+        fn content(ctx: *anyopaque, cells: []Cell, size: Point) !void {
+            const this: *@This() = @ptrCast(@alignCast(ctx));
+            assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+            const origin = this.container.origin;
+            const csize = this.container.size;
+
+            const container_cells = try this.container.content();
+            defer this.container.allocator.free(container_cells);
+
+            outer: for (0..csize.y) |row| {
+                inner: for (0..csize.x) |col| {
+                    // do not read/write out of bounce
+                    if (this.size.x < row) break :outer;
+                    if (this.size.y < col) break :inner;
+
+                    cells[((row + origin.y) * size.x) + col + origin.x] = container_cells[(row * csize.x) + col];
+                }
+            }
+        }
+    };
+}
+
 pub fn Scrollable(Event: type) type {
     return struct {
         /// `Size` of the actual contents where the anchor and the size is
@@ -591,3 +688,135 @@ test "scrollable horizontal with scrollbar" {
     try renderer.render(Container(event.SystemEvent), &container);
     try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.horizontal.scrollbar.right.zon"), renderer.screen);
 }
+
+test "alignment center" {
+    const allocator = std.testing.allocator;
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    var container: Container(event.SystemEvent) = try .init(allocator, .{}, .{});
+    defer container.deinit();
+
+    const aligned_container: Container(event.SystemEvent) = try .init(allocator, .{
+        .rectangle = .{ .fill = .green },
+        .size = .{
+            .dim = .{ .x = 12, .y = 5 },
+            .grow = .fixed,
+        },
+    }, .{});
+    var alignment: Alignment(event.SystemEvent) = .init(aligned_container, .center);
+    try container.append(try .init(allocator, .{}, alignment.element()));
+
+    try testing.expectContainerScreen(.{
+        .x = 30,
+        .y = 20,
+    }, &container, @import("test/element/alignment.center.zon"));
+}
+
+test "alignment left" {
+    const allocator = std.testing.allocator;
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    var container: Container(event.SystemEvent) = try .init(allocator, .{}, .{});
+    defer container.deinit();
+
+    const aligned_container: Container(event.SystemEvent) = try .init(allocator, .{
+        .rectangle = .{ .fill = .green },
+        .size = .{
+            .dim = .{ .x = 12, .y = 5 },
+            .grow = .fixed,
+        },
+    }, .{});
+    var alignment: Alignment(event.SystemEvent) = .init(aligned_container, .{
+        .h = .start,
+        .v = .center,
+    });
+    try container.append(try .init(allocator, .{}, alignment.element()));
+
+    try testing.expectContainerScreen(.{
+        .x = 30,
+        .y = 20,
+    }, &container, @import("test/element/alignment.left.zon"));
+}
+
+test "alignment right" {
+    const allocator = std.testing.allocator;
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    var container: Container(event.SystemEvent) = try .init(allocator, .{}, .{});
+    defer container.deinit();
+
+    const aligned_container: Container(event.SystemEvent) = try .init(allocator, .{
+        .rectangle = .{ .fill = .green },
+        .size = .{
+            .dim = .{ .x = 12, .y = 5 },
+            .grow = .fixed,
+        },
+    }, .{});
+    var alignment: Alignment(event.SystemEvent) = .init(aligned_container, .{
+        .h = .end,
+        .v = .center,
+    });
+    try container.append(try .init(allocator, .{}, alignment.element()));
+
+    try testing.expectContainerScreen(.{
+        .x = 30,
+        .y = 20,
+    }, &container, @import("test/element/alignment.right.zon"));
+}
+
+test "alignment top" {
+    const allocator = std.testing.allocator;
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    var container: Container(event.SystemEvent) = try .init(allocator, .{}, .{});
+    defer container.deinit();
+
+    const aligned_container: Container(event.SystemEvent) = try .init(allocator, .{
+        .rectangle = .{ .fill = .green },
+        .size = .{
+            .dim = .{ .x = 12, .y = 5 },
+            .grow = .fixed,
+        },
+    }, .{});
+    var alignment: Alignment(event.SystemEvent) = .init(aligned_container, .{
+        .h = .center,
+        .v = .start,
+    });
+    try container.append(try .init(allocator, .{}, alignment.element()));
+
+    try testing.expectContainerScreen(.{
+        .x = 30,
+        .y = 20,
+    }, &container, @import("test/element/alignment.top.zon"));
+}
+
+test "alignment bottom" {
+    const allocator = std.testing.allocator;
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    var container: Container(event.SystemEvent) = try .init(allocator, .{}, .{});
+    defer container.deinit();
+
+    const aligned_container: Container(event.SystemEvent) = try .init(allocator, .{
+        .rectangle = .{ .fill = .green },
+        .size = .{
+            .dim = .{ .x = 12, .y = 5 },
+            .grow = .fixed,
+        },
+    }, .{});
+    var alignment: Alignment(event.SystemEvent) = .init(aligned_container, .{
+        .h = .center,
+        .v = .end,
+    });
+    try container.append(try .init(allocator, .{}, alignment.element()));
+
+    try testing.expectContainerScreen(.{
+        .x = 30,
+        .y = 20,
+    }, &container, @import("test/element/alignment.bottom.zon"));
+}