@uxf/core 11.126.0 → 11.127.0

package/README.md

@@ -88,6 +88,78 @@ cookie.set("cookie-name", "value", /* ttl in seconds (optional) */, /* options (
 cookie.delete("cookie-name", /* options (optional) */);
 ```
 
+## Money
+
+`Money` is the monetary value type used across the packages — the amount is a **string**, so it can carry
+more precision than a JS number holds.
+
+```tsx
+import { Currency, Money } from "@uxf/core/money";
+import { currencies } from "@uxf/core/money/currencies";
+import { getCurrencySymbol } from "@uxf/core/money/get-currency-symbol";
+
+const price: Money = { amount: "1000", currency: "CZK" };
+
+getCurrencySymbol("CZK"); /* returns "Kč" */
+```
+
+### normalizeMoneyAmount
+
+Rewrites an amount into its canonical decimal form. Returns `null` when the input does not describe a
+decimal number.
+
+```tsx
+import { normalizeMoneyAmount } from "@uxf/core/money/normalize-money";
+
+normalizeMoneyAmount("1000.00"); /* returns "1000" */
+normalizeMoneyAmount("15.50"); /* returns "15.5" */
+normalizeMoneyAmount("015"); /* returns "15" */
+normalizeMoneyAmount(".5"); /* returns "0.5" */
+normalizeMoneyAmount("+15"); /* returns "15" */
+normalizeMoneyAmount("-0.00"); /* returns "0" */
+normalizeMoneyAmount("abc"); /* returns null */
+normalizeMoneyAmount("1e5"); /* returns null - exponent notation is not a decimal amount */
+```
+
+The rewriting is textual, never a `Number()` round-trip, so an amount a double cannot hold exactly
+survives intact: `"9007199254740993"` and `"100000000000000000000000"` come back unchanged rather than as
+a different number or as `"1e+23"`. This is also why exponent notation is rejected instead of expanded.
+
+Related but **not** a substitute: [`trimTrailingZeros`](#trimtrailingzeros) only strips trailing zeros
+from a fractional part and leaves leading zeros, signs and `".5"` alone.
+
+### normalizeMoney
+
+Normalizes a whole `Money` value: the amount goes through `normalizeMoneyAmount` and any extra properties
+(a GraphQL `__typename`, for instance) are dropped. Returns `null` for a nullish value or an amount that
+is not a number.
+
+```tsx
+import { normalizeMoney } from "@uxf/core/money/normalize-money";
+
+normalizeMoney({ amount: "1000.00", currency: "CZK" }); /* returns { amount: "1000", currency: "CZK" } */
+normalizeMoney({ __typename: "Money", amount: "1000", currency: "CZK" }); /* drops __typename */
+normalizeMoney({ amount: "", currency: "CZK" }); /* returns null */
+normalizeMoney(null); /* returns null */
+```
+
+**Why you need this in a form.** react-hook-form decides dirtiness with its own `deepEqual`, which
+compares `Object.keys().length` first and then every leaf. A `Money` field therefore reads as dirty as
+soon as its _shape_ drifts from the default value — an extra `__typename`, or an amount retyped as
+`"1000.00"` where the default says `"1000"` — even though the visible value is identical, and the
+unsaved-changes bar never goes away.
+
+A component can only make what it **emits** canonical; the default values are built by the consuming
+app's mappers, which no component can reach. So run both sides through the same normalizer:
+
+```tsx
+const formApi = useForm<FormData>({
+    defaultValues: { price: normalizeMoney(data.price) },
+});
+```
+
+[`@uxf/form/money-input`](../form/money-input/README.md) already normalizes what it emits, on blur.
+
 ## Utils
 
 ### adjustTextareaHeight
@@ -597,6 +669,33 @@ nonEmptyStringOrNull("test"); /* returns "test" */
 nonEmptyStringOrNull(" "); /* returns " " - non-empty string */
 ```
 
