py-sparcli 0.3.0__py3-none-any.whl

sparcli/output/box.py

@@ -0,0 +1,196 @@
+"""
+sparcli.output.box
+=================
+
+Shared box-drawing routine used by :class:`~sparcli.output.panel.Panel` and
+:class:`~sparcli.output.alert.Alert`.
+
+:func:`draw_box` frames a rendered block with a border, padding and an optional
+fill, embedding a title in the top edge and a subtitle in the bottom edge. A
+``BorderType.NONE`` box degrades to padding only. The title-embedding rules
+match the Rust original: a left-aligned title keeps a single connecting glyph.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from sparcli.core.border import BorderType
+from sparcli.core.geometry import Align, Edges, Title
+from sparcli.core.render import Rendered
+from sparcli.core.style import Style
+from sparcli.core.text import Line, Span
+from sparcli.core.width import truncate, visible_width
+from sparcli.output.layout import blank_line, pad_line, space_span
+
+_BORDER_COLUMNS = 2
+_LEFT_CONNECTOR = 1
+
+
+@dataclass(slots=True)
+class BoxOpts:
+    """Options controlling how :func:`draw_box` frames its content."""
+
+    border: BorderType = BorderType.ROUNDED
+    border_style: Style = field(default_factory=Style)
+    fill: Style = field(default_factory=Style)
+    padding: Edges = field(default_factory=lambda: Edges.symmetric(0, 1))
+    title: Title | None = None
+    subtitle: Title | None = None
+    width: int | None = None
+    content_align: Align = Align.LEFT
+
+
+def draw_box(content: Rendered, opts: BoxOpts, max_width: int) -> Rendered:
+    """
+    Frames ``content`` with a border, padding and fill.
+
+    Parameters
+    ----------
+    content : Rendered
+        The block to frame.
+    opts : BoxOpts
+        The framing options.
+    max_width : int
+        The maximum outer width in columns.
+
+    Returns
+    -------
+    Rendered
+        The framed block.
+    """
+    if opts.border.is_none():
+        return _frame_borderless(content, opts, max_width)
+    chars = opts.border.chars()
+    inner_content = _inner_content_width(content, opts, max_width)
+    body = _body_rows(content, inner_content, opts)
+    inner_width = opts.padding.left + inner_content + opts.padding.right
+    lines = [
+        _edge_line(chars.top_left, chars.top_right, inner_width, opts, True)
+    ]
+    lines.extend(
+        _border_row(row, chars.vertical, opts.border_style) for row in body
+    )
+    lines.append(
+        _edge_line(
+            chars.bottom_left, chars.bottom_right, inner_width, opts, False
+        )
+    )
+    return Rendered(lines)
+
+
+def _frame_borderless(
+    content: Rendered, opts: BoxOpts, max_width: int
+) -> Rendered:
+    """Frames content with padding and fill only, without border glyphs."""
+    inner_content = _inner_content_width(content, opts, max_width)
+    return Rendered(_body_rows(content, inner_content, opts))
+
+
+def _inner_content_width(
+    content: Rendered, opts: BoxOpts, max_width: int
+) -> int:
+    """Computes the width available for content between the padding."""
+    border_cols = 0 if opts.border.is_none() else _BORDER_COLUMNS
+    overhead = border_cols + opts.padding.horizontal()
+    if opts.width is not None:
+        outer = min(opts.width, max_width)
+        return max(0, outer - overhead)
+    natural = content.width()
+    if natural + overhead <= max_width:
+        return natural
+    return max(0, max_width - overhead)
+
+
+def _body_rows(
+    content: Rendered, inner_content: int, opts: BoxOpts
+) -> list[Line]:
+    """Builds the padded, filled content rows between the border edges."""
+    inner_width = opts.padding.left + inner_content + opts.padding.right
+    rows: list[Line] = []
+    for _ in range(opts.padding.top):
+        rows.append(blank_line(inner_width, opts.fill))
+    for line in content.lines:
+        filled = pad_line(line, inner_content, opts.content_align, opts.fill)
+        rows.append(_content_row(filled, opts))
+    for _ in range(opts.padding.bottom):
+        rows.append(blank_line(inner_width, opts.fill))
+    return rows
+
+
+def _content_row(line: Line, opts: BoxOpts) -> Line:
+    """Wraps an aligned content line in horizontal padding."""
+    spans: list[Span] = []
+    if opts.padding.left:
+        spans.append(space_span(opts.padding.left, opts.fill))
+    spans.extend(line.spans)
+    if opts.padding.right:
+        spans.append(space_span(opts.padding.right, opts.fill))
+    return Line(spans)
+
+
+def _border_row(row: Line, vertical: str, style: Style) -> Line:
+    """Wraps a content row with the left and right vertical border glyphs."""
+    edge = Span.styled(vertical, style)
+    return Line([edge, *row.spans, edge])
+
+
+def _edge_line(
+    left: str, right: str, inner_width: int, opts: BoxOpts, is_top: bool
+) -> Line:
+    """Builds a top or bottom border edge, embedding the title if present."""
+    title = opts.title if is_top else opts.subtitle
+    corner_left = Span.styled(left, opts.border_style)
+    corner_right = Span.styled(right, opts.border_style)
+    horizontal = opts.border.chars().horizontal
+    if title is None or not title.content.lines:
+        run = Span.styled(horizontal * inner_width, opts.border_style)
+        return Line([corner_left, run, corner_right])
+    middle = _embed_title(title, inner_width, horizontal, opts.border_style)
+    return Line([corner_left, *middle, corner_right])
+
+
+def _embed_title(
+    title: Title, width: int, horizontal: str, style: Style
+) -> list[Span]:
+    """Embeds a title in a horizontal border run of ``width`` columns."""
+    label = _title_spans(title)
+    label_width = sum(span.width() for span in label) + 2 * title.pad
+    if label_width >= width:
+        text = truncate(title.content.lines[0].plain(), width)
+        return [Span.styled(text, style)]
+    left_run, right_run = _title_runs(title.align, width, label_width)
+    pad_span = space_span(title.pad, style)
+    spans: list[Span] = []
+    if left_run:
+        spans.append(Span.styled(horizontal * left_run, style))
+    spans.append(pad_span)
+    spans.extend(label)
+    spans.append(pad_span)
+    if right_run:
+        spans.append(Span.styled(horizontal * right_run, style))
+    return spans
+
+
+def _title_spans(title: Title) -> list[Span]:
+    """Returns the styled spans of a title's first line."""
+    if not title.content.lines:
+        return []
+    return list(title.content.lines[0].spans)
+
+
+def _title_runs(align: Align, width: int, label_width: int) -> tuple[int, int]:
+    """Splits the border run around a title according to its alignment."""
+    slack = width - label_width
+    if align is Align.LEFT:
+        return (_LEFT_CONNECTOR, slack - _LEFT_CONNECTOR)
+    if align is Align.RIGHT:
+        return (slack - _LEFT_CONNECTOR, _LEFT_CONNECTOR)
+    left = slack // 2
+    return (left, slack - left)
+
+
+def title_bar_width(title: Title) -> int:
+    """Returns the column width a title occupies including its padding."""
+    label = sum(visible_width(line.plain()) for line in title.content.lines[:1])
+    return label + 2 * title.pad

sparcli/output/columns.py

@@ -0,0 +1,157 @@
+"""
+sparcli.output.columns
+======================
+
+Defines :class:`Columns`, a side-by-side arrangement of rendered blocks.
+
+Each column is laid out at its own width, padded to the tallest column and
+placed next to its neighbours with a configurable gap. Shorter columns are
+vertically aligned (top, middle or bottom), and an optional border glyph can be
+drawn as a separator centered in the gap. Both a keyword constructor and fluent
+builders are provided.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sparcli.core.border import BorderType
+from sparcli.core.geometry import Align, VAlign
+from sparcli.core.render import Renderable, Rendered
+from sparcli.core.style import Style
+from sparcli.core.text import Line, Span
+from sparcli.core.theme import theme
+from sparcli.output.layout import blank_line, pad_line
+
+_DEFAULT_GAP = 2
+
+
+@dataclass(slots=True)
+class _ColumnItem:
+    """One column: a rendered block and its horizontal alignment."""
+
+    block: Rendered
+    align: Align = Align.LEFT
+
+
+class Columns(Renderable):
+    """A horizontal arrangement of rendered blocks."""
+
+    __slots__ = (
+        "_items",
+        "_gap",
+        "_separator",
+        "_separator_style",
+        "_valign",
+    )
+
+    def __init__(
+        self,
+        *,
+        gap: int = _DEFAULT_GAP,
+        separator: BorderType | None = None,
+        separator_style: Style | None = None,
+        valign: VAlign = VAlign.TOP,
+    ) -> None:
+        self._items: list[_ColumnItem] = []
+        self._gap = gap
+        self._separator = separator
+        self._separator_style = (
+            separator_style
+            if separator_style is not None
+            else theme().secondary
+        )
+        self._valign = valign
+
+    def add(self, content: Renderable, width: int) -> Columns:
+        """Adds a column from a renderable laid out at ``width`` columns."""
+        self._items.append(_ColumnItem(block=content.render(width)))
+        return self
+
+    def add_rendered(self, block: Rendered) -> Columns:
+        """Adds a column from an already rendered block and returns self."""
+        self._items.append(_ColumnItem(block=block))
+        return self
+
+    def align(self, align: Align) -> Columns:
+        """Sets the alignment of the most recently added column."""
+        if self._items:
+            self._items[-1].align = align
+        return self
+
+    def gap(self, gap: int) -> Columns:
+        """Sets the gap between columns in spaces and returns self."""
+        self._gap = gap
+        return self
+
+    def separator(self, border: BorderType) -> Columns:
+        """Draws a vertical separator between columns and returns self."""
+        self._separator = border
+        return self
+
+    def valign(self, valign: VAlign) -> Columns:
+        """Sets the vertical alignment of shorter columns and returns self."""
+        self._valign = valign
+        return self
+
+    def render(self, max_width: int) -> Rendered:
+        """Renders the columns side by side, ignoring ``max_width``."""
+        if not self._items:
+            return Rendered.empty()
+        height = max(item.block.height() for item in self._items)
+        widths = [item.block.width() for item in self._items]
+        aligned = [
+            self._align_column(item, width, height)
+            for item, width in zip(self._items, widths, strict=True)
+        ]
+        lines = [
+            self._compose_row(aligned, widths, row) for row in range(height)
+        ]
+        return Rendered(lines)
+
+    def _align_column(
+        self, item: _ColumnItem, width: int, height: int
+    ) -> list[Line]:
+        """Vertically aligns and pads a column into a uniform block."""
+        pad_top = _pad_top(self._valign, height, item.block.height())
+        lines: list[Line] = [blank_line(width) for _ in range(pad_top)]
+        for line in item.block.lines:
+            lines.append(pad_line(line, width, item.align))
+        while len(lines) < height:
+            lines.append(blank_line(width))
+        return lines
+
+    def _compose_row(
+        self, aligned: list[list[Line]], widths: list[int], row: int
+    ) -> Line:
+        """Joins the columns at index ``row`` into one output line."""
+        spans: list[Span] = []
+        for index, column in enumerate(aligned):
+            if index > 0:
+                self._push_gap(spans)
+            line = (
+                column[row] if row < len(column) else blank_line(widths[index])
+            )
+            spans.extend(line.spans)
+        return Line(spans)
+
+    def _push_gap(self, spans: list[Span]) -> None:
+        """Pushes the inter-column gap and optional separator glyph."""
+        if self._separator is None:
+            spans.append(Span.raw(" " * self._gap))
+            return
+        half = self._gap // 2
+        glyph = self._separator.chars().vertical
+        spans.append(Span.raw(" " * half))
+        spans.append(Span.styled(glyph, self._separator_style))
+        rest = max(0, self._gap - (half + 1))
+        spans.append(Span.raw(" " * rest))
+
+
+def _pad_top(valign: VAlign, height: int, block_height: int) -> int:
+    """Returns the number of blank rows above a column for a vertical align."""
+    if valign is VAlign.TOP:
+        return 0
+    if valign is VAlign.MIDDLE:
+        return (height - block_height) // 2
+    return height - block_height

sparcli/output/compose.py

@@ -0,0 +1,111 @@
+"""
+sparcli.output.compose
+======================
+
+Composition helpers for stacking and placing rendered blocks.
+
+:func:`align` pads a block to a width, :func:`pad` adds box-model spacing, and
+:func:`vstack` stacks blocks vertically with an optional gap. They operate on
+:class:`~sparcli.core.render.Rendered` values, so widgets and hand-built blocks
+compose the same way.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from sparcli.core.geometry import Align, Edges
+from sparcli.core.render import Rendered
+from sparcli.core.style import Style
+from sparcli.core.text import Line, Span
+from sparcli.output.layout import blank_line, pad_line, space_span
+
+
+def align(rendered: Rendered, width: int, alignment: Align) -> Rendered:
+    """
+    Pads every line of ``rendered`` to ``width`` using ``alignment``.
+
+    Parameters
+    ----------
+    rendered : Rendered
+        The block to align.
+    width : int
+        The target width in columns.
+    alignment : Align
+        How to place each line within the width.
+
+    Returns
+    -------
+    Rendered
+        A new block with every line padded to ``width``.
+    """
+    return Rendered(
+        [pad_line(line, width, alignment) for line in rendered.lines]
+    )
+
+
+def pad(
+    rendered: Rendered, edges: Edges, style: Style | None = None
+) -> Rendered:
+    """
+    Surrounds ``rendered`` with box-model spacing.
+
+    A content line is only padded up to the block width when a right margin
+    must align; with no right margin it is kept as-is, so shorter lines stay
+    ragged instead of gaining trailing spaces.
+
+    Parameters
+    ----------
+    rendered : Rendered
+        The block to pad.
+    edges : Edges
+        The spacing to add on each side.
+    style : Style | None
+        The fill style for the padding.
+
+    Returns
+    -------
+    Rendered
+        A new padded block.
+    """
+    inner_width = rendered.width()
+    total_width = inner_width + edges.horizontal()
+    lines: list[Line] = []
+    for _ in range(edges.top):
+        lines.append(blank_line(total_width, style))
+    for line in rendered.lines:
+        spans: list[Span] = []
+        if edges.left:
+            spans.append(space_span(edges.left, style))
+        spans.extend(line.spans)
+        if edges.right:
+            gap = inner_width - line.width() + edges.right
+            spans.append(space_span(gap, style))
+        lines.append(Line(spans))
+    for _ in range(edges.bottom):
+        lines.append(blank_line(total_width, style))
+    return Rendered(lines)
+
+
+def vstack(blocks: Sequence[Rendered], gap: int = 0) -> Rendered:
+    """
+    Stacks blocks vertically with ``gap`` blank lines between them.
+
+    Parameters
+    ----------
+    blocks : Sequence[Rendered]
+        The blocks to stack, top to bottom.
+    gap : int
+        The number of blank lines inserted between blocks.
+
+    Returns
+    -------
+    Rendered
+        The stacked block.
+    """
+    lines: list[Line] = []
+    for index, block in enumerate(blocks):
+        if index and gap:
+            lines.extend(blank_line() for _ in range(gap))
+        lines.extend(block.lines)
+    return Rendered(lines)

sparcli/output/diff.py

@@ -0,0 +1,229 @@
+"""
+sparcli.output.diff
+===================
+
+Defines :class:`Diff`, a colored unified diff between two texts.
+
+Lines are matched with a longest-common-subsequence edit script and emitted as
+equal (``  ``), deleted (``- ``) or inserted (``+ ``) rows. Unchanged regions
+beyond a context window collapse into a ``…`` hunk marker, and a ``--- old`` /
+``+++ new`` header precedes the body unless it is disabled. Very large inputs
+fall back to a plain delete-then-insert listing.
+"""
+
+from __future__ import annotations
+
+import enum
+
+from sparcli.core.color import Color
+from sparcli.core.render import Renderable, Rendered
+from sparcli.core.style import Style
+from sparcli.core.text import Line
+from sparcli.core.theme import theme
+
+# Default number of unchanged context lines kept around each change.
+DEFAULT_CONTEXT = 3
+# Maximum lines per side before falling back to a full listing.
+MAX_DIFF_LINES = 5000
+
+
+class _OpKind(enum.Enum):
+    """The kind of a single line operation in the edit script."""
+
+    EQUAL = enum.auto()
+    DELETE = enum.auto()
+    INSERT = enum.auto()
+
+
+# The two-character gutter prefix for each operation kind.
+_OP_PREFIX: dict[_OpKind, str] = {
+    _OpKind.EQUAL: "  ",
+    _OpKind.DELETE: "- ",
+    _OpKind.INSERT: "+ ",
+}
+
+
+class _Op:
+    """A single line operation carrying its kind and text."""
+
+    __slots__ = ("kind", "text")
+
+    def __init__(self, kind: _OpKind, text: str) -> None:
+        self.kind = kind
+        self.text = text
+
+
+class Diff(Renderable):
+    """A unified, colored diff between an ``old`` and a ``new`` text."""
+
+    __slots__ = (
+        "_old",
+        "_new",
+        "_context",
+        "_no_header",
+        "_old_label",
+        "_new_label",
+        "_add_style",
+        "_del_style",
+        "_hunk_style",
+    )
+
+    def __init__(
+        self,
+        old: str,
+        new: str,
+        *,
+        context: int = DEFAULT_CONTEXT,
+        no_header: bool = False,
+        old_label: str = "old",
+        new_label: str = "new",
+        add_style: Style | None = None,
+        del_style: Style | None = None,
+        hunk_style: Style | None = None,
+    ) -> None:
+        self._old = old
+        self._new = new
+        self._context = context
+        self._no_header = no_header
+        self._old_label = old_label
+        self._new_label = new_label
+        self._add_style = (
+            add_style
+            if add_style is not None
+            else Style.from_color(Color.GREEN)
+        )
+        self._del_style = (
+            del_style if del_style is not None else Style.from_color(Color.RED)
+        )
+        self._hunk_style = (
+            hunk_style if hunk_style is not None else theme().secondary
+        )
+
+    def context(self, lines: int) -> Diff:
+        """Sets the number of context lines around changes."""
+        self._context = lines
+        return self
+
+    def no_header(self) -> Diff:
+        """Hides the ``---``/``+++`` header and returns the diff."""
+        self._no_header = True
+        return self
+
+    def labels(self, old: str, new: str) -> Diff:
+        """Sets the old and new side labels and returns the diff."""
+        self._old_label = old
+        self._new_label = new
+        return self
+
+    def render(self, max_width: int) -> Rendered:
+        """Renders the diff; ``max_width`` is accepted but not constraining."""
+        del max_width
+        old = _split_lines(self._old)
+        new = _split_lines(self._new)
+        ops = _diff_ops(old, new)
+        lines: list[Line] = []
+        if not self._no_header:
+            self._push_header(lines)
+        self._push_ops(lines, ops)
+        return Rendered(lines)
+
+    def _push_header(self, lines: list[Line]) -> None:
+        """Pushes the ``--- old`` / ``+++ new`` header lines."""
+        lines.append(Line.styled(f"--- {self._old_label}", self._del_style))
+        lines.append(Line.styled(f"+++ {self._new_label}", self._add_style))
+
+    def _push_ops(self, lines: list[Line], ops: list[_Op]) -> None:
+        """Pushes the diff body, collapsing unchanged regions to context."""
+        visible = _mark_visible(ops, self._context)
+        last_visible = False
+        for index, op in enumerate(ops):
+            if not visible[index]:
+                last_visible = False
+                continue
+            if not last_visible and index > 0:
+                lines.append(Line.styled("…", self._hunk_style))
+            lines.append(self._format_op(op))
+            last_visible = True
+
+    def _format_op(self, op: _Op) -> Line:
+        """Formats a single operation as a styled line."""
+        text = f"{_OP_PREFIX[op.kind]}{op.text}"
+        if op.kind is _OpKind.EQUAL:
+            return Line.raw(text)
+        style = (
+            self._del_style if op.kind is _OpKind.DELETE else self._add_style
+        )
+        return Line.styled(text, style)
+
+
+def _split_lines(text: str) -> list[str]:
+    """Splits ``text`` into lines the way Rust's ``str::lines`` does."""
+    if not text:
+        return []
+    parts = text.split("\n")
+    if parts and parts[-1] == "":
+        parts.pop()
+    return [part.removesuffix("\r") for part in parts]
+
+
+def _mark_visible(ops: list[_Op], context: int) -> list[bool]:
+    """Marks which ops are visible given the surrounding context window."""
+    visible = [False] * len(ops)
+    for index, op in enumerate(ops):
+        if op.kind is _OpKind.EQUAL:
+            continue
+        start = max(0, index - context)
+        end = min(index + context + 1, len(ops))
+        for cursor in range(start, end):
+            visible[cursor] = True
+    return visible
+
+
+def _diff_ops(old: list[str], new: list[str]) -> list[_Op]:
+    """Computes a line-based edit script using an LCS table."""
+    if len(old) > MAX_DIFF_LINES or len(new) > MAX_DIFF_LINES:
+        return _fallback_ops(old, new)
+    table = _lcs_table(old, new)
+    return _backtrack(table, old, new)
+
+
+def _lcs_table(old: list[str], new: list[str]) -> list[list[int]]:
+    """Builds the longest-common-subsequence length table."""
+    table = [[0] * (len(new) + 1) for _ in range(len(old) + 1)]
+    for i in range(len(old) - 1, -1, -1):
+        for j in range(len(new) - 1, -1, -1):
+            if old[i] == new[j]:
+                table[i][j] = table[i + 1][j + 1] + 1
+            else:
+                table[i][j] = max(table[i + 1][j], table[i][j + 1])
+    return table
+
+
+def _backtrack(
+    table: list[list[int]], old: list[str], new: list[str]
+) -> list[_Op]:
+    """Backtracks the LCS table into an ordered edit script."""
+    ops: list[_Op] = []
+    i = 0
+    j = 0
+    while i < len(old) and j < len(new):
+        if old[i] == new[j]:
+            ops.append(_Op(_OpKind.EQUAL, old[i]))
+            i += 1
+            j += 1
+        elif table[i + 1][j] >= table[i][j + 1]:
+            ops.append(_Op(_OpKind.DELETE, old[i]))
+            i += 1
+        else:
+            ops.append(_Op(_OpKind.INSERT, new[j]))
+            j += 1
+    ops.extend(_Op(_OpKind.DELETE, line) for line in old[i:])
+    ops.extend(_Op(_OpKind.INSERT, line) for line in new[j:])
+    return ops
+
+
+def _fallback_ops(old: list[str], new: list[str]) -> list[_Op]:
+    """Returns a naive diff for large inputs: delete all, then insert all."""
+    ops: list[_Op] = [_Op(_OpKind.DELETE, line) for line in old]
+    ops.extend(_Op(_OpKind.INSERT, line) for line in new)
+    return ops