🍬 CandyLayout
Constraint-based layout solver for terminal grids
Two solvers behind a LayoutSolver interface: CassowarySolver (simplex-based, optimal, handles stay/edit constraints) and GreedySolver (deterministic 5-phase fallback ported from candy-sprinkles). Swap solvers without touching call-sites. Foundation for candy-sprinkles, sugar-bits, and candy-forms layout.
Install
composer require sugarcraft/candy-layoutQuickstart
use SugarCraft\Layout\{Constraint, Direction, GreedySolver, Region};
$solver = GreedySolver::new();
$region = Region::fromSize(100, 24);
$rects = $solver->solve($region, Direction::Horizontal, [
Constraint::length(20), // exactly 20 cells
Constraint::min(10), // at least 10, takes more if available
Constraint::fill(1), // fills remaining space (weight 1)
Constraint::percentage(30), // 30% of total
Constraint::ratio(1, 3), // 1/3 of remaining after fixed
Constraint::max(50), // ceiling — greedy but clamped
]);Solvers
GreedySolverDeterministic 5-phase fallback. Bit-identical output to the existing candy-sprinkles Solver. No deps, no edit variables. Fast and predictable.
CassowarySolverFull simplex with Big-M method. Handles stay constraints and edit variables. Simplification of Badros & Borning 2001 for 1D integer outputs.
Constraint types
LengthFixed cell count — takes exactly n cells.
MinFloor — at least n cells, grows if slack available.
MaxCeiling — greedy, clamped to n cells.
FillProportional remainder — weight controls distribution across multiple Fill constraints.
PercentageFraction of total — n% of the available dimension.
RatioFractional proportion — num/denom of remaining space after fixed constraints.
Use it for
- Foundation for candy-sprinkles — step-10 wires candy-sprinkles' existing Solver to consume candy-layout.
- Foundation for sugar-bits / candy-forms — step-14/15 layout extraction.
- Swap solver without breaking call-sites — LayoutSolver is the only public contract.
Source & demos
- Source on GitHub
- Full README
- Runnable examples
- Inspired by ratatui/ratatui layout constraint system
- Based on Badros & Borning 2001 "The Cassowary Linear Arithmetic Constraint Solving Algorithm"
API
| Class | Method | Description |
|---|---|---|
| LayoutSolver | solve(Region, Direction, list<Constraint>) | Solve constraints against a region in the given direction; returns list of sub-regions |
| LayoutSolver | greedy(): self | Factory: create a GreedySolver |
| LayoutSolver | cassowary(): self | Factory: create a CassowarySolver |
| GreedySolver | new(): self | Default factory |
| CassowarySolver | new(): self | Default factory |
| Direction | Horizontal, Vertical | Enum: split direction |
| Region | fromSize(int, int) | Factory: width, height |
| Constraint | length(int) | Fixed cell count |
| Constraint | min(int) | Floor — at least n cells |
| Constraint | max(int) | Ceiling — at most n cells |
| Constraint | fill(int $weight) | Proportional remainder with weight |
| Constraint | percentage(int 0-100) | Percentage of total |
| Constraint | ratio(int $num, int $denom) | Fractional proportion |