@btst/stack 2.8.0 → 2.9.0

package/src/plugins/media/api/query-key-defs.ts

@@ -0,0 +1,41 @@
+/**
+ * Internal query key constants for the media plugin.
+ * Shared between query-keys.ts (HTTP path) and any SSR/SSG prefetching
+ * to prevent key drift between client and server.
+ */
+
+import type { AssetListParams } from "./getters";
+
+/**
+ * Discriminator for the asset list cache key.
+ */
+export interface AssetListDiscriminator {
+	folderId: string | undefined;
+	mimeType: string | undefined;
+	query: string | undefined;
+	limit: number | undefined;
+	offset: number | undefined;
+}
+
+export function assetListDiscriminator(
+	params?: AssetListParams,
+): AssetListDiscriminator {
+	return {
+		folderId: params?.folderId,
+		mimeType: params?.mimeType,
+		query: params?.query,
+		limit: params?.limit,
+		offset: params?.offset,
+	};
+}
+
+/** Full query key builders — use these with `queryClient.setQueryData()`. */
+export const MEDIA_QUERY_KEYS = {
+	assetsList: (params?: AssetListParams) =>
+		["media", "assets", "list", assetListDiscriminator(params)] as const,
+
+	assetDetail: (id: string) => ["media", "assets", "detail", id] as const,
+
+	foldersList: (parentId?: string | null) =>
+		["media", "folders", "list", parentId ?? "root"] as const,
+};

package/src/plugins/media/api/serializers.ts

@@ -0,0 +1,28 @@
+import type {
+	Asset,
+	Folder,
+	SerializedAsset,
+	SerializedFolder,
+} from "../types";
+
+/**
+ * Serialize an Asset for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeAsset(asset: Asset): SerializedAsset {
+	return {
+		...asset,
+		createdAt: asset.createdAt.toISOString(),
+	};
+}
+
+/**
+ * Serialize a Folder for SSR/SSG use (convert dates to strings).
+ * Pure function — no DB access, no hooks.
+ */
+export function serializeFolder(folder: Folder): SerializedFolder {
+	return {
+		...folder,
+		createdAt: folder.createdAt.toISOString(),
+	};
+}

package/src/plugins/media/api/storage-adapter.ts

