kmod-cli 1.0.10

package/component-templates/core/idb.ts

@@ -0,0 +1,166 @@
+import {
+  DBSchema,
+  deleteDB,
+  IDBPDatabase,
+  openDB,
+} from 'idb';
+
+// =======================
+// DB Schema định nghĩa
+// =======================
+export type AppDBSchema = DBSchema & {
+  items: {
+    key: string;
+    value: any;
+  };
+}
+
+// =======================
+// Core Init
+// =======================
+export const initDB = async (
+  name: string = "AppDB",
+  version: number = 1
+): Promise<IDBPDatabase<AppDBSchema>> => {
+  return await openDB<AppDBSchema>(name, version, {
+    upgrade(db) {
+      if (!db.objectStoreNames.contains("items")) {
+        db.createObjectStore("items", { keyPath: "id" });
+      }
+    },
+  });
+};
+
+// =======================
+// CRUD helpers
+// =======================
+export const db = {
+  add: async (data: { id: string; [key: string]: any }, dbName?: string) => {
+    try {
+      if (!data?.id) throw new Error("id is required");
+      const db = await initDB(dbName);
+      await db.put("items", data);
+      return { success: true, message: "Item added" };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  get: async (id: string, dbName?: string) => {
+    try {
+      if (!id) throw new Error("id is required");
+      const db = await initDB(dbName);
+      const item = await db.get("items", id);
+      return item
+        ? { success: true, data: item }
+        : { success: false, message: "Item not found" };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  getAll: async (dbName?: string) => {
+    try {
+      const db = await initDB(dbName);
+      const items = await db.getAll("items");
+      return { success: true, data: items };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  update: async (id: string, updatedData: any, dbName?: string) => {
+    try {
+      const db = await initDB(dbName);
+      const item = await db.get("items", id);
+      if (!item) return { success: false, message: "Item not found" };
+      const newItem = { ...item, ...updatedData };
+      await db.put("items", newItem);
+      return { success: true, message: "Item updated" };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  delete: async (id: string, dbName?: string) => {
+    try {
+      const db = await initDB(dbName);
+      await db.delete("items", id);
+      return { success: true, message: "Item deleted" };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  clear: async (dbName?: string) => {
+    try {
+      const db = await initDB(dbName);
+      await db.clear("items");
+      return { success: true, message: "All items cleared" };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+};
+
+// =======================
+// DB Management helpers
+// =======================
+export const dbManager = {
+  createDB: async (name: string, version: number = 1) => {
+    try {
+      await openDB(name, version, {
+        upgrade(db) {
+          if (!db.objectStoreNames.contains("items")) {
+            db.createObjectStore("items", { keyPath: "id" });
+          }
+        },
+      });
+      return { success: true, message: `DB ${name} created` };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  deleteDB: async (name: string) => {
+    try {
+      await deleteDB(name);
+      return { success: true, message: `DB ${name} deleted` };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  listDBs: async () => {
+    try {
+      if ("databases" in indexedDB) {
+        const dbs = await (indexedDB as any).databases();
+        return { success: true, data: dbs };
+      }
+      return {
+        success: false,
+        message: "listDBs not supported in this browser",
+      };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+
+  clearAllDBs: async () => {
+    try {
+      if ("databases" in indexedDB) {
+        const dbs = await (indexedDB as any).databases();
+        for (const db of dbs) {
+          if (db.name) await deleteDB(db.name);
+        }
+        return { success: true, message: "All DBs cleared" };
+      }
+      return {
+        success: false,
+        message: "clearAllDBs not supported in this browser",
+      };
+    } catch (err) {
+      return { success: false, message: String(err) };
+    }
+  },
+};

package/component-templates/core/storage.ts

@@ -0,0 +1,213 @@
+export type CookieSet = {
+  name: string;
+  value: string | object;
+  days?: number | "infinity";
+  path?: string;
+  sameSite?: "Lax" | "Strict" | "None";
+};
+
+export type SessionSet<T> = {
+  key: string;
+  value: T;
+  expiresMs?: number | boolean;
+};
+
+export type SessionGet<T> = {
+  key: string;
+  expiredCheck?: boolean;
+};
+export type SessionGetHas = {
+  key: string;
+  expiredCheck?: boolean;
+};
+
+export class Storage {
+  private static prefix = "app_";
+
+  // ------------------- Set Prefix -------------------
+  static setPrefix(prefix: string) {
+    this.prefix = prefix;
+  }
+
+  // ------------------- LocalStorage -------------------
+  static setItem<T>({
+    key,
+    value,
+    expiresMs = false,
+  }: {
+    key: string;
+    value: T;
+    expiresMs?: number | boolean;
+  }) {
+    const item =
+      typeof expiresMs === "number"
+        ? {
+            value,
+            expires: expiresMs ? Date.now() + expiresMs : null,
+          }
+        : value;
+    localStorage.setItem(this.prefix + key, JSON.stringify(item));
+  }
+
+  static getItem<T>({
+    key,
+    expiredCheck = false,
+  }: {
+    key: string;
+    expiredCheck?: boolean;
+  }): T | null {
+    const itemStr = localStorage.getItem(this.prefix + key);
+    if (!itemStr) return null;
+    try {
+      const item = JSON.parse(itemStr);
+      if (expiredCheck === false) return item.value;
+      if (item.expires && Date.now() > item.expires) {
+        localStorage.removeItem(this.prefix + key);
+        return null;
+      }
+      return item.value;
+    } catch {
+      localStorage.removeItem(this.prefix + key);
+      return null;
+    }
+  }
+
+  static removeItem(key: string) {
+    localStorage.removeItem(this.prefix + key);
+  }
+
+  static clearStorage() {
+    Object.keys(localStorage)
+      .filter((key) => key.startsWith(this.prefix))
+      .forEach((key) => localStorage.removeItem(key));
+  }
+
+  static hasItem({
+    key,
+    expiredCheck = false,
+  }: {
+    key: string;
+    expiredCheck?: boolean;
+  }): boolean {
+    return this.getItem({ key, expiredCheck }) !== null;
+  }
+
+  // ------------------- Cookies -------------------
+  /**
+   * Sets a cookie.
+   * @param name - The name of the cookie.
+   * @param value - The value of the cookie.
+   * @param days - The number of days until the cookie expires.
+   * @param path - The path of the cookie.
+   * @param sameSite - The SameSite attribute of the cookie. Defaults to "Lax".
+   */
+  static setCookie({
+    name,
+    value,
+    days,
+    path = "/",
+    sameSite = "Lax",
+  }: CookieSet) {
+    let val = typeof value === "object" ? JSON.stringify(value) : value;
+    let cookieStr = `${encodeURIComponent(name)}=${encodeURIComponent(
+      val
+    )}; path=${path}; SameSite=${sameSite}`;
+    if (days === "infinity") cookieStr += "; max-age=3153600000";
+    if (days && days !== "infinity") {
+      const expires = new Date();
+      expires.setTime(expires.getTime() + days * 24 * 60 * 60 * 1000);
+      cookieStr += `; expires=${expires.toUTCString()}`;
+    }
+    if (location.protocol === "https:") cookieStr += "; Secure";
+    document.cookie = cookieStr;
+  }
+
+  /**
+   * Retrieves a cookie value by name.
+   * @param name The name of the cookie.
+   * @returns The value of the cookie, or undefined if it does not exist.
+   * The value is parsed as JSON if it is a valid JSON string; otherwise it is
+   * returned as a string.
+   */
+  static getCookie<T = string>(name: string): T | undefined {
+    const nameEQ = encodeURIComponent(name) + "=";
+    const ca = document.cookie.split(";").map((c) => c.trim());
+    for (let c of ca) {
+      if (c.indexOf(nameEQ) === 0) {
+        const val = decodeURIComponent(c.substring(nameEQ.length));
+        try {
+          return JSON.parse(val) as T;
+        } catch {
+          return val as unknown as T;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Removes a cookie by name.
+   * @param name The name of the cookie to remove.
+   * @param path The path of the cookie to remove; defaults to "/".
+   */
+  static removeCookie(name: string, path = "/") {
+    document.cookie = `${encodeURIComponent(
+      name
+    )}=; path=${path}; expires=Thu, 01 Jan 1970 00:00:00 GMT`;
+  }
+
+  /**
+   * Checks if a cookie with the given name exists.
+   * @param name The name of the cookie to check.
+   * @returns true if the cookie exists, false otherwise.
+   */
+  static cookieExists(name: string): boolean {
+    return this.getCookie(name) !== undefined;
+  }
+
+  //------------------- Session Storage -------------------
+  static setSessionItem<T>({ key, value, expiresMs = false }: SessionSet<T>) {
+    const item =
+      typeof expiresMs === "number"
+        ? {
+            value,
+            expires: expiresMs ? Date.now() + expiresMs : null,
+          }
+        : value;
+    sessionStorage.setItem(this.prefix + key, JSON.stringify(item));
+  }
+
+  static getSessionItem<T>({
+    key,
+    expiredCheck = false,
+  }: SessionGet<T>): T | null {
+    const itemStr = sessionStorage.getItem(this.prefix + key);
+    if (!itemStr) return null;
+    try {
+      const item = JSON.parse(itemStr);
+      if (expiredCheck === false) return item.value;
+      if (item.expires && Date.now() > item.expires) {
+        sessionStorage.removeItem(this.prefix + key);
+        return null;
+      }
+      return item.value;
+    } catch {
+      sessionStorage.removeItem(this.prefix + key);
+      return null;
+    }
+  }
+
+  static removeSessionItem(key: string) {
+    sessionStorage.removeItem(this.prefix + key);
+  }
+
+  static clearSession() {
+    Object.keys(sessionStorage)
+      .filter((key) => key.startsWith(this.prefix))
+      .forEach((key) => sessionStorage.removeItem(key));
+  }
+
+  static hasSessionItem({ key, expiredCheck = false }: SessionGetHas): boolean {
+    return this.getSessionItem({ key, expiredCheck }) !== null;
+  }
+}

package/component-templates/hooks/count-down.ts

@@ -0,0 +1,38 @@
+// countdownStore.ts
+import { create } from 'zustand';
+
+export type CountdownState = {
+  timeLeft: number;
+  isRunning: boolean;
+  freezing: boolean;
+  setTime: (time: number) => void;
+  decrement: () => void;
+  reset: () => void;
+  start: () => void;
+  stop: () => void;
+  freeze: () => void;
+  defrost: () => void;
+}
+
+export const useCountdownStore = create<CountdownState>((set) => ({
+  timeLeft: 0,
+  isRunning: false,
+  freezing: false,
+
+  setTime: (time) => set({ timeLeft: time }),
+
+  decrement: () =>
+    set((state) =>
+      state.timeLeft > 0 ? { timeLeft: state.timeLeft - 1 } : state
+    ),
+
+  reset: () => set({ timeLeft: 0, isRunning: false }),
+
+  start: () => set({ isRunning: true }),
+
+  stop: () => set({ isRunning: false }),
+
+  freeze: () => set({ freezing: true }),
+
+  defrost: () => set({ freezing: false }),
+}));

package/component-templates/hooks/fade-on-scroll.ts

@@ -0,0 +1,52 @@
+import {
+  useEffect,
+  useState,
+} from 'react';
+
+export type FadeOnScrollProps = {
+  ref: React.RefObject<HTMLElement>;
+  threshold?: number; // Intersection Observer threshold
+  repeat?: boolean; // If true, will toggle visibility on entering/exiting viewport
+};
+
+/**
+ * useFadeUpOnScroll - Hook to track if element is visible in viewport
+ * @param {React.RefObject<HTMLElement>} ref - Ref to the element to observe
+ * @param {number} [threshold=0.5] - IntersectionObserver threshold
+ * @param {boolean} [repeat=false] - If true, will toggle visibility on entering/exiting viewport
+ * @return {boolean} - true if element is visible in viewport
+ */
+export const useFadeUpOnScroll = ({ ref, threshold = 0.5, repeat = false }: FadeOnScrollProps): boolean => {
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        entries.forEach((entry) => {
+          if (repeat) {
+            // If repeat: toggle in the state in/out Viewport
+            setIsVisible(entry.isIntersecting);
+          } else {
+            // If not repeat: just set true once
+            if (entry.isIntersecting) {
+              setIsVisible((prev) => prev || true);
+            }
+          }
+        });
+      },
+      { threshold }
+    );
+
+    const node = ref.current;
+    if (node) observer.observe(node);
+
+    return () => {
+      if (node) observer.unobserve(node);
+      observer.disconnect();
+    };
+  }, [threshold, ref, repeat]);
+
+  return isVisible;
+};
+
+export default useFadeUpOnScroll;

package/component-templates/hooks/safe-action.ts

@@ -0,0 +1,59 @@
+import {
+  useCallback,
+  useRef,
+} from 'react';
+
+import { debounce as lodashDebounce } from 'lodash';
+
+export type Options = {
+  loading: boolean;
+  enableDebounce?: boolean;
+  debounceMs?: number;
+  preventDoubleCall?: boolean;
+};
+
+/**
+ * Wraps an action function to prevent double calls, and debounce action calls
+ * if needed.
+ *
+ * @param {() => Promise<void> | void} action
+ * @param {{
+ *   loading: boolean;
+ *   enableDebounce?: boolean;
+ *   debounceMs?: number;
+ *   preventDoubleCall?: boolean;
+ * }} options
+ *
+ * @returns {(args: any[]) => Promise<void>}
+ */
+
+export const useSafeAction = (action: () => Promise<void> | void,
+  {
+    loading,
+    enableDebounce = false,
+    debounceMs = 300,
+    preventDoubleCall = true,
+  }: Options
+): (args: any[]) => Promise<void> => {
+  const isHandling = useRef(false);
+
+  const wrapped = useCallback(async () => {
+    if (loading || (preventDoubleCall && isHandling.current)) return;
+
+    try {
+      isHandling.current = true;
+      await action();
+    } finally {
+      isHandling.current = false;
+    }
+  }, [action, loading, preventDoubleCall]);
+
+  if (enableDebounce) {
+    return useCallback(
+      lodashDebounce(wrapped, debounceMs, { leading: true, trailing: false }),
+      [wrapped, debounceMs]
+    );
+  }
+
+  return wrapped;
+};

package/component-templates/hooks/spam-guard.ts

@@ -0,0 +1,31 @@
+import { useRef } from 'react';
+
+export type SpamGuardProps = {
+  limit?: number;
+  timeFrame?: number;
+  onSpam?: () => void;
+}
+
+export const useSpamGuard = ({
+  limit = 1,
+  timeFrame = 600,
+  onSpam,
+}: SpamGuardProps = {}): () => boolean => {
+  const actionsRef = useRef<number[]>([]);
+
+  const checkSpam = () => {
+    const now = Date.now();
+    const updatedActions = actionsRef.current.filter((t) => now - t < timeFrame);
+
+    if (updatedActions.length >= limit) {
+      onSpam?.();
+      return false;
+    }
+
+    updatedActions.push(now);
+    actionsRef.current = updatedActions;
+    return true;
+  };
+
+  return checkSpam;
+}

package/component-templates/lib/utils.ts

@@ -0,0 +1,6 @@
+import clsx, { ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+    return twMerge(clsx(inputs))
+}