Category tree

Name: Category tree
Author: Hectasquare

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.

npm install @hectasquare/medusa-plugin-category-tree

Категория

Другое

Создано

Hectasquare

Версия

1.0.16

Последнее обновление

1 день назад

Ежемесячные загрузки

Звезды на Github

NPM Github

@hectasquare/medusa-plugin-category-tree

An enterprise-grade, AAA interactive Category Tree, Mind Map & Category Detail Hub plugin for Medusa v2 Admin.

Inspired by modern visual and canvas tools like Figma, Miro, Linear, and NotebookLM, this plugin transforms Medusa's standard nested category list into a fluid, 60fps pan/zoom node canvas with branch-specific harmonic color coding, left-edge tier level indicators, sibling superscript rankings, and an all-in-one Category Detail Hub with product ranking and commercial top seller management.

🌟 Why This Plugin?

In high-volume e-commerce stores with hundreds or thousands of categories across multiple sales channels and brands:

Standard nested tables and indent lists quickly become unwieldy, difficult to scan, and prone to navigation fatigue.
Re-parenting or reordering categories through repeated modal dropdowns is slow, error-prone, and provides no immediate visual feedback.
Managing products, rankings, and commercial visibility required constantly hopping back and forth between administrative screens.

With this plugin:

Zero backend contamination: Lives entirely inside an external npm plugin (). Your backend core remains pristine.
Bird’s-eye hierarchy visualization: Instant visual comprehension of your entire category taxonomy with orthogonal connections () and branch-specific harmonic colors.
Hierarchical Centered Layout: Clean Buchheim/Walker-style tree geometry centering parents directly over children without cross-canvas wire tangle.
Interactive drag-and-drop reparenting: Connect and restructure categories directly on the canvas with real-time topological cycle protection.
Category Detail Hub: Complete 4-tab slide-over hub replacing the need to visit legacy pages—edit metadata, manage products, rank items, and configure storefronts in one place.
Product Ranking & Top Commercial Sellers: Reorder sibling products directly with interactive controls and star items with status reflected in storefronts.
Multi-storefront filtering: Seamlessly filter the entire tree by Sales Channel (, , , etc.).
Atomic batch updates: Stage moves visually on canvas and commit them in a single transactional request with automatic rollback.

🚀 Key Features

🗂️ All-in-One Category Detail Hub

Clicking the edit pencil icon on any node opens a wide slide-over hub featuring 4 dedicated workspaces:

General & Ranking:
- Title, Handle, Description, and Active / Internal toggles.
- Sibling category rank ordering (, , ).
- Direct link opening in a separate tab when desired.
Products Management:
- Full product listing with thumbnail, title, collection, variant count, and status badges.
- Sibling Product Ranking: Dynamic rank numbering (, , ...) with interactive Move Up and Move Down buttons.
- ⭐ Top Commercial Seller: One-click toggle marking priority commercial showcase products.
- Remove Products: Individual removal or multi-select bulk remove.
- Full-Screen FocusModal: Direct parity with Medusa's legacy Add Products modal with full-width table, search (), pagination, and batch assignment.
Storefronts & Media:
- Multi-sales channel visibility checkboxes (, , etc.).
- Native Drag-and-Drop Media Upload: Integrated with Medusa v2's native File Module ().
- Visual Gallery Manager: Image preview cards, delete actions, and one-click designation.
- Direct External URL Input: Fallback support for external CDN, Cloudinary, or DAM image links.
YouTube Videos:
- Multi-video demonstration manager with real-time thumbnail preview cards and quick remove actions.

🎨 Branch-Specific Harmonic Color Coding

Every major branch receives a distinct harmonic color (Emerald, Indigo, Amber, Rose, Cyan, Violet, Pink, Lime, Sky, Orange) assigned deterministically from its top-level root ancestor.
Vertical left-edge tier indicator bars and connecting orthogonal edge lines inherit the branch color, making complex multi-level trees effortless to scan visually.

🌳 Dual-Mode Visual Layout Engine

