millwork 0.1.0__py3-none-any.whl

millwork/manual/pages/components/text.md

@@ -0,0 +1,145 @@
+---
+title: Text
+order: 1
+---
+
+# Text
+
+Words on a page: plain text with a variant and a tone, Markdown, code, and
+the small pieces that label things.
+
+## Text
+
+`ui.Text` is a string with a `variant`: `body`, `muted`, `caption`, `label`,
+`title`, `heading`, `subheading` or `mono`. `tone` colours it, `truncate`
+keeps it to one line, `align` sets the alignment.
+
+```python live
+ui.Stack(
+    ui.Text("Heading", variant="heading"),
+    ui.Text("Title", variant="title"),
+    ui.Text("Subheading", variant="subheading"),
+    ui.Text("Body text, the default."),
+    ui.Text("Muted text for secondary information.", variant="muted"),
+    ui.Text("A caption.", variant="caption"),
+    ui.Text("A label", variant="label"),
+    ui.Text("mono: for identifiers and paths", variant="mono"),
+    ui.Row(
+        ui.Text("success", tone="success"),
+        ui.Text("warning", tone="warning"),
+        ui.Text("destructive", tone="destructive"),
+        ui.Text("primary", tone="primary"),
+        gap=4,
+    ),
+    ui.Text(
+        "A long line that is cut with an ellipsis when it does not fit the width it is given, however long it goes on.",
+        truncate=True,
+    ),
+    gap=2,
+)
+```
+
+## Markdown
+
+`ui.Markdown` renders GitHub-flavoured Markdown as real elements: headings,
+lists, tables, links and code. `tight=True` removes the outer spacing for use
+inside a card or a table cell.
+
+```python live
+ui.Markdown("""
+### A heading inside Markdown
+
+Text with **bold**, *italic*, `code` and a [link](https://example.com).
+
+- a list
+- with items
+
+| Column | Value |
+| --- | --- |
+| one | 1 |
+| two | 2 |
+""")
+```
+
+## Code
+
+`ui.Code` shows a block of code with a `language` for highlighting, an
+optional `title`, a copy button (`copyable`, on by default), `wrap` for long
+lines and `max_height` to scroll past.
+
+```python live
+ui.Code(
+    'def greet(name: str) -> str:\n    return f"Hello, {name}."\n',
+    language="python",
+    title="greet.py",
+)
+```
+
+## Badge
+
+`ui.Badge` is a small label with a `tone` and an optional `icon`.
+
+```python live
+ui.Row(
+    ui.Badge("default"),
+    ui.Badge("muted", tone="muted"),
+    ui.Badge("primary", tone="primary"),
+    ui.Badge("accent", tone="accent"),
+    ui.Badge("success", tone="success", icon="check"),
+    ui.Badge("warning", tone="warning"),
+    ui.Badge("destructive", tone="destructive"),
+    gap=2,
+    wrap=True,
+)
+```
+
+## Kbd
+
+`ui.Kbd` shows keys as keycaps.
+
+```python live
+ui.Row(
+    ui.Text("Save with"),
+    ui.Kbd(keys=["Ctrl", "S"]),
+    ui.Text("or press"),
+    ui.Kbd(keys=["Enter"]),
+    gap=2,
+)
+```
+
+## Link
+
+`ui.Link` is a hyperlink. A path inside the app navigates over the session
+without a reload; `target="_blank"` opens a new tab.
+
+```python live
+ui.Row(
+    ui.Link(label="Welcome, inside the app", href="/"),
+    ui.Link(
+        label="An outside site", href="https://example.com", target="_blank", icon="external-link"
+    ),
+    gap=6,
+)
+```
+
+## Stat
+
+`ui.Stat` is a number with a `label`, an optional `hint`, a `tone` and an
+`icon`, for telemetry and summaries.
+
+```python live
+ui.Grid(
+    ui.Stat(label="Tokens", value="12,480", hint="this session", icon="hash"),
+    ui.Stat(label="Cost", value="€0.42", tone="success", icon="zap"),
+    ui.Stat(label="Latency", value="1.9 s", hint="p95", tone="warning", icon="clock"),
+    cols={"sm": 1, "md": 3},
+)
+```
+
+## Tooltip
+
+`ui.Tooltip` wraps one child and shows `content` on hover or focus.
+
+```python live
+ui.Tooltip(ui.Button("Hover me", variant="outline"), content="More about this button.")
+```

millwork/manual/pages/index.md

