github/penpot
1
0
Fork 0
mirror of https://github.com/penpot/penpot.git synced 2026-09-11 14:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

📚 Improve plugin api docs (#10142)

Browse Source
This commit is contained in:
Alonso Torres 2026-06-11 15:51:03 +02:00 committed by GitHub
parent 9670140448
commit 6cc1c1596f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 120 additions and 87 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

207
plugins/libs/plugin-types/index.d.ts vendored
View File

@ -13,7 +13,7 @@ export interface Penpot extends Omit<
* *
* @param name title of the plugin, it'll be displayed on the top of the modal * @param name title of the plugin, it'll be displayed on the top of the modal
* @param url of the plugin * @param url of the plugin
* @param options height and width of the modal. * @param options width and height of the modal and, optionally, a `hidden` flag to open the plugin without showing the modal.
* *
* @example * @example
* ```js * ```js
@ -23,19 +23,25 @@ export interface Penpot extends Omit<
open: ( open: (
name: string, name: string,
url: string, url: string,
options?: { width: number; height: number; hidden: boolean }, options?: { width: number; height: number; hidden?: boolean },
) => void; ) => void;
/**
* The current size of the modal, or `null` if the plugin UI is not open.
* @example
* ```js
* const size = penpot.ui.size;
* console.log(size);
* ```
*/
size: { size: {
/** /**
* Returns the size of the modal. * The width of the modal.
* @example
* ```js
* const size = penpot.ui.size;
* console.log(size);
* ```
*/ */
width: number; width: number;
/**
* The height of the modal.
*/
height: number; height: number;
} | null; } | null;
@ -58,19 +64,19 @@ export interface Penpot extends Omit<
* *
* @example * @example
* ```js * ```js
* this.sendMessage({ type: 'example-type', content: 'data we want to share' }); * penpot.ui.sendMessage({ type: 'example-type', content: 'data we want to share' });
* ``` * ```
*/ */
sendMessage: (message: unknown, throwOnError?: boolean) => void; sendMessage: (message: unknown, throwOnError?: boolean) => void;
/** /**
* This is usually used in the `plugin.ts` file in order to handle the data sent by our plugin * This is usually used in the `plugin.ts` file in order to handle the messages sent from the plugin UI.
* *
@param callback - A function that will be called whenever a message is received. * @param callback - A function that will be called whenever a message is received.
* The function receives a single argument, `message`, which is of type `T`. * The function receives a single argument, `message`, which is of type `T`.
* *
* @example * @example
* ```js * ```js
* penpot.ui.onMessage((message) => {if(message.type === 'example-type' { ...do something })}); * penpot.ui.onMessage((message) => { if (message.type === 'example-type') { ...do something } });
* ``` * ```
*/ */
onMessage: <T>(callback: (message: T) => void) => void; onMessage: <T>(callback: (message: T) => void) => void;
@ -102,7 +108,9 @@ export interface Penpot extends Omit<
* ``` * ```
* - selectionchange: event emitted when the current selection changes. The callback will receive the list of ids for the new selection * - 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`) * - 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. * - filechange: event emitted when a different file is opened. The callback will receive the new file.
* - contentsave: event emitted after the file content is saved in the backend. The callback receives no arguments.
* - finish: event emitted when the current file is closed. The callback will receive the id of the closed file.
* *
* @param type The event type to listen for. * @param type The event type to listen for.
* @param callback The callback function to execute when the event is triggered. * @param callback The callback function to execute when the event is triggered.
@ -111,7 +119,7 @@ export interface Penpot extends Omit<
* *
* @example * @example
* ```js * ```js
* penpot.on('pagechange', () => {...do something}). * penpot.on('pagechange', () => {...do something});
* ``` * ```
*/ */
on<T extends keyof EventsMap>( on<T extends keyof EventsMap>(
@ -218,7 +226,7 @@ export interface Board extends ShapeBase {
clipContent: boolean; clipContent: boolean;
/** /**
* WHen true the board will be displayed in the view mode * When true the board will be displayed in the view mode
*/ */
showInViewMode: boolean; showInViewMode: boolean;
@ -245,7 +253,7 @@ export interface Board extends ShapeBase {
/** /**
* The horizontal sizing behavior of the board. * The horizontal sizing behavior of the board.
* It can be one of the following values: * It can be one of the following values:
* - 'fix': The containers has its own intrinsic fixed size. * - 'fix': The container has its own intrinsic fixed size.
* - 'auto': The container fits the content. * - 'auto': The container fits the content.
*/ */
horizontalSizing?: 'auto' | 'fix'; horizontalSizing?: 'auto' | 'fix';
@ -253,7 +261,7 @@ export interface Board extends ShapeBase {
/** /**
* The vertical sizing behavior of the board. * The vertical sizing behavior of the board.
* It can be one of the following values: * It can be one of the following values:
* - 'fix': The containers has its own intrinsic fixed size. * - 'fix': The container has its own intrinsic fixed size.
* - 'auto': The container fits the content. * - 'auto': The container fits the content.
*/ */
verticalSizing?: 'auto' | 'fix'; verticalSizing?: 'auto' | 'fix';
@ -333,16 +341,19 @@ export interface Board extends ShapeBase {
* grid.columnGap = 10; * grid.columnGap = 10;
* grid.verticalPadding = 5; * grid.verticalPadding = 5;
* grid.horizontalPadding = 5; * grid.horizontalPadding = 5;
* ```
*/ */
addGridLayout(): GridLayout; addGridLayout(): GridLayout;
/** /**
* Creates a new ruler guide. * Creates a new ruler guide attached to the board.
* @param orientation `horizontal` or `vertical`
* @param value the position of the guide relative to the board
*/ */
addRulerGuide(orientation: RulerGuideOrientation, value: number): RulerGuide; addRulerGuide(orientation: RulerGuideOrientation, value: number): RulerGuide;
/** /**
* Removes the `guide` from the current page. * Removes the `guide` from the board.
*/ */
removeRulerGuide(guide: RulerGuide): void; removeRulerGuide(guide: RulerGuide): void;
@ -369,7 +380,7 @@ export interface VariantContainer extends Board {
*/ */
export interface Boolean extends ShapeBase { export interface Boolean extends ShapeBase {
/** /**
* The type of the shape, which is always 'bool' for boolean operation shapes. * The type of the shape, which is always 'boolean' for boolean operation shapes.
*/ */
readonly type: 'boolean'; readonly type: 'boolean';
@ -745,7 +756,7 @@ export interface CommonLayout {
/** /**
* The `horizontalSizing` property specifies the horizontal sizing behavior of the container. * The `horizontalSizing` property specifies the horizontal sizing behavior of the container.
* It can be one of the following values: * It can be one of the following values:
* - 'fix': The containers has its own intrinsic fixed size. * - 'fix': The container has its own intrinsic fixed size.
* - 'fill': The container fills the available space. Only can be set if it's inside another layout. * - 'fill': The container fills the available space. Only can be set if it's inside another layout.
* - 'auto': The container fits the content. * - 'auto': The container fits the content.
*/ */
@ -753,7 +764,7 @@ export interface CommonLayout {
/** /**
* The `verticalSizing` property specifies the vertical sizing behavior of the container. * The `verticalSizing` property specifies the vertical sizing behavior of the container.
* It can be one of the following values: * It can be one of the following values:
* - 'fix': The containers has its own intrinsic fixed size. * - 'fix': The container has its own intrinsic fixed size.
* - 'fill': The container fills the available space. Only can be set if it's inside another layout. * - 'fill': The container fills the available space. Only can be set if it's inside another layout.
* - 'auto': The container fits the content. * - 'auto': The container fits the content.
*/ */
@ -979,9 +990,9 @@ export interface Context {
* @example * @example
* ```js * ```js
* const penpotShapesArray = penpot.selection; * const penpotShapesArray = penpot.selection;
* // We need to make sure that something is selected, and if the selected shape is a group, * // We need to make sure that something is selected, and that the selected shape is a group
* if (selected.length && penpot.utils.types.isGroup(penpotShapesArray[0])) { * if (penpotShapesArray.length && penpot.utils.types.isGroup(penpotShapesArray[0])) {
* penpot.group(penpotShapesArray[0]); * penpot.ungroup(penpotShapesArray[0]);
* } * }
* ``` * ```
*/ */
@ -1180,8 +1191,8 @@ export interface Context {
/** /**
* Generates markup for the given shapes. Requires `content:read` permission * Generates markup for the given shapes. Requires `content:read` permission
* @param shapes * @param shapes the shapes to generate the markup for
* @param options * @param options `type` of the markup to generate. Defaults to `'html'`.
* *
* @example * @example
* ```js * ```js
@ -1193,8 +1204,9 @@ export interface Context {
/** /**
* Generates styles for the given shapes. Requires `content:read` permission * Generates styles for the given shapes. Requires `content:read` permission
* @param shapes * @param shapes the shapes to generate the styles for
* @param options * @param options `type` of the styles to generate (defaults to `'css'`), `withPrelude` to include the style prelude
* (defaults to `false`) and `includeChildren` to also generate the styles for the shape children (defaults to `true`).
* *
* @example * @example
* ```js * ```js
@ -1489,6 +1501,9 @@ export interface Dissolve {
* This interface extends `ShapeBase` and includes properties specific to ellipses. * This interface extends `ShapeBase` and includes properties specific to ellipses.
*/ */
export interface Ellipse extends ShapeBase { export interface Ellipse extends ShapeBase {
/**
* The type of the shape, which is always 'ellipse' for ellipse shapes.
*/
type: 'ellipse'; type: 'ellipse';
/** /**
@ -1514,7 +1529,8 @@ export interface EventsMap {
*/ */
pagechange: Page; pagechange: Page;
/** /**
* The `filechange` event is triggered when there are changes in the current file. * The `filechange` event is triggered when a different file is opened.
* The callback will receive the new file.
*/ */
filechange: File; filechange: File;
/** /**
@ -1527,7 +1543,8 @@ export interface EventsMap {
*/ */
themechange: Theme; themechange: Theme;
/** /**
* The `finish` event is triggered when some operation is finished. * The `finish` event is triggered when the current file is closed.
* The callback will receive the id of the closed file.
*/ */
finish: string; finish: string;
@ -1538,7 +1555,7 @@ export interface EventsMap {
shapechange: Shape; shapechange: Shape;
/** /**
* The `contentsave` event will trigger when the content file changes. * The `contentsave` event will trigger after the file content is saved in the backend.
*/ */
contentsave: void; contentsave: void;
} }
@ -1591,7 +1608,7 @@ export interface File extends PluginData {
*/ */
pages: Page[]; pages: Page[];
/* /**
* Export the current file to an archive. * Export the current file to an archive.
* @param `exportType` indicates the type of file to generate. * @param `exportType` indicates the type of file to generate.
* - `'penpot'` will create a *.penpot file with a binary representation of the file * - `'penpot'` will create a *.penpot file with a binary representation of the file
@ -1601,7 +1618,6 @@ export interface File extends PluginData {
* - `'all'` will include the libraries as external files that will be exported in a single bundle * - `'all'` will include the libraries as external files that will be exported in a single bundle
* - `'merge'` will add all the assets into the main file and only one file will be imported * - `'merge'` will add all the assets into the main file and only one file will be imported
* - `'detach'` will unlink all the external assets and no libraries will be imported * - `'detach'` will unlink all the external assets and no libraries will be imported
* @param `progressCallback` for `zip` export can be pass this callback so a progress report is sent.
* *
* @example * @example
* ```js * ```js
@ -1652,7 +1668,7 @@ export interface FileVersion {
*/ */
readonly isAutosave: boolean; readonly isAutosave: boolean;
/* /**
* Restores the current version and replaces the content of the active file * Restores the current version and replaces the content of the active file
* for the contents of this version. * for the contents of this version.
* Requires the `content:write` permission. * Requires the `content:write` permission.
@ -1706,13 +1722,13 @@ export interface Fill {
} }
/** /**
* This subcontext allows the API o change certain defaults * This subcontext allows the API to change certain defaults
*/ */
export interface Flags { export interface Flags {
/** /**
* If `true` the .children property will be always sorted in the z-index ordering. * If `true` the .children property will always be sorted in the z-index ordering.
* Also, appendChild method will be append the children in the top-most position. * Also, the appendChild method will append the children in the top-most position.
* The insertchild method is changed acordingly to respect this ordering. * The insertChild method is changed accordingly to respect this ordering.
* Defaults to false * Defaults to false
*/ */
naturalChildOrdering: boolean; naturalChildOrdering: boolean;
@ -2172,7 +2188,7 @@ export interface Group extends ShapeBase {
export type Guide = GuideColumn | GuideRow | GuideSquare; export type Guide = GuideColumn | GuideRow | GuideSquare;
/** /**
* Represents a goard guide for columns in Penpot. * Represents a board guide for columns in Penpot.
* This interface includes properties for defining the type, visibility, and parameters of column guides within a board. * This interface includes properties for defining the type, visibility, and parameters of column guides within a board.
*/ */
export interface GuideColumn { export interface GuideColumn {
@ -2307,6 +2323,9 @@ export interface HistoryContext {
* This interface extends `ShapeBase` and includes properties specific to image shapes. * This interface extends `ShapeBase` and includes properties specific to image shapes.
*/ */
export interface Image extends ShapeBase { export interface Image extends ShapeBase {
/**
* The type of the shape, which is always 'image' for image shapes.
*/
type: 'image'; type: 'image';
/** /**
@ -2347,7 +2366,7 @@ export type ImageData = {
keepAspectRatio?: boolean; keepAspectRatio?: boolean;
/** /**
* Returns the imaged data as a byte array. * Returns the image data as a byte array.
*/ */
data(): Promise<Uint8Array>; data(): Promise<Uint8Array>;
}; };
@ -2680,7 +2699,7 @@ export interface LibraryComponent extends LibraryElement {
isVariant(): this is LibraryVariantComponent; isVariant(): this is LibraryVariantComponent;
/** /**
* Creates a new Variant from this standard Component. It creates a VariantContainer, transform this Component into a VariantComponent, duplicates it, and creates a * Creates a new Variant from this standard Component. It creates a VariantContainer, transforms this Component into a VariantComponent, duplicates it, and creates a
* set of properties based on the component name and path. * set of properties based on the component name and path.
* Similar to doing it with the contextual menu or the shortcut on the Penpot interface * Similar to doing it with the contextual menu or the shortcut on the Penpot interface
*/ */
@ -2698,12 +2717,12 @@ export interface LibraryVariantComponent extends LibraryComponent {
readonly variants: Variants | null; readonly variants: Variants | null;
/** /**
* A list of the variants props of this VariantComponent. Each property have a key and a value * A list of the variant props of this VariantComponent. Each property has a key and a value
*/ */
readonly variantProps: { [property: string]: string }; readonly variantProps: { [property: string]: string };
/** /**
* If this VariantComponent has an invalid name, that does't follow the structure [property]=[value], [property]=[value] * If this VariantComponent has an invalid name, that doesn't follow the structure [property]=[value], [property]=[value]
* this field stores that invalid name * this field stores that invalid name
*/ */
variantError: string; variantError: string;
@ -2715,8 +2734,9 @@ export interface LibraryVariantComponent extends LibraryComponent {
/** /**
* Sets the value of the variant property on the indicated position * Sets the value of the variant property on the indicated position
* @param pos The position of the property to update
* @param value The new value of the property
*/ */
setVariantProperty(pos: number, value: string): void; setVariantProperty(pos: number, value: string): void;
} }
@ -2915,7 +2935,7 @@ export interface LibraryTypography extends LibraryElement {
* Proxy for the local storage. Only elements owned by the plugin * Proxy for the local storage. Only elements owned by the plugin
* can be stored and accessed. * can be stored and accessed.
* Warning: other plugins won't be able to access this information but * Warning: other plugins won't be able to access this information but
* the user could potentialy access the data through the browser information. * the user could potentially access the data through the browser information.
*/ */
export interface LocalStorage { export interface LocalStorage {
/** /**
@ -2926,7 +2946,7 @@ export interface LocalStorage {
/** /**
* Set the data given the key. If the value already existed it * Set the data given the key. If the value already existed it
* will be overriden. The value will be stored in a string representation. * will be overridden. The value will be stored in a string representation.
* Requires the `allow:localstorage` permission. * Requires the `allow:localstorage` permission.
*/ */
setItem(key: string, value: unknown): void; setItem(key: string, value: unknown): void;
@ -3056,7 +3076,7 @@ export interface Page extends PluginData {
name: string; name: string;
/** /**
* The ruler guides attached to the board * The ruler guides attached to the page
*/ */
readonly rulerGuides: RulerGuide[]; readonly rulerGuides: RulerGuide[];
@ -3079,7 +3099,7 @@ export interface Page extends PluginData {
/** /**
* Finds all shapes on the page. * Finds all shapes on the page.
* Optionaly it gets a criteria object to search for specific criteria * Optionally it gets a criteria object to search for specific criteria
* @param criteria * @param criteria
* @example * @example
* ```js * ```js
@ -3126,6 +3146,9 @@ export interface Page extends PluginData {
/** /**
* Creates a new ruler guide. * Creates a new ruler guide.
* @param orientation `horizontal` or `vertical`
* @param value the position of the guide in absolute coordinates
* @param board if provided, the guide will be attached to the board
*/ */
addRulerGuide( addRulerGuide(
orientation: RulerGuideOrientation, orientation: RulerGuideOrientation,
@ -3139,8 +3162,7 @@ export interface Page extends PluginData {
removeRulerGuide(guide: RulerGuide): void; removeRulerGuide(guide: RulerGuide): void;
/** /**
* Creates a new comment thread in the `position`. Optionaly adds * Creates a new comment thread in the `position`.
* it into the `board`.
* Returns the thread created. * Returns the thread created.
* Requires the `comment:write` permission. * Requires the `comment:write` permission.
*/ */
@ -3183,18 +3205,18 @@ export interface Path extends ShapeBase {
toD(): string; toD(): string;
/** /**
* The content of the boolean shape, defined as the path string. * The content of the path shape, defined as the path string.
* @deprecated Use either `d` or `commands`. * @deprecated Use either `d` or `commands`.
*/ */
content: string; content: string;
/** /**
* The content of the boolean shape, defined as the path string. * The content of the path shape, defined as the path string.
*/ */
d: string; d: string;
/** /**
* The content of the boolean shape, defined as an array of path commands. * The content of the path shape, defined as an array of path commands.
*/ */
commands: Array<PathCommand>; commands: Array<PathCommand>;
@ -3434,7 +3456,7 @@ export interface Push {
readonly duration: number; readonly duration: number;
/** /**
* Function that the dissolve effect will follow for the interpolation. * Function that the push effect will follow for the interpolation.
* Defaults to `linear` * Defaults to `linear`
*/ */
readonly easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out'; readonly easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
@ -3467,8 +3489,8 @@ export interface RulerGuide {
readonly orientation: RulerGuideOrientation; readonly orientation: RulerGuideOrientation;
/** /**
* `position` is the position in the axis in absolute positioning. If this is a board * `position` is the position in the axis in absolute coordinates. If this is a board
* guide will return the positioning relative to the board. * guide it will return the position relative to the board.
*/ */
position: number; position: number;
@ -3479,7 +3501,7 @@ export interface RulerGuide {
} }
/** /**
* * The possible orientations for a ruler guide: 'horizontal' or 'vertical'.
*/ */
export type RulerGuideOrientation = 'horizontal' | 'vertical'; export type RulerGuideOrientation = 'horizontal' | 'vertical';
@ -3595,12 +3617,12 @@ export interface ShapeBase extends PluginData {
readonly height: number; readonly height: number;
/** /**
* @return Returns the bounding box surrounding the current shape * The bounding box surrounding the current shape
*/ */
readonly bounds: Bounds; readonly bounds: Bounds;
/** /**
* @return Returns the geometric center of the shape * The geometric center of the shape
*/ */
readonly center: Point; readonly center: Point;
@ -3731,7 +3753,7 @@ export interface ShapeBase extends PluginData {
flipY: boolean; flipY: boolean;
/** /**
* @return Returns the rotation in degrees of the shape with respect to it's center. * The rotation in degrees of the shape with respect to its center.
*/ */
rotation: number; rotation: number;
@ -3832,13 +3854,16 @@ export interface ShapeBase extends PluginData {
detach(): void; detach(): void;
/** /**
* TODO * Swaps the component instance for another component, keeping the overrides
* when possible. Similar to the "swap component" action on the Penpot interface.
* The current shape must be a component copy instance.
* @param component The new component to replace the current one
*/ */
swapComponent(component: LibraryComponent): void; swapComponent(component: LibraryComponent): void;
/** /**
* Switch a VariantComponent copy to the nearest one that has the specified property value * Switch a VariantComponent copy to the nearest one that has the specified property value
* @param pos The position of the poroperty to update * @param pos The position of the property to update
* @param value The new value of the property * @param value The new value of the property
*/ */
switchVariant(pos: number, value: string): void; switchVariant(pos: number, value: string): void;
@ -3873,7 +3898,7 @@ export interface ShapeBase extends PluginData {
/** /**
* Rotates the shape in relation with the given center. * Rotates the shape in relation with the given center.
* @param angle Angle in degrees to rotate. * @param angle Angle in degrees to rotate.
* @param center Center of the transform rotation. If not send will use the geometri center of the shapes. * @param center Center of the transform rotation. If not sent it will use the geometric center of the shape.
* *
* @example * @example
* ```js * ```js
@ -3952,7 +3977,7 @@ export interface ShapeBase extends PluginData {
* and the value set to the attributes will depend on which sets are active * and the value set to the attributes will depend on which sets are active
* (and will change if different sets or themes are activated later). * (and will change if different sets or themes are activated later).
*/ */
applyToken(token: Token, properties: TokenProperty[] | undefined): void; applyToken(token: Token, properties?: TokenProperty[]): void;
/** /**
* Creates a clone of the shape. * Creates a clone of the shape.
@ -3996,7 +4021,7 @@ export interface Slide {
readonly offsetEffect?: boolean; readonly offsetEffect?: boolean;
/** /**
* Function that the dissolve effect will follow for the interpolation. * Function that the slide effect will follow for the interpolation.
* Defaults to `linear`. * Defaults to `linear`.
*/ */
readonly easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out'; readonly easing?: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
@ -4068,6 +4093,9 @@ export type StrokeCap =
* This interface extends `ShapeBase` and includes properties specific to raw SVG shapes. * This interface extends `ShapeBase` and includes properties specific to raw SVG shapes.
*/ */
export interface SvgRaw extends ShapeBase { export interface SvgRaw extends ShapeBase {
/**
* The type of the shape, which is always 'svg-raw' for raw SVG shapes.
*/
type: 'svg-raw'; type: 'svg-raw';
} }
@ -4154,7 +4182,7 @@ export interface Text extends ShapeBase {
align: 'left' | 'center' | 'right' | 'justify' | 'mixed' | null; align: 'left' | 'center' | 'right' | 'justify' | 'mixed' | null;
/** /**
* The vertical alignment of the text shape. It can be a specific alignment or 'mixed' if multiple alignments are used. * The vertical alignment of the text shape.
*/ */
verticalAlign: 'top' | 'center' | 'bottom' | null; verticalAlign: 'top' | 'center' | 'bottom' | null;
@ -4402,14 +4430,14 @@ export interface TokenBase {
* and the value set to the attributes will depend on which sets are active * and the value set to the attributes will depend on which sets are active
* (and will change if different sets or themes are activated later). * (and will change if different sets or themes are activated later).
*/ */
applyToShapes(shapes: Shape[], properties: TokenProperty[] | undefined): void; applyToShapes(shapes: Shape[], properties?: TokenProperty[]): void;
/** /**
* Applies this token to the currently selected shapes. * Applies this token to the currently selected shapes.
* *
* Parameters and warnings are the same as above. * Parameters and warnings are the same as above.
*/ */
applyToSelected(properties: TokenProperty[] | undefined): void; applyToSelected(properties?: TokenProperty[]): void;
} }
/** /**
@ -4437,7 +4465,7 @@ export interface TokenBorderRadius extends TokenBase {
readonly resolvedValue: number | undefined; readonly resolvedValue: number | undefined;
} }
/* /**
* The value of a TokenShadow in its composite form. * The value of a TokenShadow in its composite form.
*/ */
export interface TokenShadowValue { export interface TokenShadowValue {
@ -4472,7 +4500,7 @@ export interface TokenShadowValue {
blur: number; blur: number;
} }
/* /**
* The value of a TokenShadow in its composite of strings form. * The value of a TokenShadow in its composite of strings form.
*/ */
export interface TokenShadowValueString { export interface TokenShadowValueString {
@ -4557,8 +4585,10 @@ export interface TokenColor extends TokenBase {
value: string; value: string;
/** /**
* The value as defined in the token itself. * The value calculated by finding all tokens with the same name in active sets
* It's a rgb color or a reference. * and resolving the references.
*
* It's a rgb color, or undefined if no value has been found in active sets.
*/ */
readonly resolvedValue: string | undefined; readonly resolvedValue: string | undefined;
} }
@ -4896,7 +4926,7 @@ export interface TokenTextDecoration extends TokenBase {
readonly resolvedValue: string | undefined; readonly resolvedValue: string | undefined;
} }
/* /**
* The value of a TokenTypography in its composite form. * The value of a TokenTypography in its composite form.
*/ */
export interface TokenTypographyValue { export interface TokenTypographyValue {
@ -4936,7 +4966,7 @@ export interface TokenTypographyValue {
textDecoration: string; textDecoration: string;
} }
/* /**
* The value of a TokenTypography in its composite of strings form. * The value of a TokenTypography in its composite of strings form.
*/ */
export interface TokenTypographyValueString { export interface TokenTypographyValueString {
@ -4962,9 +4992,9 @@ export interface TokenTypographyValueString {
fontWeight: string; fontWeight: string;
/** /**
* The line height, as a number. Note that there not exists an individual * The line height, as a number. Note that there is no individual line-height
* token type line height, only part of a Typography token. If you need to * token type; it only exists as part of a Typography token. If you need to
* put here a reference, use a NumberToken. * put a reference here, use a Number token.
*/ */
lineHeight: string; lineHeight: string;
@ -5055,8 +5085,8 @@ export interface TokenCatalog {
readonly themes: TokenTheme[]; readonly themes: TokenTheme[];
/** /**
* The list of sets in this catalog, in the order defined * The list of sets in this catalog, in the order defined
* by the user. The order is important because then same token name * by the user. The order is important because when the same token name
* exists in several active sets, the latter has precedence. * exists in several active sets, the latter has precedence.
*/ */
readonly sets: TokenSet[]; readonly sets: TokenSet[];
@ -5140,7 +5170,7 @@ export interface TokenSet {
/** /**
* Creates a new Token and adds it to the set. * Creates a new Token and adds it to the set.
* @param type Thetype of token. * @param type The type of the token.
* @param name The name of the token (required). It may contain * @param name The name of the token (required). It may contain
* a group path, separated by `.`. * a group path, separated by `.`.
* @param value The value of the token (required), in the string form. * @param value The value of the token (required), in the string form.
@ -5175,9 +5205,9 @@ export interface TokenSet {
* sets that are _not_ in this theme, because they may have been * sets that are _not_ in this theme, because they may have been
* activated by other themes. * activated by other themes.
* *
* Themes may be gruped. At any time only one of the themes in a group * Themes may be grouped. At any time only one of the themes in a group
* may be active. But there may be active themes in other groups. This * may be active. But there may be active themes in other groups. This
* allows to define multiple "axis" for theming (e.g. color scheme, * allows defining multiple "axis" for theming (e.g. color scheme,
* density or brand). * density or brand).
* *
* When a TokenSet is activated or deactivated directly, all themes * When a TokenSet is activated or deactivated directly, all themes
@ -5192,13 +5222,13 @@ export interface TokenTheme {
readonly id: string; readonly id: string;
/** /**
* Optional identifier that may exists if the theme was imported from an * Optional identifier that may exist if the theme was imported from an
* external tool that uses ids in the json file. * external tool that uses ids in the json file.
*/ */
readonly externalId: string | undefined; readonly externalId: string | undefined;
/** /**
* The group name of the theme. Can be empt string. * The group name of the theme. Can be an empty string.
*/ */
group: string; group: string;
@ -5466,7 +5496,10 @@ export interface User {
} }
/** /**
* TODO * Represents a Variant in Penpot: the grouping of all the VariantComponents that
* belong to the same VariantContainer, together with their shared properties.
* This interface provides attributes and actions that affect the Variant as a
* whole (not a single VariantComponent).
*/ */
export interface Variants { export interface Variants {
/** /**
@ -5486,7 +5519,7 @@ export interface Variants {
properties: string[]; properties: string[];
/** /**
* A list of all the values of a property along all the variantComponents of this Variant * A list of all the values of a property across all the VariantComponents of this Variant
* @param property The name of the property * @param property The name of the property
*/ */
currentValues(property: string): string[]; currentValues(property: string): string[];