From 32f6d3682edbccfa31841b2f1615c293dc0a6ad5 Mon Sep 17 00:00:00 2001 From: Dmitry Zhifarsky Date: Sun, 31 Jul 2022 15:31:02 +0400 Subject: [PATCH] docs: rework website rules list page --- website/docs/rules/overview.md | 246 -------- website/docs/rules/overview.mdx | 594 ++++++++++++++++++ website/src/components/RuleEntry.tsx | 56 ++ website/src/components/buttons/CopyButton.tsx | 32 + website/src/css/custom.css | 98 +++ 5 files changed, 780 insertions(+), 246 deletions(-) delete mode 100644 website/docs/rules/overview.md create mode 100644 website/docs/rules/overview.mdx create mode 100644 website/src/components/RuleEntry.tsx create mode 100644 website/src/components/buttons/CopyButton.tsx diff --git a/website/docs/rules/overview.md b/website/docs/rules/overview.md deleted file mode 100644 index 150d4c91b8..0000000000 --- a/website/docs/rules/overview.md +++ /dev/null @@ -1,246 +0,0 @@ ---- -sidebar_label: Overview -sidebar_position: 0 ---- - -# Rules overview - -Rules are grouped by a category to help you understand their purpose. - -Rules configuration is [described here](../getting-started/configuration#configuring-a-rules-entry). - -## Common {#common} - -- [avoid-banned-imports](./common/avoid-banned-imports.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/avoid-banned-imports.md#config-example) - - Configure some imports that you want to ban. - -- [avoid-collection-methods-with-unrelated-types](./common/avoid-collection-methods-with-unrelated-types.md) - - Avoid using collection methods with unrelated types, such as accessing a map of integers using a string key. - -- [avoid-duplicate-exports](./common/avoid-duplicate-exports.md) - - Warns when a file has multiple `exports` declarations with the same URI. - -- [avoid-dynamic](./common/avoid-dynamic.md) - - Warns when `dynamic` type is used as variable type in declaration, return type of a function, etc. - -- [avoid-global-state](./common/avoid-global-state.md) - - Warns about usage mutable global variables. - -- [avoid-ignoring-return-values](./common/avoid-ignoring-return-values.md) - - Warns when a return value of a method or function invocation or a class instance property access is not used. - -- [avoid-late-keyword](./common/avoid-late-keyword.md) - - Warns when a field or variable is declared with a `late` keyword. - -- [avoid-missing-enum-constant-in-map](./common/avoid-missing-enum-constant-in-map.md) - - Warns when a enum constant is missing in a map declaration. - -- [avoid-nested-conditional-expressions](./common/avoid-nested-conditional-expressions.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/member-ordering.md#config-example) - - Warns about nested conditional expressions. - -- [avoid-non-ascii-symbols](./common/avoid-non-ascii-symbols.md) - - Warns when a string literal contains non ascii characters. - -- [avoid-non-null-assertion](./common/avoid-non-null-assertion.md) - - Warns when non null assertion operator (or “bang” operator) is used for a property access or method invocation. The operator check works at runtime and it may fail and throw a runtime exception. - -- [avoid-throw-in-catch-block](./common/avoid-throw-in-catch-block.md) - - Warns when call `throw` in a catch block. - -- [avoid-top-level-members-in-tests](./common/avoid-top-level-members-in-tests.md) - - Warns when a public top-level member (expect the entrypoint) is declared inside a test file. - -- [avoid-unnecessary-type-assertions](./common/avoid-unnecessary-type-assertions.md) - - Warns about unnecessary usage of 'is' and 'whereType' operators. - -- [avoid-unnecessary-type-casts](./common/avoid-unnecessary-type-casts.md) - - Warns about unnecessary usage of 'as' operators. - -- [avoid-unrelated-type-assertions](./common/avoid-unrelated-type-assertions.md) - - Warns about unrelated usages of 'is' operators. - -- [avoid-unused-parameters](./common/avoid-unused-parameters.md) - - Checks for unused parameters inside a function or method body. - -- [ban-name](./common/ban-name.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/ban-name.md#config-example) - - Configure some names that you want to ban. - -- [binary-expression-operand-order](./common/binary-expression-operand-order.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Warns when a literal value is on the left hand side in a binary expressions. - -- [double-literal-format](./common/double-literal-format.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Checks that double literals should begin with `0.` instead of just `.`, and should not end with a trailing `0`. - -- [format-comment](./common/format-comment.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/format-comment.md#config-example) ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Prefer format comments like sentences. - -- [member-ordering](./common/member-ordering.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/member-ordering.md#config-example) - - Enforces ordering for a class members. - -- [member-ordering-extended](./common/member-ordering-extended.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/member-ordering-extended.md#config-example) - - Enforces ordering for a class members. - -- [newline-before-return](./common/newline-before-return.md) - - Enforces blank line between statements and return in a block. - -- [no-boolean-literal-compare](./common/no-boolean-literal-compare.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Warns on comparison to a boolean literal, as in x == true. - -- [no-empty-block](./common/no-empty-block.md) - - Disallows empty blocks except catch clause block. - -- [no-equal-arguments](./common/no-equal-arguments.md)   ![Configurable](https://img.shields.io/badge/-configurable-informational) - - Warns when equal arguments passed to a function or method invocation. - -- [no-equal-then-else](./common/no-equal-then-else.md) - - Warns when if statement has equal then and else statements or conditional expression has equal then and else expressions. - -- [no-magic-number](./common/no-magic-number.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/no-magic-number.md#config-example) - - Warns against using number literals outside of named constants or variables. - -- [no-object-declaration](./common/no-object-declaration.md) - - Warns when a class member is declared with Object type. - -- [prefer-async-await](./common/prefer-async-await.md) - - Recommends to use async/await syntax to handle Futures result instead of `.then()` invocation. - -- [prefer-commenting-analyzer-ignores](./common/prefer-commenting-analyzer-ignores.md) - - Warns when `// ignore:` comments are left without any additional description why this ignore is applied. - -- [prefer-conditional-expressions](./common/prefer-conditional-expressions.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Recommends to use a conditional expression instead of assigning to the same thing or return statement in each branch of an if statement. - -- [prefer-correct-identifier-length](./common/prefer-correct-identifier-length.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/prefer-correct-identifier-length.md#config-example) - - Warns when identifier name length very short or long. - -- [prefer-correct-type-name](./common/prefer-correct-type-name.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/prefer-correct-type-name.md#config-example) - - Type name should only contain alphanumeric characters, start with an uppercase character and span between min-length and max-length characters in length. - -- [prefer-enums-by-name](./common/prefer-enums-by-name.md) - - Since Dart 2.15 it's possible to use `byName` method on enum `values` prop instead of searching the value with `firstWhere`. - -- [prefer-first](./common/prefer-first.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Use `first` to gets the first element. - -- [prefer-immediate-return](./common/prefer-immediate-return.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Warns when a method or a function returns a variable declared right before the return statement. - -- [prefer-last](./common/prefer-last.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Use `last` to gets the last element. - -- [prefer-match-file-name](common/prefer-match-file-name.md) - - Warns when file name does not match class name. - -- [prefer-trailing-comma](./common/prefer-trailing-comma.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/prefer-trailing-comma.md#config-example)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Check for trailing comma for arguments, parameters, enum values and collections. - -- [tag-name](common/tag-name.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./common/prefer-trailing-comma.md#config-example)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Warns when tag name does not match class name. - -## Flutter specific {#flutter-specific} - -- [always-remove-listener](./flutter/always-remove-listener.md) - - Warns when an event listener is added but never removed. - -- [avoid-border-all](./flutter/avoid-border-all.md) - - Avoid using Border.all constructor. - -- [avoid-returning-widgets](./flutter/avoid-returning-widgets.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./flutter/avoid-returning-widgets.md#config-example) - - Warns when a method or function returns a Widget or subclass of a Widget. - -- [avoid-unnecessary-setstate](./flutter/avoid-unnecessary-setstate.md) - - Warns when `setState` is called inside `initState`, `didUpdateWidget` or `build` methods and when it is called from a `sync` method that is called inside those methods. - -- [avoid-wrapping-in-padding](./flutter/avoid-wrapping-in-padding.md) - - Warns when a widget is wrapped in a Padding widget but has a padding settings by itself. - -- [avoid-use-expanded-as-spacer](./flutter/avoid-use-expanded-as-spacer.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Avoid using Expanded widget as Spacer. - -- [prefer-const-border-radius](./flutter/prefer-const-border-radius.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Warns when used non const border radius. - -- [prefer-correct-edge-insets-constructor](./flutter/prefer-correct-edge-insets-constructor.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Prefer correct EdgeInsets constructor. - -- [prefer-extracting-callbacks](./flutter/prefer-extracting-callbacks.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./flutter/prefer-extracting-callbacks.md#config-example) - - Warns about inline callbacks in a widget tree and suggest to extract them to a widget method. - -- [prefer-single-widget-per-file](./flutter/prefer-single-widget-per-file.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./flutter/prefer-single-widget-per-file.md#config-example) - - Warns when a file contains more than a single widget. - -## Intl specific {#intl-specific} - -- [prefer-intl-name](./intl/prefer-intl-name.md)   ![Has auto-fix](https://img.shields.io/badge/-has%20auto--fix-success) - - Recommends to use ClassName_ClassMemberName pattern for Intl methods name argument. - -- [provide-correct-intl-args](./intl/provide-correct-intl-args.md) - - Warns when the Intl.message() invocation has incorrect args. - -## Angular specific {#angular-specific} - -- [avoid-preserve-whitespace-false](./angular/avoid-preserve-whitespace-false.md) - - Warns when a `@Component` annotation has explicit false value for preserveWhitespace. - -- [component-annotation-arguments-ordering](./angular/component-annotation-arguments-ordering.md)   [![Configurable](https://img.shields.io/badge/-configurable-informational)](./angular/component-annotation-arguments-ordering.md#config-example) - - Enforces Angular `@Component` annotation arguments ordering. - -- [prefer-on-push-cd-strategy](./angular/prefer-on-push-cd-strategy.md) - - Prefer setting changeDetection: ChangeDetectionStrategy.OnPush in Angular `@Component` annotations. diff --git a/website/docs/rules/overview.mdx b/website/docs/rules/overview.mdx new file mode 100644 index 0000000000..ee01438b68 --- /dev/null +++ b/website/docs/rules/overview.mdx @@ -0,0 +1,594 @@ +--- +sidebar_label: Overview +sidebar_position: 0 +--- + +import RuleEntry from '@site/src/components/RuleEntry'; + +# Rules overview + +:::tip + +Rules configuration is [described here](../getting-started/configuration#configuring-a-rules-entry). + +::: + +Rules are grouped by category to help you understand their purpose. Each rule has emojis denoting: + +- ⚙️ - this rule is configurable +- 🛠 - some problems reported by this rule can be fixed by editor suggestions +- ⚠️ - this rule is deprecated and will be removed in the next major release + +## Common {#common} + + + Configure some imports that you want to ban. + + + + Avoid using collection methods with unrelated types, such as accessing a map + of integers using a string key. + + + + Warns when a file has multiple exports declarations with the same + URI. + + + + Warns when dynamic type is used as variable type in declaration, + return type of a function, etc. + + + + Warns about usage mutable global variables. + + + + Warns when a return value of a method or function invocation or a class + instance property access is not used. + + + + Warns when a field or variable is declared with a late keyword. + + + + Warns when a enum constant is missing in a map declaration. + + + + Warns about nested conditional expressions. + + + + Warns when a string literal contains non ascii characters. + + + + Warns when non null assertion operator ! (or “bang” operator) is + used for a property access or method invocation. The operator check works at + runtime and it may fail and throw a runtime exception. + + + + Warns when call throw in a catch block. + + + + Warns when a public top-level member (except the entrypoint) is declared + inside a test file. + + + + Warns about unnecessary usage of is and whereType{' '} + operators. + + + + Warns about unnecessary usage of as operators. + + + + Warns about unrelated usages of is operators. + + + + Checks for unused parameters inside a function or method body. + + + + Configure some names that you want to ban. + + + + Warns when a literal value is on the left hand side in a binary expressions. + + + + Checks that double literals should begin with 0. instead of just{' '} + ., and should not end with a trailing 0. + + + + Prefer format comments like sentences. + + + + Enforces ordering for a class members. + + + + Enforces ordering for a class members. + + + + Enforces blank line between statements and return in a block. + + + + Warns on comparison to a boolean literal, as in x == true. + + + + Disallows empty blocks except catch clause block. + + + + Warns when equal arguments are passed to a function or method invocation. + + + + Warns when if statement has equal then and else statements or conditional + expression has equal then and else expressions. + + + + Warns against using number literals outside of named constants or variables. + + + + Warns when a class member is declared with Object type. + + + + Recommends to use async/await syntax to handle a{' '} + Future result instead of .then() invocation. + + + + Warns when // ignore: comments are left without any additional + description why this ignore is applied. + + + + Recommends to use a conditional expression instead of assigning to the same + thing or return statement in each branch of an if statement. + + + + Warns when an identifier name length is very short or long. + + + + Type name should only contain alphanumeric characters, start with an uppercase + character and span between min-length and max-length characters in length. + + + + Since Dart 2.15 it's possible to use byName method on enum{' '} + values prop instead of searching the value with{' '} + firstWhere. + + + + Use first to gets the first element. + + + + Warns when a method or a function returns a variable declared right before the + return statement. + + + + Use last to gets the last element. + + + + Warns when a file name does not match the class name. + + + + Checks for a trailing comma for arguments, parameters, enum values and + collections. + + + + Warns when a tag name does not match the class name. + + +## Flutter specific {#flutter-specific} + + + Warns when an event listener is added but never removed. + + + + Avoid using Border.all constructor. + + + + Warns when a method or function returns a Widget or subclass of a Widget. + + + + Warns when setState is called inside initState,{' '} + didUpdateWidget or build methods and when it is + called from a sync method that is called inside those methods. + + + + Warns when a widget is wrapped in a Padding widget but has a padding settings + by itself. + + + + Avoid using Expanded widget as Spacer. + + + + Warns when used non const border radius. + + + + Warns when used non const border radius. + + + + Warns about inline callbacks in a widget tree and suggest to extract them to a + widget method. + + + + Warns when a file contains more than a single widget. + + +## Intl specific {#intl-specific} + + + Recommends to use ClassName_ClassMemberName pattern for Intl + methods name argument. + + + + Warns when the Intl.message() invocation has incorrect args. + + +## Angular specific {#angular-specific} + + + Warns when a @Component annotation has explicit false value for{' '} + preserveWhitespace. + + + + Enforces Angular @Component annotation arguments ordering. + + + + Prefer setting changeDetection: ChangeDetectionStrategy.OnPush in + Angular @Component annotations. + diff --git a/website/src/components/RuleEntry.tsx b/website/src/components/RuleEntry.tsx new file mode 100644 index 0000000000..85952fd8d1 --- /dev/null +++ b/website/src/components/RuleEntry.tsx @@ -0,0 +1,56 @@ +import React from 'react'; +import CopyButton from './buttons/CopyButton'; + +type Props = { + name: string; + type: string; + version: string; + severity: string; + children: React.ReactNode; + hasConfig: boolean; + hasFix: boolean; + isDeprecated: boolean; +}; + +export default function RuleEntry({ + name, + type, + version, + severity, + children, + hasConfig, + hasFix, + isDeprecated, +}: Props) { + const severityLover = severity?.toLowerCase(); + const href = `${type}/${name}`; + + return ( +
+
+ + {name} + + + +

