sketch-plugin-types
Version:
TypeScript type definitions for the Sketch app plugin API (sketch/dom, sketch/ui, sketch/settings, sketch/async, sketch/data-supplier) and the Action API.
476 lines (451 loc) • 13.1 kB
TypeScript
/// <reference path="./native.d.ts" />
/// <reference path="./dom.d.ts" />
/**
* Action API typings. These are consumed by:
* - `manifest.json` via `handlers.actions` (keys of `SketchActionHandlersMap`)
* - per-command action handler functions (signature: `SketchActionHandler<Name>`)
*
* The runtime vocabulary covers 323 action names scraped from
* https://developer.sketch.com/reference/action/. Only ~12 of them document a
* concrete `actionContext` payload; the rest resolve to `unknown`.
*/
import * as Sketch from 'sketch/dom';
// ---------------------------------------------------------------------
// Documented action payloads
// ---------------------------------------------------------------------
export interface OpenDocumentContext {
document: Sketch.Document;
}
export interface CloseDocumentContext {
document?: Sketch.Document;
}
export interface StartupContext {}
export interface ShutdownContext {}
export interface SelectionChangedContext {
document: Sketch.Document;
oldSelection: Sketch.Layer[];
newSelection: Sketch.Layer[];
}
export interface LayersMovedContext {
document: Sketch.Document;
layers: Sketch.Layer[];
}
export interface LayersResizedContext {
document: Sketch.Document;
layers: Sketch.Layer[];
}
export interface TextChangedContext {
layer: Sketch.Text;
// Note: prior to Sketch 2026.1 this context also carried `old` / `new`
// string fields (previous and updated text). They were removed; plugins
// that need before/after diffing must track the change themselves.
}
export interface ArtboardChangedContext {
document: Sketch.Document;
oldArtboard: Sketch.Artboard | null;
newArtboard: Sketch.Artboard | null;
}
export interface DocumentSavedContext {
document: Sketch.Document;
/** File size of the saved document, in bytes. */
size: number;
/** `true` if the OS triggered an auto-save, `false` for a manual save. */
autoSaved: boolean;
}
export interface HandleURLContext {
/** The bridged `NSURL` that triggered the action. */
url: SketchNative.NSURL;
/** Everything after `sketch://plugin`. */
path: string;
/** Parsed `?key=value` pairs. */
query: Record<string, string>;
}
export interface ExportSlicesContext {
document: SketchNative.MSImmutableDocumentData;
exports: Array<{
/** Native `MSExportRequest` (scale, format, trimming, etc.). */
request: SketchNative.MSExportRequest;
/** Absolute filesystem path of the exported file. */
path: string;
}>;
}
// ---------------------------------------------------------------------
// Typed payload map
// ---------------------------------------------------------------------
export interface SketchActionContextMap {
OpenDocument: OpenDocumentContext;
CloseDocument: CloseDocumentContext;
Startup: StartupContext;
Shutdown: ShutdownContext;
SelectionChanged: SelectionChangedContext;
LayersMoved: LayersMovedContext;
LayersResized: LayersResizedContext;
TextChanged: TextChangedContext;
ArtboardChanged: ArtboardChangedContext;
DocumentSaved: DocumentSavedContext;
HandleURL: HandleURLContext;
ExportSlices: ExportSlicesContext;
ApplySharedLayerStyle: unknown;
ApplySharedTextStyle: unknown;
ToggleFill: unknown;
ToggleBorder: unknown;
}
// ---------------------------------------------------------------------
// Full name union (323 entries)
// ---------------------------------------------------------------------
export type SketchActionName =
| 'AddAsLibrary'
| 'AddBorder'
| 'AddExportFormat'
| 'AddFill'
| 'AddFlow'
| 'AddFlowBack'
| 'AddFlowHome'
| 'AddInnerShadow'
| 'AddShadow'
| 'AlignBottom'
| 'AlignCenter'
| 'AlignJustified'
| 'AlignLayersBottom'
| 'AlignLayersCenter'
| 'AlignLayersLeft'
| 'AlignLayersMiddle'
| 'AlignLayersRight'
| 'AlignLayersTop'
| 'AlignLeft'
| 'AlignMiddle'
| 'AlignRight'
| 'AlignTop'
| 'AlignmentActions'
| 'ApplyData'
| 'ApplyHorizontalFlip'
| 'ApplyLandscapeOrientation'
| 'ApplyPortraitOrientation'
| 'ApplySharedLayerStyle'
| 'ApplySharedTextStyle'
| 'ApplyVerticalFlip'
| 'ArtboardChanged'
| 'AssignColorSpace'
| 'Assistant'
| 'AssistantActivate'
| 'AssistantCheckDocument'
| 'AssistantCheckDocumentAutomatically'
| 'AssistantConfigure'
| 'AssistantInstallFromDisk'
| 'AssistantInstallFromURL'
| 'AssistantInstallMissing'
| 'AssistantShowIgnored'
| 'AutoExpandGroups'
| 'BackToInstance'
| 'BadgeMenu'
| 'BaseAlignLayers'
| 'BaseStyle'
| 'BooleanActionGroup'
| 'BooleanMenu'
| 'CenterLayersInCanvas'
| 'CenterSelectionInVisibleArea'
| 'ChangeFlowAnimationFromBottomAnimation'
| 'ChangeFlowAnimationFromLeftAnimation'
| 'ChangeFlowAnimationFromRightAnimation'
| 'ChangeFlowAnimationFromTopAnimation'
| 'ChangeFlowAnimationNoAnimation'
| 'ChangeFont'
| 'ChangeInferredLayout'
| 'ClearDataRecord'
| 'ClippingMask'
| 'ClippingMaskMode'
| 'CloseDocument'
| 'ClosePath'
| 'Cloud'
| 'CollapseAllGroups'
| 'ColorInspectorCircularGradientTab'
| 'ColorInspectorColorTab'
| 'ColorInspectorImageTab'
| 'ColorInspectorLinearGradientTab'
| 'ColorInspectorModeBorderTouchBarGroup'
| 'ColorInspectorModeFillTouchBarGroup'
| 'ColorInspectorModePicker'
| 'ColorInspectorRadialGradientTab'
| 'ConstraintFixHeight'
| 'ConstraintFixWidth'
| 'ConstraintPinBottom'
| 'ConstraintPinLeft'
| 'ConstraintPinRight'
| 'ConstraintPinTop'
| 'ConstraintReset'
| 'ContextMenuData'
| 'ConvertColorSpace'
| 'ConvertFlowToHotspot'
| 'ConvertSymbolOrDetachInstances'
| 'ConvertSymbolOrDetachInstancesRecursively'
| 'ConvertToOutlines'
| 'Copy'
| 'CopyCSSAttributes'
| 'CopyCloudDocumentLink'
| 'CopyOverride'
| 'CopySVGCode'
| 'CopyStyle'
| 'CreateSharedColor'
| 'CreateSharedStyle'
| 'CreateSymbol'
| 'CurveModeAsymmetric'
| 'CurveModeDisconnected'
| 'CurveModeMirrored'
| 'CurveModeStraight'
| 'CurveModeTouchGroup'
| 'Cut'
| 'DataMenu'
| 'DefaultStyle'
| 'Delete'
| 'DetachSharedColor'
| 'DetachSharedStyle'
| 'Difference'
| 'DistributeActions'
| 'DistributeHorizontally'
| 'DistributeVertically'
| 'DocumentSaved'
| 'Duplicate'
| 'Edit'
| 'EditColorSpace'
| 'Export'
| 'ExportPDFBook'
| 'ExportSelectionWithExportFormats'
| 'ExportSlices'
| 'Find'
| 'Flatten'
| 'FlattenSelection'
| 'FlipHorizontal'
| 'FlipVertical'
| 'FollowFlow'
| 'ForceResyncLibrary'
| 'GridSettings'
| 'Group'
| 'GroupActionGroup'
| 'HandleURL'
| 'HandlerGotFocus'
| 'HandlerLostFocus'
| 'HideAllGridsAndLayouts'
| 'HideLayer'
| 'IgnoreClippingMask'
| 'ImageOriginalSize'
| 'IncompatiblePluginsDisabled'
| 'InsertArrow'
| 'InsertArtboard'
| 'InsertHotspot'
| 'InsertImage'
| 'InsertLine'
| 'InsertMenu'
| 'InsertSharedText'
| 'InsertSlice'
| 'InsertSymbol'
| 'InsertTextLayer'
| 'InsertVector'
| 'Intersect'
| 'Join'
| 'LayerFocusActions'
| 'LayerHeightFocus'
| 'LayerWidthFocus'
| 'LayerXFocus'
| 'LayerYFocus'
| 'LayersMoved'
| 'LayersResized'
| 'LayoutSettings'
| 'LegacyInsertMenu'
| 'LicenseExpired'
| 'ListTypeActionBullet'
| 'ListTypeActionNone'
| 'ListTypeActionNumbered'
| 'LockLayer'
| 'Magnifier'
| 'MainMenuData'
| 'MakeGrid'
| 'MakeLowercase'
| 'MakeUppercase'
| 'ManageCloudDocumentShareSettings'
| 'MaskWithShape'
| 'Mirror'
| 'MoveActionGroup'
| 'MoveBackward'
| 'MoveForward'
| 'MoveToBack'
| 'MoveToFront'
| 'MoveToTop'
| 'MoveUpHierarchy'
| 'NavigateToOverrideMaster'
| 'NewPage'
| 'NextPage'
| 'OffsetPath'
| 'OpenDocument'
| 'OpenPreview'
| 'OpenStyleInLibrary'
| 'OpenSwatchInLibrary'
| 'OpenSymbolInLibrary'
| 'OpenTypeFeatures'
| 'OrganizeImportedSymbols'
| 'OvalShape'
| 'Paste'
| 'PasteHere'
| 'PasteOverSelection'
| 'PasteStyle'
| 'PasteWithStyle'
| 'Pencil'
| 'PolygonShape'
| 'PreviewAtActualSize'
| 'PreviousPage'
| 'Print'
| 'RectangleShape'
| 'Redo'
| 'ReduceFileSize'
| 'ReduceImageSize'
| 'RefreshData'
| 'RemoveAllOverrides'
| 'RemoveFlow'
| 'RemoveSelectedOverrides'
| 'RemoveTextTransform'
| 'RemoveUnusedStyles'
| 'RenameLayer'
| 'ReplaceColor'
| 'ReplaceFonts'
| 'ReplaceImage'
| 'ReplaceOverride'
| 'ReplaceOverrideStyle'
| 'ReplaceOverrideSymbol'
| 'ReplaceWithSymbol'
| 'ReplaceWithSymbolRoot'
| 'ResetOrigin'
| 'ResetSharedColor'
| 'ResetSharedStyle'
| 'ResetSymbolSize'
| 'ResizeArtboardToFit'
| 'RevealInLayerList'
| 'ReversePath'
| 'Rotate'
| 'RotateClockwise'
| 'RotateCounterclockwise'
| 'RoundToPixel'
| 'RoundedRectangleShape'
| 'RunPluginCommand'
| 'SaveAsTemplate'
| 'Scale'
| 'Scissors'
| 'Search'
| 'SelectAll'
| 'SelectAllArtboards'
| 'SelectionChanged'
| 'SendToSymbolsPage'
| 'Shape'
| 'ShowBorderOptions'
| 'ShowColors'
| 'ShowComponentsPane'
| 'ShowDocumentFonts'
| 'ShowFillOptions'
| 'ShowFonts'
| 'ShowLayerList'
| 'ShowReplaceColorSheet'
| 'Shutdown'
| 'Sketch.MSAddComponent'
| 'Sketch.MSChangeComponentKindActionGroup'
| 'Sketch.MSChangeLayerStyleComponentKind'
| 'Sketch.MSChangeSwatchComponentKind'
| 'Sketch.MSChangeSymbolComponentKind'
| 'Sketch.MSChangeTextStyleComponentKind'
| 'Sketch.MSComponentsPicker'
| 'Sketch.MSContentMode'
| 'Sketch.MSCopyComponent'
| 'Sketch.MSDeleteComponent'
| 'Sketch.MSDuplicateComponent'
| 'Sketch.MSEditSymbolMasterComponent'
| 'Sketch.MSFilterComponentList'
| 'Sketch.MSGroupComponents'
| 'Sketch.MSInsertComponentInstance'
| 'Sketch.MSMaintainScrollPosition'
| 'Sketch.MSRenameComponent'
| 'Sketch.MSRenameSharedStyle'
| 'Sketch.MSRevealComponent'
| 'Sketch.MSRevealComponentsPanel'
| 'Sketch.MSTidy'
| 'Sketch.MSUngroupComponents'
| 'Sketch.MSVisitSymbolComponent'
| 'Sketch.ToggleLibraryListInComponentsPanel'
| 'SmartRotate'
| 'StarShape'
| 'Startup'
| 'Subtract'
| 'SyncLibrary'
| 'SyncLocalColor'
| 'SyncLocalStyle'
| 'TextAlignTouchBarGroup'
| 'TextChanged'
| 'TextOnPath'
| 'TextStyleTouchBar'
| 'ToggleAlignmentGuides'
| 'ToggleArtboardShadow'
| 'ToggleBorder'
| 'ToggleFill'
| 'ToggleFixToViewport'
| 'ToggleFlowInteraction'
| 'ToggleGrid'
| 'ToggleInspectorVisibility'
| 'ToggleInterface'
| 'ToggleLayerHighlight'
| 'ToggleLayout'
| 'TogglePixelGrid'
| 'TogglePixelLines'
| 'ToggleRulerDragLocking'
| 'ToggleRulers'
| 'ToggleSelection'
| 'ToggleSidebarVisibility'
| 'ToggleSliceInteraction'
| 'ToggleToolbarVisibility'
| 'ToolsMenu'
| 'Transform'
| 'TriangleShape'
| 'Underline'
| 'Undo'
| 'Ungroup'
| 'Union'
| 'UnlinkAndSyncFromLibrary'
| 'UnlinkFromLibrary'
| 'UpdatePlugins'
| 'ViewDocumentInDocumentsWindow'
| 'ViewMenu'
| 'ViewOnSketchCloudWeb'
| 'Zoom'
| 'ZoomActions'
| 'ZoomIn'
| 'ZoomOut'
| 'ZoomToActualSize'
| 'ZoomToArtboard'
| 'ZoomToSelection';
/** Phase suffix that narrows a handler to one end of a two-phase action. */
export type SketchActionPhase = 'begin' | 'finish';
/**
* Any key that may appear in `handlers.actions`. Bare names listen to every
* phase; `.begin`/`.finish` narrow to one end of a two-phase action.
*/
export type SketchActionKey =
| SketchActionName
| `${SketchActionName}.${SketchActionPhase}`;
/** Resolve an action key back to its base name. */
export type SketchActionBaseName<K extends SketchActionKey> =
K extends `${infer Base}.${SketchActionPhase}` ? Base : K;
/** Strongly-typed payload for a given action name. */
export type SketchActionContextFor<Name extends string> =
Name extends keyof SketchActionContextMap
? SketchActionContextMap[Name]
: unknown;
/**
* Shape of the single `context` argument passed to an action handler.
* `actionContext` is the action-specific payload; the other fields come from
* the general plugin command context and are present in practice even though
* the Action API guide does not list them explicitly.
*/
export interface SketchHandlerContext<
Name extends SketchActionName = SketchActionName,
> {
actionContext: SketchActionContextFor<Name>;
}
/** Function signature for an action handler exported by a command script. */
export type SketchActionHandler<
Name extends SketchActionName = SketchActionName,
> = (context: SketchHandlerContext<Name>) => void;