diff --git a/.github/scripts/create-doc-md.js b/.github/scripts/create-doc-md.js index d8c2755..e2d2d20 100644 --- a/.github/scripts/create-doc-md.js +++ b/.github/scripts/create-doc-md.js @@ -1,7 +1,13 @@ import * as fs from 'fs'; -import typedocJson from '../../docs/api/api-doc.json' assert { type: 'json' }; +import typedocJson from '../../docs/api/api-doc.json' with { type: 'json' }; const singleTab = ' '; +const tabsNumber = { + 0: '', + 1: singleTab, + 2: singleTab + singleTab, + 3: singleTab + singleTab + singleTab, +}; function generateMarkdownFromTypedoc(data) { let markdown = `--- @@ -43,7 +49,7 @@ function generateMarkdownForItem(item) { markdown += `### ${item.name}\n\n`; if (item.comment && item.comment.summary) { - markdown += getComments(item.comment.summary); + markdown += getComments(item.comment.summary, 0); } if (item?.children) { @@ -62,6 +68,10 @@ function generateMarkdownForItem(item) { } else if (itemGroup.type.types) { markdown += getMarkdownCodeBlock(getNameWithType(itemGroup), 2); } + + if (itemGroup.comment && itemGroup.comment.summary) { + markdown += getComments(itemGroup.comment.summary, 2); + } } else if ( itemGroup.type?.type === 'reference' || itemGroup.type?.type === 'intrinsic' || @@ -69,19 +79,28 @@ function generateMarkdownForItem(item) { itemGroup.type?.type === 'array' ) { markdown += `* **${itemGroup.name}**\n\n`; + markdown += getMarkdownCodeBlock(getNameWithType(itemGroup), 2); if (itemGroup.comment && itemGroup.comment.summary) { markdown += - singleTab + singleTab + getComments(itemGroup.comment.summary); + getComments(itemGroup.comment.summary, 2); } - markdown += getMarkdownCodeBlock(getNameWithType(itemGroup), 2); + if (itemGroup.comment && itemGroup.comment.blockTags) { + markdown += singleTab + singleTab + `**Example:**\n\n`; + markdown += getBlockTag(itemGroup.comment.blockTags, 2); + } } else if (itemGroup.type?.type === 'reflection') { if (itemGroup.type?.declaration?.children) { markdown += `* **${itemGroup.name}**\n\n`; if (itemGroup.comment && itemGroup.comment.summary) { - markdown += getComments(itemGroup.comment.summary); + markdown += getComments(itemGroup.comment.summary, 2); + } + + if (itemGroup.comment && itemGroup.comment.blockTags) { + markdown += singleTab + singleTab + `**Example:**\n\n`; + markdown += getBlockTag(itemGroup.comment.blockTags, 2); } itemGroup.type.declaration.groups.forEach((itemSubGroup) => { @@ -93,16 +112,6 @@ function generateMarkdownForItem(item) { markdown += singleTab + `* **${itemSubGroupChildren.name}**\n\n`; - if ( - itemSubGroupChildren.comment && - itemSubGroupChildren.comment.summary - ) { - markdown += - singleTab + - singleTab + - getComments(itemSubGroupChildren.comment.summary); - } - if ( itemSubGroupChildren.type.declaration && itemSubGroupChildren.type.declaration.signatures @@ -115,12 +124,30 @@ function generateMarkdownForItem(item) { 2 ); + if ( + itemSubGroupChildren.comment && + itemSubGroupChildren.comment.summary + ) { + markdown += + getComments(itemSubGroupChildren.comment.summary, 2); + } + + if (itemSubGroupChildren.comment && itemSubGroupChildren.comment.blockTags) { + markdown += singleTab + singleTab + `**Example:**\n\n`; + markdown += getBlockTag(itemSubGroupChildren.comment.blockTags, 2); + } + // Properties with a method as type markdown += singleTab + singleTab + `**Parameters:**\n\n`; + if (itemSubGroupChildren.type.declaration.signatures[0] && itemSubGroupChildren.type.declaration.signatures[0].parameters && itemSubGroupChildren.type.declaration.signatures[0].parameters.some(param => param.comment)) { + itemSubGroupChildren.type.declaration.signatures[0].parameters.forEach(param => { + markdown += getParamsComments(param.name, param.comment.summary, 2); + }); + } markdown += getMarkdownCodeBlock( getParameters( itemSubGroupChildren.type.declaration.signatures, - 2 + 0 ), 2 ); @@ -137,11 +164,6 @@ function generateMarkdownForItem(item) { }); } else { markdown += `* **${itemGroup.name}**\n\n`; - - if (itemGroup.comment && itemGroup.comment.summary) { - markdown += singleTab + getComments(itemGroup.comment.summary); - } - markdown += getMarkdownCodeBlock( getSignatureParams( itemGroup.name, @@ -150,9 +172,23 @@ function generateMarkdownForItem(item) { 1 ); + if (itemGroup.comment && itemGroup.comment.summary) { + markdown += getComments(itemGroup.comment.summary, 1); + } + + if (itemGroup.comment && itemGroup.comment.blockTags) { + markdown += singleTab + singleTab + `**Example:**\n\n`; + markdown += getBlockTag(itemGroup.comment.blockTags, 2); + } + // Properties with a method as type if (itemGroup.type?.declaration?.signatures[0].parameters) { markdown += singleTab + `**Parameters:**\n\n`; + if (itemGroup.type?.declaration?.signatures[0] && itemGroup.type?.declaration?.signatures[0].parameters && itemGroup.type?.declaration?.signatures[0].parameters.some(param => param.comment)) { + itemGroup.type?.declaration?.signatures[0].parameters.forEach(param => { + markdown += getParamsComments(param.name, param.comment.summary, 2); + }); + } markdown += getMarkdownCodeBlock( getParameters(itemGroup.type?.declaration?.signatures, 0), 1 @@ -168,22 +204,32 @@ function generateMarkdownForItem(item) { } } else if (itemGroup.signatures) { markdown += `* **${itemGroup.name}**\n\n`; + markdown += getMarkdownCodeBlock( + getNameWithType(itemGroup.signatures[0]), + 1 + ); if ( itemGroup.signatures[0].comment && itemGroup.signatures[0].comment.summary ) { markdown += - singleTab + getComments(itemGroup.signatures[0].comment.summary); + singleTab + getComments(itemGroup.signatures[0].comment.summary, 0); + } + + if (itemGroup.signatures[0].comment && itemGroup.signatures[0].comment.blockTags) { + markdown += singleTab + singleTab + `**Example:**\n\n`; + markdown += getBlockTag(itemGroup.signatures[0].comment.blockTags, 2); } - markdown += getMarkdownCodeBlock( - getNameWithType(itemGroup.signatures[0]), - 1 - ); // Methods if (itemGroup.signatures[0].parameters) { markdown += singleTab + `**Parameters:**\n\n`; + if (itemGroup.signatures[0] && itemGroup.signatures[0].parameters && itemGroup.signatures[0].parameters.some(param => param.comment)) { + itemGroup.signatures[0].parameters.forEach(param => { + markdown += getParamsComments(param.name, param.comment.summary, 2); + }); + } markdown += getMarkdownCodeBlock( getParameters(itemGroup.signatures, 0), 1 @@ -261,11 +307,6 @@ function getType(data) { } function getParameters(signatures, tabs) { - const tabsNumber = { - 0: '', - 1: singleTab, - 2: singleTab + singleTab, - }; let paramsParts = ''; signatures.forEach((signature) => { if (signature.parameters) { @@ -300,9 +341,24 @@ function getParameters(signatures, tabs) { return paramsParts; } -function getComments(comentSummary) { +function getBlockTag(commentBlockTag, tabs) { + const block = commentBlockTag.map((block) => { + return block.content.map(content => content.text).join(' \n'); + }).join(' '); + const formatContent = block.split('\n') + .map((item) => tabsNumber[tabs] + item) + .join('\n'); + return `${formatContent}\n\n`; +} + +function getComments(comentSummary, tabs) { const comment = comentSummary.map((summary) => summary.text).join(' '); - return `${comment}\n\n`; + return `${tabsNumber[tabs]}${comment}\n\n`; +} + +function getParamsComments(paramName, comentSummary, tabs) { + const comment = comentSummary.map((summary) => summary.text).join(' '); + return `${tabsNumber[tabs]}\`${paramName}\` ${comment}\n\n`; } function getSignatureParams(paramName, signature) { @@ -320,12 +376,6 @@ function getSignatureParams(paramName, signature) { } function getMarkdownCodeBlock(content, tabs) { - const tabsNumber = { - 0: '', - 1: singleTab, - 2: singleTab + singleTab, - 3: singleTab + singleTab + singleTab, - }; const formatContent = content .split('\n') .map((item) => tabsNumber[tabs] + item) diff --git a/libs/plugin-types/index.d.ts b/libs/plugin-types/index.d.ts index f796922..d9295a2 100644 --- a/libs/plugin-types/index.d.ts +++ b/libs/plugin-types/index.d.ts @@ -1,16 +1,40 @@ +/** + * PenpotFile represents a file in the Penpot application. + * It includes properties for the file's identifier, name, and revision number. + */ export interface PenpotFile { id: string; name: string; revn: number; } +/** + * PenpotPage 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. + */ export interface PenpotPage { + /** + * The `id` property is a unique identifier for the page. + */ id: string; + /** + * The `name` property is the name of the page. + */ name: string; + /** + * Retrieves a shape by its unique identifier. + * @param id The unique identifier of the shape. + */ getShapeById(id: string): PenpotShape | null; + /** + * Finds all shapes on the page. + */ findShapes(): PenpotShape[]; } +/** + * TODO PenpotGradient + */ export type PenpotGradient = { type: 'linear' | 'radial'; startX: number; @@ -21,6 +45,9 @@ export type PenpotGradient = { stops: Array<{ color: string; opacity?: number; offset: number }>; }; +/** + * TODO PenpotImageData + */ export type PenpotImageData = { name?: string; width: number; @@ -30,6 +57,9 @@ export type PenpotImageData = { keepApectRatio?: boolean; }; +/** + * TODO PenpotFill + */ export interface PenpotFill { fillColor?: string; fillOpacity?: number; @@ -39,6 +69,10 @@ export interface PenpotFill { fillImage?: PenpotImageData; } +/** + * TODO PenpotStrokeCap + */ + export type PenpotStrokeCap = | 'round' | 'square' @@ -48,6 +82,9 @@ export type PenpotStrokeCap = | 'circle-marker' | 'diamond-marker'; +/** + * TODO PenpotStroke + */ export interface PenpotStroke { strokeColor?: string; strokeColorRefFile?: string; @@ -61,6 +98,9 @@ export interface PenpotStroke { strokeColorGradient?: PenpotGradient; } +/** + * TODO PenpotColor + */ export interface PenpotColor { id?: string; name?: string; @@ -73,6 +113,9 @@ export interface PenpotColor { image?: PenpotImageData; } +/** + * TODO PenpotShadow + */ export interface PenpotShadow { id?: string; style?: 'drop-shadow' | 'inner-shadow'; @@ -84,6 +127,9 @@ export interface PenpotShadow { color?: PenpotColor; } +/** + * TODO PenpotBlur + */ export interface PenpotBlur { id?: string; type?: 'layer-blur'; @@ -91,6 +137,9 @@ export interface PenpotBlur { hidden?: boolean; } +/** + * TODO PenpotFrameGuideColumnParams + */ export interface PenpotFrameGuideColumnParams { color: { color: string; opacity: number }; type?: 'stretch' | 'left' | 'center' | 'right'; @@ -100,45 +149,92 @@ export interface PenpotFrameGuideColumnParams { gutter?: number; } +/** + * TODO PenpotFrameGuideSquareParams + */ export interface PenpotFrameGuideSquareParams { color: { color: string; opacity: number }; size?: number; } +/** + * TODO PenpotFrameGuideColumn + */ export interface PenpotFrameGuideColumn { type: 'column'; display: boolean; params: PenpotFrameGuideColumnParams; } +/** + * TODO PenpotFrameGuideRow + */ export interface PenpotFrameGuideRow { type: 'row'; display: boolean; params: PenpotFrameGuideColumnParams; } +/** + * TODO PenpotFrameGuideSquare + */ export interface PenpotFrameGuideSquare { type: 'column'; display: boolean; params: PenpotFrameGuideSquareParams; } +/** + * TODO PenpotFrameGuide + */ export type PenpotFrameGuide = | PenpotFrameGuideColumn | PenpotFrameGuideRow | PenpotFrameGuideSquare; +/** + * TODO PenpotExport + */ export interface PenpotExport {} +/** + * TODO PenpotTrackType + */ export type PenpotTrackType = 'flex' | 'fixed' | 'percent' | 'auto'; +/** + * TODO PenpotTrack + */ export interface PenpotTrack { type: PenpotTrackType; value: number | null; } +/** + * PenpotCommonLayout 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. + */ export interface PenpotCommonLayout { + /** + * 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. + */ alignItems?: 'start' | 'end' | 'center' | 'stretch'; + /** + * 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. + */ alignContent?: | 'start' | 'end' @@ -147,7 +243,26 @@ export interface PenpotCommonLayout { | 'space-around' | 'space-evenly' | '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. + */ justifyItems?: 'start' | 'end' | 'center' | 'stretch'; + /** + * 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. + */ justifyContent?: | 'start' | 'center' @@ -157,40 +272,148 @@ export interface PenpotCommonLayout { | 'space-evenly' | 'stretch'; + /** + * The `rowGap` property specifies the gap between rows in the layout. + */ rowGap: number; + /** + * The `columnGap` property specifies the gap between columns in the layout. + */ columnGap: number; + /** + * The `verticalPadding` property specifies the vertical padding inside the container. + */ verticalPadding: number; + /** + * The `horizontalPadding` property specifies the horizontal padding inside the container. + */ horizontalPadding: number; + /** + * The `topPadding` property specifies the padding at the top of the container. + */ topPadding: number; + /** + * The `rightPadding` property specifies the padding at the right of the container. + */ rightPadding: number; + /** + * The `bottomPadding` property specifies the padding at the bottom of the container. + */ bottomPadding: number; + /** + * The `leftPadding` property specifies the padding at the left of the container. + */ leftPadding: number; + /** + * 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. + */ horizontalSizing: 'fit-content' | 'fill' | 'auto'; + /** + * 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. + */ verticalSizing: 'fit-content' | 'fill' | 'auto'; + /** + * The `remove` method removes the layout. + */ remove(): void; } +/** + * PenpotGridLayout 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. + */ export interface PenpotGridLayout extends PenpotCommonLayout { + /** + * The `dir` property specifies the primary direction of the grid layout. + * It can be either 'column' or 'row'. + */ dir: 'column' | 'row'; + /** + * The `rows` property represents the collection of rows in the grid. + * This property is read-only. + */ readonly rows: PenpotTrack[]; + /** + * The `columns` property represents the collection of columns in the grid. + * This property is read-only. + */ readonly columns: PenpotTrack[]; + /** + * Adds a new row to the grid. + * @param type The type of the row to add. + * @param value The value associated with the row type (optional). + */ addRow(type: PenpotTrackType, value?: number): void; + /** + * Adds a new row to the grid at the specified index. + * @param index The index at which to add the row. + * @param type The type of the row to add. + * @param value The value associated with the row type (optional). + */ addRowAtIndex(index: number, type: PenpotTrackType, value?: number): void; + /** + * Adds a new column to the grid. + * @param type The type of the column to add. + * @param value The value associated with the column type (optional). + */ addColumn(type: PenpotTrackType, value?: number): void; + /** + * Adds a new column to the grid at the specified index. + * @param index The index at which to add the column. + * @param type The type of the column to add. + * @param value The value associated with the column type. + */ addColumnAtIndex(index: number, type: PenpotTrackType, value: number): void; + /** + * Removes a row from the grid at the specified index. + * @param index The index of the row to remove. + */ removeRow(index: number): void; + /** + * Removes a column from the grid at the specified index. + * @param index The index of the column to remove. + */ removeColumn(index: number): void; + /** + * Sets the properties of a column at the specified index. + * @param index The index of the column to set. + * @param type The type of the column. + * @param value The value associated with the column type (optional). + */ setColumn(index: number, type: PenpotTrackType, value?: number): void; + /** + * Sets the properties of a row at the specified index. + * @param index The index of the row to set. + * @param type The type of the row. + * @param value The value associated with the row type (optional). + */ setRow(index: number, type: PenpotTrackType, value?: number): void; + /** + * Appends a child element to the grid at the specified row and column. + * @param child The child element to append. + * @param row The row index where the child will be placed. + * @param column The column index where the child will be placed. + */ appendChild(child: PenpotShape, row: number, column: number): void; } +/** + * TODO PenpotFlexLayout + */ export interface PenpotFlexLayout extends PenpotCommonLayout { dir: 'row' | 'row-reverse' | 'column' | 'column-reverse'; wrap?: 'wrap' | 'nowrap'; @@ -198,6 +421,9 @@ export interface PenpotFlexLayout extends PenpotCommonLayout { appendChild(child: PenpotShape): void; } +/** + * TODO PenpotPathCommand + */ interface PenpotPathCommand { command: | 'M' @@ -236,6 +462,9 @@ interface PenpotPathCommand { }; } +/** + * TODO PenpotShapeBase + */ export interface PenpotShapeBase { id: string; name: string; @@ -328,6 +557,9 @@ export interface PenpotShapeBase { remove(): void; } +/** + * TODO PenpotFrame + */ export interface PenpotFrame extends PenpotShapeBase { readonly type: 'frame'; readonly grid?: PenpotGridLayout; @@ -347,6 +579,9 @@ export interface PenpotFrame extends PenpotShapeBase { addGridLayout(): PenpotGridLayout; } +/** + * TODO PenpotGroup + */ export interface PenpotGroup extends PenpotShapeBase { readonly type: 'group'; @@ -358,12 +593,18 @@ export interface PenpotGroup extends PenpotShapeBase { removeMask(): void; } +/** + * TODO PenpotBoolType + */ export type PenpotBoolType = | 'union' | 'difference' | 'exclude' | 'intersection'; +/** + * TODO PenpotBool + */ export interface PenpotBool extends PenpotShapeBase { readonly type: 'bool'; @@ -377,10 +618,16 @@ export interface PenpotBool extends PenpotShapeBase { insertChild(index: number, child: PenpotShape): void; } +/** + * TODO PenpotRectangle + */ export interface PenpotRectangle extends PenpotShapeBase { readonly type: 'rect'; } +/** + * TODO PenpotPath + */ export interface PenpotPath extends PenpotShapeBase { readonly type: 'path'; @@ -388,6 +635,10 @@ export interface PenpotPath extends PenpotShapeBase { content: Array; } +/** + * PenpotText 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. + */ export interface PenpotText extends PenpotShapeBase { readonly type: 'text'; characters: string; @@ -404,24 +655,44 @@ export interface PenpotText extends PenpotShapeBase { textTransform: string | 'mixed'; } +/** + * TODO PepotFrame + */ export interface PepotFrame extends PenpotShapeBase { readonly type: 'frame'; readonly children: PenpotShape[]; } +/** + * TODO PenpotEllipse + */ export interface PenpotEllipse extends PenpotShapeBase { type: 'circle'; } +/** + * TODO PenpotSvgRaw + */ export interface PenpotSvgRaw extends PenpotShapeBase { type: 'svg-raw'; } +/** + * TODO PenpotImage + */ export interface PenpotImage extends PenpotShapeBase { type: 'image'; } +/** + * PenpotPoint represents a point in 2D space, typically with x and y coordinates. + */ export type PenpotPoint = { x: number; y: number }; + +/** + * PenpotBounds represents the boundaries of a rectangular area, + * defined by the coordinates of the top-left corner and the dimensions of the rectangle. + */ export type PenpotBounds = { x: number; y: number; @@ -429,12 +700,20 @@ export type PenpotBounds = { height: number; }; +/** + * PenpotViewport represents the viewport in the Penpot application. + * It includes the center point, zoom level, and the bounds of the viewport. + */ export interface PenpotViewport { center: PenpotPoint; zoom: number; readonly bounds: PenpotBounds; } +/** + * PenpotShape 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. + */ export type PenpotShape = | PenpotFrame | PenpotGroup @@ -446,16 +725,41 @@ export type PenpotShape = | PenpotSvgRaw | PenpotImage; +/** + * TODO EventsMap + */ export interface EventsMap { + /** + * The `pagechange` event is triggered when the active page in the project is changed. + */ pagechange: PenpotPage; + /** + * The `filechange` event is triggered when there are changes in the current file. + */ filechange: PenpotFile; + /** + * The `selectionchange` event is triggered when the selection of elements changes. + * This event passes a list of identifiers of the selected elements. + */ selectionchange: string[]; + /** + * The `themechange` event is triggered when the application theme is changed. + */ themechange: PenpotTheme; + /** + * The `finish` event is triggered when some operation is finished. + */ finish: string; } +/** + * TODO PenpotTheme + */ export type PenpotTheme = 'light' | 'dark'; +/** + * TODO PenpotLibraryElement + */ export interface PenpotLibraryElement { readonly id: string; readonly libraryId: string; @@ -463,16 +767,38 @@ export interface PenpotLibraryElement { path: string; } +/** + * TODO PenpotLibraryColor + */ export interface PenpotLibraryColor extends PenpotLibraryElement { color?: string; opacity?: number; gradient?: PenpotGradient; image?: PenpotImageData; + /** + * TODO asFill + * + * @example + * ```js + * asFill code + * ``` + */ asFill(): PenpotFill; + /** + * TODO asStroke + * + * @example + * ```js + * asStroke code + * ``` + */ asStroke(): PenpotStroke; } +/** + * TODO PenpotLibraryTypography + */ export interface PenpotLibraryTypography extends PenpotLibraryElement { fontId: string; fontFamily: string; @@ -484,56 +810,294 @@ export interface PenpotLibraryTypography extends PenpotLibraryElement { letterSpacing: string; textTransform: string; + /** + * TODO applyToText + * + * @param shape TODO + * + * @example + * ```js + * applyToText code + * ``` + */ applyToText(shape: PenpotShape): void; + /** + * TODO applyToTextRange + * + * @param shape TODO + * + * @example + * ```js + * applyToTextRange code + * ``` + */ applyToTextRange(shape: PenpotShape): void; } +/** + * TODO PenpotLibraryComponent + */ export interface PenpotLibraryComponent extends PenpotLibraryElement { + /** + * TODO instance + * + * @example + * ```js + * instance code + * ``` + */ instance(): PenpotShape; } +/** + * TODO PenpotLibrary + */ export type PenpotLibrary = { colors: PenpotLibraryColor[]; typographies: PenpotLibraryTypography[]; components: PenpotLibraryComponent[]; + /** + * TODO createColor + * + * @example + * ```js + * createColor code + * ``` + */ createColor(): PenpotLibraryColor; + /** + * TODO createTypography + * + * @example + * ```js + * createTypography code + * ``` + */ createTypography(): PenpotLibraryTypography; + /** + * TODO createComponent + * + * @example + * ```js + * createComponent code + * ``` + */ createComponent(shapes: PenpotShape[]): PenpotLibraryComponent; }; +/** + * TODO PenpotLibraryContext + */ export type PenpotLibraryContext = { + /** + * TODO local + * + * @example + * ```js + * local code + * ``` + */ local: PenpotLibrary; + /** + * TODO connected + * + * @example + * ```js + * connected code + * ``` + */ connected: PenpotLibrary[]; }; +/** + * TODO PenpotUser + */ export interface PenpotUser { + /** + * TODO id + * + * @example + * ```js + * id code + * ``` + */ readonly id: string; + /** + * TODO name + * + * @example + * ```js + * name code + * ``` + */ readonly name?: string; + /** + * TODO avatarUrl + * + * @example + * ```js + * avatarUrl code + * ``` + */ readonly avatarUrl?: string; + /** + * TODO color + * + * @example + * ```js + * color code + * ``` + */ readonly color: string; + /** + * TODO sessionId + * + * @example + * ```js + * sessionId code + * ``` + */ readonly sessionId?: string; } +/** + * TODO PenpotActiveUser + */ export interface PenpotActiveUser extends PenpotUser { + /** + * TODO position + * + * @example + * ```js + * position code + * ``` + */ readonly position?: { x: number; y: number }; + /** + * TODO zoom + * + * @example + * ```js + * zoom code + * ``` + */ readonly zoom?: number; } +/** + * TODO PenpotContext + */ export interface PenpotContext { + /** + * TODO root + * + * @example + * ```js + * context.root; + * ``` + */ readonly root: PenpotShape; + /** + * TODO currentPage + * + * @example + * ```js + * context.currentPage; + * ``` + */ readonly currentPage: PenpotPage; + /** + * TODO viewport + * + * @example + * ```js + * context.viewport; + * ``` + */ readonly viewport: PenpotViewport; + /** + * TODO library + * + * @example + * ```js + * context.library; + * ``` + */ readonly library: PenpotLibraryContext; + /** + * TODO currentUser + * + * @example + * ```js + * context.currentUser; + * ``` + */ readonly currentUser: PenpotUser; + /** + * TODO activeUsers + * + * @example + * ```js + * context.activeUsers; + * ``` + */ readonly activeUsers: PenpotActiveUser; + /** + * TODO selection + * + * @example + * ```js + * penpot.selection; + * ``` + */ selection: PenpotShape[]; + /** + * Use this method to get file data + * + * @example + * ```js + * penpot.getFile(); + * ``` + */ getFile(): PenpotFile | null; + /** + * Use this method to get page data + * + * @example + * ```js + * penpot.getPage(); + * ``` + */ getPage(): PenpotPage | null; + /** + * Use this method to get the selected elements on penpot. You'll get and array of ids. + * + * @example + * ```js + * penpot.getSelected(); + * ``` + */ getSelected(): string[]; + /** + * Use this method to get the selected elements on penpot. You'll get the data from each shape. + * + * @example + * ```js + * penpot.getSelectedShapes(); + * ``` + */ getSelectedShapes(): PenpotShape[]; + /** + * Use this method to get the selected theme on penpot. This is necessary to take care of the dark and light mode of your plugin UI. + * + * @example + * ```js + * penpot.getTheme(); + * ``` + */ getTheme(): PenpotTheme; uploadMediaUrl(name: string, url: string): Promise; @@ -541,18 +1105,99 @@ export interface PenpotContext { group(shapes: PenpotShape[]): PenpotGroup; ungroup(group: PenpotGroup, ...other: PenpotGroup[]): void; + /** + * Use this method to create the shape of a rectangle. + * + * @example + * ```js + * penpot.createRectangle(); + * ``` + */ createRectangle(): PenpotRectangle; + /** + * Use this method to create a frame. This is the first step before anything else, the container. + * Then you can add a gridlayout, flexlayout or add a shape inside the frame. + * + * @example + * ```js + * penpot.createFrame(); + * ``` + */ createFrame(): PenpotFrame; + /** + * Use this method to create the shape of a ellipse. + * + * @example + * ```js + * penpot.createEllipse(); + * ``` + */ createEllipse(): PenpotEllipse; + /** + * Use this method to create a path. + * + * @example + * ```js + * penpot.createPath(); + * ``` + */ createPath(): PenpotPath; + /** + * TODO createboolean + * + * @example + * ```js + * penpot.createBoolean(); + * ``` + */ createBoolean(boolType: PenpotBoolType, shapes: PenpotShape[]): PenpotBool; + /** + * TODO createShapeFromSvg + * + * @example + * ```js + * penpot.createShapeFromSvg(); + * ``` + */ createShapeFromSvg(svgString: string): PenpotGroup; + /** + * TODO createText + * + * @example + * ```js + * const board = penpot.createFrame(); + * let text; + * text = penpot.createText(); + * text.growType = 'auto-height'; + * text.fontFamily = 'Work Sans'; + * text.fontSize = '12'; + * board.appendChild(text); + * ``` + */ createText(text: string): PenpotText; - + /** + * TODO addListener + * + * @param type todo explanation + * @param callback todo explanation + * + * @example + * ```js + * penpot.addListener(); + * ``` + */ addListener( type: T, callback: (event: EventsMap[T]) => void ): symbol; + /** + * TODO removeListener + * + * @example + * ```js + * penpot.removeListener(); + * ``` + */ removeListener(listenerId: symbol): void; } @@ -564,8 +1209,17 @@ export interface Penpot extends Omit { ui: { /** - * Description of open + * 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. * + * @param name title of the plugin, it'll be displayed on the top of the modal + * @param url of the plugin + * @param options height and width of the modal. + * + * @example + * ```js + * penpot.ui.open('Plugin name', 'url', {width: 150, height: 300}); + * ``` */ open: ( name: string, @@ -573,13 +1227,25 @@ export interface Penpot options?: { width: number; height: number } ) => void; /** - * Description of sendMessage + * TODO description of sendMessage * + * @param message content usually is an object + * + * @example + * ```js + * this.sendMessage({ type: 'example-type', content: 'data we want to share' }); + * ``` */ sendMessage: (message: unknown) => void; /** - * Description of onMessage + * This is usually used in the `plugin.ts` file in order to handle the data sent by our plugin * + * @param message content usually is an object + * + * @example + * ```js + * penpot.ui.onMessage((message) => {if(message.type === 'example-type' { ...do something })}); + * ``` */ onMessage: (callback: (message: T) => void) => void; }; @@ -590,11 +1256,35 @@ export interface Penpot isFrame(shape: PenpotShape): shape is PenpotFrame; }; }; + /** + * Closes the plugin. When this method is called the UI will be closed. + * + * @example + * ```js + * penpot.closePlugin(); + * ``` + */ closePlugin: () => void; + /** + * TODO description of 'on' + * + * @example + * ```js + * penpot.on('pagechange', () => {...do something}). + * ``` + */ on: ( type: T, callback: (event: EventsMap[T]) => void ) => void; + /** + * TODO description of 'off' + * + * @example + * ```js + * penpot.off('pagechange', () => {...do something}). + * ``` + */ off: ( type: T, callback: (event: EventsMap[T]) => void