@@ -0,0 +1,67 @@
+---
+title: Welcome
+order: 0
+---
+
+# millwork
+
+millwork is a Python framework for data tools and AI applications. The browser
+runs one prebuilt React bundle; Python describes the page and handles its
+events. The project is Python only: the bundle is prebuilt, and Python owns
+every piece of state.
+
+```python
+import millwork as mw
+from millwork import ui
+
+app = mw.App("hello")
+
+
+@app.page("/")
+def home(s: mw.Session) -> ui.Component:
+    return ui.Page(ui.Text("Hello."))
+```
+
+Run it with `millwork run app.py` and open the address it prints.
+
+## How this manual works
+
+This manual is itself a millwork app. `millwork docs` serves it; its pages
+are Markdown files inside the package, and the sidebar, the search box and
+the header are catalogue components. Every example runs: the component you
+see is produced by the Python shown beneath it, executed by the server that
+serves these pages. Try the button:
+
+```python live
+ui.Button("Say hello", icon="sparkles", on_click=lambda s, _: s.toast("Hello from Python."))
+```
+
+An example may hold state. `state(Model)` returns an instance of your model
+that lives for the session, so a handler can change it and the page re-renders:
+
+```python live
+from pydantic import BaseModel
+
+
+class Counter(BaseModel):
+    n: int = 0
+
+
+def example(s):
+    st = state(Counter)
+    return ui.Row(
+        ui.Button("Add one", on_click=lambda s, _: setattr(st, "n", st.n + 1)),
+        ui.Text(f"Clicked {st.n} times.", variant="muted"),
+    )
+```
+
+A block ends in an expression, which is the component, or defines
+`example(s)`, a page function over the session. `mw` and `ui` are in scope;
+everything else is imported, as in an app.
+
+## Where to go next
+
+The App chapters say how an app is put together: pages and routing, state
+and handlers, signing in, theming, testing, running and deploying. The
+Components chapters walk through the catalogue, one group at a time, each
+component in its states with the Python that makes it.

millwork/manual/public/fonts/LICENSE.txt

@@ -0,0 +1,2 @@
+Inter, by Rasmus Andersson, is used under the SIL Open Font License 1.1.
+https://github.com/rsms/inter

millwork/manual/public/mark.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
+  <title>millwork</title>
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#1fb3d3"/>
+      <stop offset=".55" stop-color="#0a7ea4"/>
+      <stop offset="1" stop-color="#6d5ae0"/>
+    </linearGradient>
+  </defs>
+  <g fill="url(#g)">
+    <path id="b" d="M24 23C17 18 15 9 19 5c5-4 13 3 13 10 0 5-3 7-8 8Z"/>
+    <use href="#b" transform="rotate(120 24 24)"/>
+    <use href="#b" transform="rotate(240 24 24)"/>
+  </g>
+</svg>

millwork/manual/public/theme.json

