@povio/ui 0.0.2 → 0.0.3

package/src/hooks/useFilters.ts

@@ -0,0 +1,154 @@
+import { useEffect, useState } from "react";
+
+import { UIRouter } from "../config/router.context";
+
+type FilterValue = string | string[] | boolean;
+
+export interface FilterStore<TFilterData> {
+  filterData: TFilterData;
+  setFilterValue: (data: Partial<TFilterData>) => void;
+  getFilterValue: (keys: (keyof TFilterData)[]) => Partial<TFilterData>;
+  clearAllFilters: () => void;
+}
+
+const serializeFiltersToQuery = (filterData: Record<string, FilterValue>, prefix: string) => {
+  const query: Record<string, string | string[]> = {};
+
+  for (const [key, value] of Object.entries(filterData)) {
+    if (value === null || value === undefined) {
+      continue;
+    }
+
+    const filterKey = `filter[${prefix && `${prefix}-`}${key}]`;
+
+    if (Array.isArray(value) || typeof value === "object") {
+      query[filterKey] = JSON.stringify(value);
+    } else if (typeof value === "boolean") {
+      query[filterKey] = value ? "true" : "false";
+    } else {
+      query[filterKey] = value;
+    }
+  }
+
+  return query;
+};
+
+const parseFilterFromQuery = (query: Record<string, string>): Record<string, FilterValue> => {
+  const filter: Record<string, FilterValue> = {};
+
+  for (const [key, value] of Object.entries(query)) {
+    const match = /^filter\[(.+?)\]$/.exec(key);
+    if (!match) {
+      continue;
+    }
+
+    const filterKey = match[1];
+    const isArray = value.startsWith("[") && value.endsWith("]");
+    const isObject = value.startsWith("{") && value.endsWith("}");
+    const isNumber = !Number.isNaN(Number(value)) && value !== "";
+    const isBoolean = ["true", "false"].includes(value);
+
+    if (isArray || isObject || isNumber) {
+      filter[filterKey] = JSON.parse(value) as FilterValue;
+    } else if (isBoolean) {
+      filter[filterKey] = value === "true";
+    } else {
+      filter[filterKey] = value;
+    }
+  }
+
+  return filter;
+};
+
+export const useFilters = <TFilterData>(defaultFilterValues?: TFilterData, prefix = ""): FilterStore<TFilterData> => {
+  const { query, pathname, replace } = UIRouter.useUIRouter();
+
+  const queryFilters = parseFilterFromQuery(query as Record<string, string>);
+  const [filterData, setFilterData] = useState<TFilterData>(queryFilters as TFilterData);
+
+  useEffect(() => {
+    const setUrlToDefaultFilters = () => {
+      const flatFilterQuery = serializeFiltersToQuery(defaultFilterValues as Record<string, FilterValue>, prefix);
+      replace({
+        pathname,
+        query: {
+          ...query,
+          ...flatFilterQuery,
+        },
+      });
+    };
+
+    const currentFilters = parseFilterFromQuery(query as Record<string, string>);
+    const hasFiltersSet = Object.keys(currentFilters).length > 0;
+
+    if (defaultFilterValues && !hasFiltersSet) {
+      setUrlToDefaultFilters();
+    }
+  }, [defaultFilterValues, prefix]);
+
+  useEffect(() => {
+    const newQueryFilters = parseFilterFromQuery(query as Record<string, string>);
+    setFilterData(newQueryFilters as TFilterData);
+  }, [query]);
+
+  const setFilterValue = (data: Partial<TFilterData>) => {
+    let newFilters = { ...filterData };
+
+    const isReset = Object.keys(data).length === 0;
+    const isResetToDefault = data === defaultFilterValues;
+
+    if (isResetToDefault) {
+      newFilters = {
+        ...defaultFilterValues,
+      } satisfies TFilterData;
+    } else if (isReset) {
+      newFilters = {} as TFilterData;
+    } else {
+      Object.entries(data).forEach(([key, value]) => {
+        if (value === undefined) {
+          delete newFilters[key as keyof TFilterData];
+        } else {
+          newFilters[key as keyof TFilterData] = value as TFilterData[keyof TFilterData];
+        }
+      });
+    }
+
+    const prefixPart = prefix ? `${prefix}-` : "";
+
+    const cleanedQuery = Object.keys(query).reduce(
+      (acc, k) => {
+        if (!k.startsWith(`filter[${prefixPart}`)) {
+          acc[k] = query[k];
+        }
+        return acc;
+      },
+      {} as typeof query,
+    );
+
+    const flatFilterQuery = serializeFiltersToQuery(newFilters as Record<string, FilterValue>, prefix);
+
+    replace({
+      pathname,
+      query: {
+        ...cleanedQuery,
+        ...flatFilterQuery,
+      },
+    });
+
+    setFilterData(newFilters);
+  };
+
+  const getFilterValue = (keys: (keyof TFilterData)[]) => {
+    const result = {} as Partial<TFilterData>;
+    keys.forEach((key) => {
+      result[key] = filterData[key];
+    });
+    return result;
+  };
+
+  const clearAllFilters = () => {
+    setFilterValue(defaultFilterValues ?? ({} as TFilterData));
+  };
+
+  return { filterData, setFilterValue, getFilterValue, clearAllFilters };
+};

