bootstack 0.1.0__py3-none-any.whl

bootstack/types.py

@@ -0,0 +1,39 @@
+"""Public type aliases and token Literals for annotating bootstack code.
+
+These are the names used in widget signatures — accent/variant/surface tokens,
+layout Literals, density, and the keyword TypedDicts. Import them when you
+annotate your own helpers or widget subclasses::
+
+    from bootstack.types import AccentToken, WidgetDensity
+
+They are re-exported from :mod:`bootstack.widgets.types`.
+"""
+from bootstack.widgets.types import (
+    BaseWidgetKwargs, StyledKwargs,
+    Anchor, BorderMode, CompoundMode, Direction,
+    Fill, Justify, Orient, Padding, Relief, Side, Sticky,
+    HAlign, VAlign, HArrange, VArrange,
+    LayoutKind, AutoFlow, AccordionVariant, Region, ButtonVariant,
+    IconPosition, SelectionMode, ExportScope, ExportFormat,
+    ToastCorner, SnackbarAlign,
+    WidgetState, WidgetDensity, ScrollbarVariant,
+    AccentToken, SurfaceToken, WindowStyle,
+    ColumnSpec, EditorType, FormOptions,
+    Option, OptionDict,
+    Icon, IconSpec,
+)
+
+__all__ = [
+    "BaseWidgetKwargs", "StyledKwargs",
+    "Anchor", "BorderMode", "CompoundMode", "Direction",
+    "Fill", "Justify", "Orient", "Padding", "Relief", "Side", "Sticky",
+    "HAlign", "VAlign", "HArrange", "VArrange",
+    "LayoutKind", "AutoFlow", "AccordionVariant", "Region", "ButtonVariant",
+    "IconPosition", "SelectionMode", "ExportScope", "ExportFormat",
+    "ToastCorner", "SnackbarAlign",
+    "WidgetState", "WidgetDensity", "ScrollbarVariant",
+    "AccentToken", "SurfaceToken", "WindowStyle",
+    "ColumnSpec", "EditorType", "FormOptions",
+    "Option", "OptionDict",
+    "Icon", "IconSpec",
+]

bootstack/validation/__init__.py

@@ -0,0 +1,6 @@
+"""Validation rules and results for Field-based input widgets."""
+from .validation_rules import ValidationRule
+from .validation_result import ValidationResult
+from .types import RuleType
+
+__all__ = ['ValidationRule', 'ValidationResult', 'RuleType']

bootstack/validation/types.py

@@ -0,0 +1,15 @@
+from typing import Any, Callable, Literal, Optional, TypedDict
+
+RuleType = Literal["required", "email", "pattern", "stringLength", "range", "custom", "compare"]
+"""A built-in validation rule name."""
+
+RuleTriggerType = Literal['key', 'blur', 'always', 'manual']
+
+
+class ValidationOptions(TypedDict, total=False):
+    pattern: str
+    message: str
+    min: Any
+    max: Any
+    trigger: Optional[Literal["key", "blur", "always", "manual"]]
+    func: Callable[[str], bool]

bootstack/validation/validation_result.py

@@ -0,0 +1,17 @@
+class ValidationResult:
+    """The outcome of a single validation check.
+
+    Attributes:
+        is_valid (bool): True if validation passed, False otherwise.
+        message (str): Error message when `is_valid` is False; empty string otherwise.
+    """
+
+    def __init__(self, is_valid: bool, message: str = ""):
+        """Create a validation result.
+
+        Args:
+            is_valid: True if validation passed.
+            message: Error message. Defaults to an empty string.
+        """
+        self.is_valid = is_valid
+        self.message = message

bootstack/validation/validation_rules.py

