feat: add React 19 support with backward compatibility for React 18.3+ (#66)

hectoruch · web-flow · commit 5d96a78de82e · 2026-02-12T14:59:52.000+01:00
- Update peerDependencies to support React 18.3.0 || 19.0.0
- Upgrade devDependencies to React 19.2.4 and @types/react 19.2.14
- Add global JSX namespace declaration for React 19 compatibility
- Fix 30+ files with RefObject&lt;T | null&gt; types for React 19 stricter typing
- Add explicit initial values to useRef() calls (React 19 requirement)
- Fix 6 test errors related to ref callbacks and mock RefObjects
- Add pnpm overrides for eslint-plugin-react-hooks canary version (ESLint 10 compatibility)
- Add zod-validation-error override to resolve ESLint 10 package exports issue

Affected packages:
- @kubit-ui-web/react-components
- @kubit-ui-web/design-system (types only)
- @kubit-ui-web/storybook

TypeScript errors: 56 → 0 ✅

The library maintains full compatibility with React 18.3+ while supporting React 19.
No React 19 exclusive features are used to preserve backward compatibility.
diff --git a/package.json b/package.json
@@ -25,7 +25,13 @@
   "engines": {
     "node": "22.x"
   },
-  "packageManager": "pnpm@10.28.1",
+  "packageManager": "pnpm@10.29.3",
+  "pnpm": {
+    "overrides": {
+      "eslint-plugin-react-hooks": "7.1.0-canary-272441a9-20260209",
+      "zod-validation-error": "^3.4.0"
+    }
+  },
   "scripts": {
     "dev": "turbo run dev --filter=@kubit-ui-web/storybook",
     "dev:components": "turbo run dev --filter=@kubit-ui-web/react-components",
@@ -78,7 +84,7 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
-    "turbo": "^2.8.1"
+    "turbo": "^2.8.7"
   },
   "bugs": {
     "url": "https://github.com/kubit-ui/kubit-react-components/issues",
diff --git a/packages/components/package.json b/packages/components/package.json
@@ -166,8 +166,8 @@
     "prerelease": "pnpm validate && pnpm test"
   },
   "peerDependencies": {
-    "react": ">=17.0.0 || >=18.3.1",
-    "react-dom": ">=17.0.0 || >=18.3.1"
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0"
   },
   "dependencies": {
     "@floating-ui/dom": "^1.7.5"
@@ -180,8 +180,8 @@
     "@testing-library/user-event": "^14.6.1",
     "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@types/node": "^25.2.3",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "@types/testing-library__jest-dom": "^6.0.0",
     "@vitejs/plugin-react": "^5.1.4",
     "@vitest/coverage-v8": "^4.0.18",
@@ -193,8 +193,8 @@
     "html-validate": "^10.7.0",
     "jsdom": "^28.0.0",
     "prettier": "^3.8.1",
-    "react": "18.3.1",
-    "react-dom": "18.3.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.55.0",
     "vite": "8.0.0-beta.10",
diff --git a/packages/components/src/components/accordion/hooks/useAccordionContentOverflow.ts b/packages/components/src/components/accordion/hooks/useAccordionContentOverflow.ts
@@ -1,7 +1,7 @@
 import { type RefObject, useEffect, useRef } from 'react';
 
 interface UseAccordionContentOverflowParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
   expanded: boolean;
 }
 
diff --git a/packages/components/src/components/accordion/hooks/useAccordionInertContent.ts b/packages/components/src/components/accordion/hooks/useAccordionInertContent.ts
@@ -1,7 +1,7 @@
 import { type RefObject, useEffect } from 'react';
 
 interface UseAccordionInertContentParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
   expanded: boolean;
 }
 
diff --git a/packages/components/src/components/carousel/__tests__/carousel.test.tsx b/packages/components/src/components/carousel/__tests__/carousel.test.tsx
@@ -1,12 +1,12 @@
 import { act } from 'react';
