fix(react): restore intrinsic HTML props under React 19 types (#121)

* fix(react): restore intrinsic HTML props under React 19 types

`React.PropsWithRef<JSX.IntrinsicElements['x']>` relied on the global
`JSX` namespace, which @types/react@19 no longer augments. Under React
19 the type collapsed to `any`, silently dropping `onClick`, `type`,
`disabled`, `aria-*`, `children`, etc. from every affected component.

Replaced with `React.ComponentProps<'x'>` /
`React.ComponentPropsWithoutRef<'x'>` across ~60 type files. Works on
React 18 and 19.

Fixes #120.

* refactor(react): normalize forwardRef props to ComponentPropsWithoutRef

The codebase mixed `ComponentProps` (with ref) and `ComponentPropsWithoutRef`
across prop interfaces, all consumed by `React.forwardRef`. Normalize to
`ComponentPropsWithoutRef` throughout — the idiomatic pattern React docs
recommend for forwardRef, since forwardRef re-adds ref via `RefAttributes<T>`
to the external component type.

Side benefit: for the handful of non-forwardRef components (Link, Form,
FormItem, Descriptions), this removes `ref` from the prop type so consumers
can no longer pass a non-functional `ref` prop.

Zero external API change for forwardRef components — `<Button ref={...}/>`
still type-checks via `RefAttributes<HTMLButtonElement>`.

* fix(react): normalize ref exposure policy

Author: wangdicoder

.changeset/react-19-types-compat.md

@@ -0,0 +1,5 @@
+---
+'@tiny-design/react': patch
+---
+
+Fix TypeScript compatibility with React 19. Component prop interfaces used the pattern `React.PropsWithRef<JSX.IntrinsicElements['x']>`, which relied on a globally-augmented `JSX` namespace that `@types/react@19` no longer provides. The resolved prop types collapsed to `any`, silently dropping every intrinsic HTML attribute (`onClick`, `type`, `disabled`, `aria-*`, `children`, etc.) for consumers on React 19. Replaced the pattern with `React.ComponentProps<'x'>` / `React.ComponentPropsWithoutRef<'x'>` across ~60 component type files. Works on React 18 and 19.

packages/react/REFS.md

@@ -0,0 +1,25 @@
+# Ref Conventions
+
+This package treats `ref` as an explicit component capability, not an accidental side effect of inheriting DOM props.
+
+## Rules
+
+- Use `React.ComponentPropsWithoutRef<'tag'>` for DOM-derived prop interfaces by default.
+- Only expose `ref` when the component intentionally supports DOM access through `React.forwardRef`.
+- Do not rely on `React.ComponentProps<'tag'>` to leak `ref` into props interfaces.
+- If a component is primarily compositional or layout-only, do not expose `ref` unless there is a concrete DOM integration need.
+
+## Components That Should Expose `ref`
+
+- Interactive controls and focus targets such as `Button`, `Input`, `NativeSelect`, `Link`, `Switch`, `Checkbox`, `Radio`.
+- Components frequently used for measurement, scrolling, positioning, or animation integration such as `Tree`, `Slider`, `Grid`, `Space`, `Flex`, `Layout`, `Anchor`, `Waterfall`, `Transfer`, `Steps`, and typography primitives.
+
+## Components That Usually Should Not Expose `ref`
+
+- Grouping or compositional wrappers such as `Button.Group`, `Checkbox.Group`, `Radio.Group`, `Input.Group`, `Input.Addon`, `Form.Item`, `Descriptions`, `Descriptions.Item`.
+
+## Practical Guidance
+
+- If consumers need the outer wrapper and an inner native control, expose both intentionally, for example `Checkbox` plus `checkboxRef`, or `Radio` plus `radioRef`.
+- If a component renders different DOM elements by state, make the forwarded ref type reflect that reality instead of pretending it always points to one tag.
+- When adding a new forwarded ref, add a focused test that proves the ref resolves to the expected DOM node.

packages/react/src/alert/types.ts

@@ -5,7 +5,7 @@ export type AlertType = 'success' | 'info' | 'warning' | 'error';
 
 export interface AlertProps
   extends BaseProps,
-    Omit<React.PropsWithoutRef<JSX.IntrinsicElements['div']>, 'title'> {
+    Omit<React.ComponentPropsWithoutRef<'div'>, 'title'> {
   /** alert title */
   title?: string | ReactNode;
 

packages/react/src/anchor/__tests__/anchor.test.tsx

@@ -32,4 +32,16 @@ describe('<Anchor />', () => {
     expect(getByText('Link 1')).toBeInTheDocument();
     expect(getByText('Link 2')).toBeInTheDocument();
   });
+
+  it('should forward ref to root list element', () => {
+    const ref = React.createRef<HTMLUListElement>();
+
+    render(
+      <Anchor ref={ref}>
+        <Anchor.Link href="#section1" title="Section 1" />
+      </Anchor>
+    );
+
+    expect(ref.current).toBeInstanceOf(HTMLUListElement);
+  });
 });

packages/react/src/anchor/anchor.tsx

@@ -7,7 +7,20 @@ import { AnchorLinkProps, AnchorProps } from './types';
 import { AnchorContext } from './anchor-context';
 import Sticky from '../sticky';
 
-const Anchor = (props: AnchorProps): JSX.Element => {
+function assignRef<T>(ref: React.Ref<T> | undefined, value: T | null): void {
+  if (!ref) {
+    return;
+  }
+
+  if (typeof ref === 'function') {
+    ref(value);
+    return;
+  }
+
+  (ref as React.MutableRefObject<T | null>).current = value;
+}
+
+const Anchor = React.forwardRef<HTMLUListElement, AnchorProps>((props, ref): JSX.Element => {
   const {
     affix = false,
     offsetTop = 0,
@@ -20,6 +33,7 @@ const Anchor = (props: AnchorProps): JSX.Element => {
     style,
     children,
     prefixCls: customisedCls,
+    ...otherProps
   } = props;
   const configContext = useContext(ConfigContext);
   const prefixCls = getPrefixCls('anchor', configContext.prefixCls, customisedCls);
@@ -37,6 +51,14 @@ const Anchor = (props: AnchorProps): JSX.Element => {
     linksRef.current.delete(href);
   }, []);
 
+  const setAnchorNode = useCallback(
+    (node: HTMLUListElement | null) => {
+      anchorRef.current = node;
+      assignRef(ref, node);
+    },
+    [ref]
+  );
+
   const updateInk = useCallback(() => {
     const anchorEl = anchorRef.current;
     if (!anchorEl) return;
@@ -200,7 +222,7 @@ const Anchor = (props: AnchorProps): JSX.Element => {
   );
 
   const anchorContent = (
-    <ul className={cls} style={style} ref={anchorRef}>
+    <ul {...otherProps} className={cls} style={style} ref={setAnchorNode}>
       <div className={`${prefixCls}__ink`}>
         <div className={`${prefixCls}__ink-ball`} ref={inkBallRef} />
       </div>
@@ -228,7 +250,7 @@ const Anchor = (props: AnchorProps): JSX.Element => {
       )}
     </AnchorContext.Provider>
   );
-};
+});
 
 Anchor.displayName = 'Anchor';
 

packages/react/src/anchor/types.ts

@@ -1,7 +1,9 @@
 import React from 'react';
 import { BaseProps } from '../_utils/props';
 
-export interface AnchorProps extends BaseProps {
+export interface AnchorProps
+  extends BaseProps,
+    Omit<React.ComponentPropsWithoutRef<'ul'>, 'children' | 'onChange' | 'onClick'> {
   affix?: boolean;
   type?: 'dot' | 'line';
   offsetBottom?: number;
@@ -12,7 +14,7 @@ export interface AnchorProps extends BaseProps {
   children?: React.ReactNode;
 }
 
-export interface AnchorLinkProps extends BaseProps, React.PropsWithRef<JSX.IntrinsicElements['a']> {
+export interface AnchorLinkProps extends BaseProps, React.ComponentPropsWithoutRef<'a'> {
   href: string;
   title: string;
   children?: React.ReactElement<AnchorLinkProps>[];

packages/react/src/aspect-ratio/types.ts

@@ -3,7 +3,7 @@ import { BaseProps } from '../_utils/props';
 
 export interface AspectRatioProps
   extends BaseProps,
-    React.PropsWithoutRef<JSX.IntrinsicElements['div']> {
+    React.ComponentPropsWithoutRef<'div'> {
   /** the width of the content */
   width?: number | string;
 

packages/react/src/avatar/types.ts

@@ -6,7 +6,7 @@ export type AvatarPresence = 'online' | 'busy' | 'away' | 'offline';
 
 export interface AvatarProps
   extends BaseProps,
-    React.PropsWithoutRef<JSX.IntrinsicElements['span']> {
+    React.ComponentPropsWithoutRef<'span'> {
   /** use an icon */
   icon?: React.ReactNode;
 
@@ -28,7 +28,7 @@ export interface AvatarProps
 
 export interface AvatarGroupProps
   extends BaseProps,
-    React.PropsWithoutRef<JSX.IntrinsicElements['span']> {
+    React.ComponentPropsWithoutRef<'span'> {
   /** the distance between two avatars */
   gap: number | string;
 }

packages/react/src/badge/types.ts

@@ -3,7 +3,7 @@ import { BaseProps } from '../_utils/props';
 
 export interface BadgeProps
   extends BaseProps,
-    React.PropsWithoutRef<JSX.IntrinsicElements['span']> {
+    React.ComponentPropsWithoutRef<'span'> {
   /** the number to show in badge */
   count?: React.ReactNode;
 

packages/react/src/breadcrumb/types.ts

@@ -3,14 +3,14 @@ import { BaseProps } from '../_utils/props';
 
 export interface BreadcrumbProps
   extends BaseProps,
-    React.PropsWithoutRef<JSX.IntrinsicElements['nav']> {
+    React.ComponentPropsWithoutRef<'nav'> {
   separator?: React.ReactNode;
   children: ReactElement<BreadcrumbItemProps> | ReactElement<BreadcrumbItemProps>[];
 }
 
 export interface BreadcrumbItemProps
   extends BaseProps,
-    React.PropsWithoutRef<JSX.IntrinsicElements['li']> {
+    React.ComponentPropsWithoutRef<'li'> {
   separator?: React.ReactNode;
   children?: React.ReactNode;
 }