@korajs/react 0.5.0 → 0.6.1

package/dist/index.d.ts

@@ -1,42 +1,13 @@
-import { KoraEventEmitter } from '@korajs/core';
-import { Store, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
-import { SyncStatusInfo, SyncEngine, CursorInfo, AwarenessUser } from '@korajs/sync';
+import { KoraAppLike as KoraAppLike$1, KoraContextValue as KoraContextValue$1, UseMutationOptions as UseMutationOptions$1, UseMutationResultBase, UseQueryOptions as UseQueryOptions$1 } from '@korajs/core/bindings';
+import { Store, QueryStoreCache, CollectionRecord, QueryBuilder, CollectionAccessor } from '@korajs/store';
+import { SyncEngine, CursorInfo, SyncStatusInfo, AwarenessUser, AwarenessState } from '@korajs/sync';
 import { ReactNode } from 'react';
 import * as Y from 'yjs';
 
-/**
- * A Kora application instance returned by createApp().
- * Defined here to avoid a hard dependency on the kora meta-package.
- */
-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. */
-    getSyncEngine(): SyncEngine | null;
-}
-/**
- * Value provided by KoraProvider via React context.
- */
-interface KoraContextValue {
-    /** The local Kora store instance */
-    store: Store;
-    /** Optional sync engine for remote synchronization */
-    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;
-}
+type KoraAppLike = KoraAppLike$1<Store, SyncEngine, QueryStoreCache>;
+type KoraContextValue = KoraContextValue$1<Store, SyncEngine, QueryStoreCache>;
+type UseQueryOptions = UseQueryOptions$1;
+type UseMutationOptions<TData, TArgs extends unknown[], TContext = void> = UseMutationOptions$1<TData, TArgs, TContext>;
 /**
  * Props for the KoraProvider component.
  *
@@ -44,104 +15,33 @@ interface KoraContextValue {
  * explicit `store` + `syncEngine` props (advanced use case).
  */
 interface KoraProviderProps {
-    /** A KoraApp instance from createApp(). Extracts store and syncEngine automatically. */
     app?: KoraAppLike;
-    /** The local Kora store instance (alternative to app prop). */
     store?: Store;
-    /** Optional sync engine for remote synchronization (used with store prop). */
     syncEngine?: SyncEngine | null;
-    /** Fallback content to render while app.ready is resolving. Defaults to null. */
     fallback?: ReactNode;
-    /** Child components */
     children?: ReactNode;
 }
-/**
- * Options for the useQuery hook.
- */
-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.
- */
-interface UseMutationResult<TData, TArgs extends unknown[]> {
-    /** Fire-and-forget mutation. Catches errors silently (sets error state). */
-    mutate: (...args: TArgs) => void;
-    /** Promise-returning mutation. Throws on error. */
-    mutateAsync: (...args: TArgs) => Promise<TData>;
-    /** Whether a mutation is currently in progress */
+interface UseMutationResult<TData, TArgs extends unknown[]> extends UseMutationResultBase<TData, TArgs> {
     isLoading: boolean;
-    /** The last error that occurred, or null */
     error: Error | null;
-    /** Reset isLoading and error state */
-    reset: () => void;
 }
-/**
- * Result from the useRichText hook.
- */
 interface UseRichTextResult {
-    /** Shared Yjs document backing this field. */
     doc: Y.Doc;
-    /** Y.Text instance to bind to editor integrations. */
     text: Y.Text;
-    /** Undo local changes made to this richtext field. */
     undo: () => void;
-    /** Redo previously undone local changes. */
     redo: () => void;
-    /** True when undo can be applied. */
     canUndo: boolean;
-    /** True when redo can be applied. */
     canRedo: boolean;
-    /** True once the record field has been loaded into the Y.Doc. */
     ready: boolean;
-    /** Last hook error (load/persist), if any. */
     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;
 }
 
 /**
  * Provides Kora store and optional sync engine to all child components.
  * Must wrap any component that uses Kora hooks (useQuery, useMutation, etc.).
- *
- * Accepts either an `app` prop (recommended) or explicit `store` + `syncEngine` props.
- *
- * When using the `app` prop, KoraProvider waits for `app.ready` before rendering
- * children. A `fallback` prop can be provided to show content while initializing.
- *
- * @example
- * ```typescript
- * // Recommended: pass the app object directly
- * const app = createApp({ schema })
- * <KoraProvider app={app}><App /></KoraProvider>
- *
- * // Advanced: pass store and syncEngine explicitly
- * <KoraProvider store={store} syncEngine={syncEngine}><App /></KoraProvider>
- * ```
  */
 declare function KoraProvider({ app, store, syncEngine, fallback, children, }: KoraProviderProps): ReactNode;
 
@@ -170,64 +70,16 @@ declare function useApp<T extends KoraAppLike = KoraAppLike>(): T;
 
 /**
  * React hook for reactive queries against the local Kora store.
- *
- * Returns data synchronously from the local store — no loading spinners needed.
- * Re-renders automatically when the query results change due to mutations.
- * Uses `useSyncExternalStore` for React 18+ concurrent mode safety.
- *
- * The generic parameter `T` is inferred from the QueryBuilder, providing
- * full type safety when used with typed collection accessors.
- *
- * @param query - A QueryBuilder instance (e.g., `app.todos.where({ done: false })`)
- * @param options - Optional configuration (e.g., `{ enabled: false }` to skip the query)
- * @returns Readonly array of matching records
- *
- * @example
- * ```typescript
- * const todos = useQuery(app.todos.where({ completed: false }).orderBy('createdAt'))
- * // todos is typed as readonly InferRecord<typeof todoFields>[]
- * ```
  */
 declare function useQuery<T = CollectionRecord>(query: QueryBuilder<T>, options?: UseQueryOptions): readonly T[];
 
 /**
  * React hook for performing mutations against the local Kora store.
- *
- * 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, {
- *   onMutate: (data) => {
- *     const previous = todos
- *     setTodos((list) => [...list, { id: 'temp', ...data }])
- *     return previous
- *   },
- *   onRollback: (previous) => setTodos(previous),
- * })
- * ```
  */
 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.
- *
- * 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
- *
- * @example
- * ```typescript
- * const status = useSyncStatus()
- * // status.status: 'connected' | 'syncing' | 'synced' | 'offline' | 'error'
- * ```
  */
 declare function useSyncStatus(): SyncStatusInfo;
 
@@ -247,12 +99,7 @@ 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;
 }
 /**
@@ -260,4 +107,22 @@ interface UseRichTextOptions {
  */
 declare function useRichText(collectionName: string, recordId: string, fieldName: string, options?: UseRichTextOptions): UseRichTextResult;
 
-export { type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, useApp, useCollection, useMutation, useQuery, useRichText, useSyncStatus };
+/**
+ * Sets the local user's collaborative presence state.
+ *
+ * Automatically cleans up presence on unmount.
+ */
+declare function usePresence(user: {
+    name: string;
+    color: string;
+    avatar?: string;
+} | null): void;
+
+/**
+ * Returns all currently connected collaborators' awareness states.
+ *
+ * Excludes the local user — only returns remote peers.
+ */
+declare function useCollaborators(): AwarenessState[];
+
+export { type KoraAppLike, type KoraContextValue, KoraProvider, type KoraProviderProps, type UseMutationOptions, type UseMutationResult, type UseQueryOptions, type UseRichTextOptions, type UseRichTextResult, useApp, useCollaborators, useCollection, useMutation, usePresence, useQuery, useRichText, useSyncStatus };