@microsoft/agents-hosting-dialogs 0.6.1 → 0.6.11

package/src/memory/dialogStateManager.ts

@@ -12,15 +12,50 @@ import { DialogsComponentRegistration } from '../dialogsComponentRegistration'
 import { MemoryScope } from './scopes'
 import { PathResolver } from './pathResolvers'
 
+/**
+ * Configuration options for the DialogStateManager.
+ *
+ * @remarks
+ * This interface defines the configuration settings that control how the DialogStateManager
+ * resolves memory paths and manages different memory scopes within a dialog context.
+ * The configuration is shared across all DialogStateManager instances within a dialog chain
+ * and is cached in turn state for performance optimization.
+ */
 export interface DialogStateManagerConfiguration {
   /**
-     * List of path resolvers used to evaluate memory paths.
-     */
+   * List of path resolvers used to evaluate and transform memory path expressions.
+   *
+   * @remarks
+   * Path resolvers provide shortcut behavior for mapping path expressions to their
+   * actual memory locations. For example, a resolver might transform '$foo' to 'dialog.foo'
+   * or 'user.name' to 'user.profile.name'. Resolvers are applied in order during path
+   * transformation, allowing for complex path mapping scenarios.
+   *
+   * Common path resolver types include:
+   * - Dollar sign resolvers (e.g., $variable -> dialog.variable)
+   * - Scope alias resolvers (e.g., this -> dialog)
+   * - Custom application-specific resolvers
+   */
   readonly pathResolvers: PathResolver[];
 
   /**
-     * List of the supported memory scopes.
-     */
+   * List of the supported memory scopes available to the dialog state manager.
+   *
+   * @remarks
+   * Memory scopes are named root-level objects that provide access to different
+   * types of persistent and transient data within the dialog system. Each scope
+   * manages its own data lifecycle including loading, saving, and deletion operations.
+   *
+   * Common memory scope types include:
+   * - dialog: Dialog-specific data that persists across turns
+   * - user: User-specific data that persists across conversations
+   * - conversation: Conversation-specific data
+   * - turn: Turn-specific data (transient)
+   * - settings: Application configuration data
+   *
+   * Scopes can exist either in the dialog context or in turn state, and each
+   * scope determines whether it should be included in memory snapshots for debugging.
+   */
   readonly memoryScopes: MemoryScope[];
 }
 
