@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,638 @@
+# YearMonthPicker
+
+## 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/YearMonthPicker/YearMonthPicker.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, screen, userEvent, within } from "storybook/test";
+import YearMonthPicker, { YearMonthPickerValue } from "./YearMonthPicker";
+import { I18nProvider } from "react-aria-components";
+import { useState } from "react";
+
+const meta: Meta<typeof YearMonthPicker> = {
+  component: YearMonthPicker,
+  parameters: {
+    layout: "centered",
+  },
+  args: {
+    onChange: fn(),
+  },
+  argTypes: {
+    label: { control: "text" },
+    value: { control: false },
+    description: { control: "text" },
+    helperText: { control: "text" },
+    errorHelperText: { control: "text" },
+    successHelperText: { control: "text" },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en-EN">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const PlaygroundMonth: Story = {
+  args: {
+    label: "Pick a month",
+    mode: "month",
+    required: true,
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    buttonProps: {
+      style: { width: 220 },
+    },
+  },
+  render: (args) => {
+    function Parent() {
+      const [value, setValue] = useState<YearMonthPickerValue>({
+        month: args.value?.month || null,
+      });
+
+      return (
+        <div>
+          <YearMonthPicker
+            {...args}
+            mode={args.mode}
+            value={value}
+            onChange={(value) => {
+              args.onChange?.(value);
+              setValue(value);
+            }}
+          />
+        </div>
+      );
+    }
+    return <Parent />;
+  },
+};
+
+export const PlaygroundYear: Story = {
+  args: {
+    label: "Pick a year",
+    mode: "year",
+    firstYear: 2020,
+    lastYear: 2025,
+    buttonProps: {
+      style: { width: 220 },
+    },
+  },
+  render: (args) => {
+    function Parent() {
+      const [value, setValue] = useState<YearMonthPickerValue>({
+        year: args.value?.year || null,
+      });
+
+      return (
+        <div>
+          <YearMonthPicker
+            {...args}
+            mode={args.mode}
+            value={value}
+            onChange={(value) => {
+              args.onChange?.(value);
+              setValue(value);
+            }}
+          />
+        </div>
+      );
+    }
+    return <Parent />;
+  },
+};
+
+export const PlaygroundYearAndMonth: Story = {
+  args: {
+    label: "Pick a month and year",
+    mode: "month-year",
+    firstYear: 2020,
+    lastYear: 2025,
+    buttonProps: {
+      style: { width: 220 },
+    },
+  },
+  render: (args) => {
+    function Parent() {
+      const [value, setValue] = useState<YearMonthPickerValue>({
+        year: args.value?.year || null,
+        month: args.value?.month || null,
+      });
+
+      return (
+        <div>
+          <YearMonthPicker
+            {...args}
+            mode={args.mode}
+            value={value}
+            onChange={(value) => {
+              args.onChange?.(value);
+              setValue(value);
+            }}
+          />
+        </div>
+      );
+    }
+    return <Parent />;
+  },
+};
+
+export const MonthWithInitialValue: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    value: {
+      month: "02",
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("February");
+  },
+};
+
+export const YearWithInitialValue: Story = {
+  args: {
+    ...PlaygroundYear.args,
+    value: {
+      year: "2024",
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("2024");
+  },
+};
+
+export const MonthAndYearWithInitialValue: Story = {
+  args: {
+    ...PlaygroundYearAndMonth.args,
+    value: {
+      month: "02",
+      year: "2024",
+    },
+    buttonProps: undefined,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("February 2024");
+  },
+};
+
+export const WithHelperText: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    helperText: "Some helper text",
+    helperTextIcon: "help_outline",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Some helper text");
+  },
+};
+
+export const WithErrorHelperText: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    errorHelperText: "Some error helper text",
+    errorHelperTextIcon: "error_outline",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("Some error helper text");
+  },
+};
+
+export const WithSuccessHelperText: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    successHelperText: "Some success helper text",
+    successHelperTextIcon: "check",
+  },
+};
+
+export const WithWarningHelperText: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    warningHelperText: "Some warning helper text",
+    warningHelperTextIcon: "warning_amber",
+  },
+};
+
+export const WithLabelIconRight: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    labelIconRight: "help_outline",
+  },
+};
+
+export const WithCustomInputIcon: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    inputIcon: "help_outline",
+  },
+};
+
+export const Horizontal: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    orientation: "horizontal",
+    helperText: "Some helper text",
+    helperTextIcon: "help_outline",
+  },
+};
+
+export const FullWidth: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  args: {
+    ...PlaygroundMonth.args,
+    buttonProps: undefined,
+    fullWidth: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    ...PlaygroundMonth.args,
+    disabled: true,
+  },
+};
+
+export const DescendingYears: Story = {
+  args: {
+    ...PlaygroundYear.args,
+    sortYears: "descending",
+  },
+};
+
+export const WithTallDropdown: Story = {
+  args: {
+    ...PlaygroundYearAndMonth.args,
+    tallDropdown: true,
+  },
+  render: (args) => {
+    function Parent() {
+      const [value, setValue] = useState<YearMonthPickerValue>({
+        year: args.value?.year || null,
+        month: args.value?.month || null,
+      });
+
+      return (
+        <div>
+          <YearMonthPicker
+            {...args}
+            mode="month-year"
+            value={value}
+            onChange={(value) => {
+              args.onChange?.(value);
+              setValue(value);
+            }}
+          />
+        </div>
+      );
+    }
+    return <Parent />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup();
+    await user.click(canvas.getByLabelText("Open: Pick a month and year"));
+    const listbox = await screen.findByRole("listbox");
+    await expect(listbox).toHaveAttribute("data-tall", "true");
+  },
+};
+```
+
+## 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 { useState } from "react";
+import { userEvent, within, screen, expect } from "storybook/test";
+import YearMonthPicker, { YearMonthPickerValue } from "../YearMonthPicker";
+import * as YearMonthPickerStories from "../YearMonthPicker.stories";
+
+const meta: Meta<typeof YearMonthPicker> = {
+  ...YearMonthPickerStories.default,
+  component: YearMonthPicker,
+  parameters: {
+    ...YearMonthPickerStories.default.parameters,
+    chromatic: { disableSnapshot: true },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const MonthShouldSelectAValue: Story = {
+  args: { ...YearMonthPickerStories.PlaygroundMonth.args },
+  // @ts-expect-error
+  render: (args) => YearMonthPickerStories.PlaygroundMonth.render(args),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Open: Pick a month"));
+    await user.click(await screen.findByText("January"));
+    await expect(args.onChange).toHaveBeenCalledWith({ month: "01" });
+    await expect(canvas.getByLabelText("Open: Pick a month")).toHaveTextContent(
+      "January",
+    );
+  },
+};
+
+export const MonthShouldChangeAnInitialValue: Story = {
+  args: {
+    ...YearMonthPickerStories.PlaygroundMonth.args,
+    value: { month: "02" },
+  },
+  // @ts-expect-error
+  render: (args) => YearMonthPickerStories.PlaygroundMonth.render(args),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText("Open: Pick a month")).toHaveTextContent(
+      "February",
+    );
+    await user.click(canvas.getByLabelText("Open: Pick a month"));
+    await user.click(await screen.findByText("January"));
+    await expect(args.onChange).toHaveBeenCalledWith({ month: "01" });
+    await expect(canvas.getByLabelText("Open: Pick a month")).toHaveTextContent(
+      "January",
+    );
+  },
+};
+
+export const YearShouldSelectAValue: Story = {
+  args: { ...YearMonthPickerStories.PlaygroundYear.args },
+  // @ts-expect-error
+  render: (args) => YearMonthPickerStories.PlaygroundYear.render(args),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Open: Pick a year"));
+    await user.click(await screen.findByText("2023"));
+    await expect(args.onChange).toHaveBeenCalledWith({ year: "2023" });
+    await expect(canvas.getByLabelText("Open: Pick a year")).toHaveTextContent(
+      "2023",
+    );
+  },
+};
+
+export const YearShouldChangeAnInitialValue: Story = {
+  args: {
+    ...YearMonthPickerStories.PlaygroundYear.args,
+    value: { year: "2024" },
+  },
+  // @ts-expect-error
+  render: (args) => YearMonthPickerStories.PlaygroundYear.render(args),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText("Open: Pick a year")).toHaveTextContent(
+      "2024",
+    );
+    await user.click(canvas.getByLabelText("Open: Pick a year"));
+    await user.click(await screen.findByText("2023"));
+    await expect(args.onChange).toHaveBeenCalledWith({ year: "2023" });
+    await expect(canvas.getByLabelText("Open: Pick a year")).toHaveTextContent(
+      "2023",
+    );
+  },
+};
+
+export const MonthAndYearShouldSelectAValue: Story = {
+  args: { ...YearMonthPickerStories.PlaygroundYearAndMonth.args },
+  // @ts-expect-error
+  render: (args) => YearMonthPickerStories.PlaygroundYearAndMonth.render(args),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Open: Pick a month and year"));
+    await user.click(await screen.findByText("February"));
+    await expect(args.onChange).toHaveBeenCalledWith({
+      month: "02",
+      year: null,
+    });
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("February");
+    await user.click(await screen.findByText("2023"));
+    await expect(args.onChange).toHaveBeenCalledWith({
+      month: "02",
+      year: "2023",
+    });
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("February");
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("2023");
+  },
+};
+
+export const MonthAndYearShouldChangeAnInitialValue: Story = {
+  args: {
+    ...YearMonthPickerStories.PlaygroundYearAndMonth.args,
+    value: { month: "02", year: "2023" },
+  },
+  // @ts-expect-error
+  render: (args) => YearMonthPickerStories.PlaygroundYearAndMonth.render(args),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("February 2023");
+    await user.click(canvas.getByLabelText("Open: Pick a month and year"));
+    await user.click(await screen.findByText("March"));
+    await expect(args.onChange).toHaveBeenCalledWith({
+      month: "03",
+      year: "2023",
+    });
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("March 2023");
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("2023");
+    await user.click(await screen.findByText("2022"));
+    await expect(args.onChange).toHaveBeenCalledWith({
+      month: "03",
+      year: "2022",
+    });
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("March");
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("2022");
+  },
+};
+
+export const ShouldAllowReSelectingTheSameValue: Story = {
+  args: {
+    ...YearMonthPickerStories.PlaygroundYearAndMonth.args,
+    value: { month: "02", year: "2023" },
+  },
+  // @ts-expect-error
+  render: (args) => YearMonthPickerStories.PlaygroundYearAndMonth.render(args),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("February 2023");
+    await user.click(canvas.getByLabelText("Open: Pick a month and year"));
+    await user.click(await screen.findByText("February", { selector: "span" }));
+    await expect(args.onChange).not.toHaveBeenCalled();
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("February");
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("2023");
+    await user.click(await screen.findByText("2023"));
+    await expect(args.onChange).not.toHaveBeenCalled();
+    await expect(
+      canvas.getByLabelText("Open: Pick a month and year"),
+    ).toHaveTextContent("February 2023");
+  },
+};
+
+export const ExampleUsageMonthMode: Story = {
+  render: () => {
+    function Parent() {
+      const [value, setValue] = useState<YearMonthPickerValue>({
+        month: null,
+      });
+
+      return (
+        <YearMonthPicker
+          label="Pick a month"
+          mode="month"
+          value={value}
+          onChange={setValue}
+        />
+      );
+    }
+    return <Parent />;
+  },
+};
+
+export const ExampleUsageYearMode: Story = {
+  render: () => {
+    function Parent() {
+      const [value, setValue] = useState<YearMonthPickerValue>({
+        year: null,
+      });
+
+      return (
+        <YearMonthPicker
+          label="Pick a year"
+          mode="year"
+          value={value}
+          onChange={setValue}
+        />
+      );
+    }
+    return <Parent />;
+  },
+};
+
+export const ExampleUsageYearAndMonthMode: Story = {
+  render: () => {
+    function Parent() {
+      const [value, setValue] = useState<YearMonthPickerValue>({
+        year: null,
+        month: null,
+      });
+
+      return (
+        <YearMonthPicker
+          label="Pick a month and year"
+          mode="month-year"
+          value={value}
+          onChange={setValue}
+        />
+      );
+    }
+    return <Parent />;
+  },
+};
+```
+
+## 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 YearMonthPicker from "./YearMonthPicker.stories";
+import * as YearMonthPickerTests from "./tests/YearMonthPicker.stories";
+
+<Meta of={YearMonthPicker} />
+
+# YearMonthPicker
+
+The YearMonthPicker component allows users to pick a month, a year, or both!
+
+This component **should always be controlled** with the `value` and `onChange` props.
+
+## Example usage -> Month mode
+
+<Source of={YearMonthPickerTests.ExampleUsageMonthMode} type="code" dark />
+
+## Example usage -> Year mode
+
+<Source of={YearMonthPickerTests.ExampleUsageYearMode} type="code" dark />
+
+## Example usage -> Month and Year mode
+
+<Source
+  of={YearMonthPickerTests.ExampleUsageYearAndMonthMode}
+  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
+
+1. Open the picker with the trigger button, which have an aria-label that says "Open: \{label prop\}". (for example "Open: Pick a month")
+2. Click on a value (using `screen` from testing library because the value is inside a dialog)
+3. Assert that the correct value was selected
+
+Here is an example code of how to test the component:
+
+<Source of={YearMonthPickerTests.MonthShouldSelectAValue} type="code" dark />
+
+## Playground & Props
+
+<Canvas of={YearMonthPicker.PlaygroundYearAndMonth} />
+
+<Controls of={YearMonthPicker.PlaygroundYearAndMonth} />
+
+<Stories />
+```