ascii_layout.py

Go to the documentation of this file.

# Copyright (c) 2025-present Aquin Labs Private Limited. All Rights Reserved.
"""Shared ASCII terminal layout primitives for aquin CLI surfaces."""
 
from __future__ import annotations
 
import shutil
import textwrap
 
# Hard-coded slant figlet — no runtime dep on pyfiglet.
BANNER = r"""
    ___   ____  __  _______   __
   /   | / __ \/ / / /  _/ | / /
  / /| |/ / / / / / // //  |/ /
 / ___ / /_/ / /_/ // // /|  /
/_/  |_\___\_\____/___/_/ |_/
""".strip("\n")
 
 
def width() -> int:
    try:
        cols = shutil.get_terminal_size().columns
    except OSError:
        cols = 80
    return max(64, min(cols, 96))
 
 
def ascii_safe(text: str) -> str:
    return (
        text.replace("\u2014", "-")
        .replace("\u2500", "-")
        .replace("\u00b7", "|")
        .replace("\u2019", "'")
        .replace("\u2026", "...")
    )
 
 
def rule(char: str = "=", w: int | None = None) -> str:
    return char * (w or width())
 
 
def center(text: str, w: int | None = None) -> str:
    return text.center(w or width())
 
 
def center_block(lines: list[str], w: int | None = None) -> list[str]:
    """Pad lines to equal width, then center the block as one unit."""
    w = w or width()
    if not lines:
        return []
    block_w = max(len(line) for line in lines)
    padded = [line.ljust(block_w) for line in lines]
    left = max(0, (w - block_w) // 2)
    return [(" " * left) + line for line in padded]
 
 
def box_top(w: int | None = None) -> str:
    w = w or width()
    return "+" + "-" * (w - 2) + "+"
 
 
def box_bottom(w: int | None = None) -> str:
    return box_top(w)
 
 
def box_line(text: str, w: int | None = None) -> str:
    w = w or width()
    inner = w - 4
    text = ascii_safe(text)
    if len(text) > inner:
        text = text[: inner - 3] + "..."
    return f"| {text.ljust(inner)} |"
 
 
def box_lines(text: str, w: int | None = None) -> list[str]:
    w = w or width()
    inner = w - 4
    text = ascii_safe(text)
    stripped = text.strip()
 
    if not stripped:
        return [box_line("", w)]
 
    if len(text) <= inner:
        return [box_line(text, w)]
 
    if all(c in "-=_." for c in stripped):
        return [box_line("-" * inner, w)]
 
    wrapped = textwrap.wrap(
        text,
        width=inner,
        break_long_words=False,
        break_on_hyphens=False,
    )
    return [box_line(line, w) for line in wrapped]
 
 
def kv_line(label: str, value: str, *, label_width: int = 10, w: int | None = None) -> str:
    """Boxed key/value row: '  label  value'."""
    w = w or width()
    key = label[:label_width].ljust(label_width)
    return box_line(f"  {key}  {ascii_safe(value)}", w)
 
 
def print_logo() -> None:
    """Bare Aquin figlet — used for `aquin` with no args."""
    print(BANNER)
    print()
 
 
def print_banner(*, subtitle: str, w: int | None = None) -> None:
    w = w or width()
    print()
    print(rule("=", w))
    for line in center_block(BANNER.splitlines(), w):
        print(line.rstrip())
    print(center(subtitle, w))
    print(rule("=", w))
    print()
 
 
def print_section(title: str, body_lines: list[str], *, w: int | None = None) -> None:
    """Print a titled ASCII box. body_lines are already boxed or plain content rows."""
    w = w or width()
    print(box_top(w))
    print(box_line(title.upper(), w))
    print(box_line("", w))
    for line in body_lines:
        if line.startswith("| ") and line.endswith(" |"):
            print(line)
        else:
            for boxed in box_lines(line, w):
                print(boxed)
    print(box_bottom(w))
    print()