@box/blueprint-web 16.20.0 → 16.20.2

package/dist/lib-esm/index.d.ts

@@ -39,6 +39,7 @@ export * from './list-item/list-item';
 export * from './loading-indicator/loading-indicator';
 export * from './modal';
 export * from './navigation-menu';
+export * from './number-field';
 export * from './page';
 export * from './page-section';
 export * from './password-input';

package/dist/lib-esm/index.js

@@ -50,6 +50,7 @@ export { LoadingIndicator } from './loading-indicator/loading-indicator.js';
 export { AlertModal } from './modal/alert-modal.js';
 export { Modal } from './modal/modal.js';
 export { NavigationMenu } from './navigation-menu/index.js';
+export { NumberField } from './number-field/number-field.js';
 export { Page } from './page/index.js';
 export { PageSection } from './page-section/index.js';
 export { PasswordInput } from './password-input/password-input.js';

package/dist/lib-esm/number-field/constants.d.ts

@@ -0,0 +1,5 @@
+/** Three digits, the width the design spec draws the control at. */
+declare const NUMBER_FIELD_DEFAULT_MAX = 999;
+/** Non-negative integers only. Also governs what react-aria lets through, keeping the field digits-only. */
+declare const NUMBER_FIELD_FORMAT_OPTIONS: Intl.NumberFormatOptions;
+export { NUMBER_FIELD_DEFAULT_MAX, NUMBER_FIELD_FORMAT_OPTIONS };

package/dist/lib-esm/number-field/constants.js

@@ -0,0 +1,9 @@
+/** Three digits, the width the design spec draws the control at. */
+const NUMBER_FIELD_DEFAULT_MAX = 999;
+/** Non-negative integers only. Also governs what react-aria lets through, keeping the field digits-only. */
+const NUMBER_FIELD_FORMAT_OPTIONS = {
+  maximumFractionDigits: 0,
+  useGrouping: false
+};
+
+export { NUMBER_FIELD_DEFAULT_MAX, NUMBER_FIELD_FORMAT_OPTIONS };

package/dist/lib-esm/number-field/index.d.ts

@@ -0,0 +1,2 @@
+export { NumberField } from './number-field';
+export { type NumberFieldProps } from './types';

package/dist/lib-esm/number-field/number-field-control.d.ts

@@ -0,0 +1,24 @@
+import { type ComponentPropsWithoutRef, type ForwardedRef } from 'react';
+type NumberFieldControlProps = {
+    ariaValueMax: number;
+    ariaValueMin: number;
+    decrementAriaLabel: string;
+    hasError: boolean;
+    incrementAriaLabel: string;
+    inputLength: number;
+    inputProps: ComponentPropsWithoutRef<'input'>;
+    inputRef: ForwardedRef<HTMLInputElement>;
+    isAnimationEnabled: boolean;
+    isDecrementDisabled: boolean;
+    isDecrementLoading: boolean;
+    isIncrementDisabled: boolean;
+    isIncrementLoading: boolean;
+    labelId: string;
+    loadingAriaLabel?: string;
+    maxReachedTooltipContent?: string;
+    minReachedTooltipContent?: string;
+    showDecrementTooltip: boolean;
+    showIncrementTooltip: boolean;
+};
+export declare const NumberFieldControl: ({ ariaValueMax, ariaValueMin, decrementAriaLabel, hasError, incrementAriaLabel, inputLength, inputProps, inputRef, isAnimationEnabled, isDecrementDisabled, isDecrementLoading, isIncrementDisabled, isIncrementLoading, labelId, loadingAriaLabel, maxReachedTooltipContent, minReachedTooltipContent, showDecrementTooltip, showIncrementTooltip, }: NumberFieldControlProps) => React.ReactElement;
+export {};

package/dist/lib-esm/number-field/number-field-control.js

