@ecomcx/ecomweb-admin-sdk 1.30.0 → 1.31.0

package/dist/index.d.ts

@@ -26,6 +26,19 @@ export declare const useApi: <T = any>(path: string | null) => {
     error: Error | null;
     reload(): void;
 };
+/**
+ * Đường dẫn của trang plugin: tham số theo mẫu đã đăng ký, query, điều hướng (CMS ≥ 1.20.0):
+ *   registerPage({ path: "/orders/:id", component: OrderPage });
+ *   function OrderPage() { const { params, navigate } = useAdminRoute(); … navigate("/orders"); }
+ * CMS cũ: params rỗng, navigate tải lại trang.
+ */
+export declare const useAdminRoute: () => import("./types.js").AdminRoute;
+/** Điều hướng trong admin từ bất kỳ đâu (kể cả ngoài component) — CMS < 1.20.0: tải lại trang. */
+export declare const navigate: (to: string, opts?: {
+    replace?: boolean;
+}) => void;
+/** Loại trường của plugin cho form tự sinh (settings, widget) — CMS < 1.20.0: bỏ qua (form hiện ô chữ). */
+export declare const registerFieldType: (def: import("./types.js").FieldTypeDefinition) => void | undefined;
 export declare const can: (capability: string) => boolean;
 /**
  * Khối cho trình soạn nội dung, khai báo bằng defineBlock (file dùng chung với phần website của plugin):
@@ -45,6 +58,13 @@ export declare const registerBlockPanel: (panel: import("./types.js").BlockPanel
  * CMS cũ (chưa có tab Mẫu) → bỏ qua, không lỗi.
  */
 export declare const registerPattern: (pattern: import("./types.js").EditorPattern) => void | undefined;
+/**
+ * Nguồn dữ liệu cho mục "Gắn dữ liệu" của trình soạn (đoạn văn, tiêu đề, ảnh, nút…):
+ *   registerBindingSource({ name: "shop/product", label: "%binding.product%", fields: [{ value: "price", label: "%binding.price%" }] })
+ * Website lấy giá trị bằng definePlugin({ bindingSources: { "shop/product": (args, ctx) => … } }) của theme-sdk.
+ * CMS cũ → bỏ qua, không lỗi.
+ */
+export declare const registerBindingSource: (source: import("./types.js").EditorBindingSource) => void | undefined;
 export { defineBlock, type BlockDefinition, type BlockDefinitionInput, type BlockAttrSpec } from "@ecomcx/ecomweb-content";
 /** Thêm node/mark TipTap cho trình soạn (cấp thấp — khối thường dùng registerBlock). */
 export declare const registerEditorExtension: (pack: import("./types.js").EditorExtensionPack) => void;

package/dist/index.js

@@ -21,6 +21,28 @@ export const getMetaBoxes = (postType) => (host().getMetaBoxes ? host().getMetaB
 /** Hook lấy toàn bộ state plugin UI trong host. */
 export const usePluginUi = () => (host().usePluginUi ? host().usePluginUi() : { metaBoxes: [], pages: {}, dashboardWidgets: [], postListColumns: [], termMetaBoxes: [], loaded: true, errors: [] });
 export const useApi = (path) => host().useApi(path);
+/**
+ * Đường dẫn của trang plugin: tham số theo mẫu đã đăng ký, query, điều hướng (CMS ≥ 1.20.0):
+ *   registerPage({ path: "/orders/:id", component: OrderPage });
+ *   function OrderPage() { const { params, navigate } = useAdminRoute(); … navigate("/orders"); }
+ * CMS cũ: params rỗng, navigate tải lại trang.
+ */
+export const useAdminRoute = () => host().useAdminRoute?.() ?? {
+    path: typeof location === "undefined" ? "/" : location.pathname, params: {},
+    query: typeof location === "undefined" ? {} : Object.fromEntries(new URLSearchParams(location.search)),
+    navigate: (to) => { if (typeof location !== "undefined")
+        location.assign(to); },
+};
+/** Điều hướng trong admin từ bất kỳ đâu (kể cả ngoài component) — CMS < 1.20.0: tải lại trang. */
+export const navigate = (to, opts) => {
+    const h = host();
+    if (h.navigate)
+        h.navigate(to, opts);
+    else if (typeof location !== "undefined")
+        location.assign(to);
+};
+/** Loại trường của plugin cho form tự sinh (settings, widget) — CMS < 1.20.0: bỏ qua (form hiện ô chữ). */
+export const registerFieldType = (def) => host().registerFieldType?.(def);
 export const can = (capability) => host().can(capability);
 /**
  * Khối cho trình soạn nội dung, khai báo bằng defineBlock (file dùng chung với phần website của plugin):
@@ -45,6 +67,13 @@ export const registerBlockPanel = (panel) => host().editor.registerBlockPanel?.(
  * CMS cũ (chưa có tab Mẫu) → bỏ qua, không lỗi.
  */
 export const registerPattern = (pattern) => host().editor.registerPattern?.(pattern);
+/**
+ * Nguồn dữ liệu cho mục "Gắn dữ liệu" của trình soạn (đoạn văn, tiêu đề, ảnh, nút…):
+ *   registerBindingSource({ name: "shop/product", label: "%binding.product%", fields: [{ value: "price", label: "%binding.price%" }] })
+ * Website lấy giá trị bằng definePlugin({ bindingSources: { "shop/product": (args, ctx) => … } }) của theme-sdk.
+ * CMS cũ → bỏ qua, không lỗi.
+ */
+export const registerBindingSource = (source) => host().editor.registerBindingSource?.(source);
 export { defineBlock } from "@ecomcx/ecomweb-content";
 /** Thêm node/mark TipTap cho trình soạn (cấp thấp — khối thường dùng registerBlock). */
 export const registerEditorExtension = (pack) => host().editor.register(pack);

package/dist/types.d.ts

@@ -166,6 +166,43 @@ export interface AdminPage {
         path: string;
     }>;
 }
