supercode_frontend_tui/foundation/
width.rs

1// Derived from OpenAI Codex: codex-rs/tui/src/width.rs
2// Pinned source: 8604689ec5e3437eb79802d8d72249b7722fbf5b
3// Copyright 2025 OpenAI
4// Licensed under the Apache License, Version 2.0.
5// Modified by the Supercode contributors; see docs/legal/codex-frontend-extraction.toml.
6
7//! Width guards for transcript rendering with fixed prefix columns.
8//!
9//! Several rendering paths reserve a fixed number of columns for bullets,
10//! gutters, or labels before laying out content.  When the terminal is very
11//! narrow, those reserved columns can consume the entire width, leaving zero
12//! or negative space for content.
13//!
14//! These helpers centralise the subtraction and enforce a strict-positive
15//! contract: they return `Some(n)` where `n > 0`, or `None` when no usable
16//! content width remains.  Callers treat `None` as "render prefix-only
17//! fallback" rather than attempting wrapped rendering at zero width, which
18//! would produce empty or unstable output.
19
20/// Returns usable content width after reserving fixed columns.
21///
22/// Guarantees a strict positive width (`Some(n)` where `n > 0`) or `None` when
23/// the reserved columns consume the full width.
24///
25/// Treat `None` as "render prefix-only fallback". Coercing it to `0` and still
26/// attempting wrapped rendering often produces empty or unstable output at very
27/// narrow terminal widths.
28pub fn usable_content_width(total_width: usize, reserved_cols: usize) -> Option<usize> {
29    total_width
30        .checked_sub(reserved_cols)
31        .filter(|remaining| *remaining > 0)
32}
33
34/// `u16` convenience wrapper around [`usable_content_width`].
35///
36/// This keeps width math at callsites that receive terminal dimensions as
37/// `u16` while preserving the same `None` contract for exhausted width.
38pub fn usable_content_width_u16(total_width: u16, reserved_cols: u16) -> Option<usize> {
39    usable_content_width(usize::from(total_width), usize::from(reserved_cols))
40}
41
42#[cfg(test)]
43mod tests {
44    use super::*;
45    use pretty_assertions::assert_eq;
46
47    #[test]
48    fn usable_content_width_returns_none_when_reserved_exhausts_width() {
49        assert_eq!(
50            usable_content_width(/*total_width*/ 0, /*reserved_cols*/ 0),
51            None
52        );
53        assert_eq!(
54            usable_content_width(/*total_width*/ 2, /*reserved_cols*/ 2),
55            None
56        );
57        assert_eq!(
58            usable_content_width(/*total_width*/ 3, /*reserved_cols*/ 4),
59            None
60        );
61        assert_eq!(
62            usable_content_width(/*total_width*/ 5, /*reserved_cols*/ 4),
63            Some(1)
64        );
65    }
66
67    #[test]
68    fn usable_content_width_u16_matches_usize_variant() {
69        assert_eq!(
70            usable_content_width_u16(/*total_width*/ 2, /*reserved_cols*/ 2),
71            None
72        );
73        assert_eq!(
74            usable_content_width_u16(/*total_width*/ 5, /*reserved_cols*/ 4),
75            Some(1)
76        );
77    }
78}
supercode_frontend_tui/foundation/width.rs

supercode_frontend_tui/foundation/
width.rs