+
 import { axe } from 'vitest-axe';
 
 import { render } from '@/lib/tests/render/render';
 
-import type { ICarousel } from '../types/carousel';
-
 import { Carousel } from '../carousel';
 import { useCarousel } from '../hooks/useCarousel';
+import type { ICarousel } from '../types/carousel';
 
 const mockProps: ICarousel = {
   elements: [
@@ -28,7 +28,7 @@ const mockUseCarousel = vi.mocked(useCarousel);
 
 describe('Carousel component', () => {
   it('Should render carousel component', async () => {
-    const { container } = render(<Carousel {...mockProps} ref={() => ({})} />);
+    const { container } = render(<Carousel {...mockProps} ref={() => {}} />);
 
     const results = await axe(container);
     expect(container).toHTMLValidate({
@@ -43,7 +43,7 @@ describe('Carousel component', () => {
     render(
       <Carousel
         {...mockProps}
-        ref={() => ({})}
+        ref={() => {}}
         numElementsPerPage={mockProps.elements.length + 2}
       />,
     );
@@ -59,7 +59,7 @@ describe('Carousel component', () => {
     render(
       <Carousel
         {...mockProps}
-        ref={() => ({})}
+        ref={() => {}}
         allowModifySliceWidth={true}
         numElementsPerPage={0}
       />,
@@ -76,7 +76,7 @@ describe('Carousel component', () => {
     render(
       <Carousel
         {...mockProps}
-        ref={() => ({})}
+        ref={() => {}}
         allowModifySliceWidth={true}
         autoFitContainer={true}
         numElementsPerPage={5}
diff --git a/packages/components/src/components/carousel/hooks/types/useCarousel.ts b/packages/components/src/components/carousel/hooks/types/useCarousel.ts
@@ -4,9 +4,9 @@ import type {
 } from '../../types/carousel';
 
 export interface IUseCarouselParams {
-  rootContainerRef: React.RefObject<HTMLDivElement>;
-  viewerContainerRef: React.RefObject<HTMLDivElement>;
-  contentContainerRef: React.RefObject<HTMLDivElement>;
+  rootContainerRef: React.RefObject<HTMLDivElement | null>;
+  viewerContainerRef: React.RefObject<HTMLDivElement | null>;
+  contentContainerRef: React.RefObject<HTMLDivElement | null>;
   circular?: boolean;
   centerMode?: boolean;
   extraPadding?: number;
diff --git a/packages/components/src/components/carousel/hooks/types/useCarouselKeyNavigation.ts b/packages/components/src/components/carousel/hooks/types/useCarouselKeyNavigation.ts
@@ -1,5 +1,5 @@
 export interface IUseCarouselKeyNavigationParams {
-  rootContainerRef: React.RefObject<HTMLDivElement>;
+  rootContainerRef: React.RefObject<HTMLDivElement | null>;
   allowShiftRef: React.MutableRefObject<boolean>;
   circular: boolean;
   numPagesRef: React.MutableRefObject<number>;
diff --git a/packages/components/src/components/carousel/hooks/types/useCarouselSwipe.ts b/packages/components/src/components/carousel/hooks/types/useCarouselSwipe.ts
@@ -1,6 +1,6 @@
 export interface IUseCarouselSwipeParams {
-  viewerContainerRef: React.RefObject<HTMLDivElement>;
-  contentContainerRef: React.RefObject<HTMLDivElement>;
+  viewerContainerRef: React.RefObject<HTMLDivElement | null>;
+  contentContainerRef: React.RefObject<HTMLDivElement | null>;
   allowShiftRef: React.MutableRefObject<boolean>;
   circular: boolean;
   extraPadding: number;
diff --git a/packages/components/src/components/carousel/hooks/useCarouselSwipe.ts b/packages/components/src/components/carousel/hooks/useCarouselSwipe.ts
@@ -3,7 +3,6 @@ import { useCallback, useEffect, useRef } from 'react';
 import { useScrollBlock } from '@/lib/hooks/useScrollBlock/useScrollBlock';
 
 import type { IUseCarouselSwipe } from './types/useCarouselSwipe';
-
 import calcUtils from './utils/calc.utils';
 import CONSTANTS from './utils/constants';
 
@@ -25,7 +24,7 @@ export const useCarouselSwipe: IUseCarouselSwipe = ({
   const isDragging = useRef(false);
   const isHorizontalDragging = useRef(false);
   const isVerticalDragging = useRef(false);
-  const posInitial = useRef<number | undefined>();
+  const posInitial = useRef<number | undefined>(undefined);
   const posX1 = useRef(0);
   const posX2 = useRef(0);
   const posXInitial = useRef(0);
diff --git a/packages/components/src/components/carousel/types/carousel.ts b/packages/components/src/components/carousel/types/carousel.ts
@@ -23,8 +23,8 @@ export type CarouselScreenReaderOnlyType = Omit<
 
 export interface ICarouselStandAlone extends DataAttributes {
   cssClasses?: CarouselCssClasses;
-  viewerContainerRef: React.RefObject<HTMLDivElement>;
-  contentContainerRef: React.RefObject<HTMLDivElement>;
+  viewerContainerRef: React.RefObject<HTMLDivElement | null>;
+  contentContainerRef: React.RefObject<HTMLDivElement | null>;
   elements: JSX.Element[];
   screenReaderOnly?: CarouselScreenReaderOnlyType;
   allowModifySliceWidth?: boolean;
diff --git a/packages/components/src/components/dataTable/hooks/useDataTableHasScroll.ts b/packages/components/src/components/dataTable/hooks/useDataTableHasScroll.ts
@@ -3,7 +3,7 @@ import { type RefObject, useEffect, useState } from 'react';
 import { hasScroll as checkHasSroll } from '../../../lib/utils/scroll/hasScroll';
 
 interface UseDataTableHasScrollParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
 }
 
 interface UseDataTableHasScrollReturnType {
diff --git a/packages/components/src/components/dataTable/hooks/useDataTableShadow.ts b/packages/components/src/components/dataTable/hooks/useDataTableShadow.ts
@@ -1,7 +1,7 @@
 import { type RefObject, useEffect } from 'react';
 
 interface UseDataTableShadowParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
   headBoxShadow?: string;
   leftBoxShadow?: string;
   rightBoxShadow?: string;
diff --git a/packages/components/src/components/dataTable/hooks/useDataTableStickyDividers.ts b/packages/components/src/components/dataTable/hooks/useDataTableStickyDividers.ts
@@ -3,7 +3,7 @@ import { type RefObject, useEffect } from 'react';
 import { hasHorizontalScroll } from '../../../lib/utils/scroll/hasScroll';
 
 interface UseDataTableStickyDividersParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
 }
 
 type UseDataTableStickyDividersReturnType = object;
diff --git a/packages/components/src/components/dataTable/hooks/useDataTableStickyLeftColumns.ts b/packages/components/src/components/dataTable/hooks/useDataTableStickyLeftColumns.ts
@@ -3,7 +3,7 @@ import { type RefObject, useEffect } from 'react';
 import { hasHorizontalScroll } from '../../../lib/utils/scroll/hasScroll';
 
 interface UseDataTableStickyLeftColumnsParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
 }
 
 type UseDataTableStickyLeftColumnsReturnType = object;
diff --git a/packages/components/src/components/dataTable/hooks/useDataTableStickyRightColumns.ts b/packages/components/src/components/dataTable/hooks/useDataTableStickyRightColumns.ts
@@ -6,7 +6,7 @@ import {
 } from '../../../lib/utils/scroll/hasScroll';
 
 interface UseDataTableStickyRightColumnsParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
 }
 
 type UseDataTableStickyRightColumnsReturnType = object;
diff --git a/packages/components/src/components/inputSignature/hook/useDraw.tsx b/packages/components/src/components/inputSignature/hook/useDraw.tsx
@@ -23,8 +23,9 @@ function isImageDataEqual(a: ImageData, b: ImageData) {
 
 export const useDraw = (onChange?: (value: string) => void): ReturnType => {
   const canvasRef = useRef<HTMLCanvasElement | null>(null);
-  const context =
-    useRef<CanvasRenderingContext2D>() as React.MutableRefObject<CanvasRenderingContext2D>;
+  const context = useRef<CanvasRenderingContext2D | null>(
+    null,
+  ) as React.MutableRefObject<CanvasRenderingContext2D>;
   const isDrawing = useRef<boolean>(false);
   const isFilled = useRef<boolean>(false);
   const signatureStylesRef = useRef<InputSignatureLineStyles>({
diff --git a/packages/components/src/components/inputSignature/types/inputSignature.ts b/packages/components/src/components/inputSignature/types/inputSignature.ts
@@ -26,7 +26,7 @@ export interface InputSignatureCustomHandle {
  */
 export interface InputSignatureStandAloneProps extends DataAttributes {
   state: InputSignatureState;
-  canvasRef: React.RefObject<HTMLCanvasElement>;
+  canvasRef: React.RefObject<HTMLCanvasElement | null>;
   placeholder: CommonTextProps;
   errorText?: CommonTextProps;
   onClickContainer: (e: React.MouseEvent<HTMLDivElement>) => void;
diff --git a/packages/components/src/components/option/option.tsx b/packages/components/src/components/option/option.tsx
@@ -11,9 +11,8 @@ import {
 import { useClassName } from '@/lib/hooks/useClassName/useClassName';
 import { useGenericComponents } from '@/lib/provider/genericComponentsProvider/genericComponentsProvider';
 
-import type { OptionProps } from './types/option';
-
 import { OptionStandAlone } from './optionStandAlone';
+import type { OptionProps } from './types/option';
 
 /**
  * Option component for rendering selectable list items.
@@ -52,7 +51,7 @@ export const Option = forwardRef(
     });
 
     const { LINK: genericLinkComponent } = useGenericComponents();
-    const innerRef = useRef<HTMLElement>();
+    const innerRef = useRef<HTMLElement | null>(null);
     const [hover, setHover] = useState(false);
     const [focused, setFocused] = useState(false);
 
diff --git a/packages/components/src/components/popover/__tests__/hooks/usePopoverInteractions.test.ts b/packages/components/src/components/popover/__tests__/hooks/usePopoverInteractions.test.ts
@@ -19,7 +19,9 @@ vi.mock('@/utils/keyboard/keyboard', () => ({
 const mockOnClose = vi.fn();
 
 // Mock refs for testing
-const createMockRef = <T>(initialValue: T | null = null): RefObject<T> => ({
+const createMockRef = <T>(
+  initialValue: T | null = null,
+): RefObject<T | null> => ({
   current: initialValue,
 });
 
diff --git a/packages/components/src/components/popover/hooks/types/usePopoverLifecycle.ts b/packages/components/src/components/popover/hooks/types/usePopoverLifecycle.ts
@@ -12,7 +12,7 @@ interface IUsePopoverLifecycleParams {
 export interface IUsePopoverLifecycleResponse {
   isClosing: boolean;
   isVisible: boolean;
-  popoverRef: React.RefObject<HTMLElement>;
+  popoverRef: React.RefObject<HTMLElement | null>;
   handleInnerRef: (node: HTMLElement | null) => void;
 }
 
diff --git a/packages/components/src/components/select/types/select.ts b/packages/components/src/components/select/types/select.ts
@@ -48,13 +48,13 @@ export interface SelectStandAloneProps extends DataAttributes {
   listOptions: SelectListOptionsProps;
   optionSelected?: string;
   onOptionClick: (value: string) => void;
-  listOptionsRef: RefObject<HTMLDivElement>;
+  listOptionsRef: RefObject<HTMLDivElement | null>;
   closePopoverOnScroll?: boolean;
   openAndCloseOnHover?: boolean;
   url?: string;
   urlTarget?: HTMLAttributeAnchorTarget;
   component: 'button' | GenericLinkType;
-  buttonOrLinkRef?: RefObject<HTMLButtonElement>;
+  buttonOrLinkRef?: RefObject<HTMLButtonElement | null>;
   onFocus?: FocusEventHandler<HTMLDivElement>;
   onBlur?: FocusEventHandler<HTMLDivElement>;
   onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
diff --git a/packages/components/src/components/slider/slider.tsx b/packages/components/src/components/slider/slider.tsx
@@ -12,9 +12,8 @@ import {
 
 import { useClassName } from '@/lib/hooks/useClassName/useClassName';
 
-import type { SliderOffsetBoundariesProps, SliderProps } from './types/slider';
-
 import { SliderStandAlone } from './sliderStandAlone';
+import type { SliderOffsetBoundariesProps, SliderProps } from './types/slider';
 import {
   calcNewValueAfterKeyPress,
   decrementValue,
@@ -121,7 +120,9 @@ export const Slider = forwardRef(
       });
 
     // Debounce callback to avoid calling onChange too many times
-    const timeoutOnChange = useRef<number | NodeJS.Timeout>();
+    const timeoutOnChange = useRef<number | NodeJS.Timeout | undefined>(
+      undefined,
+    );
 
     // Focus the thumb after handleChange to ensure the activePointer is set
     // Also active thumb could change during move in range mode
diff --git a/packages/components/src/components/slider/types/slider.ts b/packages/components/src/components/slider/types/slider.ts
@@ -69,7 +69,7 @@ export interface SliderStandAloneProps extends DataAttributes {
   hover: boolean;
   pressed: boolean;
   activePointer: React.MutableRefObject<string>;
-  containerRef: React.RefObject<HTMLDivElement>;
+  containerRef: React.RefObject<HTMLDivElement | null>;
   onMouseDown: React.MouseEventHandler<HTMLDivElement>;
   onChange: (event: MouseEvent | React.TouchEvent | React.MouseEvent) => void;
   onTouchStart: React.TouchEventHandler<HTMLDivElement>;
diff --git a/packages/components/src/components/table/hooks/useTableHasScroll.ts b/packages/components/src/components/table/hooks/useTableHasScroll.ts
@@ -3,7 +3,7 @@ import { type RefObject, useEffect, useState } from 'react';
 import { hasScroll as checkHasSroll } from '../../../lib/utils/scroll/hasScroll';
 
 interface UseTableHasScrollParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
   disabled?: boolean;
 }
 
diff --git a/packages/components/src/components/table/hooks/useTableShadow.ts b/packages/components/src/components/table/hooks/useTableShadow.ts
@@ -1,7 +1,7 @@
 import { type RefObject, useEffect } from 'react';
 
 interface UseTableShadowParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
   headBoxShadow?: string;
   leftBoxShadow?: string;
   rightBoxShadow?: string;
diff --git a/packages/components/src/components/table/hooks/useTableStickyLeftColumns.ts b/packages/components/src/components/table/hooks/useTableStickyLeftColumns.ts
@@ -3,7 +3,7 @@ import { type RefObject, useEffect } from 'react';
 import { hasHorizontalScroll } from '../../../lib/utils/scroll/hasScroll';
 
 interface UseTableStickyLeftColumnsParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
   disabled?: boolean;
 }
 
diff --git a/packages/components/src/components/table/hooks/useTableStickyRightColumns.ts b/packages/components/src/components/table/hooks/useTableStickyRightColumns.ts
@@ -6,7 +6,7 @@ import {
 } from '../../../lib/utils/scroll/hasScroll';
 
 interface UseTableStickyRightColumnsParamsType {
-  ref: RefObject<HTMLDivElement>;
+  ref: RefObject<HTMLDivElement | null>;
   disabled?: boolean;
 }
 
diff --git a/packages/components/src/components/tabs/__tests__/tabs.test.tsx b/packages/components/src/components/tabs/__tests__/tabs.test.tsx
@@ -8,11 +8,10 @@ import { render } from '@/lib/tests/render/render';
 import { windowMatchMedia } from '@/lib/tests/windowMatchMedia/windowMatchMedia';
 import { DEVICE_BREAKPOINTS } from '@/lib/types/breakpoints/breakpoints';
 
-import type { TabsUnControlledProps } from '../types/tabs';
-
 import * as UseTabsUtils from '../hooks/useTabs/useTabs';
 import { TabsControlled } from '../tabsControlled';
 import { TabsUnControlled } from '../tabsUnControlled';
+import type { TabsUnControlledProps } from '../types/tabs';
 
 const tabs = [
   { content: 'Tab 1' },
@@ -129,7 +128,7 @@ describe('Tabs component', () => {
         focus: 0,
         handleClickIcon: () => ({}),
         handleClickTab: () => ({}),
-        listEl: { current: null } as RefObject<HTMLLIElement>,
+        listEl: { current: null } as unknown as RefObject<HTMLLIElement>,
         position: 0,
       };
     });
diff --git a/packages/components/src/components/tabs/hooks/useTabs/useTabs.tsx b/packages/components/src/components/tabs/hooks/useTabs/useTabs.tsx
diff --git a/packages/components/src/components/toggle/utils/thumbTransformCalculations.ts b/packages/components/src/components/toggle/utils/thumbTransformCalculations.ts
diff --git a/packages/components/src/components/tooltip/hooks/useTooltip.ts b/packages/components/src/components/tooltip/hooks/useTooltip.ts
diff --git a/packages/components/src/components/tooltip/hooks/useTooltipAsModalAriaLabel.ts b/packages/components/src/components/tooltip/hooks/useTooltipAsModalAriaLabel.ts
diff --git a/packages/components/src/components/tooltip/hooks/useTooltipContentScroll.ts b/packages/components/src/components/tooltip/hooks/useTooltipContentScroll.ts
diff --git a/packages/components/src/lib/hooks/useContentVisibility/useContentVisibility.ts b/packages/components/src/lib/hooks/useContentVisibility/useContentVisibility.ts
diff --git a/packages/components/src/lib/hooks/useEscPressed/types/useEscPressed.ts b/packages/components/src/lib/hooks/useEscPressed/types/useEscPressed.ts
diff --git a/packages/components/src/lib/hooks/useRoveFocus/useRoveFocus.ts b/packages/components/src/lib/hooks/useRoveFocus/useRoveFocus.ts
diff --git a/packages/components/src/lib/hooks/useScrollDetection/useScrollDetection.ts b/packages/components/src/lib/hooks/useScrollDetection/useScrollDetection.ts
diff --git a/packages/components/src/lib/types/react.d.ts b/packages/components/src/lib/types/react.d.ts
diff --git a/packages/storybook/package.json b/packages/storybook/package.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`import { type RefObject, useEffect, useRef } from 'react';`
`2`	`2`
`3`	`3`	`interface UseAccordionContentOverflowParamsType {`
`4`		`- ref: RefObject<HTMLDivElement>;`
	`4`	`+ ref: RefObject<HTMLDivElement \| null>;`
`5`	`5`	`expanded: boolean;`
`6`	`6`	`}`
`7`	`7`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`import { type RefObject, useEffect } from 'react';`
`2`	`2`
`3`	`3`	`interface UseAccordionInertContentParamsType {`
`4`		`- ref: RefObject<HTMLDivElement>;`
	`4`	`+ ref: RefObject<HTMLDivElement \| null>;`
`5`	`5`	`expanded: boolean;`
`6`	`6`	`}`
`7`	`7`