sheetpeek 0.1.0__py3-none-any.whl

sheetpeek/__init__.py

@@ -0,0 +1,68 @@
+"""Render Excel workbooks as HTML, Markdown and terminal text, showing what Excel shows.
+
+``read`` gives a :class:`Sheet`: the cached values, number formats, styles, column widths,
+row heights and merged ranges of one worksheet. See ``ARCHITECTURE.md``.
+"""
+
+from __future__ import annotations
+
+from sheetpeek._model import (
+    Cell,
+    CellKind,
+    CellRange,
+    CellStyle,
+    CellValue,
+    Column,
+    Font,
+    HorizontalAlignment,
+    Row,
+    Sheet,
+    SheetState,
+    VerticalAlignment,
+)
+from sheetpeek._read import Book, open, read  # noqa: A004 - sheetpeek.open, like gzip.open
+from sheetpeek._rendered import (
+    Alignment,
+    Gap,
+    Mode,
+    RenderedCell,
+    RenderedColumn,
+    RenderedRow,
+    RenderedSheet,
+    SpillEdge,
+    TextRun,
+)
+from sheetpeek.backends import Backend, register_backend, render
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Alignment",
+    "Backend",
+    "Book",
+    "Cell",
+    "CellKind",
+    "CellRange",
+    "CellStyle",
+    "CellValue",
+    "Column",
+    "Font",
+    "Gap",
+    "HorizontalAlignment",
+    "Mode",
+    "RenderedCell",
+    "RenderedColumn",
+    "RenderedRow",
+    "RenderedSheet",
+    "Row",
+    "Sheet",
+    "SheetState",
+    "SpillEdge",
+    "TextRun",
+    "VerticalAlignment",
+    "__version__",
+    "open",
+    "read",
+    "register_backend",
+    "render",
+]