@@ -29,7 +64,7 @@ const PATH_TRACKER = 'dialog._tracker.paths'
 const DIALOG_STATE_MANAGER_CONFIGURATION = 'DialogStateManagerConfiguration'
 
 /**
- * The DialogStateManager manages memory scopes and path resolvers.
+ * Manages memory scopes and path resolvers.
  *
  * @remarks
  * MemoryScopes are named root level objects, which can exist either in the dialog context or off

package/src/prompts/confirmPrompt.ts

@@ -9,9 +9,60 @@ import { ListStyle, Prompt, PromptOptions, PromptRecognizerResult, PromptValidat
 import { PromptCultureModels } from './promptCultureModels'
 import { Activity } from '@microsoft/agents-activity'
 
-// Need ChoiceDefaultsProperty so we can set choiceDefaults dynamically with lambda
+/**
+ * Defines locale-specific choice defaults for confirmation prompts.
+ *
+ * @remarks
+ * This interface represents a dictionary that maps locale strings to their corresponding
+ * choice configurations for confirmation prompts. Each locale entry contains the localized
+ * "yes" and "no" choices along with formatting options for how those choices should be
+ * presented to the user.
+ *
+ * The interface is designed to support dynamic configuration of choice defaults using
+ * lambda expressions or other dynamic assignment patterns.
+ *
+ * @example
+ * ```typescript
+ * const customChoiceDefaults: ChoiceDefaultsConfirmPrompt = {
+ *   'en-us': {
+ *     choices: ['Yes', 'No'],
+ *     options: {
+ *       inlineSeparator: ', ',
+ *       inlineOr: ' or ',
+ *       includeNumbers: true
+ *     }
+ *   },
+ *   'es-es': {
+ *     choices: ['Sí', 'No'],
+ *     options: {
+ *       inlineSeparator: ', ',
+ *       inlineOr: ' o ',
+ *       includeNumbers: true
+ *     }
+ *   }
+ * };
+ * ```
+ */
 export interface ChoiceDefaultsConfirmPrompt {
-  [locale: string]: { choices: (string | Choice)[]; options: ChoiceFactoryOptions };
+  /**
+   * Locale-specific choice configuration.
+   *
+   * @remarks
+   * The key is a locale string (e.g., 'en-us', 'fr-fr', 'de-de') and the value
+   * contains the localized choices and formatting options for that locale.
+   */
+  [locale: string]: {
+    /**
+     * Array of localized choice options, typically ["Yes", "No"] equivalents.
+     * Can be either string values or Choice objects for more complex configurations.
+     */
+    choices: (string | Choice)[];
+    /**
+     * Formatting options that control how the choices are presented to the user,
+     * including separators, conjunctions, and whether to include numbers.
+     */
+    options: ChoiceFactoryOptions
+  };
 }
 
 /**

package/src/prompts/prompt.ts

@@ -105,7 +105,8 @@ export interface PromptRecognizerResult<T> {
 /**
  * Function signature for providing a custom prompt validator.
  *
- * ```TypeScript
+ * @example
+ * ```typescript
  * type PromptValidator<T> = (prompt: PromptValidatorContext<T>) => Promise<boolean>;
  * ```
  *

package/src/prompts/promptCultureModels.ts

@@ -1,47 +1,86 @@
 import { Culture } from '@microsoft/recognizers-text-suite'
 
+/**
+ * Represents a culture-specific model that defines localization settings for prompts.
+ * This interface provides language-specific formatting rules and translations for
+ * interactive prompts such as choice lists and confirmation dialogs.
+ */
 export interface PromptCultureModel {
   /**
-     * Culture Model's Locale.
-     *
-     * @example
-     * "en-US"
-     */
+   * The locale identifier for this culture model.
+   * This follows the standard IETF language tag format (e.g., "en-US", "fr-FR", "ja-JP").
+   * Used to identify the target language and region for localization.
+   *
+   * @example
+   * "en-US" // English (United States)
+   * @example
+   * "fr-FR" // French (France)
+   * @example
+   * "ja-JP" // Japanese (Japan)
+   */
   locale: string;
+
   /**
-     * Culture Model's InlineSeparator.
-     *
-     * @example
-     * ", "
-     */
+   * The separator string used to delimit items in a list when presenting choices.
+   * This is typically used between items in the middle of a list, not before the final item.
+   *
+   * @example
+   * ", " // English: "apple, banana, orange"
+   * @example
+   * "、 " // Japanese: "りんご、 バナナ、 オレンジ"
+   */
   separator: string;
+
   /**
-     * Culture Model's InlineOr.
-     *
-     * @example
-     * " or "
-     */
+   * The conjunction string used before the final item in a two-item list.
+   * This is used when presenting exactly two choices to the user.
+   *
+   * @example
+   * " or " // English: "apple or banana"
+   * @example
+   * " ou " // French: "pomme ou banane"
+   * @example
+   * " または " // Japanese: "りんご または バナナ"
+   */
   inlineOr: string;
+
   /**
-     * Culture Model's InlineOrMore.
-     *
-     * @example
-     * ", or "
-     */
+   * The conjunction string used before the final item in a list of three or more items.
+   * This combines with the separator to create properly formatted choice lists.
+   *
+   * @example
+   * ", or " // English: "apple, banana, or orange"
+   * @example
+   * ", ou " // French: "pomme, banane, ou orange"
+   * @example
+   * "、 または " // Japanese: "りんご、 バナナ、 または オレンジ"
+   */
   inlineOrMore: string;
+
   /**
-     * Equivalent of "Yes" in Culture Model's Language.
-     *
-     * @example
-     * "Yes"
-     */
+   * The affirmative response word in the target language.
+   * Used in confirmation prompts and boolean choice scenarios.
+   *
+   * @example
+   * "Yes" // English
+   * @example
+   * "Oui" // French
+   * @example
+   * "はい" // Japanese
+   */
   yesInLanguage: string;
+
   /**
-     * Equivalent of "No" in Culture Model's Language.
-     *
-     * @example
-     * "No"
-     */
+   * The negative response word in the target language.
+   * Used in confirmation prompts and boolean choice scenarios.
+   *
+   * @example
+   * "No" // English
+   * @example
+   * "Non" // French
+   * @example
+   * "いいえ" // Japanese
+   */
   noInLanguage: string;
 }
 

package/src/recognizer.ts

@@ -8,13 +8,30 @@ import { DialogContext } from './dialogContext'
 import omit from 'lodash/omit'
 import { RecognizerResult, getTopScoringIntent } from './recognizerResult'
 
+/**
+ * Configuration options for a recognizer instance.
+ *
+ * @remarks
+ * This interface defines the configuration properties that can be used to customize
+ * the behavior and identification of a recognizer. Recognizers use this configuration
+ * to set up their basic properties and operational parameters.
+ */
 export interface RecognizerConfiguration {
+  /**
+   * Optional unique identifier for the recognizer instance.
+   *
+   * @remarks
+   * The id property allows you to distinguish between multiple recognizer instances
+   * and can be useful for logging, debugging, and telemetry purposes. If not provided,
+   * the recognizer will operate without a specific identifier.
+   */
   id?: string;
 }
 
 /**
  * Base class for implementing custom recognizers to identify intents and entities from user input.
  *
+ * @remarks
  * 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.

package/src/recognizerResult.ts

@@ -34,6 +34,32 @@ export interface RecognizerResult {
   [propName: string]: any
 }
 
+/**
+ * Finds the intent with the highest confidence score from a recognizer result.
+ *
+ * This function iterates through all intents in the recognizer result and returns
+ * the intent name and score for the intent with the highest confidence score.
+ * If multiple intents have the same highest score, the last one encountered is returned.
+ *
+ * @param result - The recognizer result containing intents and their scores
+ * @returns An object containing the top-scoring intent name and its confidence score
+ * @throws {Error} Throws an error if the result is empty or doesn't contain intents
+ *
+ * @example
+ * ```typescript
+ * const result: RecognizerResult = {
+ *   text: "Book a flight to Seattle",
+ *   intents: {
+ *     "BookFlight": { score: 0.95 },
+ *     "Cancel": { score: 0.02 },
+ *     "Help": { score: 0.03 }
+ *   }
+ * };
+ *
+ * const topIntent = getTopScoringIntent(result);
+ * // Returns: { intent: "BookFlight", score: 0.95 }
+ * ```
+ */
 export const getTopScoringIntent = (result: RecognizerResult): { intent: string; score: number } => {
   if (!result || !result.intents) {
     throw new Error('result is empty')