bootstack 0.1.0__py3-none-any.whl

bootstack/__init__.py

@@ -0,0 +1,157 @@
+"""bootstack — a Python desktop UI framework.
+
+Build modern desktop apps with a clean, Pythonic API. No Tkinter knowledge required.
+
+Example:
+    ```python
+    import bootstack as bs
+
+    with bs.App(title="Hello") as app:
+        bs.Label("Hello, world!")
+    app.run()
+    ```
+
+The top-level `bootstack` namespace holds what you *compose a UI* with: every
+widget, `App`/`AppShell`/`Window`, `Signal`, the dialog verbs
+(`alert`/`confirm`/`ask_*`/`toast`), and `set_theme`/`toggle_theme`.
+Framework primitives you reference *by type to configure behavior* live in
+submodules — for example::
+
+    from bootstack.data import SqliteDataSource, col
+    from bootstack.i18n import L, LV
+    from bootstack.validation import ValidationRule
+    from bootstack.style import Theme, get_theme_color
+    from bootstack.events import Event, Subscription
+    from bootstack.images import Image, get_icon, AppIcon
+    from bootstack.types import AccentToken
+
+See the "API overview" in the documentation for the full map.
+"""
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("bootstack")
+except Exception:
+    __version__ = "unknown"
+
+# ── Runtime patches — must run before widgets are created ─────────────────────
+from bootstack._runtime.tk_patch import install_tk_autostyle as _install_autostyle
+from bootstack._runtime.events import install_enhanced_events as _install_events
+from bootstack._runtime.visual_focus import install_visual_focus as _install_focus
+
+_install_autostyle()
+_install_events()
+_install_focus()
+
+# ── Reactive state ────────────────────────────────────────────────────────────
+from bootstack.signals import Signal
+
+# ── Theme switching (full theming API lives in `bootstack.style`) ─────────────
+from bootstack.style import set_theme, toggle_theme
+
+# ── Dialog verbs (dialog classes live in `bootstack.dialogs`) ─────────────────
+from bootstack.dialogs import (
+    alert, confirm, ask_string, ask_integer, ask_float,
+    ask_date, ask_date_range, ask_item,
+    ask_color, ask_font, ask_filter,
+    ask_save_file, ask_open_file, ask_open_files, ask_directory,
+)
+
+# ── Application & windows ─────────────────────────────────────────────────────
+from bootstack.widgets.app import App
+from bootstack.widgets.appshell import AppShell, Workbench
+from bootstack.widgets.window import Window
+from bootstack.widgets.splash import Splash
+
+# ── Public widget layer ───────────────────────────────────────────────────────
+from bootstack.widgets.stacks import Row, Column, Spacer
+from bootstack.widgets.grid import Grid
+from bootstack.widgets.boolean_controls import Checkbox, Switch, ToggleButton
+from bootstack.widgets.theme_toggle import ThemeToggle
+from bootstack.widgets.button import Button
+from bootstack.widgets.card import Card
+from bootstack.widgets.buttongroup import ButtonGroup
+from bootstack.widgets.codeeditor import CodeEditor
+from bootstack.widgets.contextmenu import ContextMenu, ContextMenuItem
+from bootstack.widgets.datefield import DateField
+from bootstack.widgets.expander import Accordion, AccordionSection
+from bootstack.widgets.gauge import Gauge
+from bootstack.widgets.groupbox import GroupBox
+from bootstack.widgets.label import Badge, Label
+from bootstack.widgets.listview import ListView
+from bootstack.widgets.menubutton import MenuButton
+from bootstack.widgets.numberfield import NumberField
+from bootstack.widgets.pagestack import PageStack, StackPage
+from bootstack.widgets.pathfield import PathField
+from bootstack.widgets.avatar import Avatar
+from bootstack.widgets.carousel import Carousel
+from bootstack.widgets.chart import Chart
+from bootstack.widgets.gallery import Gallery
+from bootstack.widgets.passwordfield import PasswordField
+from bootstack.widgets.picture import Picture
+from bootstack.widgets.progressbar import ProgressBar
+from bootstack.widgets.radio_variants import Radio, RadioToggleButton
+from bootstack.widgets.radiogroup import RadioGroup
+from bootstack.widgets.scrollview import ScrollView
+from bootstack.widgets.select import Select
+from bootstack.widgets.selectbutton import SelectButton
+from bootstack.widgets.divider import Divider
+from bootstack.widgets.splitview import SplitView, SplitPane
+from bootstack.widgets.slider import RangeSlider, Slider
+from bootstack.widgets.spinnerfield import SpinnerField
+from bootstack.widgets.datatable import DataTable
+from bootstack.widgets.tabs import TabPage, Tabs
+from bootstack.widgets.textarea import TextArea
+from bootstack.widgets.timefield import TimeField
+from bootstack.widgets.tree import Tree, TreeNode
+from bootstack.widgets.textfield import TextField
+from bootstack.widgets.toast import toast, Notification, Snackbar, snackbar
+from bootstack.widgets.togglegroup import ToggleGroup
+from bootstack.widgets.toolbar import Toolbar
+from bootstack.widgets.statusbar import StatusBar
+from bootstack.widgets.tooltip import Tooltip
+
+from bootstack.widgets.calendar import Calendar
+from bootstack.widgets.form import Form
+from bootstack.widgets.form import FormItem, FieldItem, GroupItem, TabsItem, TabItem
+
+
+# ── Public API surface ────────────────────────────────────────────────────────
+# The curated top-level namespace: things you compose a UI with. Framework
+# primitives (data, i18n, validation, events, streams, scheduling, shortcuts,
+# style, errors, store, types) live in their own submodules — see the docs'
+# "API overview". This list is kept in sync with tests/test_public_surface.py.
+__all__ = [
+    "__version__",
+    # Reactive state
+    "Signal",
+    # Theme switching
+    "set_theme", "toggle_theme",
+    # Dialog verbs
+    "alert", "confirm", "ask_string", "ask_integer", "ask_float", "ask_date",
+    "ask_date_range", "ask_item", "ask_color", "ask_font", "ask_filter",
+    "ask_save_file", "ask_open_file", "ask_open_files", "ask_directory",
+    # Application & windows
+    "App", "AppShell", "Workbench", "Window", "Splash",
+    # Layout
+    "Row", "Column", "Spacer", "Grid", "Card", "GroupBox", "Divider", "ScrollView",
+    "SplitView", "SplitPane", "Accordion", "AccordionSection",
+    # Actions
+    "Button", "ButtonGroup", "ThemeToggle", "MenuButton", "Toolbar", "StatusBar",
+    "ContextMenu", "ContextMenuItem",
+    # Inputs
+    "TextField", "PasswordField", "NumberField", "PathField", "SpinnerField",
+    "TextArea", "CodeEditor", "DateField", "TimeField", "Slider", "RangeSlider",
+    # Selection
+    "Checkbox", "Switch", "ToggleButton", "ToggleGroup", "Radio",
+    "RadioToggleButton", "RadioGroup", "Select", "SelectButton", "Calendar",
+    # Data display
+    "Label", "Badge", "ProgressBar", "Gauge", "ListView", "DataTable", "Tree", "TreeNode",
+    # Media
+    "Picture", "Gallery", "Carousel", "Avatar", "Chart",
+    # Navigation
+    "PageStack", "StackPage", "Tabs", "TabPage",
+    # Overlays
+    "Tooltip", "toast", "Notification", "Snackbar", "snackbar",
+    # Forms
+    "Form", "FormItem", "FieldItem", "GroupItem", "TabsItem", "TabItem",
+]

