codeforms 0.2.0__tar.gz → 0.2.1__tar.gz

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

@@ -15,6 +15,8 @@ info
 # Agents
 CLAUDE.md
 .claude
+.agents
+knowledge.md
 
 # Caches and temps
 .uv-cache

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codeforms
-Version: 0.2.0
+Version: 0.2.1
 Summary: Python library for creating, validating, and rendering web forms using Pydantic
 License-Expression: MIT
 License-File: LICENSE
@@ -8,6 +8,7 @@ Requires-Python: >=3.9
 Requires-Dist: pydantic[email]>=2.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # codeforms
@@ -179,11 +180,115 @@ print(dict_output)
 | `html` | Semantic HTML |
 | `html_bootstrap4` | HTML with Bootstrap 4 classes |
 | `html_bootstrap5` | HTML with Bootstrap 5 classes |
+| `json_schema` | [JSON Schema](http://json-schema.org/draft-07/schema#) (draft-07) |
 | `json` | JSON representation of the form |
 | `dict` | Python dictionary representation |
 
 HTML export can also generate a `<script>` block for basic client-side validation.
 
+### JSON Schema Export
+
+Generate a standard [JSON Schema (draft-07)](http://json-schema.org/draft-07/schema#) from any form. The resulting schema is compatible with tools like [React JSON Schema Form](https://github.com/rjsf-team/react-jsonschema-form), [Angular Formly](https://formly.dev/), and any JSON Schema validator.
+
+```python
+import json
+from codeforms import (
+    Form, TextField, EmailField, NumberField, SelectField, SelectOption,
+    CheckboxField, form_to_json_schema,
+)
+
+form = Form(
+    name="registration",
+    fields=[
+        TextField(name="name", label="Full Name", required=True, minlength=2, maxlength=100),
+        EmailField(name="email", label="Email", required=True),
+        NumberField(name="age", label="Age", min_value=18, max_value=120),
+        SelectField(
+            name="country",
+            label="Country",
+            required=True,
+            options=[
+                SelectOption(value="us", label="United States"),
+                SelectOption(value="uk", label="United Kingdom"),
+            ],
+        ),
+        CheckboxField(name="terms", label="Accept Terms", required=True),
+    ],
+)
+
+# Option 1: Direct function call
+schema = form_to_json_schema(form)
+print(json.dumps(schema, indent=2))
+
+# Option 2: Via form.export()
+result = form.export("json_schema")
+schema = result["output"]
+```
+
+Output:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "registration",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 100,
+      "title": "Full Name"
+    },
+    "email": {
+      "type": "string",
+      "format": "email",
+      "title": "Email"
+    },
+    "age": {
+      "type": "number",
+      "minimum": 18,
+      "maximum": 120,
+      "title": "Age"
+    },
+    "country": {
+      "type": "string",
+      "enum": ["us", "uk"],
+      "title": "Country"
+    },
+    "terms": {
+      "type": "boolean",
+      "title": "Accept Terms"
+    }
+  },
+  "required": ["name", "email", "country", "terms"],
+  "additionalProperties": false
+}
+```
+
+#### Field Type Mapping
+
+| codeforms Field | JSON Schema Type | Extra Keywords |
+|---|---|---|
+| `TextField` | `string` | `minLength`, `maxLength`, `pattern` |
+| `EmailField` | `string` (`format: "email"`) | — |
+| `NumberField` | `number` | `minimum`, `maximum`, `multipleOf` |
+| `DateField` | `string` (`format: "date"`) | — |
+| `SelectField` | `string` + `enum` | — |
+| `SelectField` (`multiple=True`) | `array` of `enum` strings | `minItems`, `maxItems`, `uniqueItems` |
+| `RadioField` | `string` + `enum` | — |
+| `CheckboxField` | `boolean` | — |
+| `CheckboxGroupField` | `array` of `enum` strings | `uniqueItems` |
+| `FileField` | `string` (`contentEncoding: "base64"`) | — |
+| `FileField` (`multiple=True`) | `array` of base64 strings | — |
+| `HiddenField` | `string` | — |
+| `UrlField` | `string` (`format: "uri"`) | `minLength`, `maxLength` |
+| `TextareaField` | `string` | `minLength`, `maxLength` |
+| `ListField` | `array` | `minItems`, `maxItems` |
+
+Field annotations like `label`, `help_text`, `default_value`, and `readonly` map to the JSON Schema keywords `title`, `description`, `default`, and `readOnly` respectively.
+
+Fields inside `FieldGroup` and `FormStep` containers are flattened into the top-level `properties` automatically.
+
 ## Internationalization (i18n)
 
 All validation and export messages are locale-aware. **English** (`en`) and **Spanish** (`es`) are included out of the box, and you can register any additional language at runtime via `register_locale()`.
@@ -258,6 +363,159 @@ print(result["errors"][0]["message"])  # "El campo name es requerido"
 
 See [`examples/i18n_usage.py`](examples/i18n_usage.py) for a full working example.
 
+## Dynamic Forms
+
+### Conditional Visibility
+
+Fields can be shown or hidden based on the value of other fields using `visible_when`. This is metadata that your frontend can use for dynamic UI, and the backend can respect during validation.
+
+```python
+from codeforms import Form, TextField, SelectField, SelectOption, VisibilityRule
+
+form = Form(
+    name="address",
+    fields=[
+        SelectField(
+            name="country",
+            label="Country",
+            required=True,
+            options=[
+                SelectOption(value="US", label="United States"),
+                SelectOption(value="AR", label="Argentina"),
+            ],
+        ),
+        TextField(
+            name="state",
+            label="State",
+            required=True,
+            visible_when=[
+                VisibilityRule(field="country", operator="equals", value="US"),
+            ],
+        ),
+        TextField(
+            name="province",
+            label="Province",
+            required=True,
+            visible_when=[
+                VisibilityRule(field="country", operator="equals", value="AR"),
+            ],
+        ),
+    ],
+)
+```
+
+Supported operators: `equals`, `not_equals`, `in`, `not_in`, `gt`, `lt`, `is_empty`, `is_not_empty`.
+
+#### Dynamic Validation
+
+Use `validate_form_data_dynamic()` to validate only the fields that are currently visible:
+
+```python
+from codeforms import validate_form_data_dynamic
+
+result = validate_form_data_dynamic(
+    form,
+    {"country": "US", "state": "California"},
+    respect_visibility=True,
+)
+print(result["success"])  # True — "province" is hidden, so not required
+```
+
+The legacy `validate_form_data()` function is unchanged and always validates all fields regardless of visibility.
+
+#### Checking Visible Fields
+
+```python
+visible = form.get_visible_fields({"country": "US"})
+print([f.name for f in visible])  # ["country", "state"]
+```
+
+See [`examples/conditional_visibility.py`](examples/conditional_visibility.py) for a full working example.
+
+### Dependent Options
+
+Use `DependentOptionsConfig` to define option sets that change based on another field's value:
+
+```python
+from codeforms import SelectField, SelectOption, DependentOptionsConfig
+
+city_field = SelectField(
+    name="city",
+    label="City",
+    options=[  # all possible options (for static HTML rendering)
+        SelectOption(value="nyc", label="New York City"),
+        SelectOption(value="bsas", label="Buenos Aires"),
+    ],
+    dependent_options=DependentOptionsConfig(
+        depends_on="country",
+        options_map={
+            "US": [SelectOption(value="nyc", label="New York City")],
+            "AR": [SelectOption(value="bsas", label="Buenos Aires")],
+        },
+    ),
+)
+```
+
+The `dependent_options` metadata serializes to JSON for your frontend to consume. See [`examples/dependent_options.py`](examples/dependent_options.py).
+
+## Multi-Step Wizard Forms
+
+Use `FormStep` to split a form into multiple steps. Each step contains its own fields and can be validated independently.
+
+```python
+from codeforms import Form, FormStep, TextField, EmailField, CheckboxField
+
+form = Form(
+    name="registration",
+    content=[
+        FormStep(
+            title="Personal Information",
+            description="Tell us about yourself",
+            content=[
+                TextField(name="name", label="Name", required=True),
+                EmailField(name="email", label="Email", required=True),
+            ],
+        ),
+        FormStep(
+            title="Confirmation",
+            content=[
+                CheckboxField(name="terms", label="I accept the terms", required=True),
+            ],
+            validation_mode="on_submit",
+        ),
+    ],
+)
+```
+
+### Step Validation
+
+```python
+# Validate a single step
+result = form.validate_step(0, {"name": "John", "email": "john@example.com"})
+print(result["success"])  # True
+
+# Validate all steps at once
+result = form.validate_all_steps({
+    "name": "John",
+    "email": "john@example.com",
+    "terms": True,
+})
+print(result["success"])  # True
+```
+
+### Wizard Helpers
+
+```python
+steps = form.get_steps()       # List[FormStep]
+fields = form.fields           # Flat list of all fields across all steps
+```
+
+### HTML Export
+
+Wizard forms export with `data-wizard="true"` on the `<form>` tag. Each step renders as a `<section data-step="true">` (not `<fieldset>`), so you can wire up your own step navigation in JavaScript.
+
+See [`examples/wizard_form.py`](examples/wizard_form.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.

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

@@ -167,11 +167,115 @@ print(dict_output)
 | `html` | Semantic HTML |
 | `html_bootstrap4` | HTML with Bootstrap 4 classes |
 | `html_bootstrap5` | HTML with Bootstrap 5 classes |
+| `json_schema` | [JSON Schema](http://json-schema.org/draft-07/schema#) (draft-07) |
 | `json` | JSON representation of the form |
 | `dict` | Python dictionary representation |
 
 HTML export can also generate a `<script>` block for basic client-side validation.
 
+### JSON Schema Export
+
+Generate a standard [JSON Schema (draft-07)](http://json-schema.org/draft-07/schema#) from any form. The resulting schema is compatible with tools like [React JSON Schema Form](https://github.com/rjsf-team/react-jsonschema-form), [Angular Formly](https://formly.dev/), and any JSON Schema validator.
+
+```python
+import json
+from codeforms import (
+    Form, TextField, EmailField, NumberField, SelectField, SelectOption,
+    CheckboxField, form_to_json_schema,
+)
+
+form = Form(
+    name="registration",
+    fields=[
+        TextField(name="name", label="Full Name", required=True, minlength=2, maxlength=100),
+        EmailField(name="email", label="Email", required=True),
+        NumberField(name="age", label="Age", min_value=18, max_value=120),
+        SelectField(
+            name="country",
+            label="Country",
+            required=True,
+            options=[
+                SelectOption(value="us", label="United States"),
+                SelectOption(value="uk", label="United Kingdom"),
+            ],
+        ),
+        CheckboxField(name="terms", label="Accept Terms", required=True),
+    ],
+)
+
+# Option 1: Direct function call
+schema = form_to_json_schema(form)
+print(json.dumps(schema, indent=2))
+
+# Option 2: Via form.export()
+result = form.export("json_schema")
+schema = result["output"]
+```
+
+Output:
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "title": "registration",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 100,
+      "title": "Full Name"
+    },
+    "email": {
+      "type": "string",
+      "format": "email",
+      "title": "Email"
+    },
+    "age": {
+      "type": "number",
+      "minimum": 18,
+      "maximum": 120,
+      "title": "Age"
+    },
+    "country": {
+      "type": "string",
+      "enum": ["us", "uk"],
+      "title": "Country"
+    },
+    "terms": {
+      "type": "boolean",
+      "title": "Accept Terms"
+    }
+  },
+  "required": ["name", "email", "country", "terms"],
+  "additionalProperties": false
+}
+```
+
+#### Field Type Mapping
+
+| codeforms Field | JSON Schema Type | Extra Keywords |
+|---|---|---|
+| `TextField` | `string` | `minLength`, `maxLength`, `pattern` |
+| `EmailField` | `string` (`format: "email"`) | — |
+| `NumberField` | `number` | `minimum`, `maximum`, `multipleOf` |
+| `DateField` | `string` (`format: "date"`) | — |
+| `SelectField` | `string` + `enum` | — |
+| `SelectField` (`multiple=True`) | `array` of `enum` strings | `minItems`, `maxItems`, `uniqueItems` |
+| `RadioField` | `string` + `enum` | — |
+| `CheckboxField` | `boolean` | — |
+| `CheckboxGroupField` | `array` of `enum` strings | `uniqueItems` |
+| `FileField` | `string` (`contentEncoding: "base64"`) | — |
+| `FileField` (`multiple=True`) | `array` of base64 strings | — |
+| `HiddenField` | `string` | — |
+| `UrlField` | `string` (`format: "uri"`) | `minLength`, `maxLength` |
+| `TextareaField` | `string` | `minLength`, `maxLength` |
+| `ListField` | `array` | `minItems`, `maxItems` |
+
+Field annotations like `label`, `help_text`, `default_value`, and `readonly` map to the JSON Schema keywords `title`, `description`, `default`, and `readOnly` respectively.
+
+Fields inside `FieldGroup` and `FormStep` containers are flattened into the top-level `properties` automatically.
+
 ## Internationalization (i18n)
 
 All validation and export messages are locale-aware. **English** (`en`) and **Spanish** (`es`) are included out of the box, and you can register any additional language at runtime via `register_locale()`.
