@12-apps/ui 1.0.0 → 1.3.1

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

@@ -1,310 +1,81 @@
-import { AttachFileOutlined,CloudUploadOutlined } from '@mui/icons-material';
-import { Box, Button, LinearProgress, Typography, useTheme } from '@mui/material';
-import React, { useCallback,useRef, useState } from 'react';
-
+import { Box } from '@mui/material';
+import React from 'react';
+
+import { useUploadButton } from './UploadButton.hooks';
+import {
+  UploadDropzone,
+  UploadFeedback,
+  UploadTrigger,
+  type TriggerProps,
+} from './UploadButton.parts';
 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>
-    );
-  },
-);
+/**
+ * A file picker with an optional drag-and-drop surface.
+ *
+ * The body here is deliberately thin: selection rules live in
+ * `UploadButton.hooks`, appearance in `UploadButton.parts`. What remains is the
+ * wiring — the hidden input, which trigger to render, and the feedback beneath.
+ */
+const UploadButton = React.forwardRef<HTMLInputElement, UploadButtonProps>((props, ref) => {
+  const {
+    variant = 'default',
+    label = 'Upload File',
+    disabled = false,
+    multiple = false,
+    accept,
+    capture,
+    helperText,
+    icon,
+    className,
+    'data-testid': dataTestId,
+  } = props;
+  const { inputRef, inputId, state, drag, derived, openPicker, handleInputChange } =
+    useUploadButton(props);
+
+  const trigger: TriggerProps = {
+    label,
+    icon,
+    disabled,
+    className,
+    dataTestId,
+    describedBy: derived.describedBy,
+    onOpen: openPicker,
+  };
+
+  return (
+    <Box>
+      <input
+        ref={ref || inputRef}
+        id={inputId}
+        type="file"
+        accept={accept}
+        multiple={multiple}
+        capture={capture}
+        onChange={handleInputChange}
+        style={{ display: 'none' }}
+        disabled={disabled}
+        aria-hidden="true"
+      />
+
+      {variant === 'dropzone' ? (
+        <UploadDropzone {...trigger} isDragOver={state.isDragOver} drag={drag} />
+      ) : (
+        <UploadTrigger {...trigger} variant={variant} isUploading={derived.isUploading} />
+      )}
+
+      <UploadFeedback
+        isUploading={derived.isUploading}
+        progress={derived.progress}
+        helperText={helperText}
+        helperId={derived.helperId}
+        error={derived.error}
+        errorId={derived.errorId}
+        announceDragOver={variant === 'dropzone' && state.isDragOver}
+      />
+    </Box>
+  );
+});
 
 UploadButton.displayName = 'UploadButton';
 

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

