1# llimphi-widget-fitted-box
2
3Scales a subtree to the available slot.
4
5The analogue of Flutter's `FittedBox`: the caller passes the content's **natural
6size** and a **fit policy**, and the widget applies an affine `transform` to the
7subtree so it fits the real slot (measured through the compositor's
8`LayoutBuilder` seam). The subtree ends up **centred** and, except under
9`BoxFit::Fill`, **preserves its aspect ratio**.
10
11Why it does not come for free: `taffy` sizes containers, but the content (text,
12image, custom painter) does not scale with its container — it is only positioned
13inside it. `FittedBox` applies a VISUAL scale over the whole subtree, so a
14`paint_with` canvas or a large piece of text fits into a tiny cell without the
15caller re-measuring anything.
16
17The widget's parent has `clip(true)` so no pixel escapes the slot (it only
18matters when the content's aspect does NOT match the slot under `BoxFit::None`,
19and never with `Contain`/`Fill`).
20
21## API
22
23```ignore
24use llimphi_widget_fitted_box::{fitted_box, BoxFit};
25// An 800×600 image that must fit any slot, preserving aspect
26// (shown whole, possibly with bands).
27fitted_box((800.0, 600.0), BoxFit::Contain, || my_image_view())
28```
29
30## Pure functions
31
32`compute_fit` returns `(sx, sy, dx, dy)` for a given `(slot, inner, fit)` and is
33testable without a runtime. Useful to validate the algorithm, and for cases where
34the caller already has its own transform to compose with.
35
36---
37
38Part of **llimphi** — see [llimphi](../../README.md).