@katechat/ui 1.0.0

package/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "es5",
+  "printWidth": 120,
+  "bracketSpacing": true,
+  "arrowParens": "avoid"
+}

package/esbuild.js

@@ -0,0 +1,56 @@
+import esbuild from "esbuild";
+import { clean } from "esbuild-plugin-clean";
+import { sassPlugin, postcssModules } from "esbuild-sass-plugin";
+import fs from "fs";
+
+// Create directory if it doesn't exist
+if (!fs.existsSync("./dist")) {
+  fs.mkdirSync("./dist");
+}
+// Production build configuration
+esbuild
+  .build({
+    entryPoints: ["./src/index.ts"],
+    outdir: "./dist",
+    bundle: true,
+    minify: true,
+    format: "iife",
+    splitting: false,
+    loader: {
+      ".js": "jsx",
+      ".svg": "dataurl",
+      ".png": "dataurl",
+      ".jpg": "dataurl",
+      ".gif": "dataurl",
+      ".woff": "file",
+      ".woff2": "file",
+      ".ttf": "file",
+      ".eot": "file",
+    },
+    plugins: [
+      clean({ patterns: ["./dist/*.*"] }),
+      sassPlugin({
+        filter: /\.module\.scss$/,
+        transform: postcssModules({}),
+      }),
+      sassPlugin({
+        filter: /\.scss$/,
+      }),
+    ],
+    define: {
+      "process.env.NODE_ENV": JSON.stringify(process.env.NODE_ENV || "production"),
+    },
+    metafile: true,
+  })
+  .then(result => {
+    console.log("⚡ Build complete! Bundle created in ./dist");
+    console.log(`📦 Config: APP_API_URL: ${process.env.APP_API_URL}`);
+    const outputSize = Object.entries(result.metafile.outputs).reduce((total, [name, data]) => {
+      return total + data.bytes;
+    }, 0);
+    console.log(`📦 Total bundle size: ${(outputSize / 1024 / 1024).toFixed(2)}MB`);
+  })
+  .catch(e => {
+    console.error("❌ Build failed:", e);
+    process.exit(1);
+  });

package/jest.config.js

@@ -0,0 +1,24 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "jsdom",
+  setupFilesAfterEnv: ["<rootDir>/src/setupTests.ts"],
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/src/$1",
+    "\\.(css|less|scss|sass)$": "<rootDir>/src/__mocks__/styleMock.js",
+    "\\.(jpg|jpeg|png|gif|webp|svg)$": "<rootDir>/src/__mocks__/fileMock.js",
+  },
+  transform: {
+    "^.+\\.[tj]sx?$": [
+      "ts-jest",
+      {
+        tsconfig: {
+          jsx: "react-jsx",
+        },
+      },
+    ],
+  },
+  testMatch: ["**/__tests__/**/*.test.(ts|tsx)"],
+  coverageDirectory: "coverage",
+  collectCoverageFrom: ["src/**/*.{ts,tsx}", "!src/**/*.d.ts"],
+};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@katechat/ui",
+  "version": "1.0.0",
+  "description": "KateChat - AI Chat Interface modules collection",
+  "main": "src/index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node --experimental-default-type=module esbuild.js",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,css,scss}\"",
+    "typecheck": "tsc --noEmit",
+    "test": "jest --passWithNoTests --coverage"
+  },
+  "dependencies": {
+    "highlight.js": "^11.11.1",
+    "i18next": "^23.16.8",
+    "lodash": "^4.17.21",
+    "marked": "^15.0.12",
+    "marked-highlight": "^2.2.2",
+    "marked-katex-extension": "^5.1.5"
+  },
+  "peerDependencies": {
+    "@mantine/carousel": "8.3.3",
+    "@mantine/core": "8.3.3",
+    "@mantine/dates": "8.3.3",
+    "@mantine/form": "8.3.3",
+    "@mantine/hooks": "8.3.3",
+    "@mantine/modals": "8.3.3",
+    "@mantine/notifications": "8.3.3",
+    "@tabler/icons-react": "^3.1.0",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-redux": "^9.2.0",
+    "react-router-dom": "^6.23.1"
+  },
+  "devDependencies": {
+    "@babel/preset-env": "^7.24.5",
+    "@babel/preset-react": "^7.24.1",
+    "@babel/preset-typescript": "^7.24.1",
+    "@mantine/carousel": "8.3.3",
+    "@mantine/core": "8.3.3",
+    "@mantine/dates": "8.3.3",
+    "@mantine/form": "8.3.3",
+    "@mantine/hooks": "8.3.3",
+    "@mantine/modals": "8.3.3",
+    "@mantine/notifications": "8.3.3",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/jest": "^29.5.12",
+    "@types/lodash": "^4.17.17",
+    "@types/node": "^22.15.18",
+    "@types/react": "^19.1.4",
+    "@types/react-dom": "^19.1.5",
+    "@types/react-router-dom": "^5.3.3",
+    "esbuild": "^0.25.9",
+    "esbuild-plugin-clean": "^1.0.1",
+    "esbuild-plugin-polyfill-node": "^0.3.0",
+    "esbuild-sass-plugin": "^3.3.1",
+    "express": "^4.19.2",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "postcss": "^8.5.3",
+    "postcss-modules": "^6.0.1",
+    "postcss-preset-mantine": "^1.13.0",
+    "postcss-simple-vars": "^7.0.1",
+    "prettier": "^3.2.5",
+    "react": "19.1.0",
+    "react-dom": "19.1.0",
+    "react-redux": "^9.2.0",
+    "react-router-dom": "^6.23.1",
+    "sass": "^1.71.1",
+    "typescript": "^5.8.3"
+  }
+}

