urushi 0.1.1

Composable styling, components, and terminal rendering for Rust CLIs
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
//! The width phase: two passes that settle every node's width.
//!
//! Width comes first because wrapping needs a width to wrap to. That makes the
//! dependency one-way — width, then height, then assembly — and this module is
//! the end of it that must not look forward: it never wraps a line, never
//! counts a row, and reaches nothing the height phase or assembly owns. The
//! rules it applies are `docs/design/box-sizing.md`'s and
//! `docs/design/area-sharing.md`'s, in the order `docs/design/layout-resolution.md`
//! fixes.
//!
//! It runs in two passes over the tree, each visiting a node once.
//!
//! - Pass A, bottom-up, fills [`Metrics`]: the width a node takes unbounded,
//!   the width below which it cannot go, the height below which it cannot be
//!   shrunk, and whether anything inside it spans its area. Each is `O(1)` from
//!   the children's, so the whole pass is one walk.
//! - Pass B, top-down, hands each node an area and reads pass A's numbers to
//!   settle the width it uses, descending into every child exactly once.
//!
//! Asking a subtree for its extent used to be a walk of its own, so a chain of
//! blocks measured the same leaves once per level. Folding those questions into
//! a table is what makes the phase linear; nothing about what they answer
//! changed.

use crate::{
    Align, BlockStyle, BlockTitle, Canvas, GridStyle, Key, Length, Overflow, Sides, StyledText,
    TextStyle, VerticalAlign, View, Viewport,
};

use super::geometry::Constraint;
use super::grid;

use super::sizing::{
    Claim, Kind, border_extent, degrade, distribute_constraints, horizontal, kind_of, vertical,
    width_axis,
};

/// The overflow policy a text leaf outside a block is fitted under.
static WRAP: Overflow = Overflow::Wrap;

/// What a subtree fixes about its own size, whatever area it is later given.
///
/// These are the numbers the clamp needs before the content is laid out. They
/// depend on the subtree alone, so pass A can read them off the tree once and
/// pass B can consume them without walking anything again.
#[derive(Debug)]
pub(super) struct Metrics {
    /// The width the node takes when no area bounds it — its max-content size.
    natural: usize,
    /// The width below which it cannot go without splitting a grapheme.
    floor: usize,
    /// The height below which it cannot be shrunk.
    height_floor: usize,
    /// Whether anything inside it spans its area rather than taking a size.
    ///
    /// A `Fill` length needs an area to divide, so a box containing one spans
    /// its own extent. The height axis gets this for free — a box sizes its
    /// height after its content — but the width is decided before the content
    /// is laid out, which is why the width axis has to ask.
    fills: bool,
    /// Whether an unresolved Viewport dependency reaches this node.
    width_projection: bool,
    height_projection: bool,
    width_kind: Kind,
    height_kind: Kind,
    /// One entry per child; a block has exactly one.
    children: Vec<Metrics>,
}

