@suphark/ui 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.7.0] — 2026-09-20
+
+component ระดับแอปที่ Pi Auth และ Pi Done เขียนซ้ำกัน — สเปกจาก Pi Auth ออกแบบให้ทั้งสองแอปใช้ร่วม (ไม่พึ่ง i18n/auth ของแอป ทุกข้อความรับเป็น prop หรือ `UiText`)
+
+### Added
+
+- **`CommandPalette`** (`@suphark/ui/next`) — ค้นหาแบบ ⌘K/Ctrl+K ทั้งแอป: `pages` (หน้าในเมนูที่แอปกรองสิทธิ์แล้ว — กรองฝั่ง client ตาม label/group/href/keywords) + `search?(query) => Promise<CommandPaletteSection[]>` (server action ของแอป เรียกเมื่อ ≥ `minQuery` ตัว, debounce `debounceMs` 150, เก็บ query คู่ผล ผลล่าสุดเท่านั้นที่แสดง), `compact` (ปุ่มไอคอนใน header) หรือปุ่มเต็มกว้าง + `Kbd` (⌘K/CtrlK ตาม platform หลัง mount) สำหรับ `sidebarHeader`, `shortcut` (ค่าเริ่มต้น k), `text` (fallback `UiText.palette`), `onNavigate` (ค่าเริ่มต้น router.push + ปิด); `Command shouldFilter={false}`, `CommandEmpty` แสดง "กำลังค้นหา…" ขณะ pending; types `CommandPaletteItem`, `CommandPaletteSection`, `CommandPaletteText`
+- **`OrganizationSwitcher`** (`@suphark/ui/next`) — ตัวสลับองค์กร/tenant แบบ Clerk บน `HeaderCrumb` + `DropdownMenu`: `organizations[{ id, name, slug?, logoUrl? }]`, `activeId`, `onSwitch(id)` (server action — component ทำ useTransition + `router.refresh()` ปิดได้ด้วย `refresh={false}`), `placement="header"` (HeaderCrumb ใน layout top) / `"sidebar"` (ปุ่มเต็มกว้าง + SwitcherChevron ใน `sidebarHeader`), `fallbackLabel`/`heading` (ค่าเริ่มต้น `UiText.switcher`), `hint(org)` (ค่าเริ่มต้น `/slug`), `footer` (slot ท้ายเมนู เช่น สร้างองค์กร); องค์กรเดียว = ไม่มีเมนู, active มี ✓ และกดไม่ทำอะไร, pending ปิดปุ่ม, โลโก้ `<img size-5>` หรือ Building2; types `OrganizationOption`, `OrganizationSwitcherProps`
+- `UiText.palette` / `UiText.switcher` (optional, มีค่าเริ่มต้นไทย/อังกฤษ)
+- **`IconPicker`** (barrel, generic `T extends string`) — เลือกไอคอนจากชุดที่แอปส่ง `icons[{ name, icon: LucideIcon, labelTh, labelEn, keywords? }]` (แพ็กเกจไม่ bundle ชุดไอคอน): ค้นหา name/labelTh/labelEn/keywords ผ่าน `useDeferredValue`, preview ไอคอน+ชื่อด้านบน, กริด `SelectionButton` (aria-pressed, title/aria-label ตาม `language` th/en), `accentColor` (inline style สี dynamic ของผู้ใช้), `heightClassName`/`columnsClassName`, `text` ทับข้อความ — สเปกจาก DueBell ให้ Pi Done (metadata icon) ใช้ร่วม
+- **`SelectionButton`** (barrel) — ปุ่ม toggle `aria-pressed` + สีเน้นเมื่อเลือก (Button outline) — chip ประเภท/ตัวกรอง, ช่องใน IconPicker (ยกจาก DueBell)
+- **`CalendarMonthGrid<T>`** (barrel) — ตารางเดือนเลือกวันที่แอปคุมเนื้อหาต่อวัน: `month "YYYY-MM"`, `selectedDay`, `onSelectDay(day, date)`, `itemsByDay`, `renderDay(ctx)` (คืน null = ✓ ของแพ็กเกจเมื่อ complete), `dayState(items, ctx) → { complete?, hasItems? }` → data-attribute `data-selected/today/has-items/complete/weekend` ให้ CSS ของแอปแต่ง, (data-attribute เป็น boolean มี/ไม่มี — CSS ใช้ `[data-selected]`), `weekStartsOn 0|1`, `weekdayLabels` (export `WEEKDAYS_TH`/`WEEKDAYS_EN`), `today` (ไม่ส่ง = browser หลัง mount ผ่าน `useMounted` — SSR ได้ไม่ mismatch), `dayLabel` (aria-label "วันที่ N มี M รายการ"), `legend`, `dayClassName`; ช่องว่างก่อนวันที่ 1 aspect-square; ปุ่มวัน `aria-pressed` — สเปกจาก DueBell + Pi Done
+- **`ProgressBar`** (barrel) — แถบความคืบหน้าตั้ง `tone` (default/success/warning/destructive), `size` sm/md/lg, `label`, `showValue`/`format`, `trackClassName`/`indicatorClassName`/`indicatorStyle` (สี dynamic) จาก props — `Progress` ของ shadcn ต่อท้าย Track+Indicator ให้เสมอ ส่ง children เข้าไปจะได้ 2 แถบ (รายงานจาก DueBell) จึงประกอบจาก `ProgressPrimitive.Root` โดยตรง
+- showcase: หน้า `icon-picker`, `selection-button`, `calendar-month-grid`, `progress-bar`; tests 6 กรณีเพิ่ม (รวม 100)
+- **error รายช่องในฟอร์ม server action** (ขอจาก Pi Mail): `FormState` แบบ `ok: false` รับ `errors?: Record<string, string>`; `ActionForm` และ `FormDialog` รับ `children` เป็นฟังก์ชัน `({ state, pending, errors, fieldError }) => ReactNode` (type `FormRenderContext`) → `<LabeledField error={fieldError("email")}>` ไม่ต้องมี hook ของแอป; `FormMessage` ยังแสดง `error` รวมเหมือนเดิม
+- `UserMenu`: prop `menuLabel` + `UiText.userMenu`/`signOut` (ขอจาก Pi PDF — แอปอังกฤษได้ label ไทย); `ThemeMenuItems`: prop `onThemeChange(theme)` สำหรับบันทึกธีมเป็น preference ของบัญชี + ข้อความจาก `UiText.theme`
+- `LabeledField`: prop `htmlFor` — ส่งมาแล้ว label ไม่ครอบ control (ผูกด้วย id) ให้ tooling ที่ไม่คำนวณ nested label เห็น accessible name (ข้อสังเกตจาก Pi Files)
+- `DataTable`: `showToolbar` / `showPagination` (ค่าเริ่มต้น true) ปิดแถบค้นหา/ตัวกรอง/View และ pagination สำหรับตารางตั้งค่าเล็ก ๆ (ขอจาก Pi Files)
+
+### Fixed
+
+- **`AppShell` (layout sidebar) มี `<main>` ซ้อน 2 ชั้น** (รายงานจาก DueBell): `SidebarInset` ของ shadcn เป็น `<main>` อยู่แล้ว → ใส่ `id={APP_MAIN_ID}`/`tabIndex` ที่ SidebarInset และเลิกสร้าง `<main>` ชั้นใน (เป็น `<div>`); layout top ยังมี `<main>` ตัวเดียวเหมือนเดิม
+- showcase: หน้า `command-palette`, `organization-switcher`; `/shell` (sidebarHeader + ยุบเป็นไอคอน) และ `/shell-top` (crumb องค์กร) ใช้สองตัวนี้จริงแทน mock เดิม; tests 5 กรณี (คีย์ลัด toggle + กรอง keywords, search debounce/ผลล่าสุด/push+ปิด, org เดียวไม่มีเมนู, active ไม่เรียก onSwitch + refresh, fallback label)
+
+## [0.6.1] — 2026-09-20
+
+### Added
+
+- **`npx suphark-ui-audit`** (`bin` ของแพ็กเกจ, `scripts/audit.mjs`) — ตรวจโค้ดแอปปลายทางตามกติกา design system ในคำสั่งเดียว: error = `window-dialog` (window.confirm/alert/prompt), `radix-state` (`data-[state=…]` ที่ Base UI ไม่มี), `arbitrary-text` (`text-[Npx]`), `base-ui-props` (สคริปต์เดิม); warning = `raw-palette` (bg-red-500 …), `important` (utility ลงท้าย `!` — เฉพาะ `--important` สำหรับโค้ดแพ็กเกจ); `--strict` ให้ warning เป็น error; ยกเว้น `// ui-audit-ok: เหตุผล` / `/* ui-audit-ok-file: เหตุผล */`; ข้าม `components/ui/**`, tests, generated; README + `docs/agent-rules.md` มีวิธีใช้ — repo นี้รัน `pnpm audit:ui` ใน `verify` และ CI (0 error 0 warning)
+- `FormFieldRadioCards`: prop `aria-label` ส่งต่อไป RadioGroup เมื่อไม่แสดง `label` (ข้อสังเกตจาก Pi Auth หลังย้ายมาใช้ — ของเดิมมี aria-label)
+
+### Changed
+
+- ล้าง raw palette ในแพ็กเกจเป็น semantic token: labs badge ใน `AppNav` → `text-warning-muted-foreground`, `FloatingSaveButton` สำเร็จ → `bg-success`, `FormMessage` สำเร็จ → `text-success`, ดอกจัน/ข้อความ error ใน `FormField*` → `text-destructive`, ไอคอน `ThemeToggle` → `text-warning`/`text-primary`/`text-muted-foreground`, ตัวอย่างใน design-system; ที่ยังใช้ palette โดยตั้งใจและจดไว้ (`ui-audit-ok-file`): `Notice`/`StatusBadge` (โทน 50/900 คู่ dark — รอตัดสินใจ token ระดับ tone), `lib/status-colors.ts` (ชุดสีให้ผู้ใช้เลือก)
+
 ## [0.6.0] — 2026-09-20
 
 component สำเร็จรูปสำหรับฟอร์ม server action ที่ Pi Auth ประกอบเองอยู่ (DueBell/Mail/Files ใช้ได้เหมือนกัน) — ไม่เปลี่ยน API เดิม; **รวม 0.5.2 ที่ยังไม่ได้ publish**

