@refraktor/utils 0.0.1

package/src/hooks/use-disclosure/index.ts

@@ -0,0 +1,67 @@
+import { useCallback, useMemo, useState } from "react";
+
+export interface UseDisclosureCallbacks {
+    onOpen?: () => void;
+    onClose?: () => void;
+}
+
+export interface UseDisclosureHandlers {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+}
+
+export type UseDisclosureReturn = [boolean, UseDisclosureHandlers];
+
+export function useDisclosure(
+    initialState = false,
+    callbacks?: UseDisclosureCallbacks
+): UseDisclosureReturn {
+    const [opened, setOpened] = useState(initialState);
+    const { onOpen, onClose } = callbacks ?? {};
+
+    const open = useCallback(() => {
+        setOpened((isOpened) => {
+            if (!isOpened) {
+                onOpen?.();
+            }
+
+            return true;
+        });
+    }, [onOpen]);
+
+    const close = useCallback(() => {
+        setOpened((isOpened) => {
+            if (isOpened) {
+                onClose?.();
+            }
+
+            return false;
+        });
+    }, [onClose]);
+
+    const toggle = useCallback(() => {
+        setOpened((isOpened) => {
+            const next = !isOpened;
+
+            if (next) {
+                onOpen?.();
+            } else {
+                onClose?.();
+            }
+
+            return next;
+        });
+    }, [onOpen, onClose]);
+
+    const handlers = useMemo(
+        () => ({
+            open,
+            close,
+            toggle
+        }),
+        [open, close, toggle]
+    );
+
+    return [opened, handlers];
+}

package/src/hooks/use-id/index.ts

@@ -0,0 +1,6 @@
+import { useId as useReactId } from "react";
+
+export function useId(propId?: any): string {
+    const id = useReactId();
+    return propId ?? id;
+}

package/src/hooks/use-isomorphic-layout-effect/index.ts

@@ -0,0 +1,4 @@
+import { useEffect, useLayoutEffect } from "react";
+
+export const useIsomorphicLayoutEffect: typeof useLayoutEffect =
+    typeof window !== "undefined" ? useLayoutEffect : useEffect;

package/src/hooks/use-merged-refs/index.ts

@@ -0,0 +1,45 @@
+import { Ref, useCallback, RefCallback } from "react";
+
+type AnyRef<T> = Ref<T> | undefined;
+type CleanupFunction<T> = ReturnType<RefCallback<T>>;
+
+function applyRef<T>(ref: AnyRef<T>, value: T | null): CleanupFunction<T> {
+    if (!ref) return;
+
+    if (typeof ref === "function") {
+        return ref(value);
+    }
+
+    if (typeof ref === "object" && "current" in ref) {
+        ref.current = value;
+    }
+}
+
+export function mergeRefs<T>(...refs: AnyRef<T>[]): RefCallback<T> {
+    const cleanups = new Map<AnyRef<T>, Exclude<CleanupFunction<T>, void>>();
+
+    return (node: T | null) => {
+        for (const ref of refs) {
+            const cleanup = applyRef(ref, node);
+            if (cleanup) cleanups.set(ref, cleanup);
+        }
+
+        if (cleanups.size > 0) {
+            return () => {
+                for (const ref of refs) {
+                    const fn = cleanups.get(ref);
+                    if (typeof fn === "function") {
+                        fn();
+                    } else {
+                        applyRef(ref, null);
+                    }
+                }
+                cleanups.clear();
+            };
+        }
+    };
+}
+
+export function useMergedRefs<T>(...refs: AnyRef<T>[]) {
+    return useCallback(mergeRefs(...refs), refs);
+}

package/src/hooks/use-resize-observer/index.ts

