@suphark/ui 0.19.0 → 0.20.1

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.20.1] — 2026-10-01
+
+### Fixed
+
+- **`confirm.requireText` ถูกทิ้งเงียบ ๆ** (รายงานจาก Pi Config): `RowActions`, `ConfirmActionButton` และ `ActionMenu` ส่งให้ `ConfirmDialog` แค่ title/description/label/destructive — ใส่ `confirm: { requireText: slug }` แล้วลบได้ด้วยคลิกเดียวทั้งที่ `ConfirmSpec` ประกาศว่ารองรับ → ส่ง `requireText` + `requireTextLabel` ต่อครบทั้งสามที่; tests 2 กรณี (รวม 185)
+
+## [0.20.0] — 2026-10-01
+
+ขั้น "layout" ของแผนรวม UI ทุกแอป (ดู `todo/todo.md`) — เพิ่มอย่างเดียว ไม่มี prop เดิมเปลี่ยนความหมาย
+
+### Added
+
+- **`MobileTabBar`** (`/next`) + **`AppShell mobileTabs`** — แถบเมนูล่างของมือถือ 3–5 แท็บ (ยกจาก DueBell `MobileNav`): ซ่อนตั้งแต่ `md`, แท็บสูง ≥ 56px, `badge` เป็น `CountBadge` บนไอคอน (รวมใน aria-label), `onClick` แทนการไปหน้า, ไฮไลต์ตาม path (`/` ตรงตัว, อื่น ๆ prefix หรือ `exact`); `icon` เป็น **element** (`<Home />`) จึงส่งจาก server layout ได้เหมือน `AppNav`; `AppShell` ทั้ง layout sidebar/top เว้นที่ใต้เนื้อหาให้เอง
+- utility **`pb-safe`** (safe-area ล่างของ iPhone) และ **`pb-tab-bar`** (เว้นที่ให้พ้นแถบล่าง) ใน `styles.css`
+- **`SettingsLayout`** — หน้าตั้งค่าหลายหัวข้อ (ยกจาก DueBell master-detail + PDF ค้นหาได้): จอกว้างสารบัญซ้าย sticky + เนื้อหา, มือถือรายการหัวข้อ → หน้าหัวข้อ + ปุ่ม "กลับ" (ย้ายโฟกัสไปหัวข้อให้ screen reader), `searchable` ค้น label/description/`keywords` (ไทย+อังกฤษ), `badge` ท้ายรายการ, คุมเองด้วย `value`/`onValueChange` หรือ `initialSection`
+- **`FilterBar`** — แถบค้นหา + select ตัวกรองเหนือรายการ client-side (Pi Auth เขียนซ้ำ 14 หน้า): ปุ่ม "ล้างตัวกรอง" โผล่เมื่อมีค่าค้าง (เทียบกับ `allValue` ของแต่ละตัว) และตั้งกลับให้เองถ้าไม่ส่ง `onClear`; ตัวกรองแบบอื่นใส่เป็น `children` + `active`
+- **`SetupChecklist`** — รายการ "ต้องตั้งอะไรให้ครบ" (ยกจาก Pi Auth `SetupSteps`): ✓ เมื่อทำแล้ว, ขั้นบังคับถัดไปถูกเน้น (`aria-current="step"`), ขั้น `optional` ไม่นับ, ครบแล้วซ่อนทั้งกล่อง (`hideWhenComplete`); `action` รับ `{ current, done }` ให้แอปส่ง `LinkButton` เอง (barrel ไม่พึ่ง next)
+- **`MonthStepper`** + **`useMonthCursor`** — เลือกเดือน ‹ เดือน › กดชื่อเดือนกลับเดือนนี้, `min`/`max`, `locale` (`th-TH` = พ.ศ., `th-TH-u-ca-gregory` = ค.ศ.), `format` long|short, `formatLabel` (ยกจาก DueBell `MonthSelector`)
+- **`lib/month.ts`** (barrel): `MonthKey` (`"YYYY-MM"` แบบเดียวกับ `CalendarMonthGrid`), `parseMonthKey`, `isMonthKey`, `toMonthKey`, `currentMonthKey`, `shiftMonth` (ข้ามปีให้), `compareMonth`, `formatMonthKey` — แทน `CycleMonth` ของ DueBell
+- `UiText` key ใหม่ (optional ทั้งหมด มีค่าไทย/อังกฤษใน `UI_TEXT_TH`/`UI_TEXT_EN`): `month`, `setup`, `filters`, `settings`, `mobileTabs`
+- **ชุด component สำเร็จรูป (Simple\*)** — ทิศทางของแพ็กเกจ: แอปเขียน component เดียว + props แทนการประกอบ primitive หลายชิ้นซ้อนกันแบบ shadcn (ดู `docs/agent-rules.md` "ใช้ตัวสำเร็จรูปก่อน"):
+  - `SimpleDialog` (แทน Dialog 7 ชิ้น) / `SimpleSheet` (+ `side`) — trigger, title, description, children, `footer` (ReactNode หรือ `(close) => …`), `size`, controlled ได้; **ปุ่ม X อ่าน `UiText.close`** แก้ปัญหา "Close" แปลภาษาไม่ได้โดยไม่แตะไฟล์ shadcn
+  - `SimpleTabs` (items: value/label/content/icon/badge/disabled, `variant` default|line, `fullWidth`) / `SimpleAccordion` (`multiple`, `initialOpen`)
+  - `SimpleTooltip` (ห่อ element เดียว, content ว่าง = ไม่มี tooltip) / `SimplePopover` (trigger + title/description + เนื้อหา)
+  - `ActionMenu` — เมนูคำสั่งจาก array: icon, shortcut, separator, label, href/external, destructive, **`confirm` เปิด `ConfirmDialog` ก่อนเรียก onClick**; trigger ไม่ส่ง = ปุ่ม …
+  - `SimplePagination` + `paginationRange` — page/pageCount/onPageChange, จำนวนปุ่มคงที่, มือถือเหลือ "x / y"
+  - `SimpleTable<T>` — columns (key/header/cell/align/className) + rows + getRowKey + empty + onRowClick; ค่าจาก key ตรง ๆ ถ้าไม่ส่ง cell
+  - `SegmentedControl<T>` — เลือกทีละหนึ่งและต้องมีค่าเสมอ (กดตัวเดิมไม่หลุด), `count`, `icon`, `size`, `fullWidth`
+  - `UiText` key ใหม่: `close`, `pagination`
+- **shadcn/ui base-nova ล่าสุดทั้งชุด** (`shadcn add --all --overwrite`, CLI 4.21.0): primitive ใหม่ `bubble`, `marker`, `message`, `message-scroller`, `questionnaire`, `direction` (export ใน barrel) และ `toast` (Base UI — **ไม่อยู่ใน barrel** เพราะชื่อ `toast`/`Toaster` ชนกับ sonner ที่แพ็กเกจใช้; import จาก `@suphark/ui/components/ui/toast`); dep ใหม่ `@shadcn/react`
+  - ไฟล์เดิมได้ class/ลำดับจาก upstream (ส่วนใหญ่เรียง class ใหม่) + sidebar deps ของ useEffect/useMemo ครบขึ้น
+  - **คงของที่แก้ไว้เอง** (ติดมาจาก supplychain ตั้งแต่ 0.1.0 — upstream ยังไม่มี): `scroll-area.tsx` (`data-[orientation=…]` ของ Base UI — ไม่งั้นแถบเลื่อนกว้าง 0 มองไม่เห็นทั้งแอป), `slider.tsx`, `tabs.tsx` (orientation แบบเดียวกัน), `table.tsx` (prop `containerClassName`)
+  - CLI รุ่นนี้เขียน `import { cn } from "cn"` — เปลี่ยนกลับเป็น `@suphark/ui/lib/utils` ทุกไฟล์ เพราะ `cn` ของแพ็กเกจรู้จักคลาสตามบทบาท (`text-body` ฯลฯ, 0.13.1) ส่วน `cn` ทั่วไปจะลบทิ้งเงียบ ๆ
+  - `hooks/use-mobile.ts` (CLI เขียนทับ) เติม `"use client"` คืน; biome ปิด `noDoubleEquals` เฉพาะ `components/ui/**` (`field.tsx` ของ upstream ใช้ `==`)
+- showcase: หน้า `/components/{month-stepper,filter-bar,setup-checklist,settings-layout,mobile-tab-bar,simple-dialog,simple-sheet,simple-tabs,simple-accordion,simple-tooltip,simple-popover,action-menu,simple-pagination,simple-table,segmented-control}` (118 หน้า) + `/shell` มี `mobileTabs` ให้ลองบนจอมือถือ; tests 20 กรณีเพิ่ม (รวม 183)
+
 ## [0.19.0] — 2026-09-30
 
 ปิดรายการ "component เล็กที่ใช้ร่วม" ของแผนรวม UI ทุกแอป (ดู `todo/todo.md`) — เพิ่มอย่างเดียว ไม่มี prop เดิมเปลี่ยนความหมาย

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "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 เอง",
@@ -54,11 +54,21 @@
     "./hooks/*": "./src/hooks/*.ts",
     "./package.json": "./package.json"
   },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "audit": "node scripts/audit.mjs src --important",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint:base-ui": "node scripts/audit-base-ui-props.mjs",
