WIP: exec element with initial implementation

Problem is that the main application actually does not create a pty and
instead uses the current one (for better compatability for ssh based
hosting).

The current problem is the fact that the child process should not
take over (and never give back too) the input / output handling of the
current pts. Such that both applications can receive inputs accordingly
(in best case actually controlled by the main application).

.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,11 +14,11 @@ 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
-        run: zig fmt --check .
+        run: zig fmt --check --exclude src/test .
       - name: Spell checking
         uses: crate-ci/typos@v1.25.0
         with:

README.md

@@ -1,19 +1,19 @@
-# zterm Terminal User Interface Library
+# zterm TUI Library
 
-`zterm` is a terminal user interface library to implement terminal (fullscreen or inline) applications.
+`zterm` is a terminal user interface library (*tui*) to implement terminal (fullscreen or inline) applications.
 
-> [!NOTE]
-> Only builds using the master version are tested to work.
+> [!CAUTION]
+> Only builds using the zig master version are tested to work.
 
 ## Demo
 
 Clone this repository and run `zig build --help` to see the available examples. Run a given example as follows:
 
 ```sh
-zig build --release=safe -Dexample=input run
+zig build --release=safe -Dexample=demo run
 ```
 
-> [!NOTE]
+> [!TIP]
 > Every example application can be quit using `ctrl+c`.
 
 See the [wiki](https://gitea.yves-biener.de/yves-biener/zterm/wiki) for a showcase of the examples and the further details.
@@ -26,7 +26,7 @@ To add or update `zterm` as a dependency in your project run the following comma
 zig fetch --save git+https://gitea.yves-biener.de/yves-biener/zterm
 ```
 
-Add the dependency to your module as follows in your _build.zig_:
+Add the dependency to your module as follows in your *build.zig*:
 
 ```zig
 const zterm: *Dependency = b.dependency("zterm", .{
@@ -37,181 +37,6 @@ const zterm: *Dependency = b.dependency("zterm", .{
 exe.root_module.addImport("zterm", zterm.module("zterm"));
 ```
 
----
-## Design Goals
-
-This project draws heavy inspiration from
-[clay](https://github.com/nicbarker/clay) in the way the layout is declared by
-the user. As terminal applications usually are rendered in intermediate mode,
-the rendering is also part of the event loop. Such that every time an event
-happens a render call will usually be done as well. However this is not strickly
-necessary and can be separated to have a fixed rendering of every 16ms (i.e. for
-60 fps), etc.
-
-There is only one generic container which contains properties and elements (or
-children) which can also be containers, such that each layout in the end is
-a tree.
-
-The library is designed to be very basic and not to provide any more complex
-elements such as input fields, drop-down menu's, buttons, etc. Some of them are
-either easy to implement yourself, specific for you needs or a too complex to
-be provided by the library effectively. For these use-cases there may be other
-libraries that build on top of this one to provide the complex elements as some
-sort of pre-built elements for you to use in your application (or you create
-them yourself).
-
-There are only very few system events, that are used by the built-in containers
-and properties accordingly. For you own widgets (i.e. a collection of elements)
-you can extend the events to include your own events to communicate between
-elements, effect the control flow and the corresponding generated layouts and
-much more.
-
-As this is a terminal based layout library it also provides a rendering pipeline
-alongside the event loop implementation. Usually the event loop is waiting
-blocking and will only cause a re-draw (**intermediate mode**) after each event.
-Even though the each frame is regenerated from scratch each render loop, the
-corresponding application is still pretty performant as the renderer uses a
-double buffered intermediate mode implementation to only apply the changes from
-each frame to the next to the terminal.
-
-This library is also designed to work accordingly in ssh hosted environments,
-such that an application created using this library can be accessed directly
-via ssh. This provides security through the ssh protocol and can defer the
-synchronization process, as users may access the same running instance. Which is
-the primary use-case for myself to create this library in the first place.
-
----
-## Roadmap
-
-- [ ] Container rendering
-  - [x] Layout
-    - [x] direction
-      - [x] vertical
-      - [x] horizontal
-    - [x] padding
-    - [x] gap
-  - [x] Border
-    - [x] sides
-    - [x] corners
-    - [x] separators
-  - [x] Rectangle
-  - [x] min size
-  - [ ] User control
-    - [x] event loop handling
-      - [x] mouse support
-    - [x] user content
-    - [ ] Default `Element` implementations
-      - [ ] Scrollable
-        - [x] user input handling
-          - [x] vertical
-          - [x] horizontal
-          - [x] mouse input
-        - [ ] scroll bar(s) rendering
-          - [ ] vertical
-          - [ ] horizontal
-      - [ ] Content alignment (i.e. standard calculations done with the provided `Size`)
-      - [x] User input
-        - [x] single line
-        - [x] multi line
-      - [x] min size (provide size to use which would be a minimal size - as if the actual size is smaller then the `Container` will scroll and otherwise the contents expand to the available space instead?)
-      - [ ] image support through kitty protocol (**later**)
-  - [ ] Inline rendering (**later**)
-- [ ] Examples
-  - [x] Layouts
-    - [x] vertical
-    - [x] horizontal
-    - [x] grid
-    - [x] mixed (some sort of form)
-  - [ ] Elements
-    - [x] Button
-    - [x] Text Input field
-    - [ ] Popup-menu
-    - [x] Scrollable Content (i.e. show long text of an except of something and other smaller `Container`)
-      - [x] min size
-      - [x] mouse scrolling aware of mouse position (i.e. through multiple different scrollable `Container`)
-  - [ ] Styles
-    - [ ] Text styles
-      - [ ] Colors
-        - [x] foreground
-        - [x] background
-        - [ ] underline
-      - [ ] Emphasis
-        - [x] none
-        - [x] bold
-        - [x] dim
-        - [x] italic
-        - [x] underline
-        - [x] blink
-        - [x] invert
-        - [x] hidden
-        - [x] strikethrough
-        - [ ] combinations
-    - [x] Color palette
-  - [ ] Error Handling
-    - [ ] log and show error's without crashing the application
-    - [ ] show application error that will cause a crash
-  - [ ] Demo
-    - [ ] use another tui application to launch and come back to (showcase the interrupt behavior)
-    - [ ] Launch sub-applications (not inside of a `Container` but during the application workflow, like an editor)
-- [ ] Testability
-  - [ ] snapshot ability to safe current screen (from `Renderer`) to test against
-  - [ ] try to integrate them into the library itself such that they also serve as examples on how to test
-
-Decorations should respect the layout and the viewport accordingly. This means
-that scrollbars are always visible (except there is no need to have a scrollbar)
-irrelevant depending on the size of the content. The rectangle apply to all
-cells of the content (and may be overwritten by child elements contents).
-The border of an element should be around independent of the scrolling of the
-contents, just like padding.
-
-For most of the `Element`s a standalone implementation would not make a lot
-of sense due to the complexity of the user application states. Therefore the
-library should instead provide small examples to show how you can implement
-such user fields yourself and connect them using your own event system loops to
-communicate with other `Container`s and/or `Element`s.
-
-### Scrollable contents
-
-Contents that is scrollable should be done *virtually* through the contents of
-the `Container`. This means each container contents implements scrolling for
-itself if required.
-
-This still has one issue: Layout of child elements that are already too large
-(i.e. or become too small). The library could provide automatic rendering of a
-scrollbar given the right parameters however. The scrolling input action would
-then also be implemented by the user.
-
-Open questions are regarding the sizing options (i.e. how is the size of a
-`Container` actually controlled?, how should it be controlled?, etc.). There
-should be support for the child elements to provide some kind of 'list'
-functionality built-in.
-
-**REMINDER**: (mostly for myself) The library should be and remain simple. This
-means that some code for using the library may be duplicated, but this is not
-the main goal. Others may provide more re-usable code snippets that build on top
-of this library instead.
-
-### User specific event handling and content rendering
-
-For interactions controlled by the user each container can use an `Element`
-interface which contains functions which are called by the `Container`
-during event handling (i.e. `fn handle(..)`) and during rendering (i.e. `fn
-content(..)`) to provide user specific content and user interaction. The
-`Element` may be stateful, but may also be stateless and then be re-used in
-multiple different `Container`s.
-
-Composing multiple `Element`s currently requires the implementation of a wrapper
-which contains the `Element`s that need to be handled (should work pretty well
-for stateless `Element`s). Such *stateless* `Element`s may be provided by this
-library.
-
-### Input
-
-How is the user input handled in the containers? Should there be active
-containers? Some input may happen for a specific container (i.e. when using
-mouse input). How would I handle scrolling for outer and inner elements of
-a container?
-
 ### Documentation
 
 A wiki should be created containing a bright overview of the structure and usage
@@ -219,30 +44,3 @@ of the library. For details it should refer to the examples. The documentation
 should be minimal in terms of updateability in case the library changes. Maybe
 some documentation could be derived from the code documentation (there is a tool
 for this if I recall correctly).
-
-Afterwards this README file contents can be updated to provide an actual
-overview of the library in a short form containing links to the detailed
-information required for usage.
-
-The documentation may contain tips about how to implement corresponding event
-loops or how to design own `Element`s. And also on how to test accordingly and
-use the library itself for examples on how to design the test cases.
-
-### Archive
-
-The alignment and sizing options only make sense if both are available. For
-this the current implementation has the viewport size and the content size too
-linked. Therefore they have both been removed (at least for now):
-
-  - *fit*:   adjust virtual space of container by the size of its children (i.e. a
-             container needs to be able to get the necessary size of its children)
-  - *grow*:  use as much space as available (what exactly would be the difference
-             between this option and *fit*?)
-  - *fixed*: use exactly as much cells (in the specified direction)
-
-  - *center*: elements should have their anchor be placed accordingly to their
-              size and the viewport size.
-  - *left*:   the anchor remains at zero (relative to the location of the
-              container on the screen) -> similar to the current implementation!
-  - *right*:  the anchor is fixed to the right side (i.e. size of the contents -
-              size of the viewport)

build.zig

@@ -1,13 +1,16 @@
-const std = @import("std");
-
 pub fn build(b: *std.Build) void {
     const target = b.standardTargetOptions(.{});
     const optimize = b.standardOptimizeOption(.{});
 
     const Examples = enum {
+        all,
+        demo,
+        continuous,
         // elements:
+        alignment,
         button,
         input,
+        progress,
         scrollable,
         // layouts:
         vertical,
@@ -21,10 +24,14 @@ pub fn build(b: *std.Build) void {
         errors,
     };
 
-    const example = b.option(Examples, "example", "Example to build and/or run. (default: vertical)") orelse .vertical;
+    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", .{
@@ -34,139 +41,63 @@ 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);
+    inline for (examples) |e| {
+        if (@as(Examples, @enumFromInt(e.value)) == .all) continue; // skip `.all` entry
+        const demo = b.addExecutable(.{
+            .name = e.name,
+            .root_source_file = b.path(switch (@as(Examples, @enumFromInt(e.value))) {
+                .demo => "examples/demo.zig",
+                .continuous => "examples/continuous.zig",
                 // elements:
-    const button = b.addExecutable(.{
-        .name = "button",
-        .root_source_file = b.path("examples/elements/button.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    button.root_module.addImport("zterm", lib);
-
-    const input = b.addExecutable(.{
-        .name = "input",
-        .root_source_file = b.path("examples/elements/input.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    input.root_module.addImport("zterm", lib);
-
-    const scrollable = b.addExecutable(.{
-        .name = "scrollable",
-        .root_source_file = b.path("examples/elements/scrollable.zig"),
-        .target = target,
-        .optimize = optimize,
-    });
-    scrollable.root_module.addImport("zterm", lib);
-
+                .alignment => "examples/elements/alignment.zig",
+                .button => "examples/elements/button.zig",
+                .input => "examples/elements/input.zig",
+                .progress => "examples/elements/progress.zig",
+                .scrollable => "examples/elements/scrollable.zig",
                 // 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);
-
+                .vertical => "examples/layouts/vertical.zig",
+                .horizontal => "examples/layouts/horizontal.zig",
+                .grid => "examples/layouts/grid.zig",
+                .mixed => "examples/layouts/mixed.zig",
                 // styles:
-    const palette = b.addExecutable(.{
-        .name = "palette",
-        .root_source_file = b.path("examples/styles/palette.zig"),
+                .text => "examples/styles/text.zig",
+                .palette => "examples/styles/palette.zig",
+                // error handling
+                .errors => "examples/errors.zig",
+                .all => unreachable, // should never happen
+            }),
             .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);
-
+        // import dependencies
+        demo.root_module.addImport("zterm", lib);
         // mapping of user selected example to compile step
-    const exe = switch (example) {
-        // 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,
-    };
-    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);
+        if (@intFromEnum(example) == e.value or example == .all) b.installArtifact(demo);
+    }
 
     // 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

@@ -6,16 +6,29 @@
     //
     // It is redundant to include "zig" in this name because it is already
     // within the Zig package namespace.
-    .name = "zterm",
+    .name = .zterm,
+
+    // Together with name, this represents a globally unique package
+    // identifier. This field is generated by the Zig toolchain when the
+    // package is first created, and then *never changes*. This allows
+    // unambiguous detection of one package being an updated version of
+    // another.
+    //
+    // When forking a Zig project, this id should be regenerated (delete the
+    // field and run `zig build`) if the upstream project is still maintained.
+    // Otherwise, the fork is *hostile*, attempting to take control over the
+    // original project's identity. Thus it is recommended to leave the comment
+    // on the following line intact, so that it shows up in code reviews that
+    // modify the field.
+    .fingerprint = 0xf10b37e210a619d7, // Changing this has security and trust implications.
 
     // This is a [Semantic Version](https://semver.org/).
     // In a future version of Zig it will be used for package deduplication.
-    .version = "0.0.0",
+    .version = "0.3.0",
 
-    // This field is optional.
-    // This is currently advisory only; Zig does not yet do anything
-    // with this value.
-    //.minimum_zig_version = "0.11.0",
+    // Tracks the earliest Zig version that the package considers to be a
+    // supported use case.
+    .minimum_zig_version = "0.15.0-dev.56+d0911786c",
 
     // This field is optional.
     // Each dependency must either provide a `url` and `hash`, or a `path`.
@@ -24,16 +37,14 @@
     // internet connectivity.
     .dependencies = .{
         .zg = .{
-            .url = "git+https://codeberg.org/atman/zg#4a002763419a34d61dcbb1f415821b83b9bf8ddc",
-            .hash = "1220f3e29bc40856bfc06e0ee133f814b0011c76de987d8a6a458c2f34d82708899a",
+            .url = "git+https://codeberg.org/atman/zg#9427a9e53aaa29ee071f4dcb35b809a699d75aa9",
+            .hash = "zg-0.14.1-oGqU3IQ_tALZIiBN026_NTaPJqU-Upm8P_C7QED2Rzm8",
         },
     },
     .paths = .{
+        "LICENSE",
         "build.zig",
         "build.zig.zon",
         "src",
-        // For example...
-        //"LICENSE",
-        //"README.md",
     },
 }

examples/continuous.zig

@@ -0,0 +1,245 @@
+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);
+
+                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

@@ -0,0 +1,162 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit. Press ctrl+n to launch helix.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const y = 2;
+        const x = size.x / 2 -| (text.len / 2);
+        const anchor = (y * size.x) + x;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.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});
+
+    // TODO maybe create own allocator as some sort of arena allocator to have consistent memory usage
+    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 quit_text: QuitText = .{};
+
+    // TODO what should the demo application do?
+    // - some sort of chat? -> write messages and have them displayed in a scrollable array at the right hand side?
+    // - on the left some buttons?
+    var box = try App.Container.init(allocator, .{
+        .border = .{
+            .color = .blue,
+            .sides = .all,
+        },
+        .layout = .{
+            .gap = 1,
+            .padding = .vertical(2),
+            .direction = .vertical,
+        },
+        .size = .{
+            .dim = .{ .y = 90 },
+        },
+    }, .{});
+    try box.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_green },
+    }, .{}));
+    try box.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_green },
+    }, .{}));
+    try box.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .light_green },
+    }, .{}));
+    defer box.deinit();
+
+    var scrollable: App.Scrollable = .init(box, .disabled);
+
+    var container = try App.Container.init(allocator, .{
+        .layout = .{
+            .gap = 2,
+            .separator = .{ .enabled = true },
+            .padding = .{ .top = 5, .bottom = 3, .left = 3, .right = 3 },
+            .direction = .horizontal,
+        },
+    }, quit_text.element());
+    try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
+
+    var environment = try std.process.getEnvMap(allocator);
+    defer environment.deinit();
+
+    var editor: App.Exec = .init(
+        allocator,
+        &.{
+            "tty",
+        },
+        &environment,
+        &app.queue,
+    );
+    defer editor.deinit();
+
+    try container.append(try App.Container.init(allocator, .{
+        .border = .{
+            .color = .light_blue,
+            .sides = .all,
+        },
+        .size = .{
+            .dim = .{ .x = 100 },
+        },
+    }, editor.element()));
+
+    try container.append(try App.Container.init(allocator, .{
+        .rectangle = .{ .fill = .blue },
+        .size = .{
+            .dim = .{ .x = 30 },
+        },
+    }, .{}));
+    defer container.deinit(); // also de-initializes the children
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    var process_in: std.ArrayListUnmanaged(u8) = .empty;
+    defer process_in.deinit(allocator);
+    var process_out: std.ArrayListUnmanaged(u8) = .empty;
+    defer process_out.deinit(allocator);
+
+    // 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(),
+            // NOTE errors could be displayed in another container in case one was received, etc. to provide the user with feedback
+            .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+            else => {},
+        }
+
+        // NOTE returned errors should be propagated back to the application
+        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 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,16 +1,34 @@
-const std = @import("std");
-const zterm = @import("zterm");
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
 
-const App = zterm.App(union(enum) {
-    click: [:0]const u8,
-});
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
 
-const log = std.log.scoped(.default);
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
-pub const Clickable = struct {
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+const Clickable = struct {
     const text = "Press me";
 
     queue: *App.Queue,
+    color: zterm.Color = .black,
 
     pub fn element(this: *@This()) App.Element {
         return .{
@@ -25,24 +43,32 @@ pub const Clickable = struct {
     fn handle(ctx: *anyopaque, event: App.Event) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
         switch (event) {
-            .mouse => |mouse| this.queue.push(.{ .click = @tagName(mouse.button) }),
+            .mouse => |mouse| if (mouse.button == .left and mouse.kind == .release) {
+                var value = @intFromEnum(this.color);
+                value += 1;
+                value %= 17;
+                if (value == 0) value = 1;
+                this.color = @enumFromInt(value);
+                this.queue.push(.{ .click = @tagName(mouse.button) });
+            },
             else => {},
         }
     }
 
-    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
-        _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+    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));
 
-        const row = size.rows / 2 -| (text.len / 2);
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        const row = size.y / 2 -| (text.len / 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 = .black;
+            cells[anchor + idx].style.fg = this.color;
+            cells[anchor + idx].style.emphasis = &.{.bold};
             cells[anchor + idx].cp = cp;
 
-            // NOTE: do not write over the contents of this `Container`'s `Size`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -51,10 +77,8 @@ pub const Clickable = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
 
@@ -65,13 +89,18 @@ pub fn main() !void {
     var clickable: Clickable = .{ .queue = &app.queue };
     const element = clickable.element();
 
+    var button: App.Button(.accept) = .init(&app.queue, .init(.default, "Button"));
+
+    var quit_text: QuitText = .{};
+
     var container = try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .grey },
         .layout = .{ .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 = .black } }, button.element()));
 
     try app.start();
     defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
@@ -81,14 +110,11 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
-            .click => |button| {
-                log.info("Clicked with mouse using Button: {s}", .{button});
-            },
+            .click => |b| log.info("Clicked with mouse using Button: {s}", .{b}),
+            .accept => log.info("Clicked built-in button using the mouse", .{}),
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
         }
@@ -100,7 +126,26 @@ pub fn main() !void {
             },
         });
 
+        // 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) {
+    click: [:0]const u8,
+    accept,
+});

examples/elements/input.zig

@@ -1,26 +1,31 @@
-const std = @import("std");
-const zterm = @import("zterm");
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
 
-const App = zterm.App(union(enum) {
-    accept: []u21,
-});
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
 
-const log = std.log.scoped(.default);
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
-pub const InputField = struct {
-    input: std.ArrayList(u21),
-    queue: *App.Queue,
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
 
-    pub fn init(allocator: std.mem.Allocator, queue: *App.Queue) @This() {
-        return .{
-            .input = .init(allocator),
-            .queue = queue,
+        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 deinit(this: @This()) void {
-        this.input.deinit();
-    }
+const MouseDraw = struct {
+    position: ?zterm.Point = null,
 
     pub fn element(this: *@This()) App.Element {
         return .{
@@ -35,35 +40,19 @@ pub const InputField = struct {
     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);
-
-                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 }) or key.eql(.{ .cp = zterm.input.Delete }) or key.eql(.{ .cp = zterm.input.KpDelete }))
-                    _ = this.input.pop();
-            },
-            else => {},
+            .mouse => |mouse| this.position = .{ .x = mouse.x, .y = mouse.y },
+            else => this.position = null,
         }
     }
 
-    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    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));
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
 
-        if (this.input.items.len == 0) return;
-
-        const row = 1;
-        const col = 1;
-        const anchor = (row * size.cols) + col;
-
-        for (this.input.items, 0..) |cp, idx| {
-            cells[anchor + idx].style.fg = .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;
+        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;
         }
     }
 };
@@ -71,10 +60,8 @@ pub const InputField = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
 
     const allocator = gpa.allocator();
 
@@ -82,18 +69,50 @@ pub fn main() !void {
     var renderer = zterm.Renderer.Buffered.init(allocator);
     defer renderer.deinit();
 
-    var input_field: InputField = .init(allocator, &app.queue);
+    var input_field: App.Input(.accept) = .init(allocator, &app.queue, .init(.black));
     defer input_field.deinit();
 
-    const element = input_field.element();
+    var mouse_draw: MouseDraw = .{};
+    var second_mouse_draw: MouseDraw = .{};
+    var quit_text: QuitText = .{};
 
     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 = 1 },
+        },
+    }, 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});
@@ -103,14 +122,12 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
             .accept => |input| {
                 defer allocator.free(input);
-                log.info("Accepted input {any}", .{input});
+                log.debug("Accepted input '{s}'", .{input});
             },
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
@@ -123,7 +140,27 @@ pub fn main() !void {
             },
         });
 
+        // 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 Color = zterm.Color;
+
+const App = zterm.App(union(enum) {
+    accept: []u8,
+});

examples/elements/progress.zig

@@ -0,0 +1,137 @@
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
+
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
+
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
+
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+pub fn main() !void {
+    errdefer |err| log.err("Application Error: {any}", .{err});
+
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
+    const allocator = gpa.allocator();
+
+    var app: App = .init;
+    var renderer = zterm.Renderer.Buffered.init(allocator);
+    defer renderer.deinit();
+
+    var progress_percent: u8 = 0;
+    var progress: App.Progress(.progress) = .init(&app.queue, .{
+        .percent = .{ .enabled = true },
+        .fg = .green,
+        .bg = .grey,
+    });
+    var quit_text: QuitText = .{};
+
+    var container = try App.Container.init(allocator, .{
+        .layout = .{ .padding = .all(5) },
+    }, quit_text.element());
+    defer container.deinit();
+
+    try container.append(try App.Container.init(allocator, .{}, progress.element()));
+
+    try app.start();
+    defer app.stop() catch |err| log.err("Failed to stop application: {any}", .{err});
+
+    var framerate: u64 = 60;
+    var tick_ms: u64 = @divFloor(time.ms_per_s, framerate);
+    var next_frame_ms: u64 = 0;
+
+    var increase_progress: u64 = 10;
+
+    // Continuous drawing
+    // draw loop
+    draw: while (true) {
+        const now_ms: u64 = @intCast(time.milliTimestamp());
+        if (now_ms >= next_frame_ms) {
+            next_frame_ms = now_ms + tick_ms;
+        } else {
+            time.sleep((next_frame_ms - now_ms) * time.ns_per_ms);
+            next_frame_ms += tick_ms;
+        }
+
+        // NOTE time based progress increasion
+        increase_progress -= 1;
+        if (increase_progress == 0) {
+            increase_progress = 10;
+            progress_percent += 1;
+            if (progress_percent > 100) progress_percent = 0;
+            app.postEvent(.{ .progress = progress_percent });
+        }
+
+        const len = blk: {
+            app.queue.lock();
+            defer app.queue.unlock();
+            break :blk app.queue.len();
+        };
+
+        // handle events
+        for (0..len) |_| {
+            const event = app.queue.drain() orelse break;
+            log.debug("handling event: {s}", .{@tagName(event)});
+            // pre event handling
+            switch (event) {
+                .key => |key| {
+                    if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit();
+                },
+                .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
+                .focus => |b| {
+                    // NOTE reduce framerate in case the window is not focused and restore again when focused
+                    framerate = if (b) 60 else 15;
+                    tick_ms = @divFloor(time.ms_per_s, framerate);
+                },
+                else => {},
+            }
+
+            container.handle(event) catch |err| app.postEvent(.{
+                .err = .{
+                    .err = err,
+                    .msg = "Container Event handling failed",
+                },
+            });
+
+            // post event handling
+            switch (event) {
+                .quit => break :draw,
+                else => {},
+            }
+        }
+
+        container.resize(try renderer.resize());
+        container.reposition(.{});
+        try renderer.render(@TypeOf(container), &container);
+        try renderer.flush();
+    }
+}
+
+pub const panic = App.panic_handler;
+const log = std.log.scoped(.default);
+
+const std = @import("std");
+const time = std.time;
+const assert = std.debug.assert;
+const zterm = @import("zterm");
+const App = zterm.App(union(enum) {
+    progress: u8,
+});

examples/elements/scrollable.zig

@@ -1,12 +1,30 @@
-const std = @import("std");
-const zterm = @import("zterm");
+const QuitText = struct {
+    const text = "Press ctrl+c to quit.";
 
-const input = zterm.input;
-const App = zterm.App(union(enum) {});
+    pub fn element(this: *@This()) App.Element {
+        return .{ .ptr = this, .vtable = &.{ .content = content } };
+    }
 
-const log = std.log.scoped(.default);
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        _ = ctx;
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
-pub const HelloWorldText = packed struct {
+        const row = 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
+
+        for (text, 0..) |cp, idx| {
+            cells[anchor + idx].style.fg = .white;
+            cells[anchor + idx].style.bg = .black;
+            cells[anchor + idx].cp = cp;
+
+            // NOTE do not write over the contents of this `Container`'s `Size`
+            if (anchor + idx == cells.len - 1) break;
+        }
+    }
+};
+
+const HelloWorldText = packed struct {
     const text = "Hello World";
 
     pub fn element(this: *@This()) App.Element {
@@ -16,18 +34,21 @@ pub const HelloWorldText = packed struct {
         };
     }
 
-    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
-        // NOTE: error should only be returned here in case an in-recoverable exception has occurred
-        const row = size.rows / 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        const row = size.y / 2;
+        const col = size.x / 2 -| (text.len / 2);
+        const anchor = (row * size.x) + col;
 
-        for (0.., text) |idx, char| {
-            cells[anchor + idx].style.fg = .black;
-            cells[anchor + idx].cp = char;
+        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;
         }
     }
 };
@@ -35,8 +56,8 @@ pub const HelloWorldText = packed struct {
 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;
+    // TODO maybe create own allocator as some sort of arena allocator to have consistent memory usage
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
     defer {
         const deinit_status = gpa.deinit();
         if (deinit_status == .leak) {
@@ -52,34 +73,55 @@ pub fn main() !void {
     var element_wrapper: HelloWorldText = .{};
     const element = element_wrapper.element();
 
+    var quit_text: QuitText = .{};
+
     var top_box = try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .blue },
         .layout = .{
-            .gap = 1,
+            .gap = 2,
+            .separator = .{
+                .enabled = true,
+            },
             .direction = .vertical,
             .padding = .vertical(1),
         },
-        .min_size = .{ .rows = 50 },
     }, .{});
     try top_box.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .light_green },
+        .size = .{
+            .dim = .{ .y = 30 },
+        },
     }, .{}));
     try top_box.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .light_green },
+        .size = .{
+            .dim = .{ .y = 5 },
+        },
     }, element));
     try top_box.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .light_green },
+        .size = .{
+            .dim = .{ .y = 2 },
+        },
     }, .{}));
     defer top_box.deinit();
 
     var bottom_box = try App.Container.init(allocator, .{
-        .border = .{ .separator = .{ .enabled = true } },
-        .rectangle = .{ .fill = .blue },
+        .border = .{
+            .sides = .all,
+            .color = .blue,
+        },
         .layout = .{
+            .separator = .{
+                .enabled = true,
+                .color = .red,
+            },
             .direction = .vertical,
             .padding = .vertical(1),
         },
-        .min_size = .{ .rows = 30 },
+        .size = .{
+            .dim = .{ .y = 30 },
+        },
     }, .{});
     try bottom_box.append(try App.Container.init(allocator, .{
         .rectangle = .{ .fill = .grey },
@@ -93,25 +135,23 @@ pub fn main() !void {
     defer bottom_box.deinit();
 
     var container = try App.Container.init(allocator, .{
-        .border = .{
+        .layout = .{
+            .gap = 2,
             .separator = .{
                 .enabled = true,
                 .line = .double,
             },
-        },
-        .layout = .{
-            .gap = 2,
-            .padding = .all(5),
+            .padding = .{ .top = 5, .bottom = 3, .left = 3, .right = 3 },
             .direction = .vertical,
         },
-    }, .{});
+    }, quit_text.element());
     defer container.deinit();
 
     // place empty container containing the element of the scrollable Container.
-    var scrollable_top: App.Scrollable = .init(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 = .init(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();
@@ -122,10 +162,8 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .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 => {},
@@ -137,7 +175,25 @@ pub fn main() !void {
                 .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 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.";
 
@@ -12,20 +5,20 @@ const QuitText = struct {
         return .{ .ptr = this, .vtable = &.{ .content = content } };
     }
 
-    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -38,20 +31,20 @@ const InfoText = struct {
         return .{ .ptr = this, .vtable = &.{ .content = content } };
     }
 
-    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -64,31 +57,30 @@ const ErrorNotification = struct {
         return .{ .ptr = this, .vtable = &.{ .handle = handle, .content = content } };
     }
 
-    pub fn handle(ctx: *anyopaque, event: App.Event) !void {
+    fn handle(ctx: *anyopaque, event: App.Event) !void {
         const this: *@This() = @ptrCast(@alignCast(ctx));
         switch (event) {
-            .key => |key| if (!key.isAscii()) return error.UnsupportedKey,
-            .resize => |_| {},
+            .key => |key| if (!key.isAscii()) return zterm.Error.TooSmall,
             .err => |err| this.msg = err.msg,
             else => {},
         }
     }
 
-    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    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.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         if (this.msg) |msg| {
-            const row = size.rows -| 2;
-            const col = size.cols -| 2 -| msg.len;
-            const anchor = (row * size.cols) + col;
+            const row = size.y -| 2;
+            const col = size.x -| 2 -| msg.len;
+            const anchor = (row * size.x) + col;
 
             for (msg, 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`
+                // NOTE do not write over the contents of this `Container`'s `Size`
                 if (anchor + idx == cells.len - 1) break;
             }
 
@@ -100,10 +92,9 @@ const ErrorNotification = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
     const allocator = gpa.allocator();
 
     var app: App = .init;
@@ -132,10 +123,8 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .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 => {},
@@ -147,7 +136,24 @@ pub fn main() !void {
                 .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/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.";
 
@@ -15,20 +8,20 @@ const QuitText = struct {
         };
     }
 
-    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -37,10 +30,9 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
     const allocator = gpa.allocator();
 
     var app: App = .init;
@@ -51,16 +43,16 @@ pub fn main() !void {
     const element = quit_text.element();
 
     var container = try App.Container.init(allocator, .{
-        .border = .{ .separator = .{ .enabled = true } },
         .layout = .{
+            .separator = .{ .enabled = true },
             .padding = .{ .top = 5, .bottom = 3, .left = 3, .right = 3 },
             .direction = .horizontal,
         },
     }, element);
     for (0..3) |_| {
         var column = try App.Container.init(allocator, .{
-            .border = .{ .separator = .{ .enabled = true } },
             .layout = .{
+                .separator = .{ .enabled = true },
                 .direction = .vertical,
             },
         }, .{});
@@ -85,24 +77,39 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
-            // NOTE: errors could be displayed in another container in case one was received, etc. to provide the user with feedback
+            // NOTE errors could be displayed in another container in case one was received, etc. to provide the user with feedback
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
         }
 
-        // NOTE: returned errors should be propagated back to the application
+        // NOTE returned errors should be propagated back to the application
         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/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.";
 
@@ -15,20 +8,20 @@ const QuitText = struct {
         };
     }
 
-    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -37,10 +30,9 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
     const allocator = gpa.allocator();
 
     var app: App = .init;
@@ -77,24 +69,39 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
-            // NOTE: errors could be displayed in another container in case one was received, etc. to provide the user with feedback
+            // NOTE errors could be displayed in another container in case one was received, etc. to provide the user with feedback
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
         }
 
-        // NOTE: returned errors should be propagated back to the application
+        // NOTE returned errors should be propagated back to the application
         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/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.";
 
@@ -15,20 +8,20 @@ const QuitText = struct {
         };
     }
 
-    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -37,10 +30,9 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
     const allocator = gpa.allocator();
 
     var app: App = .init;
@@ -54,13 +46,12 @@ pub fn main() !void {
         .layout = .{
             .gap = 2,
             .padding = .{ .top = 5, .bottom = 3, .left = 3, .right = 3 },
-            .direction = .horizontal,
         },
     }, element);
     for (0..3) |i| {
         var column = try App.Container.init(allocator, .{
-            .border = .{ .separator = .{ .enabled = true } },
             .layout = .{
+                .separator = .{ .enabled = true },
                 .direction = if (i > 0) .vertical else .horizontal,
             },
         }, .{});
@@ -72,7 +63,12 @@ pub fn main() !void {
                 .rectangle = .{ .fill = .yellow },
             }, .{}));
         } else {
-            try column.append(try App.Container.init(allocator, .{}, .{}));
+            try column.append(try App.Container.init(allocator, .{
+                .size = .{
+                    .dim = .{ .y = 4 },
+                    .grow = .horizontal,
+                },
+            }, .{}));
         }
         try column.append(try App.Container.init(allocator, .{
             .rectangle = .{ .fill = .blue },
@@ -89,24 +85,39 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
-            // NOTE: errors could be displayed in another container in case one was received, etc. to provide the user with feedback
+            // NOTE errors could be displayed in another container in case one was received, etc. to provide the user with feedback
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
         }
 
-        // NOTE: returned errors should be propagated back to the application
+        // NOTE returned errors should be propagated back to the application
         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/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.";
 
@@ -15,20 +8,20 @@ const QuitText = struct {
         };
     }
 
-    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -37,10 +30,9 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
     const allocator = gpa.allocator();
 
     var app: App = .init;
@@ -76,24 +68,39 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .key => |key| if (key.eql(.{ .cp = 'c', .mod = .{ .ctrl = true } })) app.quit(),
-            // NOTE: errors could be displayed in another container in case one was received, etc. to provide the user with feedback
+            // NOTE errors could be displayed in another container in case one was received, etc. to provide the user with feedback
             .err => |err| log.err("Received {s} with message: {s}", .{ @errorName(err.err), err.msg }),
             else => {},
         }
 
