@judo/model-api

TypeScript interfaces mirroring the ECore meta-model for JUDO UI Runtime

Purpose

Foundational type system for the entire JUDO UI React framework. Defines all TypeScript interfaces, enums, service symbols, and type aliases that mirror the ECore XML meta-model (meta-model/ui.ecore). This is a pure types + symbols package — no runtime logic, no React hooks, no context providers.

Architecture Layer

Layer 1 (Foundation) — depended upon by every other package in the monorepo.

Dependencies

• react (peer, optional) — only for ComponentType / ReactElement in extensibility types
• typescript (dev) — build-time only

File Structure

src/
├── index.ts                # Barrel re-export
├── enums.ts                # All enums (layout, UI, data) as `const` objects
├── extensibility.ts        # Extensibility types (customization configs, component props)
├── services.ts             # Service symbols, service interfaces, hook factory types
├── data/
│   ├── index.ts
│   ├── elements.ts         # Core data model interfaces (ClassType, RelationType, etc.)
│   └── types.ts            # Concrete DataType variants (StringType, NumericType, etc.)
├── structural/
│   ├── index.ts
│   ├── actions.ts          # All ActionDefinition interfaces (~37 action types)
│   └── application.ts      # Application, PageDefinition, NavigationItem, Action, Theme, Auth
└── visual/
    ├── index.ts
    ├── base.ts             # ModelElement, NamedElement, LabeledElement
    ├── layout.ts           # VisualElement, Container, Flex, PageContainer, Size, etc.
    ├── buttons.ts          # ButtonGroup, Button
    ├── display.ts          # Text, Label, Formatted, IconImage
    ├── inputs.ts           # All input field interfaces (14 input types + Option, InputValueConstraint)
    ├── link.ts             # Link (autocomplete/relation field)
    ├── table.ts            # Table, Column, Filter
    └── tabs.ts             # TabController, Tab

Exports Summary

Enums (27)

All enums use as const objects with companion types for tree-shaking (no TypeScript enum keyword).

| Enum | Values | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Axis | HORIZONTAL, VERTICAL | | Fit | NONE, LOOSE, TIGHT | | Stretch | NONE, HORIZONTAL, VERTICAL, BOTH | | MainAxisAlignment | CENTER, END, SPACEAROUND, SPACEBETWEEN, SPACEEVENLY, START | | CrossAxisAlignment | BASELINE, CENTER, END, START, STRETCH | | MainAxisSize | MIN, MAX | | Alignment | 9-point grid (TOP_LEFT … BOTTOM_RIGHT) | | DialogSize | XS, SM, MD, LG, XL | | PageContainerType | TABLE, FORM, VIEW | | ButtonStyle | contained, text, outlined | | ConfirmationType | NONE, CONDITIONAL, MANDATORY | | Sort | NONE, ASC, DESC | | FilterOperationType | EQUAL, NOT_EQUAL, IS_EMPTY, IS_NOT_EMPTY, LESS, LESS_OR_EQUAL, GREATER, GREATER_OR_EQUAL, LIKE | | CheckboxSelection | AUTO, ENABLED, DISABLED | | TableRepresentation | TABLE, TAG, CARD | | MenuLayout | VERTICAL, HORIZONTAL | | TabOrientation | HORIZONTAL, VERTICAL | | DurationUnit | NANOSECOND … YEAR (10 values) | | Placement | TOP, BOTTOM, START, END, DEFAULT | | TitleFrom | LABEL, ATTRIBUTE | | ClaimType | UNDEFINED, EMAIL, USERNAME | | RelationKind | ASSOCIATION, COMPOSITION, AGGREGATION, STATIC | | MemberType | STORED, DERIVED, MAPPED, TRANSIENT, ACCESS | | RelationBehaviourType | LIST, CREATE, SET, UNSET, ADD, REMOVE, RANGE, VALIDATE_CREATE, TEMPLATE, UPDATE, VALIDATE_UPDATE, DELETE, REFRESH, EXPORT | | ClassBehaviourType | REFRESH, UPDATE, VALIDATE_UPDATE, DELETE, TEMPLATE | | OperationTypeEnum | MAPPED, STATIC | | OperationTargetBehaviourType | REFRESH, UPDATE, DELETE, VALIDATE_INPUT |

