@suphark/ui 0.60.0 → 0.61.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.61.0] — 2026-10-24
+
+### Added
+- `DataTable` สถานะตาราง (ตาม mockup): **ผิดพลาด** — prop `error` แสดงกล่อง "โหลดรายการไม่สำเร็จ" แทนตาราง (ข้อความกลาง ไม่แสดง error ดิบ, ซ่อนเลขหน้า) + `onRetry` = ปุ่ม "ลองใหม่" (ทั้งสอง variant) · `variant="quiet"`: **ไม่พบ** — บอกคำค้น "ไม่พบรายการที่ตรงกับ …" + ปุ่ม "ล้างตัวกรองทั้งหมด"/"ล้างคำค้น" (เคารพ `preservedFilterIds`), **ว่างจริง** — `resourceName` ("ยังไม่มีใบสั่งซื้อ") + `emptyAction` (ปุ่มสร้าง; ไม่ส่ง = ไม่มีปุ่ม), **โหลด** — ตัวนับ "กำลังโหลด…" และ skeleton รายการ 3 บรรทัดบนมือถือ · กล่องสถานะกว้างไม่เกินจอบนมือถือ ปุ่มสูง 44px บนจอสัมผัส · `emptyStateComponent` ของแอปยังทับได้ทั้งหมด
+- `DataTableEmptyState`, `DataTableErrorState` (ภายใน `data-table-states.tsx`), `UiText.table.loading` / `emptyTitle` / `emptyTitleOf` / `emptyHint` / `noMatch` / `noMatchQuery` / `noMatchHint` / `clearAllFilters` / `clearQuery` / `errorTitle` / `errorHint` / `retry`
+- showcase: เดโม DataTable สลับสถานะ ปกติ/กำลังโหลด/ว่างจริง/ผิดพลาดได้
+
 ## [0.60.0] — 2026-10-24
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.60.0",
+  "version": "0.61.0",
   "private": false,
   "type": "module",
   "description": "Design system กลางของ Suphark apps: shadcn/ui (base-nova, Base UI, Tailwind v4) + shared components + token/ฟอนต์ Noto Sans Thai Looped — ส่งเป็น source ให้แอป Next transpile เอง",

package/src/components/data-table/data-table-states.tsx

