001/**
002 * Copyright (C) 2006-2026 Talend Inc. - www.talend.com
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.talend.sdk.component.api.configuration.action;
017
018import static java.lang.annotation.ElementType.FIELD;
019import static java.lang.annotation.ElementType.PARAMETER;
020import static java.lang.annotation.RetentionPolicy.RUNTIME;
021
022import java.lang.annotation.Retention;
023import java.lang.annotation.Target;
024
025import org.talend.sdk.component.api.configuration.action.meta.ActionRef;
026import org.talend.sdk.component.api.meta.Documentation;
027import org.talend.sdk.component.api.service.completion.Suggestions;
028
029@ActionRef(Suggestions.class)
030@Documentation("Mark the decorated field as supporting suggestions, i.e. dynamically get a list of valid values the user can use. "
031        + "Note that if you are looking to provide proposals by form (depending the option(s) values), @Suggestable is a better fit.")
032@Target({ FIELD, PARAMETER })
033@Retention(RUNTIME)
034public @interface Suggestable {
035
036    /**
037     * @return value of @{@link Suggestions} value method.
038     */
039    String value();
040
041    /**
042     * This "list" will represent the parameter the caller will send to the suggestions implementation.
043     *
044     * Syntax is the following:
045     *
046     * <ul>
047     * <li>.: represents the decorated option (aka "this")</li>
048     * <li>../foo: represents the
049     *
050     * <pre>
051     * foo
052     * </pre>
053     *
054     * option of the parent (if exists) of "."</li>
055     * <li>bar: represents the
056     *
057     * <pre>
058     * bar
059     * </pre>
060     *
061     * sibling option of the decorated field</li>
062     * <li>bar/dummy: represents the
063     *
064     * <pre>
065     * dummy
066     * </pre>
067     *
068     * option of the child bar of the decorated field</li>
069     * </ul>
070     *
071     * This syntax is close to path syntax but the important point is all the parameters are related to the decorated
072     * option.
073     *
074     * @return parameters for the validation.
075     */
076    String[] parameters() default { "." };
077
078    /**
079     * Controls how each suggestion option is rendered in the UI.
080     * Use {@link LabelDisplayMode#LABEL_ID} when option labels may not be unique,
081     * so that the identifier is shown alongside the label to allow unambiguous selection.
082     * Defaults to {@link LabelDisplayMode#LABEL} — preserves full backward compatibility.
083     *
084     * @return the display mode for suggestion options.
085     */
086    LabelDisplayMode labelDisplayMode() default LabelDisplayMode.LABEL;
087
088    /**
089     * Defines how suggestion options are displayed in the UI.
090     */
091    enum LabelDisplayMode {
092
093        /**
094         * Display the option label only.
095         * Default behaviour — use this when labels are unique.
096         */
097        LABEL,
098
099        /**
100         * Display both the label and the identifier, e.g. {@code Paris (fr-paris-01)}.
101         * Use this when labels may not be unique so that the user can make an unambiguous choice.
102         */
103        LABEL_ID
104    }
105}