@databiosphere/findable-ui 49.0.0 → 49.2.0

package/src/views/ResearchView/state/guards/guards.ts

@@ -0,0 +1,58 @@
+import {
+  AssistantMessage,
+  ErrorMessage,
+  Message,
+  MESSAGE_TYPE,
+  MessageResponse,
+  PromptMessage,
+  UserMessage,
+} from "../types";
+
+/**
+ * Returns true if the message is an assistant message.
+ * @param message - Chat message.
+ * @returns True if the message is an assistant message.
+ */
+export function isAssistantMessage<R extends MessageResponse = MessageResponse>(
+  message: Message<R>,
+): message is AssistantMessage<R> {
+  return message.type === MESSAGE_TYPE.ASSISTANT;
+}
+
+/**
+ * Returns true if the message is an error message.
+ * @param message - Chat message.
+ * @returns True if the message is an error message.
+ */
+export function isErrorMessage(message: Message): message is ErrorMessage {
+  return message.type === MESSAGE_TYPE.ERROR;
+}
+
+/**
+ * Returns true if the message is the initial prompt message.
+ * @param message - Chat message.
+ * @returns True if the message is the initial prompt message.
+ */
+export function isInitialPromptMessage(
+  message: Message,
+): message is PromptMessage & { initial: true } {
+  return isPromptMessage(message) && message.initial === true;
+}
+
+/**
+ * Returns true if the message is a prompt message.
+ * @param message - Chat message.
+ * @returns True if the message is a prompt message.
+ */
+export function isPromptMessage(message: Message): message is PromptMessage {
+  return message.type === MESSAGE_TYPE.PROMPT;
+}
+
+/**
+ * Returns true if the message is a user message.
+ * @param message - Chat message.
+ * @returns True if the message is a user message.
+ */
+export function isUserMessage(message: Message): message is UserMessage {
+  return message.type === MESSAGE_TYPE.USER;
+}

package/src/views/ResearchView/state/hooks/UseChatDispatch/hook.ts

@@ -0,0 +1,46 @@
+import { useCallback, useContext } from "react";
+import { setError } from "../../actions/setError/dispatch";
+import { setMessage } from "../../actions/setMessage/dispatch";
+import { setQuery } from "../../actions/setQuery/dispatch";
+import { setStatus } from "../../actions/setStatus/dispatch";
+import { ChatContext } from "../../context";
+import { MessageResponse } from "../../types";
+import { UseChatDispatch } from "./types";
+
+/**
+ * Hook to dispatch Chat actions.
+ * @returns Object containing action dispatch functions.
+ */
+export const useChatDispatch = (): UseChatDispatch => {
+  const { dispatch } = useContext(ChatContext);
+
+  const onSetError = useCallback(
+    (error: string) => {
+      dispatch(setError({ error }));
+    },
+    [dispatch],
+  );
+
+  const onSetMessage = useCallback(
+    <R extends MessageResponse>(response: R) => {
+      dispatch(setMessage({ response }));
+    },
+    [dispatch],
+  );
+
+  const onSetQuery = useCallback(
+    (query: string) => {
+      dispatch(setQuery({ query }));
+    },
+    [dispatch],
+  );
+
+  const onSetStatus = useCallback(
+    (loading: boolean) => {
+      dispatch(setStatus({ loading }));
+    },
+    [dispatch],
+  );
+
+  return { onSetError, onSetMessage, onSetQuery, onSetStatus };
+};

package/src/views/ResearchView/state/hooks/UseChatDispatch/types.ts

@@ -0,0 +1,11 @@
+import { MessageResponse } from "../../types";
+
+/**
+ * Return type for the useChatDispatch hook.
+ */
+export interface UseChatDispatch {
+  onSetError: (error: string) => void;
+  onSetMessage: <R extends MessageResponse>(response: R) => void;
+  onSetQuery: (query: string) => void;
+  onSetStatus: (loading: boolean) => void;
+}

package/src/views/ResearchView/state/hooks/UseChatReducer/hook.ts

