protonic 0.1.0__tar.gz

protonic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kyle Gallagher
+
+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.

protonic-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: protonic
+Version: 0.1.0
+Summary: Instant OS App Prototyping & Declarative UI Engine
+Author-email: Kyle Gallagher <kidlucrid@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dieablo101/protonic
+Project-URL: Documentation, https://dieablo101.github.io/protonic/
+Project-URL: Repository, https://github.com/dieablo101/protonic.git
+Project-URL: Issues, https://github.com/dieablo101/protonic/issues
+Keywords: gui,ui,tkinter,declarative,xml,rapid-prototyping,desktop-app
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Protonic App Engine
+
+**Instant OS App Prototyping & Declarative XML UI Engine for Python.**
+
+Protonic eliminates GUI boilerplate. You design your layout using clean, semantic XML and interact with it in Python using simple selectors, properties, and decorators.
+
+---
+
+## Key Pillars
+
+1. **Zero Boilerplate:** No window setup rites, geometry manager wrestling, or manual frame hierarchies.
+2. **Predictable Layout Physics:** Common-sense defaults (`expand="true"` vs `expand="false"`) with intrinsic content footprint for every widget.
+3. **Ergonomic Python Selectors:** `app['#id'].val`, `app['#id'].text`, `app['#id'].show()`.
+4. **Thread-Safe Background Workers:** `@app.bg` executes tasks in worker threads without freezing the 60fps GUI.
+5. **Universal Sizing Heuristics:** Widgets never collapse to 0px or randomly explode across screens.
+
+---
+
+## Architecture Overview
+
+```text
+Protonic XML (<window>, <vbox>, <hbox>, <card>, <tabs>, ...)
+        │
+        ▼
+   Protonic Parser (AST Node Tree)
+        │
+        ▼
+   Layout Physics & Intrinsic Sizing Heuristics
+        │
+        ▼
+   GUI Backend (Tkinter/TTK Desktop Engine)
+        │
+        ▲
+   Python Bridge (App, ElementProxy, @app.click, @app.bg)
+```
+
+---
+
+## Sizing Physics & Defaults (`expand`)
+
+| Widget | Default `expand` | Intrinsic Footprint / Shrink Behavior |
+|---|---|---|
+| `<button>` | `false` | Shrink-wraps to text length + button padding |
+| `<label>` | `false` | Shrink-wraps to text string |
+| `<input>` | `false` | Default 20 character columns (`chars="20"`) or placeholder |
+| `<slider>`, `<switch>` | `false` | Natural ergonomic control dimensions |
+| `<select>` | `false` | Shrink-wraps to longest option text + arrow |
+| `<image>` | `false` | Native image file resolution (e.g. 128×128) |
+| `<card>` | `false` | Shrink-wraps to inner children + card padding |
+| `<vbox>`, `<hbox>` | `false` | Shrink-wraps to inner children flow |
+| `<tabs>` | `true` | Expands to fill available space |
+| `<scroll>` | `true` | Elastic viewport for scrolling content |
+| `<list>` | `true` | Default 6 rows × 25 chars or expands to container |
+| `<canvas>` | `true` | Default 300×200px or expands to fill |
+| `<textarea>` | `true` | Default 4 rows × 40 cols or expands to fill |
+| `<spacer />` | `true` | Elastic spring absorbing remaining space |
+| `<divider />`| `true` | Expands across parent cross-axis |
+
+---
+
+## Testing
+
+Run the test suite:
+```bash
+python3 -m unittest discover -s tests
+```

protonic-0.1.0/README.md

