millwork 0.1.0__py3-none-any.whl

millwork/manual/pages/components/chat.md

@@ -0,0 +1,280 @@
+---
+title: Chat
+order: 9
+---
+
+# Chat
+
+`ui.Chat` is a conversation: messages, a composer with attachments and
+commands, and a streamed reply from Python. It needs a `key`, which names
+the thread the session keeps for it, and an `on_message` handler that gets a
+`mw.ChatTurn` and replies through it. The chat fills whatever height it is
+given, so give it one with `cls` inside a card. `attachments=ui.Accept(...)`
+says what a person may attach, of which types, how many and how large;
+without it the composer takes no files. `max_chars` caps a message and
+`max_messages` the thread, as the section below says.
+`tools=[...]` puts your own buttons in the composer; the section below
+and the Custom chapter show what goes there.
+
+## A streamed reply
+
+`turn.text`, `turn.files` and `turn.command` are what the user sent. Inside
+`async with turn.reply() as reply`, `reply.text(chunk)` streams words,
+`reply.reasoning()` opens a thinking block, `reply.step(label)` a tool
+step, `reply.status(text)` a transient marker, and `reply.suggestions([...])`
+follow-up chips. The whole turn is a task: the stop button cancels it.
+
+```python live
+import asyncio
+
+
+async def answer(s, turn):
+    text = turn.text.strip() or "nothing"
+    if turn.command == "shout":
+        text = text.upper()
+    async with turn.reply() as reply:
+        async with reply.reasoning() as r:
+            await r.text("Deciding what to say about ")
+            await asyncio.sleep(0.3)
+            await r.text(f"“{text}”.")
+        async with reply.step("Looking it up") as step:
+            await asyncio.sleep(0.4)
+            await step.output({"hits": 3})
+        for word in f"You said {text}, and I heard every word of it.".split(" "):
+            await reply.text(word + " ")
+            await asyncio.sleep(0.05)
+        for f in turn.files:
+            await reply.file(f)
+        await reply.suggestions(["Say it again", "Try /shout"])
+
+
+ui.Card(
+    ui.Chat(
+        key="demo",
+        welcome="Ask anything. The reply streams back from Python.",
+        suggestions=["What can you do?", "Write a haiku"],
+        placeholder="Type a message",
+        attachments=ui.Accept(accept=[".txt", ".md"], max_files=2),
+        commands=[
+            ui.Command(id="shout", label="Shout", icon="volume-2", description="Reply in capitals")
+        ],
+        on_message=answer,
+        cls="h-[28rem]",
+    ),
+    padding=False,
+)
+```
+
+## The thread
+
+`s.chat(key)` is the thread: `messages` holds what was said, `clear()`
+empties it, and `load(messages)` restores a stored conversation. `busy` is
+true while a reply is streaming. The session keeps the last `max_messages`
+of the Chat, 200 by default, each at most `max_chars` long, 16,000 by
+default, so a thread holds a known amount whatever a visitor sends.
+`s.drop_chat(key)` forgets a thread altogether, for an app that keeps its
+threads in a store and only the open one in the session.
+
+```python live
+ui.Row(
+    ui.Button(
+        "Clear the chat above",
+        variant="outline",
+        icon="trash-2",
+        on_click=lambda s, _: s.chat("demo").clear(),
+    ),
+    ui.Button(
+        "Count messages",
+        variant="outline",
+        on_click=lambda s, _: s.toast(f"{len(s.chat('demo').messages)} messages"),
+    ),
+    gap=2,
+)
+```
+
+## Parts a reply can carry
+
+| Call | Shows as |
+| --- | --- |
+| `await reply.text(chunk)` | streamed Markdown |
+| `async with reply.reasoning() as r` | a folded thinking block, `r.text(...)` inside |
+| `async with reply.step(label) as step` | a tool step with `step.output(...)` |
+| `await reply.source(title, url, snippet)` | a source chip |
+| `await reply.file(ref)` and `reply.image(ref)` | an attachment, an inline image |
+| `await reply.status(text)` | a marker that disappears when the reply ends |
+| `await reply.component(component)` | any catalogue component inside the message |
+| `await reply.suggestions([...])` | follow-up chips |
+| `await reply.error(text)` | an error line |
+
+## Reading aids
+
+Four things are off until asked for, since a chat is often clean enough
+without them: `avatar` puts a picture beside the assistant's messages,
+`names=True` and `timestamps=True` write who said it and when above each
+message (on hover, always on a touch screen; `assistant_name` sets the
+name), and `durations=True` shows how long the reply took and how long
+each step ran. The times are kept on the messages, so a loaded thread
+shows them too.
+
+```python live
+import asyncio
+
+
+async def answer(s, turn):
+    async with turn.reply() as reply:
+        async with reply.step("Checking the archive") as step:
+            await asyncio.sleep(0.6)
+            await step.output({"found": 2})
+        await reply.text(f"Two notes mention {turn.text.strip() or 'nothing'}.")
+
+
+ui.Card(
+    ui.Chat(
+        key="aids",
+        welcome="Hover a message for its name and time.",
+        avatar="/public/mark.svg",
+        assistant_name="Archivist",
+        names=True,
+        timestamps=True,
+        durations=True,
+        on_message=answer,
+        cls="h-[20rem]",
+    ),
+    padding=False,
+)
+```
+
+## Tools in the composer
+
+`tools=[...]` renders components left of Send. A `ui.Button` there is an
+ordinary button with a handler in Python, and nothing says it must touch
+the conversation: this gear opens a `ui.Dialog` that lives next to the
+chat, the dialog changes state, and the next reply reads it. Nothing is
+sent and no message appears. A custom component in the slot gets a `chat`
+prop to upload and send with; the Custom chapter builds a voice note
+button on it.
+
+```python live
+from pydantic import BaseModel
+
+
+class Settings(BaseModel):
+    open: bool = False
+    tone: str = "plain"
+    sign: bool = False
+
+
+async def answer(s, turn):
+    st = state(Settings)
+    async with turn.reply() as reply:
+        text = turn.text.upper() if st.tone == "shout" else turn.text
+        await reply.text(f"You said: {text}" + (" (sent from the manual)" if st.sign else ""))
+
+
+def example(s):
+    st = state(Settings)
+
+    def opened(value):
+        def handler(s, _):
+            st.open = value
+
+        return handler
+
+    return ui.Stack(
+        ui.Card(
+            ui.Chat(
+                key="settings-demo",
+                welcome="The gear in the composer opens the settings.",
+                tools=[
+                    ui.Button(
+                        key="gear",
+                        icon="settings",
+                        variant="ghost",
+                        size="sm",
+                        tooltip="Settings",
+                        on_click=opened(True),
+                    )
+                ],
+                on_message=answer,
+                cls="h-[20rem]",
+            ),
+            padding=False,
+        ),
+        ui.Dialog(
+            ui.Field(
+                ui.Select(
+                    key="tone",
+                    options=["plain", "shout"],
+                    value=st.tone,
+                    on_change=lambda s, v: setattr(st, "tone", v or "plain"),
+                ),
+                label="Tone",
+            ),
+            ui.Switch(
+                key="sign",
+                label="Sign the replies",
+                checked=st.sign,
+                on_change=lambda s, v: setattr(st, "sign", bool(v)),
+            ),
+            key="settings",
+            open=st.open,
+            title="Chat settings",
+            on_close=opened(False),
+            footer=ui.Button("Done", on_click=opened(False)),
+        ),
+    )
+```
+
+## Under a message
+
+Hover an answer and a row of buttons appears: copy, thumbs up and down
+when the chat has an `on_feedback` handler, regenerate on the latest
+answer, and any `actions` of the app's own. A thumbs down asks for a
+comment. The choice stays on the message, so it is there after a reload,
+and millwork keeps nothing else: `on_feedback` gets the message, the value
+and the comment, and the app stores them where it wants. A user message
+has an edit button; the edited message is answered again and what followed
+it goes. `regenerate=False`, `edit=False` and `copyable=False` switch each
+off.
+
+```python live
+from pydantic import BaseModel
+
+
+class Feedback(BaseModel):
+    notes: list[str] = []
+
+
+async def echo(s, turn):
+    async with turn.reply() as reply:
+        await reply.text(f"You said: {turn.text}")
+
+
+async def rated(s, message, value, comment):
+    what = "cleared" if value is None else value
+    note = f"{what}: {message.text[:30]}" + (f" ({comment})" if comment else "")
+    state(Feedback).notes.append(note)
+
+
+async def act(s, message, action):
+    s.toast(f"{action}: {message.text}")
+
+
+def example(s):
+    notes = state(Feedback).notes
+    return ui.Stack(
+        ui.Card(
+            ui.Chat(
+                key="rated",
+                welcome="Say something, then rate the answer or edit your message.",
+                on_message=echo,
+                on_feedback=rated,
+                on_action=act,
+                actions=[ui.Action(id="save", label="Save", icon="bookmark")],
+                cls="h-[22rem]",
+            ),
+            padding=False,
+        ),
+        ui.Text("Feedback so far: " + ("; ".join(notes) or "none")),
+    )
+```

