@comapeo/core-react 0.1.1 → 1.0.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.1.2](https://github.com/digidem/comapeo-core-react/compare/v0.1.1...v0.1.2) (2024-12-12)
+
+
+### Bug Fixes
+
+* fix return value of getIsArchiveDeviceQueryKey() ([8742fc2](https://github.com/digidem/comapeo-core-react/commit/8742fc24379564f64f9ec25c4c2e9179083d659d))
+
 ## [0.1.1](https://github.com/digidem/comapeo-core-react/compare/v0.1.0...v0.1.1) (2024-12-12)
 
 

package/README.md

@@ -4,10 +4,10 @@ React wrapper for working with [`@comapeo/core`](https://github.com/digidem/coma
 
 ## Installation
 
-`@comapeo/schema`, `@comapeo/core`, and `@comapeo/ipc` are peer deps and must be installed alongside this package. You may want to pin these to specific versions depending on your needs.
+`react`, `@tanstack/react-query`, `@comapeo/schema`, `@comapeo/core`, and `@comapeo/ipc` are peer deps and must be installed alongside this package. You may want to pin these to specific versions depending on your needs.
 
 ```sh
-npm install @comapeo/core-react @comapeo/schema @comapeo/core @comapeo/ipc
+npm install react @tanstack/react-query@5 @comapeo/core-react @comapeo/schema @comapeo/core @comapeo/ipc
 ```
 
 ## API Documentation

package/dist/contexts/ClientApi.d.ts

@@ -4,7 +4,7 @@ export declare const ClientApiContext: import("react").Context<import("@comapeo/
 /**
  * Create a context provider that holds a CoMapeo API client instance.
  *
- * @param {Object} opts
+ * @param opts
  * @param {ReactNode} opts.children React children node
  * @param {MapeoClientApi} opts.clientApi Client API instance
  */

package/dist/contexts/ClientApi.js

@@ -3,7 +3,7 @@ export const ClientApiContext = createContext(null);
 /**
  * Create a context provider that holds a CoMapeo API client instance.
  *
- * @param {Object} opts
+ * @param opts
  * @param {ReactNode} opts.children React children node
  * @param {MapeoClientApi} opts.clientApi Client API instance
  */

package/dist/hooks/client.d.ts

@@ -2,7 +2,7 @@
  * Access a client API instance. If a ClientApiContext provider is not
  * set up, it will throw an error.
  *
- * @returns {import('@comapeo/ipc').MapeoClientApi} Client API instance
+ * @returns Client API instance
  *
  * @example
  * ```tsx

package/dist/hooks/client.js

@@ -6,7 +6,7 @@ import { deviceInfoQueryOptions, isArchiveDeviceQueryOptions, } from '../lib/rea
  * Access a client API instance. If a ClientApiContext provider is not
  * set up, it will throw an error.
  *
- * @returns {import('@comapeo/ipc').MapeoClientApi} Client API instance
+ * @returns Client API instance
  *
  * @example
  * ```tsx

package/dist/hooks/documents.d.ts

@@ -1,15 +1,19 @@
-import { documentByDocumentIdQueryOptions, documentByVersionIdQueryOptions, documentsQueryOptions, type DocumentType } from '../lib/react-query/documents';
+import type { MapeoDoc } from '@comapeo/schema';
+import { type DocumentType } from '../lib/react-query/documents';
+type ReadHookResult<D> = {
+    data: D;
+    error: Error | null;
+    isRefetching: boolean;
+};
 /**
  * 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 {Object} opts
- * @param {string} opts.projectId Project public ID
- * @param {DocumentType} opts.docType Document type of interest
- * @param {string} opts.docId Document ID
- * @param {Object} [opts.opts]
- * @param {string} [opts.opts.lang] Language to translate the document into
+ * @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
@@ -24,150 +28,23 @@ import { documentByDocumentIdQueryOptions, documentByVersionIdQueryOptions, docu
  * }
  * ```
  */
-export declare function useSingleDocByDocId<D extends DocumentType>({ projectId, docType, docId, opts, }: {
+export declare function useSingleDocByDocId<D extends DocumentType>({ projectId, docType, docId, lang, }: {
     projectId: string;
     docType: D;
     docId: string;
-    opts?: Parameters<typeof documentByDocumentIdQueryOptions>[0]['opts'];
-}): {
-    data: ({
-        schemaName: "track";
-        locations: import("@comapeo/schema/dist/schema/track").Position[];
-        observationRefs: {
-            docId: string;
-            versionId: string;
-        }[];
-        tags: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    }) | ({
-        schemaName: "remoteDetectionAlert";
-        detectionDateStart: string;
-        detectionDateEnd: string;
-        sourceId: string;
-        metadata: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        geometry: import("@comapeo/schema/dist/schema/remoteDetectionAlert").Geometry;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    }) | ({
-        schemaName: "preset";
-        name: string;
-        geometry: ("point" | "vertex" | "line" | "area" | "relation")[];
-        tags: import("@comapeo/schema/dist/schema/preset").Tags;
-        addTags: import("@comapeo/schema/dist/schema/preset").Tags1;
-        removeTags: import("@comapeo/schema/dist/schema/preset").Tags2;
-        fieldRefs: {
-            docId: string;
-            versionId: string;
-        }[];
-        iconRef?: {
-            docId: string;
-            versionId: string;
-        } | undefined;
-        terms: string[];
-        color?: string | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    }) | ({
-        schemaName: "observation";
-        lat?: number | undefined;
-        lon?: number | undefined;
-        attachments: {
-            driveDiscoveryId: string;
-            name: string;
-            type: "attachment_type_unspecified" | "photo" | "video" | "audio" | "UNRECOGNIZED";
-            hash: string;
-        }[];
-        tags: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        metadata?: {
-            manualLocation?: boolean;
-            position?: import("@comapeo/schema/dist/schema/observation").Position;
-            lastSavedPosition?: import("@comapeo/schema/dist/schema/observation").Position;
-            positionProvider?: {
-                gpsAvailable?: boolean;
-                passiveAvailable?: boolean;
-                locationServicesEnabled: boolean;
-                networkAvailable?: boolean;
-            };
-        } | undefined;
-        presetRef?: {
-            docId: string;
-            versionId: string;
-        } | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    }) | ({
-        schemaName: "field";
-        tagKey: string;
-        type: "type_unspecified" | "text" | "number" | "selectOne" | "selectMultiple" | "UNRECOGNIZED";
-        label: string;
-        appearance?: ("appearance_unspecified" | "singleline" | "multiline" | "UNRECOGNIZED") | undefined;
-        snakeCase?: boolean | undefined;
-        options?: {
-            label: string;
-            value: string | boolean | number | null;
-        }[] | undefined;
-        universal?: boolean | undefined;
-        placeholder?: string | undefined;
-        helperText?: string | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    });
-    error: Error | null;
-    isRefetching: boolean;
-};
+    lang?: string;
+}): ReadHookResult<Extract<MapeoDoc, {
+    schemaName: D;
+}>>;
 /**
  * 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 {Object} opts
- * @param {string} opts.projectId Project public ID
- * @param {DocumentType} opts.docType Document type of interest
- * @param {string} opts.versionId Document's version ID
- * @param {Object} [opts.opts]
- * @param {string} [opts.opts.lang] Language to translate the document into
+ * @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
@@ -182,138 +59,21 @@ export declare function useSingleDocByDocId<D extends DocumentType>({ projectId,
  * }
  * ```
  */
-export declare function useSingleDocByVersionId<D extends DocumentType>({ projectId, docType, versionId, opts, }: {
+export declare function useSingleDocByVersionId<D extends DocumentType>({ projectId, docType, versionId, lang, }: {
     projectId: string;
     docType: D;
     versionId: string;
-    opts?: Parameters<typeof documentByVersionIdQueryOptions>[0]['opts'];
-}): {
-    data: {
-        schemaName: "track";
-        locations: import("@comapeo/schema/dist/schema/track").Position[];
-        observationRefs: {
-            docId: string;
-            versionId: string;
-        }[];
-        tags: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } | {
-        schemaName: "remoteDetectionAlert";
-        detectionDateStart: string;
-        detectionDateEnd: string;
-        sourceId: string;
-        metadata: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        geometry: import("@comapeo/schema/dist/schema/remoteDetectionAlert").Geometry;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } | {
-        schemaName: "preset";
-        name: string;
-        geometry: ("point" | "vertex" | "line" | "area" | "relation")[];
-        tags: import("@comapeo/schema/dist/schema/preset").Tags;
-        addTags: import("@comapeo/schema/dist/schema/preset").Tags1;
-        removeTags: import("@comapeo/schema/dist/schema/preset").Tags2;
-        fieldRefs: {
-            docId: string;
-            versionId: string;
-        }[];
-        iconRef?: {
-            docId: string;
-            versionId: string;
-        } | undefined;
-        terms: string[];
-        color?: string | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } | {
-        schemaName: "observation";
-        lat?: number | undefined;
-        lon?: number | undefined;
-        attachments: {
-            driveDiscoveryId: string;
-            name: string;
-            type: "attachment_type_unspecified" | "photo" | "video" | "audio" | "UNRECOGNIZED";
-            hash: string;
-        }[];
-        tags: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        metadata?: {
-            manualLocation?: boolean;
-            position?: import("@comapeo/schema/dist/schema/observation").Position;
-            lastSavedPosition?: import("@comapeo/schema/dist/schema/observation").Position;
-            positionProvider?: {
-                gpsAvailable?: boolean;
-                passiveAvailable?: boolean;
-                locationServicesEnabled: boolean;
-                networkAvailable?: boolean;
-            };
-        } | undefined;
-        presetRef?: {
-            docId: string;
-            versionId: string;
-        } | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } | {
-        schemaName: "field";
-        tagKey: string;
-        type: "type_unspecified" | "text" | "number" | "selectOne" | "selectMultiple" | "UNRECOGNIZED";
-        label: string;
-        appearance?: ("appearance_unspecified" | "singleline" | "multiline" | "UNRECOGNIZED") | undefined;
-        snakeCase?: boolean | undefined;
-        options?: {
-            label: string;
-            value: string | boolean | number | null;
-        }[] | undefined;
-        universal?: boolean | undefined;
-        placeholder?: string | undefined;
-        helperText?: string | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    };
-    error: Error | null;
-    isRefetching: boolean;
-};
+    lang?: string;
+}): ReadHookResult<Extract<MapeoDoc, {
+    schemaName: D;
+}>>;
 /**
  * Retrieve all documents of a specific `docType`.
  *
- * @param {Object} opts
- * @param {string} opts.projectId Project public ID
- * @param {DocumentType} opts.docType Document type of interest
- * @param {Object} [opts.opts]
- * @param {boolean} [opts.opts.includeDeleted] Include documents that have been marked as deleted
- * @param {string} [opts.opts.lang] Language to translate the documents into
+ * @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
@@ -341,135 +101,12 @@ export declare function useSingleDocByVersionId<D extends DocumentType>({ projec
  * }
  * ```
  */
-export declare function useManyDocs<D extends DocumentType>({ projectId, docType, opts, }: {
+export declare function useManyDocs<D extends DocumentType>({ projectId, docType, includeDeleted, lang, }: {
     projectId: string;
     docType: D;
-    opts?: Parameters<typeof documentsQueryOptions>[0]['opts'];
-}): {
-    data: ({
-        schemaName: "track";
-        locations: import("@comapeo/schema/dist/schema/track").Position[];
-        observationRefs: {
-            docId: string;
-            versionId: string;
-        }[];
-        tags: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    })[] | ({
-        schemaName: "remoteDetectionAlert";
-        detectionDateStart: string;
-        detectionDateEnd: string;
-        sourceId: string;
-        metadata: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        geometry: import("@comapeo/schema/dist/schema/remoteDetectionAlert").Geometry;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    })[] | ({
-        schemaName: "preset";
-        name: string;
-        geometry: ("point" | "vertex" | "line" | "area" | "relation")[];
-        tags: import("@comapeo/schema/dist/schema/preset").Tags;
-        addTags: import("@comapeo/schema/dist/schema/preset").Tags1;
-        removeTags: import("@comapeo/schema/dist/schema/preset").Tags2;
-        fieldRefs: {
-            docId: string;
-            versionId: string;
-        }[];
-        iconRef?: {
-            docId: string;
-            versionId: string;
-        } | undefined;
-        terms: string[];
-        color?: string | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    })[] | ({
-        schemaName: "observation";
-        lat?: number | undefined;
-        lon?: number | undefined;
-        attachments: {
-            driveDiscoveryId: string;
-            name: string;
-            type: "attachment_type_unspecified" | "photo" | "video" | "audio" | "UNRECOGNIZED";
-            hash: string;
-        }[];
-        tags: {
-            [k: string]: boolean | number | string | null | (boolean | number | string | null)[];
-        };
-        metadata?: {
-            manualLocation?: boolean;
-            position?: import("@comapeo/schema/dist/schema/observation").Position;
-            lastSavedPosition?: import("@comapeo/schema/dist/schema/observation").Position;
-            positionProvider?: {
-                gpsAvailable?: boolean;
-                passiveAvailable?: boolean;
-                locationServicesEnabled: boolean;
-                networkAvailable?: boolean;
-            };
-        } | undefined;
-        presetRef?: {
-            docId: string;
-            versionId: string;
-        } | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    })[] | ({
-        schemaName: "field";
-        tagKey: string;
-        type: "type_unspecified" | "text" | "number" | "selectOne" | "selectMultiple" | "UNRECOGNIZED";
-        label: string;
-        appearance?: ("appearance_unspecified" | "singleline" | "multiline" | "UNRECOGNIZED") | undefined;
-        snakeCase?: boolean | undefined;
-        options?: {
-            label: string;
-            value: string | boolean | number | null;
-        }[] | undefined;
-        universal?: boolean | undefined;
-        placeholder?: string | undefined;
-        helperText?: string | undefined;
-        docId: string;
-        versionId: string;
-        originalVersionId: string;
-        createdAt: string;
-        updatedAt: string;
-        links: string[];
-        deleted: boolean;
-    } & {
-        forks: string[];
-    })[];
-    error: Error | null;
-    isRefetching: boolean;
-};
+    includeDeleted?: boolean;
+    lang?: string;
+}): ReadHookResult<Extract<MapeoDoc, {
+    schemaName: D;
+}>>;
+export {};

package/dist/hooks/documents.js

@@ -1,18 +1,15 @@
 import { useSuspenseQuery } from '@tanstack/react-query';
 import { documentByDocumentIdQueryOptions, documentByVersionIdQueryOptions, documentsQueryOptions, } from '../lib/react-query/documents';
 import { useSingleProject } from './projects';
-// TODO: Return type is not narrowed properly by `docType`
 /**
  * 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 {Object} opts
- * @param {string} opts.projectId Project public ID
- * @param {DocumentType} opts.docType Document type of interest
- * @param {string} opts.docId Document ID
- * @param {Object} [opts.opts]
- * @param {string} [opts.opts.lang] Language to translate the document into
+ * @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
@@ -27,29 +24,33 @@ import { useSingleProject } from './projects';
  * }
  * ```
  */
-export function useSingleDocByDocId({ projectId, docType, docId, opts, }) {
+export function useSingleDocByDocId({ projectId, docType, docId, lang, }) {
     const { data: projectApi } = useSingleProject({ projectId });
     const { data, error, isRefetching } = useSuspenseQuery(documentByDocumentIdQueryOptions({
         projectApi,
         projectId,
         docType,
         docId,
-        opts,
+        lang,
     }));
-    return { data, error, isRefetching };
+    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,
+    };
 }
-// TODO: Return type is not narrowed properly by `docType`
 /**
  * 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 {Object} opts
- * @param {string} opts.projectId Project public ID
- * @param {DocumentType} opts.docType Document type of interest
- * @param {string} opts.versionId Document's version ID
- * @param {Object} [opts.opts]
- * @param {string} [opts.opts.lang] Language to translate the document into
+ * @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
@@ -64,27 +65,29 @@ export function useSingleDocByDocId({ projectId, docType, docId, opts, }) {
  * }
  * ```
  */
-export function useSingleDocByVersionId({ projectId, docType, versionId, opts, }) {
+export function useSingleDocByVersionId({ projectId, docType, versionId, lang, }) {
     const { data: projectApi } = useSingleProject({ projectId });
     const { data, error, isRefetching } = useSuspenseQuery(documentByVersionIdQueryOptions({
         projectApi,
         projectId,
         docType,
         versionId,
-        opts,
+        lang,
     }));
-    return { data, error, isRefetching };
+    return {
+        // @ts-expect-error - TS does not handle dependent types, see above
+        data,
+        error,
+        isRefetching,
+    };
 }
-// TODO: Return type is not narrowed properly by `docType`
 /**
  * Retrieve all documents of a specific `docType`.
  *
- * @param {Object} opts
- * @param {string} opts.projectId Project public ID
- * @param {DocumentType} opts.docType Document type of interest
- * @param {Object} [opts.opts]
- * @param {boolean} [opts.opts.includeDeleted] Include documents that have been marked as deleted
- * @param {string} [opts.opts.lang] Language to translate the documents into
+ * @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
@@ -112,13 +115,19 @@ export function useSingleDocByVersionId({ projectId, docType, versionId, opts, }
  * }
  * ```
  */
-export function useManyDocs({ projectId, docType, opts, }) {
+export function useManyDocs({ projectId, docType, includeDeleted, lang, }) {
     const { data: projectApi } = useSingleProject({ projectId });
     const { data, error, isRefetching } = useSuspenseQuery(documentsQueryOptions({
         projectApi,
         projectId,
         docType,
-        opts,
+        includeDeleted,
+        lang,
     }));
-    return { data, error, isRefetching };
+    return {
+        // @ts-expect-error - TS does not handle dependent types, see above
+        data,
+        error,
+        isRefetching,
+    };
 }

package/dist/hooks/maps.d.ts

@@ -4,8 +4,7 @@
  * 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 {Object} opts
- * @param {string} opts.refreshToken String to append to the returned value as a search param
+ * @param opts.refreshToken String to append to the returned value as a search param
  *
  * @example
  * ```tsx