bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/types.py

@@ -0,0 +1,305 @@
+"""Common type aliases and base TypedDicts for bootstack widgets."""
+
+import tkinter
+from typing import Any, Callable, Literal, TypedDict
+
+# ---------------------------------------------------------------------------
+# Primitive aliases
+# ---------------------------------------------------------------------------
+
+# Internal: parent-widget type. Not part of the public API.
+Master = tkinter.Misc | None
+
+# `Event` lives in the public `bootstack.events` package; re-imported here so the
+# many widget modules that pull it alongside the layout aliases keep working.
+from bootstack.events import Event  # noqa: E402
+
+EventCallback = Callable[["Event"], None]
+"""Callback that receives an `Event` object."""
+
+CommandCallback = Callable[[], Any]
+"""Callback invoked with no arguments, e.g. a button `command=`."""
+
+# ---------------------------------------------------------------------------
+# Layout literals
+# ---------------------------------------------------------------------------
+
+Anchor = Literal['n', 'ne', 'e', 'se', 's', 'sw', 'w', 'nw', 'center']
+"""Alignment anchor position."""
+
+Orient = Literal['horizontal', 'vertical']
+"""Widget orientation."""
+
+LocalizeMode = bool | Literal['auto']
+"""Whether a widget's text is translated through the catalog — `True`, `False`, or
+`'auto'` (translate when a translation is registered, otherwise show the literal)."""
+
+Justify = Literal['left', 'center', 'right']
+"""Text justification within a widget."""
+
+Relief = Literal['flat', 'raised', 'sunken', 'groove', 'ridge', 'solid']
+"""Border relief style."""
+
+CompoundMode = Literal['text', 'image', 'top', 'bottom', 'left', 'right', 'center', 'none']
+"""Relative position of image to text when both are displayed."""
+
+Padding = int | tuple[int, int] | tuple[int, int, int, int]
+"""Widget padding in pixels — a single value for all sides, `(x, y)` for the
+horizontal and vertical amounts, or `(left, top, right, bottom)`."""
+
+# ---------------------------------------------------------------------------
+# Widget state
+# ---------------------------------------------------------------------------
+
+WidgetState = Literal['normal', 'active', 'disabled', 'readonly']
+"""Widget interaction state."""
+
+WidgetDensity = Literal['default', 'compact']
+"""Widget density — `'default'` for normal sizing, `'compact'` for reduced padding."""
+
+ScrollbarVariant = Literal['default', 'thin']
+"""Scrollbar style — `'default'` for the standard rounded bar, `'thin'` for a slim
+square bar that suits compact lists, panels, and popups."""
+
+# ---------------------------------------------------------------------------
+# bootstack styling tokens
+# ---------------------------------------------------------------------------
+
+AccentToken = Literal['primary', 'secondary', 'info', 'success', 'warning', 'danger']
+"""A semantic color accent. The accent params widen this with `| str`, so
+`'default'`, `'muted'`, and modifiers (`'primary[+1]'`, `'primary[500]'`,
+`'primary[subtle]'`) are also accepted."""
+
+SurfaceToken = Literal['content', 'card', 'card_raised', 'chrome', 'overlay']
+"""Background surface context token."""
+
+WindowStyle = Literal['mica', 'acrylic', 'aero', 'transparent', 'win7']
+"""A Windows-only window effect (no-op elsewhere). These are the common effects;
+the underlying pywinstyles library accepts more (pass any as a plain string).
+See https://pypi.org/project/pywinstyles/ for the full set."""
+
+# ---------------------------------------------------------------------------
+# Geometry manager literals
+# ---------------------------------------------------------------------------
+
+Fill = Literal['none', 'x', 'y', 'both', 'horizontal', 'vertical', 'all']
+"""Fill axis for stack layout. `'horizontal'`/`'vertical'`/`'all'` are readable
+aliases for `'x'`/`'y'`/`'both'`."""
+
+Sticky = Literal['n', 's', 'e', 'w', 'ns', 'ew', 'nsew', 'ne', 'nw', 'se', 'sw', 'nse', 'nsw', 'new', 'sew', '']
+"""Cell alignment for Grid layout. Any combination of `'n'`, `'s'`, `'e'`, `'w'`."""
+
+Side = Literal['left', 'top', 'right', 'bottom']
+"""Side placement for stack layout."""
+
+HAlign = Literal['left', 'center', 'right', 'stretch']
+"""Horizontal alignment of a widget within its slot — `'left'`, `'center'`,
+`'right'`, or `'stretch'` (fill the width)."""
+
+VAlign = Literal['top', 'center', 'bottom', 'stretch']
+"""Vertical alignment of a widget within its slot — `'top'`, `'center'`,
+`'bottom'`, or `'stretch'` (fill the height)."""
+
+HArrange = Literal['left', 'center', 'right', 'space-between', 'space-around', 'space-evenly']
+"""Horizontal arrangement of a Row's children as a group — cluster them
+(`'left'`/`'center'`/`'right'`) or spread them apart with the `'space-*'` modes."""
+
+VArrange = Literal['top', 'center', 'bottom', 'space-between', 'space-around', 'space-evenly']
+"""Vertical arrangement of a Column's children as a group — cluster them
+(`'top'`/`'center'`/`'bottom'`) or spread them apart with the `'space-*'` modes."""
+
+Direction = Literal['vertical', 'horizontal', 'row', 'column', 'row-reverse', 'column-reverse']
+"""Layout direction."""
+
+LayoutKind = Literal['column', 'row', 'grid']
+"""Internal layout manager for a container — `'column'`/`'row'` pack children
+top-to-bottom / left-to-right; `'grid'` arranges them in rows and columns."""
+
+AutoFlow = Literal['row', 'column', 'row-dense', 'column-dense', 'none']
+"""Grid auto-placement direction. `'row'`/`'column'` fill along that axis;
+the `'-dense'` variants backfill gaps; `'none'` disables auto-placement."""
+
+BorderMode = Literal['inside', 'outside']
+"""Border mode for the place geometry manager."""
+
+ButtonVariant = Literal['default', 'solid', 'outline', 'ghost']
+"""Style variant shared by the button family (Button, ButtonGroup, MenuButton,
+SelectButton, ToggleButton, ToggleGroup, Toolbar) — `'default'`, `'solid'`,
+`'outline'`, or `'ghost'`."""
+
+AccordionVariant = Literal['solid', 'default']
+"""Accordion header style — `'solid'`, or `'default'` for a ghost/transparent header."""
+
+Region = Literal['before', 'center', 'after']
+"""Placement region within a menu bar — `'before'`, `'center'`, or `'after'`."""
+
+IconPosition = Literal['left', 'right', 'top', 'bottom']
+"""Position of an icon relative to a widget's text — `'left'`, `'right'`,
+`'top'`, or `'bottom'`."""
+
+SelectionMode = Literal['none', 'single', 'multi']
+"""How many rows/items can be selected — `'none'`, `'single'`, or `'multi'`."""
+
+ExportScope = Literal['all', 'page', 'selection']
+"""Which rows an export covers — `'all'` rows, the current `'page'`, or the
+current `'selection'`."""
+
+ExportFormat = Literal['csv', 'tsv', 'xlsx']
+"""A tabular export format — `'csv'`, `'tsv'`, or `'xlsx'`."""
+
+ToastCorner = Literal['top-left', 'top-right', 'bottom-left', 'bottom-right']
+"""A screen corner for a `toast()` or `Notification` — anchored to the corner of
+the monitor the app window is on, where they stack."""
+
+SnackbarAlign = Literal['left', 'center', 'right']
+"""Horizontal alignment of a `Snackbar` along the app window's bottom edge."""
+
+# ---------------------------------------------------------------------------
+# Base TypedDicts
+# ---------------------------------------------------------------------------
+
+class BaseWidgetKwargs(TypedDict, total=False):
+    """Low-level options shared by all bootstack widget wrappers."""
+    style: str
+    class_: str
+    cursor: str
+    name: str
+    takefocus: bool
+
+
+class StyledKwargs(BaseWidgetKwargs, total=False):
+    """Extends BaseWidgetKwargs with bootstack styling tokens."""
+    accent: AccentToken | str
+    variant: str
+    surface: SurfaceToken | str
+    style_options: dict[str, Any]
+
+
+# ---------------------------------------------------------------------------
+# Data-entry config types (DataTable columns + add/edit form)
+# ---------------------------------------------------------------------------
+
+EditorType = Literal[
+    'textfield',
+    'numberfield',
+    'passwordfield',
+    'datefield',
+    'textarea',
+    'select',
+    'spinnerfield',
+    'switch',
+    'checkbox',
+    'slider',
+]
+"""The field type used to edit a value in a `Form` or `DataTable` add/edit
+dialog. Inferred from the value's `dtype` when omitted."""
+
+
+class ColumnSpec(TypedDict, total=False):
+    """A column definition for `DataTable(columns=...)`.
+
+    Columns may be plain key strings or these dicts. Only `key` is required; the
+    editor keys (`editor`, `editor_options`, `dtype`, `readonly`, `required`)
+    shape how the column appears in the built-in add/edit dialog.
+    """
+
+    key: str
+    """Record field this column reads and writes."""
+    text: str
+    """Header label. Defaults to `key`."""
+    width: int
+    """Column width in pixels."""
+    minwidth: int
+    """Minimum column width in pixels."""
+    anchor: str
+    """Cell alignment — `'w'`, `'center'`, or `'e'`."""
+    format: "str | Callable[[Any], str]"
+    """Display formatter for the cell — a format-spec string applied as
+    `spec.format(value)` (e.g. `'${:,.0f}'` → `$70,000`) or a callable
+    `(value) -> str`. Display only: sorting, filtering, editing, and export use
+    the raw value."""
+    dtype: str
+    """Value type hint (e.g. `'int'`, `'text'`); drives alignment and the editor."""
+    editor: EditorType
+    """Field type used to edit this column in the add/edit dialog. Inferred from
+    `dtype` when omitted."""
+    editor_options: dict
+    """Keyword options passed to the editor field."""
+    readonly: bool
+    """Show the column but make it non-editable in the dialog."""
+    required: bool
+    """Require a value in the add/edit dialog."""
+
+
+class FormOptions(TypedDict, total=False):
+    """Layout options for the built-in add/edit dialog (`DataTable(form=...)`)."""
+
+    col_count: int
+    """Number of columns the form fields are laid out in. Default `2`."""
+    min_col_width: int
+    """Minimum width in pixels of each form column. Default `260`."""
+    scrollable: bool
+    """Scroll the form when it is taller than the dialog. Default `True`."""
+    resizable: bool
+    """Allow the dialog to be resized. Default `True`."""
+
+
+# ---------------------------------------------------------------------------
+# Selection options (the shared "data bag" option shape)
+# ---------------------------------------------------------------------------
+
+class OptionDict(TypedDict, total=False):
+    """A single choice for a selection widget, in dict form.
+
+    The dict form is a *data bag*: `text` is required (and `value` defaults to
+    it) UNLESS the dict carries an `icon` and a `value`, in which case `text` may
+    be omitted to request an icon-only option. `text`/`value` and the recognized
+    `icon`/`disabled` keys act on rendering; every *other* key rides along as
+    carried data — retrievable as the widget's `selection` (the selected
+    option's full record). Unrecognized keys are accepted, not rejected, so the
+    dict route trades key-typo safety for extensibility.
+    """
+
+    text: str
+    """Display label. Required unless `icon` + `value` are given (icon-only)."""
+    value: Any
+    """Stored and emitted value. Defaults to `text` when omitted."""
+    icon: str
+    """Optional icon spec rendered beside the label — alone when `text` is blank."""
+    disabled: bool
+    """When `True`, the option is dimmed and cannot be selected by the user."""
+    localize: "bool | Literal['auto']"
+    """Per-option translation mode — `True`, `False`, or `'auto'`. Overrides the
+    widget's group-level `localize=` for just this option. Set `False` to keep a
+    proper noun or identifier untranslated."""
+
+
+Option = str | tuple[str, Any] | OptionDict
+"""A single choice for `Select`, `SelectButton`, `RadioGroup`, or `ToggleGroup`.
+
+Three interchangeable forms, all normalized to a `(text, value)` pair:
+
+- a plain `str` — text and value are the same (`'Small'`);
+- a `(text, value)` tuple — decoupled label and value (`('Small', 's')`);
+- an `OptionDict` — `{'text': 'Small', 'value': 's'}`; the extensible form."""
+
+
+class IconSpec(TypedDict, total=False):
+    """A detailed icon specification: a Bootstrap icon name with size and color.
+
+    Use in place of a plain icon name wherever a widget accepts `icon=`, to
+    control the rendered size and color — for example
+    `icon={'name': 'bell-fill', 'size': 24, 'color': 'primary'}`.
+    """
+
+    name: str
+    """Bootstrap Icons name, e.g. `'bell-fill'`."""
+    size: int
+    """Icon size in pixels (automatically DPI-scaled)."""
+    color: str
+    """Icon color — a theme color token (e.g. `'primary'`) or a hex string."""
+
+
+Icon = str | IconSpec
+"""An icon as either a Bootstrap Icons name (`'bell-fill'`) or an `IconSpec`
+mapping for control over size and color."""

