Add clickable help icons for developer settings (#1522)

* initial tooltip

* remove extra text

* add chat tooltips

* improve for clarity

* add gpt4 vision tooltip

* add ask tooltips

* Use help callouts instead

* Use help callouts instead

* Playwright tests

* Updated text

* Fix E2E tests

* Fix vector settings default

* Update e2e test

* Adding e2e fix

---------

Co-authored-by: John Aziz <[email protected]>

Author: pamelafox

app/frontend/src/components/GPT4VSettings/GPT4VSettings.tsx

@@ -1,8 +1,11 @@
 import { useEffect, useState } from "react";
-import { Stack, Checkbox, IDropdownOption, Dropdown } from "@fluentui/react";
+import { Stack, Checkbox, ICheckboxProps, IDropdownOption, IDropdownProps, Dropdown } from "@fluentui/react";
+import { useId } from "@fluentui/react-hooks";
 
 import styles from "./GPT4VSettings.module.css";
 import { GPT4VInput } from "../../api";
+import { HelpCallout } from "../../components/HelpCallout";
+import { toolTipText } from "../../i18n/tooltips.js";
 
 interface Props {
     gpt4vInputs: GPT4VInput;
@@ -32,23 +35,42 @@ export const GPT4VSettings = ({ updateGPT4VInputs, updateUseGPT4V, isUseGPT4V, g
         useGPT4V && updateGPT4VInputs(GPT4VInput.TextAndImages);
     }, [useGPT4V]);
 
+    const useGPT4VId = useId("useGPT4V");
+    const useGPT4VFieldId = useId("useGPT4VField");
+    const gpt4VInputId = useId("gpt4VInput");
+    const gpt4VInputFieldId = useId("gpt4VInputField");
+
     return (
         <Stack className={styles.container} tokens={{ childrenGap: 10 }}>
-            <Checkbox checked={useGPT4V} label="Use GPT vision model" onChange={onuseGPT4V} />
+            <Checkbox
+                id={useGPT4VFieldId}
+                checked={useGPT4V}
+                label="Use GPT vision model"
+                onChange={onuseGPT4V}
+                aria-labelledby={useGPT4VId}
+                onRenderLabel={(props: ICheckboxProps | undefined) => (
+                    <HelpCallout labelId={useGPT4VId} fieldId={useGPT4VFieldId} helpText={toolTipText.useGPT4Vision} label={props?.label} />
+                )}
+            />
             {useGPT4V && (
                 <Dropdown
+                    id={gpt4VInputFieldId}
                     selectedKey={vectorFieldOption}
-                    label="GPT-4 Turbo with Vision Inputs"
+                    label="GPT vision model inputs"
                     options={[
                         {
                             key: GPT4VInput.TextAndImages,
-                            text: "Images and text from index"
+                            text: "Images and text"
                         },
-                        { text: "Images only", key: GPT4VInput.Images },
-                        { text: "Text only", key: GPT4VInput.Texts }
+                        { text: "Images", key: GPT4VInput.Images },
+                        { text: "Text", key: GPT4VInput.Texts }
                     ]}
                     required
                     onChange={onSetGPT4VInput}
+                    aria-labelledby={gpt4VInputId}
+                    onRenderLabel={(props: IDropdownProps | undefined) => (
+                        <HelpCallout labelId={gpt4VInputId} fieldId={gpt4VInputFieldId} helpText={toolTipText.gpt4VisionInputs} label={props?.label} />
+                    )}
                 />
             )}
         </Stack>

app/frontend/src/components/HelpCallout/HelpCallout.tsx

@@ -0,0 +1,43 @@
+import { ITextFieldProps, DefaultButton, IconButton, IButtonStyles, Callout, IStackTokens, Stack, IStackStyles, initializeIcons } from "@fluentui/react";
+import { useBoolean, useId } from "@fluentui/react-hooks";
+
+const stackTokens: IStackTokens = {
+    childrenGap: 4,
+    maxWidth: 300
+};
+
+const labelCalloutStackStyles: Partial<IStackStyles> = { root: { padding: 20 } };
+const iconButtonStyles: Partial<IButtonStyles> = { root: { marginBottom: -3 } };
+const iconProps = { iconName: "Info" };
+
+interface IHelpCalloutProps {
+    label: string | undefined;
+    labelId: string;
+    fieldId: string | undefined;
+    helpText: string;
+}
+
+export const HelpCallout = (props: IHelpCalloutProps): JSX.Element => {
+    const [isCalloutVisible, { toggle: toggleIsCalloutVisible }] = useBoolean(false);
+    const descriptionId: string = useId("description");
+    const iconButtonId: string = useId("iconButton");
+
+    return (
+        <>
+            <Stack horizontal verticalAlign="center" tokens={stackTokens}>
+                <label id={props.labelId} htmlFor={props.fieldId}>
+                    {props.label}
+                </label>
+                <IconButton id={iconButtonId} iconProps={iconProps} title="Info" ariaLabel="Info" onClick={toggleIsCalloutVisible} styles={iconButtonStyles} />
+            </Stack>
+            {isCalloutVisible && (
+                <Callout target={"#" + iconButtonId} setInitialFocus onDismiss={toggleIsCalloutVisible} ariaDescribedBy={descriptionId} role="alertdialog">
+                    <Stack tokens={stackTokens} horizontalAlign="start" styles={labelCalloutStackStyles}>
+                        <span id={descriptionId}>{props.helpText}</span>
+                        <DefaultButton onClick={toggleIsCalloutVisible}>Close</DefaultButton>
+                    </Stack>
+                </Callout>
+            )}
+        </>
+    );
+};

app/frontend/src/components/HelpCallout/index.ts

@@ -0,0 +1 @@
+export * from "./HelpCallout";

app/frontend/src/components/VectorSettings/VectorSettings.tsx

@@ -1,8 +1,11 @@
 import { useEffect, useState } from "react";
-import { ChoiceGroup, IChoiceGroupOption, Stack, IDropdownOption, Dropdown } from "@fluentui/react";
+import { Stack, IDropdownOption, Dropdown, IDropdownProps } from "@fluentui/react";
+import { useId } from "@fluentui/react-hooks";
 
 import styles from "./VectorSettings.module.css";
+import { HelpCallout } from "../../components/HelpCallout";
 import { RetrievalMode, VectorFieldOptions } from "../../api";
+import { toolTipText } from "../../i18n/tooltips.js";
 
 interface Props {
     showImageOptions?: boolean;
@@ -11,39 +14,18 @@ interface Props {
     updateVectorFields: (options: VectorFieldOptions[]) => void;
 }
 
-const vectorFields: IChoiceGroupOption[] = [
-    {
-        key: VectorFieldOptions.Embedding,
-        text: "Text Embeddings"
-    },
-    {
-        key: VectorFieldOptions.ImageEmbedding,
-        text: "Image Embeddings"
-    },
-    {
-        key: VectorFieldOptions.Both,
-        text: "Text and Image embeddings"
-    }
-];
-
 export const VectorSettings = ({ updateRetrievalMode, updateVectorFields, showImageOptions, defaultRetrievalMode }: Props) => {
     const [retrievalMode, setRetrievalMode] = useState<RetrievalMode>(RetrievalMode.Hybrid);
-    const [vectorFieldOption, setVectorFieldOption] = useState<string>();
+    const [vectorFieldOption, setVectorFieldOption] = useState<VectorFieldOptions>(VectorFieldOptions.Both);
 
     const onRetrievalModeChange = (_ev: React.FormEvent<HTMLDivElement>, option?: IDropdownOption<RetrievalMode> | undefined) => {
         setRetrievalMode(option?.data || RetrievalMode.Hybrid);
         updateRetrievalMode(option?.data || RetrievalMode.Hybrid);
     };
 
-    const onVectorFieldsChange = (_ev?: React.FormEvent<HTMLElement | HTMLInputElement>, option?: IChoiceGroupOption) => {
-        option && setVectorFieldOption(option.key);
-        let list;
-        if (option?.key === "both") {
-            list = [VectorFieldOptions.Embedding, VectorFieldOptions.ImageEmbedding];
-        } else {
-            list = [option?.key as VectorFieldOptions];
-        }
-        updateVectorFields(list);
+    const onVectorFieldsChange = (_ev: React.FormEvent<HTMLDivElement>, option?: IDropdownOption<RetrievalMode> | undefined) => {
+        setVectorFieldOption(option?.key as VectorFieldOptions);
+        updateVectorFields([option?.key as VectorFieldOptions]);
     };
 
     useEffect(() => {
@@ -52,9 +34,15 @@ export const VectorSettings = ({ updateRetrievalMode, updateVectorFields, showIm
             : updateVectorFields([VectorFieldOptions.Embedding]);
     }, [showImageOptions]);
 
+    const retrievalModeId = useId("retrievalMode");
+    const retrievalModeFieldId = useId("retrievalModeField");
+    const vectorFieldsId = useId("vectorFields");
+    const vectorFieldsFieldId = useId("vectorFieldsField");
+
     return (
         <Stack className={styles.container} tokens={{ childrenGap: 10 }}>
             <Dropdown
+                id={retrievalModeFieldId}
                 label="Retrieval mode"
                 selectedKey={defaultRetrievalMode.toString()}
                 options={[
@@ -64,15 +52,26 @@ export const VectorSettings = ({ updateRetrievalMode, updateVectorFields, showIm
                 ]}
                 required
                 onChange={onRetrievalModeChange}
+                aria-labelledby={retrievalModeId}
+                onRenderLabel={(props: IDropdownProps | undefined) => (
+                    <HelpCallout labelId={retrievalModeId} fieldId={retrievalModeFieldId} helpText={toolTipText.retrievalMode} label={props?.label} />
+                )}
             />
 
             {showImageOptions && [RetrievalMode.Vectors, RetrievalMode.Hybrid].includes(retrievalMode) && (
-                <ChoiceGroup
-                    options={vectorFields}
+                <Dropdown
+                    id={vectorFieldsFieldId}
+                    label="Vector fields (Multi-query vector search)"
+                    options={[
+                        { key: VectorFieldOptions.Embedding, text: "Text Embeddings", selected: vectorFieldOption === VectorFieldOptions.Embedding },
+                        { key: VectorFieldOptions.ImageEmbedding, text: "Image Embeddings", selected: vectorFieldOption === VectorFieldOptions.ImageEmbedding },
+                        { key: VectorFieldOptions.Both, text: "Text and Image embeddings", selected: vectorFieldOption === VectorFieldOptions.Both }
+                    ]}
                     onChange={onVectorFieldsChange}
-                    selectedKey={vectorFieldOption}
-                    defaultSelectedKey={VectorFieldOptions.Both}
-                    label="Vector Fields (Multi-query vector search)"
+                    aria-labelledby={vectorFieldsId}
+                    onRenderLabel={(props: IDropdownProps | undefined) => (
+                        <HelpCallout labelId={vectorFieldsId} fieldId={vectorFieldsFieldId} helpText={toolTipText.vectorFields} label={props?.label} />
+                    )}
                 />
             )}
         </Stack>

app/frontend/src/i18n/tooltips.ts

@@ -0,0 +1,29 @@
+// Keep values less than 20 words.
+// Don't add links to the tooltips.
+export const toolTipText = {
+    promptTemplate:
+        "Overrides the prompt used to generate the answer based on the question and search results. To append to existing prompt instead of replace whole prompt, start your prompt with '>>>'.",
+    temperature:
+        "Sets the temperature of the request to the LLM that generates the answer. Higher temperatures result in more creative responses, but they may be less grounded.",
+    searchScore:
+        "Sets a minimum score for search results coming back from Azure AI search. The score range depends on whether you're using hybrid (default), vectors only, or text only.",
+    rerankerScore:
+        "Sets a minimum score for search results coming back from the semantic reranker. The score always ranges between 1-4. The higher the score, the more semantically relevant the result is to the question.",
+    retrieveNumber:
+        "Sets the number of search results to retrieve from Azure AI search. More results may increase the likelihood of finding the correct answer, but may lead to the model getting 'lost in the middle'.",
+    excludeCategory: "Specifies a category to exclude from the search results. There are no categories used in the default data set.",
+    useSemanticReranker: "Enables the Azure AI Search semantic ranker, a model that re-ranks search results based on semantic similarity to the user's query.",
+    useSemanticCaptions:
+        "Sends semantic captions to the LLM instead of the full search result. A semantic caption is extracted from a search result during the process of semantic ranking.",
+    suggestFollowupQuestions: "Asks the LLM to suggest follow-up questions based on the user's query.",
+    useGPT4Vision: "Uses GPT-4-Turbo with Vision to generate responses based on images and text from the index.",
+    vectorFields:
+        "Specifies which embedding fields in the Azure AI Search Index will be searched, both the 'Images and text' embeddings, 'Images' only, or 'Text' only.",
+    gpt4VisionInputs:
+        "Sets what will be send to the vision model. 'Images and text' sends both images and text to the model, 'Images' sends only images, and 'Text' sends only text.",
+    retrievalMode:
+        "Sets the retrieval mode for the Azure AI Search query. `Vectors + Text (Hybrid)` uses a combination of vector search and full text search, `Vectors` uses only vector search, and `Text` uses only full text search. Hybrid is generally optimal.",
+    streamChat: "Continuously streams the response to the chat UI as it is generated.",
+    useOidSecurityFilter: "Filter search results based on the authenticated user's OID.",
+    useGroupsSecurityFilter: "Filter search results based on the authenticated user's groups."
+};