package/README.md

@@ -182,6 +182,26 @@ webview/automation บางตัวปิด `window.confirm` ทิ้ง (
 
 `createKanbanCollisionDetection({ columnItems, resolveColumnId })` (จาก `@suphark/ui/kanban`) ใช้เป็น `collisionDetection` ของ `DndContext` เมื่อมีหลายคอลัมน์ (SortableContext ต่อคอลัมน์) — ตัวอย่างบอร์ดเต็มที่ ui.suphark.com/components/kanban-board; wrapper ของการ์ด**ห้าม** `overflow-hidden` (dnd-kit ใส่ transform ที่ node ที่ `setNodeRef` ถ้าถูกครอบด้วย overflow-hidden การ์ดที่ขยับหลบจะถูก clip)
 
+### ตรวจกติกาในแอป — `npx suphark-ui-audit`
+
+แพ็กเกจมี `bin` ให้รันในแอปปลายทาง (ตรวจ `src` ค่าเริ่มต้น; ข้าม `components/ui/**`, tests, generated):
+
+```bash
+npx suphark-ui-audit            # หรือใส่ใน package.json: "audit:ui": "suphark-ui-audit src"
+npx suphark-ui-audit --strict   # warning นับเป็น error (ใช้ใน CI เมื่อล้างหมดแล้ว)
+```
+
+| กฎ | ระดับ | เจอ → ใช้แทน |
+| --- | --- | --- |
+| `window-dialog` | error | `window.confirm/alert/prompt(` → `ConfirmDialog` / `useConfirm()` / `useDialogs()` |
+| `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` |
+| `important` | warning (เฉพาะ `--important`) | utility ลงท้าย `!` ในโค้ดแพ็กเกจ |
+
+ยกเว้นรายบรรทัด `// ui-audit-ok: <เหตุผล>` (บรรทัดเดียวกันหรือบรรทัดก่อน) — ยกเว้นทั้งไฟล์ `/* ui-audit-ok-file: <เหตุผล> */`
+
 ### สิทธิ์ (ActionButton/LinkButton `permission` prop)
 
 แพ็กเกจไม่รู้จักระบบสิทธิ์ของแอป — ครอบด้วย `UiPermissionProvider` แล้วส่งฟังก์ชัน `check(requirement, options)` ของแอปเข้ามา ถ้าไม่ครอบ = อนุญาตทุกอย่าง

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.6.0",
+  "version": "0.7.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 เอง",
@@ -22,6 +22,9 @@
   "sideEffects": [
     "*.css"
   ],
+  "bin": {
+    "suphark-ui-audit": "scripts/audit.mjs"
+  },
   "files": [
     "src",
     "!src/**/__tests__",
@@ -116,6 +119,7 @@
   },
   "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",

package/scripts/audit.mjs

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * suphark-ui-audit — ตรวจโค้ดแอปปลายทางตามกติกา design system (docs/agent-rules.md) ในคำสั่งเดียว
+ *
+ *   npx suphark-ui-audit                 # ตรวจ src (ค่าเริ่มต้น)
+ *   npx suphark-ui-audit src apps/web    # หลายโฟลเดอร์
+ *   npx suphark-ui-audit --strict        # warning นับเป็น error ด้วย (ใช้ใน CI เมื่อล้างหมดแล้ว)
+ *   npx suphark-ui-audit --no-palette    # ปิดกฎ raw palette ชั่วคราว
+ *   npx suphark-ui-audit --important     # เปิดกฎ utility ลงท้าย ! (ค่าเริ่มต้นตรวจเฉพาะโค้ดของแพ็กเกจเอง)
+ *
+ * กฎ (error = พังบน Base UI / ผิดกติกาชัดเจน, warning = ควรแก้แต่ไม่บล็อก):
+ *   window-dialog   error    window.confirm/alert/prompt → ConfirmDialog / useConfirm() / useDialogs()
+ *   radix-state     error    data-[state=open|checked|active|…] ไม่มีบน Base UI → data-open / data-checked / data-active / data-popup-open
+ *   arbitrary-text  error    text-[Npx] → ใช้ scale (text-xs … text-3xl)
+ *   important       warning  utility ที่ลงท้าย ! (size-3.5!) — เฉพาะโค้ดแพ็กเกจ (--important): Tailwind ของแอปที่ scan ผ่าน @source อาจไม่ generate
+ *   raw-palette     warning  bg-red-500 / text-slate-600 … → semantic token (bg-destructive, text-muted-foreground, bg-success …)
+ *   base-ui-props   error    default* ที่ค่าเปลี่ยนได้ / onSelect บน Base UI (สคริปต์ audit-base-ui-props)
+ *
+ * ยกเว้นเป็นบรรทัด: ใส่ `// ui-audit-ok: <เหตุผล>` ท้ายบรรทัดหรือบรรทัดก่อนหน้า
+ * ยกเว้นทั้งไฟล์: `/* ui-audit-ok-file: <เหตุผล> *\/` ที่หัวไฟล์
+ * ข้ามอัตโนมัติ: node_modules, .next, dist, build, generated, __tests__, *.test.*, components/ui/** (ไฟล์ shadcn)
+ */
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith("--")));
+const roots = args.filter((a) => !a.startsWith("--"));
+if (roots.length === 0) roots.push("src");
+const STRICT = flags.has("--strict");
+const PALETTE = !flags.has("--no-palette");
+const SKIP_BASE_UI = flags.has("--no-base-ui");
+const IMPORTANT = flags.has("--important");
+
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".next",
+  "dist",
+  "build",
+  "generated",
+  "__tests__",
+  ".git",
+]);
+const LINE_MARKER = "ui-audit-ok:";
+const FILE_MARKER = "ui-audit-ok-file:";
+
+const PALETTE_COLORS =
+  "red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|slate|gray|zinc|neutral|stone";
+const RULES = [
+  {
+    id: "window-dialog",
+    level: "error",
+    regex: /\bwindow\.(confirm|alert|prompt)\s*\(/g,
+    message:
+      "ใช้ ConfirmDialog / useConfirm() / useDialogs() ของ @suphark/ui แทน window dialog (webview บางตัวปิดทิ้ง)",
+  },
+  {
+    id: "radix-state",
+    level: "error",
+    regex:
+      /data-\[state=(?:open|closed|checked|unchecked|active|inactive|on|off|visible|hidden|delayed-open|instant-open)\]/g,
+    message:
+      "Base UI ไม่ใส่ data-state — ใช้ data-open / data-closed / data-checked / data-active / data-popup-open",
+  },
+  {
+    id: "arbitrary-text",
+    level: "error",
+    regex: /\btext-\[\d+(?:px|rem|em)\]/g,
+    message: "ห้าม text-[Npx] — ใช้ typography scale (text-xs … text-3xl) ตาม docs/design-system.md",
+  },
+  {
+    id: "important",
+    level: "warning",
+    regex: /(?<=["'`\s])[a-z][\w:/[\]().%=,-]*!(?=["'`\s])/g,
+    message:
+      "utility ที่ลงท้าย ! — แอปที่ scan แพ็กเกจผ่าน @source อาจไม่ generate class นี้ ปรับ specificity แทน",
+  },
+  {
+    id: "raw-palette",
+    level: "warning",
+    regex: new RegExp(
+      `(?<![\\w-])(?:[a-z-]+:)*(?:bg|text|border|ring|fill|stroke|from|to|via|outline|decoration|divide|shadow|accent|caret|placeholder)-(?:${PALETTE_COLORS})-(?:50|100|200|300|400|500|600|700|800|900|950)(?:/\\d+)?(?![\\w-])`,
+      "g",
+    ),
+    message:
+      "raw palette → semantic token (bg-muted, text-muted-foreground, bg-destructive, bg-success, bg-warning, text-primary …)",
+  },
+];
+
+/** ปิดส่วนที่ไม่ใช่โค้ด (comment, <code>/<pre>, template ตัวอย่างในเอกสาร) ด้วยช่องว่างเพื่อคง offset */
+function mask(content) {
+  return content
+    .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/(^|[^:\\])\/\/.*$/gm, (m, p1) => p1 + " ".repeat(m.length - p1.length))
+    .replace(/<code[\s\S]*?<\/code>/g, (m) => m.replace(/[^\n]/g, " "))
+    .replace(/<pre[\s\S]*?<\/pre>/g, (m) => m.replace(/[^\n]/g, " "));
+}
+
+function walk(dir, out) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      walk(full, out);
+    } else if (/\.(tsx?|jsx?|mdx?)$/.test(e.name) && !/\.test\.[jt]sx?$/.test(e.name)) {
+      // ไฟล์ shadcn ของแอป (สำเนา CLI) ไม่ตรวจ — ควรใช้ของแพ็กเกจแทนอยู่แล้ว
+      if (/[\\/]components[\\/]ui[\\/]/.test(full)) continue;
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+const files = roots.flatMap((r) => walk(path.resolve(process.cwd(), r), []));
+const findings = [];
+let skippedFiles = 0;
+
+for (const file of files) {
+  const raw = fs.readFileSync(file, "utf8");
+  if (raw.includes(FILE_MARKER)) {
+    skippedFiles++;
+    continue;
+  }
+  const lines = raw.split("\n");
+  const masked = mask(raw).split("\n");
+  for (const rule of RULES) {
+    if (rule.id === "raw-palette" && !PALETTE) continue;
+    if (rule.id === "important" && !IMPORTANT) continue;
+    for (let i = 0; i < masked.length; i++) {
+      const line = masked[i] ?? "";
+      rule.regex.lastIndex = 0;
+      let m = rule.regex.exec(line);
+      if (!m) continue;
+      const rawLine = lines[i] ?? "";
+      const prev = lines[i - 1] ?? "";
+      if (
+        rawLine.includes(LINE_MARKER) ||
+        (prev.trim().startsWith("//") && prev.includes(LINE_MARKER))
+      )
+        continue;
+      const hits = [];
+      while (m) {
+        hits.push(m[0]);
+        m = rule.regex.exec(line);
+      }
+      findings.push({
+        file: path.relative(process.cwd(), file),
+        line: i + 1,
+        rule: rule.id,
+        level: STRICT ? "error" : rule.level,
+        hits: [...new Set(hits)],
+        message: rule.message,
+      });
+    }
+  }
+}
+
+// base-ui props audit ของแพ็กเกจ (รันเป็นโปรเซสลูกเพื่อคง UI_DIR ชี้ที่ shadcn ของแพ็กเกจ)
+let baseUiExit = 0;
+let baseUiOutput = "";
+if (!SKIP_BASE_UI) {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const uiDir = path.resolve(here, "..", "src", "components", "ui");
+  const r = spawnSync(process.execPath, [path.join(here, "audit-base-ui-props.mjs"), ...roots], {
+    encoding: "utf8",
+    env: { ...process.env, UI_DIR: uiDir },
+  });
+  baseUiExit = r.status ?? 1;
+  baseUiOutput = `${r.stdout ?? ""}${r.stderr ?? ""}`.trim();
+}
+
+// ---------- รายงาน ----------
+const byRule = new Map();
+for (const f of findings) byRule.set(f.rule, (byRule.get(f.rule) ?? 0) + 1);
+const errors = findings.filter((f) => f.level === "error");
+const warnings = findings.filter((f) => f.level === "warning");
+
+findings.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file.localeCompare(b.file)));
+let lastFile = "";
+for (const f of findings) {
+  if (f.file !== lastFile) {
+    console.log(`\n${f.file}`);
+    lastFile = f.file;
+  }
+  const tag = f.level === "error" ? "✗" : "△";
+  console.log(`  ${tag} :${f.line}  ${f.rule}  ${f.hits.join(", ")}`);
+}
+if (baseUiOutput && baseUiExit !== 0) console.log(`\n${baseUiOutput}`);
+
+console.log(
+  `\nsuphark-ui-audit — ตรวจ ${files.length} ไฟล์ใน ${roots.join(", ")}${skippedFiles ? ` (ข้าม ${skippedFiles} ไฟล์ที่ทำเครื่องหมาย ${FILE_MARKER})` : ""}`,
+);
+for (const rule of RULES) {
+  const n = byRule.get(rule.id) ?? 0;
+  if (rule.id === "raw-palette" && !PALETTE) continue;
+  if (rule.id === "important" && !IMPORTANT) continue;
+  console.log(
+    `  ${n === 0 ? "✓" : rule.level === "error" || STRICT ? "✗" : "△"} ${rule.id.padEnd(15)} ${n}${n ? `  — ${rule.message}` : ""}`,
+  );
+}
+console.log(
+  `  ${baseUiExit === 0 ? "✓" : "✗"} base-ui-props    ${baseUiExit === 0 ? "ผ่าน" : "พบปัญหา (ดูข้างบน)"}`,
+);
+console.log(`\n${errors.length} error, ${warnings.length} warning${STRICT ? " (--strict)" : ""}`);
+if (errors.length || warnings.length) {
+  console.log(
+    `ยกเว้นรายบรรทัด: // ${LINE_MARKER} <เหตุผล>   ยกเว้นทั้งไฟล์: /* ${FILE_MARKER} <เหตุผล> */`,
+  );
+}
+process.exit(errors.length > 0 || baseUiExit !== 0 ? 1 : 0);

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