@@ -0,0 +1,139 @@
+/**
+ * Options provided to storage adapters when initiating an upload.
+ */
+export interface UploadOptions {
+	filename: string;
+	mimeType: string;
+	size: number;
+	folderId?: string;
+}
+
+/**
+ * Local storage adapter — backend receives and stores file bytes directly.
+ * Suitable for development and self-hosted deployments.
+ */
+export interface DirectStorageAdapter {
+	readonly type: "local";
+	/**
+	 * Store the file buffer and return the public URL.
+	 */
+	upload(buffer: Buffer, options: UploadOptions): Promise<{ url: string }>;
+	/**
+	 * Remove the stored file given its public URL.
+	 */
+	delete(url: string): Promise<void>;
+}
+
+/**
+ * Token returned by the S3 adapter.
+ * The client performs a `PUT` to `payload.uploadUrl` with the file body,
+ * then saves `payload.publicUrl` as the asset URL.
+ */
+export interface S3UploadToken {
+	type: "presigned-url";
+	payload: {
+		uploadUrl: string;
+		publicUrl: string;
+		key: string;
+		method: "PUT";
+		headers: Record<string, string>;
+	};
+}
+
+/**
+ * S3 storage adapter — server issues a short-lived presigned PUT URL;
+ * the browser uploads directly to S3 (or R2 / MinIO).
+ */
+export interface S3StorageAdapter {
+	readonly type: "s3";
+	/**
+	 * The public base URL prefix for all assets in this bucket
+	 * (e.g. `"https://assets.example.com"`). Used by the plugin to
+	 * automatically validate client-supplied URLs when no explicit
+	 * `allowedUrlPrefixes` are configured.
+	 */
+	readonly urlPrefix: string;
+	/**
+	 * Generate a presigned PUT URL for direct client upload.
+	 */
+	generateUploadToken(options: UploadOptions): Promise<S3UploadToken>;
+	/**
+	 * Remove the stored object given its public URL.
+	 */
+	delete(url: string): Promise<void>;
+}
+
+/**
+ * Options returned from onBeforeGenerateToken and passed to Vercel Blob's handleUpload.
+ */
+export interface VercelBlobTokenOptions {
+	addRandomSuffix?: boolean;
+	allowedContentTypes?: string[];
+	maximumSizeInBytes?: number;
+}
+
+/**
+ * Callbacks provided to the Vercel Blob adapter when handling a request.
+ */
+export interface VercelBlobHandlerCallbacks {
+	/**
+	 * Called before a client token is generated.
+	 * Throw to reject the upload (auth gate).
+	 * Return options to enforce allowedContentTypes and maximumSizeInBytes at the edge.
+	 */
+	onBeforeGenerateToken?: (
+		pathname: string,
+		clientPayload: string | null,
+	) => Promise<VercelBlobTokenOptions | void> | VercelBlobTokenOptions | void;
+}
+
+/**
+ * Vercel Blob storage adapter — uses the `@vercel/blob/server` `handleUpload`
+ * protocol. The same endpoint handles both token generation and upload
+ * completion notifications from Vercel's servers.
+ */
+export interface VercelBlobStorageAdapter {
+	readonly type: "vercel-blob";
+	/**
+	 * Hostname suffix that all Vercel Blob public URLs end with.
+	 * Used by the plugin to automatically validate client-supplied URLs.
+	 * Always `".public.blob.vercel-storage.com"`.
+	 */
+	readonly urlHostnameSuffix: string;
+	/**
+	 * Process a raw request from `@vercel/blob/client`'s `upload()` or from
+	 * Vercel Blob's upload-completion webhook. Returns a JSON-serialisable object
+	 * that should be sent back as the response body.
+	 */
+	handleRequest(
+		request: Request,
+		callbacks: VercelBlobHandlerCallbacks,
+	): Promise<unknown>;
+	/**
+	 * Remove the stored blob given its public URL.
+	 */
+	delete(url: string): Promise<void>;
+}
+
+export type StorageAdapter =
+	| DirectStorageAdapter
+	| S3StorageAdapter
+	| VercelBlobStorageAdapter;
+
+export function isDirectAdapter(
+	adapter: StorageAdapter,
+): adapter is DirectStorageAdapter {
+	return adapter.type === "local";
+}
+
+export function isS3Adapter(
+	adapter: StorageAdapter,
+): adapter is S3StorageAdapter {
+	return adapter.type === "s3";
+}
+
+export function isVercelBlobAdapter(
+	adapter: StorageAdapter,
+): adapter is VercelBlobStorageAdapter {
+	return adapter.type === "vercel-blob";
+}

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

@@ -0,0 +1,6 @@
+export {
+	MediaPicker,
+	ImageInputField,
+	type MediaPickerProps,
+} from "./media-picker";
+export { LibraryPageComponent } from "./pages/library-page";

package/src/plugins/media/client/components/media-picker/asset-card.tsx