@@ -0,0 +1,15 @@
+import { useReducer } from "react";
+import { initializer } from "../../initializer/initializer";
+import { InitialArgs } from "../../initializer/types";
+import { chatReducer } from "../../reducer";
+import { ChatContextValue } from "../../types";
+
+/**
+ * Hook that manages the chat reducer with initial state from config.
+ * @param initialArgs - Initial arguments for the chat state.
+ * @returns Chat context value with dispatch and state.
+ */
+export const useChatReducer = (initialArgs?: InitialArgs): ChatContextValue => {
+  const [state, dispatch] = useReducer(chatReducer, initialArgs, initializer);
+  return { dispatch, state };
+};

package/src/views/ResearchView/state/hooks/UseChatState/hook.ts

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { ChatContext } from "../../context";
+import { ChatContextValue } from "../../types";
+
+/**
+ * Hook to access Chat state.
+ *
+ * @returns Chat state.
+ */
+export const useChatState = (): Pick<ChatContextValue, "state"> => {
+  const { state } = useContext(ChatContext);
+
+  return { state };
+};

package/src/views/ResearchView/state/initializer/initializer.ts

@@ -0,0 +1,23 @@
+import { INITIAL_STATE } from "../constants";
+import { ChatState, MESSAGE_TYPE } from "../types";
+import { InitialArgs } from "./types";
+
+/**
+ * Initializer function for the chat reducer, returning initial state.
+ * @param initialArgs - Initial arguments.
+ * @returns The initialized chat state.
+ */
+export function initializer(initialArgs?: InitialArgs): ChatState {
+  if (!initialArgs) return INITIAL_STATE;
+  return {
+    ...INITIAL_STATE,
+    messages: [
+      {
+        ...initialArgs,
+        createdAt: Date.now(),
+        initial: true,
+        type: MESSAGE_TYPE.PROMPT,
+      },
+    ],
+  };
+}

package/src/views/ResearchView/state/initializer/types.ts

@@ -0,0 +1,3 @@
+import { AiPrompt } from "../../../../common/ai/config/types";
+
+export type InitialArgs = AiPrompt;

package/src/views/ResearchView/state/provider.tsx

@@ -0,0 +1,34 @@
+import { JSX, ReactNode } from "react";
+import { ChatContext } from "./context";
+import { useChatReducer } from "./hooks/UseChatReducer/hook";
+import { InitialArgs } from "./initializer/types";
+import { QueryProvider } from "./query/provider";
+
+/**
+ * Provider for Chat state.
+ * Manages chat state such as query and response data.
+ * Nests QueryProvider to own the fetch lifecycle for query submission.
+ *
+ * @param props - Props.
+ * @param props.children - Children.
+ * @param props.initialArgs - Initial arguments.
+ * @param props.url - URL for the query endpoint.
+ *
+ * @returns A context provider wrapping the given children.
+ */
+export function ChatProvider({
+  children,
+  initialArgs,
+  url,
+}: {
+  children: ReactNode;
+  initialArgs?: InitialArgs;
+  url: string;
+}): JSX.Element {
+  const reducer = useChatReducer(initialArgs);
+  return (
+    <ChatContext.Provider value={reducer}>
+      <QueryProvider url={url}>{children}</QueryProvider>
+    </ChatContext.Provider>
+  );
+}

package/src/views/ResearchView/state/query/context.ts

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+import { QueryContextValue } from "./types";
+
+/**
+ * Context for the query submission provider.
+ */
+export const QueryContext = createContext<QueryContextValue>({
+  onSubmit: () => Promise.resolve(),
+});

package/src/views/ResearchView/state/query/hooks/UseQuery/hook.ts

@@ -0,0 +1,11 @@
+import { useContext } from "react";
+import { QueryContext } from "../../context";
+import { QueryContextValue } from "../../types";
+
+/**
+ * Hook to access query submission from the QueryProvider.
+ * @returns Query context value with onSubmit.
+ */
+export const useQuery = (): QueryContextValue => {
+  return useContext(QueryContext);
+};

package/src/views/ResearchView/state/query/hooks/UseSubmit/hook.ts

