@itwin/core-common 4.7.0-dev.0 → 4.7.0-dev.3

package/lib/cjs/ViewProps.js.map

@@ -1 +1 @@
-{"version":3,"file":"ViewProps.js","sourceRoot":"","sources":["../../src/ViewProps.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAgPH;;;GAGG;AACH,IAAiB,YAAY,CA0W5B;AA1WD,WAAiB,YAAY;IAE3B;;;;OAIG;IACU,oBAAO,GAAG,OAAgB,CAAC;IAkCxC,qGAAqG;IACxF,0BAAa,GAAG,CAAC,EAAiB,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;AAgUnF,CAAC,EA1WgB,YAAY,4BAAZ,YAAY,QA0W5B","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Views\n */\n\nimport { CompressedId64Set, Id64Array, Id64String } from \"@itwin/core-bentley\";\nimport { AngleProps, Range3dProps, TransformProps, XYProps, XYZProps, YawPitchRollProps } from \"@itwin/core-geometry\";\nimport { CameraProps } from \"./Camera\";\nimport { DisplayStyleProps, DisplayStyleSettingsProps } from \"./DisplayStyleSettings\";\nimport { DefinitionElementProps, DisplayStyleLoadProps, ElementProps, RenderTimelineProps, SheetProps, ViewAttachmentProps } from \"./ElementProps\";\nimport { EntityQueryParams } from \"./EntityProps\";\nimport { ModelProps } from \"./ModelProps\";\nimport { SubCategoryAppearance } from \"./SubCategoryAppearance\";\nimport { ViewDetails3dProps, ViewDetailsProps } from \"./ViewDetails\";\nimport { ThumbnailProps } from \"./Thumbnail\";\nimport { RenderSchedule } from \"./RenderSchedule\";\n\n/** The id of either an element or an entry in a ViewStore.\n * @public\n */\nexport type ViewIdString = Id64String; // should also include ViewStoreRpc.IdString when that's @public\n\n/** As part of a [[ViewStateProps]], describes the [[SpatialViewDefinition]] from which a [SectionDrawing]($backend) was generated.\n * @see [[SectionDrawingProps]]\n * @public\n * @extensions\n */\nexport interface SectionDrawingViewProps {\n  /** The Id of the spatial view from which the SectionDrawing was generated. */\n  spatialView: Id64String;\n  /** If true, the spatial view should be displayed in the context of the drawing view. */\n  displaySpatialView: boolean;\n  /** Transform from drawing coordinates to spatial coordinates. If undefined, use identity transform. */\n  drawingToSpatialTransform?: TransformProps;\n}\n\n/** The response props from the getCustomViewState3dData RPC endpoint\n * @internal\n */\nexport interface CustomViewState3dProps {\n  modelIds: CompressedId64Set;\n  modelExtents: Range3dProps;\n  categoryIds: CompressedId64Set;\n}\n\n/**\n * The options passed to the getCustomViewState3dData RPC endpoint.\n * @internal\n */\nexport interface CustomViewState3dCreatorOptions {\n  modelIds?: CompressedId64Set;\n}\n\n/**\n * A result row from querying for subcategories\n * @internal\n */\nexport interface SubCategoryResultRow {\n  parentId: Id64String;\n  id: Id64String;\n  appearance: SubCategoryAppearance.Props;\n}\n\n/**\n * Request props for the hydrateViewState RPC endpoint.\n * @internal\n */\nexport interface HydrateViewStateRequestProps {\n  acsId?: string;\n  notLoadedModelSelectorStateModels?: CompressedId64Set;\n  /** @deprecated in 3.x. If loading categoryIds is necessary, see [IModelConnection.SubCategoriesCache.load]($frontend)*/\n  notLoadedCategoryIds?: CompressedId64Set;\n  sheetViewAttachmentIds?: CompressedId64Set;\n  viewStateLoadProps?: ViewStateLoadProps;\n  baseModelId?: Id64String;\n  spatialViewId?: Id64String;\n}\n\n/** Response props from the hydrateViewState RPC endpoint.\n * @internal\n */\nexport interface HydrateViewStateResponseProps {\n  acsElementProps?: ElementProps;\n  modelSelectorStateModels?: ModelProps[];\n  // cast this to viewAttachmentInfo[] on the frontend.\n  sheetViewAttachmentProps?: ViewAttachmentProps[];\n  sheetViewViews?: (ViewStateProps | undefined)[];\n  baseModelProps?: ModelProps;\n  spatialViewProps?: ViewStateProps;\n  /** @deprecated in 3.x. If loading categoryIds is necessary, see [IModelConnection.SubCategoriesCache.load]($frontend)*/\n  categoryIdsResult?: SubCategoryResultRow[];\n}\n\n/** Returned from [IModelDb.Views.getViewStateData]($backend).\n * @public\n * @extensions\n */\nexport interface ViewStateProps {\n  viewDefinitionProps: ViewDefinitionProps;\n  categorySelectorProps: CategorySelectorProps;\n  modelSelectorProps?: ModelSelectorProps;\n  displayStyleProps: DisplayStyleProps;\n  /** Sheet-specific properties, if this is a view of a [SheetModel]($backend). */\n  sheetProps?: SheetProps;\n  /** The Ids of the [ViewAttachment]($backend)s contained within the [SheetModel]($backend), if this is a sheet view. */\n  sheetAttachments?: Id64Array;\n  /** For a [DrawingViewState]($frontend), the extents of the [DrawingModel]($backend), used for determining the upper limits of the view's extents. */\n  modelExtents?: Range3dProps;\n  /** Information about the [SectionDrawing]($backend) relevant to displaying a drawing view. */\n  sectionDrawing?: SectionDrawingViewProps;\n}\n\n/** Options for loading a [[ViewStateProps]] via [IModelConnection.Views.load]($frontend) or [IModelDb.Views.getViewStateData]($backend).\n * @public\n * @extensions\n */\nexport interface ViewStateLoadProps {\n  /** Options for loading the view's [[DisplayStyleProps]]. */\n  displayStyle?: DisplayStyleLoadProps;\n\n  /**\n   * bindings for query-based selectors\n   * @beta\n   */\n  queryBindings?: {\n    modelSelector?: ViewStoreRpc.QueryBindings;\n    categorySelector?: ViewStoreRpc.QueryBindings;\n  };\n}\n\n/** Properties that define a ModelSelector\n * @public\n * @extensions\n */\nexport interface ModelSelectorProps extends DefinitionElementProps {\n  models: Id64Array;\n}\n\n/** Properties that define a CategorySelector\n * @public\n * @extensions\n */\nexport interface CategorySelectorProps extends DefinitionElementProps {\n  categories: Id64Array;\n}\n\n/** Parameters for performing a query on [ViewDefinition]($backend) classes.\n * @public\n * @extensions\n */\nexport interface ViewQueryParams extends EntityQueryParams {\n  wantPrivate?: boolean;\n}\n\n/** Parameters used to construct a ViewDefinition\n * @public\n * @extensions\n */\nexport interface ViewDefinitionProps extends DefinitionElementProps {\n  categorySelectorId: ViewIdString;\n  displayStyleId: ViewIdString;\n  description?: string;\n  jsonProperties?: {\n    /** Additional properties of the view. */\n    viewDetails?: ViewDetailsProps;\n  };\n}\n\n/** Parameters to construct a ViewDefinition3d\n * @public\n * @extensions\n */\nexport interface ViewDefinition3dProps extends ViewDefinitionProps {\n  /** if true, camera is valid. */\n  cameraOn: boolean;\n  /** The lower left back corner of the view frustum. */\n  origin: XYZProps;\n  /** The extent of the view frustum. */\n  extents: XYZProps;\n  /** Rotation of the view frustum (could be undefined if going Matrix3d -> YawPitchRoll). */\n  angles?: YawPitchRollProps;\n  /** The camera used for this view. */\n  camera: CameraProps;\n  jsonProperties?: {\n    /** Additional properties of the view. */\n    viewDetails?: ViewDetails3dProps;\n  };\n}\n\n/** Parameters to construct a SpatialViewDefinition\n * @public\n * @extensions\n */\nexport interface SpatialViewDefinitionProps extends ViewDefinition3dProps {\n  modelSelectorId: ViewIdString;\n}\n\n/** Parameters used to construct a ViewDefinition2d\n * @public\n * @extensions\n */\nexport interface ViewDefinition2dProps extends ViewDefinitionProps {\n  baseModelId: Id64String;\n  origin: XYProps;\n  delta: XYProps;\n  angle: AngleProps;\n}\n\n/**\n * @public\n * @extensions\n */\nexport interface AuxCoordSystemProps extends ElementProps {\n  type?: number;\n  description?: string;\n}\n\n/**  Properties of AuxCoordSystem2d\n * @public\n * @extensions\n */\nexport interface AuxCoordSystem2dProps extends AuxCoordSystemProps {\n  /** Origin of the AuxCoordSystem2d */\n  origin?: XYProps;\n  /** Rotation angle */\n  angle?: AngleProps;\n}\n\n/** Properties of AuxCoordSystem3d\n * @public\n * @extensions\n */\nexport interface AuxCoordSystem3dProps extends AuxCoordSystemProps {\n  /** Origin of the AuxCoordSystem3d */\n  origin?: XYZProps;\n  /** Yaw angle */\n  yaw?: AngleProps;\n  /** Pitch angle */\n  pitch?: AngleProps;\n  /** Roll angle */\n  roll?: AngleProps;\n}\n\n/**\n * Access to a ViewStore from the frontend.\n * @beta\n */\nexport namespace ViewStoreRpc {\n\n  /**\n   * Version of the Rpc interface. If any methods or interfaces of this API change, this number should\n   * be incremented according to the rules of semantic versioning. See .\\rpc\\README-RpcInterfaceVersioning.md for more information.\n   *  @internal\n   */\n  export const version = \"4.0.0\" as const;\n\n  /** an Id of a View, DisplayStyle, ModelSelector, CategorySelector, or Timeline in a ViewStore.\n   * Will be a base-36 number with a leading \"@\".\n   * @public\n   */\n  export type IdString = string;\n\n  /**\n   * A string identifying a group. This may either be a \"group name path\" or the RowString of a group (e.g. either \"group1/design/issues\" or \"@4e3\")\n   * The syntax is not ambiguous because ViewStoreIdStrings always start with \"@\" and  Group names can never contain \"@\".\n   */\n  export type ViewGroupSpec = IdString | ViewGroupPath;\n\n  /** The name for a view. */\n  export type ViewName = string;\n\n  /** The name for a Tag. */\n  export type TagName = string;\n\n  /** The name of an \"owner\". Should come from the authentication system, so it will be guaranteed unique.\n   * This name should be chosen by the user rather than their email address.\n   */\n  export type OwnerName = string;\n\n  /** The path name of a view group (e.g. \"group1/design/issues\"). Does not include the \"root\" group. */\n  export type ViewGroupPath = string;\n\n  /** The name for a view group.  */\n  export type ViewGroupName = string;\n\n  /** The name for a view group.  */\n  export type ClassFullName = string;\n\n  /** Determine if a string is an Id of an entry in a ViewStore (base-36 integer with a leading \"@\") */\n  export const isViewStoreId = (id?: ViewIdString) => true === id?.startsWith(\"@\");\n\n  /** Parameters for querying for views in a ViewStore. */\n  export interface QueryParams {\n    /** a list of classFullNames to accept. If not present, all classes are returned. */\n    readonly classNames?: ClassFullName[];\n    /** Optional \"LIMIT\" clause to limit the number of views returned. */\n    readonly limit?: number;\n    /** Optional \"OFFSET\" clause. Only valid if Limit is also present. */\n    readonly offset?: number;\n    /** A string to filter view names. May include wildcards if the `nameCompare` uses LIKE or GLOB (see SQLite documentation for LIKE and GLOB). */\n    readonly nameSearch?: string;\n    /** The comparison operator for `nameSearch`. Default is `=` */\n    readonly nameCompare?: \"GLOB\" | \"LIKE\" | \"NOT GLOB\" | \"NOT LIKE\" | \"=\" | \"<\" | \">\";\n    /* the Id of the view group to query. If not present, the root group is used. There is no way to query for views from multiple view groups in one request. */\n    readonly group?: IdString;\n    /** A list of tags to filter views. If present, only views that have one or more of the tags will be returned. */\n    readonly tags?: TagName[];\n    /* The name of an owner for private views. If present, private views owned by the owner will also be returned. Shared views are always returned. */\n    readonly owner?: OwnerName;\n  }\n\n  /** Parameters for specifying a Query to select Categories or Models. */\n  export interface SelectorQuery {\n    /**\n     * The full ClassName from which to select. If this SelectorQuery is for Categories, this must be or derive from \"BisCore:Category\".\n     * If this SelectorQuery is for Models, this must be or derive from \"BisCore:Model\".\n     */\n    from: ClassFullName;\n    /** If true, only return instances of `from`. Otherwise, return instances of `from` and any subclasses of `from`. */\n    only?: boolean;\n    /**\n     * filter for query. If present, only instances of `from` that satisfy the filter will be returned.\n     * If not supplied, all instances of `from` are returned.\n     * @note\n     * This value is used into the ECQuery:`SELECT ECInstanceId FROM ${query.from} WHERE ${query.where}`.\n     */\n    where?: string;\n    /** List of Model or Category ids to add to the query results.\n     * @note This is only valid if there is a `where` clause. Otherwise all instances of `from` will be returned so there is no value in adding ids.\n    */\n    adds?: Id64Array | CompressedId64Set;\n    /** List of Model or Category Ids to remove from the query results. */\n    removes?: Id64Array | CompressedId64Set;\n  }\n\n  /** A Model or Category selector may either be a query or a list of Ids. */\n  export type SelectorProps = { query: SelectorQuery, ids?: never } | { query?: never, ids: Id64Array | CompressedId64Set };\n\n  /** Information about a View in a ViewStore. */\n  export interface ViewInfo {\n    /** The Id of the view. */\n    id: IdString;\n    /** The name of the view. */\n    name?: ViewName;\n    /** The name of the owner of the view. */\n    owner?: OwnerName;\n    /** The className of the view. */\n    className: ClassFullName;\n    /** The Id of the view group containing the view. */\n    groupId: IdString;\n    /** If true, the view is private (unshared) and will only be returned by queries that specify the owner's name. */\n    isPrivate: boolean;\n    /** The Id of a ModelSelector, if the view has one. */\n    modelSelectorId?: IdString;\n    /** The Id of the CategorySelector for this view. */\n    categorySelectorId: IdString;\n    /** The Id of a DisplayStyle for the view. */\n    displayStyleId: IdString;\n    /** a list of tags for the view. */\n    tags?: TagName[];\n  }\n\n  /** Information about a ViewGroup in a ViewStore. */\n  export interface ViewGroupInfo {\n    /** The Id of this view group. */\n    id: IdString;\n    /** The name of this view group. */\n    name: ViewGroupName;\n    /** The Id of the parent of this view group. If undefined, this is the root group. */\n    parent?: IdString;\n    /** The Id of the default view for this view group. */\n    defaultView?: IdString;\n  }\n\n  /** Arguments for adding a new view to a ViewStore. */\n  export interface AddViewArgs {\n    /** the properties of the ViewDefinition for the new view. */\n    readonly viewDefinition: ViewDefinitionProps;\n\n    /**\n     * The properties of a category selector for the new view.\n     * @note This value is only used, and should only be present if `viewDefinition.categorySelectorId` **not** a valid\n     * `IdString`. In that case, a new category selector will be created with these properties and its Id will be used.\n     * Otherwise, the categorySelectorId from the ViewDefinition is used. If it does not represent a valid category\n     * selector, an error is thrown.\n     */\n    readonly categorySelectorProps?: CategorySelectorProps;\n\n    /** The properties of a model selector for the new view.\n     * @note This value is only used, and should only be present if `viewDefinition.modelSelectorId` **not** a valid\n     * `IdString`. In that case, a new model selector will be created with these properties and its Id will be used.\n     * Otherwise, the modelSelectorId from the ViewDefinition is used. If it does not represent a valid model selector,\n     * an error is thrown.\n     */\n    readonly modelSelectorProps?: ModelSelectorProps;\n\n    /** The properties of a display style for the new view.\n     * @note This value is only used, and should only be present if `viewDefinition.displayStyleId` **not** a valid\n     * `IdString`. In that case, a new display style will be created with these properties and its Id will be used.\n     * Otherwise, the displayStyleId from the ViewDefinition is used. If it does not represent a valid display style, an\n     * error is thrown.\n     */\n    readonly displayStyleProps?: DisplayStyleProps;\n\n    /* the owner of the view. Must be present if isPrivate is true. */\n    readonly owner?: OwnerName;\n\n    /* the Id of the view group for the view. If not present, the view is added to the root group. */\n    readonly group?: IdString;\n\n    /* if true, the view is private (unshared). */\n    readonly isPrivate?: boolean;\n\n    /* an optional list of tags for the view. */\n    readonly tags?: TagName[];\n\n    /** optional thumbnail for the view. */\n    readonly thumbnail?: ThumbnailProps;\n  }\n\n  /** Argument for finding a category selector, model selector, display style, or timeline by name or Id. */\n  export type NameOrId = { name: string, id?: never } | { id: IdString, name?: never };\n\n  /** Bindings for parameterized values in where clause of SelectorQuery\n   * @see[[ECSqlStatement.bindValues]]\n   */\n  export interface QueryBindings {\n    bindings?: any[] | object;\n  }\n\n  /**\n   * Methods for reading from a ViewStore via Rpc from a frontend via `IModelConnection.views.viewsStoreReader`. These\n   * methods use the *current* ViewStore for the iModel, and attempt to load the default ViewStore if no ViewStore is\n   * currently loaded. They will throw exceptions if the request cannot be fulfilled.\n   * @note The user's accessToken is validated against the ViewStore for every request. For each of these methods, the\n   * user only needs read permission to the ViewStore.\n   */\n  export interface Reader {\n    /** Find all views owned by the supplied owner name. */\n    findViewsByOwner(args: { owner: OwnerName }): Promise<ViewInfo[]>;\n\n    /** Get a category selector by Id. Throws if it does not exist. */\n    getCategorySelector(args: NameOrId & QueryBindings): Promise<CategorySelectorProps>;\n\n    /** Get a display style by Id. Throws if it does not exist. */\n    getDisplayStyle(args: NameOrId & { opts?: DisplayStyleLoadProps }): Promise<DisplayStyleProps>;\n\n    /** Get a model selector by Id. Throws if it does not exist. */\n    getModelSelector(args: NameOrId & QueryBindings): Promise<ModelSelectorProps>;\n\n    /** Get a thumbnail for a view. */\n    getThumbnail(args: { viewId: IdString }): Promise<ThumbnailProps | undefined>;\n\n    /** Get a render timeline by Id. Throws if it does not exist. */\n    getTimeline(args: NameOrId): Promise<RenderTimelineProps>;\n\n    /** Get a view by name. The name can include the *view group path*, if no `groupId` is supplied. */\n    getViewByName(arg: { name: ViewName, groupId?: IdString }): Promise<ViewInfo | undefined>;\n\n    /** Get a view definition by viewId. Throws if it does not exist. */\n    getViewDefinition(args: { viewId: IdString }): Promise<ViewDefinitionProps>;\n\n    /** get the properties of a ViewGroup by id. This will include the defaultViewId, if one exists. */\n    getViewGroupInfo(args: { groupId?: IdString }): Promise<ViewGroupInfo | undefined>;\n\n    /** Get a list of ViewGroups that are children of the supplied parent. If no parent is supplied, the root group is used.\n     * Each entry in the list includes the id and name of the ViewGroup.\n     */\n    getViewGroups(args: { parent?: ViewGroupSpec }): Promise<{ id: IdString, name: string }[]>;\n\n    /** Get the ViewInfo for a view by Id. Returns undefined if the view does not exist. */\n    getViewInfo(args: { viewId: IdString }): Promise<ViewInfo | undefined>;\n\n    /** Query for a list of ViewInfos for views that match the supplied [[QueryParams]].\n     * @note The array will be sorted by name, ascending. To limit the size of the array, supply `limit` and `offset` in the QueryParams.\n     */\n    queryViews(queryParams: QueryParams): Promise<ViewInfo[]>;\n  }\n\n  /**\n   * Methods for writing to a ViewStore via Rpc from a frontend via `IModelConnection.views.viewsStoreWriter`. These\n   * methods use the *current* ViewStore for the iModel, and attempt to load the default ViewStore if no ViewStore is\n   * currently loaded. They will throw exceptions if the request cannot be fulfilled.\n   * @note The user's accessToken is validated against the ViewStore for every request. For each of these methods, the\n   * user must have write permission to the ViewStore.\n   */\n  export interface Writer {\n    /**\n     * Add a category selector to a ViewStore.\n     * @returns The IdString of the new category selector.\n     */\n    addCategorySelector(args: { name?: string, selector: SelectorProps, owner?: OwnerName }): Promise<IdString>;\n\n    /** Add a display style to a ViewStore.\n     * @returns The IdString of the new display style.\n     */\n    addDisplayStyle(args: { name?: string, className: string, settings: DisplayStyleSettingsProps, owner?: OwnerName }): Promise<IdString>;\n\n    /**\n     *  Add a model selector to a ViewStore.\n     * @returns The IdString of the new model selector.\n     */\n    addModelSelector(args: { name?: string, selector: SelectorProps, owner?: OwnerName }): Promise<IdString>;\n\n    /**\n     * Add a thumbnail for a view. If the view already has a thumbnail, it is replaced.\n     * If a view is deleted, its thumbnail is also deleted.\n     * @note The thumbnail must be a valid image in PNG or JPEG format.\n     */\n    addOrReplaceThumbnail(args: { viewId: IdString, thumbnail: ThumbnailProps }): Promise<void>;\n\n    /** Add tags to a view. If the view already has tags, the new tags are appended to the existing tags. */\n    addTagsToView(args: { viewId: IdString, tags: TagName[] }): Promise<void>;\n\n    /** Add a render timeline to a ViewStore.\n     * @returns The IdString of the new timeline.\n     */\n    addTimeline(args: { name?: string, timeline: RenderSchedule.ScriptProps, owner?: OwnerName }): Promise<IdString>;\n\n    /** Add a view to a ViewStore. If no group is supplied, the new view is added to the root view group.\n     * @returns The IdString of the new view\n     */\n    addView(args: AddViewArgs): Promise<IdString>;\n\n    /** Add a view group to a ViewStore. If no parent is supplied, the new group is added to the root view group.\n     * @returns the IdString of new view group\n     */\n    addViewGroup(args: { name: string, parentId?: IdString, owner?: OwnerName }): Promise<IdString>;\n\n    /** Change the default view for a view group. If no group is supplied, this changes the default view for the root view group. */\n    changeDefaultViewId(args: { defaultView: IdString, group?: ViewGroupSpec }): Promise<void>;\n\n    /** Delete the thumbnail for a view. */\n    deleteThumbnail(args: { viewId: IdString }): Promise<void>;\n\n    /**\n     * Delete a view from a ViewStore. If this is the default view for a view group, it cannot be deleted until another\n     * view is set as the default.\n     * @note If this view references a category selector, model selector, or display style that is not referenced by any\n     * other view, *and do not have a name*, they will each also be deleted. If the view has a thumbnail, it is also\n     * deleted.\n     */\n    deleteView(args: { viewId: IdString }): Promise<void>;\n\n    /** Delete a view group from a ViewStore. This will also delete all views in the group. */\n    deleteViewGroup(args: { name: ViewGroupSpec }): Promise<void>;\n\n    /** Delete a display style from a ViewStore. If the display style is referenced by any view, it cannot be deleted\n     * and an exception will be thrown.\n     */\n    deleteDisplayStyle(args: { id: IdString }): Promise<void>;\n\n    /** Delete a model selector from a ViewStore. If the model selector is referenced by any view, it cannot be deleted\n     * and an exception will be thrown. */\n    deleteModelSelector(args: { id: IdString }): Promise<void>;\n\n    /** Delete a category selector from a ViewStore. If the category selector is referenced by any view, it cannot be\n     * deleted and an exception will be thrown.\n     */\n    deleteCategorySelector(args: { id: IdString }): Promise<void>;\n\n    /** Delete a render timeline from a ViewStore. */\n    deleteTimeline(args: { id: IdString }): Promise<void>;\n\n    /** Delete a tag. This removes it from all views where it was used. */\n    deleteTag(args: { name: TagName }): Promise<void>;\n\n    /** remove a tag from a view. */\n    removeTagFromView(args: { viewId: IdString, tag: TagName }): Promise<void>;\n\n    /** Update the properties of a category selector. */\n    updateCategorySelector(args: NameOrId & { selector: SelectorProps }): Promise<void>;\n\n    /** Update the properties of a display style. */\n    updateDisplayStyle(args: NameOrId & { className: string, settings: DisplayStyleSettingsProps }): Promise<void>;\n\n    /** Update the properties of a model selector. */\n    updateModelSelector(args: NameOrId & { selector: SelectorProps }): Promise<void>;\n\n    /** Update the properties of a render timeline. */\n    updateTimeline(args: NameOrId & { timeline: RenderSchedule.ScriptProps }): Promise<void>;\n\n    /** Update the properties of a view definition. */\n    updateViewDefinition(args: { viewId: IdString, viewDefinition: ViewDefinitionProps }): Promise<void>;\n\n    /** Change a view from shared to private, or vice versa. If changing to private, the owner must be supplied. */\n    updateViewShared(arg: { viewId: IdString, isShared: boolean, owner?: string }): Promise<void>;\n\n    /** Set the name of a category selector. */\n    renameCategorySelector(args: { id: IdString, name?: string }): Promise<void>;\n\n    /** Set the name of a display style. */\n    renameDisplayStyle(args: { id: IdString, name?: string }): Promise<void>;\n\n    /** Set the name of a model selector. */\n    renameModelSelector(args: { id: IdString, name?: string }): Promise<void>;\n\n    /** Set the name of a render timeline. */\n    renameTimeline(args: { id: IdString, name?: string }): Promise<void>;\n\n    /** Set the name of a view. */\n    renameView(args: { viewId: IdString, name: string }): Promise<void>;\n\n    /** Set the name of a view group. */\n    renameViewGroup(args: { groupId: IdString, name: string }): Promise<void>;\n\n    /** rename an existing tag. */\n    renameTag(args: { oldName: TagName, newName: TagName }): Promise<void>;\n  }\n}\n"]}
+{"version":3,"file":"ViewProps.js","sourceRoot":"","sources":["../../src/ViewProps.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAgPH;;;GAGG;AACH,IAAiB,YAAY,CA0W5B;AA1WD,WAAiB,YAAY;IAE3B;;;;OAIG;IACU,oBAAO,GAAG,OAAgB,CAAC;IAkCxC,qGAAqG;IACxF,0BAAa,GAAG,CAAC,EAAiB,EAAE,EAAE,CAAC,IAAI,KAAK,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;AAgUnF,CAAC,EA1WgB,YAAY,4BAAZ,YAAY,QA0W5B","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Views\r\n */\r\n\r\nimport { CompressedId64Set, Id64Array, Id64String } from \"@itwin/core-bentley\";\r\nimport { AngleProps, Range3dProps, TransformProps, XYProps, XYZProps, YawPitchRollProps } from \"@itwin/core-geometry\";\r\nimport { CameraProps } from \"./Camera\";\r\nimport { DisplayStyleProps, DisplayStyleSettingsProps } from \"./DisplayStyleSettings\";\r\nimport { DefinitionElementProps, DisplayStyleLoadProps, ElementProps, RenderTimelineProps, SheetProps, ViewAttachmentProps } from \"./ElementProps\";\r\nimport { EntityQueryParams } from \"./EntityProps\";\r\nimport { ModelProps } from \"./ModelProps\";\r\nimport { SubCategoryAppearance } from \"./SubCategoryAppearance\";\r\nimport { ViewDetails3dProps, ViewDetailsProps } from \"./ViewDetails\";\r\nimport { ThumbnailProps } from \"./Thumbnail\";\r\nimport { RenderSchedule } from \"./RenderSchedule\";\r\n\r\n/** The id of either an element or an entry in a ViewStore.\r\n * @public\r\n */\r\nexport type ViewIdString = Id64String; // should also include ViewStoreRpc.IdString when that's @public\r\n\r\n/** As part of a [[ViewStateProps]], describes the [[SpatialViewDefinition]] from which a [SectionDrawing]($backend) was generated.\r\n * @see [[SectionDrawingProps]]\r\n * @public\r\n * @extensions\r\n */\r\nexport interface SectionDrawingViewProps {\r\n  /** The Id of the spatial view from which the SectionDrawing was generated. */\r\n  spatialView: Id64String;\r\n  /** If true, the spatial view should be displayed in the context of the drawing view. */\r\n  displaySpatialView: boolean;\r\n  /** Transform from drawing coordinates to spatial coordinates. If undefined, use identity transform. */\r\n  drawingToSpatialTransform?: TransformProps;\r\n}\r\n\r\n/** The response props from the getCustomViewState3dData RPC endpoint\r\n * @internal\r\n */\r\nexport interface CustomViewState3dProps {\r\n  modelIds: CompressedId64Set;\r\n  modelExtents: Range3dProps;\r\n  categoryIds: CompressedId64Set;\r\n}\r\n\r\n/**\r\n * The options passed to the getCustomViewState3dData RPC endpoint.\r\n * @internal\r\n */\r\nexport interface CustomViewState3dCreatorOptions {\r\n  modelIds?: CompressedId64Set;\r\n}\r\n\r\n/**\r\n * A result row from querying for subcategories\r\n * @internal\r\n */\r\nexport interface SubCategoryResultRow {\r\n  parentId: Id64String;\r\n  id: Id64String;\r\n  appearance: SubCategoryAppearance.Props;\r\n}\r\n\r\n/**\r\n * Request props for the hydrateViewState RPC endpoint.\r\n * @internal\r\n */\r\nexport interface HydrateViewStateRequestProps {\r\n  acsId?: string;\r\n  notLoadedModelSelectorStateModels?: CompressedId64Set;\r\n  /** @deprecated in 3.x. If loading categoryIds is necessary, see [IModelConnection.SubCategoriesCache.load]($frontend)*/\r\n  notLoadedCategoryIds?: CompressedId64Set;\r\n  sheetViewAttachmentIds?: CompressedId64Set;\r\n  viewStateLoadProps?: ViewStateLoadProps;\r\n  baseModelId?: Id64String;\r\n  spatialViewId?: Id64String;\r\n}\r\n\r\n/** Response props from the hydrateViewState RPC endpoint.\r\n * @internal\r\n */\r\nexport interface HydrateViewStateResponseProps {\r\n  acsElementProps?: ElementProps;\r\n  modelSelectorStateModels?: ModelProps[];\r\n  // cast this to viewAttachmentInfo[] on the frontend.\r\n  sheetViewAttachmentProps?: ViewAttachmentProps[];\r\n  sheetViewViews?: (ViewStateProps | undefined)[];\r\n  baseModelProps?: ModelProps;\r\n  spatialViewProps?: ViewStateProps;\r\n  /** @deprecated in 3.x. If loading categoryIds is necessary, see [IModelConnection.SubCategoriesCache.load]($frontend)*/\r\n  categoryIdsResult?: SubCategoryResultRow[];\r\n}\r\n\r\n/** Returned from [IModelDb.Views.getViewStateData]($backend).\r\n * @public\r\n * @extensions\r\n */\r\nexport interface ViewStateProps {\r\n  viewDefinitionProps: ViewDefinitionProps;\r\n  categorySelectorProps: CategorySelectorProps;\r\n  modelSelectorProps?: ModelSelectorProps;\r\n  displayStyleProps: DisplayStyleProps;\r\n  /** Sheet-specific properties, if this is a view of a [SheetModel]($backend). */\r\n  sheetProps?: SheetProps;\r\n  /** The Ids of the [ViewAttachment]($backend)s contained within the [SheetModel]($backend), if this is a sheet view. */\r\n  sheetAttachments?: Id64Array;\r\n  /** For a [DrawingViewState]($frontend), the extents of the [DrawingModel]($backend), used for determining the upper limits of the view's extents. */\r\n  modelExtents?: Range3dProps;\r\n  /** Information about the [SectionDrawing]($backend) relevant to displaying a drawing view. */\r\n  sectionDrawing?: SectionDrawingViewProps;\r\n}\r\n\r\n/** Options for loading a [[ViewStateProps]] via [IModelConnection.Views.load]($frontend) or [IModelDb.Views.getViewStateData]($backend).\r\n * @public\r\n * @extensions\r\n */\r\nexport interface ViewStateLoadProps {\r\n  /** Options for loading the view's [[DisplayStyleProps]]. */\r\n  displayStyle?: DisplayStyleLoadProps;\r\n\r\n  /**\r\n   * bindings for query-based selectors\r\n   * @beta\r\n   */\r\n  queryBindings?: {\r\n    modelSelector?: ViewStoreRpc.QueryBindings;\r\n    categorySelector?: ViewStoreRpc.QueryBindings;\r\n  };\r\n}\r\n\r\n/** Properties that define a ModelSelector\r\n * @public\r\n * @extensions\r\n */\r\nexport interface ModelSelectorProps extends DefinitionElementProps {\r\n  models: Id64Array;\r\n}\r\n\r\n/** Properties that define a CategorySelector\r\n * @public\r\n * @extensions\r\n */\r\nexport interface CategorySelectorProps extends DefinitionElementProps {\r\n  categories: Id64Array;\r\n}\r\n\r\n/** Parameters for performing a query on [ViewDefinition]($backend) classes.\r\n * @public\r\n * @extensions\r\n */\r\nexport interface ViewQueryParams extends EntityQueryParams {\r\n  wantPrivate?: boolean;\r\n}\r\n\r\n/** Parameters used to construct a ViewDefinition\r\n * @public\r\n * @extensions\r\n */\r\nexport interface ViewDefinitionProps extends DefinitionElementProps {\r\n  categorySelectorId: ViewIdString;\r\n  displayStyleId: ViewIdString;\r\n  description?: string;\r\n  jsonProperties?: {\r\n    /** Additional properties of the view. */\r\n    viewDetails?: ViewDetailsProps;\r\n  };\r\n}\r\n\r\n/** Parameters to construct a ViewDefinition3d\r\n * @public\r\n * @extensions\r\n */\r\nexport interface ViewDefinition3dProps extends ViewDefinitionProps {\r\n  /** if true, camera is valid. */\r\n  cameraOn: boolean;\r\n  /** The lower left back corner of the view frustum. */\r\n  origin: XYZProps;\r\n  /** The extent of the view frustum. */\r\n  extents: XYZProps;\r\n  /** Rotation of the view frustum (could be undefined if going Matrix3d -> YawPitchRoll). */\r\n  angles?: YawPitchRollProps;\r\n  /** The camera used for this view. */\r\n  camera: CameraProps;\r\n  jsonProperties?: {\r\n    /** Additional properties of the view. */\r\n    viewDetails?: ViewDetails3dProps;\r\n  };\r\n}\r\n\r\n/** Parameters to construct a SpatialViewDefinition\r\n * @public\r\n * @extensions\r\n */\r\nexport interface SpatialViewDefinitionProps extends ViewDefinition3dProps {\r\n  modelSelectorId: ViewIdString;\r\n}\r\n\r\n/** Parameters used to construct a ViewDefinition2d\r\n * @public\r\n * @extensions\r\n */\r\nexport interface ViewDefinition2dProps extends ViewDefinitionProps {\r\n  baseModelId: Id64String;\r\n  origin: XYProps;\r\n  delta: XYProps;\r\n  angle: AngleProps;\r\n}\r\n\r\n/**\r\n * @public\r\n * @extensions\r\n */\r\nexport interface AuxCoordSystemProps extends ElementProps {\r\n  type?: number;\r\n  description?: string;\r\n}\r\n\r\n/**  Properties of AuxCoordSystem2d\r\n * @public\r\n * @extensions\r\n */\r\nexport interface AuxCoordSystem2dProps extends AuxCoordSystemProps {\r\n  /** Origin of the AuxCoordSystem2d */\r\n  origin?: XYProps;\r\n  /** Rotation angle */\r\n  angle?: AngleProps;\r\n}\r\n\r\n/** Properties of AuxCoordSystem3d\r\n * @public\r\n * @extensions\r\n */\r\nexport interface AuxCoordSystem3dProps extends AuxCoordSystemProps {\r\n  /** Origin of the AuxCoordSystem3d */\r\n  origin?: XYZProps;\r\n  /** Yaw angle */\r\n  yaw?: AngleProps;\r\n  /** Pitch angle */\r\n  pitch?: AngleProps;\r\n  /** Roll angle */\r\n  roll?: AngleProps;\r\n}\r\n\r\n/**\r\n * Access to a ViewStore from the frontend.\r\n * @beta\r\n */\r\nexport namespace ViewStoreRpc {\r\n\r\n  /**\r\n   * Version of the Rpc interface. If any methods or interfaces of this API change, this number should\r\n   * be incremented according to the rules of semantic versioning. See .\\rpc\\README-RpcInterfaceVersioning.md for more information.\r\n   *  @internal\r\n   */\r\n  export const version = \"4.0.0\" as const;\r\n\r\n  /** an Id of a View, DisplayStyle, ModelSelector, CategorySelector, or Timeline in a ViewStore.\r\n   * Will be a base-36 number with a leading \"@\".\r\n   * @public\r\n   */\r\n  export type IdString = string;\r\n\r\n  /**\r\n   * A string identifying a group. This may either be a \"group name path\" or the RowString of a group (e.g. either \"group1/design/issues\" or \"@4e3\")\r\n   * The syntax is not ambiguous because ViewStoreIdStrings always start with \"@\" and  Group names can never contain \"@\".\r\n   */\r\n  export type ViewGroupSpec = IdString | ViewGroupPath;\r\n\r\n  /** The name for a view. */\r\n  export type ViewName = string;\r\n\r\n  /** The name for a Tag. */\r\n  export type TagName = string;\r\n\r\n  /** The name of an \"owner\". Should come from the authentication system, so it will be guaranteed unique.\r\n   * This name should be chosen by the user rather than their email address.\r\n   */\r\n  export type OwnerName = string;\r\n\r\n  /** The path name of a view group (e.g. \"group1/design/issues\"). Does not include the \"root\" group. */\r\n  export type ViewGroupPath = string;\r\n\r\n  /** The name for a view group.  */\r\n  export type ViewGroupName = string;\r\n\r\n  /** The name for a view group.  */\r\n  export type ClassFullName = string;\r\n\r\n  /** Determine if a string is an Id of an entry in a ViewStore (base-36 integer with a leading \"@\") */\r\n  export const isViewStoreId = (id?: ViewIdString) => true === id?.startsWith(\"@\");\r\n\r\n  /** Parameters for querying for views in a ViewStore. */\r\n  export interface QueryParams {\r\n    /** a list of classFullNames to accept. If not present, all classes are returned. */\r\n    readonly classNames?: ClassFullName[];\r\n    /** Optional \"LIMIT\" clause to limit the number of views returned. */\r\n    readonly limit?: number;\r\n    /** Optional \"OFFSET\" clause. Only valid if Limit is also present. */\r\n    readonly offset?: number;\r\n    /** A string to filter view names. May include wildcards if the `nameCompare` uses LIKE or GLOB (see SQLite documentation for LIKE and GLOB). */\r\n    readonly nameSearch?: string;\r\n    /** The comparison operator for `nameSearch`. Default is `=` */\r\n    readonly nameCompare?: \"GLOB\" | \"LIKE\" | \"NOT GLOB\" | \"NOT LIKE\" | \"=\" | \"<\" | \">\";\r\n    /* the Id of the view group to query. If not present, the root group is used. There is no way to query for views from multiple view groups in one request. */\r\n    readonly group?: IdString;\r\n    /** A list of tags to filter views. If present, only views that have one or more of the tags will be returned. */\r\n    readonly tags?: TagName[];\r\n    /* The name of an owner for private views. If present, private views owned by the owner will also be returned. Shared views are always returned. */\r\n    readonly owner?: OwnerName;\r\n  }\r\n\r\n  /** Parameters for specifying a Query to select Categories or Models. */\r\n  export interface SelectorQuery {\r\n    /**\r\n     * The full ClassName from which to select. If this SelectorQuery is for Categories, this must be or derive from \"BisCore:Category\".\r\n     * If this SelectorQuery is for Models, this must be or derive from \"BisCore:Model\".\r\n     */\r\n    from: ClassFullName;\r\n    /** If true, only return instances of `from`. Otherwise, return instances of `from` and any subclasses of `from`. */\r\n    only?: boolean;\r\n    /**\r\n     * filter for query. If present, only instances of `from` that satisfy the filter will be returned.\r\n     * If not supplied, all instances of `from` are returned.\r\n     * @note\r\n     * This value is used into the ECQuery:`SELECT ECInstanceId FROM ${query.from} WHERE ${query.where}`.\r\n     */\r\n    where?: string;\r\n    /** List of Model or Category ids to add to the query results.\r\n     * @note This is only valid if there is a `where` clause. Otherwise all instances of `from` will be returned so there is no value in adding ids.\r\n    */\r\n    adds?: Id64Array | CompressedId64Set;\r\n    /** List of Model or Category Ids to remove from the query results. */\r\n    removes?: Id64Array | CompressedId64Set;\r\n  }\r\n\r\n  /** A Model or Category selector may either be a query or a list of Ids. */\r\n  export type SelectorProps = { query: SelectorQuery, ids?: never } | { query?: never, ids: Id64Array | CompressedId64Set };\r\n\r\n  /** Information about a View in a ViewStore. */\r\n  export interface ViewInfo {\r\n    /** The Id of the view. */\r\n    id: IdString;\r\n    /** The name of the view. */\r\n    name?: ViewName;\r\n    /** The name of the owner of the view. */\r\n    owner?: OwnerName;\r\n    /** The className of the view. */\r\n    className: ClassFullName;\r\n    /** The Id of the view group containing the view. */\r\n    groupId: IdString;\r\n    /** If true, the view is private (unshared) and will only be returned by queries that specify the owner's name. */\r\n    isPrivate: boolean;\r\n    /** The Id of a ModelSelector, if the view has one. */\r\n    modelSelectorId?: IdString;\r\n    /** The Id of the CategorySelector for this view. */\r\n    categorySelectorId: IdString;\r\n    /** The Id of a DisplayStyle for the view. */\r\n    displayStyleId: IdString;\r\n    /** a list of tags for the view. */\r\n    tags?: TagName[];\r\n  }\r\n\r\n  /** Information about a ViewGroup in a ViewStore. */\r\n  export interface ViewGroupInfo {\r\n    /** The Id of this view group. */\r\n    id: IdString;\r\n    /** The name of this view group. */\r\n    name: ViewGroupName;\r\n    /** The Id of the parent of this view group. If undefined, this is the root group. */\r\n    parent?: IdString;\r\n    /** The Id of the default view for this view group. */\r\n    defaultView?: IdString;\r\n  }\r\n\r\n  /** Arguments for adding a new view to a ViewStore. */\r\n  export interface AddViewArgs {\r\n    /** the properties of the ViewDefinition for the new view. */\r\n    readonly viewDefinition: ViewDefinitionProps;\r\n\r\n    /**\r\n     * The properties of a category selector for the new view.\r\n     * @note This value is only used, and should only be present if `viewDefinition.categorySelectorId` **not** a valid\r\n     * `IdString`. In that case, a new category selector will be created with these properties and its Id will be used.\r\n     * Otherwise, the categorySelectorId from the ViewDefinition is used. If it does not represent a valid category\r\n     * selector, an error is thrown.\r\n     */\r\n    readonly categorySelectorProps?: CategorySelectorProps;\r\n\r\n    /** The properties of a model selector for the new view.\r\n     * @note This value is only used, and should only be present if `viewDefinition.modelSelectorId` **not** a valid\r\n     * `IdString`. In that case, a new model selector will be created with these properties and its Id will be used.\r\n     * Otherwise, the modelSelectorId from the ViewDefinition is used. If it does not represent a valid model selector,\r\n     * an error is thrown.\r\n     */\r\n    readonly modelSelectorProps?: ModelSelectorProps;\r\n\r\n    /** The properties of a display style for the new view.\r\n     * @note This value is only used, and should only be present if `viewDefinition.displayStyleId` **not** a valid\r\n     * `IdString`. In that case, a new display style will be created with these properties and its Id will be used.\r\n     * Otherwise, the displayStyleId from the ViewDefinition is used. If it does not represent a valid display style, an\r\n     * error is thrown.\r\n     */\r\n    readonly displayStyleProps?: DisplayStyleProps;\r\n\r\n    /* the owner of the view. Must be present if isPrivate is true. */\r\n    readonly owner?: OwnerName;\r\n\r\n    /* the Id of the view group for the view. If not present, the view is added to the root group. */\r\n    readonly group?: IdString;\r\n\r\n    /* if true, the view is private (unshared). */\r\n    readonly isPrivate?: boolean;\r\n\r\n    /* an optional list of tags for the view. */\r\n    readonly tags?: TagName[];\r\n\r\n    /** optional thumbnail for the view. */\r\n    readonly thumbnail?: ThumbnailProps;\r\n  }\r\n\r\n  /** Argument for finding a category selector, model selector, display style, or timeline by name or Id. */\r\n  export type NameOrId = { name: string, id?: never } | { id: IdString, name?: never };\r\n\r\n  /** Bindings for parameterized values in where clause of SelectorQuery\r\n   * @see[[ECSqlStatement.bindValues]]\r\n   */\r\n  export interface QueryBindings {\r\n    bindings?: any[] | object;\r\n  }\r\n\r\n  /**\r\n   * Methods for reading from a ViewStore via Rpc from a frontend via `IModelConnection.views.viewsStoreReader`. These\r\n   * methods use the *current* ViewStore for the iModel, and attempt to load the default ViewStore if no ViewStore is\r\n   * currently loaded. They will throw exceptions if the request cannot be fulfilled.\r\n   * @note The user's accessToken is validated against the ViewStore for every request. For each of these methods, the\r\n   * user only needs read permission to the ViewStore.\r\n   */\r\n  export interface Reader {\r\n    /** Find all views owned by the supplied owner name. */\r\n    findViewsByOwner(args: { owner: OwnerName }): Promise<ViewInfo[]>;\r\n\r\n    /** Get a category selector by Id. Throws if it does not exist. */\r\n    getCategorySelector(args: NameOrId & QueryBindings): Promise<CategorySelectorProps>;\r\n\r\n    /** Get a display style by Id. Throws if it does not exist. */\r\n    getDisplayStyle(args: NameOrId & { opts?: DisplayStyleLoadProps }): Promise<DisplayStyleProps>;\r\n\r\n    /** Get a model selector by Id. Throws if it does not exist. */\r\n    getModelSelector(args: NameOrId & QueryBindings): Promise<ModelSelectorProps>;\r\n\r\n    /** Get a thumbnail for a view. */\r\n    getThumbnail(args: { viewId: IdString }): Promise<ThumbnailProps | undefined>;\r\n\r\n    /** Get a render timeline by Id. Throws if it does not exist. */\r\n    getTimeline(args: NameOrId): Promise<RenderTimelineProps>;\r\n\r\n    /** Get a view by name. The name can include the *view group path*, if no `groupId` is supplied. */\r\n    getViewByName(arg: { name: ViewName, groupId?: IdString }): Promise<ViewInfo | undefined>;\r\n\r\n    /** Get a view definition by viewId. Throws if it does not exist. */\r\n    getViewDefinition(args: { viewId: IdString }): Promise<ViewDefinitionProps>;\r\n\r\n    /** get the properties of a ViewGroup by id. This will include the defaultViewId, if one exists. */\r\n    getViewGroupInfo(args: { groupId?: IdString }): Promise<ViewGroupInfo | undefined>;\r\n\r\n    /** Get a list of ViewGroups that are children of the supplied parent. If no parent is supplied, the root group is used.\r\n     * Each entry in the list includes the id and name of the ViewGroup.\r\n     */\r\n    getViewGroups(args: { parent?: ViewGroupSpec }): Promise<{ id: IdString, name: string }[]>;\r\n\r\n    /** Get the ViewInfo for a view by Id. Returns undefined if the view does not exist. */\r\n    getViewInfo(args: { viewId: IdString }): Promise<ViewInfo | undefined>;\r\n\r\n    /** Query for a list of ViewInfos for views that match the supplied [[QueryParams]].\r\n     * @note The array will be sorted by name, ascending. To limit the size of the array, supply `limit` and `offset` in the QueryParams.\r\n     */\r\n    queryViews(queryParams: QueryParams): Promise<ViewInfo[]>;\r\n  }\r\n\r\n  /**\r\n   * Methods for writing to a ViewStore via Rpc from a frontend via `IModelConnection.views.viewsStoreWriter`. These\r\n   * methods use the *current* ViewStore for the iModel, and attempt to load the default ViewStore if no ViewStore is\r\n   * currently loaded. They will throw exceptions if the request cannot be fulfilled.\r\n   * @note The user's accessToken is validated against the ViewStore for every request. For each of these methods, the\r\n   * user must have write permission to the ViewStore.\r\n   */\r\n  export interface Writer {\r\n    /**\r\n     * Add a category selector to a ViewStore.\r\n     * @returns The IdString of the new category selector.\r\n     */\r\n    addCategorySelector(args: { name?: string, selector: SelectorProps, owner?: OwnerName }): Promise<IdString>;\r\n\r\n    /** Add a display style to a ViewStore.\r\n     * @returns The IdString of the new display style.\r\n     */\r\n    addDisplayStyle(args: { name?: string, className: string, settings: DisplayStyleSettingsProps, owner?: OwnerName }): Promise<IdString>;\r\n\r\n    /**\r\n     *  Add a model selector to a ViewStore.\r\n     * @returns The IdString of the new model selector.\r\n     */\r\n    addModelSelector(args: { name?: string, selector: SelectorProps, owner?: OwnerName }): Promise<IdString>;\r\n\r\n    /**\r\n     * Add a thumbnail for a view. If the view already has a thumbnail, it is replaced.\r\n     * If a view is deleted, its thumbnail is also deleted.\r\n     * @note The thumbnail must be a valid image in PNG or JPEG format.\r\n     */\r\n    addOrReplaceThumbnail(args: { viewId: IdString, thumbnail: ThumbnailProps }): Promise<void>;\r\n\r\n    /** Add tags to a view. If the view already has tags, the new tags are appended to the existing tags. */\r\n    addTagsToView(args: { viewId: IdString, tags: TagName[] }): Promise<void>;\r\n\r\n    /** Add a render timeline to a ViewStore.\r\n     * @returns The IdString of the new timeline.\r\n     */\r\n    addTimeline(args: { name?: string, timeline: RenderSchedule.ScriptProps, owner?: OwnerName }): Promise<IdString>;\r\n\r\n    /** Add a view to a ViewStore. If no group is supplied, the new view is added to the root view group.\r\n     * @returns The IdString of the new view\r\n     */\r\n    addView(args: AddViewArgs): Promise<IdString>;\r\n\r\n    /** Add a view group to a ViewStore. If no parent is supplied, the new group is added to the root view group.\r\n     * @returns the IdString of new view group\r\n     */\r\n    addViewGroup(args: { name: string, parentId?: IdString, owner?: OwnerName }): Promise<IdString>;\r\n\r\n    /** Change the default view for a view group. If no group is supplied, this changes the default view for the root view group. */\r\n    changeDefaultViewId(args: { defaultView: IdString, group?: ViewGroupSpec }): Promise<void>;\r\n\r\n    /** Delete the thumbnail for a view. */\r\n    deleteThumbnail(args: { viewId: IdString }): Promise<void>;\r\n\r\n    /**\r\n     * Delete a view from a ViewStore. If this is the default view for a view group, it cannot be deleted until another\r\n     * view is set as the default.\r\n     * @note If this view references a category selector, model selector, or display style that is not referenced by any\r\n     * other view, *and do not have a name*, they will each also be deleted. If the view has a thumbnail, it is also\r\n     * deleted.\r\n     */\r\n    deleteView(args: { viewId: IdString }): Promise<void>;\r\n\r\n    /** Delete a view group from a ViewStore. This will also delete all views in the group. */\r\n    deleteViewGroup(args: { name: ViewGroupSpec }): Promise<void>;\r\n\r\n    /** Delete a display style from a ViewStore. If the display style is referenced by any view, it cannot be deleted\r\n     * and an exception will be thrown.\r\n     */\r\n    deleteDisplayStyle(args: { id: IdString }): Promise<void>;\r\n\r\n    /** Delete a model selector from a ViewStore. If the model selector is referenced by any view, it cannot be deleted\r\n     * and an exception will be thrown. */\r\n    deleteModelSelector(args: { id: IdString }): Promise<void>;\r\n\r\n    /** Delete a category selector from a ViewStore. If the category selector is referenced by any view, it cannot be\r\n     * deleted and an exception will be thrown.\r\n     */\r\n    deleteCategorySelector(args: { id: IdString }): Promise<void>;\r\n\r\n    /** Delete a render timeline from a ViewStore. */\r\n    deleteTimeline(args: { id: IdString }): Promise<void>;\r\n\r\n    /** Delete a tag. This removes it from all views where it was used. */\r\n    deleteTag(args: { name: TagName }): Promise<void>;\r\n\r\n    /** remove a tag from a view. */\r\n    removeTagFromView(args: { viewId: IdString, tag: TagName }): Promise<void>;\r\n\r\n    /** Update the properties of a category selector. */\r\n    updateCategorySelector(args: NameOrId & { selector: SelectorProps }): Promise<void>;\r\n\r\n    /** Update the properties of a display style. */\r\n    updateDisplayStyle(args: NameOrId & { className: string, settings: DisplayStyleSettingsProps }): Promise<void>;\r\n\r\n    /** Update the properties of a model selector. */\r\n    updateModelSelector(args: NameOrId & { selector: SelectorProps }): Promise<void>;\r\n\r\n    /** Update the properties of a render timeline. */\r\n    updateTimeline(args: NameOrId & { timeline: RenderSchedule.ScriptProps }): Promise<void>;\r\n\r\n    /** Update the properties of a view definition. */\r\n    updateViewDefinition(args: { viewId: IdString, viewDefinition: ViewDefinitionProps }): Promise<void>;\r\n\r\n    /** Change a view from shared to private, or vice versa. If changing to private, the owner must be supplied. */\r\n    updateViewShared(arg: { viewId: IdString, isShared: boolean, owner?: string }): Promise<void>;\r\n\r\n    /** Set the name of a category selector. */\r\n    renameCategorySelector(args: { id: IdString, name?: string }): Promise<void>;\r\n\r\n    /** Set the name of a display style. */\r\n    renameDisplayStyle(args: { id: IdString, name?: string }): Promise<void>;\r\n\r\n    /** Set the name of a model selector. */\r\n    renameModelSelector(args: { id: IdString, name?: string }): Promise<void>;\r\n\r\n    /** Set the name of a render timeline. */\r\n    renameTimeline(args: { id: IdString, name?: string }): Promise<void>;\r\n\r\n    /** Set the name of a view. */\r\n    renameView(args: { viewId: IdString, name: string }): Promise<void>;\r\n\r\n    /** Set the name of a view group. */\r\n    renameViewGroup(args: { groupId: IdString, name: string }): Promise<void>;\r\n\r\n    /** rename an existing tag. */\r\n    renameTag(args: { oldName: TagName, newName: TagName }): Promise<void>;\r\n  }\r\n}\r\n"]}

