@envive-ai/react-toolkit-v3 0.3.5

package/src/components/PromptCarousel/components/CarouselContentWithBlockScroll.tsx

@@ -0,0 +1,83 @@
+import { Stack } from '../../Stack';
+import { BlockScrollContainer } from './BlockScrollContainer';
+import { RepetitionNumberSuffix } from '../types/types';
+
+export interface CarouselContentWithBlockScrollProps {
+  visibleButtonsFirstRow: string[];
+  visibleButtonsSecondRow: string[];
+  shouldShowTwoRows: boolean;
+  renderButton: (
+    text: string,
+    index: number,
+    repetitionNumber?: `${RepetitionNumberSuffix}`,
+  ) => React.ReactNode;
+  isAnimated: boolean;
+  isAnimationStopped: boolean;
+  blockScrollRef: React.RefObject<HTMLDivElement>;
+  blockFirstRowStackRef: React.RefObject<HTMLDivElement>;
+}
+
+export const CarouselContentWithBlockScroll = ({
+  visibleButtonsFirstRow,
+  visibleButtonsSecondRow,
+  shouldShowTwoRows,
+  renderButton,
+  isAnimated,
+  isAnimationStopped,
+  blockScrollRef,
+  blockFirstRowStackRef,
+}: CarouselContentWithBlockScrollProps) => {
+  const showRepetitions = isAnimated && isAnimationStopped;
+
+  const renderRowButtons = (buttons: string[], startIndex: number) => (
+    <>
+      {buttons.map((text, index) => renderButton(text, startIndex + index))}
+      {showRepetitions &&
+        buttons.map((text, index) =>
+          renderButton(text, startIndex + index, RepetitionNumberSuffix.TWO),
+        )}
+      {showRepetitions &&
+        buttons.map((text, index) =>
+          renderButton(text, startIndex + index, RepetitionNumberSuffix.THREE),
+        )}
+    </>
+  );
+
+  return (
+    <BlockScrollContainer
+      scrollRef={blockScrollRef}
+      aria-label="Scrollable prompt buttons"
+    >
+      <Stack
+        direction="column"
+        gap="2"
+        className="envive-tw-w-max"
+      >
+        <div
+          ref={blockFirstRowStackRef}
+          role={shouldShowTwoRows ? 'group' : undefined}
+          aria-label={shouldShowTwoRows ? 'First row of prompt buttons' : undefined}
+        >
+          <Stack
+            direction="row"
+            gap="2"
+            className="envive-tw-whitespace-nowrap"
+          >
+            {renderRowButtons(visibleButtonsFirstRow, 0)}
+          </Stack>
+        </div>
+
+        {shouldShowTwoRows && visibleButtonsSecondRow.length > 0 && (
+          <Stack
+            direction="row"
+            gap="2"
+            className="envive-tw-whitespace-nowrap"
+            aria-label="Second row of prompt buttons"
+          >
+            {renderRowButtons(visibleButtonsSecondRow, visibleButtonsFirstRow.length)}
+          </Stack>
+        )}
+      </Stack>
+    </BlockScrollContainer>
+  );
+};

package/src/components/PromptCarousel/components/CarouselContentWithRowScroll.tsx

