Documentation polish pass for XD 21:

- Reformat changelog
- Wordsmithing for application.editDocument(), handlers.md, panel API docs,
  menu item naming/structure docs
- Rename naming.md -> menu-structure.md (plus wordsmithing)
- Update lifecycle.md docs for plugin panels
- Fix inconsistent create/show/hide strategy in panels/index.md sample code
- Call out more directly the two main strategies for panel create/hide (in
  panels/show.md, plus link from panels/index.md)
- Simplify diffs in application.md

Author: peterflynn

changes.md

@@ -2,50 +2,59 @@
 
 ## XD Release 21.0.12 (July 2019)
 
-### UI Changes
+XD 21 adds major updates: the ability to **show panel UI**, and the much-improved **UXP 3 CSS & layout engine**.
 
-* Display changes should no longer cause random crashes.
-* Plugins can now display persistent UI in the plugin panel. More information: [Panel Quick Start](./tutorials/quick-start-panel/index.md), [Migrating from Modals to Panels](./tutorials/how-to-migrate-from-modal-to-panel/index.md), [Panel Reference](./reference/ui/panels/index.md).
+_The new layout engine likely constitutes a **breaking change** for any plugin with UI_ -- read below for details.
 
-### XD API Changes
+### Plugin Panel UI
 
+* Plugins can now display UI persistently in a side panel. More information:
+    * [How to define a panel](./reference/structure/handlers.md#panel)
+    * [Panel overview / reference](./reference/ui/panels/index.md)
+    * [Panel Quick Start tutorial](./tutorials/quick-start-panel/index.md)
+    * [Migrating from dialogs to panels](./tutorials/how-to-migrate-from-modal-to-panel/index.md).
 * A new default stylesheet is provided for plugin UI that renders inside a plugin. This means that UI that renders in one manner in a modal dialog may not render in the same exact manner in a panel.
-* Default styles are now easier to override as the specificity in the default stylesheet has been reduced.
-
 
-### UXP API Changes
+### UXP 3 HTML/CSS changes
 
-UXP provides several common APIs to XD, including File I/O, Networking, and the User Interface layer. XD 21 now ships with version 3.1 , and as such, there are lots of new features you can take advantage of. In order to gain access to these features, your plugin must _opt-in_ to the UXP 3.1 layout by changing the `host.minVersion` key in the `manifest.json`:
+In order to gain access to most of these features, your plugin must _opt-in_ to the UXP 3.1 layout engine by changing the `minVersion` in your `manifest.json`:
 
-```js
-{
+```json
     "host": {
         "minVersion": "21.0"
     }
-}
 ```
 
 > **NOTE:** Without this change, your plugin will run in [backwards-compatibility mode](./migrations/uxp-2-to-3.md).
 
-* **Inline layout**. This means you now have the ability to write code like `<p>This is <a href="...">a link</a></p>` and have the link render _inline_ with the rest of the text. This is **huge**, but it can also create a tremendous impact on your plugin's layout as _the default layout for an HTML element_ now more closely aligns with the Web specification. This means that `span` elements will render with `inline`, `button`s will render as `inline-block`, etc. This means that some elements may no longer render as they did in the previous version of UXP.
-* **CSS Variables**. You can now use CSS variables to help apply themes and other layout to your plugin.
-* **`calc`**. You can use `calc` to calculate lengths in your CSS. For example, `width: calc(100% - 9px)`. Note that you can mix units, just like you can on the web.
-* **Units**! The previous version of UXP understood `px` and `%`, but this version understands nearly all of them. You can use `rem`, `em`, `px`, `pt`, `vh`, `vw`, `cm`, `in`, etc. **NOTE:** If you previously didn't specify units in your CSS, you should start. Values (other than `0`) without units will be ignored.
-* **Fixed positioning**. `position: fixed` is now technically supported, but _should not be used in panels_. It can be used in dialogs to anchor your element to a fixed position in its container, regardless of scrolling position. This is most useful for plugins that want to live within a panel. **KNOWN ISSUE:** Do not use in panels, as it is possible for a plugin to partially escape the normal bounds of a panel when using `position: fixed`. This will be addressed in the future, but the fix **will break** your plugins in the future.
-* **z-index**. You can now stack your element using `z-index`.
-* **Additional property values**: The CSS parser now understands `initial`, `unset`, and `inherit`. You can also use `!important` to override styles (although you should use this as a last resort).
-* **Linear gradient support**: You can now use the CSS syntax for linear gradients.
-* **Outline support**: You can assign an outline to your elements with the `outline` rule.
-* **object-fit**: You can use `object-fit` to better control the size of images and other elements,.
-* **New pseudo-selectors**: `:lang` and `:focus` are now available.
-* **Tab index, v1**: Setting `tab-index` to `0` will now cause any element to be focusable. You can **not** yet control the tab order.
-* **Improved default for `overflow`**: `overflow` now defaults to `visible`, not `hidden`, as per the web specification.
-
+* **Layout engine**
+    * **Inline layout** -- You now have the ability to write code like `<p>This is <a href="...">a link</a></p>` and have the link render _inline_ with the rest of the text
+    * **Layout now defaults to inline** (no longer flexbox) -- This has a tremendous impact on pre-existing plugin UI code: now `span` elements will render with `inline`, `button`s will render as `inline-block`, etc.
+    * **`overflow` defaults to `visible`** (no longer `hidden`), as per the web specification
+    * `object-fit` -- to control the size of images
+    * `z-index`
+* **SVG UI elements**
+* **New UI controls**
+    * Radio buttons -- `<input type="radio" />`
+    * Progress bars & spinners -- `<progress>`
+* **CSS improvements**
+    * `linear-gradient()`
+    * `outline`
+    * More units! -- UXP now understands `rem`, `em`, `px`, `pt`, `vh`, `vw`, `cm`, `in`, etc. **NOTE:** UXP will now start ignoring values (other than `0`) that don't specify any units, which can break older plugin UI code.
+    * CSS Variables -- easily apply themes and other layout to your plugin.
+    * More pseudo-selectors -- `:lang` and `:focus`
+    * `calc()` -- For example, `width: calc(100% - 9px)`. Note that you can mix units, just like you can on the web.
+    * Inheritance -- The CSS parser now understands `initial`, `unset`, and `inherit`. You can also use `!important` to override styles (although you should use this as a last resort).
+    * Default styles are now easier to override as the specificity in the default stylesheet has been reduced.
+* _Basic_ **Tab index** support: Setting `tab-index` to `0` will now cause any element to be focusable. You can **not** yet control the tab order.
 
 ### Known Issues
 
 See the [Known Issues page](./known-issues.md) for a comprehensive list of existing known issues.
 
+
+----
+
 ## XD Release 20.0.12 (June 2019)
 
 ### UI Changes

known-issues.md

@@ -2,9 +2,7 @@
 
 ## General Issues
 
-- When TABbing between controls on the XD Start page, focus may appear to be lost. It isn't, and continued TABbing will refocus the editable controls.
-- Some icons may be blurry in the plugin panel. Be sure to include 24px, 48px, 96px, 144px, and 192px in your plugin bundle and manifest.
-- Some icons may be missing in the plugin panel. This is the case if no icons are specified in your plugin's manifest.
+- Icons may be blurry or missing in the plugin panel if you don't include the full set of 24px, 48px, 96px, 144px, and 192px sizes in your plugin bundle and manifest.
 - Developer/Side-loading Specific
   - Plugin menus and handlers may not be in-sync across documents during development
     - If someone modifies a plugin's files on disk while XD is running, and then opens more windows in XD, any windows that were open before reflect the old version of the plugin while windows that were opened later reflect the new version of the plugin. The menu bar will always reflect the old version of the plugin regardless of which window is current.
@@ -32,7 +30,7 @@
 - It is not possible to trigger the emoji selector in a text field on macOS.
 - Many SVGs are known to render in odd ways in the UI. These issues will be addressed in the future, but we would love to hear your reports of any SVGs that don't work, and how you fixed it.
 - When tabbing in a scroll view, the scroll view is not automatically scrolled to ensure the target control is in view (macOS Only).
-- When using `<input type="radio" />`, be sure to include a `name` attribute if you want radio buttons to be exclusive. If you forget, you'll get different behavior on macOS and Windows 10. On macOS, radio buttons will not be exclusive to each other just because they are in the same container, whereas on Windows 10, radio buttons _will_ be exclusive within the same container. As such, you should _always_ use `name` to determine radio button exclusivity.
+- When using `<input type="radio" />`, be sure to include a `name` attribute. If you forget, you'll get different behavior on macOS and Windows 10. On macOS, radio buttons will not be exclusive to each other just because they are in the same container, whereas on Windows 10, radio buttons _will_ be exclusive within the same container. As such, you should _always_ use `name` to determine radio button exclusivity.
 - Emojis are rendered in the font color on Windows 10, instead of using the emoji's colors.
 - When a control in a panel is disabled and enabled, it is no longer reachable via TAB. This may also impact controls added *after* a panel is shown for the first time.
 

migrations/index.md

@@ -1,6 +1,6 @@
 # How to migrate from modal to panel
 
-Are you interested in converting your modal plugin to a panel plugin? Keep in mind that not every modal plugin is a good fit for this change. If you are curious about what differences exist, take a look at the docs for each UI entrypoint:
+Are you interested in converting your plugin's modal dialog box UI into a panel UI? Keep in mind that not every modal dialog flow is a good fit for this change. If you are curious about what differences exist, take a look at the docs for each UI entrypoint:
 
 - [Modal dialogs](/reference/ui/dialogs/index.md)
 - [Panels](/reference/ui/panels/index.md)
@@ -20,7 +20,7 @@ The complete example can be found in [our Samples repository](https://github.com
 
 ## Development Steps
 
-We are going to take a look at a sample plugin that lets users increase the width and height of the selected rectangle by inputing pixel values in the UI. As you can imagine, this process would be more efficient for the user if the plugin provided UI in a panel.
+We are going to take a look at a sample plugin that lets users increase the width and height of the selected rectangle by inputting pixel values in the UI. As you can imagine, this process would be more efficient for the user if the plugin provided UI in a panel.
 
 Let's see what this plugin will look like before and after:
 
@@ -82,7 +82,7 @@ As you can see, `host.minVersion` is changed to `21.0` since `21.0` is the earli
 
 ### 3. Understand the new structure of `main.js`
 
-A modal plugin needs one function to be exported:
+A modal-dialog command needs one function to be exported:
 
 ```js
 function enlargeRectangle() {
@@ -96,7 +96,7 @@ module.exports = {
 };
 ```
 
-A panel plugin, on the other hand, expects you to export an _object_ with one required _lifecycle method_ named `show`, and with optional lifecycle methods name `hide` and `update`:
+Plugin panel UI, on the other hand, requires you to export an _object_ with one required _lifecycle method_ named `show`, and with optional lifecycle methods name `hide` and `update`:
 
 ```js
 function show(event) {
@@ -122,11 +122,11 @@ module.exports = {
 };
 ```
 
-Review the specifics of these panel lifecycle methods in the [references](/reference/ui/panels/index.md) before moving on.
+Review the specifics of these panel lifecycle methods in the [panel-object API reference](/reference/structure/handlers.md#panel) before moving on.
 
 ### 3. Review your modal `main.js` code
 
-Let's first look at the `main.js` file of your modal plugin:
+Let's first look at the `main.js` file of your original modal-dialog plugin:
 
 ```js
 const { selection } = require("scenegraph"); // [1]
@@ -216,7 +216,7 @@ Let's start modifying code in the `main.js` file.
 
 #### Warn the user about invalid selections
 
-Your HTML markup does not have to change, but let's add a `p` tag to show a warning message if the user has selected a node that's not rectangle:
+Your HTML markup does not have to change, but let's add a `p` tag to show a warning message if the user has selected a node that's not a rectangle:
 
 ```html
 <p id="warning">
@@ -229,26 +229,20 @@ Unlike modal UI, panel UI can stay open and persistent, optionally updating in r
 
 #### Request to make changes to the scenegraph
 
-Panel plugins are asynchronous and they require a special function to hold the scenegraph open when your plugin wants to make changes to the document.
+Unlike menu commands, which have just a single entry point the user can trigger to run the command, panel plugins have many different ways that the user can interact with their DOM elements to trigger an action. As a result, your panel UI event handlers must call special function when you want to make changes to the XD document.
 
-Your plugin can request to make edits to the document with the `application.editDocument` method:
+Any part of your panel that makes changes to the scenegraph needs to be wrapped in an [`application.editDocument`](/reference/application.md#module_application-editDocument) call:
 
 ```js
 const { editDocument } = require("application");
-```
-
-Any part of your code that makes changes to the scenegraph needs to be wrapped in an `editDocument` call:
 
-```js
 editDocument({ editLabel: "Increase rectangle size" }, function(selection) {
   const selectedRectangle = selection.items[0];
   selectedRectangle.width += width;
   selectedRectangle.height += height;
 });
 ```
 
-See the [`editDocument`](/reference/application.md) reference for further information.
-
 #### Make a panel element
 
 Now, instead of creating a `dialog`, let's create a `panel` element, insert the HTML, and add an event listener with the `increaseRectangleSize` function attached.

migrations/uxp-2-to-3.md

@@ -1,8 +1,8 @@
 # UXP 2 to 3
 
-XD 20 and below utilized UXP version 2. In XD 21, we're shipping a new version of UXP: Version 3.1. This version is a _huge_ release, and comes with lots of new features of which you'll want to take advantage.
+XD 20 and below utilized UXP version 2. In XD 21, we're shipping a new version: UXP 3.1. This version is a _huge_ release, and comes with lots of new features of which you'll want to take advantage.
 
-Because the new features in UXP 3.1 are so large, we also introduced a backwards-compatibility mode. _All plugins use backwards-compatibility mode by default_, unless the plugin explicitly opts out. This helps to ensure that most plugins won't suddenly change their appearance and have broken layouts.
+Because the new features in UXP 3.1 are so large, we also introduced a backwards-compatibility mode. _All plugins use backwards-compatibility mode by default_, unless the plugin explicitly opts into UXP 3 by updating its declared `minVersion`. This helps to ensure that most plugins won't suddenly change their appearance and have broken layouts.
 
 > **Info**
 >