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 <noreply@anthropic.com>
This commit is contained in:
iris-aiandClaude Opus 5 committed 2026-09-19 21:25:35 -04:00
1 parent 61a2f601bb
commit 721a8fc50d
2 files changed
+34 -13

No files matched your search

+13 -3
View File
@@ -6,8 +6,8 @@ found is in `docs/LAYOUT_LOG.md`.
## The Iris layout repair is submitted ## The Iris layout repair is submitted
**Iris PR #19** (`layout/one-ask`) replaces closed #18. The tip is `58ce74d`, **Iris PR #19** (`layout/one-ask`) replaces closed #18. The tip is `2807a92`,
and past the reviewed `cadfba0` it is two rounds: and past the reviewed `cadfba0` it is three rounds:
- **The repair.** `add6774` fixes collapsed-share placement, retained mask - **The repair.** `add6774` fixes collapsed-share placement, retained mask
ownership and a redraw-on-reparent defect; `84dad21` removes repeated work 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<PlaceDesc>` argument that replaced `Place`, `Part`, the single `impl Into<PlaceDesc>` argument that replaced `Place`, `Part`,
`widget_within` and the separate rel-base argument. **Bryan is still `widget_within` and the separate rel-base argument. **Bryan is still
refining this**, so treat the API as current rather than frozen. refining this**, so treat the API as current rather than frozen.
- **Named operations and `Index<Axis>`**, `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<Axis>` through `impl_axis_index!`, and the bare
`[Option<LayoutLen>; 2]` became `Declared` of `Option<Len>`.
The core design remains sound. Round-to-nearest is still unchanged. 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 **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 compiler cannot catch two same-typed values being swapped. The repair moved
650 of those boxes, all from the collapsed-share correction. Every commit 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 ## What is next, in order
+21 -10
View File
@@ -344,30 +344,41 @@ and `place_at(id, place)` take `impl Into<PlaceDesc>`, so a wrapper that only
hands over a box passes a `UiRegion` and says nothing else — which is all hands over a box passes a `UiRegion` and says nothing else — which is all
`Pad`, `Offset` and `Painter::widget` do. `Pad`, `Offset` and `Painter::widget` do.
`PlaceDescAxis` is one axis, and its three constructors are named after the `PlaceDescAxis` is one axis. It is built by chaining off the value that says
operations the geometry already had, because two of them take the same span it, never by a constructor naming the type, because a constructor makes the
and differ only in how it is applied: 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. 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 starts. What a container dividing room speaks, and what makes a moved
box re-place every child by addition, exactly. Not directional: `Dir::Neg` box re-place every child by addition, exactly. Not directional: `Dir::Neg`
is handled by the span before the numbers get here. 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. 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: 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 `.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 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` constructor** — `within_desc` narrows it the way the box is narrowed,
passes it through, `sized` is it. That rule is what makes the common case `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 right by default; stating it by hand was the one thing a container could get
wrong with nothing failing. wrong with nothing failing.
`PlaceDesc` is the pair, with `x` and `y` fields and the `axis`, `axis_mut` `PlaceDesc` is the pair, with `x` and `y` fields and the `Index<Axis>` and
and `from_axis` of every other pair here, so the joint work — resolving a `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. 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<Axis>`/`IndexMut<Axis>`; 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 ## Rel bases, decided boxes and padding