@btst/stack 1.11.0 → 1.12.0

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

@@ -0,0 +1,70 @@
+export interface KanbanFormsLocalization {
+	// Board form
+	boardName: string;
+	boardNamePlaceholder: string;
+	boardDescription: string;
+	boardDescriptionPlaceholder: string;
+	createBoard: string;
+	updateBoard: string;
+	deleteBoard: string;
+	deleteBoardConfirm: string;
+	// Column form
+	columnTitle: string;
+	columnTitlePlaceholder: string;
+	createColumn: string;
+	updateColumn: string;
+	deleteColumn: string;
+	deleteColumnConfirm: string;
+	// Task form
+	taskTitle: string;
+	taskTitlePlaceholder: string;
+	taskDescription: string;
+	taskDescriptionPlaceholder: string;
+	taskPriority: string;
+	taskColumn: string;
+	taskAssignee: string;
+	createTask: string;
+	updateTask: string;
+	deleteTask: string;
+	deleteTaskConfirm: string;
+	// Validation
+	nameRequired: string;
+	titleRequired: string;
+}
+
+export const defaultKanbanFormsLocalization: KanbanFormsLocalization = {
+	// Board form
+	boardName: "Name",
+	boardNamePlaceholder: "e.g., Project Alpha",
+	boardDescription: "Description",
+	boardDescriptionPlaceholder: "Describe your board...",
+	createBoard: "Create Board",
+	updateBoard: "Update Board",
+	deleteBoard: "Delete Board",
+	deleteBoardConfirm:
+		"Are you sure you want to delete this board? This action cannot be undone. All columns and tasks will be permanently removed.",
+	// Column form
+	columnTitle: "Title",
+	columnTitlePlaceholder: "e.g., To Do",
+	createColumn: "Create Column",
+	updateColumn: "Update Column",
+	deleteColumn: "Delete Column",
+	deleteColumnConfirm:
+		"Are you sure you want to delete this column? All tasks in this column will be permanently removed.",
+	// Task form
+	taskTitle: "Title",
+	taskTitlePlaceholder: "e.g., Fix login bug",
+	taskDescription: "Description",
+	taskDescriptionPlaceholder: "Describe the task...",
+	taskPriority: "Priority",
+	taskColumn: "Column",
+	taskAssignee: "Assignee",
+	createTask: "Create Task",
+	updateTask: "Update Task",
+	deleteTask: "Delete Task",
+	deleteTaskConfirm:
+		"Are you sure you want to delete this task? This action cannot be undone.",
+	// Validation
+	nameRequired: "Name is required",
+	titleRequired: "Title is required",
+};

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

@@ -0,0 +1,36 @@
+export interface KanbanListLocalization {
+	// Page titles
+	kanbanBoards: string;
+	manageProjects: string;
+	createNewBoard: string;
+	boardDetails: string;
+	// Actions
+	newBoard: string;
+	addColumn: string;
+	addTask: string;
+	// List
+	columnsCount: string;
+	// Empty states
+	noBoardsDescription: string;
+	noColumnsDescription: string;
+	noTasksDescription: string;
+}
+
+export const defaultKanbanListLocalization: KanbanListLocalization = {
+	// Page titles
+	kanbanBoards: "Kanban Boards",
+	manageProjects: "Manage your projects and tasks",
+	createNewBoard: "Create New Board",
+	boardDetails: "Board Details",
+	// Actions
+	newBoard: "New Board",
+	addColumn: "Add Column",
+	addTask: "Add Task",
+	// List
+	columnsCount: "columns",
+	// Empty states
+	noBoardsDescription:
+		"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",
+};

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