{children}

+ +
+
added in: {version}
+ +
+ {severityLover} +
+ +
+ {hasConfig && ⚙️} + + {hasFix && 🛠} + + {isDeprecated && ⚠️} +
+
+
+
+ ); +} diff --git a/website/src/components/buttons/CopyButton.tsx b/website/src/components/buttons/CopyButton.tsx new file mode 100644 index 0000000000..122f932fa7 --- /dev/null +++ b/website/src/components/buttons/CopyButton.tsx @@ -0,0 +1,32 @@ +import React from 'react'; + +export default function CopyButton({ link }) { + const handleClick = ( + event: React.MouseEvent + ) => { + event.preventDefault(); + window.navigator.clipboard.writeText(link); + }; + + return ( + + ); +} diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 7e30b7f8a7..29a4f721fe 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -82,4 +82,102 @@ footer .container { padding-right: 0; width: 100%; } + + .rule-description { + max-width: 80%; + } +} + +.rule-entry { + border-radius: 0.5rem; + padding: 1rem; + position: relative; + background: #00c6ff1f; + margin-bottom: 10px; +} + +.rule-content { + display: flex; + flex-direction: column; +} + +.rule-link { + font-weight: 600; + text-decoration: none; + margin-right: 8px; +} + +.rule-link span { + margin-right: 6px; +} + +.copy-button { + all: unset; + position: absolute; + width: 15px; + z-index: 1; + color: var(--docsearch-text-color); +} + +.rule-link::after { + position: absolute; + content: ''; + width: 100%; + height: 100%; + top: 0; + left: 0; +} + +.rule-description { + margin: 4px 0 0 0; + line-height: 20px; + font-size: 14px; +} + +.rule-description code { + vertical-align: unset; +} + +.rule-additional-info { + display: flex; + flex-direction: row; + align-items: center; + font-size: 13px; + margin-top: 12px; +} + +.rule-severity { + font-size: 13px; + margin-left: 12px; +} + +.rule-severity.error { + color: #e05258; +} + +.rule-severity.warning { + color: #fbad65; +} + +.rule-severity.style { + color: #399929; +} + +.rule-severity.performance { + color: #00c6ff; +} + +.rule-options { + width: 66px; + font-size: 20px; + display: flex; + gap: 5px; + margin-left: 12px; +} + +.rule-options span { + display: flex; + align-items: center; + justify-content: center; + height: 24px; }