@@ -0,0 +1,97 @@
+{
+  "mode": "system",
+  "logo": "/public/mark.svg",
+  "favicon": "/public/mark.svg",
+  "fonts": [
+    {
+      "family": "Inter",
+      "src": "/public/fonts/InterVariable.woff2",
+      "weights": "100 900"
+    }
+  ],
+  "density": "comfortable",
+  "tokens": {
+    "light": {
+      "background": "#ffffff",
+      "foreground": "#16232e",
+      "card": "#ffffff",
+      "card-foreground": "#16232e",
+      "popover": "#ffffff",
+      "popover-foreground": "#16232e",
+      "primary": "#0a7ea4",
+      "primary-foreground": "#ffffff",
+      "secondary": "#f6f8f9",
+      "secondary-foreground": "#3d4c58",
+      "muted": "#f6f8f9",
+      "muted-foreground": "#5a6a76",
+      "accent": "#e9f5f9",
+      "accent-foreground": "#08637f",
+      "border": "#e4e9ed",
+      "input": "#cfd8de",
+      "ring": "#0a7ea4",
+      "destructive": "#b83232",
+      "destructive-foreground": "#ffffff",
+      "success": "#08637f",
+      "success-foreground": "#ffffff",
+      "warning": "#8a5a0a",
+      "warning-foreground": "#ffffff",
+      "info": "#6d5ae0",
+      "info-foreground": "#ffffff",
+      "sidebar": "#f6f8f9",
+      "sidebar-foreground": "#16232e",
+      "sidebar-primary": "#0a7ea4",
+      "sidebar-primary-foreground": "#ffffff",
+      "sidebar-accent": "#eaeff2",
+      "sidebar-accent-foreground": "#16232e",
+      "sidebar-border": "#e4e9ed",
+      "sidebar-ring": "#0a7ea4",
+      "chart-1": "#0a7ea4",
+      "chart-2": "#eb6834",
+      "chart-3": "#6d5ae0",
+      "chart-4": "#eda100",
+      "chart-5": "#d55181",
+      "radius": "0.5rem",
+      "font-sans": "'Inter', ui-sans-serif, system-ui, sans-serif"
+    },
+    "dark": {
+      "background": "#0f1519",
+      "foreground": "#e6edf2",
+      "card": "#171f25",
+      "card-foreground": "#e6edf2",
+      "popover": "#171f25",
+      "popover-foreground": "#e6edf2",
+      "primary": "#3fb0d8",
+      "primary-foreground": "#0f1519",
+      "secondary": "#171f25",
+      "secondary-foreground": "#c3ced6",
+      "muted": "#171f25",
+      "muted-foreground": "#93a3ae",
+      "accent": "#12303a",
+      "accent-foreground": "#72c8e6",
+      "border": "#26323b",
+      "input": "#364550",
+      "ring": "#3fb0d8",
+      "destructive": "#f08080",
+      "destructive-foreground": "#0f1519",
+      "success": "#72c8e6",
+      "success-foreground": "#0f1519",
+      "warning": "#f0c060",
+      "warning-foreground": "#0f1519",
+      "info": "#9a8cf0",
+      "info-foreground": "#0f1519",
+      "sidebar": "#141b20",
+      "sidebar-foreground": "#e6edf2",
+      "sidebar-primary": "#3fb0d8",
+      "sidebar-primary-foreground": "#0f1519",
+      "sidebar-accent": "#202a31",
+      "sidebar-accent-foreground": "#e6edf2",
+      "sidebar-border": "#26323b",
+      "sidebar-ring": "#3fb0d8",
+      "chart-1": "#2a9ac4",
+      "chart-2": "#d95926",
+      "chart-3": "#9085e9",
+      "chart-4": "#c98500",
+      "chart-5": "#d55181"
+    }
+  }
+}

millwork/nodes.py

