### Basic Layout with Modifiers

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates chaining various modifiers to define the layout of UI components within a window. This example showcases `fillWidth`, `fillHeight`, `alignBoth`, `alignHorizontal`, and `fillParent`.

```kotlin
val halfWidth = Modifier.fillWidth(fraction = 0.5f, padding = 1.5f).fillHeight()
window.layout {
    wrapper(Modifier.fillParent()) {
        content(Modifier.alignBoth(Alignment.Center).fillParent(padding = 1f)) {
            left(Modifier.alignHorizontal(Alignment.Start).then(halfWidth)) {
                leftText(Modifier.alignBoth(Alignment.Center))
            }
            right(Modifier.alignHorizontal(Alignment.End).then(halfWidth)) {
                top(Modifier.alignHorizontal(Alignment.Start).fillWidth().fillHeight(0.5f)) {
                    topText(Modifier.alignBoth(Alignment.Center))
                }
                bottom(Modifier.alignHorizontal(Alignment.End).fillWidth().fillHeight(0.5f)) {
                    bottomText(Modifier.alignBoth(Alignment.Center))
                }
            }
        }
    }
}
```

--------------------------------

### Start Microsoft Login

Source: https://github.com/sparkuniverse/essential-mod/blob/main/src/main/resources/assets/essential/account/login/microsoft.html

Initiates the Microsoft login process by redirecting the user to the Microsoft authentication page. Ensure the '{location}' placeholder is correctly replaced with the actual authentication URL.

```javascript
function start() { var width = screen.width; var height = screen.height; window.location = "{location}"; }
```

--------------------------------

### Elementa Layout DSL UI Code

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Example of the same UI screen implemented using the Elementa Layout DSL. This version simplifies the definition of parent-child relationships, making the layout structure more immediately apparent.

```kotlin
window.layout {
    wrapper {
        content {
            left {
                leftText()
            }
            right {
                top {
                    topText()
                }
                bottom {
                    bottomText()
                }
            }
        }
    }
}
```

--------------------------------

### Regular Elementa UI Code

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Example of a typical UI screen implemented using standard Elementa components and constraints. This code defines two side-by-side boxes with nested content, illustrating the verbosity and potential complexity of traditional Elementa layouts.

```kotlin
val window: Window = WindowScreen()

// This extra wrapper may seem redundant here, the reason we have it will become clear later
val wrapper by UIContainer().constrain {
    width = 100.percent
    height = 100.percent
} childOf window

val content by UIContainer().constrain {
    x = CenterConstraint()
    y = CenterConstraint()
    width = 100.percent - 2.pixels
    height = 100.percent - 2.pixels
} childOf wrapper

val left by UIContainer().constrain {
    width = 50.percent - 1.5.pixels
    height = 100.percent
} childOf content

val right by UIContainer().constrain {
    x = 0.pixels(alignOpposite = true)
    width = 50.percent - 1.5.pixels
    height = 100.percent
} childOf content

val leftText by UIText("Left").constrain {
    x = CenterConstraint()
    y = CenterConstraint()
} childOf left

val top by UIContainer().constrain {
    width = 100.percent
    height = 50.percent
} childOf right

val bottom by UIContainer().constrain {
    y = 0.pixels(alignOpposite = true)
    width = 100.percent
    height = 50.percent
} childOf right

val topText by UIText("Top").constrain {
    x = CenterConstraint()
    y = CenterConstraint()
} childOf top

val bottomText by UIText("Bottom").constrain {
    x = CenterConstraint()
    y = CenterConstraint()
} childOf bottom
```

--------------------------------

### Row with spacedBy Arrangement

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Configures a row to use a fixed spacing of 1 unit between its children, with the children positioned according to the default FloatPosition (Start).

```kotlin
row(Arrangement.spacedBy(1)) {
    box(Modifier.width(10))
    box(Modifier.width(10))
    box(Modifier.width(10))
}
```

--------------------------------

### Build All Essential Versions

Source: https://github.com/sparkuniverse/essential-mod/blob/main/README.md

Run this command to build all versions of the Essential Mod. The first build may take a significant amount of time.