+    "check:typography": "node scripts/audit-tailwind-typography.mjs",
+    "verify": "pnpm typecheck && pnpm lint:base-ui && pnpm check:typography && pnpm test"
+  },
   "dependencies": {
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
     "@fontsource/noto-sans-thai-looped": "^5.3.0",
+    "@shadcn/react": "^0.3.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
@@ -67,7 +77,7 @@
     "embla-carousel-react": "^8.6.0",
     "input-otp": "^1.5.0",
     "next-themes": "^0.4.6",
-    "react-day-picker": "^10.0.1",
+    "react-day-picker": "^10.0.2",
     "react-number-format": "^5.4.5",
     "react-resizable-panels": "^4.12.3",
     "sonner": "^2.0.8",
@@ -112,18 +122,9 @@
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
     "react-hook-form": "^7.86.0",
-    "recharts": "^3.10.1",
+    "recharts": "^3.8.0",
     "tailwindcss": "^4.3.3",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit",
-    "audit": "node scripts/audit.mjs src --important",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint:base-ui": "node scripts/audit-base-ui-props.mjs",
-    "check:typography": "node scripts/audit-tailwind-typography.mjs",
-    "verify": "pnpm typecheck && pnpm lint:base-ui && pnpm check:typography && pnpm test"
   }
