@salesforce/afv-skills 1.55.0 → 1.57.0

package/skills/platform-widget-generate/SKILL.md

@@ -2,7 +2,7 @@
 name: platform-widget-generate
 description: "Use this skill to author a complete HXL WidgetBundle (UEM body + schema.json + -meta.xml). TRIGGER when: user asks for a widget, mosaic, fragment, card, or rich UI surface for any subject, domain, feature, or entity noun; the prompt names only an entity or data shape without invoking Lightning Types, CLTs, or Apex-backed types. DO NOT TRIGGER when: the prompt explicitly says 'Lightning Type', 'CLT', 'Custom Lightning Type', 'Apex-backed type', or references '@apexClassType/...' (use platform-lightning-type-widget-coordinate); authoring a custom-LWC renderer for a Custom Lightning Type (use platform-custom-lightning-type-generate); or editing only an LWC component."
 metadata:
-  version: "1.3"
+  version: "1.4"
   domains: ["Platform", "Agentforce"]
   minApiVersion: "68.0"
   relatedSkills:
@@ -93,6 +93,7 @@ The first child of `tile/widget.children` SHOULD be a single `tile/column`. All
 
 - Bind a block property to runtime data with `{!$attrs.<attrName>}`. `<attrName>` MUST match a property name in `schema.json`.
 - Inside a `forEach`, reference the loop variable instead — e.g. `"text": "{!$item.name}"`. See `references/widget-meta-directives.md`.
+- A binding may be a **formula expression** instead of a bare field reference. See `references/widget-formulas.md` for the full supported-function list, syntax, and gotchas.
 
 ---
 
@@ -180,15 +181,19 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
    |---|---|
    | Single object (no iteration) | `<skill-root>/examples/single-object.json` |
    | Any list iteration (root-level array, nested list, or list embedded in a single-object widget) | `<skill-root>/examples/list-with-foreach.json` |
-   | Conditional rendering (`if` bound to a boolean) | `<skill-root>/examples/conditional.json` |
+   | Conditional rendering (`if` bound to a boolean or formula) | `<skill-root>/examples/conditional.json` |
+   | Computed values, text/number transforms, or `if` driven by a formula (not a bare boolean field) | `<skill-root>/examples/formulas.json` |
 
    A spec may match multiple patterns (e.g. a list of items where some items render conditionally reads both `list-with-foreach.json` and `conditional.json`). **Read every matching example, and only those — do not skip the read because the pattern feels familiar.**
 
+   **Before writing any formula**, read `references/widget-formulas.md` in full — it is the authoritative list of supported operators and functions; do not improvise a function name or operator that isn't documented there.
+
    Then:
    - Map each widget-spec property to a block property; preserve spec order.
    - **Decide root iteration:** single object → properties directly under root `tile/column`. Collection → wrap repeating block in `forEach`/`forItem`. See `references/widget-meta-directives.md`.
    - Bind values with `{!$attrs.X}` (or `{!$item.X}` inside `forEach`).
-   - For conditional blocks, add `"if"` on `meta` — only when the schema has a matching `lightning__booleanType` property.
+   - For conditional blocks, add `"if"` on `meta` — either a bare `lightning__booleanType` property, or a formula expression that evaluates to boolean. See `references/widget-formulas.md`.
+   - **When the widget spec calls for a computed value** (a total, a derived label, a formatted string) rather than a raw field, express it as a formula inside `{!...}` per `references/widget-formulas.md` — do not invent a new schema property to hold a value that can be computed from existing ones.
 
 6. **Author `schema.json`.** Build the JSON Schema from the widget spec. Fields live one level deep under an `attributes` wrapper:
 