@@ -0,0 +1,66 @@
+import { FormEvent, useCallback, useRef } from "react";
+import { fetchResponse } from "../../../../query/fetch";
+import { useChatDispatch } from "../../../hooks/UseChatDispatch/hook";
+import { MessageResponse } from "../../../types";
+import {
+  OnSubmitOptions,
+  OnSubmitPayload,
+  QueryContextValue,
+} from "../../types";
+
+/**
+ * Hook that manages query submission and abort lifecycle.
+ * @param url - The API URL to send queries to.
+ * @returns Object containing the onSubmit handler.
+ */
+export const useSubmit = (url: string): Pick<QueryContextValue, "onSubmit"> => {
+  const abortRef = useRef<AbortController>(null);
+  const dispatch = useChatDispatch();
+
+  const onSubmit = useCallback(
+    async (
+      e: FormEvent<HTMLFormElement>,
+      payload: OnSubmitPayload,
+      options: OnSubmitOptions,
+    ): Promise<void> => {
+      e.preventDefault();
+
+      if (options.status.loading) return;
+
+      const { query } = payload;
+      if (!query) return;
+
+      const form = e.currentTarget;
+
+      // Dispatch query and loading state.
+      dispatch.onSetQuery(query);
+      dispatch.onSetStatus(true);
+      form.reset();
+      options.onMutate?.(form, query);
+
+      // Abort any in-flight request.
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+
+      await fetchResponse(url, query, {
+        controller,
+        onError: (error) => {
+          dispatch.onSetError(error.message);
+          options.onError?.(error);
+        },
+        onSettled: () => {
+          dispatch.onSetStatus(false);
+          options.onSettled?.(form);
+        },
+        onSuccess: (data) => {
+          dispatch.onSetMessage(data as MessageResponse);
+          options.onSuccess?.(data);
+        },
+      });
+    },
+    [dispatch, url],
+  );
+
+  return { onSubmit };
+};

package/src/views/ResearchView/state/query/provider.tsx

@@ -0,0 +1,27 @@
+import { JSX, ReactNode } from "react";
+import { QueryContext } from "./context";
+import { useSubmit } from "./hooks/UseSubmit/hook";
+
+/**
+ * Provider that owns the fetch lifecycle for query submission.
+ * Persists across page navigation so in-flight requests are not aborted.
+ * @param props - Props.
+ * @param props.children - Children.
+ * @param props.url - URL for the query endpoint.
+ * @returns A context provider wrapping the given children.
+ */
+export function QueryProvider({
+  children,
+  url,
+}: {
+  children: ReactNode;
+  url: string;
+}): JSX.Element {
+  const { onSubmit } = useSubmit(url);
+
+  return (
+    <QueryContext.Provider value={{ onSubmit }}>
+      {children}
+    </QueryContext.Provider>
+  );
+}

package/src/views/ResearchView/state/query/types.ts

@@ -0,0 +1,31 @@
+import { FormEvent } from "react";
+import { Status } from "../types";
+
+/**
+ * Options for the onSubmit action.
+ */
+export interface OnSubmitOptions {
+  onError?: (error: Error) => void;
+  onMutate?: (form: HTMLFormElement, query: string) => void;
+  onSettled?: (form: HTMLFormElement) => void;
+  onSuccess?: (data: unknown) => void;
+  status: Status;
+}
+
+/**
+ * Payload for the onSubmit action.
+ */
+export interface OnSubmitPayload {
+  query: string;
+}
+
+/**
+ * Context value for the QueryProvider.
+ */
+export interface QueryContextValue {
+  onSubmit: (
+    e: FormEvent<HTMLFormElement>,
+    payload: OnSubmitPayload,
+    options: OnSubmitOptions,
+  ) => Promise<void>;
+}

package/src/views/ResearchView/state/reducer.ts

