@webitel/ui-chats 0.1.40 → 0.1.41

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@webitel/ui-chats",
-	"version": "0.1.40",
+	"version": "0.1.41",
 	"description": "Reusable Webitel Frontend Code for Chats UI",
 	"workspaces": [
 		"../../",
@@ -10,6 +10,7 @@
 	"scripts": {
 		"dev": "vite",
 		"build:types": "vue-tsc -p ./tsconfig.build.json",
+		"typecheck": "vue-tsc --noEmit -p ./tsconfig.typecheck.json",
 		"lint:fix": "npx biome check --write ./src",
 		"biome:ci:gh": "biome ci ./src --reporter=github",
 		"test:unit": "node -e \"process.exit(0)\"",
@@ -26,6 +27,7 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.4.16",
 		"@types/node": "^24.10.0",
+		"@webitel/chat-web-sdk": "^0.0.19",
 		"@vitejs/plugin-vue": "^6.0.1",
 		"@vue/tsconfig": "^0.8.1",
 		"mitt": "^3",
@@ -37,11 +39,17 @@
 	},
 	"peerDependencies": {
 		"@webitel/api-services": "^0.1.0",
+		"@webitel/chat-web-sdk": "^0.0.19",
 		"@webitel/styleguide": "~26.2",
 		"@webitel/ui-sdk": "~26.6",
 		"mitt": "^3",
 		"vue": "^3.5"
 	},
+	"peerDependenciesMeta": {
+		"@webitel/chat-web-sdk": {
+			"optional": true
+		}
+	},
 	"type": "module",
 	"main": "index.ts",
 	"types": "index.d.ts",
@@ -59,6 +67,14 @@
 		"./ui": {
 			"types": "./types/ui/index.d.ts",
 			"import": "./src/ui/index.ts"
+		},
+		"./types": {
+			"types": "./types/types/index.d.ts",
+			"import": "./src/types/index.ts"
+		},
+		"./adapters": {
+			"types": "./types/adapters/index.d.ts",
+			"import": "./src/adapters/index.ts"
 		}
 	},
 	"author": "webitel",

package/src/adapters/chat-web-sdk/toChatMessage.ts

