zettcode-tui 0.4.0__py3-none-any.whl

zettcode/tui/render/color.py

@@ -0,0 +1,177 @@
+"""Terminal color depth and the SGR encoding derived from it."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from functools import lru_cache
+
+from .style import Style
+
+_CUBE_STEPS = (0, 95, 135, 175, 215, 255)
+
+_ANSI16_RGB: tuple[tuple[int, int, int], ...] = (
+    (0, 0, 0),
+    (205, 0, 0),
+    (0, 205, 0),
+    (205, 205, 0),
+    (0, 0, 238),
+    (205, 0, 205),
+    (0, 205, 205),
+    (229, 229, 229),
+    (127, 127, 127),
+    (255, 0, 0),
+    (0, 255, 0),
+    (255, 255, 0),
+    (92, 92, 255),
+    (255, 0, 255),
+    (0, 255, 255),
+    (255, 255, 255),
+)
+
+_ANSI256_RGB: tuple[tuple[int, int, int], ...] = (
+    *_ANSI16_RGB,
+    *((red, green, blue) for red in _CUBE_STEPS for green in _CUBE_STEPS for blue in _CUBE_STEPS),
+    *((level, level, level) for level in range(8, 8 + 24 * 10, 10)),
+)
+
+#: The 256-colour palette above its first sixteen entries. Indices 0-15 are the
+#: terminal's own theme colours, so a scheme is free to make "white" a mid grey;
+#: everything above them is a fixed RGB value the terminal renders as written.
+_ANSI256_FIXED_RGB = _ANSI256_RGB[len(_ANSI16_RGB) :]
+
+
+class ColorDepth(IntEnum):
+    """How many distinct colors the terminal can paint."""
+
+    MONO = 1
+    ANSI16 = 16
+    ANSI256 = 256
+    TRUECOLOR = 1 << 24
+
+
+@lru_cache(maxsize=1024)
+def parse_hex(value: str) -> tuple[int, int, int] | None:
+    """Parse ``#rrggbb`` into channels, returning None for anything else."""
+    digits = value.removeprefix("#")
+    if len(digits) != 6:
+        return None
+    try:
+        return int(digits[0:2], 16), int(digits[2:4], 16), int(digits[4:6], 16)
+    except ValueError:
+        return None
+
+
+def blend(first: str, second: str, amount: float) -> str:
+    """Return a colour ``amount`` of the way from ``first`` to ``second``.
+
+    Args:
+        first: Starting ``#rrggbb`` colour, used when ``amount`` is zero.
+        second: Ending ``#rrggbb`` colour, used when ``amount`` is one.
+        amount: Fraction between them, clamped to ``0..1``.
+
+    Either colour may be ``None`` or malformed, in which case the first is
+    returned unchanged: a palette is data, and an unusable one must not crash a
+    repaint.
+    """
+    start = parse_hex(first) if first is not None else None
+    end = parse_hex(second) if second is not None else None
+    if start is None or end is None:
+        return first
+    fraction = min(1.0, max(0.0, amount))
+    channels = (round(a + (b - a) * fraction) for a, b in zip(start, end, strict=True))
+    return "#" + "".join(f"{channel:02x}" for channel in channels)
+
+
+@lru_cache(maxsize=4096)
+def rgb_to_ansi256(red: int, green: int, blue: int) -> int:
+    """Return the closest fixed index in the standard 256-color palette.
+
+    Args:
+        red: Channel value in ``0..255``.
+        green: Channel value in ``0..255``.
+        blue: Channel value in ``0..255``.
+
+    The first sixteen palette entries alias the terminal's theme, where a
+    "white" that looks right on one setup is a dim grey on another. Body text
+    must not degrade like that, so they are skipped: the answer is always one of
+    the 240 fixed colours.
+    """
+    return _nearest(_ANSI256_FIXED_RGB, red, green, blue) + len(_ANSI16_RGB)
+
+
+@lru_cache(maxsize=4096)
+def rgb_to_ansi16(red: int, green: int, blue: int) -> int:
+    """Return the closest index in the standard 16-color palette.
+
+    Args:
+        red: Channel value in ``0..255``.
+        green: Channel value in ``0..255``.
+        blue: Channel value in ``0..255``.
+    """
+    return _nearest(_ANSI16_RGB, red, green, blue)
+
+
+def encode_style(style: Style, depth: ColorDepth = ColorDepth.TRUECOLOR) -> str:
+    """Encode one style as an SGR sequence for the given color depth.
+
+    Args:
+        style: Style to encode; colours are approximated, attributes are exact.
+        depth: How precisely the terminal can paint a colour. ``MONO`` drops
+            colours entirely but still emits bold, dim, italic, and reverse.
+    """
+    # SGR 0 first, so the run starts from a known state and an attribute that
+    # was set earlier can never survive into this one.
+    codes = ["0"]
+    if style.bold:
+        codes.append("1")  # SGR 1: bold
+    if style.dim:
+        codes.append("2")  # SGR 2: faint
+    if style.italic:
+        codes.append("3")  # SGR 3: italic
+    if style.strike:
+        codes.append("9")  # SGR 9: crossed out
+    if style.reverse:
+        codes.append("7")  # SGR 7: reverse video, used for text selection
+    if depth is not ColorDepth.MONO:
+        if style.foreground:
+            color = _color(style.foreground, depth, foreground=True)
+            if color:
+                codes.append(color)
+        if style.background:
+            color = _color(style.background, depth, foreground=False)
+            if color:
+                codes.append(color)
+    return f"\x1b[{';'.join(codes)}m"  # CSI ... m: Select Graphic Rendition
+
+
+def _color(value: str, depth: ColorDepth, *, foreground: bool) -> str:
+    """Encode one hex colour as the SGR parameters the depth supports."""
+    rgb = parse_hex(value)
+    if rgb is None:
+        return ""
+    # SGR 38 selects a foreground colour, 48 the background; the parameter that
+    # follows picks how the colour is spelled.
+    base = 38 if foreground else 48
+    if depth is ColorDepth.TRUECOLOR:
+        # ``;2;r;g;b`` is 24-bit colour, one byte per channel.
+        return f"{base};2;{rgb[0]};{rgb[1]};{rgb[2]}"
+    if depth is ColorDepth.ANSI256:
+        # ``;5;n`` indexes the 256-colour cube.
+        return f"{base};5;{rgb_to_ansi256(*rgb)}"
+    index = rgb_to_ansi16(*rgb)
+    if index < 8:
+        # SGR 30-37 for foreground and 40-47 for background name the base eight.
+        return str((30 if foreground else 40) + index)
+    # SGR 90-97 and 100-107 are the bright half of the same palette.
+    return str((90 if foreground else 100) + index - 8)
+
+
+def _nearest(palette: tuple[tuple[int, int, int], ...], red: int, green: int, blue: int) -> int:
+    """Return the index of the palette entry closest to one RGB triple."""
+    best_index = 0
+    best_distance: int | None = None
+    for index, (candidate_red, candidate_green, candidate_blue) in enumerate(palette):
+        distance = (candidate_red - red) ** 2 + (candidate_green - green) ** 2 + (candidate_blue - blue) ** 2
+        if best_distance is None or distance < best_distance:
+            best_index, best_distance = index, distance
+    return best_index