Vertical Tree (Top-to-Bottom): Clustered hierarchical layout centering parents cleanly over children.
Horizontal Mind Map (Left-to-Right): Lateral branching layout (Linear/Miro style) ideal for wide root catalogs.
Recalculates dynamically with sub-millisecond responsiveness.

⛶ Box / Marquee Multi-Selection

Click and drag anywhere on the canvas to marquee-select multiple nodes at once ().
Move entire subtrees or selected clusters in unison.

🏷️ Left-Edge Tier Level Indicators & Superscript Ranks

Tier 1 (Root): Single vertical bar in branch accent.
Tier 2 (Sub): Dual vertical bars with high-contrast spacing.
Tier 3 (Sub-Sub): Triple vertical bars.
Sibling Superscripts: Numbers (, , , , ) representing the category's display rank among siblings.

📂 NotebookLM-Style Subtree Collapse

Expand or collapse individual subtrees with a single click.
Collapsed nodes show an indicator badge (e.g., ).
Quick actions in the floating dock to expand or collapse all nodes or selective subtrees.

🛡️ Topological Cycle Protection

Real-time client-side and server-side cycle detection.
Completely prevents accidental self-parenting () or cyclic loops ().

📦 Installation

Install the package in your Medusa backend project:

⚙️ Configuration

When you start your Medusa backend ( or ), the plugin automatically injects:

Admin UI Page & Sidebar Item: Registered under with a folder tree icon.
Backend API Endpoints: Under supporting atomic reorders, rank shifts, and category creations.

🛒 Storefront Integration (Product Ranking & Top Sellers)

The plugin persists category-scoped ranking and top seller configuration into :

Storefront 2 Priority Showcase Example

In your storefront API or data layer (e.g. Next.js App Router):

☁️ Media Upload & Storage Provider Compatibility

The plugin's Category Detail Hub features a unified media uploader and gallery manager. To ensure zero vendor lock-in, file handling is 100% storage-provider agnostic:

Native Medusa File Module Pipeline:
- Uploads execute via Medusa v2's native SDK (), routing directly to .
- Your backend delegates the upload to whichever File Module Provider is configured in and returns the CDN URL.
Direct External URL / CDN Fallback:
- If your assets are hosted on an external DAM, Cloudinary, Imgix, or third-party S3 bucket, you can simply paste the image URL directly into the uploader and click Add.

💡 Category Media in Medusa v2: Native vs. Plugin Architecture

In core Medusa v2, products have native media tables (), but does not have a native images relationship out of the box.

To solve this universally without imposing mandatory database migrations on standard Medusa stores, this plugin employs an adaptive hybrid architecture:

Universal Metadata Mode (Zero Config / Out of the Box):
- Stores all gallery assets and active thumbnail directly inside Medusa's native :
- Zero backend code or database migrations required. Any standard Medusa v2 installation supports this immediately.
Custom Backend Module Mode (Optional Extended Architecture):
- If your backend has extended the Medusa framework with a custom Category Media module (e.g., custom DML model exposing ), the plugin detects this endpoint and automatically synchronizes both the custom relation and metadata!

Configuring S3-Compatible Storage in Medusa v2

Because Medusa abstracts storage through , you can seamlessly route category media to AWS S3, Cloudflare R2, MinIO, or DigitalOcean Spaces by adjusting :

AWS S3

Cloudflare R2

MinIO (Self-Hosted S3)

DigitalOcean Spaces

🏗️ Architecture & Project Structure

🛠️ Development & Building

To build the plugin for distribution:

This compiles TypeScript definitions and JavaScript bundles into .

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to open an issue or pull request on our repository.

📄 License

Apache License 2.0 © HectaSquare Team

Еще в этой категории

Посмотреть все

Другое

Gati

От Devx Commerce

Синхронизируйте Medusa с Gati ERP

Другое

Product Reviews

От Lambda Curry

Добавляйте рейтинги, отзывы и модерацию товаров

Другое

Variant Images

От Betanoir

Организуйте и загружайте варианты изображений в Medusa

Плагины

Category tree

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.

npm install @hectasquare/medusa-plugin-category-tree