@@ -235,7 +240,8 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
     - **`schema-parses`** — `<pkgDir>/uiWidgets/<widgetName>/schema.json` parses as JSON.
     - **`schema-root-keys`** — root has `title` (string), `type: "object"`, and `properties.attributes` (object) — where `properties.attributes` carries `lightning:type: "lightning__objectType"` and a nested `properties` map. No `unevaluatedProperties: false`.
     - **`schema-leaf-types`** — every leaf under `properties.attributes.properties` carries a `lightning:type`. Singular nested inner-class fields carry `lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`); the nested shape is not redeclared. `List<InnerClass>` fields carry `lightning:type: "lightning__listType"` with `items.lightning:type` set to the inner Apex class reference (`@apexClassType/<namespace>__<OuterClass>$<InnerClass>`), not a redeclared field map — see `references/schema-from-lightning-type.md`. **When the list has no Apex-backed type** (schema inferred from the prompt), `items.lightning:type: "lightning__objectType"` MUST carry an inline nested `properties` map for every item field the body binds via `{!$item.X}`.
-    - **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.<outerField>.<innerField>}` for nested objects) in `<widgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream.
+    - **`bindings-resolve`** — every `{!$attrs.X}` (or `{!$attrs.<outerField>.<innerField>}` for nested objects) in `<widgetName>.json` resolves to a property under `schema.json` `properties.attributes.properties`, and every `{!$item.X}` resolves to a `forItem` loop variable defined upstream. This applies to `$attrs`/`$item` references **inside formula expressions** too.
+    - **`formulas-supported`** — every function name used inside a `{!...}` expression appears in the *Supported functions* list in `references/widget-formulas.md`.
     - **`body-envelope`** — `<widgetName>.json` root has `type: "lightning__agentforceWidget"` and a `contentBody` object whose `widgetBody` carries the UEM tree rooted at `tile/widget`. No node in the tree — root or non-root — carries a `type` key.
     - **`metaxml-wellformed`** — `<widgetName>.uiwidget-meta.xml` parses as well-formed XML.
     - **`metaxml-elements`** — `<widgetName>.uiwidget-meta.xml` has root `<UiWidgetBundle>` and contains `<masterLabel>` (non-empty), `<description>` (non-empty), and `<widgetType>JSON</widgetType>`.
@@ -259,24 +265,26 @@ Widgets express *intent*, not pixels. Each surface provides a default look and f
 
 ## Gotchas
 
-| Issue | Resolution |
-|---|---|
-| `getUiComponentSchemas` returns a partial-failure entry | Pick a different block from `discoverUiComponents`; do not silently continue without a schema |
-| Body references `{!$attrs.foo}` but `foo` is not under `schema.json` `properties.attributes.properties` | Add `foo` to `schema.json` `properties.attributes.properties` OR remove the body reference |
+| Issue | Resolution                                                                                                                                                                                                                                                     |
+|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `getUiComponentSchemas` returns a partial-failure entry | Pick a different block from `discoverUiComponents`; do not silently continue without a schema                                                                                                                                                                  |
+| Body references `{!$attrs.foo}` but `foo` is not under `schema.json` `properties.attributes.properties` | Add `foo` to `schema.json` `properties.attributes.properties` OR remove the body reference                                                                                                                                                                     |
 | Output written outside `<pkgDir>/uiWidgets/<widgetName>/` | `<pkgDir>` = `<packageDirectories[].path>/main/default` (see `references/widget-bundle-layout.md`). Dropping the `main/default/` segment is the common cause of widgets landing at `force-app/uiWidgets/...` instead of `force-app/main/default/uiWidgets/...` |
-| `if` bound to a non-boolean | Use `if` only when the schema has a `lightning__booleanType` property |
-| `tile/button` renders but does nothing when clicked | No `actions.click` entry was set — an action-less button renders disabled by design. Add one (see *Actions* above) |
-| Using `action/sendMessage` for pure navigation, or `action/openLink` when the agent should respond | `action/openLink` is synchronous and does not consume a turn; `action/sendMessage` is asynchronous and earns a fresh turn. Pick the one matching the intended UX |
+| `if` bound directly to a raw string or number relies on truthiness and is unreliable | Bind to a `lightning__booleanType` property, or use a formula comparison that evaluates to boolean                                                                                                                                                             |
+| `tile/button` renders but does nothing when clicked | No `actions.click` entry was set — an action-less button renders disabled by design. Add one (see *Actions* above)                                                                                                                                             |
+| Using `action/sendMessage` for pure navigation, or `action/openLink` when the agent should respond | `action/openLink` is synchronous and does not consume a turn; `action/sendMessage` is asynchronous and earns a fresh turn. Pick the one matching the intended UX                                                                                               |
 
 ---
 
 ## Reference File Index
 
