@12-apps/ui 1.0.0 → 1.3.0

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

@@ -0,0 +1,210 @@
+import AttachFileOutlined from '@mui/icons-material/AttachFileOutlined';
+import CloudUploadOutlined from '@mui/icons-material/CloudUploadOutlined';
+import { Box, Button, LinearProgress, Typography, useTheme } from '@mui/material';
+import type React from 'react';
+
+import type { DragHandlers } from './UploadButton.hooks';
+import type { UploadButtonProps } from './UploadButton.types';
+
+/** Shared shape for the two trigger variants. */
+export interface TriggerProps {
+  label: string;
+  icon?: React.ReactNode;
+  disabled: boolean;
+  className?: string;
+  dataTestId?: string;
+  describedBy?: string;
+  onOpen: () => void;
+}
+
+/** The drag-and-drop surface. */
+export function UploadDropzone({
+  label,
+  icon,
+  disabled,
+  className,
+  dataTestId,
+  describedBy,
+  onOpen,
+  isDragOver,
+  drag,
+}: TriggerProps & { isDragOver: boolean; drag: DragHandlers }): React.ReactElement {
+  const theme = useTheme();
+  return (
+    <Box
+      component="div"
+      {...drag}
+      onClick={onOpen}
+      sx={{
+        border: `2px dashed ${isDragOver ? theme.palette.primary.main : theme.palette.divider}`,
+        borderRadius: 2,
+        padding: 3,
+        textAlign: 'center',
+        cursor: disabled ? 'not-allowed' : 'pointer',
+        backgroundColor: 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={(event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') return;
+        event.preventDefault();
+        onOpen();
+      }}
+      aria-describedby={describedBy}
+      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>
+  );
+}
+
+/** MUI variant for each non-dropzone appearance. */
+const MUI_VARIANT = { outline: 'outlined', ghost: 'text' } as const;
+
+/** The plain-button trigger. */
+export function UploadTrigger({
+  label,
+  icon,
+  disabled,
+  className,
+  dataTestId,
+  describedBy,
+  onOpen,
+  variant,
+  isUploading,
+}: TriggerProps & {
+  variant: NonNullable<UploadButtonProps['variant']>;
+  isUploading: boolean;
+}): React.ReactElement {
+  const theme = useTheme();
+  return (
+    <Button
+      variant={MUI_VARIANT[variant as keyof typeof MUI_VARIANT] ?? 'contained'}
+      disabled={disabled || isUploading}
+      onClick={onOpen}
+      startIcon={icon || <AttachFileOutlined />}
+      className={className}
+      data-testid={dataTestId}
+      aria-describedby={describedBy}
+      sx={{
+        ...(variant === 'ghost' && {
+          '&:hover': { backgroundColor: `${theme.palette.primary.main}08` },
+        }),
+      }}
+    >
+      {isUploading ? 'Uploading...' : label}
+    </Button>
+  );
+}
+
+/** The screen-reader live region — drag, progress and error announcements. */
+function UploadAnnouncer({
+  announceDragOver,
+  isUploading,
+  progress,
+  error,
+}: {
+  announceDragOver: boolean;
+  isUploading: boolean;
+  progress: number;
+  error: string | null;
+}): React.ReactElement {
+  return (
+    <div
+      aria-live="polite"
+      aria-atomic="true"
+      className="sr-only"
+      style={{
+        position: 'absolute',
+        left: '-10000px',
+        width: '1px',
+        height: '1px',
+        overflow: 'hidden',
+      }}
+    >
+      {announceDragOver && 'File ready to drop'}
+      {isUploading && `Upload in progress: ${Math.round(progress)}%`}
+      {error && `Error: ${error}`}
+    </div>
+  );
+}
+
+/** Progress bar, helper text, error text and the live region. */
+export function UploadFeedback({
+  isUploading,
+  progress,
+  helperText,
+  helperId,
+  error,
+  errorId,
+  announceDragOver,
+}: {
+  isUploading: boolean;
+  progress: number;
+  helperText?: string;
+  helperId?: string;
+  error: string | null;
+  errorId?: string;
+  announceDragOver: boolean;
+}): React.ReactElement {
+  return (
+    <>
+      {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 && !error && (
+        <Typography
+          id={helperId}
+          variant="caption"
+          color="text.secondary"
+          sx={{ display: 'block', mt: 0.5 }}
+        >
+          {helperText}
+        </Typography>
+      )}
+
+      {error && (
+        <Typography
+          id={errorId}
+          variant="caption"
+          color="error"
+          sx={{ display: 'block', mt: 0.5 }}
+          role="alert"
+        >
+          {error}
+        </Typography>
+      )}
+
+      <UploadAnnouncer
+        announceDragOver={announceDragOver}
+        isUploading={isUploading}
+        progress={progress}
+        error={error}
+      />
+    </>
+  );
+}

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

@@ -1,4 +1,5 @@
-import { CloudUploadOutlined,PhotoCameraOutlined } from '@mui/icons-material';
+import CloudUploadOutlined from '@mui/icons-material/CloudUploadOutlined';
+import PhotoCameraOutlined from '@mui/icons-material/PhotoCameraOutlined';
 import { Box } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { action } from 'storybook/actions';

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

@@ -2,6 +2,8 @@ import { Box, FormControl, FormLabel } from '@mui/material';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 import { expect, fn,userEvent, waitFor, within } from 'storybook/test';
 
+import React from 'react';
+
 import { UploadButton } from './UploadButton';
 
 const meta: Meta<typeof UploadButton> = {
@@ -175,9 +177,11 @@ export const KeyboardNavigation: Story = {
     const canvas = within(canvasElement);
     const uploadButton = canvas.getByRole('button');
 
-    // Test keyboard navigation
-    uploadButton.focus();
-    await expect(uploadButton).toHaveFocus();
+    // Test keyboard navigation. Focus is driven with `tab()` and awaited via
+    // waitFor: a bare `.focus()` plus an immediate assertion races the browser's
+    // own focus handling.
+    await userEvent.tab();
+    await waitFor(() => expect(uploadButton).toHaveFocus());
 
     // Test Enter key activation
     await userEvent.keyboard('{Enter}');
@@ -232,7 +236,7 @@ export const FocusManagement: Story = {
 
     // Test focus management
     await userEvent.tab();
-    await expect(uploadButton).toHaveFocus();
+    await waitFor(() => expect(uploadButton).toHaveFocus());
 
     // Test focus styles
     await expect(uploadButton).toBeVisible();
@@ -452,3 +456,118 @@ export const IntegrationTest: Story = {
     await expect(documentInput).toBeInTheDocument();
   },
 };
+
+/**
+ * Multi-file mode hands the whole selection over at once. Single-file callers
+ * are untouched — they neither set `multiple` nor pass `onSelectMany`.
+ */
+export const MultipleFilesGoToOnSelectMany: Story = {
+  render: function MultipleStory() {
+    const [names, setNames] = React.useState<string[]>([]);
+    return (
+      <Box>
+        <UploadButton
+          variant="dropzone"
+          multiple
+          accept=".xml"
+          onSelect={fn()}
+          onSelectMany={(files) => setNames(files.map((file) => file.name))}
+          data-testid="multi-dropzone"
+        />
+        <span data-testid="picked">{names.join(',')}</span>
+      </Box>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvasElement.querySelector('input[type="file"]') as HTMLInputElement;
+
+    // `multiple` reaches the real input, so the OS picker allows a selection.
+    await expect(input).toHaveAttribute('multiple');
+
+    await userEvent.upload(input, [
+      new File(['<nfeProc/>'], 'a.xml', { type: 'text/xml' }),
+      new File(['<nfeProc/>'], 'b.xml', { type: 'text/xml' }),
+    ]);
+
+    await waitFor(() => expect(canvas.getByTestId('picked')).toHaveTextContent('a.xml,b.xml'));
+  },
+};
+
+/**
+ * A rejected file does not cost the caller the valid ones beside it: the error
+ * is surfaced AND the good files are handed over. Dropping a folder that also
+ * holds a PDF should still import the XMLs.
+ */
+export const RejectedFilesDoNotBlockTheRest: Story = {
+  render: function PartialStory() {
+    const [names, setNames] = React.useState<string[]>([]);
+    return (
+      <Box>
+        <UploadButton
+          variant="dropzone"
+          multiple
+          onSelect={fn()}
+          onSelectMany={(files) => setNames(files.map((file) => file.name))}
+          validate={(file) => (file.name.endsWith('.xml') ? null : 'Somente arquivos XML.')}
+          data-testid="partial-dropzone"
+        />
+        <span data-testid="accepted">{names.join(',')}</span>
+      </Box>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvasElement.querySelector('input[type="file"]') as HTMLInputElement;
+
+    await userEvent.upload(input, [
+      new File(['<nfeProc/>'], 'nota.xml', { type: 'text/xml' }),
+      new File(['%PDF'], 'danfe.pdf', { type: 'application/pdf' }),
+    ]);
+
+    // The XML still arrives…
+    await waitFor(() => expect(canvas.getByTestId('accepted')).toHaveTextContent('nota.xml'));
+    // …and the rejection is reported rather than swallowed.
+    await waitFor(() => expect(canvas.getByText('Somente arquivos XML.')).toBeInTheDocument());
+  },
+};
+
+/**
+ * `onUpload` means the same thing in both modes. It ran only for single files
+ * once, which made it a silent no-op for a multi-file caller — nothing failed,
+ * nothing uploaded.
+ */
+export const MultipleFilesStillRunOnUpload: Story = {
+  render: function MultiUploadStory() {
+    const [uploaded, setUploaded] = React.useState<string[]>([]);
+    return (
+      <Box>
+        <UploadButton
+          variant="dropzone"
+          multiple
+          onSelect={fn()}
+          onSelectMany={fn()}
+          onUpload={async (file) => {
+            setUploaded((prev) => [...prev, file.name]);
+          }}
+          data-testid="multi-upload-dropzone"
+        />
+        <span data-testid="uploaded">{uploaded.join(',')}</span>
+      </Box>
+    );
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvasElement.querySelector('input[type="file"]') as HTMLInputElement;
+
+    await userEvent.upload(input, [
+      new File(['a'], 'a.xml', { type: 'text/xml' }),
+      new File(['b'], 'b.xml', { type: 'text/xml' }),
+    ]);
+
+    // Every accepted file goes through the upload path, in order.
+    await waitFor(() => expect(canvas.getByTestId('uploaded')).toHaveTextContent('a.xml,b.xml'), {
+      timeout: 5000,
+    });
+  },
+};