botframework-webchat-component 4.14.1 → 4.15.2-main.20220413.af6e8a3

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

@@ -0,0 +1,12 @@
+import { createContext } from 'react';
+
+import type { ActivityWithRenderer, ReadonlyActivityTree } from './types';
+
+type ActivityTreeContextType = {
+  activityTreeWithRendererState: readonly [ReadonlyActivityTree];
+  flattenedActivityTreeWithRendererState: readonly [readonly ActivityWithRenderer[]];
+};
+
+export default createContext<ActivityTreeContextType>(undefined);
+
+export type { ActivityTreeContextType };

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

@@ -0,0 +1,12 @@
+import type { ActivityComponentFactory } from 'botframework-webchat-api';
+import type { WebChatActivity } from 'botframework-webchat-core';
+
+type ActivityWithRenderer = {
+  activity: WebChatActivity;
+  renderActivity: Exclude<ReturnType<ActivityComponentFactory>, false>;
+};
+
+type ActivityTree = ActivityWithRenderer[][][];
+type ReadonlyActivityTree = readonly (readonly (readonly ActivityWithRenderer[])[])[];
+
+export type { ActivityTree, ActivityWithRenderer, ReadonlyActivityTree };

package/src/providers/ActivityTree/private/useActivitiesWithRenderer.ts

@@ -0,0 +1,64 @@
+import { useCallback, useRef } from 'react';
+import type { WebChatActivity } from 'botframework-webchat-core';
+
+import useMemoize from '../../../hooks/internal/useMemoize';
+import type { ActivityWithRenderer } from './types';
+
+export default function useActivitiesWithRenderer(
+  activities: readonly WebChatActivity[],
+  createActivityRenderer
+): readonly ActivityWithRenderer[] {
+  const createActivityRendererWithLiteralArgs = useCallback(
+    (activity: WebChatActivity, nextVisibleActivity: WebChatActivity) =>
+      createActivityRenderer({ activity, nextVisibleActivity }),
+    [createActivityRenderer]
+  );
+
+  // Create a memoized context of the createActivityRenderer function.
+  // TODO: [P2] Rename useMemoize to useMemoAll
+  const entries = useMemoize(
+    createActivityRendererWithLiteralArgs,
+    createActivityRendererWithLiteralArgsMemoized => {
+      // All calls to createActivityRendererWithLiteralArgsMemoized() in this function will be memoized (LRU = 1).
+      // In the next render cycle, calls to createActivityRendererWithLiteralArgsMemoized() might return the memoized result instead.
+      // This is an improvement to React useMemo(), because it only allows 1 memoization.
+      // useMemoize() allows any number of memoization.
+
+      const activitiesWithRenderer: ActivityWithRenderer[] = [];
+      let nextVisibleActivity: WebChatActivity;
+
+      for (let index = activities.length - 1; index >= 0; index--) {
+        const activity = activities[+index];
+        const renderActivity = createActivityRendererWithLiteralArgsMemoized(activity, nextVisibleActivity);
+
+        if (renderActivity) {
+          activitiesWithRenderer.splice(0, 0, {
+            activity,
+            renderActivity
+          });
+
+          nextVisibleActivity = activity;
+        }
+      }
+
+      return Object.freeze(activitiesWithRenderer);
+    },
+    [activities]
+  );
+
+  const prevEntriesRef = useRef<readonly ActivityWithRenderer[]>([]);
+  const { current: prevEntries } = prevEntriesRef;
+
+  if (
+    prevEntries.length !== entries.length ||
+    prevEntries.some((prevEntry, index) => {
+      const entry = entries[+index];
+
+      return entry.activity !== prevEntry.activity || entry.renderActivity !== prevEntry.renderActivity;
+    })
+  ) {
+    prevEntriesRef.current = entries;
+  }
+
+  return prevEntriesRef.current;
+}

package/src/providers/ActivityTree/private/useActivityTreeWithRenderer.ts

