@thangph2146/nextjs-editor 1.0.3 → 1.0.5

package/README.md

@@ -26,7 +26,7 @@ Trong `app/layout.tsx` hoặc `_app.tsx`:
 import "@thangph2146/nextjs-editor/styles.css"
 ```
 
-**Lưu ý:** Chỉ cần import file trên. Bạn **không** cần thêm `@source` hay cấu hình nào trong `globals.css`. Style editor được đóng gói sẵn và scope trong `#editor-x` nên không bị style dự án ghi đè.
+**Lưu ý:** Chỉ cần import file trên. Bạn **không** cần thêm `@source` hay cấu hình nào trong `globals.css`. Style editor được đóng gói sẵn, scope trong `#editor-x` và nằm trong layer `nextjs-editor` — nếu app dùng CSS layer cho SCSS/global (xem bên dưới), style editor sẽ không bị ghi đè.
 
 ### 2. Dùng component Editor (Client Component)
 
@@ -61,9 +61,188 @@ export function MyEditor() {
 
 ## Ghi chú
 
-- **Ảnh**: Trong bản standalone, dialog chèn ảnh chỉ có tab **URL** và **File**. Để tab **Thư viện** hiển thị ảnh từ API của project, trong `next.config` (webpack) thêm alias: `"@thangph2146/nextjs-editor/uploads-hooks"` → đường dẫn tới file hooks uploads của app (ví dụ `src/features/uploads/hooks/use-uploads-queries.ts`). Hook cần export `useImagesList(page, limit)` trả về `{ data: { data: { folderTree, pagination } }, isLoading }` với `folderTree` có cấu trúc `FolderNode` (name, path, images, subfolders).
+- **Ảnh**: Mặc định dialog chèn ảnh có tab **URL** và **File**. Để tab **Thư viện** hiển thị ảnh từ API của project, xem [Cấu hình API thư viện ảnh](#cấu-hình-api-thư-viện-ảnh) bên dưới.
 - **Next.js**: Package dùng `next/image` và `next/dynamic` khi chạy trong Next.js; cần cài `next` trong project.
 
+## Tránh SCSS/CSS của app ghi đè editor
+
+Style editor được bọc trong **`@layer nextjs-editor`**. Trong CSS, rule **không nằm trong layer** (unlayered) có độ ưu tiên cao hơn rule trong layer, nên nếu SCSS/global của app là unlayered thì có thể ghi đè list, spacing, typography… bên trong `#editor-x`.
+
+**Cách làm:** Đưa toàn bộ SCSS/global của app vào một layer (ví dụ `app`) và khai báo thứ tự layer sao cho `nextjs-editor` đứng **sau** — khi đó style editor sẽ thắng khi specificity tương đương.
+
+### Bước 1: Khai báo thứ tự layer trong app
+
+Trong `globals.css` (hoặc file CSS chính), **dòng đầu tiên** khai báo thứ tự layer, thêm `app` và `nextjs-editor` (layer xuất hiện sau có ưu tiên cao hơn):
+
+```css
+@layer legacy, base, components, utilities, app, nextjs-editor;
+```
+
+### Bước 2: Đưa SCSS/global vào layer `app`
+
+Mọi style global/SCSS không nằm trong Tailwind (base, typography, components từ SCSS…) cần nằm trong `@layer app`.
+
+**Cách A — Bọc toàn bộ file SCSS chính:**
+
+Trong file SCSS chính (ví dụ `src/styles/main.scss`), bọc toàn bộ nội dung trong `@layer app`:
+
+```scss
+@layer app {
+  @use "abstracts/variables" as *;
+  @use "abstracts/mixins" as *;
+  @use "base/base";
+  @use "base/typography";
+  @use "components/header";
+  /* ... các @use khác ... */
+}
+```
+
+**Cách B — Import SCSS từ một file CSS có layer:**
+
+Tạo file `src/app/globals-app.css`:
+
+```css
+@layer app {
+  @import "../styles/main.scss";
+}
+```
+
+Rồi trong `layout.tsx` import sau `globals.css`: `import "./globals-app.css"`.
+
+Sau khi cấu hình, style trong layer `nextjs-editor` (đã load khi import `@thangph2146/nextjs-editor/styles.css`) sẽ có ưu tiên cao hơn layer `app`, nên cấu trúc Tailwind và theme của editor trong `#editor-x` không còn bị SCSS của app ghi đè.
+
+## Cấu hình API thư viện ảnh
+
+Tab **Thư viện** trong dialog chèn ảnh cần dữ liệu từ API/uploads của project. Bạn cấu hình bằng cách **alias** module uploads-hooks của package sang file hooks trong project.
+
+### Bước 1: Alias trong Next.js
+
+Trong `next.config.ts` (hoặc `next.config.js`), thêm `webpack.resolve.alias` để trỏ `@thangph2146/nextjs-editor/uploads-hooks` sang file hooks uploads của project:
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+import path from "path";
+
+const nextConfig: NextConfig = {
+  // ... config khác
+  webpack: (config) => {
+    config.resolve ??= {};
+    config.resolve.alias = {
+      ...config.resolve.alias,
+      "@thangph2146/nextjs-editor/uploads-hooks": path.resolve(
+        __dirname,
+        "src/features/uploads/hooks/use-uploads-queries.ts"  // đường dẫn tới file hooks của bạn
+      ),
+    };
+    return config;
+  },
+};
+
+export default nextConfig;
+```
+
+Đường dẫn file có thể khác tùy cấu trúc project (ví dụ `src/lib/uploads-queries.ts`).
+
+### Bước 2: File hooks phải export `useImagesList`
+
+File được alias tới phải export hook `useImagesList(page, limit)` với đúng chuẩn:
+
+- **Tham số:** `page: number`, `limit: number` (ví dụ `useImagesList(1, 100)`).
+- **Giá trị trả về:** object tương thích với TanStack Query (useQuery), ít nhất:
+  - `data`: response từ API, có dạng:
+    - `data.data.folderTree`: cây thư mục ảnh (xem kiểu `FolderNode` bên dưới).
+    - `data.data.pagination`: `{ page, limit, total, totalPages }` (tùy chọn).
+  - `isLoading`: boolean.
+
+**Kiểu dữ liệu (TypeScript):**
+
+```ts
+interface ImageItem {
+  fileName: string;
+  originalName: string;
+  size: number;
+  mimeType: string;
+  url: string;           // URL đầy đủ để hiển thị ảnh (img src)
+  relativePath: string;
+  createdAt: number;
+}
+
+interface FolderNode {
+  name: string;
+  path: string;
+  images: ImageItem[];
+  subfolders: FolderNode[];  // đệ quy
+}
+```
+
+**Ví dụ hook (gọi API):**
+
+```ts
+// useImagesList gọi GET /api/uploads?page=1&limit=100 (hoặc endpoint của bạn)
+export function useImagesList(page = 1, limit = 50) {
+  return useQuery({
+    queryKey: ["uploads", "images", page, limit],
+    queryFn: async () => {
+      const res = await fetch(`/api/uploads?page=${page}&limit=${limit}`);
+      const json = await res.json();
+      if (!json.success) throw new Error("Failed to fetch images");
+      return json; // { success, data: { data: [], folderTree, pagination } }
+    },
+  });
+}
+```
+
+### Bước 3: API backend trả về `folderTree`
+
+Endpoint list ảnh (ví dụ `GET /api/uploads` hoặc `GET /api/admin/uploads`) nên trả về JSON có **folderTree** — cây thư mục chứa ảnh, để editor hiển thị theo cấu trúc thư mục.
+
+**Ví dụ response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "data": [],
+    "folderTree": {
+      "name": "images",
+      "path": "images",
+      "images": [
+        {
+          "fileName": "2024/01/15/abc.jpg",
+          "originalName": "abc.jpg",
+          "size": 12345,
+          "mimeType": "image/jpeg",
+          "url": "https://example.com/api/uploads/serve/images/2024/01/15/abc.jpg",
+          "relativePath": "images/2024/01/15/abc.jpg",
+          "createdAt": 1705312800000
+        }
+      ],
+      "subfolders": [
+        {
+          "name": "2024",
+          "path": "images/2024",
+          "images": [],
+          "subfolders": []
+        }
+      ]
+    },
+    "pagination": { "page": 1, "limit": 100, "total": 50, "totalPages": 1 }
+  }
+}
+```
+
+- `folderTree.url` (hoặc mỗi `ImageItem.url`) phải là URL mà trình duyệt tải được (absolute hoặc same-origin).
+- Nếu không có alias, tab Thư viện sẽ hiển thị "Chưa có hình ảnh nào được upload" (stub mặc định).
+
+### Tóm tắt
+
+| Việc | Mô tả |
+|------|--------|
+| Alias | `@thangph2146/nextjs-editor/uploads-hooks` → file hooks uploads của project (next.config webpack). |
+| Hook | File đó export `useImagesList(page, limit)` trả về `{ data, isLoading }`, `data.data.folderTree` kiểu `FolderNode`. |
+| API | Backend trả về list ảnh kèm `folderTree` (cây thư mục + ảnh trong từng thư mục). |
+
 ## Build từ source
 
 ```bash

package/dist/index.cjs

@@ -23258,6 +23258,33 @@ function applyListColorToDom(dom, color) {
   dom.style.setProperty("--list-marker-color", color, "important");
   dom.setAttribute("data-list-color", color);
 }
+function getListColorFromDom(dom) {
+  const attr = dom.getAttribute("data-list-color");
+  if (attr) return attr;
+  const style = dom.style.getPropertyValue("list-style-color") || dom.style.getPropertyValue("--list-marker-color");
+  if (style) return style.trim();
+  const computed = typeof window !== "undefined" ? window.getComputedStyle(dom).getPropertyValue("list-style-color") : "";
+  return computed && computed !== "currentcolor" ? computed.trim() : void 0;
+}
+function $convertListWithColorElement(domNode) {
+  if (!(domNode instanceof HTMLElement)) return null;
+  const nodeName = domNode.nodeName.toLowerCase();
+  let listType = "bullet";
+  let start = 1;
+  if (nodeName === "ol") {
+    listType = "number";
+    const startAttr = domNode.getAttribute("start");
+    start = startAttr != null ? parseInt(startAttr, 10) || 1 : 1;
+  } else if (nodeName === "ul") {
+    listType = "bullet";
+  } else {
+    return null;
+  }
+  const node = $createListWithColorNode(listType, start);
+  const color = getListColorFromDom(domNode);
+  if (color) node.setListColor(color);
+  return { node };
+}
 var ListWithColorNode = class _ListWithColorNode extends import_list.ListNode {
   __listColor;
   constructor(listType, start, key) {
@@ -23266,6 +23293,12 @@ var ListWithColorNode = class _ListWithColorNode extends import_list.ListNode {
   static getType() {
     return LIST_WITH_COLOR_TYPE;
   }
+  static importDOM() {
+    return {
+      ol: () => ({ conversion: $convertListWithColorElement, priority: 0 }),
+      ul: () => ({ conversion: $convertListWithColorElement, priority: 0 })
+    };
+  }
   getType() {
     return LIST_WITH_COLOR_TYPE;
   }
@@ -23336,6 +23369,11 @@ var ListWithColorNode = class _ListWithColorNode extends import_list.ListNode {
     return json;
   }
 };
+function $createListWithColorNode(listType, start) {
+  return (0, import_lexical13.$applyNodeReplacement)(
+    new ListWithColorNode(listType, start)
+  );
+}
 function $isListWithColorNode(node) {
   return node instanceof ListWithColorNode;
 }