feat(element/progress): Progress bar implementation as an Element

src/element.zig

@@ -400,7 +400,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 +651,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 {
+                    var 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 +1325,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);
+}