bootstack/__main__.py

@@ -0,0 +1,5 @@
+"""CLI entry point — invoked as `python -m bootstack` to launch the bootstack CLI."""
+from bootstack.cli import main
+
+if __name__ == "__main__":
+    main()

bootstack/_core/__init__.py

@@ -0,0 +1,21 @@
+"""Core utilities and error types."""
+
+from __future__ import annotations
+
+from . import colorutils, publisher, capabilities
+from bootstack._core.exceptions import (
+    ThemeError,
+    NavigationError,
+    StyleBuilderError,
+    ConfigurationWarning,
+)
+
+__all__ = [
+    "colorutils",
+    "publisher",
+    "capabilities",
+    "ThemeError",
+    "NavigationError",
+    "StyleBuilderError",
+    "ConfigurationWarning",
+]

bootstack/_core/capabilities/__init__.py

@@ -0,0 +1,45 @@
+"""Core widget capabilities for bootstack.
+
+This package provides framework services that can be used by widget mixins
+and other parts of the library. Each capability module contains reusable
+logic that mixins delegate to, keeping the mixins themselves as thin glue.
+
+Capabilities:
+    signals: Signal/Variable binding and normalization
+    localization: Text translation and value formatting
+"""
+
+from bootstack._core.capabilities.signals import (
+    SignalBinding,
+    is_signal,
+    is_variable,
+    normalize_signal,
+    create_signal,
+    infer_default_value_for_widget,
+    query_binding,
+)
+
+from bootstack._core.capabilities.localization import (
+    resolve_text,
+    resolve_variable_text,
+    apply_spec,
+    get_current_locale,
+    create_formatted_signal,
+)
+
+__all__ = [
+    # Signals capability
+    "SignalBinding",
+    "is_signal",
+    "is_variable",
+    "normalize_signal",
+    "create_signal",
+    "infer_default_value_for_widget",
+    "query_binding",
+    # Localization capability
+    "resolve_text",
+    "resolve_variable_text",
+    "apply_spec",
+    "get_current_locale",
+    "create_formatted_signal",
+]

