@questpie/admin 0.0.1

package/src/hooks/README.md

@@ -0,0 +1,269 @@
+# Admin Hooks - TanStack DB Integration
+
+Admin hooks sú postavené na **TanStack DB Collections** pre offline-first, realtime data management.
+
+## Výhody TanStack DB
+
+✅ **Offline-first** - Data sú dostupné aj bez pripojenia
+✅ **Optimistic updates** - Okamžitá UI odozva
+✅ **Realtime sync** - Automatická synchronizácia cez SSE
+✅ **Better DX** - Jednoduchšie API než query/mutation hooks
+✅ **Built-in caching** - Inteligentné cache management
+
+## Basic Usage
+
+### 1. Setup AdminProvider
+
+```tsx
+import { AdminProvider } from '@questpie/admin/hooks'
+import { createQCMSClient } from '@questpie/cms/client'
+import { QueryClient } from '@tanstack/react-query'
+import type { cms } from './server/cms'
+
+const client = createQCMSClient<typeof cms>({
+  baseURL: 'http://localhost:3000'
+})
+
+const queryClient = new QueryClient()
+
+function App() {
+  return (
+    <AdminProvider client={client} queryClient={queryClient}>
+      <YourAdminApp />
+    </AdminProvider>
+  )
+}
+```
+
+### 2. Use Collection Hook
+
+```tsx
+import { useCollection } from '@questpie/admin/hooks'
+import type { cms } from './server/cms'
+
+function PostsList() {
+  const posts = useCollection<typeof cms, 'posts'>('posts', {
+    // Optional: Add filters
+    baseFindOptions: {
+      where: { published: { eq: true } },
+      orderBy: { createdAt: 'desc' },
+    },
+    // Enable realtime sync
+    realtime: true,
+  })
+
+  return (
+    <div>
+      <h1>Posts ({posts.items.length})</h1>
+      {posts.items.map(post => (
+        <div key={post.id}>
+          <h2>{post.title}</h2>
+          <p>{post.content}</p>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 3. Create Item (Optimistic Update)
+
+```tsx
+import { useCollection } from '@questpie/admin/hooks'
+
+function CreatePost() {
+  const posts = useCollection<typeof cms, 'posts'>('posts')
+
+  const handleCreate = async () => {
+    // Optimistic insert - UI updates immediately
+    await posts.insert({
+      title: 'New Post',
+      content: 'Hello World',
+      published: false,
+    })
+  }
+
+  return (
+    <button onClick={handleCreate}>
+      Create Post
+    </button>
+  )
+}
+```
+
+### 4. Update Item (Optimistic Update)
+
+```tsx
+import { useCollection, useCollectionItemById } from '@questpie/admin/hooks'
+
+function EditPost({ id }: { id: string }) {
+  const posts = useCollection<typeof cms, 'posts'>('posts')
+  const post = useCollectionItemById(posts, id)
+
+  const handleUpdate = async () => {
+    if (!post) return
+
+    // Optimistic update - UI updates immediately
+    await posts.update(id, {
+      title: 'Updated Title',
+    })
+  }
+
+  if (!post) return <div>Loading...</div>
+
+  return (
+    <div>
+      <h1>{post.title}</h1>
+      <button onClick={handleUpdate}>Update Title</button>
+    </div>
+  )
+}
+```
+
+### 5. Delete Item (Optimistic Update)
+
+```tsx
+import { useCollection } from '@questpie/admin/hooks'
+
+function DeletePost({ id }: { id: string }) {
+  const posts = useCollection<typeof cms, 'posts'>('posts')
+
+  const handleDelete = async () => {
+    // Optimistic delete - UI updates immediately
+    await posts.delete(id)
+  }
+
+  return (
+    <button onClick={handleDelete}>
+      Delete
+    </button>
+  )
+}
+```
+
+## Advanced Usage
+
+### Realtime Sync with Custom Config
+
+```tsx
+const posts = useCollection<typeof cms, 'posts'>('posts', {
+  realtime: {
+    enabled: true,
+    baseURL: 'http://localhost:3000',
+    basePath: '/cms',
+  },
+})
+```
+
+### With Relations (Eager Loading)
+
+```tsx
+const posts = useCollection<typeof cms, 'posts'>('posts', {
+  baseFindOptions: {
+    with: {
+      author: true,
+      tags: true,
+    },
+  },
+})
+
+// Now posts.items include author and tags data
+posts.items.forEach(post => {
+  console.log(post.author?.name)
+  console.log(post.tags?.map(t => t.name))
+})
+```
+
+### Filter & Sort
+
+```tsx
+const posts = useCollection<typeof cms, 'posts'>('posts', {
+  baseFindOptions: {
+    where: {
+      AND: [
+        { published: { eq: true } },
+        { createdAt: { gte: new Date('2024-01-01') } },
+      ],
+    },
+    orderBy: { createdAt: 'desc' },
+    limit: 10,
+  },
+})
+```
+
+### Pagination with LoadSubset
+
+```tsx
+import { useCollection } from '@questpie/admin/hooks'
+
+function PaginatedPosts() {
+  const posts = useCollection<typeof cms, 'posts'>('posts')
+
+  const handleLoadMore = () => {
+    posts.loadSubset({
+      limit: 10,
+      offset: posts.items.length,
+    })
+  }
+
+  return (
+    <div>
+      {posts.items.map(post => (
+        <div key={post.id}>{post.title}</div>
+      ))}
+      <button onClick={handleLoadMore}>Load More</button>
+    </div>
+  )
+}
+```
+
+## API Reference
+
+### `useCollection(collectionName, options)`
+
+Returns a TanStack DB Collection with full CRUD operations.
+
+**Options:**
+- `baseFindOptions` - Initial query (filters, sorting, relations)
+- `realtime` - Enable SSE realtime sync (boolean or config object)
+- `getKey` - Custom key extractor (defaults to `item.id`)
+
+**Returns Collection with:**
+- `items` - Array of collection items
+- `insert(data)` - Create new item (optimistic)
+- `update(id, data)` - Update item (optimistic)
+- `delete(id)` - Delete item (optimistic)
+- `loadSubset(options)` - Load more items with filters
+- `replaceAll(items)` - Replace all items (for realtime)
+
+### `useCollectionItemById(collection, id)`
+
+Get single item from collection by ID (offline-first).
+
+### `useCollectionInsert(collectionName)`
+
+Get insert function for collection.
+
+### `useCollectionUpdate(collectionName)`
+
+Get update function for collection.
+
+### `useCollectionDelete(collectionName)`
+
+Get delete function for collection.
+
+## Legacy Query/Mutation Hooks
+
+For backward compatibility, query/mutation hooks are still available:
+
+```tsx
+import {
+  useCollectionList,
+  useCollectionItem,
+  useCollectionCreate,
+  useCollectionUpdateMutation,
+  useCollectionDeleteMutation,
+} from '@questpie/admin/hooks'
+```
+
+**Recommendation:** Use TanStack DB hooks (`useCollection`) for better DX and offline-first support.

package/src/hooks/admin-provider.tsx

@@ -0,0 +1,110 @@
+import React, { createContext, useContext } from "react";
+import type { QuestpieClient } from "questpie/client";
+import type { Questpie } from "questpie";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+/**
+ * Admin context - provides access to CMS client
+ */
+export type AdminContext<T extends Questpie<any>> = {
+	client: QuestpieClient<T>;
+	locale?: string;
+	setLocale?: (locale: string) => void;
+	locales?: {
+		default: string;
+		available: string[];
+	};
+};
+
+const AdminContextInstance = createContext<AdminContext<any> | null>(null);
+
+/**
+ * Hook to access admin context
+ */
+export function useAdminContext<T extends Questpie<any>>(): AdminContext<T> {
+	const context = useContext(AdminContextInstance);
+	if (!context) {
+		throw new Error(
+			"useAdminContext must be used within AdminProvider. Wrap your app with <AdminProvider client={client}>",
+		);
+	}
+	return context;
+}
+
+/**
+ * Admin provider props
+ */
+export type AdminProviderProps<T extends Questpie<any>> = {
+	client: QuestpieClient<T>;
+	queryClient?: QueryClient;
+	locales?: {
+		default: string;
+		available: string[];
+	};
+	children: React.ReactNode;
+};
+
+/**
+ * Admin provider - provides CMS client and query client to the app
+ *
+ * @example
+ * ```tsx
+ * import { AdminProvider } from '@questpie/admin/hooks'
+ * import { createQuestpieClient } from 'questpie/client'
+ * import { QueryClient } from '@tanstack/react-query'
+ * import type { cms } from './server/cms'
+ *
+ * const client = createQuestpieClient<typeof cms>({
+ *   baseURL: 'http://localhost:3000'
+ * })
+ *
+ * const queryClient = new QueryClient()
+ *
+ * function App() {
+ *   return (
+ *     <AdminProvider client={client} queryClient={queryClient}>
+ *       <YourAdminApp />
+ *     </AdminProvider>
+ *   )
+ * }
+ * ```
+ */
+export function AdminProvider<T extends Questpie<any>>({
+	client,
+	queryClient,
+	locales,
+	children,
+}: AdminProviderProps<T>): React.ReactElement {
+	const [defaultQueryClient] = React.useState(
+		() => queryClient ?? new QueryClient(),
+	);
+	const [locale, setLocale] = React.useState(() => {
+		if (locales?.default) return locales.default;
+		if (locales?.available?.length) return locales.available[0];
+		return typeof client.getLocale === "function"
+			? client.getLocale()
+			: undefined;
+	});
+
+	React.useEffect(() => {
+		if (!locales?.available?.length) return;
+		if (!locale || !locales.available.includes(locale)) {
+			setLocale(locales.default ?? locales.available[0]);
+		}
+	}, [locale, locales]);
+
+	React.useEffect(() => {
+		if (typeof client.setLocale !== "function") return;
+		client.setLocale(locale);
+	}, [client, locale]);
+
+	return (
+		<AdminContextInstance.Provider
+			value={{ client, locale, setLocale, locales }}
+		>
+			<QueryClientProvider client={defaultQueryClient}>
+				{children}
+			</QueryClientProvider>
+		</AdminContextInstance.Provider>
+	);
+}

package/src/hooks/index.ts

@@ -0,0 +1,41 @@
+/**
+ * React hooks for admin package
+ */
+
+// Provider and context
+export { AdminProvider, useAdminContext } from "./admin-provider";
+export type { AdminProviderProps, AdminContext } from "./admin-provider";
+
+// Auth client (Better Auth integration)
+export { createAdminAuthClient } from "./use-auth";
+export type {
+	AdminAuthClient,
+	AdminAuthClientOptions,
+	AdminSession,
+	AdminUser,
+} from "./use-auth";
+
+// Jotai state management
+// TODO: Add explicit types for isolatedDeclarations support
+// export * from "./store";
+
+// TanStack DB Collection hooks (recommended - offline-first, realtime)
+export {
+	useCollection,
+	useCollectionItemById,
+	useCollectionInsert,
+	useCollectionUpdate,
+	useCollectionDelete,
+} from "./use-collection-db";
+
+// Legacy TanStack Query hooks (for backward compatibility)
+export {
+	useCollectionList,
+	useCollectionItem,
+	useCollectionCreate,
+	useCollectionUpdate as useCollectionUpdateMutation,
+	useCollectionDelete as useCollectionDeleteMutation,
+} from "./use-collection";
+
+// Global hooks
+export { useGlobal, useGlobalUpdate } from "./use-global";

package/src/hooks/store.ts

@@ -0,0 +1,248 @@
+/**
+ * Jotai Store for Admin State Management
+ *
+ * Centralized state atoms for the admin UI.
+ * Uses Jotai for reactive, atomic state management.
+ */
+
+import { atom, useAtom, useAtomValue, useSetAtom } from "jotai";
+import { atomWithStorage } from "jotai/utils";
+
+// ============================================================================
+// UI State Atoms
+// ============================================================================
+
+/**
+ * Sidebar collapsed state (persisted to localStorage)
+ */
+export const sidebarCollapsedAtom = atomWithStorage(
+	"admin:sidebar-collapsed",
+	false,
+);
+
+/**
+ * Current active locale
+ */
+export const localeAtom = atom<string | null>(null);
+
+/**
+ * Available locales configuration
+ */
+export const localesConfigAtom = atom<{
+	default: string;
+	available: string[];
+} | null>(null);
+
+/**
+ * Mobile menu open state
+ */
+export const mobileMenuOpenAtom = atom(false);
+
+/**
+ * Command palette open state
+ */
+export const commandPaletteOpenAtom = atom(false);
+
+// ============================================================================
+// Theme Atoms
+// ============================================================================
+
+/**
+ * Theme mode (persisted to localStorage)
+ */
+export type ThemeMode = "light" | "dark" | "system";
+
+export const themeModeAtom = atomWithStorage<ThemeMode>(
+	"admin:theme-mode",
+	"system",
+);
+
+/**
+ * Derived atom for resolved theme (accounts for system preference)
+ */
+export const resolvedThemeAtom = atom((get) => {
+	const mode = get(themeModeAtom);
+	if (mode !== "system") return mode;
+
+	// Check system preference (this is a static check, won't react to changes)
+	if (typeof window !== "undefined") {
+		return window.matchMedia("(prefers-color-scheme: dark)").matches
+			? "dark"
+			: "light";
+	}
+	return "light";
+});
+
+// ============================================================================
+// Navigation State Atoms
+// ============================================================================
+
+/**
+ * Current active collection (for breadcrumbs, etc.)
+ */
+export const activeCollectionAtom = atom<string | null>(null);
+
+/**
+ * Current active item ID (for editing)
+ */
+export const activeItemIdAtom = atom<string | null>(null);
+
+/**
+ * Navigation history stack
+ */
+export const navigationHistoryAtom = atom<string[]>([]);
+
+// ============================================================================
+// Form State Atoms
+// ============================================================================
+
+/**
+ * Global form dirty state (to warn on navigation)
+ */
+export const formDirtyAtom = atom(false);
+
+/**
+ * Active form errors count
+ */
+export const formErrorsCountAtom = atom(0);
+
+// ============================================================================
+// Notification Atoms
+// ============================================================================
+
+export type NotificationType = "success" | "error" | "warning" | "info";
+
+export type Notification = {
+	id: string;
+	type: NotificationType;
+	title: string;
+	message?: string;
+	duration?: number;
+	action?: {
+		label: string;
+		onClick: () => void;
+	};
+};
+
+export const notificationsAtom = atom<Notification[]>([]);
+
+/**
+ * Derived atom to add notification
+ */
+export const addNotificationAtom = atom(
+	null,
+	(get, set, notification: Omit<Notification, "id">) => {
+		const id = Math.random().toString(36).substring(2, 9);
+		const newNotification = { ...notification, id };
+		set(notificationsAtom, [...get(notificationsAtom), newNotification]);
+
+		// Auto-remove after duration
+		if (notification.duration !== 0) {
+			setTimeout(() => {
+				set(notificationsAtom, (prev) => prev.filter((n) => n.id !== id));
+			}, notification.duration ?? 5000);
+		}
+
+		return id;
+	},
+);
+
+/**
+ * Derived atom to remove notification
+ */
+export const removeNotificationAtom = atom(null, (get, set, id: string) => {
+	set(notificationsAtom, (prev) => prev.filter((n) => n.id !== id));
+});
+
+// ============================================================================
+// Custom Hooks
+// ============================================================================
+
+/**
+ * Hook for sidebar state
+ */
+export function useSidebar() {
+	const [collapsed, setCollapsed] = useAtom(sidebarCollapsedAtom);
+	return {
+		collapsed,
+		setCollapsed,
+		toggle: () => setCollapsed(!collapsed),
+	};
+}
+
+/**
+ * Hook for theme state
+ */
+export function useTheme() {
+	const [mode, setMode] = useAtom(themeModeAtom);
+	const resolved = useAtomValue(resolvedThemeAtom);
+	return {
+		mode,
+		setMode,
+		resolved,
+		isDark: resolved === "dark",
+		isLight: resolved === "light",
+	};
+}
+
+/**
+ * Hook for locale state
+ */
+export function useLocale() {
+	const [locale, setLocale] = useAtom(localeAtom);
+	const config = useAtomValue(localesConfigAtom);
+	return {
+		locale: locale ?? config?.default ?? null,
+		setLocale,
+		available: config?.available ?? [],
+		default: config?.default ?? null,
+	};
+}
+
+/**
+ * Hook for notifications
+ */
+export function useNotifications() {
+	const notifications = useAtomValue(notificationsAtom);
+	const addNotification = useSetAtom(addNotificationAtom);
+	const removeNotification = useSetAtom(removeNotificationAtom);
+
+	return {
+		notifications,
+		add: addNotification,
+		remove: removeNotification,
+		success: (title: string, message?: string) =>
+			addNotification({ type: "success", title, message }),
+		error: (title: string, message?: string) =>
+			addNotification({ type: "error", title, message }),
+		warning: (title: string, message?: string) =>
+			addNotification({ type: "warning", title, message }),
+		info: (title: string, message?: string) =>
+			addNotification({ type: "info", title, message }),
+	};
+}
+
+/**
+ * Hook for command palette
+ */
+export function useCommandPalette() {
+	const [open, setOpen] = useAtom(commandPaletteOpenAtom);
+	return {
+		open,
+		setOpen,
+		toggle: () => setOpen(!open),
+	};
+}
+
+/**
+ * Hook for form dirty state
+ */
+export function useFormDirty() {
+	const [dirty, setDirty] = useAtom(formDirtyAtom);
+	return {
+		dirty,
+		setDirty,
+		markDirty: () => setDirty(true),
+		markClean: () => setDirty(false),
+	};
+}