-| File | When to read |
-|---|---|
-| `references/widget-meta-directives.md` | For `forEach` / `forItem` (iteration) and `if` (conditional rendering), including nested loops |
-| `references/schema-from-lightning-type.md` | When `lightningTypeSchema` is provided; how to derive the widget `schema.json` from an Apex-backed Lightning Type |
-| `references/widget-bundle-layout.md` | Folder layout, `-meta.xml` shape, `<pkgDir>` resolution rules |
-| `examples/single-object.json` | Single-object pattern (root binding via `{!$attrs.X}`, no iteration) |
+| File | When to read                                                                                                                                                                        |
+|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `references/widget-meta-directives.md` | For `forEach` / `forItem` (iteration) and `if` (conditional rendering), including nested loops                                                                                      |
+| `references/schema-from-lightning-type.md` | When `lightningTypeSchema` is provided; how to derive the widget `schema.json` from an Apex-backed Lightning Type                                                                   |
+| `references/widget-bundle-layout.md` | Folder layout, `-meta.xml` shape, `<pkgDir>` resolution rules                                                                                                                       |
+| `references/widget-formulas.md` | Supported formula functions and operators                                                                                                                                           |
+| `examples/single-object.json` | Single-object pattern (root binding via `{!$attrs.X}`, no iteration)                                                                                                                |
 | `examples/list-with-foreach.json` | Any list-iteration case — root-level collections, nested lists, and lists embedded inside a single-object widget (e.g. iterating a `List<InnerClass>` inside an outer Apex payload) |
-| `examples/conditional.json` | Conditional pattern (`if` on `meta`, including `if` + `forEach` together) |
+| `examples/conditional.json` | Conditional pattern (`if` on `meta`, including `if` + `forEach` together)                                                                                                           |
+| `examples/formulas.json` | Formula usage — text/arithmetic/date transforms, `IF`/`AND`/`NOT` driving both a `tile/text` and `meta.if`                                                                          |

package/skills/platform-widget-generate/examples/formulas.json

