hocmai-feedback-widget 0.2.2 → 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,136 +1,77 @@
 # 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)**.
+> 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**.
 
-> Phiên bản `0.2.2`. API tương thích ngược với `0.2.1` — nâng cấp chỉ cần đổi version, không phải sửa code sử dụng.
+![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)
 
-## Vì sao có bản này
+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.
 
-Bộ chụp ở các bản trước tự viết một "layered canvas renderer": quét toàn bộ DOM bằng
-`getBoundingClientRect()` (treo khi có hàng nghìn node `<mjx-*>`) và chỉ render được math dạng **SVG**.
-Nhưng app render công thức bằng **MathJax v3 CHTML** (HTML + web-font riêng) nên ảnh bị **treo** và
-**trắng / mất công thức**.
+## Mục lục
 
-Bản này thay bộ chụp bằng [**snapdom**](https://github.com/zumerlab/snapdom) + các kỹ thuật:
+- [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)
 
-- **Prune off-screen**: chỉ clone phần tử trong vùng nhìn thấy → nhanh (~2s) dù trang cao hàng chục nghìn px.
-- **Nhúng font MathJax CHTML thành data-URI** trước khi chụp → công thức render đủ **ngay lần đầu** (hết lỗi `____`).
-- **Hâm nóng lúc mở form** (nền, trong khi người dùng gõ mô tả) → lúc bấm chụp chỉ còn 1 lượt nhanh.
-- **Fallback** `modern-screenshot` + **timeout** cứng (mặc định 20s) → không bao giờ treo vô hạn.
+## 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
-# hoặc
-yarn add hocmai-feedback-widget
 ```
 
-Peer deps bắt buộc: `react`, `react-dom` (>=16.8).
-
-Peer deps **tùy chọn** (chỉ khi dùng `isCkEditor`, xem mục [CKEditor](#trình-soạn-thảo-ckeditor-isckeditor)):
-`@ckeditor/ckeditor5-react@^41.2.0`, `hocmai-ckeditor-custom`, `ckeditor5-classic-with-mathtype@1.0.0`.
+**Peer dependencies:** `react`, `react-dom` (>= 16.8).
 
-> Cài qua tarball/local khi phát triển: `npm pack` rồi `yarn add ./hocmai-feedback-widget-0.2.2.tgz`.
-
-## Dùng nhanh
+## Sử dụng
 
 ### 1. Bọc app bằng `FeedbackProvider`
+
 ```tsx
 import { FeedbackProvider, type FeedbackData } from 'hocmai-feedback-widget';
 
-function App({ Component, pageProps }) {
-  const handleSubmit = async (data: FeedbackData) => {
+<FeedbackProvider
+  onSubmit={async (data: FeedbackData) => {
     // data.listImage: mảng URL ảnh đã upload
-    // data.deviceInfo, data.errorType, data.errorDescription, data.idQuestion...
     await api.post('/questionReport/studentReport', data);
-  };
-
-  return (
-    <FeedbackProvider onSubmit={handleSubmit} themeColor="#3b82f6">
-      <Component {...pageProps} />
-    </FeedbackProvider>
-  );
-}
+  }}
+>
+  <App />
+</FeedbackProvider>;
 ```
 
+> `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`
+
 ```tsx
 import { useFeedback } from 'hocmai-feedback-widget';
 
-const QuestionItem = ({ question }) => {
-  const { openFeedback } = useFeedback();
-  return (
-    <button onClick={() => openFeedback(question.id, { questionIdChild: question.childId })}>
-      Báo lỗi
-    </button>
-  );
-};
-```
+const { openFeedback } = useFeedback();
 
-### 3. Chụp màn hình trực tiếp (tùy chọn)
-```ts
-import { captureScreenshot, captureScreenshotWithOptions } from 'hocmai-feedback-widget';
+// a) Dùng onSubmit của Provider:
+openFeedback(questionId, { questionIdChild });
 
-const png = await captureScreenshot();                            // toàn viewport
-const region = await captureScreenshot({ x, y, width, height });  // 1 vùng (toạ độ viewport)
-const tuned = await captureScreenshotWithOptions(undefined, { scale: 2, timeoutMs: 30000 });
+// 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);
+});
 ```
 
-## API
-
-### `FeedbackProvider`
-| Prop | Kiểu | Mặc định | Mô tả |
-|------|------|----------|-------|
-| `onSubmit` | `(data: FeedbackData) => Promise<void>` | (bắt buộc) | Gọi khi gửi báo lỗi. |
-| `themeColor` | `string` | `#3b82f6` | Màu chủ đạo nút/viền. |
-| `isCkEditor` | `boolean` | `false` | Dùng CKEditor (rich-text) cho ô mô tả thay vì textarea. |
-| `children` | `ReactNode` | — | Nội dung app. |
-
-### `useFeedback()`
-- `openFeedback(questionId, contextData?)` — mở form. `contextData.questionIdChild` sẽ tự điền ô "ID câu hỏi con".
-- `closeFeedback()` — đóng form.
-- `isOpen`, `activeQuestionId` — trạng thái hiện tại.
-
-### `FeedbackData`
-```ts
-interface FeedbackData {
-  idQuestion: string | number;
-  idChildQuestion?: string | number;
-  errorType: string;        // incorrect_content | display_error | missing_data | technical_issue | other
-  errorDescription: string; // text; là HTML nếu bật isCkEditor
-  listImage: string[];      // URL ảnh đã upload (tối đa 3)
-  deviceInfo: { os; osVersion; browser; browserVersion; deviceType };
-  contextData?: any;
-}
-```
+### 3. Rich-text editor cho ô mô tả _(tùy chọn)_
 