+## normalizeSelectableIds
+
+Sorts a multi-choice value into a canonical order. Returns a new array (the input is never mutated), or
+`null` for a nullish value.
+
+```tsx
+import { normalizeSelectableIds } from "@uxf/core/utils/normalize-selectable-ids";
+
+normalizeSelectableIds([3, 1, 2]); /* returns [1, 2, 3] */
+normalizeSelectableIds(["b", "a"]); /* returns ["a", "b"] */
+normalizeSelectableIds(null); /* returns null */
+```
+
+Multi-choice inputs treat their value as a set but emit it as an array whose order follows the order the
+user clicked, and react-hook-form compares arrays index by index — so unticking an option and ticking it
+again leaves a semantically unchanged form reading as dirty. Run the form's `defaultValues` through this
+too, so both sides agree:
+
+```tsx
+const formApi = useForm<FormData>({
+    defaultValues: { tags: normalizeSelectableIds(data.tagIds) },
+});
+```
+
+[`@uxf/ui/checkbox-list`](../ui/checkbox-list/README.md) and
+[`@uxf/ui/multi-select`](../ui/multi-select/README.md) already normalize what they emit.
+
 ## nullishToEmptyString
 
 Converts `null` or `undefined` values to an empty string, leaving all other strings unchanged. Useful for safely displaying nullable string values in UI components.

package/money/normalize-money.d.ts

@@ -0,0 +1,20 @@
+import { Money } from "@uxf/core/money";
+/**
+ * Rewrites an amount into its canonical decimal form: `"1000.00"` and `"015"` both become `"1000"` and
+ * `"15"`. Returns `null` when the input does not describe a decimal number.
+ *
+ * The rewriting is textual on purpose. `Money.amount` is a string so that an amount can carry more
+ * precision than a double holds, and a `Number()` round-trip would throw that away — `"9007199254740993"`
+ * comes back as a different number and `"100000000000000000000000"` comes back as `"1e+23"`.
+ */
+export declare function normalizeMoneyAmount(amount: string): string | null;
+/**
+ * Normalizes a money value into a canonical shape: the amount is rewritten by `normalizeMoneyAmount` and
+ * any extra properties (a GraphQL `__typename`, for instance) are dropped.
+ *
+ * `Money` is an object, and react-hook-form compares objects by key count and then leaf by leaf, so a
+ * default value carrying an extra key — or an amount typed as `"1000.00"` where the default says
+ * `"1000"` — reads as dirty forever. Run both the form's default values and the emitted value through
+ * this function and the comparison lines up.
+ */
+export declare function normalizeMoney(value: Money | null | undefined): Money | null;

package/money/normalize-money.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeMoneyAmount = normalizeMoneyAmount;
+exports.normalizeMoney = normalizeMoney;
+const is_empty_1 = require("@uxf/core/utils/is-empty");
+const is_nil_1 = require("@uxf/core/utils/is-nil");
+// An optional sign, then digits and/or a fractional part. Deliberately no exponent notation: an amount
+// is a plain decimal string everywhere in this stack, and accepting `1e+23` would mean expanding it,
+// which is the round-trip through a double that this function exists to avoid.
+const DECIMAL_AMOUNT = /^([+-]?)(\d*)(?:\.(\d*))?$/;
+/**
+ * Rewrites an amount into its canonical decimal form: `"1000.00"` and `"015"` both become `"1000"` and
+ * `"15"`. Returns `null` when the input does not describe a decimal number.
+ *
+ * The rewriting is textual on purpose. `Money.amount` is a string so that an amount can carry more
+ * precision than a double holds, and a `Number()` round-trip would throw that away — `"9007199254740993"`
+ * comes back as a different number and `"100000000000000000000000"` comes back as `"1e+23"`.
+ */
+function normalizeMoneyAmount(amount) {
+    const match = DECIMAL_AMOUNT.exec(amount.trim());
+    if ((0, is_nil_1.isNil)(match)) {
+        return null;
+    }
+    const [, sign, integerDigits, fractionDigits = ""] = match;
+    // The pattern matches an empty string and a bare "." as well, neither of which is a number.
+    if ((0, is_empty_1.isEmpty)(integerDigits) && (0, is_empty_1.isEmpty)(fractionDigits)) {
+        return null;
+    }
+    const integer = integerDigits.replace(/^0+(?=\d)/, "") || "0";
+    const fraction = fractionDigits.replace(/0+$/, "");
+    const digits = (0, is_empty_1.isEmpty)(fraction) ? integer : `${integer}.${fraction}`;
+    return sign === "-" && digits !== "0" ? `-${digits}` : digits;
+}
+/**
+ * Normalizes a money value into a canonical shape: the amount is rewritten by `normalizeMoneyAmount` and
+ * any extra properties (a GraphQL `__typename`, for instance) are dropped.
+ *
+ * `Money` is an object, and react-hook-form compares objects by key count and then leaf by leaf, so a
+ * default value carrying an extra key — or an amount typed as `"1000.00"` where the default says
+ * `"1000"` — reads as dirty forever. Run both the form's default values and the emitted value through
+ * this function and the comparison lines up.
+ */
+function normalizeMoney(value) {
+    if ((0, is_nil_1.isNil)(value)) {
+        return null;
+    }
+    const amount = normalizeMoneyAmount(value.amount);
+    return (0, is_nil_1.isNil)(amount) ? null : { amount, currency: value.currency };
+}