-}
+}

package/src/components/app-shell/app-shell.tsx

@@ -35,6 +35,7 @@ import { AppBrand, type AppBrandProps } from "./app-brand";
 import { AppNav, type AppNavPinProps } from "./app-nav";
 import { HeaderBreadcrumbs, type HeaderBreadcrumbsProps } from "./header-breadcrumbs";
 import { HeaderCrumbs } from "./header-crumb";
+import { MobileTabBar, type MobileTabItem } from "./mobile-tab-bar";
 import { SubNav } from "./sub-nav";
 import { isTabActive, TopTabs, topLevelTabs } from "./top-tabs";
 import { type AppNavGroup, searchNav } from "./types";
@@ -102,6 +103,11 @@ export interface AppShellProps {
   contentClassName?: string;
   /** จำกัดความกว้างเนื้อหา เช่น `max-w-5xl` (Pi Auth) — ไม่ส่ง = เต็มจอ (supplychain) */
   contentMaxWidth?: string;
+  /**
+   * แถบเมนูล่างบนมือถือ (< md) 3–5 แท็บ — เว้นที่ใต้เนื้อหาให้เอง; เดสก์ท็อปยังใช้ sidebar/แท็บบนตามเดิม
+   * (ยกจาก DueBell MobileNav)
+   */
+  mobileTabs?: ReadonlyArray<MobileTabItem>;
   children: ReactNode;
 }
 
