@commercetools/nimbus 1.0.1 → 2.0.1-rc1

package/dist/money-input.d.ts

@@ -0,0 +1,879 @@
+import { HTMLChakraProps } from '@chakra-ui/react';
+import { JSX } from 'react/jsx-runtime';
+import { SlotRecipeProps } from '@chakra-ui/react';
+import { TMoneyValue as TMoneyValue_2 } from '..';
+import { TValue as TValue_2 } from '..';
+
+declare const currencies: {
+    readonly ADP: {
+        readonly fractionDigits: 0;
+    };
+    readonly AED: {
+        readonly fractionDigits: 2;
+    };
+    readonly AFA: {
+        readonly fractionDigits: 2;
+    };
+    readonly AFN: {
+        readonly fractionDigits: 2;
+    };
+    readonly ALL: {
+        readonly fractionDigits: 2;
+    };
+    readonly AMD: {
+        readonly fractionDigits: 2;
+    };
+    readonly ANG: {
+        readonly fractionDigits: 2;
+    };
+    readonly AOA: {
+        readonly fractionDigits: 2;
+    };
+    readonly ARS: {
+        readonly fractionDigits: 2;
+    };
+    readonly ATS: {
+        readonly fractionDigits: 2;
+    };
+    readonly AUD: {
+        readonly fractionDigits: 2;
+    };
+    readonly AWG: {
+        readonly fractionDigits: 2;
+    };
+    readonly AYM: {
+        readonly fractionDigits: 2;
+    };
+    readonly AZM: {
+        readonly fractionDigits: 2;
+    };
+    readonly AZN: {
+        readonly fractionDigits: 2;
+    };
+    readonly BAM: {
+        readonly fractionDigits: 2;
+    };
+    readonly BBD: {
+        readonly fractionDigits: 2;
+    };
+    readonly BDT: {
+        readonly fractionDigits: 2;
+    };
+    readonly BEF: {
+        readonly fractionDigits: 0;
+    };
+    readonly BGL: {
+        readonly fractionDigits: 2;
+    };
+    readonly BGN: {
+        readonly fractionDigits: 2;
+    };
+    readonly BHD: {
+        readonly fractionDigits: 3;
+    };
+    readonly BIF: {
+        readonly fractionDigits: 0;
+    };
+    readonly BMD: {
+        readonly fractionDigits: 2;
+    };
+    readonly BND: {
+        readonly fractionDigits: 2;
+    };
+    readonly BOB: {
+        readonly fractionDigits: 2;
+    };
+    readonly BOV: {
+        readonly fractionDigits: 2;
+    };
+    readonly BRL: {
+        readonly fractionDigits: 2;
+    };
+    readonly BSD: {
+        readonly fractionDigits: 2;
+    };
+    readonly BTN: {
+        readonly fractionDigits: 2;
+    };
+    readonly BWP: {
+        readonly fractionDigits: 2;
+    };
+    readonly BYB: {
+        readonly fractionDigits: 0;
+    };
+    readonly BYN: {
+        readonly fractionDigits: 2;
+    };
+    readonly BYR: {
+        readonly fractionDigits: 0;
+    };
+    readonly BZD: {
+        readonly fractionDigits: 2;
+    };
+    readonly CAD: {
+        readonly fractionDigits: 2;
+    };
+    readonly CDF: {
+        readonly fractionDigits: 2;
+    };
+    readonly CHF: {
+        readonly fractionDigits: 2;
+    };
+    readonly CLF: {
+        readonly fractionDigits: 0;
+    };
+    readonly CLP: {
+        readonly fractionDigits: 0;
+    };
+    readonly CNY: {
+        readonly fractionDigits: 2;
+    };
+    readonly COP: {
+        readonly fractionDigits: 2;
+    };
+    readonly CRC: {
+        readonly fractionDigits: 2;
+    };
+    readonly CSD: {
+        readonly fractionDigits: 2;
+    };
+    readonly CUC: {
+        readonly fractionDigits: 2;
+    };
+    readonly CUP: {
+        readonly fractionDigits: 2;
+    };
+    readonly CVE: {
+        readonly fractionDigits: 2;
+    };
+    readonly CYP: {
+        readonly fractionDigits: 2;
+    };
+    readonly CZK: {
+        readonly fractionDigits: 2;
+    };
+    readonly DEM: {
+        readonly fractionDigits: 2;
+    };
+    readonly DJF: {
+        readonly fractionDigits: 0;
+    };
+    readonly DKK: {
+        readonly fractionDigits: 2;
+    };
+    readonly DOP: {
+        readonly fractionDigits: 2;
+    };
+    readonly DZD: {
+        readonly fractionDigits: 2;
+    };
+    readonly EEK: {
+        readonly fractionDigits: 2;
+    };
+    readonly EGP: {
+        readonly fractionDigits: 2;
+    };
+    readonly ERN: {
+        readonly fractionDigits: 2;
+    };
+    readonly ESP: {
+        readonly fractionDigits: 0;
+    };
+    readonly ETB: {
+        readonly fractionDigits: 2;
+    };
+    readonly EUR: {
+        readonly fractionDigits: 2;
+    };
+    readonly FIM: {
+        readonly fractionDigits: 2;
+    };
+    readonly FJD: {
+        readonly fractionDigits: 2;
+    };
+    readonly FKP: {
+        readonly fractionDigits: 2;
+    };
+    readonly FRF: {
+        readonly fractionDigits: 2;
+    };
+    readonly GBP: {
+        readonly fractionDigits: 2;
+    };
+    readonly GEL: {
+        readonly fractionDigits: 2;
+    };
+    readonly GHC: {
+        readonly fractionDigits: 2;
+    };
+    readonly GHS: {
+        readonly fractionDigits: 2;
+    };
+    readonly GIP: {
+        readonly fractionDigits: 2;
+    };
+    readonly GMD: {
+        readonly fractionDigits: 2;
+    };
+    readonly GNF: {
+        readonly fractionDigits: 0;
+    };
+    readonly GRD: {
+        readonly fractionDigits: 0;
+    };
+    readonly GTQ: {
+        readonly fractionDigits: 2;
+    };
+    readonly GWP: {
+        readonly fractionDigits: 2;
+    };
+    readonly GYD: {
+        readonly fractionDigits: 2;
+    };
+    readonly HKD: {
+        readonly fractionDigits: 2;
+    };
+    readonly HNL: {
+        readonly fractionDigits: 2;
+    };
+    readonly HRK: {
+        readonly fractionDigits: 2;
+    };
+    readonly HTG: {
+        readonly fractionDigits: 2;
+    };
+    readonly HUF: {
+        readonly fractionDigits: 2;
+    };
+    readonly IDR: {
+        readonly fractionDigits: 2;
+    };
+    readonly IEP: {
+        readonly fractionDigits: 2;
+    };
+    readonly ILS: {
+        readonly fractionDigits: 2;
+    };
+    readonly INR: {
+        readonly fractionDigits: 2;
+    };
+    readonly IQD: {
+        readonly fractionDigits: 3;
+    };
+    readonly IRR: {
+        readonly fractionDigits: 2;
+    };
+    readonly ISK: {
+        readonly fractionDigits: 0;
+    };
+    readonly ITL: {
+        readonly fractionDigits: 0;
+    };
+    readonly JMD: {
+        readonly fractionDigits: 2;
+    };
+    readonly JOD: {
+        readonly fractionDigits: 3;
+    };
+    readonly JPY: {
+        readonly fractionDigits: 0;
+    };
+    readonly KES: {
+        readonly fractionDigits: 2;
+    };
+    readonly KGS: {
+        readonly fractionDigits: 2;
+    };
+    readonly KHR: {
+        readonly fractionDigits: 2;
+    };
+    readonly KMF: {
+        readonly fractionDigits: 0;
+    };
+    readonly KPW: {
+        readonly fractionDigits: 2;
+    };
+    readonly KRW: {
+        readonly fractionDigits: 0;
+    };
+    readonly KWD: {
+        readonly fractionDigits: 3;
+    };
+    readonly KYD: {
+        readonly fractionDigits: 2;
+    };
+    readonly KZT: {
+        readonly fractionDigits: 2;
+    };
+    readonly LAK: {
+        readonly fractionDigits: 2;
+    };
+    readonly LBP: {
+        readonly fractionDigits: 2;
+    };
+    readonly LKR: {
+        readonly fractionDigits: 2;
+    };
+    readonly LRD: {
+        readonly fractionDigits: 2;
+    };
+    readonly LSL: {
+        readonly fractionDigits: 2;
+    };
+    readonly LTL: {
+        readonly fractionDigits: 2;
+    };
+    readonly LUF: {
+        readonly fractionDigits: 0;
+    };
+    readonly LVL: {
+        readonly fractionDigits: 2;
+    };
+    readonly LYD: {
+        readonly fractionDigits: 3;
+    };
+    readonly MAD: {
+        readonly fractionDigits: 2;
+    };
+    readonly MDL: {
+        readonly fractionDigits: 2;
+    };
+    readonly MGA: {
+        readonly fractionDigits: 2;
+    };
+    readonly MGF: {
+        readonly fractionDigits: 0;
+    };
+    readonly MKD: {
+        readonly fractionDigits: 2;
+    };
+    readonly MMK: {
+        readonly fractionDigits: 2;
+    };
+    readonly MNT: {
+        readonly fractionDigits: 2;
+    };
+    readonly MOP: {
+        readonly fractionDigits: 2;
+    };
+    readonly MRO: {
+        readonly fractionDigits: 2;
+    };
+    readonly MTL: {
+        readonly fractionDigits: 2;
+    };
+    readonly MUR: {
+        readonly fractionDigits: 2;
+    };
+    readonly MVR: {
+        readonly fractionDigits: 2;
+    };
+    readonly MWK: {
+        readonly fractionDigits: 2;
+    };
+    readonly MXN: {
+        readonly fractionDigits: 2;
+    };
+    readonly MXV: {
+        readonly fractionDigits: 2;
+    };
+    readonly MYR: {
+        readonly fractionDigits: 2;
+    };
+    readonly MZM: {
+        readonly fractionDigits: 2;
+    };
+    readonly MZN: {
+        readonly fractionDigits: 2;
+    };
+    readonly NAD: {
+        readonly fractionDigits: 2;
+    };
+    readonly NGN: {
+        readonly fractionDigits: 2;
+    };
+    readonly NIO: {
+        readonly fractionDigits: 2;
+    };
+    readonly NLG: {
+        readonly fractionDigits: 2;
+    };
+    readonly NOK: {
+        readonly fractionDigits: 2;
+    };
+    readonly NPR: {
+        readonly fractionDigits: 2;
+    };
+    readonly NZD: {
+        readonly fractionDigits: 2;
+    };
+    readonly OMR: {
+        readonly fractionDigits: 3;
+    };
+    readonly PAB: {
+        readonly fractionDigits: 2;
+    };
+    readonly PEN: {
+        readonly fractionDigits: 2;
+    };
+    readonly PGK: {
+        readonly fractionDigits: 2;
+    };
+    readonly PHP: {
+        readonly fractionDigits: 2;
+    };
+    readonly PKR: {
+        readonly fractionDigits: 2;
+    };
+    readonly PLN: {
+        readonly fractionDigits: 2;
+    };
+    readonly PTE: {
+        readonly fractionDigits: 0;
+    };
+    readonly PYG: {
+        readonly fractionDigits: 0;
+    };
+    readonly QAR: {
+        readonly fractionDigits: 2;
+    };
+    readonly ROL: {
+        readonly fractionDigits: 2;
+    };
+    readonly RON: {
+        readonly fractionDigits: 2;
+    };
+    readonly RSD: {
+        readonly fractionDigits: 2;
+    };
+    readonly RUB: {
+        readonly fractionDigits: 2;
+    };
+    readonly RUR: {
+        readonly fractionDigits: 2;
+    };
+    readonly RWF: {
+        readonly fractionDigits: 0;
+    };
+    readonly SAR: {
+        readonly fractionDigits: 2;
+    };
+    readonly SBD: {
+        readonly fractionDigits: 2;
+    };
+    readonly SCR: {
+        readonly fractionDigits: 2;
+    };
+    readonly SDD: {
+        readonly fractionDigits: 2;
+    };
+    readonly SDG: {
+        readonly fractionDigits: 2;
+    };
+    readonly SEK: {
+        readonly fractionDigits: 2;
+    };
+    readonly SGD: {
+        readonly fractionDigits: 2;
+    };
+    readonly SHP: {
+        readonly fractionDigits: 2;
+    };
+    readonly SIT: {
+        readonly fractionDigits: 2;
+    };
+    readonly SKK: {
+        readonly fractionDigits: 2;
+    };
+    readonly SLL: {
+        readonly fractionDigits: 2;
+    };
+    readonly SOS: {
+        readonly fractionDigits: 2;
+    };
+    readonly SRD: {
+        readonly fractionDigits: 2;
+    };
+    readonly SRG: {
+        readonly fractionDigits: 2;
+    };
+    readonly SSP: {
+        readonly fractionDigits: 2;
+    };
+    readonly STD: {
+        readonly fractionDigits: 2;
+    };
+    readonly SVC: {
+        readonly fractionDigits: 2;
+    };
+    readonly SYP: {
+        readonly fractionDigits: 2;
+    };
+    readonly SZL: {
+        readonly fractionDigits: 2;
+    };
+    readonly THB: {
+        readonly fractionDigits: 2;
+    };
+    readonly TJS: {
+        readonly fractionDigits: 2;
+    };
+    readonly TMM: {
+        readonly fractionDigits: 2;
+    };
+    readonly TMT: {
+        readonly fractionDigits: 2;
+    };
+    readonly TND: {
+        readonly fractionDigits: 3;
+    };
+    readonly TOP: {
+        readonly fractionDigits: 2;
+    };
+    readonly TPE: {
+        readonly fractionDigits: 0;
+    };
+    readonly TRL: {
+        readonly fractionDigits: 0;
+    };
+    readonly TRY: {
+        readonly fractionDigits: 2;
+    };
+    readonly TTD: {
+        readonly fractionDigits: 2;
+    };
+    readonly TWD: {
+        readonly fractionDigits: 2;
+    };
+    readonly TZS: {
+        readonly fractionDigits: 2;
+    };
+    readonly UAH: {
+        readonly fractionDigits: 2;
+    };
+    readonly UGX: {
+        readonly fractionDigits: 0;
+    };
+    readonly USD: {
+        readonly fractionDigits: 2;
+    };
+    readonly USN: {
+        readonly fractionDigits: 2;
+    };
+    readonly USS: {
+        readonly fractionDigits: 2;
+    };
+    readonly UYU: {
+        readonly fractionDigits: 2;
+    };
+    readonly UZS: {
+        readonly fractionDigits: 2;
+    };
+    readonly VEB: {
+        readonly fractionDigits: 2;
+    };
+    readonly VEF: {
+        readonly fractionDigits: 2;
+    };
+    readonly VND: {
+        readonly fractionDigits: 0;
+    };
+    readonly VUV: {
+        readonly fractionDigits: 0;
+    };
+    readonly WST: {
+        readonly fractionDigits: 2;
+    };
+    readonly XAF: {
+        readonly fractionDigits: 0;
+    };
+    readonly XAG: {
+        readonly fractionDigits: -1;
+    };
+    readonly XAU: {
+        readonly fractionDigits: -1;
+    };
+    readonly XBA: {
+        readonly fractionDigits: -1;
+    };
+    readonly XBB: {
+        readonly fractionDigits: -1;
+    };
+    readonly XBC: {
+        readonly fractionDigits: -1;
+    };
+    readonly XBD: {
+        readonly fractionDigits: -1;
+    };
+    readonly XCD: {
+        readonly fractionDigits: 2;
+    };
+    readonly XDR: {
+        readonly fractionDigits: -1;
+    };
+    readonly XFO: {
+        readonly fractionDigits: -1;
+    };
+    readonly XFU: {
+        readonly fractionDigits: -1;
+    };
+    readonly XOF: {
+        readonly fractionDigits: 0;
+    };
+    readonly XPD: {
+        readonly fractionDigits: -1;
+    };
+    readonly XPF: {
+        readonly fractionDigits: 0;
+    };
+    readonly XPT: {
+        readonly fractionDigits: -1;
+    };
+    readonly XSU: {
+        readonly fractionDigits: -1;
+    };
+    readonly XTS: {
+        readonly fractionDigits: -1;
+    };
+    readonly XUA: {
+        readonly fractionDigits: -1;
+    };
+    readonly XXX: {
+        readonly fractionDigits: -1;
+    };
+    readonly YER: {
+        readonly fractionDigits: 2;
+    };
+    readonly YUM: {
+        readonly fractionDigits: 2;
+    };
+    readonly ZAR: {
+        readonly fractionDigits: 2;
+    };
+    readonly ZMK: {
+        readonly fractionDigits: 2;
+    };
+    readonly ZMW: {
+        readonly fractionDigits: 2;
+    };
+    readonly ZWD: {
+        readonly fractionDigits: 2;
+    };
+    readonly ZWL: {
+        readonly fractionDigits: 2;
+    };
+    readonly ZWN: {
+        readonly fractionDigits: 2;
+    };
+    readonly ZWR: {
+        readonly fractionDigits: 2;
+    };
+};
+
+declare type ExcludedSlotProps = "asChild" | "onChange" | "onBlur" | "onFocus" | "id" | "name" | "value" | "step";
+
+/**
+ * # MoneyInput
+ *
+ * A specialized input component for entering monetary amounts with currency selection.
+ * Supports high precision values and automatic locale-based formatting.
+ *
+ * ## Usage
+ *
+ * ### Modern API (Recommended)
+ *
+ * Use the modern event handlers for better type safety and cleaner code:
+ *
+ * ```tsx
+ * function MyComponent() {
+ *   const [value, setValue] = useState<TValue>({
+ *     amount: "",
+ *     currencyCode: "USD",
+ *   });
+ *
+ *   return (
+ *     <MoneyInput
+ *       value={value}
+ *       currencies={["USD", "EUR", "GBP"]}
+ *       onValueChange={setValue} // Recommended: handles complete value changes
+ *       onAmountChange={(amount) => console.log("Amount:", amount)}
+ *       onCurrencyChange={(currency) => console.log("Currency:", currency)}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * ### Legacy API (Deprecated)
+ *
+ * For backward compatibility only - migrate to modern API when possible:
+ *
+ * ```tsx
+ * function LegacyComponent() {
+ *   const [value, setValue] = useState<TValue>({ amount: "", currencyCode: "USD" });
+ *
+ *   const handleChange = (event: TCustomEvent) => {
+ *     const { name, value } = event.target;
+ *     if (name?.endsWith(".amount")) {
+ *       setValue(prev => ({ ...prev, amount: value as string }));
+ *     } else if (name?.endsWith(".currencyCode")) {
+ *       setValue(prev => ({ ...prev, currencyCode: value as TCurrencyCode }));
+ *     }
+ *   };
+ *
+ *   return (
+ *     <MoneyInput
+ *       value={value}
+ *       currencies={["USD", "EUR"]}
+ *       onChange={handleChange} // Deprecated - use onValueChange instead
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * ## Features
+ *
+ * - **Type-safe currency handling** with TCurrencyCode enum
+ * - **High precision support** for values exceeding standard currency precision
+ * - **Automatic locale formatting** using React Aria NumberField
+ * - **Accessibility compliant** following WCAG 2.1 AA standards
+ * - **Dual API support** for backward compatibility and modern development
+ */
+export declare const MoneyInput: {
+    (props: MoneyInputProps): JSX.Element;
+    getAmountInputId(id?: string): string | undefined;
+    getCurrencyDropdownId(id?: string): string | undefined;
+    convertToMoneyValue: (value: TValue_2, locale: string) => TMoneyValue_2 | null;
+    parseMoneyValue: (moneyValue: TMoneyValue_2, locale: string) => TValue_2;
+    isEmpty: (formValue: TValue_2) => boolean;
+    isHighPrecision: (formValue: TValue_2, locale: string) => boolean;
+    displayName: string;
+};
+
+declare type MoneyInputProps = Omit<MoneyInputRootSlotProps, ExcludedSlotProps> & {
+    /**
+     * Used as HTML id property. An id is auto-generated when it is not specified.
+     */
+    id?: string;
+    /**
+     * The prefix used to create a HTML `name` property for the amount input field (`${name}.amount`) and the currency dropdown (`${name}.currencyCode`).
+     */
+    name?: string;
+    /**
+     * Value of the input. Consists of the currency code and an amount. `amount` is a string representing the amount. A dot has to be used as the decimal separator.
+     */
+    value: TValue;
+    /**
+     * List of possible currencies. When not provided or empty, the component renders a label with the value's currency instead of a dropdown.
+     */
+    currencies?: string[];
+    /**
+     * Called when input is blurred
+     */
+    onBlur?: (event: TCustomEvent) => void;
+    /**
+     * Called when input is focused
+     */
+    onFocus?: (event: TCustomEvent) => void;
+    /**
+     * Called with the event of the input or dropdown when either the currency or the amount have changed.
+     * @deprecated Use onValueChange, onAmountChange, or onCurrencyChange for better type safety and developer experience.
+     */
+    onChange?: (event: TCustomEvent) => void;
+    /**
+     * Modern API: Called when the complete value (amount + currency) changes.
+     * This is the recommended handler for most use cases.
+     */
+    onValueChange?: (value: TValue) => void;
+    /**
+     * Modern API: Called when only the amount changes.
+     * Use this for granular control over amount changes.
+     */
+    onAmountChange?: (amount: string) => void;
+    /**
+     * Modern API: Called when only the currency changes.
+     * Use this for granular control over currency changes.
+     */
+    onCurrencyChange?: (currencyCode: TCurrencyCode) => void;
+    /**
+     * Indicates that the input cannot be modified (e.g not authorized, or changes currently saving).
+     */
+    isDisabled?: boolean;
+    /**
+     * Indicates that the field is displaying read-only content
+     */
+    isReadOnly?: boolean;
+    /**
+     * Indicates that input has errors
+     */
+    isInvalid?: boolean;
+    /**
+     * Indicates that the field is required
+     */
+    isRequired?: boolean;
+    /**
+     * Shows high precision badge in case current value uses high precision.
+     */
+    hasHighPrecisionBadge?: boolean;
+    /**
+     * Indicates that the currency input cannot be modified.
+     */
+    isCurrencyInputDisabled?: boolean;
+    /**
+     * Placeholder text for the amount input
+     */
+    placeholder?: string;
+    /**
+     * Focus the input on initial render
+     */
+    autoFocus?: boolean;
+};
+
+declare type MoneyInputRecipeProps = {
+    /**
+     * Size variant of the money input
+     * @default "md"
+     */
+    size?: SlotRecipeProps<"moneyInput">["size"];
+};
+
+declare type MoneyInputRootSlotProps = HTMLChakraProps<"div", MoneyInputRecipeProps>;
+
+export declare type TCurrencyCode = keyof typeof currencies;
+
+export declare type TCustomEvent = {
+    target: {
+        id?: string;
+        name?: string;
+        value?: string | string[] | null;
+    };
+};
+
+declare type TMoneyConditionalProps = {
+    type: "highPrecision";
+    preciseAmount: number;
+} | {
+    type: "centPrecision";
+    preciseAmount?: never;
+};
+
+export declare type TMoneyValue = {
+    currencyCode: TCurrencyCode;
+    centAmount: number;
+    fractionDigits: number;
+} & TMoneyConditionalProps;
+
+export declare type TValue = {
+    amount: string;
+    currencyCode: TCurrencyCode | "";
+};
+
+export { }
+
+
+declare module "slate" {
+    interface CustomTypes {
+        Editor: BaseEditor & ReactEditor & HistoryEditor;
+        Element: CustomElement;
+        Text: CustomText;
+    }
+}