nice-dialogs 1.3.0__py3-none-any.whl

nice_dialogs/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "1.3.0"

nice_dialogs/dialogs/__init__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from .confirmation import ConfirmationDialog
+from .cron_editor import CronEditorDialog
+from .datetime_picker import DatetimePickerDialog
+from .labelmaker import LabelMakerDialog
+from .upload_file import UploadFileDialog
+
+__all__ = [
+    "ConfirmationDialog",
+    "CronEditorDialog",
+    "DatetimePickerDialog",
+    "LabelMakerDialog",
+    "UploadFileDialog",
+]

nice_dialogs/dialogs/confirmation.py

@@ -0,0 +1,111 @@
+"""This module implements a simple Yes/No confirmation dialog with a few useful
+extra options.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from nicegui import ui
+
+
+@dataclass
+class ConfirmationDialogModel:
+    """Data model for a confirmation dialog.
+
+    Attributes allow customization of dialog elements, which allows the dialog
+    to be used in various situations that require custom messaging and light
+    theming. The text style of the message itself can be set by providing
+    Tailwind classes in the `message_text_classes` attribute, or customized
+    more directly using CSS with the `message_text_style` attribute; these are applied
+    to the `classes` and `style` of the message `ui.label` component, respectively.
+    """
+
+    icon: str = "warning"
+    icon_color: str = "warning"
+    yes_button_label: str = "Yes"
+    yes_button_color: str = "positive"
+    no_button_label: str = "No"
+    no_button_color: str = "negative"
+    remember: bool = False
+    yes_return_value: Any = True
+    no_return_value: Any = False
+    show_remember_checkbox: bool = False
+    remember_checkbox_color: str = "accent"
+    message_text_classes: str = "font-medium"
+    message_text_style: str = ""
+
+
+class ConfirmationDialog(ui.dialog):
+    """A NiceGUI dialog box presenting a simple yes/no confirmation.
+
+    Other than the required `dialog_title` and `message`, any keyword arguments are
+    passed along to the dialog's data model, which can control the wording and
+    color of the Yes/No options, as well as the displayed icon, and whether the
+    "remember my choice" checkbox is enabled.
+
+    When awaited, the dialog will always return a tuple of the configured return value
+    of the selected button and the state of the "remember" checkbox, irrespective
+    of whether it was displayed.
+
+    By default, the "yes"/"no" buttons return a bool `True`/`False` respectively,
+    but these values can be customized via the data model.
+    """
+
+    dialog_title: str
+    message: str
+    model: ConfirmationDialogModel
+
+    def __init__(
+        self,
+        *,
+        dialog_title: str = "Confirmation",
+        message: str = "Are you sure?",
+        **kwargs: Any,
+    ) -> None:
+        """Initialize the dialog and its components."""
+        super().__init__()
+        self.dialog_title = dialog_title
+        self.message = message
+        self.model = ConfirmationDialogModel(**kwargs)
+        self.dialog_layout()
+
+    if TYPE_CHECKING:
+
+        def __await__(self) -> Generator[None, None, tuple[Any, bool]]: ...
+
+    def dialog_layout(self) -> None:
+        with self, ui.card():
+            ui.label(self.dialog_title).classes("font-bold text-3xl")
+            with ui.row().classes("w-full items-center flex"):
+                ui.icon(
+                    self.model.icon, size="4rem", color=self.model.icon_color
+                ).classes("flex-none")
+                ui.label(self.message).classes(
+                    f"flex-1 {self.model.message_text_classes}"
+                ).style(self.model.message_text_style)
+
+            with ui.card_actions().classes("w-full align-left"):
+                with ui.row().classes("flex w-full"):
+                    ui.button(
+                        self.model.yes_button_label,
+                        color=self.model.yes_button_color,
+                        on_click=lambda: self.submit(
+                            (self.model.yes_return_value, self.model.remember)
+                        ),
+                    ).mark("confirm_yes")
+                    ui.button(
+                        self.model.no_button_label,
+                        color=self.model.no_button_color,
+                        on_click=lambda: self.submit(
+                            (self.model.no_return_value, self.model.remember)
+                        ),
+                    ).mark("confirm_no")
+                with ui.row().classes("flex w-full justify-end"):
+                    ui.checkbox("Don't ask me again").classes("scale-75").props(
+                        f"color={self.model.remember_checkbox_color}"
+                    ).bind_value_to(self, ("model", "remember")).bind_visibility_from(
+                        self, ("model", "show_remember_checkbox")
+                    ).tooltip("Remember my preference for this confirmation.")

nice_dialogs/dialogs/cron_editor.py

@@ -0,0 +1,336 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from itertools import islice
+from typing import TYPE_CHECKING
+
+from nicegui import ui
+from pydantic import ValidationError
+from pydantic_extra_types.cron import CronStr
+
+if TYPE_CHECKING:
+    from .types import ValueChangeEventArguments
+
+
+MINUTE_OPTIONS = {
+    "*": "Every (*)",
+    "0": "HH:00",
+    "*/15": "Every 15 minutes",
+    "*/30": "Every 30 minutes",
+}
+"""Default set of cron-minute options."""
+
+HOUR_OPTIONS = {
+    "*": "Every (*)",
+    "*/4": "Every 4 hours",
+    "*/8": "Every 8 hours",
+    "*/12": "Every 12 hours",
+    "0": "Midnight",
+    "12": "Noon",
+}
+"""Default set of cron-hour options."""
+
+# January 1, 2023 was a Sunday
+WEEKDAY_OPTIONS = {
+    "*": "Every (*)",
+    "1-5": "Weekdays",
+    "0,6": "Weekends",
+} | {str(i): datetime(2023, 1, i + 8, tzinfo=UTC).strftime("%A") for i in range(7)}
+"""Default set of cron-day-of-week options."""
+
+DAY_OPTIONS = {"*": "Every (*)"}
+"""Default set of cron-day-of-month options."""
+
+MONTH_OPTIONS = {"*": "Every (*)"} | {
+    str(n): datetime(1970, n, 1, tzinfo=UTC).strftime("%B") for n in range(1, 13)
+}
+"""Default set of cron-month options (12 months)"""
+
+
+@dataclass
+class CronEditorModel:
+    minute: str = "*"
+    hour: str = "*"
+    dom: str = "*"
+    month: str = "*"
+    dow: str = "*"
+    cron: CronStr = field(init=False)
+    is_valid: bool = field(init=False, default=True)
+
+    def __post_init__(self) -> None:
+        try:
+            self.cron = CronStr(str(self))
+        except (ValueError, ValidationError):
+            self.is_valid = False
+
+    def __repr__(self) -> str:
+        return f"{self.minute} {self.hour} {self.dom} {self.month} {self.dow}"
+
+
+class CronEditorDialog(ui.dialog):
+    """NiceGUI Dialog displaying a Cron Expression Editor.
+
+    Two action buttons are available: "Done" returns the current cron expression string;
+    "Cancel" returns None.
+
+    This dialog is created with the initial cron expression of "* * * * *". This
+    expression can be replaced by calling the `reset` method with a new cron expression
+    string.
+
+    If an invalid cron expression is used to create or reset the dialog, a notification
+    will alert the user, but the dialog will remain open in order to allow the user to
+    correct the expression.
+
+    The dialog cannot be closed with a positive action if the cron expression is
+    invalid.
+
+    The dialog's `reset` button can be used to set the cron expression back to an
+    initial expression, which is whatever value was first used to create or set the
+    dialog, which will be `* * * * *` in the default case.
+
+    Attributes
+    ----------
+    dialog_title: str
+        The title displayed at the top of the dialog.
+
+    model: CronEditorModel
+        A data model of the current cron expression, which includes string fields
+        for each cron part and a `CronStr` object for validation and scheduling.
+
+    initial_expression: str
+        The initial cron expression used with the dialog when it is first opened.
+    """
+
+    dialog_title: str
+    model: CronEditorModel
+    initial_expression: str
+
+    def __init__(
+        self,
+        *,
+        dialog_title: str = "Cron Expression Editor",
+    ) -> None:
+        super().__init__()
+        self.dialog_title = dialog_title
+        self.initial_expression = ""
+        self.reset()
+        self.dialog_layout()
+
+    if TYPE_CHECKING:
+
+        def __await__(self) -> Generator[None, None, str | None]: ...
+
+    def reset(self, cron: str | None = None) -> None:
+        """Set the dialog to its initial state or to a provided cron expression by
+        establishing or replacing the dialog's data model.
+
+        If the provided cron expression is valid and contains novel tokens, those
+        tokens will be added to the options of the relevant select components.
+
+        This method is called when the dialog is first created, and can be called
+        at any time to set the dialog to a specific new cron expression.
+        """
+        # Set the dialog's initial or fallback expression on first method call
+        self.initial_expression = self.initial_expression or cron or "* * * * *"
+
+        # Set the data model using the provided cron expression or the fallback
+        cron = cron or self.initial_expression
+        self.model = CronEditorModel(*cron.split())
+
+        if self.model.is_valid:
+            self.update_input_options()
+        else:
+            ui.notify(f"Invalid cron expression: {cron}", type="negative")
+
+    def update_input_options(self) -> None:
+        """Add novel cron expression tokens to the options of the select components.
+
+        When used interactively, users may input arbitrary cron expression tokens,
+        and the select element will accept them as new options.
+
+        When the dialog is set programatically, as with the `reset` method, we have to
+        manually add any novel tokens to those select options.
+        """
+        if TYPE_CHECKING:
+            # all select options in this implementation are dicts
+            assert isinstance(self.minute_select.options, dict)
+            assert isinstance(self.hour_select.options, dict)
+            assert isinstance(self.dom_select.options, dict)
+            assert isinstance(self.month_select.options, dict)
+            assert isinstance(self.dow_select.options, dict)
+
+        # The module constants providing default options for each component are
+        # never mutated, so are merged with the existing and novel options.
+        try:
+            if self.model.minute not in self.minute_select.options:
+                self.minute_select.set_options(
+                    {self.model.minute: self.model.minute}
+                    | self.minute_select.options
+                    | MINUTE_OPTIONS
+                )
+
+            if self.model.hour not in self.hour_select.options:
+                self.hour_select.set_options(
+                    {self.model.hour: self.model.hour}
+                    | self.hour_select.options
+                    | HOUR_OPTIONS
+                )
+
+            if self.model.dom not in self.dom_select.options:
+                self.dom_select.set_options(
+                    {self.model.dom: self.model.dom}
+                    | self.dom_select.options
+                    | DAY_OPTIONS
+                )
+
+            if self.model.month not in self.month_select.options:
+                self.month_select.set_options(
+                    {self.model.month: self.model.month}
+                    | self.month_select.options
+                    | MONTH_OPTIONS
+                )
+
+            if self.model.dow not in self.dow_select.options:
+                self.dow_select.set_options(
+                    {self.model.dow: self.model.dow}
+                    | self.dow_select.options
+                    | WEEKDAY_OPTIONS
+                )
+        except AttributeError:
+            # When called before the dialog fully is rendered, some select components
+            # may not yet be created.
+            pass
+
+    def dialog_layout(self) -> None:
+        with self, ui.card():
+            ui.label(self.dialog_title).classes("font-bold text-3xl")
+            with ui.row().classes("flex w-full"):
+                # cron expression display with copy button
+                ui.code().classes(
+                    "text-2xl/8 text-center",
+                ).bind_content_from(
+                    target_object=self,
+                    target_name="model",
+                    backward=lambda x: str(x),
+                ).classes("flex-1").mark("cron-expression-display")
+            with ui.row().classes("flex w-full"):
+                # 5 x dropdown selectors
+                self.minute_select = (
+                    ui.select(
+                        MINUTE_OPTIONS,
+                        label="Minute",
+                        with_input=True,
+                        new_value_mode="add-unique",
+                        on_change=self.handle_cron_change,
+                    )
+                    .classes("w-1/6 flex-1")
+                    .bind_value(self, ("model", "minute"))
+                    .mark(
+                        "minute",
+                    )
+                )
+                self.hour_select = (
+                    ui.select(
+                        HOUR_OPTIONS,
+                        label="Hour",
+                        with_input=True,
+                        new_value_mode="add-unique",
+                        on_change=self.handle_cron_change,
+                    )
+                    .classes("w-1/6 flex-1")
+                    .bind_value(self, ("model", "hour"))
+                    .mark(
+                        "hour",
+                    )
+                )
+                self.dom_select = (
+                    ui.select(
+                        DAY_OPTIONS,
+                        label="Day",
+                        with_input=True,
+                        new_value_mode="add-unique",
+                        on_change=self.handle_cron_change,
+                    )
+                    .classes("w-1/6 flex-1")
+                    .bind_value(self, ("model", "dom"))
+                    .mark("dom")
+                )
+                self.month_select = (
+                    ui.select(
+                        MONTH_OPTIONS,
+                        label="Month",
+                        with_input=True,
+                        new_value_mode="add-unique",
+                        on_change=self.handle_cron_change,
+                    )
+                    .classes("w-1/6 flex-1")
+                    .bind_value(self, ("model", "month"))
+                    .mark(
+                        "month",
+                    )
+                )
+                self.dow_select = (
+                    ui.select(
+                        WEEKDAY_OPTIONS,
+                        label="Weekday",
+                        with_input=True,
+                        new_value_mode="add-unique",
+                        on_change=self.handle_cron_change,
+                    )
+                    .classes("w-1/6 flex-1")
+                    .bind_value(self, ("model", "dow"))
+                    .mark("dow")
+                )
+
+            with ui.column().classes("w-full"):
+                ui.label("Next 5 Runs").classes("text-sm text-gray-400 font-medium")
+                self.show_next_runs()
+
+            with ui.card_actions().classes("w-full align-left"):
+                with ui.row().classes("flex w-full items-end"):
+                    ui.button(
+                        "Done",
+                        color="positive",
+                        on_click=lambda: self.submit(str(self.model)),
+                    ).bind_enabled_from(self, ("model", "is_valid")).mark("done")
+                    ui.button(
+                        "Cancel",
+                        color="negative",
+                        on_click=lambda: self.submit(None),
+                    ).mark("cancel")
+                    ui.space()
+                    ui.label("Reset").classes(
+                        "text-sm text-negative font-medium cursor-pointer"
+                    ).on("click", self.reset).tooltip(
+                        f"{self.initial_expression}"
+                    ).mark("reset")
+
+    def handle_cron_change(self, event: ValueChangeEventArguments) -> None:
+        """Callback handler from cron expression selectors"""
+        try:
+            self.model.cron = CronStr(str(self.model))
+            self.model.is_valid = True
+            self.show_next_runs.refresh()
+        except (ValueError, ValidationError) as e:
+            self.model.is_valid = False
+            ui.notify(e, type="negative")
+
+    @ui.refreshable_method
+    def show_next_runs(self) -> None:
+        """Refreshable method to display the next five events according to the
+        current cron schedule.
+        """
+        now = datetime.now(tz=UTC)
+        for i, run in enumerate(islice(self.model.cron.schedule(), 5)):
+            until_run = run - now
+            with ui.row().classes("w-full items-center"):
+                ui.label(str(i + 1)).classes(
+                    "text-xs bg-accent text-white px-2 py-1 rounded",
+                )
+                ui.label(f"{run:%a, %d-%b %Y at %I:%M %p %z}")
+                ui.space()
+                ui.label(
+                    f"in {until_run.days} days, {until_run.seconds // 3600} hours",
+                ).classes("text-sm text-gray-400")

nice_dialogs/dialogs/datetime_picker.py

@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime, time, tzinfo
+from enum import IntFlag, auto
+from typing import TYPE_CHECKING
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from nicegui import ui
+
+if TYPE_CHECKING:
+    from .types import ValueChangeEventArgumentsBool, ValueChangeEventArgumentsStr
+
+
+class DialogOptions(IntFlag):
+    """Dialog option flags."""
+
+    DISPLAY_12H = auto()
+    """Whether to display time in 12h format. This option does not affect the returned
+    datetime value, which is always timezone-aware in UTC.
+    """
+
+    FREEZE_TZ = auto()
+    """Whether to disallow changes to the timezone input. The timezone input may be
+    visible but not editable.
+    """
+
+    HIDE_TZ = auto()
+    """Whether to hide the timezone input. The timezone input is shown by default."""
+
+
+@dataclass
+class DatetimePickerModel:
+    """Data model for the datetime picker dialog.
+
+    Private (`init=False`) fields are used for binding with the dialog input components.
+
+    The dialog's callbacks will manage the model's fields, and the `dt` property will
+    always return a timezone-aware datetime in UTC.
+    """
+
+    ts: float
+    tz: tzinfo = UTC
+    options: DialogOptions = field(default_factory=lambda: DialogOptions(0))
+    _date: str = field(init=False, default="")
+    _time: str = field(init=False, default="")
+
+    @property
+    def dt(self) -> datetime:
+        """Returns a timezone-aware datetime in UTC."""
+        return datetime.fromtimestamp(self.ts, tz=UTC)
+
+    @property
+    def localdt(self) -> datetime:
+        """Returns a timezone-aware datetime in the specified timezone."""
+        return datetime.fromtimestamp(self.ts, tz=self.tz)
+
+
+class DatetimePickerDialog(ui.dialog):
+    """NiceGUI Dialog displaying a Datetime Picker.
+
+    Two action buttons are available: "Done" returns the selected datetime;
+    "Cancel" returns None.
+
+    The user may select any timezone they wish when using the dialog, but the returned
+    value is always timezone-aware in UTC.
+
+    Notes
+    -----
+    - The timezone input is a freeform input field, but we check that its value is
+      matched to a known timezone before updating the model.
+    - The model stores the datetime as a UTC POSIX timestamp.
+    """
+
+    dialog_title: str
+    model: DatetimePickerModel
+
+    def __init__(
+        self,
+        initial_ts: int | float | None = None,
+        *,
+        dialog_title: str = "Datetime Picker",
+        hide_timezone: bool = False,
+        freeze_timezone: bool = False,
+    ) -> None:
+        super().__init__()
+        self.dialog_title = dialog_title
+        if initial_ts is None:
+            initial_ts = datetime.now(UTC).timestamp()
+        self.model = DatetimePickerModel(ts=initial_ts, tz=UTC)
+
+        if hide_timezone:
+            self.model.options ^= DialogOptions.HIDE_TZ
+        if freeze_timezone:
+            self.model.options ^= DialogOptions.FREEZE_TZ
+
+        self.dialog_layout()
+
+    if TYPE_CHECKING:
+
+        def __await__(self) -> Generator[None, None, datetime | None]: ...
+
+    def dialog_layout(self) -> None:
+        with self, ui.card():
+            ui.label(self.dialog_title).classes("font-bold text-3xl")
+            with ui.row().classes("flex w-full"):
+                ui.date_input("Date").classes("flex-1 w-2/5").bind_value(
+                    self,
+                    ("model", "_date"),
+                    strict=False,
+                ).on_value_change(self.handle_datetime_change).mark("date")
+
+                ui.time_input("Time").classes("flex-1 w-2/5").bind_value(
+                    self,
+                    ("model", "_time"),
+                    strict=False,
+                ).on_value_change(self.handle_datetime_change).mark("time")
+
+                # The tz input is not bound the model; instead, updates are
+                # handled through the validation callback
+                self.tz_input = (
+                    ui.input(
+                        "Timezone",
+                        value=str(self.model.tz),
+                    )
+                    .classes("flex-1 w-1/5")
+                    .props("debounce=1000")
+                    .bind_enabled_from(
+                        self,
+                        ("model", "options"),
+                        backward=lambda o: not o & DialogOptions.FREEZE_TZ,
+                    )
+                    .bind_visibility_from(
+                        self,
+                        ("model", "options"),
+                        backward=lambda o: not o & DialogOptions.HIDE_TZ,
+                    )
+                    .mark("timezone")
+                )
+                self.tz_input.validation = self.validate_timezone
+
+            with ui.card_actions().classes("w-full align-left"):
+                with ui.row().classes("flex w-full"):
+                    ui.button(
+                        "Done",
+                        color="positive",
+                        on_click=lambda: self.submit(self.model.dt),
+                    ).mark(
+                        "done",
+                    )
+                    ui.button(
+                        "Cancel",
+                        color="negative",
+                        on_click=lambda: self.submit(None),
+                    ).mark("cancel")
+                    ui.space()
+                    with ui.dropdown_button("Options", color="accent"):
+                        ui.switch(text="24h").on_value_change(
+                            self.handle_24h_option_change,
+                        ).bind_value_from(
+                            self,
+                            ("model", "options"),
+                            backward=lambda o: not o & DialogOptions.DISPLAY_12H,
+                        )
+
+    def handle_24h_option_change(self, e: ValueChangeEventArgumentsBool) -> None:
+        """Callback handler for 24h display option toggle."""
+        # Instead of an XOR toggle, we are explicit in setting or clearing the
+        # flag in order to keep the model consistent with the state of the UI.
+        if e.value:
+            # Clear the 12h display option flag
+            self.model.options &= ~DialogOptions.DISPLAY_12H
+        else:
+            # Set the 12h display option flag
+            self.model.options |= DialogOptions.DISPLAY_12H
+
+        # propagate the option change to the model's string fields
+        self.tz_input.validate()
+
+    def handle_datetime_change(
+        self,
+        e: ValueChangeEventArgumentsStr | None = None,
+    ) -> None:
+        """Callback handler from datetime selectors.
+
+        The model's timestamp is updated based on the date and time input values in UTC.
+        """
+        # the date and time inputs are bound to the model
+        try:
+            d = date.fromisoformat(self.model._date)
+            t = time.fromisoformat(self.model._time)
+        except (TypeError, ValueError):
+            # case if either input is not yet populated
+            return None
+
+        # update the model timestamp based on the date and time input values
+        local_dt = datetime.combine(d, t, tzinfo=self.model.tz)
+        self.model.ts = local_dt.astimezone(UTC).timestamp()
+
+    def validate_timezone(self, value: str) -> str | None:
+        """Validation and update handler for timezone input.
+
+        The timezone input is a freeform input field, but we check that its
+        value is matched to a known timezone before updating the model.
+        """
+        try:
+            # validate and update the model
+            self.model.tz = ZoneInfo(value)
+
+            time_format = (
+                "%I:%M %p"
+                if self.model.options & DialogOptions.DISPLAY_12H
+                else "%H:%M"
+            )
+
+            # propagate the timezone change to the model's string fields
+            # these bound properties will update the UI inputs
+            self.model._date = f"{self.model.localdt.date()}"
+            self.model._time = self.model.localdt.timetz().strftime(time_format)
+        except ZoneInfoNotFoundError as e:
+            return f"Invalid timezone: {e}"
+        except Exception as e:
+            return f"Error processing timezone: {e}"
+
+        return None

nice_dialogs/dialogs/labelmaker.py

@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from enum import Enum, EnumType, IntFlag, StrEnum, auto
+from functools import partial
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Any, Literal, get_args, get_origin
+
+from nicegui import ui
+
+# SortableJS support is added in NiceGUI 3.11
+if TYPE_CHECKING:
+    if find_spec("nicegui.elements.sortable") is not None:
+        from nicegui.events import (  # type: ignore[attr-defined, unused-ignore]
+            SortableEventArguments,
+        )
+    else:
+        type SortableEventArguments = Any  # type: ignore[no-redef]
+
+
+SORTABLE_AVAILABLE = find_spec("nicegui.elements.sortable") is not None
+"""Module-level constant for whether the sortable component is available, which
+dependson NiceGUI >= 3.11.
+"""
+
+
+class DialogOptions(IntFlag):
+    """Dialog option flags."""
+
+    ALLOW_SORTABLE = auto()
+    """Whether the label list can be sorted by dragging and dropping."""
+
+    USE_DEFAULT_VALIDATOR = auto()
+    """Whether to use the default validator, which checks that fields are not empty."""
+
+
+@dataclass
+class LabelMakerModel:
+    """Data model for the label maker dialog."""
+
+    num_inputs: int = 2
+    inputs: list[ui.input | ui.select] = field(default_factory=list)
+    input_labels: list[str] = field(default_factory=list)
+    values: list[tuple[str, ...]] = field(default_factory=list)
+    validators: list[dict[str, Any]] = field(default_factory=list)
+    value_types: list[type | StrEnum | list[str]] = field(default_factory=list)
+    options: DialogOptions = field(default_factory=lambda: DialogOptions(0))
+    default_validator: dict[str, Any] = field(init=False, default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """For fields that are expected to be the same length as the number of
+        inputs, fill in any missing values with defaults.
+        """
+        if len(self.input_labels) < self.num_inputs:
+            # fill in any missing input labels with empty label
+            for _ in range(len(self.input_labels), self.num_inputs):
+                self.input_labels.append("")
+        if len(self.value_types) < self.num_inputs:
+            # fill in any missing value types with str
+            for _ in range(len(self.value_types), self.num_inputs):
+                self.value_types.append(str)
+
+    @property
+    def all_valid(self) -> bool:
+        """Returns whether all input fields currently have valid values."""
+        return all([_input.validate() for _input in self.inputs])
+
+
+class LabelMakerDialog(ui.dialog):
+    """The labelmaker dialog is an interface for applying label-based metadata
+    to an arbitrary object. The default type of "label" is a key-value pair, but
+    the dialog can be initialized with any number of input fields, and the return
+    value is a list of tuples. This leaves the formatting of the labels up to the
+    caller.
+
+    Labels are displayed in a list, can be reordered by dragging and dropping, and
+    can be removed by clicking a delete button.
+    """
+
+    dialog_title: str
+    model: LabelMakerModel
+
+    def __init__(
+        self,
+        dialog_title: str = "List Editor",
+        *,
+        allow_sorting: bool = True,
+        use_default_validator: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        """Dialog class for creating and editing sets of labels.
+
+        Other than `dialog_title`, all parameters are passed to the `LabelMakerModel`
+        dataclass, including seed values for the label list and input field validators.
+
+        By default, the input fields are simple text inputs for string values,
+        but if the `value_types` parameter is set to a list of types and the type
+        at position *n* is a `Literal`, the input at position *n* will be a select
+        component with options generated from the matching `Literal`. Likewise,
+        if this type is an `Enum`, then the input will be a select with options
+        generated from the enum names (or values, in the case of a `StrEnum`).
+        Finally if the type is a list of strings, these will be used as options
+        for a select input.
+
+        Once populated, the dialog handles all values as strings, and results
+        are not cast back to the original types.
+        """
+        super().__init__()
+        self.dialog_title = dialog_title
+        self.model = LabelMakerModel(**kwargs)
+
+        if SORTABLE_AVAILABLE and allow_sorting:
+            self.model.options |= DialogOptions.ALLOW_SORTABLE
+
+        if use_default_validator:
+            self.model.options |= DialogOptions.USE_DEFAULT_VALIDATOR
+            self.model.default_validator["Input must not be empty"] = lambda v: (
+                len(v) > 0 if v is not None else False
+            )
+
+        self.dialog_layout()
+
+    if TYPE_CHECKING:
+
+        def __await__(self) -> Generator[None, None, list[tuple[str, ...]] | None]: ...
+
+    def dialog_layout(self) -> None:
+        with self, ui.card().classes("w-[96vw] max-w-[96vw]"):
+            ui.label(self.dialog_title).classes("font-bold text-3xl")
+
+            with ui.row().classes("flex w-full items-start"):
+                # an input or select field for each label component
+                for i in range(0, self.model.num_inputs):
+                    input_element: ui.input | ui.select | None = None
+                    value_type = self.model.value_types[i]
+                    input_label = self.model.input_labels[i]
+
+                    if get_origin(value_type) is Literal:
+                        input_element = ui.select(
+                            options=list(get_args(value_type)),
+                        )
+                    elif isinstance(value_type, EnumType) and issubclass(
+                        value_type, StrEnum
+                    ):
+                        input_element = ui.select(
+                            options=[option for option in value_type],
+                        )
+                    elif isinstance(value_type, EnumType) and issubclass(
+                        value_type, Enum
+                    ):
+                        input_element = ui.select(
+                            options=[option.name for option in value_type],
+                        )
+                    elif isinstance(value_type, list):
+                        input_element = ui.select(options=value_type)
+                    else:
+                        # All other cases result in an ordinary text input
+                        input_element = ui.input()
+
+                    if TYPE_CHECKING:
+                        assert input_element is not None
+
+                    input_element.classes(add="flex-1").props("clearable").set_label(
+                        input_label
+                    )
+
+                    # Create a non-mutating copy of the provided validator for
+                    # the input and optionally apply the default validators.
+                    validators: dict[str, Any]
+                    try:
+                        validators = {**self.model.validators[i]}
+                    except IndexError:
+                        validators = {}
+
+                    if DialogOptions.USE_DEFAULT_VALIDATOR in self.model.options:
+                        validators |= self.model.default_validator
+
+                    input_element.validation = validators
+
+                    input_element.mark(f"input_{i}")
+                    self.model.inputs.append(input_element)
+
+                ui.button(
+                    icon="add", on_click=self.handle_add_label, color="accent"
+                ).props("fab-mini").tooltip("Add").bind_enabled_from(
+                    self, ("model", "all_valid")
+                ).mark("add")
+
+            ui.separator()
+
+            with ui.column().classes("w-full overflow-y-auto") as self.labels_column:
+                self.labels_container()
+
+            ui.separator()
+
+            with ui.card_actions().classes("w-full"):
+                ui.button(
+                    "Submit",
+                    on_click=lambda: self.submit(self.model.values),
+                    color="positive",
+                ).mark("submit")
+                ui.button(
+                    "Cancel", on_click=lambda: self.submit(None), color="negative"
+                ).mark("cancel")
+
+    async def handle_add_label(self) -> None:
+        label_value_tuple = tuple(str(_input.value) for _input in self.model.inputs)
+        self.model.values.append(label_value_tuple)
+        for _input in self.model.inputs:
+            _input.value = ""
+        self.labels_container.refresh()
+
+    @ui.refreshable_method
+    def labels_container(self) -> None:
+        """Creates the content of the label list container. Each list element
+        has a delete button.
+        """
+        with ui.list().classes("w-full") as list_container:
+            for i, label_tuple in enumerate(self.model.values):
+                delete_callback = partial(self.handle_delete_label, i)
+                click_callback = partial(self.handle_item_click, i)
+                with ui.item().classes("w-full").mark(f"label_{i}"):
+                    with ui.item_section().props("side"):
+                        ui.icon("drag_indicator").classes(
+                            "handle cursor-grab active:cursor-grabbing"
+                        ).bind_visibility_from(
+                            self,
+                            ("model", "options"),
+                            backward=lambda o: DialogOptions.ALLOW_SORTABLE in o,
+                        )
+                    with ui.item_section().props():
+                        ui.chip(
+                            " : ".join(label_tuple), on_click=click_callback
+                        ).classes("w-full flex-1 secondary text-white")
+                    with ui.item_section().props("side"):
+                        ui.icon(
+                            name="delete",
+                            color="warning",
+                        ).on("click", delete_callback).props("flat").tooltip(
+                            "Delete"
+                        ).mark("delete")
+
+        # We only make the list sortable if the option is enabled, which is
+        # possible only when nicegui supports it, but for type checking
+        # we also assert that the make_sortable method is present anyway
+        if TYPE_CHECKING:
+            assert hasattr(list_container, "make_sortable")
+
+        if DialogOptions.ALLOW_SORTABLE in self.model.options:
+            list_container.make_sortable(handle=".handle", on_end=self.handle_sortable)
+
+    def handle_delete_label(self, index: int) -> None:
+        """Removes the label set at the specified index from the model."""
+        self.model.values.pop(index)
+        self.labels_container.refresh()
+
+    def handle_item_click(self, index: int) -> None:
+        """Repopulates the input fields with the values of the clicked label set."""
+        try:
+            for i, _input in enumerate(self.model.inputs):
+                _input.value = self.model.values[index][i]
+        except IndexError:
+            ui.notify(
+                "An error occurred while updating the input fields.", color="negative"
+            )
+
+    def handle_sortable(self, e: SortableEventArguments) -> None:
+        """Updates the model when the label list is sorted on the client side."""
+        # If the event doesn't support the necessary attributes, make this a no-op.
+        if not hasattr(e, "old_index") or not hasattr(e, "new_index"):
+            return
+
+        try:
+            shifting_item = self.model.values.pop(e.old_index)
+            self.model.values.insert(e.new_index, shifting_item)
+        except IndexError:
+            ui.notify("An error occurred while sorting the list.", color="negative")

nice_dialogs/dialogs/types.py

@@ -0,0 +1,30 @@
+"""Module for generic NiceGUI event argument types."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import nicegui.events
+
+    type ValueChangeEventArguments = nicegui.events.ValueChangeEventArguments[Any]
+    """A generic ValueChangeEventArguments for indeterminate or dynamic value
+    change events"""
+
+    type ValueChangeEventArgumentsBool = nicegui.events.ValueChangeEventArguments[
+        bool | None
+    ]
+    """A ValueChangeEventArguments for events that use a boolean value when a
+    value is present."""
+
+    type ValueChangeEventArgumentsStr = nicegui.events.ValueChangeEventArguments[
+        str | None
+    ]
+    """A ValueChangeEventArguments for events that use a string value when a
+    value is present."""
+
+__all__ = [
+    "ValueChangeEventArguments",
+    "ValueChangeEventArgumentsBool",
+    "ValueChangeEventArgumentsStr",
+]