@@ -0,0 +1,82 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { Minus, Plus } from '@box/blueprint-web-assets/icons/Medium';
+import { useContext } from 'react';
+import { NumberFieldStateContext, useContextProps, InputContext, Group } from 'react-aria-components';
+import { BaseTextInput } from '../primitives/base-text-input/base-text-input.js';
+import { StepperButton } from './stepper-button.js';
+import styles from './number-field.module.js';
+
+const NumberFieldControl = ({
+  ariaValueMax,
+  ariaValueMin,
+  decrementAriaLabel,
+  hasError,
+  incrementAriaLabel,
+  inputLength,
+  inputProps,
+  inputRef,
+  isAnimationEnabled,
+  isDecrementDisabled,
+  isDecrementLoading,
+  isIncrementDisabled,
+  isIncrementLoading,
+  labelId,
+  loadingAriaLabel,
+  maxReachedTooltipContent,
+  minReachedTooltipContent,
+  showDecrementTooltip,
+  showIncrementTooltip
+}) => {
+  const state = useContext(NumberFieldStateContext);
+  const [racInputProps, racInputRef] = useContextProps({
+    maxLength: inputLength
+  }, inputRef, InputContext);
+  if (!state) {
+    throw new Error('NumberFieldControl must be rendered inside NumberField');
+  }
+  const decrementLoading = loadingAriaLabel && isDecrementLoading ? {
+    loading: true,
+    loadingAriaLabel
+  } : {};
+  const incrementLoading = loadingAriaLabel && isIncrementLoading ? {
+    loading: true,
+    loadingAriaLabel
+  } : {};
+  return jsxs(Group, {
+    "aria-labelledby": labelId,
+    className: styles.control,
+    children: [jsx(StepperButton, {
+      ariaLabel: decrementAriaLabel,
+      className: styles.stepperLeft,
+      disabled: isDecrementDisabled,
+      icon: Minus,
+      onClick: state.decrement,
+      showTooltip: showDecrementTooltip,
+      tooltipContent: minReachedTooltipContent,
+      ...decrementLoading
+    }), jsx(BaseTextInput, {
+      ...inputProps,
+      ...racInputProps,
+      ref: racInputRef,
+      "aria-valuemax": ariaValueMax,
+      "aria-valuemin": ariaValueMin,
+      className: styles.input,
+      "data-bp-animated": isAnimationEnabled ? 'true' : 'false',
+      invalid: hasError,
+      label: "",
+      // Pinned to the `text` react-aria already sets, since it types this as any input type.
+      type: "text"
+    }), jsx(StepperButton, {
+      ariaLabel: incrementAriaLabel,
+      className: styles.stepperRight,
+      disabled: isIncrementDisabled,
+      icon: Plus,
+      onClick: state.increment,
+      showTooltip: showIncrementTooltip,
+      tooltipContent: maxReachedTooltipContent,
+      ...incrementLoading
+    })]
+  });
+};
+
+export { NumberFieldControl };

package/dist/lib-esm/number-field/number-field.d.ts

@@ -0,0 +1,9 @@
+import { type NumberFieldProps } from './types';
+/**
+ * Numeric form field with a label, a decrement/increment stepper, and optional subtext or error.
+ *
+ * Formats non-negative whole numbers out of the box; `formatOptions` opens that up to decimals, currency
+ * and percent, and doubles as the rule for what may be typed. The control is sized to hold `maxLength`
+ * characters and does not grow or shrink with its container.
+ */
+export declare const NumberField: import("react").ForwardRefExoticComponent<NumberFieldProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/lib-esm/number-field/number-field.js

