@envive-ai/react-toolkit-v3 0.3.5

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

@@ -0,0 +1,72 @@
+export type FormTextFieldType = 'text' | 'email' | 'number' | 'url' | 'password';
+
+export type FormTextField = {
+  /**
+   * Placeholder text for the input.
+   */
+  label: string;
+  /**
+   * Required flag used only for submit validation.
+   */
+  isRequired: boolean;
+  /**
+   * Input type (text, email, number, url, password).
+   */
+  type: FormTextFieldType;
+  /**
+   * Accessible label for the input.
+   */
+  ariaLabel?: string;
+};
+
+export type FormSubmitButton = {
+  /**
+   * Button label text.
+   */
+  label: string;
+  /**
+   * Accessible label for the submit button.
+   */
+  ariaLabel?: string;
+  /**
+   * Flag that disables the submit button and prevents submit flow.
+   */
+  isDisabled?: boolean;
+};
+
+export type FormSubmitValue = {
+  /**
+   * Label for one of the input fields filled in the form.
+   */
+  label: string;
+  /**
+   * Value for one of the input fields filled in the form.
+   */
+  value: string;
+};
+
+/**
+ * Props accepted by the `Forms` component.
+ */
+export type FormProps = {
+  /**
+   * Array of definitions for form input fields.
+   */
+  textFields: FormTextField[];
+  /**
+   * Definition for the form submit button.
+   */
+  submitButton: FormSubmitButton;
+  /**
+   * Callback invoked when the form is submitted.
+   */
+  onSubmit: (values: FormSubmitValue[]) => void;
+  /**
+   * Accessible label for the form container.
+   */
+  ariaLabel?: string;
+  id?: string;
+  testId?: string;
+  className?: string;
+  style?: React.CSSProperties;
+};

package/src/components/Form/utils/buildSubmitButtonElement.ts

@@ -0,0 +1,14 @@
+import { createElement } from 'react';
+import type { FormSubmitButton } from '../types';
+import { FormsComponents } from '../components';
+
+/**
+ * Builds the submit button element based on the submit button definition.
+ */
+export const buildSubmitButtonElement = (submitButton: FormSubmitButton) => {
+  return createElement(FormsComponents.SubmitButtonItem, {
+    label: submitButton.label,
+    ariaLabel: submitButton.ariaLabel,
+    isDisabled: submitButton.isDisabled,
+  });
+};

package/src/components/Form/utils/buildTextFieldsSubmitPayload.ts

@@ -0,0 +1,17 @@
+import type { FormSubmitValue, FormTextField } from '../types';
+
+/**
+ * Builds the submit payload in the shape:
+ *   [{ label: string; value: string }]
+ */
+export const buildTextFieldsSubmitPayload = (
+  textFields: FormTextField[],
+  values: string[],
+): FormSubmitValue[] => {
+  return textFields.map((field, index) => {
+    return {
+      label: field.label,
+      value: values[index] ?? '',
+    };
+  });
+};

