medusa-dynamic-metadata 0.0.9 → 0.0.10

package/.medusa/server/src/admin/index.js

@@ -1728,17 +1728,10 @@ const UniversalMetadataWidget = ({ data, zone }) => {
     try {
       return resolveEntityType(zone, data);
     } catch (err) {
-      console.error("[UniversalMetadataWidget] Entity type resolution failed:", err);
       return void 0;
     }
   }, [zone, data]);
   if (!entityType) {
-    if (process.env.NODE_ENV !== "production") {
-      console.warn("[UniversalMetadataWidget] Could not resolve entity type.", {
-        zone,
-        dataKeys: data ? Object.keys(data) : []
-      });
-    }
     return null;
   }
   return /* @__PURE__ */ jsxRuntime.jsx(
@@ -1755,9 +1748,6 @@ const MetadataWidgetLoader = ({ data, entityType, queryKey }) => {
     entity: entityType,
     enabled: true
   });
-  if (process.env.NODE_ENV !== "production") {
-    console.debug("[UniversalMetadataWidget]", { entityType, descriptors: descriptors.length, isPending, queryKey });
-  }
   if (!isPending && descriptors.length === 0) {
     return null;
   }

package/.medusa/server/src/admin/index.mjs

@@ -1727,17 +1727,10 @@ const UniversalMetadataWidget = ({ data, zone }) => {
     try {
       return resolveEntityType(zone, data);
     } catch (err) {
-      console.error("[UniversalMetadataWidget] Entity type resolution failed:", err);
       return void 0;
     }
   }, [zone, data]);
   if (!entityType) {
-    if (process.env.NODE_ENV !== "production") {
-      console.warn("[UniversalMetadataWidget] Could not resolve entity type.", {
-        zone,
-        dataKeys: data ? Object.keys(data) : []
-      });
-    }
     return null;
   }
   return /* @__PURE__ */ jsx(
@@ -1754,9 +1747,6 @@ const MetadataWidgetLoader = ({ data, entityType, queryKey }) => {
     entity: entityType,
     enabled: true
   });
-  if (process.env.NODE_ENV !== "production") {
-    console.debug("[UniversalMetadataWidget]", { entityType, descriptors: descriptors.length, isPending, queryKey });
-  }
   if (!isPending && descriptors.length === 0) {
     return null;
   }

package/README.md

