@questpie/admin 0.0.1

package/src/hooks/use-auth.ts

@@ -0,0 +1,168 @@
+/**
+ * Auth client utilities for admin package
+ *
+ * Better Auth handles all auth state management internally.
+ * This module provides type-safe client creation helpers with
+ * full type inference from your CMS auth configuration.
+ *
+ * @example
+ * ```tsx
+ * // In your app, create the auth client once:
+ * import { createAdminAuthClient } from '@questpie/admin/hooks'
+ * import type { cms } from './server/cms'
+ *
+ * export const authClient = createAdminAuthClient<typeof cms>({
+ *   baseURL: 'http://localhost:3000'
+ * })
+ *
+ * // Then use the built-in hooks:
+ * function MyComponent() {
+ *   const { data: session, isPending, error } = authClient.useSession()
+ *
+ *   if (isPending) return <div>Loading...</div>
+ *   if (!session) return <LoginForm />
+ *
+ *   return <div>Welcome {session.user.name}</div>
+ * }
+ * ```
+ */
+
+import { createAuthClient } from "better-auth/react";
+import type { Questpie } from "questpie";
+import type { BetterAuthOptions } from "better-auth";
+
+/**
+ * Extract auth options type from Questpie instance
+ */
+type ExtractAuthOptions<T extends Questpie<any>> =
+	T extends Questpie<infer TConfig>
+		? TConfig["auth"] extends BetterAuthOptions
+			? TConfig["auth"]
+			: BetterAuthOptions
+		: BetterAuthOptions;
+
+/**
+ * Options for creating admin auth client
+ */
+export type AdminAuthClientOptions = {
+	/**
+	 * Base URL of the CMS API
+	 * @example 'http://localhost:3000'
+	 */
+	baseURL: string;
+
+	/**
+	 * Base path for auth routes
+	 * @default '/cms/auth'
+	 */
+	basePath?: string;
+
+	/**
+	 * Custom fetch implementation
+	 */
+	fetchOptions?: {
+		credentials?: RequestCredentials;
+		headers?: Record<string, string>;
+	};
+};
+
+/**
+ * Internal client options type that includes $InferAuth
+ */
+type InternalClientOptions<T extends Questpie<any>> = {
+	baseURL: string;
+	fetchOptions?: {
+		credentials?: RequestCredentials;
+		headers?: Record<string, string>;
+	};
+	$InferAuth: ExtractAuthOptions<T>;
+};
+
+/**
+ * Create a type-safe Better Auth client for the admin UI
+ *
+ * The returned client includes full type inference from your CMS auth configuration:
+ * - `useSession()` - React hook for session state (typed based on your user/session schema)
+ * - `signIn` methods (email, social providers configured in CMS)
+ * - `signOut` - Sign out the current user
+ * - `signUp` - Register new users
+ * - Plugin-specific hooks (e.g., `useListAccounts` for admin plugin)
+ *
+ * @example
+ * ```tsx
+ * import { createAdminAuthClient } from '@questpie/admin/hooks'
+ * import type { cms } from './server/cms'
+ *
+ * // Create client with type inference from your CMS
+ * export const authClient = createAdminAuthClient<typeof cms>({
+ *   baseURL: 'http://localhost:3000'
+ * })
+ *
+ * // Session data is fully typed based on your CMS auth config
+ * function App() {
+ *   const { data: session, isPending } = authClient.useSession()
+ *
+ *   if (isPending) return <Loading />
+ *   if (!session) return <LoginPage authClient={authClient} />
+ *
+ *   // session.user has all fields from your user schema
+ *   return <AdminDashboard user={session.user} />
+ * }
+ * ```
+ */
+export function createAdminAuthClient<T extends Questpie<any>>(
+	options: AdminAuthClientOptions,
+): ReturnType<typeof createAuthClient<InternalClientOptions<T>>> {
+	const basePath = options.basePath ?? "/cms/auth";
+
+	return createAuthClient<InternalClientOptions<T>>({
+		baseURL: `${options.baseURL}${basePath}`,
+		fetchOptions: {
+			credentials: options.fetchOptions?.credentials ?? "include",
+			headers: options.fetchOptions?.headers,
+		},
+	} as InternalClientOptions<T>);
+}
+
+/**
+ * Type helper to extract auth client type from CMS instance
+ *
+ * @example
+ * ```tsx
+ * import type { AdminAuthClient } from '@questpie/admin/hooks'
+ * import type { cms } from './server/cms'
+ *
+ * type MyAuthClient = AdminAuthClient<typeof cms>
+ * ```
+ */
+export type AdminAuthClient<T extends Questpie<any>> = ReturnType<
+	typeof createAdminAuthClient<T>
+>;
+
+/**
+ * Type helper to extract session type from auth client
+ *
+ * @example
+ * ```tsx
+ * import type { AdminSession } from '@questpie/admin/hooks'
+ * import type { cms } from './server/cms'
+ *
+ * type MySession = AdminSession<typeof cms>
+ * // Includes: { user: { id, email, name, role, ... }, session: { ... } }
+ * ```
+ */
+export type AdminSession<T extends Questpie<any>> =
+	AdminAuthClient<T>["$Infer"]["Session"];
+
+/**
+ * Type helper to extract user type from CMS auth configuration
+ *
+ * @example
+ * ```tsx
+ * import type { AdminUser } from '@questpie/admin/hooks'
+ * import type { cms } from './server/cms'
+ *
+ * type MyUser = AdminUser<typeof cms>
+ * ```
+ */
+export type AdminUser<T extends Questpie<any>> = AdminSession<T>["user"];

