@dabble/patches 0.5.5 → 0.5.7

package/dist/solid/primitives.d.ts

@@ -0,0 +1,235 @@
+import { Accessor } from 'solid-js';
+import { PatchesDoc } from '../client/PatchesDoc.js';
+import { ChangeMutator } from '../types.js';
+import '../event-signal.js';
+import '../algorithms/shared/changeBatching.js';
+import '../json-patch/JSONPatch.js';
+import '@dabble/delta';
+import '../json-patch/types.js';
+
+/**
+ * Options for usePatchesDoc primitive.
+ */
+interface UsePatchesDocOptions {
+    /**
+     * Whether to automatically open/close the document based on component lifecycle.
+     *
+     * - `false` (default): Assumes doc is already open. Throws if not.
+     * - `true`: Opens doc on mount with ref counting, closes on cleanup.
+     *
+     * @default false
+     */
+    autoClose?: boolean;
+}
+/**
+ * Return type for usePatchesDoc primitive.
+ */
+interface UsePatchesDocReturn<T extends object> {
+    /**
+     * Accessor for the document state.
+     * Updated whenever the document changes (local or remote).
+     */
+    data: Accessor<T | undefined>;
+    /**
+     * Whether the document is currently loading/syncing.
+     * - `true` during initial load or updates
+     * - `false` when fully synced
+     */
+    loading: Accessor<boolean>;
+    /**
+     * Error that occurred during sync, if any.
+     */
+    error: Accessor<Error | null>;
+    /**
+     * The committed revision number.
+     * Increments each time the server confirms changes.
+     */
+    rev: Accessor<number>;
+    /**
+     * Whether there are pending local changes not yet committed by server.
+     */
+    hasPending: Accessor<boolean>;
+    /**
+     * Make changes to the document.
+     *
+     * @example
+     * ```typescript
+     * change((patch, root) => {
+     *   patch.replace(root.title!, 'New Title')
+     * })
+     * ```
+     */
+    change: (mutator: ChangeMutator<T>) => void;
+    /**
+     * The underlying PatchesDoc instance.
+     * Useful for advanced operations.
+     */
+    doc: Accessor<PatchesDoc<T> | undefined>;
+}
+/**
+ * Solid primitive for reactive Patches document state.
+ *
+ * Provides reactive access to a Patches document with automatic lifecycle management.
+ *
+ * ## Explicit Lifecycle (default)
+ *
+ * By default, assumes the document is already open and just adds Solid reactivity.
+ * You control when documents are opened and closed.
+ *
+ * @example
+ * ```tsx
+ * import { onMount, onCleanup } from 'solid-js';
+ * import { usePatchesContext, usePatchesDoc } from '@dabble/patches/solid';
+ *
+ * function MyComponent(props) {
+ *   const { patches } = usePatchesContext();
+ *
+ *   // You control lifecycle
+ *   onMount(() => patches.openDoc(props.docId));
+ *   onCleanup(() => patches.closeDoc(props.docId));
+ *
+ *   // Just adds reactivity
+ *   // For static: usePatchesDoc('doc-123')
+ *   // For reactive: usePatchesDoc(() => props.docId)
+ *   const { data, loading, change } = usePatchesDoc(() => props.docId);
+ *
+ *   return <div>{data()?.title}</div>;
+ * }
+ * ```
+ *
+ * ## Auto Lifecycle
+ *
+ * With `autoClose: true`, the primitive manages the document lifecycle with
+ * reference counting. Safe to use in multiple components with the same docId.
+ *
+ * @example
+ * ```tsx
+ * // Opens on mount, closes on cleanup (ref-counted)
+ * const { data, loading, change } = usePatchesDoc('doc-123', {
+ *   autoClose: true
+ * });
+ * ```
+ *
+ * @param docId - Document ID (static string or accessor function)
+ * @param options - Configuration options
+ * @returns Reactive document state and utilities
+ * @throws Error if Patches context not provided
+ * @throws Error if doc not open in explicit mode
+ */
+declare function usePatchesDoc<T extends object>(docId: MaybeAccessor<string>, options?: UsePatchesDocOptions): UsePatchesDocReturn<T>;
+/**
+ * Return type for usePatchesSync primitive.
+ */
+interface UsePatchesSyncReturn {
+    /**
+     * Whether the WebSocket connection is established.
+     */
+    connected: Accessor<boolean>;
+    /**
+     * Whether documents are currently syncing with the server.
+     */
+    syncing: Accessor<boolean>;
+    /**
+     * Whether the client believes it has network connectivity.
+     */
+    online: Accessor<boolean>;
+}
+/**
+ * Solid primitive for reactive Patches sync state.
+ *
+ * Provides reactive access to PatchesSync connection and sync status.
+ * Useful for showing "Offline" banners, global loading indicators, etc.
+ *
+ * @example
+ * ```tsx
+ * const { connected, syncing, online } = usePatchesSync();
+ *
+ * return (
+ *   <Show when={!connected()}>
+ *     <div>You are offline</div>
+ *   </Show>
+ * );
+ * ```
+ *
+ * @returns Reactive sync state
+ * @throws Error if Patches context not provided
+ * @throws Error if PatchesSync was not provided to context
+ */
+declare function usePatchesSync(): UsePatchesSyncReturn;
+/**
+ * Type for document ID - can be static string or accessor function.
+ */
+type MaybeAccessor<T> = T | Accessor<T>;
+/**
+ * Creates a named document context that can be provided to child components.
+ *
+ * This enables child components to access the document using the returned `useDoc` hook
+ * without needing to pass the docId down through props. Supports both static and
+ * reactive docIds.
+ *
+ * ## Use Cases
+ *
+ * **Static document (user settings):**
+ * ```tsx
+ * const { Provider, useDoc } = createPatchesDoc<User>('user');
+ *
+ * <Provider docId="user-123">
+ *   <UserProfile />
+ * </Provider>
+ * ```
+ *
+ * **Reactive document (multi-tab):**
+ * ```tsx
+ * const { Provider, useDoc } = createPatchesDoc<Whiteboard>('whiteboard');
+ * const [activeTabId, setActiveTabId] = createSignal('design-1');
+ *
+ * <Provider docId={activeTabId}>
+ *   <WhiteboardCanvas />
+ * </Provider>
+ * ```
+ *
+ * **With autoClose:**
+ * ```tsx
+ * const { Provider, useDoc } = createPatchesDoc<Doc>('document');
+ * const [currentDocId, setCurrentDocId] = createSignal('doc-1');
+ *
+ * <Provider docId={currentDocId} autoClose>
+ *   <DocumentEditor />
+ * </Provider>
+ * ```
+ *
+ * @param name - Unique identifier for this document context (e.g., 'whiteboard', 'user')
+ * @returns Object with Provider component and useDoc hook
+ *
+ * @example
+ * ```tsx
+ * // Create the context
+ * const { Provider: WhiteboardProvider, useDoc: useWhiteboard } =
+ *   createPatchesDoc<WhiteboardDoc>('whiteboard');
+ *
+ * // Use in parent
+ * <WhiteboardProvider docId="whiteboard-123">
+ *   <Canvas />
+ * </WhiteboardProvider>
+ *
+ * // Use in child
+ * function Canvas() {
+ *   const { data, change } = useWhiteboard();
+ *   return <div>{data()?.title}</div>;
+ * }
+ * ```
+ */
+/**
+ * Props for the Provider component returned by createPatchesDoc.
+ */
+interface PatchesDocProviderProps {
+    docId: MaybeAccessor<string>;
+    autoClose?: boolean;
+    children: any;
+}
+declare function createPatchesDoc<T extends object>(name: string): {
+    Provider: (props: PatchesDocProviderProps) => any;
+    useDoc: () => UsePatchesDocReturn<T>;
+};
+
+export { type MaybeAccessor, type PatchesDocProviderProps, type UsePatchesDocOptions, type UsePatchesDocReturn, type UsePatchesSyncReturn, createPatchesDoc, usePatchesDoc, usePatchesSync };

