@uxf/core 11.80.4 → 11.87.0

package/README.md

@@ -125,6 +125,63 @@ useIsomorphicLayoutEffect(() => {
 
 > **Note**: Requires valid `line-height` and `font-size` styles for accurate sizing.
 
+### assertNever
+
+Checks that value is always type "never".
+```ts
+switch(value) {
+    case "a":
+        return "A";
+    case "b":
+        return "B";
+    default:
+        return assertNever(value);
+}
+```
+
+## assertNotNil
+
+```tsx
+import { assertNotNil } from "@uxf/core/utils/assert-not-nil";
+
+const testObject: { value: number | null } = { value: 10 };
+
+assertNotNil(testObject.value);
+
+// is the same as
+
+if (isNil(testObject.value)) {
+    throw new Error("Value is null");
+}
+```
+
+## camelCaseToDash
+
+```tsx
+import { camelCaseToDash } from "@uxf/core/utils/camelCaseToDash";
+
+const example = camelCaseToDash("fooBar"); /* returns "foo-bar" */
+```
+
+## capitalize
+
+```tsx
+import { capitalize } from "@uxf/core/utils/capitalize";
+
+const example = capitalize("hello world"); /* returns "Hello world" */
+```
+
+## composeRefs
+
+```tsx
+import { composeRefs } from "@uxf/core/utils/composeRefs";
+
+const firstRef = useRef<HTMLDivElement>(null);
+const secondRef = useRef<HTMLDivElement>(null);
+
+const example = <div ref={composeRefs(firstRef, secondRef)} />;
+```
+
 ### cx, cxa
 It is our fork of `clsx` library https://github.com/lukeed/clsx
 
@@ -175,9 +232,30 @@ cxa("foo", [1 && "bar", { baz:false, bat:null }, ["hello", ["world"]]], "cya");
 //=> "foo bar hello world cya"
 ```
 
+### deepEqualIgnoringKeyOrder
+
+deepEqualIgnoringKeyOrder compares two values for deep equality while ignoring the order of object keys. It serializes values in a stable way, ensuring that objects with the same data but different key orders are treated as equal. Arrays remain order-sensitive, circular references are handled safely, and primitives are compared by value.
+
+Use this helper for equality checks in tests, memoization, caching, or change detection scenarios where object key order shouldn’t matter. It’s especially useful when comparing payloads, configs, or API responses that may have non-deterministic key ordering.
+
+```typescript
+import { deepEqualIgnoringKeyOrder } from "./deep-equal-ingoring-key-order";
+
+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 }];
+console.log(deepEqualIgnoringKeyOrder(arr1, arr2)); // true (objects equal, same array order)
+
+const arr3 = [{ d: 4, c: 3 }, { b: 2, a: 1 }];
+console.log(deepEqualIgnoringKeyOrder(arr1, arr3)); // false (array order differs)
+```
+
 ### downloadFile
 
-Intended as only way to programmatically download file if there is no option to use native anchor with `download` html attribute (eg. in form submit events). 
+Intended as only way to programmatically download file if there is no option to use native anchor with `download` html attribute (eg. in form submit events).
 
 ```ts
 import { downloadFile } from "@uxf/core/utils/download-file";
@@ -199,6 +277,50 @@ escapeQuotes('The "quick" fox');
 // Output: The \"quick\" fox
 ```
 
+## filterNullish
+
+```tsx
+import { filterNullish } from "@uxf/core/utils/filter-nullish";
+
+filterNullish([0, "text", null, undefined, [], {}]); /* returns [0, "text", [], {}]  */
+```
+
+## filterAriaAndDataAttrs
+
+Filters an object to return only properties that start with `aria-` or `data-` prefixes. This utility is useful when you need to pass accessibility and data attributes to HTML elements while excluding other props like event handlers or component-specific props.
+
+```tsx
+import { filterAriaAndDataAttrs } from "@uxf/core/utils/filter-aria-and-data-attrs";
+
+// Filter accessibility and data attributes from component props
+const props = {
+    "aria-label": "Close button",
+    "data-testid": "close-btn",
+    className: "button",
+    onClick: handleClick,
+};
+
+const htmlAttrs = filterAriaAndDataAttrs(props);
+// Result: { "aria-label": "Close button", "data-testid": "close-btn" }
+
+<button {...htmlAttrs}>Close</button>
+```
+
+```tsx
+// Use case: Passing only safe attributes to a native element
+function CustomInput({ label, onChange, ...restProps }) {
+    const accessibilityAttrs = filterAriaAndDataAttrs(restProps);
+
+    return <input {...accessibilityAttrs} onChange={onChange} />;
+}
+
+<CustomInput
+    aria-describedby="helper-text"
+    data-analytics="email-input"
+    customProp="ignored"
+/>
+```
+
 ### formatBytes
 
 Appends suitable unit to the byte value of data size.
@@ -207,18 +329,102 @@ formatBytes(17.5 * 1024);
 //=> "17.5 kB"
 ```
 
