Merge pull request #217 from AdobeXD/xd-26-apis

Xd 26 apis

Author: kerrishotts

changes.md

@@ -1,5 +1,44 @@
 # Change Log
 
+XD Release 26.0.12 (January 2020)
+-------------------------------------
+
+### Drag & drop
+UXP now supports the [HTML5 Drag & Drop specification](https://html.spec.whatwg.org/multipage/dnd.html) for _some specific use cases_:
+
+* **Drag & drop within your plugin's UI**
+    * On the drag source in your UI, set the `draggable` attribute _and_ define a `dragstart` event handler that stores whatever data you want via `dataTransfer.setData()`.
+    * On the drop target in your UI, defined `dragenter`, `dragover`, and `drop` event handlers that react appropriately.
+* **Drag from plugin panel UI into XD document**
+    * Only bitmap images, SVG content, or text can be dropped into the document.
+    * Provide the mimetype `text/uri-list` and populate it only with local file paths (see [`File.nativePath`](./reference/uxp/module/storage.md#module-storage-entry-nativepath)) and/or `data:` image URIs.
+    * This will behave exactly the same as if the user had dropped files onto XD -- dropping an image onto a shape will use it as a mask, dropping multiline text onto a Repeat Grid text node will populate each grid cell with each line from the text content, etc.
+* It is not yet supported to drag content _onto_ your plugin from an outside source (e.g. dropping files on your plugin UI, or dragging images from another app into your plugin UI).
+
+For more, [see this **sample plugin code**](https://github.com/AdobeXD/plugin-samples/tree/master/ui-panel-simple-drag-and-drop).
+
+### Debugging with Chrome DevTools _(beta)_
+You can now use the Chrome DevTools UI (CDT) to debug your JS code -- and _to a limited extent_, inspect your UI DOM structure. **Read the updated [debugging tutorial](./tutorials/debugging/index.md)** for details.
+
+**What works:**
+* Set breakpoints, pause & stop through code, inspect the values of variables
+* View objects and run code in the Console view
+* View and edit the "HTML" DOM structure of your plugin's UXP UI
+
+**Important caveats:**
+* XD may be unstable while debugging a plugin. Don't debug when you have important XD documents open.
+* If you leave CDT on the Elements view, XD will crash the next time you open it. If this happens, keep CDT open after XD crashes and switch to a different tab. Then close CDT, restart XD, and begin debugging again.
+* Debugging on Windows requires some extra steps run with admin rights -- see tutorial for details.
+* Many features in the Elements tab do not work. You can view DOM structure, and view limited CSS information but not edit CSS rules. The "Select an element" button does nothing.
+* Error messages are often _missing_ from the Console view. Use the _Plugins > Development > Developer Console_ view in XD to be sure you are not missing any important information.
+* Other DevTools features such as the Network or Profiling tabs are not supported and may behave erratically if you attempt to use them.
+* XD will be partially frozen while paused on a JS breakpoint. Don't try to interact with XD while paused.
+* You may see a blank white panel to the left of the DevTools UI. Ignore this, as it does nothing.
+
+### Other API updates
+* Polygon scenenodes can now take on a star shape - see [`Polygon.starRatio`](./reference/scenegraph.md#Polygon-starRatio)
+
+
 XD Release 25.1.12 (December 2019)
 -------------------------------------
 

known-issues.md

@@ -89,6 +89,12 @@
 - Interactive elements do not support `Pointer%` events
 - `keypress` and `keyup` are not currently supported on macOS.
 
+### Drag & Drop
+
+- `drag` and `dragexit` are not supported, although other HTML5 drag/drop events do work.
+- Images and text are not implicitly draggable, unlike in HTML. You must provide a `dragstart` handler that calls `event.dataTransfer.setData()`.
+- Dragging files or other content _onto_ your plugin UI from an outside source is not supported.
+
 ## Network I/O
 
 - On macOS, it is not possible to use self-signed certificates with secure Websockets.
@@ -100,3 +106,18 @@
 ## File I/O
 
 - `Blob` is not supported. Use `ArrayBuffer` instead.
+
+## Debugging
+
+* XD may be unstable while debugging a plugin. Don't debug when you have important XD documents open.
+* Debugging on Windows requires some extra steps run with admin rights -- see [tutorial](/tutorials/debugging/index.md) for details.
+* Elements tab:
+    - If you leave CDT on the Elements tab, XD will crash the next time you open it. If this happens, keep CDT open after XD crashes and switch to a different tab. Then close CDT, restart XD, and begin debugging again.
+    - The CSS pane on the right is missing some data and cannot be used to edit CSS.
+    - Selecting/hovering elements does not highlight the corresponding region in the XD UI.
+    - The "Select an element" button does nothing.
+* Error messages are often missing from the Console view. Use the _Plugins > Development > Developer Console_ view in XD to be sure you are not missing any important information.
+* Other DevTools features such as the Network or Profiling tabs are not supported and may behave erratically if you attempt to use them.
+* XD will be partially frozen while paused on a JS breakpoint. Don't try to interact with XD while paused.
+* You may see a blank white panel to the left of the DevTools UI. Ignore this, as it does nothing.
+* If debugging exposes any private fields and methods, do not attempt to use them. Plugins referring to private APIs will be rejected or removed from XD's plugin listing.

reference/scenegraph.md

@@ -1263,25 +1263,34 @@ True if the Ellipse is a circle (i.e., has a 1:1 aspect ratio).
 **Kind**: class
 **Extends**: [<code>GraphicNode</code>](#GraphicNode)
 
-Leaf node shape that is a polygon with 3 or more sides. May also have rounded corners. The sides are not necessarily all equal in length:
+Leaf node shape that is either a convex polygon _or_ a star shape. May have rounded corners. The sides are not necessarily all equal in length:
 this is true only when the Polygon's width and height matches the aspect ratio of a regular (equilateral) polygon with the given number of
 sides.
 
-When unrotated, the Polygon always has its bottommost side as a perfectly horizontal line - with the exception of the 4-sided Polygon, which
+When unrotated, a non-star Polygon always has its bottommost side as a perfectly horizontal line - with the exception of the 4-sided Polygon, which
 is a diamond shape instead.
 
 Like all shape nodes, has no size, fill, or stroke by default unless you set one.
 
 **Example**
 ```js
-// Add a red triangle to the document and select it
+// Add a red triangle to the document
 var polygon = new Polygon();
 polygon.cornerCount = 3;
 polygon.width = 50;
 polygon.height = 100;
 polygon.fill = new Color("red");
 selection.insertionParent.addChild(polygon);
-selection.items = [polygon];
+
+// Add a blue 5-pointed star with rounded corners
+var polygon = new Polygon();
+polygon.cornerCount = 5;
+polygon.starRatio = 55;
+polygon.setAllCornerRadii(4);
+polygon.width = 100;
+polygon.height = 95;
+polygon.fill = new Color("blue");
+selection.insertionParent.addChild(polygon);
 ```
 
 * [Polygon](#Polygon)
@@ -1291,6 +1300,7 @@ selection.items = [polygon];
     * [.cornerRadii](#Polygon-cornerRadii) : <code>!Array&lt;number&gt;</code>
     * [.hasRoundedCorners](#Polygon-hasRoundedCorners) : <code>boolean</code>
     * [.setAllCornerRadii(radius)](#Polygon-setAllCornerRadii)
+    * [.starRatio](#Polygon-starRatio) : <code>number</code>
 
 
 * * *
@@ -1314,12 +1324,14 @@ selection.items = [polygon];
 ### polygon.cornerCount : <code>number</code> (integer &gt;= 3)
 **Default**: 3
 
-Number of corners (vertices), and also therefore number of sides.
+For a non-star shape, defines the number of corners (vertices), and also therefore number of sides. For a star shape, defines the
+number of star points -- there will be twice as many corners in total (the tips of the points _plus_ all the inside corners
+between the points).
 
-Setting cornerCount on an existing Polygon behaves in one of two different ways:
+Setting `cornerCount` on an existing Polygon behaves in one of two different ways:
 * If the shape's aspect ratio gives it equilateral sides, the sides remain equilateral while the size and aspect ratio of the
-  shape is changed to accomodate.
-* Otherwise, the size and aspect ratio of the shape remains unchanged.
+  shape are automatically changed as needed.
+* Otherwise, the size and aspect ratio of the shape remain unchanged.
 
 This matches how changing the corner count in XD's UI behaves.
 
@@ -1363,6 +1375,21 @@ Set the corner radius of all corners of the Polygon to the same value.
 
 * * *
 
+<a name="Polygon-starRatio"></a>
+
+### polygon.starRatio : <code>number</code> (1.0 to 100.0)
+**Default**: `100`
+**Since**: XD 26
+
+Determines how prominent the shape's star points are. The default value of 100 is a normal convex polygon (not a star at all).
+For a star shape, consider that the outer vertices at the tips of the points all lie on a circle and the inner vertices
+between the points all lie on a second, smaller circle. The `starRatio` is the ratio of the smaller circle's diameter to the
+outer circle's diameter, expressed as a percentage.
+
+**Kind**: instance property of [<code>Polygon</code>](#Polygon)
+
+* * *
+
 
 <a name="Line"></a>
 

tutorials/debugging/index.md

@@ -2,78 +2,89 @@
 
 Bugs happen! In this tutorial, you will learn how to debug your Adobe XD plugin.
 
-## Prerequisite
+### Prerequisite
 
 At least one plugin in your `develop` folder (you can create one using our [Quick Start tutorial](/tutorials/quick-start)).
 
+### Debugging Options
 
-## Debugging Steps
+There are two ways you can debug an XD plugin:
 
-During development, if your plugin is misbehaving, there are few things you can do to investigate the problem.
+* For **quick, simple debugging**, [use the Developer Console built into XD](#quick-debugging-with-developer-console)
+* For **in-depth debugging**, set up your plugin for [debugging with Chrome DevTools](#debugging-with-chrome-devtools-beta) _(beta)_
 
-### 1. Look for errors in the developer console
 
-You can see error messages your plugin may be causing with the XD developer console.
+## Quick debugging with Developer Console
 
-The developer console can be opened from the _Plugins_ menu: _Plugins > Development > Developer Console_.
+### 1. Check the Developer Console
 
+In XD, click _Plugins > Development > Developer Console_.
 
-### 2. Try reloading the plugins
+This displays information similar to what you'd find in the JS debugger's console view:
+* Any `console.log()` output from your plugin
+* Any error messages from XD due to plugin misbehavior, or failure to load a plugin
+* Stack traces if your code throws an uncaught exception
 
-You can reload all plugins in your `develop` folder from the _Plugins_ menu: _Plugins > Development > Reload Plugins_.
+The console output for _all_ installed XD plugins is mixed together in one single view here.
 
-There's also a handy keyboard shortcut:
+### 2. Reload your plugin after making fixes
+
+You can easily iterate on your plugin code without heaving to restart XD. Click _Plugins > Development > Reload Plugins_ to reload all plugins in your `develop` folder. This will reflect any changes in [manifest.json](/reference/structure/manifest.md) in addition to any changes to your JS code.
+
+There's also a handy keyboard shortcut to make reloading easier:
 
 | Platform      | Keyboard shortcut  |
 | ------------- | -------------      |
 | macOS         | Shift-Cmd-R        |
 | Windows       | Ctrl-Shift-R       |
 
-If there are any errors blocking the plugin from loading, they will appear in the developer console on reload:
-
-![reload-error.png](/images/reload-error.png)
-
-### 3. Try logging messages to the developer console
+If there are any errors blocking the plugin from loading, they will appear in the Developer Console on reload:
 
-The example code below does not appear to be creating the "Hello!" text as expected.
+![Error during reload](/images/reload-error.png)
 
-Let's try adding a "start message" and an "end message" into `sayHello()` to double-check that the code is starting and running all the way to the end:
 
-```js
-function sayHello(selection) {
-  console.log("sayHello started!");         // log a message
+## Debugging with Chrome DevTools _(beta)_
 
-  const el = new Text();
-  el.text = "Hello!";
-  el.styleRanges = [
-    {
-      length: el.text.length,
-      fill: new Color("#FFFFFF")
-    }
-  ];
+### 1. Enable debugging on your plugin
 
-  selection.insertionParent.addChild(el);
-  el.moveInParentCoordinates(100, 100);
+Navigate to the root folder of your plugin and **create a `debug.json` file**:
 
-  console.log("sayHello ran to the end!");  // log a message
+```json
+{
+    "port": 9345,
+    "breakOnStart": false
 }
 ```
 
-Your `console.log` messages will appear in the developer console:
+* Debugging is only supported for plugins in the **`develop` folder** (not plugins installed from the Plugin Manager UI).
+* Specify any port number you want.
+* Advanced: Set `breakOnStart` to true if you want the debugger to immediately pause on the first line of code in your plugin the moment it starts loading. This is useful since you won't have a chance to open DevTools _before_ this moment to set breakpoints before that initial code runs.
 
-![start-message](/images/start-message.png)
+### 2. Launch Chrome DevTools
 
-It looks like the function is running... maybe there is another problem.
+1. Windows only: _before_ launching XD, open an admin command prompt and run `CheckNetIsolation LoopbackExempt -is -n="Adobe.CC.XD.adky2gkssdxte"` -- do this _each time_ you want to debug a plugin.
+2. Open Google Chrome and navigate to **`chrome://inspect`** _(you must use Chrome)_
+3. One-time setup: ensure "Discover Network Targets" is enabled. Click the Configure button next to this and add `localhost:9345` (or whatever port number your `debug.json` file used).
+4. Click the "inspect" link under your plugin's ID.
 
-![wrong-color](/images/wrong-color.png)
+### Beta: What works, what doesn't
 
-Oops, the fill color set by the plugin is `#FFFFFF`, which is white: the same color as this artboard's background.
+Currently, you **can**...
+* Set breakpoints, pause & step through code, inspect the values of variables
+* View objects and run code in the Console view
+* View and edit the DOM structure of your plugin's UXP UI
 
-You can verify this with a `console.log` message:
+Most other DevTools features are not supported and may behave erratically if you attempt to use them.
+
+**Important caveats:**
+* XD may be unstable while debugging a plugin. Don't debug when you have important XD documents open.
+* Error messages are often _missing_ from the DevTools Console. Use the Developer Console within XD (see "Quick debugging" above) to be sure you are not missing any important information.
+* XD will be partially frozen while paused on a JS breakpoint. Don't try to interact with XD while paused.
+* You may see a blank white panel to the left of the DevTools UI. Ignore this, as it does nothing.
+* If debugging exposes any private fields and methods, do not attempt to use them. Plugins referring to private APIs will be rejected or removed from XD's plugin listing.
+
+Read the [known issues](/known-issues.md#debugging) for more details.
 
-```js
-console.log("el fill color =" + el.fill);  // OUTPUT HERE
-```
 
 ## Next Steps