@comapeo/core-react 1.0.1 → 1.1.0

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

@@ -0,0 +1,14 @@
+import type { MapeoClientApi } from '@comapeo/ipc' with { 'resolution-mode': 'import' };
+import { type ReactNode } from 'react';
+export declare const ClientApiContext: import("react").Context<import("@comapeo/ipc/dist/client.js", { with: { "resolution-mode": "import" } }).MapeoClientApi | null>;
+/**
+ * Create a context provider that holds a CoMapeo API client instance.
+ *
+ * @param opts
+ * @param {ReactNode} opts.children React children node
+ * @param {MapeoClientApi} opts.clientApi Client API instance
+ */
+export declare function ClientApiProvider({ children, clientApi, }: {
+    children: ReactNode;
+    clientApi: MapeoClientApi;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<import("@comapeo/ipc/dist/client.js", { with: { "resolution-mode": "import" } }).MapeoClientApi | null>>;

package/dist/commonjs/contexts/ClientApi.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientApiContext = void 0;
+exports.ClientApiProvider = ClientApiProvider;
+const react_1 = require("react");
+exports.ClientApiContext = (0, react_1.createContext)(null);
+/**
+ * Create a context provider that holds a CoMapeo API client instance.
+ *
+ * @param opts
+ * @param {ReactNode} opts.children React children node
+ * @param {MapeoClientApi} opts.clientApi Client API instance
+ */
+function ClientApiProvider({ children, clientApi, }) {
+    return (0, react_1.createElement)(exports.ClientApiContext.Provider, { value: clientApi }, children);
+}

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

@@ -0,0 +1,59 @@
+/**
+ * Access a client API instance. If a ClientApiContext provider is not
+ * set up, it will throw an error.
+ *
+ * @returns Client API instance
+ *
+ * @example
+ * ```tsx
+ * function ClientExample() {
+ *   return (
+ *     // Creation of clientApi omitted for brevity
+ *     <ClientApiContext.Provider clientApi={clientApi}>
+ *       <ComponentThatUsesClient />
+ *     </ClientApiContext.Provider>
+ *   )
+ * }
+ *
+ * function ComponentThatUsesClient() {
+ *   const clientApi = useClientApi()
+ *
+ *   // Rest omitted for brevity.
+ * }
+ * ```
+ *
+ */
+export declare function useClientApi(): import("@comapeo/ipc/dist/client.js", { with: { "resolution-mode": "import" } }).MapeoClientApi;
+/**
+ * Retrieve info about the current device.
+ *
+ * @example
+ * ```tsx
+ * function DeviceInfoExample() {
+ *   const { data } = useDeviceInfo()
+ * }
+ * ```
+ */
+export declare function useOwnDeviceInfo(): {
+    data: {
+        deviceId: string;
+        deviceType: "device_type_unspecified" | "mobile" | "tablet" | "desktop" | "selfHostedServer" | "UNRECOGNIZED";
+    } & Partial<import("@comapeo/core/dist/schema/client.js", { with: { "resolution-mode": "import" } }).DeviceInfoParam>;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve whether the current device is an archive device or not.
+ *
+ * @example
+ * ```tsx
+ * function IsArchiveDeviceExample() {
+ *   const { data } = useIsArchiveDevice()
+ * }
+ * ```
+ */
+export declare function useIsArchiveDevice(): {
+    data: boolean;
+    error: Error | null;
+    isRefetching: boolean;
+};

package/dist/commonjs/hooks/client.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useClientApi = useClientApi;
+exports.useOwnDeviceInfo = useOwnDeviceInfo;
+exports.useIsArchiveDevice = useIsArchiveDevice;
+const react_query_1 = require("@tanstack/react-query");
+const react_1 = require("react");
+const ClientApi_js_1 = require("../contexts/ClientApi.js");
+const client_js_1 = require("../lib/react-query/client.js");
+/**
+ * Access a client API instance. If a ClientApiContext provider is not
+ * set up, it will throw an error.
+ *
+ * @returns Client API instance
+ *
+ * @example
+ * ```tsx
+ * function ClientExample() {
+ *   return (
+ *     // Creation of clientApi omitted for brevity
+ *     <ClientApiContext.Provider clientApi={clientApi}>
+ *       <ComponentThatUsesClient />
+ *     </ClientApiContext.Provider>
+ *   )
+ * }
+ *
+ * function ComponentThatUsesClient() {
+ *   const clientApi = useClientApi()
+ *
+ *   // Rest omitted for brevity.
+ * }
+ * ```
+ *
+ */
+function useClientApi() {
+    const clientApi = (0, react_1.useContext)(ClientApi_js_1.ClientApiContext);
+    if (!clientApi) {
+        throw new Error('No client API set. Make sure you set up the ClientApiContext provider properly');
+    }
+    return clientApi;
+}
+/**
+ * Retrieve info about the current device.
+ *
+ * @example
+ * ```tsx
+ * function DeviceInfoExample() {
+ *   const { data } = useDeviceInfo()
+ * }
+ * ```
+ */
+function useOwnDeviceInfo() {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, client_js_1.deviceInfoQueryOptions)({ clientApi }));
+    return { data, error, isRefetching };
+}
+/**
+ * Retrieve whether the current device is an archive device or not.
+ *
+ * @example
+ * ```tsx
+ * function IsArchiveDeviceExample() {
+ *   const { data } = useIsArchiveDevice()
+ * }
+ * ```
+ */
+function useIsArchiveDevice() {
+    const clientApi = useClientApi();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, client_js_1.isArchiveDeviceQueryOptions)({ clientApi }));
+    return { data, error, isRefetching };
+}

