@coding-script/script-engine 0.0.2 → 0.0.4

package/README.md

@@ -9,7 +9,8 @@
 - **动态类型自动补全**：基于 `ScriptMetadata` 提供变量名补全和点号链式访问补全（如 `request.test.name`）
 - **Groovy 语法提示**：内置 `if`/`for`/`while`/`println`/`return` 等常用 Groovy 语法片段
 - **代码格式化**：内置 Groovy 格式化器，也可通过 `onFormat` 自定义格式化逻辑
-- **属性面板**：右侧侧边栏展示主函数签名、变量、数据类型（字段和方法），支持折叠/展开和拖拽调节宽度
+- **属性面板**：右侧侧边栏展示主函数签名、函数入参、绑定参数、数据类型（字段和方法），支持折叠/展开和拖拽调节宽度
+- **脚本说明**：工具栏"脚本说明"按钮，点击展开/收起脚本描述弹框，支持多行文本和 `key: value` 格式高亮
 - **主题切换**：暗色/亮色两套主题，编辑器、补全弹窗、属性面板同步切换，编辑器内部管理主题状态
 - **全屏模式**：支持 CSS 全屏（`position: fixed` 覆盖视口），不影响编辑器内容
 - **自定义工具栏**：通过 `toolbarExtra` 传入任意 React 节点