@@ -19,6 +19,22 @@ export interface UploadButtonProps {
   /** File selection callback (required) */
   onSelect: (file: globalThis.File) => void;
 
+  /** Accept more than one file per pick/drop. Pair with {@link onSelectMany}. */
+  multiple?: boolean;
+
+  /**
+   * Batch selection callback. Called INSTEAD of `onSelect` when `multiple` is
+   * set, with every file that passed validation.
+   *
+   * Rejected files don't block the rest: the first rejection is surfaced as the
+   * component's error while the valid files are still handed over, so dropping
+   * a folder that happens to contain a PDF imports the XMLs beside it.
+   *
+   * {@link UploadButtonProps.onUpload} still applies, running once per accepted
+   * file in sequence.
+   */
+  onSelectMany?: (files: globalThis.File[]) => void;
+
   /** Optional built-in upload handler with progress */
   onUpload?: (file: globalThis.File) => Promise<void>;
 

package/src/components/form/index.ts

@@ -3,6 +3,7 @@ export * from './AddressAutocomplete';
 export * from './Autocomplete';
 export * from './Button';
 export * from './Calendar';
+export * from './CepField';
 export * from './Checkbox';
 export * from './CodeEditor';
 export * from './Command';

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

@@ -0,0 +1,143 @@
+'use client';
+
+import React, { useCallback, useMemo, useRef } from 'react';
+
+import { CepField as BaseCepField, type CepAddress } from '../../CepField';
+import { useFormContext } from '../FormContext';
+
+/** The resolved address parts a form can receive. */
+type CepPart = 'street' | 'neighborhood' | 'city' | 'state';
+
+/**
+ * Which form field receives each resolved part. Omit a part to leave it alone —
+ * a form with no bairro column simply doesn't map `neighborhood`.
+ */
+export type CepFills = Partial<Record<CepPart, string>>;
+
+/** Props for the `total-form` {@link CepField}. */
+export interface CepFieldProps {
+  /** Field name; also the key into the form's values/errors. */
+  name: string;
+  /** Optional visible label. Defaults to `CEP`. */
+  label?: string;
+  /** Resolve a complete CEP. Omit for a masked input with no lookup. */
+  lookup?: (cep: string) => Promise<CepAddress | null>;
+  /** Maps each resolved address part onto a field in THIS form. */
+  fills?: CepFills;
+  /** Milliseconds to wait after the last keystroke before looking up. */
+  debounceMs?: number;
+}
+
+const PARTS: readonly CepPart[] = ['street', 'neighborhood', 'city', 'state'];
+
+/** Ownership-aware writes into sibling form fields. */
+interface OwnedAutofill {
+  /** Write one field, where `''` means "no value for this part". */
+  write: (field: string, value: string) => void;
+  /** Blank every field this hook still owns. */
+  clearOwned: () => void;
+}
+
+/**
+ * The honesty rule, in one place: this hook remembers exactly what it wrote,
+ * writes only into fields that are empty or still hold its own value, and drops
+ * the ownership record when it blanks one. That single invariant is what lets
+ * autofill replace itself freely while never touching the user's typing.
+ */
+function useOwnedAutofill(): OwnedAutofill {
+  const { values, setFieldValue } = useFormContext();
+  // What we last auto-filled per target field, so a later lookup may replace
+  // its own value while a manual edit is preserved.
+  const autoFilledRef = useRef<Record<string, string>>({});
+  // Read values at call time without making them a dependency of the callback.
+  const valuesRef = useRef(values);
+  valuesRef.current = values;
+
+  const write = useCallback(
+    (field: string, value: string) => {
+      const current = (valuesRef.current[field] ?? '').trim();
+      const ours = autoFilledRef.current[field] === current;
+      if (current !== '' && !ours) return;
+      setFieldValue(field, value);
+      if (value) {
+        autoFilledRef.current[field] = value;
+      } else {
+        delete autoFilledRef.current[field];
+      }
+    },
+    [setFieldValue],
+  );
+
+  const clearOwned = useCallback(() => {
+    // Object.keys snapshots, so `write` may delete entries as we iterate.
+    for (const field of Object.keys(autoFilledRef.current)) {
+      write(field, '');
+    }
+  }, [write]);
+
+  return useMemo(() => ({ write, clearOwned }), [write, clearOwned]);
+}
+
+/**
+ * CEP field bound to {@link useFormContext}: masks and validates the CEP, then
+ * writes the resolved logradouro/bairro/cidade/UF straight into the sibling
+ * fields named by `fills`.
+ *
+ * It will not overwrite work the user has done. A target field is only written
+ * when it is empty, or when it still holds the exact value THIS component put
+ * there — so correcting the CEP re-fills the address, but a hand-edited street
+ * survives the next lookup.
+ *
+ * @example
+ * ```tsx
+ * <Fields.CepField
+ *   name="postalCode"
+ *   lookup={lookupCep}
+ *   fills={{ street: 'addressLine1', neighborhood: 'neighborhood', city: 'city', state: 'state' }}
+ * />
+ * ```
+ */
+export function CepField({
+  name,
+  label,
+  lookup,
+  fills,
+  debounceMs,
+}: CepFieldProps): React.ReactElement {
+  const { values, errors, setFieldValue } = useFormContext();
+  const { write, clearOwned } = useOwnedAutofill();
+
+  const handleResolved = useCallback(
+    (address: CepAddress) => {
+      if (!fills) return;
+      // Every mapped part is written on EVERY resolve, absent ones as ''. A
+      // "CEP geral" (a small município's catch-all) carries no logradouro, so
+      // skipping absent parts would leave the previous CEP's street here.
+      for (const part of PARTS) {
+        const field = fills[part];
+        if (field) write(field, address[part] ?? '');
+      }
+    },
+    [fills, write],
+  );
+
+  const handleChange = useCallback(
+    (masked: string) => setFieldValue(name, masked),
+    [name, setFieldValue],
+  );
+
+  return (
+    <BaseCepField
+      name={name}
+      label={label}
+      value={values[name] ?? ''}
+      error={errors[name]}
+      onChange={handleChange}
+      onLookup={lookup}
+      onResolved={handleResolved}
+      onNotFound={clearOwned}
+      debounceMs={debounceMs}
+      dataTestId={`total-form-field-${name}`}
+    />
+  );
+}

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

@@ -0,0 +1,61 @@
+'use client';
+
+import React from 'react';
+
+import { FormControl, FormLabel, FormMessage } from '../../Form';
+import { ToggleGroup } from '../../ToggleGroup';
+import type { ToggleOption } from '../../ToggleGroup';
+import { useFormContext } from '../FormContext';
+
+/** Props for the `total-form` {@link ToggleField}. */
+export interface ToggleFieldProps {
+  /** Field name; also the key into the form's values/errors. */
+  name: string;
+  /** The mutually-exclusive options (one is always selected). */
+  options: ToggleOption[];
+  /** Optional visible label rendered above the toggle. */
+  label?: string;
+}
+
+/**
+ * Exclusive toggle (segmented control) bound to {@link useFormContext} — a
+ * label-height-matched alternative to {@link SelectField} for a short, always-set
+ * enum. Composes the `Form*` primitives and the `ToggleGroup` control, reading
+ * its value from context and writing the chosen value back through it. Ignores a
+ * deselect (clicking the active segment) so a value is always kept.
+ *
+ * Renders its error via `total-form-field-<name>-message` and the toggle via
+ * `total-form-field-<name>` (each segment at `total-form-field-<name>-item-<value>`).
+ */
+export function ToggleField({ name, options, label }: ToggleFieldProps): 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>
+      )}
+      <ToggleGroup
+        variant="exclusive"
+        options={options}
+        value={values[name] ?? ''}
+        fullWidth
+        dataTestId={testId}
+        // Match the input field height so the toggle lines up in a form row.
+        sx={{ '& .MuiToggleButtonGroup-grouped': { height: 56 } }}
+        onChange={(_event, next) => {
+          if (typeof next === 'string') setFieldValue(name, next);
+        }}
+      />
+      {error && (
+        <FormMessage error dataTestId={`${testId}-message`}>
+          {error}
+        </FormMessage>
+      )}
+    </FormControl>
+  );
+}

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

@@ -1,4 +1,8 @@
+export { CepField } from './CepField';
+export type { CepFieldProps, CepFills } from './CepField';
 export { TextField } from './TextField';
 export type { TextFieldProps } from './TextField';
 export { SelectField } from './SelectField';
 export type { SelectFieldProps } from './SelectField';
+export { ToggleField } from './ToggleField';
+export type { ToggleFieldProps } from './ToggleField';

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

@@ -1,7 +1,7 @@
 'use client';
 
-import { validateFields } from '@12-apps/shared-helpers/forms';
-import type { ValidatorSchema } from '@12-apps/shared-helpers/forms';
+import { validateFields } from '@12-apps/forms-core';
+import type { ValidatorSchema } from '@12-apps/forms-core';
 import React, { useCallback, useMemo, useState } from 'react';
 
 import { Form } from '../Form';
@@ -39,7 +39,7 @@ export interface FormContainerProps<T extends Record<string, 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
+ * field validators from `@12-apps/forms-core` on submit, and only calls
  * `onSubmit` with the validated values when no field errors remain. Uses no
  * zod and no react-hook-form.
  *