@comapeo/core-react 7.2.0 → 9.0.0

package/README.md

@@ -10,6 +10,44 @@ React wrapper for working with [`@comapeo/core`](https://github.com/digidem/coma
 npm install react @tanstack/react-query@5 @comapeo/core-react @comapeo/schema @comapeo/core @comapeo/ipc
 ```
 
+## Setup
+
+### Basic Setup
+
+Wrap your application with `ComapeoCoreProvider` and a React Query `QueryClientProvider`. You will need to be running an instance of [`@comapeo/map-server`](https://github.com/digidem/comapeo-map-server) and provide a `getMapServerBaseUrl` function that returns a Promise resolving to the base URL of your map server:
+
+```tsx
+import { ComapeoCoreProvider } from '@comapeo/core-react'
+import { createServer } from '@comapeo/map-server'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const queryClient = new QueryClient()
+
+const server = createServer()
+const listenPromise = server.listen()
+
+const getMapServerBaseUrl = async () => {
+	const { localPort } = await listenPromise
+	return new URL(`http://localhost:${localPort}/`)
+}
+
+function App() {
+	return (
+		<QueryClientProvider client={queryClient}>
+			<ComapeoCoreProvider
+				clientApi={clientApi}
+				queryClient={queryClient}
+				getMapServerBaseUrl={getMapServerBaseUrl}
+			>
+				<MyApp />
+			</ComapeoCoreProvider>
+		</QueryClientProvider>
+	)
+}
+```
+
+Hooks that communicate with the map server will wait for `getMapServerBaseUrl()` to resolve before making requests, so the provider can be mounted before the server is ready. You can also provide an optional `fetch` prop to use a custom fetch implementation.
+
 ## API Documentation
 
 Still a work in progress. Currently lives in [`docs/API.md`](./docs/API.md).

package/dist/commonjs/contexts/ClientApi.d.ts

@@ -1,6 +1,11 @@
-import type { MapeoClientApi } from '@comapeo/ipc' with { 'resolution-mode': 'import' };
-import { type Context, type JSX, type ReactNode } from 'react';
+import type { MapeoClientApi } from '@comapeo/ipc' with {
+    'resolution-mode': 'import'
+};
+import { type Context, type JSX, type PropsWithChildren } from 'react';
 export declare const ClientApiContext: Context<MapeoClientApi | null>;
+export type ClientApiProviderProps = PropsWithChildren<{
+    clientApi: MapeoClientApi;
+}>;
 /**
  * Create a context provider that holds a CoMapeo API client instance.
  *
@@ -8,7 +13,4 @@ export declare const ClientApiContext: Context<MapeoClientApi | null>;
  * @param opts.clientApi Client API instance
  *
  */
-export declare function ClientApiProvider({ children, clientApi, }: {
-    children: ReactNode;
-    clientApi: MapeoClientApi;
-}): JSX.Element;
+export declare function ClientApiProvider({ children, clientApi, }: ClientApiProviderProps): JSX.Element;

package/dist/commonjs/contexts/ClientApi.js

@@ -2,7 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClientApiContext = void 0;
 exports.ClientApiProvider = ClientApiProvider;
+const react_query_1 = require("@tanstack/react-query");
 const react_1 = require("react");
+const invites_js_1 = require("../lib/react-query/invites.js");
 exports.ClientApiContext = (0, react_1.createContext)(null);
 /**
  * Create a context provider that holds a CoMapeo API client instance.
@@ -12,5 +14,18 @@ exports.ClientApiContext = (0, react_1.createContext)(null);
  *
  */
 function ClientApiProvider({ children, clientApi, }) {
+    const queryClient = (0, react_query_1.useQueryClient)();
+    (0, react_1.useEffect)(() => {
+        function invalidateInviteCache() {
+            queryClient.invalidateQueries({ queryKey: (0, invites_js_1.getInvitesQueryKey)() });
+        }
+        // Invite listeners
+        clientApi.invite.addListener('invite-received', invalidateInviteCache);
+        clientApi.invite.addListener('invite-updated', invalidateInviteCache);
+        return () => {
+            clientApi.invite.removeListener('invite-received', invalidateInviteCache);
+            clientApi.invite.removeListener('invite-updated', invalidateInviteCache);
+        };
+    }, [clientApi, queryClient]);
     return (0, react_1.createElement)(exports.ClientApiContext.Provider, { value: clientApi }, children);
 }

package/dist/commonjs/contexts/ComapeoCore.d.ts

@@ -0,0 +1,8 @@
+import { type JSX } from 'react';
+import { type ClientApiProviderProps } from './ClientApi.js';
+import { type MapServerProviderProps } from './MapServer.js';
+type ComapeoCoreProviderProps = ClientApiProviderProps & Omit<MapServerProviderProps, 'getBaseUrl'> & {
+    getMapServerBaseUrl(): Promise<URL>;
+};
+export declare function ComapeoCoreProvider({ children, clientApi, getMapServerBaseUrl, fetch, queryClient, }: ComapeoCoreProviderProps): JSX.Element;
+export {};

package/dist/commonjs/contexts/ComapeoCore.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComapeoCoreProvider = ComapeoCoreProvider;
+const react_1 = require("react");
+const ClientApi_js_1 = require("./ClientApi.js");
+const MapServer_js_1 = require("./MapServer.js");
+function ComapeoCoreProvider({ children, clientApi, getMapServerBaseUrl, fetch, queryClient, }) {
+    return (0, react_1.createElement)(ClientApi_js_1.ClientApiProvider, { clientApi }, (0, react_1.createElement)(MapServer_js_1.MapServerProvider, { getBaseUrl: getMapServerBaseUrl, fetch, queryClient }, children));
+}

package/dist/commonjs/contexts/MapServer.d.ts

@@ -0,0 +1,69 @@
+import { type QueryClient } from '@tanstack/react-query';
+import { type EventSourceClient, type EventSourceOptions } from 'eventsource-client';
+import { type Context, type JSX, type PropsWithChildren } from 'react';
+import { createHttp } from '../lib/http.js';
+export type MapServerApiOptions = {
+    getBaseUrl(): Promise<URL>;
+    /**
+     * We assume the passed fetch implementation will only accept a `string` as
+     * input, not a `URL` or `Request`, because right now the expo/fetch
+     * implementation will only accept a `string`. Adding this restriction will
+     * catch potential issues if we try to pass a URL in our code. Can be relaxed
+     * when https://github.com/expo/expo/issues/43193 is fixed upstream.
+     */
+    fetch?(input: string, options?: RequestInit): Promise<Response>;
+};
+export type MapServerApi = ReturnType<typeof createHttp> & {
+    createEventSource(options: EventSourceOptions): EventSourceClient;
+    getMapStyleJsonUrl(mapId: string): Promise<string>;
+};
+/**
+ * Utility function to create a MapServerApi instance.
+ * Only exported for unit testing purposes.
+ * @private
+ *
+ * @param opts.getBaseUrl A function that returns a promise that resolves to the base URL of the map server.
+ * @param opts.fetch An optional custom fetch function to use for making requests to the map server. If not provided, the global `fetch` will be used.
+ */
+export declare function createMapServerApi({ getBaseUrl, fetch, }: MapServerApiOptions): MapServerApi;
+export declare const MapServerContext: Context<MapServerApi | null>;
+export type MapServerProviderProps = PropsWithChildren<MapServerApiOptions & {
+    queryClient: QueryClient;
+}>;
+/**
+ * Create a context provider that holds a `MapServerFetch` function, which waits
+ * for the map server to be ready before making requests.
+ *
+ * @param opts.children React children node
+ * @param opts.getBaseUrl A function that returns a promise that resolves to the base URL of the map server.
+ * @param opts.fetch An optional custom fetch function to use for making requests to the map server. If not provided, the global `fetch` will be used.
+ *
+ * @example
+ * ```tsx
+ * import { createServer } from '@comapeo/map-server'
+ *
+ * const server = createServer()
+ * const listenPromise = server.listen()
+ *
+ * const getBaseUrl = async () => {
+ *   const { localPort } = await listenPromise
+ *   return new URL(`http://localhost:${localPort}/`)
+ * }
+ *
+ * const mapServerApi = createMapServerApi({ getBaseUrl })
+ *
+ * function App() {
+ *   return (
+ *     <MapServerProvider mapServerApi={mapServerApi}>
+ *       <MyApp />
+ *     </MapServerProvider>
+ *   )
+ * }
+ * ```
+ */
+export declare function MapServerProvider({ children, getBaseUrl, fetch, queryClient, }: MapServerProviderProps): JSX.Element;
+/**
+ * Internal hook to get the MapServerApi (instance of ky) from context.
+ * Throws if used outside of MapServerProvider.
+ */
+export declare function useMapServerApi(): MapServerApi;

package/dist/commonjs/contexts/MapServer.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MapServerContext = void 0;
+exports.createMapServerApi = createMapServerApi;
+exports.MapServerProvider = MapServerProvider;
+exports.useMapServerApi = useMapServerApi;
+const eventsource_client_1 = require("eventsource-client");
+const react_1 = require("react");
+const client_js_1 = require("../hooks/client.js");
+const http_js_1 = require("../lib/http.js");
+const MapShares_js_1 = require("./MapShares.js");
+/**
+ * Utility function to create a MapServerApi instance.
+ * Only exported for unit testing purposes.
+ * @private
+ *
+ * @param opts.getBaseUrl A function that returns a promise that resolves to the base URL of the map server.
+ * @param opts.fetch An optional custom fetch function to use for making requests to the map server. If not provided, the global `fetch` will be used.
+ */
+function createMapServerApi({ getBaseUrl, fetch = globalThis.fetch, }) {
+    const wrappedFetch = async (input, init) => {
+        const baseUrl = await getBaseUrl();
+        return fetch(new URL(input, baseUrl).href, init);
+    };
+    const api = (0, http_js_1.createHttp)(wrappedFetch);
+    Object.defineProperty(api, 'createEventSource', {
+        value: (options) => {
+            return (0, eventsource_client_1.createEventSource)({
+                ...options,
+                fetch: async (input, init) => {
+                    const baseUrl = await getBaseUrl();
+                    return fetch(new URL(input, baseUrl).href, init);
+                },
+            });
+        },
+    });
+    Object.defineProperty(api, 'getMapStyleJsonUrl', {
+        value: async (mapId) => {
+            const baseUrl = await getBaseUrl();
+            return new URL(`/maps/${mapId}/style.json`, baseUrl).href;
+        },
+    });
+    return api;
+}
+exports.MapServerContext = (0, react_1.createContext)(null);
+/**
+ * Create a context provider that holds a `MapServerFetch` function, which waits
+ * for the map server to be ready before making requests.
+ *
+ * @param opts.children React children node
+ * @param opts.getBaseUrl A function that returns a promise that resolves to the base URL of the map server.
+ * @param opts.fetch An optional custom fetch function to use for making requests to the map server. If not provided, the global `fetch` will be used.
+ *
+ * @example
+ * ```tsx
+ * import { createServer } from '@comapeo/map-server'
+ *
+ * const server = createServer()
+ * const listenPromise = server.listen()
+ *
+ * const getBaseUrl = async () => {
+ *   const { localPort } = await listenPromise
+ *   return new URL(`http://localhost:${localPort}/`)
+ * }
+ *
+ * const mapServerApi = createMapServerApi({ getBaseUrl })
+ *
+ * function App() {
+ *   return (
+ *     <MapServerProvider mapServerApi={mapServerApi}>
+ *       <MyApp />
+ *     </MapServerProvider>
+ *   )
+ * }
+ * ```
+ */
+function MapServerProvider({ children, getBaseUrl, fetch, queryClient, }) {
+    const clientApi = (0, client_js_1.useClientApi)();
+    const mapServerApi = (0, react_1.useMemo)(() => createMapServerApi({ getBaseUrl, fetch }), [getBaseUrl, fetch]);
+    return (0, react_1.createElement)(exports.MapServerContext.Provider, { value: mapServerApi }, (0, react_1.createElement)(MapShares_js_1.SentMapSharesProvider, { clientApi, mapServerApi }, (0, react_1.createElement)(MapShares_js_1.ReceivedMapSharesProvider, { clientApi, mapServerApi, queryClient }, children)));
+}
+/**
+ * Internal hook to get the MapServerApi (instance of ky) from context.
+ * Throws if used outside of MapServerProvider.
+ */
+function useMapServerApi() {
+    const api = (0, react_1.useContext)(exports.MapServerContext);
+    if (!api) {
+        throw new Error('useMapServerApi must be used within a MapServerProvider');
+    }
+    return api;
+}

package/dist/commonjs/contexts/MapShares.d.ts

@@ -0,0 +1,52 @@
+import type { MapeoClientApi } from '@comapeo/ipc';
+import type { QueryClient } from '@tanstack/react-query';
+import { type Context, type JSX, type PropsWithChildren } from 'react';
+import { type ReceivedMapSharesStore, type ReceivedMapShareState, type SentMapSharesStore, type SentMapShareState } from '../lib/map-shares-stores.js';
+import type { MapServerApi } from './MapServer.js';
+/**
+ * @internal
+ */
+export declare const ReceivedMapSharesContext: Context<ReceivedMapSharesStore | null>;
+/**
+ * @internal
+ */
+export declare const SentMapSharesContext: Context<SentMapSharesStore | null>;
+type MapSharesProviderProps = PropsWithChildren<{
+    clientApi: MapeoClientApi;
+    mapServerApi: MapServerApi;
+}>;
+/**
+ * @internal
+ */
+export declare function ReceivedMapSharesProvider({ children, clientApi, mapServerApi, queryClient, }: MapSharesProviderProps & {
+    queryClient: QueryClient;
+}): JSX.Element;
+/**
+ * @internal
+ */
+export declare function SentMapSharesProvider({ children, clientApi, mapServerApi, }: MapSharesProviderProps): JSX.Element;
+/**
+ * @internal
+ */
+export declare function useReceivedMapSharesActions(): {
+    download({ shareId }: import("../lib/map-shares-stores.js").DownloadMapShareOptions): Promise<void>;
+    decline({ shareId, reason }: import("../lib/map-shares-stores.js").DeclineMapShareOptions): Promise<void>;
+    abort({ shareId }: import("../lib/map-shares-stores.js").AbortMapShareOptions): Promise<void>;
+};
+/**
+ * @internal
+ */
+export declare function useReceivedMapSharesState(): Array<ReceivedMapShareState>;
+export declare function useReceivedMapSharesState<T>(selector: (state: Array<ReceivedMapShareState>) => T): T;
+/**
+ * @internal
+ */
+export declare function useSentMapSharesActions(): {
+    createAndSend({ projectId, receiverDeviceId, mapId, }: import("../lib/map-shares-stores.js").CreateAndSendMapShareOptions): Promise<import("@comapeo/map-server", { with: { "resolution-mode": "import" } }).MapShareState>;
+    cancel({ shareId }: import("../lib/map-shares-stores.js").CancelMapShareOptions): Promise<void>;
+};
+/**
+ * @internal
+ */
+export declare function useSentMapSharesState<T>(selector?: (state: Array<SentMapShareState>) => T): T;
+export {};

package/dist/commonjs/contexts/MapShares.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentMapSharesContext = exports.ReceivedMapSharesContext = void 0;
+exports.ReceivedMapSharesProvider = ReceivedMapSharesProvider;
+exports.SentMapSharesProvider = SentMapSharesProvider;
+exports.useReceivedMapSharesActions = useReceivedMapSharesActions;
+exports.useReceivedMapSharesState = useReceivedMapSharesState;
+exports.useSentMapSharesActions = useSentMapSharesActions;
+exports.useSentMapSharesState = useSentMapSharesState;
+const react_1 = require("react");
+const map_shares_stores_js_1 = require("../lib/map-shares-stores.js");
+/**
+ * @internal
+ */
+exports.ReceivedMapSharesContext = (0, react_1.createContext)(null);
+/**
+ * @internal
+ */
+exports.SentMapSharesContext = (0, react_1.createContext)(null);
+/**
+ * @internal
+ */
+function ReceivedMapSharesProvider({ children, clientApi, mapServerApi, queryClient, }) {
+    const mapSharesStore = (0, react_1.useMemo)(() => (0, map_shares_stores_js_1.createReceivedMapSharesStore)({ clientApi, mapServerApi, queryClient }), [clientApi, mapServerApi, queryClient]);
+    return (0, react_1.createElement)(exports.ReceivedMapSharesContext.Provider, { value: mapSharesStore }, children);
+}
+/**
+ * @internal
+ */
+function SentMapSharesProvider({ children, clientApi, mapServerApi, }) {
+    const mapSharesStore = (0, react_1.useMemo)(() => (0, map_shares_stores_js_1.createSentMapSharesStore)({ clientApi, mapServerApi }), [clientApi, mapServerApi]);
+    return (0, react_1.createElement)(exports.SentMapSharesContext.Provider, { value: mapSharesStore }, children);
+}
+const identity = (arg) => arg;
+/**
+ * Internal hook to get the MapSharesStore from context.
+ */
+function useMapSharesActions(context) {
+    const store = (0, react_1.useContext)(context);
+    if (!store) {
+        throw new Error('useMapSharesActions must be used within MapSharesProvider');
+    }
+    return store.actions;
+}
+function useMapSharesState(context, selector = identity) {
+    const store = (0, react_1.useContext)(context);
+    if (!store) {
+        throw new Error('useMapSharesState must be used within MapSharesProvider');
+    }
+    return (0, react_1.useSyncExternalStore)(store.subscribe, (0, react_1.useCallback)(
+    // Casting here because of TS not resolving generic conditional types correctly
+    () => selector(store.getSnapshot()), [selector, store]));
+}
+/**
+ * @internal
+ */
+function useReceivedMapSharesActions() {
+    return useMapSharesActions(exports.ReceivedMapSharesContext);
+}
+function useReceivedMapSharesState(selector) {
+    return useMapSharesState(exports.ReceivedMapSharesContext, selector);
+}
+/**
+ * @internal
+ */
+function useSentMapSharesActions() {
+    return useMapSharesActions(exports.SentMapSharesContext);
+}
+/**
+ * @internal
+ */
+function useSentMapSharesState(selector) {
+    return useMapSharesState(exports.SentMapSharesContext, selector);
+}

package/dist/commonjs/hooks/client.d.ts

@@ -1,4 +1,6 @@
-import type { MapeoClientApi } from '@comapeo/ipc' with { 'resolution-mode': 'import' };
+import type { MapeoClientApi } from '@comapeo/ipc' with {
+    'resolution-mode': 'import'
+};
 /**
  * Access a client API instance. If a ClientApiContext provider is not
  * set up, it will throw an error.

package/dist/commonjs/hooks/documents.d.ts

@@ -1,4 +1,6 @@
-import type { Preset } from '@comapeo/schema' with { 'resolution-mode': 'import' };
+import type { Preset } from '@comapeo/schema' with {
+    'resolution-mode': 'import'
+};
 import type { WriteableDocumentType } from '../lib/types.js';
 /**
  * Retrieve a single document from the database based on the document's document ID.

package/dist/commonjs/hooks/invites.d.ts

@@ -1,19 +1,3 @@
-/**
- * Set up listeners for received and updated invites.
- * It is necessary to use this if you want the invites-related read hooks to update
- * based on invites that are received or changed in the background.
- *
- * @example
- * ```tsx
- * function App() {
- *   // Use this somewhere near the root of the application
- *   useSetUpInvitesListeners()
- *
- *   return <RestOfApp />
- * }
- * ```
- */
-export declare function useSetUpInvitesListeners(): void;
 /**
  * Get all invites that the device has received.
  *

package/dist/commonjs/hooks/invites.js

@@ -1,6 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useSetUpInvitesListeners = useSetUpInvitesListeners;
 exports.useManyInvites = useManyInvites;
 exports.useSingleInvite = useSingleInvite;
 exports.useAcceptInvite = useAcceptInvite;
@@ -8,40 +7,9 @@ exports.useRejectInvite = useRejectInvite;
 exports.useSendInvite = useSendInvite;
 exports.useRequestCancelInvite = useRequestCancelInvite;
 const react_query_1 = require("@tanstack/react-query");
-const react_1 = require("react");
 const invites_js_1 = require("../lib/react-query/invites.js");
 const client_js_1 = require("./client.js");
 const projects_js_1 = require("./projects.js");
-/**
- * Set up listeners for received and updated invites.
- * It is necessary to use this if you want the invites-related read hooks to update
- * based on invites that are received or changed in the background.
- *
- * @example
- * ```tsx
- * function App() {
- *   // Use this somewhere near the root of the application
- *   useSetUpInvitesListeners()
- *
- *   return <RestOfApp />
- * }
- * ```
- */
-function useSetUpInvitesListeners() {
-    const queryClient = (0, react_query_1.useQueryClient)();
-    const clientApi = (0, client_js_1.useClientApi)();
-    (0, react_1.useEffect)(() => {
-        function invalidateCache() {
-            queryClient.invalidateQueries({ queryKey: (0, invites_js_1.getInvitesQueryKey)() });
-        }
-        clientApi.invite.addListener('invite-received', invalidateCache);
-        clientApi.invite.addListener('invite-updated', invalidateCache);
-        return () => {
-            clientApi.invite.removeListener('invite-received', invalidateCache);
-            clientApi.invite.removeListener('invite-updated', invalidateCache);
-        };
-    }, [clientApi, queryClient]);
-}
 /**
  * Get all invites that the device has received.
  *