botframework-webchat-component 4.13.0 → 4.15.0

package/src/providers/LiveRegionTwin/LiveRegionTwinComposer.tsx

@@ -0,0 +1,154 @@
+import PropTypes from 'prop-types';
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type { FC, PropsWithChildren } from 'react';
+
+import LiveRegionTwinContainer from './private/LiveRegionTwinContainer';
+import LiveRegionTwinContext from './private/Context';
+import useValueRef from '../../hooks/internal/useValueRef';
+
+import type { StaticElement, StaticElementEntry } from './private/types';
+
+const DEFAULT_ARIA_LIVE = 'polite';
+const DEFAULT_FADE_AFTER = 1000;
+
+type LiveRegionTwinComposerProps = PropsWithChildren<{
+  /** 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;
+}>;
+
+/**
+ * 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 LiveRegionTwinComposer: FC<LiveRegionTwinComposerProps> = ({
+  'aria-label': ariaLabel,
+  'aria-live': ariaLive = DEFAULT_ARIA_LIVE,
+  'aria-roledescription': ariaRoleDescription,
+  children,
+  className,
+  fadeAfter = DEFAULT_FADE_AFTER,
+  role
+}) => {
+  const [staticElementEntries, setStaticElementEntries] = useState<StaticElementEntry[]>([]);
+  const fadeAfterRef = useValueRef(fadeAfter);
+  const markAllAsRenderedTimeoutIdRef = useRef<any>();
+  const nextKeyRef = useRef<number>(1);
+
+  const staticElementEntriesRef = useValueRef(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);
+  }, [fadeAfterRef, markAllAsRenderedTimeoutIdRef, setStaticElementEntries, staticElementEntriesRef]);
+
+  // When this component is unmounting, make sure all future `setTimeout` are cleared and should not be fired.
+  useEffect(
+    () => () => markAllAsRenderedTimeoutIdRef.current && clearTimeout(markAllAsRenderedTimeoutIdRef.current),
+    [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 (
+    <LiveRegionTwinContext.Provider value={context}>
+      <LiveRegionTwinContainer
+        aria-label={ariaLabel}
+        aria-live={ariaLive}
+        aria-roledescription={ariaRoleDescription}
+        className={className}
+        role={role}
+      />
+      {children}
+    </LiveRegionTwinContext.Provider>
+  );
+};
+
+LiveRegionTwinComposer.defaultProps = {
+  'aria-label': undefined,
+  'aria-live': DEFAULT_ARIA_LIVE,
+  'aria-roledescription': undefined,
+  children: undefined,
+  className: undefined,
+  fadeAfter: DEFAULT_FADE_AFTER,
+  role: undefined
+};
+
+LiveRegionTwinComposer.propTypes = {
+  'aria-label': PropTypes.string,
+  'aria-live': PropTypes.oneOf(['assertive', 'polite']),
+  'aria-roledescription': PropTypes.string,
+  children: PropTypes.any,
+  className: PropTypes.string,
+  fadeAfter: PropTypes.number,
+  role: PropTypes.string
+};
+
+export default LiveRegionTwinComposer;

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

@@ -0,0 +1,15 @@
+import { createContext } from 'react';
+
+import type { StaticElement, StaticElementEntry } from './types';
+
+type LiveRegionTwinContextType = {
+  markAllAsRendered: () => void;
+  queueStaticElement: (element: StaticElement) => void;
+  staticElementEntriesState: readonly [readonly StaticElementEntry[]];
+};
+
+const LiveRegionTwinContext = createContext<LiveRegionTwinContextType>(undefined);
+
+export default LiveRegionTwinContext;
+
+export type { LiveRegionTwinContextType };

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

@@ -0,0 +1,64 @@
+import PropTypes from 'prop-types';
+import React, { Fragment } from 'react';
+
+import type { VFC } from 'react';
+
+import useMarkAllAsRenderedEffect from './useMarkAllAsRenderedEffect';
+import useStaticElementEntries from './useStaticElementEntries';
+
+type LiveRegionTwinContainerProps = {
+  'aria-label'?: string;
+  'aria-live': 'assertive' | 'polite';
+  'aria-roledescription'?: string;
+  className?: string;
+  role?: string;
+};
+
+// 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
+}) => {
+  const [staticElementEntries] = useStaticElementEntries();
+
+  // We assume there is only one instance under the <LiveRegionTwinContext>.
+  // The assumption made us safe to mark everything is rendered.
+  // In contrary, if we have 0-to-many at different time, we may falsely mark something as rendered.
+  useMarkAllAsRenderedEffect();
+
+  return (
+    <div
+      aria-label={ariaLabel}
+      aria-live={ariaLive}
+      aria-roledescription={ariaRoleDescription}
+      className={className}
+      role={role}
+    >
+      {staticElementEntries.map(({ element, key }) =>
+        typeof element === 'string' ? <div key={key}>{element}</div> : <Fragment key={key}>{element}</Fragment>
+      )}
+    </div>
+  );
+};
+
+LiveRegionTwinContainer.defaultProps = {
+  'aria-label': undefined,
+  'aria-roledescription': undefined,
+  className: undefined,
+  role: 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
+};
+
+export default LiveRegionTwinContainer;

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

@@ -0,0 +1,10 @@
+import type { ReactElement } from 'react';
+
+type StaticElement = Exclude<ReactElement | string, undefined>;
+
+type StaticElementEntry = {
+  element: StaticElement;
+  key: number;
+};
+
+export type { StaticElement, StaticElementEntry };

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

@@ -0,0 +1,15 @@
+import { useContext } from 'react';
+
+import LiveRegionTwinContext from './Context';
+
+import type { LiveRegionTwinContextType } from './Context';
+
+export default function useLiveRegionTwinContext(thrownOnUndefined = true): 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/private/useMarkAllAsRenderedEffect.ts

@@ -0,0 +1,13 @@
+import { useEffect } from 'react';
+
+import useLiveRegionTwinContext from './useContext';
+
+// After calling `markAllAsRendered`, it will cause a re-render.
+// Since `markAllAsRendered` is a converging function, it will eventually stop re-rendering.
+// We call this hook `useXXXEffect` for us to abstract the business logic here.
+export default function useMarkAllAsRenderedEffect(): void {
+  const { markAllAsRendered } = useLiveRegionTwinContext();
+
+  // We did not set the `deps` argument as we want to run this function on every render.
+  useEffect(markAllAsRendered);
+}

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

@@ -0,0 +1,7 @@
+import useLiveRegionTwinContext from './useContext';
+
+import type { StaticElementEntry } from './types';
+
+export default function useStaticElementEntries(): readonly [readonly StaticElementEntry[]] {
+  return useLiveRegionTwinContext().staticElementEntriesState;
+}

package/src/providers/LiveRegionTwin/useQueueStaticElement.ts

@@ -0,0 +1,12 @@
+import useLiveRegionContext from './private/useContext';
+
+import type { StaticElement } from './private/types';
+
+/**
+ * Queues a static element to the live region.
+ *
+ * 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;
+}

package/src/providers/TranscriptFocus/TranscriptFocusComposer.tsx

@@ -0,0 +1,180 @@
+import { hooks } from 'botframework-webchat-api';
+import PropTypes from 'prop-types';
+import random from 'math-random';
+import React, { useCallback, useMemo } from 'react';
+
+import type { FC, MutableRefObject } from 'react';
+
+import scrollIntoViewWithBlockNearest from '../../Utils/scrollIntoViewWithBlockNearest';
+import TranscriptFocusContext from './private/Context';
+import useActivityTreeWithRenderer from '../ActivityTree/useActivityTreeWithRenderer';
+import usePrevious from '../../hooks/internal/usePrevious';
+import useStateRef from '../../hooks/internal/useStateRef';
+import useValueRef from '../../hooks/internal/useValueRef';
+
+import type { TranscriptFocusContextType } from './private/Context';
+
+const { useGetKeyByActivity } = hooks;
+
+type TranscriptFocusComposerProps = {
+  containerRef: MutableRefObject<HTMLElement>;
+};
+
+function last<T>(array: ArrayLike<T>) {
+  return array[array.length - 1];
+}
+
+function uniqueId(count = Infinity) {
+  return (
+    random()
+      // eslint-disable-next-line no-magic-numbers
+      .toString(36)
+      // eslint-disable-next-line no-magic-numbers
+      .substring(2, 2 + count)
+  );
+}
+
+const TranscriptFocusComposer: FC<TranscriptFocusComposerProps> = ({ children, containerRef }) => {
+  const [flattenedActivityTree] = useActivityTreeWithRenderer({ flat: true });
+  const [_, setRawFocusedActivityKey, rawFocusedActivityKeyRef] = useStateRef<string | undefined>();
+  const getKeyByActivity = useGetKeyByActivity();
+
+  // As we need to use IDREF for `aria-activedescendant`,
+  // this prefix will differentiate multiple instances of transcript on the same page.
+  // eslint-disable-next-line no-magic-numbers
+  const prefix = useMemo<string>(() => uniqueId(3), []);
+
+  const getDescendantIdByActivityKey: (activityKey?: string) => string | undefined = useCallback(
+    (activityKey?: string) => activityKey && `webchat__transcript-focus-${prefix}__activity-${activityKey}`,
+    [prefix]
+  );
+
+  const renderingActivityKeys = useMemo<readonly string[]>(
+    () => Object.freeze(flattenedActivityTree.map(({ activity }) => getKeyByActivity(activity))),
+    [flattenedActivityTree, getKeyByActivity]
+  );
+
+  const renderingActivityKeysRef = useValueRef<readonly string[]>(renderingActivityKeys);
+
+  // While the transcript or any descendants are not focused, if the transcript is updated, reset the user-selected active descendant.
+  // This will assume the last activity, if any, will be the active descendant.
+  const prevRenderingActivityKeys = usePrevious(renderingActivityKeys);
+
+  if (renderingActivityKeys !== prevRenderingActivityKeys && !containerRef.current?.contains(document.activeElement)) {
+    rawFocusedActivityKeyRef.current = undefined;
+  }
+
+  const { current: rawFocusedActivityKey } = rawFocusedActivityKeyRef;
+
+  const focusedActivityKey = useMemo<string>(
+    () => (renderingActivityKeys.includes(rawFocusedActivityKey) ? rawFocusedActivityKey : last(renderingActivityKeys)),
+    [renderingActivityKeys, rawFocusedActivityKey]
+  );
+
+  const focusedActivityKeyRef = useValueRef(focusedActivityKey);
+
+  const activeDescendantId = useMemo<string>(
+    () => getDescendantIdByActivityKey(focusedActivityKey),
+    [getDescendantIdByActivityKey, focusedActivityKey]
+  );
+
+  const focusByActivityKey = useCallback<
+    (activityKey: boolean | string | undefined, withFocus: boolean | undefined) => void
+  >(
+    (activityKey: boolean | string | undefined, withFocus: boolean | undefined = true) => {
+      if (activityKey === false) {
+        // `false` means set it to nothing.
+        setRawFocusedActivityKey(undefined);
+      } else if (activityKey === true) {
+        // `true` means set to something if it is not set.
+        setRawFocusedActivityKey(key => key || focusedActivityKeyRef.current);
+      } else if (activityKey) {
+        setRawFocusedActivityKey(activityKey);
+      }
+
+      if (withFocus) {
+        containerRef.current?.focus();
+
+        const activeDescendantId = getDescendantIdByActivityKey(
+          activityKey === false
+            ? // If "activityKey" is false, it means "focus nothing and reset it to the last activity".
+              last(renderingActivityKeysRef.current)
+            : activityKey && activityKey !== true
+            ? // If "activity" is not "undefined" and not "true", it means "focus on this activity".
+              activityKey
+            : // If "activityKey" is "undefined", it means "don't modify the focus".
+              // If "activityKey" is "true", it means "try to focus on anything".
+              rawFocusedActivityKeyRef.current
+        );
+
+        const activeDescendantElement = activeDescendantId && document.getElementById(activeDescendantId);
+
+        // Don't scroll active descendant into view if the focus is already inside it.
+        // Otherwise, given the focus is on the send box, clicking on any <input> inside the Adaptive Cards may cause the view to move.
+        // This UX is not desirable because click should not cause scroll.
+        if (activeDescendantElement && !activeDescendantElement.contains(document.activeElement)) {
+          scrollIntoViewWithBlockNearest(activeDescendantElement);
+        }
+      }
+    },
+    [
+      getDescendantIdByActivityKey,
+      containerRef,
+      focusedActivityKeyRef,
+      renderingActivityKeysRef,
+      rawFocusedActivityKeyRef,
+      setRawFocusedActivityKey
+    ]
+  );
+
+  const focusRelativeActivity = useCallback(
+    (delta: number) => {
+      const { current: orderedActivityKeys } = renderingActivityKeysRef;
+
+      if (isNaN(delta) || !orderedActivityKeys.length) {
+        return focusByActivityKey(false, true);
+      }
+
+      const { current: focusedActivityKey } = focusedActivityKeyRef;
+
+      const index = orderedActivityKeys.indexOf(focusedActivityKey);
+      const nextIndex = ~index
+        ? Math.max(0, Math.min(orderedActivityKeys.length - 1, index + delta))
+        : orderedActivityKeys.length - 1;
+
+      focusByActivityKey(orderedActivityKeys[+nextIndex], true);
+    },
+    [focusedActivityKeyRef, renderingActivityKeysRef, focusByActivityKey]
+  );
+
+  const contextValue = useMemo<TranscriptFocusContextType>(
+    () => ({
+      activeDescendantIdState: Object.freeze([activeDescendantId]) as readonly [string],
+      getDescendantIdByActivityKey,
+      focusByActivityKey,
+      focusedActivityKeyState: Object.freeze([focusedActivityKey]) as readonly [string],
+      focusedExplicitlyState: Object.freeze([!!rawFocusedActivityKey]) as readonly [boolean],
+      focusRelativeActivity
+    }),
+    [
+      activeDescendantId,
+      getDescendantIdByActivityKey,
+      focusByActivityKey,
+      focusedActivityKey,
+      focusRelativeActivity,
+      rawFocusedActivityKey
+    ]
+  );
+
+  return <TranscriptFocusContext.Provider value={contextValue}>{children}</TranscriptFocusContext.Provider>;
+};
+
+TranscriptFocusComposer.propTypes = {
+  // PropTypes is not fully compatible with TypeScript.
+  // @ts-ignore
+  containerRef: PropTypes.shape({
+    current: PropTypes.instanceOf(HTMLElement)
+  }).isRequired
+};
+
+export default TranscriptFocusComposer;

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

@@ -0,0 +1,16 @@
+import { createContext } from 'react';
+
+type TranscriptFocusContextType = {
+  activeDescendantIdState: readonly [string];
+  focusByActivityKey: (activityKey: boolean | string | undefined, withFocus: boolean | undefined) => void;
+  focusedActivityKeyState: readonly [string];
+  focusedExplicitlyState: readonly [boolean];
+  focusRelativeActivity: (delta: number) => void;
+  getDescendantIdByActivityKey: (activityKey?: string) => string | undefined;
+};
+
+const TranscriptFocusContext = createContext<TranscriptFocusContextType>(undefined);
+
+export default TranscriptFocusContext;
+
+export type { TranscriptFocusContextType };

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

@@ -0,0 +1,13 @@
+import { useContext } from 'react';
+
+import TranscriptFocusContext from './Context';
+
+export default function useTranscriptFocusContext(throwOnUndefined = true) {
+  const contextValue = useContext(TranscriptFocusContext);
+
+  if (throwOnUndefined && !contextValue) {
+    throw new Error('botframework-webchat internal: This hook can only be used under <TranscriptFocusComposer>.');
+  }
+
+  return contextValue;
+}

package/src/providers/TranscriptFocus/useActiveDescendantId.ts

@@ -0,0 +1,5 @@
+import useTranscriptFocusContext from './private/useContext';
+
+export default function useActiveDescendantId(): readonly [string] {
+  return useTranscriptFocusContext().activeDescendantIdState;
+}

package/src/providers/TranscriptFocus/useFocusByActivityKey.ts

@@ -0,0 +1,14 @@
+import useTranscriptFocusContext from './private/useContext';
+
+/**
+ * Put the focus on an activity based on its activity key.
+ *
+ * @param {boolean | string | undefined} activityKey - The activity key to focus on, `false` to reset focus to most recent activity, `true` to focus on anything, `undefined` for not changing the focus.
+ * @param {boolean} withFocus - `true` if the user agent focus should be sent to the transcript, otherwise, `false`.
+ */
+export default function useFocusByActivityKey(): (
+  activityKey: boolean | string | undefined,
+  withFocus?: boolean
+) => void {
+  return useTranscriptFocusContext().focusByActivityKey;
+}

package/src/providers/TranscriptFocus/useFocusRelativeActivity.ts

@@ -0,0 +1,5 @@
+import useTranscriptFocusContext from './private/useContext';
+
+export default function useFocusByActivityKey(): (delta: number) => void {
+  return useTranscriptFocusContext().focusRelativeActivity;
+}

package/src/providers/TranscriptFocus/useFocusedActivityKey.ts

@@ -0,0 +1,5 @@
+import useTranscriptFocusContext from './private/useContext';
+
+export default function useFocusedActivityKey(): readonly [string] {
+  return useTranscriptFocusContext().focusedActivityKeyState;
+}

package/src/providers/TranscriptFocus/useFocusedExplicitly.ts

@@ -0,0 +1,5 @@
+import useTranscriptFocusContext from './private/useContext';
+
+export default function useFocusedExplicitly(): readonly [boolean] {
+  return useTranscriptFocusContext().focusedExplicitlyState;
+}

package/src/providers/TranscriptFocus/useGetDescendantIdByActivityKey.ts

@@ -0,0 +1,5 @@
+import useTranscriptFocusContext from './private/useContext';
+
+export default function useGetDescendantIdByActivityKey(): (activityKey?: string) => string | undefined {
+  return useTranscriptFocusContext().getDescendantIdByActivityKey;
+}

package/src/tsconfig.json

@@ -11,5 +11,5 @@
     "skipLibCheck": true,
     "sourceMap": true
   },
-  "files": ["index.tsx"]
+  "files": ["index.ts"]
 }

package/src/types/ScrollPosition.ts

@@ -0,0 +1,6 @@
+type ScrollPosition = {
+  activityID?: string;
+  scrollTop: number;
+};
+
+export default ScrollPosition;

package/.eslintignore

@@ -1,9 +0,0 @@
-/src/__tests__/**/*
-/src/**/*.spec.js
-/src/**/*.spec.jsx
-/src/**/*.spec.ts
-/src/**/*.spec.tsx
-/src/**/*.test.js
-/src/**/*.test.jsx
-/src/**/*.test.ts
-/src/**/*.test.tsx