/// Pass A: the bottom-up walk that fills [`Metrics`] for every node.
fn metrics(view: &View) -> Metrics {
    match view {
        View::Text(text) => {
            let lines = text.lines();
            Metrics {
                natural: lines
                    .iter()
                    .map(|line| line.iter().map(|grapheme| grapheme.width()).sum())
                    .max()
                    .unwrap_or(0),
                floor: lines
                    .iter()
                    .flat_map(|line| line.iter().map(|grapheme| grapheme.width()))
                    .max()
                    .unwrap_or(0),
                height_floor: 0,
                fills: false,
                width_projection: false,
                height_projection: false,
                width_kind: Kind::Auto,
                height_kind: Kind::Auto,
                children: Vec::new(),
            }
        }
        View::Canvas(canvas) => {
            let width = canvas.width_requirements();
            let kind = if canvas.uses_viewport_sizing() {
                Kind::fill(1)
            } else {
                Kind::Auto
            };
            Metrics {
                natural: width.demand(),
                floor: width.floor(),
                height_floor: 0,
                fills: canvas.uses_viewport_sizing(),
                width_projection: false,
                height_projection: false,
                width_kind: kind,
                height_kind: kind,
                children: Vec::new(),
            }
        }
        // An anchor measures as the block it is: the key says where to report,
        // never how large to be.
        View::Block(style, title, child) | View::AnchorBlock(_, style, title, child) => {
            let inner = metrics(child);
            let frame = style.frame_size();
            let margin = style.get_margin();
            let intrinsic = inner
                .natural
                .max(title_width(style, title.as_ref()).saturating_sub(frame.width()));
            // The undegraded frame: no area is known yet, and degradation is
            // what an area does to a frame.
            let natural = width_axis(style, frame.width()).used(
                Constraint::unbounded(),
                intrinsic,
                inner.floor,
            ) + horizontal(margin);
            let floor = style
                .get_min_width()
                .map_or(0, usize::from)
                .max(frame.width() + inner.floor)
                + horizontal(margin);
            let height_floor = style
                .get_min_height()
                .map_or(0, usize::from)
                .max(frame.height() + inner.height_floor)
                + vertical(margin);
            let fills = match style.get_width() {
                Some(Length::Fill(_)) => true,
                Some(Length::Cells(_)) => false,
                None => inner.fills,
            };
            let width_projection = match (style.get_width(), style.get_max_width()) {
                (None, None) => inner.width_projection,
                _ => false,
            };
            let height_projection = match (style.get_height(), style.get_max_height()) {
                (None, None) => inner.height_projection,
                _ => false,
            };
            Metrics {
                natural,
                floor,
                height_floor,
                fills,
                width_projection,
                height_projection,
                width_kind: dependent_kind(style.get_width(), width_projection),
                height_kind: dependent_kind(style.get_height(), height_projection),
                children: vec![inner],
            }
        }
        View::Row(_, children) => {
            let children: Vec<Metrics> = children.iter().map(metrics).collect();
            let fills = children.iter().any(|child| child.fills);
            let width_projection = children.iter().any(|child| child.width_projection);
            let height_projection = children.iter().any(|child| child.height_projection);
            Metrics {
                natural: children.iter().map(|child| child.natural).sum(),
                floor: children.iter().map(|child| child.floor).sum(),
                height_floor: children
                    .iter()
                    .map(|child| child.height_floor)
                    .max()
                    .unwrap_or(0),
                fills,
                width_projection,
                height_projection,
                width_kind: dependent_kind(None, width_projection),
                height_kind: dependent_kind(None, height_projection),
                children,
            }
        }
        View::Column(_, children) => {
            let children: Vec<Metrics> = children.iter().map(metrics).collect();
            let fills = children.iter().any(|child| child.fills);
            let width_projection = children.iter().any(|child| child.width_projection);
            let height_projection = children.iter().any(|child| child.height_projection);
            Metrics {
                natural: children
                    .iter()
                    .map(|child| child.natural)
                    .max()
                    .unwrap_or(0),
                floor: children.iter().map(|child| child.floor).max().unwrap_or(0),
                height_floor: children.iter().map(|child| child.height_floor).sum(),
                fills,
                width_projection,
                height_projection,
                width_kind: dependent_kind(None, width_projection),
                height_kind: dependent_kind(None, height_projection),
                children,
            }
        }
        View::Grid(style, rows) => {
            let columns = grid::columns(rows);
            let mut cells = Vec::with_capacity(rows.len() * columns);
            for row in 0..rows.len() {
                for column in 0..columns {
                    cells.push(metrics(grid::cell(rows, row, column)));
                }
            }
            let claims = column_claims(style, rows, &cells, columns);
            let fills = cells.iter().any(|cell| cell.fills)
                || (0..columns)
                    .any(|column| matches!(style.get_column(column), Some(Length::Fill(_))));
            let width_projection = (0..columns).any(|column| {
                style.get_column(column).is_none()
                    && (0..rows.len()).any(|row| cells[row * columns + column].width_projection)
            });
            let height_projection = cells.iter().any(|cell| cell.height_projection);
            Metrics {
                natural: claims.iter().map(|claim| claim.demand).sum(),
                floor: claims.iter().map(|claim| claim.floor).sum(),
                height_floor: (0..rows.len())
                    .map(|row| row_floor(style, rows, &cells, columns, row))
                    .sum(),
                fills,
                width_projection,
                height_projection,
                width_kind: dependent_kind(None, width_projection),
                height_kind: dependent_kind(None, height_projection),
                children: cells,
            }
        }
        View::Viewport(viewport, child) => {
            let inner = metrics(child);
            let horizontal = viewport.horizontal_projection().is_some();
            let vertical = viewport.vertical_projection().is_some();
            let fills = horizontal || inner.fills;
            let width_projection = horizontal || inner.width_projection;
            let height_projection = vertical || inner.height_projection;
            Metrics {
                natural: inner.natural,
                floor: if horizontal { 0 } else { inner.floor },
                height_floor: if vertical { 0 } else { inner.height_floor },
                fills,
                width_projection,
                height_projection,
                width_kind: dependent_kind(None, width_projection),
                height_kind: dependent_kind(None, height_projection),
                children: vec![inner],
            }
        }
    }
}

