feat(NumberField): support custom units

Add a `unit` prop for units Intl.NumberFormat does not support (e.g. MiB,
GiB). React-aria's number parser rejects unknown text in the input value, so
the unit is drawn as an overlay right behind the number and the value stays a
plain number. The input's name references the unit ("Storage MiB"), matching
the current convention of writing such units into the label.

Closes #2579

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: Lisa18289

apps/docs/src/content/components/form-controls/number-field/examples/customUnit.tsx

@@ -0,0 +1,8 @@
+import {
+  Label,
+  NumberField,
+} from "@mittwald/flow-react-components";
+
+<NumberField unit="MiB" defaultValue={512}>
+  <Label>Arbeitsspeicher</Label>
+</NumberField>;

apps/docs/src/content/components/form-controls/number-field/index.mdx

@@ -27,6 +27,18 @@ definieren (s.
 
 <LiveCodeEditor example="unit" editorCollapsed stretch />
 
+## Eigene Einheit
+
+Kennt `Intl.NumberFormat` die Einheit nicht (etwa `MiB` oder `GiB`), übergib sie
+als Text über das Property `unit`. Das NumberField zeigt sie hinter der Zahl an;
+der Wert bleibt eine reine Zahl.
+
+- Nutze `unit` nur, wenn `formatOptions` die Einheit nicht abdeckt –
+  `formatOptions` lokalisiert Einheit und Schreibweise automatisch.
+- Übersetze die Einheit selbst, wenn sie sprachabhängig ist.
+
+<LiveCodeEditor example="customUnit" editorCollapsed stretch />
+
 ---
 
 # Validierung

apps/remote-dom-demo/src/app/remote/simple-form/page.tsx

@@ -14,6 +14,7 @@ import {
   Checkbox,
   Button,
   Autocomplete,
+  NumberField,
 } from "@mittwald/flow-remote-react-components";
 import { useState } from "react";
 
@@ -70,6 +71,9 @@ export default function Page() {
             Hoth
           </Option>
         </Select>
+        <NumberField name="memory" unit="MiB" defaultValue={512}>
+          <Label>Droid memory</Label>
+        </NumberField>
         <FileField multiple name="certificates">
           <Label>Holocrons</Label>
           <Button variant="outline" color="secondary">

packages/components/src/components/NumberField/NumberField.browser.test.tsx

@@ -3,6 +3,7 @@ import { page, userEvent } from "vitest/browser";
 import { expect, test, vi } from "vitest";
 import { NumberField } from "@/components/NumberField";
 import { Label } from "@/components/Label";
+import { FieldDescription } from "@/components/FieldDescription";
 
 // react-aria labels the stepper buttons after the field.
 const increase = () => page.getByRole("button", { name: "Increase Age" });
@@ -96,3 +97,60 @@ test("a disabled number field cannot be stepped", async () => {
   await expect.element(input()).toHaveValue("5");
   expect(onChange).not.toHaveBeenCalled();
 });
+
+/*
+ * React-aria cannot parse a unit Intl.NumberFormat does not know, so a custom
+ * unit stays out of the input value. The field's name carries it instead, like
+ * a unit written into the label.
+ */
+test("a custom unit is shown behind the number and named with the field", async () => {
+  const onChange = vi.fn();
+  await render(
+    <NumberField unit="MiB" defaultValue={512} onChange={onChange}>
+      <Label>Age</Label>
+      <FieldDescription>Per project</FieldDescription>
+    </NumberField>,
+  );
+
+  const field = page.getByRole("textbox", {
+    name: "Age (optional) MiB",
+    exact: true,
+  });
+
+  await expect.element(page.getByText("MiB")).toBeVisible();
+  await expect.element(field).toHaveValue("512");
+  await expect.element(field).toHaveAccessibleDescription("Per project");
+
+  await userEvent.fill(field, "1024");
+  await userEvent.tab();
+
+  expect(onChange).toHaveBeenLastCalledWith(1024);
+});
+
+test("a custom unit is hidden but named while the field is empty", async () => {
+  await render(
+    <NumberField unit="MiB">
+      <Label>Age</Label>
+    </NumberField>,
+  );
+
+  const field = page.getByRole("textbox", {
+    name: "Age (optional) MiB",
+    exact: true,
+  });
+
+  await expect.element(page.getByText("MiB")).not.toBeVisible();
+  await expect.element(field).toBeInTheDocument();
+
+  await userEvent.fill(field, "3");
+
+  await expect.element(page.getByText("MiB")).toBeVisible();
+});
+
+test("a custom unit extends an aria-label", async () => {
+  await render(<NumberField unit="MiB" aria-label="Age" />);
+
+  await expect
+    .element(page.getByRole("textbox", { name: "Age MiB", exact: true }))
+    .toBeInTheDocument();
+});

packages/components/src/components/NumberField/NumberField.module.d.scss.ts

@@ -1,7 +1,10 @@
 declare const classNames: {
   readonly group: "group";
+  readonly inputContainer: "inputContainer";
   readonly input: "input";
+  readonly unitOverlay: "unitOverlay";
   readonly readonly: "readonly";
+  readonly unitSpacer: "unitSpacer";
   readonly decrementButton: "decrementButton";
   readonly incrementButton: "incrementButton";
   readonly coarsePointerIcon: "coarsePointerIcon";

packages/components/src/components/NumberField/NumberField.module.scss

@@ -8,12 +8,48 @@
     "input increment"
     "input decrement";
 
-  .input {
+  .inputContainer {
     grid-area: input;
+    display: grid;
+    min-width: 0;
+  }
+
+  .input,
+  .unitOverlay {
+    grid-area: 1 / 1;
+  }
 
+  .input {
     @include formControl.formControl();
   }
 
+  // Mirrors the input's box so the text lines up with the input text
+  .unitOverlay {
+    @include formControl.formBorder();
+    @include formControl.formOutline();
+
+    // Grid items paint in `order`; formControl moves the input to 2
+    order: 2;
+    border-color: transparent;
+    color: var(--form-control--content-color--default);
+    white-space: pre;
+    overflow: hidden;
+    pointer-events: none;
+    contain: inline-size;
+
+    &[data-empty] {
+      visibility: hidden;
+    }
+  }
+
+  .unitSpacer {
+    visibility: hidden;
+  }
+
+  &[aria-disabled="true"] .unitOverlay {
+    color: var(--form-control--content-color--disabled);
+  }
+
   .decrementButton {
     grid-area: decrement;
   }

packages/components/src/components/NumberField/NumberField.tsx

@@ -1,4 +1,4 @@
-import { type PropsWithChildren } from "react";
+import { type PropsWithChildren, useId } from "react";
 import * as Aria from "react-aria-components";
 import formFieldStyles from "@/components/FormField/FormField.module.scss";
 import styles from "./NumberField.module.scss";
@@ -15,11 +15,18 @@ import type { FlowComponentProps } from "@/lib/componentFactory/flowComponent";
 import { flowComponent } from "@/lib/componentFactory/flowComponent";
 import { useFieldComponent } from "@/lib/hooks/useFieldComponent";
 import { useControlledHostValueProps } from "@/lib/remote/useControlledHostValueProps";
+import { NumberFieldUnit } from "./components/NumberFieldUnit";
 
 export interface NumberFieldProps
   extends
     PropsWithChildren<Omit<Aria.NumberFieldProps, "children">>,
-    FlowComponentProps<HTMLInputElement> {}
+    FlowComponentProps<HTMLInputElement> {
+  /**
+   * A unit displayed after the number, for units `Intl.NumberFormat` does not
+   * support (e.g. "MiB"). For supported units, use `formatOptions` instead.
+   */
+  unit?: string;
+}
 
 /** @flr-generate all */
 export const NumberField = flowComponent("NumberField", (props) => {
@@ -29,9 +36,13 @@ export const NumberField = flowComponent("NumberField", (props) => {
     className,
     isWheelDisabled = true,
     ref,
+    unit,
+    "aria-labelledby": ariaLabelledBy,
     ...rest
   } = useControlledHostValueProps(props, NaN);
 
+  const unitId = useId();
+
   const {
     FieldErrorView,
     FieldErrorCaptureContext,
@@ -46,6 +57,11 @@ export const NumberField = flowComponent("NumberField", (props) => {
     <Aria.NumberField
       {...rest}
       isWheelDisabled={isWheelDisabled}
+      aria-labelledby={
+        unit
+          ? [ariaLabelledBy, unitId].filter(Boolean).join(" ")
+          : ariaLabelledBy
+      }
       aria-describedby={controlProps["aria-describedby"]}
       className={clsx(rootClassName, wrapperProps.className)}
     >
@@ -64,7 +80,10 @@ export const NumberField = flowComponent("NumberField", (props) => {
           <IconChevronDown />
           <IconMinus className={styles.coarsePointerIcon} />
         </Button>
-        <Aria.Input className={styles.input} ref={ref} />
+        <div className={styles.inputContainer}>
+          <Aria.Input className={styles.input} ref={ref} />
+          {unit && <NumberFieldUnit id={unitId} unit={unit} />}
+        </div>
         <Button
           ariaSlot="increment"
           className={styles.incrementButton}

packages/components/src/components/NumberField/components/NumberFieldUnit.tsx

@@ -0,0 +1,30 @@
+import { type FC, useContext } from "react";
+import * as Aria from "react-aria-components";
+import styles from "../NumberField.module.scss";
+
+interface Props {
+  id: string;
+  unit: string;
+}
+
+/**
+ * React-aria cannot parse a unit `Intl.NumberFormat` does not know, so the unit
+ * is drawn over the input instead of being part of its value. An invisible copy
+ * of the input text pushes it right behind the number. The input's name
+ * references the unit, like a unit written into the label.
+ */
+export const NumberFieldUnit: FC<Props> = (props) => {
+  const { id, unit } = props;
+  const inputValue = useContext(Aria.NumberFieldStateContext)?.inputValue;
+
+  return (
+    <span
+      className={styles.unitOverlay}
+      data-empty={!inputValue || undefined}
+      aria-hidden
+    >
+      <span className={styles.unitSpacer}>{inputValue} </span>
+      <span id={id}>{unit}</span>
+    </span>
+  );
+};

packages/components/src/components/NumberField/stories/Default.stories.tsx

@@ -73,6 +73,14 @@ export const WithUnit: Story = {
   ),
 };
 
+export const WithCustomUnit: Story = {
+  render: (props) => (
+    <NumberField {...props} unit="MiB" defaultValue={512}>
+      <Label>Storage</Label>
+    </NumberField>
+  ),
+};
+
 export const WithContextualHelp: Story = {
   render: (props) => (
     <NumberField {...props} minValue={5} maxValue={10}>

packages/remote-elements/src/auto-generated/RemoteNumberFieldElement.ts

@@ -39,6 +39,7 @@ export class RemoteNumberFieldElement extends FlowRemoteElement<RemoteNumberFiel
       slot: {},
       step: {},
       translate: {},
+      unit: {},
       validate: {},
       validationBehavior: {},
       value: {},