@@ -0,0 +1,145 @@
+import type { ComponentType } from "react";
+import type { KanbanLocalization } from "./localization";
+
+/**
+ * User information for assignee display/selection
+ * Framework-agnostic - consumers map their auth system to this shape
+ */
+export interface KanbanUser {
+	id: string;
+	name: string;
+	avatarUrl?: string;
+	email?: string;
+}
+
+/**
+ * Context passed to lifecycle hooks
+ */
+export interface RouteContext {
+	/** Current route path */
+	path: string;
+	/** Route parameters (e.g., { boardId: "abc123" }) */
+	params?: Record<string, string>;
+	/** Whether rendering on server (true) or client (false) */
+	isSSR: boolean;
+	/** Additional context properties */
+	[key: string]: unknown;
+}
+
+/**
+ * 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.)
+ */
+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
+	 */
+	showAttribution?: boolean;
+	/**
+	 * Optional headers to pass with API requests (e.g., for SSR auth)
+	 */
+	headers?: HeadersInit;
+
+	// ============ User Resolution (required for assignee features) ============
+
+	/**
+	 * Resolve user info from an assigneeId
+	 * Called when rendering task cards/forms that have an assignee
+	 * Return null for unknown users (will show fallback UI)
+	 */
+	resolveUser: (
+		userId: string,
+	) => Promise<KanbanUser | null> | KanbanUser | null;
+
+	/**
+	 * Search/list users available for assignment
+	 * Called when user opens the assignee picker
+	 * @param query - Search query (empty string for initial load)
+	 * @param boardId - Optional board context for scoped user lists
+	 */
+	searchUsers: (
+		query: string,
+		boardId?: string,
+	) => Promise<KanbanUser[]> | KanbanUser[];
+
+	// ============ Lifecycle Hooks (optional) ============
+
+	/**
+	 * Called when a route is rendered
+	 * @param routeName - Name of the route (e.g., 'boards', 'board', 'newBoard')
+	 * @param context - Route context with path, params, etc.
+	 */
+	onRouteRender?: (
+		routeName: string,
+		context: RouteContext,
+	) => void | Promise<void>;
+
+	/**
+	 * Called when a route encounters an error
+	 * @param routeName - Name of the route
+	 * @param error - The error that occurred
+	 * @param context - Route context
+	 */
+	onRouteError?: (
+		routeName: string,
+		error: Error,
+		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;
+}

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