fn dependent_kind(length: Option<Length>, depends_on_area: bool) -> Kind {
    match length {
        None if depends_on_area => Kind::fill(1),
        _ => kind_of(length),
    }
}

/// The claim each column of a grid makes on the grid's width.
///
/// The kind comes from the column's stated [`Length`], the demand and the
/// floor from the cells beneath it, each measured with the padding that cell
/// takes. Only per-cell metrics are read, so a column's claim never depends on
/// what a sibling resolved to — the no-solver boundary
/// `docs/design/layout-resolution.md` fixes.
fn column_claims(
    style: &GridStyle,
    rows: &[Vec<View>],
    cells: &[Metrics],
    columns: usize,
) -> Vec<Claim> {
    (0..columns)
        .map(|column| {
            let (mut demand, mut floor) = (0, 0);
            for row in 0..rows.len() {
                let padding = horizontal(grid::cell_padding(style, grid::cell(rows, row, column)));
                let cell = &cells[row * columns + column];
                demand = demand.max(cell.natural + padding);
                floor = floor.max(cell.floor + padding);
            }
            let length = style.get_column(column);
            let depends_on_area =
                (0..rows.len()).any(|row| cells[row * columns + column].width_projection);
            Claim {
                kind: dependent_kind(length, depends_on_area),
                // A stated size is a demand of its own, and the floor still
                // wins over it — the clamp a `Row` child applies to itself,
                // applied here from outside, because a cell cannot know the
                // length its column states.
                demand: match length {
                    Some(Length::Cells(cells)) => usize::from(cells).max(floor),
                    _ => demand,
                },
                floor,
            }
        })
        .collect()
}

/// The height below which one row of a grid cannot be shrunk.
fn row_floor(
    style: &GridStyle,
    rows: &[Vec<View>],
    cells: &[Metrics],
    columns: usize,
    row: usize,
) -> usize {
    (0..columns)
        .map(|column| {
            let padding = vertical(grid::cell_padding(style, grid::cell(rows, row, column)));
            cells[row * columns + column].height_floor + padding
        })
        .max()
        .unwrap_or(0)
}

/// One node with its width settled, and what the later phases still need.
#[derive(Debug)]
pub(super) struct Widths<'a> {
    /// The outer width this node occupies, margin included.
    pub width: usize,
    /// How the node claims space on an enclosing `Column`'s axis.
    pub height_kind: Kind,
    /// The height below which the node cannot be shrunk.
    pub height_floor: usize,
    /// Whether an unresolved vertical Viewport reaches this node.
    pub height_projection: bool,
    pub node: WidthNode<'a>,
}

