@simplybusiness/mobius 5.26.3 → 5.27.0

package/dist/types/src/components/DateField/DateField.d.ts

@@ -0,0 +1,13 @@
+import type { RefAttributes } from "react";
+import { type TextFieldElementType, type TextFieldProps, type TextFieldRef } from "../TextField";
+export interface DateFieldProps extends Omit<TextFieldProps, "type">, RefAttributes<TextFieldElementType> {
+    /** The earliest date allowed for the input. */
+    min?: string;
+    /** The latest date allowed for the input. */
+    max?: string;
+    /** Date format to use. */
+    format?: string;
+}
+export type DateFieldRef = TextFieldRef;
+export declare const MIN_MAX_ERROR = "\"min\" value should not be greater than \"max\" value.";
+export declare const DateField: import("react").ForwardRefExoticComponent<Omit<DateFieldProps, "ref"> & RefAttributes<HTMLInputElement>>;

package/dist/types/src/components/DateField/DateField.stories.d.ts

@@ -0,0 +1,13 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { DateField } from "./DateField";
+type StoryType = StoryObj<typeof DateField>;
+declare const meta: Meta<typeof DateField>;
+export declare const Default: StoryType;
+export declare const DefaultValue: StoryType;
+export declare const WithErrorMessage: StoryType;
+export declare const LimitedDates: StoryType;
+export declare const LimitedDatesWithCustomFormat: StoryType;
+export declare const InvalidMin: StoryType;
+export declare const InvalidMax: StoryType;
+export declare const MaxBeforeMin: StoryType;
+export default meta;

package/dist/types/src/components/DateField/DateField.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/src/components/DateField/index.d.ts

@@ -0,0 +1 @@
+export * from "./DateField";

package/dist/types/src/components/DateField/validation.d.ts

@@ -0,0 +1,2 @@
+export declare const convertToDateFormat: (date: string, format?: string) => string;
+export declare const isValidDate: (date?: string, format?: string) => boolean;

package/dist/types/src/components/DateField/validation.test.d.ts

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplybusiness/mobius",
   "license": "UNLICENSED",