@@ -65,6 +65,7 @@ export function AppBrand({
       <SidebarMenuItem className={cn("flex items-center", className)}>
         <SidebarMenuButton
           size="lg"
+          // ui-audit-ok: class เดียวกับ size=lg ของ sidebar.tsx (shadcn) จึงถูก generate แน่นอน
           className="min-w-0 flex-1 group-data-[collapsible=icon]:p-0!"
           render={<Link href={href} onClick={closeMobile} />}
         >

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

@@ -49,12 +49,10 @@ function MenuTitle({ title, isLabs }: { title: string; isLabs?: boolean }) {
       <TooltipTrigger
         render={<span className="flex w-full items-center gap-1.5 overflow-hidden" />}
       >
-        <span
-          className={cn("truncate", isLabs && "font-medium text-amber-600 dark:text-amber-500")}
-        >
+        <span className={cn("truncate", isLabs && "font-medium text-warning-muted-foreground")}>
           {title}
         </span>
-        {isLabs && <FlaskConical className="h-3 w-3 shrink-0 text-amber-600 dark:text-amber-500" />}
+        {isLabs && <FlaskConical className="h-3 w-3 shrink-0 text-warning-muted-foreground" />}
       </TooltipTrigger>
       <TooltipContent side="right" align="center" className="max-w-xs break-words">
         {title}

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

@@ -114,7 +114,7 @@ export function AppShell(props: AppShellProps) {
   return <SidebarShell {...props} />;
 }
 
-/** id ของ <main> ที่ AppShell สร้าง — ใช้อ้างจาก skip link / anchor */
+/** id ของ <main> ของ AppShell (sidebar: SidebarInset, top: main ในเนื้อหา) — ใช้อ้างจาก skip link / anchor */
 export const APP_MAIN_ID = "app-main";
 
 /** ลิงก์ "ข้ามไปเนื้อหา" สำหรับคีย์บอร์ด/screen reader — มองไม่เห็นจนกด Tab ตัวแรก */
@@ -180,7 +180,8 @@ function SidebarShell({
         collapsible={collapsible}
       />
 
-      <SidebarInset>
+      {/* SidebarInset ของ shadcn เป็น <main> อยู่แล้ว → ใส่ id/tabIndex ให้ skip link ที่นี่ ไม่สร้าง <main> ซ้อน */}
+      <SidebarInset id={APP_MAIN_ID} tabIndex={-1} className="outline-none">
         {showHeader && (
           <div className="sticky top-0 z-40 shrink-0 bg-background print:static">
             {headerOpts.banner}
@@ -216,17 +217,15 @@ function SidebarShell({
             </header>
           </div>
         )}
-        <main
-          id={APP_MAIN_ID}
-          tabIndex={-1}
+        <div
           className={cn(
-            "flex flex-1 flex-col gap-4 p-4 outline-none md:gap-6 md:p-6 print:overflow-visible",
+            "flex flex-1 flex-col gap-4 p-4 md:gap-6 md:p-6 print:overflow-visible",
             contentMaxWidth && cn("mx-auto w-full", contentMaxWidth),
             contentClassName,
           )}
         >
           {children}
-        </main>
+        </div>
       </SidebarInset>
     </SidebarProvider>
   );

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

@@ -0,0 +1,256 @@
+"use client";
+
+import { useUiText } from "@suphark/ui/components/shared/ui-text";
+import { Button } from "@suphark/ui/components/ui/button";
+import {
+  Command,
+  CommandDialog,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+  CommandShortcut,
+} from "@suphark/ui/components/ui/command";
+import { Kbd } from "@suphark/ui/components/ui/kbd";
+import { useMounted } from "@suphark/ui/hooks/use-mounted";
+import { cn } from "@suphark/ui/lib/utils";
+import { Search } from "lucide-react";
+import { useRouter } from "next/navigation";
+import { type ReactNode, useEffect, useMemo, useState, useTransition } from "react";
+
+export interface CommandPaletteItem {
+  href: string;
+  label: string;
+  /** ชื่อกลุ่ม (แสดงเป็น shortcut ท้ายรายการ และใช้ค้นหา) */
+  group?: string;
+  icon?: ReactNode;
+  /** คำค้นเพิ่มเติมนอกจาก label/group/href */
+  keywords?: string[];
+}
+
+export interface CommandPaletteSection {
+  key: string;
+  heading: string;
+  items: Array<{ id: string; href: string; label: string; description?: string; icon?: ReactNode }>;
+}
+
+export interface CommandPaletteText {
+  placeholder: string;
+  title: string;
+  description: string;
+  empty: string;
+  searching: string;
+  /** หัวกลุ่ม "หน้า" */
+  pages: string;
+}
+
+const DEFAULT_TEXT: CommandPaletteText = {
+  placeholder: "ค้นหาหรือสั่งงาน…",
+  title: "ค้นหา",
+  description: "พิมพ์เพื่อค้นหาหน้าและข้อมูล",
+  empty: "ไม่พบผลลัพธ์",
+  searching: "กำลังค้นหา…",
+  pages: "หน้า",
+};
+
+/** ⌘ บน Mac, Ctrl ที่อื่น — อ่านฝั่ง client หลัง mount เท่านั้น (กัน hydration mismatch) */
+function useModKeyLabel(mounted: boolean): string {
+  return useMemo(() => {
+    if (!mounted) return "Ctrl";
+    const p = `${navigator.platform ?? ""} ${navigator.userAgent ?? ""}`;
+    return /mac|iphone|ipad/i.test(p) ? "⌘" : "Ctrl";
+  }, [mounted]);
+}
+
+/**
+ * ค้นหาแบบ ⌘K / Ctrl+K ทั้งแอป: หน้าในเมนู (แอปกรองสิทธิ์มาแล้ว) กรองฝั่ง client + ส่วนจาก server action
+ * (`search`) เมื่อพิมพ์ ≥ `minQuery` ตัว (debounce; ผลของ query ล่าสุดเท่านั้นที่แสดง)
+ * ปุ่มเรียก: `compact` = ไอคอนใน header, ค่าเริ่มต้น = ปุ่มเต็มกว้าง + Kbd ใน `sidebarHeader` ของ AppShell
+ * ข้อความรับเป็น prop `text` (ค่าเริ่มต้นจาก `UiText.palette` หรือไทย) — ไม่พึ่ง i18n ของแอป
+ * ยกจาก Pi Auth (features/console/command-palette) ให้ Pi Done/DueBell ใช้ร่วม
+ */
+export function CommandPalette({
+  pages,
+  search,
+  compact = false,
+  shortcut = "k",
+  minQuery = 2,
+  debounceMs = 150,
+  text: textProp,
+  onNavigate,
+  className,
+}: {
+  pages: CommandPaletteItem[];
+  /** server action ของแอป — คืน section ตามลำดับที่ต้องการแสดง */
+  search?: (query: string) => Promise<CommandPaletteSection[]>;
+  compact?: boolean;
+  /** ตัวอักษรคีย์ลัดร่วมกับ ⌘/Ctrl (ค่าเริ่มต้น "k") */
+  shortcut?: string;
+  minQuery?: number;
+  debounceMs?: number;
+  text?: Partial<CommandPaletteText>;
+  /** ค่าเริ่มต้น router.push + ปิดกล่อง — ครอบเพื่อ prefetch/analytics แล้วเรียกต่อเองได้ */
+  onNavigate?: (href: string) => void;
+  className?: string;
+}) {
+  const ui = useUiText();
+  const text: CommandPaletteText = { ...DEFAULT_TEXT, ...ui.palette, ...textProp };
+  const router = useRouter();
+  const mounted = useMounted();
+  const mod = useModKeyLabel(mounted);
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState("");
+  const [result, setResult] = useState<{ query: string; sections: CommandPaletteSection[] } | null>(
+    null,
+  );
+  const [pending, start] = useTransition();
+
+  // คีย์ลัดจากที่ไหนก็ได้ในแอป
+  useEffect(() => {
+    const key = shortcut.toLowerCase();
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === key) {
+        e.preventDefault();
+        setOpen((o) => !o);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [shortcut]);
+
+  const q = query.trim();
+  const shouldSearch = Boolean(search) && q.length >= minQuery;
+
+  // ค้นหาฝั่ง server หลังหยุดพิมพ์ — เก็บ query คู่กับผล ผลที่ไม่ตรง query ปัจจุบันไม่แสดง
+  useEffect(() => {
+    if (!search || !shouldSearch) return;
+    const handle = setTimeout(() => {
+      start(async () => {
+        try {
+          const sections = await search(q);
+          setResult({ query: q, sections });
+        } catch {
+          setResult({ query: q, sections: [] });
+        }
+      });
+    }, debounceMs);
+    return () => clearTimeout(handle);
+  }, [q, search, shouldSearch, debounceMs]);
+
+  const sections = shouldSearch && result?.query === q ? result.sections : [];
+  const ql = q.toLowerCase();
+  const visiblePages = ql
+    ? pages.filter((p) =>
+        `${p.label} ${p.group ?? ""} ${p.href} ${(p.keywords ?? []).join(" ")}`
+          .toLowerCase()
+          .includes(ql),
+      )
+    : pages;
+  const nothing = visiblePages.length === 0 && sections.every((s) => s.items.length === 0);
+
+  function close() {
+    setOpen(false);
+    setQuery("");
+  }
+  function go(href: string) {
+    close();
+    if (onNavigate) onNavigate(href);
+    else router.push(href);
+  }
+
+  const shortcutLabel = `${mod}${shortcut.toUpperCase()}`;
+
+  return (
+    <>
+      {compact ? (
+        <Button
+          type="button"
+          variant="ghost"
+          size="icon"
+          aria-label={text.placeholder}
+          title={`${text.placeholder} (${shortcutLabel})`}
+          className={cn("text-muted-foreground", className)}
+          onClick={() => setOpen(true)}
+        >
+          <Search />
+        </Button>
+      ) : (
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          className={cn(
+            "h-8 w-full justify-start gap-2 bg-background px-2 font-normal text-muted-foreground",
+            className,
+          )}
+          onClick={() => setOpen(true)}
+        >
+          <Search />
+          <span className="flex-1 truncate text-left">{text.placeholder}</span>
+          <Kbd className="hidden sm:inline-flex">{shortcutLabel}</Kbd>
+        </Button>
+      )}
+      <CommandDialog
+        open={open}
+        onOpenChange={(o) => (o ? setOpen(true) : close())}
+        title={text.title}
+        description={text.description}
+      >
+        <Command shouldFilter={false}>
+          <CommandInput
+            autoFocus
+            placeholder={text.placeholder}
+            value={query}
+            onValueChange={setQuery}
+          />
+          <CommandList>
+            {nothing && (
+              <CommandEmpty>{pending && shouldSearch ? text.searching : text.empty}</CommandEmpty>
+            )}
+            {visiblePages.length > 0 && (
+              <CommandGroup heading={text.pages}>
+                {visiblePages.map((p) => (
+                  <CommandItem key={p.href} value={p.href} onSelect={() => go(p.href)}>
+                    <span className="flex size-4 shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4">
+                      {p.icon}
+                    </span>
+                    <span className="flex-1 truncate">{p.label}</span>
+                    {p.group && <CommandShortcut>{p.group}</CommandShortcut>}
+                  </CommandItem>
+                ))}
+              </CommandGroup>
+            )}
+            {sections.map(
+              (s) =>
+                s.items.length > 0 && (
+                  <CommandGroup key={s.key} heading={s.heading}>
+                    {s.items.map((it) => (
+                      <CommandItem
+                        key={it.id}
+                        value={`${s.key}:${it.id}`}
+                        onSelect={() => go(it.href)}
+                      >
+                        <span className="flex size-4 shrink-0 items-center justify-center text-muted-foreground [&_svg]:size-4">
+                          {it.icon}
+                        </span>
+                        <span className="flex-1 truncate">
+                          {it.label}
+                          {it.description && (
+                            <span className="text-muted-foreground"> · {it.description}</span>
+                          )}
+                        </span>
+                      </CommandItem>
+                    ))}
+                  </CommandGroup>
+                ),
+            )}
+            {pending && shouldSearch && !nothing && (
+              <div className="px-3 py-2 text-muted-foreground text-xs">{text.searching}</div>
+            )}
+          </CommandList>
+        </Command>
+      </CommandDialog>
+    </>
+  );
+}