Metadata-Version: 2.4
Name: cjm-fasthtml-jsonschema
Version: 0.0.7
Summary: Library for generating FastHTML user interfaces from JSON Schema configurations.
Home-page: https://github.com/cj-mills/cjm-fasthtml-jsonschema
Author: Christian J. Mills
Author-email: 9126128+cj-mills@users.noreply.github.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: python-fasthtml
Requires-Dist: cjm-fasthtml-daisyui
Requires-Dist: jsonschema
Provides-Extra: dev
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cjm-fasthtml-jsonschema


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm_fasthtml_jsonschema
```

## Demo Application

Run the demo to see the library in action:

``` bash
python demo_app.py
```

Then visit:

- http://localhost:5001/ - Demo page with example form from
  `./test_files/`

``` bash
$ python ./demo_app.py -h
usage: demo_app.py [-h] [--schema SCHEMA] [--port PORT] [--host HOST]

JSON Schema to UI Demo Application

options:
  -h, --help       show this help message and exit
  --schema SCHEMA  Path to the JSON schema file (default: test_files/voxtral_config_schema.json)
  --port PORT      Port to run the server on (default: 5001)
  --host HOST      Host to run the server on (default: 0.0.0.0)
```

## Project Structure

    nbs/
    ├── components/ (1)
    │   └── fields.ipynb  # Field component generators for different JSON Schema types.
    ├── core/ (3)
    │   ├── dataclass.ipynb  # Dataclass-to-JSON-schema conversion utilities for form generation
    │   ├── parser.ipynb     # JSON Schema parsing utilities.
    │   └── types.ipynb      # Type definitions for JSON Schema elements.
    └── generators/ (1)
        └── form.ipynb  # Main form generator that creates UI from JSON Schema.

Total: 5 notebooks across 3 directories

## Module Dependencies

``` mermaid
graph LR
    components_fields[components.fields<br/>fields]
    core_dataclass[core.dataclass<br/>Dataclass Utilities]
    core_parser[core.parser<br/>parser]
    core_types[core.types<br/>types]
    generators_form[generators.form<br/>form]

    components_fields --> core_types
    core_parser --> core_types
    generators_form --> core_parser
    generators_form --> components_fields
```

*4 cross-module dependencies detected*

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### Dataclass Utilities (`dataclass.ipynb`)

> Dataclass-to-JSON-schema conversion utilities for form generation

#### Import

``` python
from cjm_fasthtml_jsonschema.core.dataclass import (
    SCHEMA_TITLE,
    SCHEMA_DESC,
    SCHEMA_MIN,
    SCHEMA_MAX,
    SCHEMA_ENUM,
    SCHEMA_MIN_LEN,
    SCHEMA_MAX_LEN,
    SCHEMA_PATTERN,
    SCHEMA_FORMAT,
    dataclass_to_jsonschema
)
```

#### Functions

``` python
def _python_type_to_json_type(
    python_type: type  # Python type annotation to convert
) -> Dict[str, Any]:  # JSON schema type definition
    "Convert Python type to JSON schema type."
```

``` python
def dataclass_to_jsonschema(
    cls: type  # Dataclass with field metadata
) -> Dict[str, Any]:  # JSON schema dictionary
    "Convert a dataclass to a JSON schema for form generation."
```

#### Variables

``` python
SCHEMA_TITLE = 'title'  # Display title for the field
SCHEMA_DESC = 'description'  # Help text description
SCHEMA_MIN = 'minimum'  # Minimum value for numbers
SCHEMA_MAX = 'maximum'  # Maximum value for numbers
SCHEMA_ENUM = 'enum'  # Allowed values for dropdowns
SCHEMA_MIN_LEN = 'minLength'  # Minimum string length
SCHEMA_MAX_LEN = 'maxLength'  # Maximum string length
SCHEMA_PATTERN = 'pattern'  # Regex pattern for strings
SCHEMA_FORMAT = 'format'  # String format (email, uri, date, etc.)
```

### fields (`fields.ipynb`)

> Field component generators for different JSON Schema types.

#### Import

``` python
from cjm_fasthtml_jsonschema.components.fields import (
    create_label,
    create_description,
    create_string_field,
    create_enum_field,
    create_number_field,
    create_range_field,
    create_boolean_field,
    create_field
)
```

#### Functions

``` python
def create_label(
    prop: SchemaProperty  # SchemaProperty object
) -> FT:  # Label component
    "Create a label for a field."
```

``` python
def create_description(
    prop: SchemaProperty  # SchemaProperty object
) -> Optional[FT]:  # P component with description or None
    "Create a description/help text for a field."
```

``` python
def create_string_field(
    prop: SchemaProperty,  # SchemaProperty object
    value: Any = None  # Current value
) -> FT:  # Div containing the field
    "Create a string input field."
