@hero-design/eslint-plugin 9.2.1 → 9.2.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @hero-design/eslint-plugin
 
+## 9.2.2
+
+### Patch Changes
+
+- [#4770](https://github.com/Thinkei/hero-design/pull/4770) [`f41e0ff2a0a23e37c0be1203320dc2677f7e6af4`](https://github.com/Thinkei/hero-design/commit/f41e0ff2a0a23e37c0be1203320dc2677f7e6af4) Thanks [@tqdungit](https://github.com/tqdungit)! - Upgrade node 22
+
 ## 9.2.1
 
 ### Patch Changes

package/README.md

@@ -1,17 +1,31 @@
 # @hero-design/eslint-plugin
 
-Hero Design's eslint plugin to ensure correct usage and deprecation of our packages.
-We **strongly recommend** all of our consumers to use this plugin with our predefined `recommendedRn` config.
+## Overview
+
+Hero Design's ESLint plugin that ensures correct usage and deprecation of Hero Design packages. The plugin is used across many repositories to enforce best practices, prevent deprecated API usage, and maintain consistency across projects using `@hero-design/rn`, `@hero-design/react`, and `@hero-design/colors`.
+
+**Key features:**
+- Enforces proper component prop usage and prevents deprecated APIs
+- Prevents direct color palette access in favor of semantic tokens
+- Ensures text content is properly wrapped in Typography components
+- Blocks not recommended imports with helpful migration messages
+- Provides pre-configured rule sets for React Native and React web projects
+
+We **strongly recommend** all consumers to use this plugin with our predefined `recommendedRn` or `recommendedReact` configs.
 
 ## Installation
 
-You'll first need to install [ESLint](https://eslint.org/):
+**Prerequisites:**
+- Node.js >= 14.17.0 (or >= 20.0.0 recommended)
+- ESLint >= 7.0.0
+
+Install ESLint (if not already installed):
 
 ```sh
 yarn add -D eslint
 ```
 
-Next, install `@hero-design/eslint-plugin`:
+Install `@hero-design/eslint-plugin`:
 
 ```sh
 yarn add -D @hero-design/eslint-plugin
@@ -19,7 +33,7 @@ yarn add -D @hero-design/eslint-plugin
 
 ## Usage
 
-Add `@hero-design` to the plugins section of your `.eslintrc` configuration file. You can omit the `eslint-plugin` postfix:
+Add `@hero-design` to the plugins section of your ESLint configuration (`.eslintrc`). You can omit the `eslint-plugin` postfix:
 
 ```json
 {
@@ -27,9 +41,11 @@ Add `@hero-design` to the plugins section of your `.eslintrc` configuration file
 }
 ```
 
-Then, you can either:
+### Recommended Configurations
+
+#### For React Native Projects
 
-1. Use our pre-defined config by adding `plugin:@hero-design/recommendedRn` under `extends` section. This approach is **strongly recommended** as it requires no configurations.
+Use the `recommendedRn` config, which includes rules for deprecated props, theme keys, and not recommended imports:
 
 ```json
 {
@@ -37,21 +53,115 @@ Then, you can either:
 }
 ```
 
-2. Configure the rules you want to use under the `rules` section. This approach should be **avoided** in most of the cases unless you have any specific needs.
+#### For React Web Projects
+
+Use the `recommendedReact` config, which includes rules for color palette access and typography:
+
+```json
+{
+  "extends": ["plugin:@hero-design/recommendedReact"]
+}
+```
+
+#### For Internal Teams (Next Version Migration)
+
+Use the `internalRn` config to prepare for upcoming breaking changes:
+
+```json
+{
+  "extends": ["plugin:@hero-design/internalRn"]
+}
+```
+
+### Manual Rule Configuration
+
+You can also configure individual rules manually, though this approach should be avoided unless you have specific needs:
 
 ```json
 {
   "rules": {
-    "@hero-design/rule-name": 2
+    "@hero-design/no-deprecated-component-prop": "error",
+    "@hero-design/no-direct-color-palette-access": "warn"
   }
 }
 ```
 
+## Examples
+
+### Basic Setup
+
+```json
+// .eslintrc.json
+{
+  "extends": [
+    "eslint:recommended",
+    "plugin:@hero-design/recommendedRn"
+  ],
+  "plugins": ["@hero-design"]
+}
+```
+
+### React Native Component Usage
+
+The plugin will catch deprecated props and suggest alternatives:
+
+```jsx
+// ❌ Incorrect - will be flagged
+import { Card } from '@hero-design/rn';
+<Card variant="outlined" />
+
+// ✅ Correct
+<Card appearance="outlined" />
+```
+
+### Color Usage
+
+```jsx
+// ❌ Incorrect - direct palette access
+const color = theme.colors.palette.redLight30;
+
+// ✅ Correct - semantic color tokens
+const color = theme.colors.text.primary;
+```
+
+### Typography Usage (React Web)
+
+```jsx
+// ❌ Incorrect - raw HTML text elements
+<div>
+  <p>Some text</p>
+</div>
+
+// ✅ Correct - Typography component
+<div>
+  <Typography tagName="p">Some text</Typography>
+</div>
+```
+
 ## Supported Rules
 
-| Rule                                            | Description                                 |
-| ----------------------------------------------- | ------------------------------------------- |
-| @hero-design/no-deprecated-component-prop       | Disallow deprecated component props         |
-| @hero-design/no-deprecated-component-prop-value | Disallow deprecated component prop's values |
-| @hero-design/no-deprecated-theme-key            | Disallow deprecated theme keys              |
-| @hero-design/not-recommended-import             | Disallow not recommended imports            |
+| Rule | Description | Config |
+|------|-------------|--------|
+| `@hero-design/banning-snowflake-approve-comment` | Disallow Snowflake Guard approval comments | - |
+| `@hero-design/no-deprecated-component-prop` | Disallow deprecated component props | - |
+| `@hero-design/no-deprecated-component-prop-next` | Disallow props deprecated in next version | `internalRn` |
+| `@hero-design/no-deprecated-component-prop-value` | Disallow deprecated component prop values | - |
+| `@hero-design/no-deprecated-theme-key` | Disallow deprecated theme keys | - |
+| `@hero-design/no-direct-color-palette-access` | Disallow direct color palette access | `recommendedReact` |
+| `@hero-design/not-recommended-import` | Disallow not recommended imports | `recommendedRn` |
+| `@hero-design/react-no-text-outside-typography` | Require text inside Typography component | `recommendedReact` |
+
+For detailed documentation on each rule, see the [docs/rules](./docs/rules/) directory.
+
+## Contributing
+
+To contribute to this plugin:
+
+1. **Add a new rule**: Create a new rule file in `lib/rules/` following the existing pattern
+2. **Add tests**: Create corresponding test files in `tests/lib/rules/`
+3. **Add documentation**: Create a markdown file in `docs/rules/` explaining the rule
+4. **Update configs**: Add the rule to appropriate configs in `lib/index.js`
+5. **Run tests**: Execute `yarn test` to ensure all tests pass
+6. **Run linter**: Execute `yarn lint` to check code quality
+
+See the existing rules for examples of the expected structure and patterns.

package/docs/rules/banning-snowflake-approve-comment.md

@@ -0,0 +1,42 @@
+# Disallow snowflake-guard comments (banning-snowflake-approve-comment)
+
+## Rule Details
+
+This rule disallows the use of comments that include `@snowflake-guard/` references. These comments are used for Snowflake Guard approval workflows and should not be committed to the codebase.
+
+Examples of **incorrect** code for this rule:
+
+```jsx
+// @snowflake-guard/approve
+const Component = () => {
+  return <div>Content</div>;
+};
+
+/* @snowflake-guard/review */
+function fetchUserData() {
+  return api.get('/users');
+}
+
+// @snowflake-guard/custom-pattern
+const config = { apiKey: process.env.API_KEY };
+```
+
+Examples of **correct** code for this rule:
+
+```jsx
+// Regular comment
+const Component = () => {
+  return <div>Content</div>;
+};
+
+function fetchUserData() {
+  return api.get('/users');
+}
+
+const config = { apiKey: process.env.API_KEY };
+```
+
+## When To Use It
+
+Use this rule to prevent Snowflake Guard approval comments from being committed to the repository. If you need Snowflake Guard approval, please contact the Andromeda team directly.
+

package/docs/rules/no-deprecated-component-prop-next.md

@@ -0,0 +1,32 @@
+# Disallow deprecated component props for next version (no-deprecated-component-prop-next)
+
+## Rule Details
+
+This rule is an alias for `no-deprecated-component-prop` and is used to flag component props that will be deprecated in the next major version. It helps teams prepare for upcoming breaking changes by warning about props that should be migrated.
+
+Examples of **incorrect** code for this rule:
+
+```js
+<Tag variant="primary" />
+<FAB.ActionGroup headerTitle="Actions" />
+<Checkbox withBorder />
+<SectionHeading fontSize={16} fontWeight="bold" />
+```
+
+Examples of **correct** code for this rule:
+
+```js
+<Tag appearance="primary" />
+<FAB.ActionGroup title="Actions" />
+<Checkbox />
+<SectionHeading />
+```
+
+### Options
+
+This rule receives the same options as `no-deprecated-component-prop`. See the [no-deprecated-component-prop documentation](./no-deprecated-component-prop.md) for details.
+
+## When To Use It
+
+Use this rule when you want to prepare for upcoming breaking changes in the next major version. This rule is typically enabled in the `internalRn` config to help internal teams migrate before the public release.
+

package/docs/rules/no-direct-color-palette-access.md

@@ -0,0 +1,34 @@
+# Disallow direct color palette access (no-direct-color-palette-access)
+
+## Rule Details
+
+This rule disallows direct access to color palette values (e.g., `theme.colors.palette.redLight30` or `colors.palette.blueDark50`). Instead, you should use semantic color tokens from the theme.
+
+Examples of **incorrect** code for this rule:
+
+```js
+const StyledComponent = styled.div`
+  color: ${({ theme }) => theme.colors.palette.redLight30};
+  background-color: ${({ theme }) => theme.colors.palette.blueDark50};
+`;
+
+// Or with direct colors import
+const color = colors.palette.greenLight20;
+```
+
+Examples of **correct** code for this rule:
+
+```js
+const StyledComponent = styled.div`
+  color: ${({ theme }) => theme.colors.text.primary};
+  background-color: ${({ theme }) => theme.colors.background.secondary};
+`;
+
+// Use semantic colors from theme
+const color = theme.colors.brand.primary;
+```
+
+## When To Use It
+
+Use this rule to enforce the use of semantic color tokens instead of direct palette access. This ensures consistent theming and makes it easier to maintain design system colors across different themes and products.
+

package/docs/rules/react-no-text-outside-typography.md

@@ -0,0 +1,57 @@
+# Require text inside Typography component (react-no-text-outside-typography)
+
+## Rule Details
+
+This rule recommends using text content inside Typography components from `@hero-design/react` instead of raw HTML text elements like `<p>`, `<span>`, `<div>`, etc.
+
+Examples of **incorrect** code for this rule:
+
+```jsx
+<div>
+  <p>Some text content</p>
+  <span>More text</span>
+</div>
+
+<div>
+  <Typography tagName="div">
+    <div>Nested text</div>
+  </Typography>
+</div>
+```
+
+Examples of **correct** code for this rule:
+
+```jsx
+<div>
+  <Typography tagName="p">Some text content</Typography>
+  <Typography tagName="span">More text</Typography>
+</div>
+
+<Typography tagName="div">
+  <ul>
+    <li>List item</li>
+  </ul>
+</Typography>
+
+<Typography tagName="p">
+  <Typography tagName="span">Nested text</Typography>
+</Typography>
+```
+
+### Allowed Cases
+
+The rule allows certain nested structures:
+
+- Text inside `<Typography tagName="p">` or `<Typography tagName="span">` can be nested up to 1 level
+- Text inside `<Typography tagName="div">` can be nested up to 2 levels when:
+  - Inside an unordered list (`<ul><li>`)
+  - Inside a paragraph (`<p>`)
+
+### Special Handling
+
+The rule also checks for `Intl.formatMessage` calls and ensures they are properly wrapped in Typography components.
+
+## When To Use It
+
+Use this rule to ensure consistent typography styling across your React application and to maintain design system standards for text rendering.
+

package/lib/rules/no-deprecated-component-prop-next.js

@@ -1,4 +1,3 @@
-
 const rule = require('./no-deprecated-component-prop');
 
 module.exports = rule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hero-design/eslint-plugin",
-  "version": "9.2.1",
+  "version": "9.2.2",
   "description": "Hero Design's eslint plugin",
   "keywords": [
     "eslint",
@@ -22,7 +22,6 @@
     "requireindex": "^1.2.0"
   },
   "devDependencies": {
-    "@eslint/compat": "^1.1.1",
     "@eslint/eslintrc": "^3.1.0",
     "@eslint/js": "^9.8.0",
     "eslint": "^8.56.0",
@@ -32,7 +31,7 @@
     "prettier-config-hd": "8.42.4"
   },
   "engines": {
-    "node": "^14.17.0 || ^16.0.0 || ^18.0.0 || >=20.0.0"
+    "node": "^14.17.0 || ^16.0.0 || ^18.0.0 || ^20.0.0 || >= 22.0.0"
   },
   "peerDependencies": {
     "eslint": ">=7"