millwork 0.1.0__py3-none-any.whl

millwork/manual/pages/components/inputs.md

@@ -0,0 +1,360 @@
+---
+title: Inputs
+order: 2
+---
+
+# Inputs
+
+Controls the user types into or picks from. Each one tells Python what
+happened through an `on_change` handler, and most can be owned by either side.
+
+## Who owns the value
+
+A control with `default=` keeps its own value in the browser and reports
+changes; a control with `value=` shows what Python says and only changes when
+Python changes it. Give one or the other, never both. Pass `value` when the
+page needs to read or reset the control, `default` when it does not.
+
+```python live
+from pydantic import BaseModel
+
+
+class Owner(BaseModel):
+    text: str = ""
+
+
+def example(s):
+    st = state(Owner)
+    return ui.Stack(
+        ui.Input(
+            value=st.text,
+            placeholder="Python owns this one",
+            on_change=lambda s, v: setattr(st, "text", v),
+        ),
+        ui.Row(
+            ui.Text(f"Python sees: {st.text!r}", variant="muted"),
+            ui.Button(
+                "Clear from Python",
+                size="sm",
+                variant="outline",
+                on_click=lambda s, _: setattr(st, "text", ""),
+            ),
+            gap=3,
+        ),
+        ui.Input(
+            default="The browser owns this one", on_change=lambda s, v: s.toast(f"Changed to {v!r}")
+        ),
+        gap=3,
+    )
+```
+
+## Button
+
+`ui.Button` takes a label, a `variant`, a `size`, an `icon` (before the label,
+or after with `icon_position="end"`), `loading`, `disabled` and a `tooltip`.
+`confirm="..."` asks before the handler runs. `form="key"` submits the Form
+with that key from anywhere on the page.
+
+```python live
+ui.Stack(
+    ui.Row(
+        ui.Button("Primary"),
+        ui.Button("Secondary", variant="secondary"),
+        ui.Button("Outline", variant="outline"),
+        ui.Button("Ghost", variant="ghost"),
+        ui.Button("Link", variant="link"),
+        ui.Button("Destructive", variant="destructive"),
+        gap=2,
+        wrap=True,
+    ),
+    ui.Row(
+        ui.Button("Small", size="sm", variant="outline"),
+        ui.Button("Medium", variant="outline"),
+        ui.Button("Large", size="lg", variant="outline"),
+        ui.Button("With icon", icon="download", variant="outline"),
+        ui.Button("Icon after", icon="arrow-right", icon_position="end", variant="outline"),
+        gap=2,
+        wrap=True,
+    ),
+    ui.Row(
+        ui.Button("Loading", loading=True),
+        ui.Button("Disabled", disabled=True),
+        ui.Button("With tooltip", tooltip="Explains itself on hover", variant="outline"),
+        ui.Button(
+            "Delete",
+            variant="destructive",
+            confirm="Delete this for good?",
+            on_click=lambda s, _: s.toast("Deleted.", tone="destructive"),
+        ),
+        gap=2,
+        wrap=True,
+    ),
+    gap=3,
+)
+```
+
+## ButtonGroup
+
+`ui.ButtonGroup` joins buttons into one control.
+
+```python live
+ui.ButtonGroup(
+    ui.Button("Day", variant="outline", on_click=lambda s, _: s.toast("Day")),
+    ui.Button("Week", variant="outline", on_click=lambda s, _: s.toast("Week")),
+    ui.Button("Month", variant="outline", on_click=lambda s, _: s.toast("Month")),
+)
+```
+
+## Input
+
+`ui.Input` is a single line of text. `kind` chooses the keyboard and
+validation (`text`, `password`, `email`, `number`, `search`, `url`),
+`prefix_icon` and `suffix` decorate it, `clearable` adds a clear button.
+`on_change` fires after a pause in typing (`debounce_ms`, 250 by default);
+`on_submit` fires on Enter.
+
+```python live
+ui.Stack(
+    ui.Input(
+        placeholder="Search",
+        prefix_icon="search",
+        kind="search",
+        clearable=True,
+        on_submit=lambda s, v: s.toast(f"Searching for {v!r}"),
+    ),
+    ui.Input(placeholder="Distance", suffix="km", kind="number"),
+    ui.Input(placeholder="Password", kind="password"),
+    ui.Input(value="Read only", readonly=True),
+    ui.Input(value="Disabled", disabled=True),
+    gap=3,
+)
+```
+
+## Textarea
+
+`ui.Textarea` is several lines. `rows` sets the starting height, `autosize`
+grows it with the text, `max_length` caps it. Ctrl+Enter submits.
+
+```python live
+ui.Textarea(
+    placeholder="Notes. Ctrl+Enter submits.",
+    rows=3,
+    autosize=True,
+    max_length=200,
+    on_submit=lambda s, v: s.toast(f"{len(v)} characters"),
+)
+```
+
+## NumberInput
+
+`ui.NumberInput` takes a number within `min` and `max`, stepping by `step`,
+with an optional `suffix`. It reports on blur and on Enter.
+
+```python live
+ui.Row(
+    ui.NumberInput(default=3, min=1, max=10, step=1, suffix="items"),
+    ui.NumberInput(default=0.5, min=0, max=1, step=0.1, placeholder="0 to 1"),
+    gap=4,
+)
+```
+
+## Slider
+
+`ui.Slider` picks a number by dragging. `marks` labels points under the
+track; `show_value` prints the value beside it. It reports on release.
+
+```python live
+ui.Stack(
+    ui.Slider(default=40, min=0, max=100, step=10),
+    ui.Slider(default=0.3, min=0, max=1, step=0.1, marks={0: "cold", 0.5: "warm", 1: "hot"}),
+    gap=6,
+)
+```
+
+## Switch and Checkbox
+
+Both are a yes or no with a `label` and an optional `description`. Use
+`checked` or `default_checked`.
+
+```python live
+ui.Stack(
+    ui.Switch(
+        label="Email me a summary", description="Once a day, at eight.", default_checked=True
+    ),
+    ui.Checkbox(
+        label="I have read the terms", on_change=lambda s, v: s.toast("Read" if v else "Unread")
+    ),
+    ui.Checkbox(label="Disabled", disabled=True),
+    gap=3,
+)
+```
+
+## Select
+
+`ui.Select` picks one from `options`. Options are strings, `(value, label)`
+pairs, or `ui.Option` objects with a `description`, an `icon`, `disabled` and a
+`group`. `clearable` allows no choice.
+
+```python live
+ui.Row(
+    ui.Select(options=["Fast", "Balanced", "Thorough"], default="Balanced"),
+    ui.Select(
+        options=[
+            ui.Option(value="nl", label="Dutch", group="Europe"),
+            ui.Option(value="de", label="German", group="Europe"),
+            ui.Option(value="ja", label="Japanese", group="Asia", disabled=True),
+        ],
+        placeholder="Language",
+        clearable=True,
+    ),
+    gap=4,
+)
+```
+
+## Combobox
+
+`ui.Combobox` is a Select with a search box. With `options` it filters in the
+browser; with `on_search` Python answers each search over the session's
+socket, without a render. `allow_custom=True` lets typed text that matches
+nothing be the value.
+
+```python live
+PEOPLE = [("ada", "Ada Lovelace"), ("grace", "Grace Hopper"), ("edsger", "Edsger Dijkstra")]
+
+
+async def search(s, query: str):
+    return [p for p in PEOPLE if query.lower() in p[1].lower()]
+
+
+def example(s):
+    return ui.Row(
+        ui.Combobox(options=PEOPLE, placeholder="Filters in the browser"),
+        ui.Combobox(on_search=search, placeholder="Asks Python as you type", clearable=True),
+        ui.Combobox(options=["red", "green"], allow_custom=True, placeholder="Or type your own"),
+        gap=4,
+        wrap=True,
+    )
+```
+
+## MultiSelect
+
+`ui.MultiSelect` picks several, shown as chips. `max` stops further picks.
+
+```python live
+ui.MultiSelect(
+    options=["Alpha", "Beta", "Gamma", "Delta"],
+    default=["Alpha"],
+    max=3,
+    placeholder="Pick up to three",
+)
+```
+
+The chips keep the order they were picked in, and that is the order Python
+receives. `sortable=True` lets the order be changed afterwards: drag a chip
+to its place, or focus it and press Alt with an arrow key. In a form, the
+same hint on the field (`json_schema_extra={"sortable": True}`) does it.
+
+```python live
+from pydantic import BaseModel
+
+
+class Pipeline(BaseModel):
+    steps: list[str] = ["Collect", "Clean", "Model"]
+
+
+def reorder(s, steps):
+    state(Pipeline).steps = steps
+
+
+def example(s):
+    st = state(Pipeline)
+    return ui.Stack(
+        ui.MultiSelect(
+            options=["Collect", "Clean", "Model", "Report", "Share"],
+            value=st.steps,
+            sortable=True,
+            on_change=reorder,
+        ),
+        ui.Text(" then ".join(st.steps) or "Nothing yet.", variant="muted"),
+        gap=2,
+    )
+```
+
+## RadioGroup, CheckboxGroup and ToggleGroup
+
+Three ways to choose from a short list: one with radios, several with
+checkboxes, or either with pressed buttons (`multiple=True` for several).
+
+```python live
+ui.Stack(
+    ui.RadioGroup(options=["Small", "Medium", "Large"], default="Medium", orientation="horizontal"),
+    ui.CheckboxGroup(
+        options=[
+            ui.Option(value="a", label="Alerts", description="Only the important ones"),
+            ui.Option(value="d", label="Digest"),
+        ],
+        default=["a"],
+    ),
+    ui.ToggleGroup(
+        options=[("left", "Left"), ("center", "Center"), ("right", "Right")], default="left"
+    ),
+    ui.ToggleGroup(
+        options=["Bold", "Italic", "Underline"], multiple=True, default=["Bold"], size="sm"
+    ),
+    gap=4,
+)
+```
+
+## DatePicker
+
+`ui.DatePicker` picks a date from a calendar; `range=True` picks a span.
+Values are ISO strings on the wire, `date` objects are accepted. `min` and
+`max` bound the pickable days.
+
+```python live
+ui.Row(
+    ui.DatePicker(
+        placeholder="A day", clearable=True, on_change=lambda s, v: s.toast(f"Picked {v}")
+    ),
+    ui.DatePicker(range=True, placeholder="A span", min="2026-01-01"),
+    gap=4,
+    wrap=True,
+)
+```
+
+## DropdownMenu
+
+`ui.DropdownMenu` opens a menu behind a `trigger` button. Items carry an
+`icon`, `disabled`, `destructive` and `separator_after`; `on_select` receives
+the chosen id.
+
+```python live
+ui.DropdownMenu(
+    trigger=ui.Button("Actions", icon="more-horizontal", variant="outline"),
+    items=[
+        ui.MenuItem(id="rename", label="Rename", icon="pencil"),
+        ui.MenuItem(id="copy", label="Duplicate", icon="copy", separator_after=True),
+        ui.MenuItem(id="delete", label="Delete", icon="trash-2", destructive=True),
+    ],
+    on_select=lambda s, item: s.toast(f"Chose {item}"),
+)
+```
+
+## Field
+
+`ui.Field` puts a `label`, `help` and an `error` around one control, for a
+form built by hand rather than from a model.
+
+```python live
+from pydantic import Field
+
+ui.Grid(
+    ui.Field(ui.Input(placeholder="Ada"), label="Name", required=True, help="As on your badge."),
+    ui.Field(
+        ui.Input(placeholder="ada@example.com", kind="email"),
+        label="Email",
+        error="This address bounced.",
+    ),
+    cols={"sm": 1, "md": 2},
+)
+```