package/src/hooks/use-collection-db.ts

@@ -0,0 +1,209 @@
+import { useMemo } from "react";
+import type { Collection } from "@tanstack/db";
+import type { QuestpieClient } from "questpie/client";
+import type { Questpie } from "questpie";
+import { createQuestpieDBHelpers } from "@questpie/tanstack-query/db";
+import { useAdminContext } from "./admin-provider";
+import { useQueryClient } from "@tanstack/react-query";
+
+/**
+ * Collection item type helper
+ * Extracts the item type from a collection's find method return type
+ */
+type CollectionItem<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+> = Awaited<ReturnType<QuestpieClient<T>["collections"][K]["find"]>> extends {
+	docs: Array<infer TItem extends object>;
+}
+	? TItem
+	: Record<string, unknown>;
+
+/**
+ * Hook to get TanStack DB Collection for a CMS collection
+ * Provides offline-first, realtime-synced collection with optimistic updates
+ *
+ * @example
+ * ```tsx
+ * function PostsList() {
+ *   const posts = useCollection('posts', {
+ *     baseFindOptions: { where: { published: { eq: true } } },
+ *     realtime: true, // Enable realtime sync
+ *   })
+ *
+ *   return (
+ *     <div>
+ *       {posts.items.map(post => (
+ *         <div key={post.id}>{post.title}</div>
+ *       ))}
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+export function useCollection<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(
+	collectionName: K,
+	options?: {
+		/**
+		 * Base query options (filters, sorting, relations)
+		 */
+		baseFindOptions?: Parameters<QuestpieClient<T>["collections"][K]["find"]>[0];
+		/**
+		 * Enable realtime sync via SSE
+		 */
+		realtime?:
+			| boolean
+			| {
+					enabled?: boolean;
+					baseURL?: string;
+					basePath?: string;
+			  };
+		/**
+		 * Custom key extractor (defaults to 'id')
+		 */
+		getKey?: (item: CollectionItem<T, K>) => string | number;
+	},
+): Collection<CollectionItem<T, K>, string | number> {
+	const { client, locale } = useAdminContext<T>();
+	const queryClient = useQueryClient();
+	const localeKey = locale ?? "default";
+
+	const collection = useMemo(() => {
+		const dbHelpers = createQuestpieDBHelpers(client, {
+			keyPrefix: ["qcms", "locale", localeKey],
+		});
+		const collectionHelper = dbHelpers.collections[collectionName as string];
+
+		if (!collectionHelper) {
+			throw new Error(
+				`Collection "${String(collectionName)}" not found in CMS`,
+			);
+		}
+
+		return collectionHelper.createCollection({
+			queryClient,
+			getKey: options?.getKey ?? ((item: any) => item.id),
+			baseFindOptions: options?.baseFindOptions,
+			realtime: options?.realtime ?? false,
+		} as any);
+	}, [
+		client,
+		queryClient,
+		collectionName,
+		localeKey,
+		options?.baseFindOptions,
+		options?.realtime,
+		options?.getKey,
+	]);
+
+	return collection as Collection<CollectionItem<T, K>, string | number>;
+}
+
+/**
+ * Hook to get a single item from collection by ID
+ * Uses TanStack DB Collection for offline-first access
+ *
+ * @example
+ * ```tsx
+ * function PostDetail({ id }: { id: string }) {
+ *   const posts = useCollection('posts')
+ *   const post = useCollectionItemById(posts, id)
+ *
+ *   if (!post) return <div>Loading...</div>
+ *
+ *   return <div>{post.title}</div>
+ * }
+ * ```
+ */
+export function useCollectionItemById<TItem extends object>(
+	collection: Collection<TItem, string | number>,
+	id: string | number,
+): TItem | undefined {
+	return collection.toArray.find(
+		(item) => collection.config.getKey(item) === id,
+	);
+}
+
+/**
+ * Hook to create item in collection
+ * Uses TanStack DB Collection with optimistic updates
+ *
+ * @example
+ * ```tsx
+ * function CreatePost() {
+ *   const posts = useCollection('posts')
+ *
+ *   const handleCreate = async () => {
+ *     await posts.insert({
+ *       title: 'New Post',
+ *       content: 'Hello World'
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleCreate}>Create Post</button>
+ * }
+ * ```
+ */
+export function useCollectionInsert<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(collectionName: K): any {
+	const collection = useCollection<T, K>(collectionName);
+	return collection.insert.bind(collection);
+}
+
+/**
+ * Hook to update item in collection
+ * Uses TanStack DB Collection with optimistic updates
+ *
+ * @example
+ * ```tsx
+ * function EditPost({ id }: { id: string }) {
+ *   const posts = useCollection('posts')
+ *   const post = useCollectionItemById(posts, id)
+ *
+ *   const handleUpdate = async () => {
+ *     await posts.update(id, {
+ *       title: 'Updated Title'
+ *     })
+ *   }
+ *
+ *   return <button onClick={handleUpdate}>Update</button>
+ * }
+ * ```
+ */
+export function useCollectionUpdate<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(collectionName: K): any {
+	const collection = useCollection<T, K>(collectionName);
+	return collection.update.bind(collection);
+}
+
+/**
+ * Hook to delete item from collection
+ * Uses TanStack DB Collection with optimistic updates
+ *
+ * @example
+ * ```tsx
+ * function DeletePost({ id }: { id: string }) {
+ *   const posts = useCollection('posts')
+ *
+ *   const handleDelete = async () => {
+ *     await posts.delete(id)
+ *   }
+ *
+ *   return <button onClick={handleDelete}>Delete</button>
+ * }
+ * ```
+ */
+export function useCollectionDelete<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(collectionName: K): any {
+	const collection = useCollection<T, K>(collectionName);
+	return collection.delete.bind(collection);
+}

