codeforms 0.1.0__tar.gz → 0.2.0__tar.gz

{codeforms-0.1.0 → codeforms-0.2.0}/.github/workflows/tests.yml

@@ -9,6 +9,9 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
 
     steps:
       - name: Checkout
@@ -17,7 +20,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
         run: |

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

@@ -8,13 +8,16 @@ wheels/
 # Virtual environments
 .venv
 
+# Private
 todo
+info
 
 # Agents
 CLAUDE.md
 .claude
 
-# Caches
+# Caches and temps
 .uv-cache
 .pytest_cache
-__pycache__/
+__pycache__/
+.tmp

codeforms-0.2.0/.python-version

@@ -0,0 +1 @@
+3.11

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: codeforms
-Version: 0.1.0
+Version: 0.2.0
 Summary: Python library for creating, validating, and rendering web forms using Pydantic
 License-Expression: MIT
 License-File: LICENSE
-Requires-Python: >=3.12
+Requires-Python: >=3.9
 Requires-Dist: pydantic[email]>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'
@@ -26,7 +26,7 @@ Or with [uv](https://docs.astral.sh/uv/):
 uv add codeforms
 ```
 
-Requires Python 3.12+.
+Requires Python 3.9+.
 
 ## Quick Start
 
@@ -258,6 +258,68 @@ print(result["errors"][0]["message"])  # "El campo name es requerido"
 
 See [`examples/i18n_usage.py`](examples/i18n_usage.py) for a full working example.
 
+## Custom Field Types
+
+You can create your own field types by subclassing `FormFieldBase` and registering them with `register_field_type()`. Custom fields integrate seamlessly with forms, JSON serialization, validation, and HTML export.
+
+### Defining a Custom Field
+
+```python
+from codeforms import FormFieldBase, register_field_type
+
+class PhoneField(FormFieldBase):
+    field_type: str = "phone"       # unique string identifier
+    country_code: str = "+1"
+
+class RatingField(FormFieldBase):
+    field_type: str = "rating"
+    min_rating: int = 1
+    max_rating: int = 5
+
+register_field_type(PhoneField)
+register_field_type(RatingField)
+```
+
+### Using Custom Fields in Forms
+
+```python
+from codeforms import Form, TextField
+
+form = Form(
+    name="feedback",
+    fields=[
+        TextField(name="name", label="Name", required=True),
+        PhoneField(name="phone", label="Phone", country_code="+54"),
+        RatingField(name="score", label="Score", max_rating=10),
+    ],
+)
+```
+
+### JSON Roundtrip
+
+Custom fields serialize and deserialize automatically (as long as the field type is registered before deserialization):
+
+```python
+import json
+
+json_str = form.to_json()
+restored = Form.loads(json_str)
+
+assert isinstance(restored.fields[1], PhoneField)
+assert restored.fields[1].country_code == "+54"
+```
+
+### Listing Registered Types
+
+```python
+from codeforms import get_registered_field_types
+
+for name, classes in sorted(get_registered_field_types().items()):
+    print(f"{name}: {[c.__name__ for c in classes]}")
+```
+
+See [`examples/custom_fields.py`](examples/custom_fields.py) for a full working example.
+
 ## License
 
 MIT

{codeforms-0.1.0 → codeforms-0.2.0}/README.md

@@ -14,7 +14,7 @@ Or with [uv](https://docs.astral.sh/uv/):
 uv add codeforms
 ```
 
-Requires Python 3.12+.
+Requires Python 3.9+.
 
 ## Quick Start
 
@@ -246,6 +246,68 @@ print(result["errors"][0]["message"])  # "El campo name es requerido"
 
 See [`examples/i18n_usage.py`](examples/i18n_usage.py) for a full working example.
 
+## Custom Field Types
+
+You can create your own field types by subclassing `FormFieldBase` and registering them with `register_field_type()`. Custom fields integrate seamlessly with forms, JSON serialization, validation, and HTML export.
+
+### Defining a Custom Field
+
+```python
+from codeforms import FormFieldBase, register_field_type
+
+class PhoneField(FormFieldBase):
+    field_type: str = "phone"       # unique string identifier
+    country_code: str = "+1"
+
+class RatingField(FormFieldBase):
+    field_type: str = "rating"
+    min_rating: int = 1
+    max_rating: int = 5
+
+register_field_type(PhoneField)
+register_field_type(RatingField)
+```
+
+### Using Custom Fields in Forms
+
+```python
+from codeforms import Form, TextField
+
+form = Form(
+    name="feedback",
+    fields=[
+        TextField(name="name", label="Name", required=True),
+        PhoneField(name="phone", label="Phone", country_code="+54"),
+        RatingField(name="score", label="Score", max_rating=10),
+    ],
+)
+```
+
+### JSON Roundtrip
+
+Custom fields serialize and deserialize automatically (as long as the field type is registered before deserialization):
+
+```python
+import json
+
+json_str = form.to_json()
+restored = Form.loads(json_str)
+
+assert isinstance(restored.fields[1], PhoneField)
+assert restored.fields[1].country_code == "+54"
+```
+
+### Listing Registered Types
+
+```python
+from codeforms import get_registered_field_types
+
+for name, classes in sorted(get_registered_field_types().items()):
+    print(f"{name}: {[c.__name__ for c in classes]}")
+```
+
+See [`examples/custom_fields.py`](examples/custom_fields.py) for a full working example.
+
 ## License
 
 MIT

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/custom_fields.py

@@ -0,0 +1,184 @@
+"""
+Custom field types example for codeforms.
+
+Demonstrates how to create and register custom field types,
+use them in forms, and perform JSON roundtrip serialization.
+"""
+
+import json
+from typing import Optional
+
+from pydantic import field_validator
+
+from codeforms import (
+    Form,
+    FormFieldBase,
+    FieldGroup,
+    TextField,
+    EmailField,
+    register_field_type,
+    get_registered_field_types,
+)
+
+
+# ---------------------------------------------------------------------------
+# 1. Define custom field types
+# ---------------------------------------------------------------------------
+
+class PhoneField(FormFieldBase):
+    """A phone number field with an optional country code."""
+    field_type: str = "phone"
+    country_code: str = "+1"
+    placeholder: Optional[str] = "e.g. +1-555-0100"
+
+
+class RatingField(FormFieldBase):
+    """A numeric rating field with configurable range."""
+    field_type: str = "rating"
+    min_rating: int = 1
+    max_rating: int = 5
+
+    @field_validator("max_rating")
+    @classmethod
+    def max_above_min(cls, v, info):
+        min_r = info.data.get("min_rating", 1)
+        if v <= min_r:
+            raise ValueError("max_rating must be greater than min_rating")
+        return v
+
+
+class ColorField(FormFieldBase):
+    """A colour picker field."""
+    field_type: str = "color"
+    color_format: str = "hex"  # hex | rgb | hsl
+
+
+# ---------------------------------------------------------------------------
+# 2. Register them
+# ---------------------------------------------------------------------------
+
+register_field_type(PhoneField)
+register_field_type(RatingField)
+register_field_type(ColorField)
+
+
+def show_registered_types():
+    """Print all registered field types."""
+    print("=" * 60)
+    print("Registered field types")
+    print("=" * 60)
+    for key, classes in sorted(get_registered_field_types().items()):
+        names = ", ".join(c.__name__ for c in classes)
+        print(f"  {key:12s} → {names}")
+    print()
+
+
+def create_form_with_custom_fields():
+    """Build a form that mixes built-in and custom field types."""
+    print("=" * 60)
+    print("Form with custom fields")
+    print("=" * 60)
+
+    form = Form(
+        name="event_feedback",
+        content=[
+            FieldGroup(
+                title="Contact",
+                fields=[
+                    TextField(name="name", label="Full name", required=True),
+                    EmailField(name="email", label="Email"),
+                    PhoneField(name="phone", label="Phone", country_code="+54"),
+                ],
+            ),
+            FieldGroup(
+                title="Feedback",
+                fields=[
+                    RatingField(
+                        name="overall_rating",
+                        label="Overall rating",
+                        max_rating=10,
+                    ),
+                    ColorField(
+                        name="fav_color",
+                        label="Favourite colour",
+                        color_format="rgb",
+                    ),
+                ],
+            ),
+        ],
+    )
+
+    print(f"Form: {form.name}")
+    print(f"Total fields: {len(form.fields)}")
+    for f in form.fields:
+        print(f"  - {f.name} ({f.field_type_value})")
+    print()
+    return form
+
+
+def json_roundtrip(form: Form):
+    """Serialize a form to JSON and back, preserving custom field data."""
+    print("=" * 60)
+    print("JSON roundtrip")
+    print("=" * 60)
+
+    json_str = form.to_json()
+    print("Serialized JSON (pretty):")
+    print(json.dumps(json.loads(json_str), indent=2))
+    print()
+
+    restored = Form.loads(json_str)
+    print("Restored form fields:")
+    for f in restored.fields:
+        extra = ""
+        if isinstance(f, PhoneField):
+            extra = f" (country_code={f.country_code})"
+        elif isinstance(f, RatingField):
+            extra = f" (max_rating={f.max_rating})"
+        elif isinstance(f, ColorField):
+            extra = f" (color_format={f.color_format})"
+        print(f"  - {f.name}: {type(f).__name__}{extra}")
+    print()
+
+
+def validate_custom_form(form: Form):
+    """Validate user data against a form with custom fields."""
+    print("=" * 60)
+    print("Data validation")
+    print("=" * 60)
+
+    data = {
+        "name": "Juan",
+        "email": "juan@example.com",
+        "phone": "+54-11-5555-0100",
+        "overall_rating": "8",
+        "fav_color": "#3498db",
+    }
+    result = form.validate_data(data)
+    print(f"Input:   {data}")
+    print(f"Result:  success={result['success']}")
+    if result.get("errors"):
+        print(f"Errors:  {result['errors']}")
+    print()
+
+
+def export_html(form: Form):
+    """Export the form to plain HTML."""
+    print("=" * 60)
+    print("HTML export")
+    print("=" * 60)
+    export = form.export("html")
+    print(export["output"][:500], "...")
+    print()
+
+
+# ---------------------------------------------------------------------------
+# Run all examples
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    show_registered_types()
+    form = create_form_with_custom_fields()
+    json_roundtrip(form)
+    validate_custom_form(form)
+    export_html(form)

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)}")