@@ -0,0 +1,191 @@
+{
+  "type": "lightning__agentforceWidget",
+  "contentBody": {
+    "widgetBody": {
+      "definition": "tile/widget",
+      "children": [
+        {
+          "definition": "tile/column",
+          "attributes": { "gap": "md" },
+          "children": [
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "1. Arithmetic operators", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "Base: ${!$attrs.price}" } },
+                { "definition": "tile/text", "attributes": { "text": "Discount: -${!$attrs.price * $attrs.discountPercentage / 100}" } },
+                { "definition": "tile/text", "attributes": { "text": "Tax: ${!$attrs.price * $attrs.taxRate}" } },
+                { "definition": "tile/text", "attributes": { "text": "Total: ${!$attrs.price * (1 + $attrs.taxRate) - ($attrs.price * $attrs.discountPercentage / 100)}", "variant": "h4", "color": "primary" } },
+                { "definition": "tile/text", "attributes": { "text": "Division: {!$attrs.price / $attrs.durationInMin}  |  Exponent: {!2 ^ 8}" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "2. Comparison operators", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "Equal: {!IF($attrs.status = 'boarding', 'yes', 'no')}  |  Not equal: {!IF($attrs.status <> 'boarding', 'yes', 'no')}" } },
+                { "definition": "tile/text", "attributes": { "text": "Greater than: {!IF($attrs.price > 1000, 'yes', 'no')}  |  Less than: {!IF($attrs.price < 1000, 'yes', 'no')}" } },
+                { "definition": "tile/text", "attributes": { "text": ">= : {!IF($attrs.price >= 1250, 'yes', 'no')}  |  <= : {!IF($attrs.price <= 1250, 'yes', 'no')}" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "3. Logical functions — IF / CASE / AND / OR / NOT", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "IF: {!IF($attrs.price > 1000, 'PREMIUM', 'standard')}" } },
+                { "definition": "tile/text", "attributes": { "text": "IF nested: {!IF($attrs.status = 'boarding', 'Now boarding!', IF($attrs.status = 'delayed', 'Delayed', 'Scheduled'))}" } },
+                { "definition": "tile/text", "attributes": { "text": "CASE: {!CASE($attrs.status, 'boarding', 'Now boarding', 'delayed', 'Please wait', 'cancelled', 'Refunded', 'On schedule')}" } },
+                { "definition": "tile/text", "attributes": { "text": "AND: {!IF(AND($attrs.isPriority, $attrs.price > 500), 'yes', 'no')}" } },
+                { "definition": "tile/text", "attributes": { "text": "OR: {!IF(OR($attrs.isPriority, $attrs.price > 5000), 'yes', 'no')}" } },
+                { "definition": "tile/text", "attributes": { "text": "NOT: {!IF(NOT($attrs.isPetAllowed), 'no pets', 'pets ok')}" } },
+                {
+                  "definition": "tile/badge",
+                  "attributes": {
+                    "label": "{!IF($attrs.status = 'boarding', 'Boarding', IF($attrs.status = 'delayed', 'Delayed', 'Scheduled'))}",
+                    "variant": "{!IF($attrs.status = 'boarding', 'info', IF($attrs.status = 'delayed', 'warning', 'secondary'))}"
+                  }
+                }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "4. Text functions", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "UPPER: {!UPPER($attrs.airline)}  |  LOWER: {!LOWER($attrs.airline)}" } },
+                { "definition": "tile/text", "attributes": { "text": "LEFT/RIGHT/MID: {!LEFT($attrs.airline, 3)}  |  {!RIGHT($attrs.airline, 4)}  |  {!MID($attrs.airline, 1, 3)}" } },
+                { "definition": "tile/text", "attributes": { "text": "LEN / TRIM / REVERSE: {!LEN($attrs.airline)}  |  [{!TRIM($attrs.notes)}]  |  {!REVERSE($attrs.flightId)}" } },
+                { "definition": "tile/text", "attributes": { "text": "SUBSTITUTE / FIND: {!SUBSTITUTE($attrs.airline, 'Indigo', 'IndiGo')}  |  {!FIND('IX', $attrs.flightId)}" } },
+                { "definition": "tile/text", "attributes": { "text": "LPAD / RPAD: [{!LPAD($attrs.flightId, 12, '.')}]  |  [{!RPAD($attrs.flightId, 12, '.')}]" } },
+                { "definition": "tile/text", "attributes": { "text": "TEXT / VALUE: {!TEXT($attrs.price)}  |  {!VALUE('42.5')}" } },
+                { "definition": "tile/text", "attributes": { "text": "CONTAINS / BEGINS: {!IF(CONTAINS($attrs.airline, 'Indi'), 'yes', 'no')}  |  {!IF(BEGINS($attrs.flightId, 'IX'), 'yes', 'no')}" } },
+                { "definition": "tile/text", "attributes": { "text": "Concat: {!$attrs.airline & ' — ' & $attrs.flightId}", "variant": "h4" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "5. Math functions", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "MOD/MAX/MIN: {!MOD($attrs.price, 100)}  |  {!MAX($attrs.price, 2000)}  |  {!MIN($attrs.price, 2000)}" } },
+                { "definition": "tile/text", "attributes": { "text": "ROUND/ABS/SQRT: {!ROUND($attrs.discountPercentage, 1)}  |  {!ABS(-42.5)}  |  {!SQRT($attrs.durationInMin)}" } },
+                { "definition": "tile/text", "attributes": { "text": "CEILING/FLOOR: {!CEILING(4.2)}  |  {!FLOOR(4.8)}" } },
+                { "definition": "tile/text", "attributes": { "text": "MCEILING/MFLOOR: {!MCEILING(-4.2)}  |  {!MFLOOR(-4.8)}" } },
+                { "definition": "tile/text", "attributes": { "text": "LOG/EXP/LN: {!LOG(1000)}  |  {!EXP(1)}  |  {!LN(2.718281828)}" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "6. Date & time functions", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "departureDate: {!$attrs.departureDate}" } },
+                { "definition": "tile/text", "attributes": { "text": "DAY/MONTH/YEAR: {!DAY(DATEVALUE($attrs.departureDate))}  |  {!MONTH(DATEVALUE($attrs.departureDate))}  |  {!YEAR(DATEVALUE($attrs.departureDate))}" } },
+                { "definition": "tile/text", "attributes": { "text": "WEEKDAY: {!WEEKDAY(DATEVALUE($attrs.departureDate))}" } },
+                { "definition": "tile/text", "attributes": { "text": "ADDMONTHS+3: {!ADDMONTHS(DATEVALUE($attrs.departureDate), 3)}" } },
+                { "definition": "tile/text", "attributes": { "text": "TODAY/NOW/TIMENOW: {!TODAY()}  |  {!NOW()}  |  {!TIMENOW()}" } },
+                { "definition": "tile/text", "attributes": { "text": "DATE(2026,12,31): {!DATE(2026,12,31)}" } },
+                { "definition": "tile/text", "attributes": { "text": "HOUR/MINUTE/SECOND/MILLISECOND from NOW: {!HOUR(NOW())} · {!MINUTE(NOW())} · {!SECOND(NOW())} · {!MILLISECOND(NOW())}" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "7. Validation & encoding functions", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "ISNULL/ISBLANK: {!IF(ISNULL($attrs.notes), 'null', 'has-value')}  |  {!IF(ISBLANK($attrs.notes), 'blank', 'has-value')}" } },
+                { "definition": "tile/text", "attributes": { "text": "NULLVALUE/BLANKVALUE: {!NULLVALUE($attrs.notes, 'n/a')}  |  {!BLANKVALUE($attrs.notes, 'empty')}" } },
+                { "definition": "tile/text", "attributes": { "text": "HTMLENCODE: {!HTMLENCODE($attrs.airline & ' <b>tag</b>')}" } },
+                { "definition": "tile/text", "attributes": { "text": "JSENCODE: {!JSENCODE($attrs.airline & \"'quote\")}" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "8. Pattern matching — ISNUMBER, REGEX", "variant": "h3" } },
+                { "definition": "tile/text", "attributes": { "text": "ISNUMBER '42.5': {!IF(ISNUMBER('42.5'), 'numeric', 'not-numeric')}" } },
+                { "definition": "tile/text", "attributes": { "text": "ISNUMBER 'abc': {!IF(ISNUMBER('abc'), 'numeric', 'not-numeric')}" } },
+                { "definition": "tile/text", "attributes": { "text": "REGEX flightId ^[A-Z]{2} [0-9]+$: {!IF(REGEX($attrs.flightId, '^[A-Z]{2} [0-9]+$'), 'match', 'no-match')}" } },
+                { "definition": "tile/text", "attributes": { "text": "REGEX airline ^[A-Za-z ]+$: {!IF(REGEX($attrs.airline, '^[A-Za-z ]+$'), 'match', 'no-match')}" } }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "meta": { "if": "{!AND($attrs.isPriority, $attrs.price > 500)}" },
+              "children": [
+                {
+                  "definition": "tile/row",
+                  "attributes": { "gap": "sm", "align": "center" },
+                  "children": [
+                    { "definition": "tile/icon", "attributes": { "name": "lightning", "color": "warning" } },
+                    { "definition": "tile/text", "attributes": { "text": "9. Formula-driven meta.if: priority fare over $500 — expedited handling" } }
+                  ]
+                }
+              ]
+            },
+
+            { "definition": "tile/spacer", "attributes": { "size": "sm" } },
+
+            {
+              "definition": "tile/column",
+              "meta": { "forEach": "{!$attrs.flights}", "forItem": "$flight" },
+              "attributes": { "gap": "xs" },
+              "children": [
+                { "definition": "tile/text", "attributes": { "text": "10. forEach + per-row formula", "variant": "h3" } },
+                {
+                  "definition": "tile/row",
+                  "attributes": { "justify": "between", "align": "center" },
+                  "children": [
+                    {
+                      "definition": "tile/column",
+                      "attributes": { "gap": "xs" },
+                      "children": [
+                        { "definition": "tile/text", "attributes": { "text": "{!$flight.airline} — {!$flight.flightId}", "variant": "h4" } },
+                        { "definition": "tile/text", "attributes": { "text": "Total with tax: ${!$flight.price * (1 + $flight.taxRate)}", "color": "muted" } }
+                      ]
+                    },
+                    {
+                      "definition": "tile/badge",
+                      "meta": { "if": "{!$flight.price > 1000}" },
+                      "attributes": { "label": "PREMIUM", "variant": "primary" }
+                    }
+                  ]
+                }
+              ]
+            }
+
+          ]
+        }
+      ]
+    }
+  }
+}

