bootstack 0.1.0__py3-none-any.whl

bootstack/style/builders/utils.py

@@ -0,0 +1,455 @@
+"""Utility functions for style builders.
+
+This module provides common utilities used across builder functions,
+including accent extraction, variant parsing, and style name manipulation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Optional
+
+from bootstack.style.element import Element
+
+if TYPE_CHECKING:
+    from bootstack.style.style_builder_ttk import StyleBuilderTtk
+
+# Standard bootstack color tokens
+COLORS = {
+    'primary', 'success', 'warning', 'danger', 'blue'
+}
+
+
+def extract_accent_from_style(ttk_style: str, default: str = 'primary') -> str:
+    """Extract accent token from TTK style name.
+
+    Args:
+        ttk_style: Full TTK style name (e.g., "custom_abc.success.Outline.TButton")
+        default: Default accent if none found
+
+    Returns:
+        Accent token name (e.g., "success")
+
+    Examples:
+        >>> extract_accent_from_style("success.Outline.TButton")
+        'success'
+        >>> extract_accent_from_style("custom_abc.danger.TLabel")
+        'danger'
+        >>> extract_accent_from_style("TButton")
+        'primary'
+    """
+    # Remove custom prefix if present
+    parts = ttk_style.split('.')
+    if parts and parts[0].startswith('custom_'):
+        parts = parts[1:]
+
+    # Find accent in parts
+    for part in parts:
+        if part.lower() in COLORS:
+            return part.lower()
+
+    return default
+
+
+def extract_variant_from_style(ttk_style: str) -> Optional[str]:
+    """Extract variant name from TTK style name.
+
+    Args:
+        ttk_style: Full TTK style name (e.g., "success.Outline.TButton")
+
+    Returns:
+        Variant name (lowercase) or None
+
+    Examples:
+        >>> extract_variant_from_style("success.Outline.TButton")
+        'outline'
+        >>> extract_variant_from_style("primary.TLabel") is None
+        True
+    """
+    parts = ttk_style.split('.')
+
+    # Remove custom prefix if present
+    if parts and parts[0].startswith('custom_'):
+        parts = parts[1:]
+
+    # Find variant (not accent, not widget class)
+    for part in parts:
+        part_lower = part.lower()
+        if part_lower not in COLORS and not part.startswith('T'):
+            return part_lower
+
+    return None
+
+
+def extract_widget_class_from_style(ttk_style: str) -> Optional[str]:
+    """Extract widget class from TTK style name.
+
+    Args:
+        ttk_style: Full TTK style name (e.g., "success.Outline.TButton")
+
+    Returns:
+        Widget class name or None
+
+    Examples:
+        >>> extract_widget_class_from_style("success.Outline.TButton")
+        'TButton'
+        >>> extract_widget_class_from_style("primary.TLabel")
+        'TLabel'
+    """
+    parts = ttk_style.split('.')
+
+    # Find widget class (starts with 'T')
+    for part in parts:
+        if part.startswith('T'):
+            return part
+
+    return None
+
+
+def parse_style_components(ttk_style: str) -> dict:
+    """Parse TTK style name into all components.
+
+    Args:
+        ttk_style: Full TTK style name
+
+    Returns:
+        Dictionary with parsed components:
+        {
+            'custom_prefix': 'custom_abc123' or None,
+            'accent': 'success' or default,
+            'variant': 'outline' or None,
+            'widget_class': 'TButton'
+        }
+
+    Examples:
+        >>> parse_style_components("custom_abc.success.Outline.TButton")
+        {'custom_prefix': 'custom_abc', 'accent': 'success', 'variant': 'outline', 'widget_class': 'TButton'}
+        >>> parse_style_components("danger.TLabel")
+        {'custom_prefix': None, 'accent': 'danger', 'variant': None, 'widget_class': 'TLabel'}
+    """
+    parts = ttk_style.split('.')
+
+    # Check for custom prefix
+    custom_prefix = None
+    if parts and parts[0].startswith('custom_'):
+        custom_prefix = parts[0]
+
+    return {
+        'custom_prefix': custom_prefix,
+        'accent': extract_accent_from_style(ttk_style),
+        'variant': extract_variant_from_style(ttk_style),
+        'widget_class': extract_widget_class_from_style(ttk_style),
+    }
+
+
+# Button utilities
+# These utilities are used by button style builders and can be reused by other widgets.
+
+# Valid button densities: 'default' (normal) and 'compact' (smaller/tighter)
+BUTTON_DENSITIES = {'default', 'compact'}
+
+
+def normalize_button_density(density: str) -> str:
+    """Normalize button density to valid values ('default' or 'compact').
+
+    Args:
+        density: The requested button density.
+
+    Returns:
+        'compact' for compact buttons, 'default' for all other densities.
+    """
+    return 'compact' if density == 'compact' else 'default'
+
+
+def button_layout(ttk_style: str) -> Element:
+    """Create the standard button element layout.
+
+    Args:
+        ttk_style: The TTK style name prefix for the button.
+
+    Returns:
+        Element tree representing the button layout.
+    """
+    return Element(f"{ttk_style}.Button.border", sticky="nsew").children(
+        [
+            Element("Button.padding", sticky="nsew").children(
+                [
+                    Element("Button.label", sticky="nsew")
+                ])
+        ])
+
+
+def toolbutton_layout(ttk_style: str) -> Element:
+    """Create the standard toolbutton element layout.
+
+    Args:
+        ttk_style: The TTK style name prefix for the toolbutton.
+
+    Returns:
+        Element tree representing the toolbutton layout.
+    """
+    return Element(f"{ttk_style}.border", sticky="nsew").children(
+        [
+            Element("Toolbutton.padding", sticky="nsew").children(
+                [
+                    Element("Toolbutton.label", sticky="nsew")
+                ])
+        ])
+
+
+def icon_size(icon_only: bool, density: str) -> int:
+    """Determine icon size based on button density and icon_only flag.
+
+    Args:
+        icon_only: Whether the button displays only an icon (no text).
+        density: The button density ('default' or 'compact').
+
+    Returns:
+        The icon size in pixels.
+    """
+    from tkinter import font
+
+    if icon_only:
+        return 20 if density != 'compact' else 17
+
+    # Size the icon to the label's cap height (font ascent) for alignment.
+    # Different buffers compensate for y_bias effect per density.
+    font_name = 'caption' if density == 'compact' else 'body'
+    f = font.nametofont(font_name)
+    buffer = 4 if density == 'compact' else 3
+    ascent = f.metrics()['ascent'] + buffer
+
+    # The ascent is already in physical pixels (named Tk fonts render at the
+    # current scaling), but this value is handed to normalize_icon_spec, which
+    # re-applies DPI scaling. Return the logical size (divide the scaling back
+    # out) so the icon is scaled exactly once and tracks the cap height at any
+    # DPI, instead of double-scaling to ~ui_scale x too large (#305).
+    from bootstack._runtime.utility import _ScalingState
+    ui_scale = _ScalingState.get_ui_scale() or 1.0
+    return round(ascent / ui_scale)
+
+
+def button_font(density: str) -> str:
+    """Get the font token for a button based on its density.
+
+    Args:
+        density: The button density ('default' or 'compact').
+
+    Returns:
+        The font token name.
+    """
+    return 'caption' if density == 'compact' else 'body'
+
+
+def button_height(b: StyleBuilderTtk, density: str) -> int:
+    """Get button height based on density, matching the total height of input fields.
+
+    Args:
+        b: The style builder instance.
+        density: The button density ('default' or 'compact').
+
+    Returns:
+        Scaled height in pixels.
+    """
+    return b.scale(37) if density == 'compact' else b.scale(43)
+
+
+def button_padding(b: StyleBuilderTtk, icon_only: bool, density: Any) -> int | tuple[int, ...]:
+    """Calculate button padding based on options.
+
+    Args:
+        b: The style builder instance.
+        icon_only: Whether the button displays only an icon.
+        density: The button density ('default' or 'compact').
+
+    Returns:
+        Padding value (0 for icon_only, scaled tuple otherwise).
+    """
+    if icon_only:
+        return b.scale((2, 3, 2, 3)) if density == 'compact' else 0
+    if density == 'compact':
+        # (left, top, right, bottom) - extra top padding to center text
+        return b.scale((6, 5, 6, 3))
+    return b.scale((8, 0))
+
+
+def resolve_icon_spec(options: dict) -> 'str | dict | None':
+    """Resolve on_icon/off_icon/icon kwargs into a unified icon spec.
+
+    Handles the three icon kwargs accepted by toggle-style widgets:
+    - icon: base icon for all states (color changes with state)
+    - off_icon: icon for the unselected/off state
+    - on_icon: icon for the selected/on state
+
+    Returns an IconSpec dict (or plain name string) suitable for passing
+    to normalize_icon_spec, or None if no icon was provided.
+    """
+    on_icon = options.get('on_icon')
+    off_icon = options.get('off_icon')
+    icon = options.get('icon')
+
+    if not on_icon and not off_icon:
+        return icon  # None, str, or full IconSpec dict
+
+    base = off_icon or icon or on_icon
+    spec: dict = {'name': base}
+    if on_icon:
+        spec['state'] = [('selected', on_icon)]
+    return spec
+
+
+def apply_icon_mapping(
+        b: StyleBuilderTtk,
+        options: dict,
+        state_spec: dict,
+        default_size: int | None = None
+) -> dict:
+    """Apply icon mapping to a state specification dictionary.
+
+    Args:
+        b: The style builder instance.
+        options: Style options dictionary containing 'icon', 'on_icon', 'off_icon',
+            and 'icon_only' keys.
+        state_spec: The state specification dictionary to update.
+        default_size: Default icon size, or None to use normalize_icon_spec defaults.
+
+    Returns:
+        Updated state_spec with icon mappings applied.
+    """
+    icon = resolve_icon_spec(options)
+    if icon is None:
+        return state_spec
+
+    if default_size is None:
+        icon = b.normalize_icon_spec(icon)
+    else:
+        icon = b.normalize_icon_spec(icon, default_size)
+
+    state_spec['image'] = b.map_stateful_icons(icon, state_spec['foreground'])
+    # Set compound to 'left' so text is visible alongside the icon
+    icon_only = options.get('icon_only', False)
+    if not icon_only:
+        state_spec['compound'] = 'left'
+    return state_spec
+
+
+# Entry/Field utilities
+# These utilities are used by entry-type style builders (Entry, Combobox, Spinbox, Field).
+
+def entry_font(density: str) -> str:
+    """Get the font for an entry widget based on its density.
+
+    Args:
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        The Tk font name.
+    """
+    from bootstack.style.typography import get_font
+    font_token = 'caption' if density == 'compact' else 'body'
+    return str(get_font(font_token))
+
+
+def entry_padding(b: StyleBuilderTtk, density: str) -> tuple:
+    """Get entry padding based on density.
+
+    Args:
+        b: The style builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled padding tuple (horizontal, vertical).
+    """
+    if density == 'compact':
+        return b.scale((6, 0))
+    return b.scale((6, 0))
+
+def field_height(b: StyleBuilderTtk, density: str) -> int:
+    """Get entry element height based on density.
+
+    Args:
+        b: The style builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled height in pixels.
+    """
+    return b.scale(26) if density == 'compact' else b.scale(33)
+
+def entry_height(b: StyleBuilderTtk, density: str) -> int:
+    """Get entry element height based on density.
+
+    Args:
+        b: The style builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled height in pixels.
+    """
+    return b.scale(25) if density == 'compact' else b.scale(31)
+
+
+def _snap_even(v: int) -> int:
+    return v if v % 2 == 0 else v + 1
+
+
+def entry_icon_size(b: StyleBuilderTtk, density: str) -> int:
+    """Get icon size for entry widgets (chevrons, spinner arrows).
+
+    Args:
+        b: The style builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled icon size in pixels, snapped to an even number.
+    """
+    return _snap_even(b.scale(12) if density == 'compact' else b.scale(14))
+
+
+def entry_image_key(base: str, density: str) -> str:
+    """Get density-aware manifest key for entry elements.
+
+    Args:
+        base: Base key name (e.g., 'input', 'input_before', 'input_after').
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Full manifest key with density suffix (e.g., 'input_default', 'input_compact').
+    """
+    return f'{base}_{density}'
+
+
+def spinner_arrow_height(b: StyleBuilderTtk, density: str) -> int:
+    """Get height for spinner arrow elements based on density.
+
+    Args:
+        b: The style builder instance.
+        density: The entry density ('default' or 'compact').
+
+    Returns:
+        Scaled arrow height in pixels, snapped to an even number.
+    """
+    return _snap_even(b.scale(10) if density == 'compact' else b.scale(13))
+
+
+def spinner_arrow_width(b: StyleBuilderTtk) -> int:
+    """Get width for spinner arrow elements.
+
+    Args:
+        b: The style builder instance.
+
+    Returns:
+        Scaled arrow width in pixels, snapped to an even number.
+    """
+    return _snap_even(b.scale(16))
+
+
+def chevron_width(b: StyleBuilderTtk) -> int:
+    """Get width for combobox chevron element.
+
+    Args:
+        b: The style builder instance.
+
+    Returns:
+        Scaled chevron width in pixels, snapped to an even number.
+    """
+    return _snap_even(b.scale(16))

bootstack/style/builders_tk/__init__.py

@@ -0,0 +1,16 @@
+"""Tk (legacy tkinter) widget builders for bootstack.
+
+Importing this package registers default builder functions for common Tk
+widgets using the StyleBuilderTk registry. Builders receive the actual
+widget instance, plus theme/color utilities via the builder object.
+"""
+
+from __future__ import annotations
+
+# Import defaults to trigger registration
+from . import defaults  # noqa: F401
+
+__all__ = [
+    'defaults',
+]
+

bootstack/style/builders_tk/defaults.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+from typing_extensions import Any
+
+from bootstack.style.style_builder_tk import StyleBuilderTk
+
+
+@StyleBuilderTk.register_builder('Tk')
+def build_tk_root(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color(options.get('surface', 'content'))
+    widget.configure(background=bg)
+    widget.option_add('*Text*Font', 'TkDefaultFont')
+
+
+@StyleBuilderTk.register_builder('Toplevel')
+def build_tk_toplevel(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color(options.get('surface', 'content'))
+    widget.configure(background=bg)
+
+
+@StyleBuilderTk.register_builder('Frame')
+def build_tk_frame(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color(options.get('surface', 'content'))
+    widget.configure(background=bg)
+
+
+@StyleBuilderTk.register_builder('Label')
+def build_tk_label(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color(options.get('surface', 'content'))
+    fg = builder.on_color(bg)
+    widget.configure(background=bg, foreground=fg)
+
+
+@StyleBuilderTk.register_builder('Button')
+def build_tk_button(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color('primary')
+    fg = builder.on_color(bg)
+    widget.configure(
+        relief='flat',
+        background=bg,
+        activebackground=bg,
+        foreground=fg,
+        activeforeground=fg,
+        highlightbackground=bg,
+    )
+
+
+@StyleBuilderTk.register_builder('Entry')
+def build_tk_entry(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color('background')
+    fg = builder.colors.get('foreground')
+    accent = builder.color('primary')
+    border = builder.border(bg)
+    widget.configure(
+        relief='flat',
+        highlightthickness=1,
+        highlightbackground=border,
+        highlightcolor=accent,
+        foreground=fg,
+        background=bg,
+        insertbackground=accent,
+        insertwidth=1
+    )
+
+
+@StyleBuilderTk.register_builder('Text')
+def build_tk_text(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color('background')
+    fg = builder.colors.get('foreground')
+    border = builder.border(bg)
+    accent = builder.color('primary')
+    accent_fg = builder.on_color(accent)
+    widget.configure(
+        background=bg,
+        foreground=fg,
+        highlightcolor=accent,
+        highlightbackground=border,
+        highlightthickness=0,
+        insertbackground=fg,
+        selectbackground=accent,
+        selectforeground=accent_fg,
+        insertwidth=1,
+        relief='flat',
+        padx=5,
+        pady=5
+    )
+
+
+@StyleBuilderTk.register_builder('Canvas')
+def build_tk_canvas(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color(options.get('surface', 'content'))
+    widget.configure(background=bg, highlightthickness=0)
+
+
+@StyleBuilderTk.register_builder('Checkbutton')
+def build_tk_checkbutton(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color(options.get('surface', 'content'))
+    fg = builder.colors.get('foreground')
+    accent = builder.color('primary')
+    widget.configure(
+        activebackground=bg,
+        activeforeground=accent,
+        background=bg,
+        foreground=fg,
+        selectcolor=bg
+    )
+
+
+@StyleBuilderTk.register_builder('Radiobutton')
+def build_tk_radiobutton(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    accent = builder.color('primary')
+    bg = builder.color(options.get('surface', 'content'))
+    fg = builder.colors.get('foreground')
+    widget.configure(
+        background=bg,
+        foreground=fg,
+        activebackground=bg,
+        activeforeground=accent,
+        highlightbackground=bg,
+        selectcolor=bg
+    )
+
+
+@StyleBuilderTk.register_builder('Scale')
+def build_tk_scale(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    accent = builder.color('primary')
+    hover = builder.active(accent)
+    border = builder.color('border')
+    widget.configure(
+        background=accent,
+        showvalue=False,
+        sliderrelief='flat',
+        borderwidth=0,
+        activebackground=hover,
+        highlightthickness=1,
+        highlightcolor=border,
+        highlightbackground=border,
+        troughcolor=border
+    )
+
+
+@StyleBuilderTk.register_builder('Listbox')
+def build_tk_listbox(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color('background')
+    fg = builder.color('foreground')
+    accent = builder.subtle('primary', bg)
+    on_accent = builder.on_color(accent)
+    border = builder.border(bg)
+    widget.configure(
+        foreground=fg,
+        background=bg,
+        selectbackground=accent,
+        selectforeground=on_accent,
+        highlightbackground=border,
+        highlightcolor=accent,
+        highlightthickness=1,
+        activestyle="none",
+        relief='flat'
+    )
+
+
+@StyleBuilderTk.register_builder('Menu')
+def build_tk_menu(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color('background')
+    fg = builder.color('foreground')
+    accent = builder.elevate(bg, 2)
+    on_accent = builder.on_color(accent)
+
+    widget.configure(
+        tearoff=False,
+        borderwidth=1,
+        foreground=fg,
+        activeforeground=on_accent,
+        selectcolor=fg,
+        activebackground=accent,
+        background=bg,
+    )
+
+
+@StyleBuilderTk.register_builder('Menubutton')
+def build_tk_menubutton(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color('primary')
+    fg = builder.on_color(bg)
+    hover = builder.active(bg)
+
+    widget.configure(
+        background=bg,
+        foreground=fg,
+        activebackground=hover,
+        activeforeground=fg,
+        borderwidth=0
+    )
+
+
+@StyleBuilderTk.register_builder('Labelframe')
+def build_tk_labelframe(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color(options.get('surface', 'content'))
+    fg = builder.on_color(bg)
+    border = builder.border(bg)
+    widget.configure(
+        background=bg,
+        foreground=fg,  # does not work on Aqua or Windows
+        borderwidth=1,
+        highlightthickness=0,
+        highlightcolor=border,
+    )
+
+
+@StyleBuilderTk.register_builder('Spinbox')
+def build_tk_spinbox(builder: StyleBuilderTk, widget: Any, **options: Any) -> None:
+    bg = builder.color('background')
+    fg = builder.color('foreground')
+    border = builder.border(bg)
+    accent = builder.subtle('primary', bg)
+    insert_background = builder.color('primary')
+
+    widget.configure(
+        relief='flat',
+        foreground=fg,
+        background=bg,
+        insertbackground=insert_background,
+        insertwidth=1,
+        highlightcolor=accent,
+        highlightthickness=1,
+        highlightbackground=border,
+        # button relief ignored by Windows and macOS
+        buttonuprelief='flat',
+        buttondownrelief='flat',
+    )