feat(example/input): readline shortcuts; better navigation;

This will be the basis for a Textfield `Element` implementation to make
it easier to add user inputs into the container structures.

.gitea/workflows/release.yaml

@@ -15,7 +15,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup zig installation
-        uses: mlugg/setup-zig@v1
+        uses: mlugg/setup-zig@v2
         with:
           version: master
       - name: Run tests

.gitea/workflows/test.yaml

@@ -14,7 +14,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
       - name: Setup zig installation
-        uses: mlugg/setup-zig@v1
+        uses: mlugg/setup-zig@v2
         with:
           version: master
       - name: Lint check

build.zig

@@ -1,5 +1,3 @@
-const std = @import("std");
-
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
@@ -7,7 +5,9 @@ pub fn build(b: *std.Build) void {
     const Examples = enum {
         all,
         demo,
+        continuous,
         // elements:
+        alignment,
         button,
         input,
         scrollable,
@@ -24,9 +24,13 @@ pub fn build(b: *std.Build) void {
     };
 
     const example = b.option(Examples, "example", "Example to build and/or run. (default: all)") orelse .all;
+    const debug_rendering = b.option(bool, "debug", "Enable debug rendering. Highlight origin's, size's, padding's, gap's, etc. (default: false)") orelse false;
+    // NOTE do not support debug rendering in release builds
+    if (debug_rendering == true and optimize != .Debug) @panic("Cannot enable debug rendering in non-debug builds.");
 
     const options = b.addOptions();
-    options.addOption(Examples, "example", example);
+    options.addOption(bool, "debug", debug_rendering);
+    const options_module = options.createModule();
 
     // dependencies
     const zg = b.dependency("zg", .{
@@ -36,163 +40,62 @@ pub fn build(b: *std.Build) void {
 
     // library
     const lib = b.addModule("zterm", .{
-        .root_source_file = b.path("src/zterm.zig"),
+        .root_source_file = b.path("src/root.zig"),
         .target = target,
         .optimize = optimize,
     });
     lib.addImport("code_point", zg.module("code_point"));
+    lib.addImport("build_options", options_module);
 
     //--- Examples ---
-
+    const examples = std.meta.fields(Examples);
-    // demo:
+    inline for (examples) |e| {
-    const demo = b.addExecutable(.{
+        if (@as(Examples, @enumFromInt(e.value)) == .all) continue; // skip `.all` entry
-        .name = "demo",
+        const demo = b.addExecutable(.{
-        .root_source_file = b.path("examples/demo.zig"),
+            .name = e.name,
-        .target = target,
+            .root_source_file = b.path(switch (@as(Examples, @enumFromInt(e.value))) {
-        .optimize = optimize,
+                .demo => "examples/demo.zig",
-    });
+                .continuous => "examples/continuous.zig",
-    demo.root_module.addImport("zterm", lib);
+                // elements:
-
+                .alignment => "examples/elements/alignment.zig",
-    // elements:
+                .button => "examples/elements/button.zig",
-    const button = b.addExecutable(.{
+                .input => "examples/elements/input.zig",
-        .name = "button",
+                .scrollable => "examples/elements/scrollable.zig",
-        .root_source_file = b.path("examples/elements/button.zig"),
+                // layouts:
-        .target = target,
+                .vertical => "examples/layouts/vertical.zig",
-        .optimize = optimize,
+                .horizontal => "examples/layouts/horizontal.zig",
-    });
+                .grid => "examples/layouts/grid.zig",
-    button.root_module.addImport("zterm", lib);
+                .mixed => "examples/layouts/mixed.zig",
-
+                // styles:
-    const input = b.addExecutable(.{
+                .text => "examples/styles/text.zig",
-        .name = "input",
+                .palette => "examples/styles/palette.zig",
-        .root_source_file = b.path("examples/elements/input.zig"),
+                // error handling
-        .target = target,
+                .errors => "examples/errors.zig",
-        .optimize = optimize,
+                .all => unreachable, // should never happen
-    });
+            }),
-    input.root_module.addImport("zterm", lib);
+            .target = target,
-
+            .optimize = optimize,
-    const scrollable = b.addExecutable(.{
+        });
-        .name = "scrollable",
+        // import dependencies
-        .root_source_file = b.path("examples/elements/scrollable.zig"),
+        demo.root_module.addImport("zterm", lib);
-        .target = target,
+        // mapping of user selected example to compile step
-        .optimize = optimize,
+        if (@intFromEnum(example) == e.value or example == .all) b.installArtifact(demo);
-    });
+    }
-    scrollable.root_module.addImport("zterm", lib);
-
-    // layouts:
-    const vertical = b.addExecutable(.{
-        .name = "vertical",
-        .root_source_file = b.path("examples/layouts/vertical.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    vertical.root_module.addImport("zterm", lib);
-
-    const horizontal = b.addExecutable(.{
-        .name = "horizontal",
-        .root_source_file = b.path("examples/layouts/horizontal.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    horizontal.root_module.addImport("zterm", lib);
-
-    const grid = b.addExecutable(.{
-        .name = "grid",
-        .root_source_file = b.path("examples/layouts/grid.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    grid.root_module.addImport("zterm", lib);
-
-    const mixed = b.addExecutable(.{
-        .name = "mixed",
-        .root_source_file = b.path("examples/layouts/mixed.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    mixed.root_module.addImport("zterm", lib);
-
-    // styles:
-    const palette = b.addExecutable(.{
-        .name = "palette",
-        .root_source_file = b.path("examples/styles/palette.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    palette.root_module.addImport("zterm", lib);
-
-    const text = b.addExecutable(.{
-        .name = "text",
-        .root_source_file = b.path("examples/styles/text.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    text.root_module.addImport("zterm", lib);
-
-    // error handling:
-    const errors = b.addExecutable(.{
-        .name = "errors",
-        .root_source_file = b.path("examples/errors.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    errors.root_module.addImport("zterm", lib);
-
-    // mapping of user selected example to compile step
-    const exe = switch (example) {
-        .demo => demo,
-        // elements:
-        .button => button,
-        .input => input,
-        .scrollable => scrollable,
-        // layouts:
-        .vertical => vertical,
-        .horizontal => horizontal,
-        .grid => grid,
-        .mixed => mixed,
-        // styles:
-        .text => text,
-        .palette => palette,
-        // error handling:
-        .errors => errors,
-        else => blk: {
-            b.installArtifact(button);
-            b.installArtifact(input);
-            b.installArtifact(scrollable);
-            b.installArtifact(vertical);
-            b.installArtifact(horizontal);
-            b.installArtifact(grid);
-            b.installArtifact(mixed);
-            b.installArtifact(text);
-            b.installArtifact(palette);
-            b.installArtifact(errors);
-            break :blk demo;
-        },
-    };
-    b.installArtifact(exe);
-
-    // zig build run
-    const run_cmd = b.addRunArtifact(exe);
-    run_cmd.step.dependOn(b.getInstallStep());
-    // Allow additional arguments, like this: `zig build run -- arg1 arg2 etc`
-    if (b.args) |args| run_cmd.addArgs(args);
-
-    // This creates a build step. It will be visible in the `zig build --help` menu,
-    // and can be selected like this: `zig build run`
-    // This will evaluate the `run` step rather than the default, which is "install".
-    const run_step = b.step("run", "Run the app");
-    run_step.dependOn(&run_cmd.step);
 
     // zig build test
     const lib_unit_tests = b.addTest(.{
-        .root_source_file = b.path("src/zterm.zig"),
+        .root_source_file = b.path("src/root.zig"),
         .target = target,
         .optimize = optimize,
     });
     lib_unit_tests.root_module.addImport("code_point", zg.module("code_point"));
     lib_unit_tests.root_module.addImport("DisplayWidth", zg.module("DisplayWidth"));
+    lib_unit_tests.root_module.addImport("build_options", options_module);
 
     const run_lib_unit_tests = b.addRunArtifact(lib_unit_tests);
 
     const test_step = b.step("test", "Run unit tests");
     test_step.dependOn(&run_lib_unit_tests.step);
 }
+
+const std = @import("std");

build.zig.zon

@@ -24,7 +24,7 @@
 
     // This is a [Semantic Version](https://semver.org/).
     // In a future version of Zig it will be used for package deduplication.
-    .version = "0.1.0",
+    .version = "0.3.0",
 
     // Tracks the earliest Zig version that the package considers to be a
     // supported use case.
@@ -37,8 +37,8 @@
     // internet connectivity.
     .dependencies = .{
         .zg = .{
-            .url = "git+https://codeberg.org/atman/zg#4a002763419a34d61dcbb1f415821b83b9bf8ddc",
+            .url = "git+https://codeberg.org/atman/zg#0b05141b033043c5f7bcd72048a48eef6531ea6c",
-            .hash = "1220f3e29bc40856bfc06e0ee133f814b0011c76de987d8a6a458c2f34d82708899a",
+            .hash = "zg-0.14.0-oGqU3KEFswIffnDu8eAE2XlhzwcfgjwtM6akIc5L7cEV",
         },
     },
     .paths = .{

examples/continuous.zig

@@ -0,0 +1,249 @@
+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;
+        }
+    }
+};
+
+/// Spinner element implementation that runs a simple animation that requires
+/// the continuous draw loop.
+const Spinner = struct {
+    counter: u8 = 0,
+    index: u8 = 0,
+
+    const map: [6]u21 = .{ '𜺎', '𜺍', '𜺇', '𜹯', '𜹿', '𜺋' };
+
+    pub fn element(this: *@This()) App.Element {
+        return .{
+            .ptr = this,
+            .vtable = &.{
+                .content = content,
+            },
+        };
+    }
+
+    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));
+
+        cells[size.x + 1].cp = map[this.index];
+
+        this.counter += 1;
+        if (this.counter >= 20) {
+            this.index += 1;
+            this.index %= 6;
+            this.counter = 0;
+        }
+    }
+};
+
+const InputField = struct {
+    input: std.ArrayList(u21),
+    queue: *App.Queue,
+
+    pub fn init(allocator: std.mem.Allocator, queue: *App.Queue) @This() {
+        return .{
+            .input = .init(allocator),
+            .queue = queue,
+        };
+    }
+
+    pub fn deinit(this: @This()) void {
+        this.input.deinit();
+    }
+
+    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) {
+            .key => |key| {
+                if (key.isAscii()) try this.input.append(key.cp);
+
+                // TODO support arrow keys for navigation?
+                // TODO support readline keybindings (i.e. ctrl-k, ctrl-u, ctrl-b, ctrl-f, etc. and the equivalent alt bindings)
+                // create an own `Element` implementation from this
+
+                if (key.eql(.{ .cp = zterm.input.Enter }) or key.eql(.{ .cp = zterm.input.KpEnter }))
+                    this.queue.push(.{ .accept = try this.input.toOwnedSlice() });
+
+                if (key.eql(.{ .cp = zterm.input.Backspace }))
+                    _ = this.input.pop();
+
+                if (key.eql(.{ .cp = zterm.input.Delete }) or key.eql(.{ .cp = zterm.input.KpDelete }))
+                    _ = this.input.pop();
+            },
+            else => {},
+        }
+    }
+
+    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.input.items.len == 0) return;
+
+        const row = 1;
+        const col = 1;
+        const anchor = (row * size.x) + col;
+
+        for (this.input.items, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .black;
+            cells[anchor + idx].style.cursor = false;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+
+            if (idx == this.input.items.len - 1) cells[anchor + idx + 1].style.cursor = true;
+        }
+    }
+};
+
+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 input_field: InputField = .init(allocator, &app.queue);
+    defer input_field.deinit();
+
+    var quit_text: QuitText = .{};
+    var spinner: Spinner = .{};
+
+    var container = try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+        .layout = .{
+            .direction = .vertical,
+            .padding = .all(5),
+        },
+    }, quit_text.element());
+    defer container.deinit();
+
+    try container.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+        .size = .{
+            .grow = .horizontal,
+            .dim = .{ .y = 10 },
+        },
+    }, input_field.element()));
+
+    const nested_container: App.Container = try .init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+    }, spinner.element());
+    try container.append(nested_container);
+
+    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;
+
+    // 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;
+        }
+
+        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| {
+                    log.debug("key {any}", .{key});
+                    if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit();
+                },
+                .accept => |input| {
+                    defer allocator.free(input);
+                    var string = try allocator.alloc(u8, input.len);
+                    defer allocator.free(string);
+                    for (0.., input) |i, char| string[i] = @intCast(char);
+                    log.debug("Accepted input '{s}'", .{string});
+                },
+                .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) {
+    accept: []u21,
+});

examples/demo.zig

@@ -1,11 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const input = zterm.input;
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit. Press ctrl+n to launch helix.";
 
@@ -15,7 +7,7 @@ const QuitText = struct {
 
     pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const y = 2;
         const x = size.x / 2 -| (text.len / 2);
@@ -36,7 +28,7 @@ pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
     // TODO maybe create own allocator as some sort of arena allocator to have consistent memory usage
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -75,7 +67,7 @@ pub fn main() !void {
     }, .{}));
     defer box.deinit();
 
-    var scrollable: App.Scrollable = .{ .container = box };
+    var scrollable: App.Scrollable = .init(box, .disabled);
 
     var container = try App.Container.init(allocator, .{
         .layout = .{
@@ -87,15 +79,54 @@ pub fn main() !void {
     }, quit_text.element());
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
-    try container.append(try App.Container.init(allocator, .{
+    var nested_container: App.Container = try .init(allocator, .{
+        .layout = .{
+            .direction = .vertical,
+            .separator = .{
+                .enabled = true,
+            },
+        },
+    }, .{});
+    var inner_container: App.Container = try .init(allocator, .{
+        .layout = .{
+            .direction = .vertical,
+        },
         .border = .{
             .color = .light_blue,
             .sides = .all,
         },
+    }, .{});
+    try inner_container.append(try .init(allocator, .{
+        .rectangle = .{
+            .fill = .blue,
+        },
         .size = .{
-            .dim = .{ .x = 100 },
+            .grow = .horizontal,
+            .dim = .{ .y = 5 },
         },
     }, .{}));
+    try inner_container.append(try .init(allocator, .{
+        .rectangle = .{
+            .fill = .red,
+        },
+        .size = .{
+            .grow = .horizontal,
+            .dim = .{ .y = 5 },
+        },
+    }, .{}));
+    try inner_container.append(try .init(allocator, .{
+        .rectangle = .{
+            .fill = .green,
+        },
+    }, .{}));
+    try nested_container.append(inner_container);
+    try nested_container.append(try .init(allocator, .{
+        .size = .{
+            .grow = .horizontal,
+            .dim = .{ .y = 1 },
+        },
+    }, .{}));
+    try container.append(nested_container);
     try container.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .blue },
         .size = .{
@@ -119,6 +150,7 @@ pub fn main() !void {
 
                 if (key.eql(.{ .cp = 'n', .mod = .{ .ctrl = true } })) {
                     try app.interrupt();
+                    renderer.size = .{}; // reset size, such that next resize will cause a full re-draw!
                     defer app.start() catch @panic("could not start app event loop");
                     var child = std.process.Child.init(&.{"hx"}, allocator);
                     _ = child.spawnAndWait() catch |err| app.postEvent(.{
@@ -149,10 +181,18 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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 input = zterm.input;
+const App = zterm.App(union(enum) {});

examples/elements/alignment.zig

@@ -0,0 +1,99 @@
+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 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();
+    }
+}
+
+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) {});

examples/elements/button.zig

@@ -1,12 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {
-    click: [:0]const u8,
-});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -16,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -66,7 +57,7 @@ const Clickable = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = size.y / 2 -| (text.len / 2);
         const col = size.x / 2 -| (text.len / 2);
@@ -86,7 +77,7 @@ const Clickable = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -139,10 +130,19 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {
+    click: [:0]const u8,
+});

examples/elements/input.zig

@@ -1,12 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {
-    accept: []u21,
-});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -16,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -33,10 +24,18 @@ const QuitText = struct {
     }
 };
 
+// TODO create an own `Element` implementation from this
 const InputField = struct {
+    /// Offset from the end describing the current position of the cursor.
+    cursor_offset: usize = 0,
+    /// Array holding the value of the input.
     input: std.ArrayList(u21),
+    /// Reference to the app's queue to issue the associated event to trigger when completing the input.
     queue: *App.Queue,
 
+    // TODO make the event to trigger user defined (needs to be `comptime`)
+    // - can this even be agnostic to `u8` / `u21`?
+
     pub fn init(allocator: std.mem.Allocator, queue: *App.Queue) @This() {
         return .{
             .input = .init(allocator),
@@ -62,13 +61,68 @@ const InputField = struct {
         const this: *@This() = @ptrCast(@alignCast(ctx));
         switch (event) {
             .key => |key| {
-                if (key.isAscii()) try this.input.append(key.cp);
+                assert(this.cursor_offset >= 0 and this.cursor_offset <= this.input.items.len);
 
-                if (key.eql(.{ .cp = zterm.input.Enter }) or key.eql(.{ .cp = zterm.input.KpEnter }))
+                // see *form* implementation in `zk`, which might become part of the library
+                if (key.eql(.{ .cp = zterm.input.Left }) or key.eql(.{ .cp = zterm.input.KpLeft }) or key.eql(.{ .cp = 'b', .mod = .{ .ctrl = true } })) {
+                    if (this.cursor_offset < this.input.items.len) this.cursor_offset += 1;
+                }
+
+                if (key.eql(.{ .cp = zterm.input.Right }) or key.eql(.{ .cp = zterm.input.KpRight }) or key.eql(.{ .cp = 'f', .mod = .{ .ctrl = true } }))
+                    this.cursor_offset -|= 1;
+
+                if (key.eql(.{ .cp = 'e', .mod = .{ .ctrl = true } })) this.cursor_offset = 0;
+
+                if (key.eql(.{ .cp = 'a', .mod = .{ .ctrl = true } })) this.cursor_offset = this.input.items.len;
+
+                if (key.eql(.{ .cp = zterm.input.Backspace })) {
+                    if (this.cursor_offset < this.input.items.len) {
+                        _ = if (this.cursor_offset == 0) this.input.pop() else this.input.orderedRemove(this.input.items.len - this.cursor_offset - 1);
+                    }
+                }
+
+                if (key.eql(.{ .cp = zterm.input.Delete }) or key.eql(.{ .cp = zterm.input.KpDelete })) {
+                    if (this.cursor_offset > 0) {
+                        _ = this.input.orderedRemove(this.input.items.len - this.cursor_offset);
+                        this.cursor_offset -= 1;
+                    }
+                }
+
+                // TODO support readline keybindings (i.e. alt bindings alt-b, alt-f
+                // TODO maybe even ctrl-left, ctrl-right?)
+                // readline commands
+                if (key.eql(.{ .cp = 'k', .mod = .{ .ctrl = true } })) {
+                    while (this.cursor_offset > 0) {
+                        _ = this.input.pop();
+                        this.cursor_offset -= 1;
+                    }
+                }
+
+                if (key.eql(.{ .cp = 'u', .mod = .{ .ctrl = true } })) {
+                    const len = this.input.items.len - this.cursor_offset;
+                    for (0..len) |_| _ = this.input.orderedRemove(0);
+                    this.cursor_offset = this.input.items.len;
+                }
+
+                if (key.eql(.{ .cp = 'w', .mod = .{ .ctrl = true } })) {
+                    var non_whitespace = false;
+                    while (this.cursor_offset < this.input.items.len) {
+                        if (non_whitespace and this.input.items[this.input.items.len - this.cursor_offset - 1] == ' ') break;
+
+                        // see backspace
+                        const removed = if (this.cursor_offset == 0) this.input.pop() else this.input.orderedRemove(this.input.items.len - this.cursor_offset - 1);
+                        if (removed != ' ') non_whitespace = true;
+                    }
+                }
+
+                // usual input keys
+                if (key.isAscii()) try this.input.insert(this.input.items.len - this.cursor_offset, key.cp);
+
+                // TODO enter to accept?
+                if (key.eql(.{ .cp = zterm.input.Enter }) or key.eql(.{ .cp = zterm.input.KpEnter })) {
                     this.queue.push(.{ .accept = try this.input.toOwnedSlice() });
-
+                    this.cursor_offset = 0;
-                if (key.eql(.{ .cp = zterm.input.Backspace }) or key.eql(.{ .cp = zterm.input.Delete }) or key.eql(.{ .cp = zterm.input.KpDelete }))
+                }
-                    _ = this.input.pop();
             },
             else => {},
         }
@@ -76,20 +130,51 @@ const InputField = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
-
-        if (this.input.items.len == 0) return;
-
-        const row = 1;
-        const col = 1;
-        const anchor = (row * size.x) + col;
 
+        // TODO add configuration for coloring the text!
         for (this.input.items, 0..) |cp, idx| {
-            cells[anchor + idx].style.fg = .black;
+            cells[idx].style.fg = .black;
-            cells[anchor + idx].cp = cp;
+            cells[idx].cp = cp;
 
             // NOTE do not write over the contents of this `Container`'s `Size`
-            if (anchor + idx == cells.len - 1) break;
+            if (idx == cells.len - 1) break;
+        }
+        // TODO show ellipse `..` (maybe with configuration where - start, middle, end)
+        // show cursor after text (if there is still space available)
+        if (this.input.items.len < cells.len) cells[this.input.items.len - this.cursor_offset].style.cursor = true;
+    }
+};
+
+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;
         }
     }
 };
@@ -97,7 +182,7 @@ const InputField = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -109,17 +194,47 @@ pub fn main() !void {
     var input_field: InputField = .init(allocator, &app.queue);
     defer input_field.deinit();
 
+    var mouse_draw: MouseDraw = .{};
+    var second_mouse_draw: MouseDraw = .{};
     var quit_text: QuitText = .{};
 
-    const element = input_field.element();
-
     var container = try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .grey },
-        .layout = .{ .padding = .all(5) },
+        .layout = .{
+            .direction = .vertical,
+            .padding = .all(5),
+        },
     }, quit_text.element());
     defer container.deinit();
 
-    try container.append(try App.Container.init(allocator, .{ .rectangle = .{ .fill = .light_grey } }, element));
+    try container.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+        .size = .{
+            .grow = .horizontal,
+            .dim = .{ .y = 10 },
+        },
+    }, input_field.element()));
+
+    var nested_container: App.Container = try .init(allocator, .{
+        .border = .{
+            .sides = .all,
+            .color = .black,
+        },
+        .rectangle = .{ .fill = .light_grey },
+        .layout = .{
+            .separator = .{
+                .enabled = true,
+                .color = .black,
+            },
+        },
+    }, .{});
+    try nested_container.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+    }, mouse_draw.element()));
+    try nested_container.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .light_grey },
+    }, second_mouse_draw.element()));
+    try container.append(nested_container);
 
     try app.start();
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
@@ -134,7 +249,10 @@ pub fn main() !void {
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
             .accept => |input| {
                 defer allocator.free(input);
-                log.info("Accepted input {any}", .{input});
+                var string = try allocator.alloc(u8, input.len);
+                defer allocator.free(string);
+                for (0.., input) |i, char| string[i] = @intCast(char);
+                log.debug("Accepted input '{s}'", .{string});
             },
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
@@ -153,10 +271,19 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {
+    accept: []u21,
+});

