@lark-apaas/fullstack-presets 1.1.7 → 1.1.9

package/lib/custom-eslint-rules/index.d.ts

@@ -2,4 +2,5 @@ export declare const customRules: {
     'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
     'require-app-container': import("eslint").Rule.RuleModule;
     'no-direct-capability-api': import("eslint").Rule.RuleModule;
+    'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
 };

package/lib/custom-eslint-rules/index.js

@@ -7,8 +7,10 @@ exports.customRules = void 0;
 const no_nested_styled_jsx_1 = __importDefault(require("./no-nested-styled-jsx"));
 const require_app_container_1 = __importDefault(require("./require-app-container"));
 const no_direct_capability_api_1 = __importDefault(require("./no-direct-capability-api"));
+const require_scroll_reveal_hook_1 = __importDefault(require("./require-scroll-reveal-hook"));
 exports.customRules = {
     'no-nested-styled-jsx': no_nested_styled_jsx_1.default,
     'require-app-container': require_app_container_1.default,
     'no-direct-capability-api': no_direct_capability_api_1.default,
+    'require-scroll-reveal-hook': require_scroll_reveal_hook_1.default,
 };

package/lib/custom-eslint-rules/require-scroll-reveal-hook.d.ts

@@ -0,0 +1,17 @@
+/**
+ * ESLint 规则：使用 scroll-reveal 样式类时必须调用 useScrollReveal hook
+ *
+ * 此规则确保开发者在使用 scroll-reveal 滚动动画样式时，
+ * 正确导入并调用 useScrollReveal hook 来启用动画效果。
+ *
+ * 错误示例：
+ *   <div className="scroll-reveal">Content</div>  // 未使用 hook
+ *
+ * 正确示例：
+ *   import { useScrollReveal } from '@lark-apaas/client-toolkit/hooks/useScrollReveal';
+ *   useScrollReveal();  // 无需参数，默认监听整个页面
+ *   return <div className="scroll-reveal">Content</div>
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/require-scroll-reveal-hook.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const DEFAULT_MESSAGE = "Elements with 'scroll-reveal' class require the useScrollReveal hook. " +
+    "Import and call useScrollReveal() from '@lark-apaas/client-toolkit/hooks/useScrollReveal'.";
+// 匹配 className 中的 scroll-reveal 类
+const SCROLL_REVEAL_PATTERN = /(^|\s)scroll-reveal(\s|$)/;
+// Hook 相关常量
+const HOOK_NAME = 'useScrollReveal';
+const HOOK_IMPORT_SOURCE = '@lark-apaas/client-toolkit/hooks/useScrollReveal';
+/**
+ * 从 AST 节点中提取 className 字符串值
+ * 支持：字符串字面量、模板字符串、字符串拼接、JSX 表达式容器
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function extractClassNameValue(node) {
+    if (!node)
+        return null;
+    switch (node.type) {
+        case 'Literal':
+            return typeof node.value === 'string' ? node.value : null;
+        case 'TemplateLiteral':
+            // 拼接所有静态部分（quasis）
+            return node.quasis
+                .map((q) => q.value.raw)
+                .join('');
+        case 'BinaryExpression':
+            // 处理字符串拼接 'a' + 'b'
+            if (node.operator === '+') {
+                const left = extractClassNameValue(node.left);
+                const right = extractClassNameValue(node.right);
+                if (left !== null || right !== null) {
+                    return (left || '') + (right || '');
+                }
+            }
+            return null;
+        case 'JSXExpressionContainer':
+            return extractClassNameValue(node.expression);
+        default:
+            return null;
+    }
+}
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: '使用 scroll-reveal 样式类时必须导入并调用 useScrollReveal hook',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    message: {
+                        type: 'string',
+                        description: '自定义错误信息',
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            requireScrollRevealHook: DEFAULT_MESSAGE,
+        },
+    },
+    create(context) {
+        const options = context.options[0];
+        const customMessage = options?.message;
+        // 文件级别的状态追踪
+        let hasScrollRevealClass = false;
+        let hasHookImport = false;
+        let hasHookCall = false;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let scrollRevealNodes = []; // 保存有 scroll-reveal 的节点用于报错定位
+        return {
+            // 检测 JSX 中的 className 属性
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXAttribute(node) {
+                if (node.name?.name !== 'className')
+                    return;
+                const classValue = extractClassNameValue(node.value);
+                if (classValue && SCROLL_REVEAL_PATTERN.test(classValue)) {
+                    hasScrollRevealClass = true;
+                    scrollRevealNodes.push(node);
+                }
+            },
+            // 检测 useScrollReveal 导入
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ImportDeclaration(node) {
+                const source = node.source?.value;
+                if (typeof source !== 'string')
+                    return;
+                // 检查是否从正确的源导入
+                if (source === HOOK_IMPORT_SOURCE ||
+                    source.includes('useScrollReveal')) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const hasHookSpecifier = node.specifiers?.some((spec) => {
+                        if (spec.type === 'ImportSpecifier') {
+                            return spec.imported?.name === HOOK_NAME;
+                        }
+                        if (spec.type === 'ImportDefaultSpecifier') {
+                            return spec.local?.name === HOOK_NAME;
+                        }
+                        return false;
+                    });
+                    if (hasHookSpecifier) {
+                        hasHookImport = true;
+                    }
+                }
+            },
+            // 检测 useScrollReveal 调用
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            CallExpression(node) {
+                if (node.callee?.name === HOOK_NAME) {
+                    hasHookCall = true;
+                }
+            },
+            // 文件遍历结束时进行检查
+            'Program:exit'() {
+                // 只有在使用了 scroll-reveal 类但未正确设置 hook 时报错
+                if (hasScrollRevealClass && (!hasHookImport || !hasHookCall)) {
+                    // 在第一个使用 scroll-reveal 的节点上报错，提供更好的开发体验
+                    const reportNode = scrollRevealNodes[0];
+                    context.report({
+                        node: reportNode,
+                        ...(customMessage
+                            ? { message: customMessage }
+                            : { messageId: 'requireScrollRevealHook' }),
+                    });
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

package/lib/recommend/eslint/eslint-client.d.ts

@@ -18,6 +18,7 @@ declare const _default: {
                 'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
                 'require-app-container': import("eslint").Rule.RuleModule;
                 'no-direct-capability-api': import("eslint").Rule.RuleModule;
+                'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
             };
         };
     };

package/lib/recommend/eslint/eslint-client.js

@@ -56,6 +56,8 @@ exports.default = {
         'no-undef': 'off', // 禁止使用未声明的变量
         'no-console': 'off', // 允许使用 console
         'prefer-const': 'off', // 不强制使用 const
+        'no-case-declarations': 'off', // 允许在 case 块中使用词法声明
+        'no-empty': 'off', // 允许空的 catch 块
         // Import 规则
         'import/no-unresolved': 'error', // 检查导入路径是否存在
         // 其他规则
@@ -112,35 +114,36 @@ exports.default = {
                 selector: 'AssignmentExpression[left.object.name="location"][left.property.name="href"]',
                 message: "Please don't use `location.href` to navigate. Use `useNavigate` hook from 'react-router-dom' instead.",
             },
-            // SelectItem组件的value属性值不能为空字符串
-            {
-                message: 'The `value` attribute of the `SelectItem` component cannot be an empty string.',
-                selector: 'JSXOpeningElement[name.name="SelectItem"]:has(JSXAttribute[name.name="value"][value.value=""]), JSXOpeningElement[name.name="SelectItem"]:has(JSXAttribute[name.name="value"][value.expression.value=""])',
-            },
             // 禁止a标签href使用相对路径
             {
                 selector: "JSXOpeningElement[name.name='a']:has(JSXAttribute[name.name='href'][value.value=/^(?!https?:|\\u002F\\u002F|mailto:|tel:|#).+/])",
                 message: "Please don't use relative paths in <a> tags. Use NavLink from 'react-router-dom' instead.",
             },
             // 禁止 variant 为 outline|link|ghost 的 Button 使用 text-white
-            {
-                selector: 'JSXElement[openingElement.name.name="Button"]' +
-                    ':has(JSXAttribute[name.name="variant"][value.value=/^(outline|link|ghost)$/])' +
-                    ':has(JSXAttribute[name.name="className"][value.value=/text-white/])',
-                message: 'Button with variant="outline|link|ghost" should not use "text-white" className. This causes visibility issues. Consider using proper semantic color tokens from `client/src/tailwind-theme.css`',
-            },
-            // 禁止在 Button 上组合 text-primary-foreground 与 bg-background 并用的情况
-            {
-                selector: 'JSXElement[openingElement.name.name="Button"]' +
-                    ':has(JSXAttribute[name.name="className"][value.value=/text-primary-foreground/])' +
-                    ':has(JSXAttribute[name.name="className"][value.value=/bg-background/])',
-                message: 'Button should not use "text-primary-foreground" and "bg-background" className. This causes visibility issues. Consider using proper semantic color tokens from `client/src/tailwind-theme.css`',
-            },
-            // 禁止使用 text-accent
-            {
-                selector: 'JSXAttribute[name.name="className"][value.value=/(^|\\s)text-accent(\\s|$)/]',
-                message: 'Classname "text-accent" would cause visibility issues. Consider using proper semantic color tokens from `client/src/tailwind-theme.css`',
-            },
+            // {
+            //   selector: 
+            //     'JSXElement[openingElement.name.name="Button"]' +
+            //     ':has(JSXAttribute[name.name="variant"][value.value=/^(outline|link|ghost)$/])' +
+            //     ':has(JSXAttribute[name.name="className"][value.value=/text-white/])',
+            //   message: 
+            //     'Button with variant="outline|link|ghost" should not use "text-white" className. This causes visibility issues. Consider using proper semantic color tokens from `client/src/tailwind-theme.css`',
+            // },
+            // // 禁止在 Button 上组合 text-primary-foreground 与 bg-background 并用的情况
+            // {
+            //   selector: 
+            //     'JSXElement[openingElement.name.name="Button"]' +
+            //     ':has(JSXAttribute[name.name="className"][value.value=/text-primary-foreground/])' + 
+            //     ':has(JSXAttribute[name.name="className"][value.value=/bg-background/])',
+            //   message: 
+            //     'Button should not use "text-primary-foreground" and "bg-background" className. This causes visibility issues. Consider using proper semantic color tokens from `client/src/tailwind-theme.css`',
+            // },
+            // // 禁止使用 text-accent
+            // {
+            //   selector:
+            //     'JSXAttribute[name.name="className"][value.value=/(^|\\s)text-accent(\\s|$)/]',
+            //   message:
+            //     'Classname "text-accent" would cause visibility issues. Consider using proper semantic color tokens from `client/src/tailwind-theme.css`',
+            // },
             // 禁止在 Tailwind 任意值语法中使用包含空格的 hsl/rgb 值
             {
                 selector: 'JSXAttribute[name.name="className"][value.value=/\\[hsl\\([^\\]]*\\s[^\\]]*\\)/]',

package/lib/recommend/eslint/index.d.ts

@@ -21,6 +21,7 @@ export declare const eslintPresets: {
                     'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
                     'require-app-container': import("eslint").Rule.RuleModule;
                     'no-direct-capability-api': import("eslint").Rule.RuleModule;
+                    'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
                 };
             };
         };

package/lib/simple/recommend/eslint/eslint-client.d.ts

@@ -20,6 +20,7 @@ declare const _default: ({
                 'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
                 'require-app-container': import("eslint").Rule.RuleModule;
                 'no-direct-capability-api': import("eslint").Rule.RuleModule;
+                'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
             };
         };
         'react-hooks': any;

package/lib/simple/recommend/eslint/eslint-client.js

@@ -5,9 +5,27 @@ const globals = require('globals');
 const reactHooks = require('eslint-plugin-react-hooks');
 const tseslint = require('typescript-eslint');
 const importPlugin = require('eslint-plugin-import');
+const fs = require('fs');
+const path = require('path');
 const custom_eslint_rules_1 = require("../../../custom-eslint-rules");
 // 检查是否启用宽松 lint 模式
 const isLooseMode = process.env.FORCE_FRAMEWORK_LINT_LOOSE_MODE === 'true';
+// 读取项目 package.json 中的 flags 配置
+function getProjectFlags() {
+    try {
+        const pkgPath = path.resolve(process.cwd(), 'package.json');
+        if (fs.existsSync(pkgPath)) {
+            const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+            return pkg.flags || {};
+        }
+    }
+    catch {
+        // ignore errors
+    }
+    return {};
+}
+const projectFlags = getProjectFlags();
+const supportScrollReveal = projectFlags.supportScrollReveal === true;
 // 基础语法规则：所有模式都启用（包括 loose 模式）
 const baseSyntaxRules = [
     // SelectItem组件的value属性值不能为空字符串
@@ -106,12 +124,16 @@ const strictSyntaxRules = [
 const looseSpecificPlugins = {
     '@lark-apaas': { rules: custom_eslint_rules_1.customRules },
 };
-// 宽松模式下覆盖的规则（关闭非关键规则）
+// 宽松模式下覆盖的规则
 const looseOverrideRules = isLooseMode
     ? {
         '@typescript-eslint/no-unsafe-function-type': 'off',
         '@typescript-eslint/no-unused-expressions': 'off',
         'no-useless-escape': 'off', // 允许不必要的转义字符
+        // 使用 scroll-reveal 样式类时必须调用 useScrollReveal()（需 flags.supportScrollReveal 为 true）
+        '@lark-apaas/require-scroll-reveal-hook': supportScrollReveal
+            ? 'error'
+            : 'off',
     }
     : {};
 // 基础配置（适用于所有文件）

package/lib/simple/recommend/eslint/index.d.ts

@@ -19,6 +19,7 @@ export declare const eslintPresets: {
                     'no-nested-styled-jsx': import("eslint").Rule.RuleModule;
                     'require-app-container': import("eslint").Rule.RuleModule;
                     'no-direct-capability-api': import("eslint").Rule.RuleModule;
+                    'require-scroll-reveal-hook': import("eslint").Rule.RuleModule;
                 };
             };
             'react-hooks': any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-presets",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "files": [
     "lib"
   ],