@ecomcx/ecomweb-theme-sdk 1.27.0 → 1.29.0

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { PostContentDoc, CommentPage, Menu, Post, ResolveResult, Site, Term, WidgetInstance } from "./types.js";
+import type { Author, PostContentDoc, CommentPage, Media, Menu, Post, ResolveResult, Site, Term, WidgetInstance } from "./types.js";
 /**
  * Client gọi Public API của CMS (dùng next-fetch-kit: chạy được cả SSR lẫn CSR,
  * tự gộp request trùng trong cùng một lần render, timeout + retry khi lỗi mạng).
@@ -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;
@@ -47,10 +86,26 @@ export interface PostQuery {
     sticky?: boolean;
     /** Kèm nội dung đầy đủ (post.content). Mặc định không — danh sách chỉ cần tiêu đề, sapo, ảnh, giúp trang nhẹ và nhanh. */
     withContent?: boolean;
+    /**
+     * `relevance` = theo độ khớp với `search` (trang tìm kiếm dùng mặc định); `rand` = ngẫu nhiên (kết quả vẫn được
+     * cache, đổi khi cache hết hạn hoặc nội dung đổi).
+     */
     page?: number;
     perPage?: number;
-    orderBy?: "date" | "title" | "modified" | "menu_order" | "comment_count";
+    orderBy?: "date" | "title" | "modified" | "menu_order" | "comment_count" | "id" | "slug" | "rand" | "relevance";
     order?: "asc" | "desc";