```bash
./gradlew build
```

--------------------------------

### Basic Layout Structure with Box, Column, and Row

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Illustrates a basic UI layout using the Layout DSL, nesting a column within a box and rows within the column. This sets up a hierarchical arrangement of UI elements.

```kotlin
window.layout {
    box(Modifier.width(500).height(500)) {
        column {
            row {
                text("top left")
                text("top right")
            }
            text("*second row*")
        }
    }
}
```

--------------------------------

### Using `box` and `text` Helpers

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Illustrates the use of `box` and `text` helper functions to further shorten layout code by abstracting common component creation patterns.

```kotlin
// Because text and simple containers are quite common, there exist `box` and `text` methods which will create the
// components with the given modifiers.
box(Modifier.alignHorizontal(Alignment.End).fillWidth().fillHeight(0.5f)) {
    text("Bottom", modifier = Modifier.alignBoth(Alignment.Center))
}
```

--------------------------------

### Basic Box Layout with Alignment

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates creating a nested box layout with specific alignments and fractional sizing. Useful for complex UI structures where precise positioning is needed.

```kotlin
val halfWidth = Modifier.fillWidth(fraction = 0.5f, padding = 1.5f).fillHeight()
window.layout {
    box(Modifier.fillParent()) {
        box(Modifier.fillParent(padding = 1f)) {
            box(Modifier.alignHorizontal(Alignment.Start).then(halfWidth)) {
                text("Left")
            }
            box(Modifier.alignHorizontal(Alignment.End).then(halfWidth)) {
                box(Modifier.alignHorizontal(Alignment.Start).fillWidth().fillHeight(0.5f)) {
                    text("Top")
                }
                box(Modifier.alignHorizontal(Alignment.End).fillWidth().fillHeight(0.5f)) {
                    text("Bottom")
                }
            }
        }
    }
}
```

--------------------------------

### Build Essential Loader Container for Platform

Source: https://github.com/sparkuniverse/essential-mod/blob/main/README.md

Build the Essential Container for a specific platform. Replace <platform> with one of the supported platforms: fabric, launchwrapper, modlauncher8, or modlauncher9. The resulting jar file will be located in loader/container/<platform>/build/libs/.

```bash
./gradlew :loader:container:<platform>:build
```

--------------------------------

### Basic Row with Arrangement

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates a row with three equally sized children and surplus space, where the arrangement strategy is to be defined.

```kotlin
row(Modifier.width(38), arrangementGoesHere) {
    box(Modifier.width(10))
    box(Modifier.width(10))
    box(Modifier.width(10))
}
```

--------------------------------

### Using LayoutScope for Component Layout

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates how to use the `layout` extension function to define the layout of a component's children within a `LayoutScope`. Shows different ways to invoke child components and apply modifiers.

```kotlin
val myComponent = UIContainer()
val myChild = UIContainer()
val myInnerChild = UIContainer()

myComponent.layout(Modifier.width(100).height(20)) {
    // Adds `myChild` as a child of `myComponent`
    invoke(myChild)
    // Or, because it's actually an extension function on UIComponent, one could also call it like this:
    myChild.invoke()
    // The name may seem a bit odd, but that's because it's also an operator function,
    // so the normal way to call it is actually just:
    myChild()
    
    // This call may also receive a Modifier to be applied to the child as well as a block that opens another
    // `LayoutScope`, this time for the child:
    myChild(Modifier.fillParent()) {
        // Adds `myInnerChild` as a child of `myChild`
        myInnerChild()
    }
    
    // But `myChild` doesn't have to be declared in a variable outside, it could also be declared inline, though
    // this is usually discouraged if it's more than just a simple constructor call:
    UIContainer()()
    // Note the double `()`: the first one is the constructor `UIContainer` call, the second is the call to `invoke`
    // that adds it as a child and can receive a Modifier and a block that opens another layout scope.
}
```

--------------------------------

### Row with equalWeight Arrangement (Shrink)

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates how equalWeight can shrink children to a uniform size when a fixed spacing of 10f is provided, ensuring no surplus space remains.

