1.2 Alpha Channel initial documentation changes

docs/changelog.md

@@ -5,17 +5,51 @@ description: Deneb Change Log - high-level details of new features and fixes for
 
 # Change Log
 
-:::caution Potential Upcoming "Breaking" Changes
-We are intending to implement cross-highlight support in an upcoming release (likely 1.2 or 1.3). Deneb will currently always apply the **filter** interaction by default (unless you have specified differently in your report configuration).
+## 1.2.0 (Alpha Channel)
 
-Much like [Cross-Filtering](interactivity-selection), Cross-Highlight will be opt-in from a specification perspective. However, if you don't have your [interactions set to cross-filter](https://docs.microsoft.com/en-us/power-bi/create-reports/service-reports-visual-interactions#change-the-interaction-behavior), Power BI will try to apply the **highlight** interaction and this will make your visual appear to do nothing when filtered by other visuals.
+[Refer here for information on how to work with early access builds](/community/early-access).
 
-When this functionality is delivered, it is recommended that you ensure any Deneb visuals are explicitly set to **filter** or **no impact** accordingly.
+### Cross-Highlighting Support (#134)
+
+To date, Deneb has only had two supported [interactions](https://docs.microsoft.com/en-us/power-bi/create-reports/service-reports-visual-interactions#change-the-interaction-behavior) from other visuals: **Filter** (default) and **None**.
+
+In this version, we have enabled support for the **Highlight** interaction. Much like [Cross-Filtering](interactivity-selection), it is opt-in - as you will need to ensure that marks have the necessary encodings for orginal vs. highlight values for any active interactions, e.g.:
+
+![Cross-Highlight functionality can now be leveraged, so you can bind encodings for original and highlight values.](/img/changelog/1.2.0/cross-highlight-example.gif "Cross-Highlight functionality can now be leveraged, so you can bind encodings for original and highlight values.")
+
+To see more about how you can get started, please check out the [Cross-Highlighting](interactivity-highlight) page for details. The **Simple Bar Chart** template for both Vega and Vega-Lite has been updated with a sample binding and encoding (as well as the [Simple Worked Example](simple-example)).
+
+:::caution Check Default Interactions
+Because this change affects the dataset that the main window sends to a visual, this may make your visuals appear differently that prior to the update if your default interaction is set to **Highlight** (as this is now an option on a Deneb visual when setting interactions). We do try our best to manage this in Deneb if not, but it is recommended that you do this the "Power BI way" and explicitly set interactions to **Filter**.
 :::
 
-## 1.2.0 (Alpha & Beta Channels)
+### Improved Visibility of Vega Versions (#185)
+
+Because Deneb embeds the Vega and Vega-Lite libraries, any new releases are not automatically available to you; these need to be packaged, tested and published via AppSource. As such, there can be a lag between what Deneb supports and any language features in the Vega or Vega-Lite documentation. A good example of this was Vega-Lite 5.2.0 releasing very shortly after Deneb 1.0.0 went live.
+
+To assist with checking compatability of the embedded runtimes vs. their documentation, we previously included the embedded Vega and or Vega-Lite versions on the landing page. However once you began editing your visual, this became hard to (re) discover. To assist with this, the version of the selected language provider is now displayed in the Preview Area toolbar, e.g.:
+
+![The current runtime version is now shown in the Visual Editor toolbar.](/img/changelog/1.2.0/preview-toolbar-vega-version.png "The current runtime version is now shown in the Visual Editor toolbar.")
+
+### Recalculate During Resize (#180)
+
+Due to the dynamic nature of Power BI visual containers, any change to the sizing can trigger an update to a visual's logic and this can cause your visual specification to get re-calculated during the process. This may not be noticeable for visuals that use a small amount of marks, but for those that are more complex, this might create more overhead than you need for something you don't do frequently.
+
+To assist with this, a **Performance Tuning** property menu has been made available, with the option to toggle **Recalculate during resize**. When version 1.2.0 becomes active, the default for this property is **OFF**, which means that Deneb will delay any further calculations until you have finished resizing your visual, e.g.:
+
+![recalculate-during-resize.gif.](/img/changelog/1.2.0/recalculate-during-resize.gif "Our raincloud plot example contains many data points and calculations, which can be computationally expensive if resizing the visual container. By turning off the 'Recalculate during resize' property, you can delay any calculations until you have finished resizing your visual.")
+
+The documentation for this feature has also been added to the [Performance Considerations](performance#recalculate-during-resize) page.
+
+### Other Minor Enhancements
+
+- Deneb will now persist the visual container size, as viewed in the report as of the last change. This means that if Deneb is re-initialized while the Visual Editor is open (e.g. by changing to another visual and back again), then it won't "forget" the size of the visual as viewed normally (#178).
+
+### Bugs Fixed
 
-1.2.0 changes will be documented as new alpha and beta builds are made available.
+- Exported templates cannot be re-imported without manual corrections (#198)
+- Specification Field Mapping will replace property keys if they match a dataset field name (#190)
+- If using `"tooltip": false` against a Vega-Lite mark (instead of omitting the `tooltip` property), an empty tooltip would be displayed (#191)
 
 ## 1.1.0 (2022-01-22)
 

docs/deeper-concepts/performance-considerations.md

@@ -50,3 +50,18 @@ Any data that you add to the visual will have performance implications, specific
 - Creating a row context with lower granularity than you actually need, which can make producing the desired output more challenging.
 
 Therefore, only add the columns and measures (and filter context) that your visual needs to communicate its message.
+
+## The Performance Tuning Property Menu
+
+The **Performance Tuning** menu in the Power BI format pane is used to expose additional properties that you can use to alter performance of your specification. Where possible, these properties are set to what makes the most sense for optimal performance.
+
+### Recalculate During Resize
+
+:::info OFF By Default
+:::
+
+Due to the dynamic nature of Power BI visual containers, any change to the sizing can trigger an update to a visual's logic and this can cause your visual specification to get re-calculated during the process. This may not be noticeable for visuals that use a small amount of marks, but for those that are more complex, this might create more overhead than you need for something you don't do frequently.
+
+If enabled, the **Recalculate during resize** property will continue to calculate any changes to the specification while a visual is in the process of being resized. If disabled, Deneb will delay any further updates until you have completed the resize operation by releasing the mouse button, e.g.:
+
+![recalculate-during-resize.gif.](./img/recalculate-during-resize.gif "Our raincloud plot example contains many data points and calculations, which can be computationally expensive if resizing the visual container. By turning off the 'Recalculate during resize' property, you can delay any calculations until you have finished resizing your visual.")

docs/getting-started/visual-editor.md

@@ -39,7 +39,26 @@ Your visual may not fit entirely into the preview area at 100% scale, so you can
 
 If you would prefer to not see the boundary marker, you can disable this in the properties pane by selecting **Editor > Show Boundary Marker > OFF** in the Power BI Format pane:
 
-![The Show Boundary Marker property in the Format pane.](./img/boundary-marker.png "The Show Boundary Marker property in the Format pane.")
+![The Show Boundary Marker property in the Format pane.](./img/boundary-marker.png "The Show Boundary Marker property in the Format pane.
+")
+
+#### Toolbar
+
+![The preview area toolbar, in the bottom-right of the Visual Editor's preview pane.](./img/preview-area-toolbar.png "The preview area toolbar, in the bottom-right of the Visual Editor's preview pane.")
+
+The preview area also contains a toolbar, which provides additional controls to assist with detail work. From left to right these are:
+
+- Specification provider and version.
+
+  :::tip Check the Provider Version Can Do What You're Looking Up
+  Deneb doesn't automatically support new releases of Vega or Vega-Lite. Because the runtimes are embedded, any new releases need to be be tested, implemented and deployed to AppSource, which can take some time. As such, you can use this information in the toolbar to confirm if the embedded version might be behind any new features published by the Vega team.
+  :::
+
+- Zoom preview out by 10% **( Ctrl + Alt + - )**
+- Zoom level slider - allows manual adjustment of zoom level from 10% to 300%.
+- Zoom preview out by 10% **( Ctrl + Alt + + )**
+- Zoom preview to actual size **( Ctrl + Alt + 0 )**
+- Zoom preview to fit available space **( Ctrl + Alt + \* )**
 
 ### Editor Pane Position
 
@@ -184,19 +203,7 @@ This dialog is also displayed by default if this is the first time opening the V
   - Please refer to the [Performance Considerations](performance#selection-of-renderer) page for further details on potential risks and mitigation approaches when it comes to selecting a renderer.
 - The **Vega > Power BI Interactivity** section specifies which interactivity features to enable.
   - As these require some additional setup in your specification, as well as some internal logic to link everything together you are able to specify whether they should be set-up or not.
-  - Please refer to the [Interactivity Features](interactivity-overview) and related pages ([Tooltips](interactivity-tooltips) | [Context-Menu](interactivity-context-menu) | [Cross-Filtering](interactivity-selection)) for further details on how to configure these for your specification.
-
-### The Preview Area Toolbar
-
-![The preview area toolbar, in the bottom-right of the Visual Editor's preview pane.](./img/preview-area-toolbar.png "The preview area toolbar, in the bottom-right of the Visual Editor's preview pane.")
-
-The preview area contains a toolbar, which provides additional controls to assist with detail work. From left to right these are:
-
-- Zoom preview out by 10% **( Ctrl + Alt + - )**
-- Zoom level slider - allows manual adjustment of zoom level from 10% to 300%.
-- Zoom preview out by 10% **( Ctrl + Alt + + )**
-- Zoom preview to actual size **( Ctrl + Alt + 0 )**
-- Zoom preview to fit available space **( Ctrl + Alt + \* )**
+  - Please refer to the [Interactivity Features](interactivity-overview) and related pages ([Tooltips](interactivity-tooltips) | [Context-Menu](interactivity-context-menu) | [Cross-Filtering](interactivity-selection) | [Cross-Highlighting](interactivity-highlight)) for further details on how to configure these for your specification.
 
 ## Column and Measure Completion