@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,579 @@
+# DatePicker
+
+## 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/DatePicker/DatePicker.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import DatePicker from "./DatePicker";
+import { I18nProvider } from "react-aria-components";
+import { fn } from "storybook/test";
+
+const meta: Meta<typeof DatePicker> = {
+  component: DatePicker,
+  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",
+  },
+  decorators: [
+    (Story, context) => (
+      <I18nProvider locale={context.parameters.locale || "en-EN"}>
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+export const Playground: StoryObj<typeof DatePicker> = {
+  args: {
+    label: "Date Picker",
+    id: "date-picker",
+    defaultValue: "2020-01-01T12:00:00",
+    onChange: fn(),
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+  },
+};
+
+export const Empty: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: undefined,
+  },
+};
+export const WithTime: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "2020-01-01T12:00:00",
+  },
+};
+
+export const WithTimeZone: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "2020-01-01T12:00:00",
+    timeZone: "America/New_York",
+  },
+};
+
+export const LocaleFR: StoryObj<typeof DatePicker> = {
+  parameters: {
+    locale: "fr-FR",
+  },
+  args: {
+    ...WithTimeZone.args,
+  },
+};
+
+export const WithMinValue: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "2020-01-15",
+    minValue: "2020-01-10",
+  },
+};
+
+export const WithMaxValue: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "2020-01-08",
+    maxValue: "2020-01-10",
+  },
+};
+
+export const Disabled: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+};
+
+export const WithError: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    errorHelperText: "Error message",
+    errorHelperTextIcon: "error_outline",
+  },
+};
+
+export const WithSuccess: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    successHelperText: "Success message",
+    successHelperTextIcon: "check",
+  },
+};
+
+export const WithWarning: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    warningHelperText: "Warning message",
+    warningHelperTextIcon: "warning_amber",
+  },
+};
+
+export const Horizontal: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    orientation: "horizontal",
+  },
+};
+
+export const Open: StoryObj<typeof DatePicker> = {
+  args: {
+    ...Playground.args,
+    isOpen: true,
+  },
+};
+
+export const FullWidth: StoryObj<typeof DatePicker> = {
+  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 DatePicker from "../DatePicker";
+import {
+  userEvent,
+  within,
+  screen,
+  fireEvent,
+  expect,
+  fn,
+} from "storybook/test";
+import { I18nProvider } from "react-aria-components";
+import { useState } from "react";
+import { Playground } from "../DatePicker.stories";
+import { useController, useForm } from "react-hook-form";
+
+const meta: Meta<typeof DatePicker> = {
+  component: DatePicker,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en-EN">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+type Story = StoryObj<typeof DatePicker>;
+
+export const ShouldSelectADateValue: Story = {
+  args: {
+    ...Playground.args,
+    onChange: fn(),
+    defaultValue: "2020-01-01",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText("month, Date Picker")).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText("day, Date Picker")).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText("year, Date Picker")).toHaveTextContent(
+      "2020",
+    );
+
+    await user.click(canvas.getByLabelText("Open calendar Date Picker"));
+    await screen.findByLabelText("Thursday, January 2, 2020");
+    await fireEvent.click(screen.getByLabelText("Thursday, January 2, 2020"));
+    await expect(args.onChange).toHaveBeenCalledWith("2020-01-02");
+    await expect(canvas.getByLabelText("month, Date Picker")).toHaveTextContent(
+      "1",
+    );
+    await expect(canvas.getByLabelText("day, Date Picker")).toHaveTextContent(
+      "2",
+    );
+    await expect(canvas.getByLabelText("year, Date Picker")).toHaveTextContent(
+      "2020",
+    );
+  },
+};
+
+export const ShouldSelectADateTimeValue: Story = {
+  args: {
+    ...Playground.args,
+    defaultValue: "2020-01-01T10:00:00",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Open calendar Date Picker"));
+    await screen.findByLabelText("Thursday, January 2, 2020");
+    await fireEvent.click(screen.getByLabelText("Thursday, January 2, 2020"));
+    await expect(args.onChange).toHaveBeenCalledWith("2020-01-02T10:00:00");
+  },
+};
+
+export const ShouldSelectADateTimeValueWithTimezone: StoryObj<
+  typeof DatePicker
+> = {
+  args: {
+    ...Playground.args,
+    timeZone: "Europe/Paris",
+    defaultValue: "2020-01-01T10:00:00",
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await user.click(canvas.getByLabelText("Open calendar Date Picker"));
+    await screen.findByLabelText("Thursday, January 2, 2020");
+    await fireEvent.click(screen.getByLabelText("Thursday, January 2, 2020"));
+    await expect(args.onChange).toHaveBeenCalledWith(
+      "2020-01-02T09:00:00.000Z",
+    );
+  },
+};
+
+export const ShouldManageThePlaceholdervalueIfATimezoneIsGiven: StoryObj<
+  typeof DatePicker
+> = {
+  args: {
+    ...Playground.args,
+    defaultValue: undefined,
+    timeZone: "Europe/Paris",
+    granularity: "minute",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await canvas.findByText("GMT+1");
+  },
+};
+
+export const ExampleWithReactHookForm: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const { control } = useForm({
+        defaultValues: {
+          date: "2020-01-01",
+        },
+      });
+
+      const { field } = useController({ control, name: "date" });
+
+      return (
+        <>
+          <div>Selected date : {field.value}</div>
+          <DatePicker
+            {...field}
+            id="example-controlled date picker"
+            label="Date Picker"
+          />
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const WithReactHookFormShouldSelectAValue: Story = {
+  render: ExampleWithReactHookForm.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Selected date : 2020-01-01");
+    await user.click(canvas.getByLabelText("Open calendar Date Picker"));
+    await screen.findByLabelText("Thursday, January 2, 2020");
+    await fireEvent.click(screen.getByLabelText("Thursday, January 2, 2020"));
+    await canvas.findByText("Selected date : 2020-01-02");
+  },
+};
+
+export const ExampleGranularity: Story = {
+  render: () => {
+    function Example() {
+      const [date, setDate] = useState("2021-04-07T18:45:22Z");
+
+      return (
+        <>
+          <DatePicker
+            id="date-and-time"
+            label="Date and time"
+            granularity="second"
+            value={date}
+            onChange={setDate}
+          />
+          <DatePicker
+            id="date"
+            label="Date"
+            granularity="day"
+            value={date}
+            onChange={setDate}
+          />
+        </>
+      );
+    }
+    return <Example />;
+  },
+};
+
+export const ExampleGranularity2: Story = {
+  render: () => {
+    function Example() {
+      return (
+        <>
+          <DatePicker id="second" label="Event date" granularity="second" />
+          <DatePicker id="day" label="Event date" granularity="day" />
+        </>
+      );
+    }
+    return <Example />;
+  },
+};
+
+export const ExampleInternationalCalendar: Story = {
+  render: () => {
+    function Example() {
+      const [date, setDate] = useState<string | null>(null);
+
+      return (
+        <I18nProvider locale="hi-IN-u-ca-indian">
+          <DatePicker
+            id="international-calendar"
+            label="Date"
+            value={date}
+            onChange={setDate}
+          />
+          <p>Selected date: {date}</p>
+        </I18nProvider>
+      );
+    }
+    return <Example />;
+  },
+};
+
+export const ExampleMinMax: Story = {
+  render: () => {
+    return (
+      <DatePicker
+        id="min-max"
+        label="Min Max"
+        minValue="2020-01-01"
+        maxValue="2020-01-03"
+        defaultValue="2020-01-02"
+      />
+    );
+  },
+};
+
+export const ExampleUnavailableDates: Story = {
+  render: () => {
+    return (
+      <DatePicker
+        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;
+        }}
+      />
+    );
+  },
+};
+
+export const ShouldBeAbleToChangeTheDateManually: Story = {
+  render: () => {
+    const ParentComponent = () => {
+      const [date, setDate] = useState<string | null>(
+        "2020-01-01T10:00:00.000",
+      );
+
+      return (
+        <>
+          <div>Selected date : {date?.toString()}</div>
+          <DatePicker
+            id="example-controlled date picker"
+            label="Date Picker"
+            timeZone="Europe/Paris"
+            value={date}
+            onChange={setDate}
+          />
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Selected date : 2020-01-01T10:00:00.000");
+    await user.type(canvas.getByLabelText("month, Date Picker"), "12");
+    await user.type(canvas.getByLabelText("day, Date Picker"), "20");
+    await user.type(canvas.getByLabelText("year, Date Picker"), "2021");
+    await canvas.findByText("Selected date : 2021-12-20T09:00:00.000Z");
+  },
+};
+```
+
+## 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 DatePicker from "./DatePicker.stories";
+import * as DatePickerTests from "./tests/DatePicker.stories";
+
+<Meta of={DatePicker} />
+
+# DatePicker
+
+A date picker combines a DateField and a Calendar popover to allow users to enter or select a date and time value.
+
+<Canvas of={DatePicker.Playground} />
+<Controls of={DatePicker.Playground} />
+
+## Example (with React Hook Form)
+
+<Source of={DatePickerTests.ExampleWithReactHookForm} type="code" dark />
+
+A date picker can be built using `<input type="date">`, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style. DatePicker helps achieve accessible and international date and time 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 dates 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, and all interactions are accessible using touch-based screen readers.
+
+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 DatePicker.
+
+## Value
+
+A `DatePicker` displays a placeholder by default. An initial, uncontrolled value can be provided to the `DatePicker` using the `defaultValue` prop.
+Alternatively, a controlled value can be provided using the `value` and `onchange` props.
+
+Date values are provided as string.
+This component handles correct international date manipulation across calendars, time zones, and other localization concerns.
+DatePicker 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.000Z` + "Europe/Paris" in `timezone` prop -> ISO 8601 UTC date. Use this type to represent an exact moment in time at a particular location on Earth.
+
+## 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={DatePickerTests.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={DatePickerTests.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={DatePickerTests.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={DatePickerTests.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={DatePickerTests.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={DatePickerTests.ShouldSelectADateValue} type="code" dark />
+```