@@ -0,0 +1,111 @@
+import type { IMessage } from '@webitel/chat-web-sdk';
+
+import type { ChatMember, ChatMessageFile, ChatMessageType } from '../../types';
+
+/**
+ * Sub-shapes of a chat-web-sdk message, derived via indexed access so this
+ * adapter depends on a single package (`@webitel/chat-web-sdk`) and stays in
+ * sync automatically when the SDK reshapes them.
+ */
+type SdkMember = NonNullable<IMessage['sender']>;
+type SdkImage = NonNullable<IMessage['images']>[number];
+type SdkDocument = NonNullable<IMessage['documents']>[number];
+
+export interface ToChatMessageOptions {
+	/**
+	 * Decide whether a message is authored by the current agent / "self" side.
+	 * Result is written to `ChatMember.self`, which drives outgoing-bubble
+	 * alignment in the UI. The message alone cannot know who "self" is — that
+	 * is presentation context the caller owns (e.g. compare `sender.contact`
+	 * against the logged-in account).
+	 */
+	isSelf?: (message: IMessage) => boolean;
+}
+
+/**
+ * Parse a chat-web-sdk Unix-ms timestamp (`string`) into the numeric ms the
+ * UI contract expects. Returns `0` for missing / non-numeric input.
+ */
+const toTimestamp = (value: string | undefined): number => {
+	if (value == null) return 0;
+	const parsed = Number(value);
+	return Number.isFinite(parsed) ? parsed : 0;
+};
+
+const mapImage = (image: SdkImage): ChatMessageFile => ({
+	id: image.id,
+	mime: image.mime,
+	url: image.url,
+});
+
+const mapDocument = (document: SdkDocument): ChatMessageFile => ({
+	id: document.id,
+	name: document.name,
+	size: document.size,
+	mime: document.mime,
+	url: document.url,
+});
+
+/**
+ * A UI message carries at most one `file`, while the SDK exposes separate
+ * `images[]` / `documents[]` arrays. Pick the first available attachment,
+ * preferring images.
+ */
+const mapAttachment = (message: IMessage): ChatMessageFile | undefined => {
+	const image = message.images?.[0];
+	if (image) return mapImage(image);
+
+	const document = message.documents?.[0];
+	if (document) return mapDocument(document);
+
+	return undefined;
+};
+
+const mapMember = (
+	sender: SdkMember | undefined,
+	self: boolean | undefined,
+): ChatMember => {
+	const contact = sender?.contact;
+
+	return {
+		id: sender?.id ?? '',
+		name: contact?.name ?? '',
+		// UI derives bot rendering from `type === 'bot'`; otherwise keep the
+		// SDK channel type ('telegram', 'webchat', …).
+		type: contact?.isBot ? 'bot' : (contact?.type ?? ''),
+		externalId: contact?.sub ?? contact?.iss,
+		self,
+	};
+};
+
+/**
+ * Map a single `@webitel/chat-web-sdk` message (`IMessage`) into the
+ * `@webitel/ui-chats` presentation contract (`ChatMessageType`).
+ *
+ * Anti-corruption layer: keeps `ui-chats` free of any backend/SDK coupling.
+ */
+export const mapMessageToChatMessage = (
+	message: IMessage,
+	options: ToChatMessageOptions = {},
+): ChatMessageType => {
+	const createdAt = toTimestamp(message.createdAt);
+
+	return {
+		id: message.id,
+		text: message.body,
+		createdAt,
+		date: createdAt,
+		updatedAt: message.editedAt ? toTimestamp(message.editedAt) : undefined,
+		file: mapAttachment(message),
+		member: mapMember(message.sender, options.isSelf?.(message)),
+	};
+};
+
+/**
+ * Batch variant of {@link mapMessageToChatMessage} for message history pages.
+ */
+export const mapMessagesToChatMessages = (
+	messages: readonly IMessage[],
+	options?: ToChatMessageOptions,
+): ChatMessageType[] =>
+	messages.map((message) => mapMessageToChatMessage(message, options));

package/src/adapters/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Adapters mapping external data sources into the `@webitel/ui-chats`
+ * presentation contract (`ChatMessageType`, …).
+ *
+ * Consuming this entry pulls `@webitel/chat-web-sdk` (declared as an optional
+ * peerDependency). The core `@webitel/ui-chats/ui` entry stays free of it.
+ */
+export {
+	mapMessagesToChatMessages,
+	mapMessageToChatMessage,
+	type ToChatMessageOptions,
+} from './chat-web-sdk/toChatMessage';

package/src/types/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Public data contract of `@webitel/ui-chats`.
+ *
+ * These are the plain, transport-agnostic shapes the UI components accept.
+ * External data sources (e.g. `@webitel/chat-web-sdk`) must be mapped into
+ * them — see `@webitel/ui-chats/adapters`.
+ */
+export type {
+	ChatMember,
+	ChatMessageChatInfo,
+	ChatMessageFile,
+	ChatMessageType,
+	ChatVia,
+	ContactInfo,
+} from '../ui/messaging/types/ChatMessage.types';

package/src/ui/index.ts

@@ -1,4 +1,6 @@
 export { ChatAction } from './chat-footer/modules/user-input/enums/ChatAction.enum';
