@suphark/ui 0.13.1 → 0.15.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.15.0] — 2026-09-30
+
+### Added
+
+- **`InfoHint`** (ขอจาก Pi Auth): ไอคอน (i) ท้ายหัวข้อ ที่เก็บคำอธิบายยาว ๆ ไว้ใน tooltip แทนการวาง
+  เป็น `description` ใต้หัวข้อถาวร — ใช้กับคำอธิบายที่คนซึ่งรู้อยู่แล้วไม่ต้องอ่านซ้ำทุกครั้ง
+  props: `children` (เนื้อหา), `label` (ชื่อที่ screen reader อ่าน — บังคับ), `side`, `className`
+  trigger เป็น **ปุ่มจริง** ไม่ใช่ `<span>` จึงเปิดได้ด้วยคีย์บอร์ด (Tab) และจอสัมผัส ไม่ใช่ hover อย่างเดียว
+- showcase: หน้า component `/components/info-hint`
+
+## [0.14.0] — 2026-09-29
+
+> **0.13.0 และ 0.13.1 ถูก publish ขึ้น npm เมื่อ 2026-09-25 จากโค้ดที่ไม่เคยเข้า git** (สเกลตัวอักษรตามบทบาท ขอจาก Pi Done) — รุ่นนี้กู้โค้ดจาก tarball 0.13.1 กลับเข้า `main` แล้ว (3-way merge กับ 0.12.0) บันทึกของสองรุ่นนั้นอยู่ข้างล่างตามที่ publish จริง
+
+รุ่นแรกของแผนรวม UI จากทุกแอป (สำรวจ Pi Auth / DueBell / Pi PDF / Pi Config — ดู `todo/todo.md`) — เพิ่มอย่างเดียว ไม่มี prop ถูกเปลี่ยนความหมาย
+
+### Added
+
+- **token สีโทนใน `styles.css`**: `--info` / `--info-foreground` (`bg-info`, `text-info`) และพื้นอ่อนครบ 4 โทน `--{info|success|warning|destructive}-subtle` / `-subtle-foreground` / `-border` (`bg-info-subtle text-info-subtle-foreground border-info-border` …) สลับ dark ให้เอง — แทน `sky-*` ที่ PDF ใช้ ~20 จุด และ `--info` ที่ DueBell ตั้งเอง (ถ้าแอปตั้ง `--info` ไว้เองให้ลบออก ค่าของแพ็กเกจ = sky-600 / dark sky-400)
+- `EmptyState`: `variant` (`dashed` ค่าเริ่มต้น · `card` · `plain`), `size="compact"`, `tone="destructive"`, `secondaryAction` (ขอจาก PDF ที่มีสำเนาของตัวเอง)
+- `CheckboxField`: `hint` — คำอธิบายใต้ label (Config เขียน `<p>` ต่อท้ายเอง ~8 จุด)
+- `SimpleSelect`: `name` + `required` — ส่งค่าใน FormData ของ server action ได้ (Config เคยใช้ hidden input เอง)
+- `FormDialog`: `renderSuccess(state)` — สำเร็จแล้วแสดงผลแทนฟอร์ม (secret/token ที่ออกครั้งเดียว) พร้อมปุ่ม "เสร็จแล้ว"; Pi Auth `SecretDialog` ใช้แทนได้
+- `ConfirmActionButton`: `redirectTo` — สำเร็จแล้ว `router.push` แทน refresh (Pi Auth `uninstall-button.tsx` ใช้แทนได้)
+- `useCopyToClipboard({ toast, timeout })`: คืน `copiedKey` (`copyToClipboard(text, key)` — หลายปุ่มในหน้าเดียวรู้ว่าปุ่มไหนเพิ่งคัดลอก), `toast: false` หรือข้อความของแอป (แปลภาษาได้), ใช้ `copyText` ที่มี fallback; `copyToClipboard` คืน `Promise<boolean>` — ของเดิม (`isCopied`, `copyToClipboard(text)`) ใช้ได้เหมือนเดิม (Pi Auth เขียน copy เอง 12 ไฟล์)
+- `formatBytes(bytes, locale, { minUnit })` — บังคับหน่วยเล็กสุด เช่น `"MB"` (PDF มีสำเนาเพราะต้องการแสดงเป็น MB)
+
+### Changed
+
+- `Notice` / `StatusBadge` ใช้ token โทนแทน palette ดิบ (ถอด `ui-audit-ok-file`) — สีเท่าเดิม ยกเว้นตัวอักษรของ `Notice` จาก 900→800 (dark 100→200) ให้ตรงกับ `StatusBadge`
+- `FormDialog`: state ของ action อยู่ในเนื้อ dialog — ปิดแล้วเปิดใหม่ได้ฟอร์มรอบใหม่เสมอ (เดิม `keepOpen` เปิดใหม่ยังเห็นผลรอบก่อน และ state ที่มี secret จะถูกส่งเป็น `prev` ไปกับ submit ถัดไป)
+- `useCopyToClipboard`: ไม่มี `navigator.clipboard` แล้วลอง fallback แทนการเตือน "Clipboard not supported"
+
+### ตรวจแล้วไม่แก้
+
+- hydration mismatch ของ trigger ที่ render ผ่าน Button (PDF รายงาน, ห่อ wrapper `slot-props.ts`): showcase ใช้ `render={<Button/>}` กับ Dialog/Sheet/Popover/DropdownMenu/Tooltip ไม่มี hydration error ใน dev — น่าจะมาจาก wrapper `asChild` ของ PDF เอง ให้ PDF ลองเปลี่ยนเป็น `render=` ตรง ๆ ก่อน
+- ข้อความ sr-only "Close" ใน `DialogContent`/`SheetContent` ยังแปลไม่ได้ — อยู่ในไฟล์ shadcn (ห้ามแก้มือ) รอตัดสินใจ
+
+### Fixed
+
+- showcase: เมนู "ออกจากระบบ" ที่หัวเว็บดูเหมือนกดไม่ได้ — ออกแล้วกลับหน้าเดิม middleware ส่งไปล็อกอิน และ Pi Auth ยังมี session จึงล็อกอินกลับทันที → `UserButton afterSignOutUrl="/login"` จอดหน้าเข้าสู่ระบบ
+
 ## [0.13.1] - 2026-09-25
 
 ### Fixed