examples/elements/scrollable.zig

@@ -1,11 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const input = zterm.input;
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -15,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -44,7 +36,7 @@ const HelloWorldText = packed struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = size.y / 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -65,7 +57,7 @@ pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
     // TODO maybe create own allocator as some sort of arena allocator to have consistent memory usage
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer {
         const deinit_status = gpa.deinit();
         if (deinit_status == .leak) {
@@ -156,10 +148,10 @@ pub fn main() !void {
     defer container.deinit();
 
     // place empty container containing the element of the scrollable Container.
-    var scrollable_top: App.Scrollable = .{ .container = top_box };
+    var scrollable_top: App.Scrollable = .init(top_box, .enabled(.grey));
     try container.append(try App.Container.init(allocator, .{}, scrollable_top.element()));
 
-    var scrollable_bottom: App.Scrollable = .{ .container = bottom_box };
+    var scrollable_bottom: App.Scrollable = .init(bottom_box, .enabled(.white));
     try container.append(try App.Container.init(allocator, .{}, scrollable_bottom.element()));
 
     try app.start();
@@ -190,10 +182,18 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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 input = zterm.input;
+const App = zterm.App(union(enum) {});

examples/errors.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -14,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -40,7 +33,7 @@ const InfoText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -67,7 +60,7 @@ const ErrorNotification = struct {
     fn handle(ctx: *anyopaque, event: App.Event) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
         switch (event) {
-            .key => |key| if (!key.isAscii()) return error.UnsupportedKey,
+            .key => |key| if (!key.isAscii()) return zterm.Error.TooSmall,
             .err => |err| this.msg = err.msg,
             else => {},
         }
@@ -75,7 +68,7 @@ const ErrorNotification = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         if (this.msg) |msg| {
             const row = size.y -| 2;
@@ -99,7 +92,7 @@ const ErrorNotification = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -150,10 +143,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {});

examples/layouts/grid.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -106,10 +99,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {});

examples/layouts/horizontal.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -98,10 +91,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {});

examples/layouts/mixed.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -114,10 +107,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {});

examples/layouts/vertical.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -17,7 +10,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -37,7 +30,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -97,10 +90,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {});

