- Refactor code structure for improved readability and maintainability

- Support for Python 3.9+
- **Custom field type registry**: Allow registering custom field types without modifying the hardcoded `Union` in `Form.content`. Provide a `register_field_type()` API.

Author: Juan Pablo Manson

.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: |

.gitignore

@@ -14,7 +14,8 @@ todo
 CLAUDE.md
 .claude
 
-# Caches
+# Caches and temps
 .uv-cache
 .pytest_cache
-__pycache__/
+__pycache__/
+.tmp

.python-version

@@ -1 +1 @@
-3.12
+3.11

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

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)

pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "codeforms"
-version = "0.1.0"
+version = "0.1.1"
 description = "Python library for creating, validating, and rendering web forms using Pydantic"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.9"
 license = "MIT"
 dependencies = [
     "pydantic[email]>=2.0",

src/codeforms/__init__.py

@@ -28,3 +28,7 @@
     register_locale,
     get_messages,
 )
+from codeforms.registry import (
+    register_field_type,
+    get_registered_field_types,
+)

src/codeforms/export.py

@@ -205,14 +205,14 @@ def field_to_html(field: FormFieldBase, **kwargs) -> str:
     skip_label = ['hidden']
 
     label_html = ''
-    if field.field_type.value not in skip_label:
+    if field.field_type_value not in skip_label:
         label_class = "form-label" if is_bootstrap else ""
         label_html = f'<label class="{label_class}" for="{field.id}">{field.label}</label>'
 
     help_html = f'<small class="{help_text_class}">{field.help_text}</small>' if field.help_text else ""
 
     # Manejar campos SELECT de manera especial
-    if field.field_type.value == 'select':
+    if field.field_type_value == 'select':
         select_attrs = {
             "id": str(field.id),
             "name": field.name,
@@ -240,7 +240,7 @@ def field_to_html(field: FormFieldBase, **kwargs) -> str:
         input_html = f'<select {attrs_str}>{options_html}</select>'
 
     # Manejar campos RADIO de manera especial
-    elif field.field_type.value == 'radio':
+    elif field.field_type_value == 'radio':
         radio_html_parts = []
         if hasattr(field, 'options'):
             for option in field.options:
@@ -265,7 +265,7 @@ def field_to_html(field: FormFieldBase, **kwargs) -> str:
         input_html = '<div class="radio-group">' + ''.join(radio_html_parts) + '</div>'
 
     # Manejar campos CHECKBOX con opciones múltiples
-    elif field.field_type.value == 'checkbox' and hasattr(field, 'options'):
+    elif field.field_type_value == 'checkbox' and hasattr(field, 'options'):
         checkbox_html_parts = []
         for option in field.options:
             checkbox_attrs = {
@@ -293,7 +293,7 @@ def field_to_html(field: FormFieldBase, **kwargs) -> str:
         attributes = {
             "id": str(field.id),
             "name": field.name,
-            "type": field.field_type.value,
+            "type": field.field_type_value,
             "class": f"{base_input_class} {field.css_classes or ''}".strip(),
             "placeholder": field.placeholder or "",
         }
@@ -308,7 +308,7 @@ def field_to_html(field: FormFieldBase, **kwargs) -> str:
             attributes["value"] = str(field.default_value)
 
         # Para checkbox simple, manejar el atributo checked
-        if field.field_type.value == 'checkbox' and hasattr(field, 'checked') and field.checked:
+        if field.field_type_value == 'checkbox' and hasattr(field, 'checked') and field.checked:
             attributes["checked"] = "checked"
 
         # Agregar atributos personalizados