@12-apps/ui 1.0.0

package/src/components/form/UploadButton/UploadButton.tsx

@@ -0,0 +1,312 @@
+import { AttachFileOutlined,CloudUploadOutlined } from '@mui/icons-material';
+import { Box, Button, LinearProgress, Typography, useTheme } from '@mui/material';
+import React, { useCallback,useRef, useState } from 'react';
+
+import type { UploadButtonProps, UploadButtonState } from './UploadButton.types';
+
+const UploadButton = React.forwardRef<HTMLInputElement, UploadButtonProps>(
+  (
+    {
+      variant = 'default',
+      label = 'Upload File',
+      accept,
+      capture,
+      disabled = false,
+      onSelect,
+      onUpload,
+      uploading: externalUploading = false,
+      progress: externalProgress = 0,
+      maxSizeMB,
+      validate,
+      helperText,
+      errorText,
+      icon,
+      className,
+      'data-testid': dataTestId,
+    },
+    ref,
+  ) => {
+    const theme = useTheme();
+    const inputRef = useRef<HTMLInputElement>(null);
+    const [state, setState] = useState<UploadButtonState>({
+      isDragOver: false,
+      isUploading: false,
+      uploadProgress: 0,
+      error: null,
+    });
+
+    // Use external state if provided, otherwise internal state
+    const isUploading = externalUploading || state.isUploading;
+    const progress = externalUploading ? externalProgress : state.uploadProgress;
+    const currentError = errorText || state.error;
+
+    const validateFile = useCallback(
+      (file: globalThis.File): string | null => {
+        // Size validation
+        if (maxSizeMB && file.size > maxSizeMB * 1024 * 1024) {
+          return `File size must be less than ${maxSizeMB}MB`;
+        }
+
+        // Custom validation
+        if (validate) {
+          return validate(file);
+        }
+
+        return null;
+      },
+      [maxSizeMB, validate],
+    );
+
+    const handleFileSelect = useCallback(
+      async (file: globalThis.File) => {
+        const validationError = validateFile(file);
+        if (validationError) {
+          setState((prev) => ({ ...prev, error: validationError }));
+          return;
+        }
+
+        // Clear any previous errors
+        setState((prev) => ({ ...prev, error: null }));
+
+        // Always call onSelect
+        onSelect(file);
+
+        // Handle built-in upload if provided
+        if (onUpload && !externalUploading) {
+          try {
+            setState((prev) => ({ ...prev, isUploading: true, uploadProgress: 0 }));
+
+            // Simulate progress for demonstration (in real implementation, this would be handled by the upload function)
+            const progressInterval = globalThis.setInterval(() => {
+              setState((prev) => {
+                if (prev.uploadProgress >= 90) {
+                  globalThis.clearInterval(progressInterval);
+                  return prev;
+                }
+                return { ...prev, uploadProgress: prev.uploadProgress + 10 };
+              });
+            }, 100);
+
+            await onUpload(file);
+
+            globalThis.clearInterval(progressInterval);
+            setState((prev) => ({ ...prev, isUploading: false, uploadProgress: 100 }));
+
+            // Reset progress after a delay
+            globalThis.setTimeout(() => {
+              setState((prev) => ({ ...prev, uploadProgress: 0 }));
+            }, 1000);
+          } catch (error) {
+            setState((prev) => ({
+              ...prev,
+              isUploading: false,
+              uploadProgress: 0,
+              error: error instanceof Error ? error.message : 'Upload failed',
+            }));
+          }
+        }
+      },
+      [onSelect, onUpload, validateFile, externalUploading],
+    );
+
+    const handleInputChange = useCallback(
+      (event: React.ChangeEvent<HTMLInputElement>) => {
+        const file = event.target.files?.[0];
+        if (file) {
+          handleFileSelect(file);
+        }
+      },
+      [handleFileSelect],
+    );
+
+    const handleDragEnter = useCallback(
+      (event: React.DragEvent) => {
+        event.preventDefault();
+        event.stopPropagation();
+        if (!disabled) {
+          setState((prev) => ({ ...prev, isDragOver: true }));
+        }
+      },
+      [disabled],
+    );
+
+    const handleDragLeave = useCallback((event: React.DragEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+      setState((prev) => ({ ...prev, isDragOver: false }));
+    }, []);
+
+    const handleDragOver = useCallback((event: React.DragEvent) => {
+      event.preventDefault();
+      event.stopPropagation();
+    }, []);
+
+    const handleDrop = useCallback(
+      (event: React.DragEvent) => {
+        event.preventDefault();
+        event.stopPropagation();
+        setState((prev) => ({ ...prev, isDragOver: false }));
+
+        if (disabled) return;
+
+        const file = event.dataTransfer.files[0];
+        if (file) {
+          handleFileSelect(file);
+        }
+      },
+      [disabled, handleFileSelect],
+    );
+
+    const handleButtonClick = useCallback(() => {
+      inputRef.current?.click();
+    }, []);
+
+    // Generate unique ID for accessibility
+    const inputId = `upload-button-${React.useId()}`;
+    const helperId = helperText ? `${inputId}-helper` : undefined;
+    const errorId = currentError ? `${inputId}-error` : undefined;
+
+    const renderDropzone = () => (
+      <Box
+        component="div"
+        onDragEnter={handleDragEnter}
+        onDragLeave={handleDragLeave}
+        onDragOver={handleDragOver}
+        onDrop={handleDrop}
+        onClick={handleButtonClick}
+        sx={{
+          border: `2px dashed ${state.isDragOver ? theme.palette.primary.main : theme.palette.divider}`,
+          borderRadius: 2,
+          padding: 3,
+          textAlign: 'center',
+          cursor: disabled ? 'not-allowed' : 'pointer',
+          backgroundColor: state.isDragOver ? `${theme.palette.primary.main  }0A` : 'transparent',
+          transition: 'all 0.2s ease-in-out',
+          ...(!disabled && {
+            '&:hover': {
+              borderColor: theme.palette.primary.main,
+              backgroundColor: `${theme.palette.primary.main  }05`,
+            },
+          }),
+          opacity: disabled ? 0.6 : 1,
+        }}
+        className={className}
+        data-testid={dataTestId}
+        role="button"
+        tabIndex={disabled ? -1 : 0}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            handleButtonClick();
+          }
+        }}
+        aria-describedby={[helperId, errorId].filter(Boolean).join(' ') || undefined}
+        aria-label={`Upload file dropzone. ${label}`}
+      >
+        <Box sx={{ mb: 2 }}>
+          {icon || <CloudUploadOutlined sx={{ fontSize: 48, color: 'text.secondary' }} />}
+        </Box>
+        <Typography variant="body1" sx={{ mb: 1 }}>
+          {label}
+        </Typography>
+        <Typography variant="body2" color="text.secondary">
+          Drop your file here or click to browse
+        </Typography>
+      </Box>
+    );
+
+    const renderButton = () => (
+      <Button
+        variant={variant === 'outline' ? 'outlined' : variant === 'ghost' ? 'text' : 'contained'}
+        disabled={disabled || isUploading}
+        onClick={handleButtonClick}
+        startIcon={icon || <AttachFileOutlined />}
+        className={className}
+        data-testid={dataTestId}
+        aria-describedby={[helperId, errorId].filter(Boolean).join(' ') || undefined}
+        sx={{
+          ...(variant === 'ghost' && {
+            '&:hover': {
+              backgroundColor: `${theme.palette.primary.main  }08`,
+            },
+          }),
+        }}
+      >
+        {isUploading ? 'Uploading...' : label}
+      </Button>
+    );
+
+    return (
+      <Box>
+        <input
+          ref={ref || inputRef}
+          id={inputId}
+          type="file"
+          accept={accept}
+          capture={capture}
+          onChange={handleInputChange}
+          style={{ display: 'none' }}
+          disabled={disabled}
+          aria-hidden="true"
+        />
+
+        {variant === 'dropzone' ? renderDropzone() : renderButton()}
+
+        {isUploading && progress > 0 && (
+          <Box sx={{ mt: 1 }}>
+            <LinearProgress variant="determinate" value={progress} sx={{ borderRadius: 1 }} />
+            <Typography variant="caption" sx={{ mt: 0.5, display: 'block' }}>
+              {Math.round(progress)}% uploaded
+            </Typography>
+          </Box>
+        )}
+
+        {helperText && !currentError && (
+          <Typography
+            id={helperId}
+            variant="caption"
+            color="text.secondary"
+            sx={{ display: 'block', mt: 0.5 }}
+          >
+            {helperText}
+          </Typography>
+        )}
+
+        {currentError && (
+          <Typography
+            id={errorId}
+            variant="caption"
+            color="error"
+            sx={{ display: 'block', mt: 0.5 }}
+            role="alert"
+          >
+            {currentError}
+          </Typography>
+        )}
+
+        {/* Screen reader announcements for drag and drop */}
+        <div
+          aria-live="polite"
+          aria-atomic="true"
+          className="sr-only"
+          style={{
+            position: 'absolute',
+            left: '-10000px',
+            width: '1px',
+            height: '1px',
+            overflow: 'hidden',
+          }}
+        >
+          {variant === 'dropzone' && state.isDragOver && 'File ready to drop'}
+          {isUploading && `Upload in progress: ${Math.round(progress)}%`}
+          {currentError && `Error: ${currentError}`}
+        </div>
+      </Box>
+    );
+  },
+);
+
+UploadButton.displayName = 'UploadButton';
+
+export { UploadButton };
+export type { UploadButtonProps, UploadButtonState };

