bootstack 0.1.0a1__py3-none-any.whl

bootstack/style/utility.py

@@ -0,0 +1,696 @@
+from colorsys import hls_to_rgb, rgb_to_hls
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Tuple, Union, cast
+
+from PIL import Image, ImageChops, ImageColor, ImageOps, ImageDraw
+from PIL.ImageTk import PhotoImage
+
+from bootstack.core.images import Image as ImageService
+from bootstack.runtime.utility import clamp
+from bootstack.style.types import ColorModel
+
+ASSETS_DIR = Path(__file__).parent.parent / "assets" / "widgets"
+ELEMENTS_DIR = Path(__file__).parent.parent / "assets" / "elements"
+
+
+@dataclass
+class ElementMeta:
+    """Scaled metadata for an element image.
+
+    All values are scaled for the current display DPI.
+    """
+    width: int
+    height: int
+    border: Union[int, Tuple[int, ...]]
+    padding: Union[int, Tuple[int, ...]]
+
+    def border_spec(self) -> Union[int, Tuple[int, ...]]:
+        """Return border in a format suitable for ttk element_create."""
+        return self.border
+
+    def padding_spec(self) -> Union[int, Tuple[int, ...]]:
+        """Return padding in a format suitable for ttk element_create."""
+        return self.padding
+
+
+@dataclass
+class ElementImageResult:
+    """Result of recolor_element_image containing the image and its metadata."""
+    image: PhotoImage
+    meta: ElementMeta
+
+
+# Cached manifest data
+_manifest_cache: dict | None = None
+
+
+def _load_manifest() -> dict:
+    """Load and cache the element manifest."""
+    global _manifest_cache
+    if _manifest_cache is not None:
+        return _manifest_cache
+
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[import-not-found]
+
+    manifest_path = ELEMENTS_DIR / "manifest.toml"
+    with open(manifest_path, "rb") as f:
+        _manifest_cache = tomllib.load(f)
+
+    return _manifest_cache
+
+
+def _get_element_info(key: str) -> dict | None:
+    """Get element info from manifest by key.
+
+    Args:
+        key: The element key (e.g., 'button_md', 'checkbox_checked')
+
+    Returns:
+        Dict with file, width, height, border, padding or None if not found.
+    """
+    manifest = _load_manifest()
+    images = manifest.get("images", {})
+    return images.get(key)
+
+HUE = 360
+SAT = 100
+LUM = 100
+
+
+def create_box_image(width: int, height: int, color: str):
+    cache_key = f"{width}{height}{color}"
+    cached = ImageService.get_cached(cache_key)
+    if cached is not None:
+        return cached
+
+    img = Image.new("RGBA", (width, height), color)
+    pm = PhotoImage(image=img)
+
+    ImageService.set_cached(cache_key, pm)
+    return pm
+
+
+def create_rounded_border_image(*,
+        size=200,
+        radius=4,
+        thickness=2,
+        fill='#ffffff',
+        stroke='#000000'
+):
+    cache_key = f"{size}{radius}{thickness}{fill}{stroke}"
+    cached = ImageService.get_cached(cache_key)
+    if cached is not None:
+        return cached
+
+    scale = 2  # light supersample for corner smoothing
+
+    s = size * scale
+    r = radius * scale
+    t = thickness * scale
+
+    img = Image.new("RGBA", (s, s), (0, 0, 0, 0))
+    d = ImageDraw.Draw(img)
+
+    # Two-rectangle approach for precise bounds control:
+    # 1. Outer rounded rect (stroke color) - fills to edges
+    # 2. Inner rounded rect (fill color) - inset by stroke thickness
+    outer_radius = r + t
+    d.rounded_rectangle(
+        (0, 0, s - 1, s - 1),
+        radius=outer_radius,
+        fill=stroke,
+    )
+
+    # Inner rect inset by stroke thickness
+    d.rounded_rectangle(
+        (t, t, s - 1 - t, s - 1 - t),
+        radius=r,
+        fill=fill,
+    )
+
+    # Resize with LANCZOS for smooth corners, then sharpen to restore edge crispness
+    from PIL import ImageFilter
+    img = img.resize((size, size), Image.Resampling.LANCZOS)
+    img = img.filter(ImageFilter.UnsharpMask(radius=0.5, percent=150, threshold=0))
+
+    pm = PhotoImage(image=img)
+    ImageService.set_cached(cache_key, pm)
+    return pm
+
+
+def create_transparent_image(width: int, height: int):
+    """Create a transparent image."""
+    cache_key = f"transparent_{width}x{height}"
+    cached = ImageService.get_cached(cache_key)
+    if cached is not None:
+        return cached
+
+    img = Image.new('RGBA', (width, height), (255, 255, 255, 0))
+    pm = PhotoImage(image=img)
+    ImageService.set_cached(cache_key, pm)
+    return pm
+
+
+def color_to_rgb(color, model: ColorModel = 'hex'):
+    """Convert color value to rgb.
+
+    The color and model parameters represent the color to be converted.
+    The value is expected to be a string for "name" and "hex" models and
+    a Tuple or List for "rgb" and "hsl" models.
+
+    **Parameters**
+
+    - `color` (Any): The color values for the model being converted.
+    - `model` (Literal['rbg', 'hsl', 'hex']): The color model being converted.
+
+    **Returns**
+
+    `Tuple[int, int, int]` — The rgb color values.
+    """
+    conformed = conform_color_model(color, model)
+    return ImageColor.getrgb(conformed)
+
+
+def color_to_hex(color, model: ColorModel = 'rgb'):
+    """Convert color value to hex.
+
+    The color and model parameters represent the color to be converted.
+    The value is expected to be a string for "name" and "hex" models and
+    a Tuple or List for "rgb" and "hsl" models.
+
+    **Parameters**
+
+    - `color` (Any): The color values for the model being converted.
+    - `model` (Literal['rgb', 'hsl', 'hex']): The color model being converted.
+
+    **Returns**
+
+    `str` — The hexadecimal color value.
+    """
+    r, g, b = color_to_rgb(color, model)
+    return f'#{r:02x}{g:02x}{b:02x}'
+
+
+def color_to_hsl(color, model: ColorModel = 'hex'):
+    """Convert color value to hsl.
+
+    The color and model parameters represent the color to be converted.
+    The value is expected to be a string for "name" and "hex" models and
+    a Tuple or List for "rgb" and "hsl" models.
+
+    **Parameters**
+
+    - `color` (Any): The color values for the model being converted.
+    - `model` (Literal['rgb', 'hsl', 'hex']): The color model being converted.
+
+    **Returns**
+
+    `Tuple[int, int, int]` — The hsl color values.
+    """
+    r, g, b = color_to_rgb(color, model)
+    hls = rgb_to_hls(r / 255, g / 255, b / 255)
+    hue = int(clamp(hls[0] * HUE, 0, HUE))
+    lum = int(clamp(hls[1] * LUM, 0, LUM))
+    sat = int(clamp(hls[2] * SAT, 0, SAT))
+    return hue, sat, lum
+
+
+def update_hsl_value(
+        color, hue=None, sat=None, lum=None,
+        in_model: ColorModel = 'hsl',
+        out_model: ColorModel = 'hsl'):
+    """Change hue, saturation, or luminosity of the color based on the hue,
+    sat, lum parameters provided.
+
+    **Parameters**
+
+    - `color` (Any): The color.
+    - `hue` (int, optional): A number between 0 and 360.
+    - `sat` (int, optional): A number between 0 and 100.
+    - `lum` (int, optional): A number between 0 and 100.
+    - `in_model` (Literal['rgb', 'hsl', 'hex']): The color model of the input color.
+    - `out_model` (Literal['rgb', 'hsl', 'hex']): The color model of the output color.
+
+    **Returns**
+
+    `Tuple[int, int, int]` — The color value based on the selected color model.
+    """
+    h, s, l = color_to_hsl(color, in_model)
+    if hue is not None:
+        h = hue
+    if sat is not None:
+        s = sat
+    if lum is not None:
+        l = lum
+    if out_model == 'rgb':
+        return color_to_rgb([h, s, l], 'hsl')
+    elif out_model == 'hex':
+        return color_to_hex([h, s, l], 'hsl')
+    else:
+        return h, s, l
+
+
+def contrast_color(
+        color, model: ColorModel, dark_color='#000',
+        light_color='#fff'):
+    """The best matching contrasting light or dark color for the given color.
+    https://stackoverflow.com/questions/1855884/determine-font-color-based-on-background-color
+
+    **Parameters**
+
+    - `color` (str): The color value to evaluate.
+    - `model` (Literal['rgb', 'hsl', 'hex']): The model of the color value to be evaluated. 'rgb' by default.
+    - `dark_color` (str): The color of the dark contrasting color.
+    - `light_color` (str): The color of the light contrasting color.
+
+    **Returns**
+
+    `str` — The matching color value.
+    """
+    if model != 'rgb':
+        r, g, b = color_to_rgb(color, model)
+    else:
+        r, g, b = color
+
+    luminance = ((0.299 * r) + (0.587 * g) + (0.114 * b)) / 255
+    if luminance > 0.5:
+        return dark_color
+    else:
+        return light_color
+
+
+def conform_color_model(color, model: ColorModel):
+    """Conform the color values to a string that can be interpreted by the
+    `PIL.ImageColor.getrgb method`.
+
+    **Parameters**
+
+    - `color` (Any): The color value to conform.
+    - `model` (Literal['rgb', 'hsl', 'hex']): The model of the color to evaluate (rgb, hex, hsl).
+
+    **Returns**
+
+    `str` — A color value string that can be used as a parameter in the PIL.ImageColor.getrgb method.
+    """
+    if model == 'hsl':
+        hue = clamp(color[0], 0, HUE)
+        sat = clamp(color[1], 0, SAT)
+        lum = clamp(color[2], 0, LUM)
+        return f'hsl({hue},{sat}%,{lum}%)'
+    elif model == 'rgb':
+        red = clamp(color[0], 0, 255)
+        grn = clamp(color[1], 0, 255)
+        blu = clamp(color[2], 0, 255)
+        return f'rgb({red},{grn},{blu})'
+    else:
+        return color
+
+
+def make_transparent(alpha, foreground, background='#fff'):
+    """Simulate color transparency.
+
+    **Parameters**
+
+    - `alpha` (float): The amount of transparency between 0.0 and 1.0.
+    - `foreground` (str): The foreground color.
+    - `background` (str): The background color.
+
+    **Returns**
+
+    `str` — A hexadecimal color representing the "transparent" version of the foreground color against the background color.
+    """
+    fg = ImageColor.getrgb(foreground)
+    bg = ImageColor.getrgb(background)
+    rgb_float = [alpha * c1 + (1 - alpha) * c2 for (c1, c2) in zip(fg, bg)]
+    rgb_int = [int(x) for x in rgb_float]
+    return '#{:02x}{:02x}{:02x}'.format(*rgb_int)
+
+
+def open_image(name: str) -> Image.Image:
+    """
+    Load a white-layout image from file.
+
+    Args:
+        name: The asset name without extension (e.g. "add" loads "add.png")
+
+    Returns:
+        A Pillow RGBA Image object.
+    """
+    path = ASSETS_DIR / f"{name}.png"
+    return Image.open(path).convert("RGBA")
+
+
+def _open_element_image(filename: str) -> Image.Image:
+    """Load an element image from the elements directory.
+
+    Args:
+        filename: The filename (e.g., "button-lg.png")
+
+    Returns:
+        A Pillow RGBA Image object.
+    """
+    path = ELEMENTS_DIR / filename
+    return Image.open(path).convert("RGBA")
+
+
+def _scale_border_or_padding(
+    value: int | list | tuple,
+    scale: float
+) -> int | tuple[int, ...]:
+    """Scale border or padding values.
+
+    Args:
+        value: Integer or sequence of integers from manifest
+        scale: Scale factor to apply
+
+    Returns:
+        Scaled value(s) as int or tuple
+    """
+    if isinstance(value, int):
+        return max(1, int(value * scale + 0.5)) if value > 0 else 0
+    elif isinstance(value, (list, tuple)):
+        scaled = tuple(
+            max(1, int(v * scale + 0.5)) if v > 0 else 0
+            for v in value
+        )
+        return scaled
+    return value
+
+
+def recolor_element_image(
+    key: str,
+    white_color: str,
+    black_color: str = "#ffffff",
+    magenta_color: str | None = None,
+    transparent_color: str | None = None,
+) -> ElementImageResult:
+    """Recolor an element image from the manifest and return scaled image with metadata.
+
+    This function fetches an image by key from the elements manifest, applies
+    luminance-based recoloring, and returns both the scaled image and scaled
+    metadata (border, padding, dimensions) for use with ttk element_create.
+
+    The scaling is cross-platform aware, handling the differences between
+    logical and physical pixels on macOS, Windows, and Linux:
+    - Windows: Uses system DPI scaling (96 DPI baseline, scales to 120, 144, etc.)
+    - macOS: Retina displays use 2x physical pixels per logical pixel
+    - Linux: Uses X11/Wayland DPI settings via winfo_fpixels
+
+    Source images are created at 2x resolution (default_dpi=2.0 in manifest),
+    so scaling accounts for this to produce correctly sized output.
+
+    Args:
+        key: Element key from manifest (e.g., 'button_md', 'checkbox_checked')
+        white_color: Replace white/light areas with this color (hex string)
+        black_color: Replace black/dark areas with this color (hex string)
+        magenta_color: Replace magenta (#ff00ff) with this color, if provided
+        transparent_color: Fill fully transparent areas with this color
+
+    Returns:
+        ElementImageResult containing:
+            - image: The recolored and scaled PhotoImage
+            - meta: ElementMeta with scaled width, height, border, and padding
+
+    Raises:
+        ValueError: If the key is not found in the manifest.
+
+    Example:
+        >>> result = recolor_element_image('button_md', '#3b82f6', '#1e40af')
+        >>> element = ElementImage(
+        ...     'MyButton.border',
+        ...     result.image,
+        ...     border=result.meta.border,
+        ...     padding=result.meta.padding
+        ... )
+    """
+    # Get element info from manifest
+    info = _get_element_info(key)
+    if info is None:
+        raise ValueError(
+            f"Element key '{key}' not found in manifest. "
+            f"Check that the key exists in assets/elements/manifest.toml"
+        )
+
+    # Get source resolution from manifest
+    manifest = _load_manifest()
+    source_resolution = manifest.get("default_dpi", 2.0)
+
+    # Calculate cross-platform scale factor
+    from bootstack.runtime.utility import _ScalingState
+    scale = _ScalingState.get_image_scale(source_resolution=source_resolution)
+
+    # Create cache key from all parameters
+    cache_key = (
+        "element", key, white_color, black_color,
+        magenta_color, transparent_color, scale
+    )
+
+    # Check if we've already created this exact result
+    cached = ImageService.get_cached(cache_key)
+    if cached is not None:
+        # Cached value is a tuple of (PhotoImage, ElementMeta)
+        return ElementImageResult(image=cached[0], meta=cached[1])
+
+    # Load and process the image
+    filename = info.get("file", f"{key.replace('_', '-')}.png")
+    img = _open_element_image(filename)
+    gray = ImageOps.grayscale(img)
+
+    fg_rgb = color_to_rgb(white_color)
+    bg_rgb = color_to_rgb(black_color)
+    mag_rgb = color_to_rgb(magenta_color) if magenta_color else None
+    trans_rgb = color_to_rgb(transparent_color) if transparent_color else None
+
+    # Luminance-based recoloring via per-channel LUTs applied to grayscale.
+    # Output channel value = round(bg + (fg - bg) * gray / 255). PIL applies
+    # the LUT in C, replacing the per-pixel Python loop.
+    def _channel_lut(bg_c: int, fg_c: int) -> list[int]:
+        return [round(bg_c + (fg_c - bg_c) * i / 255.0) for i in range(256)]
+
+    r_chan = gray.point(_channel_lut(bg_rgb[0], fg_rgb[0]))
+    g_chan = gray.point(_channel_lut(bg_rgb[1], fg_rgb[1]))
+    b_chan = gray.point(_channel_lut(bg_rgb[2], fg_rgb[2]))
+
+    r_src, g_src, b_src, alpha = img.split()
+    result = Image.merge("RGBA", (r_chan, g_chan, b_chan, alpha))
+
+    # Magenta passthrough: pixels whose source RGB is exactly (255, 0, 255)
+    # are replaced with mag_rgb. Build a 0/255 mask via channel LUTs and
+    # AND them with ImageChops.multiply (255 * 255 / 255 = 255).
+    if mag_rgb:
+        r_eq = r_src.point([255 if i == 255 else 0 for i in range(256)])
+        g_eq = g_src.point([255 if i == 0 else 0 for i in range(256)])
+        b_eq = b_src.point([255 if i == 255 else 0 for i in range(256)])
+        mag_mask = ImageChops.multiply(ImageChops.multiply(r_eq, g_eq), b_eq)
+        mag_solid = Image.new("RGBA", img.size, (*mag_rgb, 255))
+        composited = Image.composite(mag_solid, result, mag_mask)
+        # composite replaces alpha too; restore the original alpha.
+        nr, ng, nb, _ = composited.split()
+        result = Image.merge("RGBA", (nr, ng, nb, alpha))
+
+    # Flatten partial transparency over a solid backing color. Matches the
+    # old per-pixel `r_final = trans*(1-a) + r*a, alpha=255` exactly.
+    if trans_rgb:
+        backing = Image.new("RGBA", img.size, (*trans_rgb, 255))
+        result = Image.alpha_composite(backing, result)
+
+    # Scale the image
+    # Use rounding (+ 0.5) to ensure image size matches metadata dimensions exactly.
+    # This prevents centering issues caused by mismatched image/border calculations.
+    if scale != 1.0:
+        new_size = (
+            max(1, int(result.width * scale + 0.5)),
+            max(1, int(result.height * scale + 0.5))
+        )
+        # Use NEAREST for sharp-edge assets (avoids antialiasing at color boundaries)
+        # Use LANCZOS for smooth assets (rounded corners, gradients)
+        resample_mode = info.get("resample", "lanczos").lower()
+        if resample_mode == "nearest":
+            result = result.resize(new_size, Image.Resampling.NEAREST)
+        else:
+            result = result.resize(new_size, Image.Resampling.LANCZOS)
+
+    photo_image = PhotoImage(image=result)
+
+    # Scale the metadata
+    source_width = info.get("width", img.width)
+    source_height = info.get("height", img.height)
+    source_border = info.get("border", 0)
+    source_padding = info.get("padding", 0)
+
+    meta = ElementMeta(
+        width=max(1, int(source_width * scale + 0.5)),
+        height=max(1, int(source_height * scale + 0.5)),
+        border=_scale_border_or_padding(source_border, scale),
+        padding=_scale_border_or_padding(source_padding, scale),
+    )
+
+    # Cache the result as a tuple
+    ImageService.set_cached(cache_key, (photo_image, meta))
+
+    return ElementImageResult(image=photo_image, meta=meta)
+
+
+def should_darken(bg_hex: str) -> bool:
+    """Determine whether to darken or lighten based on luminance and saturation."""
+    r, g, b = [v / 255.0 for v in ImageColor.getrgb(bg_hex)]
+    h, l, s = rgb_to_hls(r, g, b)
+
+    # If the color is light and saturated, lighten it (like warning/info)
+    # If the color is already very light (lightness > 0.9), darken it to gain contrast
+    if l > 0.8:
+        return True  # Darken very light colors (like `light`)
+    if l < 0.3:
+        return False  # Lighten very dark colors (like `dark`)
+    if s > 0.6 and l > 0.6:
+        return False  # Lighten vibrant, light colors (e.g. warning/info)
+    return True  # Default: darken
+
+
+def darken_color(hex_color: str, percent: float) -> str:
+    """Darken a hex color by reducing lightness in HLS color space."""
+    r, g, b = [v / 255.0 for v in ImageColor.getrgb(hex_color)]
+    h, l, s = rgb_to_hls(r, g, b)
+    l = max(0.0, l * (1 - percent))
+    r, g, b = hls_to_rgb(h, l, s)
+    return f"#{int(r * 255):02x}{int(g * 255):02x}{int(b * 255):02x}"
+
+
+def lighten_color(hex_color: str, percent: float) -> str:
+    """Lighten a hex color by increasing lightness in HLS color space."""
+    r, g, b = [v / 255.0 for v in ImageColor.getrgb(hex_color)]
+    h, l, s = rgb_to_hls(r, g, b)
+    l = min(1.0, l + (1 - l) * percent)
+    r, g, b = hls_to_rgb(h, l, s)
+    return f"#{int(r * 255):02x}{int(g * 255):02x}{int(b * 255):02x}"
+
+
+def mix_colors(color1: str, color2: str, weight: float) -> str:
+    """Mix two colors by weight.
+
+    Args:
+        color1: The foreground color in hex format (e.g., '#FF0000').
+        color2: The background color in hex format.
+        weight: A float from 0 to 1, where 1 favors color1 and 0 favors color2.
+
+    Returns:
+        A hex color string representing the mixed result.
+    """
+    r1, g1, b1 = ImageColor.getrgb(color1)
+    r2, g2, b2 = ImageColor.getrgb(color2)
+
+    r = round(r1 * weight + r2 * (1 - weight))
+    g = round(g1 * weight + g2 * (1 - weight))
+    b = round(b1 * weight + b2 * (1 - weight))
+
+    return f"#{r:02X}{g:02X}{b:02X}"
+
+
+def tint_color(color: str, base_weight: float) -> str:
+    """Tint a color by mixing it with white.
+
+    Args:
+        color: The base color in hex.
+        base_weight: Amount of base color to retain (0–1).
+
+    Returns:
+        A tinted hex color string.
+    """
+    return mix_colors(color, "#ffffff", 1 - base_weight)
+
+
+def shade_color(color: str, base_weight: float) -> str:
+    """Shade a color by mixing it with black.
+
+    Args:
+        color: The base color in hex.
+        base_weight: Amount of base color to retain (0–1).
+
+    Returns:
+        A shaded hex color string.
+    """
+    return mix_colors(color, "#000000", 1 - base_weight)
+
+
+def relative_luminance(hex_color: str) -> float:
+    """Calculate the relative luminance of a color.
+
+    Args:
+        hex_color: A hex color string.
+
+    Returns:
+        The luminance value from 0 (black) to 1 (white).
+    """
+    r, g, b = [x / 255 for x in ImageColor.getrgb(hex_color)]
+
+    def adjust(c):
+        return c / 12.92 if c <= 0.03928 else ((c + 0.055) / 1.055) ** 2.4
+
+    r, g, b = adjust(r), adjust(g), adjust(b)
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b
+
+
+def contrast_ratio(rgb1: tuple[int, int, int], rgb2: tuple[int, int, int]) -> float:
+    def rel_luminance(r: int, g: int, b: int) -> float:
+        def channel(c): return (c / 255.0) ** 2.2
+
+        return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b)
+
+    lum1 = rel_luminance(*rgb1)
+    lum2 = rel_luminance(*rgb2)
+    lighter = max(lum1, lum2)
+    darker = min(lum1, lum2)
+    return (lighter + 0.05) / (darker + 0.05)
+
+
+def hex_to_rgb(value: str) -> tuple[int, int, int]:
+    """Convert a hex color string to an RGB tuple."""
+    value = value.lstrip("#")
+    lv = len(value)
+    result = tuple(int(value[i:i + lv // 3], 16) for i in range(0, lv, lv // 3))
+    return cast(tuple[int, int, int], result)
+
+
+def rgb_to_hex(rgb: tuple[int, int, int]) -> str:
+    """Convert an RGB tuple to a hex color string."""
+    return "#{:02x}{:02x}{:02x}".format(*rgb)
+
+
+def hsl_to_hex(h: float, s: float, l: float) -> str:
+    """Convert HSL values to a hex color string.
+
+    Args:
+        h: Hue in degrees (0-360)
+        s: Saturation as percentage (0-100)
+        l: Lightness as percentage (0-100)
+
+    Returns:
+        Hex color string (e.g., '#ff0000')
+    """
+    # Normalize to 0-1 range
+    h_norm = h / 360.0
+    s_norm = s / 100.0
+    l_norm = l / 100.0
+
+    # colorsys uses HLS order (not HSL)
+    r, g, b = hls_to_rgb(h_norm, l_norm, s_norm)
+
+    return rgb_to_hex((round(r * 255), round(g * 255), round(b * 255)))
+
+
+def best_foreground(bg_color: str, candidates: list[str] = None) -> str:
+    """Return the color with the highest contrast against the background."""
+    if candidates is None:
+        candidates = ["#000000", "#ffffff"]
+
+    bg_rgb = hex_to_rgb(bg_color)
+
+    def contrast(c: str) -> float:
+        fg_rgb = hex_to_rgb(c)
+        return contrast_ratio(bg_rgb, fg_rgb)
+
+    return max(candidates, key=contrast)

bootstack/themes/__init__.py

@@ -0,0 +1,12 @@
+"""Theme definitions for bootstack.
+
+This package contains theme definitions including standard built-in themes
+and user-defined custom themes.
+
+Modules:
+    standard: Built-in Bootstrap-inspired theme definitions
+    user: User-defined custom theme storage
+
+The themes are defined as dictionaries containing color schemes and type
+information (light/dark) used by the Style class to create themed widgets.
+"""