@itwin/saved-views-react 0.5.0 → 0.7.0

package/lib/SavedViewsClient/SavedViewsClient.d.ts

@@ -1,75 +1,98 @@
-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 { SavedViewData, SavedViewGroup, SavedView, SavedViewTag } from "../SavedView.js";
 export interface SavedViewsClient {
-    getSavedViewInfo: (args: GetSavedViewInfoParams) => Promise<SavedViewInfo>;
-    getSingularSavedView: (args: GetSingularSavedViewParams) => Promise<SavedViewRepresentation>;
-    getThumbnailUrl: (args: GetThumbnailUrlParams) => Promise<string | undefined>;
-    uploadThumbnail: (args: UploadThumbnailParams) => Promise<void>;
-    createSavedView: (args: CreateSavedViewParams) => Promise<SavedView>;
-    updateSavedView: (args: UpdateSavedViewParams) => Promise<SavedView>;
-    deleteSavedView: (args: DeleteSavedViewParams) => Promise<void>;
-    createGroup: (args: CreateGroupParams) => Promise<SavedViewGroup>;
-    updateGroup: (args: UpdateGroupParams) => Promise<SavedViewGroup>;
-    deleteGroup: (args: DeleteGroupParams) => Promise<void>;
-    createTag: (args: CreateTagParams) => Promise<SavedViewTag>;
-    updateTag: (args: UpdateTagParams) => Promise<SavedViewTag>;
-    deleteTag: (args: DeleteTagParams) => Promise<void>;
-}
-export interface GetSavedViewInfoParams extends CommonParams {
+    getSavedViews: (args: GetSavedViewsArgs) => AsyncIterableIterator<SavedView[]>;
+    getGroups: (args: GetGroupsArgs) => Promise<SavedViewGroup[]>;
+    getTags: (args: GetTagsArgs) => Promise<SavedViewTag[]>;
+    getThumbnailUrl: (args: GetThumbnailUrlArgs) => Promise<string | undefined>;
+    uploadThumbnail: (args: UploadThumbnailArgs) => Promise<void>;
+    getSavedViewById: (args: GetSavedViewByIdArgs) => Promise<SavedView>;
+    getSavedViewDataById: (args: GetSavedViewDataByIdArgs) => Promise<SavedViewData>;
+    createSavedView: (args: CreateSavedViewArgs) => Promise<SavedView>;
+    updateSavedView: (args: UpdateSavedViewArgs) => Promise<SavedView>;
+    deleteSavedView: (args: DeleteSavedViewArgs) => Promise<void>;
+    createGroup: (args: CreateGroupArgs) => Promise<SavedViewGroup>;
+    updateGroup: (args: UpdateGroupArgs) => Promise<SavedViewGroup>;
+    deleteGroup: (args: DeleteGroupArgs) => Promise<void>;
+    createTag: (args: CreateTagArgs) => Promise<SavedViewTag>;
+    updateTag: (args: UpdateTagArgs) => Promise<SavedViewTag>;
+    deleteTag: (args: DeleteTagArgs) => Promise<void>;
+}
+export interface GetSavedViewsArgs extends CommonParams {
     iTwinId: string;
     iModelId?: string | undefined;
+    groupId?: string | undefined;
 }
