From 600846a92b782263040185c3725443cbebebcc31 Mon Sep 17 00:00:00 2001 From: Yves Biener Date: Sun, 26 Oct 2025 17:42:38 +0100 Subject: [PATCH] doc(architecture): Elm architecture and short introduction into the architecture of zterm --- Architecture.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++ Roadmap.md | 1 + 2 files changed, 88 insertions(+) create mode 100644 Architecture.md diff --git a/Architecture.md b/Architecture.md new file mode 100644 index 0000000..9f37117 --- /dev/null +++ b/Architecture.md @@ -0,0 +1,87 @@ +## Architecture + +The overall design of *zterm* describes an [Elm Archictecture](https://guide.elm-lang.org/architecture/). The following listing, a rough mapping between the *Elm* components and the corresponding is given: + +- **Model** -- `App.Model` +- **View** -- `Container` and `Element` +- **Update** -- `App.Event` + +## Structural Composition + +``` +┌─────────────┐ ┌───────────┐ ┌──────────────────────┐ +│App │ │ <> │ │Container │ +├─────────────┤ │ Queue │ ├──────────────────────┤ +│+model: Model│ ├───────────┤ │+children: [Container]│ +│-queue: Queue│ └───────────┘ │+element: Element │ +└─────────────┘ └──────────────────────┘ +┌─────────────┐ ┌─────┐ +│Element │ │Model│ +├─────────────┤ ├─────┤ +│+resize() │ └─────┘ +│+reposition()│ ┌─────┐ +│+handle() │ │Event│ +│+content() │ ├─────┤ +└─────────────┘ └─────┘ +``` + +## General Loop + +The following sequence diagrams shows the general approach for the event and rendering loop: + +``` + ┌────┐ ┌────────┐ ┌───┐ ┌─────────┐ ┌───────┐ + │Main│ │Renderer│ │App│ │Container│ │Element│ + └──┬─┘ └────┬───┘ └─┬─┘ └────┬────┘ └───┬───┘ + │ │ │ │ │ +╔═══════╤════╪════════════════════════════╪═════════════════╪═════════════════╪══════════════════════════════╪═════════════╗ +║ LOOP │ quit event │ │ │ │ ║ +╟───────┘ │ │ │ │ │ ║ +║ │ Get next `Event` │ │ │ ║ +║ │─────────────────────────────────────────────>│ │ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ handle `Event` │ │ ║ +║ │ │ │────────────────>│ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │────┐ │ ║ +║ │ │ │ │ │ handle sub-`Container`s │ ║ +║ │ │ │ │<───┘ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ handle `Event` │ ║ +║ │ │ │ │─────────────────────────────>│ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │<─────────────────────────────│ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │<────────────────│ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ │ ║ +║ │<─────────────────────────────────────────────│ │ │ ║ +║ │ │ │ │ │ ║ +║ │Render the root `Container` │ │ │ │ ║ +║ │───────────────────────────>│ │ │ │ ║ +║ │ │ │ │ │ ║ +║ │ │ request `content` │ │ ║ +║ │ │──────────────────────────────────>│ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │────┐ │ ║ +║ │ │ │ │ │ render sub-`Container` │ ║ +║ │ │ │ │<───┘ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ render `content` │ ║ +║ │ │ │ │─────────────────────────────>│ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │<─────────────────────────────│ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ │ ║ +║ │ │<──────────────────────────────────│ │ ║ +║ │ │ │ │ │ ║ +║ │ │ │ │ │ ║ +║ │<───────────────────────────│ │ │ │ ║ +╚════════════╪════════════════════════════╪═════════════════╪═════════════════╪══════════════════════════════╪═════════════╝ + ┌──┴─┐ ┌────┴───┐ ┌─┴─┐ ┌────┴────┐ ┌───┴───┐ + │Main│ │Renderer│ │App│ │Container│ │Element│ + └────┘ └────────┘ └───┘ └─────────┘ └───────┘ +``` diff --git a/Roadmap.md b/Roadmap.md index 4d6c1c7..5148d72 100644 --- a/Roadmap.md +++ b/Roadmap.md @@ -17,6 +17,7 @@ The following list contains goals for certain features the library supports or i - Limit where Focus is actually necessary (and skip those accordingly) - Enhance the rendering to make it obvious where the focus is currently at +- [x] Elm architecture support (through user defined `struct` acting as the *Model*) - [ ] Container rendering - [x] Layout - [x] direction