An open source design system that's fully customizable and agent ready
TypeScript
fix: add stable merged refs (#5266)
nynexman4464fac29533c652
diff --git a/.changeset/stable-text-refs.md b/.changeset/stable-text-refs.mdnew file mode 100644index 0000000000..70f39ed7cf--- /dev/null+++ b/.changeset/stable-text-refs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Add useMergedRefs and keep Text and Heading refs stable across rerenders.++@nynexman4464diff --git a/packages/core/src/Heading/Heading.test.tsx b/packages/core/src/Heading/Heading.test.tsxindex 9c0fe00f0c..e1158fa6c1 100644--- a/packages/core/src/Heading/Heading.test.tsx+++ b/packages/core/src/Heading/Heading.test.tsx@@ -6,7 +6,7 @@*/import {render, screen} from '@testing-library/react';-import {describe, it, expect} from 'vitest';+import {describe, it, expect, vi} from 'vitest';import {Heading} from './Heading';describe('Heading', () => {@@ -16,6 +16,28 @@ describe('Heading', () => {expect(screen.getByText('Page Title')).toBeInTheDocument();});+ it('keeps a forwarded ref attached across rerenders', () => {+ const ref = vi.fn();+ const {rerender} = render(+ <Heading ref={ref} level={1}>+ Before+ </Heading>,+ );++ const element = screen.getByText('Before');+ expect(ref).toHaveBeenLastCalledWith(element);+ ref.mockClear();++ rerender(+ <Heading ref={ref} level={1}>+ After+ </Heading>,+ );++ expect(ref).not.toHaveBeenCalled();+ expect(screen.getByText('After')).toBe(element);+ });+it('renders h1 for level 1', () => {render(<Heading level={1}>H1</Heading>);const element = screen.getByText('H1');diff --git a/packages/core/src/Heading/Heading.tsx b/packages/core/src/Heading/Heading.tsxindex b702a03eab..5d6858a4c6 100644--- a/packages/core/src/Heading/Heading.tsx+++ b/packages/core/src/Heading/Heading.tsx@@ -43,7 +43,8 @@ import {import {useTruncation} from '../Text/useTruncation';import {resolveStyleColor} from '../Text/Text';import type {LayerPlacement} from '../Layer';-import {mergeProps, mergeRefs} from '../utils';+import {mergeProps} from '../utils';+import {useMergedRefs} from '../hooks/useMergedRefs';import type {BaseProps} from '../BaseProps';import {themeProps} from '../utils/themeProps';@@ -242,13 +243,16 @@ export function Heading({// Ref for the heading element (used as tooltip anchor)const headingRef = useRef<HTMLHeadingElement>(null);+ // Keep the merged ref stable across rerenders.+ const mergedRef = useMergedRefs(ref, truncation.ref, headingRef);+// Build inline style for -webkit-line-clamp (dynamic value)const inlineStyle = maxLines > 1 ? {WebkitLineClamp: maxLines} : undefined;return (<><Component- ref={mergeRefs(ref, truncation.ref, headingRef)}+ ref={mergedRef}{...mergeProps(themeProps('heading', {level, color, ...(type && {type})}),stylex.props(diff --git a/packages/core/src/Text/Text.test.tsx b/packages/core/src/Text/Text.test.tsxindex 043329718f..1e65c081c9 100644--- a/packages/core/src/Text/Text.test.tsx+++ b/packages/core/src/Text/Text.test.tsx@@ -6,7 +6,7 @@*/import {render, screen} from '@testing-library/react';-import {describe, it, expect} from 'vitest';+import {describe, it, expect, vi} from 'vitest';import {Text} from './Text';import type {TextType} from './Text';import type {TextColor} from '../theme/types';@@ -23,6 +23,28 @@ describe('Text', () => {expect(screen.getByText('Hello World')).toBeInTheDocument();});+ it('keeps a forwarded ref attached across rerenders', () => {+ const ref = vi.fn();+ const {rerender} = render(+ <Text ref={ref} type="body">+ Before+ </Text>,+ );++ const element = screen.getByText('Before');+ expect(ref).toHaveBeenLastCalledWith(element);+ ref.mockClear();++ rerender(+ <Text ref={ref} type="body">+ After+ </Text>,+ );++ expect(ref).not.toHaveBeenCalled();+ expect(screen.getByText('After')).toBe(element);+ });+it('renders as span by default', () => {render(<Text type="body">Text</Text>);const element = screen.getByText('Text');diff --git a/packages/core/src/Text/Text.tsx b/packages/core/src/Text/Text.tsxindex 4abd88d5c4..9a130df9ac 100644--- a/packages/core/src/Text/Text.tsx+++ b/packages/core/src/Text/Text.tsx@@ -48,7 +48,8 @@ import {} from './text.stylex';import {useTruncation} from './useTruncation';import type {LayerPlacement} from '../Layer';-import {mergeProps, mergeRefs} from '../utils';+import {mergeProps} from '../utils';+import {useMergedRefs} from '../hooks/useMergedRefs';import type {BaseProps} from '../BaseProps';import {themeProps} from '../utils/themeProps';@@ -271,13 +272,16 @@ export function Text({// Ref for the text element (used as tooltip anchor)const textRef = useRef<HTMLElement>(null);+ // Keep the merged ref stable across rerenders.+ const mergedRef = useMergedRefs(ref, truncation.ref, textRef);+// Build inline style for -webkit-line-clamp (dynamic value)const inlineStyle = maxLines > 1 ? {WebkitLineClamp: maxLines} : undefined;return (<><Component- ref={mergeRefs(ref, truncation.ref, textRef)}+ ref={mergedRef}{...mergeProps(themeProps('text', {type, size, color: resolvedColor}),stylex.props(diff --git a/packages/core/src/hooks/index.ts b/packages/core/src/hooks/index.tsindex ad14642941..5796d2bb32 100644--- a/packages/core/src/hooks/index.ts+++ b/packages/core/src/hooks/index.ts@@ -56,6 +56,8 @@ export type {UseTypeaheadOptions, UseTypeaheadReturn} from './useTypeahead';export {useMediaQuery} from './useMediaQuery';+export {useMergedRefs} from './useMergedRefs';+export {useOverflow} from './useOverflow';export type {UseOverflowOptions, UseOverflowReturn} from './useOverflow';diff --git a/packages/core/src/hooks/useMergedRefs.doc.mjs b/packages/core/src/hooks/useMergedRefs.doc.mjsnew file mode 100644index 0000000000..074bf37c78--- /dev/null+++ b/packages/core/src/hooks/useMergedRefs.doc.mjs@@ -0,0 +1,79 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').HookDoc} */+export const docs = {+ name: 'useMergedRefs',+ displayName: 'useMergedRefs',+ keywords: [+ 'ref',+ 'refs',+ 'merge',+ 'forwardRef',+ 'callback ref',+ 'stable ref',+ ],+ params: [+ {+ name: 'refs',+ type: 'Array<Ref<T> | undefined>',+ description: 'Up to six refs that should all receive the same element.',+ required: true,+ },+ ],+ returns: [+ {+ name: 'ref',+ type: 'RefCallback<T>',+ description:+ 'A merged callback ref that remains stable until an input ref changes.',+ },+ ],+ usage: {+ description:+ 'Combines multiple object or callback refs into one stable callback ref. Use it when a component must forward a consumer ref while also attaching internal refs. Unlike calling mergeRefs during render, the callback identity stays stable across unrelated rerenders, so React does not detach and reattach the element.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Use useMergedRefs when one element must receive both a forwarded ref and one or more internal refs.',+ },+ {+ guidance: false,+ description:+ 'Call mergeRefs directly in a JSX ref prop; that creates a new callback on every render and forces unnecessary detach and attach work.',+ },+ ],+ },+ relatedComponents: [],+ relatedHooks: [],+ importPath: '@astryxdesign/core/hooks',+ category: 'utility',+};++/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */+export const docsDense = {+ description:+ 'Combines object/callback refs into one stable callback ref. Identity changes only when an input ref changes, avoiding detach/attach churn from inline mergeRefs calls.',+ paramDescriptions: {+ refs: 'refs that should all receive the same element.',+ },+ returnDescriptions: {+ ref: 'stable merged callback ref; changes only when an input ref changes.',+ },+ usage: {+ description:+ 'Use when one element needs a forwarded consumer ref plus internal refs. Keeps the callback stable across unrelated rerenders.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Use for a forwarded ref plus internal measurement, focus, or anchor refs.',+ },+ {+ guidance: false,+ description:+ 'Call mergeRefs inline in JSX; it forces ref detach/attach on every render.',+ },+ ],+ },+};diff --git a/packages/core/src/hooks/useMergedRefs.test.tsx b/packages/core/src/hooks/useMergedRefs.test.tsxnew file mode 100644index 0000000000..4c97f8f0d8--- /dev/null+++ b/packages/core/src/hooks/useMergedRefs.test.tsx@@ -0,0 +1,62 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file useMergedRefs.test.tsx+ * @input Uses vitest, @testing-library/react, useMergedRefs hook+ * @output Unit tests for stable merged ref behavior+ * @position Testing; validates useMergedRefs.ts+ *+ * SYNC: When useMergedRefs.ts changes, update tests to match new behavior+ */++import {renderHook} from '@testing-library/react';+import {createRef} from 'react';+import {describe, expect, it, vi} from 'vitest';+import {useMergedRefs} from './useMergedRefs';++describe('useMergedRefs', () => {+ it('forwards values to callback and object refs', () => {+ const callbackRef = vi.fn();+ const objectRef = createRef<HTMLDivElement>();+ const {result} = renderHook(() =>+ useMergedRefs<HTMLDivElement>(callbackRef, objectRef),+ );+ const element = document.createElement('div');++ const cleanup = result.current(element);++ expect(callbackRef).toHaveBeenCalledWith(element);+ expect(objectRef.current).toBe(element);++ cleanup?.();+ expect(callbackRef).toHaveBeenLastCalledWith(null);+ expect(objectRef.current).toBeNull();+ });++ it('keeps the merged callback stable when input refs are unchanged', () => {+ const callbackRef = vi.fn();+ const objectRef = createRef<HTMLDivElement>();+ const {result, rerender} = renderHook(() =>+ useMergedRefs<HTMLDivElement>(callbackRef, objectRef),+ );+ const first = result.current;++ rerender();++ expect(result.current).toBe(first);+ });++ it('updates the merged callback when an input ref changes', () => {+ const firstRef = vi.fn();+ const secondRef = vi.fn();+ const {result, rerender} = renderHook(+ ({ref}) => useMergedRefs<HTMLDivElement>(ref),+ {initialProps: {ref: firstRef}},+ );+ const first = result.current;++ rerender({ref: secondRef});++ expect(result.current).not.toBe(first);+ });+});diff --git a/packages/core/src/hooks/useMergedRefs.ts b/packages/core/src/hooks/useMergedRefs.tsnew file mode 100644index 0000000000..c3f7ce9a83--- /dev/null+++ b/packages/core/src/hooks/useMergedRefs.ts@@ -0,0 +1,36 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file useMergedRefs.ts+ * @input React refs to combine into one stable callback ref+ * @output Exports useMergedRefs+ * @position Core hook; use when one element must receive multiple refs+ *+ * SYNC: When modified, update:+ * - /packages/core/src/hooks/index.ts+ * - /packages/core/src/hooks/useMergedRefs.doc.mjs+ * - /packages/core/src/hooks/useMergedRefs.test.tsx+ */++import {useMemo, type Ref, type RefCallback} from 'react';+import {mergeRefs} from '../utils/mergeRefs';++/**+ * Combine up to six refs into a callback ref whose identity changes only when+ * one of the input refs changes.+ */+export function useMergedRefs<T>(+ refA?: Ref<T>,+ refB?: Ref<T>,+ refC?: Ref<T>,+ refD?: Ref<T>,+ refE?: Ref<T>,+ refF?: Ref<T>,+): RefCallback<T> {+ return useMemo(+ () => mergeRefs(refA, refB, refC, refD, refE, refF),+ [refA, refB, refC, refD, refE, refF],+ );+}