From 14de2dd0b2e4a9c9f8904995811f3fe8c41b36fb Mon Sep 17 00:00:00 2001
From: Aleksander <aleksander@oo8.dev>
Date: Sun, 17 Aug 2025 22:00:19 +0200
Subject: [PATCH] Update documentation

---
 wgui/doc/widgets.md | 302 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 263 insertions(+), 39 deletions(-)

diff --git a/wgui/doc/widgets.md b/wgui/doc/widgets.md
index b6682cf..a8cf138 100644
--- a/wgui/doc/widgets.md
+++ b/wgui/doc/widgets.md
@@ -1,79 +1,115 @@
+# Quick jump
+
+## [Widgets](#widgets)
+
+[div](#div-widget), [label](#label-widget), [rectangle](#rectangle-widget), [sprite](#sprite-widget)
+
+## [Built-in components](#components)
+
+[Button](#button-component), [Slider](#slider-component), [CheckBox](#checkbox-component)
+
+## [Examples](#examples)
+
+[Simple layout](#simple-layout)
+
+[Value substitution (themes)](#value-substitution-themes)
+
+[File inclusion](#file-inclusion)
+
+[Macros](#macros)
+
+[Templates](#templates)
+
 # Universal widget attributes
 
-`display`: flex | block | grid
+### They can be used in any widget/component
 
-`position`: absolute | relative
+`display`: "flex" | "block" | "grid"
 
-`flex_grow`: units (3)
+`position`: "absolute" | "relative"
 
-`flex_shrink`: units (3)
+`flex_grow`: **float**
 
-`gap`: units (42) or percent (42%)
+`flex_shrink`: **float**
 
-`flex_basis`: units (42) or percent (42%)
+`gap`: **float** | **percent**
 
-`justify_self`: center | end | flex_end | flex_start | start | stretch
+`flex_basis`: **float** | **percent**
 
-`justify_content`: center | end | flex_start | flex_end | space_around | space_between | space_evenly | start | stretch
+`justify_self`: "center" | "end" | "flex_end" | "flex_start" | "start" | "stretch"
 
-`flex_wrap`: wrap | no_wrap | wrap_reverse
+`justify_content`: "center" | "end" | "flex_start" | "flex_end" | "space_around" | "space_between" | "space_evenly" | "start" | "stretch"
 
-`flex_direction`: row | column | column_reverse | row_reverse,
+`flex_wrap`: "wrap" | "no_wrap" | "wrap_reverse"
 
-`align_items`, `align_self`: baseline | center | end | flex_start | flex_end | start | stretch
+`flex_direction`: "row" | "column" | "column_reverse" | "row_reverse"
 
-`box_sizing`: border_box | content_box
+`align_items`, `align_self`: "baseline" | "center" | "end" | "flex_start" | "flex_end" | "start" | "stretch"
 
-`margin`, `margin_left`, `margin_right`, `margin_top`, `margin_bottom`: units (42) or percent (42%)
+`box_sizing`: "border_box" | "content_box"
 
-`padding`, `padding_left`, `padding_right`, `padding_top`, `padding_bottom`: units (42) or percent (42%)
+`margin`, `margin_left`, `margin_right`, `margin_top`, `margin_bottom`: **float** | **percent**
 
-`overflow`, `overflow_x`, `overflow_y`: hidden | visible | clip | scroll
+`padding`, `padding_left`, `padding_right`, `padding_top`, `padding_bottom`: **float** | **percent**
 
-`min_width`, `min_height`: units (42) or percent (42%)
+`overflow`, `overflow_x`, `overflow_y`: "hidden" | "visible" | "clip" | "scroll"
 
-`max_width`, `max_height`: units (42) or percent (42%)
+`min_width`, `min_height`: **float** | **percent**
 
-`width`, `height`: units (42) or percent (42%)
+`max_width`, `max_height`: **float** | **percent**
+
+`width`, `height`: **float** | **percent**
 
 # Widgets
 
-### `div`
+## div widget
 
-The most simple element
+`<div>`
+
+### The most simple element
 
 #### Parameters
 
-None
+_None_
 
 ---
 
-### `label`
+## label widget
 
-Text element
+`<label>`
+
+### A simple text element
 
 #### Parameters
 
-`text`: abc
+`text`: **string**
+
+_Simple text_
+
+`translation`: **string**
+
+_Translated by key_
+
+`size`: **float** (default: 14)
+
+_Text size in pixel units_
 
 `color`: #FFAABB | #FFAABBCC
 
-`align`: left | right | center | justified | end
+`align`: "left" | "right" | "center" | "justified" | "end"
 
-`weight`: normal | bold
-
-`size`: _float_
+`weight`: "normal" | "bold"
 
 ---
 
-### `rectangle`
+## rectangle widget
 
-A styled rectangle
+`<rectangle>`
+
+### A styled rectangle
 
 #### Parameters
 
-`text`: abc
-
 `color`: #FFAABB | #FFAABBCC
 
 _1st gradient color_
@@ -82,24 +118,212 @@ _1st gradient color_
 
 _2nd gradient color_
 
-`gradient`: horizontal | vertical | radial | none
+`gradient`: "horizontal" | "vertical" | "radial" | "none"
 
-`round`: _float (0.0 - 1.0)_
+`round`: **float** (default: 0) | **percent** (0-100%)
 
-`border`: _float_
+`border`: **float**
 
 `border_color`: #FFAABB | #FFAABBCC
 
 ---
 
-### `sprite`
+## sprite widget
 
-Image widget, supports raster and svg vector
+`<sprite>`
+
+### Image widget, supports raster and svg vector
 
 #### Parameters
 
-`src`: Internal (assets) image path
+`src`: **string**
 
-`src_ext`: External image path
+_Internal (assets) image path_
+
+`src_ext`: **string**
+
+_External image path_
 
 ---
+
+# Components
+
+## Button component
+
+`<Button>`
+
+### A clickable, decorated button
+
+#### Parameters
+
+`text`: **string**
+
+_Simple text_
+
+`translation`: **string**
+
+_Translated by key_
+
+`round`: **float** (default: 4) | **percent** (0-100%)
+
+`color`: #FFAABB | #FFAABBCC
+
+`border_color`: #FFAABB | #FFAABBCC
+
+---
+
+## Slider component
+
+`<Slider>`
+
+### A simple slider.
+
+#### Parameters
+
+`min_value`: **float**
+
+`max_value`: **float**
+
+_Needs to be bigger than `min_value`_
+
+`value`: **float**
+
+_Initial slider value_
+
+---
+
+## Checkbox component
+
+`<CheckBox>`
+
+### A check-box with label.
+
+#### Parameters
+
+`text`: **string**
+
+_Simple text_
+
+`translation`: **string**
+
+_Translated by key_
+
+`box_size`: **float** (default: 24)
+
+`checked`: **int** (default: 0)
+
+---
+
+# Examples
+
+## Simple layout
+
+```xml
+<layout>
+  <elements>
+    <label text="Hello, world!"/>
+    <label translation="WELCOME.HELLO_WORLD" size="20" color="#FF0000"/>
+    <div gap="16" flex_direction="row">
+      <rectangle width="16" height="16" color="#FF0000"/>
+      <rectangle width="16" height="16" color="#00FF00"/>
+      <rectangle width="16" height="16" color="#0000FF"/>
+    </div>
+  </elements>
+</layout>
+```
+
+## Value substitution (themes)
+
+```xml
+<layout>
+  <theme>
+    <var key="hello" value="Hello, world!" />
+    <var key="text_color" value="#FF0000" />
+  </theme>
+
+  <elements>
+    <!-- "~hello" will be replaced to "Hello, world!" -->
+    <label text="~hello"/>
+    <!-- "~text_color" will be replaced to "#FF0000" -->
+    <label text="This text will be red" color="~text_color"/>
+  </elements>
+</layout>
+```
+
+## Macros
+
+```xml
+<layout>
+  <macro name="my_macro"
+    margin="4" min_width="100" min_height="100" flex_direction="row" gap="8"
+    align_items="center" justify_content="center"/>
+
+  <elements>
+    <!-- This div will have all attributes specified in "my_macro" -->
+    <div macro="my_macro">
+      <label text="hello, world!"/>
+    </div>
+  </elements>
+</layout>
+
+```
+
+## File inclusion
+
+theme.xml:
+
+```xml
+<layout>
+  <theme>
+    <var key="my_red" value="#FF0000" />
+    <var key="my_green" value="#00FF00" />
+    <var key="my_blue" value="#0000FF" />
+  </theme>
+</layout>
+```
+
+bar.xml:
+
+```xml
+<layout>
+  <elements>
+    <!-- utilize theme variables included in theme.xml -->
+    <rectangle width="16" height="16" color="~my_red"/>
+    <rectangle width="16" height="16" color="~my_green"/>
+    <rectangle width="16" height="16" color="~my_blue"/>
+  </elements>
+</layout>
+```
+
+main.xml:
+
+```xml
+<layout>
+  <!-- Include theme -->
+  <include src="theme.xml"/>
+
+  <elements>
+    <!-- Include as additional elements here -->
+    <include src="bar.xml"/>
+  </elements>
+</layout>
+```
+
+## Templates
+
+```xml
+<layout>
+  <!-- "title" attrib will be passed to every matching ${title} -->
+  <template name="DecoratedTitle">
+    <rectangle color="#FFFF00" padding="8" round="4" gap="4">
+      <label text="${title}"/>
+    </rectangle>
+  </template>
+
+  <elements>
+    <!-- "title" used here -->
+    <DecoratedTitle title="This is a title.">
+  </elements>
+</layout>
+
+```