bootstack 0.1.0__py3-none-any.whl

bootstack/widgets/_impl/_parts/textentry_part.py

@@ -0,0 +1,406 @@
+from tkinter import Event, TclError
+from typing import Any, Callable
+
+from bootstack.events import ChangeEvent, InputEvent
+from bootstack.i18n import MessageCatalog, IntlFormatter
+from bootstack.widgets._impl.primitives.entry import Entry
+from bootstack.widgets._impl.mixins import ValidationMixin
+from bootstack.widgets._impl.mixins.configure_mixin import configure_delegate
+
+
+class TextEntryPart(ValidationMixin, Entry):
+    """Internationalization-aware entry widget with deferred parsing and formatting.
+
+    This widget separates user input (display text) from the committed/parsed value,
+    providing a clean pattern for handling formatted data entry. Parsing and formatting
+    only occur when the user commits the value via `<FocusOut>` or `<Return>`.
+
+    """
+
+    def __init__(
+            self,
+            master=None,
+            *,
+            value='',
+            value_format=None,
+            initial_focus: bool = False,
+            allow_blank: bool = True,
+            placeholder: str | None = None,
+            **kwargs
+    ):
+        """Initialize a TextEntryPart widget with internationalization support.
+
+        Creates an entry widget that separates display text from the parsed value.
+        The widget defers parsing and formatting until the user commits the value
+        by pressing Enter or moving focus away from the widget.
+
+        Args:
+            master: Parent widget. If None, uses the default root window.
+            value: Initial value to display and parse. Can be a string or any value
+                that can be formatted using value_format. Default is empty string.
+            value_format: ICU format pattern for parsing and formatting the value.
+                Common patterns: `'#,##0.00'` (decimal), `'¤#,##0.00'` (currency),
+                `'yyyy-MM-dd'` (date), `'#,##0.00%'` (percent).
+                If None, value is treated as plain text (no parsing/formatting).
+            initial_focus: If True, widget receives focus when created.
+            allow_blank: If True, empty input is parsed as None. If False, empty
+                input preserves the previous value.
+            placeholder: Text shown when the field is empty and unfocused.
+            **kwargs: Additional keyword arguments passed to the Entry base class.
+
+        Note:
+            The widget automatically subscribes to text changes and sets up
+            event handlers for `<FocusIn>`, `<FocusOut>`, and `<Return>`.
+        """
+        self._placeholder_text = placeholder
+        self._showing_placeholder = False
+        kwargs.setdefault('ttk_class', 'TField')
+        kwargs.setdefault('variant', 'input')
+        super().__init__(master, **kwargs)
+
+        # configuration
+        self._value_format = value_format
+        self._allow_blank = allow_blank
+        self._on_input_fid = None
+        self._fmt = IntlFormatter(locale=MessageCatalog.locale())
+
+        # set the initial display value
+        # Convert to string if it's a number
+        if isinstance(value, (int, float)):
+            initial_display = str(value)
+        else:
+            initial_display = value or self.textsignal() or ''
+
+        # Parse initial value if format is specified
+        if value_format is not None:
+            initial_value = self._parse_or_none(initial_display)
+        else:
+            initial_value = initial_display or ''
+
+        self._value = initial_value
+        self._prev_changed_value = initial_value
+
+        # normalize initial display if we already have a parsed value
+        if self._value is not None:
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+        else:
+            self.textsignal.set('')
+
+        # track last text emitted for CHANGE
+        self._prev_change_text = self.textsignal()
+
+        # subscribe to text changes
+        self._on_input_fid = self.textsignal.subscribe(self._handle_change)
+
+        # Commit on focus out / enter;
+        self.bind('<FocusIn>', self._store_prev_value, add=True)
+        self.bind('<FocusOut>', self._handle_focus_out, add=True)
+        self.bind('<Return>', self._handle_return, add=True)
+        self.winfo_toplevel().bind('<<LocaleChanged>>', self._on_locale_changed, add='+')
+
+        # set initial focus
+        if initial_focus:
+            self.focus()
+
+        # placeholder — shown when empty and unfocused; uses textvariable detach
+        # so the Signal is never set to the placeholder text
+        if placeholder:
+            self._default_fg = self.cget("foreground")
+            # remember any masking char so the placeholder can render unmasked
+            # (a password '•'/'*' mask must not turn the placeholder into bullets)
+            self._show_char = self.cget("show")
+            if not self.textsignal():
+                self._show_placeholder()
+            self.bind('<FocusIn>', self._on_focus_in_placeholder, add=True)
+            self.bind('<FocusOut>', self._on_focus_out_placeholder, add=True)
+
+    def _show_placeholder(self) -> None:
+        self._showing_placeholder = True
+        self.configure(textvariable='')
+        # render the placeholder unmasked even when an input mask is active
+        if getattr(self, '_show_char', ''):
+            self.configure(show='')
+        self.insert(0, self._placeholder_text)
+        self.configure(foreground='grey')
+
+    def _hide_placeholder(self) -> None:
+        self._showing_placeholder = False
+        self.delete(0, 'end')
+        self.configure(textvariable=self.textsignal.var)
+        # restore the input mask now that real input is shown
+        if getattr(self, '_show_char', ''):
+            self.configure(show=self._show_char)
+        self.configure(foreground=self._default_fg)
+
+    def _on_focus_in_placeholder(self, _event) -> None:
+        if self._showing_placeholder:
+            self._hide_placeholder()
+
+    def _on_focus_out_placeholder(self, _event) -> None:
+        if self._placeholder_text and not self.textsignal():
+            self._show_placeholder()
+
+    def _store_prev_value(self, _: Any):
+        """Store current value on focus-in to detect changes later."""
+        self._prev_changed_value = self._value
+
+    def _handle_focus_out(self, _):
+        """Commit value and check for changes when focus leaves the widget."""
+        if 'readonly' in self.state():
+            return
+        self.commit()
+        self._check_if_changed()
+
+    def _handle_return(self, _):
+        """Commit value and check for changes when Return key is pressed."""
+        self.commit()
+        self._check_if_changed()
+
+    def _handle_change(self, event):
+        """Emit <<Input>> event on every text change without parsing."""
+        text = self.textsignal()
+        if text == self._prev_change_text:
+            return
+        if self._showing_placeholder:
+            if text:
+                self._hide_placeholder()
+            else:
+                return
+        self._prev_change_text = text
+        self.event_generate('<<Input>>', data=InputEvent(text=text))
+
+    def _check_if_changed(self):
+        """Emit <<Change>> event if parsed value changed since focus-in."""
+        if self._value != self._prev_changed_value:
+            data = ChangeEvent(
+                value=self._value,
+                prev_value=self._prev_changed_value,
+                text=self.textsignal(),
+            )
+            self.event_generate('<<Change>>', data=data)
+            self._prev_changed_value = self._value
+
+    def _parse_or_none(self, s: str):
+        """Parse string using value_format, returning None on empty/invalid input."""
+        # If a non-string is passed (e.g., datetime/date), assume it's already parsed.
+        if not isinstance(s, str):
+            return s
+        s2 = (s or '').strip()
+        if not s2:
+            return None
+        try:
+            if self._value_format is None:
+                return s2
+            return self._fmt.parse(s2, self._value_format)
+        except ValueError:
+            return None
+
+    def _format_value(self, value: Any) -> str:
+        """Format a value for display using value_format.
+
+        Args:
+            value: The value to format (can be string, int, float, etc.)
+
+        Returns:
+            Formatted string representation of the value
+        """
+        if value is None:
+            return ''
+
+        # If no format specified, just convert to string
+        if self._value_format is None:
+            return str(value)
+
+        # IntlFormatter.format() expects numeric values, not strings
+        # So pass the value directly (it will be a number from parse())
+        try:
+            return self._fmt.format(value, self._value_format)
+        except (ValueError, TypeError):
+            # If formatting fails, return string representation
+            return str(value)
+
+    def on_input(self, callback: Callable) -> str:
+        """Bind to `<<Input>>`. Callback receives `event.data = {'text': str}`."""
+        return self.bind('<<Input>>', callback, add=True)
+
+    def off_input(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<Input>>`."""
+        self.unbind('<<Input>>', bind_id)
+
+    def on_enter(self, callback: Callable) -> str:
+        """Bind to `<Return>`. Callback receives `event.data = {'value': Any, 'text': str}`."""
+
+        def enrich_callback(event: Event) -> None:
+            data = {"value": self._value, "text": self.textsignal()}
+            event.data = data
+            return callback(event)
+
+        return self.bind('<Return>', enrich_callback, add=True)
+
+    def off_enter(self, bind_id: str | None = None) -> None:
+        """Unbind from `<Return>`."""
+        self.unbind('<Return>', bind_id)
+
+    def on_changed(self, callback: Callable) -> str:
+        """Bind to `<<Change>>`. Callback receives `event.data = {'value': Any, 'prev_value': Any, 'text': str}`."""
+        return self.bind("<<Change>>", callback, add=True)
+
+    def off_changed(self, bind_id: str | None = None) -> None:
+        """Unbind from `<<Change>>`."""
+        self.unbind('<<Change>>', bind_id)
+
+    def value(self, value=None):
+        """Get or set the parsed/committed value.
+
+        Args:
+            value: If provided, sets the display text and internal value with formatting
+
+        Returns:
+            Current parsed value if no argument provided, None otherwise
+        """
+        if value is None:
+            return self._value
+        else:
+            # Store the value and format it for display
+            if isinstance(value, (int, float)):
+                value_str = str(value)
+            else:
+                value_str = str(value) if value is not None else ''
+
+            # Parse the value if format is specified
+            if self._value_format is not None and value_str:
+                self._value = self._parse_or_none(value_str)
+            else:
+                self._value = value_str if value_str else None
+
+            # Format and display
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+            return None
+
+    def _get_validation_value(self):
+        """Return the current input parsed to its typed value, for validation.
+
+        Validation runs against the field's typed value — the string itself for
+        a text field, a `date`/`time` for a date or time field — parsed from
+        what is currently shown, not the raw display text and not the
+        last-committed value. This keeps a manual `validate()`, the automatic
+        blur/key validation, and a form-level validate in agreement on the same
+        live, typed input.
+        """
+        try:
+            return self._parse_or_none(self.get())
+        except Exception:
+            return self.get()
+
+    def text(self, value=None):
+        """Get or set the raw display text without committing.
+
+        Args:
+            value: If provided, sets the display text without parsing
+
+        Returns:
+            Current display text if no argument provided, None otherwise
+        """
+        if value is None:
+            return self.textsignal()
+        else:
+            self.textsignal.set(value)
+            return None
+
+    def commit(self):
+        """Parse display text, update value, and normalize display (called on FocusOut/Return)."""
+        if self._showing_placeholder:
+            return
+        s = self.get().strip()
+
+        # parse once
+        if s == '':
+            self._value = None if self._allow_blank else self._value
+        else:
+            try:
+                self._value = s if self._value_format is None else self._fmt.parse(s, self._value_format)
+            except ValueError:
+                # keep prior value on parse failure
+                return
+
+        # Format the value for display
+        new_text = self._format_value(self._value)
+
+        if new_text != self.textsignal():
+            # temporarily silence CHANGE while normalizing text
+            fid = getattr(self, '_on_input_fid', None)
+            if fid:
+                try:
+                    fid.cancel()
+                except TclError:
+                    pass
+            self.textsignal.set(new_text)
+            if fid:
+                self._on_input_fid = self.textsignal.subscribe(self._handle_change)
+
+    def _on_locale_changed(self, event=None):
+        """Respond to global changes in locale by updating formatter and text"""
+        self._fmt = IntlFormatter(locale=MessageCatalog.locale())
+
+        # reformat current value with new locale + same value_format
+        if self._value is not None:
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+
+    @configure_delegate('text')
+    def _delegate_text(self, value=None):
+        if value is None:
+            return self.text()
+        else:
+            return self.text(value)
+
+    @configure_delegate('value')
+    def _delegate_value(self, value=None):
+        if value is None:
+            return self.value()
+        else:
+            return self.value(value)
+
+    @configure_delegate('value_format')
+    def _delegate_value_format(self, value: str):
+        """Get or set the value format pattern and reformat display.
+
+        Can be accessed via:
+            widget.configure(value_format='#,##0.00')
+            widget['value_format'] = '#,##0.00'
+            widget.cget('value_format')
+        """
+        if value is None:
+            return self._value_format
+
+        self._value_format = value
+        # Reformat current value with new format
+        if self._value is not None:
+            formatted_text = self._format_value(self._value)
+            self.textsignal.set(formatted_text)
+
+    @configure_delegate('allow_blank')
+    def _delegate_allow_blank(self, value: bool):
+        """Get or set whether blank input is allowed.
+
+        Can be accessed via:
+            widget.configure(allow_blank=True)
+            widget['allow_blank'] = True
+            widget.cget('allow_blank')
+        """
+        if value is None:
+            return self._allow_blank
+
+        self._allow_blank = bool(value)
+
+    def destroy(self):
+        """Clean up signal subscriptions and destroy the widget."""
+        if self._on_input_fid:
+            try:
+                self._on_input_fid.cancel()
+            except Exception:
+                pass  # Ignore all errors during cleanup
+            self._on_input_fid = None
+        super().destroy()

bootstack/widgets/_impl/composites/__init__.py

@@ -0,0 +1,33 @@
+"""Composite bootstack widgets."""
+
+from bootstack.widgets._impl.composites.accordion import Accordion
+from bootstack.widgets._impl.composites.compositeframe import Composite, CompositeFrame
+from bootstack.widgets._impl.composites.expander import Expander
+from bootstack.widgets._impl.composites.list import ListItem, ListView, MemoryDataSource, DataSourceProtocol
+from bootstack.widgets._impl.composites.sidenav import (
+    SideNavHeader,
+    SideNavSeparator,
+)
+from bootstack.widgets._impl.composites.tabs import Tabs, TabView
+from bootstack.widgets._impl.composites.selectbox import SelectBox
+from bootstack.widgets._impl.composites.slider import Slider, RangeSlider
+from bootstack.widgets._impl.composites.toolbar import Toolbar
+
+__all__ = [
+    'Accordion',
+    'Composite',
+    'CompositeFrame',
+    'Expander',
+    'ListItem',
+    'ListView',
+    'MemoryDataSource',
+    'DataSourceProtocol',
+    'RangeSlider',
+    'SideNavHeader',
+    'SideNavSeparator',
+    'Slider',
+    'Tabs',
+    'TabView',
+    'SelectBox',
+    'Toolbar',
+]

bootstack/widgets/_impl/composites/_dateutils.py

@@ -0,0 +1,33 @@
+"""Shared date helpers for the date-picker composites."""
+from __future__ import annotations
+
+from datetime import date, datetime
+
+
+def coerce_date(value: date | datetime | str | None) -> date | None:
+    """Coerce a date, datetime, or date string to a plain `date`, or `None`.
+
+    Accepts `date`/`datetime` instances (a `datetime` is narrowed to its
+    `date`), `'YYYY-MM-DD'` or `'MM/DD/YYYY'` strings, and any ISO-8601 string.
+    Returns `None` for `None` or anything unparseable.
+
+    Args:
+        value: The value to coerce.
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    if isinstance(value, str):
+        for fmt in ("%Y-%m-%d", "%m/%d/%Y"):
+            try:
+                return datetime.strptime(value, fmt).date()
+            except Exception:
+                continue
+        try:
+            return datetime.fromisoformat(value).date()
+        except Exception:
+            return None
+    return None

bootstack/widgets/_impl/composites/_image_fit.py

@@ -0,0 +1,105 @@
+"""Shared image fit/crop/round helpers for the media widgets.
+
+Pure functions used by both `Picture` and the `Gallery` tile so the
+object-fit scaling and antialiased rounded-corner masking live in one place.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+from PIL import Image as PILImage, ImageChops, ImageDraw
+from PIL.Image import Resampling
+
+FitMode = Literal["contain", "cover", "fill", "none", "scale-down"]
+
+
+def resolve_pil(source: Any) -> "PILImage.Image | None":
+    """Resolve an image source (Image handle, path, or PIL image) to a PIL image.
+
+    Returns the first frame for an animated source, or None when `source` is
+    None or cannot be decoded.
+    """
+    if source is None:
+        return None
+    from bootstack.images import Image as _ImageHandle
+
+    try:
+        if isinstance(source, _ImageHandle):
+            return source._load_pil()
+        if isinstance(source, (str, Path)):
+            return PILImage.open(Path(source).expanduser())
+        if isinstance(source, PILImage.Image):
+            return source
+    except Exception:
+        return None
+    return None
+
+
+def fit_image(frame: PILImage.Image, bw: int, bh: int, fit: FitMode) -> PILImage.Image:
+    """Scale (and for `cover`, crop) `frame` to a `bw`x`bh` box per `fit`.
+
+    For `contain`/`scale-down`/`none` the result may be smaller than the box —
+    the caller positions it. For `cover`/`fill` the result is exactly the box.
+    """
+    iw, ih = frame.size
+    if iw <= 0 or ih <= 0:
+        return frame
+
+    if fit == "fill":
+        return frame.resize((bw, bh), Resampling.LANCZOS)
+
+    if fit == "cover":
+        scale = max(bw / iw, bh / ih)
+        scaled = frame.resize(
+            (max(1, round(iw * scale)), max(1, round(ih * scale))), Resampling.LANCZOS
+        )
+        left = (scaled.width - bw) // 2
+        top = (scaled.height - bh) // 2
+        return scaled.crop((left, top, left + bw, top + bh))
+
+    # contain / scale-down / none — never crop.
+    if fit == "none":
+        scale = 1.0
+    else:
+        scale = min(bw / iw, bh / ih)
+        if fit == "scale-down":
+            scale = min(scale, 1.0)
+    tw, th = max(1, round(iw * scale)), max(1, round(ih * scale))
+    if (tw, th) == (iw, ih):
+        return frame.copy()
+    return frame.resize((tw, th), Resampling.LANCZOS)
+
+
+def rounded_mask(w: int, h: int, radius: int) -> PILImage.Image:
+    """An antialiased rounded-rectangle alpha mask for a `w`x`h` box.
+
+    Drawn supersampled and downscaled with LANCZOS — `ImageDraw.rounded_rectangle`
+    is aliased at 1x, so the curve would otherwise be jagged. Callers should cache
+    the result; it depends only on `(w, h, radius)`.
+    """
+    radius = min(radius, w // 2, h // 2)
+    ss = 4 if max(w, h) <= 600 else 2
+    big = PILImage.new("L", (w * ss, h * ss), 0)
+    ImageDraw.Draw(big).rounded_rectangle(
+        [0, 0, w * ss - 1, h * ss - 1], radius=radius * ss, fill=255
+    )
+    return big.resize((w, h), Resampling.LANCZOS)
+
+
+def round_corners(
+    img: PILImage.Image, radius: int, mask: PILImage.Image | None = None
+) -> PILImage.Image:
+    """Apply a rounded-rectangle alpha mask to `img` (intersecting existing alpha).
+
+    Pass a precomputed `mask` (from `rounded_mask`) to avoid rebuilding it.
+    """
+    w, h = img.size
+    if radius <= 0:
+        return img
+    if mask is None:
+        mask = rounded_mask(w, h, radius)
+    out = img.convert("RGBA")
+    out.putalpha(ImageChops.multiply(mask, out.getchannel("A")))
+    return out