@@ -0,0 +1,66 @@
+# Protonic App Engine
+
+**Instant OS App Prototyping & Declarative XML UI Engine for Python.**
+
+Protonic eliminates GUI boilerplate. You design your layout using clean, semantic XML and interact with it in Python using simple selectors, properties, and decorators.
+
+---
+
+## Key Pillars
+
+1. **Zero Boilerplate:** No window setup rites, geometry manager wrestling, or manual frame hierarchies.
+2. **Predictable Layout Physics:** Common-sense defaults (`expand="true"` vs `expand="false"`) with intrinsic content footprint for every widget.
+3. **Ergonomic Python Selectors:** `app['#id'].val`, `app['#id'].text`, `app['#id'].show()`.
+4. **Thread-Safe Background Workers:** `@app.bg` executes tasks in worker threads without freezing the 60fps GUI.
+5. **Universal Sizing Heuristics:** Widgets never collapse to 0px or randomly explode across screens.
+
+---
+
+## Architecture Overview
+
+```text
+Protonic XML (<window>, <vbox>, <hbox>, <card>, <tabs>, ...)
+        │
+        ▼
+   Protonic Parser (AST Node Tree)
+        │
+        ▼
+   Layout Physics & Intrinsic Sizing Heuristics
+        │
+        ▼
+   GUI Backend (Tkinter/TTK Desktop Engine)
+        │
+        ▲
+   Python Bridge (App, ElementProxy, @app.click, @app.bg)
+```
+
+---
+
+## Sizing Physics & Defaults (`expand`)
+
+| Widget | Default `expand` | Intrinsic Footprint / Shrink Behavior |
+|---|---|---|
+| `<button>` | `false` | Shrink-wraps to text length + button padding |
+| `<label>` | `false` | Shrink-wraps to text string |
+| `<input>` | `false` | Default 20 character columns (`chars="20"`) or placeholder |
+| `<slider>`, `<switch>` | `false` | Natural ergonomic control dimensions |
+| `<select>` | `false` | Shrink-wraps to longest option text + arrow |
+| `<image>` | `false` | Native image file resolution (e.g. 128×128) |
+| `<card>` | `false` | Shrink-wraps to inner children + card padding |
+| `<vbox>`, `<hbox>` | `false` | Shrink-wraps to inner children flow |
+| `<tabs>` | `true` | Expands to fill available space |
+| `<scroll>` | `true` | Elastic viewport for scrolling content |
+| `<list>` | `true` | Default 6 rows × 25 chars or expands to container |
+| `<canvas>` | `true` | Default 300×200px or expands to fill |
+| `<textarea>` | `true` | Default 4 rows × 40 cols or expands to fill |
+| `<spacer />` | `true` | Elastic spring absorbing remaining space |
+| `<divider />`| `true` | Expands across parent cross-axis |
+
+---
+
+## Testing
+
+Run the test suite:
+```bash
+python3 -m unittest discover -s tests
+```

