add(example): WIP popup Element example implementation

Negative paddings use the current size to calculate the padding from
the opposite orientation. For a given dimension (horizontal or vertical)
if the size is `30` a padding of `5` would be equivalent to a padding
of `-25`. This enables to describe the size of the container using
the padding property of the `Layout` and gives users more freedom to
describe different layouts.

build.zig

@@ -10,6 +10,8 @@ pub fn build(b: *std.Build) void {
         alignment,
         button,
         input,
+        popup,
+        progress,
         scrollable,
         // layouts:
         vertical,
@@ -60,6 +62,8 @@ pub fn build(b: *std.Build) void {
                 .alignment => "examples/elements/alignment.zig",
                 .button => "examples/elements/button.zig",
                 .input => "examples/elements/input.zig",
+                .popup => "examples/elements/popup.zig",
+                .progress => "examples/elements/progress.zig",
                 .scrollable => "examples/elements/scrollable.zig",
                 // layouts:
                 .vertical => "examples/layouts/vertical.zig",

build.zig.zon

@@ -37,8 +37,8 @@
     // internet connectivity.
     .dependencies = .{
         .zg = .{
-            .url = "git+https://codeberg.org/atman/zg#0b05141b033043c5f7bcd72048a48eef6531ea6c",
-            .hash = "zg-0.14.0-oGqU3KEFswIffnDu8eAE2XlhzwcfgjwtM6akIc5L7cEV",
+            .url = "git+https://codeberg.org/atman/zg#9427a9e53aaa29ee071f4dcb35b809a699d75aa9",
+            .hash = "zg-0.14.1-oGqU3IQ_tALZIiBN026_NTaPJqU-Upm8P_C7QED2Rzm8",
         },
     },
     .paths = .{

examples/elements/popup.zig

@@ -0,0 +1,247 @@
+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;
+        }
+    }
+};
+
+const MouseDraw = struct {
+    position: ?zterm.Point = null,
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .handle = handle,
+                .content = content,
+            },
+        };
+    }
+
+    fn handle(ctx: *anyopaque, event: App.Event) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        switch (event) {
+            .mouse => |mouse| this.position = .{ .x = mouse.x, .y = mouse.y },
+            else => this.position = null,
+        }
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+
+        if (this.position) |pos| {
+            const idx = @as(usize, size.x) * @as(usize, pos.y) + @as(usize, pos.x);
+            cells[idx].cp = 'x';
+            cells[idx].style.fg = .red;
+        }
+    }
+};
+
+const Popup = struct {
+    container: ?*App.Container = null,
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .resize = resize,
+                .reposition = reposition,
+                .handle = handle,
+                .content = content,
+            },
+        };
+    }
+
+    fn resize(ctx: *anyopaque, size: zterm.Point) void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        if (this.container) |container| container.resize(size);
+    }
+
+    fn reposition(ctx: *anyopaque, _: zterm.Point) void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        if (this.container) |container| container.reposition(.{});
+    }
+
+    fn handle(ctx: *anyopaque, event: App.Event) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        switch (event) {
+            // TODO should the `Element` handle the pop_down element triggering (i.e. by defining a usual key for this?)
+            .pop_up => |optional| if (optional) |container| {
+                this.container = @ptrCast(@alignCast(container));
+            } else {
+                this.container = null;
+            },
+            else => if (this.container) |container| try container.handle(event),
+        }
+    }
+
+    fn render_container(container: App.Container, cells: []zterm.Cell, container_size: zterm.Point) !void {
+        const size = container.size;
+        const origin = container.origin;
+        const contents = try container.content();
+
+        const anchor = (@as(usize, origin.y) * @as(usize, container_size.x)) + @as(usize, origin.x);
+
+        var idx: usize = 0;
+        blk: for (0..size.y) |row| {
+            for (0..size.x) |col| {
+                cells[anchor + (row * container_size.x) + col] = contents[idx];
+                idx += 1;
+
+                if (contents.len == idx) break :blk;
+            }
+        }
+        // free immediately
+        container.allocator.free(contents);
+
+        for (container.elements.items) |child| try render_container(child, cells, size);
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        const this: *@This() = @ptrCast(@alignCast(ctx));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        if (this.container) |container| {
+            assert(cells.len == @as(usize, container.size.x) * @as(usize, container.size.y));
+            const popup_cells = try container.content();
+
+            for (container.elements.items) |child| try render_container(child, popup_cells, size);
+
+            assert(cells.len == popup_cells.len);
+            @memcpy(cells, popup_cells);
+
+            container.allocator.free(popup_cells);
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    var gpa: std.heap.DebugAllocator(.{}) = .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 popup: Popup = .{};
+    var quit_text: QuitText = .{};
+
+    // TODO
+    // - rendering of first Container contents will be overwritten by contents of the appended Container's (see the missing blue rectangle)
+    // - when rendering "nothing" it causes the below Container to be overwritten to "nothing" too!
+    // - not sure how this should be done?
+    //   - provide the pop-up with a  area where to draw? (i.e. somewhere to draw the provided `Container`)
+    //   - This however will not suffice as the contents will be overwritten!
+
+    var container = try App.Container.init(allocator, .{
+        .rectangle = .{
+            .fill = .blue,
+        },
+    }, .{});
+    defer container.deinit();
+
+    var popup_root_container = try App.Container.init(allocator, .{
+        .layout = .{
+            .padding = .{
+                .top = -17,
+                .left = -40,
+                .right = 5,
+                .bottom = 5,
+            },
+        },
+    }, .{});
+    try popup_root_container.append(try App.Container.init(allocator, .{}, popup.element()));
+
+    try container.append(try .init(allocator, .{}, quit_text.element()));
+    try container.append(popup_root_container); // FIXME it should not be appended (as it would become part of the layout)
+
+    var mouse: MouseDraw = .{};
+    var popup_container: App.Container = try .init(allocator, .{
+        .rectangle = .{ .fill = .green },
+        .layout = .{
+            .padding = .{
+                .top = -4,
+                .bottom = 1,
+                .left = 3,
+                .right = 3,
+            },
+        },
+    }, .{});
+    // showcase that inner `Container`s handle `Element`s accordingly
+    try popup_container.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+    }, mouse.element()));
+    defer popup_container.deinit();
+
+    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();
+                if (key.eql(.{ .cp = zterm.input.Space })) app.postEvent(.{ .pop_up = &popup_container });
+                if (key.eql(.{ .cp = zterm.input.Escape })) app.postEvent(.{ .pop_up = null });
+            },
+            .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();
+    }
+}
+
+pub const panic = App.panic_handler;
+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) {
+    pop_up: ?*anyopaque,
+});

