@microsoft/agents-hosting-dialogs 0.1.49

package/src/prompts/prompt.ts

@@ -0,0 +1,459 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Activity, ActivityTypes, InputHints, MessageFactory, TurnContext } from '@microsoft/agents-hosting'
+import { Choice, ChoiceFactory, ChoiceFactoryOptions } from '../choices'
+import { Dialog } from '../dialog'
+import { DialogContext } from '../dialogContext'
+import { DialogInstance } from '../dialogInstance'
+import { DialogTurnResult } from '../dialogTurnResult'
+import { DialogReason } from '../dialogReason'
+import { DialogEvent } from '../dialogEvent'
+
+/**
+ * Controls the way that choices for a `ChoicePrompt` or yes/no options for a `ConfirmPrompt` are
+ * presented to a user.
+ */
+export enum ListStyle {
+  /**
+     * Don't include any choices for prompt.
+     */
+  none,
+
+  /**
+     * Automatically select the appropriate style for the current channel.
+     */
+  auto,
+
+  /**
+     * Add choices to prompt as an inline list.
+     */
+  inline,
+
+  /**
+     * Add choices to prompt as a numbered list.
+     */
+  list,
+
+  /**
+     * Add choices to prompt as suggested actions.
+     */
+  suggestedAction,
+
+  /**
+     * Add choices to prompt as a HeroCard with buttons.
+     */
+  heroCard,
+}
+
+/**
+ * Basic configuration options supported by all prompts.
+ */
+export interface PromptOptions {
+  /**
+     * (Optional) Initial prompt to send the user.
+     */
+  prompt?: string | Activity;
+
+  /**
+     * (Optional) Retry prompt to send the user.
+     */
+  retryPrompt?: string | Activity;
+
+  /**
+     * (Optional) List of choices associated with the prompt.
+     */
+  choices?: (string | Choice)[];
+
+  /**
+     * (Optional) Property that can be used to override or set the value of ChoicePrompt.Style
+     * when the prompt is executed using DialogContext.prompt.
+     */
+  style?: ListStyle;
+
+  /**
+     * (Optional) Additional validation rules to pass the prompts validator routine.
+     */
+  validations?: object;
+
+  /**
+     * The locale to be use for recognizing the utterance.
+     */
+  recognizeLanguage?: string;
+}
+
+/**
+ * Result returned by a prompts recognizer function.
+ *
+ * @param T Type of value being recognized.
+ */
+export interface PromptRecognizerResult<T> {
+  /**
+     * If `true` the users utterance was successfully recognized and [value](#value) contains the
+     * recognized result.
+     */
+  succeeded: boolean;
+
+  /**
+     * Value that was recognized if [succeeded](#succeeded) is `true`.
+     */
+  value?: T;
+}
+
+/**
+ * Function signature for providing a custom prompt validator.
+ *
+ * ```TypeScript
+ * type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>;
+ * ```
+ *
+ * @remarks
+ * The validator should be an asynchronous function that returns `true` if
+ * `prompt.recognized.value` is valid and the prompt should end.
+ *
+ * > [!NOTE]
+ * > If the validator returns `false` the prompts default re-prompt logic will be run unless the
+ * > validator sends a custom re-prompt to the user using `prompt.context.sendActivity()`. In that
+ * > case the prompts default re-rpompt logic will not be run.
+ * @param T Type of recognizer result being validated.
+ * @param PromptValidator.prompt Contextual information containing the recognizer result and original options passed to the prompt.
+ */
+export type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>
+
+/**
+ * Contextual information passed to a custom `PromptValidator`.
+ *
+ * @param T Type of recognizer result being validated.
+ */
+export interface PromptValidatorContext<T> {
+  /**
+     * The context for the current turn of conversation with the user.
+     *
+     * @remarks
+     * The validator can use this to re-prompt the user.
+     */
+  readonly context: TurnContext;
+
+  /**
+     * Result returned from the prompts recognizer function.
+     *
+     * @remarks
+     * The `prompt.recognized.succeeded` field can be checked to determine of the recognizer found
+     * anything and then the value can be retrieved from `prompt.recognized.value`.
+     */
+  readonly recognized: PromptRecognizerResult<T>;
+
+  /**
+     * A dictionary of values persisted for each conversational turn while the prompt is active.
+     *
+     * @remarks
+     * The validator can use this to persist things like turn counts or other state information.
+     */
+  readonly state: object;
+
+  /**
+     * Original set of options passed to the prompt by the calling dialog.
+     *
+     * @remarks
+     * The validator can extend this interface to support additional prompt options.
+     */
+  readonly options: PromptOptions;
+
+  /**
+     * A count of the number of times the prompt has been executed.
+     *
+     * A number indicating how many times the prompt was invoked (starting at 1 for the first time it was invoked).
+     */
+  readonly attemptCount: number;
+}
+
+/**
+ * Base class for all prompts.
+ *
+ * @param T Type of value being returned by the prompts recognizer function.
+ */
+export abstract class Prompt<T> extends Dialog {
+  /**
+     * Creates a new Prompt instance.
+     *
+     * @param dialogId Unique ID of the prompt within its parent `DialogSet` or `ComponentDialog`.
+     * @param validator (Optional) custom validator used to provide additional validation and re-prompting logic for the prompt.
+     */
+  protected constructor (
+    dialogId: string,
+    private validator?: PromptValidator<T>
+  ) {
+    super(dialogId)
+  }
+
+  /**
+     * Called when a prompt dialog is pushed onto the dialog stack and is being activated.
+     *
+     * @param dialogContext The DialogContext for the current
+     * turn of the conversation.
+     * @param options Optional. PromptOptions,
+     * additional information to pass to the prompt being started.
+     * @returns A `Promise` representing the asynchronous operation.
+     * @remarks
+     * If the task is successful, the result indicates whether the prompt is still
+     * active after the turn has been processed by the prompt.
+     */
+  async beginDialog (dialogContext: DialogContext, options: PromptOptions): Promise<DialogTurnResult> {
+    // Ensure prompts have input hint set
+    const opt: Partial<PromptOptions> = { ...options }
+    if (opt.prompt && typeof opt.prompt === 'object' && typeof opt.prompt.inputHint !== 'string') {
+      opt.prompt.inputHint = InputHints.ExpectingInput
+    }
+    if (opt.retryPrompt && typeof opt.retryPrompt === 'object' && typeof opt.retryPrompt.inputHint !== 'string') {
+      opt.retryPrompt.inputHint = InputHints.ExpectingInput
+    }
+
+    // Initialize prompt state
+    const state: PromptState = dialogContext.activeDialog.state as PromptState
+    state.options = opt
+    state.state = {}
+
+    // Send initial prompt
+    await this.onPrompt(dialogContext.context, state.state, state.options, false)
+
+    return Dialog.EndOfTurn
+  }
+
+  /**
+     * Called when a prompt dialog is the active dialog and the user replied with a new activity.
+     *
+     * @param dialogContext The DialogContext for the current turn of conversation.
+     * @returns A `Promise` representing the asynchronous operation.
+     * @remarks
+     * If the task is successful, the result indicates whether the dialog is still
+     * active after the turn has been processed by the dialog.
+     * The prompt generally continues to receive the user's replies until it accepts the
+     * user's reply as valid input for the prompt.
+     */
+  async continueDialog (dialogContext: DialogContext): Promise<DialogTurnResult> {
+    // Don't do anything for non-message activities
+    if (dialogContext.context.activity.type !== ActivityTypes.Message) {
+      return Dialog.EndOfTurn
+    }
+
+    // Are we being continued after an interruption?
+    // - The stepCount will be 1 or more if we're running in the context of an AdaptiveDialog
+    //   and we're coming back from an interruption.
+    const stepCount = dialogContext.state.getValue('turn.stepCount')
+    if (typeof stepCount === 'number' && stepCount > 0) {
+      // re-prompt and then end
+      await this.repromptDialog(dialogContext.context, dialogContext.activeDialog)
+      return Dialog.EndOfTurn
+    }
+
+    // Perform base recognition
+    const state: PromptState = dialogContext.activeDialog.state as PromptState
+    const recognized: PromptRecognizerResult<T> = await this.onRecognize(dialogContext.context, state.state, state.options)
+
+    // Validate the return value
+    let isValid = false
+    if (this.validator) {
+      if (state.state['attemptCount'] === undefined) {
+        state.state['attemptCount'] = 0
+      }
+      isValid = await this.validator({
+        context: dialogContext.context,
+        recognized,
+        state: state.state,
+        options: state.options,
+        attemptCount: ++state.state['attemptCount'],
+      })
+    } else if (recognized.succeeded) {
+      isValid = true
+    }
+
+    // Return recognized value or re-prompt
+    if (isValid) {
+      return await dialogContext.endDialog(recognized.value)
+    } else {
+      if (!dialogContext.context.responded) {
+        await this.onPrompt(dialogContext.context, state.state, state.options, true)
+      }
+
+      return Dialog.EndOfTurn
+    }
+  }
+
+  /**
+     * Called before an event is bubbled to its parent.
+     *
+     * @param dialogContext The DialogContext for the current turn of conversation.
+     * @param event DialogEvent, the event being raised.
+     * @returns Whether the event is handled by the current dialog and further processing should stop.
+     * @remarks
+     * This is a good place to perform interception of an event as returning `true` will prevent
+     * any further bubbling of the event to the dialogs parents and will also prevent any child
+     * dialogs from performing their default processing.
+     */
+  protected async onPreBubbleEvent (dialogContext: DialogContext, event: DialogEvent): Promise<boolean> {
+    if (event.name === 'activityReceived' && dialogContext.context.activity.type === ActivityTypes.Message) {
+      // Perform base recognition
+      const state: PromptState = dialogContext.activeDialog.state as PromptState
+      const recognized: PromptRecognizerResult<T> = await this.onRecognize(
+        dialogContext.context,
+        state.state,
+        state.options
+      )
+      return recognized.succeeded
+    }
+
+    return false
+  }
+
+  /**
+     * Called when a prompt dialog resumes being the active dialog on the dialog stack, such as
+     * when the previous active dialog on the stack completes.
+     *
+     * @param dialogContext The DialogContext for the current turn of the conversation.
+     * @param _reason An enum indicating why the dialog resumed.
+     * @param _result Optional, value returned from the previous dialog on the stack.
+     * The type of the value returned is dependent on the previous dialog.
+     * @returns A Promise representing the asynchronous operation.
+     * @remarks
+     * If the task is successful, the result indicates whether the dialog is still
+     * active after the turn has been processed by the dialog.
+     */
+  async resumeDialog (dialogContext: DialogContext, _reason: DialogReason, _result?: any): Promise<DialogTurnResult> {
+    // Prompts are typically leaf nodes on the stack but the dev is free to push other dialogs
+    // on top of the stack which will result in the prompt receiving an unexpected call to
+    // resumeDialog() when the pushed on dialog ends.
+    // To avoid the prompt prematurely ending we need to implement this method and
+    // simply re-prompt the user.
+    await this.repromptDialog(dialogContext.context, dialogContext.activeDialog)
+
+    return Dialog.EndOfTurn
+  }
+
+  /**
+     * Called when a prompt dialog has been requested to re-prompt the user for input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param instance DialogInstance, the instance
+     * of the dialog on the stack.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  async repromptDialog (context: TurnContext, instance: DialogInstance): Promise<void> {
+    const state: PromptState = instance.state as PromptState
+    await this.onPrompt(context, state.state, state.options, false)
+  }
+
+  /**
+     * Called anytime the derived class should send the user a prompt.
+     *
+     * @param context Context for the current turn of conversation with the user.
+     * @param state Additional state being persisted for the prompt.
+     * @param options Options that the prompt was started with in the call to `DialogContext.prompt()`.
+     * @param isRetry If `true` the users response wasn't recognized and the re-prompt should be sent.
+     */
+  protected abstract onPrompt (
+    context: TurnContext,
+    state: object,
+    options: PromptOptions,
+    isRetry: boolean,
+  ): Promise<void>
+
+  /**
+     * Called to recognize an utterance received from the user.
+     *
+     * @remarks
+     * The Prompt class filters out non-message activities so its safe to assume that the users
+     * utterance can be retrieved from `context.activity.text`.
+     * @param context Context for the current turn of conversation with the user.
+     * @param state Additional state being persisted for the prompt.
+     * @param options Options that the prompt was started with in the call to `DialogContext.prompt()`.
+     */
+  protected abstract onRecognize (
+    context: TurnContext,
+    state: object,
+    options: PromptOptions,
+  ): Promise<PromptRecognizerResult<T>>
+
+  /**
+     * Helper function to compose an output activity containing a set of choices.
+     *
+     * @param prompt The prompt to append the users choices to.
+     * @param channelId ID of the channel the prompt is being sent to.
+     * @param choices List of choices to append.
+     * @param style Configured style for the list of choices.
+     * @param options (Optional) options to configure the underlying ChoiceFactory call.
+     * @returns The composed activity ready to send to the user.
+     */
+  protected appendChoices (
+    prompt: string | Activity,
+    channelId: string,
+    choices: (string | Choice)[],
+    style: ListStyle,
+    options?: ChoiceFactoryOptions
+  ): Activity {
+    // Get base prompt text (if any)
+    let text = ''
+    if (typeof prompt === 'string') {
+      text = prompt
+    } else if (prompt && prompt.text) {
+      text = prompt.text
+    }
+
+    // Create temporary msg
+    let msg: Activity
+    switch (style) {
+      case ListStyle.inline:
+        msg = ChoiceFactory.inline(choices, text, undefined, options)
+        break
+
+      case ListStyle.list:
+        msg = ChoiceFactory.list(choices, text, undefined, options)
+        break
+
+      case ListStyle.none:
+        msg = MessageFactory.text(text)
+        break
+
+      default:
+        msg = ChoiceFactory.forChannel(channelId, choices, text, undefined, options)
+        break
+    }
+
+    // Update prompt with text, actions and attachments
+    if (typeof prompt === 'object') {
+      // Clone the prompt Activity as to not modify the original prompt.
+      prompt = JSON.parse(JSON.stringify(prompt)) as Activity
+      prompt.text = msg.text
+      if (
+        msg.suggestedActions &&
+                Array.isArray(msg.suggestedActions.actions) &&
+                msg.suggestedActions.actions.length > 0
+      ) {
+        prompt.suggestedActions = msg.suggestedActions
+      }
+
+      if (msg.attachments) {
+        if (prompt.attachments) {
+          prompt.attachments = prompt.attachments.concat(msg.attachments)
+        } else {
+          prompt.attachments = msg.attachments
+        }
+      }
+
+      return prompt
+    } else {
+      msg.inputHint = InputHints.ExpectingInput
+
+      return msg
+    }
+  }
+}
+
+/**
+ * @private
+ */
+interface PromptState {
+  state: any;
+  options: PromptOptions;
+}

