@agregio-solutions/design-system 1.90.1 → 1.92.0

package/dist/packages/components/FileUpload/doc.md

@@ -0,0 +1,449 @@
+# FileUpload
+
+## Props
+
+The complete Props documentation with JS doc for this component is available at this path:
+
+node_modules/@agregio-solutions/design-system/dist/packages/components/FileUpload/FileUpload.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { fn, within } from "storybook/test";
+import FileUpload from "./FileUpload";
+import { I18nProvider } from "react-aria-components";
+import { useState } from "react";
+import Button from "../Button/Button";
+
+const meta: Meta<typeof FileUpload> = {
+  component: FileUpload,
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en-US">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Playground: Story = {
+  args: {
+    formGroupWrapperProps: {
+      htmlForId: "file-upload",
+      label: "[Insert label]",
+      description: "[Insert description]",
+      errorHelperText: "[Insert helper]",
+      errorHelperTextIcon: "error_outline",
+      required: true,
+      labelIconRight: "help_outline",
+      labelIconRightTooltip: "Additional information",
+    },
+    onSelectionChange: fn(),
+    allowsMultiple: true,
+    files: [
+      {
+        id: "1",
+        fileName: "[Filename.exe]",
+        fileSize: "[Size Mo]",
+        isUploading: true,
+        onDelete: fn(),
+      },
+      {
+        id: "2",
+        fileName: "test 2.txt",
+        fileSize: "100KB",
+        isUploading: false,
+        onDelete: fn(),
+      },
+      {
+        id: "3",
+        fileName: "test 3.txt",
+        isUploading: false,
+        onDelete: fn(),
+      },
+    ],
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("[Insert label]");
+    await canvas.findByText("[Insert description]");
+    await canvas.findByText("[Insert helper]");
+    await canvas.findByText("[Filename.exe]");
+    await canvas.findByText("test 2.txt");
+    await canvas.findByText("test 3.txt");
+  },
+};
+
+export const FunctionnalForm: Story = {
+  args: {
+    ...Playground.args,
+  },
+  render: (args) => {
+    const ParentComponent = () => {
+      const [files, setFiles] = useState<File[]>([]);
+
+      return (
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            // Here put you API call and state changes accordingly
+            args.onSelectionChange(files);
+          }}
+        >
+          <FileUpload
+            {...args}
+            formGroupWrapperProps={args.formGroupWrapperProps}
+            onSelectionChange={(files) =>
+              setFiles((prev) => [...prev, ...files])
+            }
+            files={files.map((file) => ({
+              id: file.name,
+              fileName: file.name,
+              fileSize: `${file.size} bytes`, // <- may need a util to format this
+              onDelete: () =>
+                setFiles((prev) => prev.filter((f) => f !== file)),
+            }))}
+          />
+
+          <hr />
+          <Button type="submit" text="Submit" />
+        </form>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const OnlyOneFile: Story = {
+  args: {
+    ...Playground.args,
+    allowsMultiple: false,
+  },
+  render: FunctionnalForm.render,
+};
+
+export const Disabled: Story = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+  render: FunctionnalForm.render,
+};
+
+export const TestOverflowingContent: Story = {
+  decorators: [
+    (Story) => (
+      <div style={{ width: "313px", overflow: "hidden" }}>
+        <Story />
+      </div>
+    ),
+  ],
+  args: {
+    ...Playground.args,
+    files: [
+      {
+        id: "1",
+        fileName: "verylongfilename-verylongfilename-verylongfilename.txt",
+        fileSize: "100000000000000000000000000000000000000000To",
+        isUploading: false,
+        onDelete: fn(),
+      },
+    ],
+  },
+};
+```
+
+## How to test this component
+
+Here are some more advanced stories with more testing coverage and examples that you can read to understand how to test this component.
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import FileUpload from "../FileUpload";
+import * as FileUploadStories from "../FileUpload.stories";
+import { useState } from "react";
+import Button from "@packages/components/Button/Button";
+import {
+  expectNotPresent,
+  someTime,
+} from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof FileUpload> = {
+  ...FileUploadStories.default,
+  parameters: {
+    ...FileUploadStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+  component: FileUpload,
+};
+export default meta;
+
+const csvFile = new File(["test"], "test.csv", { type: "text/csv" });
+const txtFile = new File(["test"], "test.txt", { type: "text/plain" });
+
+type Story = StoryObj<typeof meta>;
+
+export const TestOnlyCsv: Story = {
+  args: {
+    ...FileUploadStories.Playground.args,
+    acceptedFileTypes: ["text/csv"],
+    formGroupWrapperProps: {
+      label: "Upload a CSV file",
+      htmlForId: "file-upload",
+    },
+    files: [],
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await someTime(200); // Needed for use effect to run
+    const fileInput = canvas.getByLabelText("Upload a CSV file");
+    await user.upload(fileInput, [txtFile]);
+    await expect(args.onSelectionChange).not.toHaveBeenCalled();
+    await user.upload(fileInput, [csvFile]);
+    await expect(args.onSelectionChange).toHaveBeenCalledTimes(1);
+  },
+};
+
+export const ExampleOnlyCsv: Story = {
+  render: () => (
+    <FileUpload
+      onSelectionChange={fn()}
+      acceptedFileTypes={["text/csv"]}
+      formGroupWrapperProps={{ label: "Upload a CSV file" }}
+    />
+  ),
+};
+
+export const ExampleMultipleFiles: Story = {
+  render: () => (
+    <FileUpload
+      onSelectionChange={fn()}
+      allowsMultiple={true}
+      formGroupWrapperProps={{ label: "Upload multiple files" }}
+    />
+  ),
+};
+
+export const SimpleStateAndUploadOnSubmitExample: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [files, setFiles] = useState<File[]>([]);
+
+      return (
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            // Here put you API call and state changes accordingly
+            console.log({ files }); // eslint-disable-line no-console
+          }}
+        >
+          <FileUpload
+            onSelectionChange={(files) =>
+              setFiles((prev) => [...prev, ...files])
+            }
+            allowsMultiple
+            formGroupWrapperProps={{
+              label: "Upload a file",
+              htmlForId: "file-upload", // <- required for a11y and testing
+            }}
+            files={files.map((file) => ({
+              id: file.name,
+              fileName: file.name,
+              fileSize: `${file.size} bytes`, // <- may need a util to format this
+              onDelete: () =>
+                setFiles((prev) => prev.filter((f) => f !== file)),
+            }))}
+          />
+
+          <hr />
+          <Button type="submit" text="Submit" />
+        </form>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const TestSimpleStateAndUploadOnSubmitExample: Story = {
+  // ⬇️ same code as example above
+  render: SimpleStateAndUploadOnSubmitExample.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await someTime(100); // This delay is needed due to a hack we had to make in the component to make it work with testing-library
+    const fileInput = canvas.getByLabelText("Upload a file");
+
+    await user.upload(fileInput, [
+      new File(["test"], "test.txt", { type: "text/plain" }),
+    ]);
+    await canvas.findByText("test.txt");
+  },
+};
+
+export const SimpleStateAndUploadDirectlyExample: Story = {
+  render: () => {
+    const fakeApiCall = async () => {
+      await new Promise((resolve) => setTimeout(resolve, 1000));
+    };
+
+    const ParentComponent = () => {
+      const [files, setFiles] = useState<File[]>([]);
+      const [uploadingFiles, setUploadingFiles] = useState<File[]>([]);
+
+      return (
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            // Here put you API call and state changes accordingly
+            console.log({ files }); // eslint-disable-line no-console
+          }}
+        >
+          <FileUpload
+            onSelectionChange={async (files) => {
+              // Here is just a naive example implementation, feel free to adjust it based on your own needs and stack (react-query mutation for example).
+              // The important thing is to show the user the uploading state.
+              setUploadingFiles((prev) => [...prev, ...files]);
+              setFiles((prev) => [...prev, ...files]);
+              await fakeApiCall();
+              setUploadingFiles([]);
+            }}
+            allowsMultiple
+            formGroupWrapperProps={{
+              label: "Upload a file",
+              htmlForId: "file-upload", // <- required for a11y and testing
+            }}
+            files={files.map((file) => ({
+              id: file.name,
+              fileName: file.name,
+              fileSize: `${file.size} bytes`, // <- may need a util to format this.
+              onDelete: () =>
+                setFiles((prev) => prev.filter((f) => f !== file)),
+              isUploading: uploadingFiles.includes(file), // <- here you have to show the user the uploading state.
+            }))}
+          />
+
+          <hr />
+          <Button type="submit" text="Submit" />
+        </form>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const TestOnlyOneFile: Story = {
+  ...FileUploadStories.OnlyOneFile,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await someTime(100);
+    const fileInput = canvas.getByLabelText("[Insert label]");
+
+    await user.upload(fileInput, [
+      new File(["test"], "test.txt", { type: "text/plain" }),
+    ]);
+    await canvas.findByText("test.txt");
+    await user.upload(fileInput, [
+      new File(["test"], "test-2.txt", { type: "text/plain" }),
+    ]);
+    await expectNotPresent(() => canvas.queryByText("test-2.txt"));
+    await canvas.findByText("test.txt");
+  },
+};
+```
+
+## Developer notes
+
+Here are the notes available for the developer on the built Storybook, you can read them to understand the component and how to use it.
+
+```mdx
+import {
+  Canvas,
+  Meta,
+  Stories,
+  Controls,
+  Source,
+} from "@storybook/addon-docs/blocks";
+
+import * as FileUpload from "./FileUpload.stories";
+import * as FileUploadTests from "./tests/FileUpload.stories";
+
+<Meta of={FileUpload} />
+
+# FileUpload
+
+The FileUpload component allows users to upload files from their **file system** by searching or using **drag-and-drop**.
+
+## Accepted file types
+
+By default, the file trigger will accept any file type.
+To support only certain file types, pass an array of the mime type of files via the acceptedFileTypes prop.
+
+<Source of={FileUploadTests.ExampleOnlyCsv} type="code" dark />
+
+## Multiple files
+
+A file trigger can accept multiple files by passsing the `allowsMultiple` property.
+
+<Source of={FileUploadTests.ExampleMultipleFiles} type="code" dark />
+
+## Usage with simple state, upload on submit
+
+<Source
+  of={FileUploadTests.SimpleStateAndUploadOnSubmitExample}
+  type="code"
+  dark
+/>
+
+## Usage with simple state, upload directly
+
+<Source
+  of={FileUploadTests.SimpleStateAndUploadDirectlyExample}
+  type="code"
+  dark
+/>
+
+## Usage with react-hook-form
+
+The usage is the same, you just need to use a `Controller` component (or `useController`) to control the file upload because it does not work on uncontrolled mode.
+
+## How to test this component
+
+The most important thing is to ensure there is an `htmlForId` prop passed to the `formGroupWrapperProps` component prop.
+
+This is needed to link the label to the input.
+
+After that here is an example of how to test the component using testing-library and userEvent.
+You will notice that **we need to add a delay** before starting to run assertions.
+This is because of a hack we had to make in the component to make it work with testing-library.
+
+<Source
+  of={FileUploadTests.TestSimpleStateAndUploadOnSubmitExample}
+  type="code"
+  dark
+/>
+
+## Playground & Props
+
+<Canvas of={FileUpload.Playground} />
+
+<Controls of={FileUpload.Playground} />
+
+<Stories />
+```

package/dist/packages/components/Filter/doc.md

@@ -0,0 +1,196 @@
+# Filter
+
+## Props
+
+The complete Props documentation with JS doc for this component is available at this path:
+
+node_modules/@agregio-solutions/design-system/dist/packages/components/Filter/Filter.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Filter from "./Filter";
+import { WithReactTableFrontEndManaged } from "../DataTable/DataTable.stories";
+
+const meta: Meta<typeof Filter> = {
+  component: Filter,
+  parameters: {
+    layout: "padded",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+// We just forward the DataTable Story to keep all things grouped and avoid duplications
+export const FullFeatured: StoryObj<typeof Filter> = {
+  decorators: WithReactTableFrontEndManaged.decorators as any,
+  render: WithReactTableFrontEndManaged.render as any,
+};
+```
+
+## How to test this component
+
+Here are some more advanced stories with more testing coverage and examples that you can read to understand how to test this component.
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Filter from "../Filter";
+import { fireEvent, screen, userEvent, within } from "storybook/test";
+import { FullFeatured } from "../Filter.stories";
+import { expectNotPresent } from "@internal/test-utils-storybook/test-utils-storybook";
+
+const meta: Meta<typeof Filter> = {
+  component: Filter,
+  parameters: {
+    layout: "padded",
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+export const ShouldFilterTheRadio: StoryObj<typeof Filter> = {
+  ...FullFeatured,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+
+    // Assert initial state (no filter)
+    await canvas.findAllByText("Monday");
+    await canvas.findAllByText("Tuesday");
+
+    // Open the filter and select
+    await user.click(canvas.getByText("Filter"));
+    await fireEvent.click(screen.getByLabelText("Monday")); // fireEvent is used to avoid issue on Firefox
+    await user.click(screen.getByText("Apply"));
+    await canvas.findAllByText("Monday");
+    await canvas.findByText("Day: Monday");
+    await expectNotPresent(() => canvas.queryByText("Tuesday"));
+
+    // Remove the filter with the Chip
+    await user.click(canvas.getByLabelText("Close Day: Monday"));
+    await expectNotPresent(() => canvas.queryByText("Day: Monday"));
+    await canvas.findAllByText("Monday");
+    await canvas.findAllByText("Tuesday");
+  },
+};
+
+export const ShouldFilterTheCheckboxes: StoryObj<typeof Filter> = {
+  ...FullFeatured,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+
+    // Assert initial state (no filter)
+    await canvas.findAllByText("Pizza, Hamburger");
+    await canvas.findAllByText("Hamburger, Ramen");
+
+    // Open the filter and select
+    await user.click(canvas.getByText("Filter"));
+    await fireEvent.click(screen.getByLabelText("Pizza")); // fireEvent is used to avoid issue on Firefox
+    await user.click(screen.getByText("Apply"));
+    await canvas.findAllByText("Pizza, Hamburger");
+    await canvas.findByText("Foods: Pizza");
+    await expectNotPresent(() => canvas.queryByText("Hamburger, Ramen"));
+
+    // Remove the filter with the Chip
+    await user.click(canvas.getByLabelText("Close Foods: Pizza"));
+    await expectNotPresent(() => canvas.queryByText("Foods: Pizza"));
+    await canvas.findAllByText("Pizza, Hamburger");
+    await canvas.findAllByText("Hamburger, Ramen");
+  },
+};
+
+export const ShouldFilterTheOrganization: StoryObj<typeof Filter> = {
+  ...FullFeatured,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+
+    // Assert initial state (no filter)
+    await canvas.findAllByText("EDF Store and Forecast");
+    await canvas.findAllByText("Agregio Solutions");
+
+    // Open the filter and select
+    await user.click(canvas.getByText("Filter"));
+    await fireEvent.click(screen.getByLabelText("Filter by organization:")); // fireEvent is used to avoid issue on Firefox
+    await fireEvent.click(
+      screen.getByLabelText("DropdownItem EDF Store and Forecast"),
+    ); // fireEvent is used to avoid issue on Firefox
+    await user.click(screen.getByText("Apply"));
+    await canvas.findAllByText("EDF Store and Forecast");
+    await canvas.findByText("Organization: EDF Store and Forecast");
+    await expectNotPresent(() => canvas.queryByText("Agregio Solutions"));
+
+    // Remove the filter with the Chip
+    await user.click(
+      canvas.getByLabelText("Close Organization: EDF Store and Forecast"),
+    );
+    await expectNotPresent(() =>
+      canvas.queryByText("Organization: EDF Store and Forecast"),
+    );
+    await canvas.findAllByText("EDF Store and Forecast");
+    await canvas.findAllByText("Agregio Solutions");
+  },
+};
+```
+
+## Developer notes
+
+Here are the notes available for the developer on the built Storybook, you can read them to understand the component and how to use it.
+
+````mdx
+import { Meta, Controls, Stories, Source } from "@storybook/addon-docs/blocks";
+
+import * as Filter from "./Filter.stories";
+import { WithReactTableFrontEndManaged } from "../DataTable/DataTable.stories";
+
+<Meta of={Filter} />
+
+# Filter
+
+## Filter props
+
+<Controls of={Filter.FullFeatured} />
+
+## How to enable/disable the search bar?
+
+To enable the search bar, when creating your `table` instance with `react-table`, simply set an empty string as the `globalFilter` in the `state` or `initialState` of the table (depending on your use-case).
+
+To remove it, simply do not set it (or set it to `undefined`).
+
+Code example to **enable** the search bar:
+
+```
+const table = useReactTable({
+  data,
+  columns,
+  initialState: {
+    globalFilter: "", // <- Enable the search bar
+  },
+});
+```
+
+## How to use custom meta on react-table to create a filter?
+
+As you can see in the source code for the example story, adding a filter into the drawer is as simple as using the `meta` key on the column definition.
+
+Please use the exported type `TypeTableColumnWithFilter` to benefit from the type-safety and autocompletion features of your IDE.
+
+Here are the available keys for the `meta` object with filter abilities:
+
+- `FilterInDrawer`: function that must return a React node, typically the form to filter the column entry (like a Select, Radios, etc.)
+- `skipFilterChips`: by default, we automatically add little Chips for the user to be able to remove the filter. If you want to hide them, set this to `true`.
+- `filterChips`: when using complex data, we cannot automatically generate the chips for you. So you have to use this function that must return an array of chip data (value and onClose precisely)
+
+Here is a complete example on how to use the `meta` key in a lot of different ways.
+It also show you how to connect an external form element (here, a Switch) outside the drawer while still being able to filter the table.
+
+Please read it carefully (maybe copy-paste it in your code editor to have better syntax highlighting), with this example you may be able to handle almost all use-cases.
+
+<Source of={WithReactTableFrontEndManaged} type="code" dark />
+````