@@ -246,6 +350,159 @@ print(result["errors"][0]["message"])  # "El campo name es requerido"
 
 See [`examples/i18n_usage.py`](examples/i18n_usage.py) for a full working example.
 
+## Dynamic Forms
+
+### Conditional Visibility
+
+Fields can be shown or hidden based on the value of other fields using `visible_when`. This is metadata that your frontend can use for dynamic UI, and the backend can respect during validation.
+
+```python
+from codeforms import Form, TextField, SelectField, SelectOption, VisibilityRule
+
+form = Form(
+    name="address",
+    fields=[
+        SelectField(
+            name="country",
+            label="Country",
+            required=True,
+            options=[
+                SelectOption(value="US", label="United States"),
+                SelectOption(value="AR", label="Argentina"),
+            ],
+        ),
+        TextField(
+            name="state",
+            label="State",
+            required=True,
+            visible_when=[
+                VisibilityRule(field="country", operator="equals", value="US"),
+            ],
+        ),
+        TextField(
+            name="province",
+            label="Province",
+            required=True,
+            visible_when=[
+                VisibilityRule(field="country", operator="equals", value="AR"),
+            ],
+        ),
+    ],
+)
+```
+
+Supported operators: `equals`, `not_equals`, `in`, `not_in`, `gt`, `lt`, `is_empty`, `is_not_empty`.
+
+#### Dynamic Validation
+
+Use `validate_form_data_dynamic()` to validate only the fields that are currently visible:
+
+```python
+from codeforms import validate_form_data_dynamic
+
+result = validate_form_data_dynamic(
+    form,
+    {"country": "US", "state": "California"},
+    respect_visibility=True,
+)
+print(result["success"])  # True — "province" is hidden, so not required
+```
+
+The legacy `validate_form_data()` function is unchanged and always validates all fields regardless of visibility.
+
+#### Checking Visible Fields
+
+```python
+visible = form.get_visible_fields({"country": "US"})
+print([f.name for f in visible])  # ["country", "state"]
+```
+
+See [`examples/conditional_visibility.py`](examples/conditional_visibility.py) for a full working example.
+
+### Dependent Options
+
+Use `DependentOptionsConfig` to define option sets that change based on another field's value:
+
+```python
+from codeforms import SelectField, SelectOption, DependentOptionsConfig
+
+city_field = SelectField(
+    name="city",
+    label="City",
+    options=[  # all possible options (for static HTML rendering)
+        SelectOption(value="nyc", label="New York City"),
+        SelectOption(value="bsas", label="Buenos Aires"),
+    ],
+    dependent_options=DependentOptionsConfig(
+        depends_on="country",
+        options_map={
+            "US": [SelectOption(value="nyc", label="New York City")],
+            "AR": [SelectOption(value="bsas", label="Buenos Aires")],
+        },
+    ),
+)
+```
+
+The `dependent_options` metadata serializes to JSON for your frontend to consume. See [`examples/dependent_options.py`](examples/dependent_options.py).
+
+## Multi-Step Wizard Forms
+
+Use `FormStep` to split a form into multiple steps. Each step contains its own fields and can be validated independently.
+
+```python
+from codeforms import Form, FormStep, TextField, EmailField, CheckboxField
+
+form = Form(
+    name="registration",
+    content=[
+        FormStep(
+            title="Personal Information",
+            description="Tell us about yourself",
+            content=[
+                TextField(name="name", label="Name", required=True),
+                EmailField(name="email", label="Email", required=True),
+            ],
+        ),
+        FormStep(
+            title="Confirmation",
+            content=[
+                CheckboxField(name="terms", label="I accept the terms", required=True),
+            ],
+            validation_mode="on_submit",
+        ),
+    ],
+)
+```
+
+### Step Validation
+
+```python
+# Validate a single step
+result = form.validate_step(0, {"name": "John", "email": "john@example.com"})
+print(result["success"])  # True
+
+# Validate all steps at once
+result = form.validate_all_steps({
+    "name": "John",
+    "email": "john@example.com",
+    "terms": True,
+})
+print(result["success"])  # True
+```
+
+### Wizard Helpers
+
+```python
+steps = form.get_steps()       # List[FormStep]
+fields = form.fields           # Flat list of all fields across all steps
+```
+
+### HTML Export
+
+Wizard forms export with `data-wizard="true"` on the `<form>` tag. Each step renders as a `<section data-step="true">` (not `<fieldset>`), so you can wire up your own step navigation in JavaScript.
+
+See [`examples/wizard_form.py`](examples/wizard_form.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.

{codeforms-0.2.0 → codeforms-0.2.1}/examples/basic_usage.py

@@ -6,14 +6,14 @@ and HTML export.
 """
 
 from codeforms import (
-    Form,
-    TextField,
-    EmailField,
-    SelectField,
     CheckboxField,
     CheckboxGroupField,
+    EmailField,
+    Form,
     RadioField,
+    SelectField,
     SelectOption,
+    TextField,
     ValidationRule,
     validate_form_data,
 )
@@ -205,7 +205,9 @@ if __name__ == "__main__":
         ],
     )
 
-    contact_form.set_default_values(data={"name": "John Doe", "email": "john@example.com"})
+    contact_form.set_default_values(
+        data={"name": "John Doe", "email": "john@example.com"}
+    )
 
     # Export as Bootstrap 4 HTML
     print(contact_form.export(output_format="html_bootstrap4", id="my_form"))

{codeforms-0.2.0 → codeforms-0.2.1}/examples/conditional_visibility.py

@@ -7,9 +7,9 @@ y la diferencia entre validación legacy y dinámica.
 
 from codeforms import (
     Form,
-    TextField,
     SelectField,
     SelectOption,
+    TextField,
     VisibilityRule,
     validate_form_data,
     validate_form_data_dynamic,
@@ -79,7 +79,9 @@ if __name__ == "__main__":
     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)")
+        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) ===")

{codeforms-0.2.0 → codeforms-0.2.1}/examples/custom_fields.py

@@ -11,22 +11,23 @@ from typing import Optional
 from pydantic import field_validator
 
 from codeforms import (
+    EmailField,
+    FieldGroup,
     Form,
     FormFieldBase,
-    FieldGroup,
     TextField,
-    EmailField,
-    register_field_type,
     get_registered_field_types,
+    register_field_type,
 )
 
-
 # ---------------------------------------------------------------------------
 # 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"
@@ -34,6 +35,7 @@ class PhoneField(FormFieldBase):
 
 class RatingField(FormFieldBase):
     """A numeric rating field with configurable range."""
+
     field_type: str = "rating"
     min_rating: int = 1
     max_rating: int = 5
@@ -49,6 +51,7 @@ class RatingField(FormFieldBase):
 
 class ColorField(FormFieldBase):
     """A colour picker field."""
+
     field_type: str = "color"
     color_format: str = "hex"  # hex | rgb | hsl
 

{codeforms-0.2.0 → codeforms-0.2.1}/examples/dependent_options.py

@@ -6,10 +6,10 @@ de otro campo (por ejemplo, país → ciudades).
 """
 
 from codeforms import (
+    DependentOptionsConfig,
     Form,
     SelectField,
     SelectOption,
-    DependentOptionsConfig,
 )
 
 
@@ -62,6 +62,7 @@ if __name__ == "__main__":
 
     # 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:")