Added readme and documentation in module.jai

bindings/jai/README.md

@@ -0,0 +1,116 @@
+### Jai Language Bindings
+
+This directory contains bindings for the [Jai](https://jai.community/t/overview-of-jai/128) programming language, as well as an example implementation of the Clay demo from the video in Jai.
+
+If you haven't taken a look at the [full documentation for clay](https://github.com/nicbarker/clay/blob/main/README.md), it's recommended that you take a look there first to familiarise yourself with the general concepts. This README is abbreviated and applies to using clay in Jai specifically.
+
+The **most notable difference** between the C API and the Jai bindings is the use of for statements to create the scope for declaring child elements. This is done using some [for_expansion](https://jai.community/t/loops/147) magic.
+When using the equivalent of the [Element Macros](https://github.com/nicbarker/clay/blob/main/README.md#element-macros):
+
+```C
+// C form of element macros
+// Parent element with 8px of padding
+CLAY(CLAY_LAYOUT({ .padding = 8 })) {
+    // Child element 1
+    CLAY_TEXT(CLAY_STRING("Hello World"), CLAY_TEXT_CONFIG({ .fontSize = 16 }));
+    // Child element 2 with red background
+    CLAY(CLAY_RECTANGLE({ .color = COLOR_RED })) {
+        // etc
+    }
+}
+```
+
+```Jai
+// Jai form of element macros
+// Parent element with 8px of padding
+for Clay.Element(Clay.Layout(.{padding = 8})) {
+	// Child element 1
+	Clay.Text("Hello World", Clay.TextConfig(.{fontSize = 16}));
+	// Child element 2 with red background
+	for Clay.Element(Clay.Rectangle(.{color = COLOR_RED})) {
+		// etc
+	}
+}
+```
+
+> [!WARNING]  
+> For now, the Jai and Odin bindings are missing the OnHover() and Hovered() functions.
+> You can you PointerOver instead, an example of that is in `examples/introducing_clay_video_demo`.
+
+### Quick Start
+
+1. Download the clay-jai directory and copy it into your modules folder.
+
+```Jai
+Clay :: #import "clay-jai";
+```
+
+1. Ask clay for how much static memory it needs using [Clay.MinMemorySize()](https://github.com/nicbarker/clay/blob/main/README.md#clay_minmemorysize), create an Arena for it to use with [Clay.CreateArenaWithCapacityAndMemory()](https://github.com/nicbarker/clay/blob/main/README.md#clay_createarenawithcapacityandmemory), and initialize it with [Clay.Initialize()](https://github.com/nicbarker/clay/blob/main/README.md#clay_initialize).
+
+```Jai
+clay_required_memory := Clay.MinMemorySize();
+memory := alloc(clay_required_memory);
+clay_memory := Clay.CreateArenaWithCapacityAndMemory(clay_required_memory, memory);
+Clay.Initialize(
+	clay_memory, 
+	Clay.Dimensions.{cast(float, GetScreenWidth()), cast(float, GetScreenHeight())},
+	.{handle_clay_errors, 0}
+);
+``` 
+
+3. Provide a `measure_text(text, config)` proc marked with `#c_call` with [Clay.SetMeasureTextFunction(function)](https://github.com/nicbarker/clay/blob/main/README.md#clay_setmeasuretextfunction) so that clay can measure and wrap text.
+
+```Jai
+// Example measure text function
+measure_text :: (text: *Clay.String, config: *Clay.TextElementConfig) -> Clay.Dimensions #c_call {
+}
+
+// Tell clay how to measure text
+Clay.SetMeasureTextFunction(measure_text)
+``` 
+
+4. **Optional** - Call [Clay.SetPointerPosition(pointerPosition)](https://github.com/nicbarker/clay/blob/main/README.md#clay_setpointerposition) if you want to use mouse interactions.
+
+```Jai
+// Update internal pointer position for handling mouseover / click / touch events
+Clay.SetPointerPosition(.{ mousePositionX, mousePositionY })
+```
+
+5. Call [Clay.BeginLayout(screenWidth, screenHeight)](https://github.com/nicbarker/clay/blob/main/README.md#clay_beginlayout) and declare your layout using the provided macros.
+
+```Jai
+// An example function to begin the "root" of your layout tree
+CreateLayout :: () -> Clay.RenderCommandArray {
+	Clay.BeginLayout(windowWidth, windowHeight);
+
+	for Clay.Element(
+		Clay.ID("OuterContainer"),
+		Clay.Layout(.{
+			sizing = .{Clay.SizingGrow(), Clay.SizingGrow()},
+			padding = .{16, 16},
+			childGap = 16
+		}),
+		Clay.Rectangle(.{color = .{250, 250, 255, 255}}),
+	) {
+		// ...
+	}
+}
+```
+
+1. Call [Clay.EndLayout()](https://github.com/nicbarker/clay/blob/main/README.md#clay_endlayout) and process the resulting [Clay.RenderCommandArray](https://github.com/nicbarker/clay/blob/main/README.md#clay_rendercommandarray) in your choice of renderer.
+
+```Jai
+render_commands: Clay.RenderCommandArray = Clay.EndLayout();
+
+for 0..render_commands.length - 1 {
+	render_command := Clay.RenderCommandArray_Get(*render_commands, cast(s32) it);
+
+	if #complete render_command.commandType == {
+	case .RECTANGLE;
+		DrawRectangle(render_command.boundingBox, render_command.config.rectangleElementConfig.color)
+	// ... Implement handling of other command types
+	}
+}
+```
+
+Please see the [full C documentation for clay](https://github.com/nicbarker/clay/blob/main/README.md) for API details. All public C functions and Macros have Jai binding equivalents, generally of the form `CLAY_RECTANGLE` (C) -> `Clay.Rectangle` (Jai)

bindings/jai/clay-jai/module.jai

@@ -1,4 +1,75 @@
-// TODO Documentation about the for_expansion
+/*
+These bindings adapt the CLAY macro using some for_expansion trickery, allowing a syntax similar to the one in the Odin bindings. 
+I'll try to explain here why I did it that way.
+
+In Odin, they can mark the procedure with deferred_none, allowing to call a proc after the current one, which works well with ifs.
+
+@(require_results, deferred_none = _CloseElement)
+UI :: proc(configs: ..TypedConfig) -> bool {}
+
+You can then use it like so : 
+
+if UI(Layout(), etc..) {Children ...}
+
+So I tried to replicate this in Jai. The first thing I did was to try making a macro returning a bool with a backticked defer in it.
+
+UI :: (configs: ..TypedConfig) -> bool #must #expand {
+    `defer EndElement();
+    return true;
+}
+
+But this doesn't work if you have two elements side to side, as the end of the first element will be called after the start and the end of the second one.
+
+Another option used in these bindings : https://github.com/nick-celestin-zizic/clay-jai is to have that defer like above and have the macro return nothing. You can then use it like that : 
+
+{ UI(Layout()); Children(); }
+
+But I'm not a big fan of that since it's possible to forget the scope braces or to put the children before the element.
+
+Another option to consider is to pass a code block to a macro that puts it between the start and the end.
+
+UI :: (id: ElementId, layout: LayoutConfig, configs: ..ElementConfig, $code: Code) {
+    OpenElement();
+    ...
+    #insert code;
+    CloseElement();
+}
+
+UI(..., #code {
+    Children();
+});
+
+However this prevents to refer to variables from the previous scope, and it's also a bit akward to type.
+
+The final solution I found, inspired by the fact that CLAY uses a for loop behind the scene, was to use Jai's for_expansions.
+Here is how it works :
+
+InternalElementConfigArray :: struct {
+    configs: [] TypedConfig;
+}
+
+Element :: (configs: ..TypedConfig) -> InternalElementConfigArray #expand {
+    return .{configs};
+}
+
+for_expansion :: (configs_array: InternalElementConfigArray, body: Code, _: For_Flags) #expand {
+    Jai forces the definition of these
+    `it_index := 0;
+    `it := 0;
+    _OpenElement();
+    ...
+    #insert body;
+    _CloseElement();
+}
+
+As you can see it's kinda similar to the previous one, but doesn't have the limitation on refering to variable from the calling scope.
+Element builds an InternalElementConfigArray that has an array to the TypedConfigs, which will be passed to the for_expansion when placed after a for (this is a Jai feature).
+This then allows to write something like :
+
+for Element(Layout()) { Children(); }
+
+With the downside that it's not obvious why the for is there before reading the documentation.
+*/
 
 Vector2 :: Math.Vector2;
 

bindings/jai/examples/introducing_clay_video_demo/main.jai

@@ -30,17 +30,6 @@ to_jai_string :: (str: Clay.String) -> string {
     return .{data = str.chars, count = cast(s64, str.length)};
 }
 
-// handle_sidebar_interaction :: (
-//     element_id: Clay.ElementId,
-//     pointer_data: Clay.PointerData,
-//     user_data: s64
-// ) #c_call {
-//     // If this button was clicked
-//     if pointer_data.state == .PRESSED_THIS_FRAME {
-//         selected_document_index = user_data;
-//     }
-// }
-
 handle_clay_errors :: (error_data: Clay.ErrorData) #c_call {
     push_context {
         log_error(
@@ -87,8 +76,8 @@ main :: () {
     raylib_initialize(1024, 768, "Introducing Clay Demo", flags);
 
     clay_required_memory := Clay.MinMemorySize();
-    memory := NewArray(clay_required_memory, u8);
-    clay_memory := Clay.CreateArenaWithCapacityAndMemory(clay_required_memory, memory.data);
+    memory := alloc(clay_required_memory);
+    clay_memory := Clay.CreateArenaWithCapacityAndMemory(clay_required_memory, memory);
     Clay.Initialize(
         clay_memory, 
         Clay.Dimensions.{cast(float, Raylib.GetScreenWidth()), cast(float, Raylib.GetScreenHeight())},