protonic-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "protonic"
+version = "0.1.0"
+description = "Instant OS App Prototyping & Declarative UI Engine"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Kyle Gallagher", email = "kidlucrid@gmail.com" }
+]
+keywords = ["gui", "ui", "tkinter", "declarative", "xml", "rapid-prototyping", "desktop-app"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: User Interfaces",
+    "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/dieablo101/protonic"
+Documentation = "https://dieablo101.github.io/protonic/"
+Repository = "https://github.com/dieablo101/protonic.git"
+Issues = "https://github.com/dieablo101/protonic/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

protonic-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

protonic-0.1.0/src/protonic/__init__.py

@@ -0,0 +1,10 @@
+"""
+Protonic: Instant OS App Prototyping & Declarative UI Engine.
+"""
+
+from .app import App, load, bg
+from .proxy import ElementProxy
+from .node import Node
+
+__version__ = "0.1.0"
+__all__ = ["App", "load", "bg", "ElementProxy", "Node", "__version__"]

protonic-0.1.0/src/protonic/app.py

@@ -0,0 +1,278 @@
+"""
+Proton Application Engine & Event Loop Bridge.
+"""
+
+import sys
+import threading
+import queue
+from pathlib import Path
+from typing import Dict, Any, Callable, Optional, Union
+
+from .node import Node
+from .parser import parse_xml
+from .proxy import ElementProxy
+from .backend_tk import TkBackend
+
+
+def bg(func: Callable) -> Callable:
+    """
+    Decorator that runs a handler function in a dedicated background worker thread,
+    keeping the GUI thread and 60fps rendering completely silky and unblocked.
+    """
+    def wrapper(*args, **kwargs):
+        thread = threading.Thread(target=func, args=args, kwargs=kwargs, daemon=True)
+        thread.start()
+        return thread
+    return wrapper
+
+
+class App:
+    """
+    Main Proton Application runtime.
+    """
+
+    def __init__(self, xml_source: Optional[Union[str, Path]] = None, xml: Optional[Union[str, Path]] = None):
+        source = xml if xml is not None else xml_source
+        self._xml_source = source
+        self.root_node: Optional[Node] = None
+        self._ready_handlers: list = []
+        self._click_handlers: Dict[str, Callable] = {}
+        self._change_handlers: Dict[str, Callable] = {}
+        self._shortcuts: Dict[str, Callable] = {}
+        self._event_queue: queue.Queue = queue.Queue()
+        self._backend: Optional[TkBackend] = None
+        self._proxies: Dict[str, ElementProxy] = {}
+
+        if source is not None:
+            self.load(source)
+
+    def load(self, xml_source: Union[str, Path]) -> "App":
+        """Loads and parses Proton XML source (string or file path)."""
+        self._xml_source = xml_source
+        self.root_node = parse_xml(xml_source)
+        return self
+
+    def register_handle(self, target_id: str, handle: Any) -> None:
+        """Registers a backend widget handle with an element proxy."""
+        if target_id in self._proxies:
+            self._proxies[target_id]._backend = handle
+        else:
+            self._proxies[target_id] = ElementProxy(target_id, self, backend_handle=handle)
+
+    def get_node(self, node_id: str) -> Optional[Node]:
+        """Looks up a Node in the AST by id."""
+        if self.root_node is None:
+            return None
+        return self.root_node.find_by_id(node_id)
+
+    def __getitem__(self, selector: str) -> ElementProxy:
+        """
+        Element selector accessor.
+        app['#id'] returns an ElementProxy for that widget.
+        """
+        target_id = selector.lstrip("#")
+        if target_id not in self._proxies:
+            handle = self._backend.get_handle(target_id) if self._backend else None
+            self._proxies[target_id] = ElementProxy(target_id, self, backend_handle=handle)
+        return self._proxies[target_id]
+
+    def __setitem__(self, selector: str, value: Any) -> None:
+        """
+        Syntactic sugar: app['#status'] = 'Active' sets .val or .text.
+        """
+        proxy = self[selector]
+        node = self.get_node(proxy.id)
+        if node and node.tag in ("input", "slider", "switch", "select", "list", "textarea", "progress", "table", "tableview", "treeview"):
+            proxy.val = value
+        else:
+            proxy.text = str(value)
+
+    # --- Decorators & Event Registrations ---
+
+    @staticmethod
+    def bg(func: Callable) -> Callable:
+        """Decorator for running tasks in a background thread."""
+        return bg(func)
+
+    def action(self, name: str) -> Callable:
+        """Decorator for action handlers mapped via do="action_name": @app.action('do_add')"""
+        clean_name = name.strip()
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[clean_name] = func
+            return func
+        return decorator
+
+    def click(self, selector: str) -> Callable:
+        """Decorator for button / widget click events: @app.click('#submit')"""
+        target_id = selector.lstrip("#")
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[target_id] = func
+            return func
+        return decorator
+
+    def double_click(self, selector: str) -> Callable:
+        """Decorator for double click events on tables/lists/trees: @app.double_click('#files_table')"""
+        target_id = selector.lstrip("#")
+        specific_key = f"{target_id}:double_click"
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[specific_key] = func
+            return func
+        return decorator
+
+    def submit(self, selector: str) -> Callable:
+        """Decorator for enter/submit events on inputs: @app.submit('#path_input')"""
+        target_id = selector.lstrip("#")
+        specific_key = f"{target_id}:submit"
+        def decorator(func: Callable) -> Callable:
+            self._click_handlers[specific_key] = func
+            return func
+        return decorator
+
+    def change(self, selector: str) -> Callable:
+        """Decorator for value change events (slider, switch, input): @app.change('#slider')"""
+        target_id = selector.lstrip("#")
+        def decorator(func: Callable) -> Callable:
+            self._change_handlers[target_id] = func
+            return func
+        return decorator
+
+    def shortcut(self, hotkey: str) -> Callable:
+        """
+        Decorator to bind a global keyboard accelerator / hotkey.
+        Example:
+            @app.shortcut('Ctrl+S')
+            @app.key('F5')
+            @app.key('Escape')
+        """
+        def decorator(func: Callable) -> Callable:
+            self.register_shortcut(hotkey, func)
+            return func
+        return decorator
+
+    key = shortcut  # Universal alias: @app.key('Ctrl+Q')
+
+    def register_shortcut(self, hotkey: str, handler: Callable) -> None:
+        """Registers a global keyboard shortcut with the runtime and active backend."""
+        clean = hotkey.strip()
+        self._shortcuts[clean] = handler
+        if self._backend and self._backend.root:
+            self._backend.bind_shortcut(clean, handler)
+
+    # --- Internal Event Triggers (called by Backend) ---
+
+    def trigger_click(self, node: Node) -> None:
+        """Dispatches click event to registered handler and/or node 'do' attribute."""
+        if node.id and node.id in self._click_handlers:
+            self._click_handlers[node.id]()
+        if node.do and node.do in self._click_handlers:
+            self._click_handlers[node.do]()
+
+    def trigger_action(self, node: Node, event_type: str, *args, **kwargs) -> None:
+        """Dispatches specialized events (e.g. double_click, submit)."""
+        specific_key = f"{node.id}:{event_type}" if node.id else None
+        if specific_key and specific_key in self._click_handlers:
+            try:
+                self._click_handlers[specific_key](*args, **kwargs)
+            except TypeError:
+                self._click_handlers[specific_key]()
+        elif node.id and node.id in self._click_handlers:
+            try:
+                self._click_handlers[node.id](*args, **kwargs)
+            except TypeError:
+                self._click_handlers[node.id]()
+        elif node.do and node.do in self._click_handlers:
+            try:
+                self._click_handlers[node.do](*args, **kwargs)
+            except TypeError:
+                self._click_handlers[node.do]()
+
+    def trigger_change(self, node: Node, val: Any) -> None:
+        """Dispatches change event to registered handler."""
+        if node.id and node.id in self._change_handlers:
+            self._change_handlers[node.id](val)
+
+    def ready(self, func: Callable) -> Callable:
+        """Decorator for lifecycle callbacks executed when UI is mapped and ready: @app.ready"""
+        self._ready_handlers.append(func)
+        return func
+
+    def trigger_ready(self) -> None:
+        """Dispatches ready events to registered startup handlers."""
+        for handler in self._ready_handlers:
+            try:
+                handler()
+            except Exception as e:
+                print(f"[Proton Ready Error] {e}", file=sys.stderr)
+
+    # --- Threading & Main Dispatch ---
+
+    def dispatch_to_main(self, action: Callable[[], None]) -> None:
+        """Queues an action to be safely executed on the main GUI thread."""
+        if self._backend:
+            if threading.current_thread() is threading.main_thread():
+                action()
+            else:
+                self._backend.post_action(action)
+        else:
+            action()
+
+    # --- Standard Dialogs ---
+
+    def alert(self, title: str, message: str) -> None:
+        """Shows an alert modal dialog."""
+        if self._backend:
+            self._backend.show_alert(title, message)
+        else:
+            print(f"[ALERT: {title}] {message}")
+
+    def confirm(self, title: str, message: str) -> bool:
+        """Shows a confirmation modal dialog (Yes/No). Returns True if confirmed."""
+        if self._backend:
+            return self._backend.show_confirm(title, message)
+        return True
+
+    def open_file(self, title: str = "Open File", filetypes: Optional[list] = None) -> Optional[str]:
+        """Shows native open file dialog. Returns selected file path or None."""
+        if self._backend:
+            return self._backend.show_open_file(title, filetypes)
+        return None
+
+    def save_file(self, title: str = "Save File", default_extension: str = "", filetypes: Optional[list] = None) -> Optional[str]:
+        """Shows native save file dialog. Returns selected file path or None."""
+        if self._backend:
+            return self._backend.show_save_file(title, default_extension, filetypes)
+        return None
+
+    def choose_dir(self, title: str = "Select Directory") -> Optional[str]:
+        """Shows native directory picker dialog. Returns selected folder path or None."""
+        if self._backend:
+            return self._backend.show_choose_dir(title)
+        return None
+
+    def after(self, ms: int, func: Callable) -> Optional[str]:
+        """Schedules a function to run after ms milliseconds on the main thread."""
+        if self._backend and hasattr(self._backend, "root") and self._backend.root:
+            return self._backend.root.after(ms, func)
+        return None
+
+    def cancel_after(self, after_id: Optional[str]) -> None:
+        """Cancels a scheduled after timer."""
+        if after_id and self._backend and hasattr(self._backend, "root") and self._backend.root:
+            try:
+                self._backend.root.after_cancel(after_id)
+            except Exception:
+                pass
+
+    # --- Run Loop ---
+
+    def run(self) -> None:
+        """Starts the native Proton window and enters the GUI event loop."""
+        if self.root_node is None:
+            raise RuntimeError("Cannot run Proton App: No XML UI loaded.")
+        self._backend = TkBackend(self)
+        self._backend.render_and_run(self.root_node)
+
+
+def load(xml_source: Union[str, Path]) -> App:
+    """Convenience helper to load an XML layout and return an App instance."""
+    return App(xml_source)