Visual Interfaces

| Interface | Description | | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | ModelElement | Base for all model elements with eContainer parent navigation | | NamedElement | Adds name, optional sourceId, annotations | | LabeledElement | Mixin for elements with labels and icons | | VisualElement | Core base for ALL UI components — every visual widget extends this | | Container | Base container with children array | | Flex | Flex layout container (@type: "Flex") | | PageContainer | Top-level page container (@type: "PageContainer") | | Spacer | Empty space for layout | | Divider | Visual divider/separator | | Size | Size specification (width/height) | | SizeConstraint | Min/max size constraints | | Frame | Card/panel frame styling | | Icon | Icon definition with iconName | | Align | Alignment specification | | ButtonGroup / Button | Button grouping and individual buttons | | Text / Label / Formatted / IconImage | Display elements | | TextInput / NumericInput / DateInput / DateTimeInput / TimeInput | Input fields | | TextArea / Checkbox / Switch / EnumerationCombo / EnumerationRadio | More input types | | EnumerationToggleButtonbar / TrinaryLogicCombo / BinaryTypeInput / PasswordInput | Specialized inputs | | Input / InputValueConstraint / Option | Input base types | | Table / Column / Filter | Data table elements | | Link | Autocomplete/relation field | | TabController / Tab | Tabbed layout | | InputElement | Union of all 14 input types |

Data Interfaces

| Interface | Description | | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | | DataElement | Abstract base for all data elements | | DataType | Abstract base for data type variants | | ClassType | Transfer object type with attributes, relations, operations | | RelationType | Reference to another class | | AttributeType | Scalar attribute on a class | | OperationType | Callable method/operation | | OperationParameterType | Operation input/output parameter | | ApplicationType | Application type reference | | AccessBasedNavigation | Post-call navigation for operation results | | Annotation | Model element annotation | | MimeType | MIME type definition | | StringType / NumericType / BooleanType / DateType / TimestampType / TimeType / PasswordType / EnumerationType / BinaryType | Data type variants | | EnumerationMember | Member of an enumeration type | | AnyDataType | Union of all 9 data type variants |

Structural Interfaces

| Interface | Description | | ----------------------------------------- | ------------------------------------------------------------------------- | | Application | Root application model — contains everything | | PageDefinition | Page definition binding container + actions | | Action | Action binding between pages | | NavigationController / NavigationItem | Navigation menu | | Theme | Model-level theme colors | | Authentication / Claim | OIDC authentication configuration | | ActionDefinition | Abstract base for all action definitions | | Confirmation | Confirmation dialog configuration | | 37 concrete *ActionDefinition types | Navigation, CRUD, relation, operation, form, selector, autocomplete, etc. | | AnyActionDefinition | Discriminated union of all action definition types |

Service Symbols (13)

| Symbol | Purpose | | ---------------------------- | ---------------------------------------- | | MODEL_LOADER_SERVICE | DI key for model loading service | | MODEL_REGISTRY_SERVICE | DI key for model registry service | | NAVIGATION_BADGE_SERVICE | DI key for navigation badge service | | THEME_SERVICE | DI key for theme service | | ACTION_HANDLER_FACTORY | DI key for action handler hook factories | | COMPONENT_OVERRIDE | DI key for component overrides | | COMPONENT_OVERRIDE_SERVICE | DI key for component override service | | NOTIFICATION_SERVICE | DI key for notification service | | DIALOG_SERVICE | DI key for dialog service | | UNSAVED_CHANGES_GUARD | DI key for unsaved changes guard | | SESSION_TIMEOUT_GUARD | DI key for session timeout guard | | LOADING_SERVICE | DI key for loading indicator service | | I18N_SERVICE | DI key for internationalization service |