@@ -31,6 +32,7 @@ import type { ScriptMetadata } from '@coding-script/script-engine';
 
 const metadata: ScriptMetadata = {
   mainMethod: 'run',
+  description: '脚本主入口，接收请求参数并返回执行结果状态码',
   returnType: 'Integer',
   binds: [
     { dataType: 'GroovyBindObject', name: '$request' },
@@ -126,7 +128,44 @@ function App() {
 
 | 属性 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `toolbarExtra` | `React.ReactNode` | `undefined` | 工具栏额外内容，渲染在内置按钮之后，可传入任意 JSX |
+| `toolbar` | `ToolbarItem[]` | `undefined` | 工具栏自定义按钮列表，渲染在内置按钮之后、`toolbarExtra` 之前 |
+| `toolbarExtra` | `React.ReactNode` | `undefined` | 工具栏额外内容，渲染在最后，可传入任意 JSX |
+
+`ToolbarItem` 类型：
+
+```typescript
+interface ToolbarItem {
+  key: string;           // 唯一标识
+  label: ReactNode;      // 按钮内容
+  title: string;         // 鼠标悬停提示
+  backgroundColor: string;
+  hoverBackgroundColor: string;
+  textColor: string;
+  borderColor: string;
+  onClick: () => void;
+}
+```
+
+**使用按钮列表：**
+
+```tsx
+<ScriptCodeEditor
+  toolbar={[
+    {
+      key: 'save',
+      label: '💾 保存',
+      title: '保存脚本',
+      backgroundColor: '#007bff',
+      hoverBackgroundColor: '#0056b3',
+      textColor: '#fff',
+      borderColor: '#007bff',
+      onClick: () => saveCode(),
+    },
+  ]}
+/>
+```
+
+**使用自定义内容：**
 
 ```tsx
 <ScriptCodeEditor
@@ -151,8 +190,10 @@ function App() {
 
 ```typescript
 interface ScriptMetadata {
-  /** 主函数名称 */
-  mainMethod: string;
+  /** 主函数名称（可选） */
+  mainMethod?: string;
+  /** 脚本说明（可选，提供后在工具栏显示"脚本说明"按钮，点击展开/收起描述弹框） */
+  description?: string;
   /** 注入变量（如 $request，name 含 $ 前缀） */
   binds: ScriptBindInfo[];
   /** 主函数参数 */
@@ -241,4 +282,4 @@ pnpm run dev:app-pc
 
 ## License
 
-MIT
+Apache-2.0 license

package/dist/components/index.d.ts

@@ -1,7 +1,7 @@
 export { themes, SCROLL_CLASS, ensureScrollbarStyle } from './theme-colors';
 export type { ThemeColors } from './theme-colors';
 export { ToolbarButton } from './toolbar-button';
-export type { ToolbarButtonProps } from './toolbar-button';
+export type { ToolbarButtonProps } from '../types';
 export { Toolbar } from './toolbar';
 export type { ToolbarProps } from './toolbar';
 export { ExpandSidebarButton } from './expand-sidebar-button';

package/dist/components/section-header.d.ts

@@ -3,5 +3,7 @@ import type { ThemeColors } from './theme-colors';
 export interface SectionHeaderProps {
     colors: ThemeColors;
     label: string;
+    /** 标题右侧的额外操作区域（如按钮、图标） */
+    extra?: React.ReactNode;
 }
 export declare const SectionHeader: React.FC<SectionHeaderProps>;

package/dist/components/section-header.js

@@ -1,6 +1,9 @@
 import react from "react";
-const SectionHeader = ({ colors, label })=>/*#__PURE__*/ react.createElement("div", {
+const SectionHeader = ({ colors, label, extra })=>/*#__PURE__*/ react.createElement("div", {
         style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'space-between',
             padding: '6px 12px 4px',
             fontSize: 11,
             textTransform: 'uppercase',
@@ -8,5 +11,10 @@ const SectionHeader = ({ colors, label })=>/*#__PURE__*/ react.createElement("di
             color: colors.textSecondary,
             fontWeight: 600
         }
-    }, label);
+    }, /*#__PURE__*/ react.createElement("span", null, label), extra && /*#__PURE__*/ react.createElement("div", {
+        style: {
+            display: 'flex',
+            alignItems: 'center'
+        }
+    }, extra));
 export { SectionHeader };

package/dist/components/toolbar-button.d.ts

@@ -1,11 +1,3 @@
 import React from 'react';
-export interface ToolbarButtonProps {
-    label: React.ReactNode;
-    title: string;
-    bg: string;
-    hoverBg: string;
-    color: string;
-    border: string;
-    onClick: () => void;
-}
+import type { ToolbarButtonProps } from '../types';
 export declare const ToolbarButton: React.FC<ToolbarButtonProps>;

package/dist/components/toolbar-button.js

@@ -1,5 +1,5 @@
 import react, { useState } from "react";
-const ToolbarButton = ({ label, title, bg, hoverBg, color, border, onClick })=>{
+const ToolbarButton = ({ label, title, backgroundColor, hoverBackgroundColor, textColor, borderColor, onClick })=>{
     const [hovered, setHovered] = useState(false);
     return /*#__PURE__*/ react.createElement("button", {
         onClick: onClick,
@@ -9,9 +9,9 @@ const ToolbarButton = ({ label, title, bg, hoverBg, color, border, onClick })=>{
             display: 'inline-flex',
             alignItems: 'center',
             gap: 4,
-            background: hovered ? hoverBg : bg,
-            border: `1px solid ${border}`,
-            color,
+            background: hovered ? hoverBackgroundColor : backgroundColor,
+            border: `1px solid ${borderColor}`,
+            color: textColor,
             cursor: 'pointer',
             fontSize: 12,
             padding: '4px 10px',

package/dist/components/toolbar.d.ts

@@ -1,4 +1,5 @@
 import React from 'react';
+import type { ToolbarItem } from '../types';
 export interface ToolbarProps {
     title?: string;
     theme: 'dark' | 'light';
@@ -11,6 +12,9 @@ export interface ToolbarProps {
     enableFullscreen?: boolean;
     isFullscreen?: boolean;
     onToggleFullscreen?: () => void;
+    toolbar?: ToolbarItem[];
     toolbarExtra?: React.ReactNode;
+    /** 脚本说明内容（有值时显示"脚本说明"按钮） */
+    description?: string;
 }
 export declare const Toolbar: React.FC<ToolbarProps>;

package/dist/components/toolbar.js

@@ -1,7 +1,8 @@
-import react from "react";
+import react, { useCallback, useEffect, useRef, useState } from "react";
 import { ToolbarButton } from "./toolbar-button.js";
 import { FormatIcon } from "./format-icon.js";
 import { MaximizeIcon, MinimizeIcon } from "./fullscreen-icon.js";
+import { themes } from "./theme-colors.js";
 const HammerIcon = ({ color })=>/*#__PURE__*/ react.createElement("svg", {
         width: "14",
         height: "14",
@@ -28,13 +29,103 @@ const HammerIcon = ({ color })=>/*#__PURE__*/ react.createElement("svg", {
         opacity: 0.8,
         transform: "rotate(-25 12.25 14.5)"
     }));
-const Toolbar = ({ title, theme, onThemeChange, enableThemeToggle, enableFormat, onFormat, enableCompile, onCompile, enableFullscreen, isFullscreen, onToggleFullscreen, toolbarExtra })=>{
+const TIP_MARGIN = 6;
+const TIP_MAX_WIDTH = 380;
+function calcTooltipPos(anchorRect, el) {
+    const vw = window.innerWidth;
+    const vh = window.innerHeight;
+    const tipH = el?.scrollHeight ?? 200;
+    const spaceBelow = vh - anchorRect.bottom - TIP_MARGIN;
+    const spaceAbove = anchorRect.top - TIP_MARGIN;
+    const placeBelow = spaceBelow >= Math.min(tipH, 260) || spaceBelow >= spaceAbove;
+    const top = placeBelow ? anchorRect.bottom + TIP_MARGIN : Math.max(TIP_MARGIN, anchorRect.top - tipH - TIP_MARGIN);
+    let left = anchorRect.left;
+    const maxRight = vw - TIP_MARGIN;
+    if (left + TIP_MAX_WIDTH > maxRight) left = Math.max(TIP_MARGIN, maxRight - TIP_MAX_WIDTH);
+    const maxWidth = Math.min(TIP_MAX_WIDTH, maxRight - left);
+    const maxHeight = placeBelow ? spaceBelow - TIP_MARGIN : spaceAbove - TIP_MARGIN;
+    return {
+        top,
+        left,
+        maxWidth,
+        maxHeight: Math.max(maxHeight, 80)
+    };
+}
+const KV_RE = /^([^:]+):\s*([\s\S]+)$/;
+function renderDescLine(line, accent) {
+    const m = line.match(KV_RE);
+    if (m) return /*#__PURE__*/ react.createElement("span", null, /*#__PURE__*/ react.createElement("span", {
+        style: {
+            color: accent,
+            fontWeight: 600
+        }
+    }, m[1]), /*#__PURE__*/ react.createElement("span", null, ": ", m[2]));
+    return line;
+}
+const QuestionIcon = ({ color })=>/*#__PURE__*/ react.createElement("svg", {
+        width: "13",
+        height: "13",
+        viewBox: "0 0 24 24",
+        fill: "none",
+        stroke: color,
+        strokeWidth: 2.2,
+        strokeLinecap: "round",
+        strokeLinejoin: "round",
+        style: {
+            flexShrink: 0
+        }
+    }, /*#__PURE__*/ react.createElement("circle", {
+        cx: "12",
+        cy: "12",
+        r: "10"
+    }), /*#__PURE__*/ react.createElement("path", {
+        d: "M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"
+    }), /*#__PURE__*/ react.createElement("line", {
+        x1: "12",
+        y1: "17",
+        x2: "12.01",
+        y2: "17"
+    }));
+const Toolbar = ({ title, theme, onThemeChange, enableThemeToggle, enableFormat, onFormat, enableCompile, onCompile, enableFullscreen, isFullscreen, onToggleFullscreen, toolbar, toolbarExtra, description })=>{
     const isDark = 'dark' === theme;
+    const colors = themes[theme];
     const borderColor = isDark ? '#434343' : '#d9d9d9';
     const toolbarBg = isDark ? '#282c34' : '#fafafa';
     const toolbarText = isDark ? '#abb2bf' : '#333';
     const btnBg = isDark ? '#2c313a' : '#f0f0f0';
     const btnHoverBg = isDark ? '#3e4451' : '#e0e0e0';
+    const [showDesc, setShowDesc] = useState(false);
+    const [tipPos, setTipPos] = useState(null);
+    const descBtnRef = useRef(null);
+    const tipRef = useRef(null);
+    const updateTipPos = useCallback(()=>{
+        if (!descBtnRef.current) return;
+        setTipPos(calcTooltipPos(descBtnRef.current.getBoundingClientRect(), tipRef.current));
+    }, []);
+    useEffect(()=>{
+        if (!showDesc) return;
+        updateTipPos();
+        window.addEventListener('scroll', updateTipPos, true);
+        window.addEventListener('resize', updateTipPos);
+        return ()=>{
+            window.removeEventListener('scroll', updateTipPos, true);
+            window.removeEventListener('resize', updateTipPos);
+        };
+    }, [
+        showDesc,
+        updateTipPos
+    ]);
+    useEffect(()=>{
+        if (!showDesc) setTipPos(null);
+    }, [
+        showDesc
+    ]);
+    useEffect(()=>{
+        if (!description) setShowDesc(false);
+    }, [
+        description
+    ]);
+    const descLines = description ? description.replace(/\\n/g, '\n').split('\n').filter((l)=>l.trim()) : [];
     const handleThemeToggle = ()=>{
         const next = isDark ? 'light' : 'dark';
         onThemeChange?.(next);
@@ -64,33 +155,54 @@ const Toolbar = ({ title, theme, onThemeChange, enableThemeToggle, enableFormat,
         style: {
             marginRight: 'auto'
         }
-    }), enableThemeToggle && /*#__PURE__*/ react.createElement(ToolbarButton, {
+    }), descLines.length > 0 && /*#__PURE__*/ react.createElement("button", {
+        ref: descBtnRef,
+        onClick: ()=>setShowDesc((v)=>!v),
+        style: {
+            display: 'inline-flex',
+            alignItems: 'center',
+            gap: 4,
+            padding: '4px 10px',
+            borderRadius: 4,
+            border: `1px solid ${isDark ? '#2d5a27' : '#b7eb8f'}`,
+            background: showDesc ? isDark ? '#3a7033' : '#d4ecd3' : isDark ? '#2d5a27' : '#e6f4e5',
+            color: isDark ? '#98c379' : '#389e0d',
+            cursor: 'pointer',
+            fontSize: 12,
+            lineHeight: 1.4,
+            whiteSpace: 'nowrap',
+            transition: 'background 0.15s'
+        },
+        title: showDesc ? '隐藏脚本说明' : '查看脚本说明'
+    }, /*#__PURE__*/ react.createElement(QuestionIcon, {
+        color: "currentColor"
+    }), "脚本说明"), enableThemeToggle && /*#__PURE__*/ react.createElement(ToolbarButton, {
         label: isDark ? '🌞 浅色模式' : '🌙 深色模式',
         title: isDark ? '切换到浅色主题' : '切换到深色主题',
-        bg: btnBg,
-        hoverBg: btnHoverBg,
-        color: toolbarText,
-        border: borderColor,
+        backgroundColor: btnBg,
+        hoverBackgroundColor: btnHoverBg,
+        textColor: toolbarText,
+        borderColor: borderColor,
         onClick: handleThemeToggle
     }), enableFormat && onFormat && /*#__PURE__*/ react.createElement(ToolbarButton, {
         label: /*#__PURE__*/ react.createElement(react.Fragment, null, /*#__PURE__*/ react.createElement(FormatIcon, {
             color: isDark ? '#61afef' : '#1677ff'
         }), "格式化"),
         title: "格式化代码",
-        bg: isDark ? '#1e3a5f' : '#e6f4ff',
-        hoverBg: isDark ? '#264a73' : '#bae0ff',
-        color: isDark ? '#61afef' : '#1677ff',
-        border: isDark ? '#1e3a5f' : '#91caff',
+        backgroundColor: isDark ? '#1e3a5f' : '#e6f4ff',
+        hoverBackgroundColor: isDark ? '#264a73' : '#bae0ff',
+        textColor: isDark ? '#61afef' : '#1677ff',
+        borderColor: isDark ? '#1e3a5f' : '#91caff',
         onClick: onFormat
     }), enableCompile && onCompile && /*#__PURE__*/ react.createElement(ToolbarButton, {
         label: /*#__PURE__*/ react.createElement(react.Fragment, null, /*#__PURE__*/ react.createElement(HammerIcon, {
             color: isDark ? '#98c379' : '#389e0d'
         }), "编译验证"),
         title: "编译并验证脚本",
-        bg: isDark ? '#2d5a27' : '#e6f4e5',
-        hoverBg: isDark ? '#3a7033' : '#d4ecd3',
-        color: isDark ? '#98c379' : '#389e0d',
-        border: isDark ? '#2d5a27' : '#b7eb8f',
+        backgroundColor: isDark ? '#2d5a27' : '#e6f4e5',
+        hoverBackgroundColor: isDark ? '#3a7033' : '#d4ecd3',
+        textColor: isDark ? '#98c379' : '#389e0d',
+        borderColor: isDark ? '#2d5a27' : '#b7eb8f',
         onClick: onCompile
     }), enableFullscreen && /*#__PURE__*/ react.createElement(ToolbarButton, {
         label: /*#__PURE__*/ react.createElement(react.Fragment, null, isFullscreen ? /*#__PURE__*/ react.createElement(MinimizeIcon, {
@@ -99,11 +211,46 @@ const Toolbar = ({ title, theme, onThemeChange, enableThemeToggle, enableFormat,
             color: isDark ? '#c678dd' : '#722ed1'
         }), isFullscreen ? '退出全屏' : '全屏模式'),
         title: isFullscreen ? '退出全屏（ESC）' : '全屏显示',
-        bg: isDark ? '#3a2d5a' : '#f3e8ff',
-        hoverBg: isDark ? '#4a3d6a' : '#e9d5ff',
-        color: isDark ? '#c678dd' : '#722ed1',
-        border: isDark ? '#3a2d5a' : '#d3adf7',
+        backgroundColor: isDark ? '#3a2d5a' : '#f3e8ff',
+        hoverBackgroundColor: isDark ? '#4a3d6a' : '#e9d5ff',
+        textColor: isDark ? '#c678dd' : '#722ed1',
+        borderColor: isDark ? '#3a2d5a' : '#d3adf7',
         onClick: ()=>onToggleFullscreen?.()
-    }), toolbarExtra);
+    }), toolbar?.map((item)=>/*#__PURE__*/ react.createElement(ToolbarButton, {
+            key: item.key,
+            label: item.label,
+            title: item.title,
+            backgroundColor: item.backgroundColor,
+            hoverBackgroundColor: item.hoverBackgroundColor,
+            textColor: item.textColor,
+            borderColor: item.borderColor,
+            onClick: item.onClick
+        })), toolbarExtra, showDesc && tipPos && descLines.length > 0 && /*#__PURE__*/ react.createElement("div", {
+        ref: tipRef,
+        style: {
+            position: 'fixed',
+            top: tipPos.top,
+            left: tipPos.left,
+            maxWidth: tipPos.maxWidth,
+            maxHeight: tipPos.maxHeight,
+            overflowY: 'auto',
+            padding: '10px 14px',
+            background: colors.headerBg,
+            border: `1px solid ${colors.border}`,
+            borderRadius: 6,
+            color: colors.text,
+            fontSize: 12,
+            lineHeight: 1.65,
+            wordBreak: 'break-word',
+            zIndex: 9999,
+            boxShadow: '0 4px 16px rgba(0,0,0,0.3)',
+            pointerEvents: 'auto'
+        }
+    }, descLines.map((line, i)=>/*#__PURE__*/ react.createElement("div", {
+            key: i,
+            style: {
+                marginBottom: i < descLines.length - 1 ? 4 : 0
+            }
+        }, renderDescLine(line, colors.accent)))));
 };
 export { Toolbar };

package/dist/components/variables-section.js

@@ -3,21 +3,24 @@ import { SectionHeader } from "./section-header.js";
 import { VariableRow } from "./variable-row.js";
 const VariablesSection = ({ sortedBinds, sortedRequests, colors })=>{
     if (0 === sortedBinds.length && 0 === sortedRequests.length) return null;
-    return /*#__PURE__*/ react.createElement("div", null, /*#__PURE__*/ react.createElement(SectionHeader, {
+    return /*#__PURE__*/ react.createElement("div", null, sortedRequests.length > 0 && /*#__PURE__*/ react.createElement(react.Fragment, null, /*#__PURE__*/ react.createElement(SectionHeader, {
         colors: colors,
-        label: "变量"
+        label: "函数入参"
+    }), sortedRequests.map((req)=>/*#__PURE__*/ react.createElement(VariableRow, {
+            key: req.name,
+            name: req.name,
+            dataType: req.dataType,
+            description: req.description,
+            colors: colors
+        }))), sortedBinds.length > 0 && /*#__PURE__*/ react.createElement(react.Fragment, null, /*#__PURE__*/ react.createElement(SectionHeader, {
+        colors: colors,
+        label: "绑定参数"
     }), sortedBinds.map((bind)=>/*#__PURE__*/ react.createElement(VariableRow, {
             key: bind.name,
             name: bind.name,
             dataType: bind.dataType,
             description: bind.description,
             colors: colors
-        })), sortedRequests.map((req)=>/*#__PURE__*/ react.createElement(VariableRow, {
-            key: req.name,
-            name: req.name,
-            dataType: req.dataType,
-            description: req.description,
-            colors: colors
-        })));
+        }))));
 };
 export { VariablesSection };

package/dist/script-code.js

@@ -181,7 +181,7 @@ function buildLayoutExtensions(fontSize, minHeight, maxHeight, isFullscreen) {
     });
 }
 const ScriptCodeEditor = (props)=>{
-    const { value, readonly = false, onChange, onCompile, onFormat, onThemeChange, placeholder = '请输入 Groovy 脚本...', defaultTheme, title, metadata, defaultSidebarOpen, enableThemeToggle, enableFormat, enableCompile, enableFullscreen, toolbarExtra, options = {} } = props;
+    const { value, readonly = false, onChange, onCompile, onFormat, onThemeChange, placeholder = '请输入 Groovy 脚本...', defaultTheme, title, metadata, defaultSidebarOpen, enableThemeToggle, enableFormat, enableCompile, enableFullscreen, toolbar, toolbarExtra, options = {} } = props;
     const { fontSize = 14, minHeight = 300, maxHeight = 300 } = options;
     const [internalTheme, setInternalTheme] = useState(defaultTheme ?? 'dark');
     useEffect(()=>{
@@ -368,7 +368,9 @@ const ScriptCodeEditor = (props)=>{
         enableFullscreen: enableFullscreen,
         isFullscreen: isFullscreen,
         onToggleFullscreen: ()=>setIsFullscreen((prev)=>!prev),
-        toolbarExtra: toolbarExtra
+        toolbar: toolbar,
+        toolbarExtra: toolbarExtra,
+        description: metadata?.description
     }), /*#__PURE__*/ react.createElement("div", {
         style: {
             display: 'flex',

package/dist/types/index.d.ts

@@ -1,4 +1,26 @@
 import type React from 'react';
+/** 工具栏按钮属性 */
+export interface ToolbarButtonProps {
+    /** 按钮内容（支持 ReactNode，可包含图标 + 文字） */
+    label: React.ReactNode;
+    /** 鼠标悬停提示文字（原生 title 属性） */
+    title: string;
+    /** 按钮背景色 */
+    backgroundColor: string;
+    /** 鼠标悬停时的背景色 */
+    hoverBackgroundColor: string;
+    /** 文字颜色 */
+    textColor: string;
+    /** 边框颜色 */
+    borderColor: string;
+    /** 点击回调 */
+    onClick: () => void;
+}
+/** 工具栏自定义按钮项（用于 toolbar 数组） */
+export interface ToolbarItem extends ToolbarButtonProps {
+    /** 唯一标识（React key） */
+    key: string;
+}
 /** 函数参数信息 */
 export interface ScriptParameterInfo {
     dataType: string;
@@ -41,7 +63,8 @@ export interface ScriptRequestInfo {
 export interface ScriptMetadata {
     binds: ScriptBindInfo[];
     requests: ScriptRequestInfo[];
-    mainMethod: string;
+    description?: string;
+    mainMethod?: string;
     returnType?: string;
     types: Record<string, ScriptTypeInfo>;
 }
@@ -76,6 +99,8 @@ export interface ScriptCodeEditorProps {
     onFormat?: () => void;
     /** 编译/测试脚本回调（enableCompile 时需提供） */
     onCompile?: (code: string) => void;
+    /** 工具栏自定义按钮列表（渲染在内置按钮之后） */
+    toolbar?: ToolbarItem[];
     /** 工具栏额外内容（渲染在内置按钮之后，任意 React 节点） */
     toolbarExtra?: React.ReactNode;
     /** 其他选项 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coding-script/script-engine",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "script-engine components",
   "keywords": [
     "coding-script",