@korajs/react 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
+import { KoraEventEmitter } from '@korajs/core';
 import { Store, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
-import { SyncEngine, CursorInfo, SyncStatusInfo } from '@korajs/sync';
+import { SyncStatusInfo, SyncEngine, CursorInfo, AwarenessUser } from '@korajs/sync';
 import { ReactNode } from 'react';
 import * as Y from 'yjs';
 
@@ -10,6 +11,12 @@ import * as Y from 'yjs';
 interface KoraAppLike {
     /** Resolves when the store is open and collections are ready. */
     ready: Promise<void>;
+    /** Framework event emitter (sync, store, merge, query). */
+    events?: KoraEventEmitter;
+    /** Sync control when sync is configured. */
+    sync?: {
+        subscribeStatus(listener: (status: SyncStatusInfo) => void): () => void;
+    } | null;
     /** Get the underlying Store instance. */
     getStore(): Store;
     /** Get the underlying SyncEngine instance. Null if sync not configured. */
@@ -25,6 +32,10 @@ interface KoraContextValue {
     syncEngine: SyncEngine | null;
     /** The KoraApp instance (when provided via app prop). */
     app: KoraAppLike | null;
+    /** App event emitter (when using app prop). */
+    events: KoraEventEmitter | null;
+    /** Event-driven sync status subscription from app.sync. */
+    subscribeSyncStatus: ((listener: (status: SyncStatusInfo) => void) => () => void) | null;
 }
 /**
  * Props for the KoraProvider component.
@@ -51,6 +62,25 @@ interface UseQueryOptions {
     /** Set to false to disable the subscription (query won't execute). Defaults to true. */
     enabled?: boolean;
 }
+/**
+ * Options for optimistic updates and rollback in {@link useMutation}.
+ */
+interface UseMutationOptions<TData, TArgs extends unknown[], TContext = void> {
+    /**
+     * Runs before the mutation. Return a context value for rollback.
+     */
+    onMutate?: (...args: TArgs) => TContext | Promise<TContext>;
+    /**
+     * Reverts optimistic changes when the mutation fails.
+     */
+    onRollback?: (context: TContext, ...args: TArgs) => void | Promise<void>;
+    /** Called when the mutation succeeds. */
+    onSuccess?: (data: TData, ...args: TArgs) => void;
+    /** Called when the mutation fails (after optional rollback). */
+    onError?: (error: Error, ...args: TArgs) => void;
+    /** Called after success or failure. */
+    onSettled?: (data: TData | undefined, error: Error | null, ...args: TArgs) => void;
+}
 /**
  * Result from the useMutation hook.
  */
@@ -88,6 +118,10 @@ interface UseRichTextResult {
     error: Error | null;
     /** Remote collaborators' cursor positions in this field. Empty if no sync engine. */
     cursors: CursorInfo[];
+    /** Publish local cursor/selection to connected collaborators. No-op without sync. */
+    setCursor: (anchor: number, head: number) => void;
+    /** Clear local cursor presence for this field. */
+    clearCursor: () => void;
 }
 
 /**
@@ -159,26 +193,33 @@ declare function useQuery<T = CollectionRecord>(query: QueryBuilder<T>, options?
 /**
  * React hook for performing mutations against the local Kora store.
  *
- * Returns `mutate` for fire-and-forget usage (optimistic) and `mutateAsync`
- * for when you need to await the result. Tracks loading and error state.
+ * Returns `mutate` for fire-and-forget usage and `mutateAsync` when you need
+ * to await the result. Optional `onMutate` / `onRollback` support optimistic
+ * UI updates that revert if the mutation throws.
  *
  * @param mutationFn - An async function to execute (e.g., `app.todos.insert`)
+ * @param options - Optional optimistic/rollback and lifecycle callbacks
  * @returns Object with mutate, mutateAsync, isLoading, error, and reset
  *
  * @example
  * ```typescript
- * const { mutate } = useMutation(app.todos.insert)
- * mutate({ title: 'New todo' }) // fire-and-forget
+ * const { mutate } = useMutation(app.todos.insert, {
+ *   onMutate: (data) => {
+ *     const previous = todos
+ *     setTodos((list) => [...list, { id: 'temp', ...data }])
+ *     return previous
+ *   },
+ *   onRollback: (previous) => setTodos(previous),
+ * })
  * ```
  */
-declare function useMutation<TData, TArgs extends unknown[]>(mutationFn: (...args: TArgs) => Promise<TData>): UseMutationResult<TData, TArgs>;
+declare function useMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
 
 /**
  * React hook for monitoring the sync engine's connection status.
  *
- * Polls the SyncEngine at ~500ms intervals and re-renders only when
- * the status actually changes. Returns a default offline status when
- * no sync engine is configured.
+ * Subscribes to sync events via `app.sync.subscribeStatus` (or the sync engine
+ * emitter when using store-only mode) and re-renders only when status changes.
  *
  * @returns Current sync status information
  *
@@ -186,8 +227,6 @@ declare function useMutation<TData, TArgs extends unknown[]>(mutationFn: (...arg
  * ```typescript
  * const status = useSyncStatus()
  * // status.status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error'
- * // status.pendingOperations: number
- * // status.lastSyncedAt: number | null
  * ```
  */
 declare function useSyncStatus(): SyncStatusInfo;
@@ -207,9 +246,18 @@ declare function useSyncStatus(): SyncStatusInfo;
  */
 declare function useCollection(name: string): CollectionAccessor;
 
+interface UseRichTextOptions {
+    /** Presence identity broadcast with cursor updates. */
+    user?: AwarenessUser;
+    /**
+     * Use the incremental Yjs doc channel for live edits (recommended for large documents).
+     * When omitted, the channel activates automatically once the snapshot exceeds the sync threshold.
+     */
+    useDocChannel?: boolean;
+}
 /**
  * Binds a richtext field to a shared Yjs document for editor integration.
  */
-declare function useRichText(collectionName: string, recordId: string, fieldName: string): UseRichTextResult;
+declare function useRichText(collectionName: string, recordId: string, fieldName: string, options?: UseRichTextOptions): UseRichTextResult;
 
-export { type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationResult, type UseQueryOptions, type UseRichTextResult, useApp, useCollection, useMutation, useQuery, useRichText, useSyncStatus };
+export { type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, useApp, useCollection, useMutation, useQuery, useRichText, useSyncStatus };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import { KoraEventEmitter } from '@korajs/core';
 import { Store, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
-import { SyncEngine, CursorInfo, SyncStatusInfo } from '@korajs/sync';
+import { SyncStatusInfo, SyncEngine, CursorInfo, AwarenessUser } from '@korajs/sync';
 import { ReactNode } from 'react';
 import * as Y from 'yjs';
 
@@ -10,6 +11,12 @@ import * as Y from 'yjs';
 interface KoraAppLike {
     /** Resolves when the store is open and collections are ready. */
     ready: Promise<void>;
+    /** Framework event emitter (sync, store, merge, query). */
+    events?: KoraEventEmitter;
+    /** Sync control when sync is configured. */
+    sync?: {
+        subscribeStatus(listener: (status: SyncStatusInfo) => void): () => void;
+    } | null;
     /** Get the underlying Store instance. */
     getStore(): Store;
     /** Get the underlying SyncEngine instance. Null if sync not configured. */
@@ -25,6 +32,10 @@ interface KoraContextValue {
     syncEngine: SyncEngine | null;
     /** The KoraApp instance (when provided via app prop). */
     app: KoraAppLike | null;
+    /** App event emitter (when using app prop). */
+    events: KoraEventEmitter | null;
+    /** Event-driven sync status subscription from app.sync. */
+    subscribeSyncStatus: ((listener: (status: SyncStatusInfo) => void) => () => void) | null;
 }
 /**
  * Props for the KoraProvider component.
@@ -51,6 +62,25 @@ interface UseQueryOptions {
     /** Set to false to disable the subscription (query won't execute). Defaults to true. */
     enabled?: boolean;
 }
+/**
+ * Options for optimistic updates and rollback in {@link useMutation}.
+ */
+interface UseMutationOptions<TData, TArgs extends unknown[], TContext = void> {
+    /**
+     * Runs before the mutation. Return a context value for rollback.
+     */
+    onMutate?: (...args: TArgs) => TContext | Promise<TContext>;
+    /**
+     * Reverts optimistic changes when the mutation fails.
+     */
+    onRollback?: (context: TContext, ...args: TArgs) => void | Promise<void>;
+    /** Called when the mutation succeeds. */
+    onSuccess?: (data: TData, ...args: TArgs) => void;
+    /** Called when the mutation fails (after optional rollback). */
+    onError?: (error: Error, ...args: TArgs) => void;
+    /** Called after success or failure. */
+    onSettled?: (data: TData | undefined, error: Error | null, ...args: TArgs) => void;
+}
 /**
  * Result from the useMutation hook.
  */
@@ -88,6 +118,10 @@ interface UseRichTextResult {
     error: Error | null;
     /** Remote collaborators' cursor positions in this field. Empty if no sync engine. */
     cursors: CursorInfo[];
+    /** Publish local cursor/selection to connected collaborators. No-op without sync. */
+    setCursor: (anchor: number, head: number) => void;
+    /** Clear local cursor presence for this field. */
+    clearCursor: () => void;
 }
 
 /**
@@ -159,26 +193,33 @@ declare function useQuery<T = CollectionRecord>(query: QueryBuilder<T>, options?
 /**
  * React hook for performing mutations against the local Kora store.
  *
- * Returns `mutate` for fire-and-forget usage (optimistic) and `mutateAsync`
- * for when you need to await the result. Tracks loading and error state.
+ * Returns `mutate` for fire-and-forget usage and `mutateAsync` when you need
+ * to await the result. Optional `onMutate` / `onRollback` support optimistic
+ * UI updates that revert if the mutation throws.
  *
  * @param mutationFn - An async function to execute (e.g., `app.todos.insert`)
+ * @param options - Optional optimistic/rollback and lifecycle callbacks
  * @returns Object with mutate, mutateAsync, isLoading, error, and reset
  *
  * @example
  * ```typescript
- * const { mutate } = useMutation(app.todos.insert)
- * mutate({ title: 'New todo' }) // fire-and-forget
+ * const { mutate } = useMutation(app.todos.insert, {
+ *   onMutate: (data) => {
+ *     const previous = todos
+ *     setTodos((list) => [...list, { id: 'temp', ...data }])
+ *     return previous
+ *   },
+ *   onRollback: (previous) => setTodos(previous),
+ * })
  * ```
  */
-declare function useMutation<TData, TArgs extends unknown[]>(mutationFn: (...args: TArgs) => Promise<TData>): UseMutationResult<TData, TArgs>;
+declare function useMutation<TData, TArgs extends unknown[], TContext = void>(mutationFn: (...args: TArgs) => Promise<TData>, options?: UseMutationOptions<TData, TArgs, TContext>): UseMutationResult<TData, TArgs>;
 
 /**
  * React hook for monitoring the sync engine's connection status.
  *
- * Polls the SyncEngine at ~500ms intervals and re-renders only when
- * the status actually changes. Returns a default offline status when
- * no sync engine is configured.
+ * Subscribes to sync events via `app.sync.subscribeStatus` (or the sync engine
+ * emitter when using store-only mode) and re-renders only when status changes.
  *
  * @returns Current sync status information
  *
@@ -186,8 +227,6 @@ declare function useMutation<TData, TArgs extends unknown[]>(mutationFn: (...arg
  * ```typescript
  * const status = useSyncStatus()
  * // status.status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error'
- * // status.pendingOperations: number
- * // status.lastSyncedAt: number | null
  * ```
  */
 declare function useSyncStatus(): SyncStatusInfo;
@@ -207,9 +246,18 @@ declare function useSyncStatus(): SyncStatusInfo;
  */
 declare function useCollection(name: string): CollectionAccessor;
 
+interface UseRichTextOptions {
+    /** Presence identity broadcast with cursor updates. */
+    user?: AwarenessUser;
+    /**
+     * Use the incremental Yjs doc channel for live edits (recommended for large documents).
+     * When omitted, the channel activates automatically once the snapshot exceeds the sync threshold.
+     */
+    useDocChannel?: boolean;
+}
 /**
  * Binds a richtext field to a shared Yjs document for editor integration.
  */
-declare function useRichText(collectionName: string, recordId: string, fieldName: string): UseRichTextResult;
+declare function useRichText(collectionName: string, recordId: string, fieldName: string, options?: UseRichTextOptions): UseRichTextResult;
 
-export { type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationResult, type UseQueryOptions, type UseRichTextResult, useApp, useCollection, useMutation, useQuery, useRichText, useSyncStatus };
+export { type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, useApp, useCollection, useMutation, useQuery, useRichText, useSyncStatus };