-  "version": "5.26.3",
+  "version": "5.27.0",
   "description": "Core library of Mobius react components",
   "repository": {
     "type": "git",

package/src/components/DateField/DateField.mdx

@@ -0,0 +1,113 @@
+import { ArgTypes, Canvas, Meta } from "@storybook/blocks";
+import { DateField } from "./DateField";
+import * as DateFieldStories from "./DateField.stories";
+
+<Meta of={DateFieldStories} />
+
+# DateField
+
+DateField allows a user to input a Date. It includes a show/hide button on the right hand side.
+
+Dates are displayed in the user's locale format, e.g. `DD/MM/YYYY` or `MM/DD/YYYY`. The input field is a native HTML5 date input, which means it will show a date picker on supported browsers.
+
+## Install
+
+```bash
+yarn add @simplybusiness/mobius
+```
+
+## Usage
+
+```js
+import { DateField } from "@simplybusiness/mobius";
+```
+
+## Examples
+
+### Default
+
+<Canvas of={DateFieldStories.Default} />
+
+## Default value
+
+Dates are formatted internally in `yyyy-mm-dd` format. The `defaultValue` prop can be used to set the initial value of the input field. It is expected in the format `yyyy-mm-dd`; if you want to use a different format, you can use the `format` prop to specify a custom format.
+
+_NOTE: If you set a custom format, then you must use it for all other props (`defaultValue`, `min`, `max`, etc.) that expect a date. The component can only support one format._
+
+```js
+import { DateField } from "@simplybusiness/mobius";
+
+// Fixed date
+<DateField defaultValue="2023-10-01" />;
+
+// Today's date
+<DateField defaultValue={new Date().toISOString().split("T")[0]} />;
+
+// Custom date format for UK
+<DateField defaultValue="01/10/2023" format="dd/mm/yyyy" />;
+
+// Custom date format for US
+<DateField defaultValue="10/01/2023" format="mm/dd/yyyy" />;
+```
+
+<Canvas of={DateFieldStories.DefaultValue} />
+
+## Limiting input with min and max
+
+The default format for `min` and `max` props is `yyyy-mm-dd`. Min and max props can be used to limit the range of dates that can be selected. The input field will not allow dates outside of this range.
+
+It is possible to set the min and max props to a date in the future or past. The input field will not allow dates outside of this range.
+
+You can use a custom date format by passing a function to the `format` prop. The function should return a string in the format you want.
+
+<Canvas of={DateFieldStories.LimitedDates} />
+
+<Canvas of={DateFieldStories.LimitedDatesWithCustomFormat} />
+
+## Validation
+
+The `DateField` component supports validation. The `errorMessage` prop can be used to display error messages. The `isValid` prop can be used to indicate whether the input is valid or not.
+
+The component has internal validation for invalid min and max date props, along with logical checks that max > min. The `min` and `max` props should be in the default format `yyyy-mm-dd`, or match a supplied custom `format` prop, to ensure proper validation.
+
+<Canvas of={DateFieldStories.InvalidMin} />
+
+<Canvas of={DateFieldStories.InvalidMax} />
+
+<Canvas of={DateFieldStories.MaxBeforeMin} />
+
+## Controlled component
+
+The `DateField` component can be used as a controlled component. The value of the input field is controlled by the `value` prop. The `onChange` prop is used to update the value of the input field.
+
+## Accessibility
+
+It's recommended to pass a `label` prop in order to show a visual label. When the `label` prop is not provided, make sure to provide the `aria-label` prop instead. If the text field is labeled by a separate element, the `aria-labelledby` props must be used with the id of the labeling element.
+
+## Events
+
+The `onChange` prop can be used to listen to changes of the value of the input. See the prop table for the complete list of events supported.
+See the example of controlled component using the `onChange` prop.
+
+## Props
+
+<ArgTypes of={DateField} />
+
+## Component HTML Structure and Class names
+
+The following HTML is rendered for a DateField:
+
+```html
+<div class="mobius-date-field">
+  <label class="mobius-label">{label}</label>
+  <input class="mobius-text-field__input" type="date" />
+  <div class="mobius-error-message">{errors}</div>
+</div>
+```
+
+Class names are augmented with the following flags if true:
+
+- \--is-disabled
+- \--is-selected
+- \--is-valid
+- \--is-invalid

package/src/components/DateField/DateField.stories.tsx

@@ -0,0 +1,120 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { excludeControls } from "../../utils";
+import { StoryContainer } from "../../utils/StoryContainer";
+import type { DateFieldProps } from "./DateField";
+import { DateField } from "./DateField";
+
+type StoryType = StoryObj<typeof DateField>;
+
+const meta: Meta<typeof DateField> = {
+  title: "Forms/DateField",
+  component: DateField,
+  argTypes: {
+    ...excludeControls(
+      "description",
+      "validationState",
+      "type",
+      "labelElementType",
+      "inputElementType",
+    ),
+  },
+  args: {
+    isReadOnly: false,
+  },
+  decorators: [
+    Story => (
+      <StoryContainer>
+        <Story />
+      </StoryContainer>
+    ),
+  ],
+};
+
+export const Default: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Claim date",
+    isDisabled: false,
+    errorMessage: "",
+    isRequired: false,
+  },
+};
+
+export const DefaultValue: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Claim date",
+    isDisabled: false,
+    defaultValue: "2025-04-01",
+    isRequired: true,
+  },
+};
+
+export const WithErrorMessage: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Limited Dates (2025 - dd/mm/yyyy)",
+    isRequired: true,
+    min: "01/01/2025",
+    max: "31/12/2025",
+    format: "dd/mm/yyyy",
+    errorMessage: "This is a custom error message.",
+  },
+};
+
+export const LimitedDates: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Limited Dates (2025)",
+    isRequired: true,
+    min: "2025-01-01",
+    max: "2025-12-31",
+  },
+};
+
+export const LimitedDatesWithCustomFormat: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Limited Dates (2025 - dd/mm/yyyy)",
+    isRequired: true,
+    min: "01/01/2025",
+    max: "31/12/2025",
+    format: "dd/mm/yyyy",
+  },
+};
+
+export const InvalidMin: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Invalid Min Date",
+    isDisabled: false,
+    errorMessage: "",
+    isRequired: true,
+    min: "garbage",
+  },
+};
+
+export const InvalidMax: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Invalid Max Date",
+    isDisabled: false,
+    errorMessage: "",
+    isRequired: true,
+    max: "garbage",
+  },
+};
+
+export const MaxBeforeMin: StoryType = {
+  render: (args: DateFieldProps) => <DateField {...args} />,
+  args: {
+    label: "Max before Min",
+    isDisabled: false,
+    errorMessage: "",
+    isRequired: true,
+    min: "2023-01-01",
+    max: "2022-12-31",
+  },
+};
+
+export default meta;

