From d972e1ed71e9093015ef064643d04ccd5c395fa1 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Fri, 26 Sep 2025 20:41:04 +0200 Subject: [PATCH] Add structured info on Penpot API types and class ApiDocs for its representation --- mcp-server/data/api_types.yml | 15449 ++++++++++++++++++++++++++++++++ mcp-server/src/ApiDocs.ts | 121 + 2 files changed, 15570 insertions(+) create mode 100644 mcp-server/data/api_types.yml create mode 100644 mcp-server/src/ApiDocs.ts diff --git a/mcp-server/data/api_types.yml b/mcp-server/data/api_types.yml new file mode 100644 index 0000000..a807036 --- /dev/null +++ b/mcp-server/data/api_types.yml @@ -0,0 +1,15449 @@ +Penpot: + overview: |- + Interface Penpot + ================ + + These are methods and properties available on the `penpot` global object. + + ``` + interface Penpot { + ui: { + open: ((name: string, url: string, options?: { + width: number; + height: number; + }) => void); + size: null | { + width: number; + height: number; + }; + resize: ((width: number, height: number) => void); + sendMessage: ((message: unknown) => void); + onMessage: ((callback: ((message: T) => void)) => void); + }; + utils: ContextUtils; + closePlugin: (() => void); + on(type: T, callback: ((event: EventsMap[T]) => void), props?: { + [key: string]: unknown; + }): symbol; + off(listenerId: symbol): void; + root: null | Shape; + currentFile: null | File; + currentPage: null | Page; + viewport: Viewport; + history: HistoryContext; + library: LibraryContext; + fonts: FontsContext; + currentUser: User; + activeUsers: ActiveUser[]; + theme: Theme; + localStorage: LocalStorage; + selection: Shape[]; + shapesColors(shapes: Shape[]): (Color & ColorShapeInfo)[]; + replaceColor(shapes: Shape[], oldColor: Color, newColor: Color): void; + uploadMediaUrl(name: string, url: string): Promise; + uploadMediaData(name: string, data: Uint8Array, mimeType: string): Promise; + group(shapes: Shape[]): null | Group; + ungroup(group: Group, ...other: Group[]): void; + createRectangle(): Rectangle; + createBoard(): Board; + createEllipse(): Ellipse; + createPath(): Path; + createBoolean(boolType: BooleanType, shapes: Shape[]): null | Boolean; + createShapeFromSvg(svgString: string): null | Group; + createShapeFromSvgWithImages(svgString: string): Promise; + createText(text: string): null | Text; + generateMarkup(shapes: Shape[], options?: { + type?: "html" | "svg"; + }): string; + generateStyle(shapes: Shape[], options?: { + type?: "css"; + withPrelude?: boolean; + includeChildren?: boolean; + }): string; + generateFontFaces(shapes: Shape[]): Promise; + openViewer(): void; + createPage(): Page; + openPage(page: Page): void; + alignHorizontal(shapes: Shape[], direction: "center" | "left" | "right"): void; + alignVertical(shapes: Shape[], direction: "center" | "top" | "bottom"): void; + distributeHorizontal(shapes: Shape[]): void; + distributeVertical(shapes: Shape[]): void; + flatten(shapes: Shape[]): Path[]; + } + ``` + + Hierarchy + + * Omit + + Penpot + members: + Properties: + ui: |- + ``` + ui: { + open: ((name: string, url: string, options?: { + width: number; + height: number; + }) => void); + size: null | { + width: number; + height: number; + }; + resize: ((width: number, height: number) => void); + sendMessage: ((message: unknown) => void); + onMessage: ((callback: ((message: T) => void)) => void); + } + ``` + + Type declaration + + * open: ((name: string, url: string, options?: { width: number; height: number; }) => void) + + Opens the plugin UI. It is possible to develop a plugin without interface (see Palette color example) but if you need, the way to open this UI is using `penpot.ui.open`. + There is a minimum and maximum size for this modal and a default size but it's possible to customize it anyway with the options parameter. + + Example + ``` + penpot.ui.open('Plugin name', 'url', {width: 150, height: 300}); + ``` + + + ``` + (name, url, options?): void + ``` + + - Parameters + * name: string + + title of the plugin, it'll be displayed on the top of the modal + * url: string + + of the plugin + * options: { + width: number; + height: number; + } + + height and width of the modal. + + + width: number + + height: number + + Returns void + * size: null | { width: number; height: number; } + * resize: ((width: number, height: number) => void) + + Resizes the plugin UI. + + Example + ``` + penpot.ui.resize(300, 400); + ``` + + + ``` + (width, height): void + ``` + + - Parameters + * width: number + + The width of the modal. + * height: number + + The height of the modal. + + Returns void + * sendMessage: ((message: unknown) => void) + + Sends a message to the plugin UI. + + Example + ``` + this.sendMessage({ type: 'example-type', content: 'data we want to share' }); + ``` + + + ``` + (message): void + ``` + + - Parameters + * message: unknown + + content usually is an object + + Returns void + * onMessage: ((callback: ((message: T) => void)) => void) + + This is usually used in the `plugin.ts` file in order to handle the data sent by our plugin + + Example + ``` + penpot.ui.onMessage((message) => {if(message.type === 'example-type' { ...do something })}); + ``` + + + ``` + (callback): void + ``` + + - Type Parameters + * T + + Parameters + * callback: ((message: T) => void) + + A function that will be called whenever a message is received. + The function receives a single argument, `message`, which is of type `T`. + + + ``` + (message): void + ``` + + - Parameters + * message: T + + Returns void + + Returns void + utils: |- + ``` + utils: ContextUtils + ``` + + Provides access to utility functions and context-specific operations. + closePlugin: |- + ``` + closePlugin: (() => void) + ``` + + Closes the plugin. When this method is called the UI will be closed. + + Example + ``` + penpot.closePlugin(); + ``` + root: |- + ``` + root: null | Shape + ``` + + The root shape in the current Penpot context. Requires `content:read` permission. + + Example + ``` + const rootShape = context.root;console.log(rootShape); + ``` + currentFile: |- + ``` + currentFile: null | File + ``` + + Retrieves file data from the current Penpot context. Requires `content:read` permission. + + Returns + + Returns the file data or `null` if no file is available. + + Example + ``` + const fileData = context.currentFile;console.log(fileData); + ``` + currentPage: |- + ``` + currentPage: null | Page + ``` + + The current page in the Penpot context. Requires `content:read` permission. + + Example + ``` + const currentPage = context.currentPage;console.log(currentPage); + ``` + viewport: |- + ``` + viewport: Viewport + ``` + + The viewport settings in the Penpot context. + + Example + ``` + const viewportSettings = context.viewport;console.log(viewportSettings); + ``` + history: |- + ``` + history: HistoryContext + ``` + + Context encapsulating the history operations + + Example + ``` + const historyContext = context.history;console.log(historyContext); + ``` + library: |- + ``` + library: LibraryContext + ``` + + The library context in the Penpot context, including both local and connected libraries. Requires `library:read` permission. + + Example + ``` + const libraryContext = context.library;console.log(libraryContext); + ``` + fonts: |- + ``` + fonts: FontsContext + ``` + + The fonts context in the Penpot context, providing methods to manage fonts. Requires `content:read` permission. + + Example + ``` + const fontsContext = context.fonts;console.log(fontsContext); + ``` + currentUser: |- + ``` + currentUser: User + ``` + + The current user in the Penpot context. Requires `user:read` permission. + + Example + ``` + const currentUser = context.currentUser;console.log(currentUser); + ``` + activeUsers: |- + ``` + activeUsers: ActiveUser[] + ``` + + An array of active users in the Penpot context. Requires `user:read` permission. + + Example + ``` + const activeUsers = context.activeUsers;console.log(activeUsers); + ``` + theme: |- + ``` + theme: Theme + ``` + + The current theme (light or dark) in Penpot. + + Example + ``` + const currentTheme = context.theme;console.log(currentTheme); + ``` + localStorage: |- + ``` + localStorage: LocalStorage + ``` + + Access to the localStorage proxy + selection: |- + ``` + selection: Shape[] + ``` + + The currently selected shapes in Penpot. Requires `content:read` permission. + + Example + ``` + const selectedShapes = context.selection;console.log(selectedShapes); + ``` + Methods: + on: |- + ``` + on(type, callback, props?): symbol + ``` + + * Adds an event listener for the specified event type. + Subscribing to events requires `content:read` permission. + + The following are the possible event types: + + + pagechange: event emitted when the current page changes. The callback will receive the new page. + + shapechange: event emitted when the shape changes. This event requires to send inside the `props` object the shape + that will be observed. For example: + ``` + // Observe the current selected shapepenpot.on('shapechange', (shape) => console.log(shape.name), { shapeId: penpot.selection[0].id }); + ``` + + + selectionchange: event emitted when the current selection changes. The callback will receive the list of ids for the new selection + + themechange: event emitted when the user changes its theme. The callback will receive the new theme (currently: either `dark` or `light`) + + documentsaved: event emitted after the document is saved in the backend. + + Type Parameters + + T extends keyof EventsMap + + Parameters + + type: T + + The event type to listen for. + + callback: ((event: EventsMap[T]) => void) + + The callback function to execute when the event is triggered. + + - ``` + (event): void + ``` + + * Parameters + + event: EventsMap[T] + + Returns void + + props: { + [key: string]: unknown; + } + + The properties for the current event handler. Only makes sense for specific events. + + - [key: string]: unknown + + Returns symbol + + the listener id that can be used to call `off` and cancel the listener + + Example + ``` + penpot.on('pagechange', () => {...do something}). + ``` + off: |- + ``` + off(listenerId): void + ``` + + * Removes an event listener for the specified event type. + + Parameters + + listenerId: symbol + + the id returned by the `on` method when the callback was set + + Returns void + + Example + ``` + const listenerId = penpot.on('contentsave', () => console.log("Changed"));penpot.off(listenerId); + ``` + shapesColors: |- + ``` + shapesColors(shapes): (Color & ColorShapeInfo)[] + ``` + + * Retrieves colors applied to the given shapes in Penpot. Requires `content:read` permission. + + Parameters + + shapes: Shape[] + + Returns (Color & ColorShapeInfo)[] + + Returns an array of colors and their shape information. + + Example + ``` + const colors = context.shapesColors(shapes);console.log(colors); + ``` + replaceColor: |- + ``` + replaceColor(shapes, oldColor, newColor): void + ``` + + * Replaces a specified old color with a new color in the given shapes. Requires `content:write` permission. + + Parameters + + shapes: Shape[] + + oldColor: Color + + newColor: Color + + Returns void + + Example + ``` + context.replaceColor(shapes, oldColor, newColor); + ``` + uploadMediaUrl: |- + ``` + uploadMediaUrl(name, url): Promise + ``` + + * Uploads media to Penpot and retrieves its image data. Requires `content:write` permission. + + Parameters + + name: string + + The name of the media. + + url: string + + The URL of the media to be uploaded. + + Returns Promise + + Returns a promise that resolves to the image data of the uploaded media. + + Example + ``` + const imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');console.log(imageData);// to insert the image in a shape we can doconst board = penpot.createBoard();const shape = penpot.createRectangle();board.appendChild(shape);shape.fills = [{ fillOpacity: 1, fillImage: imageData }]; + ``` + uploadMediaData: |- + ``` + uploadMediaData(name, data, mimeType): Promise + ``` + + * Uploads media to penpot and retrieves the image data. Requires `content:write` permission. + + Parameters + + name: string + + The name of the media. + + data: Uint8Array + + The image content data + + mimeType: string + + Returns Promise + + Returns a promise that resolves to the image data of the uploaded media. + + Example + ``` + const imageData = await context.uploadMediaData('example', imageData, 'image/jpeg');console.log(imageData); + ``` + group: |- + ``` + group(shapes): null | Group + ``` + + * Groups the specified shapes. Requires `content:write` permission. + + Parameters + + shapes: Shape[] + + An array of shapes to group. + + Returns null | Group + + Returns the newly created group or `null` if the group could not be created. + + Example + ``` + const penpotShapesArray = penpot.selection;penpot.group(penpotShapesArray); + ``` + ungroup: |- + ``` + ungroup(group, ...other): void + ``` + + * Ungroups the specified group. Requires `content:write` permission. + + Parameters + + group: Group + + The group to ungroup. + + ...other: Group[] + + Additional groups to ungroup. + + Returns void + + Example + ``` + const penpotShapesArray = penpot.selection;// We need to make sure that something is selected, and if the selected shape is a group,if (selected.length && penpot.utils.types.isGroup(penpotShapesArray[0])) { penpot.group(penpotShapesArray[0]);} + ``` + createRectangle: |- + ``` + createRectangle(): Rectangle + ``` + + * Use this method to create the shape of a rectangle. Requires `content:write` permission. + + Returns Rectangle + + Example + ``` + const shape = penpot.createRectangle();// just change the values like thisshape.name = "Example rectangle";// for solid colorshape.fills = [{ fillColor: "#7EFFF5" }];// for linear gradient colorshape.fills = [{ fillColorGradient: { "type": "linear", "startX": 0.5, "startY": 0, "endX": 0.5, "endY": 1, "width": 1, "stops": [ { "color": "#003ae9", "opacity": 1, "offset": 0 }, { "color": "#003ae9", "opacity": 0, "offset": 1 } ] }}];// for a image fillconst imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');shape.fills = [{ fillOpacity: 1, fillImage: imageData }];shape.borderRadius = 8;shape.strokes = [ { strokeColor: "#2e3434", strokeStyle: "solid", strokeWidth: 2, strokeAlignment: "center", },]; + ``` + createBoard: |- + ``` + createBoard(): Board + ``` + + * Use this method to create a board. This is the first step before anything else, the container. Requires `content:write` permission. + Then you can add a gridlayout, flexlayout or add a shape inside the board. + Just a heads-up: board is a board in Penpot UI. + + Returns Board + + Example + ``` + const board = penpot.createBoard();// to add grid layoutboard.addGridLayout();// to add flex layoutboard.addFlexLayout();// to create a shape inside the boardconst shape = penpot.createRectangle();board.appendChild(shape); + ``` + createEllipse: |- + ``` + createEllipse(): Ellipse + ``` + + * Use this method to create the shape of an ellipse. Requires `content:write` permission. + + Returns Ellipse + + Example + ``` + const shape = penpot.createEllipse();// just change the values like thisshape.name = "Example ellipse";// for solid colorshape.fills = [{ fillColor: "#7EFFF5" }];// for linear gradient colorshape.fills = [{ fillColorGradient: { "type": "linear", "startX": 0.5, "startY": 0, "endX": 0.5, "endY": 1, "width": 1, "stops": [ { "color": "#003ae9", "opacity": 1, "offset": 0 }, { "color": "#003ae9", "opacity": 0, "offset": 1 } ] }}];// for an image fillconst imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');shape.fills = [{ fillOpacity: 1, fillImage: imageData }];shape.strokes = [ { strokeColor: "#2e3434", strokeStyle: "solid", strokeWidth: 2, strokeAlignment: "center", },]; + ``` + createPath: |- + ``` + createPath(): Path + ``` + + * Use this method to create a path. Requires `content:write` permission. + + Returns Path + + Example + ``` + const path = penpot.createPath();path.name = "My path";// for solid colorpath.fills = [{ fillColor: "#7EFFF5" }]; + ``` + createBoolean: |- + ``` + createBoolean(boolType, shapes): null | Boolean + ``` + + * Creates a Boolean shape based on the specified boolean operation and shapes. Requires `content:write` permission. + + Parameters + + boolType: BooleanType + + The type of boolean operation ('union', 'difference', 'exclude', 'intersection'). + + shapes: Shape[] + + An array of shapes to perform the boolean operation on. + + Returns null | Boolean + + Returns the newly created Boolean shape resulting from the boolean operation. + + Example + ``` + const booleanShape = context.createBoolean('union', [shape1, shape2]); + ``` + createShapeFromSvg: |- + ``` + createShapeFromSvg(svgString): null | Group + ``` + + * Creates a Group from an SVG string. Requires `content:write` permission. + + Parameters + + svgString: string + + The SVG string representing the shapes to be converted into a group. + + Returns null | Group + + Returns the newly created Group containing the shapes from the SVG. + + Example + ``` + const svgGroup = context.createShapeFromSvg('...'); + ``` + createShapeFromSvgWithImages: |- + ``` + createShapeFromSvgWithImages(svgString): Promise + ``` + + * Creates a Group from an SVG string. The SVG can have images and the method returns + a Promise because the shape will be available after all images are uploaded. + Requires `content:write` permission. + + Parameters + + svgString: string + + The SVG string representing the shapes to be converted into a group. + + Returns Promise + + Returns a promise with the newly created Group containing the shapes from the SVG. + + Example + ``` + const svgGroup = await context.createShapeFromSvgWithImages('...'); + ``` + createText: |- + ``` + createText(text): null | Text + ``` + + * Creates a Text shape with the specified text content. Requires `content:write` permission. + + Parameters + + text: string + + The text content for the Text shape. + + Returns null | Text + + Returns the new created shape, if the shape wasn't created can return null. + + Example + ``` + const board = penpot.createBoard();let text;text = penpot.createText();// just change the values like thistext.growType = 'auto-height';text.fontFamily = 'Work Sans';text.fontSize = '12';text.fills = [{fillColor: '#9f05ff', fillOpacity: 1}];text.strokes = [{strokeOpacity: 1, strokeStyle: 'solid', strokeWidth: 2, strokeColor: '#deabff', strokeAlignment: 'outer'}];board.appendChild(text); + ``` + generateMarkup: |- + ``` + generateMarkup(shapes, options?): string + ``` + + * Generates markup for the given shapes. Requires `content:read` permission + + Parameters + + shapes: Shape[] + + options: { + type?: "html" | "svg"; + } + - Optionaltype?: "html" | "svg" + + Returns string + + Example + ``` + const markup = context.generateMarkup(shapes, { type: 'html' });console.log(markup); + ``` + generateStyle: |- + ``` + generateStyle(shapes, options?): string + ``` + + * Generates styles for the given shapes. Requires `content:read` permission + + Parameters + + shapes: Shape[] + + options: { + type?: "css"; + withPrelude?: boolean; + includeChildren?: boolean; + } + - Optionaltype?: "css" + - OptionalwithPrelude?: boolean + - OptionalincludeChildren?: boolean + + Returns string + + Example + ``` + const styles = context.generateStyle(shapes, { type: 'css' });console.log(styles); + ``` + generateFontFaces: |- + ``` + generateFontFaces(shapes): Promise + ``` + + * Generates the fontfaces styles necessaries to render the shapes. + Requires `content:read` permission + + Parameters + + shapes: Shape[] + + Returns Promise + + Example + ``` + const fontfaces = context.generateFontFaces(penpot.selection);console.log(fontfaces); + ``` + openViewer: |- + ``` + openViewer(): void + ``` + + * Opens the viewer section. Requires `content:read` permission. + + Returns void + createPage: |- + ``` + createPage(): Page + ``` + + * Creates a new page. Requires `content:write` permission. + + Returns Page + openPage: |- + ``` + openPage(page): void + ``` + + * Changes the current open page to given page. Requires `content:read` permission. + + Parameters + + page: Page + + the page to open + + Returns void + + Example + ``` + context.openPage(page); + ``` + alignHorizontal: |- + ``` + alignHorizontal(shapes, direction): void + ``` + + * Aligning will move all the selected layers to a position relative to one + of them in the horizontal direction. + + Parameters + + shapes: Shape[] + + to align + + direction: "center" | "left" | "right" + + where the shapes will be aligned + + Returns void + alignVertical: |- + ``` + alignVertical(shapes, direction): void + ``` + + * Aligning will move all the selected layers to a position relative to one + of them in the vertical direction. + + Parameters + + shapes: Shape[] + + to align + + direction: "center" | "top" | "bottom" + + where the shapes will be aligned + + Returns void + distributeHorizontal: |- + ``` + distributeHorizontal(shapes): void + ``` + + * Distributing objects to position them horizontally with equal distances between them. + + Parameters + + shapes: Shape[] + + to distribute + + Returns void + distributeVertical: |- + ``` + distributeVertical(shapes): void + ``` + + * Distributing objects to position them vertically with equal distances between them. + + Parameters + + shapes: Shape[] + + to distribute + + Returns void + flatten: |- + ``` + flatten(shapes): Path[] + ``` + + * Converts the shapes into Paths. If the shapes are complex will put together + all its paths into one. + + Parameters + + shapes: Shape[] + + to flatten + + Returns Path[] +ActiveUser: + overview: |- + Interface ActiveUser + ==================== + + Represents an active user in Penpot, extending the `User` interface. + This interface includes additional properties specific to active users. + + ``` + interface ActiveUser { + position?: { + x: number; + y: number; + }; + zoom?: number; + id: string; + name?: string; + avatarUrl?: string; + color: string; + sessionId?: string; + } + ``` + + Hierarchy (view full) + + * User + + ActiveUser + members: + Properties: + position: |- + ``` + position?: { + x: number; + y: number; + } + ``` + + The position of the active user. + + Example + ``` + const userPosition = activeUser.position;console.log(userPosition); + ``` + zoom: |- + ``` + zoom?: number + ``` + + The zoom level of the active user. + + Example + ``` + const userZoom = activeUser.zoom;console.log(userZoom); + ``` + id: |- + ``` + id: string + ``` + + The unique identifier of the user. + + Example + ``` + const userId = user.id;console.log(userId); + ``` + name: |- + ``` + name?: string + ``` + + The name of the user. + + Example + ``` + const userName = user.name;console.log(userName); + ``` + avatarUrl: |- + ``` + avatarUrl?: string + ``` + + The URL of the user's avatar image. + + Example + ``` + const avatarUrl = user.avatarUrl;console.log(avatarUrl); + ``` + color: |- + ``` + color: string + ``` + + The color associated with the user. + + Example + ``` + const userColor = user.color;console.log(userColor); + ``` + sessionId: |- + ``` + sessionId?: string + ``` + + The session ID of the user. + + Example + ``` + const sessionId = user.sessionId;console.log(sessionId); + ``` +Blur: + overview: |- + Interface Blur + ============== + + Represents blur properties in Penpot. + This interface includes properties for defining the type and intensity of a blur effect, along with its visibility. + + ``` + interface Blur { + id?: string; + type?: "layer-blur"; + value?: number; + hidden?: boolean; + } + ``` + members: + Properties: + id: |- + ``` + id?: string + ``` + + The optional unique identifier for the blur effect. + type: |- + ``` + type + ``` + + The optional type of the blur effect. + Currently, only 'layer-blur' is supported. + value: |- + ``` + value?: number + ``` + + The optional intensity value of the blur effect. + hidden: |- + ``` + hidden?: boolean + ``` + + Specifies whether the blur effect is hidden. + Defaults to false if omitted. +Board: + overview: |- + Interface Board + =============== + + Represents a board in Penpot. + This interface extends `ShapeBase` and includes properties and methods specific to board. + + ``` + interface Board { + type: "board"; + clipContent: boolean; + showInViewMode: boolean; + grid?: GridLayout; + flex?: FlexLayout; + guides: Guide[]; + rulerGuides: RulerGuide[]; + horizontalSizing?: "auto" | "fix"; + verticalSizing?: "auto" | "fix"; + fills: Fill[]; + children: Shape[]; + appendChild(child: Shape): void; + insertChild(index: number, child: Shape): void; + addFlexLayout(): FlexLayout; + addGridLayout(): GridLayout; + addRulerGuide(orientation: RulerGuideOrientation, value: number): RulerGuide; + removeRulerGuide(guide: RulerGuide): void; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Board + members: + Properties: + type: |- + ``` + type + ``` + + The type of the shape, which is always 'board' for boards. + clipContent: |- + ``` + clipContent: boolean + ``` + + When true the board will clip the children inside + showInViewMode: |- + ``` + showInViewMode: boolean + ``` + + WHen true the board will be displayed in the view mode + grid: |- + ``` + grid?: GridLayout + ``` + + The grid layout configuration of the board, if applicable. + flex: |- + ``` + flex?: FlexLayout + ``` + + The flex layout configuration of the board, if applicable. + guides: |- + ``` + guides: Guide[] + ``` + + The guides associated with the board. + rulerGuides: |- + ``` + rulerGuides: RulerGuide[] + ``` + + The ruler guides attached to the board + horizontalSizing: |- + ``` + horizontalSizing?: "auto" | "fix" + ``` + + The horizontal sizing behavior of the board. + verticalSizing: |- + ``` + verticalSizing?: "auto" | "fix" + ``` + + The vertical sizing behavior of the board. + fills: |- + ``` + fills: Fill[] + ``` + + The fills applied to the shape. + + Overrides ShapeBase.fills + children: |- + ``` + children: Shape[] + ``` + + The children shapes contained within the board. + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + appendChild: |- + ``` + appendChild(child): void + ``` + + * Appends a child shape to the board. + + Parameters + + child: Shape + + The child shape to append. + + Returns void + + Example + ``` + board.appendChild(childShape); + ``` + insertChild: |- + ``` + insertChild(index, child): void + ``` + + * Inserts a child shape at the specified index within the board. + + Parameters + + index: number + + The index at which to insert the child shape. + + child: Shape + + The child shape to insert. + + Returns void + + Example + ``` + board.insertChild(0, childShape); + ``` + addFlexLayout: |- + ``` + addFlexLayout(): FlexLayout + ``` + + * Adds a flex layout configuration to the board (so it's necessary to create a board first of all). + + Returns FlexLayout + + Returns the flex layout configuration added to the board. + + Example + ``` + const board = penpot.createBoard();const flex = board.addFlexLayout();// You can change the flex properties as follows.flex.dir = "column";flex.wrap = "wrap";flex.alignItems = "center";flex.justifyContent = "center";flex.horizontalSizing = "fill";flex.verticalSizing = "fill"; + ``` + addGridLayout: |- + ``` + addGridLayout(): GridLayout + ``` + + * Adds a grid layout configuration to the board (so it's necessary to create a board first of all). You can add rows and columns, check addRow/addColumn. + + Returns GridLayout + + Returns the grid layout configuration added to the board. + + Example + ``` + const board = penpot.createBoard();const grid = board.addGridLayout();// You can change the grid properties as follows.grid.alignItems = "center";grid.justifyItems = "start";grid.rowGap = 10;grid.columnGap = 10;grid.verticalPadding = 5;grid.horizontalPadding = 5 + ``` + addRulerGuide: |- + ``` + addRulerGuide(orientation, value): RulerGuide + ``` + + * Creates a new ruler guide. + + Parameters + + orientation: RulerGuideOrientation + + value: number + + Returns RulerGuide + removeRulerGuide: |- + ``` + removeRulerGuide(guide): void + ``` + + * Removes the `guide` from the current page. + + Parameters + + guide: RulerGuide + + Returns void + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +Boolean: + overview: |- + Interface Boolean + ================= + + Represents a boolean operation shape in Penpot. + This interface extends `ShapeBase` and includes properties and methods specific to boolean operations. + + ``` + interface Boolean { + type: "boolean"; + toD(): string; + content: PathCommand[]; + fills: Fill[]; + children: Shape[]; + appendChild(child: Shape): void; + insertChild(index: number, child: Shape): void; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Boolean + members: + Properties: + type: |- + ``` + type + ``` + + The type of the shape, which is always 'bool' for boolean operation shapes. + content: |- + ``` + content: PathCommand[] + ``` + + The content of the boolean shape, defined as an array of path commands. + fills: |- + ``` + fills: Fill[] + ``` + + The fills applied to the shape. + + Overrides ShapeBase.fills + children: |- + ``` + children: Shape[] + ``` + + The children shapes contained within the boolean shape. + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + toD: |- + ``` + toD(): string + ``` + + * Converts the boolean shape to its path data representation. + + Returns string + + Returns the path data (d attribute) as a string. + appendChild: |- + ``` + appendChild(child): void + ``` + + * Appends a child shape to the boolean shape. + + Parameters + + child: Shape + + The child shape to append. + + Returns void + + Example + ``` + boolShape.appendChild(childShape); + ``` + insertChild: |- + ``` + insertChild(index, child): void + ``` + + * Inserts a child shape at the specified index within the boolean shape. + + Parameters + + index: number + + The index at which to insert the child shape. + + child: Shape + + The child shape to insert. + + Returns void + + Example + ``` + boolShape.insertChild(0, childShape); + ``` + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +CloseOverlay: + overview: |- + Interface CloseOverlay + ====================== + + This action will close a targeted board that is opened as an overlay. + + ``` + interface CloseOverlay { + type: "close-overlay"; + destination?: Board; + animation: Animation; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + The action type + destination: |- + ``` + destination?: Board + ``` + + The overlay to be closed with this action. + animation: |- + ``` + animation: Animation + ``` + + Animation displayed with this interaction. +Color: + overview: |- + Interface Color + =============== + + Represents color properties in Penpot. + This interface includes properties for defining solid colors, gradients, and image fills, along with metadata. + + ``` + interface Color { + id?: string; + fileId?: string; + name?: string; + path?: string; + color?: string; + opacity?: number; + refId?: string; + refFile?: string; + gradient?: Gradient; + image?: ImageData; + } + ``` + members: + Properties: + id: |- + ``` + id?: string + ``` + + The optional reference ID for an external color definition. + fileId: |- + ``` + fileId?: string + ``` + + The optional reference to an external file for the color definition. + name: |- + ``` + name?: string + ``` + + The optional name of the color. + path: |- + ``` + path?: string + ``` + + The optional path or category to which this color belongs. + color: |- + ``` + color?: string + ``` + + The optional solid color, represented as a string (e.g., '#FF5733'). + opacity: |- + ``` + opacity?: number + ``` + + The optional opacity level of the color, ranging from 0 (fully transparent) to 1 (fully opaque). + Defaults to 1 if omitted. + refId: |- + ``` + refId?: string + ``` + + The optional reference ID for an external color definition. + + Deprecated + + Use `id` instead + refFile: |- + ``` + refFile?: string + ``` + + The optional reference to an external file for the color definition. + + Deprecated + + Use `fileId` + gradient: |- + ``` + gradient?: Gradient + ``` + + The optional gradient fill defined by a Gradient object. + image: |- + ``` + image?: ImageData + ``` + + The optional image fill defined by an ImageData object. +ColorShapeInfo: + overview: |- + Interface ColorShapeInfo + ======================== + + Additional color information for the methods to extract colors from a list of shapes. + + ``` + interface ColorShapeInfo { + shapesInfo: ColorShapeInfoEntry[]; + } + ``` + members: + Properties: + shapesInfo: |- + ``` + shapesInfo: ColorShapeInfoEntry[] + ``` + + List of shapes with additional information +ColorShapeInfoEntry: + overview: |- + Interface ColorShapeInfoEntry + ============================= + + Entry for the color shape additional information. + + ``` + interface ColorShapeInfoEntry { + property: string; + index?: number; + shapeId: string; + } + ``` + members: + Properties: + property: |- + ``` + property: string + ``` + + Property that has the color (example: fill, stroke...) + index: |- + ``` + index?: number + ``` + + For properties that are indexes (such as fill) represent the index + of the color inside that property. + shapeId: |- + ``` + shapeId: string + ``` + + Identifier of the shape that contains the color +Comment: + overview: |- + Interface Comment + ================= + + Comments allow the team to have one priceless conversation getting and + providing feedback right over the designs and prototypes. + + ``` + interface Comment { + user: User; + date: Date; + content: string; + remove(): void; + } + ``` + members: + Properties: + user: |- + ``` + user: User + ``` + + The `user` that has created the comment. + date: |- + ``` + date: Date + ``` + + The `date` the comment has been created. + content: |- + ``` + content: string + ``` + + The `content` for the commentary. The owner can modify the comment. + Methods: + remove: |- + ``` + remove(): void + ``` + + * Remove the current comment from its comment thread. Only the owner can remove their comments. + Requires the `comment:write` permission. + + Returns void +CommentThread: + overview: |- + Interface CommentThread + ======================= + + Represents a list of comments one after the other. Usually these threads + are conversations the users have in Penpot. + + ``` + interface CommentThread { + seqNumber: number; + board?: Board; + owner?: User; + position: Point; + resolved: boolean; + findComments(): Promise; + reply(content: string): Promise; + remove(): void; + } + ``` + members: + Properties: + seqNumber: |- + ``` + seqNumber: number + ``` + + This is the number that is displayed on the workspace. Is an increasing + sequence for each comment. + board: |- + ``` + board?: Board + ``` + + If the thread is attached to a `board` this will have that board + reference. + owner: |- + ``` + owner?: User + ``` + + Owner of the comment thread + position: |- + ``` + position: Point + ``` + + The `position` in absolute coordinates in the canvas. + resolved: |- + ``` + resolved: boolean + ``` + + Whether the thread has been marked as `resolved` or not. + Methods: + findComments: |- + ``` + findComments(): Promise + ``` + + * List of `comments` ordered by creation date. + Requires the `comment:read` or `comment:write` permission. + + Returns Promise + reply: |- + ``` + reply(content): Promise + ``` + + * Creates a new comment after the last one in the thread. The current user will + be used as the creation user. + Requires the `comment:write` permission. + + Parameters + + content: string + + Returns Promise + remove: |- + ``` + remove(): void + ``` + + * Removes the current comment thread. Only the user that created the thread can + remove it. + Requires the `comment:write` permission. + + Returns void +CommonLayout: + overview: |- + Interface CommonLayout + ====================== + + CommonLayout represents a common layout interface in the Penpot application. + It includes various properties for alignment, spacing, padding, and sizing, as well as a method to remove the layout. + + ``` + interface CommonLayout { + alignItems?: + | "center" + | "start" + | "end" + | "stretch"; + alignContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly"; + justifyItems?: + | "center" + | "start" + | "end" + | "stretch"; + justifyContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly"; + rowGap: number; + columnGap: number; + verticalPadding: number; + horizontalPadding: number; + topPadding: number; + rightPadding: number; + bottomPadding: number; + leftPadding: number; + horizontalSizing: "fill" | "auto" | "fit-content"; + verticalSizing: "fill" | "auto" | "fit-content"; + remove(): void; + } + ``` + + Hierarchy (view full) + + * CommonLayout + + FlexLayout + + GridLayout + members: + Properties: + alignItems: |- + ``` + alignItems?: + | "center" + | "start" + | "end" + | "stretch" + ``` + + The `alignItems` property specifies the default alignment for items inside the container. + It can be one of the following values: + + * 'start': Items are aligned at the start. + * 'end': Items are aligned at the end. + * 'center': Items are centered. + * 'stretch': Items are stretched to fill the container. + alignContent: |- + ``` + alignContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly" + ``` + + The `alignContent` property specifies how the content is aligned within the container when there is extra space. + It can be one of the following values: + + * 'start': Content is aligned at the start. + * 'end': Content is aligned at the end. + * 'center': Content is centered. + * 'space-between': Content is distributed with space between. + * 'space-around': Content is distributed with space around. + * 'space-evenly': Content is distributed with even space around. + * 'stretch': Content is stretched to fill the container. + justifyItems: |- + ``` + justifyItems?: + | "center" + | "start" + | "end" + | "stretch" + ``` + + The `justifyItems` property specifies the default justification for items inside the container. + It can be one of the following values: + + * 'start': Items are justified at the start. + * 'end': Items are justified at the end. + * 'center': Items are centered. + * 'stretch': Items are stretched to fill the container. + justifyContent: |- + ``` + justifyContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly" + ``` + + The `justifyContent` property specifies how the content is justified within the container when there is extra space. + It can be one of the following values: + + * 'start': Content is justified at the start. + * 'center': Content is centered. + * 'end': Content is justified at the end. + * 'space-between': Content is distributed with space between. + * 'space-around': Content is distributed with space around. + * 'space-evenly': Content is distributed with even space around. + * 'stretch': Content is stretched to fill the container. + rowGap: |- + ``` + rowGap: number + ``` + + The `rowGap` property specifies the gap between rows in the layout. + columnGap: |- + ``` + columnGap: number + ``` + + The `columnGap` property specifies the gap between columns in the layout. + verticalPadding: |- + ``` + verticalPadding: number + ``` + + The `verticalPadding` property specifies the vertical padding inside the container. + horizontalPadding: |- + ``` + horizontalPadding: number + ``` + + The `horizontalPadding` property specifies the horizontal padding inside the container. + topPadding: |- + ``` + topPadding: number + ``` + + The `topPadding` property specifies the padding at the top of the container. + rightPadding: |- + ``` + rightPadding: number + ``` + + The `rightPadding` property specifies the padding at the right of the container. + bottomPadding: |- + ``` + bottomPadding: number + ``` + + The `bottomPadding` property specifies the padding at the bottom of the container. + leftPadding: |- + ``` + leftPadding: number + ``` + + The `leftPadding` property specifies the padding at the left of the container. + horizontalSizing: |- + ``` + horizontalSizing: "fill" | "auto" | "fit-content" + ``` + + The `horizontalSizing` property specifies the horizontal sizing behavior of the container. + It can be one of the following values: + + * 'fit-content': The container fits the content. + * 'fill': The container fills the available space. + * 'auto': The container size is determined automatically. + verticalSizing: |- + ``` + verticalSizing: "fill" | "auto" | "fit-content" + ``` + + The `verticalSizing` property specifies the vertical sizing behavior of the container. + It can be one of the following values: + + * 'fit-content': The container fits the content. + * 'fill': The container fills the available space. + * 'auto': The container size is determined automatically. + Methods: + remove: |- + ``` + remove(): void + ``` + + * The `remove` method removes the layout. + + Returns void +Context: + overview: |- + Interface Context + ================= + + Represents the context of Penpot, providing access to various Penpot functionalities and data. + + ``` + interface Context { + root: null | Shape; + currentFile: null | File; + currentPage: null | Page; + viewport: Viewport; + history: HistoryContext; + library: LibraryContext; + fonts: FontsContext; + currentUser: User; + activeUsers: ActiveUser[]; + theme: Theme; + localStorage: LocalStorage; + selection: Shape[]; + shapesColors(shapes: Shape[]): (Color & ColorShapeInfo)[]; + replaceColor(shapes: Shape[], oldColor: Color, newColor: Color): void; + uploadMediaUrl(name: string, url: string): Promise; + uploadMediaData(name: string, data: Uint8Array, mimeType: string): Promise; + group(shapes: Shape[]): null | Group; + ungroup(group: Group, ...other: Group[]): void; + createRectangle(): Rectangle; + createBoard(): Board; + createEllipse(): Ellipse; + createPath(): Path; + createBoolean(boolType: BooleanType, shapes: Shape[]): null | Boolean; + createShapeFromSvg(svgString: string): null | Group; + createShapeFromSvgWithImages(svgString: string): Promise; + createText(text: string): null | Text; + generateMarkup(shapes: Shape[], options?: { + type?: "html" | "svg"; + }): string; + generateStyle(shapes: Shape[], options?: { + type?: "css"; + withPrelude?: boolean; + includeChildren?: boolean; + }): string; + generateFontFaces(shapes: Shape[]): Promise; + addListener(type: T, callback: ((event: EventsMap[T]) => void), props?: { + [key: string]: unknown; + }): symbol; + removeListener(listenerId: symbol): void; + openViewer(): void; + createPage(): Page; + openPage(page: Page): void; + alignHorizontal(shapes: Shape[], direction: "center" | "left" | "right"): void; + alignVertical(shapes: Shape[], direction: "center" | "top" | "bottom"): void; + distributeHorizontal(shapes: Shape[]): void; + distributeVertical(shapes: Shape[]): void; + flatten(shapes: Shape[]): Path[]; + } + ``` + members: + Properties: + root: |- + ``` + root: null | Shape + ``` + + The root shape in the current Penpot context. Requires `content:read` permission. + + Example + ``` + const rootShape = context.root;console.log(rootShape); + ``` + currentFile: |- + ``` + currentFile: null | File + ``` + + Retrieves file data from the current Penpot context. Requires `content:read` permission. + + Returns + + Returns the file data or `null` if no file is available. + + Example + ``` + const fileData = context.currentFile;console.log(fileData); + ``` + currentPage: |- + ``` + currentPage: null | Page + ``` + + The current page in the Penpot context. Requires `content:read` permission. + + Example + ``` + const currentPage = context.currentPage;console.log(currentPage); + ``` + viewport: |- + ``` + viewport: Viewport + ``` + + The viewport settings in the Penpot context. + + Example + ``` + const viewportSettings = context.viewport;console.log(viewportSettings); + ``` + history: |- + ``` + history: HistoryContext + ``` + + Context encapsulating the history operations + + Example + ``` + const historyContext = context.history;console.log(historyContext); + ``` + library: |- + ``` + library: LibraryContext + ``` + + The library context in the Penpot context, including both local and connected libraries. Requires `library:read` permission. + + Example + ``` + const libraryContext = context.library;console.log(libraryContext); + ``` + fonts: |- + ``` + fonts: FontsContext + ``` + + The fonts context in the Penpot context, providing methods to manage fonts. Requires `content:read` permission. + + Example + ``` + const fontsContext = context.fonts;console.log(fontsContext); + ``` + currentUser: |- + ``` + currentUser: User + ``` + + The current user in the Penpot context. Requires `user:read` permission. + + Example + ``` + const currentUser = context.currentUser;console.log(currentUser); + ``` + activeUsers: |- + ``` + activeUsers: ActiveUser[] + ``` + + An array of active users in the Penpot context. Requires `user:read` permission. + + Example + ``` + const activeUsers = context.activeUsers;console.log(activeUsers); + ``` + theme: |- + ``` + theme: Theme + ``` + + The current theme (light or dark) in Penpot. + + Example + ``` + const currentTheme = context.theme;console.log(currentTheme); + ``` + localStorage: |- + ``` + localStorage: LocalStorage + ``` + + Access to the localStorage proxy + selection: |- + ``` + selection: Shape[] + ``` + + The currently selected shapes in Penpot. Requires `content:read` permission. + + Example + ``` + const selectedShapes = context.selection;console.log(selectedShapes); + ``` + Methods: + shapesColors: |- + ``` + shapesColors(shapes): (Color & ColorShapeInfo)[] + ``` + + * Retrieves colors applied to the given shapes in Penpot. Requires `content:read` permission. + + Parameters + + shapes: Shape[] + + Returns (Color & ColorShapeInfo)[] + + Returns an array of colors and their shape information. + + Example + ``` + const colors = context.shapesColors(shapes);console.log(colors); + ``` + replaceColor: |- + ``` + replaceColor(shapes, oldColor, newColor): void + ``` + + * Replaces a specified old color with a new color in the given shapes. Requires `content:write` permission. + + Parameters + + shapes: Shape[] + + oldColor: Color + + newColor: Color + + Returns void + + Example + ``` + context.replaceColor(shapes, oldColor, newColor); + ``` + uploadMediaUrl: |- + ``` + uploadMediaUrl(name, url): Promise + ``` + + * Uploads media to Penpot and retrieves its image data. Requires `content:write` permission. + + Parameters + + name: string + + The name of the media. + + url: string + + The URL of the media to be uploaded. + + Returns Promise + + Returns a promise that resolves to the image data of the uploaded media. + + Example + ``` + const imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');console.log(imageData);// to insert the image in a shape we can doconst board = penpot.createBoard();const shape = penpot.createRectangle();board.appendChild(shape);shape.fills = [{ fillOpacity: 1, fillImage: imageData }]; + ``` + uploadMediaData: |- + ``` + uploadMediaData(name, data, mimeType): Promise + ``` + + * Uploads media to penpot and retrieves the image data. Requires `content:write` permission. + + Parameters + + name: string + + The name of the media. + + data: Uint8Array + + The image content data + + mimeType: string + + Returns Promise + + Returns a promise that resolves to the image data of the uploaded media. + + Example + ``` + const imageData = await context.uploadMediaData('example', imageData, 'image/jpeg');console.log(imageData); + ``` + group: |- + ``` + group(shapes): null | Group + ``` + + * Groups the specified shapes. Requires `content:write` permission. + + Parameters + + shapes: Shape[] + + An array of shapes to group. + + Returns null | Group + + Returns the newly created group or `null` if the group could not be created. + + Example + ``` + const penpotShapesArray = penpot.selection;penpot.group(penpotShapesArray); + ``` + ungroup: |- + ``` + ungroup(group, ...other): void + ``` + + * Ungroups the specified group. Requires `content:write` permission. + + Parameters + + group: Group + + The group to ungroup. + + ...other: Group[] + + Additional groups to ungroup. + + Returns void + + Example + ``` + const penpotShapesArray = penpot.selection;// We need to make sure that something is selected, and if the selected shape is a group,if (selected.length && penpot.utils.types.isGroup(penpotShapesArray[0])) { penpot.group(penpotShapesArray[0]);} + ``` + createRectangle: |- + ``` + createRectangle(): Rectangle + ``` + + * Use this method to create the shape of a rectangle. Requires `content:write` permission. + + Returns Rectangle + + Example + ``` + const shape = penpot.createRectangle();// just change the values like thisshape.name = "Example rectangle";// for solid colorshape.fills = [{ fillColor: "#7EFFF5" }];// for linear gradient colorshape.fills = [{ fillColorGradient: { "type": "linear", "startX": 0.5, "startY": 0, "endX": 0.5, "endY": 1, "width": 1, "stops": [ { "color": "#003ae9", "opacity": 1, "offset": 0 }, { "color": "#003ae9", "opacity": 0, "offset": 1 } ] }}];// for a image fillconst imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');shape.fills = [{ fillOpacity: 1, fillImage: imageData }];shape.borderRadius = 8;shape.strokes = [ { strokeColor: "#2e3434", strokeStyle: "solid", strokeWidth: 2, strokeAlignment: "center", },]; + ``` + createBoard: |- + ``` + createBoard(): Board + ``` + + * Use this method to create a board. This is the first step before anything else, the container. Requires `content:write` permission. + Then you can add a gridlayout, flexlayout or add a shape inside the board. + Just a heads-up: board is a board in Penpot UI. + + Returns Board + + Example + ``` + const board = penpot.createBoard();// to add grid layoutboard.addGridLayout();// to add flex layoutboard.addFlexLayout();// to create a shape inside the boardconst shape = penpot.createRectangle();board.appendChild(shape); + ``` + createEllipse: |- + ``` + createEllipse(): Ellipse + ``` + + * Use this method to create the shape of an ellipse. Requires `content:write` permission. + + Returns Ellipse + + Example + ``` + const shape = penpot.createEllipse();// just change the values like thisshape.name = "Example ellipse";// for solid colorshape.fills = [{ fillColor: "#7EFFF5" }];// for linear gradient colorshape.fills = [{ fillColorGradient: { "type": "linear", "startX": 0.5, "startY": 0, "endX": 0.5, "endY": 1, "width": 1, "stops": [ { "color": "#003ae9", "opacity": 1, "offset": 0 }, { "color": "#003ae9", "opacity": 0, "offset": 1 } ] }}];// for an image fillconst imageData = await context.uploadMediaUrl('example', 'https://example.com/image.jpg');shape.fills = [{ fillOpacity: 1, fillImage: imageData }];shape.strokes = [ { strokeColor: "#2e3434", strokeStyle: "solid", strokeWidth: 2, strokeAlignment: "center", },]; + ``` + createPath: |- + ``` + createPath(): Path + ``` + + * Use this method to create a path. Requires `content:write` permission. + + Returns Path + + Example + ``` + const path = penpot.createPath();path.name = "My path";// for solid colorpath.fills = [{ fillColor: "#7EFFF5" }]; + ``` + createBoolean: |- + ``` + createBoolean(boolType, shapes): null | Boolean + ``` + + * Creates a Boolean shape based on the specified boolean operation and shapes. Requires `content:write` permission. + + Parameters + + boolType: BooleanType + + The type of boolean operation ('union', 'difference', 'exclude', 'intersection'). + + shapes: Shape[] + + An array of shapes to perform the boolean operation on. + + Returns null | Boolean + + Returns the newly created Boolean shape resulting from the boolean operation. + + Example + ``` + const booleanShape = context.createBoolean('union', [shape1, shape2]); + ``` + createShapeFromSvg: |- + ``` + createShapeFromSvg(svgString): null | Group + ``` + + * Creates a Group from an SVG string. Requires `content:write` permission. + + Parameters + + svgString: string + + The SVG string representing the shapes to be converted into a group. + + Returns null | Group + + Returns the newly created Group containing the shapes from the SVG. + + Example + ``` + const svgGroup = context.createShapeFromSvg('...'); + ``` + createShapeFromSvgWithImages: |- + ``` + createShapeFromSvgWithImages(svgString): Promise + ``` + + * Creates a Group from an SVG string. The SVG can have images and the method returns + a Promise because the shape will be available after all images are uploaded. + Requires `content:write` permission. + + Parameters + + svgString: string + + The SVG string representing the shapes to be converted into a group. + + Returns Promise + + Returns a promise with the newly created Group containing the shapes from the SVG. + + Example + ``` + const svgGroup = await context.createShapeFromSvgWithImages('...'); + ``` + createText: |- + ``` + createText(text): null | Text + ``` + + * Creates a Text shape with the specified text content. Requires `content:write` permission. + + Parameters + + text: string + + The text content for the Text shape. + + Returns null | Text + + Returns the new created shape, if the shape wasn't created can return null. + + Example + ``` + const board = penpot.createBoard();let text;text = penpot.createText();// just change the values like thistext.growType = 'auto-height';text.fontFamily = 'Work Sans';text.fontSize = '12';text.fills = [{fillColor: '#9f05ff', fillOpacity: 1}];text.strokes = [{strokeOpacity: 1, strokeStyle: 'solid', strokeWidth: 2, strokeColor: '#deabff', strokeAlignment: 'outer'}];board.appendChild(text); + ``` + generateMarkup: |- + ``` + generateMarkup(shapes, options?): string + ``` + + * Generates markup for the given shapes. Requires `content:read` permission + + Parameters + + shapes: Shape[] + + options: { + type?: "html" | "svg"; + } + - Optionaltype?: "html" | "svg" + + Returns string + + Example + ``` + const markup = context.generateMarkup(shapes, { type: 'html' });console.log(markup); + ``` + generateStyle: |- + ``` + generateStyle(shapes, options?): string + ``` + + * Generates styles for the given shapes. Requires `content:read` permission + + Parameters + + shapes: Shape[] + + options: { + type?: "css"; + withPrelude?: boolean; + includeChildren?: boolean; + } + - Optionaltype?: "css" + - OptionalwithPrelude?: boolean + - OptionalincludeChildren?: boolean + + Returns string + + Example + ``` + const styles = context.generateStyle(shapes, { type: 'css' });console.log(styles); + ``` + generateFontFaces: |- + ``` + generateFontFaces(shapes): Promise + ``` + + * Generates the fontfaces styles necessaries to render the shapes. + Requires `content:read` permission + + Parameters + + shapes: Shape[] + + Returns Promise + + Example + ``` + const fontfaces = context.generateFontFaces(penpot.selection);console.log(fontfaces); + ``` + addListener: |- + ``` + addListener(type, callback, props?): symbol + ``` + + * Adds the current callback as an event listener + + Type Parameters + + T extends keyof EventsMap + + Parameters + + type: T + + callback: ((event: EventsMap[T]) => void) + - ``` + (event): void + ``` + + * Parameters + + event: EventsMap[T] + + Returns void + + props: { + [key: string]: unknown; + } + - [key: string]: unknown + + Returns symbol + + Example + ``` + const listenerId = context.addListener('selectionchange', (event) => { console.log(event);}); + ``` + removeListener: |- + ``` + removeListener(listenerId): void + ``` + + * Removes the listenerId from the list of listeners + + Parameters + + listenerId: symbol + + Returns void + + Example + ``` + context.removeListener(listenerId); + ``` + openViewer: |- + ``` + openViewer(): void + ``` + + * Opens the viewer section. Requires `content:read` permission. + + Returns void + createPage: |- + ``` + createPage(): Page + ``` + + * Creates a new page. Requires `content:write` permission. + + Returns Page + openPage: |- + ``` + openPage(page): void + ``` + + * Changes the current open page to given page. Requires `content:read` permission. + + Parameters + + page: Page + + the page to open + + Returns void + + Example + ``` + context.openPage(page); + ``` + alignHorizontal: |- + ``` + alignHorizontal(shapes, direction): void + ``` + + * Aligning will move all the selected layers to a position relative to one + of them in the horizontal direction. + + Parameters + + shapes: Shape[] + + to align + + direction: "center" | "left" | "right" + + where the shapes will be aligned + + Returns void + alignVertical: |- + ``` + alignVertical(shapes, direction): void + ``` + + * Aligning will move all the selected layers to a position relative to one + of them in the vertical direction. + + Parameters + + shapes: Shape[] + + to align + + direction: "center" | "top" | "bottom" + + where the shapes will be aligned + + Returns void + distributeHorizontal: |- + ``` + distributeHorizontal(shapes): void + ``` + + * Distributing objects to position them horizontally with equal distances between them. + + Parameters + + shapes: Shape[] + + to distribute + + Returns void + distributeVertical: |- + ``` + distributeVertical(shapes): void + ``` + + * Distributing objects to position them vertically with equal distances between them. + + Parameters + + shapes: Shape[] + + to distribute + + Returns void + flatten: |- + ``` + flatten(shapes): Path[] + ``` + + * Converts the shapes into Paths. If the shapes are complex will put together + all its paths into one. + + Parameters + + shapes: Shape[] + + to flatten + + Returns Path[] +ContextGeometryUtils: + overview: |- + Interface ContextGeometryUtils + ============================== + + Utility methods for geometric calculations in Penpot. + + Example + ``` + const centerPoint = geometryUtils.center(shapes);console.log(centerPoint); + ``` + + ``` + interface ContextGeometryUtils { + center(shapes: Shape[]): null | { + x: number; + y: number; + }; + } + ``` + members: + Methods: + center: |- + ``` + center(shapes): null | { + x: number; + y: number; + } + ``` + + * Calculates the center point of a given array of shapes. + This method computes the geometric center (centroid) of the bounding boxes of the provided shapes. + + Parameters + + shapes: Shape[] + + The array of shapes to calculate the center for. + + Returns null | { x: number; y: number; } + + Returns the center point as an object with `x` and `y` coordinates, or null if the array is empty. + + Example + ``` + const centerPoint = geometryUtils.center(shapes);console.log(centerPoint); + ``` +ContextTypesUtils: + overview: |- + Interface ContextTypesUtils + =========================== + + Utility methods for determining the types of Penpot shapes. + + Example + ``` + const isBoard = typesUtils.isBoard(shape);console.log(isBoard); + ``` + + ``` + interface ContextTypesUtils { + isBoard(shape: Shape): shape is Board; + isGroup(shape: Shape): shape is Group; + isMask(shape: Shape): shape is Group; + isBool(shape: Shape): shape is Boolean; + isRectangle(shape: Shape): shape is Rectangle; + isPath(shape: Shape): shape is Path; + isText(shape: Shape): shape is Text; + isEllipse(shape: Shape): shape is Ellipse; + isSVG(shape: Shape): shape is SvgRaw; + } + ``` + members: + Methods: + isBoard: |- + ``` + isBoard(shape): shape is Board + ``` + + * Checks if the given shape is a board. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Board + + Returns true if the shape is a board, otherwise false. + isGroup: |- + ``` + isGroup(shape): shape is Group + ``` + + * Checks if the given shape is a group. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Group + + Returns true if the shape is a Group, otherwise false. + isMask: |- + ``` + isMask(shape): shape is Group + ``` + + * Checks if the given shape is a mask. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Group + + Returns true if the shape is a Group (acting as a mask), otherwise false. + isBool: |- + ``` + isBool(shape): shape is Boolean + ``` + + * Checks if the given shape is a boolean operation. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Boolean + + Returns true if the shape is a Bool, otherwise false. + isRectangle: |- + ``` + isRectangle(shape): shape is Rectangle + ``` + + * Checks if the given shape is a rectangle. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Rectangle + + Returns true if the shape is a Rectangle, otherwise false. + isPath: |- + ``` + isPath(shape): shape is Path + ``` + + * Checks if the given shape is a path. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Path + + Returns true if the shape is a Path, otherwise false. + isText: |- + ``` + isText(shape): shape is Text + ``` + + * Checks if the given shape is a text element. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Text + + Returns true if the shape is a Text, otherwise false. + isEllipse: |- + ``` + isEllipse(shape): shape is Ellipse + ``` + + * Checks if the given shape is an ellipse. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is Ellipse + + Returns true if the shape is an Ellipse, otherwise false. + isSVG: |- + ``` + isSVG(shape): shape is SvgRaw + ``` + + * Checks if the given shape is an SVG. + + Parameters + + shape: Shape + + The shape to check. + + Returns shape is SvgRaw + + Returns true if the shape is a SvgRaw, otherwise false. +ContextUtils: + overview: |- + Interface ContextUtils + ====================== + + Utility methods for various operations in Penpot. + + ``` + interface ContextUtils { + geometry: ContextGeometryUtils; + types: ContextTypesUtils; + } + ``` + members: + Properties: + geometry: |- + ``` + geometry: ContextGeometryUtils + ``` + + Geometry utility methods for Penpot. + Provides methods for geometric calculations, such as finding the center of a group of shapes. + + Example + ``` + const centerPoint = penpot.utils.geometry.center(shapes);console.log(centerPoint); + ``` + types: |- + ``` + types: ContextTypesUtils + ``` + + Type utility methods for Penpot. + Provides methods for determining the types of various shapes in Penpot. + + Example + ``` + const isBoard = utils.types.isBoard(shape);console.log(isBoard); + ``` +Dissolve: + overview: |- + Interface Dissolve + ================== + + Dissolve animation + + ``` + interface Dissolve { + type: "dissolve"; + duration: number; + easing?: + | "linear" + | "ease" + | "ease-in" + | "ease-out" + | "ease-in-out"; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + Type of the animation + duration: |- + ``` + duration: number + ``` + + Duration of the animation effect + easing: |- + ``` + easing?: + | "linear" + | "ease" + | "ease-in" + | "ease-out" + | "ease-in-out" + ``` + + Function that the dissolve effect will follow for the interpolation. + Defaults to `linear`. +Ellipse: + overview: |- + Interface Ellipse + ================= + + Represents an ellipse shape in Penpot. + This interface extends `ShapeBase` and includes properties specific to ellipses. + + ``` + interface Ellipse { + type: "ellipse"; + fills: Fill[]; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Ellipse + members: + Properties: + type: |- + ``` + type + ``` + fills: |- + ``` + fills: Fill[] + ``` + + The fills applied to the shape. + + Overrides ShapeBase.fills + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +EventsMap: + overview: |- + Interface EventsMap + =================== + + Represents a mapping of events to their corresponding types in Penpot. + This interface provides information about various events that can be triggered in the application. + + Example + ``` + penpot.on('pagechange', (event) => { console.log(event);}); + ``` + + ``` + interface EventsMap { + pagechange: Page; + filechange: File; + selectionchange: string[]; + themechange: Theme; + finish: string; + shapechange: Shape; + contentsave: void; + } + ``` + members: + Properties: + pagechange: |- + ``` + pagechange: Page + ``` + + The `pagechange` event is triggered when the active page in the project is changed. + filechange: |- + ``` + filechange: File + ``` + + The `filechange` event is triggered when there are changes in the current file. + selectionchange: |- + ``` + selectionchange: string[] + ``` + + The `selectionchange` event is triggered when the selection of elements changes. + This event passes a list of identifiers of the selected elements. + themechange: |- + ``` + themechange: Theme + ``` + + The `themechange` event is triggered when the application theme is changed. + finish: |- + ``` + finish: string + ``` + + The `finish` event is triggered when some operation is finished. + shapechange: |- + ``` + shapechange: Shape + ``` + + This event will trigger whenever the shape in the props change. It's mandatory to send + with the props an object like `{ shapeId: '' }` + contentsave: |- + ``` + contentsave: void + ``` + + The `contentsave` event will trigger when the content file changes. +Export: + overview: |- + Interface Export + ================ + + Represents export settings in Penpot. + This interface includes properties for defining export configurations. + + ``` + interface Export { + type: + | "svg" + | "png" + | "jpeg" + | "pdf"; + scale?: number; + suffix?: string; + skipChildren?: boolean; + } + ``` + members: + Properties: + type: |- + ``` + type: + | "svg" + | "png" + | "jpeg" + | "pdf" + ``` + + Type of the file to export. Can be one of the following values: png, jpeg, svg, pdf + scale: |- + ``` + scale?: number + ``` + + For bitmap formats represent the scale of the original size to resize the export + suffix: |- + ``` + suffix?: string + ``` + + Suffix that will be appended to the resulting exported file + skipChildren: |- + ``` + skipChildren?: boolean + ``` + + If true will ignore the children when exporting the shape +File: + overview: |- + Interface File + ============== + + File represents a file in the Penpot application. + It includes properties for the file's identifier, name, and revision number. + + ``` + interface File { + id: string; + name: string; + revn: number; + pages: Page[]; + export(exportType: "penpot" | "zip", libraryExportType?: "all" | "merge" | "detach"): Promise; + findVersions(criteria?: { + createdBy: User; + }): Promise; + saveVersion(label: string): Promise; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * PluginData + + File + members: + Properties: + id: |- + ``` + id: string + ``` + + The `id` property is a unique identifier for the file. + name: |- + ``` + name: string + ``` + + The `name` for the file + revn: |- + ``` + revn: number + ``` + + The `revn` will change for every document update + pages: |- + ``` + pages: Page[] + ``` + + List all the pages for the current file + Methods: + export: |- + ``` + export(exportType, libraryExportType?): Promise + ``` + + * Parameters + + exportType: "penpot" | "zip" + + libraryExportType: "all" | "merge" | "detach" + + Returns Promise + findVersions: |- + ``` + findVersions(criteria?): Promise + ``` + + * Retrieves the versions for the file. + + Parameters + + criteria: { + createdBy: User; + } + - createdBy: User + + Returns Promise + saveVersion: |- + ``` + saveVersion(label): Promise + ``` + + * Saves the current version into the versions history. + Requires the `content:write` permission. + + Parameters + + label: string + + Returns Promise + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +FileVersion: + overview: |- + Interface FileVersion + ===================== + + Type defining the file version properties. + + ``` + interface FileVersion { + label: string; + createdBy?: User; + createdAt: Date; + isAutosave: boolean; + restore(): void; + remove(): Promise; + pin(): Promise; + } + ``` + members: + Properties: + label: |- + ``` + label: string + ``` + + The current label to identify the version. + createdBy: |- + ``` + createdBy?: User + ``` + + The user that created the version. If not present, the + version is an autosave. + createdAt: |- + ``` + createdAt: Date + ``` + + The date when the version was created. + isAutosave: |- + ``` + isAutosave: boolean + ``` + + If the current version has been generated automatically. + Methods: + restore: |- + ``` + restore(): void + ``` + + * Returns void + remove: |- + ``` + remove(): Promise + ``` + + * Remove the current version. + Requires the `content:write` permission. + + Returns Promise + pin: |- + ``` + pin(): Promise + ``` + + * Converts an autosave version into a permanent version. + Requires the `content:write` permission. + + Returns Promise +Fill: + overview: |- + Interface Fill + ============== + + Represents fill properties in Penpot. You can add a fill to any shape except for groups. + This interface includes properties for defining solid color fills, gradient fills, and image fills. + + ``` + interface Fill { + fillColor?: string; + fillOpacity?: number; + fillColorGradient?: Gradient; + fillColorRefFile?: string; + fillColorRefId?: string; + fillImage?: ImageData; + } + ``` + members: + Properties: + fillColor: |- + ``` + fillColor?: string + ``` + + The optional solid fill color, represented as a string (e.g., '#FF5733'). + fillOpacity: |- + ``` + fillOpacity?: number + ``` + + The optional opacity level of the solid fill color, ranging from 0 (fully transparent) to 1 (fully opaque). + Defaults to 1 if omitted. + fillColorGradient: |- + ``` + fillColorGradient?: Gradient + ``` + + The optional gradient fill defined by a Gradient object. + fillColorRefFile: |- + ``` + fillColorRefFile?: string + ``` + + The optional reference to an external file for the fill color. + fillColorRefId: |- + ``` + fillColorRefId?: string + ``` + + The optional reference ID within the external file for the fill color. + fillImage: |- + ``` + fillImage?: ImageData + ``` + + The optional image fill defined by an ImageData object. +FlexLayout: + overview: |- + Interface FlexLayout + ==================== + + Represents a flexible layout configuration in Penpot. + This interface extends `CommonLayout` and includes properties for defining the direction, + wrapping behavior, and child management of a flex layout. + + ``` + interface FlexLayout { + alignItems?: + | "center" + | "start" + | "end" + | "stretch"; + alignContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly"; + justifyItems?: + | "center" + | "start" + | "end" + | "stretch"; + justifyContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly"; + rowGap: number; + columnGap: number; + verticalPadding: number; + horizontalPadding: number; + topPadding: number; + rightPadding: number; + bottomPadding: number; + leftPadding: number; + horizontalSizing: "fill" | "auto" | "fit-content"; + verticalSizing: "fill" | "auto" | "fit-content"; + remove(): void; + dir: + | "row" + | "row-reverse" + | "column" + | "column-reverse"; + wrap?: "wrap" | "nowrap"; + appendChild(child: Shape): void; + } + ``` + + Hierarchy (view full) + + * CommonLayout + + FlexLayout + members: + Properties: + alignItems: |- + ``` + alignItems?: + | "center" + | "start" + | "end" + | "stretch" + ``` + + The `alignItems` property specifies the default alignment for items inside the container. + It can be one of the following values: + + * 'start': Items are aligned at the start. + * 'end': Items are aligned at the end. + * 'center': Items are centered. + * 'stretch': Items are stretched to fill the container. + alignContent: |- + ``` + alignContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly" + ``` + + The `alignContent` property specifies how the content is aligned within the container when there is extra space. + It can be one of the following values: + + * 'start': Content is aligned at the start. + * 'end': Content is aligned at the end. + * 'center': Content is centered. + * 'space-between': Content is distributed with space between. + * 'space-around': Content is distributed with space around. + * 'space-evenly': Content is distributed with even space around. + * 'stretch': Content is stretched to fill the container. + justifyItems: |- + ``` + justifyItems?: + | "center" + | "start" + | "end" + | "stretch" + ``` + + The `justifyItems` property specifies the default justification for items inside the container. + It can be one of the following values: + + * 'start': Items are justified at the start. + * 'end': Items are justified at the end. + * 'center': Items are centered. + * 'stretch': Items are stretched to fill the container. + justifyContent: |- + ``` + justifyContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly" + ``` + + The `justifyContent` property specifies how the content is justified within the container when there is extra space. + It can be one of the following values: + + * 'start': Content is justified at the start. + * 'center': Content is centered. + * 'end': Content is justified at the end. + * 'space-between': Content is distributed with space between. + * 'space-around': Content is distributed with space around. + * 'space-evenly': Content is distributed with even space around. + * 'stretch': Content is stretched to fill the container. + rowGap: |- + ``` + rowGap: number + ``` + + The `rowGap` property specifies the gap between rows in the layout. + columnGap: |- + ``` + columnGap: number + ``` + + The `columnGap` property specifies the gap between columns in the layout. + verticalPadding: |- + ``` + verticalPadding: number + ``` + + The `verticalPadding` property specifies the vertical padding inside the container. + horizontalPadding: |- + ``` + horizontalPadding: number + ``` + + The `horizontalPadding` property specifies the horizontal padding inside the container. + topPadding: |- + ``` + topPadding: number + ``` + + The `topPadding` property specifies the padding at the top of the container. + rightPadding: |- + ``` + rightPadding: number + ``` + + The `rightPadding` property specifies the padding at the right of the container. + bottomPadding: |- + ``` + bottomPadding: number + ``` + + The `bottomPadding` property specifies the padding at the bottom of the container. + leftPadding: |- + ``` + leftPadding: number + ``` + + The `leftPadding` property specifies the padding at the left of the container. + horizontalSizing: |- + ``` + horizontalSizing: "fill" | "auto" | "fit-content" + ``` + + The `horizontalSizing` property specifies the horizontal sizing behavior of the container. + It can be one of the following values: + + * 'fit-content': The container fits the content. + * 'fill': The container fills the available space. + * 'auto': The container size is determined automatically. + verticalSizing: |- + ``` + verticalSizing: "fill" | "auto" | "fit-content" + ``` + + The `verticalSizing` property specifies the vertical sizing behavior of the container. + It can be one of the following values: + + * 'fit-content': The container fits the content. + * 'fill': The container fills the available space. + * 'auto': The container size is determined automatically. + dir: |- + ``` + dir: + | "row" + | "row-reverse" + | "column" + | "column-reverse" + ``` + + The direction of the flex layout. + + * 'row': Main axis is horizontal, from left to right. + * 'row-reverse': Main axis is horizontal, from right to left. + * 'column': Main axis is vertical, from top to bottom. + * 'column-reverse': Main axis is vertical, from bottom to top. + wrap: |- + ``` + wrap?: "wrap" | "nowrap" + ``` + + The optional wrapping behavior of the flex layout. + + * 'wrap': Child elements will wrap onto multiple lines. + * 'nowrap': Child elements will not wrap. + Methods: + remove: |- + ``` + remove(): void + ``` + + * The `remove` method removes the layout. + + Returns void + appendChild: |- + ``` + appendChild(child): void + ``` + + * Appends a child element to the flex layout. + + Parameters + + child: Shape + + The child element to be appended, of type `Shape`. + + Returns void + + Example + ``` + flexLayout.appendChild(childShape); + ``` +Flow: + overview: |- + Interface Flow + ============== + + Defines an interaction flow inside penpot. A flow is defined by a starting board for an interaction. + + ``` + interface Flow { + page: Page; + name: string; + startingBoard: Board; + remove(): void; + } + ``` + members: + Properties: + page: |- + ``` + page: Page + ``` + + The page in which the flow is defined + name: |- + ``` + name: string + ``` + + The name for the current flow + startingBoard: |- + ``` + startingBoard: Board + ``` + + The starting board for this interaction flow + Methods: + remove: |- + ``` + remove(): void + ``` + + * Removes the flow from the page + + Returns void +Font: + overview: |- + Interface Font + ============== + + Represents a font in Penpot, which includes details about the font family, variants, and styling options. + This interface provides properties and methods for describing and applying fonts within Penpot. + + ``` + interface Font { + name: string; + fontId: string; + fontFamily: string; + fontStyle?: null | "normal" | "italic"; + fontVariantId: string; + fontWeight: string; + variants: FontVariant[]; + applyToText(text: Text, variant?: FontVariant): void; + applyToRange(range: TextRange, variant?: FontVariant): void; + } + ``` + members: + Properties: + name: |- + ``` + name: string + ``` + + This property holds the human-readable name of the font. + fontId: |- + ``` + fontId: string + ``` + + The unique identifier of the font. + fontFamily: |- + ``` + fontFamily: string + ``` + + The font family of the font. + fontStyle: |- + ``` + fontStyle?: null | "normal" | "italic" + ``` + + The default font style of the font. + fontVariantId: |- + ``` + fontVariantId: string + ``` + + The default font variant ID of the font. + fontWeight: |- + ``` + fontWeight: string + ``` + + The default font weight of the font. + variants: |- + ``` + variants: FontVariant[] + ``` + + An array of font variants available for the font. + Methods: + applyToText: |- + ``` + applyToText(text, variant?): void + ``` + + * Applies the font styles to a text shape. + + Parameters + + text: Text + + The text shape to apply the font styles to. + + variant: FontVariant + + Optional. The specific font variant to apply. If not provided, applies the default variant. + + Returns void + + Example + ``` + font.applyToText(textShape, fontVariant); + ``` + applyToRange: |- + ``` + applyToRange(range, variant?): void + ``` + + * Applies the font styles to a text range within a text shape. + + Parameters + + range: TextRange + + The text range to apply the font styles to. + + variant: FontVariant + + Optional. The specific font variant to apply. If not provided, applies the default variant. + + Returns void + + Example + ``` + font.applyToRange(textRange, fontVariant); + ``` +FontVariant: + overview: |- + Interface FontVariant + ===================== + + Represents a font variant in Penpot, which defines a specific style variation of a font. + This interface provides properties for describing the characteristics of a font variant. + + ``` + interface FontVariant { + name: string; + fontVariantId: string; + fontWeight: string; + fontStyle: "normal" | "italic"; + } + ``` + members: + Properties: + name: |- + ``` + name: string + ``` + + The name of the font variant. + fontVariantId: |- + ``` + fontVariantId: string + ``` + + The unique identifier of the font variant. + fontWeight: |- + ``` + fontWeight: string + ``` + + The font weight of the font variant. + fontStyle: |- + ``` + fontStyle: "normal" | "italic" + ``` + + The font style of the font variant. +FontsContext: + overview: |- + Interface FontsContext + ====================== + + Represents the context for managing fonts in Penpot. + This interface provides methods to interact with fonts, such as retrieving fonts by ID or name. + + ``` + interface FontsContext { + all: Font[]; + findById(id: string): null | Font; + findByName(name: string): null | Font; + findAllById(id: string): Font[]; + findAllByName(name: string): Font[]; + } + ``` + members: + Properties: + all: |- + ``` + all: Font[] + ``` + + An array containing all available fonts. + Methods: + findById: |- + ``` + findById(id): null | Font + ``` + + * Finds a font by its unique identifier. + + Parameters + + id: string + + The ID of the font to find. + + Returns null | Font + + Returns the `Font` object if found, otherwise `null`. + + Example + ``` + const font = fontsContext.findById('font-id');if (font) { console.log(font.name);} + ``` + findByName: |- + ``` + findByName(name): null | Font + ``` + + * Finds a font by its name. + + Parameters + + name: string + + The name of the font to find. + + Returns null | Font + + Returns the `Font` object if found, otherwise `null`. + + Example + ``` + const font = fontsContext.findByName('font-name');if (font) { console.log(font.name);} + ``` + findAllById: |- + ``` + findAllById(id): Font[] + ``` + + * Finds all fonts matching a specific ID. + + Parameters + + id: string + + The ID to match against. + + Returns Font[] + + Returns an array of `Font` objects matching the provided ID. + + Example + ``` + const fonts = fontsContext.findAllById('font-id');console.log(fonts); + ``` + findAllByName: |- + ``` + findAllByName(name): Font[] + ``` + + * Finds all fonts matching a specific name. + + Parameters + + name: string + + The name to match against. + + Returns Font[] + + Returns an array of `Font` objects matching the provided name. + + Example + ``` + const fonts = fontsContext.findAllByName('font-name');console.log(fonts); + ``` +GridLayout: + overview: |- + Interface GridLayout + ==================== + + GridLayout represents a grid layout in the Penpot application, extending the common layout interface. + It includes properties and methods to manage rows, columns, and child elements within the grid. + + ``` + interface GridLayout { + alignItems?: + | "center" + | "start" + | "end" + | "stretch"; + alignContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly"; + justifyItems?: + | "center" + | "start" + | "end" + | "stretch"; + justifyContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly"; + rowGap: number; + columnGap: number; + verticalPadding: number; + horizontalPadding: number; + topPadding: number; + rightPadding: number; + bottomPadding: number; + leftPadding: number; + horizontalSizing: "fill" | "auto" | "fit-content"; + verticalSizing: "fill" | "auto" | "fit-content"; + remove(): void; + dir: "row" | "column"; + rows: Track[]; + columns: Track[]; + addRow(type: TrackType, value?: number): void; + addRowAtIndex(index: number, type: TrackType, value?: number): void; + addColumn(type: TrackType, value?: number): void; + addColumnAtIndex(index: number, type: TrackType, value: number): void; + removeRow(index: number): void; + removeColumn(index: number): void; + setColumn(index: number, type: TrackType, value?: number): void; + setRow(index: number, type: TrackType, value?: number): void; + appendChild(child: Shape, row: number, column: number): void; + } + ``` + + Hierarchy (view full) + + * CommonLayout + + GridLayout + members: + Properties: + alignItems: |- + ``` + alignItems?: + | "center" + | "start" + | "end" + | "stretch" + ``` + + The `alignItems` property specifies the default alignment for items inside the container. + It can be one of the following values: + + * 'start': Items are aligned at the start. + * 'end': Items are aligned at the end. + * 'center': Items are centered. + * 'stretch': Items are stretched to fill the container. + alignContent: |- + ``` + alignContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly" + ``` + + The `alignContent` property specifies how the content is aligned within the container when there is extra space. + It can be one of the following values: + + * 'start': Content is aligned at the start. + * 'end': Content is aligned at the end. + * 'center': Content is centered. + * 'space-between': Content is distributed with space between. + * 'space-around': Content is distributed with space around. + * 'space-evenly': Content is distributed with even space around. + * 'stretch': Content is stretched to fill the container. + justifyItems: |- + ``` + justifyItems?: + | "center" + | "start" + | "end" + | "stretch" + ``` + + The `justifyItems` property specifies the default justification for items inside the container. + It can be one of the following values: + + * 'start': Items are justified at the start. + * 'end': Items are justified at the end. + * 'center': Items are centered. + * 'stretch': Items are stretched to fill the container. + justifyContent: |- + ``` + justifyContent?: + | "center" + | "start" + | "end" + | "stretch" + | "space-between" + | "space-around" + | "space-evenly" + ``` + + The `justifyContent` property specifies how the content is justified within the container when there is extra space. + It can be one of the following values: + + * 'start': Content is justified at the start. + * 'center': Content is centered. + * 'end': Content is justified at the end. + * 'space-between': Content is distributed with space between. + * 'space-around': Content is distributed with space around. + * 'space-evenly': Content is distributed with even space around. + * 'stretch': Content is stretched to fill the container. + rowGap: |- + ``` + rowGap: number + ``` + + The `rowGap` property specifies the gap between rows in the layout. + columnGap: |- + ``` + columnGap: number + ``` + + The `columnGap` property specifies the gap between columns in the layout. + verticalPadding: |- + ``` + verticalPadding: number + ``` + + The `verticalPadding` property specifies the vertical padding inside the container. + horizontalPadding: |- + ``` + horizontalPadding: number + ``` + + The `horizontalPadding` property specifies the horizontal padding inside the container. + topPadding: |- + ``` + topPadding: number + ``` + + The `topPadding` property specifies the padding at the top of the container. + rightPadding: |- + ``` + rightPadding: number + ``` + + The `rightPadding` property specifies the padding at the right of the container. + bottomPadding: |- + ``` + bottomPadding: number + ``` + + The `bottomPadding` property specifies the padding at the bottom of the container. + leftPadding: |- + ``` + leftPadding: number + ``` + + The `leftPadding` property specifies the padding at the left of the container. + horizontalSizing: |- + ``` + horizontalSizing: "fill" | "auto" | "fit-content" + ``` + + The `horizontalSizing` property specifies the horizontal sizing behavior of the container. + It can be one of the following values: + + * 'fit-content': The container fits the content. + * 'fill': The container fills the available space. + * 'auto': The container size is determined automatically. + verticalSizing: |- + ``` + verticalSizing: "fill" | "auto" | "fit-content" + ``` + + The `verticalSizing` property specifies the vertical sizing behavior of the container. + It can be one of the following values: + + * 'fit-content': The container fits the content. + * 'fill': The container fills the available space. + * 'auto': The container size is determined automatically. + dir: |- + ``` + dir: "row" | "column" + ``` + + The `dir` property specifies the primary direction of the grid layout. + It can be either 'column' or 'row'. + rows: |- + ``` + rows: Track[] + ``` + + The `rows` property represents the collection of rows in the grid. + This property is read-only. + columns: |- + ``` + columns: Track[] + ``` + + The `columns` property represents the collection of columns in the grid. + This property is read-only. + Methods: + remove: |- + ``` + remove(): void + ``` + + * The `remove` method removes the layout. + + Returns void + addRow: |- + ``` + addRow(type, value?): void + ``` + + * Adds a new row to the grid. + + Parameters + + type: TrackType + + The type of the row to add. + + value: number + + The value associated with the row type (optional). + + Returns void + + Example + ``` + const board = penpot.createBoard();const grid = board.addGridLayout();grid.addRow("flex", 1); + ``` + addRowAtIndex: |- + ``` + addRowAtIndex(index, type, value?): void + ``` + + * Adds a new row to the grid at the specified index. + + Parameters + + index: number + + The index at which to add the row. + + type: TrackType + + The type of the row to add. + + value: number + + The value associated with the row type (optional). + + Returns void + + Example + ``` + gridLayout.addRowAtIndex(0, 'fixed', 100); + ``` + addColumn: |- + ``` + addColumn(type, value?): void + ``` + + * Adds a new column to the grid. + + Parameters + + type: TrackType + + The type of the column to add. + + value: number + + The value associated with the column type (optional). + + Returns void + + Example + ``` + const board = penpot.createBoard();const grid = board.addGridLayout();grid.addColumn('percent', 50); + ``` + addColumnAtIndex: |- + ``` + addColumnAtIndex(index, type, value): void + ``` + + * Adds a new column to the grid at the specified index. + + Parameters + + index: number + + The index at which to add the column. + + type: TrackType + + The type of the column to add. + + value: number + + The value associated with the column type. + + Returns void + + Example + ``` + gridLayout.addColumnAtIndex(1, 'auto'); + ``` + removeRow: |- + ``` + removeRow(index): void + ``` + + * Removes a row from the grid at the specified index. + + Parameters + + index: number + + The index of the row to remove. + + Returns void + + Example + ``` + gridLayout.removeRow(2); + ``` + removeColumn: |- + ``` + removeColumn(index): void + ``` + + * Removes a column from the grid at the specified index. + + Parameters + + index: number + + The index of the column to remove. + + Returns void + + Example + ``` + gridLayout.removeColumn(3); + ``` + setColumn: |- + ``` + setColumn(index, type, value?): void + ``` + + * Sets the properties of a column at the specified index. + + Parameters + + index: number + + The index of the column to set. + + type: TrackType + + The type of the column. + + value: number + + The value associated with the column type (optional). + + Returns void + + Example + ``` + gridLayout.setColumn(0, 'fixed', 200); + ``` + setRow: |- + ``` + setRow(index, type, value?): void + ``` + + * Sets the properties of a row at the specified index. + + Parameters + + index: number + + The index of the row to set. + + type: TrackType + + The type of the row. + + value: number + + The value associated with the row type (optional). + + Returns void + + Example + ``` + gridLayout.setRow(1, 'flex'); + ``` + appendChild: |- + ``` + appendChild(child, row, column): void + ``` + + * Appends a child element to the grid at the specified row and column. + + Parameters + + child: Shape + + The child element to append. + + row: number + + The row index where the child will be placed. + + column: number + + The column index where the child will be placed. + + Returns void + + Example + ``` + gridLayout.appendChild(childShape, 0, 1); + ``` +Group: + overview: |- + Interface Group + =============== + + Represents a group of shapes in Penpot. + This interface extends `ShapeBase` and includes properties and methods specific to groups. + + ``` + interface Group { + type: "group"; + children: Shape[]; + appendChild(child: Shape): void; + insertChild(index: number, child: Shape): void; + isMask(): boolean; + makeMask(): void; + removeMask(): void; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + fills: Fill[] | "mixed"; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Group + members: + Properties: + type: |- + ``` + type + ``` + + The type of the shape, which is always 'group' for groups. + children: |- + ``` + children: Shape[] + ``` + + The children shapes contained within the group. + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + fills: |- + ``` + fills: Fill[] | "mixed" + ``` + + The fills applied to the shape. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + appendChild: |- + ``` + appendChild(child): void + ``` + + * Appends a child shape to the group. + + Parameters + + child: Shape + + The child shape to append. + + Returns void + + Example + ``` + group.appendChild(childShape); + ``` + insertChild: |- + ``` + insertChild(index, child): void + ``` + + * Inserts a child shape at the specified index within the group. + + Parameters + + index: number + + The index at which to insert the child shape. + + child: Shape + + The child shape to insert. + + Returns void + + Example + ``` + group.insertChild(0, childShape); + ``` + isMask: |- + ``` + isMask(): boolean + ``` + + * Checks if the group is currently a mask. + A mask defines a clipping path for its child shapes. + + Returns boolean + makeMask: |- + ``` + makeMask(): void + ``` + + * Converts the group into a mask. + + Returns void + removeMask: |- + ``` + removeMask(): void + ``` + + * Removes the mask from the group. + + Returns void + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +GuideColumn: + overview: |- + Interface GuideColumn + ===================== + + Represents a goard guide for columns in Penpot. + This interface includes properties for defining the type, visibility, and parameters of column guides within a board. + + ``` + interface GuideColumn { + type: "column"; + display: boolean; + params: GuideColumnParams; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + The type of the guide, which is always 'column' for column guides. + display: |- + ``` + display: boolean + ``` + + Specifies whether the column guide is displayed. + params: |- + ``` + params: GuideColumnParams + ``` + + The parameters defining the appearance and layout of the column guides. +GuideColumnParams: + overview: |- + Interface GuideColumnParams + =========================== + + Represents parameters for board guide columns in Penpot. + This interface includes properties for defining the appearance and layout of column guides within a board. + + ``` + interface GuideColumnParams { + color: { + color: string; + opacity: number; + }; + type?: + | "center" + | "left" + | "right" + | "stretch"; + size?: number; + margin?: number; + itemLength?: number; + gutter?: number; + } + ``` + members: + Properties: + color: |- + ``` + color: { + color: string; + opacity: number; + } + ``` + + The color configuration for the column guides. + type: |- + ``` + type?: + | "center" + | "left" + | "right" + | "stretch" + ``` + + The optional alignment type of the column guides. + + * 'stretch': Columns stretch to fit the available space. + * 'left': Columns align to the left. + * 'center': Columns align to the center. + * 'right': Columns align to the right. + size: |- + ``` + size?: number + ``` + + The optional size of each column. + margin: |- + ``` + margin?: number + ``` + + The optional margin between the columns and the board edges. + itemLength: |- + ``` + itemLength?: number + ``` + + The optional length of each item within the columns. + gutter: |- + ``` + gutter?: number + ``` + + The optional gutter width between columns. +GuideRow: + overview: |- + Interface GuideRow + ================== + + Represents a board guide for rows in Penpot. + This interface includes properties for defining the type, visibility, and parameters of row guides within a board. + + ``` + interface GuideRow { + type: "row"; + display: boolean; + params: GuideColumnParams; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + The type of the guide, which is always 'row' for row guides. + display: |- + ``` + display: boolean + ``` + + Specifies whether the row guide is displayed. + params: |- + ``` + params: GuideColumnParams + ``` + + The parameters defining the appearance and layout of the row guides. + Note: This reuses the same parameter structure as column guides. +GuideSquare: + overview: |- + Interface GuideSquare + ===================== + + Represents a board guide for squares in Penpot. + This interface includes properties for defining the type, visibility, and parameters of square guides within a board. + + ``` + interface GuideSquare { + type: "square"; + display: boolean; + params: GuideSquareParams; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + The type of the guide, which is always 'square' for square guides. + display: |- + ``` + display: boolean + ``` + + Specifies whether the square guide is displayed. + params: |- + ``` + params: GuideSquareParams + ``` + + The parameters defining the appearance and layout of the square guides. +GuideSquareParams: + overview: |- + Interface GuideSquareParams + =========================== + + Represents parameters for board guide squares in Penpot. + This interface includes properties for defining the appearance and size of square guides within a board. + + ``` + interface GuideSquareParams { + color: { + color: string; + opacity: number; + }; + size?: number; + } + ``` + members: + Properties: + color: |- + ``` + color: { + color: string; + opacity: number; + } + ``` + + The color configuration for the square guides. + size: |- + ``` + size?: number + ``` + + The optional size of each square guide. +HistoryContext: + overview: |- + Interface HistoryContext + ======================== + + This object allows to access to some history functions + + ``` + interface HistoryContext { + undoBlockBegin(): Symbol; + undoBlockFinish(blockId: Symbol): void; + } + ``` + members: + Methods: + undoBlockBegin: |- + ``` + undoBlockBegin(): Symbol + ``` + + * Starts an undo block. All operations done inside this block will be undone together until + a call to `undoBlockFinish` is called. + + Returns Symbol + + the block identifier + undoBlockFinish: |- + ``` + undoBlockFinish(blockId): void + ``` + + * Ends the undo block started with `undoBlockBegin` + + Parameters + + blockId: Symbol + + is the id returned by `undoBlockBegin` + + Returns void + + Example + ``` + historyContext.undoBlockFinish(blockId); + ``` +Image: + overview: |- + Interface Image + =============== + + Represents an image shape in Penpot. + This interface extends `ShapeBase` and includes properties specific to image shapes. + + ``` + interface Image { + type: "image"; + fills: Fill[]; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Image + members: + Properties: + type: |- + ``` + type + ``` + fills: |- + ``` + fills: Fill[] + ``` + + The fills applied to the shape. + + Overrides ShapeBase.fills + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +Interaction: + overview: |- + Interface Interaction + ===================== + + Penpot allows you to prototype interactions by connecting boards, which can act as screens. + + ``` + interface Interaction { + shape?: Shape; + trigger: Trigger; + delay?: null | number; + action: Action; + remove(): void; + } + ``` + members: + Properties: + shape: |- + ``` + shape?: Shape + ``` + + The shape that owns the interaction + trigger: |- + ``` + trigger: Trigger + ``` + + The user action that will start the interaction. + delay: |- + ``` + delay?: null | number + ``` + + Time in **milliseconds** after the action will happen. Only applies to `after-delay` triggers. + action: |- + ``` + action: Action + ``` + + The action that will execute after the trigger happens. + Methods: + remove: |- + ``` + remove(): void + ``` + + * Removes the interaction + + Returns void +LayoutCellProperties: + overview: |- + Interface LayoutCellProperties + ============================== + + Properties for defining the layout of a cell in Penpot. + + ``` + interface LayoutCellProperties { + row?: number; + rowSpan?: number; + column?: number; + columnSpan?: number; + areaName?: string; + position?: "area" | "auto" | "manual"; + } + ``` + members: + Properties: + row: |- + ``` + row?: number + ``` + + The row index of the cell. + This value is optional and indicates the starting row of the cell. + rowSpan: |- + ``` + rowSpan?: number + ``` + + The number of rows the cell should span. + This value is optional and determines the vertical span of the cell. + column: |- + ``` + column?: number + ``` + + The column index of the cell. + This value is optional and indicates the starting column of the cell. + columnSpan: |- + ``` + columnSpan?: number + ``` + + The number of columns the cell should span. + This value is optional and determines the horizontal span of the cell. + areaName: |- + ``` + areaName?: string + ``` + + The name of the grid area that this cell belongs to. + This value is optional and can be used to define named grid areas. + position: |- + ``` + position?: "area" | "auto" | "manual" + ``` + + The positioning mode of the cell. + This value can be 'auto', 'manual', or 'area' and determines how the cell is positioned within the layout. +LayoutChildProperties: + overview: |- + Interface LayoutChildProperties + =============================== + + Properties for defining the layout of a child element in Penpot. + + ``` + interface LayoutChildProperties { + absolute: boolean; + zIndex: number; + horizontalSizing: "fill" | "auto" | "fix"; + verticalSizing: "fill" | "auto" | "fix"; + alignSelf: + | "center" + | "auto" + | "start" + | "end" + | "stretch"; + horizontalMargin: number; + verticalMargin: number; + topMargin: number; + rightMargin: number; + bottomMargin: number; + leftMargin: number; + maxWidth: null | number; + maxHeight: null | number; + minWidth: null | number; + minHeight: null | number; + } + ``` + members: + Properties: + absolute: |- + ``` + absolute: boolean + ``` + + Specifies whether the child element is positioned absolutely. + When set to true, the element is taken out of the normal document flow and positioned relative to its nearest positioned ancestor. + zIndex: |- + ``` + zIndex: number + ``` + + Defines the stack order of the child element + Elements with a higher zIndex will be displayed in front of those with a lower zIndex. + horizontalSizing: |- + ``` + horizontalSizing: "fill" | "auto" | "fix" + ``` + + Determines the horizontal sizing behavior of the child element + + * 'auto': The width is determined by the content. + * 'fill': The element takes up the available width. + * 'fix': The width is fixed. + verticalSizing: |- + ``` + verticalSizing: "fill" | "auto" | "fix" + ``` + + Determines the vertical sizing behavior of the child element. + + * 'auto': The height is determined by the content. + * 'fill': The element takes up the available height. + * 'fix': The height is fixed. + alignSelf: |- + ``` + alignSelf: + | "center" + | "auto" + | "start" + | "end" + | "stretch" + ``` + + Aligns the child element within its container. + + * 'auto': Default alignment. + * 'start': Aligns the element at the start of the container. + * 'center': Centers the element within the container. + * 'end': Aligns the element at the end of the container. + * 'stretch': Stretches the element to fill the container. + horizontalMargin: |- + ``` + horizontalMargin: number + ``` + + Sets the horizontal margin of the child element. + This is the space on the left and right sides of the element. + verticalMargin: |- + ``` + verticalMargin: number + ``` + + Sets the vertical margin of the child element. + This is the space on the top and bottom sides of the element. + topMargin: |- + ``` + topMargin: number + ``` + + Sets the top margin of the child element. + This is the space above the element. + rightMargin: |- + ``` + rightMargin: number + ``` + + Sets the right margin of the child element. + This is the space to the right of the element. + bottomMargin: |- + ``` + bottomMargin: number + ``` + + Sets the bottom margin of the child element. + This is the space below the element. + leftMargin: |- + ``` + leftMargin: number + ``` + + Sets the left margin of the child element. + This is the space to the left of the element. + maxWidth: |- + ``` + maxWidth: null | number + ``` + + Defines the maximum width of the child element. + If set to null, there is no maximum width constraint. + maxHeight: |- + ``` + maxHeight: null | number + ``` + + Defines the maximum height of the child element. + If set to null, there is no maximum height constraint. + minWidth: |- + ``` + minWidth: null | number + ``` + + Defines the minimum width of the child element. + If set to null, there is no minimum width constraint. + minHeight: |- + ``` + minHeight: null | number + ``` + + Defines the minimum height of the child element. + If set to null, there is no minimum height constraint. +Library: + overview: |- + Interface Library + ================= + + Represents a library in Penpot, containing colors, typographies, and components. + + ``` + interface Library { + id: string; + name: string; + colors: LibraryColor[]; + typographies: LibraryTypography[]; + components: LibraryComponent[]; + createColor(): LibraryColor; + createTypography(): LibraryTypography; + createComponent(shapes: Shape[]): LibraryComponent; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * PluginData + + Library + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the library. + name: |- + ``` + name: string + ``` + + The name of the library. + colors: |- + ``` + colors: LibraryColor[] + ``` + + An array of color elements in the library. + + Example + ``` + console.log(penpot.library.local.colors); + ``` + typographies: |- + ``` + typographies: LibraryTypography[] + ``` + + An array of typography elements in the library. + components: |- + ``` + components: LibraryComponent[] + ``` + + An array of component elements in the library. + + Example + ``` + console.log(penpot.library.local.components + ``` + Methods: + createColor: |- + ``` + createColor(): LibraryColor + ``` + + * Creates a new color element in the library. + + Returns LibraryColor + + Returns a new `LibraryColor` object representing the created color element. + + Example + ``` + const newColor = penpot.library.local.createColor();console.log(newColor); + ``` + createTypography: |- + ``` + createTypography(): LibraryTypography + ``` + + * Creates a new typography element in the library. + + Returns LibraryTypography + + Returns a new `LibraryTypography` object representing the created typography element. + + Example + ``` + const newTypography = library.createTypography(); + ``` + createComponent: |- + ``` + createComponent(shapes): LibraryComponent + ``` + + * Creates a new component element in the library using the provided shapes. + + Parameters + + shapes: Shape[] + + An array of `Shape` objects representing the shapes to be included in the component. + + Returns LibraryComponent + + Returns a new `LibraryComponent` object representing the created component element. + + Example + ``` + const newComponent = penpot.library.local.createComponent([shape1, shape2]); + ``` + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +LibraryColor: + overview: |- + Interface LibraryColor + ====================== + + Represents a color element from a library in Penpot. + This interface extends `LibraryElement` and includes properties specific to color elements. + + ``` + interface LibraryColor { + color?: string; + opacity?: number; + gradient?: Gradient; + image?: ImageData; + asFill(): Fill; + asStroke(): Stroke; + id: string; + libraryId: string; + name: string; + path: string; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * LibraryElement + + LibraryColor + members: + Properties: + color: |- + ``` + color?: string + ``` + + The color value of the library color. + opacity: |- + ``` + opacity?: number + ``` + + The opacity value of the library color. + gradient: |- + ``` + gradient?: Gradient + ``` + + The gradient value of the library color, if it's a gradient. + image: |- + ``` + image?: ImageData + ``` + + The image data of the library color, if it's an image fill. + id: |- + ``` + id: string + ``` + + The unique identifier of the library element. + libraryId: |- + ``` + libraryId: string + ``` + + The unique identifier of the library to which the element belongs. + name: |- + ``` + name: string + ``` + + The name of the library element. + path: |- + ``` + path: string + ``` + + The path of the library element. + Methods: + asFill: |- + ``` + asFill(): Fill + ``` + + * Converts the library color into a fill object. + + Returns Fill + + Returns a `Fill` object representing the color as a fill. + + Example + ``` + const fill = libraryColor.asFill(); + ``` + asStroke: |- + ``` + asStroke(): Stroke + ``` + + * Converts the library color into a stroke object. + + Returns Stroke + + Returns a `Stroke` object representing the color as a stroke. + + Example + ``` + const stroke = libraryColor.asStroke(); + ``` + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +LibraryComponent: + overview: |- + Interface LibraryComponent + ========================== + + Represents a component element from a library in Penpot. + This interface extends `LibraryElement` and includes properties specific to component elements. + + ``` + interface LibraryComponent { + instance(): Shape; + mainInstance(): Shape; + id: string; + libraryId: string; + name: string; + path: string; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * LibraryElement + + LibraryComponent + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the library element. + libraryId: |- + ``` + libraryId: string + ``` + + The unique identifier of the library to which the element belongs. + name: |- + ``` + name: string + ``` + + The name of the library element. + path: |- + ``` + path: string + ``` + + The path of the library element. + Methods: + instance: |- + ``` + instance(): Shape + ``` + + * Creates an instance of the component. + + Returns Shape + + Returns a `Shape` object representing the instance of the component. + + Example + ``` + const componentInstance = libraryComponent.instance(); + ``` + mainInstance: |- + ``` + mainInstance(): Shape + ``` + + * Returns Shape + + Returns the reference to the main component shape. + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +LibraryElement: + overview: |- + Interface LibraryElement + ======================== + + Represents an element in a Penpot library. + This interface provides information about a specific element in a library. + + ``` + interface LibraryElement { + id: string; + libraryId: string; + name: string; + path: string; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * PluginData + + LibraryElement + - LibraryColor + - LibraryComponent + - LibraryTypography + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the library element. + libraryId: |- + ``` + libraryId: string + ``` + + The unique identifier of the library to which the element belongs. + name: |- + ``` + name: string + ``` + + The name of the library element. + path: |- + ``` + path: string + ``` + + The path of the library element. + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +LibrarySummary: + overview: |- + Interface LibrarySummary + ======================== + + Represents a summary of a Penpot library. + This interface provides properties for summarizing various aspects of a Penpot library. + + ``` + interface LibrarySummary { + id: string; + name: string; + numColors: number; + numComponents: number; + numTypographies: number; + } + ``` + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the library. + name: |- + ``` + name: string + ``` + + The name of the library. + numColors: |- + ``` + numColors: number + ``` + + The number of colors in the library. + numComponents: |- + ``` + numComponents: number + ``` + + The number of components in the library. + numTypographies: |- + ``` + numTypographies: number + ``` + + The number of typographies in the library. +LibraryTypography: + overview: |- + Interface LibraryTypography + =========================== + + Represents a typography element from a library in Penpot. + This interface extends `LibraryElement` and includes properties specific to typography elements. + + ``` + interface LibraryTypography { + id: string; + libraryId: string; + name: string; + path: string; + fontId: string; + fontFamily: string; + fontVariantId: string; + fontSize: string; + fontWeight: string; + fontStyle?: null | "normal" | "italic"; + lineHeight: string; + letterSpacing: string; + textTransform?: + | null + | "uppercase" + | "capitalize" + | "lowercase"; + applyToText(shape: Shape): void; + applyToTextRange(range: TextRange): void; + setFont(font: Font, variant?: FontVariant): void; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * LibraryElement + + LibraryTypography + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the library element. + libraryId: |- + ``` + libraryId: string + ``` + + The unique identifier of the library to which the element belongs. + name: |- + ``` + name: string + ``` + + The name of the library element. + path: |- + ``` + path: string + ``` + + The path of the library element. + fontId: |- + ``` + fontId: string + ``` + + The unique identifier of the font used in the typography element. + fontFamily: |- + ``` + fontFamily: string + ``` + + The font family of the typography element. + fontVariantId: |- + ``` + fontVariantId: string + ``` + + The unique identifier of the font variant used in the typography element. + fontSize: |- + ``` + fontSize: string + ``` + + The font size of the typography element. + fontWeight: |- + ``` + fontWeight: string + ``` + + The font weight of the typography element. + fontStyle: |- + ``` + fontStyle?: null | "normal" | "italic" + ``` + + The font style of the typography element. + lineHeight: |- + ``` + lineHeight: string + ``` + + The line height of the typography element. + letterSpacing: |- + ``` + letterSpacing: string + ``` + + The letter spacing of the typography element. + textTransform: |- + ``` + textTransform?: + | null + | "uppercase" + | "capitalize" + | "lowercase" + ``` + + The text transform applied to the typography element. + Methods: + applyToText: |- + ``` + applyToText(shape): void + ``` + + * Applies the typography styles to a text shape. + + Parameters + + shape: Shape + + The text shape to apply the typography styles to. + + Returns void + + Example + ``` + typographyElement.applyToText(textShape); + ``` + applyToTextRange: |- + ``` + applyToTextRange(range): void + ``` + + * Applies the typography styles to a range of text within a text shape. + + Parameters + + range: TextRange + + Represents a range of text within a Text shape. This interface provides properties for styling and formatting text ranges. + + Returns void + + Example + ``` + typographyElement.applyToTextRange(textShape); + ``` + setFont: |- + ``` + setFont(font, variant?): void + ``` + + * Sets the font and optionally its variant for the typography element. + + Parameters + + font: Font + + The font to set. + + variant: FontVariant + + The font variant to set (optional). + + Returns void + + Example + ``` + typographyElement.setFont(newFont, newVariant); + ``` + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +LocalStorage: + overview: |- + Interface LocalStorage + ====================== + + Proxy for the local storage. Only elements owned by the plugin + can be stored and accessed. + Warning: other plugins won't be able to access this information but + the user could potentialy access the data through the browser information. + + ``` + interface LocalStorage { + getItem(key: string): string; + setItem(key: string, value: unknown): void; + removeItem(key: string): void; + getKeys(): string[]; + } + ``` + members: + Methods: + getItem: |- + ``` + getItem(key): string + ``` + + * Retrieve the element with the given key + Requires the `allow:localstorage` permission. + + Parameters + + key: string + + Returns string + setItem: |- + ``` + setItem(key, value): void + ``` + + * Set the data given the key. If the value already existed it + will be overriden. The value will be stored in a string representation. + Requires the `allow:localstorage` permission. + + Parameters + + key: string + + value: unknown + + Returns void + removeItem: |- + ``` + removeItem(key): void + ``` + + * Remove the value stored in the key. + Requires the `allow:localstorage` permission. + + Parameters + + key: string + + Returns void + getKeys: |- + ``` + getKeys(): string[] + ``` + + * Return all the keys for the data stored by the plugin. + Requires the `allow:localstorage` permission. + + Returns string[] +NavigateTo: + overview: |- + Interface NavigateTo + ==================== + + It takes the user from one board to the destination set in the interaction. + + ``` + interface NavigateTo { + type: "navigate-to"; + destination: Board; + preserveScrollPosition?: boolean; + animation?: Animation; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + Type of action + destination: |- + ``` + destination: Board + ``` + + Board to which the action targets + preserveScrollPosition: |- + ``` + preserveScrollPosition?: boolean + ``` + + When true the scroll will be preserved. + animation: |- + ``` + animation?: Animation + ``` + + Animation displayed with this interaction. +OpenOverlay: + overview: |- + Interface OpenOverlay + ===================== + + It opens a board right over the current board. + + ``` + interface OpenOverlay { + type: "open-overlay"; + destination: Board; + relativeTo?: Shape; + position?: + | "center" + | "manual" + | "top-left" + | "top-right" + | "top-center" + | "bottom-left" + | "bottom-right" + | "bottom-center"; + manualPositionLocation?: Point; + closeWhenClickOutside?: boolean; + addBackgroundOverlay?: boolean; + animation?: Animation; + } + ``` + + Hierarchy (view full) + + * OverlayAction + + OpenOverlay + members: + Properties: + type: |- + ``` + type + ``` + + The action type + destination: |- + ``` + destination: Board + ``` + + Overlay board that will be opened. + relativeTo: |- + ``` + relativeTo?: Shape + ``` + + Base shape to which the overlay will be positioned taking constraints into account. + position: |- + ``` + position?: + | "center" + | "manual" + | "top-left" + | "top-right" + | "top-center" + | "bottom-left" + | "bottom-right" + | "bottom-center" + ``` + + Positioning of the overlay. + manualPositionLocation: |- + ``` + manualPositionLocation?: Point + ``` + + For `position = 'manual'` the location of the overlay. + closeWhenClickOutside: |- + ``` + closeWhenClickOutside?: boolean + ``` + + When true the overlay will be closed when clicking outside + addBackgroundOverlay: |- + ``` + addBackgroundOverlay?: boolean + ``` + + When true a background will be added to the overlay. + animation: |- + ``` + animation?: Animation + ``` + + Animation displayed with this interaction. +OpenUrl: + overview: |- + Interface OpenUrl + ================= + + This action opens an URL in a new tab. + + ``` + interface OpenUrl { + type: "open-url"; + url: string; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + The action type + url: |- + ``` + url: string + ``` + + The URL to open when the action is executed +OverlayAction: + overview: |- + Interface OverlayAction + ======================= + + Base type for the actions "open-overlay" and "toggle-overlay" that share most of their properties + + ``` + interface OverlayAction { + destination: Board; + relativeTo?: Shape; + position?: + | "center" + | "manual" + | "top-left" + | "top-right" + | "top-center" + | "bottom-left" + | "bottom-right" + | "bottom-center"; + manualPositionLocation?: Point; + closeWhenClickOutside?: boolean; + addBackgroundOverlay?: boolean; + animation?: Animation; + } + ``` + + Hierarchy (view full) + + * OverlayAction + + OpenOverlay + + ToggleOverlay + members: + Properties: + destination: |- + ``` + destination: Board + ``` + + Overlay board that will be opened. + relativeTo: |- + ``` + relativeTo?: Shape + ``` + + Base shape to which the overlay will be positioned taking constraints into account. + position: |- + ``` + position?: + | "center" + | "manual" + | "top-left" + | "top-right" + | "top-center" + | "bottom-left" + | "bottom-right" + | "bottom-center" + ``` + + Positioning of the overlay. + manualPositionLocation: |- + ``` + manualPositionLocation?: Point + ``` + + For `position = 'manual'` the location of the overlay. + closeWhenClickOutside: |- + ``` + closeWhenClickOutside?: boolean + ``` + + When true the overlay will be closed when clicking outside + addBackgroundOverlay: |- + ``` + addBackgroundOverlay?: boolean + ``` + + When true a background will be added to the overlay. + animation: |- + ``` + animation?: Animation + ``` + + Animation displayed with this interaction. +Page: + overview: |- + Interface Page + ============== + + Page represents a page in the Penpot application. + It includes properties for the page's identifier and name, as well as methods for managing shapes on the page. + + ``` + interface Page { + id: string; + name: string; + rulerGuides: RulerGuide[]; + root: Shape; + getShapeById(id: string): null | Shape; + findShapes(criteria?: { + name?: string; + nameLike?: string; + type?: + | "boolean" + | "path" + | "ellipse" + | "image" + | "text" + | "group" + | "board" + | "rectangle" + | "svg-raw"; + }): Shape[]; + flows: Flow[]; + createFlow(name: string, board: Board): Flow; + removeFlow(flow: Flow): void; + addRulerGuide(orientation: RulerGuideOrientation, value: number, board?: Board): RulerGuide; + removeRulerGuide(guide: RulerGuide): void; + addCommentThread(content: string, position: Point): Promise; + removeCommentThread(commentThread: CommentThread): Promise; + findCommentThreads(criteria?: { + onlyYours: boolean; + showResolved: boolean; + }): Promise; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * PluginData + + Page + members: + Properties: + id: |- + ``` + id: string + ``` + + The `id` property is a unique identifier for the page. + name: |- + ``` + name: string + ``` + + The `name` property is the name of the page. + rulerGuides: |- + ``` + rulerGuides: RulerGuide[] + ``` + + The ruler guides attached to the board + root: |- + ``` + root: Shape + ``` + + The root shape of the current page. Will be the parent shape of all the shapes inside the document. + Requires `content:read` permission. + flows: |- + ``` + flows: Flow[] + ``` + + The interaction flows defined for the page. + Methods: + getShapeById: |- + ``` + getShapeById(id): null | Shape + ``` + + * Retrieves a shape by its unique identifier. + + Parameters + + id: string + + The unique identifier of the shape. + + Returns null | Shape + + Example + ``` + const shape = penpot.currentPage.getShapeById('shapeId'); + ``` + findShapes: |- + ``` + findShapes(criteria?): Shape[] + ``` + + * Finds all shapes on the page. + Optionaly it gets a criteria object to search for specific criteria + + Parameters + + criteria: { + name?: string; + nameLike?: string; + type?: + | "boolean" + | "path" + | "ellipse" + | "image" + | "text" + | "group" + | "board" + | "rectangle" + | "svg-raw"; + } + - Optionalname?: string + - OptionalnameLike?: string + - Optionaltype?: | "boolean" | "path" | "ellipse" | "image" | "text" | "group" | "board" | "rectangle" | "svg-raw" + + Returns Shape[] + + Example + ``` + const shapes = penpot.currentPage.findShapes({ name: 'exampleName' }); + ``` + createFlow: |- + ``` + createFlow(name, board): Flow + ``` + + * Creates a new flow in the page. + + Parameters + + name: string + + the name identifying the flow + + board: Board + + the starting board for the current flow + + Returns Flow + + Example + ``` + const flow = penpot.currentPage.createFlow('exampleFlow', board); + ``` + removeFlow: |- + ``` + removeFlow(flow): void + ``` + + * Removes the flow from the page + + Parameters + + flow: Flow + + the flow to be removed from the page + + Returns void + addRulerGuide: |- + ``` + addRulerGuide(orientation, value, board?): RulerGuide + ``` + + * Creates a new ruler guide. + + Parameters + + orientation: RulerGuideOrientation + + value: number + + board: Board + + Returns RulerGuide + removeRulerGuide: |- + ``` + removeRulerGuide(guide): void + ``` + + * Removes the `guide` from the current page. + + Parameters + + guide: RulerGuide + + Returns void + addCommentThread: |- + ``` + addCommentThread(content, position): Promise + ``` + + * Creates a new comment thread in the `position`. Optionaly adds + it into the `board`. + Returns the thread created. + Requires the `comment:write` permission. + + Parameters + + content: string + + position: Point + + Returns Promise + removeCommentThread: |- + ``` + removeCommentThread(commentThread): Promise + ``` + + * Removes the comment thread. + Requires the `comment:write` permission. + + Parameters + + commentThread: CommentThread + + Returns Promise + findCommentThreads: |- + ``` + findCommentThreads(criteria?): Promise + ``` + + * Find all the comments that match the criteria. + + + `onlyYours`: if `true` will return the threads where the current + user has engaged. + + `showResolved`: by default resolved comments will be hidden. If `true` + the resolved will be returned. + Requires the `comment:read` or `comment:write` permission. + + Parameters + + criteria: { + onlyYours: boolean; + showResolved: boolean; + } + - onlyYours: boolean + - showResolved: boolean + + Returns Promise + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +Path: + overview: |- + Interface Path + ============== + + Represents a path shape in Penpot. + This interface extends `ShapeBase` and includes properties and methods specific to paths. + + ``` + interface Path { + type: "path"; + toD(): string; + content: PathCommand[]; + fills: Fill[]; + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Path + members: + Properties: + type: |- + ``` + type + ``` + + The type of the shape, which is always 'path' for path shapes. + content: |- + ``` + content: PathCommand[] + ``` + + The content of the path shape, defined as an array of path commands. + fills: |- + ``` + fills: Fill[] + ``` + + The fills applied to the shape. + + Overrides ShapeBase.fills + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + toD: |- + ``` + toD(): string + ``` + + * Converts the path shape to its path data representation. + + Returns string + + Returns the path data (d attribute) as a string. + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +PathCommand: + overview: |- + Interface PathCommand + ===================== + + Represents a path command in Penpot. + This interface includes a property for defining the type of command. + + ``` + interface PathCommand { + command: + | "M" + | "move-to" + | "Z" + | "close-path" + | "L" + | "line-to" + | "H" + | "line-to-horizontal" + | "V" + | "line-to-vertical" + | "C" + | "curve-to" + | "S" + | "smooth-curve-to" + | "Q" + | "quadratic-bezier-curve-to" + | "T" + | "smooth-quadratic-bezier-curve-to" + | "A" + | "elliptical-arc"; + params?: { + x?: number; + y?: number; + c1x?: number; + c1y?: number; + c2x?: number; + c2y?: number; + rx?: number; + ry?: number; + xAxisRotation?: number; + largeArcFlag?: boolean; + sweepFlag?: boolean; + }; + } + ``` + members: + Properties: + command: |- + ``` + command: + | "M" + | "move-to" + | "Z" + | "close-path" + | "L" + | "line-to" + | "H" + | "line-to-horizontal" + | "V" + | "line-to-vertical" + | "C" + | "curve-to" + | "S" + | "smooth-curve-to" + | "Q" + | "quadratic-bezier-curve-to" + | "T" + | "smooth-quadratic-bezier-curve-to" + | "A" + | "elliptical-arc" + ``` + + The type of path command. + Possible values include: + + * 'M' or 'move-to': Move to a new point. + * 'Z' or 'close-path': Close the current path. + * 'L' or 'line-to': Draw a straight line to a new point. + * 'H' or 'line-to-horizontal': Draw a horizontal line to a new point. + * 'V' or 'line-to-vertical': Draw a vertical line to a new point. + * 'C' or 'curve-to': Draw a cubic Bezier curve to a new point. + * 'S' or 'smooth-curve-to': Draw a smooth cubic Bezier curve to a new point. + * 'Q' or 'quadratic-bezier-curve-to': Draw a quadratic Bezier curve to a new point. + * 'T' or 'smooth-quadratic-bezier-curve-to': Draw a smooth quadratic Bezier curve to a new point. + * 'A' or 'elliptical-arc': Draw an elliptical arc to a new point. + + Example + ``` + const pathCommand: PathCommand = { command: 'M', params: { x: 0, y: 0 } }; + ``` + params: |- + ``` + params?: { + x?: number; + y?: number; + c1x?: number; + c1y?: number; + c2x?: number; + c2y?: number; + rx?: number; + ry?: number; + xAxisRotation?: number; + largeArcFlag?: boolean; + sweepFlag?: boolean; + } + ``` + + Optional parameters associated with the path command. + + Type declaration + + * Optionalx?: number + + The x-coordinate of the point (or endpoint). + * Optionaly?: number + + The y-coordinate of the point (or endpoint). + * Optionalc1x?: number + + The x-coordinate of the first control point for curves. + * Optionalc1y?: number + + The y-coordinate of the first control point for curves. + * Optionalc2x?: number + + The x-coordinate of the second control point for curves. + * Optionalc2y?: number + + The y-coordinate of the second control point for curves. + * Optionalrx?: number + + The radius of the ellipse's x-axis. + * Optionalry?: number + + The radius of the ellipse's y-axis. + * OptionalxAxisRotation?: number + + The rotation angle of the ellipse's x-axis. + * OptionallargeArcFlag?: boolean + + A flag indicating whether to use the larger arc. + * OptionalsweepFlag?: boolean + + A flag indicating the direction of the arc. +PluginData: + overview: |- + Interface PluginData + ==================== + + Provides methods for managing plugin-specific data associated with a Penpot shape. + + ``` + interface PluginData { + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + } + ``` + + Hierarchy (view full) + + * PluginData + + File + + Library + + LibraryElement + + Page + + ShapeBase + members: + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` +PreviousScreen: + overview: |- + Interface PreviousScreen + ======================== + + It takes back to the last board shown. + + ``` + interface PreviousScreen { + type: "previous-screen"; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + The action type +Push: + overview: |- + Interface Push + ============== + + Push animation + + ``` + interface Push { + type: "push"; + direction: + | "left" + | "right" + | "up" + | "down"; + duration: number; + easing?: + | "linear" + | "ease" + | "ease-in" + | "ease-out" + | "ease-in-out"; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + Type of the animation + direction: |- + ``` + direction: + | "left" + | "right" + | "up" + | "down" + ``` + + Direction for the push animation + duration: |- + ``` + duration: number + ``` + + Duration of the animation effect + easing: |- + ``` + easing?: + | "linear" + | "ease" + | "ease-in" + | "ease-out" + | "ease-in-out" + ``` + + Function that the dissolve effect will follow for the interpolation. + Defaults to `linear` +Rectangle: + overview: |- + Interface Rectangle + =================== + + Represents a rectangle shape in Penpot. + This interface extends `ShapeBase` and includes properties specific to rectangles. + + ``` + interface Rectangle { + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + type: "rectangle"; + fills: Fill[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Rectangle + members: + Properties: + type: |- + ``` + type + ``` + + The type of the shape, which is always 'rect' for rectangle shapes. + fills: |- + ``` + fills: Fill[] + ``` + + The fills applied to the shape. + + Overrides ShapeBase.fills + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +RulerGuide: + overview: |- + Interface RulerGuide + ==================== + + Represents a ruler guide. These are horizontal or vertical lines that can be + used to position elements in the UI. + + ``` + interface RulerGuide { + orientation: RulerGuideOrientation; + position: number; + board?: Board; + } + ``` + members: + Properties: + orientation: |- + ``` + orientation: RulerGuideOrientation + ``` + + `orientation` indicates whether the ruler is either `horizontal` or `vertical` + position: |- + ``` + position: number + ``` + + `position` is the position in the axis in absolute positioning. If this is a board + guide will return the positioning relative to the board. + board: |- + ``` + board?: Board + ``` + + If the guide is attached to a board this will retrieve the board shape +Shadow: + overview: |- + Interface Shadow + ================ + + Represents shadow properties in Penpot. + This interface includes properties for defining drop shadows and inner shadows, along with their visual attributes. + + ``` + interface Shadow { + id?: string; + style?: "drop-shadow" | "inner-shadow"; + offsetX?: number; + offsetY?: number; + blur?: number; + spread?: number; + hidden?: boolean; + color?: Color; + } + ``` + members: + Properties: + id: |- + ``` + id?: string + ``` + + The optional unique identifier for the shadow. + style: |- + ``` + style?: "drop-shadow" | "inner-shadow" + ``` + + The optional style of the shadow. + + * 'drop-shadow': A shadow cast outside the element. + * 'inner-shadow': A shadow cast inside the element. + offsetX: |- + ``` + offsetX?: number + ``` + + The optional X-axis offset of the shadow. + offsetY: |- + ``` + offsetY?: number + ``` + + The optional Y-axis offset of the shadow. + blur: |- + ``` + blur?: number + ``` + + The optional blur radius of the shadow. + spread: |- + ``` + spread?: number + ``` + + The optional spread radius of the shadow. + hidden: |- + ``` + hidden?: boolean + ``` + + Specifies whether the shadow is hidden. + Defaults to false if omitted. + color: |- + ``` + color?: Color + ``` + + The optional color of the shadow, defined by a Color object. +ShapeBase: + overview: |- + Interface ShapeBase + =================== + + Represents the base properties and methods of a shape in Penpot. + This interface provides common properties and methods shared by all shapes. + + ``` + interface ShapeBase { + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + fills: Fill[] | "mixed"; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + } + ``` + + Hierarchy (view full) + + * PluginData + + ShapeBase + - Board + - Boolean + - Ellipse + - Group + - Image + - Path + - Rectangle + - SvgRaw + - Text + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + fills: |- + ``` + fills: Fill[] | "mixed" + ``` + + The fills applied to the shape. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +Slide: + overview: |- + Interface Slide + =============== + + Slide animation + + ``` + interface Slide { + type: "slide"; + way: "in" | "out"; + direction: + | "left" + | "right" + | "up" + | "down"; + duration: number; + offsetEffect?: boolean; + easing?: + | "linear" + | "ease" + | "ease-in" + | "ease-out" + | "ease-in-out"; + } + ``` + members: + Properties: + type: |- + ``` + type + ``` + + Type of the animation. + way: |- + ``` + way: "in" | "out" + ``` + + Indicate if the slide will be either in-to-out `in` or out-to-in `out`. + direction: |- + ``` + direction: + | "left" + | "right" + | "up" + | "down" + ``` + + Direction for the slide animation. + duration: |- + ``` + duration: number + ``` + + Duration of the animation effect. + offsetEffect: |- + ``` + offsetEffect?: boolean + ``` + + If `true` the offset effect will be used. + easing: |- + ``` + easing?: + | "linear" + | "ease" + | "ease-in" + | "ease-out" + | "ease-in-out" + ``` + + Function that the dissolve effect will follow for the interpolation. + Defaults to `linear`. +Stroke: + overview: |- + Interface Stroke + ================ + + Represents stroke properties in Penpot. You can add a stroke to any shape except for groups. + This interface includes properties for defining the color, style, width, alignment, and caps of a stroke. + + ``` + interface Stroke { + strokeColor?: string; + strokeColorRefFile?: string; + strokeColorRefId?: string; + strokeOpacity?: number; + strokeStyle?: + | "svg" + | "none" + | "mixed" + | "solid" + | "dotted" + | "dashed"; + strokeWidth?: number; + strokeAlignment?: "center" | "inner" | "outer"; + strokeCapStart?: StrokeCap; + strokeCapEnd?: StrokeCap; + strokeColorGradient?: Gradient; + } + ``` + members: + Properties: + strokeColor: |- + ``` + strokeColor?: string + ``` + + The optional color of the stroke, represented as a string (e.g., '#FF5733'). + strokeColorRefFile: |- + ``` + strokeColorRefFile?: string + ``` + + The optional reference to an external file for the stroke color. + strokeColorRefId: |- + ``` + strokeColorRefId?: string + ``` + + The optional reference ID within the external file for the stroke color. + strokeOpacity: |- + ``` + strokeOpacity?: number + ``` + + The optional opacity level of the stroke color, ranging from 0 (fully transparent) to 1 (fully opaque). + Defaults to 1 if omitted. + strokeStyle: |- + ``` + strokeStyle?: + | "svg" + | "none" + | "mixed" + | "solid" + | "dotted" + | "dashed" + ``` + + The optional style of the stroke. + strokeWidth: |- + ``` + strokeWidth?: number + ``` + + The optional width of the stroke. + strokeAlignment: |- + ``` + strokeAlignment?: "center" | "inner" | "outer" + ``` + + The optional alignment of the stroke relative to the shape's boundary. + strokeCapStart: |- + ``` + strokeCapStart?: StrokeCap + ``` + + The optional cap style for the start of the stroke. + strokeCapEnd: |- + ``` + strokeCapEnd?: StrokeCap + ``` + + The optional cap style for the end of the stroke. + strokeColorGradient: |- + ``` + strokeColorGradient?: Gradient + ``` + + The optional gradient stroke defined by a Gradient object. +SvgRaw: + overview: |- + Interface SvgRaw + ================ + + Represents an SVG raw shape in Penpot. + This interface extends `ShapeBase` and includes properties specific to raw SVG shapes. + + ``` + interface SvgRaw { + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + fills: Fill[] | "mixed"; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + type: "svg-raw"; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + SvgRaw + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + fills: |- + ``` + fills: Fill[] | "mixed" + ``` + + The fills applied to the shape. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + type: |- + ``` + type + ``` + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void +Text: + overview: |- + Interface Text + ============== + + Text represents a text element in the Penpot application, extending the base shape interface. + It includes various properties to define the text content and its styling attributes. + + ``` + interface Text { + getPluginData(key: string): string; + setPluginData(key: string, value: string): void; + getPluginDataKeys(): string[]; + getSharedPluginData(namespace: string, key: string): string; + setSharedPluginData(namespace: string, key: string, value: string): void; + getSharedPluginDataKeys(namespace: string): string[]; + id: string; + name: string; + parent: null | Shape; + x: number; + y: number; + width: number; + height: number; + bounds: Bounds; + center: Point; + blocked: boolean; + hidden: boolean; + visible: boolean; + proportionLock: boolean; + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale"; + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom"; + borderRadius: number; + borderRadiusTopLeft: number; + borderRadiusTopRight: number; + borderRadiusBottomRight: number; + borderRadiusBottomLeft: number; + opacity: number; + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity"; + shadows: Shadow[]; + blur?: Blur; + exports: Export[]; + boardX: number; + boardY: number; + parentX: number; + parentY: number; + flipX: boolean; + flipY: boolean; + rotation: number; + fills: Fill[] | "mixed"; + strokes: Stroke[]; + layoutChild?: LayoutChildProperties; + layoutCell?: LayoutChildProperties; + isComponentInstance(): boolean; + isComponentMainInstance(): boolean; + isComponentCopyInstance(): boolean; + isComponentRoot(): boolean; + isComponentHead(): boolean; + componentRefShape(): null | Shape; + componentRoot(): null | Shape; + componentHead(): null | Shape; + component(): null | LibraryComponent; + detach(): void; + resize(width: number, height: number): void; + rotate(angle: number, center?: null | { + x: number; + y: number; + }): void; + export(config: Export): Promise; + interactions: Interaction[]; + addInteraction(trigger: Trigger, action: Action, delay?: number): Interaction; + removeInteraction(interaction: Interaction): void; + clone(): Shape; + remove(): void; + type: "text"; + characters: string; + growType: "fixed" | "auto-width" | "auto-height"; + fontId: string; + fontFamily: string; + fontVariantId: string; + fontSize: string; + fontWeight: string; + fontStyle: + | null + | "normal" + | "italic" + | "mixed"; + lineHeight: string; + letterSpacing: string; + textTransform: + | null + | "mixed" + | "uppercase" + | "capitalize" + | "lowercase"; + textDecoration: + | null + | "mixed" + | "underline" + | "line-through"; + direction: + | null + | "mixed" + | "ltr" + | "rtl"; + align: + | null + | "center" + | "left" + | "right" + | "mixed" + | "justify"; + verticalAlign: + | null + | "center" + | "top" + | "bottom"; + getRange(start: number, end: number): TextRange; + applyTypography(typography: LibraryTypography): void; + } + ``` + + Hierarchy (view full) + + * ShapeBase + + Text + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the shape. + name: |- + ``` + name: string + ``` + + The name of the shape. + parent: |- + ``` + parent: null | Shape + ``` + + The parent shape. If the shape is the first level the parent will be the root shape. + For the root shape the parent is null + x: |- + ``` + x: number + ``` + + The x-coordinate of the shape's position. + y: |- + ``` + y: number + ``` + + The y-coordinate of the shape's position. + width: |- + ``` + width: number + ``` + + The width of the shape. + height: |- + ``` + height: number + ``` + + The height of the shape. + bounds: |- + ``` + bounds: Bounds + ``` + + Returns + + Returns the bounding box surrounding the current shape + center: |- + ``` + center: Point + ``` + + Returns + + Returns the geometric center of the shape + blocked: |- + ``` + blocked: boolean + ``` + + Indicates whether the shape is blocked. + hidden: |- + ``` + hidden: boolean + ``` + + Indicates whether the shape is hidden. + visible: |- + ``` + visible: boolean + ``` + + Indicates whether the shape is visible. + proportionLock: |- + ``` + proportionLock: boolean + ``` + + Indicates whether the shape has proportion lock enabled. + constraintsHorizontal: |- + ``` + constraintsHorizontal: + | "center" + | "left" + | "right" + | "leftright" + | "scale" + ``` + + The horizontal constraints applied to the shape. + constraintsVertical: |- + ``` + constraintsVertical: + | "center" + | "top" + | "bottom" + | "scale" + | "topbottom" + ``` + + The vertical constraints applied to the shape. + borderRadius: |- + ``` + borderRadius: number + ``` + + The border radius of the shape. + borderRadiusTopLeft: |- + ``` + borderRadiusTopLeft: number + ``` + + The border radius of the top-left corner of the shape. + borderRadiusTopRight: |- + ``` + borderRadiusTopRight: number + ``` + + The border radius of the top-right corner of the shape. + borderRadiusBottomRight: |- + ``` + borderRadiusBottomRight: number + ``` + + The border radius of the bottom-right corner of the shape. + borderRadiusBottomLeft: |- + ``` + borderRadiusBottomLeft: number + ``` + + The border radius of the bottom-left corner of the shape. + opacity: |- + ``` + opacity: number + ``` + + The opacity of the shape. + blendMode: |- + ``` + blendMode: + | "difference" + | "normal" + | "darken" + | "multiply" + | "color-burn" + | "lighten" + | "screen" + | "color-dodge" + | "overlay" + | "soft-light" + | "hard-light" + | "exclusion" + | "hue" + | "saturation" + | "color" + | "luminosity" + ``` + + The blend mode applied to the shape. + shadows: |- + ``` + shadows: Shadow[] + ``` + + The shadows applied to the shape. + blur: |- + ``` + blur?: Blur + ``` + + The blur effect applied to the shape. + exports: |- + ``` + exports: Export[] + ``` + + The export settings of the shape. + boardX: |- + ``` + boardX: number + ``` + + The x-coordinate of the shape relative to its board. + boardY: |- + ``` + boardY: number + ``` + + The y-coordinate of the shape relative to its board. + parentX: |- + ``` + parentX: number + ``` + + The x-coordinate of the shape relative to its parent. + parentY: |- + ``` + parentY: number + ``` + + The y-coordinate of the shape relative to its parent. + flipX: |- + ``` + flipX: boolean + ``` + + Indicates whether the shape is flipped horizontally. + flipY: |- + ``` + flipY: boolean + ``` + + Indicates whether the shape is flipped vertically. + rotation: |- + ``` + rotation: number + ``` + + Returns + + Returns the rotation in degrees of the shape with respect to it's center. + fills: |- + ``` + fills: Fill[] | "mixed" + ``` + + The fills applied to the shape. + strokes: |- + ``` + strokes: Stroke[] + ``` + + The strokes applied to the shape. + layoutChild: |- + ``` + layoutChild?: LayoutChildProperties + ``` + + Layout properties for children of the shape. + layoutCell: |- + ``` + layoutCell?: LayoutChildProperties + ``` + + Layout properties for cells in a grid layout. + interactions: |- + ``` + interactions: Interaction[] + ``` + + The interactions for the current shape. + type: |- + ``` + type + ``` + + The type of the shape, which is always 'text' for text shapes. + characters: |- + ``` + characters: string + ``` + + The characters contained within the text shape. + growType: |- + ``` + growType: "fixed" | "auto-width" | "auto-height" + ``` + + The grow type of the text shape, defining how the text box adjusts its size. + Possible values are: + + * 'fixed': Fixed size. + * 'auto-width': Adjusts width automatically. + * 'auto-height': Adjusts height automatically. + fontId: |- + ``` + fontId: string + ``` + + The font ID used in the text shape, or 'mixed' if multiple fonts are used. + fontFamily: |- + ``` + fontFamily: string + ``` + + The font family used in the text shape, or 'mixed' if multiple font families are used. + fontVariantId: |- + ``` + fontVariantId: string + ``` + + The font variant ID used in the text shape, or 'mixed' if multiple font variants are used. + fontSize: |- + ``` + fontSize: string + ``` + + The font size used in the text shape, or 'mixed' if multiple font sizes are used. + fontWeight: |- + ``` + fontWeight: string + ``` + + The font weight used in the text shape, or 'mixed' if multiple font weights are used. + fontStyle: |- + ``` + fontStyle: + | null + | "normal" + | "italic" + | "mixed" + ``` + + The font style used in the text shape, or 'mixed' if multiple font styles are used. + lineHeight: |- + ``` + lineHeight: string + ``` + + The line height used in the text shape, or 'mixed' if multiple line heights are used. + letterSpacing: |- + ``` + letterSpacing: string + ``` + + The letter spacing used in the text shape, or 'mixed' if multiple letter spacings are used. + textTransform: |- + ``` + textTransform: + | null + | "mixed" + | "uppercase" + | "capitalize" + | "lowercase" + ``` + + The text transform applied to the text shape, or 'mixed' if multiple text transforms are used. + textDecoration: |- + ``` + textDecoration: + | null + | "mixed" + | "underline" + | "line-through" + ``` + + The text decoration applied to the text shape, or 'mixed' if multiple text decorations are used. + direction: |- + ``` + direction: + | null + | "mixed" + | "ltr" + | "rtl" + ``` + + The text direction for the text shape, or 'mixed' if multiple directions are used. + align: |- + ``` + align: + | null + | "center" + | "left" + | "right" + | "mixed" + | "justify" + ``` + + The horizontal alignment of the text shape. It can be a specific alignment or 'mixed' if multiple alignments are used. + verticalAlign: |- + ``` + verticalAlign: + | null + | "center" + | "top" + | "bottom" + ``` + + The vertical alignment of the text shape. It can be a specific alignment or 'mixed' if multiple alignments are used. + Methods: + getPluginData: |- + ``` + getPluginData(key): string + ``` + + * Retrieves the data for our own plugin, given a specific key. + + Parameters + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the data associated with the key as a string. + + Example + ``` + const data = shape.getPluginData('exampleKey');console.log(data); + ``` + setPluginData: |- + ``` + setPluginData(key, value): void + ``` + + * Sets the plugin-specific data for the given key. + + Parameters + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setPluginData('exampleKey', 'exampleValue'); + ``` + getPluginDataKeys: |- + ``` + getPluginDataKeys(): string[] + ``` + + * Retrieves all the keys for the plugin-specific data. + + Returns string[] + + Returns an array of strings representing all the keys. + + Example + ``` + const keys = shape.getPluginDataKeys();console.log(keys); + ``` + getSharedPluginData: |- + ``` + getSharedPluginData(namespace, key): string + ``` + + * If we know the namespace of an external plugin, this is the way to get their data. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to retrieve the data. + + Returns string + + Returns the shared data associated with the key as a string. + + Example + ``` + const sharedData = shape.getSharedPluginData('exampleNamespace', 'exampleKey');console.log(sharedData); + ``` + setSharedPluginData: |- + ``` + setSharedPluginData(namespace, key, value): void + ``` + + * Sets the shared plugin-specific data for the given namespace and key. + + Parameters + + namespace: string + + The namespace for the shared data. + + key: string + + The key for which to set the data. + + value: string + + The data to set for the key. + + Returns void + + Example + ``` + shape.setSharedPluginData('exampleNamespace', 'exampleKey', 'exampleValue'); + ``` + getSharedPluginDataKeys: |- + ``` + getSharedPluginDataKeys(namespace): string[] + ``` + + * Retrieves all the keys for the shared plugin-specific data in the given namespace. + + Parameters + + namespace: string + + The namespace for the shared data. + + Returns string[] + + Returns an array of strings representing all the keys in the namespace. + + Example + ``` + const sharedKeys = shape.getSharedPluginDataKeys('exampleNamespace');console.log(sharedKeys); + ``` + isComponentInstance: |- + ``` + isComponentInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component instance + isComponentMainInstance: |- + ``` + isComponentMainInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **main** instance + isComponentCopyInstance: |- + ``` + isComponentCopyInstance(): boolean + ``` + + * Returns boolean + + Returns true if the current shape is inside a component **copy** instance + isComponentRoot: |- + ``` + isComponentRoot(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the root of a component tree + isComponentHead: |- + ``` + isComponentHead(): boolean + ``` + + * Returns boolean + + Returns true when the current shape is the head of a components tree nested structure + componentRefShape: |- + ``` + componentRefShape(): null | Shape + ``` + + * Returns null | Shape + + Returns the equivalent shape in the component main instance. If the current shape is inside a + main instance will return `null`; + componentRoot: |- + ``` + componentRoot(): null | Shape + ``` + + * Returns null | Shape + + Returns the root of the component tree structure for the current shape. If the current shape + is already a root will return itself. + componentHead: |- + ``` + componentHead(): null | Shape + ``` + + * Returns null | Shape + + Returns the head of the component tree structure for the current shape. If the current shape + is already a head will return itself. + component: |- + ``` + component(): null | LibraryComponent + ``` + + * Returns null | LibraryComponent + + If the shape is a component instance, returns the reference to the component associated + otherwise will return null + detach: |- + ``` + detach(): void + ``` + + * If the current shape is a component it will remove the component information and leave the + shape as a "basic shape" + + Returns void + resize: |- + ``` + resize(width, height): void + ``` + + * Resizes the shape to the specified width and height. + + Parameters + + width: number + + The new width of the shape. + + height: number + + The new height of the shape. + + Returns void + + Example + ``` + shape.resize(200, 100); + ``` + rotate: |- + ``` + rotate(angle, center?): void + ``` + + * Rotates the shape in relation with the given center. + + Parameters + + angle: number + + Angle in degrees to rotate. + + center: null | { + x: number; + y: number; + } + + Center of the transform rotation. If not send will use the geometri center of the shapes. + + Returns void + + Example + ``` + shape.rotate(45); + ``` + export: |- + ``` + export(config): Promise + ``` + + * Generates an export from the current shape. + + Parameters + + config: Export + + Returns Promise + + Example + ``` + shape.export({ type: 'png', scale: 2 }); + ``` + addInteraction: |- + ``` + addInteraction(trigger, action, delay?): Interaction + ``` + + * Adds a new interaction to the shape. + + Parameters + + trigger: Trigger + + defines the conditions under which the action will be triggered + + action: Action + + defines what will be executed when the trigger happens + + delay: number + + for the type of trigger `after-delay` will specify the time after triggered. Ignored otherwise. + + Returns Interaction + + Example + ``` + shape.addInteraction('click', { type: 'navigate-to', destination: anotherBoard }); + ``` + removeInteraction: |- + ``` + removeInteraction(interaction): void + ``` + + * Removes the interaction from the shape. + + Parameters + + interaction: Interaction + + is the interaction to remove from the shape + + Returns void + + Example + ``` + shape.removeInteraction(interaction); + ``` + clone: |- + ``` + clone(): Shape + ``` + + * Creates a clone of the shape. + + Returns Shape + + Returns a new instance of the shape with identical properties. + remove: |- + ``` + remove(): void + ``` + + * Removes the shape from its parent. + + Returns void + getRange: |- + ``` + getRange(start, end): TextRange + ``` + + * Gets a text range within the text shape. + + Parameters + + start: number + + The start index of the text range. + + end: number + + The end index of the text range. + + Returns TextRange + + Returns a TextRange object representing the specified text range. + + Example + ``` + const textRange = textShape.getRange(0, 10);console.log(textRange.characters); + ``` + applyTypography: |- + ``` + applyTypography(typography): void + ``` + + * Applies a typography style to the text shape. + + Parameters + + typography: LibraryTypography + + The typography style to apply. + + Returns void + + Remarks + + This method sets various typography properties for the text shape according to the given typography style. + + Example + ``` + textShape.applyTypography(typography); + ``` +TextRange: + overview: |- + Interface TextRange + =================== + + Represents a range of text within a Text shape. + This interface provides properties for styling and formatting text ranges. + + ``` + interface TextRange { + shape: Text; + characters: string; + fontId: string; + fontFamily: string; + fontVariantId: string; + fontSize: string; + fontWeight: string; + fontStyle: + | null + | "normal" + | "italic" + | "mixed"; + lineHeight: string; + letterSpacing: string; + textTransform: + | null + | "none" + | "mixed" + | "uppercase" + | "capitalize" + | "lowercase"; + textDecoration: + | null + | "none" + | "mixed" + | "underline" + | "line-through"; + direction: + | null + | "mixed" + | "ltr" + | "rtl"; + fills: Fill[] | "mixed"; + align: + | null + | "center" + | "left" + | "right" + | "mixed" + | "justify"; + verticalAlign: + | null + | "center" + | "top" + | "bottom" + | "mixed"; + applyTypography(typography: LibraryTypography): void; + } + ``` + members: + Properties: + shape: |- + ``` + shape: Text + ``` + + The Text shape to which this text range belongs. + characters: |- + ``` + characters: string + ``` + + The characters associated with the current text range. + fontId: |- + ``` + fontId: string + ``` + + The font ID of the text range. It can be a specific font ID or 'mixed' if multiple fonts are used. + fontFamily: |- + ``` + fontFamily: string + ``` + + The font family of the text range. It can be a specific font family or 'mixed' if multiple font families are used. + fontVariantId: |- + ``` + fontVariantId: string + ``` + + The font variant ID of the text range. It can be a specific font variant ID or 'mixed' if multiple font variants are used. + fontSize: |- + ``` + fontSize: string + ``` + + The font size of the text range. It can be a specific font size or 'mixed' if multiple font sizes are used. + fontWeight: |- + ``` + fontWeight: string + ``` + + The font weight of the text range. It can be a specific font weight or 'mixed' if multiple font weights are used. + fontStyle: |- + ``` + fontStyle: + | null + | "normal" + | "italic" + | "mixed" + ``` + + The font style of the text range. It can be a specific font style or 'mixed' if multiple font styles are used. + lineHeight: |- + ``` + lineHeight: string + ``` + + The line height of the text range. It can be a specific line height or 'mixed' if multiple line heights are used. + letterSpacing: |- + ``` + letterSpacing: string + ``` + + The letter spacing of the text range. It can be a specific letter spacing or 'mixed' if multiple letter spacings are used. + textTransform: |- + ``` + textTransform: + | null + | "none" + | "mixed" + | "uppercase" + | "capitalize" + | "lowercase" + ``` + + The text transform applied to the text range. It can be a specific text transform or 'mixed' if multiple text transforms are used. + textDecoration: |- + ``` + textDecoration: + | null + | "none" + | "mixed" + | "underline" + | "line-through" + ``` + + The text decoration applied to the text range. It can be a specific text decoration or 'mixed' if multiple text decorations are used. + direction: |- + ``` + direction: + | null + | "mixed" + | "ltr" + | "rtl" + ``` + + The text direction for the text range. It can be a specific direction or 'mixed' if multiple directions are used. + fills: |- + ``` + fills: Fill[] | "mixed" + ``` + + The fill styles applied to the text range. + align: |- + ``` + align: + | null + | "center" + | "left" + | "right" + | "mixed" + | "justify" + ``` + + The horizontal alignment of the text range. It can be a specific alignment or 'mixed' if multiple alignments are used. + verticalAlign: |- + ``` + verticalAlign: + | null + | "center" + | "top" + | "bottom" + | "mixed" + ``` + + The vertical alignment of the text range. It can be a specific alignment or 'mixed' if multiple alignments are used. + Methods: + applyTypography: |- + ``` + applyTypography(typography): void + ``` + + * Applies a typography style to the text range. + This method sets various typography properties for the text range according to the given typography style. + + Parameters + + typography: LibraryTypography + + The typography style to apply. + + Returns void + + Example + ``` + textRange.applyTypography(typography); + ``` +ToggleOverlay: + overview: |- + Interface ToggleOverlay + ======================= + + It opens an overlay if it is not already opened or closes it if it is already opened. + + ``` + interface ToggleOverlay { + destination: Board; + relativeTo?: Shape; + position?: + | "center" + | "manual" + | "top-left" + | "top-right" + | "top-center" + | "bottom-left" + | "bottom-right" + | "bottom-center"; + manualPositionLocation?: Point; + closeWhenClickOutside?: boolean; + addBackgroundOverlay?: boolean; + animation?: Animation; + type: "toggle-overlay"; + } + ``` + + Hierarchy (view full) + + * OverlayAction + + ToggleOverlay + members: + Properties: + destination: |- + ``` + destination: Board + ``` + + Overlay board that will be opened. + relativeTo: |- + ``` + relativeTo?: Shape + ``` + + Base shape to which the overlay will be positioned taking constraints into account. + position: |- + ``` + position?: + | "center" + | "manual" + | "top-left" + | "top-right" + | "top-center" + | "bottom-left" + | "bottom-right" + | "bottom-center" + ``` + + Positioning of the overlay. + manualPositionLocation: |- + ``` + manualPositionLocation?: Point + ``` + + For `position = 'manual'` the location of the overlay. + closeWhenClickOutside: |- + ``` + closeWhenClickOutside?: boolean + ``` + + When true the overlay will be closed when clicking outside + addBackgroundOverlay: |- + ``` + addBackgroundOverlay?: boolean + ``` + + When true a background will be added to the overlay. + animation: |- + ``` + animation?: Animation + ``` + + Animation displayed with this interaction. + type: |- + ``` + type + ``` + + The action type +Track: + overview: |- + Interface Track + =============== + + Represents a track configuration in Penpot. + This interface includes properties for defining the type and value of a track used in layout configurations. + + ``` + interface Track { + type: TrackType; + value: null | number; + } + ``` + members: + Properties: + type: |- + ``` + type: TrackType + ``` + + The type of the track. + This can be one of the following values: + + * 'flex': A flexible track type. + * 'fixed': A fixed track type. + * 'percent': A track type defined by a percentage. + * 'auto': An automatic track type. + value: |- + ``` + value: null | number + ``` + + The value of the track. + This can be a number representing the size of the track, or null if not applicable. +User: + overview: |- + Interface User + ============== + + Represents a user in Penpot. + + ``` + interface User { + id: string; + name?: string; + avatarUrl?: string; + color: string; + sessionId?: string; + } + ``` + + Hierarchy (view full) + + * User + + ActiveUser + members: + Properties: + id: |- + ``` + id: string + ``` + + The unique identifier of the user. + + Example + ``` + const userId = user.id;console.log(userId); + ``` + name: |- + ``` + name?: string + ``` + + The name of the user. + + Example + ``` + const userName = user.name;console.log(userName); + ``` + avatarUrl: |- + ``` + avatarUrl?: string + ``` + + The URL of the user's avatar image. + + Example + ``` + const avatarUrl = user.avatarUrl;console.log(avatarUrl); + ``` + color: |- + ``` + color: string + ``` + + The color associated with the user. + + Example + ``` + const userColor = user.color;console.log(userColor); + ``` + sessionId: |- + ``` + sessionId?: string + ``` + + The session ID of the user. + + Example + ``` + const sessionId = user.sessionId;console.log(sessionId); + ``` +Viewport: + overview: |- + Interface Viewport + ================== + + Viewport represents the viewport in the Penpot application. + It includes the center point, zoom level, and the bounds of the viewport. + + ``` + interface Viewport { + center: Point; + zoom: number; + bounds: Bounds; + zoomReset(): void; + zoomToFitAll(): void; + zoomIntoView(shapes: Shape[]): void; + } + ``` + members: + Properties: + center: |- + ``` + center: Point + ``` + + the `center` point of the current viewport. If changed will change the + viewport position. + zoom: |- + ``` + zoom: number + ``` + + the `zoom` level as a number where `1` represents 100%. + bounds: |- + ``` + bounds: Bounds + ``` + + the `bounds` are the current coordinates of the viewport. + Methods: + zoomReset: |- + ``` + zoomReset(): void + ``` + + * Resets the zoom level. + + Returns void + zoomToFitAll: |- + ``` + zoomToFitAll(): void + ``` + + * Changes the viewport and zoom so can fit all the current shapes in the page. + + Returns void + zoomIntoView: |- + ``` + zoomIntoView(shapes): void + ``` + + * Changes the viewport and zoom so all the `shapes` in the argument are + visible. + + Parameters + + shapes: Shape[] + + Returns void +Action: + overview: |- + Type Alias Action + ================= + + ``` + Action: + | NavigateTo + | OpenOverlay + | ToggleOverlay + | CloseOverlay + | PreviousScreen + | OpenUrl + ``` + + Type for all the possible types of actions in an interaction. + members: {} +Animation: + overview: |- + Type Alias Animation + ==================== + + ``` + Animation: Dissolve | Slide | Push + ``` + + Type of all the animations that can be added to an interaction. + members: {} +BooleanType: + overview: |- + Type Alias BooleanType + ====================== + + ``` + BooleanType: + | "union" + | "difference" + | "exclude" + | "intersection" + ``` + + Represents the boolean operation types available in Penpot. + These types define how shapes can be combined or modified using boolean operations. + members: {} +Bounds: + overview: |- + Type Alias Bounds + ================= + + ``` + Bounds: { + x: number; + y: number; + width: number; + height: number; + } + ``` + + Bounds represents the boundaries of a rectangular area, + defined by the coordinates of the top-left corner and the dimensions of the rectangle. + + Type declaration + + * x: number + + Top-left x position of the rectangular area defined + * y: number + + Top-left y position of the rectangular area defined + * width: number + + Width of the represented area + * height: number + + Height of the represented area + + Example + ``` + const bounds = { x: 50, y: 50, width: 200, height: 100 };console.log(bounds); + ``` + members: {} +Gradient: + overview: |- + Type Alias Gradient + =================== + + ``` + Gradient: { + type: "linear" | "radial"; + startX: number; + startY: number; + endX: number; + endY: number; + width: number; + stops: { + color: string; + opacity?: number; + offset: number; + }[]; + } + ``` + + Represents a gradient configuration in Penpot. + A gradient can be either linear or radial and includes properties to define its shape, position, and color stops. + + Type declaration + + * type: "linear" | "radial" + + Specifies the type of gradient. + + + 'linear': A gradient that transitions colors along a straight line. + + 'radial': A gradient that transitions colors radiating outward from a central point. + + Example + ``` + const gradient: Gradient = { type: 'linear', startX: 0, startY: 0, endX: 100, endY: 100, width: 100, stops: [{ color: '#FF5733', offset: 0 }] }; + ``` + * startX: number + + The X-coordinate of the starting point of the gradient. + * startY: number + + The Y-coordinate of the starting point of the gradient. + * endX: number + + The X-coordinate of the ending point of the gradient. + * endY: number + + The Y-coordinate of the ending point of the gradient. + * width: number + + The width of the gradient. For radial gradients, this could be interpreted as the radius. + * stops: { color: string; opacity?: number; offset: number; }[] + + An array of color stops that define the gradient. + members: {} +Guide: + overview: |- + Type Alias Guide + ================ + + ``` + Guide: GuideColumn | GuideRow | GuideSquare + ``` + + Represents a board guide in Penpot. + This type can be one of several specific board guide types: column, row, or square. + members: {} +ImageData: + overview: |- + Type Alias ImageData + ==================== + + ``` + ImageData: { + name?: string; + width: number; + height: number; + mtype?: string; + id: string; + keepAspectRatio?: boolean; + } + ``` + + Represents image data in Penpot. + This includes properties for defining the image's dimensions, metadata, and aspect ratio handling. + + Type declaration + + * Optionalname?: string + + The optional name of the image. + * width: number + + The width of the image. + * height: number + + The height of the image. + * Optionalmtype?: string + + The optional media type of the image (e.g., 'image/png', 'image/jpeg'). + * id: string + + The unique identifier for the image. + * OptionalkeepAspectRatio?: boolean + + Whether to keep the aspect ratio of the image when resizing. + Defaults to false if omitted. + members: {} +LibraryContext: + overview: |- + Type Alias LibraryContext + ========================= + + ``` + LibraryContext: { + local: Library; + connected: Library[]; + availableLibraries(): Promise; + connectLibrary(libraryId: string): Promise; + } + ``` + + Represents the context of Penpot libraries, including both local and connected libraries. + This type contains references to the local library and an array of connected libraries. + + Type declaration + + * Readonlylocal: Library + + The local library in the Penpot context. + + Example + ``` + const localLibrary = libraryContext.local; + ``` + * Readonlyconnected: Library[] + + An array of connected libraries in the Penpot context. + + Example + ``` + const connectedLibraries = libraryContext.connected; + ``` + * availableLibraries:function + + ``` + availableLibraries(): Promise + ``` + + + Retrieves a summary of available libraries that can be connected to. + + Returns Promise + + Returns a promise that resolves to an array of `LibrarySummary` objects representing available libraries. + + Example + ``` + const availableLibraries = await libraryContext.availableLibraries(); + ``` + * connectLibrary:function + + ``` + connectLibrary(libraryId): Promise + ``` + + + Connects to a specific library identified by its ID. + + Parameters + - libraryId: string + + The ID of the library to connect to. + + Returns Promise + + Returns a promise that resolves to the `Library` object representing the connected library. + + Example + ``` + const connectedLibrary = await libraryContext.connectLibrary('library-id'); + ``` + members: {} +Point: + overview: |- + Type Alias Point + ================ + + ``` + Point: { + x: number; + y: number; + } + ``` + + Point represents a point in 2D space, typically with x and y coordinates. + members: {} +RulerGuideOrientation: + overview: |- + Type Alias RulerGuideOrientation + ================================ + + ``` + RulerGuideOrientation: "horizontal" | "vertical" + ``` + members: {} +Shape: + overview: |- + Type Alias Shape + ================ + + ``` + Shape: + | Board + | Group + | Boolean + | Rectangle + | Path + | Text + | Ellipse + | SvgRaw + | Image + ``` + + Shape represents a union of various shape types used in the Penpot project. + This type allows for different shapes to be handled under a single type umbrella. + + Example + ``` + let shape: Shape;if (penpot.utils.types.isRectangle(shape)) { console.log(shape.type);} + ``` + members: {} +StrokeCap: + overview: |- + Type Alias StrokeCap + ==================== + + ``` + StrokeCap: + | "round" + | "square" + | "line-arrow" + | "triangle-arrow" + | "square-marker" + | "circle-marker" + | "diamond-marker" + ``` + + Represents the cap style of a stroke in Penpot. + This type defines various styles for the ends of a stroke. + members: {} +Theme: + overview: |- + Type Alias Theme + ================ + + ``` + Theme: "light" | "dark" + ``` + + This type specifies the possible themes: 'light' or 'dark'. + members: {} +TrackType: + overview: |- + Type Alias TrackType + ==================== + + ``` + TrackType: + | "flex" + | "fixed" + | "percent" + | "auto" + ``` + + Represents the type of track in Penpot. + This type defines various track types that can be used in layout configurations. + members: {} +Trigger: + overview: |- + Type Alias Trigger + ================== + + ``` + Trigger: + | "click" + | "mouse-enter" + | "mouse-leave" + | "after-delay" + ``` + + Types of triggers defined: + + * `click` triggers when the user uses the mouse to click on a shape + * `mouse-enter` triggers when the user moves the mouse inside the shape (even if no mouse button is pressed) + * `mouse-leave` triggers when the user moves the mouse outside the shape. + * `after-delay` triggers after the `delay` time has passed even if no interaction from the user happens. + members: {} diff --git a/mcp-server/src/ApiDocs.ts b/mcp-server/src/ApiDocs.ts new file mode 100644 index 0000000..1df4208 --- /dev/null +++ b/mcp-server/src/ApiDocs.ts @@ -0,0 +1,121 @@ +import * as yaml from "js-yaml"; +import * as fs from "fs"; +import * as path from "path"; + +/** + * Represents a single API type with its documentation. + */ +export class ApiType { + private readonly name: string; + private readonly overview: string; + private readonly members: Record>; + private cachedFullText: string | null = null; + + constructor(name: string, overview: string, members: Record>) { + this.name = name; + this.overview = overview; + this.members = members; + } + + /** + * Returns the original name of this API type. + */ + getName(): string { + return this.name; + } + + /** + * Creates a single markdown text document from all parts of this API type. + * + * The full text is cached within the object for performance. + */ + getFullText(): string { + if (this.cachedFullText === null) { + let text = this.overview; + + for (const [memberType, memberEntries] of Object.entries(this.members)) { + text += `\n\n## ${memberType}\n`; + + for (const [memberName, memberDescription] of Object.entries(memberEntries)) { + text += `\n### ${memberName}\n\n${memberDescription}`; + } + } + + this.cachedFullText = text; + } + + return this.cachedFullText; + } + + /** + * Returns the description of the member with the given name. + * + * The member type doesn't matter for the search, as member names are unique + * across all member types within a single API type. + */ + getMember(memberName: string): string | null { + for (const memberEntries of Object.values(this.members)) { + if (memberName in memberEntries) { + return memberEntries[memberName]; + } + } + return null; + } +} + +/** + * Loads and manages API documentation from YAML files. + * + * This class provides case-insensitive access to API type documentation + * loaded from the data/api_types.yml file. + */ +export class ApiDocs { + private readonly apiTypes: Map = new Map(); + + /** + * Creates a new ApiDocs instance and loads the API types from the YAML file. + */ + constructor() { + this.loadApiTypes(); + } + + /** + * Loads API types from the data/api_types.yml file. + */ + private loadApiTypes(): void { + const yamlPath = path.join(process.cwd(), "data", "api_types.yml"); + const yamlContent = fs.readFileSync(yamlPath, "utf8"); + const data = yaml.load(yamlContent) as Record; + + for (const [typeName, typeData] of Object.entries(data)) { + const overview = typeData.overview || ""; + const members = typeData.members || {}; + + const apiType = new ApiType(typeName, overview, members); + + // store with lower-case key for case-insensitive retrieval + this.apiTypes.set(typeName.toLowerCase(), apiType); + } + } + + /** + * Retrieves an API type by name (case-insensitive). + */ + getType(typeName: string): ApiType | null { + return this.apiTypes.get(typeName.toLowerCase()) || null; + } + + /** + * Returns all available type names. + */ + getTypeNames(): string[] { + return Array.from(this.apiTypes.keys()); + } + + /** + * Returns the number of loaded API types. + */ + getTypeCount(): number { + return this.apiTypes.size; + } +}