@@ -0,0 +1,135 @@
+import { hooks } from 'botframework-webchat-api';
+import { useMemo } from 'react';
+import type { WebChatActivity } from 'botframework-webchat-core';
+
+import intersectionOf from '../../../Utils/intersectionOf';
+import removeInline from '../../../Utils/removeInline';
+import type { ActivityWithRenderer, ReadonlyActivityTree } from './types';
+
+const { useGroupActivities } = hooks;
+
+function validateAllEntriesTagged<T>(entries: readonly T[], bins: readonly (readonly T[])[]): boolean {
+  return entries.every(entry => bins.some(bin => bin.includes(entry)));
+}
+
+// Activity tree is a multidimensional array, while activities is a 1D array.
+// - The first dimension of the array contains activities with same sender;
+// - The second dimension of the array contains activities with same status.
+
+// [
+//   [
+//     // Both messages are from bot and is sent as a batch, we will group them as an array.
+//     'Bot: Hello!'
+//     'Bot: What can I help today?'
+//   ],
+//   [
+//     'User: What is the weather?'
+//   ],
+//   [
+//     'Bot: Let me look it up... hold on.'
+//   ],
+//   [
+//     // This message is in a different group because it is more than a few seconds apart from the previous message.
+//     'Bot: Here is the weather forecast.'
+//   ]
+// ]
+
+function useActivityTreeWithRenderer(entries: readonly ActivityWithRenderer[]): ReadonlyActivityTree {
+  const groupActivities = useGroupActivities();
+
+  // We bin activities in 2 different ways:
+  // - `activitiesBySender` is a 2D array containing activities with same sender
+  // - `activitiesByStatus` is a 2D array containing activities with same status
+  // Both arrays should contains all activities.
+
+  const { entriesBySender, entriesByStatus } = useMemo<{
+    entriesBySender: readonly (readonly ActivityWithRenderer[])[];
+    entriesByStatus: readonly (readonly ActivityWithRenderer[])[];
+  }>(() => {
+    const visibleActivities = entries.map(({ activity }) => activity);
+
+    const {
+      sender: activitiesBySender,
+      status: activitiesByStatus
+    }: {
+      sender: readonly (readonly WebChatActivity[])[];
+      status: readonly (readonly WebChatActivity[])[];
+    } = groupActivities({
+      activities: visibleActivities
+    });
+
+    const [entriesBySender, entriesByStatus] = [activitiesBySender, activitiesByStatus].map(bins =>
+      bins.map(bin => bin.map(activity => entries.find(entry => entry.activity === activity)))
+    );
+
+    if (!validateAllEntriesTagged(visibleActivities, activitiesBySender)) {
+      console.warn(
+        'botframework-webchat: Not every activities are grouped in the "sender" property. Please fix "groupActivitiesMiddleware" and group every activities.'
+      );
+    }
+
+    if (!validateAllEntriesTagged(visibleActivities, activitiesByStatus)) {
+      console.warn(
+        'botframework-webchat: Not every activities are grouped in the "status" property. Please fix "groupActivitiesMiddleware" and group every activities.'
+      );
+    }
+
+    return {
+      entriesBySender,
+      entriesByStatus
+    };
+  }, [entries, groupActivities]);
+
+  // Create a tree of activities with 2 dimensions: sender, followed by status.
+
+  const activityTree: ReadonlyActivityTree = useMemo(() => {
+    const entriesPendingGrouping = [...entries];
+    const activityTree: (readonly (readonly ActivityWithRenderer[])[])[] = [];
+
+    while (entriesPendingGrouping.length) {
+      const entriesWithSameSender = entriesBySender.find(bin => bin.includes(entriesPendingGrouping[0]));
+      const senderTree: (readonly ActivityWithRenderer[])[] = [];
+
+      entriesWithSameSender.forEach(entry => {
+        const entriesWithSameStatus = entriesByStatus.find(bin => bin.includes(entry));
+
+        const entriesWithSameSenderAndStatus = intersectionOf<ActivityWithRenderer>(
+          entriesPendingGrouping,
+          entriesWithSameSender,
+          entriesWithSameStatus
+        );
+
+        if (entriesWithSameSenderAndStatus.length) {
+          senderTree.push(Object.freeze(entriesWithSameSenderAndStatus));
+          removeInline(entriesPendingGrouping, ...entriesWithSameSenderAndStatus);
+        }
+      });
+
+      activityTree.push(Object.freeze(senderTree));
+    }
+
+    // Assertion: All entries must be assigned to the activityTree.
+    if (
+      !entries.every(activity =>
+        activityTree.some(activitiesWithSameSender =>
+          activitiesWithSameSender.some(activitiesWithSameSenderAndStatus =>
+            activitiesWithSameSenderAndStatus.includes(activity)
+          )
+        )
+      )
+    ) {
+      console.warn('botframework-webchat internal: Not all visible activities are grouped in the activityTree.', {
+        entries,
+        activityTree
+      });
+    }
+
+    return Object.freeze(activityTree);
+  }, [entriesBySender, entriesByStatus, entries]);
+
+  return activityTree;
+}
+
+export type { ActivityWithRenderer };
+
+export default useActivityTreeWithRenderer;

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

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

package/src/providers/ActivityTree/useActivityTreeWithRenderer.ts

@@ -0,0 +1,16 @@
+import useActivityTreeContext from './private/useContext';
+
+import type { ActivityWithRenderer, ReadonlyActivityTree } from './private/types';
+
+export default function useActivityTreeWithRenderer(options?: { flat?: false }): readonly [ReadonlyActivityTree];
+export default function useActivityTreeWithRenderer(options: {
+  flat: true;
+}): readonly [readonly ActivityWithRenderer[]];
+
+export default function useActivityTreeWithRenderer(options: { flat?: boolean } = {}) {
+  const context = useActivityTreeContext();
+
+  return options?.flat === true
+    ? context.flattenedActivityTreeWithRendererState
+    : context.activityTreeWithRendererState;
+}

package/src/providers/LiveRegionTwin/LiveRegionTwinComposer.tsx

@@ -0,0 +1,161 @@
+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;
+
+  /** Optional "className" attribute for static text element. */
+  textElementClassName?: 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,
+  textElementClassName
+}) => {
+  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}
+        textElementClassName={textElementClassName}
+      />
+      {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,
+  textElementClassName: 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,
+  textElementClassName: 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,80 @@
+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;
+  textElementClassName?: 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,
+  textElementClassName
+}) => {
+  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 }) => {
+        if (typeof element === 'string') {
+          const id = `webchat__live-region-twin__text-element-${key}`;
+
+          return (
+            <div aria-atomic={true} aria-labelledby={id} className={textElementClassName} key={key}>
+              {/* "aria-labelledby" requires the use of "id" attribute. */}
+              {/* eslint-disable-next-line react/forbid-dom-props */}
+              <p id={id}>{element}</p>
+            </div>
+          );
+        }
+
+        return <Fragment key={key}>{element}</Fragment>;
+      })}
+    </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;

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;
+}