@@ -1,92 +1,45 @@
-<p align="center">
-  <a href="https://www.medusajs.com">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://user-images.githubusercontent.com/59018053/229103275-b5e482bb-4601-46e6-8142-244f531cebdb.svg">
-    <source media="(prefers-color-scheme: light)" srcset="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
-    <img alt="Medusa logo" src="https://user-images.githubusercontent.com/59018053/229103726-e5b529a3-9b3f-4970-8a1f-c6af37f087bf.svg">
-    </picture>
-  </a>
-</p>
-<h1 align="center">
-  Medusa Dynamic Metadata
-</h1>
-
-<h4 align="center">
-  <a href="https://docs.medusajs.com">Documentation</a> |
-  <a href="https://www.medusajs.com">Website</a>
-</h4>
-
-<p align="center">
-  Building blocks for digital commerce
-</p>
-<p align="center">
-  <a href="https://github.com/medusajs/medusa/blob/master/CONTRIBUTING.md">
-    <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat" alt="PRs welcome!" />
-  </a>
-    <a href="https://www.producthunt.com/posts/medusa"><img src="https://img.shields.io/badge/Product%20Hunt-%231%20Product%20of%20the%20Day-%23DA552E" alt="Product Hunt"></a>
-  <a href="https://discord.gg/xpCwq3Kfn8">
-    <img src="https://img.shields.io/badge/chat-on%20discord-7289DA.svg" alt="Discord Chat" />
-  </a>
-  <a href="https://twitter.com/intent/follow?screen_name=medusajs">
-    <img src="https://img.shields.io/twitter/follow/medusajs.svg?label=Follow%20@medusajs" alt="Follow @medusajs" />
-  </a>
-</p>
-
-## Compatibility
-
-This plugin is compatible with versions >= 2.4.0 of `@medusajs/medusa`.
-
-## Overview
-
-`medusa-dynamic-metadata` is a flexible, configuration-driven plugin that enables metadata management for any Medusa entity type. Simply configure entities in your `medusa-config.ts` file, and the plugin provides a universal widget component that automatically detects entity types and renders the appropriate metadata fields.
-
-### Key Features
-
-- **Configuration-Driven**: Enable metadata for any entity type through simple configuration
-- **Universal Widget**: Single widget component works for all entities with runtime entity detection
-- **Type-Safe**: Full TypeScript support with proper type definitions
-- **Enterprise Field Types**: 27+ field types including text, textarea, richtext, markdown, number, integer, float, bool, date/time/datetime, select/multiselect/radio/checkbox, image/video/audio/file, url/email/phone, color, json/object/array, relation
-- **Schema Validation**: Support for `required`, `default_value`, and `validation` (min, max, regex) per field
-- **Zero Code Changes**: Add metadata to new entities by updating configuration only
-
-## Supported Entities
-
-This plugin supports metadata configuration for the following entities that have valid admin detail pages:
-
-1. **products** - Widget zone: `product.details.after`
-2. **orders** - Widget zone: `order.details.after`
-3. **categories** - Widget zone: `product_category.details.after`
-4. **collections** - Widget zone: `product_collection.details.after`
-5. **customers** - Widget zone: `customer.details.after`
-6. **regions** - Widget zone: `region.details.after`
-7. **sales_channels** - Widget zone: `sales_channel.details.after`
-8. **stores** - Widget zone: `store.details.after`
-9. **promotions** - Widget zone: `promotion.details.after`
-10. **campaigns** - Widget zone: `campaign.details.after`
-11. **price_lists** - Widget zone: `price_list.details.after`
-12. **shipping_profiles** - Widget zone: `shipping_profile.details.after`
-13. **inventory_items** - Widget zone: `inventory_item.details.after`
-14. **product_variants** - Widget zone: `product_variant.details.after`
-
-> **Note**: Only entities with valid admin detail pages can be configured. The plugin includes pre-built widget files for all 14 supported entities above.
-
-## Getting Started
-
-### Installation
+# medusa-dynamic-metadata
+> Configuration-driven Medusa v2 plugin for rendering and persisting dynamic metadata fields across admin entity detail pages.
+
+## Plugin Overview
+
+`medusa-dynamic-metadata` lets you define metadata descriptors per entity in plugin options, then automatically renders a typed metadata editor in Medusa Admin widgets for those entity detail pages.
+
+### What It Does
+
+- Resolves metadata configuration from `medusa-config.ts` (`entities` map).
+- Detects entity type in admin widgets (zone first, data-shape fallback).
+- Renders a universal metadata form supporting 27 field types (`text`, `number`, `select`, `json`, `relation`, media URL/file upload, etc.).
+- Validates descriptor-driven constraints (`required`, `validation.min/max/regex`, options validation).
+- Saves metadata to entity-specific admin APIs (or custom endpoint override).
+- Provides admin API for retrieving resolved descriptors by entity.
+
+### Problem It Solves
+
+It removes the need to hand-build custom metadata UI and persistence logic per entity. Teams can add/modify metadata fields through plugin configuration instead of repeated frontend/backend boilerplate.
+
+### Medusa Version
+
+Built for **Medusa v2** (`@medusajs/framework` / `@medusajs/medusa` `2.12.3`).
+
+---
+
+## Installation & Setup
+
+### Install
 
 ```bash
 npm install medusa-dynamic-metadata
+# or
+yarn add medusa-dynamic-metadata
 ```
 
-### Configuration
-
-Add the plugin to your `medusa-config.ts`:
+### Register in `medusa-config.ts`
 
