@lark-apaas/fullstack-presets 1.1.8 → 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/no-welcome-index-route.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ESLint rule to disallow Welcome or PagePlaceholder components as the default home page route.
+ *
+ * This rule enforces that the first-level index route (the actual home page at "/")
+ * should use an actual page component rather than placeholder components from the framework.
+ *
+ * Only checks the first-level index route nested directly under a parent Route (typically Layout).
+ * Only flags Welcome/PagePlaceholder if they are imported from @lark-apaas/client-toolkit.
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/lib/custom-eslint-rules/no-welcome-index-route.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow Welcome or PagePlaceholder from @lark-apaas/client-toolkit as the default home page route element',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            noWelcomeIndex: 'Index route should not use {{componentName}} from @lark-apaas/client-toolkit as the element. Please create and use your own home page component (e.g., HomePage, Dashboard).',
+        },
+        schema: [],
+    },
+    create(context) {
+        // Track imports from @lark-apaas/client-toolkit
+        const toolkitImports = new Set();
+        return {
+            ImportDeclaration(node) {
+                const importNode = node;
+                const source = importNode.source?.value;
+                // Check if importing from @lark-apaas/client-toolkit (any subpath)
+                if (typeof source === 'string' &&
+                    source.startsWith('@lark-apaas/client-toolkit')) {
+                    // Collect all imported names
+                    importNode.specifiers?.forEach(specifier => {
+                        if (specifier.type === 'ImportSpecifier' &&
+                            specifier.imported?.name) {
+                            toolkitImports.add(specifier.imported.name);
+                        }
+                    });
+                }
+            },
+            JSXElement(node) {
+                const element = node;
+                const openingElement = element.openingElement;
+                if (!openingElement)
+                    return;
+                const elementName = openingElement.name;
+                // Check if this is a <Route> element
+                if (elementName.type !== 'JSXIdentifier' ||
+                    elementName.name !== 'Route') {
+                    return;
+                }
+                // Check if it has an index prop that is truthy
+                const indexAttr = openingElement.attributes.find(attr => attr.type === 'JSXAttribute' &&
+                    attr.name?.type === 'JSXIdentifier' &&
+                    attr.name?.name === 'index');
+                // If no index attribute, skip this route
+                if (!indexAttr) {
+                    return;
+                }
+                // Check if index={false} explicitly
+                const indexValue = indexAttr.value;
+                if (indexValue?.type === 'JSXExpressionContainer' &&
+                    indexValue.expression?.type === 'Literal' &&
+                    indexValue.expression.value === false) {
+                    return;
+                }
+                // Check if this is a first-level index route (nested under exactly one parent Route)
+                // The structure should be: <Routes> -> <Route element={<Layout />}> -> <Route index>
+                let routeParentCount = 0;
+                let current = element.parent;
+                while (current) {
+                    if (current.type === 'JSXElement') {
+                        const currentElement = current;
+                        const currentOpeningElement = currentElement.openingElement;
+                        const currentElementName = currentOpeningElement?.name;
+                        if (currentElementName?.type === 'JSXIdentifier' &&
+                            currentElementName.name === 'Route') {
+                            routeParentCount++;
+                        }
+                        else if (currentElementName?.type === 'JSXIdentifier' &&
+                            currentElementName.name === 'Routes') {
+                            // Stop when we reach Routes
+                            break;
+                        }
+                    }
+                    current = current.parent;
+                }
+                // Only check if this is a first-level route (exactly 1 parent Route)
+                // This corresponds to the default home page pattern:
+                // <Routes><Route element={<Layout />}><Route index /></Route></Routes>
+                if (routeParentCount !== 1) {
+                    return;
+                }
+                // Find the element prop
+                const elementProp = openingElement.attributes.find(attr => attr.type === 'JSXAttribute' &&
+                    attr.name?.type === 'JSXIdentifier' &&
+                    attr.name?.name === 'element');
+                if (!elementProp) {
+                    return;
+                }
+                // Check if the element prop value is a JSXExpressionContainer with a JSXElement
+                const propValue = elementProp.value;
+                if (propValue?.type === 'JSXExpressionContainer' &&
+                    propValue.expression?.type === 'JSXElement') {
+                    const jsxElement = propValue.expression;
+                    const jsxOpeningElement = jsxElement.openingElement;
+                    const jsxElementName = jsxOpeningElement?.name;
+                    // Check if the component name is Welcome or PagePlaceholder
+                    if (jsxElementName?.type === 'JSXIdentifier' &&
+                        (jsxElementName.name === 'Welcome' ||
+                            jsxElementName.name === 'PagePlaceholder')) {
+                        const componentName = jsxElementName.name;
+                        // Only report if this component was imported from @lark-apaas/client-toolkit
+                        if (toolkitImports.has(componentName)) {
+                            context.report({
+                                node: elementProp,
+                                messageId: 'noWelcomeIndex',
+                                data: {
+                                    componentName,
+                                },
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

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

@@ -0,0 +1,14 @@
+/**
+ * ESLint rule to require a default index route in RoutesComponent.
+ *
+ * This rule enforces that the RoutesComponent must have a first-level index route
+ * to handle the default "/" path. This ensures users don't see a 404 when visiting
+ * the application root.
+ *
+ * Valid configurations:
+ * 1. <Route index element={...} /> (first-level, nested under one parent Route)
+ * 2. <Route path="/" element={...} /> (first-level or top-level)
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

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

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const rule = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Require a default index route in RoutesComponent to handle the root path',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            missingIndexRoute: 'RoutesComponent is missing a default home page route. Add either:\n  - <Route index element={<HomePage />} /> (nested under Layout)\n  - <Route path="/" element={<HomePage />} /> (at any level)',
+        },
+        schema: [],
+    },
+    create(context) {
+        let inRoutesComponent = false;
+        let hasDefaultRoute = false;
+        let routeDepth = 0;
+        return {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            VariableDeclarator(node) {
+                // Check if this is RoutesComponent
+                if (node.id?.name === 'RoutesComponent') {
+                    inRoutesComponent = true;
+                    hasDefaultRoute = false;
+                    routeDepth = 0;
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'VariableDeclarator:exit'(node) {
+                if (node.id?.name === 'RoutesComponent') {
+                    if (!hasDefaultRoute) {
+                        context.report({
+                            node,
+                            messageId: 'missingIndexRoute',
+                        });
+                    }
+                    inRoutesComponent = false;
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            JSXElement(node) {
+                if (!inRoutesComponent)
+                    return;
+                const elementName = node.openingElement?.name?.name;
+                // Track Route depth
+                if (elementName === 'Route') {
+                    routeDepth++;
+                    // Only check first-level routes (depth 1 or 2)
+                    // depth 1: <Routes><Route index /></Routes>
+                    // depth 2: <Routes><Route><Route index /></Route></Routes>
+                    if (routeDepth <= 2) {
+                        const attributes = node.openingElement?.attributes || [];
+                        // Check for index attribute
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const indexAttr = attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'index');
+                        if (indexAttr) {
+                            // Make sure it's not index={false}
+                            const isIndexFalse = indexAttr.value?.type === 'JSXExpressionContainer' &&
+                                indexAttr.value.expression?.type === 'Literal' &&
+                                indexAttr.value.expression.value === false;
+                            if (!isIndexFalse) {
+                                hasDefaultRoute = true;
+                            }
+                        }
+                        // Check for path="/"
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const pathAttr = attributes.find((attr) => attr.type === 'JSXAttribute' && attr.name?.name === 'path');
+                        if (pathAttr) {
+                            const value = pathAttr.value;
+                            // Handle path="/"
+                            if (value?.type === 'Literal' && value.value === '/') {
+                                hasDefaultRoute = true;
+                            }
+                            // Handle path={"/"}
+                            if (value?.type === 'JSXExpressionContainer' &&
+                                value.expression?.type === 'Literal' &&
+                                value.expression.value === '/') {
+                                hasDefaultRoute = true;
+                            }
+                        }
+                    }
+                }
+            },
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            'JSXElement:exit'(node) {
+                if (!inRoutesComponent)
+                    return;
+                const elementName = node.openingElement?.name?.name;
+                if (elementName === 'Route') {
+                    routeDepth--;
+                }
+            },
+        };
+    },
+};
+exports.default = rule;

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/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.8",
+  "version": "1.1.9",
   "files": [
     "lib"
   ],