millwork 0.1.0__py3-none-any.whl

millwork/manual/pages/app/state.md

@@ -0,0 +1,151 @@
+---
+title: State and handlers
+order: 1
+---
+
+# State and handlers
+
+A page is a function of the session's state. A handler changes that state;
+the page renders again; the browser gets the difference. There is nothing
+reactive to subscribe to and nothing to invalidate: whatever a page shows
+comes from `s.state`, and the only place where things change is a handler.
+
+## The loop
+
+`s.state` is an instance of the model named on the page, or on the app for
+every page. A handler is any callable bound to an `on_*` prop. It receives
+the session and the event's payload: the new value for `on_change`, the
+validated model for a form's `on_submit`, nothing of use for `on_click`.
+It may be sync or async. When it returns, the page renders once, under a
+lock, so a render sees state as a handler left it.
+
+```python live
+from pydantic import BaseModel
+
+
+class Counter(BaseModel):
+    n: int = 0
+    note: str = ""
+
+
+def bump(s, _):
+    state(Counter).n += 1
+
+
+async def remember(s, text):
+    state(Counter).note = text
+
+
+def example(s):
+    st = state(Counter)
+    return ui.Stack(
+        ui.Row(
+            ui.Button("Count", on_click=bump),
+            ui.Text(f"{st.n} so far", variant="muted"),
+            gap=3,
+        ),
+        ui.Input(value=st.note, placeholder="Type, then look right", on_change=remember),
+        ui.Text(f"Python holds {st.note!r}", variant="muted"),
+        gap=3,
+    )
+```
+
+A handler that raises shows "Something went wrong." as a toast and the log
+has the traceback; the page stays as it was. A handler that needs to ask
+first uses `s.confirm` or `s.ask`, in the Feedback chapter.
+
+## Keys
+
+Every component takes a `key`. A key is a component's identity across
+renders: a keyed node keeps its browser-side state (what is typed, which
+tab is open, where a list is scrolled) when the tree around it changes,
+and a list of keyed rows that is reordered moves the rows instead of
+redrawing them. Siblings without keys are told apart by position, which is
+right for a fixed layout and wrong for a list built from data.
+
+```python live
+from pydantic import BaseModel
+
+
+class Todo(BaseModel):
+    items: list[str] = ["Read the manual", "Build a page", "Ship it"]
+
+
+def drop(s, item):
+    state(Todo).items.remove(item)
+
+
+def example(s):
+    st = state(Todo)
+    return ui.Stack(
+        *(
+            ui.Row(
+                ui.Text(item),
+                ui.Button(icon="x", size="sm", variant="ghost", on_click=lambda s, _, i=item: drop(s, i)),
+                justify="between",
+                key=item,
+            )
+            for item in st.items
+        ),
+        ui.Button(
+            "Put them back",
+            size="sm",
+            variant="outline",
+            on_click=lambda s, _: setattr(st, "items", Todo().items),
+        ),
+        gap=2,
+    )
+```
+
+A key is also how `s.reset(key)` returns a browser-owned control to its
+`default`, and how `ui.Button(form=key)` finds its form. `hidden=True`
+keeps a component in the tree without showing it, so its browser-side
+state survives; `cls` adds Tailwind classes for a spacing or sizing tweak.
+
+## Who owns a value
+
+A control shows either what Python says (`value=`, with every change
+reported through `on_change`) or what the browser holds (`default=`, with
+changes reported but not required), one or the other. The Inputs chapter shows
+the two side by side. Inside a `ui.Form` every control is browser-owned
+draft state until the form is submitted.
+
+## Reaching the session from anywhere
+
+Handlers get the session as their first argument. Code further down, a
+helper or a library that wants to show a toast, calls `mw.session()`: it
+returns the session of the handler or task that is running, on the loop
+or in the thread of a sync task.
+
+```python live
+import millwork as mw
+
+
+def notify(what: str) -> None:
+    mw.session().toast(what, tone="success")
+
+
+def example(s):
+    return ui.Button("Call a helper", variant="outline", on_click=lambda s, _: notify("The helper found the session."))
+```
+
+`s.refresh()` asks for a render from code that is not a handler, such as
+work spawned on the loop that changes state on its own. Many calls in one
+tick are one render.
+
+## What the framework notices
+
+Some mistakes the framework can see, and says so: once per session, as a
+log line with the page's path, and in debug mode as a toast as well.
+
+- **A slow page function**, over 20 ms. The page function builds the tree;
+  I/O belongs in `connect` or a task.
+- **A list without keys**: four or more siblings of one type without a
+  key whose number changed between renders.
+- **A handler that changed nothing**: no state, no command, no task.
+  Usually a forgotten `await`.
+- **A sync task that changed state from its thread.** A task reports
+  through `progress()` and returns a result; the handler that awaits it
+  puts the result in state.
+
+The Running chapter says how to turn debug mode on.