package/skills/platform-widget-generate/references/widget-formulas.md

@@ -0,0 +1,123 @@
+# Widget Formula Expressions
+
+A formula expression can appear anywhere a `{!...}` binding is written — `attributes` values, string interpolation, and `meta.if`. Read this file when a widget needs formulas.
+
+---
+
+## Syntax
+
+Every formula expression is wrapped in `{!...}`, similar to a plain binding:
+
+```text
+{!FUNCTION($attrs.fieldName)}
+```
+
+- **Field references inside a formula** use the same `$attrs.<path>` convention as plain bindings.
+- Inside a `forEach`, use the loop variable instead of `$attrs` — e.g. `{!UPPER($item.property)}`. Formulas inside `forEach` evaluate once per iteration against the current loop item — not the whole array.
+- Functions and operators are case-sensitive UPPERCASE.
+- A formula can nest functions and mix functions with operators: `{!TEXT(ROUND($attrs.property, 2))}`, `{!LEFT($attrs.property, 5) & "..."}`.
+- A formula-bearing attribute is still bound to schema properties the same way as a plain binding — every `$attrs.X` / `$item.X` referenced inside a formula must resolve to a real schema property or loop variable, per the `bindings-resolve` self-validation check.
+
+---
+
+## Supported functions and operators, by category
+
+Only the operators/functions listed here are confirmed supported — do not invent variants.
+
+### 1. Arithmetic operators
+
+| Operator | Meaning | Example                             |
+|---|---|-------------------------------------|
+| `+` | Add | `$attrs.operand1 + $attrs.operand2` |
+| `-` | Subtract | `$attrs.operand1 - $attrs.operand2` |
+| `*` | Multiply | `$attrs.operand1 * $attrs.operand2` |
+| `/` | Divide | `$attrs.operand1 / $attrs.operand2` |
+| `^` | Exponent | `$attrs.operand1 ^ $attrs.operand2` |
+
+Standard precedence applies (`^` > `*`/`/` > `+`/`-`); parenthesize to be explicit, especially when combining multiple arithmetic operators.
+
+### 2. Comparison operators
+
+Return `true`/`false`; commonly used inside `IF()` or `meta.if`.
+
+| Operator | Meaning | Example                                |
+|---|---|----------------------------------------|
+| `=` | Equal | `$attrs.property = 'constantValue'`    |
+| `<>` | Not equal | `$attrs.property <> 'constantValue'`   |
+| `>` / `<` | Greater / less than | `$attrs.property > 1000`               |
+| `>=` / `<=` | Greater-or-equal / less-or-equal | `$attrs.property1 >= $attrs.property2` |
+
+### 3. Logical functions
+
+| Function | Description | Example                                                                                              |
+|---|---|------------------------------------------------------------------------------------------------------|
+| `IF(cond, then, else)` | Conditional value; nests for multi-branch logic | `IF($attrs.property > value, 'result1', 'result2')`                                                  |
+| `CASE(expr, val1, res1, val2, res2, ..., default)` | Multi-way match, cleaner than nested `IF` for 3+ branches | `CASE($attrs.property, 'value1', 'result1', 'value2', 'result2', 'value3', 'result3', 'defaultResult')` |
+| `AND(...)` | All conditions true | `AND($attrs.property1, $attrs.property2 > value)`                                                    |
+| `OR(...)` | Any condition true | `OR($attrs.property1, $attrs.property2 > value)`                                                     |
+| `NOT(val)` | Negate a boolean | `NOT($attrs.property)`                                                                               |
+| `ISNULL(val)` | True if the value is null | `IF(ISNULL($attrs.property), 'null', 'has-value')`                                                   |
+| `ISBLANK(val)` | True if null or empty string | `IF(ISBLANK($attrs.property), 'blank', 'has-value')`                                                 |
+
+### 4. Text functions
+
+| Function | Description | Example                                             |
+|---|---|-----------------------------------------------------|
+| `UPPER(str)` / `LOWER(str)` | Case conversion | `UPPER($attrs.property)`                            |
+| `LEFT(str, n)` / `RIGHT(str, n)` | First/last `n` characters | `LEFT($attrs.property, 3)`                          |
+| `MID(str, start, len)` | Substring, **1-based** start index (first character is position 1, not 0) | `MID($attrs.property, 1, 3)`                        |
+| `LEN(val)` | Length of a string | `LEN($attrs.property)`                              |
+| `TRIM(str)` | Strip leading/trailing whitespace | `TRIM($attrs.property)`                             |
+| `REVERSE(str)` | Reverse a string | `REVERSE($attrs.property)`                          |
+| `SUBSTITUTE(str, old, new)` | Replace all occurrences | `SUBSTITUTE($attrs.property, 'string1', 'string2')` |
+| `FIND(search, str)` | 1-based index of `search` in `str`, or falsy if absent | `FIND('string', $attrs.property)`                   |
+| `LPAD(str, len, pad)` / `RPAD(str, len, pad)` | Pad to a fixed width | `LPAD($attrs.property, 12, '.')`                    |
+| `TEXT(val)` | Coerce a non-string value to text (commonly paired with `ROUND`) | `TEXT(ROUND($attrs.property, 2))`                   |
+| `VALUE(str)` | Parse text to a number (inverse of `TEXT`) | `VALUE($attrs.property)`                            |
+| `CONTAINS(str, sub)` | String contains substring — boolean, pair with `IF` | `CONTAINS($attrs.property, 'string')`               |
+| `BEGINS(str, prefix)` | String starts with — boolean, pair with `IF` | `BEGINS($attrs.property, 'string')`                 |
+| `&` (operator) | Concatenate strings | `$attrs.property1 & ' — ' & $attrs.property2`       |
+
+### 5. Math functions
+
+| Function | Description | Example                                        |
+|---|---|------------------------------------------------|
+| `MOD(num, div)` | Remainder | `MOD($attrs.fieldName, 100)`                   |
+| `MAX(...)` / `MIN(...)` | Largest/smallest of the arguments | `MAX($attrs.fieldName, 2000)`                  |
+| `ROUND(num, digits)` | Round to `digits` decimal places | `ROUND($attrs.fieldName, 1)`                   |
+| `ABS(num)` | Absolute value | `ABS($attrs.fieldName)`                        |
+| `SQRT(num)` | Square root | `SQRT($attrs.fieldName)`                       |
+| `CEILING(num)` / `FLOOR(num)` | Round away from / toward zero on the *magnitude* | `CEILING($attrs.fieldName)`|
+| `MCEILING(num)` / `MFLOOR(num)` | Round toward +∞ / −∞ ("mathematical" ceiling/floor) — matters for negative numbers | `MCEILING($attrs.fieldName)`, `MFLOOR($attrs.fieldName)`|
+| `LOG(num)` / `EXP(num)` / `LN(num)` | Base-10 log, e^x, natural log | `LOG($attrs.fieldName)`                              |
+
+### 6. Date & time functions
+
+| Function | Description | Example                                         |
+|---|---|-------------------------------------------------|
+| `DATEVALUE(str)` / `DATETIMEVALUE(str)` / `TIMEVALUE(str)` | Parse a date/datetime/time string into a value | `DATEVALUE($attrs.fieldName)`                   |
+| `DAY(date)` / `MONTH(date)` / `YEAR(date)` | Extract date components | `DAY(DATEVALUE($attrs.fieldName))`              |
+| `WEEKDAY(date)` | Day of week, `1`=Sunday … `7`=Saturday | `WEEKDAY(DATEVALUE($attrs.fieldName))`      |
+| `ADDMONTHS(date, n)` | Add `n` whole months to a date | `ADDMONTHS(DATEVALUE($attrs.fieldName), 3)` |
+| `TODAY()` / `NOW()` / `TIMENOW()` | Current server date / datetime / time — no arguments | `TODAY()`                                       |
+| `DATE(year, month, day)` | Construct a date literal | `DATE(2026, 12, 31)`                            |
+| `HOUR(dt)` / `MINUTE(dt)` / `SECOND(dt)` / `MILLISECOND(dt)` | Extract time components from a datetime | `HOUR(NOW())`                                   |
+
+A raw date/datetime **string** attribute (e.g. an ISO string from `$attrs`) must be parsed with `DATEVALUE`/`DATETIMEVALUE`/`TIMEVALUE` before date-math or extractor functions can operate on it.
+
+### 7. Validation & encoding functions
+
+| Function | Description | Example                                      |
+|---|---|----------------------------------------------|
+| `NULLVALUE(val, fallback)` | `fallback` only when `val` is null | `NULLVALUE($attrs.fieldName, 'fallback')`    |
+| `BLANKVALUE(val, fallback)` | `fallback` when `val` is null or an empty string | `BLANKVALUE($attrs.fieldName, 'fallback')`   |
+| `HTMLENCODE(str)` | Escape for literal HTML display — use on any text binding that must render literally rather than as markup | `HTMLENCODE($attrs.fieldName & ' <b>tag</b>')` |
+| `JSENCODE(str)` | Escape for safe embedding in a JS-string context | `JSENCODE($attrs.fieldName & "'quote")`        |
+
+### 8. Pattern matching functions
+
+| Function | Description | Example |
+|---|---|---|
+| `ISNUMBER(val)` | True if the value parses as a number | `ISNUMBER($attrs.fieldName)` |
+| `REGEX(str, pattern)` | True if `str` matches the regex `pattern` (standard regex string) | `REGEX($attrs.fieldName, '^[A-Z]{2} [0-9]+$')` |
+

