UFM: JavaScript-like Expressions

[leekelleher]

Description

Adds support for JavaScript-like expressions to UFM.

Using a syntax similar to JavaScript's Template literals, expressions are delimited by a dollar sign and curly braces: ${expression}.

The implementation makes use of the Heximal Expressions library (source). The syntax should feel familiar to AngularJS expressions, with piped filters/transformers.

How to test?

Go to a document that can make use of UFM-syntax/label-templates, e.g. a block list item or a property's description.
Try adding syntax for various scenarios, for example...

• Rendering a literal value: ${ propertyAlias }
• Property drilling: ${ propertyAlias.length }
• Conditionals: ${ propertyAlias.length > 0 ? "Yes" : "No" }
• Piped filters: ${ propertyAlias | uppercase }

[Copilot]

Pull Request Overview

Adds JavaScript-like ${…} expression support to Umbraco Flavored Markdown (UFM) by integrating the Heximal Expressions library, providing a marked extension for inline parsing, and a LitElement to evaluate and render expressions with filters.

• Configure TypeScript path mapping and package.json to include @heximal/expressions.
• Register a new ufmjs marked extension and expose it via manifest.
• Introduce umb-ufm-js-expression component and extend UfmContext to supply filters.

Reviewed Changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/Umbraco.Web.UI.Client/tsconfig.json	Add path mapping for heximal-expressions
src/Umbraco.Web.UI.Client/src/packages/ufm/extensions/ufmjs-marked-extension.api.ts	Implement inline marked extension for ${} tokens
src/Umbraco.Web.UI.Client/src/packages/ufm/extensions/types.ts	Export new marked extension API type
src/Umbraco.Web.UI.Client/src/packages/ufm/extensions/manifests.ts	Register the UFM JS marked extension manifest
src/Umbraco.Web.UI.Client/src/packages/ufm/contexts/ufm.context.ts	Add getFilters() method to retrieve all filters
src/Umbraco.Web.UI.Client/src/packages/ufm/components/ufm-js-expression.element.ts	Define umb-ufm-js-expression element for parsing & rendering expressions
src/Umbraco.Web.UI.Client/src/packages/ufm/components/index.ts	Export the new umb-ufm-js-expression component
src/Umbraco.Web.UI.Client/src/external/heximal-expressions/index.ts	Re-export the heximal expressions package
src/Umbraco.Web.UI.Client/package.json	Add @heximal/expressions dependency and map external path

Files not reviewed (1)

• src/Umbraco.Web.UI.Client/package-lock.json: Language not supported

Comments suppressed due to low confidence (3)

src/Umbraco.Web.UI.Client/src/packages/ufm/extensions/ufmjs-marked-extension.api.ts:5

• [nitpick] Consider using UmbUfmJsMarkedExtensionApi (capitalizing the JS acronym) for consistency with other code elements (umb-ufm-js-expression, etc.) and improved readability.

export class UmbUfmjsMarkedExtensionApi implements UmbMarkedExtensionApi {

src/Umbraco.Web.UI.Client/src/packages/ufm/components/ufm-js-expression.element.ts:36

• New expression parsing and evaluation logic isn’t covered by unit tests. Add tests for valid expressions, edge cases (syntax errors), caching behavior, and filter application to ensure correctness.

	#labelTemplate(expression: string, model?: any): string {

src/Umbraco.Web.UI.Client/src/packages/ufm/contexts/ufm.context.ts:68

• [nitpick] Consider adding a JSDoc comment explaining that this method returns a map of filter aliases to their functions, and noting any expected structure of the returned object.

	public getFilters() {

[iOvergaard]

Tested with different logical expressions ✅
Tested echoing deep values ✅
Tested registering my own markedExtension that preprocesses the HTML first (probably more related to the previous PR), and UFM still works ✅
Caching works (but hard to stress test it) ✅

[umbracocommunity]

This pull request has been mentioned on Umbraco community forum. There might be relevant details there:

https://forum.umbraco.com/t/trying-to-be-clever-with-ufm-fallbacks/4533/2