@ecomcx/ecomweb-theme-sdk 1.27.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/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 {

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.27.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",