Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

lint: forbid inline mergeRefs calls (#5269)

nynexman44648a055dfb3fe3
diff --git a/internal/eslint-plugin-astryx/README.md b/internal/eslint-plugin-astryx/README.md
index a57e14e470..c853b691aa 100644
--- a/internal/eslint-plugin-astryx/README.md
+++ b/internal/eslint-plugin-astryx/README.md
@@ -249,6 +249,34 @@ Style objects imported from another module are read from that module, so
rewrite that moves the styles onto the child. Removing a node can shift layout,
so it is never applied by `--fix`.
+### `@astryx/no-inline-merge-refs`
+
+Flags two unstable ref-composition patterns:
+
+1. `mergeRefs(...)` inside a JSX `ref` prop. Calling the utility during render
+ creates a new callback ref every time, so React detaches and reattaches the
+ element on unrelated rerenders.
+2. An inline callback passed to `useMergedRefs(...)`. The changing input makes
+ the hook recreate its callback on every render, defeating the hook.
+
+Use `useMergedRefs(...)` with stable ref inputs instead.
+
+```tsx
+// Bad
+<div ref={mergeRefs(forwardedRef, internalRef)} />;
+useMergedRefs(forwardedRef, node => setNode(node));
+
+// Good — the hook itself may be called inline when Hooks ordering is valid
+<div ref={useMergedRefs(forwardedRef, internalRef)} />;
+
+// Also good
+const ref = useMergedRefs(forwardedRef, internalRef);
+<div ref={ref} />;
+```
+
+The rule is an error in both tiers because core contains no inline
+`mergeRefs(...)` JSX callsites.
+
### `@astryx/require-letter-spacing`
Recommends adding `letterSpacing` when `fontSize` is defined (common design pattern for badges, labels).
diff --git a/internal/eslint-plugin-astryx/index.js b/internal/eslint-plugin-astryx/index.js
index 1791069e75..5e64105c9b 100644
--- a/internal/eslint-plugin-astryx/index.js
+++ b/internal/eslint-plugin-astryx/index.js
@@ -17,6 +17,7 @@
* - no-hover-on-disabled: Flags a :hover condition that can still match a disabled element (browsers suppress a disabled control's events, not its hover styling)
* - require-table-section: Requires TableRow/tr to sit inside TableHeader/TableBody/TableFooter (a row directly inside a table emits <table><tr>, which browsers repair on parse and React does not)
* - disabled-cursor: Flags a cursor that promises an interaction without giving way to not-allowed on a disabled element
+ * - no-inline-merge-refs: Flags mergeRefs calls inside JSX ref props (use useMergedRefs for stable identity)
*
* Philosophy: Strict for agents (CI), lenient for humans (local dev)
* - "strict" config: All rules as errors - use in CI/agent environments
@@ -43,6 +44,7 @@ import focusOutlineSharedRule from './focus-outline-shared.js';
import noHoverOnDisabledRule from './no-hover-on-disabled.js';
import disabledCursorRule from './disabled-cursor.js';
import noReactNamespaceHooksRule from './no-react-namespace-hooks.js';
+import noInlineMergeRefsRule from './no-inline-merge-refs.js';
import copyrightHeaderRule from './copyright-header.js';
import noRawConsoleCliRule from './no-raw-console-cli.js';
import requireBasePropsRule from './require-base-props.js';
@@ -270,6 +272,7 @@ const plugin = {
'no-hover-on-disabled': noHoverOnDisabledRule,
'disabled-cursor': disabledCursorRule,
'no-react-namespace-hooks': noReactNamespaceHooksRule,
+ 'no-inline-merge-refs': noInlineMergeRefsRule,
'require-base-props': requireBasePropsRule,
'require-ref-prop': requireRefPropRule,
'copyright-header': copyrightHeaderRule,
@@ -338,6 +341,7 @@ plugin.configs.strict = {
// honour. Error in both tiers, and autofixable.
'@astryx/disabled-cursor': 'error',
'@astryx/no-react-namespace-hooks': 'error',
+ '@astryx/no-inline-merge-refs': 'error',
'@astryx/require-base-props': 'error',
'@astryx/require-ref-prop': 'error',
'@astryx/copyright-header': 'error',
@@ -395,6 +399,7 @@ plugin.configs.recommended = {
// honour. Error in both tiers, and autofixable.
'@astryx/disabled-cursor': 'error',
'@astryx/no-react-namespace-hooks': 'error',
+ '@astryx/no-inline-merge-refs': 'error',
'@astryx/require-base-props': 'warn',
'@astryx/require-ref-prop': 'warn',
'@astryx/copyright-header': 'error',
diff --git a/internal/eslint-plugin-astryx/no-inline-merge-refs.js b/internal/eslint-plugin-astryx/no-inline-merge-refs.js
new file mode 100644
index 0000000000..c870e59be9
--- /dev/null
+++ b/internal/eslint-plugin-astryx/no-inline-merge-refs.js
@@ -0,0 +1,87 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file no-inline-merge-refs.js
+ * @description Prevents unstable ref composition during render.
+ */
+
+const noInlineMergeRefsRule = {
+ meta: {
+ type: 'problem',
+ docs: {
+ description:
+ 'Prevent render-inline mergeRefs calls and unstable callback arguments to useMergedRefs',
+ category: 'Astryx Conventions',
+ recommended: true,
+ },
+ messages: {
+ useHook:
+ 'Do not call mergeRefs inside a JSX ref prop. Use useMergedRefs so the callback ref remains stable across rerenders.',
+ stableInput:
+ 'Do not pass an inline callback to useMergedRefs. Pass a stable ref directly or memoize the callback first.',
+ },
+ schema: [],
+ },
+ create(context) {
+ const importedMergeRefs = new Set();
+ const importedUseMergedRefs = new Set();
+
+ function isInsideRefAttribute(node) {
+ let current = node.parent;
+ while (current) {
+ if (current.type === 'JSXExpressionContainer') {
+ const attribute = current.parent;
+ return (
+ attribute?.type === 'JSXAttribute' &&
+ attribute.name?.type === 'JSXIdentifier' &&
+ attribute.name.name === 'ref'
+ );
+ }
+ current = current.parent;
+ }
+ return false;
+ }
+
+ return {
+ ImportDeclaration(node) {
+ for (const specifier of node.specifiers) {
+ if (
+ specifier.type !== 'ImportSpecifier' ||
+ specifier.imported.type !== 'Identifier'
+ ) {
+ continue;
+ }
+ if (specifier.imported.name === 'mergeRefs') {
+ importedMergeRefs.add(specifier.local.name);
+ } else if (specifier.imported.name === 'useMergedRefs') {
+ importedUseMergedRefs.add(specifier.local.name);
+ }
+ }
+ },
+ CallExpression(node) {
+ if (node.callee.type !== 'Identifier') {
+ return;
+ }
+ if (
+ importedMergeRefs.has(node.callee.name) &&
+ isInsideRefAttribute(node)
+ ) {
+ context.report({node, messageId: 'useHook'});
+ return;
+ }
+ if (importedUseMergedRefs.has(node.callee.name)) {
+ for (const argument of node.arguments) {
+ if (
+ argument.type === 'ArrowFunctionExpression' ||
+ argument.type === 'FunctionExpression'
+ ) {
+ context.report({node: argument, messageId: 'stableInput'});
+ }
+ }
+ }
+ },
+ };
+ },
+};
+
+export default noInlineMergeRefsRule;
diff --git a/internal/eslint-plugin-astryx/no-inline-merge-refs.test.mjs b/internal/eslint-plugin-astryx/no-inline-merge-refs.test.mjs
new file mode 100644
index 0000000000..f320198eec
--- /dev/null
+++ b/internal/eslint-plugin-astryx/no-inline-merge-refs.test.mjs
@@ -0,0 +1,93 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file no-inline-merge-refs.test.mjs
+ */
+
+import {RuleTester} from 'eslint';
+import rule from './no-inline-merge-refs.js';
+
+const ruleTester = new RuleTester({
+ languageOptions: {
+ ecmaVersion: 2022,
+ sourceType: 'module',
+ parserOptions: {ecmaFeatures: {jsx: true}},
+ },
+});
+
+ruleTester.run('no-inline-merge-refs', rule, {
+ valid: [
+ {
+ code: `
+ import {useMergedRefs} from '../hooks';
+ const ref = useMergedRefs(forwardedRef, internalRef);
+ <div ref={ref} />;
+ `,
+ },
+ {
+ code: `
+ import {useMergedRefs} from '../hooks';
+ <div ref={useMergedRefs(forwardedRef, internalRef)} />;
+ `,
+ },
+ {
+ code: `
+ import {mergeRefs} from '../utils';
+ function createRef() {
+ const ref = mergeRefs(forwardedRef, internalRef);
+ return ref;
+ }
+ `,
+ },
+ {
+ code: `
+ function mergeRefs() {}
+ <div ref={mergeRefs(forwardedRef, internalRef)} />;
+ `,
+ },
+ {
+ code: '<div ref={callbackRef} />;',
+ },
+ ],
+ invalid: [
+ {
+ code: `
+ import {mergeRefs} from '../utils';
+ <div ref={mergeRefs(forwardedRef, internalRef)} />;
+ `,
+ errors: [{messageId: 'useHook'}],
+ },
+ {
+ code: `
+ import {mergeRefs as combineRefs} from '@astryxdesign/core/utils';
+ <div ref={combineRefs(forwardedRef, internalRef)} />;
+ `,
+ errors: [{messageId: 'useHook'}],
+ },
+ {
+ code: `
+ import {mergeRefs} from '../utils';
+ <div
+ ref={enabled ? mergeRefs(forwardedRef, internalRef) : forwardedRef}
+ />;
+ `,
+ errors: [{messageId: 'useHook'}],
+ },
+ {
+ code: `
+ import {useMergedRefs} from '../hooks';
+ useMergedRefs(forwardedRef, node => setNode(node));
+ `,
+ errors: [{messageId: 'stableInput'}],
+ },
+ {
+ code: `
+ import {useMergedRefs as combineRefs} from '@astryxdesign/core/hooks';
+ combineRefs(forwardedRef, function (node) { setNode(node); });
+ `,
+ errors: [{messageId: 'stableInput'}],
+ },
+ ],
+});
+
+console.log('All tests passed!');
diff --git a/packages/core/src/DateInput/TouchDateField.tsx b/packages/core/src/DateInput/TouchDateField.tsx
index 1a6f05dd65..ae5f6b6677 100644
--- a/packages/core/src/DateInput/TouchDateField.tsx
+++ b/packages/core/src/DateInput/TouchDateField.tsx
@@ -67,7 +67,7 @@ import {
inputStatusHoverShadowStyles,
inputStatusFocusWithinStyles,
} from '../Field';
-import {useInputStatusIcon} from '../hooks';
+import {useInputStatusIcon, useMergedRefs} from '../hooks';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {Icon} from '../Icon';
import {IconButton} from '../IconButton';
@@ -96,7 +96,6 @@ import {
getInputARIA,
isImeKeyEvent,
mergeProps,
- mergeRefs,
rtlStyles,
themeProps,
formatSharedDate,
@@ -557,6 +556,7 @@ export function TouchDateField({
const descriptionID = useId();
const statusMessageID = useId();
const inputRef = useRef<HTMLInputElement | null>(null);
+ const mergedInputRef = useMergedRefs(ref, inputRef);
const inputGroup = useInputGroup();
const [, startTransition] = useTransition();
@@ -1169,7 +1169,7 @@ export function TouchDateField({
/>
</button>
<input
- ref={mergeRefs(ref, inputRef)}
+ ref={mergedInputRef}
id={id}
type="text"
role="combobox"