@ecomcx/ecomweb-admin-sdk 1.29.0 → 1.31.0

package/dist/index.d.ts

@@ -9,6 +9,13 @@ export declare const registerDashboardWidget: (w: DashboardWidget) => void;
 export declare const registerPostListColumn: (c: import("./types.js").PostListColumn) => void;
 /** Thêm hộp vào form sửa chuyên mục/thẻ (dữ liệu lưu trong term.meta). */
 export declare const registerTermMetaBox: (b: import("./types.js").TermMetaBox) => void;
+/**
+ * Thêm hộp vào trang sửa đối tượng của plugin khác (đơn hàng, mã giảm giá, dòng bảng [PluginTable] có cột [ObjectMeta]…) —
+ * giá trị đặt qua setMeta được plugin chủ lưu cùng đối tượng. CMS < 1.18.0: bỏ qua.
+ */
+export declare const registerObjectMetaBox: (b: import("./types.js").ObjectMetaBox) => void | undefined;
+/** Hộp đã đăng ký cho một đối tượng (bỏ trống = tất cả). */
+export declare const getObjectMetaBoxes: (object?: string) => import("./types.js").ObjectMetaBox[];
 /** Lấy các MetaBox đã đăng ký trong hệ thống (tùy chọn lọc theo postType). */
 export declare const getMetaBoxes: (postType?: string) => MetaBox[];
 /** Hook lấy toàn bộ state plugin UI trong host. */
@@ -19,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):
@@ -38,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;
@@ -241,6 +268,8 @@ export declare const Tabs: NonNullable<import("react").ComponentType<{
     }>;
 }>>;
 export declare const MetaBoxes: NonNullable<import("react").ComponentType<import("./types.js").MetaBoxesProps>>;
+/** Plugin chủ vẽ chỗ cho hộp của plugin khác trong trang sửa đối tượng của mình (CMS < 1.18.0: không vẽ gì). */
+export declare const ObjectMetaBoxes: NonNullable<import("react").ComponentType<import("./types.js").ObjectMetaBoxesProps> | undefined>;
 export declare const Slot: NonNullable<import("react").ComponentType<{
     name: string;
     props?: any;

package/dist/index.js

@@ -9,11 +9,40 @@ export const registerDashboardWidget = (w) => host().registerDashboardWidget(w);
 export const registerPostListColumn = (c) => host().registerPostListColumn(c);
 /** Thêm hộp vào form sửa chuyên mục/thẻ (dữ liệu lưu trong term.meta). */
 export const registerTermMetaBox = (b) => host().registerTermMetaBox(b);
+/**
+ * Thêm hộp vào trang sửa đối tượng của plugin khác (đơn hàng, mã giảm giá, dòng bảng [PluginTable] có cột [ObjectMeta]…) —
+ * giá trị đặt qua setMeta được plugin chủ lưu cùng đối tượng. CMS < 1.18.0: bỏ qua.
+ */
+export const registerObjectMetaBox = (b) => host().registerObjectMetaBox?.(b);
+/** Hộp đã đăng ký cho một đối tượng (bỏ trống = tất cả). */
+export const getObjectMetaBoxes = (object) => host().getObjectMetaBoxes?.(object) ?? [];
 /** Lấy các MetaBox đã đăng ký trong hệ thống (tùy chọn lọc theo postType). */
 export const getMetaBoxes = (postType) => (host().getMetaBoxes ? host().getMetaBoxes(postType) : []);
 /** 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):
@@ -38,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);
@@ -137,6 +173,8 @@ export const IconButton = ui("IconButton");
 export const Section = ui("Section");
 export const Tabs = ui("Tabs");
 export const MetaBoxes = ui("MetaBoxes");
+/** Plugin chủ vẽ chỗ cho hộp của plugin khác trong trang sửa đối tượng của mình (CMS < 1.18.0: không vẽ gì). */
+export const ObjectMetaBoxes = ui("ObjectMetaBoxes", () => null);
 export const Slot = ui("Slot");
 export const Fill = ui("Fill");
 // ----- UI kit v2 (xem trang /ui-kit trong admin) -----

package/dist/types.d.ts

@@ -91,6 +91,40 @@ export interface TermMetaBox {
     taxonomies?: string[];
     component: ComponentType<TermMetaBoxProps>;
 }
+/**
+ * Đối tượng của plugin lưu trong bảng riêng (vd "ecomcx-ecommerce/order") — plugin chủ khai báo bằng ctx.Objects.Register ở backend
+ * (hoặc bảng [PluginTable] có cột [ObjectMeta]); danh sách nằm trong bootstrap của admin (`objectTypes`).
+ */
+export interface ObjectMetaBoxProps {
+    /** Tên đối tượng "{slug}/{name}". */
+    object: string;
+    /** Mã đối tượng; bỏ trống khi đang tạo mới. */
+    id?: string | number;
+    /** Dữ liệu đang sửa của đối tượng (chỉ để đọc, vd tổng tiền đơn hàng) — tuỳ plugin chủ. */
+    record?: Record<string, any>;
+    /** Meta hiện tại (đã gồm thay đổi chưa lưu). */
+    meta: Record<string, any>;
+    /** Đặt meta — plugin chủ lưu cùng đối tượng khi bấm Lưu. */
+    setMeta(key: string, value: any): void;
+}
+/** Hộp thêm vào trang sửa đối tượng của plugin khác (CMS ≥ 1.18.0), vd trường tuỳ biến cho đơn hàng. */
+export interface ObjectMetaBox {
+    id: string;
+    title: string;
+    /** Tên đối tượng "{slug}/{name}"; bỏ trống = mọi đối tượng. */
+    objects?: string[];
+    context?: "main" | "side";
+    priority?: number;
+    /** Trả false để ẩn hộp với đối tượng này (vd không có nhóm trường nào áp dụng). */
+    visible?(props: ObjectMetaBoxProps): boolean;
+    component: ComponentType<ObjectMetaBoxProps>;
+}
+/** Chỗ vẽ hộp của plugin khác trong trang sửa đối tượng của mình (plugin chủ dùng). */
+export interface ObjectMetaBoxesProps extends ObjectMetaBoxProps {
+    context?: "main" | "side" | "all";
+    excludeIds?: string[];
+    className?: string;
+}
 export interface MetaBox {
     id: string;
     title: string;
@@ -132,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;
@@ -250,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;
@@ -520,6 +612,8 @@ export interface UiKit {
         }>;
     }>;
     MetaBoxes: ComponentType<MetaBoxesProps>;
+    /** Hộp của plugin khác cho đối tượng trong bảng riêng (CMS ≥ 1.18.0). */
+    ObjectMetaBoxes?: ComponentType<ObjectMetaBoxesProps>;
     Slot: ComponentType<{
         name: string;
         props?: any;
@@ -686,6 +780,8 @@ export interface CmsAdmin {
     registerDashboardWidget(widget: DashboardWidget): void;
     registerPostListColumn(column: PostListColumn): void;
     registerTermMetaBox(box: TermMetaBox): void;
+    registerObjectMetaBox?(box: ObjectMetaBox): void;
+    getObjectMetaBoxes?(object?: string): ObjectMetaBox[];
     registerSlot(slot: AdminSlotItem): void;
     getSlots(slot: string, postType?: string): Array<AdminSlotItem>;
     registerPostRowAction(action: PostRowAction): void;
@@ -698,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;
@@ -737,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.29.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",