Merge pull request #3790 from udecode/histor/media-placeholder

Histor/media placeholder

.changeset/witty-eels-agree.md

@@ -0,0 +1,5 @@
+---
+'@udecode/plate-media': patch
+---
+
+Fix editor crash when inserting media into an empty paragraph.

apps/www/content/docs/media-placeholder.mdx

@@ -25,7 +25,6 @@ npm install @udecode/plate-media
 ```
 
 ## Usage
-How to configuration the backend see [Upload](/docs/upload).
 
 ```tsx
 import {
@@ -59,11 +58,78 @@ const components = {
 };
 ```
 
+### UploadThing Integration
 
-## UploadOptions
+The UploadThing integration provides an easy way to handle file uploads in your editor. Follow these steps to set it up:
 
-### uploadConfig
+1. Install the required dependencies:
 
+   ```bash
+   npm install @uploadthing/react uploadthing
+   ```
+
+2. Install the [media-placeholder-element](/docs/components/media-placeholder-element) component.
+
+3. Set up the UploadThing API route by copying the [example implementation](https://github.com/udecode/plate/blob/main/templates/plate-playground-template/src/app/api/uploadthing/core.ts).
+
+4. Get your UploadThing API key from the [dashboard](https://uploadthing.com/dashboard) and add it to your `.env` file:
+   ```bash
+   UPLOADTHING_SECRET=your_secret_key
+   ```
+
+### Using your own backend
+
+To implement your own backend for file uploads:
+
+1. Remove the UploadThing implementation:
+
+   ```bash
+   lib/uploadthing/
+   api/uploadthing/
+   ```
+
+2. Create your own upload hook:
+
+   ```ts
+   function useUploadFile() {
+     // Your implementation here
+     return {
+       isUploading: boolean,
+       progress: number,
+       uploadFile: (file: File) => Promise<UploadedFile>,
+       uploadedFile: UploadedFile | undefined,
+       uploadingFile: File | undefined,
+     };
+   }
+   ```
+
+3. The hook should match the interface expected by the media placeholder component:
+   ```ts
+   interface UploadedFile {
+     key: string;
+     url: string;
+     name: string;
+     size: number;
+     type: string;
+   }
+   ```
+
+### Plate UI
+
+Refer to the preview above.
+
+### Plate Plus
+
+<ComponentPreviewPro name="upload-pro" />
+
+## Plugins
+
+### PlaceholderPlugin
+
+Media placeholder element plugin.
+
+<APIOptions>
+<APIItem name="uploadConfig" type="Partial<Record<AllowedFileType, MediaItemConfig>>" optional>
 Configuration for different file types:
 
 - You can use this option to configure upload limits for each file type, including:
@@ -129,45 +195,26 @@ Configuration for different file types:
   ] as const;
   ```
 
-### disableEmptyPlaceholder
-
-`boolean` (default: `false`)
+</APIItem>
 
+<APIItem name="disableEmptyPlaceholder" type="boolean" optional>
 Disable empty placeholder when no file is selected.
 
-### disableFileDrop
-
-`boolean` (default: `false`)
+- **Default:** `false`
+</APIItem>
 
+<APIItem name="disableFileDrop" type="boolean" optional>
 Whether we can undo to the placeholder after the file upload is complete.
 
-### maxFileCount
-
-`number` (default: `5`)
+- **Default:** `false`
+</APIItem>
 
+<APIItem name="maxFileCount" type="number" optional>
 Maximum number of files that can be uploaded at once.
 
-### multiple
-
-`boolean` (default: `true`)
-
-Whether multiple files can be uploaded in one time.
-
-## Examples
-
-### Plate UI
-
-Refer to the preview above.
-
-### Plate Plus
-
-<ComponentPreviewPro name="upload-pro" />
-
-## Plugins
-
-### PlaceholderPlugin
-
-Media placeholder element plugin.
+- **Default:** `5`
+</APIItem>
+</APIOptions>
 
 ## Transforms
 

apps/www/package.json

@@ -131,6 +131,7 @@
     "@udecode/slate-react": "workspace:^",
     "@udecode/slate-utils": "workspace:^",
     "@udecode/utils": "workspace:^",
+    "@uploadthing/react": "7.1.0",
     "@vercel/og": "^0.6.2",
     "ai": "^3.4.10",
     "class-variance-authority": "^0.7.0",
@@ -172,6 +173,7 @@
     "ts-morph": "^22.0.0",
     "unist-builder": "4.0.0",
     "unist-util-visit": "^5.0.0",
+    "uploadthing": "7.2.0",
     "use-file-picker": "2.1.2",
     "vaul": "0.9.0"
   },

apps/www/public/r/styles/default/api-uploadthing.json

@@ -0,0 +1,19 @@
+{
+  "dependencies": [
+    "[email protected]"
+  ],
+  "files": [
+    {
+      "content": "import type { FileRouter } from 'uploadthing/next';\n\nimport { createRouteHandler, createUploadthing } from 'uploadthing/next';\n\nconst f = createUploadthing();\n\n// FileRouter for your app, can contain multiple FileRoutes\nconst ourFileRouter = {\n  // Define as many FileRoutes as you like, each with a unique routeSlug\n  imageUploader: f(['image', 'text', 'blob', 'pdf', 'video', 'audio'])\n    // Set permissions and file types for this FileRoute\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/require-await\n    .middleware(async ({ req }) => {\n      // This code runs on your server before upload\n\n      // Whatever is returned here is accessible in onUploadComplete as `metadata`\n      return {};\n    })\n    // eslint-disable-next-line @typescript-eslint/no-unused-vars\n    .onUploadComplete(({ file, metadata }) => {\n      // This code RUNS ON YOUR SERVER after upload\n\n      // !!! Whatever is returned here is sent to the clientside `onClientUploadComplete` callback\n      return { file };\n    }),\n} satisfies FileRouter;\n\nexport type OurFileRouter = typeof ourFileRouter;\n\n// Export routes for Next App Router\nexport const { GET, POST } = createRouteHandler({\n  router: ourFileRouter,\n\n  // Apply an (optional) custom config:\n  // config: { ... },\n});\n",
+      "path": "components/api/uploadthing/route.ts",
+      "target": "app/api/uploadthing/route.ts",
+      "type": "registry:page"
+    }
+  ],
+  "name": "api-uploadthing",
+  "registryDependencies": [
+    "media-placeholder-element",
+    "uploadthing"
+  ],
+  "type": "registry:component"
+}