@@ -0,0 +1,34 @@
+import { setErrorAction } from "./actions/setError/action";
+import { setMessageAction } from "./actions/setMessage/action";
+import { setQueryAction } from "./actions/setQuery/action";
+import { setStatusAction } from "./actions/setStatus/action";
+import { ChatAction, ChatActionKind } from "./actions/types";
+import { ChatState } from "./types";
+
+/**
+ * Reducer for the Chat state.
+ *
+ * @param state - State.
+ * @param action - Action.
+ * @returns State.
+ */
+export function chatReducer(state: ChatState, action: ChatAction): ChatState {
+  const { payload, type } = action;
+  switch (type) {
+    case ChatActionKind.SetError: {
+      return setErrorAction(state, payload);
+    }
+    case ChatActionKind.SetMessage: {
+      return setMessageAction(state, payload);
+    }
+    case ChatActionKind.SetQuery: {
+      return setQueryAction(state, payload);
+    }
+    case ChatActionKind.SetStatus: {
+      return setStatusAction(state, payload);
+    }
+    default: {
+      return state;
+    }
+  }
+}

package/src/views/ResearchView/state/types.ts

@@ -0,0 +1,149 @@
+import { Dispatch } from "react";
+import { ChatAction } from "./actions/types";
+
+/**
+ * Assistant message in the chat.
+ */
+export interface AssistantMessage<
+  R extends MessageResponse = MessageResponse,
+> extends BaseMessage {
+  response: R;
+  type: MESSAGE_TYPE.ASSISTANT;
+}
+
+/**
+ * Base message type for chat messages.
+ */
+export interface BaseMessage {
+  createdAt: number;
+}
+
+/**
+ * Context value for the Chat state provider.
+ */
+export interface ChatContextValue {
+  dispatch: Dispatch<ChatAction>;
+  state: ChatState;
+}
+
+/**
+ * State for the Chat feature.
+ */
+export interface ChatState {
+  messages: Message[];
+  status: Status;
+}
+
+/**
+ * Error message in the chat.
+ */
+export interface ErrorMessage extends BaseMessage {
+  error: string;
+  type: MESSAGE_TYPE.ERROR;
+}
+
+/**
+ * Intent values for the research API response.
+ */
+export const INTENT = {
+  AUTO: "auto",
+} as const;
+
+/**
+ * Intent type for the research API response.
+ */
+export type Intent = (typeof INTENT)[keyof typeof INTENT] | (string & {});
+
+/**
+ * Union type for messages in the chat.
+ */
+export type Message<R extends MessageResponse = MessageResponse> =
+  | AssistantMessage<R>
+  | ErrorMessage
+  | PromptMessage
+  | UserMessage;
+
+/**
+ * Message types for the chat.
+ */
+export enum MESSAGE_TYPE {
+  ASSISTANT = "ASSISTANT",
+  ERROR = "ERROR",
+  PROMPT = "PROMPT",
+  USER = "USER",
+}
+
+/**
+ * Mention extracted from the user query.
+ */
+export interface Mention {
+  exclude: boolean;
+  facet: string;
+  originalText: string;
+  values: string[];
+}
+
+/**
+ * Response from the research API.
+ */
+export interface MessageResponse {
+  intent: Intent;
+  message: string | null;
+  query: {
+    mentions: Mention[];
+    message: string | null;
+  };
+  timing: {
+    lookupMs: number;
+    pipelineMs: number;
+    totalMs: number;
+  };
+}
+
+/**
+ * Prompt message in the chat, initiated by the system.
+ */
+export interface PromptMessage extends BaseMessage {
+  initial?: boolean;
+  inputPlaceholder?: string;
+  suggestions?: PromptSuggestion[];
+  text: string;
+  type: MESSAGE_TYPE.PROMPT;
+}
+
+/**
+ * Suggestion within a prompt message.
+ */
+export interface PromptSuggestion {
+  label: string;
+  query: string;
+  variant: SuggestionVariant;
+}
+
+/**
+ * Status of the chat interaction, such as loading state.
+ */
+export interface Status {
+  loading: boolean;
+}
+
+/**
+ * Suggestion variant values for rendering suggestions.
+ */
+export const SUGGESTION_VARIANT = {
+  CHIP: "CHIP",
+} as const;
+
+/**
+ * Suggestion variant type.
+ */
+export type SuggestionVariant =
+  (typeof SUGGESTION_VARIANT)[keyof typeof SUGGESTION_VARIANT];
+
+/**
+ * User message in the chat.
+ */
+export interface UserMessage extends BaseMessage {
+  text: string;
+  type: MESSAGE_TYPE.USER;
+}

