@suphark/ui 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.29.0] — 2026-10-05
+
+### Added
+
+- `InlineEdit`: คุมโหมดแก้ไขจากข้างนอกได้ — `editing` + `onEditingChange` (controlled), `defaultEditing` และ `onCancel` (กด Esc/✕) สำหรับแอปที่เข้าโหมดแก้ไขด้วย F2 หรือเมนูคลิกขวา "เปลี่ยนชื่อ" (คำขอจาก Pi Files — เดิมต้อง `.click()` ปุ่มดินสอผ่าน DOM)
+- **`@suphark/ui/sortable` — ลากจัดลำดับ 2 ระดับ (กลุ่ม + รายการในกลุ่ม)** entry ใหม่บน dnd-kit (แยกจาก barrel เหมือน `data-table`/`kanban` เพราะ dnd-kit สร้าง context ตอน import) — ยกสมองส่วนลากออกจากแอป ส่วนการเรนเดอร์แถวยังเป็นของแอป (ตาราง/การ์ด/รายการ) ตามสเปกของ Pi Config (`values-table.tsx`)
+  - `SortableProvider` — sensors (เมาส์ + คีย์บอร์ด), collision ที่กันลากข้ามชนิด (กลุ่มชนได้แค่กลุ่ม, รายการชนได้แค่รายการกับที่วางของกลุ่ม), ย้ายข้ามกลุ่มระหว่างลาก, commit ตอนปล่อย และ **คืนลำดับเดิมอัตโนมัติเมื่อบันทึกล้มเหลว** (throw หรือ `{ ok: false, error }`) — ไม่มี `onCommitError` = ขึ้น toast ให้; ส่งมา = ส่ง error ดิบให้แอปจัดการเอง ไม่กลืนเงียบ
+  - `SortableGroup` (ขอบเขตการเรียงของกลุ่ม), `useSortableRow({ type, id })` → `{ ref, style, handleProps, isDragging }`, `useSortableDropZone(groupId)` (แปะที่ไหนก็ได้ — หัวกลุ่ม หรือแถว placeholder ของกลุ่มที่ไม่มีหัว; กลุ่มที่ย่ออยู่ก็ยังรับการวางได้), `useSortableState()` → `{ dragging, disabled }`, `DragHandle` (ใช้ `Button` ของแพ็กเกจ จึงได้ tooltip จาก `aria-label`; ปิดการลากแล้วที่จับจางลงเอง หรือซ่อนไปเลยด้วย `hideWhenDisabled`)
+  - `announcements` + `screenReaderInstructions` ส่งเป็น prop ได้ (callback ได้ `{ id, kind, groupId, index, total }` ให้แอปประกอบข้อความจากชื่อจริง) ไม่ส่ง = แม่แบบจาก `UiText.sortable`
+  - helper แบบ pure ใน `lib/sortable-order`: `sortableOrderOf`, `reorderGroups`, `reorderItems`, `moveItemToGroup`, `groupOfItem`, `sameOrder`, `moveWithin`, `sortableOrderToPayload` (คืน `{ groups: string[], items: [{ groupId: string | null, itemIds }] }` — ลำดับกลุ่มกับรายการในกลุ่มครบในก้อนเดียว, `UNGROUPED` → `null`)
+- `UiText.sortable` — `handle`, `instructions`, `started`, `moved`, `dropped`, `cancelled` (`{index}` / `{total}`)
+- showcase: หน้า `/components/sortable-list` — ตาราง 2 ระดับ ลากเรียงกลุ่ม/คีย์/ย้ายข้ามกลุ่ม พร้อมแถว "ลากมาที่นี่เพื่อเอาออกจากกลุ่ม" ที่โผล่เฉพาะตอนลากคีย์
+
+## [0.28.1] — 2026-10-05
+
+### Fixed
+
+- **`AppShell` ปุ่มย่อ/ขยายเมนูยังมี "Toggle Sidebar" อังกฤษค้างอยู่ใน `sr-only`** (รายงานจาก DueBell): `SidebarTrigger` ของ shadcn ฝังข้อความนั้นเป็น children ซึ่งแทนด้วย props ไม่ได้ (JSX children ชนะ) — 0.27.1 เปลี่ยนได้แค่ `aria-label` ตอนนี้ `AppShell` เรนเดอร์ปุ่มเองจาก `Button` ของแพ็กเกจ + `useSidebar()` จึงใช้ `UiText.toggleSidebar` ทั้งชื่อและ tooltip และไม่มีข้อความอังกฤษเหลือในปุ่ม (ยังคง `data-sidebar="trigger"` ไว้ให้ selector เดิมใช้ได้)
+
 ## [0.28.0] — 2026-10-05
 
 ### Added

package/README.md