package/src/hooks/use-collection.ts

@@ -0,0 +1,156 @@
+import {
+	useQuery,
+	useMutation,
+	useQueryClient,
+	type UseQueryOptions,
+	type UseMutationOptions,
+} from "@tanstack/react-query";
+import type { QuestpieClient } from "questpie/client";
+import type { Questpie } from "questpie";
+import { createQuestpieQueryOptions } from "@questpie/tanstack-query";
+
+import { useAdminContext } from "./admin-provider";
+
+/**
+ * Hook to fetch collection list with filters, sorting, pagination
+ */
+export function useCollectionList<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(
+	collection: K,
+	options?: Parameters<QuestpieClient<T>["collections"][K]["find"]>[0],
+	queryOptions?: Omit<UseQueryOptions, "queryKey" | "queryFn">,
+): any {
+	const { client, locale } = useAdminContext<T>();
+	const localeKey = locale ?? "default";
+	const keyPrefix = ["qcms", "locale", localeKey] as const;
+	const queryOpts = createQuestpieQueryOptions(client, { keyPrefix });
+
+	return useQuery({
+		...queryOpts.collections[collection as string].find(options as any),
+		...queryOptions,
+	});
+}
+
+/**
+ * Hook to fetch single collection item
+ */
+export function useCollectionItem<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(
+	collection: K,
+	id: string,
+	options?: Omit<
+		Parameters<QuestpieClient<T>["collections"][K]["findOne"]>[0],
+		"where"
+	>,
+	queryOptions?: Omit<UseQueryOptions, "queryKey" | "queryFn">,
+): any {
+	const { client, locale } = useAdminContext<T>();
+	const localeKey = locale ?? "default";
+	const keyPrefix = ["qcms", "locale", localeKey] as const;
+	const queryOpts = createQuestpieQueryOptions(client, { keyPrefix });
+
+	return useQuery({
+		...queryOpts.collections[collection as string].findOne({
+			where: { id },
+			...options,
+		} as any),
+		...queryOptions,
+	});
+}
+
+/**
+ * Hook to create collection item
+ */
+export function useCollectionCreate<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(
+	collection: K,
+	mutationOptions?: Omit<UseMutationOptions, "mutationFn">,
+): any {
+	const { client, locale } = useAdminContext<T>();
+	const queryClient = useQueryClient();
+	const localeKey = locale ?? "default";
+	const keyPrefix = ["qcms", "locale", localeKey] as const;
+	const queryOpts = createQuestpieQueryOptions(client, { keyPrefix });
+
+	const baseOptions = queryOpts.collections[collection as string].create();
+
+	return useMutation({
+		...baseOptions,
+		onSuccess: (data: any, variables: any, context: any) => {
+			// Invalidate list queries
+			queryClient.invalidateQueries({
+				queryKey: [...keyPrefix, "collections", collection, "find"],
+			});
+			(mutationOptions?.onSuccess as any)?.(data, variables, context);
+		},
+		...mutationOptions,
+	} as any);
+}
+
+/**
+ * Hook to update collection item
+ */
+export function useCollectionUpdate<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(
+	collection: K,
+	mutationOptions?: Omit<UseMutationOptions, "mutationFn">,
+): any {
+	const { client, locale } = useAdminContext<T>();
+	const queryClient = useQueryClient();
+	const localeKey = locale ?? "default";
+	const keyPrefix = ["qcms", "locale", localeKey] as const;
+	const queryOpts = createQuestpieQueryOptions(client, { keyPrefix });
+
+	const baseOptions = queryOpts.collections[collection as string].update();
+
+	return useMutation({
+		...baseOptions,
+		onSuccess: (data: any, variables: any, context: any) => {
+			// Invalidate list and detail queries
+			queryClient.invalidateQueries({
+				queryKey: [...keyPrefix, "collections", collection],
+			});
+			(mutationOptions?.onSuccess as any)?.(data, variables, context);
+		},
+		...mutationOptions,
+	} as any);
+}
+
+/**
+ * Hook to delete collection item
+ */
+export function useCollectionDelete<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["collections"],
+>(
+	collection: K,
+	mutationOptions?: Omit<UseMutationOptions, "mutationFn">,
+): any {
+	const { client, locale } = useAdminContext<T>();
+	const queryClient = useQueryClient();
+	const localeKey = locale ?? "default";
+	const keyPrefix = ["qcms", "locale", localeKey] as const;
+	const queryOpts = createQuestpieQueryOptions(client, { keyPrefix });
+
+	const baseOptions = queryOpts.collections[collection as string].delete();
+
+	return useMutation({
+		...baseOptions,
+		onSuccess: (data: any, variables: any, context: any) => {
+			// Invalidate list queries
+			queryClient.invalidateQueries({
+				queryKey: [...keyPrefix, "collections", collection],
+			});
+			(mutationOptions?.onSuccess as any)?.(data, variables, context);
+		},
+		...mutationOptions,
+	} as any);
+}