package/money/normalize-money.test.d.ts

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

package/money/normalize-money.test.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const normalize_money_1 = require("./normalize-money");
+test("normalizes an amount into its canonical decimal form", () => {
+    expect((0, normalize_money_1.normalizeMoneyAmount)("1000")).toBe("1000");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("1000.00")).toBe("1000");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("15.50")).toBe("15.5");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("015")).toBe("15");
+    expect((0, normalize_money_1.normalizeMoneyAmount)(".5")).toBe("0.5");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("-0")).toBe("0");
+    expect((0, normalize_money_1.normalizeMoneyAmount)(" 12 ")).toBe("12");
+});
+test("returns null for an amount that is not a decimal number", () => {
+    expect((0, normalize_money_1.normalizeMoneyAmount)("")).toBeNull();
+    expect((0, normalize_money_1.normalizeMoneyAmount)("   ")).toBeNull();
+    expect((0, normalize_money_1.normalizeMoneyAmount)("abc")).toBeNull();
+    expect((0, normalize_money_1.normalizeMoneyAmount)(".")).toBeNull();
+    expect((0, normalize_money_1.normalizeMoneyAmount)("1 000")).toBeNull();
+    expect((0, normalize_money_1.normalizeMoneyAmount)("1e5")).toBeNull();
+    expect((0, normalize_money_1.normalizeMoneyAmount)("Infinity")).toBeNull();
+});
+test("keeps an amount a double cannot hold exactly", () => {
+    // The whole reason `Money.amount` is a string: a `Number()` round-trip returns "9007199254740992"
+    // for the first one and "1e+23" for the second.
+    expect((0, normalize_money_1.normalizeMoneyAmount)("9007199254740993")).toBe("9007199254740993");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("100000000000000000000000")).toBe("100000000000000000000000");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("0.0000001")).toBe("0.0000001");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("1.005000")).toBe("1.005");
+});
+test("drops a redundant sign", () => {
+    expect((0, normalize_money_1.normalizeMoneyAmount)("+15")).toBe("15");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("-15.50")).toBe("-15.5");
+    expect((0, normalize_money_1.normalizeMoneyAmount)("-0.00")).toBe("0");
+});
+test("normalizing an amount is idempotent", () => {
+    var _a, _b;
+    expect((0, normalize_money_1.normalizeMoneyAmount)((_a = (0, normalize_money_1.normalizeMoneyAmount)("1000.00")) !== null && _a !== void 0 ? _a : "")).toBe("1000");
+    expect((0, normalize_money_1.normalizeMoneyAmount)((_b = (0, normalize_money_1.normalizeMoneyAmount)("-000.5000")) !== null && _b !== void 0 ? _b : "")).toBe("-0.5");
+});
+test("keeps the currency and drops extra properties", () => {
+    var _a;
+    const fromApi = { __typename: "Money", amount: "1000.00", currency: "CZK" };
+    expect((0, normalize_money_1.normalizeMoney)(fromApi)).toEqual({ amount: "1000", currency: "CZK" });
+    expect(Object.keys((_a = (0, normalize_money_1.normalizeMoney)(fromApi)) !== null && _a !== void 0 ? _a : {})).toEqual(["amount", "currency"]);
+});
+test("returns null for an empty value", () => {
+    expect((0, normalize_money_1.normalizeMoney)(null)).toBeNull();
+    expect((0, normalize_money_1.normalizeMoney)(undefined)).toBeNull();
+    expect((0, normalize_money_1.normalizeMoney)({ amount: "", currency: "CZK" })).toBeNull();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uxf/core",
-    "version": "11.126.0",
+    "version": "11.127.0",
     "description": "UXF Core",
     "author": "Petr Vejvoda <vejvoda@uxf.cz>",
     "homepage": "https://gitlab.com/uxf-npm/core#readme",

package/utils/normalize-selectable-ids.d.ts

@@ -0,0 +1,11 @@
+import { SelectableId } from "@uxf/core/types";
+/**
+ * Sorts a multi-choice value into a canonical order.
+ *
+ * Multi-choice inputs treat their value as a set, but they emit it as an array whose order depends on
+ * the order the user clicked. react-hook-form compares arrays index by index, so a value that is
+ * semantically unchanged still reads as dirty once an item has been unticked and ticked again. Run both
+ * the form's default values and the emitted value through this function and the comparison lines up.
+ */
+export declare function normalizeSelectableIds<T extends SelectableId>(value: T[]): T[];
+export declare function normalizeSelectableIds<T extends SelectableId>(value: T[] | null | undefined): T[] | null;

package/utils/normalize-selectable-ids.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSelectableIds = normalizeSelectableIds;
+const is_nil_1 = require("@uxf/core/utils/is-nil");
+function compareIds(a, b) {
+    if (typeof a === "number" && typeof b === "number") {
+        return a - b;
+    }
+    return String(a) < String(b) ? -1 : 1;
+}
+function normalizeSelectableIds(value) {
+    if ((0, is_nil_1.isNil)(value)) {
+        return null;
+    }
+    return [...value].sort(compareIds);
+}

package/utils/normalize-selectable-ids.test.d.ts

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

package/utils/normalize-selectable-ids.test.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const normalize_selectable_ids_1 = require("./normalize-selectable-ids");
+test("sorts numeric ids numerically", () => {
+    expect((0, normalize_selectable_ids_1.normalizeSelectableIds)([10, 9, 100])).toEqual([9, 10, 100]);
+});
+test("sorts string ids", () => {
+    expect((0, normalize_selectable_ids_1.normalizeSelectableIds)(["b", "c", "a"])).toEqual(["a", "b", "c"]);
+});
+test("does not depend on the order the items were picked", () => {
+    expect((0, normalize_selectable_ids_1.normalizeSelectableIds)([1, 3, 2])).toEqual((0, normalize_selectable_ids_1.normalizeSelectableIds)([3, 2, 1]));
+});
+test("is idempotent", () => {
+    expect((0, normalize_selectable_ids_1.normalizeSelectableIds)((0, normalize_selectable_ids_1.normalizeSelectableIds)([3, 1, 2]))).toEqual([1, 2, 3]);
+});
+test("does not mutate the input", () => {
+    const value = [3, 1, 2];
+    (0, normalize_selectable_ids_1.normalizeSelectableIds)(value);
+    expect(value).toEqual([3, 1, 2]);
+});
+test("keeps an empty value", () => {
+    expect((0, normalize_selectable_ids_1.normalizeSelectableIds)(null)).toBeNull();
+    expect((0, normalize_selectable_ids_1.normalizeSelectableIds)(undefined)).toBeNull();
+    expect((0, normalize_selectable_ids_1.normalizeSelectableIds)([])).toEqual([]);
+});