botframework-webchat-component 4.18.1 → 4.19.0

package/src/providers/HTMLContentTransformCOR/useTransformHTMLContent.ts

@@ -0,0 +1,187 @@
+import { hooks } from 'botframework-webchat-api';
+import { useCallback } from 'react';
+
+import useCodeBlockTag from '../CustomElements/useCodeBlockTagName';
+import useHTMLContentTransformContext from './private/useHTMLContentTransformContext';
+
+const { useLocalizer } = hooks;
+
+const DEFAULT_ALLOWED_TAGS: ReadonlyMap<string, Readonly<{ attributes: ReadonlySet<string> }>> = Object.freeze(
+  new Map(
+    (
+      [
+        ['a', ['aria-label', 'class', 'href', 'name', 'rel', 'target']],
+        ['b', []],
+        ['blockquote', []],
+        ['br', []],
+        ['button', ['aria-label', 'class', 'type', 'value']],
+        ['caption', []],
+        ['code', ['data-math-type']],
+        ['del', []],
+        ['div', []],
+        ['em', []],
+        ['figure', ['data-math-type', 'tabindex']],
+        ['h1', []],
+        ['h2', []],
+        ['h3', []],
+        ['h4', []],
+        ['h5', []],
+        ['h6', []],
+        ['hr', []],
+        ['i', []],
+        ['img', ['alt', 'aria-label', 'class', 'src', 'title']],
+        ['ins', []],
+        ['li', []],
+        ['nl', []],
+        ['ol', []],
+        ['p', []],
+        ['pre', ['class', 'data-math-type']],
+        ['s', []],
+        ['span', ['aria-label', 'data-math-type']],
+        ['strike', []],
+        ['strong', []],
+        ['table', []],
+        ['tbody', []],
+        ['td', []],
+        ['tfoot', []],
+        ['th', []],
+        ['thead', []],
+        ['tr', []],
+        ['ul', []],
+
+        // Followings are for MathML elements, from https://developer.mozilla.org/en-US/docs/Web/MathML.
+        ['annotation-xml', ['encoding', 'src', 'name', 'definitionURL']],
+        ['annotation', ['encoding', 'src', 'name', 'definitionURL']],
+        ['math', ['display', 'xmlns', 'mode', 'overflow', 'alttext', 'mathbackground', 'mathcolor']],
+        ['merror', ['mathbackground', 'mathcolor']],
+        ['mfenced', ['close', 'open', 'separators']],
+        ['mfrac', ['linethickness', 'numalign', 'denomalign', 'bevelled']],
+        ['mi', ['mathvariant', 'mathsize', 'mathbackground', 'mathcolor']],
+        ['mmultiscripts', ['subscriptshift', 'superscriptshift']],
+        ['mn', ['mathvariant', 'mathsize', 'mathbackground', 'mathcolor']],
+        [
+          'mo',
+          [
+            'form',
+            'fence',
+            'separator',
+            'lspace',
+            'rspace',
+            'stretchy',
+            'symmetric',
+            'maxsize',
+            'minsize',
+            'largeop',
+            'movablelimits',
+            'accent',
+            'linebreak',
+            'mathvariant',
+            'mathsize',
+            'mathbackground',
+            'mathcolor'
+          ]
+        ],
+        ['mover', ['accent', 'align']],
+        ['mpadded', ['height', 'width', 'depth', 'lspace', 'voffset']],
+        ['mphantom', ['mathbackground']],
+        ['mprescripts', []],
+        ['mroot', ['mathbackground', 'mathcolor']],
+        ['mrow', ['dir', 'mathbackground', 'mathcolor']],
+        ['ms', ['lquote', 'rquote', 'mathvariant', 'mathsize', 'mathbackground', 'mathcolor']],
+        [
+          'mspace',
+          [
+            'linebreak',
+            'width',
+            'height',
+            'depth',
+            'mediummathspace',
+            'negativemediummathspace',
+            'negativethickmathspace',
+            'negativethinmathspace',
+            'negativeverythickmathspace',
+            'negativeverythinmathspace',
+            'thickmathspace',
+            'thinmathspace',
+            'verythickmathspace',
+            'verythinmathspace'
+          ]
+        ],
+        ['msqrt', ['mathbackground', 'mathcolor']],
+        [
+          'mstyle',
+          [
+            'scriptlevel',
+            'displaystyle',
+            'scriptsizemultiplier',
+            'scriptminsize',
+            'infixlinebreakstyle',
+            'decimalpoint',
+            'mathvariant',
+            'mathsize',
+            'mathbackground',
+            'mathcolor',
+            'dir'
+          ]
+        ],
+        ['msub', ['subscriptshift']],
+        ['msubsup', ['subscriptshift', 'superscriptshift']],
+        ['msup', ['superscriptshift']],
+        [
+          'mtable',
+          [
+            'align',
+            'rowalign',
+            'columnalign',
+            'groupalign',
+            'alignmentscope',
+            'columnwidth',
+            'width',
+            'rowspacing',
+            'columnspacing',
+            'rowlines',
+            'columnlines',
+            'frame',
+            'framespacing',
+            'equalrows',
+            'equalcolumns',
+            'displaystyle',
+            'side',
+            'minlabelspacing'
+          ]
+        ],
+        ['mtd', ['rowspan', 'columnspan', 'rowalign', 'columnalign', 'groupalign']],
+        ['mtext', ['mathvariant', 'mathsize', 'mathbackground', 'mathcolor']],
+        ['mtr', ['rowalign', 'columnalign', 'groupalign']],
+        ['munder', ['accentunder', 'align']],
+        ['munderover', ['accent', 'accentunder', 'align']],
+        ['semantics', ['definitionURL', 'encoding']]
+      ] satisfies [string, string[]][]
+    ).map(
+      ([tag, attributes]) =>
+        [tag, Object.freeze({ attributes: Object.freeze(new Set(attributes)) })] satisfies [
+          string,
+          Readonly<{ attributes: ReadonlySet<string> }>
+        ]
+    )
+  )
+);
+
+export default function useTransformHTMLContent(): (documentFragment: DocumentFragment) => DocumentFragment {
+  const [codeBlockTagName] = useCodeBlockTag();
+  const { transform } = useHTMLContentTransformContext();
+
+  const localize = useLocalizer();
+  const externalLinkAlt = localize('MARKDOWN_EXTERNAL_LINK_ALT');
+
+  return useCallback(
+    documentFragment =>
+      transform({
+        allowedTags: DEFAULT_ALLOWED_TAGS,
+        codeBlockTagName,
+        documentFragment,
+        externalLinkAlt
+      }),
+    [codeBlockTagName, externalLinkAlt, transform]
+  );
+}

