@suphark/ui 0.18.0 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.19.0] — 2026-09-30
+
+ปิดรายการ "component เล็กที่ใช้ร่วม" ของแผนรวม UI ทุกแอป (ดู `todo/todo.md`) — เพิ่มอย่างเดียว ไม่มี prop เดิมเปลี่ยนความหมาย
+
+### Added
+
+- **`Stat` เพิ่ม `icon` / `badge` / `delta` / `tone`** + **`StatGrid`** (Pi Auth มี 17 การ์ดแบบนี้, DueBell มี DeltaBadge เอง): `delta` = `{ value, direction: "up"|"down"|"flat", tone?, hint? }` เลือกไอคอนเทรนด์และสีให้ (ขึ้น = success, ลง = destructive — ทับด้วย `tone` ได้เพราะบางตัวชี้วัด "ลง" คือดี), `icon` มีกรอบพื้นตามโทน, `tone` เปลี่ยนสีตัวเลข (`default|success|warning|destructive|info`); `StatGrid` คอลัมน์ 2|3|4 (มือถือ 1 → sm 2)
+- **`SettingsRow`** / **`SwitchRow`** / **`DangerZone`** (barrel) — แถวตั้งค่า: ชื่อ+คำอธิบายซ้าย control ขวา (จอแคบตกลงมา), `htmlFor` ผูกชื่อกับ control, `tone="destructive"`; `SwitchRow` = แถว + `Switch` ที่ผูก id ให้แล้ว (คลิกชื่อแล้วสลับ) รับ props ของ `Switch` ทั้งหมด; `DangerZone` = กรอบ `border-destructive/40` + พื้น subtle + เส้นคั่นแถว (Pi Auth/Pi PDF เขียน layout นี้ซ้ำ)
+- **`ConfirmDialog` / `useConfirm` `requireText`** — ต้องพิมพ์ข้อความให้ตรงก่อนปุ่มยืนยันจะกดได้ (ลบของที่กู้ไม่ได้ แบบ GitHub); `requireTextLabel` ทับข้อความเหนือช่อง, ค่าเริ่มต้นจาก `UiText.confirmTypeToConfirm`/`…Suffix` (key ใหม่); ปิดกล่องแล้วล้างสิ่งที่พิมพ์เสมอ (ยืนยันรายการถัดไปทันทีไม่ได้) — ใช้ผ่าน `confirm({ requireText: app.name, destructive: true })` ได้เลย
+- **`UserIdentity`** (barrel) — avatar (`Initials` สีพื้นคงที่ต่อชื่อ) + ชื่อ + อีเมล + `badge`/`hint`, `size` sm|default, `hideAvatar`; **ไม่มีชื่อ = ใช้อีเมลเป็นบรรทัดหลัก** (ผู้ใช้ที่ยังไม่ตั้งชื่อ) — Pi Auth เขียนซ้ำ ~15 จุด
+- **`CountBadge`** (barrel) — ป้ายจำนวนท้ายเมนู/แท็บ: เกิน `max` เป็น `99+`, `0` ซ่อนอัตโนมัติ (`showZero` บังคับแสดง), `tone` muted|primary|destructive
+- **`SaveStatus`** (barrel, ยกจาก Pi PDF) — สถานะบันทึกอัตโนมัติบรรทัดเดียว: `saving` (spinner) / `saved` (✓ เขียว) / `error` (`role="alert"`, ข้อความของแอปหรือ `UiText.actionFailed`) / `idle` + `savedAt` = เวลาสัมพัทธ์ผ่าน `ClientDateFormatter` (อัปเดตเองหลัง mount ไม่ทำ hydration mismatch); `language`/`text`
+- **`SliderField`** (barrel, ยกจาก Pi PDF) — ช่องเลื่อน + ป้ายชื่อ + ค่าปัจจุบันมุมขวา: `value`/`onValueChange` เป็น number เดี่ยว, `unit` หรือ `formatValue`, `description`, `size` sm|default, `disabled`
+- **`SkipLink`** (barrel) — ลิงก์ "ข้ามไปเนื้อหา" สำหรับหน้าที่ไม่ได้ใช้ `AppShell` (Pi PDF มีของตัวเอง); `AppShell` เปลี่ยนมาใช้ตัวเดียวกันนี้ภายใน
+- **`FormDialog` `revealSuccess`** — แบบ **ไม่ต้องส่งฟังก์ชัน** จึงใช้จาก **server component** ได้ (รายงานจาก Pi Auth: `renderSuccess` เป็นฟังก์ชัน ข้าม server/client boundary ไม่ได้ → `Functions cannot be passed directly to Client Components`): server action คืน `{ ok: true, data: { values: { "Signing secret": "whsec_…" } } }` แล้ว dialog แสดง `SecretReveal` ให้เอง + ปุ่ม "เสร็จแล้ว" (ไม่ปิดเอง); `successTitle` (ค่าเริ่มต้น `UiText.showOnce`), `successDescription` แทน description ของฟอร์ม — เคส "สร้างแล้วโชว์ secret ครั้งเดียว" (webhook secret / SCIM token / service account key / client secret) ซ้ำกันทุกแอป; `renderSuccess` เดิมยังใช้ได้จาก client component
+- showcase: หน้า `/components/settings-row`, `/components/user-identity` + หน้า `stat` ใหม่ (ไอคอน/delta/StatGrid) — 104 หน้า; tests 9 กรณีเพิ่ม (รวม 163)
+
 ## [0.18.0] — 2026-09-30
 
 > 0.17.0 ถูก publish ตอนที่ `LanguageSwitch` ยังไม่เข้า (commit ถัดไป) — ของชิ้นนี้จึงออกเป็น 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.18.0",
