composeui 0.1.0__py3-none-any.whl

composeui/qtcore/widgets/map.qml

@@ -0,0 +1,123 @@
+import QtQuick
+import QtLocation
+import QtPositioning
+
+Item {
+    id: root
+    property var points: []
+    property bool tiles: true
+    property real latitude: 0
+    property real longitude: 0
+    property alias zoom: map.zoomLevel
+    focus: true
+    signal viewportMoved(real latitude, real longitude, real zoom)
+    signal pointClicked(real latitude, real longitude)
+
+    function moved() {
+        // Copy both numbers before changing the properties that bind map.center.
+        const movedLatitude = map.center.latitude
+        const movedLongitude = map.center.longitude
+        latitude = Math.max(-85.05112878, Math.min(85.05112878, movedLatitude))
+        longitude = movedLongitude
+        viewportMoved(latitude, longitude, map.zoomLevel)
+    }
+
+    Keys.onPressed: (event) => {
+        if (event.key === Qt.Key_Plus || event.key === Qt.Key_Equal) zoom = Math.min(19, zoom + 1)
+        else if (event.key === Qt.Key_Minus) zoom = Math.max(0, zoom - 1)
+        else if (event.key === Qt.Key_Left) map.pan(-40, 0)
+        else if (event.key === Qt.Key_Right) map.pan(40, 0)
+        else if (event.key === Qt.Key_Up) map.pan(0, -40)
+        else if (event.key === Qt.Key_Down) map.pan(0, 40)
+        else return
+        event.accepted = true
+        moved()
+    }
+
+    Map {
+        id: map
+        center: QtPositioning.coordinate(root.latitude, root.longitude)
+        anchors.fill: parent
+        visible: root.tiles
+        copyrightsVisible: root.tiles
+        color: "#e5e7eb"
+        plugin: tilePlugin
+        onSupportedMapTypesChanged: {
+            // The custom host is the last map type; never select a provider repository URL.
+            if (root.tiles && supportedMapTypes.length)
+                activeMapType = supportedMapTypes[supportedMapTypes.length - 1]
+        }
+        onCenterChanged: overlay.requestPaint()
+        onZoomLevelChanged: overlay.requestPaint()
+        onMapReadyChanged: overlay.requestPaint()
+    }
+    Plugin {
+        id: tilePlugin
+        name: root.tiles ? "osm" : "itemsoverlay"
+        PluginParameter { name: "osm.useragent"; value: mapUserAgent }
+        PluginParameter { name: "osm.mapping.providersrepository.disabled"; value: true }
+        PluginParameter {
+            name: "osm.mapping.custom.host"
+            value: "https://tile.openstreetmap.org/"
+        }
+        PluginParameter {
+            name: "osm.mapping.custom.mapcopyright"
+            value: "© OpenStreetMap contributors"
+        }
+        PluginParameter { name: "osm.mapping.prefetching_style"; value: "NoPrefetching" }
+    }
+    Item {
+        anchors.fill: parent
+        DragHandler {
+            target: null
+            onTranslationChanged: (delta) => {
+                map.pan(-delta.x, -delta.y)
+                root.moved()
+            }
+        }
+        WheelHandler {
+            target: null
+            onWheel: (event) => {
+                map.zoomLevel = Math.max(0, Math.min(19, map.zoomLevel + event.angleDelta.y / 120))
+                root.moved()
+            }
+        }
+        TapHandler {
+            onTapped: (eventPoint) => {
+                const position = map.toCoordinate(eventPoint.position, false)
+                root.pointClicked(position.latitude, position.longitude)
+            }
+        }
+    }
+    Canvas {
+        id: overlay
+        anchors.fill: parent
+        onPaint: {
+            const ctx = getContext("2d")
+            ctx.clearRect(0, 0, width, height)
+            ctx.fillStyle = "#2563eb"
+            ctx.globalAlpha = 0.55
+            ctx.beginPath()
+            const world = 256 * Math.pow(2, root.zoom)
+            function mercator(latitude) {
+                const sine = Math.sin(latitude * Math.PI / 180)
+                return 0.5 - Math.log((1 + sine) / (1 - sine)) / (4 * Math.PI)
+            }
+            const centerY = mercator(root.latitude)
+            for (let i = 0; i < root.points.length; ++i) {
+                const p = root.points[i]
+                let dx = (p[1] - root.longitude) / 360
+                dx -= Math.round(dx)
+                const pixel = { x: width / 2 + dx * world,
+                    y: height / 2 + (mercator(p[0]) - centerY) * world }
+                if (pixel.x < -3 || pixel.x > width + 3 || pixel.y < -3 || pixel.y > height + 3) continue
+                ctx.moveTo(pixel.x + 3, pixel.y)
+                ctx.arc(pixel.x, pixel.y, 3, 0, 2 * Math.PI)
+            }
+            ctx.fill()
+        }
+        onWidthChanged: requestPaint()
+        onHeightChanged: requestPaint()
+    }
+    onPointsChanged: overlay.requestPaint()
+}

