Add format and tpl helpers

Author: mstijak

docs/content/intro/TypeScriptMigration.js

@@ -289,8 +289,80 @@ const m = createAccessorModelProxy<FormModel>();
          | `lessThanOrEqual(accessor, value)` | True if `x &lt;= value` |
          | `greaterThan(accessor, value)` | True if `x &gt; value` |
          | `greaterThanOrEqual(accessor, value)` | True if `x &gt;= value` |
+         | `format(accessor, fmt, nullText?)` | Formats value using format string |
 
-         These helpers return `Selector&lt;boolean&gt;` which can be used anywhere a boolean binding is expected.
+         These helpers return `Selector&lt;boolean&gt;` (or `Selector&lt;string&gt;` for `format`) which can be used anywhere a binding is expected.
+
+         ### Format Helper
+
+         The `format` helper creates a selector that formats values using CxJS format strings.
+         This is useful for displaying formatted numbers, dates, or percentages in text props:
+
+         <CodeSplit>
+            <CodeSnippet copy={false}>{`
+import { createAccessorModelProxy } from "cx/data";
+import { format } from "cx/ui";
+
+interface Product {
+   name: string;
+   price: number;
+   discount: number;
+}
+
+const m = createAccessorModelProxy<Product>();
+
+<cx>
+   {/* Format as number with 2 decimal places */}
+   <div text={format(m.price, "n;2")} />
+
+   {/* Format as percentage */}
+   <div text={format(m.discount, "p;0")} />
+
+   {/* With custom null text */}
+   <div text={format(m.price, "n;2", "N/A")} />
+</cx>
+            `}</CodeSnippet>
+         </CodeSplit>
+
+         The format string uses CxJS format syntax (e.g., `"n;2"` for numbers, `"p;0"` for percentages,
+         `"d"` for dates). The optional third parameter specifies text to display for null/undefined values.
+
+         ### Template Helper with Accessor Chains
+
+         The `tpl` function now supports accessor chains in addition to its original string-only form.
+         This allows you to create formatted strings from multiple values with full type safety:
+
+         <CodeSplit>
+            <CodeSnippet copy={false}>{`
+import { createAccessorModelProxy } from "cx/data";
+import { tpl } from "cx/ui";
+
+interface Person {
+   firstName: string;
+   lastName: string;
+   age: number;
+}
+
+const m = createAccessorModelProxy<Person>();
+
+<cx>
+   {/* Original string-only form still works */}
+   <div text={tpl("{firstName} {lastName}")} />
+
+   {/* New accessor chain form with positional placeholders */}
+   <div text={tpl(m.firstName, m.lastName, "{0} {1}")} />
+
+   {/* Supports formatting in placeholders */}
+   <div text={tpl(m.firstName, m.age, "{0} is {1:n;0} years old")} />
+
+   {/* Supports null text */}
+   <div text={tpl(m.firstName, "Hello, {0|Guest}!")} />
+</cx>
+            `}</CodeSnippet>
+         </CodeSplit>
+
+         The accessor chain form uses positional placeholders (&#123;0&#125;, &#123;1&#125;, etc.) and supports
+         all StringTemplate features including formatting (`:format`) and null text (`|nullText`).
 
          ### Typed Config Properties
 

packages/cx/package.json

@@ -1,6 +1,6 @@
 {
    "name": "cx",
-   "version": "26.1.3",
+   "version": "26.1.5",
    "description": "Advanced JavaScript UI framework for admin and dashboard applications with ready to use grid, form and chart components.",
    "exports": {
       "./data": {
@@ -97,4 +97,4 @@
       "tsconfig-paths": "^4.2.0",
       "typescript": "^5.9.3"
    }
-}
+}

packages/cx/src/ui/exprHelpers.spec.ts

@@ -14,6 +14,7 @@ import {
    notEqual,
    strictEqual,
    strictNotEqual,
+   format,
 } from "./exprHelpers";
 import assert from "assert";
 import { createAccessorModelProxy } from "../data/createAccessorModelProxy";
@@ -376,4 +377,36 @@ describe("exprHelpers", function () {
          assert.strictEqual(selector({ nullable: undefined }), true);
       });
    });
+
+   describe("format", function () {
+      it("formats numbers with specified decimal places", function () {
+         const selector = format(m.value, "n;2");
+         assert.strictEqual(selector({ value: 1234.5 }), "1234.50");
+      });
+
+      it("formats percentages", function () {
+         const selector = format(m.value, "p;0");
+         assert.strictEqual(selector({ value: 0.5 }), "50%");
+      });
+
+      it("returns empty string for null values", function () {
+         const selector = format(m.nullable, "n;2");
+         assert.strictEqual(selector({ nullable: null }), "");
+      });
+
+      it("returns empty string for undefined values", function () {
+         const selector = format(m.nullable, "n;2");
+         assert.strictEqual(selector({ nullable: undefined }), "");
+      });
+
+      it("returns custom null text for null values", function () {
+         const selector = format(m.nullable, "n;2", "N/A");
+         assert.strictEqual(selector({ nullable: null }), "N/A");
+      });
+
+      it("returns custom null text for undefined values", function () {
+         const selector = format(m.nullable, "n;2", "-");
+         assert.strictEqual(selector({ nullable: undefined }), "-");
+      });
+   });
 });