@@ -0,0 +1,105 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+export interface UseResizeObserverSize {
+    width: number;
+    height: number;
+}
+
+export interface UseResizeObserverOptions {
+    initialSize?: UseResizeObserverSize;
+    box?: ResizeObserverBoxOptions;
+    onResize?: (entry: ResizeObserverEntry) => void;
+}
+
+export interface UseResizeObserverReturn<T extends HTMLElement = HTMLElement>
+    extends UseResizeObserverSize {
+    ref: (node: T | null) => void;
+    entry: ResizeObserverEntry | null;
+}
+
+interface ResizeObserverState extends UseResizeObserverSize {
+    entry: ResizeObserverEntry | null;
+}
+
+const DEFAULT_SIZE: UseResizeObserverSize = {
+    width: 0,
+    height: 0
+};
+
+export function useResizeObserver<T extends HTMLElement = HTMLElement>(
+    options: UseResizeObserverOptions = {}
+): UseResizeObserverReturn<T> {
+    const { initialSize = DEFAULT_SIZE, box, onResize } = options;
+    const [node, setNode] = useState<T | null>(null);
+    const [state, setState] = useState<ResizeObserverState>(() => ({
+        width: initialSize.width,
+        height: initialSize.height,
+        entry: null
+    }));
+    const onResizeRef = useRef(onResize);
+
+    useEffect(() => {
+        onResizeRef.current = onResize;
+    }, [onResize]);
+
+    const ref = useCallback((nextNode: T | null) => {
+        setNode(nextNode);
+    }, []);
+
+    useEffect(() => {
+        if (!node) {
+            return;
+        }
+
+        if (
+            typeof window === "undefined" ||
+            typeof ResizeObserver === "undefined"
+        ) {
+            return;
+        }
+
+        const observer = new ResizeObserver(([entry]) => {
+            if (!entry) {
+                return;
+            }
+
+            const nextWidth = entry.contentRect.width;
+            const nextHeight = entry.contentRect.height;
+
+            setState((current) => {
+                if (
+                    current.width === nextWidth &&
+                    current.height === nextHeight &&
+                    current.entry !== null
+                ) {
+                    return current;
+                }
+
+                return {
+                    width: nextWidth,
+                    height: nextHeight,
+                    entry
+                };
+            });
+
+            onResizeRef.current?.(entry);
+        });
+
+        try {
+            observer.observe(node, box ? { box } : undefined);
+        } catch {
+            observer.observe(node);
+        }
+
+        return () => {
+            observer.disconnect();
+        };
+    }, [box, node]);
+
+    return {
+        ref,
+        width: state.width,
+        height: state.height,
+        entry: state.entry
+    };
+}

package/src/hooks/use-uncontrolled/index.ts

