Penpot/penpot-plugins
0
Fork 0
mirror of https://github.com/penpot/penpot-plugins.git synced 2025-01-21 22:22:45 -05:00
Code Issues Activity

chore: update api doc

Browse source
This commit is contained in:
Marina López 2024-06-26 14:12:15 +02:00
parent a7fc0d87c0
commit 00a1565209
1 changed files with 223 additions and 86 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

309
libs/plugin-types/index.d.ts vendored
View file

@ -884,102 +884,144 @@ interface PenpotPathCommand {
} }
/** /**
* TODO PenpotLayoutChildProperties * Properties for defining the layout of a child element in Penpot.
*/ */
export interface PenpotLayoutChildProperties { export interface PenpotLayoutChildProperties {
/** /**
* TODO absolute * 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.
*/ */
absolute: boolean; absolute: boolean;
/** /**
* TODO zIndex * Defines the stack order of the child element
* Elements with a higher zIndex will be displayed in front of those with a lower zIndex.
*/ */
zIndex: number; zIndex: number;
/** /**
* TODO horizontalSizing * 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.
*/ */
horizontalSizing: 'auto' | 'fill' | 'fix'; horizontalSizing: 'auto' | 'fill' | 'fix';
/** /**
* TODO verticalSizing * 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.
*/ */
verticalSizing: 'auto' | 'fill' | 'fix'; verticalSizing: 'auto' | 'fill' | 'fix';
/** /**
* TODO alignSelf * 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.
*/ */
alignSelf: 'auto' | 'start' | 'center' | 'end' | 'stretch'; alignSelf: 'auto' | 'start' | 'center' | 'end' | 'stretch';
/** /**
* TODO horizontalMargin * Sets the horizontal margin of the child element.
* This is the space on the left and right sides of the element.
*/ */
horizontalMargin: number; horizontalMargin: number;
/** /**
* TODO verticalMargin * Sets the vertical margin of the child element.
* This is the space on the top and bottom sides of the element.
*/ */
verticalMargin: number; verticalMargin: number;
/** /**
* TODO topMargin * Sets the top margin of the child element.
* This is the space above the element.
*/ */
topMargin: number; topMargin: number;
/** /**
* TODO rightMargin * Sets the right margin of the child element.
* This is the space to the right of the element.
*/ */
rightMargin: number; rightMargin: number;
/** /**
* TODO bottomMargin * Sets the bottom margin of the child element.
* This is the space below the element.
*/ */
bottomMargin: number; bottomMargin: number;
/** /**
* TODO leftMargin * Sets the left margin of the child element.
* This is the space to the left of the element.
*/ */
leftMargin: number; leftMargin: number;
/** /**
* TODO maxWidth * Defines the maximum width of the child element.
* If set to null, there is no maximum width constraint.
*/ */
maxWidth: number | null; maxWidth: number | null;
/** /**
* TODO maxHeight * Defines the maximum height of the child element.
* If set to null, there is no maximum height constraint.
*/ */
maxHeight: number | null; maxHeight: number | null;
/** /**
* TODO minWidth * Defines the minimum width of the child element.
* If set to null, there is no minimum width constraint.
*/ */
minWidth: number | null; minWidth: number | null;
/** /**
* TODO minHeight * Defines the minimum height of the child element.
* If set to null, there is no minimum height constraint.
*/ */
minHeight: number | null; minHeight: number | null;
} }
/** /**
* TODO PenpotLayoutCellProperties * Properties for defining the layout of a cell in Penpot.
*/ */
export interface PenpotLayoutCellProperties { export interface PenpotLayoutCellProperties {
/** /**
* TODO row * The row index of the cell.
* This value is optional and indicates the starting row of the cell.
*/ */
row?: number; row?: number;
/** /**
* TODO rowSpan * The number of rows the cell should span.
* This value is optional and determines the vertical span of the cell.
*/ */
rowSpan?: number; rowSpan?: number;
/** /**
* TODO column * The column index of the cell.
* This value is optional and indicates the starting column of the cell.
*/ */
column?: number; column?: number;
/** /**
* TODO columnSpan * The number of columns the cell should span.
* This value is optional and determines the horizontal span of the cell.
*/ */
columnSpan?: number; columnSpan?: number;
/** /**
* TODO areaName * The name of the grid area that this cell belongs to.
* This value is optional and can be used to define named grid areas.
*/ */
areaName?: string; areaName?: string;
/** /**
* TODO position * The positioning mode of the cell.
* This value can be 'auto', 'manual', or 'area' and determines how the cell is positioned within the layout.
*/ */
position?: 'auto' | 'manual' | 'area'; position?: 'auto' | 'manual' | 'area';
} }
@ -1335,7 +1377,8 @@ export interface PenpotGroup extends PenpotShapeBase {
insertChild(index: number, child: PenpotShape): void; insertChild(index: number, child: PenpotShape): void;
/** /**
* TODO * Checks if the group is currently a mask.
* A mask defines a clipping path for its child shapes.
*/ */
isMask(): boolean; isMask(): boolean;
@ -1489,32 +1532,34 @@ export interface PenpotTextRange {
textTransform: string | 'mixed'; textTransform: string | 'mixed';
/** /**
* TODO textDecoration * The text decoration applied to the text range. It can be a specific text decoration or 'mixed' if multiple text decorations are used.
*/ */
textDecoration: string | 'mixed'; textDecoration: string | 'mixed';
/** /**
* TODO direction * The text direction for the text range. It can be a specific direction or 'mixed' if multiple directions are used.
*/ */
direction: string | 'mixed'; direction: string | 'mixed';
/** /**
* TODO fills * The fill styles applied to the text range.
*/ */
fills: PenpotFill[]; fills: PenpotFill[];
/** /**
* TODO align * The horizontal alignment of the text range. It can be a specific alignment or 'mixed' if multiple alignments are used.
*/ */
align: string | 'mixed'; align: string | 'mixed';
/** /**
* TODO verticalAlign * The vertical alignment of the text range. It can be a specific alignment or 'mixed' if multiple alignments are used.
*/ */
verticalAlign: string | 'mixed'; verticalAlign: string | 'mixed';
/** /**
* TODO applyTypography * Applies a typography style to the text range.
* This method sets various typography properties for the text range according to the given typography style.
* @param typography - The typography style to apply.
*/ */
applyTypography(typography: PenpotLibraryTypography): void; applyTypography(typography: PenpotLibraryTypography): void;
} }
@ -1587,32 +1632,38 @@ export interface PenpotText extends PenpotShapeBase {
textTransform: string | 'mixed'; textTransform: string | 'mixed';
/** /**
* TODO textDecoration * The text decoration applied to the text shape, or 'mixed' if multiple text decorations are used.
*/ */
textDecoration: string | 'mixed'; textDecoration: string | 'mixed';
/** /**
* TODO direction * The text direction for the text shape, or 'mixed' if multiple directions are used.
*/ */
direction: string | 'mixed'; direction: string | 'mixed';
/** /**
* TODO align * The horizontal alignment of the text shape. It can be a specific alignment or 'mixed' if multiple alignments are used.
*/ */
align: string | 'mixed'; align: string | 'mixed';
/** /**
* TODO verticalAlign * The vertical alignment of the text shape. It can be a specific alignment or 'mixed' if multiple alignments are used.
*/ */
verticalAlign: string | 'mixed'; verticalAlign: string | 'mixed';
/** /**
* TODO getRange * Gets a text range within the text shape.
* Returns a PenpotTextRange object representing the specified text range.
* @param start - The start index of the text range.
* @param end - The end index of the text range.
*/ */
getRange(start: number, end: number): PenpotTextRange; getRange(start: number, end: number): PenpotTextRange;
/** /**
* TODO applyTypography * Applies a typography style to the text shape.
* @param typography - The typography style to apply.
* @remarks
* This method sets various typography properties for the text shape according to the given typography style.
*/ */
applyTypography(typography: PenpotLibraryTypography): void; applyTypography(typography: PenpotLibraryTypography): void;
} }
@ -1873,7 +1924,13 @@ export interface PenpotLibraryTypography extends PenpotLibraryElement {
applyToTextRange(range: PenpotTextRange): void; applyToTextRange(range: PenpotTextRange): void;
/** /**
* TODO setFont * Sets the font and optionally its variant for the typography element.
* @param font - The font to set.
* @param variant - The font variant to set (optional).
* @example
* ```js
* typographyElement.setFont(newFont, newVariant);
* ```
*/ */
setFont(font: PenpotFont, variant?: PenpotFontVariant): void; setFont(font: PenpotFont, variant?: PenpotFontVariant): void;
} }
@ -1899,45 +1956,48 @@ export interface PenpotLibraryComponent extends PenpotLibraryElement {
mainInstance: PenpotShape; mainInstance: PenpotShape;
} }
/**
* Represents a summary of a Penpot library.
* This interface provides properties for summarizing various aspects of a Penpot library.
*/
export interface PenpotLibrarySummary { export interface PenpotLibrarySummary {
/** /**
* TODO id * The unique identifier of the library.
*/ */
readonly id: string; readonly id: string;
/** /**
* TODO name * The name of the library.
*/ */
readonly name: string; readonly name: string;
/** /**
* TODO numColors * The number of colors in the library.
*/ */
readonly numColors: number; readonly numColors: number;
/** /**
* TODO numComponents * The number of components in the library.
*/ */
readonly numComponents: number; readonly numComponents: number;
/** /**
* TODO numTypographies * The number of typographies in the library.
*/ */
readonly numTypographies: number; readonly numTypographies: number;
} }
/** /**
* Represents a library in Penpot, containing colors, typographies, and components. * Represents a library in Penpot, containing colors, typographies, and components.
* This type provides methods to create new color, typography, and component elements within the library.
*/ */
export interface PenpotLibrary extends PenpotPluginData { export interface PenpotLibrary extends PenpotPluginData {
/** /**
* TODO id * The unique identifier of the library.
*/ */
readonly id: string; readonly id: string;
/** /**
* TODO name * The name of the library.
*/ */
readonly name: string; readonly name: string;
@ -2012,102 +2072,146 @@ export type PenpotLibraryContext = {
readonly connected: PenpotLibrary[]; readonly connected: PenpotLibrary[];
/** /**
* TODO: availableLibraries * Retrieves a summary of available libraries that can be connected to.
* Returns a promise that resolves to an array of `PenpotLibrarySummary` objects representing available libraries.
* @example
* ```js
* const availableLibraries = await libraryContext.availableLibraries();
* ```
*/ */
availableLibraries(): Promise<PenpotLibrarySummary[]>; availableLibraries(): Promise<PenpotLibrarySummary[]>;
/** /**
* TODO: linkToFile * TODO: linkToFile
*/ */
/**
* Connects to a specific library identified by its ID.
* Returns a promise that resolves to the `PenpotLibrary` object representing the connected library.
* @param libraryId - The ID of the library to connect to.
* @example
* ```js
* const connectedLibrary = await libraryContext.connectLibrary('library-id');
* ```
*/
connectLibrary(libraryId: string): Promise<PenpotLibrary>; connectLibrary(libraryId: string): Promise<PenpotLibrary>;
}; };
/** /**
* TODO PenpotFontVariant * 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.
*/ */
export interface PenpotFontVariant { export interface PenpotFontVariant {
/** /**
* TODO name * The name of the font variant.
*/ */
name: string; name: string;
/** /**
* TODO fontVariantId * The unique identifier of the font variant.
*/ */
fontVariantId: string; fontVariantId: string;
/** /**
* TODO fontWeight * The font weight of the font variant.
*/ */
fontWeight: string; fontWeight: string;
/** /**
* TODO fontStyle * The font style of the font variant.
*/ */
fontStyle: string; fontStyle: string;
} }
/** /**
* TODO PenpotFont * 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.
*/ */
export interface PenpotFont { export interface PenpotFont {
/** /**
* TODO name * This property holds the human-readable name of the font.
*/ */
name: string; name: string;
/** /**
* TODO fontId * The unique identifier of the font.
*/ */
fontId: string; fontId: string;
/** /**
* TODO fontFamily * The font family of the font.
*/ */
fontFamily: string; fontFamily: string;
/** /**
* TODO fontStyle * The default font style of the font.
*/ */
fontStyle: string; fontStyle: string;
/** /**
* TODO fontVariantId * The default font variant ID of the font.
*/ */
fontVariantId: string; fontVariantId: string;
/** /**
* TODO fontWeight * The default font weight of the font.
*/ */
fontWeight: string; fontWeight: string;
/** /**
* TODO variants * An array of font variants available for the font.
*/ */
variants: PenpotFontVariant[]; variants: PenpotFontVariant[];
/** /**
* TODO applyToText * Applies the font styles to a text shape.
* @param text - The text shape to apply the font styles to.
* @param variant - Optional. The specific font variant to apply. If not provided, applies the default variant.
*/ */
applyToText(text: PenpotText, variant?: PenpotFontVariant): void; applyToText(text: PenpotText, variant?: PenpotFontVariant): void;
/** /**
* TODO applyToRange * Applies the font styles to a text range within a text shape.
* @param range - The text range to apply the font styles to.
* @param variant - Optional. The specific font variant to apply. If not provided, applies the default variant.
*/ */
applyToRange(range: PenpotTextRange, variant?: PenpotFontVariant): void; applyToRange(range: PenpotTextRange, variant?: PenpotFontVariant): void;
} }
/** /**
* TODO PenpotFontsContext * Represents the context for managing fonts in Penpot.
* This interface provides methods to interact with fonts, such as retrieving fonts by ID or name.
*/ */
export interface PenpotFontsContext { export interface PenpotFontsContext {
/** /**
* TODO all * An array containing all available fonts.
*/ */
all: PenpotFont[]; all: PenpotFont[];
/** /**
* TODO findById * Finds a font by its unique identifier.
* Returns the `PenpotFont` object if found, otherwise `null`.
* @param id - The ID of the font to find.
*/ */
findById(id: string): PenpotFont | null; findById(id: string): PenpotFont | null;
/** /**
* TODO findByName * Finds a font by its name.
* Returns the `PenpotFont` object if found, otherwise `null`.
* @param name - The name of the font to find.
*/ */
findByName(name: string): PenpotFont | null; findByName(name: string): PenpotFont | null;
/** /**
* TODO findAllById * Finds all fonts matching a specific ID.
* Returns an array of `PenpotFont` objects matching the provided ID.
* @param id - The ID to match against.
*/ */
findAllById(id: string): PenpotFont[]; findAllById(id: string): PenpotFont[];
/** /**
* TODO findAllByName * Finds all fonts matching a specific name.
* Returns an array of `PenpotFont` objects matching the provided name.
* @param name - The name to match against.
*/ */
findAllByName(name: string): PenpotFont[]; findAllByName(name: string): PenpotFont[];
} }
@ -2222,7 +2326,7 @@ export interface PenpotContext {
*/ */
readonly library: PenpotLibraryContext; readonly library: PenpotLibraryContext;
/** /**
* TODO * The fonts context in the Penpot context, providing methods to manage fonts.
*/ */
readonly fonts: PenpotFontsContext; readonly fonts: PenpotFontsContext;
/** /**
@ -2289,12 +2393,13 @@ export interface PenpotContext {
getSelectedShapes(): PenpotShape[]; getSelectedShapes(): PenpotShape[];
/** /**
* TODO: shapesColors * Retrieves colors applied to the given shapes in Penpot.
* Returns an array of colors and their shape information.
*/ */
shapesColors(shapes: PenpotShape[]): (PenpotColor & PenpotColorShapeInfo)[]; shapesColors(shapes: PenpotShape[]): (PenpotColor & PenpotColorShapeInfo)[];
/** /**
* TODO: replaceColor * Replaces a specified old color with a new color in the given shapes.
*/ */
replaceColor( replaceColor(
shapes: PenpotShape[], shapes: PenpotShape[],
@ -2455,67 +2560,99 @@ export interface PenpotContext {
} }
/** /**
* TODO PenpotContextGeometryUtils * Utility methods for geometric calculations in Penpot.
*/ */
export interface PenpotContextGeometryUtils { export interface PenpotContextGeometryUtils {
/** /**
* TODO center * 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.
* Returns the center point as an object with `x` and `y` coordinates, or null if the array is empty.
* @param shapes - The array of shapes to calculate the center for.
*
*/ */
center(shapes: PenpotShape[]): { x: number; y: number } | null; center(shapes: PenpotShape[]): { x: number; y: number } | null;
} }
/** /**
* TODO PenpotContextTypesUtils * Utility methods for determining the types of Penpot shapes.
*/ */
export interface PenpotContextTypesUtils { export interface PenpotContextTypesUtils {
/** /**
* TODO isFrame * Checks if the given shape is a frame.
* Returns true if the shape is a PenpotFrame, otherwise false.
* @param shape - The shape to check.
*/ */
isFrame(shape: PenpotShape): shape is PenpotFrame; isFrame(shape: PenpotShape): shape is PenpotFrame;
/** /**
* TODO isGroup * Checks if the given shape is a group.
* Returns true if the shape is a PenpotGroup, otherwise false.
* @param shape - The shape to check.
*/ */
isGroup(shape: PenpotShape): shape is PenpotGroup; isGroup(shape: PenpotShape): shape is PenpotGroup;
/** /**
* TODO isMask * Checks if the given shape is a mask.
* Returns true if the shape is a PenpotGroup (acting as a mask), otherwise false.
* @param shape - The shape to check.
*/ */
isMask(shape: PenpotShape): shape is PenpotGroup; isMask(shape: PenpotShape): shape is PenpotGroup;
/** /**
* TODO isBool * Checks if the given shape is a boolean operation.
* Returns true if the shape is a PenpotBool, otherwise false.
* @param shape - The shape to check.
*/ */
isBool(shape: PenpotShape): shape is PenpotBool; isBool(shape: PenpotShape): shape is PenpotBool;
/** /**
* TODO isRectangle * Checks if the given shape is a rectangle.
* Returns true if the shape is a PenpotRectangle, otherwise false.
* @param shape - The shape to check.
*/ */
isRectangle(shape: PenpotShape): shape is PenpotRectangle; isRectangle(shape: PenpotShape): shape is PenpotRectangle;
/** /**
* TODO isPath * Checks if the given shape is a path.
* Returns true if the shape is a PenpotPath, otherwise false.
* @param shape - The shape to check.
*/ */
isPath(shape: PenpotShape): shape is PenpotPath; isPath(shape: PenpotShape): shape is PenpotPath;
/** /**
* TODO isText * Checks if the given shape is a text element.
* Returns true if the shape is a PenpotText, otherwise false.
* @param shape - The shape to check.
*/ */
isText(shape: PenpotShape): shape is PenpotText; isText(shape: PenpotShape): shape is PenpotText;
/** /**
* TODO isEllipse * Checks if the given shape is an ellipse.
* Returns true if the shape is a PenpotEllipse, otherwise false.
* @param shape - The shape to check.
*/ */
isEllipse(shape: PenpotShape): shape is PenpotEllipse; isEllipse(shape: PenpotShape): shape is PenpotEllipse;
/** /**
* TODO isSVG * Checks if the given shape is an SVG.
* Returns true if the shape is a PenpotSvgRaw, otherwise false.
* @param shape - The shape to check.
*/ */
isSVG(shape: PenpotShape): shape is PenpotSvgRaw; isSVG(shape: PenpotShape): shape is PenpotSvgRaw;
} }
/** /**
* TODO PenpotContextUtils * Utility methods for various operations in Penpot.
*/ */
export interface PenpotContextUtils { export interface PenpotContextUtils {
/** /**
* TODO PenpotContextGeometryUtils * Geometry utility methods for Penpot.
* Provides methods for geometric calculations, such as finding the center of a group of shapes.
*/ */
readonly geometry: PenpotContextGeometryUtils; readonly geometry: PenpotContextGeometryUtils;
/** /**
* TODO PenpotContextTypesUtils * Type utility methods for Penpot.
* Provides methods for determining the types of various shapes in Penpot.
*/ */
readonly types: PenpotContextTypesUtils; readonly types: PenpotContextTypesUtils;
} }
@ -2569,7 +2706,7 @@ export interface Penpot
onMessage: <T>(callback: (message: T) => void) => void; onMessage: <T>(callback: (message: T) => void) => void;
}; };
/** /**
* TODO: utils * Provides access to utility functions and context-specific operations.
*/ */
utils: PenpotContextUtils; utils: PenpotContextUtils;
/** /**