panelmark 0.1.0__py3-none-any.whl

panelmark/__init__.py

@@ -0,0 +1,4 @@
+from .shell import Shell
+from .interactions import Interaction
+
+__all__ = ["Shell", "Interaction"]

panelmark/draw.py

@@ -0,0 +1,182 @@
+"""Draw commands and render context for the panelmark renderer abstraction.
+
+Interactions return a ``list[DrawCommand]`` from their ``render()`` method
+rather than performing side effects directly. Each renderer provides an
+executor that translates the command list to its output surface (terminal,
+HTML, etc.).
+
+Coordinate system
+-----------------
+All row and column values in draw commands are **region-relative**:
+``(0, 0)`` is the top-left cell of the interaction's assigned region.
+The executor maps these to screen-absolute or document-absolute coordinates
+internally. Interactions never need to know their absolute position.
+
+Style dict
+----------
+The optional ``style`` argument on ``WriteCmd`` and ``FillCmd`` is a plain
+dict. All keys are optional. Renderers apply the keys they support and ignore
+the rest — unknown keys are not an error.
+
+Valid keys and values::
+
+    bold       bool   — bold / heavy weight
+    italic     bool   — italic (renderers that lack italic use normal)
+    underline  bool   — underline
+    reverse    bool   — swap foreground and background colours
+    color      str    — foreground colour name: 'red', 'green', 'yellow',
+                        'blue', 'magenta', 'cyan', 'white', 'black'
+    bg         str    — background colour name (same values as color)
+
+Example — a minimal custom render() implementation::
+
+    from panelmark.draw import WriteCmd, FillCmd, RenderContext, DrawCommand
+
+    def render(self, context: RenderContext, focused: bool = False) -> list[DrawCommand]:
+        text = self._value[:context.width].ljust(context.width)
+        style = {'reverse': True} if focused else None
+        return [
+            FillCmd(row=0, col=0, width=context.width, height=context.height),
+            WriteCmd(row=0, col=0, text=text, style=style),
+        ]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class RenderContext:
+    """Read-only rendering context passed to ``Interaction.render()``.
+
+    Carries the dimensions of the interaction's assigned region and a set
+    of capability flags describing what the current renderer supports.
+    Interactions use ``supports()`` to degrade gracefully on renderers that
+    lack a capability rather than failing or producing garbled output.
+
+    Attributes
+    ----------
+    width:
+        Width of the region in character columns.
+    height:
+        Height of the region in character rows.
+    capabilities:
+        Frozenset of feature strings supported by the renderer. Do not
+        inspect this directly — use ``supports(feature)`` instead.
+    """
+
+    width: int
+    height: int
+    capabilities: frozenset[str] = field(default_factory=frozenset)
+
+    def supports(self, feature: str) -> bool:
+        """Return True if the renderer supports *feature*.
+
+        Known feature strings (renderers may support any subset):
+
+        ``'color'``
+            At least 8 foreground/background colours are available.
+        ``'256color'``
+            256-colour palette is available.
+        ``'truecolor'``
+            24-bit (16 million colour) palette is available.
+        ``'unicode'``
+            Unicode characters (box-drawing, block elements, etc.) render
+            correctly. ASCII-only renderers do not set this.
+        ``'cursor'``
+            A text cursor can be positioned within the region. Set by TUI
+            renderers and interactive web renderers; not set by static HTML.
+        ``'italic'``
+            Italic text is visually distinct from normal weight text.
+
+        Returns False for unknown or unsupported feature strings.
+        """
+        return feature in self.capabilities
+
+
+@dataclass
+class WriteCmd:
+    """Write styled text at region-relative (row, col).
+
+    The text is written left-to-right starting at the given position.
+    No automatic clipping is performed — the executor clips to the region
+    boundary. Callers should ensure text does not exceed ``context.width``
+    columns from ``col``.
+
+    Parameters
+    ----------
+    row:
+        Zero-based row offset from the top of the region.
+    col:
+        Zero-based column offset from the left of the region.
+    text:
+        The string to write. Should not contain newlines.
+    style:
+        Optional style dict. See module docstring for valid keys.
+    """
+
+    row: int
+    col: int
+    text: str
+    style: dict | None = None
+
+
+@dataclass
+class FillCmd:
+    """Fill a rectangle with a repeated character, optionally styled.
+
+    Useful for clearing a region before writing content, or for drawing
+    a styled background block.
+
+    Parameters
+    ----------
+    row:
+        Zero-based row offset of the top-left corner.
+    col:
+        Zero-based column offset of the top-left corner.
+    width:
+        Number of columns to fill.
+    height:
+        Number of rows to fill.
+    char:
+        The character to fill with. Defaults to a space (blank/clear).
+    style:
+        Optional style dict. See module docstring for valid keys.
+    """
+
+    row: int
+    col: int
+    width: int
+    height: int
+    char: str = ' '
+    style: dict | None = None
+
+
+@dataclass
+class CursorCmd:
+    """Hint: place the text cursor at region-relative (row, col).
+
+    This is a positioning hint, not a draw operation. Renderers that
+    support a visible text cursor (``context.supports('cursor')``) move
+    the cursor here after executing all other commands in the list.
+    Renderers that do not support a cursor ignore this command entirely.
+
+    There should be at most one ``CursorCmd`` per command list. If multiple
+    are present, the executor uses the last one.
+
+    Parameters
+    ----------
+    row:
+        Zero-based row offset from the top of the region.
+    col:
+        Zero-based column offset from the left of the region.
+    """
+
+    row: int
+    col: int
+
+
+#: Union type alias for the three command types.
+#: A ``render()`` method returns ``list[DrawCommand]``.
+DrawCommand = WriteCmd | FillCmd | CursorCmd

panelmark/exceptions.py

@@ -0,0 +1,13 @@
+class ShellSyntaxError(Exception):
+    def __init__(self, message, line=None):
+        self.message = message
+        self.line = line  # 1-based line number or None
+        super().__init__(f"line {line}: {message}" if line else message)
+
+
+class RegionNotFoundError(Exception):
+    pass
+
+
+class CircularUpdateError(Exception):
+    pass

panelmark/interactions/__init__.py

@@ -0,0 +1,4 @@
+from .base import Interaction
+from panelmark.draw import DrawCommand, RenderContext, WriteCmd, FillCmd, CursorCmd
+
+__all__ = ["Interaction", "DrawCommand", "RenderContext", "WriteCmd", "FillCmd", "CursorCmd"]

panelmark/interactions/base.py

@@ -0,0 +1,63 @@
+from abc import ABC, abstractmethod
+from panelmark.draw import DrawCommand, RenderContext
+
+
+class Interaction(ABC):
+    _shell = None  # Set by Shell.assign()
+
+    @property
+    def is_focusable(self) -> bool:
+        """Return True if this interaction can meaningfully receive keyboard focus.
+        Display-only interactions override this to return False."""
+        return True
+
+    @abstractmethod
+    def render(self, context: RenderContext, focused: bool = False) -> list[DrawCommand]:
+        """Return draw commands describing the current visual state of this interaction.
+
+        Commands use region-relative coordinates: ``(0, 0)`` is the top-left
+        cell of this interaction's assigned region. The renderer maps them to
+        screen-absolute positions when executing via its command executor.
+
+        The returned list should be a complete description of the interaction's
+        visual state for the given context dimensions. Partial updates are not
+        supported — callers may skip calling ``render()`` for regions they
+        determine are unchanged, so the list must always be fully self-contained.
+
+        Parameters
+        ----------
+        context:
+            Rendering context carrying region dimensions (``context.width``,
+            ``context.height``) and renderer capability flags. Use
+            ``context.supports(feature)`` to degrade gracefully on renderers
+            that lack a capability.
+        focused:
+            True if this interaction currently has keyboard focus.
+        """
+        ...
+
+    @abstractmethod
+    def handle_key(self, key) -> tuple:
+        """
+        Handle a keypress.
+        Returns (value_changed, new_value).
+        new_value is whatever Shell.get returns.
+        """
+        ...
+
+    @abstractmethod
+    def get_value(self):
+        """Return the current value of this interaction."""
+        ...
+
+    @abstractmethod
+    def set_value(self, value) -> None:
+        """Set the current value of this interaction."""
+        ...
+
+    def signal_return(self) -> tuple:
+        """
+        Called after handle_key to check if this interaction wants Shell.run() to return.
+        Returns (should_exit, return_value).
+        """
+        return False, None

panelmark/layout.py

@@ -0,0 +1,362 @@
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Region:
+    name: str
+    row: int        # 0-based terminal row
+    col: int        # 0-based terminal col
+    width: int
+    height: int
+    heading: str | None = None
+
+
+@dataclass
+class BorderRow:
+    style: str          # 'single' or 'double'
+    title: str | None
+
+
+@dataclass
+class Panel:
+    """Leaf node — a single named (or unnamed) content region."""
+    name: str | None
+    heading: str | None
+    # Width spec
+    width: int | None       # fixed chars; None = fill or use pct
+    is_pct: bool
+    pct: float | None       # percentage 0..100; used when is_pct is True
+    # Height spec
+    row_count: int | None   # None = infer from num_rows_def
+    row_count_is_pct: bool
+    row_pct: float | None
+    num_rows_def: int = 0   # definition lines in this panel's slot
+
+
+@dataclass
+class HSplit:
+    """Horizontal split: top child above a border line, bottom child below."""
+    top: object         # LayoutNode | None
+    bottom: object      # LayoutNode | None
+    border: BorderRow | None
+
+
+@dataclass
+class VSplit:
+    """Vertical split: left and right children side by side."""
+    left: object        # LayoutNode
+    right: object       # LayoutNode
+    divider: str        # 'single' or 'double'
+
+
+# Type alias (for documentation only — Python does not enforce it)
+# LayoutNode = HSplit | VSplit | Panel | None
+
+
+@dataclass
+class LayoutModel:
+    root: object        # LayoutNode | None
+    has_percentage: bool
+
+    def resolve(self, term_width: int, term_height: int,
+                offset_row: int = 0, offset_col: int = 0) -> list:
+        """Return a flat list of Region objects with absolute coordinates.
+
+        offset_row / offset_col shift the origin so that modal shells
+        (which render at an arbitrary screen position) produce regions
+        with the correct absolute terminal coordinates from the start.
+        """
+        if self.root is None:
+            return []
+        # Content area starts one column inside the left border wall.
+        return _resolve_node(self.root,
+                             offset_row,
+                             offset_col + 1,
+                             term_width - 2, term_height,
+                             pct_base=None)
+
+
+# ---------------------------------------------------------------------------
+# Recursive resolve
+# ---------------------------------------------------------------------------
+
+def _resolve_node(node, row: int, col: int, width: int, height: int,
+                  pct_base: int | None) -> list:
+    """
+    Recursively resolve a layout node to a flat list of Regions.
+
+    row, col   — absolute top-left position of this node
+    width      — available width (excluding outer border chars)
+    height     — available height in terminal rows
+    pct_base   — total interior width used as the denominator for % specs;
+                 None means "compute on first VSplit encountered"
+    """
+    if node is None:
+        return []
+
+    if isinstance(node, Panel):
+        if node.name:
+            return [Region(name=node.name, row=row, col=col,
+                           width=width, height=height,
+                           heading=node.heading)]
+        return []
+
+    if isinstance(node, VSplit):
+        if pct_base is None:
+            num_cols = _num_vsplit_cols(node)
+            # Subtract one divider per internal column boundary
+            pct_base = width - (num_cols - 1)
+
+        left_width = _vsplit_left_width(node, width, pct_base)
+        right_width = width - left_width - 1
+
+        regions = _resolve_node(node.left, row, col,
+                                left_width, height, pct_base)
+        regions += _resolve_node(node.right, row, col + left_width + 1,
+                                 right_width, height, pct_base)
+        return regions
+
+    if isinstance(node, HSplit):
+        top_height = (_declared_height(node.top, height)
+                      if node.top is not None else 0)
+        border_rows = 1 if node.border is not None else 0
+        bottom_height = max(0, height - top_height - border_rows)
+
+        regions = []
+        if node.top is not None:
+            regions += _resolve_node(node.top, row, col, width, top_height,
+                                     None)
+        if node.bottom is not None:
+            regions += _resolve_node(node.bottom,
+                                     row + top_height + border_rows,
+                                     col, width, bottom_height, None)
+        return regions
+
+    return []
+
+
+# ---------------------------------------------------------------------------
+# Width / height helpers
+# ---------------------------------------------------------------------------
+
+def _declared_width(node, available: int, pct_base: int) -> int:
+    """
+    How wide does this node want to be?
+
+    available  — remaining width at this level (after subtracting the
+                 divider that separates it from its sibling)
+    pct_base   — total interior width for percentage calculations
+    """
+    if node is None:
+        return available
+
+    if isinstance(node, Panel):
+        if node.is_pct and node.pct is not None:
+            return int(pct_base * node.pct / 100)
+        if node.width is not None:
+            return node.width
+        return available  # fill
+
+    if isinstance(node, HSplit):
+        # Both halves of an HSplit share the same width; delegate to a child.
+        child = node.top if node.top is not None else node.bottom
+        return _declared_width(child, available, pct_base)
+
+    if isinstance(node, VSplit):
+        # A VSplit takes all available width.
+        return available
+
+    return available
+
+
+def _declared_height(node, available: int) -> int:
+    """
+    How tall does this node want to be?
+    Panels without an explicit row_count use num_rows_def as a minimum.
+    The caller may give a Panel more height than it declares (stretch).
+    """
+    if node is None:
+        return 0
+
+    if isinstance(node, Panel):
+        if node.row_count is not None:
+            if node.row_count_is_pct and node.row_pct is not None:
+                return int(available * node.row_pct / 100)
+            return node.row_count
+        return max(1, node.num_rows_def)
+
+    if isinstance(node, VSplit):
+        lh = _declared_height(node.left, available)
+        rh = _declared_height(node.right, available)
+        return max(lh, rh)
+
+    if isinstance(node, HSplit):
+        top_h = (_declared_height(node.top, available)
+                 if node.top is not None else 0)
+        border_h = 1 if node.border is not None else 0
+        bot_h = (_declared_height(node.bottom, available)
+                 if node.bottom is not None else 0)
+        return top_h + border_h + bot_h
+
+    return 0
+
+
+def _fixed_width(node) -> int | None:
+    """
+    Return the node's exact content width if every column uses a fixed character
+    count (no percentages, no fill).  Returns None if any dimension is variable.
+
+    Does NOT include the two outer border-wall columns — add 2 for terminal width.
+    """
+    if node is None:
+        return 0
+
+    if isinstance(node, Panel):
+        if node.width is not None and not node.is_pct:
+            return node.width
+        return None   # fill or percentage
+
+    if isinstance(node, VSplit):
+        lw = _fixed_width(node.left)
+        rw = _fixed_width(node.right)
+        if lw is None or rw is None:
+            return None
+        return lw + 1 + rw   # left content + divider + right content
+
+    if isinstance(node, HSplit):
+        child = node.top if node.top is not None else node.bottom
+        return _fixed_width(child)
+
+    return None
+
+
+def _fixed_height(node) -> int | None:
+    """
+    Return the node's exact height in rows if every row-bearing panel carries an
+    explicit nR declaration (no fill, no percentage rows).  Returns None otherwise.
+
+    Border rows are always 1 row each and are always counted.
+    """
+    if node is None:
+        return 0
+
+    if isinstance(node, Panel):
+        if node.row_count is not None and not node.row_count_is_pct:
+            return node.row_count
+        return None   # fill (num_rows_def) or percentage
+
+    if isinstance(node, VSplit):
+        lh = _fixed_height(node.left)
+        rh = _fixed_height(node.right)
+        if lh is None or rh is None:
+            return None
+        return max(lh, rh)
+
+    if isinstance(node, HSplit):
+        top_h = 0
+        if node.top is not None:
+            top_h = _fixed_height(node.top)
+            if top_h is None:
+                return None
+        bot_h = 0
+        if node.bottom is not None:
+            bot_h = _fixed_height(node.bottom)
+            if bot_h is None:
+                return None
+        border_h = 1 if node.border is not None else 0
+        return top_h + border_h + bot_h
+
+    return None
+
+
+def _vsplit_left_width(node: "VSplit", width: int, pct_base: int) -> int:
+    """Return the left-panel width for a VSplit given *width* available chars.
+
+    Three cases, evaluated in order:
+
+    1. **Both sides entirely fill-width** — content space is divided equally
+       among all leaf columns; any remainder falls to the rightmost columns.
+    2. **Left side fill, right side has fixed/pct constraints** — right gets its
+       declared width first; left takes what remains.
+    3. **Left side has fixed/pct constraints** — left gets its declared width;
+       right takes what remains (including its own internal fill/fixed columns).
+
+    ``pct_base`` must already be computed before calling this helper.
+    """
+    left_all_fill = _is_all_fill(node.left)
+    right_all_fill = _is_all_fill(node.right)
+
+    if left_all_fill and right_all_fill:
+        # Equal distribution: each leaf column gets the same content width.
+        # Divide available content space (width minus inter-column dividers)
+        # evenly; remainder pixels fall to the rightmost columns naturally
+        # because the right child receives whatever the left doesn't claim.
+        total_cols = _num_vsplit_cols(node)
+        left_cols = _num_vsplit_cols(node.left)
+        content_width = width - (total_cols - 1)   # strip all inter-col dividers
+        content_per_col = content_width // total_cols
+        # Left total = its content + its own internal dividers
+        left_width = content_per_col * left_cols + (left_cols - 1)
+        return max(0, min(left_width, width - 1))
+
+    if left_all_fill and not right_all_fill:
+        # Right has at least one fixed/pct column; allocate it first.
+        right_w = min(_declared_width(node.right, width - 1, pct_base), width - 1)
+        return max(0, width - right_w - 1)
+
+    # Left has at least one fixed/pct column; allocate it first.
+    return _declared_width(node.left, width - 1, pct_base)
+
+
+def _is_fill_node(node) -> bool:
+    """Return True if *node* itself has no explicit fixed-char or percentage width.
+
+    This is a shallow check — a VSplit always returns False because it is
+    treated as taking all available width regardless of its children's specs.
+    Use ``_is_all_fill`` to check whether an entire subtree is fill-only.
+    """
+    if node is None:
+        return True
+    if isinstance(node, Panel):
+        return node.width is None and not node.is_pct
+    if isinstance(node, HSplit):
+        child = node.top if node.top is not None else node.bottom
+        return _is_fill_node(child)
+    if isinstance(node, VSplit):
+        # A VSplit consumes all available width regardless of its children.
+        return False
+    return True
+
+
+def _is_all_fill(node) -> bool:
+    """Return True if *every* leaf Panel in this subtree is fill-width.
+
+    Unlike ``_is_fill_node``, this recurses into VSplit children so that a
+    VSplit whose entire column tree has no fixed/pct constraints is correctly
+    identified as all-fill.
+    """
+    if node is None:
+        return True
+    if isinstance(node, Panel):
+        return node.width is None and not node.is_pct
+    if isinstance(node, HSplit):
+        child = node.top if node.top is not None else node.bottom
+        return _is_all_fill(child)
+    if isinstance(node, VSplit):
+        return _is_all_fill(node.left) and _is_all_fill(node.right)
+    return True
+
+
+def _num_vsplit_cols(node) -> int:
+    """Count the total number of leaf Panel columns in a node's subtree."""
+    if node is None:
+        return 0
+    if isinstance(node, Panel):
+        return 1
+    if isinstance(node, VSplit):
+        return _num_vsplit_cols(node.left) + _num_vsplit_cols(node.right)
+    if isinstance(node, HSplit):
+        # Both halves of an HSplit are in the same column — count one side.
+        child = node.top if node.top is not None else node.bottom
+        return _num_vsplit_cols(child)
+    return 1

