add docs page

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

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

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

@@ -0,0 +1,76 @@
+'use client';
+import * as React from 'react';
+import { useRenderer, RenderProp } from '@base-ui-components/react/use-renderer';
+import styles from './index.module.css';
+
+type Weight = 'light' | 'regular' | 'bold';
+type Size = 'small' | 'medium' | 'large';
+
+type TextState = {
+  weight: Weight;
+  size: Size;
+};
+
+type TextProps = {
+  className: string | ((state: TextState) => string);
+  weight?: Weight;
+  render?: RenderProp<TextState>;
+  children: React.ReactNode;
+  style?: React.CSSProperties;
+  size?: Size;
+  excludedProp?: boolean;
+};
+
+const Text = React.forwardRef(
+  (props: TextProps, forwardedRef: React.ForwardedRef<HTMLElement>) => {
+    const {
+      className,
+      render,
+      style = {},
+      weight = 'regular',
+      size = 'medium',
+      ...otherProps
+    } = props;
+
+    const fontWeight = {
+      light: 300,
+      regular: 400,
+      bold: 700,
+    }[weight];
+
+    const state = React.useMemo(() => ({ weight, size }), [weight, size]);
+
+    const { renderElement } = useRenderer({
+      render: render ?? 'p',
+      state,
+      className,
+      ref: forwardedRef,
+      props: {
+        ...otherProps,
+        style: {
+          ...style,
+          fontWeight,
+        },
+      },
+    });
+
+    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>
+      <Text className={styles.Text} weight="bold" render={<strong />}>
+        Bold text rendered in a strong tag
+      </Text>
+    </div>
+  );
+}

docs/src/app/(public)/(content)/react/utils/use-renderer/demos/usage/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 in a custom build components.</Subtitle>
+<Meta
+  name="description"
+  content="Utility for adding Base UI like features in a custom build components."
+/>
+
+Base UI provides few common features across all components:
+
+- support for a [callback](/react/handbook/styling#css-classes) on the `className` prop where developers can generate classes based on the state of the components
+- [render](/react/handbook/composition) prop that allows developers to override the default rendered element of the component
+- adds data-attributes for the component's state that can be used as style hooks
+
+The `useRenderer` hook allows you to add these feature on your custom built components, so that you can provide consistenc experience across your library.
+
+## API reference
+
+### Input parameters
+
+<PropsReferenceTable
+  data={{
+    className: {
+      type: 'string | ((state: State) => string)',
+      description:
+        'The class name to apply to the rendered element. Can be a string or a function that accepts the state and returns a string.',
+    },
+    render: {
+      type: 'RenderProp<State>',
+      description: 'The render prop or React element to override the default element.',
+    },
+    state: {
+      type: 'State',
+      description:
+        'The state of the component. It will be used as a parameter for the render and className callbacks.',
+    },
+    ref: {
+      type: 'React.Ref<RenderedElementType>',
+      description: 'The ref to apply to the rendered element.',
+    },
+    props: {
+      type: 'Record<string, unknown>',
+      description: 'Props to be spread on the rendered element.',
+    },
+    styleHookMapping: {
+      type: 'StyleHookMapping<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 usage for creating a Text component that generates data-attributes based on its state, and have the support for the `render` prop and the `className` callback.
+
+<Demo path="./demos/usage" />

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',
+      },
     ],
   },
 ];