package/src/components/Form/utils/createFormSchema.ts

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+import type { FormTextField } from '../types';
+
+/**
+ * Creates a Zod schema for form validation based on the field definitions.
+ */
+export const createFormSchema = (textFields: FormTextField[]) => {
+  const schemaObject: Record<string, z.ZodTypeAny> = {};
+
+  textFields.forEach((field, index) => {
+    const fieldKey = `field_${index}`;
+    const fieldType = field.type;
+
+    if (fieldType === 'number') {
+      const numberSchema = z.union([z.coerce.number(), z.literal('')]);
+
+      if (field.isRequired) {
+        schemaObject[fieldKey] = numberSchema.refine(
+          val => val !== '',
+          `${field.label} is missing`,
+        );
+      } else {
+        schemaObject[fieldKey] = numberSchema;
+      }
+    } else {
+      let stringSchema: z.ZodString = z.string();
+
+      if (fieldType === 'email') {
+        stringSchema = stringSchema.email(`Not a valid email address`);
+      } else if (fieldType === 'url') {
+        stringSchema = stringSchema.url(`${field.label} must be a valid URL`);
+      }
+
+      if (field.isRequired) {
+        stringSchema = stringSchema.min(1, `${field.label} is missing`);
+        schemaObject[fieldKey] = stringSchema;
+      } else {
+        // For optional fields: if empty, allow. Otherwise, validate with type rules
+        schemaObject[fieldKey] = z.string().refine(
+          val => {
+            if (val === '') return true;
+            if (fieldType === 'email') {
+              return z.string().email().safeParse(val).success;
+            }
+            if (fieldType === 'url') {
+              return z.string().url().safeParse(val).success;
+            }
+            return true;
+          },
+          {
+            message: (() => {
+              if (fieldType === 'email') return 'Not a valid email address';
+              if (fieldType === 'url') return 'Not a valid URL';
+              return '';
+            })(),
+          },
+        );
+      }
+    }
+  });
+
+  return z.object(schemaObject);
+};

package/src/components/Form/utils/handleFormsSubmit.ts

@@ -0,0 +1,27 @@
+import type { FormSubmitValue, FormTextField } from '../types';
+import { buildTextFieldsSubmitPayload } from './buildTextFieldsSubmitPayload';
+import { type ValidationResult, validateTextFieldsForSubmit } from './validateTextFieldsForSubmit';
+
+type HandleFormsSubmitArgs = {
+  textFields: FormTextField[];
+  values: string[];
+  onSubmit: (values: FormSubmitValue[]) => void;
+};
+
+export type HandleFormsSubmitResult = ValidationResult;
+
+export const handleFormsSubmit = ({
+  textFields,
+  values,
+  onSubmit,
+}: HandleFormsSubmitArgs): HandleFormsSubmitResult => {
+  const validation = validateTextFieldsForSubmit(textFields, values);
+
+  if (!validation.isValid) {
+    return validation;
+  }
+
+  const payload = buildTextFieldsSubmitPayload(textFields, values);
+  onSubmit(payload);
+  return { isValid: true, fieldErrors: {} };
+};

package/src/components/Form/utils/mapTextFields.ts

@@ -0,0 +1,25 @@
+import { createElement } from 'react';
+import type { FormTextField } from '../types';
+import { FormsComponents } from '../components';
+
+/**
+ * Maps text field definitions to TextFieldItem elements.
+ */
+export const mapTextFields = (
+  textFields: FormTextField[],
+  values: string[],
+  onChange: (index: number, value: string) => void,
+  fieldErrors: Record<number, string> = {},
+) => {
+  return textFields.map((field, index) => {
+    return createElement(FormsComponents.TextFieldItem, {
+      key: `${field.label}`,
+      label: field.label,
+      value: values[index] ?? '',
+      type: field.type,
+      onChange: (value: string) => onChange(index, value),
+      ariaLabel: field.ariaLabel,
+      error: fieldErrors[index],
+    });
+  });
+};

package/src/components/Form/utils/validateTextFieldsForSubmit.ts

@@ -0,0 +1,48 @@
+import type { FormTextField } from '../types';
+import { createFormSchema } from './createFormSchema';
+
+export type ValidationResult = {
+  isValid: boolean;
+  fieldErrors: Record<number, string>;
+};
+
+/**
+ * Validates form fields using Zod schema based on field types and requirements.
+ * Returns errors mapped by field index.
+ */
+export const validateTextFieldsForSubmit = (
+  textFields: FormTextField[],
+  values: string[],
+): ValidationResult => {
+  const schema = createFormSchema(textFields);
+
+  const data: Record<string, string | number> = {};
+  textFields.forEach((_, index) => {
+    const fieldKey = `field_${index}`;
+    const value = values[index] ?? '';
+    data[fieldKey] = value;
+  });
+
+  const result = schema.safeParse(data);
+
+  if (!result.success) {
+    const fieldErrors: Record<number, string> = {};
+
+    result.error.errors.forEach(error => {
+      const fieldKey = error.path[0] as string;
+      if (fieldKey?.startsWith('field_')) {
+        const fieldIndex = parseInt(fieldKey.replace('field_', ''), 10);
+        if (!Number.isNaN(fieldIndex)) {
+          fieldErrors[fieldIndex] = error.message;
+        }
+      }
+    });
+
+    return {
+      isValid: false,
+      fieldErrors,
+    };
+  }
+
+  return { isValid: true, fieldErrors: {} };
+};