package/src/providers/LiveRegionTwin/index.ts

@@ -0,0 +1,3 @@
+export { default as LiveRegionTwinComposer } from './private/LiveRegionTwinComposer';
+export { default as useLiveRegion } from './useLiveRegion';
+export { default as useQueueStaticElement } from './useQueueStaticElement';

package/src/providers/LiveRegionTwin/private/LiveRegionTwinComposer.ts

@@ -0,0 +1,27 @@
+import { createContext } from 'react';
+import createLiveRegionTwinComposer from './createLiveRegionTwinComposer';
+
+import type { StaticElement, StaticElementEntry } from './types';
+
+export type LiveRegionTwinContextType = {
+  markAllAsRendered: () => void;
+  queueStaticElement: (element: StaticElement) => void;
+  staticElementEntriesState: readonly [readonly StaticElementEntry[]];
+};
+
+export const LiveRegionTwinContext = createContext<LiveRegionTwinContextType>(
+  new Proxy(
+    {},
+    {
+      get(_target, key: string) {
+        throw new Error(
+          `botframework-webchat: LiveRegionTwinContext.${key} can only be used inside of <LiveRegionTwinComposer>.`
+        );
+      }
+    }
+  ) as unknown as LiveRegionTwinContextType
+);
+
+const LiveRegionTwinComposer = createLiveRegionTwinComposer(LiveRegionTwinContext);
+
+export default LiveRegionTwinComposer;

package/src/providers/LiveRegionTwin/private/LiveRegionTwinContainer.tsx

@@ -1,29 +1,35 @@
-import PropTypes from 'prop-types';
+import { validateProps } from '@msinternal/botframework-webchat-react-valibot';
 import React, { Fragment } from 'react';