@@ -0,0 +1,205 @@
+import re
+from typing import Callable
+
+from bootstack.validation.types import RuleTriggerType, RuleType
+from bootstack.validation.validation_result import ValidationResult
+
+
+# Rules that operate on a text value; meaningless on a typed (number/date/time)
+# value. The field rejects these at attach time when it does not hold text.
+TEXT_RULES = frozenset({"stringLength", "pattern", "email"})
+
+# Rules that operate on an orderable typed value (number, date, or time).
+ORDERED_RULES = frozenset({"range"})
+
+
+def rule_applies_to_kind(rule_type: str, kind: str) -> bool:
+    """Whether a rule type can validate a field holding the given value kind.
+
+    Args:
+        rule_type: The rule name (e.g. `'stringLength'`, `'range'`).
+        kind: The field's value kind — `'text'`, `'number'`, `'date'`, or
+            `'time'`.
+
+    Returns:
+        `True` if the rule applies. Text rules apply only to text fields;
+        `'range'` applies only to ordered (number/date/time) fields; the
+        remaining rules (`'required'`, `'compare'`, `'custom'`) apply to any.
+    """
+    if rule_type in TEXT_RULES:
+        return kind == "text"
+    if rule_type in ORDERED_RULES:
+        return kind in ("number", "date", "time")
+    return True
+
+
+def _as_text(value: object) -> str:
+    """Coerce a value to text for the string rules.
+
+    The string rules (`stringLength`, `pattern`, `email`) operate on text. When
+    one is applied to a typed value (a number or date), coerce rather than crash;
+    the rule taxonomy rejects that misuse at attach time, this is the last-ditch
+    guard. `None` (an empty field) becomes the empty string.
+    """
+    if isinstance(value, str):
+        return value
+    return "" if value is None else str(value)
+
+
+class ValidationRule:
+    """A single validation rule that can be applied to a string value.
+
+    Supports the built-in rule types `'required'`, `'email'`,
+    `'stringLength'`, `'pattern'`, `'compare'`, and `'custom'`, and carries a
+    trigger policy that controls when the rule is evaluated.
+
+    Attributes:
+        type (RuleType): The validation rule type.
+        message (str): Custom error message; if empty a default is generated.
+        trigger (RuleTriggerType): When the rule fires — `'always'`, `'key'`,
+            `'blur'`, or `'manual'`.
+        params (dict): Additional parameters specific to the rule type
+            (e.g., `min`/`max` for `'stringLength'`, `pattern` for `'pattern'`,
+            `other_field` for `'compare'`, `func` for `'custom'`).
+    """
+
+    def __init__(
+            self,
+            rule_type: RuleType,
+            message: str = "",
+            **kwargs
+    ):
+        """Create a validation rule.
+
+        Args:
+            rule_type: The type of validation to apply.
+            message: Custom error message. If empty, a sensible default is used.
+            **kwargs: Rule-specific parameters.  Pass `trigger` to override the
+                default trigger policy; all other keys are stored in `params`
+                (e.g., `min=3, max=20` for `'stringLength'`, `pattern=r'\\d+'`
+                for `'pattern'`, `func=callable` for `'custom'`).
+        """
+        self.type = rule_type
+        self.message = message
+        self.trigger = kwargs.pop('trigger', self._default_trigger())
+        self.params = kwargs
+
+    def validate(self, value: str) -> ValidationResult:
+        """Apply this rule to a value and return the result.
+
+        Args:
+            value: The string value to validate.
+
+        Returns:
+            A ValidationResult with `is_valid=True` on success or `is_valid=False`
+            with an error message on failure.
+        """
+        msg = self.message or self._default_message()
+
+        if self.type == "required":
+            if value is None:
+                return ValidationResult(False, msg)
+            if isinstance(value, str) and not value.strip():
+                return ValidationResult(False, msg)
+            # Everything else is valid (non-empty string, number, date, etc.)
+            return ValidationResult(True, "")
+
+        elif self.type == "email":
+            if not re.match(r"[^@]+@[^@]+\.[^@]+", _as_text(value)):
+                return ValidationResult(False, msg)
+        elif self.type == "stringLength":
+            min_len = self.params.get("min", 0)
+            max_len = self.params.get("max", float("inf"))
+            if not (min_len <= len(_as_text(value)) <= max_len):
+                return ValidationResult(False, msg)
+        elif self.type == "pattern":
+            pattern = self.params.get("pattern", "")
+            if not re.match(pattern, _as_text(value)):
+                return ValidationResult(False, msg)
+        elif self.type == "range":
+            # Bounds on an ordered value (number/date/time). An empty field is
+            # not out of range — use 'required' for presence.
+            if value is None or value == "":
+                return ValidationResult(True)
+            lo = self.params.get("min")
+            hi = self.params.get("max")
+            try:
+                if lo is not None and value < lo:
+                    return ValidationResult(False, msg)
+                if hi is not None and value > hi:
+                    return ValidationResult(False, msg)
+            except TypeError:
+                # Incomparable types (e.g. a string bound against a number).
+                return ValidationResult(False, msg)
+        elif self.type == "compare":
+            if value != self._read_other(self.params.get("other_field")):
+                return ValidationResult(False, msg)
+        elif self.type == "custom":
+            func: Callable[[str], bool] = self.params.get("func")
+            if func and not func(value):
+                return ValidationResult(False, msg)
+
+        return ValidationResult(True)
+
+    @staticmethod
+    def _read_other(other: object) -> object:
+        """Resolve the current value of a `'compare'` rule's `other_field`.
+
+        Accepts a `Signal` or any zero-argument callable (called to read), a
+        field wrapper exposing a `value` property, or a plain literal value.
+
+        Args:
+            other: The `other_field` parameter passed to the rule.
+
+        Returns:
+            The other field's current value, or `None` if `other` is `None`.
+        """
+        if other is None:
+            return None
+        if callable(other):
+            return other()
+        if hasattr(other, "value"):
+            return other.value
+        return other
+
+    def _default_message(self) -> str:
+        """Return a sensible default error message for this rule type."""
+        if self.type == "required":
+            return "This field is required."
+        elif self.type == "email":
+            return "Enter a valid email address."
+        elif self.type == "stringLength":
+            min_len = self.params.get("min", 0)
+            max_len = self.params.get("max", None)
+            if max_len is None or max_len == float("inf"):
+                return f"Enter at least {min_len} characters."
+            return f"Enter between {min_len} and {max_len} characters."
+        elif self.type == "pattern":
+            return "Value does not match the required pattern."
+        elif self.type == "range":
+            lo = self.params.get("min")
+            hi = self.params.get("max")
+            if lo is not None and hi is not None:
+                return f"Enter a value between {lo} and {hi}."
+            if lo is not None:
+                return f"Enter a value of at least {lo}."
+            if hi is not None:
+                return f"Enter a value of at most {hi}."
+            return "Value is out of range."
+        elif self.type == "compare":
+            return "Values do not match."
+        elif self.type == "custom":
+            return "Invalid value."
+        return "Invalid input."
+
+    def _default_trigger(self) -> RuleTriggerType:
+        """Return the default trigger policy for this rule type."""
+        if self.type == "required":
+            return "always"
+        elif self.type in {"stringLength", "compare", "range"}:
+            return "blur"
+        elif self.type in {"email", "pattern"}:
+            return "always"
+        elif self.type in {"custom"}:
+            return "manual"
+        return "blur"

