bootstack 0.1.0a1__py3-none-any.whl

bootstack/core/capabilities/localization.py

@@ -0,0 +1,231 @@
+"""Localization capability for bootstack widgets.
+
+This module provides the core framework service for localizing widget text
+and values. It handles text resolution, value formatting, and locale change
+propagation.
+
+The widget mixin (LocalizationMixin) delegates to these functions to remain
+a thin glue layer.
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from bootstack.core.localization.msgcat import MessageCatalog
+from bootstack.core.localization.specs import (
+    LocalizedSpec,
+    LocalizedTextSpec,
+    LocalizedValueSpec,
+)
+
+if TYPE_CHECKING:
+    from bootstack.core.signals import Signal
+
+
+# =============================================================================
+# Text Resolution
+# =============================================================================
+
+def resolve_text(
+    value: Any,
+    *,
+    localize_mode: bool | str = True,
+) -> LocalizedTextSpec | None:
+    """Resolve a text value into a LocalizedTextSpec.
+
+    This function handles the logic for creating localization specs from
+    string values based on the localization mode.
+
+    Args:
+        value: The value to resolve. Can be:
+            - A LocalizedSpec: returned as-is (if it's a LocalizedTextSpec)
+            - A string: wrapped in LocalizedTextSpec if localize_mode is truthy
+            - None or empty string: returns None
+        localize_mode: Controls auto-wrapping of literals:
+            - True or "auto": wrap strings in LocalizedTextSpec
+            - False: return None (no localization)
+
+    Returns:
+        A LocalizedTextSpec if the value should be localized, None otherwise.
+
+    Examples:
+        >>> spec = resolve_text("Hello World")
+        >>> spec.key
+        'Hello World'
+
+        >>> spec = resolve_text("Hello", localize_mode=False)
+        >>> spec is None
+        True
+
+        >>> from bootstack.core.localization.specs import L
+        >>> spec = resolve_text(L("greeting"))
+        >>> spec.key
+        'greeting'
+    """
+    if value is None:
+        return None
+
+    if isinstance(value, str) and value == "":
+        return None
+
+    # If already a LocalizedSpec, return as-is
+    if isinstance(value, LocalizedTextSpec):
+        return value
+    if isinstance(value, LocalizedSpec):
+        # Other spec types (like LocalizedValueSpec) - cannot use as text
+        return None
+
+    # Check localize mode
+    if localize_mode is False:
+        return None
+
+    # Wrap string in LocalizedTextSpec
+    if isinstance(value, str):
+        return LocalizedTextSpec(key=value, original=value)
+
+    return None
+
+
+def resolve_variable_text(
+    value: Any,
+    *,
+    value_format: str | None = None,
+    default_format: str = "decimal",
+) -> LocalizedValueSpec | None:
+    """Resolve a non-string value into a LocalizedValueSpec for formatting.
+
+    This function handles the logic for creating value formatting specs from
+    numeric or other values.
+
+    Args:
+        value: The value to format. Should be a number, date, or other
+            formattable type.
+        value_format: The IntlFormatter spec (e.g., "currency", "decimal",
+            "percent"). If None, uses default_format.
+        default_format: Fallback format spec when value_format is None.
+
+    Returns:
+        A LocalizedValueSpec if the value can be formatted, None otherwise.
+
+    Examples:
+        >>> spec = resolve_variable_text(1234.56, value_format="currency")
+        >>> spec.value
+        1234.56
+        >>> spec.format_spec
+        'currency'
+
+        >>> spec = resolve_variable_text(0.5, value_format="percent")
+        >>> spec.format_spec
+        'percent'
+    """
+    if value is None:
+        return None
+
+    if isinstance(value, LocalizedValueSpec):
+        return value
+
+    if isinstance(value, str):
+        # Strings are handled by resolve_text, not this function
+        return None
+
+    fmt = value_format or default_format
+    return LocalizedValueSpec(value=value, format_spec=fmt)
+
+
+def apply_spec(spec: LocalizedSpec, locale: str | None = None) -> str:
+    """Apply a localization spec and return the resolved string.
+
+    Args:
+        spec: The LocalizedSpec to resolve.
+        locale: The locale to use. If None, uses the current locale from
+            MessageCatalog.
+
+    Returns:
+        The resolved, localized string value.
+
+    Examples:
+        >>> from bootstack.core.localization.specs import L, LV
+        >>> spec = L("hello")
+        >>> result = apply_spec(spec)  # Uses current locale
+        >>> isinstance(result, str)
+        True
+
+        >>> spec = LV(1234.56, "decimal")
+        >>> result = apply_spec(spec)
+        >>> isinstance(result, str)
+        True
+    """
+    if not spec.enabled:
+        # Return original if possible, else empty
+        if isinstance(spec, LocalizedTextSpec):
+            return spec.original or spec.key
+        elif isinstance(spec, LocalizedValueSpec):
+            return str(spec.value)
+        return ""
+
+    current_locale = locale or MessageCatalog.locale()
+    return spec.resolve(current_locale)
+
+
+def get_current_locale() -> str:
+    """Get the current locale from MessageCatalog.
+
+    Returns:
+        The current locale code (e.g., "en_US", "de_DE").
+    """
+    return MessageCatalog.locale()
+
+
+# =============================================================================
+# Signal Formatting
+# =============================================================================
+
+def create_formatted_signal(
+    source_signal: 'Signal[Any]',
+    value_format: str,
+) -> tuple['Signal[str]', Any]:
+    """Create a formatted signal that tracks a source signal.
+
+    This creates a new Signal for formatted display that subscribes to the
+    source signal and automatically formats values when they change.
+
+    Args:
+        source_signal: The source Signal to subscribe to.
+        value_format: The IntlFormatter spec for formatting values.
+
+    Returns:
+        A tuple of (formatted_signal, formatter_callback) where:
+        - formatted_signal: A new Signal[str] containing the formatted value
+        - formatter_callback: The callback function for locale change updates
+
+    Examples:
+        >>> from bootstack.core.signals import Signal
+        >>> price = Signal(1234.56)
+        >>> formatted, formatter = create_formatted_signal(price, "currency")
+        >>> # formatted.get() returns locale-formatted currency string
+    """
+    from bootstack.core.signals import Signal
+
+    formatted_signal: Signal[str] = Signal("")
+
+    def format_signal_value(value: Any) -> None:
+        """Format the signal value using the current locale."""
+        spec = LocalizedValueSpec(value=value, format_spec=value_format)
+        locale = MessageCatalog.locale()
+        formatted = spec.resolve(locale)
+        formatted_signal.set(formatted)
+
+    # Subscribe with immediate execution to format initial value
+    source_signal.subscribe(format_signal_value, immediate=True)
+
+    return formatted_signal, format_signal_value
+
+
+__all__ = [
+    "resolve_text",
+    "resolve_variable_text",
+    "apply_spec",
+    "get_current_locale",
+    "create_formatted_signal",
+]

bootstack/core/capabilities/pack.py

@@ -0,0 +1,119 @@
+"""Pack geometry manager capabilities mixin for bootstack widgets."""
+from __future__ import annotations
+
+from typing import Any, Literal, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+class PackMixin:
+    """Pack geometry manager helpers (pack).
+
+    Tk's `pack` geometry manager places widgets relative to the sides of a container.
+
+    In bootstack v2 you may prefer higher-level layout containers (e.g. `PackFrame`)
+    for most UI layout. This mixin documents the underlying Tkinter `pack_*` API
+    as an escape hatch and for interoperability with existing Tk code.
+
+    Notes:
+        - `pack()` attaches a widget to a parent container that is using pack.
+        - `pack_propagate(False)` prevents a container from resizing to fit its children.
+        - `fill`, `expand`, and `side` control how a widget consumes available space.
+        - If the parent has a `_on_child_pack` hook (e.g. PackFrame), layout defaults
+          are applied automatically.
+    """
+
+    # -------------------------------------------------------------------------
+    # Core widget methods
+    # -------------------------------------------------------------------------
+
+    def pack(self, cnf: dict[str, Any] | None = None, **kw: Any) -> Self:
+        """Position this widget using the pack geometry manager.
+
+        Args:
+            cnf: Optional dict of pack options.
+            **kw: Pack options. Common options include:
+                - side: Which side to pack against ("top", "bottom", "left", "right").
+                - fill: How the widget should fill extra space ("x", "y", "both", "none").
+                - expand: Whether the widget expands to fill extra space (0/1 or False/True).
+                - anchor: Where to place the widget if it does not fill the space.
+                - padx, pady: External padding around the widget.
+                - ipadx, ipady: Internal padding inside the widget.
+                - before, after: Pack relative to another widget.
+
+        Returns:
+            Self for method chaining.
+        """
+        options = cnf or {}
+        options.update(kw)
+
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, '_on_child_pack'):
+            parent._on_child_pack(self, **options)
+        else:
+            super().pack(**options)  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def pack_configure(self, cnf: dict[str, Any] | None = None, **kw: Any) -> Self:
+        """Alias for `pack()`.
+
+        Args:
+            cnf: Optional dict of pack options.
+            **kw: Pack options (see `pack`).
+
+        Returns:
+            Self for method chaining.
+        """
+        return self.pack(cnf, **kw)
+
+    def pack_forget(self) -> Self:
+        """Unmap this widget and forget its pack configuration.
+
+        The widget is removed from the layout, and its previous pack options
+        are discarded.
+
+        Returns:
+            Self for method chaining.
+        """
+        parent = self.master  # type: ignore[attr-defined]
+        if hasattr(parent, '_on_child_pack_forget'):
+            parent._on_child_pack_forget(self)
+        else:
+            super().pack_forget()  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def pack_info(self) -> dict[str, Any]:
+        """Return this widget's current pack configuration.
+
+        Returns:
+            A dict containing the current pack options for this widget
+            (side, fill, expand, padx, pady, etc.).
+        """
+        return super().pack_info()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Container methods (applied to the pack parent container)
+    # -------------------------------------------------------------------------
+
+    def pack_propagate(self, flag: bool | None = None) -> bool | None:
+        """Get or set pack geometry propagation for this container.
+
+        When propagation is enabled (default), the container may resize itself
+        to fit the size requests of its children.
+
+        Args:
+            flag: True/False to enable/disable propagation. If None, acts as a getter.
+
+        Returns:
+            When queried, returns the current propagation flag. When set, returns None.
+        """
+        return super().pack_propagate(flag)  # type: ignore[misc]
+
+    def pack_slaves(self) -> list[Any]:
+        """Return the widgets managed by pack in this container.
+
+        Returns:
+            A list of child widgets managed by pack (in packing order).
+        """
+        return super().pack_slaves()  # type: ignore[misc]

bootstack/core/capabilities/place.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+class PlaceMixin:
+    """Place geometry manager helpers (place).
+
+    Tk's `place` geometry manager positions widgets using absolute coordinates
+    and/or relative fractions of the container size.
+
+    `place` is useful for:
+        - overlays (badges, floating buttons, popovers)
+        - precise positioning inside a fixed-size container
+        - small "anchor" adjustments that don't fit grid/pack well
+
+    Notes:
+        - `place` is generally less adaptive than `grid` or `pack` for resizable UIs.
+        - Relative coordinates (`relx`, `rely`, `relwidth`, `relheight`) are fractions
+          of the container size (0.0–1.0).
+    """
+
+    # -------------------------------------------------------------------------
+    # Core widget methods
+    # -------------------------------------------------------------------------
+
+    def place(self, cnf: dict[str, Any] | None = None, **kw: Any) -> Self:
+        """Position this widget using the place geometry manager.
+
+        Args:
+            cnf: Optional dict of place options.
+            **kw: Place options. Common options include:
+                - x, y: Absolute coordinates in pixels (relative to container).
+                - relx, rely: Relative coordinates (0.0–1.0) of the container size.
+                - width, height: Absolute size in pixels.
+                - relwidth, relheight: Relative size (0.0–1.0) of the container size.
+                - anchor: Which point of the widget is placed at (x, y) / (relx, rely)
+                  (e.g. "nw", "center", "se").
+                - bordermode: How to interpret x/y relative to container borders.
+
+        Returns:
+            Self for method chaining.
+        """
+        options = cnf or {}
+        options.update(kw)
+        super().place(**options)  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def place_configure(self, cnf: dict[str, Any] | None = None, **kw: Any) -> Self:
+        """Alias for `place()`.
+
+        Args:
+            cnf: Optional dict of place options.
+            **kw: Place options (see `place`).
+
+        Returns:
+            Self for method chaining.
+        """
+        return self.place(cnf, **kw)
+
+    def place_forget(self) -> Self:
+        """Unmap this widget and forget its place configuration.
+
+        Returns:
+            Self for method chaining.
+        """
+        super().place_forget()  # type: ignore[misc]
+        return self  # type: ignore[return-value]
+
+    def place_info(self) -> dict[str, Any]:
+        """Return this widget's current place configuration.
+
+        Returns:
+            A dict containing the current place options for this widget
+            (x, y, relx, rely, width, height, etc.).
+        """
+        return super().place_info()  # type: ignore[misc]
+
+    # -------------------------------------------------------------------------
+    # Container methods
+    # -------------------------------------------------------------------------
+
+    def place_slaves(self) -> list[Any]:
+        """Return the widgets managed by place in this container.
+
+        Returns:
+            A list of child widgets managed by place.
+        """
+        return super().place_slaves()  # type: ignore[misc]

bootstack/core/capabilities/selection.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+
+class SelectionMixin:
+    """X selection helpers (selection).
+
+    Tk’s `selection` command provides access to the X selection mechanism (ICCCM),
+    most commonly the **PRIMARY** selection, and also supports **CLIPBOARD** and
+    other named selections.
+
+    Portability notes:
+        - On X11, PRIMARY is a system-wide selection shared across processes.
+        - On Windows, PRIMARY is provided by Tk (not the OS) and is shared only
+          within related interpreters, not across processes.
+        - For clipboard-style usage, Tk also provides the `clipboard_*` methods,
+          which are often a better cross-platform fit.
+
+    Intended usage:
+        class Widget(SelectionMixin, ttk.Widget): ...
+        class App(SelectionMixin, tkinter.Tk): ...
+    """
+
+    def selection_clear(self, **kw: Any) -> None:
+        """Clear a selection so that no window owns it.
+
+        This corresponds to `selection clear` and clears the specified selection
+        on the target display (if it exists).
+
+        Args:
+            **kw: Selection options forwarded to Tkinter. Common options include:
+                - selection: The selection name (e.g. "PRIMARY", "CLIPBOARD").
+                  Defaults to "PRIMARY".
+                - displayof: A widget/window whose display should be targeted.
+                  Defaults to "." (the application’s main display).
+        """
+        return super().selection_clear(**kw)  # type: ignore[misc]
+
+    def selection_get(self, **kw: Any) -> str:
+        """Return the current contents of a selection.
+
+        This corresponds to `selection get` and retrieves a selection from the
+        target display. The default selection is "PRIMARY" and the default type
+        is "STRING".
+
+        Args:
+            **kw: Selection options forwarded to Tkinter. Common options include:
+                - selection: The selection name (e.g. "PRIMARY", "CLIPBOARD").
+                  Defaults to "PRIMARY".
+                - type: The desired “target” type for conversion (e.g. "STRING",
+                  "UTF8_STRING", "TARGETS", "FILE_NAME"). Defaults to "STRING".
+                - displayof: A widget/window whose display should be targeted.
+                  Defaults to ".".
+
+        Returns:
+            The selection contents as a string.
+
+        Notes:
+            - If the owner returns a non-string representation (e.g. ATOM or INTEGER),
+              Tk converts it to a space-separated string representation.
+            - Tk will not retrieve UTF-8 formatted data unless you request
+              `type="UTF8_STRING"`.
+        """
+        return super().selection_get(**kw)  # type: ignore[misc]
+
+    def selection_handle(self, command: str | None, **kw: Any) -> None:
+        """Register or remove a handler for selection retrieval requests.
+
+        This corresponds to `selection handle`. When this widget owns a selection,
+        Tk will execute *command* when another client attempts to retrieve the
+        selection in the requested type.
+
+        Args:
+            command: A Tcl command (string) to execute to supply selection data.
+                If an empty string or None, removes any existing handler for the
+                given selection/type combination.
+            **kw: Handler options forwarded to Tkinter. Common options include:
+                - selection: Selection name (defaults to "PRIMARY").
+                - type: Requested type (defaults to "STRING").
+                - format: Representation format used to transmit the selection
+                  (defaults to "STRING"). Usually only needed for compatibility
+                  with non-Tk requesters.
+
+        Notes:
+            - When handling type "STRING", Tk will also handle "UTF8_STRING"
+              automatically.
+            - The command is invoked with two additional arguments appended:
+              `offset` and `maxChars`. The command should return up to `maxChars`
+              characters starting at `offset`. Large selections are retrieved
+              in multiple chunks.
+        """
+        # Tkinter expects `command` to be a Tcl script; keep the pass-through shape.
+        if command is None:
+            command = ""
+        return super().selection_handle(command, **kw)  # type: ignore[misc]
+
+    def selection_own(self, **kw: Any) -> str:
+        """Query the current selection owner within this application.
+
+        This corresponds to the *query* form of `selection own`, returning the
+        pathname of the window in this application that owns the selection on
+        the target display, or an empty string if none.
+
+        Args:
+            **kw: Query options forwarded to Tkinter. Common options include:
+                - selection: Selection name (defaults to "PRIMARY").
+                - displayof: A widget/window whose display should be targeted.
+                  Defaults to ".".
+
+        Returns:
+            The pathname of the owner window in this application, or an empty
+            string if no window in this application owns the selection.
+        """
+        return super().selection_own(**kw)  # type: ignore[misc]
+
+    def selection_own_set(
+            self,
+            owner: Any,
+            command: Callable[[], Any] | None = None,
+            *,
+            selection: str = "PRIMARY",
+    ) -> None:
+        """Make *owner* the selection owner (convenience helper).
+
+        Tk’s `selection own` *setter* form is easy to confuse with the query form.
+        This helper makes the intent explicit while still using Tk’s semantics.
+
+        Args:
+            owner: The widget/window that should own the selection.
+            command: Optional callback invoked when this widget loses ownership
+                of the selection (i.e., another window claims it).
+            selection: The selection name to claim (defaults to "PRIMARY").
+        """
+        # `selection_own` in Tkinter supports setting with `command` and `selection`.
+        return super().selection_own(owner, command=command, selection=selection)  # type: ignore[misc]