millwork/manual/pages/app/testing.md

@@ -0,0 +1,147 @@
+---
+title: Testing
+order: 4
+---
+
+# Testing
+
+A page is a function of state, handlers change state, and the wire is a
+list of messages. So a test runs the real session, dispatcher, tasks and
+render with no socket and no browser: `millwork.testing.TestApp` opens a
+page, a test clicks and types through the real event path, and reads the
+state and the messages a tab would have received.
+
+## A test
+
+```python
+from millwork import ui
+from millwork.testing import TestApp
+
+
+async def test_a_click_counts(app):
+    async with TestApp(app).open("/") as page:
+        assert page.find("count").props["content"] == "count 0"
+        await page.click("more")
+        assert page.state.n == 1
+        assert page.find("count").props["content"] == "count 1"
+        assert page.last_patch is not None
+```
+
+Tests are `async def`, run by pytest-asyncio in auto mode. `open(path)` runs the page's `connect` and the first render and
+yields a `Page`; leaving the block closes the session, `close` hook
+included. `open(path, user=User(...))` signs a person in; without one a
+gated page raises `Forbidden`, which is a test of its own. `open(path,
+state=State(...))` starts from a prepared state and skips `connect`.
+
+## Finding things
+
+`page.find(ui.Table)` is the first node of a type, `page.find("more")` the
+node with that key, `find_all` every one of them. A found node has `id`,
+`type`, `props` as they would go to the tab, `children` and, on a table,
+`rows`. `page.text()` is every string on the page, for a quick "is it
+there". `page.state` is the live state and `page.session` the session
+itself.
+
+## Acting
+
+Each action is an event through the real dispatcher, followed by the real
+render: `click(node)`, `change(node, value)`, `submit(form, draft)` with a
+dict or a model instance, `select(table, keys)`, `action(node, id, key)`
+for a row or menu action, `upload(node, path, field=)` which runs every
+check an upload gets and returns the `FileRef`, `send(chat, text,
+files=)`, `stop(chat)`, `navigate(path)`, and `event(node, name, payload)`
+for anything else. A draft that fails validation produces the same
+`form_issues` command the tab would get, at the same pointers.
+
+```python
+async def test_the_form_rejects_a_short_name(app):
+    async with TestApp(app).open("/") as page:
+        form = page.find(ui.Form)
+        await page.submit(form, {"project_name": "x"})
+        assert page.commands[-1].name == "form_issues"
+        assert page.commands[-1].args["issues"][0]["pointer"] == "/project_name"
+        assert page.state.settings is None
+```
+
+## Questions and tasks
+
+A handler that calls `s.confirm` or `s.ask` stops and waits; the test sees
+the dialog on the page and answers it with `page.answer(value)`, `False`
+or `None` for a dismissal. A task started by a handler has run by the time
+the action returns: `page.session.tasks[-1]` has its `ok`, `result` and
+`progress`. A chat turn's chunks are in `page.stream`, in order.
+
+```python
+async def test_wiping_asks_first(app):
+    async with TestApp(app).open("/") as page:
+        await page.click("wipe")
+        assert page.find(ui.Dialog).props["title"] == "Wipe?"
+        await page.answer(False)
+        assert page.state.count == 0
+        await page.click("wipe")
+        await page.answer(True)
+        assert page.state.count == -1
+```
+
+## What the tab would have seen
+
+`page.messages` is every message the server sent: `patches`, `last_patch`,
+`commands` (toasts, downloads, navigations, form issues), `toasts` as
+plain text, `stream` and `errors` are views on it. `settle()` waits until
+the session has nothing left to do: running tasks and spawned work are
+awaited, the coalesced render runs at once, and a handler waiting on an
+open question is left for `answer`. Every action settles before it
+returns, so a test reads the result on the next line.
+
+## Running one here
+
+The manual can run a test on itself. The button below builds a small app,
+opens it through `TestApp`, clicks, and reports what the assertions said.
+
+```python live
+import millwork as mw
+from pydantic import BaseModel
+from millwork.testing import TestApp
+
+
+class Count(BaseModel):
+    n: int = 0
+
+
+def tiny_app() -> mw.App:
+    app = mw.App("tiny", state=Count, public=None)
+
+    @app.page("/")
+    def home(s):
+        return ui.Page(
+            ui.Text(f"count {s.state.n}", key="count"),
+            ui.Button("more", key="more", on_click=lambda s, _: setattr(s.state, "n", s.state.n + 1)),
+        )
+
+    return app
+
+
+class Outcome(BaseModel):
+    text: str = "Not run yet."
+
+
+async def run_test(s, _):
+    try:
+        async with TestApp(tiny_app()).open("/") as page:
+            assert page.find("count").props["content"] == "count 0"
+            await page.click("more")
+            assert page.state.n == 1
+            assert page.find("count").props["content"] == "count 1"
+            ops = [op.op for op in page.last_patch.ops]
+        state(Outcome).text = f"Passed. The click produced a patch with {ops}."
+    except AssertionError as exc:
+        state(Outcome).text = f"Failed: {exc}"
+
+
+def example(s):
+    return ui.Row(
+        ui.Button("Run the test", icon="play", on_click=run_test),
+        ui.Text(state(Outcome).text, variant="muted"),
+        gap=4,
+    )
+```

