@envive-ai/react-toolkit-v3 0.3.5

package/src/components/TextField/hooks/useGetContainerProperties.ts

@@ -0,0 +1,73 @@
+import { useMemo } from 'react';
+import { Theme } from '../../../../tokens/theme/theme';
+
+export type UseGetContainerPropertiesProps = {
+  theme: Theme;
+};
+
+export type ContainerProperties = {
+  containerLayoutClasses: string;
+  containerDefaultClasses: string;
+  containerBorderClasses: string;
+  containerBorderActiveClasses: string;
+  containerFocusClasses: string;
+  containerHoverClasses: string;
+  containerDisabledClasses: string;
+};
+
+export const useGetContainerProperties = ({
+  theme,
+}: UseGetContainerPropertiesProps): ContainerProperties => {
+  const containerClasses = useMemo(() => {
+    const containerClassesMap: Record<Theme, ContainerProperties> = {
+      [Theme.STANDARD]: {
+        containerLayoutClasses:
+          'envive-tw-flex envive-tw-min-w-[358px] envive-tw-h-[40px] envive-tw-py-2 envive-tw-px-4 envive-tw-justify-between envive-tw-items-center envive-tw-flex-shrink-0',
+        containerDefaultClasses:
+          'envive-tw-border envive-tw-border-solid envive-tw-bg-background-light envive-tw-rounded-global-custom',
+        containerBorderClasses: 'envive-tw-border-border-light',
+        containerBorderActiveClasses: 'envive-tw-border-border-dark',
+        containerFocusClasses: 'envive-tw-border-border-dark',
+        containerHoverClasses: 'hover:envive-tw-border-border-dark',
+        containerDisabledClasses: 'envive-tw-opacity-50',
+      },
+      [Theme.MODERN]: {
+        containerLayoutClasses:
+          'envive-tw-flex envive-tw-min-w-[358px] envive-tw-h-[40px] envive-tw-py-2 envive-tw-pr-2 envive-tw-pl-4 envive-tw-justify-between envive-tw-items-center envive-tw-flex-shrink-0',
+        containerDefaultClasses:
+          'envive-tw-border envive-tw-border-solid envive-tw-bg-background-light envive-tw-rounded-[4px]',
+        containerBorderClasses: 'envive-tw-border-border-light',
+        containerBorderActiveClasses: 'envive-tw-border-border-dark',
+        containerFocusClasses: 'envive-tw-border-border-dark',
+        containerHoverClasses: 'hover:envive-tw-border-border-dark',
+        containerDisabledClasses: 'envive-tw-opacity-50',
+      },
+      [Theme.MINIMAL]: {
+        containerLayoutClasses:
+          'envive-tw-flex envive-tw-min-w-[358px] envive-tw-h-[40px] envive-tw-py-2 envive-tw-pr-2 envive-tw-justify-between envive-tw-items-center envive-tw-flex-shrink-0',
+        containerDefaultClasses:
+          'envive-tw-border-b envive-tw-border-solid envive-tw-bg-background-light',
+        containerBorderClasses: 'envive-tw-border-b-border-medium',
+        containerBorderActiveClasses: 'envive-tw-border-b-border-dark',
+        containerFocusClasses: 'envive-tw-border-b-border-dark',
+        containerHoverClasses: 'hover:envive-tw-border-b-border-dark',
+        containerDisabledClasses: 'envive-tw-opacity-50',
+      },
+      [Theme.GLOBAL_CUSTOM]: {
+        containerLayoutClasses:
+          'envive-tw-flex envive-tw-min-w-[358px] envive-tw-h-[40px] envive-tw-py-2 envive-tw-px-4 envive-tw-justify-between envive-tw-items-center envive-tw-flex-shrink-0',
+        containerDefaultClasses:
+          'envive-tw-border envive-tw-border-solid envive-tw-bg-background-light envive-tw-rounded-global-custom',
+        containerBorderClasses: 'envive-tw-border-border-light',
+        containerBorderActiveClasses: 'envive-tw-border-border-dark',
+        containerFocusClasses: 'envive-tw-border-border-dark',
+        containerHoverClasses: 'hover:envive-tw-border-border-dark',
+        containerDisabledClasses: 'envive-tw-opacity-50',
+      },
+    };
+
+    return containerClassesMap[theme] ?? containerClassesMap[Theme.STANDARD];
+  }, [theme]);
+
+  return containerClasses;
+};

package/src/components/TextField/hooks/useGetSkeletonProperties.ts