examples/elements/progress.zig

@@ -0,0 +1,137 @@
+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.DebugAllocator(.{}) = .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 progress_percent: u8 = 0;
+    var progress: App.Progress(.progress) = .init(&app.queue, .{
+        .percent = .{ .enabled = true },
+        .fg = .green,
+        .bg = .grey,
+    });
+    var quit_text: QuitText = .{};
+
+    var container = try App.Container.init(allocator, .{
+        .layout = .{ .padding = .all(5) },
+    }, quit_text.element());
+    defer container.deinit();
+
+    try container.append(try App.Container.init(allocator, .{}, progress.element()));
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    var framerate: u64 = 60;
+    var tick_ms: u64 = @divFloor(time.ms_per_s, framerate);
+    var next_frame_ms: u64 = 0;
+
+    var increase_progress: u64 = 10;
+
+    // Continuous drawing
+    // draw loop
+    draw: while (true) {
+        const now_ms: u64 = @intCast(time.milliTimestamp());
+        if (now_ms >= next_frame_ms) {
+            next_frame_ms = now_ms + tick_ms;
+        } else {
+            time.sleep((next_frame_ms - now_ms) * time.ns_per_ms);
+            next_frame_ms += tick_ms;
+        }
+
+        // NOTE time based progress increasion
+        increase_progress -= 1;
+        if (increase_progress == 0) {
+            increase_progress = 10;
+            progress_percent += 1;
+            if (progress_percent > 100) progress_percent = 0;
+            app.postEvent(.{ .progress = progress_percent });
+        }
+
+        const len = blk: {
+            app.queue.lock();
+            defer app.queue.unlock();
+            break :blk app.queue.len();
+        };
+
+        // handle events
+        for (0..len) |_| {
+            const event = app.queue.drain() orelse break;
+            log.debug("handling 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 }),
+                .focus => |b| {
+                    // NOTE reduce framerate in case the window is not focused and restore again when focused
+                    framerate = if (b) 60 else 15;
+                    tick_ms = @divFloor(time.ms_per_s, framerate);
+                },
+                else => {},
+            }
+
+            container.handle(event) catch |err| app.postEvent(.{
+                .err = .{
+                    .err = err,
+                    .msg = "Container Event handling failed",
+                },
+            });
+
+            // post event handling
+            switch (event) {
+                .quit => break :draw,
+                else => {},
+            }
+        }
+
+        container.resize(try renderer.resize());
+        container.reposition(.{});
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const time = std.time;
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {
+    progress: u8,
+});

