@btst/stack 2.12.2 → 3.0.0-rc.2

package/src/plugins/kanban/client/hooks/kanban-hooks.tsx

@@ -1,231 +1,68 @@
 "use client";
 
-import {
-	useMutation,
-	useQuery,
-	useQueryClient,
-	useSuspenseQuery,
-} from "@tanstack/react-query";
-import { createApiClient } from "@btst/stack/plugins/client";
+import { useQuery } from "@tanstack/react-query";
 import { usePluginOverrides } from "@btst/stack/context";
-import type { KanbanApiRouter } from "../../api";
-import { createKanbanQueryKeys } from "../../query-keys";
+import type {
+	ResourceFormConfig,
+	ResourceFormResult,
+} from "@btst/stack/plugins/client/hooks";
 import type { KanbanPluginOverrides, KanbanUser } from "../overrides";
 import type {
 	SerializedBoard,
-	SerializedBoardWithColumns,
 	SerializedColumn,
 	SerializedTask,
-	Priority,
 } from "../../types";
-
-// ============ Error Handling ============
-
-// Type guard for better-call error responses
-function isErrorResponse(
-	response: unknown,
-): response is { error: unknown; data?: never } {
-	return (
-		typeof response === "object" &&
-		response !== null &&
-		"error" in response &&
-		response.error !== null &&
-		response.error !== undefined
-	);
-}
-
-// Helper to convert error to a proper Error object with meaningful message
-function toError(error: unknown): Error {
-	if (error instanceof Error) {
-		return error;
-	}
-
-	if (typeof error === "object" && error !== null) {
-		const errorObj = error as Record<string, unknown>;
-		const message =
-			(typeof errorObj.message === "string" ? errorObj.message : null) ||
-			(typeof errorObj.error === "string" ? errorObj.error : null) ||
-			JSON.stringify(error);
-
-		const err = new Error(message);
-		Object.assign(err, error);
-		return err;
-	}
-
-	return new Error(String(error));
-}
-
-// ============ API Client Hook ============
-
-function useKanbanClient() {
-	const { apiBaseURL, apiBasePath, headers } =
-		usePluginOverrides<KanbanPluginOverrides>("kanban");
-
-	const client = createApiClient<KanbanApiRouter>({
-		baseURL: apiBaseURL,
-		basePath: apiBasePath,
-	});
-
-	return { client, headers };
-}
+import { kanban } from "./kanban-resource";
 
 // ============ Board Hooks ============
 
-/**
- * Hook to fetch list of boards
- */
+/** Hook to fetch a list of boards. */
 export function useBoards(params?: {
 	slug?: string;
 	ownerId?: string;
 	organizationId?: string;
 }) {
-	const { client, headers } = useKanbanClient();
-	const queries = createKanbanQueryKeys(client, headers);
-
-	return useQuery({
-		...queries.boards.list(params),
-		staleTime: 30_000,
-		refetchOnWindowFocus: true,
-	});
+	return kanban.boards.list.use([params]);
 }
 
-/**
- * Hook to fetch list of boards with suspense
- */
+/** Suspense variant of useBoards. */
 export function useSuspenseBoards(params?: {
 	slug?: string;
 	ownerId?: string;
 	organizationId?: string;
 }) {
-	const { client, headers } = useKanbanClient();
-	const queries = createKanbanQueryKeys(client, headers);
-
-	const result = useSuspenseQuery({
-		...queries.boards.list(params),
-		staleTime: 30_000,
-		refetchOnWindowFocus: true,
-	});
-
-	if (result.error && !result.isFetching) {
-		throw result.error;
-	}
-
-	return result;
+	return kanban.boards.list.useSuspense([params]);
 }
 
-/**
- * Hook to fetch a single board by ID
- */
+/** Hook to fetch a single board by ID. */
 export function useBoard(boardId: string) {
-	const { client, headers } = useKanbanClient();
-	const queries = createKanbanQueryKeys(client, headers);
-
-	return useQuery({
-		...queries.boards.detail(boardId),
-		staleTime: 30_000,
-		refetchOnWindowFocus: true,
-		enabled: !!boardId,
-	});
+	return kanban.boards.detail.use([boardId], { enabled: !!boardId });
 }
 
