docs: add constraint documentation

docs/plugins/layout.md

@@ -76,18 +76,140 @@ local components = {
 
 ## Constraint {#constraint}
 
-Constraints are used to define the size of a layout.
+A constraint that defines the size of a layout element.
 
-They can be used to define a fixed size, a percentage of the available space, a ratio of the available space, or a minimum or maximum size:
+Constraints can be used to specify a fixed size, a percentage of the available space, a ratio of
+the available space, a minimum or maximum size or a fill proportional value for a layout
+element.
+
+Relative constraints (percentage, ratio) are calculated relative to the entire space being
+divided, rather than the space available after applying more fixed constraints (min, max,
+length).
+
+Constraints are prioritized in the following order:
+
+1. `ui.Constraint.Min(min)`
+2. `ui.Constraint.Max(max)`
+3. `ui.Constraint.Length(len)`
+4. `ui.Constraint.Percentage(p)`
+5. `ui.Constraint.Ratio(num, den)`
+6. `ui.Constraint.Fill(scale)`
+
+### `Min(min)` {#constraint.min}
+
+Applies a minimum size constraint to the element
+
+The element size is set to at least the specified amount.
+
+```lua
+-- `{ Percentage(100), Min(20) }`
+-- ┌────────────────────────────┐┌──────────────────┐
+-- │            30 px           ││       20 px      │
+-- └────────────────────────────┘└──────────────────┘
+--
+-- `{ Percentage(100), Min(10) }`
+-- ┌──────────────────────────────────────┐┌────────┐
+-- │                 40 px                ││  10 px │
+-- └──────────────────────────────────────┘└────────┘
+```
+
+### `Max(max)` {#constraint.max}
+
+Applies a maximum size constraint to the element
+
+The element size is set to at most the specified amount.
+
+```lua
+-- `{ Percentage(0), Max(20) }`
+-- ┌────────────────────────────┐┌──────────────────┐
+-- │            30 px           ││       20 px      │
+-- └────────────────────────────┘└──────────────────┘
+--
+-- `{ Percentage(0), Max(10) }`
+-- ┌──────────────────────────────────────┐┌────────┐
+-- │                 40 px                ││  10 px │
+-- └──────────────────────────────────────┘└────────┘
+
+```
+
+### `Length(len)` {#constraint.length}
+
+Applies a length constraint to the element
+
+The element size is set to the specified amount.
 
 ```lua
-ui.Constraint.Percentage(50) -- Apply a percentage to a given amount
-ui.Constraint.Ratio(1, 3)    -- Apply a ratio
-ui.Constraint.Length(10)     -- Apply no more than the given amount (currently roughly equal to `ui.Constraint.Max`)
-ui.Constraint.Max(5)         -- Apply at most the given amount
-ui.Constraint.Min(3)         -- Apply at least the given amount
+-- `{ Length(20), Length(20) }`
+-- ┌──────────────────┐┌──────────────────┐
+-- │       20 px      ││       20 px      │
+-- └──────────────────┘└──────────────────┘
+--
+-- `{ Length(20), Length(30) }`
+-- ┌──────────────────┐┌────────────────────────────┐
+-- │       20 px      ││            30 px           │
+-- └──────────────────┘└────────────────────────────┘
 ```
 
+### `Percentage(p)` {#constraint.percentage}
+
+Applies a percentage of the available space to the element
+
+Converts the given percentage to a floating-point value and multiplies that with area.
+This value is rounded back to a integer as part of the layout split calculation.
+
+```lua
+-- `{ Percentage(75), Fill(1) }`
+-- ┌────────────────────────────────────┐┌──────────┐
+-- │                38 px               ││   12 px  │
+-- └────────────────────────────────────┘└──────────┘
+--
+-- `{ Percentage(50), Fill(1) }`
+-- ┌───────────────────────┐┌───────────────────────┐
+-- │         25 px         ││         25 px         │
+-- └───────────────────────┘└───────────────────────┘
+```
+
+### `Ratio(num, den)` {#constraint.ratio}
+
+Applies a ratio of the available space to the element
+
+Converts the given ratio to a floating-point value and multiplies that with area.
+This value is rounded back to a integer as part of the layout split calculation.
+
+```lua
+-- `{ Ratio(1, 2), Ratio(1, 2) }`
+-- ┌───────────────────────┐┌───────────────────────┐
+-- │         25 px         ││         25 px         │
+-- └───────────────────────┘└───────────────────────┘
+--
+-- `{ Ratio(1, 4), Ratio(1, 4), Ratio(1, 4), Ratio(1, 4) }`
+-- ┌───────────┐┌──────────┐┌───────────┐┌──────────┐
+-- │   13 px   ││   12 px  ││   13 px   ││   12 px  │
+-- └───────────┘└──────────┘└───────────┘└──────────┘
+```
+
+### `Fill(scale)` {#constraint.fill}
+
+Applies the scaling factor proportional to all other `Fill` elements
+to fill excess space
+
+The element will only expand or fill into excess available space, proportionally matching
+other `Fill` elements while satisfying all other constraints.
+
+```lua
+-- `{ Fill(1), Fill(2), Fill(3) }`
+-- ┌──────┐┌───────────────┐┌───────────────────────┐
+-- │ 8 px ││     17 px     ││         25 px         │
+-- └──────┘└───────────────┘└───────────────────────┘
+--
+-- `{ Fill(1), Percentage(50), Fill(1) }`
+-- ┌───────────┐┌───────────────────────┐┌──────────┐
+-- │   13 px   ││         25 px         ││   12 px  │
+-- └───────────┘└───────────────────────┘└──────────┘
+```
+
+See https://docs.rs/ratatui/latest/ratatui/layout/enum.Constraint.html for more information.
+
 ## Gauge {#gauge}
 
 Create a gauge: