induscode 0.1.0__py3-none-any.whl

induscode/console/components/banner_sweep.py

@@ -0,0 +1,188 @@
+"""Banner colour-sweep helpers — the pure, render-agnostic maths behind the
+optional startup flourish and the personalized welcome line.
+
+Port of TS ``src/console/components/banner-sweep.ts``. Two concerns, no
+Textual or Rich, no I/O, no state:
+
+- :func:`row_gradient` computes a *frozen* (single-pass, no animation timer)
+  colour for one wordmark row by lerping between two palette hexes across the
+  block's rows. The banner paints row ``i`` of ``n`` with this colour when the
+  opt-in sweep is on; off, the wordmark stays a flat accent. Because it takes
+  no clock and never schedules a frame, it is reduced-motion safe by
+  construction — the suppression decision lives at the call site, which simply
+  does not ask for a gradient when motion is reduced.
+
+- :func:`welcome_line` formats the ``"Welcome back{, name}!"`` greeting from
+  the signed-in account label, with a length guard and a name-less fallback,
+  so the banner and its tests share one formatter rather than re-deriving the
+  string.
+
+Everything here is referentially transparent: same inputs → same output.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Final
+
+__all__ = ["row_gradient", "welcome_line"]
+
+
+# ---------------------------------------------------------------------------
+# Welcome line
+# ---------------------------------------------------------------------------
+
+#: The greeting shown when no signed-in account label is available.
+_WELCOME_FALLBACK: Final[str] = "Welcome back!"
+
+#: The longest account label the welcome line embeds before it is dropped.
+#:
+#: An account key can be an arbitrary string (an email, a display name, a
+#: pasted token); past this width it stops reading as a name and starts
+#: wrapping the banner, so an over-long label is treated as "no usable name"
+#: and the fallback greeting is shown instead.
+_MAX_NAME: Final[int] = 40
+
+
+def welcome_line(name: str | None = None) -> str:
+    """Format the personalized welcome greeting.
+
+    Returns ``"Welcome back, {name}!"`` for a usable name, and the plain
+    ``"Welcome back!"`` fallback when the name is absent, blank, or too long
+    to read as a name. The name is trimmed of surrounding whitespace before
+    the checks so a padded label does not slip past the guards.
+
+    :param name: the signed-in account label, if one is known
+    :returns: the greeting string (plain text — never markup)
+    """
+    if name is None:
+        return _WELCOME_FALLBACK
+    trimmed = name.strip()
+    if len(trimmed) == 0 or len(trimmed) > _MAX_NAME:
+        return _WELCOME_FALLBACK
+    return f"Welcome back, {trimmed}!"
+
+
+# ---------------------------------------------------------------------------
+# Hex colour maths
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class _Rgb:
+    """One parsed colour channel triple, each component in the 0–255 range."""
+
+    r: int
+    g: int
+    b: int
+
+
+_SIX_HEX_RE: Final[re.Pattern[str]] = re.compile(r"^[0-9a-fA-F]{6}$")
+
+
+def _parse_hex(hex_color: str) -> _Rgb | None:
+    """Parse a ``#rrggbb`` (or ``#rgb``) hex string into its channel triple.
+
+    Tolerant of a missing leading ``#`` and of the short three-digit form
+    (each nibble is doubled). Returns ``None`` for anything it cannot read as
+    a colour, so the caller can fall back to the raw hex rather than emit
+    garbage.
+    """
+    body = hex_color[1:] if hex_color.startswith("#") else hex_color
+    if len(body) == 3:
+        six = "".join(ch + ch for ch in body)
+    elif len(body) == 6:
+        six = body
+    else:
+        return None
+    if _SIX_HEX_RE.match(six) is None:
+        return None
+    return _Rgb(
+        r=int(six[0:2], 16),
+        g=int(six[2:4], 16),
+        b=int(six[4:6], 16),
+    )
+
+
+def _clamp_channel(value: float) -> int:
+    """Clamp to the byte range and round so a lerp result is a legal channel.
+
+    Rounding is JS ``Math.round`` (half away from zero on the positive axis,
+    i.e. half-up) rather than Python's banker's rounding, so the produced
+    hexes match the TS build digit for digit.
+    """
+    if value < 0:
+        return 0
+    if value > 255:
+        return 255
+    return int(value + 0.5)
+
+
+def _lerp_rgb(start: _Rgb, end: _Rgb, t: float) -> _Rgb:
+    """Linear-interpolate between two channel triples by ``t`` in ``[0, 1]``.
+
+    ``t = 0`` returns ``start``, ``t = 1`` returns ``end``, anything between
+    mixes the two channel-wise. ``t`` is clamped so an out-of-range fraction
+    cannot overshoot.
+    """
+    k = 0.0 if t < 0 else 1.0 if t > 1 else t
+    return _Rgb(
+        r=_clamp_channel(start.r + (end.r - start.r) * k),
+        g=_clamp_channel(start.g + (end.g - start.g) * k),
+        b=_clamp_channel(start.b + (end.b - start.b) * k),
+    )
+
+
+def _channel_hex(value: int) -> str:
+    """Render one byte channel as a two-digit lowercase hex pair."""
+    return format(_clamp_channel(value), "02x")
+
+
+def _to_hex(rgb: _Rgb) -> str:
+    """Render a channel triple as a ``#rrggbb`` hex string (the form Rich's
+    colour parser accepts)."""
+    return f"#{_channel_hex(rgb.r)}{_channel_hex(rgb.g)}{_channel_hex(rgb.b)}"
+
+
+def row_gradient(
+    row_index: int,
+    row_count: int,
+    primary_hex: str,
+    secondary_hex: str,
+) -> str:
+    """The frozen sweep colour for one wordmark row.
+
+    Lerps from ``primary_hex`` (the first row) to ``secondary_hex`` (the last
+    row) across the ``row_count`` rows of the block, returning the colour for
+    row ``row_index`` as a ``#rrggbb`` hex string. A single-row block pins to
+    the primary; the endpoints are exact (row 0 = primary, row n-1 =
+    secondary). If either hex cannot be parsed, the corresponding raw input
+    hex is returned so the banner still gets a usable colour string rather
+    than nothing.
+
+    This computes a *static* gradient — there is no timer, no frame loop, no
+    clock. The whole sweep is laid down in the one render pass, which is
+    exactly why it is safe under reduced-motion: the flourish is colour, not
+    movement.
+
+    :param row_index: the zero-based row being painted
+    :param row_count: the total number of rows in the wordmark block
+    :param primary_hex: the colour of the first row (e.g. the accent)
+    :param secondary_hex: the colour of the last row (e.g. the secondary
+        accent)
+    :returns: a ``#rrggbb`` hex string (or a raw input hex when one is
+        unparseable)
+    """
+    start = _parse_hex(primary_hex)
+    end = _parse_hex(secondary_hex)
+    if start is None:
+        return secondary_hex
+    if end is None:
+        return primary_hex
+    if row_index <= 0 or row_count <= 1:
+        return _to_hex(start)
+    if row_index >= row_count - 1:
+        return _to_hex(end)
+    t = row_index / (row_count - 1)
+    return _to_hex(_lerp_rgb(start, end, t))

induscode/console/components/emblem.py

@@ -0,0 +1,181 @@
+"""Emblem — the two-tone block monogram that sits to the left of the wordmark.
+
+Port of TS ``src/console/components/Emblem.tsx``. Before this, the masthead
+was lettering alone — the "INDUS CODE" wordmark *was* the whole identity,
+painted in one flat accent. The emblem gives the brand a *mark*: a small
+fixed-width block glyph built from the box quadrant family
+(``▛ ▜ ▙ ▟ ▝ ▘ ▗ ▖ █ ▓``), split per row into a bright "fill" span and a dim
+"shadow" span so it reads as a single solid shape lit from one corner. The
+fill is the primary accent; the shadow is the secondary accent — the two
+distinct palette hues the scheme already carries — so the mark is genuinely
+two-tone rather than a single colour with a darker edge.
+
+It is purely presentational: a fixed glyph grid tinted through the framework
+:class:`~indusagi.react_ink.ThemeAdapter` at render time, no state beyond the
+reactive inputs, no side effects, no props beyond the theme and an optional
+row-colour override the banner uses to fold the emblem's fill into a frozen
+colour-sweep.
+
+Port shape (analysis 02 §7): the Ink ``Box``-per-row column becomes one
+:class:`~textual.widgets.Static` whose ``render()`` returns a prebuilt
+:class:`rich.text.Text`; the per-row fill/shadow ``<Text>`` spans become Rich
+style spans on that one renderable (``chalk.hex`` → ``rich.style.Style
+(color=…)``). The pure builders are exported so the banner can lay the emblem
+beside the wordmark row-by-row without mounting this widget.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, Sequence
+
+from rich.color import ColorParseError
+from rich.console import RenderableType
+from rich.style import Style
+from rich.text import Text
+from textual.reactive import reactive
+from textual.widgets import Static
+
+if TYPE_CHECKING:
+    from indusagi.react_ink import InkThemeAdapter
+
+__all__ = [
+    "EMBLEM_HEIGHT",
+    "Emblem",
+    "build_emblem_text",
+    "emblem_row_texts",
+    "paint_hex",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class _EmblemRow:
+    """One emblem row, split into the lit "fill" portion and the shadowed
+    portion.
+
+    Every row carries the same total glyph width so the column is
+    rectangular; either span may be empty when a row is wholly lit or wholly
+    in shadow.
+    """
+
+    # The brightly-lit portion of the row, painted in the primary accent.
+    fill: str
+    # The shadowed portion of the row, painted in the secondary accent.
+    shadow: str
+
+
+#: The emblem glyph grid: a six-row block monogram from the box quadrant
+#: family.
+#:
+#: Read top-to-bottom it is a solid rounded block with a lit upper-left face
+#: and a shadowed lower-right face — the fill/shadow split per row is what
+#: gives the two-tone, lit-from-a-corner look. Five glyphs wide on every row
+#: so the column is rectangular and aligns with the wordmark beside it.
+_EMBLEM_ROWS: Final[tuple[_EmblemRow, ...]] = (
+    _EmblemRow(fill="▛▀▀▜", shadow="▖"),
+    _EmblemRow(fill="▌█▓", shadow="▝▌"),
+    _EmblemRow(fill="▌█▓", shadow=" ▌"),
+    _EmblemRow(fill="▌█▓", shadow="▗▌"),
+    _EmblemRow(fill="▌█", shadow="▓▟▘"),
+    _EmblemRow(fill="▙▄", shadow="▄▟▘"),
+)
+
+#: How many terminal rows the emblem occupies (its glyph-grid height).
+EMBLEM_HEIGHT: Final[int] = len(_EMBLEM_ROWS)
+
+
+def paint_hex(hex_color: str, text: str) -> Text:
+    """Paint ``text`` in a raw ``#rrggbb`` hex, falling back to the unpainted
+    text if Rich rejects the colour — used for the optional colour-sweep,
+    whose per-row hexes do not exist as theme colour-keys.
+
+    The TS source wrapped ``chalk.hex`` in a try/catch; Rich parses colours
+    eagerly in ``Style.__init__`` and raises :class:`ColorParseError` for
+    garbage, which degrades to unstyled text exactly like chalk did.
+    """
+    try:
+        return Text(text, style=Style(color=hex_color))
+    except ColorParseError:
+        return Text(text)
+
+
+def emblem_row_texts(
+    theme: InkThemeAdapter,
+    row_colors: Sequence[str] | None = None,
+) -> tuple[Text, ...]:
+    """The emblem as one prebuilt :class:`rich.text.Text` per glyph row.
+
+    Each row paints its fill span in the accent role (or the supplied sweep
+    colour for that row) and its shadow span in the secondary
+    ``customMessage`` role, so the monogram reads as one solid mark with a
+    lit and a shadowed face. The banner consumes these to lay the emblem
+    beside the wordmark row-by-row.
+
+    :param theme: the framework adapter that turns roles into colours
+    :param row_colors: optional per-row fill colour (a ``#rrggbb`` hex),
+        indexed by row — the banner's frozen colour-sweep. Absent rows fall
+        back to the accent role; the shadow keeps the secondary accent so
+        the mark stays two-tone.
+    """
+    rows: list[Text] = []
+    for index, row in enumerate(_EMBLEM_ROWS):
+        sweep = row_colors[index] if row_colors is not None and index < len(row_colors) else None
+        fill = paint_hex(sweep, row.fill) if sweep is not None else theme.color("accent", row.fill)
+        line = Text()
+        line.append_text(fill)
+        line.append_text(theme.color("customMessage", row.shadow))
+        rows.append(line)
+    return tuple(rows)
+
+
+def build_emblem_text(
+    theme: InkThemeAdapter,
+    row_colors: Sequence[str] | None = None,
+) -> Text:
+    """The whole two-tone emblem as a single prebuilt Rich ``Text``.
+
+    The Ink column-of-rows becomes the rows of :func:`emblem_row_texts`
+    joined by newlines — what the :class:`Emblem` widget renders.
+    """
+    return Text("\n").join(emblem_row_texts(theme, row_colors))
+
+
+class Emblem(Static):
+    """The two-tone block emblem as one persistent ``Static``.
+
+    ``theme`` and ``row_colors`` are reactive, so a scheme switch (or the
+    banner toggling the sweep) re-renders the mark in place; the glyph grid
+    itself never changes.
+    """
+
+    DEFAULT_CSS = """
+    Emblem {
+        width: auto;
+        height: auto;
+    }
+    """
+
+    theme: reactive[InkThemeAdapter | None] = reactive(None, layout=True)
+    row_colors: reactive[tuple[str, ...] | None] = reactive(None, layout=True)
+
+    def __init__(
+        self,
+        theme: InkThemeAdapter,
+        *,
+        row_colors: Sequence[str] | None = None,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+        disabled: bool = False,
+    ) -> None:
+        super().__init__("", name=name, id=id, classes=classes, disabled=disabled)
+        self.set_reactive(Emblem.theme, theme)
+        self.set_reactive(
+            Emblem.row_colors, tuple(row_colors) if row_colors is not None else None
+        )
+
+    def render(self) -> RenderableType:
+        theme = self.theme
+        if theme is None:
+            return Text("")
+        return build_emblem_text(theme, self.row_colors)

induscode/console/components/status_bar.py

@@ -0,0 +1,102 @@
+"""StatusBar — the bottom chrome strip of the console.
+
+Port of TS ``src/console/components/StatusBar.tsx``. Composes the framework's
+:class:`~indusagi.react_ink.StatusLine` (the transient toast row) above its
+:class:`~indusagi.react_ink.Footer` (the persistent session/usage strip),
+both fed from a projected :class:`~indusagi.react_ink.SessionSnapshot`. The
+console owns no rendering of its own here — it threads the resolved theme
+adapter and the current snapshot/status into the framework widgets, which do
+the layout. Purely presentational.
+
+Port shape (analysis 02 §7 — "mostly collapses"): the Ink column ``<Box>``
+becomes a :class:`~textual.containers.Vertical` holding the two framework
+widgets, which the ``ConsoleApp`` docks at the bottom. Where TS re-rendered
+with fresh props every frame, the Textual widgets are retained and reactive:
+:meth:`StatusBar.update_state` threads one TS-shaped prop set (snapshot /
+branch / provider count / status) into the children's reactives exactly as
+the framework expects (``StatusLine.snapshot``/``.status``;
+``Footer.snapshot``/``.branch``/``.available_provider_count``).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual.containers import Vertical
+
+from indusagi.react_ink import Footer, StatusLine
+
+if TYPE_CHECKING:
+    from indusagi.react_ink import InkThemeAdapter, SessionSnapshot, StatusMessage
+
+__all__ = ["StatusBar"]
+
+
+class StatusBar(Vertical):
+    """The toast row above the footer strip.
+
+    Constructor inputs mirror the TS props (``theme`` / ``snapshot`` /
+    ``branch`` / ``provider_count`` / ``status``); the children are created
+    eagerly and exposed as :attr:`status_line` / :attr:`footer` so the host
+    app can also reach them directly. Both framework widgets hide themselves
+    until they have something to show, so an empty bar takes no rows.
+    """
+
+    DEFAULT_CSS = """
+    StatusBar {
+        width: 1fr;
+        height: auto;
+    }
+    """
+
+    def __init__(
+        self,
+        theme: InkThemeAdapter,
+        *,
+        snapshot: SessionSnapshot | None = None,
+        branch: str | None = None,
+        provider_count: int = 0,
+        status: StatusMessage | None = None,
+        name: str | None = None,
+        id: str | None = None,
+        classes: str | None = None,
+        disabled: bool = False,
+    ) -> None:
+        # The framework strips, threaded exactly the props the TS StatusBar
+        # forwarded: StatusLine gets snapshot + status, Footer gets snapshot
+        # + branch + availableProviderCount.
+        self.status_line = StatusLine(theme, snapshot=snapshot, status=status)
+        self.footer = Footer(
+            theme,
+            snapshot=snapshot,
+            branch=branch,
+            available_provider_count=provider_count,
+        )
+        super().__init__(
+            self.status_line,
+            self.footer,
+            name=name,
+            id=id,
+            classes=classes,
+            disabled=disabled,
+        )
+
+    def update_state(
+        self,
+        snapshot: SessionSnapshot | None,
+        *,
+        branch: str | None = None,
+        provider_count: int = 0,
+        status: StatusMessage | None = None,
+    ) -> None:
+        """Thread a fresh TS-shaped prop set into the framework widgets.
+
+        The console calls this once per projected snapshot (an agent event,
+        a toast change, a branch move); the children's reactives re-render
+        the strips in place.
+        """
+        self.status_line.snapshot = snapshot
+        self.status_line.status = status
+        self.footer.snapshot = snapshot
+        self.footer.branch = branch
+        self.footer.available_provider_count = provider_count