@@ -0,0 +1,71 @@
+import { Stack } from '../../Stack';
+import { ButtonContainerRow } from './ButtonContainerRow';
+import { RepetitionNumberSuffix } from '../types/types';
+
+export interface CarouselContentWithRowScrollProps {
+  visibleButtonsFirstRow: string[];
+  visibleButtonsSecondRow: string[];
+  shouldShowTwoRows: boolean;
+  renderButton: (
+    text: string,
+    index: number,
+    repetitionNumber?: `${RepetitionNumberSuffix}`,
+  ) => React.ReactNode;
+  isAnimated: boolean;
+  isAnimationStopped: boolean;
+  firstRowScrollRef: React.RefObject<HTMLDivElement>;
+  firstRowStackRef: React.RefObject<HTMLDivElement>;
+  secondRowScrollRef: React.RefObject<HTMLDivElement>;
+}
+
+export const CarouselContentWithRowScroll = ({
+  visibleButtonsFirstRow,
+  visibleButtonsSecondRow,
+  shouldShowTwoRows,
+  isAnimated,
+  isAnimationStopped,
+  renderButton,
+  firstRowScrollRef,
+  firstRowStackRef,
+  secondRowScrollRef,
+}: CarouselContentWithRowScrollProps) => {
+  const showRepetitions = isAnimated && !isAnimationStopped;
+
+  const renderRowButtons = (buttons: string[], startIndex: number) => (
+    <>
+      {buttons.map((text, index) => renderButton(text, startIndex + index))}
+      {showRepetitions &&
+        buttons.map((text, index) =>
+          renderButton(text, startIndex + index, RepetitionNumberSuffix.TWO),
+        )}
+      {showRepetitions &&
+        buttons.map((text, index) =>
+          renderButton(text, startIndex + index, RepetitionNumberSuffix.THREE),
+        )}
+    </>
+  );
+
+  return (
+    <Stack
+      direction="column"
+      gap="2"
+    >
+      <ButtonContainerRow
+        scrollRef={firstRowScrollRef}
+        stackRef={firstRowStackRef}
+        aria-label={shouldShowTwoRows ? 'First row of prompt buttons' : undefined}
+      >
+        {renderRowButtons(visibleButtonsFirstRow, 0)}
+      </ButtonContainerRow>
+
+      {shouldShowTwoRows && (
+        <ButtonContainerRow
+          scrollRef={secondRowScrollRef}
+          aria-label="Second row of prompt buttons"
+        >
+          {renderRowButtons(visibleButtonsSecondRow, visibleButtonsFirstRow.length)}
+        </ButtonContainerRow>
+      )}
+    </Stack>
+  );
+};

package/src/components/PromptCarousel/components/index.ts

@@ -0,0 +1,9 @@
+import { CarouselContentWithRowScroll } from './CarouselContentWithRowScroll';
+import { CarouselContentWithBlockScroll } from './CarouselContentWithBlockScroll';
+import { ButtonContainerRow } from './ButtonContainerRow';
+
+export const PromptCarouselComponents = {
+  CarouselContentWithRowScroll,
+  CarouselContentWithBlockScroll,
+  ButtonContainerRow,
+};

package/src/components/PromptCarousel/hooks/index.ts

@@ -0,0 +1,5 @@
+export { useHorizontalScrollAnimation } from './useHorizontalScrollAnimation';
+export { useButtonScrollPosition } from './useButtonScrollPosition';
+export { useCarouselRefs } from './useCarouselRefs';
+export { useCarouselButtons } from './useCarouselButtons';
+export { useCarouselAnimation } from './useCarouselAnimation';

package/src/components/PromptCarousel/hooks/useButtonScrollPosition.ts