-
-import type { VFC } from 'react';
+import { literal, object, optional, pipe, readonly, string, union, type InferInput } from 'valibot';
 
 import useMarkAllAsRenderedEffect from './useMarkAllAsRenderedEffect';
 import useStaticElementEntries from './useStaticElementEntries';
 
-type LiveRegionTwinContainerProps = {
-  'aria-label'?: string;
-  'aria-live': 'assertive' | 'polite';
-  'aria-roledescription'?: string;
-  className?: string;
-  role?: string;
-  textElementClassName?: string;
-};
+const liveRegionTwinContainerPropsSchema = pipe(
+  object({
+    'aria-label': optional(string()),
+    'aria-live': union([literal('assertive'), literal('polite')]),
+    'aria-roledescription': optional(string()),
+    className: optional(string()),
+    role: optional(string()),
+    textElementClassName: optional(string())
+  }),
+  readonly()
+);
+
+type LiveRegionTwinContainerProps = InferInput<typeof liveRegionTwinContainerPropsSchema>;
 
 // This container is marked as private because we assume there is only one instance under the <LiveRegionTwinContext>.
-const LiveRegionTwinContainer: VFC<LiveRegionTwinContainerProps> = ({
-  'aria-label': ariaLabel,
-  'aria-live': ariaLive,
-  'aria-roledescription': ariaRoleDescription,
-  className,
-  role,
-  textElementClassName
-}) => {
+function LiveRegionTwinContainer(props: LiveRegionTwinContainerProps) {
+  const {
+    'aria-label': ariaLabel,
+    'aria-live': ariaLive,
+    'aria-roledescription': ariaRoleDescription,
+    className,
+    role,
+    textElementClassName
+  } = validateProps(liveRegionTwinContainerPropsSchema, props);
+
   const [staticElementEntries] = useStaticElementEntries();
 
   // We assume there is only one instance under the <LiveRegionTwinContext>.
@@ -52,25 +58,7 @@ const LiveRegionTwinContainer: VFC<LiveRegionTwinContainerProps> = ({
       })}
     </div>
   );
-};
-
-LiveRegionTwinContainer.defaultProps = {
-  'aria-label': undefined,
-  'aria-roledescription': undefined,
-  className: undefined,
-  role: undefined,
-  textElementClassName: undefined
-};
-
-LiveRegionTwinContainer.propTypes = {
-  'aria-label': PropTypes.string,
-  // PropTypes.oneOf() returns type of `string`, but not `'assertive' | 'polite'`.
-  // @ts-ignore
-  'aria-live': PropTypes.oneOf(['assertive', 'polite']).isRequired,
-  'aria-roledescription': PropTypes.string,
-  className: PropTypes.string,
-  role: PropTypes.string,
-  textElementClassName: PropTypes.string
-};
+}
 
 export default LiveRegionTwinContainer;
+export { liveRegionTwinContainerPropsSchema, type LiveRegionTwinContainerProps };

package/src/providers/LiveRegionTwin/private/createLiveRegionTwinComposer.tsx

