@itwin/saved-views-react 0.6.0 → 0.8.0

package/lib/useSavedViews.d.ts

@@ -1,58 +1,191 @@
-import type { SavedView, SavedViewGroup, SavedViewTag, WriteableSavedViewProperties } from "./SavedView.js";
+import { type ReactNode, type SetStateAction } from "react";
+import type { SavedView, SavedViewData, SavedViewGroup, SavedViewTag, WriteableSavedViewProperties } from "./SavedView.js";
 import type { SavedViewsClient } from "./SavedViewsClient/SavedViewsClient.js";
-import type { PartialExcept } from "./utils.js";
-interface UseSavedViewsParams {
+import { type AllOrNone } from "./utils.js";
+type UseSavedViewsArgs = {
     /** iTwin identifier. */
     iTwinId: string;
     /** iModel identifier. */
     iModelId: string;
     /** Implements communication with Saved Views store. */
     client: SavedViewsClient;
+} & AllOrNone<ExternalState>;
+interface ExternalState {
     /**
-     * Invoked when any of {@linkcode SavedViewActions} is triggered. Does not get called again until either
-     * {@linkcode onUpdateComplete} or {@linkcode onUpdateError} is invoked.
+     * Current immutable value of Saved Views store. If provided, it is returned as
+     * {@linkcode UseSavedViewsResult.store}; otherwise an internal store is used.
+     *
+     * @example
+     * const [state, setState] = useState(useSavedViews.emptyState);
+     * const { store } = useSavedViews({ iTwinId, iModelId, client, state, setState });
+     * console.log(store === state); // true
      */
-    onUpdateInProgress?: (() => void) | undefined;
-    /** Invoked once after {@linkcode onUpdateInProgress} when the data is successfully synchronised with the store. */
-    onUpdateComplete?: (() => void) | undefined;
-    /** Invoked once after {@linkcode onUpdateInProgress} when data synchronisation with the store fails. */
-    onUpdateError?: ((error: unknown) => void) | undefined;
+    state: SavedViewsState;
+    /**
+     * Function which updates Saved Views store. It should behave the same as `setState` callback
+     * that is returned by `React.useState`.
+     *
+     * @remarks
+     * When hook arguments change, the state is not cleared automatically.
+     *
+     * @example
+     * const [state, setState] = useState(useSavedViews.emptyState);
+     * const savedViews = useSavedViews({ iTwinId, iModelId, client, state, setState });
+     */
+    setState: (action: SetStateAction<SavedViewsState>) => void;
 }
-interface UseSavedViewsResult {
+export interface SavedViewsState {
+    /** Maps `savedViewId` to {@link SavedView}. */
     savedViews: Map<string, SavedView>;
+    /** Maps `savedViewId` to {@link SavedViewData}. */
+    savedViewData: Map<string, SavedViewData>;
+    /** Maps `groupId` to {@link SavedViewGroup}. */
     groups: Map<string, SavedViewGroup>;
+    /** Maps `tagId` to {@link SavedViewTag}. */
     tags: Map<string, SavedViewTag>;
-    actions: SavedViewActions;
+    /** Maps `savedViewId` to {@link ReactNode} representing Saved View thumbnail. */
+    thumbnails: Map<string, ReactNode>;
 }
-export interface SavedViewActions {
-    submitSavedView: (savedView: SavedViewCreationProps | SavedViewUpdateProps) => Promise<string>;
-    renameSavedView: (savedViewId: string, newName: string | undefined) => void;
-    shareSavedView: (savedViewId: string, share: boolean) => void;
-    deleteSavedView: (savedViewId: string) => void;
-    createGroup: (groupName: string) => void;
-    renameGroup: (groupId: string, newName: string) => void;
-    shareGroup: (groupId: string, share: boolean) => void;
-    moveToGroup: (savedViewId: string, groupId: string) => void;
-    moveToNewGroup: (savedViewId: string, groupName: string) => void;
-    deleteGroup: (groupId: string) => void;
-    addTag: (savedViewId: string, tagId: string) => void;
-    addNewTag: (savedViewId: string, tagName: string) => void;
-    removeTag: (savedViewId: string, tagId: string) => void;
-    uploadThumbnail: (savedViewId: string, imageDataUrl: string) => void;
+interface UseSavedViewsResult extends SavedViewsActions {
+    /**
+     * Immutable state which holds Saved Views data. If {@linkcode UseSavedViewsArgs.state} is not
+     * specified, an internal state is returned; otherwise its value is the same as the provided
+     * `state` argument.
+     */
+    store: SavedViewsState;
+    /**
+     * When invoked, {@link SavedViewsClient} is queried for all available Saved Views, Groups, and
+     * Tags. When the operation ends, all obtained entities are inserted into Saved Views store.
+     *
+     * @param callback Optional callback that is invoked when the operation ends. If an error occurs,
+     *                 the operation gets cancelled and the error object is passed as the argument.
+     * @returns Callback that cancels the operation.
+     *
+     * @example
+     * const { startLoadingData } = useSavedViews({ iTwinId, iModelId, client });
+     * const [isLoading, setIsLoading] = useState(true);
+     * useEffect(
+     *   () => {
+     *     return startLoadingData((error) => {
+     *       setIsLoading(false);
+     *       if (error) {
+     *         console.error(error);
+     *       }
+     *     });
+     *   },
+     *   [],
+     * );
+     */
+    startLoadingData: (callback?: (error?: unknown) => void) => () => void;
+}
+export interface SavedViewsActions {
+    /**
+     * Creates a new {@link SavedView} entity using {@link SavedViewsClient} and stores the result in
+     * Saved Views store.
+     * @returns Identifier of the newly created Saved View.
+     */
+    createSavedView: (savedView: WriteableSavedViewProperties, savedViewData: SavedViewData) => Promise<string>;
+    /**
+     * Retrieves {@link SavedViewData} associated with given {@linkcode savedViewId} from the Saved
+     * Views store if the data is present; otherwise it is queried from {@link SavedViewsClient} and the
+     * store is updated to include the new data.
+     */
+    lookupSavedViewData: (savedViewId: string) => Promise<SavedViewData>;
+    /**
+     * Uses {@link SavedViewsClient} to update {@link SavedView} entity. On success, updates
+     * {@link SavedView} in Saved Views store with provided values.
+     */
+    updateSavedView: (savedViewId: string, savedView: Partial<WriteableSavedViewProperties>, savedViewData?: SavedViewData | undefined) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to update {@link SavedView} entity associated with given {@linkcode savedViewId}.
+     * On success, updates {@link SavedView} in Saved Views store with provided name.
+     */
+    renameSavedView: (savedViewId: string, newName: string) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to mark {@link SavedView} entity as shared or unshared. On
+     * success, updates {@link SavedView} in Saved Views store with provided status.
+     */
+    shareSavedView: (savedViewId: string, shared: boolean) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to delete {@link SavedView} entity. On success, removes
+     * {@link SavedView} from Saved Views store.
+     */
+    deleteSavedView: (savedViewId: string) => Promise<void>;
+    /**
+     * Creates a new {@link SavedViewGroup} entity using {@link SavedViewsClient} and stores the
+     * result in Saved Views store.
+     * @returns Identifier of the newly created Saved View Group.
+     */
+    createGroup: (groupName: string) => Promise<string>;
+    /**
+     * Uses {@link SavedViewsClient} to update {@link SavedViewGroup} entity. On success, updates
+     * {@link SavedViewGroup} in Saved Views store with provided name.
+     */
+    renameGroup: (groupId: string, newName: string) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to mark {@link SavedViewGroup} entity as shared or unshared. On
+     * success, updates {@link SavedViewGroup} in Saved Views store with provided status.
+     */
+    shareGroup: (groupId: string, shared: boolean) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to move {@link SavedView} entity to the specified Saved View group.
+     */
+    moveToGroup: (savedViewId: string, groupId: string | undefined) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to delete {@link SavedViewGroup} entity. On success, removes
+     * {@link SavedViewGroup} from Saved Views store.
+     */
+    deleteGroup: (groupId: string) => Promise<void>;
+    /**
+     * Creates a new {@link SavedViewTag} entity using {@link SavedViewsClient} and stores the result
+     * in Saved Views store.
+     * @returns Identifier of the newly created Saved View Tag.
+     */
+    createTag: (tagName: string) => Promise<string>;
+    /** Uses {@link SavedViewsClient} to add {@link SavedViewTag} to {@link SavedView} entity. */
+    addTag: (savedViewId: string, tagId: string) => Promise<void>;
+    /** Uses {@link SavedViewsClient} to remove {@link SavedViewTag} from {@link SavedView} entity. */
+    removeTag: (savedViewId: string, tagId: string) => Promise<void>;
+    /**
+     * Uses {@link SavedViewsClient} to delete {@link SavedViewTag} entity. On success, removes
+     * {@link SavedViewTag} from Saved Views store.
+     */
+    deleteTag: (tagId: string) => Promise<void>;
+    /** Uses {@link SavedViewsClient} to change thumbnail image for {@link SavedView} entity. */
+    uploadThumbnail: (savedViewId: string, imageDataUrl: string) => Promise<void>;
 }
-type SavedViewCreationProps = PartialExcept<WriteableSavedViewProperties, "displayName" | "viewData">;
-type SavedViewUpdateProps = WriteableSavedViewProperties & {
-    id: string;
-};
 /**
- * Pulls Saved View data from a store and provides means to update and synchronize the data back to it. Interaction with
- * the store is performed via {@linkcode SavedViewsClient} interface which could communicate, for instance, with
- * [iTwin Saved Views API](https://developer.bentley.com/apis/savedviews/overview/) using `ITwinSavedViewsClient`.
+ * Provides basic functionality to help get started with Saved Views.
  *
  * @remarks
- * Note on the current implementation limitations. While the result of the first update action is reflected immediately,
- * subsequent actions are put in a queue and executed serially. This may cause the UI to feel sluggish when user makes
- * changes to Saved Views faster than the Saved Views store can be updated.
+ * When hook arguments change, it does not automatically clear the {@linkcode UseSavedViewsResult.store}.
+ * If you want more control over the state, provide an external store via {@linkcode UseSavedViewsArgs.state}
+ * and {@linkcode UseSavedViewsArgs.setState} arguments.
+ *
+ * @example
+ * const { iTwinId, iModelId, client, viewport } = props;
+ * const savedViews = useSavedViews({ iTwinId, iModelId, client });
+ * const [isLoading, setIsLoading] = useState(true);
+ * useEffect(
+ *   () => {
+ *     return savedViews.startLoadingData(() => { setIsLoading(false); });
+ *   },
+ *   [],
+ * );
+ *
+ * if (isLoading) {
+ *   return <MyLoadingState />;
+ * }
+ *
+ * const handleOpenSavedView = async (savedViewId) => {
+ *   const savedViewData = await savedViews.lookupSavedViewData(savedViewId);
+ *   await applySavedView(iModel, viewport, savedViewData);
+ * };
+ *
+ * return <MySavedViewsWidget savedViews={savedViews} onOpenSavedView={handleOpenSavedView} />;
  */
-export declare function useSavedViews(args: UseSavedViewsParams): UseSavedViewsResult | undefined;
+export declare const useSavedViews: ((args: UseSavedViewsArgs) => UseSavedViewsResult) & {
+    /** Suggested initial state of custom Saved View stores. Immutable. */
+    emptyState: SavedViewsState;
+};
 export {};