package/postcss.config.cjs

@@ -0,0 +1,14 @@
+module.exports = {
+  plugins: {
+    "postcss-preset-mantine": {},
+    "postcss-simple-vars": {
+      variables: {
+        "mantine-breakpoint-xs": "36em",
+        "mantine-breakpoint-sm": "48em",
+        "mantine-breakpoint-md": "62em",
+        "mantine-breakpoint-lg": "75em",
+        "mantine-breakpoint-xl": "88em",
+      },
+    },
+  },
+};

package/src/__mocks__/fileMock.js

@@ -0,0 +1 @@
+module.exports = "test-file-stub";

package/src/__mocks__/styleMock.js

@@ -0,0 +1 @@
+module.exports = {};

package/src/components/chat/ChatMessagesContainer.module.scss

@@ -0,0 +1,77 @@
+@import "@mantine/core/styles.css";
+
+.messagesContainer {
+  flex-grow: 1;
+  position: relative;
+  display: none;
+  flex-direction: column;
+  border: 1px solid var(--app-shell-border-color);
+  border-radius: var(--mantine-radius-md);
+  /* 
+   * Two-level scrolling architecture:
+   * The parent (.messagesContainer) uses overflow-y: hidden to prevent unwanted scrollbars and control the visible area.
+   * The child (.scroller) uses overflow-y: scroll to enable vertical scrolling for the message list.
+   * This pattern is intentional; do not merge the scroll behavior into the parent.
+   */
+  overflow-y: hidden;
+  opacity: 1;
+  transition: all 0.3s ease;
+
+  .messagesList {
+    opacity: 0;
+    margin-bottom: 1rem;
+  }
+
+  &.empty {
+    flex-grow: 0;
+    opacity: 0;
+  }
+
+  .scroller {
+    overflow-y: scroll;
+    flex-grow: 1;
+  }
+
+  &.loadCompleted {
+    .scroller {
+      scroll-behavior: smooth;
+    }
+
+    display: flex;
+
+    .messagesList {
+      opacity: 1;
+    }
+  }
+}
+
+.anchorContainer {
+  position: absolute;
+  width: 40px;
+  left: calc(50% - 40px);
+  bottom: 0;
+  height: 48px;
+  z-index: 2;
+  display: flex;
+  flex-direction: column;
+  justify-items: center;
+  align-items: center;
+  opacity: 0;
+  transition: all 0.5s ease;
+
+  &.visible {
+    opacity: 1;
+  }
+
+  .anchor {
+    background-color: var(--mantine-color-body);
+    border-radius: 50%;
+    height: 32px;
+    width: 32px;
+    opacity: 0.75;
+
+    &:hover {
+      opacity: 1;
+    }
+  }
+}

package/src/components/chat/ChatMessagesContainer.tsx

