hocmai-feedback-widget 0.2.2 → 0.2.3

package/README.md

@@ -1,136 +1,49 @@
 # 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)**.
-
-> 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.
-
-## Vì sao có bản này
-
-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**.
-
-Bản này thay bộ chụp bằng [**snapdom**](https://github.com/zumerlab/snapdom) + các kỹ thuật:
-
-- **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.
+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.
 
 ## Cài đặt
 
 ```bash
 npm install hocmai-feedback-widget
-# hoặc
-yarn add hocmai-feedback-widget
+# peer deps: react, react-dom
 ```
 
-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`.
-
-> 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) => {
-    // 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>
-  );
-}
+<FeedbackProvider onSubmit={async (data: FeedbackData) => {
+  await api.post('/questionReport/studentReport', data); // data.listImage là URL ảnh đã upload
+}}>
+  <App />
+</FeedbackProvider>
 ```
 
+`onSubmit` **không bắt buộc** ở Provider — có thể truyền theo từng lần ở `openFeedback` (xem dưới).
+
 ### 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';
+// 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 });
+// 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. |
+### 3. (Tùy chọn) Rich-text editor cho ô mô tả — `isCkEditor`
 
-### `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;
-}
-```
-
-### `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';
@@ -141,39 +54,56 @@ import CkEditor from 'hocmai-feedback-widget/ckeditor';
 </FeedbackProvider>
 ```
 
-**Khi dùng `descriptionEditor`/`hocmai-feedback-widget/ckeditor`, phải cài thêm:**
+Phải cài thêm các peer deps (chỉ khi dùng CKEditor):
+
 ```bash
 yarn add @ckeditor/ckeditor5-react 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.
+### 4. (Tùy chọn) Chụp màn hình trực tiếp
+
+```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)
+```
 
-> ⚠️ Khi bật CKEditor, `errorDescription` là **HTML** (không phải text thuần) — backend cần xử lý phù hợp.
+## API
 
-> 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`).
+**`FeedbackProvider`**
 
-## Cơ chế chụp & giới hạn
+| 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`). |
 
-- 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).
+**`useFeedback()`** → `{ openFeedback, closeFeedback, isOpen, activeQuestionId }`
+- `openFeedback(questionId, contextData?, onSubmit?)` — mở form; `onSubmit?` ghi đè handler của Provider cho lần này.
 
-## Phát triển
+**`FeedbackData`**
 
-```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)
+```ts
+{
+  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 ý
+
+- **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`.
+- 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.
+- An toàn **SSR** (không chạm `window`/`document` lúc import).
 
 ## License
-MIT
+MIT

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,7 +16,8 @@ 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;