pyjs-examples 0.0.1__tar.gz

pyjs_examples-0.0.1/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: pyjs-examples
+Version: 0.0.1
+Summary: Official example applications for PyJS.
+Author-email: Lex Berezhny <lex@damoti.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://pyjs.org
+Project-URL: Source, https://github.com/pyjs/pyjs
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: pyjs==0.0.1
+Provides-Extra: test
+Requires-Dist: pytest>=9.0; extra == "test"
+
+# PyJS Examples
+
+This directory is the source tree for the separately installable `pyjs-examples` distribution.
+Setuptools maps this directory to the `pyjs_examples` import package, so the examples remain easy to
+browse in the repository while installing as an ordinary top-level package.
+
+From the repository root, install the core and examples from a source checkout:
+
+```bash
+python -m pip install -e . -e ./examples
+```
+
+An installed PyJS release provides the same package through the `examples` extra:
+
+```bash
+python -m pip install "pyjs[examples]"
+```
+
+Run any complete application as a module:
+
+| Example | Command |
+| --- | --- |
+| [Calculator](calculator/) | `python -m pyjs_examples.calculator` |
+| [Chatroom](chatroom/) | `python -m pyjs_examples.chatroom` |
+| [Kanban board](kanban/) | `python -m pyjs_examples.kanban` |
+| [NativeScript Counter](nativescript_counter/) | `python -m pyjs_examples.nativescript_counter` |
+| [Space Invaders](space_invaders/) | `python -m pyjs_examples.space_invaders` |
+| [TodoMVC](todomvc/) | `python -m pyjs_examples.todomvc` |
+| [Component workspace](workspace/) | `python -m pyjs_examples.workspace` |
+| [Component catalog](catalog.py) | `python -m pyjs_examples.catalog` |
+
+List or copy examples using the core scaffolding command:
+
+```bash
+pyjs template
+pyjs template pyjs_examples.calculator
+pyjs create my-calculator --template pyjs_examples.calculator
+pyjs create --single-file my_counter.py --template pyjs_examples.counter
+```
+
+The distribution registers modules and packages through the `pyjs.templates` entry-point group.
+PyJS infers file and directory templates from normal Python module structure instead of hardcoding
+a catalog.
+
+The [focused samples](samples/) are small, executable sources intended for documentation excerpts
+and `pyjs create PROJECT --template NAME`. The initial catalog includes
+`pyjs_examples.samples.state_counter` and `pyjs_examples.samples.ui_dialog`.

pyjs_examples-0.0.1/README.md

@@ -0,0 +1,47 @@
+# PyJS Examples
+
+This directory is the source tree for the separately installable `pyjs-examples` distribution.
+Setuptools maps this directory to the `pyjs_examples` import package, so the examples remain easy to
+browse in the repository while installing as an ordinary top-level package.
+
+From the repository root, install the core and examples from a source checkout:
+
+```bash
+python -m pip install -e . -e ./examples
+```
+
+An installed PyJS release provides the same package through the `examples` extra:
+
+```bash
+python -m pip install "pyjs[examples]"
+```
+
+Run any complete application as a module:
+
+| Example | Command |
+| --- | --- |
+| [Calculator](calculator/) | `python -m pyjs_examples.calculator` |
+| [Chatroom](chatroom/) | `python -m pyjs_examples.chatroom` |
+| [Kanban board](kanban/) | `python -m pyjs_examples.kanban` |
+| [NativeScript Counter](nativescript_counter/) | `python -m pyjs_examples.nativescript_counter` |
+| [Space Invaders](space_invaders/) | `python -m pyjs_examples.space_invaders` |
+| [TodoMVC](todomvc/) | `python -m pyjs_examples.todomvc` |
+| [Component workspace](workspace/) | `python -m pyjs_examples.workspace` |
+| [Component catalog](catalog.py) | `python -m pyjs_examples.catalog` |
+
+List or copy examples using the core scaffolding command:
+
+```bash
+pyjs template
+pyjs template pyjs_examples.calculator
+pyjs create my-calculator --template pyjs_examples.calculator
+pyjs create --single-file my_counter.py --template pyjs_examples.counter
+```
+
+The distribution registers modules and packages through the `pyjs.templates` entry-point group.
+PyJS infers file and directory templates from normal Python module structure instead of hardcoding
+a catalog.
+
+The [focused samples](samples/) are small, executable sources intended for documentation excerpts
+and `pyjs create PROJECT --template NAME`. The initial catalog includes
+`pyjs_examples.samples.state_counter` and `pyjs_examples.samples.ui_dialog`.

