@questpie/admin 0.0.1 → 1.0.0

package/src/hooks/README.md

@@ -1,269 +0,0 @@
-# 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

@@ -1,110 +0,0 @@
-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

@@ -1,41 +0,0 @@
-/**
- * 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

@@ -1,248 +0,0 @@
-/**
- * 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),
-	};
-}