@goplusvn/core 0.1.88 → 0.1.90

package/CHANGELOG.md

@@ -1,3 +1,76 @@
+## 0.1.90 — `between` phủ hết ngày cuối, và một bảng toán tử duy nhất
+
+Tiếp bản 0.1.89. `buildListQuery` **chép lại** bảng toán tử thay vì gọi
+`conditionForOperator` — và bản chép thiếu `between`. Hệ quả nối nhau:
+
+- Trước 0.1.89: mảng `[từ, đến]` rơi xuống nhánh mặc định rồi đi thẳng vào
+  Prisma dạng array ⇒ nổ ở tầng driver. Bộ lọc khoảng ngày của app khai đúng
+  `type: "datetime"` + `operator: "between"` hỏng sẵn mà không ai báo.
+- 0.1.89 thêm `between` nhưng dịch cận trên thành `lte`: bộ chọn ngày chỉ chở
+  ngày trần, `lte: 31/08` là chặn ở **00:00** ngày cuối ⇒ ngày cuối bị cắt gần
+  hết. Chọn 01/08–31/08 thì đơn tạo lúc 9h sáng 31/08 rơi ra ngoài. Không có
+  exception nào, chỉ thiếu dữ liệu — khó phát hiện hơn hẳn lỗi ở trên.
+
+**Đổi**
+
+- `crud/lib/filter-tree.ts` — `conditionForOperator` thêm `case "between"`,
+  dựng khoảng **nửa mở** `[từ, đến+1 ngày)` khi cận trên là ngày trần (chuỗi
+  `YYYY-MM-DD`, hoặc `Date` đúng nửa đêm UTC do `coerceFieldValue` sinh ra).
+  Mốc có giờ thật giữ nguyên `lte`; khoảng số vẫn là khoảng đóng.
+  KHÔNG cộng offset múi giờ ở đây — cận dưới cũng đang hiểu theo nửa đêm UTC,
+  thêm offset vào một đầu thì hai đầu lệch nhau. App cần biên theo lịch địa
+  phương thì quy đổi trước khi gửi.
+- `crud/lib/query-builder.ts` — bỏ chuỗi `if/else` chép tay, gọi thẳng
+  `conditionForOperator`. Filter phẳng và `filterTree` từ nay không thể lệch
+  bảng toán tử nữa (có test đối chiếu từng toán tử giữa hai đường).
+
+**Quy tắc rút ra**: comment ghi "dùng chung" mà code vẫn chép tay thì chỗ chép
+sẽ tụt lại — hợp nhất thật, đừng ghi chú suông.
+## 0.1.89 — Bộ lọc CRUD: `defaultValue` sống lại, chip vẽ một lần và đọc được
+
+Trang danh sách theo ngày (nghỉ phép, tăng ca, đăng ký suất ăn) mở ra là nạp
+**cả lịch sử**: `FilterConfig.defaultValue` được khai trong config nhưng chỉ
+dùng làm giá trị ban đầu cho ô nhập trong ngăn lọc, không nhánh nào đẩy nó vào
+state `filters` — nên request đầu tiên đi ra không mang bộ lọc nào. Cùng màn
+hình đó còn năm lỗi hiển thị khác của hàng chip.
+
+**Đổi**
+
+- `crud/lib/filter-defaults.ts` (mới) — `resolveFilterDefaults()` biến
+  `FilterConfig[]` thành `ActiveFilter[]` để seed thẳng vào state. Thêm token
+  `"$today"`: config khai `defaultValue: "$today"` thì nhận NGÀY HÔM NAY, và
+  với `operator: "between"` thì nhận `[hôm nay, hôm nay]`.
+  Ngày tính bằng `Intl.DateTimeFormat("en-CA", { timeZone })` chứ **không**
+  phải giờ máy: initializer của `useState` chạy cả trên server lẫn client, máy
+  chủ UTC và trình duyệt GMT+7 lệch ngày suốt 00:00–07:00 giờ VN ⇒ hydration
+  mismatch mỗi đêm. Giá trị seed là chuỗi `YYYY-MM-DD` trần, không phải `Date`,
+  để không kéo theo múi giờ khi đi qua JSON.
+- `crud/components/crud-provider.tsx` — `useState<ActiveFilter[]>` seed bằng
+  `resolveFilterDefaults(initialConfig?.filters)`.
+- `crud/lib/filter-display.ts` (mới) — `formatFilterValue()`: ngày in
+  `21/08/2026` theo `Asia/Ho_Chi_Minh`, khoảng cùng ngày gộp lại còn một ngày,
+  giá trị select in nhãn tuỳ chọn thay vì mã.
+- `crud/components/crud-table-toolbar.tsx` — thôi render `<CrudFilterChips>`.
+  `DataTableToolbar` đã tự vẽ hàng chip, render cả hai thì **mỗi bộ lọc hiện
+  hai chip**, mỗi chip hỏng một kiểu: một cái `JSON.stringify(Date)` ra chuỗi
+  ISO có nháy (`"2026-08-20T17:00:00.000Z"`), một cái `split(":")` cắt cụt
+  (`Fri Aug 21 2026 00`, và giá trị nào chứa dấu hai chấm cũng mất đuôi).
+  Chip giờ nhận `displayValue` đã format sẵn.
+- `crud/components/crud-table-toolbar.tsx` — bấm X trên **một** chip trước đây
+  gọi `clearFilters()` ⇒ bay sạch bộ lọc còn lại. Nay chỉ gỡ đúng chip đó.
+- `crud/components/crud-filters/datetime-filter.tsx` — xoá trắng ô ngày giờ
+  thật sự `removeFilter()`; đọc được cả `YYYY-MM-DD`, `Date` và chuỗi ISO; gửi
+  lên dạng `YYYY-MM-DD` thay vì `toISOString()` (mốc ISO của nửa đêm giờ VN là
+  `17:00Z` **hôm trước**, cột `@db.Date` cắt theo UTC ⇒ lọc ngày 20 ra ngày 19).
+- `crud/lib/query-builder.ts` — thêm nhánh `between`: thiếu nó thì mảng
+  `[từ, đến]` rơi xuống `else` và đi thẳng vào Prisma dạng array ⇒ nổ ở driver.
+- `ui/data-display/data-table/data-table-toolbar.tsx` — `ActiveFilter` thêm
+  `displayValue?: string` (tuỳ chọn, không breaking).
+- `crud/components/crud-filter-chips.tsx` — giữ export cho app gọi trực tiếp,
+  đánh `@deprecated`, và sửa luôn phần format value.
+
+**Quy tắc rút ra**: mọi phép tính "hôm nay" chạy trong component `"use client"`
+phải chốt `timeZone` tường minh — giờ máy khác nhau giữa hai lần render.
 ## 0.1.85 — Hộp thoại: gỡ bẫy class `sm:` khiến trang không ghi đè được
 
 Sửa lỗi giao diện do 0.1.84 gây ra. `DialogContent` đổi mặc định thành

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goplusvn/core",
   "description": "GoPlusVN Platform Kit - ERP kernel: layout, RBAC, CRUD, multi-tenant, system pages",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "private": false,
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/src/crud/components/crud-filter-chips.tsx

