hocmai-feedback-widget 0.2.3 → 0.2.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HOCMAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,39 @@
 # hocmai-feedback-widget
 
-Widget báo lỗi câu hỏi kèm chụp ảnh màn hình, tối ưu cho trang nhiều công thức **MathJax CHTML**. ESM, tương thích React ≥ 16.8.
+> Widget báo lỗi câu hỏi kèm chụp ảnh màn hình, tối ưu cho trang nhiều công thức **MathJax CHTML**.
+
+![version](https://img.shields.io/badge/version-0.2.3-blue)
+![react](https://img.shields.io/badge/react-%E2%89%A516.8-61dafb)
+![module](https://img.shields.io/badge/module-ESM-f7df1e)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+Bộ chụp dùng [snapdom](https://github.com/zumerlab/snapdom) + nhúng font MathJax → chụp nhanh, đủ công thức ngay lần đầu, an toàn SSR.
+
+## Mục lục
+
+- [Tính năng](#tính-năng)
+- [Cài đặt](#cài-đặt)
+- [Sử dụng](#sử-dụng)
+- [API](#api)
+- [Lưu ý](#lưu-ý)
+- [License](#license)
+
+## Tính năng
+
+- 📸 Chụp **toàn màn hình** hoặc **chọn vùng**, render đúng công thức MathJax CHTML.
+- 📝 Mô tả lỗi bằng **textarea** hoặc **CKEditor** (tùy chọn).
+- 🖼️ Tự upload ảnh và trả về URL (tối đa 3 ảnh).
+- 🔌 API gọn: `FeedbackProvider` + hook `useFeedback`.
+- 🧩 Core **không** phụ thuộc CKEditor — chỉ cài khi cần.
 
 ## Cài đặt
 
 ```bash
 npm install hocmai-feedback-widget
-# peer deps: react, react-dom
 ```
 
+**Peer dependencies:** `react`, `react-dom` (>= 16.8).
+
 ## Sử dụng
 
 ### 1. Bọc app bằng `FeedbackProvider`
@@ -16,14 +41,17 @@ npm install hocmai-feedback-widget
 ```tsx
 import { FeedbackProvider, type FeedbackData } from 'hocmai-feedback-widget';
 
-<FeedbackProvider onSubmit={async (data: FeedbackData) => {
-  await api.post('/questionReport/studentReport', data); // data.listImage là URL ảnh đã upload
-}}>
+<FeedbackProvider
+  onSubmit={async (data: FeedbackData) => {
+    // data.listImage: mảng URL ảnh đã upload
+    await api.post('/questionReport/studentReport', data);
+  }}
+>
   <App />
-</FeedbackProvider>
+</FeedbackProvider>;
 ```
 
-`onSubmit` **không bắt buộc** ở Provider — có thể truyền theo từng lần ở `openFeedback` (xem dưới).
+> `onSubmit` **không bắt buộc** ở Provider — có thể truyền theo từng lần ở `openFeedback` (xem mục 2).
 
 ### 2. Mở form từ component con bằng `useFeedback`
 
@@ -32,16 +60,16 @@ import { useFeedback } from 'hocmai-feedback-widget';
 
 const { openFeedback } = useFeedback();
 
-// Dùng onSubmit của Provider:
+// a) Dùng onSubmit của Provider:
 openFeedback(questionId, { questionIdChild });
 
-// Hoặc truyền handler riêng cho lần gọi này (ghi đè Provider):
+// b) Hoặc truyền handler riêng cho lần gọi này (ghi đè Provider):
 openFeedback(questionId, { questionIdChild }, async (data) => {
   await api.post('/questionReport/studentReport', data);
 });
 ```
 
-### 3. (Tùy chọn) Rich-text editor cho ô mô tả — `isCkEditor`
+### 3. Rich-text editor cho ô mô tả _(tùy chọn)_
 
 Bật `isCkEditor` **và** truyền `descriptionEditor` (editor đóng gói sẵn ở entry phụ):
 
@@ -51,47 +79,69 @@ import CkEditor from 'hocmai-feedback-widget/ckeditor';
 
 <FeedbackProvider onSubmit={handleSubmit} isCkEditor descriptionEditor={CkEditor}>
   <App />
-</FeedbackProvider>
+</FeedbackProvider>;
 ```
 
-Phải cài thêm các peer deps (chỉ khi dùng CKEditor):
+Cài thêm peer deps (chỉ khi dùng CKEditor):
 
 ```bash
-yarn add @ckeditor/ckeditor5-react hocmai-ckeditor-custom ckeditor5-classic-with-mathtype
+yarn add @ckeditor/ckeditor5-react@5.0.0 hocmai-ckeditor-custom ckeditor5-classic-with-mathtype
 ```
 
-### 4. (Tùy chọn) Chụp màn hình trực tiếp
+**Lưu ý**: `@ckeditor/ckeditor5-react` chỉ hỗ trợ version 5, `hocmai-ckeditor-custom` có thể dùng version 0.0.2 hoặc 0.0.7 trở lên.
+
+### 4. Chụp màn hình trực tiếp _(tùy chọn)_
 
 ```ts
 import { captureScreenshot } from 'hocmai-feedback-widget';
 
-const png = await captureScreenshot();                            // toàn viewport
-const region = await captureScreenshot({ x, y, width, height });  // 1 vùng (toạ độ viewport)
+const png = await captureScreenshot(); // toàn viewport
+const region = await captureScreenshot({ x, y, width, height }); // 1 vùng (toạ độ viewport)
 ```
 
 ## API
 
-**`FeedbackProvider`**
+### `FeedbackProvider`
+
+| Prop | Kiểu | Bắt buộc | Mặc định | Mô tả |
+| --- | --- | :---: | :---: | --- |
+| `children` | `ReactNode` | ✓ | — | Nội dung app được bọc. |
+| `onSubmit` | `(data: FeedbackData) => Promise<void> \| void` | — | — | Handler mặc định khi gửi báo lỗi. Có thể bỏ, truyền theo từng lần ở `openFeedback`. |
+| `themeColor` | `string` | — | `#3b82f6` | Màu chủ đạo của nút/viền. |
+| `isCkEditor` | `boolean` | — | `false` | Dùng rich-text editor cho ô mô tả (cần kèm `descriptionEditor`). |
+| `descriptionEditor` | `ComponentType<CkEditorProps>` | — | — | Component editor cho ô mô tả, vd `import CkEditor from 'hocmai-feedback-widget/ckeditor'`. |
+| `isEnableCaptureFull` | `boolean` | — | `true` | Hiện nút "Toàn màn hình". |
+| `isEnableCaptureElement` | `boolean` | — | `true` | Hiện nút "Chọn vùng". |
+| `uploadUrl` | `string` | — | endpoint LCMS | Nơi upload ảnh: nhận `{ base64 }`, trả `{ file_url }`. |
+
+### `useFeedback()`
 
-| Prop | Kiểu | Mô tả |
-|------|------|-------|
-| `onSubmit` | `(data: FeedbackData) => Promise<void> \| void` | Tùy chọn. Handler mặc định khi gửi. |
-| `isCkEditor` | `boolean` | Dùng rich-text editor cho ô mô tả (cần `descriptionEditor`). |
-| `descriptionEditor` | `ComponentType` | Editor truyền vào, vd `import CkEditor from 'hocmai-feedback-widget/ckeditor'`. |
-| `themeColor` | `string` | Màu chủ đạo (mặc định `#3b82f6`). |
+Trả về:
 
-**`useFeedback()`** → `{ openFeedback, closeFeedback, isOpen, activeQuestionId }`
-- `openFeedback(questionId, contextData?, onSubmit?)` — mở form; `onSubmit?` ghi đè handler của Provider cho lần này.
+| Thành phần | Kiểu | Mô tả |
+| --- | --- | --- |
+| `openFeedback` | `(questionId, contextData?, onSubmit?) => void` | Mở form báo lỗi cho một câu hỏi. |
+| `closeFeedback` | `() => void` | Đóng form. |
+| `isOpen` | `boolean` | Form đang mở hay không. |
+| `activeQuestionId` | `string \| number \| null` | ID câu hỏi đang mở form (`null` nếu đóng). |
 
-**`FeedbackData`**
+Tham số của `openFeedback`:
+
+| Tham số | Kiểu | Bắt buộc | Mô tả |
+| --- | --- | :---: | --- |
+| `questionId` | `string \| number` | ✓ | ID câu hỏi; tự điền vào ô "ID câu hỏi". |
+| `contextData` | `object` | — | Dữ liệu kèm theo (trả lại trong `FeedbackData.contextData`). `contextData.questionIdChild` tự điền ô "ID câu hỏi con". |
+| `onSubmit` | `(data: FeedbackData) => Promise<void> \| void` | — | Handler riêng cho lần gọi này, **ghi đè** `onSubmit` của Provider. |
+
+### `FeedbackData`
 
 ```ts
-{
+interface FeedbackData {
   idQuestion: string | number;
   idChildQuestion?: string | number;
-  errorType: string;        // incorrect_content | display_error | missing_data | technical_issue | other
+  errorType: string; // incorrect_content | display_error | missing_data | technical_issue | other
   errorDescription: string; // text; là HTML nếu dùng CKEditor
-  listImage: string[];      // URL ảnh đã upload (tối đa 3)
+  listImage: string[]; // URL ảnh đã upload (tối đa 3)
   deviceInfo: { os; osVersion; browser; browserVersion; deviceType };
   contextData?: any;
 }
@@ -99,11 +149,12 @@ const region = await captureScreenshot({ x, y, width, height });  // 1 vùng (to
 
 ## Lưu ý
 
-- **onSubmit** ưu tiên: handler theo lần gọi → handler ở Provider → không có thì chỉ cảnh báo (không crash).
-- **CKEditor**: `hocmai-ckeditor-custom` là build kiểu cũ → dùng `@ckeditor/ckeditor5-react` đời cũ (v5/v6), **không** dùng latest. Nên copy đúng version từ project gốc. Build này đã chứa core, **không cần** cài `@ckeditor/ckeditor5-core`.
+- **Thứ tự `onSubmit`:** handler theo lần gọi → handler ở Provider → nếu không có thì chỉ cảnh báo (không crash).
+- **CKEditor:** `hocmai-ckeditor-custom` là build kiểu cũ → dùng `@ckeditor/ckeditor5-react` đời cũ (v5/v6), **không** dùng latest. Nên copy đúng version từ project gốc. Build này đã chứa core nên **không cần** cài `@ckeditor/ckeditor5-core`.
 - Khi dùng CKEditor, `errorDescription` trả về là **HTML** — backend cần xử lý phù hợp.
-- Core **không** phụ thuộc CKEditor: app không dùng `isCkEditor` vẫn build bình thường, không cần cài deps CKEditor.
+- Core **không** phụ thuộc CKEditor: app không dùng `isCkEditor` vẫn build bình thường.
 - An toàn **SSR** (không chạm `window`/`document` lúc import).
 
 ## License
-MIT
+
+[MIT](./LICENSE)

package/dist/context/FeedbackContext.d.ts

@@ -23,6 +23,12 @@ interface FeedbackProviderProps {
     isCkEditor?: boolean;
     /** Editor component for the description (from `hocmai-feedback-widget/ckeditor` or your own). */
     descriptionEditor?: React.ComponentType<CkEditorProps>;
+    /** Show the "full screen" capture button. Default true. */
+    isEnableCaptureFull?: boolean;
+    /** Show the "select region" capture button. Default true. */
+    isEnableCaptureElement?: boolean;
+    /** Endpoint that accepts { base64 } and returns { file_url } for image uploads. */
+    uploadUrl?: string;
 }
 export declare const FeedbackProvider: React.FC<FeedbackProviderProps>;
 export {};

package/dist/hocmai-feedback-widget.mjs

@@ -7003,8 +7003,8 @@ const rd = [
           alignItems: "center",
           justifyContent: "center",
           cursor: "zoom-out",
-          animation: "fb-fade-in 0.2s ease-out",
-          backdropFilter: "blur(4px)"
+          animation: "fb-fade-in 0.15s ease-out",
+          willChange: "opacity"
         },
         onClick: () => k(null),
         children: /* @__PURE__ */ _(
@@ -7013,6 +7013,7 @@ const rd = [
             src: E,
             alt: "Zoomed",
             draggable: !1,
+            decoding: "async",
             onContextMenu: (I) => I.preventDefault(),
             style: {
               maxWidth: "90vw",
@@ -7066,7 +7067,7 @@ const rd = [
         )
       }
     ),
-    L && /* @__PURE__ */ _("div", { "data-hsa-report-ui": "true", style: { position: "fixed", top: 20, right: 20, background: "rgba(0,0,0,0.8)", color: "white", padding: "8px 12px", borderRadius: "8px", zIndex: 1e4, fontWeight: 500, backdropFilter: "blur(4px)", fontSize: "0.8rem" }, children: "Đang chụp..." }),
+    L && /* @__PURE__ */ _("div", { "data-hsa-report-ui": "true", style: { position: "fixed", top: 20, right: 20, background: "rgba(0,0,0,0.8)", color: "white", padding: "8px 12px", borderRadius: "8px", zIndex: 1e4, fontWeight: 500, fontSize: "0.8rem" }, children: "Đang chụp..." }),
     X && !j && !E && /* @__PURE__ */ K("div", { className: "fb-widget-modal", "data-hsa-report-ui": "true", children: [
       /* @__PURE__ */ K("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [
         /* @__PURE__ */ _("h2", { style: { margin: 0, fontSize: "1rem", fontWeight: 700, color: "#111827" }, children: "Báo lỗi" }),
@@ -7504,36 +7505,42 @@ const rd = [
   onSubmit: t,
   themeColor: r,
   isCkEditor: n,
-  descriptionEditor: o
+  descriptionEditor: o,
+  isEnableCaptureFull: i,
+  isEnableCaptureElement: a,
+  uploadUrl: l
 }) => {
-  const [i, a] = ie(!1), [l, s] = ie(null), [u, c] = ie(void 0), [d, f] = ie(void 0), h = (g, y, x) => {
-    s(g), c(y), f(() => x), a(!0);
-  }, m = () => {
-    a(!1);
-  }, p = async (g) => {
-    const y = d ?? t;
-    if (!y) {
+  const [s, u] = ie(!1), [c, d] = ie(null), [f, h] = ie(void 0), [m, p] = ie(void 0), g = (w, b, S) => {
+    d(w), h(b), p(() => S), u(!0);
+  }, y = () => {
+    u(!1);
+  }, x = async (w) => {
+    const b = m ?? t;
+    if (!b) {
       console.warn(
         "[feedback-widget] Bỏ qua gửi báo lỗi: chưa cung cấp onSubmit (ở FeedbackProvider hoặc openFeedback). Dữ liệu:",
-        g
+        w
       );
       return;
     }
-    await y(g);
+    await b(w);
   };
-  return /* @__PURE__ */ K(Oo.Provider, { value: { openFeedback: h, closeFeedback: m, isOpen: i, activeQuestionId: l }, children: [
+  return /* @__PURE__ */ K(Oo.Provider, { value: { openFeedback: g, closeFeedback: y, isOpen: s, activeQuestionId: c }, children: [
     e,
-    l && /* @__PURE__ */ _(
+    c && /* @__PURE__ */ _(
       od,
       {
-        questionId: l,
-        contextData: u,
-        onSubmit: p,
+        questionId: c,
+        contextData: f,
+        onSubmit: x,
         themeColor: r,
         isCkEditor: n,
         descriptionEditor: o,
-        isOpen: i,
-        onClose: m,
+        isEnableCaptureFull: i,
+        isEnableCaptureElement: a,
+        uploadUrl: l,
+        isOpen: s,
+        onClose: y,
         triggerComponent: /* @__PURE__ */ _($t, {})
       }
     )