refactor(ui): type Mosaic render callbacks from MosaicComponentProps

.changeset/mosaic-render-props.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/utils/index.ts

@@ -6,5 +6,6 @@ export {
   mergeProps,
   type RenderProp,
   type RenderPropOrElement,
+  type RenderProps,
   useRender,
 } from './use-render';

packages/headless/src/utils/use-render.test-d.ts

@@ -1,14 +1,36 @@
 import type React from 'react';
 import { describe, expectTypeOf, test } from 'vitest';
 
-import type { ComponentProps } from './use-render';
+import type { ComponentProps, RenderProps } from './use-render';
+
+type RenderFn<Tag extends keyof React.JSX.IntrinsicElements> = Extract<
+  NonNullable<ComponentProps<Tag>['render']>,
+  (...args: never[]) => unknown
+>;
+type RenderArg<Tag extends keyof React.JSX.IntrinsicElements> =
+  RenderFn<Tag> extends (props: infer P) => React.ReactElement ? P : never;
+type HasColor<P> = 'color' extends keyof P ? true : false;
 
 describe('use-render', () => {
-  test('render prop arg is narrowed to the element tag props, not the generic HTMLAttributes<HTMLElement>', () => {
-    type Props = ComponentProps<'button'>;
-    type RenderFn = Extract<NonNullable<Props['render']>, (...args: never[]) => unknown>;
-    type RenderArg = RenderFn extends (props: infer P) => React.ReactElement ? P : never;
-    expectTypeOf<RenderArg>().toEqualTypeOf<React.ComponentPropsWithRef<'button'>>();
+  test('a part keeps its own tag props', () => {
+    expectTypeOf<ComponentProps<'button'>>().toExtend<{ type?: 'button' | 'submit' | 'reset' }>();
+  });
+
+  test('the legacy `color` attribute is dropped, so it cannot widen a `color` variant', () => {
+    expectTypeOf<HasColor<ComponentProps<'button'>>>().toEqualTypeOf<false>();
+    expectTypeOf<HasColor<RenderArg<'button'>>>().toEqualTypeOf<false>();
+  });
+
+  test('the render arg is the tag-agnostic RenderProps, not the default tag props', () => {
+    expectTypeOf<RenderArg<'button'>>().toEqualTypeOf<RenderProps>();
+    expectTypeOf<RenderArg<'div'>>().toEqualTypeOf<RenderProps>();
+  });
+
+  test('render props spread onto an element other than the default tag', () => {
+    // The point of `render`: a `div` part rendering an `<a>`. A tag-pinned `ref`
+    // would make this fail, which is what every call site used to work around.
+    expectTypeOf<RenderProps>().toExtend<React.ComponentPropsWithRef<'a'>>();
+    expectTypeOf<RenderProps>().toExtend<React.ComponentPropsWithRef<'button'>>();
   });
 
   test('render also accepts an element to clone', () => {

packages/headless/src/utils/use-render.tsx

@@ -5,27 +5,48 @@ import * as React from 'react';
 // Types
 // ---------------------------------------------------------------------------
 
+/**
+ * The props a `render` callback receives, deliberately *not* the default tag's props.
+ *
+ * `render` exists to swap the rendered element, so the element's type is unknown at
+ * the point this is declared. Two things follow, and both were previously worked
+ * around at each call site instead of here:
+ *
+ * - `ref` is not pinned to the default tag. A `div` part rendering an `<a>` could
+ *   not spread its props, because `Ref<HTMLDivElement>` is not a `Ref<HTMLAnchorElement>`.
+ * - `color` is dropped. It is a non-standard HTML attribute typed `string`, so it
+ *   collides with the `color` variant a styled component spreads these props into.
+ */
+export type RenderProps = Omit<React.HTMLAttributes<HTMLElement>, 'color'> & {
+  // SAFETY: the rendered element is chosen by the callback, after this type is fixed, so
+  // no concrete element type is correct here. `Ref<Element>` does not work: `RefObject<Element>`
+  // is not a `RefObject<HTMLAnchorElement>`. `any` is what makes the ref spreadable onto
+  // whatever the callback returns, which is the whole point of `render`. Base UI's
+  // `HTMLProps` resolves this the same way.
+  ref?: React.Ref<any>;
+};
+
 /**
  * A render prop: a function that receives computed HTML props and returns a JSX element.
  */
-export type RenderProp<Props = React.HTMLAttributes<HTMLElement>> = (props: Props) => React.ReactElement;
+export type RenderProp<Props = RenderProps> = (props: Props) => React.ReactElement;
 
 /**
  * A `render` prop: a render function receiving the part's computed props, or a
- * React element to clone with them (`render={<Link/>}`). The element form lets a
- * part render a component whose own props diverge from the tag's, which a render
- * function cannot express — it is typed to receive the tag's props verbatim.
+ * React element to clone with them (`render={<Link/>}`).
  */
-export type RenderPropOrElement<Tag extends keyof React.JSX.IntrinsicElements> =
-  | RenderProp<React.ComponentPropsWithRef<Tag>>
-  | React.ReactElement;
+export type RenderPropOrElement = RenderProp | React.ReactElement;
 
 /**
- * Props accepted by any primitive part. Extends the native props for `Tag`
- * and adds the optional `render` escape hatch, narrowed to that tag's props.
+ * Props accepted by any primitive part: the native props for `Tag` plus the
+ * optional `render` escape hatch. `color` is dropped for the reason given on
+ * `RenderProps` — a part and its render callback expose the same contract.
  */
-export type ComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = React.ComponentPropsWithRef<Tag> & {
-  render?: RenderPropOrElement<Tag>;
+export type ComponentProps<Tag extends keyof React.JSX.IntrinsicElements> = Omit<
+  React.ComponentPropsWithRef<Tag>,
+  'color'
+> & {
+  render?: RenderPropOrElement;
 };
 
 /**
@@ -125,7 +146,7 @@ interface UseRenderParamsBase<
   /** Fallback HTML tag when `render` is not provided. */
   defaultTagName: Tag;
   /** Render prop or element from the consumer. */
-  render?: RenderPropOrElement<Tag>;
+  render?: RenderPropOrElement;
   /** Ref(s) to merge onto the rendered element. Merged with the element's own ref. */
   ref?: React.Ref<unknown> | Array<React.Ref<unknown> | undefined>;
   /** State object. Keys are mapped to data attributes via `stateAttributesMapping`. */
@@ -197,9 +218,7 @@ export function useRender<
   const computedProps = { ...props, ...dataAttrs };
 
   if (typeof render === 'function') {
-    // SAFETY: computedProps is the tag's props widened with data-* attrs; the render
-    // function is declared to receive this tag's props.
-    return render({ ...computedProps, ref: mergedRef } as React.ComponentPropsWithRef<Tag>);
+    return render({ ...computedProps, ref: mergedRef });
   }
 
   if (React.isValidElement(render)) {

packages/swingset/src/stories/dialog.component.stories.tsx

@@ -1,4 +1,5 @@
 /** @jsxImportSource @emotion/react */
+import type { RenderProps } from '@clerk/headless/utils';
 import { Button } from '@clerk/ui/mosaic/components/button';
 import { Dialog, dialogRecipe } from '@clerk/ui/mosaic/components/dialog';
 
@@ -15,9 +16,7 @@ export const meta: StoryMeta = {
   styles: dialogRecipe,
 };
 
-const dialogTrigger = ({ color: _nativeColor, ...props }: React.HTMLAttributes<HTMLElement>) => (
-  <Button {...props}>Open dialog</Button>
-);
+const dialogTrigger = (props: RenderProps) => <Button {...props}>Open dialog</Button>;
 
 export function Default(args: Record<string, unknown>) {
   const { size } = args as { size?: 'md' | 'lg' };

packages/ui/src/mosaic/components/button/button.tsx

@@ -1,12 +1,12 @@
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
-import type { MosaicComponentProps } from '../../props';
+import type { MosaicElementProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { truncationStyles } from '../typography.styles';
 import { iconSizes, sizes, styles, variants } from './button.styles';
 
-export interface ButtonProps extends Omit<MosaicComponentProps<'button'>, 'render'> {
+export interface ButtonProps extends MosaicElementProps<'button'> {
   color?: 'primary' | 'neutral' | 'negative';
   variant?: 'filled' | 'outline' | 'ghost' | 'link';
   size?: 'sm' | 'md' | 'lg';

packages/ui/src/mosaic/components/dialog.tsx

@@ -4,6 +4,7 @@ import type { ReactNode } from 'react';
 import React from 'react';
 
 import { Dialog as Primitive } from '../primitives/dialog';
+import type { MosaicComponentProps } from '../props';
 import type { RecipeVariantProps } from '../slot-recipe';
 import { defineSlotRecipe, useRecipe } from '../slot-recipe';
 
@@ -81,48 +82,46 @@ declare module '../registry' {
   }
 }
 
-const Backdrop = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.Backdrop>>(
-  function DialogBackdrop(props, ref) {
-    const { backdrop } = useRecipe(dialogRecipe);
-    return (
-      <Primitive.Backdrop
-        ref={ref}
-        {...props}
-        {...backdrop}
-      />
-    );
-  },
-);
+export type DialogBackdropProps = React.ComponentPropsWithoutRef<typeof Primitive.Backdrop>;
+export type DialogViewportProps = React.ComponentPropsWithoutRef<typeof Primitive.Viewport>;
+export type DialogPopupProps = React.ComponentPropsWithoutRef<typeof Primitive.Popup>;
 
-const Viewport = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.Viewport>>(
-  function DialogViewport(props, ref) {
-    const { viewport } = useRecipe(dialogRecipe);
-    return (
-      <Primitive.Viewport
-        ref={ref}
-        {...props}
-        {...viewport}
-      />
-    );
-  },
-);
+const Backdrop = React.forwardRef<HTMLDivElement, DialogBackdropProps>(function DialogBackdrop(props, ref) {
+  const { backdrop } = useRecipe(dialogRecipe);
+  return (
+    <Primitive.Backdrop
+      ref={ref}
+      {...props}
+      {...backdrop}
+    />
+  );
+});
 
-const Popup = React.forwardRef<HTMLDivElement, React.ComponentPropsWithoutRef<typeof Primitive.Popup>>(
-  function DialogPopup(props, ref) {
-    const variantProps = React.useContext(DialogVariantContext);
-    const { popup } = useRecipe(dialogRecipe, { variants: variantProps });
-    return (
-      <Primitive.Popup
-        ref={ref}
-        {...props}
-        {...popup}
-      />
-    );
-  },
-);
+const Viewport = React.forwardRef<HTMLDivElement, DialogViewportProps>(function DialogViewport(props, ref) {
+  const { viewport } = useRecipe(dialogRecipe);
+  return (
+    <Primitive.Viewport
+      ref={ref}
+      {...props}
+      {...viewport}
+    />
+  );
+});
+
+const Popup = React.forwardRef<HTMLDivElement, DialogPopupProps>(function DialogPopup(props, ref) {
+  const variantProps = React.useContext(DialogVariantContext);
+  const { popup } = useRecipe(dialogRecipe, { variants: variantProps });
+  return (
+    <Primitive.Popup
+      ref={ref}
+      {...props}
+      {...popup}
+    />
+  );
+});
 
 interface DialogProps extends Pick<HeadlessDialogProps, 'open' | 'defaultOpen' | 'onOpenChange' | 'modal'> {
-  trigger: React.ComponentProps<typeof Primitive.Trigger>['render'];
+  trigger: MosaicComponentProps<'button'>['render'];
   children: ReactNode | ((ctx: { close: () => void }) => ReactNode);
   size?: DialogVariantProps['size'];
 }

packages/ui/src/mosaic/components/item/item.tsx

@@ -1,4 +1,4 @@
-import { type RenderProp, useRender } from '@clerk/headless/utils';
+import { useRender } from '@clerk/headless/utils';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
@@ -16,16 +16,14 @@ const DEFAULT_SIZE: Size = 'md';
 /** Carries `Item.Root`'s size down to the parts it scales (`Item.Media`). */
 const ItemContext = React.createContext<Size>(DEFAULT_SIZE);
 
-export type ItemProps = Omit<MosaicComponentProps<'div'>, 'render'> & {
+export type ItemProps = MosaicComponentProps<'div'> & {
   /**
    * Row height and gap. Also sizes a nested `Item.Media`, which reads this from
    * context rather than taking its own prop, so a row scales as one unit.
    *
    * @default 'md'
    */
   size?: Size;
-  /** Render a custom element (e.g. a link or button) in place of the default `div`. */
-  render?: RenderProp<React.HTMLAttributes<HTMLElement>>;
 };
 
 /**

packages/ui/src/mosaic/components/menu/menu.tsx

@@ -4,18 +4,20 @@ import type {
   MenuPortalProps,
   MenuProps,
   MenuSeparatorProps,
-  MenuTriggerProps,
 } from '@clerk/headless/menu';
 import { Menu as Primitive } from '@clerk/headless/menu';
 import * as stylex from '@stylexjs/stylex';
 import React from 'react';
 
+import type { MosaicComponentProps } from '../../props';
 import { mergeStyleProps, themeProps } from '../../props';
 import { Button } from '../button';
 import { Icon } from '../icon';
 import { styles } from './menu.styles';
 
-export type { MenuProps, MenuSeparatorProps, MenuTriggerProps };
+export type { MenuProps, MenuSeparatorProps };
+
+export type MenuTriggerProps = MosaicComponentProps<'button'>;
 
 /**
  * Opens the menu. Renders a ghost `Button` holding an ellipsis glyph by default;
@@ -25,20 +27,21 @@ export const MenuTrigger = React.forwardRef<HTMLButtonElement, MenuTriggerProps>
   { render, className, style, children, ...rest },
   ref,
 ) {
+  const trigger: MenuTriggerProps['render'] =
+    render ??
+    (props => (
+      <Button
+        variant='ghost'
+        size='sm'
+        shape={children ? 'default' : 'square'}
+        {...props}
+      />
+    ));
+
   return (
     <Primitive.Trigger
       ref={ref}
-      render={
-        render ??
-        (({ color: _nativeColor, ...props }) => (
-          <Button
-            variant='ghost'
-            size='sm'
-            shape={children ? 'default' : 'square'}
-            {...props}
-          />
-        ))
-      }
+      render={trigger}
       {...mergeStyleProps(themeProps('menu-trigger'), className, style)}
       {...rest}
     >