millwork/manual/pages/components/layout.md

@@ -0,0 +1,154 @@
+---
+title: Layout
+order: 0
+---
+
+# Layout
+
+A page is a tree. Layout components arrange their children; they carry no
+state and emit no events. Children are positional, so a page reads like the
+screen it makes.
+
+## Page
+
+`ui.Page` is the root of every page. It is as high as the viewport, scrolls its
+body under a fixed header, and lays itself out around a `ui.Sidebar` child when
+there is one. Give it a `title` for the browser tab and a `header` for the app
+bar; `padding=False` lets a child such as `ui.Chat` fill it edge to edge.
+
+This manual is a `Page` with a `Sidebar`, so it is not shown inline.
+
+## Stack and Row
+
+`ui.Stack` lays children out vertically, `ui.Row` horizontally. Both take
+`gap`, `align` and `justify`; a `Row` can `wrap`.
+
+```python live
+ui.Stack(
+    ui.Row(ui.Badge("one"), ui.Badge("two"), ui.Badge("three"), gap=2),
+    ui.Row(ui.Button("Left", variant="outline"), ui.Button("Right"), justify="between"),
+    ui.Row(ui.Text("Centred", variant="muted"), justify="center"),
+    gap=4,
+)
+```
+
+`divided=True` draws a rule between the children of a `Stack`.
+
+```python live
+ui.Stack(ui.Text("First"), ui.Text("Second"), ui.Text("Third"), divided=True, gap=2)
+```
+
+## Grid
+
+`ui.Grid` places children in columns. `cols` is a number, or a mapping with
+`sm`, `md` and `lg` for the breakpoints at which the count changes.
+
+```python live
+ui.Grid(
+    ui.Stat(label="Sessions", value="1,204", hint="today"),
+    ui.Stat(label="Replies", value="3.8 s", hint="median", tone="success"),
+    ui.Stat(label="Errors", value="2", tone="destructive"),
+    cols={"sm": 1, "md": 3},
+)
+```
+
+## Card
+
+`ui.Card` frames content with an optional `title`, `description` and `footer`.
+`tone` colours its border; `on_click` makes the whole card a target.
+
+```python live
+ui.Grid(
+    ui.Card(
+        ui.Text("The body of the card goes here, as children."),
+        title="A card",
+        description="With a description under the title.",
+        footer=ui.Button("Action", size="sm"),
+    ),
+    ui.Card(
+        ui.Text("Clicking me toasts."),
+        title="Clickable",
+        tone="primary",
+        on_click=lambda s, _: s.toast("The card was clicked."),
+    ),
+    cols={"sm": 1, "md": 2},
+)
+```
+
+## Separator
+
+A rule between things, with an optional `label`.
+
+```python live
+ui.Stack(
+    ui.Text("Above"),
+    ui.Separator(),
+    ui.Text("Between, with a label below"),
+    ui.Separator(label="or"),
+    ui.Text("Below"),
+    gap=3,
+)
+```
+
+## Split
+
+`ui.Split` puts its children in resizable panes. `sizes` are the starting
+percentages, `min_sizes` the smallest each may be dragged to, and
+`collapsible` lets a pane fold away under its minimum. Give it a height with
+`cls`, since it fills what it is given.
+
+```python live
+ui.Split(
+    ui.Card(ui.Text("Left pane. Drag the handle."), title="Left"),
+    ui.Card(ui.Text("Right pane."), title="Right"),
+    sizes=[40, 60],
+    min_sizes=[20, 20],
+    cls="h-48",
+)
+```
+
+## Tabs
+
+`ui.Tabs` holds `ui.Tab` children, each with an `id` and a `label`, and an
+optional `icon` or `badge`. The chosen tab is the tab's business unless the
+page passes `value`; `default` names the first one shown. Panels stay mounted
+when hidden, so what the user typed in one survives a switch.
+
+```python live
+ui.Tabs(
+    ui.Tab(ui.Text("Overview text."), id="overview", label="Overview"),
+    ui.Tab(ui.Input(placeholder="Type, switch away and back"), id="edit", label="Edit", badge="1"),
+    ui.Tab(ui.Text("Settings text."), id="settings", label="Settings", icon="settings"),
+    default="overview",
+)
+```
+
+## Accordion and Collapsible
+
+`ui.Accordion` opens one `ui.AccordionItem` at a time, or several with
+`multiple=True`. `ui.Collapsible` is a single section with a `title`.
+
+```python live
+ui.Stack(
+    ui.Accordion(
+        ui.AccordionItem(
+            ui.Text("What a session is, and what it holds."), id="s", title="Sessions"
+        ),
+        ui.AccordionItem(ui.Text("How a handler changes state."), id="h", title="Handlers"),
+        default=["s"],
+    ),
+    ui.Collapsible(ui.Text("Details that are usually folded away."), title="Advanced"),
+    gap=4,
+)
+```
+
+## ScrollArea
+
+`ui.ScrollArea` scrolls its children inside a fixed `height`.
+
+```python live
+ui.ScrollArea(
+    ui.Stack(*(ui.Text(f"Line {i + 1}") for i in range(30)), gap=1),
+    height="8rem",
+)
+```