package/src/hooks/useForm.ts

@@ -0,0 +1,54 @@
+/* oxlint-disable no-restricted-imports */
+import { zodResolver } from "@hookform/resolvers/zod";
+import { useMemo } from "react";
+import {
+  type BrowserNativeObject,
+  type DefaultValues,
+  type ExtractObjects,
+  type FieldValues,
+  type NestedValue,
+  type UseFormProps as UseReactHookFormProps,
+  useForm as useReactHookForm,
+} from "react-hook-form";
+import type { z } from "zod";
+
+type DeepNullablePartial<T> = T extends BrowserNativeObject | NestedValue
+  ? T
+  : { [K in keyof T]?: ExtractObjects<T[K]> extends never ? T[K] | null : DeepNullablePartial<T[K]> };
+
+type AsyncDefaultValues<TFieldValues> = (payload?: unknown) => Promise<TFieldValues>;
+
+type NullableDefaultValues<TFieldValues> = TFieldValues extends AsyncDefaultValues<TFieldValues>
+  ? DeepNullablePartial<Awaited<TFieldValues>>
+  : DeepNullablePartial<TFieldValues>;
+
+export type UseFormResolverProps<TFieldValues extends FieldValues, TTransformedValues = TFieldValues> =
+  | { zodSchema: z.ZodType<TTransformedValues, TFieldValues>; resolver?: never }
+  | { zodSchema?: never };
+
+export type UseFormProps<TFieldValues extends FieldValues, TContext, TTransformedValues = TFieldValues> = Omit<
+  UseReactHookFormProps<TFieldValues, TContext, TTransformedValues>,
+  "defaultValues"
+> & { defaultValues?: NullableDefaultValues<TFieldValues> | AsyncDefaultValues<TFieldValues> };
+
+export function useForm<
+  TFieldValues extends FieldValues = FieldValues,
+  TContext = any,
+  TTransformedValues = TFieldValues,
+>({
+  resolver,
+  zodSchema,
+  defaultValues,
+  ...props
+}: UseFormProps<TFieldValues, TContext, TTransformedValues> & UseFormResolverProps<TFieldValues, TTransformedValues>) {
+  const formResolver = useMemo(
+    () => resolver ?? (zodSchema ? zodResolver(zodSchema) : undefined),
+    [resolver, zodSchema],
+  );
+
+  return useReactHookForm<TFieldValues, TContext, TTransformedValues>({
+    ...props,
+    resolver: formResolver,
+    defaultValues: defaultValues as DefaultValues<TFieldValues> | AsyncDefaultValues<TFieldValues>,
+  });
+}

package/src/hooks/useFormAutosave.ts