-export interface GetSingularSavedViewParams extends CommonParams {
-    savedViewId: string;
+export interface GetGroupsArgs extends CommonParams {
+    iTwinId: string;
+    iModelId?: string | undefined;
 }
-export interface GetThumbnailUrlParams extends CommonParams {
+export interface GetTagsArgs extends CommonParams {
+    iTwinId: string;
+    iModelId?: string | undefined;
+}
+export interface GetThumbnailUrlArgs extends CommonParams {
     savedViewId: string;
 }
-export interface UploadThumbnailParams extends CommonParams {
+export interface UploadThumbnailArgs 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 CreateSavedViewParams extends CommonParams {
+export interface GetSavedViewByIdArgs extends CommonParams {
+    savedViewId: string;
+}
+export interface GetSavedViewDataByIdArgs extends CommonParams {
+    savedViewId: string;
+}
+export interface CreateSavedViewArgs extends CommonParams {
     iTwinId: string;
     iModelId?: string | undefined;
-    savedView: Pick<SavedView, "displayName" | "tagIds" | "groupId" | "shared">;
-    savedViewData: ViewData;
-    extensions?: ExtensionSavedViewCreate[] | undefined;
+    displayName: string;
+    groupId?: string | undefined;
+    tagIds?: string[] | undefined;
+    shared?: boolean | undefined;
+    savedViewData: SavedViewData;
 }
-export interface UpdateSavedViewParams extends CommonParams {
-    savedView: Pick<SavedView, "id"> & Partial<SavedView>;
-    savedViewData?: ViewData | undefined;
-    extensions?: ExtensionMin[] | undefined;
+export interface UpdateSavedViewArgs extends CommonParams {
+    savedViewId: string;
+    displayName?: string | undefined;
+    groupId?: string | undefined;
+    tagIds?: string[] | undefined;
+    shared?: boolean | undefined;
+    savedViewData?: SavedViewData | undefined;
 }
-export interface DeleteSavedViewParams extends CommonParams {
+export interface DeleteSavedViewArgs extends CommonParams {
     savedViewId: string;
 }
-export interface CreateGroupParams extends CommonParams {
+export interface CreateGroupArgs extends CommonParams {
     iTwinId: string;
     iModelId?: string | undefined;
-    group: Pick<SavedViewGroup, "displayName" | "shared">;
+    displayName: string;
+    shared?: boolean | undefined;
 }
-export interface UpdateGroupParams extends CommonParams {
-    group: Pick<SavedViewGroup, "id"> & Partial<SavedViewGroup>;
+export interface UpdateGroupArgs extends CommonParams {
+    groupId: string;
+    displayName?: string | undefined;
+    shared?: boolean | undefined;
 }
-export interface DeleteGroupParams extends CommonParams {
+export interface DeleteGroupArgs extends CommonParams {
     groupId: string;
 }
-export interface CreateTagParams extends CommonParams {
+export interface CreateTagArgs extends CommonParams {
     iTwinId: string;
     iModelId?: string;
     displayName: string;
 }
-export interface UpdateTagParams extends CommonParams {
-    tag: Pick<SavedViewTag, "id"> & Partial<SavedViewTag>;
+export interface UpdateTagArgs extends CommonParams {
+    tagId: string;
+    displayName?: string | undefined;
 }
-export interface DeleteTagParams extends CommonParams {
+export interface DeleteTagArgs extends CommonParams {
     tagId: string;
 }
 interface CommonParams {

package/lib/SavedViewsWidget/SavedViewGroupTile/SavedViewGroupTile.js

@@ -23,15 +23,14 @@ export function SavedViewGroupTile(props) {
     }, 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     []);
-    const dispatchOpenGroup = () => props.onOpen(props.group.id);
     const savedViewGroupTileContext = useMemo(() => ({ group: props.group, setEditingName }), [props.group]);
     return (_jsx(SavedViewGroupTileContextProvider, { value: savedViewGroupTileContext, children: _jsx("div", { ref: divRef, children: _jsx(Tile, { className: "svr-folder", variant: "folder", name: _jsx(EditableTileName, { displayName: props.group.displayName, editable: props.editable || editingName, editing: editingName, actions: {
                         onStartEditing: () => setEditingName(true),
                         onEndEditing: (newName) => {
                             setEditingName(false);
                             if (newName !== props.group.displayName) {
-                                props.onRename?.(props.group.id, newName);
+                                props.onRename?.(props.group.groupId, newName);
                             }
                         },
-                    } }), thumbnail: _jsx(SvgFolder, { className: "iui-thumbnail-icon" }), isActionable: !props.editable && !editingName, moreOptions: (props.options && props.options.length > 0) ? props.options : undefined, onClick: dispatchOpenGroup, children: _jsxs(Text, { isMuted: true, children: [props.numItems, " items"] }) }) }) }));
+                    } }), thumbnail: _jsx(SvgFolder, { className: "iui-thumbnail-icon" }), isActionable: !props.editable && !editingName, moreOptions: (props.options && props.options.length > 0) ? props.options : undefined, onClick: () => props.onOpen(props.group.groupId), children: _jsxs(Text, { isMuted: true, children: [props.numItems, " items"] }) }) }) }));
 }

package/lib/SavedViewsWidget/SavedViewGroupTile/SavedViewGroupTileContext.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="react" />
 import type { SavedViewGroup } from "../../SavedView.js";
 /** Context that's accessable within `<SavedViewGroupTile />` component. */
 export interface SavedViewGroupTileContext {

package/lib/SavedViewsWidget/SavedViewGroupTile/SavedViewGroupTileContext.js

@@ -14,7 +14,7 @@ export const SavedViewGroupTileContextProvider = savedViewGroupTileContext.Provi
 export function useSavedViewGroupTileContext() {
     const contextValue = useContext(savedViewGroupTileContext);
     return contextValue ?? {
-        group: { id: "SavedViewGroupTileContext_NoContext", displayName: "" },
+        group: { groupId: "SavedViewGroupTileContext_NoContext", displayName: "" },
         setEditingName: () => { },
     };
 }

package/lib/SavedViewsWidget/SavedViewsExpandableBlockWidget.d.ts

@@ -1,12 +1,13 @@
 import { type ReactElement, type ReactNode } from "react";
 import type { SavedView, SavedViewGroup, SavedViewTag } from "../SavedView.js";
-import type { SavedViewActions } from "../useSavedViews.js";
+import type { SavedViewsActions } from "../useSavedViews.js";
 import "./SavedViewsExpandableBlockWidget.css";
 interface SavedViewsExpandableBlockWidgetProps {
     savedViews: Map<string, SavedView>;
     groups: Map<string, SavedViewGroup>;
     tags: Map<string, SavedViewTag>;
-    actions?: Partial<SavedViewActions> | undefined;
+    thumbnails: Map<string, ReactNode>;
+    actions?: Partial<SavedViewsActions> | undefined;
     editable?: boolean | undefined;
     options?: ((savedView: SavedView) => (((close: () => void) => ReactElement[]) | ReactElement[])) | undefined;
 }
@@ -16,8 +17,9 @@ interface SavedViewsGroupProps {
     savedViews: Map<string, SavedView>;
     groups: Map<string, SavedViewGroup>;
     tags: Map<string, SavedViewTag>;
+    thumbnails: Map<string, ReactNode>;
     expanded?: boolean | undefined;
-    actions?: Partial<SavedViewActions> | undefined;
+    actions?: Partial<SavedViewsActions> | undefined;
     editable?: boolean | undefined;
     options?: ((savedView: SavedView) => (((close: () => void) => ReactElement[]) | ReactElement[])) | undefined;
 }

package/lib/SavedViewsWidget/SavedViewsExpandableBlockWidget.js

@@ -11,11 +11,11 @@ import { StickyExpandableBlock } from "../StickyExpandableBlock/StickyExpandable
 import { TileGrid } from "../TileGrid/TileGrid.js";
 import "./SavedViewsExpandableBlockWidget.css";
 export function SavedViewsExpandableBlockWidget(props) {
-    return (_jsxs("div", { className: "svr-saved-views-widget", children: [_jsx(SavedViewsGroup, { group: undefined, savedViews: props.savedViews, actions: props.actions, groups: props.groups, tags: props.tags, editable: props.editable, options: props.options, expanded: true }), [...props.groups.values()].map((group) => _jsx(SavedViewsGroup, { group: group, savedViews: props.savedViews, groups: props.groups, tags: props.tags, actions: props.actions, editable: props.editable, options: props.options }, group.id))] }));
+    return (_jsxs("div", { className: "svr-saved-views-widget", children: [_jsx(SavedViewsGroup, { group: undefined, savedViews: props.savedViews, actions: props.actions, groups: props.groups, tags: props.tags, thumbnails: props.thumbnails, editable: props.editable, options: props.options, expanded: true }), [...props.groups.values()].map((group) => _jsx(SavedViewsGroup, { group: group, savedViews: props.savedViews, groups: props.groups, tags: props.tags, thumbnails: props.thumbnails, actions: props.actions, editable: props.editable, options: props.options }, group.groupId))] }));
 }
 export function SavedViewsGroup(props) {
-    const savedViews = [...props.savedViews.values()].filter(({ groupId }) => groupId === props.group?.id);
-    return (_jsx(BorderlessExpandableBlock, { displayName: props.group?.displayName ?? "Ungrouped", numItems: savedViews.length, expanded: props.expanded, shared: props.group?.shared, editable: props.editable, children: _jsx(TileGrid, { gridItems: savedViews, children: (savedView) => (_jsx(SavedViewTile, { savedView: savedView, tags: props.tags, editable: props.editable, onRename: props.actions?.renameSavedView, options: props.options?.(savedView) }, savedView.id)) }) }));
+    const savedViews = [...props.savedViews.values()].filter(({ groupId }) => groupId === props.group?.groupId);
+    return (_jsx(BorderlessExpandableBlock, { displayName: props.group?.displayName ?? "Ungrouped", numItems: savedViews.length, expanded: props.expanded, shared: props.group?.shared, editable: props.editable, children: _jsx(TileGrid, { gridItems: savedViews, children: (savedView) => (_jsx(SavedViewTile, { savedView: savedView, thumbnail: props.thumbnails.get(savedView.savedViewId), tags: props.tags, editable: props.editable, onRename: props.actions?.renameSavedView, options: props.options?.(savedView) }, savedView.savedViewId)) }) }));
 }
 export function BorderlessExpandableBlock(props) {
     const handleEditGroupClick = (closeDropdown) => {

package/lib/SavedViewsWidget/SavedViewsFolderWidget.d.ts

@@ -1,11 +1,12 @@
-import { type ReactElement } from "react";
-import type { SavedView, SavedViewGroup, SavedViewTag } from "../SavedView.js";
-import type { SavedViewActions } from "../useSavedViews.js";
+import { type ReactElement, type ReactNode } from "react";
+import type { SavedViewGroup, SavedView, SavedViewTag } from "../SavedView.js";
+import type { SavedViewsActions } from "../useSavedViews.js";
 interface SavedViewsFolderWidgetProps {
     savedViews: Map<string, SavedView>;
     groups: Map<string, SavedViewGroup>;
     tags: Map<string, SavedViewTag>;
-    actions?: Partial<SavedViewActions> | undefined;
+    thumbnails: Map<string, ReactNode>;
+    actions?: Partial<SavedViewsActions> | undefined;
     editable?: boolean | undefined;
     options?: ((savedView: SavedView) => (((close: () => void) => ReactElement[]) | ReactElement[])) | undefined;
     onTileClick?: ((selectedViewId: string) => void) | undefined;

package/lib/SavedViewsWidget/SavedViewsFolderWidget.js

@@ -29,16 +29,16 @@ export function SavedViewsFolderWidget(props) {
     const handleGroupOpen = useCallback((activeGroupId) => setState({ activeGroupId, focusedGroupId: undefined }), []);
     const activeGroup = state.activeGroupId !== undefined && props.groups.get(state.activeGroupId);
     if (!activeGroup) {
-        return (_jsx(SavedViewsHomeScreen, { groupedSavedViews: groupedSavedViews, groups: props.groups, tags: props.tags, focusedGroupId: state.focusedGroupId, clearFocusedGroup: () => setState(({ activeGroupId }) => ({ activeGroupId, focusedGroupId: undefined })), onGroupOpen: handleGroupOpen, initialScrollTop: storedScrollOffset, storeScrollOffset: setStoredScrollOffset, actions: props.actions, editable: props.editable, savedViewOptions: props.options, onTileClick: props.onTileClick }));
+        return (_jsx(SavedViewsHomeScreen, { groupedSavedViews: groupedSavedViews, groups: props.groups, tags: props.tags, thumbnails: props.thumbnails, focusedGroupId: state.focusedGroupId, clearFocusedGroup: () => setState(({ activeGroupId }) => ({ activeGroupId, focusedGroupId: undefined })), onGroupOpen: handleGroupOpen, initialScrollTop: storedScrollOffset, storeScrollOffset: setStoredScrollOffset, actions: props.actions, editable: props.editable, savedViewOptions: props.options, onTileClick: props.onTileClick }));
     }
-    return (_jsx(SavedViewsGroupScreen, { activeGroup: activeGroup, groups: props.groups, tags: props.tags, savedViews: groupedSavedViews.get(activeGroup.id) ?? [], setActiveGroup: (activeGroupId) => setState({ activeGroupId, focusedGroupId: state.activeGroupId }), actions: props.actions, editable: props.editable, options: props.options, onTileClick: props.onTileClick }, activeGroup.id));
+    return (_jsx(SavedViewsGroupScreen, { activeGroup: activeGroup, groups: props.groups, tags: props.tags, thumbnails: props.thumbnails, savedViews: groupedSavedViews.get(activeGroup.groupId) ?? [], setActiveGroup: (activeGroupId) => setState({ activeGroupId, focusedGroupId: state.activeGroupId }), actions: props.actions, editable: props.editable, options: props.options, onTileClick: props.onTileClick }, activeGroup.groupId));
 }
 function SavedViewsHomeScreen(props) {
     const ungroupedSavedViews = props.groupedSavedViews.get(undefined) ?? [];
-    const groupTiles = useMemo(() => [...props.groups.values()].map((group) => _jsx(SavedViewGroupTile, { group: group, numItems: props.groupedSavedViews.get(group.id)?.length ?? 0, onOpen: props.onGroupOpen, focused: group.id === props.focusedGroupId, initialScrollTop: props.initialScrollTop, editable: props.editable, options: [
+    const groupTiles = useMemo(() => [...props.groups.values()].map((group) => _jsx(SavedViewGroupTile, { group: group, numItems: props.groupedSavedViews.get(group.groupId)?.length ?? 0, onOpen: props.onGroupOpen, focused: group.groupId === props.focusedGroupId, initialScrollTop: props.initialScrollTop, editable: props.editable, options: [
             _jsx(SavedViewGroupOptions.Rename, {}, "rename"),
-            _jsx(MenuItem, { onClick: () => props.actions?.deleteGroup?.(group.id), children: "Delete" }, "delete"),
-        ], onRename: props.actions?.renameGroup }, group.id)), [
+            _jsx(MenuItem, { onClick: () => props.actions?.deleteGroup?.(group.groupId), children: "Delete" }, "delete"),
+        ], onRename: props.actions?.renameGroup }, group.groupId)), [
         props.groups,
         props.groupedSavedViews,
         props.onGroupOpen,
@@ -47,7 +47,7 @@ function SavedViewsHomeScreen(props) {
         props.editable,
         props.actions,
     ]);
-    return (_jsxs("div", { className: "svr-saved-views-widget", style: { overflow: "auto" }, onScroll: (event) => props.storeScrollOffset(event.target.scrollTop), children: [_jsx(BorderlessExpandableBlock, { displayName: "Saved views", numItems: ungroupedSavedViews.length, expanded: true, children: _jsx(TileGrid, { gridItems: ungroupedSavedViews, children: (savedView) => _jsx(SavedViewTile, { savedView: savedView, tags: props.tags, editable: props.editable, onRename: props.actions?.renameSavedView, options: props.savedViewOptions?.(savedView), onClick: props.onTileClick }, savedView.id) }) }), _jsx(BorderlessExpandableBlock, { className: "svr-group-grid", displayName: "Groups", numItems: props.groups.size, expanded: true, onExpandToggle: (expanded) => !expanded && props.clearFocusedGroup?.(), editable: props.editable, children: _jsx("div", { className: "svr-tile-grid", children: groupTiles }) })] }));
+    return (_jsxs("div", { className: "svr-saved-views-widget", style: { overflow: "auto" }, onScroll: (event) => props.storeScrollOffset(event.target.scrollTop), children: [_jsx(BorderlessExpandableBlock, { displayName: "Saved views", numItems: ungroupedSavedViews.length, expanded: true, children: _jsx(TileGrid, { gridItems: ungroupedSavedViews, children: (savedView) => _jsx(SavedViewTile, { savedView: savedView, thumbnail: props.thumbnails.get(savedView.savedViewId), tags: props.tags, editable: props.editable, onRename: props.actions?.renameSavedView, options: props.savedViewOptions?.(savedView), onClick: props.onTileClick }, savedView.savedViewId) }) }), _jsx(BorderlessExpandableBlock, { className: "svr-group-grid", displayName: "Groups", numItems: props.groups.size, expanded: true, onExpandToggle: (expanded) => !expanded && props.clearFocusedGroup?.(), editable: props.editable, children: _jsx("div", { className: "svr-tile-grid", children: groupTiles }) })] }));
 }
 function SavedViewsGroupScreen(props) {
     const groups = useMemo(() => [...props.groups.values()], [props.groups]);
@@ -56,5 +56,5 @@ function SavedViewsGroupScreen(props) {
                     gap: "var(--iui-size-s)",
                     background: "var(--iui-color-background)",
                     padding: "var(--iui-size-s)",
-                }, children: [_jsx(Button, { styleType: "borderless", startIcon: _jsx(SvgChevronLeft, {}), onClick: () => props.setActiveGroup(undefined), children: "Back" }), _jsxs(Breadcrumbs, { children: [_jsx(IconButton, { styleType: "borderless", onClick: () => props.setActiveGroup(undefined), children: _jsx(SvgHome, {}) }), _jsx(DropdownButton, { styleType: "borderless", menuItems: (close) => groups.map((group) => _jsx(MenuItem, { onClick: () => { close(); props.setActiveGroup(group.id); }, children: group.displayName }, group.id)), children: props.activeGroup.displayName })] })] }), _jsx("div", { style: { overflow: "auto" }, children: _jsx(TileGrid, { gridItems: props.savedViews, children: (savedView) => (_jsx(SavedViewTile, { savedView: savedView, tags: props.tags, editable: props.editable, options: props.options?.(savedView), onClick: props.onTileClick }, savedView.id)) }) })] }));
+                }, children: [_jsx(Button, { styleType: "borderless", startIcon: _jsx(SvgChevronLeft, {}), onClick: () => props.setActiveGroup(undefined), children: "Back" }), _jsxs(Breadcrumbs, { children: [_jsx(IconButton, { styleType: "borderless", onClick: () => props.setActiveGroup(undefined), children: _jsx(SvgHome, {}) }), _jsx(DropdownButton, { styleType: "borderless", menuItems: (close) => groups.map((group) => _jsx(MenuItem, { onClick: () => { close(); props.setActiveGroup(group.groupId); }, children: group.displayName }, group.groupId)), children: props.activeGroup.displayName })] })] }), _jsx("div", { style: { overflow: "auto" }, children: _jsx(TileGrid, { gridItems: props.savedViews, children: (savedView) => (_jsx(SavedViewTile, { savedView: savedView, thumbnail: props.thumbnails.get(savedView.savedViewId), tags: props.tags, editable: props.editable, options: props.options?.(savedView), onClick: props.onTileClick }, savedView.savedViewId)) }) })] }));
 }