millwork/manual/pages/components/tasks.md

@@ -0,0 +1,140 @@
+---
+title: Tasks
+order: 8
+---
+
+# Tasks
+
+Work that takes longer than a click goes in a task. The session owns it, the
+page shows its progress, and the user can cancel it. A handler that awaits a
+task releases the handler lock, so the page stays live meanwhile.
+
+## Starting one
+
+`s.task(work, *args, label=)` runs a coroutine or a plain function (a
+function runs in a thread). It returns a `mw.Task` whose `done`, `status`,
+`progress`, `steps` and `result` the page can read. `ui.Progress(task=)`
+and `ui.Steps(task=)` draw it, and `task.cancel()` stops it.
+
+```python live
+import time
+
+from pydantic import BaseModel
+
+
+def crunch(n: int) -> str:
+    p = mw.progress()
+    p.plan(["Read", "Analyse", "Write"])
+    with p.step("Read"):
+        time.sleep(0.4)
+    with p.step("Analyse") as step:
+        for i in range(n):
+            p.check()
+            p.set((i + 1) / n, f"row {i + 1} of {n}")
+            time.sleep(0.15)
+        step.note(f"{n} rows")
+    with p.step("Write"):
+        time.sleep(0.3)
+    return f"{n} rows analysed"
+
+
+class Job(BaseModel):
+    run: object = None
+
+
+def example(s):
+    st = state(Job)
+    running = st.run is not None and not st.run.done
+    return ui.Stack(
+        ui.Row(
+            ui.Button(
+                "Start",
+                disabled=running,
+                on_click=lambda s, _: setattr(st, "run", s.task(crunch, 12, label="Crunching")),
+            ),
+            ui.Button(
+                "Cancel",
+                variant="outline",
+                disabled=not running,
+                on_click=lambda s, _: st.run.cancel(),
+            ),
+            gap=2,
+        ),
+        ui.Progress(task=st.run) if st.run else ui.Text("No job yet.", variant="muted"),
+        ui.Steps(task=st.run) if st.run else None,
+        ui.Text(f"Result: {st.run.result}" if st.run and st.run.ok else "", variant="muted"),
+        gap=4,
+    )
+```
+
+## Reporting from the work
+
+Inside the work, `mw.progress()` is the reporter. `set(value, message)`
+moves the bar, `plan([...])` declares steps up front, `step(label)` opens
+one as a context manager, `note(text)` leaves a short result on it,
+`log(line)` appends output, and `check()` raises `mw.Cancelled` when the
+user cancelled, so a loop stops at its next check.
+
+## Waiting for a result
+
+A handler can `await` the task to use its result; the lock is released while
+it waits. `on_done=` names a handler to run when the task ends, with the
+task as its argument. `timeout=` cancels a task that runs too long.
+
+```python live
+import asyncio
+
+from pydantic import BaseModel
+
+
+async def slow_sum(a: int, b: int) -> int:
+    await asyncio.sleep(0.8)
+    return a + b
+
+
+class Sum(BaseModel):
+    text: str = "not computed"
+
+
+async def compute(s, _):
+    st = state(Sum)
+    st.text = "computing"
+    result = await s.task(slow_sum, 2, 3, label="Adding")
+    st.text = f"2 + 3 = {result}"
+
+
+def example(s):
+    return ui.Row(
+        ui.Button("Compute", on_click=compute),
+        ui.Text(state(Sum).text, variant="muted"),
+        gap=3,
+    )
+```
+
+## Later and threads
+
+`s.later(seconds, work)` runs work after a delay; `s.thread(fn, *args)`
+runs a blocking function in the thread pool and is what `s.task` does for a
+plain function.
+
+```python live
+from pydantic import BaseModel
+
+
+class Tick(BaseModel):
+    text: str = "waiting"
+
+
+def example(s):
+    st = state(Tick)
+
+    def arm(s, _):
+        st.text = "armed"
+        s.later(1.5, lambda: setattr(st, "text", "fired"))
+
+    return ui.Row(
+        ui.Button("Arm a timer", variant="outline", on_click=arm),
+        ui.Text(st.text, variant="muted"),
+        gap=3,
+    )
+```