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
//! The one pass: a [`View`] and an [`Available`] area in, one rectangle out.
//!
//! Resolution is a pure function of those two inputs — no terminal state, no
//! capability profile, no escape sequences. Its output is a [`ResolvedView`]:
//! a size and rows of graphemes carrying logical styles and the widths this
//! pass decided, which is the single thing both backends draw. That is why the
//! ANSI string and the Ratatui buffer cannot disagree about geometry.
//!
//! The pass is three phases, in the order `docs/design/layout-resolution.md`
//! fixes and in the only order the dependencies allow. [`width`](super::width)
//! settles every width, because wrapping needs a width to wrap to.
//! [`height`](super::height) then fits the text and counts the rows, because a
//! height is what wrapping produced. [`assemble`](super::assemble) then builds
//! the rectangle those numbers describe. At a Canvas leaf, each command
//! rasterizes against the settled dimensions without access to the destination
//! surface and is immediately passed to the common compositor. This module is
//! the entry point that runs the phases and the degenerate-case safety net that
//! bounds the result.

use crate::text::Grapheme;
use crate::{Key, TextStyle, View};

use super::assemble::{AssemblyCache, assemble, assemble_retained};
use super::geometry::{Available, Constraint, Size};
use super::height::{fit, heights};
use super::width::widths;

/// An axis for which a finite Canvas extent was required.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Axis {
    Width,
    Height,
}

/// The input whose finite extent is missing.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LayoutErrorKind {
    CanvasExtent,
    ViewAllocation,
    ViewportExtent,
}

/// A layout request that cannot produce finite geometry.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LayoutError {
    kind: LayoutErrorKind,
    axis: Axis,
}

impl LayoutError {
    pub const fn axis(&self) -> Axis {
        self.axis
    }
    pub const fn kind(&self) -> LayoutErrorKind {
        self.kind
    }
    pub(crate) const fn missing_extent(axis: Axis) -> Self {
        Self {
            kind: LayoutErrorKind::CanvasExtent,
            axis,
        }
    }
    pub(crate) const fn missing_allocation(axis: Axis) -> Self {
        Self {
            kind: LayoutErrorKind::ViewAllocation,
            axis,
        }
    }
    pub(crate) const fn missing_viewport_extent(axis: Axis) -> Self {
        Self {
            kind: LayoutErrorKind::ViewportExtent,
            axis,
        }
    }
}

impl std::fmt::Display for LayoutError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self.kind {
            LayoutErrorKind::CanvasExtent => write!(
                f,
                "Canvas requires an explicit {:?} on an unbounded axis",
                self.axis
            ),
            LayoutErrorKind::ViewAllocation => write!(
                f,
                "a Canvas View command with Fill requires a finite {:?} allocation",
                self.axis
            ),
            LayoutErrorKind::ViewportExtent => write!(
                f,
                "Viewport projection requires a finite {:?} allocation",
                self.axis
            ),
        }
    }
}

impl std::error::Error for LayoutError {}

/// One grapheme, the width it occupies, and its logical style.
///
/// A renderer cannot split a grapheme cluster or a wide character, because it
/// never sees text below this granularity, and it cannot disagree with the
/// layout pass about a width, because the width it needs is in the token.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StyledGrapheme {
    symbol: String,
    width: usize,
    style: TextStyle,
}

impl StyledGrapheme {
    /// Creates one styled grapheme, measuring the cells it occupies.
    ///
    /// The width is derived rather than supplied, so a token cannot claim a
    /// width its symbol does not have. Taking a [`Grapheme`] rather than a
    /// string closes the other half: a token holds one cluster, which is what
    /// a backend assumes when it writes the symbol into the cell its width
    /// starts at.
    ///
    /// Where a terminal-dependent measure would enter is
    /// [`text::width`](crate::text), the crate's one definition, and not this
    /// constructor. The pass still decides the width once and the renderers
    /// still read it here rather than measuring again.
    pub(crate) fn new(symbol: &Grapheme, style: TextStyle) -> Self {
        Self {
            symbol: symbol.as_str().to_owned(),
            width: symbol.width(),
            style,
        }
    }

    pub fn symbol(&self) -> &str {
        &self.symbol
    }

    pub const fn width(&self) -> usize {
        self.width
    }

    pub const fn style(&self) -> &TextStyle {
        &self.style
    }

    /// Creates one cell-wide blank carrying `style`.
    ///
    /// Renderers use this when a presentation layer replaces a resolved glyph
    /// while retaining cell styling such as its background color.
    pub fn space(style: TextStyle) -> Self {
        Self::new(Grapheme::space(), style)
    }
}

