composeui 0.1.0__py3-none-any.whl

composeui/textualcore/widgets/composebutton.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from textual.widgets import Button
+
+from composeui.core.signal import SignalNoArgs
+
+
+class ComposeButton(Button):
+    """A `Button` re-exposing its presses as a plain composeui `Signal`."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.clicked = SignalNoArgs()
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        event.stop()
+        self.clicked.emit()

composeui/textualcore/widgets/composechart.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import functools
+import math
+from typing import TYPE_CHECKING
+
+from textual.color import Color
+from textual_fspicker import FileSave, Filters
+from textual_fspicker.path_filters import Filter
+from textual_plotext import PlotextPlot
+
+from composeui.core import chartimage
+from composeui.core.chartcolors import series_color
+from composeui.core.signal import Signal
+from composeui.core.view import ChartKind, ChartView
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from textual.app import RenderResult
+
+    from composeui.core.view import ReferenceLine, Series
+
+
+#: the key saving the chart's image
+SAVE_IMAGE_KEY = "s"
+#: the formats the save dialog offers, the vector ones first, by its filters' names
+_IMAGE_FILTERS = {"PDF": "pdf", "SVG": "svg", "PNG": "png"}
+
+
+def _has_suffix(path: Path, suffix: str) -> bool:
+    return path.suffix.lower() == suffix
+
+
+class ComposeChart(PlotextPlot):
+    """A chart drawn with plotext's characters: no zoom or hover in a terminal.
+
+    With the `report` extra, its key `s` asks where to save its image, which
+    `image_path_chosen` emits.
+    """
+
+    can_focus = True
+
+    DEFAULT_CSS = """
+    ComposeChart {
+        height: 20;
+        min-height: 10;
+    }
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.chart_title = ""
+        self.x_label = ""
+        self.y_label = ""
+        self.series: list[Series] = []
+        self.reference_lines: list[ReferenceLine] = []
+        self.kind = ChartKind.LINE
+        self.categories: list[str] = []
+        self.x_log = False
+        self.y_log = False
+        self.image_name = "chart.pdf"
+        self.image_path_chosen: Signal[Path] = Signal()
+        self.set_save_image_text("Save Image")
+
+    def set_save_image_text(self, text: str) -> None:
+        """Describe the key saving the chart's image, e.g. in the app's footer."""
+        self._bindings.key_to_bindings.pop(SAVE_IMAGE_KEY, None)
+        self._bindings.bind(SAVE_IMAGE_KEY, "save_image", text)
+        self.refresh_bindings()
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        if action == "save_image":
+            return chartimage.is_available()  # matplotlib draws the image
+        # Textual asks a widget about its own bindings only
+        return super().check_action(action, parameters)  # pragma: no cover
+
+    def action_save_image(self) -> None:
+        filters = Filters(
+            *(
+                Filter(name, functools.partial(_has_suffix, suffix=f".{suffix}"))
+                for name, suffix in _IMAGE_FILTERS.items()
+            )
+        )
+        dialog = FileSave(filters=filters, default_file=self.image_name)
+        self.app.push_screen(dialog, self._image_path_chosen)
+
+    def _image_path_chosen(self, path: Path | None) -> None:
+        if path is None:
+            return
+        if path.suffix.lstrip(".").lower() not in chartimage.FORMATS:
+            path = path.with_name(f"{path.name}.pdf")
+        self.image_path_chosen.emit(path)
+
+    def render(self) -> RenderResult:
+        # the figure afresh at each render, from the attributes: building a figure with a
+        # log scale takes the log of its data in place, so building it twice would take
+        # the log of the logs. In the theme's colors too, its series' stepped for it
+        self._fill_figure()
+        return super().render()
+
+    def _fill_figure(self) -> None:
+        """Give plotext the chart's title, labels and series."""
+        plt = self.plt
+        plt.clear_figure()
+        plt.title(self.chart_title)
+        plt.xlabel(self.x_label)
+        plt.ylabel(self.y_label)
+        is_dark = self.app.current_theme.dark if self.is_mounted else False
+        colors = [
+            Color.parse(curve.color or series_color(index, is_dark=is_dark)).rgb
+            for index, curve in enumerate(self.series)
+        ]
+        if self.kind is ChartKind.BAR:
+            self._plot_bars(colors)
+        else:
+            self._plot_curves(colors)
+        self._plot_reference_lines()
+
+    def _plot_curves(self, colors: list[tuple[int, int, int]]) -> None:
+        plt = self.plt
+        if self.x_log:
+            plt.xscale("log")
+        if self.y_log:
+            plt.yscale("log")
+        for index, curve in enumerate(self.series):
+            is_dots = ChartView.kind_of(curve, self.kind) is ChartKind.SCATTER
+            draw = plt.scatter if is_dots else plt.plot
+            x, y = ChartView.drawn_points(curve, x_log=self.x_log, y_log=self.y_log)
+            if curve.step and not is_dots:
+                x, y = ChartView.step_points(x, y)
+            # plotext leaves a gap at a NaN itself
+            draw(
+                x,
+                y,
+                label=curve.name,
+                color=colors[index],
+                marker="braille",
+                # down to y = 0, e.g. a shape
+                fillx=curve.fill,
+            )
+
+    def _extent(self) -> tuple[list[float], list[float]]:
+        """Get the x and y the series reach, in plotext's values: a bar chart's x from 1."""
+        if self.kind is ChartKind.BAR:
+            heights = [
+                height
+                for curve in self.series
+                for height in ChartView.bar_heights(curve, len(self.categories), y_log=self.y_log)
+                if math.isfinite(height)
+            ]
+            return [0.5, len(self.categories) + 0.5], heights
+        xs: list[float] = []
+        ys: list[float] = []
+        for curve in self.series:
+            x, y = ChartView.drawn_points(curve, x_log=self.x_log, y_log=self.y_log)
+            xs.extend(value for value in x if math.isfinite(value))
+            ys.extend(value for value in y if math.isfinite(value))
+        return xs, ys
+
+    def _plot_reference_lines(self) -> None:
+        """Draw the reference lines, each labeled at its end, solid: a terminal has no dashes."""
+        is_bar = self.kind is ChartKind.BAR
+        lines = ChartView.drawn_lines(
+            self.reference_lines, x_log=self.x_log and not is_bar, y_log=self.y_log
+        )
+        if len(lines) == 0:
+            return
+        # plotext draws a bar chart's categories from 1
+        offset = 1 if is_bar else 0
+        xs, ys = self._extent()
+        xs += [line.value + offset for line in lines if line.vertical]
+        ys += [line.value for line in lines if not line.vertical]
+        # the theme's text, the axes' own
+        ink = Color.parse(self.app.theme_variables["foreground"]).rgb if self.is_mounted else None
+        for line in lines:
+            color = Color.parse(line.color).rgb if line.color is not None else ink
+            if line.vertical:
+                x = line.value + offset
+                self.plt.vline(x, color)
+                if line.label != "" and len(ys) > 0:
+                    # at its top, left of it (now, after the data)
+                    self.plt.text(line.label, x, max(ys), color, alignment="right")
+            else:
+                self.plt.hline(line.value, color)
+                if line.label != "" and len(xs) > 0:
+                    # over it, at its right end
+                    self.plt.text(line.label, max(xs), line.value, color, alignment="right")
+
+    def _plot_bars(self, colors: list[tuple[int, int, int]]) -> None:
+        if len(self.series) == 0 or len(self.categories) == 0:
+            return
+        heights = [
+            ChartView.bar_heights(curve, len(self.categories), y_log=self.y_log)
+            for curve in self.series
+        ]
+        drawn = [height for bars in heights for height in bars if math.isfinite(height)]
+        base = 0.0
+        if self.y_log:
+            self.plt.yscale("log")
+            # from the power of 10 under the lowest bar: a log axis has no 0
+            base = 10.0 ** math.floor(math.log10(min(drawn))) if len(drawn) > 0 else 1.0
+        # plotext draws numbers only: no bar is a bar from the base to itself
+        heights = [[h if math.isfinite(h) else base for h in bars] for bars in heights]
+        # plotext takes a label and a color per series, as its stub doesn't say
+        self.plt.multiple_bar(  # type: ignore[call-arg]
+            self.categories,
+            heights,
+            labels=[curve.name for curve in self.series],
+            color=colors,  # type: ignore[arg-type]
+            minimum=base,
+        )

