@uxf/localize 11.125.0 → 11.126.0

package/README.md

@@ -169,6 +169,7 @@ const formatNumber = useFormatNumber();
 
 formatNumber(2000.78); // 2 001         (default precision 0)
 formatNumber(2000.78, { precision: 2 }); // 2 000,78
+formatNumber(2000, { showPlusSign: true }); // +2 000        (+ only on positive values)
 
 <FormatNumber value={2000.78} />;
 ```
@@ -219,6 +220,7 @@ formatMoney({ amount: "2000.78", currency: "USD" }); // 2 001 $
 formatMoney({ amount: "2000.78", currency: "CZK" }, { precision: 1 }); // 2 000,8 Kč
 formatMoney({ amount: "2000.78", currency: "CZK" }, { precision: 1, preferIsoCode: true }); // 2 000,8 CZK
 formatMoney({ amount: "2000.78", currency: "CZK" }, { precision: 1, hideSymbol: true }); // 2 000,8
+formatMoney({ amount: "500", currency: "CZK" }, { showPlusSign: true }); // +500 Kč      (+ only on positive values)
 
 <FormatMoney money={{ amount: "2000.78", currency: "CZK" }} />;
 ```
@@ -236,6 +238,7 @@ formatPercentage(0.782); // 78 %          (default precision 0)
 formatPercentage(0.782, null, { precision: 2 }); // 78,20 %
 formatPercentage(0.782, "up"); // 79 %
 formatPercentage(0.788, "down"); // 78 %
+formatPercentage(0.5, null, { showPlusSign: true }); // +50 %       (+ only on positive values)
 
 <FormatPercentage roundingType="up" value={0.782} />;
 ```
@@ -268,25 +271,25 @@ createLocalize<DT extends string = DateTimes, T extends string = Times, Locales
 
 Returns an object with the following members:
 
-| Member | Signature | Notes |
-| --- | --- | --- |
-| `LocalizeProvider` | `Provider<string>` | React context provider; `value` is the active locale key. |
-| `useLocaleConfig` | `() => LocalizeConfig<DT, T>` | Returns the config for the current locale. |
-| `formatNumber` | `(locale, value, options?) => string` | `options: { precision? }`. |
-| `useFormatNumber` | `() => (value, options?) => string` | Locale from context. |
-| `FormatNumber` | `FC<{ value; options? }>` | |
-| `formatMoney` | `(locale, money, options?) => string` | `options: { hideSymbol?, precision?, preferIsoCode? }`. |
-| `useFormatMoney` | `() => (money, options?) => string` | Locale from context. |
-| `FormatMoney` | `FC<{ money; options? }>` | |
-| `formatPercentage` | `(locale, value, roundingType?, options?) => string` | `roundingType: "nearest" \| "up" \| "down" \| null`. |
-| `useFormatPercentage` | `() => (value, roundingType?, options?) => string` | Locale from context. |
-| `FormatPercentage` | `FC<{ value; roundingType?; options? }>` | |
-| `formatDateTime` | `(locale, value, format, timeZone?) => string` | `value: DateValue`; default `timeZone` is `Europe/Prague`. |
-| `useFormatDateTime` | `() => (value, format) => string` | No `timeZone` param (fixed to default). |
-| `FormatDateTime` | `FC<{ value; format; timeZone? }>` | |
-| `formatTime` | `(locale, value, format) => string` | `value: TimeString`. |
-| `useFormatTime` | `() => (value, format) => string` | Locale from context. |
-| `FormatTime` | `FC<{ value; format }>` | |
+| Member                | Signature                                            | Notes                                                                                          |
+| --------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `LocalizeProvider`    | `Provider<string>`                                   | React context provider; `value` is the active locale key.                                      |
+| `useLocaleConfig`     | `() => LocalizeConfig<DT, T>`                        | Returns the config for the current locale.                                                     |
+| `formatNumber`        | `(locale, value, options?) => string`                | `options: { precision?, showPlusSign? }`.                                                      |
+| `useFormatNumber`     | `() => (value, options?) => string`                  | Locale from context.                                                                           |
+| `FormatNumber`        | `FC<{ value; options? }>`                            |                                                                                                |
+| `formatMoney`         | `(locale, money, options?) => string`                | `options: { hideSymbol?, precision?, preferIsoCode?, showPlusSign? }`.                         |
+| `useFormatMoney`      | `() => (money, options?) => string`                  | Locale from context.                                                                           |
+| `FormatMoney`         | `FC<{ money; options? }>`                            |                                                                                                |
+| `formatPercentage`    | `(locale, value, roundingType?, options?) => string` | `roundingType: "nearest" \| "up" \| "down" \| null`; `options: { precision?, showPlusSign? }`. |
+| `useFormatPercentage` | `() => (value, roundingType?, options?) => string`   | Locale from context.                                                                           |
+| `FormatPercentage`    | `FC<{ value; roundingType?; options? }>`             |                                                                                                |
+| `formatDateTime`      | `(locale, value, format, timeZone?) => string`       | `value: DateValue`; default `timeZone` is `Europe/Prague`.                                     |
+| `useFormatDateTime`   | `() => (value, format) => string`                    | No `timeZone` param (fixed to default).                                                        |
+| `FormatDateTime`      | `FC<{ value; format; timeZone? }>`                   |                                                                                                |
+| `formatTime`          | `(locale, value, format) => string`                  | `value: TimeString`.                                                                           |
+| `useFormatTime`       | `() => (value, format) => string`                    | Locale from context.                                                                           |
+| `FormatTime`          | `FC<{ value; format }>`                              |                                                                                                |
 
 ### Exported types
 
@@ -305,6 +308,7 @@ Returns an object with the following members:
 - **Time zone defaults to `Europe/Prague`** for date/time formatting. The `useFormatDateTime` hook is fixed to that default; to override, use the standalone `formatDateTime(locale, value, format, timeZone)` or the `FormatDateTime` component's `timeZone` prop.
 - **Date-only strings** (`"YYYY-MM-DD"`) are parsed as midnight in the target time zone, while `Date` instances represent a concrete instant and are shifted into that zone — the same wall-clock string can render differently depending on the input form.
 - **Currency patterns** use currency.js placeholders: `#` = amount, `!` = symbol. Built-in defaults exist for `EUR` and `USD`; `specialCases` in the config override per currency; otherwise a plain `# <symbol>` pattern is used, and `preferIsoCode` forces the ISO code instead of the symbol.
