first commit

front/packages/hooks/src/index.ts

@@ -0,0 +1,11 @@
+import useBoolean from './use-boolean';
+import useLoading from './use-loading';
+import useCountDown from './use-count-down';
+import useContext from './use-context';
+import useSvgIconRender from './use-svg-icon-render';
+import useHookTable from './use-table';
+
+export { useBoolean, useLoading, useCountDown, useContext, useSvgIconRender, useHookTable };
+
+export * from './use-signal';
+export * from './use-table';

front/packages/hooks/src/use-boolean.ts

@@ -0,0 +1,31 @@
+import { ref } from 'vue';
+
+/**
+ * Boolean
+ *
+ * @param initValue Init value
+ */
+export default function useBoolean(initValue = false) {
+  const bool = ref(initValue);
+
+  function setBool(value: boolean) {
+    bool.value = value;
+  }
+  function setTrue() {
+    setBool(true);
+  }
+  function setFalse() {
+    setBool(false);
+  }
+  function toggle() {
+    setBool(!bool.value);
+  }
+
+  return {
+    bool,
+    setBool,
+    setTrue,
+    setFalse,
+    toggle
+  };
+}

front/packages/hooks/src/use-context.ts

@@ -0,0 +1,96 @@
+import { inject, provide } from 'vue';
+import type { InjectionKey } from 'vue';
+
+/**
+ * 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 '@sa/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
+ */
+export default function useContext<T extends (...args: any[]) => any>(contextName: string, fn: T) {
+  type Context = ReturnType<T>;
+
+  const { useProvide, useInject: useStore } = createContext<Context>(contextName);
+
+  function setupStore(...args: Parameters<T>) {
+    const context: Context = fn(...args);
+    return useProvide(context);
+  }
+
+  return {
+    /** Setup store in the parent component */
+    setupStore,
+    /** Use store in the child component */
+    useStore
+  };
+}
+
+/** Create context */
+function createContext<T>(contextName: string) {
+  const injectKey: InjectionKey<T> = Symbol(contextName);
+
+  function useProvide(context: T) {
+    provide(injectKey, context);
+
+    return context;
+  }
+
+  function useInject() {
+    return inject(injectKey) as T;
+  }
+
+  return {
+    useProvide,
+    useInject
+  };
+}

front/packages/hooks/src/use-count-down.ts

@@ -0,0 +1,49 @@
+import { computed, onScopeDispose, ref } from 'vue';
+import { useRafFn } from '@vueuse/core';
+
+/**
+ * count down
+ *
+ * @param seconds - count down seconds
+ */
+export default function useCountDown(seconds: number) {
+  const FPS_PER_SECOND = 60;
+
+  const fps = ref(0);
+
+  const count = computed(() => Math.ceil(fps.value / FPS_PER_SECOND));
+
+  const isCounting = computed(() => fps.value > 0);
+
+  const { pause, resume } = useRafFn(
+    () => {
+      if (fps.value > 0) {
+        fps.value -= 1;
+      } else {
+        pause();
+      }
+    },
+    { immediate: false }
+  );
+
+  function start(updateSeconds: number = seconds) {
+    fps.value = FPS_PER_SECOND * updateSeconds;
+    resume();
+  }
+
+  function stop() {
+    fps.value = 0;
+    pause();
+  }
+
+  onScopeDispose(() => {
+    pause();
+  });
+
+  return {
+    count,
+    isCounting,
+    start,
+    stop
+  };
+}

front/packages/hooks/src/use-loading.ts

@@ -0,0 +1,16 @@
+import useBoolean from './use-boolean';
+
+/**
+ * Loading
+ *
+ * @param initValue Init value
+ */
+export default function useLoading(initValue = false) {
+  const { bool: loading, setTrue: startLoading, setFalse: endLoading } = useBoolean(initValue);
+
+  return {
+    loading,
+    startLoading,
+    endLoading
+  };
+}

front/packages/hooks/src/use-request.ts