-        // NOTE: returned errors should be propagated back to the application
+        // NOTE returned errors should be propagated back to the application
         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/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.";
 
@@ -12,20 +5,20 @@ const QuitText = struct {
         return .{ .ptr = this, .vtable = &.{ .content = content } };
     }
 
-    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -34,10 +27,9 @@ const QuitText = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
     const allocator = gpa.allocator();
 
     var app: App = .init;
@@ -57,15 +49,14 @@ pub fn main() !void {
 
     var box = try App.Container.init(allocator, .{
         .layout = .{ .direction = .horizontal },
-        .min_size = .{ .cols = 3 * std.meta.fields(zterm.Color).len }, // ensure enough columns to render all colors -> scrollable otherwise
     }, .{});
     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 = .init(box);
+    var scrollable: App.Scrollable = .init(box, .disabled);
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
     try app.start();
@@ -75,10 +66,8 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .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 => {},
@@ -90,7 +79,24 @@ pub fn main() !void {
                 .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/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.";
 
@@ -12,20 +5,20 @@ const QuitText = struct {
         return .{ .ptr = this, .vtable = &.{ .content = content } };
     }
 
-    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        assert(cells.len == @as(usize, size.x) * @as(usize, size.y));
 
         const row = 2;
-        const col = size.cols / 2 -| (text.len / 2);
-        const anchor = (row * size.cols) + col;
+        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`
+            // NOTE do not write over the contents of this `Container`'s `Size`
             if (anchor + idx == cells.len - 1) break;
         }
     }
@@ -38,40 +31,40 @@ const TextStyles = struct {
         return .{ .ptr = this, .vtable = &.{ .content = content } };
     }
 
-    pub fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Size) !void {
-        @setEvalBranchQuota(50000);
+    fn content(ctx: *anyopaque, cells: []zterm.Cell, size: zterm.Point) !void {
+        @setEvalBranchQuota(10000);
         _ = ctx;
-        std.debug.assert(cells.len == @as(usize, size.cols) * @as(usize, size.rows));
+        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 (comptime fg_field.value == bg_field.value) continue;
+                if (fg_field.value == 0) continue; // zterm.Color.default == 0 -> skip
+                if (fg_field.value == bg_field.value) continue;
 
                 // witouth any emphasis
                 for (text) |cp| {
-                    cells[(row * size.cols) + col].style.bg = @enumFromInt(bg_field.value);
-                    cells[(row * size.cols) + col].style.fg = @enumFromInt(fg_field.value);
-                    cells[(row * size.cols) + col].cp = cp;
+                    cells[(row * size.x) + col].style.bg = @enumFromInt(bg_field.value);
+                    cells[(row * size.x) + col].style.fg = @enumFromInt(fg_field.value);
+                    cells[(row * size.x) + col].cp = cp;
                     col += 1;
                 }
 
                 // 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| {
-                        cells[(row * size.cols) + col].style.bg = @enumFromInt(bg_field.value);
-                        cells[(row * size.cols) + col].style.fg = @enumFromInt(fg_field.value);
-                        cells[(row * size.cols) + col].style.emphasis = &.{emphasis};
-                        cells[(row * size.cols) + col].cp = cp;
+                        cells[(row * size.x) + col].style.bg = @enumFromInt(bg_field.value);
+                        cells[(row * size.x) + col].style.fg = @enumFromInt(fg_field.value);
+                        cells[(row * size.x) + col].style.emphasis = &.{emphasis};
+                        cells[(row * size.x) + col].cp = cp;
                         col += 1;
                     }
                 }
@@ -85,10 +78,9 @@ const TextStyles = struct {
 pub fn main() !void {
     errdefer |err| log.err("Application Error: {any}", .{err});
 
-    var gpa: std.heap.GeneralPurposeAllocator(.{}) = .init;
-    defer if (gpa.deinit() == .leak) {
-        log.err("memory leak", .{});
-    };
+    var gpa: std.heap.DebugAllocator(.{}) = .init;
+    defer if (gpa.deinit() == .leak) log.err("memory leak", .{});
+
     const allocator = gpa.allocator();
 
     var app: App = .init;
@@ -110,14 +102,16 @@ pub fn main() !void {
 
     var box = try App.Container.init(allocator, .{
         .layout = .{ .direction = .vertical },
-        .min_size = .{
-            .rows = (std.meta.fields(zterm.Color).len - 1) * (std.meta.fields(zterm.Color).len - 2),
-            .cols = std.meta.fields(zterm.Style.Emphasis).len * TextStyles.text.len,
-        }, // ensure enough rows and/or columns to render all text styles -> scrollable otherwise
+        .size = .{
+            .dim = .{
+                .x = std.meta.fields(zterm.Style.Emphasis).len * TextStyles.text.len,
+                .y = (std.meta.fields(zterm.Color).len - 1) * (std.meta.fields(zterm.Color).len - 2),
+            },
+        },
     }, text_styles.element());
     defer box.deinit();
 
-    var scrollable: App.Scrollable = .init(box);
+    var scrollable: App.Scrollable = .init(box, .disabled);
     try container.append(try App.Container.init(allocator, .{}, scrollable.element()));
 
     try app.start();
@@ -127,10 +121,8 @@ pub fn main() !void {
         const event = app.nextEvent();
         log.debug("received event: {s}", .{@tagName(event)});
 
+        // pre event handling
         switch (event) {
-            .init => continue,
-            .quit => break,
-            .resize => |size| try renderer.resize(size),
             .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 => {},
@@ -142,7 +134,24 @@ pub fn main() !void {
                 .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) {});

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 Size = @import("size.zig").Size;
-
-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,59 +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,
-        quit_event: std.Thread.ResetEvent,
-        termios: ?std.posix.termios = null,
-        attached_handler: bool = false,
-        prev_size: Size,
+        thread: ?Thread = null,
+        quit_event: Thread.ResetEvent,
+        termios: ?posix.termios = null,
+        winch_registered: bool = false,
 
-        pub const SignalHandler = struct {
-            context: *anyopaque,
-            callback: *const fn (context: *anyopaque) void,
-        };
+        // global variable for the registered handler for WINCH
+        var handler_ctx: *anyopaque = undefined;
+        /// 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,
-            .prev_size = .{},
         };
 
         pub fn start(this: *@This()) !void {
             if (this.thread) |_| return;
 
-            if (!this.attached_handler) {
-                var winch_act = std.posix.Sigaction{
-                    .handler = .{ .handler = @This().handleWinch },
-                    .mask = std.posix.empty_sigset,
-                    .flags = 0,
-                };
-                std.posix.sigaction(std.posix.SIG.WINCH, &winch_act, null);
-
-                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);
+
+            if (!this.winch_registered) {
+                handler_ctx = this;
+                var act = posix.Sigaction{
+                    .handler = .{ .handler = handleWinch },
+                    .mask = posix.sigemptyset(),
+                    .flags = 0,
+                };
+                posix.sigaction(posix.SIG.WINCH, &act, null);
+                this.winch_registered = true;
             }
 
             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;
 
@@ -99,11 +73,6 @@ pub fn App(comptime E: type) type {
             try terminal.enterAltScreen();
             try terminal.hideCursor();
             try terminal.enableMouseSupport();
-
-            // send initial size afterwards
-            const size = terminal.getTerminalSize();
-            this.postEvent(.{ .resize = size });
-            this.prev_size = size;
         }
 
         pub fn interrupt(this: *@This()) !void {
@@ -146,39 +115,15 @@ pub fn App(comptime E: type) type {
             this.queue.push(e);
         }
 
-        fn winsizeCallback(ptr: *anyopaque) void {
-            const this: *@This() = @ptrCast(@alignCast(ptr));
-            const size = terminal.getTerminalSize();
-            if (size.cols != this.prev_size.cols or size.rows != this.prev_size.rows) {
-                this.postEvent(.{ .resize = size });
-                this.prev_size = size;
-            }
-        }
-
-        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;
             while (true) {
-                // FIX: I still think that there is a race condition (I'm just waiting 'long' enough)
+                // FIX I still think that there is a race condition (I'm just waiting 'long' enough)
                 this.quit_event.timedWait(20 * std.time.ns_per_ms) catch {
-                    // FIX: in case the queue is full -> the next user input should panic and quit the application? because something seems to clock up the event queue
+                    // FIX in case the queue is full -> the next user input should panic and quit the application? because something seems to clock up the event queue
                     const read_bytes = try terminal.read(buf[0..]);
-                    // TODO: `break` should not terminate the reading of the user inputs, but instead only the received faulty input!
+                    // TODO `break` should not terminate the reading of the user inputs, but instead only the received faulty input!
                     // escape key presses
                     if (buf[0] == 0x1b and read_bytes > 1) {
                         switch (buf[1]) {
@@ -218,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,
@@ -231,22 +179,36 @@ 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], ';');
-                                        const number_buf = field_iter.next() orelse unreachable; // always will have one field
-                                        const number = std.fmt.parseUnsigned(u16, number_buf, 10) catch break;
+                                        var field_iter = mem.splitScalar(u8, sequence[2 .. sequence.len - 1], ';');
 
                                         const key: Key = .{
-                                            .cp = switch (number) {
+                                            .cp = blk: {
+                                                const number_buf = field_iter.next() orelse unreachable; // always will have one field
+                                                const number = fmt.parseUnsigned(u16, number_buf, 10) catch break;
+                                                break :blk switch (number) {
                                                     2 => input.Insert,
                                                     3 => input.Delete,
                                                     5 => input.PageUp,
@@ -265,26 +227,47 @@ pub fn App(comptime E: type) type {
                                                     21 => input.F10,
                                                     23 => input.F11,
                                                     24 => input.F12,
+                                                    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 },
-                                                57427 => input.KpBegin,
+                                                    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 });
                                     },
-                                    // TODO: focus usage? should this even be in the default event system?
+                                    // TODO focus usage? should this even be in the default event system?
                                     '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 button_mask = std.fmt.parseUnsigned(u16, sequence[3..delim1], 10) catch break;
-                                        const delim2 = std.mem.indexOfScalarPos(u8, sequence, delim1 + 1, ';') orelse break;
-                                        const px = std.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 delim1 = mem.indexOfScalarPos(u8, sequence, 3, ';') orelse break;
+                                        const button_mask = fmt.parseUnsigned(u16, sequence[3..delim1], 10) catch break;
+                                        const delim2 = mem.indexOfScalarPos(u8, sequence, delim1 + 1, ';') orelse break;
+                                        const px = fmt.parseUnsigned(u16, sequence[delim1 + 1 .. delim2], 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;
@@ -302,15 +285,11 @@ pub fn App(comptime E: type) type {
 
                                         const mouse: Mouse = .{
                                             .button = button,
-                                            .col = px -| 1,
-                                            .row = py -| 1,
+                                            .x = px -| 1,
+                                            .y = py -| 1,
                                             .kind = blk: {
-                                                if (motion and button != Mouse.Button.none) {
-                                                    break :blk .drag;
-                                                }
-                                                if (motion and button == Mouse.Button.none) {
-                                                    break :blk .motion;
-                                                }
+                                                if (motion and button != Mouse.Button.none) break :blk .drag;
+                                                if (motion and button == Mouse.Button.none) break :blk .motion;
                                                 if (sequence[sequence.len - 1] == 'm') break :blk .release;
                                                 break :blk .press;
                                             },
@@ -324,29 +303,26 @@ 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 height_char = iter.next() orelse break;
                                             const width_char = iter.next() orelse break;
+                                            const height_char = iter.next() orelse break;
 
-                                            // TODO: only post the event if the size has changed?
-                                            // because there might be too many resize events (which force a re-draw of the entire screen)
-                                            const size: Size = .{
-                                                .rows = std.fmt.parseUnsigned(u16, height_char, 10) catch break,
-                                                .cols = std.fmt.parseUnsigned(u16, width_char, 10) catch break,
-                                            };
-                                            if (size.cols != this.prev_size.cols or size.rows != this.prev_size.rows) {
-                                                this.postEvent(.{ .resize = size });
-                                                this.prev_size = size;
-                                            }
+                                            _ = width_char;
+                                            _ = height_char;
+                                            this.postEvent(.resize);
+                                            // this.postEvent(.{ .size = .{
+                                            //     .x = fmt.parseUnsigned(u16, width_char, 10) catch break,
+                                            //     .y = fmt.parseUnsigned(u16, height_char, 10) catch break,
+                                            // } });
                                         }
                                     },
                                     'u' => {
@@ -361,9 +337,29 @@ pub fn App(comptime E: type) type {
                                     else => {},
                                 }
                             },
-                            // TODO: parse corresponding codes
-                            // 0x5B => parseCsi(input, &self.buf), // CSI see https://github.com/rockorager/libvaxis/blob/main/src/Parser.zig
-                            else => {},
+                            0x50 => {
+                                // DCS
+                            },
+                            0x58 => {
+                                // SOS
+                            },
+                            0x5D => {
+                                // OSC
+                            },
+                            // TODO parse corresponding codes
+                            0x5F => {
+                                // APC
+                                // parse for kitty graphics capabilities
+                            },
+                            else => {
+                                // alt + <char> keypress
+                                this.postEvent(.{
+                                    .key = .{
+                                        .cp = buf[1],
+                                        .mod = .{ .alt = true },
+                                    },
+                                });
+                            },
                         }
                     } else {
                         const b = buf[0];
@@ -371,10 +367,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 },
@@ -391,5 +388,55 @@ 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 Button = element.Button(Event, Queue);
+        pub const Exec = element.Exec(Event, Queue);
+        pub const Input = element.Input(Event, Queue);
+        pub const Progress = element.Progress(Event, Queue);
+        pub const Scrollable = element.Scrollable(Event);
+        pub const Queue = queue.Queue(Event, 256);
     };
 }
+
+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");
-const Style = @import("style.zig");
+//! Cell type containing content and formatting for each character in the terminal screen.
 
-pub const Cell = @This();
-
-style: Style = .{ .emphasis = &.{} },
-// TODO: embrace `zg` dependency more due to utf-8 encoding
+// 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);
@@ -19,3 +16,51 @@ pub fn reset(this: *Cell) void {
 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 = &.{} } },
+        .{ .cp = 'v', .style = .{ .emphasis = &.{ .bold, .underline } } },
+        .{ .cp = 'e', .style = .{ .emphasis = &.{.italic} } },
+        .{ .cp = 's', .style = .{ .fg = .light_green, .bg = .black, .emphasis = &.{.underline} } },
+    };
+
+    var string = std.ArrayList(u8).init(std.testing.allocator);
+    defer string.deinit();
+
+    const writer = string.writer();
+    for (cells) |cell| {
+        try cell.value(writer);
+    }
+    try std.testing.expectEqualSlices(
+        u8,
+        "\x1b[38;5;10;48;5;8;59mY\x1b[0m\x1b[39;49;59;1;4mv\x1b[0m\x1b[39;49;59;3me\x1b[0m\x1b[38;5;2;48;5;16;59;4ms\x1b[0m",
+        string.items,
+    );
+}
+
+test "utf-8 styled text" {
+    const cells: [4]Cell = .{
+        .{ .cp = '╭', .style = .{ .fg = .green, .bg = .grey, .emphasis = &.{} } },
+        .{ .cp = '─', .style = .{ .emphasis = &.{} } },
+        .{ .cp = '┄', .style = .{ .emphasis = &.{} } },
+        .{ .cp = '┘', .style = .{ .fg = .light_green, .bg = .black, .emphasis = &.{.underline} } },
+    };
+
+    var string = std.ArrayList(u8).init(std.testing.allocator);
+    defer string.deinit();
+
+    const writer = string.writer();
+    for (cells) |cell| {
+        try cell.value(writer);
+    }
+    try std.testing.expectEqualSlices(
+        u8,
+        "\x1b[38;5;10;48;5;8;59m╭\x1b[0m\x1b[39;49;59m─\x1b[0m\x1b[39;49;59m┄\x1b[0m\x1b[38;5;2;48;5;16;59;4m┘\x1b[0m",
+        string.items,
+    );
+}

src/color.zig

@@ -1,5 +1,3 @@
-const std = @import("std");
-
 pub const Color = enum(u8) {
     default = 0,
     black = 16,
@@ -18,21 +16,26 @@ pub const Color = enum(u8) {
     magenta,
     cyan,
     white,
-    // TODO: add further colors as described in https://gist.github.com/ConnerWill/d4b6c776b509add763e17f9f113fd25b # Color / Graphics Mode - 256 Colors
+    // 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", .{}),
-                .bg => try std.fmt.format(writer, "49", .{}),
-                .ul => try std.fmt.format(writer, "59", .{}),
+                .fg => try format(writer, "39", .{}),
+                .bg => try format(writer, "49", .{}),
+                .ul => try format(writer, "59", .{}),
             }
         } else {
             switch (coloring) {
-                .fg => try std.fmt.format(writer, "38;5;{d}", .{@intFromEnum(this)}),
-                .bg => try std.fmt.format(writer, "48;5;{d}", .{@intFromEnum(this)}),
-                .ul => try std.fmt.format(writer, "58;5;{d}", .{@intFromEnum(this)}),
+                .fg => try format(writer, "38;5;{d}", .{@intFromEnum(this)}),
+                .bg => try format(writer, "48;5;{d}", .{@intFromEnum(this)}),
+                .ul => try format(writer, "58;5;{d}", .{@intFromEnum(this)}),
             }
         }
     }
 };
+
+const std = @import("std");
+const format = std.fmt.format;

src/ctlseqs.zig

@@ -92,7 +92,7 @@ pub const bg_rgb_legacy = "\x1b[48;2;{d};{d};{d}m";
 pub const ul_rgb_legacy = "\x1b[58;2;{d};{d};{d}m";
 
 // Underlines
-pub const ul_off = "\x1b[24m"; // NOTE: this could be \x1b[4:0m but is not as widely supported
+pub const ul_off = "\x1b[24m"; // NOTE this could be \x1b[4:0m but is not as widely supported
 pub const ul_single = "\x1b[4m";
 pub const ul_double = "\x1b[4:2m";
 pub const ul_curly = "\x1b[4:3m";

src/error.zig

@@ -0,0 +1,4 @@
+pub const Error = error{
+    /// Thrown when a `Container` is too small to be rendered in the current screen part.
+    TooSmall,
+};

src/event.zig

@@ -1,35 +1,31 @@
 //! 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 Size = @import("size.zig").Size;
 
 /// System events available to every `zterm.App`
 pub const SystemEvent = union(enum) {
     /// Initialize event, which is send once at the beginning of the event loop and before the first render loop
-    /// TODO: not sure if this is necessary or if there is an actual usecase for this - for now it will remain
+    /// TODO not sure if this is necessary or if there is an actual usecase for this - for now it will remain
     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,
     },
-    /// Resize event emitted by the terminal to derive the `Size` of the current terminal the application is rendered in
-    resize: Size,
     /// Input key event received from the user
     key: Key,
     /// Mouse input event
     mouse: Mouse,
     /// Focus event for mouse interaction
-    /// TODO: this should instead be a union with a `Size` to derive which container / element the focus meant for
+    /// TODO this should instead be a union with a `Size` to derive which container / element the focus meant for
     focus: bool,
+    /// Exit event for a completed `Exec` with the associated pid. Fired and handled by `Exec` `Element`s.
+    exited: std.posix.pid_t,
 };
 
 pub fn mergeTaggedUnions(comptime A: type, comptime B: type) type {
@@ -94,3 +90,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,11 +1,8 @@
 //! Input module for `zterm`. Contains structs to represent key events and mouse events.
-const std = @import("std");
-
-const Size = @import("size.zig").Size;
 
 pub const Mouse = packed struct {
-    col: u16,
-    row: u16,
+    x: u16,
+    y: u16,
     button: Button,
     kind: Kind,
 
@@ -32,12 +29,12 @@ 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(), size: Size) bool {
-        return this.col >= size.anchor.col and this.col <= size.cols + size.anchor.col and
-            this.row >= size.anchor.row and this.row <= size.rows + size.anchor.row;
+    pub fn in(this: @This(), origin: Point, size: Point) bool {
+        return this.x >= origin.x and this.x < size.x + origin.x and
+            this.y >= origin.y and this.y < size.y + origin.y;
     }
 };
 
@@ -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
@@ -88,8 +87,27 @@ pub const Key = packed struct {
             (this.cp >= 32 and this.cp <= 126 or // ascii printable characters (except for input.Delete)
                 this.cp >= 128 and this.cp <= 255); // extended ascii codes
     }
+
+    test "isAscii with ascii character" {
+        try testing.expectEqual(true, isAscii(.{ .cp = 'c' }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .ctrl = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true } }));
+        try testing.expectEqual(false, isAscii(.{ .cp = 'c', .mod = .{ .alt = true, .ctrl = true } }));
+    }
+
+    test "isAscii with non-ascii character" {
+        try testing.expectEqual(false, isAscii(.{ .cp = Escape }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Enter }));
+        try testing.expectEqual(false, isAscii(.{ .cp = Enter, .mod = .{ .alt = true } }));
+    }
+
+    test "isAscii with excluded input.Delete" {
+        try testing.expectEqual(false, isAscii(.{ .cp = Delete }));
+        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;
@@ -134,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;
@@ -171,8 +174,8 @@ pub const KpLeft: u21 = 57417;
 pub const KpRight: u21 = 57418;
 pub const KpUp: u21 = 57419;
 pub const KpDown: u21 = 57420;
-pub const KpPage_up: u21 = 57421;
-pub const KpPage_down: u21 = 57422;
+pub const KpPageUp: u21 = 57421;
+pub const KpPageDown: u21 = 57422;
 pub const KpHome: u21 = 57423;
 pub const KpEnd: u21 = 57424;
 pub const KpInsert: u21 = 57425;
@@ -205,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/point.zig

@@ -0,0 +1,60 @@
+pub const Point = packed struct {
+    x: u16 = 0,
+    y: u16 = 0,
+
+    pub fn add(a: @This(), b: @This()) @This() {
+        return .{
+            .x = a.x + b.x,
+            .y = a.y + b.y,
+        };
+    }
+
+    pub fn max(a: @This(), b: @This()) @This() {
+        return .{
+            .x = @max(a.x, b.x),
+            .y = @max(a.y, b.y),
+        };
+    }
+
+    test "adding" {
+        const testing = @import("std").testing;
+
+        const a: @This() = .{
+            .x = 10,
+            .y = 20,
+        };
+
+        const b: @This() = .{
+            .x = 20,
+            .y = 10,
+        };
+
+        try testing.expectEqual(@This(){
+            .x = 30,
+            .y = 30,
+        }, a.add(b));
+    }
+
+    test "maximum" {
+        const testing = @import("std").testing;
+
+        const a: @This() = .{
+            .x = 10,
+            .y = 20,
+        };
+
+        const b: @This() = .{
+            .x = 20,
+            .y = 10,
+        };
+
+        try testing.expectEqual(@This(){
+            .x = 20,
+            .y = 20,
+        }, a.max(b));
+    }
+};
+
+test {
+    _ = Point;
+}

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 std.testing.expectEqual(4, queue.pop());
+    try testing.expectEqual(3, 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 std.testing.expectEqual(2, queue.pop());
+    try testing.expectEqual(1, queue.pop());
+    try testing.expectEqual(2, queue.pop());
     thread.join();
 }
 

src/render.zig

@@ -1,21 +1,14 @@
-const std = @import("std");
-const terminal = @import("terminal.zig");
-
-const Cell = @import("cell.zig");
-const Position = @import("size.zig").Position;
-const Size = @import("size.zig").Size;
+//! Renderer for `zterm`.
 
 /// Double-buffered intermediate rendering pipeline
 pub const Buffered = struct {
-    const log = std.log.scoped(.renderer_buffered);
-    // _ = log;
-    allocator: std.mem.Allocator,
+    allocator: Allocator,
     created: bool,
-    size: Size,
+    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,
@@ -32,84 +25,107 @@ pub const Buffered = struct {
         }
     }
 
-    pub fn resize(this: *@This(), size: Size) !void {
-        log.debug("renderer::resize", .{});
-        defer this.size = size;
+    pub fn resize(this: *@This()) !Point {
+        const size = terminal.getTerminalSize();
+        if (meta.eql(this.size, size)) return this.size;
+
+        this.size = size;
+        const n = @as(usize, this.size.x) * @as(usize, this.size.y);
 
         if (!this.created) {
-            this.screen = this.allocator.alloc(Cell, @as(usize, size.cols) * @as(usize, size.rows)) catch @panic("render.zig: Out of memory.");
-            @memset(this.screen, .{});
-            this.virtual_screen = this.allocator.alloc(Cell, @as(usize, size.cols) * @as(usize, size.rows)) catch @panic("render.zig: Out of memory.");
+            this.screen = this.allocator.alloc(Cell, n) catch @panic("render.zig: Out of memory.");
+
+            this.virtual_screen = this.allocator.alloc(Cell, n) catch @panic("render.zig: Out of memory.");
             @memset(this.virtual_screen, .{});
+
             this.created = true;
         } else {
             this.allocator.free(this.screen);
-            this.screen = this.allocator.alloc(Cell, @as(usize, size.cols) * @as(usize, size.rows)) catch @panic("render.zig: Out of memory.");
-            @memset(this.screen, .{});
+            this.screen = this.allocator.alloc(Cell, n) catch @panic("render.zig: Out of memory.");
+
             this.allocator.free(this.virtual_screen);
-            this.virtual_screen = this.allocator.alloc(Cell, @as(usize, size.cols) * @as(usize, size.rows)) catch @panic("render.zig: Out of memory.");
+            this.virtual_screen = this.allocator.alloc(Cell, n) catch @panic("render.zig: Out of memory.");
             @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.
     pub fn clear(this: *@This()) !void {
-        log.debug("renderer::clear", .{});
         try terminal.clearScreen();
         @memset(this.screen, .{});
     }
 
     /// Render provided cells at size (anchor and dimension) into the *virtual screen*.
     pub fn render(this: *@This(), comptime T: type, container: *T) !void {
-        const size: Size = container.size;
-        const cells: []const Cell = try container.contents();
+        const size: Point = container.size;
+        const origin: Point = container.origin;
+        const cells: []const Cell = try container.content();
 
         if (cells.len == 0) return;
 
         var idx: usize = 0;
         var vs = this.virtual_screen;
-        const anchor: usize = (@as(usize, size.anchor.row) * @as(usize, this.size.cols)) + @as(usize, size.anchor.col);
+        const anchor: usize = (@as(usize, origin.y) * @as(usize, this.size.x)) + @as(usize, origin.x);
 
-        blk: for (0..size.rows) |row| {
-            for (0..size.cols) |col| {
-                const cell = cells[idx];
+        blk: for (0..size.y) |row| {
+            for (0..size.x) |col| {
+                vs[anchor + (row * this.size.x) + col] = cells[idx];
                 idx += 1;
 
-                vs[anchor + (row * this.size.cols) + col].style = cell.style;
-                vs[anchor + (row * this.size.cols) + col].cp = cell.cp;
-
                 if (cells.len == idx) break :blk;
             }
         }
         // free immediately
         container.allocator.free(cells);
 
-        for (container.elements.items) |*element| {
-            try this.render(T, element);
-        }
+        for (container.elements.items) |*element| try this.render(T, element);
     }
 
     /// 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 {
-        // TODO: measure timings of rendered frames?
-        log.debug("renderer::flush", .{});
+        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;
-        for (0..this.size.rows) |row| {
-            for (0..this.size.cols) |col| {
-                const idx = (row * this.size.cols) + col;
+        for (0..this.size.y) |row| {
+            for (0..this.size.x) |col| {
+                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(.{ .row = @truncate(row + 1), .col = @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

@@ -1,12 +1,14 @@
 // private imports
 const container = @import("container.zig");
 const color = @import("color.zig");
-const size = @import("size.zig");
+const size = @import("point.zig");
 
 // public exports
 pub const input = @import("input.zig");
+pub const testing = @import("testing.zig");
 
 pub const App = @import("app.zig").App;
+pub const Error = @import("error.zig").Error;
 // App also exports further types once initialized with the user events at compile time:
 // `App.Container`
 // `App.Element`
@@ -15,23 +17,23 @@ 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");
 pub const Color = color.Color;
 pub const Key = input.Key;
 pub const Mouse = input.Mouse;
-pub const Position = size.Position;
-pub const Size = size.Size;
+pub const Point = @import("point.zig").Point;
 pub const Style = @import("style.zig");
 
 test {
     _ = @import("terminal.zig");
+    _ = @import("container.zig");
     _ = @import("queue.zig");
+    _ = @import("error.zig");
+    _ = @import("point.zig");
 
     _ = color;
-    _ = size;
 
     _ = Cell;
     _ = Key;

src/size.zig

@@ -1,17 +0,0 @@
-pub const Size = packed struct {
-    anchor: Position = .{},
-    cols: u16 = 0,
-    rows: u16 = 0,
-
-    pub fn merge(this: @This(), other: @This()) Size {
-        return .{
-            .cols = this.cols + other.cols,
-            .rows = this.rows + other.rows,
-        };
-    }
-};
-
-pub const Position = packed struct {
-    col: u16 = 0,
-    row: u16 = 0,
-};

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;
-
-pub const Style = @This();
+fg: Color = .default,
+bg: Color = .default,
+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 = .white,
-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);
-    std.debug.assert(bytes > 0);
+    const bytes = try unicode.utf8Encode(cp, &buffer);
+    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, ";", .{});
+    // FIX assert that if the underline property is set that the ul style and the attribute for underlining is available
+    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)});
-    try std.fmt.format(writer, "m", .{});
+    for (this.emphasis) |attribute| try format(writer, ";{d}", .{@intFromEnum(attribute)});
+    try format(writer, "m", .{});
     // content
-    try std.fmt.format(writer, "{s}", .{buffer});
-    try std.fmt.format(writer, "\x1b[0m", .{});
+    try format(writer, "{s}", .{buffer[0..bytes]});
+    try format(writer, "\x1b[0m", .{});
 }
 
-// TODO: implement helper functions for terminal capabilities:
+// 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 Position = @import("size.zig").Position;
-const Size = @import("size.zig").Size;
-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;
-    _ = std.posix.system.ioctl(std.posix.STDIN_FILENO, std.posix.T.IOCGWINSZ, @intFromPtr(&ws));
-    return .{ .cols = ws.col, .rows = ws.row };
+    var ws: posix.winsize = undefined;
+    _ = 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(
@@ -89,21 +77,21 @@ pub fn writer() Writer {
     return .{ .context = .{} };
 }
 
-pub fn setCursorPosition(pos: Position) !void {
+pub fn setCursorPosition(pos: Point) !void {
     var buf: [64]u8 = undefined;
-    const value = try std.fmt.bufPrint(&buf, "\x1b[{d};{d}H", .{ pos.row, pos.col });
-    _ = try std.posix.write(std.posix.STDIN_FILENO, value);
+    const value = try std.fmt.bufPrint(&buf, "\x1b[{d};{d}H", .{ pos.y + 1, pos.x + 1 });
+    _ = 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;
@@ -137,8 +125,8 @@ pub fn getCursorPosition() !Size.Position {
     }
 
     return .{
-        .row = try std.fmt.parseInt(u16, row[0..ridx], 10) - 1,
-        .col = try std.fmt.parseInt(u16, col[0..cidx], 10) - 1,
+        .x = try std.fmt.parseInt(u16, col[0..cidx], 10) - 1,
+        .y = try std.fmt.parseInt(u16, row[0..ridx], 10) - 1,
     };
 }
 
@@ -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 {
-    var termios = try std.posix.tcgetattr(std.posix.STDIN_FILENO);
+pub fn enableRawMode(bak: *posix.termios) !void {
+    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(std.posix.V.TIME)] = 0;
+    termios.cc[@intFromEnum(posix.V.MIN)] = 1;
+    termios.cc[@intFromEnum(posix.V.TIME)] = 0;
 
-    try std.posix.tcsetattr(
-        std.posix.STDIN_FILENO,
+    try posix.tcsetattr(
+        posix.STDIN_FILENO,
         .FLUSH,
         termios,
     );
 }
 
 /// Reverts `enableRawMode` to restore initial functionality.
-pub fn disableRawMode(bak: *std.posix.termios) !void {
-    try std.posix.tcsetattr(
-        std.posix.STDIN_FILENO,
+pub fn disableRawMode(bak: *posix.termios) !void {
+    try posix.tcsetattr(
+        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);
-    if (!std.mem.eql(u8, buf[0..len], "\x1b[?2026;") or len < 9) {
+    const len = try posix.read(posix.STDIN_FILENO, &buf);
+    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

@@ -0,0 +1,199 @@
+//! Testing namespace for `zterm` to provide testing capabilities for `Containers`, `Event` handling, `App`s and `Element` implementations.
+
+/// Single-buffer test rendering pipeline for testing purposes.
+pub const Renderer = struct {
+    allocator: Allocator,
+    size: Point,
+    screen: []Cell,
+
+    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, .{});
+
+        return .{
+            .allocator = allocator,
+            .size = size,
+            .screen = screen,
+        };
+    }
+
+    pub fn deinit(this: *@This()) void {
+        this.allocator.free(this.screen);
+    }
+
+    pub fn resize(this: *@This(), size: Point) !void {
+        this.size = size;
+        const n = @as(usize, size.x) * @as(usize, size.y);
+
+        this.allocator.free(this.screen);
+        this.screen = this.allocator.alloc(Cell, n) catch @panic("testing.zig: Out of memory.");
+        @memset(this.screen, .{});
+    }
+
+    pub fn clear(this: *@This()) !void {
+        @memset(this.screen, .{});
+    }
+
+    pub fn render(this: *@This(), comptime T: type, container: *const T) !void {
+        const size: Point = container.size;
+        const origin: Point = container.origin;
+        const cells: []const Cell = try container.content();
+
+        if (cells.len == 0) return;
+
+        var idx: usize = 0;
+        const anchor = (@as(usize, origin.y) * @as(usize, this.size.x)) + @as(usize, origin.x);
+
+        blk: for (0..size.y) |row| {
+            for (0..size.x) |col| {
+                const cell = cells[idx];
+                idx += 1;
+
+                this.screen[anchor + (row * this.size.x) + col].style = cell.style;
+                this.screen[anchor + (row * this.size.x) + col].cp = cell.cp;
+
+                if (cells.len == idx) break :blk;
+            }
+        }
+        // free immediately
+        container.allocator.free(cells);
+
+        for (container.elements.items) |*element| try this.render(T, element);
+    }
+
+    pub fn save(this: @This(), writer: anytype) !void {
+        try std.zon.stringify.serialize(this.screen, .{ .whitespace = false }, writer);
+    }
+};
+
+/// This function is intended to be used only in tests. Test if a `Container`'s
+/// rendered contents are equal to the expected `Cell` slice.
+///
+/// # Test data creation
+///
+/// Create a .zon file containing the expected `Cell` slice using the `zterm.testing.Renderer.save` method:
+///
+/// ```zig
+/// const file = try std.fs.cwd().createFile("test/container/border/all.zon", .{ .truncate = true });
+/// defer file.close();
+///
+/// const allocator = std.testing.allocator;
+/// var renderer: testing.Renderer = .init(allocator, size);
+/// defer renderer.deinit();
+///
+/// try container.handle(.{ .size = size });
+/// try renderer.render(Container(event.SystemEvent), &container);
+/// try renderer.save(file.writer());
+/// ```
+///
+/// # Testing against created data
+///
+/// Then later load that .zon file at compile time and run your test against this `Cell` slice.
+///
+/// ```zig
+/// var container: Container(event.SystemEvent) = try .init(std.testing.allocator, .{
+///     .border = .{
+///         .color = .green,
+///         .sides = .all,
+///     },
+/// }, .{});
+/// defer container.deinit();
+///
+/// try testing.expectContainerScreen(.{
+///     .rows = 20,
+///     .cols = 30,
+/// }, &container, @import("test/container/border.all.zon"));
+/// ```
+pub fn expectContainerScreen(size: Point, container: *Container(event.SystemEvent), expected: []const Cell) !void {
+    const allocator = testing.allocator;
+    var renderer: Renderer = .init(allocator, size);
+    defer renderer.deinit();
+
+    container.resize(size);
+    container.reposition(.{});
+    try renderer.render(Container(event.SystemEvent), container);
+
+    try expectEqualCells(.{}, renderer.size, expected, renderer.screen);
+}
+
+/// This function is intended to be used only in tests. Test if the two
+/// provided cell arrays are identical. Usually the `Cell` slices are
+/// 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 = testing.allocator;
+
+    try testing.expectEqual(expected.len, actual.len);
+    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();
+
+    var actual_cps = try std.ArrayList(Cell).initCapacity(allocator, size.x);
+    defer actual_cps.deinit();
+
+    var output = try std.ArrayList(u8).initCapacity(allocator, expected_cps.capacity * actual_cps.capacity + 5 * size.y);
+    defer output.deinit();
+
+    var buffer = std.io.bufferedWriter(output.writer());
+    defer buffer.flush() catch {};
+
+    const writer = buffer.writer();
+    var differ = false;
+
+    const dwd = try DisplayWidth.DisplayWidthData.init(allocator);
+    defer dwd.deinit();
+    const dw: DisplayWidth = .{ .data = &dwd };
+
+    const expected_centered = try dw.center(allocator, "Expected Screen", size.x, " ");
+    defer allocator.free(expected_centered);
+
+    const actual_centered = try dw.center(allocator, "Actual Screen", size.x, " ");
+    defer allocator.free(actual_centered);
+
+    try writer.print("Screens are not equivalent.\n{s} ┆ {s}\n", .{ expected_centered, actual_centered });
+
+    for (origin.y..size.y) |row| {
+        defer {
+            expected_cps.clearRetainingCapacity();
+            actual_cps.clearRetainingCapacity();
+        }
+        for (origin.x..size.x) |col| {
+            const expected_cell = expected[(row * size.x) + col];
+            const actual_cell = actual[(row * size.x) + col];
+
+            if (!expected_cell.eql(actual_cell)) differ = true;
+
+            try expected_cps.append(expected_cell);
+            try actual_cps.append(actual_cell);
+        }
+
+        // write screens both formatted to buffer
+        for (expected_cps.items) |cell| try cell.value(writer);
+        _ = try writer.write(" ┆ ");
+        for (actual_cps.items) |cell| try cell.value(writer);
+        _ = try writer.write("\n");
+    }
+
+    if (!differ) return;
+
+    // test failed
+    try buffer.flush();
+
+    debug.lockStdErr();
+    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;