textual-wtf 0.8.0__py3-none-any.whl

textual_wtf/__init__.py

@@ -0,0 +1,67 @@
+"""
+Textual Forms - A declarative forms library for Textual TUI applications
+
+Example:
+    from textual_wtf import Form, StringField, IntegerField
+
+    class UserForm(Form):
+        name = StringField(label="Name", required=True)
+        age = IntegerField(label="Age", min_value=0, max_value=130)
+"""
+from .version import __version__
+
+from .exceptions import ValidationError, FieldError, FormError, AmbiguousFieldError
+from .bound_fields import BoundField
+from .fields import (
+    Field,
+    StringField,
+    IntegerField,
+    BooleanField,
+    ChoiceField,
+    TextField,
+)
+from .forms import Form
+from .validators import (
+    EvenInteger,
+    Palindromic,
+    EmailValidator,
+)
+from .widgets import (
+    FormInput,
+    FormIntegerInput,
+    FormTextArea,
+    FormCheckbox,
+    FormSelect,
+    WidgetRegistry,
+)
+
+__all__ = [
+    # Exceptions
+    "ValidationError",
+    "FieldError",
+    "FormError",
+    "AmbiguousFieldError",
+    # Fields
+    "Field",
+    "BoundField",
+    "StringField",
+    "IntegerField",
+    "BooleanField",
+    "ChoiceField",
+    "TextField",
+    # Forms
+    "Form",
+    # Validators
+    "EvenInteger",
+    "Palindromic",
+    "EmailValidator",
+    # Widgets
+    "FormInput",
+    "FormIntegerInput",
+    "FormTextArea",
+    "FormCheckbox",
+    "FormSelect",
+    "WidgetRegistry",
+    # Structural
+    "__version__,"
+]

textual_wtf/bound_fields.py