+    /** Ngày đăng từ (gồm cả mốc), ISO-8601 hoặc Date — vd sự kiện / tin tức từ đầu năm học. */
+    after?: string | Date;
+    /** Ngày đăng trước (không gồm mốc). */
+    before?: string | Date;
+    /** Năm đăng (UTC); kèm `month` 1–12 để lấy một tháng — trang lưu trữ. */
+    year?: number;
+    month?: number;
+    /**
+     * 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[];
@@ -58,6 +113,95 @@ export declare const getPosts: ({ withContent, ...q }?: PostQuery) => Promise<{
     page: number;
     totalPages: number;
 }>;
+/** Một trang của danh sách công khai (term, tác giả, media). */
+export interface ListPage<T> {
+    items: T[];
+    total: number;
+    page: number;
+    totalPages: number;
+}
+/** Một giá trị facet: slug term (facet phân loại) hoặc giá trị meta, kèm số bài. */
+export interface FacetValue {
+    value: string;
+    count: number;
+    termId?: number | null;
+    name?: string | null;
+    parentId?: number | null;
+}
+export interface FacetResult {
+    total: number;
+    facets: Record<string, FacetValue[]>;
+}
+/**
+ * Đếm số bài theo từng giá trị (bộ lọc có số đếm: "Khoa CNTT (12)") trên đúng tập bài mà {@link getPosts} trả về với
+ * cùng điều kiện. `facets`: tên phân loại công khai ("category") và/hoặc `"meta:khoá"` (khoá khai báo `filterable`).
+ * Tối đa 5 facet × 100 giá trị, đếm trong PostgreSQL.
+ * @example const { facets } = await getFacets(["khoa", "meta:hoc-ky"], { type: "khoa-hoc", taxQuery })
+ */
+export declare function getFacets(facets: string[], query?: Omit<PostQuery, "page" | "perPage" | "withContent" | "orderBy" | "order" | "orderByMeta">): Promise<FacetResult>;
+export interface TermQuery {
+    taxonomy: string;
+    locale?: string;
+    /** Tìm theo tên, không phân biệt dấu. */
+    search?: string;
+    /** Chỉ term con trực tiếp của term này; 0 = chỉ term gốc. */
+    parent?: number;
+    include?: number[];
+    exclude?: number[];
+    hideEmpty?: boolean;
+    /** Chỉ term có meta khoá này (và đúng giá trị nếu có metaValue). */
+    metaKey?: string;
+    metaValue?: string;
+    orderBy?: "name" | "slug" | "count" | "id";
+    order?: "asc" | "desc";
+    /** perPage 1–500 (mặc định 100). */
+    page?: number;
+    perPage?: number;
+    /** Tham số thêm cho plugin (filter terms.query đọc trong Query). */
+    params?: Record<string, string>;
+}
+/** Danh sách term có phân trang, lọc theo cha / từ khoá / meta, sắp xếp — bản đầy đủ của {@link getTerms}. */
+export declare const queryTerms: ({ params, ...q }: TermQuery) => Promise<ListPage<Term>>;
+export interface AuthorQuery {
+    locale?: string;
+    /** Tìm theo tên hiển thị, không phân biệt dấu. */
+    search?: string;
+    include?: number[];
+    exclude?: number[];
+    /** Lọc theo meta công khai (khoá khai báo `UserMeta` Public), vd metaKey "khoa". Khoá không công khai → 422. */
+    metaKey?: string;
+    metaValue?: string;
+    orderBy?: "name" | "post_count" | "id";
+    order?: "asc" | "desc";
+    /** perPage 1–100 (mặc định 20). */
+    page?: number;
+    perPage?: number;
+    /** Tham số thêm cho plugin (filter authors.query), vd plugin danh bạ thêm vai trò "giang-vien". */
+    params?: Record<string, string>;
+}
+/**
+ * Danh sách tác giả công khai (trang "Đội ngũ", danh bạ): mặc định thành viên có bài đã đăng; plugin mở rộng qua
+ * filter authors.query. Chỉ có tên, slug, ảnh, tiểu sử, meta công khai — không bao giờ có email.
+ */
+export declare const getAuthors: ({ params, ...q }?: AuthorQuery) => Promise<ListPage<Author>>;
+export interface MediaQuery {
+    /** Tìm theo tiêu đề, alt, chú thích, tên file — không phân biệt dấu. */
+    search?: string;
+    /** Tiền tố kiểu file: "image/", "video/", "application/pdf". */
+    mime?: string;
+    folder?: number;
+    include?: number[];
+    exclude?: number[];
+    orderBy?: "date" | "title" | "id" | "size";
+    order?: "asc" | "desc";
+    /** perPage 1–100 (mặc định 20). */
+    page?: number;
+    perPage?: number;
+    /** Tham số thêm cho plugin (filter media.query). */
+    params?: Record<string, string>;
+}
+/** Danh sách media (thư viện ảnh, tài liệu tải về) — plugin giới hạn / mở rộng qua filter media.query. */
+export declare const getMedia: ({ params, ...q }?: MediaQuery) => Promise<ListPage<Media>>;
 export declare const getPost: (type: string, slug: string, locale?: string) => Promise<Post | null>;
 export declare const getTerms: (taxonomy: string, hideEmpty?: boolean, locale?: string) => Promise<Term[]>;
 /** Cookie giữ token bản nháp của Trình dựng (website đang ở chế độ xem trước). */
@@ -73,8 +217,13 @@ export declare const getPattern: (id: number) => Promise<PostContentDoc | null>;
 export declare const getMenu: (location: string, locale?: string) => Promise<Menu | null>;
 export declare const getMenuById: (id: number) => Promise<Menu | null>;
 export declare const getWidgets: (area: string, locale?: string) => Promise<WidgetInstance[]>;