@@ -0,0 +1,11 @@
+import { useMemo } from 'react';
+
+export const useGetSkeletonProperties = (isLoading?: boolean) => {
+  const skeletonClass = useMemo(() => {
+    if (!isLoading) return undefined;
+
+    return 'envive-tw-animate-pulse';
+  }, [isLoading]);
+
+  return { skeletonClass };
+};

package/src/components/TextField/hooks/useSendIconHandlers.ts

@@ -0,0 +1,30 @@
+import { useCallback } from 'react';
+
+/**
+ * Manages the event handlers for SendIcon component.
+ * Handles both click and keyboard events.
+ */
+export const useSendIconHandlers = (disabled: boolean, hasValue: boolean, onClick?: () => void) => {
+  const handleClick = useCallback(() => {
+    if (!disabled && onClick && hasValue) {
+      onClick();
+    }
+  }, [disabled, onClick, hasValue]);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLButtonElement>) => {
+      if (event.key === 'Enter' || event.key === ' ') {
+        event.preventDefault();
+        if (!disabled && onClick && hasValue) {
+          onClick();
+        }
+      }
+    },
+    [disabled, onClick, hasValue],
+  );
+
+  return {
+    handleClick,
+    handleKeyDown,
+  };
+};

package/src/components/TextField/hooks/useTextFieldFocus.ts

@@ -0,0 +1,22 @@
+import { useCallback, useState } from 'react';
+
+/**
+ * Manages the focus state for TextField component.
+ */
+export const useTextFieldFocus = () => {
+  const [isFocused, setIsFocused] = useState(false);
+
+  const handleFocus = useCallback(() => {
+    setIsFocused(true);
+  }, []);
+
+  const handleBlur = useCallback(() => {
+    setIsFocused(false);
+  }, []);
+
+  return {
+    isFocused,
+    handleFocus,
+    handleBlur,
+  };
+};

package/src/components/TextField/hooks/useTextFieldSubmit.ts

@@ -0,0 +1,36 @@
+import { useCallback } from 'react';
+
+/**
+ * Manages the submit logic for TextField component.
+ * Handles both Enter key press and button click submissions.
+ */
+export const useTextFieldSubmit = (
+  onSubmit: ((value: string) => void) | undefined,
+  hasValue: boolean,
+  disabled: boolean,
+  isLoading: boolean,
+  currentValue: string,
+  resetValue: () => void,
+) => {
+  const handleSubmit = useCallback(() => {
+    if (onSubmit && hasValue && !disabled && !isLoading) {
+      onSubmit(currentValue);
+      resetValue();
+    }
+  }, [onSubmit, hasValue, disabled, isLoading, currentValue, resetValue]);
+
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === 'Enter' && hasValue && !disabled && !isLoading) {
+        event.preventDefault();
+        handleSubmit();
+      }
+    },
+    [hasValue, disabled, isLoading, handleSubmit],
+  );
+
+  return {
+    handleSubmit,
+    handleKeyDown,
+  };
+};

package/src/components/TextField/hooks/useTextFieldValue.ts

@@ -0,0 +1,42 @@
+import { useCallback, useState } from 'react';
+
+/**
+ * Manages the value state for TextField component.
+ * Handles both controlled and uncontrolled modes.
+ */
+export const useTextFieldValue = (
+  controlledValue: string | undefined,
+  onChange?: (value: string) => void,
+) => {
+  const [internalValue, setInternalValue] = useState('');
+
+  const isControlled = controlledValue !== undefined;
+  const currentValue = isControlled ? controlledValue : internalValue;
+  const hasValue = currentValue.trim().length > 0;
+
+  const handleChange = useCallback(
+    (newValue: string) => {
+      if (!isControlled) {
+        setInternalValue(newValue);
+      }
+      if (onChange) {
+        onChange(newValue);
+      }
+    },
+    [isControlled, onChange],
+  );
+
+  const resetValue = useCallback(() => {
+    if (!isControlled) {
+      setInternalValue('');
+    }
+  }, [isControlled]);
+
+  return {
+    currentValue,
+    hasValue,
+    handleChange,
+    isControlled,
+    resetValue,
+  };
+};

package/src/components/TextField/index.ts

@@ -0,0 +1,2 @@
+export { TextField } from './TextField';
+export type { TextFieldProps } from './types';

package/src/components/TextField/types/index.ts