@@ -5,12 +5,19 @@ import { X } from "lucide-react";
 import type { EntityConfig } from "../../types";
 
 import { Badge } from "../../ui";
+import { formatFilterValue } from "../lib/filter-display";
 import { useCrudState } from "./crud-context";
 
 interface CrudFilterChipsProps {
   config: EntityConfig;
 }
 
+/**
+ * @deprecated `CrudTableToolbar` KHÔNG còn render component này — thanh công cụ
+ * (`DataTableToolbar`) đã tự vẽ hàng chip, render cả hai thì mỗi bộ lọc hiện
+ * hai lần. Giữ export để app ngoài đang gọi trực tiếp không gãy khi nâng cấp.
+ */
+
 export function CrudFilterChips({ config }: CrudFilterChipsProps) {
   const { filters, removeFilter, search, setSearch } = useCrudState();
 
@@ -18,43 +25,6 @@ export function CrudFilterChips({ config }: CrudFilterChipsProps) {
     return null;
   }
 
-  const getFilterLabel = (filterName: string, value: unknown): string => {
-    const filterConfig = config.filters?.find((f) => f.name === filterName);
-    if (!filterConfig) return filterName;
-
-    // Handle different filter types
-    if (filterConfig.type === "select" || filterConfig.type === "radio") {
-      const option = filterConfig.options?.find(
-        (opt) => opt.value === value || String(opt.value) === String(value),
-      );
-      return option
-        ? `${filterConfig.label}: ${option.label}`
-        : `${filterConfig.label}: ${String(value)}`;
-    }
-
-    if (filterConfig.type === "checkbox" && Array.isArray(value)) {
-      const labels = value
-        .map((v) => {
-          const option = filterConfig.options?.find(
-            (opt) => opt.value === v || String(opt.value) === String(v),
-          );
-          return option ? option.label : String(v);
-        })
-        .filter(Boolean);
-      return `${filterConfig.label}: ${labels.join(", ")}`;
-    }
-
-    if (
-      filterConfig.type === "datetime" &&
-      Array.isArray(value) &&
-      value.length === 2
-    ) {
-      return `${filterConfig.label}: ${new Date(value[0] as string).toLocaleDateString()} - ${new Date(value[1] as string).toLocaleDateString()}`;
-    }
-
-    return `${filterConfig.label}: ${String(value)}`;
-  };
-
   return (
     <div className="flex items-center gap-2 flex-wrap">
       {/* Search chip */}
@@ -83,10 +53,15 @@ export function CrudFilterChips({ config }: CrudFilterChipsProps) {
           className="gap-1.5 px-2.5 py-1 text-xs font-medium hover:bg-secondary/80 transition-colors"
         >
           <span className="text-muted-foreground">
-            {getFilterLabel(filter.name, filter.value).split(":")[0]}:
+            {config.filters?.find((f) => f.name === filter.name)?.label ??
+              filter.name}
+            :
           </span>
           <span className="font-semibold">
-            {getFilterLabel(filter.name, filter.value).split(":")[1]?.trim()}
+            {formatFilterValue(
+              config.filters?.find((f) => f.name === filter.name),
+              filter.value,
+            )}
           </span>
           <button
             onClick={() => removeFilter(filter.name)}

package/src/crud/components/crud-filters/datetime-filter.tsx

@@ -14,44 +14,85 @@ interface DateTimeFilterProps {
   mode?: "single" | "range";
 }
 
+/**
+ * Giá trị bộ lọc ➝ `Date` cho bộ chọn.
+ *
+ * Bộ lọc chở CHUỖI "YYYY-MM-DD" (xem `filter-defaults`), nhưng URL/`coerceFilters`
+ * có thể trả về `Date`. Nhận cả hai, và dựng ngày trần bằng bộ dựng theo GIỜ ĐỊA
+ * PHƯƠNG chứ không phải `new Date("2026-08-23")` — chuỗi đó là 00:00 UTC, ở
+ * GMT+7 hiện ra vẫn đúng ngày, nhưng ở múi giờ âm thì lùi một ngày ngay trên
+ * lịch người dùng đang nhìn.
+ */
+function parseDateValue(val: unknown): Date | null {
+  if (!val) return null;
+  if (val instanceof Date) return Number.isNaN(val.getTime()) ? null : val;
+  if (typeof val !== "string") return null;
+  const bare = val.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (bare) {
+    return new Date(Number(bare[1]), Number(bare[2]) - 1, Number(bare[3]));
+  }
+  const parsed = new Date(val);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+function parseRangeValue(val: unknown): [Date, Date] | null {
+  if (!Array.isArray(val) || val.length !== 2) return null;
+  const from = parseDateValue(val[0]);
+  const to = parseDateValue(val[1]);
+  return from && to ? [from, to] : null;
+}
+
+/** `Date` ➝ "YYYY-MM-DD" theo lịch người dùng đang nhìn. */
+function toDateKey(date: Date): string {
+  const pad = (n: number) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+
 export function DateTimeFilter({
   filter,
   mode = "single",
 }: DateTimeFilterProps) {
-  const { filters, updateFilter, addFilter } = useCrudContext();
+  const { filters, addFilter, removeFilter } = useCrudContext();
   const currentFilter = filters.find((f) => f.name === filter.name);
-  const [value, setValue] = useState<Date | [Date, Date] | null>(
-    currentFilter?.value
-      ? mode === "range"
-        ? (currentFilter.value as [Date, Date])
-        : (currentFilter.value as Date)
-      : null,
+
+  const [value, setValue] = useState<Date | [Date, Date] | null>(() =>
+    mode === "range"
+      ? parseRangeValue(currentFilter?.value)
+      : parseDateValue(currentFilter?.value),
   );
 
+  // Bộ lọc đổi từ bên ngoài (seed `defaultValue`, bấm X trên chip, Đặt lại) —
+  // ô nhập phải đi theo, kể cả khi bộ lọc bị GỠ (về rỗng, không giữ giá trị cũ).
   useEffect(() => {
-    const externalFilter = filters.find((f) => f.name === filter.name);
-    if (externalFilter && externalFilter.value !== value) {
-      setValue(
-        mode === "range"
-          ? (externalFilter.value as [Date, Date])
-          : (externalFilter.value as Date),
-      );
-    }
-  }, [filters, filter.name, mode, value]);
+    const external = filters.find((f) => f.name === filter.name);
+    setValue(
+      mode === "range"
+        ? parseRangeValue(external?.value)
+        : parseDateValue(external?.value),
+    );
+  }, [filters, filter.name, mode]);
 
   const handleChange = (newValue: Date | [Date, Date] | null) => {
     setValue(newValue);
 
+    // Xoá ngày là GỠ bộ lọc. Trước đây nhánh này return sớm nên chip vẫn còn và
+    // danh sách vẫn bị lọc — không có đường nào bỏ lọc ngày.
     if (!newValue) {
+      removeFilter(filter.name);
       return;
     }
 
     const operator =
       mode === "range" ? filter.operator || "between" : filter.operator || "eq";
 
+    // Gửi đi CHUỖI ngày trần: không mang giờ thì không có gì để lệch múi giờ
+    // trên đường qua URL. `Date.toISOString()` của 00:00 giờ VN là 17:00Z hôm
+    // TRƯỚC — đúng cái đã làm bộ lọc trả về dữ liệu của hôm qua.
     addFilter({
       name: filter.name,
-      value: newValue,
+      value: Array.isArray(newValue)
+        ? [toDateKey(newValue[0]), toDateKey(newValue[1])]
+        : toDateKey(newValue),
       operator,
     });
   };

package/src/crud/components/crud-provider.tsx

@@ -2,6 +2,8 @@
 
 import { useCallback, useMemo, useState } from "react";
 
+import { resolveFilterDefaults } from "../lib/filter-defaults";
+
 import type {
   ActiveFilter,
   CrudPermissions,
@@ -28,7 +30,8 @@ import type {
 
 // Combined interface for backward compatibility
 interface CrudContextValue
-  extends CrudConfigContextValue,
+  extends
+    CrudConfigContextValue,
     CrudStateContextValue,
     CrudSelectionContextValue {}
 
@@ -66,7 +69,12 @@ export function CrudProvider({
 
   // --- State (Search, Filters, Pagination, Sorting) ---
   const [search, setSearch] = useState<string>("");
-  const [filters, setFilters] = useState<ActiveFilter[]>([]);
+  // Bộ lọc khai `defaultValue` phải ĐANG CHẠY ngay khi trang mở, không chỉ nằm
+  // trong ngăn lọc. Trang danh sách theo ngày mà mở ra không lọc thì nạp cả
+  // lịch sử — xem `resolveFilterDefaults`.
+  const [filters, setFilters] = useState<ActiveFilter[]>(() =>
+    resolveFilterDefaults(initialConfig?.filters),
+  );
   const [pagination, setPagination] = useState({ page: 1, pageSize: 10 });
 
   // Validate defaultSort field exists in visible table fields

package/src/crud/components/crud-table-toolbar.tsx

@@ -5,9 +5,9 @@ import type { Table } from "@tanstack/react-table";
 
 import type { CrudPermissions, EntityConfig } from "../../types";
 
-import { CrudFilterChips } from "./crud-filter-chips";
 import { FilterBuilder } from "./crud-filters/filter-builder";
 import { useCrudState } from "./crud-context";
+import { formatFilterValue } from "../lib/filter-display";
 import { DataTableToolbar } from "../../ui/data-display/data-table/data-table-toolbar";
 import type { FilterConfig } from "../../ui/data-display/data-table/data-table-toolbar";
 
@@ -26,7 +26,7 @@ export function CrudTableToolbar<TData>({
   viewMode = "table",
   onViewModeChange,
 }: CrudTableToolbarProps<TData>) {
-  const { filters, clearFilters, addFilter, removeFilter, search, setSearch } =
+  const { filters, setFilters, clearFilters, search, setSearch } =
     useCrudState();
 
   // Convert Crud filters to DataTable filters
@@ -41,51 +41,49 @@ export function CrudTableToolbar<TData>({
     }));
   }, [config.filters]);
 
+  // Chip do MỘT chỗ vẽ: `DataTableToolbar`. Trước đây toolbar này render thêm
+  // `<CrudFilterChips>` ngay dưới, hai component đọc cùng mảng `filters` nên
+  // mỗi bộ lọc hiện hai chip — và hai chip in giá trị theo hai kiểu hỏng khác
+  // nhau (JSON thô / bị `split(":")` cắt cụt).
   const activeFilters = useMemo(() => {
     return filters.map((f) => ({
       name: f.name,
       value: f.value,
       operator: f.operator,
+      displayValue: formatFilterValue(
+        config.filters?.find((cf) => cf.name === f.name),
+        f.value,
+      ),
     }));
-  }, [filters]);
+  }, [filters, config.filters]);
 
   return (
-    <div className="space-y-2">
-      <DataTableToolbar
-        table={table}
-        // Search
-        searchEnabled={config.features?.search}
-        searchValue={search}
-        onSearchChange={setSearch}
-        searchPlaceholder={`Search ${config.pluralLabel.toLowerCase()}...`}
-        // Filters
-        filters={dataTableFilters}
-        activeFilters={activeFilters}
-        // Custom filter builder overrides the default filter rendering
-        filterBuilder={<FilterBuilder filters={config.filters!} />}
-        // Filter callbacks
-        onFiltersChange={(newFilters) => {
-          if (newFilters.length === 0) {
-            clearFilters();
-          } else {
-            // Complex syncing is handled by FilterBuilder/CrudFilterChips
-            // This callback mainly handles the "Clear all" action
-            clearFilters();
-          }
-        }}
-        // View Options
-        viewMode={viewMode}
-        onViewModeChange={onViewModeChange}
-        enableViewModeToggle={!!onViewModeChange}
-        // Reset
-        onReset={() => {
-          setSearch("");
-          clearFilters();
-        }}
-      />
-
-      {/* Second row: Filter chips (specific to CRUD complex filters) */}
-      <CrudFilterChips config={config} />
-    </div>
+    <DataTableToolbar
+      table={table}
+      // Search
+      searchEnabled={config.features?.search}
+      searchValue={search}
+      onSearchChange={setSearch}
+      searchPlaceholder={`Search ${config.pluralLabel.toLowerCase()}...`}
+      // Filters
+      filters={dataTableFilters}
+      activeFilters={activeFilters}
+      // Custom filter builder overrides the default filter rendering
+      filterBuilder={<FilterBuilder filters={config.filters!} />}
+      // Bấm X trên MỘT chip chỉ gỡ chip đó. Trước đây nhánh nào cũng gọi
+      // `clearFilters()` nên gỡ một cái là bay sạch bộ lọc còn lại.
+      onFiltersChange={(next) =>
+        setFilters(filters.filter((f) => next.some((n) => n.name === f.name)))
+      }
+      // View Options
+      viewMode={viewMode}
+      onViewModeChange={onViewModeChange}
+      enableViewModeToggle={!!onViewModeChange}
+      // Reset
+      onReset={() => {
+        setSearch("");
+        clearFilters();
+      }}
+    />
   );
 }

package/src/crud/lib/filter-between.test.ts

@@ -0,0 +1,123 @@
+/**
+ * BỘ LỌC KHOẢNG NGÀY — `between`.
+ *
+ * Hai lỗi nối nhau, cùng một gốc: `buildListQuery` chép lại bảng toán tử thay
+ * vì gọi `conditionForOperator`, và bản chép thiếu `between`.
+ *
+ *  1. Trước 0.1.89: mảng `[từ, đến]` rơi xuống nhánh mặc định, đi thẳng vào
+ *     Prisma dạng array ⇒ nổ ở tầng driver. Hai bộ lọc khoảng ngày của vinhhoa
+ *     (orders.createdAt, purchaseOrders.orderDate) hỏng sẵn mà không ai báo.
+ *  2. 0.1.89 dịch thành `lte` ⇒ chặn ở 00:00 ngày cuối, NGÀY CUỐI BỊ CẮT gần
+ *     hết. Đây mới là kiểu hỏng nguy hiểm: không exception, chỉ thiếu dữ liệu.
+ *
+ * Bản vá: khoảng nửa mở `[từ, đến+1 ngày)`, và hai đường (filter phẳng /
+ * `filterTree`) dùng CHUNG một bảng toán tử để không lệch nhau lần nữa.
+ */
+import { describe, expect, it } from "vitest";
+
+import type { EntityConfig, FilterOperator } from "../../types";
+
+import { buildListQuery } from "./query-builder";
+import { conditionForOperator } from "./filter-tree";
+
+const config = {
+  name: "orders",
+  label: "Đơn",
+  pluralLabel: "Đơn",
+  fields: [
+    { name: "createdAt", label: "Ngày tạo", type: "datetime" },
+    { name: "total", label: "Tổng", type: "number" },
+  ],
+} as unknown as EntityConfig;
+
+function whereFor(value: unknown) {
+  return buildListQuery({
+    entity: "orders",
+    config,
+    params: {
+      page: 1,
+      pageSize: 10,
+      filters: [{ name: "createdAt", value, operator: "between" }],
+    },
+  }).where.createdAt;
+}
+
+describe("between — cận trên phải phủ hết ngày cuối", () => {
+  it("ngày trần dạng chuỗi ➝ nửa mở tới nửa đêm hôm sau", () => {
+    expect(whereFor(["2026-08-01", "2026-08-31"])).toEqual({
+      gte: "2026-08-01",
+      lt: new Date("2026-09-01T00:00:00.000Z"),
+    });
+  });
+
+  it("Date nửa đêm UTC (đã qua coerceFieldValue) cũng được nới", () => {
+    const where = whereFor([
+      new Date("2026-08-01T00:00:00.000Z"),
+      new Date("2026-08-31T00:00:00.000Z"),
+    ]);
+
+    expect((where as { lt: Date }).lt.toISOString()).toBe(
+      "2026-09-01T00:00:00.000Z",
+    );
+  });
+
+  it("bản ghi lúc 9h sáng ngày cuối nằm TRONG khoảng", () => {
+    const { lt } = whereFor(["2026-08-01", "2026-08-31"]) as { lt: Date };
+    expect(new Date("2026-08-31T09:00:00.000Z").getTime()).toBeLessThan(
+      lt.getTime(),
+    );
+  });
+
+  it("mốc CÓ giờ thật thì giữ nguyên lte, không tự nới thêm một ngày", () => {
+    const end = new Date("2026-08-31T12:30:00.000Z");
+    expect(whereFor(["2026-08-01T00:00:00.000Z", end])).toEqual({
+      gte: "2026-08-01T00:00:00.000Z",
+      lte: end,
+    });
+  });
+
+  it("mảng không đủ hai mốc ➝ trả nguyên giá trị, không dựng khoảng méo", () => {
+    expect(conditionForOperator("between", ["2026-08-01"])).toEqual([
+      "2026-08-01",
+    ]);
+  });
+
+  it("khoảng số vẫn là khoảng đóng — chỉ NGÀY mới được nới", () => {
+    expect(conditionForOperator("between", [1000, 5000])).toEqual({
+      gte: 1000,
+      lte: 5000,
+    });
+  });
+});
+
+describe("filter phẳng và filterTree dùng chung một bảng toán tử", () => {
+  const cases: [FilterOperator, unknown][] = [
+    ["contains", "an"],
+    ["in", [1, 2]],
+    ["notIn", [3]],
+    ["eq", 5],
+    ["ne", 5],
+    ["gt", 5],
+    ["gte", 5],
+    ["lt", 5],
+    ["lte", 5],
+    ["startsWith", "a"],
+    ["endsWith", "z"],
+    ["isNotNull", 1],
+    ["between", ["2026-08-01", "2026-08-31"]],
+  ];
+
+  it.each(cases)("%s cho cùng một điều kiện ở cả hai đường", (op, value) => {
+    const flat = buildListQuery({
+      entity: "orders",
+      config,
+      params: {
+        page: 1,
+        pageSize: 10,
+        filters: [{ name: "total", value, operator: op }],
+      },
+    }).where.total;
+
+    expect(flat).toEqual(conditionForOperator(op, value));
+  });
+});

package/src/crud/lib/filter-defaults.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import type { FilterConfig } from "../../types";
+
+import { resolveFilterDefaults, todayDateKey } from "./filter-defaults";
+import { formatFilterValue } from "./filter-display";
+
+const dateFilter: FilterConfig = {
+  name: "date",
+  label: "Ngày nghỉ",
+  type: "datetime",
+  field: "date",
+  operator: "eq",
+  defaultValue: "$today",
+};
+
+describe("resolveFilterDefaults", () => {
+  it("giải $today thành ngày trần theo lịch VN", () => {
+    const [filter] = resolveFilterDefaults([dateFilter]);
+    expect(filter).toEqual({
+      name: "date",
+      value: todayDateKey(),
+      operator: "eq",
+    });
+    expect(filter.value).toMatch(/^\d{4}-\d{2}-\d{2}$/);
+  });
+
+  it("$today với operator between ➝ hôm nay tới hết hôm nay", () => {
+    const [filter] = resolveFilterDefaults([
+      { ...dateFilter, operator: "between" },
+    ]);
+    expect(filter.value).toEqual([todayDateKey(), todayDateKey()]);
+  });
+
+  it("ngày VN tính theo múi giờ cố định, không theo giờ máy", () => {
+    // Ngưỡng đổi ngày ở VN là 17:00Z hôm trước; máy chạy UTC vẫn phải ra ngày VN.
+    const vn = new Intl.DateTimeFormat("en-CA", {
+      timeZone: "Asia/Ho_Chi_Minh",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).format(new Date());
+    expect(todayDateKey()).toBe(vn);
+  });
+
+  it("bộ lọc không khai defaultValue ➝ không bật sẵn", () => {
+    expect(
+      resolveFilterDefaults([{ ...dateFilter, defaultValue: undefined }]),
+    ).toEqual([]);
+    expect(resolveFilterDefaults(undefined)).toEqual([]);
+  });
+
+  it("giữ nguyên defaultValue thường (không phải token)", () => {
+    const [filter] = resolveFilterDefaults([
+      {
+        name: "status",
+        label: "Trạng thái",
+        type: "select",
+        field: "status",
+        defaultValue: "approved",
+      },
+    ]);
+    expect(filter).toEqual({
+      name: "status",
+      value: "approved",
+      operator: "eq",
+    });
+  });
+});
+
+describe("formatFilterValue", () => {
+  it("ngày hiện dd/MM/yyyy, không phải chuỗi ISO hay JSON", () => {
+    expect(formatFilterValue(dateFilter, "2026-08-21")).toBe("21/08/2026");
+    // 00:00 giờ VN ngày 21/08 = 17:00Z ngày 20/08 — vẫn phải đọc là 21/08.
+    expect(
+      formatFilterValue(dateFilter, new Date("2026-08-20T17:00:00.000Z")),
+    ).toBe("21/08/2026");
+  });
+
+  it("khoảng một ngày đọc gọn thành một ngày", () => {
+    expect(
+      formatFilterValue({ ...dateFilter, operator: "between" }, [
+        "2026-08-21",
+        "2026-08-21",
+      ]),
+    ).toBe("21/08/2026");
+    expect(
+      formatFilterValue({ ...dateFilter, operator: "between" }, [
+        "2026-08-21",
+        "2026-08-23",
+      ]),
+    ).toBe("21/08/2026 - 23/08/2026");
+  });
+
+  it("select hiện nhãn tuỳ chọn, không hiện giá trị thô", () => {
+    const filter: FilterConfig = {
+      name: "status",
+      label: "Trạng thái",
+      type: "select",
+      field: "status",
+      options: [{ label: "Đã duyệt", value: "approved" }],
+    };
+    expect(formatFilterValue(filter, "approved")).toBe("Đã duyệt");
+  });
+
+  it("giá trị có dấu hai chấm KHÔNG bị cắt cụt", () => {
+    const filter: FilterConfig = {
+      name: "note",
+      label: "Ghi chú",
+      type: "text",
+      field: "note",
+    };
+    expect(formatFilterValue(filter, "ca 1: 06:30")).toBe("ca 1: 06:30");
+  });
+});

package/src/crud/lib/filter-defaults.ts

@@ -0,0 +1,56 @@
+import type { ActiveFilter, FilterConfig } from "../../types";
+
+/**
+ * BỘ LỌC MẶC ĐỊNH — biến `FilterConfig.defaultValue` thành bộ lọc đang chạy thật.
+ *
+ * Trước đây `defaultValue` chỉ được vài ô nhập trong ngăn lọc đọc để đặt giá
+ * trị ban đầu; không nhánh nào đẩy nó vào state `filters` của `CrudProvider`
+ * (khởi tạo cứng bằng `[]`). App khai xong tưởng đã bật, mà trang vẫn mở ra ở
+ * trạng thái KHÔNG lọc — danh sách theo ngày nạp toàn bộ lịch sử.
+ *
+ * Token `"$today"` giải ra NGÀY HÔM NAY theo lịch Việt Nam, dạng "YYYY-MM-DD".
+ * Hai điểm bắt buộc:
+ *
+ *  · Tính bằng `Intl` với `timeZone` cố định, KHÔNG dùng giờ máy. Hàm này chạy
+ *    trong initializer của `useState` nên nổ ở CẢ server lẫn trình duyệt; lấy
+ *    giờ máy thì server (thường UTC) ra ngày khác trình duyệt (GMT+7) và React
+ *    báo hydration mismatch — mỗi đêm một lần, từ 00:00 đến 07:00 giờ VN.
+ *  · Giá trị là CHUỖI ngày trần, không phải `Date`. Chuỗi không mang giờ nên
+ *    không có gì để lệch múi giờ khi đi qua URL; `coerceFieldValue` ở route
+ *    handler ép về `Date` đúng kiểu cột ngay trước khi vào Prisma.
+ */
+export const TODAY_TOKEN = "$today";
+
+/** Múi giờ vận hành — trùng với formatter hiển thị trong `utils` (vi-VN). */
+const TZ = "Asia/Ho_Chi_Minh";
+
+/** Hôm nay theo lịch VN, "YYYY-MM-DD". `en-CA` cho ra đúng dạng ISO này. */
+export function todayDateKey(): string {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone: TZ,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(new Date());
+}
+
+/** `defaultValue` đã khai ➝ giá trị thật (giải token nếu có). */
+export function resolveDefaultValue(filter: FilterConfig): unknown {
+  if (filter.defaultValue !== TODAY_TOKEN) return filter.defaultValue;
+  const today = todayDateKey();
+  // Bộ chọn KHOẢNG ngày cần cặp [từ, đến] — hôm nay tới hết hôm nay.
+  return filter.operator === "between" ? [today, today] : today;
+}
+
+/** Danh sách bộ lọc bật sẵn khi trang vừa mở. */
+export function resolveFilterDefaults(
+  filters: FilterConfig[] | undefined,
+): ActiveFilter[] {
+  return (filters ?? [])
+    .filter((f) => f.defaultValue !== undefined)
+    .map((f) => ({
+      name: f.name,
+      value: resolveDefaultValue(f),
+      operator: f.operator ?? "eq",
+    }));
+}

package/src/crud/lib/filter-display.ts

@@ -0,0 +1,59 @@
+import type { FilterConfig } from "../../types";
+
+/**
+ * GIÁ TRỊ BỘ LỌC ➝ CHỮ CHO NGƯỜI ĐỌC (chip trên thanh công cụ).
+ *
+ * Trước đây chip tự lo phần này và hỏng theo hai kiểu khác nhau:
+ *  · `typeof value === "object" ? JSON.stringify(v) : String(v)` — ngày là
+ *    `Date` (typeof "object") nên chip in ra `"2026-08-20T17:00:00.000Z"`,
+ *    kèm cả dấu nháy của JSON.
+ *  · dựng chuỗi `"Nhãn: giá trị"` rồi `.split(":")` để tách lại hai vế — giá
+ *    trị nào có dấu hai chấm là mất đuôi, `String(date)` bị cắt còn
+ *    "Fri Aug 21 2026 00".
+ *
+ * Nhãn và giá trị ở đây là HAI thứ tách rời từ đầu, không ghép rồi cắt.
+ */
+const DATE_FORMAT: Intl.DateTimeFormatOptions = {
+  day: "2-digit",
+  month: "2-digit",
+  year: "numeric",
+  timeZone: "Asia/Ho_Chi_Minh",
+};
+
+function formatDate(value: unknown): string {
+  const date = value instanceof Date ? value : new Date(String(value));
+  if (Number.isNaN(date.getTime())) return String(value);
+  return new Intl.DateTimeFormat("vi-VN", DATE_FORMAT).format(date);
+}
+
+function optionLabel(filter: FilterConfig, value: unknown): string {
+  const option = filter.options?.find(
+    (opt) => opt.value === value || String(opt.value) === String(value),
+  );
+  return option ? option.label : String(value);
+}
+
+/** Chỉ phần GIÁ TRỊ — nhãn do chip tự lấy từ `filter.label`. */
+export function formatFilterValue(
+  filter: FilterConfig | undefined,
+  value: unknown,
+): string {
+  if (value === null || value === undefined) return "";
+  if (!filter) return String(value);
+
+  if (filter.type === "select" || filter.type === "radio") {
+    return optionLabel(filter, value);
+  }
+
+  if (Array.isArray(value)) {
+    if (filter.type === "datetime") {
+      const parts = value.map(formatDate);
+      // Khoảng một ngày ("hôm nay tới hết hôm nay") đọc là một ngày.
+      return parts[0] === parts[1] ? parts[0] : parts.join(" - ");
+    }
+    return value.map((v) => optionLabel(filter, v)).join(", ");
+  }
+
+  if (filter.type === "datetime") return formatDate(value);
+  return String(value);
+}

package/src/crud/lib/filter-tree.ts

@@ -29,11 +29,46 @@ export type FilterTreeNode =
 const MAX_DEPTH = 4;
 const MAX_LEAVES = 30;
 
+const DATE_KEY = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86_400_000;
+
+/**
+ * Cận TRÊN của `between` khi mốc gửi xuống không mang giờ.
+ *
+ * Bộ chọn ngày chỉ chở ngày trần ("2026-08-31", hoặc `Date` đã ép về nửa đêm
+ * UTC — xem `coerceFieldValue`). Dịch thẳng thành `lte` là chặn ở 00:00 của
+ * ngày cuối, tức NGÀY CUỐI BỊ CẮT gần hết: chọn 01/08–31/08 thì bản ghi tạo
+ * lúc 9h sáng 31/08 rơi ra ngoài. Người dùng không thấy lỗi, chỉ thấy thiếu
+ * dữ liệu — kiểu hỏng khó phát hiện hơn hẳn một cái exception.
+ *
+ * Nên khoảng dựng NỬA MỞ: `[từ, đến+1 ngày)`. Không cộng múi giờ ở đây —
+ * cận dưới cũng đang hiểu theo nửa đêm UTC, thêm offset vào một đầu thì hai
+ * đầu lệch nhau. App nào cần biên theo lịch địa phương thì tự quy đổi trước
+ * khi gửi (xem cách tanloc-spartronics dùng `vnDateKeyToDbDate`).
+ *
+ * Mốc CÓ giờ thật thì giữ nguyên `lte` — đó là ý người gọi, không phải ngày trần.
+ */
+function upperDateBound(value: unknown): Record<string, unknown> {
+  if (typeof value === "string" && DATE_KEY.test(value)) {
+    return { lt: new Date(Date.parse(`${value}T00:00:00.000Z`) + DAY_MS) };
+  }
+  // Nửa đêm UTC chằn chặn = ngày trần đã qua `new Date("YYYY-MM-DD")`.
+  if (value instanceof Date && value.getTime() % DAY_MS === 0) {
+    return { lt: new Date(value.getTime() + DAY_MS) };
+  }
+  return { lte: value };
+}
+
 /** Điều kiện Prisma cho một toán tử — dùng chung với filter phẳng. */
 export function conditionForOperator(op: string, value: unknown): unknown {
   switch (op) {
     case "contains":
       return { contains: value, mode: "insensitive" };
+    // Khoảng [từ, đến] của bộ chọn ngày. Trước 0.1.89 KHÔNG có nhánh này: cả
+    // mảng rơi xuống `default` và đi thẳng vào Prisma dạng array ⇒ nổ ở driver.
+    case "between":
+      if (!Array.isArray(value) || value.length !== 2) return value;
+      return { gte: value[0], ...upperDateBound(value[1]) };
     case "in":
       return { in: value };
     case "notIn":

package/src/crud/lib/query-builder.ts

@@ -1,4 +1,4 @@
-import { compileFilterTree } from "./filter-tree";
+import { compileFilterTree, conditionForOperator } from "./filter-tree";
 import { CrudRequestError } from "./errors";
 import type { CrudQueryParams, EntityConfig } from "../../types";
 
@@ -58,21 +58,10 @@ export function buildListQuery({
         key = parts.pop()!;
         for (const p of parts) { if (!target[p]) target[p] = {}; target = target[p]; }
       }
-      const op = operator as string;
-      if (op === "contains") target[key] = { contains: value, mode: "insensitive" };
-      else if (op === "in") target[key] = { in: value };
-      else if (op === "notIn") target[key] = { notIn: value };
-      else if (op === "eq") target[key] = value;
-      else if (op === "ne") target[key] = { not: value };
-      else if (op === "gt") target[key] = { gt: value };
-      else if (op === "gte") target[key] = { gte: value };
-      else if (op === "lt") target[key] = { lt: value };
-      else if (op === "lte") target[key] = { lte: value };
-      else if (op === "startsWith") target[key] = { startsWith: value, mode: "insensitive" };
-      else if (op === "endsWith") target[key] = { endsWith: value, mode: "insensitive" };
-      else if (op === "isNull") target[key] = null;
-      else if (op === "isNotNull") target[key] = { not: null };
-      else target[key] = value;
+      // MỘT bảng toán tử cho cả hai đường (filter phẳng ở đây, `filterTree` ở
+      // dưới). Trước đây chỗ này chép lại chuỗi if riêng, và bản chép thiếu
+      // `between` — bộ lọc khoảng ngày của app khai đúng type vẫn nổ ở driver.
+      target[key] = conditionForOperator(operator as string, value);
     }
   }
 

package/src/types/index.ts

@@ -653,6 +653,13 @@ export interface FilterConfig {
   type: FilterType;
   field: string;
   operator?: FilterOperator;
+  /**
+   * Bộ lọc BẬT SẴN khi trang vừa mở — `CrudProvider` seed thẳng vào state
+   * `filters`, nên nó hiện thành chip và người dùng thấy mình đang xem cái gì.
+   *
+   * Token `"$today"` = hôm nay theo lịch VN; với `operator: "between"` nó giải
+   * thành cặp [hôm nay, hôm nay]. Xem `crud/lib/filter-defaults`.
+   */
   defaultValue?: unknown;
   options?: Array<{ label: string; value: string | number | boolean }>;
   dataSource?: DataSource;

package/src/ui/data-display/data-table/data-table-toolbar.tsx

@@ -27,6 +27,11 @@ export interface ActiveFilter {
   name: string;
   value: unknown;
   operator: string;
+  /**
+   * Chữ đã dựng sẵn cho chip. Lớp trên biết `FilterConfig` (nhãn tuỳ chọn,
+   * kiểu ngày) nên nó dựng; toolbar chỉ in ra. Không truyền thì rơi về cách cũ.
+   */
+  displayValue?: string;
 }
 
 export interface FilterConfig {
@@ -345,9 +350,10 @@ export function DataTableToolbar<TData>({
             const filterConfig = filters.find((f) => f.name === filter.name);
             const label = filterConfig?.label || filter.name;
             const displayValue =
-              typeof filter.value === "object"
+              filter.displayValue ??
+              (typeof filter.value === "object"
                 ? JSON.stringify(filter.value)
-                : String(filter.value);
+                : String(filter.value));
 
             return (
               <div