millwork/manual/pages/components/custom.md

@@ -0,0 +1,148 @@
+---
+title: Custom components
+order: 10
+---
+
+# Custom components
+
+When the catalogue has no component for something, an app writes one in
+JSX. The file lives in the app's `components/` folder, is compiled in the
+browser, and composes the same primitives the catalogue is built from.
+Python reaches it by name with `ui.Custom`.
+
+## The contract
+
+A component is a default export that receives `props` from Python, `emit`
+to send an event back, `request` to ask one of its handlers and get the
+answer as a promise, `fileUrl` to show a session file, and `children`
+rendered from Python.
+
+```jsx
+import { useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Badge } from "@/components/ui/badge";
+import { Sparkles } from "lucide-react";
+
+export default function Hello({ props, emit, children }) {
+  const [clicks, setClicks] = useState(0);
+  return (
+    <div className="flex flex-col gap-2 rounded-xl border border-dashed border-primary/40 p-4">
+      <div className="flex items-center gap-2">
+        <Sparkles className="size-4 text-primary" />
+        <span className="font-medium">Hello, {props.who}.</span>
+        <Badge variant="secondary">server says {props.count}</Badge>
+        <Badge variant="outline">local clicks {clicks}</Badge>
+      </div>
+      <div className="flex gap-2">
+        <Button size="sm" variant="outline" onClick={() => setClicks((c) => c + 1)}>Local +1</Button>
+        <Button size="sm" onClick={() => emit("wave", clicks)}>Wave to the server</Button>
+      </div>
+      {children}
+    </div>
+  );
+}
+```
+
+## Using it from Python
+
+`ui.Custom(name, props=, events=)` renders `components/<name>.jsx`. Events
+the component emits reach the handler named in `events`, or `on_event` as
+`(name, payload)`.
+
+```python live
+from pydantic import BaseModel
+
+
+class Waves(BaseModel):
+    count: int = 0
+
+
+def example(s):
+    st = state(Waves)
+
+    def waved(s, clicks):
+        st.count += 1
+        s.toast(f"Waved after {clicks} local clicks.")
+
+    return ui.Custom(
+        "Hello",
+        ui.Text("Children from Python render inside the custom component.", variant="muted"),
+        props={"who": "Ada", "count": st.count},
+        events={"wave": waved},
+    )
+```
+
+The import map a custom component can draw on is React, lucide icons, and
+every `@/components/ui/*` module the catalogue uses. Tailwind classes work;
+ones the bundle never saw are compiled in the browser on first use.
+
+## In a chat's composer
+
+`ui.Chat(tools=[...])` puts components in the composer, left of Send: a
+`ui.Button` with a handler in Python, or a custom component, which then
+receives a `chat` prop with `upload(file)`, `send(text, files)` and
+`busy`. That is enough for anything the browser can capture. This voice
+note button records with the browser's own recorder, uploads the clip
+under the chat's `attachments` limits and sends it; the handler gets it as
+`turn.files[0]`. `paperclip=False` keeps the attach button away when the
+tool is the only way files come in, and `capture="environment"` on
+`Accept` makes the paperclip open the camera on a phone.
+
+```python live
+async def heard(s, turn):
+    async with turn.reply() as reply:
+        if turn.files:
+            clip = turn.files[0]
+            await reply.text(f"A voice note of {clip.size // 1024} KB. Here it is back:")
+            await reply.file(clip)
+        else:
+            await reply.text("Press the microphone and say something.")
+
+
+ui.Card(
+    ui.Chat(
+        key="voice",
+        welcome="Record a voice note with the microphone button.",
+        attachments=ui.Accept(accept=[".webm", ".ogg", ".mp4", ".m4a"], paperclip=False),
+        tools=[ui.Custom("Voice")],
+        on_message=heard,
+        cls="h-[20rem]",
+    ),
+    padding=False,
+)
+```
+
+```jsx
+// components/Voice.jsx
+import { useRef, useState } from "react";
+import { Button } from "@/components/ui/button";
+import { Mic, Square } from "lucide-react";
+
+export default function Voice({ chat }) {
+  const [recorder, setRecorder] = useState(null);
+  const chunks = useRef([]);
+  if (!chat) return null;
+
+  async function start() {
+    const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+    const r = new MediaRecorder(stream);
+    chunks.current = [];
+    r.ondataavailable = (e) => chunks.current.push(e.data);
+    r.onstop = async () => {
+      stream.getTracks().forEach((t) => t.stop());
+      const blob = new Blob(chunks.current, { type: r.mimeType || "audio/webm" });
+      const ref = await chat.upload(new File([blob], "voice.webm", { type: blob.type }));
+      chat.send("", [ref]);
+    };
+    r.start();
+    setRecorder(r);
+  }
+
+  return (
+    <Button type="button" size="icon-sm" variant={recorder ? "destructive" : "ghost"}
+      onClick={recorder ? () => { recorder.stop(); setRecorder(null); } : start}>
+      {recorder ? <Square /> : <Mic />}
+    </Button>
+  );
+}
+```