package/dist/{hooks → commonjs/hooks}/documents.d.ts

@@ -1,5 +1,5 @@
-import type { MapeoDoc } from '@comapeo/schema';
-import { type DocumentType } from '../lib/react-query/documents';
+import type { MapeoDoc } from '@comapeo/schema' with { 'resolution-mode': 'import' };
+import { type DocumentType } from '../lib/react-query/documents.js';
 type ReadHookResult<D> = {
     data: D;
     error: Error | null;

package/dist/commonjs/hooks/documents.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSingleDocByDocId = useSingleDocByDocId;
+exports.useSingleDocByVersionId = useSingleDocByVersionId;
+exports.useManyDocs = useManyDocs;
+const react_query_1 = require("@tanstack/react-query");
+const documents_js_1 = require("../lib/react-query/documents.js");
+const projects_js_1 = require("./projects.js");
+/**
+ * Retrieve a single document from the database based on the document's document ID.
+ *
+ * Triggers the closest error boundary if the document cannot be found
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.docType Document type of interest
+ * @param opts.docId Document ID
+ * @param opts.lang Language to translate the document into
+ *
+ * @example
+ * ```tsx
+ * function SingleDocumentByDocIdExample() {
+ *   const { data } = useSingleDocByDocId({
+ *     projectId: '...',
+ *     docType: 'observation',
+ *     docId: '...',
+ *   })
+ *
+ *   console.log(data.schemaName) // logs 'observation'
+ * }
+ * ```
+ */
+function useSingleDocByDocId({ projectId, docType, docId, lang, }) {
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, documents_js_1.documentByDocumentIdQueryOptions)({
+        projectApi,
+        projectId,
+        docType,
+        docId,
+        lang,
+    }));
+    return {
+        // @ts-expect-error - TS does not handle dependent types, so this will not
+        // be narrowed properly within the function body. See for example
+        // https://github.com/microsoft/TypeScript/issues/33014#event-15134418011
+        data,
+        error,
+        isRefetching,
+    };
+}
+/**
+ * Retrieve a single document from the database based on the document's version ID.
+ *
+ * Triggers the closest error boundary if the document cannot be found.
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.docType Document type of interest
+ * @param opts.versionId Document's version ID
+ * @param opts.lang Language to translate the document into
+ *
+ *  * @example
+ * ```tsx
+ * function SingleDocumentByVersionIdExample() {
+ *   const { data } = useSingleDocByVersionId({
+ *     projectId: '...',
+ *     docType: 'observation',
+ *     docId: '...',
+ *   })
+ *
+ *   console.log(data.schemaName) // logs 'observation'
+ * }
+ * ```
+ */
+function useSingleDocByVersionId({ projectId, docType, versionId, lang, }) {
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, documents_js_1.documentByVersionIdQueryOptions)({
+        projectApi,
+        projectId,
+        docType,
+        versionId,
+        lang,
+    }));
+    return {
+        // @ts-expect-error - TS does not handle dependent types, see above
+        data,
+        error,
+        isRefetching,
+    };
+}
+/**
+ * Retrieve all documents of a specific `docType`.
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.docType Document type of interest
+ * @param opts.includeDeleted Include documents that have been marked as deleted
+ * @param opts.lang Language to translate the documents into
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyDocs({
+ *     projectId: '...',
+ *     docType: 'observations',
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function useAllObservations(opts) {
+ *   return useManyDocs({
+ *     ...opts,
+ *     docType: 'observations',
+ *   })
+ * }
+ *
+ * function useAllPresets(opts) {
+ *   return useManyDocs({
+ *     ...opts,
+ *     docType: 'presets',
+ *   })
+ * }
+ * ```
+ */
+function useManyDocs({ projectId, docType, includeDeleted, lang, }) {
+    const { data: projectApi } = (0, projects_js_1.useSingleProject)({ projectId });
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, documents_js_1.documentsQueryOptions)({
+        projectApi,
+        projectId,
+        docType,
+        includeDeleted,
+        lang,
+    }));
+    return {
+        // @ts-expect-error - TS does not handle dependent types, see above
+        data,
+        error,
+        isRefetching,
+    };
+}

