@recursica/mui-adapter 0.22.0 → 0.23.0

package/src/components/FileUpload/FileUpload.tsx

@@ -1,8 +1,352 @@
-import React from "react";
-import "./FileUpload.module.css";
+import React, { forwardRef, useEffect, useRef, useState } from "react";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { Button } from "../Button/Button";
+import { Chip } from "../Chip/Chip";
+import {
+  FormControlWrapper,
+  type RecursicaFormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import styles from "./FileUpload.module.css";
 
-export type FileUploadProps = React.HTMLAttributes<HTMLDivElement>;
+import {
+  fileMatchesAccept,
+  type RecursicaFileUploadItem,
+  type RecursicaFileUploadProps as BaseRecursicaFileUploadProps,
+} from "@recursica/adapter-common";
+export type { RecursicaFileUploadItem };
 
-export const FileUpload: React.FC<FileUploadProps> = (props) => {
-  return <div {...props}>FileUpload</div>;
-};
+export interface RecursicaFileUploadProps
+  extends Omit<
+      React.HTMLAttributes<HTMLDivElement>,
+      "children" | "onDrop" | "onChange"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    BaseRecursicaFileUploadProps {
+  /** Visually forces the mandatory asterisk. Accepted for API parity with other adapters; MUI's own `required` already renders the asterisk, so this has no separate effect here. */
+  withAsterisk?: boolean;
+}
+
+export type FileUploadProps = RecursicaOverStyled<RecursicaFileUploadProps>;
+
+function UploadIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M12 3v12" />
+      <path d="M7 8l5-5 5 5" />
+      <path d="M4 21h16" />
+    </svg>
+  );
+}
+
+/**
+ * A dropzone for uploading files, with a native browse-button fallback and a
+ * removable-chip list of the currently selected files.
+ *
+ * @example
+ * <FileUpload
+ *   label="Upload Files"
+ *   assistiveText="Max file size 5MB"
+ *   files={files}
+ *   onFilesAdded={(added) => setFiles((f) => [...f, ...added.map((file) => ({ file }))])}
+ *   onFileRemove={(id) => setFiles((f) => f.filter((item) => (item.id ?? item.file.name) !== id))}
+ * />
+ */
+export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
+  function FileUpload(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      labelActionArea,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+
+      files,
+      onFilesAdded,
+      onFileRemove,
+      accept,
+      multiple = true,
+      maxSize,
+      maxFiles,
+      onFilesRejected,
+      invalidFileTypeMessage = "File type not accepted",
+      maxFilesMessage = `Maximum of ${maxFiles} files allowed`,
+      icon,
+      dropzoneLabel = "Drag and drop files here to upload",
+      browseButtonLabel = "Browse files",
+      removeFileLabel = "Remove",
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    // Whether the most recent drop/pick attempt included a file that failed the `accept` check —
+    // surfaced as the control's error state (see `effectiveError` below) rather than left for the
+    // integrator to wire up themselves.
+    const [invalidTypeRejected, setInvalidTypeRejected] = useState(false);
+    // Whether the most recent drop/pick attempt included a file that would have pushed the total
+    // past `maxFiles` — surfaced the same way as `invalidTypeRejected` (see `effectiveError`).
+    const [tooManyFilesRejected, setTooManyFilesRejected] = useState(false);
+
+    const handleFiles = (incoming: FileList | File[]) => {
+      if (disabled) return;
+      const list = Array.from(incoming);
+      if (list.length === 0) return;
+
+      const currentCount = files?.length ?? 0;
+      const accepted: File[] = [];
+      const rejected: File[] = [];
+      let hasInvalidType = false;
+      let hasTooMany = false;
+      for (const file of list) {
+        const isInvalidType = !fileMatchesAccept(file, accept);
+        if (isInvalidType) hasInvalidType = true;
+        const isTooLarge = maxSize !== undefined && file.size > maxSize;
+        const wouldExceedMax =
+          maxFiles !== undefined && currentCount + accepted.length >= maxFiles;
+        if (wouldExceedMax) hasTooMany = true;
+        const isRejected = isInvalidType || isTooLarge || wouldExceedMax;
+        (isRejected ? rejected : accepted).push(file);
+      }
+      setInvalidTypeRejected(hasInvalidType);
+      setTooManyFilesRejected(hasTooMany);
+      if (accepted.length > 0) onFilesAdded?.(accepted);
+      if (rejected.length > 0) onFilesRejected?.(rejected);
+    };
+
+    // Counts nested dragenter/dragleave pairs (they fire for every child element the pointer
+    // crosses, not just the dropzone itself) so the drag-over visual state only clears once the
+    // pointer has actually left the dropzone, not just moved between its children.
+    const dragCounterRef = useRef(0);
+    const [isDragging, setIsDragging] = useState(false);
+
+    const handleDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current += 1;
+      setIsDragging(true);
+    };
+
+    const handleDragLeave = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current -= 1;
+      if (dragCounterRef.current <= 0) {
+        dragCounterRef.current = 0;
+        setIsDragging(false);
+      }
+    };
+
+    const handleDragOver = (event: React.DragEvent<HTMLDivElement>) => {
+      // Required so the browser treats this element as a valid drop target.
+      event.preventDefault();
+    };
+
+    const handleDrop = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current = 0;
+      setIsDragging(false);
+      handleFiles(event.dataTransfer.files);
+    };
+
+    const openFilePicker = () => {
+      if (disabled) return;
+      inputRef.current?.click();
+    };
+
+    const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+      if (event.target.files) handleFiles(event.target.files);
+      // Reset so picking the same file again still fires a change event.
+      event.target.value = "";
+    };
+
+    // Roving tabindex across the file chip list: only the "active" chip's remove icon is a tab
+    // stop (Tab lands on the first chip), and Left/Right/Up/Down move it — see
+    // FILEUPLOAD_IMPLEMENTATION_NOTES.md.
+    const [activeChipIndex, setActiveChipIndex] = useState(0);
+    const removeIconRefs = useRef<Array<HTMLSpanElement | null>>([]);
+    const prevFileCountRef = useRef(files?.length ?? 0);
+
+    useEffect(() => {
+      const count = files?.length ?? 0;
+      // A chip was removed (via keyboard or otherwise) — keep focus in the list, clamped to the
+      // new length, rather than letting it fall back to the document body.
+      if (count > 0 && count < prevFileCountRef.current) {
+        const nextIndex = Math.min(activeChipIndex, count - 1);
+        setActiveChipIndex(nextIndex);
+        removeIconRefs.current[nextIndex]?.focus();
+      }
+      prevFileCountRef.current = count;
+      // Only react to the file list itself shrinking/growing, not to activeChipIndex changes.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [files]);
+
+    const handleFileListKeyDown = (
+      event: React.KeyboardEvent<HTMLDivElement>,
+    ) => {
+      const count = files?.length ?? 0;
+      if (count === 0) return;
+      let nextIndex: number | undefined;
+      if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+        nextIndex = (activeChipIndex + 1) % count;
+      } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+        nextIndex = (activeChipIndex - 1 + count) % count;
+      }
+      if (nextIndex === undefined) return;
+      event.preventDefault();
+      setActiveChipIndex(nextIndex);
+      removeIconRefs.current[nextIndex]?.focus();
+    };
+
+    // The built-in `accept`-mismatch message is only shown when the integrator hasn't supplied
+    // their own `error` — an explicit error always wins.
+    const effectiveError =
+      error ??
+      (invalidTypeRejected
+        ? invalidFileTypeMessage
+        : tooManyFilesRejected
+          ? maxFilesMessage
+          : undefined);
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <FormControlWrapper
+        overStyled={overStyled}
+        className={wrapperClass}
+        style={style}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        labelActionArea={labelActionArea}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={effectiveError}
+        required={required}
+        disabled={disabled}
+        id={id}
+      >
+        <div
+          ref={ref}
+          className={styles.root}
+          data-disabled={disabled ? "true" : undefined}
+          data-error={effectiveError ? "true" : undefined}
+          {...restRecord}
+        >
+          {!readOnly && (
+            <div
+              className={styles.dropzone}
+              data-dragging={isDragging ? "true" : undefined}
+              onDragEnter={disabled ? undefined : handleDragEnter}
+              onDragLeave={disabled ? undefined : handleDragLeave}
+              onDragOver={disabled ? undefined : handleDragOver}
+              onDrop={disabled ? undefined : handleDrop}
+            >
+              <span className={styles.uploadIcon}>
+                {icon ?? <UploadIcon />}
+              </span>
+              <span className={styles.dropzoneText}>{dropzoneLabel}</span>
+              <Button
+                variant="outline"
+                disabled={disabled}
+                onClick={openFilePicker}
+              >
+                {browseButtonLabel}
+              </Button>
+              <input
+                ref={inputRef}
+                type="file"
+                hidden
+                accept={accept}
+                multiple={multiple}
+                disabled={disabled}
+                onChange={handleInputChange}
+              />
+            </div>
+          )}
+
+          {files &&
+            files.length > 0 &&
+            (readOnly ? (
+              <div className={styles.fileList}>
+                {files.map((item: RecursicaFileUploadItem) => {
+                  const itemId = item.id ?? item.file.name;
+                  return (
+                    <Chip key={itemId} tabIndex={-1}>
+                      {item.file.name}
+                    </Chip>
+                  );
+                })}
+              </div>
+            ) : (
+              <div
+                className={styles.fileList}
+                onKeyDown={handleFileListKeyDown}
+              >
+                {files.map((item: RecursicaFileUploadItem, index) => {
+                  const itemId = item.id ?? item.file.name;
+                  return (
+                    <Chip
+                      key={itemId}
+                      tabIndex={-1}
+                      removeLabel={removeFileLabel}
+                      removeTabIndex={index === activeChipIndex ? 0 : -1}
+                      removeIconRef={(el) => {
+                        removeIconRefs.current[index] = el;
+                      }}
+                      onRemove={
+                        disabled ? undefined : () => onFileRemove?.(itemId)
+                      }
+                    >
+                      {item.file.name}
+                    </Chip>
+                  );
+                })}
+              </div>
+            ))}
+        </div>
+      </FormControlWrapper>
+    );
+  },
+);
+
+FileUpload.displayName = "FileUpload";

