@btst/stack 2.12.2 → 3.0.0-rc.2

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

@@ -3,17 +3,29 @@ export interface KanbanListLocalization {
 	kanbanBoards: string;
 	manageProjects: string;
 	createNewBoard: string;
+	createNewBoardDescription: string;
 	boardDetails: string;
+	boardDetailsDescription: string;
 	// Actions
 	newBoard: string;
 	addColumn: string;
 	addTask: string;
+	editBoard: string;
+	editColumn: string;
+	editTask: string;
 	// List
 	columnsCount: string;
 	// Empty states
 	noBoardsDescription: string;
 	noColumnsDescription: string;
 	noTasksDescription: string;
+	boardNotFound: string;
+	boardNotFoundDescription: string;
+	addColumnDescription: string;
+	editColumnDescription: string;
+	editBoardDescription: string;
+	addTaskDescription: string;
+	editTaskDescription: string;
 }
 
 export const defaultKanbanListLocalization: KanbanListLocalization = {
@@ -21,11 +33,16 @@ export const defaultKanbanListLocalization: KanbanListLocalization = {
 	kanbanBoards: "Kanban Boards",
 	manageProjects: "Manage your projects and tasks",
 	createNewBoard: "Create New Board",
+	createNewBoardDescription: "Set up a new kanban board for your project",
 	boardDetails: "Board Details",
+	boardDetailsDescription: "Enter the details for your new kanban board.",
 	// Actions
 	newBoard: "New Board",
 	addColumn: "Add Column",
 	addTask: "Add Task",
+	editBoard: "Edit Board",
+	editColumn: "Edit Column",
+	editTask: "Edit Task",
 	// List
 	columnsCount: "columns",
 	// Empty states
@@ -33,4 +50,12 @@ export const defaultKanbanListLocalization: KanbanListLocalization = {
 		"Create your first kanban board to start organizing your tasks.",
 	noColumnsDescription: "Create your first column to start organizing tasks.",
 	noTasksDescription: "Add a task to get started",
+	boardNotFound: "Board not found",
+	boardNotFoundDescription:
+		"The board you're looking for doesn't exist or you don't have access to it.",
+	addColumnDescription: "Add a new column to this board.",
+	editColumnDescription: "Update the column details.",
+	editBoardDescription: "Update board details.",
+	addTaskDescription: "Create a new task.",
+	editTaskDescription: "Update task details.",
 };

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

@@ -30,40 +30,14 @@ export interface RouteContext {
 /**
  * Overridable components and functions for the Kanban plugin
  *
- * External consumers can provide their own implementations of these
- * to customize the behavior for their framework (Next.js, React Router, etc.)
+ * External consumers can provide their own implementations to customize
+ * plugin-specific components and behavior.
  */
 export interface KanbanPluginOverrides {
-	/**
-	 * Link component for navigation
-	 */
-	Link?: ComponentType<React.ComponentProps<"a"> & Record<string, unknown>>;
-	/**
-	 * Navigation function for programmatic navigation
-	 */
-	navigate: (path: string) => void | Promise<void>;
-	/**
-	 * Refresh function to invalidate server-side cache (e.g., Next.js router.refresh())
-	 */
-	refresh?: () => void | Promise<void>;
-	/**
-	 * Image component for displaying images
-	 */
-	Image?: ComponentType<
-		React.ImgHTMLAttributes<HTMLImageElement> & Record<string, unknown>
-	>;
 	/**
 	 * Localization object for the kanban plugin
 	 */
 	localization?: KanbanLocalization;
-	/**
-	 * API base URL
-	 */
-	apiBaseURL: string;
-	/**
-	 * API base path
-	 */
-	apiBasePath: string;
 	/**
 	 * Whether to show the attribution
 	 */
@@ -144,31 +118,6 @@ export interface KanbanPluginOverrides {
 		context: RouteContext,
 	) => void | Promise<void>;
 
-	/**
-	 * Called before the boards list page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param context - Route context
-	 */
-	onBeforeBoardsPageRendered?: (context: RouteContext) => boolean;
-
-	/**
-	 * Called before a single board page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param boardId - The board ID
-	 * @param context - Route context
-	 */
-	onBeforeBoardPageRendered?: (
-		boardId: string,
-		context: RouteContext,
-	) => boolean;
-
-	/**
-	 * Called before the new board page is rendered
-	 * Return false to prevent rendering (e.g., for authorization)
-	 * @param context - Route context
-	 */
-	onBeforeNewBoardPageRendered?: (context: RouteContext) => boolean;
-
 	// ============ Slot Overrides ============
 
 	/**
@@ -183,10 +132,6 @@ export interface KanbanPluginOverrides {
 	 *     <CommentThread
 	 *       resourceId={task.id}
 	 *       resourceType="kanban-task"
-	 *       apiBaseURL={apiBaseURL}
-	 *       apiBasePath="/api/data"
-	 *       currentUserId={session?.userId}
-	 *       loginHref="/login"
 	 *     />
 	 *   ),
 	 * }

package/src/plugins/kanban/client/plugin.tsx

@@ -2,9 +2,8 @@ import {
 	defineClientPlugin,
 	createApiClient,
 	isConnectionError,
-	runClientHookWithShim,
 } from "@btst/stack/plugins/client";
-import { createRoute } from "@btst/yar";
+import { defineRoute, defineRoutes } from "@btst/yar";
 import type { ComponentType } from "react";
 import type { QueryClient } from "@tanstack/react-query";
 import type { KanbanApiRouter } from "../api";
@@ -92,7 +91,7 @@ export interface KanbanClientConfig {
 		/** Replaces the new board page */
 		newBoard?: ComponentType;
 		/** Replaces the board detail page */
-		board?: ComponentType<{ boardId: string }>;
+		board?: ComponentType<{ params: { boardId: string } }>;
 	};
 }
 
@@ -157,10 +156,7 @@ function createBoardsLoader(config: KanbanClientConfig) {
 
 			try {
 				if (hooks?.beforeLoadBoards) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadBoards!(context),
-						"Load prevented by beforeLoadBoards hook",
-					);
+					await hooks.beforeLoadBoards(context);
 				}
 
 				const client = createApiClient<KanbanApiRouter>({
@@ -177,10 +173,7 @@ function createBoardsLoader(config: KanbanClientConfig) {
 					const boards = queryClient.getQueryData<SerializedBoardWithColumns[]>(
 						listQuery.queryKey,
 					);
-					await runClientHookWithShim(
-						() => hooks.afterLoadBoards!(boards || null, context),
-						"Load prevented by afterLoadBoards hook",
-					);
+					await hooks.afterLoadBoards(boards || null, context);
 				}
 
 				const queryState = queryClient.getQueryState(listQuery.queryKey);
@@ -223,10 +216,7 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 
 			try {
 				if (hooks?.beforeLoadBoard) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadBoard!(boardId, context),
-						"Load prevented by beforeLoadBoard hook",
-					);
+					await hooks.beforeLoadBoard(boardId, context);
 				}
 
 				const client = createApiClient<KanbanApiRouter>({
@@ -242,10 +232,7 @@ function createBoardLoader(boardId: string, config: KanbanClientConfig) {
 					const board = queryClient.getQueryData<SerializedBoardWithColumns>(
 						boardQuery.queryKey,
 					);
-					await runClientHookWithShim(
-						() => hooks.afterLoadBoard!(board || null, boardId, context),
-						"Load prevented by afterLoadBoard hook",
-					);
+					await hooks.afterLoadBoard(board || null, boardId, context);
 				}
 
 				const queryState = queryClient.getQueryState(boardQuery.queryKey);
@@ -287,17 +274,11 @@ function createNewBoardLoader(config: KanbanClientConfig) {
 
 			try {
 				if (hooks?.beforeLoadNewBoard) {
-					await runClientHookWithShim(
-						() => hooks.beforeLoadNewBoard!(context),
-						"Load prevented by beforeLoadNewBoard hook",
-					);
+					await hooks.beforeLoadNewBoard(context);
 				}
 
 				if (hooks?.afterLoadNewBoard) {
-					await runClientHookWithShim(
-						() => hooks.afterLoadNewBoard!(context),
-						"Load prevented by afterLoadNewBoard hook",
-					);
+					await hooks.afterLoadNewBoard(context);
 				}
 			} catch (error) {
 				if (hooks?.onLoadError) {
@@ -420,34 +401,29 @@ export const kanbanClientPlugin = (config: KanbanClientConfig) =>
 	defineClientPlugin({
 		name: "kanban",
 
-		routes: () => ({
-			boards: createRoute("/kanban", () => {
-				const CustomBoards = config.pageComponents?.boards;
-				return {
-					PageComponent: CustomBoards ?? (() => <BoardsListPageComponent />),
-					loader: createBoardsLoader(config),
-					meta: createBoardsListMeta(config),
-				};
-			}),
-			newBoard: createRoute("/kanban/new", () => {
-				const CustomNewBoard = config.pageComponents?.newBoard;
-				return {
-					PageComponent: CustomNewBoard ?? NewBoardPageComponent,
-					loader: createNewBoardLoader(config),
-					meta: createNewBoardMeta(config),
-				};
-			}),
-			board: createRoute("/kanban/:boardId", ({ params: { boardId } }) => {
-				const CustomBoard = config.pageComponents?.board;
-				return {
-					PageComponent: CustomBoard
-						? () => <CustomBoard boardId={boardId} />
-						: () => <BoardPageComponent boardId={boardId} />,
-					loader: createBoardLoader(boardId, config),
-					meta: createBoardMeta(boardId, config),
-				};
-			}),
-		}),
+		routes: () =>
+			defineRoutes(
+				{
+					boards: defineRoute("/kanban", {
+						page: BoardsListPageComponent,
+						loader: createBoardsLoader(config),
+						meta: createBoardsListMeta(config),
+					}),
+					newBoard: defineRoute("/kanban/new", {
+						page: NewBoardPageComponent,
+						loader: createNewBoardLoader(config),
+						meta: createNewBoardMeta(config),
+					}),
+					board: defineRoute("/kanban/:boardId", {
+						page: ({ params }) => (
+							<BoardPageComponent boardId={params.boardId} />
+						),
+						loader: ({ params }) => createBoardLoader(params.boardId, config)(),
+						meta: ({ params }) => createBoardMeta(params.boardId, config)(),
+					}),
+				},
+				{ pages: config.pageComponents },
+			),
 
 		sitemap: async () => {
 			const origin = `${config.siteBaseURL}${config.siteBasePath}`;

package/src/plugins/kanban/query-keys.ts

@@ -1,13 +1,19 @@
-import {
-	mergeQueryKeys,
-	createQueryKeys,
-} from "@lukemorales/query-key-factory";
 import type { KanbanApiRouter } from "./api";
-import { createApiClient } from "@btst/stack/plugins/client";
-import type { SerializedBoardWithColumns } from "./types";
+import {
+	createApiClient,
+	createResourceQueryKeys,
+	type ResourcesDeclaration,
+} from "@btst/stack/plugins/client";
+import type {
+	Priority,
+	SerializedBoard,
+	SerializedBoardWithColumns,
+	SerializedColumn,
+	SerializedTask,
+} from "./types";
 import { boardsListDiscriminator } from "./api/query-key-defs";
 
-interface BoardsListParams {
+export interface BoardsListParams {
 	slug?: string;
 	ownerId?: string;
 	organizationId?: string;
@@ -15,136 +21,254 @@ interface BoardsListParams {
 	offset?: number;
 }
 
-// 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
-	);
+export interface CreateBoardInput {
+	name: string;
+	description?: string;
+	ownerId?: string;
+	organizationId?: string;
 }
 
-// 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));
+export interface UpdateBoardInput {
+	id: string;
+	data: Partial<{
+		name: string;
+		description: string;
+		slug: string;
+	}>;
 }
 
-export function createKanbanQueryKeys(
-	client: ReturnType<typeof createApiClient<KanbanApiRouter>>,
-	headers?: HeadersInit,
-) {
-	const boards = createBoardsQueries(client, headers);
+export interface CreateColumnInput {
+	title: string;
+	boardId: string;
+	order?: number;
+}
 
-	return mergeQueryKeys(boards);
+export interface UpdateColumnInput {
+	id: string;
+	data: Partial<{
+		title: string;
+		order: number;
+	}>;
 }
 
-function createBoardsQueries(
-	client: ReturnType<typeof createApiClient<KanbanApiRouter>>,
-	headers?: HeadersInit,
-) {
-	return createQueryKeys("boards", {
-		list: (params?: BoardsListParams) => ({
-			queryKey: [boardsListDiscriminator(params)],
-			queryFn: async () => {
-				try {
-					const response = await client("/boards", {
-						method: "GET",
-						query: {
-							slug: params?.slug,
-							ownerId: params?.ownerId,
-							organizationId: params?.organizationId,
-							limit: params?.limit ?? 50,
-							offset: params?.offset ?? 0,
-						},
-						headers,
-					});
-
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-
-					const envelope = (response as { data?: unknown }).data as
-						| { items?: SerializedBoardWithColumns[] }
-						| undefined;
-					return envelope?.items ?? ([] as SerializedBoardWithColumns[]);
-				} catch (error) {
-					throw error;
-				}
+export interface ReorderColumnsInput {
+	boardId: string;
+	columnIds: string[];
+}
+
+export interface CreateTaskInput {
+	title: string;
+	description?: string;
+	priority?: Priority;
+	columnId: string;
+	assigneeId?: string;
+	order?: number;
+}
+
+export interface UpdateTaskInput {
+	id: string;
+	data: Partial<{
+		title: string;
+		description: string;
+		priority: Priority;
+		columnId: string;
+		assigneeId: string | null;
+		order: number;
+		isArchived: boolean;
+	}>;
+}
+
+export interface MoveTaskInput {
+	taskId: string;
+	targetColumnId: string;
+	targetOrder: number;
+}
+
+export interface ReorderTasksInput {
+	columnId: string;
+	taskIds: string[];
+}
+
+/**
+ * Kanban resource declaration — the single source of truth for query keys,
+ * HTTP mappings, cache invalidation, and generated client hooks.
+ *
+ * Board key shapes intentionally match `KANBAN_QUERY_KEYS` so SSR loaders and
+ * `prefetchForRoute` hydrate the same cache entries as client hooks.
+ */
+export const kanbanResources = {
+	boards: {
+		queries: {
+			list: {
+				path: "/boards",
+				query: (params?: BoardsListParams) => ({
+					slug: params?.slug,
+					ownerId: params?.ownerId,
+					organizationId: params?.organizationId,
+					limit: params?.limit ?? 50,
+					offset: params?.offset ?? 0,
+				}),
+				key: (params?: BoardsListParams) => [boardsListDiscriminator(params)],
+				select: (
+					data: any,
+					_params?: BoardsListParams,
+				): SerializedBoardWithColumns[] => data?.items ?? [],
 			},
-		}),
-
-		detail: (boardId: string) => ({
-			queryKey: [boardId],
-			queryFn: async () => {
-				if (!boardId) return null;
-
-				try {
-					const response = await client("/boards/:id", {
-						method: "GET",
-						params: { id: boardId },
-						headers,
-					});
-
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-
-					return ((response as { data?: unknown }).data ??
-						null) as unknown as SerializedBoardWithColumns | null;
-				} catch (error) {
-					throw error;
-				}
+
+			detail: {
+				path: "/boards/:id",
+				params: (boardId: string) => ({ id: boardId }),
+				key: (boardId: string) => [boardId],
+				select: (
+					data: any,
+					_boardId: string,
+				): SerializedBoardWithColumns | null => data ?? null,
+				skip: (boardId: string) => !boardId,
 			},
-		}),
-
-		// Get board by slug
-		bySlug: (slug: string) => ({
-			queryKey: ["slug", slug],
-			queryFn: async () => {
-				if (!slug) return null;
-
-				try {
-					const response = await client("/boards", {
-						method: "GET",
-						query: { slug, limit: 1 },
-						headers,
-					});
-
-					if (isErrorResponse(response)) {
-						const errorResponse = response as { error: unknown };
-						throw toError(errorResponse.error);
-					}
-
-					const envelope = (response as { data?: unknown }).data as
-						| { items?: SerializedBoardWithColumns[] }
-						| undefined;
-					return envelope?.items?.[0] ?? null;
-				} catch (error) {
-					throw error;
-				}
+
+			bySlug: {
+				path: "/boards",
+				query: (slug: string) => ({ slug, limit: 1 }),
+				key: (slug: string) => ["slug", slug],
+				select: (data: any, _slug: string): SerializedBoardWithColumns | null =>
+					data?.items?.[0] ?? null,
+				skip: (slug: string) => !slug,
+			},
+		},
+
+		mutations: {
+			create: {
+				path: "@post/boards",
+				method: "POST" as const,
+				input: (data: CreateBoardInput) => ({ body: data }),
+				select: (data: any) => data as SerializedBoardWithColumns,
+				setData: {
+					query: "detail",
+					args: (board: SerializedBoardWithColumns) => [board.id],
+				},
+				invalidates: ["boards.list"],
+				refresh: false,
+			},
+			update: {
+				path: "@put/boards/:id",
+				method: "PUT" as const,
+				input: ({ id, data }: UpdateBoardInput) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: any) => data as SerializedBoard,
+				invalidates: ["boards"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/boards/:id",
+				method: "DELETE" as const,
+				input: (id: string) => ({ params: { id } }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["boards.list"],
+				refresh: false,
+			},
+		},
+	},
+
+	columns: {
+		queries: {},
+		mutations: {
+			create: {
+				path: "@post/columns",
+				method: "POST" as const,
+				input: (data: CreateColumnInput) => ({ body: data }),
+				select: (data: any) => data as SerializedColumn,
+				invalidates: ["boards"],
+				refresh: false,
+			},
+			update: {
+				path: "@put/columns/:id",
+				method: "PUT" as const,
+				input: ({ id, data }: UpdateColumnInput) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: any) => data as SerializedColumn,
+				invalidates: ["boards"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/columns/:id",
+				method: "DELETE" as const,
+				input: (id: string) => ({ params: { id } }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["boards"],
+				refresh: false,
+			},
+			reorder: {
+				path: "@post/columns/reorder",
+				method: "POST" as const,
+				input: (data: ReorderColumnsInput) => ({ body: data }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["boards"],
+				refresh: false,
+			},
+		},
+	},
+
+	tasks: {
+		queries: {},
+		mutations: {
+			create: {
+				path: "@post/tasks",
+				method: "POST" as const,
+				input: (data: CreateTaskInput) => ({ body: data }),
+				select: (data: any) => data as SerializedTask,
+				invalidates: ["boards"],
+				refresh: false,
+			},
+			update: {
+				path: "@put/tasks/:id",
+				method: "PUT" as const,
+				input: ({ id, data }: UpdateTaskInput) => ({
+					params: { id },
+					body: data,
+				}),
+				select: (data: any) => data as SerializedTask,
+				invalidates: ["boards"],
+				refresh: false,
+			},
+			delete: {
+				path: "@delete/tasks/:id",
+				method: "DELETE" as const,
+				input: (id: string) => ({ params: { id } }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["boards"],
+				refresh: false,
 			},
-		}),
-	});
+			move: {
+				path: "@post/tasks/move",
+				method: "POST" as const,
+				input: (data: MoveTaskInput) => ({ body: data }),
+				select: (data: any) => data as SerializedTask,
+				invalidates: ["boards"],
+				refresh: false,
+			},
+			reorder: {
+				path: "@post/tasks/reorder",
+				method: "POST" as const,
+				input: (data: ReorderTasksInput) => ({ body: data }),
+				select: (data: any) => data as { success: boolean },
+				invalidates: ["boards"],
+				refresh: false,
+			},
+		},
+	},
+} satisfies ResourcesDeclaration;
+
+const kanbanQueryResources = {
+	boards: kanbanResources.boards,
+} satisfies ResourcesDeclaration;
+
+export function createKanbanQueryKeys(
+	client: ReturnType<typeof createApiClient<KanbanApiRouter>>,
+	headers?: HeadersInit,
+) {
+	return createResourceQueryKeys(client, kanbanQueryResources, headers);
 }