@@ -0,0 +1,128 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { RepetitionNumberSuffix } from '../types/types';
+
+const getElementId = (element: Element | null): string | null => {
+  if (!element) return null;
+  return element.id?.trim() || null;
+};
+
+export function useButtonScrollPosition(
+  firstRowScrollRef: React.RefObject<HTMLDivElement>,
+  blockScrollRef: React.RefObject<HTMLDivElement>,
+  shouldUseRowScroll: boolean,
+) {
+  const savedButtonIdRef = useRef<string | null>(null);
+  const savedButtonPositionRef = useRef<number | null>(null);
+
+  const captureButtonUnderMouse = useCallback(
+    (mouseX: number, mouseY: number) => {
+      const container = firstRowScrollRef.current;
+      if (!container) return;
+
+      const containerRect = container.getBoundingClientRect();
+
+      const elementUnderMouse = document.elementFromPoint(mouseX, mouseY);
+      const targetButtonId = getElementId(elementUnderMouse);
+
+      let closestButton: HTMLElement | null = null;
+
+      if (targetButtonId) {
+        const buttonById = document.querySelector(`#${CSS.escape(targetButtonId)}`) as HTMLElement;
+        if (
+          buttonById &&
+          (elementUnderMouse === buttonById || buttonById.contains(elementUnderMouse as Node))
+        ) {
+          closestButton = buttonById;
+        }
+      }
+
+      if (!closestButton) {
+        const buttons = Array.from(container.querySelectorAll('button')) as HTMLElement[];
+        let closestDistance = Infinity;
+
+        for (const button of buttons) {
+          const buttonRect = button.getBoundingClientRect();
+
+          if (
+            mouseX >= buttonRect.left &&
+            mouseX <= buttonRect.right &&
+            mouseY >= buttonRect.top &&
+            mouseY <= buttonRect.bottom
+          ) {
+            closestButton = button;
+            break;
+          }
+
+          const buttonCenterX = buttonRect.left + buttonRect.width / 2;
+          const buttonCenterY = buttonRect.top + buttonRect.height / 2;
+          const distance = Math.sqrt((mouseX - buttonCenterX) ** 2 + (mouseY - buttonCenterY) ** 2);
+
+          if (distance < closestDistance) {
+            closestDistance = distance;
+            closestButton = button;
+          }
+        }
+      }
+
+      if (closestButton) {
+        const id = getElementId(closestButton);
+        if (id) {
+          savedButtonIdRef.current = id;
+          const buttonRect = closestButton.getBoundingClientRect();
+          savedButtonPositionRef.current = buttonRect.left - containerRect.left;
+        }
+      }
+    },
+    [firstRowScrollRef],
+  );
+
+  useEffect(() => {
+    if (
+      shouldUseRowScroll ||
+      !blockScrollRef.current ||
+      !savedButtonIdRef.current ||
+      savedButtonPositionRef.current === null
+    ) {
+      return;
+    }
+
+    const container = blockScrollRef.current;
+    const targetId = savedButtonIdRef.current.trim();
+    const targetPosition = savedButtonPositionRef.current;
+
+    const getScrollId = (id: string) => {
+      if (id.endsWith(RepetitionNumberSuffix.TWO)) {
+        return id;
+      }
+
+      if (id.endsWith(RepetitionNumberSuffix.THREE)) {
+        return `${id.slice(0, -2)}${RepetitionNumberSuffix.TWO}`;
+      }
+
+      return `${id}${RepetitionNumberSuffix.TWO}`;
+    };
+
+    const applyScroll = () => {
+      const finalId = getScrollId(targetId);
+      const targetButton = container.querySelector(`#${CSS.escape(`${finalId}`)}`) as HTMLElement;
+      const scrollableContent = container.firstElementChild as HTMLElement;
+
+      if (!targetButton || !scrollableContent) return;
+
+      const contentRect = scrollableContent.getBoundingClientRect();
+      const buttonRect = targetButton.getBoundingClientRect();
+      const buttonPositionInContent = buttonRect.left - contentRect.left + container.scrollLeft;
+      const newScrollLeft = buttonPositionInContent - targetPosition;
+
+      container.scrollLeft = Math.max(0, newScrollLeft);
+    };
+
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        requestAnimationFrame(applyScroll);
+      });
+    });
+  }, [shouldUseRowScroll, blockScrollRef]);
+
+  return { captureButtonUnderMouse };
+}

package/src/components/PromptCarousel/hooks/useCarouselAnimation.ts

