@suphark/ui 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 รูปแบบตาม [Keep a Changelog](https://keepachangelog.com/) · semver: patch = หน้าตา/บั๊ก, minor = component/prop ใหม่, major = เปลี่ยน/ลบ props
 
+## [0.34.0] — 2026-10-06
+
+### Fixed
+
+- **`SortableProvider` ทำ hydration mismatch ทุกหน้าที่ SSR** (รายงานจาก Pi Config ตอนลากบนของจริง): ไม่ได้ส่ง `id` ให้ `DndContext` → dnd-kit สร้าง `aria-describedby="DndDescribedBy-N"` จากตัวนับที่เดินไม่ตรงกันระหว่าง server กับ client, React 19 ขึ้น error และ **ไม่ซ่อมให้** — attribute ค้างชี้ element ที่ไม่มีอยู่ ผู้ใช้ screen reader จึงไม่ได้ยินคำอธิบายวิธีลาก · ตอนนี้ค่าเริ่มต้นเป็น `useId()` (ตรงกันทั้งสองฝั่ง) และรับ prop **`id`** สำหรับ id ที่สื่อความหมาย — กระทบทุกแอปที่ใช้ `@suphark/ui/sortable` ใน Next.js
+- `@suphark/ui/sortable`: เสียงประกาศระหว่างลากในกลุ่มเดียวกันบอกตำแหน่ง **เดิม** ซ้ำ ("ย้ายไปตำแหน่งที่ 1 จาก 2" ทั้งที่เลื่อนลงแล้ว) เพราะลำดับจริงเปลี่ยนตอนปล่อย — ตอนนี้ระหว่างลากประกาศตำแหน่งของเป้าหมาย และตอนปล่อยประกาศตำแหน่งจริงหลังย้าย (เจอระหว่างทดสอบลากด้วยคีย์บอร์ดตามที่ Pi Config ถาม; ลากด้วยคีย์บอร์ดเองทำงานถูกอยู่แล้ว)
+- showcase: `/components/sortable-list` ย้ายแถว "ลากมาที่นี่เพื่อเอาออกจากกลุ่ม" ไปท้ายตาราง — เดิมโผล่เหนือกลุ่มตอนเริ่มลาก ดันแถวที่กำลังลากลง จนลากคีย์ในกลุ่มด้วยคีย์บอร์ดไม่ขยับ (README เพิ่มคำเตือนนี้ + เรื่อง `id`)
+
 ## [0.33.0] — 2026-10-06
 
 ### Fixed

package/README.md

@@ -217,7 +217,8 @@ const [order, setOrder] = useState(() =>
 </SortableProvider>
 ```
 
-- กลุ่มที่ไม่มีหัวกลุ่ม (เช่น "ยังไม่จัดกลุ่ม") ใช้ `useSortableDropZone(groupId)` แปะกับแถว placeholder ของตัวเอง และดูว่าควรแสดงเมื่อไหร่จาก `useSortableState().dragging`
+- กลุ่มที่ไม่มีหัวกลุ่ม (เช่น "ยังไม่จัดกลุ่ม") ใช้ `useSortableDropZone(groupId)` แปะกับแถว placeholder ของตัวเอง และดูว่าควรแสดงเมื่อไหร่จาก `useSortableState().dragging` — **วางแถวนี้ไว้ใต้แถวที่ลากได้ทั้งหมด (ท้ายตาราง)** ถ้ามันโผล่ขึ้นเหนือแถวที่กำลังลาก layout จะเลื่อนตอนเริ่มลาก แล้วการลากด้วยคีย์บอร์ดจะไม่ขยับ
+- ตั้ง `id` ของ `SortableProvider` ได้ (ไม่ตั้ง = `useId()`) — ต้องคงที่ระหว่าง SSR กับ client ไม่งั้น `aria-describedby` ของ dnd-kit จะ hydration mismatch
 - `onCommit` ล้มเหลว (throw หรือ `{ ok: false, error }`) = คืนลำดับเดิม + toast; ถ้าอยากจัดการ error เองใส่ `onCommitError`
 - `sortableOrderToPayload(order)` คืน `{ groups, items }` — `groups` คือลำดับของกลุ่ม, `items` คือรายการในแต่ละกลุ่มเรียงตามนั้น (ของที่ยังไม่มีกลุ่มมาก่อนด้วย `groupId: null`)
 - `SortableProvider disabled` (เช่นระหว่างกรอง ซึ่งลำดับที่เห็นไม่ใช่ลำดับจริง) ทำให้ `DragHandle` จางลงและกดไม่ได้ — ไม่อยากให้เห็นเลยใส่ `hideWhenDisabled`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suphark/ui",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "private": false,
   "type": "module",
   "description": "Design system กลางของ Suphark apps: shadcn/ui (base-nova, Base UI, Tailwind v4) + shared components + token/ฟอนต์ Noto Sans Thai Looped — ส่งเป็น source ให้แอป Next transpile เอง",

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

@@ -41,6 +41,7 @@ import {
   type ReactNode,
   useCallback,
   useContext,
+  useId,
   useMemo,
   useRef,
   useState,
@@ -131,6 +132,13 @@ export interface SortableProviderProps {
    * ไม่ส่ง = แม่แบบจาก `UiText.sortable` (`{index}` / `{total}`)
    */
   announcements?: SortableAnnouncements;
+  /**
+   * id ของ `DndContext` — ต้องคงที่ระหว่าง SSR กับ client ไม่งั้น `aria-describedby="DndDescribedBy-N"`
+   * ที่ dnd-kit สร้างจากตัวนับจะไม่ตรงกัน (hydration mismatch ที่ React ไม่ซ่อมให้ → screen reader
+   * ไม่ได้ยินคำอธิบายวิธีลาก) · ไม่ส่ง = `useId()` ซึ่งตรงกันทั้งสองฝั่งอยู่แล้ว · ส่ง id ที่สื่อความหมาย
+   * (เช่น `values-${environmentId}`) ช่วยตอนไล่ปัญหา
+   */
+  id?: string;
   children: ReactNode;
 }
 
@@ -152,8 +160,10 @@ export function SortableProvider({
   onCommitError,
   screenReaderInstructions,
   announcements,
+  id,
   children,
 }: SortableProviderProps) {
+  const fallbackId = useId();
   const text = useUiText();
   const [dragging, setDragging] = useState<SortableKind | null>(null);
   const beforeDrag = useRef<SortableOrder | null>(null);
@@ -271,6 +281,31 @@ export function SortableProvider({
     };
   }, []);
 
+  /**
+   * ตำแหน่งที่ "จะไปวาง" ระหว่างลาก — ในกลุ่มเดียวกันลำดับจริงยังไม่เปลี่ยนจนกว่าจะปล่อย
+   * (เดิมประกาศตำแหน่งเดิมซ้ำ เช่น "ตำแหน่งที่ 1" ทั้งที่เลื่อนลงมาแล้ว) จึงใช้ตำแหน่งของเป้าหมายแทน
+   * ข้ามกลุ่มไม่ต้องทำอะไร — onDragOver ย้ายเข้ากลุ่มใหม่ใน order ไปแล้ว
+   */
+  const describeTarget = useCallback(
+    (activeId: UniqueIdentifier, overId: UniqueIdentifier | null): SortableAnnouncementContext => {
+      const base = describe(activeId);
+      if (overId === null || overId === activeId) return base;
+      const current = latest.current;
+      if (base.kind === "group" && kindOf(overId) === "g") {
+        const at = current.groups.indexOf(rawOf(overId));
+        return at >= 0 ? { ...base, index: at + 1 } : base;
+      }
+      if (base.kind === "item" && kindOf(overId) === "i") {
+        const group = groupOfItem(current, rawOf(overId));
+        if (!group || group !== base.groupId) return base;
+        const at = (current.items[group] ?? []).indexOf(rawOf(overId));
+        return at >= 0 ? { ...base, index: at + 1 } : base;
+      }
+      return base;
+    },
+    [describe],
+  );
+
   const dndAnnouncements = useMemo(() => {
     const fill = (
       template: string | undefined,
@@ -285,9 +320,19 @@ export function SortableProvider({
         own: ((context: SortableAnnouncementContext) => string | undefined) | undefined,
         template: string | undefined,
         fallback: string,
+        // ระหว่างลาก = ตำแหน่งของเป้าหมาย; ตอนปล่อย order อัปเดตแล้ว จึงใช้ตำแหน่งจริงของตัวที่ลาก
+        useTarget = false,
       ) =>
-      ({ active }: { active: { id: UniqueIdentifier } }) => {
-        const context = describe(active.id);
+      ({
+        active,
+        over,
+      }: {
+        active: { id: UniqueIdentifier };
+        over?: { id: UniqueIdentifier } | null;
+      }) => {
+        const context = useTarget
+          ? describeTarget(active.id, over?.id ?? null)
+          : describe(active.id);
         return own?.(context) ?? fill(template, fallback, context);
       };
     return {
@@ -300,6 +345,7 @@ export function SortableProvider({
         announcements?.onDragOver,
         text.sortable?.moved,
         "ย้ายไปตำแหน่งที่ {index} จาก {total}",
+        true,
       ),
       onDragEnd: announce(
         announcements?.onDragEnd,
@@ -308,7 +354,7 @@ export function SortableProvider({
       ),
       onDragCancel: announce(announcements?.onDragCancel, text.sortable?.cancelled, "ยกเลิกการลาก"),
     };
-  }, [announcements, describe, text.sortable]);
+  }, [announcements, describeTarget, text.sortable]);
 
   const groupIds = useMemo(() => order.groups.map((id) => dndId("group", id)), [order.groups]);
 
@@ -324,6 +370,7 @@ export function SortableProvider({
   return (
     <SortableStateContext.Provider value={state}>
       <DndContext
+        id={id ?? fallbackId}
         sensors={sensors}
         collisionDetection={collision}
         accessibility={{