@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,465 @@
+# Calendar
+
+## 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/Calendar/Calendar.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import Calendar, { CalendarCell } from "./Calendar";
+import { fn } from "storybook/test";
+import { useState } from "react";
+import styled from "styled-components";
+import YearMonthPicker from "../YearMonthPicker/YearMonthPicker";
+
+const meta: Meta<typeof Calendar> = {
+  component: Calendar,
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    mode: { control: false },
+    value: { control: false },
+    visibleDuration: { control: false },
+    minValue: { control: false },
+    maxValue: { control: false },
+    defaultFocusedValue: { control: false },
+    onChange: { control: false },
+    focusedValue: { control: false },
+  },
+  args: {
+    onChange: fn(),
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Calendar>;
+
+export const Playground: Story = {
+  args: {},
+  render: (args) => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<string | null>("2021-01-04");
+
+      return (
+        <Calendar
+          {...args}
+          value={value}
+          onChange={setValue}
+          mode="single"
+          defaultFocusedValue="2021-01-04"
+        />
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const SingleMode: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<string | null>("2021-01-04");
+
+      return (
+        <>
+          <Calendar
+            mode="single"
+            value={value}
+            onChange={setValue}
+            defaultFocusedValue="2021-01-01"
+          />
+          <p>Debug value: {value}</p>
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const RangeMode: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<null | { start: string; end: string }>(
+        {
+          start: "2021-01-01",
+          end: "2021-01-21",
+        },
+      );
+
+      return (
+        <>
+          <Calendar
+            mode="range"
+            value={value}
+            onChange={setValue}
+            defaultFocusedValue="2021-01-01"
+          />
+          <p>Start: {value?.start}</p>
+          <p>End: {value?.end}</p>
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const MultipleMode: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<string[]>([
+        "2021-01-01",
+        "2021-01-04",
+        "2021-01-10",
+        "2021-01-21",
+      ]);
+
+      return (
+        <>
+          <Calendar
+            mode="multiple"
+            value={value}
+            onChange={setValue}
+            defaultFocusedValue="2021-01-01"
+          />
+          <p>Debug: value:</p>
+          <ul>
+            {value.map((v) => (
+              <li key={v}>{v}</li>
+            ))}
+          </ul>
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const Compact: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<string | null>("2021-01-04");
+
+      return (
+        <Calendar
+          mode="single"
+          value={value}
+          onChange={setValue}
+          defaultFocusedValue="2021-01-01"
+          size="compact"
+        />
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const NoContainer: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState<string | null>("2021-01-04");
+
+      return (
+        <Calendar
+          mode="single"
+          value={value}
+          onChange={setValue}
+          defaultFocusedValue="2021-01-01"
+          noContainer
+        />
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const ControlledHeading: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [focusedValue, setFocusedValue] = useState<string>("2021-01-01");
+      const [value, setValue] = useState<string | null>("2021-01-04");
+
+      const year = focusedValue.split("-")[0];
+      const month = focusedValue.split("-")[1];
+
+      return (
+        <>
+          <YearMonthPicker
+            mode="month-year"
+            value={{ year, month }}
+            onChange={(yearMonth) => {
+              setFocusedValue(yearMonth.year + "-" + yearMonth.month + "-01");
+            }}
+            fullWidth
+          />
+          <Calendar
+            mode="single"
+            value={value}
+            onChange={setValue}
+            focusedValue={focusedValue}
+            onFocusChange={setFocusedValue}
+            noHeading
+          />
+        </>
+      );
+    };
+
+    return <ParentComponent />;
+  },
+};
+
+export const CustomCellSingleMode: Story = {
+  render: () => {
+    // In another file, (i.e. CustomCalendar.styled.ts)
+    const CustomCalendarCell = styled(CalendarCell)`
+      --left-color: transparent;
+      --right-color: transparent;
+
+      &::before,
+      &::after {
+        content: "";
+        position: absolute;
+        inset: -1px;
+        border-radius: 50%;
+        border: 2px solid transparent;
+      }
+
+      &::before {
+        border-color: var(--left-color);
+        clip-path: polygon(0 0, 50% 0, 50% 100%, 0 100%);
+      }
+
+      &::after {
+        border-color: var(--right-color);
+        clip-path: polygon(50% 0, 100% 0, 100% 100%, 50% 100%);
+      }
+
+      &[data-is-indisponibility="true"] {
+        --left-color: var(--color-content-message-negative);
+        --right-color: var(--color-content-message-negative);
+      }
+
+      &[data-is-activation="true"] {
+        --left-color: var(--color-content-message-positive);
+        --right-color: var(--color-content-message-positive);
+      }
+
+      &[data-is-indisponibility="true"][data-is-activation="true"] {
+        --left-color: var(--color-content-message-negative);
+        --right-color: var(--color-content-message-positive);
+      }
+    `;
+
+    const ParentComponent = () => {
+      const [selected, setSelected] = useState<string | null>(null);
+
+      const indisponibilityDates = ["2021-01-05", "2021-01-06", "2021-01-07"];
+      const activationDates = [
+        "2021-01-01",
+        "2021-01-02",
+        "2021-01-07",
+        "2021-01-08",
+      ];
+
+      return (
+        <Calendar
+          mode="single"
+          value={selected}
+          onChange={setSelected}
+          defaultFocusedValue="2021-01-01"
+          renderCalendarCell={(date) => (
+            <CustomCalendarCell
+              date={date}
+              mode="single"
+              data-is-indisponibility={indisponibilityDates.includes(date)}
+              data-is-activation={activationDates.includes(date)}
+            />
+          )}
+        />
+      );
+    };
+
+    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 Calendar from "../Calendar";
+import * as CalendarStories from "../Calendar.stories";
+import { expect, fireEvent, within } from "storybook/test";
+import { I18nProvider } from "react-aria-components";
+
+const meta: Meta<typeof Calendar> = {
+  component: Calendar,
+  ...CalendarStories.default,
+  parameters: {
+    ...CalendarStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en-EN">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof Calendar>;
+
+export const TestSingleMode: Story = {
+  render: CalendarStories.SingleMode.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await fireEvent.click(canvas.getByLabelText("Saturday, January 2, 2021"));
+    await canvas.findByLabelText("Saturday, January 2, 2021 selected");
+    await canvas.findByText("Debug value: 2021-01-02");
+  },
+};
+
+export const TestRangeMode: Story = {
+  render: CalendarStories.RangeMode.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByLabelText(
+      "Selected Range: Friday, January 1 to Thursday, January 21, 2021, Friday, January 1, 2021 selected",
+    );
+    await canvas.findByLabelText("Saturday, January 2, 2021 selected");
+    await canvas.findByLabelText(
+      "Selected Range: Friday, January 1 to Thursday, January 21, 2021, Thursday, January 21, 2021 selected",
+    );
+    await canvas.findByText("Start: 2021-01-01");
+    await canvas.findByText("End: 2021-01-21");
+    await fireEvent.click(canvas.getByLabelText("Sunday, January 24, 2021"));
+    await fireEvent.click(canvas.getByLabelText("Saturday, January 30, 2021"));
+    await canvas.findByLabelText(
+      "Selected Range: Sunday, January 24 to Saturday, January 30, 2021, Sunday, January 24, 2021 selected",
+    );
+    await canvas.findByLabelText(
+      "Selected Range: Sunday, January 24 to Saturday, January 30, 2021, Saturday, January 30, 2021 selected",
+    );
+    await canvas.findByText("Start: 2021-01-24");
+    await canvas.findByText("End: 2021-01-30");
+  },
+};
+
+export const TestMultipleMode: Story = {
+  render: CalendarStories.MultipleMode.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // Check that an initial value is selected on the Calendar
+    await expect(
+      canvas.getByLabelText("Friday, January 1, 2021"),
+    ).toHaveAttribute("data-multiple-selected", "true");
+
+    // Check that the initial values are present in the debug state
+    await canvas.findByText("2021-01-01");
+
+    // Check that an element is unselected, then click on it, and check that it is selected
+    await expect(
+      canvas.getByLabelText("Saturday, January 2, 2021"),
+    ).toHaveAttribute("data-multiple-selected", "false");
+    await fireEvent.click(canvas.getByLabelText("Saturday, January 2, 2021"));
+    await expect(
+      canvas.getByLabelText("Saturday, January 2, 2021"),
+    ).toHaveAttribute("data-multiple-selected", "true");
+  },
+};
+```
+
+## 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, Source, Canvas } from "@storybook/addon-docs/blocks";
+
+import * as Calendar from "./Calendar.stories";
+import * as CalendarTests from "./tests/Calendar.stories";
+
+<Meta of={Calendar} />
+
+# Calendar
+
+A calendar displays one or more date grids and allows users to select a single date.
+
+This is the exact same component as the one used in the DatePicker and DateRangePicker components.
+
+<Canvas of={Calendar.Playground} />
+<Controls of={Calendar.Playground} />
+
+## Example usage : "single" mode
+
+<Canvas of={Calendar.SingleMode} sourceState="shown" />
+
+## Example usage : "range" mode
+
+<Canvas of={Calendar.RangeMode} sourceState="shown" />
+
+## Example usage : "multiple" mode
+
+<Canvas of={Calendar.MultipleMode} sourceState="shown" />
+
+## Customizing the Calendar Cells
+
+The Calendar provides you with a `CalendarCell` component that you can use to customize the cells of the calendar.
+
+this way, you have complete control over the calendar's appearance and can create totally unique behaviors specific to your application.
+
+Below are a few use cases and how to achieve them.
+
+### Cells with multiple states : activation and indisponibility
+
+Here is the feature needed :
+
+- Have a calendar that display dates that can have multiple states : activation and indisponibility
+- When a date is activated, the cell is green
+- When a date is indisponible, the cell is red
+- When a date is both activated and indisponible, the cell is half green and half red
+
+To achieve this, we can use the `CalendarCell` component and override the default styles with CSS variables.
+Also, we use the "single" mode on the Calendar to allow the user to select a single date (to see more details above for example)
+
+<Canvas of={Calendar.CustomCellSingleMode} sourceState="shown" />
+
+## How to test the Calendar component
+
+Here are some code examples based on react-testing-library about how to test each mode of the Calendar component.
+
+As you can see, **we must use `fireEvent` instead of `userEvent`** due to some limitations.
+
+To know the text you need to target for a specific date, use your browser's dev tools and inspect the aria-label attribute of the element.
+
+The language of those aria-labels depends on the user's locale or the `I18nProvider` provided in your app (or test file).
+
+### Testing the "single" mode
+
+<Source of={CalendarTests.TestSingleMode} />
+
+### Testing the "range" mode
+
+<Source of={CalendarTests.TestRangeMode} />
+
+### Testing the "multiple" mode
+
+<Source of={CalendarTests.TestMultipleMode} />
+```

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

@@ -0,0 +1,151 @@
+# ChartLegend
+
+## 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/ChartLegend/ChartLegend.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { userEvent, within, waitFor, expect, fn } from "storybook/test";
+
+import ChartLegend from "./ChartLegend";
+import { chartIcons } from "@packages/internal-components/ChartIcon/ChartIcon";
+
+const meta: Meta<typeof ChartLegend> = {
+  component: ChartLegend,
+  tags: ["autodocs"],
+  argTypes: {
+    text: { type: "string" },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+};
+export default meta;
+
+export const Playground: StoryObj<typeof ChartLegend> = {
+  args: {
+    text: "Legend",
+    onClick: fn(),
+    chartColor: "var(--color-content-brand-brand-2)",
+  },
+};
+
+export const Clicked: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByText("Legend"));
+    await waitFor(() => expect(args.onClick).toHaveBeenCalledTimes(1));
+  },
+};
+
+export const Hover: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    // @ts-ignore
+    "data-force-hovered": true,
+  },
+};
+
+export const Selected: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    isSelected: true,
+  },
+};
+
+export const SelectedHover: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Selected.args,
+    // @ts-ignore
+    "data-force-hovered": true,
+  },
+};
+
+export const DefaultFocus: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    // @ts-ignore
+    "data-force-focus-visible": true,
+  },
+};
+
+export const SelectedFocus: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Selected.args,
+    // @ts-ignore
+    "data-force-focus-visible": true,
+  },
+};
+
+export const Pressed: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    // @ts-ignore
+    "data-force-pressed": true,
+  },
+};
+
+export const WithoutInteraction: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    onClick: undefined,
+  },
+};
+
+export const AllIcons: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    onClick: undefined,
+  },
+  render: (args) => (
+    <div style={{ display: "flex", gap: "var(--spacing-xs)" }}>
+      {chartIcons.map((icon) => (
+        <ChartLegend key={icon} {...args} icon={icon} text={icon} />
+      ))}
+    </div>
+  ),
+};
+
+export const WithCustomIcon: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    onClick: undefined,
+    customIcon: (
+      <svg width="12" height="12" viewBox="0 0 32 32">
+        <path
+          cx="16"
+          cy="16"
+          transform="translate(16, 16)"
+          d="M0,-16L9.237604307034012,0L0,16L-9.237604307034012,0Z"
+          fill="var(--chart-color)" // use this CSS variable to get the proper color for each item
+        />
+      </svg>
+    ),
+  },
+};
+
+export const WithLightColor: StoryObj<typeof ChartLegend> = {
+  args: {
+    ...Playground.args,
+    onClick: undefined,
+    chartColor: "var(--color-content-dataviz-azure-2)",
+    circleOutlineColor: "var(--color-content-dataviz-azure-3)",
+  },
+};
+```