@hairy/react-lib 1.47.0 → 1.50.0

package/dist/index.d.cts

@@ -0,0 +1,258 @@
+import { AnyFn, BooleanLike, Deferred, PromiseFn, PromiseType } from "@hairy/utils";
+import * as react from "react";
+import { ComponentClass, DetailedHTMLProps, FC, HTMLAttributes, JSX, PropsWithChildren, ReactElement, ReactNode, useCallback, useEffect, useInsertionEffect, useReducer, useRef, useState } from "react";
+
+//#region src/utils/cls.d.ts
+type Value = string | boolean | undefined | null;
+type Mapping = Record<string, any>;
+interface ArgumentArray extends Array<Argument> {}
+interface ReadonlyArgumentArray extends ReadonlyArray<Argument> {}
+type Argument = Value | Mapping | ArgumentArray | ReadonlyArgumentArray;
+/**
+ * A simple JavaScript utility for conditionally joining classNames together.
+ */
+declare function cls(...args: ArgumentArray): string;
+declare namespace cls {
+  var parse: (arg: any) => string;
+  var append: (value: any, newClass: any) => any;
+}
+//#endregion
+//#region src/utils/track.d.ts
+/**
+ * @requires `Trigger` component to be mounted in the tree.
+ *
+ * @example
+ * ```tsx
+ * // Obtain externally
+ * import { track } from '@hairy/lib-react'
+ * const context = await track(() => useContext(YourContext))
+ * console.log(context) // { ... }
+ * ```
+ */
+declare function track<T extends AnyFn>(fn: T, ...args: Parameters<T>): Promise<ReturnType<T>>;
+//#endregion
+//#region src/utils/wrapper.d.ts
+type WrapperTag = keyof JSX.IntrinsicElements | Function;
+type WrapperProps<As extends keyof JSX.IntrinsicElements | React.FC | unknown> = {
+  /** @deprecated use `as` instead */tag?: As;
+  as?: As;
+} & (As extends keyof JSX.IntrinsicElements ? JSX.IntrinsicElements[As] : unknown) & (As extends React.FC<infer P> ? P : unknown);
+declare function wrapper(asChild: any, props: unknown, children?: React.ReactNode): react.ReactNode;
+//#endregion
+//#region src/components/condition/Case.d.ts
+type CaseProps<Kag> = WrapperProps<Kag> & {
+  cond?: BooleanLike;
+  children?: ReactNode;
+};
+declare function Case<Tag extends WrapperTag>(props: CaseProps<Tag>): ReactNode;
+//#endregion
+//#region src/components/condition/Default.d.ts
+type DefaultProps<Tag> = WrapperProps<Tag> & {
+  children?: ReactNode;
+};
+declare function Default<Tag extends WrapperTag>(props: DefaultProps<Tag>): ReactNode;
+//#endregion
+//#region src/components/condition/If.d.ts
+type IfProps<Kag> = WrapperProps<Kag> & {
+  cond?: BooleanLike;
+  then?: ReactNode;
+  else?: ReactNode;
+  children?: ReactNode;
+};
+declare function If<K extends WrapperTag>(props: IfProps<K>): ReactNode;
+//#endregion
+//#region src/components/condition/Else.d.ts
+type ElseProps<Tag> = IfProps<Tag>;
+declare function Else<Tag extends WrapperTag>(props: ElseProps<Tag>): react.ReactNode;
+//#endregion
+//#region src/components/condition/Switch.d.ts
+interface SwitchProps extends PropsWithChildren {
+  value?: BooleanLike;
+}
+declare function Switch(props: SwitchProps): ReactElement<unknown, string | react.JSXElementConstructor<any>> | null;
+//#endregion
+//#region src/components/condition/Then.d.ts
+type ThenProps<Tag> = IfProps<Tag>;
+declare function Then<Tag extends WrapperTag>(props: ThenProps<Tag>): react.ReactNode;
+//#endregion
+//#region src/components/condition/Unless.d.ts
+type UnlessProps<Tag> = WrapperProps<Tag> & {
+  cond?: BooleanLike;
+  then?: ReactNode;
+  else?: ReactNode;
+  children?: ReactNode;
+};
+declare function Unless<Tag extends WrapperTag>(props: UnlessProps<Tag>): ReactNode;
+//#endregion
+//#region src/components/utils/Injector.d.ts
+interface InjectComponent<P> {
+  component: FC<P> | ComponentClass<P>;
+  props?: P;
+}
+interface InjectorProps {
+  install: (FC<any> | InjectComponent<any> | ComponentClass<any>)[];
+  children?: ReactNode;
+}
+declare function Injector(props: InjectorProps): ReactNode;
+//#endregion
+//#region src/components/utils/Trigger.d.ts
+interface Exposer {
+  deferred: Deferred<any>;
+  args: any[];
+  fn: AnyFn;
+  id: number;
+}
+/**
+ * @example
+ * ```tsx
+ * import { Trigger } from '@hairy/lib-react'
+ *
+ * // Use triggers to capture context
+ * function App() {
+ *  return (
+ *   <YourContext.Provider>
+ *    <Trigger />
+ *   </YourContext.Provider>
+ *  )
+ * }
+ *
+ * // Obtain externally
+ * import { track } from '@hairy/lib-react'
+ * const context = await track(() => useContext(YourContext))
+ * console.log(context) // { ... }
+ * ```
+ */
+declare function Trigger(): ReactNode[];
+declare namespace Trigger {
+  var id: number;
+  var tasks: Map<number, Exposer> & {
+    $$valtioSnapshot: Omit<Map<number, Exposer>, "set" | "delete" | "clear">;
+  };
+}
+//#endregion
+//#region src/hooks/tryUseCallback.d.ts
+declare const tryUseCallback: typeof useCallback;
+//#endregion
+//#region src/hooks/tryUseEffect.d.ts
+declare const tryUseEffect: typeof useEffect;
+//#endregion
+//#region src/hooks/tryUseInsertionEffect.d.ts
+declare const tryUseInsertionEffect: typeof useInsertionEffect;
+//#endregion
+//#region src/hooks/tryUseReducer.d.ts
+declare const tryUseReducer: typeof useReducer;
+//#endregion
+//#region src/hooks/tryUseRef.d.ts
+declare const tryUseRef: typeof useRef;
+//#endregion
+//#region src/hooks/tryUseState.d.ts
+declare const tryUseState: typeof useState;
+//#endregion
+//#region src/hooks/tryUseUpdate.d.ts
+declare function tryUseUpdate(): () => void;
+//#endregion
+//#region src/hooks/useAsyncCallback.d.ts
+declare function useAsyncCallback<T extends PromiseFn>(fun: T): readonly [boolean, T, Error | undefined];
+//#endregion
+//#region src/hooks/types/index.d.ts
+type AsyncState<T> = {
+  loading: boolean;
+  error?: undefined;
+  value?: undefined;
+} | {
+  loading: true;
+  error?: Error | undefined;
+  value?: T;
+} | {
+  loading: false;
+  error: Error;
+  value?: undefined;
+} | {
+  loading: false;
+  error?: undefined;
+  value: T;
+};
+type StateFromFnReturningPromise<T extends PromiseFn = PromiseFn> = AsyncState<PromiseType<ReturnType<T>>>;
+declare type AsyncStateReturn<T extends PromiseFn = PromiseFn> = [StateFromFnReturningPromise<T>, T];
+//#endregion
+//#region src/hooks/useAsyncState.d.ts
+type UseAsyncStateOptions<T extends AnyFn> = {
+  immediate?: boolean;
+  initial?: PromiseType<ReturnType<T>>;
+  deps?: any[];
+} | {
+  immediate?: boolean;
+  initial: PromiseType<ReturnType<T>>;
+  deps?: any[];
+};
+declare function useAsyncState<T extends PromiseFn>(fun: T, deps?: any[], options?: UseAsyncStateOptions<T>): AsyncStateReturn<T>;
+//#endregion
+//#region src/hooks/useDebounce.d.ts
+declare function useDebounce<T>(value: T, delay: number): T;
+//#endregion
+//#region src/hooks/useEventBus.d.ts
+interface EventBusListener<T = any> {
+  (event: T): void;
+}
+declare function useEventBus<T>(key: string): {
+  on: (listener: EventBusListener<T>) => void;
+  emit: (event?: T) => void;
+  off: (listener: EventBusListener) => void;
+};
+//#endregion
+//#region src/hooks/useFetchIntercept.d.ts
+interface FetchResponseInterceptCallback {
+  (response: Response, init: RequestInit | undefined): Response | Promise<Response>;
+}
+interface FetchRequestInterceptCallback {
+  (fetch: typeof window.fetch, input: RequestInfo | URL, init?: RequestInit | undefined): Response | Promise<Response>;
+}
+declare function useFetchResponseIntercept(intercept: FetchResponseInterceptCallback): void;
+declare function useFetchRequestIntercept(intercept: FetchRequestInterceptCallback): void;
+//#endregion
+//#region src/hooks/useMounted.d.ts
+declare function useMounted(): boolean;
+//#endregion
+//#region src/hooks/useOffsetPagination.d.ts
+interface UseOffsetPaginationOptions {
+  total?: number;
+  page?: number;
+  pageSize?: number;
+  onChange?: (pagination: Pagination) => void;
+  onPageSizeChange?: (pagination: Pagination) => void;
+  onPageCountChange?: (pagination: Pagination) => void;
+}
+interface Pagination {
+  pageSizeChange: (limit: number) => void;
+  pageChange: (page: number) => void;
+  next: () => void;
+  prev: () => void;
+  page: number;
+  pageSize: number;
+  isFirstPage: boolean;
+  isLastPage: boolean;
+  pageCount: number;
+  total: number;
+}
+declare function useOffsetPagination(options: UseOffsetPaginationOptions): Pagination;
+//#endregion
+//#region src/hooks/useUpdate.d.ts
+declare function useUpdate(): () => void;
+//#endregion
+//#region src/hooks/useWatch.d.ts
+interface UseWatchCallback<T = any> {
+  (value: T, oldValue: T): void;
+}
+interface UseWatchOptions {
+  immediate?: boolean;
+}
+declare function useWatch<T extends any[]>(source: readonly [...T], callback: UseWatchCallback<[...T]>, options?: UseWatchOptions): void;
+declare function useWatch<T>(source: T, callback: UseWatchCallback<T>, options?: UseWatchOptions): void;
+//#endregion
+//#region src/hooks/useWhenever.d.ts
+declare function useWhenever<T>(source: T, cb: UseWatchCallback<Exclude<T, null | undefined>>, options?: UseWatchOptions): void;
+//#endregion
+//#region src/types/index.d.ts
+type PropsWithDetailedHTML<T = HTMLDivElement> = DetailedHTMLProps<HTMLAttributes<T>, T>;
+//#endregion
+export { Argument, ArgumentArray, Case, CaseProps, Default, DefaultProps, Else, ElseProps, EventBusListener, Exposer, FetchRequestInterceptCallback, FetchResponseInterceptCallback, If, IfProps, InjectComponent, Injector, InjectorProps, Mapping, Pagination, PropsWithDetailedHTML, ReadonlyArgumentArray, Switch, SwitchProps, Then, ThenProps, Trigger, Unless, UnlessProps, UseAsyncStateOptions, UseOffsetPaginationOptions, UseWatchCallback, UseWatchOptions, Value, WrapperProps, WrapperTag, cls, track, tryUseCallback, tryUseEffect, tryUseInsertionEffect, tryUseReducer, tryUseRef, tryUseState, tryUseUpdate, useAsyncCallback, useAsyncState, useDebounce, useEventBus, useFetchRequestIntercept, useFetchResponseIntercept, useMounted, useOffsetPagination, useUpdate, useWatch, useWhenever, wrapper };

