@itwin/saved-views-react 0.4.1 → 0.6.0

package/README.md

@@ -2,10 +2,59 @@
 
 ## About
 
-A collection of React components for building applications that deal with [Saved Views](https://developer.bentley.com/apis/savedviews/overview/).
+A collection of utilities and React components for building iTwin applications that deal with [Saved Views](https://developer.bentley.com/apis/savedviews/overview/).
 
 ## Documentation
 
+### [captureSavedViewData](./src/captureSavedViewData.ts)
+
+Captures current viewport state into serializable format. The returned data can later be used to restore viewport's view.
+
+```ts
+const { viewData, extensions = [] } = await captureSavedViewData({ viewport });
+extensions.push(myCustomExtension(viewport));
+console.log({ viewData, extensions }); /*
+{
+  viewData: { itwin3dView: {...} },
+  extensions: {
+    { extensionName: "EmphasizeElements", data: "{...}" },
+    { extensionName: "MyCustomExtension", data: "my_custom_extension_data" },
+  }
+} */
+```
+
+### [captureSavedViewThumbnail](./src/captureSavedViewThumbnail.ts)
+
+Generates Saved View thumbnail based on what is currently displayed on the viewport.
+
+```ts
+const thumbnail = captureSavedViewThumbnail(viewport);
+console.log(thumbnail); // "data:image/png;base64,iVBORw0KGoAAAANSUhEUg..."
+```
+
+### [applySavedView](./src/applySavedView.ts)
+
+Updates viewport state to match captured Saved View.
+
+```ts
+// Capture viewport state
+const savedViewData = await captureSavedViewData({ viewport });
+// Restore viewport state
+await applySavedView(iModel, viewport, savedViewData);
+```
+
+### [createViewState](./src/createViewState.ts)
+
+Creates ViewState object out of Saved View data. It provides a lower-level access to view data for advanced use.
+
+```ts
+const viewState = await createViewState(iModel, savedViewData.viewData);
+await applySavedView(iModel, viewport, savedViewData, { viewState });
+
+// The two lines above are equivalent to
+await applySavedView(iModel, viewport, savedViewData);
+```
+
 ### React components
 
 * [SavedViewTile](./src/SavedViewTile/SavedViewTile.tsx)
@@ -42,7 +91,7 @@ export function SavedViewsWidget(props) {
 }
 ```
 
-### useSavedViews
+### [useSavedViews](./src/useSavedViews.tsx)
 
 [useSavedViews](./src/useSavedViews.tsx) React hook provides basic functionality to jump-start your Saved Views widget. It accepts [`ITwinSavedViewsClient`](./src/SavedViewsClient/ITwinSavedViewsClient.ts) which is used to pull Saved View data and synchronize it back to the [Saved Views service](https://developer.bentley.com/apis/savedviews/overview/).
 

package/lib/SavedView.d.ts

@@ -1,18 +1,39 @@
+import type { ViewData } from "@itwin/saved-views-client";
 import type { ReactNode } from "react";
 export interface SavedView {
     id: string;
     displayName: string;
+    viewData?: ViewData | undefined;
     groupId?: string | undefined;
     creatorId?: string | undefined;
     tagIds?: string[] | undefined;
     shared?: boolean | undefined;
     thumbnail?: ReactNode | string | undefined;
-    /** `extensionName` and `data` pairs. */
-    extensions?: Map<string, string> | undefined;
+    extensions?: SavedViewExtension[] | undefined;
     /** Time the saved view was created as an ISO8601 string, `"YYYY-MM-DDTHH:mm:ss.sssZ"` */
-    creationTime?: string;
+    creationTime?: string | undefined;
     /** Time the saved view was last modified as an ISO8601 string, `"YYYY-MM-DDTHH:mm:ss.sssZ"` */
-    lastModified?: string;
+    lastModified?: string | undefined;
+}
+export interface SavedViewExtension {
+    /** Extension identifier. Saved View cannot contain multiple extensions that share the same `extensionName`. */
+    extensionName: string;
+    /**
+     * Serialized extension data.
+     *
+     * @example
+     * const extension = {
+     *   // Unique identifier makes extension data format portable between applications because it avoids collision
+     *   // with different implementations
+     *   extensionName: "CustomHighlight_$5be36494-ae03-4400-bb80-24ffd9db2a87",
+     *   data: JSON.stringify({
+     *     description: "For illustrative purposes only. We do not provide implementation for this extensionName."
+     *     highlightColor: "#f05599",
+     *     models: ["0x20000000006"],
+     *   }),
+     * };
+     */
+    data: string;
 }
 export interface SavedViewTag {
     id: string;
@@ -24,3 +45,4 @@ export interface SavedViewGroup {
     creatorId?: string | undefined;
     shared?: boolean | undefined;
 }
+export type WriteableSavedViewProperties = Omit<SavedView, "id" | "creatorId" | "creationTime" | "lastModified">;

package/lib/SavedViewTile/SavedViewTile.js

@@ -3,7 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 * Copyright (c) Bentley Systems, Incorporated. All rights reserved.
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
-import { SvgEdit, SvgImageFrame, SvgMore, SvgShare, SvgTag } from "@itwin/itwinui-icons-react";
+import { SvgEdit, SvgMore, SvgSavedView, SvgShare, SvgTag } from "@itwin/itwinui-icons-react";
 import { Button, IconButton, Input, Text, Tile } from "@itwin/itwinui-react";
 import { useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { LayeredDropdownMenu } from "../LayeredDropdownMenu/LayeredDropdownMenu.js";
@@ -67,7 +67,7 @@ export function SavedViewTile(props) {
                             ? _jsx(Tile.ThumbnailPicture, { url: props.savedView.thumbnail })
                             : props.savedView.thumbnail
                                 ? props.savedView.thumbnail
-                                : _jsx(Tile.ThumbnailPicture, { children: _jsx(SvgImageFrame, {}) }), _jsx(TileIconContainer, { style: { placeSelf: "start" }, icons: props.leftIcons }), _jsx(TileIconContainer, { style: { placeSelf: "start end" }, icons: rightIcons })] }), _jsxs(Tile.ContentArea, { children: [_jsx(Tile.Metadata, { children: metadata }), (typeof props.options === "function" || (props.options && props.options.length > 0)) &&
+                                : _jsx(Tile.ThumbnailPicture, { children: _jsx(SvgSavedView, {}) }), _jsx(TileIconContainer, { style: { placeSelf: "start" }, icons: props.leftIcons }), _jsx(TileIconContainer, { style: { placeSelf: "start end" }, icons: rightIcons })] }), _jsxs(Tile.ContentArea, { children: [_jsx(Tile.Metadata, { children: metadata }), (typeof props.options === "function" || (props.options && props.options.length > 0)) &&
                             _jsx("div", { className: "svr-tile--more-options", onClick: (ev) => ev.stopPropagation(), children: _jsx(LayeredDropdownMenu, { menuItems: props.options, children: _jsx(IconButton, { size: "small", styleType: "borderless", children: _jsx(SvgMore, {}) }) }) })] })] }) }));
 }
 function isOverflowing(element) {

package/lib/SavedViewsClient/ITwinSavedViewsClient.d.ts

@@ -1,23 +1,23 @@
-import { type SavedViewRepresentation } from "@itwin/saved-views-client";
 import type { SavedView, SavedViewGroup, SavedViewTag } from "../SavedView.js";
-import type { CreateGroupParams, CreateSavedViewParams, CreateTagParams, DeleteGroupParams, DeleteSavedViewParams, DeleteTagParams, GetSavedViewInfoParams, GetSingularSavedViewParams, GetThumbnailUrlParams, SavedViewInfo, SavedViewsClient, UpdateGroupParams, UpdateSavedViewParams, UpdateTagParams, UploadThumbnailParams } from "./SavedViewsClient.js";
+import type { CreateGroupParams, CreateSavedViewParams, CreateTagParams, DeleteGroupParams, DeleteSavedViewParams, DeleteTagParams, GetAllGroupsParams, GetAllSavedViewsParams, GetAllTagsParams, GetSavedViewParams, GetThumbnailUrlParams, SavedViewsClient, UpdateGroupParams, UpdateSavedViewParams, UpdateTagParams, UploadThumbnailParams } from "./SavedViewsClient.js";
 interface ITwinSavedViewsClientParams {
-    /** @default "https://api.bentley.com/savedviews"  */
-    getAccessToken: () => Promise<string>;
     /**
      * Authorization token that grants access to iTwin Saved Views API. The token should be valid for `savedviews:read`
      * and `savedviews:modify` OIDC scopes.
-     */
+    */
+    getAccessToken: () => Promise<string>;
+    /** @default "https://api.bentley.com/savedviews"  */
     baseUrl?: string | undefined;
 }
-/**  */
 export declare class ITwinSavedViewsClient implements SavedViewsClient {
-    private client;
+    #private;
     constructor(args: ITwinSavedViewsClientParams);
-    getSavedViewInfo(args: GetSavedViewInfoParams): Promise<SavedViewInfo>;
-    getSingularSavedView(args: GetSingularSavedViewParams): Promise<SavedViewRepresentation>;
+    getAllSavedViews(args: GetAllSavedViewsParams): AsyncIterableIterator<SavedView[]>;
+    getAllGroups(args: GetAllGroupsParams): Promise<SavedViewGroup[]>;
+    getAllTags(args: GetAllTagsParams): Promise<SavedViewTag[]>;
     getThumbnailUrl(args: GetThumbnailUrlParams): Promise<string | undefined>;
     uploadThumbnail(args: UploadThumbnailParams): Promise<void>;
+    getSavedView(args: GetSavedViewParams): Promise<SavedView>;
     createSavedView(args: CreateSavedViewParams): Promise<SavedView>;
     updateSavedView(args: UpdateSavedViewParams): Promise<SavedView>;
     deleteSavedView(args: DeleteSavedViewParams): Promise<void>;

package/lib/SavedViewsClient/ITwinSavedViewsClient.js

@@ -3,33 +3,39 @@
 * See LICENSE.md in the project root for license terms and full copyright notice.
 *--------------------------------------------------------------------------------------------*/
 import { ITwinSavedViewsClient as Client, } from "@itwin/saved-views-client";
-/**  */
 export class ITwinSavedViewsClient {
-    client;
+    #client;
     constructor(args) {
-        this.client = new Client(args);
-    }
-    async getSavedViewInfo(args) {
-        const [{ savedViews }, { groups }, { tags }] = await Promise.all([
-            this.client.getAllSavedViewsMinimal(args),
-            this.client.getAllGroups(args),
-            this.client.getAllTags(args),
-        ]);
-        return {
-            savedViews: savedViews.map(savedViewResponseToSavedView),
-            groups: groups.map(groupResponseToSavedViewGroup),
-            tags: tags.map(tagResponseToSavedViewTag),
-        };
-    }
-    async getSingularSavedView(args) {
-        const response = await this.client.getSavedViewRepresentation({
-            savedViewId: args.savedViewId,
+        this.#client = new Client(args);
+    }
+    async *getAllSavedViews(args) {
+        const iterable = this.#client.getAllSavedViewsRepresentation({
+            iTwinId: args.iTwinId,
+            iModelId: args.iModelId,
+            signal: args.signal,
+        });
+        for await (const page of iterable) {
+            yield page.savedViews.map(savedViewResponseToSavedView);
+        }
+    }
+    async getAllGroups(args) {
+        const response = await this.#client.getAllGroups({
+            iTwinId: args.iTwinId,
+            iModelId: args.iModelId,
             signal: args.signal,
         });
-        return response.savedView;
+        return response.groups.map(groupResponseToSavedViewGroup);
+    }
+    async getAllTags(args) {
+        const response = await this.#client.getAllTags({
+            iTwinId: args.iTwinId,
+            iModelId: args.iModelId,
+            signal: args.signal,
+        });
+        return response.tags.map(tagResponseToSavedViewTag);
     }
     async getThumbnailUrl(args) {
-        const response = await this.client.getImage({
+        const response = await this.#client.getImage({
             savedViewId: args.savedViewId,
             size: "thumbnail",
             signal: args.signal,
@@ -37,43 +43,55 @@ export class ITwinSavedViewsClient {
         return response.href;
     }
     async uploadThumbnail(args) {
-        await this.client.updateImage({
+        await this.#client.updateImage({
             savedViewId: args.savedViewId,
             image: args.image,
             signal: args.signal,
         });
     }
+    async getSavedView(args) {
+        const response = await this.#client.getSavedViewRepresentation({
+            savedViewId: args.savedViewId,
+            signal: args.signal,
+        });
+        return savedViewResponseToSavedView(response.savedView);
+    }
     async createSavedView(args) {
-        const { savedView } = await this.client.createSavedView({
+        const { savedView } = await this.#client.createSavedView({
             iTwinId: args.iTwinId,
             iModelId: args.iModelId,
             displayName: args.savedView.displayName,
             tagIds: args.savedView.tagIds,
             groupId: args.savedView.groupId,
             shared: args.savedView.shared,
-            savedViewData: args.savedViewData,
+            savedViewData: args.savedView.viewData,
+            extensions: args.savedView.extensions,
             signal: args.signal,
         });
         return savedViewResponseToSavedView(savedView);
     }
     async updateSavedView(args) {
-        const { savedView } = await this.client.updateSavedView({
+        const { savedView } = await this.#client.updateSavedView({
             savedViewId: args.savedView.id,
             displayName: args.savedView.displayName,
             tagIds: args.savedView.tagIds,
             groupId: args.savedView.groupId,
             shared: args.savedView.shared,
-            savedViewData: args.savedViewData,
-            extensions: args.extensions,
+            savedViewData: args.savedView.viewData,
             signal: args.signal,
         });
+        await Promise.all((args.savedView.extensions ?? []).map(({ extensionName, data }) => this.#client.createExtension({
+            savedViewId: args.savedView.id,
+            extensionName,
+            data,
+        })));
         return savedViewResponseToSavedView(savedView);
     }
     async deleteSavedView(args) {
-        await this.client.deleteSavedView({ savedViewId: args.savedViewId, signal: args.signal });
+        await this.#client.deleteSavedView({ savedViewId: args.savedViewId, signal: args.signal });
     }
     async createGroup(args) {
-        const { group } = await this.client.createGroup({
+        const { group } = await this.#client.createGroup({
             iTwinId: args.iTwinId,
             iModelId: args.iModelId,
             displayName: args.group.displayName,
@@ -82,7 +100,7 @@ export class ITwinSavedViewsClient {
         return groupResponseToSavedViewGroup(group);
     }
     async updateGroup(args) {
-        const { group } = await this.client.updateGroup({
+        const { group } = await this.#client.updateGroup({
             groupId: args.group.id,
             displayName: args.group.displayName,
             shared: args.group.shared,
@@ -91,12 +109,14 @@ export class ITwinSavedViewsClient {
         return groupResponseToSavedViewGroup(group);
     }
     async deleteGroup(args) {
-        const savedViews = await this.client.getAllSavedViewsMinimal({ groupId: args.groupId, signal: args.signal });
-        await Promise.all(savedViews.savedViews.map(({ id }) => this.client.deleteSavedView({ savedViewId: id, signal: args.signal })));
-        await this.client.deleteGroup({ groupId: args.groupId, signal: args.signal });
+        const savedViewPages = this.#client.getAllSavedViewsMinimal({ groupId: args.groupId, signal: args.signal });
+        for await (const savedViews of savedViewPages) {
+            await Promise.all(savedViews.savedViews.map(({ id }) => this.#client.deleteSavedView({ savedViewId: id, signal: args.signal })));
+        }
+        await this.#client.deleteGroup({ groupId: args.groupId, signal: args.signal });
     }
     async createTag(args) {
-        const { tag } = await this.client.createTag({
+        const { tag } = await this.#client.createTag({
             iTwinId: args.iTwinId,
             iModelId: args.iModelId,
             displayName: args.displayName,
@@ -105,7 +125,7 @@ export class ITwinSavedViewsClient {
         return tagResponseToSavedViewTag(tag);
     }
     async updateTag(args) {
-        const { tag } = await this.client.updateTag({
+        const { tag } = await this.#client.updateTag({
             tagId: args.tag.id,
             displayName: args.tag.displayName,
             signal: args.signal,
@@ -113,18 +133,20 @@ export class ITwinSavedViewsClient {
         return tagResponseToSavedViewTag(tag);
     }
     async deleteTag(args) {
-        await this.client.deleteTag({ tagId: args.tagId, signal: args.signal });
+        await this.#client.deleteTag({ tagId: args.tagId, signal: args.signal });
     }
 }
 function savedViewResponseToSavedView(response) {
     return {
         id: response.id,
         displayName: response.displayName,
+        viewData: response.savedViewData,
         tagIds: response.tags?.map((tag) => tag.id),
         groupId: response._links.group?.href.split("/").at(-1),
         creatorId: response._links.creator?.href.split("/").at(-1),
         shared: response.shared,
         thumbnail: undefined,
+        extensions: response.extensions,
         creationTime: response.creationTime,
         lastModified: response.lastModified,
     };

package/lib/SavedViewsClient/SavedViewsClient.d.ts

@@ -1,15 +1,12 @@
-import type { ExtensionMin, ExtensionSavedViewCreate, SavedViewRepresentation, ViewData } from "@itwin/saved-views-client";
-import type { SavedView, SavedViewGroup, SavedViewTag } from "../SavedView.js";
-export interface SavedViewInfo {
-    savedViews: SavedView[];
-    groups: SavedViewGroup[];
-    tags: SavedViewTag[];
-}
+import type { SavedView, SavedViewGroup, SavedViewTag, WriteableSavedViewProperties } from "../SavedView.js";
+import type { PartialExcept } from "../utils.js";
 export interface SavedViewsClient {
-    getSavedViewInfo: (args: GetSavedViewInfoParams) => Promise<SavedViewInfo>;
-    getSingularSavedView: (args: GetSingularSavedViewParams) => Promise<SavedViewRepresentation>;
+    getAllSavedViews: (args: GetAllSavedViewsParams) => AsyncIterableIterator<SavedView[]>;
+    getAllGroups: (args: GetAllGroupsParams) => Promise<SavedViewGroup[]>;
+    getAllTags: (args: GetAllTagsParams) => Promise<SavedViewTag[]>;
     getThumbnailUrl: (args: GetThumbnailUrlParams) => Promise<string | undefined>;
     uploadThumbnail: (args: UploadThumbnailParams) => Promise<void>;
+    getSavedView: (args: GetSavedViewParams) => Promise<SavedView>;
     createSavedView: (args: CreateSavedViewParams) => Promise<SavedView>;
     updateSavedView: (args: UpdateSavedViewParams) => Promise<SavedView>;
     deleteSavedView: (args: DeleteSavedViewParams) => Promise<void>;
@@ -20,32 +17,43 @@ export interface SavedViewsClient {
     updateTag: (args: UpdateTagParams) => Promise<SavedViewTag>;
     deleteTag: (args: DeleteTagParams) => Promise<void>;
 }
-export interface GetSavedViewInfoParams extends CommonParams {
+export interface GetAllSavedViewsParams extends CommonParams {
     iTwinId: string;
     iModelId?: string | undefined;
 }
-export interface GetSingularSavedViewParams extends CommonParams {
-    savedViewId: string;
+export interface GetAllGroupsParams extends CommonParams {
+    iTwinId: string;
+    iModelId?: string | undefined;
+}
+export interface GetAllTagsParams extends CommonParams {
+    iTwinId: string;
+    iModelId?: string | undefined;
 }
 export interface GetThumbnailUrlParams extends CommonParams {
     savedViewId: string;
 }
 export interface UploadThumbnailParams extends CommonParams {
     savedViewId: string;
-    /** Image data encoded as base64 data URL. */
+    /**
+     * Image data encoded as base64 data URL.
+     *
+     * @example
+     * "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVQYV2NgYAAAAAMAAWgmWQ0AAAAASUVORK5CYII="
+     */
     image: string;
 }
+export interface GetSavedViewParams extends CommonParams {
+    savedViewId: string;
+}
 export interface CreateSavedViewParams extends CommonParams {
     iTwinId: string;
     iModelId?: string | undefined;
-    savedView: Pick<SavedView, "displayName" | "tagIds" | "groupId" | "shared">;
-    savedViewData: ViewData;
-    extensions?: ExtensionSavedViewCreate[] | undefined;
+    savedView: PartialExcept<WriteableSavedViewProperties, "displayName" | "viewData">;
 }
 export interface UpdateSavedViewParams extends CommonParams {
-    savedView: Pick<SavedView, "id"> & Partial<SavedView>;
-    savedViewData?: ViewData | undefined;
-    extensions?: ExtensionMin[] | undefined;
+    savedView: Partial<WriteableSavedViewProperties> & {
+        id: string;
+    };
 }
 export interface DeleteSavedViewParams extends CommonParams {
     savedViewId: string;

package/lib/applySavedView.d.ts

@@ -0,0 +1,67 @@
+import { ViewState, type IModelConnection, type Viewport } from "@itwin/core-frontend";
+import type { SavedView } from "./SavedView.js";
+export interface ApplySavedViewSettings {
+    /**
+     * Strategy to use when other setting does not specify one. By default, viewport is reset to default state and then
+     * all captured Saved View data is applied on top.
+     * @default "apply"
+     *
+     * @example
+     * await applySavedView(iModel, viewport, savedView, { all: "keep", viewState: "apply" });
+     */
+    all?: ApplyStrategy | undefined;
+    /**
+     * How to handle captured {@link ViewState} data. The default behavior is to generate a new `ViewState` object out of
+     * {@linkcode SavedView.viewData} and apply it to viewport.
+     *
+     * You can optionally provide a pre-made `ViewState` instance to conserve resources. It is usually obtained from
+     * {@link createViewState} result.
+     *
+     * @example
+     * import { applySavedView, createViewState } from "@itwin/saved-views-react";
+     *
+     * const viewState = await createViewState(iModel, savedView);
+     * await Promise.all([
+     *   applySavedView(iModel, viewport1, savedView, { viewState }),
+     *   applySavedView(iModel, viewport2, savedView, { viewState }),
+     * ]);
+     *
+     * @remarks
+     * When neither `SavedView.viewData` nor `ViewState` is provided, current {@linkcode Viewport.view} is preserved.
+     */
+    viewState?: ApplyStrategy | ViewState | undefined;
+    /**
+     * How to handle visibility of models and categories that exist in iModel but are not captured in Saved View data. Has
+     * effect only when `modelAndCategoryVisibility` strategy is set to `"apply"`.
+     * @default "hidden"
+     */
+    modelAndCategoryVisibilityFallback?: "visible" | "hidden" | undefined;
+    /** How to handle captured element emphasis data. In default state emphasis is turned off. */
+    emphasis?: ApplyStrategy | undefined;
+    /**
+     * How to handle captured {@link Viewport.perModelCategoryVisibility} data. In default state no overrides are present.
+     */
+    perModelCategoryVisibility?: ApplyStrategy | undefined;
+}
+/**
+ * Controls how viewport state is going to be altered.
+ *
+ * * `"apply"` – Apply captured Saved View state. Falls back to `"reset"` on failure (e.g. missing Saved View data).
+ * * `"reset"` – Reset to the default viewport state
+ * * `"keep"` – Keep the current viewport state
+ */
+type ApplyStrategy = "apply" | "reset" | "keep";
+/**
+ * Updates {@linkcode viewport} state to match captured Saved View.
+ *
+ * @example
+ * // Optionally, you can create and manage ViewState object yourself to avoid redundant work,
+ * // e.g. when applying the same Saved View to multiple viewports
+ * const viewState = await createViewState(iModel, savedView);
+ * await Promise.all([
+ *   applySavedView(iModel, viewport1, savedView, { viewState }),
+ *   applySavedView(iModel, viewport2, savedView, { viewState }),
+ * ]);
+ */
+export declare function applySavedView(iModel: IModelConnection, viewport: Viewport, savedViewData: Pick<SavedView, "viewData" | "extensions">, settings?: ApplySavedViewSettings | undefined): Promise<void>;
+export {};

package/lib/applySavedView.js

@@ -0,0 +1,47 @@
+/*---------------------------------------------------------------------------------------------
+* Copyright (c) Bentley Systems, Incorporated. All rights reserved.
+* See LICENSE.md in the project root for license terms and full copyright notice.
+*--------------------------------------------------------------------------------------------*/
+import { ViewState } from "@itwin/core-frontend";
+import { createViewState } from "./createViewState.js";
+import { extensionHandlers } from "./translation/SavedViewsExtensionHandlers.js";
+/**
+ * Updates {@linkcode viewport} state to match captured Saved View.
+ *
+ * @example
+ * // Optionally, you can create and manage ViewState object yourself to avoid redundant work,
+ * // e.g. when applying the same Saved View to multiple viewports
+ * const viewState = await createViewState(iModel, savedView);
+ * await Promise.all([
+ *   applySavedView(iModel, viewport1, savedView, { viewState }),
+ *   applySavedView(iModel, viewport2, savedView, { viewState }),
+ * ]);
+ */
+export async function applySavedView(iModel, viewport, savedViewData, settings = {}) {
+    const defaultStrategy = settings.all ?? "apply";
+    if ((settings.viewState ?? defaultStrategy) !== "keep") {
+        if (settings.viewState instanceof ViewState) {
+            viewport.changeView(settings.viewState);
+        }
+        else if (savedViewData.viewData) {
+            const { modelAndCategoryVisibilityFallback } = settings;
+            const viewState = await createViewState(iModel, savedViewData.viewData, { modelAndCategoryVisibilityFallback });
+            viewport.changeView(viewState);
+        }
+    }
+    const extensions = new Map(savedViewData.extensions?.map(({ extensionName, data }) => [extensionName, data]));
+    const processExtension = (extensionHandler, strategy = defaultStrategy) => {
+        if (strategy === "keep") {
+            return;
+        }
+        extensionHandler.reset(viewport);
+        if (strategy === "apply") {
+            const extensionData = extensions.get(extensionHandler.extensionName);
+            if (extensionData) {
+                extensionHandler.apply(extensionData, viewport);
+            }
+        }
+    };
+    processExtension(extensionHandlers.emphasizeElements, settings.emphasis);
+    processExtension(extensionHandlers.perModelCategoryVisibility, settings.perModelCategoryVisibility);
+}

package/lib/captureSavedViewData.d.ts

@@ -1,16 +1,41 @@
 import { Id64Array } from "@itwin/core-bentley";
 import { type IModelConnection, type Viewport } from "@itwin/core-frontend";
 import { type ViewData } from "@itwin/saved-views-client";
+import type { SavedViewExtension } from "./SavedView.js";
 interface CaptureSavedViewDataArgs {
-    /** Viewport to capture the view from. */
+    /** Viewport to capture. */
     viewport: Viewport;
     /**
-     * Collect a list of models and categories that are currently not enabled in the {@linkcode viewport}.
-     * @default true
+     * Whether to skip capturing data for `"EmphasizeElements"` extension.
+     * @default false
      */
-    captureHiddenModelsAndCategories?: boolean | undefined;
+    omitEmphasis?: boolean | undefined;
+    /**
+     * Whether to skip capturing data for `"PerModelCategoryVisibility"` extension.
+     * @default false
+     */
+    omitPerModelCategoryVisibility?: boolean | undefined;
+}
+interface CaptureSavedViewDataResult {
+    viewData: ViewData;
+    /** Value is `undefined` when no extension data is captured. */
+    extensions: SavedViewExtension[] | undefined;
 }
-export declare function captureSavedViewData(args: CaptureSavedViewDataArgs): Promise<ViewData>;
+/**
+ * Captures current {@link Viewport} state into serializable format. The returned data can later be used to restore
+ * viewport's view.
+ *
+ * @example
+ * import { captureSavedViewData, captureSavedViewThumbnail } from "@itwin/saved-views-react";
+ *
+ * async function saveViewport(viewport) {
+ *   const { viewData, extensions = [] } = await captureSavedViewData({ viewport });
+ *   const myExtensions = captureMyCustomState(viewport);
+ *   const thumbnail = captureSavedViewThumbnail(viewport);
+ *   return { thumbnail, viewData, extensions: extensions.concat(myExtensions) };
+ * }
+ */
+export declare function captureSavedViewData(args: CaptureSavedViewDataArgs): Promise<CaptureSavedViewDataResult>;
 export declare function getMissingModels(iModel: IModelConnection, knownModels: Set<string>): Promise<string[]>;
 export declare function getMissingCategories(iModel: IModelConnection, knownCategories: Set<string>): Promise<Id64Array>;
 export {};

package/lib/captureSavedViewData.js

@@ -1,24 +1,45 @@
 import { QueryRowFormat } from "@itwin/core-common";
+import { extensionHandlers } from "./translation/SavedViewsExtensionHandlers.js";
 import { extractClipVectorsFromLegacy } from "./translation/clipVectorsLegacyExtractor.js";
 import { extractDisplayStyle2dFromLegacy, extractDisplayStyle3dFromLegacy, } from "./translation/displayStyleExtractor.js";
+/**
+ * Captures current {@link Viewport} state into serializable format. The returned data can later be used to restore
+ * viewport's view.
+ *
+ * @example
+ * import { captureSavedViewData, captureSavedViewThumbnail } from "@itwin/saved-views-react";
+ *
+ * async function saveViewport(viewport) {
+ *   const { viewData, extensions = [] } = await captureSavedViewData({ viewport });
+ *   const myExtensions = captureMyCustomState(viewport);
+ *   const thumbnail = captureSavedViewThumbnail(viewport);
+ *   return { thumbnail, viewData, extensions: extensions.concat(myExtensions) };
+ * }
+ */
 export async function captureSavedViewData(args) {
-    const { captureHiddenModelsAndCategories = true } = args;
-    const hiddenCategoriesPromise = captureHiddenModelsAndCategories
-        ? getMissingCategories(args.viewport.iModel, new Set(args.viewport.view.categorySelector.toJSON().categories))
-        : undefined;
-    if (args.viewport.view.isSpatialView()) {
+    return {
+        viewData: await createSavedViewVariant(args.viewport),
+        extensions: [extensionHandlers.emphasizeElements, extensionHandlers.perModelCategoryVisibility]
+            .map((extension) => ({
+            extensionName: extension.extensionName,
+            data: extension.capture(args.viewport),
+        }))
+            .filter(({ data }) => data !== undefined),
+    };
+}
+async function createSavedViewVariant(viewport) {
+    const hiddenCategoriesPromise = getMissingCategories(viewport.iModel, new Set(viewport.view.categorySelector.toJSON().categories));
+    if (viewport.view.isSpatialView()) {
         const [hiddenCategories, hiddenModels] = await Promise.all([
             hiddenCategoriesPromise,
-            captureHiddenModelsAndCategories
-                ? getMissingModels(args.viewport.iModel, new Set(args.viewport.view.modelSelector.toJSON().models))
-                : undefined,
+            getMissingModels(viewport.iModel, new Set(viewport.view.modelSelector.toJSON().models)),
         ]);
-        return createSpatialSavedViewObject(args.viewport, hiddenCategories, hiddenModels);
+        return createSpatialSavedViewObject(viewport, hiddenCategories, hiddenModels);
     }
-    if (args.viewport.view.isDrawingView()) {
-        return createDrawingSavedViewObject(args.viewport, await hiddenCategoriesPromise);
+    if (viewport.view.isDrawingView()) {
+        return createDrawingSavedViewObject(viewport, await hiddenCategoriesPromise);
     }
-    return createSheetSavedViewObject(args.viewport, await hiddenCategoriesPromise);
+    return createSheetSavedViewObject(viewport, await hiddenCategoriesPromise);
 }
 function createSpatialSavedViewObject(vp, hiddenCategories, hiddenModels) {
     const viewState = vp.view;