@maxax/hooks 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,443 @@
+import * as vue from 'vue';
+import { ComputedRef, Ref, InjectionKey, CSSProperties, WritableComputedRef, ShallowRef, ComputedGetter, DebuggerOptions, WritableComputedOptions, Component } from 'vue';
+import { VisibleDomRect } from '@maxax/utils';
+import { AxiosError, ResponseType, CustomAxiosRequestConfig, MappedType } from '@maxax/axios';
+
+/**
+ * Boolean
+ *
+ * @param initValue Init value
+ */
+declare function useBoolean(initValue?: boolean): {
+    bool: vue.Ref<boolean, boolean>;
+    setBool: (value: boolean) => void;
+    setTrue: () => void;
+    setFalse: () => void;
+    toggle: () => void;
+};
+
+declare enum SizeEnum {
+    XS = "XS",
+    SM = "SM",
+    MD = "MD",
+    LG = "LG",
+    XL = "XL",
+    XXL = "XXL"
+}
+declare enum ScreenEnum {
+    XS = 320,
+    SM = 640,
+    MD = 768,
+    LG = 960,
+    XL = 1280,
+    XXL = 1536
+}
+
+interface CreateCallbackParams {
+    screen: ComputedRef<SizeEnum | undefined>;
+    width: ComputedRef<number>;
+    realWidth: ComputedRef<number>;
+    screenEnum: typeof ScreenEnum;
+    screenMap: Map<SizeEnum, number>;
+    sizeEnum: typeof SizeEnum;
+}
+declare function useBreakpoint(): {
+    screenRef: ComputedRef<SizeEnum | undefined>;
+    widthRef: ComputedRef<number>;
+    screenEnum: typeof ScreenEnum;
+    realWidthRef: ComputedRef<number>;
+};
+declare function createBreakpointListen(fn?: (opt: CreateCallbackParams) => void): {
+    screenRef: ComputedRef<SizeEnum | undefined>;
+    screenEnum: typeof ScreenEnum;
+    widthRef: ComputedRef<number>;
+    realWidthRef: ComputedRef<number>;
+};
+
+interface WindowLocation {
+    hash?: string;
+    host?: string;
+    hostname?: string;
+    href?: string;
+    origin?: string;
+    pathname?: string;
+    port?: string;
+    protocol?: string;
+    search?: string;
+}
+declare function useBrowserLocation(customWindow?: (Window & typeof globalThis) | null): Ref<WindowLocation>;
+
+declare function useInjectionInstanceCollection(injectionName: string | InjectionKey<unknown>, collectionKey: string, registerKeyRef: Ref<string | undefined>): void;
+declare function useInjectionCollection(injectionName: string | InjectionKey<unknown>, collectionKey: string, valueRef: Ref<any>): void;
+declare function useInjectionElementCollection(injectionName: string | InjectionKey<unknown>, collectionKey: string, getElement: () => HTMLElement | null): void;
+
+/**
+ * Use context
+ *
+ * @example
+ *   ```ts
+ *   // there are three vue files: A.vue, B.vue, C.vue, and A.vue is the parent component of B.vue and C.vue
+ *
+ *   // context.ts
+ *   import { ref } from 'vue';
+ *   import { useContext } from '@max/hooks';
+ *
+ *   export const { setupStore, useStore } = useContext('demo', () => {
+ *     const count = ref(0);
+ *
+ *     function increment() {
+ *       count.value++;
+ *     }
+ *
+ *     function decrement() {
+ *       count.value--;
+ *     }
+ *
+ *     return {
+ *       count,
+ *       increment,
+ *       decrement
+ *     };
+ *   })
+ *   ``` // A.vue
+ *   ```vue
+ *   <template>
+ *     <div>A</div>
+ *   </template>
+ *   <script setup lang="ts">
+ *   import { setupStore } from './context';
+ *
+ *   setupStore();
+ *   // const { increment } = setupStore(); // also can control the store in the parent component
+ *   </script>
+ *   ``` // B.vue
+ *   ```vue
+ *   <template>
+ *    <div>B</div>
+ *   </template>
+ *   <script setup lang="ts">
+ *   import { useStore } from './context';
+ *
+ *   const { count, increment } = useStore();
+ *   </script>
+ *   ```;
+ *
+ *   // C.vue is same as B.vue
+ *
+ * @param contextName Context name
+ * @param fn Context function
+ */
+declare function useContext<T extends (...args: any[]) => any>(contextName: string, fn: T): {
+    /** Setup store in the parent component */
+    setupStore: (...args: Parameters<T>) => ReturnType<T>;
+    /** Use store in the child component */
+    useStore: () => ReturnType<T>;
+};
+
+/**
+ * Count down
+ *
+ * @param seconds - count down seconds
+ */
+declare function useCountDown(seconds: number): {
+    count: vue.ComputedRef<number>;
+    isCounting: vue.ComputedRef<boolean>;
+    start: (updateSeconds?: number) => void;
+    stop: () => void;
+};
+
+declare function useDeferredTrue(valueRef: Ref<any>, delay: number, shouldDelayRef: Ref<boolean>): Ref<boolean>;
+
+type RemoveEventFn = () => void;
+interface UseEventParams {
+    el?: Element | Ref<Element | undefined> | Window | any;
+    name: string;
+    listener: EventListener;
+    options?: boolean | AddEventListenerOptions;
+    autoRemove?: boolean;
+    isDebounce?: boolean;
+    wait?: number;
+}
+declare function useEventListener({ el, name, listener, options, autoRemove, isDebounce, wait }: UseEventParams): {
+    removeEvent: RemoveEventFn;
+};
+
+declare function useIsComposing(): Ref<boolean>;
+
+declare function useLayoutContentStyle(diffHeight?: number): {
+    contentElement: vue.Ref<HTMLDivElement | null, HTMLDivElement | null>;
+    overlayStyle: vue.ComputedRef<CSSProperties>;
+    visibleDomRect: vue.Ref<{
+        bottom: number;
+        height: number;
+        left: number;
+        right: number;
+        top: number;
+        width: number;
+    } | null, VisibleDomRect | {
+        bottom: number;
+        height: number;
+        left: number;
+        right: number;
+        top: number;
+        width: number;
+    } | null>;
+};
+declare function useLayoutHeaderStyle(): {
+    getLayoutHeaderHeight: () => number;
+    setLayoutHeaderHeight: (height: number) => void;
+};
+declare function useLayoutFooterStyle(): {
+    getLayoutFooterHeight: () => number;
+    setLayoutFooterHeight: (height: number) => void;
+};
+
+/**
+ * Loading
+ *
+ * @param initValue Init value
+ */
+declare function useLoading(initValue?: boolean): {
+    loading: vue.Ref<boolean, boolean>;
+    startLoading: () => void;
+    endLoading: () => void;
+};
+
+declare function useLocalPage(list: any[], pageSize: number): {
+    setCurrentPage: (page: number) => void;
+    getTotal: vue.ComputedRef<number>;
+    setPageSize: (size: number) => void;
+    getPaginationList: vue.ComputedRef<any[]>;
+    setPagination: (page: {
+        currentPage: number;
+        pageSize: number;
+    }) => void;
+    getPageList: () => any[];
+};
+
+declare const lockHtmlScrollRightCompensationRef: Ref<string, string>;
+declare function useLockHtmlScroll(lockRef: Ref<boolean>): void;
+
+type MemoGetter<T> = () => T;
+type MemoSetter<T> = (v: T) => void;
+interface WritableMemoOptions<T> {
+    get: MemoGetter<T>;
+    set: MemoSetter<T>;
+}
+declare function useMemo<T>(getter: MemoGetter<T>): ComputedRef<T>;
+declare function useMemo<T>(options: WritableMemoOptions<T>): WritableComputedRef<T>;
+
+declare function useMergedState<T>(controlledStateRef: Ref<T | undefined>, uncontrolledStateRef: Ref<T>): ComputedRef<T>;
+
+interface HookRequestInstanceResponseSuccessData<T = any> {
+    data: Ref<T>;
+    error: Ref<null>;
+}
+interface HookRequestInstanceResponseFailData<ResponseData = any> {
+    data: Ref<null>;
+    error: Ref<AxiosError<ResponseData>>;
+}
+type HookRequestInstanceResponseData<T = any, ResponseData = any> = {
+    loading: Ref<boolean>;
+} & (HookRequestInstanceResponseSuccessData<T> | HookRequestInstanceResponseFailData<ResponseData>);
+interface HookRequestInstance<ResponseData = any> {
+    <T = any, R extends ResponseType = 'json'>(config: CustomAxiosRequestConfig): HookRequestInstanceResponseData<MappedType<R, T>, ResponseData>;
+    cancelRequest: (requestId: string) => void;
+    cancelAllRequest: () => void;
+}
+
+interface ScriptOptions {
+    src: string;
+}
+declare function useScript(opts: ScriptOptions): {
+    isLoading: vue.Ref<boolean, boolean>;
+    error: vue.Ref<boolean, boolean>;
+    success: vue.Ref<boolean, boolean>;
+    toPromise: () => Promise<unknown>;
+};
+
+declare function useScroll(refEl: Ref<Element | Window | null>, options?: {
+    wait?: number;
+    leading?: boolean;
+    trailing?: boolean;
+}): {
+    refX: Ref<number, number>;
+    refY: Ref<number, number>;
+    stop: () => void;
+};
+
+type Updater<T> = (value: T) => T;
+type Mutator<T> = (value: T) => void;
+/**
+ * Signal is a reactive value that can be set, updated or mutated
+ *
+ * @example
+ *   ```ts
+ *   const count = useSignal(0);
+ *
+ *   // `watchEffect`
+ *   watchEffect(() => {
+ *   console.log(count());
+ *   });
+ *
+ *   // watch
+ *   watch(count, value => {
+ *   console.log(value);
+ *   });
+ *
+ *   // useComputed
+ *   const double = useComputed(() => count() * 2);
+ *   const writeableDouble = useComputed({
+ *   get: () => count() * 2,
+ *   set: value => count.set(value / 2)
+ *   });
+ *   ```
+ */
+interface Signal<T> {
+    (): Readonly<T>;
+    /**
+     * Set the value of the signal
+     *
+     * It recommend use `set` for primitive values
+     *
+     * @param value
+     */
+    set: (value: T) => void;
+    /**
+     * Update the value of the signal using an updater function
+     *
+     * It recommend use `update` for non-primitive values, only the first level of the object will be reactive.
+     *
+     * @param updater
+     */
+    update: (updater: Updater<T>) => void;
+    /**
+     * Mutate the value of the signal using a mutator function
+     *
+     * this action will call `triggerRef`, so the value will be tracked on `watchEffect`.
+     *
+     * It recommend use `mutate` for non-primitive values, all levels of the object will be reactive.
+     *
+     * @param mutator
+     */
+    mutate: (mutator: Mutator<T>) => void;
+    /**
+     * Get the reference of the signal
+     *
+     * Sometimes it can be useful to make `v-model` work with the signal
+     *
+     * ```vue
+     * <template>
+     *   <input v-model="model.count" />
+     * </template>;
+     *
+     * <script setup lang="ts">
+     *  const state = useSignal({ count: 0 }, { useRef: true });
+     *
+     *  const model = state.getRef();
+     * </script>
+     * ```
+     */
+    getRef: () => Readonly<ShallowRef<Readonly<T>>>;
+}
+interface ReadonlySignal<T> {
+    (): Readonly<T>;
+}
+interface SignalOptions {
+    /**
+     * Whether to use `ref` to store the value
+     *
+     * @default false use `sharedRef` to store the value
+     */
+    useRef?: boolean;
+}
+declare function useSignal<T>(initialValue: T, options?: SignalOptions): Signal<T>;
+declare function useComputed<T>(getter: ComputedGetter<T>, debugOptions?: DebuggerOptions): ReadonlySignal<T>;
+declare function useComputed<T>(options: WritableComputedOptions<T>, debugOptions?: DebuggerOptions): Signal<T>;
+
+interface IconConfig {
+    /** Iconify icon name */
+    icon?: string;
+    /** Local icon name */
+    localIcon?: string;
+    /** Icon color */
+    color?: string;
+    /** Icon size */
+    fontSize?: number;
+}
+/**
+ * Svg icon render hook
+ *
+ * @param SvgIcon Svg icon component
+ */
+declare function useSvgIconRender(SvgIcon: Component): {
+    SvgIconVNode: (config: IconConfig) => (() => vue.VNode<vue.RendererNode, vue.RendererElement, {
+        [key: string]: any;
+    }>) | undefined;
+};
+
+type MaybePromise<T> = T | Promise<T>;
+type ApiFn = (args: any) => Promise<unknown>;
+interface TableColumnCheck {
+    key: string;
+    title: string;
+    checked: boolean;
+}
+type TableDataWithIndex<T> = T & {
+    index: number;
+};
+interface TransformedData<T> {
+    data: TableDataWithIndex<T>[];
+    pageNum: number;
+    pageSize: number;
+    total: number;
+}
+type Transformer<T, Response> = (response: Response) => TransformedData<T>;
+interface TableConfig<A extends ApiFn, T, C> {
+    /** Api function to get table data */
+    apiFn: A;
+    /** Api params */
+    apiParams?: Parameters<A>[0];
+    /** Transform api response to table data */
+    transformer: Transformer<T, Awaited<ReturnType<A>>>;
+    /** Columns factory */
+    columns: () => C[];
+    /**
+     * Get column checks
+     *
+     * @param columns
+     */
+    getColumnChecks: (columns: C[]) => TableColumnCheck[];
+    /**
+     * Get columns
+     *
+     * @param columns
+     */
+    getColumns: (columns: C[], checks: TableColumnCheck[]) => C[];
+    /**
+     * Callback when response fetched
+     *
+     * @param transformed transformed data
+     */
+    onFetched?: (transformed: TransformedData<T>) => MaybePromise<void>;
+    /**
+     * Whether to get data immediately
+     *
+     * @default true
+     */
+    immediate?: boolean;
+}
+declare function useHookTable<A extends ApiFn, T, C>(config: TableConfig<A, T, C>): {
+    loading: Ref<boolean, boolean>;
+    empty: Ref<boolean, boolean>;
+    data: Ref<TableDataWithIndex<T>[], TableDataWithIndex<T>[]>;
+    columns: vue.ComputedRef<C[]>;
+    columnChecks: Ref<TableColumnCheck[], TableColumnCheck[]>;
+    reloadColumns: () => void;
+    getData: () => Promise<void>;
+    searchParams: NonNullable<Parameters<A>[0]>;
+    updateSearchParams: (params: Partial<Parameters<A>[0]>) => void;
+    resetSearchParams: () => void;
+};
+
+export { type ApiFn, type CreateCallbackParams, type HookRequestInstance, type HookRequestInstanceResponseData, type HookRequestInstanceResponseFailData, type HookRequestInstanceResponseSuccessData, type MaybePromise, type ReadonlySignal, type RemoveEventFn, type Signal, type SignalOptions, type TableColumnCheck, type TableConfig, type TableDataWithIndex, type TransformedData, type Transformer, type UseEventParams, type WindowLocation, createBreakpointListen, lockHtmlScrollRightCompensationRef, useBoolean, useBreakpoint, useBrowserLocation, useComputed, useContext, useCountDown, useDeferredTrue, useEventListener, useHookTable, useInjectionCollection, useInjectionElementCollection, useInjectionInstanceCollection, useIsComposing, useLayoutContentStyle, useLayoutFooterStyle, useLayoutHeaderStyle, useLoading, useLocalPage, useLockHtmlScroll, useMemo, useMergedState, useScript, useScroll, useSignal, useSvgIconRender };