@@ -0,0 +1,45 @@
+import { Theme } from '../../../../tokens/theme/theme';
+
+export type TextFieldProps = {
+  /**
+   * Visual theme of the text field.
+   * @default Theme.GLOBAL_CUSTOM (uses CSS variable --envive-global-custom-theme)
+   */
+  theme?: Theme;
+  /**
+   * Placeholder text displayed when the input is empty.
+   */
+  placeholder: string;
+  /**
+   * Controlled value of the input. If not provided, the component manages its own state.
+   */
+  value?: string;
+  /**
+   * Callback function invoked when the input value changes.
+   */
+  onChange?: (value: string) => void;
+  /**
+   * Callback function invoked when the form is submitted (Enter key or icon click).
+   */
+  onSubmit?: (value: string) => void;
+  disabled?: boolean;
+  ariaLabel?: string;
+  id?: string;
+  /**
+   * Adds a `data-testid` attribute for testing utilities.
+   */
+  testId?: string;
+  /**
+   * Additional class names appended to the computed classes.
+   */
+  className?: string;
+  /**
+   * Inline styles forwarded to the rendered element.
+   */
+  style?: React.CSSProperties;
+  /**
+   * Shows a loading skeleton state when true.
+   * @default false
+   */
+  isLoading?: boolean;
+};

package/src/components/TextField/utils/createInputChangeHandler.ts

@@ -0,0 +1,11 @@
+/**
+ * Creates a change handler for the input element.
+ * Only calls onChange when the input is enabled.
+ */
+export const createInputChangeHandler = (disabled: boolean, onChange?: (value: string) => void) => {
+  return (event: React.ChangeEvent<HTMLInputElement>) => {
+    if (!disabled && onChange) {
+      onChange(event.target.value);
+    }
+  };
+};

package/src/components/TextField/utils/getIconColor.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns the appropriate icon color based on the hasValue and disabled state.
+ */
+export const getIconColor = (hasValue: boolean, disabled: boolean): string => {
+  if (disabled || !hasValue) {
+    return 'var(--envive-colors-border-medium)';
+  }
+  return 'var(--envive-colors-text-primary)';
+};

package/src/components/TextField/utils/getInputClasses.ts

@@ -0,0 +1,33 @@
+import { Theme } from '../../../../tokens/theme/theme';
+
+type InputClasses = {
+  inputClasses: string;
+};
+
+/**
+ * Returns input CSS classes specific to each TextField theme.
+ */
+export const getInputClasses = (theme: Theme): InputClasses => {
+  switch (theme) {
+    case Theme.STANDARD:
+      return {
+        inputClasses:
+          'envive-tw-flex-1 envive-tw-bg-transparent envive-tw-border-0 envive-tw-outline-none envive-tw-text-text-primary envive-tw-text-b3-rg',
+      };
+
+    case Theme.MODERN:
+      return {
+        inputClasses:
+          'envive-tw-flex-1 envive-tw-bg-transparent envive-tw-border-0 envive-tw-outline-none envive-tw-text-text-primary envive-tw-text-b3-rg',
+      };
+
+    case Theme.MINIMAL:
+      return {
+        inputClasses:
+          'envive-tw-flex-1 envive-tw-bg-transparent envive-tw-border-0 envive-tw-outline-none envive-tw-text-text-primary envive-tw-text-b3-rg envive-tw-pl-0',
+      };
+
+    default:
+      return getInputClasses(Theme.STANDARD);
+  }
+};

package/src/components/TextField/utils/getLayoutStateProperties.ts

@@ -0,0 +1,14 @@
+/**
+ * Calculates state properties based on the layout state.
+ */
+export const getLayoutStateProperties = (
+  hasValue: boolean,
+  isFocused: boolean,
+  disabled: boolean,
+) => {
+  return {
+    isActive: (hasValue || isFocused) && !disabled,
+    shouldShowFocus: isFocused && !disabled,
+    shouldShowHover: !disabled,
+  };
+};

package/src/components/TextField/utils/getSendIconElement.tsx