bootstack/widgets/__init__.py

@@ -0,0 +1,74 @@
+"""Widget package for bootstack.
+
+Public widgets are lazily importable from this package — e.g.
+`from bootstack.widgets import Button` — mirroring the canonical
+`import bootstack as bs; bs.Button` access. Resolution is lazy (PEP 562)
+so importing the package does not eagerly pull in every widget module.
+"""
+from typing import Any
+
+# Public widget-area name -> defining submodule (relative to this package).
+# Single source of truth for the runtime namespace below.
+_EXPORTS: dict[str, str] = {
+    # Application & windows
+    "App": "app", "AppShell": "appshell", "Workbench": "appshell",
+    "Window": "window", "Splash": "splash",
+    # Layout
+    "Row": "stacks", "Column": "stacks", "Spacer": "stacks",
+    "Grid": "grid", "Card": "card",
+    "GroupBox": "groupbox", "Divider": "divider", "ScrollView": "scrollview",
+    "SplitView": "splitview", "SplitPane": "splitview",
+    "Accordion": "expander", "AccordionSection": "expander",
+    # Actions
+    "Button": "button", "ButtonGroup": "buttongroup", "MenuButton": "menubutton",
+    "Toolbar": "toolbar", "StatusBar": "statusbar",
+    "ContextMenu": "contextmenu", "ContextMenuItem": "contextmenu",
+    # Inputs
+    "TextField": "textfield", "PasswordField": "passwordfield",
+    "NumberField": "numberfield", "PathField": "pathfield",
+    "SpinnerField": "spinnerfield", "TextArea": "textarea", "CodeEditor": "codeeditor",
+    "DateField": "datefield", "TimeField": "timefield",
+    "Slider": "slider", "RangeSlider": "slider",
+    "EditFilter": "_impl.composites.textarea.filter",
+    # Selection
+    "Checkbox": "boolean_controls", "Switch": "boolean_controls",
+    "ToggleButton": "boolean_controls", "ThemeToggle": "theme_toggle",
+    "ToggleGroup": "togglegroup",
+    "Radio": "radio_variants", "RadioToggleButton": "radio_variants",
+    "RadioGroup": "radiogroup", "Select": "select", "SelectButton": "selectbutton",
+    "Calendar": "calendar",
+    # Data display
+    "Label": "label", "Badge": "label", "Picture": "picture", "Gallery": "gallery",
+    "Carousel": "carousel", "Avatar": "avatar", "ProgressBar": "progressbar",
+    "Gauge": "gauge", "ListView": "listview", "DataTable": "datatable",
+    "Tree": "tree", "TreeNode": "tree", "Chart": "chart",
+    # Navigation
+    "PageStack": "pagestack", "StackPage": "pagestack",
+    "Tabs": "tabs", "TabPage": "tabs",
+    # Overlays
+    "Tooltip": "tooltip", "toast": "toast", "Notification": "toast",
+    "Snackbar": "toast", "snackbar": "toast",
+    # Forms
+    "Form": "form", "FormItem": "form", "FieldItem": "form", "GroupItem": "form",
+    "TabsItem": "form", "TabItem": "form",
+    # Extension base classes (for building custom public widgets)
+    "PublicWidgetBase": "_core.base", "PublicContainer": "_core.container",
+}
+
+__all__ = sorted(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import and cache a public widget by name (PEP 562)."""
+    module = _EXPORTS.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    obj = getattr(importlib.import_module(f"bootstack.widgets.{module}"), name)
+    globals()[name] = obj  # cache so subsequent lookups skip __getattr__
+    return obj
+
+
+def __dir__() -> list[str]:
+    return sorted(set(globals()) | set(_EXPORTS))

bootstack/widgets/_core/__init__.py

@@ -0,0 +1,31 @@
+"""Public framework internals — extend here, do not import directly from user code."""
+from bootstack.widgets._core.base import PublicWidgetBase
+from bootstack.widgets._core.container import PublicContainer
+from bootstack.widgets._core.context import push_container, pop_container, current_container
+from bootstack.widgets._core.events import register_widget_events, resolve_event
+from bootstack.widgets.types import Event
+from bootstack.errors import BootstackError, UnknownEventError, ParentResolutionError
+from bootstack.widgets._core.field_mixin import FieldAddonMixin
+from bootstack.scheduling import Schedule, Job
+from bootstack.streams import Stream, Handle
+from bootstack.events import Subscription
+
+__all__ = [
+    "BootstackError",
+    "Event",
+    "FieldAddonMixin",
+    "Handle",
+    "Job",
+    "ParentResolutionError",
+    "PublicContainer",
+    "PublicWidgetBase",
+    "Schedule",
+    "Stream",
+    "Subscription",
+    "UnknownEventError",
+    "current_container",
+    "pop_container",
+    "push_container",
+    "register_widget_events",
+    "resolve_event",
+]

bootstack/widgets/_core/app_config.py

@@ -0,0 +1,266 @@
+"""Flat configuration properties shared by `App` and `AppShell`.
+
+The public app surface exposes configuration as flat `app.*` properties, so
+that what goes in through the constructor comes back out symmetrically:
+`App(theme=...)` in, `app.theme` out. Settable knobs reflect live where the
+machinery supports a runtime change (theme, locale, title); locale-derived
+formats are read-only.
+
+`AppConfigMixin` delegates to the internal runtime `App` returned by
+`_config_app()`, which each public class implements.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, Sequence, overload
+
+from bootstack.events import Subscription
+
+if TYPE_CHECKING:
+    from bootstack.streams import Stream
+    from bootstack.widgets.types import WindowStyle
+
+
+class AppConfigMixin:
+    """Mixin providing flat configuration properties for the public app.
+
+    Subclasses must implement `_config_app()` to return the internal runtime
+    `App` (a `tkinter.Tk` subclass) whose `settings` holds the resolved
+    configuration.
+    """
+
+    def _config_app(self) -> Any:
+        """Return the internal runtime `App` backing this public app."""
+        raise NotImplementedError
+
+    @property
+    def _settings(self) -> Any:
+        return self._config_app().settings
+
+    # ----- identity -----
+
+    @property
+    def title(self) -> str:
+        """The window title bar text (also the app's display name)."""
+        return self._config_app().title()
+
+    @title.setter
+    def title(self, value: str) -> None:
+        app = self._config_app()
+        app.title(value)
+        app.settings.app_name = value
+
+    # The app name (config-directory / taskbar identity) is set via `title=`
+    # (which writes both the title bar and `app_name`); there is no separate
+    # public `name` property — it was redundant with `title`.
+
+    # ----- theme -----
+
+    @property
+    def theme(self) -> str:
+        """The active theme name. Setting it switches the theme live."""
+        from bootstack.style.style import get_theme
+        return get_theme()
+
+    @theme.setter
+    def theme(self, value: str) -> None:
+        from bootstack.style.style import set_theme
+        set_theme(value)
+        self._settings.theme = value
+
+    @property
+    def light_theme(self) -> str:
+        """Theme used for the light end of system-appearance / `toggle_theme`."""
+        return self._settings.light_theme
+
+    @light_theme.setter
+    def light_theme(self, value: str) -> None:
+        self._settings.light_theme = value
+
+    @property
+    def dark_theme(self) -> str:
+        """Theme used for the dark end of system-appearance / `toggle_theme`."""
+        return self._settings.dark_theme
+
+    @dark_theme.setter
+    def dark_theme(self, value: str) -> None:
+        self._settings.dark_theme = value
+
+    @property
+    def follow_system_appearance(self) -> bool:
+        """Whether the app tracks the OS light/dark appearance (macOS)."""
+        return self._settings.follow_system_appearance
+
+    @follow_system_appearance.setter
+    def follow_system_appearance(self, value: bool) -> None:
+        self._settings.follow_system_appearance = value
+
+    # `available_themes` is intentionally construction-only (no runtime property):
+    # `App(available_themes=...)` reads as an input ("offer these themes"), but a
+    # getter would collide with `get_themes()` (the actual theme-list query) and
+    # return `()` by default. Read the exposed list via `get_themes()`.
+
+    # ----- localization -----
+
+    @property
+    def locale(self) -> str | None:
+        """The active locale (e.g. `'en_US'`). Setting it switches locale live."""
+        return self._settings.locale
+
+    @locale.setter
+    def locale(self, value: str) -> None:
+        from bootstack.i18n.msgcat import MessageCatalog
+        MessageCatalog.locale(value)
+        self._settings.locale = value
+
+    # `localize_mode` is construction-only (no runtime property): changing it
+    # would only affect widgets created afterward, not the existing UI, so a
+    # live setter would be misleading. Pass it to the constructor.
+
+    @property
+    def locale_language(self) -> str | None:
+        """Base language code derived from the locale (e.g. `'en'`). Read-only."""
+        from bootstack._runtime.app import _language_from_locale
+        loc = self._settings.locale
+        return _language_from_locale(loc) if loc else None
+
+    @property
+    def locale_date_format(self) -> str | None:
+        """Short date pattern for the active locale (e.g. `'M/d/yy'`). Read-only."""
+        from bootstack._runtime.app import _safe_date_format
+        loc = self._settings.locale
+        return _safe_date_format(loc) if loc else None
+
+    @property
+    def locale_time_format(self) -> str | None:
+        """Short time pattern for the active locale, e.g. h:mm a. Read-only."""
+        from bootstack._runtime.app import _safe_time_format
+        loc = self._settings.locale
+        return _safe_time_format(loc) if loc else None
+
+    @property
+    def locale_decimal(self) -> str | None:
+        """Decimal separator for the active locale (e.g. `'.'`). Read-only."""
+        from bootstack._runtime.app import _safe_decimal_symbol
+        loc = self._settings.locale
+        return _safe_decimal_symbol(loc) if loc else None
+
+    @property
+    def locale_thousands(self) -> str | None:
+        """Thousands separator for the active locale (e.g. `','`). Read-only."""
+        from bootstack._runtime.app import _safe_group_symbol
+        loc = self._settings.locale
+        return _safe_group_symbol(loc) if loc else None
+
+    # ----- platform / window state -----
+
+    @property
+    def window_style(self) -> WindowStyle | str | None:
+        """Windows-only window effect, or None to disable."""
+        return self._settings.window_style
+
+    @window_style.setter
+    def window_style(self, value: WindowStyle | str | None) -> None:
+        app = self._config_app()
+        app.settings.window_style = value
+        # Best-effort live re-apply (Windows / pywinstyles only).
+        try:
+            app._window_style = value
+            app._window_style_applied = False
+            app._apply_window_style()
+        except Exception:
+            pass
+
+    # `macos_quit_behavior` and `state_path` are construction-only (no runtime
+    # properties): both are set-once startup configuration that a user would not
+    # change while the app runs. Pass them to the constructor.
+
+    @property
+    def remember_window_state(self) -> bool:
+        """Whether window geometry is saved on close and restored on launch."""
+        return self._settings.remember_window_state
+
+    @remember_window_state.setter
+    def remember_window_state(self, value: bool) -> None:
+        self._settings.remember_window_state = value
+
+    # ----- configuration-change events -----
+
+    def _bind_value_event(
+        self,
+        sequence: str,
+        key: str,
+        handler: Callable[[Any], Any] | None,
+    ) -> "Stream | Subscription":
+        app = self._config_app()
+
+        def _decode(h: Callable[[Any], Any]) -> Callable[[Any], Any]:
+            def _wrapped(raw: Any) -> Any:
+                data = getattr(raw, "data", None)
+                value = data.get(key) if isinstance(data, dict) else data
+                return h(value)
+            return _wrapped
+
+        if handler is None:
+            from bootstack.streams import Stream
+
+            def _source(h: Callable[[Any], Any]) -> Subscription:
+                bid = app.bind(sequence, _decode(h), add="+")
+                return Subscription(app, sequence, bid)
+
+            return Stream(app, _source=_source)
+        bid = app.bind(sequence, _decode(handler), add="+")
+        return Subscription(app, sequence, bid)
+
+    @overload
+    def on_theme_change(self) -> "Stream": ...
+    @overload
+    def on_theme_change(self, handler: Callable[[str], Any]) -> Subscription: ...
+    def on_theme_change(
+        self, handler: Callable[[str], Any] | None = None
+    ) -> "Stream | Subscription":
+        """React to theme changes; the handler receives the new theme name.
+
+        Fired after the theme is fully rebuilt, so handlers can safely read new
+        colors. Useful for persisting the choice, e.g.
+        `app.on_theme_change(lambda t: store.update(theme=t))`.
+
+        Returns:
+            `Subscription` (with handler) or `Stream` (without handler).
+        """
+        return self._bind_value_event("<<BsThemeChanged>>", "theme", handler)
+
+    @overload
+    def on_locale_change(self) -> "Stream": ...
+    @overload
+    def on_locale_change(self, handler: Callable[[str], Any]) -> Subscription: ...
+    def on_locale_change(
+        self, handler: Callable[[str], Any] | None = None
+    ) -> "Stream | Subscription":
+        """React to locale changes; the handler receives the new locale code.
+
+        Returns:
+            `Subscription` (with handler) or `Stream` (without handler).
+        """
+        return self._bind_value_event("<<LocaleChanged>>", "locale", handler)
+
+
+# The set of App() constructor kwargs that map to configuration. Used by
+# App.from_store() to tolerantly filter a persisted dict (version skew).
+APP_CONFIG_KWARGS: frozenset[str] = frozenset({
+    "title",
+    "theme",
+    "light_theme",
+    "dark_theme",
+    "follow_system_appearance",
+    "available_themes",
+    "locale",
+    "localize_mode",
+    "window_style",
+    "macos_quit_behavior",
+    "remember_window_state",
+    "state_path",
+})
+
+
+__all__ = ["AppConfigMixin", "APP_CONFIG_KWARGS"]