@btst/stack 2.8.1 → 2.9.0

package/src/plugins/blog/client/components/forms/markdown-editor.tsx

@@ -8,7 +8,12 @@ import { editorViewCtx, parserCtx } from "@milkdown/kit/core";
 import { listener, listenerCtx } from "@milkdown/kit/plugin/listener";
 import { Slice } from "@milkdown/kit/prose/model";
 import { Selection } from "@milkdown/kit/prose/state";
-import { useLayoutEffect, useRef, useState } from "react";
+import {
+	useLayoutEffect,
+	useRef,
+	useState,
+	type MutableRefObject,
+} from "react";
 
 export interface MarkdownEditorProps {
 	value?: string;
@@ -18,6 +23,19 @@ export interface MarkdownEditorProps {
 	uploadImage?: (file: File) => Promise<string>;
 	/** Placeholder text shown when the editor is empty. */
 	placeholder?: string;
+	/**
+	 * Optional ref that will be populated with an `insertImage(url)` function.
+	 * Call `insertImageRef.current?.(url)` to programmatically insert an image.
+	 * The URL must be a valid, percent-encoded URL (storage adapters guarantee this).
+	 */
+	insertImageRef?: MutableRefObject<((url: string) => void) | null>;
+	/**
+	 * When provided, clicking the Crepe image block's upload area opens a media
+	 * picker instead of the native file dialog. The callback receives a `setUrl`
+	 * function — call it with the chosen URL to set it into the image block.
+	 * The URL must be a valid, percent-encoded URL (storage adapters guarantee this).
+	 */
+	openMediaPickerForImageBlock?: (setUrl: (url: string) => void) => void;
 }
 
 export function MarkdownEditor({
@@ -26,6 +44,8 @@ export function MarkdownEditor({
 	className,
 	uploadImage,
 	placeholder = "Write something...",
+	insertImageRef,
+	openMediaPickerForImageBlock,
 }: MarkdownEditorProps) {
 	const containerRef = useRef<HTMLDivElement | null>(null);
 	const crepeRef = useRef<Crepe | null>(null);
@@ -33,6 +53,9 @@ export function MarkdownEditor({
 	const [isReady, setIsReady] = useState(false);
 	const onChangeRef = useRef<typeof onChange>(onChange);
 	const initialValueRef = useRef<string>(value ?? "");
+	const openMediaPickerRef = useRef<typeof openMediaPickerForImageBlock>(
+		openMediaPickerForImageBlock,
+	);
 	type ThrottledFn = ((markdown: string) => void) & {
 		cancel?: () => void;
 		flush?: () => void;
@@ -40,12 +63,24 @@ export function MarkdownEditor({
 	const throttledOnChangeRef = useRef<ThrottledFn | null>(null);
 
 	onChangeRef.current = onChange;
+	openMediaPickerRef.current = openMediaPickerForImageBlock;
 
 	useLayoutEffect(() => {
 		if (crepeRef.current) return;
 		const container = containerRef.current;
 		if (!container) return;
 
+		const hasMediaPicker = !!openMediaPickerRef.current;
+
+		const imageBlockConfig: Record<string, unknown> = {};
+		if (uploadImage) {
+			imageBlockConfig.onUpload = async (file: File) => uploadImage(file);
+		}
+		if (hasMediaPicker) {
+			imageBlockConfig.blockUploadPlaceholderText = "Media Picker";
+			imageBlockConfig.inlineUploadPlaceholderText = "Media Picker";
+		}
+
 		const crepe = new Crepe({
 			root: container,
 			defaultValue: initialValueRef.current,
@@ -53,19 +88,47 @@ export function MarkdownEditor({
 				[CrepeFeature.Placeholder]: {
 					text: placeholder,
 				},
-				...(uploadImage
-					? {
-							[CrepeFeature.ImageBlock]: {
-								onUpload: async (file: File) => {
-									const url = await uploadImage(file);
-									return url;
-								},
-							},
-						}
+				...(Object.keys(imageBlockConfig).length > 0
+					? { [CrepeFeature.ImageBlock]: imageBlockConfig }
 					: {}),
 			},
 		});
 
+		// Intercept clicks on Crepe image-block upload placeholders so that the
+		// native file dialog is suppressed and the media picker is opened instead.
+		const interceptHandler = (e: MouseEvent) => {
+			if (!openMediaPickerRef.current) return;
+			const target = e.target as Element;
+			// Only intercept clicks inside the upload placeholder area.
+			const inPlaceholder = target.closest(".image-edit .placeholder");
+			if (!inPlaceholder) return;
+			// Let the hidden file <input> itself through (shouldn't receive clicks normally).
+			if ((target as HTMLElement).matches("input")) return;
+
+			e.preventDefault();
+			e.stopPropagation();
+
+			const imageEdit = inPlaceholder.closest(".image-edit");
+			const linkInput = imageEdit?.querySelector(
+				".link-input-area",
+			) as HTMLInputElement | null;
+
+			openMediaPickerRef.current((url: string) => {
+				if (!linkInput) return;
+				// Use the native setter so Vue's reactivity picks up the change.
+				const nativeSetter = Object.getOwnPropertyDescriptor(
+					HTMLInputElement.prototype,
+					"value",
+				)?.set;
+				nativeSetter?.call(linkInput, url);
+				linkInput.dispatchEvent(new Event("input", { bubbles: true }));
+				linkInput.dispatchEvent(
+					new KeyboardEvent("keydown", { key: "Enter", bubbles: true }),
+				);
+			});
+		};
+		container.addEventListener("click", interceptHandler, true);
+
 		// Prepare throttled onChange once per editor instance
 		throttledOnChangeRef.current = throttle((markdown: string) => {
 			if (onChangeRef.current) onChangeRef.current(markdown);
@@ -86,6 +149,7 @@ export function MarkdownEditor({
 		crepeRef.current = crepe;
 
 		return () => {
+			container.removeEventListener("click", interceptHandler, true);
 			try {
 				isReadyRef.current = false;
 				throttledOnChangeRef.current?.cancel?.();
@@ -133,6 +197,38 @@ export function MarkdownEditor({
 		});
 	}, [value, isReady]);
 
+	// Expose insertImage via ref so the parent can insert images programmatically
+	useLayoutEffect(() => {
+		if (!insertImageRef) return;
+		insertImageRef.current = (url: string) => {
+			if (!crepeRef.current || !isReadyRef.current) return;
+			try {
+				const currentMarkdown = crepeRef.current.getMarkdown?.() ?? "";
+				const imageMarkdown = `\n\n![](${url})\n\n`;
+				const newMarkdown = currentMarkdown.trimEnd() + imageMarkdown;
+				crepeRef.current.editor.action((ctx) => {
+					const view = ctx.get(editorViewCtx);
+					const parser = ctx.get(parserCtx);
+					const doc = parser(newMarkdown);
+					if (!doc) return;
+					const state = view.state;
+					const tr = state.tr.replace(
+						0,
+						state.doc.content.size,
+						new Slice(doc.content, 0, 0),
+					);
+					view.dispatch(tr);
+				});
+				if (onChangeRef.current) onChangeRef.current(newMarkdown);
+			} catch {
+				// Editor may not be ready yet
+			}
+		};
+		return () => {
+			if (insertImageRef) insertImageRef.current = null;
+		};
+	}, [insertImageRef]);
+
 	return (
 		<div ref={containerRef} className={cn("milkdown-custom", className)} />
 	);

package/src/plugins/blog/client/overrides.ts

@@ -2,6 +2,18 @@ import type { SerializedPost } from "../types";
 import type { ComponentType, ReactNode } from "react";
 import type { BlogLocalization } from "./localization";
 
+/**
+ * Props for the overridable blog featured image input component.
+ */
+export interface BlogImageInputFieldProps {
+	/** Current image URL value */
+	value: string;
+	/** Called when the image URL changes */
+	onChange: (value: string) => void;
+	/** Whether the field is required */
+	isRequired?: boolean;
+}
+
 /**
  * Context passed to lifecycle hooks
  */
@@ -48,9 +60,54 @@ export interface BlogPluginOverrides {
 		React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>
 	>;
 	/**
-	 * Function used to upload an image and return its URL.
+	 * Function used to upload a new image file and return its URL.
+	 * This is separate from `imagePicker`, which selects an existing asset URL.
 	 */
 	uploadImage: (file: File) => Promise<string>;
+	/**
+	 * Optional custom component for the featured image field.
+	 *
+	 * When provided it replaces the default file-upload input entirely.
+	 * The component receives `value` (current URL string) and `onChange` (setter).
+	 *
+	 * Typical use case: render a preview when a value is set, and a media-picker
+	 * trigger when no value is set.
+	 *
+	 * @example
+	 * ```tsx
+	 * imageInputField: ({ value, onChange }) =>
+	 *   value ? (
+	 *     <div>
+	 *       <img src={value} alt="Preview" />
+	 *       <MediaPicker trigger={<button>Change</button>} accept={["image/*"]}
+	 *         onSelect={(assets) => onChange(assets[0].url)} />
+	 *     </div>
+	 *   ) : (
+	 *     <MediaPicker trigger={<button>Browse media</button>} accept={["image/*"]}
+	 *       onSelect={(assets) => onChange(assets[0].url)} />
+	 *   )
+	 * ```
+	 */
+	imageInputField?: ComponentType<BlogImageInputFieldProps>;
+
+	/**
+	 * Optional trigger component for a media picker.
+	 * When provided, it is rendered adjacent to the Markdown editor and allows
+	 * users to browse and select previously uploaded assets.
+	 * Receives `onSelect(url)` — insert the chosen URL into the editor.
+	 *
+	 * @example
+	 * ```tsx
+	 * imagePicker: ({ onSelect }) => (
+	 *   <MediaPicker
+	 *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+	 *     accept={["image/*"]}
+	 *     onSelect={(assets) => onSelect(assets[0].url)}
+	 *   />
+	 * )
+	 * ```
+	 */
+	imagePicker?: ComponentType<{ onSelect: (url: string) => void }>;
 	/**
 	 * Localization object for the blog plugin
 	 */

package/src/plugins/cms/client/components/forms/content-form.tsx

@@ -56,6 +56,12 @@ function buildFieldConfigFromJsonSchema(
 		string,
 		React.ComponentType<AutoFormInputComponentProps>
 	>,
+	imagePicker?: React.ComponentType<{ onSelect: (url: string) => void }>,
+	imageInputField?: React.ComponentType<{
+		value: string;
+		onChange: (value: string) => void;
+		isRequired?: boolean;
+	}>,
 ): FieldConfig<Record<string, unknown>> {
 	// Get base config from shared utility (handles fieldType from JSON Schema)
 	const baseConfig = buildFieldConfigBase(jsonSchema, fieldComponents);
@@ -73,14 +79,14 @@ function buildFieldConfigFromJsonSchema(
 		// Handle "file" fieldType when there's NO custom component for "file"
 		if (prop.fieldType === "file" && !fieldComponents?.["file"]) {
 			// Use CMSFileUpload as the default file component
-			if (!uploadImage) {
-				// Show a clear error message if uploadImage is not provided
+			if (!uploadImage && !imageInputField) {
+				// Show a clear error message if neither uploadImage nor imageInputField is provided
 				baseConfig[key] = {
 					...baseConfig[key],
 					fieldType: () => (
 						<div className="rounded-md border border-destructive bg-destructive/10 p-3 text-sm text-destructive">
-							File upload requires an <code>uploadImage</code> function in CMS
-							overrides.
+							File upload requires an <code>uploadImage</code> or{" "}
+							<code>imageInputField</code> function in CMS overrides.
 						</div>
 					),
 				};
@@ -88,7 +94,12 @@ function buildFieldConfigFromJsonSchema(
 				baseConfig[key] = {
 					...baseConfig[key],
 					fieldType: (props: AutoFormInputComponentProps) => (
-						<CMSFileUpload {...props} uploadImage={uploadImage} />
+						<CMSFileUpload
+							{...props}
+							uploadImage={uploadImage ?? (() => Promise.resolve(""))}
+							imageInputField={imageInputField}
+							imagePicker={imagePicker}
+						/>
 					),
 				};
 			}
@@ -151,6 +162,8 @@ export function ContentForm({
 	const {
 		localization: customLocalization,
 		uploadImage,
+		imagePicker,
+		imageInputField,
 		fieldComponents,
 	} = usePluginOverrides<CMSPluginOverrides>("cms");
 	const localization = { ...CMS_LOCALIZATION, ...customLocalization };
@@ -214,8 +227,14 @@ export function ContentForm({
 	// Build field config for AutoForm (fieldType is now embedded in jsonSchema)
 	const fieldConfig = useMemo(
 		() =>
-			buildFieldConfigFromJsonSchema(jsonSchema, uploadImage, fieldComponents),
-		[jsonSchema, uploadImage, fieldComponents],
+			buildFieldConfigFromJsonSchema(
+				jsonSchema,
+				uploadImage,
+				fieldComponents,
+				imagePicker,
+				imageInputField,
+			),
+		[jsonSchema, uploadImage, fieldComponents, imagePicker, imageInputField],
 	);
 
 	// Find the field to use for slug auto-generation

package/src/plugins/cms/client/components/forms/file-upload.tsx

@@ -1,6 +1,12 @@
 "use client";
 
-import { useState, useCallback, useEffect, type ChangeEvent } from "react";
+import {
+	useState,
+	useCallback,
+	useEffect,
+	type ChangeEvent,
+	type ComponentType,
+} from "react";
 import { toast } from "sonner";
 import type { AutoFormInputComponentProps } from "@workspace/ui/components/auto-form/types";
 import { Input } from "@workspace/ui/components/input";
@@ -23,6 +29,20 @@ export interface CMSFileUploadProps extends AutoFormInputComponentProps {
 	 * This is required - consumers must provide an upload implementation.
 	 */
 	uploadImage: (file: File) => Promise<string>;
+	/**
+	 * Optional custom component for the image field.
+	 * When provided, it replaces the default file-upload input entirely.
+	 */
+	imageInputField?: ComponentType<{
+		value: string;
+		onChange: (value: string) => void;
+		isRequired?: boolean;
+	}>;
+	/**
+	 * Optional trigger component for a media picker.
+	 * When provided, it is rendered as a "Browse media" option.
+	 */
+	imagePicker?: ComponentType<{ onSelect: (url: string) => void }>;
 }
 
 /**
@@ -54,6 +74,8 @@ export function CMSFileUpload({
 	fieldProps,
 	field,
 	uploadImage,
+	imageInputField: ImageInputField,
+	imagePicker: ImagePickerTrigger,
 }: CMSFileUploadProps) {
 	// Exclude showLabel and value from props spread
 	// File inputs cannot have their value set programmatically (browser security)
@@ -63,6 +85,8 @@ export function CMSFileUpload({
 		...safeFieldProps
 	} = fieldProps;
 	const showLabel = _showLabel === undefined ? true : _showLabel;
+
+	// All hooks must be called unconditionally before any early return.
 	const [isUploading, setIsUploading] = useState(false);
 	const [previewUrl, setPreviewUrl] = useState<string | null>(
 		field.value || null,
@@ -80,7 +104,6 @@ export function CMSFileUpload({
 			const file = e.target.files?.[0];
 			if (!file) return;
 
-			// Check if it's an image
 			if (!file.type.startsWith("image/")) {
 				toast.error("Please select an image file");
 				return;
@@ -106,6 +129,29 @@ export function CMSFileUpload({
 		field.onChange("");
 	}, [field]);
 
+	// When a custom imageInputField component is provided via overrides, delegate to it.
+	if (ImageInputField) {
+		return (
+			<FormItem>
+				{showLabel && (
+					<AutoFormLabel
+						label={fieldConfigItem?.label || label}
+						isRequired={isRequired}
+					/>
+				)}
+				<FormControl>
+					<ImageInputField
+						value={field.value || ""}
+						onChange={field.onChange}
+						isRequired={isRequired}
+					/>
+				</FormControl>
+				<AutoFormTooltip fieldConfigItem={fieldConfigItem} />
+				<FormMessage />
+			</FormItem>
+		);
+	}
+
 	return (
 		<FormItem>
 			{showLabel && (
@@ -116,19 +162,31 @@ export function CMSFileUpload({
 			)}
 			{!previewUrl && (
 				<FormControl>
-					<div className="relative">
-						<Input
-							type="file"
-							accept="image/*"
-							{...safeFieldProps}
-							onChange={handleFileChange}
-							disabled={isUploading}
-							className="cursor-pointer"
-							data-testid="image-upload-input"
-						/>
-						{isUploading && (
-							<div className="absolute inset-0 flex items-center justify-center bg-background/80">
-								<Loader2 className="h-4 w-4 animate-spin" />
+					<div className="space-y-2">
+						<div className="relative">
+							<Input
+								type="file"
+								accept="image/*"
+								{...safeFieldProps}
+								onChange={handleFileChange}
+								disabled={isUploading}
+								className="cursor-pointer"
+								data-testid="image-upload-input"
+							/>
+							{isUploading && (
+								<div className="absolute inset-0 flex items-center justify-center bg-background/80">
+									<Loader2 className="h-4 w-4 animate-spin" />
+								</div>
+							)}
+						</div>
+						{ImagePickerTrigger && (
+							<div data-testid="image-picker-trigger">
+								<ImagePickerTrigger
+									onSelect={(url: string) => {
+										setPreviewUrl(url);
+										field.onChange(url);
+									}}
+								/>
 							</div>
 						)}
 					</div>

package/src/plugins/cms/client/overrides.ts

@@ -2,6 +2,18 @@ import type { ComponentType } from "react";
 import type { CMSLocalization } from "./localization";
 import type { AutoFormInputComponentProps } from "@workspace/ui/components/auto-form/types";
 
+/**
+ * Props for the overridable CMS image input field component.
+ */
+export interface CmsImageInputFieldProps {
+	/** Current image URL value */
+	value: string;
+	/** Called when the image URL changes */
+	onChange: (value: string) => void;
+	/** Whether the field is required */
+	isRequired?: boolean;
+}
+
 /**
  * Context passed to lifecycle hooks
  */
@@ -46,11 +58,54 @@ export interface CMSPluginOverrides {
 	>;
 
 	/**
-	 * Function used to upload an image and return its URL.
-	 * Used by the default "file" field component.
+	 * Function used to upload a new image file and return its URL.
+	 * Used by the default "file" field component when not selecting an existing
+	 * asset via `imagePicker` or `imageInputField`.
 	 */
 	uploadImage?: (file: File) => Promise<string>;
 
+	/**
+	 * Optional custom component for image fields (fieldType: "file").
+	 *
+	 * When provided it replaces the default file-upload input entirely.
+	 * The component receives `value` (current URL string) and `onChange` (setter).
+	 *
+	 * @example
+	 * ```tsx
+	 * imageInputField: ({ value, onChange }) =>
+	 *   value ? (
+	 *     <div>
+	 *       <img src={value} alt="Preview" />
+	 *       <MediaPicker trigger={<button>Change</button>} accept={["image/*"]}
+	 *         onSelect={(assets) => onChange(assets[0].url)} />
+	 *     </div>
+	 *   ) : (
+	 *     <MediaPicker trigger={<button>Browse media</button>} accept={["image/*"]}
+	 *       onSelect={(assets) => onChange(assets[0].url)} />
+	 *   )
+	 * ```
+	 */
+	imageInputField?: ComponentType<CmsImageInputFieldProps>;
+
+	/**
+	 * Optional trigger component for a media picker.
+	 * When provided, it is rendered inside the default "file" field component as a
+	 * "Browse media" option, letting users select a previously uploaded asset.
+	 * Receives `onSelect(url)` — the URL is set as the field value.
+	 *
+	 * @example
+	 * ```tsx
+	 * imagePicker: ({ onSelect }) => (
+	 *   <MediaPicker
+	 *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+	 *     accept={["image/*"]}
+	 *     onSelect={(assets) => onSelect(assets[0].url)}
+	 *   />
+	 * )
+	 * ```
+	 */
+	imagePicker?: ComponentType<{ onSelect: (url: string) => void }>;
+
 	/**
 	 * Custom field components for AutoForm fields.
 	 *

package/src/plugins/kanban/client/components/forms/board-form.tsx

@@ -50,7 +50,7 @@ export function BoardForm({ board, onClose, onSuccess }: BoardFormProps) {
 	};
 
 	return (
-		<form onSubmit={handleSubmit} className="space-y-4">
+		<form onSubmit={handleSubmit} className="space-y-4 overflow-x-hidden">
 			<div className="space-y-2">
 				<Label htmlFor="name">Name *</Label>
 				<Input

package/src/plugins/kanban/client/components/forms/task-form.tsx

@@ -14,7 +14,9 @@ import {
 } from "@workspace/ui/components/select";
 import { MinimalTiptapEditor } from "@workspace/ui/components/minimal-tiptap";
 import SearchSelect from "@workspace/ui/components/search-select";
+import { usePluginOverrides } from "@btst/stack/context";
 import { useTaskMutations, useSearchUsers } from "../../hooks/kanban-hooks";
+import type { KanbanPluginOverrides } from "../../overrides";
 import { PRIORITY_OPTIONS } from "../../../utils";
 import type {
 	SerializedColumn,
@@ -44,6 +46,8 @@ export function TaskForm({
 	onDelete,
 }: TaskFormProps) {
 	const isEditing = !!taskId;
+	const { uploadImage, imagePicker: imagePickerTrigger } =
+		usePluginOverrides<KanbanPluginOverrides>("kanban");
 	const {
 		createTask,
 		updateTask,
@@ -155,7 +159,7 @@ export function TaskForm({
 	};
 
 	return (
-		<form onSubmit={handleSubmit} className="space-y-4">
+		<form onSubmit={handleSubmit} className="space-y-4 overflow-x-hidden">
 			<div className="space-y-2">
 				<Label htmlFor="title">Title *</Label>
 				<Input
@@ -227,6 +231,8 @@ export function TaskForm({
 					output="markdown"
 					placeholder="Describe the task..."
 					className="min-h-[150px]"
+					uploader={uploadImage}
+					imagePickerTrigger={imagePickerTrigger}
 				/>
 			</div>
 

package/src/plugins/kanban/client/overrides.ts

@@ -73,6 +73,31 @@ export interface KanbanPluginOverrides {
 	 */
 	headers?: HeadersInit;
 
+	/**
+	 * Function used to upload a new image file from the task description editor
+	 * and return its URL. This is separate from `imagePicker`, which selects an
+	 * existing asset URL.
+	 */
+	uploadImage?: (file: File) => Promise<string>;
+
+	/**
+	 * Optional trigger component for a media picker.
+	 * When provided, it appears inside the image insertion dialog of the task description editor,
+	 * letting users browse and select previously uploaded assets.
+	 *
+	 * @example
+	 * ```tsx
+	 * imagePicker: ({ onSelect }) => (
+	 *   <MediaPicker
+	 *     trigger={<Button size="sm" variant="outline">Browse media</Button>}
+	 *     accept={["image/*"]}
+	 *     onSelect={(assets) => onSelect(assets[0].url)}
+	 *   />
+	 * )
+	 * ```
+	 */
+	imagePicker?: ComponentType<{ onSelect: (url: string) => void }>;
+
 	// ============ User Resolution (required for assignee features) ============
 
 	/**

package/src/plugins/media/__tests__/__stubs__/vercel-blob-server.ts

@@ -0,0 +1,9 @@
+/**
+ * Stub for @vercel/blob/server — used in tests only.
+ * The real module is an optional peer dependency.
+ */
+export async function handleUpload(_options: unknown): Promise<unknown> {
+	throw new Error(
+		"handleUpload is not available in the installed @vercel/blob version. Use a version that exports @vercel/blob/server.",
+	);
+}