@@ -0,0 +1,100 @@
+import { type DependencyList, useEffect, useRef } from "react";
+import type { DefaultValues, FieldValues, KeepStateOptions } from "react-hook-form";
+
+import { type UseAutosaveProps, useAutosave } from "#ui/hooks/useAutosave";
+import { type UseFormProps, type UseFormResolverProps, useForm } from "#ui/hooks/useForm";
+import { ObjectUtils } from "#ui/utils/object.utils";
+
+const getResetTimeoutErrorMessage = (resetTimeout: number) => `Form Reset Timeout (${resetTimeout}ms) - Action Required
+Problem: Form values weren't reset after submission.
+
+Likely causes:
+• Missing variables in reset dependency array
+• Reset dependencies not updating after form save
+• Async operations blocking timely reset
+
+Solutions:
+1. Ensure reset dependencies include all relevant state variables
+2. Confirm your submission handler updates state properly (check query invalidation)
+3. For slower operations, consider increasing the timeout threshold`;
+
+export type UseFormAutosaveProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TContext = any,
+  TTransformedValues = TFieldValues,
+  TResponse = unknown,
+> = Omit<UseFormProps<TFieldValues, TContext, TTransformedValues>, "defaultValues"> &
+  UseFormResolverProps<TFieldValues, TTransformedValues> & {
+    autosaveDelay?: UseAutosaveProps<TFieldValues, TContext, TTransformedValues, TResponse>["delay"];
+    enableAutosave?: UseAutosaveProps<TFieldValues, TContext, TTransformedValues, TResponse>["enabled"];
+    onAutosave: UseAutosaveProps<TFieldValues, TContext, TTransformedValues, TResponse>["onSave"];
+    getResetValues: () => UseFormProps<TFieldValues, TContext, TTransformedValues>["defaultValues"];
+    resetDeps: DependencyList;
+    resetTimeout?: number;
+  };
+
+export function useFormAutosave<
+  TFieldValues extends FieldValues = FieldValues,
+  TContext = any,
+  TTransformedValues = TFieldValues,
+  TResponse = any,
+>({
+  autosaveDelay,
+  enableAutosave,
+  onAutosave,
+  getResetValues,
+  resetDeps,
+  resetTimeout = 5000,
+  ...props
+}: UseFormAutosaveProps<TFieldValues, TContext, TTransformedValues, TResponse>) {
+  const form = useForm<TFieldValues, TContext, TTransformedValues>({ ...props, defaultValues: getResetValues() });
+
+  const shouldResetFormValuesRef = useRef(false);
+  const resetFormValuesTimeoutRef = useRef<NodeJS.Timeout | undefined>(undefined);
+
+  useEffect(() => {
+    const resetValues = getResetValues() as DefaultValues<TFieldValues> | undefined;
+    if (resetValues === undefined) {
+      return;
+    }
+
+    const resetFormValues = async () => {
+      const keepStateOptions: KeepStateOptions | undefined = shouldResetFormValuesRef.current
+        ? { keepDirtyValues: true }
+        : undefined;
+      shouldResetFormValuesRef.current = false;
+
+      let values = resetValues;
+      if (ObjectUtils.isFunction(resetValues)) {
+        values = await (resetValues as () => Promise<DefaultValues<TFieldValues>>)();
+      }
+      form.reset(values, keepStateOptions);
+    };
+
+    resetFormValues();
+  }, [...resetDeps]);
+
+  const onSaveSuccess = () => {
+    shouldResetFormValuesRef.current = true;
+
+    if (resetFormValuesTimeoutRef.current) {
+      clearTimeout(resetFormValuesTimeoutRef.current);
+    }
+
+    resetFormValuesTimeoutRef.current = setTimeout(() => {
+      if (shouldResetFormValuesRef.current) {
+        throw new Error(getResetTimeoutErrorMessage(resetTimeout));
+      }
+    }, resetTimeout);
+  };
+
+  useAutosave<TFieldValues, TContext, TTransformedValues, TResponse>({
+    form,
+    delay: autosaveDelay,
+    enabled: enableAutosave,
+    onSave: onAutosave,
+    onSaveSuccess,
+  });
+
+  return form;
+}

package/src/hooks/useIntersectionObserver.ts