-/** Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận). */
-export declare const getComments: (postId: number, page?: number) => Promise<CommentPage>;
+/**
+ * Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận).
+ * Bài có mật khẩu (core >= 1.15): CMS chỉ trả bình luận khi có token mở khoá — unlock = giá trị cookie cms-unlock (không cache).
+ */
+export declare const getComments: (postId: number, page?: number, unlock?: string) => Promise<CommentPage>;
+/** Cookie mở khoá bài có mật khẩu của request hiện tại (server component); ngoài request → undefined. */
+export declare function requestUnlock(): Promise<string | undefined>;
 export declare const getArchives: (locale?: string) => Promise<{
     year: number;
     month: number;

package/dist/api.js

@@ -116,8 +116,50 @@ 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({
+            ...postQueryParams(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());
+/** Tham số đơn giản của PostQuery → query string (Date → ISO). */
+function postQueryParams(q) {
+    const iso = (d) => (d instanceof Date ? d.toISOString() : d);
+    return { ...q, after: iso(q.after), before: iso(q.before) };
+}
+/**
+ * Đếm số bài theo từng giá trị (bộ lọc có số đếm: "Khoa CNTT (12)") trên đúng tập bài mà {@link getPosts} trả về với
+ * cùng điều kiện. `facets`: tên phân loại công khai ("category") và/hoặc `"meta:khoá"` (khoá khai báo `filterable`).
+ * Tối đa 5 facet × 100 giá trị, đếm trong PostgreSQL.
+ * @example const { facets } = await getFacets(["khoa", "meta:hoc-ky"], { type: "khoa-hoc", taxQuery })
+ */
+export async function getFacets(facets, query = {}) {
+    const { taxQuery, metaQuery, ...rest } = query;
+    return cmsFetch("/posts/facets", { tags: ["posts"], query: clean({
+            ...postQueryParams(rest),
+            facets: facets.join(","),
+            taxQuery: taxQuery?.length ? JSON.stringify(taxQuery) : undefined,
+            metaQuery: metaQuery?.clauses?.length ? JSON.stringify(metaQuery) : undefined,
+            locale: rest.locale ?? (await getRequestLocale()),
+        }) });
+}
+/** Danh sách term có phân trang, lọc theo cha / từ khoá / meta, sắp xếp — bản đầy đủ của {@link getTerms}. */
+export const queryTerms = async ({ params, ...q }) => cmsFetch("/terms", { tags: ["terms"], query: clean({ ...params, ...q, locale: await loc(q.locale) }) });
+/**
+ * Danh sách tác giả công khai (trang "Đội ngũ", danh bạ): mặc định thành viên có bài đã đăng; plugin mở rộng qua
+ * filter authors.query. Chỉ có tên, slug, ảnh, tiểu sử, meta công khai — không bao giờ có email.
+ */
+export const getAuthors = async ({ params, ...q } = {}) => cmsFetch("/authors", { tags: ["authors"], query: clean({ ...params, ...q, locale: await loc(q.locale) }) });
+/** Danh sách media (thư viện ảnh, tài liệu tải về) — plugin giới hạn / mở rộng qua filter media.query. */
+export const getMedia = async ({ params, ...q } = {}) => cmsFetch("/media", { tags: ["media"], query: clean({ ...params, ...q }) });
 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) }) });
 /** Cookie giữ token bản nháp của Trình dựng (website đang ở chế độ xem trước). */