package/dist/solid/primitives.js

@@ -0,0 +1,226 @@
+import "../chunk-IZ2YBCUP.js";
+import {
+  createSignal,
+  createContext,
+  useContext,
+  createResource,
+  createEffect,
+  onCleanup
+} from "solid-js";
+import { usePatchesContext } from "./context.js";
+import { getDocManager } from "./doc-manager.js";
+function usePatchesDoc(docId, options = {}) {
+  const { patches } = usePatchesContext();
+  const autoClose = options.autoClose ?? false;
+  const [doc, setDoc] = createSignal(void 0);
+  const [data, setData] = createSignal(void 0);
+  const [loading, setLoading] = createSignal(true);
+  const [error, setError] = createSignal(null);
+  const [rev, setRev] = createSignal(0);
+  const [hasPending, setHasPending] = createSignal(false);
+  const manager = getDocManager(patches);
+  const docIdAccessor = toAccessor(docId);
+  function setupDoc(patchesDoc) {
+    setDoc(patchesDoc);
+    const unsubState = patchesDoc.subscribe((state) => {
+      setData(() => state);
+      setRev(patchesDoc.committedRev);
+      setHasPending(patchesDoc.hasPending);
+    });
+    onCleanup(() => unsubState());
+    const unsubSync = patchesDoc.onSyncing((syncState) => {
+      setLoading(syncState === "initial" || syncState === "updating");
+      setError(syncState instanceof Error ? syncState : null);
+    });
+    onCleanup(() => unsubSync());
+    setLoading(patchesDoc.syncing !== null);
+  }
+  if (autoClose) {
+    const [docResource] = createResource(docIdAccessor, async (id) => {
+      return await manager.openDoc(patches, id);
+    });
+    createEffect(() => {
+      const loadedDoc = docResource();
+      if (loadedDoc) {
+        setupDoc(loadedDoc);
+      }
+      const resourceError = docResource.error;
+      if (resourceError) {
+        setError(resourceError);
+        setLoading(false);
+      }
+    });
+    onCleanup(() => {
+      const id = docIdAccessor();
+      manager.closeDoc(patches, id);
+    });
+  } else {
+    createEffect(() => {
+      const id = docIdAccessor();
+      const patchesDoc = patches.getOpenDoc(id);
+      if (!patchesDoc) {
+        throw new Error(
+          `Document "${id}" is not open. Either open it with patches.openDoc() first, or use { autoClose: true } option.`
+        );
+      }
+      manager.incrementRefCount(id);
+      setupDoc(patchesDoc);
+      onCleanup(() => {
+        manager.decrementRefCount(id);
+      });
+    });
+  }
+  function change(mutator) {
+    const currentDoc = doc();
+    if (!currentDoc) {
+      throw new Error("Cannot make changes: document not loaded yet");
+    }
+    currentDoc.change(mutator);
+  }
+  return {
+    data,
+    loading,
+    error,
+    rev,
+    hasPending,
+    change,
+    doc
+  };
+}
+function usePatchesSync() {
+  const { sync } = usePatchesContext();
+  if (!sync) {
+    throw new Error("PatchesSync not found in context. Did you forget to pass sync to PatchesProvider?");
+  }
+  const [connected, setConnected] = createSignal(sync.state.connected);
+  const [syncing, setSyncing] = createSignal(sync.state.syncing === "updating");
+  const [online, setOnline] = createSignal(sync.state.online);
+  const unsubscribe = sync.onStateChange((state) => {
+    setConnected(state.connected);
+    setSyncing(state.syncing === "updating");
+    setOnline(state.online);
+  });
+  onCleanup(() => {
+    unsubscribe();
+  });
+  return {
+    connected,
+    syncing,
+    online
+  };
+}
+function toAccessor(value) {
+  return typeof value === "function" ? value : () => value;
+}
+function createPatchesDoc(name) {
+  const Context = createContext();
+  function Provider(props) {
+    const { patches } = usePatchesContext();
+    const manager = getDocManager(patches);
+    const autoClose = props.autoClose ?? false;
+    const [doc, setDoc] = createSignal(void 0);
+    const [data, setData] = createSignal(void 0);
+    const [loading, setLoading] = createSignal(true);
+    const [error, setError] = createSignal(null);
+    const [rev, setRev] = createSignal(0);
+    const [hasPending, setHasPending] = createSignal(false);
+    function setupDoc(patchesDoc) {
+      setDoc(patchesDoc);
+      const unsubState = patchesDoc.subscribe((state) => {
+        setData(() => state);
+        setRev(patchesDoc.committedRev);
+        setHasPending(patchesDoc.hasPending);
+      });
+      onCleanup(() => unsubState());
+      const unsubSync = patchesDoc.onSyncing((syncState) => {
+        setLoading(syncState === "initial" || syncState === "updating");
+        setError(syncState instanceof Error ? syncState : null);
+      });
+      onCleanup(() => unsubSync());
+      setLoading(patchesDoc.syncing !== null);
+    }
+    const docIdAccessor = toAccessor(props.docId);
+    if (autoClose) {
+      const [docResource] = createResource(docIdAccessor, async (id) => {
+        return await manager.openDoc(patches, id);
+      });
+      createEffect(() => {
+        const loadedDoc = docResource();
+        if (loadedDoc) {
+          setupDoc(loadedDoc);
+        }
+        const resourceError = docResource.error;
+        if (resourceError) {
+          setError(resourceError);
+          setLoading(false);
+        }
+      });
+      createEffect((prevId) => {
+        const currentId = docIdAccessor();
+        if (prevId && prevId !== currentId) {
+          manager.closeDoc(patches, prevId);
+        }
+        return currentId;
+      });
+      onCleanup(() => {
+        const id = docIdAccessor();
+        manager.closeDoc(patches, id);
+      });
+    } else {
+      createEffect((prevId) => {
+        const id = docIdAccessor();
+        if (prevId && prevId !== id) {
+          manager.decrementRefCount(prevId);
+        }
+        const patchesDoc = patches.getOpenDoc(id);
+        if (!patchesDoc) {
+          throw new Error(
+            `Document "${id}" is not open. Either open it with patches.openDoc() first, or use autoClose option.`
+          );
+        }
+        manager.incrementRefCount(id);
+        setupDoc(patchesDoc);
+        return id;
+      });
+      onCleanup(() => {
+        const id = docIdAccessor();
+        manager.decrementRefCount(id);
+      });
+    }
+    function change(mutator) {
+      const currentDoc = doc();
+      if (!currentDoc) {
+        throw new Error("Cannot make changes: document not loaded yet");
+      }
+      currentDoc.change(mutator);
+    }
+    const value = {
+      data,
+      loading,
+      error,
+      rev,
+      hasPending,
+      change,
+      doc
+    };
+    return /* @__PURE__ */ React.createElement(Context.Provider, { value, children: props.children });
+  }
+  function useDoc() {
+    const context = useContext(Context);
+    if (!context) {
+      throw new Error(
+        `useDoc('${name}') must be called within the corresponding Provider. Did you forget to wrap your component with the Provider from createPatchesDoc('${name}')?`
+      );
+    }
+    return context;
+  }
+  return {
+    Provider,
+    useDoc
+  };
+}
+export {
+  createPatchesDoc,
+  usePatchesDoc,
+  usePatchesSync
+};