package/src/components/DateField/DateField.test.tsx

@@ -0,0 +1,238 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import React from "react";
+import { DateField, MIN_MAX_ERROR } from "./DateField";
+
+describe("DateField", () => {
+  it("renders correctly", () => {
+    render(<DateField aria-label="date-input" data-testid="custom-test-id" />);
+    expect(screen.getByTestId("custom-test-id")).toBeInTheDocument();
+    expect(screen.getByTestId("custom-test-id")).toHaveAttribute(
+      "type",
+      "date",
+    );
+  });
+
+  it("applies data-testid to input element", () => {
+    render(<DateField aria-label="date-input" data-testid="custom-test-id" />);
+    expect(screen.getByTestId("custom-test-id")).toBeInTheDocument();
+  });
+
+  it("applies custom className", () => {
+    render(
+      <DateField
+        className="custom-class"
+        aria-label="date-input"
+        data-testid="custom-test-id"
+      />,
+    );
+    expect(screen.getByTestId("custom-test-id")).toHaveClass(
+      "mobius-date-field",
+    );
+    expect(screen.getByTestId("custom-test-id")).toHaveClass("custom-class");
+  });
+
+  it("forwards props to TextField", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        placeholder="Select date"
+        isDisabled
+        data-testid="custom-test-id"
+      />,
+    );
+    const input = screen.getByTestId("custom-test-id");
+    expect(input).toHaveAttribute("placeholder", "Select date");
+    expect(input).toBeDisabled();
+  });
+
+  it("applies min and max attributes", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        min="2023-01-01"
+        max="2023-12-31"
+        data-testid="custom-test-id"
+      />,
+    );
+    const input = screen.getByTestId("custom-test-id");
+    expect(input).toHaveAttribute("min", "2023-01-01");
+    expect(input).toHaveAttribute("max", "2023-12-31");
+  });
+
+  it("formats defaultValue when format is provided", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        defaultValue="01/15/2023"
+        format="mm/dd/yyyy"
+        data-testid="custom-test-id"
+      />,
+    );
+    const input = screen.getByTestId("custom-test-id");
+    expect(input).toHaveValue("2023-01-15");
+  });
+
+  it("shows error for invalid min date", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        min="invalid-date"
+        data-testid="custom-test-id"
+      />,
+    );
+    expect(screen.getByText(/Invalid min date/)).toBeInTheDocument();
+  });
+
+  it("shows error for invalid max date", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        max="invalid-date"
+        data-testid="custom-test-id"
+      />,
+    );
+    expect(screen.getByText(/Invalid max date/)).toBeInTheDocument();
+  });
+
+  it("shows error when min is greater than max", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        min="2023-12-31"
+        max="2023-01-01"
+        data-testid="custom-test-id"
+      />,
+    );
+    expect(screen.getByText(MIN_MAX_ERROR)).toBeInTheDocument();
+  });
+
+  it("accepts valid min and max values", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        min="2023-01-01"
+        max="2023-12-31"
+        data-testid="custom-test-id"
+      />,
+    );
+    // Should not show error messages
+    expect(screen.queryByText(/Invalid/)).not.toBeInTheDocument();
+    expect(screen.queryByText(MIN_MAX_ERROR)).not.toBeInTheDocument();
+  });
+
+  it("passes ref to the underlying input", () => {
+    const ref = React.createRef<HTMLInputElement>();
+    render(
+      <DateField
+        aria-label="date-input"
+        ref={ref}
+        data-testid="custom-test-id"
+      />,
+    );
+    expect(ref.current).not.toBeNull();
+    expect(ref.current?.tagName).toBe("INPUT");
+  });
+
+  it("uses custom errorMessage when provided", () => {
+    render(
+      <DateField
+        aria-label="date-input"
+        errorMessage="Custom error message"
+        data-testid="custom-test-id"
+      />,
+    );
+    expect(screen.getByText("Custom error message")).toBeInTheDocument();
+  });
+
+  describe("DateField validation on blur", () => {
+    it("calls onBlur handler with correct event on blur", async () => {
+      const handleChange = jest.fn();
+
+      render(
+        <DateField
+          aria-label="date-input"
+          data-testid="date-field"
+          onBlur={handleChange}
+        />,
+      );
+
+      const input = screen.getByTestId("date-field");
+      await userEvent.type(input, "2023-10-15");
+      fireEvent.blur(input);
+
+      expect(handleChange).toHaveBeenCalledTimes(1);
+
+      expect(handleChange.mock.calls[0][0].target.value).toEqual("2023-10-15");
+      expect(screen.queryByText("Invalid date input")).not.toBeInTheDocument();
+    });
+
+    it("validates against min date on blur", async () => {
+      render(
+        <DateField
+          aria-label="date-input"
+          data-testid="date-field"
+          min="2023-10-10"
+        />,
+      );
+
+      const input = screen.getByTestId("date-field");
+      await userEvent.clear(input);
+      await userEvent.type(input, "2023-10-05");
+      fireEvent.blur(input);
+
+      expect(screen.getByText("Invalid date input")).toBeInTheDocument();
+
+      // Test valid date
+      await userEvent.clear(input);
+      await userEvent.type(input, "2023-10-15");
+      fireEvent.blur(input);
+
+      expect(screen.queryByText("Invalid date input")).not.toBeInTheDocument();
+    });
+
+    it("validates against max date on blur", async () => {
+      render(
+        <DateField
+          aria-label="date-input"
+          data-testid="date-field"
+          max="2023-10-20"
+        />,
+      );
+
+      const input = screen.getByTestId("date-field");
+      await userEvent.clear(input);
+      await userEvent.type(input, "2023-10-25");
+      fireEvent.blur(input);
+
+      expect(screen.getByText("Invalid date input")).toBeInTheDocument();
+    });
+
+    it("resets validation state when valid input is provided after invalid input", async () => {
+      render(
+        <DateField
+          aria-label="date-input"
+          data-testid="date-field"
+          min="2023-01-01"
+          max="2023-12-31"
+        />,
+      );
+
+      const input = screen.getByTestId("date-field");
+
+      // Enter invalid date
+      await userEvent.clear(input);
+      await userEvent.type(input, "2024-01-15");
+      fireEvent.blur(input);
+
+      expect(screen.getByText("Invalid date input")).toBeInTheDocument();
+
+      // Enter valid date
+      await userEvent.clear(input);
+      await userEvent.type(input, "2023-06-15");
+      fireEvent.blur(input);
+
+      expect(screen.queryByText("Invalid date input")).not.toBeInTheDocument();
+    });
+  });
+});

