初始化

packages/hooks/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@sa/hooks",
+  "version": "1.3.15",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "typesVersions": {
+    "*": {
+      "*": ["./src/*"]
+    }
+  },
+  "dependencies": {
+    "@sa/axios": "workspace:*",
+    "@sa/utils": "workspace:*"
+  }
+}

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 useTable from './use-table';
+
+export { useBoolean, useLoading, useCountDown, useContext, useSvgIconRender, useTable };
+
+export * from './use-signal';
+export type * from './use-table';

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
+  };
+}

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
+  };
+}

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

@@ -0,0 +1,68 @@
+import { computed, onScopeDispose, ref } from 'vue';
+import { useRafFn } from '@vueuse/core';
+
+/**
+ * A hook for implementing a countdown timer. It uses `requestAnimationFrame` for smooth and accurate timing,
+ * independent of the screen refresh rate.
+ *
+ * @param initialSeconds - The total number of seconds for the countdown.
+ */
+export default function useCountDown(initialSeconds: number) {
+  const remainingSeconds = ref(0);
+
+  const count = computed(() => Math.ceil(remainingSeconds.value));
+
+  const isCounting = computed(() => remainingSeconds.value > 0);
+
+  const { pause, resume } = useRafFn(
+    ({ delta }) => {
+      // delta: milliseconds elapsed since the last frame.
+
+      // If countdown already reached zero or below, ensure it's 0 and stop.
+      if (remainingSeconds.value <= 0) {
+        remainingSeconds.value = 0;
+        pause();
+        return;
+      }
+
+      // Calculate seconds passed since the last frame.
+      const secondsPassed = delta / 1000;
+      remainingSeconds.value -= secondsPassed;
+
+      // If countdown has finished after decrementing.
+      if (remainingSeconds.value <= 0) {
+        remainingSeconds.value = 0;
+        pause();
+      }
+    },
+    { immediate: false } // The timer does not start automatically.
+  );
+
+  /**
+   * Starts the countdown.
+   *
+   * @param [updatedSeconds=initialSeconds] - Optionally, start with a new duration. Default is `initialSeconds`
+   */
+  function start(updatedSeconds: number = initialSeconds) {
+    remainingSeconds.value = updatedSeconds;
+    resume();
+  }
+
+  /** Stops the countdown and resets the remaining time to 0. */
+  function stop() {
+    remainingSeconds.value = 0;
+    pause();
+  }
+
+  // Ensure the rAF loop is cleaned up when the component is unmounted.
+  onScopeDispose(() => {
+    pause();
+  });
+
+  return {
+    count,
+    isCounting,
+    start,
+    stop
+  };
+}

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
+  };
+}

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

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;
+}

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
+  };
+}

packages/hooks/src/use-table.ts

@@ -0,0 +1,132 @@
+import { computed, ref } from 'vue';
+import type { Ref, VNodeChild } from 'vue';
+import useBoolean from './use-boolean';
+import useLoading from './use-loading';
+
+export interface PaginationData<T> {
+  data: T[];
+  pageNum: number;
+  pageSize: number;
+  total: number;
+}
+
+type GetApiData<ApiData, Pagination extends boolean> = Pagination extends true ? PaginationData<ApiData> : ApiData[];
+
+type Transform<ResponseData, ApiData, Pagination extends boolean> = (
+  response: ResponseData
+) => GetApiData<ApiData, Pagination>;
+
+export type TableColumnCheckTitle = string | ((...args: any) => VNodeChild);
+
+export type TableColumnCheck = {
+  prop: string;
+  label: TableColumnCheckTitle;
+  checked: boolean;
+  visible: boolean;
+};
+
+export interface UseTableOptions<ResponseData, ApiData, Column, Pagination extends boolean> {
+  /**
+   * api function to get table data
+   */
+  api: () => Promise<ResponseData>;
+  /**
+   * whether to enable pagination
+   */
+  pagination?: Pagination;
+  /**
+   * transform api response to table data
+   */
+  transform: Transform<ResponseData, ApiData, Pagination>;
+  /**
+   * columns factory
+   */
+  columns: () => Column[];
+  /**
+   * get column checks
+   */
+  getColumnChecks: (columns: Column[]) => TableColumnCheck[];
+  /**
+   * get columns
+   */
+  getColumns: (columns: Column[], checks: TableColumnCheck[]) => Column[];
+  /**
+   * callback when response fetched
+   */
+  onFetched?: (data: GetApiData<ApiData, Pagination>) => void | Promise<void>;
+  /**
+   * whether to get data immediately
+   *
+   * @default true
+   */
+  immediate?: boolean;
+}
+
+export default function useTable<ResponseData, ApiData, Column, Pagination extends boolean>(
+  options: UseTableOptions<ResponseData, ApiData, Column, Pagination>
+) {
+  const { loading, startLoading, endLoading } = useLoading();
+  const { bool: empty, setBool: setEmpty } = useBoolean();
+
+  const { api, pagination, transform, columns, getColumnChecks, getColumns, onFetched, immediate = true } = options;
+
+  const data = ref([]) as Ref<ApiData[]>;
+
+  const columnChecks = ref(getColumnChecks(columns())) as Ref<TableColumnCheck[]>;
+
+  const $columns = computed(() => getColumns(columns(), columnChecks.value));
+
+  function reloadColumns() {
+    const checkMap = new Map(columnChecks.value.map(col => [col.prop, col.checked]));
+
+    const defaultChecks = getColumnChecks(columns());
+
+    columnChecks.value = defaultChecks.map(col => ({
+      ...col,
+      checked: checkMap.get(col.prop) ?? col.checked
+    }));
+  }
+
+  async function getData() {
+    try {
+      startLoading();
+
+      const response = await api();
+
+      const transformed = transform(response);
+
+      data.value = getTableData(transformed, pagination);
+
+      setEmpty(data.value.length === 0);
+
+      await onFetched?.(transformed);
+    } finally {
+      endLoading();
+    }
+  }
+
+  if (immediate) {
+    getData();
+  }
+
+  return {
+    loading,
+    empty,
+    data,
+    columns: $columns,
+    columnChecks,
+    reloadColumns,
+    getData
+  };
+}
+
+function getTableData<ApiData, Pagination extends boolean>(
+  data: GetApiData<ApiData, Pagination>,
+  pagination?: Pagination
+) {
+  if (pagination) {
+    return (data as PaginationData<ApiData>).data;
+  }
+
+  return data as ApiData[];
+}

packages/hooks/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "jsx": "preserve",
+    "lib": ["DOM", "ESNext"],
+    "baseUrl": ".",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+    "types": ["node"],
+    "strict": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "allowSyntheticDefaultImports": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}