package/lib/applySavedView.d.ts

@@ -1,64 +1,69 @@
-import { ViewState, type IModelConnection, type Viewport } from "@itwin/core-frontend";
-import { type SavedViewRepresentation } from "@itwin/saved-views-client";
+import { ViewChangeOptions, ViewPose, ViewState, type IModelConnection, type Viewport } from "@itwin/core-frontend";
+import type { SavedViewData } 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"
+     * How to make use of captured {@link ViewState} data. The default behavior is
+     * to generate a new `ViewState` object out of {@linkcode SavedViewData.viewData}
+     * and apply it to viewport.
      *
-     * @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 and
-     * apply it to viewport.
+     * You can optionally provide a pre-made `ViewState` instance.
      *
-     * You can optionally provide a pre-made `ViewState` instance to conserve resources. It is usually obtained from
-     * {@link createViewState} result.
+     * @default "apply"
      *
      * @example
      * import { applySavedView, createViewState } from "@itwin/saved-views-react";
      *
-     * const viewState = await createViewState(iModel, savedView);
+     * const viewState = await createViewState(iModel, savedViewData);
      * await Promise.all([
      *   applySavedView(iModel, viewport1, savedView, { viewState }),
      *   applySavedView(iModel, viewport2, savedView, { viewState }),
      * ]);
      */
