@judo/expressions

Expression language integration for JUDO UI Runtime, wrapping @judo/idem

Purpose

Provides a React context-based integration for the @judo/idem expression evaluator. Creates a pre-configured EvalExpr instance with date-fns date functions and shares it via React context so any component in the tree can evaluate IDEM expressions (arithmetic, logic, string functions, collection operations, date manipulation) against runtime data.

Architecture Layer

Layer 2 (Cross-cutting) — consumed by components and higher layers for expression evaluation (e.g., visibility conditions, computed labels, guard expressions).

Dependencies

• @judo/idem — IDEM expression language evaluator (dependency)
• antlr4ng ^3 — ANTLR4 runtime required by @judo/idem (peer)
• date-fns ^4 — date manipulation functions injected into the evaluator (peer)
• react ^19 — React runtime (peer)

File Structure

src/
├── index.ts                          # Barrel re-exports + type re-exports from @judo/idem
├── expression-context.tsx            # ExpressionProvider, useExpression, useExpressionOptional
└── expression-context.test.tsx       # Full test suite (53 tests)

Exports Summary

| Export | Kind | Description | | ------------------------- | --------- | -------------------------------------------------------------------------------------------------- | | ExpressionProvider | component | React provider that creates a configured EvalExpr instance (memoized) and shares it via context. | | ExpressionProviderProps | interface | Props for ExpressionProvider: { children: ReactNode }. | | useExpression() | hook | Returns the EvalExpr function from context. Throws if used outside ExpressionProvider. | | useExpressionOptional() | hook | Returns the EvalExpr function or null if no provider is in the tree. Safe for optional usage. | | EvalExpr | type | Re-exported from @judo/idem. The evaluator function signature: <T>(expr: string, ctx?) => T. | | Self | type | Re-exported from @judo/idem. The context type for self references in expressions. |

Key Patterns

• Single memoized instance: ExpressionProvider creates the EvalExpr evaluator once via useMemo([], ...) and reuses it across re-renders
• Date function injection: The provider configures @judo/idem with date-fns functions (addDays, subDays, parseISO, differenceInDays, differenceInSeconds) for date expression support
• Type re-exports: Core types (EvalExpr, Self) are re-exported from @judo/idem for consumer convenience, avoiding direct @judo/idem imports in consuming packages
• Throw vs null pattern: useExpression() throws for mandatory usage; useExpressionOptional() returns null for optional/conditional usage
• No configuration props: The provider takes no configuration — the evaluator setup is fixed with the standard date functions

Supported Expression Features

The @judo/idem evaluator (exposed through this package) supports:

| Category | Examples | | ----------- | -------------------------------------------------------------------- | | Arithmetic | +, -, *, /, mod, ^, unary -, parentheses | | Comparison | ==, !=, <, >, <=, >= | | Logical | and, or, not, xor, ternary ? : | | Literals | strings ('...'), numbers, booleans, null, decimals | | Self access | self.prop, self.nested.prop, null-safe navigation | | Strings | !lowerCase(), !upperCase(), !length(), !trim() | | Null checks | !isDefined(), !isUndefined() | | Collections | !size(), !sum(), !min(), !max(), !avg(), !filter(), in | | Dates | today, date literals (`2024-01-15`), date-fns functions |