panelmark/observer.py

@@ -0,0 +1,49 @@
+from .exceptions import CircularUpdateError
+
+
+class ChangeHandle:
+    def __init__(self, observer, name, callback_id):
+        self._observer = observer
+        self._name = name
+        self._callback_id = callback_id
+
+    def remove(self) -> None:
+        self._observer._remove(self._name, self._callback_id)
+
+
+class Observer:
+    def __init__(self):
+        self._callbacks = {}  # name -> dict of {id: callback}
+        self._next_id = 0
+
+    def register(self, name: str, callback) -> ChangeHandle:
+        if name not in self._callbacks:
+            self._callbacks[name] = {}
+        cb_id = self._next_id
+        self._next_id += 1
+        self._callbacks[name][cb_id] = callback
+        return ChangeHandle(self, name, cb_id)
+
+    def _remove(self, name: str, callback_id: int) -> None:
+        if name in self._callbacks and callback_id in self._callbacks[name]:
+            del self._callbacks[name][callback_id]
+
+    def notify(self, name: str, value, updating: set | None = None) -> None:
+        """
+        Notify all callbacks registered on name.
+        updating is the set of currently-updating region names for cycle detection.
+        Raises CircularUpdateError if name is already in updating.
+        """
+        if updating is None:
+            updating = set()
+
+        if name in updating:
+            raise CircularUpdateError(
+                f"circular update detected involving '{name}'"
+            )
+
+        updating = updating | {name}
+
+        callbacks = self._callbacks.get(name, {})
+        for cb_id, callback in list(callbacks.items()):
+            callback(value, updating)