@@ -0,0 +1,155 @@
+import { hooks } from 'botframework-webchat-api';
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState, type Context, type ReactNode } from 'react';
+import { useRefFrom } from 'use-ref-from';
+
+import { type LiveRegionTwinContextType } from './LiveRegionTwinComposer';
+import LiveRegionTwinContainer from './LiveRegionTwinContainer';
+
+import type { StaticElement, StaticElementEntry } from './types';
+
+const { usePonyfill } = hooks;
+
+const DEFAULT_ARIA_LIVE = 'polite';
+const DEFAULT_FADE_AFTER = 1000;
+
+type LiveRegionTwinComposerProps = Readonly<{
+  /** Optional "aria-label" attribute for the live region twin container. */
+  'aria-label'?: string;
+
+  /** "aria-live" attribute for the live region twin container, defaults to `'polite'`. */
+  'aria-live'?: 'assertive' | 'polite';
+
+  /** Optional "aria-roledescription" attribute for the live region twin container. */
+  'aria-roledescription'?: string;
+
+  /** Optional "className" attribute for the live region twin container. */
+  className?: string;
+
+  /**
+   * Static elements will fade out after this timeout value specified in milliseconds, defaults to `1000`.
+   *
+   * When lowering this value, make sure screen reader can continue to pick up new static elements before fading out.
+   *
+   * If this prop is updated, it will be reflected in next queueing elements.
+   */
+  fadeAfter?: number;
+
+  /** Optional "role" attribute for the live region twin container. */
+  role?: string;
+
+  /** Optional "className" attribute for static text element. */
+  textElementClassName?: string;
+
+  children?: ReactNode | undefined;
+}>;
+
+/**
+ * Live region twin is an UI component for queueing texts or elements to the screen reader using
+ * a container element with `aria-live` attribute set.
+ *
+ * After the text is rendered and queued, it will be removed to reduce burden on the DOM tree.
+ * Currently, we assume the assistive technologies should pick up the text within 1 second of rendering.
+ * This value is configurable.
+ *
+ * By default, the live region is visible. If is is not desirable, the caller can use `className` prop to
+ * hide its visuals.
+ */
+const createLiveRegionTwinComposer = ({ Provider }: Context<LiveRegionTwinContextType>) => {
+  const LiveRegionTwinComposer = ({
+    'aria-label': ariaLabel,
+    'aria-live': ariaLive = DEFAULT_ARIA_LIVE,
+    'aria-roledescription': ariaRoleDescription,
+    children,
+    className,
+    fadeAfter = DEFAULT_FADE_AFTER,
+    role,
+    textElementClassName
+  }: LiveRegionTwinComposerProps) => {
+    const [{ clearTimeout, setTimeout }] = usePonyfill();
+    const [staticElementEntries, setStaticElementEntries] = useState<StaticElementEntry[]>([]);
+    const fadeAfterRef = useRefFrom(fadeAfter);
+    const markAllAsRenderedTimeoutIdRef = useRef<any>();
+    const nextKeyRef = useRef<number>(1);
+
+    const staticElementEntriesRef = useRefFrom(staticElementEntries);
+
+    // This function is called by an effect hook `useMarkAllAsRenderedEffect`, it must be designed with converging in mind.
+    // To prevent infinite render loop, after multiple calls to this function, it should eventually no-op.
+    const markAllAsRendered = useCallback<() => void>(() => {
+      if (!staticElementEntriesRef.current.length) {
+        // Nothing to remove.
+        return;
+      }
+
+      // When removing each element one-by-one based on an individual timeout, Narrator would narrate them twice occasionally.
+      // Possibly it think some elements that is not removed during the current cycle, are new elements and queued them twice.
+      // Thus, we are removing all at once to prevent bugs in Narrator.
+      markAllAsRenderedTimeoutIdRef.current && clearTimeout(markAllAsRenderedTimeoutIdRef.current);
+
+      markAllAsRenderedTimeoutIdRef.current = setTimeout(() => {
+        // We are playing safe by using value ref to check its length here.
+        // If we are certain that `setStaticElements(emptyArray => emptyArray)` is a no-op,
+        // we could replace it with just the setter function.
+        staticElementEntriesRef.current.length && setStaticElementEntries([]);
+      }, fadeAfterRef.current);
+    }, [
+      clearTimeout,
+      fadeAfterRef,
+      markAllAsRenderedTimeoutIdRef,
+      setStaticElementEntries,
+      setTimeout,
+      staticElementEntriesRef
+    ]);
+
+    // When this component is unmounting, make sure all future `setTimeout` are cleared and should not be fired.
+    useEffect(
+      () => () => markAllAsRenderedTimeoutIdRef.current && clearTimeout(markAllAsRenderedTimeoutIdRef.current),
+      [clearTimeout, markAllAsRenderedTimeoutIdRef]
+    );
+
+    const queueStaticElement = useCallback<(staticElement: StaticElement) => void>(
+      (element: StaticElement): void => {
+        const key = nextKeyRef.current;
+
+        nextKeyRef.current = nextKeyRef.current + 1;
+
+        setStaticElementEntries(entries => [...entries, { element, key }]);
+      },
+      [nextKeyRef, setStaticElementEntries]
+    );
+
+    const staticElementEntriesState = useMemo<readonly [readonly StaticElementEntry[]]>(
+      () => Object.freeze([Object.freeze(staticElementEntries)]) as readonly [readonly StaticElementEntry[]],
+      [staticElementEntries]
+    );
+
+    const context = useMemo(
+      () => ({
+        markAllAsRendered,
+        queueStaticElement,
+        staticElementEntriesState
+      }),
+      [markAllAsRendered, queueStaticElement, staticElementEntriesState]
+    );
+
+    return (
+      <Provider value={context}>
+        <LiveRegionTwinContainer
+          aria-label={ariaLabel}
+          aria-live={ariaLive}
+          aria-roledescription={ariaRoleDescription}
+          className={className}
+          role={role}
+          textElementClassName={textElementClassName}
+        />
+        {children}
+      </Provider>
+    );
+  };
+
+  LiveRegionTwinComposer.displayName = 'LiveRegionTwinComposer';
+
+  return memo(LiveRegionTwinComposer);
+};
+
+export default createLiveRegionTwinComposer;