zettcode/tui/render/renderer.py

@@ -0,0 +1,151 @@
+"""ANSI differential renderer that writes only changed cell ranges."""
+
+from __future__ import annotations
+
+from io import StringIO
+from typing import TextIO
+
+from .canvas import Canvas
+from .color import ColorDepth, encode_style
+from .style import Cell, Style
+
+#: Synchronized output (DEC private mode 2026). A terminal that knows it holds back the screen from the first byte
+#: after ``BEGIN_SYNC`` to the ``END_SYNC``, then shows the whole frame at once; one that does not know it ignores
+#: the mode, as any terminal ignores a private mode it has no name for. Without it, a terminal may refresh while a
+#: frame is half parsed, and a quick drag shows what the frame was in the middle of: the old place erased and the
+#: new one not yet painted.
+BEGIN_SYNC = "\x1b[?2026h"
+END_SYNC = "\x1b[?2026l"
+#: DECTCEM hide and show, the pair this renderer moves the cursor with.
+HIDE_CURSOR = "\x1b[?25l"
+SHOW_CURSOR = "\x1b[?25h"
+
+#: Stands for "no frame has been written yet", which no cursor position equals.
+_UNKNOWN = object()
+
+
+class DifferentialRenderer:
+    """Write only changed cell ranges since the previous frame.
+
+    The vocabulary is deliberately small: Erase in Display (``ED``), Cursor
+    Position (``CUP``), Select Graphic Rendition (``SGR``), the cursor
+    show/hide pair, and the begin/end of a synchronized update. Anything else
+    would change a mode this renderer has no way to restore.
+
+    A frame that paints something is one synchronized update, drawn with the
+    cursor hidden and shown again where a widget wants it at the end, so a
+    terminal that cannot hold the update back still does not show the cursor
+    running across the cells as they are written.
+    """
+
+    def __init__(self, output: TextIO, *, color_depth: ColorDepth = ColorDepth.TRUECOLOR) -> None:
+        """Write frames to ``output`` at the given colour depth.
+
+        Args:
+            output: Text stream to write ANSI to; a real terminal or a StringIO
+                in tests.
+            color_depth: How precisely colours may be encoded.
+        """
+        self.output = output
+        self.color_depth = color_depth
+        self.previous: Canvas | None = None
+        #: Where the cursor was left by the last frame (``None`` is hidden), or ``_UNKNOWN`` before any frame: a
+        #: frame that changes no cell and wants the cursor where it already is has nothing to say.
+        self._cursor: tuple[int, int] | None | object = _UNKNOWN
+
+    def reset(self) -> None:
+        """Forget the previous frame so the next render repaints everything."""
+        self.previous = None
+        self._cursor = _UNKNOWN
+
+    def render(self, canvas: Canvas, *, cursor: tuple[int, int] | None = None) -> None:
+        """Emit only the cells that differ from the previous frame.
+
+        Args:
+            canvas: The frame to display.
+            cursor: Cell to place the terminal cursor on, or ``None`` to hide it.
+                A size change on canvas forces a full repaint regardless.
+        """
+        full = self.previous is None or (self.previous.width, self.previous.height) != (canvas.width, canvas.height)
+        stream = StringIO()
+        painted = False
+        if full:
+            # ED 2 erases the whole display. A resize renumbers every cell, so
+            # diffing against the old frame would leave stale glyphs behind.
+            stream.write("\x1b[2J")
+            painted = True
+        for y, row in enumerate(canvas.cells):
+            previous_row = None if full or self.previous is None else self.previous.cells[y]
+            if previous_row == row:
+                continue  # An untouched row costs no bytes at all.
+            painted = True
+            start, end = _changed_bounds(row, previous_row)
+            # CUP carries a 1-based row and column; the canvas is 0-based.
+            stream.write(f"\x1b[{y + 1};{start + 1}H")
+            active_style: Style | None = None
+            for cell in row[start : end + 1]:
+                if cell.continuation:
+                    continue  # The wide glyph's leading cell painted this column.
+                if cell.style != active_style:
+                    # SGR is stateful, so it is emitted only where a run's style
+                    # actually changes rather than once per cell.
+                    stream.write(encode_style(cell.style, self.color_depth))
+                    active_style = cell.style
+                stream.write(cell.character or " ")
+            # SGR 0 resets colour and attributes before the next CUP, so a run
+            # cannot bleed past the row it belongs to.
+            stream.write("\x1b[0m")
+        if cursor is None:
+            # DECTCEM hide: no widget asked for the cursor this frame. A frame that painted hid it before the first
+            # cell, so only a frame that painted nothing has to say so.
+            if not painted:
+                stream.write(HIDE_CURSOR)
+        else:
+            x, y = cursor
+            # Move first, then show: CUP on its own leaves the cursor hidden.
+            stream.write(f"\x1b[{y + 1};{x + 1}H{SHOW_CURSOR}")
+        frame = stream.getvalue()
+        if painted:
+            # The cursor goes first, so a terminal that ignores the update still never shows it mid-frame; the
+            # tail puts it back where a widget wants it.
+            frame = f"{BEGIN_SYNC}{HIDE_CURSOR}{frame}{END_SYNC}"
+        elif cursor == self._cursor:
+            # Nothing changed on the screen or at the cursor: there is nothing to send.
+            self.previous = canvas
+            return
+        self._cursor = cursor
+        self.output.write(frame)
+        self.output.flush()
+        self.previous = canvas
+
+
+def _changed_bounds(row: list[Cell], previous: list[Cell] | None) -> tuple[int, int]:
+    """Return an inclusive column range that safely repaints every changed cell.
+
+    Args:
+        row: The row being painted.
+        previous: The same row one frame earlier, or ``None`` when the frame is
+            painted from scratch, in which case the whole row counts as changed.
+
+    Returns:
+        ``(start, end)``, both inclusive. The range is widened outward to whole
+        glyphs, so it may cover cells that did not change; ``end < start`` means
+        the rows are identical and nothing has to be painted.
+    """
+    if previous is None:
+        return 0, len(row) - 1
+
+    changed = [index for index, cell in enumerate(row) if cell != previous[index]]
+    if not changed:
+        # An empty range keeps this a total function: a caller that forgot to
+        # skip an identical row gets "nothing to paint" instead of an IndexError.
+        return 0, -1
+    start, end = changed[0], changed[-1]
+
+    # A wide glyph occupies a leading cell plus one or more continuation cells.
+    # Include its leader so replacing either half never leaves a stale terminal glyph.
+    while start > 0 and (row[start].continuation or previous[start].continuation):
+        start -= 1
+    while end + 1 < len(row) and (row[end + 1].continuation or previous[end + 1].continuation):
+        end += 1
+    return start, end

