@refraktor/utils 0.0.1

package/build/utils/get-change-value/index.d.ts

@@ -0,0 +1,10 @@
+type Props = {
+    value: number;
+    min: number;
+    max: number;
+    step: number;
+    precision?: number;
+};
+export declare function getChangeValue({ value, min, max, step, precision }: Props): number;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/utils/get-change-value/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/get-change-value/index.ts"],"names":[],"mappings":"AAAA,KAAK,KAAK,GAAG;IACT,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,wBAAgB,cAAc,CAAC,EAC3B,KAAK,EACL,GAAG,EACH,GAAG,EACH,IAAI,EACJ,SAAS,EACZ,EAAE,KAAK,GAAG,MAAM,CAOhB"}

package/build/utils/get-change-value/index.js

@@ -0,0 +1,7 @@
+export function getChangeValue({ value, min, max, step, precision }) {
+    const scaled = min + value * (max - min);
+    const stepped = Math.round(scaled / step) * step;
+    if (precision !== undefined)
+        return Number(stepped.toFixed(precision));
+    return Math.min(Math.max(stepped, min), max);
+}

package/build/utils/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./auto-contrast";
+export * from "./clamp";
+export * from "./context";
+export * from "./get-change-value";
+export * from "./storage";
+//# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,oBAAoB,CAAC;AACnC,cAAc,WAAW,CAAC"}

package/build/utils/index.js

@@ -0,0 +1,5 @@
+export * from "./auto-contrast";
+export * from "./clamp";
+export * from "./context";
+export * from "./get-change-value";
+export * from "./storage";

package/build/utils/storage/index.d.ts

@@ -0,0 +1,39 @@
+export interface StorageOptions<T> {
+    /** Default value if key doesn't exist */
+    defaultValue?: T;
+    /** Time-to-live in milliseconds */
+    ttl?: number;
+    /** Custom serializer function */
+    serializer?: (value: T) => string;
+    /** Custom deserializer function */
+    deserializer?: (value: string) => T;
+}
+export interface StorageItem<T> {
+    value: T;
+    expiry?: number;
+}
+export interface StorageEventPayload<T> {
+    key: string;
+    oldValue: T | null;
+    newValue: T | null;
+}
+type StorageListener<T> = (payload: StorageEventPayload<T>) => void;
+export declare function createStorage<T>(key: string, options?: StorageOptions<T>): {
+    get: () => T | null;
+    set: (value: T) => void;
+    remove: () => void;
+    exists: () => boolean;
+    subscribe: (listener: StorageListener<T>) => (() => void);
+    update: (updater: (current: T | null) => T) => void;
+    key: string;
+};
+export declare const storage: {
+    get<T>(key: string, defaultValue?: T): T | null;
+    set<T>(key: string, value: T, ttl?: number): void;
+    remove(key: string): void;
+    clear(): void;
+    keys(): string[];
+    size(): number;
+};
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/utils/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/storage/index.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc,CAAC,CAAC;IAC7B,yCAAyC;IACzC,YAAY,CAAC,EAAE,CAAC,CAAC;IAEjB,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb,iCAAiC;IACjC,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAM,CAAC;IAElC,mCAAmC;IACnC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC1B,KAAK,EAAE,CAAC,CAAC;IACT,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC;CACtB;AAED,KAAK,eAAe,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAIpE,wBAAgB,aAAa,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,cAAc,CAAC,CAAC,CAAM;eAYzD,CAAC,GAAG,IAAI;iBAoBJ,CAAC,KAAG,IAAI;kBAqBT,IAAI;kBAWJ,OAAO;0BAKG,eAAe,CAAC,CAAC,CAAC,KAAG,CAAC,MAAM,IAAI,CAAC;sBA+BrC,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,KAAG,IAAI;;EAc3D;AAED,eAAO,MAAM,OAAO;QACZ,CAAC,OAAO,MAAM,iBAAiB,CAAC,GAAG,CAAC,GAAG,IAAI;QAuB3C,CAAC,OAAO,MAAM,SAAS,CAAC,QAAQ,MAAM,GAAG,IAAI;gBAcrC,MAAM,GAAG,IAAI;aAKhB,IAAI;YAKL,MAAM,EAAE;YAKR,MAAM;CAIjB,CAAC"}

