panelmark-html 0.1.0__tar.gz

panelmark_html-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_html-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.2
+Name: panelmark-html
+Version: 0.1.0
+Summary: Static HTML/CSS renderer for panelmark shells.
+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-html
+Keywords: ui,layout,html,renderer,panelmark
+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
+Requires-Dist: panelmark>=0.1.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: panelmark; extra == "dev"
+
+# panelmark-html
+
+**panelmark-html** is the static HTML/CSS renderer for the
+[panelmark](https://github.com/sirrommit/panelmark) ecosystem. Given a
+`panelmark` shell and its assigned interactions, it produces an HTML document
+or fragment representing the shell's panel structure.
+
+---
+
+## What this package is
+
+- A static renderer: layout model in, HTML string out.
+- Useful for server-side rendering into Flask/Django templates, generating
+  reports or dashboards, and automated snapshot tests.
+- The structural foundation that `panelmark-web` will build live interactivity
+  on top of.
+
+## What this package is not
+
+- It does not handle browser events, keyboard or mouse input, or focus
+  transitions.
+- It does not open sockets, HTTP routes, or sessions.
+- It does not render interaction-internal state (item lists, form fields,
+  text content). Panel bodies are empty placeholders with stable DOM hooks;
+  filling them in with live content is the job of `panelmark-web`.
+- It does not require JavaScript for its output to be valid HTML.
+
+## Relationship to panelmark-web
+
+`panelmark-html` and `panelmark-web` are separate packages with distinct scopes.
+
+| Package | Role |
+|---------|------|
+| **panelmark-html** | Static structure: panel layout, borders, headings, stable DOM hooks |
+| **panelmark-web** | Live layer: WebSocket sessions, browser events, interaction rendering, draw-command updates |
+
+`panelmark-web` depends on `panelmark-html` for its rendered structure. The
+DOM hooks and CSS classes defined here are the stable contract between the two
+packages.
+
+## Installation
+
+```
+pip install panelmark-html
+```
+
+## Dependencies
+
+- `panelmark` — core layout model and shell state machine
+- No web framework dependency
+- No JavaScript build step
+
+## Status
+
+**Package maturity:** Pre-alpha. The public Python API (`render_fragment`,
+`render_document`, `get_base_css`, `HTMLRenderer`) and higher-level rendering
+features may still evolve.
+
+**Hook contract:** The region-level DOM hooks (`data-pm-region`, `id`,
+`data-pm-*` attributes) and CSS classes (`.pm-shell`, `.pm-split-*`,
+`.pm-panel`, `.pm-panel-body`) are the intended stable substrate for
+`panelmark-web` and are documented as such in
+[docs/hook-contract.md](docs/hook-contract.md).  These will not change
+without a major version bump.
+
+## Quick start
+
+```python
+from panelmark import Shell
+from panelmark_html import render_fragment, get_base_css
+
+LAYOUT = """
+|=== <bold>My App</> ===|
+|{$main$            }|
+|==================|
+|{2R $status$       }|
+|==================|
+"""
+
+shell = Shell(LAYOUT)
+html = render_fragment(shell)
+# Panel bodies are empty — fill them with panelmark-web or your own renderer.
+print(html)
+```
+
+For a complete HTML document including base CSS:
+
+```python
+document = render_document(shell)
+# Returns a full <html>...<body>...</body></html> string with embedded CSS.
+```
+
+## API
+
+| Symbol | Description |
+|--------|-------------|
+| `render_fragment(shell)` | Renders the shell as an HTML fragment (no `<html>` or `<head>` wrapper). Returns a string. |
+| `render_document(shell)` | Renders the shell as a complete HTML document, including the base CSS inline. Returns a string. |
+| `get_base_css()` | Returns the base CSS string for manual inclusion in your own template. |
+| `HTMLRenderer` | Low-level renderer class. Use this for custom integration or when you need per-region control. |
+
+All symbols are importable from `panelmark_html`. Full API reference:
+[panelmark-html rendering API](https://github.com/sirrommit/panelmark-docs/blob/main/docs/panelmark-html/rendering-api.md)
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Hook Contract](docs/hook-contract.md) | Stable DOM interface: element structure, CSS classes, `data-pm-*` attributes, CSS custom properties. **Canonical location — this repo.** |
+| [Rendering API Reference](https://github.com/sirrommit/panelmark-docs/blob/main/docs/panelmark-html/rendering-api.md) | Full reference for `render_fragment`, `render_document`, `get_base_css`, and `HTMLRenderer` |
+| [Ecosystem Overview](https://github.com/sirrommit/panelmark-docs/blob/main/docs/ecosystem.md) | How panelmark-html fits into the panelmark package ecosystem |
+| [Shell Language](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/overview.md) | ASCII-art layout syntax reference |
+| [panelmark-web](https://github.com/sirrommit/panelmark-web) | Live web runtime that builds on this package's hook contract |

panelmark_html-0.1.0/README.md

@@ -0,0 +1,113 @@
+# panelmark-html
+
+**panelmark-html** is the static HTML/CSS renderer for the
+[panelmark](https://github.com/sirrommit/panelmark) ecosystem. Given a
+`panelmark` shell and its assigned interactions, it produces an HTML document
+or fragment representing the shell's panel structure.
+
+---
+
+## What this package is
+
+- A static renderer: layout model in, HTML string out.
+- Useful for server-side rendering into Flask/Django templates, generating
+  reports or dashboards, and automated snapshot tests.
+- The structural foundation that `panelmark-web` will build live interactivity
+  on top of.
+
+## What this package is not
+
+- It does not handle browser events, keyboard or mouse input, or focus
+  transitions.
+- It does not open sockets, HTTP routes, or sessions.
+- It does not render interaction-internal state (item lists, form fields,
+  text content). Panel bodies are empty placeholders with stable DOM hooks;
+  filling them in with live content is the job of `panelmark-web`.
+- It does not require JavaScript for its output to be valid HTML.
+
+## Relationship to panelmark-web
+
+`panelmark-html` and `panelmark-web` are separate packages with distinct scopes.
+
+| Package | Role |
+|---------|------|
+| **panelmark-html** | Static structure: panel layout, borders, headings, stable DOM hooks |
+| **panelmark-web** | Live layer: WebSocket sessions, browser events, interaction rendering, draw-command updates |
+
+`panelmark-web` depends on `panelmark-html` for its rendered structure. The
+DOM hooks and CSS classes defined here are the stable contract between the two
+packages.
+
+## Installation
+
+```
+pip install panelmark-html
+```
+
+## Dependencies
+
+- `panelmark` — core layout model and shell state machine
+- No web framework dependency
+- No JavaScript build step
+
+## Status
+
+**Package maturity:** Pre-alpha. The public Python API (`render_fragment`,
+`render_document`, `get_base_css`, `HTMLRenderer`) and higher-level rendering
+features may still evolve.
+
+**Hook contract:** The region-level DOM hooks (`data-pm-region`, `id`,
+`data-pm-*` attributes) and CSS classes (`.pm-shell`, `.pm-split-*`,
+`.pm-panel`, `.pm-panel-body`) are the intended stable substrate for
+`panelmark-web` and are documented as such in
+[docs/hook-contract.md](docs/hook-contract.md).  These will not change
+without a major version bump.
+
+## Quick start
+
+```python
+from panelmark import Shell
+from panelmark_html import render_fragment, get_base_css
+
+LAYOUT = """
+|=== <bold>My App</> ===|
+|{$main$            }|
+|==================|
+|{2R $status$       }|
+|==================|
+"""
+
+shell = Shell(LAYOUT)
+html = render_fragment(shell)
+# Panel bodies are empty — fill them with panelmark-web or your own renderer.
+print(html)
+```
+
+For a complete HTML document including base CSS:
+
+```python
+document = render_document(shell)
+# Returns a full <html>...<body>...</body></html> string with embedded CSS.
+```
+
+## API
+
+| Symbol | Description |
+|--------|-------------|
+| `render_fragment(shell)` | Renders the shell as an HTML fragment (no `<html>` or `<head>` wrapper). Returns a string. |
+| `render_document(shell)` | Renders the shell as a complete HTML document, including the base CSS inline. Returns a string. |
+| `get_base_css()` | Returns the base CSS string for manual inclusion in your own template. |
+| `HTMLRenderer` | Low-level renderer class. Use this for custom integration or when you need per-region control. |
+
+All symbols are importable from `panelmark_html`. Full API reference:
+[panelmark-html rendering API](https://github.com/sirrommit/panelmark-docs/blob/main/docs/panelmark-html/rendering-api.md)
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [Hook Contract](docs/hook-contract.md) | Stable DOM interface: element structure, CSS classes, `data-pm-*` attributes, CSS custom properties. **Canonical location — this repo.** |
+| [Rendering API Reference](https://github.com/sirrommit/panelmark-docs/blob/main/docs/panelmark-html/rendering-api.md) | Full reference for `render_fragment`, `render_document`, `get_base_css`, and `HTMLRenderer` |
+| [Ecosystem Overview](https://github.com/sirrommit/panelmark-docs/blob/main/docs/ecosystem.md) | How panelmark-html fits into the panelmark package ecosystem |
+| [Shell Language](https://github.com/sirrommit/panelmark-docs/blob/main/docs/shell-language/overview.md) | ASCII-art layout syntax reference |
+| [panelmark-web](https://github.com/sirrommit/panelmark-web) | Live web runtime that builds on this package's hook contract |

panelmark_html-0.1.0/panelmark_html/__init__.py

@@ -0,0 +1,55 @@
+"""panelmark-html — static HTML/CSS renderer for panelmark shells.
+
+This package converts a panelmark Shell into an HTML document or fragment.
+It does not handle browser events, network transport, or live interaction
+state.  For a live web application, use panelmark-web, which builds on top
+of this package.
+
+Public API
+----------
+render_fragment(shell, *, include_css=False) -> str
+render_document(shell, *, title="panelmark", css_href=None, extra_head="") -> str
+get_base_css() -> str
+HTMLRenderer
+"""
+
+from .renderer import HTMLRenderer
+from .css import get_base_css
+
+
+def render_fragment(shell, *, include_css: bool = False) -> str:
+    """Return an HTML fragment for *shell*.
+
+    Parameters
+    ----------
+    shell:
+        A ``panelmark.Shell`` instance.
+    include_css:
+        If True, prepend a ``<style>`` block with the base CSS.
+    """
+    return HTMLRenderer().render_fragment(shell, include_css=include_css)
+
+
+def render_document(shell, *, title: str = 'panelmark',
+                    css_href: str | None = None,
+                    extra_head: str = '') -> str:
+    """Return a full HTML document for *shell*.
+
+    Parameters
+    ----------
+    shell:
+        A ``panelmark.Shell`` instance.
+    title:
+        Value for the ``<title>`` element.
+    css_href:
+        If provided, emit a ``<link>`` to this stylesheet instead of
+        inlining the base CSS.
+    extra_head:
+        Optional raw HTML string appended inside ``<head>``.
+    """
+    return HTMLRenderer().render_document(
+        shell, title=title, css_href=css_href, extra_head=extra_head
+    )
+
+
+__all__ = ['HTMLRenderer', 'render_fragment', 'render_document', 'get_base_css']

panelmark_html-0.1.0/panelmark_html/css.py

@@ -0,0 +1,135 @@
+_BASE_CSS = """\
+/* panelmark-html base styles
+ *
+ * All visual values are controlled by CSS custom properties.
+ * Override any variable in your own stylesheet to theme the shell.
+ *
+ * Custom properties
+ * -----------------
+ * --pm-border-color        border / divider colour
+ * --pm-border-width        thickness of all borders and dividers
+ * --pm-gap                 gap between sibling panels (not used by default;
+ *                          override to add spacing between panels)
+ * --pm-radius              corner radius on panels
+ * --pm-heading-font-weight heading font weight
+ * --pm-panel-padding       padding inside panel body and heading
+ * --pm-focused-border-color  border colour on the focused panel
+ * --pm-focused-border-width  border thickness on the focused panel
+ */
+
+:root {
+  --pm-border-color: #888;
+  --pm-border-width: 1px;
+  --pm-gap: 0px;
+  --pm-radius: 0px;
+  --pm-heading-font-weight: bold;
+  --pm-panel-padding: 0.5rem;
+  --pm-focused-border-color: #4a9eff;
+  --pm-focused-border-width: 2px;
+}
+
+/* Shell container --------------------------------------------------------- */
+
+.pm-shell {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  font-family: monospace, monospace;
+  font-size: 0.875rem;
+  border: var(--pm-border-width) solid var(--pm-border-color);
+  border-radius: var(--pm-radius);
+}
+
+/* Splits ------------------------------------------------------------------ */
+
+.pm-split {
+  display: flex;
+  flex: 1 1 0;
+  min-height: 0;
+  min-width: 0;
+  gap: var(--pm-gap);
+}
+
+.pm-split-h {
+  flex-direction: column;
+}
+
+.pm-split-v {
+  flex-direction: row;
+}
+
+/* Single-pixel dividers between sibling panels, without double borders */
+.pm-split-h > * + * {
+  border-top: var(--pm-border-width) solid var(--pm-border-color);
+}
+
+.pm-split-v > * + * {
+  border-left: var(--pm-border-width) solid var(--pm-border-color);
+}
+
+/* Panels ------------------------------------------------------------------ */
+
+.pm-panel[data-pm-focused="true"] {
+  outline: var(--pm-focused-border-width) solid var(--pm-focused-border-color);
+  outline-offset: -1px;
+}
+
+.pm-panel {
+  display: flex;
+  flex-direction: column;
+  flex: 1 1 0;
+  min-height: 0;
+  min-width: 0;
+  box-sizing: border-box;
+  overflow: hidden;
+}
+
+.pm-panel-heading {
+  flex-shrink: 0;
+  box-sizing: border-box;
+  padding: 0.25rem var(--pm-panel-padding);
+  font-weight: var(--pm-heading-font-weight);
+  border-bottom: var(--pm-border-width) solid var(--pm-border-color);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.pm-panel-body {
+  flex: 1 1 0;
+  min-height: 0;
+  box-sizing: border-box;
+  padding: var(--pm-panel-padding);
+  overflow: auto;
+}
+"""
+
+
+def get_base_css() -> str:
+    """Return the base CSS string for panelmark-html layouts.
+
+    The returned string uses CSS custom properties (variables) for all
+    visual values so that embedding applications can theme the shell
+    without modifying this stylesheet.
+
+    The focused-panel highlight is controlled by
+    ``--pm-focused-border-color`` and ``--pm-focused-border-width``.
+    These are used by the ``[data-pm-focused="true"]`` rule and are
+    updated live by ``panelmark-web`` after each key event.
+
+    Suggested usage::
+
+        # Inline in a document
+        page = render_document(shell, title="My App")
+
+        # Link an external copy
+        page = render_document(shell, css_href="/static/panelmark.css")
+        # then write get_base_css() to that path at build time
+
+        # Embed in a fragment
+        fragment = render_fragment(shell, include_css=True)
+    """
+    return _BASE_CSS

panelmark_html-0.1.0/panelmark_html/renderer.py

@@ -0,0 +1,166 @@
+from html import escape
+
+from panelmark.layout import HSplit, VSplit, Panel
+
+from .css import get_base_css
+
+
+class HTMLRenderer:
+    """Converts a panelmark Shell into an HTML fragment or full document.
+
+    Renders the shell's panel structure with stable DOM hooks.  Each named
+    panel that has an assigned interaction receives ``data-pm-interaction``,
+    ``data-pm-focusable``, and ``data-pm-focused`` attributes.  Named panels
+    without an assigned interaction receive ``data-pm-empty="true"``.  Panel
+    bodies are always empty placeholders; interaction body content is deferred
+    to ``panelmark-web``.
+
+    CSS rules are provided by ``get_base_css()``.
+    """
+
+    def render_fragment(self, shell, *, include_css: bool = False) -> str:
+        """Return an HTML fragment for *shell*.
+
+        Parameters
+        ----------
+        shell:
+            A ``panelmark.Shell`` instance.
+        include_css:
+            If True, prepend a ``<style>`` block with the base CSS.
+        """
+        parts = []
+        if include_css:
+            css = get_base_css()
+            if css:
+                parts.append(f'<style>\n{css}\n</style>\n')
+        parts.append(self._render_shell(shell))
+        return ''.join(parts)
+
+    def render_document(self, shell, *, title: str = 'panelmark',
+                        css_href: str | None = None,
+                        extra_head: str = '') -> str:
+        """Return a full HTML document for *shell*.
+
+        Parameters
+        ----------
+        shell:
+            A ``panelmark.Shell`` instance.
+        title:
+            Value for the ``<title>`` element.
+        css_href:
+            If provided, emit a ``<link>`` to this stylesheet instead of
+            inlining the base CSS.
+        extra_head:
+            Optional raw HTML string appended inside ``<head>`` before
+            ``</head>``.
+        """
+        head_lines = [
+            '    <meta charset="UTF-8">',
+            '    <meta name="viewport" content="width=device-width, initial-scale=1.0">',
+            f'    <title>{escape(title)}</title>',
+        ]
+        if css_href:
+            head_lines.append(
+                f'    <link rel="stylesheet" href="{escape(css_href, quote=True)}">'
+            )
+        else:
+            css = get_base_css()
+            if css:
+                head_lines.append(f'    <style>\n{css}\n    </style>')
+        if extra_head:
+            head_lines.append(f'    {extra_head}')
+
+        head = '\n'.join(head_lines)
+        fragment = self._render_shell(shell)
+
+        return (
+            '<!DOCTYPE html>\n'
+            '<html lang="en">\n'
+            '<head>\n'
+            f'{head}\n'
+            '</head>\n'
+            '<body>\n'
+            f'{fragment}'
+            '</body>\n'
+            '</html>\n'
+        )
+
+    # ------------------------------------------------------------------
+    # Internal rendering
+    # ------------------------------------------------------------------
+
+    def _render_shell(self, shell) -> str:
+        node = shell.layout.root
+        if node is None:
+            return '<div class="pm-shell" data-pm-shell></div>\n'
+        inner = self._render_node(node, shell, indent=2)
+        return f'<div class="pm-shell" data-pm-shell>\n{inner}</div>\n'
+
+    def _render_node(self, node, shell, indent: int = 0) -> str:
+        if node is None:
+            return ''
+        pad = ' ' * indent
+
+        if isinstance(node, Panel):
+            return self._render_panel(node, shell, indent)
+
+        if isinstance(node, VSplit):
+            left = self._render_node(node.left, shell, indent + 2)
+            right = self._render_node(node.right, shell, indent + 2)
+            return (
+                f'{pad}<div class="pm-split pm-split-v">\n'
+                f'{left}'
+                f'{right}'
+                f'{pad}</div>\n'
+            )
+
+        if isinstance(node, HSplit):
+            top = self._render_node(node.top, shell, indent + 2)
+            bottom = self._render_node(node.bottom, shell, indent + 2)
+            return (
+                f'{pad}<div class="pm-split pm-split-h">\n'
+                f'{top}'
+                f'{bottom}'
+                f'{pad}</div>\n'
+            )
+
+        return ''
+
+    def _render_panel(self, node: Panel, shell, indent: int = 0) -> str:
+        pad = ' ' * indent
+        inner = ' ' * (indent + 2)
+
+        attrs = ['class="pm-panel"']
+        if node.name:
+            attrs.append(f'data-pm-region="{escape(node.name, quote=True)}"')
+            attrs.append('data-pm-kind="panel"')
+            attrs.append(f'id="pm-region-{escape(node.name, quote=True)}"')
+
+            if node.heading:
+                attrs.append(f'data-pm-heading="{escape(node.heading, quote=True)}"')
+
+            interaction = shell.interactions.get(node.name)
+            if interaction is not None:
+                cls = type(interaction)
+                qualified = f'{cls.__module__}.{cls.__qualname__}'
+                focusable = 'true' if interaction.is_focusable else 'false'
+                focused = 'true' if shell.focus == node.name else 'false'
+                attrs.append(f'data-pm-interaction="{escape(qualified, quote=True)}"')
+                attrs.append(f'data-pm-focusable="{focusable}"')
+                attrs.append(f'data-pm-focused="{focused}"')
+            else:
+                attrs.append('data-pm-empty="true"')
+
+        lines = [f'{pad}<section {" ".join(attrs)}>\n']
+
+        if node.heading:
+            lines.append(
+                f'{inner}<header class="pm-panel-heading">'
+                f'{escape(node.heading)}'
+                f'</header>\n'
+            )
+
+        lines.append(f'{inner}<div class="pm-panel-body"></div>\n')
+        lines.append(f'{pad}</section>\n')
+
+        return ''.join(lines)