package/src/components/form/UploadButton/UploadButton.types.ts

@@ -0,0 +1,58 @@
+import type { ReactNode } from 'react';
+
+export interface UploadButtonProps {
+  /** Button variant style */
+  variant?: 'default' | 'outline' | 'ghost' | 'dropzone';
+
+  /** Button text label */
+  label?: string;
+
+  /** File type restrictions (e.g., "image/*,.pdf") */
+  accept?: string;
+
+  /** Mobile camera capture hint */
+  capture?: 'user' | 'environment';
+
+  /** Disable file selection */
+  disabled?: boolean;
+
+  /** File selection callback (required) */
+  onSelect: (file: globalThis.File) => void;
+
+  /** Optional built-in upload handler with progress */
+  onUpload?: (file: globalThis.File) => Promise<void>;
+
+  /** External upload state control */
+  uploading?: boolean;
+
+  /** Upload progress (0-100) */
+  progress?: number;
+
+  /** Maximum file size in MB */
+  maxSizeMB?: number;
+
+  /** Custom file validation function */
+  validate?: (file: globalThis.File) => string | null;
+
+  /** Helper text */
+  helperText?: string;
+
+  /** Error message */
+  errorText?: string;
+
+  /** Custom icon */
+  icon?: ReactNode;
+
+  /** Additional CSS classes */
+  className?: string;
+
+  /** Test identifier */
+  'data-testid'?: string;
+}
+
+export interface UploadButtonState {
+  isDragOver: boolean;
+  isUploading: boolean;
+  uploadProgress: number;
+  error: string | null;
+}