package/README.md

@@ -89,7 +89,7 @@ import { ChartContainer } from "@suphark/ui/components/ui/chart";
 | `src/components/app-shell/*` | AppShell (sidebar + header + เนื้อหา), AppNav, AppBrand, UserMenu, HeaderBreadcrumbs, NavLink, filterNav/searchNav | export ผ่าน `@suphark/ui/next` (ใช้ next/link, next/navigation) |
 | `src/components/design-system/*` | หน้า showcase (render ใน `apps/showcase`) | ไม่อยู่ใน barrel |
 | `src/lib/*`, `src/hooks/*` | `cn`, formatter วันที่ไทย + `formatBytes`, สีสถานะ, permission context, `useIsMobile`, `useCopyToClipboard`, `useMounted`, `useTicker` | |
-| `src/styles.css` | token (slate + success/warning/sidebar/chart), radius, ฟอนต์, scrollbar, dark variant | |
+| `src/styles.css` | token (slate + success/warning/info + พื้นอ่อนตามโทน `*-subtle`/`*-border` + sidebar/chart), สเกลตัวอักษรตามบทบาท (`text-body` …), radius, ฟอนต์, scrollbar, dark variant | |
 | `scripts/*.mjs` | audit บังคับ: Base UI props (`default*`/`onSelect`), typography scale | แอปปลายทางรันได้จาก `node_modules/@suphark/ui/scripts` |
 
 ### โครงแอป (AppShell)
@@ -200,7 +200,7 @@ npx suphark-ui-audit --strict   # warning นับเป็น error (ใช้
 | `radix-state` | error | `data-[state=open\|checked\|active…]` → `data-open` / `data-checked` / `data-active` / `data-popup-open` (Base UI ไม่มี data-state) |
 | `arbitrary-text` | error | `text-[Npx]` → `text-xs … text-3xl` |
 | `base-ui-props` | error | `default*` ที่ค่าเปลี่ยนได้ / `onSelect` บนเมนู (ดู `scripts/audit-base-ui-props.mjs`) |
-| `raw-palette` | warning | `bg-red-500`, `text-slate-600` … → `bg-destructive`, `text-muted-foreground`, `bg-success`, `bg-warning`, `text-primary` |
+| `raw-palette` | warning | `bg-red-500`, `text-slate-600` … → `bg-destructive`, `text-muted-foreground`, `bg-success`, `bg-warning`, `bg-info`, `text-primary`; พื้นอ่อน `bg-sky-50 text-sky-800` → `bg-info-subtle text-info-subtle-foreground` |
 | `important` | warning (เฉพาะ `--important`) | utility ลงท้าย `!` ในโค้ดแพ็กเกจ |
 
 ยกเว้นรายบรรทัด `// ui-audit-ok: <เหตุผล>` (บรรทัดเดียวกันหรือบรรทัดก่อน) — ยกเว้นทั้งไฟล์ `/* ui-audit-ok-file: <เหตุผล> */`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.13.1",
+  "version": "0.15.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/design-system/sections/showcase-foundations.tsx

@@ -72,6 +72,20 @@ export function ShowcaseFoundations() {
       tailwind: "bg-success / text-success-foreground",
       usage: "Approved status, Success badges, Positive rate variance",
     },
