@microsoft/agents-hosting-dialogs 1.0.0 → 1.0.3-g444d99f704

package/src/choices/findValues.ts

@@ -31,7 +31,7 @@ export interface FindValuesOptions {
 }
 
 /**
- * @summary Represents a value that was successfully found and matched during a search operation.
+ * Represents a value that was successfully found and matched during a search operation.
  *
  * @remarks
  * This interface contains the matched value along with metadata about the match quality
@@ -49,7 +49,8 @@ export interface FindValuesOptions {
  */
 export interface FoundValue {
   /**
-   * @summary The exact value that was matched from the original search list.
+   * The exact value that was matched from the original search list.
+   *
    * @remarks
    * This is the original string value, not the user's input that matched it.
    *
@@ -58,7 +59,8 @@ export interface FoundValue {
   value: string;
 
   /**
-   * @summary The zero-based index position of this value in the original list that was searched.
+   * The zero-based index position of this value in the original list that was searched.
+   *
    * @remarks
    * This allows you to correlate the found value back to its position in the source array.
    *
@@ -67,7 +69,8 @@ export interface FoundValue {
   index: number;
 
   /**
-   * @summary A confidence score between 0 and 1 indicating the quality of the match.
+   * A confidence score between 0 and 1 indicating the quality of the match.
+   *
    * @remarks
    * - 1.0 indicates a perfect exact match
    * - Lower values indicate partial or fuzzy matches
@@ -79,7 +82,8 @@ export interface FoundValue {
 }
 
 /**
- * @summary Represents a value with its original position that can be used in search operations.
+ * Represents a value with its original position that can be used in search operations.
+ *
  * @remarks
  * This interface is used internally by the search algorithm to maintain the relationship
  * between search values and their original positions in the source array.
@@ -102,7 +106,8 @@ export interface FoundValue {
  */
 export interface SortedValue {
   /**
-   * @summary The string value to be searched for during matching operations.
+   * The string value to be searched for during matching operations.
+   *
    * @remarks
    * This is the actual text content that will be compared against user input.
    *
@@ -111,7 +116,8 @@ export interface SortedValue {
   value: string;
 
   /**
-   * @summary The zero-based index position of this value in the original source array.
+   * The zero-based index position of this value in the original source array.
+   *
    * @remarks
    * This allows the search algorithm to correlate found matches back to their
    * original positions, which is essential for maintaining proper choice selection.
@@ -122,17 +128,20 @@ export interface SortedValue {
 }
 
 /**
- * @summary Low-level function that searches for a set of values within an utterance.
+ * Low-level function that searches for a set of values within an utterance.
+ *
+ * @param utterance The text or user utterance to search over.
+ * @param values List of values to search over.
+ * @param options (Optional) options used to tweak the search that's performed.
+ * @returns A list of found values.
+ *
  * @remarks
  * Higher level functions like `findChoices()` and `recognizeChoices()` are layered above this function.  In most
  * cases its easier to just call one of the higher level functions instead but this function contains
  * the fuzzy search algorithm that drives choice recognition.
  *
  * @internal
- * @param utterance The text or user utterance to search over.
- * @param values List of values to search over.
- * @param options (Optional) options used to tweak the search that's performed.
- * @returns A list of found values.
+
  */
 export function findValues (
   utterance: string,

package/src/componentDialog.ts

@@ -16,36 +16,39 @@ const PERSISTED_DIALOG_STATE = 'dialogs'
 /**
  * Base class for a dialog that contains other child dialogs.
  *
+ * @param O (Optional) options that can be passed into the `DialogContext.beginDialog()` method.
+ *
  * @remarks
  * Component dialogs let you break your agent's logic up into components that can themselves be added
  * as a dialog to another `ComponentDialog` or `DialogSet`. Components can also be exported as part
  * of a node package and used within other agents.
  *
- * @param O (Optional) options that can be passed into the `DialogContext.beginDialog()` method.
  */
 export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
   /**
-     * ID of the child dialog that should be started anytime the component is started.
-     *
-     * @remarks
-     * This defaults to the ID of the first child dialog added using [addDialog()](#adddialog).
-     */
+    * ID of the child dialog that should be started anytime the component is started.
+    *
+    * @remarks
+    * This defaults to the ID of the first child dialog added using [addDialog()](#adddialog).
+    */
   protected initialDialogId: string
 
   /**
-     * Called when the dialog is started and pushed onto the parent's dialog stack.
-     * By default, this calls the
-     * Dialog.BeginDialogAsync(DialogContext, object, CancellationToken) method
-     * of the component dialog's initial dialog, as defined by InitialDialogId.
-     * Override this method in a derived class to implement interrupt logic.
-     *
-     * @param outerDialogContext The parent 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
-     * If the task is successful, the result indicates whether the dialog is still
-     * active after the turn has been processed by the dialog.
-     */
+    * Called when the dialog is started and pushed onto the parent's dialog stack.
+    *
+    * @param outerDialogContext The parent 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
+    * If the task is successful, the result indicates whether the dialog is still
+    * active after the turn has been processed by the dialog.
+    * By default, this calls the
+    * Dialog.BeginDialogAsync(DialogContext, object, CancellationToken) method
+    * of the component dialog's initial dialog, as defined by InitialDialogId.
+    * Override this method in a derived class to implement interrupt logic.
+    *
+    */
   async beginDialog (outerDialogContext: DialogContext, options?: O): Promise<DialogTurnResult> {
     await this.checkForVersionChange(outerDialogContext)
 
@@ -73,14 +76,16 @@ export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
   /**
      * Called when the dialog is _continued_, where it is the active dialog and the
      * user replies with a new Activity.
-     * If this method is *not* overridden, the dialog automatically ends when the user replies.
      *
      * @param outerDialogContext The parent DialogContext for the current turn of conversation.
      * @returns A Promise representing the asynchronous operation.
+     *
      * @remarks
+     * If this method is *not* overridden, the dialog automatically ends when the user replies.
      * If the task is successful, the result indicates whether the dialog is still
      * active after the turn has been processed by the dialog. The result may also contain a
      * return value.
+     *
      */
   async continueDialog (outerDialogContext: DialogContext): Promise<DialogTurnResult> {
     await this.checkForVersionChange(outerDialogContext)
@@ -108,6 +113,7 @@ export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
      * @param _result Optional, value returned from the dialog that was called. The type
      * of the value returned is dependent on the child dialog.
      * @returns A Promise representing the asynchronous operation.
+     *
      * @remarks
      * If the task is successful, the result indicates whether this dialog is still
      * active after this dialog turn has been processed.
@@ -132,12 +138,12 @@ export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
   }
 
   /**
-     * Called when the dialog should re-prompt the user for input.
-     *
-     * @param context The TurnContext object for this turn.
-     * @param instance State information for this dialog.
-     * @returns A Promise representing the asynchronous operation.
-     */
+    * Called when the dialog should re-prompt the user for input.
+    *
+    * @param context The TurnContext object for this turn.
+    * @param instance State information for this dialog.
+    * @returns A Promise representing the asynchronous operation.
+    */
   async repromptDialog (context: TurnContext, instance: DialogInstance): Promise<void> {
     // Forward to inner dialogs
     const innerDC: DialogContext = this.createInnerDC(context, instance)
@@ -148,15 +154,18 @@ export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
   }
 
   /**
-     * Called when the Dialog is ending.
-     *
-     * @param context The TurnContext object for this turn.
-     * @param instance State information associated with the instance of this component Dialog on its parent's dialog stack.
-     * @param reason Reason why the Dialog ended.
-     * @returns A Promise representing the asynchronous operation.
-     * @remarks When this method is called from the parent dialog's context, the component Dialog
-     * cancels all of the dialogs on its inner dialog stack before ending.
-     */
+    * Called when the Dialog is ending.
+    *
+    * @param context The TurnContext object for this turn.
+    * @param instance State information associated with the instance of this component Dialog on its parent's dialog stack.
+    * @param reason Reason why the Dialog ended.
+    * @returns A Promise representing the asynchronous operation.
+    *
+    * @remarks
+    * When this method is called from the parent dialog's context, the component Dialog
+    * cancels all of the dialogs on its inner dialog stack before ending.
+    *
+    */
   async endDialog (context: TurnContext, instance: DialogInstance, reason: DialogReason): Promise<void> {
     // Forward cancel to inner dialogs
     if (reason === DialogReason.cancelCalled) {
@@ -169,13 +178,14 @@ export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
   }
 
   /**
-     * Adds a child Dialog or prompt to the components internal DialogSet.
-     *
-     * @param dialog The child Dialog or prompt to add.
-     * @returns The ComponentDialog after the operation is complete.
-     * @remarks
-     * The Dialog.id of the first child added to the component will be assigned to the initialDialogId property.
-     */
+    * Adds a child Dialog or prompt to the components internal DialogSet.
+    *
+    * @param dialog The child Dialog or prompt to add.
+    * @returns The ComponentDialog after the operation is complete.
+    *
+    * @remarks
+    * The Dialog.id of the first child added to the component will be assigned to the initialDialogId property.
+    */
   addDialog (dialog: Dialog): this {
     this.dialogs.add(dialog)
     if (this.initialDialogId === undefined) {
@@ -196,101 +206,121 @@ export class ComponentDialog<O extends object = {}> extends DialogContainer<O> {
   }
 
   /**
-     * Called anytime an instance of the component has been started.
-     *
-     * @remarks
-     * SHOULD be overridden by components that wish to perform custom interruption logic. The
-     * default implementation calls `innerDC.beginDialog()` with the dialog assigned to
-     * initialdialogid.
-     * @param innerDialogContext Dialog context for the components internal `DialogSet`.
-     * @param options (Optional) options that were passed to the component by its parent.
-     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
-     */
+    * Called anytime an instance of the component has been started.
+    *
+    * @param innerDialogContext Dialog context for the components internal `DialogSet`.
+    * @param options (Optional) options that were passed to the component by its parent.
+    * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
+    *
+    * @remarks
+    * SHOULD be overridden by components that wish to perform custom interruption logic. The
+    * default implementation calls `innerDC.beginDialog()` with the dialog assigned to
+    * `initialDialogId`.
+    *
+    */
   protected onBeginDialog (innerDialogContext: DialogContext, options?: O): Promise<DialogTurnResult> {
     return innerDialogContext.beginDialog(this.initialDialogId, options)
   }
 
   /**
-     * Called anytime a multi-turn component receives additional activities.
-     *
-     * @remarks
-     * SHOULD be overridden by components that wish to perform custom interruption logic. The
-     * default implementation calls `innerDC.continueDialog()`.
-     * @param innerDC Dialog context for the components internal `DialogSet`.
-     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
-     */
+    * Called anytime a multi-turn component receives additional activities.
+    *
+    * @param innerDC Dialog context for the components internal `DialogSet`.
+    * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
+    *
+    * @remarks
+    * SHOULD be overridden by components that wish to perform custom interruption logic. The
+    * default implementation calls `innerDC.continueDialog()`.
+    */
   protected onContinueDialog (innerDC: DialogContext): Promise<DialogTurnResult> {
     return innerDC.continueDialog()
   }
 
   /**
-     * Called when the component is ending.
-     *
-     * @remarks
-     * If the `reason` code is equal to `DialogReason.cancelCalled`, then any active child dialogs
-     * will be cancelled before this method is called.
-     * @param _context Context for the current turn of conversation.
-     * @param _instance The components instance data within its parents dialog stack.
-     * @param _reason The reason the component is ending.
-     * @returns A promise representing the asynchronous operation.
-     */
+    * Called when the component is ending.
+    *
+    * @param _context Context for the current turn of conversation.
+    * @param _instance The components instance data within its parents dialog stack.
+    * @param _reason The reason the component is ending.
+    * @returns A promise representing the asynchronous operation.
+    *
+    * @remarks
+    * If the `reason` code is equal to `DialogReason.cancelCalled`, then any active child dialogs
+    * will be cancelled before this method is called.
+    *
+    */
   protected onEndDialog (_context: TurnContext, _instance: DialogInstance, _reason: DialogReason): Promise<void> {
     return Promise.resolve()
   }
 
   /**
-     * Called when the component has been requested to re-prompt the user for input.
-     *
-     * @remarks
-     * The active child dialog will have already been asked to reprompt before this method is called.
-     * @param _context Context for the current turn of conversation.
-     * @param _instance The instance of the current dialog.
-     * @returns A promise representing the asynchronous operation.
-     */
+    * Called when the component has been requested to re-prompt the user for input.
+    *
+    * @param _context Context for the current turn of conversation.
+    * @param _instance The instance of the current dialog.
+    * @returns A promise representing the asynchronous operation.
+    *
+    * @remarks
+    * The active child dialog will have already been asked to reprompt before this method is called.
+    *
+    */
   protected onRepromptDialog (_context: TurnContext, _instance: DialogInstance): Promise<void> {
     return Promise.resolve()
   }
 
   /**
-     * Called when the components last active child dialog ends and the component is ending.
-     *
-     * @remarks
-     * SHOULD be overridden by components that wish to perform custom logic before the component
-     * ends.  The default implementation calls `outerDC.endDialog()` with the `result` returned
-     * from the last active child dialog.
-     * @param outerDC Dialog context for the parents `DialogSet`.
-     * @param result Result returned by the last active child dialog. Can be a value of `undefined`.
-     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
-     */
+    * Called when the components last active child dialog ends and the component is ending.
+    *
+    * @param outerDC Dialog context for the parents `DialogSet`.
+    * @param result Result returned by the last active child dialog. Can be a value of `undefined`.
+    * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
+    *
+    * @remarks
+    * SHOULD be overridden by components that wish to perform custom logic before the component
+    * ends.  The default implementation calls `outerDC.endDialog()` with the `result` returned
+    * from the last active child dialog.
+    */
   protected endComponent (outerDC: DialogContext, result: any): Promise<DialogTurnResult> {
     return outerDC.endDialog(result)
   }
 
   /**
-     * @private
-     * @param context DialogContext for the current turn of conversation with the user.
-     * @param instance DialogInstance which contains the current state information for this dialog.
-     * @returns A new DialogContext instance.
-     * @remarks
-     * You should only call this if you don't have a dialogContext to work with (such as OnResume())
-     */
+    * Creates a new DialogContext instance for the current turn of conversation.
+    *
+    * @param context DialogContext for the current turn of conversation with the user.
+    * @param instance DialogInstance which contains the current state information for this dialog.
+    * @returns A new DialogContext instance.
+    *
+    * @remarks
+    * You should only call this if you don't have a dialogContext to work with (such as OnResume())
+    *
+    * @private
+    */
   private createInnerDC (context: DialogContext, instance: DialogInstance): DialogContext
   /**
-     * @private
+     * Creates a new DialogContext instance for the current turn of conversation.
+     *
      * @param context TurnContext for the current turn of conversation with the user.
      * @param instance DialogInstance which contains the current state information for this dialog.
      * @returns A new DialogContext instance.
+     *
      * @remarks
      * You should only call this if you don't have a dc to work with (such as OnResume())
+     *
+     * @private
      */
   private createInnerDC (context: TurnContext, instance: DialogInstance): DialogContext
   /**
-     * @private
+     * Creates a new DialogContext instance for the current turn of conversation.
+     *
      * @param context TurnContext or DialogContext for the current turn of conversation with the user.
      * @param instance DialogInstance which contains the current state information for this dialog.
      * @returns A new DialogContext instance.
+     *
      * @remarks
      * You should only call this if you don't have a dc to work with (such as OnResume())
+     *
+     * @private
      */
   private createInnerDC (context: TurnContext | DialogContext, instance: DialogInstance): DialogContext {
     if (!instance) {

package/src/dialog.ts

@@ -39,9 +39,10 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
   /**
      * Unique ID of the dialog.
      *
+     * @returns The Id for the dialog.
+     *
      * @remarks
      * This will be automatically generated if not specified.
-     * @returns The Id for the dialog.
      */
   get id (): string {
     if (this._id === undefined) {
@@ -60,6 +61,8 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
   /**
      * An encoded string used to aid in the detection of agent changes on re-deployment.
      *
+     * @returns Unique string which should only change when dialog has changed in a way that should restart the dialog.
+     *
      * @remarks
      * This defaults to returning the dialog's `id` but can be overridden to provide more
      * precise change detection logic. Any dialog on the stack that has its version change will
@@ -67,7 +70,7 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
      * an error will be thrown resulting in the agent error handler logic being run.
      *
      * Returning an empty string will disable version tracking for the component all together.
-     * @returns Unique string which should only change when dialog has changed in a way that should restart the dialog.
+     *
      */
   getVersion (): string {
     return this.id
@@ -96,6 +99,7 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
      * When overridden in a derived class, continues the dialog.
      *
      * @param dc The context for the current dialog turn.
+     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
      *
      * @remarks
      * Derived dialogs that support multiple-turn conversations should override this method.
@@ -107,7 +111,6 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
      * To signal to the dialog context that this dialog has completed, await
      * {@link DialogContext.endDialog} before exiting this method.
      *
-     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
      */
   async continueDialog (dc: DialogContext): Promise<DialogTurnResult> {
     // By default just end the current dialog.
@@ -120,6 +123,7 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
      * @param dc The context for the current dialog turn.
      * @param reason The reason the dialog is resuming. This will typically be DialogReason.endCalled
      * @param result Optional. The return value, if any, from the dialog that ended.
+     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
      *
      * @remarks
      * Derived dialogs that support multiple-turn conversations should override this method.
@@ -133,7 +137,6 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
      * necessarily be the one that started the child dialog.
      * To signal to the dialog context that this dialog has completed, await {@link DialogContext.endDialog} before exiting this method.
      *
-     * @returns {Promise<DialogTurnResult>} A promise resolving to the dialog turn result.
      */
   async resumeDialog (dc: DialogContext, reason: DialogReason, result?: any): Promise<DialogTurnResult> {
     // By default just end the current dialog and return result to parent.
@@ -205,13 +208,14 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
   /**
      * Called before an event is bubbled to its parent.
      *
+     * @param _dc The dialog context for the current turn of conversation.
+     * @param _e 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.
-     * @param _dc The dialog context for the current turn of conversation.
-     * @param _e The event being raised.
-     * @returns Whether the event is handled by the current dialog and further processing should stop.
      */
   protected async onPreBubbleEvent (_dc: DialogContext, _e: DialogEvent): Promise<boolean> {
     return false
@@ -220,12 +224,13 @@ export abstract class Dialog<O extends object = {}> extends Configurable {
   /**
      * Called after an event was bubbled to all parents and wasn't handled.
      *
-     * @remarks
-     * This is a good place to perform default processing logic for an event. Returning `true` will
-     * prevent any processing of the event by child dialogs.
      * @param _dc The dialog context for the current turn of conversation.
      * @param _e 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 default processing logic for an event. Returning `true` will
+     * prevent any processing of the event by child dialogs.
      */
   protected async onPostBubbleEvent (_dc: DialogContext, _e: DialogEvent): Promise<boolean> {
     return false

package/src/dialogContainer.ts

@@ -55,13 +55,14 @@ export abstract class DialogContainer<O extends object = {}> extends Dialog<O> {
   /**
      * Returns internal version identifier for this container.
      *
+     * @returns Version which represents the change of the internals of this container.
+     *
      * @remarks
      * DialogContainers detect changes of all sub-components in the container and map that to a `versionChanged` event.
      * Because they do this, DialogContainers "hide" the internal changes and just have the .id. This isolates changes
      * to the container level unless a container doesn't handle it.  To support this DialogContainers define a
      * protected method getInternalVersion() which computes if this dialog or child dialogs have changed
      * which is then examined via calls to checkForVersionChange().
-     * @returns Version which represents the change of the internals of this container.
      */
   protected getInternalVersion (): string {
     return this.dialogs.getVersion()
@@ -71,9 +72,11 @@ export abstract class DialogContainer<O extends object = {}> extends Dialog<O> {
      * Checks to see if a containers child dialogs have changed since the current dialog instance
      * was started.
      *
+     * @param dialogContext Current dialog context.
+     *
      * @remarks
      * This should be called at the start of `beginDialog()`, `continueDialog()`, and `resumeDialog()`.
-     * @param dialogContext Current dialog context.
+     *
      */
   protected async checkForVersionChange (dialogContext: DialogContext): Promise<void> {
     const current = dialogContext.activeDialog.version