[8.x] ES Lint rules for css-in-js declarations within Kibana (elastic…

…#200703) (elastic#204620) # Backport This will backport the following commits from `main` to `8.x`: - [ES Lint rules for css-in-js declarations within Kibana (elastic#200703)](elastic#200703)  ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) \r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>\r\nCo-authored-by: Elastic Machine <[email protected]>","sha":"7370cc712ee2bf23f4cf53eef2e74942340f761c","branchLabelMapping":{"^v9.0.0$":"main","^v8.18.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","backport missing","v9.0.0","Team:SharedUX","backport:prev-minor"],"number":200703,"url":"https://github.com/elastic/kibana/pull/200703","mergeCommit":{"message":"ES Lint rules for css-in-js declarations within Kibana (elastic#200703)\n\n## Summary\r\n\r\nCloses https://github.com/elastic/kibana-team/issues/1272\r\n\r\nThis PR adds implementation for eslint rules to help facilitate the\r\nmigration away from SASS files to leveraging the design tokens EUI\r\nprovides for styling.\r\n\r\nThe introduced rules in this PR are as follows;\r\n\r\n- #### No CSS Color values\r\n Consider; \r\n\r\n ```tsx\r\n <EuiCode style={{ color: '#dd4040' }}>Hello World!</EuiCode>\r\n ```\r\n\r\nthis expression because it specifies the css color property, with a\r\nvalid [CSS color\r\nvalue](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value),\r\nwhen the aforementioned rule is enabled depending on the set report\r\nlevel set the user would get a feedback, see screenshot below;\r\n\r\n\r\n<img width=\"735\" alt=\"Screenshot 2024-11-20 at 12 46 17\"\r\nsrc=\"https://github.com/user-attachments/assets/d2f608dc-782c-4d83-88e6-92dfdd8f6101\">\r\n\r\nThis rule also works for variables defined elsewhere in the code and\r\nreferenced as a value to the style prop, see screenshot below;\r\n\r\n<img width=\"1658\" alt=\"Screenshot 2024-11-26 at 13 29 45\"\r\nsrc=\"https://github.com/user-attachments/assets/f8aadf6b-318b-4c6a-b7c9-bb44fb867b58\">\r\n\r\nfeedback will also be provided when some variable that is a literal\r\nvalue is specified as a value for any earmarked property that should not\r\nspecify literal values.\r\n\r\n<img width=\"1730\" alt=\"Screenshot 2024-11-28 at 19 00 08\"\r\nsrc=\"https://github.com/user-attachments/assets/bc3a8674-9469-4c7a-b0c9-7a2bfa7f08dc\">\r\n\r\nfeedback will be provided for referencing a member prop of some object\r\ndefined elsewhere as a value to any earmarked property that we have\r\ndeemed to not specify literal values\r\n\r\n<img width=\"1676\" alt=\"Screenshot 2024-11-29 at 11 36 44\"\r\nsrc=\"https://github.com/user-attachments/assets/c4537fbf-b2d8-46bb-ad5f-8582e8c9a932\">\r\n\r\n\tSupports;\r\n\t- object values\r\n\t- object references\r\n\t- template literals\r\n\t- tagged templates \r\n\r\nThis approach does not penalize variable declarations, only the usages\r\nof any said variable when it doesn't conform to expectation\r\n\r\n- #### Prefer CSS attributes for EUI components (optional)\r\n Consider; \r\n\r\n ```tsx\r\n<EuiCode style={{ someCSSProperty: 'propertyValue' }}>Hello\r\nWorld!</EuiCode>\r\n ```\r\nA declaration like the one above, will be regarded as an error and can\r\nbe fixed, when it's fixed it will be re-written as\r\n \r\n ```tsx\r\n<EuiCode css={{ someCSSProperty: 'propertyValue' }}>Hello\r\nWorld!</EuiCode>\r\n ```\r\n\r\n\t\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>\r\nCo-authored-by: Elastic Machine <[email protected]>","sha":"7370cc712ee2bf23f4cf53eef2e74942340f761c"}},"sourceBranch":"main","suggestedTargetBranches":[],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/200703","number":200703,"mergeCommit":{"message":"ES Lint rules for css-in-js declarations within Kibana (elastic#200703)\n\n## Summary\r\n\r\nCloses https://github.com/elastic/kibana-team/issues/1272\r\n\r\nThis PR adds implementation for eslint rules to help facilitate the\r\nmigration away from SASS files to leveraging the design tokens EUI\r\nprovides for styling.\r\n\r\nThe introduced rules in this PR are as follows;\r\n\r\n- #### No CSS Color values\r\n Consider; \r\n\r\n ```tsx\r\n <EuiCode style={{ color: '#dd4040' }}>Hello World!</EuiCode>\r\n ```\r\n\r\nthis expression because it specifies the css color property, with a\r\nvalid [CSS color\r\nvalue](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value),\r\nwhen the aforementioned rule is enabled depending on the set report\r\nlevel set the user would get a feedback, see screenshot below;\r\n\r\n\r\n<img width=\"735\" alt=\"Screenshot 2024-11-20 at 12 46 17\"\r\nsrc=\"https://github.com/user-attachments/assets/d2f608dc-782c-4d83-88e6-92dfdd8f6101\">\r\n\r\nThis rule also works for variables defined elsewhere in the code and\r\nreferenced as a value to the style prop, see screenshot below;\r\n\r\n<img width=\"1658\" alt=\"Screenshot 2024-11-26 at 13 29 45\"\r\nsrc=\"https://github.com/user-attachments/assets/f8aadf6b-318b-4c6a-b7c9-bb44fb867b58\">\r\n\r\nfeedback will also be provided when some variable that is a literal\r\nvalue is specified as a value for any earmarked property that should not\r\nspecify literal values.\r\n\r\n<img width=\"1730\" alt=\"Screenshot 2024-11-28 at 19 00 08\"\r\nsrc=\"https://github.com/user-attachments/assets/bc3a8674-9469-4c7a-b0c9-7a2bfa7f08dc\">\r\n\r\nfeedback will be provided for referencing a member prop of some object\r\ndefined elsewhere as a value to any earmarked property that we have\r\ndeemed to not specify literal values\r\n\r\n<img width=\"1676\" alt=\"Screenshot 2024-11-29 at 11 36 44\"\r\nsrc=\"https://github.com/user-attachments/assets/c4537fbf-b2d8-46bb-ad5f-8582e8c9a932\">\r\n\r\n\tSupports;\r\n\t- object values\r\n\t- object references\r\n\t- template literals\r\n\t- tagged templates \r\n\r\nThis approach does not penalize variable declarations, only the usages\r\nof any said variable when it doesn't conform to expectation\r\n\r\n- #### Prefer CSS attributes for EUI components (optional)\r\n Consider; \r\n\r\n ```tsx\r\n<EuiCode style={{ someCSSProperty: 'propertyValue' }}>Hello\r\nWorld!</EuiCode>\r\n ```\r\nA declaration like the one above, will be regarded as an error and can\r\nbe fixed, when it's fixed it will be re-written as\r\n \r\n ```tsx\r\n<EuiCode css={{ someCSSProperty: 'propertyValue' }}>Hello\r\nWorld!</EuiCode>\r\n ```\r\n\r\n\t\r\n\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <[email protected]>\r\nCo-authored-by: Elastic Machine <[email protected]>","sha":"7370cc712ee2bf23f4cf53eef2e74942340f761c"}}]}] BACKPORT-->
natasha-moore-elastic · Dec 18, 2024 · f535325 · f535325
1 parent 1e6a6ca
commit f535325
Show file tree

Hide file tree

Showing 16 changed files with 1,065 additions and 4 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -764,7 +764,6 @@ module.exports = {
         ],
       },
     },
