[useRenderer] Add public hook

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/data-attributes/css-modules/index.module.css

@@ -0,0 +1,16 @@
+.Text {
+  cursor: pointer;
+  font-size: 0.875rem;
+  line-height: 1rem;
+  font-weight: 400;
+  color: var(--color-gray-900);
+  &[data-size='small'] {
+    font-size: 0.75rem;
+  }
+  &[data-size='large'] {
+    font-size: 1.25rem;
+  }
+  &[data-color='active'] {
+    color: var(--color-blue);
+  }
+}

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/data-attributes/css-modules/index.tsx

@@ -0,0 +1,58 @@
+'use client';
+import * as React from 'react';
+import { useRenderer, RenderProp } from '@base-ui-components/react/use-renderer';
+import styles from './index.module.css';
+
+type Size = 'small' | 'medium' | 'large';
+type Color = 'default' | 'active';
+
+type TextState = {
+  size: Size;
+  color: Color;
+};
+
+type TextProps = {
+  className: string | ((state: TextState) => string);
+  render?: RenderProp<TextState>;
+  onClick?: (event: React.MouseEvent<Element>) => void;
+  children: React.ReactNode;
+  size?: Size;
+};
+
+function Text(props: TextProps) {
+  const { className, render, size = 'medium', onClick, ...otherProps } = props;
+  const [color, setColor] = React.useState<Color>('default');
+
+  const onClickHandler = (event: React.MouseEvent<Element>) => {
+    setColor(color === 'default' ? 'active' : 'default');
+    onClick?.(event);
+  };
+
+  const state = React.useMemo(() => ({ size, color }), [size, color]);
+
+  const { renderElement } = useRenderer({
+    render: render ?? <p />,
+    state,
+    className,
+    props: {
+      ...otherProps,
+      onClick: onClickHandler,
+    },
+  });
+
+  return renderElement();
+}
+
+export default function ExampleText() {
+  return (
+    <div>
+      <Text className={styles.Text} size="small">
+        Small size
+      </Text>
+      <Text className={styles.Text}>Medium size</Text>
+      <Text className={styles.Text} size="large">
+        Large size
+      </Text>
+    </div>
+  );
+}

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/data-attributes/index.ts

@@ -0,0 +1,2 @@
+'use client';
+export { default as CssModules } from './css-modules';

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/render/css-modules/index.module.css

@@ -0,0 +1,5 @@
+.Text {
+  font-size: 0.875rem;
+  line-height: 1rem;
+  color: var(--color-gray-900);
+}

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/render/css-modules/index.tsx

@@ -0,0 +1,32 @@
+'use client';
+import * as React from 'react';
+import { useRenderer, RenderProp } from '@base-ui-components/react/use-renderer';
+import styles from './index.module.css';
+
+type TextProps = {
+  className?: string;
+  render?: RenderProp<Record<string, any>>;
+  children: React.ReactNode;
+};
+
+function Text(props: TextProps) {
+  const { render, ...otherProps } = props;
+
+  const { renderElement } = useRenderer({
+    render: render ?? <p />,
+    props: otherProps,
+  });
+
+  return renderElement();
+}
+
+export default function ExampleText() {
+  return (
+    <div>
+      <Text className={styles.Text}>Text component rendered as a paragraph tag</Text>
+      <Text className={styles.Text} render={<strong />}>
+        Text component rendered as a strong tag
+      </Text>
+    </div>
+  );
+}

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/render/index.ts

@@ -0,0 +1,2 @@
+'use client';
+export { default as CssModules } from './css-modules';

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/state-attributes-map/css-modules/index.module.css

@@ -0,0 +1,16 @@
+.Text {
+  cursor: pointer;
+  font-size: 0.875rem;
+  line-height: 1rem;
+  font-weight: 400;
+  color: var(--color-gray-900);
+  &[data-size-small] {
+    font-size: 0.75rem;
+  }
+  &[data-size-large] {
+    font-size: 1.25rem;
+  }
+  &[data-color-active] {
+    color: var(--color-blue);
+  }
+}

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/state-attributes-map/css-modules/index.tsx