package/build/utils/storage/index.js

@@ -0,0 +1,150 @@
+const isBrowser = typeof window !== "undefined";
+export function createStorage(key, options = {}) {
+    const { defaultValue, ttl, serializer = JSON.stringify, deserializer = JSON.parse } = options;
+    const listeners = new Set();
+    const getFullKey = () => key;
+    const get = () => {
+        if (!isBrowser)
+            return defaultValue ?? null;
+        try {
+            const raw = localStorage.getItem(getFullKey());
+            if (raw === null)
+                return defaultValue ?? null;
+            const item = deserializer(raw);
+            if (item.expiry && Date.now() > item.expiry) {
+                remove();
+                return defaultValue ?? null;
+            }
+            return item.value;
+        }
+        catch {
+            return defaultValue ?? null;
+        }
+    };
+    const set = (value) => {
+        if (!isBrowser)
+            return;
+        try {
+            const oldValue = get();
+            const item = {
+                value,
+                expiry: ttl ? Date.now() + ttl : undefined
+            };
+            localStorage.setItem(getFullKey(), serializer(item));
+            listeners.forEach((listener) => listener({ key: getFullKey(), oldValue, newValue: value }));
+        }
+        catch (error) {
+            console.warn(`Failed to set localStorage key "${key}":`, error);
+        }
+    };
+    const remove = () => {
+        if (!isBrowser)
+            return;
+        const oldValue = get();
+        localStorage.removeItem(getFullKey());
+        listeners.forEach((listener) => listener({ key: getFullKey(), oldValue, newValue: null }));
+    };
+    const exists = () => {
+        if (!isBrowser)
+            return false;
+        return localStorage.getItem(getFullKey()) !== null;
+    };
+    const subscribe = (listener) => {
+        listeners.add(listener);
+        const handleStorageEvent = (event) => {
+            if (event.key === getFullKey()) {
+                try {
+                    const oldValue = event.oldValue
+                        ? deserializer(event.oldValue).value
+                        : null;
+                    const newValue = event.newValue
+                        ? deserializer(event.newValue).value
+                        : null;
+                    listener({ key: getFullKey(), oldValue, newValue });
+                }
+                catch {
+                    // Ignore parse errors
+                }
+            }
+        };
+        if (isBrowser) {
+            window.addEventListener("storage", handleStorageEvent);
+        }
+        return () => {
+            listeners.delete(listener);
+            if (isBrowser) {
+                window.removeEventListener("storage", handleStorageEvent);
+            }
+        };
+    };
+    const update = (updater) => {
+        const current = get();
+        set(updater(current));
+    };
+    return {
+        get,
+        set,
+        remove,
+        exists,
+        subscribe,
+        update,
+        key: getFullKey()
+    };
+}
+export const storage = {
+    get(key, defaultValue) {
+        if (!isBrowser)
+            return defaultValue ?? null;
+        try {
+            const raw = localStorage.getItem(key);
+            if (raw === null)
+                return defaultValue ?? null;
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && "value" in parsed) {
+                if (parsed.expiry && Date.now() > parsed.expiry) {
+                    localStorage.removeItem(key);
+                    return defaultValue ?? null;
+                }
+                return parsed.value;
+            }
+            return parsed;
+        }
+        catch {
+            return defaultValue ?? null;
+        }
+    },
+    set(key, value, ttl) {
+        if (!isBrowser)
+            return;
+        try {
+            const item = {
+                value,
+                expiry: ttl ? Date.now() + ttl : undefined
+            };
+            localStorage.setItem(key, JSON.stringify(item));
+        }
+        catch (error) {
+            console.warn(`Failed to set localStorage key "${key}":`, error);
+        }
+    },
+    remove(key) {
+        if (!isBrowser)
+            return;
+        localStorage.removeItem(key);
+    },
+    clear() {
+        if (!isBrowser)
+            return;
+        localStorage.clear();
+    },
+    keys() {
+        if (!isBrowser)
+            return [];
+        return Object.keys(localStorage);
+    },
+    size() {
+        if (!isBrowser)
+            return 0;
+        return localStorage.length;
+    }
+};

