Merge pull request #224 from AdobeXD/xd-30-docs

XD 30 docs changes

Author: krice-nw

changes.md

@@ -1,5 +1,17 @@
 # Change Log
 
+XD Release 30.0.12 (June 2020)
+-------------------------------------
+
+### New features
+* **Scrollable Groups** -- Plugins will see a new [ScrollableGroup](./reference/scenegraph.md#ScrollableGroup) node type and can read the scroll direction(s) and viewport size. Plugins cannot yet create a ScrollableGroup or modify its viewport, however.
+
+### Known Issues
+* **Content Aware Stacks** -- Some plugin actions, such as changing a node's position or its Responsive Resize constraints, may be ignored or behave unexpectedly when the node's parent is a Group with Stack layout enabled. Plugins cannot yet create, read, or modify Stack layout settings on a Group.
+
+* MouseEvent `clientX`/`clientY` and `offsetX`/`offsetY` values are incorrect (and always have been) -- these values will probably change in the _next_ XD release, so do not rely on them.
+
+
 XD Release 29.0.32 (May 2020)
 -------------------------------------
 
@@ -34,7 +46,7 @@ Bug fixes:
 
 ### Known Issues
 
-* MouseEvent `clientX`/`clientY` and `offsetX`/`offsetY` values are incorrect (and always have been) -- these values will probably change in the _next_ XD release.
+* MouseEvent `clientX`/`clientY` and `offsetX`/`offsetY` values are incorrect (and always have been) -- these values will change in a near-future XD release, so do not rely on them.
 
 ### Plugin submission process
 

reference/core/automatic-cleanups.md

@@ -14,3 +14,7 @@ To make writing your plugin simpler, XD performs a number of automated cleanups
 
 * **Repeat Grid cell syncing** - Most changes you make inside a Repeat Grid cell are automatically mirrored to all its other cells, except for certain properties
   such as text and images which XD permits to vary between grid cells.
+
+* **Content-Aware Group & Stack layout updates** -- The background layer (if any) of a Content-Aware Group will update automatically after a plugin changes the
+  size or position of its contents. Similarly, changing a node inside a Group with Stack layout will automatically slide its adjacent siblings to preserve a
+  constant margin around the node. These changes do not occur until after the plugin command finishes.

reference/scenegraph.md

@@ -63,6 +63,7 @@ function myCommand(selection) {
     * [Group](#Group)
     * [SymbolInstance](#SymbolInstance)
     * [RepeatGrid](#RepeatGrid)
+    * [ScrollableGroup](#ScrollableGroup)
     * [LinkedGraphic](#LinkedGraphic)
     * [RootNode](#RootNode)
 
@@ -534,7 +535,7 @@ True if the node should be included in the output of _File > Export > Batch_ and
 **Since**: XD 19
 
 True if the node stays in a fixed position while the Artboard's content is scrolling (when viewed in an interactive prototype).
-_Only applicable for nodes whose immediate parent is an Artboard._
+_Only applicable for nodes whose immediate parent is an Artboard_ -- this does not apply to content inside a ScrollableGroup!
 
 For other nodes, this property returns undefined and cannot be set. To determine whether those nodes scroll or remain
 fixed, walk up the parent chain and check this property on the topmost ancestor in the Artboard.
@@ -866,6 +867,10 @@ Groups and other containers cannot be created directly using scenenode construct
 scenegraph (you can't add subtrees all at once) nor can you add an empty Group and then add children to it (can't add nodes outside
 the scope of the current _edit context_). Instead, to create Groups and other nested structures, use [commands](commands.md).
 
+Plain Groups (as well as some other node types, like SymbolInstances) can have dynamic layout features enabled such as padding and
+stack layouts. These are sometimes referred to as Content-Aware Groups or Stack containers, but ultimately these appear in the API as
+plain Group nodes. They do not carry the same edit-context restrictions as Masked Groups or other special node types.
+
 In a Mask Group, the mask shape is included in the group's `children` list, at the top of the z order. It is not visible - only its
 path outline is used, for clipping the group.
 
@@ -976,6 +981,8 @@ complete list). Attempting to set this property on such node types results in an
 ### group.mask : ?[<code>SceneNode</code>](#SceneNode)
 The mask shape applied to this group, if any. This object is also present in the group's `children` list. Though it has no direct visual appearance of its own, the mask affects the entire group's appearance by clipping all its other content.
 
+The `localBounds`, `globalBounds`, and `globalDrawBounds` of a Masked Group are based on the bounds of the mask shape alone, regardless of whether the content is larger than the mask or even if the content doesn't fill the mask area completely.
+
 **Kind**: instance property of [<code>Group</code>](#Group)
 **Read only**: true
 
@@ -2189,6 +2196,56 @@ You can call this API from either of _two different edit contexts_:
 
 * * *
 
+<a name="ScrollableGroup"></a>
+
+## ScrollableGroup
+**Since:** XD 30
+**Kind**: class
+**Extends**: [<code>SceneNode</code>](#SceneNode)
+
+ScrollableGroup nodes are content that users can interactively scroll around. Content is viewed through a [viewport](#ScrollableGroup-viewport),
+with everything else clipped. If a ScrollableGroup is set to only scroll on one axis, on the other axis the viewport is
+automatically sized to exactly fit the bounds of the content so nothing is clipped.
+
+The scroll distance range is defined by a _scrollable area_ rectangle which is the union of the viewport and the bounds of all
+the content. This can include some blank space, if the content is initially positioned not filling the entire viewport.
+
+* [ScrollableGroup](#ScrollableGroup)
+    * [.scrollingType](#ScrollableGroup-scrollingType) : <code>string</code>
+    * [.viewport](#ScrollableGroup-viewport) : <code>{! {viewportWidth: number, offsetX: number} | {viewportHeight: number, offsetY: number} |
+         {viewportWidth: number, offsetX: number, viewportHeight: number, offsetY: number} }</code>
+
+* * *
+
+<a name="ScrollableGroup-scrollingType"></a>
+
+### ScrollableGroup.scrollingType : <code>string</code>
+The type of scrolling: one of ScrollableGroup.VERTICAL, HORIZONTAL and PANNING.
+        PANNING enables scrolling on both axes.
+
+**Kind**: instance property of [<code>ScrollableGroup</code>](#ScrollableGroup)
+
+* * *
+
+<a name="ScrollableGroup-viewport"></a>
+
+### ScrollableGroup.viewport : <code>!{viewportWidth: number, offsetX: number} | {viewportHeight: number, offsetY: number} | {viewportWidth: number, offsetX: number, viewportHeight: number, offsetY: number}}</code>
+The viewport is a rectangle whose bounds are defined explicitly on scrolling axes and fit automatically to the
+content on non-scrolling axes:
+* On a scrolling axis, the bounds are specified in [local coordinates](/reference/core/coordinate-spaces-and-units.md)
+using the `viewport` values specified here.
+* On a non-scrolling axis, the bounds are automatically calculated to exactly fit the content (just like the blue
+selection rectangle seen when you select a plain Group).
+
+For example, if scrollingType == VERTICAL, the top of the viewport is `viewport.offsetY` in the ScrollableGroup's
+local coordinates, the bottom of the viewport is `viewport.offsetY + viewport.viewportHeight` in local coordinates,
+and horizontally there is no viewport clipping -- the entire current [localBounds](#SceneNode-localBounds) range is visible. The
+`viewport` object will only contain `offsetY` and `viewportHeight` properties in this case.
+
+**Kind**: instance property of [<code>ScrollableGroup</code>](#ScrollableGroup)
+
+* * *
+
 <a name="LinkedGraphic"></a>
 
 ## LinkedGraphic