@@ -0,0 +1,33 @@
+import { useEffect, useState } from "react";
+
+type UseIntersectionObserverProps = {
+  onIntersection?: () => void;
+} & IntersectionObserverInit;
+
+export const useIntersectionObserver = ({
+  onIntersection,
+  root,
+  rootMargin,
+  threshold,
+}: UseIntersectionObserverProps) => {
+  const [ref, setRef] = useState<Element | null>(null);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries: IntersectionObserverEntry[]) => {
+        if (entries.some((entry) => entry.isIntersecting)) {
+          onIntersection?.();
+        }
+      },
+      { root, rootMargin, threshold },
+    );
+
+    if (ref) {
+      observer.observe(ref);
+    }
+
+    return () => observer.disconnect();
+  }, [ref, root, rootMargin, threshold, onIntersection]);
+
+  return { setRef };
+};

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,81 @@
+import { useCallback, useEffect, useState } from "react";
+import type { z } from "zod";
+
+interface IProps<ZOutput, ZInput> {
+  key: string;
+  schema: z.ZodType<ZOutput, ZInput>;
+}
+
+export const useLocalStorage = <ZOutput, ZInput>({ key, schema }: IProps<ZOutput, ZInput>) => {
+  const [value, setValue] = useState<ZOutput | null>(null);
+  const [isInitialLoading, setIsInitialLoading] = useState(true);
+
+  const [error, setError] = useState<Error | null>(null);
+
+  useEffect(() => {
+    if (!localStorage) {
+      setValue(null);
+      return;
+    }
+
+    try {
+      const lsValue = localStorage.getItem(key);
+      if (!lsValue) {
+        setValue(null);
+        return;
+      }
+
+      let jsonOrString: unknown;
+      try {
+        jsonOrString = JSON.parse(lsValue);
+      } catch {
+        jsonOrString = lsValue;
+      }
+
+      const parsedValue = schema.safeParse(jsonOrString);
+
+      if (parsedValue.success) {
+        setValue(parsedValue.data);
+      } else {
+        setError(parsedValue.error);
+        setValue(null);
+      }
+    } finally {
+      setIsInitialLoading(false);
+    }
+  }, [key, schema]);
+
+  const set = useCallback(
+    (newValue: ZInput) => {
+      if (!localStorage) {
+        return;
+      }
+
+      const parsedValue = schema.safeParse(newValue);
+
+      if (!parsedValue.success) {
+        return;
+      }
+
+      if (typeof parsedValue.data === "string") {
+        localStorage.setItem(key, parsedValue.data);
+      } else {
+        localStorage.setItem(key, JSON.stringify(parsedValue.data));
+      }
+
+      setValue(parsedValue.data);
+    },
+    [key, schema],
+  );
+
+  const remove = useCallback(() => {
+    if (!localStorage) {
+      return;
+    }
+
+    localStorage.removeItem(key);
+    setValue(null);
+  }, [key]);
+
+  return { value, set, remove, error, isInitialLoading };
+};

package/src/hooks/useLongPressRepeat.ts

@@ -0,0 +1,40 @@
+import { useEffect, useRef } from "react";
+
+export const useLongPressRepeat = ({
+  onPress,
+  enabled = true,
+  interval = 85,
+  timeout = 500,
+}: {
+  onPress: (long?: boolean) => void;
+  enabled?: boolean;
+  interval?: number;
+  timeout?: number;
+}) => {
+  const intervalRef = useRef<NodeJS.Timeout>(undefined);
+
+  useEffect(() => {
+    return () => {
+      clearInterval(intervalRef.current);
+    };
+  }, []);
+
+  const onPressStart = () => {
+    onPress(false);
+    if (!enabled) {
+      return;
+    }
+    intervalRef.current = setTimeout(() => {
+      onPress(true);
+      intervalRef.current = setInterval(() => {
+        onPress(true);
+      }, interval);
+    }, timeout);
+  };
+
+  const onPressEnd = () => {
+    clearInterval(intervalRef.current);
+  };
+
+  return { onPressStart, onPressEnd };
+};

package/src/hooks/usePagination.ts

@@ -0,0 +1,41 @@
+import type { PaginationState } from "@tanstack/react-table";
+import { useEffect, useState } from "react";
+
+import { UIRouter } from "../config/router.context";
+
+const DEFAULT_STATE: PaginationState = {
+  pageIndex: 1,
+  pageSize: 20,
+};
+
+export function usePagination(defaultPagination?: PaginationState) {
+  const { pathname, query, replace, searchParams } = UIRouter.useUIRouter();
+
+  const [pagination, setPagination] = useState<PaginationState>(
+    defaultPagination ?? {
+      pageIndex: searchParams.has("page")
+        ? Number.parseInt(searchParams.get("page") ?? "", 10)
+        : DEFAULT_STATE.pageIndex,
+      pageSize: searchParams.has("size") ? Number.parseInt(searchParams.get("size") ?? "", 10) : DEFAULT_STATE.pageSize,
+    },
+  );
+
+  useEffect(() => {
+    const { page: _page, size: _size, ...queryParms } = query;
+    replace({
+      pathname,
+      query: {
+        ...queryParms,
+        ...(pagination.pageSize !== DEFAULT_STATE.pageSize ? { size: pagination.pageSize } : {}),
+        ...(pagination.pageIndex !== DEFAULT_STATE.pageIndex ? { page: pagination.pageIndex } : {}),
+      },
+    });
+  }, [pagination]);
+
+  return {
+    pagination,
+    setPagination,
+    pageIndex: pagination.pageIndex,
+    pageSize: pagination.pageSize,
+  };
+}