pyjs_examples-0.0.1/__init__.py

@@ -0,0 +1 @@
+"""Official example applications and focused samples for PyJS."""

pyjs_examples-0.0.1/calculator/README.md

@@ -0,0 +1,55 @@
+# Calculator Example
+
+This project is a small but complete calculator application and the primary
+example for pyjs browser-target testing.
+
+It demonstrates:
+
+- calculator state and behavior owned by a custom element
+- typed `state()` fields serialized to DOM attributes and rendered with `@effect`
+- a centered responsive custom-element UI
+- digit and decimal entry
+- addition, subtraction, multiplication, and division
+- sign, percent, clear, and divide-by-zero behavior
+- asynchronous result persistence through an HTTP POST route
+- per-browser in-memory sessions that restore the last result after refresh
+- browser tests that interact with the real DOM through button events
+
+The example intentionally stays focused on calculator behavior. Reusable widget
+coverage, including the dropdown menu and floating positioning, lives under
+`tests/web/ui/`.
+
+## Run the calculator
+
+From the repository root:
+
+```bash
+.venv/bin/python -m pyjs_examples.calculator
+```
+
+Open `http://127.0.0.1:8000/`. Completing a calculation with `=` saves its
+result to the server. Refreshing the page restores that result through the
+browser's session cookie. Sessions are intentionally in memory, so restarting
+the server clears them.
+
+## Run the tests
+
+From the repository root, run the Python target:
+
+```bash
+.venv/bin/python -m pytest -q examples/calculator/tests
+```
+
+Run the same model tests plus the browser-only UI tests in the browser:
+
+```bash
+.venv/bin/python -m pytest -q examples/calculator/tests --pyjs-target=web
+```
+
+The pytest plugin starts or reconnects to the browser-test daemon on
+`127.0.0.1:8765`. To keep the daemon alive while iterating:
+
+```bash
+.venv/bin/python -m pytest -q examples/calculator/tests --pyjs-target=web \
+  --pyjs-daemon-idle-seconds=0
+```

pyjs_examples-0.0.1/calculator/__init__.py

@@ -0,0 +1 @@
+"""A tested calculator with reactive DOM state and HTTP session persistence."""

pyjs_examples-0.0.1/calculator/__main__.py

@@ -0,0 +1,9 @@
+from pyjs.server import serve
+
+from .calculator import render, save_result
+
+serve(
+    "pyjs_examples.calculator.calculator",
+    render=render,
+    routes={("POST", "/api/calculator/result"): save_result},
+)

pyjs_examples-0.0.1/calculator/calculator.py

