tabula rasa

README.md

@@ -0,0 +1,53 @@
+# That's It!
+
+Minimal, cross-environment user interface framework.
+
+## Definitions
+
+### User interface
+
+A **user interface** is a program which, repeatedly:
+* **renders** information to be displayed to the user;
+* **handles** input from the user;
+thus interactively performing tasks until an exit condition is met.
+
+### Engine
+
+An **engine** is the underlying platform responsible for:
+* Displaying your program's `render`ed output to the user
+* Reading user input to be `handle`d by your program.
+
+For example, the `tui` engine is based on `crossterm`,
+a library for rendering text user interfaces.
+
+### Widget
+
+A **widget** is any struct that implements the `Input<E, I>` and `Output<E, O>` 
+traits for a given engine `E`. This enables it to act as a component of the
+user interface. Widgets may contain arbitrary state -- including other widgets.
+We provide a set of basic widgets that allow you to define standard hierarchical
+UI layouts. It's the implementor's responsibility to define
+`render` and `handle` behaviors for custom widgets.
+
+### Input
+
+**To respond to user input**, implement the trait `Input`.
+It has a single method, `handle`, which takes an input
+event, and returns an engine-specific value.
+
+In the case of the `tui` engine, the returned value is a
+`bool` corresponding to whether the input event was captured
+by the current widget. Returning `true` from `render` terminates
+the handling of the current event; returning `false` "bubbles" it
+to the parent widget.
+
+### Output
+
+**To display data to the user**, implement the trait `Output`.
+It has a single method, `render`, which takes a mutable instance
+of the engine, and returns and engine-specific value.
+
+In the case of the `tui` engine, the returned value is `[u16;2]`,
+corresponding to the size requested by the widget. This allows
+the layout components to implement dynamic, responsive layouts in the
+terminal.