nice_dialogs/dialogs/upload_file.py

@@ -0,0 +1,148 @@
+"""Dialog for managing the upload of a single file.
+
+This dialog is designed to be simple and straightforward for the upload of one
+file at a time to a NiceGUI application. For more robust uploading needs,
+especially the handling of larger files, consult the NiceGUI docuementation for
+the `ui.upload` component, particularly the advice regarding adjusting the
+Starlette Multiparser's `spool_max_size`.
+
+The default spool size of 1MiB is sufficient for many use cases, especially for
+the small files this dialog supports in its default configuration. With this
+limit, the NiceGUI uploader uses buffer during the upload but then passes the
+actual bytes of the uploaded file to the `on_upload` callback. If the file
+is larger than Starlette's spool size, the upload is spilled to a temp file
+instead.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Generator
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from nicegui import ui
+from nicegui.elements.upload_files import FileUpload
+from nicegui.events import UiEventArguments, UploadEventArguments
+
+
+@dataclass
+class UploadFileModel:
+    """Data model for the upload file dialog.
+
+    Attributes
+    ----------
+    max_file_size: int
+        The maximum allowed file size in bytes. This defaults to 1 MiB.
+
+    allowed_file_types: list[str]
+        A list of allowed file types for upload. These file types are not
+        documented by NiceGUI but are passed directly to the `accept` property
+        of the underlying Quasar `<q-uploader>` component.
+    """
+
+    allowed_file_types: list[str] = field(default_factory=list)
+    max_file_size: int = 1_048_576  # 1 MiB
+
+
+class UploadFileDialog(ui.dialog):
+    """NiceGUI Dialog for uploading a single file.
+
+    With a maximum file size of around 1MB, this dialog is intended for small
+    files that will fit in RAM (within the default spool size of the underlying
+    Starlette MultipartParser).
+
+    When a file is successfully uploaded, the dialog automatically closes and
+    returns the FileUpload object. A "Cancel" button allows users to dismiss the
+    dialog without uploading, returning None.
+
+    Params
+    ------
+    dialog_title: str
+        The title displayed at the top of the dialog.
+
+    allowed_file_types: list[str]
+        A list of allowed file types for upload, e.g. `[".jpg", ".png"]` to only
+        allow JPEG and PNG images, or `["image/*"]` to allow all image types.
+        See NiceGUI's `ui.upload` component for more details.
+
+    max_file_size: int
+        The maximum allowed file size in bytes. Defaults to 1,000,000 bytes (1 MB).
+
+    Returns
+    -------
+    nicegui.elements.upload_files.FileUpload | None
+        The uploaded file object when the upload completes, or `None` if the user
+        clicks "Cancel".
+    """
+
+    def __init__(
+        self,
+        *,
+        dialog_title: str = "Single File Upload",
+        allowed_file_types: list[str] = [".*"],
+        max_file_size: int = 1_000_000,
+    ) -> None:
+        """Initialize the dialog and its components."""
+        super().__init__()
+        self.dialog_title = dialog_title
+        self.model = UploadFileModel(
+            allowed_file_types=allowed_file_types,
+            max_file_size=max_file_size,
+        )
+        self.dialog_layout()
+
+    if TYPE_CHECKING:
+
+        def __await__(self) -> Generator[None, None, FileUpload | None]: ...
+
+    def dialog_layout(self) -> None:
+        with self, ui.card():
+            ui.label(self.dialog_title).classes("font-bold text-3xl")
+            with ui.row().classes("flex w-full"):
+                self.uploader = (
+                    ui.upload(
+                        label="Upload File",
+                        on_begin_upload=self.handle_begin_upload,
+                        on_upload=self.handle_file_upload,
+                        on_rejected=self.handle_rejected_upload,
+                        max_file_size=self.model.max_file_size,
+                        max_files=1,
+                    )
+                    .classes("flex-1")
+                    .props(f'accept="{",".join(self.model.allowed_file_types)}"')
+                    .mark("file_upload")
+                )
+
+            with ui.card_actions().classes("w-full align-left"):
+                with ui.row().classes("flex w-full"):
+                    ui.button(
+                        "Cancel",
+                        color="negative",
+                        on_click=lambda: self.submit(None),
+                    ).mark("cancel")
+
+    async def handle_begin_upload(self, e: UiEventArguments) -> None:
+        """Callback handler for the beginning of a file upload."""
+        ...
+
+    async def handle_file_upload(self, e: UploadEventArguments) -> None:
+        """Callback handler for successful file upload.
+
+        Displays a notification with the file size and immediately submits the
+        dialog with the uploaded file object.
+        """
+        size_k = e.file.size() / 1024
+        ui.notify(
+            f"Upload complete: {e.file.name} ({size_k:.1f} KiB)", color="positive"
+        )
+        self.submit(e.file)
+
+    async def handle_rejected_upload(self, e: UiEventArguments) -> None:
+        """Callback handler for rejected file upload (e.g. due to file type or size
+        restrictions).
+        """
+        ui.notify(
+            "File upload rejected. Please ensure the file meets the type and size "
+            "requirements.",
+            color="negative",
+        )

nice_dialogs-1.3.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: nice-dialogs
+Version: 1.3.0
+Summary: Package containing reusable general-purpose NiceGUI dialogs
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: nicegui<4,>=3.11
+Requires-Dist: pydantic-extra-types[cron]>=2.10.6
+Description-Content-Type: text/markdown
+
+# Nice Dialogs
+
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![prek](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/j178/prek/master/docs/assets/badge-v0.json)](https://github.com/j178/prek)
+
+A collection of opinionated [NiceGUI](https://nicegui.io) dialogs.
+
+## Dialogs
+
+### Cron Expression Editor
+
+Using `cron_converter` via `CronStr` from `pydantic-extra-types`, this dialog allows one to build a cron expression by populating the cron schedule parts from selectors.
+
+### Datetime Picker
+
+A dialog, on which one may pick an arbitrary date and time using the appropriate NiceGUI picker elements.
+A timezone field is optional and allows the user to set an IANA timezone while using the dialog.
+The returned datetime object is always timezone-aware and converted to UTC.
+
+### File Uploader
+
+A simple single-file uploader component dialog with options for restricting file types and max size.
+The dialog returns a NiceGUI `FileUpload` object for the consumer to dereference after the dialog returns.
+
+## Requirements
+
+- uv. This project is managed by [uv](https://astral.sh/uv)
+- Python >= 3.13[^1].
+- NiceGUI >= 3.11[^2].
+
+## Examples
+
+A NiceGUI application can be started to demonstrate the dialogs by running `make examples`.
+Note this uses NiceGUI's native mode by default. You may set the `NATIVE=0` environment variable to disable native mode.
+The example application is also used by the NiceGUI `User` test fixture.
+
+## Development Setup
+
+To prepare for development, run `make init`.
+The contents of the `.vscode/` directory may be useful for IDE-based testing and debugging.
+
+## Usage in Projects
+
+To use these dialogs in a NiceGUI application, set a dependency; example for `uv` and `pyproject.toml` shown:
+
+```
+dependencies = [
+    ...,
+    "nice-dialog",
+]
+
+[tool.uv.sources]
+nice-dialog = { git = "https://github.com/tcjennings/nice-dialogs", rev = "..." }
+```
+
+> [!TIP]
+> Consider pinning a `git` dependency source to a specific commit revision for maximum security.
+
+[^1]: This project uses modern Python syntax, including `datetime` format strings, structural pattern matching, and walrus operators.
+
+[^2]: This project uses NiceGUI features introduced in version 3.11 (e.g., nested dictionary binding and type generics) and is not compatible with older versions.

nice_dialogs-1.3.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+nice_dialogs/__init__.py,sha256=-0hDPCmjKjiRAJwSdoTTVvQMsNTHPUmzaAMRKa2NsyM,49
+nice_dialogs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nice_dialogs/dialogs/__init__.py,sha256=XKEkPGHnBWIwNcim8fPgvWcne1QL_c8egN672kUTnp4,397
+nice_dialogs/dialogs/confirmation.py,sha256=yoRf7RNJdmXnEiFh25Lb1j8jgFp77TNhh49Hba0lXCM,4400
+nice_dialogs/dialogs/cron_editor.py,sha256=atA4CGJokVlU10CPU01HTEf79AnXnGS9FeRtms93TMM,12542
+nice_dialogs/dialogs/datetime_picker.py,sha256=EQPTa1CGxJF_141l90Y5JowwH3cYIxEuSLYoaHYLd8w,8267
+nice_dialogs/dialogs/labelmaker.py,sha256=MDKmDGnhORe9FivfLAZf_lnpCA5k1pXR_A2y8i1v2zI,11791
+nice_dialogs/dialogs/types.py,sha256=oC4hV5FSoi9Tm9H15jLsM3gf69D0vS2os8MQMj1QzLk,902
+nice_dialogs/dialogs/upload_file.py,sha256=v_r44S_nZOeeKYr6Fhn0zUd4k1PcWUzPxV6uh4YoIv0,5474
+nice_dialogs-1.3.0.dist-info/METADATA,sha256=2dkuYtB0jgudFTdeQnLJt5i1jlghoZDs2ygCjfH6a7U,3401
+nice_dialogs-1.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+nice_dialogs-1.3.0.dist-info/licenses/LICENSE,sha256=cKcebn3s97ceAXWCbTh2aMmhBVVz-vwV92xVBezRRnk,1070
+nice_dialogs-1.3.0.dist-info/RECORD,,

nice_dialogs-1.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nice_dialogs-1.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toby Jennings
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.