pyclay 1.0.0__py3-none-any.whl

pyclay/__init__.py

@@ -0,0 +1,335 @@
+"""
+pyclay – public API
+====================
+Every function appends a component dict to the runtime tree.
+An optional ``style`` dict lets callers control CSS per-element.
+"""
+
+__version__ = "1.0.0"
+
+from contextlib import contextmanager
+from pyclay import _runtime
+
+
+# Page config
+
+_VALID_THEMES = {"ivory", "nebula", "arctic", "obsidian"}
+
+def page_config(*, title="My App", theme="ivory", favicon="", custom_css=""):
+    """Set page-level settings.  Call once, at the top of your script.
+
+    Args:
+        title:      Browser tab title.
+        theme:      ``"ivory"``, ``"nebula"``, ``"arctic"``, or ``"obsidian"``.
+        favicon:    URL to a favicon image (optional).
+        custom_css: Path or URL to a custom CSS file (optional).
+    """
+    assert theme in _VALID_THEMES, f"theme must be one of {_VALID_THEMES}"
+    _runtime.set_page_config(title=title, theme=theme, favicon=favicon, custom_css=custom_css)
+
+
+def page(name):
+    """Switch context to build a new page. Subsequent elements belong to this page.
+
+    Args:
+        name: Unique page identifier/label (e.g. "Docs" or "Components").
+    """
+    _runtime.set_current_page(name)
+
+
+# Text
+
+def heading(text, level=1, *, style=None):
+    assert 1 <= level <= 6, "Heading level must be 1-6"
+    _runtime.add({"type": "heading", "text": text, "level": level, "style": style})
+
+
+def text(content, *, style=None):
+    _runtime.add({"type": "paragraph", "text": content, "style": style})
+
+
+def bold(content, *, style=None):
+    _runtime.add({"type": "bold", "text": content, "style": style})
+
+
+def italic(content, *, style=None):
+    _runtime.add({"type": "italic", "text": content, "style": style})
+
+
+def blockquote(content, *, style=None):
+    _runtime.add({"type": "blockquote", "text": content, "style": style})
+
+
+def kbd(text_content):
+    """Render a keyboard-key style element."""
+    _runtime.add({"type": "kbd", "text": text_content})
+
+
+# Lists
+
+def bullet_list(items, *, style=None):
+    assert isinstance(items, list), "bullet_list expects a list"
+    _runtime.add({"type": "bullet_list", "items": items, "style": style})
+
+
+def ordered_list(items, *, style=None):
+    assert isinstance(items, list), "ordered_list expects a list"
+    _runtime.add({"type": "ordered_list", "items": items, "style": style})
+
+
+# Media / embeds
+
+def image(src, *, alt="", width=None, height=None, style=None):
+    _runtime.add({"type": "image", "src": src, "alt": alt, "width": width, "height": height, "style": style})
+
+
+def video(src, *, autoplay=False, loop=False, controls=True, width=None, height=None, style=None):
+    """Render a video element.
+
+    Args:
+        src:      URL or path to the video (e.g. "assets/video.mp4").
+        autoplay: If True, play automatically (will be muted for browser compliance).
+        loop:     If True, play in a loop.
+        controls: If True, display playback controls.
+        width:    Optional width of the video.
+        height:   Optional height of the video.
+        style:    Optional style overrides dictionary.
+    """
+    _runtime.add({
+        "type": "video",
+        "src": src,
+        "autoplay": autoplay,
+        "loop": loop,
+        "controls": controls,
+        "width": width,
+        "height": height,
+        "style": style
+    })
+
+
+
+def link(text, href, *, style=None):
+    _runtime.add({"type": "link", "text": text, "href": href, "style": style})
+
+
+def code_block(code, *, language="", style=None):
+    _runtime.add({"type": "code_block", "code": code, "language": language, "style": style})
+
+
+def html_raw(markup):
+    """Inject arbitrary HTML.  Use with care."""
+    _runtime.add({"type": "raw", "html": markup})
+
+
+# Decorative
+
+def divider(*, style=None):
+    _runtime.add({"type": "divider", "style": style})
+
+
+def spacer(height="1rem"):
+    _runtime.add({"type": "spacer", "height": height})
+
+
+# Data display
+
+def table(headers, rows, *, style=None):
+    """Render an HTML table.
+
+    Args:
+        headers: List of column header strings.
+        rows:    List of rows, each row a list of cell values.
+    """
+    _runtime.add({"type": "table", "headers": headers, "rows": rows, "style": style})
+
+
+def metric(label, value, *, delta=None, delta_color=None, style=None):
+    """Streamlit-style metric card.
+
+    Args:
+        label:       Metric title.
+        value:       Primary value to display.
+        delta:       Optional delta string (e.g. "+12%").
+        delta_color: ``"green"`` (default for positive) or ``"red"``.
+    """
+    _runtime.add({
+        "type": "metric",
+        "label": label,
+        "value": value,
+        "delta": delta,
+        "delta_color": delta_color,
+        "style": style,
+    })
+
+
+def progress_bar(value, *, max_value=100, label="", style=None):
+    _runtime.add({
+        "type": "progress_bar",
+        "value": value,
+        "max": max_value,
+        "label": label,
+        "style": style,
+    })
+
+
+# UI elements
+
+def badge(text, *, color="#6366f1", style=None):
+    _runtime.add({"type": "badge", "text": text, "color": color, "style": style})
+
+
+def alert(text, *, variant="info", style=None):
+    """Alert box.  ``variant`` is one of: info, success, warning, error."""
+    _runtime.add({"type": "alert", "text": text, "variant": variant, "style": style})
+
+
+def button(label, *, style=None):
+    """Visual-only styled button (no click handler)."""
+    _runtime.add({"type": "button", "label": label, "style": style})
+
+
+def link_button(label, href, *, style=None):
+    """An anchor element styled as a button.  Navigates to *href* on click."""
+    _runtime.add({"type": "link_button", "label": label, "href": href, "style": style})
+
+
+def card(title="", body="", *, style=None):
+    """A bordered card container.  Accepts plain text title/body."""
+    _runtime.add({"type": "card", "title": title, "body": body, "style": style})
+
+
+# Collapsible / Tabs
+
+def accordion(items, *, style=None):
+    """Collapsible accordion using ``<details>/<summary>``.
+
+    Args:
+        items: List of ``{"title": "...", "content": "..."}`` dicts.
+    """
+    assert isinstance(items, list), "accordion expects a list of items"
+    _runtime.add({"type": "accordion", "items": items, "style": style})
+
+
+def tabs(labels, *, style=None):
+    """Begin a tabbed section.  Follow with ``tab_panel()`` context managers.
+
+    Args:
+        labels: List of tab label strings, one per panel.
+    """
+    assert isinstance(labels, list) and len(labels) >= 1, "tabs expects a list of labels"
+    comp = {"type": "tabs", "labels": labels, "panels": [], "style": style}
+    _runtime.add(comp)
+    _runtime._tabs_stack.append(comp)
+
+
+@contextmanager
+def tab_panel(*, style=None):
+    """Context manager for a single tab panel inside a ``tabs()`` block."""
+    assert _runtime._tabs_stack, "tab_panel() must be used after a tabs() call"
+    panel = {"type": "container", "children": [], "style": style}
+    _runtime._tabs_stack[-1]["panels"].append(panel)
+    _runtime._container_stack.append(panel["children"])
+    try:
+        yield
+    finally:
+        _runtime._container_stack.pop()
+        # Pop tabs_stack when all panels are defined
+        if len(_runtime._tabs_stack[-1]["panels"]) >= len(_runtime._tabs_stack[-1]["labels"]):
+            _runtime._tabs_stack.pop()
+
+
+# Navbar & Footer
+
+_VALID_NAV_VARIANTS = {"simple", "centered"}
+_VALID_FOOTER_VARIANTS = {"simple", "columns"}
+
+def navbar(title="", links=None, *, variant="simple", style=None):
+    """Add a navigation bar to the top of the page.
+
+    Args:
+        title:   Brand / logo text.
+        links:   List of ``{"text": "...", "href": "..."}`` dicts.
+        variant: ``"simple"`` (logo left, links right) or
+                 ``"centered"`` (logo centred, links below).
+    """
+    assert variant in _VALID_NAV_VARIANTS, f"navbar variant must be one of {_VALID_NAV_VARIANTS}"
+    _runtime.add({
+        "type": "navbar",
+        "title": title,
+        "links": links or [],
+        "variant": variant,
+        "style": style,
+    })
+
+
+def footer(text="", links=None, *, variant="simple", columns_data=None, style=None):
+    """Add a footer to the bottom of the page.
+
+    Args:
+        text:         Main footer text (copyright line, etc.).
+        links:        List of ``{"text": "...", "href": "..."}`` dicts.
+        variant:      ``"simple"`` (single line) or ``"columns"`` (multi-column).
+        columns_data: For ``"columns"`` variant only -- list of
+                      ``{"heading": "...", "links": [{"text": ..., "href": ...}, ...]}`` dicts.
+    """
+    assert variant in _VALID_FOOTER_VARIANTS, f"footer variant must be one of {_VALID_FOOTER_VARIANTS}"
+    _runtime.add({
+        "type": "footer",
+        "text": text,
+        "links": links or [],
+        "variant": variant,
+        "columns_data": columns_data or [],
+        "style": style,
+    })
+
+
+# Layout: container & columns
+
+@contextmanager
+def container(*, style=None):
+    """Context manager -- wraps children in a styled ``<div>``."""
+    comp = {"type": "container", "children": [], "style": style}
+    _runtime.push_container(comp)
+    try:
+        yield
+    finally:
+        _runtime.pop_container()
+
+
+@contextmanager
+def columns(ratios=None, *, gap="1rem", style=None):
+    """Context manager -- CSS-grid columns.
+
+    ``ratios`` is a list of relative widths, e.g. ``[1, 2]`` -> ``1fr 2fr``.
+    Use nested ``column()`` calls inside.
+    """
+    if ratios is None:
+        ratios = [1, 1]
+    template = " ".join(f"{r}fr" for r in ratios)
+    merged = style or {}
+    merged = {
+        "display": "grid",
+        "grid_template_columns": template,
+        "gap": gap,
+        **merged,
+    }
+    comp = {"type": "container", "children": [], "style": merged}
+    _runtime.push_container(comp)
+    try:
+        yield
+    finally:
+        _runtime.pop_container()
+
+
+@contextmanager
+def column(*, style=None):
+    """A single column inside a ``columns()`` block."""
+    merged = style or {}
+    merged = {"min_width": "0", **merged}
+    comp = {"type": "container", "children": [], "style": merged}
+    _runtime.push_container(comp)
+    try:
+        yield
+    finally:
+        _runtime.pop_container()
+