package/src/components/FileUpload/USAGE.md

@@ -14,15 +14,29 @@ import { FileUpload } from "@recursica/mui-adapter";
 
 ## 2. Basic Example
 
+`FileUpload` is a **controlled** component: it never stores the selected files itself. `onFilesAdded` reports newly dropped/picked files, `onFileRemove` reports which file was removed, and you own the `files` array in between.
+
 ```tsx
-import React from "react";
+import React, { useState } from "react";
 import { FileUpload } from "@recursica/mui-adapter";
+import { type RecursicaFileUploadItem } from "@recursica/adapter-common";
 
 export default function Demo() {
+  const [files, setFiles] = useState<RecursicaFileUploadItem[]>([]);
+
   return (
     <FileUpload
-      label="Drop files here"
-      onDrop={(files) => console.log(files)}
+      label="Upload Files"
+      assistiveText="Max file size 5MB"
+      files={files}
+      onFilesAdded={(added) =>
+        setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+      }
+      onFileRemove={(id) =>
+        setFiles((prev) =>
+          prev.filter((item) => (item.id ?? item.file.name) !== id),
+        )
+      }
     />
   );
 }
@@ -30,12 +44,156 @@ export default function Demo() {
 
 ---
 
-## 3. Design System Integration
+## 3. Props Reference
+
+| Prop                     | Type                        | Description                                                                                                                                                                                                                          |
+| ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `files`                  | `RecursicaFileUploadItem[]` | Files currently selected, rendered as removable chips below the dropzone. Each item is `{ file: File; id?: string }`.                                                                                                                |
+| `onFilesAdded`           | `(files: File[]) => void`   | Called with newly dropped/picked files. Only the new files — merge them into `files` yourself.                                                                                                                                       |
+| `onFileRemove`           | `(id: string) => void`      | Called with a file's `id` (or `file.name` if no `id` was given) when its remove (X) icon is activated.                                                                                                                               |
+| `accept`                 | `string`                    | Native `accept` attribute (e.g. `".pdf,.png"` or `"image/*"`) — constrains the picker dialog, and is also enforced against dropped files (via `onFilesRejected`), since the browser never applies `accept` to a `drop` event itself. |
+| `multiple`               | `boolean`                   | Whether more than one file can be selected/dropped at once. Defaults to `true`.                                                                                                                                                      |
+| `maxSize`                | `number`                    | Maximum size per file, in bytes. Oversized files go to `onFilesRejected` instead of `onFilesAdded`.                                                                                                                                  |
+| `maxFiles`               | `number`                    | Maximum total number of files allowed in `files`. Files that would exceed it go to `onFilesRejected` instead of `onFilesAdded`.                                                                                                      |
+| `onFilesRejected`        | `(files: File[]) => void`   | Called with files rejected for exceeding `maxSize`/`maxFiles` or not matching `accept`.                                                                                                                                              |
+| `invalidFileTypeMessage` | `React.ReactNode`           | Error message shown when a file is rejected for not matching `accept`. Defaults to `"File type not accepted"`. An explicit `error` prop always takes priority over this.                                                             |
+| `maxFilesMessage`        | `React.ReactNode`           | Error message shown when a file is rejected for exceeding `maxFiles`. Defaults to `"Maximum of {maxFiles} files allowed"`. An explicit `error` prop always takes priority over this.                                                 |
+| `icon`                   | `React.ReactNode`           | Icon shown above the dropzone label. Defaults to the built-in upload icon.                                                                                                                                                           |
+| `dropzoneLabel`          | `React.ReactNode`           | Text shown inside the dropzone. Defaults to `"Drag and drop files here to upload"`.                                                                                                                                                  |
+| `browseButtonLabel`      | `React.ReactNode`           | Label for the button that opens the native file picker. Defaults to `"Browse files"`.                                                                                                                                                |
+| `removeFileLabel`        | `string`                    | Screen-reader label for each file chip's remove button. Defaults to `"Remove"`.                                                                                                                                                      |
+| `disabled`               | `boolean`                   | Disables the dropzone, browse button, and every file chip's remove icon.                                                                                                                                                             |
+| `readOnly`               | `boolean`                   | Renders `files` as a static chip list with no remove icon, and omits the dropzone/browse button entirely.                                                                                                                            |
+
+`FileUpload` also accepts the standard Recursica form-control props (`label`, `assistiveText`, `error`, `required`, `withAsterisk`, `formLayout`, `labelSize`, `labelAlignment`, `labelOptionalText`, `labelWithEditIcon`, `onLabelEditClick`) — see [FormControlWrapper's USAGE.md](../FormControlWrapper/USAGE.md) for how these behave.
+
+---
+
+## 4. Rejecting Oversized Files
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Max file size 5MB"
+  maxSize={5 * 1024 * 1024}
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFilesRejected={(rejected) =>
+    setError(`${rejected.length} file(s) exceeded the 5MB limit.`)
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+---
+
+## 5. Rejecting Files by Extension/MIME Type
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Only .pdf and .png files are accepted"
+  accept=".pdf,.png"
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+This applies equally to a file picked via "Browse files" and one dragged directly onto the
+dropzone — the browser's own `accept` filtering never covers drag-and-drop, so `FileUpload`
+re-validates it itself before calling `onFilesAdded`/`onFilesRejected`.
+
+A mismatched file automatically puts the control into its error state with the message
+`"File type not accepted"` — no need to wire `onFilesRejected` into your own `error` prop just to
+show something. Override the message with `invalidFileTypeMessage`, or pass your own `error` prop
+to take over the error state entirely:
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  accept=".pdf,.png"
+  invalidFileTypeMessage="Only PDF and PNG files are supported"
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+---
+
+## 6. Limiting the Number of Files
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Up to 2 files allowed"
+  maxFiles={2}
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+Once `files` reaches `maxFiles`, further dropped/picked files are rejected the same way an
+`accept` mismatch is — automatically switching the control into its error state with the default
+`maxFilesMessage` ("Maximum of 2 files allowed" for the example above). Override the message with
+`maxFilesMessage`, or pass your own `error` prop to take over the error state entirely.
+
+---
+
+## 7. Read-only Mode
+
+```tsx
+<FileUpload label="Uploaded Files" readOnly files={files} />
+```
+
+Renders `files` as a plain, non-removable chip list with no dropzone or Browse button — for
+displaying files that were already submitted and can no longer be changed. `onFilesAdded`/
+`onFileRemove` aren't called in this mode since there's nothing to add or remove.
+
+---
+
+## 8. Keyboard Navigation of the File List
+
+Once files are selected, their chips form a single roving-tabindex group, not one tab stop per
+chip: `Tab` lands on the first chip's remove icon, `Enter`/`Space` removes the focused chip, and
+`ArrowLeft`/`ArrowRight`/`ArrowUp`/`ArrowDown` move focus between chips (wrapping at both ends).
+This is a group-level pattern, not an option on `Chip` used standalone elsewhere. (Not applicable
+in `readOnly` mode, which has no remove icons to navigate to.)
+
+---
+
+## 9. Design System Integration
 
 All Recursica components in the `@recursica/mui-adapter` package adhere strictly to design system spacing, scaling, and behavior patterns.
 
 > [!IMPORTANT]
 >
-> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **Anti-override protection**: Rogue style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
 > - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
 > - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/index.ts

@@ -14,7 +14,6 @@ export const Stack = rawComponents.Stack;
 export const Container = rawComponents.Container;
 export const Typography = rawComponents.Typography;
 export const FileInput = rawComponents.FileInput;
-export const FileUpload = rawComponents.FileUpload;
 
 // Statically wrap and export components to inject overStyled visual highlight in dev mode
 export const Accordion = wrapComponent(
@@ -65,6 +64,9 @@ export const DatePicker = wrapComponent(
 export const Dropdown = wrapComponent(
   rawComponents.Dropdown,
 ) as typeof rawComponents.Dropdown;
+export const FileUpload = wrapComponent(
+  rawComponents.FileUpload,
+) as typeof rawComponents.FileUpload;
 export const FormControlLayout = wrapComponent(
   rawComponents.FormControlLayout,
 ) as typeof rawComponents.FormControlLayout;