/// The part of an anchor rectangle that survived every enclosing clip.
///
/// Coordinates remain relative to the final [`ResolvedView`]. A clipped
/// rectangle is never moved onto an edge; this value is the true intersection.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct VisibleRect {
    x: i64,
    y: i64,
    width: usize,
    height: usize,
}

impl VisibleRect {
    pub const fn x(&self) -> i64 {
        self.x
    }

    pub const fn y(&self) -> i64 {
        self.y
    }

    pub const fn width(&self) -> usize {
        self.width
    }

    pub const fn height(&self) -> usize {
        self.height
    }
}

/// One anchor's complete logical rectangle and its visible intersection.
///
/// The logical rectangle is stated relative to the resolved view's own
/// top-left cell. It is translated but never clipped or rounded onto an edge.
/// [`visible`](Self::visible) separately reports what survived Block, Canvas,
/// Viewport, and final safety clips.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct AnchoredRect {
    key: Key,
    x: i64,
    y: i64,
    width: usize,
    height: usize,
    visible: Option<VisibleRect>,
}

impl AnchoredRect {
    pub(super) const fn new(key: Key, x: usize, y: usize, width: usize, height: usize) -> Self {
        Self {
            key,
            x: x as i64,
            y: y as i64,
            width,
            height,
            visible: Some(VisibleRect {
                x: x as i64,
                y: y as i64,
                width,
                height,
            }),
        }
    }

    /// The key the anchor carried.
    pub const fn key(&self) -> Key {
        self.key
    }

    /// Cells from the resolved view's left edge.
    pub const fn x(&self) -> i64 {
        self.x
    }

    /// Rows from the resolved view's top edge.
    pub const fn y(&self) -> i64 {
        self.y
    }

    pub const fn width(&self) -> usize {
        self.width
    }

    pub const fn height(&self) -> usize {
        self.height
    }

    /// Returns whether the region covers no cells, as a cursor anchor does.
    pub const fn is_empty(&self) -> bool {
        self.width == 0 || self.height == 0
    }

    /// Returns whether the [`ResolvedView`] this came from contains the whole
    /// region.
    ///
    /// A partially visible or outside region returns false. A zero-sized
    /// cursor point returns true only when it lies inside every half-open clip;
    /// a point on the right or bottom edge is outside.
    pub const fn is_within_resolved_view(&self) -> bool {
        match self.visible {
            Some(_) if self.width == 0 && self.height == 0 => true,
            Some(visible) => {
                visible.x == self.x
                    && visible.y == self.y
                    && visible.width == self.width
                    && visible.height == self.height
            }
            None => false,
        }
    }

    /// The part of the logical rectangle that survived every enclosing clip.
    pub const fn visible(&self) -> Option<VisibleRect> {
        self.visible
    }

    /// Settles
    /// [`is_within_resolved_view`](Self::is_within_resolved_view) against the
    /// rectangle this is reported with.
    pub(super) fn locate(mut self, resolved: Size) -> Self {
        self.clip(0, 0, resolved.width(), resolved.height());
        self
    }

    /// Moves the rectangle by the offset a parent nests it at.
    ///
    /// This is what assembly applies as it nests a rectangle inside a larger
    /// one: every offset a parent introduces — padding, a border, a margin, a
    /// sibling to the left, an alignment gap — moves the anchors within it.
    pub(super) const fn offset(mut self, x: i64, y: i64) -> Self {
        self.x = self.x.saturating_add(x);
        self.y = self.y.saturating_add(y);
        if let Some(visible) = &mut self.visible {
            visible.x = visible.x.saturating_add(x);
            visible.y = visible.y.saturating_add(y);
        }
        self
    }

    pub(super) fn clip(&mut self, x: i64, y: i64, width: usize, height: usize) {
        let Some(visible) = self.visible else {
            return;
        };
        let right = x.saturating_add(i64::try_from(width).unwrap_or(i64::MAX));
        let bottom = y.saturating_add(i64::try_from(height).unwrap_or(i64::MAX));

        if visible.width == 0 && visible.height == 0 {
            if visible.x < x || visible.x >= right || visible.y < y || visible.y >= bottom {
                self.visible = None;
            }
            return;
        }

        let visible_right = visible
            .x
            .saturating_add(i64::try_from(visible.width).unwrap_or(i64::MAX));
        let visible_bottom = visible
            .y
            .saturating_add(i64::try_from(visible.height).unwrap_or(i64::MAX));
        let left = visible.x.max(x);
        let top = visible.y.max(y);
        let clipped_right = visible_right.min(right);
        let clipped_bottom = visible_bottom.min(bottom);
        if clipped_right <= left || clipped_bottom <= top {
            self.visible = None;
            return;
        }
        self.visible = Some(VisibleRect {
            x: left,
            y: top,
            width: usize::try_from(clipped_right - left).unwrap_or(usize::MAX),
            height: usize::try_from(clipped_bottom - top).unwrap_or(usize::MAX),
        });
    }
}