@@ -0,0 +1,53 @@
+import Send from '@envive-ai/react-icons/Send';
+import SendStandard from '@envive-ai/react-icons/SendStandard';
+import SendModern from '@envive-ai/react-icons/SendModern';
+import SendMinimalist from '@envive-ai/react-icons/SendMinimalist';
+import { Theme } from '../../../../tokens/theme/theme';
+import { CustomIcon } from '../../utils/CustomIcon';
+import { getIconColor } from './getIconColor';
+
+/**
+ * Returns the appropriate icon element based on the TextField theme.
+ */
+export const getSendIconElement = (
+  theme: Theme,
+  hasValue: boolean,
+  disabled: boolean,
+): JSX.Element => {
+  const iconColor = getIconColor(hasValue, disabled);
+
+  switch (theme) {
+    case Theme.STANDARD:
+      return (
+        <CustomIcon
+          IconComponent={<SendStandard />}
+          fill={iconColor}
+          stroke={iconColor}
+        />
+      );
+    case Theme.MODERN:
+      return (
+        <CustomIcon
+          IconComponent={<SendModern />}
+          fill={iconColor}
+          stroke={iconColor}
+        />
+      );
+    case Theme.MINIMAL:
+      return (
+        <CustomIcon
+          IconComponent={<SendMinimalist />}
+          fill={iconColor}
+          stroke={iconColor}
+        />
+      );
+    default:
+      return (
+        <CustomIcon
+          IconComponent={<Send />}
+          fill={iconColor}
+          stroke={iconColor}
+        />
+      );
+  }
+};

package/src/components/Title/Title.tsx

@@ -0,0 +1,40 @@
+import classNames from 'classnames';
+import { TitleComponents } from './components';
+import type { TitleProps } from './types';
+import { useGetSkeletonProperties } from '../Image/hooks/useGetSkeletonProperties';
+
+/**
+ * Renders a title with a label text and an optional logo.
+ */
+export const Title = ({
+  label,
+  logo,
+  id,
+  testId,
+  className,
+  style,
+  ariaLabel,
+  isLoading = false,
+}: TitleProps): JSX.Element => {
+  const logoComponent = !isLoading && logo ? <TitleComponents.Image logo={logo} /> : null;
+  const labelComponent = (
+    <TitleComponents.Label
+      label={isLoading ? '' : label}
+      ariaLabel={isLoading ? label : undefined}
+    />
+  );
+  const { skeletonClass } = useGetSkeletonProperties(isLoading);
+  const loadingHeightClass = isLoading ? 'envive-tw-h-[24px]' : '';
+
+  return (
+    <TitleComponents.Layout
+      id={id}
+      testId={testId}
+      className={classNames(className, skeletonClass, loadingHeightClass)}
+      style={style}
+      ariaLabel={ariaLabel}
+      logo={logoComponent}
+      label={labelComponent}
+    />
+  );
+};

package/src/components/Title/__tests__/Title.test.tsx