package/dist/commonjs/hooks/maps.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useMapStyleUrl = useMapStyleUrl;
+const react_query_1 = require("@tanstack/react-query");
+const maps_js_1 = require("../lib/react-query/maps.js");
+const client_js_1 = require("./client.js");
+/**
+ * Get a URL that points to a StyleJSON resource served by the embedded HTTP server.
+ *
+ * If `opts.refreshToken` is specified, it will be appended to the returned URL as a search param. This is useful for forcing cache busting
+ * due to hidden internal details by consuming components (e.g. map component from MapLibre).
+ *
+ * @param opts.refreshToken String to append to the returned value as a search param
+ *
+ * @example
+ * ```tsx
+ * function ExampleWithoutRefreshToken() {
+ *   const { data, isRefetching } = useMapStyleUrl()
+ *
+ *   console.log(data) // logs something like 'http://localhost:...'
+ * }
+ * ```
+ *
+ * ```tsx
+ * function ExampleWithRefreshToken() {
+ *   const [refreshToken] = useState('foo')
+ *   const { data } = useMapStyleUrl({ refreshToken })
+ *
+ *   console.log(data) // logs something like 'http://localhost:...?refresh_token=foo'
+ * }
+ * ```
+ */
+function useMapStyleUrl({ refreshToken, } = {}) {
+    const clientApi = (0, client_js_1.useClientApi)();
+    const { data, error, isRefetching } = (0, react_query_1.useSuspenseQuery)((0, maps_js_1.mapStyleJsonUrlQueryOptions)({ clientApi, refreshToken }));
+    return { data, error, isRefetching };
+}

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