+/**
+ * Đường dẫn hiện tại của trang plugin (useAdminRoute, CMS ≥ 1.20.0). registerPage nhận mẫu "/orders/:id" (một đoạn)
+ * hoặc "/orders/*" (phần còn lại, params["*"]).
+ */
+export interface AdminRoute {
+    /** Đường dẫn trong admin, vd "/orders/12". */
+    path: string;
+    params: Record<string, string>;
+    /** Tham số sau "?" của URL. */
+    query: Record<string, string>;
+    /** Điều hướng trong admin (không tải lại trang). */
+    navigate(to: string, opts?: {
+        replace?: boolean;
+    }): void;
+}
+/** Props component của loại trường plugin (registerFieldType, CMS ≥ 1.20.0). */
+export interface FieldTypeProps {
+    field: {
+        key: string;
+        type: string;
+        label: string;
+        options?: string[];
+        help?: string;
+        default?: unknown;
+    };
+    value: any;
+    onChange(value: any): void;
+}
+/**
+ * Loại trường cho form tự sinh của admin (settings plugin — ISettingsRegistry / plugin.json "settings", widget):
+ * khai báo trường với Type = tên này ở backend, vd new FieldDefinition("brand", "shop/color-range", "Màu").
+ */
+export interface FieldTypeDefinition {
+    /** Tên dạng "slug/tên" để không trùng loại có sẵn của core. */
+    type: string;
+    component: ComponentType<FieldTypeProps>;
+}
 export interface DashboardWidget {
     id: string;
     title: string;
@@ -284,6 +321,27 @@ export interface PostRowAction {
 /** Danh sách khác (ngoài bài viết) cho plugin mở rộng: người dùng, bình luận, media. */
 export type AdminListName = "users" | "comments" | "media";
 /** Mẫu (pattern): đoạn nội dung dựng sẵn, chèn = chép khối vào bài. */
+/**
+ * Nguồn dữ liệu để gắn vào thuộc tính của khối (mục "Gắn dữ liệu" trong trình soạn). Tên trùng với nguồn plugin cung cấp
+ * cho website qua definePlugin({ bindingSources }) của theme-sdk — trình soạn chỉ hiện lựa chọn + xem trước, website lấy giá trị thật.
+ */
+export interface EditorBindingSource {
+    /** "slug/tên". */
+    name: string;
+    /** Nhận "%khoá%" (locales của plugin). */
+    label: string;
+    /** Trường chọn được (đặt vào args[argKey]); nhãn nhận "%khoá%". Không có → ô nhập tự do. */
+    fields?: Array<{
+        value: string;
+        label: string;
+    }>;
+    /** Tên tham số (mặc định "field"). */
+    argKey?: string;
+    /** Chỉ cho các thuộc tính này (vd ["src"]). */
+    attributes?: string[];
+    /** Giá trị xem trước trong trình soạn. */
+    preview?(args: Record<string, string | number | boolean>): string | undefined | Promise<string | undefined>;
+}
 export interface EditorPattern {
     /** "slug-plugin/tên". */
     name: string;
@@ -736,6 +794,14 @@ export interface CmsAdmin {
     getPostRowActions(postType?: string): Array<PostRowAction>;
     getMetaBoxes?(postType?: string): MetaBox[];
     usePluginUi?(): any;
+    /** CMS ≥ 1.20.0 */
+    useAdminRoute?(): AdminRoute;
+    /** CMS ≥ 1.20.0 */
+    navigate?(to: string, opts?: {
+        replace?: boolean;
+    }): void;
+    /** CMS ≥ 1.20.0 */
+    registerFieldType?(def: FieldTypeDefinition): void;
     /** Hook React lấy dữ liệu đơn giản: const { data, loading, error, reload } = useApi("/admin/...") */
     useApi<T = any>(path: string | null): {
         data: T | undefined;
@@ -775,6 +841,8 @@ export interface CmsAdmin {
         registerBlockPanel?(panel: BlockPanel): void;
         /** Mẫu — đoạn nội dung dựng sẵn trong tab "Mẫu" của trình chèn (CMS ≥ 1.12.0). */
         registerPattern?(pattern: EditorPattern): void;
+        /** Nguồn gắn dữ liệu cho khối (CMS có trình soạn v2 — @ecomcx/ecomweb-editor ≥ 1.19). */
+        registerBindingSource?(source: EditorBindingSource): void;
         tiptap: {
             Node: any;
             Mark: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecomcx/ecomweb-admin-sdk",
-  "version": "1.30.0",
+  "version": "1.31.0",
   "description": "SDK cho phần admin của plugin: đăng ký trang, meta box, widget dashboard và dùng bộ UI của admin.",
   "type": "module",
   "main": "./dist/index.js",