bootstack/_core/capabilities/after.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class AfterMixin:
+    """Scheduling helpers (after).
+
+    Tk’s `after` family lets you schedule callbacks to run later on the Tk event loop.
+
+    Common uses:
+        - Debounce user input (schedule a callback and cancel previous ones).
+        - Run periodic UI updates (schedule, then reschedule from inside the callback).
+        - Defer work until the UI is idle (`after_idle`) so layout/paint can complete.
+
+    Notes:
+        - Callbacks run on the Tk thread/event loop. If you have long-running work,
+          run it off-thread/process and schedule UI updates back onto Tk using `after`.
+        - `after` returns an identifier that can be canceled with `after_cancel`.
+    """
+
+    def after(self, ms: int, func: Callable[..., Any] | None = None, *args: Any) -> str:
+        """Schedule a callback to run after a delay.
+
+        Args:
+            ms: Delay in milliseconds.
+            func: Callback to run. If omitted/None, Tk blocks for `ms` milliseconds
+                while still processing events (use sparingly).
+            *args: Arguments to pass to `func` when it is called.
+
+        Returns:
+            An identifier that can be used with `after_cancel`.
+        """
+        return super().after(ms, func, *args)  # type: ignore[misc]
+
+    def after_idle(self, func: Callable[..., Any], *args: Any) -> str:
+        """Schedule a callback to run when the event loop is idle.
+
+        Idle callbacks run after Tk has finished processing the current batch of
+        events and pending UI work.
+
+        Args:
+            func: Callback to run.
+            *args: Arguments to pass to `func` when it is called.
+
+        Returns:
+            An identifier that can be used with `after_cancel`.
+        """
+        return super().after_idle(func, *args)  # type: ignore[misc]
+
+    def after_cancel(self, id: str) -> None:
+        """Cancel a scheduled callback.
+
+        Args:
+            id: The identifier returned by `after` or `after_idle`.
+        """
+        return super().after_cancel(id)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Convenience helpers (optional)
+    # -------------------------------------------------------------------------
+
+    def after_repeat(self, ms: int, func: Callable[..., Any], *args: Any) -> Callable[[], None]:
+        """Call `func` repeatedly every `ms` milliseconds.
+
+        This helper schedules `func` and then automatically reschedules it after
+        each run. It returns a `cancel()` function you can call to stop repetition.
+
+        Args:
+            ms: Interval in milliseconds.
+            func: Callback to run each interval.
+            *args: Arguments to pass to `func`.
+
+        Returns:
+            A `cancel()` callable. Call it to stop the repeating schedule.
+
+        Examples:
+            >>> cancel = widget.after_repeat(250, tick)
+            >>> cancel()
+        """
+        cancelled = False
+        token: str | None = None
+
+        def _run():
+            nonlocal token
+            if cancelled:
+                return
+            func(*args)
+            token = self.after(ms, _run)
+
+        token = self.after(ms, _run)
+
+        def cancel() -> None:
+            nonlocal cancelled, token
+            cancelled = True
+            if token is not None:
+                try:
+                    self.after_cancel(token)
+                except Exception:
+                    pass
+                token = None
+
+        return cancel

bootstack/_core/capabilities/bind.py