@@ -0,0 +1,325 @@
+from pyjs import effect, js, nojs, state
+from pyjs.web.domx import ProxyElement, button, ref, tag, tw
+from pyjs.web.events import Event
+from pyjs.web.network import fetch
+from pyjs.web.ui import Widget
+
+
+@js
+class CalculatorKeyListener:
+    def __init__(self, app: CalculatorApp, kind: str, value: str):
+        self.app = app
+        self.kind = kind
+        self.value = value
+
+    @js(include=True)
+    async def handleEvent(self, event: Event):
+        self.app.press(self.kind, self.value)
+        if self.kind == "equals" and not self.app.error:
+            await self.app.persist_result()
+
+
+@js
+class CalculatorKey(ProxyElement):
+    def __init__(self, label: str, value: str, kind: str, wide: bool):
+        attributes = {
+            "aria-label": label,
+            "data-key": value,
+            "type": "button",
+        }
+        if wide:
+            self.element = button(
+                tw(
+                    "col-span-2 h-12 rounded-xl bg-slate-100 px-5 text-left text-xl "
+                    "font-medium text-slate-950 shadow-sm hover:bg-slate-200 "
+                    "focus:outline-none focus:ring-2 focus:ring-slate-400"
+                ),
+                attributes,
+                label,
+            )
+        elif kind == "operator" or kind == "equals":
+            self.element = button(
+                tw(
+                    "h-12 rounded-xl bg-amber-500 text-xl font-semibold text-white shadow-sm "
+                    "hover:bg-amber-600 focus:outline-none focus:ring-2 focus:ring-amber-400"
+                ),
+                attributes,
+                label,
+            )
+        elif kind == "action":
+            self.element = button(
+                tw(
+                    "h-12 rounded-xl bg-slate-200 text-lg font-medium text-slate-800 shadow-sm "
+                    "hover:bg-slate-300 focus:outline-none focus:ring-2 focus:ring-slate-400"
+                ),
+                attributes,
+                label,
+            )
+        else:
+            self.element = button(
+                tw(
+                    "h-12 rounded-xl bg-slate-100 text-xl font-medium text-slate-950 shadow-sm "
+                    "hover:bg-slate-200 focus:outline-none focus:ring-2 focus:ring-slate-400"
+                ),
+                attributes,
+                label,
+            )
+
+    def bind(self, app: CalculatorApp, kind: str, value: str):
+        self.listener = CalculatorKeyListener(app, kind, value)
+        self.element.addEventListener("click", self.listener)
+
+
+@js
+class CalculatorApp(Widget):
+    display_value = state("0")
+    stored_value = state(0.0)
+    pending_operator = state("")
+    replace_display = state(True)
+    error = state(False)
+    save_url = state("")
+
+    def __init__(self, initial_value: str = "0", save_url: str = ""):
+        super().__init__()
+        self.display = ref(
+            tag(
+                "div",
+                tw(
+                    "min-h-20 overflow-hidden rounded-xl bg-slate-950 px-5 py-4 text-right "
+                    "font-mono text-3xl font-semibold tracking-tight text-white"
+                ),
+                {
+                    "aria-live": "polite",
+                    "data-testid": "calculator-display",
+                    "role": "status",
+                },
+                initial_value,
+            )
+        )
+        self.display_value = initial_value
+        self.save_url = save_url
+
+        self.clear_button = ref(CalculatorKey("AC", "clear", "action", False))
+        self.clear_button.bind(self, "action", "clear")
+        self.sign_button = ref(CalculatorKey("±", "sign", "action", False))
+        self.sign_button.bind(self, "action", "sign")
+        self.percent_button = ref(CalculatorKey("%", "percent", "action", False))
+        self.percent_button.bind(self, "action", "percent")
+        self.divide_button = ref(CalculatorKey("÷", "/", "operator", False))
+        self.divide_button.bind(self, "operator", "/")
+        self.seven_button = ref(CalculatorKey("7", "7", "digit", False))
+        self.seven_button.bind(self, "digit", "7")
+        self.eight_button = ref(CalculatorKey("8", "8", "digit", False))
+        self.eight_button.bind(self, "digit", "8")
+        self.nine_button = ref(CalculatorKey("9", "9", "digit", False))
+        self.nine_button.bind(self, "digit", "9")
+        self.multiply_button = ref(CalculatorKey("×", "*", "operator", False))
+        self.multiply_button.bind(self, "operator", "*")
+        self.four_button = ref(CalculatorKey("4", "4", "digit", False))
+        self.four_button.bind(self, "digit", "4")
+        self.five_button = ref(CalculatorKey("5", "5", "digit", False))
+        self.five_button.bind(self, "digit", "5")
+        self.six_button = ref(CalculatorKey("6", "6", "digit", False))
+        self.six_button.bind(self, "digit", "6")
+        self.subtract_button = ref(CalculatorKey("−", "-", "operator", False))
+        self.subtract_button.bind(self, "operator", "-")
+        self.one_button = ref(CalculatorKey("1", "1", "digit", False))
+        self.one_button.bind(self, "digit", "1")
+        self.two_button = ref(CalculatorKey("2", "2", "digit", False))
+        self.two_button.bind(self, "digit", "2")
+        self.three_button = ref(CalculatorKey("3", "3", "digit", False))
+        self.three_button.bind(self, "digit", "3")
+        self.add_button = ref(CalculatorKey("+", "+", "operator", False))
+        self.add_button.bind(self, "operator", "+")
+        self.zero_button = ref(CalculatorKey("0", "0", "digit", True))
+        self.zero_button.bind(self, "digit", "0")
+        self.decimal_button = ref(CalculatorKey(".", ".", "decimal", False))
+        self.decimal_button.bind(self, "decimal", ".")
+        self.equals_button = ref(CalculatorKey("=", "=", "equals", False))
+        self.equals_button.bind(self, "equals", "=")
+        keys: list[CalculatorKey] = [
+            self.clear_button,
+            self.sign_button,
+            self.percent_button,
+            self.divide_button,
+            self.seven_button,
+            self.eight_button,
+            self.nine_button,
+            self.multiply_button,
+            self.four_button,
+            self.five_button,
+            self.six_button,
+            self.subtract_button,
+            self.one_button,
+            self.two_button,
+            self.three_button,
+            self.add_button,
+            self.zero_button,
+            self.decimal_button,
+            self.equals_button,
+        ]
+        card = tag(
+            "main",
+            tw("w-full max-w-sm rounded-3xl border border-slate-200 bg-white p-4 shadow-xl"),
+            {"data-testid": "calculator-card"},
+            tag(
+                "header",
+                tw("mb-4 flex items-end justify-between px-1"),
+                tag("h1", tw("text-lg font-semibold text-slate-950"), "Calculator"),
+                tag(
+                    "span",
+                    tw("text-xs font-medium uppercase tracking-widest text-slate-400"),
+                    "PyJS",
+                ),
+            ),
+            self.display,
+            tag("div", tw("mt-4 grid grid-cols-4 gap-2"), *keys),
+        )
+        self.add(
+            tw("box-border flex min-h-screen items-center justify-center bg-slate-100 p-4"),
+            card,
+        )
+
+    @effect(display_value)
+    def render_display(self):
+        self.display.textContent = self.display_value
+
+    def clear(self):
+        self.display_value = "0"
+        self.stored_value = 0.0
+        self.pending_operator = ""
+        self.replace_display = True
+        self.error = False
+
+    def value(self) -> float:
+        if self.error:
+            return 0.0
+        return float(self.display_value)
+
+    def input_digit(self, digit: str):
+        if self.error:
+            self.clear()
+        if self.replace_display or self.display_value == "0":
+            self.display_value = digit
+            self.replace_display = False
+        else:
+            self.display_value += digit
+
+    def input_decimal(self):
+        if self.error:
+            self.clear()
+        if self.replace_display:
+            self.display_value = "0."
+            self.replace_display = False
+        elif len(self.display_value.split(".")) == 1:
+            self.display_value += "."
+
+    def toggle_sign(self):
+        value = self.display_value
+        if self.error or value == "0" or value == "0.0":
+            return
+        self.display_value = str(0.0 - float(value))
+
+    def percent(self):
+        if self.error:
+            return
+        self.display_value = str(float(self.display_value) / 100.0)
+        self.replace_display = True
+
+    def choose_operator(self, operator: str):
+        if self.error:
+            return
+        if self.pending_operator != "" and not self.replace_display:
+            self.calculate()
+            if self.error:
+                return
+        self.stored_value = float(self.display_value)
+        self.pending_operator = operator
+        self.replace_display = True
+
+    def calculate_result(self, left: float, right: float, operator: str) -> float:
+        if operator == "+":
+            return left + right
+        if operator == "-":
+            return left - right
+        if operator == "*":
+            return left * right
+        return left / right
+
+    def calculate(self) -> float:
+        operator = self.pending_operator
+        if self.error or operator == "":
+            return self.value()
+        right = float(self.display_value)
+        if operator == "/" and right == 0.0:
+            self.display_value = "Error"
+            self.pending_operator = ""
+            self.replace_display = True
+            self.error = True
+            return 0.0
+        result = self.calculate_result(self.stored_value, right, operator)
+        self.display_value = str(result)
+        self.stored_value = result
+        self.pending_operator = ""
+        self.replace_display = True
+        return result
+
+    async def persist_result(self):
+        if self.save_url == "":
+            return
+        await fetch(
+            self.save_url,
+            {
+                "method": "POST",
+                "headers": {"Content-Type": "text/plain"},
+                "body": self.display_value,
+                "keepalive": True,
+            },
+        )
+
+    def press(self, kind: str, value: str):
+        if kind == "digit":
+            self.input_digit(value)
+        elif kind == "decimal":
+            self.input_decimal()
+        elif kind == "operator":
+            self.choose_operator(value)
+        elif kind == "equals":
+            self.calculate()
+        elif value == "clear":
+            self.clear()
+        elif value == "sign":
+            self.toggle_sign()
+        else:
+            self.percent()
+
+
+def main(initial_value: str = "0", save_url: str = ""):
+    return CalculatorApp(initial_value=initial_value, save_url=save_url)
+
+
+@nojs
+def render(request):
+    return main(request.session.get("last_result", "0"), "/api/calculator/result")
+
+
+@nojs
+def save_result(request):
+    import math
+
+    result = request.body.decode("utf-8")
+    if len(result) > 32:
+        raise ValueError("result must be a short numeric string")
+    if not math.isfinite(float(result)):
+        raise ValueError("result must be finite")
+    request.session["last_result"] = result
+
+
+if __name__ == "__main__":
+    from pyjs.server import serve
+
+    serve(
+        "calculator",
+        render=render,
+        routes={("POST", "/api/calculator/result"): save_result},
+    )

