@elliemae/ds-chat-container 3.80.0-next.31 → 3.80.0-next.35

package/dist/types/parts/chat-container-messages-list/useChatContainerMessageList.d.ts

@@ -1,13 +1,18 @@
 import React from 'react';
 import { useGetGlobalAttributes } from '@elliemae/ds-props-helpers';
+import type { DSFastListT } from '@elliemae/ds-fast-list';
 import { useKeyboard } from './useKeyboard.js';
+import { useMessageFocusTracker } from './useMessageFocusTracker.js';
 import type { DSChatT } from '../../react-desc-prop-types.js';
 type UseChatContainerMessageList = (props: DSChatT.MessagesListProps) => {
     propsWithDefault: DSChatT.MessagesListProps;
     globalAttributes: ReturnType<typeof useGetGlobalAttributes>;
-    useVirtualHelpers: DSChatT.ChatVirtualizer;
+    fastListActionRef: React.MutableRefObject<DSFastListT.ActionRef>;
+    paddingStart: number;
+    paddingEnd: number;
     loadMoreRef: React.MutableRefObject<HTMLButtonElement | undefined>;
-    virtualListRef: React.MutableRefObject<HTMLDivElement | undefined>;
+    virtualListRef: React.MutableRefObject<HTMLDivElement | null>;
+    focusTracker: ReturnType<typeof useMessageFocusTracker>;
 } & ReturnType<typeof useKeyboard>;
 export declare const useChatContainerMessageList: UseChatContainerMessageList;
 export {};

package/dist/types/parts/chat-container-messages-list/useFocusAndScrollHelpers.d.ts

@@ -1,17 +1,21 @@
 import React from 'react';
+import type { DSFastListT } from '@elliemae/ds-fast-list';
 import type { DSChatT } from '../../react-desc-prop-types.js';
+import type { MessageId } from './useMessageFocusTracker.js';
 type UseFocusAndScrollHelpersArgs = {
     propsWithDefault: DSChatT.MessagesListProps;
-    useVirtualHelpers: DSChatT.ChatVirtualizer;
+    fastListActionRef: React.MutableRefObject<DSFastListT.ActionRef>;
     pendingOnScroll: React.MutableRefObject<boolean>;
-    virtualListRef: React.MutableRefObject<HTMLDivElement | undefined>;
+    trackFocusMessage: (messageId: MessageId, options?: {
+        preventScroll?: boolean;
+    }) => void;
 };