+- **`showPlusSign` only adds `+`** to a positive, non-zero **final** value (e.g. `+500 Kč`, `+50 %`). It never touches the negative sign — `-` is always shown regardless (handled by currency.js `negativePattern`) — and a value that rounds to `0` stays unsigned. Matches `Intl.NumberFormat`'s `signDisplay: "exceptZero"`.
 - **Separators are non-breaking spaces** in some locales (e.g. `cs`), so `"2 001"` contains ` `, not a regular space.
 
 ## Links

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/localize",
-    "version": "11.125.0",
+    "version": "11.126.0",
     "description": "",
     "main": "index.js",
     "scripts": {
@@ -19,8 +19,8 @@
         "currency.js": "2.0.4"
     },
     "peerDependencies": {
-        "@uxf/core": "11.124.0",
-        "@uxf/core-react": "11.125.0",
+        "@uxf/core": "11.126.0",
+        "@uxf/core-react": "11.126.0",
         "dayjs": "^1.11.21",
         "react": ">=18.2.0",
         "react-dom": ">=18.2.0"
@@ -28,8 +28,8 @@
     "devDependencies": {
         "@types/react": "18.3.31",
         "@types/react-dom": "18.3.7",
-        "@uxf/core": "11.124.0",
-        "@uxf/core-react": "11.125.0",
+        "@uxf/core": "11.126.0",
+        "@uxf/core-react": "11.126.0",
         "dayjs": "^1.11.21",
         "react": "18.3.1",
         "react-dom": "18.3.1"

package/src/format-money/format-money.js

@@ -9,6 +9,7 @@ const empty_object_1 = require("@uxf/core/constants/empty-object");
 const currency_js_1 = __importDefault(require("currency.js"));
 const react_1 = require("react");
 const context_1 = require("../context/context");
+const apply_sign_to_pattern_1 = require("../utils/apply-sign-to-pattern");
 const curry_1 = require("../utils/curry");
 const money_defaults_1 = require("../utils/money-defaults");
 const defaultPatterns = {
@@ -32,14 +33,17 @@ function createFormatMoney(localizeConfigs) {
             : !(options === null || options === void 0 ? void 0 : options.preferIsoCode)
                 ? currentPatterns
                 : defaultPatterns;
+        const amount = (0, currency_js_1.default)(money.amount, { precision });
+        const pattern = (0, apply_sign_to_pattern_1._applySignToPattern)(patterns.pattern, amount.value, options === null || options === void 0 ? void 0 : options.showPlusSign);
         const formatOptions = {
             ...patterns,
+            pattern,
             decimal: config.decimalSeparator,
             separator: config.thousandsSeparator,
             precision,
             symbol,
         };
-        return (0, currency_js_1.default)(money.amount, { precision }).format(formatOptions);
+        return amount.format(formatOptions);
     };
 }
 function createUseFormatMoney(localizeConfigs) {

package/src/format-money/format-money.test.js

@@ -28,4 +28,11 @@ describe("money formatter", function () {
         expect(formatMoneyWithLocales("en", { amount: "2000.78", currency: "USD" }, { precision: 1, preferIsoCode: true })).toBe("2,000.8\xa0USD");
         expect(formatMoneyWithLocales("en", { amount: "2000.78", currency: "USD" }, { precision: 1, hideSymbol: true })).toBe("2,000.8");
     });
+    it("format money with sign", function () {
+        expect(formatMoneyWithLocales("cs", { amount: "500", currency: "CZK" }, { showPlusSign: true })).toBe("+500\xa0Kč");
+        expect(formatMoneyWithLocales("cs", { amount: "-500", currency: "CZK" }, { showPlusSign: true })).toBe("-500\xa0Kč");
+        expect(formatMoneyWithLocales("cs", { amount: "0", currency: "CZK" }, { showPlusSign: true })).toBe("0\xa0Kč");
+        expect(formatMoneyWithLocales("cs", { amount: "500", currency: "CZK" }, { showPlusSign: true, hideSymbol: true })).toBe("+500");
+        expect(formatMoneyWithLocales("cs", { amount: "500", currency: "CZK" }, { showPlusSign: true, preferIsoCode: true })).toBe("+500\xa0CZK");
+    });
 });

package/src/format-number/format-number.js

@@ -8,14 +8,17 @@ exports.createUseFormatNumber = createUseFormatNumber;
 const currency_js_1 = __importDefault(require("currency.js"));
 const react_1 = require("react");
 const context_1 = require("../context/context");
+const apply_sign_to_pattern_1 = require("../utils/apply-sign-to-pattern");
 const curry_1 = require("../utils/curry");
 const map_options_1 = require("../utils/map-options");
 function createFormatNumber(localizeConfigs) {
     return (locale, value, options) => {
         var _a;
         const precision = (_a = options === null || options === void 0 ? void 0 : options.precision) !== null && _a !== void 0 ? _a : 0;
-        const formatOptions = { ...(0, map_options_1._mapOptions)(localizeConfigs[locale].number), precision };
-        return (0, currency_js_1.default)(value, { precision }).format(formatOptions);
+        const amount = (0, currency_js_1.default)(value, { precision });
+        const base = (0, map_options_1._mapOptions)(localizeConfigs[locale].number);
+        const pattern = (0, apply_sign_to_pattern_1._applySignToPattern)(base.pattern, amount.value, options === null || options === void 0 ? void 0 : options.showPlusSign);
+        return amount.format({ ...base, pattern, precision });
     };
 }
 function createUseFormatNumber(localizeConfigs) {

package/src/format-number/format-number.test.js

@@ -16,4 +16,11 @@ describe("number formatter", function () {
         expect(formatNumberWithLocales("en", 2000.78)).toBe("2,001");
         expect(formatNumberWithLocales("en", 2000.78, { precision: 2 })).toBe("2,000.78");
     });
+    it("format number with sign", function () {
+        expect(formatNumberWithLocales("cs", 2000, { showPlusSign: true })).toBe("+2\xa0000");
+        expect(formatNumberWithLocales("cs", -2000, { showPlusSign: true })).toBe("-2\xa0000");
+        expect(formatNumberWithLocales("cs", 0, { showPlusSign: true })).toBe("0");
+        expect(formatNumberWithLocales("cs", 0.4, { showPlusSign: true })).toBe("0");
+        expect(formatNumberWithLocales("cs", 0.04, { showPlusSign: true, precision: 2 })).toBe("+0,04");
+    });
 });