package/dist/types.d.ts

@@ -68,9 +68,9 @@ interface Branch {
     /** The ID of the branch document. */
     id: string;
     /** The ID of the document this document was branched from. */
-    branchedFromId: string;
+    docId: string;
     /** The revision number on the source document where the branch occurred. */
-    branchedRev: number;
+    branchedAtRev: number;
     /** Server-side ISO timestamp when the branch was created (UTC with Z). */
     createdAt: string;
     /** Optional user-friendly name for the branch. */
@@ -80,7 +80,7 @@ interface Branch {
     /** Optional arbitrary metadata associated with the branch record. */
     [metadata: string]: any;
 }
-type EditableBranchMetadata = Disallowed<Branch, 'id' | 'branchedFromId' | 'branchedRev' | 'createdAt' | 'status'>;
+type EditableBranchMetadata = Disallowed<Branch, 'id' | 'docId' | 'branchedAtRev' | 'createdAt' | 'status'>;
 /**
  * Metadata, state snapshot, and included changes for a specific version.
  */
@@ -102,17 +102,17 @@ interface VersionMetadata {
     startedAt: string;
     /** Server-side ISO timestamp of version end (UTC with Z). */
     endedAt: string;
-    /** The revision number this version was created at. */
-    rev: number;
-    /** The revision number on the main timeline before the changes that created this version. If this is an offline/branch version, this is the revision number of the source document where the branch was created and not . */
-    baseRev: number;
+    /** The ending revision number of this version (the last change's rev). */
+    endRev: number;
+    /** The starting revision number of this version (the first change's baseRev). If this is an offline/branch version, this is the revision number of the source document where the branch was created. */
+    startRev: number;
     /** Optional arbitrary metadata associated with the version. */
     [metadata: string]: any;
 }
 type Disallowed<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>> & {
     [P in K]?: never;
 };
-type EditableVersionMetadata = Disallowed<VersionMetadata, 'id' | 'parentId' | 'groupId' | 'origin' | 'branchName' | 'startedAt' | 'endedAt' | 'rev' | 'baseRev'>;
+type EditableVersionMetadata = Disallowed<VersionMetadata, 'id' | 'parentId' | 'groupId' | 'origin' | 'branchName' | 'startedAt' | 'endedAt' | 'endRev' | 'startRev'>;
 /**
  * Options for committing changes.
  */
@@ -155,8 +155,8 @@ interface ListVersionsOptions {
     endBefore?: number | string;
     /** Maximum number of versions to return. */
     limit?: number;
-    /** Sort by startedAt, rev, or baseRev. Defaults to 'rev'. */
-    orderBy?: 'startedAt' | 'rev' | 'baseRev';
+    /** Sort by startedAt, endRev, or startRev. Defaults to 'endRev'. */
+    orderBy?: 'startedAt' | 'endRev' | 'startRev';
     /** Return versions in descending order. Defaults to false (ascending). When reversed, startAfter and endBefore apply to the *reversed* list. */
     reverse?: boolean;
     /** Filter by the origin type. */