package/src/components/DateField/DateField.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import classNames from "classnames/dedupe";
+import type { FocusEvent, RefAttributes } from "react";
+import { forwardRef, useEffect, useRef, useState } from "react";
+import { mergeRefs } from "../../utils/mergeRefs";
+import {
+  TextField,
+  type TextFieldElementType,
+  type TextFieldProps,
+  type TextFieldRef,
+} from "../TextField";
+import { convertToDateFormat, isValidDate } from "./validation";
+
+export interface DateFieldProps
+  extends Omit<TextFieldProps, "type">,
+    RefAttributes<TextFieldElementType> {
+  /** The earliest date allowed for the input. */
+  min?: string;
+  /** The latest date allowed for the input. */
+  max?: string;
+  /** Date format to use. */
+  format?: string;
+}
+
+export type DateFieldRef = TextFieldRef;
+
+export const MIN_MAX_ERROR =
+  '"min" value should not be greater than "max" value.';
+
+export const DateField = forwardRef<HTMLInputElement, DateFieldProps>(
+  (props, ref) => {
+    const {
+      min,
+      max,
+      format,
+      className,
+      errorMessage,
+      defaultValue,
+      value,
+      ...otherProps
+    } = props;
+    const [error, setError] = useState<string | undefined>(errorMessage);
+    const [isInvalid, setIsInvalid] = useState<boolean | undefined>(undefined);
+    const localRef = useRef<TextFieldElementType>(null);
+    const classes = classNames("mobius-date-field", className);
+
+    // If a custom format is provided, convert the min, max,
+    // and defaultValue dates to that format
+    const formattedMin = min ? convertToDateFormat(min, format) : undefined;
+    const formattedMax = max ? convertToDateFormat(max, format) : undefined;
+    const formattedDefaultValue = defaultValue
+      ? convertToDateFormat(defaultValue, format)
+      : undefined;
+    const formattedValue = value
+      ? convertToDateFormat(value, format)
+      : undefined;
+
+    const setInvalidState = (error?: string) => {
+      setError(error);
+      setIsInvalid(true);
+    };
+
+    const setValidState = () => {
+      setError(props.errorMessage);
+      setIsInvalid(false);
+    };
+
+    // Validate min and max values
+    useEffect(() => {
+      if (!isValidDate(min, format)) {
+        setInvalidState(`Invalid min date: ${min}`);
+        return;
+      }
+      if (!isValidDate(max, format)) {
+        setInvalidState(`Invalid max date: ${max}`);
+        return;
+      }
+
+      if (min && max) {
+        const minDate = new Date(min);
+        const maxDate = new Date(max);
+        if (minDate > maxDate) {
+          setInvalidState(MIN_MAX_ERROR);
+        } else {
+          setValidState();
+        }
+      } else {
+        setValidState();
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [min, max, format]);
+
+    const validate = () => {
+      // If 'min' or 'max' values are provided, checkValidity() will
+      // validate the date and return a boolean
+      const isValidInput = localRef.current?.checkValidity();
+
+      if (!isValidInput) {
+        setInvalidState("Invalid date input");
+      } else {
+        setValidState();
+      }
+    };
+
+    // User has interacted with the component and navigated away
+    const handleBlur = (event: FocusEvent<Element>) => {
+      validate();
+      otherProps.onBlur?.(event);
+    };
+
+    return (
+      <TextField
+        ref={mergeRefs([localRef, ref])}
+        className={classes}
+        type="date"
+        min={formattedMin}
+        max={formattedMax}
+        errorMessage={error}
+        isInvalid={isInvalid}
+        defaultValue={formattedDefaultValue}
+        value={formattedValue}
+        onBlur={handleBlur}
+        {...otherProps}
+      />
+    );
+  },
+);
+
+DateField.displayName = "DateField";

package/src/components/DateField/index.tsx

@@ -0,0 +1 @@
+export * from "./DateField";