#[derive(Debug)]
pub(super) enum WidthNode<'a> {
    Text(TextBox<'a>),
    Block(BlockBox<'a>),
    Row(VerticalAlign, Vec<Widths<'a>>),
    Column(Align, Vec<Widths<'a>>),
    Grid(GridBox<'a>),
    Canvas(&'a Canvas, bool, super::canvas::CanvasRequirements),
    Viewport(&'a Viewport, bool, Box<Widths<'a>>),
}

/// A grid whose column widths are settled.
///
/// `columns` is one width per column, padding included, and every cell of
/// column `j` was resolved under `columns[j]` less its own padding. The two
/// cannot disagree: the second is what the first was handed down as.
#[derive(Debug)]
pub(super) struct GridBox<'a> {
    pub columns: Vec<usize>,
    pub rows: Vec<Vec<GridCell<'a>>>,
}

/// One cell of a grid, with the padding it takes around it.
#[derive(Debug)]
pub(super) struct GridCell<'a> {
    /// The cell's own padding where it states one, the grid's otherwise. Its
    /// horizontal sides carry this phase's degradation; the vertical ones are
    /// still as stated, because only the height phase knows the area that
    /// degrades those.
    pub padding: Sides,
    /// How the cell places itself in a column or a row wider than it is. A
    /// cell that is not a box states none of this and takes the defaults.
    pub align: Align,
    pub vertical_align: VerticalAlign,
    pub child: Widths<'a>,
}

/// A text leaf and everything needed to fit its lines, once a width exists.
#[derive(Debug)]
pub(super) struct TextBox<'a> {
    pub text: &'a StyledText,
    /// The area the leaf was given, which is what the policy fits against —
    /// not the width it resolved to, which a grapheme it cannot split may
    /// widen.
    pub area: Option<usize>,
    pub overflow: &'a Overflow,
    /// Per-line alignment and the style filling the gap, both supplied by an
    /// enclosing block.
    pub align: Align,
    pub fill: TextStyle,
}

/// A block whose horizontal frame and content width are settled.
///
/// `padding` and `margin` carry the horizontal degradation this phase decided;
/// their vertical sides are still as the style stated them, because only the
/// height phase knows the area that degrades those.
#[derive(Debug)]
pub(super) struct BlockBox<'a> {
    pub style: &'a BlockStyle,
    pub title: Option<&'a BlockTitle>,
    /// The key to report this box's content rectangle under, if it is an
    /// anchor.
    pub anchor: Option<Key>,
    pub padding: Sides,
    pub margin: Sides,
    pub content_width: usize,
    pub child: Box<Widths<'a>>,
}

/// What an enclosing block fits a text leaf it directly contains under.
#[derive(Clone, Copy)]
struct TextFit<'a> {
    align: Align,
    fill: &'a TextStyle,
    overflow: &'a Overflow,
}

/// Settles every node's width under `area`.
pub(super) fn widths(view: &View, area: Option<usize>) -> Widths<'_> {
    place(
        view,
        &metrics(view),
        Constraint::available(area),
        area.is_some(),
        None,
    )
}