```kotlin
Arrangement.equalWeight(10f)
```

--------------------------------

### Define and Use Class Component in Layout DSL

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Create a custom UI component by extending UIContainer and configuring its layout using the Layout DSL within its init block. Instances can be created and configured with modifiers.

```kotlin
class Button(label: String, onClick: () -> Unit) : UIContainer() {
    init {
        layout(Modifier.width(100f).height(20f).color(Palette.buttonOutlineColor).onLeftClick(onClick)) {
            box(Modifier.alignBoth(Alignment.Center).fillParent(padding = 1f).color(Palette.buttonBackgroundColor)) {
                text(label)
            }
        }
    }
}

window.layout {
    column(Arrangement. Arrangement.spacedBy(5f)) {
        row(Arrangement.spacedBy(3f)) {
            Button("Yes", ::accept)()
            Button("No", ::reject)()
        }
        Button("Cancel", ::cancel)(Modifier.width(30f).height(10f))
    }
}
```

--------------------------------

### Box Container with Sizing and Color Modifiers

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates using a box container to create a UI element with specific dimensions and a background color. It shows nesting boxes to achieve effects like an outlined button.

```kotlin
box(Modifier.width(100f).height(20f).color(outlineColor)) {
    box(Modifier.fillParent(padding = 1f).color(backgroundColor)) {
        text(label)
    }
}
```

--------------------------------

### Row and Column Layouts with Arrangement

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Illustrates using `row` and `column` for more structured layouts, incorporating `Arrangement` for spacing and `Alignment` for secondary axis positioning. Suitable for arranging elements horizontally or vertically with controlled spacing.

```kotlin
val halfWidth = Modifier.fillWidth(fraction = 0.5f, padding = 1.5f).fillHeight()
window.layout {
    box(Modifier.fillParent()) {
        row(Modifier.fillParent(padding = 1f), Arrangement.SpaceBetween) {
            box(halfWidth) {
                text("Left")
            }
            column(halfWidth) {
                box(Modifier.fillWidth().fillHeight(0.5f)) {
                    text("Top")
                }
                box(Modifier.fillWidth().fillHeight(0.5f)) {
                    text("Bottom")
                }
            }
        }
    }
}
```

--------------------------------

### Row with equalWeight Arrangement (Expand)

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Sets up a row where children are given equal width, expanding to fill all available space with a spacing of 1f.

```kotlin
Arrangement.equalWeight(1f)
```

--------------------------------

### Create a Custom Modifier Extension

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates creating a reusable custom modifier extension using the 'then' function. It shows how to modify component constraints and define a cleanup function.

```kotlin
fun Modifier.something() = this then {
    // The component is passed as the receiver, so you can simply call its methods
    val orgConstraint = constraints.x
    constrain {
        // Do keep in mind that modifiers are supposed to be re-usable, so you need to create a new constraint here
        // every time, you cannot for example re-use a single constraint passed via arguments.
        // That's why the BasicXModifier takes a constraint factory as its argument rather than a single constraint.
        x = 10.pixels
    }

    // And finally return a function that will clean up your change (or throw a NotImplementedError if your modifier
    // can/does not support that)
    {
        constrain {
            x = orgConstraint
        }
    }
}
```

--------------------------------

### Storing Layout Components in Variables

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Shows how to capture the UI components returned by layout functions into local variables for later reference. This is useful for accessing or manipulating specific parts of the UI tree.

```kotlin
val wrapper: UIComponent
val content: UIComponent
window.layout {
    wrapper = box(Modifier.width(500).height(500)) {
        content = column {
            // ...
        }
    }
}
```

--------------------------------

### Inlining Component Constructors

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Compares defining a layout component with explicit fields versus inlining its constructor. This shows how to simplify repetitive component creation.

```kotlin
// With fields:
bottom(Modifier.alignHorizontal(Alignment.End).fillWidth().fillHeight(0.5f)) {
    bottomText(Modifier.alignBoth(Alignment.Center))
}
// Constructors inlined:
UIComponent()(Modifier.alignHorizontal(Alignment.End).fillWidth().fillHeight(0.5f)) {
    UIText("Bottom")(Modifier.alignBoth(Alignment.Center))
}
```

