init

packages/hooks/src/index.ts

@@ -0,0 +1,9 @@
+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 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';
+
+/**
+ * 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 [provideDemoContext, useDemoContext] = 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 { provideDemoContext } from './context';
+ *
+ *   provideDemoContext();
+ *   // const { increment } = provideDemoContext(); // also can control the store in the parent component
+ *   </script>
+ *   ``` // B.vue
+ *   ```vue
+ *   <template>
+ *    <div>B</div>
+ *   </template>
+ *   <script setup lang="ts">
+ *   import { useDemoContext } from './context';
+ *
+ *   const { count, increment } = useDemoContext();
+ *   </script>
+ *   ```;
+ *
+ *   // C.vue is same as B.vue
+ *
+ * @param contextName Context name
+ * @param fn Context function
+ */
+export default function useContext<Arguments extends Array<any>, T>(
+  contextName: string,
+  composable: (...args: Arguments) => T
+) {
+  const key = Symbol(contextName);
+
+  /**
+   * Injects the context value.
+   *
+   * @param consumerName - The name of the component that is consuming the context. If provided, the component must be
+   *   used within the context provider.
+   * @param defaultValue - The default value to return if the context is not provided.
+   * @returns The context value.
+   */
+  const useInject = <N extends string | null | undefined = undefined>(
+    consumerName?: N,
+    defaultValue?: T
+  ): N extends null | undefined ? T | null : T => {
+    const value = inject(key, defaultValue);
+
+    if (consumerName && !value) {
+      throw new Error(`\`${consumerName}\` must be used within \`${contextName}\``);
+    }
+
+    // @ts-expect-error - we want to return null if the value is undefined or null
+    return value || null;
+  };
+
+  const useProvide = (...args: Arguments) => {
+    const value = composable(...args);
+
+    provide(key, value);
+
+    return value;
+  };
+
+  return [useProvide, useInject] as const;
+}

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,82 @@
+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-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 = {
+  key: string;
+  title: 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.key, col.checked]));
+
+    const defaultChecks = getColumnChecks(columns());
+
+    columnChecks.value = defaultChecks.map(col => ({
+      ...col,
+      checked: checkMap.get(col.key) ?? 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[];
+}