package/src/hooks/use-global.ts

@@ -0,0 +1,69 @@
+import {
+	useQuery,
+	useMutation,
+	useQueryClient,
+	type UseQueryOptions,
+	type UseMutationOptions,
+} from "@tanstack/react-query";
+import type { QuestpieClient } from "questpie/client";
+import type { Questpie } from "questpie";
+import { createQuestpieQueryOptions } from "@questpie/tanstack-query";
+import { useAdminContext } from "./admin-provider";
+
+/**
+ * Hook to fetch global settings
+ */
+export function useGlobal<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["globals"],
+>(
+	globalName: K,
+	options?: Parameters<QuestpieClient<T>["globals"][K]["get"]>[0],
+	queryOptions?: Omit<UseQueryOptions, "queryKey" | "queryFn">,
+): any {
+	const { client, locale } = useAdminContext<T>();
+	const localeKey = locale ?? "default";
+	const keyPrefix = ["qcms", "locale", localeKey] as const;
+	const queryOpts = createQuestpieQueryOptions(client, { keyPrefix });
+
+	return useQuery({
+		...queryOpts.globals[globalName as string].get(options as any),
+		...queryOptions,
+	});
+}
+
+/**
+ * Hook to update global settings
+ */
+export function useGlobalUpdate<
+	T extends Questpie<any>,
+	K extends keyof QuestpieClient<T>["globals"],
+>(
+	globalName: K,
+	mutationOptions?: UseMutationOptions<
+		Awaited<ReturnType<QuestpieClient<T>["globals"][K]["update"]>>,
+		Error,
+		{
+			data: Parameters<QuestpieClient<T>["globals"][K]["update"]>[0];
+			options?: Parameters<QuestpieClient<T>["globals"][K]["update"]>[1];
+		}
+	>,
+): any {
+	const { client, locale } = useAdminContext<T>();
+	const queryClient = useQueryClient();
+	const localeKey = locale ?? "default";
+	const keyPrefix = ["qcms", "locale", localeKey] as const;
+	const queryOpts = createQuestpieQueryOptions(client, { keyPrefix });
+
+	return useMutation({
+		...queryOpts.globals[globalName as string].update(),
+		onSuccess: (...args) => {
+			// Invalidate global queries
+			queryClient.invalidateQueries({
+				queryKey: [...keyPrefix, "globals", globalName],
+			});
+			mutationOptions?.onSuccess?.(...args);
+		},
+		...mutationOptions,
+	});
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,21 @@
+import * as React from "react";
+
+const MOBILE_BREAKPOINT = 768;
+
+export function useIsMobile() {
+	const [isMobile, setIsMobile] = React.useState<boolean | undefined>(
+		undefined,
+	);
+
+	React.useEffect(() => {
+		const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+		const onChange = () => {
+			setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+		};
+		mql.addEventListener("change", onChange);
+		setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+		return () => mql.removeEventListener("change", onChange);
+	}, []);
+
+	return !!isMobile;
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]): string {
+	return twMerge(clsx(inputs));
+}