-### `FeedbackWidget` (dùng độc lập, không qua Provider)
-| Prop | Kiểu | Mặc định | Mô tả |
-|------|------|----------|-------|
-| `questionId` | `string \| number` | (bắt buộc) | ID câu hỏi. |
-| `onSubmit` | `function` | (bắt buộc) | Nhận `FeedbackData`. |
-| `contextData` | `object` | — | Dữ liệu kèm theo (vd `questionIdChild`). |
-| `themeColor` | `string` | `#3b82f6` | Màu chủ đạo. |
-| `isOpen` / `onClose` / `onOpen` | — | — | Điều khiển hiển thị thủ công. |
-| `isEnableCaptureFull` | `boolean` | `true` | Bật nút "Toàn màn hình". |
-| `isEnableCaptureElement` | `boolean` | `true` | Bật nút "Chọn vùng". |
-| `isCkEditor` | `boolean` | `false` | Dùng CKEditor cho ô mô tả. |
-| `uploadUrl` | `string` | endpoint LCMS mặc định | Nơi upload ảnh `{ base64 }` → trả `{ file_url }`. |
-
-### Tiện ích chụp
-- `captureScreenshot(cropRect?, onProgress?) => Promise<string | null>` — trả PNG data-URL (hoặc `null` nếu thất bại).
-- `captureScreenshotWithOptions(cropRect, options)` — `options`: `{ scale?, backgroundColor?, timeoutMs?, excludeSelectors?, onProgress? }`.
-- `prewarmCapture()` — hâm nóng font/cache (tự gọi khi form mở).
-- Types: `Rect`, `CaptureProgress`, `CaptureOptions`.
-
-## Trình soạn thảo CKEditor (`isCkEditor`)
-
-Mặc định ô mô tả là textarea. Muốn dùng **CKEditor (kèm MathType)**, bật `isCkEditor` **và truyền component
-editor** qua prop `descriptionEditor`. Editor nằm ở **entry phụ** `hocmai-feedback-widget/ckeditor`.
-
-> Vì sao tách rời? Để **core widget không phụ thuộc CKEditor** — app không dùng CKEditor vẫn build bình
-> thường, không cần cài deps CKEditor. Chỉ ai dùng `descriptionEditor` mới cần cài.
+Bật `isCkEditor` **và** truyền `descriptionEditor` (editor đóng gói sẵn ở entry phụ):
 
 ```tsx
 import { FeedbackProvider } from 'hocmai-feedback-widget';
@@ -138,42 +79,82 @@ import CkEditor from 'hocmai-feedback-widget/ckeditor';
 
 <FeedbackProvider onSubmit={handleSubmit} isCkEditor descriptionEditor={CkEditor}>
   <App />
-</FeedbackProvider>
+</FeedbackProvider>;
 ```
 
