@microsoft/agents-hosting-dialogs 0.1.49

package/src/prompts/choicePrompt.ts

@@ -0,0 +1,176 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { Activity, TurnContext } from '@microsoft/agents-hosting'
+import { ChoiceFactory, ChoiceFactoryOptions, FindChoicesOptions, FoundChoice, recognizeChoices } from '../choices'
+import { ListStyle, Prompt, PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt'
+import { PromptCultureModels } from './promptCultureModels'
+
+// Need ChoiceDefaultsProperty so we can set choiceDefaults dynamically with lambda
+interface ChoiceDefaultsChoicePrompt {
+  [locale: string]: ChoiceFactoryOptions;
+}
+
+/**
+ * Prompts a user to select from a list of choices.
+ *
+ * @remarks
+ * By default the prompt will return to the calling dialog a `FoundChoice` object containing the
+ * choice that was selected.
+ */
+export class ChoicePrompt extends Prompt<FoundChoice> {
+  /**
+     * A dictionary of Default Choices based on [[PromptCultureModels.getSupportedCultures()]].
+     * Can be replaced by user using the constructor that contains choiceDefaults.
+     */
+  private choiceDefaults: ChoiceDefaultsChoicePrompt
+
+  /**
+     * The prompts default locale that should be recognized.
+     */
+  defaultLocale: string | undefined
+
+  /**
+     * Style of the "yes" and "no" choices rendered to the user when prompting.
+     *
+     * @remarks
+     * Defaults to `ListStyle.auto`.
+     */
+  style: ListStyle
+
+  /**
+     * Additional options passed to the `ChoiceFactory` and used to tweak the style of choices
+     * rendered to the user.
+     */
+  choiceOptions: ChoiceFactoryOptions | undefined
+
+  /**
+     * Additional options passed to the underlying `recognizeChoices()` function.
+     */
+  recognizerOptions: FindChoicesOptions | undefined
+
+  /**
+     * Creates a new `ChoicePrompt` instance.
+     *
+     * @param dialogId Unique ID of the dialog within its parent `DialogSet`.
+     * @param validator (Optional) validator that will be called each time the user responds to the prompt. If the validator replies with a message no additional retry prompt will be sent.
+     * @param defaultLocale (Optional) locale to use if `dc.context.activity.locale` not specified. Defaults to a value of `en-us`.
+     * @param choiceDefaults (Optional) Overrides the dictionary of Bot Framework SDK-supported _choiceDefaults (for prompt localization).
+     *  Must be passed in to each ConfirmPrompt that needs the custom choice defaults.
+     */
+  constructor (
+    dialogId: string,
+    validator?: PromptValidator<FoundChoice>,
+    defaultLocale?: string,
+    choiceDefaults?: ChoiceDefaultsChoicePrompt
+  ) {
+    super(dialogId, validator)
+    this.style = ListStyle.auto
+    this.defaultLocale = defaultLocale
+
+    if (choiceDefaults === undefined) {
+      const supported: ChoiceDefaultsChoicePrompt = {}
+      PromptCultureModels.getSupportedCultures().forEach((culture): void => {
+        supported[culture.locale] = {
+          inlineSeparator: culture.separator,
+          inlineOr: culture.inlineOr,
+          inlineOrMore: culture.inlineOrMore,
+          includeNumbers: true,
+        }
+      })
+      this.choiceDefaults = supported
+    } else {
+      this.choiceDefaults = choiceDefaults
+    }
+  }
+
+  /**
+     * Prompts the user for input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @param isRetry `true` if this is the first time this prompt dialog instance
+     * on the stack is prompting the user for input; otherwise, false.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onPrompt (
+    context: TurnContext,
+    state: any,
+    options: PromptOptions,
+    isRetry: boolean
+  ): Promise<void> {
+    // Determine locale
+    const locale = this.determineCulture(context.activity)
+
+    // Format prompt to send
+    let prompt: Activity
+    const choices =
+            (this.style === ListStyle.suggestedAction ? ChoiceFactory.toChoices(options.choices) : options.choices) ||
+            []
+    const channelId = context.activity.channelId
+    const choiceOptions = this.choiceOptions || this.choiceDefaults[locale]
+    const choiceStyle: ListStyle = options.style === 0 ? 0 : options.style || this.style
+    if (isRetry && options.retryPrompt) {
+      prompt = this.appendChoices(options.retryPrompt, channelId, choices, choiceStyle, choiceOptions)
+    } else {
+      prompt = this.appendChoices(options.prompt, channelId, choices, choiceStyle, choiceOptions)
+    }
+
+    // Send prompt
+    await context.sendActivity(prompt)
+  }
+
+  /**
+     * Attempts to recognize the user's input.
+     *
+     * @param context TurnContext context for the current
+     * turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onRecognize (
+    context: TurnContext,
+    state: any,
+    options: PromptOptions
+  ): Promise<PromptRecognizerResult<FoundChoice>> {
+    const result: PromptRecognizerResult<FoundChoice> = { succeeded: false }
+    const activity = context.activity
+    const utterance = activity.text
+    if (!utterance) {
+      return result
+    }
+    const choices =
+            (this.style === ListStyle.suggestedAction ? ChoiceFactory.toChoices(options.choices) : options.choices) ||
+            []
+    const opt = this.recognizerOptions || {}
+    opt.locale = this.determineCulture(activity, opt)
+    const results = recognizeChoices(utterance, choices, opt)
+    if (Array.isArray(results) && results.length > 0) {
+      result.succeeded = true
+      result.value = results[0].resolution
+    }
+
+    return result
+  }
+
+  /**
+     * @private
+     */
+  private determineCulture (activity: Activity, opt?: FindChoicesOptions): string {
+    const optLocale = opt && opt.locale ? opt.locale : null
+    let culture = PromptCultureModels.mapToNearestLanguage(
+      activity.locale || optLocale || this.defaultLocale || PromptCultureModels.English.locale
+    )
+    if (!(culture && this.choiceDefaults[culture])) {
+      culture = PromptCultureModels.English.locale
+    }
+
+    return culture
+  }
+}

package/src/prompts/confirmPrompt.ts

@@ -0,0 +1,182 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import * as Recognizers from '@microsoft/recognizers-text-choice'
+import { Activity, TurnContext } from '@microsoft/agents-hosting'
+import { Choice, ChoiceFactoryOptions, recognizeChoices } from '../choices'
+import { ListStyle, Prompt, PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt'
+import { PromptCultureModels } from './promptCultureModels'
+
+// Need ChoiceDefaultsProperty so we can set choiceDefaults dynamically with lambda
+interface ChoiceDefaultsConfirmPrompt {
+  [locale: string]: { choices: (string | Choice)[]; options: ChoiceFactoryOptions };
+}
+
+/**
+ * Prompts a user to confirm something with a "yes" or "no" response.
+ *
+ * @remarks
+ * By default the prompt will return to the calling dialog a `boolean` representing the users
+ * selection.
+ */
+export class ConfirmPrompt extends Prompt<boolean> {
+  /**
+     * A dictionary of Default Choices based on [[PromptCultureModels.getSupportedCultures()]].
+     * Can be replaced by user using the constructor that contains choiceDefaults.
+     * This is initially set in the constructor.
+     */
+  private choiceDefaults: ChoiceDefaultsConfirmPrompt
+  /**
+     * The prompts default locale that should be recognized.
+     */
+  defaultLocale: string | undefined
+
+  /**
+     * Style of the "yes" and "no" choices rendered to the user when prompting.
+     *
+     * @remarks
+     * Defaults to `ListStyle.auto`.
+     */
+  style: ListStyle
+
+  /**
+     * Additional options passed to the `ChoiceFactory` and used to tweak the style of choices
+     * rendered to the user.
+     */
+  choiceOptions: ChoiceFactoryOptions | undefined
+
+  /**
+     * Custom list of choices to send for the prompt.
+     */
+  confirmChoices: (string | Choice)[] | undefined
+
+  /**
+     * Creates a new ConfirmPrompt instance.
+     *
+     * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
+     * @param validator (Optional) validator that will be called each time the user responds to the prompt.
+     * @param defaultLocale (Optional) locale to use if `TurnContext.activity.locale` is not specified. Defaults to a value of `en-us`.
+     * @param choiceDefaults (Optional) Overrides the dictionary of Default Choices on [[PromptCultureModels.getSupportedCultures()]].
+     */
+  constructor (
+    dialogId: string,
+    validator?: PromptValidator<boolean>,
+    defaultLocale?: string,
+    choiceDefaults?: ChoiceDefaultsConfirmPrompt
+  ) {
+    super(dialogId, validator)
+    this.style = ListStyle.auto
+    this.defaultLocale = defaultLocale
+
+    if (choiceDefaults === undefined) {
+      const supported: ChoiceDefaultsConfirmPrompt = {}
+      PromptCultureModels.getSupportedCultures().forEach((culture): void => {
+        supported[culture.locale] = {
+          choices: [culture.yesInLanguage, culture.noInLanguage],
+          options: {
+            inlineSeparator: culture.separator,
+            inlineOr: culture.inlineOr,
+            inlineOrMore: culture.inlineOrMore,
+            includeNumbers: true,
+          },
+        }
+      })
+      this.choiceDefaults = supported
+    } else {
+      this.choiceDefaults = choiceDefaults
+    }
+  }
+
+  /**
+     * Prompts the user for input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @param isRetry `true` if this is the first time this prompt dialog instance
+     * on the stack is prompting the user for input; otherwise, false.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onPrompt (
+    context: TurnContext,
+    state: any,
+    options: PromptOptions,
+    isRetry: boolean
+  ): Promise<void> {
+    // Format prompt to send
+    let prompt: Activity
+    const channelId = context.activity.channelId
+    const culture = this.determineCulture(context.activity)
+    const choiceOptions = this.choiceOptions || this.choiceDefaults[culture].options
+    const choices = this.confirmChoices || this.choiceDefaults[culture].choices
+    if (isRetry && options.retryPrompt) {
+      prompt = this.appendChoices(options.retryPrompt, channelId, choices, this.style, choiceOptions)
+    } else {
+      prompt = this.appendChoices(options.prompt, channelId, choices, this.style, choiceOptions)
+    }
+
+    // Send prompt
+    await context.sendActivity(prompt)
+  }
+
+  /**
+     * Attempts to recognize the user's input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param _state Contains state for the current instance of the prompt on the dialog stack.
+     * @param _options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onRecognize (
+    context: TurnContext,
+    _state,
+    _options: PromptOptions
+  ): Promise<PromptRecognizerResult<boolean>> {
+    const result: PromptRecognizerResult<boolean> = { succeeded: false }
+    const activity = context.activity
+    const utterance = activity.text
+    if (!utterance) {
+      return result
+    }
+    const culture = this.determineCulture(context.activity)
+    const results = Recognizers.recognizeBoolean(utterance, _options.recognizeLanguage ?? culture)
+    if (results.length > 0 && results[0].resolution) {
+      result.succeeded = true
+      result.value = results[0].resolution.value
+    } else {
+      // If the prompt text was sent to the user with numbers, the prompt should recognize number choices.
+      const choiceOptions = this.choiceOptions || this.choiceDefaults[culture].options
+
+      if (typeof choiceOptions.includeNumbers !== 'boolean' || choiceOptions.includeNumbers) {
+        const confirmChoices = this.confirmChoices || this.choiceDefaults[culture].choices
+        const choices = [confirmChoices[0], confirmChoices[1]]
+        const secondOrMoreAttemptResults = recognizeChoices(utterance, choices)
+        if (secondOrMoreAttemptResults.length > 0) {
+          result.succeeded = true
+          result.value = secondOrMoreAttemptResults[0].resolution.index === 0
+        }
+      }
+    }
+
+    return result
+  }
+
+  /**
+     * @private
+     */
+  private determineCulture (activity: Activity): string {
+    let culture = PromptCultureModels.mapToNearestLanguage(
+      activity.locale || this.defaultLocale || PromptCultureModels.English.locale
+    )
+    if (!(culture && this.choiceDefaults[culture])) {
+      culture = PromptCultureModels.English.locale
+    }
+
+    return culture
+  }
+}

package/src/prompts/datetimePrompt.ts

@@ -0,0 +1,110 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import * as Recognizers from '@microsoft/recognizers-text-date-time'
+import { Activity, InputHints, TurnContext } from '@microsoft/agents-hosting'
+import { Prompt, PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt'
+
+/**
+ * Result returned by the `DateTimePrompt`.
+ */
+export interface DateTimeResolution {
+  /**
+     * TIMEX expression representing ambiguity of the recognized time.
+     */
+  timex: string;
+
+  /**
+     * Type of time recognized. Possible values are 'date', 'time', 'datetime', 'daterange',
+     * 'timerange', 'datetimerange', 'duration', or 'set'.
+     */
+  type: string;
+
+  /**
+     * Value of the specified [type](#type) that's a reasonable approximation given the ambiguity
+     * of the [timex](#timex).
+     */
+  value: string;
+}
+
+/**
+ * Prompts a user to enter a datetime expression.
+ *
+ * @remarks
+ * By default the prompt will return to the calling dialog a `DateTimeResolution[]`.
+ */
+export class DateTimePrompt extends Prompt<DateTimeResolution[]> {
+  /**
+     * The prompts default locale that should be recognized.
+     */
+  defaultLocale: string | undefined
+
+  /**
+     * Creates a new DateTimePrompt instance.
+     *
+     * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
+     * @param validator (Optional) validator that will be called each time the user responds to the prompt.
+     * @param defaultLocale (Optional) locale to use if `TurnContext.activity.locale` is not specified. Defaults to a value of `en-us`.
+     */
+  constructor (dialogId: string, validator?: PromptValidator<DateTimeResolution[]>, defaultLocale?: string) {
+    super(dialogId, validator)
+    this.defaultLocale = defaultLocale
+  }
+
+  /**
+     * Prompts the user for input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @param isRetry `true` if this is the first time this prompt dialog instance
+     * on the stack is prompting the user for input; otherwise, false.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onPrompt (
+    context: TurnContext,
+    state: any,
+    options: PromptOptions,
+    isRetry: boolean
+  ): Promise<void> {
+    if (isRetry && options.retryPrompt) {
+      await context.sendActivity(options.retryPrompt, undefined, InputHints.ExpectingInput)
+    } else if (options.prompt) {
+      await context.sendActivity(options.prompt, undefined, InputHints.ExpectingInput)
+    }
+  }
+
+  /**
+     * Attempts to recognize the user's input.
+     *
+     * @param context TurnContext, context for the current
+     * turn of conversation with the user.
+     * @param _state Contains state for the current instance of the prompt on the dialog stack.
+     * @param _options A PromptOptions object constructed
+     * from the options initially provided in the call to Prompt.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onRecognize (
+    context: TurnContext,
+    _state: any,
+    _options: PromptOptions
+  ): Promise<PromptRecognizerResult<DateTimeResolution[]>> {
+    const result: PromptRecognizerResult<DateTimeResolution[]> = { succeeded: false }
+    const activity: Activity = context.activity
+    const utterance: string = activity.text
+    if (!utterance) {
+      return result
+    }
+    const locale: string = activity.locale || this.defaultLocale || 'en-us'
+    const results: any[] = Recognizers.recognizeDateTime(utterance, locale)
+    if (results.length > 0 && results[0].resolution) {
+      result.succeeded = true
+      result.value = results[0].resolution.values
+    }
+
+    return result
+  }
+}

package/src/prompts/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+export * from './activityPrompt'
+export * from './attachmentPrompt'
+export * from './choicePrompt'
+export * from './confirmPrompt'
+export * from './datetimePrompt'
+export * from './numberPrompt'
+export * from './prompt'
+export * from './textPrompt'
+export * from './promptCultureModels'

package/src/prompts/numberPrompt.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import Globalize from 'globalize'
+import { recognizeNumber } from '@microsoft/recognizers-text-number'
+import * as locales from '../i18n'
+import { InputHints, TurnContext } from '@microsoft/agents-hosting'
+import { Prompt, PromptOptions, PromptRecognizerResult, PromptValidator } from './prompt'
+
+// Load all registered locales into Globalize library
+Object.values(locales).forEach((locale) => Globalize.load(locale))
+
+/**
+ * Prompts a user to enter a number.
+ *
+ * @remarks
+ * By default the prompt will return to the calling dialog a `number` representing the users input.
+ */
+export class NumberPrompt extends Prompt<number> {
+  /**
+     * The prompts default locale that should be recognized.
+     */
+  defaultLocale?: string
+
+  /**
+     * Creates a new NumberPrompt instance.
+     *
+     * @param dialogId Unique ID of the dialog within its parent `DialogSet` or `ComponentDialog`.
+     * @param validator (Optional) validator that will be called each time the user responds to the prompt.
+     * @param defaultLocale (Optional) locale to use if `TurnContext.activity.locale` is not specified. Defaults to a value of `en-us`.
+     */
+  constructor (dialogId: string, validator?: PromptValidator<number>, defaultLocale?: string) {
+    super(dialogId, validator)
+    this.defaultLocale = defaultLocale
+  }
+
+  /**
+     * Prompts the user for input.
+     *
+     * @param context [TurnContext] context for the current
+     * turn of conversation with the user.
+     * @param state Contains state for the current instance of the prompt on the dialog stack.
+     * @param options A [PromptOptions] object constructed
+     * from the options initially provided in the call to Prompt.
+     * @param isRetry `true` if this is the first time this prompt dialog instance
+     * on the stack is prompting the user for input; otherwise, false.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onPrompt (
+    context: TurnContext,
+    state: unknown,
+    options: PromptOptions,
+    isRetry: boolean
+  ): Promise<void> {
+    if (isRetry && options.retryPrompt) {
+      await context.sendActivity(options.retryPrompt, undefined, InputHints.ExpectingInput)
+    } else if (options.prompt) {
+      await context.sendActivity(options.prompt, undefined, InputHints.ExpectingInput)
+    }
+  }
+
+  /**
+     * Attempts to recognize the user's input.
+     *
+     * @param context [TurnContext], context for the current
+     * turn of conversation with the user.
+     * @param _state Contains state for the current instance of the prompt on the dialog stack.
+     * @param _options A [PromptOptions] object constructed
+     * from the options initially provided in the call to Prompt.
+     * @returns A `Promise` representing the asynchronous operation.
+     */
+  protected async onRecognize (
+    context: TurnContext,
+    _state: unknown,
+    _options: PromptOptions
+  ): Promise<PromptRecognizerResult<number>> {
+    const result: PromptRecognizerResult<number> = { succeeded: false }
+    const activity = context.activity
+
+    const utterance = activity.text
+    if (!utterance) {
+      return result
+    }
+
+    const defaultLocale = this.defaultLocale || 'en-us'
+    const locale = activity.locale || defaultLocale
+
+    const [{ resolution = null } = {}] = recognizeNumber(utterance, locale) || []
+    if (resolution) {
+      result.succeeded = true
+
+      // Note: if we encounter an exception loading a globalize number parser, fall back to the
+      // parser for the default locale
+      const parser = Globalize(this.getCultureFormattedForGlobalize(locale))
+      let numberParser: (value: string) => number
+      try {
+        numberParser = parser.numberParser()
+      } catch {
+        numberParser = Globalize(this.getCultureFormattedForGlobalize(defaultLocale)).numberParser()
+      }
+
+      result.value = numberParser(resolution.value)
+    }
+
+    return result
+  }
+
+  /**
+     * @private
+     * The portions of the Globalize parsing library we use only need the first letters for internationalization culture
+     */
+  private getCultureFormattedForGlobalize (culture: string): string {
+    return culture.slice(0, 2).toLowerCase()
+  }
+}