-/**
- * Hook to fetch a single board with suspense
- */
+/** Suspense variant of useBoard. */
 export function useSuspenseBoard(boardId: string) {
-	const { client, headers } = useKanbanClient();
-	const queries = createKanbanQueryKeys(client, headers);
-
-	const result = useSuspenseQuery({
-		...queries.boards.detail(boardId),
-		staleTime: 30_000,
-		refetchOnWindowFocus: true,
-	});
-
-	if (result.error && !result.isFetching) {
-		throw result.error;
-	}
-
-	return result;
+	return kanban.boards.detail.useSuspense([boardId]);
 }
 
-// ============ Board Mutations ============
-
 /**
- * Hook for board CRUD mutations
+ * Form lifecycle hook for creating/editing boards. It submits the matching
+ * resource mutation and exposes normalized field-level server errors.
  */
-export function useBoardMutations() {
-	const { client, headers } = useKanbanClient();
-	const queryClient = useQueryClient();
-
-	const createMutation = useMutation({
-		mutationFn: async (data: {
-			name: string;
-			description?: string;
-			ownerId?: string;
-			organizationId?: string;
-		}) => {
-			const response = await client("@post/boards", {
-				method: "POST",
-				body: data,
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as SerializedBoardWithColumns;
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
-
-	const updateMutation = useMutation({
-		mutationFn: async ({
-			id,
-			data,
-		}: {
-			id: string;
-			data: Partial<{
-				name: string;
-				description: string;
-				slug: string;
-			}>;
-		}) => {
-			const response = await client("@put/boards/:id", {
-				method: "PUT",
-				params: { id },
-				body: data,
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as SerializedBoard;
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
+export function useBoardForm<TValues>(
+	config: ResourceFormConfig<TValues, SerializedBoard | null, SerializedBoard>,
+): ResourceFormResult<TValues, SerializedBoard | null, SerializedBoard> {
+	return kanban.boards.useForm<
+		TValues,
+		SerializedBoard,
+		SerializedBoard | null
+	>(config);
+}
 
-	const deleteMutation = useMutation({
-		mutationFn: async (id: string) => {
-			const response = await client("@delete/boards/:id", {
-				method: "DELETE",
-				params: { id },
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as { success: boolean };
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
+/** Hook for board CRUD mutations. */
+export function useBoardMutations() {
+	const createMutation = kanban.boards.create.use();
+	const updateMutation = kanban.boards.update.use();
+	const deleteMutation = kanban.boards.delete.use();
 
 	return {
 		createBoard: createMutation.mutateAsync,
@@ -243,106 +80,31 @@ export function useBoardMutations() {
 	};
 }
 
-// ============ Column Mutations ============
+// ============ Column Hooks ============
 
 /**
- * Hook for column CRUD mutations
+ * Form lifecycle hook for creating/editing columns with server field errors.
  */
-export function useColumnMutations() {
-	const { client, headers } = useKanbanClient();
-	const queryClient = useQueryClient();
-
-	const createMutation = useMutation({
-		mutationFn: async (data: {
-			title: string;
-			boardId: string;
-			order?: number;
-		}) => {
-			const response = await client("@post/columns", {
-				method: "POST",
-				body: data,
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as SerializedColumn;
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
-
-	const updateMutation = useMutation({
-		mutationFn: async ({
-			id,
-			data,
-		}: {
-			id: string;
-			data: Partial<{
-				title: string;
-				order: number;
-			}>;
-		}) => {
-			const response = await client("@put/columns/:id", {
-				method: "PUT",
-				params: { id },
-				body: data,
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as SerializedColumn;
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
-
-	const deleteMutation = useMutation({
-		mutationFn: async (id: string) => {
-			const response = await client("@delete/columns/:id", {
-				method: "DELETE",
-				params: { id },
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as { success: boolean };
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
+export function useColumnForm<TValues>(
+	config: ResourceFormConfig<
+		TValues,
+		SerializedColumn | null,
+		SerializedColumn
+	>,
+): ResourceFormResult<TValues, SerializedColumn | null, SerializedColumn> {
+	return kanban.columns.useForm<
+		TValues,
+		SerializedColumn,
+		SerializedColumn | null
+	>(config);
+}
 
-	const reorderMutation = useMutation({
-		mutationFn: async ({
-			boardId,
-			columnIds,
-		}: {
-			boardId: string;
-			columnIds: string[];
-		}) => {
-			const response = await client("@post/columns/reorder", {
-				method: "POST",
-				body: { boardId, columnIds },
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as { success: boolean };
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
+/** Hook for column CRUD and reorder mutations. */
+export function useColumnMutations() {
+	const createMutation = kanban.columns.create.use();
+	const updateMutation = kanban.columns.update.use();
+	const deleteMutation = kanban.columns.delete.use();
+	const reorderMutation = kanban.columns.reorder.use();
 
 	return {
 		createColumn: createMutation.mutateAsync,
@@ -364,140 +126,26 @@ export function useColumnMutations() {
 	};
 }
 
-// ============ Task Mutations ============
+// ============ Task Hooks ============
 
 /**
- * Hook for task CRUD mutations
+ * Form lifecycle hook for creating/editing tasks with server field errors.
  */
-export function useTaskMutations() {
-	const { client, headers } = useKanbanClient();
-	const queryClient = useQueryClient();
-
-	const createMutation = useMutation({
-		mutationFn: async (data: {
-			title: string;
-			description?: string;
-			priority?: Priority;
-			columnId: string;
-			assigneeId?: string;
-			order?: number;
-		}) => {
-			const response = await client("@post/tasks", {
-				method: "POST",
-				body: data,
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as SerializedTask;
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
-
-	const updateMutation = useMutation({
-		mutationFn: async ({
-			id,
-			data,
-		}: {
-			id: string;
-			data: Partial<{
-				title: string;
-				description: string;
-				priority: Priority;
-				columnId: string;
-				assigneeId: string | null;
-				order: number;
-				isArchived: boolean;
-			}>;
-		}) => {
-			const response = await client("@put/tasks/:id", {
-				method: "PUT",
-				params: { id },
-				body: data,
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as SerializedTask;
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
-
-	const deleteMutation = useMutation({
-		mutationFn: async (id: string) => {
-			const response = await client("@delete/tasks/:id", {
-				method: "DELETE",
-				params: { id },
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as { success: boolean };
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
-
-	const moveMutation = useMutation({
-		mutationFn: async ({
-			taskId,
-			targetColumnId,
-			targetOrder,
-		}: {
-			taskId: string;
-			targetColumnId: string;
-			targetOrder: number;
-		}) => {
-			const response = await client("@post/tasks/move", {
-				method: "POST",
-				body: { taskId, targetColumnId, targetOrder },
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as SerializedTask;
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
+export function useTaskForm<TValues>(
+	config: ResourceFormConfig<TValues, SerializedTask | null, SerializedTask>,
+): ResourceFormResult<TValues, SerializedTask | null, SerializedTask> {
+	return kanban.tasks.useForm<TValues, SerializedTask, SerializedTask | null>(
+		config,
+	);
+}
 
-	const reorderMutation = useMutation({
-		mutationFn: async ({
-			columnId,
-			taskIds,
-		}: {
-			columnId: string;
-			taskIds: string[];
-		}) => {
-			const response = await client("@post/tasks/reorder", {
-				method: "POST",
-				body: { columnId, taskIds },
-				headers,
-			});
-			if (isErrorResponse(response)) {
-				const errorResponse = response as { error: unknown };
-				throw toError(errorResponse.error);
-			}
-			return response.data as unknown as { success: boolean };
-		},
-		onSuccess: () => {
-			queryClient.invalidateQueries({ queryKey: ["boards"] });
-		},
-	});
+/** Hook for task CRUD, move, and reorder mutations. */
+export function useTaskMutations() {
+	const createMutation = kanban.tasks.create.use();
+	const updateMutation = kanban.tasks.update.use();
+	const deleteMutation = kanban.tasks.delete.use();
+	const moveMutation = kanban.tasks.move.use();
+	const reorderMutation = kanban.tasks.reorder.use();
 
 	return {
 		createTask: createMutation.mutateAsync,
@@ -525,10 +173,7 @@ export function useTaskMutations() {
 
 // ============ User Resolution Hooks ============
 
-/**
- * Hook to resolve a user from their ID
- * Caches results to avoid repeated lookups
- */
+/** Resolve a user from the consumer-provided callback. */
 export function useResolveUser(userId: string | undefined | null) {
 	const { resolveUser } = usePluginOverrides<KanbanPluginOverrides>("kanban");
 
@@ -536,29 +181,21 @@ export function useResolveUser(userId: string | undefined | null) {
 		queryKey: ["kanban", "users", userId],
 		queryFn: async () => {
 			if (!userId) return null;
-			const result = await resolveUser(userId);
-			return result;
+			return resolveUser(userId);
 		},
 		enabled: !!userId,
-		staleTime: 5 * 60 * 1000, // Cache user info for 5 minutes
-		gcTime: 10 * 60 * 1000, // Keep in cache for 10 minutes
+		staleTime: 5 * 60 * 1000,
+		gcTime: 10 * 60 * 1000,
 	});
 }
 
-/**
- * Hook to search for users available for assignment
- * @param query - Search query (empty string for all users)
- * @param boardId - Optional board context for scoped user lists
- */
+/** Search for assignable users through the consumer-provided callback. */
 export function useSearchUsers(query: string, boardId?: string) {
 	const { searchUsers } = usePluginOverrides<KanbanPluginOverrides>("kanban");
 
 	return useQuery<KanbanUser[]>({
 		queryKey: ["kanban", "users", "search", query, boardId],
-		queryFn: async () => {
-			const result = await searchUsers(query, boardId);
-			return result;
-		},
-		staleTime: 30_000, // Cache search results for 30 seconds
+		queryFn: () => searchUsers(query, boardId),
+		staleTime: 30_000,
 	});
 }

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

@@ -0,0 +1,13 @@
+"use client";
+
+import { createResource } from "@btst/stack/plugins/client/hooks";
+import { kanbanResources } from "../../query-keys";
+
+/**
+ * Factory-generated Kanban resource hooks. Internal — public hooks preserve
+ * the existing Kanban-specific names and return shapes in `kanban-hooks.tsx`.
+ */
+export const kanban = createResource({
+	plugin: "kanban",
+	resources: kanbanResources,
+});

package/src/plugins/kanban/client/localization/kanban-common.ts

@@ -11,6 +11,8 @@ export interface KanbanCommonLocalization {
 	// Status
 	loading: string;
 	saving: string;
+	creating: string;
+	updating: string;
 	deleting: string;
 	// Labels
 	board: string;
@@ -28,9 +30,19 @@ export interface KanbanCommonLocalization {
 	noBoards: string;
 	noColumns: string;
 	noTasks: string;
+	assigned: string;
+	unassigned: string;
+	// Generic UI
+	pageNotFound: string;
+	pageNotFoundDescription: string;
+	unexpectedError: string;
+	tryAgain: string;
 	// Errors
 	errorGeneric: string;
 	errorNotFound: string;
+	deleteBoardError: string;
+	deleteColumnError: string;
+	deleteTaskError: string;
 }
 
 export const defaultKanbanCommonLocalization: KanbanCommonLocalization = {
@@ -46,6 +58,8 @@ export const defaultKanbanCommonLocalization: KanbanCommonLocalization = {
 	// Status
 	loading: "Loading...",
 	saving: "Saving...",
+	creating: "Creating...",
+	updating: "Updating...",
 	deleting: "Deleting...",
 	// Labels
 	board: "Board",
@@ -63,7 +77,17 @@ export const defaultKanbanCommonLocalization: KanbanCommonLocalization = {
 	noBoards: "No boards yet",
 	noColumns: "No columns yet",
 	noTasks: "No tasks yet",
+	assigned: "Assigned",
+	unassigned: "Unassigned",
+	// Generic UI
+	pageNotFound: "Page Not Found",
+	pageNotFoundDescription: "The page you're looking for doesn't exist.",
+	unexpectedError: "An unexpected error occurred. Please try again.",
+	tryAgain: "Try Again",
 	// Errors
 	errorGeneric: "Something went wrong",
 	errorNotFound: "Not found",
+	deleteBoardError: "Failed to delete board",
+	deleteColumnError: "Failed to delete column",
+	deleteTaskError: "Failed to delete task",
 };

package/src/plugins/kanban/client/localization/kanban-forms.ts

@@ -23,6 +23,11 @@ export interface KanbanFormsLocalization {
 	taskPriority: string;
 	taskColumn: string;
 	taskAssignee: string;
+	selectPriority: string;
+	selectColumn: string;
+	selectAssignee: string;
+	noUsersFound: string;
+	taskMovePartialError: string;
 	createTask: string;
 	updateTask: string;
 	deleteTask: string;
@@ -59,6 +64,12 @@ export const defaultKanbanFormsLocalization: KanbanFormsLocalization = {
 	taskPriority: "Priority",
 	taskColumn: "Column",
 	taskAssignee: "Assignee",
+	selectPriority: "Select priority",
+	selectColumn: "Select column",
+	selectAssignee: "Select assignee",
+	noUsersFound: "No users found",
+	taskMovePartialError:
+		"Task properties were saved, but moving to the new column failed: {{message}}. You can try dragging the task to the desired column.",
 	createTask: "Create Task",
 	updateTask: "Update Task",
 	deleteTask: "Delete Task",