+  "version": "0.19.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/app-shell/app-shell.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { SkipLink } from "@suphark/ui/components/shared/skip-link";
 import {
   InputGroup,
   InputGroupAddon,
@@ -123,16 +124,9 @@ export function AppShell(props: AppShellProps) {
 /** id ของ <main> ของ AppShell (sidebar: SidebarInset, top: main ในเนื้อหา) — ใช้อ้างจาก skip link / anchor */
 export const APP_MAIN_ID = "app-main";
 
-/** ลิงก์ "ข้ามไปเนื้อหา" สำหรับคีย์บอร์ด/screen reader — มองไม่เห็นจนกด Tab ตัวแรก */
+/** ลิงก์ "ข้ามไปเนื้อหา" ของ AppShell — ใช้ `SkipLink` ตัวเดียวกับที่ export ให้แอปใช้นอก AppShell */
 function SkipToMain() {
-  return (
-    <a
-      href={`#${APP_MAIN_ID}`}
-      className="sr-only z-[60] rounded-md bg-background px-3 py-2 text-sm font-medium ring-2 ring-ring focus:not-sr-only focus:fixed focus:top-2 focus:left-2"
-    >
-      ข้ามไปเนื้อหา
-    </a>
-  );
+  return <SkipLink href={`#${APP_MAIN_ID}`} />;
 }
 
 function SidebarShell({

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

@@ -10,8 +10,10 @@ import {
   AlertDialogHeader,
   AlertDialogTitle,
 } from "@suphark/ui/components/ui/alert-dialog";
+import { Input } from "@suphark/ui/components/ui/input";
+import { Label } from "@suphark/ui/components/ui/label";
 import { Loader2 } from "lucide-react";
-import type { ReactNode } from "react";
+import { type ReactNode, useEffect, useId, useState } from "react";
 import { useUiText } from "./ui-text";
 
 /** สเปกการยืนยัน — string = description อย่างเดียว (title/ปุ่มใช้ค่าเริ่มต้นจาก UiText) */
@@ -24,6 +26,10 @@ export type ConfirmSpec =
       cancelLabel?: string;
       /** ปุ่มยืนยันสีแดง (RowActions ใช้ `destructive` ของรายการเป็นค่าเริ่มต้นอยู่แล้ว) */
       destructive?: boolean;
+      /** ต้องพิมพ์ข้อความนี้ให้ตรงก่อนกดยืนยันได้ (ลบของที่กู้คืนไม่ได้ — แบบ GitHub) */
+      requireText?: string;
+      /** คำอธิบายเหนือช่องพิมพ์ (ค่าเริ่มต้น "พิมพ์ \"X\" เพื่อยืนยัน") */
+      requireTextLabel?: ReactNode;
     };
 
 /** แปลง ConfirmSpec เป็น object เสมอ */
@@ -45,6 +51,8 @@ export function ConfirmDialog({
   cancelLabel,
   destructive = false,
   pending = false,
+  requireText,
+  requireTextLabel,
   onConfirm,
 }: {
   open: boolean;
@@ -56,9 +64,19 @@ export function ConfirmDialog({
   /** ปุ่มยืนยันสีแดง (ลบ/เพิกถอน) */
   destructive?: boolean;
   pending?: boolean;
+  /** ต้องพิมพ์ข้อความนี้ให้ตรงก่อนปุ่มยืนยันจะกดได้ (ชื่อแอป/โปรเจกต์ที่กำลังจะลบ) */
+  requireText?: string;
+  requireTextLabel?: ReactNode;
   onConfirm: () => void;
 }) {
   const text = useUiText();
+  const inputId = useId();
+  const [typed, setTyped] = useState("");
+  // เปิดใหม่ทุกครั้ง = ล้างสิ่งที่พิมพ์ไว้ (ไม่ให้ยืนยันรายการถัดไปได้ทันที)
+  useEffect(() => {
+    if (!open) setTyped("");
+  }, [open]);
+  const blocked = Boolean(requireText) && typed.trim() !== requireText;
   return (
     <AlertDialog open={open} onOpenChange={(o) => !pending && onOpenChange(o)}>
       <AlertDialogContent>
@@ -66,11 +84,32 @@ export function ConfirmDialog({
           <AlertDialogTitle>{title ?? text.confirmTitle ?? "ยืนยันการทำรายการ"}</AlertDialogTitle>
           <AlertDialogDescription>{description}</AlertDialogDescription>
         </AlertDialogHeader>
+        {requireText && (
+          <div className="flex flex-col gap-1.5">
+            <Label htmlFor={inputId} className="font-normal text-sm">
+              {requireTextLabel ?? (
+                <>
+                  {text.confirmTypeToConfirm ?? "พิมพ์"}{" "}
+                  <span className="font-medium">{requireText}</span>{" "}
+                  {text.confirmTypeToConfirmSuffix ?? "เพื่อยืนยัน"}
+                </>
+              )}
+            </Label>
+            <Input
+              id={inputId}
+              value={typed}
+              onChange={(e) => setTyped(e.target.value)}
+              autoComplete="off"
+              spellCheck={false}
+              disabled={pending}
+            />
+          </div>
+        )}
         <AlertDialogFooter>
           <AlertDialogCancel disabled={pending}>{cancelLabel ?? text.cancel}</AlertDialogCancel>
           <AlertDialogAction
             variant={destructive ? "destructive" : "default"}
-            disabled={pending}
+            disabled={pending || blocked}
             aria-busy={pending || undefined}
             onClick={onConfirm}
           >

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

@@ -0,0 +1,41 @@
+import { cn } from "@suphark/ui/lib/utils";
+import type { ComponentProps } from "react";
+
+/**
+ * ป้ายจำนวนเล็ก ๆ ท้ายชื่อเมนู/แท็บ/หัวข้อ — เกิน `max` แสดง "99+"; 0 ซ่อนอัตโนมัติ (`showZero` เพื่อบังคับแสดง)
+ *
+ *   ผู้ใช้ <CountBadge value={members.length} />
+ */
+export function CountBadge({
+  value,
+  max = 99,
+  showZero = false,
+  tone = "muted",
+  className,
+  ...props
+}: Omit<ComponentProps<"span">, "children"> & {
+  value: number | null | undefined;
+  max?: number;
+  showZero?: boolean;
+  /** muted = พื้นเทา (ค่าเริ่มต้น), primary/destructive = เน้น (เช่นจำนวนที่ยังไม่อ่าน) */
+  tone?: "muted" | "primary" | "destructive";
+}) {
+  if (value == null || (!showZero && value <= 0)) return null;
+  return (
+    <span
+      data-slot="count-badge"
+      className={cn(
+        "inline-flex min-w-5 shrink-0 items-center justify-center rounded-full px-1.5 font-medium text-label tabular-nums",
+        tone === "primary"
+          ? "bg-primary text-primary-foreground"
+          : tone === "destructive"
+            ? "bg-destructive text-white"
+            : "bg-muted text-muted-foreground",
+        className,
+      )}
+      {...props}
+    >
+      {value > max ? `${max}+` : value}
+    </span>
+  );
+}

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

@@ -0,0 +1,79 @@
+"use client";
+
+import { Label } from "@suphark/ui/components/ui/label";
+import { Slider } from "@suphark/ui/components/ui/slider";
+import { cn } from "@suphark/ui/lib/utils";
+import { type ReactNode, useId } from "react";
+
+export interface SliderFieldProps {
+  label: ReactNode;
+  value: number;
+  onValueChange: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+  /** หน่วยต่อท้ายตัวเลข เช่น "%" หรือ " px" */
+  unit?: string;
+  /** จัดรูปแบบค่าที่แสดงเอง (ทับ `unit`) */
+  formatValue?: (value: number) => ReactNode;
+  description?: ReactNode;
+  disabled?: boolean;
+  /** sm = ระยะห่างแคบ + ป้ายตัวเล็ก */
+  size?: "sm" | "default";
+  id?: string;
+  className?: string;
+}
+
+/**
+ * ช่องเลื่อนพร้อมป้ายชื่อและค่าปัจจุบันมุมขวา (ตั้งค่าที่เป็นตัวเลขต่อเนื่อง เช่น ความละเอียด/ความทึบ)
+ * — ยกจาก Pi PDF; ค่าเป็น number เดี่ยว (ช่วงค่าให้ใช้ `Slider` ตรง ๆ)
+ */
+export function SliderField({
+  label,
+  value,
+  onValueChange,
+  min = 0,
+  max = 100,
+  step = 1,
+  unit = "",
+  formatValue,
+  description,
+  disabled = false,
+  size = "default",
+  id,
+  className,
+}: SliderFieldProps) {
+  const generatedId = useId();
+  const sliderId = id ?? generatedId;
+  return (
+    <div
+      data-slot="slider-field"
+      className={cn(
+        "flex flex-col",
+        size === "sm" ? "gap-1.5" : "gap-2.5",
+        disabled && "pointer-events-none opacity-60",
+        className,
+      )}
+    >
+      <div className="flex items-center justify-between gap-4">
+        <Label htmlFor={sliderId} className={size === "sm" ? "text-xs" : "font-medium text-sm"}>
+          {label}
+        </Label>
+        <span className="font-medium font-mono text-muted-foreground text-xs tabular-nums">
+          {formatValue ? formatValue(value) : `${value}${unit}`}
+        </span>
+      </div>
+      <Slider
+        id={sliderId}
+        value={value}
+        onValueChange={(next) => onValueChange(typeof next === "number" ? next : (next[0] ?? min))}
+        min={min}
+        max={max}
+        step={step}
+        disabled={disabled}
+        aria-label={typeof label === "string" ? label : undefined}
+      />
+      {description && <p className="text-muted-foreground text-xs">{description}</p>}
+    </div>
+  );
+}

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

@@ -1,5 +1,6 @@
 "use client";
 
+import { SecretReveal } from "@suphark/ui/components/shared/secret-reveal";
 import { Button } from "@suphark/ui/components/ui/button";
 import {
   Dialog,
@@ -44,6 +45,9 @@ export function FormDialog<TData = undefined>({
   onOpenChange,
   keepOpen = false,
   renderSuccess,
+  revealSuccess = false,
+  successTitle,
+  successDescription,
   contentClassName,
 }: {
   /** ปุ่มเปิด (ต้องเป็น <Button> ของ shadcn — Base UI จะใช้ตัวนี้เป็น trigger โดยตรง) */
@@ -64,6 +68,17 @@ export function FormDialog<TData = undefined>({
    * ปิดแล้วเปิดใหม่ = ฟอร์มว่าง รอบใหม่ (state เดิมรวม data ถูกทิ้ง ไม่ถูกส่งกลับไปกับ submit ครั้งถัดไป)
    */
   renderSuccess?: (state: Extract<FormState<TData>, { ok: true }>) => ReactNode;
+  /**
+   * แบบไม่ต้องส่งฟังก์ชัน (ใช้จาก **server component** ได้): สำเร็จแล้วถ้า `state.data` เป็น
+   * `{ values: Record<string, string> }` จะแสดง `SecretReveal` ให้เอง พร้อมปุ่ม "เสร็จแล้ว"
+   * (เคส "สร้างแล้วโชว์ secret ครั้งเดียว" — webhook secret / SCIM token / service account key / client secret)
+   * `renderSuccess` เป็นฟังก์ชันจึงข้าม boundary ไม่ได้ (ขอจาก Pi Auth)
+   */
+  revealSuccess?: boolean;
+  /** หัวข้อของ `SecretReveal` เมื่อใช้ `revealSuccess` (ค่าเริ่มต้น `UiText.showOnce`) */
+  successTitle?: string;
+  /** ข้อความใต้หัวข้อของหน้าจอสำเร็จ (แทน `description` ของฟอร์ม) */
+  successDescription?: ReactNode;
   /** ความกว้าง/คลาสของ DialogContent (ค่าเริ่มต้น sm:max-w-md) */
   contentClassName?: string;
 }) {
@@ -84,8 +99,11 @@ export function FormDialog<TData = undefined>({
           description={description}
           action={action}
           submitLabel={submitLabel}
-          keepOpen={keepOpen || renderSuccess !== undefined}
+          keepOpen={keepOpen || renderSuccess !== undefined || revealSuccess}
           renderSuccess={renderSuccess}
+          revealSuccess={revealSuccess}
+          successTitle={successTitle}
+          successDescription={successDescription}
           close={() => setOpen(false)}
         >
           {children}
@@ -103,6 +121,9 @@ function FormDialogBody<TData>({
   children,
   keepOpen,
   renderSuccess,
+  revealSuccess,
+  successTitle,
+  successDescription,
   close,
 }: {
   title: ReactNode;
@@ -112,6 +133,9 @@ function FormDialogBody<TData>({
   children: ReactNode | ((ctx: FormRenderContext) => ReactNode);
   keepOpen: boolean;
   renderSuccess?: (state: Extract<FormState<TData>, { ok: true }>) => ReactNode;
+  revealSuccess?: boolean;
+  successTitle?: string;
+  successDescription?: ReactNode;
   close: () => void;
 }) {
   const router = useRouter();
@@ -129,15 +153,19 @@ function FormDialogBody<TData>({
     }
   }, [state, submitted]);
 
-  if (state?.ok && renderSuccess) {
+  const revealValues = revealSuccess && state?.ok ? revealableValues(state.data) : null;
+
+  if (state?.ok && (renderSuccess || revealValues)) {
+    const successDesc = successDescription ?? description;
     return (
       <div className="flex min-h-0 flex-1 flex-col gap-4">
         <DialogHeader>
           <DialogTitle>{title}</DialogTitle>
-          {description && <DialogDescription>{description}</DialogDescription>}
+          {successDesc && <DialogDescription>{successDesc}</DialogDescription>}
         </DialogHeader>
         <div className="-mx-1 flex min-h-0 flex-1 flex-col gap-3 overflow-y-auto px-1">
-          {renderSuccess(state)}
+          {renderSuccess ? renderSuccess(state) : null}
+          {revealValues && <SecretReveal values={revealValues} title={successTitle} />}
         </div>
         <DialogFooter>
           <Button type="button" onClick={close}>
@@ -179,3 +207,14 @@ function FormDialogBody<TData>({
     </form>
   );
 }
+
+/** `data` ของ server action เป็น `{ values: Record<string, string> }` ไหม (ใช้กับ `revealSuccess`) */
+function revealableValues(data: unknown): Record<string, string> | null {
+  if (!data || typeof data !== "object" || !("values" in data)) return null;
+  const { values } = data as { values: unknown };
+  if (!values || typeof values !== "object") return null;
+  const entries = Object.entries(values as Record<string, unknown>).filter(
+    ([, v]) => typeof v === "string",
+  ) as Array<[string, string]>;
+  return entries.length > 0 ? Object.fromEntries(entries) : null;
+}

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

@@ -0,0 +1,99 @@
+"use client";
+
+import { ClientDateFormatter } from "@suphark/ui/components/shared/time/client-date-formatter";
+import { useUiText } from "@suphark/ui/components/shared/ui-text";
+import { cn } from "@suphark/ui/lib/utils";
+import { AlertCircle, Check, Loader2 } from "lucide-react";
+import type { ReactNode } from "react";
+
+export type SaveState = "idle" | "saving" | "saved" | "error";
+
+export interface SaveStatusText {
+  saving: string;
+  saved: string;
+  error: string;
+  /** นำหน้าเวลาที่บันทึกล่าสุด เช่น "บันทึกเมื่อ" */
+  savedAt: string;
+}
+
+const TEXT: Record<"th" | "en", SaveStatusText> = {
+  th: { saving: "กำลังบันทึก…", saved: "บันทึกแล้ว", error: "บันทึกไม่สำเร็จ", savedAt: "บันทึกเมื่อ" },
+  en: { saving: "Saving…", saved: "Saved", error: "Couldn't save", savedAt: "Saved" },
+};
+
+/**
+ * สถานะบันทึกอัตโนมัติแบบบรรทัดเดียว (ยกจาก Pi PDF) — วางใน toolbar/หัวหน้า
+ * `savedAt` ใส่มาแล้วจะแสดงเวลาสัมพัทธ์ที่อัปเดตเองฝั่ง client (ไม่ทำ hydration mismatch)
+ */
+export function SaveStatus({
+  state,
+  savedAt,
+  error,
+  language = "th",
+  text: textProp,
+  className,
+}: {
+  state: SaveState;
+  /** เวลาที่บันทึกล่าสุด — แสดงเป็นเวลาสัมพัทธ์เมื่อ state = "saved"/"idle" */
+  savedAt?: Date | string | number | null;
+  /** ข้อความ error ของแอป (ไม่ส่ง = ข้อความเริ่มต้น) */
+  error?: ReactNode;
+  language?: "th" | "en";
+  text?: Partial<SaveStatusText>;
+  className?: string;
+}) {
+  const ui = useUiText();
+  const text: SaveStatusText = { ...TEXT[language], ...textProp };
+  const base = cn("inline-flex items-center gap-1.5 text-xs", className);
+
+  if (state === "saving") {
+    return (
+      <span
+        data-slot="save-status"
+        data-state="saving"
+        aria-live="polite"
+        className={cn(base, "text-muted-foreground")}
+      >
+        <Loader2 className="size-3.5 animate-spin" aria-hidden="true" />
+        {text.saving}
+      </span>
+    );
+  }
+  if (state === "error") {
+    return (
+      <span
+        data-slot="save-status"
+        data-state="error"
+        role="alert"
+        className={cn(base, "text-destructive")}
+      >
+        <AlertCircle className="size-3.5" aria-hidden="true" />
+        {error ?? ui.actionFailed ?? text.error}
+      </span>
+    );
+  }
+  if (state === "saved") {
+    return (
+      <span
+        data-slot="save-status"
+        data-state="saved"
+        aria-live="polite"
+        className={cn(base, "text-success")}
+      >
+        <Check className="size-3.5" aria-hidden="true" />
+        {text.saved}
+      </span>
+    );
+  }
+  if (!savedAt) return null;
+  return (
+    <span data-slot="save-status" data-state="idle" className={cn(base, "text-muted-foreground")}>
+      {text.savedAt}{" "}
+      <ClientDateFormatter
+        date={savedAt}
+        formatType="relative"
+        locale={language === "en" ? "en-US" : "th-TH"}
+      />
+    </span>
+  );
+}

package/src/components/shared/settings-row.tsx

@@ -0,0 +1,118 @@
+"use client";
+
+import { Switch } from "@suphark/ui/components/ui/switch";
+import { cn } from "@suphark/ui/lib/utils";
+import { type ComponentProps, type ReactNode, useId } from "react";
+
+/**
+ * แถวตั้งค่า: ชื่อ + คำอธิบายด้านซ้าย, control ด้านขวา (จอแคบตกลงมาอยู่ใต้ข้อความ)
+ * ใช้เป็นแถวในหน้าตั้งค่า/โซนอันตราย — ยกจาก Pi Auth/Pi PDF ที่เขียน layout เดียวกันซ้ำ
+ */
+export function SettingsRow({
+  title,
+  description,
+  children,
+  htmlFor,
+  tone = "default",
+  className,
+}: {
+  title: ReactNode;
+  description?: ReactNode;
+  /** control ด้านขวา (Switch, Button, Select …) */
+  children?: ReactNode;
+  /** ผูกชื่อแถวกับ control ด้วย id (ทำให้คลิกชื่อแล้วโฟกัส control) */
+  htmlFor?: string;
+  /** destructive = แถวในโซนอันตราย (ชื่อสีแดง) */
+  tone?: "default" | "destructive";
+  className?: string;
+}) {
+  const Title = htmlFor ? "label" : "span";
+  return (
+    <div
+      data-slot="settings-row"
+      className={cn(
+        "flex flex-col gap-3 py-3 sm:flex-row sm:items-center sm:justify-between sm:gap-6",
+        className,
+      )}
+    >
+      <div className="flex min-w-0 flex-col gap-0.5">
+        <Title
+          {...(htmlFor ? { htmlFor } : {})}
+          className={cn(
+            "font-medium text-sm",
+            tone === "destructive" && "text-destructive",
+            htmlFor && "cursor-pointer",
+          )}
+        >
+          {title}
+        </Title>
+        {description && <span className="text-muted-foreground text-xs">{description}</span>}
+      </div>
+      {children && <div className="flex shrink-0 items-center gap-2">{children}</div>}
+    </div>
+  );
+}
+
+/**
+ * แถวตั้งค่าแบบเปิด/ปิด — `SettingsRow` + `Switch` ที่ผูก id ให้แล้ว (คลิกชื่อแล้วสลับได้)
+ *
+ *   <SwitchRow title="แจ้งเตือนทางอีเมล" description="ส่งสรุปทุกเช้า" checked={on} onCheckedChange={setOn} />
+ */
+export function SwitchRow({
+  title,
+  description,
+  checked,
+  onCheckedChange,
+  disabled,
+  id,
+  className,
+  ...props
+}: Omit<ComponentProps<typeof Switch>, "title"> & {
+  title: ReactNode;
+  description?: ReactNode;
+  className?: string;
+}) {
+  const generatedId = useId();
+  const switchId = id ?? generatedId;
+  return (
+    <SettingsRow title={title} description={description} htmlFor={switchId} className={className}>
+      <Switch
+        {...props}
+        id={switchId}
+        checked={checked}
+        onCheckedChange={onCheckedChange}
+        disabled={disabled}
+      />
+    </SettingsRow>
+  );
+}
+
+/**
+ * โซนอันตราย (Clerk/GitHub "Danger zone"): กรอบแดงอ่อน + แถวการกระทำที่ย้อนกลับไม่ได้
+ * แอปใส่ `SettingsRow tone="destructive"` เป็นลูก (ปุ่มจริงใช้ `ConfirmActionButton`/`useConfirm` ของแพ็กเกจ)
+ */
+export function DangerZone({
+  title,
+  description,
+  children,
+  className,
+}: {
+  title?: ReactNode;
+  description?: ReactNode;
+  children: ReactNode;
+  className?: string;
+}) {
+  return (
+    <section
+      data-slot="danger-zone"
+      className={cn(
+        "flex flex-col gap-1 rounded-xl border border-destructive/40 bg-destructive-subtle/40 p-4",
+        className,
+      )}
+    >
+      {title && <h2 className="font-semibold text-destructive text-sm">{title}</h2>}
+      {description && <p className="text-muted-foreground text-xs">{description}</p>}
+      <div className="divide-y divide-destructive/20">{children}</div>
+    </section>
+  );
+}

package/src/components/shared/skip-link.tsx

@@ -0,0 +1,30 @@
+import { cn } from "@suphark/ui/lib/utils";
+import type { ReactNode } from "react";
+
+/**
+ * ลิงก์ "ข้ามไปเนื้อหา" — element แรกที่ Tab จาก address bar เจอ แล้วกด Enter ข้าม header/เมนูไปที่เนื้อหา
+ * มองไม่เห็นจนกว่าจะโฟกัส; `AppShell` ใส่ให้แล้ว (`href="#app-main"`) — ตัวนี้สำหรับหน้าที่ไม่ได้ใช้ AppShell
+ * (เช่นหน้า login/เอกสารของ Pi PDF ที่เขียนเอง) — จำไว้ว่าเป้าหมายต้องมี `tabIndex={-1}`
+ */
+export function SkipLink({
+  href = "#main-content",
+  children = "ข้ามไปเนื้อหา",
+  className,
+}: {
+  href?: string;
+  children?: ReactNode;
+  className?: string;
+}) {
+  return (
+    <a
+      data-slot="skip-link"
+      href={href}
+      className={cn(
+        "sr-only z-[60] rounded-md bg-background px-3 py-2 font-medium text-sm ring-2 ring-ring focus:not-sr-only focus:fixed focus:top-2 focus:left-2",
+        className,
+      )}
+    >
+      {children}
+    </a>
+  );
+}

package/src/components/shared/stat.tsx

@@ -1,26 +1,130 @@
 import { Card, CardContent } from "@suphark/ui/components/ui/card";
 import { cn } from "@suphark/ui/lib/utils";
+import { Minus, TrendingDown, TrendingUp } from "lucide-react";
 import type { ReactNode } from "react";
 
-/** ตัวเลขสรุปบนหน้าภาพรวม/สุขภาพระบบ */
+export type StatTone = "default" | "success" | "warning" | "destructive" | "info";
+
+const TONE_TEXT: Record<StatTone, string> = {
+  default: "text-foreground",
+  success: "text-success",
+  warning: "text-warning",
+  destructive: "text-destructive",
+  info: "text-info",
+};
+const TONE_ICON: Record<StatTone, string> = {
+  default: "bg-muted text-muted-foreground",
+  success: "bg-success-subtle text-success-subtle-foreground",
+  warning: "bg-warning-subtle text-warning-subtle-foreground",
+  destructive: "bg-destructive-subtle text-destructive-subtle-foreground",
+  info: "bg-info-subtle text-info-subtle-foreground",
+};
+
+export interface StatDelta {
+  /** ข้อความที่แสดง เช่น "+12%" หรือ "+3 สัปดาห์นี้" */
+  value: ReactNode;
+  /** ขึ้น = ดี/ไม่ดี ต่างกันไปตามตัวชี้วัด → แอปบอกโทนเอง (ค่าเริ่มต้นดูจาก direction) */
+  direction?: "up" | "down" | "flat";
+  tone?: StatTone;
+  /** ข้อความเทียบ เช่น "จากเดือนก่อน" */
+  hint?: ReactNode;
+}
+
+const DELTA_ICON = { up: TrendingUp, down: TrendingDown, flat: Minus };
+
+/**
+ * ตัวเลขสรุปบนหน้าภาพรวม/สุขภาพระบบ — เพิ่มไอคอน, ป้าย และส่วนต่างจากช่วงก่อนได้
+ * (Pi Auth มี 17 การ์ดแบบนี้, DueBell มี DeltaBadge ของตัวเอง)
+ */
 export function Stat({
   label,
   value,
   hint,
+  icon,
+  badge,
+  delta,
+  tone = "default",
   className,
 }: {
   label: ReactNode;
   value: ReactNode;
   hint?: ReactNode;
+  /** ไอคอนมุมขวาบน (ใส่กรอบพื้นตาม `tone` ให้) */
+  icon?: ReactNode;
+  /** ป้ายท้ายป้ายชื่อ เช่น `<StatusBadge>` */
+  badge?: ReactNode;
+  /** ส่วนต่างจากช่วงก่อน */
+  delta?: StatDelta;
+  /** โทนของตัวเลขและไอคอน */
+  tone?: StatTone;
   className?: string;
 }) {
+  const direction = delta?.direction ?? "flat";
+  const DeltaIcon = DELTA_ICON[direction];
+  const deltaTone =
+    delta?.tone ??
+    (direction === "up" ? "success" : direction === "down" ? "destructive" : "default");
+
   return (
-    <Card className={cn("gap-1 py-4", className)}>
-      <CardContent className="flex flex-col gap-1">
-        <span className="text-xs font-medium text-muted-foreground">{label}</span>
-        <span className="text-2xl font-semibold tabular-nums tracking-tight">{value}</span>
-        {hint && <span className="text-xs text-muted-foreground">{hint}</span>}
+    <Card data-slot="stat" className={cn("gap-1 py-4", className)}>
+      <CardContent className="flex items-start gap-3">
+        <div className="flex min-w-0 flex-1 flex-col gap-1">
+          <span className="flex items-center gap-1.5 font-medium text-muted-foreground text-xs">
+            <span className="truncate">{label}</span>
+            {badge}
+          </span>
+          <span
+            className={cn("font-semibold text-2xl tabular-nums tracking-tight", TONE_TEXT[tone])}
+          >
+            {value}
+          </span>
+          {delta && (
+            <span className="flex items-center gap-1 text-xs">
+              <span className={cn("flex items-center gap-0.5 font-medium", TONE_TEXT[deltaTone])}>
+                <DeltaIcon className="size-3.5" aria-hidden="true" />
+                {delta.value}
+              </span>
+              {delta.hint && <span className="text-muted-foreground">{delta.hint}</span>}
+            </span>
+          )}
+          {hint && <span className="text-muted-foreground text-xs">{hint}</span>}
+        </div>
+        {icon && (
+          <span
+            aria-hidden="true"
+            className={cn(
+              "grid size-9 shrink-0 place-items-center rounded-lg [&_svg]:size-4",
+              TONE_ICON[tone],
+            )}
+          >
+            {icon}
+          </span>
+        )}
       </CardContent>
     </Card>
   );
 }
+
+/** กริดของ `Stat` — คอลัมน์ตามจำนวนที่ต้องการ (ค่าเริ่มต้น 1 → 2 → 4 ตามความกว้างจอ) */
+export function StatGrid({
+  children,
+  columns = 4,
+  className,
+}: {
+  children: ReactNode;
+  columns?: 2 | 3 | 4;
+  className?: string;
+}) {
+  return (
+    <div
+      data-slot="stat-grid"
+      className={cn(
+        "grid gap-3 sm:grid-cols-2",
+        columns === 2 ? "lg:grid-cols-2" : columns === 3 ? "lg:grid-cols-3" : "lg:grid-cols-4",
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+}

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

@@ -53,6 +53,9 @@ export interface UiText {
   search?: Partial<{ placeholder: string; label: string; clear: string }>;
   /** LanguageSwitch/LanguageMenuItems: หัวกลุ่ม + aria-label ปุ่ม (optional — "ภาษา") */
   language?: Partial<{ label: string }>;
+  /** ConfirmDialog `requireText`: คำนำหน้า/ต่อท้ายช่องพิมพ์ยืนยัน (optional — "พิมพ์" … "เพื่อยืนยัน") */
+  confirmTypeToConfirm?: string;
+  confirmTypeToConfirmSuffix?: string;
 }
 
 export const UI_TEXT_TH: UiText = {
@@ -88,6 +91,8 @@ export const UI_TEXT_TH: UiText = {
   sectionNav: { tabs: "แท็บย่อย" },
   search: { placeholder: "ค้นหา…", label: "ค้นหา", clear: "ล้างการค้นหา" },
   language: { label: "ภาษา" },
+  confirmTypeToConfirm: "พิมพ์",
+  confirmTypeToConfirmSuffix: "เพื่อยืนยัน",
 };
 
 export const UI_TEXT_EN: UiText = {
@@ -123,6 +128,8 @@ export const UI_TEXT_EN: UiText = {
   sectionNav: { tabs: "Section tabs" },
   search: { placeholder: "Search…", label: "Search", clear: "Clear search" },
   language: { label: "Language" },
+  confirmTypeToConfirm: "Type",
+  confirmTypeToConfirmSuffix: "to confirm",
 };
 
 const UiTextContext = createContext<UiText>(UI_TEXT_TH);

package/src/components/shared/user-identity.tsx

@@ -0,0 +1,61 @@
+import { Initials } from "@suphark/ui/components/shared/initials";
+import { cn } from "@suphark/ui/lib/utils";
+import type { ReactNode } from "react";
+
+export interface UserIdentityProps {
+  name: string | null | undefined;
+  /** บรรทัดรอง — ปกติคืออีเมล */
+  email?: ReactNode;
+  /** รูปโปรไฟล์ (ไม่มี = ตัวย่อชื่อพร้อมสีพื้นคงที่ต่อชื่อ) */
+  src?: string | null;
+  /** ต่อท้ายชื่อ เช่น `<StatusBadge>` หรือป้าย "คุณ" */
+  badge?: ReactNode;
+  /** ใต้บรรทัดอีเมล เช่น "เข้าใช้ล่าสุด 2 ชม.ที่แล้ว" */
+  hint?: ReactNode;
+  /** sm = ใช้ในแถวตาราง (avatar size-7), default = size-9 */
+  size?: "sm" | "default";
+  /** ซ่อน avatar (เมื่อแถวมีรูปอยู่แล้ว) */
+  hideAvatar?: boolean;
+  className?: string;
+}
+
+/**
+ * ชื่อผู้ใช้ + อีเมล + avatar ในบล็อกเดียว — แถวตาราง, เมนู, การ์ดสมาชิก (Pi Auth เขียนซ้ำ ~15 จุด)
+ * ชื่อว่าง = แสดงอีเมลเป็นบรรทัดหลักแทน (ผู้ใช้ที่ยังไม่ตั้งชื่อ)
+ */
+export function UserIdentity({
+  name,
+  email,
+  src,
+  badge,
+  hint,
+  size = "default",
+  hideAvatar = false,
+  className,
+}: UserIdentityProps) {
+  const displayName = name?.trim() || null;
+  const primary = displayName ?? (typeof email === "string" ? email : null);
+  const secondary = displayName ? email : null;
+
+  return (
+    <div data-slot="user-identity" className={cn("flex min-w-0 items-center gap-2", className)}>
+      {!hideAvatar && (
+        <Initials
+          name={displayName ?? (typeof email === "string" ? email : "")}
+          src={src}
+          className={size === "sm" ? "size-7" : "size-9"}
+        />
+      )}
+      <div className="flex min-w-0 flex-col">
+        <span className="flex items-center gap-1.5">
+          <span className={cn("truncate font-medium", size === "sm" ? "text-sm" : "text-sm")}>
+            {primary ?? "—"}
+          </span>
+          {badge}
+        </span>
+        {secondary && <span className="truncate text-muted-foreground text-xs">{secondary}</span>}
+        {hint && <span className="truncate text-muted-foreground text-xs">{hint}</span>}
+      </div>
+    </div>
+  );
+}

package/src/hooks/use-confirm.tsx

@@ -55,6 +55,8 @@ export function useConfirm(): {
       confirmLabel={request.options.confirmLabel}
       cancelLabel={request.options.cancelLabel}
       destructive={request.options.destructive}
+      requireText={request.options.requireText}
+      requireTextLabel={request.options.requireTextLabel}
       onConfirm={() => settle(true)}
     />
   ) : null;

package/src/index.ts

@@ -37,6 +37,7 @@ export {
   type ConfirmSpec,
   normalizeConfirm,
 } from "./components/shared/confirm-dialog";
+export { CountBadge } from "./components/shared/count-badge";
 export { DataList, DataRow } from "./components/shared/data-list";
 export { DateRangePicker } from "./components/shared/date/date-range-picker";
 export { DescriptionList } from "./components/shared/description-list";
@@ -84,6 +85,7 @@ export {
   type SimpleSelectOptions,
   type SimpleSelectProps,
 } from "./components/shared/form/simple-select";
+export { SliderField, type SliderFieldProps } from "./components/shared/form/slider-field";
 export {
   type FormAction,
   FormMessage,
@@ -136,10 +138,13 @@ export {
   type RuleLeaf,
   type RuleNot,
 } from "./components/shared/rule-builder";
+export { type SaveState, SaveStatus, type SaveStatusText } from "./components/shared/save-status";
 export { SecretReveal } from "./components/shared/secret-reveal";
 export { SectionCard } from "./components/shared/section-card";
 export { SelectionButton } from "./components/shared/selection-button";
-export { Stat } from "./components/shared/stat";
+export { DangerZone, SettingsRow, SwitchRow } from "./components/shared/settings-row";
+export { SkipLink } from "./components/shared/skip-link";
+export { Stat, type StatDelta, StatGrid, type StatTone } from "./components/shared/stat";
 export { StatusBadge, statusTone, type Tone } from "./components/shared/status-badge";
 export { SwitcherChevron } from "./components/shared/switcher-chevron";
 export { CodeBlock, type CodeBlockProps } from "./components/shared/text/code-block";
@@ -164,6 +169,7 @@ export {
   type UploadListText,
   type UploadStatus,
 } from "./components/shared/upload-list";
+export { UserIdentity, type UserIdentityProps } from "./components/shared/user-identity";
 // ---------- shadcn/ui primitives ----------
 export * from "./components/ui/accordion";
 export * from "./components/ui/alert";