sheetpeek/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m sheetpeek``: the command line."""
+
+import sys
+
+from sheetpeek.cli import main
+
+sys.exit(main())

sheetpeek/_carlito.py

@@ -0,0 +1,47 @@
+"""Carlito's advance widths, for spacing Calibri text in HTML as Excel for Mac does.
+
+Generated by ``tools/carlito_widths.py`` from Carlito 1.104 (Copyright 2013 The Carlito
+Project Authors, https://github.com/googlefonts/carlito), which is licensed under the SIL Open
+Font License 1.1. Carlito is metric-compatible with Calibri. Only the advance widths are kept,
+in font units, for printable ASCII; no font data is included.
+"""
+
+UNITS_PER_EM = 2048
+FIRST = 32  # the advance of chr(FIRST + k) is ADVANCES[style][k]
+
+# fmt: off
+ADVANCES: dict[str, tuple[int, ...]] = {
+    "regular": (
+        463, 667, 821, 1020, 1038, 1464, 1397, 452, 621, 621, 1020, 1020, 511, 627, 517, 791, 1038,
+        1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 548, 548, 1020, 1020, 1020, 949, 1831,
+        1185, 1114, 1092, 1260, 1000, 941, 1292, 1276, 516, 653, 1064, 861, 1751, 1322, 1356, 1058,
+        1378, 1112, 941, 998, 1314, 1162, 1822, 1063, 998, 959, 628, 791, 628, 1020, 1020, 596, 981,
+        1076, 866, 1076, 1019, 625, 964, 1076, 470, 490, 931, 470, 1636, 1076, 1080, 1076, 1076,
+        714, 801, 686, 1076, 925, 1464, 887, 927, 809, 644, 943, 644, 1020,
+    ),
+    "bold": (
+        463, 667, 898, 1020, 1038, 1493, 1443, 478, 638, 638, 1020, 1020, 528, 627, 547, 880, 1038,
+        1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 565, 565, 1020, 1020, 1020, 949, 1840,
+        1241, 1148, 1084, 1291, 999, 940, 1305, 1292, 546, 678, 1120, 866, 1790, 1349, 1385, 1090,
+        1405, 1153, 968, 1014, 1337, 1211, 1856, 1128, 1064, 979, 665, 880, 665, 1020, 1020, 615,
+        1011, 1099, 857, 1099, 1031, 648, 971, 1099, 503, 523, 983, 503, 1666, 1099, 1101, 1099,
+        1099, 728, 817, 710, 1099, 969, 1526, 941, 970, 814, 704, 973, 704, 1020,
+    ),
+    "italic": (
+        463, 667, 821, 1020, 1038, 1464, 1397, 452, 621, 621, 1020, 1020, 511, 627, 517, 794, 1038,
+        1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 548, 548, 1020, 1020, 1020, 949, 1831,
+        1185, 1114, 1070, 1260, 1000, 941, 1292, 1276, 516, 653, 1064, 861, 1751, 1320, 1340, 1058,
+        1360, 1112, 926, 998, 1314, 1162, 1823, 1063, 998, 959, 628, 787, 628, 1020, 1020, 596,
+        1053, 1053, 852, 1053, 978, 625, 1053, 1053, 470, 490, 931, 470, 1620, 1053, 1051, 1053,
+        1053, 702, 797, 686, 1053, 913, 1464, 887, 916, 809, 644, 943, 644, 1020,
+    ),
+    "bold italic": (
+        463, 667, 898, 1020, 1038, 1493, 1443, 478, 638, 638, 1020, 1020, 528, 627, 547, 889, 1038,
+        1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 1038, 565, 565, 1020, 1020, 1020, 949, 1840,
+        1241, 1148, 1062, 1291, 999, 940, 1305, 1292, 546, 678, 1120, 866, 1790, 1344, 1369, 1090,
+        1387, 1153, 953, 1014, 1337, 1211, 1857, 1128, 1064, 979, 665, 870, 665, 1020, 1020, 615,
+        1081, 1081, 843, 1081, 1006, 648, 1081, 1080, 503, 523, 983, 503, 1646, 1080, 1080, 1081,
+        1081, 721, 807, 710, 1080, 961, 1526, 941, 963, 814, 704, 973, 704, 1020,
+    ),
+}
+# fmt: on

sheetpeek/_colors.py

@@ -0,0 +1,155 @@
+"""Resolve stored colors (RGB, indexed, theme with tint, automatic) to ``RRGGBB``.
+
+Theme colors follow ECMA-376: the theme's ``clrScheme`` gives the base color and ``tint``
+lightens or darkens it in HLS space (§18.8.19). Captured (suite ``theme_colors``, 96 cells):
+Excel's index order swaps the first two pairs, and the tint is applied in Windows' integer HLS
+on a scale of 240 (``ColorRGBToHLS``), the lightness truncated, which reproduces every cell.
+"""
+
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from collections.abc import Sequence
+
+_A = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+# clrScheme children in document order.
+_SCHEME = (
+    "dk1", "lt1", "dk2", "lt2", "accent1", "accent2", "accent3", "accent4", "accent5",
+    "accent6", "hlink", "folHlink",
+)  # fmt: skip
+# Excel's theme index → clrScheme entry: the light and dark pairs are swapped.
+_THEME_ORDER = (1, 0, 3, 2, 4, 5, 6, 7, 8, 9, 10, 11)
+_AUTOMATIC_INDEX = (64, 65)  # system foreground and background
+_HLS = 240  # Windows' HLSMAX
+_RGB = 255
+
+
+def theme_colors(theme_xml: bytes | str | None) -> tuple[str, ...]:
+    """The twelve theme colors as ``RRGGBB``, in Excel's theme index order.
+
+    A workbook without a theme part, or with an unreadable one, has no theme colors.
+    """
+    if not theme_xml:
+        return ()
+    try:
+        root = ET.fromstring(theme_xml)
+    except ET.ParseError:
+        return ()
+    scheme = root.find(f".//{_A}clrScheme")
+    if scheme is None:
+        return ()
+    found: dict[str, str] = {}
+    for name in _SCHEME:
+        entry = scheme.find(f"{_A}{name}")
+        if entry is None:
+            return ()
+        srgb = entry.find(f"{_A}srgbClr")
+        system = entry.find(f"{_A}sysClr")
+        if srgb is not None:
+            found[name] = srgb.get("val", "000000").upper()
+        elif system is not None:
+            found[name] = system.get("lastClr", "000000").upper()
+        else:
+            return ()
+    return tuple(found[_SCHEME[i]] for i in _THEME_ORDER)
+
+
+def resolve(
+    kind: str | None,
+    value: str | int | None,
+    tint: float,
+    theme: Sequence[str],
+    palette: Sequence[str],
+) -> str | None:
+    """A stored color as ``RRGGBB``, or ``None`` for automatic or unresolvable colors.
+
+    Args:
+        kind: How the file states the color: ``rgb``, ``indexed``, ``theme``, or anything else
+            (``auto``, missing) for automatic.
+        value: ``AARRGGBB`` or ``RRGGBB`` text for ``rgb``; the index for ``indexed`` and
+            ``theme``.
+        tint: Lightening (positive) or darkening (negative), from -1 to 1.
+        theme: Theme colors in Excel's index order (:func:`theme_colors`).
+        palette: The indexed palette as ``AARRGGBB`` strings (custom or default).
+    """
+    if kind == "rgb":
+        if not isinstance(value, str) or len(value) not in (6, 8):
+            return None
+        base = value[-6:].upper()
+    elif kind == "indexed":
+        if not isinstance(value, int) or value in _AUTOMATIC_INDEX or not 0 <= value < len(palette):
+            return None
+        base = palette[value][-6:].upper()
+    elif kind == "theme":
+        if not isinstance(value, int) or not 0 <= value < len(theme):
+            return None
+        base = theme[value]
+    else:
+        return None
+    return apply_tint(base, tint) if tint else base
+
+
+def apply_tint(rgb: str, tint: float) -> str:
+    """Lighten (``tint > 0``) or darken (``tint < 0``) an ``RRGGBB`` color as Excel does.
+
+    ECMA-376's tint on the lightness, in Windows' integer HLS (scale 240): darkening multiplies
+    the lightness by ``1 + tint``, lightening moves it ``tint`` of the way to white, and the
+    result is truncated (captured, suite ``theme_colors``).
+    """
+    if not tint:
+        return rgb
+    hue, lightness, saturation = _to_hls(*(int(rgb[i : i + 2], 16) for i in (0, 2, 4)))
+    tinted = lightness * (1 + tint) if tint < 0 else lightness * (1 - tint) + _HLS * tint
+    red, green, blue = _to_rgb(hue, max(0, min(_HLS, int(tinted))), saturation)
+    return f"{red:02X}{green:02X}{blue:02X}"
+
+
+def _to_hls(red: int, green: int, blue: int) -> tuple[int, int, int]:
+    """Windows' ``ColorRGBToHLS``: hue, lightness and saturation from 0 to 240."""
+    high, low = max(red, green, blue), min(red, green, blue)
+    lightness = ((high + low) * _HLS + _RGB) // (2 * _RGB)
+    if high == low:
+        return 0, lightness, 0
+    spread, total = high - low, high + low
+    if lightness <= _HLS // 2:
+        saturation = (spread * _HLS + total // 2) // total
+    else:
+        saturation = (spread * _HLS + (2 * _RGB - total) // 2) // (2 * _RGB - total)
+    sixth = _HLS // 6
+    r, g, b = (((high - c) * sixth + spread // 2) // spread for c in (red, green, blue))
+    if red == high:
+        hue = b - g
+    elif green == high:
+        hue = _HLS // 3 + r - b
+    else:
+        hue = 2 * _HLS // 3 + g - r
+    return hue % _HLS, lightness, saturation
+
+
+def _to_rgb(hue: int, lightness: int, saturation: int) -> tuple[int, int, int]:
+    """Windows' ``ColorHLSToRGB``."""
+    if saturation == 0:
+        grey = (lightness * _RGB + _HLS // 2) // _HLS
+        return grey, grey, grey
+    if lightness <= _HLS // 2:
+        high = (lightness * (_HLS + saturation) + _HLS // 2) // _HLS
+    else:
+        high = lightness + saturation - (lightness * saturation + _HLS // 2) // _HLS
+    low = 2 * lightness - high
+    red, green, blue = (
+        (_hue(low, high, hue + shift) * _RGB + _HLS // 2) // _HLS
+        for shift in (_HLS // 3, 0, -_HLS // 3)
+    )
+    return red, green, blue
+
+
+def _hue(low: int, high: int, hue: int) -> int:
+    hue %= _HLS
+    sixth = _HLS // 6
+    if hue < sixth:
+        return low + ((high - low) * hue + _HLS // 12) // sixth
+    if hue < _HLS // 2:
+        return high
+    if hue < 2 * _HLS // 3:
+        return low + ((high - low) * (2 * _HLS // 3 - hue) + _HLS // 12) // sixth
+    return low

sheetpeek/_excel.py

@@ -0,0 +1,408 @@
+"""``excel`` mode: a sheet laid out in points, as Excel for Mac lays it out.
+
+Columns take xlformat's widths in points and rows the heights of ``ARCHITECTURE.md`` §4.7. Each
+cell is formatted at its column's width in dialog units (a merge at its merged width), then
+placed by its alignment and spilled into free neighbors by the rules of §4.1, in points. The
+result is a list of :class:`~sheetpeek.TextRun` per row, with each run's clip window, and the
+column boundaries text crosses. Two spills may take the same free cell; both are kept, as Excel
+draws both.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import xlformat
+
+from sheetpeek._layout import (
+    _column_hidden,
+    _edge_columns,
+    _Fonts,
+    _Formatter,
+    _Grid,
+    _Origin,
+    _Shown,
+)
+from sheetpeek._model import Column, Row, Sheet
+from sheetpeek._rendered import RenderedCell, RenderedColumn, RenderedRow, RenderedSheet, TextRun
+from sheetpeek._rows import (
+    WRAPPED_LEADING,
+    baseline_offsets,
+    fits_cells,
+    font_row_height,
+    row_height,
+    wrapped_height,
+)
+
+_COLUMN_PADDING = 5.0  # points of a column not counted in its dialog units (xlformat)
+
+
+def dialog_units(points: float, digit_width: float) -> float:
+    """The Column Width dialog number of a column ``points`` wide, for a merged width.
+
+    Provisional: inverts xlformat's ``column_points`` (``round(MDW * w + 5)``, below one unit
+    ``round(w * (MDW + 5))``) until xlformat accepts widths in points.
+    """
+    if points < digit_width + _COLUMN_PADDING:
+        return points / (digit_width + _COLUMN_PADDING)
+    return (points - _COLUMN_PADDING) / digit_width
+
+
+def lay_out(
+    sheet: Sheet, columns: list[Column], rows: list[Row], warnings: list[str], fonts: _Fonts
+) -> RenderedSheet:
+    """Lay out the visible ``columns`` and ``rows`` of a sheet in points."""
+    normal = fonts.get(sheet.normal_font)
+
+    def metrics(column: Column) -> xlformat.ColumnMetrics:
+        return xlformat.file_column_metrics(
+            column.width,
+            base_col_width=sheet.base_column_width,
+            default_col_width=sheet.default_column_width,
+            font=normal,  # the Normal font: xlformat names it font= here, unlike format_cell
+        )
+
+    base = metrics(Column(1))
+    if sheet.ref is None or not columns or not rows:
+        rendered = tuple(
+            RenderedColumn(c.index, None, _column_hidden(c), False, 0.0, _points(c, metrics))
+            for c in columns
+        )
+        return RenderedSheet(sheet, "excel", _placed(rendered), (), 0, tuple(warnings))
+    # Added columns are at the default width; a text spills at most twice a digit per character.
+    before, after = _edge_columns(sheet, max(1, int(base.points // (2 * base.digit_width))))
+    every = before + columns + after
+    widths = [_points(c, metrics) for c in every]
+    added = set(range(len(before))) | set(range(len(before) + len(columns), len(every)))
+    grid = _Grid(
+        sheet, rows, every, [0] * len(every), added, 0, False, _Formatter(sheet, warnings, fonts)
+    )
+
+    blocks: dict[tuple[int, int], float | None] = {}
+
+    def units(cols: list[int]) -> float | None:
+        key = (cols[0], cols[-1])
+        if key not in blocks:
+            total = sum(widths[p] for p in cols)
+            blocks[key] = dialog_units(total, base.digit_width) if total > 0 else None
+        return blocks[key]
+
+    grid.units = units
+    heights = [_fitted(grid, i, row, sheet, widths, base, fonts) for i, row in enumerate(rows)]
+    layout = _Points(grid, widths, heights, base, fonts)
+    rendered_rows, kept = layout.render()
+    x0 = layout.xs[kept[0]]
+    rendered_columns = tuple(
+        RenderedColumn(
+            every[p].index,
+            None,
+            _column_hidden(every[p]),
+            p in added,
+            layout.xs[p] - x0,
+            widths[p],
+        )
+        for p in kept
+    )
+    return RenderedSheet(sheet, "excel", rendered_columns, rendered_rows, 0, tuple(warnings))
+
+
+def _fitted(
+    grid: _Grid,
+    i: int,
+    row: Row,
+    sheet: Sheet,
+    widths: list[float],
+    base: xlformat.ColumnMetrics,
+    fonts: _Fonts,
+) -> float:
+    """A row's height, fitted to its cells as Excel fits it on opening (§4.7)."""
+    height = row_height(row, sheet)
+    if not fits_cells(row, sheet):
+        return height
+    for p in range(len(grid.columns)):
+        if p in grid.added:
+            continue
+        cell = grid.cell(i, p)
+        height = max(height, font_row_height(cell.font))
+        # A merged cell's font counts, its wrapped lines do not (captured).
+        merged = (row.index, grid.columns[p].index) in grid.merge_of
+        if cell.kind == "text" and cell.style.wrap and widths[p] and not merged:
+            budget = widths[p] - base.left_inset - base.right_inset
+            lines = _wrap(str(cell.value), budget, fonts.get(cell.font))
+            height = max(height, wrapped_height(len(lines), cell.font))
+    return height
+
+
+def _points(column: Column, metrics: Any) -> float:
+    return 0.0 if _column_hidden(column) else float(metrics(column).points)
+
+
+def _placed(columns: tuple[RenderedColumn, ...]) -> tuple[RenderedColumn, ...]:
+    """Columns with their x positions as running sums of their widths."""
+    x, result = 0.0, []
+    for c in columns:
+        result.append(RenderedColumn(c.index, None, c.hidden, c.added, x, c.width_pt))
+        x += c.width_pt or 0.0
+    return tuple(result)
+
+
+class _Points:
+    """Places every origin's text in points: runs, clips, spill and crossed boundaries."""
+
+    def __init__(
+        self,
+        grid: _Grid,
+        widths: list[float],
+        heights: list[float],
+        base: xlformat.ColumnMetrics,
+        fonts: _Fonts,
+    ) -> None:
+        self.grid = grid
+        self.widths = widths
+        self.heights = heights
+        self.left_inset = base.left_inset
+        self.right_inset = base.right_inset
+        self.digit = base.digit_width
+        self.fonts = fonts
+        self.xs = _running(widths)
+        self.ys = _running(heights)
+        self.no_claims: set[tuple[int, int]] = set()  # both competing spills take a cell
+
+    def render(self) -> tuple[tuple[RenderedRow, ...], list[int]]:
+        grid = self.grid
+        origins, shown = grid.origins()
+        runs: dict[int, list[TextRun]] = {}
+        crossed: set[tuple[int, int]] = set()  # (row position, p): boundary between p and p + 1
+        spans: list[tuple[int, int]] = []
+        lines_of: dict[int, int] = {}
+        spill_of: dict[tuple[int, int], tuple[int, int]] = {}
+        for origin in origins:
+            placed, low, high, count = self.place(origin)
+            if not placed:
+                continue
+            runs.setdefault(origin.rows[0], []).extend(placed)
+            spans.append((low, high))
+            for i in origin.rows:
+                for p in range(low, high):
+                    crossed.add((i, p))
+            spill_of[(origin.cell.row, origin.cell.column)] = (
+                origin.cols[0] - low,
+                high - origin.cols[-1],
+            )
+            if len(origin.rows) == 1:
+                i = origin.rows[0]
+                lines_of[i] = max(lines_of.get(i, 1), count)
+        real = [p for p in range(len(grid.columns)) if p not in grid.added]
+        reached = [p for low, high in spans for p in (low, high) if p in grid.added]
+        kept = list(range(min([*reached, real[0]]), max([*reached, real[-1]]) + 1))
+        x0 = self.xs[kept[0]]
+        result = []
+        for i, row in enumerate(grid.rows):
+            cells = []
+            for p in kept:
+                cell = grid.cell(i, p)
+                position = (row.index, grid.columns[p].index)
+                merge = grid.merge_of.get(position)
+                show = shown.get(position, _Shown())
+                cells.append(
+                    RenderedCell(
+                        cell=cell,
+                        text=show.text,
+                        full_text=show.full_text,
+                        overflow=show.overflow,
+                        align=show.align,
+                        format_color=show.format_color,
+                        merge=merge,
+                        spill=spill_of.get(position, (0, 0)),
+                        lines=(),
+                        source=None,
+                        fill=grid.anchor_fill(merge) if merge else cell.fill,
+                        font=None,
+                        color=None,
+                    )
+                )
+            row_runs = tuple(_shifted(run, x0) for run in runs.get(i, ()))
+            result.append(
+                RenderedRow(
+                    row.index,
+                    row,
+                    lines_of.get(i, 1),
+                    tuple(cells),
+                    (),
+                    self.ys[i],
+                    self.heights[i],
+                    row_runs,
+                    tuple((i, p) in crossed for p in kept[:-1]),
+                )
+            )
+        return tuple(result), kept
+
+    def place(self, origin: _Origin) -> tuple[list[TextRun], int, int, int]:
+        """The runs of one origin, the columns its text spans, and its line count."""
+        cell, shown = origin.cell, origin.shown
+        first, last = origin.cols[0], origin.cols[-1]
+        if not shown.text:
+            return [], first, last, 0
+        x0, x1 = self.xs[first], self.xs[last] + self.widths[last]
+        top = self.ys[origin.rows[0]]
+        bottom = self.ys[origin.rows[-1]] + self.heights[origin.rows[-1]]
+        font = self.fonts.get(cell.font)
+        align = shown.align
+        budget = (x1 - x0) - self.left_inset - self.right_inset
+        wraps = cell.kind == "text" and (cell.style.wrap or align in ("justify", "distributed"))
+        text = shown.text
+        # a line break in a cell without wrapping is not drawn
+        lines = _wrap(text, budget, font) if wraps else [text.replace("\r", "").replace("\n", "")]
+        line, above, below = baseline_offsets(cell.font)
+        n = len(lines)
+        if n > 1:
+            line += WRAPPED_LEADING  # provisional: the pitch of a fitted wrapped row
+        v_align = cell.style.v_align
+        if n * line > bottom - top:
+            # Lines that do not fit start at the top: a custom-height row shows its first line
+            # (captured, layout rows 161 to 168; unverified for centered text).
+            first_baseline = top + above
+        elif v_align == "center":
+            first_baseline = top + math.floor((bottom - top - n * line) / 2) + above
+        elif v_align == "bottom":
+            first_baseline = bottom - below - (n - 1) * line
+        else:
+            first_baseline = top + above
+        indent = cell.style.indent * self.digit
+        color = shown.format_color or cell.font.color
+        source = (cell.row, cell.column)
+        low, high = first, last
+        placed: list[tuple[str, float, str, float]] = []  # (text, x, anchor, baseline)
+        for k, line_text in enumerate(lines):
+            baseline = first_baseline + k * line
+            width = xlformat.text_width(line_text, font=font)
+            words = line_text.split()
+            if align == "fill":
+                copies = max(1, math.floor(budget / width)) if width else 1
+                pieces = [(line_text * copies, x0 + self.left_inset, "left")]
+            elif align == "distributed" or (align == "justify" and k < n - 1 and len(words) > 1):
+                pieces = self.spread(words, x0, x1, font, align == "distributed")
+            elif align == "right" and not shown.overflow:
+                pieces = [(line_text, x1 - self.right_inset - indent - width, "right")]
+            elif align == "center" or shown.overflow:
+                # A # run is centered whatever the alignment (captured, layout rows 130 to 136).
+                x = x0 + 1 + math.ceil((x1 - x0 - 1 - width) / 2)
+                pieces = [(line_text, x, "center")]
+            else:
+                pieces = [(line_text, x0 + self.left_inset + indent, "left")]
+            if origin.spills and n == 1 and align in ("left", "right", "center"):
+                x = pieces[0][1]
+                low, high = self.spill(origin, x, x + width, align)
+            placed.extend((piece, x, anchor, baseline) for piece, x, anchor in pieces)
+        clip = (self.xs[low] + 1, top + 1, self.xs[high] + self.widths[high], bottom)
+        runs = [
+            TextRun(
+                piece,
+                x,
+                baseline,
+                xlformat.text_width(piece, font=font),
+                clip,
+                anchor,  # type: ignore[arg-type]
+                source,
+                cell.font,
+                color,
+            )
+            for piece, x, anchor, baseline in placed
+            if piece
+        ]
+        return runs, low, high, n
+
+    def spread(
+        self, words: list[str], x0: float, x1: float, font: xlformat.Font, distributed: bool
+    ) -> list[tuple[str, float, str]]:
+        """Words spread across the cell between its insets.
+
+        A single word is centered there when ``distributed`` and left-aligned otherwise.
+        """
+        lo, hi = x0 + self.left_inset, x1 - self.right_inset
+        widths = [xlformat.text_width(w, font=font) for w in words]
+        if len(words) == 1:
+            if distributed:
+                return [(words[0], lo + math.floor((hi - lo - widths[0]) / 2), "center")]
+            return [(words[0], lo, "left")]
+        gap = (hi - lo - sum(widths)) / (len(words) - 1)
+        result, x = [], lo
+        for word, width in zip(words, widths, strict=True):
+            result.append((word, x, "left"))
+            x += width + gap
+        return result
+
+    def spill(self, origin: _Origin, x: float, end: float, align: str) -> tuple[int, int]:
+        """The visible column positions a single line from ``x`` to ``end`` spans (§4.1).
+
+        Left text takes a column to the right once its end passes that column's gridline. Right
+        text takes one to the left once its start reaches the far edge of its own leftmost
+        gridline: the one-point asymmetry Excel shows (captured). Centered text takes a column
+        on both sides at once while it overflows either edge; once one side is blocked, the
+        other grows only as far as its own text needs (captured). A cell holding a value, or
+        merged, blocks.
+        """
+        i = origin.rows[0]
+        first, last = origin.cols[0], origin.cols[-1]
+        left = right = 0
+        left_open = right_open = True
+        while True:
+            lo = self.xs[first - left]
+            hi = self.xs[last + right] + self.widths[last + right]
+            need_left = x <= lo + 1 if align == "right" else x < lo + 1
+            need_right = end > hi
+            if not (need_left or need_right):
+                break
+            left_open = left_open and self.grid.free(i, first - left - 1, self.no_claims)
+            right_open = right_open and self.grid.free(i, last + right + 1, self.no_claims)
+            centered = align == "center" and left_open and right_open
+            grow_left = left_open and (need_left or centered)
+            grow_right = right_open and (need_right or centered)
+            if not (grow_left or grow_right):
+                break
+            left += grow_left
+            right += grow_right
+        return first - left, last + right
+
+
+def _running(sizes: list[float]) -> list[float]:
+    positions, total = [], 0.0
+    for size in sizes:
+        positions.append(total)
+        total += size
+    return positions
+
+
+def _shifted(run: TextRun, dx: float) -> TextRun:
+    if not dx:
+        return run
+    left, top, right, bottom = run.clip
+    return TextRun(
+        run.text, run.x - dx, run.y, run.width, (left - dx, top, right - dx, bottom),
+        run.align, run.source, run.font, run.color,
+    )  # fmt: skip
+
+
+def _wrap(text: str, budget: float, font: xlformat.Font) -> list[str]:
+    """Lines of ``text`` broken at spaces to fit ``budget`` points; explicit breaks kept.
+
+    A word wider than the budget is broken between characters.
+    """
+    lines: list[str] = []
+    for paragraph in text.replace("\r", "").split("\n"):
+        line = ""
+        for word in paragraph.split(" "):
+            candidate = f"{line} {word}" if line else word
+            if line and xlformat.text_width(candidate, font=font) > budget:
+                lines.append(line)
+                candidate = word
+            line = candidate
+            while len(line) > 1 and xlformat.text_width(line, font=font) > budget:
+                cut = len(line) - 1
+                while cut > 1 and xlformat.text_width(line[:cut], font=font) > budget:
+                    cut -= 1
+                lines.append(line[:cut])
+                line = line[cut:]
+        lines.append(line)
+    return lines