@@ -0,0 +1,151 @@
+import React, { useCallback, useEffect, useImperativeHandle, useRef, useState } from "react";
+import { Group, Loader } from "@mantine/core";
+import { IconCircleChevronDown } from "@tabler/icons-react";
+import { Message, Model, PluginProps } from "@/core";
+import { useIntersectionObserver } from "@/hooks";
+import { ChatMessagesList } from "./ChatMessagesList";
+
+import classes from "./ChatMessagesContainer.module.scss";
+
+interface IProps {
+  messages?: Message[];
+  models: Model[];
+  addChatMessage: (message: Message) => void;
+  removeMessages: (args: { messagesToDelete?: Message[]; deleteAfter?: Message }) => void;
+  loadMoreMessages?: () => void;
+  plugins?: React.FC<PluginProps<Message>>[];
+  detailsPlugins?: ((message: Message) => React.ReactNode)[];
+  streaming?: boolean;
+  loading?: boolean;
+  loadCompleted?: boolean;
+}
+
+export interface ChatMessagesContainerRef {
+  scrollToBottom: () => void;
+}
+
+export const ChatMessagesContainer = React.forwardRef<ChatMessagesContainerRef, IProps>(
+  (
+    {
+      messages,
+      models,
+      addChatMessage,
+      removeMessages,
+      loadMoreMessages,
+      plugins,
+      detailsPlugins,
+      streaming = false,
+      loadCompleted = true,
+      loading = false,
+    },
+    ref
+  ) => {
+    const [showAnchorButton, setShowAnchorButton] = useState<boolean>(false);
+    const messagesContainerRef = useRef<HTMLDivElement>(null);
+    const anchorTimer = useRef<NodeJS.Timeout | null>(null);
+
+    // #region Scrolling
+    const scrollToBottom = useCallback(() => {
+      messagesContainerRef.current?.scrollTo(0, messagesContainerRef.current?.scrollHeight ?? 0);
+    }, [messagesContainerRef]);
+
+    // Expose scrollToBottom method to parent via ref
+    useImperativeHandle(
+      ref,
+      () => ({
+        scrollToBottom,
+      }),
+      [scrollToBottom]
+    );
+
+    const autoScroll = useCallback(() => {
+      if (!showAnchorButton) {
+        scrollToBottom();
+      }
+    }, [scrollToBottom, showAnchorButton]);
+
+    useEffect(() => {
+      autoScroll();
+    }, [messages, autoScroll]);
+
+    const handleScroll = useCallback(
+      (e: React.MouseEvent<HTMLDivElement>) => {
+        const { scrollTop, scrollHeight, clientHeight } = e.target as HTMLDivElement;
+        anchorTimer.current && clearTimeout(anchorTimer.current);
+
+        if (scrollHeight - scrollTop - clientHeight < 2) {
+          setShowAnchorButton(false);
+        } else if (messages?.length) {
+          if (streaming) {
+            anchorTimer.current = setTimeout(() => {
+              setShowAnchorButton(true);
+            }, 100);
+          } else {
+            setShowAnchorButton(true);
+          }
+        }
+      },
+      [messages?.length, streaming]
+    );
+
+    const anchorHandleClick = useCallback(() => {
+      setShowAnchorButton(false);
+      scrollToBottom();
+    }, [scrollToBottom]);
+
+    useEffect(() => {
+      if (loadCompleted) {
+        setShowAnchorButton(false);
+        setTimeout(scrollToBottom, 200);
+      }
+    }, [loadCompleted]);
+
+    const firstMessageRef = useIntersectionObserver<HTMLDivElement>(
+      () => loadMoreMessages?.(),
+      [loadMoreMessages],
+      200
+    );
+
+    // #endregion
+
+    return (
+      <div
+        className={[
+          classes.messagesContainer,
+          loadCompleted ? classes.loadCompleted : "",
+          loadCompleted && messages?.length === 0 ? classes.empty : "",
+        ].join(" ")}
+      >
+        <div className={classes.scroller} ref={messagesContainerRef} onScroll={handleScroll}>
+          <div ref={firstMessageRef} />
+          {loading && (
+            <Group justify="center" align="center" py="xl">
+              <Loader />
+            </Group>
+          )}
+
+          <div className={classes.messagesList}>
+            {messages && (
+              <ChatMessagesList
+                messages={messages}
+                onMessageDeleted={removeMessages} // Reload messages after deletion
+                onAddMessage={addChatMessage}
+                models={models}
+                plugins={plugins}
+                detailsPlugins={detailsPlugins}
+              />
+            )}
+          </div>
+        </div>
+
+        <div className={[classes.anchorContainer, showAnchorButton ? classes.visible : ""].join(" ")}>
+          <div className={classes.anchor}>
+            <IconCircleChevronDown size={32} color="teal" style={{ cursor: "pointer" }} onClick={anchorHandleClick} />
+          </div>
+        </div>
+      </div>
+    );
+  }
+);
+
+ChatMessagesContainer.displayName = "ChatMessagesContainer";

