Update (#30)

* Update

* update

---------

Co-authored-by: zhe <[email protected]>

Author: ziyuhehe

docs/add-functionality/methods-and-properties.md

@@ -73,6 +73,8 @@ The `url` property refers to the full URL of the dashboard to be embedded. There
 1. Use `serverURL`, `configAppId`, `applicationID`, `objectID`, and `pageKey` properties.
 1. If the `configAppId` property is not provided, embedding SDK will build the URL using: `serverURL` + '/app/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`.
 1. Otherwise the URL will be: `serverURL` + '/app/' + 'config/' + `configAppId` + '/' + `applicationID` + '/' + `objectID` + '/' + `pageKey`.
+1. The `configAppId` refers to the application Id of the embeded dashboard.
+1. The `applicationID` refers to the project Id of the embeded dashboard.
 
 #### Required?
 

docs/embed-library-main-page/embed-library-properties.md

@@ -327,3 +327,36 @@ The detailed embedding behavior is below:
     - If you choose "Collapse toolbar by default" in the application settings, the navigation bar is collapsed at the start and is only expanded/visible when the user expands it manually.
 
     - If you don't choose "Collapse toolbar by default", the navigation bar is shown on the embedded report page.
+
+### `settings`
+
+#### Required?
+
+No
+
+#### Properties
+
+##### `reportConsumption`
+
+Use the `reportConsumption` object to customize the options on the report consumption page. The detailed properties contain:
+
+- `disableManipulationsAutoSaving`
+
+  - Disable the report instance manipulation auto saving or not.
+  - Default value: `false`.
+
+### `instance`
+
+Use this `instance` object to specify a report based dashboard instance for the embedded report. If you would like to make some manipulation to the report based dashboard instance before it is embedded, you can use this property, e.g., sorting a column. If the `instance` is used, the Embedding SDK will use it instead of creating a new report based dashboard instance.
+
+#### Required?
+
+No
+
+#### Properties
+
+- `mid` - This instance ID.
+
+#### Default value
+
+`null`

docs/embed-report-page/embed-report-properties.md

@@ -274,7 +274,9 @@ Here are some examples for the filter object in the `MstrDossier.applyFilter()`
 
 #### On-Page selectors
 
-To apply selections to on-page selectors, use the same input as chapter-level filters.
+##### Attribute Element Filter
+
+To apply selections on Attribute Element filter inside a page, use the same input as chapter-level filters.
 
 - Select the element list of the selector
 
@@ -326,6 +328,45 @@ To apply selections to on-page selectors, use the same input as chapter-level fi
   }
   ```
 
+##### Attribute/Metric Selector
+
+To apply selections on an Attribute/Metric selector inside a page, you can use the following input:
+
+- Select the object list of the selector
+
+  ```js
+  try {
+    await mstrDossier.applyFilter({
+      key: "W76",
+      currentSelection: {
+        objectItems: [
+          {
+            id: "<string>",
+            name: "<string>",
+          },
+        ],
+      },
+    });
+  } catch (error) {
+    // Your own error handling code
+  }
+  ```
+
+- Unset the selection of the selector
+
+  ```js
+  try {
+    await mstrDossier.applyFilter({
+      key: "W76",
+      currentSelection: {
+        selectionStatus: "unfiltered",
+      },
+    });
+  } catch (error) {
+    // Your own error handling code
+  }
+  ```
+
 #### Visualizations used as filters
 
 - Select attribute elements of the visualization

docs/images/information-window-limitations.png

@@ -0,0 +1,34 @@
+---
+title: Information Window
+description: Interactive contextual information display for visualizations
+---
+
+<Available since="StrategyJune 2025"/>
+
+## Overview
+
+The Information Window feature enhances data visualization interactivity by providing contextual details in a dynamic overlay. When a user clicks on a visualization element, a contextual window appears displaying additional information that is automatically filtered based on the selected element.
+
+## Implementation
+
+To implement the Information Window feature, please refer to the [MstrDossier API documentation](mstr-dossier.md) for the required parameters and implementation details.
+
+## Behavior Specifications
+
+### Size Management
+
+The Information Window automatically adjusts its dimensions based on the content and maintains the optimal width-to-height ratio consistent with MicroStrategyLibrary standards:
+
+![Information Window Size Adaptation](../images/information-window-size.png)
+
+### Positioning Logic
+
+The Information Window intelligently positions itself relative to the interaction point. When a user clicks on a visualization element, the window appears proximal to the click location while ensuring it remains fully visible within the viewport.
+
+## Technical Limitations
+
+The Information Window feature has specific compatibility constraints:
+
+![Information Window Compatibility Constraints](../images/information-window-limitations.png)
+
+Certain selector components and filtering mechanisms are not compatible with the Information Window rendering system. For optimal implementation, avoid using these unsupported configurations.

docs/images/information-window-size.png

@@ -17,13 +17,15 @@ The object returned from the `MstrEnvironment.loadDossier()` function, which all
 
 #### Input Parameters
 
-| Parameter Name     | Data Type   | Description                                                                                                                                                                                                                                                                                                                                                              | Is Required |
-| ------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
-| props              | Array       | This parameter cannot be empty. It describes the visualizations that must appear on the page. Each visualization must have a valid container. If you call `refresh()` for a second time, the visualizations rendered in the former `refresh()` call are destroyed first, then all the visualizations specified in the second `refresh()` call are shown on page by page. | true        |
-| props[i].key       | String      | The visualization key id.                                                                                                                                                                                                                                                                                                                                                | true        |
-| props[i].container | HTMLElement | The HTML element used for displaying the visualization. The HTML element must be in the current DOM tree of the client’s page. All elements must exist and cannot be in iframes. The `Node.contains()` function is used to determine this and is compatible with all browsers.                                                                                           | true        |
-| options            | Object      | An object containing optional parameters to control the behavior of the `refresh()` function.                                                                                                                                                                                                                                                                            | false       |
-| options.signal     | AbortSignal | An `AbortSignal` object that allows you to abort the refresh operation. This signal is typically created by an `AbortController` and can be used to cancel the operation by calling `AbortController.abort()` if needed.                                                                                                                                                 | false       |
+| Parameter Name             | Data Type   | Description                                                                                                                                                                                                                                                                                                                                                              | Is Required |
+| -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| props                      | Array       | This parameter cannot be empty. It describes the visualizations that must appear on the page. Each visualization must have a valid container. If you call `refresh()` for a second time, the visualizations rendered in the former `refresh()` call are destroyed first, then all the visualizations specified in the second `refresh()` call are shown on page by page. | true        |
+| props[i].key               | String      | The visualization key id.                                                                                                                                                                                                                                                                                                                                                | true        |
+| props[i].container         | HTMLElement | The HTML element used for displaying the visualization. The HTML element must be in the current DOM tree of the client's page. All elements must exist and cannot be in iframes. The `Node.contains()` function is used to determine this and is compatible with all browsers.                                                                                           | true        |
+| props[i].infoWindow        | Object      | An object that controls the information window behavior for the visualization.                                                                                                                                                                                                                                                                                           | false       |
+| props[i].infoWindow.enable | Boolean     | When set to `true`, enables the information window rendering for the visualization.                                                                                                                                                                                                                                                                                      | false       |
+| options                    | Object      | An object containing optional parameters to control the behavior of the `refresh()` function.                                                                                                                                                                                                                                                                            | false       |
+| options.signal             | AbortSignal | An `AbortSignal` object that allows you to abort the refresh operation. This signal is typically created by an `AbortController` and can be used to cancel the operation by calling `AbortController.abort()` if needed.                                                                                                                                                 | false       |
 
 #### Response
 
@@ -94,6 +96,37 @@ if (shouldAbortRefresh) {
 }
 ```
 