package/src/format-percentage/format-percentage.test.js

@@ -22,4 +22,9 @@ describe("percentage formatter", function () {
         expect(formatPercentageWithLocales("en", 0.782, "up")).toBe("79\xa0%");
         expect(formatPercentageWithLocales("en", 0.788, "down")).toBe("78\xa0%");
     });
+    it("format percentage with sign", function () {
+        expect(formatPercentageWithLocales("cs", 0.5, null, { showPlusSign: true })).toBe("+50\xa0%");
+        expect(formatPercentageWithLocales("cs", -0.5, null, { showPlusSign: true })).toBe("-50\xa0%");
+        expect(formatPercentageWithLocales("cs", 0, null, { showPlusSign: true })).toBe("0\xa0%");
+    });
 });

package/src/types.d.ts

@@ -4,6 +4,7 @@ import { FC, Provider } from "react";
 import { TimeZone as CoreTimeZone } from "./utils/time-zone";
 export type FormatNumberOptions = {
     precision?: number;
+    showPlusSign?: boolean;
 };
 export type FormatNumberFunction<Locales extends string> = (locale: Locales, value: number, options?: FormatNumberOptions) => string;
 export type UseFormatNumberFunction = () => (value: number, options?: FormatNumberOptions) => string;
@@ -21,6 +22,7 @@ export type FormatMoneyOptions = {
     hideSymbol?: boolean;
     precision?: number;
     preferIsoCode?: boolean;
+    showPlusSign?: boolean;
 };
 export type FormatMoneyFunction<Locales extends string> = (locale: Locales, money: Money, options?: FormatMoneyOptions) => string;
 export type UseFormatMoneyFunction = () => (money: Money, options?: FormatMoneyOptions) => string;