package/tests/research.assistantMessageUtils.test.ts

@@ -0,0 +1,149 @@
+import {
+  getMappings,
+  getMentions,
+} from "../src/views/ResearchView/assistant/components/Messages/components/AssistantMessage/utils";
+import {
+  AssistantMessage,
+  MESSAGE_TYPE,
+} from "../src/views/ResearchView/state/types";
+
+/**
+ * Creates a mock AssistantMessage with the given mentions.
+ * @param mentions - Array of mention objects.
+ * @returns A mock AssistantMessage.
+ */
+function mockMessage(
+  mentions: AssistantMessage["response"]["query"]["mentions"],
+): AssistantMessage {
+  return {
+    createdAt: Date.now(),
+    response: {
+      intent: "auto",
+      message: null,
+      query: {
+        mentions,
+        message: null,
+      },
+      timing: {
+        lookupMs: 0,
+        pipelineMs: 0,
+        totalMs: 0,
+      },
+    },
+    type: MESSAGE_TYPE.ASSISTANT,
+  };
+}
+
+describe("getMappings", () => {
+  it("returns empty string for empty mentions", () => {
+    expect(getMappings(mockMessage([]))).toBe("");
+  });
+
+  it("formats a single mention", () => {
+    const message = mockMessage([
+      {
+        exclude: false,
+        facet: "disease",
+        originalText: "T2D",
+        values: ["T2D"],
+      },
+    ]);
+    expect(getMappings(message)).toBe("disease: T2D");
+  });
+
+  it("formats a mention with multiple values", () => {
+    const message = mockMessage([
+      {
+        exclude: false,
+        facet: "disease",
+        originalText: "cancer",
+        values: ["lung cancer", "breast cancer"],
+      },
+    ]);
+    expect(getMappings(message)).toBe("disease: lung cancer, breast cancer");
+  });
+
+  it("groups mentions by facet", () => {
+    const message = mockMessage([
+      {
+        exclude: false,
+        facet: "disease",
+        originalText: "T2D",
+        values: ["T2D"],
+      },
+      {
+        exclude: false,
+        facet: "disease",
+        originalText: "T1D",
+        values: ["T1D"],
+      },
+    ]);
+    expect(getMappings(message)).toBe("disease: T2D, T1D");
+  });
+
+  it("separates different facets with slashes", () => {
+    const message = mockMessage([
+      {
+        exclude: false,
+        facet: "disease",
+        originalText: "T2D",
+        values: ["T2D"],
+      },
+      {
+        exclude: false,
+        facet: "data_type",
+        originalText: "WGS",
+        values: ["WGS"],
+      },
+    ]);
+    expect(getMappings(message)).toBe("disease: T2D / data_type: WGS");
+  });
+
+  it("marks excluded facets", () => {
+    const message = mockMessage([
+      {
+        exclude: true,
+        facet: "disease",
+        originalText: "T2D",
+        values: ["T2D"],
+      },
+    ]);
+    expect(getMappings(message)).toBe("disease (exclude): T2D");
+  });
+});
+
+describe("getMentions", () => {
+  it("returns empty string for empty mentions", () => {
+    expect(getMentions(mockMessage([]))).toBe("");
+  });
+
+  it("returns original text for a single mention", () => {
+    const message = mockMessage([
+      {
+        exclude: false,
+        facet: "disease",
+        originalText: "T2D",
+        values: ["T2D"],
+      },
+    ]);
+    expect(getMentions(message)).toBe("T2D");
+  });
+
+  it("joins multiple mentions with commas", () => {
+    const message = mockMessage([
+      {
+        exclude: false,
+        facet: "disease",
+        originalText: "T2D",
+        values: ["T2D"],
+      },
+      {
+        exclude: false,
+        facet: "data_type",
+        originalText: "WGS",
+        values: ["WGS"],
+      },
+    ]);
+    expect(getMentions(message)).toBe("T2D, WGS");
+  });
+});