@@ -0,0 +1,179 @@
+import '@testing-library/jest-dom';
+import { describe, expect, it } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Title } from '../Title';
+
+describe('Title', () => {
+  describe('Basic rendering', () => {
+    it('should render with logo and label', () => {
+      render(
+        <Title
+          label="Widget Title"
+          logo="https://picsum.photos/400/600"
+        />,
+      );
+      expect(screen.getByText('Widget Title')).toBeInTheDocument();
+    });
+
+    it('should render without logo (only label)', () => {
+      render(<Title label="Widget Title" />);
+      expect(screen.getByText('Widget Title')).toBeInTheDocument();
+    });
+
+    it('should apply id attribute when provided', () => {
+      const { container } = render(
+        <Title
+          label="Test"
+          id="test-title-id"
+        />,
+      );
+      const element = container.querySelector('#test-title-id');
+      expect(element).toBeInTheDocument();
+    });
+
+    it('should apply testId attribute when provided', () => {
+      render(
+        <Title
+          label="Test"
+          testId="test-title"
+        />,
+      );
+      expect(screen.getByTestId('test-title')).toBeInTheDocument();
+    });
+
+    it('should apply custom className when provided', () => {
+      const { container } = render(
+        <Title
+          label="Test"
+          className="custom-class"
+        />,
+      );
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('custom-class');
+    });
+
+    it('should apply custom style when provided', () => {
+      const { container } = render(
+        <Title
+          label="Test"
+          style={{ marginTop: '20px' }}
+        />,
+      );
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveStyle({ marginTop: '20px' });
+    });
+  });
+
+  describe('Props validation', () => {
+    it('should render without error when label is empty string', () => {
+      const { container } = render(<Title label="" />);
+      expect(container.firstChild).toBeInTheDocument();
+      const typography = container.querySelector('.envive-tw-text-h2-md');
+      expect(typography).toBeInTheDocument();
+    });
+
+    it('should accept valid label', () => {
+      render(<Title label="Valid Label" />);
+      expect(screen.getByText('Valid Label')).toBeInTheDocument();
+    });
+  });
+
+  describe('Logo handling', () => {
+    it('should render logo when provided', () => {
+      const { container } = render(
+        <Title
+          label="Test"
+          logo="https://picsum.photos/400/600"
+        />,
+      );
+      // The Image component should be rendered
+      const img = container.querySelector('img');
+      expect(img).toBeInTheDocument();
+    });
+
+    it('should not render logo when not provided', () => {
+      const { container } = render(<Title label="Test" />);
+      const img = container.querySelector('img');
+      expect(img).not.toBeInTheDocument();
+    });
+
+    it('should hide logo when image fails to load', () => {
+      const { container, rerender } = render(
+        <Title
+          label="Test"
+          logo="https://invalid-url-that-will-fail.com/image.jpg"
+        />,
+      );
+
+      // Initially, the image should be rendered
+      const img = container.querySelector('img');
+      expect(img).toBeInTheDocument();
+
+      // Simulate error by triggering onError
+      if (img) {
+        const errorEvent = new Event('error');
+        img.dispatchEvent(errorEvent);
+      }
+
+      // After error, the image should be hidden (component returns null)
+      rerender(
+        <Title
+          label="Test"
+          logo="https://invalid-url-that-will-fail.com/image.jpg"
+        />,
+      );
+
+      // The Image component should handle the error internally
+      // We can verify the logo component handles errors by checking
+      // that the component doesn't crash
+      expect(screen.getByText('Test')).toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('should apply aria-label to container when provided', () => {
+      const { container } = render(
+        <Title
+          label="Test"
+          ariaLabel="Title for widget"
+        />,
+      );
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveAttribute('aria-label', 'Title for widget');
+      expect(element).toHaveAttribute('role', 'text');
+    });
+
+    it('should not apply aria-label when not provided', () => {
+      const { container } = render(<Title label="Test" />);
+      const element = container.firstChild as HTMLElement;
+      expect(element).not.toHaveAttribute('aria-label');
+      expect(element).not.toHaveAttribute('role');
+    });
+
+    it('should apply decorative attributes to logo (alt="" and role="presentation")', () => {
+      const { container } = render(
+        <Title
+          label="Test"
+          logo="https://picsum.photos/400/600"
+        />,
+      );
+      const img = container.querySelector('img');
+      expect(img).toHaveAttribute('alt', 'Merchant Logo');
+    });
+  });
+
+  describe('Layout', () => {
+    it('should render as div element', () => {
+      const { container } = render(<Title label="Test" />);
+      const element = container.firstChild as HTMLElement;
+      expect(element.tagName).toBe('DIV');
+    });
+
+    it('should use Stack with correct props (row, gap 2, center align)', () => {
+      const { container } = render(<Title label="Test" />);
+      // Stack should be rendered inside the div
+      const stack = container.querySelector('.envive-tw-flex');
+      expect(stack).toBeInTheDocument();
+    });
+  });
+});

package/src/components/Title/components/Image.tsx

@@ -0,0 +1,66 @@
+import { useEffect, useRef, useState } from 'react';
+
+export type ImageProps = {
+  logo: string;
+};
+
+export const Image = ({ logo }: ImageProps): React.ReactNode => {
+  const [hasError, setHasError] = useState(false);
+  const containerRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    // Reset error state when logo changes
+    setHasError(false);
+  }, [logo]);
+
+  useEffect(() => {
+    if (hasError) {
+      return (): void => {
+        // No cleanup needed - consistent return
+      };
+    }
+
+    const container = containerRef.current;
+    if (!container) {
+      return (): void => {
+        // No cleanup needed - consistent return
+      };
+    }
+
+    const img = container.querySelector('img');
+    if (!img) {
+      return (): void => {
+        // No cleanup needed - consistent return
+      };
+    }
+
+    const handleError = () => {
+      setHasError(true);
+    };
+
+    // Check if image already failed to load
+    if (!img.complete || img.naturalHeight === 0) {
+      // Image hasn't loaded yet or failed, wait for error event
+      img.addEventListener('error', handleError, { once: true });
+    }
+
+    return (): void => {
+      img.removeEventListener('error', handleError);
+    };
+  }, [logo, hasError]);
+
+  // Don't render if there's an error loading the image
+  if (hasError) {
+    return null;
+  }
+
+  return (
+    <div ref={containerRef}>
+      <img
+        src={logo}
+        alt="Merchant Logo"
+        className="envive-tw-h-4"
+      />
+    </div>
+  );
+};