@@ -0,0 +1,79 @@
+import { ref } from 'vue';
+import type { Ref } from 'vue';
+import { createFlatRequest } from '@sa/axios';
+import type {
+  AxiosError,
+  CreateAxiosDefaults,
+  CustomAxiosRequestConfig,
+  MappedType,
+  RequestOption,
+  ResponseType
+} from '@sa/axios';
+import useLoading from './use-loading';
+
+export type HookRequestInstanceResponseSuccessData<T = any> = {
+  data: Ref<T>;
+  error: Ref<null>;
+};
+
+export type HookRequestInstanceResponseFailData<ResponseData = any> = {
+  data: Ref<null>;
+  error: Ref<AxiosError<ResponseData>>;
+};
+
+export type HookRequestInstanceResponseData<T = any, ResponseData = any> = {
+  loading: Ref<boolean>;
+} & (HookRequestInstanceResponseSuccessData<T> | HookRequestInstanceResponseFailData<ResponseData>);
+
+export interface HookRequestInstance<ResponseData = any> {
+  <T = any, R extends ResponseType = 'json'>(
+    config: CustomAxiosRequestConfig
+  ): HookRequestInstanceResponseData<MappedType<R, T>, ResponseData>;
+  cancelRequest: (requestId: string) => void;
+  cancelAllRequest: () => void;
+}
+
+/**
+ * create a hook request instance
+ *
+ * @param axiosConfig
+ * @param options
+ */
+export default function createHookRequest<ResponseData = any>(
+  axiosConfig?: CreateAxiosDefaults,
+  options?: Partial<RequestOption<ResponseData>>
+) {
+  const request = createFlatRequest<ResponseData>(axiosConfig, options);
+
+  const hookRequest: HookRequestInstance<ResponseData> = function hookRequest<T = any, R extends ResponseType = 'json'>(
+    config: CustomAxiosRequestConfig
+  ) {
+    const { loading, startLoading, endLoading } = useLoading();
+
+    const data = ref<MappedType<R, T> | null>(null) as Ref<MappedType<R, T>>;
+    const error = ref<AxiosError<ResponseData> | null>(null) as Ref<AxiosError<ResponseData> | null>;
+
+    startLoading();
+
+    request(config).then(res => {
+      if (res.data) {
+        data.value = res.data;
+      } else {
+        error.value = res.error;
+      }
+
+      endLoading();
+    });
+
+    return {
+      loading,
+      data,
+      error
+    };
+  } as HookRequestInstance<ResponseData>;
+
+  hookRequest.cancelRequest = request.cancelRequest;
+  hookRequest.cancelAllRequest = request.cancelAllRequest;
+
+  return hookRequest;
+}

front/packages/hooks/src/use-signal.ts

