botframework-webchat-api 4.13.0 → 4.15.0

package/src/StyleOptions.ts

@@ -1,3 +1,5 @@
+import { DirectLineActivity } from 'botframework-webchat-core';
+
 type StyleOptions = {
   /**
    * Basic styling
@@ -219,7 +221,10 @@ type StyleOptions = {
 
   /**
    * Prevent scroll to end button from rendering
+   *
+   * @deprecated Since 4.14.0: To hide the scroll to end button, please set `scrollToEndButtonBehavior` to `false`.
    */
+  // TODO: [P4] Will be removed on or after 2023-06-02.
   hideScrollToEndButton?: boolean;
 
   /**
@@ -243,7 +248,7 @@ type StyleOptions = {
   /**
    * Specify number of pixels to overscroll or underscroll after pause
    */
-  autoScrollSnapOnPageoffset?: number;
+  autoScrollSnapOnPageOffset?: number;
 
   /**
    * Send box styling
@@ -254,15 +259,101 @@ type StyleOptions = {
   microphoneButtonColorOnDictate?: string;
   sendBoxBackground?: string;
 
+  /** Send box button: Icon color, defaults to subtle */
+  sendBoxButtonColor?: string;
+
   /**
-   * Button color defaults to subtle
+   * Send box button: Shade border radius
+   *
+   * @default 2
    */
-  sendBoxButtonColor?: string;
+  sendBoxButtonShadeBorderRadius?: number;
+
+  /** Send box button: Shade color */
+  sendBoxButtonShadeColor?: string;
+
+  /**
+   * Send box button: Shade inset
+   *
+   * @default 2
+   */
+  sendBoxButtonShadeInset?: number;
+
+  /** Send box button (while `:active`): Icon color */
+  sendBoxButtonColorOnActive?: string;
 
+  /**
+   * Send box button (while `:active`): Shade color
+   *
+   * @default '#EDEBE9'
+   */
+  sendBoxButtonShadeColorOnActive?: string;
+
+  /**
+   * Send box button (while `:disabled`): Icon color
+   *
+   * @default '#A19F9D'
+   */
   sendBoxButtonColorOnDisabled?: string;
+
+  /**
+   * Send box button (while `:disabled`): Shade color
+   *
+   * @default '#F3F2F1'
+   */
+  sendBoxButtonShadeColorOnDisabled?: string;
+
+  /** Send box button (while `:focus`): Icon color */
   sendBoxButtonColorOnFocus?: string;
+
+  /** Send box button (while `:focus`): Shade color */
+  sendBoxButtonShadeColorOnFocus?: string;
+
+  /** Send box button (while `:hover`): Icon color */
   sendBoxButtonColorOnHover?: string;
 
+  /**
+   * Send box button (while `:hover`): Shade color
+   *
+   * @default '#F3F2F1'
+   */
+  sendBoxButtonShadeColorOnHover?: string;
+
+  /**
+   * Send box button (while `:focus-visible`): Keyboard focus indicator border color
+   *
+   * @default '#605E5C'
+   */
+  sendBoxButtonKeyboardFocusIndicatorBorderColor?: string;
+
+  /**
+   * Send box button (while `:focus-visible`): Keyboard focus indicator border radius
+   *
+   * @default 0
+   */
+  sendBoxButtonKeyboardFocusIndicatorBorderRadius?: number | string;
+
+  /**
+   * Send box button (while `:focus-visible`): Keyboard focus indicator border style
+   *
+   * @default 'solid'
+   */
+  sendBoxButtonKeyboardFocusIndicatorBorderStyle?: string;
+
+  /**
+   * Send box button (while` :focus-visible`): Keyboard focus indicator border width
+   *
+   * @default 4
+   */
+  sendBoxButtonKeyboardFocusIndicatorBorderWidth?: number;
+
+  /**
+   * Send box button (while `:focus-visible`): Keyboard focus indicator inset
+   *
+   * @default 4
+   */
+  sendBoxButtonKeyboardFocusIndicatorInset?: number;
+
   /**
    * Disabled text color defaults to subtle
    */
@@ -297,35 +388,230 @@ type StyleOptions = {
    * Suggested Actions
    */
 
+  /**
+   * Suggested action: border radius
+   *
+   * @default 0
+   */
+  suggestedActionBorderRadius?: number | string;
+
+  /**
+   * Suggested action: Background
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBackgroundColor` instead. This option will be removed on or after 2023-09-16.
+   */
   suggestedActionBackground?: string;
 
   /**
-   * Border color defaults to accent.
+   * Suggested action: Background color
+   *
+   * @default 'White'
    */
+  suggestedActionBackgroundColor?: string;
+
+  /** Suggested action: Border color, defaults to accent color */
   suggestedActionBorderColor?: string;
 
-  suggestedActionBorderRadius?: number | string;
+  /**
+   * Suggested action: Border style
+   *
+   * @default 'solid'
+   */
   suggestedActionBorderStyle?: string;
-  suggestedActionBorderWidth?: number | string;
 
   /**
-   * Disabled background defaults to suggestedActionBackground
+   * Suggested action: Border width
+   *
+   * @default 2
+   */
+  suggestedActionBorderWidth?: number;
+
+  /** Suggested action: Text color, defaults to accent color */
+  suggestedActionTextColor?: string;
+
+  /** Suggested action (while `:disabled`): Background color, defaults to suggestedActionBackground */
+  suggestedActionBackgroundColorOnDisabled?: string;
+
+  /**
+   * Suggested action (while `:disabled`): Border color
+   *
+   * @default '#E6E6E6'
+   */
+  suggestedActionBorderColorOnDisabled?: string;
+
+  /** Suggested action (while `:disabled`): Border style */
+  suggestedActionBorderStyleOnDisabled?: string;
+
+  /** Suggested action (while `:disabled`): Border width */
+  suggestedActionBorderWidthOnDisabled?: number;
+
+  /** Suggested action (while `:disabled`): Foreground color, defaults to subtle color */
+  suggestedActionTextColorOnDisabled?: string;
+
+  /**
+   * Suggested action (while `:active`): Background color
+   *
+   * @default '#EDEBE9'
+   */
+  suggestedActionBackgroundColorOnActive?: string;
+
+  /** Suggested action (while `:active`): Border color */
+  suggestedActionBorderColorOnActive?: string;
+
+  /** Suggested action (while `:active`): Border style */
+  suggestedActionBorderStyleOnActive?: string;
+
+  /** Suggested action (while `:active`): Border width */
+  suggestedActionBorderWidthOnActive?: number;
+
+  /** Suggested action (while `:active`): Text color */
+  suggestedActionTextColorOnActive?: string;
+
+  /** Suggested action (while `:focus`): Background color */
+  suggestedActionBackgroundColorOnFocus?: string;
+
+  /** Suggested action (while `:focus`): Border color */
+  suggestedActionBorderColorOnFocus?: string;
+
+  /** Suggested action (while `:focus`): Border style */
+  suggestedActionBorderStyleOnFocus?: string;
+
+  /** Suggested action (while `:focus`): Border width */
+  suggestedActionBorderWidthOnFocus?: number;
+
+  /** Suggested action (while `:focus`): Text color */
+  suggestedActionTextColorOnFocus?: string;
+
+  /**
+   * Suggested action (while `:hover`): Background color
+   *
+   * @default '#F3F2F1'
+   */
+  suggestedActionBackgroundColorOnHover?: string;
+
+  /** Suggested action (while `:hover`): Border color */
+  suggestedActionBorderColorOnHover?: string;
+
+  /** Suggested action (while `:hover`): Border style */
+  suggestedActionBorderStyleOnHover?: string;
+
+  /** Suggested action (while `:hover`): Border width */
+  suggestedActionBorderWidthOnHover?: number;
+
+  /** Suggested action (while `:hover`): Text color */
+  suggestedActionTextColorOnHover?: string;
+
+  /**
+   * Suggested action (while `:disabled`): Background, defaults to suggestedActionBackground.
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBackgroundColorOnDisabled` instead. This option will be removed on or after 2023-09-16.
    */
   suggestedActionDisabledBackground?: string;
 
+  /**
+   * Suggested action (while `:disabled`): Border color
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBorderColorOnDisabled` instead. This option will be removed on or after 2023-09-16.
+   */
   suggestedActionDisabledBorderColor?: string;
+
+  /**
+   * Suggested action (while `:disabled`): Border style
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBorderStyleOnDisabled` instead. This option will be removed on or after 2023-09-16.
+   */
   suggestedActionDisabledBorderStyle?: string;
-  suggestedActionDisabledBorderWidth?: number | string;
 
   /**
-   * Disabled text color defaults to subtle
+   * Suggested action (while `:disabled`): Border width
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBorderWidthOnDisabled` instead. This option will be removed on or after 2023-09-16.
+   */
+  suggestedActionDisabledBorderWidth?: number;
+
+  /**
+   * Suggested action (while `:disabled`): Foreground color, defaults to subtle color
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionTextColorOnDisabled` instead. This option will be removed on or after 2023-09-16.
    */
   suggestedActionDisabledTextColor?: string;
 
+  /**
+   * Suggested action: Height
+   *
+   * @default 40
+   */
   suggestedActionHeight?: number | string;
+
+  /**
+   * Suggested action: Image height
+   *
+   * @default 20
+   */
   suggestedActionImageHeight?: number | string;
+
+  /**
+   * Suggested action: Layout type
+   *
+   * @default 'carousel'
+   */
   suggestedActionLayout?: 'carousel' | 'flow' | 'stacked';
-  suggestedActionTextColor?: string;
+
+  /**
+   * Suggested action (while `:focus-visible`): Keyboard focus indicator border color
+   *
+   * @default '#605E5C'
+   */
+  suggestedActionKeyboardFocusIndicatorBorderColor?: string;
+
+  /**
+   * Suggested action (while `:focus-visible`): Keyboard focus indicator border radius
+   *
+   * @default 0
+   */
+  suggestedActionKeyboardFocusIndicatorBorderRadius?: number | string;
+
+  /**
+   * Suggested action (while `:focus-visible`): Keyboard focus indicator border style
+   *
+   * @default 'solid'
+   */
+  suggestedActionKeyboardFocusIndicatorBorderStyle?: string;
+
+  /**
+   * Suggested action (while `:focus-visible`): Keyboard focus indicator border width
+   *
+   * @default 1
+   */
+  suggestedActionKeyboardFocusIndicatorBorderWidth?: number;
+
+  /**
+   * Suggested action (while `:focus-visible`): Keyboard focus indicator inset
+   *
+   * @default 2
+   */
+  suggestedActionKeyboardFocusIndicatorInset?: number;
+
+  /**
+   * Suggested action (while `:active`): background
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBackgroundColorOnActive` instead. This option will be removed on or after 2023-09-16.
+   */
+  suggestedActionActiveBackground?: string;
+
+  /**
+   * Suggested action (while `:focus`): background
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBackgroundColorOnFocus` instead. This option will be removed on or after 2023-09-16.
+   */
+  suggestedActionFocusBackground?: string;
+
+  /**
+   * Suggested action (while `:hover`): background
+   *
+   * @deprecated Since 4.15.0: Please use `suggestedActionBackgroundColorOnHover` instead. This option will be removed on or after 2023-09-16.
+   */
+  suggestedActionHoverBackground?: string;
 
   /**
    * Suggested actions carousel layout
@@ -362,9 +648,9 @@ type StyleOptions = {
   suggestedActionsStackedHeight?: number | 'auto';
 
   /**
-   * Stacked overflow default value is 'auto
+   * Stacked overflow default value is 'auto'
    */
-  suggestedActionsStackedOverflow?: 'string';
+  suggestedActionsStackedOverflow?: 'auto' | 'hidden' | 'scroll' | 'visible';
 
   /**
    * Button max height default value is 100% if suggestedActionsStackedLayoutButtonTextWrap is true
@@ -380,8 +666,16 @@ type StyleOptions = {
    * Timestamp
    */
 
-  groupTimestamp?: boolean;
-  sendTimeout?: number;
+  /**
+   * Specifies the time window for grouping related timestamps.
+   *
+   * `number` - time window for grouping related timestamps (in milliseconds)
+   * `false` - never group timestamps
+   * `true` - group all timestamps
+   */
+  groupTimestamp?: boolean | number;
+
+  sendTimeout?: number | ((activity: DirectLineActivity) => number);
   sendTimeoutForAttachments?: number;
 
   /**
@@ -413,7 +707,26 @@ type StyleOptions = {
    * e.g. carousel and suggested action flippers, scroll to bottom, etc.
    */
 
+  /**
+   * Controls when the new messages button should show.
+   *
+   * - `"unread"` will show when there are any unread and offscreen messages (default)
+   * - `"any"` will show when there are any offscreen messages
+   * - `false` will always hide the button
+   */
+  scrollToEndButtonBehavior?: false | 'any' | 'unread';
+
+  /** Font size of the new message button. */
+  scrollToEndButtonFontSize?: number | string;
+
+  /**
+   * Font size of the new message button.
+   *
+   * @deprecated Since 4.14.0: Renamed to {@linkcode scrollToEndButtonFontSize}.
+   */
+  // TODO: [P4] Will be removed on or after 2023-06-02.
   newMessagesButtonFontSize?: number | string;
+
   transcriptOverlayButtonBackground?: string;
   transcriptOverlayButtonBackgroundOnDisabled?: string;
   transcriptOverlayButtonBackgroundOnFocus?: string;
@@ -484,7 +797,11 @@ type StyleOptions = {
   videoHeight?: number | string;
 };
 
-type StrictStyleOptions = Required<StyleOptions> & {
+// StrictStyleOptions is only used internally in Web Chat and for simplifying our code:
+// 1. Allow developers to set the "bubbleNubOffset" option as "top" (string), but when we normalize them, we will convert it to 0 (number);
+// 2. Renamed/deprecated options, only the newer option will be kept, the older option will be dropped.
+//    Internally, no code should use the deprecated value except the migration code.
+type StrictStyleOptions = Required<Omit<StyleOptions, 'hideScrollToEndButton' | 'newMessagesButtonFontSize'>> & {
   bubbleFromUserNubOffset: number;
   bubbleNubOffset: number;
   emojiSet: false | Record<string, string>;

package/src/defaultStyleOptions.ts

@@ -84,21 +84,43 @@ const DEFAULT_OPTIONS: Required<StyleOptions> = {
   markdownRespectCRLF: true,
 
   // Scroll behavior
-  hideScrollToEndButton: false,
+  hideScrollToEndButton: undefined, // Deprecated as of 4.14.0. Use "scrollToEndButtonBehavior" instead. Remove on or after 2023-06-02.
   autoScrollSnapOnActivity: false,
   autoScrollSnapOnActivityOffset: 0,
   autoScrollSnapOnPage: false,
-  autoScrollSnapOnPageoffset: 0,
+  autoScrollSnapOnPageOffset: 0, // TODO: Rename from "autoScrollSnapOnPageoffset".
 
   // Send box
   hideSendBox: false,
   hideUploadButton: false,
   microphoneButtonColorOnDictate: '#F33',
   sendBoxBackground: 'White',
+
+  // Send box buttons
   sendBoxButtonColor: undefined,
-  sendBoxButtonColorOnDisabled: '#CCC',
-  sendBoxButtonColorOnFocus: '#333',
-  sendBoxButtonColorOnHover: '#333',
+  sendBoxButtonShadeColor: undefined,
+
+  sendBoxButtonColorOnActive: undefined,
+  sendBoxButtonShadeColorOnActive: '#EDEBE9',
+
+  sendBoxButtonColorOnDisabled: '#A19F9D',
+  sendBoxButtonShadeColorOnDisabled: '#F3F2F1',
+
+  sendBoxButtonColorOnFocus: undefined,
+  sendBoxButtonShadeColorOnFocus: undefined,
+
+  sendBoxButtonColorOnHover: undefined,
+  sendBoxButtonShadeColorOnHover: '#F3F2F1',
+
+  sendBoxButtonShadeBorderRadius: 2,
+  sendBoxButtonShadeInset: 2,
+
+  sendBoxButtonKeyboardFocusIndicatorBorderColor: '#605E5C',
+  sendBoxButtonKeyboardFocusIndicatorBorderRadius: 0,
+  sendBoxButtonKeyboardFocusIndicatorBorderStyle: 'solid',
+  sendBoxButtonKeyboardFocusIndicatorBorderWidth: 1,
+  sendBoxButtonKeyboardFocusIndicatorInset: 4,
+
   sendBoxDisabledTextColor: undefined,
   sendBoxHeight: 40,
   sendBoxMaxHeight: 200,
@@ -121,21 +143,57 @@ const DEFAULT_OPTIONS: Required<StyleOptions> = {
   spinnerAnimationPadding: 12,
 
   // Suggested actions
-  suggestedActionBackground: 'White',
-  suggestedActionBorderColor: undefined,
   suggestedActionBorderRadius: 0,
-  suggestedActionBorderStyle: 'solid',
-  suggestedActionBorderWidth: 2,
-  suggestedActionDisabledBackground: undefined,
-  suggestedActionDisabledBorderColor: '#E6E6E6',
-  suggestedActionDisabledBorderStyle: 'solid',
-  suggestedActionDisabledBorderWidth: 2,
-  suggestedActionDisabledTextColor: undefined,
   suggestedActionHeight: 40,
   suggestedActionImageHeight: 20,
   suggestedActionLayout: 'carousel',
+
+  suggestedActionBackgroundColor: 'White',
+  suggestedActionBorderColor: undefined,
+  suggestedActionBorderStyle: 'solid',
+  suggestedActionBorderWidth: 2,
   suggestedActionTextColor: undefined,
 
+  suggestedActionBackgroundColorOnActive: '#EDEBE9',
+  suggestedActionBorderColorOnActive: undefined,
+  suggestedActionBorderStyleOnActive: undefined,
+  suggestedActionBorderWidthOnActive: undefined,
+  suggestedActionTextColorOnActive: undefined,
+
+  suggestedActionBackgroundColorOnDisabled: undefined,
+  suggestedActionBorderColorOnDisabled: '#E6E6E6',
+  suggestedActionBorderStyleOnDisabled: undefined,
+  suggestedActionBorderWidthOnDisabled: undefined,
+  suggestedActionTextColorOnDisabled: undefined,
+
+  suggestedActionBackgroundColorOnFocus: undefined,
+  suggestedActionBorderColorOnFocus: undefined,
+  suggestedActionBorderStyleOnFocus: undefined,
+  suggestedActionBorderWidthOnFocus: undefined,
+  suggestedActionTextColorOnFocus: undefined,
+
+  suggestedActionBackgroundColorOnHover: '#F3F2F1',
+  suggestedActionBorderColorOnHover: undefined,
+  suggestedActionBorderStyleOnHover: undefined,
+  suggestedActionBorderWidthOnHover: undefined,
+  suggestedActionTextColorOnHover: undefined,
+
+  suggestedActionKeyboardFocusIndicatorBorderColor: '#605E5C',
+  suggestedActionKeyboardFocusIndicatorBorderRadius: 0,
+  suggestedActionKeyboardFocusIndicatorBorderStyle: 'solid',
+  suggestedActionKeyboardFocusIndicatorBorderWidth: 1,
+  suggestedActionKeyboardFocusIndicatorInset: 2,
+
+  suggestedActionActiveBackground: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionBackground: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionDisabledBackground: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionDisabledBorderColor: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionDisabledBorderStyle: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionDisabledBorderWidth: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionDisabledTextColor: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionFocusBackground: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+  suggestedActionHoverBackground: undefined, // Deprecated as of 4.15.0. Remove on or after 2023-09-16.
+
   // Suggested actions carousel layout
   suggestedActionsCarouselFlipperCursor: undefined,
   suggestedActionsCarouselFlipperBoxWidth: 40,
@@ -158,7 +216,9 @@ const DEFAULT_OPTIONS: Required<StyleOptions> = {
   timestampFormat: 'relative',
 
   // Transcript overlay buttons
-  newMessagesButtonFontSize: '85%',
+  scrollToEndButtonBehavior: 'unread',
+  scrollToEndButtonFontSize: '85%',
+  newMessagesButtonFontSize: undefined, // Deprecated as of 4.14.0, renamed to "scrollToEndButtonFontSize". Remove on or after 2023-06-02.
   transcriptOverlayButtonBackground: 'rgba(0, 0, 0, .6)',
   transcriptOverlayButtonBackgroundOnDisabled: 'rgba(0, 0, 0, .6)',
   transcriptOverlayButtonBackgroundOnFocus: 'rgba(0, 0, 0, .8)',