bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/mixins/font_mixin.py

@@ -0,0 +1,368 @@
+"""Font modifier syntax for inline font customization in bootstack widgets.
+
+This module provides a mixin that enables concise font modification syntax for all
+bootstack widgets. The syntax uses bracket notation similar to style modifiers,
+allowing inline font customization without creating custom Font objects.
+
+## Syntax
+
+The full modifier syntax follows the pattern: `family[size][weight][style]`
+
+All components are optional and can be mixed in any combination. When components are
+omitted, the widget's current font values are preserved.
+
+Components:
+    - family: Font family name or typography token (e.g., 'helvetica', 'body', 'heading-lg')
+    - size: Point size (e.g., '16'), pixel size (e.g., '16px'), or size token (e.g., 'sm', 'lg')
+    - weight: 'bold' or 'normal'
+    - style: 'italic', 'roman', 'underline', 'overstrike' (comma-separated for multiple)
+
+Size Tokens:
+    xs=8pt, sm=10pt, md=12pt, lg=14pt, xl=16pt, xxl=18pt
+
+Font Tokens:
+    body, label, heading-md, heading-lg, heading-xl, display-lg, display-xl,
+    code, hyperlink, caption, body-sm, body-lg, body-xl
+
+## Behavior
+
+- **At widget creation**: Modifiers are applied to the widget's default style font
+- **At runtime**: Modifiers are applied to the widget's current font
+- **Missing family**: Uses widget's current font family (or 'body' token if none)
+- **Missing size**: Uses widget's current font size (or 'body' token size if none)
+
+## Examples
+
+Basic modifications:
+
+```python
+# Use body token, make it bold
+Label(root, text="Title", font="body[bold]")
+
+# Change current font to 16pt (preserves family)
+label.configure(font="[16]")
+
+# Make current font bold and italic (preserves family and size)
+label.configure(font="[bold,italic]")
+```
+
+Custom font families:
+
+```python
+# Helvetica, 16pt, bold
+Button(root, text="Click", font="helvetica[16][bold]")
+
+# Arial, 14 pixels (negative in Tk), bold and italic
+Label(root, text="Text", font="arial[14px][bold,italic]")
+```
+
+Size tokens:
+
+```python
+# Small size (10pt) with bold
+Entry(root, font="[sm][bold]")
+
+# Large size (14pt)
+Label(root, font="[lg]")
+```
+
+Font tokens with modifiers:
+
+```python
+# Heading-lg token with italic style
+Label(root, text="Heading", font="heading-lg[italic]")
+
+# Label token at custom size
+Button(root, text="Button", font="label[16]")
+```
+
+Multiple style modifiers:
+
+```python
+# Bold, italic, and underlined
+Label(root, text="Emphasis", font="[16][bold,italic,underline]")
+```
+
+## Integration
+
+FontMixin is automatically integrated into all bootstack widgets via TTKWrapperBase.
+No additional setup is required - all widgets supporting the 'font' argument automatically
+gain modifier syntax support.
+
+The mixin uses the @configure_delegate pattern to intercept font configuration, parse
+the modifier syntax, and apply the resolved font specification to the underlying ttk widget.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    pass
+
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+
+
+# Size tokens mapping (shortcuts for common sizes)
+SIZE_TOKENS = {
+    'xs': 8,
+    'sm': 10,
+    'md': 12,
+    'lg': 14,
+    'xl': 16,
+    'xxl': 18,
+}
+
+
+def _get_font_token_names() -> set[str]:
+    """Get all valid font token names (lazy to avoid import issues)."""
+    from bootstack.style.typography import FontTokenNames
+    return {
+        name.replace('_', '-')
+        for name in dir(FontTokenNames)
+        if not name.startswith('_')
+    }
+
+
+def parse_font_modifier(font_spec: str) -> dict[str, Any]:
+    """Parse font modifier syntax string into configuration dict.
+
+    Args:
+        font_spec: Font specification string (e.g., "helvetica[16][bold]")
+
+    Returns:
+        Dict with keys: family, size, weight, slant, underline, overstrike
+    """
+    if not font_spec or not font_spec.strip():
+        return {}
+
+    result = {}
+
+    # Find all bracketed parts: [content]
+    bracket_pattern = r'\[([^\]]+)\]'
+    parts = re.findall(bracket_pattern, font_spec)
+
+    # Get family/token (everything before first bracket, or whole string if no brackets)
+    if '[' in font_spec:
+        family_part = font_spec[:font_spec.index('[')].strip()
+    else:
+        family_part = font_spec.strip()
+
+    if family_part:
+        result['family'] = family_part
+
+    # Process each bracketed part
+    for part in parts:
+        part = part.strip()
+        if not part:
+            continue
+
+        # Check if it's a pixel size (e.g., "16px")
+        if part.endswith('px'):
+            try:
+                # Pixel sizes are negative in Tk
+                result['size'] = -int(part[:-2])
+                continue
+            except ValueError:
+                pass
+
+        # Check if it's a point size (e.g., "16")
+        if part.isdigit():
+            result['size'] = int(part)
+            continue
+
+        # Check if it's a size token (e.g., "sm", "lg")
+        if part in SIZE_TOKENS:
+            result['size'] = SIZE_TOKENS[part]
+            continue
+
+        # Otherwise, treat as comma-separated modifiers
+        modifiers = [m.strip().lower() for m in part.split(',')]
+        for modifier in modifiers:
+            if not modifier:
+                continue
+
+            # Weight modifiers
+            if modifier in ('bold', 'normal'):
+                result['weight'] = modifier
+            # Slant modifiers
+            elif modifier in ('italic', 'roman'):
+                result['slant'] = modifier
+            # Boolean modifiers
+            elif modifier == 'underline':
+                result['underline'] = True
+            elif modifier == 'overstrike':
+                result['overstrike'] = True
+
+    return result
+
+
+def build_font_from_modifier(font_spec: str, base_font: Any = None) -> tuple | str:
+    """Build Tk-compatible font tuple from modifier syntax, using base_font for missing values.
+
+    Args:
+        font_spec: Font specification with modifier syntax (e.g., "[16][bold]")
+        base_font: Base font to extend (token name or tuple); defaults to 'body' token
+
+    Returns:
+        Font tuple like ('Helvetica', 16, 'bold italic') or token name
+    """
+    from bootstack.style.typography import Typography
+
+    parsed = parse_font_modifier(font_spec)
+    if not parsed:
+        return base_font or 'body'
+
+    # Start with base font configuration
+    config = {}
+    family_is_token = False
+    font_token_names = _get_font_token_names()
+
+    # Check if family is a known token
+    if 'family' in parsed:
+        family_name = parsed['family']
+        if family_name in font_token_names:
+            # It's a font token - get its spec
+            token_spec = Typography.get_token(family_name)
+            config['family'] = token_spec.font
+            config['size'] = token_spec.size
+            config['weight'] = token_spec.weight
+            if token_spec.underline:
+                config['underline'] = token_spec.underline
+            family_is_token = True
+        else:
+            # It's a font family name
+            config['family'] = family_name
+    elif base_font:
+        # Use base font if provided
+        if isinstance(base_font, str) and base_font in font_token_names:
+            token_spec = Typography.get_token(base_font)
+            config['family'] = token_spec.font
+            config['size'] = token_spec.size
+            config['weight'] = token_spec.weight
+            if token_spec.underline:
+                config['underline'] = token_spec.underline
+        elif isinstance(base_font, tuple) and len(base_font) >= 2:
+            config['family'] = base_font[0]
+            config['size'] = base_font[1]
+            if len(base_font) >= 3:
+                # Parse weight/slant from tuple
+                styles = base_font[2].split()
+                for style in styles:
+                    if style in ('bold', 'normal'):
+                        config['weight'] = style
+                    elif style in ('italic', 'roman'):
+                        config['slant'] = style
+
+    # Apply parsed modifiers (override base)
+    if 'size' in parsed:
+        config['size'] = parsed['size']
+    if 'weight' in parsed:
+        config['weight'] = parsed['weight']
+    if 'slant' in parsed:
+        config['slant'] = parsed['slant']
+    if 'underline' in parsed:
+        config['underline'] = parsed['underline']
+    if 'overstrike' in parsed:
+        config['overstrike'] = parsed['overstrike']
+
+    # Ensure we have family and size - use body token as fallback
+    if 'family' not in config or 'size' not in config:
+        body_spec = Typography.get_token('body')
+        if 'family' not in config:
+            config['family'] = body_spec.font
+        if 'size' not in config:
+            config['size'] = body_spec.size
+
+    # Build Tk font specification as tuple (family, size, modifiers_string)
+    family = config['family']
+    size = config['size']
+    modifiers = []
+
+    if config.get('weight') == 'bold':
+        modifiers.append('bold')
+    if config.get('slant') == 'italic':
+        modifiers.append('italic')
+    if config.get('underline'):
+        modifiers.append('underline')
+    if config.get('overstrike'):
+        modifiers.append('overstrike')
+
+    if modifiers:
+        return (family, size, ' '.join(modifiers))
+    else:
+        return (family, size)
+
+
+class FontMixin:
+    """Adds font modifier syntax support to widgets at construction and runtime."""
+
+    def _init_font_mixin(self, kwargs: dict[str, Any]) -> Any:
+        """Extract and pre-process the `font` kwarg before widget construction.
+
+        Called by `TTKWrapperBase.__init__` before `super().__init__` so the
+        font modifier string is resolved to a Tk-compatible tuple early.
+
+        Args:
+            kwargs: The widget constructor kwargs dict (mutated in-place — `font`
+                is popped if present).
+
+        Returns:
+            The resolved font value (token name or tuple), or None if `font` was
+            not in kwargs.
+        """
+        if "font" not in kwargs:
+            return None
+
+        value = kwargs.pop("font")
+
+        if isinstance(value, str):
+            font_token_names = _get_font_token_names()
+
+            if value in font_token_names and "[" not in value:
+                return value
+
+            if "[" in value:
+                # Constructor-time: no widget yet, so use a stable base
+                return build_font_from_modifier(value, base_font="body")
+
+        return value
+
+    @configure_delegate("font")
+    def _delegate_font(self, value: Any = None) -> Any:
+        """Get or set the widget font, resolving bootstack modifier syntax.
+
+        Accepts a plain font name, a token name (e.g. `'body'`,
+        `'heading-lg'`), a modifier expression (e.g. `'body[bold]'`,
+        `'[16][italic]'`), or a Tk font tuple. Modifier expressions are
+        merged with the widget's current font so only the specified
+        attributes change.
+
+        Args:
+            value: Font specification, or None to query the current font.
+
+        Returns:
+            Current font value when querying, otherwise the result of
+            the underlying `configure(font=...)` call.
+        """
+        if value is None:
+            return self._ttk_base.cget(self, "font")  # type: ignore[misc]
+
+        if isinstance(value, str):
+            font_token_names = _get_font_token_names()
+
+            if value in font_token_names and "[" not in value:
+                font_value = value
+            elif "[" in value:
+                try:
+                    current_font = self._ttk_base.cget(self, "font")  # type: ignore[misc]
+                except Exception:
+                    current_font = "body"
+                font_value = build_font_from_modifier(value, base_font=current_font)
+            else:
+                font_value = value
+        else:
+            font_value = value
+
+        return self._ttk_base.configure(self, font=font_value)  # type: ignore[misc]

bootstack/widgets/_impl/mixins/icon_mixin.py

@@ -0,0 +1,61 @@
+"""Icon mixin for widgets that support theme-aware icons.
+
+Provides a `@configure_delegate('icon')` handler that applies an icon through
+the style system and preserves current style tokens, orientation, and
+surface color where applicable.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+
+
+class IconMixin:
+    """Adds `icon` configuration support via the style engine."""
+
+    configure_style_options: Callable
+    rebuild_style: Callable
+
+    @configure_delegate("icon")
+    def _delegate_icon(self, value: Any = None) -> Any:
+        """Get or set the widget icon.
+
+        Args:
+            value: Icon name (str), icon spec dict, or None to query the
+                current value.
+
+        Returns:
+            Current icon value when querying (`value` is None), otherwise
+            the result of rebuilding the widget style.
+        """
+        if value is None:
+            return self.configure_style_options("icon")
+        else:
+            self.configure_style_options(icon=value)
+            return self.rebuild_style()
+
+    @configure_delegate("icon_only")
+    def _delegate_icon_only(self, value: Any = None) -> Any:
+        """Get or set icon-only display mode.
+
+        When `True`, removes the extra padding reserved for text so the
+        icon fills the available space without a label gap.
+
+        Args:
+            value: `True` to enable icon-only mode, `False` to disable,
+                or None to query the current value.
+
+        Returns:
+            Current `icon_only` value when querying, otherwise the result
+            of rebuilding the widget style.
+        """
+        if value is None:
+            return self.configure_style_options("icon_only")
+        else:
+            self.configure_style_options(icon_only=value)
+            return self.rebuild_style()
+
+
+__all__ = ["IconMixin"]

