panelmark 0.1.0__tar.gz

panelmark-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Timothy Morris PhD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

panelmark-0.1.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.2
+Name: panelmark
+Version: 0.1.0
+Summary: A markup language for UI layouts — define panels once, render anywhere.
+Author-email: Timothy Morris PhD <sirrommit@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2024 Timothy Morris PhD
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Repository, https://github.com/sirrommit/panelmark
+Keywords: ui,layout,dsl,markup,tui,terminal,gui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+
+# panelmark
+
+**panelmark** is a zero-dependency Python library for defining terminal UI layouts using a readable
+ASCII-art shell language, and for implementing the interaction logic that runs inside them.
+
+panelmark is the **core library** in the panelmark ecosystem. It has no runtime dependencies on
+any terminal library. It defines:
+
+---
+
+## What is real today
+
+| Feature | Status |
+|---------|--------|
+| Shell definition language (ASCII-art DSL) | ✅ Fully working |
+| `#` line comments and `/* */` block comments | ✅ Fully working |
+| Horizontal splits (`=` / `-` border rows) | ✅ Fully working |
+| Vertical splits — single-line divider (`\|`) | ✅ Fully working |
+| Vertical splits — double-line divider (`\|\|`) | ✅ Fully working |
+| Equal-width fill splits (all columns fill-width) | ✅ Columns share space equally (differ by at most 1 char) |
+| Panel headings (`__text__` syntax) | ⚠️ Parsed and stored; renderers must implement display |
+| `Shell` state machine (focus, dirty tracking, key dispatch, `on_change`, `bind`) | ✅ Fully working |
+| Draw command abstraction (`DrawCommand`, `RenderContext`, `WriteCmd`, `FillCmd`, `CursorCmd`) | ✅ Fully working |
+| `Interaction` base class | ✅ Fully working |
+
+See [panelmark-tui limitations](https://github.com/sirrommit/panelmark-docs/blob/main/docs/panelmark-tui/limitations.md) for the combined limitations list.
+
+---
+
+- The **shell definition language** — an ASCII-art syntax for describing layouts
+- The **layout model** — resolved geometry (row, col, width, height) for each named region
+- The **draw command abstraction** — renderer-agnostic `DrawCommand` types returned by interactions
+- The **`Interaction` base class** — the protocol all interactive widgets implement
+- The **`Shell` state machine** — focus, dirty tracking, key dispatch, and value observation
+
+To actually display a shell in a terminal, pair panelmark with
+[**panelmark-tui**](https://github.com/sirrommit/panelmark-tui), which wraps
+[blessed](https://github.com/jquast/blessed) and provides a full event loop, built-in
+interactions, and renderer-specific convenience widgets.
+
+---
+
+## Installation
+
+```
+pip install panelmark
+```
+
+---
+
+## Quick start
+
+```python
+from panelmark import Shell, Interaction
+from panelmark.draw import DrawCommand, RenderContext, WriteCmd, FillCmd
+
+# 1. Define a layout
+LAYOUT = """
+|=== <bold>My App</> ===|
+|{10R $sidebar$  }|{$main$        }|
+|==================|
+|{2R  $status$              }|
+|==================|
+"""
+
+# 2. Implement an interaction
+class Label(Interaction):
+    def __init__(self, text: str):
+        self._text = text
+
+    @property
+    def is_focusable(self) -> bool:
+        return False
+
+    def render(self, context: RenderContext, focused: bool = False) -> list[DrawCommand]:
+        line = self._text[:context.width].ljust(context.width)
+        return [WriteCmd(row=0, col=0, text=line)]
+
+    def handle_key(self, key) -> tuple:
+        return False, self.get_value()
+
+    def get_value(self):
+        return self._text
+
+    def set_value(self, value) -> None:
+        self._text = str(value)
+
+# 3. Assign interactions to regions
+shell = Shell(LAYOUT)
+shell.assign("sidebar", Label("Navigation"))
+shell.assign("main", Label("Content area"))
+shell.assign("status", Label("Ready"))
+
+# 4. Drive with a renderer (e.g. panelmark-tui)
+# result = shell.run()   ← panelmark_tui.Shell adds run()
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Shell Language](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/overview.md) | Shell, region, and panel concepts; state machine methods |
+| [Shell Language Syntax](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/syntax.md) | Full grammar reference for the ASCII-art layout DSL |
+| [Shell Language Examples](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/examples.md) | Annotated examples; custom interactions; portable rendering patterns |
+| [Draw Commands](https://github.com/sirrommit/panelmark-docs/blob/main/docs/renderer-spec/contract.md) | `DrawCommand` types, `RenderContext`, and the style dict |
+| [Custom Interactions](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/examples.md) | Implementing the `Interaction` ABC |
+| [Renderer Spec](https://github.com/sirrommit/panelmark-docs/blob/main/docs/renderer-spec/overview.md) | Renderer compatibility contract, portable library layer, and extension policy |
+| [Ecosystem Overview](https://github.com/sirrommit/panelmark-docs/blob/main/docs/ecosystem.md) | Layered design; package responsibilities; dependency direction |
+| [Choosing a Renderer](https://github.com/sirrommit/panelmark-docs/blob/main/docs/getting-started.md) | Decision tree for selecting the right package |
+
+---
+
+## Ecosystem
+
+panelmark follows a layered design. The core library is renderer-agnostic;
+renderer-specific packages extend it.
+
+| Package | Role |
+|---------|------|
+| **panelmark** (this package) | Zero-dependency core: shell language, layout, draw commands, interaction protocol |
+| [**panelmark-tui**](https://github.com/sirrommit/panelmark-tui) | Terminal renderer (blessed); portable-library-compatible |
+| [**panelmark-html**](https://github.com/sirrommit/panelmark-html) | Static HTML/CSS renderer; pre-alpha; foundation for panelmark-web |
+| [**panelmark-web**](https://github.com/sirrommit/panelmark-web) | Live web runtime via WebSockets; portable-library-compatible |
+
+See [ecosystem overview](https://github.com/sirrommit/panelmark-docs/blob/main/docs/ecosystem.md)
+for the full design rationale and dependency diagram.
+
+---
+
+## License
+
+MIT

panelmark-0.1.0/README.md

@@ -0,0 +1,134 @@
+# panelmark
+
+**panelmark** is a zero-dependency Python library for defining terminal UI layouts using a readable
+ASCII-art shell language, and for implementing the interaction logic that runs inside them.
+
+panelmark is the **core library** in the panelmark ecosystem. It has no runtime dependencies on
+any terminal library. It defines:
+
+---
+
+## What is real today
+
+| Feature | Status |
+|---------|--------|
+| Shell definition language (ASCII-art DSL) | ✅ Fully working |
+| `#` line comments and `/* */` block comments | ✅ Fully working |
+| Horizontal splits (`=` / `-` border rows) | ✅ Fully working |
+| Vertical splits — single-line divider (`\|`) | ✅ Fully working |
+| Vertical splits — double-line divider (`\|\|`) | ✅ Fully working |
+| Equal-width fill splits (all columns fill-width) | ✅ Columns share space equally (differ by at most 1 char) |
+| Panel headings (`__text__` syntax) | ⚠️ Parsed and stored; renderers must implement display |
+| `Shell` state machine (focus, dirty tracking, key dispatch, `on_change`, `bind`) | ✅ Fully working |
+| Draw command abstraction (`DrawCommand`, `RenderContext`, `WriteCmd`, `FillCmd`, `CursorCmd`) | ✅ Fully working |
+| `Interaction` base class | ✅ Fully working |
+
+See [panelmark-tui limitations](https://github.com/sirrommit/panelmark-docs/blob/main/docs/panelmark-tui/limitations.md) for the combined limitations list.
+
+---
+
+- The **shell definition language** — an ASCII-art syntax for describing layouts
+- The **layout model** — resolved geometry (row, col, width, height) for each named region
+- The **draw command abstraction** — renderer-agnostic `DrawCommand` types returned by interactions
+- The **`Interaction` base class** — the protocol all interactive widgets implement
+- The **`Shell` state machine** — focus, dirty tracking, key dispatch, and value observation
+
+To actually display a shell in a terminal, pair panelmark with
+[**panelmark-tui**](https://github.com/sirrommit/panelmark-tui), which wraps
+[blessed](https://github.com/jquast/blessed) and provides a full event loop, built-in
+interactions, and renderer-specific convenience widgets.
+
+---
+
+## Installation
+
+```
+pip install panelmark
+```
+
+---
+
+## Quick start
+
+```python
+from panelmark import Shell, Interaction
+from panelmark.draw import DrawCommand, RenderContext, WriteCmd, FillCmd
+
+# 1. Define a layout
+LAYOUT = """
+|=== <bold>My App</> ===|
+|{10R $sidebar$  }|{$main$        }|
+|==================|
+|{2R  $status$              }|
+|==================|
+"""
+
+# 2. Implement an interaction
+class Label(Interaction):
+    def __init__(self, text: str):
+        self._text = text
+
+    @property
+    def is_focusable(self) -> bool:
+        return False
+
+    def render(self, context: RenderContext, focused: bool = False) -> list[DrawCommand]:
+        line = self._text[:context.width].ljust(context.width)
+        return [WriteCmd(row=0, col=0, text=line)]
+
+    def handle_key(self, key) -> tuple:
+        return False, self.get_value()
+
+    def get_value(self):
+        return self._text
+
+    def set_value(self, value) -> None:
+        self._text = str(value)
+
+# 3. Assign interactions to regions
+shell = Shell(LAYOUT)
+shell.assign("sidebar", Label("Navigation"))
+shell.assign("main", Label("Content area"))
+shell.assign("status", Label("Ready"))
+
+# 4. Drive with a renderer (e.g. panelmark-tui)
+# result = shell.run()   ← panelmark_tui.Shell adds run()
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Shell Language](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/overview.md) | Shell, region, and panel concepts; state machine methods |
+| [Shell Language Syntax](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/syntax.md) | Full grammar reference for the ASCII-art layout DSL |
+| [Shell Language Examples](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/examples.md) | Annotated examples; custom interactions; portable rendering patterns |
+| [Draw Commands](https://github.com/sirrommit/panelmark-docs/blob/main/docs/renderer-spec/contract.md) | `DrawCommand` types, `RenderContext`, and the style dict |
+| [Custom Interactions](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/examples.md) | Implementing the `Interaction` ABC |
+| [Renderer Spec](https://github.com/sirrommit/panelmark-docs/blob/main/docs/renderer-spec/overview.md) | Renderer compatibility contract, portable library layer, and extension policy |
+| [Ecosystem Overview](https://github.com/sirrommit/panelmark-docs/blob/main/docs/ecosystem.md) | Layered design; package responsibilities; dependency direction |
+| [Choosing a Renderer](https://github.com/sirrommit/panelmark-docs/blob/main/docs/getting-started.md) | Decision tree for selecting the right package |
+
+---
+
+## Ecosystem
+
+panelmark follows a layered design. The core library is renderer-agnostic;
+renderer-specific packages extend it.
+
+| Package | Role |
+|---------|------|
+| **panelmark** (this package) | Zero-dependency core: shell language, layout, draw commands, interaction protocol |
+| [**panelmark-tui**](https://github.com/sirrommit/panelmark-tui) | Terminal renderer (blessed); portable-library-compatible |
+| [**panelmark-html**](https://github.com/sirrommit/panelmark-html) | Static HTML/CSS renderer; pre-alpha; foundation for panelmark-web |
+| [**panelmark-web**](https://github.com/sirrommit/panelmark-web) | Live web runtime via WebSockets; portable-library-compatible |
+
+See [ecosystem overview](https://github.com/sirrommit/panelmark-docs/blob/main/docs/ecosystem.md)
+for the full design rationale and dependency diagram.
+
+---
+
+## License
+
+MIT

panelmark-0.1.0/panelmark/__init__.py

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

panelmark-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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