zettcode/tui/render/rich_text.py

@@ -0,0 +1,80 @@
+"""Layout styled lines without requiring a mounted widget.
+
+RichText widgets and virtualized LineSources use the same column-aware
+wrapping and indentation. The resulting TextLines are plain render data;
+scrolling and focus stay with the widget that presents them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Literal, TypeAlias
+
+from .style import Span, Style, TextLine
+from .text import truncate_spans, wrap_spans
+
+Alignment: TypeAlias = Literal["left", "center", "right"]
+
+
+def inset_line(line: TextLine, columns: int) -> TextLine:
+    """Shift a nonblank line right, retaining the style of its first run."""
+    if columns <= 0 or not line.spans:
+        return line
+    first, *rest = line.spans
+    return TextLine((Span(" " * columns + first.text, first.style), *rest), metadata=line.metadata)
+
+
+def align_line(line: TextLine, columns: int) -> TextLine:
+    """Shift a line right by ``columns`` of plain space, leaving its own styling where it is.
+
+    This is not :func:`inset_line`, which gives the margin the style of the first run. That is
+    what a wrapped continuation wants — the indent of a list item belongs to the item — and it
+    is wrong for alignment: a run that carries a background would drag it across the whole
+    margin, and a line meant to be a pill would be a stripe from the edge of the screen to the
+    last word. The margin of an aligned line is empty.
+    """
+    if columns <= 0 or not line.spans:
+        return line
+    return TextLine((Span(" " * columns, Style()), *line.spans), metadata=line.metadata)
+
+
+def layout_rich_lines(
+    lines: Sequence[TextLine],
+    width: int,
+    *,
+    wrap: bool = True,
+    align: Alignment = "left",
+) -> tuple[TextLine, ...]:
+    """Wrap or truncate styled lines within a display-column budget.
+
+    ``TextLine.metadata`` may contain an integer hanging indent. That indent
+    is applied to continuation rows, so a list wraps beneath its own text.
+    Alignment adds space only to rows narrower than the available width.
+    """
+    if width <= 0:
+        return ()
+    if align not in ("left", "center", "right"):
+        raise ValueError(f"Unknown alignment: {align!r}")
+    laid_out: list[TextLine] = []
+    for line in lines:
+        indent = line.metadata if isinstance(line.metadata, int) and line.metadata > 0 else 0
+        if wrap:
+            rows = wrap_spans(line.spans, width)
+            if len(rows) > 1 and indent:
+                remainder = tuple(span for row in rows[1:] for span in row)
+                rows = [rows[0], *wrap_spans(remainder, max(1, width - min(indent, width - 1)))]
+        else:
+            rows = [truncate_spans(line.spans, width)]
+        for position, spans in enumerate(rows):
+            row = TextLine(tuple(spans))
+            if wrap and position and indent:
+                row = inset_line(row, min(indent, width - 1))
+            used = row.width
+            if used > width:
+                row = TextLine(truncate_spans(row.spans, width))
+                used = row.width
+            if align != "left" and used < width and row.spans:
+                gap = (width - used) // 2 if align == "center" else width - used
+                row = align_line(row, gap)
+            laid_out.append(row)
+    return tuple(laid_out)

zettcode/tui/render/style.py

@@ -0,0 +1,121 @@
+"""Styled text primitives shared by every render target."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - annotations only, avoids an import cycle
+    from .rich_text import Alignment
+
+
+@dataclass(frozen=True, slots=True)
+class Style:
+    """Terminal style independent from ANSI encoding.
+
+    Attributes:
+        foreground: Hex colour, or ``None`` to leave the terminal default.
+        background: Hex colour, or ``None`` for no background.
+        bold: Emit the bold attribute.
+        italic: Emit the italic attribute.
+        dim: Emit the faint attribute, used for de-emphasised structure.
+        strike: Emit the crossed-out attribute, used for text a writer removed.
+        reverse: Swap foreground and background; a text selection is painted
+            this way so it works over any colour underneath.
+    """
+
+    foreground: str | None = None
+    background: str | None = None
+    bold: bool = False
+    italic: bool = False
+    dim: bool = False
+    strike: bool = False
+    reverse: bool = False
+
+
+DEFAULT_STYLE = Style()
+
+
+_measure: Callable[[str], int] | None = None
+
+
+def _display_width() -> Callable[[str], int]:
+    """Return ``text.display_width``, imported the first time it is needed and kept.
+
+    ``text`` builds on the types in this module, so this module cannot import it when
+    it loads; asking for the function inside every call was a statement the
+    interpreter had to resolve each time, and a transcript measures a span tens of
+    thousands of times.
+    """
+    global _measure
+    if _measure is None:
+        from .text import display_width
+
+        _measure = display_width
+    return _measure
+
+
+@dataclass(frozen=True, slots=True)
+class Span:
+    """One styled text fragment.
+
+    Attributes:
+        text: Characters that share one style; no newlines.
+        style: Style applied to every character in ``text``.
+    """
+
+    text: str
+    style: Style = DEFAULT_STYLE
+
+    @property
+    def width(self) -> int:
+        """Return the columns this fragment paints, including wide glyphs."""
+        return _display_width()(self.text)
+
+
+@dataclass(frozen=True, slots=True)
+class TextLine:
+    """One logical line with optional component-owned metadata.
+
+    Attributes:
+        spans: Styled fragments in paint order.
+        metadata: Free-form slot for the component that produced the line; the
+            canvas ignores it, hit-testing and callers may read it.
+    """
+
+    spans: tuple[Span, ...] = ()
+    metadata: object | None = None
+
+    @property
+    def text(self) -> str:
+        """Return the concatenated text of every span."""
+        return "".join(span.text for span in self.spans)
+
+    @property
+    def width(self) -> int:
+        """Return the displayed column width of this line."""
+        measure = _display_width()
+        return sum(measure(span.text) for span in self.spans)
+
+    def layout(self, width: int, *, wrap: bool = True, align: Alignment = "left") -> tuple[TextLine, ...]:
+        """Lay out this line using the same rules as a RichText widget."""
+        from .rich_text import layout_rich_lines
+
+        return layout_rich_lines((self,), width, wrap=wrap, align=align)
+
+
+@dataclass(frozen=True, slots=True)
+class Cell:
+    """One terminal column; wide glyph tails use continuation=True.
+
+    Attributes:
+        character: Glyph drawn in this column, or ``""`` on a continuation cell.
+        style: Style of the cell; a continuation cell repeats its leader's style.
+        continuation: This cell is the second half of a wide glyph, so the
+            renderer must skip it and the leader must be repainted together.
+    """
+
+    character: str = " "
+    style: Style = DEFAULT_STYLE
+    continuation: bool = False