pyjs_examples-0.0.1/calculator/tests/test_browser_calculator.py

@@ -0,0 +1,67 @@
+import pytest
+from pyjs import js
+from pyjs.testing.web import mount
+from pyjs.web.events import Event
+from pyjs.web.html import HTMLButtonElement
+from pyjs_examples.calculator.calculator import CalculatorApp
+
+pytestmark = pytest.mark.pyjs_web
+
+
+@js
+def click(button: HTMLButtonElement):
+    button.dispatchEvent(Event("click"))
+
+
+@js
+def mounted_calculator() -> CalculatorApp:
+    app = CalculatorApp()
+    mount(app)
+    return app
+
+
+@js
+def test_calculator_renders_a_complete_keypad():
+    app = mounted_calculator()
+
+    assert len(app.querySelectorAll("[data-key]")) == 19
+    assert app.display.textContent.strip() == "0"
+
+
+@js
+def test_calculator_buttons_complete_an_expression():
+    app = mounted_calculator()
+    click(app.one_button.element)
+    click(app.two_button.element)
+    click(app.add_button.element)
+    click(app.seven_button.element)
+    click(app.equals_button.element)
+
+    assert float(app.display.textContent.strip()) == 19.0
+
+
+@js
+def test_calculator_supports_decimal_sign_percent_and_clear():
+    app = mounted_calculator()
+    click(app.five_button.element)
+    click(app.zero_button.element)
+    click(app.percent_button.element)
+    assert float(app.display.textContent.strip()) == 0.5
+
+    click(app.sign_button.element)
+    assert float(app.display.textContent.strip()) == -0.5
+
+    click(app.clear_button.element)
+    assert app.display.textContent.strip() == "0"
+
+
+@js
+def test_calculator_visual_showcase():
+    app = mounted_calculator()
+    click(app.one_button.element)
+    click(app.two_button.element)
+    click(app.multiply_button.element)
+    click(app.three_button.element)
+    click(app.equals_button.element)
+
+    assert float(app.display.textContent.strip()) == 36.0