@@ -0,0 +1,192 @@
+"""Event binding capabilities mixin for bootstack widgets."""
+from __future__ import annotations
+
+from typing import Any, Callable, TYPE_CHECKING
+
+from typing_extensions import TypedDict
+
+if TYPE_CHECKING:
+    from typing_extensions import Unpack
+
+
+class EventGenerateKwargs(TypedDict, total=False):
+    """Keyword options for `event_generate` (Tk event field overrides).
+
+    All fields are optional. Only supply fields relevant to the event type
+    being synthesized (e.g., `x`/`y` for mouse events, `keysym` for key events).
+    """
+    x: int
+    """Widget-relative x-coordinate in pixels."""
+    y: int
+    """Widget-relative y-coordinate in pixels."""
+    rootx: int
+    """Screen (root) x-coordinate in pixels."""
+    rooty: int
+    """Screen (root) y-coordinate in pixels."""
+    state: int
+    """Modifier key bitmask (Shift, Ctrl, Alt, etc.)."""
+    time: int
+    """Event timestamp in milliseconds."""
+    keycode: int
+    """Key code for keyboard events."""
+    keysym: str
+    """Key symbol name for keyboard events (e.g., `'Return'`, `'Escape'`, `'a'`)."""
+    button: int
+    """Mouse button number — 1=left, 2=middle, 3=right."""
+    delta: int
+    """Scroll wheel delta (positive = up, negative = down)."""
+    width: int
+    """Width value for Configure events."""
+    height: int
+    """Height value for Configure events."""
+    when: str
+    """When to deliver the event — `'now'`, `'tail'`, `'mark'`, or `'head'`. Defaults to `'tail'`."""
+
+
+class BindingsMixin:
+    """Event binding and virtual event generation.
+
+    This mixin documents the *Tkinter-style* binding API (`bind`, `unbind`,
+    `bind_all`, etc.) while reflecting bootstack v2's enhanced event system.
+
+    Differences from stock Tkinter:
+        - Virtual events generated via `event_generate("<<Name>>", data=...)` may
+          carry **arbitrary Python objects** as event payload.
+        - Event handlers receive an event object with a consistent `.data` attribute:
+            - `.data` is the Python object you passed for virtual events.
+            - `.data` is `None` for non-virtual events.
+
+    Notes:
+        - Prefer `bind` over `bind_all` unless you truly need a global binding.
+        - Return the string `"break"` from a handler to stop further processing.
+        - Virtual event data is intended for application-local messaging.
+    """
+
+    # ---------------------------------------------------------------------
+    # Binding (widget, class, and application/global)
+    # ---------------------------------------------------------------------
+
+    def bind(
+            self,
+            sequence: str | None = None,
+            func: Callable[..., Any] | None = None,
+            add: bool | str | None = None,
+    ) -> str | None:
+        """Bind an event sequence to a handler.
+
+        Args:
+            sequence: Event pattern string (e.g. `"<Button-1>"`, `"<KeyPress>"`, `"<<MyEvent>>"`).
+                If None, returns a string describing all bindings on this widget.
+            func: Handler callable. The handler is called with a single argument:
+                the event object. For bootstack enhanced events, `event.data`
+                is always present (None for regular events, payload for virtual events).
+            add: If true/`"+"` then this binding is added in addition to existing bindings.
+                If false/None then any existing binding for this sequence is replaced.
+
+        Returns:
+            If `func` is provided, returns an internal Tk binding id that can be used
+            with `unbind(sequence, funcid)`. If `func` is None, returns a Tcl binding
+            script string (Tkinter behavior varies by version) or None.
+
+        Examples:
+            Bind a regular event:
+
+                widget.bind("<Button-1>", on_click)
+
+            Bind a virtual event that carries Python data:
+
+                widget.bind("<<Save>>", on_save)
+                widget.event_generate("<<Save>>", data={"path": "doc.txt"})
+        """
+        return super().bind(sequence, func, add)  # type: ignore[misc]
+
+    def unbind(self, sequence: str, funcid: str | None = None) -> None:
+        """Remove a binding for an event sequence.
+
+        Args:
+            sequence: The event sequence that was previously bound.
+            funcid: The binding id returned from `bind`. If omitted, removes all
+                handlers for the given sequence on this widget.
+        """
+        return super().unbind(sequence, funcid)  # type: ignore[misc]
+
+    def bind_all(
+            self,
+            sequence: str | None = None,
+            func: Callable[..., Any] | None = None,
+            add: bool | str | None = None,
+    ) -> str | None:
+        """Bind an event sequence at the application level (all widgets).
+
+        Use sparingly. This affects *every* widget in the application.
+
+        Args:
+            sequence: Event pattern string.
+            func: Handler callable.
+            add: Whether to add alongside existing bindings.
+
+        Returns:
+            A binding id when setting a binding, otherwise a binding script string
+            (version-dependent) or None.
+        """
+        return super().bind_all(sequence, func, add)  # type: ignore[misc]
+
+    def unbind_all(self, sequence: str) -> None:
+        """Remove an application-level binding for the given sequence.
+
+        Args:
+            sequence: The event sequence to unbind.
+        """
+        return super().unbind_all(sequence)  # type: ignore[misc]
+
+    def bind_class(
+            self,
+            className: str,
+            sequence: str | None = None,
+            func: Callable[..., Any] | None = None,
+            add: bool | str | None = None,
+    ) -> str | None:
+        """Bind an event sequence to a Tk widget class.
+
+        This attaches a handler to *all widgets of a given Tk class name*
+        (e.g. `"TButton"`, `"TEntry"`).
+
+        Args:
+            className: Tk class name.
+            sequence: Event pattern string.
+            func: Handler callable.
+            add: Whether to add alongside existing bindings.
+
+        Returns:
+            A binding id when setting a binding, otherwise a binding script string
+            (version-dependent) or None.
+        """
+        return super().bind_class(className, sequence, func, add)  # type: ignore[misc]
+
+    def unbind_class(self, className: str, sequence: str) -> None:
+        """Remove a class-level binding.
+
+        Args:
+            className: Tk class name.
+            sequence: Event sequence to unbind for that class.
+        """
+        return super().unbind_class(className, sequence)  # type: ignore[misc]
+
+    # ---------------------------------------------------------------------
+    # Event generation (including virtual-event payloads)
+    # ---------------------------------------------------------------------
+
+    def event_generate(self, sequence: str, data: Any | None = None, **kw: Unpack[EventGenerateKwargs]) -> None:
+        """Generate an event.
+
+        Synthesizes both physical events (e.g. `"<Button-1>"`) and virtual events
+        (e.g. `"<<MyEvent>>"`). For virtual events, bootstack supports attaching
+        a Python payload via `data`.
+
+        Args:
+            sequence: Event sequence to generate (commonly `"<<Name>>"` for virtual events).
+            data: Optional Python object payload for virtual events. Handlers receive
+                an event whose `.data` is this value. Ignored for non-virtual events.
+            **kw: See `EventGenerateKwargs` for Tk event field overrides (x, y, state, etc.).
+        """
+        return super().event_generate(sequence, data=data, **kw)  # type: ignore[misc]