composeui/textualcore/widgets/composecheckbox.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from textual.widgets import Checkbox
+
+from composeui.core.signal import Signal
+
+
+class ComposeCheckBox(Checkbox):
+    """A `Checkbox` re-exposing the user's toggles as a plain composeui `Signal`.
+
+    Textual posts `Checkbox.Changed` for any change of `value`, set in code too;
+    `set_checked` keeps those quiet, as Qt's renderers block their widget's signals
+    while refreshing it, so `toggled` only reports the user's toggles.
+    """
+
+    # a form row's field while the row is invalid (see `ROW_INVALID_CLASS`)
+    DEFAULT_CSS = """
+    ComposeCheckBox.-row-invalid {
+        border: tall $error 60%;
+        &:focus {
+            border: tall $error;
+        }
+    }
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.toggled: Signal[bool] = Signal()
+
+    def set_checked(self, is_checked: bool) -> None:
+        with self.prevent(Checkbox.Changed):
+            self.value = is_checked
+
+    def on_checkbox_changed(self, event: Checkbox.Changed) -> None:
+        self.toggled.emit(event.value)

composeui/textualcore/widgets/composecollapsible.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from textual.content import Content
+from textual.widgets import Collapsible
+
+from composeui.core.signal import Signal
+
+if TYPE_CHECKING:
+    from textual.widget import Widget
+
+
+class ComposeCollapsible(Collapsible):
+    """A `Collapsible` re-exposing the user's toggles as a plain composeui `Signal`.
+
+    Textual posts `Collapsible.Expanded`/`Collapsed` for any change of `collapsed`, set
+    in code too; `set_expanded` keeps those quiet, as Qt's renderers block their
+    widget's signals while refreshing it, so `toggled` only reports the user's toggles.
+    The messages bubble: one from a collapsible nested in this one isn't this one's.
+    """
+
+    def __init__(self, *children: Widget) -> None:
+        super().__init__(*children)
+        self.toggled: Signal[bool] = Signal()
+
+    def _watch_title(self, title: str) -> None:
+        # plain text: Textual's own reads the title as markup
+        self._title.label = Content(title)
+
+    def set_expanded(self, is_expanded: bool) -> None:
+        with self.prevent(Collapsible.Expanded, Collapsible.Collapsed):
+            self.collapsed = not is_expanded
+
+    def on_collapsible_expanded(self, event: Collapsible.Expanded) -> None:
+        if event.collapsible is self:
+            self.toggled.emit(True)  # noqa: FBT003
+
+    def on_collapsible_collapsed(self, event: Collapsible.Collapsed) -> None:
+        if event.collapsible is self:
+            self.toggled.emit(False)  # noqa: FBT003

composeui/textualcore/widgets/composecombobox.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from textual.content import Content
+from textual.widgets import Select
+
+from composeui.core.signal import Signal
+
+TValue = TypeVar("TValue")
+
+
+def _options(values: dict[str, TValue]) -> list[tuple[Content, TValue]]:
+    """Get the options of `values`, their labels plain text, not markup."""
+    return [(Content(label), value) for label, value in values.items()]
+
+
+class ComposeComboBox(Select[TValue], Generic[TValue]):
+    """A combobox built from a `{label: value}` mapping."""
+
+    # a form row's field while the row is invalid (see `ROW_INVALID_CLASS`): the border
+    # is the current option's
+    DEFAULT_CSS = """
+    ComposeComboBox.-row-invalid > SelectCurrent {
+        border: tall $error 60%;
+    }
+    ComposeComboBox.-row-invalid:focus > SelectCurrent {
+        border: tall $error;
+    }
+    """
+
+    def __init__(self, values: dict[str, TValue]) -> None:
+        self._values: dict[str, TValue] = dict(values)
+        super().__init__(_options(values))
+        self.value_changed: Signal[TValue | None] = Signal()
+
+    def set_values(self, values: dict[str, TValue]) -> None:
+        """Rebuild the select for a new set of options."""
+        # set in code, not chosen by the user: `value_changed` isn't emitted
+        with self.prevent(Select.Changed):
+            self.set_options(_options(values))
+
+    def set_value(self, value: TValue | None) -> None:
+        with self.prevent(Select.Changed):
+            if value is None:
+                self.value = Select.NULL
+            else:
+                self.value = value
+
+    def current_value(self) -> TValue | None:
+        return self.selection
+
+    def on_select_changed(self, event: Select.Changed) -> None:
+        self.value_changed.emit(self.current_value())

composeui/textualcore/widgets/composedateinput.py

@@ -0,0 +1,325 @@
+from __future__ import annotations
+
+import calendar
+import datetime
+from typing import TYPE_CHECKING, ClassVar, Optional
+
+from rich.style import Style
+from rich.text import Text
+from textual.binding import Binding, BindingType
+from textual.containers import Center, Horizontal, Middle
+from textual.screen import ModalScreen
+from textual.validation import ValidationResult, Validator
+from textual.widget import Widget
+from textual.widgets import Button
+
+from composeui.core.signal import Signal
+from composeui.core.view import ISO_DATE_FORMAT, format_date, parse_date
+from composeui.textualcore.widgets.composeinput import ComposeInput
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from textual import events
+    from textual.app import ComposeResult, RenderResult
+
+#: a day's cell in the month grid: its number right-aligned, after a space
+_CELL_WIDTH = 3
+#: the month grid's lines above its weeks: the month, then the days' names
+_HEADER_LINES = 2
+
+
+class ComposeMonth(Widget, can_focus=True):
+    """A month's days in a grid, a week a line from Monday, the cursor on one day.
+
+    Textual has no calendar. The arrows move the cursor a day or a week, Page Up/Down a
+    month, onto the next month's grid as needed; Enter picks the cursor's day, and a click
+    picks the day under it (or, on the month's line, goes to the month before or after).
+    Days out of `minimum`/`maximum` are dimmed and never picked.
+    """
+
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("left", "move(-1)", show=False),
+        Binding("right", "move(1)", show=False),
+        Binding("up", "move(-7)", show=False),
+        Binding("down", "move(7)", show=False),
+        Binding("pageup", "move_month(-1)", show=False),
+        Binding("pagedown", "move_month(1)", show=False),
+        Binding("enter", "pick", show=False),
+    ]
+
+    COMPONENT_CLASSES: ClassVar[set[str]] = {
+        "month--title",
+        "month--day-name",
+        "month--cursor",
+        "month--picked",
+        "month--out-of-range",
+    }
+
+    DEFAULT_CSS = """
+    ComposeMonth {
+        width: 21;
+        height: 8;
+        & > .month--title {
+            text-style: bold;
+        }
+        & > .month--day-name {
+            color: $foreground 60%;
+        }
+        & > .month--cursor {
+            background: $accent 40%;
+        }
+        &:focus > .month--cursor {
+            background: $accent;
+            color: $text;
+        }
+        & > .month--picked {
+            text-style: bold underline;
+        }
+        & > .month--out-of-range {
+            color: $foreground 30%;
+        }
+    }
+    """
+
+    def __init__(
+        self,
+        picked: datetime.date | None,
+        minimum: datetime.date | None,
+        maximum: datetime.date | None,
+        month_names: Sequence[str] = (),
+        day_names: Sequence[str] = (),
+    ) -> None:
+        super().__init__()
+        self.minimum, self.maximum = minimum, maximum
+        # on the date picked, else on today
+        self.cursor = self._in_range(picked or datetime.datetime.now().astimezone().date())
+        self.picked_date = picked
+        self.month_names = list(month_names) or list(calendar.month_name)[1:]
+        self.day_names = list(day_names) or [name[:2] for name in calendar.day_abbr]
+        #: the user picked a day
+        self.picked: Signal[datetime.date] = Signal()
+
+    def render(self) -> RenderResult:
+        text = Text(no_wrap=True, overflow="crop")
+        width = 7 * _CELL_WIDTH
+        title = f"{self.month_names[self.cursor.month - 1]} {self.cursor.year}"
+        text.append(
+            f"<{title.center(width - 2)}>\n", style=self.get_component_rich_style("month--title")
+        )
+        names = "".join(f"{name[:2]:>{_CELL_WIDTH}}" for name in self.day_names)
+        text.append(f"{names}\n", style=self.get_component_rich_style("month--day-name"))
+        for week in self._weeks():
+            for day in week:
+                if day is None:
+                    text.append(" " * _CELL_WIDTH)
+                    continue
+                styles = []
+                if not self._is_in_range(day):
+                    styles.append("month--out-of-range")
+                if day == self.picked_date:
+                    styles.append("month--picked")
+                if day == self.cursor:
+                    styles.append("month--cursor")
+                style = Style.combine([Style(), *map(self.get_component_rich_style, styles)])
+                text.append(" ")
+                text.append(f"{day.day:>{_CELL_WIDTH - 1}}", style=style)
+            text.append("\n")
+        text.rstrip()
+        return text
+
+    def _weeks(self) -> list[list[datetime.date | None]]:
+        """Get the cursor's month a week a list, Monday first, None out of the month."""
+        month = calendar.Calendar(firstweekday=0)
+        return [
+            [day if day.month == self.cursor.month else None for day in week]
+            for week in month.monthdatescalendar(self.cursor.year, self.cursor.month)
+        ]
+
+    def action_move(self, days: int) -> None:
+        self._move_to(self.cursor + datetime.timedelta(days=days))
+
+    def action_move_month(self, months: int) -> None:
+        month = self.cursor.month - 1 + months
+        year, month = self.cursor.year + month // 12, month % 12 + 1
+        day = min(self.cursor.day, calendar.monthrange(year, month)[1])
+        self._move_to(datetime.date(year, month, day))
+
+    def action_pick(self) -> None:
+        if self._is_in_range(self.cursor):
+            self.picked.emit(self.cursor)
+
+    def on_click(self, event: events.Click) -> None:
+        if event.y == 0:
+            self.action_move_month(-1 if event.x < 7 * _CELL_WIDTH // 2 else 1)
+            return
+        week, column = event.y - _HEADER_LINES, event.x // _CELL_WIDTH
+        weeks = self._weeks()
+        if 0 <= week < len(weeks) and 0 <= column < len(weeks[week]):
+            day = weeks[week][column]
+            if day is not None and self._is_in_range(day):
+                self.cursor = day
+                self.picked.emit(day)
+
+    def _move_to(self, day: datetime.date) -> None:
+        self.cursor = self._in_range(day)
+        self.refresh()
+
+    def _is_in_range(self, day: datetime.date) -> bool:
+        return (self.minimum is None or day >= self.minimum) and (
+            self.maximum is None or day <= self.maximum
+        )
+
+    def _in_range(self, day: datetime.date) -> datetime.date:
+        if self.minimum is not None and day < self.minimum:
+            return self.minimum
+        if self.maximum is not None and day > self.maximum:
+            return self.maximum
+        return day
+
+
+class ComposeCalendar(ModalScreen[Optional[datetime.date]]):
+    """A month grid over the app: dismissed with the day picked, or None on Escape."""
+
+    BINDINGS: ClassVar[list[BindingType]] = [Binding("escape", "dismiss_none", show=False)]
+
+    DEFAULT_CSS = """
+    ComposeCalendar {
+        align: center middle;
+        & ComposeMonth {
+            border: round $accent;
+            padding: 0 1;
+            width: 25;
+            height: 10;
+            background: $surface;
+        }
+    }
+    """
+
+    def __init__(self, month: ComposeMonth) -> None:
+        super().__init__()
+        self.month = month
+        month.picked.connect(self._dismiss_with)
+
+    def compose(self) -> ComposeResult:
+        with Middle(), Center():
+            yield self.month
+
+    def on_mount(self) -> None:
+        self.month.focus()
+
+    def action_dismiss_none(self) -> None:
+        self.dismiss(None)
+
+    def _dismiss_with(self, day: datetime.date) -> None:
+        self.dismiss(day)
+
+
+class _DateValidator(Validator):
+    """A date as the field's format says, within its range; no date at all is valid too."""
+
+    def __init__(self, field: ComposeDateInput) -> None:
+        super().__init__()
+        self.field = field
+
+    def validate(self, value: str) -> ValidationResult:
+        if value.strip() == "":
+            return self.success()
+        try:
+            date = parse_date(value, self.field.date_format)
+        except ValueError:
+            return self.failure()
+        minimum, maximum = self.field.minimum, self.field.maximum
+        if (minimum is not None and date < minimum) or (maximum is not None and date > maximum):
+            return self.failure()
+        return self.success()
+
+
+class ComposeDateInput(Horizontal):
+    """A field typing a date as `date_format` says, then a button opening a calendar.
+
+    `date_edited` reports the user's dates, typed or picked, and None once the field is
+    emptied: never a date set in code (`set_date`), though Textual posts its field's
+    changes either way. Text that isn't a date, or a date out of range, marks the field
+    invalid; text that isn't a date reports nothing, and leaving the field puts the date
+    back.
+    """
+
+    DEFAULT_CSS = """
+    ComposeDateInput {
+        height: auto;
+        & > ComposeInput {
+            width: 1fr;
+        }
+        & > Button {
+            min-width: 5;
+            width: 5;
+        }
+        &.-row-invalid > ComposeInput {
+            border: tall $error 60%;
+            &:focus {
+                border: tall $error;
+            }
+        }
+    }
+    """
+
+    def __init__(self) -> None:
+        self.input = ComposeInput(validators=[])
+        self.button = Button("▾")
+        super().__init__(self.input, self.button)
+        self.input.validators.append(_DateValidator(self))
+        self.date_format = ISO_DATE_FORMAT
+        self.minimum: datetime.date | None = None
+        self.maximum: datetime.date | None = None
+        self.month_names: list[str] = []
+        self.day_names: list[str] = []
+        self._date: datetime.date | None = None
+        self.date_edited: Signal[datetime.date | None] = Signal()
+        self.input.value_changed.connect(self._read_text)
+        self.input.value_submitted.connect(self._show_date)
+
+    def set_date(self, value: datetime.date | None) -> 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 open_calendar(self) -> None:
+        """Show the calendar on the date, else on today."""
+        month = ComposeMonth(
+            self._date, self.minimum, self.maximum, self.month_names, self.day_names
+        )
+        self.app.push_screen(ComposeCalendar(month), self._pick)
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        event.stop()
+        self.open_calendar()
+
+    def _pick(self, value: datetime.date | None) -> None:
+        if value is not None:
+            self._edit(value)
+            self._show_date()
+        self.input.focus()
+
+    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 _edit(self, value: datetime.date | None) -> 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.input.value != text:
+            self.input.value = text