@@ -0,0 +1,140 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import clsx from 'clsx';
+import { forwardRef } from 'react';
+import { NumberField as NumberField$1 } from 'react-aria-components';
+import '../blueprint-configuration-context/blueprint-configuration-context.js';
+import '../blueprint-configuration-context/consts.js';
+import { useBlueprintConfiguration } from '../blueprint-configuration-context/useBlueprintConfiguration.js';
+import { InlineError } from '../primitives/inline-error/inline-error.js';
+import { Text } from '../text/text.js';
+import { useLabelable } from '../util-components/labelable/useLabelable.js';
+import { useUniqueId } from '../utils/useUniqueId.js';
+import { NUMBER_FIELD_FORMAT_OPTIONS, NUMBER_FIELD_DEFAULT_MAX } from './constants.js';
+import { NumberFieldControl } from './number-field-control.js';
+import styles from './number-field.module.js';
+
+/**
+ * Numeric form field with a label, a decrement/increment stepper, and optional subtext or error.
+ *
+ * Formats non-negative whole numbers out of the box; `formatOptions` opens that up to decimals, currency
+ * and percent, and doubles as the rule for what may be typed. The control is sized to hold `maxLength`
+ * characters and does not grow or shrink with its container.
+ */
+const NumberField = /*#__PURE__*/forwardRef((props, forwardedRef) => {
+  const {
+    className,
+    decrementAriaLabel,
+    disabled = false,
+    error,
+    form,
+    formatOptions = NUMBER_FIELD_FORMAT_OPTIONS,
+    hideLabel = false,
+    id,
+    incrementAriaLabel,
+    label,
+    loading = false,
+    loadingAriaLabel,
+    max = NUMBER_FIELD_DEFAULT_MAX,
+    maxLength,
+    maxReachedTooltipContent,
+    min = 0,
+    minReachedTooltipContent,
+    name,
+    onChange,
+    readOnly = false,
+    required = false,
+    step = 1,
+    subtext,
+    value,
+    'aria-describedby': ariaDescribedByProp,
+    ...rest
+  } = props;
+  const uniqueId = useUniqueId('number-field-');
+  const inputId = id || uniqueId;
+  const labelId = useUniqueId('number-field-label-');
+  const subtextId = useUniqueId('number-field-subtext-');
+  const inlineErrorId = useUniqueId('number-field-error-');
+  const isDecrementLoading = !disabled && (loading === true || loading === 'decrement');
+  const isIncrementLoading = !disabled && (loading === true || loading === 'increment');
+  const isAnyLoading = isDecrementLoading || isIncrementLoading;
+  const isInteractive = !disabled && !readOnly;
+  // Hide the error while loading: BaseTextInput suppresses aria-invalid when disabled, so showing
+  // InlineError alone would leave an inconsistent a11y state.
+  const hasError = !!error && !disabled && !isAnyLoading;
+  const hasSubtext = !hasError && !!subtext;
+  // Also sizes the control, handed to the stylesheet as `--number-field-digits` below.
+  const inputLength = maxLength ?? String(max).length;
+  const Label = useLabelable(label, inputId, required);
+  // Mirrors TextInput
+  const {
+    componentsWithAnimationEnabled
+  } = useBlueprintConfiguration();
+  const isAnimationEnabled = componentsWithAnimationEnabled.includes('TextInput');
+  const ariaDescribedBy = clsx(ariaDescribedByProp, {
+    [inlineErrorId]: hasError,
+    [subtextId]: hasSubtext
+  }) || undefined;
+  return jsxs(NumberField$1, {
+    "aria-describedby": ariaDescribedBy,
+    "aria-labelledby": labelId,
+    className: clsx(styles.numberField, className),
+    formatOptions: formatOptions,
+    form: form,
+    id: inputId,
+    isDisabled: disabled || isAnyLoading,
+    isInvalid: hasError,
+    isReadOnly: readOnly,
+    isRequired: required,
+    maxValue: max,
+    minValue: min,
+    name: name,
+    onChange: onChange,
+    step: step,
+    style: {
+      '--number-field-digits': inputLength
+    },
+    validationBehavior: "native",
+    value: value,
+    children: [jsx(Label, {
+      className: clsx(styles.label, {
+        [styles.hidden]: hideLabel
+      }),
+      hideLabel: hideLabel,
+      id: labelId
+    }), jsx(NumberFieldControl, {
+      ariaValueMax: max,
+      ariaValueMin: min,
+      decrementAriaLabel: decrementAriaLabel,
+      hasError: hasError,
+      incrementAriaLabel: incrementAriaLabel,
+      inputLength: inputLength,
+      inputProps: rest,
+      inputRef: forwardedRef,
+      isAnimationEnabled: isAnimationEnabled,
+      isDecrementDisabled: !isInteractive || value <= min || isAnyLoading && !isDecrementLoading,
+      isDecrementLoading: isDecrementLoading,
+      isIncrementDisabled: !isInteractive || value >= max || isAnyLoading && !isIncrementLoading,
+      isIncrementLoading: isIncrementLoading,
+      labelId: labelId,
+      loadingAriaLabel: loadingAriaLabel,
+      maxReachedTooltipContent: maxReachedTooltipContent,
+      minReachedTooltipContent: minReachedTooltipContent,
+      showDecrementTooltip: isInteractive && !isAnyLoading && value <= min,
+      showIncrementTooltip: isInteractive && !isAnyLoading && value >= max
+    }), hasError ? jsx(InlineError, {
+      className: styles.inlineError,
+      id: inlineErrorId,
+      children: error
+    }) : hasSubtext && jsx(Text, {
+      as: "p",
+      className: styles.subtext,
+      color: "textOnLightSecondary",
+      id: subtextId,
+      variant: "caption",
+      children: subtext
+    })]
+  });
+});
+NumberField.displayName = 'NumberField';
+
+export { NumberField };