src/app.zig

@@ -415,6 +415,7 @@ pub fn App(comptime E: type) type {
         pub const Alignment = element.Alignment(Event);
         pub const Button = element.Button(Event, Queue);
         pub const Input = element.Input(Event, Queue);
+        pub const Progress = element.Progress(Event, Queue);
         pub const Scrollable = element.Scrollable(Event);
         pub const Queue = queue.Queue(Event, 256);
     };

src/container.zig

@@ -195,6 +195,33 @@ pub const Rectangle = packed struct {
         }, &container, @import("test/container/rectangle_with_parent_padding.zon"));
     }
 
+    test "fill color padding to show parent fill (negative padding)" {
+        const event = @import("event.zig");
+        const testing = @import("testing.zig");
+
+        var container: Container(event.SystemEvent) = try .init(std.testing.allocator, .{
+            .layout = .{
+                .padding = .{
+                    .top = -18,
+                    .bottom = -18,
+                    .left = -28,
+                    .right = -28,
+                },
+            },
+            .rectangle = .{ .fill = .green },
+        }, .{});
+        try container.append(try .init(std.testing.allocator, .{
+            .rectangle = .{ .fill = .white },
+        }, .{}));
+        try container.append(try .init(std.testing.allocator, .{}, .{}));
+        defer container.deinit();
+
+        try testing.expectContainerScreen(.{
+            .y = 20,
+            .x = 30,
+        }, &container, @import("test/container/rectangle_with_parent_padding.zon"));
+    }
+
     test "fill color spacer with padding" {
         const event = @import("event.zig");
         const testing = @import("testing.zig");
@@ -293,23 +320,23 @@ pub const Layout = packed struct {
     direction: enum(u1) { horizontal, vertical } = .horizontal,
     /// Padding outside of the child elements
     padding: packed struct {
-        top: u16 = 0,
-        bottom: u16 = 0,
-        left: u16 = 0,
-        right: u16 = 0,
+        top: i16 = 0,
+        bottom: i16 = 0,
+        left: i16 = 0,
+        right: i16 = 0,
 
         /// Create a padding with equivalent padding in all four directions.
-        pub fn all(padding: u16) @This() {
+        pub fn all(padding: i16) @This() {
             return .{ .top = padding, .bottom = padding, .left = padding, .right = padding };
         }
 
         /// Create a padding with equivalent padding in the left and right directions; others directions remain the default value.
-        pub fn horizontal(padding: u16) @This() {
+        pub fn horizontal(padding: i16) @This() {
             return .{ .left = padding, .right = padding };
         }
 
         /// Create a padding with equivalent padding in the top and bottom directions; others directions remain the default value.
-        pub fn vertical(padding: u16) @This() {
+        pub fn vertical(padding: i16) @This() {
             return .{ .top = padding, .bottom = padding };
         }
     } = .{},
@@ -326,6 +353,11 @@ pub const Layout = packed struct {
         } = .line,
     } = .{},
 
+    /// Calculate the absolute offset for the provided `padding` if it is negative to get the absolute padding for the given `size`.
+    pub fn getAbsolutePadding(padding: i16, size: u16) u16 {
+        return if (padding >= 0) @intCast(padding) else size -| @as(u16, @intCast(-padding));
+    }
+
     pub fn content(this: @This(), comptime C: type, cells: []Cell, origin: Point, size: Point, children: []const C) void {
         assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
@@ -566,6 +598,7 @@ pub fn Container(comptime Event: type) type {
         size: Point,
         properties: Properties,
         element: Element,
+        // TODO this should be renamed to `children`
         elements: std.ArrayList(@This()),
 
         /// Properties for each `Container` to configure their layout,
@@ -593,10 +626,8 @@ pub fn Container(comptime Event: type) type {
             };
         }
 
-        pub fn deinit(this: *@This()) void {
-            for (this.elements.items) |*element| {
-                element.deinit();
-            }
+        pub fn deinit(this: *const @This()) void {
+            for (this.elements.items) |*element| element.deinit();
             this.elements.deinit();
         }
 
@@ -610,8 +641,8 @@ pub fn Container(comptime Event: type) type {
             this.element.reposition(origin);
 
             var offset = origin.add(.{
-                .x = layout.padding.left,
-                .y = layout.padding.top,
+                .x = Layout.getAbsolutePadding(layout.padding.left, this.size.x),
+                .y = Layout.getAbsolutePadding(layout.padding.top, this.size.y),
             });
 
             const sides = this.properties.border.sides;
@@ -643,8 +674,8 @@ pub fn Container(comptime Event: type) type {
             };
 
             if (this.elements.items.len > 0) switch (layout.direction) {
-                .horizontal => size.x += layout.padding.left + layout.padding.right,
-                .vertical => size.y += layout.padding.top + layout.padding.bottom,
+                .horizontal => size.x += Layout.getAbsolutePadding(layout.padding.left, this.size.x) + Layout.getAbsolutePadding(layout.padding.right, this.size.x),
+                .vertical => size.y += Layout.getAbsolutePadding(layout.padding.top, this.size.y) + Layout.getAbsolutePadding(layout.padding.bottom, this.size.y),
             };
 
             const sides = this.properties.border.sides;
@@ -692,16 +723,16 @@ pub fn Container(comptime Event: type) type {
         fn grow_resize(this: *@This(), max_size: Point) void {
             const layout = this.properties.layout;
             var remainder = switch (layout.direction) {
-                .horizontal => max_size.x -| (layout.padding.left + layout.padding.right),
-                .vertical => max_size.y -| (layout.padding.top + layout.padding.bottom),
+                .horizontal => max_size.x -| (Layout.getAbsolutePadding(layout.padding.left, this.size.x) + Layout.getAbsolutePadding(layout.padding.right, this.size.x)),
+                .vertical => max_size.y -| (Layout.getAbsolutePadding(layout.padding.top, this.size.y) + Layout.getAbsolutePadding(layout.padding.bottom, this.size.y)),
             };
             remainder -|= layout.gap * @as(u16, @truncate(this.elements.items.len -| 1));
 
             if (layout.separator.enabled) remainder -|= @as(u16, @truncate(this.elements.items.len -| 1));
 
             var available = switch (layout.direction) {
-                .horizontal => max_size.y -| (layout.padding.top + layout.padding.bottom),
-                .vertical => max_size.x -| (layout.padding.left + layout.padding.right),
+                .horizontal => max_size.y -| (Layout.getAbsolutePadding(layout.padding.top, this.size.y) + Layout.getAbsolutePadding(layout.padding.bottom, this.size.y)),
+                .vertical => max_size.x -| (Layout.getAbsolutePadding(layout.padding.left, this.size.x) + Layout.getAbsolutePadding(layout.padding.right, this.size.x)),
             };
 
             const sides = this.properties.border.sides;
@@ -773,6 +804,7 @@ pub fn Container(comptime Event: type) type {
 
                 for (this.elements.items) |child| {
                     if (child.properties.size.grow == .fixed) continue;
+
                     switch (layout.direction) {
                         .horizontal => if (child.properties.size.grow == .vertical) continue,
                         .vertical => if (child.properties.size.grow == .horizontal) continue,
@@ -794,10 +826,8 @@ pub fn Container(comptime Event: type) type {
 
                 size_to_correct = @min(size_to_correct, remainder / growable_children);
                 var overflow: u16 = 0;
-                if (size_to_correct == 0 and remainder > 0) {
-                    // there is some overflow
-                    overflow = remainder;
-                }
+                if (size_to_correct == 0 and remainder > 0) overflow = remainder;
+
                 for (this.elements.items) |*child| {
                     const child_size = switch (layout.direction) {
                         .horizontal => child.size.x,
@@ -838,6 +868,7 @@ pub fn Container(comptime Event: type) type {
 
         pub fn resize(this: *@This(), size: Point) void {
             // NOTE assume that this function is only called for the root `Container`
+            this.size = size;
             const fit_size = this.fit_resize();
             // if (fit_size.y > size.y or fit_size.x > size.x) @panic("error: cannot render in available space");
             switch (this.properties.size.grow) {
@@ -855,7 +886,7 @@ pub fn Container(comptime Event: type) type {
             this.grow_resize(this.size);
         }
 
-        pub fn handle(this: *@This(), event: Event) !void {
+        pub fn handle(this: *const @This(), event: Event) !void {
             switch (event) {
                 .mouse => |mouse| if (mouse.in(this.origin, this.size)) {
                     // the element receives the mouse event with relative position
@@ -873,11 +904,12 @@ pub fn Container(comptime Event: type) type {
             }
         }
 
-        pub fn content(this: *const @This()) ![]const Cell {
+        pub fn content(this: *const @This()) ![]Cell {
             if (this.size.x == 0 or this.size.y == 0) return Error.TooSmall;
+
             const cells = try this.allocator.alloc(Cell, @as(usize, this.size.x) * @as(usize, this.size.y));
-            @memset(cells, .{});
             errdefer this.allocator.free(cells);
+            @memset(cells, .{});
 
             this.properties.layout.content(@This(), cells, this.origin, this.size, this.elements.items);
             this.properties.border.content(cells, this.size);

src/element.zig

@@ -182,6 +182,7 @@ pub fn Scrollable(Event: type) type {
         configuration: Configuration,
 
         pub const Configuration = packed struct {
+            // TODO the scrollbar bool and the color should be in their own struct using `enabled` and `color` inside of the struct to be more consistent with other `Configuration` structs
             scrollbar: bool,
             color: Color = .default,
             x_axis: bool = false,
@@ -281,7 +282,6 @@ pub fn Scrollable(Event: type) type {
             const size = container.size;
             const origin = container.origin;
             const contents = try container.content();
-            defer container.allocator.free(contents);
 
             const anchor = (@as(usize, origin.y) * @as(usize, container_size.x)) + @as(usize, origin.x);
 
@@ -294,6 +294,8 @@ pub fn Scrollable(Event: type) type {
                     if (contents.len == idx) break :blk;
                 }
             }
+            // free immediately
+            container.allocator.free(contents);
 
             for (container.elements.items) |child| try render_container(child, cells, size);
         }
@@ -306,13 +308,7 @@ pub fn Scrollable(Event: type) type {
             const offset_y: usize = if (this.configuration.y_axis) 1 else 0;
 
             const container_size = this.container.size;
-            const container_cells = try this.container.allocator.alloc(Cell, @as(usize, container_size.x) * @as(usize, container_size.y));
-            {
-                const container_cells_const = try this.container.content();
-                defer this.container.allocator.free(container_cells_const);
-                assert(container_cells_const.len == @as(usize, container_size.x) * @as(usize, container_size.y));
-                @memcpy(container_cells, container_cells_const);
-            }
+            const container_cells = try this.container.content();
 
             for (this.container.elements.items) |child| try render_container(child, container_cells, container_size);
 
@@ -400,7 +396,7 @@ pub fn Input(Event: type, Queue: type) fn (meta.FieldEnum(Event)) type {
                 queue: *Queue,
 
                 /// Configuration for InputField's.
-                pub const Configuration = struct {
+                pub const Configuration = packed struct {
                     color: Color,
 
                     pub fn init(color: Color) @This() {
@@ -651,6 +647,106 @@ pub fn Button(Event: type, Queue: type) fn (meta.FieldEnum(Event)) type {
     return button_struct.button_fn;
 }
 
+pub fn Progress(Event: type, Queue: type) fn (meta.FieldEnum(Event)) type {
+    // NOTE the struct is necessary, as otherwise I cannot point to the function I want to return
+    const progress_struct = struct {
+        pub fn progress_fn(progress_event: meta.FieldEnum(Event)) type {
+            { // check for type correctness and the associated type to use for the passed `progress_event`
+                const err_msg = "Unexpected type for the associated input completion event to trigger. Only `u8` is allowed.";
+                switch (@typeInfo(@FieldType(Event, @tagName(progress_event)))) {
+                    .int => |num| {
+                        if (num.signedness != .unsigned) @compileError(err_msg);
+                        switch (num.bits) {
+                            8 => {},
+                            else => @compileError(err_msg),
+                        }
+                    },
+                    else => @compileError(err_msg),
+                }
+            }
+            return struct {
+                configuration: Configuration,
+                progress: u8 = 0,
+                queue: *Queue,
+
+                pub const Configuration = packed struct {
+                    /// Control whether the percentage of the progress be rendered.
+                    percent: packed struct {
+                        enabled: bool = false,
+                        alignment: enum(u2) { left, middle, right } = .middle,
+                    } = .{},
+                    /// Foreground color to use for the progress bar.
+                    fg: Color,
+                    /// Background color to use for the progress bar.
+                    bg: Color,
+                    /// Code point to use for rendering the progress bar with.
+                    cp: u21 = '━',
+                };
+
+                pub fn init(queue: *Queue, configuration: Configuration) @This() {
+                    return .{
+                        .configuration = configuration,
+                        .queue = queue,
+                    };
+                }
+
+                pub fn element(this: *@This()) Element(Event) {
+                    return .{
+                        .ptr = this,
+                        .vtable = &.{
+                            .handle = handle,
+                            .content = content,
+                        },
+                    };
+                }
+
+                fn handle(ctx: *anyopaque, event: Event) !void {
+                    const this: *@This() = @ptrCast(@alignCast(ctx));
+                    // TODO should this `Element` trigger a completion event? (I don't think that this is useful?)
+                    switch (event) {
+                        progress_event => |value| {
+                            assert(value >= 0 and value <= 100);
+                            this.progress = value;
+                        },
+                        else => {},
+                    }
+                }
+
+                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 ratio: f32 = @as(f32, @floatFromInt(size.x)) / 100.0;
+                    const scrollbar_end_pos: usize = @intFromFloat(ratio * @as(f32, @floatFromInt(this.progress)));
+
+                    // NOTE remain `undefined` in case percentage rendering is not enabled
+                    var percent_buf: [6]u8 = undefined;
+                    var percent_buf_len: usize = undefined;
+                    if (this.configuration.percent.enabled) percent_buf_len = (try std.fmt.bufPrint(&percent_buf, "[{d: >3}%]", .{this.progress})).len;
+
+                    for (0..size.x) |idx| {
+                        // NOTE the progress bar is rendered at the bottom row of the `Container` taking its entire columns
+                        cells[((size.y - 1) * size.x) + idx] = .{
+                            .style = .{
+                                .fg = if (scrollbar_end_pos > 0 and idx <= scrollbar_end_pos) this.configuration.fg else this.configuration.bg,
+                                .emphasis = &.{},
+                            },
+                            .cp = if (this.configuration.percent.enabled) switch (this.configuration.percent.alignment) {
+                                .left => if (idx < percent_buf_len) percent_buf[idx] else this.configuration.cp,
+                                .middle => if (idx >= ((size.x - percent_buf_len) / 2) and idx < ((size.x - percent_buf_len) / 2) + percent_buf_len) percent_buf[percent_buf_len - (((size.x - percent_buf_len) / 2) + percent_buf_len - idx - 1) - 1] else this.configuration.cp,
+                                .right => if (idx >= size.x - percent_buf_len) percent_buf[percent_buf_len - ((size.x - idx + percent_buf_len - 1) % percent_buf_len) - 1] else this.configuration.cp,
+                            } else this.configuration.cp,
+                        };
+                        // NOTE do not write over the contents of this `Container`'s `Size`
+                        if (idx == cells.len - 1) break;
+                    }
+                }
+            };
+        }
+    };
+    return progress_struct.progress_fn;
+}
+
 const std = @import("std");
 const assert = std.debug.assert;
 const meta = std.meta;
@@ -1225,3 +1321,78 @@ test "button" {
         else => false,
     });
 }
+
+test "progress" {
+    const allocator = std.testing.allocator;
+    const event = @import("event.zig");
+    const Event = event.mergeTaggedUnions(event.SystemEvent, union(enum) {
+        progress: u8,
+    });
+    const testing = @import("testing.zig");
+    const Queue = @import("queue").Queue(Event, 256);
+
+    const size: Point = .{
+        .x = 30,
+        .y = 20,
+    };
+
+    var container: Container(Event) = try .init(allocator, .{
+        .layout = .{
+            .padding = .all(1),
+        },
+        .rectangle = .{ .fill = .white },
+    }, .{});
+    defer container.deinit();
+
+    var progress: Progress(Event, Queue)(.progress) = .init(&.{}, .{
+        .percent = .{ .enabled = true },
+        .fg = .green,
+        .bg = .grey,
+    });
+    const progress_container: Container(Event) = try .init(allocator, .{}, progress.element());
+    try container.append(progress_container);
+
+    var renderer: testing.Renderer = .init(allocator, size);
+    defer renderer.deinit();
+
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(Event), &container);
+    // try testing.expectEqualCells(.{}, renderer.size, @import("test/element/progress_zero.zon"), renderer.screen);
+
+    // test the progress of the `Element`
+    try container.handle(.{
+        .progress = 25,
+    });
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(Event), &container);
+    // try testing.expectEqualCells(.{}, renderer.size, @import("test/element/progress_one_quarter.zon"), renderer.screen);
+
+    // test the progress of the `Element`
+    try container.handle(.{
+        .progress = 50,
+    });
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(Event), &container);
+    // try testing.expectEqualCells(.{}, renderer.size, @import("test/element/progress_half.zon"), renderer.screen);
+
+    // test the progress of the `Element`
+    try container.handle(.{
+        .progress = 75,
+    });
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(Event), &container);
+    // try testing.expectEqualCells(.{}, renderer.size, @import("test/element/progress_three_quarter.zon"), renderer.screen);
+
+    // test the progress of the `Element`
+    try container.handle(.{
+        .progress = 100,
+    });
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(Event), &container);
+    // try testing.expectEqualCells(.{}, renderer.size, @import("test/element/progress_one_hundred.zon"), renderer.screen);
+}