millwork 0.1.0__py3-none-any.whl

millwork/manual/pages/components/feedback.md

@@ -0,0 +1,212 @@
+---
+title: Feedback
+order: 3
+---
+
+# Feedback
+
+Telling the user what is going on: alerts, toasts, dialogs, progress and the
+empty and loading states.
+
+## Alert
+
+`ui.Alert` is a banner with a `title`, a `description`, a `tone`, an `icon`,
+`actions` and, with `dismissable`, a close button that fires `on_dismiss`.
+
+```python live
+ui.Stack(
+    ui.Alert(title="Heads up", description="Something to know, with the default tone."),
+    ui.Alert(title="Saved", description="The project was saved.", tone="success"),
+    ui.Alert(title="Check the dates", description="The end is before the start.", tone="warning"),
+    ui.Alert(
+        title="Upload failed",
+        description="The file was larger than 50 MB.",
+        tone="destructive",
+        actions=[ui.Button("Try again", size="sm", on_click=lambda s, _: s.toast("Retrying"))],
+    ),
+    ui.Alert(title="Dismiss me", dismissable=True, on_dismiss=lambda s, _: s.toast("Dismissed")),
+    gap=3,
+)
+```
+
+## Toast
+
+A toast is not a component but a command: `s.toast(message, tone=, title=)`
+from any handler. `action=(label, handler)` puts a button on it that runs
+the handler once.
+
+```python live
+ui.Row(
+    ui.Button("Plain", variant="outline", on_click=lambda s, _: s.toast("A plain toast.")),
+    ui.Button(
+        "Success", variant="outline", on_click=lambda s, _: s.toast("Saved.", tone="success")
+    ),
+    ui.Button(
+        "With title",
+        variant="outline",
+        on_click=lambda s, _: s.toast("Three rows changed.", title="Imported"),
+    ),
+    ui.Button(
+        "With action",
+        variant="outline",
+        on_click=lambda s, _: s.toast(
+            "Deleted.", tone="destructive", action=("Undo", lambda s, _: s.toast("Restored."))
+        ),
+    ),
+    gap=2,
+    wrap=True,
+)
+```
+
+## Dialog
+
+`ui.Dialog` is open when state says so. It has a `title`, a `description`, a
+`footer`, a `size` from `sm` to `full`, and `on_close` fires when the user
+dismisses it, so the handler sets state and it closes.
+
+```python live
+from pydantic import BaseModel
+
+
+class Modal(BaseModel):
+    open: bool = False
+
+
+def example(s):
+    st = state(Modal)
+
+    def close(s, _):
+        st.open = False
+
+    return ui.Row(
+        ui.Button("Open a dialog", on_click=lambda s, _: setattr(st, "open", True)),
+        ui.Dialog(
+            ui.Text("Dialogs hold any children. This one has a footer with a button."),
+            open=st.open,
+            title="A dialog",
+            description="Close it with the button, the cross, Escape or a click outside.",
+            footer=ui.Button("Done", on_click=close),
+            on_close=close,
+        ),
+    )
+```
+
+## Confirm and ask
+
+Two session calls wait for the user from inside a handler. `await s.confirm(
+title, description=, destructive=)` shows a dialog and returns True or
+False. `await s.ask(component)` shows any component and returns what it
+submits: a `Form` answers with its validated model, a closed dialog answers
+None.
+
+```python live
+from pydantic import BaseModel
+
+
+class Asked(BaseModel):
+    answer: str = "nothing yet"
+
+
+async def confirm(s, _):
+    st = state(Asked)
+    ok = await s.confirm("Archive the project?", "You can restore it later.", destructive=True)
+    st.answer = "archived" if ok else "kept"
+
+
+def example(s):
+    st = state(Asked)
+    return ui.Row(
+        ui.Button("Archive", variant="outline", on_click=confirm),
+        ui.Text(f"Result: {st.answer}", variant="muted"),
+        gap=3,
+    )
+```
+
+## Sheet
+
+`ui.Sheet` slides a panel in from a `side`. Like a dialog it is open when
+state says so and `on_close` lets the handler close it.
+
+```python live
+from pydantic import BaseModel
+
+
+class Panel(BaseModel):
+    open: bool = False
+
+
+def example(s):
+    st = state(Panel)
+    return ui.Row(
+        ui.Button(
+            "Open settings", variant="outline", on_click=lambda s, _: setattr(st, "open", True)
+        ),
+        ui.Sheet(
+            ui.Switch(label="Email summaries", default_checked=True),
+            ui.Select(options=["Fast", "Thorough"], default="Fast"),
+            open=st.open,
+            side="right",
+            title="Settings",
+            description="A sheet holding a few controls.",
+            on_close=lambda s, _: setattr(st, "open", False),
+        ),
+    )
+```
+
+## Spinner and Skeleton
+
+`ui.Spinner` shows work in progress with an optional `label`. `ui.Skeleton`
+stands in for content still loading, shaped like `text`, a `card` or a
+`table`.
+
+```python live
+ui.Stack(
+    ui.Row(
+        ui.Spinner(size="sm"),
+        ui.Spinner(),
+        ui.Spinner(size="lg", label="Loading the project"),
+        gap=6,
+    ),
+    ui.Grid(
+        ui.Skeleton(rows=3),
+        ui.Skeleton(shape="card"),
+        ui.Skeleton(shape="table", rows=4),
+        cols={"sm": 1, "md": 3},
+    ),
+    gap=6,
+)
+```
+
+## Empty
+
+`ui.Empty` is the state before there is anything: a `title`, a
+`description`, an `icon` and an `action`.
+
+```python live
+ui.Empty(
+    title="No projects yet",
+    description="Create one to start, or import from a file.",
+    icon="inbox",
+    action=ui.Button("New project", on_click=lambda s, _: s.toast("Creating")),
+)
+```
+
+## Progress and Steps
+
+`ui.Progress` is a bar for a `value` from 0 to 1 with a `label` and a
+`description`, or for a running task (see the Tasks chapter). `ui.Steps`
+draws a list of `mw.Step` items with their status.
+
+```python live
+ui.Stack(
+    ui.Progress(value=0.65, label="Importing", description="130 of 200 rows"),
+    ui.Steps(
+        items=[
+            mw.Step(id="read", label="Read the document", status="done", note="12 pages"),
+            mw.Step(id="find", label="Find the headings", status="running"),
+            mw.Step(id="route", label="Add routing", status="pending"),
+        ]
+    ),
+    gap=6,
+)
+```