@@ -0,0 +1,47 @@
+import { useCallback, useState } from 'react';
+import { AnimationSpeed } from '../types/types';
+import { useButtonScrollPosition } from './useButtonScrollPosition';
+import { useHorizontalScrollAnimation } from './useHorizontalScrollAnimation';
+
+interface UseCarouselAnimationProps {
+  firstRowScrollRef: React.RefObject<HTMLDivElement>;
+  blockScrollRef: React.RefObject<HTMLDivElement>;
+  scrollRefs: React.RefObject<HTMLDivElement>[];
+  animationSpeed: `${AnimationSpeed}`;
+  isAnimated: boolean;
+}
+
+export const useCarouselAnimation = ({
+  firstRowScrollRef,
+  blockScrollRef,
+  scrollRefs,
+  animationSpeed,
+  isAnimated,
+}: UseCarouselAnimationProps) => {
+  const [isAnimationStopped, setIsAnimationStopped] = useState(false);
+  const shouldUseRowScroll = isAnimated && !isAnimationStopped;
+
+  const { captureButtonUnderMouse } = useButtonScrollPosition(
+    firstRowScrollRef,
+    blockScrollRef,
+    shouldUseRowScroll,
+  );
+
+  const onStopAll = useCallback(
+    (mouseX?: number, mouseY?: number) => {
+      if (mouseX !== undefined && mouseY !== undefined) {
+        captureButtonUnderMouse(mouseX, mouseY);
+      }
+      setIsAnimationStopped(true);
+    },
+    [captureButtonUnderMouse],
+  );
+
+  useHorizontalScrollAnimation(
+    scrollRefs,
+    onStopAll,
+    shouldUseRowScroll ? animationSpeed : AnimationSpeed.NONE,
+  );
+
+  return { isAnimationStopped, shouldUseRowScroll };
+};

package/src/components/PromptCarousel/hooks/useCarouselButtons.ts

@@ -0,0 +1,35 @@
+import { useMemo } from 'react';
+
+interface UseCarouselButtonsProps {
+  promptButtonTexts: string[];
+  shouldShowTwoRows: boolean;
+}
+
+export const useCarouselButtons = ({
+  promptButtonTexts,
+  shouldShowTwoRows,
+}: UseCarouselButtonsProps) => {
+  const visibleButtonsFirstRow = useMemo(() => {
+    if (!Array.isArray(promptButtonTexts)) {
+      return [];
+    }
+    return shouldShowTwoRows
+      ? promptButtonTexts.slice(0, Math.ceil((promptButtonTexts.length + 1) / 2))
+      : promptButtonTexts;
+  }, [promptButtonTexts, shouldShowTwoRows]);
+
+  const visibleButtonsSecondRow = useMemo(() => {
+    if (!Array.isArray(promptButtonTexts)) {
+      return [];
+    }
+    return promptButtonTexts.slice(
+      Math.ceil((promptButtonTexts.length + 1) / 2),
+      promptButtonTexts.length,
+    );
+  }, [promptButtonTexts]);
+
+  return {
+    visibleButtonsFirstRow,
+    visibleButtonsSecondRow,
+  };
+};

package/src/components/PromptCarousel/hooks/useCarouselRefs.ts

@@ -0,0 +1,26 @@
+import { useRef } from 'react';
+
+interface UseCarouselRefsProps {
+  shouldShowTwoRows: boolean;
+}
+
+export const useCarouselRefs = ({ shouldShowTwoRows }: UseCarouselRefsProps) => {
+  const firstRowScrollRef = useRef<HTMLDivElement>(null);
+  const firstRowStackRef = useRef<HTMLDivElement>(null);
+  const secondRowScrollRef = useRef<HTMLDivElement>(null);
+  const blockScrollRef = useRef<HTMLDivElement>(null);
+  const blockFirstRowStackRef = useRef<HTMLDivElement>(null);
+
+  const scrollRefs = shouldShowTwoRows
+    ? [firstRowScrollRef, secondRowScrollRef]
+    : [firstRowScrollRef];
+
+  return {
+    firstRowScrollRef,
+    firstRowStackRef,
+    secondRowScrollRef,
+    blockScrollRef,
+    blockFirstRowStackRef,
+    scrollRefs,
+  };
+};

package/src/components/PromptCarousel/hooks/useGetScrollProperties.ts

@@ -0,0 +1,14 @@
+export const useGetScrollProperties = () => {
+  const scrollStyle = {
+    scrollbarWidth: 'none',
+    msOverflowStyle: 'none',
+  } as const;
+
+  const scrollClasses = [
+    'envive-tw-overflow-x-scroll',
+    'envive-tw-overflow-y-hidden',
+    '[&::-webkit-scrollbar]:hidden',
+  ] as const;
+
+  return { scrollClasses, scrollStyle };
+};

