@suphark/ui 0.60.0 → 0.62.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.62.0] — 2026-10-24
+
+### Added
+- `SimpleTable variant="quiet"` (opt-in, ค่าเริ่มต้น `default` เหมือนเดิม — เข้าชุดกับ `DataTable variant="quiet"`): หัวตารางเรียบ · แถวพื้นตอนชี้ · แถวที่เลือกมีแถบสีซ้าย · `StatusBadge` เป็นจุดสี · ช่องติ๊กและปุ่มท้ายแถว (คอลัมน์ที่ `key: "actions"`) โผล่เมื่อชี้/โฟกัส (จอสัมผัสเห็นตลอด)
+- `SimpleTableColumn.mobile` (`QuietMobileSlot` = `title | end | sub | status | meta | hidden`): บนจอ < sm ของ `quiet` แสดงเป็นรายการแถวละ 3 บรรทัดแทนตารางเลื่อนแนวนอน (ช่องติ๊กอยู่ซ้ายรายการ พื้นที่แตะ 44px) · ไม่ใส่ slot ใดเลย = ตารางเหมือนเดิม
+- `SimpleTable isLoading` (skeleton), `error` + `onRetry` (กล่องผิดพลาดแบบเดียวกับ DataTable) — ใช้ได้ทั้งสอง variant · `empty` เดิมของแอปยังใช้เหมือนเดิม
+- `QuietMobileSlot` (type), ภายใน: `shared/table-states.tsx` (กล่องสถานะ/skeleton ที่ DataTable ใช้ร่วมกัน ไม่พึ่ง tanstack)
+
+## [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.62.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,71 @@
+"use client";
+
+import { Button } from "@suphark/ui/components/shared/button/button";
+import { TableStateBox as StateBox } from "@suphark/ui/components/shared/table-states";
+import { useUiText } from "@suphark/ui/components/shared/ui-text";
+import type { Table } from "@tanstack/react-table";
+import { Inbox, SearchX } from "lucide-react";
+import type React from "react";
+
+/** ไม่พบรายการ: มีตัวกรอง/คำค้นอยู่ → ล้างได้ทันที · ไม่มีเลย → ว่างจริง (+ปุ่มที่แอปส่งมา) */
+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>
+  );
+}
+
+export {
+  QuietMobileSkeleton,
+  TableErrorState as DataTableErrorState,
+} from "@suphark/ui/components/shared/table-states";

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/quiet-table.ts

@@ -0,0 +1,5 @@
+/** ตำแหน่งของคอลัมน์ในรายการมือถือของตาราง `variant="quiet"` (ชนิดเดียวกับ `DataTableMobileSlot`) */
+export type QuietMobileSlot = "title" | "end" | "sub" | "status" | "meta" | "hidden";
+
+/** ลำดับบรรทัดของรายการมือถือ (`meta` ต่อท้าย `status`, `end` ต่อท้าย `title`) */
+export const QUIET_MOBILE_SLOT_ORDER: QuietMobileSlot[] = ["title", "end", "sub", "status", "meta"];

package/src/components/shared/simple-table.tsx

