tuile 0.9.0 → 0.11.0

data/book/09-styled-text.md

@@ -0,0 +1,132 @@
+# 9. Styled text
+
+Everything Tuile draws is, eventually, text with colors on it — a
+highlighted list row, a red error label, a border in the active accent.
+The value type that carries "text plus styling" through the whole
+framework is {Tuile::StyledString}, and it's worth one chapter of *why*,
+because the obvious representation — a plain `String` with ANSI escape
+codes threaded through it — is the one Tuile deliberately does *not* use.
+
+## Why not just a String with escape codes in it
+
+A terminal styles text with SGR escape sequences: `"\e[31mred\e[0m"` is
+the word "red" in red. It's tempting to treat a styled string as exactly
+that — a normal `String` that happens to contain those bytes — and let
+the terminal sort it out.
+
+The trouble shows up the moment you do anything *structural* to the text.
+Slice out columns 5 through 10: which colors are active at column 5? To
+answer, you have to scan every escape sequence from the start of the
+string, tracking the running SGR state, because the color at column 5 was
+set by some `\e[...m` that might be twenty characters earlier. Word-wrap
+it across a narrow viewport: every break point needs that same running
+state re-established on the next line, or the color bleeds or resets
+wrong. Concatenate two of them: whose reset wins? Every operation becomes
+"parse the SGR state machine, figure out what's active here, splice
+carefully." The escape codes and the text are tangled together, and the
+tangle has to be re-untangled on every edit.
+
+{Tuile::StyledString} untangles it once, structurally. A styled string is
+a sequence of **spans**, each a maximal run of characters that share one
+complete {Tuile::StyledString::Style} — foreground, background, bold,
+italic, underline, strikethrough. The spans are non-overlapping and tile
+the whole string: every character belongs to exactly one span, and that
+span's `style` *is* the character's style. There are no overlay layers to
+merge, no running state to reconstruct. "What's the style at column 5?"
+is just "which span contains column 5?" — a lookup, not a replay.
+
+That's the trade. You pay one extra type — you construct or parse a
+{Tuile::StyledString} instead of building a raw `String` — and in return
+slicing, wrapping, and concatenation become ordinary operations on a list
+of spans, each of which already knows its own style. For a framework that
+slices and wraps text constantly, on every repaint, that's the right side
+of the trade.
+
+## The algebra
+
+Once text is spans, the operations you'd want on a string come back, but
+style-aware. You concatenate with `+` (a plain `String` operand is parsed
+first, so embedded escapes round-trip). You take substrings by *display
+column* with `slice` — display column, not byte offset, because a
+fullwidth CJK character is two columns wide and a combining mark is zero,
+and the terminal cares about columns. You split on newlines with `lines`,
+word-wrap to a width with `wrap`, and truncate-with-ellipsis with
+`ellipsize`. Every one of them returns a fresh {Tuile::StyledString} with
+the spans carried across the cut intact — the value is immutable and its
+spans are frozen and shared, so these are cheap.
+
+Two details are worth knowing because they're choices, not accidents.
+Slicing **never splits a glyph**: if a two-column character straddles the
+boundary of your slice, it's dropped rather than rendered as half a
+character, which the terminal couldn't do anyway. "Glyph" there means a
+*grapheme cluster*, not a character, and the distinction is not pedantic —
+a letter plus its combining accent is two characters and one glyph, and a
+slice that kept the letter but dropped the mark would hand you back a
+visibly different word. Emoji make the same point louder: a thumbs-up plus
+a skin-tone modifier is two characters, one glyph, and two columns. Tuile
+measures clusters throughout and credits a combined emoji its real width
+rather than adding up its pieces, so text with emoji in it lays out and
+paints at the same size. And wrapping guarantees
+no output line exceeds the target width *whenever every character fits in
+that width* — a single glyph wider than the whole viewport still lands on
+its own line at its natural width, because there's nowhere narrower to put
+it. The exact signatures live in the rdoc; this is the shape of the
+toolbox.
+
+## Rendering and the minimal diff
+
+Two spans, both red, sitting next to each other, should not each re-emit
+`\e[31m` — the terminal is already red. {Tuile::StyledString#to_ansi}
+renders the spans to escape codes by **diffing** each span's style against
+the one before it, emitting only the codes that actually changed. A
+transition back to the plain default style emits a single `\e[0m` rather
+than laboriously turning each attribute off. The rendered run always
+closes with `\e[0m` if it ended non-default, so styling never bleeds into
+whatever the terminal prints next.
+
+This isn't just tidiness. The same style-diffing logic
+({Tuile::StyledString::Style#sgr_to}) is what the back buffer uses when it
+flushes changed cells to the terminal (chapter 2) — cell-to-cell there,
+span-to-span here, identical minimal sequences. Styled text and the
+flicker-free repaint model are the same idea at two scales: never rewrite
+what's already correct.
+
+## The parser: strict by default, lenient on request
+
+You can go the other way too — parse an ANSI-coded `String` *into* spans
+with {Tuile::StyledString.parse}. Here Tuile makes a sharp choice that's
+easy to get wrong, so it's worth stating plainly: **the parser is strict
+by default.**
+
+Strict means it recognizes exactly the SGR codes that map to a
+{Tuile::StyledString::Style}'s attributes — the foreground and background
+colors, bold, italic, underline, strikethrough — and *raises* on anything
+else. An unmodeled attribute like blink or reverse video, an unknown SGR
+code, a non-SGR escape like a cursor move or an OSC sequence: all of them
+are a {Tuile::StyledString::ParseError}, not a shrug. The reason is a
+contract worth protecting: `parse(to_ansi(x)) == x`. If parsing silently
+dropped what it didn't understand, that round-trip would quietly lie, and
+a styled string that survived a save/load cycle might come back subtly
+different. Strict parsing keeps the round-trip honest — anything the model
+can't represent is refused at the door, not swallowed.
+
+But strictness is wrong for one common job: piping in colored output you
+didn't produce and don't control — `git --color` through a pager, a build
+tool's output, anything that sprinkles cursor moves and exotic attributes
+you have no intention of modeling. For that, pass `lenient: true`. Now the
+parser keeps the colors and attributes it understands and **discards
+everything else** — unmodeled codes, malformed extended colors, cursor
+moves, OSC and other string sequences, stray escapes — instead of
+raising. It's lossy by definition (`parse(x, lenient: true)` does not
+round-trip back to `x`), and that's the point: "give me the colors, throw
+the rest away." Strict for text you own and must preserve exactly; lenient
+for text you're borrowing and only want the colors from.
+
+---
+
+{Tuile::StyledString} is the quiet primitive under everything visible.
+You rarely construct one by hand for simple cases — a {Tuile::Component::Label}
+takes a plain `String` and wraps it for you — but the moment you render
+your own content with per-span colors (a log line, a syntax-highlighted
+snippet, a diff), this is the type you're building, and the theming hook
+from chapter 6 is where you rebuild it when the palette changes.

data/book/README.md

@@ -29,7 +29,9 @@ theming (including live OS light/dark flips). Chapters 7–8 close out
 **narratively** — a tour of the shipped component toolbox framed around
 when and why to reach for each, and how to test a Tuile app end to end.
 Those two lean on the rdoc for the exact APIs; the guide keeps to the
-walkthroughs and use-cases.
+walkthroughs and use-cases. Chapter 9 is a **deep dive** on
+`Tuile::StyledString`, the text primitive under everything the framework
+draws — read it when you start rendering your own styled content.
 
 The book grows organically — a chapter exists when a concept has earned
 one, not to fill an outline.
@@ -50,7 +52,9 @@ one, not to fill an outline.
    the design. Top-down, absolute, integer coordinates; a parent
    assigns its children's `rect` and components never negotiate a size.
    The C64 argument for *why simple layouting is enough* on a character
-   grid, `Layout::Absolute` and the `rect=` override, `Fraction` for
+   grid, `Layout::Absolute` and the `rect=` override, the `Vertical` /
+   `Horizontal` box layouts and their three constraints (`Fixed` /
+   `Percent` / `Expand`) as sugar over that same rule, `Fraction` for
    sizing a popup against the screen, and resize as a discrete
    recompute. Geometry primitives (`Point` / `Size` / `Rect`) live here.
 4. **[The event loop and background work](04-event-loop.md).** The
@@ -59,21 +63,25 @@ one, not to fill an outline.
    `submit`, and how terminal resize (`SIGWINCH`) is plumbed through the
    same queue rather than handled off the signal.
 5. **[Focus and the keyboard](05-focus.md).** The focus chain and
-   `focusable?`, and the order in which a keystroke is offered to the
-   tree — Tab, global shortcuts, a component's `key_shortcut`, then
-   `handle_key`. How a focused text field swallows printable keys, and
-   how `keyboard_hint` drives the status bar.
+   `focusable?`, and the three-rung order in which a keystroke is offered
+   to the tree — Tab, global shortcuts, then `handle_key` delivered to
+   focus and bubbling up its ancestors. Why scope-wide keys (pane jumps, a
+   form's default button) belong on an ancestor, and how `keyboard_hint`
+   drives the status bar.
 6. **[Theming](06-theming.md).** Semantic color tokens read at paint
-   time, light/dark auto-detection at startup and live OS appearance
-   flips, pairing variants in a `ThemeDef`, app-specific custom tokens,
-   and rebuilding theme-derived content in `on_theme_changed`.
+   time, opt-in component backgrounds that inherit down the tree
+   (`bg_color`), light/dark auto-detection at startup and live OS
+   appearance flips, pairing variants in a `ThemeDef`, app-specific custom
+   tokens, and rebuilding theme-derived content in `on_theme_changed`.
 7. **[The component library](07-components.md).** A narrative tour of
    the shipped toolbox — Window, List, the text inputs and views,
-   Popup, and the window conveniences — framed around *when and why*
-   you reach for each. Signatures stay in the rdoc.
+   ProgressBar, Popup, and the window conveniences — framed around
+   *when and why* you reach for each. Signatures stay in the rdoc.
 8. **[Testing a Tuile app](08-testing.md).** The testing approach:
    `FakeScreen`, asserting against the painted buffer, driving
    invalidation, and PTY-based end-to-end tests of runnable scripts.
-
-All eight chapters are currently **stubs** — the skeleton is in place so
-the numbering is stable; prose lands chapter by chapter.
+9. **[Styled text](09-styled-text.md).** A deep dive on
+   `Tuile::StyledString`, the span-based "text plus styling" value type
+   under everything Tuile draws: why spans instead of a `String` full of
+   escape codes, the style-aware algebra (slice/wrap/concat by display
+   column), minimal-diff rendering, and the strict-vs-lenient parser.