package/src/components/PromptCarousel/hooks/useHorizontalScrollAnimation.ts

@@ -0,0 +1,103 @@
+import { useEffect, useRef } from 'react';
+import { AnimationSpeed } from '../types/types';
+
+export function useHorizontalScrollAnimation(
+  scrollContainerRefs: React.RefObject<HTMLDivElement>[],
+  onStopAll: (mouseX?: number, mouseY?: number) => void,
+  animationSpeed: `${AnimationSpeed}` = 'none',
+) {
+  const animationRefs = useRef<(number | null)[]>([]);
+  const lastTimestampRefs = useRef<(number | null)[]>([]);
+  const accumulatedScrollRefs = useRef<number[]>([]);
+  const isStoppedRef = useRef(false);
+
+  useEffect(() => {
+    if (animationSpeed === AnimationSpeed.NONE) {
+      return undefined;
+    }
+
+    const containers = scrollContainerRefs
+      .map(ref => ref.current)
+      .filter((container): container is HTMLDivElement => container !== null);
+
+    if (containers.length === 0) {
+      return undefined;
+    }
+
+    animationRefs.current = containers.map(() => null);
+    lastTimestampRefs.current = containers.map(() => null);
+    accumulatedScrollRefs.current = containers.map(() => 0);
+
+    const PIXELS_PER_SECOND = animationSpeed === AnimationSpeed.FAST ? 60 : 30;
+
+    const cancelAllAnimations = () => {
+      animationRefs.current.forEach(rafId => {
+        if (rafId !== null) {
+          cancelAnimationFrame(rafId);
+        }
+      });
+    };
+
+    const createAnimationLoop = (index: number) => {
+      const step = (timestamp: number) => {
+        if (isStoppedRef.current) return;
+
+        const container = containers[index];
+        if (!container || container.scrollWidth <= container.clientWidth) {
+          animationRefs.current[index] = requestAnimationFrame(step);
+          return;
+        }
+
+        if (lastTimestampRefs.current[index] === null) {
+          lastTimestampRefs.current[index] = timestamp;
+        }
+
+        const delta = timestamp - lastTimestampRefs.current[index]!;
+        lastTimestampRefs.current[index] = timestamp;
+        accumulatedScrollRefs.current[index] += PIXELS_PER_SECOND * (delta / 1000);
+
+        const pixelsToScroll = Math.floor(accumulatedScrollRefs.current[index]);
+        if (pixelsToScroll > 0) {
+          const newScrollLeft = container.scrollLeft + pixelsToScroll;
+          const maxScroll = container.scrollWidth - container.clientWidth;
+
+          if (Math.ceil(newScrollLeft) >= maxScroll) {
+            container.scrollLeft = 0;
+            accumulatedScrollRefs.current[index] = 0;
+          } else {
+            container.scrollLeft = newScrollLeft;
+            accumulatedScrollRefs.current[index] -= pixelsToScroll;
+          }
+        }
+
+        if (!isStoppedRef.current) {
+          animationRefs.current[index] = requestAnimationFrame(step);
+        }
+      };
+
+      return step;
+    };
+
+    containers.forEach((container, index) => {
+      animationRefs.current[index] = requestAnimationFrame(createAnimationLoop(index));
+    });
+
+    const handleMouseEnter = (event: MouseEvent) => {
+      isStoppedRef.current = true;
+      onStopAll(event.clientX, event.clientY);
+      cancelAllAnimations();
+    };
+
+    containers.forEach(container => {
+      container.addEventListener('mouseenter', handleMouseEnter);
+    });
+
+    return () => {
+      isStoppedRef.current = true;
+      cancelAllAnimations();
+      containers.forEach(container => {
+        container.removeEventListener('mouseenter', handleMouseEnter);
+      });
+    };
+  }, [animationSpeed, scrollContainerRefs, onStopAll]);
+}

package/src/components/PromptCarousel/index.ts

@@ -0,0 +1,3 @@
+export { PromptCarousel } from './PromptCarousel';
+export type { PromptCarouselProps } from './types/types';
+export { AnimationSpeed, PromptCarouselRows } from './types/types';

