Geometry and Unicode

struct Offset

A 2D displacement in cells. isbits.

Fields

• x::Int64: Horizontal component.

• y::Int64: Vertical component.

struct Region

An axis-aligned rectangle. 1-based and inclusive: the origin is the top-left cell (x, y) and the last cell is (x + width - 1, y + height - 1). isbits.

Fields

• x::Int64: Left edge, 1-based.

• y::Int64: Top edge, 1-based.

• width::Int64: Horizontal extent, in cells.

• height::Int64: Vertical extent, in cells.

Region(s::Size) -> Region

The region covering a Size anchored at the origin: Region(1, 1, w, h).

struct Size

A width x height extent in terminal cells. isbits.

Always width/height, never cols/rows.

Fields

• width::Int64: Horizontal extent, in cells.

• height::Int64: Vertical extent, in cells.

struct Spacing

Per-edge insets, in cells, in CSS order. isbits.

Fields

• top::Int64: Top inset.

• right::Int64: Right inset.

• bottom::Int64: Bottom inset.

• left::Int64: Left inset.

Spacing(vert::Int64, horz::Int64) -> Spacing

CSS two-value shorthand: vert on top/bottom, horz on left/right.

Spacing(all::Int64) -> Spacing

Uniform spacing on all four edges.

+(a::Offset, b::Offset) -> Offset

Componentwise sum of two offsets. Pure.

+(a::Size, b::Size) -> Size

Componentwise sum of two sizes. Pure.

+(a::Spacing, b::Spacing) -> Spacing

Fieldwise sum of two Spacing values. Pure.

-(a::Offset, b::Offset) -> Offset

Componentwise difference of two offsets. Pure.

in(o::Offset, r::Region) -> Bool

Containment test, inclusive at both ends. Pure.

intersect(a::Region, b::Region) -> Region

Overlap of two regions, or EMPTY_REGION when disjoint.

NEVER returns nothing: clipping is on the per-cell hot path and must stay type-stable. Pure.

isempty(r::Region) -> Bool

True when r covers no cell (width <= 0 || height <= 0). Pure.

issubset(a::Region, b::Region) -> Bool

True when every cell of a lies in b. Pure.

union(a::Region, b::Region) -> Region

Bounding box of two regions. An empty operand is the identity. Pure.

area(r::Region) -> Int64

Cell count of r, clamped at zero per axis. Pure.

bottom(r::Region) -> Int64

Bottom row of r, inclusive: r.y + r.height - 1. Pure.

clamp_size(s::Size, lo::Size, hi::Size) -> Size

Per-axis clamp of s between lo and hi. Pure.

clamp_to(r::Region, outer::Region) -> Region

Clip r to outer; identical to intersect. Pure.

grow(r::Region, s::Spacing) -> Region

Outset r by s. Pure.

horizontal(s::Spacing) -> Int64

Total horizontal inset: left + right. Pure.

origin(r::Region) -> Offset

Top-left cell of r as an Offset. Pure.

right(r::Region) -> Int64

Rightmost column of r, inclusive: r.x + r.width - 1. Pure.

shrink(r::Region, s::Spacing) -> Region

Inset r by s. Width and height CLAMP TO ZERO, never go negative: layout underflow must degrade to an empty region, not to garbage that crashes a writer. Pure.

size_of(r::Region) -> Size

Extent of r as a Size. Deliberately NOT Base.size: a Region is not an array. Pure.

split_col(r::Region, at::Int64) -> Tuple{Region, Region}

Split r vertically; at is the number of COLUMNS in the left piece. The two pieces partition r exactly. Pure.

at is clamped to 0:r.width, so neither piece ever has a negative extent and area(left) + area(right) == area(r) always holds.

split_row(r::Region, at::Int64) -> Tuple{Region, Region}

Split r horizontally; at is the number of ROWS in the top piece. The two pieces partition r exactly. Pure.

at is clamped to 0:r.height, so neither piece ever has a negative extent and area(top) + area(bottom) == area(r) always holds.

translate(r::Region, o::Offset) -> Region

Move r by o, keeping its extent. Pure.

vertical(s::Spacing) -> Int64

Total vertical inset: top + bottom. Pure.

First regional indicator, U+1F1E6 (letter A).

Last regional indicator, U+1F1FF (letter Z).

Variation Selector-15: forces text (narrow) presentation.

Variation Selector-16: forces emoji (wide) presentation.

Zero Width Joiner.

_uw_break_word!(
    out::Vector{String},
    word::AbstractString,
    w::Int64
) -> SubString{String}

Emit whole lines for a word wider than w and return the trailing remainder, whose text_width is <= w.

A single cluster wider than the entire budget is given a line of its own: halving it would corrupt the grid, and dropping it would lose content and spin this loop forever.

_uw_string_backed(s::String) -> String

Reinterpret any string as a String-backed one, without copying when it already is. Keeps truncate_width's return type SubString{String} type-stable for String and SubString{String} inputs alike.

_uw_wrap_line!(
    out::Vector{String},
    line::AbstractString,
    w::Int64
)

Greedily pack the words of one hard line into out.

char_width(c::AbstractChar) -> Int64

Display cells for a single CODEPOINT: 0, 1 or 2. Pure.

Per-codepoint width comes straight from the Unicode width tables (Base.textwidth on a Char, which is a table lookup, NOT the codepoint-summing string method this file exists to avoid). The result is clamped into 0:2, and an invalid codepoint measures 0 so this function is total and never throws on the render hot path.

grapheme_cells(
    s::AbstractString
) -> Vector{Tuple{String, Int64}}

Split s into (cluster, width) pairs – the unit a Buffer stores. Pure.

grapheme_width(g::AbstractString) -> Int64

Display cells for ONE grapheme cluster: 0, 1 or 2. Pure.

NORMATIVE rule, applied in order. Peek codepoints via iterate; MUST NOT collect (that allocates a Vector{Char} per cell per frame).

1. empty cluster -> 0
2. first two codepoints are both regional indicators -> 2
3. cluster contains VS16 (U+FE0F) -> 2
4. cluster ends with VS15 (U+FE0E) -> 1
5. base (first) codepoint is a control -> 0
6. otherwise clamp(char_width(base), 0, 2) – every trailing codepoint (ZWJ, skin tone modifier, combining mark) contributes 0.

is_combining(c::AbstractChar) -> Bool

True when c occupies no cell of its own. Pure.

is_regional_indicator(c::AbstractChar) -> Bool

True for U+1F1E6..U+1F1FF, the flag building blocks. Pure.

is_wide(c::AbstractChar) -> Bool

True when c occupies two cells. Pure.

text_width(s::AbstractString) -> Int64

Sum of grapheme_width over Unicode.graphemes(s). Pure.

NEVER uses textwidth(s).

truncate_width(
    s::AbstractString,
    w::Int64
) -> SubString{String}

Longest prefix of s whose text_width is <= w. A width-2 cluster that would straddle w is DROPPED, not halved. Pure.

wrap_width(s::AbstractString, w::Int64) -> Vector{String}

Greedy word wrap on text_width. Breaks mid-word only when a single word exceeds w. Never splits a grapheme cluster. Pure.

Words are whitespace-separated; an explicit newline is a hard break, so a blank input line survives as an empty output line.

abstract type Event

Supertype of every input/system event.

Fields

abstract type Widget

Base type of every UI component. Implementors provide exactly one required method: node(w::MyWidget)::WidgetNode.

Fields