Категория

Другое

Создано

Hectasquare

Версия

1.0.16

Последнее обновление

1 день назад

Ежемесячные загрузки

Звезды на Github

NPM Github

@hectasquare/medusa-plugin-category-tree

An enterprise-grade, AAA interactive Category Tree, Mind Map & Category Detail Hub plugin for Medusa v2 Admin.

🌟 Why This Plugin?

In high-volume e-commerce stores with hundreds or thousands of categories across multiple sales channels and brands:

Standard nested tables and indent lists quickly become unwieldy, difficult to scan, and prone to navigation fatigue.
Re-parenting or reordering categories through repeated modal dropdowns is slow, error-prone, and provides no immediate visual feedback.
Managing products, rankings, and commercial visibility required constantly hopping back and forth between administrative screens.

With this plugin:

Zero backend contamination: Lives entirely inside an external npm plugin (). Your backend core remains pristine.
Bird’s-eye hierarchy visualization: Instant visual comprehension of your entire category taxonomy with orthogonal connections () and branch-specific harmonic colors.
Hierarchical Centered Layout: Clean Buchheim/Walker-style tree geometry centering parents directly over children without cross-canvas wire tangle.
Interactive drag-and-drop reparenting: Connect and restructure categories directly on the canvas with real-time topological cycle protection.
Category Detail Hub: Complete 4-tab slide-over hub replacing the need to visit legacy pages—edit metadata, manage products, rank items, and configure storefronts in one place.
Product Ranking & Top Commercial Sellers: Reorder sibling products directly with interactive controls and star items with status reflected in storefronts.
Multi-storefront filtering: Seamlessly filter the entire tree by Sales Channel (, , , etc.).
Atomic batch updates: Stage moves visually on canvas and commit them in a single transactional request with automatic rollback.

🚀 Key Features

🗂️ All-in-One Category Detail Hub

Clicking the edit pencil icon on any node opens a wide slide-over hub featuring 4 dedicated workspaces:

General & Ranking:
- Title, Handle, Description, and Active / Internal toggles.
- Sibling category rank ordering (, , ).
- Direct link opening in a separate tab when desired.
Products Management:
- Full product listing with thumbnail, title, collection, variant count, and status badges.
- Sibling Product Ranking: Dynamic rank numbering (, , ...) with interactive Move Up and Move Down buttons.
- ⭐ Top Commercial Seller: One-click toggle marking priority commercial showcase products.
- Remove Products: Individual removal or multi-select bulk remove.
- Full-Screen FocusModal: Direct parity with Medusa's legacy Add Products modal with full-width table, search (), pagination, and batch assignment.
Storefronts & Media:
- Multi-sales channel visibility checkboxes (, , etc.).
- Native Drag-and-Drop Media Upload: Integrated with Medusa v2's native File Module ().
- Visual Gallery Manager: Image preview cards, delete actions, and one-click designation.
- Direct External URL Input: Fallback support for external CDN, Cloudinary, or DAM image links.
YouTube Videos:
- Multi-video demonstration manager with real-time thumbnail preview cards and quick remove actions.

🎨 Branch-Specific Harmonic Color Coding

Every major branch receives a distinct harmonic color (Emerald, Indigo, Amber, Rose, Cyan, Violet, Pink, Lime, Sky, Orange) assigned deterministically from its top-level root ancestor.
Vertical left-edge tier indicator bars and connecting orthogonal edge lines inherit the branch color, making complex multi-level trees effortless to scan visually.

🌳 Dual-Mode Visual Layout Engine

Vertical Tree (Top-to-Bottom): Clustered hierarchical layout centering parents cleanly over children.
Horizontal Mind Map (Left-to-Right): Lateral branching layout (Linear/Miro style) ideal for wide root catalogs.
Recalculates dynamically with sub-millisecond responsiveness.

⛶ Box / Marquee Multi-Selection

Click and drag anywhere on the canvas to marquee-select multiple nodes at once ().
Move entire subtrees or selected clusters in unison.

🏷️ Left-Edge Tier Level Indicators & Superscript Ranks