examples/styles/palette.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -14,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -34,7 +27,7 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -60,10 +53,10 @@ pub fn main() !void {
     defer box.deinit();
 
     inline for (std.meta.fields(zterm.Color)) |field| {
-        if (comptime field.value == 0) continue; // zterm.Color.default == 0 -> skip
+        if (field.value == 0) continue; // zterm.Color.default == 0 -> skip
         try box.append(try App.Container.init(allocator, .{ .rectangle = .{ .fill = @enumFromInt(field.value) } }, .{}));
     }
-    var scrollable: App.Scrollable = .{ .container = box };
+    var scrollable: App.Scrollable = .init(box, .disabled);
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
     try app.start();
@@ -93,10 +86,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {});

examples/styles/text.zig

@@ -1,10 +1,3 @@
-const std = @import("std");
-const zterm = @import("zterm");
-
-const App = zterm.App(union(enum) {});
-
-const log = std.log.scoped(.default);
-
 const QuitText = struct {
     const text = "Press ctrl+c to quit.";
 
@@ -14,7 +7,7 @@ const QuitText = struct {
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
         const col = size.x / 2 -| (text.len / 2);
@@ -39,20 +32,20 @@ const TextStyles = struct {
     }
 
     fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
-        @setEvalBranchQuota(50000);
+        @setEvalBranchQuota(10000);
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         var row: usize = 0;
         var col: usize = 0;
 
         // Color
         inline for (std.meta.fields(zterm.Color)) |bg_field| {
-            if (comptime bg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
+            if (bg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
 
             inline for (std.meta.fields(zterm.Color)) |fg_field| {
-                if (comptime fg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
+                if (fg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
-                if (comptime fg_field.value == bg_field.value) continue;
+                if (fg_field.value == bg_field.value) continue;
 
                 // witouth any emphasis
                 for (text) |cp| {
@@ -64,7 +57,7 @@ const TextStyles = struct {
 
                 // emphasis (no combinations)
                 inline for (std.meta.fields(zterm.Style.Emphasis)) |emp_field| {
-                    if (comptime emp_field.value == 0) continue; // zterm.Style.Emphasis.reset == 0 -> skip
+                    if (emp_field.value == 0) continue; // zterm.Style.Emphasis.reset == 0 -> skip
                     const emphasis: zterm.Style.Emphasis = @enumFromInt(emp_field.value);
 
                     for (text) |cp| {
@@ -85,7 +78,7 @@ const TextStyles = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
@@ -118,7 +111,7 @@ pub fn main() !void {
     }, text_styles.element());
     defer box.deinit();
 
-    var scrollable: App.Scrollable = .{ .container = box };
+    var scrollable: App.Scrollable = .init(box, .disabled);
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
     try app.start();
@@ -148,10 +141,17 @@ pub fn main() !void {
             else => {},
         }
 
-        try renderer.resize();
+        container.resize(try renderer.resize());
-        container.resize(renderer.size);
         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) {});

src/app.zig

@@ -1,19 +1,4 @@
 //! Application type for TUI-applications
-const std = @import("std");
-const code_point = @import("code_point");
-const event = @import("event.zig");
-const input = @import("input.zig");
-const terminal = @import("terminal.zig");
-const queue = @import("queue.zig");
-
-const mergeTaggedUnions = event.mergeTaggedUnions;
-const isTaggedUnion = event.isTaggedUnion;
-
-const Mouse = input.Mouse;
-const Key = input.Key;
-const Point = @import("point.zig").Point;
-
-const log = std.log.scoped(.app);
 
 /// Create the App Type with the associated user events _E_ which describes
 /// an tagged union for all the user events that can be send through the
@@ -39,57 +24,48 @@ pub fn App(comptime E: type) type {
         @compileError("Provided user event `E` for `App(comptime E: type)` is not of type `union(enum)`.");
     }
     return struct {
-        pub const Event = mergeTaggedUnions(event.SystemEvent, E);
-        pub const Container = @import("container.zig").Container(Event);
-        const element = @import("element.zig");
-        pub const Element = element.Element(Event);
-        pub const Scrollable = element.Scrollable(Event);
-        pub const Queue = queue.Queue(Event, 256);
-
         queue: Queue,
-        thread: ?std.Thread,
+        thread: ?Thread = null,
-        quit_event: std.Thread.ResetEvent,
+        quit_event: Thread.ResetEvent,
-        termios: ?std.posix.termios = null,
+        termios: ?posix.termios = null,
-        attached_handler: bool = false,
+        winch_registered: bool = false,
 
-        pub const SignalHandler = struct {
+        // global variable for the registered handler for WINCH
-            context: *anyopaque,
+        var handler_ctx: *anyopaque = undefined;
-            callback: *const fn (context: *anyopaque) void,
+        /// registered WINCH handler to report resize events
-        };
+        fn handleWinch(_: c_int) callconv(.C) void {
+            const this: *@This() = @ptrCast(@alignCast(handler_ctx));
+            // NOTE this does not have to be done if in-band resize events are supported
+            // -> the signal might not work correctly when hosting the application over ssh!
+            this.postEvent(.resize);
+        }
 
         pub const init: @This() = .{
             .queue = .{},
-            .thread = null,
             .quit_event = .{},
-            .termios = null,
-            .attached_handler = false,
         };
 
         pub fn start(this: *@This()) !void {
             if (this.thread) |_| return;
 
-            if (!this.attached_handler) {
+            // post init event (as the very first element to be in the queue - event loop)
-                var winch_act = std.posix.Sigaction{
+            this.postEvent(.init);
-                    .handler = .{ .handler = @This().handleWinch },
+
-                    .mask = std.posix.empty_sigset,
+            if (!this.winch_registered) {
+                handler_ctx = this;
+                var act = posix.Sigaction{
+                    .handler = .{ .handler = handleWinch },
+                    .mask = posix.sigemptyset(),
                     .flags = 0,
                 };
-                std.posix.sigaction(std.posix.SIG.WINCH, &winch_act, null);
+                posix.sigaction(posix.SIG.WINCH, &act, null);
-
+                this.winch_registered = true;
-                try registerWinch(.{
-                    .context = this,
-                    .callback = @This().winsizeCallback,
-                });
-                this.attached_handler = true;
-
-                // post init event (as the very first element to be in the queue - event loop)
-                this.postEvent(.init);
             }
 
             this.quit_event.reset();
-            this.thread = try std.Thread.spawn(.{}, @This().run, .{this});
+            this.thread = try Thread.spawn(.{}, @This().run, .{this});
 
-            var termios: std.posix.termios = undefined;
+            var termios: posix.termios = undefined;
             try terminal.enableRawMode(&termios);
             if (this.termios) |_| {} else this.termios = termios;
 
@@ -139,27 +115,6 @@ pub fn App(comptime E: type) type {
             this.queue.push(e);
         }
 
-        fn winsizeCallback(ptr: *anyopaque) void {
-            const this: *@This() = @ptrCast(@alignCast(ptr));
-            _ = this;
-            // this.postEvent(.{ .size = terminal.getTerminalSize() });
-        }
-
-        var winch_handler: ?SignalHandler = null;
-
-        fn registerWinch(handler: SignalHandler) !void {
-            if (winch_handler) |_| {
-                @panic("Cannot register another WINCH handler.");
-            }
-            winch_handler = handler;
-        }
-
-        fn handleWinch(_: c_int) callconv(.C) void {
-            if (winch_handler) |handler| {
-                handler.callback(handler.context);
-            }
-        }
-
         fn run(this: *@This()) !void {
             // thread to read user inputs
             var buf: [256]u8 = undefined;
@@ -208,6 +163,9 @@ pub fn App(comptime E: type) type {
                                         // Legacy keys
                                         // CSI {ABCDEFHPQS}
                                         // CSI 1 ; modifier:event_type {ABCDEFHPQS}
+                                        var field_iter = std.mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
+                                        _ = field_iter.next(); // skip first field
+
                                         const key: Key = .{
                                             .cp = switch (final) {
                                                 'A' => input.Up,
@@ -221,44 +179,79 @@ pub fn App(comptime E: type) type {
                                                 'Q' => input.F2,
                                                 'R' => input.F3,
                                                 'S' => input.F4,
-                                                else => unreachable, // switch case prevents in this case form ever happening
+                                                else => unreachable,
+                                            },
+                                            .mod = blk: {
+                                                // modifier_mask:event_type
+                                                var mod: Key.Modifier = .{};
+                                                const field_buf = field_iter.next() orelse break :blk mod;
+                                                var param_iter = std.mem.splitScalar(u8, field_buf, ':');
+                                                const modifier_buf = param_iter.next() orelse unreachable;
+                                                const modifier_mask = fmt.parseUnsigned(u8, modifier_buf, 10) catch break :blk mod;
+                                                if ((modifier_mask -| 1) & 1 != 0) mod.shift = true;
+                                                if ((modifier_mask -| 1) & 2 != 0) mod.alt = true;
+                                                if ((modifier_mask -| 1) & 4 != 0) mod.ctrl = true;
+                                                break :blk mod;
                                             },
                                         };
                                         this.postEvent(.{ .key = key });
                                     },
+                                    'Z' => this.postEvent(.{ .key = .{ .cp = input.Tab, .mod = .{ .shift = true } } }),
                                     '~' => {
                                         // Legacy keys
                                         // CSI number ~
                                         // CSI number ; modifier ~
                                         // CSI number ; modifier:event_type ; text_as_codepoint ~
-                                        var field_iter = std.mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
+                                        var field_iter = mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
-                                        const number_buf = field_iter.next() orelse unreachable; // always will have one field
-                                        const number = std.fmt.parseUnsigned(u16, number_buf, 10) catch break;
 
                                         const key: Key = .{
-                                            .cp = switch (number) {
+                                            .cp = blk: {
-                                                2 => input.Insert,
+                                                const number_buf = field_iter.next() orelse unreachable; // always will have one field
-                                                3 => input.Delete,
+                                                const number = fmt.parseUnsigned(u16, number_buf, 10) catch break;
-                                                5 => input.PageUp,
+                                                break :blk switch (number) {
-                                                6 => input.PageDown,
+                                                    2 => input.Insert,
-                                                7 => input.Home,
+                                                    3 => input.Delete,
-                                                8 => input.End,
+                                                    5 => input.PageUp,
-                                                11 => input.F1,
+                                                    6 => input.PageDown,
-                                                12 => input.F2,
+                                                    7 => input.Home,
-                                                13 => input.F3,
+                                                    8 => input.End,
-                                                14 => input.F4,
+                                                    11 => input.F1,
-                                                15 => input.F5,
+                                                    12 => input.F2,
-                                                17 => input.F6,
+                                                    13 => input.F3,
-                                                18 => input.F7,
+                                                    14 => input.F4,
-                                                19 => input.F8,
+                                                    15 => input.F5,
-                                                20 => input.F9,
+                                                    17 => input.F6,
-                                                21 => input.F10,
+                                                    18 => input.F7,
-                                                23 => input.F11,
+                                                    19 => input.F8,
-                                                24 => input.F12,
+                                                    20 => input.F9,
-                                                // 200 => return .{ .event = .paste_start, .n = sequence.len },
+                                                    21 => input.F10,
-                                                // 201 => return .{ .event = .paste_end, .n = sequence.len },
+                                                    23 => input.F11,
-                                                57427 => input.KpBegin,
+                                                    24 => input.F12,
-                                                else => unreachable,
+                                                    25 => input.F13,
+                                                    26 => input.F14,
+                                                    28 => input.F15,
+                                                    29 => input.F16,
+                                                    31 => input.F17,
+                                                    32 => input.F18,
+                                                    33 => input.F19,
+                                                    34 => input.F20,
+                                                    // 200 => return .{ .event = .paste_start, .n = sequence.len },
+                                                    // 201 => return .{ .event = .paste_end, .n = sequence.len },
+                                                    57399...57454 => |code| code,
+                                                    else => unreachable,
+                                                };
+                                            },
+                                            .mod = blk: {
+                                                // modifier_mask:event_type
+                                                var mod: Key.Modifier = .{};
+                                                const field_buf = field_iter.next() orelse break :blk mod;
+                                                var param_iter = std.mem.splitScalar(u8, field_buf, ':');
+                                                const modifier_buf = param_iter.next() orelse unreachable;
+                                                const modifier_mask = fmt.parseUnsigned(u8, modifier_buf, 10) catch break :blk mod;
+                                                if ((modifier_mask -| 1) & 1 != 0) mod.shift = true;
+                                                if ((modifier_mask -| 1) & 2 != 0) mod.alt = true;
+                                                if ((modifier_mask -| 1) & 4 != 0) mod.ctrl = true;
+                                                break :blk mod;
                                             },
                                         };
                                         this.postEvent(.{ .key = key });
@@ -267,14 +260,14 @@ pub fn App(comptime E: type) type {
                                     'I' => this.postEvent(.{ .focus = true }),
                                     'O' => this.postEvent(.{ .focus = false }),
                                     'M', 'm' => {
-                                        std.debug.assert(sequence.len >= 4);
+                                        assert(sequence.len >= 4);
                                         if (sequence[2] != '<') break;
 
-                                        const delim1 = std.mem.indexOfScalarPos(u8, sequence, 3, ';') orelse break;
+                                        const delim1 = mem.indexOfScalarPos(u8, sequence, 3, ';') orelse break;
-                                        const button_mask = std.fmt.parseUnsigned(u16, sequence[3..delim1], 10) catch break;
+                                        const button_mask = fmt.parseUnsigned(u16, sequence[3..delim1], 10) catch break;
-                                        const delim2 = std.mem.indexOfScalarPos(u8, sequence, delim1 + 1, ';') orelse break;
+                                        const delim2 = mem.indexOfScalarPos(u8, sequence, delim1 + 1, ';') orelse break;
-                                        const px = std.fmt.parseUnsigned(u16, sequence[delim1 + 1 .. delim2], 10) catch break;
+                                        const px = fmt.parseUnsigned(u16, sequence[delim1 + 1 .. delim2], 10) catch break;
-                                        const py = std.fmt.parseUnsigned(u16, sequence[delim2 + 1 .. sequence.len - 1], 10) catch break;
+                                        const py = fmt.parseUnsigned(u16, sequence[delim2 + 1 .. sequence.len - 1], 10) catch break;
 
                                         const mouse_bits = packed struct {
                                             const motion: u8 = 0b00100000;
@@ -314,14 +307,14 @@ pub fn App(comptime E: type) type {
                                         // Device Status Report
                                         // CSI Ps n
                                         // CSI ? Ps n
-                                        std.debug.assert(sequence.len >= 3);
+                                        assert(sequence.len >= 3);
                                     },
                                     't' => {
                                         // XTWINOPS
                                         // Split first into fields delimited by ';'
-                                        var iter = std.mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
+                                        var iter = mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
                                         const ps = iter.first();
-                                        if (std.mem.eql(u8, "48", ps)) {
+                                        if (mem.eql(u8, "48", ps)) {
                                             // in band window resize
                                             // CSI 48 ; height ; width ; height_pix ; width_pix t
                                             const width_char = iter.next() orelse break;
@@ -329,9 +322,10 @@ pub fn App(comptime E: type) type {
 
                                             _ = width_char;
                                             _ = height_char;
+                                            this.postEvent(.resize);
                                             // this.postEvent(.{ .size = .{
-                                            //     .x = std.fmt.parseUnsigned(u16, width_char, 10) catch break,
+                                            //     .x = fmt.parseUnsigned(u16, width_char, 10) catch break,
-                                            //     .y = std.fmt.parseUnsigned(u16, height_char, 10) catch break,
+                                            //     .y = fmt.parseUnsigned(u16, height_char, 10) catch break,
                                             // } });
                                         }
                                     },
@@ -347,9 +341,29 @@ pub fn App(comptime E: type) type {
                                     else => {},
                                 }
                             },
+                            0x50 => {
+                                // DCS
+                            },
+                            0x58 => {
+                                // SOS
+                            },
+                            0x5D => {
+                                // OSC
+                            },
                             // TODO parse corresponding codes
-                            // 0x5B => parseCsi(input, &self.buf), // CSI see https://github.com/rockorager/libvaxis/blob/main/src/Parser.zig
+                            0x5F => {
-                            else => {},
+                                // APC
+                                // parse for kitty graphics capabilities
+                            },
+                            else => {
+                                // alt + <char> keypress
+                                this.postEvent(.{
+                                    .key = .{
+                                        .cp = buf[1],
+                                        .mod = .{ .alt = true },
+                                    },
+                                });
+                            },
                         }
                     } else {
                         const b = buf[0];
@@ -357,10 +371,11 @@ pub fn App(comptime E: type) type {
                             0x00 => .{ .cp = '@', .mod = .{ .ctrl = true } },
                             0x08 => .{ .cp = input.Backspace },
                             0x09 => .{ .cp = input.Tab },
-                            0x0a, 0x0d => .{ .cp = input.Enter },
+                            0x0a => .{ .cp = 'j', .mod = .{ .ctrl = true } },
+                            0x0d => .{ .cp = input.Enter },
                             0x01...0x07, 0x0b...0x0c, 0x0e...0x1a => .{ .cp = b + 0x60, .mod = .{ .ctrl = true } },
                             0x1b => escape: {
-                                std.debug.assert(read_bytes == 1);
+                                assert(read_bytes == 1);
                                 break :escape .{ .cp = input.Escape };
                             },
                             0x7f => .{ .cp = input.Backspace },
@@ -377,5 +392,52 @@ pub fn App(comptime E: type) type {
                 break;
             }
         }
+
+        pub fn panic_handler(msg: []const u8, _: ?*std.builtin.StackTrace, ret_addr: ?usize) noreturn {
+            terminal.disableMouseSupport() catch {};
+            terminal.exitAltScreen() catch {};
+            terminal.showCursor() catch {};
+            var termios: posix.termios = .{
+                .iflag = .{},
+                .lflag = .{},
+                .cflag = .{},
+                .oflag = .{},
+                .cc = undefined,
+                .line = 0,
+                .ispeed = undefined,
+                .ospeed = undefined,
+            };
+            terminal.disableRawMode(&termios) catch {};
+            terminal.restoreScreen() catch {};
+            std.debug.defaultPanic(msg, ret_addr);
+        }
+
+        const element = @import("element.zig");
+        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);
     };
 }
+
+const log = std.log.scoped(.app);
+
+const std = @import("std");
+const mem = std.mem;
+const fmt = std.fmt;
+const posix = std.posix;
+const Thread = std.Thread;
+const assert = std.debug.assert;
+const code_point = @import("code_point");
+const event = @import("event.zig");
+const input = @import("input.zig");
+const terminal = @import("terminal.zig");
+const queue = @import("queue.zig");
+const mergeTaggedUnions = event.mergeTaggedUnions;
+const isTaggedUnion = event.isTaggedUnion;
+const Mouse = input.Mouse;
+const Key = input.Key;
+const Point = @import("point.zig").Point;

src/cell.zig

@@ -1,11 +1,8 @@
-const std = @import("std");
+//! Cell type containing content and formatting for each character in the terminal screen.
-const Style = @import("style.zig");
 
-pub const Cell = @This();
-
-style: Style = .{ .emphasis = &.{} },
 // TODO embrace `zg` dependency more due to utf-8 encoding
 cp: u21 = ' ',
+style: Style = .{ .emphasis = &.{} },
 
 pub fn eql(this: Cell, other: Cell) bool {
     return this.cp == other.cp and this.style.eql(other.style);
@@ -20,6 +17,10 @@ pub fn value(this: Cell, writer: anytype) !void {
     try this.style.value(writer, this.cp);
 }
 
+const std = @import("std");
+const Style = @import("style.zig");
+const Cell = @This();
+
 test "ascii styled text" {
     const cells: [4]Cell = .{
         .{ .cp = 'Y', .style = .{ .fg = .green, .bg = .grey, .emphasis = &.{} } },

src/color.zig

@@ -1,5 +1,3 @@
-const std = @import("std");
-
 pub const Color = enum(u8) {
     default = 0,
     black = 16,
@@ -20,19 +18,24 @@ pub const Color = enum(u8) {
     white,
     // TODO add further colors as described in https://gist.github.com/ConnerWill/d4b6c776b509add763e17f9f113fd25b # Color / Graphics Mode - 256 Colors
 
+    // TODO might be useful to use the std.ascii stuff!
+
     pub inline fn write(this: Color, writer: anytype, comptime coloring: enum { fg, bg, ul }) !void {
         if (this == .default) {
             switch (coloring) {
-                .fg => try std.fmt.format(writer, "39", .{}),
+                .fg => try format(writer, "39", .{}),
-                .bg => try std.fmt.format(writer, "49", .{}),
+                .bg => try format(writer, "49", .{}),
-                .ul => try std.fmt.format(writer, "59", .{}),
+                .ul => try format(writer, "59", .{}),
             }
         } else {
             switch (coloring) {
-                .fg => try std.fmt.format(writer, "38;5;{d}", .{@intFromEnum(this)}),
+                .fg => try format(writer, "38;5;{d}", .{@intFromEnum(this)}),
-                .bg => try std.fmt.format(writer, "48;5;{d}", .{@intFromEnum(this)}),
+                .bg => try format(writer, "48;5;{d}", .{@intFromEnum(this)}),
-                .ul => try std.fmt.format(writer, "58;5;{d}", .{@intFromEnum(this)}),
+                .ul => try format(writer, "58;5;{d}", .{@intFromEnum(this)}),
             }
         }
     }
 };
+
+const std = @import("std");
+const format = std.fmt.format;

src/container.zig

@@ -1,21 +1,5 @@
-const std = @import("std");
-
-const isTaggedUnion = @import("event.zig").isTaggedUnion;
-
-const Cell = @import("cell.zig");
-const Color = @import("color.zig").Color;
-const Point = @import("point.zig").Point;
-const Style = @import("style.zig");
-const Error = @import("error.zig").Error;
-
-const log = std.log.scoped(.container);
-
 /// Border configuration struct
 pub const Border = packed struct {
-    // corners:
-    const rounded_border: [6]u21 = .{ '╭', '─', '╮', '│', '╰', '╯' };
-    const squared_border: [6]u21 = .{ '┌', '─', '┐', '│', '└', '┘' };
-
     /// Color to use for the border
     color: Color = .default,
     /// Configure the corner type to be used for the border
@@ -39,13 +23,12 @@ pub const Border = packed struct {
     } = .{},
 
     pub fn content(this: @This(), cells: []Cell, size: Point) void {
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
-        const frame = switch (this.corners) {
+        const frame: [6]u21 = switch (this.corners) {
-            .rounded => Border.rounded_border,
+            .rounded => .{ '╭', '─', '╮', '│', '╰', '╯' },
-            .squared => Border.squared_border,
+            .squared => .{ '┌', '─', '┐', '│', '└', '┘' },
         };
-        std.debug.assert(frame.len == 6);
 
         // render top and bottom border
         if (this.sides.top or this.sides.bottom) {
@@ -155,13 +138,20 @@ pub const Rectangle = packed struct {
 
     // NOTE caller owns `Cells` slice and ensures that `cells.len == size.x * size.y`
     pub fn content(this: @This(), cells: []Cell, size: Point) void {
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         for (0..size.y) |row| {
             for (0..size.x) |col| {
                 cells[(row * size.x) + col].style.bg = this.fill;
             }
         }
+
+        // DEBUG render corresponding beginning of the rectangle for this `Container` *red*
+        if (comptime build_options.debug) {
+            cells[0].style.fg = .red;
+            cells[0].style.bg = .black;
+            cells[0].cp = 'r'; // 'r' for *rectangle*
+        }
     }
 
     test "fill color overwrite parent fill" {
@@ -299,11 +289,6 @@ pub const Rectangle = packed struct {
 
 /// Layout configuration struct
 pub const Layout = packed struct {
-    // separator.line:
-    const line: [2]u21 = .{ '│', '─' };
-    const dotted: [2]u21 = .{ '┆', '┄' };
-    const double: [2]u21 = .{ '║', '═' };
-
     /// control the direction in which child elements are laid out
     direction: enum(u1) { horizontal, vertical } = .horizontal,
     /// Padding outside of the child elements
@@ -342,13 +327,13 @@ pub const Layout = packed struct {
     } = .{},
 
     pub fn content(this: @This(), comptime C: type, cells: []Cell, origin: Point, size: Point, children: []const C) void {
-        std.debug.assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         if (this.separator.enabled and children.len > 1) {
             const line_cps: [2]u21 = switch (this.separator.line) {
-                .line => line,
+                .line => .{ '│', '─' },
-                .dotted => dotted,
+                .dotted => .{ '┆', '┄' },
-                .double => double,
+                .double => .{ '║', '═' },
             };
             const gap: u16 = (this.gap + 1) / 2;
 
@@ -371,8 +356,11 @@ pub const Layout = packed struct {
                 }
 
                 // DEBUG render corresponding beginning of the separator for this `Container` *red*
-                // cells[anchor].style.fg = .red;
+                if (comptime build_options.debug) {
-                // cells[anchor].style.bg = .red;
+                    cells[anchor].style.fg = .red;
+                    cells[anchor].style.bg = .black;
+                    cells[anchor].cp = 's'; // 's' for *separator*
+                }
             }
         }
     }
@@ -573,7 +561,7 @@ pub fn Container(comptime Event: type) type {
 
     const Element = @import("element.zig").Element(Event);
     return struct {
-        allocator: std.mem.Allocator,
+        allocator: Allocator,
         origin: Point,
         size: Point,
         properties: Properties,
@@ -591,7 +579,7 @@ pub fn Container(comptime Event: type) type {
         };
 
         pub fn init(
-            allocator: std.mem.Allocator,
+            allocator: Allocator,
             properties: Properties,
             element: Element,
         ) !@This() {
@@ -697,13 +685,11 @@ pub fn Container(comptime Event: type) type {
                     .y = @max(size.y, this.properties.size.dim.y),
                 },
             };
-            log.debug("fit_size returning: {any}", .{this.size});
             return this.size;
         }
 
         /// growable implicitly requires the root `Container` to have a set a size property to the size of the available terminal screen
         fn grow_resize(this: *@This(), max_size: Point) void {
-            log.debug("grow_size: {any}", .{this.size});
             const layout = this.properties.layout;
             var remainder = switch (layout.direction) {
                 .horizontal => max_size.x -| (layout.padding.left + layout.padding.right),
@@ -787,6 +773,10 @@ 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,
+                    }
 
                     const size = switch (layout.direction) {
                         .horizontal => child.size.x,
@@ -817,9 +807,11 @@ pub fn Container(comptime Event: type) type {
                         switch (layout.direction) {
                             .horizontal => if (child.properties.size.grow != .vertical) {
                                 child.size.x += size_to_correct;
+                                remainder -|= size_to_correct;
                             },
                             .vertical => if (child.properties.size.grow != .horizontal) {
                                 child.size.y += size_to_correct;
+                                remainder -|= size_to_correct;
                             },
                         }
                         if (overflow > 0) {
@@ -836,7 +828,6 @@ pub fn Container(comptime Event: type) type {
                                 },
                             }
                         }
-                        remainder -|= size_to_correct;
                     }
                 }
             }
@@ -867,7 +858,12 @@ pub fn Container(comptime Event: type) type {
         pub fn handle(this: *@This(), event: Event) !void {
             switch (event) {
                 .mouse => |mouse| if (mouse.in(this.origin, this.size)) {
-                    try this.element.handle(event);
+                    // the element receives the mouse event with relative position
+                    assert(mouse.x >= this.origin.x and mouse.y >= this.origin.y);
+                    var relative_mouse: input.Mouse = mouse;
+                    relative_mouse.x -= this.origin.x;
+                    relative_mouse.y -= this.origin.y;
+                    try this.element.handle(.{ .mouse = relative_mouse });
                     for (this.elements.items) |*element| try element.handle(event);
                 },
                 else => {
@@ -889,19 +885,43 @@ pub fn Container(comptime Event: type) type {
 
             try this.element.content(cells, this.size);
 
-            // DEBUG render corresponding top left corner of this `Container` *red*
+            // DEBUG render corresponding corners (except top left) of this `Container` *red*
-            // cells[0].style.fg = .red;
+            if (comptime build_options.debug) {
-            // cells[0].style.bg = .red;
+                // top right
+                cells[this.size.x -| 1].style.fg = .red;
+                cells[this.size.x -| 1].style.bg = .black;
+                cells[this.size.x -| 1].cp = 'c'; // 'c' for *container*
+                // bottom left
+                cells[this.size.x * (this.size.y -| 1)].style.fg = .red;
+                cells[this.size.x * (this.size.y -| 1)].style.bg = .black;
+                cells[this.size.x * (this.size.y -| 1)].cp = 'c'; // 'c' for *container*
+                // bottom right
+                cells[this.size.x * this.size.y -| 1].style.fg = .red;
+                cells[this.size.x * this.size.y -| 1].style.bg = .black;
+                cells[this.size.x * this.size.y -| 1].cp = 'c'; // 'c' for *container*
+            }
 
             return cells;
         }
     };
 }
 
+const log = std.log.scoped(.container);
+
+const std = @import("std");
+const assert = std.debug.assert;
+const Allocator = std.mem.Allocator;
+const build_options = @import("build_options");
+const input = @import("input.zig");
+const isTaggedUnion = @import("event.zig").isTaggedUnion;
+const Cell = @import("cell.zig");
+const Color = @import("color.zig").Color;
+const Point = @import("point.zig").Point;
+const Style = @import("style.zig");
+const Error = @import("error.zig").Error;
+
 test {
-    _ = Border;
+    @import("std").testing.refAllDeclsRecursive(@This());
-    _ = Layout;
-    _ = Rectangle;
 }
 
 test "Container Fixed and Grow Size Vertical" {

src/element.zig

@@ -1,11 +1,4 @@
 //! Interface for Element's which describe the contents of a `Container`.
-const std = @import("std");
-const input = @import("input.zig");
-
-const Container = @import("container.zig").Container;
-const Cell = @import("cell.zig");
-const Mouse = input.Mouse;
-const Point = @import("point.zig").Point;
 
 pub fn Element(Event: type) type {
     return struct {
@@ -20,13 +13,13 @@ pub fn Element(Event: type) type {
         };
 
         /// Resize the corresponding `Element` with the given *size*.
-        pub fn resize(this: @This(), size: Point) void {
+        pub inline fn resize(this: @This(), size: Point) void {
             if (this.vtable.resize) |resize_fn|
                 resize_fn(this.ptr, size);
         }
 
         /// Reposition the corresponding `Element` with the given *origin*.
-        pub fn reposition(this: @This(), origin: Point) void {
+        pub inline fn reposition(this: @This(), origin: Point) void {
             if (this.vtable.reposition) |reposition_fn|
                 reposition_fn(this.ptr, origin);
         }
@@ -59,25 +52,57 @@ pub fn Element(Event: type) type {
         ///   Otherwise user specific errors should be caught using the `handle`
         ///   function before the rendering of the `Container` happens.
         pub inline fn content(this: @This(), cells: []Cell, size: Point) !void {
-            if (this.vtable.content) |content_fn|
+            if (this.vtable.content) |content_fn| {
                 try content_fn(this.ptr, cells, size);
+
+                // DEBUG render corresponding top left corner of this `Element` *red*
+                // - only rendered if the corresponding associated element renders contents into the `Container`
+                if (comptime build_options.debug) {
+                    cells[0].style.fg = .red;
+                    cells[0].style.bg = .black;
+                    cells[0].cp = 'e'; // 'e' for *element*
+                }
+            }
         }
     };
 }
 
-pub fn Scrollable(Event: type) type {
+pub fn Alignment(Event: type) type {
     return struct {
-        /// `Size` of the actual contents where the anchor and the size is
+        /// `Size` of the actual contents that should be aligned.
-        /// representing the size and location on screen.
         size: Point = .{},
-        /// `Size` of the `Container` content that is scrollable and mapped to
+        /// Alignment Configuration to use for aligning the associated contents of this `Element`.
-        /// the *size* of the `Scrollable` `Element`.
+        configuration: Configuration,
-        container_size: Point = .{},
+        /// `Container` to render in alignment. It needs to use the sizing options accordingly to be effective.
-        /// Anchor of the viewport of the scrollable `Container`.
-        anchor: Point = .{},
-        /// The actual `Container`, that is scrollable.
         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,
@@ -93,9 +118,125 @@ pub fn Scrollable(Event: type) type {
         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
+        /// representing the size and location on screen.
+        size: Point = .{},
+        /// `Size` of the `Container` content that is scrollable and mapped to
+        /// the *size* of the `Scrollable` `Element`.
+        container_size: Point = .{},
+        /// Anchor of the viewport of the scrollable `Container`.
+        anchor: Point = .{},
+        /// The actual `Container`, that is scrollable.
+        container: Container(Event),
+        /// Whether the scrollable contents should show a scroll bar or not.
+        /// The scroll bar will only be shown if required and enabled. With the
+        /// corresponding provided color if to be shown.
+        configuration: Configuration,
+
+        pub const Configuration = packed struct {
+            scrollbar: bool,
+            color: Color = .default,
+            x_axis: bool = false,
+            y_axis: bool = false,
+
+            pub const disabled: @This() = .{ .scrollbar = false };
+
+            pub fn enabled(color: Color) @This() {
+                return .{ .scrollbar = true, .color = color };
+            }
+        };
+
+        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));
+            const last_max_anchor_x = this.container_size.x -| this.size.x;
+            const last_max_anchor_y = this.container_size.y -| this.size.y;
+
+            this.size = size;
+            this.container.resize(size);
+            if (this.configuration.scrollbar) {
+                if (this.container.properties.size.dim.x > this.size.x or this.container.size.x > this.size.x) this.configuration.y_axis = true;
+                if (this.container.properties.size.dim.y > this.size.y or this.container.size.y > this.size.y) this.configuration.x_axis = true;
+
+                if (this.configuration.x_axis or this.configuration.y_axis) this.container.resize(.{
+                    .x = this.size.x - if (this.configuration.x_axis) @as(u16, 1) else @as(u16, 0),
+                    .y = this.size.y - if (this.configuration.y_axis) @as(u16, 1) else @as(u16, 0),
+                });
+            }
+
+            const new_max_anchor_x = this.container.size.x -| size.x;
+            const new_max_anchor_y = this.container.size.y -| size.y;
+
+            // correct anchor if necessary
+            if (new_max_anchor_x < last_max_anchor_x and this.anchor.x > new_max_anchor_x) this.anchor.x = new_max_anchor_x;
+            if (new_max_anchor_y < last_max_anchor_y and this.anchor.y > new_max_anchor_y) this.anchor.y = new_max_anchor_y;
 
-            // TODO scrollbar space - depending on configuration and only if necessary?
-            this.container.resize(this.size);
             this.container_size = this.container.size;
         }
 
@@ -113,8 +254,8 @@ pub fn Scrollable(Event: type) type {
                         this.anchor.y -|= 1;
                     },
                     Mouse.Button.wheel_down => if (this.container_size.y > this.size.y) {
-                        const max_origin_y = this.container_size.y -| this.size.y;
+                        const max_anchor_y = this.container_size.y -| this.size.y;
-                        this.anchor.y = @min(this.anchor.y + 1, max_origin_y);
+                        this.anchor.y = @min(this.anchor.y + 1, max_anchor_y);
                     },
                     Mouse.Button.wheel_left => if (this.container_size.x > this.size.x) {
                         this.anchor.x -|= 1;
@@ -159,33 +300,82 @@ pub fn Scrollable(Event: type) type {
 
         fn content(ctx: *anyopaque, cells: []Cell, size: Point) !void {
             const this: *@This() = @ptrCast(@alignCast(ctx));
-            std.debug.assert(cells.len == @as(usize, this.size.x) * @as(usize, this.size.y));
+            assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+            assert(cells.len == @as(usize, this.size.x) * @as(usize, this.size.y));
+            const offset_x: usize = if (this.configuration.x_axis) 1 else 0;
+            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);
-                std.debug.assert(container_cells_const.len == @as(usize, container_size.x) * @as(usize, container_size.y));
+                assert(container_cells_const.len == @as(usize, container_size.x) * @as(usize, container_size.y));
                 @memcpy(container_cells, container_cells_const);
             }
 
             for (this.container.elements.items) |child| try render_container(child, container_cells, container_size);
 
             const anchor = (@as(usize, this.anchor.y) * @as(usize, container_size.x)) + @as(usize, this.anchor.x);
-            // TODO render scrollbar according to configuration!
+            for (0..size.y - offset_y) |row| {
-            for (0..size.y) |row| {
+                for (0..size.x - offset_x) |col| {
-                for (0..size.x) |col| {
                     cells[(row * size.x) + col] = container_cells[anchor + (row * container_size.x) + col];
                 }
             }
+            if (this.configuration.scrollbar) {
+                if (this.configuration.x_axis) {
+                    const ratio: f32 = @as(f32, @floatFromInt(this.size.y)) / @as(f32, @floatFromInt(this.container.size.y));
+                    const scrollbar_size: usize = @intFromFloat(@as(f32, @floatFromInt(this.size.y)) * ratio);
+                    const pos_ratio: f32 = @as(f32, @floatFromInt(this.anchor.y)) / @as(f32, @floatFromInt(this.container.size.y));
+                    const scrollbar_starting_pos: usize = @intFromFloat(@as(f32, @floatFromInt(this.size.y)) * pos_ratio);
+                    for (0..size.y) |row| {
+                        cells[(row * size.x) + size.x - 1] = .{
+                            .style = .{
+                                .fg = this.configuration.color,
+                                .emphasis = if (row >= scrollbar_starting_pos and row <= scrollbar_starting_pos + scrollbar_size)
+                                    &.{} // scrollbar itself
+                                else
+                                    &.{.dim}, // background (around scrollbar)
+                            },
+                            .cp = '🮋', // 7/8 block right
+                        };
+                    }
+                }
+                if (this.configuration.y_axis) {
+                    const ratio: f32 = @as(f32, @floatFromInt(this.size.x)) / @as(f32, @floatFromInt(this.container.size.x));
+                    const scrollbar_size: usize = @intFromFloat(@as(f32, @floatFromInt(this.size.x)) * ratio);
+                    const pos_ratio: f32 = @as(f32, @floatFromInt(this.anchor.x)) / @as(f32, @floatFromInt(this.container.size.x));
+                    const scrollbar_starting_pos: usize = @intFromFloat(@as(f32, @floatFromInt(this.size.x)) * pos_ratio);
+                    for (0..size.x) |col| {
+                        cells[((size.y - 1) * size.x) + col] = .{
+                            .style = .{
+                                .fg = this.configuration.color,
+                                .emphasis = if (col >= scrollbar_starting_pos and col <= scrollbar_starting_pos + scrollbar_size)
+                                    &.{} // scrollbar itself
+                                else
+                                    &.{.dim}, // background (around scrollbar)
+                            },
+                            .cp = '🮄', // 5/8 block top (to make it look more equivalent to the vertical scrollbar)
+                        };
+                    }
+                }
+            }
             this.container.allocator.free(container_cells);
         }
     };
 }
 
+const std = @import("std");
+const assert = std.debug.assert;
+const build_options = @import("build_options");
+const input = @import("input.zig");
+const Container = @import("container.zig").Container;
+const Cell = @import("cell.zig");
+const Color = @import("color.zig").Color;
+const Mouse = input.Mouse;
+const Point = @import("point.zig").Point;
+
 // TODO nested scrollable `Container`s?'
-// TODO reaction only for when the event is actually pushed to the corresponding `Container` rendered container
 
 test "scrollable vertical" {
     const event = @import("event.zig");
@@ -222,7 +412,7 @@ test "scrollable vertical" {
     }, .{}));
     defer box.deinit();
 
-    var scrollable: Scrollable(event.SystemEvent) = .{ .container = box };
+    var scrollable: Scrollable(event.SystemEvent) = .init(box, .disabled);
 
     var container: Container(event.SystemEvent) = try .init(allocator, .{
         .border = .{
@@ -265,6 +455,84 @@ test "scrollable vertical" {
     try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.vertical.bottom.zon"), renderer.screen);
 }
 
+test "scrollable vertical with scrollbar" {
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    const allocator = std.testing.allocator;
+    const size: Point = .{
+        .x = 30,
+        .y = 20,
+    };
+
+    var box: Container(event.SystemEvent) = try .init(allocator, .{
+        .border = .{
+            .sides = .all,
+            .color = .red,
+        },
+        .layout = .{
+            .separator = .{
+                .enabled = true,
+                .color = .red,
+            },
+            .direction = .vertical,
+            .padding = .all(1),
+        },
+        .size = .{
+            .dim = .{ .y = size.y + 15 },
+        },
+    }, .{});
+    try box.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+    }, .{}));
+    try box.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+    }, .{}));
+    defer box.deinit();
+
+    var scrollable: Scrollable(event.SystemEvent) = .init(box, .enabled(.white));
+
+    var container: Container(event.SystemEvent) = try .init(allocator, .{
+        .border = .{
+            .color = .green,
+            .sides = .vertical,
+        },
+    }, scrollable.element());
+    defer container.deinit();
+
+    var renderer: testing.Renderer = .init(allocator, size);
+    defer renderer.deinit();
+
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(event.SystemEvent), &container);
+    try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.vertical.scrollbar.top.zon"), renderer.screen);
+
+    // scroll down 15 times (exactly to the end)
+    for (0..15) |_| try container.handle(.{
+        .mouse = .{
+            .button = .wheel_down,
+            .kind = .press,
+            .x = 5,
+            .y = 5,
+        },
+    });
+    try renderer.render(Container(event.SystemEvent), &container);
+    try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.vertical.scrollbar.bottom.zon"), renderer.screen);
+
+    // further scrolling down will not change anything
+    try container.handle(.{
+        .mouse = .{
+            .button = .wheel_down,
+            .kind = .press,
+            .x = 5,
+            .y = 5,
+        },
+    });
+    try renderer.render(Container(event.SystemEvent), &container);
+    try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.vertical.scrollbar.bottom.zon"), renderer.screen);
+}
+
 test "scrollable horizontal" {
     const event = @import("event.zig");
     const testing = @import("testing.zig");
@@ -300,7 +568,7 @@ test "scrollable horizontal" {
     }, .{}));
     defer box.deinit();
 
-    var scrollable: Scrollable(event.SystemEvent) = .{ .container = box };
+    var scrollable: Scrollable(event.SystemEvent) = .init(box, .disabled);
 
     var container: Container(event.SystemEvent) = try .init(allocator, .{
         .border = .{
@@ -342,3 +610,213 @@ test "scrollable horizontal" {
     try renderer.render(Container(event.SystemEvent), &container);
     try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.horizontal.right.zon"), renderer.screen);
 }
+
+test "scrollable horizontal with scrollbar" {
+    const event = @import("event.zig");
+    const testing = @import("testing.zig");
+
+    const allocator = std.testing.allocator;
+    const size: Point = .{
+        .x = 30,
+        .y = 20,
+    };
+
+    var box: Container(event.SystemEvent) = try .init(allocator, .{
+        .border = .{
+            .sides = .all,
+            .color = .red,
+        },
+        .layout = .{
+            .separator = .{
+                .enabled = true,
+                .color = .red,
+            },
+            .direction = .horizontal,
+            .padding = .all(1),
+        },
+        .size = .{
+            .dim = .{ .x = size.x + 15 },
+        },
+    }, .{});
+    try box.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+    }, .{}));
+    try box.append(try .init(allocator, .{
+        .rectangle = .{ .fill = .grey },
+    }, .{}));
+    defer box.deinit();
+
+    var scrollable: Scrollable(event.SystemEvent) = .init(box, .enabled(.white));
+
+    var container: Container(event.SystemEvent) = try .init(allocator, .{
+        .border = .{
+            .color = .green,
+            .sides = .horizontal,
+        },
+    }, scrollable.element());
+    defer container.deinit();
+
+    var renderer: testing.Renderer = .init(allocator, size);
+    defer renderer.deinit();
+
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(event.SystemEvent), &container);
+    try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.horizontal.scrollbar.left.zon"), renderer.screen);
+
+    // scroll right 15 times (exactly to the end)
+    for (0..15) |_| try container.handle(.{
+        .mouse = .{
+            .button = .wheel_right,
+            .kind = .press,
+            .x = 5,
+            .y = 5,
+        },
+    });
+    try renderer.render(Container(event.SystemEvent), &container);
+    try testing.expectEqualCells(.{}, renderer.size, @import("test/element/scrollable.horizontal.scrollbar.right.zon"), renderer.screen);
+
+    // further scrolling right will not change anything
+    try container.handle(.{
+        .mouse = .{
+            .button = .wheel_right,
+            .kind = .press,
+            .x = 5,
+            .y = 5,
+        },
+    });
+    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"));
+}

src/event.zig

@@ -1,12 +1,5 @@
 //! Events which are defined by the library. They might be extended by user
 //! events. See `App` for more details about user defined events.
-const std = @import("std");
-const input = @import("input.zig");
-const terminal = @import("terminal.zig");
-
-const Key = input.Key;
-const Mouse = input.Mouse;
-const Point = @import("point.zig").Point;
 
 /// System events available to every `zterm.App`
 pub const SystemEvent = union(enum) {
@@ -15,8 +8,11 @@ pub const SystemEvent = union(enum) {
     init,
     /// Quit event to signify the end of the event loop (rendering should stop afterwards)
     quit,
+    /// Resize event to signify that the application should re-draw to resize
+    resize,
     /// Error event to notify other containers about a recoverable error
     err: struct {
+        /// actual error
         err: anyerror,
         /// associated error message
         msg: []const u8,
@@ -92,3 +88,10 @@ pub fn isTaggedUnion(comptime E: type) bool {
     }
     return true;
 }
+
+const std = @import("std");
+const input = @import("input.zig");
+const terminal = @import("terminal.zig");
+const Key = input.Key;
+const Mouse = input.Mouse;
+const Point = @import("point.zig").Point;

src/input.zig

@@ -1,7 +1,4 @@
 //! Input module for `zterm`. Contains structs to represent key events and mouse events.
-const std = @import("std");
-
-const Point = @import("point.zig").Point;
 
 pub const Mouse = packed struct {
     x: u16,
@@ -32,7 +29,7 @@ pub const Mouse = packed struct {
     };
 
     pub fn eql(this: @This(), other: @This()) bool {
-        return std.meta.eql(this, other);
+        return meta.eql(this, other);
     }
 
     pub fn in(this: @This(), origin: Point, size: Point) bool {
@@ -65,9 +62,11 @@ pub const Key = packed struct {
     /// }
     /// ```
     pub fn eql(this: @This(), other: @This()) bool {
-        return std.meta.eql(this, other);
+        return meta.eql(this, other);
     }
 
+    // TODO might be useful to use the std.ascii stuff!
+
     /// Determine if the `Key` is an ascii character that can be printed to
     /// the screen. This means that the code point of the `Key` is an ascii
     /// character between 32 - 255 (with the exception of 127 = Delete) and no
@@ -90,24 +89,25 @@ pub const Key = packed struct {
     }
 
     test "isAscii with ascii character" {
-        try std.testing.expectEqual(true, isAscii(.{ .cp = 'c' }));
+        try testing.expectEqual(true, isAscii(.{ .cp = 'c' }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .ctrl = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .ctrl = true } }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true } }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true, .ctrl = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true, .ctrl = true } }));
     }
 
     test "isAscii with non-ascii character" {
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Escape }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Escape }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Enter }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Enter }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Enter, .mod = .{ .alt = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Enter, .mod = .{ .alt = true } }));
     }
 
     test "isAscii with excluded input.Delete" {
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Delete }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Delete }));
-        try std.testing.expectEqual(false, isAscii(.{ .cp = Delete, .mod = .{ .alt = false, .ctrl = false } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Delete, .mod = .{ .alt = false, .ctrl = false } }));
     }
 };
 
+// TODO: std.ascii has the escape codes too!
 // codepoints for keys
 pub const Tab: u21 = 0x09;
 pub const Enter: u21 = 0x0D;
@@ -152,21 +152,6 @@ pub const F17: u21 = 57380;
 pub const F18: u21 = 57381;
 pub const F19: u21 = 57382;
 pub const F20: u21 = 57383;
-pub const F21: u21 = 57384;
-pub const F22: u21 = 57385;
-pub const F23: u21 = 57386;
-pub const F24: u21 = 57387;
-pub const F25: u21 = 57388;
-pub const F26: u21 = 57389;
-pub const F27: u21 = 57390;
-pub const F28: u21 = 57391;
-pub const F29: u21 = 57392;
-pub const F30: u21 = 57393;
-pub const F31: u21 = 57394;
-pub const F32: u21 = 57395;
-pub const F33: u21 = 57396;
-pub const F34: u21 = 57397;
-pub const F35: u21 = 57398;
 pub const Kp0: u21 = 57399;
 pub const Kp1: u21 = 57400;
 pub const Kp2: u21 = 57401;
@@ -223,3 +208,8 @@ pub const RightHyper: u21 = 57451;
 pub const RightMeta: u21 = 57452;
 pub const IsoLevel3Shift: u21 = 57453;
 pub const IsoLevel5Shift: u21 = 57454;
+
+const std = @import("std");
+const meta = std.meta;
+const Point = @import("point.zig").Point;
+const testing = std.testing;

src/queue.zig

@@ -1,9 +1,7 @@
 // taken from https://github.com/rockorager/libvaxis/blob/main/src/queue.zig (MIT-License)
 // with slight modifications
-const std = @import("std");
-const assert = std.debug.assert;
 
-/// Thread safe. Fixed size. Blocking push and pop.
+/// Queue implementation. Thread safe. Fixed size. Blocking push and pop. Polling through tryPop and tryPush.
 pub fn Queue(comptime T: type, comptime size: usize) type {
     return struct {
         buf: [size]T = undefined,
@@ -92,6 +90,23 @@ pub fn Queue(comptime T: type, comptime size: usize) type {
             assert(!this.isEmptyLH());
         }
 
+        pub fn lock(this: *QueueType) void {
+            this.mutex.lock();
+        }
+
+        pub fn unlock(this: *QueueType) void {
+            this.mutex.unlock();
+        }
+
+        /// Used to efficiently drain the queue
+        pub fn drain(this: *QueueType) ?T {
+            if (this.isEmptyLH()) return null;
+
+            const result = this.buf[this.mask(this.read_index)];
+            this.read_index = this.mask2(this.read_index + 1);
+            return result;
+        }
+
         fn isEmptyLH(this: QueueType) bool {
             return this.write_index == this.read_index;
         }
@@ -116,7 +131,7 @@ pub fn Queue(comptime T: type, comptime size: usize) type {
         }
 
         /// Returns the length
-        fn len(this: QueueType) usize {
+        pub fn len(this: QueueType) usize {
             const wrap_offset = 2 * this.buf.len *
                 @intFromBool(this.write_index < this.read_index);
             const adjusted_write_index = this.write_index + wrap_offset;
@@ -135,8 +150,12 @@ pub fn Queue(comptime T: type, comptime size: usize) type {
     };
 }
 
+const std = @import("std");
 const testing = std.testing;
+const assert = std.debug.assert;
+const Thread = std.Thread;
 const cfg = Thread.SpawnConfig{ .allocator = testing.allocator };
+
 test "Queue: simple push / pop" {
     var queue: Queue(u8, 16) = .{};
     queue.push(1);
@@ -146,7 +165,6 @@ test "Queue: simple push / pop" {
     try testing.expectEqual(2, queue.pop());
 }
 
-const Thread = std.Thread;
 fn testPushPop(q: *Queue(u8, 2)) !void {
     q.push(3);
     try testing.expectEqual(2, q.pop());
@@ -199,7 +217,7 @@ fn sleepyPop(q: *Queue(u8, 2)) !void {
     try Thread.yield();
     std.time.sleep(std.time.ns_per_s);
     // Finally, let that other thread go.
-    try std.testing.expectEqual(1, q.pop());
+    try testing.expectEqual(1, q.pop());
 
     // This won't continue until the other thread has had a chance to
     // put at least one item in the queue.
@@ -218,7 +236,7 @@ fn sleepyPop(q: *Queue(u8, 2)) !void {
     std.time.sleep(std.time.ns_per_s / 2);
 
     // Pop that thing and we're done.
-    try std.testing.expectEqual(2, q.pop());
+    try testing.expectEqual(2, q.pop());
 }
 
 test "Fill, block, fill, block" {
@@ -238,15 +256,15 @@ test "Fill, block, fill, block" {
 
     // Just to make sure the sleeps are yielding to this thread, make
     // sure it took at least 900ms to do the push.
-    try std.testing.expect(then - now > 900);
+    try testing.expect(then - now > 900);
 
     // This should block again, waiting for the other thread.
     queue.push(4);
 
     // And once that push has gone through, the other thread's done.
     thread.join();
-    try std.testing.expectEqual(3, queue.pop());
+    try testing.expectEqual(3, queue.pop());
-    try std.testing.expectEqual(4, queue.pop());
+    try testing.expectEqual(4, queue.pop());
 }
 
 fn sleepyPush(q: *Queue(u8, 1)) !void {
@@ -284,8 +302,8 @@ test "Drain, block, drain, block" {
 
     var queue: Queue(u8, 1) = .{};
     const thread = try Thread.spawn(cfg, sleepyPush, .{&queue});
-    try std.testing.expectEqual(1, queue.pop());
+    try testing.expectEqual(1, queue.pop());
-    try std.testing.expectEqual(2, queue.pop());
+    try testing.expectEqual(2, queue.pop());
     thread.join();
 }
 

src/render.zig

@@ -1,18 +1,14 @@
-const std = @import("std");
+//! Renderer for `zterm`.
-const terminal = @import("terminal.zig");
-
-const Cell = @import("cell.zig");
-const Point = @import("point.zig").Point;
 
 /// Double-buffered intermediate rendering pipeline
 pub const Buffered = struct {
-    allocator: std.mem.Allocator,
+    allocator: Allocator,
     created: bool,
     size: Point,
     screen: []Cell,
     virtual_screen: []Cell,
 
-    pub fn init(allocator: std.mem.Allocator) @This() {
+    pub fn init(allocator: Allocator) @This() {
         return .{
             .allocator = allocator,
             .created = false,
@@ -29,9 +25,9 @@ pub const Buffered = struct {
         }
     }
 
-    pub fn resize(this: *@This()) !void {
+    pub fn resize(this: *@This()) !Point {
         const size = terminal.getTerminalSize();
-        if (std.meta.eql(this.size, size)) return;
+        if (meta.eql(this.size, size)) return this.size;
 
         this.size = size;
         const n = @as(usize, this.size.x) * @as(usize, this.size.y);
@@ -52,6 +48,7 @@ pub const Buffered = struct {
             @memset(this.virtual_screen, .{});
         }
         try this.clear();
+        return size;
     }
 
     /// Clear the entire screen and reset the screen buffer, to force a re-draw with the next `flush` call.
@@ -88,7 +85,9 @@ pub const Buffered = struct {
 
     /// Write *virtual screen* to alternate screen (should be called once and last during each render loop iteration in the main loop).
     pub fn flush(this: *@This()) !void {
+        try terminal.hideCursor();
         // TODO measure timings of rendered frames?
+        var cursor_position: ?Point = null;
         const writer = terminal.writer();
         const s = this.screen;
         const vs = this.virtual_screen;
@@ -97,14 +96,36 @@ pub const Buffered = struct {
                 const idx = (row * this.size.x) + col;
                 const cs = s[idx];
                 const cvs = vs[idx];
+
+                // update the latest found cursor position
+                if (cvs.style.cursor) {
+                    assert(cursor_position == null);
+                    cursor_position = .{
+                        .x = @truncate(col),
+                        .y = @truncate(row),
+                    };
+                }
+
                 if (cs.eql(cvs)) continue;
 
                 // render differences found in virtual screen
-                try terminal.setCursorPosition(.{ .y = @truncate(row + 1), .x = @truncate(col + 1) });
+                try terminal.setCursorPosition(.{ .y = @truncate(row), .x = @truncate(col) });
                 try cvs.value(writer);
                 // update screen to be the virtual screen for the next frame
                 s[idx] = vs[idx];
             }
         }
+        if (cursor_position) |point| {
+            try terminal.showCursor();
+            try terminal.setCursorPosition(point);
+        }
     }
 };
+
+const std = @import("std");
+const meta = std.meta;
+const assert = std.debug.assert;
+const Allocator = std.mem.Allocator;
+const terminal = @import("terminal.zig");
+const Cell = @import("cell.zig");
+const Point = @import("point.zig").Point;

src/root.zig

@@ -17,7 +17,6 @@ pub const Renderer = @import("render.zig");
 // Container Configurations
 pub const Border = container.Border;
 pub const Rectangle = container.Rectangle;
-pub const Scroll = container.Scroll;
 pub const Layout = container.Layout;
 
 pub const Cell = @import("cell.zig");

src/style.zig

@@ -7,11 +7,13 @@
 
 // taken from https://github.com/rockorager/libvaxis/blob/main/src/Cell.zig (MIT-License)
 // with slight modifications
-const std = @import("std");
 
-const Color = @import("color.zig").Color;
+fg: Color = .default,
-
+bg: Color = .default,
-pub const Style = @This();
+ul: Color = .default,
+cursor: bool = false,
+ul_style: Underline = .off,
+emphasis: []const Emphasis,
 
 pub const Underline = enum {
     off,
@@ -34,39 +36,43 @@ pub const Emphasis = enum(u8) {
     strikethrough,
 };
 
-fg: Color = .default,
-bg: Color = .default,
-ul: Color = .default,
-ul_style: Underline = .off,
-emphasis: []const Emphasis,
-
 pub fn eql(this: Style, other: Style) bool {
-    return std.meta.eql(this, other);
+    return meta.eql(this, other);
 }
 
+// TODO might be useful to use the std.ascii stuff!
+
 pub fn value(this: Style, writer: anytype, cp: u21) !void {
     var buffer: [4]u8 = undefined;
-    const bytes = try std.unicode.utf8Encode(cp, &buffer);
+    const bytes = try unicode.utf8Encode(cp, &buffer);
-    std.debug.assert(bytes > 0);
+    assert(bytes > 0);
     // build ansi sequence for 256 colors ...
     // foreground
-    try std.fmt.format(writer, "\x1b[", .{});
+    try format(writer, "\x1b[", .{});
     try this.fg.write(writer, .fg);
     // background
-    try std.fmt.format(writer, ";", .{});
+    try format(writer, ";", .{});
     try this.bg.write(writer, .bg);
     // underline
     // FIX assert that if the underline property is set that the ul style and the attribute for underlining is available
-    try std.fmt.format(writer, ";", .{});
+    try format(writer, ";", .{});
     try this.ul.write(writer, .ul);
     // append styles (aka attributes like bold, italic, strikethrough, etc.)
-    for (this.emphasis) |attribute| try std.fmt.format(writer, ";{d}", .{@intFromEnum(attribute)});
+    for (this.emphasis) |attribute| try format(writer, ";{d}", .{@intFromEnum(attribute)});
-    try std.fmt.format(writer, "m", .{});
+    try format(writer, "m", .{});
     // content
-    try std.fmt.format(writer, "{s}", .{buffer[0..bytes]});
+    try format(writer, "{s}", .{buffer[0..bytes]});
-    try std.fmt.format(writer, "\x1b[0m", .{});
+    try format(writer, "\x1b[0m", .{});
 }
 
 // TODO implement helper functions for terminal capabilities:
 // - links / url display (osc 8)
 // - show / hide cursor?
+
+const std = @import("std");
+const unicode = std.unicode;
+const meta = std.meta;
+const assert = std.debug.assert;
+const format = std.fmt.format;
+const Color = @import("color.zig").Color;
+const Style = @This();

src/terminal.zig

@@ -1,15 +1,3 @@
-const std = @import("std");
-const code_point = @import("code_point");
-const ctlseqs = @import("ctlseqs.zig");
-const input = @import("input.zig");
-
-const Key = input.Key;
-const Point = @import("point.zig").Point;
-const Size = @import("point.zig").Point;
-const Cell = @import("cell.zig");
-
-const log = std.log.scoped(.terminal);
-
 // Ref: https://vt100.net/docs/vt510-rm/DECRPM.html
 pub const ReportMode = enum {
     not_recognized,
@@ -21,62 +9,62 @@ pub const ReportMode = enum {
 
 /// Gets number of rows and columns in the terminal
 pub fn getTerminalSize() Size {
-    var ws: std.posix.winsize = undefined;
+    var ws: posix.winsize = undefined;
-    _ = std.posix.system.ioctl(std.posix.STDIN_FILENO, std.posix.T.IOCGWINSZ, @intFromPtr(&ws));
+    _ = posix.system.ioctl(posix.STDIN_FILENO, posix.T.IOCGWINSZ, @intFromPtr(&ws));
     return .{ .x = ws.col, .y = ws.row };
 }
 
 pub fn saveScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.save_screen);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.save_screen);
 }
 
 pub fn restoreScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.restore_screen);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.restore_screen);
 }
 
 pub fn enterAltScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.smcup);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.smcup);
 }
 
 pub fn exitAltScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.rmcup);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.rmcup);
 }
 
 pub fn clearScreen() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.clear_screen);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.clear_screen);
 }
 
 pub fn hideCursor() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.hide_cursor);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.hide_cursor);
 }
 
 pub fn showCursor() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.show_cursor);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.show_cursor);
 }
 
 pub fn setCursorPositionHome() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.home);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.home);
 }
 
 pub fn enableMouseSupport() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.mouse_set);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.mouse_set);
 }
 
 pub fn disableMouseSupport() !void {
-    _ = try std.posix.write(std.posix.STDIN_FILENO, ctlseqs.mouse_reset);
+    _ = try posix.write(posix.STDIN_FILENO, ctlseqs.mouse_reset);
 }
 
 pub fn read(buf: []u8) !usize {
-    return try std.posix.read(std.posix.STDIN_FILENO, buf);
+    return try posix.read(posix.STDIN_FILENO, buf);
 }
 
 pub fn write(buf: []const u8) !usize {
-    return try std.posix.write(std.posix.STDIN_FILENO, buf);
+    return try posix.write(posix.STDIN_FILENO, buf);
 }
 
 fn contextWrite(context: @This(), data: []const u8) anyerror!usize {
     _ = context;
-    return try std.posix.write(std.posix.STDOUT_FILENO, data);
+    return try posix.write(posix.STDOUT_FILENO, data);
 }
 
 const Writer = std.io.Writer(
@@ -91,19 +79,19 @@ pub fn writer() Writer {
 
 pub fn setCursorPosition(pos: Point) !void {
     var buf: [64]u8 = undefined;
-    const value = try std.fmt.bufPrint(&buf, "\x1b[{d};{d}H", .{ pos.y, pos.x });
+    const value = try std.fmt.bufPrint(&buf, "\x1b[{d};{d}H", .{ pos.y + 1, pos.x + 1 });
-    _ = try std.posix.write(std.posix.STDIN_FILENO, value);
+    _ = try posix.write(posix.STDIN_FILENO, value);
 }
 
 pub fn getCursorPosition() !Size.Position {
     // Needs Raw mode (no wait for \n) to work properly cause
     // control sequence will not be written without it.
-    _ = try std.posix.write(std.posix.STDIN_FILENO, "\x1b[6n");
+    _ = try posix.write(posix.STDIN_FILENO, "\x1b[6n");
 
     var buf: [64]u8 = undefined;
 
     // format: \x1b, "[", R1,..., Rn, ";", C1, ..., Cn, "R"
-    const len = try std.posix.read(std.posix.STDIN_FILENO, &buf);
+    const len = try posix.read(posix.STDIN_FILENO, &buf);
 
     if (!isCursorPosition(buf[0..len])) {
         return error.InvalidValueReturned;
@@ -166,8 +154,8 @@ pub fn isCursorPosition(buf: []u8) bool {
 ///
 /// `bak`: pointer to store termios struct backup before
 /// altering, this is used to disable raw mode.
-pub fn enableRawMode(bak: *std.posix.termios) !void {
+pub fn enableRawMode(bak: *posix.termios) !void {
-    var termios = try std.posix.tcgetattr(std.posix.STDIN_FILENO);
+    var termios = try posix.tcgetattr(posix.STDIN_FILENO);
     bak.* = termios;
 
     // termios flags used by termios(3)
@@ -192,20 +180,20 @@ pub fn enableRawMode(bak: *std.posix.termios) !void {
     termios.cflag.CSIZE = .CS8;
     termios.cflag.PARENB = false;
 
-    termios.cc[@intFromEnum(std.posix.V.MIN)] = 1;
+    termios.cc[@intFromEnum(posix.V.MIN)] = 1;
-    termios.cc[@intFromEnum(std.posix.V.TIME)] = 0;
+    termios.cc[@intFromEnum(posix.V.TIME)] = 0;
 
-    try std.posix.tcsetattr(
+    try posix.tcsetattr(
-        std.posix.STDIN_FILENO,
+        posix.STDIN_FILENO,
         .FLUSH,
         termios,
     );
 }
 
 /// Reverts `enableRawMode` to restore initial functionality.
-pub fn disableRawMode(bak: *std.posix.termios) !void {
+pub fn disableRawMode(bak: *posix.termios) !void {
-    try std.posix.tcsetattr(
+    try posix.tcsetattr(
-        std.posix.STDIN_FILENO,
+        posix.STDIN_FILENO,
         .FLUSH,
         bak.*,
     );
@@ -215,13 +203,13 @@ pub fn disableRawMode(bak: *std.posix.termios) !void {
 pub fn canSynchornizeOutput() !bool {
     // Needs Raw mode (no wait for \n) to work properly cause
     // control sequence will not be written without it.
-    _ = try std.posix.write(std.posix.STDIN_FILENO, "\x1b[?2026$p");
+    _ = try posix.write(posix.STDIN_FILENO, "\x1b[?2026$p");
 
     var buf: [64]u8 = undefined;
 
     // format: \x1b, "[", "?", "2", "0", "2", "6", ";", n, "$", "y"
-    const len = try std.posix.read(std.posix.STDIN_FILENO, &buf);
+    const len = try posix.read(posix.STDIN_FILENO, &buf);
-    if (!std.mem.eql(u8, buf[0..len], "\x1b[?2026;") or len < 9) {
+    if (!mem.eql(u8, buf[0..len], "\x1b[?2026;") or len < 9) {
         return false;
     }
 
@@ -238,3 +226,16 @@ fn getReportMode(ps: u8) ReportMode {
         else => ReportMode.not_recognized,
     };
 }
+
+const log = std.log.scoped(.terminal);
+
+const std = @import("std");
+const mem = std.mem;
+const posix = std.posix;
+const code_point = @import("code_point");
+const ctlseqs = @import("ctlseqs.zig");
+const input = @import("input.zig");
+const Key = input.Key;
+const Point = @import("point.zig").Point;
+const Size = @import("point.zig").Point;
+const Cell = @import("cell.zig");

src/testing.zig

@@ -1,23 +1,12 @@
 //! Testing namespace for `zterm` to provide testing capabilities for `Containers`, `Event` handling, `App`s and `Element` implementations.
-const std = @import("std");
-const event = @import("event.zig");
-const Container = @import("container.zig").Container;
-
-const Cell = @import("cell.zig");
-const DisplayWidth = @import("DisplayWidth");
-const Point = @import("point.zig").Point;
-
-// TODO how would I describe the expected screens?
-// - including styling?
-// - compare generated strings instead? -> how would this be generated for the user?
 
 /// Single-buffer test rendering pipeline for testing purposes.
 pub const Renderer = struct {
-    allocator: std.mem.Allocator,
+    allocator: Allocator,
     size: Point,
     screen: []Cell,
 
-    pub fn init(allocator: std.mem.Allocator, size: Point) @This() {
+    pub fn init(allocator: Allocator, size: Point) @This() {
         const screen = allocator.alloc(Cell, @as(usize, size.x) * @as(usize, size.y)) catch @panic("testing.zig: Out of memory.");
         @memset(screen, .{});
 
@@ -116,11 +105,10 @@ pub const Renderer = struct {
 /// }, &container, @import("test/container/border.all.zon"));
 /// ```
 pub fn expectContainerScreen(size: Point, container: *Container(event.SystemEvent), expected: []const Cell) !void {
-    const allocator = std.testing.allocator;
+    const allocator = testing.allocator;
     var renderer: Renderer = .init(allocator, size);
     defer renderer.deinit();
 
-    try renderer.resize(size);
     container.resize(size);
     container.reposition(.{});
     try renderer.render(Container(event.SystemEvent), container);
@@ -133,10 +121,10 @@ pub fn expectContainerScreen(size: Point, container: *Container(event.SystemEven
 /// the contents of a given screen from the `zterm.testing.Renderer`. See
 /// `zterm.testing.expectContainerScreen` for an example usage.
 pub fn expectEqualCells(origin: Point, size: Point, expected: []const Cell, actual: []const Cell) !void {
-    const allocator = std.testing.allocator;
+    const allocator = testing.allocator;
 
-    try std.testing.expectEqual(expected.len, actual.len);
+    try testing.expectEqual(expected.len, actual.len);
-    try std.testing.expectEqual(expected.len, @as(usize, size.y) * @as(usize, size.x));
+    try testing.expectEqual(expected.len, @as(usize, size.y) * @as(usize, size.x));
 
     var expected_cps = try std.ArrayList(Cell).initCapacity(allocator, size.x);
     defer expected_cps.deinit();
@@ -192,10 +180,20 @@ pub fn expectEqualCells(origin: Point, size: Point, expected: []const Cell, actu
     // test failed
     try buffer.flush();
 
-    std.debug.lockStdErr();
+    debug.lockStdErr();
-    defer std.debug.unlockStdErr();
+    defer debug.unlockStdErr();
 
     const std_writer = std.io.getStdErr().writer();
     try std_writer.writeAll(output.items);
     return error.TestExpectEqualCells;
 }
+
+const std = @import("std");
+const debug = std.debug;
+const testing = std.testing;
+const Allocator = std.mem.Allocator;
+const event = @import("event.zig");
+const Container = @import("container.zig").Container;
+const Cell = @import("cell.zig");
+const DisplayWidth = @import("DisplayWidth");
+const Point = @import("point.zig").Point;