@lark-apaas/fullstack-presets 1.1.11 → 1.1.12

package/lib/custom-stylelint-rules/hsl-variable.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 自定义 Stylelint 规则：校验 CSS 声明中非法的 hsl() 写法
+ *
+ * 遍历所有 CSS 声明（包括自定义属性 --*），当值以 hsl()/hsla() 开头时，
+ * 使用 css-tree 的词法器验证其是否符合 CSS color 规范。
+ *
+ * 注意：只处理纯颜色值声明，不处理复合值（如 box-shadow、background 等）中的 hsl()。
+ *
+ * 非法示例：
+ *   --color: hsl(100%, 50%, 26%);      // hue 不能是百分比
+ *   --color: hsl(200 50% 26% 0.5);     // alpha 缺少斜杠
+ *   --color: hsl(200 50%);             // 缺少 lightness
+ *   color: hsl();                      // 空参数
+ *
+ * 合法示例：
+ *   --color: hsl(200, 50%, 26%);       // CSS3 逗号写法
+ *   --color: hsl(200 50% 26%);         // CSS4 空格写法
+ *   --color: hsl(200deg 50% 26%);      // 带单位的 hue
+ *   --color: hsl(200 50% 26% / 0.5);   // CSS4 带 alpha
+ *
+ * 跳过（不检查）的示例：
+ *   --shadow: 0px 2px 12px hsl(0 0% 0% / 0.01);  // 复合值中的 hsl
+ *   background: linear-gradient(hsl(...), ...);  // 复合值中的 hsl
+ */
+import stylelint from 'stylelint';
+export declare const ruleName = "custom/hsl-valid-value";
+export declare const messages: {
+    invalidHsl: (value: string) => string;
+};
+export declare const meta: {
+    url: string;
+};
+declare const _default: stylelint.Plugin;
+export default _default;

package/lib/custom-stylelint-rules/hsl-variable.js