@@ -0,0 +1,251 @@
+import type { BitmapOpts, SvgOpts } from '@comapeo/core/dist/icon-api.js' with { 'resolution-mode': 'import' };
+import type { BlobId } from '@comapeo/core/dist/types.js' with { 'resolution-mode': 'import' };
+/**
+ * Retrieve the project settings for a project.
+ *
+ * @param opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useProjectSettings({ projectId: '...' })
+ *
+ *   console.log(data.name)
+ * }
+ * ```
+ */
+export declare function useProjectSettings({ projectId }: {
+    projectId: string;
+}): {
+    data: import("@comapeo/core/dist/mapeo-project.js", { with: { "resolution-mode": "import" } }).EditableProjectSettings;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a project API instance for a project.
+ *
+ * This is mostly used internally by the other hooks and should only be used if certain project APIs are not exposed via the hooks.
+ *
+ * @param opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleProject({ projectId: '...' })
+ * }
+ * ```
+ */
+export declare function useSingleProject({ projectId }: {
+    projectId: string;
+}): {
+    data: import("rpc-reflector/lib/types.js").ClientApi<import("@comapeo/core/dist/mapeo-project.js", { with: { "resolution-mode": "import" } }).MapeoProject>;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve project information for each project that exists.
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyProjects()
+ *
+ *   console.log(data.map(project => project.name))
+ * }
+ * ```
+ */
+export declare function useManyProjects(): {
+    data: (Pick<{
+        schemaName: "projectSettings";
+        name?: string | undefined;
+        defaultPresets?: {
+            point: string[];
+            area: string[];
+            vertex: string[];
+            line: string[];
+            relation: string[];
+        } | undefined;
+        configMetadata?: {
+            name: string;
+            buildDate: string;
+            importDate: string;
+            fileVersion: string;
+        } | undefined;
+    }, "name"> & {
+        projectId: string;
+        createdAt?: string | undefined;
+        updatedAt?: string | undefined;
+    })[];
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a single member of a project.
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.projectId Device ID of interest
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useSingleMember({ projectId: '...', deviceId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+export declare function useSingleMember({ projectId, deviceId, }: {
+    projectId: string;
+    deviceId: string;
+}): {
+    data: import("@comapeo/core/dist/member-api.js", { with: { "resolution-mode": "import" } }).MemberInfo;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve all members of a project.
+ *
+ * @param opts.projectId Project public ID
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useManyMembers({ projectId: '...' })
+ *
+ *   console.log(data.role)
+ * }
+ * ```
+ */
+export declare function useManyMembers({ projectId }: {
+    projectId: string;
+}): {
+    data: import("@comapeo/core/dist/member-api.js", { with: { "resolution-mode": "import" } }).MemberInfo[];
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a URL that points to icon resources served by the embedded HTTP server.
+ *
+ * _TODO: Explain bitmap opts vs svg opts_
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.iconId Icon ID of interest
+ * @param opts.mimeType MIME type of desired resource
+ * @param opts.pixelDensity Pixel density resource (only applicable when `mimeType` is `'image/png'`)
+ * @param opts.size Size of desired resource
+ *
+ * @example
+ * ```tsx
+ * function PngExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     mimeType: 'image/png',
+ *     pixelDensity: 1,
+ *     size: 'medium'
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function SvgExample() {
+ *   const { data } = useIconUrl({
+ *     projectId: '...',
+ *     iconId: '...',
+ *     mimeType: 'image/svg',
+ *     size: 'medium'
+ *   })
+ * }
+ * ```
+ */
+export declare function useIconUrl({ projectId, iconId, ...mimeBasedOpts }: {
+    projectId: string;
+    iconId: string;
+} & (BitmapOpts | SvgOpts)): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve a URL that points to a desired blob resource.
+ *
+ * _TODO: Explain BlobId in more depth_
+ *
+ * @param opts.projectId Project public Id
+ * @param opts.blobId Blob ID of the desired resource
+ *
+ * @example
+ * ```tsx
+ * function PhotoExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'photo',
+ *       variant: 'thumbnail',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function AudioExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'audio',
+ *       variant: 'original',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ *
+ * ```tsx
+ * function VideoExample() {
+ *   const { data } = useAttachmentUrl({
+ *     projectId: '...',
+ *     blobId: {
+ *       type: 'video',
+ *       variant: 'original',
+ *       name: '...',
+ *       driveId: '...',
+ *     }
+ *   })
+ * }
+ * ```
+ */
+export declare function useAttachmentUrl({ projectId, blobId, }: {
+    projectId: string;
+    blobId: BlobId;
+}): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};
+/**
+ * Retrieve the device ID that created a document.
+ *
+ * @param opts.projectId Project public ID
+ * @param opts.originalVersionId Version ID of document
+ *
+ * @example
+ * ```tsx
+ * function BasicExample() {
+ *   const { data } = useDocumentCreatedBy({
+ *     projectId: '...',
+ *     originalVersionId: '...',
+ *   })
+ * }
+ * ```
+ */
+export declare function useDocumentCreatedBy({ projectId, originalVersionId, }: {
+    projectId: string;
+    originalVersionId: string;
+}): {
+    data: string;
+    error: Error | null;
+    isRefetching: boolean;
+};