@diskette/use-render 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # useRender
 
-A React hook for component libraries that enables flexible render prop patterns, allowing consumers to override a component's default rendered element while maintaining proper `ref`, `className`, and `style` merging.
+A React hook for component libraries that lets consumers swap the rendered element—like rendering a `<a>` instead of a `<button>`—while keeping all your component's behavior intact. It handles the tricky parts: merging refs, combining props, and letting className and style respond to internal state.
 
 ## Installation
 
@@ -8,68 +8,58 @@ A React hook for component libraries that enables flexible render prop patterns,
 pnpm add @diskette/use-render
 ```
 
-## Features
+## Quick Start
 
-- **Render prop support** - Override elements via `render` prop (element or function)
-- **State-aware className** - Resolve classNames dynamically based on component state
-- **State-aware style** - Resolve styles dynamically based on component state
-- **Automatic ref merging** - Combines multiple refs seamlessly
-- **Children as render function** - Pass children as a function receiving state
-
-## Usage
-
-### Building a Component
-
-Use `useRender` inside your component to enable the render prop pattern:
+Here's a simple button component that consumers can render as any element:
 
 ```tsx
 import { useRender, type ComponentProps } from '@diskette/use-render'
 
-interface ButtonState {
-  isPressed: boolean
-  isHovered: boolean
-}
-
-type ButtonProps = ComponentProps<'button', ButtonState>
+type ButtonProps = ComponentProps<'button', { isPressed: boolean }>
 
 function Button(props: ButtonProps) {
   const [isPressed, setIsPressed] = useState(false)
-  const [isHovered, setIsHovered] = useState(false)
-
-  const state: ButtonState = { isPressed, isHovered }
 
-  return useRender('button', state, {
-    baseProps: {
-      className: 'btn',
-      onMouseDown: () => setIsPressed(true),
-      onMouseUp: () => setIsPressed(false),
-      onMouseEnter: () => setIsHovered(true),
-      onMouseLeave: () => setIsHovered(false),
+  return useRender(
+    'button',
+    { isPressed },
+    {
+      baseProps: {
+        className: 'btn',
+        onMouseDown: () => setIsPressed(true),
+        onMouseUp: () => setIsPressed(false),
+      },
+      props,
     },
-    props,
-  })
+  )
 }
 ```
 
-### Consuming the Component
-
-#### Default Usage
+Now consumers can use it normally, or swap the element entirely:
 
 ```tsx
+// Renders a <button>
 <Button className="primary">Click me</Button>
+
+// Renders an <a> with all the button's behavior
+<Button render={<a href="/path" />}>Go somewhere</Button>
 ```
 
-#### Override with Element
+## Usage
+
+### Overriding the `Element`
+
+Pass a JSX element to `render` and it will be cloned with your component's props:
 
 ```tsx
 <Button render={<a href="/path" />}>Link styled as button</Button>
 ```
 
-#### Override with Function
+Or pass a function to get full control over rendering, with access to both props and state:
 
 ```tsx
 <Button
-  render={(state, props) => (
+  render={(props, state) => (
     <a {...props} href="/path" data-pressed={state.isPressed} />
   )}
 >
@@ -77,9 +67,9 @@ function Button(props: ButtonProps) {
 </Button>
 ```
 
-### State-Aware className
+### State-Aware `className`
 
-Pass a function to resolve className based on component state:
+Pass a function to compute `className` based on component state. The second argument gives you access to the base `className` set by the component:
 
 ```tsx
 <Button
@@ -91,15 +81,15 @@ Pass a function to resolve className based on component state:
 </Button>
 ```
 
-Or pass a string to merge with the default className (uses `clsx`):
+Or just pass a string. It will be merged with the default `className`:
 
 ```tsx
 <Button className="primary large">Click me</Button>
 ```
 
-### State-Aware style
+### State-Aware style `(CSSProperties)`
 
-Pass a function to resolve styles based on component state:
+Same pattern works for inline styles:
 
 ```tsx
 <Button
@@ -114,83 +104,53 @@ Pass a function to resolve styles based on component state:
 
 ### Children as Render Function
 
-Access state in children:
+Access state by passing a function:
 
 ```tsx
 <Button>{(state) => (state.isPressed ? 'Pressing...' : 'Click me')}</Button>
 ```
 
-## API
-
-### `useRender(tag, options)`
-
-```ts
-function useRender<T extends ElementType, S>(
-  tag: T,
-  state,
-  options: UseRenderOptions<T, S>,
-): ReactNode
-```
+### `render` vs `children` as Function
 
-#### Parameters
+You might wonder why both exist—most libraries pick one or the other. They serve different purposes:
 
-- `tag` - The default element type to render (e.g., `'button'`, `'div'`)
-- `options` - Configuration object
+- **`render`** swaps the element itself. Use it when you need a `<a>` instead of a `<button>`, or want to integrate with a router's `<Link>`.
+- **`children` as function** changes what's inside the element. Use it when the content should react to internal state.
 
-#### Options
+They compose naturally—you can use both at once:
 
-```ts
-interface UseRenderOptions<T extends ElementType, S> {
-  baseProps?: React.ComponentProps<T>
-  props?: ComponentProps<T, S>
-  ref?: React.Ref<any> | (React.Ref<any> | undefined)[]
-}
+```tsx
+<Button render={<a href="/path" />}>
+  {(state) => (state.isPressed ? 'Going...' : 'Go somewhere')}
+</Button>
 ```
 
-| Option      | Description                                                        |
-| ----------- | ------------------------------------------------------------------ |
-| `baseProps` | Base props applied to the element                                  |
-| `props`     | Consumer-provided props (typically forwarded from component props) |
-| `ref`       | Ref(s) to merge with the consumer's ref                            |
-
-### `ComponentProps<T, S>`
-
-Type for component's external public props. Components using `useRender` should use this type (or extend from it) instead of `React.ComponentProps`. It's essentially `React.ComponentProps<T>` augmented with state-aware `className`, `style`, `children`, and the `render` prop:
-
-```ts
-type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
-  children?: ((state: S) => ReactNode) | ReactNode
-  className?: ClassNameResolver<S>
-  style?: StyleResolver<S>
-  render?: Renderer<T, S> | JSX.Element
-}
-```
+## API
 
-### `ClassNameResolver<S>`
+### `useRender(tag, state, options)`
 
 ```ts
-type ClassNameResolver<S> =
-  | ((state: S, baseClassName?: string) => string | undefined)
-  | string
-  | undefined
+function useRender<T extends ElementType, S>(
+  tag: T,
+  state: S,
+  options: UseRenderOptions<T, S>,
+): ReactNode
 ```
 
-### `StyleResolver<S>`
+| Parameter           | Description                                                        |
+| ------------------- | ------------------------------------------------------------------ |
+| `tag`               | Default element type (e.g., `'button'`, `'div'`)                   |
+| `state`             | Component state passed to resolvers and render functions           |
+| `options.baseProps` | Base props applied to the element (your component's defaults)      |
+| `options.props`     | Consumer-provided props (typically forwarded from component props) |
+| `options.ref`       | Ref(s) to merge with the consumer's ref                            |
 
-```ts
-type StyleResolver<S> =
-  | ((state: S, baseStyle?: CSSProperties) => CSSProperties | undefined)
-  | CSSProperties
-  | undefined
-```
+### `ComponentProps<ElementType, State>`
 
-### `Renderer<T, S>`
+Use this type for your component's public props. It extends `React.ComponentProps<T>` and augments `className`, `style`, and `children` to be state-aware as well as provide the `render` prop:
 
 ```ts
-type Renderer<T extends ElementType, S> = (
-  state: S,
-  props: ComponentPropsWithRef<T>,
-) => ReactNode
+type ButtonProps = ComponentProps<'button', ButtonState>
 ```
 
 ## License

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { useRender } from './use-render.ts';
-export type { ComponentProps, UseRenderOptions } from './use-render.ts';
+export type { UseRenderOptions } from './use-render.ts';
+export type { BaseComponentProps, ClassName, ComponentProps, ComponentRenderer, DataAttributes, Style, } from './types.ts';

package/dist/types.d.ts

@@ -1,8 +1,16 @@
-import type { ComponentPropsWithRef, CSSProperties, ElementType, ReactNode } from 'react';
-export type ClassNameResolver<State> = ((state: State, baseClassName?: string) => string | undefined) | string | undefined;
-export type StyleResolver<State> = ((state: State, baseStyle?: CSSProperties) => CSSProperties | undefined) | CSSProperties | undefined;
-export type Renderer<S> = (state: S, props: React.HTMLAttributes<any> & {
-    ref?: React.Ref<any> | undefined;
-}) => ReactNode;
+import type { ComponentPropsWithRef, CSSProperties, ElementType, HTMLAttributes, JSX, ReactNode, Ref } from 'react';
+export type ClassName<State> = ((state: State, baseClassName?: string) => string | undefined) | string;
+export type Style<State> = ((state: State, baseStyle?: CSSProperties) => CSSProperties | undefined) | CSSProperties;
+export type ComponentRenderer<S> = (props: HTMLAttributes<any> & {
+    ref?: Ref<any> | undefined;
+}, state: S) => ReactNode;
 export type DataAttributes = Record<`data-${string}`, string | number | boolean>;
 export type BaseComponentProps<T extends ElementType> = Omit<ComponentPropsWithRef<T>, 'children' | 'className' | 'style'>;
+export type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
+    children?: ReactNode | {
+        bivarianceHack(state: S): ReactNode;
+    }['bivarianceHack'];
+    className?: ClassName<S>;
+    style?: Style<S>;
+    render?: ComponentRenderer<S> | JSX.Element;
+};

package/dist/use-render.d.ts

@@ -1,11 +1,5 @@
-import type { ElementType, JSX, ReactNode } from 'react';
-import type { BaseComponentProps, ClassNameResolver, DataAttributes, Renderer, StyleResolver } from './types.ts';
-export type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
-    children?: ((state: S) => ReactNode) | ReactNode;
-    className?: ClassNameResolver<S>;
-    style?: StyleResolver<S>;
-    render?: Renderer<S> | JSX.Element;
-};
+import type { ElementType, ReactNode } from 'react';
+import type { ComponentProps, DataAttributes } from './types.ts';
 export interface UseRenderOptions<T extends ElementType, S> {
     baseProps?: React.ComponentProps<T> & DataAttributes;
     props?: ComponentProps<T, S> & DataAttributes;
@@ -31,4 +25,4 @@ export interface UseRenderOptions<T extends ElementType, S> {
  * <Button render={<a href="#" />} />
  * ```
  */
-export declare function useRender<T extends ElementType, S>(tag: T, state: S, options: UseRenderOptions<T, S>): ReactNode;
+export declare function useRender<T extends ElementType, S>(tag: T, state: S, options?: UseRenderOptions<T, S>): ReactNode;

package/dist/use-render.js

@@ -21,14 +21,14 @@ import { isFunction, isString, mergeProps, resolveClassName, resolveStyle, } fro
  * <Button render={<a href="#" />} />
  * ```
  */
-export function useRender(tag, state, options) {
+export function useRender(tag, state, options = {}) {
     // Workarounds for getting the prop objects to be typed. But should still be ok as the properties we need is common to all elements
     const baseProps = options.baseProps ?? {};
     const props = (options.props ?? {});
     const { className: baseClassName, style: baseStyle, children: baseChildren, ...base } = baseProps;
     const { className, style, children, ref, render, ...rest } = props ?? {};
-    const resolvedClassName = resolveClassName(baseClassName, className, state);
-    const resolvedStyle = resolveStyle(baseStyle, style, state);
+    const resolvedClassName = resolveClassName(state, baseClassName, className);
+    const resolvedStyle = resolveStyle(state, baseStyle, style);
     const refs = Array.isArray(options.ref)
         ? [ref, ...options.ref]
         : [ref, options.ref];
@@ -49,12 +49,12 @@ export function useRender(tag, state, options) {
     if (isValidElement(render)) {
         return cloneElement(render, resolvedProps, resolvedChildren);
     }
-    // For `<Component render={(state, props) => <a {...props} />)} />`
+    // For `<Component render={(props) => <a {...props} />)} />`
     if (isFunction(render)) {
-        return render(state, {
+        return render({
             ...resolvedProps,
             children: resolvedChildren,
-        });
+        }, state);
     }
     return createElement(tag, resolvedProps, resolvedChildren ?? baseChildren);
 }

package/dist/use-render.test.jsx

@@ -1,6 +1,7 @@
 import React, { useState } from 'react';
 import { describe, expect, test, vi } from 'vitest';
 import { render } from 'vitest-browser-react';
+import {} from "./types.js";
 import { useRender } from "./use-render.js";
 function createBtn(defaultProps) {
     return function Button(props) {
@@ -126,9 +127,9 @@ describe('useRender', () => {
             await expect.element(link).toHaveTextContent('Link');
             await expect.element(link).toHaveAttribute('href', '/path');
         });
-        test('render function receives state and props', async () => {
+        test('render function receives props and state', async () => {
             const Button = createBtn();
-            const { getByRole } = await render(<Button className="custom" render={(state, props) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
+            const { getByRole } = await render(<Button className="custom" render={(props, state) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
                         e.preventDefault();
                         props.onClick?.(e);
                     }}/>)}>
@@ -153,7 +154,7 @@ describe('useRender', () => {
         });
         test('function render prop with children as function', async () => {
             const Button = createBtn();
-            const { getByRole } = await render(<Button render={(state, props) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
+            const { getByRole } = await render(<Button render={(props, state) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
                         e.preventDefault();
                         props.onClick?.(e);
                     }}/>)}>

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
 import type { CSSProperties } from 'react';
-import type { ClassNameResolver, StyleResolver } from './types.ts';
+import type { ClassName, Style } from './types.ts';
 export declare const isString: (value: unknown) => value is string;
 export declare const isFunction: (value: unknown) => value is Function;
 export declare const isUndefined: (value: unknown) => value is undefined;
@@ -15,14 +15,14 @@ export declare function mergeProps<T extends Record<string, unknown>>(defaultPro
  * - Merges string values using clsx
  * - Function props receive the resolved default value
  */
-export declare function resolveClassName<State>(defaultClassName: ClassNameResolver<State>, propsClassName: ClassNameResolver<State>, state: State): string | undefined;
+export declare function resolveClassName<State>(state: State, defaultClassName?: ClassName<State>, propsClassName?: ClassName<State>): string | undefined;
 /**
  * Resolves and merges style values from defaultProps and props.
  * - Resolves function values with the provided state
  * - Merges object values using object spread
  * - Function props receive the resolved default value
  */
-export declare function resolveStyle<State>(defaultStyle: StyleResolver<State>, propsStyle: StyleResolver<State>, state: State): CSSProperties | undefined;
+export declare function resolveStyle<State>(state: State, defaultStyle?: Style<State>, propsStyle?: Style<State>): CSSProperties | undefined;
 type ClassValue = ClassValue[] | Record<string, any> | string | number | bigint | null | boolean | undefined;
 export declare function clsx(...inputs: ClassValue[]): string;
 export {};

package/dist/utils.js

@@ -27,7 +27,7 @@ export function mergeProps(defaultProps, props) {
  * - Merges string values using clsx
  * - Function props receive the resolved default value
  */
-export function resolveClassName(defaultClassName, propsClassName, state) {
+export function resolveClassName(state, defaultClassName, propsClassName) {
     const resolvedDefault = isFunction(defaultClassName)
         ? defaultClassName(state)
         : defaultClassName;
@@ -49,7 +49,7 @@ export function resolveClassName(defaultClassName, propsClassName, state) {
  * - Merges object values using object spread
  * - Function props receive the resolved default value
  */
-export function resolveStyle(defaultStyle, propsStyle, state) {
+export function resolveStyle(state, defaultStyle, propsStyle) {
     const resolvedDefault = isFunction(defaultStyle)
         ? defaultStyle(state)
         : defaultStyle;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@diskette/use-render",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "exports": "./dist/index.js",
   "files": [
     "dist"