@@ -0,0 +1,116 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.meta = exports.messages = exports.ruleName = void 0;
+/**
+ * 自定义 Stylelint 规则：校验 CSS 声明中非法的 hsl() 写法
+ *
+ * 遍历所有 CSS 声明（包括自定义属性 --*），当值以 hsl()/hsla() 开头时，
+ * 使用 css-tree 的词法器验证其是否符合 CSS color 规范。
+ *
+ * 注意：只处理纯颜色值声明，不处理复合值（如 box-shadow、background 等）中的 hsl()。
+ *
+ * 非法示例：
+ *   --color: hsl(100%, 50%, 26%);      // hue 不能是百分比
+ *   --color: hsl(200 50% 26% 0.5);     // alpha 缺少斜杠
+ *   --color: hsl(200 50%);             // 缺少 lightness
+ *   color: hsl();                      // 空参数
+ *
+ * 合法示例：
+ *   --color: hsl(200, 50%, 26%);       // CSS3 逗号写法
+ *   --color: hsl(200 50% 26%);         // CSS4 空格写法
+ *   --color: hsl(200deg 50% 26%);      // 带单位的 hue
+ *   --color: hsl(200 50% 26% / 0.5);   // CSS4 带 alpha
+ *
+ * 跳过（不检查）的示例：
+ *   --shadow: 0px 2px 12px hsl(0 0% 0% / 0.01);  // 复合值中的 hsl
+ *   background: linear-gradient(hsl(...), ...);  // 复合值中的 hsl
+ */
+const stylelint_1 = __importDefault(require("stylelint"));
+const csstree = __importStar(require("css-tree"));
+exports.ruleName = 'custom/hsl-valid-value';
+const { report, ruleMessages, validateOptions } = stylelint_1.default.utils;
+exports.messages = ruleMessages(exports.ruleName, {
+    invalidHsl: (value) => `Invalid hsl() value: "${value}". Refer to https://developer.mozilla.org/docs/Web/CSS/color_value/hsl`,
+});
+exports.meta = {
+    url: 'https://github.com/csstree/stylelint-validator',
+};
+const rule = primary => {
+    return (root, result) => {
+        const validOptions = validateOptions(result, exports.ruleName, {
+            actual: primary,
+            possible: [true],
+        });
+        if (!validOptions || !primary)
+            return;
+        root.walkDecls(decl => {
+            const value = decl.value.trim();
+            // 只处理纯 hsl/hsla 颜色值，跳过复合值（如 box-shadow）
+            if (!/^hsla?\(/i.test(value))
+                return;
+            try {
+                const ast = csstree.parse(value, { context: 'value' });
+                const matchResult = csstree.lexer.matchType('color', ast);
+                if (matchResult.error) {
+                    report({
+                        message: exports.messages.invalidHsl(value),
+                        node: decl,
+                        result,
+                        ruleName: exports.ruleName,
+                        word: value,
+                    });
+                }
+            }
+            catch {
+                // css-tree parse 失败也视为非法值
+                report({
+                    message: exports.messages.invalidHsl(value),
+                    node: decl,
+                    result,
+                    ruleName: exports.ruleName,
+                    word: value,
+                });
+            }
+        });
+    };
+};
+rule.ruleName = exports.ruleName;
+rule.messages = exports.messages;
+rule.meta = exports.meta;
+exports.default = stylelint_1.default.createPlugin(exports.ruleName, rule);

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

@@ -59,7 +59,7 @@ exports.default = {
         'no-case-declarations': 'off', // 允许在 case 块中使用词法声明
         'no-empty': 'off', // 允许空的 catch 块
         // Import 规则
-        'import/no-unresolved': 'error', // 检查导入路径是否存在
+        'import/no-unresolved': ['error', { ignore: ['\\?raw$'] }], // 检查导入路径是否存在，忽略 ?raw 查询参数
         // 其他规则
         'no-constant-binary-expression': 'off', // 不强制使用常量二进制表达式
         // React Refresh 相关 - 开发时不影响渲染的检测

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

@@ -1,5 +1,7 @@
 export declare const stylelintPresets: {
+    plugins: import("stylelint").Plugin[];
     rules: {
         'declaration-block-no-duplicate-custom-properties': boolean;
+        "custom/hsl-valid-value": true | null;
     };
 };

package/lib/recommend/stylelint/index.js

@@ -1,8 +1,45 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stylelintPresets = void 0;
+const hsl_variable_1 = __importStar(require("../../custom-stylelint-rules/hsl-variable"));
+const isLooseMode = process.env.FORCE_FRAMEWORK_LINT_LOOSE_MODE === 'true';
 exports.stylelintPresets = {
+    plugins: [hsl_variable_1.default],
     rules: {
         'declaration-block-no-duplicate-custom-properties': true,
+        [hsl_variable_1.ruleName]: isLooseMode || null,
     },
 };

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

@@ -186,7 +186,7 @@ const baseConfig = {
         'no-useless-escape': 'off',
         'no-case-declarations': 'off',
         // Import 规则
-        'import/no-unresolved': 'error', // 检查导入路径是否存在
+        'import/no-unresolved': ['error', { ignore: ['\\?raw$'] }], // 检查导入路径是否存在，忽略 ?raw 查询参数
         // 其他规则
         'no-constant-binary-expression': 'off', // 不强制使用常量二进制表达式
         // React Refresh 相关 - 开发时不影响渲染的检测

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

@@ -1,5 +1,7 @@
 export declare const stylelintPresets: {
+    plugins: import("stylelint").Plugin[];
     rules: {
         'declaration-block-no-duplicate-custom-properties': boolean;
+        "custom/hsl-valid-value": true | null;
     };
 };

package/lib/simple/recommend/stylelint/index.js

@@ -1,8 +1,45 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stylelintPresets = void 0;
+const hsl_variable_1 = __importStar(require("../../../custom-stylelint-rules/hsl-variable"));
+const isLooseMode = process.env.FORCE_FRAMEWORK_LINT_LOOSE_MODE === 'true';
 exports.stylelintPresets = {
+    plugins: [hsl_variable_1.default],
     rules: {
         'declaration-block-no-duplicate-custom-properties': true,
+        [hsl_variable_1.ruleName]: isLooseMode || null,
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-presets",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "files": [
     "lib"
   ],
@@ -26,21 +26,25 @@
     "@eslint/js": "^9.35.0",
     "@types/node": "^22.19.1",
     "@types/styled-jsx": "^2.2.9",
+    "css-tree": "^3.1.0",
     "eslint-import-resolver-alias": "^1.1.2",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^5.2.0",
     "globals": "^16.4.0",
+    "stylelint": "^17.3.0",
     "tailwindcss-animate": "^1.0.7"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",
     "@babel/preset-react": "^7.24.0",
+    "@types/css-tree": "^2.3.11",
     "@types/eslint": "^9.6.0",
     "eslint": "^9.35.0",
     "styled-jsx": "^5.1.6",
     "typescript": "^5.9.2",
-    "typescript-eslint": "^8.44.0"
+    "typescript-eslint": "^8.44.0",
+    "vitest": "^2.0.0"
   },
   "peerDependencies": {
     "eslint": "^9.0.0",

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

@@ -1,12 +0,0 @@
-/**
- * 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

@@ -1,123 +0,0 @@
-"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

@@ -1,14 +0,0 @@
-/**
- * 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

@@ -1,98 +0,0 @@
-"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;