@@ -0,0 +1,150 @@
+"use client";
+
+import { Button } from "@suphark/ui/components/shared/button/button";
+import { useUiText } from "@suphark/ui/components/shared/ui-text";
+import { cn } from "@suphark/ui/lib/utils";
+import type { Table } from "@tanstack/react-table";
+import { Inbox, SearchX, TriangleAlert } from "lucide-react";
+import type React from "react";
+
+/**
+ * กล่องสถานะกลางตาราง (ไม่พบ / ว่าง / ผิดพลาด) — บนมือถือจำกัดความกว้างเท่าจอ
+ * เพื่อไม่ให้ไปอยู่กลางตารางที่เลื่อนแนวนอน (sticky ที่ขอบซ้ายของกล่องเลื่อน)
+ */
+function StateBox({
+  icon,
+  title,
+  hint,
+  tone,
+  children,
+}: {
+  icon: React.ReactNode;
+  title: string;
+  hint?: string;
+  tone?: "danger";
+  children?: React.ReactNode;
+}) {
+  return (
+    <div
+      role={tone === "danger" ? "alert" : "status"}
+      className="sticky left-0 mx-auto flex w-[calc(100vw-3rem)] max-w-full flex-col items-center gap-1.5 px-4 py-8 text-center sm:w-auto"
+    >
+      <div
+        aria-hidden="true"
+        className={cn(
+          "flex size-10 items-center justify-center rounded-full [&_svg]:size-5",
+          tone === "danger"
+            ? "bg-destructive-subtle text-destructive-subtle-foreground"
+            : "bg-muted text-muted-foreground",
+        )}
+      >
+        {icon}
+      </div>
+      <h3 className="mt-1.5 font-semibold text-sm">{title}</h3>
+      {hint && <p className="max-w-[34ch] text-muted-foreground text-xs">{hint}</p>}
+      {children && (
+        <div className="mt-2 flex flex-wrap justify-center gap-2 [&_button]:pointer-coarse:h-11">
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** ไม่พบรายการ: มีตัวกรอง/คำค้นอยู่ → ล้างได้ทันที · ไม่มีเลย → ว่างจริง (+ปุ่มที่แอปส่งมา) */
+export function DataTableEmptyState<TData>({
+  table,
+  preservedFilterIds = [],
+  resourceName,
+  emptyAction,
+}: {
+  table: Table<TData>;
+  preservedFilterIds?: string[];
+  resourceName?: string;
+  emptyAction?: React.ReactNode;
+}) {
+  const text = useUiText();
+  const keep = new Set(preservedFilterIds);
+  const query = String(table.getState().globalFilter ?? "").trim();
+  const hasColumnFilters = table.getState().columnFilters.some((filter) => !keep.has(filter.id));
+  if (!query && !hasColumnFilters) {
+    return (
+      <StateBox
+        icon={<Inbox />}
+        title={
+          resourceName
+            ? (text.table?.emptyTitleOf ?? "ยังไม่มี{resource}").replace("{resource}", resourceName)
+            : (text.table?.emptyTitle ?? "ยังไม่มีรายการ")
+        }
+        hint={text.table?.emptyHint ?? "เมื่อสร้างแล้วจะแสดงที่นี่"}
+      >
+        {emptyAction}
+      </StateBox>
+    );
+  }
+  const clearQuery = () => table.setGlobalFilter("");
+  const clearAll = () => {
+    table.setColumnFilters((filters) => filters.filter((filter) => keep.has(filter.id)));
+    table.setGlobalFilter("");
+  };
+  return (
+    <StateBox
+      icon={<SearchX />}
+      title={
+        query
+          ? (text.table?.noMatchQuery ?? 'ไม่พบรายการที่ตรงกับ "{query}"').replace("{query}", query)
+          : (text.table?.noMatch ?? "ไม่พบรายการที่ตรงกัน")
+      }
+      hint={text.table?.noMatchHint ?? "ลองคำค้นอื่น หรือเอาตัวกรองออกบางตัว"}
+    >
+      <Button size="sm" onClick={clearAll}>
+        {text.table?.clearAllFilters ?? "ล้างตัวกรองทั้งหมด"}
+      </Button>
+      {query && hasColumnFilters && (
+        <Button size="sm" variant="outline" onClick={clearQuery}>
+          {text.table?.clearQuery ?? "ล้างคำค้น"}
+        </Button>
+      )}
+    </StateBox>
+  );
+}
+
+/** โหลดไม่สำเร็จ: ข้อความกลาง ๆ (ไม่แสดงข้อความดิบของระบบ) + ปุ่มลองใหม่เมื่อส่ง `onRetry` */
+export function DataTableErrorState({ onRetry }: { onRetry?: () => void }) {
+  const text = useUiText();
+  return (
+    <StateBox
+      tone="danger"
+      icon={<TriangleAlert />}
+      title={text.table?.errorTitle ?? "โหลดรายการไม่สำเร็จ"}
+      hint={text.table?.errorHint ?? "การเชื่อมต่อขัดข้อง ลองใหม่อีกครั้ง"}
+    >
+      {onRetry && (
+        <Button size="sm" onClick={onRetry}>
+          {text.table?.retry ?? "ลองใหม่"}
+        </Button>
+      )}
+    </StateBox>
+  );
+}
+
+/** skeleton ของรายการมือถือ (แถวละ 3 บรรทัด) ระหว่างโหลด */
+export function QuietMobileSkeleton({ rows }: { rows: number }) {
+  const text = useUiText();
+  return (
+    <ul
+      aria-busy="true"
+      aria-label={text.table?.loading ?? "กำลังโหลด…"}
+      className="divide-y overflow-hidden rounded-xl border bg-card sm:hidden"
+    >
+      {Array.from({ length: Math.min(rows, 5) }).map((_, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: แถว skeleton ไม่มีตัวตน ใช้ตำแหน่งเป็น key ได้
+        <li key={i} className="flex flex-col gap-2 px-4 py-3">
+          <div className="h-3 w-1/2 animate-pulse rounded bg-muted" />
+          <div className="h-3 w-4/5 animate-pulse rounded bg-muted" />
+          <div className="h-3 w-1/3 animate-pulse rounded bg-muted" />
+        </li>
+      ))}
+    </ul>
+  );
+}

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

@@ -40,6 +40,8 @@ interface DataTableToolbarProps<TData> {
   variant?: "default" | "quiet";
   density?: "comfortable" | "compact";
   onDensityChange?: (density: "comfortable" | "compact") => void;
+  /** `quiet`: ตัวนับแสดง "กำลังโหลด…" */
+  isLoading?: boolean;
 }
 
 export function DataTableToolbar<TData>({
@@ -52,6 +54,7 @@ export function DataTableToolbar<TData>({
   variant = "default",
   density = "comfortable",
   onDensityChange,
+  isLoading,
 }: DataTableToolbarProps<TData>) {
   const text = useUiText();
   const isMobile = useIsMobile();
@@ -280,9 +283,11 @@ export function DataTableToolbar<TData>({
         })}
         <div className="ml-auto flex items-center gap-1">
           <span className="me-1 text-muted-foreground text-xs tabular-nums">
-            {(text.table?.shownOf ?? "{shown} จาก {total} รายการ")
-              .replace("{shown}", String(shown))
-              .replace("{total}", String(total))}
+            {isLoading
+              ? (text.table?.loading ?? "กำลังโหลด…")
+              : (text.table?.shownOf ?? "{shown} จาก {total} รายการ")
+                  .replace("{shown}", String(shown))
+                  .replace("{total}", String(total))}
           </span>
           {actionsComponent}
           {onDensityChange && (

package/src/components/data-table/data-table.tsx

@@ -15,6 +15,7 @@ import { cn } from "@suphark/ui/lib/utils";
 import { flexRender } from "@tanstack/react-table";
 import * as React from "react";
 import { DataTablePagination } from "./data-table-pagination";
+import { DataTableEmptyState, DataTableErrorState, QuietMobileSkeleton } from "./data-table-states";
 import { DataTableToolbar } from "./data-table-toolbar";
 import type { DataTableMobileSlot, DataTableProps } from "./types";
 import { useDataTable } from "./use-data-table";
@@ -86,6 +87,10 @@ export function DataTable<TData, TValue>({
   defaultDensity = "comfortable",
   selectionActions,
   densityStorageKey,
+  resourceName,
+  emptyAction,
+  error,
+  onRetry,
 }: DataTableProps<TData, TValue>) {
   const text = useUiText();
   const quiet = variant === "quiet";
@@ -193,7 +198,13 @@ export function DataTable<TData, TValue>({
         ))}
       </TableHeader>
       <TableBody>
-        {isLoading ? (
+        {error ? (
+          <TableRow>
+            <TableCell colSpan={table.getVisibleLeafColumns().length}>
+              <DataTableErrorState onRetry={onRetry} />
+            </TableCell>
+          </TableRow>
+        ) : isLoading ? (
           Array.from({ length: initialPageSize }).map((_, i) => (
             // biome-ignore lint/suspicious/noArrayIndexKey: แถว skeleton ไม่มีตัวตน ใช้ตำแหน่งเป็น key ได้
             <TableRow key={i}>
@@ -246,7 +257,17 @@ export function DataTable<TData, TValue>({
         ) : (
           <TableRow>
             <TableCell colSpan={table.getVisibleLeafColumns().length} className="h-24 text-center">
-              {emptyStateComponent || (text.table?.noResults ?? "ไม่พบข้อมูล")}
+              {emptyStateComponent ||
+                (quiet ? (
+                  <DataTableEmptyState
+                    table={table}
+                    preservedFilterIds={preservedFilterIds}
+                    resourceName={resourceName}
+                    emptyAction={emptyAction}
+                  />
+                ) : (
+                  (text.table?.noResults ?? "ไม่พบข้อมูล")
+                ))}
             </TableCell>
           </TableRow>
         )}
@@ -258,8 +279,10 @@ export function DataTable<TData, TValue>({
     .getAllLeafColumns()
     .some((column) => (column.columnDef.meta as { mobile?: string } | undefined)?.mobile);
   const mobileList =
-    quiet && hasMobileSlots && !isLoading && table.getRowModel().rows.length > 0 ? (
+    quiet && hasMobileSlots && !isLoading && !error && table.getRowModel().rows.length > 0 ? (
       <QuietMobileList table={table} />
+    ) : quiet && hasMobileSlots && isLoading && !error ? (
+      <QuietMobileSkeleton rows={initialPageSize} />
     ) : null;
 
   const customView = renderCustomView?.(table);
@@ -280,6 +303,7 @@ export function DataTable<TData, TValue>({
           variant={variant}
           density={density}
           onDensityChange={setDensity}
+          isLoading={isLoading}
         />
       )}
       {customView ? (
@@ -321,7 +345,7 @@ export function DataTable<TData, TValue>({
               renderTable(false)
             )}
           </div>
-          {showPagination && (
+          {showPagination && !error && (
             <div
               className={
                 stickyPagination

package/src/components/data-table/types.ts

@@ -122,6 +122,14 @@ export interface DataTableProps<TData, TValue> {
    * ไม่ส่ง = ไม่จำ (กลับเป็น `defaultDensity` ทุกครั้ง) · localStorage ใช้ไม่ได้ก็ทำงานต่อโดยไม่จำ
    */
   densityStorageKey?: string;
+  /** ชื่อชนิดข้อมูลสำหรับสถานะว่าง เช่น "ใบสั่งซื้อ" → "ยังไม่มีใบสั่งซื้อ" (`quiet`) */
+  resourceName?: string;
+  /** `quiet`: ปุ่ม/ลิงก์ในสถานะ "ว่างจริง" (ไม่มีข้อมูลและไม่มีตัวกรอง) เช่น ปุ่ม "สร้างใบสั่งซื้อ" — ไม่ส่ง = ไม่มีปุ่ม */
+  emptyAction?: React.ReactNode;
+  /** โหลดไม่สำเร็จ: แสดงสถานะผิดพลาดแทนตาราง (ทั้งสอง variant) — ข้อความกลาง ๆ ไม่แสดง error ดิบ */
+  error?: boolean;
+  /** ปุ่ม "ลองใหม่" ของสถานะผิดพลาด — ไม่ส่ง = ไม่มีปุ่ม */
+  onRetry?: () => void;
   /** `quiet`: ปุ่มคำสั่งในแคปซูลเลือกหมู่ (ส่งออก/ลบ …) — ไม่ส่ง = แคปซูลมีแค่จำนวนที่เลือกและปุ่มล้าง */
   selectionActions?: (table: Table<TData>) => React.ReactNode;
 }

package/src/components/shared/ui-text.tsx

@@ -87,6 +87,19 @@ export interface UiText {
     density: string;
     /** `variant="quiet"` มือถือ — `{count}` */
     selectedCount: string;
+    /** สถานะตาราง: `emptyTitleOf` ใช้ `{resource}`, `noMatchQuery` ใช้ `{query}` */
+    loading: string;
+    emptyTitle: string;
+    emptyTitleOf: string;
+    emptyHint: string;
+    noMatch: string;
+    noMatchQuery: string;
+    noMatchHint: string;
+    clearAllFilters: string;
+    clearQuery: string;
+    errorTitle: string;
+    errorHint: string;
+    retry: string;
     /** ข้อความในแคปซูลเลือกหมู่ (สั้นกว่า `selectedCount` เพราะหัวรายการมือถือบอก "เลือก N รายการ" อยู่แล้ว) */
     selectedPill: string;
     selectAll: string;
@@ -332,6 +345,18 @@ export const UI_TEXT_TH: UiText = {
     shownOf: "{shown} จาก {total} รายการ",
     density: "ความหนาแน่นของแถว",
     selectedCount: "เลือก {count} รายการ",
+    loading: "กำลังโหลด…",
+    emptyTitle: "ยังไม่มีรายการ",
+    emptyTitleOf: "ยังไม่มี{resource}",
+    emptyHint: "เมื่อสร้างแล้วจะแสดงที่นี่",
+    noMatch: "ไม่พบรายการที่ตรงกัน",
+    noMatchQuery: 'ไม่พบรายการที่ตรงกับ "{query}"',
+    noMatchHint: "ลองคำค้นอื่น หรือเอาตัวกรองออกบางตัว",
+    clearAllFilters: "ล้างตัวกรองทั้งหมด",
+    clearQuery: "ล้างคำค้น",
+    errorTitle: "โหลดรายการไม่สำเร็จ",
+    errorHint: "การเชื่อมต่อขัดข้อง ลองใหม่อีกครั้ง",
+    retry: "ลองใหม่",
     selectedPill: "{count} รายการ",
     selectAll: "เลือกทั้งหมด",
     longPressHint: "กดค้างที่แถวเพื่อเลือกหมู่",
@@ -555,6 +580,18 @@ export const UI_TEXT_EN: UiText = {
     shownOf: "{shown} of {total} items",
     density: "Row density",
     selectedCount: "{count} selected",
+    loading: "Loading…",
+    emptyTitle: "Nothing here yet",
+    emptyTitleOf: "No {resource} yet",
+    emptyHint: "Items will show up here once created.",
+    noMatch: "No matching items",
+    noMatchQuery: 'No items match "{query}"',
+    noMatchHint: "Try another search, or remove some filters.",
+    clearAllFilters: "Clear all filters",
+    clearQuery: "Clear search",
+    errorTitle: "Couldn't load the list",
+    errorHint: "The connection dropped. Try again.",
+    retry: "Try again",
     selectedPill: "{count} items",
     selectAll: "Select all",
     longPressHint: "Press and hold a row to select several",