+    {
+      name: "Info",
+      class: "bg-info text-info-foreground",
+      token: "var(--info)",
+      tailwind: "bg-info / text-info-foreground / text-info",
+      usage: "ข้อมูลประกอบ, รายการที่เลือก, ลิงก์ช่วยเหลือ — แทน sky-* ที่แอปเขียนเอง",
+    },
+    {
+      name: "Tone subtle (info / success / warning / destructive)",
+      class: "bg-info-subtle text-info-subtle-foreground border border-info-border",
+      token: "var(--{tone}-subtle) / var(--{tone}-border)",
+      tailwind: "bg-{tone}-subtle / text-{tone}-subtle-foreground / border-{tone}-border",
+      usage: "พื้นอ่อนของ Notice, StatusBadge, callout — สลับ dark ให้เอง ไม่ต้องใส่ dark: เอง",
+    },
     {
       name: "Border / Input / Ring",
       class: "bg-card text-foreground border-2 border-ring",

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

@@ -29,6 +29,7 @@ export function ConfirmActionButton({
   action,
   data,
   onDone,
+  redirectTo,
   variant,
   children,
   ...props
@@ -38,6 +39,8 @@ export function ConfirmActionButton({
   data?: Record<string, string>;
   /** เรียกหลัง action สำเร็จ (ก่อน refresh) เช่น toast */
   onDone?: () => void;
+  /** สำเร็จแล้วไปหน้านี้แทน refresh (เช่น ลบรายการแล้วกลับหน้า list) */
+  redirectTo?: string;
 }) {
   const router = useRouter();
   const text = useUiText();
@@ -78,7 +81,8 @@ export function ConfirmActionButton({
             }
             onDone?.();
             setOpen(false);
-            router.refresh();
+            if (redirectTo) router.push(redirectTo);
+            else router.refresh();
           });
         }}
       />

package/src/components/shared/empty-state.tsx

@@ -1,31 +1,69 @@
 import { cn } from "@suphark/ui/lib/utils";
 import type { ReactNode } from "react";
 
-/** หน้าว่าง = คำเชิญให้ทำขั้นถัดไป: ไอคอน, ประโยคเดียวว่าคืออะไร, ปุ่มเดียวว่าทำอะไรต่อ */
+/**
+ * หน้าว่าง = คำเชิญให้ทำขั้นถัดไป: ไอคอน, ประโยคเดียวว่าคืออะไร, ปุ่มเดียวว่าทำอะไรต่อ
+ *
+ * - `variant`: "dashed" (ค่าเริ่มต้น กรอบเส้นประ) · "card" (พื้น card เส้นทึบ) · "plain" (ไม่มีกรอบ — วางใน card ที่มีอยู่แล้ว)
+ * - `size="compact"`: ระยะ/ไอคอนเล็ก สำหรับช่องแคบ เช่น panel ข้าง, popover, ตารางย่อย
+ * - `tone="destructive"`: ไอคอนสีแดง สำหรับสถานะว่างเพราะผิดพลาด (เช่น โหลดไม่ได้) — ข้อผิดพลาดทั้งหน้าใช้ ErrorState
+ * - `secondaryAction`: ปุ่มรอง วางข้าง `action`
+ */
 export function EmptyState({
   icon,
   title,
   description,
   action,
+  secondaryAction,
+  variant = "dashed",
+  size = "default",
+  tone = "default",
   className,
 }: {
   icon?: ReactNode;
   title: ReactNode;
   description?: ReactNode;
   action?: ReactNode;
+  secondaryAction?: ReactNode;
+  variant?: "dashed" | "card" | "plain";
+  size?: "default" | "compact";
+  tone?: "default" | "destructive";
   className?: string;
 }) {
+  const compact = size === "compact";
   return (
     <div
       className={cn(
-        "flex flex-col items-center justify-center gap-2 rounded-xl border border-dashed px-6 py-12 text-center",
+        "flex flex-col items-center justify-center gap-2 rounded-xl text-center",
+        compact ? "px-4 py-6" : "px-6 py-12",
+        variant === "dashed" && "border border-dashed",
+        variant === "card" && "border bg-card text-card-foreground",
         className,
       )}
     >
-      {icon && <div className="mb-1 text-muted-foreground [&_svg]:size-8">{icon}</div>}
-      <p className="text-sm font-medium">{title}</p>
-      {description && <p className="max-w-sm text-sm text-muted-foreground">{description}</p>}
-      {action && <div className="mt-2">{action}</div>}
+      {icon && (
+        <div
+          className={cn(
+            "mb-1",
+            compact ? "[&_svg]:size-6" : "[&_svg]:size-8",
+            tone === "destructive" ? "text-destructive" : "text-muted-foreground",
+          )}
+        >
+          {icon}
+        </div>
+      )}
+      <p className="font-medium text-sm">{title}</p>
+      {description && (
+        <p className={cn("max-w-sm text-muted-foreground", compact ? "text-xs" : "text-sm")}>
+          {description}
+        </p>
+      )}
+      {(action || secondaryAction) && (
+        <div className="mt-2 flex flex-wrap items-center justify-center gap-2">
+          {action}
+          {secondaryAction}
+        </div>
+      )}
     </div>
   );
 }

package/src/components/shared/form/labeled-field.tsx

@@ -67,16 +67,33 @@ export function LabeledField({
  * Checkbox ของ shadcn + label บรรทัดเดียว — ใส่ `name` แล้วส่ง "on" ใน FormData ของ server action ได้
  *
  *   <CheckboxField name="allowSignup" defaultChecked label="เปิดให้สมัครเอง" />
+ *   <CheckboxField name="overwrite" label="เขียนทับค่าเดิม" hint="คีย์ที่มีอยู่แล้วจะถูกแทนที่" />
  */
 export function CheckboxField({
   label,
+  hint,
   className,
   ...props
-}: ComponentProps<typeof Checkbox> & { label: ReactNode }) {
+}: ComponentProps<typeof Checkbox> & {
+  label: ReactNode;
+  /** คำอธิบายใต้ label (เยื้องตรงกับ label) */
+  hint?: ReactNode;
+}) {
+  if (!hint) {
+    return (
+      <Label className={cn("flex items-center gap-2 font-normal", className)}>
+        <Checkbox {...props} />
+        <span className="text-sm">{label}</span>
+      </Label>
+    );
+  }
   return (
-    <Label className={cn("flex items-center gap-2 font-normal", className)}>
-      <Checkbox {...props} />
-      <span className="text-sm">{label}</span>
+    <Label className={cn("flex items-start gap-2 font-normal", className)}>
+      <Checkbox className="mt-0.5" {...props} />
+      <span className="flex flex-col gap-0.5">
+        <span className="text-sm">{label}</span>
+        <span className="text-muted-foreground text-xs">{hint}</span>
+      </span>
     </Label>
   );
 }

package/src/components/shared/form/simple-select.tsx

@@ -41,6 +41,10 @@ export interface SimpleSelectProps<T extends string = string> {
   triggerClassName?: string;
   contentClassName?: string;
   ariaLabel?: string;
+  /** ชื่อฟิลด์ใน FormData (server action) — ส่งค่าที่เลือกผ่าน hidden input ของ Base UI */
+  name?: string;
+  /** บังคับเลือกก่อน submit ฟอร์ม */
+  required?: boolean;
 }
 
 function isGroupList<T extends string>(
@@ -63,6 +67,8 @@ export function SimpleSelect<T extends string = string>({
   triggerClassName,
   contentClassName,
   ariaLabel,
+  name,
+  required,
 }: SimpleSelectProps<T>) {
   const { flatOptions, groups } = React.useMemo(() => {
     if (isGroupList(options)) {
@@ -122,6 +128,8 @@ export function SimpleSelect<T extends string = string>({
         }
       }}
       disabled={disabled}
+      name={name}
+      required={required}
     >
       <SelectTrigger
         size={size}

package/src/components/shared/form-dialog.tsx

@@ -43,6 +43,7 @@ export function FormDialog<TData = undefined>({
   open: controlledOpen,
   onOpenChange,
   keepOpen = false,
+  renderSuccess,
   contentClassName,
 }: {
   /** ปุ่มเปิด (ต้องเป็น <Button> ของ shadcn — Base UI จะใช้ตัวนี้เป็น trigger โดยตรง) */
@@ -58,65 +59,123 @@ export function FormDialog<TData = undefined>({
   onOpenChange?: (open: boolean) => void;
   /** ผลลัพธ์ต้องอ่านหลังสำเร็จ (เช่น secret แสดงครั้งเดียว) → ไม่ปิดเอง */
   keepOpen?: boolean;
+  /**
+   * สำเร็จแล้วแสดงผลแทนฟอร์ม (เช่น secret/token ที่ออกใหม่ แสดงครั้งเดียว) พร้อมปุ่ม "เสร็จแล้ว" — ไม่ปิดเอง
+   * ปิดแล้วเปิดใหม่ = ฟอร์มว่าง รอบใหม่ (state เดิมรวม data ถูกทิ้ง ไม่ถูกส่งกลับไปกับ submit ครั้งถัดไป)
+   */
+  renderSuccess?: (state: Extract<FormState<TData>, { ok: true }>) => ReactNode;
   /** ความกว้าง/คลาสของ DialogContent (ค่าเริ่มต้น sm:max-w-md) */
   contentClassName?: string;
 }) {
-  const router = useRouter();
-  const text = useUiText();
   const [uncontrolled, setUncontrolled] = useState(false);
   const open = controlledOpen ?? uncontrolled;
   const setOpen = onOpenChange ?? setUncontrolled;
+
+  return (
+    <Dialog open={open} onOpenChange={setOpen}>
+      {trigger && <DialogTrigger render={trigger} />}
+      {/* จำกัดความสูงไว้ในจอ: header/footer ตรึง เฉพาะเนื้อฟอร์มเลื่อน (ฟอร์มยาวไม่ล้นในหน้าต่างเตี้ย) */}
+      <DialogContent
+        className={cn("flex max-h-[calc(100dvh-2rem)] flex-col", contentClassName ?? "sm:max-w-md")}
+      >
+        {/* state ของ action อยู่ในเนื้อ dialog ซึ่ง unmount ตอนปิด → เปิดใหม่ได้ฟอร์มรอบใหม่ */}
+        <FormDialogBody
+          title={title}
+          description={description}
+          action={action}
+          submitLabel={submitLabel}
+          keepOpen={keepOpen || renderSuccess !== undefined}
+          renderSuccess={renderSuccess}
+          close={() => setOpen(false)}
+        >
+          {children}
+        </FormDialogBody>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function FormDialogBody<TData>({
+  title,
+  description,
+  action,
+  submitLabel,
+  children,
+  keepOpen,
+  renderSuccess,
+  close,
+}: {
+  title: ReactNode;
+  description?: ReactNode;
+  action: FormAction<TData>;
+  submitLabel?: string;
+  children: ReactNode | ((ctx: FormRenderContext) => ReactNode);
+  keepOpen: boolean;
+  renderSuccess?: (state: Extract<FormState<TData>, { ok: true }>) => ReactNode;
+  close: () => void;
+}) {
+  const router = useRouter();
+  const text = useUiText();
   const [state, formAction, pending] = useActionState<FormState<TData>, FormData>(action, null);
   const [submitted, setSubmitted] = useState(0);
 
   // biome-ignore lint/correctness/useExhaustiveDependencies: ทำงานเมื่อผลของการ submit เปลี่ยนเท่านั้น
   useEffect(() => {
     if (state?.ok && !keepOpen) {
-      setOpen(false);
+      close();
       router.refresh();
     } else if (state?.ok) {
       router.refresh();
     }
   }, [state, submitted]);
 
+  if (state?.ok && renderSuccess) {
+    return (
+      <div className="flex min-h-0 flex-1 flex-col gap-4">
+        <DialogHeader>
+          <DialogTitle>{title}</DialogTitle>
+          {description && <DialogDescription>{description}</DialogDescription>}
+        </DialogHeader>
+        <div className="-mx-1 flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto px-1">
+          {renderSuccess(state)}
+        </div>
+        <DialogFooter>
+          <Button type="button" onClick={close}>
+            {text.done}
+          </Button>
+        </DialogFooter>
+      </div>
+    );
+  }
+
   return (
-    <Dialog open={open} onOpenChange={setOpen}>
-      {trigger && <DialogTrigger render={trigger} />}
-      {/* จำกัดความสูงไว้ในจอ: header/footer ตรึง เฉพาะเนื้อฟอร์มเลื่อน (ฟอร์มยาวไม่ล้นในหน้าต่างเตี้ย) */}
-      <DialogContent
-        className={cn("flex max-h-[calc(100dvh-2rem)] flex-col", contentClassName ?? "sm:max-w-md")}
-      >
-        <form
-          // ไม่ใช้ `action=` — React 19 รีเซ็ตฟอร์ม uncontrolled หลัง action จบทุกครั้ง (แม้คืน error)
-          // ทำให้ค่าที่พิมพ์หาย; เรียก action ใน transition เองแทน ฟอร์มจึงคงค่าไว้ให้แก้ต่อได้
-          onSubmit={(e) => {
-            e.preventDefault();
-            const fd = new FormData(e.currentTarget);
-            setSubmitted((n) => n + 1);
-            startTransition(() => formAction(fd));
-          }}
-          className="flex min-h-0 flex-1 flex-col gap-4"
-        >
-          <DialogHeader>
-            <DialogTitle>{title}</DialogTitle>
-            {description && <DialogDescription>{description}</DialogDescription>}
-          </DialogHeader>
-          <div className="-mx-1 flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto px-1">
-            {typeof children === "function"
-              ? children(formRenderContext(state, pending))
-              : children}
-          </div>
-          <FormMessage state={state} />
-          <DialogFooter>
-            <Button type="button" variant="ghost" onClick={() => setOpen(false)}>
-              {text.cancel}
-            </Button>
-            <Button type="submit" disabled={pending}>
-              {submitLabel ?? text.save}
-            </Button>
-          </DialogFooter>
-        </form>
-      </DialogContent>
-    </Dialog>
+    <form
+      // ไม่ใช้ `action=` — React 19 รีเซ็ตฟอร์ม uncontrolled หลัง action จบทุกครั้ง (แม้คืน error)
+      // ทำให้ค่าที่พิมพ์หาย; เรียก action ใน transition เองแทน ฟอร์มจึงคงค่าไว้ให้แก้ต่อได้
+      onSubmit={(e) => {
+        e.preventDefault();
+        const fd = new FormData(e.currentTarget);
+        setSubmitted((n) => n + 1);
+        startTransition(() => formAction(fd));
+      }}
+      className="flex min-h-0 flex-1 flex-col gap-4"
+    >
+      <DialogHeader>
+        <DialogTitle>{title}</DialogTitle>
+        {description && <DialogDescription>{description}</DialogDescription>}
+      </DialogHeader>
+      <div className="-mx-1 flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto px-1">
+        {typeof children === "function" ? children(formRenderContext(state, pending)) : children}
+      </div>
+      <FormMessage state={state} />
+      <DialogFooter>
+        <Button type="button" variant="ghost" onClick={close}>
+          {text.cancel}
+        </Button>
+        <Button type="submit" disabled={pending}>
+          {submitLabel ?? text.save}
+        </Button>
+      </DialogFooter>
+    </form>
   );
 }

package/src/components/shared/info-hint.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { Tooltip, TooltipContent, TooltipTrigger } from "@suphark/ui/components/ui/tooltip";
+import { cn } from "@suphark/ui/lib/utils";
+import { InfoIcon } from "lucide-react";
+import type { ReactNode } from "react";
+
+/**
+ * คำอธิบายที่ไม่ควรกินพื้นที่ถาวร — เก็บไว้หลังไอคอน (i) ท้ายหัวข้อ แล้วค่อยแสดงเมื่อวางเมาส์/โฟกัส
+ * ใช้กับคำอธิบายที่คนซึ่งรู้อยู่แล้วไม่ต้องอ่านซ้ำทุกครั้ง (เช่นหัวข้อการ์ดในหน้าตั้งค่า)
+ *
+ * trigger เป็นปุ่มจริงเพื่อให้เข้าถึงได้ด้วยคีย์บอร์ดและจอสัมผัส ไม่ใช่ hover อย่างเดียว —
+ * `label` คือสิ่งที่ screen reader อ่าน ควรบอกว่าเป็นคำอธิบายของอะไร
+ */
+export function InfoHint({
+  children,
+  label,
+  side = "top",
+  className,
+}: {
+  /** เนื้อหาใน tooltip */
+  children: ReactNode;
+  /** ชื่อที่ screen reader อ่าน เช่น "คำอธิบาย Attribute" */
+  label: string;
+  side?: "top" | "bottom" | "left" | "right";
+  className?: string;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger
+        aria-label={label}
+        className={cn(
+          "inline-flex size-4 shrink-0 items-center justify-center rounded-full text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-3 focus-visible:ring-ring/50",
+          className,
+        )}
+      >
+        <InfoIcon className="size-3.5" aria-hidden />
+      </TooltipTrigger>
+      <TooltipContent side={side} className="max-w-xs text-pretty leading-relaxed">
+        {children}
+      </TooltipContent>
+    </Tooltip>
+  );
+}

package/src/components/shared/notice.tsx

@@ -1,4 +1,3 @@
-/* ui-audit-ok-file: โทน info/success/warning/danger ใช้ palette 50/900 คู่ dark โดยตั้งใจ — รอตัดสินใจ token ระดับ tone (todo) */
 import { Alert, AlertDescription, AlertTitle } from "@suphark/ui/components/ui/alert";
 import { cn } from "@suphark/ui/lib/utils";
 import type { ComponentProps, ReactNode } from "react";
@@ -6,14 +5,12 @@ import type { Tone } from "./status-badge";
 
 export type NoticeTone = Exclude<Tone, "neutral">;
 
+/** token โทนใน styles.css (สลับ dark ให้เอง) */
 const TONE: Record<NoticeTone, string> = {
-  info: "border-sky-200 bg-sky-50 text-sky-900 dark:border-sky-900 dark:bg-sky-950 dark:text-sky-100",
-  success:
-    "border-emerald-200 bg-emerald-50 text-emerald-900 dark:border-emerald-900 dark:bg-emerald-950 dark:text-emerald-100",
-  warning:
-    "border-amber-300 bg-amber-50 text-amber-900 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-100",
-  danger:
-    "border-red-200 bg-red-50 text-red-900 dark:border-red-900 dark:bg-red-950 dark:text-red-100",
+  info: "border-info-border bg-info-subtle text-info-subtle-foreground",
+  success: "border-success-border bg-success-subtle text-success-subtle-foreground",
+  warning: "border-warning-border bg-warning-subtle text-warning-subtle-foreground",
+  danger: "border-destructive-border bg-destructive-subtle text-destructive-subtle-foreground",
 };
 
 /** Alert ของ shadcn + สีตามความหมาย (info/success/warning/danger) */

package/src/components/shared/status-badge.tsx

@@ -1,4 +1,3 @@
-/* ui-audit-ok-file: โทน badge ใช้ palette 50/800 คู่ dark โดยตั้งใจ — รอตัดสินใจ token ระดับ tone (todo) */
 import { Badge } from "@suphark/ui/components/ui/badge";
 import { cn } from "@suphark/ui/lib/utils";
 import type { ComponentProps } from "react";
@@ -7,13 +6,10 @@ export type Tone = "neutral" | "success" | "warning" | "danger" | "info";
 
 const TONE: Record<Tone, string> = {
   neutral: "border-transparent bg-muted text-muted-foreground",
-  success:
-    "border-emerald-200 bg-emerald-50 text-emerald-800 dark:border-emerald-900 dark:bg-emerald-950 dark:text-emerald-200",
-  warning:
-    "border-amber-200 bg-amber-50 text-amber-800 dark:border-amber-900 dark:bg-amber-950 dark:text-amber-200",
-  danger:
-    "border-red-200 bg-red-50 text-red-800 dark:border-red-900 dark:bg-red-950 dark:text-red-200",
-  info: "border-sky-200 bg-sky-50 text-sky-800 dark:border-sky-900 dark:bg-sky-950 dark:text-sky-200",
+  success: "border-success-border bg-success-subtle text-success-subtle-foreground",
+  warning: "border-warning-border bg-warning-subtle text-warning-subtle-foreground",
+  danger: "border-destructive-border bg-destructive-subtle text-destructive-subtle-foreground",
+  info: "border-info-border bg-info-subtle text-info-subtle-foreground",
 };
 
 /** Badge ของ shadcn (variant outline) + สีตามความหมายของสถานะ */

package/src/hooks/use-copy-to-clipboard.ts

@@ -1,27 +1,64 @@
 "use client";
 
-import { useState } from "react";
-import { toast } from "sonner";
-
-export function useCopyToClipboard() {
-  const [isCopied, setIsCopied] = useState(false);
-
-  const copyToClipboard = async (text: string) => {
-    if (!navigator?.clipboard) {
-      toast.warning("Clipboard not supported");
-      return;
-    }
-
-    try {
-      await navigator.clipboard.writeText(text);
-      setIsCopied(true);
-      toast.success("Copied to clipboard");
-      setTimeout(() => setIsCopied(false), 2000);
-    } catch {
-      toast.error("Failed to copy");
-      setIsCopied(false);
-    }
-  };
-
-  return { isCopied, copyToClipboard };
+import { copyText } from "@suphark/ui/lib/copy-text";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { toast as sonner } from "sonner";
+
+export interface CopyToClipboardLabels {
+  success: string;
+  failed: string;
+}
+
+export interface UseCopyToClipboardOptions {
+  /** false = ไม่แสดง toast (แอปแสดง ✓ ที่ปุ่มเอง); object = ข้อความของแอป (แปลภาษาได้) */
+  toast?: boolean | Partial<CopyToClipboardLabels>;
+  /** ms ที่ `isCopied`/`copiedKey` ค้างไว้หลังคัดลอก */
+  timeout?: number;
+}
+
+const DEFAULT_LABELS: CopyToClipboardLabels = {
+  success: "Copied to clipboard",
+  failed: "Failed to copy",
+};
+
+/**
+ * คัดลอกข้อความ (มี fallback execCommand สำหรับ browser/webview ที่บล็อก clipboard API)
+ *
+ *   const { copyToClipboard, copiedKey } = useCopyToClipboard({ toast: { success: "คัดลอกแล้ว", failed: "คัดลอกไม่สำเร็จ" } });
+ *   copyToClipboard(row.value, row.id)   // หลายปุ่มในหน้าเดียว → copiedKey บอกว่าปุ่มไหนเพิ่งคัดลอก
+ */
+export function useCopyToClipboard(options: UseCopyToClipboardOptions = {}) {
+  const { toast = true, timeout = 2000 } = options;
+  const [copiedKey, setCopiedKey] = useState<string | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    [],
+  );
+
+  const labels = typeof toast === "object" ? { ...DEFAULT_LABELS, ...toast } : DEFAULT_LABELS;
+  const showToast = toast !== false;
+  const { success, failed } = labels;
+
+  const copyToClipboard = useCallback(
+    async (text: string, key = "default"): Promise<boolean> => {
+      const ok = await copyText(text);
+      if (timer.current) clearTimeout(timer.current);
+      if (!ok) {
+        setCopiedKey(null);
+        if (showToast) sonner.error(failed);
+        return false;
+      }
+      setCopiedKey(key);
+      if (showToast) sonner.success(success);
+      timer.current = setTimeout(() => setCopiedKey(null), timeout);
+      return true;
+    },
+    [showToast, success, failed, timeout],
+  );
+
+  return { isCopied: copiedKey !== null, copiedKey, copyToClipboard };
 }

package/src/index.ts

@@ -95,6 +95,7 @@ export {
   type IconPickerProps,
   type IconPickerText,
 } from "./components/shared/icon-picker";
+export { InfoHint } from "./components/shared/info-hint";
 export { Initials, initialsOf } from "./components/shared/initials";
 export { ErrorState, type RouteError } from "./components/shared/layout/error-state";
 export {

package/src/lib/formatters.ts

@@ -49,15 +49,24 @@ export function formatThaiFullDate(date: Date | string | number | null | undefin
  * ขนาดไฟล์อ่านง่าย (ฐาน 1024): 0 B, 1.5 KB, 12.3 MB, 1.2 GB — ตัวเลขทศนิยม 1 ตำแหน่งเมื่อ < 10
  *   formatBytes(1536) → "1.5 KB"
  */
-export function formatBytes(bytes: number | null | undefined, locale = "th-TH"): string {
+export function formatBytes(
+  bytes: number | null | undefined,
+  locale = "th-TH",
+  options: {
+    /** หน่วยเล็กสุดที่แสดง เช่น "MB" → 200 KB แสดงเป็น "0.2 MB" (หน้าที่แสดงโควตา/ไฟล์ใหญ่) */
+    minUnit?: "B" | "KB" | "MB" | "GB";
+  } = {},
+): string {
   if (bytes == null || !Number.isFinite(bytes) || bytes < 0) return "—";
   const units = ["B", "KB", "MB", "GB", "TB"] as const;
+  const minIndex = options.minUnit ? units.indexOf(options.minUnit) : 0;
   let value = bytes;
   let i = 0;
-  while (value >= 1024 && i < units.length - 1) {
+  while ((value >= 1024 || i < minIndex) && i < units.length - 1) {
     value /= 1024;
     i += 1;
   }
-  const digits = i === 0 ? 0 : value < 10 ? 1 : 0;
+  // ค่า < 1 เกิดได้เฉพาะเมื่อบังคับ minUnit → ให้ทศนิยม 2 ตำแหน่งไม่ให้ปัดเป็น 0
+  const digits = i === 0 ? 0 : value < 1 ? 2 : value < 10 ? 1 : 0;
   return `${value.toLocaleString(locale, { maximumFractionDigits: digits })} ${units[i]}`;
 }

package/src/styles.css

@@ -50,6 +50,21 @@
   --color-warning: var(--warning);
   --color-warning-foreground: var(--warning-foreground);
   --color-warning-muted-foreground: var(--warning-muted-foreground);
+  --color-info: var(--info);
+  --color-info-foreground: var(--info-foreground);
+  /* พื้นอ่อน/ตัวอักษร/เส้นขอบของโทน (Notice, StatusBadge, callout ของแอป) — bg-info-subtle text-info-subtle-foreground border-info-border */
+  --color-info-subtle: var(--info-subtle);
+  --color-info-subtle-foreground: var(--info-subtle-foreground);
+  --color-info-border: var(--info-border);
+  --color-success-subtle: var(--success-subtle);
+  --color-success-subtle-foreground: var(--success-subtle-foreground);
+  --color-success-border: var(--success-border);
+  --color-warning-subtle: var(--warning-subtle);
+  --color-warning-subtle-foreground: var(--warning-subtle-foreground);
+  --color-warning-border: var(--warning-border);
+  --color-destructive-subtle: var(--destructive-subtle);
+  --color-destructive-subtle-foreground: var(--destructive-subtle-foreground);
+  --color-destructive-border: var(--destructive-border);
   --color-accent-foreground: var(--accent-foreground);
   --color-accent: var(--accent);
   --color-muted-foreground: var(--muted-foreground);
@@ -142,6 +157,21 @@
   --warning: oklch(0.852 0.199 91.936);
   --warning-foreground: oklch(0.286 0.066 53.813);
   --warning-muted-foreground: oklch(0.421 0.095 57.708);
+  /* โทน: ค่าเท่า Tailwind sky/emerald/amber/red ที่ Notice/StatusBadge เคยใช้ตรง ๆ (50 พื้น · 200 ขอบ · 800 ตัวอักษร) */
+  --info: oklch(0.588 0.158 241.966);
+  --info-foreground: oklch(0.984 0.003 247.858);
+  --info-subtle: oklch(0.977 0.013 236.62);
+  --info-subtle-foreground: oklch(0.443 0.11 240.79);
+  --info-border: oklch(0.901 0.058 230.902);
+  --success-subtle: oklch(0.979 0.021 166.113);
+  --success-subtle-foreground: oklch(0.432 0.095 166.913);
+  --success-border: oklch(0.905 0.093 164.15);
+  --warning-subtle: oklch(0.987 0.022 95.277);
+  --warning-subtle-foreground: oklch(0.473 0.137 46.201);
+  --warning-border: oklch(0.924 0.12 95.746);
+  --destructive-subtle: oklch(0.971 0.013 17.38);
+  --destructive-subtle-foreground: oklch(0.444 0.177 26.899);
+  --destructive-border: oklch(0.885 0.062 18.334);
   --border: oklch(0.929 0.013 255.508);
   --input: oklch(0.929 0.013 255.508);
   --ring: oklch(0.704 0.04 256.788);
@@ -183,6 +213,21 @@
   --warning: oklch(0.852 0.199 91.936);
   --warning-foreground: oklch(0.286 0.066 53.813);
   --warning-muted-foreground: oklch(0.905 0.182 98.111);
+  /* dark: 950 พื้น · 900 ขอบ · 200 ตัวอักษร · info ทึบ = sky-400 */
+  --info: oklch(0.746 0.16 232.661);
+  --info-foreground: oklch(0.293 0.066 243.157);
+  --info-subtle: oklch(0.293 0.066 243.157);
+  --info-subtle-foreground: oklch(0.901 0.058 230.902);
+  --info-border: oklch(0.391 0.09 240.876);
+  --success-subtle: oklch(0.262 0.051 172.552);
+  --success-subtle-foreground: oklch(0.905 0.093 164.15);
+  --success-border: oklch(0.378 0.077 168.94);
+  --warning-subtle: oklch(0.279 0.077 45.635);
+  --warning-subtle-foreground: oklch(0.924 0.12 95.746);
+  --warning-border: oklch(0.414 0.112 45.904);
+  --destructive-subtle: oklch(0.258 0.092 26.042);
+  --destructive-subtle-foreground: oklch(0.885 0.062 18.334);
+  --destructive-border: oklch(0.396 0.141 25.723);
   --border: oklch(1 0 0 / 10%);
   --input: oklch(1 0 0 / 15%);
   --ring: oklch(0.551 0.027 264.364);