@knotx/decorators 0.0.0

package/dist/index.d.mts

@@ -0,0 +1,370 @@
+import { RenderType, IPlugin, EdgeOperatorFunction, EdgeOperationPipe, EdgeRenderType, Engine, PluginData, Layer, VerticalAlignment, HorizontalAlignment, Container, NodeOperatorFunction, NodeOperationPipe, NodeRenderType } from '@knotx/core';
+
+interface IInternalPlugin<TPluginName extends string = string, TRenderType extends RenderType = RenderType> extends IPlugin<TPluginName, TRenderType> {
+}
+
+declare const edgeOperatorSymbol: unique symbol;
+declare module '../internal' {
+    interface IInternalPlugin {
+        [edgeOperatorSymbol]?: Record<string | symbol, EdgeOperatorFunction>;
+    }
+}
+/**
+ * 边操作装饰器
+ * 用于声明一个方法作为边操作函数
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends BasePlugin {
+ *   @edgeOperator()
+ *   addEdge(source: string, target: string) {
+ *     return [{
+ *       type: 'add',
+ *       edge: {
+ *         id: generateId(),
+ *         source,
+ *         target,
+ *       }
+ *     }]
+ *   }
+ * }
+ * ```
+ */
+declare function edgeOperator(): <TRenderType extends RenderType, Args extends any[]>(_target: any, { name, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<IInternalPlugin<string, TRenderType>, EdgeOperatorFunction<any, Args>>) => void;
+
+declare const edgePipeSymbol: unique symbol;
+declare module '../internal' {
+    interface IInternalPlugin {
+        [edgePipeSymbol]?: Record<string | symbol, EdgeOperationPipe<any>>;
+    }
+}
+/**
+ * 边操作管道装饰器
+ * 用于声明一个方法作为边操作管道，在边操作执行前后进行处理
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends BasePlugin {
+ *   @edgePipe()
+ *   validateEdgeOperation(): EdgeOperationPipe {
+ *     return {
+ *       // 在操作执行前进行验证
+ *       preOperation: () => pipe(
+ *         filter(operation => {
+ *           if (operation.type === 'add') {
+ *             return this.validateEdge(operation.data)
+ *           }
+ *           return true
+ *         })
+ *       )
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function edgePipe(): <TRenderType extends RenderType, T = any>(_target: any, { name, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<IInternalPlugin<string, TRenderType>, () => EdgeOperationPipe<T>>) => void;
+
+declare const edgeRendererSymbol: unique symbol;
+declare module '../internal' {
+    interface IInternalPlugin {
+        [edgeRendererSymbol]?: Record<string, EdgeRenderType>;
+    }
+}
+declare function edgeType(type: string): <TRenderType extends RenderType>(_target: any, { name, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<IInternalPlugin<string, TRenderType>, EdgeRenderType> | ClassFieldDecoratorContext<IInternalPlugin<string, TRenderType>, EdgeRenderType>) => void;
+
+type InjectableDataKey = keyof {
+    [K in keyof Engine as Engine[K] extends (...args: any[]) => any ? never : K]: Engine[K];
+};
+type InjectableMethodKey = Exclude<keyof Engine, InjectableDataKey>;
+interface InjectWithContext<T, TContext> {
+    __contextRef__: T;
+    __contextValue__: TContext;
+}
+type InjectDecoratorInjectableDataType = {
+    [K in InjectableDataKey]: {
+        (): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, Engine[K]>) => void;
+        <R>(selector: (data: Engine[K]) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, R>) => void;
+        <R, TContext>(selector: (data: Engine[K], context: TContext) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, InjectWithContext<R, TContext>>) => void;
+    };
+};
+type InjectDecoratorInjectablePluginDataType = {
+    [K in keyof PluginData]: {
+        [P in keyof PluginData[K]]: {
+            (): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, PluginData[K][P]>) => void;
+            <R>(selector: (data: PluginData[K][P]) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, R>) => void;
+            <R, TContext>(selector: (data: PluginData[K][P], context: TContext) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, InjectWithContext<R, TContext>>) => void;
+        };
+    };
+};
+type InjectDecoratorInjectableMethodType = {
+    [K in InjectableMethodKey]: () => (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, Engine[K]>) => void;
+};
+interface InjectDecoratorCallableDataType {
+    /**
+     * 注入引擎属性装饰器
+     * 用于将引擎的数据属性注入到插件类的字段中
+     * @param engineKey 引擎数据的键名
+     * @example
+     * ```
+     * @inject('nodes')
+     * nodes!: NodeData[]
+     * ```
+     */
+    <T extends InjectableDataKey>(engineKey: T): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, Engine[T]>) => void;
+    /**
+     * 注入引擎属性装饰器
+     * 用于将引擎的数据属性注入到插件类的字段中
+     * @param engineKey 引擎数据的键名
+     * @param selector 可选的选择器函数，用于转换注入的数据
+     * @example
+     * ```
+     * @inject('nodes', nodes => nodes.length)
+     * nodesCount!: number
+     * ```
+     */
+    <T extends InjectableDataKey, R = Engine[T]>(engineKey: T, selector: (data: Engine[T]) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, R>) => void;
+    /**
+     * 注入引擎属性装饰器
+     * 用于将引擎的数据属性注入到插件类的字段中
+     * @param engineKey 引擎数据的键名
+     * @param selector 可选的选择器函数，用于转换注入的数据
+     * @param context 可选的上下文对象，用于选择器函数
+     * @example
+     * ```
+     * @inject('nodes', (nodes, context) => nodes.find(node => node.id === context.node))
+     * ```
+     */
+    <T extends InjectableDataKey, TContext, R = Engine[T]>(engineKey: T, selector: (data: Engine[T], context: TContext) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, InjectWithContext<R, TContext>>) => void;
+}
+interface InjectDecoratorCallablePluginDataType {
+    /**
+     * 注入插件属性装饰器
+     * 用于将其他插件的数据属性注入到当前插件类的字段中
+     * @param pluginName 插件名称
+     * @param property 插件属性名
+     * @example
+     * ```
+     * @inject('history', 'canUndo')
+     * canUndo!: boolean
+     * ```
+     */
+    <T extends keyof PluginData, TP extends keyof PluginData[T]>(pluginName: T, property: TP): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, PluginData[T][TP]>) => void;
+    /**
+     * 注入插件属性装饰器
+     * 用于将其他插件的数据属性注入到当前插件类的字段中
+     * @param pluginName 插件名称
+     * @param property 插件属性名
+     * @param selector 可选的选择器函数，用于转换注入的数据
+     * @example
+     * ```
+     * @inject('drag', 'options', options => options.inertia)
+     * dragInertia!: boolean
+     * ```
+     */
+    <T extends keyof PluginData, TP extends keyof PluginData[T], R = PluginData[T][TP]>(pluginName: T, property: TP, selector: (data: PluginData[T][TP]) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, R>) => void;
+    /**
+     * 注入插件属性装饰器
+     * 用于将其他插件的数据属性注入到当前插件类的字段中
+     * @param pluginName 插件名称
+     * @param property 插件属性名
+     * @param selector 可选的选择器函数，用于转换注入的数据
+     * @param context 可选的上下文对象，用于选择器函数
+     * @example
+     * ```
+     * @inject('history', 'canUndo', (canUndo, context) => canUndo === context.xx)
+     * ```
+     */
+    <T extends keyof PluginData, TP extends keyof PluginData[T], TContext, R = PluginData[T][TP]>(pluginName: T, property: TP, selector: (data: PluginData[T][TP], context: TContext) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, InjectWithContext<R, TContext>>) => void;
+}
+interface InjectDecoratorCallableMethodType {
+    /**
+     * 注入引擎方法装饰器
+     * 用于将引擎的方法注入到插件类的字段或方法中
+     * @param methodKey 引擎方法的键名
+     * @example
+     * ```
+     * @inject('getNode')
+     * getNode!: (id: string) => NodeData | undefined
+     *
+     * @inject('dispatchNodeOperation')
+     * dispatchNodeOperation!: (operation: NodeOperation) => void
+     * ```
+     */
+    <T extends InjectableMethodKey>(methodKey: T): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, Engine[T]>) => void;
+}
+type Injectable = Pick<Engine, InjectableDataKey> & PluginData;
+interface InjectDecoratorInjectableType {
+    /**
+     * 使用 injectable 风格的注入
+     * 用于将多个数据源注入到插件类的字段中
+     * @param selector 使用 injectable 对象访问多个数据源的选择器函数
+     * @example
+     * ```
+     * @inject((injectable, context) => injectable.nodes.filter(node => node.id === context.id))
+     * filteredNodes!: NodeData[]
+     * ```
+     */
+    <R>(selector: (injectable: Injectable) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, R>) => void;
+    <R, TContext>(selector: (injectable: Injectable, context: TContext) => R): (_: undefined, context: ClassFieldDecoratorContext<IInternalPlugin, InjectWithContext<R, TContext>>) => void;
+}
+type InjectDecorator = InjectDecoratorInjectableDataType & InjectDecoratorInjectablePluginDataType & InjectDecoratorInjectableMethodType & InjectDecoratorCallableDataType & InjectDecoratorCallablePluginDataType & InjectDecoratorCallableMethodType & InjectDecoratorInjectableType;
+
+/**
+ * 注入引擎变量
+ * \@inject.property()
+ *
+ * 注入引擎变量并使用选择器
+ * \@inject.property(selector)
+ *
+ * 注入插件变量
+ * \@inject.pluginName.property()
+ * \@inject.pluginName.property(selector)
+ *
+ * 注入引擎方法
+ * \@inject.methodName()
+ */
+declare const inject: InjectDecorator;
+
+/**
+ * 注册插件属性装饰器
+ *
+ * 用于将插件的属性注册到引擎中，使其他插件可以通过 inject 访问该属性
+ * 支持装饰字段和 getter，当装饰字段时，属性值变化会自动通知订阅者
+ *
+ * @param property 要注册的属性名
+ * @returns 类字段或 getter 装饰器函数
+ * @example
+ * ```
+ * // 注册普通字段
+ * @register('canUndo')
+ * canUndo = false
+ *
+ * // 注册计算属性
+ * @register('ref')
+ * get ref() {
+ *   return this
+ * }
+ * ```
+ */
+declare function register<T extends keyof PluginData, TP extends keyof PluginData[T]>(property: TP): <TRenderType extends RenderType>(_: any, context: ClassFieldDecoratorContext<IInternalPlugin<T, TRenderType>, PluginData[T][TP]> | ClassGetterDecoratorContext<IInternalPlugin<T, TRenderType>, PluginData[T][TP]>) => void;
+
+declare function layer<This extends IPlugin>(layer: Layer, offset?: number): (_target: any, { name, kind, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<This>) => void;
+
+/**
+ * 面板位置
+ * @example
+ * ```
+ * @panel('top')
+ * ```
+ */
+type PanelPosition = VerticalAlignment | HorizontalAlignment | `${HorizontalAlignment}-${VerticalAlignment}` | 'center';
+/**
+ * 面板偏移
+ * @example
+ * ```
+ * @panel('top', { x: 10, y: 10 })
+ * ```
+ */
+interface PanelOffset {
+    x?: number;
+    y?: number;
+}
+/**
+ * 创建面板包装组件
+ * @param position 面板位置
+ * @param offset 面板偏移
+ */
+declare function createPanelWrapper(position: PanelPosition, offset?: PanelOffset): ({ children, container }: {
+    children: React.ReactNode;
+    container: Container;
+}) => JSX.Element;
+/**
+ * 面板装饰器
+ * @param position 面板位置
+ * @param offset 面板偏移
+ */
+declare function panel<This extends IPlugin>(position: PanelPosition, offset?: PanelOffset): (_target: any, { name, kind, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<This>) => void;
+
+declare const nodeOperatorSymbol: unique symbol;
+declare module '../internal' {
+    interface IInternalPlugin {
+        [nodeOperatorSymbol]?: Record<string | symbol, NodeOperatorFunction>;
+    }
+}
+/**
+ * 节点操作装饰器
+ * 用于声明一个方法作为节点操作函数
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends BasePlugin {
+ *   @nodeOperator()
+ *   addNode(x: number, y: number) {
+ *     return [{
+ *       type: 'add',
+ *       node: {
+ *         id: generateId(),
+ *         type: 'default',
+ *         position: { x, y }
+ *       }
+ *     }]
+ *   }
+ * }
+ * ```
+ */
+declare function nodeOperator(): <TRenderType extends RenderType, Args extends any[]>(_target: any, { name, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<IInternalPlugin<string, TRenderType>, NodeOperatorFunction<any, Args>>) => void;
+
+declare const nodePipeSymbol: unique symbol;
+declare module '../internal' {
+    interface IInternalPlugin {
+        [nodePipeSymbol]?: Record<string | symbol, NodeOperationPipe<any>>;
+    }
+}
+/**
+ * 节点操作管道装饰器
+ * 用于声明一个方法作为节点操作管道，在节点操作执行前后进行处理
+ *
+ * @example
+ * ```typescript
+ * class MyPlugin extends BasePlugin {
+ *   @nodePipe()
+ *   validateNodeOperation(): NodeOperationPipe {
+ *     return {
+ *       // 在操作执行前进行验证
+ *       preOperation: () => pipe(
+ *         filter(operation => {
+ *           if (operation.type === 'add') {
+ *             return this.validateNode(operation.data)
+ *           }
+ *           return true
+ *         })
+ *       )
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function nodePipe(): <TRenderType extends RenderType, T = any>(_target: any, { name, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<IInternalPlugin<string, TRenderType>, () => NodeOperationPipe<T>>) => void;
+
+declare const nodeRendererSymbol: unique symbol;
+declare module '../internal' {
+    interface IInternalPlugin {
+        [nodeRendererSymbol]?: Record<string, NodeRenderType>;
+    }
+}
+declare function nodeType(type: string): <TRenderType extends RenderType>(_target: any, { name, static: isStatic, private: isPrivate, addInitializer }: ClassMethodDecoratorContext<IInternalPlugin<string, TRenderType>, NodeRenderType> | ClassFieldDecoratorContext<IInternalPlugin<string, TRenderType>, NodeRenderType>) => void;
+
+/**
+ * 生命周期装饰器
+ * 在插件初始化时调用
+ */
+declare function OnInit<This extends IPlugin>(originalMethod: (this: This) => void, context: ClassMethodDecoratorContext<This>): void;
+/**
+ * 销毁装饰器
+ * 在插件销毁时调用
+ */
+declare function OnDestroy<This extends IPlugin>(originalMethod: (this: This) => void, context: ClassMethodDecoratorContext<This>): void;
+
+declare function observable<T>(): (_: any, context: ClassFieldDecoratorContext<IPlugin, T>) => void;
+
+export { type InjectDecorator, type InjectDecoratorCallableDataType, type InjectDecoratorCallableMethodType, type InjectDecoratorCallablePluginDataType, type InjectDecoratorInjectableDataType, type InjectDecoratorInjectableMethodType, type InjectDecoratorInjectablePluginDataType, type InjectDecoratorInjectableType, type InjectWithContext, type Injectable, type InjectableDataKey, type InjectableMethodKey, OnDestroy, OnInit, type PanelOffset, type PanelPosition, createPanelWrapper, edgeOperator, edgePipe, edgeType, inject, layer, nodeOperator, nodePipe, nodeType, observable, panel, register };