feat: add WpMediaUpload field type for WordPress Media Library

src/components/settings/Settings.stories.tsx

@@ -5328,7 +5328,7 @@ const dokanSettingsSchema: SettingsElement[] = [
                                 "dependency_key": "vendor_onboarding.vendor_setup_wizard_logo",
                                 "dependencies": [],
                                 "validations": [],
-                                "variant": "file_upload",
+                                "variant": "wp_media_upload",
                                 "value": "",
                                 "default": "",
                                 "placeholder": "+ Choose File",

src/components/settings/field-renderer.tsx

@@ -21,6 +21,8 @@ import {
     RichTextField,
     GoogleAnalyticsField,
     CombineInputField,
+    WpMediaUploadField,
+    WpMediaUploadMultipleField,
 } from './fields';
 
 // ============================================
@@ -224,6 +226,20 @@ export function FieldRenderer({
                 mergedElement
             );
 
+        case 'wp_media_upload':
+            return applyFilters(
+                `${filterPrefix}_settings_wp_media_upload_field`,
+                <WpMediaUploadField {...fieldProps} />,
+                mergedElement
+            );
+
+        case 'wp_media_upload_multiple':
+            return applyFilters(
+                `${filterPrefix}_settings_wp_media_upload_multiple_field`,
+                <WpMediaUploadMultipleField {...fieldProps} />,
+                mergedElement
+            );
+
         default:
             // Unknown variant — consumer must handle via applyFilters
             return applyFilters(

src/components/settings/fields.tsx

@@ -1,4 +1,5 @@
 import React, { useState } from "react";
+import { WpMediaUpload, WpMediaUploadMultiple } from '../wordpress/WpMediaUpload';
 import { cn } from "@/lib/utils";
 import * as LucideIcons from "lucide-react";
 import { FileText, Info, Eye, EyeOff, ArrowUpRight, RefreshCcw } from "lucide-react";
@@ -931,6 +932,40 @@ export function CombineInputField({ element, onChange, ...rest }: FieldComponent
   );
 }
 
+// ============================================
+// WP Media Upload Fields
+// ============================================
+
+export function WpMediaUploadField({ element, onChange, ...rest }: FieldComponentProps) {
+  return (
+    <FieldWrapper element={element} layout={element.layout ?? 'horizontal'} {...rest}>
+      <WpMediaUpload
+        value={String(element.value ?? '')}
+        onChange={(url) => onChange(element.dependency_key!, url)}
+        btnText={element.placeholder ? String(element.placeholder) : undefined}
+        disabled={element.disabled}
+      />
+    </FieldWrapper>
+  );
+}
+
+export function WpMediaUploadMultipleField({ element, onChange, ...rest }: FieldComponentProps) {
+  const currentValue = Array.isArray(element.value)
+    ? (element.value as string[])
+    : element.value ? [String(element.value)] : [];
+
+  return (
+    <FieldWrapper element={element} layout={element.layout ?? 'horizontal'} {...rest}>
+      <WpMediaUploadMultiple
+        value={currentValue}
+        onChange={(urls) => onChange(element.dependency_key!, urls)}
+        btnText={element.placeholder ? String(element.placeholder) : undefined}
+        disabled={element.disabled}
+      />
+    </FieldWrapper>
+  );
+}
+
 // ============================================
 // Fallback Field (for unknown variants)
 // ============================================

src/components/settings/settings-content.tsx

@@ -4,6 +4,7 @@ import { FieldRenderer } from './field-renderer';
 import { cn } from '@/lib/utils';
 import { FileText, Info } from "lucide-react";
 import { ScrollArea, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui";
+import { Button } from "@/components/ui/button";
 import { RawHTML } from "@wordpress/element";
 
 // ============================================
@@ -137,7 +138,14 @@ export function SettingsContent({ className }: { className?: string }) {
               >
                   {renderSaveButton
                     ? renderSaveButton({ scopeId, dirty, hasErrors, onSave: handleSave })
-                    : null}
+                    : (
+                      <Button
+                        onClick={handleSave}
+                        disabled={!dirty || hasErrors}
+                      >
+                        Save Changes
+                      </Button>
+                    )}
               </div>
             )}
 

src/components/wordpress/WpMediaUpload.stories.tsx

@@ -0,0 +1,141 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { fn } from 'storybook/test';
+import { useState } from 'react';
+import { WpMediaUpload, WpMediaUploadMultiple } from './WpMediaUpload';
+
+// ── Mock wp.media for Storybook (not available outside WordPress) ─────────────
+
+const SAMPLE_IMAGE = 'https://placehold.co/400x400/e2e8f0/475569?text=Logo';
+const SAMPLE_IMAGES = [
+    'https://placehold.co/400x400/e2e8f0/475569?text=Image+1',
+    'https://placehold.co/400x400/dbeafe/1d4ed8?text=Image+2',
+    'https://placehold.co/400x400/dcfce7/15803d?text=Image+3',
+];
+
+function mockWpMedia( multiple = false ) {
+    ( window as any ).wp = {
+        media: ( _options: object ) => {
+            let selectCb: (() => void) | null = null;
+            const urls = multiple ? SAMPLE_IMAGES.slice( 0, 2 ) : [ SAMPLE_IMAGE ];
+            return {
+                on: ( event: string, cb: () => void ) => {
+                    if ( event === 'select' ) selectCb = cb;
+                },
+                once: ( event: string, cb: () => void ) => {
+                    if ( event === 'select' ) selectCb = cb;
+                },
+                open: () => {
+                    // Simulate async media selection
+                    setTimeout( () => selectCb?.(), 300 );
+                },
+                state: () => ( {
+                    get: ( key: string ) => {
+                        if ( key !== 'selection' ) return null;
+                        if ( multiple ) {
+                            const items = urls.map( ( url ) => ( { toJSON: () => ( { url } ) } ) );
+                            return {
+                                map: ( fn: ( a: any ) => any ) => items.map( fn ),
+                                each: ( fn: ( a: any ) => void ) => items.forEach( fn ),
+                                pop: () => items.pop(),
+                            };
+                        }
+                        const item = { toJSON: () => ( { url: urls[0] } ) };
+                        return {
+                            map: ( fn: ( a: any ) => any ) => [ item ].map( fn ),
+                            each: ( fn: ( a: any ) => void ) => [ item ].forEach( fn ),
+                            first: () => item,
+                            pop: () => item.toJSON(),
+                        };
+                    },
+                } ),
+            };
+        },
+    };
+}
+
+// ── Single ────────────────────────────────────────────────────────────────────
+
+const SingleMeta = {
+    title: 'WordPress/WpMediaUpload',
+    component: WpMediaUpload,
+    parameters: { layout: 'centered' },
+    tags: ['autodocs'],
+    args: {
+        onChange: fn(),
+    },
+    argTypes: {
+        value: { control: 'text' },
+        btnText: { control: 'text' },
+        disabled: { control: 'boolean' },
+    },
+    decorators: [
+        ( Story: any ) => {
+            mockWpMedia( false );
+            return <Story />;
+        },
+    ],
+} satisfies Meta<typeof WpMediaUpload>;
+
+export default SingleMeta;
+
+type SingleStory = StoryObj<typeof SingleMeta>;
+
+export const Empty: SingleStory = {
+    args: {
+        btnText: 'Upload Logo',
+    },
+};
+
+export const WithPreview: SingleStory = {
+    args: {
+        value: SAMPLE_IMAGE,
+        btnText: 'Upload Logo',
+    },
+};
+
+export const Disabled: SingleStory = {
+    args: {
+        value: SAMPLE_IMAGE,
+        btnText: 'Upload Logo',
+        disabled: true,
+    },
+};
+
+/** Interactive — click "Upload Image" to simulate a media library selection. */
+export const Interactive: SingleStory = {
+    render: ( args ) => {
+        const [ value, setValue ] = useState( args.value ?? '' );
+        return <WpMediaUpload { ...args } value={ value } onChange={ setValue } />;
+    },
+    args: {},
+};
+
+// ── Multiple ──────────────────────────────────────────────────────────────────
+
+export const Multiple: StoryObj<typeof WpMediaUploadMultiple> = {
+    render: () => {
+        const [ values, setValues ] = useState<string[]>( [] );
+        mockWpMedia( true );
+        return (
+            <WpMediaUploadMultiple
+                value={ values }
+                onChange={ setValues }
+                btnText="Add Images"
+            />
+        );
+    },
+};
+
+export const MultipleWithExisting: StoryObj<typeof WpMediaUploadMultiple> = {
+    render: () => {
+        const [ values, setValues ] = useState<string[]>( SAMPLE_IMAGES );
+        mockWpMedia( true );
+        return (
+            <WpMediaUploadMultiple
+                value={ values }
+                onChange={ setValues }
+                btnText="Add Images"
+            />
+        );
+    },
+};

src/components/wordpress/WpMediaUpload.tsx

@@ -0,0 +1,144 @@
+import React from 'react';
+import { Upload, X } from 'lucide-react';
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/ui/button';
+import wpMedia from '@/lib/WpMedia';
+
+// ─── Single ───────────────────────────────────────────────────────────────────
+
+export interface WpMediaUploadProps {
+    value?: string;
+    onChange: ( url: string ) => void;
+    btnText?: string;
+    className?: string;
+    disabled?: boolean;
+}
+
+export function WpMediaUpload( {
+    value,
+    onChange,
+    btnText = 'Upload Image',
+    className,
+    disabled,
+}: WpMediaUploadProps ) {
+    const handleUpload = () => {
+        wpMedia( ( file ) => {
+            const url = Array.isArray( file ) ? ( file[0]?.url ?? '' ) : ( file as { url: string } ).url;
+            onChange( url );
+        } );
+    };
+
+    return (
+        <div className={ cn( 'flex flex-col items-end gap-2', className ) }>
+            { value && (
+                <div className="relative inline-flex">
+                    <img
+                        src={ value }
+                        alt=""
+                        className="h-16 w-16 rounded-md border border-border bg-muted object-contain p-1"
+                    />
+                    <button
+                        type="button"
+                        disabled={ disabled }
+                        title="Remove"
+                        onClick={ () => onChange( '' ) }
+                        className="absolute -right-2 -top-2 flex h-4 w-4 items-center justify-center rounded-full bg-destructive text-white hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-50"
+                    >
+                        <X size={ 10 } strokeWidth={ 3 } />
+                    </button>
+                </div>
+            ) }
+            <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                disabled={ disabled }
+                onClick={ handleUpload }
+                className="gap-1.5"
+            >
+                <Upload size={ 14 } />
+                { value ? 'Change' : btnText }
+            </Button>
+        </div>
+    );
+}
+
+// ─── Multiple ─────────────────────────────────────────────────────────────────
+
+export interface WpMediaUploadMultipleProps {
+    value?: string[];
+    onChange: ( urls: string[] ) => void;
+    btnText?: string;
+    className?: string;
+    disabled?: boolean;
+}
+
+export function WpMediaUploadMultiple( {
+    value = [],
+    onChange,
+    btnText = 'Add Images',
+    className,
+    disabled,
+}: WpMediaUploadMultipleProps ) {
+    const handleUpload = () => {
+        // @ts-expect-error wp.media is not defined in the global scope
+        const frame = wp.media( {
+            title: 'Select Images',
+            button: { text: 'Add' },
+            multiple: true,
+        } );
+
+        frame.once( 'select', () => {
+            const selection = frame.state().get( 'selection' );
+            const newUrls: string[] = [];
+            selection.each( ( attachment: { toJSON: () => { url: string } } ) => {
+                newUrls.push( attachment.toJSON().url );
+            } );
+            onChange( [ ...value, ...newUrls ] );
+        } );
+
+        frame.open();
+    };
+
+    const remove = ( index: number ) => {
+        onChange( value.filter( ( _, i ) => i !== index ) );
+    };
+
+    return (
+        <div className={ cn( 'flex flex-col items-end gap-2', className ) }>
+            { value.length > 0 && (
+                <div className="flex flex-wrap justify-end gap-2">
+                    { value.map( ( url, i ) => (
+                        <div key={ i } className="relative inline-flex">
+                            <img
+                                src={ url }
+                                alt=""
+                                className="h-14 w-14 rounded-md border border-border bg-muted object-contain p-1"
+                            />
+                            <button
+                                type="button"
+                                disabled={ disabled }
+                                title="Remove"
+                                onClick={ () => remove( i ) }
+                                className="absolute -right-1.5 -top-1.5 flex h-4 w-4 items-center justify-center rounded-full bg-destructive text-white hover:opacity-90 disabled:cursor-not-allowed disabled:opacity-50"
+                            >
+                                <X size={ 10 } strokeWidth={ 3 } />
+                            </button>
+                        </div>
+                    ) ) }
+                </div>
+            ) }
+            <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                disabled={ disabled }
+                onClick={ handleUpload }
+                className="gap-1.5"
+            >
+                <Upload size={ 14 } />
+                { btnText }
+            </Button>
+        </div>
+    );
+}