pyclay/_cli.py

@@ -0,0 +1,153 @@
+import sys
+import os
+import time
+import traceback
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+from pyclay import _runtime, _renderer, _server
+
+def run_script(script_path):
+    _runtime.reset()
+    try:
+        with open(script_path, encoding="utf-8") as f:
+            code = f.read()
+        exec(code, {"__name__": "__main__"})
+        html = _renderer.render_page()
+        return html
+    except Exception:
+        # Format a friendly error page instead of crashing
+        tb = traceback.format_exc()
+        print(f"\n{'='*60}")
+        print(f"  ERROR in {script_path}")
+        print(f"{'='*60}")
+        print(tb)
+        print(f"{'='*60}\n")
+        error_html = f"""<!DOCTYPE html>
+<html><head><meta charset="UTF-8"><title>pyclay – Error</title>
+<style>
+  body {{ font-family: 'Inter', -apple-system, sans-serif; background: #0f0f17; color: #e4e4f0; margin: 0; padding: 2rem; }}
+  .error-box {{ background: #1a1a2e; border: 1px solid #ef4444; border-radius: 10px; padding: 2rem; max-width: 800px; margin: 2rem auto; }}
+  h1 {{ color: #ef4444; margin-top: 0; font-size: 1.4rem; }}
+  pre {{ background: #111; padding: 1.2rem; border-radius: 8px; overflow-x: auto; font-size: 0.85rem; line-height: 1.6; color: #fca5a5; }}
+  p {{ color: #888; font-size: 0.9rem; }}
+</style></head>
+<body>
+  <div class="error-box">
+    <h1>\u26a0 Build Error</h1>
+    <pre>{_renderer._esc(tb)}</pre>
+    <p>Fix the error and save your file - the page will auto-reload.</p>
+  </div>
+</body></html>"""
+        return error_html
+
+class _ReloadHandler(FileSystemEventHandler):
+    def __init__(self, script_path):
+        self.script_path = script_path
+
+    def on_modified(self, event):
+        if event.src_path.endswith(self.script_path.lstrip("./")):
+            print(f"Change detected - reloading {self.script_path}")
+            html = run_script(self.script_path)
+            _server.update_html(html)  # push new HTML, bump timestamp
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: pyclay <command> [args]")
+        print("")
+        print("Commands:")
+        print("  run <script.py>              Start dev server with hot reload")
+        print("  build <script.py> [--out DIR] Export static HTML")
+        sys.exit(1)
+
+    command = sys.argv[1]
+
+    if command == "build":
+        if len(sys.argv) < 3:
+            print("Usage: pyclay build <script.py> [--out DIR]")
+            sys.exit(1)
+
+        script_path = sys.argv[2]
+
+        # Parse --out flag
+        out_dir = "dist"
+        if "--out" in sys.argv:
+            idx = sys.argv.index("--out")
+            if idx + 1 < len(sys.argv):
+                out_dir = sys.argv[idx + 1]
+
+        _runtime.reset()
+        try:
+            with open(script_path, encoding="utf-8") as f:
+                code = f.read()
+            exec(code, {"__name__": "__main__"})
+            html = _renderer.render_page()
+        except Exception:
+            print(f"\nBuild failed for {script_path}:")
+            traceback.print_exc()
+            sys.exit(1)
+
+        # Strip hot-reload JS from production build
+        import re
+        html = re.sub(r'<script>\s*let _pc_last.*?</script>', '', html, flags=re.DOTALL)
+
+        os.makedirs(out_dir, exist_ok=True)
+        out_path = os.path.join(out_dir, "index.html")
+        with open(out_path, "w", encoding="utf-8") as f:
+            f.write(html)
+
+        # Copy assets/ directory to output directory if it exists
+        if os.path.exists("assets"):
+            import shutil
+            out_assets_dir = os.path.join(out_dir, "assets")
+            try:
+                if os.path.exists(out_assets_dir):
+                    shutil.rmtree(out_assets_dir)
+                shutil.copytree("assets", out_assets_dir)
+                print(f"  Assets: copied assets/ -> {out_assets_dir}")
+            except Exception as e:
+                print(f"  Warning: failed to copy assets folder: {e}")
+
+        abs_path = os.path.abspath(out_path)
+        print(f"Built successfully -> {abs_path}")
+        print(f"  Size: {len(html):,} bytes")
+
+    elif command == "run":
+        if len(sys.argv) < 3:
+            print("Usage: pyclay run <script.py> [--port PORT]")
+            sys.exit(1)
+
+        script_path = sys.argv[2]
+
+        # Parse --port flag
+        port = 8501
+        if "--port" in sys.argv:
+            idx = sys.argv.index("--port")
+            if idx + 1 < len(sys.argv):
+                port = int(sys.argv[idx + 1])
+
+        # first render
+        html = run_script(script_path)
+        server = _server.serve(html, port=port)
+
+        # watch for file changes
+        handler = _ReloadHandler(script_path)
+        observer = Observer()
+        observer.schedule(handler, path=".", recursive=True)
+        observer.start()
+
+        print("Watching for changes... (Ctrl+C to stop)")
+
+        try:
+            while True:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            print("\nStopped.")
+            observer.stop()
+            server.shutdown()
+
+        observer.join()
+
+    else:
+        print(f"Unknown command: {command}")
+        print("Available commands: run, build")
+        sys.exit(1)