@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,651 @@
+# PageLayout
+
+## 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/PageLayout/PageLayout.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { fn } from "storybook/test";
+import PageLayout from "./PageLayout";
+import { STORYBOOK_VIEWPORTS } from "@internal/test-utils-storybook/test-utils-storybook";
+import NavigationItem from "../NavigationItem/NavigationItem";
+import Button from "../Button/Button";
+import Navigation from "../Navigation/Navigation";
+import Tag from "../Tag/Tag";
+import Breadcrumbs from "../Breadcrumbs/Breadcrumbs";
+import Header from "../Header/Header";
+import Select from "../Select/Select";
+import SelectItem from "../SelectItem/SelectItem";
+import Tabs from "../Tabs/Tabs/Tabs";
+import TabList from "../Tabs/TabList/TabList";
+import Tab from "../Tabs/Tab/Tab";
+import TabPanel from "../Tabs/TabPanel/TabPanel";
+import arrayOfLength from "@internal/arrayOfLength/arrayOfLength";
+import { I18nProvider } from "react-aria-components";
+import { useMemo } from "react";
+import {
+  createColumnHelper,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getPaginationRowModel,
+  getSortedRowModel,
+  useReactTable,
+} from "@tanstack/react-table";
+import DataTableHeader from "../DataTable/DataTableHeader/DataTableHeader";
+import DataTableCell from "../DataTable/DataTableCell/DataTableCell";
+import Radio from "../Radio/Radio";
+import Filter, { TypeTableColumnWithFilter } from "../Filter/Filter";
+import CheckboxGroup from "../CheckboxGroup/CheckboxGroup";
+import Checkbox from "../Checkbox/Checkbox";
+import Switch from "../Switch/Switch";
+import DataTable from "../DataTable/DataTable";
+
+const meta: Meta<typeof PageLayout> = {
+  component: PageLayout,
+  parameters: {
+    layout: "none",
+  },
+  decorators: [
+    (Story) => {
+      return (
+        <I18nProvider locale="fr">
+          <Story />
+        </I18nProvider>
+      );
+    },
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Desktop: Story = {
+  args: {
+    navigationComponent: (
+      <Navigation logo="agregio" onParametersClick={fn()} onLogoutClick={fn()}>
+        <>
+          {arrayOfLength(10).map((index) => (
+            <NavigationItem
+              key={index}
+              label={`Item ${index}`}
+              href={`/item-${index}`}
+              iconLeft="home"
+            />
+          ))}
+          <NavigationItem
+            label={`Item Dropdown`}
+            iconLeft="home"
+            subLinks={[
+              { href: "/", label: "Sous-libellé 1" },
+              { href: "/", label: "Sous-libellé 2" },
+            ]}
+          />
+        </>
+      </Navigation>
+    ),
+    children: (
+      <>
+        <Header
+          title="Insert title"
+          subtitle="Insert subtitle"
+          tagComponent={<Tag iconLeft="help_outline">[Insert tag]</Tag>}
+          logo="agregio"
+          onGoBack={fn()}
+          breadcrumbsComponent={
+            <Breadcrumbs
+              links={[
+                { href: "#link-1", text: "Link 1" },
+                { href: "#link-2", text: "Link 2" },
+                { href: "#link-3", text: "Link 3" },
+              ]}
+            />
+          }
+          helperIconComponent={
+            <Button
+              iconLeft="help_outline"
+              onClick={() => alert("Help")}
+              mode="tertiary"
+            />
+          }
+          notificationIconComponent={
+            <Button
+              iconLeft="notifications_none"
+              onClick={() => alert("Notifications")}
+              mode="tertiary"
+            />
+          }
+          additionalActions={
+            <Select
+              mode="single"
+              id="select"
+              aria-label="Select"
+              value={null}
+              onChange={fn()}
+              placeholder="Select"
+            >
+              <SelectItem id="select-item-1" text="Select Item 1" />
+              <SelectItem id="select-item-2" text="Select Item 2" />
+              <SelectItem id="select-item-3" text="Select Item 3" />
+            </Select>
+          }
+          tabsComponent={
+            <Tabs>
+              <TabList>
+                <Tab id="tab-1">Tab 1</Tab>
+                <Tab
+                  id="tab-2"
+                  badgeProps={{ nature: "negative", variant: "dot" }}
+                >
+                  Tab 2
+                </Tab>
+                <Tab id="tab-3" badgeProps={{ value: 8, nature: "negative" }}>
+                  Tab 3
+                </Tab>
+              </TabList>
+              <div style={{ marginTop: "var(--spacing-md" }}>
+                <TabPanel id="tab-1">Content for the panel 1</TabPanel>
+                <TabPanel id="tab-2">Content for the panel 2</TabPanel>
+                <TabPanel id="tab-3">Content for the panel 3</TabPanel>
+              </div>
+            </Tabs>
+          }
+        />
+      </>
+    ),
+  },
+};
+
+export const Mobile: Story = {
+  args: {
+    ...Desktop.args,
+  },
+  parameters: {
+    ...STORYBOOK_VIEWPORTS,
+    layout: "none",
+  },
+  globals: {
+    viewport: { value: "iphone6", isRotated: false },
+  },
+};
+
+export const PageLayoutWithDataTable: Story = {
+  args: {
+    ...Desktop.args,
+  },
+  render: () => {
+    const ParentComponent = () => {
+      // Below are just type definition of the data and its generation
+      // Typically you would get this from your API and will not have to create them here
+      // We let it so you can fully understand how the filter works based on the data provided
+
+      type User = {
+        firstname: string;
+        lastname: string;
+        email: string;
+        isValidated?: boolean;
+        day?: string;
+        foods?: Array<string>;
+        organization?: { id: string; name: string };
+        isActive?: boolean;
+      };
+
+      const ALL_FOODS = useMemo(
+        () => ["Pizza", "Hamburger", "Ramen", "Sushi", "Fries"],
+        [],
+      );
+
+      const FOODS = useMemo(
+        () => [
+          [ALL_FOODS[0], ALL_FOODS[1]],
+          [ALL_FOODS[1], ALL_FOODS[2]],
+          [ALL_FOODS[2], ALL_FOODS[3]],
+          [ALL_FOODS[3], ALL_FOODS[4]],
+          [ALL_FOODS[4], ALL_FOODS[0]],
+        ],
+        [ALL_FOODS],
+      );
+
+      const ORGANIZATIONS = useMemo(
+        () => [
+          { id: "1", name: "EDF Store and Forecast" },
+          { id: "2", name: "Agregio Solutions" },
+          { id: "3", name: "Dalkia" },
+        ],
+        [],
+      );
+
+      const DAYS = useMemo(
+        () => ["Monday", "Tuesday", "Wednesday", "Thursday"],
+        [],
+      );
+
+      const data: Array<User> = useMemo(
+        () =>
+          arrayOfLength(300).map((index) => ({
+            firstname: `Firstname ${index + 1}`,
+            lastname: `Lastname ${index + 1}`,
+            email: `john-doe${index + 1}@example.com`,
+            isValidated: index % 2 === 0,
+            foods: FOODS[index % FOODS.length],
+            day: DAYS[index % DAYS.length],
+            organization: ORGANIZATIONS[index % ORGANIZATIONS.length],
+            isActive: index % 2 === 0,
+          })),
+        [DAYS, FOODS, ORGANIZATIONS],
+      );
+
+      // Here starts the interesting stuff: columns definitions.
+      // All the features of the filters comes from those columns definitions
+      // Please read carefully each column, they all serve as a different example of how to use the filters
+      const columnHelper = createColumnHelper<User>();
+
+      const columns = useMemo(
+        () => [
+          columnHelper.accessor("firstname", {
+            // Here, because there is no "FilterInDrawer" component, there will be nothing in the filter drawer related to the firstname
+            // But the firstname can still be filtered by the global filter (search input)
+            header: ({ header }) => (
+              <DataTableHeader
+                onSortClick={header.column.getToggleSortingHandler()}
+                sortDirection={header.column.getIsSorted() || "none"}
+                text="Firstname"
+              />
+            ),
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+          }),
+          // Here is an example using a "FilterInDrawer" component that render a radio group to filter the day
+          // Please note the "filterFn" is "arrIncludes" for this king of value (Array<string>)
+          // Also note the usage of `satisfies TypeTableColumnWithFilter<User>` to help you type check the column definition (because meta is a custom property)
+          // Finally, you will note that the Chips are auto-generated, if you do not want to use them you can set the `skipFilterChips` to true
+          columnHelper.accessor("day", {
+            id: "Day",
+            header: () => <DataTableHeader text="Day" />,
+            cell: (props) => <DataTableCell>{props.getValue()}</DataTableCell>,
+            filterFn: "equals",
+            meta: {
+              FilterInDrawer: ({ column }) => (
+                <div>
+                  <b>Filter by day:</b>
+
+                  {DAYS.map((day) => (
+                    <Radio
+                      label={day}
+                      key={day}
+                      checked={column.getFilterValue() === day}
+                      onChange={() => column.setFilterValue(day)}
+                    />
+                  ))}
+                </div>
+              ),
+            } satisfies TypeTableColumnWithFilter<User>,
+          }),
+          // Here is another example using a "FilterInDrawer" component that render a checkbox group to filter the food
+          // Please note the "filterFn" is "arrIncludesSome" -> we want to include all entries that match at least one food
+          // Also note the usage of `satisfies TypeTableColumnWithFilter<User>` to help you type check the column definition (because meta is a custom property)
+          // Finally, you will note that the Chips are auto-generated, if you do not want to use them you can set the `skipFilterChips` to true
+          columnHelper.accessor("foods", {
+            id: "Foods",
+            header: () => <DataTableHeader text="Foods" />,
+            cell: (props) => (
+              <DataTableCell>{props.getValue()?.join(", ")}</DataTableCell>
+            ),
+            filterFn: "arrIncludesSome",
+            meta: {
+              FilterInDrawer: ({ column }) => (
+                <div style={{ marginTop: 8 }}>
+                  <b>Filter by food (at least one):</b>
+                  <CheckboxGroup
+                    value={column.getFilterValue() as any}
+                    onChange={column.setFilterValue}
+                    aria-label="Filter by food (at least one)"
+                  >
+                    {ALL_FOODS.map((food) => (
+                      <div key={food}>
+                        <Checkbox label={food} value={food} />
+                      </div>
+                    ))}
+                  </CheckboxGroup>
+                </div>
+              ),
+            } satisfies TypeTableColumnWithFilter<User>,
+          }),
+          // Here is another example using a "FilterInDrawer" component that render a select to filter the organization
+          // Please note the "filterFn" is a custom function that will filter the data based on the organization id
+          // Also note the usage of `satisfies TypeTableColumnWithFilter<User>` to help you type check the column definition (because meta is a custom property)
+          // And most important here, we have a custom meta property `filterChips` that will generate a chip to display the selected organization
+          // The Filter can not handle automatic chips when the data is a complex object, so you have to handle that manually
+          columnHelper.accessor("organization", {
+            id: "Organization",
+            header: () => <DataTableHeader text="Organization" />,
+            cell: (props) => (
+              <DataTableCell>{props.getValue()?.name}</DataTableCell>
+            ),
+            filterFn: (row, _, filterValue) => {
+              if (!filterValue) return true;
+              return row.original.organization?.id === filterValue;
+            },
+            meta: {
+              filterChips: ({ column }) => {
+                const value = column.getFilterValue();
+                const organization = ORGANIZATIONS.find(
+                  (org) => org.id === value,
+                );
+                if (!organization) return [];
+                return [
+                  {
+                    value: `Organization: ${organization.name}`,
+                    onClose: () => column.setFilterValue(null),
+                  },
+                ];
+              },
+              FilterInDrawer: ({ column }) => (
+                <Select
+                  id="organization-select"
+                  label="Filter by organization:"
+                  mode="single"
+                  value={column.getFilterValue() as any}
+                  onChange={column.setFilterValue}
+                  fullWidth
+                  wrapperProps={{ style: { marginBottom: 8 } }}
+                >
+                  {ORGANIZATIONS.map((organization) => (
+                    <SelectItem
+                      text={organization.name}
+                      id={organization.id}
+                      key={organization.id}
+                    />
+                  ))}
+                </Select>
+              ),
+            } satisfies TypeTableColumnWithFilter<User>,
+          }),
+          // Here is an example that uses a filter outside of the drawer.
+          // See the "extraLeftContent" prop to see how to connect it to react-table filtering features
+          columnHelper.accessor("isActive", {
+            header: () => <DataTableHeader text="Active" />,
+            cell: (props) => (
+              <DataTableCell>{props.getValue() ? "✅" : "❌"}</DataTableCell>
+            ),
+            filterFn: (row, _, filterValue) => {
+              if (!filterValue) return true;
+              return !!row.original.isActive;
+            },
+          }),
+          // Here is an example of an empty column, for example to display an actions bar
+          // You can note that the header is empty, the text is optional
+          columnHelper.display({
+            id: "actions",
+            header: () => <DataTableHeader />,
+            cell: () => (
+              <DataTableCell>
+                <Button mode="secondary" iconLeft="edit" />
+              </DataTableCell>
+            ),
+          }),
+        ],
+        [ALL_FOODS, DAYS, ORGANIZATIONS, columnHelper],
+      );
+
+      // And here we define the table as usual
+      const table = useReactTable({
+        data,
+        columns,
+        initialState: {
+          globalFilter: "",
+          pagination: {
+            pageSize: 50,
+          },
+        },
+        getCoreRowModel: getCoreRowModel(),
+        getSortedRowModel: getSortedRowModel(),
+        getFilteredRowModel: getFilteredRowModel(),
+        getPaginationRowModel: getPaginationRowModel(),
+      });
+
+      // Get the pagination state
+      const pagination = table.getState().pagination;
+
+      // Render the table using the base DataTable component
+      return (
+        <PageLayout
+          navigationComponent={
+            <Navigation
+              logo="agregio"
+              onParametersClick={fn()}
+              onLogoutClick={fn()}
+            >
+              <>
+                {arrayOfLength(10).map((index) => (
+                  <NavigationItem
+                    key={index}
+                    label={`Item ${index}`}
+                    href={`/item-${index}`}
+                    iconLeft="home"
+                  />
+                ))}
+                <NavigationItem
+                  label={`Item Dropdown`}
+                  iconLeft="home"
+                  subLinks={[
+                    { href: "/", label: "Sous-libellé 1" },
+                    { href: "/", label: "Sous-libellé 2" },
+                  ]}
+                />
+              </>
+            </Navigation>
+          }
+        >
+          <>
+            <Header title={"Test"} />
+            <Filter<User>
+              onDownloadClick={() => alert("Download")}
+              onSettingsClick={() => alert("Settings")}
+              table={table}
+              extraLeftContent={
+                <>
+                  <Switch
+                    label="Only active"
+                    isSelected={!!table.getColumn("isActive")?.getFilterValue()}
+                    onChange={() =>
+                      table
+                        .getColumn("isActive")
+                        ?.setFilterValue((prevValue: boolean) => !prevValue)
+                    }
+                  />
+                </>
+              }
+              extraRightContent={
+                <>
+                  <Button
+                    mode="secondary"
+                    onClick={() => alert("Secondary")}
+                    text="Secondary"
+                  />
+                  <Button
+                    mode="primary"
+                    onClick={() => alert("Primary")}
+                    text="Primary"
+                  />
+                </>
+              }
+            />
+            <DataTable table={table} pagination={pagination} />
+          </>
+        </PageLayout>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+```
+
+## 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, userEvent, within } from "storybook/test";
+import PageLayout from "../PageLayout";
+import { STORYBOOK_VIEWPORTS } from "@internal/test-utils-storybook/test-utils-storybook";
+import * as PageLayoutStories from "../PageLayout.stories";
+
+const meta: Meta<typeof PageLayout> = {
+  ...PageLayoutStories.default,
+  parameters: {
+    ...PageLayoutStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+  component: PageLayout,
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Desktop: Story = {
+  args: {
+    ...PageLayoutStories.Desktop.args,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+
+    await expect(canvas.getByText("Item 0")).toBeVisible();
+    await expect(canvas.getByLabelText("Menu mobile")).not.toBeVisible();
+    await expect(
+      canvas.getByTestId("navigation-mobile-collapsed-menu"),
+    ).toBeVisible();
+    await expect(
+      canvas.getByTestId("navigation-mobile-close-menu"),
+    ).not.toBeVisible();
+
+    await user.click(canvas.getByTestId("navigation-mobile-collapsed-menu"));
+
+    await expect(canvas.getByLabelText("Menu mobile")).not.toBeVisible();
+    await expect(canvas.getByText("Item 0")).not.toBeVisible();
+    await expect(
+      canvas.getByTestId("navigation-mobile-collapsed-menu"),
+    ).toBeVisible();
+    await expect(
+      canvas.getByTestId("navigation-mobile-close-menu"),
+    ).not.toBeVisible();
+
+    await user.click(canvas.getByTestId("navigation-mobile-collapsed-menu"));
+
+    await expect(canvas.getByText("Item 0")).toBeVisible();
+  },
+};
+
+export const MobileShouldOpenNavigationOnClickOnMobileBurgerMenu: Story = {
+  args: {
+    ...Desktop.args,
+  },
+  parameters: {
+    ...STORYBOOK_VIEWPORTS,
+    layout: "none",
+  },
+  globals: {
+    viewport: { value: "iphone6", isRotated: false },
+  },
+  // TODO: see https://github.com/storybookjs/test-runner/issues/85
+  // play: async ({ canvasElement }) => {
+  //   const canvas = within(canvasElement);
+  //   const user = userEvent.setup();
+
+  //   await expect(canvas.getByText("Item 0")).not.toBeVisible();
+  //   await expectPresent(() => canvas.getByLabelText("Menu mobile"));
+  //   await expect(
+  //     canvas.getByTestId("navigation-mobile-close-menu"),
+  //   ).not.toBeVisible();
+
+  //   await user.click(canvas.getByLabelText("Menu mobile"));
+
+  //   await expect(canvas.getByText("Item 0")).toBeVisible();
+  //   await expect(
+  //     canvas.getByTestId("navigation-mobile-close-menu"),
+  //   ).toBeVisible();
+
+  //   await user.click(canvas.getByTestId("navigation-mobile-close-menu"));
+
+  //   await expect(
+  //     canvas.getByTestId("navigation-mobile-close-menu"),
+  //   ).not.toBeVisible();
+  //   await expect(canvas.getByText("Item 0")).not.toBeVisible();
+  // },
+};
+
+export const MobileShouldCloseNavigationOnClickOnNavigationItem: Story = {
+  args: {
+    ...Desktop.args,
+  },
+  parameters: {
+    ...STORYBOOK_VIEWPORTS,
+    layout: "none",
+  },
+  globals: {
+    viewport: { value: "iphone6", isRotated: false },
+  },
+  // TODO: see https://github.com/storybookjs/test-runner/issues/85
+  // play: async ({ canvasElement }) => {
+  //   const canvas = within(canvasElement);
+  //   const user = userEvent.setup();
+
+  //   await expect(canvas.getByText("Item 0")).not.toBeVisible();
+  //   await expectPresent(() => canvas.getByLabelText("Menu mobile"));
+  //   await expect(
+  //     canvas.getByTestId("navigation-mobile-close-menu"),
+  //   ).not.toBeVisible();
+
+  //   await user.click(canvas.getByTestId("navigation-mobile-close-menu"));
+
+  //   await expect(canvas.getByText("Item 0")).toBeVisible();
+  //   await expect(
+  //     canvas.getByTestId("navigation-mobile-close-menu"),
+  //   ).toBeVisible();
+
+  //   await user.click(canvas.getByText("Item 1"));
+
+  //   await expect(
+  //     canvas.getByTestId("navigation-mobile-close-menu"),
+  //   ).not.toBeVisible();
+  //   await expect(canvas.queryByText("Item 1")).not.toBeVisible();
+  // },
+};
+```
+
+## 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 PageLayout from "./PageLayout.stories";
+import * as PageLayoutTests from "./tests/PageLayout.stories";
+
+<Meta of={PageLayout} />
+
+# PageLayout
+
+A page layout is a container for all the content of a page.
+
+## Example usage
+
+Coming soon...
+```