diff --git a/.helix/languages.toml b/.helix/languages.toml new file mode 100644 index 0000000..09ca16b --- /dev/null +++ b/.helix/languages.toml @@ -0,0 +1,6 @@ +[[language]] +name = "markdown" +scope = "source.md" +file-types = ["markdown", "md"] +text-width = 100 +soft-wrap.wrap-at-text-width = true diff --git a/Built-in Layouts.-.md b/Built-in Layouts.-.md deleted file mode 100644 index e448ed8..0000000 --- a/Built-in Layouts.-.md +++ /dev/null @@ -1,42 +0,0 @@ -`App.Layout` serve several different purposes. They provide one or multiple of the following features for contained elements (`Layout`'s and/or `Widget`'s): - -- structuring -- decorating - -The following Layouts are provided by `zterm`: - -- `VContainer` -- `VStack` -- `HContainer` -- `HStack` -- `Padding` -- `Margin` -- `Framing` - -# VContainer - -Vertical container for sized elements. - -# VStack - -Vertical stacking of contained elements. Essentially a `VContainer` where every element has equivalent size. - -# HContainer - -Horizontal container for sized elements. - -# HStack - -Horizontal stacking of contained elements. Essentially a `HContainer` where every element has equivalent size. - -# Padding - -Provide absolute padding for the contained single element. - -# Margin - -Provide relative (percentual) margins for the contained single element. - -# Framing - -Provide a frame (stylable through configuration parameter) for the contained single element. diff --git a/Built-in Widgets.-.md b/Built-in Widgets.-.md deleted file mode 100644 index 9b5c67d..0000000 --- a/Built-in Widgets.-.md +++ /dev/null @@ -1,19 +0,0 @@ -`Widget`'s provide an isolated struct which provides the contents to display in the provided `Size` on the terminal. Each `Widget` can control how and when to update their displayed contents. - -The following `Widget`'s are provided by `zterm`: - -- `Text` -- `RawText` -- `Spacer` - -# Text - -Static display of provided `Cell` array, which allows for styling (e.g. coloring of text, decoration of text, etc.) of displayed contents. - -# RawText - -Pager `Widget` for the provided file. Mainly used for Debugging purposes. - -# Spacer - -Empty `Widget` that is supposed to remain empty and serve as a placeholder for corresponding areas of the terminal screen. diff --git a/Design.md b/Design.md new file mode 100644 index 0000000..bb41457 --- /dev/null +++ b/Design.md @@ -0,0 +1,26 @@ +## 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](https://en.wikipedia.org/wiki/Immediate_mode_(computer_graphics)), a render loop is also completed at the end of a single event loop. Such that every time an event happens a render call will usually be done as well. However this is not strickly necessary forced by *zterm* and can be separated to have a fixed rendering of every 16ms (i.e. for 60 fps), etc. + +> [!NOTE] +> All examples are implemented as *intermediate mode* rendered applications. + +There is only one generic `Container` which includes properties, child container and optionally an `Element`. In the end a `Container` describes a tree structure containing layout and content. + +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). + +> [!CAUTION] +> There are no built-in components to provide complex behavior. + +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. + +> [!TIPS] +> Keep the tagged type of each user event as small as possible. If you need access to bigger structs you can also aways use pointers. + +This library 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 - some events usually don't cause a draw (i.e. `.init` or your own if you want them not to). Even though each frame is regenerated from scratch each render loop, the corresponding application is still pretty performant as the renderer uses a *double buffered* implementation to only apply the changes from each frame to the next to the screen. + +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. + +--- +1. [clay - High performance UI layout library in C | Github](https://github.com/nicbarker/clay) +2. [clay layout library | YouTube](https://www.youtube.com/watch?v=DYWTw19_8r4) diff --git a/Elements.md b/Elements.md new file mode 100644 index 0000000..bf475ca --- /dev/null +++ b/Elements.md @@ -0,0 +1,13 @@ +## [TODO] Elements + +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. + +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 + +### Advanced usage diff --git a/Examples.md b/Examples.md new file mode 100644 index 0000000..8db3c8e --- /dev/null +++ b/Examples.md @@ -0,0 +1,28 @@ +## Examples + +You can build the every example through the example option. For example: + +```sh +zig build --release=safe -Dexample=demo run +``` + +> [!NOTE] +> In debug build mode log messages will be written to stderr. You can pipe the output of stderr to a file when running in debug mode to not disturb the tui rendering. e.g. `zig build run 2> log` + +For all available examples run `zig build --help` + +> [!TIP] +> Every example application can be quit using `ctrl+c`. + +The examples are structured in four categories: + +- Overall examples: + i.e. Error handling, Demo application, .. +- Elements: + i.e. Button, Input, Scrollable, .. +- Layouts: + i.e. Vertical, Horizontal, Grid, Mixed, .. +- Styles: + i.e. Color palette, Text styles, .. + +They serve to provide examples on how to use the library as well as showcase the capabilities of the library. For the implementation source files see [examples](https://gitea.yves-biener.de/yves-biener/zterm/src/branch/main/examples). diff --git a/Home.md b/Home.md index 9cc9528..24646d7 100644 --- a/Home.md +++ b/Home.md @@ -1,7 +1,6 @@ -Welcome to the Wiki Documentation for **zterm**. +# Welcome to the Wiki Documentation for *zterm* -This wiki contains documentation about the built-in `App.Layout`'s and `App.Widget`'s and how to write own `Layout` and `Widget` types. +This wiki contains documentation about the design goals, implementation details and the usage of the **zterm** library. -For example implementations see [examples](https://gitea.yves-biener.de/yves-biener/zterm/src/branch/main/examples). - -You can clone this repository and run `zig build --release=fast` to build the example applications in release mode and run them to test them out on your machine. +> [!NOTE] +> Use the link tree on the right to navigate to the sections that you are interested in. It is recommended to read the **Design** first to get a broughter understanding of the concept of the library before jumping into examples. diff --git a/Roadmap.md b/Roadmap.md new file mode 100644 index 0000000..cf60795 --- /dev/null +++ b/Roadmap.md @@ -0,0 +1,77 @@ +## Roadmap + +The following list contains goals for certain features the library supports or is planned on supporting. + +- [ ] 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 + - [x] Error Handling + - log and show error's without crashing the application + - [ ] Demo + - [x] use another tui application to launch and come back to (showcase the interrupt behavior) + - [x] Launch sub-applications (not inside of a `Container` but during the application workflow, like an editor) + - [ ] implement some functionality to have it be more like a working demo application +- [ ] 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 diff --git a/Testing.md b/Testing.md new file mode 100644 index 0000000..d18c15d --- /dev/null +++ b/Testing.md @@ -0,0 +1,5 @@ +## [TODO] Testing + +Using a different testing renderer (in a corresponding namespace `zterm.testing`) renderes without flushing to the screen, but keeps the corresponding `zterm.Cell` slice for comparison. The main question would rather be how to provide the expected value for the `zterm.Cell` slice. + +The test renderer shall be configured with a given size (as the corresponding terminal for the screen size will not be available). This serves two aspects: Firstly, `.resize` Event triggering and secondly, the rendering into a `zterm.Cell` slice with the provided size dimensions (for testing layout handling and rendering (i.e. of a scrollable element, etc.)).