-    viewState?: Exclude<ApplyStrategy, "reset"> | ViewState | undefined;
+    viewState?: ApplyStrategy | ViewState | undefined;
+    /**
+     * How to handle camera pose in captured data.
+     * @default "apply"
+     */
+    camera?: ApplyStrategy | ViewPose | 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"`.
+     * How to handle element emphasis in captured data.
+     * @default "apply"
+     */
+    emphasis?: ApplyStrategy | "clear" | undefined;
+    /**
+     * How to handle captured {@link Viewport.perModelCategoryVisibility} data.
+     * @default "apply"
+     */
+    perModelCategoryVisibility?: ApplyStrategy | "clear" | undefined;
+    /**
+     * How to handle visibility of models and categories that exist in iModel but
+     * are not captured in Saved View data.
      * @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.
+     * Options forwarded to {@link Viewport.changeView}.
+     * @default undefined
      */
-    perModelCategoryVisibility?: ApplyStrategy | undefined;
+    viewChangeOptions?: ViewChangeOptions | 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
+ *   * `"apply"` – Apply captured Saved View state to viewport
+ *   * `"keep"` – Preserve current viewport state
  */
-type ApplyStrategy = "apply" | "reset" | "keep";
+type ApplyStrategy = "apply" | "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);
+ * const viewState = await createViewState(iModel, savedViewData);
  * await Promise.all([
- *   applySavedView(iModel, firstViewport, savedView, { viewState }),
- *   applySavedView(iModel, secondViewport, savedView, { viewState }),
+ *   applySavedView(iModel, viewport1, savedView, { viewState }),
+ *   applySavedView(iModel, viewport2, savedView, { viewState }),
  * ]);
  */