@@ -31,6 +33,7 @@ export type FormatMoneyComponent = FC<{
 export type RoundingType = "nearest" | "up" | "down";
 export type FormatPercentageOptions = {
     precision?: number;
+    showPlusSign?: boolean;
 };
 export type FormatPercentageFunction<Locales extends string> = (locale: Locales, value: number, roundingType?: RoundingType | null, options?: FormatPercentageOptions) => string;
 export type UseFormatPercentageFunction = () => (value: number, roundingType?: RoundingType | null, options?: FormatPercentageOptions) => string;

package/src/utils/apply-sign-to-pattern.d.ts

@@ -0,0 +1 @@
+export declare const _applySignToPattern: (pattern: string | undefined, value: number, showPlusSign?: boolean) => string | undefined;

package/src/utils/apply-sign-to-pattern.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._applySignToPattern = void 0;
+const _applySignToPattern = (pattern, value, showPlusSign) => (pattern !== undefined && showPlusSign && value > 0 ? `+${pattern}` : pattern);
+exports._applySignToPattern = _applySignToPattern;

package/src/utils/apply-sign-to-pattern.test.d.ts

@@ -0,0 +1 @@
+export {};

package/src/utils/apply-sign-to-pattern.test.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const apply_sign_to_pattern_1 = require("./apply-sign-to-pattern");
+describe("_applySignToPattern", () => {
+    it("prepends + to a positive value when showPlusSign is enabled", () => {
+        expect((0, apply_sign_to_pattern_1._applySignToPattern)("#", 500, true)).toBe("+#");
+        expect((0, apply_sign_to_pattern_1._applySignToPattern)("#\xa0!", 500, true)).toBe("+#\xa0!");
+    });
+    it("does not touch zero or negative values", () => {
+        expect((0, apply_sign_to_pattern_1._applySignToPattern)("#", 0, true)).toBe("#");
+        expect((0, apply_sign_to_pattern_1._applySignToPattern)("#", -500, true)).toBe("#");
+    });
+    it("returns the pattern unchanged when showPlusSign is falsy", () => {
+        expect((0, apply_sign_to_pattern_1._applySignToPattern)("#", 500)).toBe("#");
+        expect((0, apply_sign_to_pattern_1._applySignToPattern)("#", 500, false)).toBe("#");
+    });
+});