From db55e3d1e083cc5c2cb54c079f97274e2a6775b8 Mon Sep 17 00:00:00 2001 From: Isaiah Turner <42742035+Isaiah-Turner@users.noreply.github.com> Date: Wed, 30 Sep 2026 10:49:30 -0700 Subject: [PATCH] update typings --- plugin-api-standalone.d.ts | 160 +++++++++++++++++++++++++++++++++---- plugin-api.d.ts | 158 ++++++++++++++++++++++++++++++++---- 2 files changed, 289 insertions(+), 29 deletions(-) diff --git a/plugin-api-standalone.d.ts b/plugin-api-standalone.d.ts index 620a065..68436f2 100644 --- a/plugin-api-standalone.d.ts +++ b/plugin-api-standalone.d.ts @@ -1475,6 +1475,12 @@ interface PluginAPI { * Creates a new Grid style. */ createGridStyle(): GridStyle + /** + * Note: This API is only available in Figma Design + * + * Creates a new custom animation style. See {@link CustomAnimationStyle}. + */ + createCustomAnimationStyle(): CustomAnimationStyle /** * Returns the list of local paint styles. */ @@ -1515,6 +1521,16 @@ interface PluginAPI { * @deprecated Use {@link PluginAPI.getLocalGridStylesAsync} instead. This function will throw an exception if the plugin manifest contains `"documentAccess": "dynamic-page"`. */ getLocalGridStyles(): GridStyle[] + /** + * Returns the list of local custom animation styles. + */ + getLocalCustomAnimationStylesAsync(): Promise + /** + * Returns the list of local custom animation styles. + * + * @deprecated Use {@link PluginAPI.getLocalCustomAnimationStylesAsync} instead. This function will throw an exception if the plugin manifest contains `"documentAccess": "dynamic-page"`. + */ + getLocalCustomAnimationStyles(): CustomAnimationStyle[] /** * Returns all of the colors in a user’s current selection. This * returns the same values that are shown in Figma's native selection @@ -1558,6 +1574,15 @@ interface PluginAPI { * Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local grid styles. */ moveLocalGridStyleAfter(targetNode: GridStyle, reference: GridStyle | null): void + /** + * Note: This API is only available in Figma Design + * + * Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local custom animation styles. + */ + moveLocalCustomAnimationStyleAfter( + targetNode: CustomAnimationStyle, + reference: CustomAnimationStyle | null, + ): void /** * Note: This API is only available in Figma Design * @@ -1582,6 +1607,12 @@ interface PluginAPI { * Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain grid styles. When referring to nested folders, the full delimited folder name must be used. See the {@link BaseStyle } section for more info. */ moveLocalGridFolderAfter(targetFolder: string, reference: string | null): void + /** + * Note: This API is only available in Figma Design + * + * Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain custom animation styles. When referring to nested folders, the full delimited folder name must be used. See the {@link BaseStyle } section for more info. + */ + moveLocalCustomAnimationFolderAfter(targetFolder: string, reference: string | null): void /** * Loads a component node from the team library. Promise is rejected if there is no published component with that key or if the request fails. */ @@ -5864,13 +5895,17 @@ interface AvailableAnimationStyle extends BaseAnimationStyle { /** * @see https://developers.figma.com/docs/plugins/api/Motion */ -interface AnimationStyleConfiguration { +interface FigmaAnimationStyleConfiguration { /** - * The duration of the applied animation style in seconds. + * Defaults to `"FIGMA"` when omitted. + */ + readonly type?: 'FIGMA' + /** + * The duration of the applied animation style in seconds. Must be finite and non-negative. */ readonly duration?: number /** - * The timeline offset of the applied animation style in seconds. + * The timeline offset of the applied animation style in seconds. Must be finite and non-negative. */ readonly timelineOffset?: number readonly props?: { @@ -5880,9 +5915,48 @@ interface AnimationStyleConfiguration { /** * @see https://developers.figma.com/docs/plugins/api/Motion */ -interface AppliedAnimationStyle extends BaseAnimationStyle, AnimationStyleConfiguration { +interface CustomAnimationStyleConfiguration { + readonly type: 'CUSTOM' + /** + * The timeline offset of the applied animation style in seconds. Must be finite and non-negative. + */ + readonly timelineOffset?: number +} +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +type AnimationStyleConfiguration = + FigmaAnimationStyleConfiguration | CustomAnimationStyleConfiguration +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +interface AppliedFigmaAnimationStyle extends BaseAnimationStyle, FigmaAnimationStyleConfiguration { + /** + * Always present when read back, unlike the optional `type` on + * {@link FigmaAnimationStyleConfiguration}. + */ + readonly type: 'FIGMA' readonly id: string + readonly description?: string } +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +interface AppliedCustomAnimationStyle + extends BaseAnimationStyle, CustomAnimationStyleConfiguration { + readonly id: string +} +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +type AppliedAnimationStyle = AppliedFigmaAnimationStyle | AppliedCustomAnimationStyle +/** + * One Figma animation contained in a {@link CustomAnimationStyle}. Read via + * `style.animationEntries` and created by `style.addAnimationEntryAsync()`. + * + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +type AnimationEntry = AppliedFigmaAnimationStyle /** * @see https://developers.figma.com/docs/plugins/api/Motion */ @@ -6664,14 +6738,21 @@ interface SceneNodeMixin extends ExplicitVariableModesMixin, MotionNodeMixin { interface MotionNodeMixin { /** * The Motion animation style instances currently applied to this node. - * Their `props` values are the configured property values for this node. + * + * Each entry is discriminated by `type`: `"FIGMA"` for a Figma-provided + * animation style, whose `props` values are the configured property values + * for this node, and `"CUSTOM"` for a {@link CustomAnimationStyle}. * * @remarks * ```ts * const node = figma.currentPage.selection[0] * if (node) { * for (const style of node.animationStyles) { - * console.log(style.name, style.id, style.props) + * if (style.type === 'FIGMA') { + * console.log(style.name, style.id, style.props) + * } else { + * console.log(style.name, style.id) + * } * } * } * ``` @@ -6720,8 +6801,8 @@ interface MotionNodeMixin { /** * Applies a Motion animation style to this node and returns the applied animation style instance id. * - * @param styleId - The `styleId` of the animation style to apply. Use {@link MotionAPI.figmaAnimationStyles} to get available styles. - * @param animationStyleData - Optional values used to configure the applied animation style. + * @param styleId - The animation style to apply. For a Figma animation style, the `styleId` from {@link MotionAPI.figmaAnimationStyles}. For a custom animation style, the `id` of a {@link CustomAnimationStyle}. + * @param animationStyleData - Optional values used to configure the applied animation style. Omit `type`, or set it to `"FIGMA"`, for a Figma animation style; set it to `"CUSTOM"` to apply a custom animation style. * * @remarks * ```ts @@ -6744,7 +6825,7 @@ interface MotionNodeMixin { /** * Removes an applied Motion animation style from this node. * - * @param id - The applied animation style instance id returned by {@link MotionNodeMixin.applyAnimationStyle} or read from {@link MotionNodeMixin.animationStyles}. + * @param id - The applied animation style instance id returned by {@link MotionNodeMixin.applyAnimationStyle} or read from {@link MotionNodeMixin.animationStyles}. The id determines which applied style is removed, whether it is a Figma animation style or a {@link CustomAnimationStyle}. * * @remarks * ```ts @@ -7721,7 +7802,7 @@ interface AutoLayoutMixin { * * @remarks * - * This property can only be set on layers with `layoutMode === "HORIZONTAL"`. Setting it on layers without this property will throw an Error. + * This property can only be set on layers with `layoutMode === "HORIZONTAL"` or `layoutMode === "VERTICAL"`. Setting it on layers with a different `layoutMode` will throw an Error. * * This property must be set to `"WRAP"` in order for the {@link AutoLayoutMixin.counterAxisSpacing} and {@link AutoLayoutMixin.counterAxisAlignContent} properties to be applicable. */ @@ -7903,8 +7984,8 @@ interface AutoLayoutMixin { * * Changing this property on a non-wrapping auto-layout frame will throw an error. * - * - `"AUTO"`: If all children of this auto-layout frame have {@link AutoLayoutChildrenMixin.layoutAlign} set to `"STRETCH"`, the tracks will stretch to fill the auto-layout frame. This is like flexbox `align-content: stretch`. Otherwise, each track will be as tall as the tallest child of the track, and will align based on the value of {@link AutoLayoutMixin.counterAxisAlignItems}. This is like flexbox `align-content: start | center | end`. {@link AutoLayoutMixin.counterAxisSpacing} is respected when `counterAxisAlignContent` is set to `"AUTO"`. - * - `"SPACE_BETWEEN"`: Tracks are all sized based on the tallest child in the track. The free space within the auto-layout frame is divided up evenly between each track. If the total height of all tracks is taller than the height of the auto-layout frame, the spacing will be 0. + * - `"AUTO"`: If all children of this auto-layout frame have {@link AutoLayoutChildrenMixin.layoutAlign} set to `"STRETCH"`, the tracks will stretch to fill the auto-layout frame. This is like flexbox `align-content: stretch`. Otherwise, each track will be sized to the largest child along the counter axis, and will align based on the value of {@link AutoLayoutMixin.counterAxisAlignItems}. This is like flexbox `align-content: start | center | end`. {@link AutoLayoutMixin.counterAxisSpacing} is respected when `counterAxisAlignContent` is set to `"AUTO"`. + * - `"SPACE_BETWEEN"`: Tracks are all sized based on the largest child along the counter axis in the track. The free space within the auto-layout frame is divided up evenly between each track. If the total size of all tracks along the counter axis exceeds the auto-layout frame’s counter-axis size, the spacing will be 0. */ counterAxisAlignContent: 'AUTO' | 'SPACE_BETWEEN' /** @@ -12369,7 +12450,7 @@ type SceneNode = * @see https://developers.figma.com/docs/plugins/api/node-types */ type NodeType = BaseNode['type'] -type StyleType = 'PAINT' | 'TEXT' | 'EFFECT' | 'GRID' +type StyleType = 'PAINT' | 'TEXT' | 'EFFECT' | 'GRID' | 'CUSTOM_ANIMATION' /** * @see https://developers.figma.com/docs/plugins/api/InheritedStyleField */ @@ -12538,7 +12619,56 @@ interface GridStyle extends BaseStyleMixin { readonly [field in VariableBindableGridStyleField]?: VariableAlias[] } } -type BaseStyle = PaintStyle | TextStyle | EffectStyle | GridStyle +interface CustomAnimationStyle extends BaseStyleMixin { + /** + * The string literal "CUSTOM_ANIMATION" representing the style type. Always check the `type` before reading other properties. + */ + type: 'CUSTOM_ANIMATION' + /** + * The Figma animations contained in this custom animation style, in order. + * + * @remarks + * ```ts + * const [style] = await figma.getLocalCustomAnimationStylesAsync() + * for (const entry of style?.animationEntries ?? []) { + * console.log(entry.id, entry.name, entry.props) + * } + * ``` + */ + readonly animationEntries: AnimationEntry[] + /** + * Adds a Figma animation to this custom animation style and resolves with the + * created entry. Throws if the style is remote, or if the animation cannot be + * added programmatically. + * + * @param styleId - The `styleId` of the Figma animation style to add, from {@link MotionAPI.figmaAnimationStyles}. + * @param props - Optional property overrides for the new entry. + * + * @remarks + * ```ts + * const style = figma.createCustomAnimationStyle() + * const [opacity] = figma.motion.figmaAnimationStyles() + * if (opacity) { + * const entry = await style.addAnimationEntryAsync(opacity.styleId) + * console.log(entry.id, entry.name) + * } + * ``` + */ + addAnimationEntryAsync( + styleId: string, + props?: { + readonly [key: string]: AnimationStylePropValue + }, + ): Promise + /** + * Removes an animation entry from this custom animation style. Throws if the + * style is remote, or if the style has no entry with that id. + * + * @param id - The `id` of the entry to remove, read from {@link CustomAnimationStyle.animationEntries}. + */ + removeAnimationEntry(id: string): void +} +type BaseStyle = PaintStyle | TextStyle | EffectStyle | GridStyle | CustomAnimationStyle interface Image { /** * A unique hash of the contents of the image file. @@ -12712,4 +12842,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, MotionAPI, 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, FontVariationSettings, FontNameInput, TextCase, TextDecoration, TextDecorationStyle, FontStyle, TextDecorationOffset, TextDecorationThickness, TextDecorationColor, OpenTypeFeature, ArcData, DropShadowEffect, InnerShadowEffect, BlurEffectBase, BlurEffectNormal, BlurEffectProgressive, BlurEffect, NoiseEffectBase, NoiseEffectMonotone, NoiseEffectDuotone, NoiseEffectMultitone, NoiseEffect, TextureEffect, GlassEffect, ShaderEffect, Effect, ConstraintType, Constraints, ColorStop, ImageFilters, SolidPaint, GradientPaint, ImagePaint, VideoPaint, PatternPaint, ShaderPaint, Paint, ShaderPropertyValue, ShaderPropertyDefinition, Shader, Guide, RowsColsLayoutGrid, GridLayoutGrid, LayoutGrid, ExportSettingsConstraints, ExportSettingsImage, ExportSettingsSVGBase, ExportSettingsSVG, ExportSettingsSVGString, ExportSettingsPDF, ExportSettingsREST, VideoExportScale, VideoExportConstraint, ExportSettingsMP4, ExportSettingsGIF, ExportSettingsWEBM, ExportSettings, WindingRule, VectorVertex, VectorSegment, VectorRegion, VectorNetwork, VectorPath, VectorPaths, LetterSpacing, LineHeight, LeadingTrim, TextWrapStyle, 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, MotionEasing, PhysicalSpring, NormalizedSpring, AnimationStylePropValue, AvailableAnimationStylePropValue, BaseAnimationStyle, AvailableAnimationStyle, AnimationStyleConfiguration, AppliedAnimationStyle, KeyframeValue, ManualKeyframeInput, ManualKeyframeTrackInput, ManualKeyframe, ManualKeyframeBinding, ManualKeyframeTrack, KeyframeBinding, KeyframePropertyFieldName, EffectKeyframeFieldName, KeyframeField, ComponentPropKeyframeTracks, ComponentPropKeyframeBindings, PaintManualKeyframeTrack, PaintKeyframeBinding, EffectManualKeyframeTracks, EffectKeyframeBindings, ManualKeyframeTracks, Animations, Timeline, OverflowDirection, OverlayPositionType, OverlayBackground, OverlayBackgroundInteraction, PublishStatus, ConnectorEndpointPosition, ConnectorEndpointPositionAndEndpointNodeId, ConnectorEndpointEndpointNodeIdAndMagnet, ConnectorEndpoint, ConnectorStrokeCap, BaseNodeMixin, PluginDataMixin, DevResourcesMixin, DevStatusMixin, SceneNodeMixin, MotionNodeMixin, 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, GridTrackReorderOptions, GridTrackReorderEntry, 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, SlotSettings, ComponentPropertyOptions, ComponentPropertyDefinitions, ComponentSetNode, ComponentNode, ComponentProperties, InstanceNode, SlotNode, BooleanOperationNode, StickyNode, StampNode, TableNode, TableCellNode, HighlightNode, WashiTapeNode, ShapeWithTextNode, CodeBlockNode, LabelSublayerNode, ConnectorNode, VariableResolvedDataType, VariableAlias, VariableComposedColor, 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, MotionAPI, 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, FontVariationSettings, FontNameInput, TextCase, TextDecoration, TextDecorationStyle, FontStyle, TextDecorationOffset, TextDecorationThickness, TextDecorationColor, OpenTypeFeature, ArcData, DropShadowEffect, InnerShadowEffect, BlurEffectBase, BlurEffectNormal, BlurEffectProgressive, BlurEffect, NoiseEffectBase, NoiseEffectMonotone, NoiseEffectDuotone, NoiseEffectMultitone, NoiseEffect, TextureEffect, GlassEffect, ShaderEffect, Effect, ConstraintType, Constraints, ColorStop, ImageFilters, SolidPaint, GradientPaint, ImagePaint, VideoPaint, PatternPaint, ShaderPaint, Paint, ShaderPropertyValue, ShaderPropertyDefinition, Shader, Guide, RowsColsLayoutGrid, GridLayoutGrid, LayoutGrid, ExportSettingsConstraints, ExportSettingsImage, ExportSettingsSVGBase, ExportSettingsSVG, ExportSettingsSVGString, ExportSettingsPDF, ExportSettingsREST, VideoExportScale, VideoExportConstraint, ExportSettingsMP4, ExportSettingsGIF, ExportSettingsWEBM, ExportSettings, WindingRule, VectorVertex, VectorSegment, VectorRegion, VectorNetwork, VectorPath, VectorPaths, LetterSpacing, LineHeight, LeadingTrim, TextWrapStyle, 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, MotionEasing, PhysicalSpring, NormalizedSpring, AnimationStylePropValue, AvailableAnimationStylePropValue, BaseAnimationStyle, AvailableAnimationStyle, FigmaAnimationStyleConfiguration, CustomAnimationStyleConfiguration, AnimationStyleConfiguration, AppliedFigmaAnimationStyle, AppliedCustomAnimationStyle, AppliedAnimationStyle, AnimationEntry, KeyframeValue, ManualKeyframeInput, ManualKeyframeTrackInput, ManualKeyframe, ManualKeyframeBinding, ManualKeyframeTrack, KeyframeBinding, KeyframePropertyFieldName, EffectKeyframeFieldName, KeyframeField, ComponentPropKeyframeTracks, ComponentPropKeyframeBindings, PaintManualKeyframeTrack, PaintKeyframeBinding, EffectManualKeyframeTracks, EffectKeyframeBindings, ManualKeyframeTracks, Animations, Timeline, OverflowDirection, OverlayPositionType, OverlayBackground, OverlayBackgroundInteraction, PublishStatus, ConnectorEndpointPosition, ConnectorEndpointPositionAndEndpointNodeId, ConnectorEndpointEndpointNodeIdAndMagnet, ConnectorEndpoint, ConnectorStrokeCap, BaseNodeMixin, PluginDataMixin, DevResourcesMixin, DevStatusMixin, SceneNodeMixin, MotionNodeMixin, 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, GridTrackReorderOptions, GridTrackReorderEntry, 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, SlotSettings, ComponentPropertyOptions, ComponentPropertyDefinitions, ComponentSetNode, ComponentNode, ComponentProperties, InstanceNode, SlotNode, BooleanOperationNode, StickyNode, StampNode, TableNode, TableCellNode, HighlightNode, WashiTapeNode, ShapeWithTextNode, CodeBlockNode, LabelSublayerNode, ConnectorNode, VariableResolvedDataType, VariableAlias, VariableComposedColor, 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, CustomAnimationStyle, BaseStyle, Image, Video, BaseUser, User, ActiveUser, FindAllCriteria, TransformModifier, RepeatModifier, LinearRepeatModifier, RadialRepeatModifier } diff --git a/plugin-api.d.ts b/plugin-api.d.ts index d743760..67fbe3a 100644 --- a/plugin-api.d.ts +++ b/plugin-api.d.ts @@ -1475,6 +1475,12 @@ interface PluginAPI { * Creates a new Grid style. */ createGridStyle(): GridStyle + /** + * Note: This API is only available in Figma Design + * + * Creates a new custom animation style. See {@link CustomAnimationStyle}. + */ + createCustomAnimationStyle(): CustomAnimationStyle /** * Returns the list of local paint styles. */ @@ -1515,6 +1521,16 @@ interface PluginAPI { * @deprecated Use {@link PluginAPI.getLocalGridStylesAsync} instead. This function will throw an exception if the plugin manifest contains `"documentAccess": "dynamic-page"`. */ getLocalGridStyles(): GridStyle[] + /** + * Returns the list of local custom animation styles. + */ + getLocalCustomAnimationStylesAsync(): Promise + /** + * Returns the list of local custom animation styles. + * + * @deprecated Use {@link PluginAPI.getLocalCustomAnimationStylesAsync} instead. This function will throw an exception if the plugin manifest contains `"documentAccess": "dynamic-page"`. + */ + getLocalCustomAnimationStyles(): CustomAnimationStyle[] /** * Returns all of the colors in a user’s current selection. This * returns the same values that are shown in Figma's native selection @@ -1558,6 +1574,15 @@ interface PluginAPI { * Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local grid styles. */ moveLocalGridStyleAfter(targetNode: GridStyle, reference: GridStyle | null): void + /** + * Note: This API is only available in Figma Design + * + * Reorders a target node after the specified reference node (if provided) or to be first if reference is null. The target and reference nodes must live in the same folder. The target and reference nodes must be local custom animation styles. + */ + moveLocalCustomAnimationStyleAfter( + targetNode: CustomAnimationStyle, + reference: CustomAnimationStyle | null, + ): void /** * Note: This API is only available in Figma Design * @@ -1582,6 +1607,12 @@ interface PluginAPI { * Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain grid styles. When referring to nested folders, the full delimited folder name must be used. See the {@link BaseStyle } section for more info. */ moveLocalGridFolderAfter(targetFolder: string, reference: string | null): void + /** + * Note: This API is only available in Figma Design + * + * Reorders a target folder after the specified reference folder (if provided) or to be first in the parent folder if reference is null. The target and reference folders must have the same parent folder. The target and reference folders must contain custom animation styles. When referring to nested folders, the full delimited folder name must be used. See the {@link BaseStyle } section for more info. + */ + moveLocalCustomAnimationFolderAfter(targetFolder: string, reference: string | null): void /** * Loads a component node from the team library. Promise is rejected if there is no published component with that key or if the request fails. */ @@ -5864,13 +5895,17 @@ interface AvailableAnimationStyle extends BaseAnimationStyle { /** * @see https://developers.figma.com/docs/plugins/api/Motion */ -interface AnimationStyleConfiguration { +interface FigmaAnimationStyleConfiguration { /** - * The duration of the applied animation style in seconds. + * Defaults to `"FIGMA"` when omitted. + */ + readonly type?: 'FIGMA' + /** + * The duration of the applied animation style in seconds. Must be finite and non-negative. */ readonly duration?: number /** - * The timeline offset of the applied animation style in seconds. + * The timeline offset of the applied animation style in seconds. Must be finite and non-negative. */ readonly timelineOffset?: number readonly props?: { @@ -5880,9 +5915,48 @@ interface AnimationStyleConfiguration { /** * @see https://developers.figma.com/docs/plugins/api/Motion */ -interface AppliedAnimationStyle extends BaseAnimationStyle, AnimationStyleConfiguration { +interface CustomAnimationStyleConfiguration { + readonly type: 'CUSTOM' + /** + * The timeline offset of the applied animation style in seconds. Must be finite and non-negative. + */ + readonly timelineOffset?: number +} +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +type AnimationStyleConfiguration = + FigmaAnimationStyleConfiguration | CustomAnimationStyleConfiguration +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +interface AppliedFigmaAnimationStyle extends BaseAnimationStyle, FigmaAnimationStyleConfiguration { + /** + * Always present when read back, unlike the optional `type` on + * {@link FigmaAnimationStyleConfiguration}. + */ + readonly type: 'FIGMA' readonly id: string + readonly description?: string } +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +interface AppliedCustomAnimationStyle + extends BaseAnimationStyle, CustomAnimationStyleConfiguration { + readonly id: string +} +/** + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +type AppliedAnimationStyle = AppliedFigmaAnimationStyle | AppliedCustomAnimationStyle +/** + * One Figma animation contained in a {@link CustomAnimationStyle}. Read via + * `style.animationEntries` and created by `style.addAnimationEntryAsync()`. + * + * @see https://developers.figma.com/docs/plugins/api/Motion + */ +type AnimationEntry = AppliedFigmaAnimationStyle /** * @see https://developers.figma.com/docs/plugins/api/Motion */ @@ -6664,14 +6738,21 @@ interface SceneNodeMixin extends ExplicitVariableModesMixin, MotionNodeMixin { interface MotionNodeMixin { /** * The Motion animation style instances currently applied to this node. - * Their `props` values are the configured property values for this node. + * + * Each entry is discriminated by `type`: `"FIGMA"` for a Figma-provided + * animation style, whose `props` values are the configured property values + * for this node, and `"CUSTOM"` for a {@link CustomAnimationStyle}. * * @remarks * ```ts * const node = figma.currentPage.selection[0] * if (node) { * for (const style of node.animationStyles) { - * console.log(style.name, style.id, style.props) + * if (style.type === 'FIGMA') { + * console.log(style.name, style.id, style.props) + * } else { + * console.log(style.name, style.id) + * } * } * } * ``` @@ -6720,8 +6801,8 @@ interface MotionNodeMixin { /** * Applies a Motion animation style to this node and returns the applied animation style instance id. * - * @param styleId - The `styleId` of the animation style to apply. Use {@link MotionAPI.figmaAnimationStyles} to get available styles. - * @param animationStyleData - Optional values used to configure the applied animation style. + * @param styleId - The animation style to apply. For a Figma animation style, the `styleId` from {@link MotionAPI.figmaAnimationStyles}. For a custom animation style, the `id` of a {@link CustomAnimationStyle}. + * @param animationStyleData - Optional values used to configure the applied animation style. Omit `type`, or set it to `"FIGMA"`, for a Figma animation style; set it to `"CUSTOM"` to apply a custom animation style. * * @remarks * ```ts @@ -6744,7 +6825,7 @@ interface MotionNodeMixin { /** * Removes an applied Motion animation style from this node. * - * @param id - The applied animation style instance id returned by {@link MotionNodeMixin.applyAnimationStyle} or read from {@link MotionNodeMixin.animationStyles}. + * @param id - The applied animation style instance id returned by {@link MotionNodeMixin.applyAnimationStyle} or read from {@link MotionNodeMixin.animationStyles}. The id determines which applied style is removed, whether it is a Figma animation style or a {@link CustomAnimationStyle}. * * @remarks * ```ts @@ -7721,7 +7802,7 @@ interface AutoLayoutMixin { * * @remarks * - * This property can only be set on layers with `layoutMode === "HORIZONTAL"`. Setting it on layers without this property will throw an Error. + * This property can only be set on layers with `layoutMode === "HORIZONTAL"` or `layoutMode === "VERTICAL"`. Setting it on layers with a different `layoutMode` will throw an Error. * * This property must be set to `"WRAP"` in order for the {@link AutoLayoutMixin.counterAxisSpacing} and {@link AutoLayoutMixin.counterAxisAlignContent} properties to be applicable. */ @@ -7903,8 +7984,8 @@ interface AutoLayoutMixin { * * Changing this property on a non-wrapping auto-layout frame will throw an error. * - * - `"AUTO"`: If all children of this auto-layout frame have {@link AutoLayoutChildrenMixin.layoutAlign} set to `"STRETCH"`, the tracks will stretch to fill the auto-layout frame. This is like flexbox `align-content: stretch`. Otherwise, each track will be as tall as the tallest child of the track, and will align based on the value of {@link AutoLayoutMixin.counterAxisAlignItems}. This is like flexbox `align-content: start | center | end`. {@link AutoLayoutMixin.counterAxisSpacing} is respected when `counterAxisAlignContent` is set to `"AUTO"`. - * - `"SPACE_BETWEEN"`: Tracks are all sized based on the tallest child in the track. The free space within the auto-layout frame is divided up evenly between each track. If the total height of all tracks is taller than the height of the auto-layout frame, the spacing will be 0. + * - `"AUTO"`: If all children of this auto-layout frame have {@link AutoLayoutChildrenMixin.layoutAlign} set to `"STRETCH"`, the tracks will stretch to fill the auto-layout frame. This is like flexbox `align-content: stretch`. Otherwise, each track will be sized to the largest child along the counter axis, and will align based on the value of {@link AutoLayoutMixin.counterAxisAlignItems}. This is like flexbox `align-content: start | center | end`. {@link AutoLayoutMixin.counterAxisSpacing} is respected when `counterAxisAlignContent` is set to `"AUTO"`. + * - `"SPACE_BETWEEN"`: Tracks are all sized based on the largest child along the counter axis in the track. The free space within the auto-layout frame is divided up evenly between each track. If the total size of all tracks along the counter axis exceeds the auto-layout frame’s counter-axis size, the spacing will be 0. */ counterAxisAlignContent: 'AUTO' | 'SPACE_BETWEEN' /** @@ -12369,7 +12450,7 @@ type SceneNode = * @see https://developers.figma.com/docs/plugins/api/node-types */ type NodeType = BaseNode['type'] -type StyleType = 'PAINT' | 'TEXT' | 'EFFECT' | 'GRID' +type StyleType = 'PAINT' | 'TEXT' | 'EFFECT' | 'GRID' | 'CUSTOM_ANIMATION' /** * @see https://developers.figma.com/docs/plugins/api/InheritedStyleField */ @@ -12538,7 +12619,56 @@ interface GridStyle extends BaseStyleMixin { readonly [field in VariableBindableGridStyleField]?: VariableAlias[] } } -type BaseStyle = PaintStyle | TextStyle | EffectStyle | GridStyle +interface CustomAnimationStyle extends BaseStyleMixin { + /** + * The string literal "CUSTOM_ANIMATION" representing the style type. Always check the `type` before reading other properties. + */ + type: 'CUSTOM_ANIMATION' + /** + * The Figma animations contained in this custom animation style, in order. + * + * @remarks + * ```ts + * const [style] = await figma.getLocalCustomAnimationStylesAsync() + * for (const entry of style?.animationEntries ?? []) { + * console.log(entry.id, entry.name, entry.props) + * } + * ``` + */ + readonly animationEntries: AnimationEntry[] + /** + * Adds a Figma animation to this custom animation style and resolves with the + * created entry. Throws if the style is remote, or if the animation cannot be + * added programmatically. + * + * @param styleId - The `styleId` of the Figma animation style to add, from {@link MotionAPI.figmaAnimationStyles}. + * @param props - Optional property overrides for the new entry. + * + * @remarks + * ```ts + * const style = figma.createCustomAnimationStyle() + * const [opacity] = figma.motion.figmaAnimationStyles() + * if (opacity) { + * const entry = await style.addAnimationEntryAsync(opacity.styleId) + * console.log(entry.id, entry.name) + * } + * ``` + */ + addAnimationEntryAsync( + styleId: string, + props?: { + readonly [key: string]: AnimationStylePropValue + }, + ): Promise + /** + * Removes an animation entry from this custom animation style. Throws if the + * style is remote, or if the style has no entry with that id. + * + * @param id - The `id` of the entry to remove, read from {@link CustomAnimationStyle.animationEntries}. + */ + removeAnimationEntry(id: string): void +} +type BaseStyle = PaintStyle | TextStyle | EffectStyle | GridStyle | CustomAnimationStyle interface Image { /** * A unique hash of the contents of the image file.