@mastergo/plugin-typings 2.7.0 → 2.8.0-beta.2

package/README-en.md

@@ -1,3 +1,5 @@
+[![Publish to NPM](https://github.com/mastergo-design/plugin-typings/actions/workflows/publish.yaml/badge.svg)](https://github.com/mastergo-design/plugin-typings/actions/workflows/publish.yaml)
+
 **English** | [中文](./README.md)
 
 # MasterGo Plugin Typings

package/README.md

@@ -1,3 +1,5 @@
+[![Publish to NPM](https://github.com/mastergo-design/plugin-typings/actions/workflows/publish.yaml/badge.svg)](https://github.com/mastergo-design/plugin-typings/actions/workflows/publish.yaml)
+
 **中文** | [English](./README-en.md)
 
 # MasterGo插件API声明文件

package/dist/index.d.ts

@@ -999,7 +999,11 @@ declare global {
 }
 
 declare global {
+  /**
+   * @deprecated please use mg instead
+   */
   const mastergo: PluginAPI
+
   const mg: PluginAPI
   const console: Console
   const __html__: string
@@ -1020,14 +1024,47 @@ declare global {
     clear(): void
   }
 
+  interface ConfirmAction {
+    label: string
+    type: 'primary' | 'text'
+    action: () => void
+  }
+
+  interface PromptAction {
+    label: string
+    type: 'primary' | 'text'
+    action: (value: string) => void
+  }
+
   interface Image {
     readonly href: string
     getBytesAsync(): Promise<Uint8Array>
   }
 
-  type PluginEventType = 'selectionchange' | 'layoutchange' | 'currentpagechange' | 'close' | 'themechange' | 'drop' | 'run'
   type ThemeColor = 'dark' | 'light'
 
+  type LayoutInfo = {
+    leftbar: number;
+    rightbar: number;
+    canvas: number;
+    window: number;
+    height: number;
+    topbar: number;
+  }
+
+  type MGEventCallbackMap = {
+    'selectionchange': (selectionLayerIds: string[]) => void;
+    'layoutchange': (layoutInfo: LayoutInfo) => void;
+    'currentpagechange': (pageId: string) => void;
+    'themechange': (theme: ThemeColor) => void;
+    'drop': (event: DropEvent) => void;
+    'run': (command: { command: string }) => void;
+    'close': () => void;
+    'beforeReadyForDev': (sectionLayerId: string, callback: (setReady: boolean) => void) => void;
+  }
+
+  type PluginEventType = keyof MGEventCallbackMap
+
   interface PluginAPI {
     readonly document: DocumentNode
 
@@ -1051,14 +1088,16 @@ declare global {
 
     readonly viewport: ViewportAPI
 
-    // only available in devMode
+    /**
+     * @note only available in devMode
+     */
     readonly codegen?: CodegenAPI
 
     closePlugin(): void
 
-    on(type: PluginEventType, callback: CallableFunction): void
-    once(type: PluginEventType, callback: CallableFunction): void
-    off(type?: PluginEventType, callback?: CallableFunction): void
+    on<T extends PluginEventType>(type: T, callback: MGEventCallbackMap[T]): void
+    once<T extends PluginEventType>(type: T, callback: MGEventCallbackMap[T]): void
+    off<T extends PluginEventType>(type?: T, callback?: MGEventCallbackMap[T]): void
 
     commitUndo(): void
     triggerUndo(): void
@@ -1105,16 +1144,64 @@ declare global {
 
     getStyleById(id: string): Style | null
     getTitleByFontFamilyAndStyle(fontFamily: string, fontStyle: string): FontAlias | null
+
     createFillStyle(config: CreateStyleConfig): PaintStyle
-    createStrokeStyle(config: CreateStyleConfig): PaintStyle
     createEffectStyle(config: CreateStyleConfig): EffectStyle
     createTextStyle(config: CreateStyleConfig): TextStyle
     createGridStyle(config: CreateStyleConfig): GridStyle
+    createCornerRadiusStyle(config: CreateStyleConfig): CornerRadiusStyle
+    createPaddingStyle(config: CreateStyleConfig): PaddingStyle
+    createSpacingStyle(config: CreateStyleConfig): SpacingStyle
+
+    /**
+     * @deprecated please use createStrokeFillStyle instead
+     */
+    createStrokeStyle(config: CreateStyleConfig): PaintStyle
+    createStrokeFillStyle(config: CreateStyleConfig): PaintStyle
+    createStrokeWidthStyle(config: CreateStyleConfig): StrokeWidthStyle
+
+    /**
+     * createFillStyle/createStrokeFillStyle 这些函数的聚合函数，传入不同的 type，返回对应的 style
+     * @param layerId 
+     * @param type NodeStyleType
+     * @param styleName
+     * @param description optional
+     */
+    createStyleByLayer<T extends NodeStyleType>(layerId: string, type: T, styleName: string, description?: string): NodeStyleReturnType<T>
+
+    /**
+     * 创建一个新的默认样式，不依赖某一个图层中的样式，
+     * eg: createStyle('PAINT', 'New Style', 'This is a new style')
+     * @param type styleType
+     * @param styleName
+     * @param description optional
+     */
+    createStyle<T extends StyleType>(type: T, styleName: string, description?: string): StyleReturnType<T>
+    /**
+     * 创建某一个样式的副本
+     * @param sourceStyleId 副本的源样式id
+     * @param type 
+     * @param styleName 
+     * @param description 
+     */
+    createStyleCopy<T extends StyleType = StyleType>(sourceStyleId: string, type: T, styleName?: string, description?: string): StyleReturnType<T>
+    /**
+     * 创建某一个样式引用
+     * @param sourceStyleId 引用源样式id
+     * @param type 
+     * @param styleName 
+     * @param description 
+     */
+    createStyleRef<T extends StyleType = StyleType>(sourceStyleId: string, type: T,  styleName?: string, description?: string): StyleReturnType<T>
 
     getLocalPaintStyles(): PaintStyle[]
     getLocalEffectStyles(): EffectStyle[]
     getLocalTextStyles(): TextStyle[]
     getLocalGridStyles(): GridStyle[]
+    getLocalStrokeWidthStyles(): StrokeWidthStyle[]
+    getLocalCornerRadiusStyles(): CornerRadiusStyle[]
+    getLocalPaddingStyles(): PaddingStyle[]
+    getLocalSpacingStyles(): SpacingStyle[]
 
     listAvailableFontsAsync(): Promise<Font[]>
     loadFontAsync(fontName: FontName): Promise<boolean>
@@ -1135,6 +1222,9 @@ declare global {
 
     hexToRGBA(hex: string): RGBA
     RGBAToHex(rgba: RGBA): string
+
+    confirm: (message: string, options: [ConfirmAction, ...ConfirmAction[]]) => void
+    prompt: (message: string, defaultValue: string, options: [PromptAction, ...PromptAction[]]) => void
   }
 
   interface User {
@@ -1256,19 +1346,23 @@ declare global {
     description: string
     documentationLinks: ReadonlyArray<DocumentationLink>
     /**
-     * 是否为团队库组件/样式
-    */
+     * @description 组件或者组件集的别名
+     */
+    alias: string
+
+    /**
+     * @description 是否为团队库组件/样式
+     */
     readonly isExternal: boolean
     readonly ukey: string
     readonly publishStatus: PublishStatus
   }
 
-  /// /////////////////////////////////////////////////////////////////////////////
   // Styles
+  type StyleType = 'PAINT' | 'TEXT' | 'EFFECT' | 'GRID' | 'STROKE_WIDTH' | 'CORNER_RADIUS' | 'PADDING' | 'SPACING'
+  type NodeStyleType = 'fill' | 'strokeFill' | 'strokeWidth' | 'cornerRadius' | 'padding' | 'spacing'
 
-  type StyleType = 'PAINT' | 'TEXT' | 'EFFECT' | 'GRID'
-
-  interface BaseStyle extends Omit<PublishableMixin, 'documentationLinks'> {
+  interface BaseStyle extends Omit<PublishableMixin, 'documentationLinks' | 'alias'> {
     readonly id: string
     readonly type: StyleType
     name: string
@@ -1280,6 +1374,26 @@ declare global {
     paints: ReadonlyArray<Paint>
   }
 
+  interface StrokeWidthStyle extends BaseStyle {
+    type: 'STROKE_WIDTH'
+    value: StrokeWidth
+  }
+
+  interface CornerRadiusStyle extends BaseStyle {
+    type: 'CORNER_RADIUS'
+    value: CornerRadius
+  }
+
+  interface PaddingStyle extends BaseStyle {
+    type: 'PADDING'
+    value: Padding
+  }
+
+  interface SpacingStyle extends BaseStyle {
+    type: 'SPACING'
+    value: Spacing
+  }
+
   interface NumValue {
     value: number
     unit: 'PIXELS' | 'PERCENT'
@@ -1463,6 +1577,24 @@ declare global {
 
   type Paint = SolidPaint | GradientPaint | ImagePaint
 
+  type CSSWidthSetter = number | [number, number] | [number, number, number] | [number, number, number, number]
+
+  interface StrokeWidth {
+    width: CSSWidthSetter,
+  }
+
+  interface Padding {
+    padding: CSSWidthSetter,
+  }
+
+  interface Spacing {
+    spacing: CSSWidthSetter,
+  }
+
+  interface CornerRadius {
+    cornerRadius: CSSWidthSetter,
+  }
+
   type WindingRule = 'Nonzero' | 'Evenodd'
 
   // 待确定
@@ -1658,7 +1790,17 @@ declare global {
     dashCap: DashCap
     strokeDashes: ReadonlyArray<number>
     fillStyleId: string
+    /**
+     * @deprecated please use strokePaintStyleId instead
+     */
     strokeStyleId: string
+    strokeFillStyleId: string
+    strokeWidthStyleId: string
+    borderStyleId: string
+    paddingStyleId: string
+    spacingStyleId: string
+    cornerRadiusStyleId: string
+
     /**
      * You have to ensure the layer has stroke before invoking this method.
      * 在调用接口之前需要确保layer有描边.
@@ -2310,6 +2452,10 @@ declare global {
       effects: ReadonlyArray<TeamLibraryStyle>
       texts: ReadonlyArray<TeamLibraryStyle>
       grids: ReadonlyArray<TeamLibraryStyle>
+      strokeWidths: ReadonlyArray<TeamLibraryStyle>
+      cornerRadiuses: ReadonlyArray<TeamLibraryStyle>
+      paddings: ReadonlyArray<TeamLibraryStyle>
+      spacings: ReadonlyArray<TeamLibraryStyle>
     }
   }>
 
@@ -2423,4 +2569,22 @@ declare global {
      */
     getCodeByDSL(data: MGDSL.MGDSLData, type: MGDSL.Framework): Promise<CodeFile | null>;
   }
+
+  type StyleReturnType<T extends StyleType> = 
+    T extends 'PAINT' ? PaintStyle : 
+    T extends 'TEXT' ? TextStyle : 
+    T extends 'EFFECT' ? EffectStyle : 
+    T extends 'GRID' ? GridStyle : 
+    T extends 'STROKE_WIDTH' ? StrokeWidthStyle : 
+    T extends 'CORNER_RADIUS' ? CornerRadiusStyle : 
+    T extends 'PADDING' ? PaddingStyle : 
+    T extends 'SPACING' ? SpacingStyle : never
+
+  type NodeStyleReturnType<T extends NodeStyleType> = 
+    T extends 'fill' ? PaintStyle : 
+    T extends 'strokeFill' ? PaintStyle : 
+    T extends 'strokeWidth' ? StrokeWidthStyle : 
+    T extends 'cornerRadius' ? CornerRadiusStyle : 
+    T extends 'padding' ? PaddingStyle : 
+    T extends 'spacing' ? SpacingStyle : never
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastergo/plugin-typings",
-  "version": "2.7.0",
+  "version": "2.8.0-beta.2",
   "description": "MasterGo插件API声明文件",
   "main": "",
   "types": "dist/index.d.ts",