@salesforce-ux/eslint-plugin-slds 0.5.2 → 1.0.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce-ux/eslint-plugin-slds",
-  "version": "0.5.2",
+  "version": "1.0.0-alpha.0",
   "main": "build/index.js",
   "exports": {
     ".": {
@@ -11,13 +11,15 @@
     "./config": {
       "import": "./eslint.config.mjs",
       "require": "./eslint.config.mjs"
-    }
+    },
+    "./rule-messages.yml": "./src/config/rule-messages.yml"
   },
   "files": [
     "build/**",
     "README.md",
     "RULES.md",
-    "eslint.config.mjs"
+    "eslint.config.mjs",
+    "src/config/rule-messages.yml"
   ],
   "engines": {
     "node": ">=18.18.0"
@@ -32,9 +34,12 @@
   "license": "ISC",
   "description": "ESLint plugin provides custom linting rules specifically built for Salesforce Lightning Design System 2 (SLDS 2 beta)",
   "dependencies": {
+    "@eslint/css": "^0.9.0",
+    "@eslint/css-tree": "^3.6.5",
     "@html-eslint/eslint-plugin": "^0.34.0",
     "@html-eslint/parser": "^0.34.0",
-    "@salesforce-ux/sds-metadata": "^0.3.3"
+    "@salesforce-ux/sds-metadata": "^0.3.3",
+    "chroma-js": "^3.1.2"
   },
   "peerDependencies": {
     "eslint": "^8.0.0 || ^9.0.0"

package/src/config/rule-messages.yml

@@ -0,0 +1,143 @@
+# ESLint Rule Messages - Complete Configuration
+# This file contains all rule metadata: descriptions, documentation URLs, user-facing messages etc.
+
+# =============================================================================
+# CSS Rules (ESLint v9 with @eslint/css)
+# =============================================================================
+
+no-slds-class-overrides:
+  description: "Create new custom CSS classes instead of overriding SLDS selectors"
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-slds-class-overrides"
+  type: "problem"
+  messages:
+    sldsClassOverride: "Overriding .{{className}} isn't supported. To differentiate SLDS and custom classes, create a CSS class in your namespace. Examples: myapp-input, myapp-button."
+
+no-deprecated-slds-classes:
+  description: "Please replace the deprecated classes with a modern equivalent"
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-deprecated-slds-classes"
+  type: "problem"
+  messages:
+    deprecatedClass: "The class {{className}} is deprecated and not available in SLDS2. Please update to a supported class."
+
+no-deprecated-tokens-slds1:
+  description: "Update outdated design tokens to SLDS 2 styling hooks with similar values. For more information, see Styling Hooks on lightningdesignsystem.com."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-deprecated-tokens-slds1"
+  type: "problem"
+  messages:
+    deprecatedToken: "Consider removing {{oldValue}} or replacing it with {{newValue}}. Set the fallback to {{oldValue}}. For more info, see Styling Hooks on lightningdesignsystem.com."
+    noReplacement: "Update outdated design tokens to SLDS 2 styling hooks with similar values. For more information, see Styling Hooks on lightningdesignsystem.com."
+
+enforce-sds-to-slds-hooks:
+  description: "Convert your existing --sds styling hooks to --slds styling hooks. See lightningdesignsystem.com for more info."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#enforce-sds-to-slds-hooks"
+  type: "problem"
+  messages:
+    replaceSdsWithSlds: "Replace {{oldValue}} with {{suggestedMatch}} styling hook."
+  
+# =============================================================================
+# HTML/Component Rules (ESLint v8 & v9)
+# =============================================================================
+
+enforce-bem-usage:
+  description: "Replace BEM double-dash syntax in class names with single underscore syntax"
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#enforce-bem-usage"
+  type: "problem"
+  messages:
+    bemDoubleDash: "{{actual}} has been retired. Update it to the new name {{newValue}}."
+    fixBemNaming: "Update to correct BEM naming convention"
+
+modal-close-button-issue:
+  description: "Update component attributes or CSS classes for the modal close button to comply with the modal component blueprint"
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#modal-close-button-issue"
+  type: "problem"
+  messages:
+    modalCloseButtonIssue: "Update component attributes or CSS classes for the modal close button to comply with the modal component blueprint."
+    removeClass: "Remove the slds-button_icon-inverse class from the modal close button in components that use the SLDS modal blueprint."
+    changeVariant: "Change the variant attribute value from bare-inverse to bare in <lightning-button-icon> or <lightning-icon>."
+    removeVariant: "Remove the variant attribute from the <lightning-icon> component inside the <button> element."
+    ensureButtonClasses: "Add or move slds-button and slds-button_icon to the class attribute of the <button> element or <lightning-button-icon> component."
+    ensureSizeAttribute: "To size icons properly, set the size attribute ‌to large in the <lightning-icon> and <lightning-button-icon> components."
+
+no-deprecated-classes-slds2:
+  description: "Replace classes that aren't available with SLDS 2 classes"
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-deprecated-classes-slds2"
+  type: "problem"
+  messages:
+    deprecatedClass: "The class {{className}} isn't available in SLDS 2. Update it to a class supported in SLDS 2. See lightningdesignsystem.com for more information."
+    updateToModernClass: "Replace deprecated class with modern equivalent"
+    checkDocumentation: "See lightningdesignsystem.com for SLDS 2 class alternatives"
+
+lwc-token-to-slds-hook:
+  description: "Replace the deprecated --lwc tokens with the latest --slds tokens. See lightningdesignsystem.com for more info."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#lwc-token-to-slds-hook"
+  type: "problem"
+  messages:
+    errorWithReplacement: "The '{{oldValue}}' design token is deprecated. Replace it with '{{newValue}}'. For more info, see Global Styling Hooks on lightningdesignsystem.com."
+    errorWithStyleHooks: "The '{{oldValue}}' design token is deprecated. Replace it with the SLDS 2 '{{newValue}}' styling hook and set the fallback to '{{oldValue}}'. For more info, see Global Styling Hooks on lightningdesignsystem.com."
+    errorWithNoRecommendation: "The '{{oldValue}}' design token is deprecated. For more info, see the New Global Styling Hook Guidance on lightningdesignsystem.com."
+
+no-sldshook-fallback-for-lwctoken:
+  description: "Avoid using --slds styling hooks as fallback values for --lwc tokens."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-sldshook-fallback-for-lwctoken"
+  type: "problem"
+  messages:
+    unsupportedFallback: "Remove the {{sldsToken}} styling hook that is used as a fallback value for {{lwcToken}}."
+
+no-unsupported-hooks-slds2:
+  description: "Identifies styling hooks that aren't present in SLDS 2. They must be replaced with styling hooks that have a similar effect, or they must be removed."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-unsupported-hooks-slds2"
+  type: "problem"
+  messages:
+    deprecated: "The {{token}} styling hook isn't present in SLDS 2 and there's no equivalent replacement. Remove it or replace it with a styling hook with a similar effect."
+
+no-slds-var-without-fallback:
+  description: "Add fallback values to SLDS styling hooks. The fallback values are used in Salesforce environments where styling hooks are unavailable."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-slds-var-without-fallback"
+  type: "problem"
+  messages:
+    varWithoutFallback: "Your code uses the {{cssVar}} styling hook without a fallback value. Styling hooks are unavailable in some Salesforce environments. To render your component correctly in all environments, add this fallback value: var({{cssVar}}, {{recommendation}}). To make this fallback value brand-aware, use a branded design token instead of a static value. See Design Tokens on v1.lightningdesignsystem.com."
+
+no-slds-namespace-for-custom-hooks:
+  description: "To differentiate custom styling hooks from SLDS styling hooks, create custom styling hooks in your namespace."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-slds-namespace-for-custom-hooks"
+  type: "problem"
+  messages:
+    customHookNamespace: "Using the --slds namespace for {{token}} isn't supported. Create the custom styling hook in your namespace. Example: --myapp-{{tokenWithoutNamespace}}"
+
+no-slds-private-var:
+  description: "Some SLDS styling hooks are private and reserved only for internal Salesforce use. Private SLDS styling hooks have prefixes --_slds- and --slds-s-. For more information, look up private CSS in lightningdesignsystem.com."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-slds-private-var"
+  type: "problem"
+  messages:
+    privateVar: "This styling hook is reserved for internal Salesforce use. Remove the --_slds- or –slds-s private variable within selector {{prop}}. For more information, look up private CSS in lightningdesignsystem.com."
+
+enforce-component-hook-naming-convention:
+  description: "Replace component styling hooks that use a deprecated naming convention."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#enforce-component-hook-naming-convention"
+  type: "problem"
+  messages:
+    replace: "Replace the deprecated {{oldValue}} component styling hook with {{suggestedMatch}}."
+
+no-hardcoded-values-slds1:
+  description: "Replace static values with SLDS 1 design tokens. For more information, look up design tokens on lightningdesignsystem.com."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-hardcoded-value"
+  type: "suggestion"
+  messages:
+    hardcodedValue: "Replace the {{oldValue}} static value with an SLDS 1 styling hook: {{newValue}}."
+    noReplacement: "There's no replacement styling hook for the {{oldValue}} static value. Remove the static value."
+
+no-hardcoded-values-slds2:
+  description: "Replace static values with SLDS 2 styling hooks. For more information, look up design tokens on lightningdesignsystem.com."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#no-hardcoded-value"
+  type: "suggestion"
+  messages:
+    hardcodedValue: "Consider replacing the {{oldValue}} static value with an SLDS 2 styling hook that has a similar value: {{newValue}}."
+    noReplacement: "There's no replacement styling hook for the {{oldValue}} static value. Remove the static value."
+
+reduce-annotations:
+  description: "Remove your annotations and update your code."
+  url: "https://developer.salesforce.com/docs/platform/slds-linter/guide/reference-rules.html#reduce-annotations"
+  type: "problem"
+  messages:
+    removeAnnotation: "Remove this annotation and update the code to SLDS best practices. For help, file an issue at https://github.com/salesforce-ux/slds-linter/"
+

package/build/rules/enforce-bem-usage.d.ts

@@ -1,28 +0,0 @@
-declare const _default: {
-    meta: {
-        type: string;
-        docs: {
-            category: string;
-            recommended: boolean;
-            description: string;
-            url: string;
-        };
-        fixable: string;
-        schema: {
-            type: string;
-            properties: {
-                pattern: {
-                    type: string;
-                };
-                flags: {
-                    type: string;
-                };
-            };
-            additionalProperties: boolean;
-        }[];
-    };
-    create(context: any): {
-        Tag: (node: any) => void;
-    };
-};
-export = _default;

package/build/rules/utils/node.js

@@ -1,197 +0,0 @@
-"use strict";
-// THIS IS TAKEN FROM html-eslint
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.findAttr = findAttr;
-exports.isAttributesEmpty = isAttributesEmpty;
-exports.isNodeTokensOnSameLine = isNodeTokensOnSameLine;
-exports.splitToLineNodes = splitToLineNodes;
-exports.getLocBetween = getLocBetween;
-exports.isExpressionInTemplate = isExpressionInTemplate;
-exports.isTag = isTag;
-exports.isComment = isComment;
-exports.isText = isText;
-exports.isOverlapWithTemplates = isOverlapWithTemplates;
-exports.codeToLines = codeToLines;
-exports.isRangesOverlap = isRangesOverlap;
-exports.getTemplateTokens = getTemplateTokens;
-const parser_1 = require("@html-eslint/parser");
-/**
- * @param {TagNode | ScriptTagNode | StyleTagNode} node
- * @param {string} key
- * @returns {AttributeNode | undefined}
- */
-function findAttr(node, key) {
-    return node.attributes.find((attr) => attr.key && attr.key.value.toLowerCase() === key.toLowerCase());
-}
-/**
- * Checks whether a node's attributes is empty or not.
- * @param {TagNode | ScriptTagNode | StyleTagNode} node
- * @returns {boolean}
- */
-function isAttributesEmpty(node) {
-    return !node.attributes || node.attributes.length <= 0;
-}
-/**
- * Checks whether a node's all tokens are on the same line or not.
- * @param {AnyNode} node A node to check
- * @returns {boolean} `true` if a node's tokens are on the same line, otherwise `false`.
- */
-function isNodeTokensOnSameLine(node) {
-    return node.loc.start.line === node.loc.end.line;
-}
-/**
- *
- * @param {Range} rangeA
- * @param {Range} rangeB
- * @returns {boolean}
- */
-function isRangesOverlap(rangeA, rangeB) {
-    return rangeA[0] < rangeB[1] && rangeB[0] < rangeA[1];
-}
-/**
- * @param {(TextNode | CommentContentNode)['templates']} templates
- * @param {Range} range
- * @returns {boolean}
- */
-function isOverlapWithTemplates(templates, range) {
-    return templates
-        .filter((template) => template.isTemplate)
-        .some((template) => isRangesOverlap(template.range, range));
-}
-/**
- *
- * @param {TextNode | CommentContentNode} node
- * @returns {LineNode[]}
- */
-function splitToLineNodes(node) {
-    let start = node.range[0];
-    let line = node.loc.start.line;
-    const startCol = node.loc.start.column;
-    /**
-     * @type {LineNode[]}
-     */
-    const lineNodes = [];
-    const templates = node.templates || [];
-    /**
-     *
-     * @param {import("../../types").Range} range
-     */
-    function shouldSkipIndentCheck(range) {
-        const overlappedTemplates = templates.filter((template) => template.isTemplate && isRangesOverlap(template.range, range));
-        const isLineInTemplate = overlappedTemplates.some((template) => {
-            return template.range[0] <= range[0] && template.range[1] >= range[1];
-        });
-        if (isLineInTemplate) {
-            return true;
-        }
-        const isLineBeforeTemplate = overlappedTemplates.some((template) => {
-            return template.range[0] <= range[0] && template.range[1] <= range[1];
-        });
-        if (isLineBeforeTemplate) {
-            return true;
-        }
-        const isLineAfterTemplate = overlappedTemplates.some((template) => {
-            return template.range[1] <= range[0];
-        });
-        if (isLineAfterTemplate) {
-            return true;
-        }
-        return false;
-    }
-    node.value.split("\n").forEach((value, index) => {
-        const columnStart = index === 0 ? startCol : 0;
-        /**
-         * @type {import("../../types").Range}
-         */
-        const range = [start, start + value.length];
-        const loc = {
-            start: {
-                line,
-                column: columnStart,
-            },
-            end: {
-                line,
-                column: columnStart + value.length,
-            },
-        };
-        /**
-         * @type {LineNode}
-         */
-        const lineNode = {
-            type: "Line",
-            value,
-            range,
-            loc,
-            skipIndentCheck: shouldSkipIndentCheck(range),
-        };
-        start += value.length + 1;
-        line += 1;
-        lineNodes.push(lineNode);
-    });
-    return lineNodes;
-}
-/**
- * Get location between two nodes.
- * @param {BaseNode} before A node placed in before
- * @param {BaseNode} after A node placed in after
- * @returns {Location} location between two nodes.
- */
-function getLocBetween(before, after) {
-    return {
-        start: before.loc.end,
-        end: after.loc.start,
-    };
-}
-/**
- * @param {AttributeValueNode} node
- * @return {boolean}
- */
-function isExpressionInTemplate(node) {
-    if (node.type === parser_1.NODE_TYPES.AttributeValue) {
-        return node.value.indexOf("${") === 0;
-    }
-    return false;
-}
-/**
- * @param {AnyNode} node
- * @returns {node is TagNode}
- */
-function isTag(node) {
-    return node.type === parser_1.NODE_TYPES.Tag;
-}
-/**
- * @param {AnyNode} node
- * @returns {node is CommentNode}
- */
-function isComment(node) {
-    return node.type === parser_1.NODE_TYPES.Comment;
-}
-/**
- * @param {AnyNode} node
- * @returns {node is TextNode}
- */
-function isText(node) {
-    return node.type === parser_1.NODE_TYPES.Text;
-}
-const lineBreakPattern = /\r\n|[\r\n\u2028\u2029]/u;
-const lineEndingPattern = new RegExp(lineBreakPattern.source, "gu");
-/**
- * @param {string} source
- * @returns {string[]}
- */
-function codeToLines(source) {
-    return source.split(lineEndingPattern);
-}
-/**
- *
- * @param {AnyToken[]} tokens
- * @returns {((CommentContentNode | TextNode)['templates'][number])[]}
- */
-function getTemplateTokens(tokens) {
-    return ([]
-        .concat(...tokens
-        // @ts-ignore
-        .map((token) => token["templates"] || []))
-        // @ts-ignore
-        .filter((token) => token.isTemplate));
-}

package/build/rules/utils/rule.d.ts

@@ -1,7 +0,0 @@
-export declare const messages: {
-    removeClass: string;
-    changeVariant: string;
-    removeVariant: string;
-    ensureButtonClasses: string;
-    ensureSizeAttribute: string;
-};

package/build/rules/utils/rule.js

@@ -1,10 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.messages = void 0;
-exports.messages = {
-    removeClass: "Remove the slds-button_icon-inverse class from the modal close button in components that use the SLDS modal blueprint.",
-    changeVariant: "Change the variant attribute value from bare-inverse to bare in <lightning-button-icon> or <lightning-icon>.",
-    removeVariant: "Remove the variant attribute from the <lightning-icon> component inside the <button> element.",
-    ensureButtonClasses: "Add or move slds-button and slds-button_icon to the class attribute of the <button> element or <lightning-button-icon> component.",
-    ensureSizeAttribute: "To size icons properly, set the size attribute ‌to large in the <lightning-icon> and <lightning-button-icon> components.",
-};

package/build/rules/utils/rule.js.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/rules/utils/rule.ts"],
-  "sourcesContent": ["export const messages= {\n        removeClass:\n          \"Remove the slds-button_icon-inverse class from the modal close button in components that use the SLDS modal blueprint.\",\n        changeVariant:\n          \"Change the variant attribute value from bare-inverse to bare in <lightning-button-icon> or <lightning-icon>.\",\n        removeVariant:\n          \"Remove the variant attribute from the <lightning-icon> component inside the <button> element.\",\n        ensureButtonClasses:\n          \"Add or move slds-button and slds-button_icon to the class attribute of the <button> element or <lightning-button-icon> component.\",\n        ensureSizeAttribute:\n          \"To size icons properly, set the size attribute \u200Cto large in the <lightning-icon> and <lightning-button-icon> components.\",\n      }"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAO,IAAM,WAAU;AAAA,EACf,aACE;AAAA,EACF,eACE;AAAA,EACF,eACE;AAAA,EACF,qBACE;AAAA,EACF,qBACE;AACJ;",
-  "names": []
-}