package/build/utils/storage/storage.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=storage.d.ts.map

package/build/utils/storage/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/utils/storage/storage.ts"],"names":[],"mappings":""}

package/build/utils/storage/storage.js

@@ -0,0 +1 @@
+"use strict";

package/build/utils/storage/storage.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=storage.test.d.ts.map

package/build/utils/storage/storage.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.test.d.ts","sourceRoot":"","sources":["../../../src/utils/storage/storage.test.ts"],"names":[],"mappings":""}

package/build/utils/storage/storage.test.js

@@ -0,0 +1,153 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createStorage, createStorageAdapter, storage } from "./index";
+const originalWindow = globalThis.window;
+const createMockStorage = () => {
+    const map = new Map();
+    return {
+        get length() {
+            return map.size;
+        },
+        clear() {
+            map.clear();
+        },
+        getItem(key) {
+            return map.has(key) ? map.get(key) : null;
+        },
+        key(index) {
+            return Array.from(map.keys())[index] ?? null;
+        },
+        removeItem(key) {
+            map.delete(key);
+        },
+        setItem(key, value) {
+            map.set(key, value);
+        }
+    };
+};
+const installMockWindow = () => {
+    const localStorage = createMockStorage();
+    const sessionStorage = createMockStorage();
+    const listeners = new Set();
+    const windowMock = {
+        localStorage,
+        sessionStorage,
+        addEventListener(type, listener) {
+            if (type === "storage" && typeof listener === "function") {
+                listeners.add(listener);
+            }
+        },
+        removeEventListener(type, listener) {
+            if (type === "storage" && typeof listener === "function") {
+                listeners.delete(listener);
+            }
+        },
+        dispatchStorageEvent(event) {
+            listeners.forEach((listener) => listener(event));
+        }
+    };
+    Object.defineProperty(globalThis, "window", {
+        value: windowMock,
+        configurable: true,
+        writable: true
+    });
+    return windowMock;
+};
+afterEach(() => {
+    vi.useRealTimers();
+    if (originalWindow === undefined) {
+        delete globalThis.window;
+    }
+    else {
+        Object.defineProperty(globalThis, "window", {
+            value: originalWindow,
+            configurable: true,
+            writable: true
+        });
+    }
+});
+describe("createStorageAdapter", () => {
+    it("creates in-memory adapters that can store values", () => {
+        const adapter = createStorageAdapter("memory");
+        adapter.setItem("theme", "dark");
+        expect(adapter.getItem("theme")).toBe("dark");
+        expect(adapter.size()).toBe(1);
+        expect(adapter.keys()).toEqual(["theme"]);
+    });
+    it("creates independent memory adapters", () => {
+        const first = createStorageAdapter("memory");
+        const second = createStorageAdapter("memory");
+        first.setItem("theme", "dark");
+        expect(first.getItem("theme")).toBe("dark");
+        expect(second.getItem("theme")).toBeNull();
+    });
+});
+describe("createStorage", () => {
+    it("supports session adapter selection", () => {
+        const windowMock = installMockWindow();
+        const sessionStore = createStorage("theme", {
+            adapter: "session"
+        });
+        sessionStore.set("dark");
+        expect(windowMock.sessionStorage.getItem("theme")).not.toBeNull();
+        expect(windowMock.localStorage.getItem("theme")).toBeNull();
+        expect(sessionStore.get()).toBe("dark");
+    });
+    it("supports memory adapter without browser APIs", () => {
+        delete globalThis.window;
+        const memoryStore = createStorage("count", {
+            adapter: "memory",
+            defaultValue: 0
+        });
+        memoryStore.set(2);
+        memoryStore.update((value) => (value ?? 0) + 1);
+        expect(memoryStore.get()).toBe(3);
+    });
+    it("expires values based on TTL", () => {
+        vi.useFakeTimers();
+        const memoryStore = createStorage("token", {
+            adapter: "memory",
+            ttl: 1000
+        });
+        memoryStore.set("abc");
+        vi.advanceTimersByTime(1001);
+        expect(memoryStore.get()).toBeNull();
+    });
+    it("subscribes to local writes and cross-context storage events", () => {
+        const windowMock = installMockWindow();
+        const localStore = createStorage("theme", { adapter: "local" });
+        const listener = vi.fn();
+        const unsubscribe = localStore.subscribe(listener);
+        localStore.set("dark");
+        windowMock.dispatchStorageEvent({
+            key: "theme",
+            oldValue: JSON.stringify({ value: "dark" }),
+            newValue: JSON.stringify({ value: "light" }),
+            storageArea: windowMock.localStorage
+        });
+        expect(listener).toHaveBeenNthCalledWith(1, {
+            key: "theme",
+            oldValue: null,
+            newValue: "dark"
+        });
+        expect(listener).toHaveBeenNthCalledWith(2, {
+            key: "theme",
+            oldValue: "dark",
+            newValue: "light"
+        });
+        unsubscribe();
+    });
+});
+describe("storage", () => {
+    it("keeps local storage as default and exposes session/memory clients", () => {
+        const windowMock = installMockWindow();
+        storage.set("theme", "dark");
+        storage.session.set("theme", "light");
+        storage.memory.set("theme", "system");
+        expect(storage.get("theme")).toBe("dark");
+        expect(storage.local.get("theme")).toBe("dark");
+        expect(storage.session.get("theme")).toBe("light");
+        expect(storage.memory.get("theme")).toBe("system");
+        expect(windowMock.localStorage.getItem("theme")).not.toBeNull();
+        expect(windowMock.sessionStorage.getItem("theme")).not.toBeNull();
+    });
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+    "name": "@refraktor/utils",
+    "version": "0.0.1",
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "main": "./build/index.js",
+    "module": "./build/index.js",
+    "types": "./build/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./build/index.d.ts",
+            "import": "./build/index.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch",
+        "clean": "rm -rf build"
+    },
+    "peerDependencies": {
+        "react": ">=18.0.0"
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.7",
+        "typescript": "^5.9.3"
+    }
+}