package/dist/lib-esm/number-field/number-field.module.js

@@ -0,0 +1,4 @@
+import '../index.css';
+var styles = {"numberField":"bp_number_field_module_numberField--e9b37","label":"bp_number_field_module_label--e9b37","hidden":"bp_number_field_module_hidden--e9b37","control":"bp_number_field_module_control--e9b37","stepperLeft":"bp_number_field_module_stepperLeft--e9b37","stepperRight":"bp_number_field_module_stepperRight--e9b37","input":"bp_number_field_module_input--e9b37","inlineError":"bp_number_field_module_inlineError--e9b37","subtext":"bp_number_field_module_subtext--e9b37"};
+
+export { styles as default };

package/dist/lib-esm/number-field/stepper-button.d.ts

@@ -0,0 +1,21 @@
+import { type RequireAllOrNone } from 'type-fest';
+import { type SvgIconComponent } from '../button/types';
+type StepperLoadingProps = RequireAllOrNone<{
+    loading: boolean;
+    loadingAriaLabel: string;
+}, 'loading' | 'loadingAriaLabel'>;
+type StepperButtonProps = {
+    ariaLabel: string;
+    className?: string;
+    disabled: boolean;
+    icon: SvgIconComponent;
+    onClick: () => void;
+    showTooltip: boolean;
+    tooltipContent?: string;
+} & StepperLoadingProps;
+/**
+ * With a boundary tooltip to show, `disabled` gives way to `aria-disabled` so the button stays focusable
+ * and hoverable enough to surface it.
+ */
+export declare const StepperButton: ({ ariaLabel, className, disabled, icon, onClick, showTooltip, tooltipContent, ...loadingProps }: StepperButtonProps) => React.ReactElement;
+export type { StepperLoadingProps };

package/dist/lib-esm/number-field/stepper-button.js

@@ -0,0 +1,41 @@
+import { jsx } from 'react/jsx-runtime';
+import { Button } from '../button/button.js';
+import { Tooltip } from '../tooltip/tooltip.js';
+
+/**
+ * With a boundary tooltip to show, `disabled` gives way to `aria-disabled` so the button stays focusable
+ * and hoverable enough to surface it.
+ */
+const StepperButton = ({
+  ariaLabel,
+  className,
+  disabled,
+  icon,
+  onClick,
+  showTooltip,
+  tooltipContent,
+  ...loadingProps
+}) => {
+  const tooltip = showTooltip ? tooltipContent : undefined;
+  const button = jsx(Button, {
+    ...loadingProps,
+    accessibleWhenDisabled: !!tooltip,
+    "aria-label": ariaLabel,
+    className: className,
+    disabled: disabled,
+    onClick: onClick,
+    size: "large",
+    startIcon: icon,
+    type: "button",
+    variant: "secondary"
+  });
+  if (tooltip) {
+    return jsx(Tooltip, {
+      content: tooltip,
+      children: button
+    });
+  }
+  return button;
+};
+
+export { StepperButton };

package/dist/lib-esm/number-field/types.d.ts

