@hectasquare/medusa-plugin-category-tree 1.0.12 → 1.0.13

package/.medusa/server/src/admin/components/category-tree/category-tree-canvas.js

@@ -114,10 +114,46 @@ const CanvasInner = () => {
         });
     }, [selectedNodeIds]);
     const handleMoveSiblingUp = (0, react_1.useCallback)((id) => {
-        setCategories((prev) => (0, tree_state_1.moveSiblingRank)(prev, id, "up"));
+        setCategories((prev) => {
+            const { nextCategories, siblingMoves } = (0, tree_state_1.moveSiblingRank)(prev, id, "up");
+            if (siblingMoves.length > 0) {
+                // AAA Realtime: Immediately auto-persist contiguous ranks to backend in background
+                sdk_1.sdk.client
+                    .fetch("/admin/category-tree/reorder", {
+                    method: "POST",
+                    body: { moves: siblingMoves },
+                })
+                    .then(() => {
+                    setOriginalCategories([...nextCategories]);
+                })
+                    .catch((err) => {
+                    console.error("Failed to auto-save sibling rank:", err);
+                    ui_1.toast.error("Failed to save ranking: " + (err.message || "Unknown error"));
+                });
+            }
+            return nextCategories;
+        });
     }, []);
     const handleMoveSiblingDown = (0, react_1.useCallback)((id) => {
-        setCategories((prev) => (0, tree_state_1.moveSiblingRank)(prev, id, "down"));
+        setCategories((prev) => {
+            const { nextCategories, siblingMoves } = (0, tree_state_1.moveSiblingRank)(prev, id, "down");
+            if (siblingMoves.length > 0) {
+                // AAA Realtime: Immediately auto-persist contiguous ranks to backend in background
+                sdk_1.sdk.client
+                    .fetch("/admin/category-tree/reorder", {
+                    method: "POST",
+                    body: { moves: siblingMoves },
+                })
+                    .then(() => {
+                    setOriginalCategories([...nextCategories]);
+                })
+                    .catch((err) => {
+                    console.error("Failed to auto-save sibling rank:", err);
+                    ui_1.toast.error("Failed to save ranking: " + (err.message || "Unknown error"));
+                });
+            }
+            return nextCategories;
+        });
     }, []);
     const handleAddChild = (0, react_1.useCallback)((parent) => {
         setCreateParentCategory(parent);
@@ -315,6 +351,7 @@ const CanvasInner = () => {
                     setCategories((prev) => [...prev, newCat]);
                     setOriginalCategories((prev) => [...prev, newCat]);
                 } }), (0, jsx_runtime_1.jsx)(edit_category_drawer_1.EditCategoryDrawer, { open: editDrawerOpen, onOpenChange: setEditDrawerOpen, category: editingCategory, salesChannels: salesChannels, onSuccess: (updatedCat) => {
+                    setEditingCategory(updatedCat);
                     setCategories((prev) => prev.map((c) => (c.id === updatedCat.id ? updatedCat : c)));
                     setOriginalCategories((prev) => prev.map((c) => (c.id === updatedCat.id ? updatedCat : c)));
                 }, onDeleteSuccess: (deletedId) => {

package/.medusa/server/src/admin/components/category-tree/edit-category-drawer.js

@@ -51,7 +51,7 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
         if (category) {
             setName(category.name || "");
             setHandle(category.handle || "");
-            setDescription(category.description || "");
+            setDescription(category.description || category.metadata?.description || "");
             setImageUrl(category.image_url || "");
             setRank(category.rank ?? 0);
             setIsActive(Boolean(category.is_active));
@@ -362,9 +362,14 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
             ui_1.toast.info("Video removed (remember to save)");
         }
     };
-    const handleSubmit = async (e) => {
-        if (e && e.preventDefault)
-            e.preventDefault();
+    const handleSubmit = async (eOrClose, closeAfter = false) => {
+        let shouldClose = closeAfter;
+        if (typeof eOrClose === "boolean") {
+            shouldClose = eOrClose;
+        }
+        else if (eOrClose && eOrClose.preventDefault) {
+            eOrClose.preventDefault();
+        }
         if (!name.trim()) {
             ui_1.toast.error("Category name is required");
             return;
@@ -377,8 +382,10 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
             const bannerImg = categoryImages.find((img) => img.type === "banner") ||
                 (categoryImages.length > 1 ? categoryImages.find((img) => img.url !== thumbImg?.url) : null) ||
                 null;
+            const descValue = description.trim();
             const updatedMetadata = {
                 ...(currentMetadata || {}),
+                description: descValue || null,
                 sales_channels: selectedChannels,
                 youtube_urls: youtubeUrls,
                 youtube_url: youtubeUrls[0] || null,
@@ -393,7 +400,7 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
             await sdk_1.sdk.admin.productCategory.update(category.id, {
                 name: name.trim(),
                 handle: handle.trim() || undefined,
-                description: description.trim() || undefined,
+                description: descValue ? descValue : null,
                 rank: Number(rank) || 0,
                 is_active: isActive,
                 is_internal: isInternal,
@@ -403,7 +410,7 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
                 ...category,
                 name: name.trim(),
                 handle: handle.trim(),
-                description: description.trim() || null,
+                description: descValue ? descValue : null,
                 image_url: thumbImg ? thumbImg.url : "",
                 rank: Number(rank) || 0,
                 sales_channels: selectedChannels,
@@ -413,7 +420,9 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
             };
             ui_1.toast.success("Category updated successfully");
             onSuccess(updated);
-            onOpenChange(false);
+            if (shouldClose) {
+                onOpenChange(false);
+            }
         }
         catch (err) {
             ui_1.toast.error(err?.message || "Failed to update category");
@@ -473,7 +482,7 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
                                                                     ? "ring-2 ring-blue-500 border-transparent"
                                                                     : isBanner
                                                                         ? "ring-2 ring-emerald-500 border-transparent"
-                                                                        : "border-ui-border-base hover:border-ui-border-strong"}`, children: [(0, jsx_runtime_1.jsx)("img", { src: img.url, alt: "Category Media", className: "w-full h-full object-cover" }), isThumbnail && ((0, jsx_runtime_1.jsx)("div", { className: "absolute top-1.5 left-1.5 bg-blue-600 text-white text-[9px] font-bold px-1.5 py-0.5 rounded shadow-xs", children: "\u2605 Thumbnail" })), !isThumbnail && isBanner && ((0, jsx_runtime_1.jsx)("div", { className: "absolute top-1.5 left-1.5 bg-emerald-600 text-white text-[9px] font-bold px-1.5 py-0.5 rounded shadow-xs", children: "\uD83D\uDDBC\uFE0F Hero Banner" })), (0, jsx_runtime_1.jsxs)("div", { className: "absolute inset-0 bg-black/60 opacity-0 group-hover:opacity-100 transition-opacity flex flex-col items-center justify-center gap-1.5 p-1.5", children: [!isThumbnail && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: (e) => {
+                                                                        : "border-ui-border-base hover:border-ui-border-strong"}`, children: [(0, jsx_runtime_1.jsx)("img", { src: img.url, alt: "Category Media", className: "w-full h-full object-contain p-1.5" }), isThumbnail && ((0, jsx_runtime_1.jsx)("div", { className: "absolute top-1.5 left-1.5 bg-blue-600 text-white text-[9px] font-bold px-1.5 py-0.5 rounded shadow-xs", children: "\u2605 Thumbnail" })), !isThumbnail && isBanner && ((0, jsx_runtime_1.jsx)("div", { className: "absolute top-1.5 left-1.5 bg-emerald-600 text-white text-[9px] font-bold px-1.5 py-0.5 rounded shadow-xs", children: "\uD83D\uDDBC\uFE0F Hero Banner" })), (0, jsx_runtime_1.jsxs)("div", { className: "absolute inset-0 bg-black/60 opacity-0 group-hover:opacity-100 transition-opacity flex flex-col items-center justify-center gap-1.5 p-1.5", children: [!isThumbnail && ((0, jsx_runtime_1.jsx)("button", { type: "button", onClick: (e) => {
                                                                                     e.preventDefault();
                                                                                     e.stopPropagation();
                                                                                     handleSetThumbnail(img);
@@ -500,6 +509,13 @@ const EditCategoryDrawer = ({ open, onOpenChange, category, salesChannels, onSuc
                                             const id = extractYouTubeVideoId(url);
                                             const thumb = id ? `https://img.youtube.com/vi/${id}/hqdefault.jpg` : null;
                                             return ((0, jsx_runtime_1.jsxs)("div", { className: "flex flex-col border border-ui-border-base rounded-xl overflow-hidden bg-ui-bg-subtle/40 shadow-xs", children: [(0, jsx_runtime_1.jsxs)("div", { className: "relative aspect-video bg-black/80 overflow-hidden flex items-center justify-center", children: [thumb ? ((0, jsx_runtime_1.jsx)("img", { src: thumb, alt: "YouTube Preview", className: "w-full h-full object-cover" })) : ((0, jsx_runtime_1.jsx)("span", { className: "text-xs text-white", children: "Video" })), (0, jsx_runtime_1.jsx)("button", { type: "button", onClick: () => handleRemoveYoutube(url), className: "absolute top-1.5 right-1.5 p-1 bg-black/70 hover:bg-rose-600 text-white rounded-full transition-colors cursor-pointer", title: "Remove video", children: (0, jsx_runtime_1.jsx)(icons_1.Trash, { className: "w-3 h-3" }) })] }), (0, jsx_runtime_1.jsx)("div", { className: "p-2", children: (0, jsx_runtime_1.jsx)("span", { className: "text-[10px] text-ui-fg-muted truncate block font-mono", title: url, children: url }) })] }, url));
-                                        }) }))] }))] }), (0, jsx_runtime_1.jsxs)(ui_1.Drawer.Footer, { className: "flex justify-end gap-2 px-6 py-4 border-t border-ui-border-base", children: [(0, jsx_runtime_1.jsx)(ui_1.Button, { type: "button", variant: "secondary", size: "small", onClick: () => onOpenChange(false), disabled: isSubmitting || isDeleting, children: "Close" }), (0, jsx_runtime_1.jsx)(ui_1.Button, { type: "button", size: "small", onClick: () => handleSubmit(), isLoading: isSubmitting, disabled: isSubmitting || !name.trim() || isDeleting, children: "Save Category" })] })] }) }) }));
+                                        }) }))] }))] }), (0, jsx_runtime_1.jsxs)(ui_1.Drawer.Footer, { className: "flex justify-end gap-2 px-6 py-4 border-t border-ui-border-base", children: [(0, jsx_runtime_1.jsx)(ui_1.Button, { type: "button", variant: "secondary", size: "small", onClick: () => {
+                                    if (name.trim()) {
+                                        handleSubmit(true);
+                                    }
+                                    else {
+                                        onOpenChange(false);
+                                    }
+                                }, disabled: isSubmitting || isDeleting, children: "Close" }), (0, jsx_runtime_1.jsx)(ui_1.Button, { type: "button", size: "small", onClick: () => handleSubmit(false), isLoading: isSubmitting, disabled: isSubmitting || !name.trim() || isDeleting, children: "Save Category" })] })] }) }) }));
 };
 exports.EditCategoryDrawer = EditCategoryDrawer;