-**Khi dùng `descriptionEditor`/`hocmai-feedback-widget/ckeditor`, phải cài thêm:**
+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
 ```
 
-> ⚠️ **Xung đột phiên bản:** `hocmai-ckeditor-custom` là build kiểu cũ → phải dùng `@ckeditor/ckeditor5-react`
-> đời cũ (v5/v6), **KHÔNG** dùng latest (v11 cần `ckeditor5>=46`). Nên **copy đúng version** của 3 package
-> này từ project gốc đang chạy CKEditor. Build này đã chứa sẵn core nên **không cần** `@ckeditor/ckeditor5-core` riêng.
+**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.
 
-> ⚠️ Khi bật CKEditor, `errorDescription` là **HTML** (không phải text thuần) — backend cần xử lý phù hợp.
+### 4. Chụp màn hình trực tiếp _(tùy chọn)_
 
-> Bạn cũng có thể truyền editor của riêng mình cho `descriptionEditor` (component nhận props
-> `{ handleContent, contentQuestion, error, placeholder, uploadUrl }` — xem type `CkEditorProps`).
+```ts
+import { captureScreenshot } from 'hocmai-feedback-widget';
 
-## Cơ chế chụp & giới hạn
+const png = await captureScreenshot(); // toàn viewport
+const region = await captureScreenshot({ x, y, width, height }); // 1 vùng (toạ độ viewport)
+```
 
-- Mặc định chụp **vùng viewport** (hoặc vùng crop), không phải toàn trang → nhanh kể cả trang dài.
-- UI của chính widget tự bị loại khỏi ảnh (qua thuộc tính `data-hsa-report-ui`).
-- `scale` mặc định theo thiết bị, bị giới hạn bởi kích thước canvas tối đa của trình duyệt (16384px/cạnh).
-- An toàn SSR (không chạm `window`/`document` lúc import).
+## API
 
-## Phát triển
+### `FeedbackProvider`
 
-```bash
-npm install
-npm run dev        # dev harness: 60 câu nhiều công thức MathJax CHTML
-npm run typecheck  # kiểm tra kiểu
-npm run test       # Playwright: chụp nhanh + không trắng + đúng vùng + cuộn
-npm run build      # build dist (esm .mjs + umd .cjs + .d.ts)
+| 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()`
+
+Trả về:
+
+| 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). |
+
+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
+  errorDescription: string; // text; là HTML nếu dùng CKEditor
+  listImage: string[]; // URL ảnh đã upload (tối đa 3)
+  deviceInfo: { os; osVersion; browser; browserVersion; deviceType };
+  contextData?: any;
+}
 ```
 
-## Migrate từ `hocmai-feedback-widget@0.2.1`
-Chỉ cần nâng version — API `FeedbackProvider`/`useFeedback`/`FeedbackData` giữ nguyên. Không phải sửa code sử dụng. (Bản này thêm tùy chọn `isCkEditor` và `uploadUrl`.)
+## Lưu ý
+
+- **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.
+- An toàn **SSR** (không chạm `window`/`document` lúc import).
 
 ## License
-MIT
+
+[MIT](./LICENSE)

package/dist/components/FeedbackWidget.d.ts

@@ -13,7 +13,8 @@ export interface FeedbackData {
 export interface FeedbackProps {
     questionId: string | number;
     contextData?: Record<string, any>;
-    onSubmit: (data: FeedbackData) => Promise<void>;
+    /** Submit handler. Optional — may be provided per call via openFeedback or at the Provider. */
+    onSubmit?: (data: FeedbackData) => Promise<void> | void;
     themeColor?: string;
     triggerComponent?: React.ReactNode;
     isOpen?: boolean;

package/dist/context/FeedbackContext.d.ts

@@ -1,8 +1,14 @@
 import { default as React, ReactNode } from 'react';
 import { FeedbackData } from '../components/FeedbackWidget';
 import { CkEditorProps } from '../components/CkEditor';
+export type FeedbackSubmitHandler = (data: FeedbackData) => Promise<void> | void;
 interface FeedbackContextType {
-    openFeedback: (questionId: string | number, contextData?: any) => void;
+    /**
+     * Open the report form.
+     * @param onSubmit optional per-call handler; overrides the Provider's onSubmit
+     *                 for this submission. Lets you handle submit from anywhere.
+     */
+    openFeedback: (questionId: string | number, contextData?: any, onSubmit?: FeedbackSubmitHandler) => void;
     closeFeedback: () => void;
     isOpen: boolean;
     activeQuestionId: string | number | null;
@@ -10,12 +16,19 @@ interface FeedbackContextType {
 export declare const useFeedback: () => FeedbackContextType;
 interface FeedbackProviderProps {
     children: ReactNode;
-    onSubmit: (data: FeedbackData) => Promise<void>;
+    /** Default submit handler. Optional — you can instead pass one per call via openFeedback. */
+    onSubmit?: FeedbackSubmitHandler;
     themeColor?: string;
     /** Use the rich-text editor for the description instead of a plain textarea. */
     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 {};