@@ -0,0 +1,62 @@
+'use client';
+import * as React from 'react';
+import { useRenderer, RenderProp } from '@base-ui-components/react/use-renderer';
+import styles from './index.module.css';
+
+type Size = 'small' | 'medium' | 'large';
+type Color = 'default' | 'active';
+
+type TextState = {
+  size: Size;
+  color: Color;
+};
+
+type TextProps = {
+  className: string | ((state: TextState) => string);
+  render?: RenderProp<TextState>;
+  onClick?: (event: React.MouseEvent<Element>) => void;
+  children: React.ReactNode;
+  size?: Size;
+};
+
+function Text(props: TextProps) {
+  const { className, render, size = 'medium', onClick, ...otherProps } = props;
+  const [color, setColor] = React.useState<Color>('default');
+
+  const onClickHandler = (event: React.MouseEvent<Element>) => {
+    setColor(color === 'default' ? 'active' : 'default');
+    onClick?.(event);
+  };
+
+  const state = React.useMemo(() => ({ size, color }), [size, color]);
+
+  const { renderElement } = useRenderer({
+    render: render ?? <p />,
+    state,
+    className,
+    stateAttributesMap: {
+      size: (value) => ({ [`data-size-${value}`]: '' }),
+      color: (value) => ({ [`data-color-${value}`]: '' }),
+    },
+    props: {
+      ...otherProps,
+      onClick: onClickHandler,
+    },
+  });
+
+  return renderElement();
+}
+
+export default function ExampleText() {
+  return (
+    <div>
+      <Text className={styles.Text} size="small">
+        Small text
+      </Text>
+      <Text className={styles.Text}>Default text</Text>
+      <Text className={styles.Text} size="large">
+        Large text
+      </Text>
+    </div>
+  );
+}

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/state-attributes-map/index.ts

@@ -0,0 +1,2 @@
+'use client';
+export { default as CssModules } from './css-modules';

docs/src/app/(public)/(content)/react/utils/use-renderer/page.mdx

@@ -0,0 +1,60 @@
+# useRenderer
+
+<Subtitle>Utility for adding Base UI-like features to custom components.</Subtitle>
+<Meta name="description" content="Utility for adding Base UI-like features to custom components." />
+
+The `useRenderer` hook allows you to support the same features Base UI provides across all components so that you can also have a consistent experience in your custom components:
+
+- A [render](/react/handbook/composition) prop to override the default rendered element.
+- A [callback](/react/handbook/styling#css-classes) on the `className` prop that enables passing dynamically generated CSS classes based on the component's state.
+- Adds [data-attributes](https://base-ui.com/react/handbook/styling#data-attributes) that map to the component's state that can be used as style hooks.
+
+## API reference
+
+### Input parameters
+
+<PropsReferenceTable
+  data={{
+    className: {
+      type: 'string | ((state: State) => string)',
+      description:
+        "CSS class applied to the element, or a function that returns a class based on the component's state.",
+    },
+    render: {
+      type: 'RenderProp<State>',
+      description:
+        "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a \`ReactElement\` or a function that returns the element to render.",
+    },
+    state: {
+      type: 'State',
+      description:
+        'The state of the component. It will be used as a parameter for the render and className callbacks.',
+    },
+    props: {
+      type: 'Record<string, unknown>',
+      description: 'Props to be spread on the rendered element.',
+    },
+    stateAttributesMap: {
+      type: 'StateDataAttributes<State>',
+      description: 'A mapping of state to style hooks.',
+    },
+  }}
+/>
+
+### Return value
+
+The hook returns a function that when called returns the element that should be rendered.
+
+## Usage
+
+This is an example of a Text component that provides the support for the render prop.
+
+<Demo path="./demos/render" />
+
+In the following demo, the Text component provides more Base UI features, like adding data attributes and `className` callback where developers can have access to the internal state of the component.
+
+<Demo path="./demos/data-attributes" />
+
+Additionally, you can also customize how the data-attributes are generated, by providing the `stateAttributesMap` option.
+
+<Demo path="./demos/state-attributes-map" />

docs/src/nav.ts

@@ -149,6 +149,10 @@ export const nav = [
         label: 'Direction Provider',
         href: '/react/utils/direction-provider',
       },
+      {
+        label: 'useRenderer',
+        href: '/react/utils/use-renderer',
+      },
     ],
   },
 ];