package/src/components/chat/ChatMessagesList.tsx

@@ -0,0 +1,216 @@
+import React, { useCallback, useRef, useState } from "react";
+import { Stack, Group } from "@mantine/core";
+import { notifications } from "@mantine/notifications";
+
+import { notEmpty, ok } from "@/lib/assert";
+import { Message, Model, PluginProps } from "@/core";
+import { ChatMessage } from "./message/ChatMessage";
+import { ImagePopup } from "../modal/ImagePopup";
+
+interface ChatMessagesProps {
+  messages: Message[];
+  onMessageDeleted?: (args: { messagesToDelete?: Message[]; deleteAfter?: Message }) => void;
+  onAddMessage?: (message: Message) => void;
+  plugins?: React.FC<PluginProps<Message>>[];
+  detailsPlugins?: ((message: Message) => React.ReactNode)[];
+  models: Model[];
+}
+
+export const ChatMessagesList: React.FC<ChatMessagesProps> = ({
+  messages,
+  onMessageDeleted,
+  onAddMessage,
+  plugins = [],
+  detailsPlugins = [],
+  models = [],
+}) => {
+  const componentRef = useRef<HTMLDivElement>(null);
+
+  const [imageToShow, setImageToShow] = useState<string | undefined>();
+  const [imageFileName, setImageFileName] = useState<string | undefined>();
+  const [updatedMessages, setUpdatedMessages] = useState<Set<string>>(new Set());
+
+  const addEditedMessage = (messageId: string) => setUpdatedMessages(prev => new Set(prev).add(messageId));
+
+  const clearEditedMessage = (messageId: string) => {
+    setUpdatedMessages(prev => {
+      const set = new Set(prev);
+      set.delete(messageId);
+      return set;
+    });
+  };
+
+  const resetSelectedImage = () => {
+    setImageToShow(undefined);
+    setImageFileName(undefined);
+  };
+
+  // common messages interaction logic
+  const handleMessageClick = useCallback(
+    (e: React.MouseEvent<HTMLDivElement>) => {
+      if (!e.target) return;
+
+      // common clicks logic to simplify code in ChatMessage component
+      const classesToFind = ["code-copy-btn", "code-toggle-all", "copy-message-btn", "code-header", "message-image"];
+
+      let el: HTMLElement = e.target as HTMLElement;
+      for (const cls of classesToFind) {
+        const trg = el.closest(`.${cls}`);
+        if (trg) {
+          el = trg as HTMLElement;
+          break;
+        }
+      }
+
+      if (!el) {
+        return;
+      }
+
+      const target = el as HTMLElement;
+      const toggleCodeBlock = (header: HTMLElement) => {
+        const codeBlock = header?.nextElementSibling as HTMLElement;
+        if (codeBlock.classList.contains("collapsed")) {
+          header.classList.remove("collapsed");
+          codeBlock && codeBlock.classList.remove("collapsed");
+        } else {
+          header.classList.add("collapsed");
+          codeBlock && codeBlock.classList.add("collapsed");
+        }
+      };
+
+      // copy code block
+      if (target.classList.contains("code-copy-btn")) {
+        const data = target.parentElement?.parentElement?.nextElementSibling?.querySelector(
+          ".code-data"
+        ) as HTMLElement;
+        if (data) {
+          const code = decodeURIComponent(data.dataset.code || "").trim();
+          navigator.clipboard.writeText(code);
+        }
+
+        const copyIcon = target.querySelector(".copy-icon") as HTMLElement;
+        const checkIcon = target.querySelector(".check-icon") as HTMLElement;
+        if (copyIcon && checkIcon) {
+          copyIcon.style.display = "none";
+          checkIcon.style.display = "block";
+          setTimeout(() => {
+            copyIcon.style.display = "block";
+            checkIcon.style.display = "none";
+          }, 2000);
+        }
+      }
+      // code toggle btn
+      else if (target.classList.contains("code-header")) {
+        toggleCodeBlock(target);
+      }
+      // all code blocks toggle
+      else if (target.classList.contains("code-toggle-all")) {
+        componentRef.current?.querySelectorAll(".code-header").forEach(header => {
+          toggleCodeBlock(header as HTMLElement);
+        });
+      }
+      // copy message
+      else if (target.classList.contains("copy-message-btn")) {
+        if (target.dataset["messageId"]) {
+          const index = target.dataset["messageIndex"];
+          const linkedIndex = target.dataset["messageLinkedIndex"];
+          const messageId = target.dataset["messageId"];
+
+          let msg: Message | undefined =
+            index != undefined ? messages[Number(index)] : messages.find(m => m.id === messageId);
+          if (linkedIndex != undefined) {
+            msg = msg?.linkedMessages?.[Number(linkedIndex)];
+          }
+          ok(msg, "Message should exist to copy");
+          const content = (msg.content || "").trim();
+          const html = msg.html || [];
+
+          if (html.length && html[0]) {
+            const blobHTML = new Blob([html.join("<br/>")], { type: "text/html" });
+            const blobPlain = new Blob([content], { type: "text/plain" });
+            navigator.clipboard
+              .write([new ClipboardItem({ [blobHTML.type]: blobHTML, [blobPlain.type]: blobPlain })])
+              .catch(err =>
+                notifications.show({
+                  title: "Error",
+                  message: err.message || "Failed to copy message",
+                  color: "red",
+                })
+              );
+          } else {
+            navigator.clipboard.writeText(content);
+          }
+
+          const checkIcon = target.parentElement?.querySelector(".check-icon") as HTMLElement;
+          if (checkIcon) {
+            target.style.display = "none";
+            checkIcon.style.display = "inline-block";
+            setTimeout(() => {
+              target.style.display = "inline-block";
+              checkIcon.style.display = "none";
+            }, 2000);
+          }
+        }
+      }
+      // code toggle btn
+      else if (target.classList.contains("message-image")) {
+        const fileName = target.dataset["fileName"];
+        const imageUrl = (target as HTMLImageElement).src;
+
+        setImageToShow(imageUrl);
+        setImageFileName(fileName);
+      }
+    },
+    [messages]
+  );
+
+  const pluginsLoader = useCallback(
+    (msg: Message) => {
+      return (
+        <>
+          {plugins.map((PluginComponent, idx) => (
+            <PluginComponent
+              key={idx}
+              message={msg}
+              onAddMessage={onAddMessage}
+              onAction={addEditedMessage}
+              onActionEnd={clearEditedMessage}
+              onMessageDeleted={onMessageDeleted}
+              disabled={updatedMessages.has(msg.id)}
+            />
+          ))}
+        </>
+      );
+    },
+    [plugins, onAddMessage, onMessageDeleted, updatedMessages, addEditedMessage, clearEditedMessage]
+  );
+
+  const messageDetailsLoader = useCallback(
+    (msg: Message) => {
+      const details = detailsPlugins.map((plugin, idx) => plugin(msg)).filter(notEmpty);
+      return details.length ? details : null;
+    },
+    [plugins, detailsPlugins]
+  );
+
+  return (
+    <>
+      <Stack gap="xs" ref={componentRef} onClick={handleMessageClick}>
+        {messages.map((msg, index) => (
+          <Group key={msg.id} align="flex-start" gap="xs">
+            <ChatMessage
+              message={msg}
+              index={index}
+              disabled={updatedMessages.has(msg.id)}
+              pluginsLoader={pluginsLoader}
+              messageDetailsLoader={messageDetailsLoader}
+              models={models}
+            />
+          </Group>
+        ))}
+      </Stack>
+
+      <ImagePopup fileName={imageFileName ?? ""} fileUrl={imageToShow ?? ""} onClose={resetSelectedImage} />
+    </>
+  );
+};

package/src/components/chat/index.ts

@@ -0,0 +1,4 @@
+export * from "./message";
+export * from "./input";
+export * from "./ChatMessagesList";
+export { ChatMessagesContainer, type ChatMessagesContainerRef } from "./ChatMessagesContainer";