@@ -147,6 +153,7 @@ function SidebarShell({
   defaultOpen = true,
   contentClassName,
   contentMaxWidth,
+  mobileTabs,
   children,
 }: AppShellProps) {
   const style = brandColor
@@ -224,12 +231,14 @@ function SidebarShell({
         <div
           className={cn(
             "flex flex-1 flex-col gap-4 p-4 md:gap-6 md:p-6 print:overflow-visible",
+            mobileTabs?.length && "pb-tab-bar md:pb-6",
             contentMaxWidth && cn("mx-auto w-full", contentMaxWidth),
             contentClassName,
           )}
         >
           {children}
         </div>
+        {mobileTabs?.length ? <MobileTabBar items={mobileTabs} /> : null}
       </SidebarInset>
     </SidebarProvider>
   );
@@ -248,6 +257,7 @@ function TopShell({
   brandForeground,
   contentClassName,
   contentMaxWidth,
+  mobileTabs,
   children,
 }: AppShellProps) {
   const pathname = usePathname();
@@ -312,6 +322,7 @@ function TopShell({
       <div
         className={cn(
           "flex w-full flex-1 flex-col gap-4 p-4 md:flex-row md:gap-8 md:p-6",
+          mobileTabs?.length && "pb-tab-bar md:pb-6",
           contentMaxWidth && cn("mx-auto", contentMaxWidth),
         )}
       >
@@ -335,6 +346,7 @@ function TopShell({
           {children}
         </main>
       </div>
+      {mobileTabs?.length ? <MobileTabBar items={mobileTabs} /> : null}
     </div>
   );
 }

package/src/components/app-shell/index.ts

@@ -10,6 +10,7 @@ export {
 } from "./command-palette";
 export { HeaderBreadcrumbs, type HeaderBreadcrumbsProps } from "./header-breadcrumbs";
 export { HeaderCrumb, HeaderCrumbs } from "./header-crumb";
+export { MobileTabBar, type MobileTabItem } from "./mobile-tab-bar";
 export { NavLink } from "./nav-link";
 export {
   type OrganizationOption,

package/src/components/app-shell/mobile-tab-bar.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { CountBadge } from "@suphark/ui/components/shared/count-badge";
+import { useUiText } from "@suphark/ui/components/shared/ui-text";
+import { cn } from "@suphark/ui/lib/utils";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import type { ReactNode } from "react";
+import { isNavActive } from "./types";
+
+export interface MobileTabItem {
+  href: string;
+  label: string;
+  /** element เช่น `<Home />` (ไม่ใช่ component) — ส่งจาก server layout ได้เหมือน AppNav */
+  icon: ReactNode;
+  /** ตัวเลขบนไอคอน (เช่นแจ้งเตือนค้าง) — 0/undefined ไม่แสดง */
+  badge?: number;
+  /** ไฮไลต์เฉพาะ path ตรงตัว (ค่าเริ่มต้น: href "/" ตรงตัว, อื่น ๆ prefix) */
+  exact?: boolean;
+  /** กดแล้วทำ action แทนการไปหน้า (เช่นเปิด sheet แจ้งเตือน) */
+  onClick?: () => void;
+}
+
+/**
+ * แถบเมนูล่างสำหรับมือถือ (ยกจาก DueBell `MobileNav`) — ซ่อนตั้งแต่ md, เผื่อ safe-area ของ iPhone,
+ * แท็บละ ≥ 44px ตามเกณฑ์จอสัมผัส; ใช้ผ่าน `AppShell mobileTabs` (เว้นที่ใต้เนื้อหาให้เอง)
+ * หรือวางเองแล้วใส่ `pb-[calc(4rem+env(safe-area-inset-bottom))] md:pb-0` ให้เนื้อหา
+ * ควรมี 3–5 แท็บ — เกินนั้นให้ใช้เมนู sidebar
+ */
+export function MobileTabBar({
+  items,
+  className,
+  "aria-label": ariaLabel,
+}: {
+  items: ReadonlyArray<MobileTabItem>;
+  className?: string;
+  "aria-label"?: string;
+}) {
+  const pathname = usePathname();
+  const text = useUiText();
+  return (
+    <nav
+      data-slot="mobile-tab-bar"
+      aria-label={ariaLabel ?? text.mobileTabs ?? "เมนูหลัก"}
+      className={cn(
+        "fixed inset-x-0 bottom-0 z-40 border-t bg-background/95 pb-safe backdrop-blur md:hidden print:hidden",
+        className,
+      )}
+    >
+      <ul className="mx-auto flex max-w-lg items-stretch justify-around px-1">
+        {items.map((item) => {
+          const active = isNavActive(pathname, item.href, item.exact ?? item.href === "/");
+          const content: ReactNode = (
+            <>
+              <span className="relative">
+                <span
+                  aria-hidden
+                  className={cn("flex [&_svg]:size-5", active && "[&_svg]:stroke-[2.5]")}
+                >
+                  {item.icon}
+                </span>
+                {item.badge ? (
+                  <CountBadge
+                    value={item.badge}
+                    tone="destructive"
+                    className="absolute -top-1.5 -right-3 min-w-4 px-1"
+                  />
+                ) : null}
+              </span>
+              <span className="text-label leading-tight">{item.label}</span>
+            </>
+          );
+          const itemClass = cn(
+            "flex min-h-14 w-full min-w-14 flex-col items-center justify-center gap-0.5 rounded-lg px-2 py-1.5 no-underline outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring",
+            active ? "font-semibold text-primary" : "text-muted-foreground hover:text-foreground",
+          );
+          return (
+            <li key={item.href} className="flex flex-1">
+              {item.onClick ? (
+                <button
+                  type="button"
+                  onClick={item.onClick}
+                  className={itemClass}
+                  aria-label={item.badge ? `${item.label} (${item.badge})` : undefined}
+                >
+                  {content}
+                </button>
+              ) : (
+                <Link
+                  href={item.href}
+                  className={itemClass}
+                  aria-current={active ? "page" : undefined}
+                  aria-label={item.badge ? `${item.label} (${item.badge})` : undefined}
+                >
+                  {content}
+                </Link>
+              )}
+            </li>
+          );
+        })}
+      </ul>
+    </nav>
+  );
+}

package/src/components/shared/action-menu.tsx

@@ -0,0 +1,157 @@
+"use client";
+
+import { Button } from "@suphark/ui/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger,
+} from "@suphark/ui/components/ui/dropdown-menu";
+import { MoreHorizontal } from "lucide-react";
+import { type ReactElement, type ReactNode, useState } from "react";
+import { ConfirmDialog, type ConfirmSpec, normalizeConfirm } from "./confirm-dialog";
+import { useUiText } from "./ui-text";
+
+export interface ActionMenuCommand {
+  type?: "item";
+  label: ReactNode;
+  icon?: ReactNode;
+  onClick?: () => unknown;
+  /** ลิงก์ธรรมดา (`<a>`) — ลิงก์ภายในของ Next ที่ต้อง prefetch ใช้ onClick + router.push */
+  href?: string;
+  /** เปิดแท็บใหม่ (ใช้กับ href) */
+  external?: boolean;
+  shortcut?: string;
+  destructive?: boolean;
+  disabled?: boolean;
+  /** ถามยืนยันก่อน onClick (string = คำถาม หรือ object กำหนดหัว/ปุ่มเอง) */
+  confirm?: ConfirmSpec;
+}
+
+export type ActionMenuItem =
+  | ActionMenuCommand
+  | { type: "separator" }
+  | { type: "label"; label: ReactNode };
+
+/**
+ * เมนูคำสั่งสำเร็จรูปจาก array (แทน DropdownMenu/Trigger/Content/Item/Separator/Label/Shortcut)
+ * trigger ไม่ส่ง = ปุ่มไอคอน "…" (aria-label จาก `label` หรือ UiText.actions)
+ * แถวในตาราง/รายการที่เรียก server action + refresh ใช้ `RowActions` (`@suphark/ui/next`)
+ *
+ *   <ActionMenu items={[
+ *     { label: "แก้ไข", icon: <Pencil />, onClick: edit },
+ *     { type: "separator" },
+ *     { label: "ลบ", icon: <Trash2 />, destructive: true, confirm: "ลบรายการนี้?", onClick: remove },
+ *   ]} />
+ */
+export function ActionMenu({
+  items,
+  trigger,
+  label,
+  align = "end",
+}: {
+  items: ReadonlyArray<ActionMenuItem>;
+  trigger?: ReactElement;
+  /** aria-label ของปุ่ม … (ค่าเริ่มต้น UiText.actions) */
+  label?: string;
+  align?: "start" | "center" | "end";
+}) {
+  const text = useUiText();
+  const [confirming, setConfirming] = useState<ActionMenuCommand | null>(null);
+  const [pending, setPending] = useState(false);
+
+  const run = async (fn?: () => unknown) => {
+    if (!fn) return;
+    setPending(true);
+    try {
+      await fn();
+    } finally {
+      setPending(false);
+    }
+  };
+
+  const spec = confirming?.confirm ? normalizeConfirm(confirming.confirm) : null;
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger
+          render={
+            trigger ?? (
+              <Button variant="ghost" size="icon-sm" aria-label={label ?? text.actions}>
+                <MoreHorizontal />
+              </Button>
+            )
+          }
+        />
+        <DropdownMenuContent align={align} className="min-w-40">
+          <DropdownMenuGroup>
+            {items.map((item, i) => {
+              if (item.type === "separator") {
+                // biome-ignore lint/suspicious/noArrayIndexKey: ตัวคั่นไม่มี id — ลำดับคงที่ตาม items
+                return <DropdownMenuSeparator key={`sep-${i}`} />;
+              }
+              if (item.type === "label") {
+                // biome-ignore lint/suspicious/noArrayIndexKey: หัวกลุ่มไม่มี id — ลำดับคงที่ตาม items
+                return <DropdownMenuLabel key={`label-${i}`}>{item.label}</DropdownMenuLabel>;
+              }
+              const content = (
+                <>
+                  {item.icon}
+                  {item.label}
+                  {item.shortcut && <DropdownMenuShortcut>{item.shortcut}</DropdownMenuShortcut>}
+                </>
+              );
+              return (
+                <DropdownMenuItem
+                  // biome-ignore lint/suspicious/noArrayIndexKey: label เป็น ReactNode ใช้เป็น key ไม่ได้
+                  key={`item-${i}`}
+                  variant={item.destructive ? "destructive" : "default"}
+                  disabled={item.disabled}
+                  render={
+                    item.href ? (
+                      <a
+                        href={item.href}
+                        target={item.external ? "_blank" : undefined}
+                        rel={item.external ? "noreferrer" : undefined}
+                      />
+                    ) : undefined
+                  }
+                  onClick={() => {
+                    if (item.href) return;
+                    if (item.confirm) setConfirming(item);
+                    else void run(item.onClick);
+                  }}
+                >
+                  {content}
+                </DropdownMenuItem>
+              );
+            })}
+          </DropdownMenuGroup>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      {spec && confirming && (
+        <ConfirmDialog
+          open
+          onOpenChange={(o) => !o && setConfirming(null)}
+          title={spec.title}
+          description={spec.description}
+          confirmLabel={spec.confirmLabel}
+          cancelLabel={spec.cancelLabel}
+          requireText={spec.requireText}
+          requireTextLabel={spec.requireTextLabel}
+          destructive={spec.destructive ?? confirming.destructive}
+          pending={pending}
+          onConfirm={async () => {
+            await run(confirming.onClick);
+            setConfirming(null);
+          }}
+        />
+      )}
+    </>
+  );
+}

package/src/components/shared/button/confirm-action-button.tsx

@@ -66,6 +66,8 @@ export function ConfirmActionButton({
         description={spec.description}
         confirmLabel={spec.confirmLabel}
         cancelLabel={spec.cancelLabel}
+        requireText={spec.requireText}
+        requireTextLabel={spec.requireTextLabel}
         destructive={destructive}
         pending={pending}
         onConfirm={() => {

package/src/components/shared/filter-bar.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import { Button } from "@suphark/ui/components/ui/button";
+import { NativeSelect, NativeSelectOption } from "@suphark/ui/components/ui/native-select";
+import { cn } from "@suphark/ui/lib/utils";
+import { XIcon } from "lucide-react";
+import type { ReactNode } from "react";
+import { SearchInput } from "./form/search-input";
+import { useUiText } from "./ui-text";
+
+export interface FilterBarFilter {
+  id: string;
+  /** aria-label ของ select (ไม่มี label ที่มองเห็น) */
+  label: string;
+  value: string;
+  onValueChange: (value: string) => void;
+  options: ReadonlyArray<{ value: string; label: string }>;
+  /** ค่าที่หมายถึง "ทั้งหมด" (ไม่กรอง) — ใช้ตัดสินว่ามีตัวกรองค้างไหม และค่าที่ปุ่มล้างตั้งกลับ (ค่าเริ่มต้น "") */
+  allValue?: string;
+  className?: string;
+}
+
+/**
+ * แถบค้นหา + ตัวกรองเหนือตาราง/รายการแบบ client-side (ยกจาก Pi Auth — มี 14 หน้าเขียนซ้ำ):
+ * ช่องค้นหาซ้าย · select ตัวกรองขวา · ปุ่ม "ล้างตัวกรอง" โผล่เมื่อมีอะไรค้าง
+ * ตารางที่ใช้ tanstack ให้ใช้ toolbar ของ `@suphark/ui/data-table` แทน
+ *
+ *   <FilterBar
+ *     search={{ value: q, onValueChange: setQ, placeholder: "ค้นหาชื่อหรืออีเมล" }}
+ *     filters={[{ id: "role", label: "บทบาท", value: role, onValueChange: setRole, allValue: "ALL",
+ *                 options: [{ value: "ALL", label: "ทุกบทบาท" }, { value: "admin", label: "ผู้ดูแล" }] }]}
+ *   />
+ */
+export function FilterBar({
+  search,
+  filters = [],
+  onClear,
+  active,
+  children,
+  className,
+}: {
+  search?: { value: string; onValueChange: (value: string) => void; placeholder?: string };
+  filters?: FilterBarFilter[];
+  /** ไม่ส่ง = ล้างช่องค้นหา + ตั้งทุกตัวกรองกลับ `allValue` ให้เอง */
+  onClear?: () => void;
+  /** บังคับสถานะ "มีตัวกรองค้าง" (เช่นมีตัวกรองใน children) — ไม่ส่ง = คำนวณจาก search/filters */
+  active?: boolean;
+  /** ตัวกรองแบบอื่นที่แอปประกอบเอง (DateRangePicker, ToggleGroup …) วางต่อจาก select */
+  children?: ReactNode;
+  className?: string;
+}) {
+  const text = useUiText();
+  const isActive =
+    active ?? ((search?.value ?? "") !== "" || filters.some((f) => f.value !== (f.allValue ?? "")));
+
+  const clear = () => {
+    if (onClear) return onClear();
+    search?.onValueChange("");
+    for (const f of filters) f.onValueChange(f.allValue ?? "");
+  };
+
+  return (
+    <div
+      data-slot="filter-bar"
+      role="search"
+      aria-label={text.filters?.label ?? "ตัวกรอง"}
+      className={cn(
+        "flex flex-col gap-3 lg:flex-row lg:items-center lg:justify-between",
+        className,
+      )}
+    >
+      {search && (
+        <SearchInput
+          value={search.value}
+          onValueChange={search.onValueChange}
+          placeholder={search.placeholder}
+          groupClassName="lg:max-w-sm flex-1"
+        />
+      )}
+      {(filters.length > 0 || children || isActive) && (
+        <div className="flex flex-wrap items-center gap-2">
+          {filters.map((f) => (
+            <NativeSelect
+              key={f.id}
+              aria-label={f.label}
+              value={f.value}
+              onChange={(e) => f.onValueChange(e.target.value)}
+              className={cn("w-auto max-w-48", f.className)}
+            >
+              {f.options.map((o) => (
+                <NativeSelectOption key={o.value} value={o.value}>
+                  {o.label}
+                </NativeSelectOption>
+              ))}
+            </NativeSelect>
+          ))}
+          {children}
+          {isActive && (
+            <Button type="button" variant="ghost" size="sm" onClick={clear}>
+              <XIcon />
+              {text.filters?.clear ?? "ล้างตัวกรอง"}
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}