composeui/qtcore/widgets/qchart.py

@@ -0,0 +1,393 @@
+"""A chart widget over pyqtgraph: fast with long series, zoomed and panned with the mouse."""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+import pyqtgraph as pg
+from qtpy.QtCore import QEvent, QPointF, QSize, Qt
+from qtpy.QtCore import Signal as QtSignal
+from qtpy.QtGui import QAction, QColor, QFont, QPalette
+
+from composeui.core import chartimage
+from composeui.core.chartcolors import is_dashed, series_color
+from composeui.core.view import ChartKind, ChartView, LineStyle
+
+if TYPE_CHECKING:
+    from qtpy.QtWidgets import QWidget
+
+    from composeui.core.view import ReferenceLine, Series
+
+#: the hover values' rate, per second: a mouse sends far more moves than that
+_HOVER_RATE = 30
+#: the lightness (of 255) under which a background is dark
+_DARK_LIGHTNESS = 128
+#: the size a chart asks of its layout, in pixels: pyqtgraph's own, before it is shown
+_SIZE_HINT = (600, 480)
+#: a scatter's dots, in pixels
+_DOT_SIZE = 8
+
+
+#: a reference line's pen style, by its style
+_LINE_STYLES = {
+    LineStyle.SOLID: Qt.PenStyle.SolidLine,
+    LineStyle.DASHED: Qt.PenStyle.DashLine,
+    LineStyle.DOTTED: Qt.PenStyle.DotLine,
+    LineStyle.DASH_DOT: Qt.PenStyle.DashDotLine,
+}
+
+
+def _format(value: float, unit: str) -> str:
+    # its trailing zeros kept: as many digits wherever the cursor is, as on the web
+    return f"{value:#.4g} {unit}".rstrip()
+
+
+def _tabular_font() -> QFont:
+    """Get the application's font with digits of one width, where Qt has them (6.7)."""
+    font = QFont()
+    if hasattr(font, "setFeature") and hasattr(QFont, "Tag"):  # pragma: no branch
+        font.setFeature(QFont.Tag("tnum"), 1)
+    return font
+
+
+class QChart(pg.PlotWidget):  # type: ignore[misc]
+    """A chart of series; hovering it shows each series' point nearest the cursor's x.
+
+    Its colors follow the application's palette, changing with it (a dark scheme).
+    """
+
+    #: the user asked for the chart's image, from its context menu's Save Image
+    save_image_requested = QtSignal()
+    #: the user clicked the plot at a point, as the axes' values (not their logs)
+    point_clicked = QtSignal(float, float)
+    #: whether `__init__` is done: pyqtgraph's own changes the palette before it is
+    _is_built = False
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self._series: list[Series] = []
+        self._kind = ChartKind.LINE
+        self._categories: list[str] = []
+        self._x_log = False
+        self._y_log = False
+        self._bars: list[pg.BarGraphItem] = []
+        self._units = ("", "")
+        self._items: list[pg.PlotDataItem] = []
+        self._reference_lines: list[ReferenceLine] = []
+        self._line_items: list[pg.InfiniteLine] = []
+        plot = self.getPlotItem()
+        self._legend = plot.addLegend()
+        # pyqtgraph thins and clips what it draws itself: a million points stay fluid
+        plot.setDownsampling(auto=True, mode="peak")
+        plot.setClipToView(True)
+        plot.showGrid(x=True, y=True, alpha=0.15)
+        self._crosshair = pg.InfiniteLine(angle=90, movable=False)
+        self._crosshair.setVisible(False)
+        self._hover = pg.TextItem(anchor=(0, 1))
+        # its values change as the cursor moves, without changing their width
+        self._hover.setFont(_tabular_font())
+        self._hover.setVisible(False)
+        for item in (self._crosshair, self._hover):
+            plot.addItem(item, ignoreBounds=True)
+        self.scene().sigMouseClicked.connect(self._on_mouse_clicked)
+        self._mouse_proxy = pg.SignalProxy(
+            self.scene().sigMouseMoved, rateLimit=_HOVER_RATE, slot=self._on_mouse_moved
+        )
+        #: beside pyqtgraph's own Export, which stays for CSV; only with matplotlib, which
+        #: draws the image
+        self.save_image_action = QAction(self)
+        self.save_image_action.triggered.connect(self.save_image_requested.emit)
+        if chartimage.is_available():
+            plot.getViewBox().menu.addAction(self.save_image_action)
+        self._is_built = True
+        self._apply_palette()
+
+    def set_title(self, title: str) -> None:
+        self.getPlotItem().setTitle(title or None)
+
+    def set_axis(self, axis: str, title: str, unit: str) -> None:
+        """Label the `axis` ("bottom" or "left"); pyqtgraph scales the unit, e.g. into ms."""
+        self.getPlotItem().setLabel(axis, title or None, units=unit or None)
+        x_unit, y_unit = self._units
+        self._units = (unit, y_unit) if axis == "bottom" else (x_unit, unit)
+
+    def set_kind(self, kind: ChartKind) -> None:
+        """Draw the series as `kind`, unless they say otherwise (`Series.kind`)."""
+        self._kind = kind
+        self._draw()
+
+    def set_categories(self, categories: list[str]) -> None:
+        """Name a bar chart's categories, under their groups of bars."""
+        self._categories = categories
+        self._draw()
+
+    def set_log(self, *, x_log: bool, y_log: bool) -> None:
+        """Make the axes log axes or linear ones; a bar chart's x stays its categories."""
+        self._x_log, self._y_log = x_log, y_log
+        self._draw()
+
+    def set_series(self, series: list[Series]) -> None:
+        """Show `series`, reusing the items drawn: the zoom stays where the user put it."""
+        self._series = series
+        self._draw()
+        self._hover.setVisible(False)
+        self._crosshair.setVisible(False)
+
+    def set_reference_lines(self, lines: list[ReferenceLine]) -> None:
+        """Draw lines at values, each in its style, labeled beside itself."""
+        self._reference_lines = lines
+        self._draw()
+
+    def _draw(self) -> None:
+        """Draw the series as curves, or as a bar chart's bars, and their legend."""
+        plot = self.getPlotItem()
+        is_bar = self._kind is ChartKind.BAR
+        curve_count, bar_count = (0, len(self._series)) if is_bar else (len(self._series), 0)
+        for items, count, make in (
+            (self._items, curve_count, lambda: plot.plot(connect="finite")),
+            (self._bars, bar_count, self._make_bars),
+        ):
+            while len(items) > count:
+                plot.removeItem(items.pop())
+            while len(items) < count:
+                items.append(make())
+        x_log = self._x_log and not is_bar
+        for item, curve in zip(self._items, self._series):
+            x, y = ChartView.drawn_points(curve, x_log=x_log, y_log=self._y_log)
+            if self._is_step(curve):
+                x, y = ChartView.step_points(x, y)
+            item.setData(np.asarray(x, dtype=float), np.asarray(y, dtype=float))
+            item.opts["name"] = curve.name
+        # the curves draw their log themselves; the bars are given theirs (see `_bar_opts`)
+        plot.setLogMode(x=x_log, y=self._y_log)
+        ticks = [list(enumerate(self._categories))] if is_bar else None
+        plot.getAxis("bottom").setTicks(ticks)
+        self._draw_reference_lines(x_log=x_log)
+        self._apply_styles()
+
+    def _draw_reference_lines(self, *, x_log: bool) -> None:
+        """Draw the reference lines afresh: a log axis takes their logs, as pyqtgraph doesn't."""
+        plot = self.getPlotItem()
+        for item in self._line_items:
+            plot.removeItem(item)
+        self._line_items = []
+        lines = ChartView.drawn_lines(self._reference_lines, x_log=x_log, y_log=self._y_log)
+        for line in lines:
+            is_log = x_log if line.vertical else self._y_log
+            item = pg.InfiniteLine(
+                pos=math.log10(line.value) if is_log else line.value,
+                angle=90 if line.vertical else 0,
+                movable=False,
+                # the label is a format of the line's value: braces of its own are text
+                label=line.label.replace("{", "{{").replace("}", "}}"),
+                # a horizontal one's at its right end, over it; a vertical one's at its
+                # top, left of it (now, after the data)
+                labelOpts={
+                    "position": 0.98,
+                    "anchors": [(1, 0), (1, 0)] if line.vertical else [(1, 1), (1, 1)],
+                },
+            )
+            item.setZValue(1)  # over the series
+            plot.addItem(item)
+            self._line_items.append(item)
+
+    def _make_bars(self) -> pg.BarGraphItem:
+        bars = pg.BarGraphItem(x0=[], height=[], width=1)
+        self.getPlotItem().addItem(bars)
+        return bars
+
+    def shown_range(self) -> tuple[tuple[float, float], tuple[float, float]]:
+        """Get the x and y ranges the chart shows, e.g. zoomed into; not their logs."""
+        (x_min, x_max), (y_min, y_max) = self.getPlotItem().getViewBox().viewRange()
+        if self._x_log and self._kind is not ChartKind.BAR:
+            x_min, x_max = 10**x_min, 10**x_max
+        if self._y_log:
+            y_min, y_max = 10**y_min, 10**y_max
+        return (float(x_min), float(x_max)), (float(y_min), float(y_max))
+
+    def sizeHint(self) -> QSize:  # noqa: N802
+        # not its scene's, which follows its own size: a height it was given once would stay
+        return QSize(*_SIZE_HINT)
+
+    def legend_names(self) -> list[str]:
+        return [label.text for _sample, label in self._legend.items]
+
+    def hover_text(self) -> str:
+        """Get the values the hover shows, empty while the cursor is off the chart."""
+        return str(self._hover.toPlainText()) if self._hover.isVisible() else ""
+
+    def changeEvent(self, event: QEvent) -> None:  # noqa: N802
+        super().changeEvent(event)
+        if event.type() == QEvent.Type.PaletteChange and self._is_built:
+            self._apply_palette()
+
+    def _is_dark(self) -> bool:
+        return bool(self.palette().color(QPalette.ColorRole.Window).lightness() < _DARK_LIGHTNESS)
+
+    def _apply_palette(self) -> None:
+        palette = self.palette()
+        background = palette.color(QPalette.ColorRole.Window)
+        text = palette.color(QPalette.ColorRole.WindowText)
+        self.setBackground(background)
+        plot = self.getPlotItem()
+        for name in ("bottom", "left"):
+            axis = plot.getAxis(name)
+            axis.setPen(text)
+            axis.setTextPen(text)
+        plot.titleLabel.setText(plot.titleLabel.text, color=text)
+        self._legend.setLabelTextColor(text)
+        # over the data, so its names stay readable over a curve or a bar
+        legend_background = QColor(background)
+        legend_background.setAlpha(200)
+        self._legend.setBrush(legend_background)
+        self._hover.setColor(text)
+        crosshair = QColor(text)
+        crosshair.setAlpha(120)
+        self._crosshair.setPen(pg.mkPen(crosshair))
+        self._apply_styles()
+
+    def _apply_styles(self) -> None:
+        is_dark = self._is_dark()
+        background = self.palette().color(QPalette.ColorRole.Window)
+        for index, (item, curve) in enumerate(zip(self._items, self._series)):
+            color = curve.color or series_color(index, is_dark=is_dark)
+            # filled down to 0, e.g. a shape
+            item.setFillLevel(0 if curve.fill else None)
+            item.setBrush(color if curve.fill else None)
+            if ChartView.kind_of(curve, self._kind) is ChartKind.SCATTER:
+                item.setPen(None)
+                # past the palette, around again as triangles
+                item.setSymbol("t" if is_dashed(index) else "o")
+                item.setSymbolSize(_DOT_SIZE)
+                item.setSymbolBrush(color)
+                # a ring of the background: overlapping dots stay apart
+                item.setSymbolPen(pg.mkPen(background, width=1))
+            else:
+                item.setSymbol(None)
+                style = {"dash": [6, 4]} if is_dashed(index) else {}
+                item.setPen(pg.mkPen(color, width=2, **style))
+        all_heights = [
+            np.asarray(ChartView.bar_heights(curve, len(self._categories), y_log=self._y_log))
+            for curve in self._series
+        ]
+        drawn = np.concatenate([[], *all_heights])
+        drawn = drawn[np.isfinite(drawn)]
+        # on a log axis, the bars rise from the power of 10 under the lowest of them
+        base = math.floor(np.log10(drawn.min())) if self._y_log and len(drawn) > 0 else 0
+        for index, (bars, curve, heights) in enumerate(zip(self._bars, self._series, all_heights)):
+            categories = np.flatnonzero(np.isfinite(heights))  # a NaN: no bar
+            tops = np.log10(heights[categories]) if self._y_log else heights[categories]
+            offset, width = ChartView.bar_slot(index, len(self._series))
+            bars.setOpts(
+                x0=categories + offset - width / 2,
+                y0=base,
+                height=tops - base,
+                width=width,
+                brush=curve.color or series_color(index, is_dark=is_dark),
+                # a line of the background between neighbouring bars
+                pen=pg.mkPen(background, width=1),
+                name=curve.name,
+            )
+        text = self.palette().color(QPalette.ColorRole.WindowText)
+        lines = ChartView.drawn_lines(
+            self._reference_lines,
+            x_log=self._x_log and self._kind is not ChartKind.BAR,
+            y_log=self._y_log,
+        )
+        for item, line in zip(self._line_items, lines):
+            ink = QColor(line.color) if line.color is not None else text
+            item.setPen(pg.mkPen(ink, width=1.5, style=_LINE_STYLES[line.style]))
+            item.label.setColor(ink)
+        # the legend's samples draw the styles their items had when added
+        self._legend.clear()
+        for item, curve in zip(self._items or self._bars, self._series):
+            self._legend.addItem(item, curve.name)
+
+    def _on_mouse_clicked(self, event: Any) -> None:
+        if event.button() != Qt.MouseButton.LeftButton or event.double():
+            return  # the right button opens the context menu
+        self.click(event.scenePos())
+
+    def click(self, scene_position: QPointF) -> None:
+        """Emit `point_clicked` for a click at `scene_position`, if it is on the plot."""
+        view_box = self.getPlotItem().getViewBox()
+        if not view_box.sceneBoundingRect().contains(scene_position):
+            return
+        position = view_box.mapSceneToView(scene_position)
+        x, y = position.x(), position.y()
+        # the view's values are their logs on a log axis
+        if self._x_log and self._kind is not ChartKind.BAR:
+            x = 10**x
+        if self._y_log:
+            y = 10**y
+        self.point_clicked.emit(float(x), float(y))
+
+    def _on_mouse_moved(self, event: tuple[Any, ...]) -> None:
+        self.show_hover(event[0])
+
+    def show_hover(self, scene_position: QPointF) -> None:
+        """Show the values nearest `scene_position`'s x, or hide them off the plot."""
+        view_box = self.getPlotItem().vb
+        if not view_box.sceneBoundingRect().contains(scene_position) or len(self._series) == 0:
+            self._hover.setVisible(False)
+            self._crosshair.setVisible(False)
+            return
+        position = view_box.mapSceneToView(scene_position)
+        is_log = self._x_log and self._kind is not ChartKind.BAR
+        # the view's x is its log on a log axis
+        lines = self._hover_lines(10 ** position.x() if is_log else position.x())
+        if len(lines) == 0:  # between a bar chart's categories, or past them
+            self._hover.setVisible(False)
+            self._crosshair.setVisible(False)
+            return
+        self._crosshair.setPos(position.x())
+        self._crosshair.setVisible(True)
+        self._hover.setText("\n".join(lines))
+        self._hover.setPos(position)
+        self._hover.setVisible(True)
+
+    def _hover_lines(self, x: float) -> list[str]:
+        """Get what the hover shows at `x`: where it is, then each series' value there."""
+        x_unit, y_unit = self._units
+        if self._kind is ChartKind.BAR:
+            category = round(x)
+            if not 0 <= category < len(self._categories):
+                return []
+            lines = [self._categories[category]]
+            for curve in self._series:
+                heights = ChartView.bar_heights(curve, len(self._categories), y_log=self._y_log)
+                height = heights[category]
+                if math.isfinite(height):
+                    lines.append(f"{curve.name}: {_format(height, y_unit)}")
+            return lines
+        lines = [_format(x, x_unit)]
+        for curve in self._series:
+            points = ChartView.drawn_points(curve, x_log=self._x_log, y_log=self._y_log)
+            if self._is_step(curve):
+                # the value held there, rather than the next point's
+                held = ChartView.held_value(*points, x)
+                y = None if held is None or math.isnan(held) else held
+            else:
+                point = _nearest(*points, x)
+                y = None if point is None else point[1]
+            if y is not None:
+                lines.append(f"{curve.name}: {_format(y, y_unit)}")
+        return lines
+
+    def _is_step(self, curve: Series) -> bool:
+        """Tell whether `curve` is drawn in steps: a line's points only, not dots."""
+        return curve.step and ChartView.kind_of(curve, self._kind) is ChartKind.LINE
+
+
+def _nearest(x_values: list[float], y_values: list[float], x: float) -> tuple[float, float] | None:
+    """Get the drawn point with the x nearest `x`, None when none is drawn."""
+    xs = np.asarray(x_values, dtype=float)
+    ys = np.asarray(y_values, dtype=float)
+    drawn = np.isfinite(xs) & np.isfinite(ys)
+    if not drawn.any():
+        return None
+    distances = np.where(drawn, np.abs(xs - x), math.inf)
+    index = int(np.argmin(distances))
+    return float(xs[index]), float(ys[index])

