@ecomcx/ecomweb-theme-sdk 1.26.0 → 1.28.0

package/dist/api.d.ts

@@ -32,6 +32,37 @@ export declare const UNLOCK_HEADER = "X-CMS-Unlock";
 /** unlock: giá trị cookie cms-unlock — có thì không dùng cache (nội dung riêng của người đã nhập mật khẩu). */
 export declare const resolvePath: (path: string, query?: Record<string, string | string[] | undefined>, noStore?: boolean, unlock?: string) => Promise<ResolveResult>;
 export declare const getPreview: (token: string) => Promise<ResolveResult>;
+/** Một điều kiện lọc theo taxonomy: bài phải khớp (hoặc không khớp) các term này. */
+export interface TaxQueryClause {
+    taxonomy: string;
+    terms: string[];
+    /** Mặc định "IN". "NOT IN" = loại bài thuộc các term này. */
+    operator?: "IN" | "NOT IN";
+}
+/**
+ * Một điều kiện lọc theo trường tuỳ biến (post.meta). Giá trị so sánh phải đúng kiểu JSON (số là số).
+ *
+ * So bằng (`=`, `!=`, `IN`, `NOT IN`, `EXISTS`, `NOT EXISTS`) chạy trên chỉ mục GIN sẵn có — dùng được
+ * với mọi khoá meta.
+ *
+ * So khoảng (`>`, `>=`, `<`, `<=`, `BETWEEN`, `LIKE`) **chỉ dùng được với khoá đã khai báo
+ * `filterable`** (backend tạo chỉ mục B-tree cho khoá đó lúc khởi động); khoá chưa khai báo trả 422.
+ * Với khoá kiểu số, giá trị phải là số JSON (chuỗi số cũng được, core tự chuyển) — nếu không phép so
+ * sẽ so chuỗi ("100" < "20").
+ */
+export interface MetaQueryClause {
+    key: string;
+    compare: "=" | "!=" | "IN" | "NOT IN" | "EXISTS" | "NOT EXISTS" | ">" | ">=" | "<" | "<=" | "BETWEEN" | "LIKE";
+    /** Bỏ trống với EXISTS / NOT EXISTS. Với LIKE: mẫu có `%` / `_`. */
+    value?: string | number | boolean | (string | number | boolean)[];
+    /** Cận trên của BETWEEN (bắt buộc với BETWEEN). */
+    value2?: string | number;
+}
+export interface MetaQuery {
+    /** Mặc định "AND". */
+    relation?: "AND" | "OR";
+    clauses: MetaQueryClause[];
+}
 export interface PostQuery {
     /** Mặc định: ngôn ngữ của request hiện tại. */
     locale?: string;
@@ -40,6 +71,14 @@ export interface PostQuery {
     term?: string;
     authorId?: number;
     search?: string;
+    /** Lọc nhiều post type cùng lúc (bài viết + trang + job...). Gộp với `type`. */
+    types?: string[];
+    /** Lọc nhiều taxonomy cùng lúc — thay cho taxonomy/term khi cần AND/OR nhiều điều kiện. */
+    taxQuery?: TaxQueryClause[];
+    /** Lọc theo trường tuỳ biến; chạy trong cơ sở dữ liệu trên chỉ mục GIN của posts.meta. */
+    metaQuery?: MetaQuery;
+    /** Chỉ lấy bài thuộc ngữ cảnh này (plugin tự lọc thêm qua filter posts.query). */
+    context?: string;
     include?: number[];
     exclude?: number[];
     parentId?: number;
@@ -51,6 +90,11 @@ export interface PostQuery {
     perPage?: number;
     orderBy?: "date" | "title" | "modified" | "menu_order" | "comment_count";
     order?: "asc" | "desc";
+    /**
+     * Sắp xếp theo một khoá meta đã khai báo `filterable` (vd `"gia"`, `"job_deadline"`) — thay cho `orderBy`.
+     * Khoá chưa khai báo trả 422 (không có chỉ mục thì sắp xếp phải quét toàn bảng).
+     */
+    orderByMeta?: string;
 }
 export declare const getPosts: ({ withContent, ...q }?: PostQuery) => Promise<{
     items: Post[];

package/dist/api.js

@@ -116,7 +116,19 @@ export const UNLOCK_HEADER = "X-CMS-Unlock";
 /** unlock: giá trị cookie cms-unlock — có thì không dùng cache (nội dung riêng của người đã nhập mật khẩu). */
 export const resolvePath = (path, query = {}, noStore = false, unlock) => cmsFetch("/resolve", { tags: ["posts"], noStore: noStore || !!unlock, query: clean({ ...query, path }), headers: unlock ? { [UNLOCK_HEADER]: unlock } : undefined });
 export const getPreview = (token) => cmsFetch("/preview", { noStore: true, query: { token } });
-export const getPosts = async ({ withContent, ...q } = {}) => cmsFetch("/posts", { tags: ["posts"], query: clean({ ...q, content: withContent ?? false, locale: q.locale ?? (await getRequestLocale()) }) });
+export const getPosts = async ({ withContent, ...q } = {}) => {
+    // Bóc tách TRONG thân hàm, không phải trong tham số: chữ ký đã công bố của getPosts nằm trong baseline
+    // hợp đồng (api/theme-sdk.txt) nên thêm tên vào tham số là đổi một dòng đã ký (CI coi là phá hợp đồng).
+    const { taxQuery, metaQuery, ...rest } = q;
+    return cmsFetch("/posts", { tags: ["posts"], query: clean({
+            ...rest,
+            // Bộ lọc phức tạp đi dạng JSON — core phân tích và áp thẳng vào câu SQL (không lọc bằng bộ nhớ).
+            taxQuery: taxQuery?.length ? JSON.stringify(taxQuery) : undefined,
+            metaQuery: metaQuery?.clauses?.length ? JSON.stringify(metaQuery) : undefined,
+            content: withContent ?? false,
+            locale: rest.locale ?? (await getRequestLocale()),
+        }) });
+};
 const loc = async (locale) => locale ?? (await getRequestLocale());
 export const getPost = async (type, slug, locale) => cmsFetch(`/posts/${type}/${encodeURIComponent(slug)}`, { tags: ["posts"], query: clean({ locale: await loc(locale) }) }).catch(() => null);
 export const getTerms = async (taxonomy, hideEmpty = true, locale) => cmsFetch(`/terms/${taxonomy}`, { tags: ["terms"], query: clean({ hideEmpty, locale: await loc(locale) }) });

package/dist/components.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { getArchives, getComments, getMenu, getMenuById, getPosts, getSite, getTerms, getWidgets } from "./api.js";
 import { findWidget, getSlotItems } from "./runtime.js";
-import { cx, formatDate, pageLink } from "./utils.js";
+import { cx, formatDate, pageLink, pageLinkWithQuery } from "./utils.js";
 import { Img } from "./image.js";
 import { CommentForm, CommentList, CommentsMore, ExtensionBoundary, LanguageSwitcherClient, Link, SearchFormClient } from "./client.js";
 import { getT } from "./i18n.js";
@@ -102,7 +102,11 @@ export async function Pagination({ data, prevLabel, nextLabel }) {
         else if (pages[pages.length - 1] !== "…")
             pages.push("…");
     }
-    const link = (p) => pageLink(data.basePath, p, data.kind === "search" ? data.search : null);
+    // Danh sách có bộ lọc (?phong-ban=…, ?muc-luong=…) → giữ nguyên bộ lọc khi chuyển trang
+    const hasFilters = Object.keys(data.query ?? {}).some((k) => k !== "s" && k !== "page");
+    const link = (p) => hasFilters
+        ? pageLinkWithQuery(data.basePath, p, data.query)
+        : pageLink(data.basePath, p, data.kind === "search" ? data.search : null);
     return (_jsxs("nav", { className: "pagination", "aria-label": t("pagination.label"), children: [data.page > 1 && _jsx(Link, { className: "prev", href: link(data.page - 1), children: prevLabel }), pages.map((p, i) => p === "…" ? _jsx("span", { className: "dots", children: "\u2026" }, `e${i}`)
                 : p === data.page ? _jsx("span", { className: "current", "aria-current": "page", children: p }, p)
                     : _jsx(Link, { href: link(p), children: p }, p)), data.page < data.totalPages && _jsx(Link, { className: "next", href: link(data.page + 1), children: nextLabel })] }));

package/dist/content.js

@@ -19,7 +19,7 @@ export async function PostContent({ post, content, className }) {
     }
     if (!doc?.blocks?.length)
         return null;
-    const rendered = await renderContent(doc, await contentContext(site, post), (blocks) => applyFilters("post.blocks", blocks, { site, post }, site));
+    const rendered = await renderContent(doc, { ...(await contentContext(site, post)), source: post ? `post:${post.id}` : undefined }, (blocks) => applyFilters("post.blocks", blocks, { site, post }, site));
     return _jsx("div", { className: cx(className ?? "entry-content", "ecx-content"), children: rendered });
 }
 /**
@@ -31,7 +31,7 @@ export async function EditableRegion({ name, data, className, children }) {
     const doc = (await getTemplates().catch(() => null))?.parts[name];
     const site = await getSite();
     const own = doc?.blocks?.length
-        ? _jsx("div", { className: cx(`ecx-region ecx-region-${name}`, "ecx-content", className), children: await renderContent(doc, await contentContext(site, data?.post, data)) })
+        ? _jsx("div", { className: cx(`ecx-region ecx-region-${name}`, "ecx-content", className), children: await renderContent(doc, { ...(await contentContext(site, data?.post, data)), source: `part:${name}` }) })
         : _jsx(_Fragment, { children: children });
     return _jsx(_Fragment, { children: await regionOverride(name, own, site, data) });
 }
@@ -45,9 +45,11 @@ async function regionOverride(name, fallback, site, data) {
 /** Ngữ cảnh vẽ nội dung dùng chung cho bài viết và template khối. */
 export async function contentContext(site, post, data) {
     const t = await getT();
+    // Bản nháp (xem trực tiếp / Trình dựng) không vào cache công khai → được gắn vị trí khối cho khung soạn
+    const markBlocks = await import("next/headers").then(async ({ draftMode }) => (await draftMode()).isEnabled).catch(() => false);
     const blocks = (await getActiveExtensions(site)).flatMap((d) => d.blockTypes ?? []);
     return {
-        site, post, data, blocks,
+        site, post, data, blocks, markBlocks,
         resolve: { shortcode: (name) => findShortcode(name, site), block: (type) => findBlock(type, site) },
         labels: { download: t("file.download"), toc: t("toc.title") },
         boundary: (name, key, el) => _jsx(ExtensionBoundary, { name: name, children: el }, key),

package/dist/dynamic.js

@@ -112,14 +112,14 @@ export async function renderDynamic(node, key, ctx, children) {
             const doc = await ctx.pattern(a.ref);
             if (!doc)
                 return null;
-            return _jsx(Fragment, { children: await renderContent(doc, { ...ctx, partDepth: (ctx.partDepth ?? 0) + 1 }) }, key);
+            return _jsx(Fragment, { children: await renderContent(doc, { ...ctx, partDepth: (ctx.partDepth ?? 0) + 1, source: `pattern:${a.ref}` }) }, key);
         }
         case "templatePart": {
             if (!a.slug || !ctx.parts || (ctx.partDepth ?? 0) >= 4)
                 return null;
             const doc = await ctx.parts(String(a.slug));
             const Tag = (["header", "footer", "aside", "section"].includes(a.tagName) ? a.tagName : "div");
-            const part = doc ? _jsx(Tag, { className: cx("ecx-template-part", `ecx-template-part-${a.slug}`), children: await renderContent(doc, { ...ctx, partDepth: (ctx.partDepth ?? 0) + 1 }) }) : null;
+            const part = doc ? _jsx(Tag, { className: cx("ecx-template-part", `ecx-template-part-${a.slug}`), children: await renderContent(doc, { ...ctx, partDepth: (ctx.partDepth ?? 0) + 1, source: `part:${a.slug}` }) }) : null;
             const el = ctx.region ? await ctx.region(String(a.slug), part) : part;
             return el == null ? null : _jsx(Fragment, { children: el }, key);
         }

package/dist/rich.d.ts

@@ -48,6 +48,14 @@ export interface RenderContext {
         id: string;
         text: string;
     }>;
+    /**
+     * Đang xem bản nháp (Trình dựng / xem trực tiếp): gắn data-ecx-doc + data-ecx-path cho từng khối để khung soạn ở admin
+     * biết người dùng bấm vào khối nào. `source` = tài liệu đang vẽ ("template:single", "part:header", "post:12", "pattern:3").
+     */
+    markBlocks?: boolean;
+    source?: string;
+    /** Khoá của khối richtext đang vẽ — đường dẫn khối = phần khoá sau nó (do renderBlock đặt). */
+    pathRoot?: string;
 }
 type Node = Omit<RichNode, "attrs" | "content" | "marks"> & {
     attrs?: Record<string, any>;

package/dist/rich.js

@@ -152,7 +152,21 @@ function decorate(el, a, key, ctx) {
 async function renderNode(node, key, ctx) {
     const el = await renderNodeInner(node, key, ctx);
     const a = node.attrs;
-    return a && (a.style || a.blockStyle || a.className || a.anchor) ? decorate(el, a, key, ctx) : el;
+    const out = a && (a.style || a.blockStyle || a.className || a.anchor) ? decorate(el, a, key, ctx) : el;
+    return ctx.markBlocks && ctx.source && ctx.pathRoot != null && key.startsWith(ctx.pathRoot + "-") && !UNMARKED.has(node.type)
+        ? markBlock(out, ctx.source, key.slice(ctx.pathRoot.length + 1), key)
+        : out;
+}
+/** Nút không chọn riêng được trong khung soạn (hoặc bọc thêm thẻ sẽ sai cấu trúc HTML: li trong ul, ô trong bảng). */
+const UNMARKED = new Set(["text", "hardBreak", "listItem", "taskItem", "tableRow", "tableCell", "tableHeader"]);
+/** Gắn vị trí khối: thẻ HTML thì thêm thuộc tính, component thì bọc thẻ display:contents (không đổi bố cục). */
+function markBlock(el, source, path, key) {
+    if (el == null || el === false)
+        return el;
+    const attrs = { "data-ecx-doc": source, "data-ecx-path": path };
+    if (isValidElement(el) && typeof el.type === "string")
+        return cloneElement(el, attrs);
+    return _jsx("div", { style: { display: "contents" }, ...attrs, children: el }, key);
 }
 async function renderNodeInner(node, key, ctx) {
     const children = async () => Promise.all((node.content ?? []).map((c, i) => renderNode(c, `${key}-${i}`, ctx)));
@@ -359,7 +373,7 @@ async function renderHtml(html, key, ctx) {
 }
 async function renderBlock(block, key, ctx) {
     switch (block.type) {
-        case "richtext": return block.data ? await renderNode(block.data, key, ctx) : null;
+        case "richtext": return block.data ? await renderNode(block.data, key, ctx.markBlocks ? { ...ctx, pathRoot: key } : ctx) : null;
         case "html": return await renderHtml(String(block.data?.html ?? ""), key, ctx);
         default: {
             const Comp = await ctx.resolve.block(block.type);

package/dist/template-blocks.js

@@ -7,5 +7,5 @@ export default async function BlockTemplate({ data, site, template }) {
     const doc = (await getTemplates()).templates[template];
     if (!doc)
         return null;
-    return _jsx("div", { className: `ecx-template ecx-template-${template} ecx-content`, children: await renderContent(doc, await contentContext(site, data.post, data)) });
+    return _jsx("div", { className: `ecx-template ecx-template-${template} ecx-content`, children: await renderContent(doc, { ...(await contentContext(site, data.post, data)), source: `template:${template}` }) });
 }

package/dist/types.d.ts

@@ -214,6 +214,12 @@ export interface ResolveResult {
     } | null;
     /** Không cho máy tìm kiếm index. */
     noIndex?: boolean;
+    /**
+     * Tham số truy vấn của URL (searchParams) của request hiện tại — server render đọc trực tiếp để
+     * lọc danh sách ngay trên máy chủ. Dùng cho bộ lọc người đọc chọn: `getPosts({ metaQuery: … })`
+     * rồi truyền `data.query` vào để giữ bộ lọc khi chuyển trang (xem `pageLinkWithQuery`).
+     */
+    query?: Record<string, string>;
 }
 /** Props mà mọi template của theme nhận được. */
 export interface TemplateProps {
@@ -277,6 +283,8 @@ export interface ThemeManifest {
         template?: string;
         locked?: boolean;
     }>;
+    /** Nguồn ngoài website theme cần nạp (CSP): { "style-src": ["https://fonts.googleapis.com"], "font-src": ["https://fonts.gstatic.com"] }. */
+    csp?: Partial<Record<"script-src" | "style-src" | "img-src" | "font-src" | "connect-src" | "frame-src" | "media-src" | "worker-src" | "form-action", string[]>>;
     [key: string]: unknown;
 }
 type Loader<T> = () => Promise<{

package/dist/utils.d.ts

@@ -5,4 +5,11 @@ export declare function formatDate(value: string | null | undefined, site?: Pick
 }): string;
 export declare function setting<T = string>(settings: Record<string, unknown>, key: string, fallback: T): T;
 export declare function pageLink(basePath: string, page: number, search?: string | null): string;
+/**
+ * Link của một trang trong danh sách CÓ bộ lọc: giữ nguyên mọi tham số truy vấn hiện có (phòng ban,
+ * mức lương, từ khoá…) và chỉ đổi số trang. Truyền `data.query` của trang vào.
+ *
+ *   <Link href={pageLinkWithQuery(data.basePath, 2, data.query)}>2</Link>
+ */
+export declare function pageLinkWithQuery(basePath: string, page: number, query?: Record<string, string> | null): string;
 export declare function cx(...classes: Array<string | false | null | undefined>): string;

package/dist/utils.js

@@ -24,6 +24,25 @@ export function pageLink(basePath, page, search) {
     const path = page <= 1 ? base || "/" : `${base}/page/${page}`;
     return search ? `${path}${path.includes("?") ? "&" : "?"}s=${encodeURIComponent(search)}` : path;
 }
+/**
+ * Link của một trang trong danh sách CÓ bộ lọc: giữ nguyên mọi tham số truy vấn hiện có (phòng ban,
+ * mức lương, từ khoá…) và chỉ đổi số trang. Truyền `data.query` của trang vào.
+ *
+ *   <Link href={pageLinkWithQuery(data.basePath, 2, data.query)}>2</Link>
+ */
+export function pageLinkWithQuery(basePath, page, query) {
+    const base = basePath === "/" ? "" : basePath.replace(/\/$/, "");
+    const path = page <= 1 ? base || "/" : `${base}/page/${page}`;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query ?? {})) {
+        // "page" do đường dẫn quyết định; tham số rỗng không cần giữ
+        if (k === "page" || v === "" || v === undefined || v === null)
+            continue;
+        params.set(k, v);
+    }
+    const qs = params.toString();
+    return qs ? `${path}${path.includes("?") ? "&" : "?"}${qs}` : path;
+}
 export function cx(...classes) {
     return classes.filter(Boolean).join(" ");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecomcx/ecomweb-theme-sdk",
-  "version": "1.26.0",
+  "version": "1.28.0",
   "description": "SDK để viết theme và phần frontend của plugin cho Ecomweb",
   "type": "module",
   "main": "./dist/index.js",