@xnetjs/react 0.0.2 → 0.1.0

package/dist/core.d.ts

@@ -0,0 +1,372 @@
+import { Q as QueryFilter, j as QueryBaseResult, F as FlatNode, M as MigrationWarning } from './useQuery-D7ajycrc.js';
+export { c as QueryListResult, d as QuerySingleResult, S as SortDirection, u as useQuery } from './useQuery-D7ajycrc.js';
+import { PropertyBuilder, DefinedSchema, InferCreateProps, NodeState, NodeBatchWriteInput, NodeBatchWriteResult } from '@xnetjs/data';
+import { QueryPageInfo } from '@xnetjs/data-bridge';
+import { Awareness } from 'y-protocols/awareness';
+import * as Y from 'yjs';
+import { Identity } from '@xnetjs/identity';
+export { f as XNetConfig, X as XNetContextValue, e as XNetProvider, g as XNetProviderProps, h as XNetRuntimeConfig, i as XNetRuntimeFallback, j as XNetRuntimeMode, k as XNetRuntimePhase, d as XNetRuntimeStatus, l as XNetRuntimeWorkerConfig, a as useXNet } from './context-CFu9i136.js';
+import { Component, ReactNode, ErrorInfo } from 'react';
+import '@xnetjs/core';
+import '@xnetjs/runtime';
+import '@xnetjs/crypto';
+import '@xnetjs/sync';
+import '@xnetjs/history';
+import '@xnetjs/plugins';
+import './telemetry-context-B7r6H1KW.js';
+
+/**
+ * useInfiniteQuery - incremental "load more" wrapper over useQuery.
+ *
+ * Unlike a cursor-paged implementation (which freezes earlier pages and keeps
+ * the live page on `after` cursor semantics — a shape that falls off the
+ * bridge's incremental delta path and re-executes storage on every matching
+ * edit), this hook models the loaded region as a single GROWING
+ * `limit + orderBy` window. That descriptor stays on the bounded-delta fast
+ * path, so:
+ *
+ * - edits to any already-loaded row update in place without re-querying, and
+ * - every loaded row stays live (no stale frozen pages).
+ *
+ * Calling `fetchNextPage()` grows the window by `pageSize`; the previous rows
+ * are retained during the (single) read for the larger window so the list
+ * does not flicker.
+ */
+
+interface InfiniteQueryFilter<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>> extends Omit<QueryFilter<P>, 'limit' | 'offset' | 'page'> {
+    /** Number of rows to grow the window by on each `fetchNextPage()`. */
+    pageSize?: number;
+    /** Optional page metadata. `first` defaults to `pageSize` when omitted. */
+    page?: Omit<NonNullable<QueryFilter<P>['page']>, 'first'> & {
+        first?: number;
+    };
+    /**
+     * Upper bound on the live window size. Once reached, `fetchNextPage()` is a
+     * no-op and `hasMore` is false. Defaults to unbounded — set this for
+     * virtualized lists so the overfetch buffer and live snapshot stay bounded.
+     */
+    maxLoaded?: number;
+}
+interface InfiniteQueryPage<P extends Record<string, PropertyBuilder>> {
+    cursor: string | null;
+    data: FlatNode<P>[];
+    pageInfo: QueryPageInfo;
+}
+interface InfiniteQueryResult<P extends Record<string, PropertyBuilder>> extends QueryBaseResult {
+    /** All loaded rows in descriptor order. */
+    data: FlatNode<P>[];
+    /** Loaded rows grouped into `pageSize` chunks for grouped/virtualized rendering. */
+    pages: InfiniteQueryPage<P>[];
+    /** Aggregated pagination metadata for the loaded window. */
+    pageInfo: QueryPageInfo;
+    /** Total matching count when known. Null means unavailable or intentionally not counted. */
+    totalCount: number | null;
+    /** Whether the window can grow further. */
+    hasMore: boolean;
+    /** Whether `fetchNextPage()` has grown the window and is awaiting the larger read. */
+    isFetchingNextPage: boolean;
+    /** Grow the loaded window by `pageSize` (bounded by `maxLoaded`). */
+    fetchNextPage: () => Promise<void>;
+    /** Shrink the window back to the first page. */
+    reset: () => void;
+    /** Migration warnings across the loaded window. */
+    migrationWarnings: MigrationWarning[];
+}
+declare function useInfiniteQuery<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, filter?: InfiniteQueryFilter<P>): InfiniteQueryResult<P>;
+
+/**
+ * useMutate - Unified write hook for Nodes via DataBridge
+ *
+ * A single hook for all write operations:
+ * - Create nodes (requires schema)
+ * - Update nodes (requires schema for type safety)
+ * - Delete nodes (by ID)
+ * - Atomic transactions (multiple operations)
+ *
+ * Uses DataBridge for off-main-thread data access.
+ *
+ * Features:
+ * - Immediate local updates (bridge updates UI subscribers synchronously)
+ * - Type-safe schema-bound mutations
+ * - Transaction support for atomic multi-node operations
+ * - Pending state tracking
+ *
+ * @example
+ * ```tsx
+ * const { create, update, remove, mutate, isPending } = useMutate()
+ *
+ * // Simple operations
+ * await create(TaskSchema, { title: 'New Task', status: 'todo' })
+ * await update(TaskSchema, taskId, { status: 'done' })  // Type-safe!
+ * await remove(taskId)
+ *
+ * // Atomic transaction
+ * await mutate([
+ *   { type: 'create', schema: TaskSchema, data: { title: 'Task 1' } },
+ *   { type: 'update', id: taskId, data: { status: 'done' } },
+ *   { type: 'delete', id: oldTaskId }
+ * ])
+ * ```
+ */
+
+/**
+ * Create operation for mutate
+ */
+interface MutateCreate<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>> {
+    type: 'create';
+    schema: DefinedSchema<P>;
+    data: InferCreateProps<P>;
+    id?: string;
+}
+/**
+ * Update operation for mutate
+ */
+interface MutateUpdate {
+    type: 'update';
+    id: string;
+    data: Record<string, unknown>;
+}
+/**
+ * Delete operation for mutate
+ */
+interface MutateDelete {
+    type: 'delete';
+    id: string;
+}
+/**
+ * Restore operation for mutate
+ */
+interface MutateRestore {
+    type: 'restore';
+    id: string;
+}
+/**
+ * All possible mutate operations
+ */
+type MutateOp = MutateCreate<Record<string, PropertyBuilder>> | MutateUpdate | MutateDelete | MutateRestore;
+/**
+ * Result from a mutate transaction
+ */
+interface MutateResult {
+    /** Results for each operation (NodeState or null for delete) */
+    results: (NodeState | null)[];
+    /** Batch ID when transaction backend is available */
+    batchId?: string;
+    /** Temp ID mapping when transaction backend is available */
+    tempIds?: Record<string, string>;
+}
+/**
+ * Result from useMutate hook
+ */
+interface UseMutateResult {
+    /**
+     * Create a new node.
+     * Requires a schema to know what type to create.
+     * Optionally specify a custom ID (otherwise auto-generated).
+     *
+     * @returns The created node (flattened), or null if creation failed
+     */
+    create: <P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, data: InferCreateProps<P>, id?: string) => Promise<FlatNode<P> | null>;
+    /**
+     * Update an existing node by ID.
+     * Requires schema for type-safe property checking.
+     *
+     * @example
+     * ```tsx
+     * await update(TaskSchema, taskId, { status: 'done' })  // OK
+     * await update(TaskSchema, taskId, { typo: 'x' })       // Type error!
+     * ```
+     *
+     * @returns The updated node (flattened), or null if update failed
+     */
+    update: <P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, id: string, data: Partial<InferCreateProps<P>>) => Promise<FlatNode<P> | null>;
+    /**
+     * Delete a node by ID (soft delete).
+     */
+    remove: (id: string) => Promise<void>;
+    /**
+     * Restore a deleted node by ID.
+     *
+     * @returns The restored node (flattened), or null if restore failed
+     */
+    restore: (id: string) => Promise<FlatNode<Record<string, PropertyBuilder>> | null>;
+    /**
+     * Execute multiple operations atomically.
+     * All operations succeed or fail together.
+     *
+     * Note: Atomicity requires a bridge implementing DataBridge.transaction
+     * (MainThreadBridge, WorkerBridge, NativeBridge all do). Bridges without
+     * it execute operations sequentially (not truly atomic).
+     */
+    mutate: (ops: MutateOp[]) => Promise<MutateResult | null>;
+    /**
+     * Execute a storage-owned bulk write.
+     */
+    bulk: (input: NodeBatchWriteInput) => Promise<NodeBatchWriteResult | null>;
+    /**
+     * Whether any mutation is currently in progress.
+     */
+    isPending: boolean;
+    /**
+     * Number of pending mutations.
+     */
+    pendingCount: number;
+}
+/**
+ * Hook for all write operations on Nodes via DataBridge.
+ *
+ * Provides both convenience methods (create, update, remove) and
+ * a full transaction API (mutate) for atomic multi-node operations.
+ *
+ * All operations update the local cache immediately, and subscribers
+ * see changes synchronously. Background sync handles persistence.
+ */
+declare function useMutate(): UseMutateResult;
+
+/**
+ * Sync connection status
+ */
+type SyncStatus = 'offline' | 'connecting' | 'connected' | 'error';
+interface PresenceUser {
+    did: string;
+    name?: string;
+    color?: string;
+    lastSeen?: number;
+    isStale?: boolean;
+}
+/**
+ * Options for useNode
+ */
+interface UseNodeOptions<P extends Record<string, PropertyBuilder>> {
+    /** Signaling servers for y-webrtc (default: localhost for dev) */
+    signalingServers?: string[];
+    /** Disable auto-sync (default: false) */
+    disableSync?: boolean;
+    /** Debounce persistence delay in ms (default: 1000) */
+    persistDebounce?: number;
+    /**
+     * Auto-create the node if it doesn't exist.
+     * Provide the default properties to use for creation.
+     */
+    createIfMissing?: InferCreateProps<P>;
+    /**
+     * User's DID for presence/cursors. If provided, broadcasts awareness state.
+     */
+    did?: string;
+}
+/**
+ * Result from useNode hook
+ */
+interface UseNodeResult<P extends Record<string, PropertyBuilder>> {
+    /** Node properties (flattened - access directly: data.title) */
+    data: FlatNode<P> | null;
+    /** Yjs document instance (null if schema has no document type) */
+    doc: Y.Doc | null;
+    /**
+     * Update node properties (type-safe).
+     * Only properties defined in the schema are allowed.
+     */
+    update: (properties: Partial<InferCreateProps<P>>) => Promise<void>;
+    /**
+     * Soft-delete the node.
+     */
+    remove: () => Promise<void>;
+    /** Whether currently loading */
+    loading: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Whether document has unsaved changes */
+    isDirty: boolean;
+    /** Last persistence timestamp */
+    lastSavedAt: number | null;
+    /** Whether the node was auto-created (via createIfMissing) */
+    wasCreated: boolean;
+    /** Sync connection status */
+    syncStatus: SyncStatus;
+    /** Sync error message (if syncStatus is 'error') */
+    syncError: string | null;
+    /** Connected peer count */
+    peerCount: number;
+    /** Presence list (live awareness + hub snapshot) */
+    presence: PresenceUser[];
+    /** Yjs Awareness instance (for TipTap CollaborationCursor) */
+    awareness: Awareness | null;
+    /** Manually trigger save */
+    save: () => Promise<void>;
+    /** Reload from storage */
+    reload: () => Promise<void>;
+}
+/**
+ * Load a Node with its CRDT document.
+ *
+ * This is the primary hook for editing content. It combines:
+ * - Data loading (with FlatNode for ergonomic access)
+ * - Y.Doc for collaborative rich text
+ * - Type-safe mutations
+ * - Real-time sync and presence
+ */
+declare function useNode<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, id: string | null, options?: UseNodeOptions<P>): UseNodeResult<P>;
+
+/**
+ * useIdentity hook for identity access
+ */
+
+/**
+ * Result from useIdentity hook
+ */
+interface UseIdentityResult {
+    identity: Identity | null;
+    isAuthenticated: boolean;
+    did: string | null;
+}
+/**
+ * Hook for accessing current identity
+ */
+declare function useIdentity(): UseIdentityResult;
+
+/**
+ * Global error boundary for xNet React apps.
+ *
+ * Catches unhandled React render errors and displays a recovery UI
+ * instead of crashing the entire app tree.
+ */
+
+type ErrorBoundaryFallbackProps = {
+    error: Error;
+    reset: () => void;
+};
+type ErrorBoundaryProps = {
+    children: ReactNode;
+    /** Custom fallback UI. Receives error + reset function. If omitted, a default error screen is shown. */
+    fallback?: ReactNode | ((props: ErrorBoundaryFallbackProps) => ReactNode);
+    /** Callback fired when an error is caught. */
+    onError?: (error: Error, errorInfo: ErrorInfo) => void;
+    /** Change this value to force a reset (e.g. after navigation). */
+    resetKey?: string | number;
+};
+type ErrorBoundaryState = {
+    hasError: boolean;
+    error: Error | null;
+};
+declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    state: ErrorBoundaryState;
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    private handleReset;
+    componentDidUpdate(prevProps: ErrorBoundaryProps): void;
+    render(): ReactNode;
+}
+
+type OfflineIndicatorProps = {
+    /** Custom message. Default: 'You are offline. Changes will sync when reconnected.' */
+    message?: string;
+    /** Additional CSS class. */
+    className?: string;
+    /** Position. Default: 'bottom'. */
+    position?: 'top' | 'bottom';
+};
+/** Returns true when the browser is offline. */
+declare function useIsOffline(): boolean;
+declare function OfflineIndicator({ message, className, position }: OfflineIndicatorProps): JSX.Element | null;
+
+export { ErrorBoundary, type ErrorBoundaryProps, FlatNode, type InfiniteQueryFilter, type InfiniteQueryPage, type InfiniteQueryResult, MigrationWarning, type MutateCreate, type MutateDelete, type MutateOp, type MutateRestore, type MutateUpdate, OfflineIndicator, type OfflineIndicatorProps, type PresenceUser, QueryFilter, type SyncStatus, type UseIdentityResult, type UseMutateResult, type UseNodeOptions, type UseNodeResult, useIdentity, useInfiniteQuery, useIsOffline, useMutate, useNode };

package/dist/core.js

@@ -0,0 +1,29 @@
+import {
+  ErrorBoundary,
+  OfflineIndicator,
+  useIdentity,
+  useInfiniteQuery,
+  useIsOffline,
+  useNode
+} from "./chunk-QHNYQVUM.js";
+import {
+  useMutate,
+  useQuery
+} from "./chunk-6VOICQZ3.js";
+import "./chunk-JCOFKBOB.js";
+import {
+  XNetProvider,
+  useXNet
+} from "./chunk-IHTMVTTE.js";
+export {
+  ErrorBoundary,
+  OfflineIndicator,
+  XNetProvider,
+  useIdentity,
+  useInfiniteQuery,
+  useIsOffline,
+  useMutate,
+  useNode,
+  useQuery,
+  useXNet
+};