package/lib/cjs/WhiteOnWhiteReversalSettings.js.map

@@ -1 +1 @@
-{"version":3,"file":"WhiteOnWhiteReversalSettings.js","sourceRoot":"","sources":["../../src/WhiteOnWhiteReversalSettings.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAaH;;;;;;GAMG;AACH,MAAa,4BAA4B;IAOvC,YAAoB,gBAAyB;QAC3C,IAAI,CAAC,qBAAqB,GAAG,gBAAgB,CAAC;IAChD,CAAC;IAKD,uCAAuC;IAChC,MAAM,CAAC,QAAQ,CAAC,KAAiC;QACtD,OAAO,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IACtE,CAAC;IAED,mHAAmH;IAC5G,MAAM;QACX,OAAO,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,CAAC;IAED,uDAAuD;IAChD,MAAM,CAAC,KAAmC;QAC/C,OAAO,IAAI,KAAK,KAAK,CAAC;IACxB,CAAC;;AA3BH,oEA4BC;AAjBgB,sCAAS,GAAG,IAAI,4BAA4B,CAAC,IAAI,CAAC,CAAC;AACnD,oCAAO,GAAG,IAAI,4BAA4B,CAAC,KAAK,CAAC,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module DisplayStyles\n */\n\n/** JSON representation of a [[WhiteOnWhiteReversalSettings]].\n * @public\n * @extensions\n */\nexport interface WhiteOnWhiteReversalProps {\n  /** Default: false.\n   * @see [[WhiteOnWhiteReversalSettings.ignoreBackgroundColor]].\n   */\n  ignoreBackgroundColor?: boolean;\n}\n\n/** As part of a [[DisplayStyleSettings]], controls how white-on-white reversal is applied to make white geometry more\n * visible in the view.\n * By default, pure white geometry is displayed as black instead if the [[DisplayStyleSettings.backgroundColor]] is also pure white.\n * These settings are only applied if the display style's [[ViewFlags.whiteOnWhiteReversal]] flag is enabled.\n * @see [[DisplayStyleSettings.whiteOnWhiteReversal]] to change these settings for a display style.\n * @public\n */\nexport class WhiteOnWhiteReversalSettings {\n  /** If true, white-on-white reversal ignores the display style's background color; otherwise, white-on-white reversal applies only\n   * if the background color is pure white.\n   * @see [[DisplayStyleSettings.backgroundColor]] to change the background color.\n   */\n  public readonly ignoreBackgroundColor: boolean;\n\n  private constructor(ignoreBackground: boolean) {\n    this.ignoreBackgroundColor = ignoreBackground;\n  }\n\n  private static _noIgnore = new WhiteOnWhiteReversalSettings(true);\n  private static _ignore = new WhiteOnWhiteReversalSettings(false);\n\n  /** Create from JSON representation. */\n  public static fromJSON(props?: WhiteOnWhiteReversalProps): WhiteOnWhiteReversalSettings {\n    return props?.ignoreBackgroundColor ? this._noIgnore : this._ignore;\n  }\n\n  /** Convert to JSON representation. The JSON representation is `undefined` if these settings match the defaults. */\n  public toJSON(): WhiteOnWhiteReversalProps | undefined {\n    return this.ignoreBackgroundColor ? { ignoreBackgroundColor: true } : undefined;\n  }\n\n  /** Returns true if `this` is equivalent to `other`. */\n  public equals(other: WhiteOnWhiteReversalSettings): boolean {\n    return this === other;\n  }\n}\n"]}
+{"version":3,"file":"WhiteOnWhiteReversalSettings.js","sourceRoot":"","sources":["../../src/WhiteOnWhiteReversalSettings.ts"],"names":[],"mappings":";AAAA;;;+FAG+F;AAC/F;;GAEG;;;AAaH;;;;;;GAMG;AACH,MAAa,4BAA4B;IAOvC,YAAoB,gBAAyB;QAC3C,IAAI,CAAC,qBAAqB,GAAG,gBAAgB,CAAC;IAChD,CAAC;IAKD,uCAAuC;IAChC,MAAM,CAAC,QAAQ,CAAC,KAAiC;QACtD,OAAO,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;IACtE,CAAC;IAED,mHAAmH;IAC5G,MAAM;QACX,OAAO,IAAI,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,qBAAqB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAClF,CAAC;IAED,uDAAuD;IAChD,MAAM,CAAC,KAAmC;QAC/C,OAAO,IAAI,KAAK,KAAK,CAAC;IACxB,CAAC;;AA3BH,oEA4BC;AAjBgB,sCAAS,GAAG,IAAI,4BAA4B,CAAC,IAAI,CAAC,CAAC;AACnD,oCAAO,GAAG,IAAI,4BAA4B,CAAC,KAAK,CAAC,CAAC","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module DisplayStyles\r\n */\r\n\r\n/** JSON representation of a [[WhiteOnWhiteReversalSettings]].\r\n * @public\r\n * @extensions\r\n */\r\nexport interface WhiteOnWhiteReversalProps {\r\n  /** Default: false.\r\n   * @see [[WhiteOnWhiteReversalSettings.ignoreBackgroundColor]].\r\n   */\r\n  ignoreBackgroundColor?: boolean;\r\n}\r\n\r\n/** As part of a [[DisplayStyleSettings]], controls how white-on-white reversal is applied to make white geometry more\r\n * visible in the view.\r\n * By default, pure white geometry is displayed as black instead if the [[DisplayStyleSettings.backgroundColor]] is also pure white.\r\n * These settings are only applied if the display style's [[ViewFlags.whiteOnWhiteReversal]] flag is enabled.\r\n * @see [[DisplayStyleSettings.whiteOnWhiteReversal]] to change these settings for a display style.\r\n * @public\r\n */\r\nexport class WhiteOnWhiteReversalSettings {\r\n  /** If true, white-on-white reversal ignores the display style's background color; otherwise, white-on-white reversal applies only\r\n   * if the background color is pure white.\r\n   * @see [[DisplayStyleSettings.backgroundColor]] to change the background color.\r\n   */\r\n  public readonly ignoreBackgroundColor: boolean;\r\n\r\n  private constructor(ignoreBackground: boolean) {\r\n    this.ignoreBackgroundColor = ignoreBackground;\r\n  }\r\n\r\n  private static _noIgnore = new WhiteOnWhiteReversalSettings(true);\r\n  private static _ignore = new WhiteOnWhiteReversalSettings(false);\r\n\r\n  /** Create from JSON representation. */\r\n  public static fromJSON(props?: WhiteOnWhiteReversalProps): WhiteOnWhiteReversalSettings {\r\n    return props?.ignoreBackgroundColor ? this._noIgnore : this._ignore;\r\n  }\r\n\r\n  /** Convert to JSON representation. The JSON representation is `undefined` if these settings match the defaults. */\r\n  public toJSON(): WhiteOnWhiteReversalProps | undefined {\r\n    return this.ignoreBackgroundColor ? { ignoreBackgroundColor: true } : undefined;\r\n  }\r\n\r\n  /** Returns true if `this` is equivalent to `other`. */\r\n  public equals(other: WhiteOnWhiteReversalSettings): boolean {\r\n    return this === other;\r\n  }\r\n}\r\n"]}