Tier 1 (Root): Single vertical bar in branch accent.
Tier 2 (Sub): Dual vertical bars with high-contrast spacing.
Tier 3 (Sub-Sub): Triple vertical bars.
Sibling Superscripts: Numbers (, , , , ) representing the category's display rank among siblings.

📂 NotebookLM-Style Subtree Collapse

Expand or collapse individual subtrees with a single click.
Collapsed nodes show an indicator badge (e.g., ).
Quick actions in the floating dock to expand or collapse all nodes or selective subtrees.

🛡️ Topological Cycle Protection

Real-time client-side and server-side cycle detection.
Completely prevents accidental self-parenting () or cyclic loops ().

📦 Installation

Install the package in your Medusa backend project:

1npm install @hectasquare/medusa-plugin-category-tree
2# or
3pnpm add @hectasquare/medusa-plugin-category-tree
4# or
5yarn add @hectasquare/medusa-plugin-category-tree

⚙️ Configuration

1module.exports = defineConfig({
plugins: [
  {
    resolve: "@hectasquare/medusa-plugin-category-tree",
    options: {},
  },
],
8})

When you start your Medusa backend ( or ), the plugin automatically injects:

Admin UI Page & Sidebar Item: Registered under with a folder tree icon.
Backend API Endpoints: Under supporting atomic reorders, rank shifts, and category creations.

🛒 Storefront Integration (Product Ranking & Top Sellers)

The plugin persists category-scoped ranking and top seller configuration into :

Storefront 2 Priority Showcase Example

In your storefront API or data layer (e.g. Next.js App Router):

1// Inspect category metadata for top commercial sellers
2const topSellerIds = category.metadata?.top_sellers || []
3
4if (topSellerIds.length > 0) {
5  // Fetch top seller products and place them first in designated order
6  const { products: topProducts } = await getProductsList({
7    queryParams: { id: topSellerIds },
8  })
9  topProducts.sort((a, b) => topSellerIds.indexOf(a.id) - topSellerIds.indexOf(b.id))
10  
11  // Fill remaining slots from the general category pool without duplicates
12  return [...topProducts, ...otherCategoryProducts]
13}

☁️ Media Upload & Storage Provider Compatibility

The plugin's Category Detail Hub features a unified media uploader and gallery manager. To ensure zero vendor lock-in, file handling is 100% storage-provider agnostic:

Native Medusa File Module Pipeline:
- Uploads execute via Medusa v2's native SDK (), routing directly to .
- Your backend delegates the upload to whichever File Module Provider is configured in and returns the CDN URL.
Direct External URL / CDN Fallback:
- If your assets are hosted on an external DAM, Cloudinary, Imgix, or third-party S3 bucket, you can simply paste the image URL directly into the uploader and click Add.

💡 Category Media in Medusa v2: Native vs. Plugin Architecture

In core Medusa v2, products have native media tables (), but does not have a native images relationship out of the box.

To solve this universally without imposing mandatory database migrations on standard Medusa stores, this plugin employs an adaptive hybrid architecture:

Universal Metadata Mode (Zero Config / Out of the Box):

Stores all gallery assets and active thumbnail directly inside Medusa's native :

1{
"metadata": {
  "image_url": "https://cdn.store.com/category-thumb.webp",
  "images": [
    { "id": "img_01", "url": "https://cdn.store.com/hero.webp", "type": "thumbnail" },
    { "id": "img_02", "url": "https://cdn.store.com/banner.webp", "type": "image" }
  ]
}
9}

Zero backend code or database migrations required. Any standard Medusa v2 installation supports this immediately.

Custom Backend Module Mode (Optional Extended Architecture):
- If your backend has extended the Medusa framework with a custom Category Media module (e.g., custom DML model exposing ), the plugin detects this endpoint and automatically synchronizes both the custom relation and metadata!

Configuring S3-Compatible Storage in Medusa v2

Because Medusa abstracts storage through , you can seamlessly route category media to AWS S3, Cloudflare R2, MinIO, or DigitalOcean Spaces by adjusting :

AWS S3

