diff --git a/README.md b/README.md index 8e8d8fd..eecff52 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,39 @@ # Adobe XD Plugin API typings -Typings for Adobe XD API Surfaces -![typings-supported autocompletion features in JetBrains WebStorm](image.png) - -Detailed instructions for using these type declarations to get autocompletion features in editors and IDEs can be found in the [repository's wiki](https://github.com/AdobeXD/typings/wiki/Autocompletion-in-editors-and-IDEs). +Typings for [Adobe XD](https://www.adobe.io/xd/uxp/develop/reference/xd-index/) and (UXP)[https://www.adobe.io/xd/uxp/uxp/] Plugin Development -## Download -The best option to download the typings is to download the latest release from . +![typings-supported autocompletion features in JetBrains WebStorm](image.png) ## Getting started -These Type Declaration files provide your IDE (e.g. Visual Studio Code or WebStorm) with information about the XD API surface, enabling type checking, autocomplete suggestions, and more. To get started, simply copy the following resources from this repo into your project's main directory: - -- The `jsconfig.json` file. -- The `types` directory. - -Your IDE may require further setup to take full advantage of the types. Please see this [wiki page](https://github.com/AdobeXD/typings/wiki/Autocompletion-in-editors-and-IDEs#editor--ide-specific-instructions) for more. - -The Type Declaration files also allow you to use TypeScript instead of JavaScript for your plugin development. For that, you'll have to copy the `types` folder to your project and include it in the `paths` of your `tsconfig.json`: -```json -{ - "paths": { - "*": [ - "types/*" - ] +These Type Declaration files provide your IDE (e.g. Visual Studio Code or WebStorm) with information about the XD API surface, enabling type checking, autocomplete suggestions, and more. + +To get started +- install the package via npm: + ``` + npm i @adobexd/typings` + ``` +- add the typings file to `"typeRoots"` your `jsconfig.json` or `tsconfig.json`: + ```json + { + "compilerOptions": { + "typeRoots": ["node_modules/@adobexd/typings"] + }, } -} -``` - -You may also take a look at the `tsconfig.json` file contained in this repository for reference. - -## One last thing + ``` +- (optional) add the [UXP WebComponents](https://www.adobe.io/xd/uxp/uxp/reference-spectrum/) to the `JSX.IntrinsicElements` namespace by adding a reference to a `types.d.ts` file + ```ts + /// + ``` + + +## About these type files These type declarations track the contents of the official documentation. If an issue with the type declarations stems from an issue with the official documentation, then the type declaration files will be fixed once the issue is addressed in the documentation. This is intentional so as to keep the type declarations both maintainable and in sync with the documentation. A few notable exceptions include: -- `scenegraph.SceneNode` and `scenegraph.RootNode`, are documented as classes, but implemented as interfaces (in the TypeScript-sense, i.e., without a constructor), which is how they get declared in the typings -- To avoid ambiguity with the *DOM* `Selection` type, the interface [`Selection`](https://adobexdplatform.com/plugin-docs/reference/selection.html) is implemented under the name `XDSelection` (in the global namespace), here. -- The `LinearGradient` type is incorrectly documented as [`LinearGradientFill`](https://adobexdplatform.com/plugin-docs/reference/LinearGradientFill.html). This is implemented "the right way" in the typings. +- The [`application.import()`](https://www.adobe.io/xd/uxp/develop/reference/application/#import) function cannot be declared because `import` is a reserved TypeScript keyword (not sure if this can be fixed). It is declared as `application.importFiles()` instead. +- To avoid ambiguity with the *DOM* `Selection` type, the interface [`Selection`](https://www.adobe.io/xd/uxp/develop/reference/selection/) is also provided as an alias `XDSelection` and exported from the `'scenegraph'` module + +## Original Documentation Links +- [New Adobe.io XD Docs](https://www.adobe.io/xd/uxp/develop/reference/xd-index/) +- [New Adobe.io XD Docs GitHub Repo](https://github.com/AdobeDocs/uxp-xd/tree/main/src/pages/develop/reference) +- [Adobe XD API Updates and Changelog](https://www.adobe.io/xd/uxp/develop/changelog/) +- [Original Adobe XD Platform Docs](https://adobexdplatform.com/plugin-docs/reference/xd-index.html) diff --git a/index.d.ts b/index.d.ts new file mode 100644 index 0000000..2548627 --- /dev/null +++ b/index.d.ts @@ -0,0 +1,11 @@ +// Type definitions for Adobe XD and UXP v45.0.0 +// Project: https://www.adobe.io/xd/uxp/develop/reference/xd-index/ +// Definitions by: James Bradford +// Pablo Klaschka +// Eric Robinson +// Kerri Shotts +// Jonathan Fontanez +// Definitions: https://github.com/AdobeXD/typings + +import './xd' +import './uxp' \ No newline at end of file diff --git a/package.json b/package.json index 5af1cd9..e8fedf3 100644 --- a/package.json +++ b/package.json @@ -1,27 +1,40 @@ { "name": "@adobexd/typings", - "version": "25.0.0", - "types": "./types/index.d.ts", + "version": "45.0.0", + "main": "", + "types": "index.d.ts", "description": "Typings for Adobe XD CC", + "license": "MIT", + "homepage": "https://github.com/AdobeXD/typings#readme", "repository": { "type": "git", "url": "git@github.com:AdobeXD/typings.git" }, + "bugs": { + "url": "https://github.com/AdobeXD/typings/issues" + }, + "files": [ + "index.d.ts", + "xd", + "uxp" + ], "keywords": [ - "typescript", "adobe-xd", "xd", "adobexd", "plugins", + "types", + "@types", "typings", - "typescript definitions" + "typescript definitions", + "typescript" ], - "license": "MIT", - "bugs": { - "url": "https://github.com/AdobeXD/typings/issues" - }, - "homepage": "https://github.com/AdobeXD/typings#readme", "contributors": [ + { + "name": "James Bradford", + "email": "james@bradford.digital", + "url": "https://github.com/arniebradfo" + }, { "name": "Pablo Klaschka", "email": "xdplugins@pabloklaschka.de", @@ -43,4 +56,4 @@ "url": "https://github.com/tato123" } ] -} +} \ No newline at end of file diff --git a/sample.js b/sample.js index ceaca5a..995432a 100644 --- a/sample.js +++ b/sample.js @@ -1,32 +1,32 @@ -const {Text, Ellipse, Color} = require("scenegraph"); -const clipboard = require("clipboard"); -const shell = require("uxp").shell; -const fs = require("uxp").storage.localFileSystem; +const { Text, Ellipse, Color } = require('scenegraph'); +const clipboard = require('clipboard'); +const shell = require('uxp').shell; +const fs = require('uxp').storage.localFileSystem; const assets = require('assets'); const uxp = require('uxp'); /** - * @param {XDSelection} selection + * @param {import('scenegraph').Selection} selection * @param {import('scenegraph').RootNode} documentRoot */ async function test(selection, documentRoot) { for (const node of selection.items) { - console.log("Hello world: ", node); + console.log('Hello world: ', node); if (node instanceof Text) { clipboard.copyText(node.text); } else if (node instanceof Ellipse) { - node.fill = new Color("#ffaaee"); + node.fill = new Color('#ffaaee'); await shell.openExternal('https://adobe-xd.gitbook.io/plugin-api-reference/uxp-api-reference/network-apis/shell'); } } const tempFolder = await fs.getTemporaryFolder(); - const newFile = await tempFolder.createFile("tempfile.txt", {overwrite: true}); - await newFile.write("Hello, world!"); - await newFile.moveTo(tempFolder, {overwrite: true}); + const newFile = await tempFolder.createFile('tempfile.txt', { overwrite: true }); + await newFile.write('Hello, world!'); + await newFile.moveTo(tempFolder, { overwrite: true }); const anotherFile = await tempFolder.getEntry('tempfile.txt'); if (anotherFile.isFile) { - anotherFile.write("Good day"); + anotherFile.write('Good day'); } else if (anotherFile.isFolder) { console.log("That's a folder. It shouldn't be a folder. What have you done?") } @@ -40,3 +40,4 @@ module.exports = { test: test } }; + diff --git a/tsconfig.json b/tsconfig.json index a5b25ad..b8eec06 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,18 +1,25 @@ { - "compilerOptions": { - "strict": true, - "target": "es2015", - "baseUrl": "./", - "allowJs": true, - "checkJs": true, - "lib": [ - "es2015", - "dom" - ], - "typeRoots": [ - "./types/index.d.ts", - "node_modules/@types" - ], - "types": ["./types", "node_modules/types"] - } -} + "compilerOptions": { + "target": "es2015", + "module": "commonjs", + "baseUrl": "./", + "typeRoots": [ + "./" + ], + "types": [], + "lib": [ + "es2015", + "dom" + ], + "checkJs": true, + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "strictFunctionTypes": true, + "forceConsistentCasingInFileNames": true, + "noEmit": true + }, + "files": [ + "index.d.ts" + ] +} \ No newline at end of file diff --git a/tslint.json b/tslint.json new file mode 100644 index 0000000..eb9fbcb --- /dev/null +++ b/tslint.json @@ -0,0 +1,3 @@ +{ + "extends": "@definitelytyped/dtslint/dt.json" +} \ No newline at end of file diff --git a/types/scenegraph.d.ts b/types/scenegraph.d.ts deleted file mode 100644 index bbad14d..0000000 --- a/types/scenegraph.d.ts +++ /dev/null @@ -1,1367 +0,0 @@ -declare module 'scenegraph' { - import {Interaction} from 'interactions'; - import {storage} from 'uxp'; - - interface Point { - x: number; - y: number; - } - - interface ScaleFactor { - scaleX: number; - scaleY: number; - } - - export class Matrix { - /** - * Creates a new transform matrix with the following structure: - * - * ``` - * | a c e | - * | b d f | - * | 0 0 1 | - * ``` - * - * Note: XD does not generally allow transform matrices with scale or shear (skew) components - only translate and rotate components are typically permitted. - * - * If no arguments, creates a new identity matrix by default. - * - * @param a - * @param b - * @param c - * @param d - * @param e - * @param f - */ - constructor(a: number, b: number, c: number, d: number, e: number, f: number); - - /** - * Copies another matrix's values into this matrix. - * @param otherMatrix The matrix to copy values from. - */ - setFrom(otherMatrix: Matrix): void; - - /** - * Returns a copy of the matrix - */ - clone(): Matrix; - - /** - * Multiplies a passed affine transform to the right: this * M. The result effectively applies the transform of the passed in matrix first, followed by the transform of this matrix second. Modifies this matrix object and also returns it so calls can be chained. - * @param aOrOtherMatrix A Matrix or the a component of an affine transform. - * @param b The b component of an affine transform. - * @param c The c component of an affine transform. - * @param d The d component of an affine transform. - * @param e The e component of an affine transform. - * @param f The f component of an affine transform. - */ - add(aOrOtherMatrix: number, b: number, c: number, d: number, e: number, f: number): void; - - /** - * Multiplies a passed affine transform to the right: this * M. The result effectively applies the transform of the passed in matrix first, followed by the transform of this matrix second. Modifies this matrix object and also returns it so calls can be chained. - * @param aOrOtherMatrix A Matrix or the a component of an affine transform. - */ - add(aOrOtherMatrix: Matrix): void; - - /** - * Multiplies a passed affine transform to the left: M * this. The result effectively applies the transform of this matrix first, followed by the transform of the passed in matrix second. Modifies this matrix object and also returns it so calls can be chained. - * @param aOrOtherMatrix A Matrix or the a component of an affine transform. - * @param b The b component of an affine transform. - * @param c The c component of an affine transform. - * @param d The d component of an affine transform. - * @param e The e component of an affine transform. - * @param f The f component of an affine transform. - */ - multLeft(aOrOtherMatrix: number, b: number, c: number, d: number, e: number, f: number): void; - - /** - * Multiplies a passed affine transform to the left: M * this. The result effectively applies the transform of this matrix first, followed by the transform of the passed in matrix second. Modifies this matrix object and also returns it so calls can be chained. - * @param aOrOtherMatrix A Matrix or the a component of an affine transform. - */ - multLeft(aOrOtherMatrix: Matrix): void; - - /** - * Returns an inverted version of the matrix. Returns a brand new matrix - does not modify this matrix object. - */ - invert(): Matrix; - - /** - * Applies translation before the current transform of this matrix, as if using the add() method. Modifies this matrix object and also returns it so calls can be chained. - * @param tx horizontal offset distance - * @param ty vertical offset distance - */ - translate(tx: number, ty: number): Matrix; - - /** - * Applies scaling before the current transform of this matrix, as if using the add() method. Modifies this matrix object and also returns it so calls can be chained. - * - * Note: scale transforms are not generally permitted in XD. - * @param sx amount to be scaled, with 1 resulting in no change - * @param sy amount to scale along the vertical axis. (Otherwise sx applies to both axes.) - * @param cx horizontal origin point from which to scale (if unspecified, scales from the local coordinates' origin point) - * @param cy vertical origin point from which to scale - */ - scale(sx: number, sy?: number, cx?: number, cy?: number): Matrix; - - /** - * Applies clockwise rotation before the current transform of this matrix, as if using the add() method. Modifies this matrix object and also returns it so calls can be chained. - * @param angle angle of rotation, in degrees clockwise - * @param cx horizontal origin point from which to rotate (if unspecified, scales from the local coordinates' origin point) - * @param cy vertical origin point from which to rotate - */ - rotate(angle: number, cx?: number, cy?: number): Matrix; - - /** - * Returns x coordinate of the given point after transformation described by this matrix. See also Matrix.y and Matrix.transformPoint. - * @param x - * @param y - */ - x(x: number, y: number): number; - - /** - * Returns y coordinate of the given point after transformation described by this matrix. See also Matrix.x and Matrix.transformPoint. - * @param x - * @param y - */ - y(x: number, y: number): number; - - /** - * Returns x & y coordinates of the given point after transformation described by this matrix. - * @param point - */ - transformPoint(point: Point): Point; - - /** - * Transforms a rectangle using this matrix, returning the axis-aligned bounds of the resulting rectangle. If this matrix has rotation, then the result will have different width & height from the original rectangle, due to axis alignment. See "Coordinate Spaces" for some illustrations of this. - * @param rect - */ - transformRect(rect: Bounds): Bounds; - - /** - * @return The translation component of this matrix: [tx, ty]. Equals the `e` and `f` components of this matrix. - */ - getTranslate(): number[]; - - /** - * Split the matrix into scale factors. This method assumes that there is no skew in the matrix. - */ - scaleFactors(): ScaleFactor; - - /** - * Returns a new matrix that contains only the translate and rotate components of the current matrix, with the given scale factors stripped out. Must be passed the exact scale factors returned by scaleFactors() for this matrix, and this matrix must have no skew/shear component. - * - * Returns a brand new matrix - does not modify this matrix object. - * @param scaleX horizontal scale component to remove - * @param scaleY vertical scale component to remove - */ - removedScaleMatrix(scaleX: number, scaleY: number): Matrix; - - /** - * @return true, if the matrix includes any skew (shear) - */ - hasSkew(): boolean; - } - - export class Color { - /** - * Integer 0-255. Get/set the alpha channel value. - */ - a: number; - - /** - * Integer 0-255. Get/set the red channel value. - */ - r: number; - - /** - * Integer 0-255. Get/set the green channel value. - */ - g: number; - - /** - * Integer 0-255. Get/set the blue channel value. - */ - b: number; - - /** - * Creates a new color instance. - * @param value String in CSS color format (hex, rgb, rgba, hsl, hsla, hsv, hsva, or color name); or ARGB numeric value (unsigned 32-bit integer); or object with r, g, b, a keys all set to integers from 0 - 255 (if a is omitted, 255 is used). - * @param opacity Optional, floating-point value from 0 - 1. Use when value parameter doesn't specify an opacity and you don't want the default 1.0 (100%) opacity. - */ - constructor(value: string | { r: number, g: number, b: number, a?: number }, opacity?: number); - - /** - * Convert to an object with r, g, b, a keys where r, g, b, a range from 0 - 255. - */ - toRgba(): { r: number, g: number, b: number, a: number }; - - /** - * Convert to hex string with "#" prefix. Ignores the Color's alpha value. Returns a 3-digit string if possible, otherwise returns a 6-digit string. - * @param forceSixDigits True if you want the result to always have 6 digits. - */ - toHex(forceSixDigits: boolean): string; - - /** - * Returns a clone of the current color object - */ - clone(): Color; - } - - export class LinearGradient { - /** - * Array of objects representing each color and its position along the gradient line. The position (stop value) is a number 0.0 - 1.0. - */ - colorStops: { color: Color, stop: number }[]; - - /** - * X position of the start of the gradient line, as a multiple of the object's bounding box: X=0 indicates the left edge of the bounding box and X=1 indicates the right edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. - */ - startX: number; - - /** - * Y position of the start of the gradient line, as a multiple of the object's bounding box: Y=0 indicates the top edge of the bounding box and Y=1 indicates the bottom edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. - */ - startY: number; - - /** - * X position of the end of the gradient line, as a multiple of the object's bounding box: X=0 indicates the left edge of the bounding box and X=1 indicates the right edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. - */ - endX: number; - - /** - * Y position of the end of the gradient line, as a multiple of the object's bounding box: Y=0 indicates the top edge of the bounding box and Y=1 indicates the bottom edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. - */ - endY: number; - - /** - * Create a new LinearGradient instance. - */ - constructor(); - - /** - * Returns a copy of this instance. - */ - clone(): LinearGradient; - - /** - * Returns an array of [startX, startY, endX, endY]. - */ - getEndPoints(): number[]; - - /** - * Shorthand for setting all four start/endpoint properties. - * @param startX - * @param startY - * @param endX - * @param endY - */ - setEndPoints(startX: number, startY: number, endX: number, endY: number): void; - } - - /** - * **The RadialGradient type is not documented and its API may change. Plugins currently cannot modify or otherwise work with radial gradients.** - */ - export class RadialGradient { - // TODO: Waiting for documentation to arrive - } - - export class ImageFill { - /** - * The image is stretched (distorting its aspect ratio) so its edges line up exactly with the edges of the shape. (Similar to `object-fit: fill` in CSS). - */ - static SCALE_STRETCH: string; - /** - * The image's aspect ratio is preserved and it it scaled to completely cover the area of the shape. This means on one axis the image's edges line up exactly with the edges of the shape, and on the other axis the image extends beyond the shape's bounds and is cropped. (Similar to `object-fit: cover` in CSS). - */ - static SCALE_COVER: string; - - /** - * How the image is scaled when the aspect ratio of the shape does not match the aspect ratio of the image: - * * ImageFill.SCALE_STRETCH - The image is stretched (distorting its aspect ratio) so its edges line up exactly with the edges of the shape. (Similar to `object-fit: fill` in CSS). - * * ImageFill.SCALE_COVER - The image's aspect ratio is preserved and it it scaled to completely cover the area of the shape. This means on one axis the image's edges line up exactly with the edges of the shape, and on the other axis the image extends beyond the shape's bounds and is cropped. (Similar to `object-fit: cover` in CSS). - * - * Image size and scaling are also affected by cropping settings, but these are not yet exposed to plugins. - * - * To change this property, use cloneWithOverrides. - */ - scaleBehaviour: string; - - /** - * Format the image data was originally encoded in, such as `image/gif` or `image/jpeg`. - */ - readonly mimeType: string; - - /** - * True if the image comes from a link to an external resource, such as Creative Cloud Libraries. - */ - readonly isLinkedContent: boolean; - - /** - * Pixel dimensions of the underlying bitmap image data. - */ - readonly naturalWidth: number; - - /** - * Pixel dimensions of the underlying bitmap image data. - */ - readonly naturalHeight: number; - - /** - * - * @param fileOrDataURI File object pointing to an image file; or a string containing a data: URI with a base-64 encoded image. - */ - constructor(fileOrDataURI: string | storage.File); - - /** - * @returns a new copy of this ImageFill. - */ - clone(): ImageFill; - } - - - export class Shadow { - /** - * X offset of the shadow relative to the shape it is attached to, in global coordinates (i.e. independent of the shape's rotation or any parent's rotation). May be negative. - */ - x: number; - - /** - * Y offset of the shadow relative to the shape it is attached to, in global coordinates (i.e. independent of the shape's rotation or any parent's rotation). May be negative. - */ - y: number; - blur: number; - color: Color; - - /** - * If false, the shadow is not rendered. The user can toggle this via a checkbox in the Properties panel. - */ - visible: boolean; - - /** - * Creates a drop shadow style object with the given properties. - * @param x - * @param y - * @param blur - * @param color - * @param visible optional and defaults to true. - */ - constructor(x: number, y: number, blur: number, color: Color, visible: boolean) - } - - export class Blur { - /** - * The amount of blur - * - * (0 - 50) - */ - blurAmount: number; - /** - * For background blur effects, the amount to increase or decrease the brightness of the background. Ignored for object blur effects. - * - * (-50 - 50) - */ - brightnessAmount: number; - - /** - * For background blur effects, the a multiplier on the opacity of the object's fill drawn over top of the blurred background. Useful to create a color tint on top of the blurred background. Does not affect stroke opacity. - * - * Ignored for object blur effects. - * - * (0.0 - 1.0) - */ - fillOpacity: number; - /** - * If true, renders a background blur effect: all objects beneath the shape are blurred (modulated by brightnessAmount), but the shape itself is still rendered with crisp edges (with its fill modulated by fillOpacity). - * - * If false, renders an object blur effect: the shape itself is blurred, and objects beneath it are unaffected. - */ - isBackgroundEffect: boolean; - - /** - * If false, the blur effect is not rendered. The user can toggle this via a checkbox in the Properties panel. - */ - visible: boolean; - - /** - * Creates an object blur or background blur effect object with the given properties. - * @param blurAmount - * @param brightnessAmount - * @param fillOpacity - * @param visible - * @param isBackgroundEffect - */ - constructor(blurAmount: number, brightnessAmount: number, fillOpacity: number, visible?: boolean, isBackgroundEffect?: boolean); - } - - export interface Bounds { - x: number; - y: number; - width: number; - height: number; - } - - export interface SceneNode extends SceneNodeClass { - } - - /** - * Base class of all scenegraph nodes. Nodes will always be an instance of some subclass of SceneNode. - */ - abstract class SceneNodeClass { - /** - * Returns a unique identifier for this node that stays the same when the file is closed & reopened, or if the node is moved to a different part of the document. Cut-Paste will result in a new guid, however. - */ - readonly guid: string; - /** - * Returns the parent node. Null if this is the root node, or a freshly constructed node which has not been added to a parent yet. - */ - readonly parent: SceneNode | null; - /** - * Returns a list of this node’s children. List is length 0 if the node has no children. The first child is lowest in the z order. - * This list is not an Array, so you must use at(i) instead of [i] to access children by index. It has a number of Array-like methods such as forEach() for convenience, however. - * The list is immutable. Use removeFromParent and addChild to add/remove child nodes. - */ - readonly children: SceneNodeList; - /** - * True if the node’s parent chain connects back to the document root node. - */ - readonly isInArtworkTree: boolean; - /** - * True if this node is a type that could have children (e.g. an Artboard, Group, Boolean Group, etc.). - */ - readonly isContainer: boolean; - /** - * True if this node is part of the current selection. To change which nodes are selected, use selection. - */ - readonly selected: boolean; - - /** - * False if this node has been hidden by the user (eyeball toggle in Layers panel). If true, the node may still be invisible for other reasons: a parent or grandparent has visible=false, the node has opacity=0%, the node is clipped by a mask, etc. - */ - visible: boolean; - - /** - * (0.0-1.0)Node’s opacity setting. The overall visual opacity seen on canvas is determined by combining this value with the opacity of the node’s entire parent chain, as well as the opacity settings of its fill/stroke properties if this is a leaf node. - */ - opacity: number; - - /** - * Affine transform matrix that converts from the node’s local coordinate space to its parent’s coordinate space. The matrix never has skew or scale components, and if this node is an Artboard the matrix never has rotation either. Rather than working with the raw matrix directly, it may be easier to use methods such as placeInParentCoordinates or rotateAround. - * Returns a fresh Matrix each time, so this can be mutated by the caller without interfering with anything. Mutating the returned Matrix does not change the node’s transform - only invoking the ‘transform’ setter changes the node. To modify an existing transform, always be sure to re-invoke the transform setter rather than just changing the Matrix object’s properties inline. See “Properties with object values”. - * For an overview of node transforms & coordinate systems, see Coordinate spaces. - */ - readonly transform: Matrix; - - /** - * The translate component of this node’s transform. Since translation is applied after any rotation in the transform Matrix, translation occurs along the parent’s X/Y axes, not the node’s own local X/Y axes. This is equivalent to the e & f fields in the transform Matrix. - * For an overview of node positioning & coordinate systems, see Coordinate spaces. - */ - translation: Point; - - /** - * The rotation component of this node’s transform, in clockwise degrees. - * For an overview of node transforms & coordinate systems, see Coordinate spaces. - */ - readonly rotation: number; - - /** - * The node’s path bounds in document-global coordinate space (represented by a bounding box aligned with global X/Y axes). Path bounds match the selection outline seen in the XD, but exclude some visual parts of the node (outer stroke, drop shadow / blur, etc.). - */ - readonly globalBounds: Bounds; - - /** - * The node’s path bounds in its own local coordinate space. This coordinate space may be rotated and translated relative to the parent’s coordinate space. Path bounds match the selection outline seen in XD, but exclude some visual parts of the node (outerstroke, drop shadow / blur, etc.). - * The visual top-left of a node’s path bounds is located at (localBounds.x, localBounds.y). This value is not necessarily (0,0) in the local coordinate space: for example, a text node’s baseline is at y=0 in local coordinates, so the top of the text has a negative y value. - */ - readonly localBounds: Bounds; - - /** - * The node’s path bounds in its parent’s coordinate space (represented by a bounding box aligned with the parent’s X/Y axes - so if the node has rotation, the top-left of the node is not necessarily located at the top-left of boundsInParent). Path bounds match the selection outline seen in XD, but exclude some visual parts of the node (outer stroke, drop shadow / blur, etc.). - */ - readonly boundsInParent: Bounds; - - /** - * The position of the node’s upper-left corner (localBounds.x, localBounds.y) in its parent’s coordinate space. If the node is rotated, this is not the same as the top-left corner of boundsInParent. This is a shortcut for node.transform.transformPoint({x: node.localBounds.x, y: node.localBounds.y}) - */ - readonly topLeftInParent: Point; - - /** - * The position of the node’s centerpoint in its own local coordinate space. Useful as an argument to rotateAround. This is a shortcut for {x: localBounds.x + localBounds.width/2, y: localBounds.y + localBounds.height/2}) - */ - readonly localCenterPoint: Point; - - /** - * The node’s draw bounds in document-global coordinate space. Draw bounds are larger than the selection outline seen in XD, including outer stroke, drop shadow / blur, etc. - every visible pixel of the node is encompassed by these bounds. This matches the image dimensions if the node is exported as a PNG/JPEG bitmap. - */ - readonly globalDrawBounds: Bounds; - - /** - * Node name as seen in the Layers panel. Also used as filename during export. - */ - name: string; - - /** - * True if name is a generic, auto-generated string (e.g. “Rectangle 5”). False if name has been explicitly set. - */ - readonly hasDefaultName: boolean; - - /** - * True if the node is locked, meaning it cannot normally be selected. - */ - locked: boolean; - - /** - * True if the node should be included in the output of File > export > Batch and other bulk-export workflows. - */ - markedForExport: boolean; - - /** - * **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._ - * - * 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. - */ - fixedWhenScrolling?: boolean; - - /** - * Get all interactions that are triggered by this node in the document's interactive prototype. Each element in the array is an Interaction object which describes a gesture/event plus the action it produces. - * - * Note: If this node (or one of its ancestors) has `visible` = false, tap and drag interactions on it will not be triggered. - * - * Currently, this API excludes any keyboard/gamepad interactions on this node. - * - * @example ```javascript - // Print all the interactions triggered by a node - node.triggeredInteractions.forEach(interaction => { - console.log("Trigger: " + interaction.trigger.type + " -> Action: " + interaction.action.type); -}); - * ``` - * - * @see interactions.allInteractions - */ - readonly triggeredInteractions?: Array; - - /** - * True if the node's appearance comes from a link to an external resource, such as Creative Cloud Libraries or a separate XD document (in the case of a Linked Component instance). - */ - readonly hasLinkedContent: boolean; - - /** - * **Since:** XD 14 - * Metadata specific to your plugin. Must be a value which can be converted to a JSON string, or undefined to clear the stored metadata on this node. - * - * Metadata is persisted with the document when it is saved. Duplicating a node (including across documents, via copy-paste) will duplicate the metadata with it. If the node lies within a Component or Repeat Grid, all instances of the node will have identical metadata (changes in one copy will automatically be synced to the other copy). Metadata stored by this plugin cannot be accessed by other plugins - each plugin has its own isolated metadata storage. - - * - * To store general metadata for the document overall, set pluginData on the root node of the scenegraph. Metadata on the root node can be changed from any edit context. - */ - pluginData: any; - - /** - * Remove this node from its parent, effectively deleting it from the document. - */ - removeFromParent(): void; - - /** - * Move the node by the given number of pixels along the parent’s X/Y axes (if this node has no rotation, this is identical to moving the node along its own local X/Y axes). This is equivalent to modifying the value returned by ‘translation’ and then setting it back. - * For an overview of node positioning & coordinate systems, see Coordinate spaces. - * @param {number} deltaX - * @param {number} deltaY - */ - moveInParentCoordinates(deltaX: number, deltaY: number): void; - - /** - * Move the node so the given point in its local coordinates is placed at the given point in its parent’s coordinates (taking into account any rotation on this node, etc.). - * For an overview of node positioning & coordinate systems, see Coordinate spaces. - * @param {Point} registrationPoint Point in this node’s local coordinate space to align with parentPoint - * @param {Point} parentPoint Point in this node’s parent’s coordinate space to move registrationPoint to - */ - placeInParentCoordinates( - registrationPoint: Point, - parentPoint: Point - ): void; - - /** - * Rotate the node clockwise by the given number of degrees around the given point in the plugin’s local coordinate space. If this node already has nonzero rotation, this operation adds to its existing angle. - * @param {number} deltaAngle In degrees. - * @param {Point} rotationCenter Point to rotate around, in node’s local coordinates. - */ - rotateAround(deltaAngle: number, rotationCenter: Point): void; - - /** - * Attempts to change localBounds.width & height to match the specified sizes. This operation may not succeed, since some nodes are not resizable. Resizing one dimension may affect the other, if the node’s aspect ratio is locked. - * @param {number} width - * @param {number} height - */ - resize(width: number, height: number): void; - } - - /** - * Base class for nodes that have a stroke and/or fill. This includes leaf nodes such as Rectangle, as well as BooleanGroup which is a container node. If you create a shape node, it will not be visible unless you explicitly give it either a stroke or a fill. - */ - export class GraphicNode extends SceneNodeClass { - /** - * The fill applied to this shape, if any. If this property is null or fillEnabled is false, no fill is drawn. Freshly created nodes have no fill by default. - * - * For Line objects, fill is ignored. For Text objects, only solid Color fill values are allowed. - * - * To modify an existing fill, always be sure to re-invoke the fill setter rather than just changing the fill object’s properties inline. See “Properties with object values”. - * - * Known issue: When modifying a gradient fill object specifically, you must clone the gradient returned by the getter before modifying it, to avoid issues with Undo history. - */ - fill: - | null - | Color - | LinearGradient - | RadialGradient - | ImageFill; - - /** - * If false, the fill is not rendered. The user can toggle this via a checkbox in the Properties panel. - */ - fillEnabled: boolean; - - /** - * The stroke color applied to this shape, if any. If this property is null or strokeEnabled is false, no stroke is drawn. Freshly created nodes have no stroke by default. Artboard objects ignore stroke settings. - * - * Depending on the strokeWidth and strokePosition, the path outline of a node may need to be positioned on fractional pixels in order for the stroke itself to be crisply aligned to the pixel grid. For example, if a horizontal line uses a 1px center stroke, the line’s y should end in .5 to keep the stroke on-pixel. - * - * To modify an existing stroke, always be sure to re-invoke the stroke setter rather than just changing the Color object’s properties inline. See “Properties with object values”. - */ - stroke: null | Color; - - /** - * If false, the stroke is not rendered. The user can toggle this via a checkbox in the Properties panel. - */ - strokeEnabled: boolean; - - /** - * Thickness in pixels of the stroke. - * value must be >= 0 - */ - strokeWidth: number; - - /** - * @default `CENTER_STROKE` for most shapes, `INNER_STROKE` for Rectangle, Ellipse & Polygon - * Position of the stroke relative to the shape’s path outline: GraphicNode.INNER_STROKE, OUTER_STROKE, or CENTER_STROKE. - */ - strokePosition: string; - - /** - * For Lines and non-closed Paths, how the dangling ends of the stroke are rendered: GraphicNode.STROKE_CAP_NONE, STROKE_CAP_SQUARE, or STROKE_CAP_ROUND. - */ - strokeEndCaps: string; - - /** - * How sharp corners in the shape are rendered: GraphicNode.STROKE_JOIN_BEVEL, STROKE_JOIN_ROUND, or STROKE_JOIN_MITER. - */ - strokeJoins: string; - - /** - * value must be >= 0 - */ - strokeMiterLimit: number; - - /** - * Empty array indicates a solid stroke. If non-empty, values represent the lengths of rendered and blank segments of the stroke’s dash pattern, repeated along the length of the stroke. The first value is the length of the first solid segment. If the array is odd length, the items are copied to double the array length. For example, [3] produces the same effect as [3, 3]. - * - * The appearance of each segment’s start/end follows the strokeEndCaps setting. - */ - strokeDashArray: Array; - - /** - * Ignored unless strokeDashArray is non-empty. Shifts the “phase” of the repeating dash pattern along the length of the stroke. - */ - strokeDashOffset: number; - - /** - * The node’s dropshadow, if any. If there is no shadow applied, this property may be null or shadow.visible may be false. - */ - shadow: null | Shadow; - - /** - * The node’s object blur or background blur settings, if applicable. If there is no blur effect applied, this property may be null or blur.visible may be false. - */ - blur: null | Blur; - - /** - * Returns a representation of the node’s outline in SVG syntax. Note that only nodes with strokePosition == GraphicNode.CENTER_STROKE can be faithfully rendered in actual SVG using the exact pathData shown here. - */ - readonly pathData: string; - - /** - * True if the node’s image fill comes from a link to an external resource, such as Creative Cloud Libraries. - */ - readonly hasLinkedGraphicFill: boolean; - } - - /** - * Artboard container node. All Artboards must be children of the root node (they cannot be nested), and they must be placed below all pasteboard content in the z order. - * - * Artboards can have a background fill, but the stroke, shadow, and blur settings are all ignored. Artboards cannot be locked or hidden, or have opacity < 100%. - * - * If a node is changed to overlap an Artboard, it will automatically become a child of the artboard when the operation finishes, and similar if a node is changed to no longer overlap an Artboard. It is not possible to have a node overlapping an Artboard that does not become a child of the artboard, or vice versa, a node that falls entirely outside an Artboard’s bounds but remains its child. - */ - export class Artboard extends GraphicNode { - /** - * value must be >= 0 - */ - width: number; - - /** - * For scrollable Artboards, this is the total height encompassing all content - not just the viewport size (i.e. screen height). - * - * value must be >= 0 - */ - height: number; - - /** - * If Artboard is scrollable, this is the height of the viewport (e.g. mobile device screen size). Null if Artboard isn’t scrollable. - */ - viewportHeight: null | number; - - /** - * **Since**: XD 19 - * - * Get all interactions whose destination is this artboard (either navigating the entire view, i.e. a `"goToArtboard"` action, or - * showing this artboard as an overlay, i.e. an `"overlay"` action). Each element in the array is an [Interaction object]( - * /interactions.md#Interaction) - * which describes a gesture/event plus the action it produces. - * - * May include interactions that are impossible to trigger because the trigger node (or one of its ancestors) has `visible` = false. - * - * Note: currently, this API excludes any applicable keyboard/gamepad interactions. - * @see SceneNode.triggeredInteractions - * @see interactions.allInteractions - */ - readonly incomingInteractions: Array<{ triggerNode: SceneNode, interactions: Array }>; - - /** - * **Since**: XD 19 - * - * True if this is the starting Artboard seen when the interactive prototype is launched. - * - * @see interactions.homeArtboard - */ - readonly isHomeArtboard: boolean; - - /** - * Adds a child node to this container node. You can only add leaf nodes this way; to create structured subtrees of content, use commands. - * @param {SceneNode} node Child to add - * @param {number} index Optional: index to insert child at. Child is appended to end of children list (top of z order) otherwise. - */ - addChild(node: SceneNode, index?: number): void; - - /** - * Inserts a child node after the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately after this existing child - */ - addChildAfter(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Inserts a child node before the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately before this existing child - */ - addChildBefore(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Removes all children from this node. Equivalent to calling removeFromParent() on each child in turn, but faster. - */ - removeAllChildren(): void; - } - - /** - * Rectangle leaf node shape, with or without rounded corners. Like all shape nodes, has no fill or stroke by default unless you set one. - */ - export class Rectangle extends GraphicNode { - /** - * value must be >= 0 - */ - width: number; - - /** - * value must be >= 0 - */ - height: number; - - /** - * Default: `{topLeft:0, topRight:0, bottomRight:0, bottomLeft:0}` - * The actual corner radius that is rendered is capped based on the size of the rectangle even if the radius value set here is higher (see {@link effectiveCornerRadii}) - * To set all corners to the same value, use {@link setAllCornerRadii} - */ - cornerRadii: { - topLeft: number; - topRight: number; - bottomRight: number; - bottomLeft: number; - }; - - /** - * True if any of the Rectangle’s four corners is rounded (corner radius > 0). - */ - readonly hasRoundedCorners: boolean; - - /** - * The actual corner radius that is rendered may be capped by the size of the rectangle. Returns the actual radii that are currently in effect, which may be smaller than the {@link cornerRadii} values as a result. - */ - effectiveCornerRadii: { - topLeft: number; - topRight: number; - bottomRight: number; - bottomLeft: number; - }; - - /** - * Set the rounding radius of all four corners of the Rectangle to the same value. The actual corner radius that is rendered is capped based on the size of the rectangle even if the radius value set here is higher (see {@link effectiveCornerRadii}) - * To set the corners to different radius values, use {@link cornerRadii}. - */ - setAllCornerRadii(radius: number): void; - } - - /** - * Ellipse leaf node shape. - */ - export class Ellipse extends GraphicNode { - radiusX: number; - radiusY: number; - /** - * True if the Ellipse is a circle (i.e., has a 1:1 aspect ratio). - */ - isCircle: boolean; - } - - /** - * Line leaf node shape. - */ - export class Line extends GraphicNode { - /** - * Start point of the Line in local coordinate space.TEMP: To change the start point, use setStartEnd. - */ - readonly start: Point; - /** - * Endpoint of the Line in local coordinate space.TEMP: To change the endpoint, use setStartEnd. - */ - readonly end: Point; - - /** - * Set the start and end points of the Line in local coordinate space. The values may be normalized by this setter, shifting the node’s translation and counter-shifting the start/end points. So the start/end setters may return values different from the values you passed this setter, even though the line’s visual bounds and appearance are the same. - * @param {number} startX - * @param {number} startY - * @param {number} endX - * @param {number} endY - */ - setStartEnd( - startX: number, - startY: number, - endX: number, - endY: number - ): void; - } - - /** - * Arbitrary vector Path leaf node shape. - * - * The path may not start at (0,0) in local coordinates, for example if it starts with a move (“M”) - */ - export class Path extends GraphicNode { - /** - * Representation of the path outline in SVG syntax. Unlike other node types, pathData is writable here. Syntax is automatically normalized, so the getter may return a slightly different string than what you passed to the setter. - */ - pathData: string; - } - - /** - * **Since**: XD 19 - * 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: 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 is a diamond shape instead. - * - * Like all shape nodes, has no size, fill, or stroke by default unless you set one. - * - * @example ```javascript - // Add a red triangle to the document and select it - 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]; - * ``` - */ - export class Polygon extends GraphicNode { - /** - * > 0 - */ - width: number; - - /** - * > 0 - */ - height: number; - - /** - * @default 3 - * Number of corners (vertices), and also therefore number of sides. - * - * 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. - * - * This matches how changing the corner count in XD's UI behaves. - * - * To change corner count while guaranteeing the shape will not change size, save its original size first, set `cornerCount`, and then set size back to the saved values. - */ - cornerCount: number; - - /** - * True if any of the Polygon's corners is rounded (corner radius > 0). - */ - readonly hasRoundedCorners: boolean; - - /** - * List of corner radius for each corner of the polygon. To set corner radius, use [setAllCornerRadii()](#Polygon-setAllCornerRadii). - */ - cornerRadii: number[]; - - /** - * Set the corner radius of all corners of the Polygon to the same value. - * @param {number} radius - */ - setAllCornerRadii(radius: number): void; - } - - /** - * BooleanGroup container node - although it has fill/stroke/etc. properties like a leaf shape node, it is a container with children. Its visual appearance is determined by generating a path via a nondestructive boolean operation on all its children’s paths. - * - * It is not currently possible for plugins to create a new BooleanGroup node, aside from using commands.duplicate to clone existing BooleanGroups. - */ - export class BooleanGroup extends GraphicNode { - /** - * Which boolean operation is used to generate the path: BooleanGroup.PATH_OP_ADD, PATH_OP_SUBTRACT, PATH_OP_INTERSECT, or PATH_OP_EXCLUDE_OVERLAP. - */ - readonly pathOp: string; - - /** - * Adds a child node to this container node. You can only add leaf nodes this way; to create structured subtrees of content, use commands. - * @param {SceneNode} node Child to add - * @param {number} index Optional: index to insert child at. Child is appended to end of children list (top of z order) otherwise. - */ - addChild(node: SceneNode, index?: number): void; - - /** - * Inserts a child node after the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately after this existing child - */ - addChildAfter(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Inserts a child node before the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately before this existing child - */ - addChildBefore(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Removes all children from this node. Equivalent to calling removeFromParent() on each child in turn, but faster. - */ - removeAllChildren(): void; - } - - /** - * Text leaf node shape. Text can have a fill and/or stroke, but only a solid-color fill is allowed (gradient or image will will be rejected). - * - * There are two types of Text nodes: - * - **Point Text** - Expands to fit the full width of the text content. Only uses multiple lines if the text content contains hard line breaks ("\n"). - * - **Area Text** - Fixed width and height. Text is automatically wrapped (soft line wrapping) to fit the width. If it does not fit the height, any remaining text is clipped. Check whether areaBox is null to determine the type of a Text node. - * - * The baseline of a Point Text node is at y=0 in its own local coordinate system. Horizontally, local x=0 is the anchor point that the text grows from / shrinks toward when edited. This anchor depends on the justification: for example, if the text is centered, x=0 is the horizontal centerpoint of the text. - * - * The bounds reported for a Text object leave enough space for descenders, uppercase letters, and accent marks, even if the current string does not contain any of those characters. This makes aligning text based on its bounds behave more consistently. - */ - export class Text extends GraphicNode { - /** - * The plaintext content of the node, including any hard line breaks but excluding soft line wrap breaks. - * - * Setting text does not change styleRanges, so styles aligned with the old text’s string indices will continue to be applied to the new string’s indices unless you explicitly change styleRanges as well. - */ - text: string; - - /** - * Array of text ranges and their character style settings. Each range covers a set number of characters in the text content. Ranges are contiguous, with each one starting immediately after the previous one. Any characters past the end of the last range use the same style as the last range. - * - * When setting styleRanges, any fields missing from a given range default to the existing values from the last range in the old value of styleRanges. The styleRanges getter always returns fully realized range objects with all fields specified. - */ - styleRanges: Array<{ - length: number; - fontFamily: string; - fontStyle: string; - fontSize: number; - fill: Color; - charSpacing: number; - underline: boolean; - strikethrough: boolean; - textTransform: string; - textScript: string; - }>; - - /** - * If true, the text is drawn upside down. - */ - flipY: boolean; - - /** - * **Since:** XD 14 - * Set the font family across all style ranges, or get the font family of the last style range (font family of all the text if one range covers all the text). Plugins should not assume any particular default value for fontFamily. - */ - fontFamily: string; - - /** - * **Since:** XD 14 - * Set the font style across all style ranges, or get the font style of the last style range (font style of all the text if one range covers all the text). - * @default non-italic normal weight style - */ - fontStyle: string; - - /** - * **Since:** XD 14 - * Font size in document pixels. Set the font size across all style ranges, or get the font size of the last style range (font size of all the text if one range covers all the text). Plugins should not assume any particular default value for fontSize. - */ - fontSize: number; - - /** - * Set the text color across all style ranges, or get the color of the last style range (color of all the text if one range covers all the text). Unlike most other nodes, text only allows a solid color fill - gradients and image fills are not supported. - * @default null - */ - fill: Color | null; - - /** - * **Since:** XD 14 - * Character spacing in increments of 1/1000th of the fontSize, in addition to the font's default character kerning. May be negative. - * - * Set the character spacing across all style ranges, or get the character spacing of the last style range (character spacing of all the text if one range covers all the text). - * @default 0 - */ - charSpacing: number; - - /** - * **Since:** XD 14 - * Set underline across all style ranges, or get the underline of the last style range (underline of all the text if one range covers all the text). - * @default false - */ - underline: boolean; - - /** - * @default false - * **Since**: XD 19 - * - * Set strikethrough across all style ranges, or get the strikethrough of the last style range (strikethrough of all the text if one range covers all the text). - */ - strikethrough: boolean; - - /** - * @default "none" - * **Since**: XD 19 - * - * Set textTransform ("none", "uppercase", "lowercase", or "titlecase") across all style ranges, or get the textTransform of the last style range. - */ - textTransform: 'none' | 'uppercase' | 'lowercase' | 'titlecase'; - - /** - * @default "none" - * **Since**: XD 20 - * - * Set textScript ("none" or "superscript" or "subscript") across all style ranges, or get the textScript of the last style range. - */ - textScript: 'none' | 'superscript' | 'subscript'; - - static readonly ALIGN_LEFT: string; - static readonly ALIGN_CENTER: string; - static readonly ALIGN_RIGHT: string; - - /** - * Horizontal alignment: Text.ALIGN_LEFT, ALIGN_CENTER, or ALIGN_RIGHT. This setting affects the layout of multiline text, and for point text it also affects how the text is positioned relative to its anchor point (x=0 in local coordinates) and what direction the text grows when edited by the user. - * - * Changing textAlign on existing point text will cause it to shift horizontally. To change textAlign while keeping the text in a fixed position, shift the text horizontally (moving its anchor point) to compensate: - * @example ```javascript - * let originalBounds = textNode.localBounds; - * textNode.textAlign = newAlignValue; - * let newBounds = textNode.localBounds; - * textNode.moveInParentCoordinates(originalBounds.x - newBounds.x, 0); - * - * @default Text.ALIGN_LEFT - */ - textAlign: string; - - /** - * Distance between baselines in multiline text, in document pixels. The special value 0 causes XD to use the default line spacing defined by the font given the current font size & style. - * - * This property is not automatically adjusted when fontSize changes, if line spacing is not set to 0, the line spacing will stay fixed while the font size changes, shifting the spacing’s proportional relationship to font size. If the value is 0, then the rendered line spacing will change to match the new font size, since 0 means the spacing is dynamically calculated from the current font settings. - * - * @default 0 - */ - lineSpacing: number; - - /** - * **Since:** XD 14 - * - * Additional distance between paragraphs, in document pixels, added to the lineSpacing amount (soft line breaks in area text are separated only by lineSpacing, while hard line breaks are separated by lineSpacing + paragraphSpacing). Unlike lineSpacing, 0 is not a special value; it just means no added spacing. - * - * Similar to {@link lineSpacing}, this property is not automatically adjusted when fontSize changes. The paragraph spacing amount will stay fixed while the font size changes, shifting the spacing's proportional relationship to font size. - * - * @default 0 - */ - paragraphSpacing: number; - - /** - * `Null` for point text. For area text, specifies the size of the rectangle within which text is wrapped and clipped. - * - * Changing point text to area text or vice versa will change the origin / anchor point of the text, thus changing its localBounds, but it will also automatically change the node's transform so its globalBounds and boundsInParent origins remain unchanged. - * - * Changing area text to point text will also automatically insert hard line breaks ("\n") into the text to match the previous line wrapping's appearance exactly. - */ - areaBox: null | { width: number; height: number }; - - /** - * Always false for point text. For area text, true if the text does not fit in the content box and its bottom is being clipped. - */ - readonly clippedByArea: boolean; - } - - /** - * Group nodes represent two types of simple containers in XD: - * - Plain Groups, created by the Object > Group command - * - Masked Groups, created by the Object > Mask With Shape command You can determine whether a group is masked by checking the mask property. - * - * Groups and other containers cannot be created directly using scenenode constructors, since you can’t add a populated Group to the 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. - * - * 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. - */ - export class Group extends SceneNodeClass { - /** - * 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 groups’s appearance by clipping all its other content. - */ - readonly mask: SceneNode | null; - - /** - * Adds a child node to this container node. You can only add leaf nodes this way; to create structured subtrees of content, use commands. - * @param {SceneNode} node Child to add - * @param {number} index Optional: index to insert child at. Child is appended to end of children list (top of z order) otherwise. - */ - addChild(node: SceneNode, index?: number): void; - - /** - * Inserts a child node after the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately after this existing child - */ - addChildAfter(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Inserts a child node before the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately before this existing child - */ - addChildBefore(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Removes all children from this node. Equivalent to calling removeFromParent() on each child in turn, but faster. - */ - removeAllChildren(): void; - } - - /** - * Container node representing one instance of a Component (previously known as "Symbols" in XD's UI). Changes made to the contents of a SymbolInstance are treated in one of two ways: - * * If `isMaster` is **false**: The changes affect _only_ this one instance. This creates an "override": changes made to the corresponding part of the master later will no longer get synced to this particular instance. - * * If `isMaster` is **true**: The changes are automatically synced to all other other instances of the component - _except_ for instances where the affected nodes have instance-specific overrides. As a result, your plugin's batch of edits **may not be applied atomically** in some instances. - * - * To elaborate: if your plugin command makes edits to more than one property or more than one node as part of a single gesture, and the user invokes your plugin while editing a component master, other instances of the component may receive only a _partial application_ of your plugin's changes. In many cases this will feel like a natural consequence of the overrides the user has created, but if this partial application of your plugin's intended changes feels too confusing in your use case, you may opt to warn users or disable some of your plugin's functionality when `selection.editContext` is (or is inside of) a component with `isMaster` true. - * - * Note that overrides vary somewhat in granularity. In some but not all cases, overriding one property may also prevent other properties on the same node from receiving future updates from the master instance. - * - * It is not currently possible for plugins to *create* a new component definition or a new SymbolInstance node, aside from using `require('commands').duplicate` to clone existing SymbolInstances. - */ - export class SymbolInstance extends SceneNodeClass { - /** - * An identifier unique within this document that is shared by all instances of the same component. - */ - readonly symbolId: string; - - /** - * True if this is the "master" instance of the component, which forms the template for all new instances. When the user edits the master, those changes are synced to all other instances of the component (unless blocked by "overrides" - * @see SymbolInstance - */ - readonly isMaster: boolean; - - /** - * Adds a child node to this container node. You can only add leaf nodes this way; to create structured subtrees of content, use commands. - * @param {SceneNode} node Child to add - * @param {number} index Optional: index to insert child at. Child is appended to end of children list (top of z order) otherwise. - */ - addChild(node: SceneNode, index?: number): void; - - /** - * Inserts a child node after the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately after this existing child - */ - addChildAfter(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Inserts a child node before the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately before this existing child - */ - addChildBefore(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Removes all children from this node. Equivalent to calling removeFromParent() on each child in turn, but faster. - */ - removeAllChildren(): void; - } - - /** - * Repeat Grid container node containing multiple grid cells, each one a child Group. Changes within one cell are automatically synced to all the other cells - with certain exceptions, called "overrides." A Repeat Grid also defines a rectangular clipping mask which determines how may cells are visible (new cells are automatically generated as needed if the Repeat Grid is resized larger). - * Each grid cell is a Group that is an immediate child of the RepeatGrid. These groups are automatically created and destroyed as needed when the RepeatGrid is resized. - * It is not currently possible for plugins to create a new RepeatGrid node, aside from using commands.duplicate to clone existing RepeatGrids. - */ - export class RepeatGrid extends SceneNodeClass { - /** - * Defines size of the RepeatGrid. Cells are created and destroyed as necessary to fill the current size. Cells that only partially fit will be clipped. - */ - width: number; - - /** - * Defines size of the RepeatGrid. Cells are created and destroyed as necessary to fill the current size. Cells that only partially fit will be clipped. - */ - height: number; - - /** - * Number of grid columns - */ - numColumns: number; - - /** - * Number of grid rows - */ - numRows: number; - - /** - * Horizontal spacing between grid cells/columns - */ - paddingX: number; - - /** - * Vertical spacing between grid cells/rows - */ - paddingY: number; - - /** - * The size of each grid cell. The size of each cell’s content can vary slightly due to text overrides; the cell size is always set to the width of the widest cell content and the height of the tallest cell content. - */ - cellSize: { width: number; height: number }; - - /** - * Attach a sequence of text values to the instances of a given text node across all the cells of a Repeat Grid. The sequence is repeated as necessary to cover all the grid cells. This is a persistent data binding, so if the Repeat Grid is resized later to increase the number of grid cells, items from this sequence will be used to fill the text values of the new cells. - * You can call this API from either of two different edit contexts: - * - Edit context is the parent node of this RepeatGrid (i.e. a context where the RepeatGrid could be selected) - * - Edit context is the RepeatGrid cell which is the parent of textNode (i.e. a context where textNode could be selected) - * @param {Text} textNode A Text node exemplar that is an immediate child of one of this RepeatGrid's cells. The data series will be bound to this text node and all corresponding copies of it in the other grid cells. - * @param {string[]} textValues Array of one or more strings. Empty strings are ignored. - */ - attachTextDataSeries(textNode: Text, textValues: string[]): void; - - /** - * Attach a sequence of image fills to the instances of a given shape node across all the cells of a Repeat Grid. The sequence is repeated as necessary to cover all the grid cells. This is a persistent data binding, so if the Repeat Grid is resized later to increase the number of grid cells, items from this sequence will be used to set the image fill in the new cells. - * You can call this API from either of two different edit contexts: - * - Edit context is the parent node of this RepeatGrid (i.e. a context where the RepeatGrid could be selected) - * - Edit context is the RepeatGrid cell which is the parent of shapeNode (i.e. a context where shapeNode could be selected) - * @param {GraphicNode} shapeNode A shape node exemplar that is an immediate child of one of this RepeatGrid's cells. The image series will be bound to this node and all corresponding copies of it in the other grid cells. Must be a node type that supports image fills (e.g. Rectangle, but not Text or Line). - * @param {string[]} images Array of one or more ImageFills. - */ - attachImageDataSeries(shapeNode: GraphicNode, images: string[]): void; - - /** - * Adds a child node to this container node. You can only add leaf nodes this way; to create structured subtrees of content, use commands. - * @param {SceneNode} node Child to add - * @param {number} index Optional: index to insert child at. Child is appended to end of children list (top of z order) otherwise. - */ - addChild(node: SceneNode, index?: number): void; - - /** - * Inserts a child node after the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately after this existing child - */ - addChildAfter(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Inserts a child node before the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately before this existing child - */ - addChildBefore(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Removes all children from this node. Equivalent to calling removeFromParent() on each child in turn, but faster. - */ - removeAllChildren(): void; - } - - /** - * Container node whose content is linked to an external resource, such as Creative Cloud Libraries. It cannot be edited except by first ungrouping it, breaking this link. - */ - export class LinkedGraphic extends SceneNodeClass { - } - - export interface RootNode extends RootNodeClass { - } - - /** - * Class representing the root node of the document. All Artboards are children of this node, as well as any pasteboard content that does not lie within an Artboard. Artboards must be grouped contiguously at the bottom of this node’s z order. The root node has no visual appearance of its own. - */ - class RootNodeClass extends SceneNodeClass { - /** - * Adds a child node to this container node. You can only add leaf nodes this way; to create structured subtrees of content, use commands. - * @param {SceneNode} node Child to add - * @param {number} index Optional: index to insert child at. Child is appended to end of children list (top of z order) otherwise. - */ - addChild(node: SceneNode, index?: number): void; - - /** - * Inserts a child node after the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately after this existing child - */ - addChildAfter(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Inserts a child node before the given reference node. - * @param {SceneNode} node Child to add - * @param {SceneNode} relativeTo New child is added immediately before this existing child - */ - addChildBefore(node: SceneNode, relativeTo: SceneNode): void; - - /** - * Removes all children from this node. Equivalent to calling removeFromParent() on each child in turn, but faster. - */ - removeAllChildren(): void; - } - - /** - * **Since:** XD 14 - * Object representing the current selection state and edit context. Also available as the first argument passed to your plugin command handler function. - */ - export const selection: XDSelection; - - /** - * **Since:** XD 14 - * Root node of the current document's scenegraph. Also available as the second argument passed to your plugin command handler function. - */ - export const root: RootNode; - - export {}; // Avoid exporting SceneNodeClass and RootNodeClass -} diff --git a/types/uxp.d.ts b/uxp/index.d.ts similarity index 95% rename from types/uxp.d.ts rename to uxp/index.d.ts index a46c526..4225dd0 100644 --- a/types/uxp.d.ts +++ b/uxp/index.d.ts @@ -1,7 +1,7 @@ declare module 'uxp' { /** - * To get an instance: `require("uxp").shell` + * To get an instance: `require('uxp').shell` */ interface Shell { /** @@ -204,7 +204,7 @@ declare module 'uxp' { */ interface FileSystemProvider { /** - * Gets a file (or files) suitable for reading by displaying an "Open" file picker dialog to the user. File entries returned by this API are read-only - use getFileForSaving to get a File entry you can write to. + * Gets a file (or files) suitable for reading by displaying an 'Open' file picker dialog to the user. File entries returned by this API are read-only - use getFileForSaving to get a File entry you can write to. * * The user can select multiple files only if the `allowMultiple` option is `true`. * @param options additional options @@ -213,12 +213,12 @@ declare module 'uxp' { */ getFileForOpening(options?: { /** - * Optional. Allowed file extensions, with no "." prefix; use `storage.fileTypes.all` to allow any file to be picked + * Optional. Allowed file extensions, with no '.' prefix; use `storage.fileTypes.all` to allow any file to be picked * @default ['*'] */ types?: string[]; /** - * Optional. If `true`, multiple files can be selected and this API returns `Array`. + * Optional. If `true`, multiple files can be selected and this API returns `File[]`. * * If `false`, only one file can be selected and this API returns a File directly. * @@ -228,7 +228,7 @@ declare module 'uxp' { }): Promise; /** - * Gets a file reference suitable for saving. The file is read-write. Any file picker displayed will be of the "save" variety. + * Gets a file reference suitable for saving. The file is read-write. Any file picker displayed will be of the 'save' variety. * * If the user attempts to save a file that doesn't exist, the file is created automatically. * @@ -240,7 +240,7 @@ declare module 'uxp' { */ getFileForSaving(suggestedName: string, options: { /** - * Required. Allowed file extensions, with no "." prefix. + * Required. Allowed file extensions, with no '.' prefix. */ types: string[]; }): Promise; @@ -307,7 +307,7 @@ declare module 'uxp' { /** * Creates a File Entry object within this folder and returns the appropriate instance. Note that this method just create a file entry object and not the actual file on the disk. The file actually gets created when you call for eg: write method on the file entry object. - * @param {string} name the name of the file to create + * @param name the name of the file to create * @param options additional options * * @returns the created entry @@ -322,14 +322,14 @@ declare module 'uxp' { /** * Creates a Folder within this folder and returns the appropriate instance. - * @param {string} name the name of the folder to create + * @param name the name of the folder to create * @returns the created entry */ createFolder(name: string): Promise; /** * Gets an entry from within this folder and returns the appropriate instance. - * @param {string} filePath the name/path of the entry to fetch + * @param filePath the name/path of the entry to fetch * * @returns the fetched entry. */ @@ -337,8 +337,8 @@ declare module 'uxp' { /** * Renames an item on disk to a new name within the same folder. The Entry object passed to this function is automatically updated to reference the new name, however any other Entry objects referencing the original item will not be updated, and will thus no longer point to an item that exists on disk. - * @param {Entry} entry entry to rename (File or Folder). Must exist. - * @param {string} newName the new name to assign + * @param entry entry to rename (File or Folder). Must exist. + * @param newName the new name to assign * @param options additional options */ renameEntry(entry: Entry, newName: string, options?: { diff --git a/uxp/jsxWebComponents.d.ts b/uxp/jsxWebComponents.d.ts new file mode 100644 index 0000000..37dc813 --- /dev/null +++ b/uxp/jsxWebComponents.d.ts @@ -0,0 +1,45 @@ +declare namespace JSX { + // add UXP web components to the native React IntrinsicElements + // https://www.adobe.io/xd/uxp/uxp/reference-spectrum/ + // TODO: these could be typed with their attributes + interface IntrinsicElements { + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/Typography/sp-body/ */ + "sp-body": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/Typography/sp-detail/ */ + "sp-detail": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/Typography/sp-heading/ */ + "sp-heading": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/Typography/sp-label/ */ + "sp-label": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-action-button/ */ + "sp-action-button": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-button/ */ + "sp-button": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-checkbox/ */ + "sp-checkbox": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-divider/ */ + "sp-divider": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-dropdown/ */ + "sp-dropdown": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-icon/ */ + "sp-icon": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-link/ */ + "sp-link": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-menu/ */ + "sp-menu": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-menu-item/ */ + "sp-menu-item": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-progressbar/ */ + "sp-progressbar": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-radio/ */ + "sp-radio": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-radio-group/ */ + "sp-radio-group": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-slider/ */ + "sp-slider": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-textfield/ */ + "sp-textfield": any; + /** https://www.adobe.io/xd/uxp/uxp/reference-spectrum/User%20Interface/sp-textarea/ */ + "sp-textarea": any; + } +} diff --git a/types/application.d.ts b/xd/application.d.ts similarity index 77% rename from types/application.d.ts rename to xd/application.d.ts index e2b74b6..bab3711 100644 --- a/types/application.d.ts +++ b/xd/application.d.ts @@ -1,6 +1,9 @@ +/** + * [application on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/application/) + */ declare module 'application' { - import {Color, SceneNode, RootNode} from "scenegraph"; - import {storage} from "uxp"; + import { Color, SceneNode, RootNode, Selection } from 'scenegraph'; + import { storage } from 'uxp'; interface EditSettings { /** @@ -8,7 +11,7 @@ declare module 'application' { */ editLabel?: string; /** - * If two consecutive edits to the same selection have the same `mergeId`, they are flattened together into one Undo step. If unspecified, for "high frequency" UI events (see above), XD treats the originating DOM node as a unique identifier for merging; for other UI events, merging is disabled. + * If two consecutive edits to the same selection have the same `mergeId`, they are flattened together into one Undo step. If unspecified, for 'high frequency' UI events (see above), XD treats the originating DOM node as a unique identifier for merging; for other UI events, merging is disabled. */ mergeId?: string; } @@ -21,7 +24,7 @@ declare module 'application' { * * It is passed two arguments, the selection and the root node of the scenegraph * * It can return a Promise to extend the duration of the edit asynchronously * - * You can only call `editDocument()` in response to a user action, such as a button `"click"` event or a text input's `"input"` event. This generally means you must call it while a UI event handler is on the call stack. + * You can only call `editDocument()` in response to a user action, such as a button `'click'` event or a text input's `'input'` event. This generally means you must call it while a UI event handler is on the call stack. * * For UI events that often occur in rapid-fire clusters, such as dragging a slider or pressing keys in a text field, XD tries to smartly merge consecutive edits into a single atomic Undo step. See the `mergeId` option below to customize this behavior. * @param editFunction Function which will perform your plugin's edits to the scenegraph. @@ -36,7 +39,7 @@ declare module 'application' { * * It is passed two arguments, the selection and the root node of the scenegraph * * It can return a Promise to extend the duration of the edit asynchronously * - * You can only call `editDocument()` in response to a user action, such as a button `"click"` event or a text input's `"input"` event. This generally means you must call it while a UI event handler is on the call stack. + * You can only call `editDocument()` in response to a user action, such as a button `'click'` event or a text input's `'input'` event. This generally means you must call it while a UI event handler is on the call stack. * * For UI events that often occur in rapid-fire clusters, such as dragging a slider or pressing keys in a text field, XD tries to smartly merge consecutive edits into a single atomic Undo step. See the `mergeId` option below to customize this behavior. * @param options Optional settings object (see below). This argument can be omitted. @@ -57,7 +60,7 @@ declare module 'application' { interface RenditionSettingsPNGorJPG extends RenditionSettingsBase { /** - * (PNG & JPG renditions) DPI multipler in the range [0.1, 100], e.g. 2.0 for @2x DPI. + * (PNG & JPG renditions) DPI multiplier in the range [0.1, 100], e.g. 2.0 for @2x DPI. */ scale: number; /** @@ -110,10 +113,10 @@ declare module 'application' { * All rendition settings fields are required (for a given rendition type) unless otherwise specified. */ export type RenditionSettings = - RenditionSettingsPNG - | RenditionSettingsJPG - | RenditionSettingsSVG - | RenditionSettingsPDF; + RenditionSettingsPNG | + RenditionSettingsJPG | + RenditionSettingsSVG | + RenditionSettingsPDF ; /** * Type that gets returned by `application.createRenditions` @@ -131,29 +134,43 @@ declare module 'application' { * A single createRenditions() call can generate any number of renditions, including multiple renditions of the same node (with different output settings) or renditions of multiple different nodes. Only one createRenditions() call can be executing at any given time, so wait for the Promise it returns before calling it again. * * @param renditions List of renditions to generate - * @return Promise, string> - Promise which is fulfilled with an array of RenditionResults (pointing to the same outputFiles that were originally passed in, or rejected with an error string if one or more renditions failed for any reason. */ export function createRenditions(renditions: RenditionSettings[]): Promise; export enum RenditionType { - JPG = "jpg", - PNG = "png", - PDF = "pdf", - SVG = "svg", + JPG = 'jpg', + PNG = 'png', + PDF = 'pdf', + SVG = 'svg', } /** - * Adobe XD version number in the form "major.minor.patch.build" + * __Note:__ the actual name of this function is `application.import(entries)` but `import` is a reserved keyword in TypeScript, so this is a placeholder... + * + * @since XD 45 + * + * Equivalent to File > Import. Brings assets into the XD document, including images, videos, and Adobe Photoshop or Adobe Illustrator files. Assets will be added as a child of the artboard that is the parent of the current selection (or to the document root if nothing is selected). + * + * Supported import file extensions: AI (Illustrator), BMP, GIF, JPG, JPEG, JSON (Lottie), MP4 (Video), PNG, PSD (Photoshop), TIF, TIFF, TXT + * + * An error will be thrown if a passed file does not exist or has an unsupported file extension. Parsing errors or other import problems that are specific to formats supported by XD are displayed to the user in the same way the File > Import action informs users. + * + * @param entries List of files to be imported + */ + export function importFiles(entries: storage.File[]): void + + /** + * Adobe XD version number in the form 'major.minor.patch.build' */ export const version: string; /** - * Current language the application UI is using. This may not equal the user's OS locale setting: it is the closest locale supported by XD - use this when you want your plugin's UI to be consistent with XD's UI. Specifies language only, with no region info (e.g. "fr", not "fr_FR"). + * Current language the application UI is using. This may not equal the user's OS locale setting: it is the closest locale supported by XD - use this when you want your plugin's UI to be consistent with XD's UI. Specifies language only, with no region info (e.g. 'fr', not 'fr_FR'). */ export const appLanguage: string; /** - * User's OS-wide locale setting. May not match the XD UI, since XD does not support all world languages. Includes both language and region (e.g. "fr_CA" or "en_US"). + * User's OS-wide locale setting. May not match the XD UI, since XD does not support all world languages. Includes both language and region (e.g. 'fr_CA' or 'en_US'). */ export const systemLocale: string; diff --git a/types/assets.d.ts b/xd/assets.d.ts similarity index 82% rename from types/assets.d.ts rename to xd/assets.d.ts index 91e5fe8..df19c6c 100644 --- a/types/assets.d.ts +++ b/xd/assets.d.ts @@ -1,12 +1,18 @@ +/** + * [assets on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/assets/) + * + * @since XD 15 + */ declare module 'assets' { - import {Color, LinearGradient, RadialGradient} from "scenegraph"; + import {Color, LinearGradient, RadialGradient} from 'scenegraph'; /** * Type of gradient color element: linear gradient or radial gradient */ export enum GradientType { - LINEAR, - RADIAL + LINEAR = 'LINEAR', + RADIAL = 'RADIAL', + // ANGULAR = 'ANGULAR', // ??? } /** @@ -39,7 +45,7 @@ declare module 'assets' { /** * Array of color stops used in the gradient, where stop >= 0 and <= 1, and the values are strictly increasing. Same format as the colorStops property of a LinearGradient object. */ - colorStops: Array<{ stop: number, color: Color }> + colorStops: { stop: number, color: Color }[] } /** @@ -93,22 +99,25 @@ declare module 'assets' { */ underline: boolean; /** - * (**Since**: XD 19) + * @since XD 19 * Default `false`; whether strikethrough is turned on */ strikethrough?: boolean; /** - * (**Since**: XD 19) - * Default "none"; one of "none", "uppercase", "lowercase", or "titlecase" + * @since XD 19 + * Default 'none'; one of 'none', 'uppercase', 'lowercase', or 'titlecase' */ textTransform?: 'none' | 'uppercase' | 'lowercase' | 'titlecase'; /** - * (**Since**: XD 20) - * Default "none"; one of "none", "superscript", or "subscript" + * @since XD 20 + * Default 'none'; one of 'none', 'superscript', or 'subscript' */ textScript?: 'none' | 'superscript' | 'subscript'; } + // nonstandard + type ColorOrAsset = Color | ColorAsset | LinearGradient | RadialGradient | GradientAsset + /** * The collection of colors and gradients saved in this document's Asset library */ @@ -117,13 +126,8 @@ declare module 'assets' { * Get a list of all color/gradient assets, in the order they appear in the Assets panel. * * The list may contain a mix of solid Color assets and/or gradient assets. If there are no color/gradient assets, an empty array is returned. - * - * @example - * var assets = require("assets"), - * allColors = assets.colors.get(); - * */ - get(): Array; + get(): (ColorAsset | GradientAsset)[]; /** * Add color/gradient assets to the collection. @@ -132,7 +136,7 @@ declare module 'assets' { * @param colorAssets The color assets * @returns {number} number of assets added (may be less than requested if duplicates already exist) */ - add(colorAssets: Color | ColorAsset | LinearGradient | RadialGradient | GradientAsset | Array): number; + add(colorAssets: ColorOrAsset | ColorOrAsset[]): number; /** * Delete color/gradient assets from the collection. @@ -142,7 +146,7 @@ declare module 'assets' { * @param colorAssets The color assets * @returns {number} number of assets deleted (may be less than requested if some didn't exist) */ - delete(colorAssets: Color | ColorAsset | LinearGradient | RadialGradient | GradientAsset | Array): number; + delete(colorAssets: ColorOrAsset | ColorOrAsset[]): number; } /** @@ -153,13 +157,8 @@ declare module 'assets' { * Get a list of all character style assets, in the order they appear in the Assets panel. * * If there are no character style assets, an empty array is returned. - * - * @example - * var assets = require("assets"), - * allCharacterStyles = assets.characterStyles.get(); - * */ - get(): Array; + get(): CharacterStyleAsset[]; /** * Add one or more character style assets to the collection. @@ -169,7 +168,7 @@ declare module 'assets' { * @param charStyleAssets The character style assets * @returns {number} number of assets added (may be less than requested if duplicates already exist) */ - add(charStyleAssets: CharacterStyleAsset | Array): number; + add(charStyleAssets: CharacterStyleAsset | CharacterStyleAsset[]): number; /** * Delete one or more character style assets from the collection. @@ -181,7 +180,7 @@ declare module 'assets' { * @returns {number} number of assets deleted (may be less than requested if some didn't exist) * @param charStyleAssets The character styles */ - delete(charStyleAssets: CharacterStyleAsset | Array): number; + delete(charStyleAssets: CharacterStyleAsset | CharacterStyleAsset[]): number; } /** diff --git a/types/clipboard.d.ts b/xd/clipboard.d.ts similarity index 71% rename from types/clipboard.d.ts rename to xd/clipboard.d.ts index 3f593c7..03d1af3 100644 --- a/types/clipboard.d.ts +++ b/xd/clipboard.d.ts @@ -1,3 +1,6 @@ +/** + * [clipboard on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/clipboard/) + */ declare module 'clipboard' { /** * Write plain text to the clipboard. diff --git a/types/cloud.d.ts b/xd/cloud.d.ts similarity index 94% rename from types/cloud.d.ts rename to xd/cloud.d.ts index 9d4831a..ed4b110 100644 --- a/types/cloud.d.ts +++ b/xd/cloud.d.ts @@ -1,3 +1,8 @@ +/** + * [cloud on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/cloud/) + * + * @since XD 14 + */ declare module 'cloud' { interface BaseSharedArtifact { type: ArtifactType; @@ -82,8 +87,6 @@ declare module 'cloud' { * Get a list of recently shared artifacts generated from this document. Older artifacts may not be included even if the shared links are still live. Shared links that have been deleted from the server (File > Manage Published Links) may still be listed here, as this API only provides a record of recent share actions from XD - not what the links' current status on the server may be. * * The list may contain a mix of PrototypeArtifact and/or SpecsArtifact, and items are listed in no particular order. If nothing has been shared from this document, an empty array is returned. - * - * @return {!Array} */ - export function getSharedArtifacts(): Array; + export function getSharedArtifacts(): (PrototypeArtifact | SpecsArtifact)[]; } diff --git a/types/commands.d.ts b/xd/commands.d.ts similarity index 73% rename from types/commands.d.ts rename to xd/commands.d.ts index f119e64..ff53007 100644 --- a/types/commands.d.ts +++ b/xd/commands.d.ts @@ -1,3 +1,10 @@ +/** + * [commands on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/commands/) + * + * You can make structural changes to the scenegraph, and perform other complex operations, by programmatically invoking the same commands as XD users have access to in the UI. Because structural changes have many nuanced rules and behaviors in XD, these calls function more like automating the UI than like low-level APIs. + * + * For example, these methods do not take arguments. Instead, set the selection to the objects you want the command to target, then invoke the command. Commands may also change the selection when run - for example, group() selects the newly created Group node. + */ declare module 'commands' { /** * Wraps the selected objects in a Group, leaving the Group selected afterward. Equivalent to Object > Group in the UI. @@ -19,6 +26,12 @@ declare module 'commands' { */ export function convertToPath(): void; + /** + * Converts each selected object's stroke to a Path with the exact same visual appearance. Only applies to leaf nodes, Groups and Boolean Groups. Equivalent to Object > Path > Outline Stroke. + + */ + export function outlineStroke(): void; + /** * Duplicates all selected objects, leaving the duplicates selected afterward. * @@ -94,14 +107,13 @@ declare module 'commands' { */ export function alignToPixelGrid(): void; + /** + * Flips the object horizontally. Some objects such as Symbols cannot be flipped. Equivalent to Object > Flip > Horizontally. + */ + // function flipHorizontal(): void; -// /** -//* Flips the object horizontally. Some objects such as Symbols cannot be flipped. Equivalent to Object > Flip > Horizontally. -//*/ -//function filpHorizontal(): void; -// -// /** -// * Flips the object vertically. Some objects such as Symbols cannot be flipped. Equivalent to Object > Flip > Vertically. -//*/ -//function flipVertical(): void; + /** + * Flips the object vertically. Some objects such as Symbols cannot be flipped. Equivalent to Object > Flip > Vertically. + */ + // function flipVertical(): void; } diff --git a/xd/index.d.ts b/xd/index.d.ts new file mode 100644 index 0000000..fd5b093 --- /dev/null +++ b/xd/index.d.ts @@ -0,0 +1,8 @@ +import './application'; +import './assets'; +import './clipboard'; +import './cloud'; +import './commands'; +import './interactions'; +import './scenegraph'; +import './viewport'; \ No newline at end of file diff --git a/types/interactions.d.ts b/xd/interactions.d.ts similarity index 61% rename from types/interactions.d.ts rename to xd/interactions.d.ts index 523d3e1..443fa35 100644 --- a/types/interactions.d.ts +++ b/xd/interactions.d.ts @@ -1,40 +1,22 @@ +/** + * [interactions on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/interactions/) + * + * @since XD 19+ (some APIs added later) + * + * The interactions module and related APIs provide read only information about the document's interactive prototype mode, including: + * - The blue 'wires' seen in XD's prototyping UI, known as 'interactions,' which specify gestures/events which trigger actions to occur in the prototype. Accessible as a single consolidated global listing via this module's allInteractions API, or you can access information from specific nodes in the scenegraph via SceneNode.triggeredInteractions and Artboard.incomingInteractions. + * - Designers can author multiple prototype or interaction flows in a single document and publish unique shareable links for each flow. Developers can access all document flows using the flows API. With multiple flow support the homeArtboard API is being deprecated as XD no longer has a single home artboard restriction. + * - Properties that affect Artboard scrolling behavior: Artboard viewportHeight and node fixedWhenScrolling. + * + * Tip Interactions are a fast-changing area in XD. APIs here have a higher likelihood of becoming deprecated, or lagging behind new XD features, than other parts of XD's plugin APIs. + */ declare module 'interactions' { - import {Artboard, SceneNode} from "scenegraph"; - /** - * The starting Artboard seen when the interactive prototype is launched. - * @see Artboard.isHomeArtboard - */ - export const homeArtboard: Artboard | null; - - /** - * Returns a collection of *all* interactions across the entire document, grouped by triggering scenenode. Each entry in this array specifies a `triggerNode` and the result of getting [`triggerNode.triggeredInteractions`](./scenegraph.md#SceneNode-triggeredInteractions). - * - * May include interactions that are impossible to trigger because the trigger node (or one of its ancestors) has `visible` = false. - * - * Note: currently, this API excludes all of the document's keyboard/gamepad interactions. - */ - export const allInteractions: Array<{ triggerNode: SceneNode, interactions: Array }>; + import { Artboard, SceneNode } from 'scenegraph'; /** * An interaction consists of a Trigger + Action pair and is attached to a single, specific scenenode. * - * @example ```javascript - { - trigger: { - type: "tap" - }, - action: { - type: "goToArtboard", - destination: Artboard node, - preserveScrollPosition: false, - transition: { - type: "dissolve", - duration: 0.4, - easing: "ease-out" - } - } -}``` * Note: Interaction objects are not plain JSON -- they may reference scenenodes (as seen above) and other strongly-typed objects. */ type Interaction = { @@ -48,46 +30,21 @@ declare module 'interactions' { action: Action; } - /** - * Animation style with which `"goToArtboard"` and `"overlay"` actions transition from/to Artboards. - */ - type Transition = { - /** - * One of: `autoAnimate´, `dissolve`, `push`, `slide`, `none` - */ - type: 'autoAnimate' | 'dissolve' | 'push' | 'slide' | 'none'; - - /** - * _(If type = "push" or "slide")._ One of: `"L"`, `"R"`, `"T"`, `"B"` - */ - fromSide?: string; - - /** - * Length of animation in seconds - */ - duration: number; - - /** - * One of: `linear`, `ease-in`, `ease-out`, `ease-in-out`, `wind-up`, `bounce`, `snap` - */ - easing: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'wind-up' | 'bounce' | 'snap'; - } - type Trigger = { /** * One of the trigger types listed below. * - * ### `"tap"` + * ### `'tap'` * When the user clicks or taps on a scenenode. * - * ### `"drag"` + * ### `'drag'` * When the user drags or swipes a scenenode. Can only trigger a `goToArtboard` action with the `autoAnimate` transition style. * - * ### `"time"` + * ### `'time'` * Once a set amount of time elapses (this trigger type only exists on Artboard nodes). Additional Trigger properties: * * {@link delay} * - * ### `"voice"` + * ### `'voice'` * When the user speaks a specific voice command. Additional Trigger properties: * * {@link speechCommand} */ @@ -115,22 +72,22 @@ declare module 'interactions' { /** * One of the action types listed below. * - * ### "goToArtboard" + * ### 'goToArtboard' * Navigate the entire screen to view a different artboard. Additional Action properties: * * {@link destination} * * {@link transition} * * {@link preserveScrollPosition} * - * ### "overlay" + * ### 'overlay' * Displays a second artboard overlaid on top of the current one. Additional Action properties: * * {@link overlay} * * {@link transition} * * {@link overlayTopLeft} * - * ### "goBack" - * Reverse the last `"goToArtboard"` or `"overlay"` action, replaying in reverse whatever transition it used. + * ### 'goBack' + * Reverse the last `'goToArtboard'` or `'overlay'` action, replaying in reverse whatever transition it used. * - * ### "speak" + * ### 'speak' * Speak with audio output to the user. Additional Action properties: * * {@link speechOutput} * * {@link locale} @@ -166,12 +123,80 @@ declare module 'interactions' { */ speechOutput?: string; /** - * Locale determines the pronounciation and accent of the digital voice. Includes both language *and* region (e.g. "en-us"). + * Locale determines the pronounciation and accent of the digital voice. Includes both language *and* region (e.g. 'en-us'). */ locale?: string; /** - * "Persona" of the digital voice to use. Available personas vary by locale. + * 'Persona' of the digital voice to use. Available personas vary by locale. */ voice?: string; } + + /** + * Animation style with which `'goToArtboard'` and `'overlay'` actions transition from/to Artboards. + */ + type Transition = { + /** + * One of: `autoAnimate´, `dissolve`, `push`, `slide`, `none` + */ + type: 'autoAnimate' | 'dissolve' | 'push' | 'slide' | 'none'; + + /** + * _(If type = 'push' or 'slide')._ One of: `'L'`, `'R'`, `'T'`, `'B'` + */ + fromSide?: string; + + /** + * Length of animation in seconds + */ + duration: number; + + /** + * One of: `linear`, `ease-in`, `ease-out`, `ease-in-out`, `wind-up`, `bounce`, `snap` + */ + easing: 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'wind-up' | 'bounce' | 'snap'; + } + + /** + * + */ + type FlowInfo = { + /** + * Auto-generated or user-defined label for a particular flow. + */ + name: string; + + /** + * Artboard from which a particular flow or a prototype experience begins. + */ + homeArtboard: Artboard; + + /** + * URL is the latest published link associated with a particular flow and can be null in case no link is published for that flow. + */ + url: string | null; + } + + /** + * The starting Artboard seen when the interactive prototype is launched. + */ + export const homeArtboard: Artboard | null; + + /** + * @since XD 33 + * + * Returns a collection of information on all flows across the entire document. + * + * A flow is a series or set of artboards starting from one artboard (called a home artboard), which are connected to other artboards or screens via wires or interactions. A document can have zero or multiple (one or more than one) flows and can therefore have zero or multiple home artboards. Each entry in the return array represents a FlowInfo object. + */ + export const flows: FlowInfo[] + + /** + * Returns a collection of *all* interactions across the entire document, grouped by triggering scenenode. Each entry in this array specifies a `triggerNode` and the result of getting [`triggerNode.triggeredInteractions`](./scenegraph.md#SceneNode-triggeredInteractions). + * + * May include interactions that are impossible to trigger because the trigger node (or one of its ancestors) has `visible` = false. + * + * Note: currently, this API excludes all of the document's keyboard/gamepad interactions. + */ + export const allInteractions: { triggerNode: SceneNode, interactions: Interaction[] }[]; } diff --git a/xd/scenegraph/AngularGradient.d.ts b/xd/scenegraph/AngularGradient.d.ts new file mode 100644 index 0000000..6a70548 --- /dev/null +++ b/xd/scenegraph/AngularGradient.d.ts @@ -0,0 +1,55 @@ +declare module 'scenegraph' { + /** + * [AngularGradient on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/AngularGradient/) + * @since XD 42 + * In an angular (also known as 'conical') gradient, colors blend together in a sweeping pattern around a shape from the center of a circle. The gradient fills the entire area of the shape it is applied to. + */ + export class AngularGradient { + + /** + * Create a new AngularGradient instance. + */ + constructor() + + /** + * Returns a copy of this instance. + */ + clone(): AngularGradient; + + /** + * Array of objects representing each color and its position along the gradient circle. The position (stop value) is a number 0.0 - 1.0. + */ + colorStops: { stop: number, color: Color }[] + + /** + * X position of the center of the gradient circle, as a multiple of the object's bounding box: X=0 indicates the left edge of the bounding box and X=1 indicates the right edge. The gradient circle center may start or end outside the object's bounding box, so values may be < 0 or > 1. + */ + startX: number + + /** + * Y position of the center of the gradient circle, as a multiple of the object's bounding box: Y=0 indicates the top edge of the bounding box and Y=1 indicates the bottom edge. The gradient circle center may start or end outside the object's bounding box, so values may be < 0 or > 1. + */ + startY: number + + /** + * Returns an array of [startX, startY, endX, endY]. + */ + getEndPoints(): [number, number, number, number] + + /** + * Method for setting all four start/endpoint properties. (endX, endY) point is the end of the gradient circle radius. + */ + setEndPoints(startX: number, startY: number, endX: number, endY: number): void + + /** + * Rotation of the gradient in degrees. + */ + rotation: number + + /** + * String representing the type of the gradient, in this case angular gradient. + */ + type: string + + } +} diff --git a/xd/scenegraph/Artboard.d.ts b/xd/scenegraph/Artboard.d.ts new file mode 100644 index 0000000..297b3cc --- /dev/null +++ b/xd/scenegraph/Artboard.d.ts @@ -0,0 +1,53 @@ +import { Interaction } from 'interactions'; + +declare module 'scenegraph' { + /** + * [Artboard on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Artboard/) + * + * Artboard container node. All Artboards must be children of the root node (they cannot be nested), and they must be placed below all pasteboard content in the z order. + * + * Artboards can have a background fill, but the stroke, shadow, and blur settings are all ignored. Artboards cannot be locked or hidden, or have opacity < 100%. + * + * Generally, all nodes that overlap an Artboard are children of that artboard, and nodes that don't overlap any Artboard are children of the root (pasteboard). XD ensures this automatically: if a node is modified in any way that changes whether it overlaps an Artboard, its parent will automatically be changed accordingly after the edit operation finishes. + */ + export class Artboard extends GraphicNode { + + /** + * > 0 + */ + width: number // > 0 + + /** + * > 0 + * + * For scrollable Artboards, this is the total height encompassing all content - not just the viewport size (i.e. screen height). + */ + height: number // > 0 + + /** + * If Artboard is scrollable, this is the height of the viewport (e.g. mobile device screen size). Null if Artboard isn't scrollable. + */ + viewportHeight: number | null + + /** + * @since XD 19 + * + * Get all interactions whose destination is this artboard (either navigating the entire view, i.e. a 'goToArtboard' action, or showing this artboard as an overlay, i.e. an 'overlay' action). Each element in the array is an Interaction object which describes a gesture/event plus the action it produces. + * + * May include interactions that are impossible to trigger because the trigger node (or one of its ancestors) has visible = false. + * + * Note: currently, this API excludes any applicable keyboard/gamepad interactions. + */ + readonly incomingInteractions: { triggerNode: SceneNode, interactions: Interaction[] }[] + + /** + * @deprecated XD 33 - Please use flows which supports multiple flows. + * + * @since XD 19 - True if this is the starting Artboard seen when the interactive prototype is launched. + * + * @since XD 32 - In case there are multiple interactive prototype experiences (flows), implying multiple home artboards, this API returns true only for the top-left artboard among all of those home artboards. + */ + readonly isHomeArtboard: boolean + + } +} \ No newline at end of file diff --git a/xd/scenegraph/Blur.d.ts b/xd/scenegraph/Blur.d.ts new file mode 100644 index 0000000..fe9a397 --- /dev/null +++ b/xd/scenegraph/Blur.d.ts @@ -0,0 +1,46 @@ +declare module 'scenegraph' { + /** + * [Blur on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Blur/) + */ + export class Blur { + + /** + * Creates an object blur or background blur effect object with the given properties. + */ + constructor(blurAmount: number, brightnessAmount: number, fillOpacity: number, visible?: boolean, isBackgroundEffect?: boolean); + + /** + * 0 - 50 + */ + blurAmount: number + + /** + * -50 - 50 + * + * For background blur effects, the amount to increase or decrease the brightness of the background. Ignored for object blur effects. + */ + brightnessAmount: number + + /** + * 0.0 - 1.0 + * + * For background blur effects, the a multiplier on the opacity of the object's fill drawn over top of the blurred background. Useful to create a color tint on top of the blurred background. Does not affect stroke opacity. + * + * Ignored for object blur effects. + */ + fillOpacity: number + + /** + * If true, renders a background blur effect: all objects beneath the shape are blurred (modulated by brightnessAmount), but the shape itself is still rendered with crisp edges (with its fill modulated by fillOpacity). + * + * If false, renders an object blur effect: the shape itself is blurred, and objects beneath it are unaffected. + */ + isBackgroundEffect: boolean + + /** + * If false, the blur effect is not rendered. The user can toggle this via a checkbox in the Properties panel. + */ + visible: boolean + + } +} \ No newline at end of file diff --git a/xd/scenegraph/BooleanGroup.d.ts b/xd/scenegraph/BooleanGroup.d.ts new file mode 100644 index 0000000..fd1369a --- /dev/null +++ b/xd/scenegraph/BooleanGroup.d.ts @@ -0,0 +1,20 @@ +declare module 'scenegraph' { + /** + * [BooleanGroup on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/BooleanGroup/) + * + * BooleanGroup container node - although it has fill/stroke/etc. properties like a leaf shape node, it is a container with children. Its visual appearance is determined by generating a path via a nondestructive boolean operation on all its children's paths. + * + * It is not currently possible for plugins to create a new BooleanGroup node, aside from using commands.duplicate() to clone existing BooleanGroups. + */ + export class BooleanGroup extends GraphicNode { + /** + * Which boolean operation is used to generate the path: BooleanGroup. PATH_OP_ADD, PATH_OP_SUBTRACT, PATH_OP_INTERSECT, or PATH_OP_EXCLUDE_OVERLAP. + */ + readonly pathOp: 'PATH_OP_ADD' | 'PATH_OP_SUBTRACT' | 'PATH_OP_INTERSECT' | 'PATH_OP_EXCLUDE_OVERLAP' // string; + static readonly PATH_OP_ADD = 'PATH_OP_ADD'; + static readonly PATH_OP_SUBTRACT = 'PATH_OP_SUBTRACT'; + static readonly PATH_OP_INTERSECT = 'PATH_OP_INTERSECT'; + static readonly PATH_OP_EXCLUDE_OVERLAP = 'PATH_OP_EXCLUDE_OVERLAP'; + + } +} diff --git a/xd/scenegraph/Color.d.ts b/xd/scenegraph/Color.d.ts new file mode 100644 index 0000000..c9f0e9d --- /dev/null +++ b/xd/scenegraph/Color.d.ts @@ -0,0 +1,50 @@ +declare module 'scenegraph' { + /** + * [Color on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Color/) + */ + export class Color { + /** + * Creates a new color instance. + * @param value String in CSS color format (hex, rgb, rgba, hsl, hsla, hsv, hsva, or color name); or ARGB numeric value (unsigned 32-bit integer); or object with r, g, b, a keys all set to integers from 0 - 255 (if a is omitted, 255 is used). + * @param opacity Optional, floating-point value from 0 - 1. Use when value parameter doesn't specify an opacity and you don't want the default 1.0 (100%) opacity. + */ + constructor(value: string | { r: number, g: number, b: number, a?: number }, opacity?: number); + + /** + * Integer 0-255. Get/set the alpha channel value. + */ + a: number; + + /** + * Integer 0-255. Get/set the red channel value. + */ + r: number; + + /** + * Integer 0-255. Get/set the green channel value. + */ + g: number; + + /** + * Integer 0-255. Get/set the blue channel value. + */ + b: number; + + + /** + * Convert to an object with r, g, b, a keys where r, g, b, a range from 0 - 255. + */ + toRgba(): { r: number, g: number, b: number, a: number }; + + /** + * Convert to hex string with '#' prefix. Ignores the Color's alpha value. Returns a 3-character string in the form #123 if possible, otherwise returns a 6-character string in the form #456ABC. + * @param forceSixDigits True if you want the result to always have 6 digits. + */ + toHex(forceSixDigits: boolean): string; + + /** + * Returns a clone of the current color object + */ + clone(): Color; + } +} \ No newline at end of file diff --git a/xd/scenegraph/Ellipse.d.ts b/xd/scenegraph/Ellipse.d.ts new file mode 100644 index 0000000..c5ad4a3 --- /dev/null +++ b/xd/scenegraph/Ellipse.d.ts @@ -0,0 +1,15 @@ +declare module 'scenegraph' { + /** + * [Ellipse on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Ellipse/) + * + * Ellipse leaf node shape. + */ + export class Ellipse extends GraphicNode { + radiusX: number; + radiusY: number; + /** + * True if the Ellipse is a circle (i.e., has a 1:1 aspect ratio). + */ + readonly isCircle: boolean; + } +} \ No newline at end of file diff --git a/xd/scenegraph/GraphicNode.d.ts b/xd/scenegraph/GraphicNode.d.ts new file mode 100644 index 0000000..26fe0fc --- /dev/null +++ b/xd/scenegraph/GraphicNode.d.ts @@ -0,0 +1,110 @@ +declare module 'scenegraph' { + /** + * [GraphicNode on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/GraphicNode/) + * + * Base class for nodes that have a stroke and/or fill. This includes leaf nodes such as Rectangle, as well as BooleanGroup which is a container node. If you create a shape node, it will not be visible unless you explicitly give it either a stroke or a fill. + */ + export class GraphicNode extends SceneNode { + + /** + * @updated XD 42 + * @default null + * + * The fill applied to this shape, if any. If this property is null or fillEnabled is false, no fill is drawn. Freshly created nodes have no fill by default. + * + * For Line objects, fill is ignored. For Text objects, only solid Color fill values are allowed. + * + * To modify an existing fill, always be sure to re-invoke the fill setter rather than just changing the fill object’s properties inline. See “Properties with object values”. + * + * Known issue: When modifying a gradient fill object specifically, you must clone the gradient returned by the getter before modifying it, to avoid issues with Undo history. + */ + fill: Color | LinearGradient | RadialGradient | AngularGradient | ImageFill | null; + + /** + * If false, the fill is not rendered. The user can toggle this via a checkbox in the Properties panel. + */ + fillEnabled: boolean; + + /** + * The stroke color applied to this shape, if any. If this property is null or strokeEnabled is false, no stroke is drawn. Freshly created nodes have no stroke by default. Artboard objects ignore stroke settings. + * + * Depending on the strokeWidth and strokePosition, the path outline of a node may need to be positioned on fractional pixels in order for the stroke itself to be crisply aligned to the pixel grid. For example, if a horizontal line uses a 1px center stroke, the line’s y should end in .5 to keep the stroke on-pixel. + * + * To modify an existing stroke, always be sure to re-invoke the stroke setter rather than just changing the Color object’s properties inline. See “Properties with object values”. + */ + stroke: Color | null; + + /** + * If false, the stroke is not rendered. The user can toggle this via a checkbox in the Properties panel. + */ + strokeEnabled: boolean; + + /** + * Thickness in pixels of the stroke. + * value must be >= 0 + */ + strokeWidth: number; + + /** + * @default `CENTER_STROKE` for most shapes, `INNER_STROKE` for Rectangle, Ellipse & Polygon + * Position of the stroke relative to the shape’s path outline: GraphicNode.INNER_STROKE, OUTER_STROKE, or CENTER_STROKE. + */ + strokePosition: 'INNER_STROKE' | 'OUTER_STROKE' | 'CENTER_STROKE' // string; + static readonly INNER_STROKE = 'INNER_STROKE'; + static readonly OUTER_STROKE = 'OUTER_STROKE'; + static readonly CENTER_STROKE = 'CENTER_STROKE'; + + /** + * For Lines and non-closed Paths, how the dangling ends of the stroke are rendered: GraphicNode.STROKE_CAP_NONE, STROKE_CAP_SQUARE, or STROKE_CAP_ROUND. + */ + strokeEndCaps: 'STROKE_CAP_NONE' | 'STROKE_CAP_SQUARE' | 'STROKE_CAP_ROUND' // string; + static readonly STROKE_CAP_NONE = 'STROKE_CAP_NONE'; + static readonly STROKE_CAP_SQUARE = 'STROKE_CAP_SQUARE'; + static readonly STROKE_CAP_ROUND = 'STROKE_CAP_ROUND'; + + /** + * How sharp corners in the shape are rendered: GraphicNode.STROKE_JOIN_BEVEL, STROKE_JOIN_ROUND, or STROKE_JOIN_MITER. + */ + strokeJoins: 'STROKE_JOIN_BEVEL' | 'STROKE_JOIN_ROUND' | 'STROKE_JOIN_MITER' // string; + static readonly STROKE_JOIN_BEVEL = 'STROKE_JOIN_BEVEL'; + static readonly STROKE_JOIN_ROUND = 'STROKE_JOIN_ROUND'; + static readonly STROKE_JOIN_MITER = 'STROKE_JOIN_MITER'; + + /** + * value must be >= 0 + */ + strokeMiterLimit: number; + + /** + * Empty array indicates a solid stroke. If non-empty, values represent the lengths of rendered and blank segments of the stroke’s dash pattern, repeated along the length of the stroke. The first value is the length of the first solid segment. If the array is odd length, the items are copied to double the array length. For example, [3] produces the same effect as [3, 3]. + * + * The appearance of each segment’s start/end follows the strokeEndCaps setting. + */ + strokeDashArray: number[]; + + /** + * Ignored unless strokeDashArray is non-empty. Shifts the “phase” of the repeating dash pattern along the length of the stroke. + */ + strokeDashOffset: number; + + /** + * The node’s dropshadow, if any. If there is no shadow applied, this property may be null or shadow.visible may be false. + */ + shadow: Shadow | null; + + /** + * The node’s object blur or background blur settings, if applicable. If there is no blur effect applied, this property may be null or blur.visible may be false. + */ + blur: Blur | null; + + /** + * Returns a representation of the node’s outline in SVG syntax. Note that only nodes with strokePosition == GraphicNode.CENTER_STROKE can be faithfully rendered in actual SVG using the exact pathData shown here. + */ + readonly pathData: string; + + /** + * True if the node’s image fill comes from a link to an external resource, such as Creative Cloud Libraries. + */ + readonly hasLinkedGraphicFill: boolean; + } +} \ No newline at end of file diff --git a/xd/scenegraph/Group.d.ts b/xd/scenegraph/Group.d.ts new file mode 100644 index 0000000..1c9e244 --- /dev/null +++ b/xd/scenegraph/Group.d.ts @@ -0,0 +1,24 @@ +declare module 'scenegraph' { + /** [Group on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Group/) */ + export class Group extends SceneNode { + + /** https://www.adobe.io/xd/uxp/develop/reference/Group/#addchild */ + addChild(node: SceneNode, index?: number): void + + /** https://www.adobe.io/xd/uxp/develop/reference/Group/#addchildafter */ + addChildAfter(node: SceneNode, relativeTo: SceneNode): void + + /** https://www.adobe.io/xd/uxp/develop/reference/Group/#addchildbefore */ + addChildBefore(node: SceneNode, relativeTo: SceneNode): void + + /** https://www.adobe.io/xd/uxp/develop/reference/Group/#removeallchildren */ + removeAllChildren(): void + + /** https://www.adobe.io/xd/uxp/develop/reference/Group/#dynamiclayout */ + dynamicLayout?: boolean + + /** https://www.adobe.io/xd/uxp/develop/reference/Group/#mask */ + readonly mask?: SceneNode + + } +} \ No newline at end of file diff --git a/xd/scenegraph/ImageFill.d.ts b/xd/scenegraph/ImageFill.d.ts new file mode 100644 index 0000000..4baa3c5 --- /dev/null +++ b/xd/scenegraph/ImageFill.d.ts @@ -0,0 +1,33 @@ +import { storage } from 'uxp'; + +declare module 'scenegraph' { + /** [ImageFill on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/ImageFill/) */ + export class ImageFill { + + constructor(fileOrDataURI: storage.File | string) + + /** https://www.adobe.io/xd/uxp/develop/reference/ImageFill/#clone */ + clone(): ImageFill + + /** https://www.adobe.io/xd/uxp/develop/reference/ImageFill/#assetid */ + assetId: string + + /** https://www.adobe.io/xd/uxp/develop/reference/ImageFill/#scalebehavior */ + scaleBehavior: 'SCALE_COVER' | 'SCALE_STRETCH' // string + static readonly SCALE_COVER = 'SCALE_COVER'; + static readonly SCALE_STRETCH = 'SCALE_STRETCH'; + + /** https://www.adobe.io/xd/uxp/develop/reference/ImageFill/#naturalwidth */ + readonly naturalWidth: number + + /** https://www.adobe.io/xd/uxp/develop/reference/ImageFill/#naturalheight */ + readonly naturalHeight: number + + /** https://www.adobe.io/xd/uxp/develop/reference/ImageFill/#mimetype */ + readonly mimeType: string + + /** https://www.adobe.io/xd/uxp/develop/reference/ImageFill/#islinkedcontent */ + readonly isLinkedContent: boolean + + } +} \ No newline at end of file diff --git a/xd/scenegraph/InnerShadow.d.ts b/xd/scenegraph/InnerShadow.d.ts new file mode 100644 index 0000000..b1bb259 --- /dev/null +++ b/xd/scenegraph/InnerShadow.d.ts @@ -0,0 +1,11 @@ +declare module 'scenegraph' { + /** [InnerShadow on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/InnerShadow/) */ + export class InnerShadow { + + constructor(x?: number, y?: number, blur?: number, color?: Color, visible?: boolean) + + /** https://www.adobe.io/xd/uxp/develop/reference/InnerShadow/#setshadow */ + setShadow(x?: number, y?: number, blur?: number, color?: Color, visible?: boolean): void + + } +} \ No newline at end of file diff --git a/xd/scenegraph/Line.d.ts b/xd/scenegraph/Line.d.ts new file mode 100644 index 0000000..8660f00 --- /dev/null +++ b/xd/scenegraph/Line.d.ts @@ -0,0 +1,28 @@ +declare module 'scenegraph' { + /** + * [Line on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Line/) + * + * Line leaf node shape. Lines have a stroke but no fill. + */ + export class Line extends GraphicNode { + + /** + * Start point of the Line in local coordinate space. To change the start point, use setStartEnd. + */ + readonly start: Point; + /** + * Endpoint of the Line in local coordinate space. To change the endpoint, use setStartEnd. + */ + readonly end: Point; + + /** + * Set the start and end points of the Line in local coordinate space. The values may be normalized by this setter, shifting the node’s translation and counter-shifting the start/end points. So the start/end setters may return values different from the values you passed this setter, even though the line’s visual bounds and appearance are the same. + */ + setStartEnd( + startX: number, + startY: number, + endX: number, + endY: number + ): void; + } +} \ No newline at end of file diff --git a/xd/scenegraph/LinearGradient.d.ts b/xd/scenegraph/LinearGradient.d.ts new file mode 100644 index 0000000..01df5a8 --- /dev/null +++ b/xd/scenegraph/LinearGradient.d.ts @@ -0,0 +1,60 @@ +declare module 'scenegraph' { + /** + * [LinearGradient on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/LinearGradient/) + * + * In a linear gradient, colors blend smoothly along a straight line, extending out perpendicularly from that line. The gradient fills the entire area of the shape it is applied to. + */ + export class LinearGradient { + + /** + * Create a new LinearGradient instance. + */ + constructor(); + + /** + * Returns a copy of this instance. + */ + clone(): LinearGradient; + + /** + * Array of objects representing each color and its position along the gradient line. The position (stop value) is a number 0.0 - 1.0. + */ + colorStops: { stop: number, color: Color }[] + + /** + * X position of the start of the gradient line, as a multiple of the object's bounding box: X=0 indicates the left edge of the bounding box and X=1 indicates the right edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. + */ + startX: number; + + /** + * Y position of the start of the gradient line, as a multiple of the object's bounding box: Y=0 indicates the top edge of the bounding box and Y=1 indicates the bottom edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. + */ + startY: number; + + /** + * X position of the end of the gradient line, as a multiple of the object's bounding box: X=0 indicates the left edge of the bounding box and X=1 indicates the right edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. + */ + endX: number; + + /** + * Y position of the end of the gradient line, as a multiple of the object's bounding box: Y=0 indicates the top edge of the bounding box and Y=1 indicates the bottom edge. The gradient line may start or end outside the object's bounding box, so values may be < 0 or > 1. + */ + endY: number; + + /** + * Returns an array of [startX, startY, endX, endY]. + */ + getEndPoints(): [number, number, number, number]; // number[]; + + /** + * Shorthand for setting all four start/endpoint properties. + */ + setEndPoints(startX: number, startY: number, endX: number, endY: number): void; + + /** + * @since XD 42 + * String representing the type of the gradient, in this case linear gradient. + */ + type: string + } +} \ No newline at end of file diff --git a/xd/scenegraph/LinkedGraphic.d.ts b/xd/scenegraph/LinkedGraphic.d.ts new file mode 100644 index 0000000..97892b0 --- /dev/null +++ b/xd/scenegraph/LinkedGraphic.d.ts @@ -0,0 +1,8 @@ +declare module 'scenegraph' { + /** + * [LinkedGraphic on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/LinkedGraphic/) + * + * Container node whose content is linked to an external resource, such as Creative Cloud Libraries. It cannot be edited except by first ungrouping it, breaking this link. + */ + export class LinkedGraphic extends SceneNode { } +} diff --git a/xd/scenegraph/Lottie.d.ts b/xd/scenegraph/Lottie.d.ts new file mode 100644 index 0000000..fab9c97 --- /dev/null +++ b/xd/scenegraph/Lottie.d.ts @@ -0,0 +1,10 @@ +declare module 'scenegraph' { + /** + * [Lottie on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Lottie/) + * + * @since XD 45 + * + * Lottie is a vector animation format that can be imported into XD from a JSON file. Within XD, a user will be able to control the playback of Lottie animation. Lottie files are limited to 15 MB. + */ + export class Lottie extends SceneNode { } +} \ No newline at end of file diff --git a/xd/scenegraph/Matrix.d.ts b/xd/scenegraph/Matrix.d.ts new file mode 100644 index 0000000..dc37e2b --- /dev/null +++ b/xd/scenegraph/Matrix.d.ts @@ -0,0 +1,142 @@ +declare module 'scenegraph' { + /** + * [Matrix on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Matrix/) + */ + export class Matrix { + /** + * Creates a new transform matrix with the following structure: + * + * ``` + * | a c e | + * | b d f | + * | 0 0 1 | + * ``` + * + * Note: XD does not generally allow transform matrices with scale or shear (skew) components - only translate and rotate components are typically permitted. + * + * If no arguments, creates a new identity matrix by default. + * + * @param a + * @param b + * @param c + * @param d + * @param e + * @param f + */ + constructor(a: number, b: number, c: number, d: number, e: number, f: number); + + /** + * Copies another matrix's values into this matrix. + * @param otherMatrix The matrix to copy values from. + */ + setFrom(otherMatrix: Matrix): void; + + /** + * Returns a copy of the matrix + */ + clone(): Matrix; + + /** + * Multiplies a passed affine transform to the right: this * M. The result effectively applies the transform of the passed in matrix first, followed by the transform of this matrix second. Modifies this matrix object and also returns it so calls can be chained. + * @param aOrMatrix A Matrix or the `a` component of an affine transform. + * @param b The `b` component of an affine transform. + * @param c The `c` component of an affine transform. + * @param d The `d` component of an affine transform. + * @param e The `e` component of an affine transform. + * @param f The `f` component of an affine transform. + */ + add(aOrMatrix: number | Matrix, b?: number, c?: number, d?: number, e?: number, f?: number): Matrix; + + /** + * Multiplies a passed affine transform to the left: M * this. The result effectively applies the transform of this matrix first, followed by the transform of the passed in matrix second. Modifies this matrix object and also returns it so calls can be chained. + * @param aOrMatrix A Matrix or the a component of an affine transform. + * @param b The b component of an affine transform. + * @param c The c component of an affine transform. + * @param d The d component of an affine transform. + * @param e The e component of an affine transform. + * @param f The f component of an affine transform. + */ + multLeft(aOrMatrix: number | Matrix, b?: number, c?: number, d?: number, e?: number, f?: number): Matrix; + + /** + * Returns an inverted version of the matrix. Returns a brand new matrix - does not modify this matrix object. + */ + invert(): Matrix; + + /** + * Applies translation before the current transform of this matrix, as if using the add() method. Modifies this matrix object and also returns it so calls can be chained. + * @param tx horizontal offset distance + * @param ty vertical offset distance + */ + translate(tx: number, ty: number): Matrix; + + /** + * Applies scaling before the current transform of this matrix, as if using the add() method. Modifies this matrix object and also returns it so calls can be chained. + * + * Note: scale transforms are not generally permitted in XD. + * @param sx amount to be scaled, with 1 resulting in no change + * @param sy amount to scale along the vertical axis. (Otherwise sx applies to both axes.) + * @param cx horizontal origin point from which to scale (if unspecified, scales from the local coordinates' origin point) + * @param cy vertical origin point from which to scale + */ + scale(sx: number, sy?: number, cx?: number, cy?: number): Matrix; + + /** + * Applies clockwise rotation before the current transform of this matrix, as if using the add() method. Modifies this matrix object and also returns it so calls can be chained. + * @param angle angle of rotation, in degrees clockwise + * @param cx horizontal origin point from which to rotate (if unspecified, scales from the local coordinates' origin point) + * @param cy vertical origin point from which to rotate + */ + rotate(angle: number, cx?: number, cy?: number): Matrix; + + /** + * Returns x coordinate of the given point after transformation described by this matrix. See also Matrix.y and Matrix.transformPoint. + * @param x + * @param y + */ + x(x: number, y: number): number; + + /** + * Returns y coordinate of the given point after transformation described by this matrix. See also Matrix.x and Matrix.transformPoint. + * @param x + * @param y + */ + y(x: number, y: number): number; + + /** + * Returns x & y coordinates of the given point after transformation described by this matrix. + * @param point + */ + transformPoint(point: Point): Point; + + /** + * Transforms a rectangle using this matrix, returning the axis-aligned bounds of the resulting rectangle. If this matrix has rotation, then the result will have different width & height from the original rectangle, due to axis alignment. See 'Coordinate Spaces' for some illustrations of this. + * @param rect + */ + transformRect(rect: Bounds): Bounds; + + /** + * @return The translation component of this matrix: [tx, ty]. Equals the `e` and `f` components of this matrix. + */ + getTranslate(): number[] + + /** + * Split the matrix into scale factors. This method assumes that there is no skew in the matrix. + */ + scaleFactors(): { scaleX: number, scaleY: number }; + + /** + * Returns a new matrix that contains only the translate and rotate components of the current matrix, with the given scale factors stripped out. Must be passed the exact scale factors returned by scaleFactors() for this matrix, and this matrix must have no skew/shear component. + * + * Returns a brand new matrix - does not modify this matrix object. + * @param scaleX horizontal scale component to remove + * @param scaleY vertical scale component to remove + */ + removedScaleMatrix(scaleX: number, scaleY: number): Matrix; + + /** + * @return true, if the matrix includes any skew (shear) + */ + hasSkew(): boolean; + } +} diff --git a/xd/scenegraph/Matrix3D.d.ts b/xd/scenegraph/Matrix3D.d.ts new file mode 100644 index 0000000..8b93d29 --- /dev/null +++ b/xd/scenegraph/Matrix3D.d.ts @@ -0,0 +1,241 @@ +declare module 'scenegraph' { + /** + * [Matrix3D on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Matrix3D/) + */ + export class Matrix3D { + + /** + * Creates a new 3D transform matrix with the following structure: + * + * ``` + * | a c m02 e | + * | b d m12 f | + * | m20 m21 m22 mz | + * | 0 0 0 1 | + * ``` + */ + constructor( + a: number, + b: number, + c: number, + d: number, + e: number, + f: number, + m20: number, + m21: number, + m02: number, + m12: number, + m22: number, + z: number + ) + + /** + * Create a new Matrix3D object starting from the given Matrix2D or Matrix3D parameter. + */ + newFrom(m: Matrix | Matrix3D): Matrix3D + + /** + * Copies another matrix's values into this matrix. + */ + setFrom(otherMatrix: Matrix | Matrix3D): void + + /** + * Clone the matrix + */ + clone(): Matrix3D + + /** + * Safely add a mixture of Matrix and Matrix3D without dropping the 3D part. + * + * Returns the addition result which is Matrix if both were Matrix, and Matrix3D otherwise. + */ + add(m1: Matrix | Matrix3D, m2: Matrix | Matrix3D): Matrix | Matrix3D + + /** + * Clears the 3D components of this matrix. Functionally equivalent to converting to a 2D matrix and then back to a 3D one. + */ + clear3D(): void + + /** + * Returns true if we have 3D components in this matrix. + * + * Check if this matrix has 3D components. An efficient of checking if new Matrix3D().setFrom(this.toMatrix()) !== this + */ + strictHas3D(): boolean + + /** + * Check if this matrix has 3D components, with an epsilon. Returns true if we have 3D components in this matrix. + */ + has3D(): boolean + + /** + * Set the 2D components of this matrix and clear the 3D ones. + */ + set6(a: number, b: number, c: number, d: number, e: number, f: number): void + + /** + * Set the identity matrix. + */ + setIdentity(): void + + /** + * + */ + isIdentity(): boolean + + /** + * + */ + isInvertible(): boolean + + /** + * + */ + invert(): Matrix3D + + /** + * + */ + setConcat(a: Matrix3D, b: Matrix3D): Matrix3D + + /** + * + */ + multRight(a: number, b: number, c: number, d: number, e: number, f: number): Matrix3D + + /** + * + */ + multLeft(a: number, b: number, c: number, d: number, e: number, f: number): Matrix3D + + /** + * + */ + translate(tx: number, ty: number, tz: number): Matrix3D + + /** + * + */ + translateLeft(tx: number, ty: number, tz: number): Matrix3D + + /** + * + */ + translateWithPoint(point: Point | Point3D): Matrix3D + + /** + * Get the translate component of this matrix, as an array. + */ + getTranslate(): any[] // ??? + + /** + * + */ + scale(scale: number, sy?: number, sz?: number): Matrix3D + + /** + * + */ + rotate(a: number, x?: number, y?: number): Matrix3D + + /** + * + */ + rotateX(a: number): Matrix3D + + /** + * + */ + rotateY(a: number): Matrix3D + + /** + * + */ + x(x: number, y: number, z?: number): number + + /** + * + */ + y(x: number, y: number, z?: number): number + + /** + * + */ + z(x: number, y: number, z?: number): number + + /** + * + */ + transformPoint(point: Point): Point + + /** + * + */ + transformOrigin(): Point + + /** + * + */ + transformPoint3D(point: Point3D): Point3D + + /** + * + */ + transformRect(rect: Bounds): Bounds + + /** + * + */ + hasSkew(): boolean + + /** + * + */ + hasSkewXZ(): boolean + + /** + * + */ + hasSkewYZ(): boolean + + /** + * + */ + isTranslationOnly(): boolean + + /** + * + */ + getRotation(): number + + /** + * + */ + flip( + flipInfo: { flipX: boolean, flipY: boolean }, + width?: number, + height?: number + ): void + + /** + * + */ + equals(otherMatrix: Matrix3D): boolean + + /** + * + */ + strictEquals(otherMatrix: Matrix3D): boolean + + /** + * + */ + toTransformString(): string + + /** + * + */ + roundToSinglePrecision(): Matrix3D + + } +} \ No newline at end of file diff --git a/xd/scenegraph/Path.d.ts b/xd/scenegraph/Path.d.ts new file mode 100644 index 0000000..7ed7b42 --- /dev/null +++ b/xd/scenegraph/Path.d.ts @@ -0,0 +1,17 @@ +declare module 'scenegraph' { + /** + * [Path on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Path/) + * + * Arbitrary vector Path leaf node shape. Paths can be open or closed, and a Path may include multiple disjoint sections (a.k.a. a 'compound path'). Even open Paths may have a fill - the fill is drawn as if the Path were closed with a final 'Z' segment. + * + * The path may not start at (0,0) in local coordinates, for example if it starts with a move ('M') segment. + */ + export class Path extends GraphicNode { + + /** + * Representation of the path outline in SVG syntax. Unlike other node types, pathData is writable here. Syntax is automatically normalized, so the getter may return a slightly different string than what you passed to the setter. + */ + pathData: string; + + } +} \ No newline at end of file diff --git a/xd/scenegraph/PerPluginStorage.d.ts b/xd/scenegraph/PerPluginStorage.d.ts new file mode 100644 index 0000000..1f83288 --- /dev/null +++ b/xd/scenegraph/PerPluginStorage.d.ts @@ -0,0 +1,50 @@ +declare module 'scenegraph' { + /** + * [PerPluginStorage on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/PerPluginStorage/) + * + * @since XD 29 + */ + export interface PerPluginStorage { + + /** + * + */ + getAll(): Record> + + /** + * + */ + getForPluginId(pluginId: string): Record + + /** + * + */ + keys(pluginId: string): string[] + + /** + * + */ + getItem(pluginId: string, key: string): string | undefined + + /** + * + */ + setItem(pluginId: string, key: string, value?: string): void + + /** + * + */ + removeItem(pluginId: string, key: string): void + + /** + * + */ + toString(): string + + /** + * + */ + toJSON(): Object + + } +} \ No newline at end of file diff --git a/xd/scenegraph/Polygon.d.ts b/xd/scenegraph/Polygon.d.ts new file mode 100644 index 0000000..0d1cdd5 --- /dev/null +++ b/xd/scenegraph/Polygon.d.ts @@ -0,0 +1,67 @@ +declare module 'scenegraph' { + /** + * [Polygon on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Polygon/) + * + * @since XD 19 + * + * 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: 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 is a diamond shape instead. + * + * Like all shape nodes, has no size, fill, or stroke by default unless you set one. + */ + export class Polygon extends GraphicNode { + + /** + * > 0 + */ + width: number; + + /** + * > 0 + */ + height: number; + + /** + * @default 3 + * Number of corners (vertices), and also therefore number of sides. + * + * 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 accommodate. + * * Otherwise, the size and aspect ratio of the shape remains unchanged. + * + * This matches how changing the corner count in XD's UI behaves. + * + * To change corner count while guaranteeing the shape will not change size, save its original size first, set `cornerCount`, and then set size back to the saved values. + */ + cornerCount: number; + + /** + * List of corner radius for each corner of the polygon. To set corner radius, use setAllCornerRadii(). + */ + readonly cornerRadii: number[] + + /** + * True if any of the Polygon's corners is rounded (corner radius > 0). + */ + readonly hasRoundedCorners: boolean; + + /** + * Set the corner radius of all corners of the Polygon to the same value. + * @param radius + */ + setAllCornerRadii(radius: number): void; + + /** + * 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. + */ + starRatio: number + + } +} \ No newline at end of file diff --git a/xd/scenegraph/RadialGradient.d.ts b/xd/scenegraph/RadialGradient.d.ts new file mode 100644 index 0000000..4f56840 --- /dev/null +++ b/xd/scenegraph/RadialGradient.d.ts @@ -0,0 +1,47 @@ +declare module 'scenegraph' { + /** + * [RadialGradient on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/RadialGradient/) + * + * @since XD 42 + * + * In a radial gradient, colors blend smoothly in a radius around a center point. The gradient fills the entire area of the shape it is applied to. + */ + export class RadialGradient { + + /** + * Create a new RadialGradient instance. + */ + constructor() + + /** + * Returns a copy of this instance. + */ + clone(): RadialGradient + + /** + * Array of objects representing each color and its position along the gradient line. The position (stop value) is a number 0.0 - 1.0. + */ + colorStops: { stop: number, color: Color }[] + + /** + * Number representing the gradient radius. The value is multiple of the object's bounding box with condition 0 ≤ endR. + */ + endR: number + + /** + * Returns a point (cx, cy) representing the gradient center. The values are multiple of the object's bounding box: 0 ≤ cx, cy ≤ 1 to position the gradient inside the object's bounding box, or the values may be < 0 or > 1 for a gradient outside the object's bounding box. + */ + getCenterPoint(): Point + + /** + * Method for setting the gradient center. + */ + setCenterPoint(cx: number, cy: number): void + + /** + * String representing the type of the gradient, in this case radial gradient. + */ + type: string + + } +} \ No newline at end of file diff --git a/xd/scenegraph/Rectangle.d.ts b/xd/scenegraph/Rectangle.d.ts new file mode 100644 index 0000000..e28574b --- /dev/null +++ b/xd/scenegraph/Rectangle.d.ts @@ -0,0 +1,51 @@ +declare module 'scenegraph' { + /** + * [Rectangle on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Rectangle/) + * + * Rectangle leaf node shape, with or without rounded corners. Like all shape nodes, has no fill or stroke by default unless you set one. + */ + export class Rectangle extends GraphicNode { + + /** + * value must be >= 0 + */ + width: number; + + /** + * value must be >= 0 + */ + height: number; + + /** + * Default: `{topLeft:0, topRight:0, bottomRight:0, bottomLeft:0}` + * The actual corner radius that is rendered is capped based on the size of the rectangle even if the radius value set here is higher (see {@link effectiveCornerRadii}) + * To set all corners to the same value, use {@link setAllCornerRadii} + */ + cornerRadii: CornerRadii + + /** + * True if any of the Rectangle’s four corners is rounded (corner radius > 0). + */ + readonly hasRoundedCorners: boolean; + + /** + * Set the rounding radius of all four corners of the Rectangle to the same value. The actual corner radius that is rendered is capped based on the size of the rectangle even if the radius value set here is higher (see {@link effectiveCornerRadii}) + * To set the corners to different radius values, use {@link cornerRadii}. + */ + setAllCornerRadii(radius: number): void; + + /** + * The actual corner radius that is rendered may be capped by the size of the rectangle. Returns the actual radii that are currently in effect, which may be smaller than the {@link cornerRadii} values as a result. + */ + effectiveCornerRadii: CornerRadii + + + } + + export type CornerRadii = { + topLeft: number; + topRight: number; + bottomRight: number; + bottomLeft: number; + } +} \ No newline at end of file diff --git a/xd/scenegraph/RepeatGrid.d.ts b/xd/scenegraph/RepeatGrid.d.ts new file mode 100644 index 0000000..2554cdb --- /dev/null +++ b/xd/scenegraph/RepeatGrid.d.ts @@ -0,0 +1,67 @@ +declare module 'scenegraph' { + /** + * [RepeatGrid on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/RepeatGrid/) + * + * Repeat Grid container node containing multiple grid cells, each one a child Group. Changes within one cell are automatically synced to all the other cells - with certain exceptions, called 'overrides.' A Repeat Grid also defines a rectangular clipping mask which determines how may cells are visible (new cells are automatically generated as needed if the Repeat Grid is resized larger). + * Each grid cell is a Group that is an immediate child of the RepeatGrid. These groups are automatically created and destroyed as needed when the RepeatGrid is resized. + * It is not currently possible for plugins to create a new RepeatGrid node, aside from using commands.duplicate to clone existing RepeatGrids. + */ + export class RepeatGrid extends SceneNode { + + /** + * Defines size of the RepeatGrid. Cells are created and destroyed as necessary to fill the current size. Cells that only partially fit will be clipped. + */ + width: number; + + /** + * Defines size of the RepeatGrid. Cells are created and destroyed as necessary to fill the current size. Cells that only partially fit will be clipped. + */ + height: number; + + /** + * Number of grid columns + */ + numColumns: number; + + /** + * Number of grid rows + */ + numRows: number; + + /** + * Horizontal spacing between grid cells/columns + */ + paddingX: number; + + /** + * Vertical spacing between grid cells/rows + */ + paddingY: number; + + /** + * The size of each grid cell. The size of each cell’s content can vary slightly due to text overrides; the cell size is always set to the width of the widest cell content and the height of the tallest cell content. + */ + cellSize: { width: number; height: number }; + + /** + * Attach a sequence of text values to the instances of a given text node across all the cells of a Repeat Grid. The sequence is repeated as necessary to cover all the grid cells. This is a persistent data binding, so if the Repeat Grid is resized later to increase the number of grid cells, items from this sequence will be used to fill the text values of the new cells. + * You can call this API from either of two different edit contexts: + * - Edit context is the parent node of this RepeatGrid (i.e. a context where the RepeatGrid could be selected) + * - Edit context is the RepeatGrid cell which is the parent of textNode (i.e. a context where textNode could be selected) + * @param textNode A Text node exemplar that is an immediate child of one of this RepeatGrid's cells. The data series will be bound to this text node and all corresponding copies of it in the other grid cells. + * @param textValues Array of one or more strings. Empty strings are ignored. + */ + attachTextDataSeries(textNode: Text, textValues: string[]): void; + + /** + * Attach a sequence of image fills to the instances of a given shape node across all the cells of a Repeat Grid. The sequence is repeated as necessary to cover all the grid cells. This is a persistent data binding, so if the Repeat Grid is resized later to increase the number of grid cells, items from this sequence will be used to set the image fill in the new cells. + * You can call this API from either of two different edit contexts: + * - Edit context is the parent node of this RepeatGrid (i.e. a context where the RepeatGrid could be selected) + * - Edit context is the RepeatGrid cell which is the parent of shapeNode (i.e. a context where shapeNode could be selected) + * @param shapeNode A shape node exemplar that is an immediate child of one of this RepeatGrid's cells. The image series will be bound to this node and all corresponding copies of it in the other grid cells. Must be a node type that supports image fills (e.g. Rectangle, but not Text or Line). + * @param images Array of one or more ImageFills. + */ + attachImageDataSeries(shapeNode: GraphicNode, images: ImageFill[]): void; + + } +} \ No newline at end of file diff --git a/xd/scenegraph/RootNode.d.ts b/xd/scenegraph/RootNode.d.ts new file mode 100644 index 0000000..8cb64b9 --- /dev/null +++ b/xd/scenegraph/RootNode.d.ts @@ -0,0 +1,34 @@ +declare module 'scenegraph' { + /** + * [RootNode on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/RootNode/) + * + * Class representing the root node of the document. All Artboards are children of this node, as well as any pasteboard content that does not lie within an Artboard. Artboards must be grouped contiguously at the bottom of this node's z order. The root node has no visual appearance of its own. + */ + export class RootNode extends SceneNode { + /** + * Adds a child node to this container node. You can only add leaf nodes this way; to create structured subtrees of content, use commands. + * @param node Child to add + * @param index Optional: index to insert child at. Child is appended to end of children list (top of z order) otherwise. + */ + addChild(node: SceneNode, index?: number): void; + + /** + * Inserts a child node after the given reference node. + * @param node Child to add + * @param relativeTo New child is added immediately after this existing child + */ + addChildAfter(node: SceneNode, relativeTo: SceneNode): void; + + /** + * Inserts a child node before the given reference node. + * @param node Child to add + * @param relativeTo New child is added immediately before this existing child + */ + addChildBefore(node: SceneNode, relativeTo: SceneNode): void; + + /** + * Removes all children from this node. Equivalent to calling removeFromParent() on each child in turn, but faster. + */ + removeAllChildren(): void; + } +} \ No newline at end of file diff --git a/xd/scenegraph/SceneNode.d.ts b/xd/scenegraph/SceneNode.d.ts new file mode 100644 index 0000000..d2c3052 --- /dev/null +++ b/xd/scenegraph/SceneNode.d.ts @@ -0,0 +1,458 @@ +import { Interaction } from 'interactions'; + +declare module 'scenegraph' { + /** + * [SceneNode on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/SceneNode/) + * + * Base class of all scenegraph nodes. Nodes will always be an instance of some subclass of SceneNode. + */ + export abstract class SceneNode { + + /** + * Returns a unique identifier for this node that stays the same when the file is closed & reopened, or if the node is moved to a different part of the document. Cut-Paste will result in a new guid, however. + */ + readonly guid: string; + + /** + * Returns the parent node. Null if this is the root node, or a freshly constructed node which has not been added to a parent yet. + */ + readonly parent: SceneNode | null; + + /** + * Returns a list of this node’s children. List is length 0 if the node has no children. The first child is lowest in the z order. + * This list is not an Array, so you must use at(i) instead of [i] to access children by index. It has a number of Array-like methods such as forEach() for convenience, however. + * The list is immutable. Use removeFromParent and addChild to add/remove child nodes. + */ + readonly children: SceneNodeList; + + /** + * True if the node’s parent chain connects back to the document root node. + */ + readonly isInArtworkTree: boolean; + + /** + * True if this node is a type that could have children (e.g. an Artboard, Group, Boolean Group, etc.). + */ + readonly isContainer: boolean; + + /** + * True if this node is part of the current selection. To change which nodes are selected, use selection. + */ + readonly selected: boolean; + + /** + * False if this node has been hidden by the user (eyeball toggle in Layers panel). If true, the node may still be invisible for other reasons: a parent or grandparent has visible=false, the node has opacity=0%, the node is clipped by a mask, etc. + */ + visible: boolean; + + /** + * (0.0-1.0)Node’s opacity setting. The overall visual opacity seen on canvas is determined by combining this value with the opacity of the node’s entire parent chain, as well as the opacity settings of its fill/stroke properties if this is a leaf node. + */ + opacity: number; + + /** + * @default 'BLEND_MODE_PASSTHROUGH' + * @since XD 27 + * + * Blend mode determines how a node is composited onto the content below it. + * + * Note: for leaf nodes (GraphicNode), the XD UI may show leaf nodes as blend mode 'Normal' even when the underlying value is BLEND_MODE_PASSTHROUGH. This is because 'Pass Through' and 'Normal' are essentially equivalent for leaf nodes -- they only differ in appearance when a node has children. + * + */ + blendMode: BlendMode + + /** + * Affine transform matrix that converts from the node's local coordinate space to its parent's coordinate space. The matrix never has skew or scale components, and if this node is an Artboard the matrix never has rotation either. Rather than reading the raw matrix values directly, it may be easier to use the translation and rotation properties. + * + * @since XD 40 transform will return a Matrix3D objects for 3D transformed nodes. Again, rather than reading the raw matrix values directly, it may be easier to use the zDepth, rotationX and rotationY for 3D specific properties. + * + * To move or resize a node, use the translation property or APIs like placeInParentCoordinates() or rotateAround(). Setting the entire transform matrix directly is not allowed. To resize a node, use resize(). + * + * For an overview of node transforms & coordinate systems, see Coordinate spaces. + * + * This getter returns a fresh Matrix each time, so its fields can be mutated by the caller without interfering with the node's state. + */ + readonly transform: Matrix | Matrix3D; + + /** + * The translate component of this node’s transform. Since translation is applied after any rotation in the transform Matrix, translation occurs along the parent’s X/Y axes, not the node’s own local X/Y axes. This is equivalent to the e & f fields in the transform Matrix. + * For an overview of node positioning & coordinate systems, see Coordinate spaces. + */ + translation: Point; + + /** + * The rotation component of this node’s transform, in clockwise degrees. + * For an overview of node transforms & coordinate systems, see Coordinate spaces. + */ + readonly rotation: number; + + /** + * The node’s path bounds in document-global coordinate space (represented by a bounding box aligned with global X/Y axes). Path bounds match the selection outline seen in the XD, but exclude some visual parts of the node (outer stroke, drop shadow / blur, etc.). + */ + readonly globalBounds: Bounds; + + /** + * The node’s path bounds in its own local coordinate space. This coordinate space may be rotated and translated relative to the parent’s coordinate space. Path bounds match the selection outline seen in XD, but exclude some visual parts of the node (outerstroke, drop shadow / blur, etc.). + * The visual top-left of a node’s path bounds is located at (localBounds.x, localBounds.y). This value is not necessarily (0,0) in the local coordinate space: for example, a text node’s baseline is at y=0 in local coordinates, so the top of the text has a negative y value. + */ + readonly localBounds: Bounds; + + /** + * The node’s path bounds in its parent’s coordinate space (represented by a bounding box aligned with the parent’s X/Y axes - so if the node has rotation, the top-left of the node is not necessarily located at the top-left of boundsInParent). Path bounds match the selection outline seen in XD, but exclude some visual parts of the node (outer stroke, drop shadow / blur, etc.). + */ + readonly boundsInParent: Bounds; + + /** + * The position of the node’s upper-left corner (localBounds.x, localBounds.y) in its parent’s coordinate space. If the node is rotated, this is not the same as the top-left corner of boundsInParent. This is a shortcut for node.transform.transformPoint({x: node.localBounds.x, y: node.localBounds.y}) + */ + readonly topLeftInParent: Point; + + /** + * The position of the node’s centerpoint in its own local coordinate space. Useful as an argument to rotateAround. This is a shortcut for {x: localBounds.x + localBounds.width/2, y: localBounds.y + localBounds.height/2}) + */ + readonly localCenterPoint: Point; + + /** + * The node’s draw bounds in document-global coordinate space. Draw bounds are larger than the selection outline seen in XD, including outer stroke, drop shadow / blur, etc. - every visible pixel of the node is encompassed by these bounds. This matches the image dimensions if the node is exported as a PNG/JPEG bitmap. + */ + readonly globalDrawBounds: Bounds; + + /** + * Node name as seen in the Layers panel. Also used as filename during export. + */ + name: string; + + /** + * True if name is a generic, auto-generated string (e.g. “Rectangle 5”). False if name has been explicitly set. + */ + readonly hasDefaultName: boolean; + + /** + * True if the node is locked, meaning it cannot normally be selected. + */ + locked: boolean; + + /** + * True if the node should be included in the output of File > export > Batch and other bulk-export workflows. + */ + markedForExport: boolean; + + /** + * @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._ + * + * 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. + */ + fixedWhenScrolling?: boolean; + + /** + * @since XD 19 + * + * Get all interactions that are triggered by this node in the document's interactive prototype. Each element in the array is an Interaction object which describes a gesture/event plus the action it produces. + * + * Note: If this node (or one of its ancestors) has `visible` = false, tap and drag interactions on it will not be triggered. + * + * Currently, this API excludes any keyboard/gamepad interactions on this node. + */ + readonly triggeredInteractions?: Interaction[]; + + /** + * @since XD 38 + * + * Returns a list of this node's children, skipping the background node when present. The list is z-index ordered, from lowest to highest. This list is not an Array, so you must use at(i) instead of [i] to access content children by index. + */ + readonly contentChildren: SceneNodeList + + /** + * @since XD 38 + * + * Encapsulates all the Layout properties: Responsive Resize, Padding and Stacks. By design, the Stack property is conditioned by the presence of Padding property which, in turn, is conditioned by the presence of Responsive Resize property. + */ + layout: LayoutProperties + + /** + * @since XD 29 + * + * Horizontal dynamic-layout settings used with the Responsive Resize feature. Setting this only determines how the node is updated when its parent is resized -- it does not change the node's current size or position. + */ + horizontalConstraints?: HorizontalConstraints + + /** + * @since XD 29 + * + * Vertical dynamic-layout settings used with the Responsive Resize feature. Setting this only determines how the node is updated when its parent is resized -- it does not change the node's current size or position. + */ + verticalConstraints?: VerticalConstraints + + /** + * @since XD 29 + * + * True if this node's Responsive Resize layout settings, which are normally automatically inferred by XD, have been overridden with specific desired values. Constraints on a node are either all overridden, or all automatic -- never mixed. + * + * If false, each time the parent resizes XD will automatically guess the best layout settings to used based on the current size & position of this node within its parent. You can use the horizontalConstraints and verticalConstraints getters to check what computed settings XD would use based on the node's current size & position. + * + * Automatically becomes true any time you set horizontalConstraints or verticalConstraints. To reset to false, call resetToAutoConstraints(). + */ + readonly hasCustomConstraints: boolean + + /** + * @since XD 29 + * + * Erase any overridden Responsive Resize layout settings, restoring the default behavior where XD will automatically guess the best layout settings for this node the next time its parent is resized. This function does not change the node's current size & position, however. + * + * Calling this will cause hasCustomConstraints to become false. + */ + resetToAutoConstraints(): void + + /** + * True if the node's appearance comes from a link to an external resource, such as Creative Cloud Libraries or a separate XD document (in the case of a Linked Component instance). + */ + readonly hasLinkedContent: boolean + + /** + * @since XD 14 + * Metadata specific to your plugin. Must be a value which can be converted to a JSON string, or undefined to clear the stored metadata on this node. + * + * Metadata is persisted with the document when it is saved. Duplicating a node (including across documents, via copy-paste) will duplicate the metadata with it. If the node lies within a Component or Repeat Grid, all instances of the node will have identical metadata (changes in one copy will automatically be synced to the other copy). Metadata stored by this plugin cannot be accessed by other plugins - each plugin has its own isolated metadata storage. + * + * To store general metadata for the document overall, set pluginData on the root node of the scenegraph. Metadata on the root node can be changed from any edit context. + */ + pluginData: any; + + /** + * @since XD 29 + * + * Metadata storage accessible by other plugins, separated into silos by plugin ID. Your plugin can read & write the storage for its own plugin ID, but storage for other plugin IDs is read-only. This property returns a PerPluginStorage API object. + * + * Each scenenode has its own metadata storage. To store general metadata that is not specific to one scenenode, use sharedPluginData on the document's scenegraph root. + * + * Metadata is persisted with the document when it is saved. See pluginMetadata for info on how metadata is duplicated when nodes are copied or synced. + */ + sharedPluginData: PerPluginStorage + + /** + * Remove this node from its parent, effectively deleting it from the document. + */ + removeFromParent(): void; + + /** + * @updated XD 40 + * + * Move the node by the given number of pixels along the parent's X/Y axes (if this node has no rotation, this is identical to moving the node along its own local X/Y axes). This is equivalent to modifying the value returned by 'translation' and then setting it back. + * + * The third parameter, deltaZ (optional), allows the movement of the object on Z axis. + * + * @param deltaX Amount to move along X axis + * @param deltaY Amount to move along Y axis + * @param deltaZ Optional: number of pixels to change depth with + */ + moveInParentCoordinates(deltaX: number, deltaY: number, deltaZ?: number): void; + + /** + * Move the node so the given point in its local coordinates is placed at the given point in its parent’s coordinates (taking into account any rotation on this node, etc.). + * For an overview of node positioning & coordinate systems, see Coordinate spaces. + * @param registrationPoint Point in this node’s local coordinate space to align with parentPoint + * @param parentPoint Point in this node’s parent’s coordinate space to move registrationPoint to + */ + placeInParentCoordinates(registrationPoint: Point, parentPoint: Point): void; + + /** + * @since XD 40 + * + * Move the node so the given point in its local coordinates is placed at the given point in its parent's coordinates (taking into account any rotation on this node, etc.). + * + * If a 2D point is passed as parameter for either registrationPoint or parentPoint it will be treated as a 3D point with z = 0 (a point in node's plane). + * + * @param registrationPoint 2D or 3D point in this node's local coordinate space to align with parentPoint + * @param parentPoint 2D or 3D point in this node's parent's coordinate space to move registrationPoint to + */ + placeInParentCoordinates3D(registrationPoint: Point, parentPoint: Point): void; + + /** + * @since XD 40 + * + * The perspective center component of this node, in parent coordinates. It represents the point in canvas plane where the viewer eye is placed. The perspective center exists for the top level 3D transformed node in a hierarchy and it is null otherwise. + * + * Example: Artboard1 contains a Group1 that contains a Group2 that contains Rectangle1 and Rectangle2. If Group1 is 2D, Group2 is 3D (e.g. rotated 30 deg on Y), Rectangle1 is 2D and Rectangle2 is 3D, the perspective center is set on Group2. For all the others elements the perspectiveCenterInParentCoordinates property is null. + */ + perspectiveCenterInParentCoordinates: Point + + /** + * @since XD 40 + * + * The zDepth component of this node's transform. Since zDepth is applied after any rotation in the transform Matrix, zDepth occurs along the parent's Z axis, not the node's own local Z axis. This is equivalent to the mz field in the transform Matrix. zDepth is 0 for 2D nodes. + * + * If portions of objects are placed at z greater than 800 (e.g. an unrotated shape with zDepth >= 800 or a 90 deg Y-rotated shape having width = 2000) rendering artifacts will appear. + */ + zDepth: number + + /** + * @since XD 40 + * + * Move the node by the given number of pixels along the parent's Z axis (if this node has no 3D rotation, this is identical to moving the node along its own local Z axis). + */ + moveZDepth(deltaZ: number): void + + /** + * Rotate the node clockwise by the given number of degrees around the given point in the plugin’s local coordinate space. If this node already has nonzero rotation, this operation adds to its existing angle. + * @param deltaAngle In degrees. + * @param rotationCenter Point to rotate around, in node’s local coordinates. + */ + rotateAround(deltaAngle: number, rotationCenter: Point): void; + + /** + * @since XD 40 + * + * The rotation around X axis component of this node's transform, in degrees. (A positive rotation on X means the upper side of the object is moving away from the viewer) + */ + readonly rotationX: number + + /** + * @since XD 40 + * + * The rotation around Y axis component of this node's SceneNode, in degrees. (A positive rotation on Y means the right side of the object is moving away from the viewer) + */ + readonly rotationY: number + + /** + * @since XD 40 + * Rotate the node around X axis by the given number of degrees around the given point in the plugin's local coordinate space. If this node already has nonzero rotation on X axis, this operation adds to its existing angle. The rotation around Z and the rotation around Y are left unmodified. The rotations around the 3D axes are applied in the following order: rotation around X axis is applied first, followed by rotation around Y and then rotation around Z (2D rotation) + * @param deltaAngle In degrees + * @param rotationCenter Point to rotate around, in node's local coordinates. + */ + rotateXAround(deltaAngle: number, rotationCenter: Point): void + + /** + * @since XD 40 + * Rotate the node around Y axis by the given number of degrees around the given point in the plugin's local coordinate space. If this node already has nonzero rotation on Y axis, this operation adds to its existing angle. The rotation around Z and the rotation around X are left unmodified. The rotations around the 3D axes are applied in the following order: rotation around X axis is applied first, followed by rotation around Y and then rotation around Z (2D rotation) + * @param deltaAngle In degrees + * @param rotationCenter Point to rotate around, in node's local coordinates. + */ + rotateYAround(deltaAngle: number, rotationCenter: Point): void + + + /** + * Attempts to change localBounds.width & height to match the specified sizes. This operation may not succeed, since some nodes are not resizable. Resizing one dimension may affect the other, if the node’s aspect ratio is locked. + * @param width + * @param height + */ + resize(width: number, height: number): void; + + /** + * @since XD 40 + * @default null + * + * The node's inner shadow, if any. If this property is null or innerShadow.visible is false, no inner shadow is drawn. Artboard, Line and any container object like Group, ScrollableGroup, SymbolInstance and Repeat Grid don't support inner shadow. + * + * To modify an existing inner shadow, always be sure to re-invoke the innerShadow setter rather than just changing the InnerShadow object's properties inline.See 'Properties with object values'. + */ + innerShadow: InnerShadow | null + + + static readonly BLEND_MODE_PASSTHROUGH = 'BLEND_MODE_PASSTHROUGH' + static readonly BLEND_MODE_NORMAL = 'BLEND_MODE_NORMAL' + static readonly BLEND_MODE_MULTIPLY = 'BLEND_MODE_MULTIPLY' + static readonly BLEND_MODE_DARKEN = 'BLEND_MODE_DARKEN' + static readonly BLEND_MODE_COLOR_BURN = 'BLEND_MODE_COLOR_BURN' + static readonly BLEND_MODE_LIGHTEN = 'BLEND_MODE_LIGHTEN' + static readonly BLEND_MODE_SCREEN = 'BLEND_MODE_SCREEN' + static readonly BLEND_MODE_COLOR_DODGE = 'BLEND_MODE_COLOR_DODGE' + static readonly BLEND_MODE_OVERLAY = 'BLEND_MODE_OVERLAY' + static readonly BLEND_MODE_SOFT_LIGHT = 'BLEND_MODE_SOFT_LIGHT' + static readonly BLEND_MODE_HARD_LIGHT = 'BLEND_MODE_HARD_LIGHT' + static readonly BLEND_MODE_DIFFERENCE = 'BLEND_MODE_DIFFERENCE' + static readonly BLEND_MODE_EXCLUSION = 'BLEND_MODE_EXCLUSION' + static readonly BLEND_MODE_HUE = 'BLEND_MODE_HUE' + static readonly BLEND_MODE_SATURATION = 'BLEND_MODE_SATURATION' + static readonly BLEND_MODE_COLOR = 'BLEND_MODE_COLOR' + static readonly BLEND_MODE_LUMINOSITY = 'BLEND_MODE_LUMINOSITY' + + static readonly FIXED_LEFT = 'FIXED_LEFT' + static readonly FIXED_RIGHT = 'FIXED_RIGHT' + static readonly FIXED_TOP = 'FIXED_TOP' + static readonly FIXED_BOTTOM = 'FIXED_BOTTOM' + static readonly FIXED_BOTH = 'FIXED_BOTH' + static readonly POSITION_PROPORTIONAL = 'POSITION_PROPORTIONAL' + + static readonly LAYOUT_NONE = 'LAYOUT_NONE' + static readonly LAYOUT_RESPONSIVE_RESIZE = 'LAYOUT_RESPONSIVE_RESIZE' + static readonly LAYOUT_PADDING = 'LAYOUT_PADDING' + static readonly LAYOUT_STACK = 'LAYOUT_STACK' + + static readonly STACK_HORIZONTAL = 'STACK_HORIZONTAL' + static readonly STACK_VERTICAL = 'STACK_VERTICAL' + + static readonly RESPONSIVE_RESIZE_AUTO = 'RESPONSIVE_RESIZE_AUTO' + static readonly RESPONSIVE_RESIZE_MANUAL = 'RESPONSIVE_RESIZE_MANUAL' + + } + + export type BlendMode = + 'BLEND_MODE_PASSTHROUGH' | + 'BLEND_MODE_NORMAL' | + 'BLEND_MODE_MULTIPLY' | + 'BLEND_MODE_DARKEN' | + 'BLEND_MODE_COLOR_BURN' | + 'BLEND_MODE_LIGHTEN' | + 'BLEND_MODE_SCREEN' | + 'BLEND_MODE_COLOR_DODGE' | + 'BLEND_MODE_OVERLAY' | + 'BLEND_MODE_SOFT_LIGHT' | + 'BLEND_MODE_HARD_LIGHT' | + 'BLEND_MODE_DIFFERENCE' | + 'BLEND_MODE_EXCLUSION' | + 'BLEND_MODE_HUE' | + 'BLEND_MODE_SATURATION' | + 'BLEND_MODE_COLOR' | + 'BLEND_MODE_LUMINOSITY'; + + /** https://www.adobe.io/xd/uxp/develop/reference/SceneNode/#horizontalconstraints */ + export interface HorizontalConstraints { + position: 'FIXED_LEFT' | 'FIXED_RIGHT' | 'FIXED_BOTH' | 'POSITION_PROPORTIONAL' + size: 'SIZE_FIXED' | 'SIZE_RESIZES' + } + + /** https://www.adobe.io/xd/uxp/develop/reference/SceneNode/#verticalconstraints */ + export interface VerticalConstraints { + position: 'FIXED_TOP' | 'FIXED_BOTTOM' | 'FIXED_BOTH' | 'POSITION_PROPORTIONAL' + size: 'SIZE_RESIZES' | 'SIZE_FIXED' + } + + /** top, right, bottom, left, width and height are all Boolean values set to true when enabled. */ + export interface ResizeConstraints { + top: boolean, + right: boolean, + bottom: boolean, + left: boolean, + width: boolean, + height: boolean + } + + /** https://www.adobe.io/xd/uxp/develop/reference/SceneNode/#layout */ + export interface LayoutProperties { + type: 'LAYOUT_NONE' | 'LAYOUT_RESPONSIVE_RESIZE' | 'LAYOUT_PADDING' | 'LAYOUT_STACK' + /** Included if layout type is LAYOUT_STACK */ + stack?: { + orientation: 'STACK_HORIZONTAL' | 'STACK_VERTICAL' + /** a number if each cell is equidistant or an array of spaces between cells in order provided by contentChildren */ + spacings: number[] | number + } + /** Included if layout type is LAYOUT_STACK or LAYOUT_PADDING */ + padding?: { + /** SceneNode used as the background or null if no background set */ + background: SceneNode | null + /** + * top, right, bottom, left are all numbers which determines each side padding amount. + * A single number represents the padding used by all four sides. + */ + values: number | { top: number, right: number, bottom: number, left: number } + } + /** Included if layout type is LAYOUT_STACK, LAYOUT_PADDING or LAYOUT_RESPONSIVE_RESIZE */ + resizeConstraints?: { + type: 'RESPONSIVE_RESIZE_AUTO' | 'RESPONSIVE_RESIZE_MANUAL' + values: ResizeConstraints + } + } + +} \ No newline at end of file diff --git a/xd/scenegraph/SceneNodeList.d.ts b/xd/scenegraph/SceneNodeList.d.ts new file mode 100644 index 0000000..5c485e2 --- /dev/null +++ b/xd/scenegraph/SceneNodeList.d.ts @@ -0,0 +1,65 @@ +declare module 'scenegraph' { + /** + * [SceneNodeList on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/SceneNodeList/) + * + * Represents the children of a SceneNode. Typically accessed via the SceneNode.children property. + * + * This is not an Array, so you must use .at(i) instead of [i] to access children by index. It has a number of Array-like methods such as forEach for convenience, however. For best performance, iterate the list using these methods rather than repeatedly calling at(). + * + * Items in this list are ordered from lowest z order to highest. + */ + export interface SceneNodeList { + + /** + * Number of children in the list. + */ + readonly length: number; + + /** + * Iterate all children in the list. + */ + forEach( + callback: (sceneNode: SceneNode, index: number) => void, + thisArg?: object + ): void; + + /** + * Iterate all children in the list, in reverse order (highest z order to lowest). + */ + forEachRight( + callback: (sceneNode: SceneNode, index: number) => void, + thisArg?: object + ): void; + + /** + * Iterates all children and returns an array of just the children that passed the filter function's test. + */ + filter( + callback: (sceneNode: SceneNode, index: number) => boolean, + thisArg?: object + ): SceneNode[]; + + /** + * Iterates all children and returns an array of the map function's result value for each child node. + */ + map( + callback: (sceneNode: SceneNode, index: number) => any, + thisArg?: object + ): any[]; + + /** + * Iterates children until the test returns true for at least one child. Returns true if the test function returned true for at least one child. + */ + some( + callback: (sceneNode: SceneNode, index: number) => boolean, + thisArg?: object + ): boolean; + + /** + * Returns the child node at the specified index in the list, or null if index is out of bounds. + * + * Note: calling at() repeatedly (e.g. in a for loop) is not as fast as using SceneNodeList's iteration methods such as forEach(), some(), or map(). + */ + at(index: number): SceneNode | null; + } +} \ No newline at end of file diff --git a/xd/scenegraph/ScrollableGroup.d.ts b/xd/scenegraph/ScrollableGroup.d.ts new file mode 100644 index 0000000..d113f4f --- /dev/null +++ b/xd/scenegraph/ScrollableGroup.d.ts @@ -0,0 +1,31 @@ +declare module 'scenegraph' { + /** + * [ScrollableGroup on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/ScrollableGroup/) + * + * @since XD 30 + * + * ScrollableGroup nodes are content that users can interactively scroll around. Content is viewed through a 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. + */ + export class ScrollableGroup extends SceneNode { + + /** + * The type of scrolling: one of ScrollableGroup.VERTICAL, HORIZONTAL and PANNING. PANNING enables scrolling on both axes. + */ + scrollingType: 'VERTICAL' | 'HORIZONTAL' | 'PANNING' // string + + /** + * 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 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 range is visible. The viewport object will only contain offsetY and viewportHeight properties in this case. + */ + viewport: HorizontalScrollViewport | VerticalScrollViewport | PanningScrollViewport + } + + export interface HorizontalScrollViewport { viewportWidth: number, offsetX: number } + export interface VerticalScrollViewport { viewportHeight: number, offsetY: number } + export interface PanningScrollViewport { viewportWidth: number, offsetX: number, viewportHeight: number, offsetY: number } +} \ No newline at end of file diff --git a/xd/scenegraph/Shadow.d.ts b/xd/scenegraph/Shadow.d.ts new file mode 100644 index 0000000..c0c4a78 --- /dev/null +++ b/xd/scenegraph/Shadow.d.ts @@ -0,0 +1,38 @@ +declare module 'scenegraph' { + /** + * [Shadow on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Shadow/) + */ + export class Shadow { + + /** + * Creates a drop shadow style object with the given properties. + */ + constructor(x: number, y: number, blur: number, color: Color, visible?: boolean) + + /** + * X offset of the shadow relative to the shape it is attached to, in global coordinates (i.e. independent of the shape's rotation or any parent's rotation). May be negative. + */ + x: number; + + /** + * Y offset of the shadow relative to the shape it is attached to, in global coordinates (i.e. independent of the shape's rotation or any parent's rotation). May be negative. + */ + y: number; + + /** + * must be >= 0 + */ + blur: number; + + /** + * + */ + color: Color; + + /** + * If false, the shadow is not rendered. The user can toggle this via a checkbox in the Properties panel. + */ + visible: boolean; + + } +} \ No newline at end of file diff --git a/xd/scenegraph/SymbolInstance.d.ts b/xd/scenegraph/SymbolInstance.d.ts new file mode 100644 index 0000000..d12e373 --- /dev/null +++ b/xd/scenegraph/SymbolInstance.d.ts @@ -0,0 +1,28 @@ +declare module 'scenegraph' { + /** + * [SymbolInstance on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/SymbolInstance/) + * + * Container node representing one instance of a Component (previously known as 'Symbols' in XD's UI). Changes made to the contents of a SymbolInstance are treated in one of two ways: + * - If `isMaster` is **false**: The changes affect _only_ this one instance. This creates an 'override': changes made to the corresponding part of the master later will no longer get synced to this particular instance. + * - If `isMaster` is **true**: The changes are automatically synced to all other other instances of the component - _except_ for instances where the affected nodes have instance-specific overrides. As a result, your plugin's batch of edits **may not be applied atomically** in some instances. + * + * To elaborate: if your plugin command makes edits to more than one property or more than one node as part of a single gesture, and the user invokes your plugin while editing a component master, other instances of the component may receive only a _partial application_ of your plugin's changes. In many cases this will feel like a natural consequence of the overrides the user has created, but if this partial application of your plugin's intended changes feels too confusing in your use case, you may opt to warn users or disable some of your plugin's functionality when `selection.editContext` is (or is inside of) a component with `isMaster` true. + * + * Note that overrides vary somewhat in granularity. In some but not all cases, overriding one property may also prevent other properties on the same node from receiving future updates from the master instance. + * + * It is not currently possible for plugins to *create* a new component definition or a new SymbolInstance node, aside from using `require('commands').duplicate` to clone existing SymbolInstances. + */ + export class SymbolInstance extends SceneNode { + + /** + * An identifier unique within this document that is shared by all instances of the same component. + */ + readonly symbolId: string; + + /** + * True if this is the 'master' instance of the component, which forms the template for all new instances. When the user edits the master, those changes are synced to all other instances of the component (unless blocked by 'overrides' + */ + readonly isMaster: boolean; + + } +} diff --git a/xd/scenegraph/Text.d.ts b/xd/scenegraph/Text.d.ts new file mode 100644 index 0000000..17d030f --- /dev/null +++ b/xd/scenegraph/Text.d.ts @@ -0,0 +1,199 @@ +declare module 'scenegraph' { + /** + * [Text on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Text/) + * + * Text leaf node shape. Text can have a fill and/or stroke, but only a solid-color fill is allowed (gradient or image fill will be rejected). + * + * There are three types of Text nodes: + * - Point Text - Expands to fit the full width of the text content. Only uses multiple lines if the text content contains hard line breaks ('\n'). + * - Area Text - Fixed width and height. Text is automatically wrapped (soft line wrapping) to fit the width. If it does not fit the height, any remaining text is clipped. + * - (@since XD 34) Auto-height Text - Fixed width. Text is automatically wrapped (soft line wrapping) to fit the width. The height is expanded to match all the text lines. + * + * Use layoutBox to determine the type of a text node. + * + * Deprecated: XD 34 + * Check whether areaBox is null to determine if the type of a Text node. + * + * Text bounds and layout work differently depending on the type of text: + * - Point Text - The baseline is at y=0 in the node's local coordinate system. Horizontally, local x=0 is the anchor point that the text grows from / shrinks toward when edited. This anchor depends on the justification: for example, if the text is centered, x=0 is the horizontal centerpoint of the text. The bounding box leaves enough space for descenders, uppercase letters, and accent marks, even if the current string does not contain any of those characters. This makes aligning text based on its bounds behave more consistently. + * - Area Text / Auto-height text - The baseline is at a positive y value in local coordinates, and its local (0, 0) is the top left of anchor point the areaBox. Text always flows to the right and down from this local origin regardless of justification. + */ + export class Text extends GraphicNode { + /** + * @default ' ' (a single space character) + * + * The plaintext content of the node, including any hard line breaks but excluding soft line wrap breaks. + * + * Setting text does not change styleRanges, so styles aligned with the old text’s string indices will continue to be applied to the new string’s indices unless you explicitly change styleRanges as well. + */ + text: string; + + /** + * Array of text ranges and their character style settings. Each range covers a set number of characters in the text content. Ranges are contiguous, with each one starting immediately after the previous one. Any characters past the end of the last range use the same style as the last range. + * + * When setting styleRanges, any fields missing from a given range default to the existing values from the last range in the old value of styleRanges. The styleRanges getter always returns fully realized range objects with all fields specified. + */ + styleRanges: { + length: number; + fontFamily: string; + fontStyle: string; + fontSize: number; + fill: Color; + charSpacing: number; + underline: boolean; + strikethrough: boolean; + textTransform: string; + textScript: string; + }[]; + + /** + * @since XD 14 + * + * Set the font family across all style ranges, or get the font family of the last style range (font family of all the text if one range covers all the text). Plugins should not assume any particular default value for fontFamily. + */ + fontFamily: string; + + /** + * @since XD 14 + * @default non-italic normal weight style + * + * Set the font style across all style ranges, or get the font style of the last style range (font style of all the text if one range covers all the text). + */ + fontStyle: string; + + /** + * @since XD 14 + * + * Font size in document pixels. Set the font size across all style ranges, or get the font size of the last style range (font size of all the text if one range covers all the text). Plugins should not assume any particular default value for fontSize. + */ + fontSize: number; + + /** + * @default null + * + * Set the text color across all style ranges, or get the color of the last style range (color of all the text if one range covers all the text). Unlike most other nodes, text only allows a solid color fill - gradients and image fills are not supported. + */ + fill: Color | null; + + /** + * @since XD 14 + * @default 0 + * + * Character spacing in increments of 1/1000th of the fontSize, in addition to the font's default character kerning. May be negative. + * + * Set the character spacing across all style ranges, or get the character spacing of the last style range (character spacing of all the text if one range covers all the text). + */ + charSpacing: number; + + /** + * @since XD 14 + * @default false + * + * Set underline across all style ranges, or get the underline of the last style range (underline of all the text if one range covers all the text). + */ + underline: boolean; + + /** + * @since XD 19 + * @default false + * + * Set strikethrough across all style ranges, or get the strikethrough of the last style range (strikethrough of all the text if one range covers all the text). + */ + strikethrough: boolean; + + /** + * @since XD 19 + * @default 'none' + * + * Set textTransform ('none', 'uppercase', 'lowercase', or 'titlecase') across all style ranges, or get the textTransform of the last style range. + */ + textTransform: 'none' | 'uppercase' | 'lowercase' | 'titlecase'; + + /** + * @since XD 20 + * @default 'none' + * + * Set textScript ('none' or 'superscript' or 'subscript') across all style ranges, or get the textScript of the last style range. + */ + textScript: 'none' | 'superscript' | 'subscript'; + + /** + * If true, the text is drawn upside down. + */ + flipY: boolean; + + /** + * @default Text.ALIGN_LEFT + * + * Horizontal alignment: Text.ALIGN_LEFT, ALIGN_CENTER, or ALIGN_RIGHT. This setting affects the layout of multiline text, and for point text it also affects how the text is positioned relative to its anchor point (x=0 in local coordinates) and what direction the text grows when edited by the user. + * + * Changing textAlign on existing point text will cause it to shift horizontally. To change textAlign while keeping the text in a fixed position, shift the text horizontally (moving its anchor point) to compensate: + */ + textAlign: 'ALIGN_LEFT' | 'ALIGN_CENTER' | 'ALIGN_RIGHT' // string; + static readonly ALIGN_LEFT = 'ALIGN_LEFT'; + static readonly ALIGN_CENTER = 'ALIGN_CENTER'; + static readonly ALIGN_RIGHT = 'ALIGN_RIGHT'; + + /** + * @default 0 + * + * Distance between baselines in multiline text, in document pixels. The special value 0 causes XD to use the default line spacing defined by the font given the current font size & style. + * + * This property is not automatically adjusted when fontSize changes, if line spacing is not set to 0, the line spacing will stay fixed while the font size changes, shifting the spacing’s proportional relationship to font size. If the value is 0, then the rendered line spacing will change to match the new font size, since 0 means the spacing is dynamically calculated from the current font settings. + */ + lineSpacing: number; + + /** + * @since XD 14 + * @default 0 + * + * Additional distance between paragraphs, in document pixels, added to the lineSpacing amount (soft line breaks in area text are separated only by lineSpacing, while hard line breaks are separated by lineSpacing + paragraphSpacing). Unlike lineSpacing, 0 is not a special value; it just means no added spacing. + * + * Similar to {@link lineSpacing}, this property is not automatically adjusted when fontSize changes. The paragraph spacing amount will stay fixed while the font size changes, shifting the spacing's proportional relationship to font size. + */ + paragraphSpacing: number; + + /** + * @deprecated XD 34 - Please use layoutBox which supports all text types. + * + * `Null` for point text. For area text, specifies the size of the rectangle within which text is wrapped and clipped. + * + * Changing point text to area text or vice versa will change the origin / anchor point of the text, thus changing its localBounds, but it will also automatically change the node's transform so its globalBounds and boundsInParent origins remain unchanged. + * + * Changing area text to point text will also automatically insert hard line breaks ('\n') into the text to match the previous line wrapping's appearance exactly. + */ + areaBox: null | { width: number; height: number }; + + + /** + * @since XD 34 + * + * Type: Text.POINT (for point text also referred as auto width), FIXED_HEIGHT (for area text also referred as fixed size) or AUTO_HEIGHT (for the new auto height text) + * + * Width: number between 0-999999. This is ignored and can be omitted for Text.POINT + * + * Height: number between 0-999999. This is ignored and can be omitted for Text.POINT and Text.AUTO_HEIGHT + * + * Changing POINT text to FIXED_HEIGHT or AUTO_HEIGHT text or vice versa will change the origin / anchor point of the text, thus changing its localBounds, but it will also automatically change the node's transform so its globalBounds and boundsInParent origins remain unchanged. + * + * Changing FIXED_HEIGHT or AUTO_HEIGHT text to POINT text will automatically insert hard line break ('\n') into the text to match the previous line wrapping's appearance exactly. + * + * Changing from FIXED_HEIGHT to AUTO_HEIGHT text will automatically change the height of the bounds to match the height of the total text (can be a no-op). + * + * Changing from AUTO_HEIGHT to FIXED_HEIGHT text will not change the bounds, transform or origin (no-op). + */ + layoutBox: { + type: 'POINT' | 'FIXED_HEIGHT' | 'AUTO_HEIGHT', // string, + width?: number, + height?: number + } + static readonly POINT = 'POINT'; + static readonly FIXED_HEIGHT = 'FIXED_HEIGHT'; + static readonly AUTO_HEIGHT = 'AUTO_HEIGHT'; + + /** + * Always false for point text. For area text, true if the text does not fit in the content box and its bottom is being clipped. + */ + readonly clippedByArea: boolean; + } +} diff --git a/xd/scenegraph/Video.d.ts b/xd/scenegraph/Video.d.ts new file mode 100644 index 0000000..c0681a6 --- /dev/null +++ b/xd/scenegraph/Video.d.ts @@ -0,0 +1,18 @@ +declare module 'scenegraph' { + /** + * [Video on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/Video/) + * + * @since XD 45 + * + * Video files can be imported into XD. Within XD, a user can control playback, mute/unmute audio, loop or trim video. + * + * Supported videos: + * - Format: MP4 + * - Codec: H.264 + * - Audio: AAC + * - Maximum file size: 15 MB + * - Maximum resolution: 4K + * - Maximum videos per document: 20 + */ + export class Video extends SceneNode { } +} diff --git a/xd/scenegraph/index.d.ts b/xd/scenegraph/index.d.ts new file mode 100644 index 0000000..8a84a79 --- /dev/null +++ b/xd/scenegraph/index.d.ts @@ -0,0 +1,32 @@ +import './AngularGradient'; +import './Artboard'; +import './Blur'; +import './BooleanGroup'; +import './Color'; +import './Ellipse'; +import './GraphicNode'; +import './Group'; +import './ImageFill'; +import './InnerShadow'; +import './Line'; +import './LinearGradient'; +import './LinkedGraphic'; +import './Lottie'; +import './Matrix'; +import './Matrix3D'; +import './Path'; +import './PerPluginStorage'; +import './Polygon'; +import './RadialGradient'; +import './Rectangle'; +import './RepeatGrid'; +import './RootNode'; +import './scenegraph'; +import './SceneNode'; +import './SceneNodeList'; +import './ScrollableGroup'; +import './selection'; +import './Shadow'; +import './SymbolInstance'; +import './Text'; +import './Video'; \ No newline at end of file diff --git a/xd/scenegraph/scenegraph.d.ts b/xd/scenegraph/scenegraph.d.ts new file mode 100644 index 0000000..2939ce3 --- /dev/null +++ b/xd/scenegraph/scenegraph.d.ts @@ -0,0 +1,57 @@ +/** + * [scenegraph on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/scenegraph/) + * + * The scenegraph is a node tree which represents the structure of the XD document. It closely matches the hierarchy seen in the Layers panel inside XD. Some scenenodes may contain children (e.g., a Group or Artboard), while others are leaf nodes (e.g., a Rectangle or Text node). The root of the scenegraph contains all Artboards that exist in the document, as well as all pasteboard content (nodes that are not contained by any artboard). + * + * You can modify properties on any scenenodes within the current edit context, and add leaf nodes to the current edit context, but you cannot make structural changes directly to the scenegraph tree. Instead, use commands. + * + * Typically, you access scenegraph nodes via the selection argument that is passed to your plugin command, or by traversing the entire document tree using the documentRoot argument that is passed to your plugin command. These objects are also accessible on the scenegraph module for convenience. + */ +declare module 'scenegraph' { + + export interface Point { + x: number; + y: number; + } + + export interface Point3D extends Point{ + z: number; + } + + export interface Bounds { + x: number; + y: number; + width: number; + height: number; + } + + /** + * @since XD 14 + * Object representing the current selection state and edit context. Also available as the first argument passed to your plugin command handler function. + */ + export const selection: Selection; + + /** + * @since XD 14 + * Root node of the current document's scenegraph. Also available as the second argument passed to your plugin command handler function. + */ + export const root: RootNode; + + /** + * __non-standard__ - interface for a plugin's `main.js` `module.exports.commands` + * [Basic Example](https://www.adobe.io/xd/uxp/develop/tutorials/quick-start/#4-create-your-plugins-code) + */ + export interface CommandHandler { + (selection: Selection, root:RootNode): void + } + + /** + * @since XD 28 + * + * Returns the scenenode in this document that has the given node GUID. Returns undefined if no such node exists connected to the scenegraph tree (detached/orphan nodes will not be found). This provides a fast way of persistently remembering a node across plugin operations and even across document open/closes. + * + * @param guid SceneNode GUID -- must be all lowercase, as returned by the guid getter + */ + export function getNodeByGUID(guid:string): SceneNode + +} diff --git a/types/index.d.ts b/xd/scenegraph/selection.d.ts similarity index 72% rename from types/index.d.ts rename to xd/scenegraph/selection.d.ts index 85dff7f..0c0c844 100644 --- a/types/index.d.ts +++ b/xd/scenegraph/selection.d.ts @@ -1,52 +1,4 @@ -import './application'; -import './assets'; -import './clipboard'; -import './cloud'; -import './commands'; -import './interactions'; -import './scenegraph'; -import './uxp'; -import './viewport'; -import {SceneNode, Artboard} from 'scenegraph'; - -declare global { - function require(path:string): any; - - /** - * Represents the children of a scenenode. Typically accessed via the SceneNode.children property. - */ - interface SceneNodeList { - items: SceneNode[]; - readonly length: number; - - forEach( - callback: (sceneNode: SceneNode, index: number) => void, - thisArg?: object - ): void; - - forEachRight( - callback: (sceneNode: SceneNode, index: number) => void, - thisArg?: object - ): void; - - filter( - callback: (sceneNode: SceneNode, index: number) => boolean, - thisArg?: object - ): Array; - - map( - callback: (sceneNode: SceneNode, index: number) => any, - thisArg?: object - ): Array; - - some( - callback: (sceneNode: SceneNode, index: number) => boolean, - thisArg?: object - ): boolean; - - at(index: number): SceneNode | null; - } - +declare module 'scenegraph' { /** * The selection object represents the currently selected set of nodes in the UI. You can set the selection to use it as input for commands, or to determine what is left selected for the user when your plugin’s edit operation completes. * @@ -61,7 +13,7 @@ declare global { * * Items that are locked cannot be in the selection. If the user or your plugin attempts to select any locked items, they are automatically filtered into a separate list (itemsIncludingLocked) which is generally only used by the Unlock command. */ - interface XDSelection { + export interface Selection { /** * Array representing the current selection. Empty array if nothing is selected (never null). Never includes locked nodes. * @@ -71,11 +23,11 @@ declare global { * * Returns a fresh array each time, so this can be mutated by the caller without interfering with anything. Mutating the array does not change the selection - only invoking the ‘items’ setter changes selection. */ - items: Array; + items: SceneNode[]; /** * Array representing the current selection plus any locked items that the user has attempted to select. */ - itemsIncludingLocked: Array; + itemsIncludingLocked: SceneNode[]; /** * True if the selection isn’t empty and consists of one or more non-Artboards. Never true at the same time as hasArtboards. */ @@ -97,4 +49,8 @@ declare global { */ focusedArtboard: Artboard | null | undefined; } -} + + /** alias to scenegraph.Selection to avoid confusiton with native browser Selection */ + export type XDSelection = Selection + +} \ No newline at end of file diff --git a/types/viewport.d.ts b/xd/viewport.d.ts similarity index 81% rename from types/viewport.d.ts rename to xd/viewport.d.ts index f2cac92..d369f8a 100644 --- a/types/viewport.d.ts +++ b/xd/viewport.d.ts @@ -1,25 +1,18 @@ +/** + * [viewport on Adobe.io](https://www.adobe.io/xd/uxp/develop/reference/viewport/) + * + * @since XD 14 + * + * The viewport module represents the current UI view of the XD document's content. + */ declare module 'viewport' { - /** - * The `viewport` module represents the current UI view of the XD document's content. - * Since: XD 14 - */ - import {SceneNode} from "scenegraph"; - - /** - * The current viewport bounds expressed in global coordinates. - */ - export const bounds: { x: number, y: number, width: number, height: number }; - - /** - * The current viewport zoom factor (where 1.0 = 100% zoom, 0.5 = 50% zoom, etc.). - */ - export const zoomFactor: number; + import {SceneNode} from 'scenegraph'; /** * Smoothly pan the viewport to bring the entire given region into view. If the region is already fully in view, does nothing. If the given region is too large to fit entirely in view, it is simply centered (zoom remains unchanged). * * The region can be defined by passing a {@link SceneNode}, or by explicitly specifying a rectangle in global coordinates. - * @param {!SceneNode} node The node that gets scrolled into view + * @param node The node that gets scrolled into view */ export function scrollIntoView(node: SceneNode): void; @@ -36,8 +29,8 @@ declare module 'viewport' { /** * Smoothly pan the viewport to center on a specific point in the document's global coordinates. Even if the point is already in view, the view pans until it is centered. - * @param {number} x The x-coordinate of the centered point (in the document's global coordinates) - * @param {number} y The y-coordinate of the centered point (in the document's global coordinates) + * @param x The x-coordinate of the centered point (in the document's global coordinates) + * @param y The y-coordinate of the centered point (in the document's global coordinates) */ export function scrollToCenter(x: number, y: number): void; @@ -45,7 +38,7 @@ declare module 'viewport' { * Zoom & pan the view as needed so the given region fills the viewport (with some padding). If the region is large, zooms out as needed so it fits entirely in view. If the region is smaller, zooms in so the region fills the entire viewport - may zoom in past 100% to achieve this. * * The region can be defined by passing a {@link SceneNode}, or by explicitly specifying a rectangle in global coordinates. - * @param {!SceneNode} node + * @param node */ export function zoomToRect(node: SceneNode): void; @@ -53,10 +46,20 @@ declare module 'viewport' { * Zoom & pan the view as needed so the given region fills the viewport (with some padding). If the region is large, zooms out as needed so it fits entirely in view. If the region is smaller, zooms in so the region fills the entire viewport - may zoom in past 100% to achieve this. * * The region can be defined by passing a {@link SceneNode}, or by explicitly specifying a rectangle in global coordinates. - * @param {number} x - * @param {number} y - * @param {number} width - * @param {number} height + * @param x + * @param y + * @param width + * @param height */ export function zoomToRect(x: number, y: number, width: number, height: number): void; + + /** + * The current viewport bounds expressed in global coordinates. + */ + export const bounds: { x: number, y: number, width: number, height: number }; + + /** + * The current viewport zoom factor (where 1.0 = 100% zoom, 0.5 = 50% zoom, etc.). + */ + export const zoomFactor: number; }