/// A view resolved to one rectangle of styled graphemes.
///
/// Every row's widths sum to `size.width()`, and the row count equals
/// `size.height()`. Styles are logical: a
/// [`RenderSettings`](crate::RenderSettings) is applied when a renderer
/// serializes the rectangle, so capability resolution stays at the output
/// boundary.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ResolvedView {
    size: Size,
    rows: Vec<Vec<StyledGrapheme>>,
    anchors: Vec<AnchoredRect>,
}

/// An opt-in evaluator that reuses unchanged View evaluation across frames.
///
/// `Resolver` has the same observable result as [`resolve`]. It retains only
/// core reconciliation inputs and materialized output; the current View and
/// available area still decide layout. Application state, clocks, redraw
/// scheduling, terminal capabilities, and graphics protocol state stay with
/// the host that composes those independent capabilities.
///
/// The free [`resolve`] function remains the ordinary stateless path and does
/// not construct this cache metadata.
pub struct Resolver {
    previous_available: Option<Available>,
    previous_result: Option<ResolvedView>,
    assembly: AssemblyCache,
}

impl Resolver {
    /// Creates an empty retained evaluator.
    pub const fn new() -> Self {
        Self {
            previous_available: None,
            previous_result: None,
            assembly: AssemblyCache::new(),
        }
    }

    /// Resolves one immutable View snapshot, reusing unchanged subtree output.
    ///
    /// A changed Viewport origin reprojects its retained child. Changes to
    /// content or to a settled layout input invalidate the affected artifact,
    /// while independent unchanged subtrees remain reusable.
    pub fn resolve(
        &mut self,
        view: &View,
        available: Available,
    ) -> Result<ResolvedView, LayoutError> {
        if self.assembly.matches_previous_view(view)
            && self.previous_available == Some(available)
            && let Some(result) = &self.previous_result
        {
            return Ok(result.clone());
        }

        let fitted = fit(widths(view, available.width()));
        let sized = heights(&fitted, Constraint::available(available.height()));
        validate_canvas_extents(&sized)?;

        self.assembly.begin_frame(view);
        let mut rect = match assemble_retained(&sized, &mut self.assembly) {
            Ok(rect) => rect,
            Err(error) => {
                self.assembly.abort_frame();
                return Err(error);
            }
        };
        crop_to_available(&mut rect, available);
        let result = resolved(rect);
        self.assembly.finish_frame(view);
        self.previous_available = Some(available);
        self.previous_result = Some(result.clone());
        Ok(result)
    }

    /// Drops every retained evaluation artifact.
    pub fn clear(&mut self) {
        self.previous_available = None;
        self.previous_result = None;
        self.assembly.clear();
    }
}

impl Default for Resolver {
    fn default() -> Self {
        Self::new()
    }
}

impl ResolvedView {
    pub(crate) fn new(
        size: Size,
        rows: Vec<Vec<StyledGrapheme>>,
        anchors: Vec<AnchoredRect>,
    ) -> Self {
        Self {
            size,
            rows,
            anchors,
        }
    }

    pub const fn size(&self) -> Size {
        self.size
    }

    pub fn rows(&self) -> &[Vec<StyledGrapheme>] {
        &self.rows
    }

    /// Where each anchor in the tree landed, in tree order — a box before
    /// what it encloses.
    ///
    /// A tree carrying no anchor reports nothing, which is every view built
    /// before anchors existed.
    pub fn anchors(&self) -> &[AnchoredRect] {
        &self.anchors
    }

    /// The region reported under `key`.
    ///
    /// This is the ordinary read: a caller filling one region asks for it by
    /// name rather than scanning [`anchors`](Self::anchors).
    ///
    /// ```
    /// use urushi::{Available, BlockStyle, TextStyle, VerticalAlign, View, resolve};
    ///
    /// let view = View::row(
    ///     VerticalAlign::Top,
    ///     [View::text("> ", TextStyle::new()), View::anchor("cursor")],
    /// );
    /// let resolved = resolve(&view, Available::NONE).unwrap();
    ///
    /// assert_eq!(resolved.anchor("cursor").unwrap().x(), 2);
    /// assert!(resolved.anchor("elsewhere").is_none());
    /// ```
    pub fn anchor(&self, key: impl Into<Key>) -> Option<&AnchoredRect> {
        let key = key.into();
        self.anchors.iter().find(|anchor| anchor.key == key)
    }
}

