feat(QTDI-2979): Add labelDisplayMode attribute to @Suggestable

[thboileau]

Requirements

• Any code change adding any logic MUST be tested through a unit test executed with the default build
• Any API addition MUST be done with a documentation update if relevant

Why this PR is needed?

Jira: QTDI-2979 — Allow to configure how the labels are displayed for a suggestable field

When two or more @Suggestable options share the same label, the Studio user cannot distinguish between them. Selecting the wrong option leads to misconfigured jobs that may only fail at runtime, which is costly to debug.

This PR provides a TCK-level mechanism that allows component developers to declare that their suggestable field may have non-unique labels, so that the front-end can surface enough information for an unambiguous choice.

What does this PR adds (design/code thoughts)?

component-api — Suggestable.java

• Adds an inner enum LabelDisplayMode with two constants:
  • LABEL (default) — show option label only; no change for existing usages.
  • LABEL_ID — show both label and identifier (e.g. Paris (fr-paris-01)); use when labels may not be unique.
• Adds annotation attribute labelDisplayMode() defaulting to LabelDisplayMode.LABEL.

Serialisation (no change to ActionParameterEnricher)

The existing ActionParameterEnricher already serialises all annotation methods generically. The new attribute appears automatically in the component metadata map as:

tcomp::action::suggestions::labelDisplayMode = "LABEL"   // or "LABEL_ID"

No changes to component-server-model are required — SimplePropertyDefinition.metadata is already a Map<String, String>.

Tests — ActionParameterEnricherTest.java

• Updated suggestion() test: asserts that the default value produces labelDisplayMode = "LABEL" in the serialised metadata.
• New suggestionWithLabelId() test: asserts that setting labelDisplayMode = LABEL_ID produces labelDisplayMode = "LABEL_ID".

Backward compatibility

The attribute defaults to LABEL. All existing @Suggestable usages gain labelDisplayMode = LABEL in their metadata map — additive, transparent to consumers that do not know the key.

Out of scope

• Studio rendering (separate future ticket)
• BuiltInSuggestable — not affected
• Documentation ticket (PO to open)

AI generated code

https://internal.qlik.dev/general/ways-of-working/code-reviews/#guidelines-for-ai-generated-code

• this PR has been written with the help of GitHub Copilot or another generative AI tool

[thboileau]

🔍 Scope & Design Review — QTDI-2979

Round 1 — Final verdict: APPROVED

AC Coverage

AC	Requirement	Status
AC-1	@Suggestable gains optional labelDisplayMode attribute	✅ PASS
AC-2	Enum LABEL (default) + LABEL_ID	✅ PASS
AC-3	Declared in component-api, serialised via ActionParameterEnricher	✅ PASS
AC-4	Default LABEL, backward compatible — additive only	✅ PASS
AC-5	Front-ends can read from metadata map	✅ PASS

Edge cases — all clear

• Null not possible for annotation attributes (Java guarantee).
• Suggestable.LabelDisplayMode is a public inner enum — accessible to all callers.
• Serialised value "LABEL" / "LABEL_ID" (uppercase) is consistent with codebase convention (BuiltInSuggestable.Name also uppercases).
• Backward compat confirmed: existing @Suggestable usages gain labelDisplayMode=LABEL in their metadata map (additive, ignored by consumers that don't know the key).
• Anonymous-class test pattern is consistent with all other tests in the file.

Findings

Severity	Finding	Action
(none)	—	—

Review performed by AI (GitHub Copilot). Scope and design decisions validated by Dev before implementation.

[thboileau]

✅ Compliance Check — QTDI-2979

Summary

Severity	Count
Critical (fixed)	0
Warning	0
Info	0

File-by-file findings

component-api/.../Suggestable.java

Rule	Status	Notes
No wildcard imports	✅ PASS	No new imports added
Javadoc on new labelDisplayMode()	✅ PASS	Has @return and description
Javadoc on LabelDisplayMode enum constants	✅ PASS	Both LABEL and LABEL_ID have Javadoc
No deprecation of existing API	✅ PASS	Purely additive
Spotless	✅ PASS	mvn spotless:check — no violations

component-runtime-manager/.../ActionParameterEnricherTest.java

Rule	Status	Notes
Test class naming (Test suffix)	✅ PASS	ActionParameterEnricherTest
Same package as production class	✅ PASS	Both parameterenricher package
No wildcard imports	✅ PASS	No new imports
UT coverage — new behaviour	✅ PASS	suggestionWithLabelId() covers LABEL_ID; suggestion() covers LABEL default
No TUJ required	✅ PASS	Purely additive schema change; no Studio-level integration risk identified
Spotless	✅ PASS	mvn spotless:check — no violations

Quality rules

Rule	Status
UT for every behaviour change	✅ PASS
TUJ scope check	N/A — no TUJ needed (UT-only scope confirmed)
DOC ticket	PO responsibility

Verdict: COMPLIANT — no Critical findings.

Compliance check performed by AI (GitHub Copilot).

[sonar-rnd]

Quality Gate passed

Issues

• 0 New Issues
• 1 Fixed Issue
• 0 Accepted Issues

Measures

• 0 Security Hotspots
• 0.00% Coverage (0.00% Estimated after merge)
• 0.00% Duplicated Code (1.50% Estimated after merge)

Project ID: org.talend.sdk.component:component-runtime

View in SonarQube