package/lib/cjs/annotation/TextAnnotation.d.ts

@@ -1,41 +1,38 @@
 /** @packageDocumentation
  * @module Annotation
  */
-import { Point3d, Range2d, Transform, YawPitchRollAngles, YawPitchRollProps } from "@itwin/core-geometry";
+import { Point3d, Transform, XAndY, XYZProps, YawPitchRollAngles, YawPitchRollProps } from "@itwin/core-geometry";
 import { TextBlock, TextBlockProps } from "./TextBlock";
-/**
- * Describes the horizontal and vertical alignment of a [[TextAnnotation]]'s text relative to the [Placement]($common) origin of
- * the [TextAnnotation2d]($backend) or [TextAnnotation3d]($backend) host element, also referred to as the annotation's "anchor point".
- * For example, if the anchor is specified as middle-center, the text will be centered on the element's origin.
- * The anchor point also serves as the pivot point for [[TextAnnotation.rotation]], such that the text is rotated about the
- * anchor point while the anchor point remains fixed.
+/** Describes how to compute the "anchor point" for a [[TextAnnotation]].
+ * The anchor point is a point on or inside of the 2d bounding box enclosing the contents of the annotation's [[TextBlock]].
+ * The annotation can be rotated and translated relative to the anchor point. The anchor point also serves as the snap point
+ * when [AccuSnap]($frontend) is set to [SnapMode.Origin]($frontend).
+ * @see [[TextAnnotation]] for a description of how the anchor point is computed.
  * @beta
- * @preview
- * @extensions
  */
 export interface TextAnnotationAnchor {
     /**
      * The vertical alignment of the anchor point.
-     * "top" aligns the top of the text with the anchor point.
-     * "middle" aligns the middle of the text with the anchor point.
-     * "bottom" aligns the bottom of the text with the anchor point.
+     * "top" aligns the anchor point with the top of the text's bounding box.
+     * "middle" aligns the anchor point with the middle of the text's bounding box.
+     * "bottom" aligns the anchor point with the bottom of the text's bounding box.
      */
     vertical: "top" | "middle" | "bottom";
     /**
      * The horizontal alignment of the anchor point.
-     * "left" aligns the left side of the text with the anchor point.
-     * "center" aligns the center of the text with the anchor point.
-     * "right" aligns the right side of the text with the anchor point.
+     * "left" aligns the anchor point with left side of the text's bounding box.
+     * "center" aligns the anchor point with center of the text with's bounding box.
+     * "right" aligns the anchor point with right side of the text's bounding box.
      */
     horizontal: "left" | "center" | "right";
 }
 /**
  * JSON representation of a [[TextAnnotation]].
  * @beta
- * @preview
- * @extensions
  */
 export interface TextAnnotationProps {
+    /** See [[TextAnnotation.offset]]. Default: [0, 0, 0]. */
+    offset?: XYZProps;
     /** See [[TextAnnotation.orientation]]. Default: no rotation. */
     orientation?: YawPitchRollProps;
     /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */
@@ -45,10 +42,10 @@ export interface TextAnnotationProps {
 }
 /** Arguments supplied to [[TextAnnotation.create]].
  * @beta
- * @preview
- * @extensions
  */
 export interface TextAnnotationCreateArgs {
+    /** See [[TextAnnotation.offset]]. Default: (0, 0, 0). */
+    offset?: Point3d;
     /** See [[TextAnnotation.orientation]]. Default: no rotation. */
     orientation?: YawPitchRollAngles;
     /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */
@@ -58,26 +55,28 @@ export interface TextAnnotationCreateArgs {
 }
 /**
  * Represents a formatted block of text positioned in 2d or 3d space.
- * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a TextAnnotation from which their geometric representation is generated.
+ * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a single TextAnnotation from which their geometric representation is generated.
+ * Other types of elements may store multiple TextAnnotations, positioned relative to one another.
+ * The annotation's position and orientation relative to the host element's [Placement]($common) is determined as follows:
+ * - First, the width and height of a box enclosing the contents of the [[textBlock]] must be computed using [computeTextBlockExtents]($backend). This yields a box with the top-left
+ * corner at (0, 0) and the bottom-right corner at (width, -height).
+ * - Then, an "anchor point" is computed based on the text box and the [[anchor]] property. For example, if the annotation is anchored at the center-left, the anchor point will be (width/2, -height).
+ * - The [[orientation]] is applied to rotate the box around the anchor point.
+ * - Finally, the [[offset]] is added to the anchor point to apply translation.
  * @see [produceTextAnnotationGeometry]($backend) to decompose the annotation into a set of geometric primitives suitable for use with [[GeometryStreamBuilder.appendTextBlock]].
  * @beta
- * @preview
- * @extensions
  */
 export declare class TextAnnotation {
-    /**
-     * The rotation of the annotation.
+    /** The rotation of the annotation.
      * @note When defining an annotation for a [TextAnnotation2d]($backend), only the `yaw` component (rotation around the Z axis) is used.
      */
     orientation: YawPitchRollAngles;
-    /**
-     * The formatted document.
-     */
+    /** The formatted document. */
     textBlock: TextBlock;
-    /**
-     * Describes how the [[textBlock]]'s content should be aligned relative to the host element's origin.
-     */
+    /** Describes how to compute the [[textBlock]]'s anchor point. */
     anchor: TextAnnotationAnchor;
+    /** An offset applied to the anchor point that can be used to position annotations within the same geometry stream relative to one another. */
+    offset: Point3d;
     private constructor();
     /** Creates a new TextAnnotation. */
     static create(args?: TextAnnotationCreateArgs): TextAnnotation;
@@ -89,12 +88,19 @@ export declare class TextAnnotation {
      * Converts this annotation to its JSON representation.
      */
     toJSON(): TextAnnotationProps;
-    /**
-     * @internal used by produceTextAnnotationGeometry; requires layoutRange computed by layoutTextBlock.
+    /** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.
+     * The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored
+     * at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.
+     * The text block will be rotated around the fixed anchor point according to [[orientation]], then the anchor point will be translated by [[offset]].
+     * @param textBlockDimensions The width and height of the bounding box containing the text block. You can compute this using [computeTextBlockExtents]($common).
+     * @see [[computeAnchorPoint]] to compute the transform's anchor point.
+     */
+    computeTransform(textBlockDimensions: XAndY): Transform;
+    /** Compute the anchor point of this annotation as specified by [[anchor]].
+     * @param textBlockDimensions The width and height of the bounding box containing the [[textBlock]]. You can compute this using [computeTextBlockExtents]($common).
+     * @see [[computeTransform]] to compute the transform relative to the anchor point.
      */
-    computeDocumentTransform(layoutRange: Range2d): Transform;
-    /** @internal */
-    computeAnchorPoint(layoutRange: Range2d): Point3d;
+    computeAnchorPoint(textBlockDimensions: XAndY): Point3d;
     /** Returns true if this annotation is logically equivalent to `other`. */
     equals(other: TextAnnotation): boolean;
 }

package/lib/cjs/annotation/TextAnnotation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TextAnnotation.d.ts","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC1G,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAEtC;;;;;OAKG;IACH,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACzC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,sEAAsE;IACtE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,gEAAgE;IAChE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AACD;;;;;;;GAOG;AACH,qBAAa,cAAc;IACzB;;;OAGG;IACI,WAAW,EAAE,kBAAkB,CAAC;IACvC;;OAEG;IACI,SAAS,EAAE,SAAS,CAAC;IAC5B;;OAEG;IACI,MAAM,EAAE,oBAAoB,CAAC;IAEpC,OAAO;IAMP,oCAAoC;WACtB,MAAM,CAAC,IAAI,CAAC,EAAE,wBAAwB,GAAG,cAAc;IAQrE;;OAEG;WACW,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,GAAG,cAAc;IAQ9E;;OAEG;IACI,MAAM,IAAI,mBAAmB;IAkBpC;;OAEG;IACI,wBAAwB,CAAC,WAAW,EAAE,OAAO,GAAG,SAAS;IAOhE,gBAAgB;IACT,kBAAkB,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO;IAyBxD,0EAA0E;IACnE,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;CAI9C"}
+{"version":3,"file":"TextAnnotation.d.ts","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"AAIA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAClH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAEtC;;;;;OAKG;IACH,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;CACzC;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,gEAAgE;IAChE,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,sEAAsE;IACtE,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,sEAAsE;IACtE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wDAAwD;IACxD,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IACzB;;OAEG;IACI,WAAW,EAAE,kBAAkB,CAAC;IACvC,8BAA8B;IACvB,SAAS,EAAE,SAAS,CAAC;IAC5B,iEAAiE;IAC1D,MAAM,EAAE,oBAAoB,CAAC;IACpC,8IAA8I;IACvI,MAAM,EAAE,OAAO,CAAC;IAEvB,OAAO;IAOP,oCAAoC;WACtB,MAAM,CAAC,IAAI,CAAC,EAAE,wBAAwB,GAAG,cAAc;IASrE;;OAEG;WACW,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,SAAS,GAAG,cAAc;IAS9E;;OAEG;IACI,MAAM,IAAI,mBAAmB;IAsBpC;;;;;;OAMG;IACI,gBAAgB,CAAC,mBAAmB,EAAE,KAAK,GAAG,SAAS;IAS9D;;;OAGG;IACI,kBAAkB,CAAC,mBAAmB,EAAE,KAAK,GAAG,OAAO;IAyB9D,0EAA0E;IACnE,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO;CAK9C"}

package/lib/cjs/annotation/TextAnnotation.js

@@ -12,30 +12,38 @@ const core_geometry_1 = require("@itwin/core-geometry");
 const TextBlock_1 = require("./TextBlock");
 /**
  * Represents a formatted block of text positioned in 2d or 3d space.
- * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a TextAnnotation from which their geometric representation is generated.
+ * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a single TextAnnotation from which their geometric representation is generated.
+ * Other types of elements may store multiple TextAnnotations, positioned relative to one another.
+ * The annotation's position and orientation relative to the host element's [Placement]($common) is determined as follows:
+ * - First, the width and height of a box enclosing the contents of the [[textBlock]] must be computed using [computeTextBlockExtents]($backend). This yields a box with the top-left
+ * corner at (0, 0) and the bottom-right corner at (width, -height).
+ * - Then, an "anchor point" is computed based on the text box and the [[anchor]] property. For example, if the annotation is anchored at the center-left, the anchor point will be (width/2, -height).
+ * - The [[orientation]] is applied to rotate the box around the anchor point.
+ * - Finally, the [[offset]] is added to the anchor point to apply translation.
  * @see [produceTextAnnotationGeometry]($backend) to decompose the annotation into a set of geometric primitives suitable for use with [[GeometryStreamBuilder.appendTextBlock]].
  * @beta
- * @preview
- * @extensions
  */
 class TextAnnotation {
-    constructor(angles, textBlock, anchor) {
+    constructor(offset, angles, textBlock, anchor) {
+        this.offset = offset;
         this.orientation = angles;
         this.textBlock = textBlock;
         this.anchor = anchor;
     }
     /** Creates a new TextAnnotation. */
     static create(args) {
+        const offset = args?.offset ?? new core_geometry_1.Point3d();
         const angles = args?.orientation ?? new core_geometry_1.YawPitchRollAngles();
         const textBlock = args?.textBlock ?? TextBlock_1.TextBlock.createEmpty();
         const anchor = args?.anchor ?? { vertical: "top", horizontal: "left" };
-        return new TextAnnotation(angles, textBlock, anchor);
+        return new TextAnnotation(offset, angles, textBlock, anchor);
     }
     /**
      * Creates a new TextAnnotation instance from its JSON representation.
      */
     static fromJSON(props) {
         return TextAnnotation.create({
+            offset: props?.offset ? core_geometry_1.Point3d.fromJSON(props.offset) : undefined,
             orientation: props?.orientation ? core_geometry_1.YawPitchRollAngles.fromJSON(props.orientation) : undefined,
             textBlock: props?.textBlock ? TextBlock_1.TextBlock.create(props.textBlock) : undefined,
             anchor: props?.anchor ? { ...props.anchor } : undefined,
@@ -49,6 +57,9 @@ class TextAnnotation {
         // Even if the text block is empty, we want to record its style name and overrides, e.g.,
         // so the user can pick up where they left off editing it next time.
         props.textBlock = this.textBlock.toJSON();
+        if (!this.offset.isZero) {
+            props.offset = this.offset.toJSON();
+        }
         if (!this.orientation.isIdentity()) {
             props.orientation = this.orientation.toJSON();
         }
@@ -57,32 +68,41 @@ class TextAnnotation {
         }
         return props;
     }
-    /**
-     * @internal used by produceTextAnnotationGeometry; requires layoutRange computed by layoutTextBlock.
+    /** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.
+     * The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored
+     * at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.
+     * The text block will be rotated around the fixed anchor point according to [[orientation]], then the anchor point will be translated by [[offset]].
+     * @param textBlockDimensions The width and height of the bounding box containing the text block. You can compute this using [computeTextBlockExtents]($common).
+     * @see [[computeAnchorPoint]] to compute the transform's anchor point.
      */
-    computeDocumentTransform(layoutRange) {
-        const origin = this.computeAnchorPoint(layoutRange);
+    computeTransform(textBlockDimensions) {
+        const anchorPt = this.computeAnchorPoint(textBlockDimensions);
         const matrix = this.orientation.toMatrix3d();
-        return core_geometry_1.Transform.createFixedPointAndMatrix(origin, matrix);
+        const rotation = core_geometry_1.Transform.createFixedPointAndMatrix(anchorPt, matrix);
+        const translation = core_geometry_1.Transform.createTranslation(this.offset);
+        return translation.multiplyTransformTransform(rotation, rotation);
     }
-    /** @internal */
-    computeAnchorPoint(layoutRange) {
+    /** Compute the anchor point of this annotation as specified by [[anchor]].
+     * @param textBlockDimensions The width and height of the bounding box containing the [[textBlock]]. You can compute this using [computeTextBlockExtents]($common).
+     * @see [[computeTransform]] to compute the transform relative to the anchor point.
+     */
+    computeAnchorPoint(textBlockDimensions) {
         let x = 0;
         let y = 0;
         switch (this.anchor.horizontal) {
             case "center":
-                x += layoutRange.xLength() / 2;
+                x += textBlockDimensions.x / 2;
                 break;
             case "right":
-                x += layoutRange.xLength();
+                x += textBlockDimensions.x;
                 break;
         }
         switch (this.anchor.vertical) {
             case "middle":
-                y -= layoutRange.yLength() / 2;
+                y -= textBlockDimensions.y / 2;
                 break;
             case "bottom":
-                y -= layoutRange.yLength();
+                y -= textBlockDimensions.y;
                 break;
         }
         return new core_geometry_1.Point3d(x, y, 0);
@@ -90,7 +110,8 @@ class TextAnnotation {
     /** Returns true if this annotation is logically equivalent to `other`. */
     equals(other) {
         return this.anchor.horizontal === other.anchor.horizontal && this.anchor.vertical === other.anchor.vertical
-            && this.orientation.isAlmostEqual(other.orientation) && this.textBlock.equals(other.textBlock);
+            && this.orientation.isAlmostEqual(other.orientation) && this.offset.isAlmostEqual(other.offset)
+            && this.textBlock.equals(other.textBlock);
     }
 }
 exports.TextAnnotation = TextAnnotation;

package/lib/cjs/annotation/TextAnnotation.js.map

@@ -1 +1 @@
-{"version":3,"file":"TextAnnotation.js","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\n* See LICENSE.md in the project root for license terms and full copyright notice.\n*--------------------------------------------------------------------------------------------*/\n/** @packageDocumentation\n * @module Annotation\n */\n\nimport { Point3d, Range2d, Transform, YawPitchRollAngles, YawPitchRollProps } from \"@itwin/core-geometry\";\nimport { TextBlock, TextBlockProps } from \"./TextBlock\";\n\n/**\n * Describes the horizontal and vertical alignment of a [[TextAnnotation]]'s text relative to the [Placement]($common) origin of\n * the [TextAnnotation2d]($backend) or [TextAnnotation3d]($backend) host element, also referred to as the annotation's \"anchor point\".\n * For example, if the anchor is specified as middle-center, the text will be centered on the element's origin.\n * The anchor point also serves as the pivot point for [[TextAnnotation.rotation]], such that the text is rotated about the\n * anchor point while the anchor point remains fixed.\n * @beta\n * @preview\n * @extensions\n */\nexport interface TextAnnotationAnchor {\n  /**\n   * The vertical alignment of the anchor point.\n   * \"top\" aligns the top of the text with the anchor point.\n   * \"middle\" aligns the middle of the text with the anchor point.\n   * \"bottom\" aligns the bottom of the text with the anchor point.\n   */\n  vertical: \"top\" | \"middle\" | \"bottom\";\n\n  /**\n   * The horizontal alignment of the anchor point.\n   * \"left\" aligns the left side of the text with the anchor point.\n   * \"center\" aligns the center of the text with the anchor point.\n   * \"right\" aligns the right side of the text with the anchor point.\n   */\n  horizontal: \"left\" | \"center\" | \"right\";\n}\n\n/**\n * JSON representation of a [[TextAnnotation]].\n * @beta\n * @preview\n * @extensions\n */\nexport interface TextAnnotationProps {\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\n  orientation?: YawPitchRollProps;\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\n  textBlock?: TextBlockProps;\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\n  anchor?: TextAnnotationAnchor;\n}\n\n/** Arguments supplied to [[TextAnnotation.create]].\n * @beta\n * @preview\n * @extensions\n */\nexport interface TextAnnotationCreateArgs {\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\n  orientation?: YawPitchRollAngles;\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\n  textBlock?: TextBlock;\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\n  anchor?: TextAnnotationAnchor;\n}\n/**\n * Represents a formatted block of text positioned in 2d or 3d space.\n * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a TextAnnotation from which their geometric representation is generated.\n * @see [produceTextAnnotationGeometry]($backend) to decompose the annotation into a set of geometric primitives suitable for use with [[GeometryStreamBuilder.appendTextBlock]].\n * @beta\n * @preview\n * @extensions\n */\nexport class TextAnnotation {\n  /**\n   * The rotation of the annotation.\n   * @note When defining an annotation for a [TextAnnotation2d]($backend), only the `yaw` component (rotation around the Z axis) is used.\n   */\n  public orientation: YawPitchRollAngles;\n  /**\n   * The formatted document.\n   */\n  public textBlock: TextBlock;\n  /**\n   * Describes how the [[textBlock]]'s content should be aligned relative to the host element's origin.\n   */\n  public anchor: TextAnnotationAnchor;\n\n  private constructor(angles: YawPitchRollAngles, textBlock: TextBlock, anchor: TextAnnotationAnchor) {\n    this.orientation = angles;\n    this.textBlock = textBlock;\n    this.anchor = anchor;\n  }\n\n  /** Creates a new TextAnnotation. */\n  public static create(args?: TextAnnotationCreateArgs): TextAnnotation {\n    const angles = args?.orientation ?? new YawPitchRollAngles();\n    const textBlock = args?.textBlock ?? TextBlock.createEmpty();\n    const anchor = args?.anchor ?? { vertical: \"top\", horizontal: \"left\" };\n\n    return new TextAnnotation(angles, textBlock, anchor);\n  }\n\n  /**\n   * Creates a new TextAnnotation instance from its JSON representation.\n   */\n  public static fromJSON(props: TextAnnotationProps | undefined): TextAnnotation {\n    return TextAnnotation.create({\n      orientation: props?.orientation ? YawPitchRollAngles.fromJSON(props.orientation) : undefined,\n      textBlock: props?.textBlock ? TextBlock.create(props.textBlock) : undefined,\n      anchor: props?.anchor ? { ...props.anchor } : undefined,\n    });\n  }\n\n  /**\n   * Converts this annotation to its JSON representation.\n   */\n  public toJSON(): TextAnnotationProps {\n    const props: TextAnnotationProps = {};\n\n    // Even if the text block is empty, we want to record its style name and overrides, e.g.,\n    // so the user can pick up where they left off editing it next time.\n    props.textBlock = this.textBlock.toJSON();\n\n    if (!this.orientation.isIdentity()) {\n      props.orientation = this.orientation.toJSON();\n    }\n\n    if (this.anchor.vertical !== \"top\" || this.anchor.horizontal !== \"left\") {\n      props.anchor = { ...this.anchor };\n    }\n\n    return props;\n  }\n\n  /**\n   * @internal used by produceTextAnnotationGeometry; requires layoutRange computed by layoutTextBlock.\n   */\n  public computeDocumentTransform(layoutRange: Range2d): Transform {\n    const origin = this.computeAnchorPoint(layoutRange);\n    const matrix = this.orientation.toMatrix3d();\n\n    return Transform.createFixedPointAndMatrix(origin, matrix);\n  }\n\n  /** @internal */\n  public computeAnchorPoint(layoutRange: Range2d): Point3d {\n    let x = 0;\n    let y = 0;\n\n    switch (this.anchor.horizontal) {\n      case \"center\":\n        x += layoutRange.xLength() / 2;\n        break;\n      case \"right\":\n        x += layoutRange.xLength();\n        break;\n    }\n\n    switch (this.anchor.vertical) {\n      case \"middle\":\n        y -= layoutRange.yLength() / 2;\n        break;\n      case \"bottom\":\n        y -= layoutRange.yLength();\n        break;\n    }\n\n    return new Point3d(x, y, 0);\n  }\n\n  /** Returns true if this annotation is logically equivalent to `other`. */\n  public equals(other: TextAnnotation): boolean {\n    return this.anchor.horizontal === other.anchor.horizontal && this.anchor.vertical === other.anchor.vertical\n      && this.orientation.isAlmostEqual(other.orientation) && this.textBlock.equals(other.textBlock);\n  }\n}\n"]}
+{"version":3,"file":"TextAnnotation.js","sourceRoot":"","sources":["../../../src/annotation/TextAnnotation.ts"],"names":[],"mappings":"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","sourcesContent":["/*---------------------------------------------------------------------------------------------\r\n* Copyright (c) Bentley Systems, Incorporated. All rights reserved.\r\n* See LICENSE.md in the project root for license terms and full copyright notice.\r\n*--------------------------------------------------------------------------------------------*/\r\n/** @packageDocumentation\r\n * @module Annotation\r\n */\r\n\r\nimport { Point3d, Transform, XAndY, XYZProps, YawPitchRollAngles, YawPitchRollProps } from \"@itwin/core-geometry\";\r\nimport { TextBlock, TextBlockProps } from \"./TextBlock\";\r\n\r\n/** Describes how to compute the \"anchor point\" for a [[TextAnnotation]].\r\n * The anchor point is a point on or inside of the 2d bounding box enclosing the contents of the annotation's [[TextBlock]].\r\n * The annotation can be rotated and translated relative to the anchor point. The anchor point also serves as the snap point\r\n * when [AccuSnap]($frontend) is set to [SnapMode.Origin]($frontend).\r\n * @see [[TextAnnotation]] for a description of how the anchor point is computed.\r\n * @beta\r\n */\r\nexport interface TextAnnotationAnchor {\r\n  /**\r\n   * The vertical alignment of the anchor point.\r\n   * \"top\" aligns the anchor point with the top of the text's bounding box.\r\n   * \"middle\" aligns the anchor point with the middle of the text's bounding box.\r\n   * \"bottom\" aligns the anchor point with the bottom of the text's bounding box.\r\n   */\r\n  vertical: \"top\" | \"middle\" | \"bottom\";\r\n\r\n  /**\r\n   * The horizontal alignment of the anchor point.\r\n   * \"left\" aligns the anchor point with left side of the text's bounding box.\r\n   * \"center\" aligns the anchor point with center of the text with's bounding box.\r\n   * \"right\" aligns the anchor point with right side of the text's bounding box.\r\n   */\r\n  horizontal: \"left\" | \"center\" | \"right\";\r\n}\r\n\r\n/**\r\n * JSON representation of a [[TextAnnotation]].\r\n * @beta\r\n */\r\nexport interface TextAnnotationProps {\r\n  /** See [[TextAnnotation.offset]]. Default: [0, 0, 0]. */\r\n  offset?: XYZProps;\r\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\r\n  orientation?: YawPitchRollProps;\r\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\r\n  textBlock?: TextBlockProps;\r\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\r\n  anchor?: TextAnnotationAnchor;\r\n}\r\n\r\n/** Arguments supplied to [[TextAnnotation.create]].\r\n * @beta\r\n */\r\nexport interface TextAnnotationCreateArgs {\r\n  /** See [[TextAnnotation.offset]]. Default: (0, 0, 0). */\r\n  offset?: Point3d;\r\n  /** See [[TextAnnotation.orientation]]. Default: no rotation. */\r\n  orientation?: YawPitchRollAngles;\r\n  /** See [[TextAnnotation.textBlock]]. Default: an empty text block. */\r\n  textBlock?: TextBlock;\r\n  /** See [[TextAnnotation.anchor]]. Default: top-left. */\r\n  anchor?: TextAnnotationAnchor;\r\n}\r\n\r\n/**\r\n * Represents a formatted block of text positioned in 2d or 3d space.\r\n * [TextAnnotation2d]($backend) and [TextAnnotation3d]($backend) elements store a single TextAnnotation from which their geometric representation is generated.\r\n * Other types of elements may store multiple TextAnnotations, positioned relative to one another.\r\n * The annotation's position and orientation relative to the host element's [Placement]($common) is determined as follows:\r\n * - First, the width and height of a box enclosing the contents of the [[textBlock]] must be computed using [computeTextBlockExtents]($backend). This yields a box with the top-left\r\n * corner at (0, 0) and the bottom-right corner at (width, -height).\r\n * - Then, an \"anchor point\" is computed based on the text box and the [[anchor]] property. For example, if the annotation is anchored at the center-left, the anchor point will be (width/2, -height).\r\n * - The [[orientation]] is applied to rotate the box around the anchor point.\r\n * - Finally, the [[offset]] is added to the anchor point to apply translation.\r\n * @see [produceTextAnnotationGeometry]($backend) to decompose the annotation into a set of geometric primitives suitable for use with [[GeometryStreamBuilder.appendTextBlock]].\r\n * @beta\r\n */\r\nexport class TextAnnotation {\r\n  /** The rotation of the annotation.\r\n   * @note When defining an annotation for a [TextAnnotation2d]($backend), only the `yaw` component (rotation around the Z axis) is used.\r\n   */\r\n  public orientation: YawPitchRollAngles;\r\n  /** The formatted document. */\r\n  public textBlock: TextBlock;\r\n  /** Describes how to compute the [[textBlock]]'s anchor point. */\r\n  public anchor: TextAnnotationAnchor;\r\n  /** An offset applied to the anchor point that can be used to position annotations within the same geometry stream relative to one another. */\r\n  public offset: Point3d;\r\n\r\n  private constructor(offset: Point3d, angles: YawPitchRollAngles, textBlock: TextBlock, anchor: TextAnnotationAnchor) {\r\n    this.offset = offset;\r\n    this.orientation = angles;\r\n    this.textBlock = textBlock;\r\n    this.anchor = anchor;\r\n  }\r\n\r\n  /** Creates a new TextAnnotation. */\r\n  public static create(args?: TextAnnotationCreateArgs): TextAnnotation {\r\n    const offset = args?.offset ?? new Point3d();\r\n    const angles = args?.orientation ?? new YawPitchRollAngles();\r\n    const textBlock = args?.textBlock ?? TextBlock.createEmpty();\r\n    const anchor = args?.anchor ?? { vertical: \"top\", horizontal: \"left\" };\r\n\r\n    return new TextAnnotation(offset, angles, textBlock, anchor);\r\n  }\r\n\r\n  /**\r\n   * Creates a new TextAnnotation instance from its JSON representation.\r\n   */\r\n  public static fromJSON(props: TextAnnotationProps | undefined): TextAnnotation {\r\n    return TextAnnotation.create({\r\n      offset: props?.offset ? Point3d.fromJSON(props.offset) : undefined,\r\n      orientation: props?.orientation ? YawPitchRollAngles.fromJSON(props.orientation) : undefined,\r\n      textBlock: props?.textBlock ? TextBlock.create(props.textBlock) : undefined,\r\n      anchor: props?.anchor ? { ...props.anchor } : undefined,\r\n    });\r\n  }\r\n\r\n  /**\r\n   * Converts this annotation to its JSON representation.\r\n   */\r\n  public toJSON(): TextAnnotationProps {\r\n    const props: TextAnnotationProps = {};\r\n\r\n    // Even if the text block is empty, we want to record its style name and overrides, e.g.,\r\n    // so the user can pick up where they left off editing it next time.\r\n    props.textBlock = this.textBlock.toJSON();\r\n\r\n    if (!this.offset.isZero) {\r\n      props.offset = this.offset.toJSON();\r\n    }\r\n\r\n    if (!this.orientation.isIdentity()) {\r\n      props.orientation = this.orientation.toJSON();\r\n    }\r\n\r\n    if (this.anchor.vertical !== \"top\" || this.anchor.horizontal !== \"left\") {\r\n      props.anchor = { ...this.anchor };\r\n    }\r\n\r\n    return props;\r\n  }\r\n\r\n  /** Compute the transform that positions and orients this annotation relative to its anchor point, based on the [[textBlock]]'s computed bounding box.\r\n   * The anchor point is computed as specified by this annotation's [[anchor]] setting. For example, if the text block is anchored\r\n   * at the bottom left, then the transform will be relative to the bottom-left corner of `textBlockExtents`.\r\n   * The text block will be rotated around the fixed anchor point according to [[orientation]], then the anchor point will be translated by [[offset]].\r\n   * @param textBlockDimensions The width and height of the bounding box containing the text block. You can compute this using [computeTextBlockExtents]($common).\r\n   * @see [[computeAnchorPoint]] to compute the transform's anchor point.\r\n   */\r\n  public computeTransform(textBlockDimensions: XAndY): Transform {\r\n    const anchorPt = this.computeAnchorPoint(textBlockDimensions);\r\n    const matrix = this.orientation.toMatrix3d();\r\n\r\n    const rotation = Transform.createFixedPointAndMatrix(anchorPt, matrix);\r\n    const translation = Transform.createTranslation(this.offset);\r\n    return translation.multiplyTransformTransform(rotation, rotation);\r\n  }\r\n\r\n  /** Compute the anchor point of this annotation as specified by [[anchor]].\r\n   * @param textBlockDimensions The width and height of the bounding box containing the [[textBlock]]. You can compute this using [computeTextBlockExtents]($common).\r\n   * @see [[computeTransform]] to compute the transform relative to the anchor point.\r\n   */\r\n  public computeAnchorPoint(textBlockDimensions: XAndY): Point3d {\r\n    let x = 0;\r\n    let y = 0;\r\n\r\n    switch (this.anchor.horizontal) {\r\n      case \"center\":\r\n        x += textBlockDimensions.x / 2;\r\n        break;\r\n      case \"right\":\r\n        x += textBlockDimensions.x;\r\n        break;\r\n    }\r\n\r\n    switch (this.anchor.vertical) {\r\n      case \"middle\":\r\n        y -= textBlockDimensions.y / 2;\r\n        break;\r\n      case \"bottom\":\r\n        y -= textBlockDimensions.y;\r\n        break;\r\n    }\r\n\r\n    return new Point3d(x, y, 0);\r\n  }\r\n\r\n  /** Returns true if this annotation is logically equivalent to `other`. */\r\n  public equals(other: TextAnnotation): boolean {\r\n    return this.anchor.horizontal === other.anchor.horizontal && this.anchor.vertical === other.anchor.vertical\r\n      && this.orientation.isAlmostEqual(other.orientation) && this.offset.isAlmostEqual(other.offset)\r\n      && this.textBlock.equals(other.textBlock);\r\n  }\r\n}\r\n"]}