-export declare const useFocusAndScrollHelpers: ({ propsWithDefault: { onScrollEnds }, useVirtualHelpers: { scrollToIndex: vScroll, calculateRange }, pendingOnScroll, virtualListRef, }: UseFocusAndScrollHelpersArgs) => {
+export declare const useFocusAndScrollHelpers: ({ propsWithDefault: { onScrollEnds, messages }, fastListActionRef, pendingOnScroll, trackFocusMessage, }: UseFocusAndScrollHelpersArgs) => {
+    vScroll: (index: number, opts?: DSChatT.ScrollActionOptions) => void;
     onScrollStop: () => string[];
-    updateCache: import("lodash").DebouncedFuncLeading<() => void>;
     getMessagesInView: () => string[];
     onlyFocus: (index: string) => void;
-    scrollAndFocus: (index: number) => void;
+    scrollAndFocus: (index: number, opts?: DSChatT.ScrollActionOptions) => void;
     checkPendingOnScroll: () => void;
 };
 export {};

package/dist/types/parts/chat-container-messages-list/useGlobalEventListener.d.ts

@@ -3,7 +3,7 @@ import { type TypescriptHelpersT } from '@elliemae/ds-typescript-helpers';
 import { type DSChatT } from '../../react-desc-prop-types.js';
 type UseGlobalEventListenerArgs = {
     propsWithDefault: DSChatT.MessagesListProps;
-    virtualListRef: React.MutableRefObject<HTMLDivElement | undefined>;
+    virtualListRef: React.MutableRefObject<HTMLDivElement | null>;
     onScrollStop: () => string[];
     checkPendingOnScroll: TypescriptHelpersT.GenericFunc;
 };

package/dist/types/parts/chat-container-messages-list/useKeyboard.d.ts

@@ -1,15 +1,19 @@
 import React from 'react';
 import type { DSChatT } from '../../react-desc-prop-types.js';
+import type { MessageId } from './useMessageFocusTracker.js';
 type UseKeyboardArgs = {
     propsWithDefault: DSChatT.MessagesListProps;
     actionRef: DSChatT.ActionRef;
-    virtualListRef: React.MutableRefObject<HTMLDivElement | undefined>;
+    virtualListRef: React.MutableRefObject<HTMLDivElement | null>;
     loadMoreRef: React.MutableRefObject<HTMLButtonElement | undefined>;
-    scrollAndFocus: (index: number, opts?: DSChatT.ScrollToIndexOptions) => void;
+    scrollAndFocus: (index: number, opts?: DSChatT.ScrollActionOptions) => void;
     onlyFocus: (index: string) => void;
     getMessagesInView: () => string[];
+    trackFocusMessage: (messageId: MessageId, options?: {
+        preventScroll?: boolean;
+    }) => void;
 };
-export declare const useKeyboard: ({ propsWithDefault: { hasMoreItems, messages, bannerPosition, bannerRef }, actionRef, virtualListRef, loadMoreRef, scrollAndFocus, onlyFocus, getMessagesInView, }: UseKeyboardArgs) => {
+export declare const useKeyboard: ({ propsWithDefault: { hasMoreItems, messages, bannerPosition, bannerRef }, actionRef, virtualListRef, loadMoreRef, scrollAndFocus, onlyFocus, getMessagesInView, trackFocusMessage, }: UseKeyboardArgs) => {
     handleKey: (e: React.KeyboardEvent<HTMLElement>) => void;
     handleListKey: (e: React.KeyboardEvent) => void;
 };

package/dist/types/parts/chat-container-messages-list/useMessageFocusTracker.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+/** Focus identity of a message, from `getMessageFocusId`. */
+export type MessageId = string;
+/**
+ * Identity the focus intent is kept by: the message's `dsId`, which survives index shifts. `dsId` is required by
+ * the types but not at runtime, so a message without one falls back to its index (the focus then follows the
+ * position, as it did before the focus tracker) instead of matching every other id-less message. The two forms
+ * carry different prefixes so a `dsId` can never equal an index fallback, and the type of the `dsId` is kept so
+ * `3` and `'3'` stay different messages, as with a direct comparison.
+ */
+export declare const getMessageFocusId: (message: {
+    dsId?: string | number | null;
+}, index: number) => MessageId;
+/**
+ * Target by position, for a request made before the message exists in the rendered list (for example
+ * `focusToIndex` called right after the consumer adds a message): the item at that index focuses itself when it
+ * mounts, and its real focus then moves the intent to its identity.
+ */
+export declare const getMessagePositionId: (index: number) => MessageId;
+export type MessageFocusRequest = {
+    /** Identity of the message to focus, from `getMessageFocusId`. */
+    messageId: MessageId;
+    /** Incremented by every explicit request, so asking again for the current target focuses it again. */
+    requestId: number;
+    /** `true` when the caller scrolls to the message itself, so focusing must not scroll as well. */
+    preventScroll: boolean;
+};
+type TrackFocusOptions = {
+    preventScroll?: boolean;
+};
+/**
+ * Message focus through the focus-tracker pattern: handlers declare which message should have the focus, and
+ * only that message's `ItemRenderer` focuses itself from its ref callback, once React has committed it. Nothing
+ * here moves the focus directly.
+ *
+ * Removing a focused message never clears the intent: React does not dispatch `onBlur` for a focused node it
+ * removes itself (measured for a prepend and for a message scrolled out of the virtual window). The intent is
+ * cleared by real focus moves: leaving the list (`handleFocusOut`), a `focusin` on a non-message element of the
+ * list, any `focusin` outside the list while an intent exists (also when the focus was on the page, where no
+ * event crosses the list), and a remount that finds the focus elsewhere (`mayTakeFocus`).
+ */
+export declare const useMessageFocusTracker: (virtualListRef: React.MutableRefObject<HTMLDivElement | null>) => {
+    focusRequest: MessageFocusRequest | null;
+    trackFocusMessage: (messageId: MessageId, { preventScroll }?: TrackFocusOptions) => void;
+    trackFocusResetter: () => void;
+    trackFocusedMessage: (messageId: MessageId) => void;
+    mayTakeFocus: (requestId: number, target: Element | null) => "request" | "restore" | null;
+    markFulfilled: (requestId: number) => void;
+    handleFocusOut: (e: React.FocusEvent<HTMLElement>) => void;
+    listRootRef: (node: HTMLElement | null) => void;
+};
+export {};