pyjs_examples-0.0.1/calculator/tests/test_calculator.py

@@ -0,0 +1,72 @@
+from pyjs import js
+from pyjs_examples.calculator.calculator import CalculatorApp
+
+
+@js
+def test_enters_whole_and_decimal_numbers():
+    calculator = CalculatorApp()
+    calculator.input_digit("1")
+    calculator.input_digit("2")
+    calculator.input_decimal()
+    calculator.input_digit("5")
+
+    assert calculator.value() == 12.5
+
+
+@js
+def test_performs_the_four_arithmetic_operations():
+    calculator = CalculatorApp()
+    calculator.input_digit("8")
+    calculator.choose_operator("+")
+    calculator.input_digit("2")
+    assert calculator.calculate() == 10.0
+
+    calculator.choose_operator("-")
+    calculator.input_digit("3")
+    assert calculator.calculate() == 7.0
+
+    calculator.choose_operator("*")
+    calculator.input_digit("6")
+    assert calculator.calculate() == 42.0
+
+    calculator.choose_operator("/")
+    calculator.input_digit("2")
+    assert calculator.calculate() == 21.0
+
+
+@js
+def test_supports_sign_percent_clear_and_divide_by_zero():
+    calculator = CalculatorApp()
+    calculator.input_digit("5")
+    calculator.input_digit("0")
+    calculator.percent()
+    assert calculator.value() == 0.5
+
+    calculator.toggle_sign()
+    assert calculator.value() == -0.5
+
+    calculator.clear()
+    assert calculator.value() == 0.0
+
+    calculator.input_digit("9")
+    calculator.choose_operator("/")
+    calculator.input_digit("0")
+    calculator.calculate()
+    assert calculator.display_value == "Error"
+    assert calculator.error
+
+
+@js
+def test_initial_and_calculation_state_is_stored_on_the_custom_element():
+    calculator = CalculatorApp(initial_value="12.0")
+
+    assert calculator.getAttribute("display-value") == "12.0"
+    calculator.choose_operator("+")
+    calculator.input_digit("3")
+
+    stored_value = calculator.getAttribute("stored-value")
+    assert stored_value is not None
+    assert float(stored_value) == 12.0
+    assert calculator.getAttribute("pending-operator") == "+"
+    assert not calculator.hasAttribute("replace-display")
+    assert not calculator.hasAttribute("error")