@@ -12,6 +12,8 @@ import {
 import { cn } from "@suphark/ui/lib/utils";
 import type { ReactNode } from "react";
 import { EmptyRow } from "./empty-row";
+import { QUIET_MOBILE_SLOT_ORDER, type QuietMobileSlot } from "./quiet-table";
+import { QuietMobileSkeleton, TableErrorState } from "./table-states";
 
 export interface SimpleTableColumn<T> {
   /** key ของคอลัมน์ — ถ้าตรงกับ field ของแถวและไม่ส่ง cell จะแสดงค่านั้นตรง ๆ */
@@ -21,6 +23,12 @@ export interface SimpleTableColumn<T> {
   align?: "left" | "center" | "right";
   /** class ของทั้งหัวและเซลล์ เช่น "w-32" หรือ "hidden md:table-cell" (ซ่อนบนมือถือ) */
   className?: string;
+  /**
+   * `variant="quiet"` บนจอ < sm: ตำแหน่งในรายการแถวละ 3 บรรทัด (`title` ชื่อ · `end` ยอดต่อท้ายชื่อ · `sub` บรรทัดรอง ·
+   * `status` สถานะ · `meta` ข้อความเล็กต่อท้ายสถานะ · `hidden` ไม่แสดง) — ไม่ใส่ slot ใดเลย = ตารางเลื่อนแนวนอนเหมือนเดิม
+   * คอลัมน์ที่ `key === "actions"` ถือเป็นปุ่มท้ายแถว (quiet: โผล่เมื่อชี้/โฟกัส)
+   */
+  mobile?: QuietMobileSlot;
 }
 
 /**
@@ -45,6 +53,10 @@ export function SimpleTable<T>({
   selectAllLabel = "เลือกทั้งหมด",
   caption,
   className,
+  variant = "default",
+  isLoading,
+  error,
+  onRetry,
 }: {
   columns: ReadonlyArray<SimpleTableColumn<T>>;
   rows: ReadonlyArray<T>;
@@ -62,7 +74,21 @@ export function SimpleTable<T>({
   /** คำอธิบายตารางสำหรับ screen reader (sr-only) */
   caption?: string;
   className?: string;
+  /**
+   * `quiet` = หัวเรียบ แถวเรียบ สถานะเป็นจุดสี ช่องติ๊ก/ปุ่มท้ายแถว (`key: "actions"`) โผล่เมื่อชี้ (จอสัมผัสเห็นตลอด)
+   * และรายการบนมือถือผ่าน `columns[].mobile` — เข้าชุดกับ `DataTable variant="quiet"`
+   */
+  variant?: "default" | "quiet";
+  /** แสดง skeleton แทนแถว */
+  isLoading?: boolean;
+  /** โหลดไม่สำเร็จ: แสดงกล่องผิดพลาดแทนแถว (ข้อความกลาง ไม่แสดง error ดิบ) */
+  error?: boolean;
+  /** ปุ่ม "ลองใหม่" ของกล่องผิดพลาด — ไม่ส่ง = ไม่มีปุ่ม */
+  onRetry?: () => void;
 }) {
+  const quiet = variant === "quiet";
+  const hasMobileSlots = quiet && columns.some((c) => c.mobile);
+  const hasRows = rows.length > 0 && !isLoading && !error;
   const alignClass = (a?: "left" | "center" | "right") =>
     a === "right" ? "text-right tabular-nums" : a === "center" ? "text-center" : undefined;
 
@@ -78,8 +104,18 @@ export function SimpleTable<T>({
     else next.delete(key);
     onSelectedChange?.([...next]);
   }
-  return (
-    <div className={cn("overflow-hidden rounded-xl border bg-card", className)}>
+  const tableColSpan = columns.length + (selectable ? 1 : 0);
+  const showMobileList = hasMobileSlots && hasRows;
+  const showMobileSkeleton = hasMobileSlots && Boolean(isLoading) && !error;
+  const body = (
+    <div
+      className={cn(
+        "overflow-hidden rounded-xl border bg-card",
+        quiet && QUIET_SIMPLE_TABLE,
+        (showMobileList || showMobileSkeleton) && "max-sm:hidden",
+        className,
+      )}
+    >
       <Table>
         {caption && <caption className="sr-only">{caption}</caption>}
         <TableHeader>
@@ -104,8 +140,26 @@ export function SimpleTable<T>({
           </TableRow>
         </TableHeader>
         <TableBody>
-          {rows.length === 0 ? (
-            <EmptyRow colSpan={columns.length + (selectable ? 1 : 0)}>{empty}</EmptyRow>
+          {error ? (
+            <TableRow>
+              <TableCell colSpan={tableColSpan}>
+                <TableErrorState onRetry={onRetry} />
+              </TableCell>
+            </TableRow>
+          ) : isLoading ? (
+            Array.from({ length: 3 }).map((_, i) => (
+              // biome-ignore lint/suspicious/noArrayIndexKey: แถว skeleton ไม่มีตัวตน ใช้ตำแหน่งเป็น key ได้
+              <TableRow key={i}>
+                {Array.from({ length: tableColSpan }).map((_cell, j) => (
+                  // biome-ignore lint/suspicious/noArrayIndexKey: เซลล์ skeleton เช่นกัน
+                  <TableCell key={j}>
+                    <div className="h-4 w-full animate-pulse rounded bg-muted" />
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))
+          ) : rows.length === 0 ? (
+            <EmptyRow colSpan={tableColSpan}>{empty}</EmptyRow>
           ) : (
             rows.map((row, i) => (
               <TableRow
@@ -126,7 +180,11 @@ export function SimpleTable<T>({
                   </TableCell>
                 )}
                 {columns.map((c) => (
-                  <TableCell key={c.key} className={cn(alignClass(c.align), c.className)}>
+                  <TableCell
+                    key={c.key}
+                    data-slot={c.key === "actions" ? "simple-table-row-actions" : undefined}
+                    className={cn(alignClass(c.align), c.className)}
+                  >
                     {c.cell
                       ? c.cell(row, i)
                       : String((row as Record<string, unknown>)[c.key] ?? "")}
@@ -139,4 +197,131 @@ export function SimpleTable<T>({
       </Table>
     </div>
   );
+  if (!quiet) return body;
+  return (
+    <div data-variant="quiet" className="flex flex-col gap-2">
+      {showMobileList && (
+        <QuietSimpleMobileList
+          columns={columns}
+          rows={rows}
+          getRowKey={getRowKey}
+          selectable={selectable}
+          selectedKeys={selectedKeys}
+          selectLabel={selectLabel}
+          toggleRow={toggleRow}
+          onRowClick={onRowClick}
+        />
+      )}
+      {showMobileSkeleton && <QuietMobileSkeleton rows={3} />}
+      {body}
+    </div>
+  );
+}
+
+/** `variant="quiet"`: สไตล์ผ่านตัวเลือก CSS (ไม่แตะ markup ของเซลล์ที่แอปส่งมา) — ชุดเดียวกับ `DataTable` quiet */
+const QUIET_SIMPLE_TABLE = [
+  "shadow-none",
+  "[&_thead]:bg-muted/40 [&_th]:h-9 [&_th]:font-semibold [&_th]:text-label [&_th]:text-muted-foreground",
+  "[&_tbody_tr]:hover:bg-muted/40",
+  "[&_tbody_tr[data-selected]]:bg-primary/[0.07] [&_tbody_tr[data-selected]]:shadow-[inset_3px_0_0_var(--primary)]",
+  "[@media(hover:hover)]:[&_tbody_tr:not(:hover):not(:focus-within):not([data-selected])_[role=checkbox]]:opacity-0",
+  "[@media(hover:hover)]:[&_tbody_tr:not(:hover):not(:focus-within)_[data-slot=simple-table-row-actions]]:opacity-0",
+  "[&_[role=checkbox]]:transition-opacity [&_[data-slot=simple-table-row-actions]]:transition-opacity",
+  "[&_td]:py-2.5",
+].join(" ");
+
+function QuietSimpleMobileList<T>({
+  columns,
+  rows,
+  getRowKey,
+  selectable,
+  selectedKeys,
+  selectLabel,
+  toggleRow,
+  onRowClick,
+}: {
+  columns: ReadonlyArray<SimpleTableColumn<T>>;
+  rows: ReadonlyArray<T>;
+  getRowKey: (row: T, index: number) => string | number;
+  selectable: boolean;
+  selectedKeys: Set<string | number>;
+  selectLabel: string;
+  toggleRow: (key: string | number, checked: boolean) => void;
+  onRowClick?: (row: T) => void;
+}) {
+  const pick = (slot: QuietMobileSlot) => columns.filter((c) => c.mobile === slot);
+  const render = (c: SimpleTableColumn<T>, row: T, i: number) => (
+    <span key={c.key}>
+      {c.cell ? c.cell(row, i) : String((row as Record<string, unknown>)[c.key] ?? "")}
+    </span>
+  );
+  return (
+    <ul className="divide-y overflow-hidden rounded-xl border bg-card sm:hidden">
+      {rows.map((row, i) => {
+        const key = getRowKey(row, i);
+        const isSelected = selectedKeys.has(key);
+        return (
+          <li
+            key={key}
+            data-selected={isSelected || undefined}
+            onClick={onRowClick ? () => onRowClick(row) : undefined}
+            className={cn(
+              "flex items-start gap-3 px-4 py-2.5 data-selected:bg-primary/[0.07] data-selected:shadow-[inset_3px_0_0_var(--primary)]",
+              onRowClick && "cursor-pointer",
+            )}
+          >
+            {selectable && (
+              // ขยายพื้นที่แตะรอบช่องติ๊ก 16px เป็น 44px
+              <div className="-m-3.5 -mt-3 shrink-0 p-3.5">
+                <Checkbox
+                  aria-label={selectLabel}
+                  checked={isSelected}
+                  onCheckedChange={(checked) => toggleRow(key, checked === true)}
+                  onClick={(event) => event.stopPropagation()}
+                />
+              </div>
+            )}
+            <div className="flex min-w-0 flex-1 flex-col gap-0.5">
+              {QUIET_MOBILE_SLOT_ORDER.map((slot) => {
+                const found = pick(slot);
+                if (slot === "meta" || slot === "end" || found.length === 0) return null;
+                if (slot === "title") {
+                  return (
+                    <div
+                      key={slot}
+                      className="flex items-baseline justify-between gap-2 font-semibold text-sm"
+                    >
+                      <span className="min-w-0 truncate">
+                        {found.map((c) => render(c, row, i))}
+                      </span>
+                      <span className="shrink-0 tabular-nums">
+                        {pick("end").map((c) => render(c, row, i))}
+                      </span>
+                    </div>
+                  );
+                }
+                if (slot === "sub") {
+                  return (
+                    <div key={slot} className="truncate text-muted-foreground text-sm">
+                      {found.map((c) => render(c, row, i))}
+                    </div>
+                  );
+                }
+                return (
+                  <div key={slot} className="flex items-center gap-1.5 text-xs">
+                    {found.map((c) => render(c, row, i))}
+                    {pick("meta").map((c) => (
+                      <span key={c.key} className="text-muted-foreground">
+                        · {render(c, row, i)}
+                      </span>
+                    ))}
+                  </div>
+                );
+              })}
+            </div>
+          </li>
+        );
+      })}
+    </ul>
+  );
 }

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

@@ -0,0 +1,91 @@
+"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 { TriangleAlert } from "lucide-react";
+import type React from "react";
+
+/**
+ * กล่องสถานะกลางตาราง (ไม่พบ / ว่าง / ผิดพลาด) — บนมือถือจำกัดความกว้างเท่าจอ
+ * เพื่อไม่ให้ไปอยู่กลางตารางที่เลื่อนแนวนอน (sticky ที่ขอบซ้ายของกล่องเลื่อน)
+ */
+export function TableStateBox({
+  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>
+  );
+}
+
+/** โหลดไม่สำเร็จ: ข้อความกลาง ๆ (ไม่แสดงข้อความดิบของระบบ) + ปุ่มลองใหม่เมื่อส่ง `onRetry` */
+export function TableErrorState({ onRetry }: { onRetry?: () => void }) {
+  const text = useUiText();
+  return (
+    <TableStateBox
+      tone="danger"
+      icon={<TriangleAlert />}
+      title={text.table?.errorTitle ?? "โหลดรายการไม่สำเร็จ"}
+      hint={text.table?.errorHint ?? "การเชื่อมต่อขัดข้อง ลองใหม่อีกครั้ง"}
+    >
+      {onRetry && (
+        <Button size="sm" onClick={onRetry}>
+          {text.table?.retry ?? "ลองใหม่"}
+        </Button>
+      )}
+    </TableStateBox>
+  );
+}
+
+/** 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/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",

package/src/index.ts

@@ -210,6 +210,7 @@ export { PageHeader } from "./components/shared/page-header";
 export { PageSkeleton } from "./components/shared/page-skeleton";
 export { type Presence, PresenceDot } from "./components/shared/presence-dot";
 export { ProgressBar, type ProgressTone } from "./components/shared/progress-bar";
+export type { QuietMobileSlot } from "./components/shared/quiet-table";
 export {
   type RecordAccent,
   RecordCard,