/// Pass B: hands `area` down and reads pass A's numbers to settle each width.
fn place<'a>(
    view: &'a View,
    metrics: &Metrics,
    constraint: Constraint,
    bounded: bool,
    fit: Option<TextFit<'a>>,
) -> Widths<'a> {
    match view {
        View::Text(text) => {
            let (align, fill, overflow) = fit.map_or_else(
                || {
                    // Preserve the uniform leaf's fill behavior. Mixed text
                    // has no one style that can own geometry, so its bare
                    // alignment gap is terminal-default.
                    (
                        Align::Left,
                        text.uniform_style().cloned().unwrap_or_else(TextStyle::new),
                        &WRAP,
                    )
                },
                |fit| (fit.align, fit.fill.clone(), fit.overflow),
            );
            Widths {
                width: text_width(constraint.cap, overflow, metrics),
                height_kind: metrics.height_kind,
                height_floor: metrics.height_floor,
                height_projection: metrics.height_projection,
                node: WidthNode::Text(TextBox {
                    text,
                    area: constraint.cap,
                    overflow,
                    align,
                    fill,
                }),
            }
        }
        View::Canvas(canvas) => {
            let width = constraint
                .reference
                .map(|area| area.max(metrics.floor))
                .unwrap_or(metrics.natural);
            let height = canvas.height_requirements(width);
            Widths {
                width,
                height_kind: metrics.height_kind,
                height_floor: height.floor(),
                height_projection: metrics.height_projection,
                node: WidthNode::Canvas(canvas, bounded, height),
            }
        }
        View::Block(style, title, child) | View::AnchorBlock(_, style, title, child) => {
            let inner = &metrics.children[0];
            let border = border_extent(style);
            let mut padding = style.get_padding();
            let mut margin = style.get_margin();

            // 1. Degrade the frame to the area — the horizontal half of it.
            //    The axes degrade independently, so the height phase decides
            //    the other half against the area it is given.
            let across = degrade(
                constraint.cap,
                horizontal(margin),
                border.width(),
                horizontal(padding),
                inner.floor,
            );
            if across.margin {
                margin.left = 0;
                margin.right = 0;
            }
            if across.padding {
                padding.left = 0;
                padding.right = 0;
            }

            // 2. Resolve the width by the clamp. The content has not been laid
            //    out yet: the width comes from the intrinsic width, the bounds,
            //    and the area, never from what wrapping is about to do.
            let axis = width_axis(
                style,
                border.width() + usize::from(padding.left) + usize::from(padding.right),
            );
            // Every sizing property measures the box; margin lies outside it.
            let box_constraint = Constraint {
                reference: constraint
                    .reference
                    .map(|area| area.saturating_sub(horizontal(margin))),
                cap: constraint
                    .cap
                    .map(|area| area.saturating_sub(horizontal(margin))),
            };
            let title_intrinsic = title_width(style, title.as_ref()).saturating_sub(axis.frame);
            let intrinsic = if inner.fills
                && let Some(area) = box_constraint.reference
            {
                area.saturating_sub(axis.frame)
            } else {
                inner.natural.max(title_intrinsic)
            };
            let used = axis.used(box_constraint, intrinsic, inner.floor);
            let content_width = used - axis.frame;
            let child_constraint = Constraint::established(content_width);
            let local_bound = matches!(axis.length, Some(Length::Cells(_))) || axis.max.is_some();

            // 3. The child, under what the box leaves it. A directly contained
            //    text leaf meets the block's overflow policy here; any other
            //    child absorbs its own overflow when it resolves.
            let child = place(
                child,
                inner,
                child_constraint,
                bounded || local_bound,
                Some(TextFit {
                    align: style.get_align(),
                    fill: style.text_style(),
                    overflow: style.get_overflow(),
                }),
            );
            debug_assert!(
                child.width <= content_width,
                "a child never resolves wider than the box that assigned it: \
                 {} > {content_width}",
                child.width
            );
            let height_floor = style
                .get_min_height()
                .map_or(0, usize::from)
                .max(border.height() + vertical(padding) + child.height_floor)
                + vertical(margin);

            Widths {
                width: used + horizontal(margin),
                height_kind: metrics.height_kind,
                height_floor,
                height_projection: metrics.height_projection,
                node: WidthNode::Block(BlockBox {
                    style,
                    title: title.as_ref(),
                    anchor: match view {
                        View::AnchorBlock(key, _, _, _) => Some(*key),
                        _ => None,
                    },
                    padding,
                    margin,
                    content_width,
                    child: Box::new(child),
                }),
            }
        }
        View::Row(align, children) => {
            // The main axis is divided: stated widths, then intrinsic ones,
            // then `Fill` weights over what remains. With no width to divide —
            // under `measure` — every child takes its intrinsic width.
            let claims: Vec<Claim> = metrics
                .children
                .iter()
                .map(|child| Claim {
                    kind: child.width_kind,
                    demand: child.natural,
                    floor: child.floor,
                })
                .collect();
            let shares = distribute_constraints(constraint.reference, constraint.cap, &claims);
            let children: Vec<Widths<'a>> = children
                .iter()
                .zip(&metrics.children)
                .enumerate()
                .map(|(index, (child, inner))| {
                    place(
                        child,
                        inner,
                        if constraint.reference.is_some() {
                            Constraint::established(shares[index])
                        } else {
                            Constraint::unbounded()
                        },
                        bounded,
                        None,
                    )
                })
                .collect();
            Widths {
                // Nothing is renegotiated: a child that resolves narrower than
                // its assignment leaves the remainder unused.
                width: children.iter().map(|child| child.width).sum(),
                height_kind: metrics.height_kind,
                height_floor: children
                    .iter()
                    .map(|child| child.height_floor)
                    .max()
                    .unwrap_or(0),
                height_projection: metrics.height_projection,
                node: WidthNode::Row(*align, children),
            }
        }
        View::Column(align, children) => {
            // The cross axis has nothing to divide: every child receives the
            // column's own width.
            let children: Vec<Widths<'a>> = children
                .iter()
                .zip(&metrics.children)
                .map(|(child, inner)| place(child, inner, constraint, bounded, None))
                .collect();
            Widths {
                width: children.iter().map(|child| child.width).max().unwrap_or(0),
                height_kind: metrics.height_kind,
                height_floor: children.iter().map(|child| child.height_floor).sum(),
                height_projection: metrics.height_projection,
                node: WidthNode::Column(*align, children),
            }
        }
        View::Grid(style, rows) => {
            let columns = grid::columns(rows);
            let claims = column_claims(style, rows, &metrics.children, columns);

            // One `distribute` settles every column, and column j's width is
            // what every cell of column j resolves under.
            let mut widths = distribute_constraints(constraint.reference, constraint.cap, &claims);

            let mut placed = Vec::with_capacity(rows.len());
            for row in 0..rows.len() {
                let mut cells = Vec::with_capacity(columns);
                for (column, width) in widths.iter_mut().enumerate() {
                    let view = grid::cell(rows, row, column);
                    let inner = &metrics.children[row * columns + column];
                    let share = *width;

                    let mut padding = grid::cell_padding(style, view);
                    let across = degrade(Some(share), 0, 0, horizontal(padding), inner.floor);
                    if across.padding {
                        padding.left = 0;
                        padding.right = 0;
                    }

                    let child = place(
                        view,
                        inner,
                        Constraint::established(share.saturating_sub(horizontal(padding))),
                        bounded || matches!(claims[column].kind, Kind::Cells),
                        None,
                    );
                    // A cell wider than its share is a grapheme that could not
                    // be split, and it widens the column exactly as such a
                    // child widens a `Row`. Every cell of the column is placed
                    // in the wider one, so they still line up.
                    *width = (*width).max(child.width + horizontal(padding));
                    let (align, vertical_align) = grid::cell_alignment(view);
                    cells.push(GridCell {
                        padding,
                        align,
                        vertical_align,
                        child,
                    });
                }
                placed.push(cells);
            }

            let height_floor = placed
                .iter()
                .map(|row| {
                    row.iter()
                        .map(|cell| cell.child.height_floor + vertical(cell.padding))
                        .max()
                        .unwrap_or(0)
                })
                .sum();

            Widths {
                width: widths.iter().sum(),
                height_kind: metrics.height_kind,
                height_floor,
                height_projection: metrics.height_projection,
                node: WidthNode::Grid(GridBox {
                    columns: widths,
                    rows: placed,
                }),
            }
        }
        View::Viewport(viewport, child) => {
            let horizontal = viewport.horizontal_projection().is_some();
            let extent = constraint.reference;
            let child_constraint = if horizontal {
                Constraint {
                    reference: extent,
                    cap: None,
                }
            } else {
                constraint
            };
            let child = place(child, &metrics.children[0], child_constraint, bounded, None);
            Widths {
                width: if horizontal {
                    extent.unwrap_or(child.width)
                } else {
                    child.width
                },
                height_kind: metrics.height_kind,
                height_floor: metrics.height_floor,
                height_projection: metrics.height_projection,
                node: WidthNode::Viewport(viewport, bounded, Box::new(child)),
            }
        }
    }
}