package/src/components/PromptCarousel/types/types.ts

@@ -0,0 +1,101 @@
+import { Theme } from '../../../../tokens/theme/theme';
+import { PromptButtonVariant } from '../../PromptButton/types';
+
+/**
+ * Props for the PromptCarousel component.
+ *
+ * @interface PromptCarouselProps
+ */
+export interface PromptCarouselProps {
+  /**
+   * Unique identifier for the carousel component.
+   */
+  id?: string;
+  /**
+   * Test identifier for automated testing purposes.
+   */
+  testId?: string;
+  /**
+   * Additional CSS class names to apply to the carousel container.
+   */
+  className?: string;
+  /**
+   * Inline styles to apply to the carousel container.
+   */
+  style?: React.CSSProperties;
+  /**
+   * Whether the carousel is in a loading state.
+   * @default false
+   */
+  isLoading?: boolean;
+  /**
+   * Array of text labels for the prompt buttons in the carousel.
+   */
+  promptButtonTexts: string[];
+  /**
+   * Visual variant/style of the prompt buttons.
+   * @default PromptButtonVariant.LIGHT
+   */
+  promptButtonType?: PromptButtonVariant;
+  /**
+   * Whether the first button should be rendered with bold text.
+   * @default false
+   */
+  boldFirstButton?: boolean;
+  /**
+   * Visual theme of the prompt carousel.
+   * @default Theme.GLOBAL_CUSTOM
+   */
+  theme?: Theme;
+  /**
+   * Callback function invoked when a prompt button is clicked.
+   * @param text - The text of the clicked button.
+   */
+  handleButtonClick?: (text: string) => void;
+  /**
+   * Number of rows to display in the carousel.
+   * Controls the layout behavior (always one row, always two rows, or responsive).
+   * @default PromptCarouselRows.ALWAYS_ONE
+   */
+  promptCarouselRows?: `${PromptCarouselRows}`;
+  /**
+   * Animation speed for carousel transitions.
+   * Controls how fast or slow the animations play, or disables them entirely.
+   * @default AnimationSpeed.NONE
+   */
+  animationSpeed?: `${AnimationSpeed}`;
+  /**
+   * Accessibility: Provides an accessible name for the carousel container.
+   */
+  'aria-label'?: string;
+  /**
+   * Accessibility: Identifies the element(s) that label the carousel container.
+   */
+  'aria-labelledby'?: string;
+  /**
+   * Accessibility: Identifies the element(s) that describe the carousel container.
+   */
+  'aria-describedby'?: string;
+  /**
+   * Accessibility: Defines the role of the carousel container element.
+   * @default 'region'
+   */
+  role?: string;
+}
+
+export enum AnimationSpeed {
+  FAST = 'fast',
+  SLOW = 'slow',
+  NONE = 'none',
+}
+
+export enum PromptCarouselRows {
+  ALWAYS_ONE = 'alwaysOne',
+  ALWAYS_TWO = 'alwaysTwo',
+  TWO_ON_MOBILE_ONE_ON_DESKTOP = 'twoOnMobile-OneOnDesktop',
+}
+
+export enum RepetitionNumberSuffix {
+  TWO = '-2',
+  THREE = '-3',
+}

package/src/components/PromptCarousel/utils/functions.ts

@@ -0,0 +1,19 @@
+import { AnimationSpeed, PromptCarouselRows } from '../types/types';
+
+export const isAnimated = (animationSpeed: `${AnimationSpeed}`) => {
+  return animationSpeed !== AnimationSpeed.NONE;
+};
+
+export const shouldShowTwoRows = (
+  promptCarouselRows: `${PromptCarouselRows}`,
+  isMobile: boolean,
+) => {
+  return (
+    promptCarouselRows === PromptCarouselRows.ALWAYS_TWO ||
+    (promptCarouselRows === PromptCarouselRows.TWO_ON_MOBILE_ONE_ON_DESKTOP && isMobile)
+  );
+};
+
+export function removeSpaces(value: string): string {
+  return value.replace(/\s+/g, '');
+}