bootstack/_core/capabilities/bindtags.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+
+class BindtagsMixin:
+    """Bindtags helpers (bindtags).
+
+    Bindtags control **the order in which Tk processes bindings** for an event.
+
+    Every widget has a list of bindtags. When an event occurs on a widget, Tk
+    processes bindings in tag order. Each tag may have bindings associated with it.
+
+    Typical default bindtags for a widget look like:
+
+        (widget_pathname, widget_class, toplevel_pathname, "all")
+
+    Practical uses:
+        - Insert a custom tag (e.g. "MyApp") to apply shared behaviors across widgets.
+        - Reorder tags to change precedence (e.g. run class bindings before widget bindings).
+        - Remove a tag to disable a layer of default behavior (use with care).
+
+    Notes:
+        - Bindtags affect event dispatch only; they do not change focus or grab behavior.
+        - Misordering tags can break default widget behaviors (Tab traversal, selection,
+          text editing, etc.), so keep changes minimal and well-scoped.
+    """
+
+    def bindtags(self, tags: Sequence[str] | None = None) -> tuple[str, ...]:
+        """Get or set the bindtags for this widget.
+
+        Args:
+            tags: The bindtags to set. If None, returns the current bindtags.
+                Tags are processed in order when dispatching events.
+
+        Returns:
+            The current bindtags as a tuple.
+        """
+        # Tkinter's `bindtags()` returns a tuple and accepts a sequence for setting.
+        if tags is None:
+            return super().bindtags()  # type: ignore[misc]
+        return super().bindtags(tags)  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Convenience helpers (optional)
+    # -------------------------------------------------------------------------
+
+    def bindtags_prepend(self, tag: str) -> tuple[str, ...]:
+        """Prepend a tag to the bindtags list.
+
+        This increases the tag's priority (it will be processed earlier).
+
+        Args:
+            tag: Tag name to prepend.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        if tag not in current:
+            current.insert(0, tag)
+            self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_append(self, tag: str) -> tuple[str, ...]:
+        """Append a tag to the bindtags list.
+
+        This decreases the tag's priority (it will be processed later).
+
+        Args:
+            tag: Tag name to append.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        if tag not in current:
+            current.append(tag)
+            self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_remove(self, tag: str) -> tuple[str, ...]:
+        """Remove a tag from the bindtags list.
+
+        Args:
+            tag: Tag name to remove.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = [t for t in self.bindtags() if t != tag]
+        self.bindtags(current)
+        return tuple(current)
+
+    def bindtags_replace(self, old: str, new: str) -> tuple[str, ...]:
+        """Replace a bindtag with another tag.
+
+        Args:
+            old: Existing tag name.
+            new: Replacement tag name.
+
+        Returns:
+            The updated bindtags tuple.
+        """
+        current = list(self.bindtags())
+        try:
+            idx = current.index(old)
+        except ValueError:
+            return tuple(current)
+        current[idx] = new
+        self.bindtags(current)
+        return tuple(current)