codeforms 0.1.1__tar.gz → 0.2.0__tar.gz

{codeforms-0.1.1 → codeforms-0.2.0}/.gitignore

@@ -8,7 +8,9 @@ wheels/
 # Virtual environments
 .venv
 
+# Private
 todo
+info
 
 # Agents
 CLAUDE.md

{codeforms-0.1.1 → codeforms-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforms
-Version: 0.1.1
+Version: 0.2.0
 Summary: Python library for creating, validating, and rendering web forms using Pydantic
 License-Expression: MIT
 License-File: LICENSE

codeforms-0.2.0/examples/conditional_visibility.py

@@ -0,0 +1,103 @@
+"""
+Ejemplo de visibilidad condicional con visible_when.
+
+Demuestra cómo ocultar/mostrar campos según el valor de otros campos,
+y la diferencia entre validación legacy y dinámica.
+"""
+
+from codeforms import (
+    Form,
+    TextField,
+    SelectField,
+    SelectOption,
+    VisibilityRule,
+    validate_form_data,
+    validate_form_data_dynamic,
+)
+
+
+def create_address_form() -> Form:
+    """Crea un formulario de dirección con campos condicionales."""
+    return Form(
+        name="address_form",
+        fields=[
+            SelectField(
+                name="country",
+                label="Country",
+                required=True,
+                options=[
+                    SelectOption(value="US", label="United States"),
+                    SelectOption(value="AR", label="Argentina"),
+                    SelectOption(value="UK", label="United Kingdom"),
+                ],
+            ),
+            # Solo visible cuando country == "US"
+            TextField(
+                name="state",
+                label="State",
+                required=True,
+                visible_when=[
+                    VisibilityRule(field="country", operator="equals", value="US"),
+                ],
+            ),
+            # Solo visible cuando country == "AR"
+            TextField(
+                name="province",
+                label="Province",
+                required=True,
+                visible_when=[
+                    VisibilityRule(field="country", operator="equals", value="AR"),
+                ],
+            ),
+            # Solo visible cuando country == "UK"
+            TextField(
+                name="county",
+                label="County",
+                required=True,
+                visible_when=[
+                    VisibilityRule(field="country", operator="equals", value="UK"),
+                ],
+            ),
+            # Siempre visible
+            TextField(
+                name="city",
+                label="City",
+                required=True,
+            ),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    form = create_address_form()
+    data_us = {"country": "US", "state": "California", "city": "Los Angeles"}
+    data_ar = {"country": "AR", "province": "Buenos Aires", "city": "CABA"}
+
+    # --- Legacy validation: ignores visible_when ---
+    print("=== Legacy validate_form_data (ignores visible_when) ===")
+    result = validate_form_data(form, data_us)
+    print(f"US data: success={result['success']}")
+    if not result["success"]:
+        print(f"  Errors: {result['errors']}")
+        print("  (Province and County are required but missing — legacy doesn't know they're hidden)")
+
+    # --- Dynamic validation: respects visible_when ---
+    print("\n=== Dynamic validate_form_data_dynamic (respects visible_when) ===")
+    result = validate_form_data_dynamic(form, data_us, respect_visibility=True)
+    print(f"US data: success={result['success']}")
+    if result["success"]:
+        print(f"  Validated data: {result['data']}")
+        print("  (Province and County are hidden, so not validated)")
+
+    result = validate_form_data_dynamic(form, data_ar, respect_visibility=True)
+    print(f"AR data: success={result['success']}")
+    if result["success"]:
+        print(f"  Validated data: {result['data']}")
+
+    # --- Visible fields helper ---
+    print("\n=== get_visible_fields ===")
+    visible = form.get_visible_fields(data_us)
+    print(f"Visible fields for US: {[f.name for f in visible]}")
+
+    visible = form.get_visible_fields(data_ar)
+    print(f"Visible fields for AR: {[f.name for f in visible]}")

codeforms-0.2.0/examples/dependent_options.py

@@ -0,0 +1,73 @@
+"""
+Ejemplo de opciones dependientes con DependentOptionsConfig.
+
+Demuestra cómo definir campos cuyos opciones cambian según el valor
+de otro campo (por ejemplo, país → ciudades).
+"""
+
+from codeforms import (
+    Form,
+    SelectField,
+    SelectOption,
+    DependentOptionsConfig,
+)
+
+
+def create_location_form() -> Form:
+    """Crea un formulario con ciudades dependientes del país seleccionado."""
+    return Form(
+        name="location_form",
+        fields=[
+            SelectField(
+                name="country",
+                label="Country",
+                required=True,
+                options=[
+                    SelectOption(value="US", label="United States"),
+                    SelectOption(value="AR", label="Argentina"),
+                ],
+            ),
+            SelectField(
+                name="city",
+                label="City",
+                required=True,
+                # Opciones estáticas (todas las ciudades posibles para HTML rendering)
+                options=[
+                    SelectOption(value="nyc", label="New York City"),
+                    SelectOption(value="la", label="Los Angeles"),
+                    SelectOption(value="bsas", label="Buenos Aires"),
+                    SelectOption(value="cor", label="Córdoba"),
+                ],
+                # Metadata de dependencia (para lógica dinámica en frontend o backend)
+                dependent_options=DependentOptionsConfig(
+                    depends_on="country",
+                    options_map={
+                        "US": [
+                            SelectOption(value="nyc", label="New York City"),
+                            SelectOption(value="la", label="Los Angeles"),
+                        ],
+                        "AR": [
+                            SelectOption(value="bsas", label="Buenos Aires"),
+                            SelectOption(value="cor", label="Córdoba"),
+                        ],
+                    },
+                ),
+            ),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    form = create_location_form()
+
+    # La metadata de dependencia se serializa a JSON
+    import json
+    data = json.loads(form.model_dump_json(exclude_none=True))
+    city_field = data["content"][1]
+    print("City field dependent_options:")
+    print(json.dumps(city_field["dependent_options"], indent=2))
+
+    # Las opciones específicas para cada país
+    dep = form.fields[1].dependent_options
+    print(f"\nOptions for US: {[o.label for o in dep.options_map['US']]}")
+    print(f"Options for AR: {[o.label for o in dep.options_map['AR']]}")

codeforms-0.2.0/examples/wizard_form.py

@@ -0,0 +1,129 @@
+"""
+Ejemplo de formulario multi-paso (wizard) con FormStep.
+
+Demuestra cómo crear un formulario wizard con validación por paso
+y validación global.
+"""
+
+from codeforms import (
+    Form,
+    FormStep,
+    TextField,
+    EmailField,
+    NumberField,
+    SelectField,
+    SelectOption,
+    CheckboxField,
+    FieldGroup,
+    validate_form_data_dynamic,
+)
+
+
+def create_registration_wizard() -> Form:
+    """Crea un formulario wizard de registro de usuario en 3 pasos."""
+    return Form(
+        name="registration_wizard",
+        content=[
+            # Paso 1: Información personal
+            FormStep(
+                title="Personal Information",
+                description="Tell us about yourself",
+                content=[
+                    TextField(name="first_name", label="First Name", required=True),
+                    TextField(name="last_name", label="Last Name", required=True),
+                    EmailField(name="email", label="Email", required=True),
+                ],
+            ),
+            # Paso 2: Preferencias
+            FormStep(
+                title="Preferences",
+                description="Choose your plan and preferences",
+                content=[
+                    SelectField(
+                        name="plan",
+                        label="Plan",
+                        required=True,
+                        options=[
+                            SelectOption(value="free", label="Free"),
+                            SelectOption(value="pro", label="Professional"),
+                            SelectOption(value="enterprise", label="Enterprise"),
+                        ],
+                    ),
+                    NumberField(
+                        name="team_size",
+                        label="Team Size",
+                        min_value=1,
+                        max_value=1000,
+                    ),
+                ],
+            ),
+            # Paso 3: Confirmación
+            FormStep(
+                title="Confirmation",
+                description="Review and accept the terms",
+                content=[
+                    CheckboxField(
+                        name="terms",
+                        label="I accept the terms and conditions",
+                        required=True,
+                    ),
+                ],
+                validation_mode="on_submit",
+            ),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    form = create_registration_wizard()
+
+    # Verificar estructura
+    print(f"Form: {form.name}")
+    print(f"Steps: {len(form.get_steps())}")
+    print(f"Total fields: {len(form.fields)}")
+
+    for i, step in enumerate(form.get_steps()):
+        print(f"\n  Step {i + 1}: {step.title}")
+        for field in step.fields:
+            print(f"    - {field.name} ({'required' if field.required else 'optional'})")
+
+    # Validar paso 1
+    print("\n--- Validating Step 1 ---")
+    result = form.validate_step(0, {
+        "first_name": "John",
+        "last_name": "Doe",
+        "email": "john@example.com",
+    })
+    print(f"Step 1 valid: {result['success']}")
+
+    # Validar paso 2
+    print("\n--- Validating Step 2 ---")
+    result = form.validate_step(1, {
+        "plan": "pro",
+        "team_size": 5,
+    })
+    print(f"Step 2 valid: {result['success']}")
+
+    # Validar todos los pasos
+    print("\n--- Validating All Steps ---")
+    result = form.validate_all_steps({
+        "first_name": "John",
+        "last_name": "Doe",
+        "email": "john@example.com",
+        "plan": "pro",
+        "team_size": 5,
+        "terms": True,
+    })
+    print(f"All steps valid: {result['success']}")
+
+    # Exportar HTML
+    print("\n--- HTML Export ---")
+    export = form.export("html_bootstrap5")
+    print(export["output"][:300] + "...")
+
+    # JSON roundtrip
+    print("\n--- JSON Roundtrip ---")
+    json_str = form.model_dump_json()
+    restored = Form.model_validate_json(json_str)
+    print(f"Restored steps: {len(restored.get_steps())}")
+    print(f"Restored fields: {len(restored.fields)}")

{codeforms-0.1.1 → codeforms-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codeforms"
-version = "0.1.1"
+version = "0.2.0"
 description = "Python library for creating, validating, and rendering web forms using Pydantic"
 readme = "README.md"
 requires-python = ">=3.9"

codeforms-0.2.0/src/codeforms/__init__.py

@@ -0,0 +1,86 @@
+from codeforms.fields import (
+    FieldType,
+    ValidationRule,
+    VisibilityRule,
+    DependentOptionsConfig,
+    FormFieldBase,
+    SelectOption,
+    CheckboxField,
+    CheckboxGroupField,
+    RadioField,
+    SelectField,
+    TextField,
+    EmailField,
+    NumberField,
+    DateField,
+    FileField,
+    HiddenField,
+    UrlField,
+    TextareaField,
+    ListField,
+    FieldGroup,
+    FormStep,
+)
+from codeforms.forms import (
+    Form,
+    FormDataValidator,
+    validate_form_data,
+    evaluate_visibility,
+    validate_form_data_dynamic,
+)
+from codeforms.export import ExportFormat
+from codeforms.i18n import (
+    t,
+    set_locale,
+    get_locale,
+    get_available_locales,
+    register_locale,
+    get_messages,
+)
+from codeforms.registry import (
+    register_field_type,
+    get_registered_field_types,
+)
+
+__all__ = [
+    # Field types and base
+    "FieldType",
+    "ValidationRule",
+    "VisibilityRule",
+    "DependentOptionsConfig",
+    "FormFieldBase",
+    "SelectOption",
+    "CheckboxField",
+    "CheckboxGroupField",
+    "RadioField",
+    "SelectField",
+    "TextField",
+    "EmailField",
+    "NumberField",
+    "DateField",
+    "FileField",
+    "HiddenField",
+    "UrlField",
+    "TextareaField",
+    "ListField",
+    "FieldGroup",
+    "FormStep",
+    # Form
+    "Form",
+    "FormDataValidator",
+    "validate_form_data",
+    "evaluate_visibility",
+    "validate_form_data_dynamic",
+    # Export
+    "ExportFormat",
+    # i18n
+    "t",
+    "set_locale",
+    "get_locale",
+    "get_available_locales",
+    "register_locale",
+    "get_messages",
+    # Registry
+    "register_field_type",
+    "get_registered_field_types",
+]

{codeforms-0.1.1 → codeforms-0.2.0}/src/codeforms/export.py

@@ -1,6 +1,6 @@
 from enum import Enum
 from codeforms.forms import Form
-from codeforms.fields import FormFieldBase
+from codeforms.fields import FormFieldBase, FieldGroup, FormStep
 from codeforms.i18n import t
 
 
@@ -111,6 +111,17 @@ def group_exporter(group, output_format: str, **kwargs) -> str:
     return ""
 
 
+def step_exporter(step, output_format: str, **kwargs) -> str:
+    """Exporta un paso de formulario (wizard) al formato especificado"""
+    if output_format in ('html', ExportFormat.HTML.value,
+                         ExportFormat.BOOTSTRAP4.value,
+                         ExportFormat.BOOTSTRAP5.value):
+        actual_kwargs = kwargs.get('kwargs', kwargs)
+        actual_kwargs['output_format'] = output_format
+        return step_to_html(step, **actual_kwargs)
+    return ""
+
+
 def group_to_html(group, **kwargs) -> str:
     """Genera la representación HTML del grupo de campos usando fieldset y legend"""
     output_format = kwargs.get('output_format', ExportFormat.HTML.value)
@@ -147,27 +158,85 @@ def group_to_html(group, **kwargs) -> str:
     html += description_html
     html += fields_html
     html += '</fieldset>'
-    
+
+    return html
+
+
+def step_to_html(step, **kwargs) -> str:
+    """Genera la representación HTML de un paso del wizard usando <section>.
+
+    Diferente de FieldGroup (que usa <fieldset>) para distinguir semánticamente.
+    """
+    output_format = kwargs.get('output_format', ExportFormat.HTML.value)
+    is_bootstrap = output_format in [ExportFormat.BOOTSTRAP4.value, ExportFormat.BOOTSTRAP5.value]
+
+    # Clases CSS para el section
+    step_class = f"form-step mb-4 {step.css_classes or ''}".strip() if is_bootstrap else f"form-step {step.css_classes or ''}".strip()
+    title_class = "h4 mb-3" if is_bootstrap else "step-title"
+
+    # Atributos del section
+    step_attrs = {
+        "id": f"step_{step.id}",
+        "class": step_class,
+        "data-step": "true",
+        "data-validation-mode": step.validation_mode,
+        "data-skippable": str(step.skippable).lower()
+    }
+    step_attrs.update(step.attributes)
+
+    attrs_str = " ".join(f'{k}="{v}"' for k, v in step_attrs.items() if v)
+
+    # Generar HTML del contenido (campos y/o grupos)
+    content_html_parts = []
+    for item in step.content:
+        if isinstance(item, FieldGroup):
+            content_html_parts.append(group_to_html(item, **kwargs))
+        else:
+            content_html_parts.append(field_to_html(item, **kwargs))
+    content_html = "\n".join(content_html_parts)
+
+    # Descripción opcional
+    description_html = ""
+    if step.description:
+        desc_class = "text-muted mb-3" if is_bootstrap else "step-description"
+        description_html = f'<p class="{desc_class}">{step.description}</p>'
+
+    html = f'<section {attrs_str}>'
+    html += f'<h2 class="{title_class}">{step.title}</h2>'
+    html += description_html
+    html += content_html
+    html += '</section>'
+
     return html
 
+
 def form_to_html(form: Form, **kwargs) -> str:
     """Genera el HTML completo del formulario"""
     output_format = kwargs.get('output_format', ExportFormat.HTML.value)
     form_class = "needs-validation" if output_format in [ExportFormat.BOOTSTRAP4.value, ExportFormat.BOOTSTRAP5.value] else ""
-    
+
+    # Detectar si es wizard
+    is_wizard = any(isinstance(item, FormStep) for item in form.content)
+    if is_wizard:
+        form_class = f"{form_class} form-wizard".strip()
+
     attributes = {
         "id": kwargs.get('id') or str(form.id),
         "name": form.name,
         "class": f"{form_class} {form.css_classes or ''}".strip(),
         "enctype": kwargs.get('enctype') or "application/x-www-form-urlencoded"
     }
+    if is_wizard:
+        attributes["data-wizard"] = "true"
 
     attrs_str = " ".join(f'{k}="{v}"' for k, v in attributes.items() if v)
-    
-    # Generar HTML para cada elemento del contenido (campos o grupos)
+
+    # Generar HTML para cada elemento del contenido (campos, grupos o steps)
     content_html_parts = []
     for item in form.content:
-        if hasattr(item, 'fields') and hasattr(item, 'title'):  # Es un FieldGroup
+        if isinstance(item, FormStep):  # Es un FormStep (wizard)
+            content_html_parts.append(step_to_html(item, **kwargs))
+        elif isinstance(item, FieldGroup):  # Es un FieldGroup
             content_html_parts.append(group_to_html(item, **kwargs))
         else:  # Es un campo individual
             content_html_parts.append(field_to_html(item, **kwargs))

{codeforms-0.1.1 → codeforms-0.2.0}/src/codeforms/fields.py

@@ -1,7 +1,7 @@
 import re
 from datetime import date, datetime
 from enum import Enum
-from typing import Optional, List, Union, Dict, Any, Type, Set
+from typing import Optional, List, Literal, Union, Dict, Any, Type, Set
 from uuid import UUID, uuid4
 from pydantic import BaseModel, Field, EmailStr, ConfigDict, field_validator, model_validator
 from codeforms.i18n import t
@@ -30,6 +30,25 @@ class ValidationRule(BaseModel):
     message: str
 
 
+class VisibilityRule(BaseModel):
+    """Regla de visibilidad condicional para un campo."""
+    field: str                    # nombre del campo del que depende
+    operator: str = "equals"      # equals, not_equals, in, not_in, gt, lt, is_empty, is_not_empty
+    value: Any = None             # valor a comparar
+
+
+class SelectOption(BaseModel):
+    value: str
+    label: str
+    selected: bool = False
+
+
+class DependentOptionsConfig(BaseModel):
+    """Configuración para opciones dependientes de otro campo."""
+    depends_on: str                              # nombre del campo padre
+    options_map: Dict[str, List[SelectOption]]    # valor_padre → opciones disponibles
+
+
 class FormFieldBase(BaseModel):
     id: UUID = Field(default_factory=uuid4)
     name: str
@@ -43,6 +62,8 @@ class FormFieldBase(BaseModel):
     css_classes: Optional[str] = None
     readonly: bool = False
     attributes: Dict[str, str] = Field(default_factory=dict)
+    visible_when: Optional[List[VisibilityRule]] = None
+    dependent_options: Optional[DependentOptionsConfig] = None
 
     @field_validator('attributes', mode='before')
     @classmethod
@@ -74,12 +95,6 @@ class FormFieldBase(BaseModel):
         return field_exporter(self, output_format, kwargs=kwargs)
 
 
-class SelectOption(BaseModel):
-    value: str
-    label: str
-    selected: bool = False
-
-
 class CheckboxField(FormFieldBase):
     field_type: FieldType = FieldType.CHECKBOX
     checked: bool = False
@@ -258,6 +273,7 @@ class ListField(FormFieldBase):
 
 class FieldGroup(BaseModel):
     """Representa un grupo de campos en un formulario para organización en secciones"""
+    container_type: str = "group"  # Discriminador explícito para distinguir de FormStep
     id: UUID = Field(default_factory=uuid4)
     title: str
     description: Optional[str] = None
@@ -298,3 +314,64 @@ class FieldGroup(BaseModel):
         from codeforms.export import group_exporter
         return group_exporter(self, output_format, kwargs=kwargs)
 
+
+class FormStep(BaseModel):
+    """Representa un paso en un formulario multi-paso (wizard).
+
+    Agrupa campos y/o grupos de campos en una secuencia lógica.
+    Se diferencia de FieldGroup mediante el discriminador explícito type="step".
+    """
+    type: Literal["step"] = "step"  # Discriminador explícito (RISK-1)
+    id: UUID = Field(default_factory=uuid4)
+    title: str
+    description: Optional[str] = None
+    content: List[Any]  # Puede contener campos y/o FieldGroups
+    css_classes: Optional[str] = None
+    attributes: Dict[str, str] = Field(default_factory=dict)
+    validation_mode: str = "on_next"  # on_next | on_submit | on_change
+    skippable: bool = False
+
+    model_config = {
+        "json_serializers": {
+            UUID: str,
+            datetime: lambda v: v.isoformat(),
+            date: lambda v: v.isoformat()
+        }
+    }
+
+    @field_validator('attributes', mode='before')
+    @classmethod
+    def coerce_attributes_to_strings(cls, v: Any) -> Dict[str, str]:
+        if v is None:
+            return {}
+        if isinstance(v, dict):
+            return {str(k): str(val) for k, val in v.items()}
+        return v
+
+    @model_validator(mode='before')
+    @classmethod
+    def resolve_step_content(cls, data: Any) -> Any:
+        """Resolver items del contenido del paso usando el registry."""
+        if isinstance(data, dict) and 'content' in data:
+            from codeforms.registry import resolve_content_item
+            data = data.copy()
+            data['content'] = [resolve_content_item(item) for item in data['content']]
+        return data
+
+    @property
+    def fields(self) -> List[FormFieldBase]:
+        """Devuelve una lista plana de todos los campos en este paso,
+        incluyendo campos dentro de FieldGroups anidados (RISK-2)."""
+        all_fields = []
+        for item in self.content:
+            if isinstance(item, FieldGroup):
+                all_fields.extend(item.fields)
+            elif isinstance(item, FormFieldBase):
+                all_fields.append(item)
+        return all_fields
+
+    def export(self, output_format: str = 'html', **kwargs) -> str:
+        """Exportar el paso en diferentes formatos."""
+        from codeforms.export import step_exporter
+        return step_exporter(self, output_format, kwargs=kwargs)
+