package/.medusa/server/src/admin/components/category-tree/lib/layout-engine.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.computeDagreLayout = exports.CARD_HEIGHT = exports.CARD_WIDTH = void 0;
 exports.computeTreeLayout = computeTreeLayout;
 const react_1 = require("@xyflow/react");
+const tree_state_1 = require("./tree-state");
 exports.CARD_WIDTH = 270;
 exports.CARD_HEIGHT = 86;
 /**
@@ -32,15 +33,18 @@ function computeTreeLayout(nodes, edges, options = {}) {
         }
     });
     // Identify roots (nodes with no incoming edge in the visible graph)
-    const rootNodes = nodes.filter((n) => !parentMap.has(n.id));
-    // Sort children by their category rank
-    const getRank = (id) => {
-        const raw = nodeMap.get(id)?.data?.category?.rank;
-        return typeof raw === "number" ? raw : 0;
-    };
+    const rootNodes = nodes.filter((n) => !parentMap.has(n.id)).sort((a, b) => {
+        const catA = a.data?.category || { id: a.id };
+        const catB = b.data?.category || { id: b.id };
+        return (0, tree_state_1.compareCategories)(catA, catB);
+    });
     function buildTree(id, depth) {
         const rawNode = nodeMap.get(id);
-        const childIds = (childrenMap.get(id) || []).sort((a, b) => getRank(a) - getRank(b) || a.localeCompare(b));
+        const childIds = (childrenMap.get(id) || []).sort((aId, bId) => {
+            const catA = nodeMap.get(aId)?.data?.category || { id: aId };
+            const catB = nodeMap.get(bId)?.data?.category || { id: bId };
+            return (0, tree_state_1.compareCategories)(catA, catB);
+        });
         const children = childIds.map((childId) => buildTree(childId, depth + 1));
         return {
             id,
@@ -87,8 +91,6 @@ function computeTreeLayout(nodes, edges, options = {}) {
         const centerOfChildren = (firstChild.primaryCoord + lastChild.primaryCoord) / 2;
         treeNode.primaryCoord = centerOfChildren;
     }
-    // Sort roots by their rank
-    rootNodes.sort((a, b) => getRank(a.id) - getRank(b.id) || a.id.localeCompare(b.id));
     const positionedNodes = [];
     let globalOffset = 0;
     rootNodes.forEach((root) => {

package/.medusa/server/src/admin/components/category-tree/lib/tree-state.d.ts

@@ -2,6 +2,15 @@ import { Node, Edge } from "@xyflow/react";
 import { CategoryTreeNode, CategoryMoveItem } from "../types";
 export declare function toSuperscript(num: number): string;
 export declare function computeTiers(categories: CategoryTreeNode[]): Map<string, number>;
+export declare function compareCategories(a: {
+    rank?: number;
+    name?: string;
+    id?: string;
+}, b: {
+    rank?: number;
+    name?: string;
+    id?: string;
+}): number;
 export declare function computeSiblingRanks(categories: CategoryTreeNode[]): Map<string, {
     rankNum: number;
     superscript: string;
@@ -24,6 +33,14 @@ export declare const BRANCH_PALETTE: {
 export declare function computeBranchColors(categories: CategoryTreeNode[]): Map<string, string>;
 /**
  * Swaps sibling ranking (up or down). Modifies rank property among siblings
- * and returns a new categories array ready for preview and commit.
+ * and returns a new categories array ready for preview and commit, along with
+ * explicit contiguous moves for all siblings in the group.
  */