millwork/manual/pages/components/files.md

@@ -0,0 +1,194 @@
+---
+title: Files
+order: 7
+---
+
+# Files
+
+Files belong to the session. An upload becomes a `mw.FileRef` with an id, a
+name, a size and a type; the bytes live on the server for as long as the
+session does and travel to the browser over the session's own socket, so a
+file has no URL and needs no signing.
+
+## FileUpload
+
+`ui.FileUpload` is a drop zone (`dropzone=False` makes it a button). `accept`
+lists extensions, `multiple` and `max_files` allow more than one,
+`max_size_mb` caps each. `on_upload` receives the `FileRef`s; `on_reject`
+receives `{name, reason}` for a file that was refused.
+
+```python live
+from pydantic import BaseModel
+
+
+class Uploads(BaseModel):
+    files: list = []
+
+
+async def uploaded(s, refs):
+    state(Uploads).files.extend(refs)
+
+
+def example(s):
+    st = state(Uploads)
+    return ui.Stack(
+        ui.FileUpload(
+            accept=[".txt", ".md", ".png", ".pdf"],
+            multiple=True,
+            max_files=3,
+            max_size_mb=5,
+            on_upload=uploaded,
+            on_reject=lambda s, r: s.toast(f"{r['name']}: {r['reason']}", tone="warning"),
+        ),
+        *(ui.FileCard(file=f, key=f.id) for f in st.files),
+        gap=3,
+    )
+```
+
+## FileCard
+
+`ui.FileCard` shows a file with its size and kind, an optional `meta` line,
+a `status` and `actions`. Given a `FileRef`, Open shows the bytes in a new
+tab; given a `url`, it links there.
+
+```python live
+from pydantic import BaseModel
+
+
+class Held(BaseModel):
+    ref: object = None
+
+
+def example(s):
+    st = state(Held)
+    if st.ref is None:
+        st.ref = s.files.add("Notes for the pilot.\n", name="notes.txt")
+    return ui.Stack(
+        ui.FileCard(
+            file=st.ref,
+            meta="added just now",
+            actions=[ui.MenuItem(id="remove", label="Remove", icon="trash-2", destructive=True)],
+            on_action=lambda s, a: s.toast(f"{a} requested"),
+        ),
+        ui.FileCard(
+            name="report.pdf", size=482_000, kind="pdf", status="loading", meta="converting"
+        ),
+        ui.FileCard(
+            name="broken.csv", size=12, kind="text", status="error", meta="could not parse"
+        ),
+        gap=2,
+    )
+```
+
+## Image and Pdf
+
+`ui.Image` and `ui.Pdf` take a `FileRef` or an outside URL. An image has a
+`size` and a `fit`; a PDF a `page` and a `height`. The browser's own viewer
+shows the PDF, so a form or a link inside it looks like part of the app:
+show files the app made or the person uploaded themselves, not documents
+from strangers.
+
+```python live
+import struct, zlib
+
+from pydantic import BaseModel
+
+
+def png(w=48, h=48, rgb=(10, 126, 164)) -> bytes:
+    raw = b"".join(b"\x00" + bytes(rgb) * w for _ in range(h))
+
+    def chunk(tag, data):
+        return struct.pack(">I", len(data)) + tag + data + struct.pack(">I", zlib.crc32(tag + data))
+
+    return (
+        b"\x89PNG\r\n\x1a\n"
+        + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
+        + chunk(b"IDAT", zlib.compress(raw))
+        + chunk(b"IEND", b"")
+    )
+
+
+class Pic(BaseModel):
+    ref: object = None
+
+
+def example(s):
+    st = state(Pic)
+    if st.ref is None:
+        st.ref = s.files.add(png(), name="square.png")
+    return ui.Row(
+        ui.Image(src=st.ref, alt="A teal square", size="sm"),
+        ui.Image(
+            src="https://picsum.photos/seed/millwork/160/96",
+            alt="An outside image",
+            size="sm",
+            fit="cover",
+        ),
+        gap=4,
+    )
+```
+
+A PDF the session holds shows the same way, from its bytes:
+
+```python live
+from pydantic import BaseModel
+
+
+def tiny_pdf(text: str) -> bytes:
+    stream = f"BT /F1 24 Tf 40 120 Td ({text}) Tj ET".encode()
+    objs = [
+        b"<< /Type /Catalog /Pages 2 0 R >>",
+        b"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        b"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 320 180] /Contents 4 0 R "
+        b"/Resources << /Font << /F1 5 0 R >> >> >>",
+        b"<< /Length " + str(len(stream)).encode() + b" >>\nstream\n" + stream + b"\nendstream",
+        b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+    ]
+    out = b"%PDF-1.4\n"
+    offsets = []
+    for n, body in enumerate(objs, 1):
+        offsets.append(len(out))
+        out += f"{n} 0 obj\n".encode() + body + b"\nendobj\n"
+    xref = len(out)
+    out += f"xref\n0 {len(objs) + 1}\n0000000000 65535 f \n".encode()
+    out += b"".join(f"{o:010d} 00000 n \n".encode() for o in offsets)
+    out += f"trailer\n<< /Size {len(objs) + 1} /Root 1 0 R >>\nstartxref\n{xref}\n%%EOF\n".encode()
+    return out
+
+class Doc(BaseModel):
+    ref: object = None
+
+def example(s):
+    st = state(Doc)
+    if st.ref is None:
+        st.ref = s.files.add(tiny_pdf("Hello from millwork"), name="hello.pdf")
+    return ui.Pdf(src=st.ref, height="14rem")
+```
+
+## Download
+
+`ui.Download` is a button that saves a file. `content` is bytes, text, a
+path, a callable that makes any of those on click, or a `FileRef`, which
+saves straight away without a round trip. `s.download(filename, content)`
+does the same from a handler, without a button.
+
+```python live
+def report() -> str:
+    return "name,score\nAda,0.92\nGrace,0.88\n"
+
+
+ui.Row(
+    ui.Download("Text", filename="hello.txt", content="Hello from millwork.\n"),
+    ui.Download(
+        "Made on click", filename="report.csv", content=report, mime="text/csv", variant="primary"
+    ),
+    ui.Button(
+        "From a handler",
+        variant="outline",
+        icon="download",
+        on_click=lambda s, _: s.download("pushed.txt", "Sent by a handler.\n"),
+    ),
+    gap=2,
+    wrap=True,
+)
+```