-
     /**
      * Jest specific rules
      */

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
@@ -426,6 +426,7 @@ packages/kbn-es-query @elastic/kibana-data-discovery
 packages/kbn-es-types @elastic/kibana-core @elastic/obs-knowledge-team
 src/platform/plugins/shared/es_ui_shared @elastic/kibana-management
 packages/kbn-eslint-config @elastic/kibana-operations
+packages/kbn-eslint-plugin-css @elastic/appex-sharedux
 packages/kbn-eslint-plugin-disable @elastic/kibana-operations
 packages/kbn-eslint-plugin-eslint @elastic/kibana-operations
 packages/kbn-eslint-plugin-i18n @elastic/obs-knowledge-team @elastic/kibana-operations

diff --git a/package.json b/package.json
@@ -1447,6 +1447,7 @@
     "@kbn/es": "link:packages/kbn-es",
     "@kbn/es-archiver": "link:packages/kbn-es-archiver",
     "@kbn/eslint-config": "link:packages/kbn-eslint-config",
+    "@kbn/eslint-plugin-css": "link:packages/kbn-eslint-plugin-css",
     "@kbn/eslint-plugin-disable": "link:packages/kbn-eslint-plugin-disable",
     "@kbn/eslint-plugin-eslint": "link:packages/kbn-eslint-plugin-eslint",
     "@kbn/eslint-plugin-i18n": "link:packages/kbn-eslint-plugin-i18n",