@@ -197,6 +197,32 @@ webview/automation บางตัวปิด `window.confirm` ทิ้ง (
 
 ต้องการ `alert` / `prompt` / `choose` (หลายปุ่ม) / `checklist` ด้วย หรือไม่อยาก render `confirmDialog` ทุกที่: ครอบ `<DialogsProvider>` ที่ root แล้ว `const dialogs = useDialogs()` — `await dialogs.prompt({ description: "ชื่อใหม่", defaultValue })` คืน string หรือ null; หัว/ปุ่มค่าเริ่มต้นจาก `UiText.ok/alertTitle/promptTitle/chooseTitle/checklistTitle`
 
+### ลากจัดลำดับ (`@suphark/ui/sortable`)
+
+ลากเรียงกลุ่ม เรียงรายการในกลุ่ม และย้ายรายการข้ามกลุ่ม ในตาราง/รายการเดียวกัน — แพ็กเกจดูแล sensors, collision, การย้ายระหว่างลาก และ **คืนลำดับเดิมให้เองเมื่อบันทึกไม่สำเร็จ** ส่วนการเรนเดอร์แถวยังเป็นของแอป
+
+```tsx
+const [order, setOrder] = useState(() =>
+  sortableOrderOf(groups, items, { groupId: (g) => g.id, itemId: (i) => i.id, itemGroupId: (i) => i.groupId }),
+);
+
+<SortableProvider order={order} onOrderChange={setOrder} onCommit={(next) => saveOrder(sortableOrderToPayload(next))}>
+  <SortableGroup itemIds={order.items[groupId] ?? []}>
+    {/* แต่ละแถว: const row = useSortableRow({ type: "item", id }); */}
+    <TableRow ref={row.ref} style={row.style}>
+      <TableCell><DragHandle label={`ลาก ${item.name}`} {...row.handleProps} /></TableCell>
+      …
+    </TableRow>
+  </SortableGroup>
+</SortableProvider>
+```
+
+- กลุ่มที่ไม่มีหัวกลุ่ม (เช่น "ยังไม่จัดกลุ่ม") ใช้ `useSortableDropZone(groupId)` แปะกับแถว placeholder ของตัวเอง และดูว่าควรแสดงเมื่อไหร่จาก `useSortableState().dragging`
+- `onCommit` ล้มเหลว (throw หรือ `{ ok: false, error }`) = คืนลำดับเดิม + toast; ถ้าอยากจัดการ error เองใส่ `onCommitError`
+- `sortableOrderToPayload(order)` คืน `{ groups, items }` — `groups` คือลำดับของกลุ่ม, `items` คือรายการในแต่ละกลุ่มเรียงตามนั้น (ของที่ยังไม่มีกลุ่มมาก่อนด้วย `groupId: null`)
+- `SortableProvider disabled` (เช่นระหว่างกรอง ซึ่งลำดับที่เห็นไม่ใช่ลำดับจริง) ทำให้ `DragHandle` จางลงและกดไม่ได้ — ไม่อยากให้เห็นเลยใส่ `hideWhenDisabled`
+- ข้อความ screen reader: ใส่ `announcements`/`screenReaderInstructions` เป็น prop (callback ได้ `{ id, kind, groupId, index, total }`) หรือปล่อยให้ใช้แม่แบบจาก `UiText.sortable`
+
 ### PWA (`@suphark/ui/pwa`)
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.28.0",
+  "version": "0.29.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 เอง",
@@ -44,6 +44,7 @@
     "./data-table": "./src/data-table.ts",
     "./pwa": "./src/pwa.ts",
     "./kanban": "./src/kanban.ts",
+    "./sortable": "./src/sortable.ts",
     "./styles.css": "./src/styles.css",
     "./components/shared/button": "./src/components/shared/button/index.ts",
     "./components/shared/theme": "./src/components/shared/theme/index.ts",

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { SimpleTooltip } from "@suphark/ui/components/shared/simple-tooltip";
+import { Button } from "@suphark/ui/components/shared/button/button";
 import { SkipLink } from "@suphark/ui/components/shared/skip-link";
 import { useUiText } from "@suphark/ui/components/shared/ui-text";
 import {
@@ -18,11 +18,10 @@ import {
   SidebarInset,
   SidebarProvider,
   SidebarRail,
-  SidebarTrigger,
   useSidebar,
 } from "@suphark/ui/components/ui/sidebar";
 import { cn } from "@suphark/ui/lib/utils";
-import { Search, X } from "lucide-react";
+import { PanelLeftIcon, Search, X } from "lucide-react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
 import {
@@ -78,7 +77,7 @@ export interface AppShellProps {
   /** ท้าย sidebar — ปกติคือ `<UserMenu variant="sidebar" />` */
   sidebarFooter?: ReactNode;
   /**
-   * header ของเนื้อหา: `false` = ไม่มี header, `true`/ไม่ส่ง = SidebarTrigger + breadcrumb อัตโนมัติ
+   * header ของเนื้อหา: `false` = ไม่มี header, `true`/ไม่ส่ง = ปุ่มย่อ/ขยายเมนู + breadcrumb อัตโนมัติ
    * ส่ง object เพื่อกำหนดเอง
    */
   header?:
@@ -207,9 +206,7 @@ function SidebarShell({
               )}
             >
               <div className="flex h-12 min-w-0 flex-1 items-center gap-2 md:h-full">
-                <SimpleTooltip content={toggleSidebarLabel}>
-                  <SidebarTrigger className="-ml-1" aria-label={toggleSidebarLabel} />
-                </SimpleTooltip>
+                <SidebarToggle label={toggleSidebarLabel} />
                 {breadcrumbs && (
                   <>
                     <Separator orientation="vertical" className="mr-2 hidden h-4 md:block" />
@@ -357,6 +354,28 @@ function TopShell({
   );
 }
 
+/**
+ * ปุ่มย่อ/ขยายเมนูในหัวเรื่อง — เขียนเองแทน `SidebarTrigger` ของ shadcn เพราะตัวนั้นฝัง
+ * `<span className="sr-only">Toggle Sidebar</span>` เป็นภาษาอังกฤษไว้ใน children (แทนไม่ได้
+ * เพราะ JSX children ชนะ props) ตัวนี้ใช้ `UiText` และได้ tooltip จาก `Button` ของแพ็กเกจ
+ * คง `data-sidebar="trigger"` ไว้ให้แอปที่ยิง selector เดิมยังใช้ได้
+ */
+function SidebarToggle({ label }: { label: string }) {
+  const { toggleSidebar } = useSidebar();
+  return (
+    <Button
+      data-sidebar="trigger"
+      variant="ghost"
+      size="icon-sm"
+      aria-label={label}
+      className="-ml-1"
+      onClick={toggleSidebar}
+    >
+      <PanelLeftIcon />
+    </Button>
+  );
+}
+
 /** แผง sidebar — แยกเพื่อใช้ useSidebar (ล้างคำค้นเมื่อยุบ ไม่ให้เมนูถูกกรองทั้งที่มองไม่เห็นช่องค้นหา) */
 function ShellSidebar({
   brand,

package/src/components/shared/inline-edit.tsx

@@ -20,6 +20,16 @@ export interface InlineEditProps {
   emptyLabel?: ReactNode;
   /** ตรวจก่อนบันทึก — คืนข้อความ = ไม่ผ่าน */
   validate?: (value: string) => string | null | undefined;
+  /**
+   * คุมโหมดแก้ไขจากข้างนอก (เช่นเข้าโหมดแก้ไขด้วย F2 หรือเมนูคลิกขวา "เปลี่ยนชื่อ")
+   * ส่ง `editing` คู่กับ `onEditingChange` = controlled; ไม่ส่ง = component คุมเอง
+   */
+  editing?: boolean;
+  onEditingChange?: (editing: boolean) => void;
+  /** เริ่มต้นอยู่ในโหมดแก้ไขเลย (uncontrolled — เช่นแถวที่เพิ่งสร้าง) */
+  defaultEditing?: boolean;
+  /** กด Esc / ปุ่ม ✕ (ไม่ถูกเรียกเมื่อบันทึกสำเร็จ) */
+  onCancel?: () => void;
   /** ค่าเดิมกับค่าใหม่เท่ากัน = ปิดโหมดแก้ไขโดยไม่เรียก `onSave` (ค่าเริ่มต้น true) */
   skipWhenUnchanged?: boolean;
   disabled?: boolean;
@@ -42,25 +52,49 @@ export function InlineEdit({
   placeholder,
   emptyLabel = "—",
   validate,
+  editing: editingProp,
+  onEditingChange,
+  defaultEditing = false,
+  onCancel,
   skipWhenUnchanged = true,
   disabled = false,
   size = "default",
   className,
 }: InlineEditProps) {
   const text = useUiText();
-  const [editing, setEditing] = useState(false);
+  const [uncontrolledEditing, setUncontrolledEditing] = useState(defaultEditing);
+  const editing = editingProp ?? uncontrolledEditing;
   const [draft, setDraft] = useState(value);
   const [pending, setPending] = useState(false);
   const inputRef = useRef<HTMLInputElement>(null);
   // เลือกข้อความทั้งหมดครั้งแรกที่เข้าโหมดแก้ไข — พิมพ์ทับได้ทันที (โฟกัสรอบหลังไม่เลือกซ้ำ)
   const selectedOnOpen = useRef(false);
 
+  // เข้าโหมดแก้ไขจากข้างนอก (F2/เมนู) ก็ต้องเริ่มจากค่าปัจจุบันเหมือนกดปุ่มดินสอ
+  const wasEditing = useRef(editing);
+  if (editing && !wasEditing.current) {
+    setDraft(value);
+    selectedOnOpen.current = false;
+  }
+  wasEditing.current = editing;
+
+  function setEditing(next: boolean) {
+    if (editingProp === undefined) setUncontrolledEditing(next);
+    onEditingChange?.(next);
+  }
+
   function start() {
     setDraft(value);
     selectedOnOpen.current = false;
     setEditing(true);
   }
 
+  /** ยกเลิก (Esc / ปุ่ม ✕) — ต่างจากบันทึกสำเร็จตรงที่บอกแอปด้วย */
+  function cancel() {
+    setEditing(false);
+    onCancel?.();
+  }
+
   async function commit() {
     const next = draft.trim();
     if (skipWhenUnchanged && next === value.trim()) {
@@ -148,7 +182,7 @@ export function InlineEdit({
             void commit();
           } else if (e.key === "Escape") {
             e.preventDefault();
-            setEditing(false);
+            cancel();
           }
         }}
       />
@@ -166,7 +200,7 @@ export function InlineEdit({
         size={compact ? "icon-xs" : "icon-sm"}
         aria-label={text.cancel}
         disabled={pending}
-        onClick={() => setEditing(false)}
+        onClick={cancel}
       >
         <XIcon />
       </Button>

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

@@ -22,6 +22,16 @@ export interface UiText {
   actionFailed?: string;
   /** InlineEdit: ปุ่มดินสอ (optional — "แก้ไข") */
   edit?: string;
+  /** SortableList (optional) — ที่จับลาก + คำอธิบายสำหรับ screen reader */
+  sortable?: Partial<{
+    handle: string;
+    instructions: string;
+    /** ใช้ `{index}` / `{total}` */
+    started: string;
+    moved: string;
+    dropped: string;
+    cancelled: string;
+  }>;
   /** SelectionBar (optional) — `selected` ใช้ `{count}` */
   selection?: Partial<{ selected: string; clear: string }>;
   /** DataTable (optional) — `rowsSelected` ใช้ `{selected}`/`{total}`, `pageOf` ใช้ `{page}`/`{pages}` */
@@ -154,6 +164,14 @@ export const UI_TEXT_TH: UiText = {
   actionFailed: "ดำเนินการไม่สำเร็จ",
   edit: "แก้ไข",
   selection: { selected: "เลือก {count} รายการ", clear: "ล้างการเลือก" },
+  sortable: {
+    handle: "ลากเพื่อจัดลำดับ",
+    instructions: "กด Space เพื่อเริ่มลาก ใช้ปุ่มลูกศรเลื่อน แล้วกด Space อีกครั้งเพื่อวาง (Esc = ยกเลิก)",
+    started: "เริ่มลากรายการที่ {index} จาก {total}",
+    moved: "ย้ายไปตำแหน่งที่ {index} จาก {total}",
+    dropped: "วางที่ตำแหน่งที่ {index} จาก {total}",
+    cancelled: "ยกเลิกการลาก",
+  },
   table: {
     rowsPerPage: "แถวต่อหน้า",
     pageOf: "หน้า {page} จาก {pages}",
@@ -265,6 +283,15 @@ export const UI_TEXT_EN: UiText = {
   actionFailed: "Action failed",
   edit: "Edit",
   selection: { selected: "{count} selected", clear: "Clear selection" },
+  sortable: {
+    handle: "Drag to reorder",
+    instructions:
+      "Press Space to start dragging, use arrow keys to move, Space again to drop (Esc to cancel)",
+    started: "Picked up item {index} of {total}",
+    moved: "Moved to position {index} of {total}",
+    dropped: "Dropped at position {index} of {total}",
+    cancelled: "Dragging cancelled",
+  },
   table: {
     rowsPerPage: "Rows per page",
     pageOf: "Page {page} of {pages}",

package/src/components/sortable/sortable-list.tsx

@@ -0,0 +1,450 @@
+"use client";
+
+import {
+  type CollisionDetection,
+  closestCenter,
+  DndContext,
+  type DragEndEvent,
+  type DragOverEvent,
+  type DragStartEvent,
+  KeyboardSensor,
+  PointerSensor,
+  type UniqueIdentifier,
+  useDroppable,
+  useSensor,
+  useSensors,
+} from "@dnd-kit/core";
+import {
+  SortableContext,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { Button } from "@suphark/ui/components/shared/button/button";
+import { useUiText } from "@suphark/ui/components/shared/ui-text";
+import { errorMessage } from "@suphark/ui/lib/action-result";
+import {
+  groupOfItem,
+  moveItemToGroup,
+  reorderGroups,
+  reorderItems,
+  type SortableOrder,
+  sameOrder,
+  UNGROUPED,
+} from "@suphark/ui/lib/sortable-order";
+import { cn } from "@suphark/ui/lib/utils";
+import { GripVerticalIcon } from "lucide-react";
+import {
+  type CSSProperties,
+  createContext,
+  type ReactNode,
+  useCallback,
+  useContext,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { toast } from "sonner";
+
+export type SortableKind = "group" | "item";
+
+// id ของ dnd-kit ต้องไม่ชนกันข้ามชนิด: กลุ่ม / รายการ / หัวกลุ่มที่ใช้เป็นที่วาง
+const dndId = (kind: SortableKind | "zone", id: string) =>
+  `${kind === "group" ? "g" : kind === "item" ? "i" : "z"}:${id}`;
+const kindOf = (id: UniqueIdentifier) => String(id).slice(0, 1);
+const rawOf = (id: UniqueIdentifier) => String(id).slice(2);
+
+/** ลากกลุ่มชนได้แค่กลุ่ม ลากรายการชนได้แค่รายการกับหัวกลุ่ม — ไม่งั้น closestCenter สลับชนิดกันมั่ว */
+const collision: CollisionDetection = (args) => {
+  const draggingGroup = kindOf(args.active.id) === "g";
+  return closestCenter({
+    ...args,
+    droppableContainers: args.droppableContainers.filter(
+      (container) => (kindOf(container.id) === "g") === draggingGroup,
+    ),
+  });
+};
+
+interface SortableState {
+  /** กำลังลากชนิดไหนอยู่ (null = ไม่ได้ลาก) — ใช้ปิดที่วางของอีกชนิด */
+  dragging: SortableKind | null;
+  disabled: boolean;
+  handleLabel: string;
+}
+
+const SortableStateContext = createContext<SortableState>({
+  dragging: null,
+  disabled: true,
+  handleLabel: "ลากเพื่อจัดลำดับ",
+});
+
+/**
+ * สถานะการลากตอนนี้ — ใช้ตัดสินใจเรนเดอร์ที่วางเอง เช่นแถว "ลากมาที่นี่เพื่อเอาออกจากกลุ่ม"
+ * ที่ควรโผล่เฉพาะตอน `dragging === "item"` (กลุ่มที่ไม่มีหัวกลุ่มต้องมีที่วางของตัวเอง)
+ */
+export function useSortableState(): { dragging: SortableKind | null; disabled: boolean } {
+  const state = useContext(SortableStateContext);
+  return { dragging: state.dragging, disabled: state.disabled };
+}
+
+/** ข้อมูลของสิ่งที่กำลังลาก ส่งให้แอปประกอบข้อความเอง (แอปรู้ชื่อคีย์/ชื่อกลุ่ม แพ็กเกจไม่รู้) */
+export interface SortableAnnouncementContext {
+  id: string;
+  kind: SortableKind;
+  /** กลุ่มที่อยู่ตอนนี้ (เฉพาะ kind = "item") */
+  groupId?: string;
+  /** ตำแหน่งในกลุ่ม/ในลำดับกลุ่ม เริ่มที่ 1 */
+  index: number;
+  total: number;
+}
+
+export interface SortableAnnouncements {
+  onDragStart?: (context: SortableAnnouncementContext) => string | undefined;
+  onDragOver?: (context: SortableAnnouncementContext) => string | undefined;
+  onDragEnd?: (context: SortableAnnouncementContext) => string | undefined;
+  onDragCancel?: (context: SortableAnnouncementContext) => string | undefined;
+}
+
+export interface SortableProviderProps {
+  order: SortableOrder;
+  /** ลำดับเปลี่ยนระหว่างลาก (ย้ายข้ามกลุ่ม) และตอนปล่อย — แอปเก็บไว้ใน state ของตัวเอง */
+  onOrderChange: (order: SortableOrder) => void;
+  /**
+   * บันทึกลำดับใหม่ตอนปล่อย — throw หรือคืน `{ ok: false, error }` = ล้มเหลว
+   * ล้มเหลวแล้ว provider คืนลำดับเดิมให้เองและขึ้น toast (ไม่ต้องจัดการใน call site)
+   */
+  onCommit?: (order: SortableOrder) => void | Promise<unknown>;
+  /** ปิดการลากทั้งชุด (เช่นระหว่างค้นหา หรือผู้ใช้ไม่มีสิทธิ์แก้) */
+  disabled?: boolean;
+  /** aria-label ของที่จับ (ค่าเริ่มต้นจาก `UiText.sortable.handle`) */
+  handleLabel?: string;
+  /**
+   * `onCommit` ล้มเหลวแล้วทำอะไรต่อ — ไม่ส่ง = ขึ้น toast ข้อความของ error ให้เอง
+   * ส่งมา = แพ็กเกจไม่ขึ้น toast แต่ส่ง error ดิบให้แอปจัดการ (คืนลำดับเดิมให้เสมอทั้งสองทาง)
+   */
+  onCommitError?: (error: unknown) => void;
+  /** คำอธิบายวิธีลากด้วยคีย์บอร์ด (ไม่ส่ง = `UiText.sortable.instructions`) */
+  screenReaderInstructions?: string;
+  /**
+   * ข้อความประกาศระหว่างลากสำหรับ screen reader — แอปประกอบเองจากชื่อจริงของข้อมูล
+   * ไม่ส่ง = แม่แบบจาก `UiText.sortable` (`{index}` / `{total}`)
+   */
+  announcements?: SortableAnnouncements;
+  children: ReactNode;
+}
+
+/**
+ * บริบทการลากจัดลำดับ 2 ระดับ (กลุ่ม + รายการในกลุ่ม) — ยกสมองส่วนลากออกมาจากแอป
+ * การเรนเดอร์ยังเป็นของแอป (แถวตาราง/การ์ด/รายการ) ผ่าน `useSortableRow`
+ * ย้ายข้ามกลุ่มได้ระหว่างลาก และกลุ่มที่ย่ออยู่ก็ยังรับการวางได้ด้วย `useSortableDropZone`
+ *
+ *   <SortableProvider order={order} onOrderChange={setOrder} onCommit={save}>
+ *     <SortableGroup id={UNGROUPED} itemIds={order.items[UNGROUPED]}>…</SortableGroup>
+ *   </SortableProvider>
+ */
+export function SortableProvider({
+  order,
+  onOrderChange,
+  onCommit,
+  disabled = false,
+  handleLabel,
+  onCommitError,
+  screenReaderInstructions,
+  announcements,
+  children,
+}: SortableProviderProps) {
+  const text = useUiText();
+  const [dragging, setDragging] = useState<SortableKind | null>(null);
+  const beforeDrag = useRef<SortableOrder | null>(null);
+  // อ่านลำดับล่าสุดตอนปล่อย (onDragOver เปลี่ยนไปหลายรอบแล้ว prop ยังไม่ทัน)
+  const latest = useRef(order);
+  latest.current = order;
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 5 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  const containerOf = useCallback((id: UniqueIdentifier, current: SortableOrder) => {
+    if (kindOf(id) === "z") return rawOf(id);
+    return groupOfItem(current, rawOf(id));
+  }, []);
+
+  function onDragStart({ active }: DragStartEvent) {
+    beforeDrag.current = latest.current;
+    setDragging(kindOf(active.id) === "g" ? "group" : "item");
+  }
+
+  function onDragOver({ active, over }: DragOverEvent) {
+    if (!over || kindOf(active.id) !== "i") return;
+    const current = latest.current;
+    const from = containerOf(active.id, current);
+    const to = containerOf(over.id, current);
+    if (!from || !to || from === to) return;
+    const next = moveItemToGroup(
+      current,
+      rawOf(active.id),
+      to,
+      kindOf(over.id) === "i" ? rawOf(over.id) : null,
+    );
+    if (next !== current) {
+      latest.current = next;
+      onOrderChange(next);
+    }
+  }
+
+  /** ล้มเหลว = คืนลำดับเดิมเสมอ แล้วส่ง error ต่อให้แอป (ไม่มี `onCommitError` = ขึ้น toast ให้) */
+  function failed(error: unknown, snapshot: SortableOrder) {
+    onOrderChange(snapshot);
+    latest.current = snapshot;
+    if (onCommitError) onCommitError(error);
+    else toast.error(errorMessage(error, text.actionFailed ?? "ดำเนินการไม่สำเร็จ"));
+  }
+
+  async function commit(next: SortableOrder, snapshot: SortableOrder) {
+    if (!onCommit) return;
+    try {
+      const result = await onCommit(next);
+      // server action ที่คืน { ok: false, error } ถือว่าล้มเหลวเหมือน throw
+      if (result && typeof result === "object" && "ok" in result && result.ok === false) {
+        failed("error" in result ? result.error : undefined, snapshot);
+      }
+    } catch (err) {
+      failed(err, snapshot);
+    }
+  }
+
+  function onDragEnd({ active, over }: DragEndEvent) {
+    const snapshot = beforeDrag.current;
+    beforeDrag.current = null;
+    setDragging(null);
+    const current = latest.current;
+    let next = current;
+    if (over && kindOf(active.id) === "g" && kindOf(over.id) === "g") {
+      next = reorderGroups(current, rawOf(active.id), rawOf(over.id));
+    } else if (over && kindOf(active.id) === "i" && kindOf(over.id) === "i") {
+      next = reorderItems(current, rawOf(active.id), rawOf(over.id));
+    }
+    if (next !== current) {
+      latest.current = next;
+      onOrderChange(next);
+    }
+    if (snapshot && !sameOrder(snapshot, next)) void commit(next, snapshot);
+  }
+
+  function onDragCancel() {
+    const snapshot = beforeDrag.current;
+    beforeDrag.current = null;
+    setDragging(null);
+    if (snapshot) {
+      latest.current = snapshot;
+      onOrderChange(snapshot);
+    }
+  }
+
+  const instructions =
+    screenReaderInstructions ??
+    text.sortable?.instructions ??
+    "กด Space เพื่อเริ่มลาก ใช้ปุ่มลูกศรเลื่อน แล้วกด Space อีกครั้งเพื่อวาง (Esc = ยกเลิก)";
+
+  /** เหตุการณ์ของ dnd-kit → บริบทที่แอปอ่านง่าย (ตำแหน่งเริ่มที่ 1) */
+  const describe = useCallback((id: UniqueIdentifier): SortableAnnouncementContext => {
+    const current = latest.current;
+    const raw = rawOf(id);
+    if (kindOf(id) === "g") {
+      return {
+        id: raw,
+        kind: "group",
+        index: current.groups.indexOf(raw) + 1,
+        total: current.groups.length,
+      };
+    }
+    const group = groupOfItem(current, raw);
+    const list = group ? (current.items[group] ?? []) : [];
+    return {
+      id: raw,
+      kind: "item",
+      groupId: group,
+      index: list.indexOf(raw) + 1,
+      total: list.length,
+    };
+  }, []);
+
+  const dndAnnouncements = useMemo(() => {
+    const fill = (
+      template: string | undefined,
+      fallback: string,
+      ctx: SortableAnnouncementContext,
+    ) =>
+      (template ?? fallback)
+        .replace("{index}", String(ctx.index))
+        .replace("{total}", String(ctx.total));
+    const announce =
+      (
+        own: ((context: SortableAnnouncementContext) => string | undefined) | undefined,
+        template: string | undefined,
+        fallback: string,
+      ) =>
+      ({ active }: { active: { id: UniqueIdentifier } }) => {
+        const context = describe(active.id);
+        return own?.(context) ?? fill(template, fallback, context);
+      };
+    return {
+      onDragStart: announce(
+        announcements?.onDragStart,
+        text.sortable?.started,
+        "เริ่มลากรายการที่ {index} จาก {total}",
+      ),
+      onDragOver: announce(
+        announcements?.onDragOver,
+        text.sortable?.moved,
+        "ย้ายไปตำแหน่งที่ {index} จาก {total}",
+      ),
+      onDragEnd: announce(
+        announcements?.onDragEnd,
+        text.sortable?.dropped,
+        "วางที่ตำแหน่งที่ {index} จาก {total}",
+      ),
+      onDragCancel: announce(announcements?.onDragCancel, text.sortable?.cancelled, "ยกเลิกการลาก"),
+    };
+  }, [announcements, describe, text.sortable]);
+
+  const state = useMemo<SortableState>(
+    () => ({
+      dragging,
+      disabled,
+      handleLabel: handleLabel ?? text.sortable?.handle ?? "ลากเพื่อจัดลำดับ",
+    }),
+    [dragging, disabled, handleLabel, text.sortable?.handle],
+  );
+
+  return (
+    <SortableStateContext.Provider value={state}>
+      <DndContext
+        sensors={sensors}
+        collisionDetection={collision}
+        accessibility={{
+          screenReaderInstructions: { draggable: instructions },
+          announcements: dndAnnouncements,
+        }}
+        onDragStart={onDragStart}
+        onDragOver={onDragOver}
+        onDragEnd={onDragEnd}
+        onDragCancel={onDragCancel}
+      >
+        {children}
+      </DndContext>
+    </SortableStateContext.Provider>
+  );
+}
+
+/** ขอบเขตการเรียงของกลุ่มหนึ่ง — ครอบแถวของกลุ่มนั้น (ลำดับ id ต้องตรงกับที่เรนเดอร์) */
+export function SortableGroup({
+  itemIds,
+  children,
+}: {
+  itemIds: ReadonlyArray<string>;
+  children: ReactNode;
+}) {
+  const ids = useMemo(() => itemIds.map((id) => dndId("item", id)), [itemIds]);
+  return (
+    <SortableContext items={ids} strategy={verticalListSortingStrategy}>
+      {children}
+    </SortableContext>
+  );
+}
+
+export interface SortableRow {
+  /** แปะที่ element ของแถว */
+  ref: (node: HTMLElement | null) => void;
+  style: CSSProperties;
+  /** props ที่ต้องแปะที่ "ที่จับ" — ส่งต่อให้ `<DragHandle {...handleProps} />` */
+  handleProps: Record<string, unknown>;
+  isDragging: boolean;
+}
+
+/**
+ * ทำให้แถวหนึ่งลากได้ — แอปเอา `ref`/`style` ไปแปะที่ `<TableRow>` และ `handleProps` ที่ `<DragHandle>`
+ * `type: "group"` = ลากทั้งกลุ่ม, `"item"` = ลากรายการในกลุ่ม
+ */
+export function useSortableRow({
+  type,
+  id,
+  disabled,
+}: {
+  type: SortableKind;
+  id: string;
+  /** ปิดเฉพาะแถวนี้ (ทั้งชุดปิดที่ `SortableProvider disabled`) */
+  disabled?: boolean;
+}): SortableRow {
+  const state = useContext(SortableStateContext);
+  const sortable = useSortable({
+    id: dndId(type, id),
+    disabled: disabled || state.disabled,
+  });
+  return {
+    ref: sortable.setNodeRef,
+    style: {
+      transform: CSS.Translate.toString(sortable.transform),
+      transition: sortable.transition,
+      ...(sortable.isDragging ? { position: "relative", zIndex: 1, opacity: 0.85 } : {}),
+    },
+    handleProps: { ...sortable.attributes, ...sortable.listeners },
+    isDragging: sortable.isDragging,
+  };
+}
+
+/**
+ * ทำให้หัวกลุ่ม (หรือพื้นที่ว่างของกลุ่ม) รับการวางรายการได้ — กลุ่มที่ย่ออยู่ก็ยังรับได้
+ * ปิดเองเมื่อกำลังลากกลุ่ม (ไม่ใช่รายการ)
+ */
+export function useSortableDropZone(groupId: string | null): {
+  ref: (node: HTMLElement | null) => void;
+  isOver: boolean;
+} {
+  const state = useContext(SortableStateContext);
+  const droppable = useDroppable({
+    // `null` = กลุ่มของรายการที่ยังไม่มีกลุ่ม (เขียน `useSortableDropZone(null)` ได้เลย)
+    id: dndId("zone", groupId ?? UNGROUPED),
+    disabled: state.disabled || state.dragging !== "item",
+  });
+  return { ref: droppable.setNodeRef, isOver: droppable.isOver };
+}
+
+/**
+ * ปุ่มที่จับสำหรับลาก — ใช้ `Button` ของแพ็กเกจ จึงได้ tooltip จาก `aria-label` อัตโนมัติ
+ * ต้องกระจาย `handleProps` จาก `useSortableRow` ลงไปด้วยเสมอ
+ */
+export function DragHandle({
+  label,
+  className,
+  disabled,
+  hideWhenDisabled = false,
+  ...handleProps
+}: {
+  label?: string;
+  className?: string;
+  disabled?: boolean;
+  /** ปิดการลากแล้วไม่ต้องแสดงที่จับเลย (ค่าเริ่มต้นคือแสดงแบบจาง ๆ ให้รู้ว่ามีแต่ตอนนี้ลากไม่ได้) */
+  hideWhenDisabled?: boolean;
+} & Record<string, unknown>) {
+  const state = useContext(SortableStateContext);
+  const off = disabled ?? state.disabled;
+  if (off && hideWhenDisabled) return null;
+  return (
+    <Button
+      variant="ghost"
+      size="icon-sm"
+      aria-label={label ?? state.handleLabel}
+      disabled={off}
+      className={cn("cursor-grab touch-none active:cursor-grabbing", className)}
+      {...handleProps}
+    >
+      <GripVerticalIcon />
+    </Button>
+  );
+}
+
+export type { SortableOrder };
+export { UNGROUPED };

package/src/lib/sortable-order.ts

@@ -0,0 +1,142 @@
+/**
+ * ลำดับของรายการ 2 ระดับ (กลุ่ม → รายการในกลุ่ม) แบบ pure — ไม่พึ่ง dnd-kit และไม่พึ่ง React
+ * ใช้โดย `@suphark/ui/sortable` และเทสต์ได้ตรง ๆ; แอปเอาไปสร้าง payload ตอนบันทึกได้เลย
+ */
+
+/** รายการที่ยังไม่อยู่กลุ่มไหน — เก็บในถังนี้ (แสดงเป็นกลุ่มไม่มีชื่อ) */
+export const UNGROUPED = "__ungrouped__";
+
+export interface SortableOrder {
+  /** ลำดับของกลุ่ม (ไม่รวม `UNGROUPED`) */
+  groups: string[];
+  /** id ของรายการในแต่ละกลุ่ม — key เป็น id ของกลุ่มหรือ `UNGROUPED` */
+  items: Record<string, string[]>;
+}
+
+/** สร้างลำดับเริ่มต้นจากข้อมูลที่โหลดมา (กลุ่มเรียงตามที่ส่งมา รายการเรียงตามที่ส่งมา) */
+export function sortableOrderOf<TGroup, TItem>(
+  groups: ReadonlyArray<TGroup>,
+  items: ReadonlyArray<TItem>,
+  select: {
+    groupId: (group: TGroup) => string;
+    itemId: (item: TItem) => string;
+    /** รายการนี้อยู่กลุ่มไหน — `null`/`undefined` = ยังไม่อยู่กลุ่มไหน */
+    itemGroupId: (item: TItem) => string | null | undefined;
+  },
+): SortableOrder {
+  const order: SortableOrder = { groups: [], items: { [UNGROUPED]: [] } };
+  for (const group of groups) {
+    const id = select.groupId(group);
+    order.groups.push(id);
+    order.items[id] = [];
+  }
+  for (const item of items) {
+    const container = select.itemGroupId(item) ?? UNGROUPED;
+    const list = order.items[container];
+    if (list) list.push(select.itemId(item));
+    else order.items[container] = [select.itemId(item)];
+  }
+  return order;
+}
+
+/** กลุ่มที่รายการนี้อยู่ (ไม่เจอ = undefined) */
+export function groupOfItem(order: SortableOrder, itemId: string): string | undefined {
+  return Object.keys(order.items).find((group) => order.items[group]?.includes(itemId));
+}
+
+/** ย้ายของในอาเรย์เดียว (เหมือน `arrayMove` ของ dnd-kit แต่ไม่ต้อง import) */
+export function moveWithin<T>(list: ReadonlyArray<T>, from: number, to: number): T[] {
+  const next = [...list];
+  const [moved] = next.splice(from, 1);
+  if (moved === undefined) return next;
+  next.splice(to, 0, moved);
+  return next;
+}
+
+/** เรียงกลุ่มใหม่: ย้าย `groupId` ไปอยู่ตำแหน่งของ `overGroupId` */
+export function reorderGroups(
+  order: SortableOrder,
+  groupId: string,
+  overGroupId: string,
+): SortableOrder {
+  const from = order.groups.indexOf(groupId);
+  const to = order.groups.indexOf(overGroupId);
+  if (from < 0 || to < 0 || from === to) return order;
+  return { ...order, groups: moveWithin(order.groups, from, to) };
+}
+
+/** เรียงรายการในกลุ่มเดียวกัน: ย้าย `itemId` ไปอยู่ตำแหน่งของ `overItemId` */
+export function reorderItems(
+  order: SortableOrder,
+  itemId: string,
+  overItemId: string,
+): SortableOrder {
+  const group = groupOfItem(order, itemId);
+  if (!group || group !== groupOfItem(order, overItemId)) return order;
+  const list = order.items[group] ?? [];
+  const from = list.indexOf(itemId);
+  const to = list.indexOf(overItemId);
+  if (from < 0 || to < 0 || from === to) return order;
+  return { ...order, items: { ...order.items, [group]: moveWithin(list, from, to) } };
+}
+
+/**
+ * ย้ายรายการไปกลุ่มอื่น — แทรกก่อน `beforeItemId` (ไม่ส่ง = ต่อท้ายกลุ่มปลายทาง)
+ * เรียกระหว่างลากได้ (ให้แถวไปโผล่ในกลุ่มใหม่ทันที) เพราะคืน object ใหม่เมื่อมีอะไรเปลี่ยนจริงเท่านั้น
+ */
+export function moveItemToGroup(
+  order: SortableOrder,
+  itemId: string,
+  toGroup: string,
+  beforeItemId?: string | null,
+): SortableOrder {
+  const from = groupOfItem(order, itemId);
+  if (!from || from === toGroup) return order;
+  const target = order.items[toGroup] ?? [];
+  const at = beforeItemId ? target.indexOf(beforeItemId) : -1;
+  const index = at >= 0 ? at : target.length;
+  return {
+    ...order,
+    items: {
+      ...order.items,
+      [from]: (order.items[from] ?? []).filter((id) => id !== itemId),
+      [toGroup]: [...target.slice(0, index), itemId, ...target.slice(index)],
+    },
+  };
+}
+
+/** ลำดับเหมือนกันไหม (ใช้ตัดสินว่าต้องบันทึกหรือไม่) */
+export function sameOrder(a: SortableOrder, b: SortableOrder): boolean {
+  if (a === b) return true;
+  if (a.groups.length !== b.groups.length) return false;
+  if (a.groups.some((id, i) => b.groups[i] !== id)) return false;
+  const keys = new Set([...Object.keys(a.items), ...Object.keys(b.items)]);
+  for (const key of keys) {
+    const left = a.items[key] ?? [];
+    const right = b.items[key] ?? [];
+    if (left.length !== right.length) return false;
+    if (left.some((id, i) => right[i] !== id)) return false;
+  }
+  return true;
+}
+
+export interface SortableOrderPayload {
+  /** ลำดับของกลุ่ม (ไม่มี `UNGROUPED` — ของที่ไม่มีกลุ่มไม่ใช่กลุ่มจริง) */
+  groups: string[];
+  /** รายการในแต่ละกลุ่ม เรียงตามลำดับกลุ่ม โดยของที่ไม่มีกลุ่มมาก่อนด้วย `groupId: null` */
+  items: Array<{ groupId: string | null; itemIds: string[] }>;
+}
+
+/**
+ * แปลงเป็นรูปที่ส่งเข้า server action ได้ — คืนทั้งลำดับกลุ่มและรายการในกลุ่ม
+ * ชื่อฟิลด์เป็นศัพท์กลางของแพ็กเกจ (`groupId`) แอปที่ใช้ศัพท์อื่น (เช่น `sectionId`) rename ชั้นเดียวที่ปลายทาง
+ */
+export function sortableOrderToPayload(order: SortableOrder): SortableOrderPayload {
+  return {
+    groups: [...order.groups],
+    items: [UNGROUPED, ...order.groups].map((group) => ({
+      groupId: group === UNGROUPED ? null : group,
+      itemIds: order.items[group] ?? [],
+    })),
+  };
+}

package/src/sortable.ts

@@ -0,0 +1,31 @@
+/**
+ * @suphark/ui/sortable — ลากจัดลำดับ 2 ระดับ (กลุ่ม + รายการในกลุ่ม) บน dnd-kit
+ * แยกจาก barrel หลักเพราะ @dnd-kit/core สร้าง React context ตอน import (ใช้จาก server component ไม่ได้)
+ * เช่นเดียวกับ data-table/kanban — การเรนเดอร์แถวยังเป็นของแอป (ตาราง/การ์ด/รายการ)
+ */
+export {
+  DragHandle,
+  type SortableAnnouncementContext,
+  type SortableAnnouncements,
+  SortableGroup,
+  type SortableKind,
+  SortableProvider,
+  type SortableProviderProps,
+  type SortableRow,
+  useSortableDropZone,
+  useSortableRow,
+  useSortableState,
+} from "./components/sortable/sortable-list";
+export {
+  groupOfItem,
+  moveItemToGroup,
+  moveWithin,
+  reorderGroups,
+  reorderItems,
+  type SortableOrder,
+  type SortableOrderPayload,
+  sameOrder,
+  sortableOrderOf,
+  sortableOrderToPayload,
+  UNGROUPED,
+} from "./lib/sortable-order";