package/src/components/form/UploadButton/index.ts

@@ -0,0 +1,2 @@
+export { UploadButton } from './UploadButton';
+export type { UploadButtonProps, UploadButtonState } from './UploadButton.types';

package/src/components/form/index.ts

@@ -0,0 +1,25 @@
+// Form Components
+export * from './AddressAutocomplete';
+export * from './Autocomplete';
+export * from './Button';
+export * from './Calendar';
+export * from './Checkbox';
+export * from './CodeEditor';
+export * from './Command';
+export * from './Form';
+export * from './Input';
+export * from './InputOTP';
+export * from './Label';
+export * from './Menubar';
+export * from './PasswordStrength';
+export * from './PhoneInput';
+export * from './RadioGroup';
+export * from './RichTextEditor';
+export * from './SearchPalette';
+export * from './Select';
+export * from './Slider';
+export * from './Switch';
+export * from './Textarea';
+export * from './Toggle';
+export * from './ToggleGroup';
+export * from './UploadButton';

package/src/components/form/total-form/Fields/SelectField.tsx

@@ -0,0 +1,57 @@
+'use client';
+
+import React from 'react';
+
+import { FormControl, FormLabel, FormMessage } from '../../Form';
+import { Select } from '../../Select';
+import type { SelectOption } from '../../Select';
+import { useFormContext } from '../FormContext';
+
+/** Props for the `total-form` {@link SelectField}. */
+export interface SelectFieldProps {
+  /** Field name; also the key into the form's values/errors. */
+  name: string;
+  /** Selectable options. */
+  options: SelectOption[];
+  /** Optional visible label rendered above the select. */
+  label?: string;
+  /** Placeholder shown when no option is selected. */
+  placeholder?: string;
+}
+
+/**
+ * Select field bound to {@link useFormContext}. Composes the existing
+ * `@12-apps/ui` `Form*` primitives and the `Select` control, reading its
+ * value/error from context and writing the chosen value back through it.
+ *
+ * Renders its error via `total-form-field-<name>-message` and the select via
+ * `total-form-field-<name>`.
+ */
+export function SelectField({ name, options, label, placeholder }: SelectFieldProps): React.ReactElement {
+  const { values, errors, setFieldValue } = useFormContext();
+  const error = errors[name];
+  const testId = `total-form-field-${name}`;
+
+  return (
+    <FormControl fullWidth>
+      {label && (
+        <FormLabel htmlFor={name} error={Boolean(error)}>
+          {label}
+        </FormLabel>
+      )}
+      <Select
+        options={options}
+        placeholder={placeholder}
+        value={values[name] ?? ''}
+        error={Boolean(error)}
+        data-testid={testId}
+        onChange={(event) => setFieldValue(name, String(event.target.value))}
+      />
+      {error && (
+        <FormMessage error dataTestId={`${testId}-message`}>
+          {error}
+        </FormMessage>
+      )}
+    </FormControl>
+  );
+}