millwork/manual/pages/app/theming.md

@@ -0,0 +1,122 @@
+---
+title: Theming
+order: 3
+---
+
+# Theming
+
+An app's look is one JSON file: `public/theme.json`, found on its own, or
+any path given as `App(theme=...)`. It holds the colour tokens for light
+and dark, the fonts, the logo and a few options. The server renders it
+into the page before the bundle loads, so there is no flash of the default
+look. Without a file the app looks like stock shadcn.
+
+```json
+{
+  "mode": "system",
+  "fonts": [{"family": "Inter", "src": "/public/fonts/InterVariable.woff2", "weights": "100 900"}],
+  "tokens": {
+    "light": {"primary": "#0a7ea4", "primary-foreground": "#ffffff", "radius": "0.5rem",
+              "font-sans": "'Inter', ui-sans-serif, system-ui, sans-serif"},
+    "dark": {"primary": "#2a9ac4"}
+  },
+  "logo": {"light": "/public/logo.svg", "dark": "/public/logo-dark.svg"},
+  "favicon": "/public/favicon.svg",
+  "login_image": "/public/login.jpg",
+  "density": "comfortable"
+}
+```
+
+## Tokens
+
+The tokens are shadcn's: `background`, `foreground`, `card`, `popover`,
+`primary`, `secondary`, `muted`, `accent`, `destructive`, each with its
+`-foreground`, then `border`, `input`, `ring`, `chart-1` to `chart-5`, the
+`sidebar-*` group, `radius`, `font-sans`, `font-mono` and `font-heading`.
+Three are millwork's own, with their `-foreground`: `success` and
+`warning`, which the catalogue's `tone` vocabulary needs, and `info`, which
+a custom component may use as `bg-info text-info-foreground`. A value is
+one CSS value, hex, `oklch(...)`, a length or a font stack. A token left
+out keeps the default, so a brand is four or five values. An unknown
+token, or a value CSS could misuse, is refused when the app starts.
+
+Light and dark are both always there: `mode` is `light`, `dark` or
+`system`, and the user menu in the header lets a person choose, kept in
+their browser. The tones below take their colours from this manual's
+theme file, in whichever scheme you are reading.
+
+```python live
+ui.Stack(
+    ui.Row(
+        ui.Badge("primary", tone="primary"),
+        ui.Badge("success", tone="success", icon="check"),
+        ui.Badge("warning", tone="warning"),
+        ui.Badge("destructive", tone="destructive"),
+        ui.Badge("accent", tone="accent"),
+        gap=2,
+        wrap=True,
+    ),
+    ui.Alert(title="Saved", description="A success alert takes the success tokens.", tone="success"),
+    gap=3,
+)
+```
+
+The five chart tokens are read in order by the charts. Pick them as a set
+that stays apart for colour-blind readers in both schemes.
+
+## Fonts
+
+A font is a file under `public/`, served by the app: `family`, `src`,
+`weights` (one weight or a range) and `style`. It becomes an `@font-face`
+rule, and the `font-sans` token names it. A `url` to a font service is
+accepted instead of `src` and logged once at start, as a reminder that
+every page view then calls a third party.
+
+## Logo, favicon and login image
+
+`logo` is one path, or `light` and `dark` paths; the `ui.Header` shows it
+unless `logo=False`, and `ui.Logo` puts it on a page of the app's own, an
+error page for instance. `favicon` and `login_image` are paths under
+`/public/` too. The login page and the framework's error pages show the
+logo and the app's name. A theme sets colours, fonts and these images;
+layout belongs to the components.
+
+## Options
+
+`density` is `comfortable` or `compact`; compact tightens tables, forms,
+stacks and cards for data tools. `scrollbars` is `thin` (the default, in
+the page's own ink) or `auto` for the platform's. `locale` sets the page
+language and how dates and numbers are formatted.
+
+## Strings
+
+Interface copy comes from the app's own Python, in its own language. The
+framework has strings of its own: the bundle's controls (`send`, `stop`,
+`attach`, `search`, `no_results`, `clear`, `loading`, `reconnecting`,
+`sign_in`, `username`, `password`) and the messages the server sends on
+its own account (`wait_for_reply`, `message_too_long`, `something_went_wrong`,
+`too_many_sessions`, `signed_out` and the rest). They are English; an app in
+another language sets them in the theme's `strings` section, key by key,
+and a key the framework does not know is refused. Every key is in the
+table below, with its English.
+
+```json
+{"locale": "nl", "strings": {"send": "Verstuur", "stop": "Stop", "search": "Zoeken"}}
+```
+
+```python live
+from millwork.theme import STRINGS
+
+ui.Table(
+    rows=[{"key": k, "english": v} for k, v in sorted(STRINGS.items())],
+    row_key="key",
+    height=320,
+)
+```
+
+## While designing
+
+In debug mode the theme file is watched: a save reaches every open tab as
+a command, without a reload. `millwork docs --theme path/to/theme.json`
+shows this whole manual in a theme, which is the quickest way to see a
+token set on every component in both schemes.

