@suphark/ui 0.28.0 → 0.30.0

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/index.ts

@@ -197,7 +197,11 @@ export {
 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 { SegmentedControl, type SegmentedOption } from "./components/shared/segmented-control";
+export {
+  SegmentedControl,
+  type SegmentedOption,
+  type SegmentedTone,
+} from "./components/shared/segmented-control";
 export {
   type SelectionAction,
   SelectionBar,

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";