@@ -0,0 +1,463 @@
+import {
+	defineClientPlugin,
+	createApiClient,
+} from "@btst/stack/plugins/client";
+import { createRoute } from "@btst/yar";
+import type { QueryClient } from "@tanstack/react-query";
+import type { KanbanApiRouter } from "../api";
+import { createKanbanQueryKeys } from "../query-keys";
+import type { SerializedBoardWithColumns } from "../types";
+import { BoardsListPageComponent } from "./components/pages/boards-list-page";
+import { NewBoardPageComponent } from "./components/pages/new-board-page";
+import { BoardPageComponent } from "./components/pages/board-page";
+
+/**
+ * Context passed to route hooks
+ */
+export interface RouteContext {
+	/** Current route path */
+	path: string;
+	/** Route parameters (e.g., { boardId: "abc123" }) */
+	params?: Record<string, string>;
+	/** Whether rendering on server (true) or client (false) */
+	isSSR: boolean;
+	/** Additional context properties */
+	[key: string]: unknown;
+}
+
+/**
+ * Context passed to loader hooks
+ */
+export interface LoaderContext {
+	/** Current route path */
+	path: string;
+	/** Route parameters */
+	params?: Record<string, string>;
+	/** Whether rendering on server (true) or client (false) */
+	isSSR: boolean;
+	/** Base URL for API calls */
+	apiBaseURL: string;
+	/** Path where the API is mounted */
+	apiBasePath: string;
+	/** Optional headers for the request */
+	headers?: Headers;
+	/** Additional context properties */
+	[key: string]: unknown;
+}
+
+/**
+ * Configuration for kanban client plugin
+ */
+export interface KanbanClientConfig {
+	/** Base URL for API calls (e.g., "http://localhost:3000") */
+	apiBaseURL: string;
+	/** Path where the API is mounted (e.g., "/api/data") */
+	apiBasePath: string;
+	/** Base URL of your site for SEO meta tags */
+	siteBaseURL: string;
+	/** Path where pages are mounted (e.g., "/pages") */
+	siteBasePath: string;
+	/** React Query client instance for caching */
+	queryClient: QueryClient;
+
+	/** Optional SEO configuration for meta tags */
+	seo?: {
+		/** Site name for Open Graph tags */
+		siteName?: string;
+		/** Default description */
+		description?: string;
+		/** Locale for Open Graph (e.g., "en_US") */
+		locale?: string;
+		/** Default image URL for social sharing */
+		defaultImage?: string;
+	};
+
+	/** Optional hooks for customizing behavior */
+	hooks?: KanbanClientHooks;
+
+	/** Optional headers for SSR (e.g., forwarding cookies) */
+	headers?: Headers;
+}
+
+/**
+ * Hooks for kanban client plugin
+ * All hooks are optional and allow consumers to customize behavior
+ */
+export interface KanbanClientHooks {
+	/**
+	 * Called before loading boards list. Return false to cancel loading.
+	 */
+	beforeLoadBoards?: (context: LoaderContext) => Promise<boolean> | boolean;
+	/**
+	 * Called after boards are loaded. Return false to cancel further processing.
+	 */
+	afterLoadBoards?: (
+		boards: SerializedBoardWithColumns[] | null,
+		context: LoaderContext,
+	) => Promise<boolean> | boolean;
+	/**
+	 * Called before loading a single board. Return false to cancel loading.
+	 */
+	beforeLoadBoard?: (
+		boardId: string,
+		context: LoaderContext,
+	) => Promise<boolean> | boolean;
+	/**
+	 * Called after a board is loaded. Return false to cancel further processing.
+	 */
+	afterLoadBoard?: (
+		board: SerializedBoardWithColumns | null,
+		boardId: string,
+		context: LoaderContext,
+	) => Promise<boolean> | boolean;
+	/**
+	 * Called before loading the new board page. Return false to cancel.
+	 */
+	beforeLoadNewBoard?: (context: LoaderContext) => Promise<boolean> | boolean;
+	/**
+	 * Called after the new board page is loaded. Return false to cancel.
+	 */
+	afterLoadNewBoard?: (context: LoaderContext) => Promise<boolean> | boolean;
+	/**
+	 * Called when a loading error occurs
+	 */
+	onLoadError?: (error: Error, context: LoaderContext) => Promise<void> | void;
+}
+
+// Loader for SSR prefetching - boards list
+function createBoardsLoader(config: KanbanClientConfig) {
+	return async () => {
+		if (typeof window === "undefined") {
+			const { queryClient, apiBasePath, apiBaseURL, hooks, headers } = config;
+
+			const context: LoaderContext = {
+				path: "/kanban",
+				isSSR: true,
+				apiBaseURL,
+				apiBasePath,
+				headers,
+			};
+
+			try {
+				if (hooks?.beforeLoadBoards) {
+					const canLoad = await hooks.beforeLoadBoards(context);
+					if (!canLoad) {
+						throw new Error("Load prevented by beforeLoadBoards hook");
+					}
+				}
+
+				const client = createApiClient<KanbanApiRouter>({
+					baseURL: apiBaseURL,
+					basePath: apiBasePath,
+				});
+
+				const queries = createKanbanQueryKeys(client, headers);
+				const listQuery = queries.boards.list({});
+
+				await queryClient.prefetchQuery(listQuery);
+
+				if (hooks?.afterLoadBoards) {
+					const boards = queryClient.getQueryData<SerializedBoardWithColumns[]>(
+						listQuery.queryKey,
+					);
+					const canContinue = await hooks.afterLoadBoards(
+						boards || null,
+						context,
+					);
+					if (canContinue === false) {
+						throw new Error("Load prevented by afterLoadBoards hook");
+					}
+				}
+
+				const queryState = queryClient.getQueryState(listQuery.queryKey);
+				if (queryState?.error && hooks?.onLoadError) {
+					const error =
+						queryState.error instanceof Error
+							? queryState.error
+							: new Error(String(queryState.error));
+					await hooks.onLoadError(error, context);
+				}
+			} catch (error) {
+				if (hooks?.onLoadError) {
+					await hooks.onLoadError(error as Error, context);
+				}
+			}
+		}
+	};
+}
+
+// Loader for SSR prefetching - single board
+function createBoardLoader(boardId: string, config: KanbanClientConfig) {
+	return async () => {
+		if (typeof window === "undefined") {
+			const { queryClient, apiBasePath, apiBaseURL, hooks, headers } = config;
+
+			const context: LoaderContext = {
+				path: `/kanban/${boardId}`,
+				params: { boardId },
+				isSSR: true,
+				apiBaseURL,
+				apiBasePath,
+				headers,
+			};
+
+			try {
+				if (hooks?.beforeLoadBoard) {
+					const canLoad = await hooks.beforeLoadBoard(boardId, context);
+					if (!canLoad) {
+						throw new Error("Load prevented by beforeLoadBoard hook");
+					}
+				}
+
+				const client = createApiClient<KanbanApiRouter>({
+					baseURL: apiBaseURL,
+					basePath: apiBasePath,
+				});
+
+				const queries = createKanbanQueryKeys(client, headers);
+				const boardQuery = queries.boards.detail(boardId);
+				await queryClient.prefetchQuery(boardQuery);
+
+				if (hooks?.afterLoadBoard) {
+					const board = queryClient.getQueryData<SerializedBoardWithColumns>(
+						boardQuery.queryKey,
+					);
+					const canContinue = await hooks.afterLoadBoard(
+						board || null,
+						boardId,
+						context,
+					);
+					if (canContinue === false) {
+						throw new Error("Load prevented by afterLoadBoard hook");
+					}
+				}
+
+				const queryState = queryClient.getQueryState(boardQuery.queryKey);
+				if (queryState?.error && hooks?.onLoadError) {
+					const error =
+						queryState.error instanceof Error
+							? queryState.error
+							: new Error(String(queryState.error));
+					await hooks.onLoadError(error, context);
+				}
+			} catch (error) {
+				if (hooks?.onLoadError) {
+					await hooks.onLoadError(error as Error, context);
+				}
+			}
+		}
+	};
+}
+
+// Loader for new board page
+function createNewBoardLoader(config: KanbanClientConfig) {
+	return async () => {
+		if (typeof window === "undefined") {
+			const { apiBasePath, apiBaseURL, hooks, headers } = config;
+
+			const context: LoaderContext = {
+				path: "/kanban/new",
+				isSSR: true,
+				apiBaseURL,
+				apiBasePath,
+				headers,
+			};
+
+			try {
+				if (hooks?.beforeLoadNewBoard) {
+					const canLoad = await hooks.beforeLoadNewBoard(context);
+					if (!canLoad) {
+						throw new Error("Load prevented by beforeLoadNewBoard hook");
+					}
+				}
+
+				if (hooks?.afterLoadNewBoard) {
+					const canContinue = await hooks.afterLoadNewBoard(context);
+					if (canContinue === false) {
+						throw new Error("Load prevented by afterLoadNewBoard hook");
+					}
+				}
+			} catch (error) {
+				if (hooks?.onLoadError) {
+					await hooks.onLoadError(error as Error, context);
+				}
+			}
+		}
+	};
+}
+
+// Meta generators
+function createBoardsListMeta(config: KanbanClientConfig) {
+	return () => {
+		const { siteBaseURL, siteBasePath, seo } = config;
+		const fullUrl = `${siteBaseURL}${siteBasePath}/kanban`;
+		const title = "Kanban Boards";
+		const description =
+			seo?.description || "Manage your projects with kanban boards";
+
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "description", content: description },
+			{ name: "robots", content: "index, follow" },
+			{ property: "og:type", content: "website" },
+			{ property: "og:title", content: title },
+			{ property: "og:description", content: description },
+			{ property: "og:url", content: fullUrl },
+			...(seo?.siteName
+				? [{ property: "og:site_name", content: seo.siteName }]
+				: []),
+			...(seo?.locale ? [{ property: "og:locale", content: seo.locale }] : []),
+			...(seo?.defaultImage
+				? [{ property: "og:image", content: seo.defaultImage }]
+				: []),
+			{ name: "twitter:card", content: "summary" },
+			{ name: "twitter:title", content: title },
+			{ name: "twitter:description", content: description },
+		];
+	};
+}
+
+function createBoardMeta(boardId: string, config: KanbanClientConfig) {
+	return () => {
+		const {
+			queryClient,
+			apiBaseURL,
+			apiBasePath,
+			siteBaseURL,
+			siteBasePath,
+			seo,
+		} = config;
+		const queries = createKanbanQueryKeys(
+			createApiClient<KanbanApiRouter>({
+				baseURL: apiBaseURL,
+				basePath: apiBasePath,
+			}),
+		);
+		const board = queryClient.getQueryData<SerializedBoardWithColumns>(
+			queries.boards.detail(boardId).queryKey,
+		);
+
+		if (!board) {
+			return [
+				{ title: "Board Not Found" },
+				{ name: "robots", content: "noindex" },
+			];
+		}
+
+		const fullUrl = `${siteBaseURL}${siteBasePath}/kanban/${board.id}`;
+		const title = board.name;
+		const description = board.description || `Kanban board: ${board.name}`;
+
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "description", content: description },
+			{ name: "robots", content: "index, follow" },
+			{ property: "og:type", content: "website" },
+			{ property: "og:title", content: title },
+			{ property: "og:description", content: description },
+			{ property: "og:url", content: fullUrl },
+			...(seo?.siteName
+				? [{ property: "og:site_name", content: seo.siteName }]
+				: []),
+			...(seo?.defaultImage
+				? [{ property: "og:image", content: seo.defaultImage }]
+				: []),
+			{ name: "twitter:card", content: "summary" },
+			{ name: "twitter:title", content: title },
+		];
+	};
+}
+
+function createNewBoardMeta(config: KanbanClientConfig) {
+	return () => {
+		const { siteBaseURL, siteBasePath } = config;
+		const fullUrl = `${siteBaseURL}${siteBasePath}/kanban/new`;
+		const title = "Create New Board";
+
+		return [
+			{ title },
+			{ name: "title", content: title },
+			{ name: "description", content: "Create a new kanban board" },
+			{ name: "robots", content: "noindex, nofollow" },
+			{ property: "og:type", content: "website" },
+			{ property: "og:title", content: title },
+			{ property: "og:url", content: fullUrl },
+			{ name: "twitter:card", content: "summary" },
+			{ name: "twitter:title", content: title },
+		];
+	};
+}
+
+/**
+ * Kanban client plugin
+ * Provides routes, components, and React Query hooks for kanban boards
+ */
+export const kanbanClientPlugin = (config: KanbanClientConfig) =>
+	defineClientPlugin({
+		name: "kanban",
+
+		routes: () => ({
+			boards: createRoute("/kanban", () => {
+				return {
+					PageComponent: () => <BoardsListPageComponent />,
+					loader: createBoardsLoader(config),
+					meta: createBoardsListMeta(config),
+				};
+			}),
+			newBoard: createRoute("/kanban/new", () => {
+				return {
+					PageComponent: NewBoardPageComponent,
+					loader: createNewBoardLoader(config),
+					meta: createNewBoardMeta(config),
+				};
+			}),
+			board: createRoute("/kanban/:boardId", ({ params: { boardId } }) => {
+				return {
+					PageComponent: () => <BoardPageComponent boardId={boardId} />,
+					loader: createBoardLoader(boardId, config),
+					meta: createBoardMeta(boardId, config),
+				};
+			}),
+		}),
+
+		sitemap: async () => {
+			const origin = `${config.siteBaseURL}${config.siteBasePath}`;
+			const indexUrl = `${origin}/kanban`;
+
+			const client = createApiClient<KanbanApiRouter>({
+				baseURL: config.apiBaseURL,
+				basePath: config.apiBasePath,
+			});
+
+			let boards: SerializedBoardWithColumns[] = [];
+			try {
+				const res = await client("/boards", {
+					method: "GET",
+					query: { limit: 100 },
+				});
+				boards = ((res as { data?: unknown }).data ??
+					[]) as SerializedBoardWithColumns[];
+			} catch {
+				// Ignore errors for sitemap
+			}
+
+			const entries = [
+				{
+					url: indexUrl,
+					lastModified: new Date(),
+					changeFrequency: "daily" as const,
+					priority: 0.7,
+				},
+				...boards.map((b) => ({
+					url: `${origin}/kanban/${b.id}`,
+					lastModified: b.updatedAt ? new Date(b.updatedAt) : undefined,
+					changeFrequency: "weekly" as const,
+					priority: 0.6,
+				})),
+			];
+
+			return entries;
+		},
+	});