composeui/qtcore/widgets/qdatefield.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import datetime
+from typing import Any, Optional
+
+from qtpy.QtCore import QDate, QPoint, Qt
+from qtpy.QtCore import Signal as QtSignal
+from qtpy.QtWidgets import QCalendarWidget, QHBoxLayout, QLineEdit, QToolButton, QWidget
+
+from composeui.core.view import ISO_DATE_FORMAT, format_date, parse_date
+
+#: a calendar's own range, Qt's default, for a limit the view leaves out
+_CALENDAR_FIRST, _CALENDAR_LAST = QDate(-4714, 11, 25), QDate(9999, 12, 31)
+
+
+def _qdate(value: datetime.date) -> QDate:
+    return QDate(value.year, value.month, value.day)
+
+
+class QDateField(QWidget):
+    """A field typing a date as `date_format` says, then a button opening a calendar.
+
+    Qt's date edit can't be empty: this field can, meaning no date. `date_edited` reports
+    the user's dates, typed or picked, and None once the field is emptied; text that isn't
+    a date reports nothing, and leaving the field puts the date back. The calendar, a
+    popup, offers the dates from `minimum` to `maximum`, named in the system's language.
+    """
+
+    #: the user typed or picked a date (a `datetime.date`), or emptied the field (None)
+    date_edited = QtSignal(object)
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._date: Optional[datetime.date] = None
+        self._date_format = ISO_DATE_FORMAT
+        layout = QHBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(2)
+        self.line_edit = QLineEdit()
+        self.line_edit.textEdited.connect(self._read_text)
+        self.line_edit.editingFinished.connect(self._show_date)
+        layout.addWidget(self.line_edit)
+        self.button = QToolButton()
+        self.button.setArrowType(Qt.ArrowType.DownArrow)
+        self.button.clicked.connect(self.open_calendar)
+        layout.addWidget(self.button)
+        self.calendar = QCalendarWidget(self)
+        self.calendar.setWindowFlags(Qt.WindowType.Popup)
+        self.calendar.clicked.connect(self._pick)
+        self.calendar.activated.connect(self._pick)  # Enter on a day
+
+    def set_date(self, value: Optional[datetime.date]) -> None:
+        self._date = value
+        self._show_date()
+
+    def set_date_format(self, date_format: str) -> None:
+        self._date_format = date_format
+        self._show_date()
+
+    def set_range(self, minimum: Optional[datetime.date], maximum: Optional[datetime.date]) -> None:
+        first = _CALENDAR_FIRST if minimum is None else _qdate(minimum)
+        last = _CALENDAR_LAST if maximum is None else _qdate(maximum)
+        self.calendar.setDateRange(first, last)
+
+    def open_calendar(self) -> None:
+        """Show the calendar under the field, on the date, else on today's month."""
+        if self._date is not None:
+            self.calendar.setSelectedDate(_qdate(self._date))
+        else:
+            today = QDate.currentDate()
+            self.calendar.setCurrentPage(today.year(), today.month())
+        self.calendar.move(self.mapToGlobal(QPoint(0, self.height())))
+        self.calendar.show()
+        self.calendar.setFocus()
+
+    def _read_text(self, text: str) -> None:
+        if text.strip() == "":
+            self._edit(None)
+            return
+        try:
+            value = parse_date(text, self._date_format)
+        except ValueError:
+            return  # not a date yet, e.g. halfway through typing one
+        self._edit(value)
+
+    def _pick(self, value: QDate) -> None:
+        # `close`, not `hide`: it also releases the popup's window, which WSLg's
+        # compositor could otherwise keep drawing (see `release_when_hidden`)
+        self.calendar.close()
+        self._edit(datetime.date(value.year(), value.month(), value.day()))
+        self._show_date()
+
+    def _edit(self, value: Optional[datetime.date]) -> None:
+        if value != self._date:
+            self._date = value
+            self.date_edited.emit(value)
+
+    def _show_date(self) -> None:
+        text = "" if self._date is None else format_date(self._date, self._date_format)
+        if self.line_edit.text() != text:
+            self.line_edit.setText(text)

