@btst/stack 2.8.0 → 2.9.0

package/src/plugins/media/client/components/media-picker/utils.ts

@@ -0,0 +1,17 @@
+export function matchesAccept(mimeType: string, accept?: string[]) {
+	if (!accept || accept.length === 0) return true;
+	return accept.some((a) => {
+		if (a.endsWith("/*")) return mimeType.startsWith(a.slice(0, -1));
+		return mimeType === a;
+	});
+}
+
+export function isImage(mimeType: string) {
+	return mimeType.startsWith("image/");
+}
+
+export function formatBytes(bytes: number) {
+	if (bytes < 1024) return `${bytes} B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+	return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/src/plugins/media/client/components/pages/library-page.internal.tsx

@@ -0,0 +1,134 @@
+"use client";
+import { useState, useCallback, useRef } from "react";
+import { useDeleteAsset, useUploadAsset } from "../../hooks/use-media";
+import { Button } from "@workspace/ui/components/button";
+import { Upload, Loader2 } from "lucide-react";
+import { cn } from "@workspace/ui/lib/utils";
+import { toast } from "sonner";
+import { usePluginOverrides } from "@btst/stack/context";
+import type { MediaPluginOverrides } from "../../overrides";
+import { useRouteLifecycle } from "@workspace/ui/hooks/use-route-lifecycle";
+import { BrowseTab } from "../media-picker/browse-tab";
+import { FolderTree } from "../media-picker/folder-tree";
+
+export function LibraryPage() {
+	const overrides = usePluginOverrides<
+		MediaPluginOverrides,
+		Partial<MediaPluginOverrides>
+	>("media", {});
+
+	useRouteLifecycle({
+		routeName: "library",
+		context: {
+			path: "/media",
+			isSSR: typeof window === "undefined",
+		},
+		overrides,
+		beforeRenderHook: (overrides, context) => {
+			if (overrides.onBeforeLibraryPageRendered) {
+				return overrides.onBeforeLibraryPageRendered(context);
+			}
+			return true;
+		},
+	});
+
+	const [selectedFolder, setSelectedFolder] = useState<string | null>(null);
+	const [dragging, setDragging] = useState(false);
+	const fileInputRef = useRef<HTMLInputElement>(null);
+	const { mutateAsync: uploadAsset, isPending: isUploading } = useUploadAsset();
+	const { mutateAsync: deleteAsset } = useDeleteAsset();
+	const { apiBaseURL = "" } = overrides;
+
+	const handleUpload = useCallback(
+		async (files: FileList | File[]) => {
+			const arr = Array.from(files);
+			for (const file of arr) {
+				try {
+					await uploadAsset({ file, folderId: selectedFolder ?? undefined });
+					toast.success(`Uploaded ${file.name}`);
+				} catch (err) {
+					toast.error(err instanceof Error ? err.message : "Upload failed");
+				}
+			}
+		},
+		[selectedFolder, uploadAsset],
+	);
+
+	const handleDelete = async (id: string) => {
+		if (!confirm("Delete this asset?")) return;
+		try {
+			await deleteAsset(id);
+			toast.success("Deleted");
+		} catch (err) {
+			toast.error(err instanceof Error ? err.message : "Delete failed");
+		}
+	};
+
+	return (
+		<div className="flex h-[calc(100dvh-4rem)] flex-col overflow-hidden md:flex-row">
+			<div className="max-h-48 shrink-0 overflow-hidden border-b bg-muted/20 md:h-full md:max-h-none md:w-52 md:border-b-0 md:border-r">
+				<FolderTree selectedId={selectedFolder} onSelect={setSelectedFolder} />
+			</div>
+
+			<div
+				className={cn(
+					"relative flex flex-1 flex-col overflow-hidden border-t md:border-t-0",
+					dragging && "ring-2 ring-inset ring-ring",
+				)}
+				onDragOver={(e) => {
+					e.preventDefault();
+					setDragging(true);
+				}}
+				onDragLeave={() => setDragging(false)}
+				onDrop={(e) => {
+					e.preventDefault();
+					setDragging(false);
+					void handleUpload(e.dataTransfer.files);
+				}}
+			>
+				{/* Toolbar */}
+				<div className="flex flex-col gap-3 border-b px-4 py-3 sm:flex-row sm:items-center sm:justify-end">
+					<Button
+						size="sm"
+						onClick={() => fileInputRef.current?.click()}
+						disabled={isUploading}
+						className="w-full sm:w-auto"
+					>
+						{isUploading ? (
+							<Loader2 className="mr-2 size-3.5 animate-spin" />
+						) : (
+							<Upload className="mr-2 size-3.5" />
+						)}
+						Upload
+					</Button>
+					<input
+						ref={fileInputRef}
+						type="file"
+						multiple
+						className="hidden"
+						onChange={(e) => e.target.files && handleUpload(e.target.files)}
+					/>
+				</div>
+
+				{/* Drop overlay */}
+				{dragging && (
+					<div className="pointer-events-none absolute inset-0 z-10 flex items-center justify-center bg-background/80">
+						<div className="rounded-lg border-2 border-dashed border-ring p-8 text-center">
+							<Upload className="mx-auto mb-2 size-10 text-ring" />
+							<p className="font-medium">Drop files to upload</p>
+						</div>
+					</div>
+				)}
+
+				<div className="flex-1 min-h-0 p-3 sm:p-4">
+					<BrowseTab
+						folderId={selectedFolder}
+						onDelete={handleDelete}
+						apiBaseURL={apiBaseURL}
+						emptyMessage="No files yet. Drag & drop or click Upload."
+					/>
+				</div>
+			</div>
+		</div>
+	);
+}

package/src/plugins/media/client/components/pages/library-page.tsx

@@ -0,0 +1,42 @@
+"use client";
+import { lazy } from "react";
+import type { FallbackProps } from "react-error-boundary";
+import { usePluginOverrides } from "@btst/stack/context";
+import { ComposedRoute } from "@btst/stack/client/components";
+import type { MediaPluginOverrides } from "../../overrides";
+import { Loader2 } from "lucide-react";
+
+const LibraryPage = lazy(() =>
+	import("./library-page.internal").then((m) => ({ default: m.LibraryPage })),
+);
+
+function LibraryLoading() {
+	return (
+		<div className="flex h-96 items-center justify-center">
+			<Loader2 className="size-8 animate-spin text-muted-foreground" />
+		</div>
+	);
+}
+
+function LibraryError({ error }: FallbackProps) {
+	const message = error instanceof Error ? error.message : String(error);
+	return (
+		<div className="flex h-96 items-center justify-center p-8 text-destructive">
+			<p className="text-sm">{message}</p>
+		</div>
+	);
+}
+
+export function LibraryPageComponent() {
+	usePluginOverrides<MediaPluginOverrides>("media");
+	return (
+		<ComposedRoute
+			path="/media"
+			PageComponent={LibraryPage}
+			ErrorComponent={LibraryError}
+			LoadingComponent={LibraryLoading}
+			NotFoundComponent={() => null}
+			onError={(error) => console.error("[btst/media] Library error:", error)}
+		/>
+	);
+}

package/src/plugins/media/client/hooks/index.tsx

@@ -0,0 +1,9 @@
+export {
+	useAssets,
+	useFolders,
+	useUploadAsset,
+	useRegisterAsset,
+	useDeleteAsset,
+	useCreateFolder,
+	useDeleteFolder,
+} from "./use-media";

package/src/plugins/media/client/hooks/use-media.tsx

@@ -0,0 +1,289 @@
+"use client";
+import {
+	useInfiniteQuery,
+	useQuery,
+	useMutation,
+	useQueryClient,
+} from "@tanstack/react-query";
+import { usePluginOverrides } from "@btst/stack/context";
+import { createApiClient } from "@btst/stack/plugins/client";
+import type { MediaApiRouter } from "../../api/plugin";
+import type { MediaPluginOverrides } from "../overrides";
+import { createMediaQueryKeys } from "../../query-keys";
+import type { AssetListParams } from "../../api/getters";
+import type { SerializedAsset, SerializedFolder } from "../../types";
+import { uploadAsset } from "../upload";
+
+function useMediaConfig() {
+	return usePluginOverrides<MediaPluginOverrides>("media");
+}
+
+function useMediaApiClient() {
+	const { apiBaseURL, apiBasePath, headers } = useMediaConfig();
+	const client = createApiClient<MediaApiRouter>({
+		baseURL: apiBaseURL,
+		basePath: apiBasePath,
+	});
+	return { client, headers };
+}
+
+/**
+ * Infinite-scroll list of assets, optionally filtered by folder / MIME type / search.
+ */
+export function useAssets(params?: AssetListParams) {
+	const { client, headers } = useMediaApiClient();
+	const queries = createMediaQueryKeys(client, headers);
+	const { queryClient } = useMediaConfig();
+
+	const limit = params?.limit ?? 20;
+
+	return useInfiniteQuery(
+		{
+			...queries.mediaAssets.list(params),
+			initialPageParam: 0,
+			refetchOnMount: "always",
+			getNextPageParam: (
+				lastPage: {
+					items: SerializedAsset[];
+					total: number;
+					limit?: number;
+					offset?: number;
+				},
+				_allPages: any[],
+				lastPageParam: number,
+			) => {
+				const offset = (lastPage.offset ?? 0) + lastPage.items.length;
+				return offset < lastPage.total ? offset : undefined;
+			},
+		},
+		queryClient,
+	);
+}
+
+/**
+ * List of folders, optionally filtered by parentId.
+ * Pass `null` for root-level folders, `undefined` for all folders.
+ */
+export function useFolders(parentId?: string | null) {
+	const { client, headers } = useMediaApiClient();
+	const queries = createMediaQueryKeys(client, headers);
+	const { queryClient } = useMediaConfig();
+
+	return useQuery(
+		{
+			...queries.mediaFolders.list(parentId),
+		},
+		queryClient,
+	);
+}
+
+/**
+ * Upload an asset — adapter-aware. Handles direct, S3, and Vercel Blob flows.
+ */
+export function useUploadAsset() {
+	const {
+		apiBaseURL,
+		apiBasePath,
+		headers,
+		uploadMode = "direct",
+		imageCompression,
+		queryClient: qc,
+	} = useMediaConfig();
+	const reactQueryClient = useQueryClient(qc);
+
+	return useMutation(
+		{
+			mutationFn: async ({
+				file,
+				folderId,
+			}: {
+				file: File;
+				folderId?: string;
+			}): Promise<SerializedAsset> =>
+				uploadAsset(
+					{
+						apiBaseURL,
+						apiBasePath,
+						headers,
+						uploadMode,
+						imageCompression,
+					},
+					{ file, folderId },
+				),
+			onSuccess: () => {
+				reactQueryClient.invalidateQueries({ queryKey: ["mediaAssets"] });
+			},
+		},
+		qc,
+	);
+}
+
+/**
+ * Register an asset URL directly (for when the URL already exists).
+ */
+export function useRegisterAsset() {
+	const {
+		apiBaseURL,
+		apiBasePath,
+		headers,
+		queryClient: qc,
+	} = useMediaConfig();
+	const reactQueryClient = useQueryClient(qc);
+
+	return useMutation(
+		{
+			mutationFn: async (input: {
+				url: string;
+				filename: string;
+				mimeType?: string;
+				size?: number;
+				folderId?: string;
+			}): Promise<SerializedAsset> => {
+				const base = `${apiBaseURL}${apiBasePath}`;
+				const headersObj = new Headers(headers as HeadersInit | undefined);
+				const res = await fetch(`${base}/media/assets`, {
+					method: "POST",
+					headers: {
+						...Object.fromEntries(headersObj.entries()),
+						"Content-Type": "application/json",
+					},
+					body: JSON.stringify({
+						filename: input.filename,
+						originalName: input.filename,
+						mimeType: input.mimeType ?? "application/octet-stream",
+						size: input.size ?? 0,
+						url: input.url,
+						folderId: input.folderId,
+					}),
+				});
+				if (!res.ok) {
+					const err = await res
+						.json()
+						.catch(() => ({ message: res.statusText }));
+					throw new Error(err.message ?? "Failed to register asset");
+				}
+				return res.json();
+			},
+			onSuccess: () => {
+				reactQueryClient.invalidateQueries({ queryKey: ["mediaAssets"] });
+			},
+		},
+		qc,
+	);
+}
+
+/**
+ * Delete an asset by ID.
+ */
+export function useDeleteAsset() {
+	const {
+		apiBaseURL,
+		apiBasePath,
+		headers,
+		queryClient: qc,
+	} = useMediaConfig();
+	const reactQueryClient = useQueryClient(qc);
+
+	return useMutation(
+		{
+			mutationFn: async (id: string) => {
+				const base = `${apiBaseURL}${apiBasePath}`;
+				const headersObj = new Headers(headers as HeadersInit | undefined);
+				const res = await fetch(`${base}/media/assets/${id}`, {
+					method: "DELETE",
+					headers: headersObj,
+				});
+				if (!res.ok) {
+					const err = await res
+						.json()
+						.catch(() => ({ message: res.statusText }));
+					throw new Error(err.message ?? "Delete failed");
+				}
+			},
+			onSuccess: () => {
+				reactQueryClient.invalidateQueries({ queryKey: ["mediaAssets"] });
+			},
+		},
+		qc,
+	);
+}
+
+/**
+ * Create a new folder.
+ */
+export function useCreateFolder() {
+	const {
+		apiBaseURL,
+		apiBasePath,
+		headers,
+		queryClient: qc,
+	} = useMediaConfig();
+	const reactQueryClient = useQueryClient(qc);
+
+	return useMutation(
+		{
+			mutationFn: async (input: {
+				name: string;
+				parentId?: string;
+			}): Promise<SerializedFolder> => {
+				const base = `${apiBaseURL}${apiBasePath}`;
+				const headersObj = new Headers(headers as HeadersInit | undefined);
+				const res = await fetch(`${base}/media/folders`, {
+					method: "POST",
+					headers: {
+						...Object.fromEntries(headersObj.entries()),
+						"Content-Type": "application/json",
+					},
+					body: JSON.stringify(input),
+				});
+				if (!res.ok) {
+					const err = await res
+						.json()
+						.catch(() => ({ message: res.statusText }));
+					throw new Error(err.message ?? "Failed to create folder");
+				}
+				return res.json();
+			},
+			onSuccess: () => {
+				reactQueryClient.invalidateQueries({ queryKey: ["mediaFolders"] });
+			},
+		},
+		qc,
+	);
+}
+
+/**
+ * Delete a folder by ID.
+ */
+export function useDeleteFolder() {
+	const {
+		apiBaseURL,
+		apiBasePath,
+		headers,
+		queryClient: qc,
+	} = useMediaConfig();
+	const reactQueryClient = useQueryClient(qc);
+
+	return useMutation(
+		{
+			mutationFn: async (id: string) => {
+				const base = `${apiBaseURL}${apiBasePath}`;
+				const headersObj = new Headers(headers as HeadersInit | undefined);
+				const res = await fetch(`${base}/media/folders/${id}`, {
+					method: "DELETE",
+					headers: headersObj,
+				});
+				if (!res.ok) {
+					const err = await res
+						.json()
+						.catch(() => ({ message: res.statusText }));
+					throw new Error(err.message ?? "Failed to delete folder");
+				}
+			},
+			onSuccess: () => {
+				reactQueryClient.invalidateQueries({ queryKey: ["mediaFolders"] });
+			},
+		},
+		qc,
+	);
+}

package/src/plugins/media/client/index.ts

@@ -0,0 +1,4 @@
+export { mediaClientPlugin } from "./plugin";
+export type { MediaPluginOverrides, MediaUploadMode } from "./overrides";
+export { uploadAsset } from "./upload";
+export type { MediaUploadClientConfig, UploadAssetInput } from "./upload";

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

@@ -0,0 +1,127 @@
+import type { ComponentType } from "react";
+import type { QueryClient } from "@tanstack/react-query";
+import type { ImageCompressionOptions } from "./utils/image-compression";
+
+/**
+ * Upload mode — must match the storage adapter configured in mediaBackendPlugin.
+ * - `"direct"` — local filesystem adapter, files are uploaded via `POST /media/upload`
+ * - `"s3"` — AWS S3 / R2 / MinIO, the client fetches a presigned token then PUTs directly to S3
+ * - `"vercel-blob"` — Vercel Blob, uses the `@vercel/blob/client` SDK for direct upload
+ */
+export type MediaUploadMode = "direct" | "s3" | "vercel-blob";
+
+/**
+ * Overridable components and functions for the Media plugin.
+ *
+ * External consumers provide these when registering the media client plugin
+ * via the StackProvider overrides.
+ */
+export interface MediaPluginOverrides {
+	/**
+	 * Base URL for API calls (e.g., "http://localhost:3000").
+	 */
+	apiBaseURL: string;
+
+	/**
+	 * Path where the API is mounted (e.g., "/api/data").
+	 */
+	apiBasePath: string;
+
+	/**
+	 * React Query client — used by the MediaPicker to cache and fetch assets.
+	 */
+	queryClient: QueryClient;
+
+	/**
+	 * Upload mode — must match the storageAdapter configured in mediaBackendPlugin.
+	 * @default "direct"
+	 */
+	uploadMode?: MediaUploadMode;
+
+	/**
+	 * Optional headers to pass with API requests (e.g., for SSR auth).
+	 */
+	headers?: HeadersInit;
+
+	/**
+	 * Navigation function for programmatic navigation.
+	 */
+	navigate: (path: string) => void | Promise<void>;
+
+	/**
+	 * Link component for navigation within the media library page.
+	 */
+	Link?: ComponentType<React.ComponentProps<"a"> & Record<string, any>>;
+
+	/**
+	 * Image component for rendering asset thumbnails and previews.
+	 *
+	 * When provided, replaces the default `<img>` element in asset cards,
+	 * the media library grid, and the ImageInputField preview. Use this
+	 * to plug in Next.js `<Image>` for automatic optimisation.
+	 *
+	 * @example
+	 * ```tsx
+	 * Image: (props) => <NextImage {...props} />
+	 * ```
+	 */
+	Image?: ComponentType<
+		React.ImgHTMLAttributes<HTMLImageElement> & Record<string, any>
+	>;
+
+	/**
+	 * Client-side image compression applied before upload via the Canvas API.
+	 *
+	 * Images are scaled down to fit within `maxWidth` × `maxHeight` (preserving
+	 * aspect ratio) and re-encoded at `quality`. SVG and GIF files are always
+	 * passed through unchanged.
+	 *
+	 * Set to `false` to disable compression entirely.
+	 *
+	 * @default { maxWidth: 2048, maxHeight: 2048, quality: 0.85 }
+	 */
+	imageCompression?: ImageCompressionOptions | false;
+
+	// ============ Lifecycle Hooks ============
+
+	/**
+	 * Called when a media route is rendered.
+	 */
+	onRouteRender?: (
+		routeName: string,
+		context: MediaRouteContext,
+	) => void | Promise<void>;
+
+	/**
+	 * Called when a media route encounters an error.
+	 */
+	onRouteError?: (
+		routeName: string,
+		error: Error,
+		context: MediaRouteContext,
+	) => void | Promise<void>;
+
+	/**
+	 * Called before the media library page is rendered.
+	 * Return `false` to prevent rendering (e.g., redirect unauthenticated users).
+	 *
+	 * @example
+	 * ```ts
+	 * media: {
+	 *   onBeforeLibraryPageRendered: (context) => !!currentUser?.isAdmin,
+	 *   onRouteError: (routeName, error, context) => navigate("/login"),
+	 * }
+	 * ```
+	 */
+	onBeforeLibraryPageRendered?: (context: MediaRouteContext) => boolean;
+}
+
+export interface MediaRouteContext {
+	/** Current route path */
+	path: string;
+	/** Route parameters */
+	params?: Record<string, string>;
+	/** Whether rendering on server (true) or client (false) */
+	isSSR: boolean;
+	[key: string]: unknown;
+}