@@ -0,0 +1,144 @@
+import { computed, ref, shallowRef, triggerRef } from 'vue';
+import type {
+  ComputedGetter,
+  DebuggerOptions,
+  Ref,
+  ShallowRef,
+  WritableComputedOptions,
+  WritableComputedRef
+} from 'vue';
+
+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)
+ *   });
+ *   ```
+ */
+export 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>>>;
+}
+
+export interface ReadonlySignal<T> {
+  (): Readonly<T>;
+}
+
+export interface SignalOptions {
+  /**
+   * Whether to use `ref` to store the value
+   *
+   * @default false use `sharedRef` to store the value
+   */
+  useRef?: boolean;
+}
+
+export function useSignal<T>(initialValue: T, options?: SignalOptions): Signal<T> {
+  const { useRef } = options || {};
+
+  const state = useRef ? (ref(initialValue) as Ref<T>) : shallowRef(initialValue);
+
+  return createSignal(state);
+}
+
+export function useComputed<T>(getter: ComputedGetter<T>, debugOptions?: DebuggerOptions): ReadonlySignal<T>;
+export function useComputed<T>(options: WritableComputedOptions<T>, debugOptions?: DebuggerOptions): Signal<T>;
+export function useComputed<T>(
+  getterOrOptions: ComputedGetter<T> | WritableComputedOptions<T>,
+  debugOptions?: DebuggerOptions
+) {
+  const isGetter = typeof getterOrOptions === 'function';
+
+  const computedValue = computed(getterOrOptions as any, debugOptions);
+
+  if (isGetter) {
+    return () => computedValue.value as ReadonlySignal<T>;
+  }
+
+  return createSignal(computedValue);
+}
+
+function createSignal<T>(state: ShallowRef<T> | WritableComputedRef<T>): Signal<T> {
+  const signal = () => state.value;
+
+  signal.set = (value: T) => {
+    state.value = value;
+  };
+
+  signal.update = (updater: Updater<T>) => {
+    state.value = updater(state.value);
+  };
+
+  signal.mutate = (mutator: Mutator<T>) => {
+    mutator(state.value);
+    triggerRef(state);
+  };
+
+  signal.getRef = () => state as Readonly<ShallowRef<Readonly<T>>>;
+
+  return signal;
+}

front/packages/hooks/src/use-svg-icon-render.ts

@@ -0,0 +1,50 @@
+import { h } from 'vue';
+import type { Component } from 'vue';
+
+/**
+ * Svg icon render hook
+ *
+ * @param SvgIcon Svg icon component
+ */
+export default function useSvgIconRender(SvgIcon: Component) {
+  interface IconConfig {
+    /** Iconify icon name */
+    icon?: string;
+    /** Local icon name */
+    localIcon?: string;
+    /** Icon color */
+    color?: string;
+    /** Icon size */
+    fontSize?: number;
+  }
+
+  type IconStyle = Partial<Pick<CSSStyleDeclaration, 'color' | 'fontSize'>>;
+
+  /**
+   * Svg icon VNode
+   *
+   * @param config
+   */
+  const SvgIconVNode = (config: IconConfig) => {
+    const { color, fontSize, icon, localIcon } = config;
+
+    const style: IconStyle = {};
+
+    if (color) {
+      style.color = color;
+    }
+    if (fontSize) {
+      style.fontSize = `${fontSize}px`;
+    }
+
+    if (!icon && !localIcon) {
+      return undefined;
+    }
+
+    return () => h(SvgIcon, { icon, localIcon, style });
+  };
+
+  return {
+    SvgIconVNode
+  };
+}

front/packages/hooks/src/use-table.ts

@@ -0,0 +1,153 @@
+import { computed, reactive, ref } from 'vue';
+import type { Ref } from 'vue';
+import { jsonClone } from '@sa/utils';
+import useBoolean from './use-boolean';
+import useLoading from './use-loading';
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export type ApiFn = (args: any) => Promise<unknown>;
+
+export type TableColumnCheck = {
+  key: string;
+  title: string;
+  checked: boolean;
+};
+
+export type TableDataWithIndex<T> = T & { index?: number };
+
+export type TransformedData<T> = {
+  data: TableDataWithIndex<T>[];
+  pageNum: number;
+  pageSize: number;
+  total: number;
+};
+
+export type Transformer<T, Response> = (response: Response) => TransformedData<T>;
+
+export type 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;
+};
+
+export default function useHookTable<A extends ApiFn, T, C>(config: TableConfig<A, T, C>) {
+  const { loading, startLoading, endLoading } = useLoading();
+  const { bool: empty, setBool: setEmpty } = useBoolean();
+
+  const { apiFn, apiParams, transformer, immediate = true, getColumnChecks, getColumns } = config;
+
+  const searchParams: NonNullable<Parameters<A>[0]> = reactive(jsonClone({ ...apiParams }));
+
+  const allColumns = ref(config.columns()) as Ref<C[]>;
+
+  const data: Ref<TableDataWithIndex<T>[]> = ref([]);
+
+  const columnChecks: Ref<TableColumnCheck[]> = ref(getColumnChecks(config.columns()));
+
+  const columns = computed(() => getColumns(allColumns.value, columnChecks.value));
+
+  function reloadColumns() {
+    allColumns.value = config.columns();
+
+    const checkMap = new Map(columnChecks.value.map(col => [col.key, col.checked]));
+
+    const defaultChecks = getColumnChecks(allColumns.value);
+
+    columnChecks.value = defaultChecks.map(col => ({
+      ...col,
+      checked: checkMap.get(col.key) ?? col.checked
+    }));
+  }
+
+  async function getData() {
+    startLoading();
+
+    const formattedParams = formatSearchParams(searchParams);
+
+    const response = await apiFn(formattedParams);
+
+    const transformed = transformer(response as Awaited<ReturnType<A>>);
+
+    data.value = transformed.data;
+
+    setEmpty(transformed.data.length === 0);
+
+    await config.onFetched?.(transformed);
+
+    endLoading();
+  }
+
+  function formatSearchParams(params: Record<string, unknown>) {
+    const formattedParams: Record<string, unknown> = {};
+
+    // remove null and undefined values from search params: 去除搜索参数中的 null 和 undefined 值
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== null && value !== undefined) {
+        formattedParams[key] = value;
+      }
+    });
+
+    return formattedParams;
+  }
+
+  /**
+   * update search params
+   *
+   * @param params
+   */
+  function updateSearchParams(params: Partial<Parameters<A>[0]>) {
+    Object.assign(searchParams, params);
+  }
+
+  /** reset search params */
+  function resetSearchParams() {
+    Object.assign(searchParams, jsonClone(apiParams));
+  }
+
+  if (immediate) {
+    getData();
+  }
+
+  return {
+    loading,
+    empty,
+    data,
+    columns,
+    columnChecks,
+    reloadColumns,
+    getData,
+    searchParams,
+    updateSearchParams,
+    resetSearchParams
+  };
+}