@@ -0,0 +1,150 @@
+import { useDeleteAsset } from "../../hooks/use-media";
+import type { SerializedAsset } from "../../../types";
+import { cn } from "@workspace/ui/lib/utils";
+import { File, Check, Copy, Trash2 } from "lucide-react";
+import { isImage, formatBytes } from "./utils";
+import { usePluginOverrides } from "@btst/stack/context";
+import type { MediaPluginOverrides } from "../../overrides";
+import { AssetPreviewButton } from "./asset-preview-button";
+import { toast } from "sonner";
+
+export function AssetCard({
+	asset,
+	onToggle,
+	selected = false,
+	onDelete,
+	apiBaseURL,
+}: {
+	asset: SerializedAsset;
+	selected?: boolean;
+	onToggle?: () => void;
+	onDelete?: (id: string) => void | Promise<void>;
+	apiBaseURL?: string;
+}) {
+	const { mutateAsync: deleteAsset } = useDeleteAsset();
+	const { Image: ImageComponent } = usePluginOverrides<
+		MediaPluginOverrides,
+		Partial<MediaPluginOverrides>
+	>("media", {});
+	const imageAsset = isImage(asset.mimeType);
+	const selectable = typeof onToggle === "function";
+
+	const copyUrl = () => {
+		let fullUrl: string;
+		try {
+			fullUrl = new URL(asset.url, apiBaseURL).href;
+		} catch {
+			fullUrl = asset.url;
+		}
+		navigator.clipboard
+			.writeText(fullUrl)
+			.then(() => toast.success("URL copied"));
+	};
+
+	const handleDelete = () => {
+		if (onDelete) {
+			return onDelete(asset.id);
+		}
+
+		if (confirm(`Delete "${asset.originalName}"?`)) {
+			return deleteAsset(asset.id).catch(console.error);
+		}
+	};
+
+	return (
+		<div
+			role={selectable ? "button" : undefined}
+			tabIndex={selectable ? 0 : undefined}
+			data-testid="media-asset-item"
+			onClick={onToggle}
+			onKeyDown={(e) => {
+				if (selectable && (e.key === "Enter" || e.key === " ")) {
+					e.preventDefault();
+					onToggle();
+				}
+			}}
+			className={cn(
+				"group relative cursor-pointer rounded-md border bg-muted/30 p-1 transition-all hover:border-ring hover:shadow-sm",
+				!selectable && "cursor-default",
+				selected && "border-ring ring-1 ring-ring",
+			)}
+		>
+			{/* Thumbnail */}
+			<div className="flex h-28 items-center justify-center overflow-hidden rounded bg-muted">
+				{imageAsset ? (
+					ImageComponent ? (
+						<ImageComponent
+							src={asset.url}
+							alt={asset.alt || asset.originalName}
+							className="h-full w-full object-cover"
+							width={160}
+							height={80}
+						/>
+					) : (
+						<img
+							src={asset.url}
+							alt={asset.alt || asset.originalName}
+							className="h-full w-full object-cover"
+							loading="lazy"
+						/>
+					)
+				) : (
+					<File className="size-8 text-muted-foreground" />
+				)}
+			</div>
+
+			{/* Name + size */}
+			<div className="mt-1 px-0.5">
+				<p
+					className="truncate text-xs font-medium leading-tight"
+					title={asset.originalName}
+				>
+					{asset.originalName}
+				</p>
+				<p className="text-[10px] text-muted-foreground">
+					{formatBytes(asset.size)}
+				</p>
+			</div>
+
+			{/* Selection indicator */}
+			{selected && (
+				<div className="absolute right-1 top-1 rounded-full bg-primary p-0.5 text-primary-foreground">
+					<Check className="size-3" />
+				</div>
+			)}
+
+			<div className="absolute right-1 top-1 hidden gap-1 group-hover:flex">
+				{apiBaseURL ? (
+					<button
+						type="button"
+						title="Copy URL"
+						onClick={(e) => {
+							e.stopPropagation();
+							copyUrl();
+						}}
+						className="rounded bg-background/80 p-0.5 shadow hover:bg-background"
+					>
+						<Copy className="size-3" />
+					</button>
+				) : null}
+				{imageAsset ? (
+					<AssetPreviewButton
+						asset={asset}
+						className="rounded bg-background/80 p-0.5 shadow hover:bg-background"
+					/>
+				) : null}
+				<button
+					type="button"
+					title="Delete"
+					onClick={(e) => {
+						e.stopPropagation();
+						void handleDelete();
+					}}
+					className="rounded bg-destructive/80 p-0.5 text-white hover:bg-destructive"
+				>
+					<Trash2 className="size-3" />
+				</button>
+			</div>
+		</div>
+	);
+}

package/src/plugins/media/client/components/media-picker/asset-preview-button.tsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { useState } from "react";
+import {
+	Dialog,
+	DialogClose,
+	DialogContent,
+	DialogHeader,
+	DialogTitle,
+} from "@workspace/ui/components/dialog";
+import { Eye, X } from "lucide-react";
+import type { SerializedAsset } from "../../../types";
+
+export function AssetPreviewButton({
+	asset,
+	className,
+}: {
+	asset: SerializedAsset;
+	className: string;
+}) {
+	const [open, setOpen] = useState(false);
+
+	return (
+		<>
+			<button
+				type="button"
+				title="Preview"
+				aria-label={`Preview ${asset.originalName}`}
+				onClick={(event) => {
+					event.stopPropagation();
+					setOpen(true);
+				}}
+				className={className}
+			>
+				<Eye className="size-3" />
+			</button>
+
+			<Dialog open={open} onOpenChange={setOpen}>
+				<DialogContent
+					showCloseButton={false}
+					className="h-screen w-screen max-w-none border-0 bg-black/95 p-4 shadow-none sm:max-w-none sm:rounded-none sm:p-6"
+				>
+					<DialogHeader className="sr-only">
+						<DialogTitle>{asset.alt || asset.originalName}</DialogTitle>
+					</DialogHeader>
+
+					<DialogClose
+						className="absolute right-4 top-4 z-10 rounded bg-black/60 p-2 text-white transition hover:bg-black/80"
+						aria-label="Close preview"
+					>
+						<X className="size-4" />
+					</DialogClose>
+
+					<div className="h-full w-full overflow-auto">
+						<div className="flex min-h-full w-full items-start justify-center">
+							<img
+								src={asset.url}
+								alt={asset.alt || asset.originalName}
+								className="block h-auto w-auto max-w-none"
+							/>
+						</div>
+					</div>
+				</DialogContent>
+			</Dialog>
+		</>
+	);
+}