millwork/manual/pages/components/form.md

@@ -0,0 +1,135 @@
+---
+title: Form
+order: 6
+---
+
+# Form
+
+`ui.Form` renders a Pydantic model as fields and hands `on_submit` a
+validated instance. Types choose the controls: `str` an input, `int` and
+`float` a number, `bool` a switch, `Literal` and `Enum` a select, `date` a
+date picker, a nested model a fieldset, a list of models a repeatable list.
+Validation errors land on the field they concern.
+
+## From a model
+
+`Field(title=, description=, examples=)` give a field its label, its help
+text and its placeholder. Constraints such as `min_length`, `ge` and `le`
+become the control's limits and the validation.
+
+```python live
+import datetime as dt
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class Project(BaseModel):
+    title: str = Field(title="Title", examples=["Q1 report"], min_length=3)
+    language: Literal["en", "nl", "de"] = Field("en", title="Language")
+    starts: dt.date | None = Field(None, title="Starts")
+    count: int = Field(3, ge=1, le=10, title="Copies", description="Between one and ten.")
+    enabled: bool = Field(True, title="Active")
+    notes: str | None = Field(None, title="Notes", max_length=500)
+
+
+class Saved(BaseModel):
+    last: str = "nothing yet"
+
+
+async def save(s, project: Project):
+    state(Saved).last = f"{project.title} ({project.language}, {project.count})"
+
+
+def example(s):
+    return ui.Stack(
+        ui.Form(Project, on_submit=save, layout=2),
+        ui.Text(f"Saved: {state(Saved).last}", variant="muted"),
+        gap=4,
+    )
+```
+
+## Labels and overrides
+
+`labels` maps a field's pointer, or its name, to a `label`, `help`,
+`placeholder` and `choices`, so the model stays free of interface copy.
+`overrides` maps a pointer to any spec key: a `widget`, `min`, `max`,
+`step`, `rows`. `fields` picks a subset in order.
+
+```python live
+from pydantic import BaseModel
+
+
+class Settings(BaseModel):
+    name: str = ""
+    level: int = 1
+    mood: str = "ok"
+    tags: list[Literal["a", "b", "c"]] = []
+
+
+ui.Form(
+    Settings,
+    fields=["name", "mood", "level", "tags"],
+    labels={"name": {"label": "Display name", "help": "Shown to other users."}},
+    overrides={
+        "/mood": {"choices": [("ok", "Fine"), ("bad", "Not fine")]},
+        "/level": {"widget": "slider", "min": 0, "max": 5},
+        "/tags": {"widget": "multiselect"},
+    },
+    on_submit=lambda s, v: s.toast(f"{v.name or 'someone'} is {v.mood}"),
+)
+```
+
+## Rejecting a valid draft
+
+A handler that finds something wrong raises `ui.FormIssues` with a list of
+`(pointer, message)` pairs; the form shows each at its field and keeps the
+draft.
+
+```python live
+from pydantic import BaseModel, Field
+
+
+class Signup(BaseModel):
+    email: str = Field(title="Email")
+    handle: str = Field(title="Handle", min_length=2)
+
+
+TAKEN = {"ada", "grace"}
+
+
+async def register(s, v: Signup):
+    if v.handle.lower() in TAKEN:
+        raise ui.FormIssues([("/handle", "That handle is taken.")])
+    s.toast(f"Welcome, {v.handle}.", tone="success")
+
+
+ui.Form(Signup, on_submit=register, submit="Register", cancel="Clear")
+```
+
+## Submitting from outside
+
+`submit=None` hides the form's own button; a `ui.Button(form=key)` anywhere
+on the page submits the form with that key.
+
+```python live
+from pydantic import BaseModel, Field
+
+
+class Quick(BaseModel):
+    query: str = Field("", title="Query")
+
+
+ui.Row(
+    ui.Form(
+        Quick,
+        key="quick",
+        submit=None,
+        on_submit=lambda s, v: s.toast(f"Searching {v.query!r}"),
+        cls="grow",
+    ),
+    ui.Button("Go", form="quick", icon="search"),
+    align="end",
+    gap=3,
+)
+```