@recursica/mui-adapter 0.22.0 → 0.23.0

package/src/components/FileUpload/FileUpload.module.css

@@ -1,40 +1,205 @@
 /* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_border-radius */
+   - border-style has no usable var(...) form: the Figma-exported token's value is the literal
+     string `"dashed"` (quotes included), which is not a valid CSS <line-style> keyword — the same
+     class of "structural, not tokenized" property the canonical guide already treats border-style
+     as (see .root's own HARDCODED VALUES note below and TimePicker/DatePicker's identical
+     hardcoded `border-style: solid`). Hardcoded to the keyword `dashed` instead.
+   - properties_icon-size has no equivalent: unlike TextField/DatePicker, file-upload has no
+     dedicated icon-size token. Sized to visually match the Figma reference instead (see
+     HARDCODED VALUES below). */
 /* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_border-style */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_item-gap */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_list-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_padding */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_properties_vertical-element-gap */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_layouts_side-by-side_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_layouts_stacked_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_default_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_default_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_default_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_default_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_default_properties_colors_upload-icon */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_upload-icon */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_error_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_upload-icon */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_focus_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_focus_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_focus_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_focus_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_file-upload_variants_states_focus_properties_colors_upload-icon */
+
+/* HARDCODED VALUES:
+   - .root: display: flex; flex-direction: column; width: 100% — structural layout, not a design
+     token concern (matches how other block-level components like Layer are laid out).
+   - .dropzone: border-style: dashed — see EXEMPTIONS above.
+   - .uploadIcon: width/height: 2rem — no icon-size token exists for file-upload (unlike
+     TextField/DatePicker); sized to visually match the Figma reference. Revisit if a dedicated
+     token is ever added. */
+
+/* LAYOUT SPACING OVERRIDES:
+   - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
+.layoutOverride {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_file-upload_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.layoutOverride[data-form-layout="side-by-side"] {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_file-upload_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+.root {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  gap: var(--recursica_ui-kit_components_file-upload_properties_list-spacing);
+}
+
+.dropzone {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  position: relative; /* HARDCODE: anchors the drag-over overlay below */
+  box-sizing: border-box;
+  width: 100%;
+  border-style: dashed; /* HARDCODE: see EXEMPTIONS above */
+  border-width: var(
+    --recursica_ui-kit_components_file-upload_properties_border-size
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_file-upload_properties_border-radius
+  );
+  border-color: var(
+    --recursica_ui-kit_components_file-upload_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_file-upload_properties_colors_background-color
+  );
+  padding: var(--recursica_ui-kit_components_file-upload_properties_padding);
+  gap: var(
+    --recursica_ui-kit_components_file-upload_properties_vertical-element-gap
+  );
+}
+
+/* Dragging-over state: reuses the generic hover overlay recipe (see Button.module.css) for the
+   background, and the shared "selected" border bridge var FormControlWrapper already exposes
+   (see FormControlWrapper.module.css) for the border — file-upload has no color tokens of its own
+   for this state. See "Dragging-over visual state" in FILEUPLOAD_IMPLEMENTATION_NOTES.md. */
+.dropzone > * {
+  position: relative;
+  z-index: 1;
+}
+.dropzone::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  z-index: 0;
+  pointer-events: none;
+  transition: opacity 150ms ease;
+  opacity: 0;
+  background-color: var(--recursica_brand_states_hover_color);
+}
+.dropzone[data-dragging="true"] {
+  border-color: var(--form-field-border-selected);
+}
+.dropzone[data-dragging="true"]::after {
+  opacity: var(--recursica_brand_states_hover_opacity);
+}
+
+.uploadIcon {
+  display: flex;
+  width: 2rem; /* HARDCODE: see EXEMPTIONS above */
+  height: 2rem; /* HARDCODE: see EXEMPTIONS above */
+  color: var(
+    --recursica_ui-kit_components_file-upload_properties_colors_upload-icon
+  );
+}
+
+.uploadIcon svg {
+  width: 100%;
+  height: 100%;
+}
+
+.dropzoneText {
+  font-family: var(
+    --recursica_ui-kit_components_file-upload_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_file-upload_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_file-upload_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_file-upload_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_file-upload_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_file-upload_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_file-upload_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_file-upload_properties_text_text-transform
+  );
+  color: var(
+    --recursica_ui-kit_components_file-upload_properties_colors_text-color
+  );
+  text-align: center;
+}
+
+.fileList {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--recursica_ui-kit_components_file-upload_properties_item-gap);
+}
+
+/* -------------------------------------
+   STATE CASCADE ARCHITECTURE
+-------------------------------------- */
+
+/* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-error="true"] .dropzone {
+  border-width: var(
+    --recursica_ui-kit_components_file-upload_variants_states_error_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_background-color
+  );
+}
+
+.root[data-error="true"] .dropzoneText {
+  color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_text-color
+  );
+}
+
+.root[data-error="true"] .uploadIcon {
+  color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_error_properties_colors_upload-icon
+  );
+}
+
+/* Disabled State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-disabled="true"] .dropzone {
+  border-width: var(
+    --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_border-size
+  );
+  border-color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_background-color
+  );
+}
+
+.root[data-disabled="true"] .dropzoneText {
+  color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_text-color
+  );
+}
+
+.root[data-disabled="true"] .uploadIcon {
+  color: var(
+    --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_colors_upload-icon
+  );
+}
+
+.root[data-disabled="true"] {
+  opacity: var(
+    --recursica_ui-kit_components_file-upload_variants_states_disabled_properties_opacity
+  );
+  cursor: not-allowed;
+}

package/src/components/FileUpload/FileUpload.stories.tsx

@@ -1,18 +1,362 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import React, { useState } from "react";
 import { FileUpload } from "./FileUpload";
-import { ComingSoon } from "@recursica/storybook-template";
+import { type RecursicaFileUploadItem } from "@recursica/adapter-common";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+function mockFile(name: string, size = 1024) {
+  return new File([new Uint8Array(size)], name);
+}
 
 const meta: Meta<typeof FileUpload> = {
-  title: "UI-Kit/🚧 FileUpload",
+  title: "UI-Kit/FileUpload",
   component: FileUpload,
   tags: ["autodocs"],
-  argTypes: {},
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`FileUpload\` component is a drag-and-drop dropzone with a native browse-button fallback, integrated directly into the \`FormControlWrapper\` architecture. Selected files render as a removable-chip list below the dropzone.
+
+### Examples
+\`\`\`tsx
+<FileUpload
+  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))
+  }
+/>
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    accept: {
+      control: "text",
+      description:
+        "Native `accept` attribute for the file picker (e.g. `.pdf,.png`).",
+    },
+    multiple: {
+      control: "boolean",
+      description: "Whether multiple files can be selected/dropped at once.",
+    },
+    maxSize: {
+      control: "number",
+      description: "Maximum size per file, in bytes.",
+    },
+    maxFiles: {
+      control: "number",
+      description: "Maximum total number of files allowed.",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Renders `files` as a static chip list with no remove icon, and hides the dropzone.",
+    },
+    dropzoneLabel: {
+      control: "text",
+    },
+    browseButtonLabel: {
+      control: "text",
+    },
+    icon: {
+      table: { disable: true },
+    },
+    files: {
+      table: { disable: true },
+    },
+    onFilesAdded: {
+      table: { disable: true },
+    },
+    onFileRemove: {
+      table: { disable: true },
+    },
+    onFilesRejected: {
+      table: { disable: true },
+    },
+  },
 };
 
 export default meta;
 
 type Story = StoryObj<typeof FileUpload>;
+type FileUploadStoryArgs = React.ComponentProps<typeof FileUpload> & {
+  withLayer?: boolean;
+  layer?: number;
+};
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="FileUpload" />,
+  args: {
+    label: "Upload Files",
+    assistiveText: "Max file size 5MB",
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files, setFiles] = useState<RecursicaFileUploadItem[]>([]);
+    return (
+      <FileUpload
+        {...args}
+        files={files}
+        onFilesAdded={(added) =>
+          setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+        }
+        onFileRemove={(id) =>
+          setFiles((prev) =>
+            prev.filter((item) => (item.id ?? item.file.name) !== id),
+          )
+        }
+      />
+    );
+  },
+};
+
+export const WithFiles: Story = {
+  args: {
+    label: "Upload Files",
+    assistiveText: "Max file size 5MB",
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files, setFiles] = useState<RecursicaFileUploadItem[]>([
+      { file: mockFile("document.pdf") },
+      { file: mockFile("image.png") },
+      { file: mockFile("spreadsheet.xlsx") },
+    ]);
+    return (
+      <FileUpload
+        {...args}
+        files={files}
+        onFilesAdded={(added) =>
+          setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+        }
+        onFileRemove={(id) =>
+          setFiles((prev) =>
+            prev.filter((item) => (item.id ?? item.file.name) !== id),
+          )
+        }
+      />
+    );
+  },
+};
+
+export const EmptyState: Story = {
+  args: {
+    label: "Upload Files",
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Upload Files",
+    disabled: true,
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files] = useState<RecursicaFileUploadItem[]>([
+      { file: mockFile("document.pdf") },
+    ]);
+    return <FileUpload {...args} files={files} />;
+  },
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Upload Files",
+    error: "File upload failed. Please try again.",
+  },
+};
+
+function StarIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="currentColor"
+      aria-hidden
+    >
+      <path d="M12 2l2.9 6.6 7.1.6-5.4 4.7 1.6 7-6.2-3.8-6.2 3.8 1.6-7L2 9.2l7.1-.6z" />
+    </svg>
+  );
+}
+
+export const CustomIcon: Story = {
+  args: {
+    label: "Upload Files",
+    icon: <StarIcon />,
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files, setFiles] = useState<RecursicaFileUploadItem[]>([]);
+    return (
+      <FileUpload
+        {...args}
+        files={files}
+        onFilesAdded={(added) =>
+          setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+        }
+        onFileRemove={(id) =>
+          setFiles((prev) =>
+            prev.filter((item) => (item.id ?? item.file.name) !== id),
+          )
+        }
+      />
+    );
+  },
+};
+
+export const LongFilenames: Story = {
+  args: {
+    label: "Upload Files",
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files, setFiles] = useState<RecursicaFileUploadItem[]>([
+      {
+        file: mockFile("quarterly-financial-report-final-version-approved.pdf"),
+      },
+      { file: mockFile("2026-08-team-offsite-photos-and-notes.zip") },
+      { file: mockFile("resume.docx") },
+    ]);
+    return (
+      <FileUpload
+        {...args}
+        files={files}
+        onFilesAdded={(added) =>
+          setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+        }
+        onFileRemove={(id) =>
+          setFiles((prev) =>
+            prev.filter((item) => (item.id ?? item.file.name) !== id),
+          )
+        }
+      />
+    );
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: "Upload Files",
+    assistiveText: "Submitted files cannot be changed",
+    readOnly: true,
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files] = useState<RecursicaFileUploadItem[]>([
+      { file: mockFile("document.pdf") },
+      { file: mockFile("image.png") },
+    ]);
+    return <FileUpload {...args} files={files} />;
+  },
+};
+
+// Demonstrates that `accept` isn't just cosmetic on the browse-button dialog — files that don't
+// match it are rejected the same way whether picked via Browse or dropped directly (drag-and-drop
+// bypasses the native `accept` filtering entirely, so this only works because FileUpload
+// re-validates it itself). Drag a non-.pdf/.png file onto the dropzone (or edit `accept` in the
+// controls) to see the control switch into its error state with the default
+// `invalidFileTypeMessage` ("File type not accepted") instead of accepting the file.
+export const AcceptRestriction: Story = {
+  args: {
+    label: "Upload Files",
+    assistiveText: "Only .pdf and .png files are accepted",
+    accept: ".pdf,.png",
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files, setFiles] = useState<RecursicaFileUploadItem[]>([]);
+    return (
+      <FileUpload
+        {...args}
+        files={files}
+        onFilesAdded={(added) =>
+          setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+        }
+        onFileRemove={(id) =>
+          setFiles((prev) =>
+            prev.filter((item) => (item.id ?? item.file.name) !== id),
+          )
+        }
+      />
+    );
+  },
+};
+
+// Demonstrates `maxFiles`: already at the 2-file cap below, so dropping/picking another file is
+// rejected the same way an `accept` mismatch is — the control switches into its error state with
+// the default `maxFilesMessage` ("Maximum of 2 files allowed") instead of accepting the file.
+export const MaxFilesRestriction: Story = {
+  args: {
+    label: "Upload Files",
+    assistiveText: "Up to 2 files allowed",
+    maxFiles: 2,
+  },
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  render: function FileUploadStory({
+    withLayer,
+    layer,
+    ...args
+  }: FileUploadStoryArgs) {
+    /* eslint-enable @typescript-eslint/no-unused-vars */
+    const [files, setFiles] = useState<RecursicaFileUploadItem[]>([
+      { file: mockFile("document.pdf") },
+      { file: mockFile("image.png") },
+    ]);
+    return (
+      <FileUpload
+        {...args}
+        files={files}
+        onFilesAdded={(added) =>
+          setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+        }
+        onFileRemove={(id) =>
+          setFiles((prev) =>
+            prev.filter((item) => (item.id ?? item.file.name) !== id),
+          )
+        }
+      />
+    );
+  },
 };