@@ -0,0 +1,245 @@
+"""BoundField - runtime state for fields in form instances"""
+from typing import Any, Optional, List, TYPE_CHECKING
+from textual.widget import Widget
+from textual.validation import Validator
+
+from .exceptions import ValidationError
+
+if TYPE_CHECKING:
+    from .fields import Field
+    from .forms import Form
+
+
+class BoundField:
+    """
+    Holds runtime state for a field in a form instance.
+    
+    Separates mutable state (_widget, _errors, _value) from immutable
+    configuration (stored in the Field instance). This allows Field
+    instances to be safely shared across multiple form instances.
+    
+    CRITICAL INVARIANT: _value must always contain the current Python value,
+    regardless of whether a widget exists. This ensures data is never lost
+    and provides a canonical source of truth.
+    
+    Attributes:
+        field: Reference to the Field configuration (shared, immutable)
+        form: Parent form instance
+        name: Field name in the form
+        _widget_instance: The actual Textual widget (or None)
+        _errors: Current validation errors
+        _value: Current Python value (ALWAYS KEPT IN SYNC)
+    """
+    
+    def __init__(self, field: 'Field', form: 'Form', name: str, initial: Any = None):
+        """
+        Initialize BoundField with runtime state
+        
+        Args:
+            field: Field configuration (shared across instances)
+            form: Parent form instance
+            name: Field name
+            initial: Initial value (overrides field.initial if provided)
+        """
+        # Reference to configuration
+        self.field = field
+        self.form = form
+        self.name = name
+        
+        # Runtime state (mutable, instance-specific)
+        self._widget_instance: Optional[Widget] = None
+        self._errors: List[str] = []
+        self._value = initial if initial is not None else field.initial
+    
+    # ========================================================================
+    # Properties - Delegate configuration to Field
+    # ========================================================================
+    
+    @property
+    def label(self) -> Optional[str]:
+        """Field label (delegated to Field config)"""
+        return self.field.label
+    
+    @property
+    def help_text(self) -> Optional[str]:
+        """Field help text (delegated to Field config)"""
+        return self.field.help_text
+    
+    @property
+    def required(self) -> bool:
+        """Whether field is required (delegated to Field config)"""
+        return self.field.required
+    
+    @property
+    def disabled(self) -> bool:
+        """Whether field is disabled (delegated to Field config)"""
+        return self.field.disabled
+    
+    @property
+    def validators(self) -> List[Validator]:
+        """Field validators (delegated to Field config)"""
+        return self.field.validators
+    
+    @property
+    def initial(self) -> Any:
+        """Initial value (delegated to Field config)"""
+        return self.field.initial
+    
+    # ========================================================================
+    # Properties - Runtime state
+    # ========================================================================
+    
+    @property
+    def widget(self) -> Optional[Widget]:
+        """Get widget instance"""
+        return self._widget_instance
+    
+    @widget.setter
+    def widget(self, widget: Widget) -> None:
+        """Set widget instance"""
+        # Sync value from departing widget before it's replaced or cleared,
+        # so that any user input is preserved in _value.
+        if self._widget_instance is not None:
+            self._value = self.field.to_python(self._widget_instance.value)
+        
+        self._widget_instance = widget
+        if widget:
+            # Create back-reference so widget can access bound field
+            widget.bound_field = self
+    
+    @property
+    def errors(self) -> List[str]:
+        """Get validation errors"""
+        return self._errors
+    
+    @errors.setter
+    def errors(self, errors: List[str]) -> None:
+        """Set validation errors"""
+        self._errors = errors
+    
+    @property
+    def value(self) -> Any:
+        """
+        Get current field value
+        
+        CRITICAL: If widget exists, reads from widget and SYNCS to _value.
+        This ensures _value is always current, even when user types in widget.
+        
+        Returns:
+            Current Python value (from widget if exists, otherwise from _value)
+        """
+        if self._widget_instance is not None:
+            # Read from widget and keep _value in sync
+            python_value = self.field.to_python(self._widget_instance.value)
+            self._value = python_value  # CRITICAL: Always sync
+            return python_value
+        return self._value
+    
+    @value.setter
+    def value(self, value: Any) -> None:
+        """
+        Set field value
+        
+        CRITICAL: Always updates _value (canonical storage) and syncs to
+        widget if it exists. This ensures both storage locations stay in sync.
+        
+        Args:
+            value: Python value to set
+        """
+        self._value = value  # CRITICAL: Always update canonical storage
+        if self._widget_instance is not None:
+            # Also sync to widget if it exists
+            self._widget_instance.value = self.field.to_widget(value)
+    
+    # ========================================================================
+    # Methods - Delegate to Field for logic
+    # ========================================================================
+    
+    def create_widget(self) -> Widget:
+        """
+        Create widget using field configuration
+        
+        Returns:
+            Widget instance configured from Field
+        """
+        widget = self.field.create_widget()
+        self._widget_instance = widget
+        # Set back-reference
+        widget.bound_field = self
+        # Also set field reference for backward compatibility
+        widget.field = self
+        return widget
+    
+    def to_python(self, value: Any) -> Any:
+        """Convert widget value to Python value (delegated to Field)"""
+        return self.field.to_python(value)
+    
+    def to_widget(self, value: Any) -> Any:
+        """Convert Python value to widget value (delegated to Field)"""
+        return self.field.to_widget(value)
+    
+    def validate(self, value: Any) -> None:
+        """
+        Validate value using field configuration
+        
+        Clears existing errors and validates the value.
+        Stores validation errors in _errors list.
+        
+        Args:
+            value: Value to validate
+        """
+        self._errors = []
+        try:
+            self.field.validate(value)
+        except ValidationError as e:
+            self._errors.append(str(e))
+    
+    def clean(self, value: Any) -> Any:
+        """
+        Convert and validate value
+        
+        Args:
+            value: Raw value to clean
+            
+        Returns:
+            Cleaned Python value
+            
+        Raises:
+            ValidationError: If validation fails
+        """
+        python_value = self.field.to_python(value)
+        self.validate(python_value)
+        if self._errors:
+            raise ValidationError(self._errors[0])
+        return python_value
+    
+    # ========================================================================
+    # Additional properties for compatibility with code that accesses
+    # field-specific attributes (e.g., IntegerField.min_value)
+    # ========================================================================
+    
+    def __getattr__(self, name: str) -> Any:
+        """
+        Delegate attribute access to Field for any attributes not found on BoundField
+        
+        This allows access to field-specific configuration like:
+        - IntegerField.min_value, max_value
+        - ChoiceField.choices
+        - etc.
+        """
+        # Avoid infinite recursion for special attributes
+        if name.startswith('_'):
+            raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")
+        
+        # Try to get attribute from Field
+        try:
+            return getattr(self.field, name)
+        except AttributeError:
+            raise AttributeError(
+                f"'{type(self).__name__}' and '{type(self.field).__name__}' "
+                f"have no attribute '{name}'"
+            )
+    
+    def __repr__(self) -> str:
+        """String representation for debugging"""
+        return f"<BoundField: {self.name} ({self.field.__class__.__name__})>"

textual_wtf/demo/advanced_form.py