-export declare function applySavedView(iModel: IModelConnection, viewport: Viewport, savedView: Pick<SavedViewRepresentation, "savedViewData" | "extensions">, settings?: ApplySavedViewSettings | undefined): Promise<void>;
+export declare function applySavedView(iModel: IModelConnection, viewport: Viewport, savedViewData: SavedViewData, settings?: ApplySavedViewSettings | undefined): Promise<void>;
 export {};

package/lib/applySavedView.js

@@ -2,7 +2,7 @@
 * 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 { ViewPose, ViewState } from "@itwin/core-frontend";
 import { createViewState } from "./createViewState.js";
 import { extensionHandlers } from "./translation/SavedViewsExtensionHandlers.js";
 /**
@@ -11,37 +11,72 @@ import { extensionHandlers } from "./translation/SavedViewsExtensionHandlers.js"
  * @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);
+ * const viewState = await createViewState(iModel, savedViewData);
  * await Promise.all([
- *   applySavedView(iModel, firstViewport, savedView, { viewState }),
- *   applySavedView(iModel, secondViewport, savedView, { viewState }),
+ *   applySavedView(iModel, viewport1, savedView, { viewState }),
+ *   applySavedView(iModel, viewport2, savedView, { viewState }),
  * ]);
  */
-export async function applySavedView(iModel, viewport, savedView, settings = {}) {
-    const defaultStrategy = settings.all ?? "apply";
-    if ((settings.viewState ?? defaultStrategy) !== "keep") {
-        if (settings.viewState instanceof ViewState) {
-            viewport.changeView(settings.viewState);
+export async function applySavedView(iModel, viewport, savedViewData, settings = {}) {
+    if (settings.viewState !== "keep") {
+        // We use "hidden" as the default value for modelAndCategoryVisibilityFallback
+        // because users expect modelSelector.enabled and categorySelector.enabled to
+        // act as exclusive whitelists when modelSelector.disabled or categorySelector.disabled
+        // arrays are empty, respectively.
+        const { modelAndCategoryVisibilityFallback = "hidden" } = settings;
+        const viewState = settings.viewState instanceof ViewState
+            ? settings.viewState
+            : await createViewState(iModel, savedViewData.viewData, { modelAndCategoryVisibilityFallback });
+        if (settings.camera instanceof ViewPose) {
+            viewState.applyPose(settings.camera);
         }
-        else {
-            const { modelAndCategoryVisibilityFallback } = settings;
-            const viewState = await createViewState(iModel, savedView.savedViewData, { modelAndCategoryVisibilityFallback });
-            viewport.changeView(viewState);
+        else if (settings.camera === "keep") {
+            viewState.applyPose(viewport.view.savePose());
         }
+        viewport.changeView(viewState, settings.viewChangeOptions);
     }
-    const extensions = new Map(savedView.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);
-            }
+    const extensions = findKnownExtensions(savedViewData.extensions ?? []);
+    if (extensions.emphasis) {
+        if (settings.emphasis !== "keep") {
+            extensionHandlers.emphasizeElements.reset(viewport);
+        }
+        if (settings.emphasis === "apply") {
+            extensionHandlers.emphasizeElements.apply(extensions.emphasis, viewport);
+        }
+    }
+    if (extensions.perModelCategoryVisibility) {
+        if (settings.perModelCategoryVisibility !== "keep") {
+            extensionHandlers.perModelCategoryVisibility.reset(viewport);
         }
+        if (settings.perModelCategoryVisibility === "apply") {
+            extensionHandlers.perModelCategoryVisibility.apply(extensions.perModelCategoryVisibility, viewport);
+        }
+    }
+}
+/** Finds first occurences of known extensions. */
+function findKnownExtensions(extensions) {
+    const result = {
+        emphasis: undefined,
+        perModelCategoryVisibility: undefined,
     };
-    processExtension(extensionHandlers.emphasizeElements, settings.emphasis);
-    processExtension(extensionHandlers.perModelCategoryVisibility, settings.perModelCategoryVisibility);
+    for (const extension of extensions) {
+        if (result.emphasis === undefined &&
+            extension.extensionName === extensionHandlers.emphasizeElements.extensionName) {
+            result.emphasis = extension.data;
+            if (result.perModelCategoryVisibility) {
+                break;
+            }
+        }
+        if (result.perModelCategoryVisibility === undefined &&
+            extension.extensionName === extensionHandlers.perModelCategoryVisibility.extensionName) {
+            result.perModelCategoryVisibility = extension.data;
+            if (result.emphasis) {
+                break;
+            }
+        }
+        if (result.emphasis && result.perModelCategoryVisibility) {
+            break;
+        }
+    }
+    return result;
 }

package/lib/captureSavedViewData.d.ts

@@ -1,11 +1,37 @@
 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 { IModelConnection, Viewport } from "@itwin/core-frontend";
+import type { SavedViewData } from "./SavedView.js";
 interface CaptureSavedViewDataArgs {
     /** Viewport to capture. */
     viewport: Viewport;
+    /**
+     * Whether function will skip capturing element emphasis state.
+     * @default false
+     */
+    omitEmphasis?: boolean | undefined;
+    /**
+     * Whether function will skip capturing `viewport.perModelCategoryVisibility` state.
+     * @default false
+     */
+    omitPerModelCategoryVisibility?: boolean | undefined;
 }
-export declare function captureSavedViewData(args: CaptureSavedViewDataArgs): Promise<ViewData>;
-export declare function getMissingModels(iModel: IModelConnection, knownModels: Set<string>): Promise<string[]>;
-export declare function getMissingCategories(iModel: IModelConnection, knownCategories: Set<string>): Promise<Id64Array>;
+/**
+ * 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 = captureMyCustomViewportState(viewport);
+ *   const thumbnail = captureSavedViewThumbnail(viewport);
+ *   return { thumbnail, viewData, extensions: extensions.concat(myExtensions) };
+ * }
+ */
+export declare function captureSavedViewData(args: CaptureSavedViewDataArgs): Promise<SavedViewData>;
+export declare function queryMissingModels(iModel: IModelConnection, knownModels: Set<string>): Promise<string[]>;
+export declare function queryAllSpatiallyLocatedModels(iModel: IModelConnection): Promise<string[]>;
+export declare function queryMissingCategories(iModel: IModelConnection, knownCategories: Set<string>): Promise<Id64Array>;
+export declare function queryAllCategories(iModel: IModelConnection): Promise<string[]>;
 export {};