From 1a9655414ecf53e0f5bf201ed608f9edf2a90da8 Mon Sep 17 00:00:00 2001 From: iris <2+iris@noreply.localhost> Date: Tue, 8 Sep 2026 16:38:05 -0400 Subject: [PATCH] docs: Iris's idea for retiring masked_by -- a Stack that names its mask She asked whether `masked_by` earns its place, since `.background(x).masked()` looks like the same thing. Measured: for a square-cornered surface it is (identical to the pixel on the composer at the phone's size and density), and what the pair cannot express is a clip that is not a box, which is why the method stands for now. Her suggestion, in IRIS_TODO.md's "Reconsider": let `Stack` name where its mask comes from the way `StackSize::Child(n)` already names where its size comes from, at which point `masked_by` and `Masked::shape` both go away. Co-Authored-By: Claude Opus 5 --- docs/IRIS_TODO.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/IRIS_TODO.md b/docs/IRIS_TODO.md index 855da12..81934b0 100644 --- a/docs/IRIS_TODO.md +++ b/docs/IRIS_TODO.md @@ -964,6 +964,31 @@ do not duplicate it there. both ways and keeping the one that is shorter to explain; delete the other rather than keeping two ways. +- [ ] **A `Stack` that chooses its mask the way it chooses its size + (Iris, 2026-09-08).** She asked whether `masked_by` deserves to exist: + "a method that just does 2 separate things you can already easily do + does not deserve to exist." For a square-cornered surface it is indeed + redundant -- `.background(rect(BAR_FILL)).masked()` was measured + against `.masked_by(rect(BAR_FILL))` on the composer at the phone's own + size and density and the two are identical to the pixel. What the pair + cannot express is a clip that is not a box: `Painter::set_mask` writes + a `RectPrimitive::color(Color::NONE)` at the widget's own region, with + no radius, so `.background(rect(fill).radius(r)).masked()` draws a + rounded panel and then cuts its content square. Both other call sites + (`row.rs`'s fence, `tool.rs`'s raw output) are rounded, which is why + the method stands for now. + Her suggestion for removing it properly: **`Stack` already names where + its size comes from (`StackSize::Child(n)`); let it name where its + *mask* comes from the same way.** Then `.background(x)` is the one way + to put a surface behind something, and clipping to that surface is a + property of the stack rather than a second wrapper -- `masked_by` goes, + and `Masked::shape` with it. Worth checking while designing it: what a + stack with no mask child means (today's behaviour), whether the mask + child must also have been *drawn* first (`set_mask_to_widget` requires + it, and `Stack` draws in order, so naming child 0 is safe and naming a + later one is not), and what happens when the named child is the same + one the size comes from. + ## Build (asked for by Iris, 2026-09-06): a density-independent length unit - [x] **A third length kind beside relative and pixels, so display scales