Create PyScript UIs in Python

Author: laffra

README.md

@@ -1,2 +1,114 @@
 # ltk
 LTK is a little toolkit for writing UIs in PyScript
+
+LTK is implemented as a declarative Python library and leverages `jQuery` for DOM operations.
+
+## Widget Specification
+
+New widget types are created by symply subclassing `ltk.Widget`:
+
+```python
+class HBox(Widget):
+    classes = [ "ltk-hbox" ]
+```
+
+By default, widgets are created as `div` DOM elements. You can choose a different tag:
+
+```python
+class Preformatted(Widget):
+    classes = [ "ltk-pre" ]
+    tag = "pre"
+```
+
+## Creating a UI
+
+To create a UI, elements are constructed declaratively:
+
+```python
+ltk.Table(
+    ltk.TableRow(
+        ltk.TableHeader("header1")
+        ltk.TableHeader("header2")
+    ),
+    [
+        ltk.TableRow(
+            ltk.TableData(value1),
+            ltk.TableData(value2),
+        )
+        for value1, value2 in data
+    ],
+)
+```
+
+Widgets are added to others by using jQuery's `append` and `appendTo` calls:
+```python
+ltk.body.append(
+    ltk.Table(...)
+)
+
+container = ltk.VBox(...)
+ltk.H1("This is a header").appendTo(container)
+```
+
+## Styling
+
+Widgets can be styled using element styles:
+```python
+ltk.Text("Some text")
+    .css("background-color", "red")
+    .css("color", "white")
+    .css("padding", 8)
+```
+
+Widgets can also be styled using an external stylesheet:
+```python
+ltk.Text("Some text").addClass("my-special-text)
+```
+
+```css
+.ltk-text {
+    font-family: Arial;
+}
+
+.my-special-text {
+    font-family: Courier;
+    background-color: red;
+    color: white;
+    padding: 8px;
+}
+```
+
+## Events
+
+Event handlers are attached using jQuery mechanisms. As the functions cross PyOdide and JavaScript namespaces, they need to be wrapped with `pyodide.ffi.create_proxy` calls. We use the shortcut offered by `ltk.proxy`:
+```python
+def buy(event):
+    purchase(...)
+
+Card("Buy Now").on("click", ltk.proxy(buy))
+```
+
+## Examples
+
+See the `LTK Kitchen Sink` or explore the `examples` folder
+
+
+## License
+
+LTK is covered under the Apache License:
+
+ - The Apache license is a permissive open source software license.
+
+ - It allows users to freely use, modify, and distribute the software (including for commercial purposes).
+
+ - Modified versions can be distributed without having to release the source code. Though source code changes should be documented.
+
+ - The license requires modified versions to retain the Apache license and copyright notice.
+
+ - The software is provided by the authors "as is" with no warranties.
+
+ - Users are not granted patent rights by contributors, but contributors cannot revoke patent grants for previous contributions.
+
+ - The license does not require derived works to adopt the Apache license. Though this is encouraged for consistency.
+
+

examples/__init__.py

@@ -0,0 +1,9 @@
+from examples import custom
+from examples import table
+from examples import tictactoe
+
+elements = [
+    tictactoe.create(),
+    table.create(),
+    custom.create(),
+]

examples/custom.py

@@ -0,0 +1,35 @@
+import ltk
+
+# Create a new widget, based on VBox
+class ImageWithLabel(ltk.VBox):
+    classes = [ "custom" ]
+
+    def __init__(self, src, label):
+        ltk.VBox.__init__(self, 
+            # Add two widgets. Styling could be done in external CSS
+            ltk.Image(src)
+                # CSS selector would be ".custom .ltk-image"
+                .css("width", 200),
+            ltk.Text(label)
+                # CSS selector would be ".custom .ltk-text"
+                .css("width", "100%")
+                .css("text-align", "center")
+        )
+
+
+def create():
+    # Create the custom widget and add an orange border for clarity
+    custom_widget = ImageWithLabel(
+        "https://chrislaffra.com/chris.png",
+        "Chris laffra"
+    ).css("border", "2px solid orange")
+
+    return ltk.VBox(
+        ltk.H2("Showing a Card with a custom widget inside of it"),
+        ltk.Card(custom_widget)
+            .css("width", 200)
+            .draggable(),
+        ltk.Text("For clarity, we marked the custom widget orange.")
+            .css("margin-top", 20),
+        ltk.H4("Tip: drag the card."),
+    ).attr("name", "Custom")

examples/table.py

