@agregio-solutions/design-system 1.90.1 → 1.92.0

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

@@ -0,0 +1,582 @@
+# NumberField
+
+## 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/NumberField/NumberField.d.ts
+
+## Example usage
+
+Here are the Storybook Stories.
+
+Base stories:
+
+```tsx
+import { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, within } from "storybook/test";
+import NumberField from "./NumberField";
+import { STORYBOOK_VIEWPORTS } from "@internal/test-utils-storybook/test-utils-storybook";
+import { I18nProvider } from "react-aria-components";
+
+const meta: Meta<typeof NumberField> = {
+  component: NumberField,
+  argTypes: {
+    label: { control: "text" },
+    helperText: { control: "text" },
+    errorHelperText: { control: "text" },
+    successHelperText: { control: "text" },
+    warningHelperText: { control: "text" },
+    formatOptions: { control: "object" },
+  },
+  parameters: {
+    layout: "centered",
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="fr-FR">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+const getRoot = (canvasElement: HTMLElement) =>
+  canvasElement.querySelector('[data-design-system-component="NumberField"]');
+
+export const Playground: StoryObj<typeof NumberField> = {
+  args: {
+    onChange: fn(),
+    label: "[Insert label]",
+    labelIconRight: "help_outline",
+    labelIconRightTooltip: "Additional information",
+    helperText: "[Insert helper]",
+    helperTextIcon: "help_outline",
+    defaultValue: 42,
+    step: 1,
+    required: true,
+  },
+};
+
+export const Default: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("[Insert label]")).toBeInTheDocument();
+    await expect(getRoot(canvasElement)).toHaveAttribute(
+      "data-nature",
+      "default",
+    );
+  },
+};
+
+export const Disabled: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    isDisabled: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByLabelText("[Insert label]")).toBeDisabled();
+    await expect(getRoot(canvasElement)).toHaveAttribute("data-disabled");
+  },
+};
+
+export const ReadOnly: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    isReadOnly: true,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveAttribute(
+      "readonly",
+    );
+  },
+};
+
+export const WithError: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    errorHelperText: "Error message",
+    errorHelperTextIcon: "error_outline",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Error message")).toBeInTheDocument();
+    await expect(getRoot(canvasElement)).toHaveAttribute(
+      "data-nature",
+      "negative",
+    );
+  },
+};
+
+export const WithSuccess: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    successHelperText: "Success message",
+    successHelperTextIcon: "check",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Success message")).toBeInTheDocument();
+    await expect(getRoot(canvasElement)).toHaveAttribute(
+      "data-nature",
+      "positive",
+    );
+  },
+};
+
+export const WithWarning: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    helperText: undefined,
+    warningHelperText: "Warning message",
+    warningHelperTextIcon: "warning_amber",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText("Warning message")).toBeInTheDocument();
+    await expect(getRoot(canvasElement)).toHaveAttribute(
+      "data-nature",
+      "warning",
+    );
+  },
+};
+
+export const WithMinMax: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    defaultValue: 5,
+    minValue: 0,
+    maxValue: 10,
+    step: 1,
+    helperText: "Value between 0 and 10",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByLabelText("[Insert label]")).toHaveValue("5");
+  },
+};
+
+export const FormattedCurrency: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    label: "Price",
+    defaultValue: 1234.5,
+    step: 0.01,
+    formatOptions: { style: "currency", currency: "EUR" },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByLabelText("Price") as HTMLInputElement;
+    await expect(input.value).toMatch(/1[,.\s]234[,.\s]50/);
+    await expect(input.value).toMatch(/€/);
+  },
+};
+
+export const FormattedPercent: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    label: "Progress",
+    defaultValue: 0.25,
+    step: 0.01,
+    formatOptions: { style: "percent" },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByLabelText("Progress") as HTMLInputElement;
+    await expect(input.value).toMatch(/25\s?%/);
+  },
+};
+
+export const HorizontalOrientation: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    orientation: "horizontal",
+  },
+  play: async ({ canvasElement }) => {
+    const topSection = canvasElement.querySelector("[data-orientation]");
+    await expect(topSection).toHaveAttribute("data-orientation", "horizontal");
+  },
+};
+
+export const Mobile: StoryObj<typeof NumberField> = {
+  parameters: {
+    ...STORYBOOK_VIEWPORTS,
+  },
+  globals: {
+    viewport: { value: "iphone6", isRotated: false },
+  },
+  args: {
+    ...Playground.args,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(
+      canvas.getByRole("button", { name: "Diminuer : [Insert label]" }),
+    ).toBeVisible();
+    await expect(
+      canvas.getByRole("button", { name: "Augmenter : [Insert label]" }),
+    ).toBeVisible();
+  },
+};
+
+export const DisplayOnly: StoryObj<typeof NumberField> = {
+  args: {
+    ...Playground.args,
+    isDisplayOnly: true,
+    value: 1234.56,
+    formatOptions: { style: "currency", currency: "EUR" },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText(/1\s?234,56\s?€/)).toBeVisible();
+    await expect(canvas.queryByRole("textbox")).not.toBeInTheDocument();
+    await expect(canvas.queryByRole("spinbutton")).not.toBeInTheDocument();
+    await expect(
+      canvas.queryByRole("button", { name: /Augmenter/i }),
+    ).not.toBeInTheDocument();
+    await expect(
+      canvas.queryByRole("button", { name: /Diminuer/i }),
+    ).not.toBeInTheDocument();
+  },
+};
+
+export const FullWidth: StoryObj<typeof NumberField> = {
+  parameters: {
+    layout: "padded",
+  },
+  args: {
+    ...Playground.args,
+    fullWidth: true,
+  },
+  play: async ({ canvasElement }) => {
+    await expect(getRoot(canvasElement)).toHaveAttribute(
+      "data-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 { userEvent, within, expect, fn } from "storybook/test";
+import { I18nProvider } from "react-aria-components";
+import { useState } from "react";
+import NumberField from "../NumberField";
+
+const meta: Meta<typeof NumberField> = {
+  component: NumberField,
+  argTypes: {
+    label: { control: "text" },
+  },
+  parameters: {
+    layout: "centered",
+    chromatic: { disableSnapshot: true },
+  },
+  decorators: [
+    (Story) => (
+      <I18nProvider locale="en-US">
+        <Story />
+      </I18nProvider>
+    ),
+  ],
+};
+export default meta;
+
+const baseArgs = {
+  label: "Amount",
+  id: "number-field-test",
+  onChange: fn(),
+};
+
+export const ShouldTypeAValue: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    const input = canvas.getByLabelText("Amount");
+    await user.type(input, "42");
+    await expect(input).toHaveValue("42");
+    // React Aria NumberField commits the value on blur.
+    await user.tab();
+    await expect(args.onChange).toHaveBeenLastCalledWith(42);
+  },
+};
+
+export const ShouldIncrementViaButton: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 10,
+    step: 1,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    const increment = canvas.getByRole("button", {
+      name: "Increment : Amount",
+    });
+    await user.click(increment);
+    await expect(args.onChange).toHaveBeenLastCalledWith(11);
+  },
+};
+
+export const ShouldDecrementViaButton: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 10,
+    step: 1,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    const decrement = canvas.getByRole("button", {
+      name: "Decrement : Amount",
+    });
+    await user.click(decrement);
+    await expect(args.onChange).toHaveBeenLastCalledWith(9);
+  },
+};
+
+export const ShouldIncrementViaKeyboard: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 5,
+    step: 1,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    const input = canvas.getByLabelText("Amount");
+    await user.click(input);
+    await user.keyboard("{ArrowUp}");
+    await expect(args.onChange).toHaveBeenLastCalledWith(6);
+    await user.keyboard("{ArrowDown}");
+    await expect(args.onChange).toHaveBeenLastCalledWith(5);
+  },
+};
+
+export const ShouldRespectMinValue: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 0,
+    minValue: 0,
+    maxValue: 10,
+    step: 1,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const decrement = canvas.getByRole("button", {
+      name: "Decrement : Amount",
+    });
+    await expect(decrement).toBeDisabled();
+  },
+};
+
+export const ShouldRespectMaxValue: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 10,
+    minValue: 0,
+    maxValue: 10,
+    step: 1,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const increment = canvas.getByRole("button", {
+      name: "Increment : Amount",
+    });
+    await expect(increment).toBeDisabled();
+  },
+};
+
+export const ShouldNotChangeWhenDisabled: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 5,
+    isDisabled: true,
+  },
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    const input = canvas.getByLabelText("Amount");
+    await user.type(input, "9");
+    await expect(args.onChange).not.toHaveBeenCalled();
+  },
+};
+
+export const ShouldFormatCurrency: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 1234.5,
+    formatOptions: { style: "currency", currency: "EUR" },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const input = canvas.getByLabelText("Amount") as HTMLInputElement;
+    await expect(input.value).toMatch(/€1,234\.50/);
+  },
+};
+
+export const ShouldExposeNegativeNatureOnError: StoryObj<typeof NumberField> = {
+  args: {
+    ...baseArgs,
+    errorHelperText: "Invalid value",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const root = canvasElement.querySelector(
+      '[data-design-system-component="NumberField"]',
+    );
+    await expect(root).toHaveAttribute("data-nature", "negative");
+    await expect(canvas.getByText("Invalid value")).toBeInTheDocument();
+  },
+};
+
+export const ExampleControlled: StoryObj<typeof NumberField> = {
+  render: () => {
+    const Wrapper = () => {
+      const [value, setValue] = useState<number>(0);
+      return (
+        <>
+          <div>Value is: {value}</div>
+          <NumberField label="Controlled" value={value} onChange={setValue} />
+        </>
+      );
+    };
+    return <Wrapper />;
+  },
+};
+
+export const ControlledShouldReflectValue: StoryObj<typeof NumberField> = {
+  render: ExampleControlled.render,
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    await canvas.findByText("Value is: 0");
+    const increment = canvas.getByRole("button", {
+      name: "Increment : Controlled",
+    });
+    await user.click(increment);
+    await canvas.findByText("Value is: 1");
+  },
+};
+
+export const UncontrolledShouldUpdateInternalValue: StoryObj<
+  typeof NumberField
+> = {
+  args: {
+    ...baseArgs,
+    defaultValue: 10,
+    step: 1,
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const user = userEvent.setup({ delay: 50 });
+    const input = canvas.getByLabelText("Amount") as HTMLInputElement;
+    await expect(input).toHaveValue("10");
+    const increment = canvas.getByRole("button", {
+      name: "Increment : Amount",
+    });
+    await user.click(increment);
+    await expect(input).toHaveValue("11");
+  },
+};
+```
+
+## 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 NumberField from "./NumberField.stories";
+import * as NumberFieldTests from "./tests/NumberField.stories";
+
+<Meta of={NumberField} />
+
+# NumberField
+
+A NumberField allows users to enter a number, and increment or decrement the value using stepper buttons or the keyboard.
+
+<Canvas of={NumberField.Playground} />
+<Controls of={NumberField.Playground} />
+
+A number field can be built using `<input type="number">`, but this is very limited in functionality, lacking in internationalization capabilities, inconsistent between browsers, and difficult to style.
+NumberField helps achieve accessible and international number fields that can be styled as needed.
+
+- **International** – Supports locale-aware formatting, number systems, currencies, units, and right-to-left layouts via `formatOptions`.
+- **Accessible** – Exposed as a spinbutton to assistive technologies, with labelled increment/decrement buttons and full keyboard support (Arrow keys, Page Up/Down, Home/End).
+- **Touch friendly** – Dedicated mobile stepper buttons are rendered on small viewports for easier one-hand usage.
+- **Validated** – Values can be clamped to a `minValue`/`maxValue` range and snapped to a `step`.
+
+Read [the React Aria NumberField docs](https://react-aria.adobe.com/NumberField.html) for more details about the internationalization, accessibility, and user experience features implemented under the hood.
+
+## Value
+
+A `NumberField` accepts a plain JavaScript `number`. An initial, uncontrolled value can be provided via `defaultValue`, or a controlled value via `value` together with `onChange`.
+
+<Canvas of={NumberFieldTests.ExampleControlled} sourceState="shown" />
+
+## Minimum and maximum
+
+The `minValue` and `maxValue` props clamp the allowed range. When the current value reaches a bound, the corresponding stepper button is disabled.
+
+<Canvas of={NumberField.WithMinMax} sourceState="shown" />
+
+## Step
+
+The `step` prop controls the amount added or subtracted on each increment/decrement tick (buttons or keyboard). It also defines the snapping grid when `commitBehavior="snap"`.
+
+## Formatting
+
+`formatOptions` follows the standard [`Intl.NumberFormat` options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options). It controls both the displayed value and which characters are allowed during typing.
+
+A currency field:
+
+<Canvas of={NumberField.FormattedCurrency} sourceState="shown" />
+
+A percentage field (values are expressed as decimals, e.g. `0.25` renders as `25 %`):
+
+<Canvas of={NumberField.FormattedPercent} sourceState="shown" />
+
+Locale is resolved via the surrounding `I18nProvider`. Wrap your app (or your story) with the locale you want (`fr-FR`, `en-US`, ...) to switch decimal separators, grouping, and currency symbols.
+
+## Advanced React Aria options
+
+Most common configuration is exposed as top-level props. For less common React Aria options, pass them through `advancedReactAriaOptions`. See the [React Aria NumberField API](https://react-aria.adobe.com/NumberField.html#numberfield) for the full list.
+
+## How to test this component
+
+The input rendered by NumberField is a real `<input>` (with `role="spinbutton"`) and can be targeted by its label:
+
+<Source of={NumberFieldTests.ShouldTypeAValue} type="code" dark />
+
+The stepper buttons are labelled using the field's label for screen readers. Target them by their accessible name (the label for increment/decrement depends on the locale — `Increment` / `Decrement` in English, `Augmenter` / `Diminuer` in French):
+
+<Source of={NumberFieldTests.ShouldIncrementViaButton} type="code" dark />
+
+Note that React Aria commits the typed value on blur, so remember to `tab()` out of the field before asserting on `onChange` calls.
+
+<Stories includePrimary={false} />
+```