UI Helper Modules¶

The UI layer is organized into focused helper modules that handle specific concerns. This separation improves testability and reduces coupling in the route handlers. The submodules live under the metaseed.ui.helpers package, whose __init__ re-exports their public functions for convenient access.

graph TD
    Routes[Route Handlers] --> H[metaseed.ui.helpers]
    H --> EH[entity_helpers]
    H --> TH[table_helpers]
    H --> NH[navigation_helpers]
    H --> FC[FormContext<br/>from metaseed.forms]

    EH --> State[AppState]
    TH --> State
    NH --> State
    FC --> State

Hold "Alt" / "Option" to enable pan & zoom

Form rendering¶

Form rendering context and value collection are exposed through the metaseed.ui.helpers package.

FormContext¶

Dataclass that encapsulates form rendering state, reducing parameter counts in template rendering. It is defined in metaseed.forms and re-exported from metaseed.ui.helpers.

from metaseed.ui.helpers import FormContext

ctx = FormContext(
    entity_type="Study",
    helper=facade.Study,
    values={"title": "My Study"},
    node_id="abc123",  # None for create forms
)

# Access field categories
required = ctx.get_required_fields()
optional = ctx.get_optional_fields()
nested = ctx.get_nested_fields()

Property	Description
`is_edit`	True if editing existing entity
`description`	Entity description from spec
`ontology_term`	Ontology term from spec

Functions¶

Function	Purpose
`collect_form_values(form_data, helper)`	Extract typed values from form submission
`filter_fields(fields, ...)`	Filter field list by required/nested criteria
`get_field_data(helper)`	Get field metadata for template rendering
`is_nested_field(field)`	Check if field dict represents nested entity
`format_validation_errors(e)`	Convert ValidationError to user-friendly messages

entity_helpers¶

Handles entity traversal and nested item extraction.

Functions¶

Function	Purpose
`to_dict(item)`	Convert Pydantic model or dict to plain dict
`walk_nested_entities(data, entity_type, facade)`	Recursively traverse nested entities, yielding (type, data) tuples
`extract_nested_items(instance, helper)`	Extract nested items from instance as dict mapping
`collect_entities_by_type(state, facade)`	Collect all entities (root and nested) organized by type

Example: Walking Nested Entities¶

from metaseed.ui.helpers.entity_helpers import walk_nested_entities

investigation_data = {
    "unique_id": "INV-1",
    "studies": [
        {"unique_id": "STU-1", "observation_units": [...]}
    ]
}

for entity_type, data in walk_nested_entities(investigation_data, "Investigation", facade):
    print(f"{entity_type}: {data.get('unique_id')}")
# Output:
# Study: STU-1
# ObservationUnit: ...

table_helpers¶

Handles inline table building for nested entity display.

Functions¶

Function	Purpose
`get_table_columns(facade, entity_type)`	Get column names for table (excludes nested fields)
`get_table_column_info(facade, entity_type)`	Get complete column metadata (types, constraints, required)
`build_inline_tables(state, facade, entity_type)`	Build table data for all nested fields of an entity
`get_items_store(state, parent_type, field_name)`	Get correct items store based on nested edit context
`format_table_rows(items)`	Format items list for table row rendering

Table Column Info¶

get_table_column_info returns a dictionary with:

Key	Type	Description
`columns`	`list[str]`	Column names to display
`column_types`	`dict[str, str]`	Field type per column
`column_constraints`	`dict[str, dict]`	Constraints per column
`required_columns`	`set[str]`	Required field names
`has_nested_children`	`bool`	Whether entity has nested children

navigation_helpers¶

Handles breadcrumb building and reference field resolution.

Functions¶

Function	Purpose
`build_breadcrumb(state)`	Build breadcrumb navigation from nested edit stack
`error_response(request, templates, message)`	Create error response with notification template
`get_reference_fields(profile, version, entity_type)`	Get all reference fields for an entity type
`get_parent_id_fields(reference_fields, parent_type)`	Get fields that reference the parent entity
`get_parent_identifier(state, parent_type, target_field)`	Get parent entity's identifier value

Reference Field Resolution¶

Reference fields link entities to their parents. The helper checks two sources:

Field definitions with parent_ref attribute (e.g., parent_ref: Study.identifier)
Validation rules with reference attribute (legacy)

from metaseed.ui.helpers.navigation_helpers import get_reference_fields

refs = get_reference_fields("miappe", "1.2", "Sample")
# Returns:
# {
#     "observation_unit_id": {
#         "target_entity": "ObservationUnit",
#         "target_field": "unique_id"
#     }
# }

Module Dependencies¶

entity_helpers      (standalone)
table_helpers       --> navigation_helpers (for reference fields)
navigation_helpers  --> specs.loader

FormContext is defined in metaseed.forms and re-exported from metaseed.ui.helpers. The helper modules depend on AppState for session state access.