@@ -1561,6 +1562,7 @@
     "@types/classnames": "^2.2.9",
     "@types/cli-progress": "^3.11.5",
     "@types/color": "^3.0.3",
+    "@types/cssstyle": "^2.2.4",
     "@types/cytoscape": "^3.14.0",
     "@types/d3": "^3.5.43",
     "@types/d3-array": "^2.12.1",
@@ -1710,6 +1712,7 @@
     "css-loader": "^3.4.2",
     "cssnano": "^5.1.12",
     "cssnano-preset-default": "^5.2.12",
+    "cssstyle": "^4.1.0",
     "csstype": "^3.0.2",
     "cypress": "13.6.3",
     "cypress-axe": "^1.5.0",

diff --git a/packages/kbn-eslint-config/.eslintrc.js b/packages/kbn-eslint-config/.eslintrc.js
@@ -28,6 +28,7 @@ module.exports = {
     '@kbn/eslint-plugin-imports',
     '@kbn/eslint-plugin-telemetry',
     '@kbn/eslint-plugin-i18n',
+    '@kbn/eslint-plugin-css',
     'eslint-plugin-depend',
     'prettier',
   ],
@@ -328,6 +329,7 @@ module.exports = {
     '@kbn/imports/no_boundary_crossing': 'error',
     '@kbn/imports/no_group_crossing_manifests': 'error',
     '@kbn/imports/no_group_crossing_imports': 'error',
+    '@kbn/css/no_css_color': 'warn',
     'no-new-func': 'error',
     'no-implied-eval': 'error',
     'no-prototype-builtins': 'error',

diff --git a/packages/kbn-eslint-plugin-css/README.mdx b/packages/kbn-eslint-plugin-css/README.mdx
@@ -0,0 +1,129 @@
+---
+id: kibSharedUXEslintPluginCSS
+slug: /kibana-dev-docs/shared-ux/packages/kbn-eslint-plugin-css
+title: '@kbn/eslint-plugin-design-tokens'
+description: Custom ESLint rules to guardrails for using eui in the Kibana repository
+date: 2024-11-19
+tags: ['kibana', 'dev', 'contributor', 'shared_ux', 'eslint', 'eui']
+---
+
+# Summary
+
+`@kbn/eslint-plugin-css` is an ESLint plugin providing custom ESLint rules to help setup guardrails for using eui in the Kibana repo especially around styling.
+
+The aim of this package is to help engineers to modify EUI components in a much complaint way.
+
+If a rule does not behave as you expect or you have an idea of how these rules can be improved, please reach out to the Shared UX team.
+
+# Rules
+
+## `@kbn/css/no_css_color`
+
+This rule warns engineers to not use literal css color in the codebase, particularly for CSS properties that apply color to 
+either the html element or text nodes, but rather urge users to defer to using the color tokens provided by EUI.
+
+This rule kicks in on the following JSXAttributes; `style`, `className` and `css` and supports various approaches to providing styling declarations.
+
+### Example
+
+The following code:
+
+```
+// Filename: /x-pack/plugins/observability_solution/observability/public/my_component.tsx
+
+import React from 'react';
+import { EuiText } from '@elastic/eui';
+
+function MyComponent() {
+    return (
+        <EuiText style={{ color: 'red' }}>You know, for search</EuiText>
+    )
+}
+```
+
+```
+// Filename: /x-pack/plugins/observability_solution/observability/public/my_component.tsx
+
+import React from 'react';
+import { EuiText } from '@elastic/eui';
+
+function MyComponent() {
+
+    const style = {
+        color: 'red'
+    }
+
+    return (
+        <EuiText style={{ color: style.color }}>You know, for search</EuiText>
+    )
+}
+```
+
+```
+// Filename: /x-pack/plugins/observability_solution/observability/public/my_component.tsx
+
+import React from 'react';
+import { EuiText } from '@elastic/eui';
+
+function MyComponent() {
+    const colorValue = '#dd4040';
+
+    return (
+        <EuiText style={{ color: colorValue }}>You know, for search</EuiText>
+    )
+}
+```
+
+will all raise an eslint report with an appropriate message of severity that matches the configuration of the rule, further more all the examples above
+will also match for when the attribute in question is `css`. The `css` attribute will also raise a report the following cases below;
+
+```
+// Filename: /x-pack/plugins/observability_solution/observability/public/my_component.tsx
+
+import React from 'react';
+import { css } from '@emotion/css';
+import { EuiText } from '@elastic/eui';
+
+function MyComponent() {
+    return (
+        <EuiText css={css`color: '#dd4040' `}>You know, for search</EuiText>
+    )
+}
+```
+
+```
+// Filename: /x-pack/plugins/observability_solution/observability/public/my_component.tsx
+
+import React from 'react';
+import { EuiText } from '@elastic/eui';
+
+function MyComponent() {
+    return (
+        <EuiText css={() => ({ color: '#dd4040' })}>You know, for search</EuiText>
+    )
+}
+```
+
+A special case is also covered for the `className` attribute, where the rule will also raise a report for the following case below;
+
+
+```
+// Filename: /x-pack/plugins/observability_solution/observability/public/my_component.tsx
+
+import React from 'react';
+import { css } from '@emotion/css';
+import { EuiText } from '@elastic/eui';
+
+function MyComponent() {
+    return (
+        <EuiText className={css`color: '#dd4040'`}>You know, for search</EuiText>
+    )
+}
+```
+
+it's worth pointing out that although the examples provided are specific to EUI components, this rule applies to all JSX elements.
+
+## `@kbn/css/prefer_css_attributes_for_eui_components`
+
+This rule warns engineers to use the `css` attribute for EUI components instead of the `style` attribute. 
+
diff --git a/packages/kbn-eslint-plugin-css/index.ts b/packages/kbn-eslint-plugin-css/index.ts
@@ -0,0 +1,20 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+import { NoCssColor } from './src/rules/no_css_color';
+import { PreferCSSAttributeForEuiComponents } from './src/rules/prefer_css_attribute_for_eui_components';
+
+/**
+ * Custom ESLint rules, included as `'@kbn/eslint-plugin-design-tokens'` in the kibana eslint config
+ * @internal
+ */
+export const rules = {
+  no_css_color: NoCssColor,
+  prefer_css_attributes_for_eui_components: PreferCSSAttributeForEuiComponents,
+};
diff --git a/packages/kbn-eslint-plugin-css/jest.config.js b/packages/kbn-eslint-plugin-css/jest.config.js
@@ -0,0 +1,14 @@
+/*
+ * Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one
+ * or more contributor license agreements. Licensed under the "Elastic License
+ * 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side
+ * Public License v 1"; you may not use this file except in compliance with, at
+ * your election, the "Elastic License 2.0", the "GNU Affero General Public
+ * License v3.0 only", or the "Server Side Public License, v 1".
+ */
+
+module.exports = {
+  preset: '@kbn/test',
+  rootDir: '../..',
+  roots: ['<rootDir>/packages/kbn-eslint-plugin-css'],
+};
diff --git a/packages/kbn-eslint-plugin-css/kibana.jsonc b/packages/kbn-eslint-plugin-css/kibana.jsonc
@@ -0,0 +1,6 @@
+{
+  "type": "shared-common",
+  "id": "@kbn/eslint-plugin-css",
+  "devOnly": true,
+  "owner": "@elastic/appex-sharedux"
+}
diff --git a/packages/kbn-eslint-plugin-css/package.json b/packages/kbn-eslint-plugin-css/package.json
@@ -0,0 +1,6 @@
+{
+  "name": "@kbn/eslint-plugin-css",
+  "version": "1.0.0",
+  "private": true,
+  "license": "Elastic License 2.0 OR AGPL-3.0-only OR SSPL-1.0"
+}
-Original file line number
+Diff line change
@@ Expand Up / @@ -764,7 +764,6 @@ module.exports = { @@
             ],
           },
         },
         /**
          * Jest specific rules
          */
@@ Expand Down @@