refactor: improve on enforce-ref-last-prop ESLint rule docs (#8129)

**Related Issue:** #7669, #7659 ## Summary Refactor to improve on `enforce-ref-last-prop` ESLint rule docs. --------- Co-authored-by: JC Franco <[email protected]>
Esri · Nov 8, 2023 · 142dc20 · 142dc20
1 parent 051f332
commit 142dc20
Show file tree

Hide file tree

Showing 3 changed files with 5 additions and 5 deletions.
diff --git a/packages/eslint-plugin-calcite-components/README.md b/packages/eslint-plugin-calcite-components/README.md
@@ -51,7 +51,7 @@ This rule catches props/attributes that should be in the encapsulated HTML struc
 
 - [`@esri/calcite-components/enforce-ref-last-prop`](./docs/enforce-ref-last-prop.md)
 
-This rule ensures this is a workaround for a [Stencil bug](https://github.com/ionic-team/stencil/issues/4074) where ref is called in the specified order and not after initializing element with all its attributes/properties. This can cause attributes/properties to be outdated by the time the callback is invoked. This rule ensures the `ref` attribute is ordered last in a JSXElement to keep it up-to-date.
+This ensures the node passed into the `ref` callback is in sync with its JSX attributes/properties when invoked.
 
 - [`@esri/calcite-components/require-event-emitter-type`](./docs/require-event-emitter-type.md)
 

diff --git a/packages/eslint-plugin-calcite-components/docs/enforce-ref-last-prop.md b/packages/eslint-plugin-calcite-components/docs/enforce-ref-last-prop.md
@@ -1,8 +1,8 @@
 # enforce-ref-last-prop
 
-This updates `ref` usage to work around a Stencil bug where ref is called in the specified order and not after initializing element with all its attributes/properties. This can cause attributes/properties to be outdated by the time the callback is invoked.
+This ensures the node passed into the `ref` callback is in sync with its JSX attributes/properties when invoked.
 
-This rule ensures the `ref` attribute is ordered last in a JSXElement to keep it up-to-date.
+Placing `ref` last helps work around a [Stencil bug](https://github.com/ionic-team/stencil/issues/4074) where the `ref` callback is invoked in the specified order and not after initializing the element with all its attributes/properties. This can cause attributes/properties to be outdated by the time the callback is invoked.
 
 ## Config
 

diff --git a/packages/eslint-plugin-calcite-components/src/rules/enforce-ref-last-prop.ts b/packages/eslint-plugin-calcite-components/src/rules/enforce-ref-last-prop.ts
@@ -4,7 +4,7 @@ import type { JSXAttribute, JSXSpreadAttribute, JSXOpeningElement } from "@babel
 const rule: Rule.RuleModule = {
   meta: {
     docs: {
-      description: `This updates ref usage to work around a Stencil bug where ref is called in the specified order and not after initializing element with all its attributes/properties. This can cause attributes/properties to be outdated by the time the callback is invoked. This rule ensures the ref attribute is ordered last in a JSXElement to keep it up-to-date.`,
+      description: `This ensures the node passed into the ref callback is in sync with its JSX attributes/properties when invoked.`,
       recommended: true,
     },
     fixable: "code",
@@ -30,7 +30,7 @@ const rule: Rule.RuleModule = {
           if (refAttribute && attributes.indexOf(refAttribute) !== attributes.length - 1) {
             context.report({
               node,
-              message: `Attribute "ref" should be placed last in a JSXElement so node attrs/props are in sync. If it's called in the specified order, attributes/properties can be outdated by the time the callback is invoked.`,
+              message: `"ref" prop should be placed last in JSX to ensure the node attrs/props are in sync.`,
             });
           }
         }