```

``` python
def create_enum_field(
    prop: SchemaProperty,  # SchemaProperty object
    value: Any = None  # Current value
) -> FT:  # Div containing the field
    "Create an enum select dropdown field."
```

``` python
def create_number_field(
    prop: SchemaProperty,  # SchemaProperty object
    value: Any = None  # Current value
) -> FT:  # Div containing the field
    "Create a number input field."
```

``` python
def create_range_field(
    prop: SchemaProperty,  # SchemaProperty object
    value: Any = None  # Current value
) -> FT:  # Div containing the field
    "Create a range slider field."
```

``` python
def create_boolean_field(
    prop: SchemaProperty,  # SchemaProperty object
    value: Any = None  # Current value
) -> FT:  # Div containing the field
    "Create a boolean toggle field."
```

``` python
def create_field(
    prop: SchemaProperty,  # SchemaProperty object
    value: Any = None  # Current value
) -> FT:  # Div containing the field
    "Create an appropriate field based on the property type."
```

### form (`form.ipynb`)

> Main form generator that creates UI from JSON Schema.

#### Import

``` python
from cjm_fasthtml_jsonschema.generators.form import (
    generate_form_ui
)
```

#### Functions

``` python
def generate_form_ui(
    schema: Dict[str, Any],  # JSON Schema dictionary
    values: Optional[Dict[str, Any]] = None,  # Optional dictionary of current values
    show_title: bool = True,  # Whether to show the schema title
    show_description: bool = True,  # Whether to show schema description
    compact: bool = False,  # Use compact layout (less spacing)
    card_wrapper: bool = True  # Wrap the form in a card component
) -> FT:  # FastHTML component containing the generated form UI
    "Generate a FastHTML form UI from a JSON Schema."
```

### parser (`parser.ipynb`)

> JSON Schema parsing utilities.

#### Import

``` python
from cjm_fasthtml_jsonschema.core.parser import (
    SchemaParser
)
```

#### Classes

``` python
class SchemaParser:
    def __init__(
        self,
        schema: Dict[str, Any]  # JSON Schema dictionary
    )
    "Parse JSON Schema and extract property information."
    
    def __init__(
            self,
            schema: Dict[str, Any]  # JSON Schema dictionary
        )
        "Initialize parser with a JSON Schema."
    
    def get_property(
            self,
            name: str  # Property name
        ) -> Optional[SchemaProperty]:  # SchemaProperty object or None if not found
        "Get a specific property by name."
    
    def get_required_properties(
            self
        ) -> List[SchemaProperty]:  # List of all required SchemaProperty objects
        "Get all required properties."
    
    def get_optional_properties(
            self
        ) -> List[SchemaProperty]:  # List of all optional SchemaProperty objects
        "Get all optional properties."
```

### types (`types.ipynb`)

> Type definitions for JSON Schema elements.

#### Import

``` python
from cjm_fasthtml_jsonschema.core.types import (
    SchemaProperty
)
```

#### Classes

``` python
@dataclass
class SchemaProperty:
    "Represents a single property in a JSON Schema."
    
    name: str
    schema: Dict[str, Any]
    required: bool = False
    value: Any
    
    def type(
            self
        ) -> str:  # The property's type (e.g., 'string', 'number', 'boolean')
        "Get the property type."
    
    def is_nullable(
            self
        ) -> bool:  # True if the property allows null values
        "Check if property allows null values."
    
    def default(
            self
        ) -> Any:  # The default value for this property, or None if not specified
        "Get default value if specified."
    
    def description(
            self
        ) -> Optional[str]:  # The property's description text, or None if not provided
        "Get property description."
    
    def enum_values(
            self
        ) -> Optional[List[Any]]:  # List of allowed enum values, or None if not an enum
        "Get enum values if property is an enum."
    
    def examples(
            self
        ) -> Optional[List[Any]]:  # List of example values, or None if not provided
        "Get example values if provided."
    
    def minimum(
            self
        ) -> Optional[Union[int, float]]:  # Minimum allowed value for numeric types, or None if not specified
        "Get minimum value for numeric types."
    
    def maximum(
            self
        ) -> Optional[Union[int, float]]:  # Maximum allowed value for numeric types, or None if not specified
        "Get maximum value for numeric types."
    
    def min_length(
            self
        ) -> Optional[int]:  # Minimum length for string types, or None if not specified
        "Get minimum length for string types."
    
    def max_length(
            self
        ) -> Optional[int]:  # Maximum length for string types, or None if not specified
        "Get maximum length for string types."
    
    def pattern(
            self
        ) -> Optional[str]:  # Regex pattern for string validation, or None if not specified
        "Get regex pattern for string validation."
    
    def format(
            self
        ) -> Optional[str]:  # Format hint (e.g., 'email', 'uri', 'date'), or None if not specified
        "Get format hint (e.g., 'email', 'uri', 'date')."
```