@@ -0,0 +1,139 @@
+"""Advanced form example with results display"""
+from textual.app import App, ComposeResult
+from textual.containers import Container
+from textual.screen import Screen
+from textual.widgets import Static
+from textual_wtf import (
+    Form, StringField, IntegerField, BooleanField, ChoiceField, TextField
+)
+from textual_wtf.validators import EmailValidator, EvenInteger
+from textual_wtf.demo.results_screen import ResultsDisplayScreen
+
+class ContactForm(Form):
+    """Contact form with multiple field types"""
+    name = StringField(
+        label="Full Name",
+        required=True,
+        help_text="Enter your full name"
+    )
+    email = StringField(
+        label="Email",
+        required=True,
+        validators=[EmailValidator()]
+    )
+    age = IntegerField(
+        label="Age (even numbers only)",
+        min_value=18,
+        max_value=100,
+        validators=[EvenInteger()]
+    )
+    country = ChoiceField(
+        label="Country",
+        choices=[
+            ("us", "United States"),
+            ("uk", "United Kingdom"),
+            ("ca", "Canada"),
+            ("au", "Australia"),
+        ],
+        required=True
+    )
+    subscribe = BooleanField(
+        label="Subscribe to newsletter"
+    )
+    message = TextField(
+        label="Message",
+        help_text="Tell us about yourself"
+    )
+
+
+class ResultsScreen(ResultsDisplayScreen):
+    """Utility Screen to display form results"""
+
+    def compose(self) -> ComposeResult:
+        with Container(id="results-container"):
+            yield Static(self.result_title, id="results-title")
+
+            yield from self.show_data()
+            yield from self.buttons()
+
+
+class AdvancedFormScreen(Screen):
+    """Demo app for advanced form features"""
+
+    CSS = """
+    Screen {
+        align: center middle;
+    }
+
+    RenderedForm {
+        width: 60;
+        height: auto;
+        max-height: 90%;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        # Pre-populate with example data
+        initial_data = {
+            "name": "John Doe",
+            "email": "john@example.com",
+            "age": 30,
+            "country": "us",
+            "subscribe": True,
+        }
+        self.form = ContactForm(
+            title="Contact Information",
+            data=initial_data
+        )
+        yield self.form.render()
+
+    def on_form_submitted(self, event: Form.Submitted):
+        """Handle form submission"""
+        data = event.form.get_data()
+
+        def check_reset(cont):
+            if cont:
+                self.reset_form()
+            else:
+                self.dismiss(cont)
+
+        self.app.push_screen(
+            ResultsScreen("Form Submitted Successfully!", data), check_reset
+        )
+
+    def on_form_cancelled(self, event: Form.Cancelled):
+        """Handle form cancellation"""
+
+        def check_reset(cont):
+            if cont:
+                self.reset_form()
+            else:
+                self.dismiss(cont)
+
+        self.app.push_screen(ResultsScreen("Form Cancelled", None), check_reset)
+
+    def reset_form(self):
+        """Clear form and create fresh one"""
+        old_form = self.query_one("RenderedForm")
+        old_form.remove()
+
+        self.form = ContactForm(title="Contact Information")
+        self.mount(self.form.render())
+
+class AdvancedFormApp(App):
+
+    def on_mount(self):
+        self.app.push_screen(AdvancedFormScreen(), callback=self.exit_app)
+
+    def exit_app(self, result=None) -> None:
+        """Called when BasicFormScreen is dismissed."""
+        self.exit(result)
+
+
+
+def main():
+    AdvancedFormApp().run()
+
+
+if __name__ == "__main__":
+    main()

textual_wtf/demo/basic_form.py

@@ -0,0 +1,92 @@
+"""Basic form example with results display"""
+from textual.app import App, ComposeResult
+from textual.containers import Container, Center
+from textual.screen import Screen
+from textual.widgets import Static, Button
+from textual_wtf import Form, StringField, IntegerField, BooleanField
+from textual_wtf.demo.results_screen import ResultsDisplayScreen  # Demo library utility
+
+class UserForm(Form):
+    """Simple user registration form"""
+    name = StringField(label="Name", required=True)
+    age = IntegerField(label="Age", min_value=0, max_value=130)
+    active = BooleanField(label="Active User")
+
+
+class ResultScreen(ResultsDisplayScreen):
+    """Utility Screen to display form results"""
+
+    def compose(self) -> ComposeResult:
+        with Container(id="results-container"):
+            yield Static(self.result_title, id="results-title")
+
+            yield from self.show_data()
+            yield from self.buttons()
+
+
+class BasicFormScreen(Screen):
+    """Demo app for basic form"""
+
+    CSS_PATH = "basic_form.tcss"
+
+    def compose(self) -> ComposeResult:
+        self.form = UserForm(title="User Registration")
+        yield self.form.render()
+
+    def on_form_submitted(self, event: Form.Submitted):
+        """Handle form submission"""
+        data = event.form.get_data()
+        # Show results screen
+
+        def check_reset(cont):
+            if cont:
+                self.reset_form()
+            else:
+                self.dismiss(cont)
+
+        self.app.push_screen(
+            ResultScreen("Form Submitted Successfully!", data), check_reset
+        )
+
+    def on_form_cancelled(self, event: Form.Cancelled):
+        """Handle form cancellation"""
+        # Show cancellation screen
+
+        def check_reset(cont):
+            if cont:
+                self.reset_form()
+            else:
+                self.dismiss(cont)
+
+        self.app.push_screen(ResultScreen("Form Cancelled", None), check_reset)
+
+    def reset_form(self):
+        """Clear form and create fresh one"""
+        # Remove old form
+        old_form = self.query_one("RenderedForm")
+        old_form.remove()
+
+        # Create and mount new form
+        self.form = UserForm(title="User Registration")
+        self.mount(self.form.render())
+
+    def on_click(self):
+        self.app.log(self.css_tree)
+        self.app.log(self.tree)
+
+
+class BasicFormApp(App):
+
+    def on_mount(self):
+        self.app.push_screen(BasicFormScreen(), callback=self.exit_app)
+
+    def exit_app(self, result=None) -> None:
+        """Called when BasicFormScreen is dismissed."""
+        self.exit(result)
+
+
+def main():
+    BasicFormApp().run()
+
+if __name__ == "__main__":
+    main()

textual_wtf/demo/basic_form.tcss

@@ -0,0 +1,7 @@
+Screen {
+    align: center middle;
+}
+
+RenderedForm {
+    width: 80%;
+}

textual_wtf/demo/launcher.py

@@ -0,0 +1,124 @@
+import sys
+import os
+import subprocess
+import importlib.resources as i_r
+
+from textual.app import App, ComposeResult
+from textual.containers import Vertical
+from textual.screen import Screen
+from textual.widgets import Label, Header, Footer
+from textual.message import Message
+
+from textual_wtf.demo.basic_form import BasicFormScreen as BasicScreen
+from textual_wtf.demo.advanced_form import AdvancedFormScreen as AdvancedScreen
+from textual_wtf.demo.user_registration import RegistrationScreen
+from textual_wtf.demo.nested_once_form import ShopScreen as NestedOnceScreen
+from textual_wtf.demo.nested_twice_form import ShopScreen as NestedTwiceScreen
+
+class MenuLink(Label):
+    """A clickable text link widget."""
+
+    DEFAULT_CSS = """
+    MenuLink {
+        color: $accent;
+        text-style: underline;
+        margin-bottom: 1;
+        width: auto;
+        content-align: center middle;
+    }
+    MenuLink:hover {
+        color: $text;
+        text-style: bold underline;
+        background: $accent 10%;
+    }
+    """
+
+    class Clicked(Message):
+        """Message posted when the link is clicked."""
+
+        def __init__(self, link: "MenuLink") -> None:
+            self.link = link
+            super().__init__()
+
+
+
+    def __init__(self, title: str, app_screen: Screen = None, is_exit: bool = False):
+        super().__init__(title)
+        self.app_screen = app_screen
+        self.is_exit = is_exit
+
+    def on_click(self) -> None:
+        """Handle click event."""
+        self.post_message(self.Clicked(self))
+
+
+class LauncherApp(App):
+    """A simple launcher for Textual Forms examples."""
+
+    CSS = """
+    Screen {
+        align: center middle;
+        background: $surface;
+    }
+
+    #menu-container {
+        width: 50;
+        height: auto;
+        border: thick $primary;
+        background: $panel;
+        padding: 1 2;
+    }
+
+    #title-label {
+        width: 100%;
+        content-align: center middle;
+        text-style: bold;
+        padding-bottom: 2;
+        color: $text-muted;
+    }
+
+    /* Style the exit link differently */
+    .exit-link {
+        color: $error;
+        margin-top: 1;
+    }
+    .exit-link:hover {
+        color: $error-lighten-1;
+        background: $error 10%;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+
+        with Vertical(id="menu-container"):
+            yield Label("Select an Application", id="title-label")
+
+            # Application Links
+            yield MenuLink("1. Basic Form", app_screen=BasicScreen)
+            yield MenuLink("2. Advanced Form", app_screen=AdvancedScreen)
+            yield MenuLink("3. User Registration", app_screen=RegistrationScreen)
+            yield MenuLink("4. Composition Example", app_screen=NestedOnceScreen)
+            yield MenuLink("5. Multiply Included Example", app_screen=NestedTwiceScreen)
+
+            # Exit Link
+            yield MenuLink("Exit Launcher", is_exit=True)
+
+        yield Footer()
+
+    def on_menu_link_clicked(self, event: MenuLink.Clicked) -> None:
+        """Handle the custom link click message."""
+        link = event.link
+
+        if link.is_exit:
+            self.exit()
+        elif link.app_screen:
+            self.app.push_screen(link.app_screen())
+
+
+def main():
+        LauncherApp().run()
+
+
+if __name__ == "__main__":
+    main()