From 721a8fc50d0d41fdea08c5aef26b8d3259bed9b0 Mon Sep 17 00:00:00 2001 From: iris-ai <4+iris-ai@noreply.localhost> Date: Sat, 19 Sep 2026 21:25:35 -0400 Subject: [PATCH] Record the naming round in the handoff and LAYOUT.md Iris PR #19's tip is 2807a92. LAYOUT.md's settled-design section named the retired `PlaceDescAxis::within`/`shifted`/`sized` constructors and the `axis`/`axis_mut` accessors; it now says the `_desc` chaining rule, the `axis` lift, and that every pair is a struct of two per-axis values read with `[axis]`. Co-Authored-By: Claude Opus 5 --- docs/HANDOFF.md | 16 +++++++++++++--- docs/LAYOUT.md | 31 +++++++++++++++++++++---------- 2 files changed, 34 insertions(+), 13 deletions(-) diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 2843997..fe057a0 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -6,8 +6,8 @@ found is in `docs/LAYOUT_LOG.md`. ## The Iris layout repair is submitted -**Iris PR #19** (`layout/one-ask`) replaces closed #18. The tip is `58ce74d`, -and past the reviewed `cadfba0` it is two rounds: +**Iris PR #19** (`layout/one-ask`) replaces closed #18. The tip is `2807a92`, +and past the reviewed `cadfba0` it is three rounds: - **The repair.** `add6774` fixes collapsed-share placement, retained mask ownership and a redraw-on-reparent defect; `84dad21` removes repeated work @@ -18,6 +18,15 @@ and past the reviewed `cadfba0` it is two rounds: the single `impl Into` argument that replaced `Place`, `Part`, `widget_within` and the separate rel-base argument. **Bryan is still refining this**, so treat the API as current rather than frozen. +- **Named operations and `Index`**, `55df32a` and `2807a92`, settled + with Bryan on 2026-09-19. A description is built by chaining off the value + that says it (`UiSpan::shifted_desc`, `Len::as_desc`), never by a + constructor naming the type; `on` is reserved for events, so the lift is + `PlaceDescAxis::axis`. Arithmetic that needed a comment became a name: + `UiSpan::place`, `LayoutLen::without_leftover`/`is_px`/`is_only_leftover`/ + `declared`, `Holds::covers`. `LayoutHolds` became `AxisHolds` on `x`/`y`, + every pair got `Index` through `impl_axis_index!`, and the bare + `[Option; 2]` became `Declared` of `Option`. The core design remains sound. Round-to-nearest is still unchanged. @@ -35,7 +44,8 @@ The gate that matters for anything shaped like a rename or a refactor is the **cold dump**: `layout_dump` over 400 depth-5 trees is 34,492 boxes, and the compiler cannot catch two same-typed values being swapped. The repair moved 650 of those boxes, all from the collapsed-share correction. Every commit -since has been byte-identical to `84dad21`, including the whole API rewrite. +since has been byte-identical to `84dad21`, including the whole API rewrite +and the naming work above. ## What is next, in order diff --git a/docs/LAYOUT.md b/docs/LAYOUT.md index 6d27bdd..4151087 100644 --- a/docs/LAYOUT.md +++ b/docs/LAYOUT.md @@ -344,30 +344,41 @@ and `place_at(id, place)` take `impl Into`, so a wrapper that only hands over a box passes a `UiRegion` and says nothing else — which is all `Pad`, `Offset` and `Painter::widget` do. -`PlaceDescAxis` is one axis, and its three constructors are named after the -operations the geometry already had, because two of them take the same span -and differ only in how it is applied: +`PlaceDescAxis` is one axis. It is built by chaining off the value that says +it, never by a constructor naming the type, because a constructor makes the +reader go back to the start of the line. The `_desc` suffix is what says which +type comes out. The three are named after the operations the geometry already +had, because two of them take the same span and differ only in how it is +applied: -- `within(span)` — `UiSpan::within`: composed into the caller's box, so it +- `UiSpan::within_desc()` — `UiSpan::within`: composed into the caller's box, so it moves and scales with it. What an inset speaks. -- `shifted(span)` — `UiSpan::shift`: window lengths from where the caller's +- `UiSpan::shifted_desc()` — `UiSpan::shift`: window lengths from where the caller's box starts. What a container dividing room speaks, and what makes a moved box re-place every child by addition, exactly. Not directional: `Dir::Neg` is handled by the span before the numbers get here. -- `sized(len)` — the body of `placement` with the length given from above +- `Len::as_desc()` — the body of `placement` with the length given from above rather than reported. What a stack's sizing child decides for the rest. What is optional is a builder, so a caller writes only what it decided: `.fills()` says the region is the placement, and `.rel_base(len)` names the child's rel base outright. **The rel base a caller does not name follows the -constructor** — `within` narrows it the way the box is narrowed, `shifted` -passes it through, `sized` is it. That rule is what makes the common case +constructor** — `within_desc` narrows it the way the box is narrowed, +`shifted_desc` passes it through, `as_desc` is it. That rule is what makes the common case right by default; stating it by hand was the one thing a container could get wrong with nothing failing. -`PlaceDesc` is the pair, with `x` and `y` fields and the `axis`, `axis_mut` -and `from_axis` of every other pair here, so the joint work — resolving a +`PlaceDesc` is the pair, with `x` and `y` fields and the `Index` and +`from_axis` of every other pair here, so the joint work — resolving a region, reading the fill flags — is written once rather than per axis. +`PlaceDescAxis::axis(axis)` goes the other way, lifting one axis into a pair +with the whole box across it. + +**Every pair here is a struct of two per-axis values, read with `[axis]`.** +`impl_axis_index!` gives it `Index`/`IndexMut`; there are no +`axis`/`axis_mut` methods and no bare `[T; 2]`. A pair kept as arrays of its +fields instead — which `LayoutHolds` was, until `AxisHolds` — cannot write +any of its own operations once. ## Rel bases, decided boxes and padding