fn title_width(style: &BlockStyle, title: Option<&BlockTitle>) -> usize {
    let Some(title) = title else {
        return 0;
    };
    debug_assert!(
        style.get_border().is_some() && style.get_border_top(),
        "a titled block requires an enabled top border"
    );
    if style.get_border().is_none() || !style.get_border_top() {
        return 0;
    }

    if title.text().as_str().is_empty() {
        return 0;
    }
    let text = title
        .text()
        .lines()
        .first()
        .map(|line| line.iter().map(|grapheme| grapheme.width()).sum())
        .unwrap_or(0);
    let border = border_extent(style).width();
    border
        .saturating_add(text)
        .saturating_add(usize::from(title.horizontal_padding()).saturating_mul(2))
}

/// The width a text leaf uses, without fitting a single line.
///
/// Fitting cannot widen a leaf past what the policy and the graphemes already
/// fix, and the area only caps: an area wider than the text never widens it, so
/// both policies stay at or below the natural width. `Overflow::Clip` cuts to
/// the area, with no floor, because a clip may cut a grapheme it cannot split.
/// Under `Overflow::Wrap` a line is at most the area, except where one grapheme
/// is wider than that — and a grapheme that cannot be split is exactly the
/// floor pass A measured. With no area at all, the leaf takes its own lines.
///
/// This is what keeps the phase order honest: the width of a text leaf is
/// decided from the text, never from what wrapping is about to do with it.
fn text_width(area: Option<usize>, overflow: &Overflow, metrics: &Metrics) -> usize {
    match (area, overflow) {
        (None, _) => metrics.natural,
        (Some(area), Overflow::Wrap) => area.min(metrics.natural).max(metrics.floor),
        (Some(area), Overflow::Clip(_)) => area.min(metrics.natural),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::{Border, TextStyle};

    fn text(content: &str) -> View {
        View::text(content, TextStyle::new())
    }

    fn natural(view: &View) -> usize {
        metrics(view).natural
    }

    fn floor(view: &View) -> usize {
        metrics(view).floor
    }

    fn fills(view: &View) -> bool {
        metrics(view).fills
    }

    #[test]
    fn text_is_measured_by_its_widest_line_and_its_widest_grapheme() {
        assert_eq!(natural(&text("ab\nabcd\nabc")), 4);
        assert_eq!(floor(&text("ab\nabcd\nabc")), 1);

        assert_eq!(natural(&text("日本語")), 6);
        assert_eq!(
            floor(&text("日本語")),
            2,
            "a wide character cannot be split"
        );
        assert_eq!(floor(&text("a👩‍💻")), 2, "nor can a cluster");

        assert_eq!(natural(&text("")), 0);
        assert_eq!(floor(&text("")), 0);
    }

    #[test]
    fn a_block_measures_its_frame_bounds_and_margin() {
        let bordered = View::block(
            BlockStyle::new().border(Border::NORMAL).padding((0, 1)),
            text("abc"),
        );
        assert_eq!(natural(&bordered), 7, "3 content + 2 padding + 2 border");
        assert_eq!(floor(&bordered), 5, "one grapheme plus the frame");

        let bounded = View::block(BlockStyle::new().max_width(2), text("abcd"));
        assert_eq!(natural(&bounded), 2, "the maximum caps the measure");

        let floored = View::block(BlockStyle::new().min_width(9), text("abcd"));
        assert_eq!(natural(&floored), 9);
        assert_eq!(floor(&floored), 9, "the minimum is a floor too");

        let spaced = View::block(BlockStyle::new().margin((0, 2)), text("ab"));
        assert_eq!(natural(&spaced), 6, "margin lies outside the box");
        assert_eq!(floor(&spaced), 5);
    }

    #[test]
    fn a_row_sums_its_children_and_a_column_takes_the_widest() {
        let children = [text("abcd"), text("日本")];
        let row = View::row(VerticalAlign::Top, children.clone());
        let column = View::column(Align::Left, children);

        assert_eq!(natural(&row), 8);
        assert_eq!(floor(&row), 3, "one grapheme from each child");
        assert_eq!(natural(&column), 4);
        assert_eq!(floor(&column), 2);
    }

    #[test]
    fn a_height_floor_is_the_frame_and_a_width_floor_is_the_content() {
        let bordered = View::block(BlockStyle::new().border(Border::NORMAL), text("abc"));

        assert_eq!(metrics(&text("abc")).height_floor, 0, "a row can be absent");
        assert_eq!(metrics(&bordered).height_floor, 2, "the frame cannot");
        assert_eq!(floor(&bordered), 3, "one grapheme plus it");

        let floored = View::block(BlockStyle::new().min_height(5), text("a"));
        assert_eq!(metrics(&floored).height_floor, 5);

        let spaced = View::block(BlockStyle::new().margin((1, 0)), text("a"));
        assert_eq!(metrics(&spaced).height_floor, 2, "margin lies outside");
    }

    #[test]
    fn a_view_fills_its_area_when_anything_inside_it_does() {
        let filling = View::block(BlockStyle::new().width(Length::fill(1)), text("a"));

        assert!(!fills(&text("a")));
        assert!(fills(&filling));
        assert!(
            fills(&View::block(BlockStyle::new(), filling.clone())),
            "an automatic box inherits its content's appetite"
        );
        assert!(
            !fills(&View::block(BlockStyle::new().width(4), filling.clone())),
            "a stated size settles the box, whatever it contains"
        );
        assert!(fills(&View::row(VerticalAlign::Top, [text("a"), filling])));
    }

    #[test]
    fn a_text_leaf_is_capped_by_its_area_and_never_widened_by_it() {
        let wide = metrics(&text("日本"));

        assert_eq!(text_width(None, &Overflow::Wrap, &wide), 4, "its own lines");
        assert_eq!(text_width(Some(3), &Overflow::Wrap, &wide), 3);
        assert_eq!(
            text_width(Some(10), &Overflow::Wrap, &wide),
            4,
            "an area wider than the text is a cap, not a size to take"
        );
        assert_eq!(
            text_width(Some(10), &Overflow::clip(), &wide),
            4,
            "nor is there anything for a clip to cut"
        );
        assert_eq!(
            text_width(Some(1), &Overflow::Wrap, &wide),
            2,
            "one unsplittable grapheme is wider than the area"
        );
        assert_eq!(
            text_width(Some(1), &Overflow::clip(), &wide),
            1,
            "a clip cuts to the area instead of widening"
        );
    }

    #[test]
    fn a_block_hands_its_content_width_down_and_keeps_its_own() {
        let view = View::block(
            BlockStyle::new().border(Border::NORMAL).padding((0, 1)),
            text("abcdefgh"),
        );

        let placed = widths(&view, Some(6));
        assert_eq!(placed.width, 6);
        let WidthNode::Block(block) = &placed.node else {
            panic!("a block");
        };
        assert_eq!(block.content_width, 2, "6 less two borders and two pads");
        assert_eq!(block.child.width, 2);
    }
}