@@ -0,0 +1,300 @@
+"""Components, the tree they become, and the diff between two trees.
+
+A page function returns a ``Component``. ``build`` walks it into a ``Tree``:
+a flat table of wire ``Node``s with stable ids, plus the handlers those nodes
+bound. ``diff`` turns the previous and the next ``Tree`` into patch ops.
+
+Identity: a node's id is its parent's id, a slash, and either its ``key`` or
+its position among the parent's children, counting ``None`` children so a
+conditional sibling does not shift the ones after it. The position carries
+the component type, so a different component in the same place is a
+remove and an add, never a prop update on the wrong kind of node.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import enum
+from collections.abc import Callable, Iterable, Mapping
+from pathlib import PurePath
+from typing import Any, ClassVar, Protocol, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+from pydantic_core import to_jsonable_python
+
+from millwork.protocol import AddOp, ChildrenOp, Node, PatchOp, RemoveOp, SetOp, UnsetOp
+
+Handler = Callable[..., Any]
+ROOT_ID = "root"
+
+
+@runtime_checkable
+class Wireable(Protocol):
+    """Anything that knows how to appear in props: tasks, file references."""
+
+    def __millwork_wire__(self) -> Any: ...
+
+
+class Component(BaseModel):
+    """Base of every catalogue component. Subclasses set ``type``.
+
+    Children are positional: ``Card(Text("a"), Button("b"), title="t")``. A
+    bare string child becomes a ``Text``; ``None`` is skipped but keeps its
+    position. Props named ``on_*`` are handlers and never reach the wire;
+    the wire sees ``on_*: true`` so the bundle knows which events to emit.
+    """
+
+    model_config = ConfigDict(extra="forbid", arbitrary_types_allowed=True)
+
+    type: ClassVar[str] = "component"
+    key: str | None = None
+    hidden: bool = False
+    cls: str | None = None
+    children: list[Any] = []
+
+    def __init__(self, *children: Any, **props: Any) -> None:
+        if children and "children" in props:
+            raise TypeError("children are positional or keyword, not both")
+        if children:
+            props["children"] = list(children)
+        if "children" in props:
+            props["children"] = _flatten(props["children"])
+        super().__init__(**props)
+
+    # Fields that never reach the wire as they are (a callable evaluated at
+    # render, say); ``wire_extra`` supplies what goes instead.
+    wire_exclude: ClassVar[frozenset[str]] = frozenset()
+
+    def wire_extra(self) -> dict[str, Any]:
+        """Extra props computed at render time. Override in components that need it."""
+        return {}
+
+    def wire_type(self) -> str:
+        """The node type on the wire; a custom component names its own."""
+        return self.type
+
+
+class Text(Component):
+    type: ClassVar[str] = "Text"
+    content: str = ""
+    variant: str = "body"
+    truncate: bool = False
+    align: str | None = None
+    tone: str | None = None
+
+    def __init__(self, content: str = "", **props: Any) -> None:
+        super().__init__(content=content, **props)
+
+
+class Tree:
+    """A built page: flat nodes, the handlers they bound, and the root id."""
+
+    def __init__(self) -> None:
+        self.root: str = ROOT_ID
+        self.nodes: dict[str, Node] = {}
+        self.handlers: dict[tuple[str, str], Handler] = {}
+        self.callables: dict[tuple[str, str], Callable[..., Any]] = {}
+        self.components: dict[str, Component] = {}
+        # Nodes whose children include a run of keyless siblings of one type, and
+        # that type: a list built from data, if the run grows or shrinks later.
+        self.keyless_runs: dict[str, str] = {}
+
+    def handler(self, node_id: str, event: str) -> Handler | None:
+        return self.handlers.get((node_id, event))
+
+
+def _flatten(children: Any) -> list[Any]:
+    """Lists and tuples among children are spliced in, so a helper may return a list."""
+    out: list[Any] = []
+    for child in children:
+        if isinstance(child, list | tuple):
+            out.extend(_flatten(child))
+        else:
+            out.append(child)
+    return out
+
+
+def build(root: Component, root_id: str = ROOT_ID) -> Tree:
+    tree = Tree()
+    tree.root = root_id
+    _walk(root, root_id, tree)
+    return tree
+
+
+def _walk(component: Component, node_id: str, tree: Tree) -> None:
+    props: dict[str, Any] = {}
+    for name, value in component:
+        if name in ("children", "key") or name in component.wire_exclude:
+            continue
+        if callable(value) and not isinstance(value, type):
+            if name.startswith("on_"):
+                tree.handlers[(node_id, name[3:])] = value
+                props[name] = True
+            else:
+                tree.callables[(node_id, name)] = value
+                props[name] = {"$callable": True}
+            continue
+        if isinstance(value, Component):
+            slot_id = f"{node_id}/@{name}"
+            _walk(value, slot_id, tree)
+            props[name] = {"$node": slot_id}
+            continue
+        if isinstance(value, list) and value and all(isinstance(v, Component) for v in value):
+            items: list[Any] = []
+            for index, item in enumerate(value):
+                slot_id = f"{node_id}/@{name}.{item.key or index}"
+                if slot_id in tree.nodes:
+                    raise ValueError(f"duplicate key {item.key!r} in {name} of {node_id}")
+                _walk(item, slot_id, tree)
+                items.append({"$node": slot_id})
+            props[name] = items
+            continue
+        if value is None and name not in component.model_fields_set:
+            # Absent on the wire: a prop the page never set. An explicit ``value=None``
+            # is sent as null and means "controlled, and empty".
+            continue
+        props[name] = wire_value(value)
+    for name, value in component.wire_extra().items():
+        if isinstance(value, Component):
+            slot_id = f"{node_id}/@{name}"
+            _walk(value, slot_id, tree)
+            props[name] = {"$node": slot_id}
+        elif (
+            isinstance(value, dict)
+            and value
+            and all(isinstance(v, Component) for v in value.values())
+        ):
+            slots: dict[str, Any] = {}
+            for key, child in value.items():
+                slot_id = f"{node_id}/@{name}.{key}"
+                _walk(child, slot_id, tree)
+                slots[str(key)] = {"$node": slot_id}
+            props[name] = slots
+        else:
+            props[name] = wire_value(value)
+    for event, handler in getattr(component, "events", {}).items():
+        tree.handlers[(node_id, event)] = handler
+        props[f"on_{event}"] = True
+    if props.get("hidden") is False:
+        del props["hidden"]
+    children_ids: list[str] = []
+    for index, child in enumerate(component.children):
+        if child is None:
+            continue
+        if isinstance(child, str):
+            child = Text(child)
+        if not isinstance(child, Component):
+            raise TypeError(
+                f"{type(component).__name__} child {index} is {type(child).__name__}, "
+                "not a component or a string"
+            )
+        child_id = (
+            f"{node_id}/{child.key}" if child.key else f"{node_id}/{index}:{child.wire_type()}"
+        )
+        if child_id in tree.nodes:
+            raise ValueError(f"duplicate key {child.key!r} under {node_id}")
+        children_ids.append(child_id)
+        _walk(child, child_id, tree)
+    _check_keys(component, node_id, tree)
+    tree.nodes[node_id] = Node(
+        id=node_id, type=component.wire_type(), props=props, children=children_ids
+    )
+    tree.components[node_id] = component
+
+
+def wire_value(value: Any) -> Any:
+    """Turn a prop value into JSON-ready data."""
+    if value is None or isinstance(value, bool | int | float | str):
+        return value
+    if isinstance(value, Wireable):
+        return value.__millwork_wire__()
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if isinstance(value, enum.Enum):
+        return value.value
+    if isinstance(value, dt.datetime | dt.date | dt.time):
+        return value.isoformat()
+    if isinstance(value, PurePath):
+        return str(value)
+    if isinstance(value, Mapping):
+        return {str(k): wire_value(v) for k, v in value.items()}
+    if isinstance(value, Iterable) and not isinstance(value, bytes | bytearray):
+        return [wire_value(v) for v in value]
+    try:
+        return to_jsonable_python(value)
+    except Exception as exc:
+        raise TypeError(f"cannot send a {type(value).__name__} as a prop") from exc
+
+
+def diff(old: Tree | None, new: Tree) -> list[PatchOp]:
+    """Patch ops that take the client from ``old`` to ``new``.
+
+    Adds come first so references resolve, then updates, then removes.
+    """
+    if old is None:
+        raise ValueError("diff needs a previous tree; use a mount for the first render")
+    ops: list[PatchOp] = []
+    for node_id, node in new.nodes.items():
+        if node_id not in old.nodes:
+            ops.append(AddOp(node=node))
+    for node_id, node in new.nodes.items():
+        before = old.nodes.get(node_id)
+        if before is None:
+            continue
+        if before.type != node.type:
+            ops.append(RemoveOp(id=node_id))
+            ops.append(AddOp(node=node))
+            continue
+        changed = {k: v for k, v in node.props.items() if before.props.get(k, _MISSING) != v}
+        if changed:
+            ops.append(SetOp(id=node_id, props=changed))
+        gone = [k for k in before.props if k not in node.props]
+        if gone:
+            ops.append(UnsetOp(id=node_id, keys=gone))
+        if before.children != node.children:
+            ops.append(ChildrenOp(id=node_id, children=node.children))
+    for node_id in old.nodes:
+        if node_id not in new.nodes:
+            ops.append(RemoveOp(id=node_id))
+    return ops
+
+
+def apply(nodes: dict[str, Node], ops: list[PatchOp]) -> dict[str, Node]:
+    """Apply patch ops to a node table, the way the bundle does. For tests."""
+    out = {k: v.model_copy(deep=True) for k, v in nodes.items()}
+    for op in ops:
+        if isinstance(op, AddOp):
+            out[op.node.id] = op.node.model_copy(deep=True)
+        elif isinstance(op, RemoveOp):
+            out.pop(op.id, None)
+        elif isinstance(op, SetOp):
+            out[op.id].props.update(op.props)
+        elif isinstance(op, UnsetOp):
+            for k in op.keys:
+                out[op.id].props.pop(k, None)
+        elif isinstance(op, ChildrenOp):
+            out[op.id].children = list(op.children)
+    return out
+
+
+_MISSING = object()
+
+
+# A run of this many keyless siblings of one type may be a list built from data,
+# where a reorder would re-render every row instead of moving them. It is one
+# only when its length changes between renders; a static layout never does.
+KEYLESS_RUN = 4
+
+
+def _check_keys(component: Component, node_id: str, tree: Tree) -> None:
+    run: list[Component] = []
+    for child in component.children:
+        if isinstance(child, Component) and child.key is None:
+            if run and type(child) is not type(run[-1]):
+                run = []
+            run.append(child)
+            if len(run) == KEYLESS_RUN:
+                tree.keyless_runs[node_id] = child.wire_type()
+                return
+        else:
+            run = []