package/skills/platform-widget-generate/references/widget-meta-directives.md

@@ -1,4 +1,4 @@
-# Widget Meta Directives Reference
+# Widget Meta Directives
 
 The `meta` object on a UEM block carries runtime directives for iteration (`forEach` / `forItem`) and conditional rendering (`if`). Read this file when a widget needs either.
 
@@ -79,8 +79,8 @@ The inner `forEach` references an array on the outer loop variable and uses a di
 ### Rules
 
 - Place `if` on the `meta` object of the block.
-- Use `if` only when the schema has a `lightning__booleanType` property suited to the condition. Bind directly to that property (or to a loop variable holding such a value). If no suitable boolean exists in the schema, do not use `if` — render the block unconditionally instead.
-- Do not lean on the truthiness of strings (`""` vs `"value"`), numbers (`0` vs `1`), or nullable fields — that may render today but is not guaranteed across surfaces. Comparisons, arithmetic, and string operations are not supported.
+- `if` accepts either a bare `lightning__booleanType` property (or a loop variable holding one) OR a **formula expression** that evaluates to a boolean — comparisons (`{!$attrs.fieldName > 1000}`) and logical functions (`{!AND($attrs.fieldName1, $attrs.fieldName2 > 500)}`) are both valid. See `references/widget-formulas.md` for the full formula syntax and supported-function list.
+- Do not lean on the truthiness of a raw string (`""` vs `"value"`) or number (`0` vs `1`) bound directly — that relies on implicit coercion and is unreliable. Bind to a real boolean property, or use an explicit formula comparison instead.
 - `if` may coexist with `forEach` on the same `meta`. `if` is evaluated first — if `false`, the loop is skipped entirely.
 
 ### Example — top-level boolean
@@ -126,5 +126,5 @@ The inner `forEach` references an array on the outer loop variable and uses a di
 
 | Issue | Resolution |
 |---|---|
-| `if` bound to a non-boolean (string or number) does not behave as expected | Use `if` only when the schema has a `lightning__booleanType` property; otherwise render the block unconditionally |
+| `if` bound directly to a raw string or number relies on truthiness and is unreliable | Bind to a `lightning__booleanType` property, or use a formula comparison that evaluates to boolean — see `references/widget-formulas.md` |
 | Nested loops share the same `forItem` name | Pick distinct names (e.g. `$item` outer, `$line` inner) — there is no validation error on collision |