package/src/providers/LiveRegionTwin/private/useContext.ts

@@ -1,15 +1,9 @@
 import { useContext } from 'react';
 
-import LiveRegionTwinContext from './Context';
+import { LiveRegionTwinContext, type LiveRegionTwinContextType } from './LiveRegionTwinComposer';
 
-import type { LiveRegionTwinContextType } from './Context';
-
-export default function useLiveRegionTwinContext(thrownOnUndefined = true): LiveRegionTwinContextType {
+export default function useLiveRegionTwinContext(): LiveRegionTwinContextType {
   const contextValue = useContext(LiveRegionTwinContext);
 
-  if (thrownOnUndefined && !contextValue) {
-    throw new Error('botframework-webchat internal: This hook can only be used under <LiveRegionComposer>.');
-  }
-
   return contextValue;
 }

package/src/providers/LiveRegionTwin/useLiveRegion.ts

@@ -0,0 +1,27 @@
+import { useMemo, type DependencyList, type ReactElement } from 'react';
+import { useRefFrom } from 'use-ref-from';
+
+import useQueueStaticElement from './useQueueStaticElement';
+
+/**
+ * Pushes a node to the live region.
+ *
+ * Once the node is pushed, it cannot be undoed.
+ *
+ * @param createNode Create node to be pushed to the live region.
+ * @param deps Will push a new node if the values in the list change.
+ */
+export default function useLiveRegion(
+  createNode: () => false | null | ReactElement | string | undefined,
+  deps: DependencyList
+) {
+  const createNodeRef = useRefFrom(createNode);
+  const queueStaticElement = useQueueStaticElement();
+
+  useMemo(() => {
+    const node = createNodeRef?.current();
+
+    node && queueStaticElement(node);
+    // eslint-disable-next-line react-hooks/exhaustive-deps, react-hooks/use-memo
+  }, [...deps, createNodeRef, queueStaticElement]);
+}

package/src/providers/LiveRegionTwin/useQueueStaticElement.ts

@@ -1,4 +1,4 @@
-import useLiveRegionContext from './private/useContext';
+import useLiveRegionTwinContext from './private/useContext';
 
 import type { StaticElement } from './private/types';
 
@@ -8,5 +8,5 @@ import type { StaticElement } from './private/types';
  * After the element is queued, screen reader will eventually narrate it and it cannot be changed.
  */
 export default function useQueueStaticElement(): (element: StaticElement) => void {
-  return useLiveRegionContext().queueStaticElement;
+  return useLiveRegionTwinContext().queueStaticElement;
 }

package/src/providers/ModalDialog/private/Popover.tsx

@@ -1,7 +1,8 @@
 import { hooks } from 'botframework-webchat-api';
 import classNames from 'classnames';
-import React, { memo, type PropsWithChildren, useCallback, useEffect, useRef } from 'react';
+import React, { memo, type PropsWithChildren, useCallback, useLayoutEffect, useRef } from 'react';
 
+import { ComponentIcon } from '../../../Icon';
 import useStyleSet from '../../../hooks/useStyleSet';
 
 const { useLocalizer } = hooks;
@@ -21,11 +22,11 @@ const ModalDialog = memo(
     const dialogRef = useRef<HTMLDialogElement>(null);
     const localize = useLocalizer();
 
-    const closeButtonAlt = localize('KEYBOARD_HELP_CLOSE_BUTTON_ALT');
+    const closeButtonAlt = localize('CLOSE_BUTTON_ALT');
 
     const handleCloseButtonClick = useCallback(() => dialogRef.current?.close(), [dialogRef]);
 
-    useEffect(() => dialogRef.current?.showModal(), [dialogRef]);
+    useLayoutEffect(() => dialogRef.current?.showModal(), [dialogRef]);
 
     return (
       <dialog
@@ -49,18 +50,7 @@ const ModalDialog = memo(
               onClick={handleCloseButtonClick}
               type="button"
             >
-              <div className="webchat__modal-dialog__close-button-border">
-                <svg
-                  className="webchat__modal-dialog__close-button-image"
-                  // "focusable" attribute is only available in IE11 and "tabIndex={-1}" does not work.
-                  focusable={false}
-                  role="presentation"
-                  viewBox="0 0 2048 2048"
-                  xmlns="http://www.w3.org/2000/svg"
-                >
-                  <path d="M2048 136l-888 888 888 888-136 136-888-888-888 888L0 1912l888-888L0 136 136 0l888 888L1912 0l136 136z" />
-                </svg>
-              </div>
+              <ComponentIcon appearance="text" className="webchat__modal-dialog__close-button-icon" icon="dismiss" />
             </button>
           </div>
           <div className="webchat__modal-dialog__body">{children}</div>

package/src/providers/ReducedMotion/ReducedMotionComposer.tsx

@@ -0,0 +1,35 @@
+import React, { memo, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+import { type ContextOf } from '../../types/ContextOf';
+import Context from './private/Context';
+
+type ContextType = ContextOf<typeof Context>;
+
+type ReducedMotionComposerProps = Readonly<{
+  children?: ReactNode | undefined;
+}>;
+
+const ReducedMotionComposer = memo(({ children }: ReducedMotionComposerProps) => {
+  const shouldReduceMotionQueryList = useMemo(() => matchMedia?.('(prefers-reduced-motion: reduce)'), []);
+  const [shouldReduceMotion, setShouldReduceMotion] = useState<boolean>(
+    () => shouldReduceMotionQueryList?.matches ?? false
+  );
+
+  const shouldReduceMotionState = useMemo(() => Object.freeze([shouldReduceMotion] as const), [shouldReduceMotion]);
+
+  const context = useMemo<ContextType>(() => Object.freeze({ shouldReduceMotionState }), [shouldReduceMotionState]);
+
+  useEffect(() => {
+    const handleChange = ({ matches }: MediaQueryListEvent) => setShouldReduceMotion(matches);
+
+    shouldReduceMotionQueryList.addEventListener('change', handleChange);
+
+    return () => shouldReduceMotionQueryList.removeEventListener('change', handleChange);
+  }, [setShouldReduceMotion, shouldReduceMotionQueryList]);
+
+  return <Context.Provider value={context}>{children}</Context.Provider>;
+});
+
+ReducedMotionComposer.displayName = 'ReducedMotionComposer';
+
+export default ReducedMotionComposer;

package/src/providers/ReducedMotion/private/Context.ts

@@ -0,0 +1,22 @@
+import { createContext } from 'react';
+
+type ContextType = Readonly<{
+  shouldReduceMotionState: readonly [boolean];
+}>;
+
+type ContextAsGetter<T extends Record<string, unknown>> =
+  T extends Record<infer K, infer V> ? Record<K, { get(): V }> : never;
+
+const defaultContextValue: ContextAsGetter<ContextType> = {
+  shouldReduceMotionState: {
+    get() {
+      throw new Error('shouldReduceMotionState cannot be used outside of <ReducedMotionComposer>.');
+    }
+  }
+};
+
+const Context = createContext<ContextType>(Object.create({}, defaultContextValue));
+
+Context.displayName = 'ReducedMotionComposer';
+
+export default Context;

package/src/providers/ReducedMotion/private/useContext.ts

@@ -0,0 +1,8 @@
+import { useContext as useReactContext } from 'react';
+
+import { type ContextOf } from '../../../types/ContextOf';
+import Context from './Context';
+
+export default function useContext(): ContextOf<typeof Context> {
+  return useReactContext(Context);
+}

package/src/providers/ReducedMotion/useShouldReduceMotion.ts

@@ -0,0 +1,5 @@
+import useContext from './private/useContext';
+
+export default function useShouldReduceMotion(): ReturnType<typeof useContext>['shouldReduceMotionState'] {
+  return useContext().shouldReduceMotionState;
+}