Skip to content

The open alternative to Salesforce, designed for AI.

Share NumberStepper across settings (#27028)

Raphaël Bosi60cd0989cd89
diff --git a/packages/twenty-docs/docs.json b/packages/twenty-docs/docs.json
index 9b3127f968c..c4a26407170 100644
--- a/packages/twenty-docs/docs.json
+++ b/packages/twenty-docs/docs.json
@@ -568,6 +568,7 @@
"ui/primitives/input/field",
"ui/primitives/input/input",
"ui/primitives/input/input-group",
+ "ui/primitives/input/number-stepper",
"ui/primitives/input/textarea",
"ui/primitives/input/checkbox",
"ui/primitives/input/radio",
diff --git a/packages/twenty-docs/navigation/base-structure.json b/packages/twenty-docs/navigation/base-structure.json
index a0fcdcdcb74..7418dcab95a 100644
--- a/packages/twenty-docs/navigation/base-structure.json
+++ b/packages/twenty-docs/navigation/base-structure.json
@@ -581,6 +581,7 @@
"ui/primitives/input/field",
"ui/primitives/input/input",
"ui/primitives/input/input-group",
+ "ui/primitives/input/number-stepper",
"ui/primitives/input/textarea",
"ui/primitives/input/checkbox",
"ui/primitives/input/radio",
diff --git a/packages/twenty-docs/snippets/ui/generated/input/number-stepper.mdx b/packages/twenty-docs/snippets/ui/generated/input/number-stepper.mdx
new file mode 100644
index 00000000000..fd69abe81cf
--- /dev/null
+++ b/packages/twenty-docs/snippets/ui/generated/input/number-stepper.mdx
@@ -0,0 +1,100 @@
+{/*
+ * _____ _
+ *|_ _|_ _____ _ __ | |_ _ _
+ * | | \ \ /\ / / _ \ '_ \| __| | | | Auto-generated file
+ * | | \ V V / __/ | | | |_| |_| | DO NOT EDIT - changes will be overwritten
+ * |_| \_/\_/ \___|_| |_|\__|\__, | Generated by: npx nx generate:ui twenty-docs
+ * |___/
+ *
+ * This file is generated from the documentation data in packages/twenty-ui/generated.
+ * To update it, edit the component prop types or design tokens in twenty-ui and run:
+ * npx nx generate:ui twenty-docs
+ */}
+
+<ParamField body="allowOutOfRange" type="boolean" default="false">
+ Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.
+</ParamField>
+
+<ParamField body="aria-roledescription" type="string" default="Number field">
+ A user-friendly description of the input's role for assistive tech. This is a role
+ description, not an accessible name — use `Field.Label` or `aria-label` to name the control.
+</ParamField>
+
+<ParamField body="className" type="string | ((state: NumberFieldInputState) =&gt; string | undefined)">
+ Class applied to the visible input.
+</ParamField>
+
+<ParamField body="decrementLabel" type="string" default="Decrease value">
+ Accessible name for the decrement button.
+</ParamField>
+
+<ParamField body="defaultValue" type="number">
+ Initial number when the field owns its value.
+</ParamField>
+
+<ParamField body="disabled" type="boolean" default="false">
+ Disables the input and both buttons, and omits the form value.
+</ParamField>
+
+<ParamField body="form" type="string">
+ ID of the form that owns the submitted numeric value.
+</ParamField>
+
+<ParamField body="id" type="string">
+ ID of the visible input. Generated when omitted.
+</ParamField>
+
+<ParamField body="incrementLabel" type="string" default="Increase value">
+ Accessible name for the increment button.
+</ParamField>
+
+<ParamField body="max" type="number">
+ Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
+</ParamField>
+
+<ParamField body="min" type="number">
+ Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.
+</ParamField>
+
+<ParamField body="name" type="string">
+ Name of the numeric value submitted with a form.
+</ParamField>
+
+<ParamField body="onValueChange" type="((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) =&gt; void)">
+ Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number.
+</ParamField>
+
+<ParamField body="readOnly" type="boolean" default="false">
+ Prevents numeric changes while keeping the input focusable.
+</ParamField>
+
+<ParamField body="ref" type="Ref&lt;HTMLInputElement&gt;">
+ Ref to the visible input element.
+</ParamField>
+
+<ParamField body="render" type="ReactElement&lt;unknown, string | JSXElementConstructor&lt;any&gt;&gt; | ComponentRenderFn&lt;DetailedHTMLProps&lt;InputHTMLAttributes&lt;HTMLInputElement&gt;, HTMLInputElement&gt;, NumberFieldInputState&gt;">
+ Allows you to replace the component's HTML element
+ with a different tag, or compose it with another component.
+
+ Accepts a `ReactElement` or a function that returns the element to render.
+</ParamField>
+
+<ParamField body="required" type="boolean" default="false">
+ Requires a numeric value for native form submission.
+</ParamField>
+
+<ParamField body="showButtons" type="boolean" default="true">
+ Shows the decrement and increment buttons.
+</ParamField>
+
+<ParamField body="step" type="number" default="1">
+ Amount added or subtracted by the buttons and arrow keys.
+</ParamField>
+
+<ParamField body="style" type="CSSProperties | ((state: NumberFieldInputState) =&gt; CSSProperties | undefined)">
+ Inline styles applied to the visible input.
+</ParamField>
+
+<ParamField body="value" type="number | null">
+ Controlled numeric value. Use null for an empty field.
+</ParamField>
diff --git a/packages/twenty-docs/ui/primitives/input/number-stepper.mdx b/packages/twenty-docs/ui/primitives/input/number-stepper.mdx
new file mode 100644
index 00000000000..9eaf494d45d
--- /dev/null
+++ b/packages/twenty-docs/ui/primitives/input/number-stepper.mdx
@@ -0,0 +1,95 @@
+---
+title: NumberStepper
+description: Edit a number with optional bounds and increment or decrement buttons.
+---
+
+import { StoryEmbed } from '/snippets/ui/StoryEmbed.mdx';
+import NumberStepperReference from '/snippets/ui/generated/input/number-stepper.mdx';
+
+`NumberStepper` combines a compact numeric text field with decrement and increment buttons. It owns numeric editing, bounds, and step interactions. Your application chooses the limits and handles persistence.
+
+<StoryEmbed
+ storyId="ui-input-numberstepper--default"
+ title="NumberStepper example"
+ height={180}
+/>
+
+## Uncontrolled value
+
+Use `defaultValue` to set the initial quantity. The input owns subsequent changes.
+
+```tsx
+import { Field, NumberStepper } from 'twenty-ui/primitives/input';
+
+export const QuantityInput = () => (
+ <Field.Root>
+ <Field.Label>Quantity</Field.Label>
+ <NumberStepper name="quantity" defaultValue={3} min={0} max={10} step={1} />
+ <Field.Description>Choose up to ten items.</Field.Description>
+ </Field.Root>
+);
+```
+
+## Controlled value
+
+Pass a number or `null` through `value` and update it in `onValueChange` to own the same quantity in React state. The callback receives the next numeric value and event details.
+
+```tsx
+import { useState } from 'react';
+import { Field, NumberStepper } from 'twenty-ui/primitives/input';
+
+export const QuantityInput = () => {
+ const [quantity, setQuantity] = useState<number | null>(3);
+
+ return (
+ <Field.Root>
+ <Field.Label>Quantity</Field.Label>
+ <NumberStepper
+ name="quantity"
+ value={quantity}
+ onValueChange={setQuantity}
+ min={0}
+ max={10}
+ step={1}
+ />
+ <Field.Description>Choose up to ten items.</Field.Description>
+ </Field.Root>
+ );
+};
+```
+
+Clearing the field reports `null`. Incomplete text such as `-` or `+` remains editable without reporting an invalid number until it is replaced or stepped. By default, parseable numeric edits report the bounded value; the displayed draft is normalized on blur. Values equal to the current value do not call `onValueChange` again.
+
+## Application validation
+
+Set `allowOutOfRange` when the application needs the parsed value before applying its own limits or validation. `onValueChange` then receives typed and pasted numbers outside the range. Uncontrolled fields, or controlled fields that accept those values, preserve them on blur. Controlled fields that reject them return to their accepted value on blur. For example, replacing `60` with `45` reports `4` and then `45`, even when `min={30}`. The application can ignore the intermediate value without accidentally saving the minimum.
+
+Buttons and keyboard adjustments still stop at `min` and `max`. Native form validation prevents submission while an accepted value is outside that range. `allowOutOfRange` defaults to `false`.
+
+## Bounds and interaction
+
+`min` and `max` are inclusive. Increment and decrement buttons stop at the matching bound. Arrow Up and Arrow Down adjust the focused input by `step`, which defaults to `1`. Home and End select the corresponding bound when provided; call `event.preventBaseUIHandler()` in `onKeyDown` to keep a key's text editing behavior instead. The same step applies when Shift or Alt is held. Displayed values support up to 15 fraction digits; use a positive step within that precision for decimal adjustments.
+
+Values use Latin digits and show grouping separators from five integer digits, such as `12,500`. Typed and pasted group separators of the browser's locale are accepted.
+
+`step` controls adjustments; it does not round typed values to a step. When `min` is set, native form validation also requires `min` plus a multiple of `step`: with the default `step` of `1`, a typed `2.5` blocks submission. Set `showButtons={false}` for text editing with the same keyboard behavior.
+
+Each button has a default accessible name. Use `decrementLabel` and `incrementLabel` to provide contextual or translated names. Give the input a visible `Field.Label`, `aria-label`, or `aria-labelledby`.
+
+## Forms and focus
+
+Use `name` to include the numeric value in a form. `form` associates it with a form elsewhere in the document. The adjustment buttons use `type="button"`, so adjusting a value does not submit the form. `required` participates in native validation.
+
+Use a controlled `value` when your application needs to reset the field. A native form reset does not reset the numeric state.
+
+`disabled` prevents changes and excludes the value from form submission. `readOnly` prevents changes while keeping the input focusable and its value available to the form.
+
+Native input attributes and handlers, `className`, `style`, and `ref` apply to the visible input. For example, call `ref.current?.focus()` to focus the field. Combine the input with `Field.Description` and `Field.Error` for guidance and validation messages.
+
+## Front component renderer
+
+The React and Preact renderer sandboxes support keyboard adjustments, bounds, and form values. Pointer stepping and text editing are currently blocked by missing input selection and native event support in the renderer. Pasting is not supported: without input selection, the pasted text is inserted around the whole value, that wrong number is reported, and the front component then stops rendering. These limitations do not affect normal React rendering.
+
+## Props
+
+<NumberStepperReference />
diff --git a/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx b/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx
index d6571a3c831..1384b33b35d 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx
+++ b/packages/twenty-front-component-renderer/src/__stories__/TwentyUiGallery.stories.tsx
@@ -5,6 +5,8 @@ import { inlineBannerSandboxTest } from '@/__stories__/twenty-ui-gallery/utils/i
import { themeTokenTest } from '@/__stories__/twenty-ui-gallery/utils/themeTokenTest';
import { progressTest } from '@/__stories__/twenty-ui-gallery/utils/progressTest';
import { inputTest } from '@/__stories__/twenty-ui-gallery/utils/inputTest';
+import { numberStepperTest } from '@/__stories__/twenty-ui-gallery/utils/numberStepperTest';
+import { numberStepperSandboxFailureTest } from '@/__stories__/twenty-ui-gallery/utils/numberStepperSandboxFailureTest';
import { settingsRowTest } from '@/__stories__/twenty-ui-gallery/utils/settingsRowTest';
import { resizeHandleTest } from '@/__stories__/twenty-ui-gallery/utils/resizeHandleTest';
import { createListItemSandboxFailureTest } from '@/__stories__/twenty-ui-gallery/utils/createListItemSandboxFailureTest';
@@ -127,6 +129,30 @@ export const InputPreact: Story = createGalleryStory({
play: inputTest,
});
+export const NumberStepperReact: Story = createGalleryStory({
+ frontComponentBundleName: 'twenty-ui-number-stepper',
+ runtime: 'react',
+ play: numberStepperTest,
+});
+
+export const NumberStepperPreact: Story = createGalleryStory({
+ frontComponentBundleName: 'twenty-ui-number-stepper',
+ runtime: 'preact',
+ play: numberStepperTest,
+});
+
+export const NumberStepperInteractionGapsReact: Story = createGalleryStory({
+ frontComponentBundleName: 'twenty-ui-number-stepper',
+ runtime: 'react',
+ play: numberStepperSandboxFailureTest,
+});
+
+export const NumberStepperInteractionGapsPreact: Story = createGalleryStory({
+ frontComponentBundleName: 'twenty-ui-number-stepper',
+ runtime: 'preact',
+ play: numberStepperSandboxFailureTest,
+});
+
export const JsonVisualizerReact: Story = createGalleryStory({
frontComponentBundleName: 'twenty-ui-json-visualizer-gallery',
runtime: 'react',
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md
index 694e6a97e60..77f29b2c633 100644
--- a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/README.md
@@ -16,6 +16,7 @@ requiring them to occur.
| Fixture | Components |
| --- | --- |
| `twenty-ui-field-controls` | Field, Input, InputGroup, Textarea |
+| `twenty-ui-number-stepper` | NumberStepper (keyboard bounds, disabled/read-only state, named form values and submission) |
| `twenty-ui-display-helpers` | Text |
| `twenty-ui-image-input` | ImageInput |
| `twenty-ui-list-item` | ListItem |
@@ -52,6 +53,7 @@ No stories are skipped or marked as expected-to-fail by the runner.
| Component | Current limitation |
| --- | --- |
| Field controls | Forwarded events lack the `nativeEvent` Base UI reads for `composedPath`. Textarea's cloned render element loses its change handler in React. The value report checks the state received by the component after typing. |
+| NumberStepper | Pointer stepping fails because the worker input does not implement `setSelectionRange`. Text editing fails because forwarded events lack the `nativeEvent.defaultPrevented` Base UI reads. Pasting is not covered: without `selectionStart`/`selectionEnd`, Base UI inserts the pasted text around the whole value and reports that number, then its caret restore throws from a layout effect, which unmounts the React tree and stops Preact rendering. Separate React and Preact stories assert the pointer and typing gaps and successful keyboard bounds, disabled/read-only state, named form values and submission. |
| ImageInput | Native file picker activation and usable file contents are unavailable in the sandbox. The fixture checks forwarded file metadata, preview recovery, action callbacks, and supplied error changes. See the [ImageInput documentation](../../../../twenty-docs/ui/components/image-input.mdx). |
| Tabs | Activation fails on the missing `nativeEvent` for `composedPath` in both runtimes. |
| Popover, Dialog, AlertDialog | Opening fails while reading pointer contact data from the missing `nativeEvent`. |
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-number-stepper.front-component.tsx b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-number-stepper.front-component.tsx
new file mode 100644
index 00000000000..25772ed5469
--- /dev/null
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/twenty-ui-number-stepper.front-component.tsx
@@ -0,0 +1,68 @@
+import { useState } from 'react';
+import { defineFrontComponent } from 'twenty-sdk/define';
+import { Button, Field, NumberStepper } from 'twenty-ui/primitives/input';
+import { Text } from 'twenty-ui/primitives/typography';
+
+import { TwentyUiGalleryCard } from '@/__stories__/shared/front-components/twenty-ui-gallery-card';
+
+const NumberStepperExample = () => {
+ const [value, setValue] = useState<number | null>(3);
+ const [changes, setChanges] = useState(0);
+ const [submissions, setSubmissions] = useState(0);
+
+ return (
+ <TwentyUiGalleryCard title="NumberStepper">
+ <form
+ aria-label="Quantity form"
+ onSubmit={(event) => {
+ event.preventDefault();
+ setSubmissions((count) => count + 1);
+ }}
+ >
+ <Field.Root>
+ <Field.Label>Quantity</Field.Label>
+ <NumberStepper
+ name="quantity"
+ min={0}
+ max={5}
+ value={value}
+ onValueChange={(nextValue) => {
+ setValue(nextValue);
+ setChanges((count) => count + 1);
+ }}
+ />
+ <Field.Description>Choose up to five items</Field.Description>
+ </Field.Root>
+ <NumberStepper
+ aria-label="Disabled quantity"
+ name="disabledQuantity"
+ defaultValue={2}
+ disabled
+ decrementLabel="Decrease disabled quantity"
+ incrementLabel="Increase disabled quantity"
+ onValueChange={() => setChanges((count) => count + 1)}
+ />
+ <NumberStepper
+ aria-label="Read-only quantity"
+ name="readOnlyQuantity"
+ defaultValue={4}
+ readOnly
+ showButtons={false}
+ onValueChange={() => setChanges((count) => count + 1)}
+ />
+ <Button type="submit">Save quantity</Button>
+ <Text role="status">
+ Value: {value ?? 'empty'}; Changes: {changes}; Submissions:{' '}
+ {submissions}
+ </Text>
+ </form>
+ </TwentyUiGalleryCard>
+ );
+};
+
+export default defineFrontComponent({
+ universalIdentifier: 'f8132b7b-34ae-428b-bf60-029c7e36924d',
+ name: 'twenty-ui-number-stepper',
+ description: 'Numeric editing, bounds and form behavior in the sandbox',
+ component: NumberStepperExample,
+});
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/numberStepperSandboxFailureTest.ts b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/numberStepperSandboxFailureTest.ts
new file mode 100644
index 00000000000..f9d9c2cbb5a
--- /dev/null
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/numberStepperSandboxFailureTest.ts
@@ -0,0 +1,31 @@
+import { expect, userEvent, within } from 'storybook/test';
+
+import { expectFrontComponentMounted } from '@/__stories__/shared/test-utils/matchers/expectFrontComponentMounted';
+import { SANDBOX_ERROR_PATTERNS } from '@/__stories__/twenty-ui-gallery/constants/SANDBOX_ERROR_PATTERNS';
+import { type TwentyUiGalleryPlayFunction } from '@/__stories__/twenty-ui-gallery/types/TwentyUiGalleryPlayFunction';
+import { expectSandboxErrors } from '@/__stories__/twenty-ui-gallery/utils/expectSandboxErrors';
+
+const MISSING_SELECTION_RANGE_ERROR =
+ /^Uncaught TypeError: .+\.setSelectionRange is not a function$/;
+
+export const numberStepperSandboxFailureTest: TwentyUiGalleryPlayFunction =
+ async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ await expectFrontComponentMounted(canvas);
+
+ const status = canvas.getByRole('status');
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Increase value' }),
+ );
+ await expectSandboxErrors({
+ requiredErrors: [MISSING_SELECTION_RANGE_ERROR],
+ });
+ expect(status).toHaveTextContent('Value: 3; Changes: 0; Submissions: 0');
+
+ await userEvent.clear(canvas.getByRole('textbox', { name: 'Quantity' }));
+ await expectSandboxErrors({
+ requiredErrors: [SANDBOX_ERROR_PATTERNS.NATIVE_EVENT_DEFAULT_PREVENTED],
+ allowedAdditionalErrors: [MISSING_SELECTION_RANGE_ERROR],
+ });
+ expect(status).toHaveTextContent('Value: 3; Changes: 0; Submissions: 0');
+ };
diff --git a/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/numberStepperTest.ts b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/numberStepperTest.ts
new file mode 100644
index 00000000000..7b2f685e755
--- /dev/null
+++ b/packages/twenty-front-component-renderer/src/__stories__/twenty-ui-gallery/utils/numberStepperTest.ts
@@ -0,0 +1,71 @@
+import { expect, userEvent, waitFor, within } from 'storybook/test';
+
+import { errorHandler } from '@/__stories__/shared/test-utils/createFrontComponentStoryMeta';
+import { expectFrontComponentMounted } from '@/__stories__/shared/test-utils/matchers/expectFrontComponentMounted';
+import { type TwentyUiGalleryPlayFunction } from '@/__stories__/twenty-ui-gallery/types/TwentyUiGalleryPlayFunction';
+
+export const numberStepperTest: TwentyUiGalleryPlayFunction = async ({
+ canvasElement,
+}) => {
+ const canvas = within(canvasElement);
+ await expectFrontComponentMounted(canvas);
+
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+ const increment = canvas.getByRole('button', { name: 'Increase value' });
+ const decrement = canvas.getByRole('button', { name: 'Decrease value' });
+ const status = canvas.getByRole('status');
+
+ expect(input).toHaveValue('3');
+ expect(input).toHaveAccessibleDescription('Choose up to five items');
+ expect(increment).toHaveAttribute('type', 'button');
+ expect(decrement).toHaveAttribute('type', 'button');
+ expect(
+ canvas.getByRole('textbox', { name: 'Disabled quantity' }),
+ ).toBeDisabled();
+
+ const readOnlyInput = canvas.getByRole('textbox', {
+ name: 'Read-only quantity',
+ });
+ expect(readOnlyInput).toHaveAttribute('readonly');
+ await userEvent.type(readOnlyInput, '9');
+ await userEvent.keyboard('{ArrowUp}');
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Increase disabled quantity' }),
+ );
+ expect(readOnlyInput).toHaveValue('4');
+ expect(status).toHaveTextContent('Value: 3; Changes: 0; Submissions: 0');
+
+ await userEvent.click(input);
+ await waitFor(() => expect(input).toHaveFocus());
+ await userEvent.keyboard('{ArrowDown}');
+ await waitFor(() =>
+ expect(status).toHaveTextContent('Value: 2; Changes: 1; Submissions: 0'),
+ );
+ await userEvent.keyboard('{Home}');
+ await waitFor(() => expect(decrement).toBeDisabled());
+ await userEvent.keyboard('{ArrowDown}');
+ await expect(status).toHaveTextContent(
+ 'Value: 0; Changes: 2; Submissions: 0',
+ );
+ await userEvent.keyboard('{End}');
+ await waitFor(() =>
+ expect(status).toHaveTextContent('Value: 5; Changes: 3; Submissions: 0'),
+ );
+ expect(increment).toBeDisabled();
+ await userEvent.keyboard('{ArrowDown}');
+ await waitFor(() =>
+ expect(status).toHaveTextContent('Value: 4; Changes: 4; Submissions: 0'),
+ );
+
+ const form = canvas.getByRole('form', { name: 'Quantity form' });
+ expect(form).toBeInstanceOf(HTMLFormElement);
+ const formData = new FormData(form as HTMLFormElement);
+ expect(formData.get('quantity')).toBe('4');
+ expect(formData.get('readOnlyQuantity')).toBe('4');
+ expect(formData.has('disabledQuantity')).toBe(false);
+ await userEvent.click(canvas.getByRole('button', { name: 'Save quantity' }));
+ await waitFor(() =>
+ expect(status).toHaveTextContent('Value: 4; Changes: 4; Submissions: 1'),
+ );
+ expect(errorHandler).not.toHaveBeenCalled();
+};
diff --git a/packages/twenty-front/src/modules/settings/components/SettingsCounter.tsx b/packages/twenty-front/src/modules/settings/components/SettingsCounter.tsx
index 8083ce0b5d8..f91b6a68c53 100644
--- a/packages/twenty-front/src/modules/settings/components/SettingsCounter.tsx
+++ b/packages/twenty-front/src/modules/settings/components/SettingsCounter.tsx
@@ -1,10 +1,22 @@
-import { t } from '@lingui/core/macro';
-import { SettingsTextInput } from '@/ui/input/components/SettingsTextInput';
+import { usePushFocusItemToFocusStack } from '@/ui/utilities/focus/hooks/usePushFocusItemToFocusStack';
+import { useRemoveFocusItemFromFocusStackById } from '@/ui/utilities/focus/hooks/useRemoveFocusItemFromFocusStackById';
+import { FocusComponentType } from '@/ui/utilities/focus/types/FocusComponentType';
+import { useHotkeysOnFocusedElement } from '@/ui/utilities/hotkey/hooks/useHotkeysOnFocusedElement';
import { styled } from '@linaria/react';
-import { IconMinus, IconPlus } from 'twenty-ui/icon';
-import { IconButton } from 'twenty-ui/components';
+import { t } from '@lingui/core/macro';
+import { isInteger, isNonEmptyString } from '@sniptt/guards';
+import { useId, useRef } from 'react';
+import { Key } from 'ts-key-enum';
+import { isDefined } from 'twenty-shared/utils';
+import {
+ NumberStepper,
+ type NumberStepperProps,
+} from 'twenty-ui/primitives/input';
import { themeCssVariables } from 'twenty-ui/theme';
-import { castAsNumberOrNull } from '~/utils/cast-as-number-or-null';
+
+const SETTINGS_COUNTER_CARET_NAVIGATION_KEYS: string[] = [Key.Home, Key.End];
+
+const SETTINGS_COUNTER_SEPARATOR_AND_PLUS_SIGN_KEYS = ['.', ',', '+'];
type SettingsCounterProps = {
value: number;
@@ -13,12 +25,13 @@ type SettingsCounterProps = {
maxValue?: number;
disabled?: boolean;
showButtons?: boolean;
+ 'aria-labelledby': string;
+ 'aria-describedby'?: string;
};
const StyledCounterContainer = styled.div<{ showButtons: boolean }>`
align-items: center;
display: flex;
- gap: ${themeCssVariables.spacing[1]};
margin-left: auto;
width: ${({ showButtons }) =>
showButtons
@@ -26,17 +39,6 @@ const StyledCounterContainer = styled.div<{ showButtons: boolean }>`
: themeCssVariables.spacing[16]};
`;
-const StyledTextInputContainer = styled.div`
- width: ${themeCssVariables.spacing[16]};
-
- > * input {
- font-weight: ${themeCssVariables.font.weight.medium};
- height: ${themeCssVariables.spacing[6]};
- text-align: center;
- width: ${themeCssVariables.spacing[16]};
- }
-`;
-
export const SettingsCounter = ({
value,
onChange,
@@ -44,71 +46,114 @@ export const SettingsCounter = ({
maxValue,
disabled = false,
showButtons = true,
+ 'aria-labelledby': ariaLabelledBy,
+ 'aria-describedby': ariaDescribedBy,
}: SettingsCounterProps) => {
- const handleIncrementCounter = () => {
- if (maxValue === undefined || value < maxValue) {
- onChange(value + 1);
+ const instanceId = useId();
+ const inputRef = useRef<HTMLInputElement>(null);
+ const { pushFocusItemToFocusStack } = usePushFocusItemToFocusStack();
+ const { removeFocusItemFromFocusStackById } =
+ useRemoveFocusItemFromFocusStackById();
+
+ const handleFocus = () => {
+ pushFocusItemToFocusStack({
+ focusId: instanceId,
+ component: {
+ type: FocusComponentType.TEXT_INPUT,
+ instanceId,
+ },
+ globalHotkeysConfig: {
+ enableGlobalHotkeysConflictingWithKeyboard: false,
+ },
+ });
+ };
+
+ const handleBlur: NonNullable<NumberStepperProps['onBlur']> = (event) => {
+ removeFocusItemFromFocusStackById({ focusId: instanceId });
+
+ const isFieldLeftEmpty = !isNonEmptyString(
+ event.currentTarget.value.trim(),
+ );
+
+ if (isFieldLeftEmpty && value !== minValue) {
+ onChange(minValue);
}
};
- const handleDecrementCounter = () => {
- if (value > minValue) {
- onChange(value - 1);
+ const handleKeyDown: NonNullable<NumberStepperProps['onKeyDown']> = (
+ event,
+ ) => {
+ if (SETTINGS_COUNTER_CARET_NAVIGATION_KEYS.includes(event.key)) {
+ event.preventBaseUIHandler();
+ return;
+ }
+
+ const isBlockedMinusSign = event.key === '-' && minValue >= 0;
+ const isSeparatorOrPlusSign =
+ SETTINGS_COUNTER_SEPARATOR_AND_PLUS_SIGN_KEYS.includes(event.key);
+
+ if (isBlockedMinusSign || isSeparatorOrPlusSign) {
+ event.preventDefault();
}
};
- const handleTextInputChange = (value: string) => {
- const castedNumber = castAsNumberOrNull(value);
- if (castedNumber === null) {
- onChange(minValue);
+ const handleEscape = () => {
+ inputRef.current?.blur();
+ };
+
+ useHotkeysOnFocusedElement({
+ keys: [Key.Escape],
+ callback: handleEscape,
+ focusId: instanceId,
+ dependencies: [handleEscape],
+ options: {
+ preventDefault: false,
+ },
+ });
+
+ const handleValueChange = (nextValue: number | null) => {
+ if (!isDefined(nextValue)) {
return;
}
- if (castedNumber < minValue) {
+ const isPersistableValue = isInteger(nextValue) && nextValue >= minValue;
+
+ if (!isPersistableValue) {
return;
}
- if (maxValue !== undefined && castedNumber > maxValue) {
- onChange(maxValue);
+ const nextSettingsValue = Math.min(
+ nextValue,
+ maxValue ?? Number.POSITIVE_INFINITY,
+ );
+
+ if (nextSettingsValue === value) {
return;
}
- onChange(castedNumber);
+
+ onChange(nextSettingsValue);
};
return (
<StyledCounterContainer showButtons={showButtons}>
- {showButtons && (
- <IconButton
- aria-label={t`Decrease value`}
- size="sm"
- variant="outline"
- onClick={handleDecrementCounter}
- disabled={disabled}
- >
- <IconMinus />
- </IconButton>
- )}
- <StyledTextInputContainer>
- <SettingsTextInput
- instanceId="settings-counter-input"
- name="counter"
- fullWidth
- value={value.toString()}
- onChange={handleTextInputChange}
- disabled={disabled}
- />
- </StyledTextInputContainer>
- {showButtons && (
- <IconButton
- aria-label={t`Increase value`}
- size="sm"
- variant="outline"
- onClick={handleIncrementCounter}
- disabled={disabled}
- >
- <IconPlus />
- </IconButton>
- )}
+ <NumberStepper
+ ref={inputRef}
+ aria-labelledby={ariaLabelledBy}
+ aria-describedby={ariaDescribedBy}
+ aria-roledescription={t`Number field`}
+ value={value}
+ onValueChange={handleValueChange}
+ allowOutOfRange
+ min={minValue}
+ max={maxValue}
+ disabled={disabled}
+ showButtons={showButtons}
+ decrementLabel={t`Decrease value`}
+ incrementLabel={t`Increase value`}
+ onFocus={handleFocus}
+ onBlur={handleBlur}
+ onKeyDown={handleKeyDown}
+ />
</StyledCounterContainer>
);
};
diff --git a/packages/twenty-front/src/modules/settings/components/SettingsOptions/SettingsOptionCardContentCounter.tsx b/packages/twenty-front/src/modules/settings/components/SettingsOptions/SettingsOptionCardContentCounter.tsx
index 81e2ec5299c..4a191a0699c 100644
--- a/packages/twenty-front/src/modules/settings/components/SettingsOptions/SettingsOptionCardContentCounter.tsx
+++ b/packages/twenty-front/src/modules/settings/components/SettingsOptions/SettingsOptionCardContentCounter.tsx
@@ -7,6 +7,8 @@ import {
StyledSettingsCardTitle,
} from '@/settings/components/SettingsOptions/SettingsCardContentBase';
import { SettingsOptionIconCustomizer } from '@/settings/components/SettingsOptions/SettingsOptionIconCustomizer';
+import { isNonEmptyString } from '@sniptt/guards';
+import { useId } from 'react';
import { OverflowingTextWithTooltip } from 'twenty-ui/primitives/typography';
import { type IconComponent } from 'twenty-ui/icon';
@@ -33,6 +35,10 @@ export const SettingsOptionCardContentCounter = ({
maxValue,
showButtons = true,
}: SettingsOptionCardContentCounterProps) => {
+ const titleId = useId();
+ const descriptionId = useId();
+ const hasDescription = isNonEmptyString(description);
+
return (
<StyledSettingsCardContent disabled={disabled}>
{Icon && (
@@ -41,14 +47,16 @@ export const SettingsOptionCardContentCounter = ({
</StyledSettingsCardIcon>
)}
<StyledSettingsCardTextContainer>
- <StyledSettingsCardTitle>{title}</StyledSettingsCardTitle>
- {description && (
- <StyledSettingsCardDescription>
+ <StyledSettingsCardTitle id={titleId}>{title}</StyledSettingsCardTitle>
+ {hasDescription && (
+ <StyledSettingsCardDescription id={descriptionId}>
<OverflowingTextWithTooltip text={description} />
</StyledSettingsCardDescription>
)}
</StyledSettingsCardTextContainer>
<SettingsCounter
+ aria-labelledby={titleId}
+ aria-describedby={hasDescription ? descriptionId : undefined}
value={value}
onChange={onChange}
minValue={minValue}
diff --git a/packages/twenty-front/src/modules/settings/components/__tests__/SettingsCounter.test.tsx b/packages/twenty-front/src/modules/settings/components/__tests__/SettingsCounter.test.tsx
new file mode 100644
index 00000000000..85d7bd55153
--- /dev/null
+++ b/packages/twenty-front/src/modules/settings/components/__tests__/SettingsCounter.test.tsx
@@ -0,0 +1,312 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { createStore, Provider as JotaiProvider } from 'jotai';
+import { useState } from 'react';
+
+import { SettingsOptionCardContentCounter } from '@/settings/components/SettingsOptions/SettingsOptionCardContentCounter';
+import { focusStackState } from '@/ui/utilities/focus/states/focusStackState';
+import { FocusComponentType } from '@/ui/utilities/focus/types/FocusComponentType';
+
+const RetentionCounter = ({
+ onChange,
+ showButtons = false,
+}: {
+ onChange: (value: number) => void;
+ showButtons?: boolean;
+}) => {
+ const [value, setValue] = useState(90);
+
+ return (
+ <SettingsOptionCardContentCounter
+ title="Log retention"
+ description="Number of days to retain audit logs"
+ value={value}
+ onChange={(nextValue) => {
+ onChange(nextValue);
+ setValue(nextValue);
+ }}
+ minValue={30}
+ maxValue={1095}
+ showButtons={showButtons}
+ />
+ );
+};
+
+it('associates settings copy and persists the minimum once a cleared field loses focus', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ expect(input).toHaveAccessibleDescription(
+ 'Number of days to retain audit logs',
+ );
+
+ await user.clear(input);
+
+ expect(input).toHaveValue('');
+ expect(onChange).not.toHaveBeenCalled();
+
+ await user.tab();
+
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange).toHaveBeenCalledWith(30);
+ expect(input).toHaveValue('30');
+});
+
+it('keeps Home and End as caret navigation without persisting a bound', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.click(input);
+ await user.keyboard('{Home}1{End}');
+
+ expect(input).toHaveValue('190');
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange).toHaveBeenCalledWith(190);
+});
+
+it('accepts only whole numbers when typing or pasting', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.tripleClick(input);
+ await user.keyboard('-+1,0.00');
+
+ expect(input).toHaveValue('1000');
+ expect(onChange).toHaveBeenCalledTimes(2);
+ expect(onChange).toHaveBeenLastCalledWith(1000);
+
+ await user.tripleClick(input);
+ await user.paste('45.5');
+ await user.tab();
+
+ expect(input).toHaveValue('1000');
+ expect(onChange).toHaveBeenCalledTimes(2);
+});
+
+it('persists a single change when stepping from a below-minimum draft', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} showButtons />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.tripleClick(input);
+ await user.keyboard('4');
+ await user.click(screen.getByRole('button', { name: 'Increase value' }));
+
+ expect(input).toHaveValue('30');
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange).toHaveBeenCalledWith(30);
+});
+
+it('ignores below-minimum drafts and persists valid retention edits immediately', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.tripleClick(input);
+ await user.keyboard('6');
+
+ expect(input).toHaveValue('6');
+ expect(onChange).not.toHaveBeenCalled();
+
+ await user.keyboard('0');
+
+ expect(input).toHaveValue('60');
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange).toHaveBeenCalledWith(60);
+
+ await user.tab();
+
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange).toHaveBeenCalledWith(60);
+ expect(input).toHaveValue('60');
+});
+
+it('restores the saved value when a below-minimum draft loses focus', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.tripleClick(input);
+ await user.keyboard('4');
+ await user.tab();
+
+ expect(input).toHaveValue('90');
+ expect(onChange).not.toHaveBeenCalled();
+});
+
+it('clamps a pasted retention value to the maximum exactly once', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.tripleClick(input);
+ await user.paste('2000');
+
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange).toHaveBeenCalledWith(1095);
+
+ await user.tab();
+
+ expect(input).toHaveValue('1095');
+ expect(onChange).toHaveBeenCalledTimes(1);
+});
+
+it('persists each pointer and keyboard adjustment once', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <RetentionCounter onChange={onChange} showButtons />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.click(screen.getByRole('button', { name: 'Increase value' }));
+
+ expect(input).toHaveValue('91');
+ expect(onChange).toHaveBeenCalledTimes(1);
+ expect(onChange).toHaveBeenLastCalledWith(91);
+
+ await user.click(input);
+ await user.keyboard('{ArrowDown}');
+ await user.tab();
+
+ expect(input).toHaveValue('90');
+ expect(onChange).toHaveBeenCalledTimes(2);
+ expect(onChange).toHaveBeenLastCalledWith(90);
+});
+
+it('restores an already saved minimum without persisting another change', async () => {
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={createStore()}>
+ <SettingsOptionCardContentCounter
+ title="Log retention"
+ value={30}
+ onChange={onChange}
+ minValue={30}
+ maxValue={1095}
+ showButtons={false}
+ />
+ </JotaiProvider>,
+ );
+
+ const input = screen.getByRole('textbox', { name: 'Log retention' });
+
+ await user.clear(input);
+ await user.tab();
+
+ expect(input).toHaveValue('30');
+ expect(onChange).not.toHaveBeenCalled();
+});
+
+it('isolates input focus and restores global hotkeys when Escape blurs it', async () => {
+ const store = createStore();
+ const onChange = jest.fn();
+ const user = userEvent.setup();
+
+ render(
+ <JotaiProvider store={store}>
+ <SettingsOptionCardContentCounter
+ title="Timeout"
+ value={45}
+ onChange={onChange}
+ minValue={1}
+ maxValue={900}
+ showButtons={false}
+ />
+ <SettingsOptionCardContentCounter
+ title="Maximum values"
+ value={3}
+ onChange={onChange}
+ minValue={1}
+ showButtons={false}
+ />
+ </JotaiProvider>,
+ );
+
+ const timeoutInput = screen.getByRole('textbox', { name: 'Timeout' });
+ const maximumValuesInput = screen.getByRole('textbox', {
+ name: 'Maximum values',
+ });
+
+ await user.click(timeoutInput);
+
+ const timeoutFocusItem = store.get(focusStackState.atom).at(-1);
+
+ expect(timeoutFocusItem).toMatchObject({
+ componentInstance: { componentType: FocusComponentType.TEXT_INPUT },
+ globalHotkeysConfig: {
+ enableGlobalHotkeysConflictingWithKeyboard: false,
+ },
+ });
+
+ await user.click(maximumValuesInput);
+
+ expect(store.get(focusStackState.atom)).toHaveLength(1);
+ expect(store.get(focusStackState.atom).at(-1)?.focusId).not.toBe(
+ timeoutFocusItem?.focusId,
+ );
+
+ await user.keyboard('{Escape}');
+
+ expect(maximumValuesInput).not.toHaveFocus();
+ expect(store.get(focusStackState.atom)).toHaveLength(0);
+ expect(onChange).not.toHaveBeenCalled();
+});
diff --git a/packages/twenty-shared/src/constants/DocumentationPaths.ts b/packages/twenty-shared/src/constants/DocumentationPaths.ts
index d338c77ab83..fc64933d564 100644
--- a/packages/twenty-shared/src/constants/DocumentationPaths.ts
+++ b/packages/twenty-shared/src/constants/DocumentationPaths.ts
@@ -176,6 +176,7 @@ export const DOCUMENTATION_PATHS = {
UI_PRIMITIVES_INPUT_FIELD: '/ui/primitives/input/field',
UI_PRIMITIVES_INPUT_INPUT: '/ui/primitives/input/input',
UI_PRIMITIVES_INPUT_INPUT_GROUP: '/ui/primitives/input/input-group',
+ UI_PRIMITIVES_INPUT_NUMBER_STEPPER: '/ui/primitives/input/number-stepper',
UI_PRIMITIVES_INPUT_RADIO: '/ui/primitives/input/radio',
UI_PRIMITIVES_INPUT_RADIO_GROUP: '/ui/primitives/input/radio-group',
UI_PRIMITIVES_INPUT_SEGMENTED_CONTROL:
diff --git a/packages/twenty-ui/docs/components.ts b/packages/twenty-ui/docs/components.ts
index 887e2b0870d..d75a65c48a6 100644
--- a/packages/twenty-ui/docs/components.ts
+++ b/packages/twenty-ui/docs/components.ts
@@ -11,6 +11,7 @@ import { TOAST_PROVIDER_PROP_DESCRIPTIONS } from './toastProviderPropDescription
import { TOASTER_PROP_DESCRIPTIONS } from './toasterPropDescriptions';
import { RADIO_PROP_DESCRIPTIONS } from './radioPropDescriptions';
import { SEARCH_INPUT_PROP_DESCRIPTIONS } from './searchInputPropDescriptions';
+import { NUMBER_STEPPER_PROP_DESCRIPTIONS } from './numberStepperPropDescriptions';
import { IMAGE_INPUT_PROP_DESCRIPTIONS } from './imageInputPropDescriptions';
import { ANIMATED_ICON_CROSSFADE_PROP_DESCRIPTIONS } from './animatedIconCrossfadePropDescriptions';
import { MENU_ITEM_PROP_DESCRIPTIONS } from './menuItemPropDescriptions';
@@ -246,6 +247,13 @@ export const DOCUMENTED_COMPONENTS = [
entryPoint: 'twenty-ui/primitives/input',
slug: 'input/input-group',
},
+ {
+ name: 'NumberStepper',
+ source: 'primitives/input/NumberStepper/NumberStepper.tsx',
+ entryPoint: 'twenty-ui/primitives/input',
+ slug: 'input/number-stepper',
+ propDescriptions: NUMBER_STEPPER_PROP_DESCRIPTIONS,
+ },
{
name: 'Textarea',
source: 'primitives/input/Textarea/Textarea.tsx',
diff --git a/packages/twenty-ui/docs/module-ownership.json b/packages/twenty-ui/docs/module-ownership.json
index 8b4fc6e16d4..f7fb0770280 100644
--- a/packages/twenty-ui/docs/module-ownership.json
+++ b/packages/twenty-ui/docs/module-ownership.json
@@ -20,6 +20,7 @@
"ListItem",
"Loader",
"Menu",
+ "NumberStepper",
"OverflowingTextWithTooltip",
"Pill",
"Popover",
diff --git a/packages/twenty-ui/docs/numberStepperPropDescriptions.ts b/packages/twenty-ui/docs/numberStepperPropDescriptions.ts
new file mode 100644
index 00000000000..b9fb39b302e
--- /dev/null
+++ b/packages/twenty-ui/docs/numberStepperPropDescriptions.ts
@@ -0,0 +1,27 @@
+import { type ComponentProps } from 'react';
+
+import { type NumberStepper } from '../src/primitives/input/NumberStepper/NumberStepper';
+
+export const NUMBER_STEPPER_PROP_DESCRIPTIONS = {
+ value: 'Controlled numeric value. Use null for an empty field.',
+ defaultValue: 'Initial number when the field owns its value.',
+ onValueChange:
+ 'Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number.',
+ allowOutOfRange:
+ 'Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.',
+ min: 'Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.',
+ max: 'Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.',
+ step: 'Amount added or subtracted by the buttons and arrow keys.',
+ showButtons: 'Shows the decrement and increment buttons.',
+ decrementLabel: 'Accessible name for the decrement button.',
+ incrementLabel: 'Accessible name for the increment button.',
+ disabled: 'Disables the input and both buttons, and omits the form value.',
+ readOnly: 'Prevents numeric changes while keeping the input focusable.',
+ required: 'Requires a numeric value for native form submission.',
+ name: 'Name of the numeric value submitted with a form.',
+ form: 'ID of the form that owns the submitted numeric value.',
+ id: 'ID of the visible input. Generated when omitted.',
+ ref: 'Ref to the visible input element.',
+ className: 'Class applied to the visible input.',
+ style: 'Inline styles applied to the visible input.',
+} satisfies Partial<Record<keyof ComponentProps<typeof NumberStepper>, string>>;
diff --git a/packages/twenty-ui/docs/public-exports.json b/packages/twenty-ui/docs/public-exports.json
index f3963da4c7f..f48f8bcb8ba 100644
--- a/packages/twenty-ui/docs/public-exports.json
+++ b/packages/twenty-ui/docs/public-exports.json
@@ -693,6 +693,7 @@
"Field": "primitives/input/Field/Field",
"Input": "primitives/input/Input/Input",
"InputGroup": "primitives/input/InputGroup/InputGroup",
+ "NumberStepper": "primitives/input/NumberStepper/NumberStepper",
"Radio": "primitives/input/Radio/Radio",
"RadioGroup": "primitives/input/RadioGroup/RadioGroup",
"SegmentedControl": "primitives/input/SegmentedControl/SegmentedControl",
@@ -715,6 +716,7 @@
"InputGroupProps": "primitives/input/InputGroup/types/InputGroupProps",
"InputProps": "primitives/input/Input/types/InputProps",
"InputSize": "primitives/input/types/InputSize",
+ "NumberStepperProps": "primitives/input/NumberStepper/types/NumberStepperProps",
"RadioGroupProps": "primitives/input/RadioGroup/types/RadioGroupProps",
"RadioProps": "primitives/input/Radio/types/RadioProps",
"SegmentedControlOption": "primitives/input/SegmentedControl/types/SegmentedControlOption",
diff --git a/packages/twenty-ui/generated/components.docs.json b/packages/twenty-ui/generated/components.docs.json
index 2b5b507c491..9b7f8d064cc 100644
--- a/packages/twenty-ui/generated/components.docs.json
+++ b/packages/twenty-ui/generated/components.docs.json
@@ -1773,6 +1773,160 @@
}
]
},
+ {
+ "name": "NumberStepper",
+ "entryPoint": "twenty-ui/primitives/input",
+ "slug": "input/number-stepper",
+ "props": [
+ {
+ "name": "allowOutOfRange",
+ "type": "boolean",
+ "required": false,
+ "defaultValue": "false",
+ "description": "Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded."
+ },
+ {
+ "name": "aria-roledescription",
+ "type": "string",
+ "required": false,
+ "defaultValue": "Number field",
+ "description": "A user-friendly description of the input's role for assistive tech. This is a role\ndescription, not an accessible name — use `Field.Label` or `aria-label` to name the control."
+ },
+ {
+ "name": "className",
+ "type": "string | ((state: NumberFieldInputState) => string | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Class applied to the visible input."
+ },
+ {
+ "name": "decrementLabel",
+ "type": "string",
+ "required": false,
+ "defaultValue": "Decrease value",
+ "description": "Accessible name for the decrement button."
+ },
+ {
+ "name": "defaultValue",
+ "type": "number",
+ "required": false,
+ "defaultValue": null,
+ "description": "Initial number when the field owns its value."
+ },
+ {
+ "name": "disabled",
+ "type": "boolean",
+ "required": false,
+ "defaultValue": "false",
+ "description": "Disables the input and both buttons, and omits the form value."
+ },
+ {
+ "name": "form",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "ID of the form that owns the submitted numeric value."
+ },
+ {
+ "name": "id",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "ID of the visible input. Generated when omitted."
+ },
+ {
+ "name": "incrementLabel",
+ "type": "string",
+ "required": false,
+ "defaultValue": "Increase value",
+ "description": "Accessible name for the increment button."
+ },
+ {
+ "name": "max",
+ "type": "number",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur."
+ },
+ {
+ "name": "min",
+ "type": "number",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur."
+ },
+ {
+ "name": "name",
+ "type": "string",
+ "required": false,
+ "defaultValue": null,
+ "description": "Name of the numeric value submitted with a form."
+ },
+ {
+ "name": "onValueChange",
+ "type": "((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) => void)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number."
+ },
+ {
+ "name": "readOnly",
+ "type": "boolean",
+ "required": false,
+ "defaultValue": "false",
+ "description": "Prevents numeric changes while keeping the input focusable."
+ },
+ {
+ "name": "ref",
+ "type": "Ref<HTMLInputElement>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Ref to the visible input element."
+ },
+ {
+ "name": "render",
+ "type": "ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<DetailedHTMLProps<InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, NumberFieldInputState>",
+ "required": false,
+ "defaultValue": null,
+ "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+ },
+ {
+ "name": "required",
+ "type": "boolean",
+ "required": false,
+ "defaultValue": "false",
+ "description": "Requires a numeric value for native form submission."
+ },
+ {
+ "name": "showButtons",
+ "type": "boolean",
+ "required": false,
+ "defaultValue": "true",
+ "description": "Shows the decrement and increment buttons."
+ },
+ {
+ "name": "step",
+ "type": "number",
+ "required": false,
+ "defaultValue": "1",
+ "description": "Amount added or subtracted by the buttons and arrow keys."
+ },
+ {
+ "name": "style",
+ "type": "CSSProperties | ((state: NumberFieldInputState) => CSSProperties | undefined)",
+ "required": false,
+ "defaultValue": null,
+ "description": "Inline styles applied to the visible input."
+ },
+ {
+ "name": "value",
+ "type": "number | null",
+ "required": false,
+ "defaultValue": null,
+ "description": "Controlled numeric value. Use null for an empty field."
+ }
+ ]
+ },
{
"name": "Textarea",
"entryPoint": "twenty-ui/primitives/input",
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.module.scss b/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.module.scss
new file mode 100644
index 00000000000..433b97a0e19
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.module.scss
@@ -0,0 +1,35 @@
+.root {
+ align-items: center;
+ display: inline-flex;
+ gap: var(--t-spacing-1);
+}
+
+.valueInput {
+ box-sizing: border-box;
+ font-weight: var(--t-font-weight-medium);
+ inline-size: var(--t-spacing-16);
+ text-align: center;
+}
+
+.button {
+ @include square-button;
+
+ --tw-button-size: var(--t-spacing-6);
+
+ &[data-readonly] {
+ --tw-button-active: var(--tw-button-background);
+ --tw-button-hover: var(--tw-button-background);
+
+ cursor: default;
+ opacity: 0.5;
+ }
+}
+
+.icon {
+ display: flex;
+
+ > svg {
+ block-size: calc(var(--t-icon-size-md) * 1px);
+ inline-size: calc(var(--t-icon-size-md) * 1px);
+ }
+}
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.module.scss.d.ts b/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.module.scss.d.ts
new file mode 100644
index 00000000000..25f1e17047c
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.module.scss.d.ts
@@ -0,0 +1,7 @@
+declare const classNames: {
+ readonly root: 'root';
+ readonly valueInput: 'valueInput';
+ readonly button: 'button';
+ readonly icon: 'icon';
+};
+export default classNames;
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.tsx
new file mode 100644
index 00000000000..d31af2479e9
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/NumberStepper.tsx
@@ -0,0 +1,135 @@
+import { NumberField } from '@base-ui/react/number-field';
+import { useControlled } from '@base-ui/utils/useControlled';
+import { useValueAsRef } from '@base-ui/utils/useValueAsRef';
+import { clsx } from 'clsx';
+
+import { IconMinus, IconPlus } from '@ui/icon';
+import { Button } from '@ui/primitives/input/Button/Button';
+import inputStyles from '@ui/primitives/input/Input/Input.module.scss';
+import { mergeClassNames } from '@ui/utilities/internal/mergeClassNames';
+
+import { NUMBER_STEPPER_FORMAT } from './internal/constants/NumberStepperFormat';
+import { isBlurRoundingOfCurrentValue } from './internal/utils/isBlurRoundingOfCurrentValue';
+import styles from './NumberStepper.module.scss';
+import { type NumberStepperProps } from './types/NumberStepperProps';
+
+export const NumberStepper = ({
+ value,
+ defaultValue,
+ onValueChange,
+ allowOutOfRange = false,
+ min,
+ max,
+ step = 1,
+ disabled,
+ readOnly,
+ required,
+ name,
+ form,
+ id,
+ showButtons = true,
+ decrementLabel = 'Decrease value',
+ incrementLabel = 'Increase value',
+ className,
+ ...props
+}: NumberStepperProps) => {
+ const [resolvedValue, setResolvedValue] = useControlled({
+ controlled: value,
+ default: defaultValue ?? null,
+ name: 'NumberStepper',
+ state: 'value',
+ });
+ const currentValueRef = useValueAsRef(resolvedValue);
+
+ const handleValueChange: NonNullable<
+ NumberField.Root.Props['onValueChange']
+ > = (nextValue, eventDetails) => {
+ if (nextValue === currentValueRef.current) {
+ return;
+ }
+
+ const isRoundingOnlyBlurChange = isBlurRoundingOfCurrentValue({
+ nextValue,
+ currentValue: currentValueRef.current,
+ reason: eventDetails.reason,
+ });
+
+ if (isRoundingOnlyBlurChange) {
+ eventDetails.cancel();
+ return;
+ }
+
+ onValueChange?.(nextValue, eventDetails);
+
+ if (eventDetails.isCanceled) {
+ return;
+ }
+
+ currentValueRef.current = nextValue;
+ setResolvedValue(nextValue);
+ };
+
+ return (
+ <NumberField.Root
+ value={resolvedValue}
+ onValueChange={handleValueChange}
+ min={min}
+ max={max}
+ allowOutOfRange={allowOutOfRange}
+ step={step}
+ smallStep={step}
+ largeStep={step}
+ disabled={disabled}
+ readOnly={readOnly}
+ required={required}
+ name={name}
+ form={form}
+ id={id}
+ format={NUMBER_STEPPER_FORMAT}
+ className={styles.root}
+ >
+ {showButtons && (
+ <NumberField.Decrement
+ aria-label={decrementLabel}
+ render={
+ <Button
+ type="button"
+ size="sm"
+ className={styles.button}
+ startIcon={
+ <span className={styles.icon}>
+ <IconMinus />
+ </span>
+ }
+ />
+ }
+ />
+ )}
+ <NumberField.Input
+ {...props}
+ form={form}
+ className={mergeClassNames(
+ clsx(inputStyles.input, inputStyles.sm, styles.valueInput),
+ className,
+ )}
+ />
+ {showButtons && (
+ <NumberField.Increment
+ aria-label={incrementLabel}
+ render={
+ <Button
+ type="button"
+ size="sm"
+ className={styles.button}
+ startIcon={
+ <span className={styles.icon}>
+ <IconPlus />
+ </span>
+ }
+ />
+ }
+ />
+ )}
+ </NumberField.Root>
+ );
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/ControlledNumberStepperExample.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/ControlledNumberStepperExample.tsx
new file mode 100644
index 00000000000..8f13cc9c5aa
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/ControlledNumberStepperExample.tsx
@@ -0,0 +1,22 @@
+import { useState } from 'react';
+
+import { NumberStepper } from '../NumberStepper';
+import { type NumberStepperProps } from '../types/NumberStepperProps';
+
+export const ControlledNumberStepperExample = (props: NumberStepperProps) => {
+ const [value, setValue] = useState<number | null>(props.defaultValue ?? null);
+
+ return (
+ <NumberStepper
+ {...props}
+ value={value}
+ onValueChange={(nextValue, eventDetails) => {
+ props.onValueChange?.(nextValue, eventDetails);
+
+ if (!eventDetails.isCanceled) {
+ setValue(nextValue);
+ }
+ }}
+ />
+ );
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.forms.stories.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.forms.stories.tsx
new file mode 100644
index 00000000000..2f829f663b8
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.forms.stories.tsx
@@ -0,0 +1,190 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+import { A11Y_DEFER_COLOR_CONTRAST, ComponentDecorator } from '@ui/testing';
+
+import { NumberStepper } from '../NumberStepper';
+import { NumberStepperFieldExample } from './NumberStepperFieldExample';
+import { NumberStepperFormExample } from './NumberStepperFormExample';
+
+const meta: Meta<typeof NumberStepper> = {
+ title: 'UI/Input/NumberStepper/Forms',
+ component: NumberStepper,
+ tags: ['!autodocs'],
+ decorators: [ComponentDecorator],
+ parameters: { a11y: A11Y_DEFER_COLOR_CONTRAST },
+ args: {
+ 'aria-label': 'Quantity',
+ defaultValue: 1,
+ min: 0,
+ max: 2,
+ onValueChange: fn(),
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof NumberStepper>;
+
+export const FormSubmission: Story = {
+ render: (args) => <NumberStepperFormExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+ const savedQuantity = canvas.getByLabelText('Saved quantity');
+ const submissionCount = canvas.getByLabelText('Submission count');
+
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Increase value' }),
+ );
+ await expect(input).toHaveValue('2');
+ await expect(savedQuantity).toHaveTextContent('Not saved');
+ await expect(submissionCount).toHaveTextContent('0');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Save quantity' }),
+ );
+ await expect(savedQuantity).toHaveTextContent('2');
+ await expect(submissionCount).toHaveTextContent('1');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ },
+};
+
+export const SmallFractionalStep: Story = {
+ args: { defaultValue: 0, step: 0.0001 },
+ render: (args) => <NumberStepperFormExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Increase value' }),
+ );
+ await expect(input).toHaveValue('0.0001');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 0.0001,
+ expect.anything(),
+ );
+ await userEvent.click(input);
+ await userEvent.tab();
+ await expect(input).toHaveValue('0.0001');
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Save quantity' }),
+ );
+ await expect(canvas.getByLabelText('Saved quantity')).toHaveTextContent(
+ '0.0001',
+ );
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ },
+};
+
+export const ExternalForm: Story = {
+ render: (args) => <NumberStepperFormExample {...args} external />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Save quantity' }),
+ );
+ await expect(canvas.getByLabelText('Saved quantity')).toHaveTextContent(
+ '1',
+ );
+ await expect(canvas.getByLabelText('Submission count')).toHaveTextContent(
+ '1',
+ );
+ },
+};
+
+export const Required: Story = {
+ args: { defaultValue: undefined, required: true },
+ render: (args) => <NumberStepperFormExample {...args} />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await expect(input).toBeRequired();
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Save quantity' }),
+ );
+ await expect(input).toBeInvalid();
+ await expect(canvas.getByLabelText('Submission count')).toHaveTextContent(
+ '0',
+ );
+ await userEvent.type(input, '2');
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Save quantity' }),
+ );
+ await expect(canvas.getByLabelText('Saved quantity')).toHaveTextContent(
+ '2',
+ );
+ await expect(canvas.getByLabelText('Submission count')).toHaveTextContent(
+ '1',
+ );
+ },
+};
+
+export const WithFieldAndRef: Story = {
+ render: (args) => <NumberStepperFieldExample {...args} />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await userEvent.click(canvas.getByText('Quantity', { selector: 'label' }));
+ await expect(input).toHaveFocus();
+ await expect(input).toHaveAttribute('aria-invalid', 'true');
+ await expect(input).toHaveAccessibleDescription(
+ 'Choose a quantity between zero and two. Check the quantity.',
+ );
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Focus quantity' }),
+ );
+ await expect(input).toHaveFocus();
+ },
+};
+
+export const OutOfRangeValidation: Story = {
+ args: { defaultValue: 60, min: 30, max: 90, allowOutOfRange: true },
+ render: (args) => <NumberStepperFormExample {...args} />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+ const saveButton = canvas.getByRole('button', { name: 'Save quantity' });
+
+ await userEvent.tripleClick(input);
+ await userEvent.keyboard('999');
+ await userEvent.click(saveButton);
+ await expect(input).toHaveValue('999');
+ await expect(input.closest('form')).toBeInvalid();
+ await expect(canvas.getByLabelText('Submission count')).toHaveTextContent(
+ '0',
+ );
+ await userEvent.tripleClick(input);
+ await userEvent.keyboard('60');
+ await userEvent.click(saveButton);
+ await expect(canvas.getByLabelText('Saved quantity')).toHaveTextContent(
+ '60',
+ );
+ await expect(canvas.getByLabelText('Submission count')).toHaveTextContent(
+ '1',
+ );
+ },
+};
+
+export const DisabledSubmission: Story = {
+ args: { disabled: true },
+ render: (args) => <NumberStepperFormExample {...args} />,
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+
+ await expect(
+ canvas.getByRole('textbox', { name: 'Quantity' }),
+ ).toBeDisabled();
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Save quantity' }),
+ );
+ await expect(canvas.getByLabelText('Saved quantity')).toBeEmptyDOMElement();
+ await expect(canvas.getByLabelText('Submission count')).toHaveTextContent(
+ '1',
+ );
+ },
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.interactions.stories.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.interactions.stories.tsx
new file mode 100644
index 00000000000..2edbc52eb9c
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.interactions.stories.tsx
@@ -0,0 +1,382 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+
+import { A11Y_DEFER_COLOR_CONTRAST, ComponentDecorator } from '@ui/testing';
+
+import { NumberStepper } from '../NumberStepper';
+import { type NumberStepperProps } from '../types/NumberStepperProps';
+import { ControlledNumberStepperExample } from './ControlledNumberStepperExample';
+
+const meta: Meta<typeof NumberStepper> = {
+ title: 'UI/Input/NumberStepper/Interactions',
+ component: NumberStepper,
+ tags: ['!autodocs'],
+ decorators: [ComponentDecorator],
+ parameters: { a11y: A11Y_DEFER_COLOR_CONTRAST },
+ args: {
+ 'aria-label': 'Quantity',
+ defaultValue: 1,
+ min: 0,
+ max: 2,
+ onValueChange: fn(),
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof NumberStepper>;
+
+export const PointerBounds: Story = {
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+ const decrease = canvas.getByRole('button', { name: 'Decrease value' });
+ const increase = canvas.getByRole('button', { name: 'Increase value' });
+
+ await expect(input.getBoundingClientRect().width).toBe(64);
+ await expect(input.getBoundingClientRect().height).toBe(24);
+ for (const button of [decrease, increase]) {
+ await expect(button.getBoundingClientRect().width).toBe(24);
+ await expect(button.getBoundingClientRect().height).toBe(24);
+ }
+
+ await userEvent.click(increase);
+ await expect(input).toHaveValue('2');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 2,
+ expect.anything(),
+ );
+ await expect(increase).toBeDisabled();
+ await userEvent.click(increase);
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+
+ await userEvent.click(decrease);
+ await userEvent.click(decrease);
+ await expect(input).toHaveValue('0');
+ await expect(decrease).toBeDisabled();
+ await userEvent.click(decrease);
+ await expect(args.onValueChange).toHaveBeenCalledTimes(3);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 0,
+ expect.anything(),
+ );
+ },
+};
+
+export const KeyboardBounds: Story = {
+ play: async ({ canvasElement, args }) => {
+ const input = within(canvasElement).getByRole('textbox', {
+ name: 'Quantity',
+ });
+
+ await userEvent.click(input);
+ await userEvent.keyboard('{ArrowUp}{ArrowUp}');
+ await expect(input).toHaveValue('2');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await userEvent.keyboard('{Home}{ArrowDown}');
+ await expect(input).toHaveValue('0');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ await userEvent.keyboard('{End}{ArrowDown}');
+ await expect(input).toHaveValue('1');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(4);
+ await userEvent.tab();
+ await expect(args.onValueChange).toHaveBeenCalledTimes(4);
+ },
+};
+
+export const ControlledDraft: Story = {
+ args: { min: -5, max: 5 },
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const input = within(canvasElement).getByRole('textbox', {
+ name: 'Quantity',
+ });
+
+ await userEvent.clear(input);
+ await expect(input).toHaveValue('');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ null,
+ expect.anything(),
+ );
+ await userEvent.type(input, '-');
+ await expect(input).toHaveValue('-');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await userEvent.tab();
+ await expect(input).toHaveValue('-');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await userEvent.type(input, '3');
+ await expect(input).toHaveValue('-3');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ -3,
+ expect.anything(),
+ );
+ await userEvent.tab();
+ await expect(input).toHaveValue('-3');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ },
+};
+
+export const BoundedDraft: Story = {
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const input = within(canvasElement).getByRole('textbox', {
+ name: 'Quantity',
+ });
+
+ await userEvent.clear(input);
+ await userEvent.type(input, '9');
+ await expect(input).toHaveValue('9');
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 2,
+ expect.anything(),
+ );
+ await userEvent.tab();
+ await expect(input).toHaveValue('2');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 2,
+ expect.anything(),
+ );
+ await userEvent.click(input);
+ await userEvent.tab();
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ },
+};
+
+export const FractionalStep: Story = {
+ args: { defaultValue: 0.1, step: 0.1 },
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Increase value' }),
+ );
+ await expect(input).toHaveValue('0.2');
+ await userEvent.click(input);
+ await userEvent.keyboard('{Shift>}{ArrowUp}{/Shift}');
+ await expect(input).toHaveValue('0.3');
+ await userEvent.keyboard('{Alt>}{ArrowDown}{/Alt}');
+ await expect(input).toHaveValue('0.2');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(3);
+ await expect(args.onValueChange).toHaveBeenNthCalledWith(
+ 2,
+ 0.3,
+ expect.anything(),
+ );
+ },
+};
+
+export const Disabled: Story = {
+ args: { disabled: true },
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await expect(input).toBeDisabled();
+ for (const button of canvas.getAllByRole('button')) {
+ await expect(button).toBeDisabled();
+ await userEvent.click(button);
+ }
+ await userEvent.type(input, '9');
+ await expect(input).toHaveValue('1');
+ await expect(args.onValueChange).not.toHaveBeenCalled();
+ },
+};
+
+export const ReadOnly: Story = {
+ args: { readOnly: true },
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await expect(input).toHaveAttribute('readonly');
+ await userEvent.click(input);
+ await expect(input).toHaveFocus();
+ await userEvent.keyboard('9{ArrowUp}{Home}{End}');
+ for (const button of canvas.getAllByRole('button')) {
+ await expect(button).toHaveAttribute('aria-disabled', 'true');
+ await expect(getComputedStyle(button).cursor).toBe('default');
+ await expect(getComputedStyle(button).opacity).toBe('0.5');
+ await userEvent.click(button);
+ }
+ await expect(input).toHaveValue('1');
+ await expect(args.onValueChange).not.toHaveBeenCalled();
+ },
+};
+
+export const OutOfRangeDraft: Story = {
+ args: { defaultValue: 60, min: 30, max: 90, allowOutOfRange: true },
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const input = within(canvasElement).getByRole('textbox', {
+ name: 'Quantity',
+ });
+
+ await userEvent.tripleClick(input);
+ await userEvent.keyboard('6');
+ await expect(input).toHaveValue('6');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 6,
+ expect.anything(),
+ );
+ await userEvent.keyboard('0');
+ await expect(input).toHaveValue('60');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 60,
+ expect.anything(),
+ );
+ await userEvent.tab();
+ await expect(input).toHaveValue('60');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ await userEvent.click(input);
+ await userEvent.tab();
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ },
+};
+
+export const OutOfRangeStepping: Story = {
+ args: { defaultValue: 60, min: 30, max: 90, allowOutOfRange: true },
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+ const decrease = canvas.getByRole('button', { name: 'Decrease value' });
+ const increase = canvas.getByRole('button', { name: 'Increase value' });
+
+ await userEvent.tripleClick(input);
+ await userEvent.keyboard('999');
+ await expect(input).toHaveValue('999');
+ await userEvent.tab();
+ await expect(input).toHaveValue('999');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(3);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 999,
+ expect.anything(),
+ );
+ await userEvent.click(decrease);
+ await expect(input).toHaveValue('90');
+ await expect(increase).toBeDisabled();
+ await expect(args.onValueChange).toHaveBeenCalledTimes(4);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 90,
+ expect.anything(),
+ );
+ await userEvent.click(input);
+ await userEvent.keyboard('{Home}{ArrowDown}');
+ await expect(input).toHaveValue('30');
+ await expect(decrease).toBeDisabled();
+ await expect(args.onValueChange).toHaveBeenCalledTimes(5);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 30,
+ expect.anything(),
+ );
+ },
+};
+
+export const OutOfRangeDraftStepping: Story = {
+ args: { defaultValue: 60, min: 30, max: 90, allowOutOfRange: true },
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await userEvent.tripleClick(input);
+ await userEvent.keyboard('4');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Increase value' }),
+ );
+ await expect(input).toHaveValue('30');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 30,
+ expect.anything(),
+ );
+ },
+};
+
+export const GroupedInput: Story = {
+ args: { defaultValue: 0, max: 20000 },
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const input = within(canvasElement).getByRole('textbox', {
+ name: 'Quantity',
+ });
+
+ await userEvent.tripleClick(input);
+ await userEvent.keyboard('12,500');
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 12500,
+ expect.anything(),
+ );
+ await userEvent.tab();
+ await expect(input).toHaveValue('12,500');
+ await userEvent.tripleClick(input);
+ await userEvent.paste('1,500');
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 1500,
+ expect.anything(),
+ );
+ await userEvent.tab();
+ await expect(input).toHaveValue('1500');
+ },
+};
+
+export const UneditedPrecision: Story = {
+ args: { defaultValue: 0.1 + 0.2 },
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const input = within(canvasElement).getByRole('textbox', {
+ name: 'Quantity',
+ });
+
+ await expect(input).toHaveValue('0.3');
+ await userEvent.click(input);
+ await userEvent.tab();
+ await expect(input).toHaveValue('0.3');
+ await expect(args.onValueChange).not.toHaveBeenCalled();
+ },
+};
+
+export const CanceledChange: Story = {
+ args: {
+ onValueChange: fn<NonNullable<NumberStepperProps['onValueChange']>>(
+ (nextValue, eventDetails) => {
+ if (nextValue === 2) {
+ eventDetails.cancel();
+ }
+ },
+ ),
+ },
+ render: (args) => <ControlledNumberStepperExample {...args} />,
+ play: async ({ canvasElement, args }) => {
+ const canvas = within(canvasElement);
+ const input = canvas.getByRole('textbox', { name: 'Quantity' });
+
+ await userEvent.click(
+ canvas.getByRole('button', { name: 'Increase value' }),
+ );
+ await expect(input).toHaveValue('1');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(1);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 2,
+ expect.objectContaining({ isCanceled: true }),
+ );
+ await userEvent.click(input);
+ await userEvent.keyboard('{ArrowUp}');
+ await expect(input).toHaveValue('1');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(2);
+ await userEvent.keyboard('{ArrowDown}');
+ await expect(input).toHaveValue('0');
+ await expect(args.onValueChange).toHaveBeenCalledTimes(3);
+ await expect(args.onValueChange).toHaveBeenLastCalledWith(
+ 0,
+ expect.objectContaining({ isCanceled: false }),
+ );
+ },
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.stories.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.stories.tsx
new file mode 100644
index 00000000000..5d081862c75
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepper.stories.tsx
@@ -0,0 +1,79 @@
+import { type Meta, type StoryObj } from '@storybook/react-vite';
+
+import {
+ A11Y_DEFER_COLOR_CONTRAST,
+ CatalogDecorator,
+ type CatalogStory,
+ ComponentDecorator,
+} from '@ui/testing';
+
+import { NumberStepper } from '../NumberStepper';
+
+const meta: Meta<typeof NumberStepper> = {
+ title: 'UI/Input/NumberStepper',
+ component: NumberStepper,
+ args: { 'aria-label': 'Quantity', defaultValue: 3, min: 0, max: 10 },
+};
+
+export default meta;
+type Story = StoryObj<typeof NumberStepper>;
+
+export const Default: Story = {
+ decorators: [ComponentDecorator],
+};
+
+export const WithoutButtons: Story = {
+ decorators: [ComponentDecorator],
+ args: { showButtons: false },
+};
+
+type NumberStepperCatalogState =
+ | 'default'
+ | 'minimum'
+ | 'maximum'
+ | 'disabled'
+ | 'readOnly'
+ | 'invalid';
+
+const getNumberStepperCatalogStateProps = (
+ state: NumberStepperCatalogState,
+) => ({
+ defaultValue: state === 'minimum' ? 0 : state === 'maximum' ? 10 : 3,
+ disabled: state === 'disabled',
+ readOnly: state === 'readOnly',
+ 'aria-invalid': state === 'invalid' || undefined,
+});
+
+export const Catalog: CatalogStory<Story, typeof NumberStepper> = {
+ decorators: [CatalogDecorator],
+ parameters: {
+ a11y: A11Y_DEFER_COLOR_CONTRAST,
+ catalog: {
+ dimensions: [
+ {
+ name: 'state',
+ values: [
+ 'default',
+ 'minimum',
+ 'maximum',
+ 'disabled',
+ 'readOnly',
+ 'invalid',
+ ] satisfies NumberStepperCatalogState[],
+ props: getNumberStepperCatalogStateProps,
+ },
+ {
+ name: 'buttons',
+ values: ['visible', 'hidden'],
+ props: (buttons: string) => ({ showButtons: buttons === 'visible' }),
+ },
+ ],
+ },
+ },
+};
+
+export const CatalogDark: CatalogStory<Story, typeof NumberStepper> = {
+ ...Catalog,
+ tags: ['!autodocs'],
+ globals: { colorScheme: 'dark' },
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepperFieldExample.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepperFieldExample.tsx
new file mode 100644
index 00000000000..847eeb043ea
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepperFieldExample.tsx
@@ -0,0 +1,25 @@
+import { useRef } from 'react';
+
+import { Button } from '@ui/primitives/input/Button/Button';
+import { Field } from '@ui/primitives/input/Field/Field';
+
+import { NumberStepper } from '../NumberStepper';
+import { type NumberStepperProps } from '../types/NumberStepperProps';
+
+export const NumberStepperFieldExample = (props: NumberStepperProps) => {
+ const inputRef = useRef<HTMLInputElement>(null);
+
+ return (
+ <>
+ <Field.Root invalid>
+ <Field.Label>Quantity</Field.Label>
+ <NumberStepper {...props} aria-label={undefined} ref={inputRef} />
+ <Field.Description>
+ Choose a quantity between zero and two.
+ </Field.Description>
+ <Field.Error match>Check the quantity.</Field.Error>
+ </Field.Root>
+ <Button onClick={() => inputRef.current?.focus()}>Focus quantity</Button>
+ </>
+ );
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepperFormExample.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepperFormExample.tsx
new file mode 100644
index 00000000000..1ff6184d58b
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/__stories__/NumberStepperFormExample.tsx
@@ -0,0 +1,38 @@
+import { useId, useState } from 'react';
+
+import { Button } from '@ui/primitives/input/Button/Button';
+
+import { NumberStepper } from '../NumberStepper';
+import { type NumberStepperProps } from '../types/NumberStepperProps';
+
+export const NumberStepperFormExample = ({
+ external = false,
+ ...props
+}: NumberStepperProps & { external?: boolean }) => {
+ const formId = useId();
+ const [savedQuantity, setSavedQuantity] = useState('Not saved');
+ const [submissionCount, setSubmissionCount] = useState(0);
+
+ const input = <NumberStepper {...props} form={formId} name="quantity" />;
+
+ return (
+ <>
+ {external && input}
+ <form
+ id={formId}
+ onSubmit={(event) => {
+ event.preventDefault();
+ setSavedQuantity(
+ String(new FormData(event.currentTarget).get('quantity') ?? ''),
+ );
+ setSubmissionCount((count) => count + 1);
+ }}
+ >
+ {!external && input}
+ <Button type="submit">Save quantity</Button>
+ </form>
+ <output aria-label="Saved quantity">{savedQuantity}</output>
+ <output aria-label="Submission count">{submissionCount}</output>
+ </>
+ );
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/__tests__/NumberStepper.test.tsx b/packages/twenty-ui/src/primitives/input/NumberStepper/__tests__/NumberStepper.test.tsx
new file mode 100644
index 00000000000..88c5788e6b3
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/__tests__/NumberStepper.test.tsx
@@ -0,0 +1,12 @@
+import { runComponentConformance } from '@test-utilities/conformance/runComponentConformance';
+
+import { NumberStepper } from '../NumberStepper';
+import styles from '../NumberStepper.module.scss';
+
+runComponentConformance({
+ name: 'NumberStepper',
+ element: <NumberStepper aria-label="Quantity" />,
+ refInstanceOf: HTMLInputElement,
+ ownClassName: styles.valueInput,
+ renderPropTagName: 'input',
+});
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/internal/constants/NumberStepperFormat.ts b/packages/twenty-ui/src/primitives/input/NumberStepper/internal/constants/NumberStepperFormat.ts
new file mode 100644
index 00000000000..037ec0cb014
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/internal/constants/NumberStepperFormat.ts
@@ -0,0 +1,5 @@
+export const NUMBER_STEPPER_FORMAT: Intl.NumberFormatOptions = {
+ maximumFractionDigits: 15,
+ numberingSystem: 'latn',
+ useGrouping: 'min2',
+};
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/internal/utils/isBlurRoundingOfCurrentValue.ts b/packages/twenty-ui/src/primitives/input/NumberStepper/internal/utils/isBlurRoundingOfCurrentValue.ts
new file mode 100644
index 00000000000..394c4151796
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/internal/utils/isBlurRoundingOfCurrentValue.ts
@@ -0,0 +1,19 @@
+import { type NumberField } from '@base-ui/react/number-field';
+import { formatNumber } from '@base-ui/utils/formatNumber';
+
+import { NUMBER_STEPPER_FORMAT } from '../constants/NumberStepperFormat';
+
+type IsBlurRoundingOfCurrentValueArgs = {
+ nextValue: number | null;
+ currentValue: number | null;
+ reason: NumberField.Root.ChangeEventReason;
+};
+
+export const isBlurRoundingOfCurrentValue = ({
+ nextValue,
+ currentValue,
+ reason,
+}: IsBlurRoundingOfCurrentValueArgs) =>
+ reason === 'input-blur' &&
+ formatNumber(nextValue, undefined, NUMBER_STEPPER_FORMAT) ===
+ formatNumber(currentValue, undefined, NUMBER_STEPPER_FORMAT);
diff --git a/packages/twenty-ui/src/primitives/input/NumberStepper/types/NumberStepperProps.ts b/packages/twenty-ui/src/primitives/input/NumberStepper/types/NumberStepperProps.ts
new file mode 100644
index 00000000000..693bcc041e2
--- /dev/null
+++ b/packages/twenty-ui/src/primitives/input/NumberStepper/types/NumberStepperProps.ts
@@ -0,0 +1,36 @@
+import { type NumberField } from '@base-ui/react/number-field';
+
+export type NumberStepperProps = Omit<
+ NumberField.Input.Props,
+ | 'children'
+ | 'defaultValue'
+ | 'disabled'
+ | 'max'
+ | 'min'
+ | 'name'
+ | 'onChange'
+ | 'readOnly'
+ | 'required'
+ | 'size'
+ | 'step'
+ | 'type'
+ | 'value'
+> &
+ Pick<
+ NumberField.Root.Props,
+ | 'allowOutOfRange'
+ | 'defaultValue'
+ | 'disabled'
+ | 'max'
+ | 'min'
+ | 'name'
+ | 'onValueChange'
+ | 'readOnly'
+ | 'required'
+ | 'value'
+ > & {
+ step?: number;
+ showButtons?: boolean;
+ decrementLabel?: string;
+ incrementLabel?: string;
+ };
diff --git a/packages/twenty-ui/src/primitives/input/index.ts b/packages/twenty-ui/src/primitives/input/index.ts
index e5bcf4d0f22..f18d70d4492 100644
--- a/packages/twenty-ui/src/primitives/input/index.ts
+++ b/packages/twenty-ui/src/primitives/input/index.ts
@@ -25,6 +25,8 @@ export { Input } from './Input/Input';
export type { InputProps } from './Input/types/InputProps';
export { InputGroup } from './InputGroup/InputGroup';
export type { InputGroupProps } from './InputGroup/types/InputGroupProps';
+export { NumberStepper } from './NumberStepper/NumberStepper';
+export type { NumberStepperProps } from './NumberStepper/types/NumberStepperProps';
export { Radio } from './Radio/Radio';
export type { RadioProps } from './Radio/types/RadioProps';
export { RadioGroup } from './RadioGroup/RadioGroup';
diff --git a/packages/twenty-ui/tsconfig.json b/packages/twenty-ui/tsconfig.json
index 5349269693b..ab6f0ff360d 100644
--- a/packages/twenty-ui/tsconfig.json
+++ b/packages/twenty-ui/tsconfig.json
@@ -2,6 +2,7 @@
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"target": "ES2020",
+ "lib": ["ES2020", "DOM", "ES2023.Intl"],
"jsx": "react-jsx",
"allowJs": false,
"allowSyntheticDefaultImports": true,