+With InfoWindow:
+
+```js
+try {
+  const environment = await microstrategy.embeddingComponent.environments.create({
+    serverUrl: "https://demo.microstrategy.com/MicroStrategyLibrary",
+    getAuthToken: () => {
+      // Logic similar to the existing Native Embedding SDK.
+    },
+  });
+  const dossier = await environment.loadDossier({
+    projectId: "B19DEDCC11D4E0EFC000EB9495D0F44F",
+    objectId: "D9AB379D11EC92C1D9DC0080EFD415BB",
+  });
+  // Begin here
+  const containerHtmlElement = document.getElementById("containerA");
+  await dossier.refresh([
+    {
+      key: "K66",
+      container: containerHtmlElement,
+      infoWindow: {
+        enable: true,
+      },
+    },
+  ]);
+  // Your own code after the visualizations are all loaded
+} catch (error) {
+  // Add your own handling logic here
+}
+```
+
 #### API Errors
 
 | Error Case                                                                                               | Error Category | Handling Module      | Error Handling                                                                                                                 |
@@ -107,6 +140,7 @@ if (shouldAbortRefresh) {
 | A container is occupied by other dossiers                                                                | Invalid input  | Native Embedding SDK | Caught by the `catch()` of the promise object                                                                                  |
 | Other REST API errors                                                                                    | Other          | Native Embedding SDK | Caught by the `catch()` of the promise object                                                                                  |
 | The key is the visualization key of the visualization in the panel                                       | Invalid input  | Native Embedding SDK | console err message in console "The visualization `${VisualizationKey}` is a visualization in a panel, which isn't supported." |
+| Info window is not found for the specified visualization key                                             | Invalid input  | Native Embedding SDK | Console error message: `Info window is not found for visualization key:${vizKey}.`                                             |
 | Object you pass to AbortController.abort(), or `AbortError: signal is aborted without reason` otherwise. | Abort Error    | Native Embedding SDK | Caught by the `catch()` of the promise object                                                                                  |
 
 ### The get information API

docs/native-embedding-architecture/apply-filter.md

@@ -0,0 +1,140 @@
+---
+title: Library OAuth2 authentication APIs
+description: Describes the Embedding SDK APIs that is available for Library OAuth2 authentication.
+---
+
+To simplify the [Library OAuth2](https://doc-dev.microstrategy.com/producthelp/2021/Workstation/en-us/Content/oauth2.htm) login workflow, we expose new APIs
+
+`microstrategy.auth.oauthLogin(serverUrl, options)`
+
+`microstrategy.auth.oauthRefreshToken(serverUrl, options)`
+
+The details of those new APIs are as below:
+
+### `microstrategy.auth.oauthLogin(serverUrl, options)`
+
+#### Description
+
+This API can be used to start the Library OAuth2 login workflow on the embedding scenario.
+
+#### Input Parameters
+
+- `serverUrl` (`string`):  
+  The URL of a Library server that has been successfully configured with OAuth2.
+
+- `options` (`OAuth2LoginOptions`):  
+  An object containing the following fields:
+
+  - `clientId` (`string`):  
+    The client identifier issued by the authorization server during OAuth2 client registration.
+  - `clientSecret` (`string`, optional):  
+    The client secret corresponding to the clientId, used to authenticate the client with the authorization server.
+
+    If provided together with `requireRefreshToken: true`, a refresh token will be issued as part of the login response.
+
+  - `requireRefreshToken` (`boolean`, optional):  
+    Specifies whether a refresh token should be requested during login.
+
+    Only takes effect if `clientSecret` is provided.
+
+    If true, both an access token and a refresh token will be returned.
+
+    If false (or omitted), only an access token will be returned.
+
+#### Return type
+
+Returns a `Promise` that resolves to an object containing the following fields:
+
+```ts
+{
+  accessToken: string;
+  refreshToken?: string;
+}
+```
+
+- accessToken: The OAuth2 access token for authenticating subsequent requests.
+- refreshToken (optional): The refresh token that can be used to obtain a new access token when the
+  current one expires.
+
+#### Example
+
+```js
+microstrategy.embeddingContexts.embedLibraryPage({
+  serverUrl: "{YOUR_LIBRARY_SERVER_URL}",
+  placeholder: document.getElementById("LibraryHomePageContainer"),
+  enableCustomAuthentication: true,
+  customAuthenticationType: microstrategy.dossier.CustomAuthenticationType.AUTH_TOKEN,
+  getLoginToken: async () => {
+    const data = await microstrategy.auth.oauthLogin("{YOUR_LIBRARY_SERVER_URL}", {
+      clientId: "{YOUR_OAUTH2_CLIENT_ID}",
+      clientSecret: "{YOUR_OAUTH2_CLIENT_SECRET}",
+      requireRefreshToken: true,
+    });
+    return data.accessToken;
+  },
+});
+```
+
+### `microstrategy.auth.oauthRefreshToken(serverUrl, options)`
+
+#### Description
+
+This API allows obtaining a new access token using a previously acquired refresh token.
+
+#### Input Parameters
+
+- `serverUrl` (`string`):  
+  The URL of a Library server that has been successfully configured with OAuth2.
+
+- `options` (`OAuth2RefreshTokenOptions`):  
+  An object containing the following fields:
+
+  - `clientId` (`string`):  
+    The client identifier issued by the authorization server during OAuth2 client registration.
+
+  - `clientSecret` (`string`):  
+    The client secret corresponding to the clientId, used to authenticate the client with the authorization server.
+
+  - `refreshToken` (`string`):  
+    The refresh token that was previously obtained during login.
+
+#### Return type
+
+Returns a `Promise` that resolves to an object containing the following fields:
+
+```ts
+{
+  accessToken: string;
+  refreshToken: string;
+}
+```
+
+- accessToken: The OAuth2 access token for authenticating subsequent requests.
+- refreshToken: The refresh token that can be used to obtain a new access token when the
+  current one expires.
+
+#### Example
+
+```js
+const data = await microstrategy.auth.oauthRefreshToken("{YOUR_LIBRARY_SERVER_URL}", {
+  clientId: "{YOUR_OAUTH2_CLIENT_ID}",
+  clientSecret: "{YOUR_OAUTH2_CLIENT_SECRET}",
+  refreshToken: "{YOUR_REFRESH_TOKEN}",
+});
+const { accessToken } = data;
+const { refreshToken } = data;
+```
+
+#### API errors
+
+This API would have the wrong behavior or report an error in the cases below:
+
+- When `serverUrl` is not a Library server that supports OAuth2 login.
+- If you receive a `HTTP Status 400 - Bad Request` response, ensure that the redirectUrl is [correctly configured](https://doc-dev.microstrategy.com/producthelp/2021/Workstation/en-us/Content/config_oauth2.htm). The expected format for the redirectUrl is: `YOUR_LIBRARY_SERVER_URL/static/embedding/auth-end.html?origin=YOUR_EMBEDDING_ORIGIN` and Make sure to replace:
+
+  - `YOUR_LIBRARY_SERVER_URL` with the actual Library server URL.
+  - `YOUR_EMBEDDING_ORIGIN` with the origin of the embedding application. For example, if your embedding page URL is `https://example.com:8443/path/demo.html`, then the origin is `https://example.com:8443`.
+
+- When the client application can't get the Strategy login window because of
+  [COOP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Opener-Policy)
+  setting is too strict.