[WTF-1967]: Generate widget property types for metadata associations (#…

…106)

## Checklist

-   Contains unit tests ✅ 
-   Contains breaking changes ❌
-   Compatible with: MX 🔟
- Did you update version and changelog? ❌ (This will be done after the
release.)
-   PR title properly formatted (`[XX-000]: description`)? ✅ 

## This PR contains

-   [ ] Bug fix
-   [x] Feature
-   [ ] Refactor
-   [ ] Documentation
-   [ ] Other (describe)

## What is the purpose of this PR?
This PR introduces types generation for `AssociationMetaData`.

## Relevant changes
Client types generator is adjusted to incorporate the recently developed
PW API of flexible filtering over associations.

## What should be covered while testing?
Testing should include, creating a `AssociationMetaData` property in the
Widget Definition XML and verifying (after building the widget to
trigger the generator) the resulting widget property TypeScript types.

packages/pluggable-widgets-tools/CHANGELOG.md

@@ -6,6 +6,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Added
+
+-   We added the property type AssociationMetaData which exposes useful metadata for filtering and sorting datasources.
+
+### Changed
+
+-   We updated the Mendix package to 10.16.49747.
+
 ## [10.15.0] - 2024-09-24
 
 ### Added

packages/pluggable-widgets-tools/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mendix/pluggable-widgets-tools",
-  "version": "10.15.0",
+  "version": "10.16.0",
   "description": "Mendix Pluggable Widgets Tools",
   "engines": {
     "node": ">=16"
@@ -80,7 +80,7 @@
     "jest-junit": "^13.0.0",
     "jest-react-hooks-shallow": "^1.5.1",
     "make-dir": "^3.1.0",
-    "mendix": "^10.15.46408",
+    "mendix": "^10.16.49747",
     "metro-react-native-babel-preset": "^0.74.1",
     "mime": "^3.0.0",
     "node-fetch": "^2.6.1",

packages/pluggable-widgets-tools/src/typings-generator/__tests__/index.spec.ts

@@ -41,6 +41,8 @@ import {
 } from "./outputs/non-linked-list-attribute-refset";
 import { attributeMetaDataNativeInput, attributeMetaDataWebInput } from "./inputs/metadata-attribute";
 import { attributeMetaDataNativeOutput, attributeMetaDataWebOutput } from "./outputs/metadata-attribute";
+import { associationMetaDataNativeInput, associationMetaDataWebInput } from "./inputs/metadata-association";
+import { associationMetaDataNativeOutput, associationMetaDataWebOutput } from "./outputs/metadata-association";
 
 describe("Generating tests", () => {
     it("Generates a parsed typing from XML for native", () => {
@@ -212,6 +214,16 @@ describe("Generating tests", () => {
         const newContent = generateNativeTypesFor(attributeMetaDataNativeInput);
         expect(newContent).toBe(attributeMetaDataNativeOutput);
     });
+
+    it("Generates a parsed typing from XML for web using metadata association", () => {
+        const newContent = generateFullTypesFor(associationMetaDataWebInput);
+        expect(newContent).toBe(associationMetaDataWebOutput);
+    });
+
+    it("Generates a parsed typing from XML for native using metadata association", () => {
+        const newContent = generateNativeTypesFor(associationMetaDataNativeInput);
+        expect(newContent).toBe(associationMetaDataNativeOutput);
+    });
 });
 
 function generateFullTypesFor(xml: string) {

packages/pluggable-widgets-tools/src/typings-generator/__tests__/inputs/metadata-association.ts

@@ -0,0 +1,56 @@
+export const associationMetaDataWebInput = `<?xml version="1.0" encoding="utf-8"?>
+<widget id="mendix.mywidget.MyWidget" needsEntityContext="true" offlineCapable="true"
+    pluginWidget="true" supportedPlatform="Web"
+    xmlns="http://www.mendix.com/widget/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.mendix.com/widget/1.0/ ../xsd/widget.xsd">
+    <properties>
+        <propertyGroup caption="General">
+            <property key="data" type="datasource" isList="true">
+                <caption>Reference</caption>
+                <description />
+            </property>
+            <property key="metaReference" type="association" isMetaData="true" dataSource="data">
+                <caption>Reference</caption>
+                <description />
+                <associationTypes>
+                    <associationType name="Reference" />
+                </associationTypes>
+            </property>
+            <property key="metaReferenceSet" type="association" isMetaData="true" dataSource="data">
+                <caption>Reference</caption>
+                <description />
+                <associationTypes>
+                    <associationType name="ReferenceSet" />
+                </associationTypes>
+            </property>
+        </propertyGroup>
+    </properties>
+</widget>`;
+export const associationMetaDataNativeInput = `<?xml version="1.0" encoding="utf-8"?>
+<widget id="mendix.mywidget.MyWidget" needsEntityContext="true" offlineCapable="true"
+    pluginWidget="true" supportedPlatform="Native"
+    xmlns="http://www.mendix.com/widget/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://www.mendix.com/widget/1.0/ ../xsd/widget.xsd">
+    <properties>
+        <propertyGroup caption="General">
+            <property key="data" type="datasource" isList="true">
+                <caption>Reference</caption>
+                <description />
+            </property>
+            <property key="metaReference" type="association" isMetaData="true" dataSource="data">
+                <caption>Reference</caption>
+                <description />
+                <associationTypes>
+                    <associationType name="Reference" />
+                </associationTypes>
+            </property>
+            <property key="metaReferenceSet" type="association" isMetaData="true" dataSource="data">
+                <caption>Reference</caption>
+                <description />
+                <associationTypes>
+                    <associationType name="ReferenceSet" />
+                </associationTypes>
+            </property>
+        </propertyGroup>
+    </properties>
+</widget>`;

packages/pluggable-widgets-tools/src/typings-generator/__tests__/inputs/metadata-attribute.ts

@@ -27,6 +27,7 @@ export const attributeMetaDataWebInput = `<?xml version="1.0" encoding="utf-8"?>
         </propertyGroup>
     </properties>
 </widget>`;
+
 export const attributeMetaDataNativeInput = `<?xml version="1.0" encoding="utf-8"?>
 <widget id="mendix.mywidget.MyWidget" needsEntityContext="true" offlineCapable="true"
     pluginWidget="true" supportedPlatform="Native"

packages/pluggable-widgets-tools/src/typings-generator/__tests__/outputs/metadata-association.ts

@@ -0,0 +1,41 @@
+export const associationMetaDataWebOutput = `/**
+ * This file was generated from MyWidget.xml
+ * WARNING: All changes made to this file will be overwritten
+ * @author Mendix Widgets Framework Team
+ */
+import { CSSProperties } from "react";
+import { AssociationMetaData, ListValue } from "mendix";
+
+export interface MyWidgetContainerProps {
+    name: string;
+    class: string;
+    style?: CSSProperties;
+    tabIndex?: number;
+    data: ListValue;
+    metaReference: AssociationMetaData;
+    metaReferenceSet: AssociationMetaData;
+}
+
+export interface MyWidgetPreviewProps {
+    /**
+     * @deprecated Deprecated since version 9.18.0. Please use class property instead.
+     */
+    className: string;
+    class: string;
+    style: string;
+    styleObject?: CSSProperties;
+    readOnly: boolean;
+    renderMode?: "design" | "xray" | "structure";
+    data: {} | { caption: string } | { type: string } | null;
+    metaReference: string;
+    metaReferenceSet: string;
+}
+`;
+
+export const associationMetaDataNativeOutput = `export interface MyWidgetProps<Style> {
+    name: string;
+    style: Style[];
+    data: ListValue;
+    metaReference: AssociationMetaData;
+    metaReferenceSet: AssociationMetaData;
+}`;

packages/pluggable-widgets-tools/src/typings-generator/generate.ts

@@ -5,6 +5,7 @@ import { WidgetXml } from "./WidgetXml";
 
 const mxExports = [
     "ActionValue",
+    "AssociationMetaData",
     "AttributeMetaData",
     "DynamicValue",
     "EditableValue",

packages/pluggable-widgets-tools/src/typings-generator/generateClientTypes.ts

@@ -141,7 +141,7 @@ function toClientPropType(
                 if (!linkedToDataSource) {
                     throw new Error(`[XML] Attribute property can only have isMetaData="true" when linked to a datasource`);
                 }
-                return `AttributeMetaData<${unionType}>`
+                return `AttributeMetaData<${unionType}>`;
             }
 
             if (!prop.associationTypes?.length) {
@@ -158,9 +158,18 @@ function toClientPropType(
             if (!prop.associationTypes?.length) {
                 throw new Error("[XML] Association property requires associationTypes element");
             }
+
+            const linkedToDataSource = !!prop.$.dataSource;
+            if (prop.$.isMetaData === "true") {
+                if (!linkedToDataSource) {
+                    throw new Error(`[XML] Association property can only have isMetaData="true" when linked to a datasource`);
+                }
+                return "AssociationMetaData";
+            }
+
             const types = prop.associationTypes
                 .flatMap(ats => ats.associationType)
-                .map(at => toAssociationOutputType(at.$.name, !!prop.$.dataSource));
+                .map(at => toAssociationOutputType(at.$.name, linkedToDataSource));
             return toUniqueUnionType(types);
         }
         case "expression":