package/dist/index.d.mts

@@ -0,0 +1,258 @@
+import { AnyFn, BooleanLike, Deferred, PromiseFn, PromiseType } from "@hairy/utils";
+import * as react from "react";
+import { ComponentClass, DetailedHTMLProps, FC, HTMLAttributes, JSX, PropsWithChildren, ReactElement, ReactNode, useCallback, useEffect, useInsertionEffect, useReducer, useRef, useState } from "react";
+
+//#region src/utils/cls.d.ts
+type Value = string | boolean | undefined | null;
+type Mapping = Record<string, any>;
+interface ArgumentArray extends Array<Argument> {}
+interface ReadonlyArgumentArray extends ReadonlyArray<Argument> {}
+type Argument = Value | Mapping | ArgumentArray | ReadonlyArgumentArray;
+/**
+ * A simple JavaScript utility for conditionally joining classNames together.
+ */
+declare function cls(...args: ArgumentArray): string;
+declare namespace cls {
+  var parse: (arg: any) => string;
+  var append: (value: any, newClass: any) => any;
+}
+//#endregion
+//#region src/utils/track.d.ts
+/**
+ * @requires `Trigger` component to be mounted in the tree.
+ *
+ * @example
+ * ```tsx
+ * // Obtain externally
+ * import { track } from '@hairy/lib-react'
+ * const context = await track(() => useContext(YourContext))
+ * console.log(context) // { ... }
+ * ```
+ */
+declare function track<T extends AnyFn>(fn: T, ...args: Parameters<T>): Promise<ReturnType<T>>;
+//#endregion
+//#region src/utils/wrapper.d.ts
+type WrapperTag = keyof JSX.IntrinsicElements | Function;
+type WrapperProps<As extends keyof JSX.IntrinsicElements | React.FC | unknown> = {
+  /** @deprecated use `as` instead */tag?: As;
+  as?: As;
+} & (As extends keyof JSX.IntrinsicElements ? JSX.IntrinsicElements[As] : unknown) & (As extends React.FC<infer P> ? P : unknown);
+declare function wrapper(asChild: any, props: unknown, children?: React.ReactNode): react.ReactNode;
+//#endregion
+//#region src/components/condition/Case.d.ts
+type CaseProps<Kag> = WrapperProps<Kag> & {
+  cond?: BooleanLike;
+  children?: ReactNode;
+};
+declare function Case<Tag extends WrapperTag>(props: CaseProps<Tag>): ReactNode;
+//#endregion
+//#region src/components/condition/Default.d.ts
+type DefaultProps<Tag> = WrapperProps<Tag> & {
+  children?: ReactNode;
+};
+declare function Default<Tag extends WrapperTag>(props: DefaultProps<Tag>): ReactNode;
+//#endregion
+//#region src/components/condition/If.d.ts
+type IfProps<Kag> = WrapperProps<Kag> & {
+  cond?: BooleanLike;
+  then?: ReactNode;
+  else?: ReactNode;
+  children?: ReactNode;
+};
+declare function If<K extends WrapperTag>(props: IfProps<K>): ReactNode;
+//#endregion
+//#region src/components/condition/Else.d.ts
+type ElseProps<Tag> = IfProps<Tag>;
+declare function Else<Tag extends WrapperTag>(props: ElseProps<Tag>): react.ReactNode;
+//#endregion
+//#region src/components/condition/Switch.d.ts
+interface SwitchProps extends PropsWithChildren {
+  value?: BooleanLike;
+}
+declare function Switch(props: SwitchProps): ReactElement<unknown, string | react.JSXElementConstructor<any>> | null;
+//#endregion
+//#region src/components/condition/Then.d.ts
+type ThenProps<Tag> = IfProps<Tag>;
+declare function Then<Tag extends WrapperTag>(props: ThenProps<Tag>): react.ReactNode;
+//#endregion
+//#region src/components/condition/Unless.d.ts
+type UnlessProps<Tag> = WrapperProps<Tag> & {
+  cond?: BooleanLike;
+  then?: ReactNode;
+  else?: ReactNode;
+  children?: ReactNode;
+};
+declare function Unless<Tag extends WrapperTag>(props: UnlessProps<Tag>): ReactNode;
+//#endregion
+//#region src/components/utils/Injector.d.ts
+interface InjectComponent<P> {
+  component: FC<P> | ComponentClass<P>;
+  props?: P;
+}
+interface InjectorProps {
+  install: (FC<any> | InjectComponent<any> | ComponentClass<any>)[];
+  children?: ReactNode;
+}
+declare function Injector(props: InjectorProps): ReactNode;
+//#endregion
+//#region src/components/utils/Trigger.d.ts
+interface Exposer {
+  deferred: Deferred<any>;
+  args: any[];
+  fn: AnyFn;
+  id: number;
+}
+/**
+ * @example
+ * ```tsx
+ * import { Trigger } from '@hairy/lib-react'
+ *
+ * // Use triggers to capture context
+ * function App() {
+ *  return (
+ *   <YourContext.Provider>
+ *    <Trigger />
+ *   </YourContext.Provider>
+ *  )
+ * }
+ *
+ * // Obtain externally
+ * import { track } from '@hairy/lib-react'
+ * const context = await track(() => useContext(YourContext))
+ * console.log(context) // { ... }
+ * ```
+ */
+declare function Trigger(): ReactNode[];
+declare namespace Trigger {
+  var id: number;
+  var tasks: Map<number, Exposer> & {
+    $$valtioSnapshot: Omit<Map<number, Exposer>, "set" | "delete" | "clear">;
+  };
+}
+//#endregion
+//#region src/hooks/tryUseCallback.d.ts
+declare const tryUseCallback: typeof useCallback;
+//#endregion
+//#region src/hooks/tryUseEffect.d.ts
+declare const tryUseEffect: typeof useEffect;
+//#endregion
+//#region src/hooks/tryUseInsertionEffect.d.ts
+declare const tryUseInsertionEffect: typeof useInsertionEffect;
+//#endregion
+//#region src/hooks/tryUseReducer.d.ts
+declare const tryUseReducer: typeof useReducer;
+//#endregion
+//#region src/hooks/tryUseRef.d.ts
+declare const tryUseRef: typeof useRef;
+//#endregion
+//#region src/hooks/tryUseState.d.ts
+declare const tryUseState: typeof useState;
+//#endregion
+//#region src/hooks/tryUseUpdate.d.ts
+declare function tryUseUpdate(): () => void;
+//#endregion
+//#region src/hooks/useAsyncCallback.d.ts
+declare function useAsyncCallback<T extends PromiseFn>(fun: T): readonly [boolean, T, Error | undefined];
+//#endregion
+//#region src/hooks/types/index.d.ts
+type AsyncState<T> = {
+  loading: boolean;
+  error?: undefined;
+  value?: undefined;
+} | {
+  loading: true;
+  error?: Error | undefined;
+  value?: T;
+} | {
+  loading: false;
+  error: Error;
+  value?: undefined;
+} | {
+  loading: false;
+  error?: undefined;
+  value: T;
+};
+type StateFromFnReturningPromise<T extends PromiseFn = PromiseFn> = AsyncState<PromiseType<ReturnType<T>>>;
+declare type AsyncStateReturn<T extends PromiseFn = PromiseFn> = [StateFromFnReturningPromise<T>, T];
+//#endregion
+//#region src/hooks/useAsyncState.d.ts
+type UseAsyncStateOptions<T extends AnyFn> = {
+  immediate?: boolean;
+  initial?: PromiseType<ReturnType<T>>;
+  deps?: any[];
+} | {
+  immediate?: boolean;
+  initial: PromiseType<ReturnType<T>>;
+  deps?: any[];
+};
+declare function useAsyncState<T extends PromiseFn>(fun: T, deps?: any[], options?: UseAsyncStateOptions<T>): AsyncStateReturn<T>;
+//#endregion
+//#region src/hooks/useDebounce.d.ts
+declare function useDebounce<T>(value: T, delay: number): T;
+//#endregion
+//#region src/hooks/useEventBus.d.ts
+interface EventBusListener<T = any> {
+  (event: T): void;
+}
+declare function useEventBus<T>(key: string): {
+  on: (listener: EventBusListener<T>) => void;
+  emit: (event?: T) => void;
+  off: (listener: EventBusListener) => void;
+};
+//#endregion
+//#region src/hooks/useFetchIntercept.d.ts
+interface FetchResponseInterceptCallback {
+  (response: Response, init: RequestInit | undefined): Response | Promise<Response>;
+}
+interface FetchRequestInterceptCallback {
+  (fetch: typeof window.fetch, input: RequestInfo | URL, init?: RequestInit | undefined): Response | Promise<Response>;
+}
+declare function useFetchResponseIntercept(intercept: FetchResponseInterceptCallback): void;
+declare function useFetchRequestIntercept(intercept: FetchRequestInterceptCallback): void;
+//#endregion
+//#region src/hooks/useMounted.d.ts
+declare function useMounted(): boolean;
+//#endregion
+//#region src/hooks/useOffsetPagination.d.ts
+interface UseOffsetPaginationOptions {
+  total?: number;
+  page?: number;
+  pageSize?: number;
+  onChange?: (pagination: Pagination) => void;
+  onPageSizeChange?: (pagination: Pagination) => void;
+  onPageCountChange?: (pagination: Pagination) => void;
+}
+interface Pagination {
+  pageSizeChange: (limit: number) => void;
+  pageChange: (page: number) => void;
+  next: () => void;
+  prev: () => void;
+  page: number;
+  pageSize: number;
+  isFirstPage: boolean;
+  isLastPage: boolean;
+  pageCount: number;
+  total: number;
+}
+declare function useOffsetPagination(options: UseOffsetPaginationOptions): Pagination;
+//#endregion
+//#region src/hooks/useUpdate.d.ts
+declare function useUpdate(): () => void;
+//#endregion
+//#region src/hooks/useWatch.d.ts
+interface UseWatchCallback<T = any> {
+  (value: T, oldValue: T): void;
+}
+interface UseWatchOptions {
+  immediate?: boolean;
+}
+declare function useWatch<T extends any[]>(source: readonly [...T], callback: UseWatchCallback<[...T]>, options?: UseWatchOptions): void;
+declare function useWatch<T>(source: T, callback: UseWatchCallback<T>, options?: UseWatchOptions): void;
+//#endregion
+//#region src/hooks/useWhenever.d.ts
+declare function useWhenever<T>(source: T, cb: UseWatchCallback<Exclude<T, null | undefined>>, options?: UseWatchOptions): void;
+//#endregion
+//#region src/types/index.d.ts
+type PropsWithDetailedHTML<T = HTMLDivElement> = DetailedHTMLProps<HTMLAttributes<T>, T>;
+//#endregion
+export { Argument, ArgumentArray, Case, CaseProps, Default, DefaultProps, Else, ElseProps, EventBusListener, Exposer, FetchRequestInterceptCallback, FetchResponseInterceptCallback, If, IfProps, InjectComponent, Injector, InjectorProps, Mapping, Pagination, PropsWithDetailedHTML, ReadonlyArgumentArray, Switch, SwitchProps, Then, ThenProps, Trigger, Unless, UnlessProps, UseAsyncStateOptions, UseOffsetPaginationOptions, UseWatchCallback, UseWatchOptions, Value, WrapperProps, WrapperTag, cls, track, tryUseCallback, tryUseEffect, tryUseInsertionEffect, tryUseReducer, tryUseRef, tryUseState, tryUseUpdate, useAsyncCallback, useAsyncState, useDebounce, useEventBus, useFetchRequestIntercept, useFetchResponseIntercept, useMounted, useOffsetPagination, useUpdate, useWatch, useWhenever, wrapper };