docs: flex

plugins/ui/docs/components/flex.md

@@ -0,0 +1,254 @@
+# Flex
+A flexbox-based layout container that utilizes Spectrum dimension values and supports the gap property for consistent spacing between items.
+
+## Example
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def flex():
+    return ui.flex(
+        ui.view(background_color="red", height="size-800", width="size-800"),
+        ui.view(background_color="green", height="size-800", width="size-800"),
+        ui.view(background_color="yellow", height="size-800", width="size-800"),
+    )
+
+
+my_flex = flex()
+```
+
+## Direction
+
+The `direction` prop determines the direction in which the flex items are laid out.
+
+Options:
+- `row` (default): the flex items are arranged horizontally from left to right.
+- `column`: the flex items are arranged vertically from top to bottom.
+- `row-reverse`: the flex items are arranged horizontally from right to left.
+- `column-reverse`: the flex items are arranged vertically from bottom to top.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def flex():
+    return [
+        ui.flex(
+            ui.view(background_color="red", height="size-800", width="size-800"),
+            ui.view(background_color="green", height="size-800", width="size-800"),
+            ui.view(background_color="yellow", height="size-800", width="size-800"),
+        ),
+        ui.flex(
+            ui.view(background_color="red", height="size-800", width="size-800"),
+            ui.view(background_color="green", height="size-800", width="size-800"),
+            ui.view(background_color="yellow", height="size-800", width="size-800"),
+            direction="row-reverse",
+        ),
+        ui.flex(
+            ui.view(background_color="red", height="size-800", width="size-800"),
+            ui.view(background_color="green", height="size-800", width="size-800"),
+            ui.view(background_color="yellow", height="size-800", width="size-800"),
+            direction="column",
+        ),
+        ui.flex(
+            ui.view(background_color="red", height="size-800", width="size-800"),
+            ui.view(background_color="green", height="size-800", width="size-800"),
+            ui.view(background_color="yellow", height="size-800", width="size-800"),
+            direction="column-reverse",
+        ),
+    ]
+
+
+my_flex = flex()
+```
+
+## Nesting
+
+Flexboxes can be nested to create more complicated layouts. By using the `flex` prop on the children, the flexbox can expand to fill the remaining space.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def flex():
+    return [
+        ui.flex(
+            ui.view(background_color="red", height="size-800"),
+            ui.flex(
+                ui.view(background_color="green", height="size-800", width="size-800"),
+                ui.view(background_color="blue", height="size-800", width="size-800"),
+            ),
+            direction="column",
+        ),
+    ]
+
+
+my_flex = flex()
+```
+
+
+## Wrapping
+
+When enabled, items that overflow wrap into the next row. Resize your browser window to see the items reflow.
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def flex():
+    return ui.flex(
+        ui.view(background_color="red", height="size-800", width="size-800"),
+        ui.view(background_color="green", height="size-800", width="size-800"),
+        ui.view(background_color="yellow", height="size-800", width="size-800"),
+        ui.view(background_color="blue", height="size-800", width="size-800"),
+        ui.view(background_color="orange", height="size-800", width="size-800"),
+        wrap=True,
+        width="200px",
+        align_content="start",
+    )
+
+
+my_flex = flex()
+```
+
+
+## Alignment
+
+The `alignItems` prop can align items along the cross-axis. When the direction is set to "column", it controls horizontal alignment, and when it is set to "row", it controls vertical alignment.
+
+Options:
+- `stretch` (default): the flex items are stretched to fill the container along the cross axis
+- `start`: the flex items are aligned at the start of the cross axis
+- `end`: the flex items are aligned at the end of the cross axis
+- `center`: the flex items are centered along the cross axis
+- `self-start`: the flex items are aligned at the start of their container
+- `self-end`: the flex items are aligned at the end of their container
+- `baseline`: the flex items are aligned based on their baselines
+- `first baseline`: the flex items are aligned based on the first baseline of the container
+- `last baseline`: the flex items are aligned based on the last baseline of the container
+- `safe center`: the flex items are centered along the cross axis, ensuring they remain within the safe area
+- `unsafe center`: the flex items are centered along the cross axis, without considering the safe area
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def flex():
+    vertical = ui.flex(
+        ui.flex(
+            ui.view(background_color="red", height="size-800", width="size-400"),
+            ui.view(background_color="green", height="size-800", width="size-800"),
+            ui.view(background_color="blue", height="size-800", width="size-200"),
+            direction="column",
+            align_items="start",
+        ),
+        ui.flex(
+            ui.view(background_color="red", height="size-800", width="size-400"),
+            ui.view(background_color="green", height="size-800", width="size-800"),
+            ui.view(background_color="blue", height="size-800", width="size-200"),
+            direction="column",
+            align_items="center",
+        ),
+        ui.flex(
+            ui.view(background_color="red", height="size-800", width="size-400"),
+            ui.view(background_color="green", height="size-800", width="size-800"),
+            ui.view(background_color="blue", height="size-800", width="size-200"),
+            direction="column",
+            align_items="end",
+        ),
+    )
+    horizontal = ui.flex(
+        ui.flex(
+            ui.view(background_color="red", width="size-800", height="size-400"),
+            ui.view(background_color="green", width="size-800", height="size-800"),
+            ui.view(background_color="blue", width="size-800", height="size-200"),
+            align_items="start",
+        ),
+        ui.flex(
+            ui.view(background_color="red", width="size-800", height="size-400"),
+            ui.view(background_color="green", width="size-800", height="size-800"),
+            ui.view(background_color="blue", width="size-800", height="size-200"),
+            align_items="center",
+        ),
+        ui.flex(
+            ui.view(background_color="red", width="size-800", height="size-400"),
+            ui.view(background_color="green", width="size-800", height="size-800"),
+            ui.view(background_color="blue", width="size-800", height="size-200"),
+            align_items="end",
+        ),
+        direction="column",
+    )
+
+    return ui.flex(vertical, horizontal)
+
+
+my_flex = flex()
+```
+
+
+## Justification
+
+The `justifyContent` prop aligns items along the main axis. For a "column" direction, it controls vertical alignment, and for a "row" direction, it controls horizontal alignment.
+
+Options:
+- `stretch` (default): the flex items are stretched to fill the container along the cross axis
+- `start`: the flex items are aligned at the start of the cross axis
+- `end`: the flex items are aligned at the end of the cross axis
+- `center`: the flex items are centered along the cross axis
+- `left`: the flex items are packed toward the left edge of the container
+- `right`: the flex items are packed toward the right edge of the container
+- `space-between`: the flex items are evenly distributed with the first item at the start and the last item at the end
+- `space-around`: the flex items are evenly distributed with equal space around them
+- `space-evenly`: the flex items are evenly distributed with equal space between them
+- `baseline`: the flex items are aligned based on their baselines
+- `first baseline`: the flex items are aligned based on the first baseline of the container
+- `last baseline`: the flex items are aligned based on the last baseline of the container
+- `safe center`: the flex items are centered along the cross axis, ensuring they remain within the safe area
+- `unsafe center`: the flex items are centered along the cross axis, without considering the safe area
+
+```python
+from deephaven import ui
+
+
+@ui.component
+def flex():
+    start = ui.flex(
+        ui.view(background_color="red", height="size-800", width="size-400"),
+        ui.view(background_color="green", height="size-800", width="size-800"),
+        ui.view(background_color="blue", height="size-800", width="size-200"),
+        justify_content="start",
+        width="500px",
+    )
+    center = ui.flex(
+        ui.view(background_color="red", height="size-800", width="size-400"),
+        ui.view(background_color="green", height="size-800", width="size-800"),
+        ui.view(background_color="blue", height="size-800", width="size-200"),
+        justify_content="center",
+        width="500px",
+    )
+    end = ui.flex(
+        ui.view(background_color="red", height="size-800", width="size-400"),
+        ui.view(background_color="green", height="size-800", width="size-800"),
+        ui.view(background_color="blue", height="size-800", width="size-200"),
+        justify_content="end",
+        width="500px",
+    )
+
+    return ui.flex(start, center, end, direction="column")
+
+
+my_flex = flex()
+```
+
+
+## API reference
+
+```{eval-rst}
+.. dhautofunction:: deephaven.ui.flex
+```

plugins/ui/src/deephaven/ui/components/flex.py

@@ -39,6 +39,9 @@ def flex(
         gap: The space to display between both rows and columns of children.
         column_gap: The space to display between columns of children.
         row_gap: The space to display between rows of children.
+
+    Returns:
+        The rendered flex box.
     """
     return component_element(
         "Flex",