@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,638 @@
+# DateRangePicker
+
+## 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/DateRangePicker/DateRangePicker.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import DateRangePicker from "./DateRangePicker";
+import { I18nProvider } from "react-aria-components";
+import { fn } from "storybook/test";
+
+const meta: Meta<typeof DateRangePicker> = {
+  component: DateRangePicker,
+  argTypes: {
+    label: { control: "text" },
+    value: { control: "text" },
+    timeZone: {
+      control: "select",
+      options: ["America/New_York", "Europe/Paris"],
+    },
+    shouldCloseOnSelect: { control: "boolean" },
+    description: { control: "text" },
+    helperText: { control: "text" },
+    errorHelperText: { control: "text" },
+    successHelperText: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  globals: {
+    backgrounds: { value: "light" },
+  },
+  decorators: [
+    (Story, context) => (
+      <I18nProvider locale={context.parameters.locale || "en-EN"}>
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+export const Playground: StoryObj<typeof DateRangePicker> = {
+  args: {
+    label: "Date Range Picker",
+    id: "date-range-picker",
+    onChange: fn(),
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    defaultValue: {
+      start: "2020-01-01T12:00:00",
+      end: "2020-01-10T12:00:00",
+    },
+  },
+};
+
+export const Empty: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: undefined,
+  },
+};
+
+export const WithTime: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: {
+      start: "2020-01-01T12:00:00",
+      end: "2020-01-10T12:00:00",
+    },
+  },
+};
+
+export const WithTimeZone: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: {
+      start: "2020-01-01T12:00:00",
+      end: "2020-01-10T12:00:00",
+    },
+    timeZone: "America/New_York",
+  },
+};
+
+export const LocaleFR: StoryObj<typeof DateRangePicker> = {
+  parameters: {
+    locale: "fr-FR",
+  },
+  args: {
+    ...WithTimeZone.args,
+  },
+};
+
+export const WithMinValue: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: {
+      start: "2020-01-15",
+      end: "2020-01-15",
+    },
+    minValue: "2020-01-10",
+  },
+};
+
+export const WithMaxValue: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: {
+      start: "2020-01-08",
+      end: "2020-01-08",
+    },
+    maxValue: "2020-01-10",
+  },
+};
+
+export const Disabled: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+};
+
+export const WithError: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    errorHelperText: "Error message",
+    errorHelperTextIcon: "error_outline",
+  },
+};
+
+export const WithSuccess: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    successHelperText: "Success message",
+    successHelperTextIcon: "check",
+  },
+};
+
+export const WithWarning: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    warningHelperText: "Warning message",
+    warningHelperTextIcon: "warning_amber",
+  },
+};
+
+export const Horizontal: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    orientation: "horizontal",
+  },
+};
+
+export const Open: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    isOpen: true,
+  },
+};
+
+export const FullWidth: StoryObj<typeof DateRangePicker> = {
+  parameters: {
+    layout: "padded",
+  },
+  args: {
+    ...Playground.args,
+    fullWidth: 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 DateRangePicker from "../DateRangePicker";
+import {
+  userEvent,
+  within,
+  screen,
+  fireEvent,
+  expect,
+  fn,
+} from "storybook/test";
+import { I18nProvider } from "react-aria-components";
+import { useState } from "react";
+import { Playground } from "../DateRangePicker.stories";
+import { useController, useForm } from "react-hook-form";
+
+const meta: Meta<typeof DateRangePicker> = {
+  component: DateRangePicker,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en-EN">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+export const ShouldSelectADateValue: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    onChange: fn(),
+    defaultValue: {
+      start: "2020-01-01",
+      end: "2020-01-03",
+    },
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText(/month, Start Date/)).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText(/day, Start Date/)).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText(/year, Start Date/)).toHaveTextContent(
+      "2020",
+    );
+    await expect(canvas.getByLabelText(/month, End Date/)).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText(/day, End Date/)).toHaveTextContent("3");
+    await expect(canvas.getByLabelText(/year, End Date/)).toHaveTextContent(
+      "2020",
+    );
+
+    await user.click(canvas.getByLabelText("Open calendar Date Range Picker"));
+    await screen.findByLabelText("Sunday, January 5, 2020");
+    await fireEvent.click(screen.getByLabelText("Sunday, January 5, 2020"));
+    await fireEvent.click(screen.getByLabelText("Saturday, January 11, 2020"));
+    await expect(args.onChange).toHaveBeenCalledWith({
+      start: "2020-01-05",
+      end: "2020-01-11",
+    });
+    await expect(canvas.getByLabelText(/month, Start Date/)).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText(/day, Start Date/)).toHaveTextContent(
+      "5",
+    );
+    await expect(canvas.getByLabelText(/year, Start Date/)).toHaveTextContent(
+      "2020",
+    );
+    await expect(canvas.getByLabelText(/month, End Date/)).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText(/day, End Date/)).toHaveTextContent(
+      "11",
+    );
+    await expect(canvas.getByLabelText(/year, End Date/)).toHaveTextContent(
+      "2020",
+    );
+  },
+};
+
+export const ShouldSelectADateTimeValue: StoryObj<typeof DateRangePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: {
+      start: "2020-01-01T10:00:00",
+      end: "2020-01-03T10:00:00",
+    },
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Open calendar Date Range Picker"));
+    await screen.findByLabelText("Sunday, January 5, 2020");
+    await fireEvent.click(screen.getByLabelText("Sunday, January 5, 2020"));
+    await fireEvent.click(screen.getByLabelText("Saturday, January 11, 2020"));
+    await expect(args.onChange).toHaveBeenCalledWith({
+      start: "2020-01-05T10:00:00",
+      end: "2020-01-11T10:00:00",
+    });
+  },
+};
+
+export const ShouldSelectADateTimeValueWithTimezone: StoryObj<
+  typeof DateRangePicker
+> = {
+  args: {
+    ...Playground.args,
+    timeZone: "Europe/Paris",
+    defaultValue: {
+      start: "2020-01-01T10:00:00",
+      end: "2020-01-03T10:00:00",
+    },
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Open calendar Date Range Picker"));
+    await screen.findByLabelText("Sunday, January 5, 2020");
+    await fireEvent.click(screen.getByLabelText("Sunday, January 5, 2020"));
+    await fireEvent.click(screen.getByLabelText("Saturday, January 11, 2020"));
+    await expect(args.onChange).toHaveBeenCalledWith({
+      start: "2020-01-05T09:00:00.000Z",
+      end: "2020-01-11T09:00:00.000Z",
+    });
+  },
+};
+
+export const ShouldManageThePlaceholdervalueIfATimezoneIsGiven: StoryObj<
+  typeof DateRangePicker
+> = {
+  args: {
+    ...Playground.args,
+    defaultValue: undefined,
+    timeZone: "Europe/Paris",
+    granularity: "minute",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getAllByText("GMT+1")).toHaveLength(2);
+  },
+};
+
+export const ExampleWithReactHookForm: StoryObj<typeof DateRangePicker> = {
+  render: () => {
+    const ParentComponent = () => {
+      const { control } = useForm({
+        defaultValues: {
+          date: {
+            start: "2020-01-01",
+            end: "2020-01-03",
+          },
+        },
+      });
+
+      const { field } = useController({ control, name: "date" });
+
+      return (
+        <>
+          <div>
+            Selected date : {field.value?.start} - {field.value?.end}
+          </div>
+          <DateRangePicker
+            {...field}
+            id="example-controlled date range picker"
+            label="Date Range Picker"
+          />
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const ControlledShouldSelectAValue: StoryObj<typeof DateRangePicker> = {
+  render: ExampleWithReactHookForm.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Selected date : 2020-01-01 - 2020-01-03");
+    await user.click(canvas.getByLabelText("Open calendar Date Range Picker"));
+    await screen.findByLabelText("Sunday, January 5, 2020");
+    await fireEvent.click(screen.getByLabelText("Sunday, January 5, 2020"));
+    await fireEvent.click(screen.getByLabelText("Saturday, January 11, 2020"));
+    await canvas.findByText("Selected date : 2020-01-05 - 2020-01-11");
+  },
+};
+
+export const ExampleGranularity: StoryObj<typeof DateRangePicker> = {
+  render: () => {
+    function Example() {
+      const [date, setDate] = useState<null | {
+        start: string;
+        end: string;
+      }>({
+        start: "2021-04-07T18:45:22Z",
+        end: "2021-04-07T18:45:22Z",
+      });
+
+      return (
+        <>
+          <DateRangePicker
+            id="date-and-time"
+            label="Date and time"
+            granularity="second"
+            value={date}
+            onChange={setDate}
+          />
+
+          <DateRangePicker
+            id="date"
+            label="Date"
+            granularity="day"
+            value={date}
+            onChange={setDate}
+          />
+        </>
+      );
+    }
+    return <Example />;
+  },
+};
+
+export const ExampleGranularity2: StoryObj<typeof DateRangePicker> = {
+  render: () => {
+    function Example() {
+      return (
+        <>
+          <DateRangePicker
+            id="second"
+            label="Event date"
+            granularity="second"
+          />
+          <DateRangePicker id="day" label="Event date" granularity="day" />
+        </>
+      );
+    }
+    return <Example />;
+  },
+};
+
+export const ExampleInternationalCalendar: StoryObj<typeof DateRangePicker> = {
+  render: () => {
+    function Example() {
+      const [date, setDate] = useState<null | {
+        start: string;
+        end: string;
+      }>(null);
+
+      return (
+        <I18nProvider locale="hi-IN-u-ca-indian">
+          <DateRangePicker
+            id="international-calendar"
+            label="Date"
+            value={date}
+            onChange={setDate}
+          />
+          <p>
+            Selected date: {date?.start} - {date?.end}
+          </p>
+        </I18nProvider>
+      );
+    }
+    return <Example />;
+  },
+};
+
+export const ExampleMinMax: StoryObj<typeof DateRangePicker> = {
+  render: () => {
+    return (
+      <DateRangePicker
+        id="min-max"
+        label="Min Max"
+        minValue="2020-01-01"
+        maxValue="2020-01-10"
+        defaultValue={{
+          start: "2020-01-02",
+          end: "2020-01-07",
+        }}
+      />
+    );
+  },
+};
+
+export const ExampleUnavailableDates: StoryObj<typeof DateRangePicker> = {
+  render: () => {
+    return (
+      <DateRangePicker
+        id="unavailable-dates"
+        label="Unavailable dates"
+        isDateUnavailable={(stringDate) => {
+          const date = new Date(stringDate);
+          // 0 is Sunday, 6 is Saturday
+          if (date.getDay() === 0 || date.getDay() === 6) {
+            return true;
+          }
+          return false;
+        }}
+      />
+    );
+  },
+};
+```
+
+## 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,
+  Story,
+} from "@storybook/addon-docs/blocks";
+
+import * as DateRangePicker from "./DateRangePicker.stories";
+import * as DateRangePickerTests from "./tests/DateRangePicker.stories";
+
+<Meta of={DateRangePicker} />
+
+# DateRangePicker
+
+A date range picker combines two DateFields and a RangeCalendar popover to allow users to enter or select a date and time range.
+
+<Canvas of={DateRangePicker.Playground} />
+<Controls of={DateRangePicker.Playground} />
+
+## Example (with React Hook Form)
+
+<Source of={DateRangePickerTests.ExampleWithReactHookForm} type="code" dark />
+
+A date range picker can be built using two separate `<input type="date">` elements, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style.
+DateRangePicker helps achieve accessible and international date and time range pickers that can be styled as needed.
+
+- **Dates and times** – Support for dates and times with configurable granularity.
+- **International** – Support for 13 calendar systems used around the world, including Gregorian, Buddhist, Islamic, Persian, and more. Locale-specific formatting, number systems, hour cycles, and right-to-left support are available as well.
+- **Time zone aware** – Dates and times can optionally include a time zone. All modifications follow time zone rules such as daylight saving time.
+- **Accessible** – Each date and time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit dates using the keyboard, in any date format and locale. Users can also open a calendar popover to select date ranges in a standard month grid. Localized screen reader messages are included to announce when the selection and visible date range change.
+- **Touch friendly** – Date segments are editable using an easy to use numeric keypad, date ranges can be selected by dragging over dates in the calendar using a touch screen, and all interactions are accessible using touch-based screen readers.
+- **Validation** – Integrates with HTML forms, supporting required, minimum and maximum values, unavailable dates, custom validation functions, realtime validation, and server-side validation errors.
+- **Customizable** – As with all of React Aria, the DOM structure and styling of all elements can be fully customized.
+
+Read [the React Aria blog post](https://react-spectrum.adobe.com/blog/date-and-time-pickers-for-all.html) for more details about the internationalization, accessibility, and user experience features implemented by DateRangePicker.
+
+## Value
+
+A `DateRangePicker` displays a placeholder by default. An initial, uncontrolled value can be provided to the `DateRangePicker` using the `defaultValue` prop.
+Alternatively, a controlled value can be provided using the `value` and `onchange` props.
+
+Here is the type for the `value` prop (also valid for `defaultValue`, `onChange`, etc.):
+
+```ts
+type DateRangePickerValue = null | {
+  start: string;
+  end: string;
+};
+```
+
+Date values are provided as string.
+This component handles correct international date manipulation across calendars, time zones, and other localization concerns.
+DateRangePicker supports values of the following string formats:
+
+- `YYYY-MM-DD` -> a date without any time components. Use this type to represent dates where the time is not important, such as a birthday or an all day calendar event.
+- `YYYY-MM-DDTHH:mm:ss` -> a date with a time, but not in any specific time zone. Use this type to represent times that occur at the same local time regardless of the time zone, such as the time of New Years Eve fireworks which always occur at midnight. Most times are better stored with a timezone (see below)
+- `YYYY-MM-DDTHH:mm:ss+HH:mm` + "Europe/Paris" in `timezone` prop -> a date with a time in a specific time zone. Use this type to represent an exact moment in time at a particular location on Earth. The offset is optionnal, but if provided must be in the format `HH:mm` and match the timezone.
+
+## Granularity
+
+The granularity prop allows you to control the smallest unit that is displayed by DatePicker.
+By default, dates values are displayed with "day" granularity (year, month, and day) if there is no time part in it, and "minute" granularity if there is a time part.
+More granular time values can be displayed by setting the granularity prop to "second".
+
+In addition, when a value with a time is provided but you wish to only display the date, you can set the granularity to "day".
+This has no effect on the actual value (it still has a time component), only on what fields are displayed.
+In the following example, two DatePickers are synchronized with the same value, but display different granularities.
+
+<Canvas of={DateRangePickerTests.ExampleGranularity} sourceState="shown" />
+
+If no value or defaultValue prop is passed, then the granularity prop also affects which type of value is emitted from the onChange event.
+
+<Canvas of={DateRangePickerTests.ExampleGranularity2} sourceState="shown" />
+
+## International calendar
+
+DatePicker supports selecting dates in many calendar systems used around the world, including Gregorian, Hebrew, Indian, Islamic, Buddhist, and more.
+Dates are automatically displayed in the appropriate calendar system for the user's locale.
+The calendar system can be overridden using the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string), passed to the [I18nProvider](?path=/docs/components-i18nprovider--docs) component.
+
+Selected dates passed to onChange always use the same calendar system as the value or defaultValue prop.
+If no value or defaultValue is provided, then dates passed to onChange are always in the Gregorian calendar since this is the most commonly used.
+This means that even though the user selects dates in their local calendar system, applications are able to deal with dates from all users consistently.
+
+The below example displays a DatePicker in the Hindi language, using the Indian calendar.
+Dates emitted from onChange are in the Gregorian calendar.
+
+<Canvas
+  of={DateRangePickerTests.ExampleInternationalCalendar}
+  sourceState="shown"
+/>
+
+## Minimum and maximum values
+
+The `minValue` and `maxValue` props can also be used to ensure the value is within a specific range.
+Here is an example:
+
+<Canvas of={DateRangePickerTests.ExampleMinMax} sourceState="shown" />
+
+## Unavailable dates
+
+DatePicker supports marking certain dates as unavailable.
+These dates remain focusable with the keyboard in the calendar so that navigation is consistent, but cannot be selected by the user.
+When an unavailable date is entered into the date field, it is marked as invalid (but error message and submission prevention should be made by you on the form level).
+The `isDateUnavailable` prop accepts a callback that is called to evaluate whether each visible date is unavailable.
+
+This example show how to mark all week-ends as unavailable.
+
+<Canvas of={DateRangePickerTests.ExampleUnavailableDates} sourceState="shown" />
+
+## How to test this component
+
+First, click on the button that triggers the calendar opening. It will have a label name formatted like this: `Open calendar ${label}`.
+For example: `getByLabelText("Open calendar Date Picker")` if the component has a label "Date Picker".
+
+Second, you need to click on a date. The date will show up in a popup.
+You may need to use `screen.getByLabelText` to target an element inside it. The label will have the corresponding date formatted in the language you provided with the `I18nProvider`.
+
+For example, if the locale is "en", you can target a specific date visible in the actual opened calendar using the code `fireEvent.click(screen.getByLabelText("Thursday, January 2, 2020"))`.
+
+You may notice that we used `fireEvent` because of a bug with `userEvent` on Firefox for some specific edge cases that (sadly) happen with this calendar.
+
+If you want to target any other part of the component, just inspect the rendered HTML and you will see that every targetable element has a dedicated aria-label that you can target with `screen.getByLabelText`.
+
+Here is a complete example of one of our tests using Storybook and Testing Library:
+
+<Source of={DateRangePickerTests.ShouldSelectADateValue} type="code" dark />
+````