packages/react/package.json

@@ -56,6 +56,7 @@
     "./tooltip": "./src/tooltip/index.ts",
     "./unstable-no-ssr": "./src/unstable-no-ssr/index.ts",
     "./unstable-use-media-query": "./src/unstable-use-media-query/index.ts",
+    "./use-renderer": "./src/use-renderer/index.ts",
     "./utils": "./src/utils/index.ts"
   },
   "imports": {

packages/react/src/index.ts

@@ -25,3 +25,4 @@ export * from './tabs';
 export * from './toggle';
 export * from './toggle-group';
 export * from './tooltip';
+export * from './use-renderer';

packages/react/src/use-renderer/index.ts

@@ -0,0 +1 @@
+export * from './useRenderer';

packages/react/src/use-renderer/useRenderer.test.tsx

@@ -0,0 +1,93 @@
+import * as React from 'react';
+import { expect } from 'chai';
+import { createRenderer } from '@mui/internal-test-utils';
+import { useRenderer } from '@base-ui-components/react/use-renderer';
+
+describe('useRenderer', () => {
+  const { render } = createRenderer();
+
+  it('render props does not overwrite className in a render function when unspecified', async () => {
+    function TestComponent(props: {
+      render: useRenderer.Settings<any, Element>['render'];
+      className?: useRenderer.Settings<any, Element>['className'];
+    }) {
+      const { render: renderProp, className } = props;
+      const { renderElement } = useRenderer({
+        render: renderProp,
+        state: {},
+        className,
+      });
+      return renderElement();
+    }
+
+    const { container } = await render(
+      <TestComponent
+        render={(props: any, state: any) => <span className="my-span" {...props} {...state} />}
+      />,
+    );
+
+    const element = container.firstElementChild;
+
+    expect(element).to.have.attribute('class', 'my-span');
+  });
+
+  it('includes data-attributes for all state members', async () => {
+    function TestComponent(props: {
+      render?: useRenderer.Settings<any, Element>['render'];
+      className?: useRenderer.Settings<any, Element>['className'];
+      size: 'small' | 'medium' | 'large';
+      weight: 'light' | 'regular' | 'bold';
+    }) {
+      const { render: renderProp, size, weight } = props;
+      const { renderElement } = useRenderer({
+        render: renderProp ?? 'span',
+        state: {
+          size,
+          weight,
+        },
+      });
+      return renderElement();
+    }
+
+    const { container } = await render(<TestComponent size="large" weight="bold" />);
+
+    const element = container.firstElementChild;
+
+    expect(element).to.have.attribute('data-size', 'large');
+    expect(element).to.have.attribute('data-weight', 'bold');
+  });
+
+  it('respects the customStyleHookMapping config if provided', async () => {
+    function TestComponent(props: {
+      render?: useRenderer.Settings<any, Element>['render'];
+      className?: useRenderer.Settings<any, Element>['className'];
+      size: 'small' | 'medium' | 'large';
+      weight: 'light' | 'regular' | 'bold';
+    }) {
+      const { render: renderProp, size, weight } = props;
+      const { renderElement } = useRenderer({
+        render: renderProp ?? 'span',
+        state: {
+          size,
+          weight,
+        },
+        stateAttributesMap: {
+          size(value) {
+            return { [`data-size${value}`]: '' };
+          },
+          weight() {
+            return null;
+          },
+        },
+      });
+      return renderElement();
+    }
+
+    const { container } = await render(<TestComponent size="large" weight="bold" />);
+
+    const element = container.firstElementChild;
+
+    expect(element).to.have.attribute('data-sizelarge', '');
+    expect(element).not.to.have.attribute('data-weight');
+  });
+});