@@ -0,0 +1,36 @@
+import { useState } from "react";
+
+export type UseUncontrolledProps<T> = {
+    value?: T;
+    defaultValue?: T;
+    finalValue?: T;
+    onChange?: (value: T, ...payload: any[]) => void;
+};
+
+export type UseUncontrolledReturn<T> = [
+    T,
+    (value: T, ...payload: any[]) => void,
+    boolean
+];
+
+export function useUncontrolled<T>({
+    value,
+    defaultValue,
+    finalValue,
+    onChange = () => {}
+}: UseUncontrolledProps<T>): UseUncontrolledReturn<T> {
+    const [state, setState] = useState(
+        defaultValue !== undefined ? defaultValue : finalValue
+    );
+
+    const handleChange = (val: T, ...payload: any[]) => {
+        setState(val);
+        onChange?.(val, ...payload);
+    };
+
+    if (value !== undefined) {
+        return [value as T, onChange, true];
+    }
+
+    return [state as T, handleChange, false];
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./hooks";
+export * from "./utils";

package/src/utils/auto-contrast/index.ts

@@ -0,0 +1,73 @@
+type RGB = {
+    r: number;
+    g: number;
+    b: number;
+};
+
+function parseHexColor(color: string): RGB | null {
+    const value = color.trim().replace(/^#/, "");
+
+    if (![3, 4, 6, 8].includes(value.length)) return null;
+    if (!/^[0-9a-fA-F]+$/.test(value)) return null;
+
+    const normalized =
+        value.length === 3 || value.length === 4
+            ? value
+                  .slice(0, 3)
+                  .split("")
+                  .map((char) => `${char}${char}`)
+                  .join("")
+            : value.slice(0, 6);
+
+    return {
+        r: Number.parseInt(normalized.slice(0, 2), 16),
+        g: Number.parseInt(normalized.slice(2, 4), 16),
+        b: Number.parseInt(normalized.slice(4, 6), 16)
+    };
+}
+
+function toRelativeLuminance(channel: number): number {
+    const sRGB = channel / 255;
+
+    if (sRGB <= 0.03928) return sRGB / 12.92;
+
+    return ((sRGB + 0.055) / 1.055) ** 2.4;
+}
+
+function getLuminance(color: RGB): number {
+    return (
+        0.2126 * toRelativeLuminance(color.r) +
+        0.7152 * toRelativeLuminance(color.g) +
+        0.0722 * toRelativeLuminance(color.b)
+    );
+}
+
+function getContrastRatio(background: RGB, foreground: RGB): number {
+    const backgroundLuminance = getLuminance(background);
+    const foregroundLuminance = getLuminance(foreground);
+
+    const lighter = Math.max(backgroundLuminance, foregroundLuminance);
+    const darker = Math.min(backgroundLuminance, foregroundLuminance);
+
+    return (lighter + 0.05) / (darker + 0.05);
+}
+
+export function getAutoContrastTextColor(
+    background: string,
+    darkText: string,
+    lightText: string,
+    fallbackColor: string
+): string {
+    const backgroundRGB = parseHexColor(background);
+    if (!backgroundRGB) return fallbackColor;
+
+    const darkTextRGB = parseHexColor(darkText);
+    const lightTextRGB = parseHexColor(lightText);
+
+    if (!darkTextRGB || !lightTextRGB) return fallbackColor;
+
+    return getContrastRatio(backgroundRGB, darkTextRGB) >=
+        getContrastRatio(backgroundRGB, lightTextRGB)
+        ? darkText
+        : lightText;
+}

package/src/utils/clamp/index.ts

@@ -0,0 +1,13 @@
+export function clamp(
+    value: number,
+    min: number | undefined,
+    max: number | undefined
+): number {
+    if (min === undefined && max === undefined) return value;
+
+    if (min !== undefined && max === undefined) return Math.max(min, value);
+
+    if (min === undefined && max !== undefined) return Math.min(max, value);
+
+    return Math.min(Math.max(value, min!), max!);
+}

package/src/utils/context/index.ts

@@ -0,0 +1,2 @@
+export { createOptionalContext } from "./optional-context";
+export { createSafeContext } from "./safe-context";

package/src/utils/context/optional-context.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+
+export function createOptionalContext<ContextValue>(
+    initialValue: ContextValue | null = null
+) {
+    const Context = createContext<ContextValue | null>(initialValue);
+
+    const useOptionalContext = () => useContext(Context);
+
+    const Provider = ({
+        value,
+        children
+    }: {
+        value: ContextValue;
+        children: React.ReactNode;
+    }) => {
+        return <Context.Provider value={value}>{children}</Context.Provider>;
+    };
+
+    return [Provider, useOptionalContext] as const;
+}

package/src/utils/context/safe-context.tsx

@@ -0,0 +1,25 @@
+import { createContext, useContext } from "react";
+
+export function createSafeContext<ContextValue>(err: string) {
+    const Context = createContext<ContextValue | null>(null);
+
+    const useSafeContext = () => {
+        const context = useContext(Context);
+
+        if (context === null) {
+            throw new Error(err);
+        }
+
+        return context;
+    };
+
+    const Provider = ({
+        children,
+        value
+    }: {
+        children: React.ReactNode;
+        value: ContextValue;
+    }) => <Context.Provider value={value}>{children}</Context.Provider>;
+
+    return [Provider, useSafeContext] as const;
+}

package/src/utils/get-change-value/index.ts

@@ -0,0 +1,22 @@
+type Props = {
+    value: number;
+    min: number;
+    max: number;
+    step: number;
+    precision?: number;
+};
+
+export function getChangeValue({
+    value,
+    min,
+    max,
+    step,
+    precision
+}: Props): number {
+    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/src/utils/index.ts

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

package/src/utils/storage/index.ts

@@ -0,0 +1,203 @@
+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;
+
+const isBrowser = typeof window !== "undefined";
+
+export function createStorage<T>(key: string, options: StorageOptions<T> = {}) {
+    const {
+        defaultValue,
+        ttl,
+        serializer = JSON.stringify,
+        deserializer = JSON.parse
+    } = options;
+
+    const listeners = new Set<StorageListener<T>>();
+
+    const getFullKey = () => key;
+
+    const get = (): T | null => {
+        if (!isBrowser) return defaultValue ?? null;
+
+        try {
+            const raw = localStorage.getItem(getFullKey());
+            if (raw === null) return defaultValue ?? null;
+
+            const item: StorageItem<T> = deserializer(raw);
+
+            if (item.expiry && Date.now() > item.expiry) {
+                remove();
+                return defaultValue ?? null;
+            }
+
+            return item.value;
+        } catch {
+            return defaultValue ?? null;
+        }
+    };
+
+    const set = (value: T): void => {
+        if (!isBrowser) return;
+
+        try {
+            const oldValue = get();
+
+            const item: StorageItem<T> = {
+                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 = (): void => {
+        if (!isBrowser) return;
+
+        const oldValue = get();
+        localStorage.removeItem(getFullKey());
+
+        listeners.forEach((listener) =>
+            listener({ key: getFullKey(), oldValue, newValue: null })
+        );
+    };
+
+    const exists = (): boolean => {
+        if (!isBrowser) return false;
+        return localStorage.getItem(getFullKey()) !== null;
+    };
+
+    const subscribe = (listener: StorageListener<T>): (() => void) => {
+        listeners.add(listener);
+
+        const handleStorageEvent = (event: StorageEvent) => {
+            if (event.key === getFullKey()) {
+                try {
+                    const oldValue = event.oldValue
+                        ? (deserializer(event.oldValue) as StorageItem<T>).value
+                        : null;
+                    const newValue = event.newValue
+                        ? (deserializer(event.newValue) as StorageItem<T>).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: (current: T | null) => T): void => {
+        const current = get();
+        set(updater(current));
+    };
+
+    return {
+        get,
+        set,
+        remove,
+        exists,
+        subscribe,
+        update,
+        key: getFullKey()
+    };
+}
+
+export const storage = {
+    get<T>(key: string, defaultValue?: T): T | null {
+        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<T>(key: string, value: T, ttl?: number): void {
+        if (!isBrowser) return;
+
+        try {
+            const item: StorageItem<T> = {
+                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: string): void {
+        if (!isBrowser) return;
+        localStorage.removeItem(key);
+    },
+
+    clear(): void {
+        if (!isBrowser) return;
+        localStorage.clear();
+    },
+
+    keys(): string[] {
+        if (!isBrowser) return [];
+        return Object.keys(localStorage);
+    },
+
+    size(): number {
+        if (!isBrowser) return 0;
+        return localStorage.length;
+    }
+};

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./build",
+        "rootDir": "./src",
+        "declaration": true,
+        "declarationMap": true,
+        "noEmit": false,
+        "allowImportingTsExtensions": false
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "build"]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/index.ts","./src/hooks/index.ts","./src/hooks/use-click-outside/index.ts","./src/hooks/use-debounced-callback/index.ts","./src/hooks/use-disclosure/index.ts","./src/hooks/use-id/index.ts","./src/hooks/use-isomorphic-layout-effect/index.ts","./src/hooks/use-merged-refs/index.ts","./src/hooks/use-resize-observer/index.ts","./src/hooks/use-uncontrolled/index.ts","./src/utils/index.ts","./src/utils/auto-contrast/index.ts","./src/utils/clamp/index.ts","./src/utils/context/index.ts","./src/utils/context/optional-context.tsx","./src/utils/context/safe-context.tsx","./src/utils/get-change-value/index.ts","./src/utils/storage/index.ts"],"version":"5.9.3"}