composeui/qtcore/widgets/qexpander.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import Any
+
+from qtpy.QtCore import Qt
+from qtpy.QtCore import Signal as QtSignal
+from qtpy.QtWidgets import QSizePolicy, QToolButton, QVBoxLayout, QWidget
+
+#: pixels the content is indented by, under the header's title
+_INDENT = 20
+
+
+class QExpander(QWidget):
+    """A collapsible section: a header button with an arrow, then its content.
+
+    The content shows only while the section is expanded. `expanded_changed` reports the
+    user's clicks on the header; `set_expanded` is quiet, and so is any change while the
+    expander's signals are blocked (the renderers block them while refreshing).
+    """
+
+    #: the user expanded (True) or collapsed (False) the section
+    expanded_changed = QtSignal(bool)
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        self.header = QToolButton()
+        self.header.setCheckable(True)
+        self.header.setAutoRaise(True)
+        self.header.setToolButtonStyle(Qt.ToolButtonStyle.ToolButtonTextBesideIcon)
+        # the whole row is the header to click, not only its text
+        self.header.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Fixed)
+        # flat: a checkable button draws itself pressed while expanded, not a header's look
+        self.header.setStyleSheet("QToolButton { border: none; padding: 2px 0; }")
+        font = self.header.font()
+        font.setBold(True)
+        self.header.setFont(font)
+        self.header.toggled.connect(self._on_header_toggled)
+        layout.addWidget(self.header)
+        self.content = QWidget()
+        self.content_layout = QVBoxLayout(self.content)
+        # under the title, past the arrow, so a nested section reads as nested
+        self.content_layout.setContentsMargins(_INDENT, 0, 0, 0)
+        layout.addWidget(self.content)
+        self._show_expanded(is_expanded=False)
+
+    def set_expanded(self, is_expanded: bool) -> None:
+        self.header.blockSignals(True)  # noqa: FBT003
+        self.header.setChecked(is_expanded)
+        self.header.blockSignals(False)  # noqa: FBT003
+        self._show_expanded(is_expanded=is_expanded)
+
+    def _show_expanded(self, *, is_expanded: bool) -> None:
+        self.header.setArrowType(Qt.ArrowType.DownArrow if is_expanded else Qt.ArrowType.RightArrow)
+        self.content.setVisible(is_expanded)
+
+    def _on_header_toggled(self, is_expanded: bool) -> None:
+        self._show_expanded(is_expanded=is_expanded)
+        self.expanded_changed.emit(is_expanded)