@vlrc-fe/hooks 1.0.0

package/README.md

@@ -0,0 +1,125 @@
+# @vlrc-fe/hooks
+
+---
+ai_package_metadata:
+  package_name: "@vlrc-fe/hooks"
+  version: "workspace:*"
+  conventions:
+    import_hygiene:
+      main_app: "Do NOT manually import. Let Vite auto-import handle it (src/types/auto-imports.d.ts)."
+      local_packages: "Always use explicit relative or workspace imports. Packages compile without auto-imports."
+    hook_rules:
+      state_boundaries: "Prefer TanStack Query for server state. Use Zustand stores inside packages/ or apps/ only for pure UI/client state."
+      explicit_types: "Always declare explicit return types on hooks inside packages/ to avoid TS7056 / TS5088 serialization compilation limits."
+---
+
+Reusable, optimized, and tree-shaken React Hooks for the VLRC project monorepo.
+
+> [!IMPORTANT]
+> **AUTO-IMPORT CONVENTION**: In the main web application (`src/`), **do not write explicit import statements** for any hooks in this package. They are dynamically parsed and registered by Vite into `src/types/auto-imports.d.ts`.
+> **EXPLICIT PACKAGE IMPORTS**: Inside independent packages (like `packages/components` or `packages/hooks`), **always** write explicit imports because packages are compiled standalone using `tsc`.
+
+---
+
+## 📚 Agent & Codex Skill Reference
+
+This package is fully integrated with the **[platform-core-components Agent Skill](file:///Users/lvtruong/personal/vlrc/.agent/skills/platform-core-components/SKILL.md)**. For modal lifecycle patterns, data-binding examples, and `ConfirmModal` composition, see:
+- **[Dialogs, ConfirmModal & useModalState Bindings](file:///Users/lvtruong/personal/vlrc/.agent/skills/platform-core-components/references/modals.md)**
+
+---
+
+## 📦 Core Hook: `useModalState`
+
+A multi-key modal state manager that handles **open/close lifecycles**, **lazy mounting** (`load` flag), and **delayed DOM unmounting** (via `destroyDelay`) for smooth exit animations. It manages multiple independent modals from a single hook call using a typed key list.
+
+### Hook Signature
+
+```typescript
+function useModalState<const T extends ReadonlyArray<string>>(
+  keyList: T,
+  options?: { destroyDelay?: number }
+): {
+  modal: Record<T[number], { load: boolean; open: boolean }>;
+  openModal: (name: T[number]) => void;
+  closeModal: (name: T[number]) => void;
+}
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `keyList` | `ReadonlyArray<string>` | - | **(Required)** A tuple of string keys identifying each modal, e.g. `['edit', 'delete', 'detail']`. |
+| `options.destroyDelay` | `number` | `300` | Milliseconds to wait after closing before setting `load: false` (unmounting the modal DOM). Set to `0` for instant unmount. |
+
+### Return Value
+
+| Field | Type | Description |
+| :--- | :--- | :--- |
+| `modal` | `Record<Key, { load: boolean; open: boolean }>` | State map. `load` controls whether the modal component mounts in the DOM. `open` controls its visible/animated state. |
+| `openModal` | `(name: Key) => void` | Sets both `load: true` and `open: true` for the given key. Cancels any pending destroy timer. |
+| `closeModal` | `(name: Key) => void` | Sets `open: false` immediately, then sets `load: false` after `destroyDelay` ms. This two-phase approach allows CSS exit animations to complete before the component unmounts. |
+
+### Lifecycle Flow
+
+```
+openModal('edit')  →  { load: true, open: true }   // mount + animate in
+closeModal('edit') →  { load: true, open: false }   // animate out (300ms)
+                   →  { load: false, open: false }   // unmount from DOM
+```
+
+### Example: Managing Multiple Modals
+
+```tsx
+const CourseManager = () => {
+  const { modal, openModal, closeModal } = useModalState(['edit', 'delete'] as const);
+
+  return (
+    <>
+      <Button onClick={() => openModal('edit')}>Sửa khóa học</Button>
+      <Button variant="destructive" onClick={() => openModal('delete')}>Xóa khóa học</Button>
+
+      {/* Only mounts when modal.edit.load is true */}
+      {modal.edit.load && (
+        <Modal open={modal.edit.open} onOpenChange={() => closeModal('edit')}>
+          <div className="p-6">
+            <h3 className="text-lg font-bold">Chỉnh sửa khóa học</h3>
+            {/* Edit form content */}
+          </div>
+        </Modal>
+      )}
+
+      {/* Destructive confirmation with lazy mount */}
+      {modal.delete.load && (
+        <ConfirmModal
+          open={modal.delete.open}
+          title="Xác nhận xóa?"
+          description="Khóa học sẽ bị xóa vĩnh viễn."
+          variant="destructive"
+          onCancel={() => closeModal('delete')}
+          onConfirm={async () => {
+            await deleteCourseMutation.mutateAsync(courseId);
+            closeModal('delete');
+          }}
+        />
+      )}
+    </>
+  );
+};
+```
+
+### Why Two-Phase Unmounting?
+
+The `load` / `open` separation exists because:
+- **`open: false`** triggers exit animations (e.g. Radix Dialog fade-out, scale-down transitions).
+- **`load: false`** removes the component from the React tree entirely after the animation completes.
+- Without this, closing a dialog would instantly unmount its DOM nodes, cutting off any exit animation mid-frame.
+
+---
+
+## 🛠 Package Scripts
+
+Managed by Lerna and PNPM Workspaces:
+- Build package: `pnpm build`
+- Version package: `pnpm version:packages`
+- Publish package: `pnpm publish:packages`

package/dist/index.cjs

@@ -0,0 +1 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./index2.cjs");exports.useModalState=e.useModalState;

package/dist/index.js

@@ -0,0 +1,2 @@
+import { useModalState as e } from "./index2.js";
+export { e as useModalState };

package/dist/index2.cjs

@@ -0,0 +1 @@
+let e=require("react");function t(t,n){let r=n?.destroyDelay??300,i=(0,e.useMemo)(()=>JSON.stringify(t),[t]),a=e=>e.reduce((e,t)=>(e[t]={load:!1,open:!1},e),{}),[o,s]=(0,e.useState)(()=>a(t)),c=(0,e.useRef)(new Map);return(0,e.useEffect)(()=>{s(e=>{let n=!1,r={...e};for(let e of t)e in r||(r[e]={load:!1,open:!1},n=!0);return n?r:e})},[t,i]),(0,e.useEffect)(()=>()=>{for(let e of c.current.values())clearTimeout(e);c.current.clear()},[]),{modal:o,openModal:e=>{s(t=>{if(!(e in t))return t;let n=c.current.get(String(e));return n&&(clearTimeout(n),c.current.delete(String(e))),{...t,[e]:{...t[e],open:!0,load:!0}}})},closeModal:e=>{if(s(t=>e in t?{...t,[e]:{...t[e],open:!1}}:t),r<=0){s(t=>e in t?{...t,[e]:{...t[e],load:!1}}:t);return}let t=String(e),n=c.current.get(t);n&&(clearTimeout(n),c.current.delete(t));let i=setTimeout(()=>{s(t=>e in t?{...t,[e]:{...t[e],load:!1}}:t),c.current.delete(t)},r);c.current.set(t,i)}}}exports.useModalState=t;

package/dist/index2.js

@@ -0,0 +1,69 @@
+import { useEffect as e, useMemo as t, useRef as n, useState as r } from "react";
+//#region src/useModalState.ts
+function i(i, a) {
+	let o = a?.destroyDelay ?? 300, s = t(() => JSON.stringify(i), [i]), c = (e) => e.reduce((e, t) => (e[t] = {
+		load: !1,
+		open: !1
+	}, e), {}), [l, u] = r(() => c(i)), d = n(/* @__PURE__ */ new Map());
+	return e(() => {
+		u((e) => {
+			let t = !1, n = { ...e };
+			for (let e of i) e in n || (n[e] = {
+				load: !1,
+				open: !1
+			}, t = !0);
+			return t ? n : e;
+		});
+	}, [i, s]), e(() => () => {
+		for (let e of d.current.values()) clearTimeout(e);
+		d.current.clear();
+	}, []), {
+		modal: l,
+		openModal: (e) => {
+			u((t) => {
+				if (!(e in t)) return t;
+				let n = d.current.get(String(e));
+				return n && (clearTimeout(n), d.current.delete(String(e))), {
+					...t,
+					[e]: {
+						...t[e],
+						open: !0,
+						load: !0
+					}
+				};
+			});
+		},
+		closeModal: (e) => {
+			if (u((t) => e in t ? {
+				...t,
+				[e]: {
+					...t[e],
+					open: !1
+				}
+			} : t), o <= 0) {
+				u((t) => e in t ? {
+					...t,
+					[e]: {
+						...t[e],
+						load: !1
+					}
+				} : t);
+				return;
+			}
+			let t = String(e), n = d.current.get(t);
+			n && (clearTimeout(n), d.current.delete(t));
+			let r = setTimeout(() => {
+				u((t) => e in t ? {
+					...t,
+					[e]: {
+						...t[e],
+						load: !1
+					}
+				} : t), d.current.delete(t);
+			}, o);
+			d.current.set(t, r);
+		}
+	};
+}
+//#endregion
+export { i as useModalState };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@vlrc-fe/hooks",
+  "version": "1.0.0",
+  "description": "Reusable PlatformCore React hooks.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^6.0.2",
+    "typescript": "~6.0.3",
+    "vite": "8.0.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && vite build",
+    "lint": "eslint ."
+  }
+}