package/src/hooks/index.ts

@@ -0,0 +1,8 @@
+export { useId } from "./use-id";
+export { useDisclosure } from "./use-disclosure";
+export { useClickOutside } from "./use-click-outside";
+export { useResizeObserver } from "./use-resize-observer";
+export { useMergedRefs } from "./use-merged-refs";
+export { useUncontrolled } from "./use-uncontrolled";
+export { useDebouncedCallback } from "./use-debounced-callback";
+export { useIsomorphicLayoutEffect } from "./use-isomorphic-layout-effect";

package/src/hooks/use-click-outside/index.ts

@@ -0,0 +1,76 @@
+import { useEffect, useRef } from "react";
+
+export type UseClickOutsideEvent = keyof DocumentEventMap;
+
+type UseClickOutsideNode = HTMLElement | null;
+
+const DEFAULT_EVENTS: UseClickOutsideEvent[] = ["mousedown", "touchstart"];
+const DEFAULT_NODES: UseClickOutsideNode[] = [];
+
+export function useClickOutside<T extends HTMLElement = HTMLElement>(
+    handler: (event: Event) => void,
+    events: UseClickOutsideEvent[] = DEFAULT_EVENTS,
+    nodes: UseClickOutsideNode[] = DEFAULT_NODES
+) {
+    const ref = useRef<T>(null);
+    const handlerRef = useRef(handler);
+
+    useEffect(() => {
+        handlerRef.current = handler;
+    }, [handler]);
+
+    useEffect(() => {
+        const listener = (event: Event) => {
+            const target = event.target;
+
+            if (!(target instanceof Node)) {
+                return;
+            }
+
+            const element = ref.current;
+
+            if (!element) {
+                return;
+            }
+
+            const path =
+                typeof event.composedPath === "function"
+                    ? event.composedPath()
+                    : undefined;
+
+            const isInsideElement = path
+                ? path.includes(element)
+                : element.contains(target);
+
+            if (isInsideElement) {
+                return;
+            }
+
+            const isInsideAdditionalNode = nodes.some((node) => {
+                if (!node) {
+                    return false;
+                }
+
+                return path ? path.includes(node) : node.contains(target);
+            });
+
+            if (isInsideAdditionalNode) {
+                return;
+            }
+
+            handlerRef.current(event);
+        };
+
+        for (const eventName of events) {
+            document.addEventListener(eventName, listener);
+        }
+
+        return () => {
+            for (const eventName of events) {
+                document.removeEventListener(eventName, listener);
+            }
+        };
+    }, [events, nodes]);
+
+    return ref;
+}