package/src/components/form/total-form/Fields/TextField.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import React from 'react';
+
+import { FormControl, FormLabel, FormMessage } from '../../Form';
+import { Input } from '../../Input';
+import { useFormContext } from '../FormContext';
+
+/** Props for the `total-form` {@link TextField}. */
+export interface TextFieldProps {
+  /** Field name; also the key into the form's values/errors. */
+  name: string;
+  /** Optional visible label rendered above the input. */
+  label?: string;
+  /** Native input type (e.g. `email`, `password`). Defaults to `text`. */
+  type?: string;
+  /** Placeholder shown when the field is empty. */
+  placeholder?: string;
+}
+
+/**
+ * Text input field bound to {@link useFormContext}. Composes the existing
+ * `@12-apps/ui` `Form*` presentational primitives and the `Input` control,
+ * reading its value/error from context and writing changes back through it.
+ *
+ * Renders its error via `total-form-field-<name>-message` and the input via
+ * `total-form-field-<name>`.
+ */
+export function TextField({ name, label, type = 'text', placeholder }: TextFieldProps): React.ReactElement {
+  const { values, errors, setFieldValue } = useFormContext();
+  const error = errors[name];
+  const testId = `total-form-field-${name}`;
+
+  return (
+    <FormControl fullWidth>
+      {label && (
+        <FormLabel htmlFor={name} error={Boolean(error)}>
+          {label}
+        </FormLabel>
+      )}
+      <Input
+        id={name}
+        name={name}
+        type={type}
+        placeholder={placeholder}
+        value={values[name] ?? ''}
+        error={Boolean(error)}
+        data-testid={testId}
+        onChange={(event) => setFieldValue(name, event.target.value)}
+      />
+      {error && (
+        <FormMessage error dataTestId={`${testId}-message`}>
+          {error}
+        </FormMessage>
+      )}
+    </FormControl>
+  );
+}

package/src/components/form/total-form/Fields/index.ts

@@ -0,0 +1,4 @@
+export { TextField } from './TextField';
+export type { TextFieldProps } from './TextField';
+export { SelectField } from './SelectField';
+export type { SelectFieldProps } from './SelectField';

package/src/components/form/total-form/FormContainer.tsx