package/src/prompts/promptCultureModels.ts

@@ -0,0 +1,178 @@
+import { Culture } from '@microsoft/recognizers-text-suite'
+
+export interface PromptCultureModel {
+  /**
+     * Culture Model's Locale.
+     *
+     * @example
+     * "en-US"
+     */
+  locale: string;
+  /**
+     * Culture Model's InlineSeparator.
+     *
+     * @example
+     * ", "
+     */
+  separator: string;
+  /**
+     * Culture Model's InlineOr.
+     *
+     * @example
+     * " or "
+     */
+  inlineOr: string;
+  /**
+     * Culture Model's InlineOrMore.
+     *
+     * @example
+     * ", or "
+     */
+  inlineOrMore: string;
+  /**
+     * Equivalent of "Yes" in Culture Model's Language.
+     *
+     * @example
+     * "Yes"
+     */
+  yesInLanguage: string;
+  /**
+     * Equivalent of "No" in Culture Model's Language.
+     *
+     * @example
+     * "No"
+     */
+  noInLanguage: string;
+}
+
+/**
+ * Class container for currently-supported Culture Models in Confirm and Choice Prompt.
+ */
+export class PromptCultureModels {
+  static Chinese: PromptCultureModel = {
+    locale: Culture.Chinese,
+    separator: ', ',
+    inlineOr: ' 要么 ',
+    inlineOrMore: '， 要么 ',
+    yesInLanguage: '是的',
+    noInLanguage: '不',
+  }
+
+  static Dutch: PromptCultureModel = {
+    locale: Culture.Dutch,
+    separator: ', ',
+    inlineOr: ' of ',
+    inlineOrMore: ', of ',
+    yesInLanguage: 'Ja',
+    noInLanguage: 'Nee',
+  }
+
+  static English: PromptCultureModel = {
+    locale: Culture.English,
+    separator: ', ',
+    inlineOr: ' or ',
+    inlineOrMore: ', or ',
+    yesInLanguage: 'Yes',
+    noInLanguage: 'No',
+  }
+
+  static French: PromptCultureModel = {
+    locale: Culture.French,
+    separator: ', ',
+    inlineOr: ' ou ',
+    inlineOrMore: ', ou ',
+    yesInLanguage: 'Oui',
+    noInLanguage: 'Non',
+  }
+
+  static German: PromptCultureModel = {
+    locale: Culture.German,
+    separator: ', ',
+    inlineOr: ' oder ',
+    inlineOrMore: ', oder ',
+    yesInLanguage: 'Ja',
+    noInLanguage: 'Nein',
+  }
+
+  static Italian: PromptCultureModel = {
+    locale: Culture.Italian,
+    separator: ', ',
+    inlineOr: ' o ',
+    inlineOrMore: ' o ',
+    yesInLanguage: 'Si',
+    noInLanguage: 'No',
+  }
+
+  static Japanese: PromptCultureModel = {
+    locale: Culture.Japanese,
+    separator: '、 ',
+    inlineOr: ' または ',
+    inlineOrMore: '、 または ',
+    yesInLanguage: 'はい',
+    noInLanguage: 'いいえ',
+  }
+
+  static Portuguese: PromptCultureModel = {
+    locale: Culture.Portuguese,
+    separator: ', ',
+    inlineOr: ' ou ',
+    inlineOrMore: ', ou ',
+    yesInLanguage: 'Sim',
+    noInLanguage: 'Não',
+  }
+
+  static Spanish: PromptCultureModel = {
+    locale: Culture.Spanish,
+    separator: ', ',
+    inlineOr: ' o ',
+    inlineOrMore: ', o ',
+    yesInLanguage: 'Sí',
+    noInLanguage: 'No',
+  }
+
+  /**
+     * @private
+     */
+  private static getSupportedCultureCodes (): string[] {
+    return this.getSupportedCultures().map((c): string => c.locale)
+  }
+
+  /**
+     * Use Recognizers-Text to normalize various potential Locale strings to a standard.
+     *
+     * @remarks This is mostly a copy/paste from https://github.com/microsoft/Recognizers-Text/blob/master/JavaScript/packages/recognizers-text/src/culture.ts#L39
+     *          This doesn't directly use Recognizers-Text's MapToNearestLanguage because if they add language support before we do, it will break our prompts.
+     * @param cultureCode Represents locale. Examples: "en-US, en-us, EN".
+     * @returns Normalized locale.
+     */
+  static mapToNearestLanguage (cultureCode: string): string {
+    if (cultureCode) {
+      cultureCode = cultureCode.toLowerCase()
+      const supportedCultureCodes = this.getSupportedCultureCodes()
+
+      if (supportedCultureCodes.indexOf(cultureCode) < 0) {
+        const culturePrefix = cultureCode.split('-')[0].trim()
+
+        supportedCultureCodes.forEach(function (supportedCultureCode): void {
+          if (supportedCultureCode.startsWith(culturePrefix)) {
+            cultureCode = supportedCultureCode
+          }
+        })
+      }
+    }
+
+    return cultureCode
+  }
+
+  static getSupportedCultures = (): PromptCultureModel[] => [
+    PromptCultureModels.Chinese,
+    PromptCultureModels.Dutch,
+    PromptCultureModels.English,
+    PromptCultureModels.French,
+    PromptCultureModels.German,
+    PromptCultureModels.Italian,
+    PromptCultureModels.Japanese,
+    PromptCultureModels.Portuguese,
+    PromptCultureModels.Spanish,
+  ]
+}