@btst/stack 2.12.2 → 3.0.0-rc.1

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

@@ -1,22 +1,29 @@
 "use client";
-import { useState, useCallback, useRef } from "react";
+import { useState, useCallback, useEffect, 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 {
+	CanAccess,
+	useCan,
+	useNotify,
+	usePluginOverrides,
+	useTranslate,
+} from "@btst/stack/context";
+import { useListState, type ListStateSchema } from "@btst/stack/client";
 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 t = useTranslate();
+	const notify = useNotify();
 	const overrides = usePluginOverrides<
 		MediaPluginOverrides,
 		Partial<MediaPluginOverrides>
 	>("media", {});
-
 	useRouteLifecycle({
 		routeName: "library",
 		context: {
@@ -24,43 +31,80 @@ export function LibraryPage() {
 			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 [{ folder, q: search }, setListState] = useListState("media-library", {
+		folder: { type: "string", default: "" },
+		q: { type: "string", default: "", history: "replace" },
+	} as const satisfies ListStateSchema);
+	const selectedFolder = folder || null;
+	const [searchInput, setSearchInput] = useState(search);
+	const lastSyncedSearch = useRef(search);
+
+	useEffect(() => {
+		if (search !== lastSyncedSearch.current) {
+			lastSyncedSearch.current = search;
+			setSearchInput(search);
+		}
+	}, [search]);
+
+	useEffect(() => {
+		if (searchInput === search) return;
+		const timeout = setTimeout(() => {
+			lastSyncedSearch.current = searchInput;
+			setListState({ q: searchInput });
+		}, 300);
+		return () => clearTimeout(timeout);
+	}, [searchInput, search, setListState]);
+
+	const setSelectedFolder = useCallback(
+		(id: string | null) => setListState({ folder: id ?? "" }),
+		[setListState],
+	);
 	const [dragging, setDragging] = useState(false);
 	const fileInputRef = useRef<HTMLInputElement>(null);
 	const { mutateAsync: uploadAsset, isPending: isUploading } = useUploadAsset();
 	const { mutateAsync: deleteAsset } = useDeleteAsset();
-	const { apiBaseURL = "" } = overrides;
+	const { can: canCreateAsset } = useCan({
+		resource: "media:asset",
+		action: "create",
+	});
 
 	const handleUpload = useCallback(
 		async (files: FileList | File[]) => {
+			if (!canCreateAsset) return;
 			const arr = Array.from(files);
 			for (const file of arr) {
 				try {
 					await uploadAsset({ file, folderId: selectedFolder ?? undefined });
-					toast.success(`Uploaded ${file.name}`);
+					notify.success(
+						t("media.toasts.uploadSuccess", "Uploaded {{filename}}", {
+							filename: file.name,
+						}),
+					);
 				} catch (err) {
-					toast.error(err instanceof Error ? err.message : "Upload failed");
+					notify.error(
+						err instanceof Error
+							? err.message
+							: t("media.toasts.uploadError", "Upload failed"),
+					);
 				}
 			}
 		},
-		[selectedFolder, uploadAsset],
+		[canCreateAsset, notify, selectedFolder, t, uploadAsset],
 	);
 
 	const handleDelete = async (id: string) => {
-		if (!confirm("Delete this asset?")) return;
+		if (!confirm(t("media.assets.deleteConfirm", "Delete this asset?"))) return;
 		try {
 			await deleteAsset(id);
-			toast.success("Deleted");
+			notify.success(t("media.toasts.deleteSuccess", "Asset deleted"));
 		} catch (err) {
-			toast.error(err instanceof Error ? err.message : "Delete failed");
+			notify.error(
+				err instanceof Error
+					? err.message
+					: t("media.toasts.deleteError", "Delete failed"),
+			);
 		}
 	};
 
@@ -76,11 +120,13 @@ export function LibraryPage() {
 					dragging && "ring-2 ring-inset ring-ring",
 				)}
 				onDragOver={(e) => {
+					if (!canCreateAsset) return;
 					e.preventDefault();
 					setDragging(true);
 				}}
 				onDragLeave={() => setDragging(false)}
 				onDrop={(e) => {
+					if (!canCreateAsset) return;
 					e.preventDefault();
 					setDragging(false);
 					void handleUpload(e.dataTransfer.files);
@@ -88,34 +134,38 @@ export function LibraryPage() {
 			>
 				{/* 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)}
-					/>
+					<CanAccess resource="media:asset" action="create">
+						<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" />
+							)}
+							{t("media.actions.upload", "Upload")}
+						</Button>
+						<input
+							ref={fileInputRef}
+							type="file"
+							multiple
+							className="hidden"
+							onChange={(e) => e.target.files && handleUpload(e.target.files)}
+						/>
+					</CanAccess>
 				</div>
 
 				{/* Drop overlay */}
-				{dragging && (
+				{dragging && canCreateAsset && (
 					<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>
+							<p className="font-medium">
+								{t("media.upload.dropFiles", "Drop files to upload")}
+							</p>
 						</div>
 					</div>
 				)}
@@ -123,9 +173,14 @@ export function LibraryPage() {
 				<div className="flex-1 min-h-0 p-3 sm:p-4">
 					<BrowseTab
 						folderId={selectedFolder}
+						search={searchInput}
+						searchQuery={search}
+						onSearchChange={setSearchInput}
 						onDelete={handleDelete}
-						apiBaseURL={apiBaseURL}
-						emptyMessage="No files yet. Drag & drop or click Upload."
+						emptyMessage={t(
+							"media.assets.emptyLibrary",
+							"No files yet. Drag & drop or click Upload.",
+						)}
 					/>
 				</div>
 			</div>

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

@@ -32,6 +32,7 @@ export function LibraryPageComponent() {
 	return (
 		<ComposedRoute
 			path="/media"
+			permission={{ resource: "media:asset", action: "read" }}
 			PageComponent={LibraryPage}
 			ErrorComponent={LibraryError}
 			LoadingComponent={LibraryLoading}

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

@@ -6,4 +6,12 @@ export {
 	useDeleteAsset,
 	useCreateFolder,
 	useDeleteFolder,
+	useRegisterAssetForm,
+	useCreateFolderForm,
+} from "./use-media";
+export type {
+	RegisterAssetFormValues,
+	UseRegisterAssetFormOptions,
+	CreateFolderFormValues,
+	UseCreateFolderFormOptions,
 } from "./use-media";

package/src/plugins/media/client/hooks/media-resource.ts

@@ -0,0 +1,10 @@
+"use client";
+
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import { mediaResources } from "../../query-keys";
+
+/** Factory-generated hooks shared by the public Media hook wrappers. */
+export const media = createResource({
+	plugin: "media",
+	resources: mediaResources,
+});

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

@@ -1,289 +1,165 @@
 "use client";
+
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type { ResourceFormResult } from "@btst/stack/plugins/client/hooks";
 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";
+	usePluginOverrides,
+	useStack,
+	useTranslate,
+} from "@btst/stack/context";
 import type { AssetListParams } from "../../api/getters";
+import type { RegisterAssetInput } from "../../query-keys";
 import type { SerializedAsset, SerializedFolder } from "../../types";
+import type { MediaPluginOverrides } from "../overrides";
 import { uploadAsset } from "../upload";
+import { media } from "./media-resource";
 
-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, or search. */
+export function useAssets(params: AssetListParams = {}) {
+	return media.mediaAssets.list.useInfinite([params]);
 }
 
-/**
- * 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.
- */
+/** Pass `null` for root-level folders and `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,
-	);
+	return media.mediaFolders.list.use([parentId]);
 }
 
 /**
- * Upload an asset — adapter-aware. Handles direct, S3, and Vercel Blob flows.
+ * Upload an asset through the configured direct, S3, or Vercel Blob transport.
+ * This remains custom because the resource factory models JSON requests only.
  */
 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"] });
-			},
+	} = usePluginOverrides<MediaPluginOverrides>("media");
+	const { api } = useStack();
+	// Resource-generated asset queries use the nearest QueryClientProvider.
+	// Keep the custom upload transport on that same cache.
+	const queryClient = useQueryClient();
+
+	return useMutation({
+		mutationFn: async ({
+			file,
+			folderId,
+		}: {
+			file: File;
+			folderId?: string;
+		}): Promise<SerializedAsset> =>
+			uploadAsset(
+				{
+					apiBaseURL: api?.baseURL ?? "",
+					apiBasePath: api?.basePath ?? "",
+					headers,
+					uploadMode,
+					imageCompression,
+				},
+				{ file, folderId },
+			),
+		onSuccess: async () => {
+			await queryClient.invalidateQueries({
+				queryKey: ["mediaAssets", "list"],
+				// Browse unmounts while the Upload tab is active, and resource
+				// queries intentionally disable refetch-on-mount. Refresh inactive
+				// list variants so the uploaded asset is present when Browse remounts.
+				refetchType: "all",
+			});
 		},
-		qc,
-	);
+	});
 }
 
-/**
- * Register an asset URL directly (for when the URL already exists).
- */
+/** Register an already-hosted asset URL. */
 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,
-	);
+	return media.mediaAssets.create.use();
 }
 
-/**
- * Delete an asset by ID.
- */
+/** 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,
-	);
+	return media.mediaAssets.delete.use();
 }
 
-/**
- * Create a new folder.
- */
+/** 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,
-	);
+	return media.mediaFolders.create.use();
 }
 
-/**
- * Delete a folder by ID.
- */
+/** Delete a folder by ID. */
 export function useDeleteFolder() {
-	const {
-		apiBaseURL,
-		apiBasePath,
-		headers,
-		queryClient: qc,
-	} = useMediaConfig();
-	const reactQueryClient = useQueryClient(qc);
+	return media.mediaFolders.delete.use();
+}
 
-	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,
-	);
+export interface RegisterAssetFormValues {
+	url: string;
+}
+
+export interface UseRegisterAssetFormOptions {
+	folderId?: string;
+	onSuccess?: (asset: SerializedAsset) => void | Promise<void>;
+}
+
+function filenameFromUrl(url: string): string {
+	try {
+		const filename = new URL(url).pathname.split("/").filter(Boolean).pop();
+		return filename ? decodeURIComponent(filename) : "asset";
+	} catch {
+		return "asset";
+	}
+}
+
+/** Form lifecycle for registering a hosted asset URL. */
+export function useRegisterAssetForm(
+	options: UseRegisterAssetFormOptions = {},
+): ResourceFormResult<RegisterAssetFormValues, null, SerializedAsset> {
+	const t = useTranslate();
+	return media.mediaAssets.useForm<
+		RegisterAssetFormValues,
+		SerializedAsset,
+		null
+	>({
+		action: "create",
+		defaults: { url: "" },
+		toCreateVars: (values): RegisterAssetInput => ({
+			url: values.url.trim(),
+			filename: filenameFromUrl(values.url.trim()),
+			folderId: options.folderId,
+		}),
+		successMessage: t("media.toasts.registerSuccess", "Asset added"),
+		errorMessage: (error) =>
+			error.message || t("media.toasts.registerError", "Failed to add asset"),
+		onSuccess: options.onSuccess,
+	});
+}
+
+export interface CreateFolderFormValues {
+	name: string;
+}
+
+export interface UseCreateFolderFormOptions {
+	parentId?: string;
+	onSuccess?: (folder: SerializedFolder) => void | Promise<void>;
+}
+
+/** Form lifecycle for creating a media folder. */
+export function useCreateFolderForm(
+	options: UseCreateFolderFormOptions = {},
+): ResourceFormResult<CreateFolderFormValues, null, SerializedFolder> {
+	const t = useTranslate();
+	return media.mediaFolders.useForm<
+		CreateFolderFormValues,
+		SerializedFolder,
+		null
+	>({
+		action: "create",
+		defaults: { name: "" },
+		toCreateVars: (values) => ({
+			name: values.name.trim(),
+			parentId: options.parentId,
+		}),
+		successMessage: t("media.toasts.folderCreateSuccess", "Folder created"),
+		errorMessage: (error) =>
+			error.message ||
+			t("media.toasts.folderCreateError", "Failed to create folder"),
+		onSuccess: options.onSuccess,
+	});
 }