millwork/manual/pages/components/charts.md

@@ -0,0 +1,263 @@
+---
+title: Charts
+order: 5
+---
+
+# Charts
+
+A chart takes rows, like the Table does. `x` names the category or time
+column and `y` the value column, or several of them. Each series takes the
+next of the theme's five chart colours, in the order given, and keeps it
+when a neighbour disappears. Five series is the limit: a sixth has no colour
+of its own, so fold it into another or draw a second chart. Every chart has
+a tooltip; a legend appears from two series up.
+
+## Bar chart
+
+`ui.BarChart` compares magnitudes by category. `labels=True` writes the
+value at the end of each bar; `format` chooses `number`, `integer`,
+`percent` or `currency`.
+
+```python live
+MONTHS = [
+    {"month": "Jan", "sales": 42, "costs": 31, "visits": 1200},
+    {"month": "Feb", "sales": 48, "costs": 30, "visits": 1350},
+    {"month": "Mar", "sales": 55, "costs": 34, "visits": 1600},
+    {"month": "Apr", "sales": 51, "costs": 35, "visits": 1500},
+    {"month": "May", "sales": 63, "costs": 38, "visits": 1900},
+    {"month": "Jun", "sales": 70, "costs": 41, "visits": 2100},
+]
+
+ui.BarChart(MONTHS, x="month", y={"sales": "Sales", "costs": "Costs"}, labels=True, height=220)
+```
+
+## Stacked, percent and horizontal
+
+`stacked=True` adds the series up; `stacked="percent"` draws every bar full
+and shows each series' share. `horizontal=True` turns the chart on its side,
+which suits long category names.
+
+```python live
+SHARE = [
+    {"channel": "Direct", "new": 120, "returning": 340},
+    {"channel": "Search engines", "new": 410, "returning": 190},
+    {"channel": "Social media", "new": 230, "returning": 80},
+    {"channel": "Newsletter", "new": 40, "returning": 260},
+]
+
+ui.Grid(
+    ui.BarChart(SHARE, x="channel", y=["new", "returning"], stacked=True, height=200),
+    ui.BarChart(
+        SHARE, x="channel", y=["new", "returning"], stacked="percent", horizontal=True, height=200
+    ),
+    cols={"sm": 1, "md": 2},
+)
+```
+
+## Long rows
+
+Data often arrives with one row per series and category. `by` names the
+column that holds the series name, and `y` the one column with the values;
+Python pivots the rows before they leave.
+
+```python live
+REGIONS = [
+    {"quarter": "Q1", "region": "North", "orders": 120},
+    {"quarter": "Q1", "region": "South", "orders": 90},
+    {"quarter": "Q2", "region": "North", "orders": 140},
+    {"quarter": "Q2", "region": "South", "orders": 110},
+    {"quarter": "Q3", "region": "North", "orders": 135},
+    {"quarter": "Q3", "region": "South", "orders": 150},
+]
+
+ui.BarChart(REGIONS, x="quarter", y="orders", by="region", height=200)
+```
+
+## A diverging scale
+
+When the series are steps of one ordered scale, `diverging=True` draws them
+to either side of the midpoint, coloured from one hue through grey to
+another instead of five unrelated colours. The middle step, when there is
+one, straddles the axis.
+
+```python live
+WEATHER = [
+    {"month": "Mar", "freezing": 4, "cold": 12, "mild": 10, "warm": 5, "hot": 0},
+    {"month": "Apr", "freezing": 1, "cold": 8, "mild": 14, "warm": 7, "hot": 0},
+    {"month": "May", "freezing": 0, "cold": 3, "mild": 12, "warm": 13, "hot": 3},
+    {"month": "Jun", "freezing": 0, "cold": 1, "mild": 8, "warm": 15, "hot": 6},
+]
+
+ui.BarChart(
+    WEATHER,
+    x="month",
+    y=["freezing", "cold", "mild", "warm", "hot"],
+    diverging=True,
+    horizontal=True,
+    height=200,
+)
+```
+
+## Emphasis
+
+Often one series is the point and the rest are context. `emphasis` names
+the one that keeps its colour; the others recede into grey.
+
+```python live
+ui.LineChart(
+    MONTHS,
+    x="month",
+    y={"sales": "Sales", "costs": "Costs"},
+    emphasis="sales",
+    labels=True,
+    height=200,
+)
+```
+
+## Line and area
+
+`ui.LineChart` draws a trend over an ordered x. `curve=True` smooths it,
+`dots=True` marks the points, and `labels=True` names each line at its end
+rather than numbering every point. `ui.AreaChart` fills under the line and
+`stacked=True` adds the series up.
+
+```python live
+ui.Grid(
+    ui.LineChart(MONTHS, x="month", y="visits", curve=True, dots=True, height=200),
+    ui.AreaChart(
+        MONTHS, x="month", y={"sales": "Sales", "costs": "Costs"}, stacked=True, height=200
+    ),
+    cols={"sm": 1, "md": 2},
+)
+```
+
+## Clicks
+
+`on_click` receives the point: its `x`, the `series` key and `value` for a
+bar, and `values` for every series at that x. On a line or area chart the
+click lands on the nearest x.
+
+```python live
+from pydantic import BaseModel
+
+
+class Picked(BaseModel):
+    text: str = "Click a bar."
+
+
+def picked(s, point):
+    state(Picked).text = f"{point['series']} in {point['x']}: {point['value']}"
+
+
+def example(s):
+    return ui.Stack(
+        ui.BarChart(MONTHS, x="month", y=["sales", "costs"], on_click=picked, height=180),
+        ui.Text(state(Picked).text, variant="muted"),
+        gap=2,
+    )
+```
+
+## Stat
+
+`ui.Stat` is the headline number. `delta` is the change, drawn with its
+direction; `good="down"` says a fall is the welcome move, for costs or
+errors. `trend` draws a sparkline whose last point is the current one.
+
+```python live
+ui.Grid(
+    ui.Stat(label="Revenue", value="€ 70k", delta=0.11, trend=[42, 48, 55, 51, 63, 70]),
+    ui.Stat(label="Costs", value="€ 41k", delta=0.08, good="down", trend=[31, 30, 34, 35, 38, 41]),
+    ui.Stat(label="Open tickets", value="12", delta=-3, delta_format="number", good="down"),
+    cols={"sm": 1, "md": 3},
+)
+```
+
+## Plotly and other libraries
+
+The catalogue draws the forms most pages need. For anything else, an app
+brings its own library through a custom component. Plotly is the common
+case; the same shape works for any library that draws into a div.
+
+The page may only run scripts from its own origin, so the library is served
+by the app itself: put `plotly.min.js` in the app's `public/` folder. The
+custom component loads it once, then hands the figure to Plotly whenever
+the props change.
+
+```jsx
+// components/Plotly.jsx
+import { useEffect, useRef } from "react";
+
+let loading = null;
+
+function loadPlotly() {
+  if (window.Plotly) return Promise.resolve(window.Plotly);
+  loading ??= new Promise((resolve, reject) => {
+    const script = document.createElement("script");
+    script.src = `${window.__mw.base || ""}/public/plotly.min.js`;
+    script.onload = () => resolve(window.Plotly);
+    script.onerror = () => reject(new Error("plotly.min.js did not load"));
+    document.head.appendChild(script);
+  });
+  return loading;
+}
+
+export default function Plotly({ props }) {
+  const ref = useRef(null);
+  useEffect(() => {
+    let alive = true;
+    loadPlotly().then((Plotly) => {
+      if (!alive || !ref.current) return;
+      const { data, layout } = props.figure;
+      Plotly.react(ref.current, data, layout, { responsive: true, displaylogo: false });
+    });
+    return () => {
+      alive = false;
+    };
+  }, [props.figure]);
+  useEffect(() => () => window.Plotly?.purge(ref.current), []);
+  return <div ref={ref} style={{ width: "100%", height: props.height ?? 320 }} />;
+}
+```
+
+On the Python side a figure is built as usual and sent as JSON. A
+transparent background lets the page's own colours through in both
+schemes; the figure's own colours are Plotly's, not the theme's. Plotly
+Express wants pandas installed next to it; graph objects need nothing.
+
+```python
+import json
+
+import plotly.express as px
+
+def example(s):
+    fig = px.line(MONTHS, x="month", y="visits", markers=True)
+    fig.update_layout(
+        paper_bgcolor="rgba(0,0,0,0)",
+        plot_bgcolor="rgba(0,0,0,0)",
+        margin={"l": 0, "r": 0, "t": 0, "b": 0},
+    )
+    return ui.Custom("Plotly", props={"figure": json.loads(fig.to_json()), "height": 300})
+```
+
+A click on a bar or a point can come back the same way as in the Hello
+component: register a Plotly event on the div and call `emit`.
+
+## Images from Python
+
+Any library that renders to SVG or PNG works without a component at all:
+the session keeps the bytes and `ui.Image` shows them. No tooltip, no theme
+awareness, no script in the browser.
+
+```python
+import io
+
+import matplotlib.pyplot as plt
+
+def example(s):
+    fig, ax = plt.subplots(figsize=(6, 3))
+    ax.plot([m["month"] for m in MONTHS], [m["visits"] for m in MONTHS])
+    out = io.BytesIO()
+    fig.savefig(out, format="svg", transparent=True)
+    plt.close(fig)
+    return ui.Image(src=s.files.add(out.getvalue(), name="visits.svg"), alt="Visits per month")
+```