-export declare function moveSiblingRank(categories: CategoryTreeNode[], targetId: string, direction: "up" | "down"): CategoryTreeNode[];
+export declare function moveSiblingRank(categories: CategoryTreeNode[], targetId: string, direction: "up" | "down"): {
+    nextCategories: CategoryTreeNode[];
+    siblingMoves: Array<{
+        id: string;
+        parent_category_id: string | null;
+        rank: number;
+    }>;
+};

package/.medusa/server/src/admin/components/category-tree/lib/tree-state.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BRANCH_PALETTE = void 0;
 exports.toSuperscript = toSuperscript;
 exports.computeTiers = computeTiers;
+exports.compareCategories = compareCategories;
 exports.computeSiblingRanks = computeSiblingRanks;
 exports.wouldCreateCycle = wouldCreateCycle;
 exports.computeSubtreeIds = computeSubtreeIds;
@@ -53,6 +54,18 @@ function computeTiers(categories) {
     }
     return tierMap;
 }
+function compareCategories(a, b) {
+    const rankA = typeof a.rank === "number" ? a.rank : 9999;
+    const rankB = typeof b.rank === "number" ? b.rank : 9999;
+    if (rankA !== rankB)
+        return rankA - rankB;
+    const nameA = (a.name || "").trim();
+    const nameB = (b.name || "").trim();
+    const nameComp = nameA.localeCompare(nameB);
+    if (nameComp !== 0)
+        return nameComp;
+    return (a.id || "").localeCompare(b.id || "");
+}
 function computeSiblingRanks(categories) {
     const grouped = new Map();
     for (const c of categories) {
@@ -63,7 +76,7 @@ function computeSiblingRanks(categories) {
     }
     const result = new Map();
     for (const [, list] of grouped.entries()) {
-        list.sort((a, b) => a.rank - b.rank);
+        list.sort(compareCategories);
         list.forEach((item, index) => {
             const rankNum = index + 1;
             result.set(item.id, {
@@ -188,37 +201,44 @@ function computeBranchColors(categories) {
 }
 /**
  * Swaps sibling ranking (up or down). Modifies rank property among siblings
- * and returns a new categories array ready for preview and commit.
+ * and returns a new categories array ready for preview and commit, along with
+ * explicit contiguous moves for all siblings in the group.
  */
 function moveSiblingRank(categories, targetId, direction) {
     const target = categories.find((c) => c.id === targetId);
     if (!target)
-        return categories;
+        return { nextCategories: categories, siblingMoves: [] };
     const parentId = target.parent_category_id || null;
     const siblings = categories
         .filter((c) => (c.parent_category_id || null) === parentId)
-        .sort((a, b) => a.rank - b.rank);
+        .sort(compareCategories);
     const currentIndex = siblings.findIndex((s) => s.id === targetId);
     if (currentIndex === -1)
-        return categories;
+        return { nextCategories: categories, siblingMoves: [] };
     const targetIndex = direction === "up" ? currentIndex - 1 : currentIndex + 1;
     if (targetIndex < 0 || targetIndex >= siblings.length)
-        return categories;
-    const adjacent = siblings[targetIndex];
-    // Normalize ranks if they are identical or uninitialized
+        return { nextCategories: categories, siblingMoves: [] };
+    // Swap target and adjacent within ordered sibling list
+    const reordered = [...siblings];
+    const temp = reordered[currentIndex];
+    reordered[currentIndex] = reordered[targetIndex];
+    reordered[targetIndex] = temp;
+    // Normalize contiguous ranks: 0, 1, 2, 3...
     const updatedRanks = new Map();
-    siblings.forEach((s, idx) => {
-        updatedRanks.set(s.id, idx * 10);
+    const siblingMoves = [];
+    reordered.forEach((s, idx) => {
+        updatedRanks.set(s.id, idx);
+        siblingMoves.push({
+            id: s.id,
+            parent_category_id: parentId,
+            rank: idx,
+        });
     });
-    // Swap target and adjacent
-    const targetNewRank = targetIndex * 10;
-    const adjacentNewRank = currentIndex * 10;
-    updatedRanks.set(target.id, targetNewRank);
-    updatedRanks.set(adjacent.id, adjacentNewRank);
-    return categories.map((c) => {
+    const nextCategories = categories.map((c) => {
         if (updatedRanks.has(c.id)) {
             return { ...c, rank: updatedRanks.get(c.id) };
         }
         return c;
     });
+    return { nextCategories, siblingMoves };
 }

package/.medusa/server/src/api/admin/category-tree/reorder/route.js

@@ -10,10 +10,10 @@ const POST = async (req, res) => {
     }
     const { moves } = parsed.data;
     const productModule = req.scope.resolve(utils_1.Modules.PRODUCT);
-    const existing = await productModule.listProductCategories({}, { select: ["id", "parent_category_id", "rank"], take: null });
+    const existing = await productModule.listProductCategories({}, { select: ["id", "parent_category_id", "rank", "metadata"], take: null });
     const existingMap = new Map(existing.map((c) => [
         c.id,
-        { parent_category_id: c.parent_category_id, rank: c.rank },
+        { parent_category_id: c.parent_category_id, rank: c.rank, metadata: c.metadata },
     ]));
     const simulatedParents = new Map();
     for (const [id, data] of existingMap.entries()) {
@@ -44,9 +44,15 @@ const POST = async (req, res) => {
     const applied = [];
     try {
         for (const m of moves) {
+            const prevMeta = existingMap.get(m.id)?.metadata || {};
             await productModule.updateProductCategories(m.id, {
                 parent_category_id: m.parent_category_id,
                 rank: m.rank,
+                metadata: {
+                    ...prevMeta,
+                    rank: m.rank,
+                    sibling_rank: m.rank + 1,
+                },
             });
             applied.push(m.id);
         }

package/.medusa/server/src/api/admin/category-tree/route.js

@@ -59,6 +59,19 @@ const GET = async (req, res) => {
         });
         categories = catDataFallback || [];
     }
+    // Enforce universal deterministic sorting (rank ASC, name ASC, id ASC)
+    categories.sort((a, b) => {
+        const rankA = typeof a.rank === "number" ? a.rank : 9999;
+        const rankB = typeof b.rank === "number" ? b.rank : 9999;
+        if (rankA !== rankB)
+            return rankA - rankB;
+        const nameA = (a.name || "").trim();
+        const nameB = (b.name || "").trim();
+        const nameComp = nameA.localeCompare(nameB);
+        if (nameComp !== 0)
+            return nameComp;
+        return (a.id || "").localeCompare(b.id || "");
+    });
     const allChannelIds = salesChannels.map((sc) => sc.id);
     const enriched = categories.map((cat) => {
         const images = Array.isArray(cat.product_category_image)
@@ -79,7 +92,7 @@ const GET = async (req, res) => {
             id: cat.id,
             name: cat.name,
             handle: cat.handle,
-            description: cat.description || null,
+            description: cat.description || cat.metadata?.description || null,
             parent_category_id: cat.parent_category_id || null,
             rank: typeof cat.rank === "number" ? cat.rank : 0,
             is_active: Boolean(cat.is_active),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hectasquare/medusa-plugin-category-tree",
-  "version": "1.0.12",
+  "version": "1.0.13",
   "description": "AAA Interactive Category Tree & Mind Map for Medusa v2 Admin with drag-and-drop reparenting, tier indicators, superscript ranks, multi-storefront filtering, and NotebookLM-style subtree collapse.",
   "author": "HectaSquare Team",
   "license": "Apache-2.0",

package/src/admin/components/category-tree/category-tree-canvas.tsx

@@ -149,11 +149,47 @@ const CanvasInner: React.FC = () => {
   }, [selectedNodeIds])
 
   const handleMoveSiblingUp = useCallback((id: string) => {
-    setCategories((prev) => moveSiblingRank(prev, id, "up"))
+    setCategories((prev) => {
+      const { nextCategories, siblingMoves } = moveSiblingRank(prev, id, "up")
+      if (siblingMoves.length > 0) {
+        // AAA Realtime: Immediately auto-persist contiguous ranks to backend in background
+        sdk.client
+          .fetch("/admin/category-tree/reorder", {
+            method: "POST",
+            body: { moves: siblingMoves },
+          })
+          .then(() => {
+            setOriginalCategories([...nextCategories])
+          })
+          .catch((err: any) => {
+            console.error("Failed to auto-save sibling rank:", err)
+            toast.error("Failed to save ranking: " + (err.message || "Unknown error"))
+          })
+      }
+      return nextCategories
+    })
   }, [])
 
   const handleMoveSiblingDown = useCallback((id: string) => {
-    setCategories((prev) => moveSiblingRank(prev, id, "down"))
+    setCategories((prev) => {
+      const { nextCategories, siblingMoves } = moveSiblingRank(prev, id, "down")
+      if (siblingMoves.length > 0) {
+        // AAA Realtime: Immediately auto-persist contiguous ranks to backend in background
+        sdk.client
+          .fetch("/admin/category-tree/reorder", {
+            method: "POST",
+            body: { moves: siblingMoves },
+          })
+          .then(() => {
+            setOriginalCategories([...nextCategories])
+          })
+          .catch((err: any) => {
+            console.error("Failed to auto-save sibling rank:", err)
+            toast.error("Failed to save ranking: " + (err.message || "Unknown error"))
+          })
+      }
+      return nextCategories
+    })
   }, [])
 
   const handleAddChild = useCallback((parent: CategoryTreeNode) => {
@@ -478,6 +514,7 @@ const CanvasInner: React.FC = () => {
         category={editingCategory}
         salesChannels={salesChannels}
         onSuccess={(updatedCat) => {
+          setEditingCategory(updatedCat)
           setCategories((prev) =>
             prev.map((c) => (c.id === updatedCat.id ? updatedCat : c))
           )

package/src/admin/components/category-tree/edit-category-drawer.tsx

@@ -76,7 +76,7 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
     if (category) {
       setName(category.name || "")
       setHandle(category.handle || "")
-      setDescription(category.description || "")
+      setDescription(category.description || (category.metadata as any)?.description || "")
       setImageUrl(category.image_url || "")
       setRank(category.rank ?? 0)
       setIsActive(Boolean(category.is_active))
@@ -411,8 +411,13 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
     }
   }
 
-  const handleSubmit = async (e?: React.FormEvent) => {
-    if (e && e.preventDefault) e.preventDefault()
+  const handleSubmit = async (eOrClose?: React.FormEvent | boolean, closeAfter: boolean = false) => {
+    let shouldClose = closeAfter
+    if (typeof eOrClose === "boolean") {
+      shouldClose = eOrClose
+    } else if (eOrClose && (eOrClose as any).preventDefault) {
+      (eOrClose as any).preventDefault()
+    }
     if (!name.trim()) {
       toast.error("Category name is required")
       return
@@ -429,8 +434,11 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
         (categoryImages.length > 1 ? categoryImages.find((img) => img.url !== thumbImg?.url) : null) ||
         null
 
+      const descValue = description.trim()
+
       const updatedMetadata: Record<string, any> = {
         ...(currentMetadata || {}),
+        description: descValue || null,
         sales_channels: selectedChannels,
         youtube_urls: youtubeUrls,
         youtube_url: youtubeUrls[0] || null,
@@ -446,7 +454,7 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
       await sdk.admin.productCategory.update(category.id, {
         name: name.trim(),
         handle: handle.trim() || undefined,
-        description: description.trim() || undefined,
+        description: descValue ? descValue : null,
         rank: Number(rank) || 0,
         is_active: isActive,
         is_internal: isInternal,
@@ -457,7 +465,7 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
         ...category,
         name: name.trim(),
         handle: handle.trim(),
-        description: description.trim() || null,
+        description: descValue ? descValue : null,
         image_url: thumbImg ? thumbImg.url : "",
         rank: Number(rank) || 0,
         sales_channels: selectedChannels,
@@ -468,7 +476,9 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
 
       toast.success("Category updated successfully")
       onSuccess(updated)
-      onOpenChange(false)
+      if (shouldClose) {
+        onOpenChange(false)
+      }
     } catch (err: any) {
       toast.error(err?.message || "Failed to update category")
     } finally {
@@ -848,7 +858,7 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
                               <img
                                 src={img.url}
                                 alt="Category Media"
-                                className="w-full h-full object-cover"
+                                className="w-full h-full object-contain p-1.5"
                               />
 
                               {isThumbnail && (
@@ -1036,7 +1046,13 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
               type="button"
               variant="secondary"
               size="small"
-              onClick={() => onOpenChange(false)}
+              onClick={() => {
+                if (name.trim()) {
+                  handleSubmit(true)
+                } else {
+                  onOpenChange(false)
+                }
+              }}
               disabled={isSubmitting || isDeleting}
             >
               Close
@@ -1044,7 +1060,7 @@ export const EditCategoryDrawer: React.FC<EditCategoryDrawerProps> = ({
             <Button
               type="button"
               size="small"
-              onClick={() => handleSubmit()}
+              onClick={() => handleSubmit(false)}
               isLoading={isSubmitting}
               disabled={isSubmitting || !name.trim() || isDeleting}
             >

package/src/admin/components/category-tree/lib/layout-engine.ts

@@ -1,4 +1,5 @@
 import { Node, Edge, Position } from "@xyflow/react"
+import { compareCategories } from "./tree-state"
 
 export const CARD_WIDTH = 270
 export const CARD_HEIGHT = 86
@@ -54,19 +55,19 @@ export function computeTreeLayout(
   })
 
   // Identify roots (nodes with no incoming edge in the visible graph)
-  const rootNodes = nodes.filter((n) => !parentMap.has(n.id))
-
-  // Sort children by their category rank
-  const getRank = (id: string): number => {
-    const raw = (nodeMap.get(id)?.data as any)?.category?.rank
-    return typeof raw === "number" ? raw : 0
-  }
+  const rootNodes = nodes.filter((n) => !parentMap.has(n.id)).sort((a, b) => {
+    const catA = (a.data as any)?.category || { id: a.id }
+    const catB = (b.data as any)?.category || { id: b.id }
+    return compareCategories(catA, catB)
+  })
 
   function buildTree(id: string, depth: number): TreeLayoutNode {
     const rawNode = nodeMap.get(id)!
-    const childIds = (childrenMap.get(id) || []).sort(
-      (a, b) => getRank(a) - getRank(b) || a.localeCompare(b)
-    )
+    const childIds = (childrenMap.get(id) || []).sort((aId, bId) => {
+      const catA = (nodeMap.get(aId)?.data as any)?.category || { id: aId }
+      const catB = (nodeMap.get(bId)?.data as any)?.category || { id: bId }
+      return compareCategories(catA, catB)
+    })
 
     const children = childIds.map((childId) => buildTree(childId, depth + 1))
 
@@ -129,8 +130,6 @@ export function computeTreeLayout(
     treeNode.primaryCoord = centerOfChildren
   }
 
-  // Sort roots by their rank
-  rootNodes.sort((a, b) => getRank(a.id) - getRank(b.id) || a.id.localeCompare(b.id))
 
   const positionedNodes: Node[] = []
   let globalOffset = 0

package/src/admin/components/category-tree/lib/tree-state.ts

@@ -52,6 +52,20 @@ export function computeTiers(
   return tierMap
 }
 
+export function compareCategories(
+  a: { rank?: number; name?: string; id?: string },
+  b: { rank?: number; name?: string; id?: string }
+): number {
+  const rankA = typeof a.rank === "number" ? a.rank : 9999
+  const rankB = typeof b.rank === "number" ? b.rank : 9999
+  if (rankA !== rankB) return rankA - rankB
+  const nameA = (a.name || "").trim()
+  const nameB = (b.name || "").trim()
+  const nameComp = nameA.localeCompare(nameB)
+  if (nameComp !== 0) return nameComp
+  return (a.id || "").localeCompare(b.id || "")
+}
+
 export function computeSiblingRanks(
   categories: CategoryTreeNode[]
 ): Map<string, { rankNum: number; superscript: string }> {
@@ -67,7 +81,7 @@ export function computeSiblingRanks(
   const result = new Map<string, { rankNum: number; superscript: string }>()
 
   for (const [, list] of grouped.entries()) {
-    list.sort((a, b) => a.rank - b.rank)
+    list.sort(compareCategories)
     list.forEach((item, index) => {
       const rankNum = index + 1
       result.set(item.id, {
@@ -236,44 +250,56 @@ export function computeBranchColors(
 
 /**
  * Swaps sibling ranking (up or down). Modifies rank property among siblings
- * and returns a new categories array ready for preview and commit.
+ * and returns a new categories array ready for preview and commit, along with
+ * explicit contiguous moves for all siblings in the group.
  */
 export function moveSiblingRank(
   categories: CategoryTreeNode[],
   targetId: string,
   direction: "up" | "down"
-): CategoryTreeNode[] {
+): {
+  nextCategories: CategoryTreeNode[]
+  siblingMoves: Array<{ id: string; parent_category_id: string | null; rank: number }>
+} {
   const target = categories.find((c) => c.id === targetId)
-  if (!target) return categories
+  if (!target) return { nextCategories: categories, siblingMoves: [] }
 
   const parentId = target.parent_category_id || null
   const siblings = categories
     .filter((c) => (c.parent_category_id || null) === parentId)
-    .sort((a, b) => a.rank - b.rank)
+    .sort(compareCategories)
 
   const currentIndex = siblings.findIndex((s) => s.id === targetId)
-  if (currentIndex === -1) return categories
+  if (currentIndex === -1) return { nextCategories: categories, siblingMoves: [] }
 
   const targetIndex = direction === "up" ? currentIndex - 1 : currentIndex + 1
-  if (targetIndex < 0 || targetIndex >= siblings.length) return categories
+  if (targetIndex < 0 || targetIndex >= siblings.length) return { nextCategories: categories, siblingMoves: [] }
+
+  // Swap target and adjacent within ordered sibling list
+  const reordered = [...siblings]
+  const temp = reordered[currentIndex]
+  reordered[currentIndex] = reordered[targetIndex]
+  reordered[targetIndex] = temp
 
-  const adjacent = siblings[targetIndex]
-  // Normalize ranks if they are identical or uninitialized
+  // Normalize contiguous ranks: 0, 1, 2, 3...
   const updatedRanks = new Map<string, number>()
-  siblings.forEach((s, idx) => {
-    updatedRanks.set(s.id, idx * 10)
+  const siblingMoves: Array<{ id: string; parent_category_id: string | null; rank: number }> = []
+
+  reordered.forEach((s, idx) => {
+    updatedRanks.set(s.id, idx)
+    siblingMoves.push({
+      id: s.id,
+      parent_category_id: parentId,
+      rank: idx,
+    })
   })
 
-  // Swap target and adjacent
-  const targetNewRank = targetIndex * 10
-  const adjacentNewRank = currentIndex * 10
-  updatedRanks.set(target.id, targetNewRank)
-  updatedRanks.set(adjacent.id, adjacentNewRank)
-
-  return categories.map((c) => {
+  const nextCategories = categories.map((c) => {
     if (updatedRanks.has(c.id)) {
       return { ...c, rank: updatedRanks.get(c.id)! }
     }
     return c
   })
+
+  return { nextCategories, siblingMoves }
 }

package/src/api/admin/category-tree/reorder/route.ts

@@ -22,15 +22,15 @@ export const POST = async (
 
   const existing = await productModule.listProductCategories(
     {},
-    { select: ["id", "parent_category_id", "rank"], take: null }
+    { select: ["id", "parent_category_id", "rank", "metadata"], take: null }
   )
   const existingMap = new Map<
     string,
-    { parent_category_id: string | null; rank: number }
+    { parent_category_id: string | null; rank: number; metadata?: any }
   >(
     existing.map((c: any) => [
       c.id,
-      { parent_category_id: c.parent_category_id, rank: c.rank },
+      { parent_category_id: c.parent_category_id, rank: c.rank, metadata: c.metadata },
     ])
   )
 
@@ -78,9 +78,15 @@ export const POST = async (
   const applied: string[] = []
   try {
     for (const m of moves) {
+      const prevMeta = existingMap.get(m.id)?.metadata || {}
       await productModule.updateProductCategories(m.id, {
         parent_category_id: m.parent_category_id,
         rank: m.rank,
+        metadata: {
+          ...prevMeta,
+          rank: m.rank,
+          sibling_rank: m.rank + 1,
+        },
       })
       applied.push(m.id)
     }

package/src/api/admin/category-tree/route.ts

@@ -65,6 +65,18 @@ export const GET = async (
     categories = (catDataFallback as any[]) || []
   }
 
+  // Enforce universal deterministic sorting (rank ASC, name ASC, id ASC)
+  categories.sort((a, b) => {
+    const rankA = typeof a.rank === "number" ? a.rank : 9999
+    const rankB = typeof b.rank === "number" ? b.rank : 9999
+    if (rankA !== rankB) return rankA - rankB
+    const nameA = (a.name || "").trim()
+    const nameB = (b.name || "").trim()
+    const nameComp = nameA.localeCompare(nameB)
+    if (nameComp !== 0) return nameComp
+    return (a.id || "").localeCompare(b.id || "")
+  })
+
   const allChannelIds = salesChannels.map((sc) => sc.id)
 
   const enriched = categories.map((cat) => {
@@ -96,7 +108,7 @@ export const GET = async (
       id: cat.id,
       name: cat.name,
       handle: cat.handle,
-      description: cat.description || null,
+      description: cat.description || cat.metadata?.description || null,
       parent_category_id: cat.parent_category_id || null,
       rank: typeof cat.rank === "number" ? cat.rank : 0,
       is_active: Boolean(cat.is_active),