@@ -0,0 +1,62 @@
+import ltk
+
+# Create an HTML table to display country temperature data
+# Use LTK widgets to generate the table structure
+
+def create():
+    # In this example we construct the UI by iteratively appending to a container.
+    # Elements are added to the container using jQuery "append" and "appendTo" calls.
+    # The table itself is created with a more declarative creation pattern.
+    container = ltk.Container().attr("name", "HTML Tables")
+
+    # DOM elements can be created using ltk objects, or directly with HTML.
+    container.append(
+        ltk.create("""
+            <h1>
+                HTML Table created in Python
+            </h1>
+        """)
+    )
+
+    # Resize options to be used for the first colum. We pass a Python dict 
+    # to JavaScript and convert it to a map using the "to_js" function.
+    resize_options = ltk.to_js({
+        "handles": "e",
+        "alsoResize": ".country",
+    })
+
+    ltk.Table(
+        # Create a table with headers for country and temperature.
+        ltk.TableRow(
+            ltk.TableHeader("Country")
+                .css("border-right", "2px solid orange")
+                .resizable(resize_options),
+            ltk.TableHeader("Yearly Average Temperature")
+        ),
+        # Populate the table rows with country and temperature data.
+        [
+            ltk.TableRow(
+                ltk.TableData(country).addClass("country"),
+                ltk.TableData(temperature),
+            )
+            for country, temperature in get_averages().items()
+        ],
+    ).appendTo(container)
+
+    container.append(ltk.H4("Tip: resize the country column using the orange handle."))
+
+    return container
+
+
+def get_averages():
+    return {
+        "Afghanistan": 12.6,
+        "Albania": 11.4,
+        "Algeria": 22.5,
+        "Andorra": 7.6,
+        "Angola": 21.55,
+        "Antigua and Barbuda": 26,
+        "Argentina": 14.8,
+        "Armenia": 7.15,
+        "Australia": 21.65,
+    }

examples/tictactoe.css

@@ -0,0 +1,16 @@
+.square {
+    width: 70px;
+    height: 70px;
+    border: 1px solid gray;
+    cursor: pointer;
+}
+
+.choice {
+    font-family: "Brush Script MT";
+    font-size: 42px;
+    font-family: Brush Script MT;
+    text-align: center;
+    margin: auto;
+    width: 90%;
+    height: 90%;
+}

examples/tictactoe.py

@@ -0,0 +1,58 @@
+import ltk
+
+# Tic Tac Toe Game
+#
+# This implements a simple Tic Tac Toe game in PyScript using the LTK toolkit.
+# It draws a Tic Tac Toe board that allows clicking squares to place X and O marks alternately.
+#
+# The UI uses LTK widget classes:
+#  - Container for each square
+#  - VBox and HBox to create the grid
+#  - Text for the X and O labels
+#
+# This provides an interactive grid layout without needing much explicit layout code.
+
+def choose(event):
+    #
+    # This event handler is attached to each square container:
+    #  - The handler checks if the square is empty
+    #  - If empty, it adds an X or O text label based on whose turn it is
+    #
+    square = ltk.find(event.target)
+    if not square.text():
+        square.append(
+            ltk.Text("X" if ltk.find(".choice").length % 2 else "O")
+                .addClass("choice")
+        )
+
+
+def enter(event):
+    # First erase all existing squares
+    ltk.find(".square").css("background", "white")
+
+    # Highlight the current square, but only if does not contain a choice already
+    square = ltk.jQuery(event.target)
+    if not square.text():
+        square.css("background", "lightblue")
+
+
+def create():
+    # Set up the game board:
+    #  - Create a 3x3 grid of Container widgets to represent the board squares
+    #  - Attach a click handler to each square container
+    #  - Add the grid containers into a nested VBox/HBox layout
+    #  - Render the layout into the #example div
+    return ltk.Div(
+        ltk.H2("Tic Tac Toe Game"),
+        ltk.VBox(
+            ltk.HBox(
+                ltk.Container()
+                    .addClass("square")
+                    .on("click", ltk.proxy(choose))
+                    .on("mouseenter", ltk.proxy(enter))
+                for column in range(3)
+            )
+            for row in range(3)
+        ),
+        ltk.H4("Tip: Click inside the squares."),
+    ).attr("name", "Tic Tac Toe")

index.html

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <title>LTK</title>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+
+    <!-- Import PyScript CSS and JS -->
+    <link rel="stylesheet" href="https://pyscript.net/releases/2023.11.1/core.css" />
+    <script defer type="module" src="https://pyscript.net/releases/2023.11.1/core.js"></script>
+
+    <!-- Import LTK and jQuery -->
+    <link rel="stylesheet" href="ltk/ltk.css" />
+    <script src="https://code.jquery.com/jquery-3.6.0.js"></script>
+    <script src="https://code.jquery.com/ui/1.13.2/jquery-ui.js"></script>
+    <link rel="stylesheet" href="https://code.jquery.com/ui/1.13.2/themes/base/jquery-ui.css">
+
+    <!-- Import custom CSS for our examples -->
+    <link rel="stylesheet" href="examples/tictactoe.css" />
+</head>
+<body>
+    <h1>The PyScript LTK Kitchen Sink</h1>
+
+    <!-- Include LTK itself and its examples -->
+    <py-config>
+        [[fetch]]
+        files = [
+            "ltk/__init__.py",
+            "ltk/jquery.py",
+            "ltk/widgets.py",
+            "examples/__init__.py",
+            "examples/tictactoe.py",
+            "examples/custom.py",
+            "examples/table.py",
+        ]
+    </py-config>
+
+    <!-- Create all the examples and add them to the DOM -->
+    <py-script>
+        import ltk, examples
+        ltk.body.append(
+            ltk.Tabs(examples.elements)
+        )
+    </py-script>
+</body>
+</html>