@@ -0,0 +1,104 @@
+'use client';
+
+import { validateFields } from '@12-apps/shared-helpers/forms';
+import type { ValidatorSchema } from '@12-apps/shared-helpers/forms';
+import React, { useCallback, useMemo, useState } from 'react';
+
+import { Form } from '../Form';
+
+import { FormContext } from './FormContext';
+import type { TotalFormContextValue } from './FormContext';
+
+/** Imperative helpers handed to {@link FormContainerProps.onSubmit}. */
+export interface FormSubmitHelpers {
+  /**
+   * Set (highlight) per-field error messages after a submit — e.g. mapping a
+   * server failure back to the exact offending field. Pass `{}` to clear. Each
+   * error auto-clears when the user edits that field.
+   */
+  setFieldErrors: (errors: Record<string, string | undefined>) => void;
+}
+
+/** Props for {@link FormContainer}. */
+export interface FormContainerProps<T extends Record<string, string>> {
+  /** Initial value for every field, keyed by field name. */
+  initialValues: T;
+  /** Per-field validators run on submit. Omit to skip validation. */
+  schema?: ValidatorSchema<T>;
+  /**
+   * Called with the validated values once the form passes validation. Receives
+   * {@link FormSubmitHelpers} so it can highlight fields on a server failure.
+   */
+  onSubmit: (values: T, helpers: FormSubmitHelpers) => void | Promise<void>;
+  /** Field components, the submit button, and the error snackbar. */
+  children: React.ReactNode;
+  /** Test id applied to the underlying `<form>`. Defaults to `total-form`. */
+  dataTestId?: string;
+}
+
+/**
+ * Stateful, domain-agnostic form container ported from the gym-app
+ * `total-form`. Holds values/errors/submitting in {@link FormContext}, runs the
+ * field validators from `@12-apps/shared-helpers/forms` on submit, and only calls
+ * `onSubmit` with the validated values when no field errors remain. Uses no
+ * zod and no react-hook-form.
+ *
+ * @typeParam T - The form's value shape (a record of string fields).
+ */
+export function FormContainer<T extends Record<string, string>>({
+  initialValues,
+  schema,
+  onSubmit,
+  children,
+  dataTestId = 'total-form',
+}: FormContainerProps<T>): React.ReactElement {
+  const [values, setValues] = useState<T>(initialValues);
+  const [errors, setErrors] = useState<Record<string, string | undefined>>({});
+  const [submitting, setSubmitting] = useState(false);
+
+  const setFieldValue = useCallback<TotalFormContextValue['setFieldValue']>((name, value) => {
+    setValues((prev) => ({ ...prev, [name]: value }));
+    setErrors((prev) => {
+      if (!prev[name]) return prev;
+      const next = { ...prev };
+      delete next[name];
+      return next;
+    });
+  }, []);
+
+  const handleSubmit = useCallback(
+    async (event: React.FormEvent<HTMLFormElement>) => {
+      event.preventDefault();
+      const nextErrors = schema ? validateFields(values, schema) : {};
+      setErrors(nextErrors);
+      if (Object.values(nextErrors).some(Boolean)) return;
+
+      setSubmitting(true);
+      try {
+        // Replace the error map so the helper's contract holds: passing `{}`
+        // clears, and a later field-less failure can't leave a stale highlight.
+        // `onSubmit` only runs once client validation passes, so there are no
+        // client errors here to preserve.
+        await onSubmit(values, {
+          setFieldErrors: (fieldErrors) => setErrors(fieldErrors),
+        });
+      } finally {
+        setSubmitting(false);
+      }
+    },
+    [onSubmit, schema, values],
+  );
+
+  const contextValue = useMemo<TotalFormContextValue>(
+    () => ({ values, errors, submitting, setFieldValue }),
+    [errors, setFieldValue, submitting, values],
+  );
+
+  return (
+    <FormContext.Provider value={contextValue}>
+      <Form dataTestId={dataTestId} onSubmit={handleSubmit} noValidate>
+        {children}
+      </Form>
+    </FormContext.Provider>
+  );
+}

package/src/components/form/total-form/FormContext.tsx

@@ -0,0 +1,38 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+/**
+ * Shape of the value exposed by the `total-form` {@link FormContext}.
+ *
+ * Field values and errors are keyed by field name. The container owns the
+ * state; fields and controls read from and write to it through
+ * {@link useFormContext}.
+ */
+export interface TotalFormContextValue {
+  /** Current value of every field, keyed by field name. */
+  values: Record<string, string>;
+  /** First validation error per field (absent when the field is valid). */
+  errors: Record<string, string | undefined>;
+  /** Whether the form's `onSubmit` handler is currently running. */
+  submitting: boolean;
+  /** Updates a single field's value and clears any resolved error for it. */
+  setFieldValue: (name: string, value: string) => void;
+}
+
+/** React context backing the `total-form` layer. `null` outside a container. */
+export const FormContext = createContext<TotalFormContextValue | null>(null);
+
+/**
+ * Reads the nearest {@link FormContext}.
+ *
+ * @throws If called outside a `FormContainer`.
+ * @returns The current form context value.
+ */
+export function useFormContext(): TotalFormContextValue {
+  const context = useContext(FormContext);
+  if (!context) {
+    throw new Error('useFormContext must be used within a <FormContainer>');
+  }
+  return context;
+}