bootstack/widgets/_impl/mixins/localization_mixin.py

@@ -0,0 +1,253 @@
+"""Localization mixin for bootstack widgets.
+
+Provides automatic text translation and value formatting based on the current
+locale. Widgets using this mixin will automatically update when the locale
+changes.
+
+This mixin is a thin glue layer that delegates resolution logic to the core
+localization capability module.
+"""
+
+from __future__ import annotations
+
+import tkinter
+from typing import Any, Dict
+from tkinter import StringVar, Misc
+
+from bootstack._core.capabilities.localization import (
+    resolve_text,
+    resolve_variable_text,
+    apply_spec,
+    create_formatted_signal,
+)
+from bootstack.i18n.specs import (
+    LocalizedSpec,
+)
+from bootstack._runtime.app import get_app_settings
+
+
+class LocalizationMixin(Misc):
+    """Mixin for widgets that support automatic text and value localization.
+
+    This mixin enables widgets to automatically localize text and format values
+    according to the current locale. It listens for locale change events and
+    updates all registered fields accordingly.
+
+    This mixin delegates resolution logic to the core localization capability.
+
+    Attributes:
+        localize: Controls whether literals are auto-wrapped into localization specs.
+            Can be True, False, or "auto".
+        value_format: Default IntlFormatter spec for non-string values (e.g., 'currency',
+            'decimal', 'percent').
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize the localizable widget mixin.
+
+        This mixin intercepts localization-related kwargs. It inspects 'text'
+        for localization without consuming it, so it can be passed to the
+        underlying widget. It consumes 'localize' and 'value_format' as they
+        are not standard ttk options.
+        """
+        # Determine the localization mode. A widget-specific 'localize' argument
+        # overrides the global app setting. This argument is consumed from kwargs.
+        localize = kwargs.pop('localize', get_app_settings().localize_mode)
+        value_format = kwargs.pop('value_format', None)
+
+        # Get 'text' for localization without removing it from kwargs.
+        text_to_localize = kwargs.get('text')
+
+        # Call the next class in the MRO with the remaining kwargs.
+        # 'text' is still in kwargs for the underlying widget to use.
+        super().__init__(*args, **kwargs)
+
+        # --- Post-init setup ---
+        self._localized_fields: Dict[str, LocalizedSpec] = {}
+        self._localize_mode = localize
+        self._default_value_format = value_format
+
+        root = self.winfo_toplevel()  # event is generated on root
+        root.bind("<<LocaleChanged>>", self._on_locale_changed, add="+")
+
+        # Check if widget has a textsignal or textvariable with value_format
+        if value_format and self._has_signal_or_variable():
+            self._setup_signal_formatting(value_format)
+        else:
+            # Register the text field for static localization
+            self.register_localized_field('text', text_to_localize, value_format=value_format)
+
+    def _has_signal_or_variable(self) -> bool:
+        """Check if the widget has a textsignal, textvariable, or configured textvariable.
+
+        Returns:
+            True if any signal/variable binding exists.
+        """
+        if hasattr(self, '_textsignal') or hasattr(self, '_textvariable'):
+            return True
+        try:
+            textvariable_name = self.cget('textvariable')
+            return bool(textvariable_name)
+        except Exception:
+            return False
+
+    def register_localized_field(
+        self,
+        field_name: str,
+        value: Any,
+        *,
+        value_format: str | None = None,
+        localize: bool | str | None = None,
+    ) -> None:
+        """Register a widget field for automatic localization.
+
+        Args:
+            field_name: The widget field name (e.g., "text", "textvariable").
+            value: The value to localize. Can be a literal string/number or a LocalizedSpec.
+            value_format: Optional IntlFormatter spec for non-string values (e.g., 'currency').
+            localize: Override the widget's default localization mode for this field.
+        """
+        if value is None:
+            return
+
+        if isinstance(value, str) and value == "":
+            return
+
+        localize_mode = self._localize_mode if localize is None else localize
+
+        # If already a spec, use it directly
+        if isinstance(value, LocalizedSpec):
+            self._localized_fields[field_name] = value
+            self._apply_spec_now(field_name, value)
+            return
+
+        if localize_mode is False:
+            return
+
+        # Resolve the value to a spec using core capability
+        if isinstance(value, str):
+            spec = resolve_text(value, localize_mode=localize_mode)
+        else:
+            spec = resolve_variable_text(
+                value,
+                value_format=value_format,
+                default_format=self._default_value_format or "decimal",
+            )
+
+        if spec is not None:
+            self._localized_fields[field_name] = spec
+            self._apply_spec_now(field_name, spec)
+
+    def _apply_spec_now(self, field_name: str, spec: LocalizedSpec) -> None:
+        """Resolve a localization spec using the current locale and apply immediately.
+
+        Args:
+            field_name: The widget field name to update.
+            spec: The LocalizedSpec to resolve and apply.
+        """
+        if not spec.enabled:
+            return
+        value = apply_spec(spec)
+        self._apply_localized_value(field_name, value)
+
+    def _on_locale_changed(self, event: tkinter.Event | None = None) -> None:
+        """Handle locale change events by refreshing all localized fields.
+
+        Args:
+            event: The Tkinter event object (unused).
+        """
+        self._refresh_localized_fields()
+
+        # If we have signal formatting, trigger a re-format with new locale
+        if hasattr(self, '_signal_formatter'):
+            value_format, formatter, source_signal = self._signal_formatter
+            # Re-format current value from source signal with new locale
+            formatter(source_signal())
+
+    def _refresh_localized_fields(self) -> None:
+        """Refresh all registered localized fields with the current locale."""
+        for field_name, spec in self._localized_fields.items():
+            if not spec.enabled:
+                continue
+            value = apply_spec(spec)
+            self._apply_localized_value(field_name, value)
+
+    def _setup_signal_formatting(self, value_format: str) -> None:
+        """Subscribe to textsignal and format its values.
+
+        When formatting is enabled, this creates a private textvariable for this widget
+        and subscribes to the source signal to format and display values independently.
+
+        Args:
+            value_format: The format spec (e.g., 'currency', 'decimal').
+        """
+        # Ensure textsignal exists (triggers lazy creation if needed)
+        if not hasattr(self, '_textsignal'):
+            _ = self.textsignal
+
+        # Save reference to the source signal (the one we're subscribing to)
+        source_signal = self._textsignal
+
+        # Create formatted signal using core capability
+        formatted_signal, formatter = create_formatted_signal(source_signal, value_format)
+
+        # Update our internal references to use the new private signal/variable
+        self._textsignal = formatted_signal
+        self._textvariable = formatted_signal.var
+
+        # Configure widget to use the new private variable
+        try:
+            self._ttk_base.configure(self, textvariable=self._textvariable)  # type: ignore[misc]
+        except Exception:
+            pass
+
+        # Store references for locale changes
+        self._signal_formatter = (value_format, formatter, source_signal)
+
+    def _apply_localized_value(self, field_name: str, value: str) -> None:
+        """Apply a localized value to the widget field.
+
+        Checks for associated textvariable/variable first to ensure proper
+        integration with textsignal/signal reactive bindings. Falls back to
+        direct widget configuration if no variable is found.
+
+        Args:
+            field_name: The widget field name to update.
+            value: The localized value to apply.
+        """
+        # Check if field has a direct attribute (less common)
+        var = getattr(self, field_name, None)
+        if isinstance(var, StringVar):
+            var.set(value)
+            return
+
+        # Check for textvariable (for 'text' field)
+        if field_name == 'text':
+            # Try cached _textvariable first
+            if hasattr(self, '_textvariable') and self._textvariable:
+                self._textvariable.set(value)
+                return
+
+            # Try to get textvariable from widget configuration
+            try:
+                textvariable_name = self.cget('textvariable')
+                if textvariable_name:
+                    # Get the actual variable object via the property
+                    self.textvariable.set(value)
+                    return
+            except Exception:
+                pass
+
+        # Check for variable (for 'value' or other fields)
+        if hasattr(self, '_variable') and self._variable and field_name != 'text':
+            self._variable.set(value)
+            return
+
+        # Fallback: configure the widget option directly
+        try:
+            self.configure({field_name: value})
+        except Exception:
+            pass
+
+
+__all__ = ["LocalizationMixin"]