bootstack/widgets/window.py

@@ -0,0 +1,307 @@
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING, Any, Callable, Literal
+
+from bootstack.widgets._impl.primitives.flexframe import FlexFrame
+from bootstack.widgets._core.container import FlexContainer
+from bootstack.widgets._core.window_controls import WindowControlsMixin
+from bootstack.widgets._core.window_menu import ChromeHostMixin
+from bootstack.widgets.types import (
+    Padding, HAlign, VArrange, Anchor, SurfaceToken, WindowStyle,
+)
+
+if TYPE_CHECKING:
+    from bootstack.images import AppIcon, Image
+
+
+def _resolve_window_parent(parent: Any) -> Any:
+    """Resolve a public widget (or tk widget) to its containing tk window.
+
+    Accepts an `App`, a `Window`, or any widget inside one, and returns the
+    enclosing toplevel — so centering and transient-parenting act on the window,
+    not on a small child widget.
+    """
+    if parent is None:
+        return None
+    widget = None
+    for attr in ("_tk_root", "_tk_toplevel", "_internal"):
+        widget = getattr(parent, attr, None)
+        if widget is not None:
+            break
+    if widget is None:
+        widget = parent  # assume it is already a tk widget
+    try:
+        return widget.winfo_toplevel()
+    except Exception:
+        return widget
+
+
+def _resolve_anchor_widget(target: Any) -> Any:
+    """Resolve an anchor target to a tk widget (keeping it, not its toplevel).
+
+    A string (`'screen'`/`'cursor'`/`'parent'`) passes through; a public widget
+    resolves to the underlying tk widget so a window can be placed relative to
+    that exact widget (e.g. beside a field).
+    """
+    if isinstance(target, str) or target is None:
+        return target
+    for attr in ("_tk_toplevel", "_tk_root", "_internal"):
+        widget = getattr(target, attr, None)
+        if widget is not None:
+            return widget
+    return target
+
+
+class Window(WindowControlsMixin, ChromeHostMixin, FlexContainer):
+    """A secondary top-level window.
+
+    Behaves as an implicit `Column` from the user's perspective: children
+    created inside a `with` block are automatically packed into its content
+    frame top-to-bottom.  Call `show()` to display the window after building
+    its content, or `block_until_closed()` to show it and wait for the user
+    to close it.
+
+    Args:
+        title: Window title bar text.
+        size: Initial size as `(width, height)`.
+        icon: Title-bar and taskbar icon — an icon file path, an `Image` handle,
+            or an `AppIcon`. Defaults to the bootstack icon.
+        position: Initial position as `(x, y)`.
+        min_size: Minimum window size as `(width, height)`.
+        max_size: Maximum window size as `(width, height)`.
+        resizable: Whether the window can be resized as `(width, height)`.
+        modal: Modality level. `False` — non-modal (default). `True` or
+            `'window'` — grabs input from the parent only. `'app'` — grabs
+            input from all windows.
+        parent: The window this one belongs to — an `App`, another `Window`, or
+            any widget inside one. Makes this window transient to it (stacks
+            above it, hides with it) and is the target for `center_on_parent`.
+            Defaults to the main application window.
+        center_on_parent: Center over `parent` (the main window if `parent` is
+            not given).
+        center_on_screen: Center on the screen.
+        topmost: Keep the window above other windows.
+        undecorated: Remove OS window decorations (`overrideredirect`).
+            Ignored on macOS. Unless `window_controls=False`, the window gets a
+            built-in draggable title bar with min/max/close so it stays movable
+            and closeable; add your own with `add_toolbar(show_window_controls=True)`
+            to take over the chrome.
+        window_controls: When `undecorated`, provide a built-in title bar with
+            window controls and dragging if you add no chrome toolbar of your
+            own. Set `False` for a truly chromeless window (e.g. a splash or
+            popover). Default `True`. No effect on a decorated window.
+        window_style: Windows-only window effect. None inherits the app's setting.
+        on_close: Callback invoked when the user clicks the close button.
+            Return `False` to veto; return `None` or `True` to allow.
+        padding: Inner padding for the content frame.
+        gap: Spacing between children.
+        horizontal_items: Horizontal alignment of children — `'left'`,
+            `'center'`, `'right'`, or `'stretch'` (fill the width). Default
+            `'center'`.
+        vertical_items: How children are arranged top to bottom — `'top'`,
+            `'center'`, `'bottom'`, or a `'space-*'` mode. Default `'top'`.
+        grow_items: When `True`, children grow equally to fill the height.
+        surface: Surface token for the content frame background.
+    """
+
+    _auto_place = False  # top-level window — no parent manages its position
+
+    def __init__(
+        self,
+        *,
+        title: str = "",
+        size: tuple[int, int] | None = None,
+        icon: "str | Image | AppIcon | None" = None,
+        position: tuple[int, int] | None = None,
+        min_size: tuple[int, int] | None = None,
+        max_size: tuple[int, int] | None = None,
+        resizable: tuple[bool, bool] | None = None,
+        modal: Literal[False, True, "window", "app"] = False,
+        parent: Any = None,
+        center_on_parent: bool = False,
+        center_on_screen: bool = False,
+        topmost: bool = False,
+        undecorated: bool = False,
+        window_controls: bool = True,
+        window_style: WindowStyle | str | None = None,
+        on_close: Callable[[], bool | None] | None = None,
+        # Content frame layout
+        padding: Padding | None = None,
+        gap: int = 0,
+        horizontal_items: HAlign = "center",
+        vertical_items: VArrange = "top",
+        grow_items: bool = False,
+        surface: SurfaceToken | str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        from bootstack._runtime.toplevel import Toplevel as _InternalToplevel
+
+        self._parent = None
+        # overrideredirect has no effect on macOS — so the borderless treatment
+        # (custom border + title bar) is Windows/Linux only.
+        self._undecorated = undecorated and sys.platform != "darwin"
+        self._window_controls = window_controls
+
+        init_kwargs: dict[str, Any] = {
+            "title": title,
+            "modal": modal,
+            "center_on_parent": center_on_parent,
+            "center_on_screen": center_on_screen,
+            "topmost": topmost,
+            "overrideredirect": undecorated,
+        }
+        if size is not None:
+            init_kwargs["size"] = size
+        if position is not None:
+            init_kwargs["position"] = position
+        if min_size is not None:
+            init_kwargs["minsize"] = min_size
+        if max_size is not None:
+            init_kwargs["maxsize"] = max_size
+        if resizable is not None:
+            init_kwargs["resizable"] = resizable
+        if on_close is not None:
+            init_kwargs["on_close"] = on_close
+        if window_style is not None:
+            init_kwargs["window_style"] = window_style
+
+        parent_widget = _resolve_window_parent(parent)
+        self._parent_window = parent_widget
+        if parent_widget is not None:
+            init_kwargs["transient"] = parent_widget
+
+        from bootstack.widgets._core.image_binding import resolve_window_icon
+
+        icon_path, icon_image = resolve_window_icon(icon)
+        if icon_path is not None:
+            init_kwargs["icon"] = icon_path
+        init_kwargs.update(kwargs)
+
+        self._tk_toplevel = _InternalToplevel(**init_kwargs)
+
+        # An Image handle needs the window to exist before it can be rendered.
+        self._window_icon_photo = None
+        if icon_image is not None:
+            self._window_icon_photo = icon_image._materialize()
+            self._tk_toplevel._setup_icon(self._window_icon_photo)
+
+        frame_kwargs: dict[str, Any] = {
+            "direction": "vertical",
+            "gap": gap,
+            "horizontal_items": horizontal_items,
+            "vertical_items": vertical_items,
+            "grow_items": grow_items,
+        }
+        if padding is not None:
+            frame_kwargs["padding"] = padding
+        if surface is not None:
+            frame_kwargs["surface"] = surface
+
+        # In undecorated mode the OS border is gone; a 1px themed border frame
+        # substitutes it and hosts both the chrome stack and the content. A
+        # chromeless window (`window_controls=False`, e.g. a splash) keeps no
+        # border either.
+        if self._undecorated and self._window_controls:
+            from bootstack.widgets._impl.primitives.frame import Frame
+
+            self._region_root = Frame(self._tk_toplevel, show_border=True, padding=1)
+            self._region_root.pack(fill="both", expand=True)
+        else:
+            self._region_root = self._tk_toplevel
+
+        self._content_frame = FlexFrame(self._region_root, **frame_kwargs)
+        self._content_frame.pack(fill="both", expand=True)
+
+        self._internal = self._tk_toplevel
+
+    def _toolbar_stack_parent(self) -> Any:
+        # The chrome stack lives inside the (bordered) region root, above content.
+        return getattr(self, "_region_root", self._tk_toplevel)
+
+    @property
+    def _flex_frame(self) -> Any:
+        return self._content_frame
+
+    # ----- Lifecycle -----
+
+    def show(
+        self,
+        *,
+        anchor_to: Any = None,
+        anchor_point: Anchor = "center",
+        window_point: Anchor = "center",
+        offset: tuple[int, int] = (0, 0),
+        auto_flip: bool = True,
+    ) -> "Window":
+        """Show the window, optionally positioned relative to a widget.
+
+        With no arguments the window appears at its configured position (or
+        centered on its `parent`). Pass `anchor_to` to place it relative to a
+        widget instead — for example, to the right of a field.
+
+        Args:
+            anchor_to: A widget to position this window against, or one of
+                `'screen'`, `'cursor'`, or `'parent'`. When given, this overrides
+                centering.
+            anchor_point: The point on the anchor target to align to — one of
+                `'n'`, `'s'`, `'e'`, `'w'`, `'ne'`, `'nw'`, `'se'`, `'sw'`, or
+                `'center'`. For example, `'e'` is the target's right edge.
+            window_point: The matching point on this window placed at the anchor
+                (same value set). For example, `anchor_point='e'` with
+                `window_point='w'` puts this window's left edge at the target's
+                right edge — i.e. to its right.
+            offset: Extra `(x, y)` pixel offset from the anchored position.
+            auto_flip: Flip to the opposite side if the window would otherwise go
+                off-screen. Defaults to `True`.
+
+        Returns:
+            `self` — allows chaining: `win = Window(...).show()`.
+        """
+        self._ensure_default_titlebar()
+        if anchor_to is not None:
+            from bootstack._runtime.window_utilities import WindowPositioning
+
+            toplevel = self._tk_toplevel
+            toplevel.update_idletasks()
+            WindowPositioning.position_anchored(
+                window=toplevel,
+                anchor_to=_resolve_anchor_widget(anchor_to),
+                parent=self._parent_window,
+                anchor_point=anchor_point,
+                window_point=window_point,
+                offset=offset,
+                auto_flip=auto_flip,
+                ensure_visible=True,
+            )
+        self._tk_toplevel.show()
+        return self
+
+    def block_until_closed(self) -> Any:
+        """Show the window and block until it is destroyed.
+
+        Returns:
+            The value of `result` at the time the window was closed.
+        """
+        self._ensure_default_titlebar()
+        return self._tk_toplevel.block_until_closed()
+
+    # ----- Properties -----
+
+    @property
+    def title(self) -> str:
+        """The window's title bar text. Assigning to it updates the title live."""
+        return self._tk_toplevel.title()
+
+    @title.setter
+    def title(self, value: str) -> None:
+        self._tk_toplevel.title(value)
+
+    @property
+    def result(self) -> Any:
+        """Value set before closing, returned by `block_until_closed()`."""
+        return self._tk_toplevel.result
+
+    @result.setter
+    def result(self, value: Any) -> None:
+        self._tk_toplevel.result = value