@@ -0,0 +1,99 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import { type RequireAllOrNone } from 'type-fest';
+import { type Labelable } from '../util-components/labelable';
+export interface Loading {
+    /**
+     * Shows a spinner on both steppers, or on just one. The input and the other stepper are disabled while
+     * it spins. Requires `loadingAriaLabel`.
+     */
+    loading: boolean | 'increment' | 'decrement';
+    /** The aria-label for the stepper loading indicators. */
+    loadingAriaLabel: string;
+}
+/**
+ * Attributes NumberField sets from its own props, so they cannot be forwarded. `size` is included because
+ * the control takes its width from `maxLength`.
+ */
+type ReservedInputAttributes = 'defaultValue' | 'disabled' | 'inputMode' | 'max' | 'min' | 'onBlur' | 'onChange' | 'onKeyDown' | 'pattern' | 'readOnly' | 'required' | 'size' | 'step' | 'type' | 'value';
+/**
+ * Remaining props are forwarded to the `<input>`, so the field takes part in native form submission.
+ * `className` styles the wrapper holding the label, the control and the subtext.
+ */
+interface NumberFieldBaseProps extends Omit<ComponentPropsWithoutRef<'input'>, ReservedInputAttributes>, Labelable {
+    /** Accessible label for the decrement button. */
+    decrementAriaLabel: string;
+    /**
+     * When true, prevents the user from interacting with the field.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+    /** Error message rendered below the control, replacing the subtext and marking the control invalid. */
+    error?: ReactNode;
+    /**
+     * How the value is formatted and, in turn, what may be typed — react-aria parses input with the same
+     * options it formats with. Must be a stable reference, so hoist or memoize it.
+     *
+     * @default { maximumFractionDigits: 0, useGrouping: false }
+     */
+    formatOptions?: Intl.NumberFormatOptions;
+    /**
+     * When true, the label is visually hidden but remains available to assistive technology.
+     *
+     * @default false
+     */
+    hideLabel?: boolean;
+    /** Accessible label for the increment button. */
+    incrementAriaLabel: string;
+    /** The field label rendered above the control. */
+    label: Labelable['label'];
+    /**
+     * The upper bound. Disables the increment button once reached, shows `maxReachedTooltipContent`, and
+     * snaps typed commits down to this value.
+     *
+     * @default 999
+     */
+    max?: number;
+    /**
+     * How many characters the input accepts and is sized to hold. Defaults to the digits of `max`; set it
+     * when `formatOptions` needs room for a separator or a sign.
+     */
+    maxLength?: number;
+    /** Localized tooltip content shown when the increment button is disabled because the value is at max. */
+    maxReachedTooltipContent?: string;
+    /**
+     * The lower bound. Disables the decrement button once reached, shows `minReachedTooltipContent`, and
+     * snaps typed commits up to this value.
+     *
+     * @default 0
+     */
+    min?: number;
+    /** Localized tooltip content shown when the decrement button is disabled because the value is at min. */
+    minReachedTooltipContent?: string;
+    /** Called with the new value when a stepper is used, or when the typed draft is committed on blur or Enter. */
+    onChange: (value: number) => void;
+    /**
+     * When true, the value is displayed but cannot be edited and the stepper buttons are inactive.
+     *
+     * @default false
+     */
+    readOnly?: boolean;
+    /**
+     * When true, marks the field as required.
+     *
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * The stepping interval used by the increment and decrement buttons.
+     *
+     * @default 1
+     */
+    step?: number;
+    /** Helper text rendered below the control. Not rendered while the field is in its error state. */
+    subtext?: string;
+    /** The controlled value of the field. Must be used in conjunction with `onChange`. */
+    value: number;
+}
+export type NumberFieldProps = NumberFieldBaseProps & RequireAllOrNone<Loading, keyof Loading>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@box/blueprint-web",
-    "version": "16.20.0",
+    "version": "16.20.2",
     "type": "module",
     "license": "SEE LICENSE IN LICENSE",
     "publishConfig": {
@@ -50,7 +50,7 @@
     "dependencies": {
         "@ariakit/react": "0.4.21",
         "@ariakit/react-core": "0.4.21",
-        "@box/blueprint-web-assets": "^5.7.7",
+        "@box/blueprint-web-assets": "^5.7.9",
         "@internationalized/date": "^3.12.0",
         "@radix-ui/react-accordion": "1.1.2",
         "@radix-ui/react-checkbox": "1.0.4",
@@ -79,7 +79,7 @@
         "type-fest": "^3.2.0"
     },
     "devDependencies": {
-        "@box/storybook-utils": "^1.2.16",
+        "@box/storybook-utils": "^1.2.18",
         "@figma/code-connect": "1.4.4",
         "@types/react": "^18.0.0",
         "@types/react-dom": "^18.0.0",