zettcode/tui/render/sweep.py

@@ -0,0 +1,87 @@
+"""A highlight that travels across a label, one span per brightness step.
+
+A wait is easier to read when something moves through it than when the whole row
+flips between two states: the eye follows the bright point, and the rest of the
+label keeps its ordinary colour, so the text never disappears mid-pulse.
+
+The effect is a span, not a widget. :class:`SweepSpan` is an ordinary
+:class:`~zettcode.tui.Span` — same text, same resting style — that also carries
+the colour of the bright point and the width of the ramp around it;
+:func:`sweep_spans` resolves one into the plain spans a renderer draws for a
+single frame.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+from .color import blend
+from .style import DEFAULT_STYLE, Span, Style
+from .text import character_width, display_width
+
+
+@dataclass(frozen=True, slots=True)
+class SweepSpan(Span):
+    """A run of text with a highlight that moves across it.
+
+    Attributes:
+        peak: Style of the character the highlight sits on; the colour in it is
+            blended towards :attr:`Span.style` on the way out, so a palette only
+            has to name the bright end.
+        ramp: Columns on either side that fade back to the resting style. The
+            highlight also spends this many columns off each end of the text, so
+            the sweep pauses instead of jumping back to the start.
+    """
+
+    peak: Style = DEFAULT_STYLE
+    ramp: int = 4
+
+    @property
+    def travel(self) -> int:
+        """Return how many columns one full pass takes, ends included."""
+        return display_width(self.text) + max(1, self.ramp) * 2
+
+
+def sweep_spans(span: SweepSpan, step: int) -> tuple[Span, ...]:
+    """Resolve one sweep into the spans to draw for a frame.
+
+    Args:
+        span: The label, its resting style, and its highlight.
+        step: Column the highlight has travelled to; it wraps every
+            :attr:`SweepSpan.travel` columns, so a renderer can pass a frame
+            counter straight in.
+
+    Adjacent characters that ended up with the same style are merged, so a label
+    costs at most ``2 * ramp + 1`` runs per frame.
+    """
+    ramp = max(1, span.ramp)
+    centre = (step % span.travel) - ramp
+    runs: list[Span] = []
+    column = 0
+    for character in span.text:
+        amount = 1.0 - abs(column - centre) / (ramp + 1)
+        runs.append(Span(character, _style_at(span, amount)))
+        column += character_width(character)
+    return _merge(runs)
+
+
+def _style_at(span: SweepSpan, amount: float) -> Style:
+    """Return the style for one character, ``amount`` along the ramp."""
+    if amount <= 0:
+        return span.style
+    if amount >= 1:
+        return span.peak
+    if span.style.foreground is None or span.peak.foreground is None:
+        return span.peak if amount > 0.5 else span.style
+    return replace(span.style, foreground=blend(span.style.foreground, span.peak.foreground, amount))
+
+
+def _merge(runs: list[Span]) -> tuple[Span, ...]:
+    """Join adjacent runs that share a style, so a frame draws few spans."""
+    merged: list[Span] = []
+    for run in runs:
+        if merged and merged[-1].style == run.style:
+            merged[-1] = Span(merged[-1].text + run.text, run.style)
+        else:
+            merged.append(run)
+    return tuple(merged)