@suphark/ui 0.1.0

package/src/components/design-system/sections/showcase-guidelines-recipes.tsx

@@ -0,0 +1,397 @@
+"use client";
+
+import { Badge } from "@suphark/ui/components/ui/badge";
+import { Button } from "@suphark/ui/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@suphark/ui/components/ui/card";
+import {
+  Accessibility,
+  Check,
+  CheckCircle2,
+  Code2,
+  Copy,
+  MessageSquare,
+  RefreshCw,
+} from "lucide-react";
+import * as React from "react";
+
+export function ShowcaseGuidelinesRecipes() {
+  const [copiedIndex, setCopiedIndex] = React.useState<number | null>(null);
+
+  const copyCode = (code: string, idx: number) => {
+    navigator.clipboard.writeText(code);
+    setCopiedIndex(idx);
+    setTimeout(() => setCopiedIndex(null), 2000);
+  };
+
+  const a11yRules = [
+    {
+      title: "Focus Visible Rings",
+      rule: "ทุก interactive element ต้องมี focus ring ชัดเจน",
+      detail:
+        "ใช้คลาส focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none เพื่อให้ผู้ใช้คีย์บอร์ดรับรู้ตำแหน่งปัจจุบันได้แม่นยำ",
+      tag: "Keyboard A11y",
+    },
+    {
+      title: "Icon-Only Button Accessible Names",
+      rule: "ปุ่มที่มีเฉพาะไอคอนต้องมี aria-label เสมอ",
+      detail:
+        "<Button size='icon' aria-label='ลบแพ็กเกจ'><Trash2 /></Button> เพื่อให้ Screen Reader อ่านออกเสียงความหมายของปุ่มได้ถูกต้อง",
+      tag: "Screen Reader",
+    },
+    {
+      title: "Dialog / Sheet Titles & Descriptions",
+      rule: "Modal ทุกตัวต้องมี DialogTitle และ DialogDescription",
+      detail:
+        "Base UI ต้องการ Title สำหรับ ARIA header ถ้าไม่ต้องการให้แสดงผลทางสายตาให้ใช้ className='sr-only'",
+      tag: "Dialog Semantics",
+    },
+    {
+      title: "Error Recovery & Tone of Voice",
+      rule: "ข้อความ Error ต้องชี้แนะวิธีแก้ไข โดยไม่กล่าวโทษผู้ใช้",
+      detail:
+        "บอกสิ่งที่เกิดขึ้นและวิธีแก้ให้ตรงจุด เช่น 'ระบุงบประมาณเป็นตัวเลขมากกว่า 0 บาท' แทน 'คุณกรอกข้อมูลผิดพลาด'",
+      tag: "UX Copy",
+    },
+    {
+      title: "Reduced Motion Respect",
+      rule: "เคารพการตั้งค่าลดการเคลื่อนไหวของผู้ใช้",
+      detail:
+        "ระบบ Tailwind v4 รองรับ motion-reduce อัตโนมัติ เลี่ยงการใส่แอนิเมชันที่ไม่จำเป็นในหน้างานทำงานข้อมูล",
+      tag: "Motion",
+    },
+  ];
+
+  const uxWritingRules = [
+    {
+      bad: "Submit / ยืนยัน",
+      good: "Save changes / บันทึกการเปลี่ยนแปลง",
+      why: "ปุ่มควรระบุสิ่งที่จะเกิดขึ้นกับระบบโดยตรง (Active Voice)",
+    },
+    {
+      bad: "Delete / ลบ",
+      good: "Delete package / ลบแพ็กเกจจัดซื้อ",
+      why: "ระบุเป้าหมายของ Action เพื่อป้องกันการกดลบผิดพลาด",
+    },
+    {
+      bad: "คลิกที่ 'Publish' -> Toast 'บันทึกสำเร็จ'",
+      good: "คลิกที่ 'Publish' -> Toast 'Published package successfully'",
+      why: "รักษาความสอดคล้องของคำศัพท์จากปุ่มไปยังผลลัพธ์ (Action-to-Toast Consistency)",
+    },
+    {
+      bad: "ไม่พบข้อมูล กรุณาลองใหม่อีกครั้ง",
+      good: "ยังไม่มีแพ็กเกจจัดซื้อในโครงการนี้ [สร้างแพ็กเกจใหม่]",
+      why: "Empty State คือคำเชิญชวนให้เริ่มต้นทำ Action ต่อไป ไม่ใช่ทางตัน",
+    },
+  ];
+
+  const recipe1 = `// 1. PageShell + Toolbar + DataTable Pattern
+import { PageShell } from "@suphark/ui/components/shared/layout/page-shell";
+import { AddNewButton } from "@suphark/ui/components/shared/button";
+import { DataTable } from "@suphark/ui/components/shared/data-table/data-table";
+
+export default function PackageListPage() {
+  return (
+    <PageShell
+      title="แพ็กเกจจัดซื้อ (Procurement Packages)"
+      description="จัดการและติดตามสถานะการเปิดซองราคาและจัดจ้างผู้รับเหมา"
+      actions={<AddNewButton label="สร้างแพ็กเกจจัดซื้อ" />}
+    >
+      <div className="flex flex-col gap-4">
+        {/* Toolbar Filters */}
+        <div className="flex items-center justify-between gap-3">
+          <PackageSearchFilter />
+          <PackageStatusFilter />
+        </div>
+
+        {/* Dynamic Table with Suspense Fallback */}
+        <PackageDataTable />
+      </div>
+    </PageShell>
+  );
+}`;
+
+  const recipe2 = `// 2. FieldGroup + InputGroup + Server Action Validation
+import { FieldGroup, Field, FieldLabel, FieldDescription, FieldError } from "@suphark/ui/components/ui/field";
+import { InputGroup, InputGroupAddon, InputGroupInput } from "@suphark/ui/components/ui/input-group";
+import { DollarSign } from "lucide-react";
+
+export function BudgetField({ state }: { state?: ActionResponse }) {
+  const isInvalid = Boolean(state?.errors?.budget);
+
+  return (
+    <FieldGroup>
+      <Field data-invalid={isInvalid ? true : undefined}>
+        <FieldLabel htmlFor="budget-input">งบประมาณกลาง (THB)</FieldLabel>
+        <InputGroup>
+          <InputGroupAddon>
+            <DollarSign className="size-4 text-muted-foreground" />
+          </InputGroupAddon>
+          <InputGroupInput
+            id="budget-input"
+            name="budget"
+            aria-invalid={isInvalid ? true : undefined}
+            placeholder="0.00"
+          />
+        </InputGroup>
+        {isInvalid ? (
+          <FieldError>{state.errors.budget[0]}</FieldError>
+        ) : (
+          <FieldDescription>ระบุจำนวนเงินสุทธิรวม VAT 7%</FieldDescription>
+        )}
+      </Field>
+    </FieldGroup>
+  );
+}`;
+
+  const recipe3 = `// 3. Destructive Confirmation AlertDialog
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  AlertDialogTrigger,
+} from "@suphark/ui/components/ui/alert-dialog";
+import { Button } from "@suphark/ui/components/ui/button";
+
+export function DeletePackageDialog({ packageId }: { packageId: string }) {
+  return (
+    <AlertDialog>
+      <AlertDialogTrigger render={<Button variant="destructive" size="sm" />}>
+        ลบแพ็กเกจ
+      </AlertDialogTrigger>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>ยืนยันการลบแพ็กเกจจัดซื้อ?</AlertDialogTitle>
+          <AlertDialogDescription>
+            การกระทำนี้จะลบใบเสนอราคาและเอกสารแนบทั้งหมดอย่างถาวร และไม่สามารถกู้คืนได้
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>ยกเลิก</AlertDialogCancel>
+          <AlertDialogAction variant="destructive" onClick={() => handleDelete(packageId)}>
+            ยืนยันการลบแพ็กเกจ
+          </AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}`;
+
+  const recipe4 = `// 4. Server Action Trigger Button with Loading Spinner & Toast
+"use client";
+
+import { useTransition } from "react";
+import { Button } from "@suphark/ui/components/ui/button";
+import { Spinner } from "@suphark/ui/components/ui/spinner";
+import { toast } from "sonner";
+import { approvePackageAction } from "../actions/approve-package";
+
+export function ApprovePackageButton({ id }: { id: string }) {
+  const [isPending, startTransition] = useTransition();
+
+  const handleApprove = () => {
+    startTransition(async () => {
+      const res = await approvePackageAction(id);
+      if (res.success) {
+        toast.success("อนุมัติแพ็กเกจสำเร็จ", {
+          description: "ส่งการแจ้งเตือนไปยังผู้เสนอราคาเรียบร้อยแล้ว",
+        });
+      } else {
+        toast.error("การอนุมัติล้มเหลว", { description: res.error });
+      }
+    });
+  };
+
+  return (
+    <Button onClick={handleApprove} disabled={isPending}>
+      {isPending && <Spinner data-icon="inline-start" />}
+      {isPending ? "กำลังอนุมัติ..." : "อนุมัติแพ็กเกจ"}
+    </Button>
+  );
+}`;
+
+  const recipes = [
+    { title: "1. PageShell + Toolbar + Table", code: recipe1 },
+    { title: "2. Unified FieldGroup & Validation", code: recipe2 },
+    { title: "3. Destructive Confirmation AlertDialog", code: recipe3 },
+    { title: "4. Server Action Button + Spinner + Toast", code: recipe4 },
+  ];
+
+  return (
+    <div className="flex flex-col gap-8">
+      {/* Section Header */}
+      <div className="flex flex-col gap-1">
+        <div className="flex items-center gap-2">
+          <Badge variant="outline">Rules & Recipes</Badge>
+          <span className="text-xs text-muted-foreground">
+            Web Interface Guidelines, UX Copy Standards & Production Code Recipes
+          </span>
+        </div>
+        <h2 className="text-xl font-bold tracking-tight text-foreground">
+          แนวปฏิบัติและแม่แบบโค้ดมาตรฐาน (Guidelines & Code Recipes)
+        </h2>
+        <p className="text-sm text-muted-foreground">
+          สรุปเกณฑ์การตรวจสอบ Accessibility, กฎการเขียน UX Copy สำหรับผู้ใช้,
+          และแม่แบบโค้ดที่สามารถนำไปใช้งานได้ทันที
+        </p>
+      </div>
+
+      {/* Web Interface Guidelines Checklist */}
+      <Card>
+        <CardHeader>
+          <div className="flex items-center justify-between">
+            <div>
+              <CardTitle className="text-base flex items-center gap-2">
+                <Accessibility className="size-4 text-primary" /> Web Interface Guidelines
+                (Mandatory Baseline)
+              </CardTitle>
+              <CardDescription className="text-xs">
+                เกณฑ์มาตรฐานสากลที่ทุกหน้าจอต้องผ่านการตรวจสอบ
+              </CardDescription>
+            </div>
+            <Badge variant="secondary">A11y Baseline</Badge>
+          </div>
+        </CardHeader>
+        <CardContent className="grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+          {a11yRules.map((rule) => (
+            <div key={rule.title} className="flex flex-col gap-1.5 rounded-lg border bg-card p-3">
+              <div className="flex items-center justify-between">
+                <Badge variant="outline" className="text-xs">
+                  {rule.tag}
+                </Badge>
+                <CheckCircle2 className="size-3.5 text-primary" />
+              </div>
+              <h4 className="font-semibold text-xs text-foreground pt-1">{rule.title}</h4>
+              <p className="text-xs text-primary/90 font-medium">{rule.rule}</p>
+              <p className="text-xs text-muted-foreground leading-normal">{rule.detail}</p>
+            </div>
+          ))}
+        </CardContent>
+      </Card>
+
+      {/* UX Writing & Copy Standards */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base flex items-center gap-2">
+            <MessageSquare className="size-4 text-primary" /> Frontend Design: UX Writing & Action
+            Voice
+          </CardTitle>
+          <CardDescription className="text-xs">
+            การใช้ภาษาที่ชัดเจนและมุ่งเน้นสิ่งที่ผู้ใช้ควบคุมได้ (Active Voice & Cohesion)
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-3 md:grid-cols-2">
+          {uxWritingRules.map((item) => (
+            <div key={item.bad} className="flex flex-col gap-2 rounded-lg border p-3 bg-card">
+              <div className="flex flex-col gap-1 text-xs">
+                <div className="flex items-start gap-2 text-destructive">
+                  <span className="font-bold">✕ หลีกเลี่ยง:</span>
+                  <span className="line-through">{item.bad}</span>
+                </div>
+                <div className="flex items-start gap-2 text-emerald-600 font-medium">
+                  <span className="font-bold">✓ แนะนำ:</span>
+                  <span>{item.good}</span>
+                </div>
+              </div>
+              <p className="text-xs text-muted-foreground pt-1 border-t border-dashed">
+                {item.why}
+              </p>
+            </div>
+          ))}
+        </CardContent>
+      </Card>
+
+      {/* Redesign Workflow Checklist */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-base flex items-center gap-2">
+            <RefreshCw className="size-4 text-primary" /> Redesign Safety: Behavior Preservation
+            Checklist
+          </CardTitle>
+          <CardDescription className="text-xs">
+            เมื่อทำการ Redesign UI ต้องคงความสามารถของระบบเดิม 100%
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4 text-xs">
+          <div className="flex flex-col gap-1 rounded-md border p-3 bg-card">
+            <span className="font-semibold text-foreground">1. Auth & Permissions</span>
+            <p className="text-muted-foreground">
+              คงการตรวจสิทธิ์ 7-action RBAC และ Server Action Guard เดิม
+            </p>
+          </div>
+          <div className="flex flex-col gap-1 rounded-md border p-3 bg-card">
+            <span className="font-semibold text-foreground">2. Data Contracts</span>
+            <p className="text-muted-foreground">
+              คง Form validation schema, ActionResponse&lt;T&gt; และ API types
+            </p>
+          </div>
+          <div className="flex flex-col gap-1 rounded-md border p-3 bg-card">
+            <span className="font-semibold text-foreground">3. URL & Search State</span>
+            <p className="text-muted-foreground">
+              คง Query params สำหรับ Search, Filter, Tab และ Pagination
+            </p>
+          </div>
+          <div className="flex flex-col gap-1 rounded-md border p-3 bg-card">
+            <span className="font-semibold text-foreground">4. Loading & Error States</span>
+            <p className="text-muted-foreground">
+              คง Skeletons, Suspense Boundaries, Error Boundaries, และ Empty views
+            </p>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Code Recipes */}
+      <section className="flex flex-col gap-4">
+        <div className="flex items-center justify-between">
+          <div>
+            <h3 className="text-base font-semibold flex items-center gap-2">
+              <Code2 className="size-4 text-primary" /> Production Code Recipes
+            </h3>
+            <p className="text-xs text-muted-foreground">แม่แบบโค้ดที่พร้อมคัดลอกไปใช้งานในฟีเจอร์ต่าง ๆ</p>
+          </div>
+        </div>
+
+        <div className="grid gap-6 xl:grid-cols-2">
+          {recipes.map((recipe, idx) => (
+            <Card key={recipe.title} className="flex flex-col justify-between overflow-hidden">
+              <CardHeader className="py-3 px-4 bg-muted/40 border-b flex-row items-center justify-between">
+                <CardTitle className="text-xs font-semibold font-mono">{recipe.title}</CardTitle>
+                <Button
+                  size="xs"
+                  variant="outline"
+                  className="gap-1.5"
+                  onClick={() => copyCode(recipe.code, idx)}
+                >
+                  {copiedIndex === idx ? (
+                    <>
+                      <Check className="size-3 text-success" /> คัดลอกแล้ว
+                    </>
+                  ) : (
+                    <>
+                      <Copy className="size-3" /> คัดลอกโค้ด
+                    </>
+                  )}
+                </Button>
+              </CardHeader>
+              <CardContent className="p-0">
+                <pre className="max-h-[380px] overflow-x-auto p-3 text-xs font-mono leading-relaxed bg-muted/20">
+                  <code>{recipe.code}</code>
+                </pre>
+              </CardContent>
+            </Card>
+          ))}
+        </div>
+      </section>
+    </div>
+  );
+}