diff --git a/packages/eslint-plugin-calcite-components/README.md b/packages/eslint-plugin-calcite-components/README.md index 55fa7dcec36..f7b92321b0f 100644 --- 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 index 88cd6a1508d..2017dc3caf3 100644 --- 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 index cf1eafe6f99..f7bebd46428 100644 --- 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.`, }); } }