diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 14143d6..f80b0d3 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -5,7 +5,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out repository code - uses: actions/checkout@v2 + uses: actions/checkout@v4 - run: npm install typescript - run: npm test - run: npm run prettier:check @@ -14,5 +14,5 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out repository code - uses: actions/checkout@v2 + uses: actions/checkout@v4 - run: ./test-usage.sh diff --git a/plugin-api-standalone.d.ts b/plugin-api-standalone.d.ts index b677b85..25772c8 100644 --- a/plugin-api-standalone.d.ts +++ b/plugin-api-standalone.d.ts @@ -443,7 +443,6 @@ interface PluginAPI { readonly teamLibrary: TeamLibraryAPI /** * This property contains methods to work with annotations. - * */ readonly annotations: AnnotationsAPI /** @@ -451,7 +450,6 @@ interface PluginAPI { * This API is only available in Buzz. * * This property contains methods to work in Buzz. - * */ readonly buzz: BuzzAPI /** @@ -811,29 +809,43 @@ interface PluginAPI { * Triggered when the total time on the timer changes. From the UI, it is only possible to add time to the timer. However, plugin code can both add and remove time from a running timer. */ on(type: ArgFreeEventType, callback: () => void): void + on(type: 'run', callback: (event: RunEvent) => void): void + on(type: 'drop', callback: (event: DropEvent) => boolean): void + on(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void + on(type: 'slidesviewchange', callback: (event: SlidesViewChangeEvent) => void): void + on(type: 'canvasviewchange', callback: (event: CanvasViewChangeEvent) => void): void + on( type: 'textreview', callback: (event: TextReviewEvent) => Promise | TextReviewRange[], ): void + on(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void /** * Same as `figma.on`, but the callback will only be called once, the first time the specified event happens. */ once(type: ArgFreeEventType, callback: () => void): void + once(type: 'run', callback: (event: RunEvent) => void): void + once(type: 'drop', callback: (event: DropEvent) => boolean): void + once(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void + once(type: 'slidesviewchange', callback: (event: SlidesViewChangeEvent) => void): void + once(type: 'canvasviewchange', callback: (event: CanvasViewChangeEvent) => void): void + once( type: 'textreview', callback: (event: TextReviewEvent) => Promise | TextReviewRange[], ): void + once(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void /** * Removes a callback added with `figma.on` or `figma.once`. @@ -856,15 +868,22 @@ interface PluginAPI { * ``` */ off(type: ArgFreeEventType, callback: () => void): void + off(type: 'run', callback: (event: RunEvent) => void): void + off(type: 'drop', callback: (event: DropEvent) => boolean): void + off(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void + off(type: 'slidesviewchange', callback: (event: SlidesViewChangeEvent) => void): void + off(type: 'canvasviewchange', callback: (event: CanvasViewChangeEvent) => void): void + off( type: 'textreview', callback: (event: TextReviewEvent) => Promise | TextReviewRange[], ): void + off(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void /** * This a constant value that some node properties return when they are a mix of multiple values. An example might be font size: a single text node can use multiple different font sizes for different character ranges. For those properties, you should always compare against `figma.mixed`. @@ -1931,7 +1950,6 @@ interface PluginAPI { * ```ts * const grid = figma.getCanvasGrid() * ``` - * */ getCanvasGrid(): Array> /** @@ -1968,7 +1986,6 @@ interface PluginAPI { * @remarks * * If no row index is provided, the row will be added at the end of the grid. - * */ createCanvasRow(rowIndex?: number): SceneNode /** @@ -2814,7 +2831,6 @@ interface ConstantsAPI { * ``` * * @remarks - * */ colors: ColorPalettes } @@ -2914,6 +2930,7 @@ interface CodegenAPI { type: 'generate', callback: (event: CodegenEvent) => Promise | CodegenResult[], ): void + on(type: 'preferenceschange', callback: (event: CodegenPreferencesEvent) => Promise): void /** * Same as {@link CodegenAPI.on | `figma.codegen.on`}, but the callback only gets called the first time. @@ -2922,6 +2939,7 @@ interface CodegenAPI { type: 'generate', callback: (event: CodegenEvent) => Promise | CodegenResult[], ): void + once(type: 'preferenceschange', callback: (event: CodegenPreferencesEvent) => Promise): void /** * Removes a callback added by {@link CodegenAPI.on | `figma.codegen.on`} or {@link CodegenAPI.once | `figma.codegen.once`}. @@ -2930,6 +2948,7 @@ interface CodegenAPI { type: 'generate', callback: (event: CodegenEvent) => Promise | CodegenResult[], ): void + off(type: 'preferenceschange', callback: (event: CodegenPreferencesEvent) => Promise): void /** * Read the current preferences as specified by the user. @@ -3308,6 +3327,7 @@ interface RunParametersEvent { command: string parameters: ParametersType } + interface OpenDevResourcesEvent { command: 'open-dev-resource' parameters?: undefined @@ -3316,7 +3336,9 @@ interface OpenDevResourcesEvent { name: string } } + type RunEvent = RunParametersEvent | OpenDevResourcesEvent + interface SlidesViewChangeEvent { view: 'GRID' | 'SINGLE_SLIDE' } @@ -3334,6 +3356,7 @@ interface CanvasViewChangeEvent { */ view: 'SINGLE_ASSET' | 'GRID' } + interface DropEvent { node: BaseNode | SceneNode x: number @@ -3344,22 +3367,26 @@ interface DropEvent { files: DropFile[] dropMetadata?: any } + interface DropItem { type: string data: string } + interface DropFile { name: string type: string getBytesAsync(): Promise getTextAsync(): Promise } + interface DocumentChangeEvent { /** * An array of {@link DocumentChange} that has happened since the last time the event was fired. */ documentChanges: DocumentChange[] } + interface StyleChangeEvent { /** * An array of {@link StyleChange} that has happened since the last time the event was fired. @@ -3621,6 +3648,7 @@ type NodeChangeProperty = | 'authorName' | 'code' | 'textBackground' + interface NodeChangeEvent { nodeChanges: NodeChange[] } @@ -3652,9 +3680,11 @@ type StyleChangeProperty = | 'paint' | 'effects' | 'layoutGrids' + type TextReviewEvent = { text: string } + type TextReviewRange = { start: number end: number @@ -5276,6 +5306,12 @@ type ConnectorStrokeCap = | 'TRIANGLE_FILLED' | 'DIAMOND_FILLED' | 'CIRCLE_FILLED' + | 'ERD_ZERO_OR_ONE' + | 'ERD_EXACTLY_ONE' + | 'ERD_ZERO_OR_MORE' + | 'ERD_ONE_OR_MORE' + | 'ERD_ONE' + | 'ERD_MANY' /** * @see https://developers.figma.com/docs/plugins/api/node-properties */ @@ -5509,7 +5545,6 @@ interface DevResourcesMixin { * * @param url - The url of the dev resource. * @param name - The name of the dev resource. If not provided, Figma will get the name from the url. - * */ addDevResourceAsync(url: string, name?: string): Promise /** @@ -5518,7 +5553,6 @@ interface DevResourcesMixin { * * @param currentUrl - The current url of the dev resource. * @param newValue - The new name and/or url of the dev resource. - * */ editDevResourceAsync( currentUrl: string, @@ -5597,6 +5631,8 @@ interface SceneNodeMixin extends ExplicitVariableModesMixin { readonly attachedConnectors: ConnectorNode[] /** * All component properties that are attached on this node. A node can only have `componentPropertyReferences` if it is a component sublayer or an instance sublayer. It will be `null` otherwise. The value in the key-value pair refers to the component property name as returned by `componentPropertyDefinitions` on the containing component, component set or main component (for instances). + * + * When setting, may throw the following errors: cannotApplySlotPropertyToNonFrameNode, cannotApplySlotPropertyToFrameWithGrid, or cannotApplySlotPropertyToFrame. */ componentPropertyReferences: | { @@ -6443,6 +6479,8 @@ interface AutoLayoutMixin { * * This property must be set to `"HORIZONTAL"` or `"VERTICAL"` in order for the {@link AutoLayoutMixin.primaryAxisSizingMode}, {@link AutoLayoutMixin.counterAxisSizingMode}, {@link AutoLayoutMixin.layoutWrap}, {@link AutoLayoutMixin.primaryAxisAlignItems}, {@link AutoLayoutMixin.counterAxisAlignItems}, {@link AutoLayoutMixin.counterAxisAlignContent}, {@link AutoLayoutMixin.paddingTop}, {@link AutoLayoutMixin.paddingBottom}, {@link AutoLayoutMixin.paddingLeft}, {@link AutoLayoutMixin.paddingRight}, {@link AutoLayoutMixin.itemSpacing}, {@link AutoLayoutMixin.counterAxisSpacing}, {@link AutoLayoutMixin.itemReverseZIndex}, and {@link AutoLayoutMixin.strokesIncludedInLayout} properties to be applicable. * + * Note: `GRID` is not supported for Slot frames, and setting `GRID` will throw a cannotApplyGridToSlot error. + * * ```ts title="Auto-layout frame with horizontal layout" * const parentFrame = figma.createFrame() * parentFrame.appendChild(figma.createFrame()) @@ -8058,7 +8096,6 @@ interface AnnotationsMixin { * Annotations on the node. * * Learn more about annotations in the [Help Center](https://help.figma.com/hc/en-us/articles/20774752502935) or see the [Annotation type](https://developers.figma.com/docs/plugins/api/Annotation) for usage examples. - * */ annotations: ReadonlyArray } @@ -8381,7 +8418,7 @@ interface ComponentPropertiesMixin { */ readonly componentPropertyDefinitions: ComponentPropertyDefinitions /** - * Adds a new component property to this node and returns the property name with its unique identifier suffixed. This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'` or `'VARIANT'`. + * Adds a new component property to this node and returns the property name with its unique identifier suffixed. This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'`, `'VARIANT'`, or `'SLOT'`. */ addComponentProperty( propertyName: string, @@ -8392,11 +8429,12 @@ interface ComponentPropertiesMixin { /** * Modifies the name, default value, or preferred values of an existing component property on this node and returns the property name with its unique identifier suffixed. * - * This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'`, or `'VARIANT'` with the following restrictions: + * This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'`, `'VARIANT'`, or `'SLOT'` with the following restrictions: * * - `name` is supported for all properties - * - `defaultValue` is supported for `'BOOLEAN'`, `'TEXT'`, and `'INSTANCE_SWAP'` properties, but not for `'VARIANT'` properties - * - `preferredValues` is only supported for `'INSTANCE_SWAP'` properties + * - `defaultValue` is supported for `'BOOLEAN'`, `'TEXT'`, and `'INSTANCE_SWAP'` properties, but not for `'VARIANT'` or `'SLOT'` properties + * - `preferredValues` is only supported for `'INSTANCE_SWAP'` and `'SLOT'` properties + * - `description` is only supported for `'SLOT'` properties */ editComponentProperty( propertyName: string, @@ -8404,10 +8442,11 @@ interface ComponentPropertiesMixin { name?: string defaultValue?: string | boolean | VariableAlias preferredValues?: InstanceSwapPreferredValue[] + description?: string }, ): string /** - * Deletes an existing component property on this node. This function only supports properties with type `'BOOLEAN'`, `'TEXT'`, or `'INSTANCE_SWAP'`. + * Deletes an existing component property on this node. This function only supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'` or `'SLOT'`. */ deleteComponentProperty(propertyName: string): void } @@ -9292,13 +9331,17 @@ interface PageNode focusedSlide?: SlideNode | null /** * - * Note: This API is only available in Figma Slides and Figma Buzz + * Note: This API is only available in Figma Slides, Figma Buzz, and Dev Mode. * - * When in Asset View, the Slide/Asset that is currently focused is accessible via this property. + * For Figma Slides and Figma Buzz: + * When in Asset View, this is the focused slide or asset. + * + * For Dev Mode: + * This is the node currently focused in Dev Mode focus view. This property is read-only in Dev Mode. * * @remarks * - * You can also set this via: + * In Figma Slides and Figma Buzz, you can also set this via: * * ```ts * figma.currentPage.focusedNode = node @@ -9620,7 +9663,7 @@ interface TextPathNode /** * @see https://developers.figma.com/docs/plugins/api/ComponentPropertyType */ -type ComponentPropertyType = 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP' | 'VARIANT' +type ComponentPropertyType = 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP' | 'VARIANT' | 'SLOT' /** * @see https://developers.figma.com/docs/plugins/api/InstanceSwapPreferredValue */ @@ -9633,6 +9676,7 @@ type InstanceSwapPreferredValue = { */ type ComponentPropertyOptions = { preferredValues?: InstanceSwapPreferredValue[] + description?: string } /** * @see https://developers.figma.com/docs/plugins/api/ComponentPropertyDefinitions @@ -9643,6 +9687,7 @@ type ComponentPropertyDefinitions = { defaultValue: string | boolean preferredValues?: InstanceSwapPreferredValue[] variantOptions?: string[] + description?: string readonly boundVariables?: { [field in VariableBindableComponentPropertyField]?: VariableAlias } @@ -9690,6 +9735,10 @@ interface ComponentNode * Creates an instance of this component. By default, the instance will be parented under `figma.currentPage`. */ createInstance(): InstanceNode + /** + * Creates a new slot node within this component. + */ + createSlot(): SlotNode /** * Returns an array of all of the instances of this component in the document. */ @@ -9742,7 +9791,7 @@ interface InstanceNode extends DefaultFrameMixin, VariantMixin { */ swapComponent(componentNode: ComponentNode): void /** - * Sets the component properties and values for this instance. `propertyName` corresponds to the names returned by `componentPropertyDefinitions` and should be suffixed with `'#'` and a unique ID for `'TEXT'`, `'BOOLEAN'`, and `'INSTANCE_SWAP'` properties. In the case of name collision, this function prioritizes updating the `'VARIANT'` type properties. Existing properties that are non-specified in the function will maintain their current value. + * Sets the component properties and values for this instance. `propertyName` corresponds to the names returned by `componentPropertyDefinitions` and should be suffixed with `'#'` and a unique ID for `'TEXT'`, `'BOOLEAN'`, and `'INSTANCE_SWAP'` properties. Does not support `'SLOT'` properties and will throw `cannotSetSlotProperty`. In the case of name collision, this function prioritizes updating the `'VARIANT'` type properties. Existing properties that are non-specified in the function will maintain their current value. */ setProperties(properties: { [propertyName: string]: string | boolean | VariableAlias }): void /** @@ -9787,6 +9836,16 @@ interface InstanceNode extends DefaultFrameMixin, VariantMixin { */ removeOverrides(): void } +interface SlotNode extends DefaultFrameMixin { + /** + * The type of this node, represented by the string literal "SLOT" + */ + readonly type: 'SLOT' + /** + * Resets a given slot node to the original component slot content. + */ + resetSlot(): void +} interface BooleanOperationNode extends DefaultShapeMixin, ChildrenMixin, @@ -10945,6 +11004,7 @@ type SceneNode = | SlideNode | SlideRowNode | SlideGridNode + | SlotNode | InteractiveSlideElementNode /** * @see https://developers.figma.com/docs/plugins/api/node-types @@ -11288,4 +11348,4 @@ interface RadialRepeatModifier extends RepeatModifier { } // prettier-ignore -export { ArgFreeEventType, PluginAPI, VersionHistoryResult, VariablesAPI, LibraryVariableCollection, LibraryVariable, AnnotationsAPI, BuzzAPI, BuzzTextField, BuzzMediaField, BuzzAssetType, TeamLibraryAPI, PaymentStatus, PaymentsAPI, ClientStorageAPI, NotificationOptions, NotifyDequeueReason, NotificationHandler, ShowUIOptions, UIPostMessageOptions, OnMessageProperties, MessageEventHandler, UIAPI, UtilAPI, ColorPalette, ColorPalettes, ConstantsAPI, CodegenEvent, CodegenPreferences, CodegenPreferencesEvent, CodegenResult, CodegenAPI, DevResource, DevResourceWithNodeId, LinkPreviewEvent, PlainTextElement, LinkPreviewResult, AuthEvent, DevResourceOpenEvent, AuthResult, VSCodeAPI, DevResourcesAPI, TimerAPI, ViewportAPI, TextReviewAPI, ParameterValues, SuggestionResults, ParameterInputEvent, ParametersAPI, RunParametersEvent, OpenDevResourcesEvent, RunEvent, SlidesViewChangeEvent, CanvasViewChangeEvent, DropEvent, DropItem, DropFile, DocumentChangeEvent, StyleChangeEvent, StyleChange, BaseDocumentChange, BaseNodeChange, RemovedNode, CreateChange, DeleteChange, PropertyChange, BaseStyleChange, StyleCreateChange, StyleDeleteChange, StylePropertyChange, DocumentChange, NodeChangeProperty, NodeChangeEvent, NodeChange, StyleChangeProperty, TextReviewEvent, TextReviewRange, Transform, Vector, Rect, RGB, RGBA, FontName, TextCase, TextDecoration, TextDecorationStyle, FontStyle, TextDecorationOffset, TextDecorationThickness, TextDecorationColor, OpenTypeFeature, ArcData, DropShadowEffect, InnerShadowEffect, BlurEffectBase, BlurEffectNormal, BlurEffectProgressive, BlurEffect, NoiseEffectBase, NoiseEffectMonotone, NoiseEffectDuotone, NoiseEffectMultitone, NoiseEffect, TextureEffect, GlassEffect, Effect, ConstraintType, Constraints, ColorStop, ImageFilters, SolidPaint, GradientPaint, ImagePaint, VideoPaint, PatternPaint, Paint, Guide, RowsColsLayoutGrid, GridLayoutGrid, LayoutGrid, ExportSettingsConstraints, ExportSettingsImage, ExportSettingsSVGBase, ExportSettingsSVG, ExportSettingsSVGString, ExportSettingsPDF, ExportSettingsREST, ExportSettings, WindingRule, VectorVertex, VectorSegment, VectorRegion, VectorNetwork, VectorPath, VectorPaths, LetterSpacing, LineHeight, LeadingTrim, HyperlinkTarget, TextListOptions, BlendMode, MaskType, Font, TextStyleOverrideType, StyledTextSegment, TextPathStartData, Reaction, VariableDataType, ExpressionFunction, Expression, VariableValueWithExpression, VariableData, ConditionalBlock, DevStatus, Action, SimpleTransition, DirectionalTransition, Transition, Trigger, Navigation, Easing, EasingFunctionBezier, EasingFunctionSpring, OverflowDirection, OverlayPositionType, OverlayBackground, OverlayBackgroundInteraction, PublishStatus, ConnectorEndpointPosition, ConnectorEndpointPositionAndEndpointNodeId, ConnectorEndpointEndpointNodeIdAndMagnet, ConnectorEndpoint, ConnectorStrokeCap, BaseNodeMixin, PluginDataMixin, DevResourcesMixin, DevStatusMixin, SceneNodeMixin, VariableBindableNodeField, VariableBindableTextField, VariableBindablePaintField, VariableBindablePaintStyleField, VariableBindableColorStopField, VariableBindableEffectField, VariableBindableEffectStyleField, VariableBindableLayoutGridField, VariableBindableGridStyleField, VariableBindableComponentPropertyField, VariableBindableComponentPropertyDefinitionField, StickableMixin, ChildrenMixin, ConstraintMixin, DimensionAndPositionMixin, LayoutMixin, AspectRatioLockMixin, BlendMixin, ContainerMixin, DeprecatedBackgroundMixin, StrokeCap, StrokeJoin, HandleMirroring, AutoLayoutMixin, GridTrackSize, GridLayoutMixin, AutoLayoutChildrenMixin, GridChildrenMixin, InferredAutoLayoutResult, DetachedInfo, MinimalStrokesMixin, IndividualStrokesMixin, MinimalFillsMixin, VariableWidthPoint, PresetVariableWidthStrokeProperties, CustomVariableWidthStrokeProperties, VariableWidthStrokeProperties, ComplexStrokeProperties, ScatterBrushProperties, StretchBrushProperties, BrushStrokeProperties, DynamicStrokeProperties, GeometryMixin, ComplexStrokesMixin, CornerMixin, RectangleCornerMixin, ExportMixin, FramePrototypingMixin, VectorLikeMixin, ReactionMixin, DocumentationLink, PublishableMixin, DefaultShapeMixin, BaseFrameMixin, DefaultFrameMixin, OpaqueNodeMixin, MinimalBlendMixin, Annotation, AnnotationProperty, AnnotationPropertyType, AnnotationsMixin, Measurement, MeasurementSide, MeasurementOffset, MeasurementsMixin, VariantMixin, ComponentPropertiesMixin, BaseNonResizableTextMixin, NonResizableTextMixin, NonResizableTextPathMixin, TextSublayerNode, DocumentNode, ExplicitVariableModesMixin, PageNode, FrameNode, GroupNode, TransformGroupNode, SliceNode, RectangleNode, LineNode, EllipseNode, PolygonNode, StarNode, VectorNode, TextNode, TextPathNode, ComponentPropertyType, InstanceSwapPreferredValue, ComponentPropertyOptions, ComponentPropertyDefinitions, ComponentSetNode, ComponentNode, ComponentProperties, InstanceNode, BooleanOperationNode, StickyNode, StampNode, TableNode, TableCellNode, HighlightNode, WashiTapeNode, ShapeWithTextNode, CodeBlockNode, LabelSublayerNode, ConnectorNode, VariableResolvedDataType, VariableAlias, VariableValue, VariableScope, CodeSyntaxPlatform, Variable, VariableCollection, ExtendedVariableCollection, AnnotationCategoryColor, AnnotationCategory, WidgetNode, EmbedData, EmbedNode, LinkUnfurlData, LinkUnfurlNode, MediaData, MediaNode, SectionNode, SlideNode, SlideRowNode, SlideGridNode, InteractiveSlideElementNode, SlideTransition, BaseNode, SceneNode, NodeType, StyleType, InheritedStyleField, StyleConsumers, BaseStyleMixin, PaintStyle, TextStyle, EffectStyle, GridStyle, BaseStyle, Image, Video, BaseUser, User, ActiveUser, FindAllCriteria, TransformModifier, RepeatModifier, LinearRepeatModifier, RadialRepeatModifier } +export { ArgFreeEventType, PluginAPI, VersionHistoryResult, VariablesAPI, LibraryVariableCollection, LibraryVariable, AnnotationsAPI, BuzzAPI, BuzzTextField, BuzzMediaField, BuzzAssetType, TeamLibraryAPI, PaymentStatus, PaymentsAPI, ClientStorageAPI, NotificationOptions, NotifyDequeueReason, NotificationHandler, ShowUIOptions, UIPostMessageOptions, OnMessageProperties, MessageEventHandler, UIAPI, UtilAPI, ColorPalette, ColorPalettes, ConstantsAPI, CodegenEvent, CodegenPreferences, CodegenPreferencesEvent, CodegenResult, CodegenAPI, DevResource, DevResourceWithNodeId, LinkPreviewEvent, PlainTextElement, LinkPreviewResult, AuthEvent, DevResourceOpenEvent, AuthResult, VSCodeAPI, DevResourcesAPI, TimerAPI, ViewportAPI, TextReviewAPI, ParameterValues, SuggestionResults, ParameterInputEvent, ParametersAPI, RunParametersEvent, OpenDevResourcesEvent, RunEvent, SlidesViewChangeEvent, CanvasViewChangeEvent, DropEvent, DropItem, DropFile, DocumentChangeEvent, StyleChangeEvent, StyleChange, BaseDocumentChange, BaseNodeChange, RemovedNode, CreateChange, DeleteChange, PropertyChange, BaseStyleChange, StyleCreateChange, StyleDeleteChange, StylePropertyChange, DocumentChange, NodeChangeProperty, NodeChangeEvent, NodeChange, StyleChangeProperty, TextReviewEvent, TextReviewRange, Transform, Vector, Rect, RGB, RGBA, FontName, TextCase, TextDecoration, TextDecorationStyle, FontStyle, TextDecorationOffset, TextDecorationThickness, TextDecorationColor, OpenTypeFeature, ArcData, DropShadowEffect, InnerShadowEffect, BlurEffectBase, BlurEffectNormal, BlurEffectProgressive, BlurEffect, NoiseEffectBase, NoiseEffectMonotone, NoiseEffectDuotone, NoiseEffectMultitone, NoiseEffect, TextureEffect, GlassEffect, Effect, ConstraintType, Constraints, ColorStop, ImageFilters, SolidPaint, GradientPaint, ImagePaint, VideoPaint, PatternPaint, Paint, Guide, RowsColsLayoutGrid, GridLayoutGrid, LayoutGrid, ExportSettingsConstraints, ExportSettingsImage, ExportSettingsSVGBase, ExportSettingsSVG, ExportSettingsSVGString, ExportSettingsPDF, ExportSettingsREST, ExportSettings, WindingRule, VectorVertex, VectorSegment, VectorRegion, VectorNetwork, VectorPath, VectorPaths, LetterSpacing, LineHeight, LeadingTrim, HyperlinkTarget, TextListOptions, BlendMode, MaskType, Font, TextStyleOverrideType, StyledTextSegment, TextPathStartData, Reaction, VariableDataType, ExpressionFunction, Expression, VariableValueWithExpression, VariableData, ConditionalBlock, DevStatus, Action, SimpleTransition, DirectionalTransition, Transition, Trigger, Navigation, Easing, EasingFunctionBezier, EasingFunctionSpring, OverflowDirection, OverlayPositionType, OverlayBackground, OverlayBackgroundInteraction, PublishStatus, ConnectorEndpointPosition, ConnectorEndpointPositionAndEndpointNodeId, ConnectorEndpointEndpointNodeIdAndMagnet, ConnectorEndpoint, ConnectorStrokeCap, BaseNodeMixin, PluginDataMixin, DevResourcesMixin, DevStatusMixin, SceneNodeMixin, VariableBindableNodeField, VariableBindableTextField, VariableBindablePaintField, VariableBindablePaintStyleField, VariableBindableColorStopField, VariableBindableEffectField, VariableBindableEffectStyleField, VariableBindableLayoutGridField, VariableBindableGridStyleField, VariableBindableComponentPropertyField, VariableBindableComponentPropertyDefinitionField, StickableMixin, ChildrenMixin, ConstraintMixin, DimensionAndPositionMixin, LayoutMixin, AspectRatioLockMixin, BlendMixin, ContainerMixin, DeprecatedBackgroundMixin, StrokeCap, StrokeJoin, HandleMirroring, AutoLayoutMixin, GridTrackSize, GridLayoutMixin, AutoLayoutChildrenMixin, GridChildrenMixin, InferredAutoLayoutResult, DetachedInfo, MinimalStrokesMixin, IndividualStrokesMixin, MinimalFillsMixin, VariableWidthPoint, PresetVariableWidthStrokeProperties, CustomVariableWidthStrokeProperties, VariableWidthStrokeProperties, ComplexStrokeProperties, ScatterBrushProperties, StretchBrushProperties, BrushStrokeProperties, DynamicStrokeProperties, GeometryMixin, ComplexStrokesMixin, CornerMixin, RectangleCornerMixin, ExportMixin, FramePrototypingMixin, VectorLikeMixin, ReactionMixin, DocumentationLink, PublishableMixin, DefaultShapeMixin, BaseFrameMixin, DefaultFrameMixin, OpaqueNodeMixin, MinimalBlendMixin, Annotation, AnnotationProperty, AnnotationPropertyType, AnnotationsMixin, Measurement, MeasurementSide, MeasurementOffset, MeasurementsMixin, VariantMixin, ComponentPropertiesMixin, BaseNonResizableTextMixin, NonResizableTextMixin, NonResizableTextPathMixin, TextSublayerNode, DocumentNode, ExplicitVariableModesMixin, PageNode, FrameNode, GroupNode, TransformGroupNode, SliceNode, RectangleNode, LineNode, EllipseNode, PolygonNode, StarNode, VectorNode, TextNode, TextPathNode, ComponentPropertyType, InstanceSwapPreferredValue, ComponentPropertyOptions, ComponentPropertyDefinitions, ComponentSetNode, ComponentNode, ComponentProperties, InstanceNode, SlotNode, BooleanOperationNode, StickyNode, StampNode, TableNode, TableCellNode, HighlightNode, WashiTapeNode, ShapeWithTextNode, CodeBlockNode, LabelSublayerNode, ConnectorNode, VariableResolvedDataType, VariableAlias, VariableValue, VariableScope, CodeSyntaxPlatform, Variable, VariableCollection, ExtendedVariableCollection, AnnotationCategoryColor, AnnotationCategory, WidgetNode, EmbedData, EmbedNode, LinkUnfurlData, LinkUnfurlNode, MediaData, MediaNode, SectionNode, SlideNode, SlideRowNode, SlideGridNode, InteractiveSlideElementNode, SlideTransition, BaseNode, SceneNode, NodeType, StyleType, InheritedStyleField, StyleConsumers, BaseStyleMixin, PaintStyle, TextStyle, EffectStyle, GridStyle, BaseStyle, Image, Video, BaseUser, User, ActiveUser, FindAllCriteria, TransformModifier, RepeatModifier, LinearRepeatModifier, RadialRepeatModifier } diff --git a/plugin-api.d.ts b/plugin-api.d.ts index 15c2d34..f0c6fc6 100644 --- a/plugin-api.d.ts +++ b/plugin-api.d.ts @@ -439,7 +439,6 @@ interface PluginAPI { readonly teamLibrary: TeamLibraryAPI /** * This property contains methods to work with annotations. - * */ readonly annotations: AnnotationsAPI /** @@ -447,7 +446,6 @@ interface PluginAPI { * This API is only available in Buzz. * * This property contains methods to work in Buzz. - * */ readonly buzz: BuzzAPI /** @@ -807,29 +805,43 @@ interface PluginAPI { * Triggered when the total time on the timer changes. From the UI, it is only possible to add time to the timer. However, plugin code can both add and remove time from a running timer. */ on(type: ArgFreeEventType, callback: () => void): void + on(type: 'run', callback: (event: RunEvent) => void): void + on(type: 'drop', callback: (event: DropEvent) => boolean): void + on(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void + on(type: 'slidesviewchange', callback: (event: SlidesViewChangeEvent) => void): void + on(type: 'canvasviewchange', callback: (event: CanvasViewChangeEvent) => void): void + on( type: 'textreview', callback: (event: TextReviewEvent) => Promise | TextReviewRange[], ): void + on(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void /** * Same as `figma.on`, but the callback will only be called once, the first time the specified event happens. */ once(type: ArgFreeEventType, callback: () => void): void + once(type: 'run', callback: (event: RunEvent) => void): void + once(type: 'drop', callback: (event: DropEvent) => boolean): void + once(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void + once(type: 'slidesviewchange', callback: (event: SlidesViewChangeEvent) => void): void + once(type: 'canvasviewchange', callback: (event: CanvasViewChangeEvent) => void): void + once( type: 'textreview', callback: (event: TextReviewEvent) => Promise | TextReviewRange[], ): void + once(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void /** * Removes a callback added with `figma.on` or `figma.once`. @@ -852,15 +864,22 @@ interface PluginAPI { * ``` */ off(type: ArgFreeEventType, callback: () => void): void + off(type: 'run', callback: (event: RunEvent) => void): void + off(type: 'drop', callback: (event: DropEvent) => boolean): void + off(type: 'documentchange', callback: (event: DocumentChangeEvent) => void): void + off(type: 'slidesviewchange', callback: (event: SlidesViewChangeEvent) => void): void + off(type: 'canvasviewchange', callback: (event: CanvasViewChangeEvent) => void): void + off( type: 'textreview', callback: (event: TextReviewEvent) => Promise | TextReviewRange[], ): void + off(type: 'stylechange', callback: (event: StyleChangeEvent) => void): void /** * This a constant value that some node properties return when they are a mix of multiple values. An example might be font size: a single text node can use multiple different font sizes for different character ranges. For those properties, you should always compare against `figma.mixed`. @@ -1927,7 +1946,6 @@ interface PluginAPI { * ```ts * const grid = figma.getCanvasGrid() * ``` - * */ getCanvasGrid(): Array> /** @@ -1964,7 +1982,6 @@ interface PluginAPI { * @remarks * * If no row index is provided, the row will be added at the end of the grid. - * */ createCanvasRow(rowIndex?: number): SceneNode /** @@ -2810,7 +2827,6 @@ interface ConstantsAPI { * ``` * * @remarks - * */ colors: ColorPalettes } @@ -2910,6 +2926,7 @@ interface CodegenAPI { type: 'generate', callback: (event: CodegenEvent) => Promise | CodegenResult[], ): void + on(type: 'preferenceschange', callback: (event: CodegenPreferencesEvent) => Promise): void /** * Same as {@link CodegenAPI.on | `figma.codegen.on`}, but the callback only gets called the first time. @@ -2918,6 +2935,7 @@ interface CodegenAPI { type: 'generate', callback: (event: CodegenEvent) => Promise | CodegenResult[], ): void + once(type: 'preferenceschange', callback: (event: CodegenPreferencesEvent) => Promise): void /** * Removes a callback added by {@link CodegenAPI.on | `figma.codegen.on`} or {@link CodegenAPI.once | `figma.codegen.once`}. @@ -2926,6 +2944,7 @@ interface CodegenAPI { type: 'generate', callback: (event: CodegenEvent) => Promise | CodegenResult[], ): void + off(type: 'preferenceschange', callback: (event: CodegenPreferencesEvent) => Promise): void /** * Read the current preferences as specified by the user. @@ -3304,6 +3323,7 @@ interface RunParametersEvent { command: string parameters: ParametersType } + interface OpenDevResourcesEvent { command: 'open-dev-resource' parameters?: undefined @@ -3312,7 +3332,9 @@ interface OpenDevResourcesEvent { name: string } } + type RunEvent = RunParametersEvent | OpenDevResourcesEvent + interface SlidesViewChangeEvent { view: 'GRID' | 'SINGLE_SLIDE' } @@ -3330,6 +3352,7 @@ interface CanvasViewChangeEvent { */ view: 'SINGLE_ASSET' | 'GRID' } + interface DropEvent { node: BaseNode | SceneNode x: number @@ -3340,22 +3363,26 @@ interface DropEvent { files: DropFile[] dropMetadata?: any } + interface DropItem { type: string data: string } + interface DropFile { name: string type: string getBytesAsync(): Promise getTextAsync(): Promise } + interface DocumentChangeEvent { /** * An array of {@link DocumentChange} that has happened since the last time the event was fired. */ documentChanges: DocumentChange[] } + interface StyleChangeEvent { /** * An array of {@link StyleChange} that has happened since the last time the event was fired. @@ -3617,6 +3644,7 @@ type NodeChangeProperty = | 'authorName' | 'code' | 'textBackground' + interface NodeChangeEvent { nodeChanges: NodeChange[] } @@ -3648,9 +3676,11 @@ type StyleChangeProperty = | 'paint' | 'effects' | 'layoutGrids' + type TextReviewEvent = { text: string } + type TextReviewRange = { start: number end: number @@ -5272,6 +5302,12 @@ type ConnectorStrokeCap = | 'TRIANGLE_FILLED' | 'DIAMOND_FILLED' | 'CIRCLE_FILLED' + | 'ERD_ZERO_OR_ONE' + | 'ERD_EXACTLY_ONE' + | 'ERD_ZERO_OR_MORE' + | 'ERD_ONE_OR_MORE' + | 'ERD_ONE' + | 'ERD_MANY' /** * @see https://developers.figma.com/docs/plugins/api/node-properties */ @@ -5505,7 +5541,6 @@ interface DevResourcesMixin { * * @param url - The url of the dev resource. * @param name - The name of the dev resource. If not provided, Figma will get the name from the url. - * */ addDevResourceAsync(url: string, name?: string): Promise /** @@ -5514,7 +5549,6 @@ interface DevResourcesMixin { * * @param currentUrl - The current url of the dev resource. * @param newValue - The new name and/or url of the dev resource. - * */ editDevResourceAsync( currentUrl: string, @@ -5593,6 +5627,8 @@ interface SceneNodeMixin extends ExplicitVariableModesMixin { readonly attachedConnectors: ConnectorNode[] /** * All component properties that are attached on this node. A node can only have `componentPropertyReferences` if it is a component sublayer or an instance sublayer. It will be `null` otherwise. The value in the key-value pair refers to the component property name as returned by `componentPropertyDefinitions` on the containing component, component set or main component (for instances). + * + * When setting, may throw the following errors: cannotApplySlotPropertyToNonFrameNode, cannotApplySlotPropertyToFrameWithGrid, or cannotApplySlotPropertyToFrame. */ componentPropertyReferences: | { @@ -6439,6 +6475,8 @@ interface AutoLayoutMixin { * * This property must be set to `"HORIZONTAL"` or `"VERTICAL"` in order for the {@link AutoLayoutMixin.primaryAxisSizingMode}, {@link AutoLayoutMixin.counterAxisSizingMode}, {@link AutoLayoutMixin.layoutWrap}, {@link AutoLayoutMixin.primaryAxisAlignItems}, {@link AutoLayoutMixin.counterAxisAlignItems}, {@link AutoLayoutMixin.counterAxisAlignContent}, {@link AutoLayoutMixin.paddingTop}, {@link AutoLayoutMixin.paddingBottom}, {@link AutoLayoutMixin.paddingLeft}, {@link AutoLayoutMixin.paddingRight}, {@link AutoLayoutMixin.itemSpacing}, {@link AutoLayoutMixin.counterAxisSpacing}, {@link AutoLayoutMixin.itemReverseZIndex}, and {@link AutoLayoutMixin.strokesIncludedInLayout} properties to be applicable. * + * Note: `GRID` is not supported for Slot frames, and setting `GRID` will throw a cannotApplyGridToSlot error. + * * ```ts title="Auto-layout frame with horizontal layout" * const parentFrame = figma.createFrame() * parentFrame.appendChild(figma.createFrame()) @@ -8054,7 +8092,6 @@ interface AnnotationsMixin { * Annotations on the node. * * Learn more about annotations in the [Help Center](https://help.figma.com/hc/en-us/articles/20774752502935) or see the [Annotation type](https://developers.figma.com/docs/plugins/api/Annotation) for usage examples. - * */ annotations: ReadonlyArray } @@ -8377,7 +8414,7 @@ interface ComponentPropertiesMixin { */ readonly componentPropertyDefinitions: ComponentPropertyDefinitions /** - * Adds a new component property to this node and returns the property name with its unique identifier suffixed. This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'` or `'VARIANT'`. + * Adds a new component property to this node and returns the property name with its unique identifier suffixed. This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'`, `'VARIANT'`, or `'SLOT'`. */ addComponentProperty( propertyName: string, @@ -8388,11 +8425,12 @@ interface ComponentPropertiesMixin { /** * Modifies the name, default value, or preferred values of an existing component property on this node and returns the property name with its unique identifier suffixed. * - * This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'`, or `'VARIANT'` with the following restrictions: + * This function supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'`, `'VARIANT'`, or `'SLOT'` with the following restrictions: * * - `name` is supported for all properties - * - `defaultValue` is supported for `'BOOLEAN'`, `'TEXT'`, and `'INSTANCE_SWAP'` properties, but not for `'VARIANT'` properties - * - `preferredValues` is only supported for `'INSTANCE_SWAP'` properties + * - `defaultValue` is supported for `'BOOLEAN'`, `'TEXT'`, and `'INSTANCE_SWAP'` properties, but not for `'VARIANT'` or `'SLOT'` properties + * - `preferredValues` is only supported for `'INSTANCE_SWAP'` and `'SLOT'` properties + * - `description` is only supported for `'SLOT'` properties */ editComponentProperty( propertyName: string, @@ -8400,10 +8438,11 @@ interface ComponentPropertiesMixin { name?: string defaultValue?: string | boolean | VariableAlias preferredValues?: InstanceSwapPreferredValue[] + description?: string }, ): string /** - * Deletes an existing component property on this node. This function only supports properties with type `'BOOLEAN'`, `'TEXT'`, or `'INSTANCE_SWAP'`. + * Deletes an existing component property on this node. This function only supports properties with type `'BOOLEAN'`, `'TEXT'`, `'INSTANCE_SWAP'` or `'SLOT'`. */ deleteComponentProperty(propertyName: string): void } @@ -9288,13 +9327,17 @@ interface PageNode focusedSlide?: SlideNode | null /** * - * Note: This API is only available in Figma Slides and Figma Buzz + * Note: This API is only available in Figma Slides, Figma Buzz, and Dev Mode. * - * When in Asset View, the Slide/Asset that is currently focused is accessible via this property. + * For Figma Slides and Figma Buzz: + * When in Asset View, this is the focused slide or asset. + * + * For Dev Mode: + * This is the node currently focused in Dev Mode focus view. This property is read-only in Dev Mode. * * @remarks * - * You can also set this via: + * In Figma Slides and Figma Buzz, you can also set this via: * * ```ts * figma.currentPage.focusedNode = node @@ -9616,7 +9659,7 @@ interface TextPathNode /** * @see https://developers.figma.com/docs/plugins/api/ComponentPropertyType */ -type ComponentPropertyType = 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP' | 'VARIANT' +type ComponentPropertyType = 'BOOLEAN' | 'TEXT' | 'INSTANCE_SWAP' | 'VARIANT' | 'SLOT' /** * @see https://developers.figma.com/docs/plugins/api/InstanceSwapPreferredValue */ @@ -9629,6 +9672,7 @@ type InstanceSwapPreferredValue = { */ type ComponentPropertyOptions = { preferredValues?: InstanceSwapPreferredValue[] + description?: string } /** * @see https://developers.figma.com/docs/plugins/api/ComponentPropertyDefinitions @@ -9639,6 +9683,7 @@ type ComponentPropertyDefinitions = { defaultValue: string | boolean preferredValues?: InstanceSwapPreferredValue[] variantOptions?: string[] + description?: string readonly boundVariables?: { [field in VariableBindableComponentPropertyField]?: VariableAlias } @@ -9686,6 +9731,10 @@ interface ComponentNode * Creates an instance of this component. By default, the instance will be parented under `figma.currentPage`. */ createInstance(): InstanceNode + /** + * Creates a new slot node within this component. + */ + createSlot(): SlotNode /** * Returns an array of all of the instances of this component in the document. */ @@ -9738,7 +9787,7 @@ interface InstanceNode extends DefaultFrameMixin, VariantMixin { */ swapComponent(componentNode: ComponentNode): void /** - * Sets the component properties and values for this instance. `propertyName` corresponds to the names returned by `componentPropertyDefinitions` and should be suffixed with `'#'` and a unique ID for `'TEXT'`, `'BOOLEAN'`, and `'INSTANCE_SWAP'` properties. In the case of name collision, this function prioritizes updating the `'VARIANT'` type properties. Existing properties that are non-specified in the function will maintain their current value. + * Sets the component properties and values for this instance. `propertyName` corresponds to the names returned by `componentPropertyDefinitions` and should be suffixed with `'#'` and a unique ID for `'TEXT'`, `'BOOLEAN'`, and `'INSTANCE_SWAP'` properties. Does not support `'SLOT'` properties and will throw `cannotSetSlotProperty`. In the case of name collision, this function prioritizes updating the `'VARIANT'` type properties. Existing properties that are non-specified in the function will maintain their current value. */ setProperties(properties: { [propertyName: string]: string | boolean | VariableAlias }): void /** @@ -9783,6 +9832,16 @@ interface InstanceNode extends DefaultFrameMixin, VariantMixin { */ removeOverrides(): void } +interface SlotNode extends DefaultFrameMixin { + /** + * The type of this node, represented by the string literal "SLOT" + */ + readonly type: 'SLOT' + /** + * Resets a given slot node to the original component slot content. + */ + resetSlot(): void +} interface BooleanOperationNode extends DefaultShapeMixin, ChildrenMixin, @@ -10941,6 +11000,7 @@ type SceneNode = | SlideNode | SlideRowNode | SlideGridNode + | SlotNode | InteractiveSlideElementNode /** * @see https://developers.figma.com/docs/plugins/api/node-types diff --git a/test-usage.sh b/test-usage.sh index 7c43b67..faf69a0 100755 --- a/test-usage.sh +++ b/test-usage.sh @@ -147,7 +147,7 @@ function testParameters() { EOF -npm install typescript +npm install typescript@5 npm install ../../ npx tsc --noEmit @@ -198,7 +198,7 @@ const gradient: GradientPaint = { type VectorAlias = Vector EOF -npm install typescript +npm install typescript@5 npm install ../../ npx tsc --noEmit