--------------------------------

### Enabling Cache in forEach

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Enable caching for `forEach` to improve performance when dealing with a practically limited number of values, especially in scenarios like search.

```kotlin
val myListState = mutableListStateOf("a", "b", "c")
window.layout {
    forEach(myListState, cache = true) { myStr ->
        text(myStr)
    }
}
```

--------------------------------

### Conditional Rendering with if_

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Conditionally render components based on a boolean state. Supports caching of inactive components by default.

```kotlin
val myBoolState = mutableStateOf(true)
window.layout {
    text("Before")
    if_(myBoolState) {
        text("It's true!")
    } `else` {
        box(Modifier.color(Color.RED)) {
            text("Oh no")
        }
    }
    text("After")
}
```

--------------------------------

### Iterating Over Lists with forEach

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Render a variable number of components by iterating over a `ListState`. Manages scope disposal and insertion automatically. Caching is disabled by default.

```kotlin
val myListState = mutableListStateOf("a", "b", "c")
window.layout {
    forEach(myListState) { myStr ->
        text(myStr)
    }
}
```

--------------------------------

### Avoiding Spacer with SpacedBy

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Illustrates a pattern to avoid where spacers are used in conjunction with `Arrangement.spacedBy`, which can lead to confusion regarding the actual space applied.

```kotlin
row(Arrangement.spacedBy(1f)) {
    spacer(width = 6f)
    text("a")
    text("b")
    text("c")
    spacer(width = 1f)
}
```

--------------------------------

### Using Spacer for Horizontal Spacing

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Creates invisible components to take up a specific amount of horizontal space between other components.

```kotlin
row {
    spacer(width = 2f)
    text("Hello")
    spacer(width = 10f)
    text("World")
}
```

--------------------------------

### Build Specific Minecraft Version

Source: https://github.com/sparkuniverse/essential-mod/blob/main/README.md

Build the Essential Mod for a specific Minecraft version. Replace <version>-<loader> with the desired version and loader (e.g., 1.12.2-forge). Note that building non-main versions may require intermediate versions to be set up.

```bash
./gradlew :<version>-<loader>:build
```

--------------------------------

### Spacer for Non-Symmetrical Padding

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates using spacers to achieve non-symmetrical padding around a group of components, offering an alternative to nested boxes with explicit padding.

```kotlin
row {
    spacer(width = 7f)
    row(Arrangement.spacedBy(1f)) {
        text("a")
        text("b")
        text("c")
    }
    spacer(width = 2f)
}
```

```kotlin
row {
    spacer(width = 5f)
    box(Modifier.childBasedWidth(padding = 2f)) {
        row(Arrangement.spacedBy(1f)) {
            text("a")
            text("b")
            text("c")
        }
    }
}
```

--------------------------------

### Composing Modifiers with `then`

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Illustrates how to chain two `Modifier` instances together using the `then` method or the infix operator. The resulting modifier applies modifications sequentially.

```kotlin
modifierA.then(modifierB)
modifierA then modifierB
```

--------------------------------

### Box Hover Effects

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Demonstrates changing a box's color when hovered using `whenHovered` and `hoverColor` modifiers.

```kotlin
box(Modifier.whenHovered(Modifier.color(Color.RED), Modifier.color(Color.BLACK)).then(size))
```

```kotlin
box(Modifier.color(Color.Black).whenHovered(Modifier.color(Color.RED)).then(size))
```

```kotlin
box(Modifier.color(Color.Black).hoverColor(Color.RED).then(size))
```

--------------------------------

### Define a Custom Modifier

Source: https://github.com/sparkuniverse/essential-mod/blob/main/elementa/layoutdsl/src/main/kotlin/gg/essential/gui/layoutdsl/README.md

Shows how to define a custom modifier by implementing the Modifier interface. This includes applying a change to a component and returning a function to undo the change.

```kotlin
interface Modifier {
    fun applyToComponent(component: UIComponent): () -> Unit
}
```