-```typescript
+```ts
 import { defineConfig } from "@medusajs/framework"
 
 export default defineConfig({
-  // ... other config
   plugins: [
     {
       resolve: "medusa-dynamic-metadata",
@@ -96,23 +49,6 @@ export default defineConfig({
             descriptors: [
               { key: "brand", label: "Brand", type: "text", filterable: true },
               { key: "warranty_years", label: "Warranty (Years)", type: "number" },
-              {
-                key: "status",
-                label: "Status",
-                type: "select",
-                options: [
-                  { value: "draft", label: "Draft" },
-                  { value: "active", label: "Active" },
-                  { value: "archived", label: "Archived" },
-                ],
-              },
-            ],
-            expose_client_helpers: true,
-            filterable: true,
-          },
-          orders: {
-            descriptors: [
-              { key: "source", label: "Source", type: "text" },
             ],
           },
         },
@@ -122,262 +58,309 @@ export default defineConfig({
 })
 ```
 
-### Widget Files
+### Database Migrations
 
-The plugin includes minimal wrapper widget files for all 14 supported entities listed above. Each wrapper:
+No custom module/entity migrations are present in this plugin source. It uses existing Medusa entity metadata columns and admin endpoints.
 
-1. Specifies the widget zone (required by Medusa's widget system)
-2. Delegates to the universal `UniversalMetadataWidget` component
-3. Automatically detects the entity type at runtime
+---
 
-**Note:** If an entity is not configured in your `medusa-config.ts`, the admin hook will treat that as "no descriptors" and the widget will not render for that entity (no error is shown). This prevents widgets from appearing for entities you don't intend to manage metadata for, such as `regions`.
+## Configuration (`config.ts` / plugin options)
 
-**For entities not in the supported list**: Only entities with valid admin detail pages can have metadata widgets. If you need to add support for a new entity that has a detail page in Medusa's admin, create a minimal wrapper widget file using the template in `src/admin/widget-templates/generic-metadata-widget.template.tsx` (copy it into `src/admin/widgets/`; do not leave the template inside `widgets/` or it will register as a duplicate widget).
+Defined in `src/config/metadata-options.ts`.
 
-### Building the Plugin
+### Root Options
 
-```bash
-npm run build
-```
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `entities` | `Record<string, EntityMetadataConfig>` | Optional | `{}` | Per-entity metadata configuration keyed by entity type (for example `products`, `orders`). |
 
-This builds the plugin with all extensions.
+### Entity Metadata Config
 
-### Development
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `descriptors` | `MetadataDescriptor[]` | Optional | `[]` | Field definitions to render and persist. |
+| `expose_client_helpers` | `boolean` | Optional | `false` | Flag stored in normalized config (helper exposure toggle). |
+| `filterable` | `boolean` | Optional | `false` | Entity-level filterability flag in config. |
+| `widget_zone` | `string` | Optional | Auto-resolved from entity mapping or `{singular}.details.after` | Admin widget zone override. |
+| `api_endpoint` | `string` | Optional | Derived from entity registry | Admin update endpoint override for saving metadata. |
 
-```bash
-npm run dev
-```
+### Metadata Descriptor Fields
 
-This runs the plugin in watch mode for development.
+| Field | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `key` | `string` | Yes | - | Metadata key on entity. |
+| `type` | `MetadataFieldType` | Yes | - | Input type and coercion/validation behavior. |
+| `label` | `string` | Optional | `key` | Display label. |
+| `filterable` | `boolean` | Optional | `false` | Per-field filterable marker. |
+| `required` | `boolean` | Optional | `false` | Required validation. |
+| `default_value` | `unknown` | Optional | `undefined` | Default form value when metadata is missing. |
+| `validation` | `{ min?: number; max?: number; regex?: string }` | Optional | `undefined` | Numeric/regex constraints. |
+| `options` | `{ value: string; label?: string }[]` | Optional | `undefined` | Used for `select`, `multiselect`, `radio`, `checkbox`. |
 
-## How It Works
+### Supported `MetadataFieldType` Values
 
-### Architecture Flow
+`text`, `textarea`, `richtext`, `markdown`, `number`, `integer`, `float`, `bool`, `date`, `time`, `datetime`, `select`, `multiselect`, `radio`, `checkbox`, `image`, `video`, `audio`, `file`, `url`, `email`, `phone`, `color`, `json`, `object`, `array`, `relation`
 
-```
-Configuration (medusa-config.ts)
-    ↓
-Plugin Initialization
-    ↓
-Widget Files (minimal wrappers with zones)
-    ↓
-UniversalMetadataWidget (runtime entity detection)
-    ↓
-MetadataTableWidget (UI component)
-    ↓
-API Endpoints (save/load metadata)
+### Complete Example Config
+
+```ts
+{
+  resolve: "medusa-dynamic-metadata",
+  options: {
+    entities: {
+      products: {
+        descriptors: [
+          { key: "brand", label: "Brand", type: "text", filterable: true, required: true },
+          { key: "warranty_years", label: "Warranty (Years)", type: "integer", validation: { min: 0, max: 20 } },
+          {
+            key: "status",
+            label: "Status",
+            type: "select",
+            options: [
+              { value: "draft", label: "Draft" },
+              { value: "active", label: "Active" },
+            ],
+          },
+          { key: "care_guide", label: "Care Guide", type: "file" },
+          { key: "specs", label: "Specs", type: "json" },
+        ],
+        expose_client_helpers: false,
+        filterable: true,
+        widget_zone: "product.details.after",
+        api_endpoint: "/admin/products/{id}",
+      },
+      orders: {
+        descriptors: [
+          { key: "source", label: "Source", type: "text" },
+          { key: "priority", label: "Priority", type: "radio", options: [{ value: "normal" }, { value: "high" }] },
+        ],
+      },
+    },
+  },
+}
 ```
 
-### Universal Widget Architecture
+---
 
-The plugin uses a single universal widget component (`UniversalMetadataWidget`) that works for all entity types:
+## Environment Variables
 
-1. **Runtime Entity Detection**: The widget automatically detects the entity type using:
-   - **Zone-based detection** (primary): Resolves entity type from the widget zone (e.g., `"product.details.after"` → `"products"`)
-   - **Data structure detection** (fallback): Pattern matching on data properties (e.g., `handle`, `title` → products; `display_id`, `status` → orders)
+Environment variable usage found in plugin source:
 
-2. **Configuration Loading**: Fetches metadata descriptors from `/admin/metadata-config?entity={entityType}` based on detected entity type
+| Variable | Where | Purpose | Required | Example |
+|---|---|---|---|---|
+| `NODE_ENV` | `src/admin/components/universal-metadata-widget.tsx` | Enables/disables debug/warn logs in non-production mode. | Optional | `production` |
 
-3. **Dynamic Rendering**: Renders appropriate form fields based on the descriptors (text, number, date, select, multiselect, color, JSON, etc.)
+> ⚠️ Note: `src/modules/README.md` contains example text referencing `process.env.API_KEY`, but it is documentation content, not runtime plugin code.
 
-4. **Metadata Management**: Saves metadata through standard Medusa entity API endpoints
+---
 
-### Widget Structure
+## REST APIs / Routes
 
-Widget files are minimal wrappers that:
-- Specify the widget zone (required by Medusa)
-- Pass the zone to `UniversalMetadataWidget`
-- Let the universal component handle all entity-specific logic
+### 1) `GET /admin/metadata-config`
 
-Example widget file:
-```typescript
-const Widget = ({ data }) => {
-  return <UniversalMetadataWidget data={data} zone="product.details.after" />
-}
+- **Auth:** Admin (admin route namespace)
+- **Query params:**
+  - `entity` (`string`, optional, default: `"products"`)
+- **Response:**
+  ```json
+  {
+    "metadataDescriptors": [
+      {
+        "key": "brand",
+        "type": "text",
+        "label": "Brand"
+      }
+    ]
+  }
+  ```
+- **Behavior:**
+  - Reads plugin config with `resolveDynamicMetadataOptions`.
+  - Returns empty descriptor array when entity is not configured (no 404).
+
+### 2) `POST /admin/product-variants/:id`
+
+- **Auth:** Admin (admin route namespace)
+- **Path params:**
+  - `id` (`string`, required): product variant ID.
+- **Body:** passthrough payload with optional `metadata` object plus other variant update fields.
+- **Response:**
+  ```json
+  {
+    "product_variant": {
+      "id": "variant_...",
+      "metadata": {}
+    }
+  }
+  ```
+- **Behavior:**
+  - Executes `updateProductVariantsWorkflow` with selector by ID and update payload.
+  - Returns first updated variant as `product_variant`.
 
-export const config = defineWidgetConfig({
-  zone: "product.details.after"
+### Important Endpoint Examples
+
+```bash
+# Get metadata descriptors for products
+curl -X GET "http://localhost:9000/admin/metadata-config?entity=products" \
+  -H "Authorization: Bearer <admin_token>"
+```
+
+```bash
+# Update metadata on a product variant
+curl -X POST "http://localhost:9000/admin/product-variants/variant_123" \
+  -H "Authorization: Bearer <admin_token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "metadata": {
+      "fabric": "cotton",
+      "is_limited": true
+    }
+  }'
+```
+
+```ts
+// fetch example for metadata config
+const res = await fetch("/admin/metadata-config?entity=orders", {
+  credentials: "include",
 })
+const data = await res.json()
 ```
 
-### Creating Widgets for New Entities
+---
 
-To add metadata support for a new entity:
+## Services
 
-1. **Add configuration** in `medusa-config.ts`:
-```typescript
-entities: {
-  customers: {
-    descriptors: [
-      { key: "preferred_language", type: "text" }
-    ]
-  }
-}
-```
+No custom backend service classes are defined in this plugin source.
 
-2. **Create a minimal widget file** (if zone doesn't match existing patterns):
-   - Copy `src/admin/widget-templates/generic-metadata-widget.template.tsx` into `src/admin/widgets/`
-   - Update the zone to match your entity's admin zone
-   - The universal widget will automatically detect the entity type
-
-## Configuration Options
-
-### Entity Configuration
-
-Each entity in the configuration supports:
-
-- `descriptors`: Array of metadata field definitions
-  - `key`: Unique identifier for the field
-  - `label`: Display label (optional, defaults to key)
-  - `type`: Field type (see [Field Type Reference](#field-type-reference) below)
-  - `required`: Whether the field must have a value (default: `false`)
-  - `default_value`: Default value when no value is set (optional)
-  - `validation`: Validation rules — `{ min?: number, max?: number, regex?: string }` (optional)
-  - `options`: For `select`, `multiselect`, `radio`, `checkbox` — array of `{ value: string, label?: string }`
-  - `filterable`: Whether the field can be used for filtering (default: `false`)
-- `expose_client_helpers`: Expose client-side helper functions (default: `false`)
-- `filterable`: Enable filtering for this entity (default: `false`)
-- `widget_zone`: Custom widget zone override (optional)
-- `api_endpoint`: Custom API endpoint override (optional)
-
-### Field Type Reference
-
-| Type | Use Case | Options/Validation |
-|------|-----------|-------------------|
-| `text` | Short single-line text | — |
-| `textarea` | Multi-line text (product description) | — |
-| `richtext` | Formatted content (HTML) | — |
-| `markdown` | Markdown content | — |
-| `number` | Decimal numbers | min, max, regex |
-| `integer` | Whole numbers | min, max, regex |
-| `float` | Decimal numbers | min, max, regex |
-| `bool` | Boolean toggle | — |
-| `date` | Date only (sale start) | — |
-| `time` | Time only | — |
-| `datetime` | Date and time (scheduled publish) | — |
-| `select` | Single option dropdown | options required |
-| `multiselect` | Multiple options (tags) | options required |
-| `radio` | Single choice (UX alternative to select) | options required |
-| `checkbox` | Multiple checkboxes | options required |
-| `image` | Image URL (product badge) | — |
-| `video` | Video URL (demo video) | — |
-| `audio` | Audio URL | — |
-| `file` | Generic file URL | — |
-| `url` | Valid URL | — |
-| `email` | Email address | — |
-| `phone` | Phone number | — |
-| `color` | Color (hex or rgb) | — |
-| `json` | Arbitrary JSON | — |
-| `object` | JSON object | — |
-| `array` | JSON array | — |
-| `relation` | Entity ID reference | — |
-
-## API
-
-The plugin provides admin API endpoints for metadata management:
-
-- `GET /admin/metadata-config?entity={entityType}` - Get metadata descriptors for an entity
-- Metadata is managed through the standard Medusa entity APIs with metadata fields
-
-## Examples
-
-### Basic Configuration
-
-```typescript
-{
-  entities: {
-    products: {
-      descriptors: [
-        { key: "brand", type: "text", filterable: true },
-        { key: "warranty_years", type: "number" },
-      ],
-    },
-  },
-}
-```
+> ⚠️ Note: Most logic is implemented as configuration utilities (`src/config/*`) and shared metadata helpers (`src/shared/metadata/utils.ts`) consumed by admin UI.
 
-### Advanced Configuration
+---
 
-```typescript
-{
-  entities: {
-    products: {
-      descriptors: [
-        { key: "brand", label: "Brand Name", type: "text", filterable: true },
-        { key: "warranty_years", label: "Warranty Period", type: "number" },
-        { key: "has_warranty", label: "Has Warranty", type: "bool" },
-        { key: "manual_pdf", label: "Manual PDF", type: "file" },
-      ],
-      expose_client_helpers: true,
-      filterable: true,
-      widget_zone: "product.details.after", // Optional override
-    },
-  },
-}
-```
+## Workflows & Steps (Medusa v2)
 
-### Commerce-Focused Examples
+No custom workflows or steps are defined in this plugin source.
 
-```typescript
-{
-  entities: {
-    products: {
-      descriptors: [
-        // Sale dates
-        { key: "sale_start", label: "Sale Start", type: "datetime", required: true },
-        { key: "sale_end", label: "Sale End", type: "datetime" },
-        // Multiselect tags
-        {
-          key: "tags",
-          label: "Tags",
-          type: "multiselect",
-          options: [
-            { value: "bestseller", label: "Bestseller" },
-            { value: "new", label: "New Arrival" },
-            { value: "sale", label: "On Sale" },
-          ],
-        },
-        // Color customization
-        { key: "badge_color", label: "Badge Color", type: "color", default_value: "#ff0000" },
-        // Structured data
-        {
-          key: "dimensions",
-          label: "Dimensions (JSON)",
-          type: "object",
-          default_value: { width: 0, height: 0, depth: 0 },
-        },
-        // Contact/URL fields
-        { key: "support_url", label: "Support URL", type: "url" },
-        { key: "support_email", label: "Support Email", type: "email" },
-        { key: "support_phone", label: "Support Phone", type: "phone" },
-        // Relation to another product
-        { key: "related_product_id", label: "Related Product", type: "relation" },
-      ],
-    },
-  },
-}
-```
+The plugin calls Medusa core workflow `updateProductVariantsWorkflow` in `POST /admin/product-variants/:id`.
+
+---
+
+## Subscribers / Event Hooks
+
+No runtime subscribers/event handlers are defined in this plugin source (only template/readme scaffolding under `src/subscribers`).
+
+---
+
+## Admin UI / Widgets
+
+### Universal Components
+
+- **`UniversalMetadataWidget` (`src/admin/components/universal-metadata-widget.tsx`)**
+  - Detects entity type from widget zone; falls back to data-shape signals.
+  - Loads descriptors via `useMetadataConfig`.
+  - Renders `MetadataTableWidget` only when descriptors exist.
+
+- **`MetadataTableWidget` (`src/admin/components/metadata-table.tsx`)**
+  - Renders typed controls per descriptor.
+  - Performs descriptor-based validation.
+  - Uploads media/file fields through `POST /admin/uploads` and stores URL in metadata value.
+  - Saves metadata by resolving entity endpoint (`resolveApiEndpoint`) and calling `POST`.
+  - Invalidates/refetches React Query cache using resolved query keys.
+
+### Registered Metadata Widgets (wrappers)
+
+Each file is a minimal wrapper around `UniversalMetadataWidget` with a fixed zone:
+
+| Entity | Zone |
+|---|---|
+| `products` | `product.details.after` |
+| `orders` | `order.details.after` |
+| `categories` | `product_category.details.after` |
+| `collections` | `product_collection.details.after` |
+| `customers` | `customer.details.after` |
+| `regions` | `region.details.after` |
+| `sales_channels` | `sales_channel.details.after` |
+| `stores` | `store.details.after` |
+| `promotions` | `promotion.details.after` |
+| `campaigns` | `campaign.details.after` |
+| `price_lists` | `price_list.details.after` |
+| `shipping_profiles` | `shipping_profile.details.after` |
+| `inventory_items` | `inventory_item.details.after` |
+| `product_variants` | `product_variant.details.after` |
+
+### Additional Widget
+
+- **`hide-default-metadata` (`src/admin/widgets/hide-default-metadata.tsx`)**
+  - **Zone:** `product.details.side.before`
+  - **Purpose:** DOM-level hiding of default Medusa metadata panel to avoid UI duplication.
+  - **Interaction:** none (automatic MutationObserver behavior).
+
+> ⚠️ Note: This widget hides DOM elements by structure/class heuristics and may need adjustment if Admin DOM structure changes in future Medusa releases.
+
+---
+
+## Models & Entities
+
+No custom database models/entities are defined in this plugin source.
+
+The plugin operates on existing Medusa entities by reading/writing their `metadata` field via admin APIs.
+
+---
+
+## Use Cases & Examples
+
+1. **Product enrichment without code changes**
+   - Add new product metadata fields (brand, care instructions, support URLs) via plugin options.
+   - Use: `entities.products.descriptors` + `product.details.after` widget.
+
+2. **Operational order annotations**
+   - Add structured metadata to orders (source channel, routing note, internal tags).
+   - Use: `entities.orders.descriptors` + metadata table UI.
+
+3. **Per-entity metadata governance**
+   - Make fields required and validated (`min/max/regex`) to standardize admin data entry.
+   - Use: descriptor `required` and `validation`.
+
+4. **Variant-level custom attributes**
+   - Persist metadata on product variants and update through variant route workflow.
+   - Use: `POST /admin/product-variants/:id`.
+
+5. **File/media metadata links**
+   - Upload file/image/video/audio in metadata form and store uploaded URL in metadata.
+   - Use: file/media descriptor types in metadata table.
+
+---
+
+## Troubleshooting
+
+### Metadata widget doesn’t appear
+
+- **Cause:** no descriptors configured for that entity.
+- **Fix:** add `entities.<entityType>.descriptors` in plugin options; rebuild/restart app.
+
+### “Unable to load metadata configuration”
+
+- **Cause:** admin can’t reach `/admin/metadata-config` or plugin not loaded.
+- **Fix:** verify plugin registration in `medusa-config.ts`, rebuild plugin, restart Medusa server.
+
+### “No API endpoint configured for <entityType>”
 
-## Scripts
+- **Cause:** entity type lacks mapping in registry and no `api_endpoint` override configured.
+- **Fix:** set `api_endpoint` (and optionally `widget_zone`) for that entity in plugin options.
 
-- `npm run build` - Build the plugin
-- `npm run dev` - Run in development/watch mode
+### Save fails with backend error
 
-## What is Medusa
+- **Cause:** invalid payload, endpoint mismatch, or authorization issue.
+- **Fix:** verify resolved endpoint, admin auth/session, and descriptor/value shape.
 
-Medusa is a set of commerce modules and tools that allow you to build rich, reliable, and performant commerce applications without reinventing core commerce logic. The modules can be customized and used to build advanced ecommerce stores, marketplaces, or any product that needs foundational commerce primitives. All modules are open-source and freely available on npm.
+### File upload fails in metadata field
 
-Learn more about [Medusa’s architecture](https://docs.medusajs.com/learn/introduction/architecture) and [commerce modules](https://docs.medusajs.com/learn/fundamentals/modules/commerce-modules) in the Docs.
+- **Cause:** `/admin/uploads` request fails or no URL returned.
+- **Fix:** confirm uploads endpoint availability and permissions; inspect server response message shown in toast.
 
-## Community & Contributions
+### Default and custom metadata sections both visible
 
-The community and core team are available in [GitHub Discussions](https://github.com/medusajs/medusa/discussions), where you can ask for support, discuss roadmap, and share ideas.
+- **Cause:** hide widget not active for current zone/page or DOM structure mismatch.
+- **Fix:** verify `hide-default-metadata` widget registration and adjust selector logic if Admin markup changed.
 
-Join our [Discord server](https://discord.com/invite/medusajs) to meet other community members.
+---
 
-## Other channels
 
-- [GitHub Issues](https://github.com/medusajs/medusa/issues)
-- [Twitter](https://twitter.com/medusajs)
-- [LinkedIn](https://www.linkedin.com/company/medusajs)
-- [Medusa Blog](https://medusajs.com/blog/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-dynamic-metadata",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "A starter for Medusa plugins.",
   "author": "Medusa (https://medusajs.com)",
   "license": "MIT",