@envive-ai/react-toolkit-v3 0.3.5

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

@@ -0,0 +1,257 @@
+import '@testing-library/jest-dom';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { Stack } from '../Stack';
+
+const mockWindowWidth = (width: number) => {
+  Object.defineProperty(window, 'innerWidth', {
+    writable: true,
+    configurable: true,
+    value: width,
+  });
+  window.dispatchEvent(new Event('resize'));
+};
+
+describe('Stack', () => {
+  beforeEach(() => {
+    mockWindowWidth(1024);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('Basic rendering', () => {
+    it('should render children correctly', () => {
+      render(
+        <Stack>
+          <div>Child 1</div>
+          <div>Child 2</div>
+        </Stack>,
+      );
+      expect(screen.getByText('Child 1')).toBeInTheDocument();
+      expect(screen.getByText('Child 2')).toBeInTheDocument();
+    });
+  });
+
+  describe('Direction', () => {
+    it('should apply column direction', () => {
+      const { container } = render(<Stack direction="column">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-col');
+    });
+
+    it('should apply row direction', () => {
+      const { container } = render(<Stack direction="row">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-row');
+    });
+
+    it('should apply column-reverse direction', () => {
+      const { container } = render(<Stack direction="column-reverse">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-col-reverse');
+    });
+
+    it('should apply row-reverse direction', () => {
+      const { container } = render(<Stack direction="row-reverse">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-row-reverse');
+    });
+  });
+
+  describe('Gap', () => {
+    it('should apply gap class when gap is provided', () => {
+      const { container } = render(<Stack gap={4}>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-gap-4');
+    });
+
+    it('should apply gap-0 when gap is 0', () => {
+      const { container } = render(<Stack gap="0">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-gap-0');
+    });
+
+    it('should not apply gap class when gap is undefined', () => {
+      const { container } = render(<Stack>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).not.toHaveClass('envive-tw-gap-4');
+    });
+  });
+
+  describe('Wrap', () => {
+    it('should apply flex-wrap when wrap is true', () => {
+      const { container } = render(<Stack wrap>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-wrap');
+    });
+
+    it('should apply flex-nowrap when wrap is false', () => {
+      const { container } = render(<Stack wrap={false}>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-nowrap');
+    });
+
+    it('should apply flex-nowrap classes when wrap is not specified', () => {
+      const { container } = render(<Stack>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-nowrap');
+    });
+  });
+
+  describe('Align', () => {
+    it('should apply items-start when align is start', () => {
+      const { container } = render(<Stack align="start">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-items-start');
+    });
+
+    it('should apply items-center when align is center', () => {
+      const { container } = render(<Stack align="center">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-items-center');
+    });
+
+    it('should apply items-stretch when align is stretch', () => {
+      const { container } = render(<Stack align="stretch">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-items-stretch');
+    });
+
+    it('should apply default align (stretch)', () => {
+      const { container } = render(<Stack>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-items-stretch');
+    });
+  });
+
+  describe('Justify', () => {
+    it('should apply justify-start when justify is start', () => {
+      const { container } = render(<Stack justify="start">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-justify-start');
+    });
+
+    it('should apply justify-between when justify is between', () => {
+      const { container } = render(<Stack justify="between">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-justify-between');
+    });
+
+    it('should apply justify-center when justify is center', () => {
+      const { container } = render(<Stack justify="center">Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-justify-center');
+    });
+
+    it('should apply default justify (start)', () => {
+      const { container } = render(<Stack>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-justify-start');
+    });
+  });
+
+  describe('Divider', () => {
+    it('should render divider between children', () => {
+      render(
+        <Stack divider={<span data-testid="divider">|</span>}>
+          <div>Child 1</div>
+          <div>Child 2</div>
+          <div>Child 3</div>
+        </Stack>,
+      );
+      const dividers = screen.getAllByTestId('divider');
+      expect(dividers).toHaveLength(2);
+    });
+
+    it('should not render divider when divider is not provided', () => {
+      render(
+        <Stack>
+          <div>Child 1</div>
+          <div>Child 2</div>
+        </Stack>,
+      );
+      expect(screen.queryByTestId('divider')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Responsive values', () => {
+    it('should handle array direction values at SM breakpoint', () => {
+      mockWindowWidth(640);
+      const { container, rerender } = render(<Stack direction={['column', 'row']}>Content</Stack>);
+      let element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-row');
+
+      mockWindowWidth(400);
+      rerender(<Stack direction={['column', 'row']}>Content</Stack>);
+      element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-col');
+    });
+
+    it('should handle object direction values at MD breakpoint', () => {
+      mockWindowWidth(768);
+      const { container } = render(
+        <Stack direction={{ base: 'column', md: 'row' }}>Content</Stack>,
+      );
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-flex-row');
+    });
+
+    it('should handle object gap values at MD breakpoint', () => {
+      mockWindowWidth(768);
+      const { container } = render(<Stack gap={{ base: 2, md: 8 }}>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-gap-8');
+    });
+
+    it('should handle array gap values at SM breakpoint', () => {
+      mockWindowWidth(640);
+      const { container, rerender } = render(<Stack gap={[2, 4, 6]}>Content</Stack>);
+      // Trigger rerender to ensure useResponsiveValue picks up the new window width
+      rerender(<Stack gap={[2, 4, 6]}>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      // At SM breakpoint (index 2), array [2, 4, 6] should use value at index 2, which is 6
+      expect(element).toHaveClass('envive-tw-gap-6');
+    });
+
+    it('should handle object align values at LG breakpoint', () => {
+      mockWindowWidth(1024);
+      const { container } = render(<Stack align={{ base: 'start', lg: 'center' }}>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-items-center');
+    });
+
+    it('should handle object justify values at XL breakpoint', () => {
+      mockWindowWidth(1280);
+      const { container } = render(
+        <Stack justify={{ base: 'start', xl: 'between' }}>Content</Stack>,
+      );
+      const element = container.firstChild as HTMLElement;
+      expect(element).toHaveClass('envive-tw-justify-between');
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle empty children', () => {
+      const { container } = render(<Stack />);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toBeInTheDocument();
+      expect(element).toBeEmptyDOMElement();
+    });
+
+    it('should handle null children', () => {
+      const { container } = render(<Stack>{null}</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toBeInTheDocument();
+    });
+
+    it('should handle undefined gap', () => {
+      const { container } = render(<Stack gap={undefined}>Content</Stack>);
+      const element = container.firstChild as HTMLElement;
+      expect(element).toBeInTheDocument();
+
+      expect(element.className).not.toContain('envive-tw-gap-');
+    });
+  });
+});

package/src/components/Stack/hooks/useFormatStackChildren.tsx

@@ -0,0 +1,34 @@
+import {
+  Children,
+  type ReactElement,
+  type ReactNode,
+  cloneElement,
+  isValidElement,
+  useMemo,
+} from 'react';
+
+type UseStackChildrenParams = {
+  children: ReactNode;
+  divider?: ReactNode;
+};
+
+const renderDivider = (divider: ReactNode) => {
+  if (isValidElement(divider)) return cloneElement(divider as ReactElement);
+
+  return <span className="envive-tw-flex">{divider}</span>;
+};
+export const useFormatStackChildren = ({ children, divider }: UseStackChildrenParams) => {
+  return useMemo(() => {
+    if (!divider) return children;
+
+    const childrenArray = Children.toArray(children);
+
+    return childrenArray.reduce<ReactNode[]>((acc, child, index) => {
+      acc.push(child);
+
+      if (divider && index < childrenArray.length - 1) acc.push(renderDivider(divider));
+
+      return acc;
+    }, []);
+  }, [children, divider]);
+};

package/src/components/Stack/hooks/useGetAlignProperties.ts

@@ -0,0 +1,25 @@
+import { useMemo } from 'react';
+import type { StackAlign } from '../types/index.js';
+
+export const useGetAlignProperties = (align?: StackAlign) => {
+  return useMemo(() => {
+    if (!align)
+      return {
+        alignClass: undefined,
+      };
+
+    const ALIGN_CLASS_MAP: Record<StackAlign, string> = {
+      start: 'envive-tw-items-start',
+      end: 'envive-tw-items-end',
+      center: 'envive-tw-items-center',
+      baseline: 'envive-tw-items-baseline',
+      stretch: 'envive-tw-items-stretch',
+    };
+
+    const alignClass = ALIGN_CLASS_MAP[align];
+
+    return {
+      alignClass,
+    };
+  }, [align]);
+};

package/src/components/Stack/hooks/useGetDirectionProperties.ts

@@ -0,0 +1,19 @@
+import { useMemo } from 'react';
+import type { StackDirection } from '../types/index.js';
+
+export const useGetDirectionProperties = (direction: StackDirection) => {
+  return useMemo(() => {
+    const DIRECTION_CLASS_MAP: Record<StackDirection, string> = {
+      column: 'envive-tw-flex-col',
+      'column-reverse': 'envive-tw-flex-col-reverse',
+      row: 'envive-tw-flex-row',
+      'row-reverse': 'envive-tw-flex-row-reverse',
+    };
+
+    const directionClass = DIRECTION_CLASS_MAP[direction] ?? DIRECTION_CLASS_MAP.column;
+
+    return {
+      directionClass,
+    };
+  }, [direction]);
+};

package/src/components/Stack/hooks/useGetGapProperties.ts

@@ -0,0 +1,18 @@
+import { useMemo } from 'react';
+import type { StackGapValue } from '../types/index.js';
+import { STACK_GAP_TOKENS } from '../utils/constants.js';
+
+export const useGetGapProperties = (gapValue: StackGapValue | undefined) => {
+  return useMemo(() => {
+    if (gapValue === undefined) return { gapClass: undefined };
+
+    if (typeof gapValue === 'number') {
+      const key = gapValue.toString();
+      return { gapClass: STACK_GAP_TOKENS[key] ?? undefined };
+    }
+
+    return {
+      gapClass: STACK_GAP_TOKENS[gapValue] ?? undefined,
+    };
+  }, [gapValue]);
+};

package/src/components/Stack/hooks/useGetJustifyProperties.ts

@@ -0,0 +1,26 @@
+import { useMemo } from 'react';
+import type { StackJustify } from '../types/index.js';
+
+export const useGetJustifyProperties = (justify?: StackJustify) => {
+  return useMemo(() => {
+    if (!justify)
+      return {
+        justifyClass: undefined,
+      };
+
+    const JUSTIFY_CLASS_MAP: Record<StackJustify, string> = {
+      start: 'envive-tw-justify-start',
+      end: 'envive-tw-justify-end',
+      center: 'envive-tw-justify-center',
+      between: 'envive-tw-justify-between',
+      around: 'envive-tw-justify-around',
+      evenly: 'envive-tw-justify-evenly',
+    };
+
+    const justifyClass = JUSTIFY_CLASS_MAP[justify];
+
+    return {
+      justifyClass,
+    };
+  }, [justify]);
+};

package/src/components/Stack/hooks/useGetStyleProperties.ts

@@ -0,0 +1,44 @@
+import { useGetAlignProperties } from './useGetAlignProperties';
+import { useGetGapProperties } from './useGetGapProperties';
+import { useGetJustifyProperties } from './useGetJustifyProperties';
+import { useGetWrapProperties } from './useGetWrapProperties';
+import { StackAlign, StackDirection, StackGapValue, StackJustify } from '../types';
+import { useGetDirectionProperties } from './useGetDirectionProperties';
+import { useResponsiveValue } from '../../utils/useResponsiveValue';
+import type { StackProps } from '../types';
+
+export const useGetStyleProperties = ({ direction, gap, wrap, align, justify }: StackProps) => {
+  const resolvedDirection = useResponsiveValue<StackDirection>({
+    value: direction,
+    fallback: 'column',
+  });
+  const { directionClass } = useGetDirectionProperties(resolvedDirection);
+
+  const resolvedGap = useResponsiveValue<StackGapValue>({
+    value: gap,
+    fallback: undefined,
+  });
+  const { gapClass } = useGetGapProperties(resolvedGap);
+
+  const wrapClass = useGetWrapProperties(wrap);
+
+  const resolvedAlign = useResponsiveValue<StackAlign | undefined>({
+    value: align,
+    fallback: undefined,
+  });
+  const { alignClass } = useGetAlignProperties(resolvedAlign);
+
+  const resolvedJustify = useResponsiveValue<StackJustify | undefined>({
+    value: justify,
+    fallback: undefined,
+  });
+  const { justifyClass } = useGetJustifyProperties(resolvedJustify);
+
+  return {
+    directionClass,
+    gapClass,
+    wrapClass,
+    alignClass,
+    justifyClass,
+  };
+};

package/src/components/Stack/hooks/useGetWrapProperties.ts

@@ -0,0 +1,7 @@
+import { useMemo } from 'react';
+
+export const useGetWrapProperties = (wrap: boolean) => {
+  return useMemo(() => {
+    return wrap ? 'envive-tw-flex-wrap' : 'envive-tw-flex-nowrap';
+  }, [wrap]);
+};

package/src/components/Stack/index.ts

@@ -0,0 +1,13 @@
+export { Stack } from './Stack';
+export type {
+  StackProps,
+  StackDirection,
+  StackGap,
+  StackDirectionValue,
+  StackGapValue,
+  StackWrap,
+  StackAlign,
+  StackJustify,
+  StackAlignValue,
+  StackJustifyValue,
+} from './types/index';

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

@@ -0,0 +1,70 @@
+import type { ReactNode } from 'react';
+import { ResponsiveValue } from 'src/components/utils/useResponsiveValue';
+
+export type StackDirection = 'column' | 'column-reverse' | 'row' | 'row-reverse';
+
+export type StackGapValue = number | string;
+
+export type StackGap = ResponsiveValue<StackGapValue>;
+
+export type StackDirectionValue = ResponsiveValue<StackDirection>;
+
+export type StackWrap = boolean;
+
+export type StackAlign = 'start' | 'end' | 'center' | 'baseline' | 'stretch';
+
+export type StackJustify = 'start' | 'end' | 'center' | 'between' | 'around' | 'evenly';
+
+export type StackAlignValue = ResponsiveValue<StackAlign>;
+
+export type StackJustifyValue = ResponsiveValue<StackJustify>;
+
+/**
+ * Props accepted by the `Stack` component.
+ */
+export interface StackProps {
+  /**
+   * Unique `id` attribute attached to the rendered element.
+   */
+  id?: string;
+  /**
+   * Adds a `data-testid` attribute for testing utilities.
+   */
+  testId?: string;
+  /**
+   * Node rendered inside the stack element.
+   */
+  children?: ReactNode;
+  /**
+   * Additional class names appended to the computed stack classes.
+   */
+  className?: string;
+  /**
+   * Inline styles forwarded to the rendered element.
+   */
+  style?: React.CSSProperties;
+  /**
+   * Defines the flex-direction style property. Accepts responsive values.
+   */
+  direction?: StackDirectionValue;
+  /**
+   * Add an element between each child.
+   */
+  divider?: ReactNode;
+  /**
+   * Defines the gap between immediate children. Accepts responsive values.
+   */
+  gap?: StackGap;
+  /**
+   * Defines whether flex items should wrap. When true, items wrap to multiple lines.
+   */
+  wrap?: StackWrap;
+  /**
+   * Defines the align-items style property. Accepts responsive values.
+   */
+  align?: StackAlignValue;
+  /**
+   * Defines the justify-content style property. Accepts responsive values.
+   */
+  justify?: StackJustifyValue;
+}

package/src/components/Stack/utils/constants.ts

@@ -0,0 +1,36 @@
+export const STACK_GAP_TOKENS: Record<string, string> = {
+  '0': 'envive-tw-gap-0',
+  '0.5': 'envive-tw-gap-0.5',
+  '1': 'envive-tw-gap-1',
+  '1.5': 'envive-tw-gap-1.5',
+  '2': 'envive-tw-gap-2',
+  '2.5': 'envive-tw-gap-2.5',
+  '3': 'envive-tw-gap-3',
+  '3.5': 'envive-tw-gap-3.5',
+  '4': 'envive-tw-gap-4',
+  '5': 'envive-tw-gap-5',
+  '6': 'envive-tw-gap-6',
+  '7': 'envive-tw-gap-7',
+  '8': 'envive-tw-gap-8',
+  '9': 'envive-tw-gap-9',
+  '10': 'envive-tw-gap-10',
+  '11': 'envive-tw-gap-11',
+  '12': 'envive-tw-gap-12',
+  '14': 'envive-tw-gap-14',
+  '16': 'envive-tw-gap-16',
+  '20': 'envive-tw-gap-20',
+  '24': 'envive-tw-gap-24',
+  '28': 'envive-tw-gap-28',
+  '32': 'envive-tw-gap-32',
+  '36': 'envive-tw-gap-36',
+  '40': 'envive-tw-gap-40',
+  '44': 'envive-tw-gap-44',
+  '48': 'envive-tw-gap-48',
+  '52': 'envive-tw-gap-52',
+  '56': 'envive-tw-gap-56',
+  '60': 'envive-tw-gap-60',
+  '64': 'envive-tw-gap-64',
+  '72': 'envive-tw-gap-72',
+  '80': 'envive-tw-gap-80',
+  '96': 'envive-tw-gap-96',
+};

package/src/components/TextField/TextField.tsx

@@ -0,0 +1,84 @@
+import classNames from 'classnames';
+import { Theme } from '../../../tokens/theme/theme';
+import { TextFieldComponents } from './components';
+import type { TextFieldProps } from './types';
+import { useGetSkeletonProperties } from './hooks/useGetSkeletonProperties';
+import { useTextFieldValue } from './hooks/useTextFieldValue';
+import { useTextFieldFocus } from './hooks/useTextFieldFocus';
+import { useTextFieldSubmit } from './hooks/useTextFieldSubmit';
+import { resolveTheme } from '../utils/resolveTheme';
+
+/**
+ * Renders a text input field with a send icon.
+ * Supports three visual themes: Standard, Modern, and Minimal.
+ */
+export const TextField = ({
+  theme = Theme.GLOBAL_CUSTOM,
+  placeholder,
+  value: controlledValue,
+  onChange,
+  onSubmit,
+  disabled = false,
+  id,
+  testId,
+  className,
+  style,
+  ariaLabel,
+  isLoading = false,
+}: TextFieldProps): JSX.Element => {
+  const { currentValue, hasValue, handleChange, resetValue } = useTextFieldValue(
+    controlledValue,
+    onChange,
+  );
+  const { isFocused, handleFocus, handleBlur } = useTextFieldFocus();
+  const { handleSubmit, handleKeyDown } = useTextFieldSubmit(
+    onSubmit,
+    hasValue,
+    disabled,
+    isLoading,
+    currentValue,
+    resetValue,
+  );
+  const { skeletonClass } = useGetSkeletonProperties(isLoading);
+
+  const resolvedTheme = resolveTheme(theme);
+
+  const input = (
+    <TextFieldComponents.Input
+      theme={resolvedTheme}
+      placeholder={isLoading ? '' : placeholder}
+      value={isLoading ? '' : currentValue}
+      onChange={handleChange}
+      onKeyDown={handleKeyDown}
+      onFocus={handleFocus}
+      onBlur={handleBlur}
+      disabled={disabled || isLoading}
+      ariaLabel={ariaLabel}
+    />
+  );
+
+  const sendIcon = !isLoading ? (
+    <TextFieldComponents.SendIcon
+      theme={resolvedTheme}
+      hasValue={hasValue}
+      disabled={disabled}
+      onClick={handleSubmit}
+      ariaLabel={ariaLabel}
+    />
+  ) : null;
+
+  return (
+    <TextFieldComponents.Layout
+      theme={resolvedTheme}
+      input={input}
+      sendIcon={sendIcon}
+      isFocused={isFocused}
+      hasValue={hasValue}
+      disabled={disabled}
+      id={id}
+      testId={testId}
+      className={classNames(className, skeletonClass, disabled && 'envive-tw-cursor-not-allowed')}
+      style={style}
+    />
+  );
+};