@bigbinary/neeto-commons-frontend 2.0.59 → 2.0.61

package/react-utils.d.ts

@@ -1,120 +1,343 @@
+import dayjs from "dayjs";
 import React from "react";
-
-import { RouteProps } from "react-router-dom";
-import { Notice } from "@honeybadger-io/js/dist/server/types/core/types";
-import { History } from "history";
-import { StoreApi, UseBoundStore } from "zustand";
-
-export const HoneybadgerErrorBoundary: React.FC<{
-  ErrorComponent?: React.ReactNode | React.ComponentType<any>;
-  filterErrors?: (error: Notice) => boolean;
-}>;
-
-export function PrivateRoute(
-  props: {
-    condition?: boolean;
-    redirectRoute?: string;
-    errorPage?: React.ReactNode;
-  } & RouteProps
-): JSX.Element;
-
-type OptionsType = {
-  root?: Element | null;
-  rootMargin?: String;
-  threshold?: Number | Number[];
+export function resetAuthTokens(): void;
+/**
+ *
+ * Curried: true
+ *
+ * It is a curried function that accepts a function as the first parameter and an
+ *
+ * event as the second, and executes the given function with event.target.value
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * const onChange = val => console.log(`Value = ${val}`);
+ * 
+ * <input onChange={withEventTargetValue(onChange)} />;
+ * 
+ * // For example, in this case when user types "1" in the input field, "Value = 1" will be printed in the console.
+ * @endexample
+*/
+export function withEventTargetValue(func: (value: string) => void, event: React.ChangeEventHandler<HTMLInputElement>): void;
+/**
+ *
+ * Curried: true
+ *
+ * It is a curried function that accepts a function as the first parameter and an
+ *
+ * event as the second, and executes the given function with event.target.value
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * const onChange = val => console.log(`Value = ${val}`);
+ * 
+ * <input onChange={withEventTargetValue(onChange)} />;
+ * 
+ * // For example, in this case when user types "1" in the input field, "Value = 1" will be printed in the console.
+ * @endexample
+*/
+export function withEventTargetValue(func: (value: string) => void): (event: React.ChangeEventHandler<HTMLInputElement>) => void;
+/**
+ *
+ * Curried: false
+ *
+ * This function returns the subdomain of the current URL.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * // Let the current url be "https://spinkart.example.com".
+ * getSubdomain();
+ * 
+ * // output: spinkart
+ * @endexample
+*/
+export function getSubdomain(): string;
+/**
+ *
+ * Curried: false
+ *
+ * Returns the specified hardcoded data after some delay for simulating an API
+ *
+ * call.
+ *
+ * This function will simulate an API call and retrieve the hardcoded success/error
+ *
+ * responses after some delay based on the given error probability. This function
+ *
+ * is helpful when we are building the frontend before the backend is ready.
+ *
+ * @example 
+ *
+ * simulateApiCall(hardCodedResponseData, hardCodedErrorResponse);
+ * @endexample
+*/
+export function simulateApiCall<T>(result: T, error?: any, errorProbability?: number, delayMs?: number): Promise<T>;
+/**
+ *
+ * Curried: false
+ *
+ * Copies the given string to clipboard and shows a success toaster message.
+ *
+ * This function accepts a string as an argument and copies it to the clipboard.
+ *
+ * Also, it accepts two optional arguments: a boolean flag to indicate whether a
+ *
+ * toaster should be shown and a message to be shown in the toaster. By default the
+ *
+ * show toaster flag is set to true and the toaster message is set to "Copied to
+ *
+ * clipboard!". You can override these defaults by passing the appropriate values
+ *
+ * to the function.
+ *
+ * @example 
+ *
+ * copyToClipboard("https://spinkart.example.com", {
+ *   showToastr: true,
+ *   message: "URL copied successfully!",
+ * });
+ * 
+ * // If the URL is copied to the clipboard, a toaster message will be shown with the message "URL copied successfully!"
+ * @endexample
+*/
+export function copyToClipboard(text: string, configs?: {
+  showToastr?: boolean;
+  message?: string;
+}): void;
+/**
+ *
+ * Curried: false
+ *
+ * Builds a URL by inflating route like template string (example:
+ *
+ * /products/:productId/variants/:id) using the given params. Any extra
+ *
+ * properties in the params will be attached as query parameters to the URL.
+ *
+ * @example 
+ *
+ * buildUrl("/products/:id", { id: "123" }); // output "/products/123"
+ * buildUrl("/products", { search: "abc" }); // output "/products?search=abc"
+ * buildUrl("/products/:productId/variants/:variantId/attributes", {
+ *   productId: "123",
+ *   variantId: "456",
+ *   search: "abc",
+ *   page: 1,
+ *   per_page: 10,
+ * }); // output "/products/123/variants/456/attributes?page=1&per_page=10&search=abc"
+ * @endexample
+*/
+export function buildUrl(route: string, params: object): string;
+type TimerType = {
+  lastUpdated: number;
+  interval: number;
 };
-export function useIsElementVisibleInDom(
-  target: Element | null,
-  options?: OptionsType
-): Boolean;
-
-export function useDebounce<T>(value: T, delay?: number): T;
-
-export function useFuncDebounce<F extends Function>(
-  func: F,
-  delay?: number
-): F & { cancel: () => void };
-
-export function useLocalStorage<T>(
-  key: string,
-  initialValue?: T
-): [T, (value: T) => void];
-
-export function useOnClickOutside<T>(
-  ref: React.MutableRefObject<T>,
-  handler: (event: MouseEvent | TouchEvent) => any
-);
-
-export function usePrevious<T>(value: T): T;
-
-export function useUpdateEffect(effect: () => void, deps: any[]): void;
-
-export function useDisplayErrorPage(): boolean;
-
-export const useErrorDisplayStore: UseBoundStore<
-  StoreApi<{
-    showErrorPage: boolean;
-    statusCode: number;
-  }>
->;
-
-type ZustandConfigType = (
-  set: (data: any) => void,
-  get: () => any,
-  api: any
-) => any;
-export function withImmutableActions(
-  config: ZustandConfigType
-): ZustandConfigType;
-
-export declare type ZustandStoreHook = {
-  (
-    selector: (state: any) => any,
-    comparator?: (a: any, b: any) => boolean
-  ): any;
-  (): any;
+/**
+ *
+ * The useTimer hook re-renders in the specified time interval. This can
+ *
+ * auto-update the rendered elapsed time in components without requiring the
+ *
+ * application to be manually refreshed.
+ *
+ * This hook accepts a single argument timerIntervalInSeconds, which is the
+ *
+ * number of seconds after which the component will re-render. The default value is
+ *
+ * 60 seconds.
+ *
+ * All invocations of useTimer hooks are attached to a single setInterval call
+ *
+ * which ticks every 1 second. So using that hook in multiple components won't
+ *
+ * cause any performance drop.
+ *
+ * Note that the maximum precision for useTimer hook is one second. In other
+ *
+ * words, there is a possibility that your component will take at most one more
+ *
+ * second than the scheduled time interval to re-render.
+ *
+ * @example 
+ *
+ * import { useTimer } from "neetocommons/react-utils";
+ * 
+ * const Component = () => {
+ *   useTimer(timerIntervalInSeconds);
+ * 
+ *   // Rest of the component
+ * };
+ * @endexample
+*/
+export function useTimer(interval: number): TimerType;
+type DateTimeType = string | number | dayjs.Dayjs | Date | null | undefined;
+export const timeFormat: {
+  fromNow: (time: DateTimeType) => string;
+  time: (time: DateTimeType) => string;
+  date: (time: DateTimeType) => string;
+  dateWeek: (time: DateTimeType) => string;
+  dateWeekWithoutYear: (time: DateTimeType) => string;
+  dateTime: (time: DateTimeType) => string;
+  dateWeekTime: (time: DateTimeType) => string;
+  extended: (time: DateTimeType) => string;
 };
-
-export function useFieldSubmit(onSubmit: () => any): {
-  current: HTMLInputElement & HTMLTextAreaElement;
+export const dateFormat: typeof timeFormat;
+/**
+ *
+ * Curried: false
+ *
+ * Converts the given number to a locale string (converts to a comma separated
+ *
+ * string). It automatically identifies the locale using globalProps. If a valid
+ *
+ * value isn't present in globalProps, it will rely on the current browser's
+ *
+ * locale.
+ *
+ * The function also accepts options, which will be forwarded to
+ *
+ * Number.prototype.toLocaleString, which can be used for additional
+ *
+ * configurations like rounding, currency, units etc.
+ *
+ * @example 
+ *
+ * toLocale(1000000); // "1,000,000" when locale is "en-US"
+ * toLocale(1000000); // "10,00,000" when locale is "en-IN"
+ * toLocale(1000000.987, { maximumFractionDigits: 2 }); // "1,000,000.99"
+ * toLocale(1000000.987, {
+ *   currencyDisplay: "narrowSymbol",
+ *   style: "currency",
+ *   currency: "INR",
+ * }); // "₹1,000,000.99"
+ * @endexample
+*/
+export function toLocale(number: string | number, options?: Intl.NumberFormatOptions): string;
+type qsOptionsType = {
+  comma?: boolean | undefined;
+  delimiter?: string | RegExp | undefined;
+  depth?: number | false | undefined;
+  decoder?: ((str: string, defaultDecoder: any, charset: string, type: "key" | "value") => any) | undefined;
+  arrayLimit?: number | undefined;
+  parseArrays?: boolean | undefined;
+  allowDots?: boolean | undefined;
+  plainObjects?: boolean | undefined;
+  allowPrototypes?: boolean | undefined;
+  parameterLimit?: number | undefined;
+  strictNullHandling?: boolean | undefined;
+  ignoreQueryPrefix?: boolean | undefined;
+  charset?: "utf-8" | "iso-8859-1" | undefined;
+  charsetSentinel?: boolean | undefined;
+  interpretNumericEntities?: boolean | undefined;
 };
-
-export function withTitle(
-  Component: () => JSX.Element,
-  title?: string
-): (props) => JSX.Element;
-
-export async function registerBrowserNotifications(): Promise<void>;
-
-export async function destroyBrowserSubscription(): Promise<void>;
-
-export function handleMetaClick(
-  history: History,
-  params: string | object,
-  event: React.MouseEvent<HTMLElement, MouseEvent>
-): void;
-export function handleMetaClick(
-  history: History,
-  params: string | object
-): (event: React.MouseEvent<HTMLElement, MouseEvent>) => void;
-export function handleMetaClick(
-  history: History
-): (
-  params: string | object,
-  event: React.MouseEvent<HTMLElement, MouseEvent>
-) => void;
-
-export function isMetaKeyPressed(
-  event: React.MouseEvent<HTMLElement, MouseEvent>
-): boolean;
-
-type ConfigType = {
-  mode?: "default" | "global" | "scoped";
-  unbindOnUnmount?: boolean;
-  enabled?: boolean;
+type QueryParamsType = {
+  [key: string]: any;
 };
-export function useHotKeys(
-  hotkey: string | string[],
-  handler: (event: React.KeyboardEvent) => void,
-  config?: ConfigType
-): React.MutableRefObject | null;
+/**
+ *
+ * Curried: false
+ *
+ * This function returns all the query parameters of the current URL as an object.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * // Let the current url be "https://example.com?search=something&sort=date".
+ * getQueryParams();
+ * 
+ * // output: { search: "something", sort: "date" }
+ * @endexample
+*/
+export function getQueryParams(options?: qsOptionsType): QueryParamsType;
+/**
+ *
+ * Curried: false
+ *
+ * This function joins the given strings with hyphen.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * joinHyphenCase("hello", "world"); // output: "hello-world"
+ * @endexample
+*/
+export function joinHyphenCase(...args: string[]): string;
+/**
+ *
+ * Curried: false
+ *
+ * Creates a debounced function that will execute the given function after the
+ *
+ * stated wait time in milliseconds has elapsed since the last time it was invoked.
+ *
+ * It accepts the function to be debounced as the first argument, the delay in
+ *
+ * milliseconds as the second argument.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * const searchForProducts = debounce(async key => {
+ *   // this function will be triggered once after user stops typing for 300ms
+ *   const products = await productsApi.fetch(key);
+ *   // do something with the products
+ * }, 300);
+ * <input onChange={e => searchForProducts(e.target.value)} />;
+ * @endexample
+*/
+export function debounce<F extends Function>(func: F, delay?: number): F;
+/**
+ *
+ * Curried: false
+ *
+ * This function will return true if the current user has the given permission.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * hasPermission("user.view_settings");
+ * @endexample
+*/
+export function hasPermission(permission: string): boolean;
+/**
+ *
+ * Curried: false
+ *
+ * This function will return true if the current user has any of the given
+ *
+ * permissions.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * hasAnyPermission("user.view_settings", "user.edit_settings");
+ * @endexample
+*/
+export function hasAnyPermission(...permissions: string[]): boolean;
+/**
+ *
+ * Curried: false
+ *
+ * This function will return true if the current user has all of the given
+ *
+ * permissions.
+ *
+ * Usage:
+ *
+ * @example 
+ *
+ * hasAllPermissions("user.view_settings", "user.edit_settings");
+ * @endexample
+*/
+export function hasAllPermissions(...permissions: string[]): boolean;