@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,353 @@
+# TimeField
+
+## 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/TimeField/TimeField.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import TimeField from "./TimeField";
+import { I18nProvider } from "react-aria-components";
+import { fn } from "storybook/test";
+
+const meta: Meta<typeof TimeField> = {
+  component: TimeField,
+  argTypes: {
+    label: { control: "text" },
+    value: { control: false },
+    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 TimeField> = {
+  args: {
+    label: "Time Field",
+    id: "time-field",
+    defaultValue: "12:34:56",
+    onChange: fn(),
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+  },
+};
+
+export const Empty: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    defaultValue: undefined,
+  },
+};
+
+export const OnlyHour: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "12",
+    granularity: "hour",
+  },
+};
+
+export const HourMinute: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "12:34",
+    granularity: "minute",
+  },
+};
+
+export const HourMinuteSecond: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "12:34:56",
+    granularity: "second",
+  },
+};
+
+export const LocaleFR: StoryObj<typeof TimeField> = {
+  parameters: {
+    locale: "fr-FR",
+  },
+  args: {
+    ...HourMinuteSecond.args,
+  },
+};
+
+export const Disabled: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+};
+
+export const WithError: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    errorHelperText: "Error message",
+    errorHelperTextIcon: "error_outline",
+  },
+};
+
+export const WithSuccess: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    successHelperText: "Success message",
+    successHelperTextIcon: "check",
+  },
+};
+
+export const WithWarning: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    warningHelperText: "Warning message",
+    warningHelperTextIcon: "warning_amber",
+  },
+};
+
+export const WithHorizontalOrientation: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    orientation: "horizontal",
+  },
+};
+
+export const FullWidth: StoryObj<typeof TimeField> = {
+  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 TimeField from "../TimeField";
+import { userEvent, within, expect, fn } from "storybook/test";
+import { I18nProvider } from "react-aria-components";
+import { useState } from "react";
+import { Playground } from "../TimeField.stories";
+
+const meta: Meta<typeof TimeField> = {
+  component: TimeField,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en-EN">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+export const ShouldSelectAValue: StoryObj<typeof TimeField> = {
+  args: {
+    ...Playground.args,
+    defaultValue: "12:34",
+    onChange: fn(),
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await expect(canvas.getByLabelText("hour, Time Field")).toHaveTextContent(
+      "12",
+    );
+    await expect(canvas.getByLabelText("minute, Time Field")).toHaveTextContent(
+      "34",
+    );
+
+    await user.type(canvas.getByLabelText("hour, Time Field"), "11");
+    await expect(canvas.getByLabelText("hour, Time Field")).toHaveTextContent(
+      "11",
+    );
+    await user.type(canvas.getByLabelText("minute, Time Field"), "59");
+    await expect(canvas.getByLabelText("minute, Time Field")).toHaveTextContent(
+      "59",
+    );
+    await user.type(canvas.getByLabelText("AM/PM, Time Field"), "A");
+
+    await expect(args.onChange).toHaveBeenCalledWith("11:59:00");
+  },
+};
+
+export const ExampleControlled: StoryObj<typeof TimeField> = {
+  render: () => {
+    const ParentComponent = () => {
+      const [value, setValue] = useState("12:34");
+
+      return (
+        <>
+          <div>Selected time : {value}</div>
+          <TimeField
+            value={value}
+            onChange={setValue}
+            id="example-controlled time field"
+            label="Time Field"
+          />
+        </>
+      );
+    };
+    return <ParentComponent />;
+  },
+};
+
+export const ControlledShouldSelectAValue: StoryObj<typeof TimeField> = {
+  render: ExampleControlled.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Selected time : 12:34");
+    await user.type(canvas.getByLabelText("hour, Time Field"), "11");
+    await user.type(canvas.getByLabelText("minute, Time Field"), "59");
+    await user.type(canvas.getByLabelText("AM/PM, Time Field"), "A");
+    await canvas.findByText("Selected time : 11:59:00");
+  },
+};
+
+export const ExampleGranularity: StoryObj<typeof TimeField> = {
+  render: () => {
+    function Example() {
+      const [time, setDate] = useState("12:34");
+
+      return (
+        <>
+          <TimeField
+            id="time-and-time"
+            label="Date and time"
+            granularity="second"
+            value={time}
+            onChange={setDate}
+          />
+          <TimeField
+            id="time"
+            label="Date"
+            granularity="hour"
+            value={time}
+            onChange={setDate}
+          />
+        </>
+      );
+    }
+    return <Example />;
+  },
+};
+
+export const ExampleGranularity2: StoryObj<typeof TimeField> = {
+  render: () => {
+    function Example() {
+      return (
+        <>
+          <TimeField id="second" label="Event time" granularity="second" />
+          <TimeField id="hour" label="Event time" granularity="hour" />
+        </>
+      );
+    }
+    return <Example />;
+  },
+};
+```
+
+## 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 TimeField from "./TimeField.stories";
+import * as TimeFieldTests from "./tests/TimeField.stories";
+
+<Meta of={TimeField} />
+
+# TimeField
+
+A time field allows users to enter and edit time values using a keyboard. Each part of a time value is displayed in an individually editable segment.
+
+<Canvas of={TimeField.Playground} />
+<Controls of={TimeField.Playground} />
+
+## Example
+
+<Source of={TimeFieldTests.ExampleControlled} type="code" dark />
+
+A time field can be built using `<input type="time">`, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style.
+TimeField helps achieve accessible and international time fields that can be styled as needed.
+
+- **International** – Support for locale-specific formatting, number systems, hour cycles, and right-to-left layout.
+- **Accessible** – Each time unit is displayed as an individually focusable and editable segment, which allows users an easy way to edit times using the keyboard, in any format and locale.
+- **Touch friendly** – Time 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 TimeField.
+
+## Value
+
+A `TimeField` displays a placeholder by default. An initial, uncontrolled value can be provided to the `TimeField` using the `defaultValue` prop.
+Alternatively, a controlled value can be provided using the `value` and `onchange` props.
+
+Time values are provided as string.
+This component handles correct international time manipulation across time zones and other localization concerns.
+TimeField supports values of the following string formats:
+
+- `hh` -> only the hour is displayed
+- `hh:mm` -> only the hour and minute are displayed
+- `hh:mm:ss` -> only the hour, minute and second are displayed
+- `hh:mm:ss.sss` -> the hour, minute, second and millisecond are displayed (millisecond are not selectable by the user and will not change when the rest of the time is changed)
+
+## Granularity
+
+The granularity prop allows you to control the smallest unit that is displayed by TimeField. By default, times are displayed with "minute" granularity.
+More granular time values can be displayed by setting the granularity prop to "second".
+
+<Canvas of={TimeFieldTests.ExampleGranularity} sourceState="shown" />
+
+## How to test this component
+
+The fields to type the hours/minute/seconds are not real inputs, but you can still fill them with `userEvent.type` as well.
+Just inspect the rendered HTML and you will see that every targetable element has a dedicated aria-label that you can target with `getByLabelText`.
+
+Here is a complete example of one of our tests using Storybook and Testing Library:
+
+<Source of={TimeFieldTests.ShouldSelectAValue} type="code" dark />
+```