package/src/hooks/use-debounced-callback/index.ts

@@ -0,0 +1,128 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+export interface UseDebouncedCallbackOptions {
+    leading?: boolean;
+    trailing?: boolean;
+}
+
+export type UseDebouncedCallbackReturn<
+    TArgs extends unknown[],
+    TResult
+> = ((...args: TArgs) => void) & {
+    cancel: () => void;
+    flush: () => TResult | undefined;
+    isPending: () => boolean;
+};
+
+export function useDebouncedCallback<TArgs extends unknown[], TResult>(
+    callback: (...args: TArgs) => TResult,
+    delay: number,
+    options: UseDebouncedCallbackOptions = {}
+): UseDebouncedCallbackReturn<TArgs, TResult> {
+    const { leading = false, trailing = true } = options;
+    const wait = Math.max(0, delay);
+
+    const callbackRef = useRef(callback);
+    const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const lastArgsRef = useRef<TArgs | null>(null);
+    const shouldCallTrailingRef = useRef(false);
+    const resultRef = useRef<TResult | undefined>(undefined);
+
+    useEffect(() => {
+        callbackRef.current = callback;
+    }, [callback]);
+
+    const invoke = useCallback((args: TArgs) => {
+        const result = callbackRef.current(...args);
+        resultRef.current = result;
+        return result;
+    }, []);
+
+    const clearTimer = useCallback(() => {
+        if (timeoutRef.current !== null) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+    }, []);
+
+    const cancel = useCallback(() => {
+        clearTimer();
+        shouldCallTrailingRef.current = false;
+        lastArgsRef.current = null;
+    }, [clearTimer]);
+
+    const flush = useCallback(() => {
+        if (timeoutRef.current === null) {
+            return resultRef.current;
+        }
+
+        clearTimer();
+
+        if (
+            trailing &&
+            shouldCallTrailingRef.current &&
+            lastArgsRef.current !== null
+        ) {
+            const next = invoke(lastArgsRef.current);
+            shouldCallTrailingRef.current = false;
+            lastArgsRef.current = null;
+            return next;
+        }
+
+        shouldCallTrailingRef.current = false;
+        lastArgsRef.current = null;
+        return resultRef.current;
+    }, [clearTimer, invoke, trailing]);
+
+    const isPending = useCallback(() => timeoutRef.current !== null, []);
+
+    const debounced = useMemo(() => {
+        const fn = (...args: TArgs) => {
+            if (!leading && !trailing) {
+                return;
+            }
+
+            const hasTimer = timeoutRef.current !== null;
+
+            if (!hasTimer) {
+                if (leading) {
+                    invoke(args);
+                    shouldCallTrailingRef.current = false;
+                    lastArgsRef.current = null;
+                } else {
+                    shouldCallTrailingRef.current = true;
+                    lastArgsRef.current = args;
+                }
+            } else if (trailing) {
+                shouldCallTrailingRef.current = true;
+                lastArgsRef.current = args;
+            }
+
+            clearTimer();
+            timeoutRef.current = setTimeout(() => {
+                timeoutRef.current = null;
+
+                if (
+                    trailing &&
+                    shouldCallTrailingRef.current &&
+                    lastArgsRef.current !== null
+                ) {
+                    invoke(lastArgsRef.current);
+                }
+
+                shouldCallTrailingRef.current = false;
+                lastArgsRef.current = null;
+            }, wait);
+        };
+
+        return Object.assign(fn, {
+            cancel,
+            flush,
+            isPending
+        });
+    }, [cancel, clearTimer, flush, invoke, isPending, leading, trailing, wait]);
+
+    useEffect(() => cancel, [cancel]);
+
+    return debounced;
+}