/// Returns the intrinsic rectangle `view` occupies: its size when no area
/// bounds it.
///
/// This is [`resolve`] under [`Available::NONE`], not a second set of rules —
/// the same two sizing phases, stopping before the rectangle they describe is
/// built. No rectangle is allocated.
pub fn measure(view: &View) -> Size {
    try_measure(view).expect("intrinsic measurement requires every finite extent to be stated")
}

/// Tries to measure a view, reporting any required finite extent that is not
/// established within the tree.
pub fn try_measure(view: &View) -> Result<Size, LayoutError> {
    let fitted = fit(widths(view, None));
    let sized = heights(&fitted, Constraint::unbounded());
    validate_canvas_extents(&sized)?;
    Ok(Size::new(sized.width, sized.height))
}

/// Resolves `view` into one rectangle sized under `available`.
///
/// Every node resolves its own size under the area, so a bound reshapes a box
/// rather than cutting it. The crop below is the degenerate-case safety net:
/// it fires only when a rectangle could not be made to fit — an area that
/// cannot hold a frame at all — and it cuts grapheme-atomically.
pub fn resolve(view: &View, available: Available) -> Result<ResolvedView, LayoutError> {
    let fitted = fit(widths(view, available.width()));
    let sized = heights(&fitted, Constraint::available(available.height()));
    validate_canvas_extents(&sized)?;
    let mut rect = assemble(&sized)?;
    crop_to_available(&mut rect, available);
    Ok(resolved(rect))
}

fn crop_to_available(rect: &mut super::assemble::Rect, available: Available) {
    if let Some(width) = available.width() {
        rect.crop_width(width, &TextStyle::new());
    }
    if let Some(height) = available.height() {
        rect.crop_height(height);
    }
}

fn resolved(rect: super::assemble::Rect) -> ResolvedView {
    debug_assert_unique(&rect.anchors);
    let size = rect.size();
    let anchors = rect
        .anchors
        .into_iter()
        .map(|anchor| anchor.locate(size))
        .collect();
    ResolvedView::new(size, rect.rows, anchors)
}

fn validate_canvas_extents(sized: &super::height::Sized<'_>) -> Result<(), LayoutError> {
    use super::height::SizedNode;
    match &sized.node {
        SizedNode::Canvas {
            canvas,
            width_bounded,
            height_bounded,
            ..
        } => {
            if canvas.uses_viewport_sizing() && !width_bounded && canvas.explicit_width().is_none()
            {
                return Err(LayoutError::missing_extent(Axis::Width));
            }
            if canvas.uses_viewport_sizing()
                && !height_bounded
                && canvas.explicit_height().is_none()
            {
                return Err(LayoutError::missing_extent(Axis::Height));
            }
            Ok(())
        }
        SizedNode::Block { child, .. } => validate_canvas_extents(child),
        SizedNode::Viewport {
            viewport,
            width_bounded,
            height_bounded,
            child,
        } => {
            if viewport.horizontal_projection().is_some() && !width_bounded {
                return Err(LayoutError::missing_viewport_extent(Axis::Width));
            }
            if viewport.vertical_projection().is_some() && !height_bounded {
                return Err(LayoutError::missing_viewport_extent(Axis::Height));
            }
            validate_canvas_extents(child)
        }
        SizedNode::Row(_, children) | SizedNode::Column(_, children) => {
            children.iter().try_for_each(validate_canvas_extents)
        }
        SizedNode::Grid { rows, .. } => rows
            .iter()
            .flatten()
            .try_for_each(|cell| validate_canvas_extents(&cell.child)),
        SizedNode::Text { .. } => Ok(()),
    }
}

/// Asserts that no key names two regions.
///
/// One key, one region: a caller reads a region by the name it gave, and two
/// answers to one name is a mistake in the tree rather than something layout
/// can resolve. As with escape sequences in a `Text` node, this is a contract
/// violation detected as a development aid — debug builds assert, release
/// builds report both regions in tree order and leave the caller to whatever
/// it makes of them.
fn debug_assert_unique(anchors: &[AnchoredRect]) {
    debug_assert!(
        {
            let mut seen = std::collections::HashSet::with_capacity(anchors.len());
            anchors.iter().all(|anchor| seen.insert(anchor.key()))
        },
        "two anchors carry one key; a key names one region"
    );
}