millwork 0.1.0__py3-none-any.whl

millwork/ui/charts.py

@@ -0,0 +1,214 @@
+"""Charts: rows in, a drawn chart out, coloured from the theme's chart tokens.
+
+A chart takes rows like the Table does. ``x`` names the category or time
+column; ``y`` names one value column or several (wide rows), or one value
+column with ``by`` naming the column that holds the series name (long rows),
+which Python pivots to wide before the wire. Series keep the order they are
+given or first appear in and take ``chart-1`` to ``chart-5`` in that order,
+so a series keeps its colour when a filter removes a neighbour.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from decimal import Decimal
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, PrivateAttr, model_validator
+from pydantic_core import to_jsonable_python
+
+from millwork.nodes import Component
+
+MAX_SERIES = 5
+"""Five hues the theme defines; a sixth series would need a generated colour."""
+
+ValueFormat = Literal["number", "integer", "percent", "currency"]
+
+
+def _value(v: Any) -> Any:
+    # A Decimal (database rows) would become a string, and a string is a gap.
+    if isinstance(v, Decimal):
+        return float(v)
+    return to_jsonable_python(v)
+
+
+def _row_dict(row: Any) -> dict[str, Any]:
+    if isinstance(row, BaseModel):
+        return {k: _value(v) for k, v in row.model_dump().items()}
+    if isinstance(row, Mapping):
+        return {str(k): _value(v) for k, v in row.items()}
+    raise TypeError(f"a chart row is a mapping or a model, not {type(row).__name__}")
+
+
+def _series_spec(y: Any) -> list[dict[str, str]]:
+    if isinstance(y, str):
+        return [{"key": y, "label": y}]
+    if isinstance(y, Mapping):
+        return [{"key": str(k), "label": str(v)} for k, v in y.items()]
+    if isinstance(y, Sequence):
+        out: list[dict[str, str]] = []
+        for item in y:
+            if isinstance(item, str):
+                out.append({"key": item, "label": item})
+            elif isinstance(item, Sequence) and len(item) == 2:
+                out.append({"key": str(item[0]), "label": str(item[1])})
+            else:
+                raise TypeError("a series is a column name or a (column, label) pair")
+        return out
+    raise TypeError("y is a column name, a list of them, or a mapping of column to label")
+
+
+class _Chart(Component):
+    """What every chart shares: rows, the x column, series, formats, a click."""
+
+    wire_exclude: ClassVar[frozenset[str]] = frozenset({"rows", "y", "by"})
+
+    rows: Sequence[Any]
+    x: str
+    y: Any
+    by: str | None = None
+    format: ValueFormat | None = None
+    labels: bool = False
+    legend: bool | None = None
+    emphasis: str | None = None
+    height: int | None = None
+    on_click: Any = None
+
+    # Built once from the rows: the series in drawing order and the wide points.
+    _series: list[dict[str, str]] = PrivateAttr()
+    _points: list[dict[str, Any]] = PrivateAttr()
+
+    def __init__(self, rows: Sequence[Any] = (), **props: Any) -> None:
+        super().__init__(rows=rows, **props)
+
+    @model_validator(mode="after")
+    def _check(self) -> _Chart:
+        if self.by is not None and not isinstance(self.y, str):
+            raise ValueError("with by=, y names the one column that holds the values")
+        dicts = [_row_dict(r) for r in self.rows]
+        if dicts:
+            wanted = [self.x, self.by, str(self.y)] if self.by else [self.x]
+            missing = [c for c in wanted if c not in dicts[0]]
+            if missing:
+                raise ValueError(f"the rows have no column {missing[0]!r}")
+        series = self._build_series(dicts)
+        if not series:
+            raise ValueError("a chart needs at least one series")
+        if len(series) > MAX_SERIES:
+            raise ValueError(
+                f"a chart draws {MAX_SERIES} series at most; fold the rest into one, "
+                "or draw several charts"
+            )
+        keys = [s["key"] for s in series]
+        if len(set(keys)) != len(keys):
+            raise ValueError("series keys repeat")
+        if "x" in keys:
+            raise ValueError("a series cannot be called 'x'; that name is the category")
+        if self.emphasis is not None and self.emphasis not in keys:
+            raise ValueError(f"emphasis names a series; {self.emphasis!r} is not one of {keys}")
+        if dicts and self.by is None:
+            missing = [k for k in keys if k not in dicts[0]]
+            if missing:
+                hint = ""
+                if isinstance(self.y, tuple) and len(self.y) == 2:
+                    hint = " (a (column, label) pair goes inside a list)"
+                raise ValueError(f"the rows have no column {missing[0]!r}{hint}")
+        self._series = series
+        self._points = self._build_points(dicts, keys)
+        return self
+
+    def _build_series(self, dicts: list[dict[str, Any]]) -> list[dict[str, str]]:
+        if self.by is None:
+            return _series_spec(self.y)
+        value = str(self.y)
+        seen: dict[str, None] = {}
+        for r in dicts:
+            name = r.get(self.by)
+            if name is not None:
+                seen.setdefault(str(name), None)
+        return [{"key": k, "label": k} for k in seen] or [{"key": value, "label": value}]
+
+    def _build_points(self, dicts: list[dict[str, Any]], keys: list[str]) -> list[dict[str, Any]]:
+        if self.by is None:
+            return [{"x": r.get(self.x), **{k: r.get(k) for k in keys}} for r in dicts]
+        value = str(self.y)
+        order: dict[Any, dict[str, Any]] = {}
+        for r in dicts:
+            x = r.get(self.x)
+            try:
+                point = order.setdefault(x, {"x": x})
+            except TypeError:
+                raise ValueError(f"with by=, x values must be hashable, not {x!r}") from None
+            name = r.get(self.by)
+            if name is None:
+                continue
+            if str(name) in point:
+                raise ValueError(
+                    f"two rows have {self.x}={x!r} and {self.by}={name!r}; group the rows first"
+                )
+            point[str(name)] = r.get(value)
+        return [{"x": p["x"], **{k: p.get(k) for k in keys}} for p in order.values()]
+
+    def series(self) -> list[dict[str, str]]:
+        """The series on the wire: ``{key, label}`` in drawing order."""
+        return self._series
+
+    def points(self) -> list[dict[str, Any]]:
+        """Wide rows: ``x`` plus one value per series key, in row order."""
+        return self._points
+
+    def wire_extra(self) -> dict[str, Any]:
+        return {"data": self._points, "series": self._series}
+
+
+class BarChart(_Chart):
+    """Bars for magnitudes by category: grouped, ``stacked``, ``horizontal``.
+
+    ``stacked="percent"`` stacks to a full bar. ``diverging`` is for an
+    ordered scale such as agree to disagree: the series are a scale from
+    one pole to the other, drawn to either side of a neutral midpoint, and
+    coloured from two hues through grey instead of five. Its values are
+    counts, never negative, and it draws no value labels.
+    """
+
+    type: ClassVar[str] = "BarChart"
+    stacked: bool | Literal["percent"] = False
+    horizontal: bool = False
+    diverging: bool = False
+
+    @model_validator(mode="after")
+    def _check_bars(self) -> BarChart:
+        if self.diverging and self.stacked == "percent":
+            raise ValueError("a diverging chart is stacked around its midpoint; percent is not")
+        if self.diverging and self.emphasis is not None:
+            raise ValueError("a diverging chart colours a scale, not one series")
+        if self.diverging:
+            for point in self.points():
+                for k, v in point.items():
+                    if k != "x" and isinstance(v, int | float) and v < 0:
+                        raise ValueError(
+                            f"a diverging chart stacks counts to either side; {k}={v!r} is negative"
+                        )
+        return self
+
+
+class LineChart(_Chart):
+    """Lines over an ordered x: one per series, a crosshair tooltip across them.
+
+    ``curve`` smooths the lines; ``dots`` marks every point.
+    """
+
+    type: ClassVar[str] = "LineChart"
+    curve: bool = False
+    dots: bool = False
+
+
+class AreaChart(_Chart):
+    """Lines with the space under them filled; ``stacked`` adds the series up."""
+
+    type: ClassVar[str] = "AreaChart"
+    stacked: bool | Literal["percent"] = False
+    curve: bool = False
+
+
+__all__ = ["AreaChart", "BarChart", "LineChart", "MAX_SERIES"]

millwork/ui/chat.py

@@ -0,0 +1,97 @@
+"""The Chat component: one handler, one reply handle, messages the session owns."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, ConfigDict
+
+from millwork import context
+from millwork.nodes import Component
+
+
+class Command(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    label: str
+    icon: str | None = None
+    description: str | None = None
+
+
+class Action(BaseModel):
+    """A button under an assistant message; ``on_action`` receives its id."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    label: str
+    icon: str | None = None
+
+
+class Accept(BaseModel):
+    """What the composer takes: the extensions, how many per message, how large.
+    ``capture`` opens the camera or the microphone straight away on a phone;
+    ``paperclip=False`` hides the attach button while uploads from the chat's
+    ``tools`` still go by these limits."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    accept: list[str] | None = None
+    max_files: int = 5
+    max_size_mb: int | None = None
+    capture: Literal["user", "environment"] | None = None
+    paperclip: bool = True
+
+
+class Chat(Component):
+    type: ClassVar[str] = "Chat"
+    wire_exclude: ClassVar[frozenset[str]] = frozenset()
+
+    welcome: str | None = None
+    suggestions: list[str] = []
+    placeholder: str | None = None
+    attachments: Accept | None = None
+    # The longest message and the most of them the session keeps for the
+    # thread, the oldest going first: together they bound what a thread can
+    # hold, whatever is sent.
+    max_chars: int = 16_000
+    max_messages: int = 200
+    commands: list[Command] = []
+    disabled: bool = False
+    show_steps: Literal["full", "collapsed", "hidden"] = "collapsed"
+    # Reading aids, each off by default: the assistant's picture beside its
+    # messages, a name and a time above each message (on hover, always without
+    # a mouse), and how long a reply and each of its steps took.
+    avatar: str | None = None
+    assistant_name: str | None = None
+    names: bool = False
+    timestamps: bool = False
+    durations: bool = False
+    # Under an assistant message: copy, thumbs up and down (with ``on_feedback``),
+    # regenerate on the last one, the app's own ``actions``; a user message can
+    # be edited and resent. Each is off without its handler or flag.
+    copyable: bool = True
+    regenerate: bool = True
+    edit: bool = True
+    actions: list[Action] = []
+    # Components in the composer, left of Send: a Button with a handler, or a
+    # Custom component, which receives ``chat`` with upload, send and busy.
+    tools: list[Component] = []
+    on_message: Any = None
+    on_stop: Any = None
+    on_feedback: Any = None
+    on_action: Any = None
+
+    def wire_extra(self) -> dict[str, Any]:
+        """The finished messages and the thread's live bits; the in-flight one is the stream's."""
+        s = context.current()
+        if s is None or self.key is None:
+            return {"messages": [], "busy": False, "inline": {}}
+        thread = s.chat(self.key)
+        return {
+            "messages": [m.model_dump(mode="json") for m in thread.messages],
+            "busy": thread.busy,
+            "live_suggestions": thread.suggestions,
+            "inline": dict(thread.inline),
+        }

millwork/ui/files.py

@@ -0,0 +1,101 @@
+"""Files on a page: upload, cards, viewers, downloads."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Literal
+
+from pydantic import field_validator
+
+from millwork.files import FileRef
+from millwork.nodes import Component
+from millwork.ui.table import MenuItem
+
+
+def _safe_src(value: Any) -> Any:
+    if isinstance(value, str):
+        from millwork.ui import safe_href
+
+        return safe_href(value)
+    return value
+
+
+class FileUpload(Component):
+    """Uploads go over the session's socket; the handler receives ``FileRef``s."""
+
+    type: ClassVar[str] = "FileUpload"
+    accept: list[str] | None = None
+    multiple: bool = False
+    max_files: int = 10
+    max_size_mb: int | None = None
+    label: str | None = None
+    description: str | None = None
+    dropzone: bool = True
+    disabled: bool = False
+    on_upload: Any = None
+    on_reject: Any = None
+
+
+class FileCard(Component):
+    type: ClassVar[str] = "FileCard"
+    file: FileRef | None = None
+    name: str | None = None
+    size: int | None = None
+    kind: str | None = None
+    url: str | None = None
+    status: Literal["ready", "loading", "error"] = "ready"
+    _url = field_validator("url")(staticmethod(_safe_src))
+    meta: str | None = None
+    actions: list[MenuItem] = []
+    on_action: Any = None
+    on_click: Any = None
+
+
+class Image(Component):
+    type: ClassVar[str] = "Image"
+    src: FileRef | str
+    alt: str = ""
+    _src = field_validator("src")(staticmethod(_safe_src))
+    size: Literal["sm", "md", "lg", "full"] = "md"
+    fit: Literal["cover", "contain"] = "contain"
+    on_click: Any = None
+
+
+class Pdf(Component):
+    """A PDF in the browser's own viewer. A form or a link inside the document
+    looks like part of the app, so show files the app made or the person
+    uploaded themselves, not documents from strangers."""
+
+    type: ClassVar[str] = "Pdf"
+    src: FileRef | str
+    page: int | None = None
+    _src = field_validator("src")(staticmethod(_safe_src))
+    height: str = "70vh"
+
+
+class Download(Component):
+    """A button that downloads a file, bytes, text, or what a callable returns on click."""
+
+    type: ClassVar[str] = "Download"
+    wire_exclude: ClassVar[frozenset[str]] = frozenset({"content"})
+
+    label: str = "Download"
+    filename: str
+    content: Any
+    mime: str | None = None
+    variant: Literal["primary", "secondary", "outline", "ghost", "link"] = "outline"
+    icon: str | None = "download"
+    disabled: bool = False
+
+    def __init__(self, label: str = "Download", **props: Any) -> None:
+        super().__init__(label=label, **props)
+
+    def wire_extra(self) -> dict[str, Any]:
+        # A session file downloads by id, straight over the socket: no click round
+        # trip, no copy of the file.
+        if isinstance(self.content, FileRef):
+            from millwork import context
+
+            s = context.current()
+            if s is not None and s.id == self.content.session:
+                return {"file_id": self.content.id}
+        return {}

millwork/ui/form.py

@@ -0,0 +1,102 @@
+"""The Form component: a Pydantic model becomes fields, a submit becomes an instance."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any, ClassVar, Literal, Type  # noqa: UP035
+
+from pydantic import BaseModel
+
+from millwork.forms import Issue, field_spec
+from millwork.nodes import Component
+
+
+class Form(Component):
+    type: ClassVar[str] = "Form"
+    wire_exclude: ClassVar[frozenset[str]] = frozenset({"model", "initial"})
+
+    # ``Type`` rather than ``type``: the class body's ``type`` is the component's wire name.
+    model: Type[BaseModel]  # noqa: UP006
+    # Any: a ``BaseModel`` annotation would make pydantic try to build one from a dict.
+    initial: Any = None
+    submit: str | None = "Save"
+    cancel: str | None = None
+    layout: Literal["vertical", "horizontal"] | int = "vertical"
+    fields: list[str] | None = None
+    labels: Mapping[str, Mapping[str, Any]] | None = None
+    # pointer (or field name) to spec keys: widget, choices, placeholder, min, max, step, rows...
+    overrides: Mapping[str, Mapping[str, Any]] | None = None
+    issues: list[Issue] = []
+    disabled: bool = False
+    read_only: bool = False
+    dense: bool = False
+    on_submit: Any = None
+    on_cancel: Any = None
+
+    def __init__(self, model: Any = None, **props: Any) -> None:
+        if model is not None:
+            props["model"] = model
+        super().__init__(**props)
+
+    def wire_extra(self) -> dict[str, Any]:
+        spec = field_spec(self.model)
+        if self.fields is not None:
+            order = {name: i for i, name in enumerate(self.fields)}
+            spec["fields"] = sorted(
+                (f for f in spec["fields"] if f["name"] in order), key=lambda f: order[f["name"]]
+            )
+        if self.labels:
+            _apply_labels(spec["fields"], self.labels)
+        if self.overrides:
+            _apply_overrides(spec["fields"], self.overrides)
+        initial: Any = None
+        if isinstance(self.initial, BaseModel):
+            initial = self.initial.model_dump(mode="json")
+        elif isinstance(self.initial, Mapping):
+            initial = dict(self.initial)
+        elif self.initial is not None:
+            raise TypeError("Form.initial is a model instance or a mapping")
+        # The key doubles as the form element's id, so a Button(type="submit", form=key)
+        # anywhere on the page submits it.
+        return {"schema": spec, "initial": initial, "form_id": self.key}
+
+
+def _apply_labels(fields: list[dict[str, Any]], labels: Mapping[str, Mapping[str, Any]]) -> None:
+    _apply(fields, labels, keys=("label", "help", "placeholder"))
+
+
+def _apply_overrides(
+    fields: list[dict[str, Any]], overrides: Mapping[str, Mapping[str, Any]]
+) -> None:
+    _apply(fields, overrides, keys=None)
+
+
+def _apply(
+    fields: list[dict[str, Any]],
+    table: Mapping[str, Mapping[str, Any]],
+    keys: tuple[str, ...] | None,
+) -> None:
+    """Merge ``table[pointer]`` (or ``table[name]``) into each field spec, recursively.
+
+    ``keys`` limits what is taken; ``None`` takes everything. ``choices`` becomes
+    ``options`` either way.
+    """
+    for f in fields:
+        override = table.get(f["pointer"]) or table.get(f["name"])
+        if override:
+            for k, v in override.items():
+                if k == "choices":
+                    f["options"] = [
+                        {"value": c[0], "label": c[1]} if isinstance(c, tuple | list) else c
+                        for c in v
+                    ]
+                    if f["widget"] == "input":
+                        f["widget"] = "select"
+                elif keys is None or k in keys:
+                    f[k] = v
+        if "fields" in f:
+            _apply(f["fields"], table, keys)
+        if "item" in f and "fields" in f["item"]:
+            _apply(f["item"]["fields"], table, keys)
+        for v in f.get("variants", []):
+            _apply(v["fields"], table, keys)

millwork/ui/table.py

@@ -0,0 +1,145 @@
+"""The Table: rows as data, columns as a spec, tones instead of styles.
+
+Phase 1: every row is in the browser;
+sort, filter and pagination are the table's business; selection is the
+server's.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, ClassVar, Literal
+
+from pydantic import BaseModel, ConfigDict, field_validator
+from pydantic_core import to_jsonable_python
+
+from millwork.nodes import Component
+
+Format = Literal[
+    "text",
+    "number",
+    "integer",
+    "percent",
+    "currency",
+    "date",
+    "datetime",
+    "bool",
+    "badge",
+    "link",
+    "code",
+]
+Tone = Literal["default", "muted", "primary", "accent", "success", "warning", "destructive"]
+Row = Mapping[str, Any]
+
+
+class Column(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    key: str
+    header: str | None = None
+    width: int | str | None = None
+    align: Literal["left", "center", "right"] = "left"
+    format: Format = "text"
+    sortable: bool = True
+    filterable: bool = True
+    hidden: bool = False
+    wrap: bool = False
+
+
+class MenuItem(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    id: str
+    label: str
+    icon: str | None = None
+    disabled: bool = False
+    destructive: bool = False
+    separator_after: bool = False
+
+
+def _row_dict(row: Any) -> dict[str, Any]:
+    if isinstance(row, BaseModel):
+        return row.model_dump(mode="json")
+    if isinstance(row, Mapping):
+        return {str(k): to_jsonable_python(v) for k, v in row.items()}
+    raise TypeError(f"a table row is a mapping or a model, not {type(row).__name__}")
+
+
+class Table(Component):
+    type: ClassVar[str] = "Table"
+    wire_exclude: ClassVar[frozenset[str]] = frozenset({"tones", "rows"})
+
+    rows: Sequence[Any] = []
+    columns: list[Column] | None = None
+    row_key: str = "id"
+    height: int | str | None = None
+    sticky_header: bool = True
+    sortable: bool = True
+    default_sort: list[tuple[str, Literal["asc", "desc"]]] = []
+    filters: bool = False
+    search: bool = False
+    page_size: int | None = None
+    selection: Literal["none", "row", "rows"] = "none"
+    selected: list[Any] = []
+    row_actions: list[MenuItem] = []
+    tones: Callable[[Any], str | None] | Mapping[str, Callable[[Any, Any], str | None]] | None = (
+        None
+    )
+    summary: bool | str = True
+    empty: str = ""
+    on_select: Any = None
+    on_row_click: Any = None
+    on_action: Any = None
+    on_sort: Any = None
+    on_filter: Any = None
+
+    @field_validator("columns", mode="before")
+    @classmethod
+    def _columns(cls, value: Any) -> Any:
+        if value is None:
+            return None
+        out = []
+        for c in value:
+            if isinstance(c, str):
+                out.append(Column(key=c))
+            elif isinstance(c, Column):
+                out.append(c)
+            elif isinstance(c, Mapping):
+                out.append(Column(**c))
+            else:
+                raise TypeError(f"not a column: {c!r}")
+        return out
+
+    def wire_extra(self) -> dict[str, Any]:
+        rows = [_row_dict(r) for r in self.rows]
+        columns = self.columns
+        if columns is None:
+            keys = list(rows[0].keys()) if rows else []
+            columns = [Column(key=k) for k in keys]
+        tone_rows: dict[int, str] = {}
+        tone_cells: dict[int, dict[str, str]] = {}
+        if callable(self.tones):
+            for i, raw in enumerate(self.rows):
+                tone = self.tones(raw)
+                if tone:
+                    tone_rows[i] = tone
+        elif self.tones:
+            for i, (raw, row) in enumerate(zip(self.rows, rows, strict=True)):
+                for col, fn in self.tones.items():
+                    tone = fn(raw, row.get(col))
+                    if tone:
+                        tone_cells.setdefault(i, {})[col] = tone
+        # Keys the browser uses for selection and clicks. Rows without the key column
+        # fall back to their index, which only works when no row has a key to clash with.
+        keyed = [self.row_key in row for row in rows]
+        if any(keyed) and not all(keyed):
+            missing = keyed.index(False)
+            raise ValueError(f"table row {missing} has no {self.row_key!r}; every row needs one")
+        keys = [to_jsonable_python(row.get(self.row_key, i)) for i, row in enumerate(rows)]
+        return {
+            "rows": rows,
+            "keys": keys,
+            "columns": [c.model_dump(mode="json") for c in columns],
+            "tone_rows": {str(i): t for i, t in tone_rows.items()},
+            "tone_cells": {str(i): t for i, t in tone_cells.items()},
+        }