@@ -143,7 +185,22 @@ export const getPattern = (id) => cmsFetch(`/patterns/${id}`, { tags: ["patterns
 export const getMenu = async (location, locale) => cmsFetch(`/menus/${location}`, { tags: ["menus"], query: clean({ locale: await loc(locale) }) });
 export const getMenuById = (id) => cmsFetch(`/menus/id/${id}`, { tags: ["menus"] });
 export const getWidgets = async (area, locale) => cmsFetch(`/widgets/${area}`, { tags: ["widgets"], query: clean({ locale: await loc(locale) }) });
-/** Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận). */
-export const getComments = (postId, page = 1) => cmsFetch(`/comments/${postId}`, { tags: [`comments:${postId}`], query: page > 1 ? { page } : undefined });
+/**
+ * Bình luận đã duyệt theo trang (số mỗi trang, thứ tự: Cài đặt › Thảo luận).
+ * Bài có mật khẩu (core >= 1.15): CMS chỉ trả bình luận khi có token mở khoá — unlock = giá trị cookie cms-unlock (không cache).
+ */
+export const getComments = (postId, page = 1, unlock) => cmsFetch(`/comments/${postId}`, {
+    tags: [`comments:${postId}`], noStore: !!unlock, query: page > 1 ? { page } : undefined, headers: unlock ? { [UNLOCK_HEADER]: unlock } : undefined,
+});
+/** Cookie mở khoá bài có mật khẩu của request hiện tại (server component); ngoài request → undefined. */
+export async function requestUnlock() {
+    try {
+        const { cookies } = await import("next/headers");
+        return (await cookies()).get(UNLOCK_COOKIE)?.value;
+    }
+    catch {
+        return undefined;
+    }
+}
 export const getArchives = async (locale) => cmsFetch("/archives", { tags: ["posts"], query: clean({ locale: await loc(locale) }) });
 export const getLanguages = () => cmsFetch("/languages", { tags: ["site"] });

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 { getArchives, getComments, getMenu, getMenuById, getPosts, getSite, getTerms, getWidgets, requestUnlock } 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 })] }));
@@ -130,7 +134,8 @@ export async function Comments({ post, title }) {
         return null;
     if (post.passwordProtected && !post.content)
         return null; // bài có mật khẩu: ẩn bình luận tới khi mở khoá
-    const [site, page, t] = await Promise.all([getSite(), getComments(post.id), getT()]);
+    const unlock = post.passwordProtected ? await requestUnlock() : undefined;
+    const [site, page, t] = await Promise.all([getSite(), getComments(post.id, 1, unlock), getT()]);
     const comments = page?.items ?? [];
     const dateSite = { dateFormat: site.dateFormat, timezone: site.timezone, locale: site.locale };
     title ??= t("comments.title");

package/dist/types.d.ts

@@ -11,6 +11,12 @@ export interface Author {
     slug: string;
     avatarUrl?: string | null;
     bio?: string | null;
+    /** Meta công khai của thành viên (plugin khai báo `UserMeta` Public), vd `{ khoa: "cntt" }`. */
+    meta?: JsonObject;
+    /** Số bài đã đăng — chỉ có trong danh sách {@link getAuthors}. */
+    postCount?: number | null;
+    /** Dữ liệu plugin thêm qua filter api.author.response. */
+    extra?: JsonObject;
 }
 export interface MediaSize {
     url: string;
@@ -34,6 +40,8 @@ export interface Media {
     /** Điểm lấy nét 0–1 (object-position). */
     focalX?: number | null;
     focalY?: number | null;
+    title?: string;
+    createdAt?: string;
 }
 export interface Term {
     id: number;
@@ -214,6 +222,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 {
@@ -279,6 +293,20 @@ export interface ThemeManifest {
     }>;
     /** 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[]>>;
+    /**
+     * Kiểu nội dung của theme (CMS ≥ 1.15, như plugin.json — giống functions.php của WordPress):
+     * { "su-kien": { "label": "Sự kiện", "rewriteSlug": "su-kien", "taxonomies": ["khoa"] } }.
+     * Đăng ký khi theme (hoặc theme con) đang dùng; không đè kiểu của core/plugin.
+     */
+    postTypes?: Record<string, Record<string, JsonValue>>;
+    /** Phân loại của theme: { "khoa": { "label": "Khoa", "hierarchical": true, "postTypes": ["su-kien"] } }. */
+    taxonomies?: Record<string, Record<string, JsonValue>>;
+    /** Meta bài của theme: { "ngay-bat-dau": { "filterable": true, "indexType": "date" } } — lọc/sắp xếp/facet được. */
+    postMeta?: Record<string, Record<string, JsonValue>>;
+    /** Meta thành viên: { "hoc-vi": { "public": true } } — hiện trong hồ sơ tác giả (Author.meta). */
+    userMeta?: Record<string, {
+        public?: boolean;
+    }>;
     [key: string]: unknown;
 }
 type Loader<T> = () => Promise<{
@@ -429,6 +457,14 @@ export interface FilterMap {
     "sitemap.entries": (entries: SitemapEntry[], ctx: {
         site: Site;
     }) => SitemapEntry[] | Promise<SitemapEntry[]>;
+    /**
+     * Đổi thứ tự / thêm tên template trước khi theme chọn (core ≥ 1.15) — vd plugin "Sự kiện" thêm "plugin-su-kien" lên đầu
+     * cho kiểu nội dung của nó và khai báo template đó trong `definePlugin({ templates })`. Theme có template trùng tên vẫn thắng.
+     */
+    "template.hierarchy": (templates: string[], ctx: {
+        site: Site;
+        data: ResolveResult;
+    }) => string[] | Promise<string[]>;
     /** Thêm/bớt class của thẻ <body> (vd "logged-in", "has-promo-bar") */
     "body.class": (classes: string[], ctx: {
         site: Site;

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.29.0",
   "description": "SDK để viết theme và phần frontend của plugin cho Ecomweb",
   "type": "module",
   "main": "./dist/index.js",