@uxf/core 11.124.0 → 11.127.0

package/README.md

@@ -3,24 +3,26 @@
 ## Constants
 
 - common modifier classnames for interactive elements (eg. `CLASSES.IS_HOVERABLE` for is-hoverable classname)
-  - `focus-visible`
-  - `is-active`
-  - `is-busy`
-  - `is-disabled`
-  - `is-focused`
-  - `is-hoverable`
-  - `is-hovered`
-  - `is-invalid`
-  - `is-loading`
-  - `is-not-hoverable`
-  - `is-readonly`
-  - `is-required`
-  - `is-selected`
+    - `focus-visible`
+    - `is-active`
+    - `is-busy`
+    - `is-disabled`
+    - `is-focused`
+    - `is-hoverable`
+    - `is-hovered`
+    - `is-invalid`
+    - `is-loading`
+    - `is-not-hoverable`
+    - `is-readonly`
+    - `is-required`
+    - `is-selected`
 
 ## Resizer
+
 !!! Required [@uxf/resizer](https://www.npmjs.com/package/@uxf/resizer) version `>= 2.3.2` which supported `quality` parameter.
 
 ### Config
+
 ```json
 [
     {
@@ -37,19 +39,19 @@
 ### Usage for generated images
 
 ```tsx
-import {resizerImageUrl} from "@uxf/core/utils/resizer";
+import { resizerImageUrl } from "@uxf/core/utils/resizer";
 
-<img src={resizerImageUrl(file, width, height, params)}/>
+<img src={resizerImageUrl(file, width, height, params)} />;
 ```
 
 ### Usage for static images
 
 ```tsx
-import {resizerImageUrl} from "@uxf/core/utils/resizer";
+import { resizerImageUrl } from "@uxf/core/utils/resizer";
 
 import staticImage from "./path/to/static-image.png";
 
-<img src={resizerImageUrl(staticImage, width, height, params)}/>
+<img src={resizerImageUrl(staticImage, width, height, params)} />;
 ```
 
 ## QR code generator
@@ -86,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
@@ -93,43 +167,49 @@ cookie.delete("cookie-name", /* options (optional) */);
 Dynamically adjusts the height of a `<textarea>` based on its content and an optional number of rows.
 
 #### Parameters
+
 - **`element`**: The `<textarea>` to adjust.
 - **`rows`** (optional): Minimum visible rows. Default is `4`.
 
 #### Behavior
+
 - Leverages MutationObserver API to measure content height.
 - Adjusts height to fit content or the minimum height based on the `rows` parameter, calculated using `line-height` and `font-size`.
 
 #### Usage
+
 ```typescript
 adjustTextareaHeight(textarea); // Adjusts height (min 4 rows)
 adjustTextareaHeight(textarea, 6); // With 6-row minimum
-``` 
+```
+
 In React component:
+
 ```tsx
 import { useIsomorphicLayoutEffect } from "@uxf/core-react/hooks/use-isomorphic-layout-effect";
 import { isNotNil } from "@uxf/core/utils/is-not-nil";
 
 useIsomorphicLayoutEffect(() => {
-  const textarea = textareaRef.current;
-
-  if (isNotNil(textarea)) {
-      return;
-  }
-  
-  const cleanup = adjustTextareaHeight(textarea);
-  
-  return () => cleanup();
+    const textarea = textareaRef.current;
+
+    if (isNotNil(textarea)) {
+        return;
+    }
+
+    const cleanup = adjustTextareaHeight(textarea);
+
+    return () => cleanup();
 }, []);
-``` 
+```
 
 > **Note**: Requires valid `line-height` and `font-size` styles for accurate sizing.
 
 ### assertNever
 
 Checks that value is always type "never".
+
 ```ts
-switch(value) {
+switch (value) {
     case "a":
         return "A";
     case "b":
@@ -209,9 +289,11 @@ const example = <div ref={composeRefs(firstRef, secondRef)} />;
 ```
 
 ### cx, cxa
+
 It is our fork of `clsx` library https://github.com/lukeed/clsx
 
 We will mainly use `cx`, which is fork of `clsx/lite` – it accepts **ONLY** string values! Any non-string arguments are ignored!
+
 ```tsx
 import { cx } from "@uxf/core/utils/cx";
 
@@ -224,9 +306,10 @@ cx({ foo: true });
 //=> ""
 ```
 
-The `cxa` function is full fork of `clsx` and can take *any* number of arguments, each of which can be an Object, Array, Boolean, or String.
+The `cxa` function is full fork of `clsx` and can take _any_ number of arguments, each of which can be an Object, Array, Boolean, or String.
 
 **Important**: Any falsy values are discarded! Standalone Boolean values are discarded as well.
+
 ```tsx
 import { cxa } from "@uxf/core/utils/cxa";
 
@@ -238,11 +321,11 @@ cxa("foo", true && "bar", "baz");
 //=> "foo bar baz"
 
 // Objects
-cxa({ foo:true, bar:false, baz:isTrue() });
+cxa({ foo: true, bar: false, baz: isTrue() });
 //=> "foo baz"
 
 // Objects (variadic)
-cxa({ foo:true }, { bar:false }, null, { "--foobar":"hello" });
+cxa({ foo: true }, { bar: false }, null, { "--foobar": "hello" });
 //=> "foo --foobar"
 
 // Arrays
@@ -254,7 +337,7 @@ cxa(["foo"], ["", 0, false, "bar"], [["baz", [["hello"], "there"]]]);
 //=> "foo bar baz hello there"
 
 // Kitchen sink (with nesting)
-cxa("foo", [1 && "bar", { baz:false, bat:null }, ["hello", ["world"]]], "cya");
+cxa("foo", [1 && "bar", { baz: false, bat: null }, ["hello", ["world"]]], "cya");
 //=> "foo bar hello world cya"
 ```
 
@@ -285,11 +368,20 @@ const a = { b: 2, a: 1, nested: { y: 2, x: 1 } };
 const b = { nested: { x: 1, y: 2 }, a: 1, b: 2 };
 console.log(deepEqualIgnoringKeyOrder(a, b)); // true
 
-const arr1 = [{ a: 1, b: 2 }, { c: 3, d: 4 }];
-const arr2 = [{ b: 2, a: 1 }, { d: 4, c: 3 }];
+const arr1 = [
+    { a: 1, b: 2 },
+    { c: 3, d: 4 },
+];
+const arr2 = [
+    { b: 2, a: 1 },
+    { d: 4, c: 3 },
+];
 console.log(deepEqualIgnoringKeyOrder(arr1, arr2)); // true (objects equal, same array order)
 
-const arr3 = [{ d: 4, c: 3 }, { b: 2, a: 1 }];
+const arr3 = [
+    { d: 4, c: 3 },
+    { b: 2, a: 1 },
+];
 console.log(deepEqualIgnoringKeyOrder(arr1, arr3)); // false (array order differs)
 ```
 
@@ -302,7 +394,7 @@ import { downloadFile } from "@uxf/core/utils/download-file";
 import { FormEventHandler } from "react";
 
 const submitHandler: FormEventHandler<HTMLFormElement> = () => {
-    downloadFile("https://example.com/file", "file.txt")
+    downloadFile("https://example.com/file", "file.txt");
 };
 ```
 
@@ -313,7 +405,7 @@ Escapes all double quotes (`"`) in a string by replacing them with `\"`.
 ```ts
 import { escapeQuotes } from "@uxf/core/utils/escape-quotes";
 
-escapeQuotes('The "quick" fox'); 
+escapeQuotes('The "quick" fox');
 // Output: The \"quick\" fox
 ```
 
@@ -324,9 +416,9 @@ Converts a 0-based index to a 1-based (human-readable) index.
 ```tsx
 import { humanIndex } from "@uxf/core/utils/human-index";
 
-humanIndex(0);  /* returns 1 */
-humanIndex(9);  /* returns 10 */
-humanIndex(-1);  /* throws error */
+humanIndex(0); /* returns 1 */
+humanIndex(9); /* returns 10 */
+humanIndex(-1); /* throws error */
 ```
 
 ## filterNullish
@@ -369,7 +461,7 @@ const props = {
 const htmlAttrs = filterAriaAndDataAttrs(props);
 // Result: { "aria-label": "Close button", "data-testid": "close-btn" }
 
-<button {...htmlAttrs}>Close</button>
+<button {...htmlAttrs}>Close</button>;
 ```
 
 ```tsx
@@ -380,16 +472,13 @@ function CustomInput({ label, onChange, ...restProps }) {
     return <input {...accessibilityAttrs} onChange={onChange} />;
 }
 
-<CustomInput
-    aria-describedby="helper-text"
-    data-analytics="email-input"
-    customProp="ignored"
-/>
+<CustomInput aria-describedby="helper-text" data-analytics="email-input" customProp="ignored" />;
 ```
 
 ### formatBytes
 
 Appends suitable unit to the byte value of data size.
+
 ```ts
 formatBytes(17.5 * 1024);
 //=> "17.5 kB"
@@ -423,7 +512,7 @@ Re-export of [lodash.isequal](https://lodash.com/docs/#isEqual). Performs a deep
 import { isEqual } from "@uxf/core/utils/is-equal";
 
 isEqual({ a: 1, b: [2, 3] }, { a: 1, b: [2, 3] }); /* returns true */
-isEqual({ a: 1 }, { a: 2 });                         /* returns false */
+isEqual({ a: 1 }, { a: 2 }); /* returns false */
 ```
 
 ## isEmpty
@@ -444,11 +533,11 @@ Checks if a number is even.
 ```tsx
 import { isEven } from "@uxf/core/utils/is-even";
 
-isEven(2);  /* returns true */
-isEven(4);  /* returns true */
-isEven(1);  /* returns false */
-isEven(3);  /* returns false */
-isEven(0);  /* returns true */
+isEven(2); /* returns true */
+isEven(4); /* returns true */
+isEven(1); /* returns false */
+isEven(3); /* returns false */
+isEven(0); /* returns true */
 isEven(-2); /* returns true */
 ```
 
@@ -459,11 +548,11 @@ Checks if a number is odd.
 ```tsx
 import { isOdd } from "@uxf/core/utils/is-odd";
 
-isOdd(1);  /* returns true */
-isOdd(3);  /* returns true */
-isOdd(2);  /* returns false */
-isOdd(4);  /* returns false */
-isOdd(0);  /* returns false */
+isOdd(1); /* returns true */
+isOdd(3); /* returns true */
+isOdd(2); /* returns false */
+isOdd(4); /* returns false */
+isOdd(0); /* returns false */
 isOdd(-1); /* returns true */
 ```
 
@@ -482,13 +571,13 @@ const serverExample = isServer; /* returns true if DOM is NOT available */
 ```tsx
 import { isNil } from "@uxf/core/utils/is-nil";
 
-isNil(null);      /* returns true */
+isNil(null); /* returns true */
 isNil(undefined); /* returns true */
-isNil(true);      /* returns false */
-isNil(1);         /* returns false */
-isNil(0);         /* returns false */
-isNil([]);        /* returns false */
-isNil("string");  /* returns false */
+isNil(true); /* returns false */
+isNil(1); /* returns false */
+isNil(0); /* returns false */
+isNil([]); /* returns false */
+isNil("string"); /* returns false */
 ```
 
 ## isNotNil
@@ -496,13 +585,13 @@ isNil("string");  /* returns false */
 ```tsx
 import { isNotNil } from "@uxf/core/utils/is-not-nil";
 
-isNotNil(null);      /* returns false */
+isNotNil(null); /* returns false */
 isNotNil(undefined); /* returns false */
-isNotNil(true);      /* returns true */
-isNotNil(1);         /* returns true */
-isNotNil(0);         /* returns true */
-isNotNil([]);        /* returns true */
-isNotNil("string");  /* returns true */
+isNotNil(true); /* returns true */
+isNotNil(1); /* returns true */
+isNotNil(0); /* returns true */
+isNotNil([]); /* returns true */
+isNotNil("string"); /* returns true */
 ```
 
 ## isNotNilNorEmpty
@@ -529,18 +618,18 @@ Type guard that checks if a value is a plain object. Returns `false` for arrays,
 ```tsx
 import { isPlainObject } from "@uxf/core/utils/is-plain-object";
 
-isPlainObject({});           /* returns true */
-isPlainObject({ a: 1 });     /* returns true */
-isPlainObject([]);           /* returns false */
-isPlainObject([1, 2, 3]);    /* returns false */
-isPlainObject(new Date());   /* returns false */
-isPlainObject(new Map());    /* returns false */
-isPlainObject(new Set());    /* returns false */
-isPlainObject(/regex/);      /* returns false */
-isPlainObject(null);         /* returns false */
-isPlainObject(undefined);    /* returns false */
-isPlainObject("string");     /* returns false */
-isPlainObject(123);          /* returns false */
+isPlainObject({}); /* returns true */
+isPlainObject({ a: 1 }); /* returns true */
+isPlainObject([]); /* returns false */
+isPlainObject([1, 2, 3]); /* returns false */
+isPlainObject(new Date()); /* returns false */
+isPlainObject(new Map()); /* returns false */
+isPlainObject(new Set()); /* returns false */
+isPlainObject(/regex/); /* returns false */
+isPlainObject(null); /* returns false */
+isPlainObject(undefined); /* returns false */
+isPlainObject("string"); /* returns false */
+isPlainObject(123); /* returns false */
 ```
 
 ## last
@@ -549,7 +638,7 @@ isPlainObject(123);          /* returns false */
 import { last } from "@uxf/core/utils/last";
 
 last([1, 2]); /* returns 2 */
-last([]);     /* returns undefined */
+last([]); /* returns undefined */
 ```
 
 ## nonEmptyArrayOrNull
@@ -559,11 +648,11 @@ Converts empty arrays, `null`, or `undefined` values to `null`, leaving all non-
 ```tsx
 import { nonEmptyArrayOrNull } from "@uxf/core/utils/non-empty-array-or-null";
 
-nonEmptyArrayOrNull([]);          /* returns null */
-nonEmptyArrayOrNull(null);        /* returns null */
-nonEmptyArrayOrNull(undefined);   /* returns null */
-nonEmptyArrayOrNull([1, 2, 3]);   /* returns [1, 2, 3] */
-nonEmptyArrayOrNull(["a", "b"]);  /* returns ["a", "b"] */
+nonEmptyArrayOrNull([]); /* returns null */
+nonEmptyArrayOrNull(null); /* returns null */
+nonEmptyArrayOrNull(undefined); /* returns null */
+nonEmptyArrayOrNull([1, 2, 3]); /* returns [1, 2, 3] */
+nonEmptyArrayOrNull(["a", "b"]); /* returns ["a", "b"] */
 ```
 
 ## nonEmptyStringOrNull
@@ -573,13 +662,40 @@ Converts empty strings and `undefined` values to `null`, leaving all other strin
 ```tsx
 import { nonEmptyStringOrNull } from "@uxf/core/utils/non-empty-string-or-null";
 
-nonEmptyStringOrNull("");         /* returns null */
-nonEmptyStringOrNull(undefined);  /* returns null */
-nonEmptyStringOrNull(null);       /* returns null */
-nonEmptyStringOrNull("test");     /* returns "test" */
-nonEmptyStringOrNull(" ");        /* returns " " - non-empty string */
+nonEmptyStringOrNull(""); /* returns null */
+nonEmptyStringOrNull(undefined); /* returns null */
+nonEmptyStringOrNull(null); /* returns null */
+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.
@@ -587,10 +703,10 @@ Converts `null` or `undefined` values to an empty string, leaving all other stri
 ```tsx
 import { nullishToEmptyString } from "@uxf/core/utils/nullish-to-empty-string";
 
-nullishToEmptyString(null);            /* returns "" */
-nullishToEmptyString(undefined);       /* returns "" */
-nullishToEmptyString("");              /* returns "" */
-nullishToEmptyString("hello world");   /* returns "hello world" */
+nullishToEmptyString(null); /* returns "" */
+nullishToEmptyString(undefined); /* returns "" */
+nullishToEmptyString(""); /* returns "" */
+nullishToEmptyString("hello world"); /* returns "hello world" */
 ```
 
 ## numberOrNull
@@ -600,13 +716,13 @@ Converts `NaN`, `null`, or `undefined` values to `null`, leaving all valid numbe
 ```tsx
 import { numberOrNull } from "@uxf/core/utils/number-or-null";
 
-numberOrNull(0);          /* returns 0 */
-numberOrNull(42);         /* returns 42 */
-numberOrNull(-1);         /* returns -1 */
-numberOrNull(3.14);       /* returns 3.14 */
-numberOrNull(NaN);        /* returns null */
-numberOrNull(null);       /* returns null */
-numberOrNull(undefined);  /* returns null */
+numberOrNull(0); /* returns 0 */
+numberOrNull(42); /* returns 42 */
+numberOrNull(-1); /* returns -1 */
+numberOrNull(3.14); /* returns 3.14 */
+numberOrNull(NaN); /* returns null */
+numberOrNull(null); /* returns null */
+numberOrNull(undefined); /* returns null */
 ```
 
 ## plural
@@ -639,7 +755,26 @@ Re-export of [qs](https://github.com/ljharb/qs). A querystring parsing and strin
 import { stringify, parse } from "@uxf/core/utils/qs";
 
 stringify({ a: "b", c: [1, 2] }); /* returns "a=b&c%5B0%5D=1&c%5B1%5D=2" */
-parse("a=b&c=1");                 /* returns { a: "b", c: "1" } */
+parse("a=b&c=1"); /* returns { a: "b", c: "1" } */
+```
+
+## safeLocalStorage / safeSessionStorage
+
+Web storage that never throws. Safari in private mode, iOS with cookies blocked, sandboxed iframes and several in-app browsers throw `SecurityError: The operation is insecure.` on **reads as well as writes** — and in some browsers even on the bare `window.localStorage` property access — so unguarded storage access during render can take the whole app down. A full quota throws `QuotaExceededError` the same way.
+
+A read that cannot happen returns `null`, a write that cannot happen returns `false`. The storage object is resolved per call, so importing this module on the server is safe.
+
+```tsx
+import { safeLocalStorage, safeSessionStorage } from "@uxf/core/utils/safe-storage";
+
+safeLocalStorage.setItem("theme", "dark"); /* returns true, or false when storage is unavailable */
+safeLocalStorage.getItem("theme"); /* returns "dark", or null when storage is unavailable */
+safeLocalStorage.removeItem("theme"); /* returns true when it went through */
+safeLocalStorage.clear(); /* returns true when it went through */
+safeLocalStorage.length; /* returns 0 when storage is unavailable */
+safeLocalStorage.key(0); /* returns null when storage is unavailable */
+
+safeSessionStorage.getItem("wizard-step"); /* same API for sessionStorage */
 ```
 
 ## slugify
@@ -685,10 +820,10 @@ const example = trimTrailingZeros("120,450"); /* returns "120,45" */
 ```
 
 ## Validators
+
 ```tsx
 import { Validator } from "@uxf/core";
 
 Validator.isEmail("...");
 Validator.isPhone("...");
 ```
-

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.124.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([]);
+});

package/utils/safe-storage.d.ts

@@ -0,0 +1,10 @@
+export interface SafeStorage {
+    clear: () => boolean;
+    getItem: (key: string) => string | null;
+    key: (index: number) => string | null;
+    readonly length: number;
+    removeItem: (key: string) => boolean;
+    setItem: (key: string, value: string) => boolean;
+}
+export declare const safeLocalStorage: SafeStorage;
+export declare const safeSessionStorage: SafeStorage;

package/utils/safe-storage.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeSessionStorage = exports.safeLocalStorage = void 0;
+const is_browser_1 = require("./is-browser");
+const is_nil_1 = require("./is-nil");
+/**
+ * Web storage is not always usable. Safari in private mode, iOS with cookies blocked, sandboxed
+ * iframes and several in-app browsers throw `SecurityError: The operation is insecure.` — and a full
+ * quota throws `QuotaExceededError` — on **reads as well as writes**, and in some browsers even on
+ * the bare `window.localStorage` property access. An unguarded read during render therefore takes
+ * the whole app down.
+ *
+ * These wrappers never throw: a read that cannot happen returns `null`, a write that cannot happen
+ * returns `false`. The storage object is resolved per call, so a page that gains (or loses) access
+ * mid-session is handled too, and importing this module on the server is safe.
+ */
+function getWebStorage(name) {
+    if (!is_browser_1.isBrowser) {
+        return null;
+    }
+    try {
+        return window[name];
+    }
+    catch {
+        return null;
+    }
+}
+function createSafeStorage(name) {
+    return {
+        clear() {
+            const storage = getWebStorage(name);
+            if ((0, is_nil_1.isNil)(storage)) {
+                return false;
+            }
+            try {
+                storage.clear();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        getItem(key) {
+            const storage = getWebStorage(name);
+            if ((0, is_nil_1.isNil)(storage)) {
+                return null;
+            }
+            try {
+                return storage.getItem(key);
+            }
+            catch {
+                return null;
+            }
+        },
+        key(index) {
+            const storage = getWebStorage(name);
+            if ((0, is_nil_1.isNil)(storage)) {
+                return null;
+            }
+            try {
+                return storage.key(index);
+            }
+            catch {
+                return null;
+            }
+        },
+        get length() {
+            const storage = getWebStorage(name);
+            if ((0, is_nil_1.isNil)(storage)) {
+                return 0;
+            }
+            try {
+                return storage.length;
+            }
+            catch {
+                return 0;
+            }
+        },
+        removeItem(key) {
+            const storage = getWebStorage(name);
+            if ((0, is_nil_1.isNil)(storage)) {
+                return false;
+            }
+            try {
+                storage.removeItem(key);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        setItem(key, value) {
+            const storage = getWebStorage(name);
+            if ((0, is_nil_1.isNil)(storage)) {
+                return false;
+            }
+            try {
+                storage.setItem(key, value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+exports.safeLocalStorage = createSafeStorage("localStorage");
+exports.safeSessionStorage = createSafeStorage("sessionStorage");

package/utils/safe-storage.test.d.ts

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

package/utils/safe-storage.test.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const safe_storage_1 = require("./safe-storage");
+function throwSecurityError() {
+    throw new DOMException("The operation is insecure.", "SecurityError");
+}
+describe.each([
+    ["safeLocalStorage", safe_storage_1.safeLocalStorage, window.localStorage],
+    ["safeSessionStorage", safe_storage_1.safeSessionStorage, window.sessionStorage],
+])("%s", (_name, safeStorage, storage) => {
+    beforeEach(() => {
+        jest.restoreAllMocks();
+        storage.clear();
+    });
+    describe("with a working storage", () => {
+        it("reads and writes", () => {
+            expect(safeStorage.getItem("theme")).toBeNull();
+            expect(safeStorage.setItem("theme", "dark")).toBe(true);
+            expect(safeStorage.getItem("theme")).toBe("dark");
+        });
+        it("removes and clears", () => {
+            safeStorage.setItem("theme", "dark");
+            expect(safeStorage.removeItem("theme")).toBe(true);
+            expect(safeStorage.getItem("theme")).toBeNull();
+            safeStorage.setItem("theme", "dark");
+            expect(safeStorage.clear()).toBe(true);
+            expect(safeStorage.length).toBe(0);
+        });
+        it("enumerates keys", () => {
+            safeStorage.setItem("theme", "dark");
+            expect(safeStorage.length).toBe(1);
+            expect(safeStorage.key(0)).toBe("theme");
+            expect(safeStorage.key(1)).toBeNull();
+        });
+    });
+    describe("with a storage that throws (private mode, blocked storage, full quota)", () => {
+        it("returns null instead of throwing on a read", () => {
+            jest.spyOn(Storage.prototype, "getItem").mockImplementation(throwSecurityError);
+            expect(() => safeStorage.getItem("theme")).not.toThrow();
+            expect(safeStorage.getItem("theme")).toBeNull();
+        });
+        it("returns false instead of throwing on a write", () => {
+            jest.spyOn(Storage.prototype, "setItem").mockImplementation(throwSecurityError);
+            jest.spyOn(Storage.prototype, "removeItem").mockImplementation(throwSecurityError);
+            jest.spyOn(Storage.prototype, "clear").mockImplementation(throwSecurityError);
+            expect(safeStorage.setItem("theme", "dark")).toBe(false);
+            expect(safeStorage.removeItem("theme")).toBe(false);
+            expect(safeStorage.clear()).toBe(false);
+        });
+        it("returns empty values instead of throwing on enumeration", () => {
+            jest.spyOn(Storage.prototype, "key").mockImplementation(throwSecurityError);
+            jest.spyOn(Storage.prototype, "length", "get").mockImplementation(throwSecurityError);
+            expect(safeStorage.key(0)).toBeNull();
+            expect(safeStorage.length).toBe(0);
+        });
+    });
+});