-### assertNever
+## isEmpty
 
-Checks that value is always type "never".
-```ts
-switch(value) {
-    case "a":
-        return "A";
-    case "b":
-        return "B";
-    default:
-        return assertNever(value);
-}
+```tsx
+import { isEmpty } from "@uxf/core/utils/is-empty";
+
+isEmpty("not-empty"); /* returns false */
+isEmpty(""); /* returns true */
+isEmpty(["1"]); /* returns false */
+isEmpty([]); /* returns true */
+```
+
+## isBrowser / isServer
+
+```tsx
+import { isBrowser } from "@uxf/core/utils/isBrowser";
+import { isServer } from "@uxf/core/utils/isServer";
+
+const browserExample = isBrowser; /* returns true if DOM is available */
+const serverExample = isServer; /* returns true if DOM is NOT available */
+```
+
+## isNil
+
+```tsx
+import { isNil } from "@uxf/core/utils/is-nil";
+
+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 */
+```
+
+## isNotNil
+
+```tsx
+import { isNotNil } from "@uxf/core/utils/is-not-nil";
+
+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 */
+```
+
+```tsx
+import { last } from "@uxf/core/utils/last";
+
+last([1, 2]); /* returns 2 */
+last([]);     /* returns undefined */
+```
+
+## slugify
+
+```tsx
+import { slugify } from "@uxf/core/utils/slugify";
+
+const example = slugify("Jak se dnes máte?"); /* returns "jak-se-dnes-mate" */
+```
+
+### stableStringify
+
+Deterministically converts any JavaScript value into a JSON string by recursively sorting object keys while preserving array order. It safely handles circular references by replacing them with the string "[Circular]" and never mutates the input. This makes it ideal for creating stable cache keys, hashing inputs, logging, or equality checks that should ignore object key order.
+
+```typescript
+// Example usage
+import { stableStringify } from "./stable-stringify";
+
+// Key order does not affect the output
+const a = { b: 2, a: 1, nested: { y: 2, x: 1 } };
+const b = { nested: { x: 1, y: 2 }, a: 1, b: 2 };
+
+console.log(stableStringify(a));
+// -> {"a":1,"b":2,"nested":{"x":1,"y":2}}
+
+console.log(stableStringify(b));
+// -> {"a":1,"b":2,"nested":{"x":1,"y":2}}  // same as above
+
+// Circular references are handled
+const obj: any = { name: "root" };
+obj.self = obj;
+
+console.log(stableStringify(obj));
+// -> {"name":"root","self":"[Circular]"}
+```
+
+## trimTrailingZeros
+
+```tsx
+import { trimTrailingZeros } from "@uxf/core/utils/trimTrailingZeros";
+
+const example = trimTrailingZeros("120,450"); /* returns "120,45" */
 ```
 
 ## Validators

package/package.json

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

package/utils/deep-equal-ingoring-key-order.d.ts

@@ -0,0 +1 @@
+export declare function deepEqualIgnoringKeyOrder(a: unknown, b: unknown): boolean;

package/utils/deep-equal-ingoring-key-order.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deepEqualIgnoringKeyOrder = deepEqualIgnoringKeyOrder;
+const stable_stringify_1 = require("./stable-stringify");
+function deepEqualIgnoringKeyOrder(a, b) {
+    return (0, stable_stringify_1.stableStringify)(a) === (0, stable_stringify_1.stableStringify)(b);
+}

package/utils/deep-equal-ingoring-key-order.test.d.ts

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

package/utils/deep-equal-ingoring-key-order.test.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// packages/core/utils/deep-equal-ingoring-key-order.test.ts
+const deep_equal_ingoring_key_order_1 = require("./deep-equal-ingoring-key-order");
+describe("deepEqualIgnoringKeyOrder", () => {
+    it("returns true for objects with same keys in different orders", () => {
+        const a = { b: 2, a: 1, c: 3 };
+        const b = { c: 3, b: 2, a: 1 };
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("returns true for nested objects with different key orders", () => {
+        const a = { z: 0, nested: { b: 2, a: 1 }, another: { y: 2, x: 1 } };
+        const b = { another: { x: 1, y: 2 }, nested: { a: 1, b: 2 }, z: 0 };
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("returns true for arrays where items are objects with different key orders", () => {
+        const a = [
+            { b: 2, a: 1 },
+            { d: 4, c: 3 },
+        ];
+        const b = [
+            { a: 1, b: 2 },
+            { c: 3, d: 4 },
+        ];
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("returns false when array order differs", () => {
+        const a = [
+            { a: 1, b: 2 },
+            { c: 3, d: 4 },
+        ];
+        const b = [
+            { c: 3, d: 4 },
+            { a: 1, b: 2 },
+        ];
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(false);
+    });
+    it("returns false when values differ", () => {
+        const a = { a: 1, b: 2 };
+        const b = { a: 1, b: 3 };
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(false);
+    });
+    it("returns false for different types", () => {
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(1, "1")).toBe(false);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(true, "true")).toBe(false);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(null, {})).toBe(false);
+    });
+    it("returns true for identical primitives", () => {
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(null, null)).toBe(true);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(42, 42)).toBe(true);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(true, true)).toBe(true);
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)("hello", "hello")).toBe(true);
+    });
+    it("handles equal circular object references as equal", () => {
+        const a = { name: "root" };
+        a.self = a;
+        const b = { name: "root" };
+        b.self = b;
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+    it("distinguishes different circular shapes", () => {
+        const x = { a: 1 };
+        x.self = x; // self points to parent
+        const y = { a: 1, self: {} };
+        y.self.self = y.self; // self points to itself (nested circular)
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(x, y)).toBe(false);
+    });
+    it("works with nested circular structures", () => {
+        const a = { id: 1, child: { id: 2 } };
+        a.child.parent = a;
+        const b = { child: { id: 2 }, id: 1 };
+        b.child.parent = b;
+        expect((0, deep_equal_ingoring_key_order_1.deepEqualIgnoringKeyOrder)(a, b)).toBe(true);
+    });
+});

package/utils/filter-aria-and-data-attrs.d.ts

@@ -0,0 +1,3 @@
+export declare function filterAriaAndDataAttrs<P extends Record<string, any>>(props: P): {
+    [k: string]: any;
+};

package/utils/filter-aria-and-data-attrs.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filterAriaAndDataAttrs = filterAriaAndDataAttrs;
+function filterAriaAndDataAttrs(props) {
+    return Object.fromEntries(Object.entries(props).filter((p) => { var _a, _b; return Boolean(((_a = p.at(0)) === null || _a === void 0 ? void 0 : _a.startsWith("aria-")) || ((_b = p.at(0)) === null || _b === void 0 ? void 0 : _b.startsWith("data-"))); }));
+}

package/utils/filter-aria-and-data-attrs.test.d.ts

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

package/utils/filter-aria-and-data-attrs.test.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const filter_aria_and_data_attrs_1 = require("./filter-aria-and-data-attrs");
+describe("filterAriaAndDataAttrs", () => {
+    it("should filter only aria- attributes", () => {
+        const props = {
+            "aria-label": "test label",
+            "aria-hidden": true,
+            className: "test-class",
+            id: "test-id",
+        };
+        const result = (0, filter_aria_and_data_attrs_1.filterAriaAndDataAttrs)(props);
+        expect(result).toEqual({
+            "aria-label": "test label",
+            "aria-hidden": true,
+        });
+    });
+    it("should filter only data- attributes", () => {
+        const props = {
+            "data-testid": "test",
+            "data-value": 123,
+            className: "test-class",
+            onClick: jest.fn(),
+        };
+        const result = (0, filter_aria_and_data_attrs_1.filterAriaAndDataAttrs)(props);
+        expect(result).toEqual({
+            "data-testid": "test",
+            "data-value": 123,
+        });
+    });
+    it("should filter both aria- and data- attributes", () => {
+        const props = {
+            "aria-label": "label",
+            "data-testid": "test",
+            "aria-describedby": "desc",
+            "data-custom": "value",
+            className: "class",
+            style: { color: "red" },
+        };
+        const result = (0, filter_aria_and_data_attrs_1.filterAriaAndDataAttrs)(props);
+        expect(result).toEqual({
+            "aria-label": "label",
+            "data-testid": "test",
+            "aria-describedby": "desc",
+            "data-custom": "value",
+        });
+    });
+    it("should return empty object when no aria- or data- attributes present", () => {
+        const props = {
+            className: "test",
+            id: "id",
+            onClick: jest.fn(),
+        };
+        const result = (0, filter_aria_and_data_attrs_1.filterAriaAndDataAttrs)(props);
+        expect(result).toEqual({});
+    });
+    it("should return empty object for empty input", () => {
+        const props = {};
+        const result = (0, filter_aria_and_data_attrs_1.filterAriaAndDataAttrs)(props);
+        expect(result).toEqual({});
+    });
+    it("should handle attributes with various value types", () => {
+        const props = {
+            "aria-expanded": false,
+            "aria-level": 2,
+            "data-object": { nested: "value" },
+            "data-array": [1, 2, 3],
+            "data-null": null,
+            "data-undefined": undefined,
+            regularProp: "value",
+        };
+        const result = (0, filter_aria_and_data_attrs_1.filterAriaAndDataAttrs)(props);
+        expect(result).toEqual({
+            "aria-expanded": false,
+            "aria-level": 2,
+            "data-object": { nested: "value" },
+            "data-array": [1, 2, 3],
+            "data-null": null,
+            "data-undefined": undefined,
+        });
+    });
+    it("should not filter attributes that contain but don't start with aria- or data-", () => {
+        const props = {
+            "aria-label": "keep",
+            "data-id": "keep",
+            "my-aria-label": "remove",
+            "my-data-id": "remove",
+        };
+        const result = (0, filter_aria_and_data_attrs_1.filterAriaAndDataAttrs)(props);
+        expect(result).toEqual({
+            "aria-label": "keep",
+            "data-id": "keep",
+        });
+    });
+});

package/utils/resizer.js

@@ -35,7 +35,11 @@ const BASE_PATH = (_b = process.env.NEXT_PUBLIC_BASE_PATH) !== null && _b !== vo
 const resizerStaticImageUrl = (src, width = "auto", height = "auto", props = {}, version = 1) => {
     var _a;
     const { fit = "cover", position = "center", toFormat = undefined, trim = "not-trim", background = "FFF" } = props;
-    const filepath = typeof src === "string" ? src : src.src;
+    let filepath = typeof src === "string" ? src : src.src;
+    // fix absolute assetPrefix
+    if (!filepath.startsWith("/")) {
+        filepath = new URL(filepath).pathname;
+    }
     const dotIndex = filepath.lastIndexOf(".");
     const filename = filepath.slice(0, dotIndex);
     const extension = filepath.slice(dotIndex + 1);

package/utils/resizer.test.js

@@ -16,7 +16,7 @@ describe("resizerGetDefaultConfig", () => {
             toFormat: "avif",
             quality: 1,
         });
-        expect(url).toBe("/generated/static/x_x_cv_b_t_nt_1/1http://example.com/image.jpg.avif");
+        expect(url).toBe("/generated/static/x_x_cv_b_t_nt_1/1/image.jpg.avif");
     });
     it("should return a valid URL for an ImageResponse source", () => {
         const imageResponse = {
@@ -29,7 +29,7 @@ describe("resizerGetDefaultConfig", () => {
     });
     it("should return a valid URL for a string source", () => {
         const url = (0, resizer_1.resizerImageUrl)("http://example.com/image.png", 250, 250, { toFormat: "webp" });
-        expect(url).toBe("/generated/static/250_250_cv_c_FFF_nt_x/1http://example.com/image.png.webp");
+        expect(url).toBe("/generated/static/250_250_cv_c_FFF_nt_x/1/image.png.webp");
     });
     it("should return undefined for null or undefined source", () => {
         expect((0, resizer_1.resizerImageUrl)(null)).toBeUndefined();

package/utils/stable-stringify.d.ts

@@ -0,0 +1 @@
+export declare function stableStringify(value: unknown): string;

package/utils/stable-stringify.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableStringify = stableStringify;
+function stableStringify(value) {
+    const seen = new WeakSet();
+    function normalize(val) {
+        if (val && typeof val === "object") {
+            if (seen.has(val)) {
+                return "[Circular]";
+            }
+            seen.add(val);
+            if (Array.isArray(val)) {
+                return val.map(normalize);
+            }
+            // plain object: sort keys
+            const out = {};
+            for (const key of Object.keys(val).sort()) {
+                out[key] = normalize(val[key]);
+            }
+            return out;
+        }
+        return val;
+    }
+    return JSON.stringify(normalize(value));
+}

package/utils/stable-stringify.test.d.ts

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

package/utils/stable-stringify.test.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const stable_stringify_1 = require("./stable-stringify");
+describe("stableStringify", () => {
+    it("produces identical strings for objects with the same keys in different orders", () => {
+        const a = { b: 2, a: 1, c: 3 };
+        const b = { c: 3, b: 2, a: 1 };
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe((0, stable_stringify_1.stableStringify)(b));
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe('{"a":1,"b":2,"c":3}');
+    });
+    it("sorts keys recursively in nested objects", () => {
+        const a = { z: 0, nested: { b: 2, a: 1 }, another: { y: 2, x: 1 } };
+        const b = { another: { x: 1, y: 2 }, nested: { a: 1, b: 2 }, z: 0 };
+        const sa = (0, stable_stringify_1.stableStringify)(a);
+        const sb = (0, stable_stringify_1.stableStringify)(b);
+        expect(sa).toBe(sb);
+        expect(sa).toBe('{"another":{"x":1,"y":2},"nested":{"a":1,"b":2},"z":0}');
+    });
+    it("normalizes arrays while preserving array order", () => {
+        const a = [
+            { b: 2, a: 1 },
+            { d: 4, c: 3 },
+        ];
+        const b = [
+            { a: 1, b: 2 },
+            { c: 3, d: 4 },
+        ];
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe((0, stable_stringify_1.stableStringify)(b));
+        expect((0, stable_stringify_1.stableStringify)(a)).toBe('[{"a":1,"b":2},{"c":3,"d":4}]');
+    });
+    it("handles circular references in objects", () => {
+        const obj = { name: "root" };
+        obj.self = obj;
+        expect((0, stable_stringify_1.stableStringify)(obj)).toBe('{"name":"root","self":"[Circular]"}');
+    });
+    it("handles circular references in arrays", () => {
+        const arr = [];
+        arr.push(arr);
+        expect((0, stable_stringify_1.stableStringify)(arr)).toBe('["[Circular]"]');
+    });
+    it("handles mixed nested circular structures", () => {
+        const a = { id: 1, child: { id: 2 } };
+        a.child.parent = a;
+        const str = (0, stable_stringify_1.stableStringify)(a);
+        expect(str).toBe('{"child":{"id":2,"parent":"[Circular]"},"id":1}');
+    });
+    it("handles primitives", () => {
+        expect((0, stable_stringify_1.stableStringify)(null)).toBe("null");
+        expect((0, stable_stringify_1.stableStringify)(42)).toBe("42");
+        expect((0, stable_stringify_1.stableStringify)(true)).toBe("true");
+        expect((0, stable_stringify_1.stableStringify)("hello")).toBe('"hello"');
+    });
+    it("does not mutate the input object", () => {
+        const input = { b: 2, a: 1, nested: { y: 2, x: 1 } };
+        const snapshot = JSON.parse(JSON.stringify(input));
+        void (0, stable_stringify_1.stableStringify)(input);
+        expect(input).toEqual(snapshot);
+    });
+});