package/src/plugins/media/client/components/media-picker/browse-tab.tsx

@@ -0,0 +1,116 @@
+import { useState, useRef } from "react";
+import { useAssets } from "../../hooks/use-media";
+import type { SerializedAsset } from "../../../types";
+import { Input } from "@workspace/ui/components/input";
+import { Button } from "@workspace/ui/components/button";
+import { Loader2, Search, X, Image } from "lucide-react";
+import { AssetCard } from "./asset-card";
+import { matchesAccept } from "./utils";
+
+export function BrowseTab({
+	folderId,
+	selected = [],
+	accept,
+	onToggle,
+	onDelete,
+	apiBaseURL,
+	emptyMessage = "No files found",
+}: {
+	folderId: string | null;
+	selected?: SerializedAsset[];
+	accept?: string[];
+	onToggle?: (asset: SerializedAsset) => void;
+	onDelete?: (id: string) => void | Promise<void>;
+	apiBaseURL?: string;
+	emptyMessage?: string;
+}) {
+	const [search, setSearch] = useState("");
+	const [debouncedSearch, setDebouncedSearch] = useState("");
+	const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+	const selectable = typeof onToggle === "function";
+
+	const handleSearch = (v: string) => {
+		setSearch(v);
+		if (debounceRef.current) clearTimeout(debounceRef.current);
+		debounceRef.current = setTimeout(() => setDebouncedSearch(v), 300);
+	};
+
+	const { data, fetchNextPage, hasNextPage, isFetchingNextPage, isLoading } =
+		useAssets({
+			folderId: folderId ?? undefined,
+			query: debouncedSearch || undefined,
+			limit: 40,
+		});
+
+	const allAssets = data?.pages.flatMap((p) => p.items) ?? [];
+	const filtered = accept
+		? allAssets.filter((a) => matchesAccept(a.mimeType, accept))
+		: allAssets;
+
+	return (
+		<div className="flex h-full min-h-0 flex-col gap-2">
+			<div className="relative">
+				<Search className="absolute left-2 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+				<Input
+					value={search}
+					onChange={(e) => handleSearch(e.target.value)}
+					placeholder="Search files…"
+					className="h-8 pl-7 text-sm"
+				/>
+				{search && (
+					<button
+						type="button"
+						onClick={() => {
+							setSearch("");
+							setDebouncedSearch("");
+						}}
+						className="absolute right-2 top-1/2 -translate-y-1/2 text-muted-foreground hover:text-foreground"
+					>
+						<X className="size-3.5" />
+					</button>
+				)}
+			</div>
+
+			{isLoading ? (
+				<div className="flex flex-1 items-center justify-center">
+					<Loader2 className="size-6 animate-spin text-muted-foreground" />
+				</div>
+			) : filtered.length === 0 ? (
+				<div className="flex flex-1 flex-col items-center justify-center gap-2 text-sm text-muted-foreground">
+					<Image className="size-8" />
+					<p>{emptyMessage}</p>
+				</div>
+			) : (
+				<div className="flex-1 overflow-y-auto overscroll-contain">
+					<div className="grid grid-cols-2 gap-2 pb-2 sm:grid-cols-3 lg:grid-cols-4 xl:grid-cols-5">
+						{filtered.map((asset) => (
+							<AssetCard
+								key={asset.id}
+								asset={asset}
+								selected={selected.some((s) => s.id === asset.id)}
+								onToggle={selectable ? () => onToggle(asset) : undefined}
+								onDelete={onDelete}
+								apiBaseURL={apiBaseURL}
+							/>
+						))}
+					</div>
+					{hasNextPage && (
+						<div className="flex justify-center py-2">
+							<Button
+								variant="ghost"
+								size="sm"
+								onClick={() => fetchNextPage()}
+								disabled={isFetchingNextPage}
+							>
+								{isFetchingNextPage ? (
+									<Loader2 className="mr-1 size-3 animate-spin" />
+								) : null}
+								Load more
+							</Button>
+						</div>
+					)}
+				</div>
+			)}
+		</div>
+	);
+}