@microsoft/agents-hosting-dialogs 0.2.14 → 0.4.1

package/src/prompts/prompt.ts

@@ -13,7 +13,7 @@ import { DialogEvent } from '../dialogEvent'
 import { Activity, ActivityTypes, InputHints } from '@microsoft/agents-activity'
 
 /**
- * Controls the way that choices for a `ChoicePrompt` or yes/no options for a `ConfirmPrompt` are
+ * Controls the way that choices for a {@link ChoicePrompt} or yes/no options for a {@link ConfirmPrompt} are
  * presented to a user.
  */
 export enum ListStyle {
@@ -91,13 +91,13 @@ export interface PromptOptions {
  */
 export interface PromptRecognizerResult<T> {
   /**
-     * If `true` the users utterance was successfully recognized and [value](#value) contains the
+     * If `true` the user's utterance was successfully recognized and `value` contains the
      * recognized result.
      */
   succeeded: boolean;
 
   /**
-     * Value that was recognized if [succeeded](#succeeded) is `true`.
+     * Value that was recognized if `succeeded` is `true`.
      */
   value?: T;
 }
@@ -116,7 +116,7 @@ export interface PromptRecognizerResult<T> {
  * > [!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.
+ * > case the prompts default re-prompt logic will not be run.
  * @param T Type of recognizer result being validated.
  * @param prompt Contextual information containing the recognizer result and original options passed to the prompt.
  */
@@ -140,8 +140,8 @@ export interface PromptValidatorContext<T> {
      * 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`.
+     * The {@link @microsoft/agents-hosting-dialogs.PromptRecognizerResult.succeeded | recognized.succeeded} field can be checked to determine of the recognizer found
+     * anything and then the value can be retrieved from {@link @microsoft/agents-hosting-dialogs.PromptRecognizerResult.value | recognized.value}.
      */
   readonly recognized: PromptRecognizerResult<T>;
 
@@ -178,7 +178,7 @@ 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 dialogId Unique ID of the prompt within its parent {@link DialogSet} or {@link ComponentDialog}.
      * @param validator (Optional) custom validator used to provide additional validation and re-prompting logic for the prompt.
      */
   protected constructor (

package/src/prompts/promptCultureModels.ts

@@ -49,6 +49,9 @@ export interface PromptCultureModel {
  * Class container for currently-supported Culture Models in Confirm and Choice Prompt.
  */
 export class PromptCultureModels {
+  /**
+   * Represents the Chinese culture model with locale and language-specific settings.
+   */
   static Chinese: PromptCultureModel = {
     locale: Culture.Chinese,
     separator: ', ',
@@ -58,6 +61,9 @@ export class PromptCultureModels {
     noInLanguage: '不',
   }
 
+  /**
+   * Represents the Dutch culture model with locale and language-specific settings.
+   */
   static Dutch: PromptCultureModel = {
     locale: Culture.Dutch,
     separator: ', ',
@@ -67,6 +73,9 @@ export class PromptCultureModels {
     noInLanguage: 'Nee',
   }
 
+  /**
+   * Represents the English culture model with locale and language-specific settings.
+   */
   static English: PromptCultureModel = {
     locale: Culture.English,
     separator: ', ',
@@ -76,6 +85,9 @@ export class PromptCultureModels {
     noInLanguage: 'No',
   }
 
+  /**
+   * Represents the French culture model with locale and language-specific settings.
+   */
   static French: PromptCultureModel = {
     locale: Culture.French,
     separator: ', ',
@@ -85,6 +97,9 @@ export class PromptCultureModels {
     noInLanguage: 'Non',
   }
 
+  /**
+   * Represents the German culture model with locale and language-specific settings.
+   */
   static German: PromptCultureModel = {
     locale: Culture.German,
     separator: ', ',
@@ -94,6 +109,9 @@ export class PromptCultureModels {
     noInLanguage: 'Nein',
   }
 
+  /**
+   * Represents the Italian culture model with locale and language-specific settings.
+   */
   static Italian: PromptCultureModel = {
     locale: Culture.Italian,
     separator: ', ',
@@ -103,6 +121,9 @@ export class PromptCultureModels {
     noInLanguage: 'No',
   }
 
+  /**
+   * Represents the Japanese culture model with locale and language-specific settings.
+   */
   static Japanese: PromptCultureModel = {
     locale: Culture.Japanese,
     separator: '、 ',
@@ -112,6 +133,9 @@ export class PromptCultureModels {
     noInLanguage: 'いいえ',
   }
 
+  /**
+   * Represents the Portuguese culture model with locale and language-specific settings.
+   */
   static Portuguese: PromptCultureModel = {
     locale: Culture.Portuguese,
     separator: ', ',
@@ -121,6 +145,9 @@ export class PromptCultureModels {
     noInLanguage: 'Não',
   }
 
+  /**
+   * Represents the Spanish culture model with locale and language-specific settings.
+   */
   static Spanish: PromptCultureModel = {
     locale: Culture.Spanish,
     separator: ', ',
@@ -131,6 +158,9 @@ export class PromptCultureModels {
   }
 
   /**
+     * Retrieves a list of supported culture codes.
+     *
+     * @returns An array of supported locale strings.
      * @private
      */
   private static getSupportedCultureCodes (): string[] {
@@ -138,12 +168,12 @@ export class PromptCultureModels {
   }
 
   /**
-     * Use Recognizers-Text to normalize various potential Locale strings to a standard.
+     * Normalizes a given locale string to the nearest supported language.
      *
+     * @param cultureCode The locale string to normalize (e.g., "en-US").
+     * @returns The normalized locale string.
      * @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) {
@@ -164,6 +194,11 @@ export class PromptCultureModels {
     return cultureCode
   }
 
+  /**
+     * Retrieves a list of supported culture models.
+     *
+     * @returns An array of `PromptCultureModel` objects representing supported cultures.
+     */
   static getSupportedCultures = (): PromptCultureModel[] => [
     PromptCultureModels.Chinese,
     PromptCultureModels.Dutch,

package/src/recognizer.ts

@@ -13,9 +13,16 @@ export interface RecognizerConfiguration {
 }
 
 /**
- * Recognizer base class.
+ * Base class for implementing custom recognizers to identify intents and entities from user input.
+ *
+ * Recognizers process user input, such as text or speech, and return structured data representing
+ * the recognized intents, entities, and other relevant information. This class provides a foundation
+ * for creating custom recognizers by defining common methods and properties.
  */
 export class Recognizer extends Configurable implements RecognizerConfiguration {
+  /**
+   * Optional. The unique identifier for the recognizer.
+   */
   id?: string
   /**
      * To recognize intents and entities in a users utterance.

package/src/recognizerResult.ts

@@ -8,11 +8,30 @@ import { IntentScore } from './intentScore'
  * Value returned from a recognizer.
  */
 export interface RecognizerResult {
-  text: string;
-  alteredText?: string;
-  intents: Record<string, IntentScore>;
-  entities?: any;
-  [propName: string]: any;
+  /**
+   * The original text input provided by the user.
+   */
+  text: string
+
+  /**
+   * Optional. The modified version of the text input, if applicable.
+   */
+  alteredText?: string
+
+  /**
+   * A mapping of intent names to their corresponding confidence scores.
+   */
+  intents: Record<string, IntentScore>
+
+  /**
+   * Optional. Entities recognized in the input, if any.
+   */
+  entities?: any
+
+  /**
+   * Additional properties that may be included in the recognizer result.
+   */
+  [propName: string]: any
 }
 
 export const getTopScoringIntent = (result: RecognizerResult): { intent: string; score: number } => {

package/src/serviceCollection.ts

@@ -62,9 +62,9 @@ export class ServiceCollection {
   /**
      * Register an instance by key. This will overwrite existing instances.
      *
-     * @param key key of the instance being provided
-     * @param instance instance to provide
-     * @returns this for chaining
+     * @param key Key of the instance being provided.
+     * @param instance Instance to provide.
+     * @returns `this` for chaining.
      */
   addInstance<InstanceType>(key: string, instance: InstanceType): this {
     if (this.graph.hasNode(key)) {
@@ -78,19 +78,19 @@ export class ServiceCollection {
   /**
      * Register a factory for a key.
      *
-     * @param key key that factory will provide
-     * @param factory function that creates an instance to provide
-     * @returns this for chaining
+     * @param key Key that factory will provide.
+     * @param factory Function that creates an instance to provide.
+     * @returns `this` for chaining.
      */
   addFactory<InstanceType>(key: string, factory: Factory<InstanceType, false>): this
 
   /**
      * Register a factory for a key with a set of dependencies.
      *
-     * @param key key that factory will provide
-     * @param dependencies set of things this instance depends on. Will be provided to factory function via `services`.
-     * @param factory function that creates an instance to provide
-     * @returns this for chaining
+     * @param key Key that factory will provide.
+     * @param dependencies Set of things this instance depends on. Will be provided to factory function via `services`.
+     * @param factory Function that creates an instance to provide.
+     * @returns `this` for chaining.
      */
   addFactory<InstanceType, Dependencies>(
     key: string,
@@ -144,10 +144,10 @@ export class ServiceCollection {
      * Register a factory (that expects an initial value that is not undefined) for a key
      * with a set of dependencies.
      *
-     * @param key key that factory will provide
-     * @param dependencies set of things this instance depends on. Will be provided to factory function via `services`.
-     * @param factory function that creates an instance to provide
-     * @returns this for chaining
+     * @param key Key that factory will provide.
+     * @param dependencies Set of things this instance depends on. Will be provided to factory function via `services`.
+     * @param factory Function that creates an instance to provide.
+     * @returns `this` for chaining.
      */
   composeFactory<InstanceType, Dependencies>(
     key: string,
@@ -241,9 +241,9 @@ export class ServiceCollection {
   /**
      * Build a single service.
      *
-     * @param key service to build
-     * @param deep reconstruct all dependencies
-     * @returns the service instance, or undefined
+     * @param key Service to build.
+     * @param deep Whether to reconstruct all dependencies.
+     * @returns The service instance, or undefined.
      */
   makeInstance<InstanceType = unknown>(key: string, deep = false): InstanceType | undefined {
     // If this is not a deep reconstruction, reuse any services that `key` depends on
@@ -264,9 +264,9 @@ export class ServiceCollection {
   /**
      * Build a single service and assert that it is not undefined.
      *
-     * @param key service to build
-     * @param deep reconstruct all dependencies
-     * @returns the service instance
+     * @param key Service to build.
+     * @param deep Wheter to reconstruct all dependencies.
+     * @returns The service instance
      */
   mustMakeInstance<InstanceType = unknown>(key: string, deep = false): InstanceType {
     const instance = this.makeInstance<InstanceType>(key, deep)
@@ -287,8 +287,8 @@ export class ServiceCollection {
   /**
      * Build the full set of services, asserting that the specified keys are not undefined.
      *
-     * @param keys instances that must be not undefined
-     * @returns all resolve services
+     * @param keys Instances that must be not undefined
+     * @returns All resolve services
      */
   mustMakeInstances<InstancesType extends Record<string, unknown> = Record<string, unknown>>(
     ...keys: string[]

package/src/waterfallDialog.ts

@@ -29,7 +29,7 @@ export class WaterfallDialog<O extends object = {}> extends Dialog<O> {
      * Creates a new waterfall dialog containing the given array of steps.
      *
      * @remarks
-     * See the addstep function for details on creating a valid step function.
+     * See the {@link WaterfallDialog.addStep | addStep function} for details on creating a valid step function.
      * @param dialogId Unique ID of the dialog within the component or set its being added to.
      * @param steps (Optional) array of asynchronous waterfall step functions.
      */
@@ -67,7 +67,7 @@ export class WaterfallDialog<O extends object = {}> extends Dialog<O> {
   /**
      * Called when the WaterfallDialog is started and pushed onto the dialog stack.
      *
-     * @param dialogContext The DialogContext for the current turn of conversation.
+     * @param dialogContext The {@link DialogContext} for the current turn of conversation.
      * @param options Optional, initial information to pass to the Dialog.
      * @returns A Promise representing the asynchronous operation.
      * @remarks
@@ -89,7 +89,7 @@ export class WaterfallDialog<O extends object = {}> extends Dialog<O> {
      * Called when the WaterfallDialog is _continued_, where it is the active dialog and the
      * user replies with a new Activity.
      *
-     * @param dialogContext The DialogContext for the current turn of conversation.
+     * @param dialogContext The {@link 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
@@ -109,7 +109,7 @@ export class WaterfallDialog<O extends object = {}> extends Dialog<O> {
   /**
      * Called when a child WaterfallDialog completed its turn, returning control to this dialog.
      *
-     * @param dc The DialogContext for the current turn of the conversation.
+     * @param dc The {@link DialogContext} for the current turn of the conversation.
      * @param reason DialogReason why the dialog resumed.
      * @param result Optional, value returned from the dialog that was called. The type
      * of the value returned is dependent on the child dialog.
@@ -138,7 +138,7 @@ export class WaterfallDialog<O extends object = {}> extends Dialog<O> {
   /**
      * Executes a step of the WaterfallDialog.
      *
-     * @param dc The DialogContext for the current turn of conversation.
+     * @param dc The {@link DialogContext} for the current turn of conversation.
      * @param index The index of the current waterfall step to execute.
      * @param reason The DialogReason the waterfall step is being executed.
      * @param result Optional, result returned by a dialog called in the previous waterfall step.

package/src/waterfallStepContext.ts

@@ -10,12 +10,38 @@ import { DialogTurnResult } from './dialogTurnResult'
  * Values passed to the `WaterfallStepContext` constructor.
  */
 export interface WaterfallStepInfo<O extends object> {
-  index: number;
-  options: O;
-  reason: DialogReason;
-  result: any;
-  values: object;
-  onNext(result?: any): Promise<DialogTurnResult>;
+  /**
+   * The index of the current step in the waterfall dialog.
+   */
+  index: number
+
+  /**
+   * The options passed to the waterfall dialog when it was started.
+   */
+  options: O
+
+  /**
+   * The reason the current step is being executed.
+   */
+  reason: DialogReason
+
+  /**
+   * The result returned by the previous step or dialog.
+   */
+  result: any
+
+  /**
+   * A dictionary of values shared across all steps in the waterfall dialog.
+   */
+  values: object
+
+  /**
+   * A function to proceed to the next step in the waterfall dialog.
+   *
+   * @param result Optional result to pass to the next step.
+   * @returns A promise resolving to the result of the next dialog turn.
+   */
+  onNext(result?: any): Promise<DialogTurnResult>
 }
 
 /**