@lark-apaas/fullstack-presets 1.1.5-beta.20 → 1.1.5-beta.22

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-stylelint-rules/hsl-variable.d.ts

@@ -21,6 +21,13 @@
  * 跳过（不检查）的示例：
  *   --shadow: 0px 2px 12px hsl(0 0% 0% / 0.01);  // 复合值中的 hsl
  *   background: linear-gradient(hsl(...), ...);  // 复合值中的 hsl
+ *   --border: hsl(from hsl(217 80% 55%) h s calc(l + var(--x)));  // CSS Color Level 5 相对颜色语法
+ *   --color: hsl(none 50% 26%);                  // none 关键字（CSS Color Level 4）
+ *
+ * var() 通道的处理：
+ *   对每个 var() 独立尝试占位符 0 和 0%（hue 位置需要数字，sat/light 位置需要百分比），
+ *   穷举所有 2^n 组合，只要存在一种合法结构就认为该写法合法。
+ *   这样可以在不误报合法写法的前提下，仍然捕获结构性错误（如缺少参数）。
  */
 import stylelint from 'stylelint';
 export declare const ruleName = "custom/hsl-valid-value";

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

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.meta = exports.messages = exports.ruleName = void 0;
+// @ts-nocheck
 /**
  * 自定义 Stylelint 规则：校验 CSS 声明中非法的 hsl() 写法
  *
@@ -60,6 +61,13 @@ exports.meta = exports.messages = exports.ruleName = void 0;
  * 跳过（不检查）的示例：
  *   --shadow: 0px 2px 12px hsl(0 0% 0% / 0.01);  // 复合值中的 hsl
  *   background: linear-gradient(hsl(...), ...);  // 复合值中的 hsl
+ *   --border: hsl(from hsl(217 80% 55%) h s calc(l + var(--x)));  // CSS Color Level 5 相对颜色语法
+ *   --color: hsl(none 50% 26%);                  // none 关键字（CSS Color Level 4）
+ *
+ * var() 通道的处理：
+ *   对每个 var() 独立尝试占位符 0 和 0%（hue 位置需要数字，sat/light 位置需要百分比），
+ *   穷举所有 2^n 组合，只要存在一种合法结构就认为该写法合法。
+ *   这样可以在不误报合法写法的前提下，仍然捕获结构性错误（如缺少参数）。
  */
 const stylelint_1 = __importDefault(require("stylelint"));
 const csstree = __importStar(require("css-tree"));
@@ -71,6 +79,65 @@ exports.messages = ruleMessages(exports.ruleName, {
 exports.meta = {
     url: 'https://github.com/csstree/stylelint-validator',
 };
+/**
+ * 提取字符串中所有顶层 var() 的位置和长度，使用括号计数支持任意深度嵌套。
+ * 例如 var(--a, var(--b, var(--c, 0))) 会被作为一个整体提取。
+ */
+function extractVarRanges(value) {
+    const ranges = [];
+    const varStart = /var\s*\(/gi;
+    let m;
+    while ((m = varStart.exec(value)) !== null) {
+        let depth = 1;
+        let j = m.index + m[0].length;
+        while (j < value.length && depth > 0) {
+            if (value[j] === '(')
+                depth++;
+            else if (value[j] === ')')
+                depth--;
+            j++;
+        }
+        ranges.push({ index: m.index, length: j - m.index });
+        varStart.lastIndex = j; // 跳过已处理的 var()，避免重复匹配内层
+    }
+    return ranges;
+}
+/**
+ * 对 hsl() 值中的每个 var() 分别尝试占位符 "0" 和 "0%"，
+ * 穷举 2^n 种组合，只要任意一种通过 css-tree 词法验证就返回 true。
+ *
+ * 背景：css-tree 不能解析 var()，但不同通道对占位符类型要求不同：
+ *   - hue 位置需要数字（0），saturation/lightness 位置需要百分比（0%）。
+ * 穷举组合避免了需要感知通道位置的复杂解析。
+ */
+function isHslValidWithVarPlaceholders(value, ranges) {
+    const isValidCssColor = (v) => {
+        try {
+            const ast = csstree.parse(v, { context: 'value' });
+            return !csstree.lexer.matchType('color', ast).error;
+        }
+        catch {
+            return false;
+        }
+    };
+    const n = ranges.length;
+    const total = 1 << n; // 2^n 种组合
+    for (let mask = 0; mask < total; mask++) {
+        let replaced = value;
+        let offset = 0;
+        for (let i = 0; i < n; i++) {
+            const placeholder = (mask >> i) & 1 ? '0%' : '0';
+            const m = ranges[i];
+            const start = m.index + offset;
+            const end = start + m.length;
+            replaced = replaced.slice(0, start) + placeholder + replaced.slice(end);
+            offset += placeholder.length - m.length;
+        }
+        if (isValidCssColor(replaced))
+            return true;
+    }
+    return false; // 所有组合均非法，视为结构性错误
+}
 const rule = primary => {
     return (root, result) => {
         const validOptions = validateOptions(result, exports.ruleName, {
@@ -84,6 +151,29 @@ const rule = primary => {
             // 只处理纯 hsl/hsla 颜色值，跳过复合值（如 box-shadow）
             if (!/^hsla?\(/i.test(value))
                 return;
+            // 跳过 CSS Color Level 5 相对颜色语法：hsl(from <color> h s l)
+            // css-tree 词法器尚不支持该语法，直接跳过避免误报
+            if (/^hsla?\(\s*from\s+/i.test(value))
+                return;
+            // none 关键字只在现代空格语法中合法（CSS Color Level 4），逗号语法不支持
+            // 通过是否含逗号区分语法：现代语法跳过，逗号语法交由 css-tree 验证
+            const isLegacySyntax = /^hsla?\s*\([^)]*,/i.test(value);
+            if (!isLegacySyntax && /\bnone\b/i.test(value))
+                return;
+            // 包含 var() 时，穷举占位符组合进行结构性校验
+            const varRanges = extractVarRanges(value);
+            if (varRanges.length > 0) {
+                if (!isHslValidWithVarPlaceholders(value, varRanges)) {
+                    report({
+                        message: exports.messages.invalidHsl(value),
+                        node: decl,
+                        result,
+                        ruleName: exports.ruleName,
+                        word: value,
+                    });
+                }
+                return;
+            }
             try {
                 const ast = csstree.parse(value, { context: 'value' });
                 const matchResult = csstree.lexer.matchType('color', ast);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/fullstack-presets",
-  "version": "1.1.5-beta.20",
+  "version": "1.1.5-beta.22",
   "files": [
     "lib"
   ],