packages/cx/src/ui/exprHelpers.ts

@@ -1,5 +1,7 @@
+import { computable } from "../data/computable";
 import { AccessorChain } from "../data/createAccessorModelProxy";
 import { Selector } from "../data/Selector";
+import { Format } from "../util/Format";
 import { expr } from "./expr";
 
 /** Returns a selector that converts the value to boolean using !! */
@@ -76,3 +78,19 @@ export function strictEqual<V>(arg: AccessorChain<V>, value: V): Selector<boolea
 export function strictNotEqual<V>(arg: AccessorChain<V>, value: V): Selector<boolean> {
    return expr(arg, (x) => x !== value);
 }
+
+/** Returns a selector that formats the value using the specified format string.
+ * Format strings use semicolon-separated syntax: "formatType;param1;param2"
+ * @param arg - The accessor chain to the value
+ * @param fmt - The format string
+ * @param nullText - Optional text to display for null/undefined values
+ * @example
+ * format(m.price, "n;2") // formats as number with 2 decimal places
+ * format(m.date, "d") // formats as date
+ * format(m.value, "p;0;2") // formats as percentage with 0-2 decimal places
+ * format(m.value, "n;2", "N/A") // shows "N/A" for null values
+ */
+export function format<V>(arg: AccessorChain<V>, fmt: string, nullText?: string): Selector<string> {
+   let f = nullText != null ? `${fmt}|${nullText}` : fmt;
+   return computable(arg, (x) => Format.value(x, f));
+}

packages/cx/src/ui/tpl.spec.ts

@@ -0,0 +1,69 @@
+import { tpl } from "./tpl";
+import assert from "assert";
+import { createAccessorModelProxy } from "../data/createAccessorModelProxy";
+
+interface Model {
+   firstName: string;
+   lastName: string;
+   age: number;
+   city: string;
+}
+
+describe("tpl", function () {
+   const m = createAccessorModelProxy<Model>();
+
+   describe("string-only form", function () {
+      it("returns a tpl object", function () {
+         const result = tpl("{firstName} {lastName}");
+         assert.deepStrictEqual(result, { tpl: "{firstName} {lastName}" });
+      });
+   });
+
+   describe("accessor chain form", function () {
+      it("formats with a single accessor", function () {
+         const selector = tpl(m.firstName, "Hello, {0}!");
+         assert.strictEqual(selector({ firstName: "John" }), "Hello, John!");
+      });
+
+      it("formats with two accessors", function () {
+         const selector = tpl(m.firstName, m.lastName, "{0} {1}");
+         assert.strictEqual(selector({ firstName: "John", lastName: "Doe" }), "John Doe");
+      });
+
+      it("formats with three accessors", function () {
+         const selector = tpl(m.firstName, m.lastName, m.age, "{0} {1} is {2} years old");
+         assert.strictEqual(
+            selector({ firstName: "John", lastName: "Doe", age: 30 }),
+            "John Doe is 30 years old",
+         );
+      });
+
+      it("formats with four accessors", function () {
+         const selector = tpl(m.firstName, m.lastName, m.age, m.city, "{0} {1}, {2}, from {3}");
+         assert.strictEqual(
+            selector({ firstName: "John", lastName: "Doe", age: 30, city: "NYC" }),
+            "John Doe, 30, from NYC",
+         );
+      });
+
+      it("handles null values", function () {
+         const selector = tpl(m.firstName, m.lastName, "{0} {1}");
+         assert.strictEqual(selector({ firstName: "John", lastName: null }), "John ");
+      });
+
+      it("handles undefined values", function () {
+         const selector = tpl(m.firstName, m.lastName, "{0} {1}");
+         assert.strictEqual(selector({ firstName: undefined, lastName: "Doe" }), " Doe");
+      });
+
+      it("supports formatting in template", function () {
+         const selector = tpl(m.age, "Age: {0:n;0}");
+         assert.strictEqual(selector({ age: 30 }), "Age: 30");
+      });
+
+      it("supports null text in template", function () {
+         const selector = tpl(m.firstName, "Name: {0|N/A}");
+         assert.strictEqual(selector({ firstName: null }), "Name: N/A");
+      });
+   });
+});

packages/cx/src/ui/tpl.ts

@@ -1,5 +1,18 @@
-export function tpl(text: string) {
-   return {
-      tpl: text
-   }
+import { computable, ComputableSelector } from "../data/computable";
+import { MemoSelector } from "../data/Selector";
+import { StringTemplate } from "../data/StringTemplate";
+import { Tpl } from "./Prop";
+
+export function tpl(text: string): Tpl;
+export function tpl<T extends ComputableSelector[]>(...args: [...T, string]): MemoSelector<string>;
+export function tpl(...args: any[]): any {
+   if (args.length === 1)
+      return {
+         tpl: args[0],
+      };
+
+   let template = args[args.length - 1];
+   let formatter = StringTemplate.get(template);
+   let selectors = args.slice(0, -1);
+   return computable(...selectors, (...values: any[]) => formatter(values));
 }