+export { useChatScroll } from './messaging/composables/useChatScroll';
+export { useObserveHeightUntilStable } from './messaging/composables/useObserveHeightUntilStable';
 export { useChatMessageFile } from './messaging/modules/message/composables/useChatMessageFile';
 export { MessageAction } from './messaging/modules/message/enums/MessageAction.enum';
 export type {

package/src/ui/messaging/components/chat-date-divider.vue

@@ -19,7 +19,7 @@ const props = defineProps<{
 
 const { t } = useI18n();
 
-const formattedDate = computed<Date>(() => {
+const formattedDate = computed<string>(() => {
 	const chatDate = formatDate(+props.date, FormatDateMode.DATE);
 	const today = formatDate(Date.now(), FormatDateMode.DATE);
 

package/src/ui/messaging/components/scroll-to-bottom-btn.vue

@@ -17,8 +17,6 @@
 </template>
 
 <script setup lang="ts">
-import { defineEmits } from 'vue';
-
 const props = withDefaults(
 	defineProps<{
 		newMessageCount?: number;

package/src/ui/messaging/components/the-messages-container.vue

@@ -7,31 +7,35 @@
       ref="messages-container"
       class="the-chat-messages-container__wrapper wt-scrollbar"
       @scroll="handleChatScroll"
-      @resize="handleChatResize"
     >
-      <chat-observer
-        v-if="props.next"
-        :next="props.next"
-        :loading="props.isLoading"
-        @[ChatAction.LoadNextMessages]="handleLoadNextMessages"
-      />
-      <chat-message
-        v-for="(message, index) of props.messages"
-        :key="message.id"
-        :message="message"
-        :agent-name="props.agentName"
-        :show-avatar="showAvatar(index)"
-        :without-avatars="props.withoutAvatars"
-        :username="props.contact?.name"
-        @[MessageAction.ClickOnImage]="clickOnImage(message)"
+      <div
+        ref="chat-content"
+        class="the-chat-messages-container__content"
       >
-        <template #before-message>
-          <chat-date-divider
-            v-if="showChatDate(index)"
-            :date="message.createdAt"
-          />
-        </template>
-      </chat-message>
+        <chat-observer
+          v-if="props.next"
+          :next="props.next"
+          :loading="props.isLoading"
+          @[ChatAction.LoadNextMessages]="handleLoadNextMessages"
+        />
+        <chat-message
+          v-for="(message, index) of props.messages"
+          :key="message.id"
+          :message="message"
+          :agent-name="props.agentName"
+          :show-avatar="showAvatar(index)"
+          :without-avatars="props.withoutAvatars"
+          :username="props.contact?.name?.commonName"
+          @[MessageAction.ClickOnImage]="clickOnImage(message)"
+        >
+          <template #before-message>
+            <chat-date-divider
+              v-if="showChatDate(index)"
+              :date="message.createdAt"
+            />
+          </template>
+        </chat-message>
+      </div>
     </div>
     <scroll-to-bottom-btn
       v-if="showScrollToBottomBtn"
@@ -47,17 +51,11 @@
 >
 import { WebitelContactsContact } from '@webitel/api-services/gen/models';
 import type { Emitter } from 'mitt';
-import {
-	computed,
-	defineProps,
-	inject,
-	nextTick,
-	onMounted,
-	useTemplateRef,
-} from 'vue';
+import { computed, inject, useTemplateRef } from 'vue';
 import { ChatAction } from '../../chat-footer/modules/user-input/enums/ChatAction.enum';
 import type { UiChatsEmitterEvents } from '../../utils/emitter';
 import { useChatScroll } from '../composables/useChatScroll';
+import { useObserveHeightUntilStable } from '../composables/useObserveHeightUntilStable';
 import ChatMessage from '../modules/message/components/chat-message.vue';
 import { useChatMessages } from '../modules/message/composables/useChatMessage';
 import { MessageAction } from '../modules/message/enums/MessageAction.enum';
@@ -76,17 +74,22 @@ const props = withDefaults(
 		withoutAvatars?: boolean;
 		agentName?: string;
 		contact?: WebitelContactsContact;
+		chatId?: string;
+		isChatClosed?: boolean;
 	}>(),
 	{
 		next: false,
 		isLoading: false,
 		withoutAvatars: false,
+		chatId: '',
+		isChatClosed: false,
 	},
 );
 
 const emit = defineEmits<(e: typeof ChatAction.LoadNextMessages) => void>();
 
-const messagesContainer = useTemplateRef('messages-container');
+const chatContainer = useTemplateRef('messages-container');
+const chatContent = useTemplateRef('chat-content');
 
 const { showAvatar, showChatDate } = useChatMessages(
 	computed(() => props.messages),
@@ -98,11 +101,21 @@ const {
 	scrollToBottom,
 	loadNextMessages,
 	handleChatScroll,
-	handleChatResize,
-} = useChatScroll(
-	messagesContainer,
-	computed(() => props.messages), // props values reactivity https://stackoverflow.com/questions/72408463/use-props-in-composables-vue3 @author ye.pohranichna
-	computed(() => props.isLoading),
+} = useChatScroll({
+	chatContainer,
+	chatContent,
+	messages: computed(() => props.messages), // props values reactivity https://stackoverflow.com/questions/72408463/use-props-in-composables-vue3 @author ye.pohranichna
+	chatId: computed(() => props.chatId),
+	isChatClosed: computed(() => props.isChatClosed),
+	isLoading: computed(() => props.isLoading),
+	onBeforeStart: ({ scrollToBottom }) => {
+		scrollToBottom();
+		startObserve();
+	},
+});
+
+const { startObserve } = useObserveHeightUntilStable(chatContainer, () =>
+	scrollToBottom('instant'),
 );
 
 function handleLoadNextMessages() {
@@ -117,13 +130,7 @@ function clickOnImage(message: ChatMessageType) {
 	uiChatsEmitter?.emit('clickChatMessageImage', message);
 }
 
-onMounted(async () => {
-	/* TODO: add loader on all chat(in the-chat-container?) and remove timeout after that */
-	await nextTick();
-	setTimeout(() => {
-		scrollToBottom();
-	}, 500);
-});
+// TODO: add loader for all chats(in the-chat-container or in calling component?)
 </script>
 
 <style
@@ -138,14 +145,17 @@ onMounted(async () => {
 }
 
 .the-chat-messages-container__wrapper {
-  display: flex;
-  flex-direction: column;
   box-sizing: border-box;
   overflow-x: hidden;
   overflow-y: auto;
   width: 100%;
   padding-right: var(--scrollbar-width); // scrollbar offset
   scrollbar-gutter: stable both-edges;
+}
+
+.the-chat-messages-container__content {
+  display: flex;
+  flex-direction: column;
   gap: var(--spacing-xs);
 }
 </style>

package/src/ui/messaging/composables/useChatScroll.ts

@@ -1,8 +1,9 @@
-import { useScroll } from '@vueuse/core';
+import { useResizeObserver, useScroll } from '@vueuse/core';
 import {
 	type ComputedRef,
 	computed,
 	nextTick,
+	onUnmounted,
 	type Ref,
 	ref,
 	watch,
@@ -10,105 +11,152 @@ import {
 
 import type { ChatMessageType } from '../types/ChatMessage.types';
 
-export const useChatScroll = (
-	element: Ref<HTMLElement | null> = null,
-	messages: Ref<ChatMessageType[]> | ComputedRef<ChatMessageType[]>,
-	isLoading?: Ref<boolean> | ComputedRef<boolean>,
-) => {
-	/* @author ye.pohranichna
-  why 136px? because: https://webitel.atlassian.net/browse/WTEL-7136 */
-	const defaultThreshold = 136;
-	const { arrivedState } = useScroll(element);
-
-	const newUnseenMessagesCount = ref<number>(0);
-	const showScrollToBottomBtn = ref<boolean>(false);
-	/* @author ye.pohranichna
-    the distance where the scrollToBottomBtn must be shown/hide. */
-	const threshold = ref<number>(defaultThreshold);
-	const isLoadingNextMessages = ref<boolean>(false);
-	const lastVisibleMessageEl = ref<HTMLElement | null>(null);
-
-	const isLastMessageIsMy = computed<boolean>(
-		() => lastMessage.value?.member?.self,
-	);
-	const lastMessage = computed<ChatMessageType>(() => messages.value?.at(-1));
-	const handleChatScroll = () => {
-		const wrapper = element.value;
-		if (!wrapper) return;
-
-		handleShowScrollToBottomBtn(wrapper);
-	};
-
-	const handleChatResize = () => {
-		const wrapper = element.value;
-		if (!wrapper) return;
-
-		updateThreshold(wrapper);
-		handleShowScrollToBottomBtn(wrapper);
-	};
-
-	const handleShowScrollToBottomBtn = (el: HTMLElement) => {
-		if (arrivedState.bottom) {
-			resetScrollToBottomBtn();
-			return;
-			/* @author ye.pohranichna
-          quit the function because we are already at the bottom */
-		}
-
-		const { scrollTop, scrollHeight, clientHeight } = el;
-		const distanceFromBottom = scrollHeight - (scrollTop + clientHeight);
-		showScrollToBottomBtn.value = distanceFromBottom > threshold.value;
-	};
-
-	const resetScrollToBottomBtn = (): void => {
-		newUnseenMessagesCount.value = 0;
-		showScrollToBottomBtn.value = false;
-	};
-
-	const updateThreshold = (el: HTMLElement) => {
-		/* @author ye.pohranichna
-         need to update if clientHeight was changed
-         https://webitel.atlassian.net/browse/WTEL-7136 */
-		threshold.value = Math.max(defaultThreshold, el.clientHeight * 0.3);
-	};
+import { useScrollToBottomBtn } from './useScrollToBottomBtn';
+
+export interface UseChatScrollOptions {
+	chatContainer: Ref<HTMLElement | null>;
+	chatContent: Ref<HTMLElement | null>;
+	messages: Ref<ChatMessageType[]> | ComputedRef<ChatMessageType[]>;
+	chatId: ComputedRef<string>;
+	isChatClosed: ComputedRef<boolean>;
+	isLoading?: Ref<boolean> | ComputedRef<boolean>;
+	onBeforeStart?: (options: {
+		scrollToBottom: (behavior?: ScrollBehavior) => void;
+	}) => void;
+}
+
+export const useChatScroll = ({
+	chatContainer,
+	chatContent,
+	messages,
+	chatId,
+	isChatClosed,
+	isLoading,
+	onBeforeStart = (options) => {
+		options.scrollToBottom();
+	},
+}: UseChatScrollOptions) => {
+	const { arrivedState } = useScroll(chatContainer);
+
+	const {
+		showScrollToBottomBtn,
+		handleChatScroll,
+		resetScrollToBottomBtn,
+		updateScrollToBottomBtnVisibility,
+		updateThreshold,
+	} = useScrollToBottomBtn(chatContainer, arrivedState);
+
+	let isLoadingNextMessages = false;
+	let lastVisibleMessageEl: HTMLElement | null = null;
+	let prevScrollHeight = 0;
+	let resizeObserver: ResizeObserver | null = null;
+	/**
+	 * @author PolinaSukhorukova-webitel
+	 *
+	 * 2 tolerates subpixel scrollTop/clientHeight rounding that can leave
+	 * their sum a fraction short of scrollHeight at the very bottom.
+	 */
+	const bottomThreshold = 2;
+
+	const newUnseenMessagesCount = ref(0);
+
+	const lastMessage = computed(() => messages.value?.at(-1));
+	const isLastMessageMy = computed(() => !!lastMessage.value?.member?.self);
 
 	const handleBtnAfterNewMessage = () => {
-		if (arrivedState.bottom || isLastMessageIsMy.value) {
-			scrollToBottom('smooth');
-		} else {
+		if (isLastMessageMy.value) {
+			scrollToBottom('instant');
+		} else if (!arrivedState.bottom) {
 			newUnseenMessagesCount.value += 1;
 		}
 	};
 
 	const scrollToBottom = (behavior: ScrollBehavior = 'instant') => {
-		element?.value.scrollTo({
-			top: element?.value.scrollHeight,
-			behavior: behavior === 'instant' ? 'auto' : behavior,
+		chatContainer.value?.scrollTo({
+			top: chatContainer.value?.scrollHeight,
+			behavior,
 		});
 
 		newUnseenMessagesCount.value = 0;
-		showScrollToBottomBtn.value = false;
-	};
 
+		resetScrollToBottomBtn();
+	};
 	const getTopMessageEl = () => {
 		// help to fix chat viewing position when new messages was loaded
-		if (!element.value?.children) return;
-		lastVisibleMessageEl.value =
-			element.value?.getElementsByClassName('chat-message')[0] ?? null;
+		if (!chatContainer.value?.children) return;
+		lastVisibleMessageEl =
+			(chatContainer.value?.getElementsByClassName(
+				'chat-message',
+			)[0] as HTMLElement) ?? null;
 	};
 
 	const loadNextMessages = (
-		canLoadMore: boolean | undefined,
+		canLoadMore: boolean,
 		onLoadNextMessages: () => void,
 	) => {
-		if (isLoadingNextMessages.value || isLoading?.value || !canLoadMore) return;
+		if (isLoadingNextMessages || isLoading?.value || !canLoadMore) return;
 
-		isLoadingNextMessages.value = true;
+		isLoadingNextMessages = true;
 		getTopMessageEl();
 
 		onLoadNextMessages();
 	};
 
+	const startStickToBottomObserving = () => {
+		if (!chatContent.value) return;
+
+		prevScrollHeight = chatContainer.value?.scrollHeight ?? 0;
+
+		resizeObserver = new ResizeObserver(() => {
+			const el = chatContainer.value;
+			if (!el) return;
+
+			const newScrollHeight = el.scrollHeight;
+
+			const wasNearBottom =
+				el.scrollTop + el.clientHeight >= prevScrollHeight - bottomThreshold;
+			const contentGrown = newScrollHeight > prevScrollHeight;
+
+			/**
+			 * @author PolinaSukhorukova-webitel
+			 *
+			 * arrivedState.bottom lags after programmatic scrollTo,
+			 * so the distance is also checked manually.
+			 */
+			const shouldScrollToBottom =
+				contentGrown && (arrivedState.bottom || wasNearBottom);
+
+			if (shouldScrollToBottom) {
+				scrollToBottom('instant');
+			}
+
+			prevScrollHeight = newScrollHeight;
+			updateScrollToBottomBtnVisibility(el);
+		});
+
+		resizeObserver.observe(chatContent.value);
+	};
+
+	const stopStickToBottomObserving = () => {
+		resizeObserver?.disconnect();
+		resizeObserver = null;
+	};
+
+	useResizeObserver(chatContainer, () => {
+		const el = chatContainer.value;
+		if (!el) return;
+
+		updateThreshold(el.clientHeight);
+		updateScrollToBottomBtnVisibility(el);
+	});
+
+	const resetScrollState = () => {
+		stopStickToBottomObserving();
+		prevScrollHeight = 0;
+		newUnseenMessagesCount.value = 0;
+		resetScrollToBottomBtn();
+	};
+
 	watch(
 		() => messages.value?.length,
 		(newValue, oldValue) => {
@@ -123,25 +171,57 @@ export const useChatScroll = (
 	watch(
 		() => isLoading?.value,
 		async (loading) => {
-			if (loading || !isLoadingNextMessages.value) return;
+			// restore scroll position after older messages are prepended:
+			// scroll to the previously top message so the view doesn't jump
+			if (loading || !isLoadingNextMessages) return;
 
 			await nextTick();
 
-			element.value?.scrollTo({
-				top: lastVisibleMessageEl.value?.offsetTop,
+			chatContainer.value?.scrollTo({
+				top: lastVisibleMessageEl?.offsetTop,
 				behavior: 'auto',
 			});
 
-			isLoadingNextMessages.value = false;
+			isLoadingNextMessages = false;
 		},
 	);
 
+	watch(
+		() => chatId.value,
+		async () => {
+			resetScrollState();
+
+			if (isChatClosed.value) return;
+
+			await nextTick();
+
+			onBeforeStart?.({
+				scrollToBottom,
+			});
+
+			startStickToBottomObserving();
+		},
+		{
+			immediate: true,
+		},
+	);
+
+	watch(
+		() => arrivedState.bottom,
+		(bottom) => {
+			if (bottom) newUnseenMessagesCount.value = 0;
+		},
+	);
+
+	onUnmounted(() => {
+		stopStickToBottomObserving();
+	});
+
 	return {
 		showScrollToBottomBtn,
 		newUnseenMessagesCount,
 		scrollToBottom,
 		loadNextMessages,
 		handleChatScroll,
-		handleChatResize,
 	};
 };