package/src/hooks/useScrollableListBox.ts

@@ -0,0 +1,35 @@
+import { useEffect, useRef } from "react";
+
+import { useBreakpoint } from "#ui/hooks/useBreakpoint";
+
+export function useScrollableListBox() {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const isDesktop = useBreakpoint("md");
+
+  useEffect(() => {
+    const node = ref.current;
+    if (!node || isDesktop) {
+      return undefined;
+    }
+
+    const onPointerDownCapture = (e: PointerEvent) => {
+      e.stopPropagation();
+    };
+
+    const onClickCapture = (e: MouseEvent) => {
+      if ((e.currentTarget as HTMLDivElement)?.contains(e.target as Node) && e.target !== e.currentTarget) {
+        (e.target as HTMLElement).click();
+      }
+    };
+
+    node.addEventListener("pointerdown", onPointerDownCapture);
+    node.addEventListener("click", onClickCapture);
+
+    return () => {
+      node.removeEventListener("pointerdown", onPointerDownCapture);
+      node.removeEventListener("click", onClickCapture);
+    };
+  }, [ref, isDesktop]);
+
+  return { ref };
+}

package/src/hooks/useSingletonMutation.ts

@@ -0,0 +1,30 @@
+import { type UseMutationOptions, useMutation } from "@tanstack/react-query";
+import { useRef } from "react";
+
+export function useSingletonMutation<TData, TError, TVariables>({
+  mutationFn,
+  ...options
+}: UseMutationOptions<TData, TError, TVariables> &
+  Required<Pick<UseMutationOptions<TData, TError, TVariables>, "mutationFn">>) {
+  const mutationFnPromiseRef = useRef<Promise<TData> | null>(null);
+
+  return useMutation<TData, TError, TVariables>({
+    ...options,
+    mutationFn: async (variables) => {
+      if (mutationFnPromiseRef.current) {
+        return mutationFnPromiseRef.current;
+      }
+
+      const promise = mutationFn(variables);
+
+      mutationFnPromiseRef.current = promise;
+
+      try {
+        const result = await promise;
+        return result;
+      } finally {
+        mutationFnPromiseRef.current = null;
+      }
+    },
+  });
+}

package/src/hooks/useSorting.ts

@@ -0,0 +1,39 @@
+import type { SortingState } from "@tanstack/react-table";
+import { useEffect, useMemo, useState } from "react";
+
+import { UIRouter } from "../config/router.context";
+
+export function useSorting(defaultSorting?: SortingState, prefix = "") {
+  const { pathname, replace, searchParams, query } = UIRouter.useUIRouter();
+
+  const [sorting, setSorting] = useState<SortingState>(
+    defaultSorting ??
+      searchParams
+        .get(`order${prefix && `-${prefix}`}`)
+        ?.split(",")
+        .map((item: string) => {
+          if (item.startsWith("-")) {
+            return { id: item.slice(1), desc: true };
+          }
+          if (item.startsWith("+")) {
+            return { id: item.slice(1), desc: false };
+          }
+          return { id: item, desc: false };
+        }) ??
+      [],
+  );
+
+  const order = useMemo(() => {
+    return sorting.map((field) => `${field.desc ? "-" : "+"}${field.id}`).join(",");
+  }, [sorting]);
+
+  useEffect(() => {
+    const { sort: _sort, ...queryParms } = query;
+    replace({
+      pathname,
+      query: { ...queryParms, ...(order ? { [`order${prefix && `-${prefix}`}`]: order } : {}) },
+    });
+  }, [order]);
+
+  return { sorting, setSorting, order };
+}

package/src/hooks/useStateAndRef.ts

@@ -0,0 +1,20 @@
+import { type RefObject, type SetStateAction, useCallback, useRef, useState } from "react";
+
+import { ObjectUtils } from "#ui/utils/object.utils";
+
+type StateRefReturn<T> = [T, RefObject<T>, (value: SetStateAction<T>) => void];
+
+export const useStateAndRef = <T>(initialState: T | (() => T)): StateRefReturn<T> => {
+  const [state, setState] = useState<T>(initialState);
+  const ref = useRef<T>(state);
+
+  const updateValue = useCallback(
+    (value: SetStateAction<T>) => {
+      ref.current = ObjectUtils.isFunction(value) ? value(ref.current) : value;
+      setState(ref.current);
+    },
+    [setState],
+  );
+
+  return [state, ref, updateValue];
+};