1// medusa-config.js
2module.exports = defineConfig({
modules: [
  {
    resolve: "@medusajs/medusa/file",
    options: {
      providers: [
        {
          resolve: "@medusajs/medusa/file-s3",
          id: "s3",
          options: {
            file_url: process.env.MEDUSA_FILE_URL, // CDN or bucket public URL
            access_key_id: process.env.S3_ACCESS_KEY_ID,
            secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
            region: process.env.S3_REGION,
            bucket: process.env.S3_BUCKET,
          },
        },
      ],
    },
  },
],
23})

Cloudflare R2

1// medusa-config.js
2options: {
3  file_url: process.env.R2_PUBLIC_URL, // e.g. https://pub-xxxx.r2.dev or custom domain
4  access_key_id: process.env.R2_ACCESS_KEY_ID,
5  secret_access_key: process.env.R2_SECRET_ACCESS_KEY,
6  bucket: process.env.R2_BUCKET_NAME,
7  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
8  region: "auto",
9}

MinIO (Self-Hosted S3)

1// medusa-config.js
2options: {
file_url: process.env.MINIO_PUBLIC_URL, // e.g. http://localhost:9000/my-bucket
access_key_id: process.env.MINIO_ROOT_USER,
secret_access_key: process.env.MINIO_ROOT_PASSWORD,
bucket: process.env.MINIO_BUCKET,
endpoint: process.env.MINIO_ENDPOINT, // e.g. http://127.0.0.1:9000
additional_client_config: {
  forcePathStyle: true, // Required for MinIO
},
11}

DigitalOcean Spaces

1// medusa-config.js
2options: {
3  file_url: `https://${process.env.DO_SPACES_BUCKET}.${process.env.DO_SPACES_REGION}.digitaloceanspaces.com`,
4  access_key_id: process.env.DO_SPACES_KEY,
5  secret_access_key: process.env.DO_SPACES_SECRET,
6  bucket: process.env.DO_SPACES_BUCKET,
7  endpoint: `https://${process.env.DO_SPACES_REGION}.digitaloceanspaces.com`,
8  region: process.env.DO_SPACES_REGION,
9}

🏗️ Architecture & Project Structure

1medusa-plugin-category-tree/
2├── src/
3│   ├── admin/
4│   │   ├── index.tsx                         # Medusa Admin SDK registration
5│   │   ├── routes/category-tree/             # Route /app/category-tree
6│   │   └── components/category-tree/
7│   │       ├── category-tree-canvas.tsx      # Interactive canvas & marquee selection
8│   │       ├── category-node.tsx             # Node card with tier bars & ranks
9│   │       ├── custom-edge.tsx               # Orthogonal edge matching branch color
10│   │       ├── canvas-dock.tsx               # Floating glassmorphic dock
11│   │       ├── tier-bars.tsx                 # Branch-colored tier bars
12│   │       ├── edit-category-drawer.tsx      # 4-tab Category Detail Hub
13│   │       ├── category-products-manager.tsx # Products table, ranking & FocusModal
14│   │       ├── create-category-drawer.tsx    # Slide-over subcategory creator
15│   │       └── lib/
16│   │           ├── layout-engine.ts          # Buchheim/Walker centered tree engine
17│   │           └── tree-state.ts             # Palette, tiers, ranks, & cycle checks
18│   ├── api/admin/category-tree/              # Server route handlers
19│   └── workflows/                            # Atomic reorder workflows
20├── package.json
21├── tsconfig.json
22└── README.md

🛠️ Development & Building

To build the plugin for distribution:

1# In the plugin directory
2pnpm build
3# or
4npm run build

This compiles TypeScript definitions and JavaScript bundles into .

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to open an issue or pull request on our repository.

📄 License

Еще в этой категории

Посмотреть все

Другое

Gati

От Devx Commerce

Синхронизируйте Medusa с Gati ERP

Другое

Product Reviews

От Lambda Curry

Добавляйте рейтинги, отзывы и модерацию товаров

Другое

Variant Images

От Betanoir

Организуйте и загружайте варианты изображений в Medusa