millwork/manual/pages/components/data.md

@@ -0,0 +1,112 @@
+---
+title: Data
+order: 4
+---
+
+# Data
+
+`ui.Table` shows rows: dicts, Pydantic models or dataclasses. Columns come
+from the rows unless `columns` names them, with a `header`, a `format`, a
+`width`, an `align`, and whether they are `sortable` or `filterable`.
+
+## A plain table
+
+Sorting is on by default and happens in the browser. `row_key` names the
+field that identifies a row, `id` unless told otherwise.
+
+```python live
+ROWS = [
+    {"id": 1, "name": "Ada", "role": "Engineer", "score": 0.92, "joined": "2024-03-01", "active": True},
+    {"id": 2, "name": "Grace", "role": "Admiral", "score": 0.88, "joined": "2023-11-15", "active": True},
+    {"id": 3, "name": "Edsger", "role": "Professor", "score": 0.75, "joined": "2022-06-30", "active": False},
+    {"id": 4, "name": "Barbara", "role": "Architect", "score": 0.81, "joined": "2024-08-12", "active": True},
+]
+
+ui.Table(rows=ROWS)
+```
+
+## Columns and formats
+
+`format` renders a value as `text`, `number`, `integer`, `percent`,
+`currency`, `date`, `datetime`, `bool`, `badge`, `link` or `code`.
+
+```python live
+ui.Table(
+    rows=ROWS,
+    columns=[
+        ui.Column(key="name", header="Name"),
+        ui.Column(key="role", header="Role", format="badge"),
+        ui.Column(key="score", header="Score", format="percent", align="right"),
+        ui.Column(key="joined", header="Joined", format="date"),
+        ui.Column(key="active", header="Active", format="bool", align="center"),
+    ],
+    default_sort=[("score", "desc")],
+)
+```
+
+## Search, filters and pages
+
+`search=True` adds a box that matches any column; `filters=True` adds a
+filter row whose kind follows each column's values; `page_size` pages the
+rows. `summary` is the count line under the table, or custom text.
+
+```python live
+ui.Table(rows=ROWS, search=True, filters=True, page_size=3, summary="People in the pilot")
+```
+
+## Selection and row actions
+
+`selection="row"` or `"rows"` lets the user pick; `on_select` receives the
+keys. `row_actions` adds a menu per row and `on_action` receives
+`(action id, row key)`. `on_row_click` receives the key of the clicked row.
+
+```python live
+from pydantic import BaseModel
+
+
+class Picked(BaseModel):
+    keys: list = []
+    last: str = ""
+
+
+def example(s):
+    st = state(Picked)
+    return ui.Stack(
+        ui.Table(
+            rows=ROWS,
+            columns=[ui.Column(key="name"), ui.Column(key="role")],
+            selection="rows",
+            selected=st.keys,
+            on_select=lambda s, keys: setattr(st, "keys", keys),
+            row_actions=[
+                ui.MenuItem(id="edit", label="Edit", icon="pencil"),
+                ui.MenuItem(id="remove", label="Remove", icon="trash-2", destructive=True),
+            ],
+            on_action=lambda s, a: setattr(st, "last", f"{a[0]} on row {a[1]}"),
+            on_row_click=lambda s, key: setattr(st, "last", f"clicked row {key}"),
+        ),
+        ui.Text(f"Selected: {st.keys}. Last: {st.last or 'nothing'}", variant="muted"),
+        gap=3,
+    )
+```
+
+## Tones
+
+`tones` colours rows: a function of the row returning a tone, or a mapping
+from column key to a function of the row and the cell.
+
+```python live
+ui.Table(
+    rows=ROWS,
+    columns=[ui.Column(key="name"), ui.Column(key="score", format="percent")],
+    tones=lambda r: "success" if r["score"] > 0.85 else ("warning" if r["score"] < 0.8 else None),
+)
+```
+
+## Empty
+
+`empty` is the text shown when there are no rows.
+
+```python live
+ui.Table(rows=[], columns=[ui.Column(key="name"), ui.Column(key="role")], empty="No people match.")
+```