Service Interfaces

Key service interfaces: ModelLoaderService, ModelRegistryService, NavigationBadgeService, ThemeService, ComponentOverrideService — all expose subscribe/getSnapshot for React's useSyncExternalStore.

Supporting types: RegistrySnapshot, BadgeInfo, ThemeConfig, ActionHandlerHook, ActionHandlerFn, ActionHandlerContext, ActionHandlerFactoryProperties, BuiltInActionHandlerFactoryProperties, OverrideComponent, ComponentOverride, ComponentOverrideProperties.

Extensibility Types

| Interface / Type | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | CustomComponentProps | Props passed to every custom component implementation (element, page, onDispatch) | | CustomComponent | A custom component implementation type | | ElementTypeMap | Maps @type discriminator strings to TypeScript interfaces | | ElementTypeName | Union of all valid @type discriminator strings | | ComponentInterceptor | Type-safe interceptor for a specific element type | | AnyComponentInterceptor | Loose interceptor for runtime use | | ComponentInterceptors | Map of element type → interceptor functions | | ActionLifecycleContext | Context for action lifecycle hooks (action, page, transfer, callDefault, etc.) | | ActionLifecycle | Standard lifecycle methods: before, execute, after, onError | | PageActionOverrides | Map of action sourceId → partial ActionLifecycle | | VisualPropertySet | Set of overridable visual properties (hidden, disabled, required, label, readOnly, className, custom) | | VisualPropertyOverrides | Map of element sourceId → partial VisualPropertySet | | VisualPropertiesHook | Hook returning visual property overrides | | SubThemeHook | Function producing scoped MUI ThemeOptions for a named sub-theme | | PageCustomization | Per-page customization bundle (actions, visualProperties, typeaheadProviders, tableRowHighlighting, enumOptionFilter, dateValidationProps, columnCustomizers, itemContainerConfigs) | | CustomizationsConfig | Top-level config (pages, components, componentInterceptors, subThemeProviders, redirectHandler, customRoutes, menuCustomizer, footerText, heroComponent, settingsPage, guestComponent) | | TableRowHighlightConfig | Row highlighting rule (name, label, backgroundColor, color, condition) | | EnumOptionFilterFn | Filter function for enum input options | | DateValidationProps | Dynamic date validation constraints (minDate, maxDate, disableFuture, disablePast) | | DateValidationFn | Function returning date validation constraints from transfer data | | ColumnCustomizerFn | Function receiving GridColDef + Column to customize DataGrid columns | | ItemComponentProps | Props for custom item components (row, columns, onRowClick, onDelete) | | ItemToolbarProps | Props for custom item toolbar (element, totalCount) | | ItemContainerConfig | Config for CARD/TAG representations (layout, ItemElement, ToolbarElement) | | GuestPageProps | Props for custom guest page (application, signIn) | | HeroComponentProps | Props for custom hero component (principal, actorName, signOut, etc.) |

Key Patterns

• EMF/ECore mirroring: Every interface maps to a named ECore class via @type discriminator
• Simplified @type values: Visual and action types use "Flex", "Table", "BackActionDefinition" (no ui: prefix); data types use "data:ClassType", "data:StringType" (keep data: prefix)
• as const objects: All enums use as const objects + companion types for tree-shaking (no TypeScript enum)
• Resolved references: Interfaces use resolved object references (not string $ref pointers)
• EMF defaults: Properties with ECore defaults are optional — parser fills them in
• eContainer parent navigation: Set during parsing for upward tree traversal
• Symbol-based DI: All 13 service symbols use Symbol.for() for cross-package service discovery
• subscribe/getSnapshot contract: Services implement the React 18 useSyncExternalStore protocol
• Three-layer separation: Data layer → Structural layer → Visual layer (deliberately decoupled)