package/src/components/Image/Image.tsx

@@ -0,0 +1,98 @@
+import classNames from 'classnames';
+import { ImageAspectRatio, ImageObjectFit } from './types';
+import type { ImageProps } from './types';
+import { useGetAspectRatioProperties } from './hooks/useGetAspectRatioProperties';
+import { useGetObjectFitProperties } from './hooks/useGetObjectFitProperties';
+import { useGetRoundedProperties } from './hooks/useGetRoundedProperties';
+import { useGetAccessibilityProperties } from './hooks/useGetAccessibilityProperties';
+import { useGetSkeletonProperties } from './hooks/useGetSkeletonProperties';
+import { useGetWidthProperties } from './hooks/useGetWidthProperties';
+import { useHandleImageLoading } from './hooks/useHandleImageLoading';
+
+/**
+ * Renders an image with configurable aspect ratio and object fit options.
+ * Supports square (1:1) and portrait (3:4) aspect ratios.
+ */
+export const Image = ({
+  id,
+  testId,
+  src,
+  alt,
+  aspectRatio = ImageAspectRatio.GLOBAL_CUSTOM,
+  objectFit = ImageObjectFit.COVER,
+  className,
+  style,
+  rounded = false,
+  width,
+  isLoading: isLoadingProp = false,
+  'aria-label': ariaLabel,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
+  role = 'img',
+  'aria-hidden': ariaHidden,
+  ...rest
+}: ImageProps) => {
+  const { aspectRatioClass } = useGetAspectRatioProperties(aspectRatio);
+  const { objectFitClass } = useGetObjectFitProperties(objectFit);
+  const { roundedClass } = useGetRoundedProperties(rounded);
+  const { sizeStyle, widthClass } = useGetWidthProperties(width);
+
+  const { isLoading, imgRef, handleLoad, handleError } = useHandleImageLoading({
+    src,
+    isLoadingProp,
+  });
+
+  const { skeletonClass } = useGetSkeletonProperties(isLoading);
+
+  const { accessibilityProps } = useGetAccessibilityProperties({
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+    role,
+    'aria-hidden': ariaHidden,
+  });
+
+  const containerStyle = {
+    ...style,
+    ...(sizeStyle || {}),
+  };
+
+  return (
+    <div
+      className={classNames(
+        'envive-tw-relative envive-tw-overflow-hidden',
+        widthClass,
+        aspectRatioClass,
+        roundedClass,
+        isLoading && skeletonClass,
+        className,
+      )}
+      style={containerStyle}
+      id={id}
+      data-testid={testId}
+    >
+      {isLoading && (
+        <div
+          className={classNames('envive-tw-inset-0 envive-tw-absolute', skeletonClass)}
+          aria-label={ariaLabel || alt}
+          role="img"
+          {...(ariaHidden !== undefined && { 'aria-hidden': ariaHidden })}
+        />
+      )}
+      <img
+        ref={imgRef}
+        src={src}
+        alt={alt}
+        className={classNames(
+          'envive-tw-h-full envive-tw-w-full',
+          objectFitClass,
+          isLoading && 'envive-tw-opacity-0',
+        )}
+        onLoad={handleLoad}
+        onError={handleError}
+        {...accessibilityProps}
+        {...rest}
+      />
+    </div>
+  );
+};