@diskette/use-render 0.6.1 → 0.8.0

package/README.md

@@ -1,158 +1,138 @@
 # useRender
 
-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
+React hooks for building components with render prop composition and type-safe state-driven styling.
 
 ```bash
 pnpm add @diskette/use-render
 ```
 
-## Quick Start
+## Overview
 
-Here's a simple button component that consumers can render as any element:
+When building component libraries, you often need to let consumers customize rendering—swap the underlying element, access internal state for styling, or compose refs and event handlers. These hooks handle that plumbing:
 
-```tsx
-import { useRender, type ComponentProps } from '@diskette/use-render'
+- **Component authors** get prop merging, ref composition, and render prop support out of the box
+- **Consumers** get type-safe APIs where `className`, `style`, and `children` can be functions of component state
 
-type ButtonProps = ComponentProps<'button', { isPressed: boolean }>
+## `useRenderSlot` — Stateless Slots
 
-function Button(props: ButtonProps) {
-  const [isPressed, setIsPressed] = useState(false)
-
-  return useRender(
-    'button',
-    { isPressed },
-    {
-      baseProps: {
-        className: 'btn',
-        onMouseDown: () => setIsPressed(true),
-        onMouseUp: () => setIsPressed(false),
-      },
-      props,
-    },
-  )
-}
-```
+For wrapper components that don't expose internal state. Consumers can still swap the element or pass props—they just won't get state callbacks.
 
-Now consumers can use it normally, or swap the element entirely:
+**Component author:**
 
 ```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>
-```
+import { useRenderSlot, SlotProps } from '@diskette/use-render'
 
-## Usage
+type CardProps = SlotProps<'div'>
 
-### Overriding the `Element`
+function Card(props: CardProps) {
+  return useRenderSlot('div', { props, baseProps: { className: 'card' } })
+}
+```
 
-Pass a JSX element to `render` and it will be cloned with your component's props:
+**Consumer:**
 
 ```tsx
-<Button render={<a href="/path" />}>Link styled as button</Button>
+<Card className="card-primary">Content</Card>
+<Card render={<section />}>Content</Card>
+<Card render={(props) => <article {...props} />}>Content</Card>
 ```
 
-Or pass a function to get full control over rendering, with access to both props and state:
+Props merge automatically—`className` and `style` combine, refs compose, event handlers chain (consumer runs first). The `render` prop receives only `props` since there's no state to pass.
 
-```tsx
-<Button
-  render={(props, state) => (
-    <a {...props} href="/path" data-pressed={state.isPressed} />
-  )}
->
-  Link with state access
-</Button>
-```
+## `useRender` — Stateful Components
 
-### State-Aware `className`
+For components that expose internal state to consumers. The state flows through `className`, `style`, `children`, and `render` as callback parameters.
 
-Pass a function to compute `className` based on component state. The second argument gives you access to the base `className` set by the component:
+**Component author:**
 
 ```tsx
-<Button
-  className={(state, baseClassName) =>
-    `${baseClassName} ${state.isPressed ? 'pressed' : ''}`
-  }
->
-  Press me
-</Button>
-```
+import { useRender, ComponentProps } from '@diskette/use-render'
 
-Or just pass a string. It will be merged with the default `className`:
+type State = { disabled: boolean; loading: boolean }
+type ButtonProps = ComponentProps<'button', State>
 
-```tsx
-<Button className="primary large">Click me</Button>
+function Button(props: ButtonProps) {
+  const state: State = { disabled: props.disabled ?? false, loading: false }
+  return useRender('button', state, { props })
+}
 ```
 
-### State-Aware style `(CSSProperties)`
-
-Same pattern works for inline styles:
+**Consumer:**
 
 ```tsx
-<Button
-  style={(state) => ({
-    backgroundColor: state.isPressed ? 'darkblue' : 'blue',
-    transform: state.isPressed ? 'scale(0.98)' : undefined,
-  })}
->
-  Press me
-</Button>
-```
+// State-driven className
+<Button className={(state) => state.disabled ? 'opacity-50' : undefined} />
 
-### Children as Render Function
+// State-driven className with access to base className
+<Button className={(state, base) => `${base} ${state.disabled ? 'opacity-50' : ''}`} />
 
-Access state by passing a function:
+// State-driven style
+<Button style={(state) => ({ opacity: state.disabled ? 0.5 : 1 })} />
 
-```tsx
-<Button>{(state) => (state.isPressed ? 'Pressing...' : 'Click me')}</Button>
+// State-driven style with access to base style
+<Button style={(state, base) => ({ ...base, opacity: state.disabled ? 0.5 : 1 })} />
+
+// State-driven children
+<Button>{(state) => state.loading ? 'Loading...' : 'Submit'}</Button>
+
+// Render prop with state access
+<Button render={(props, state) => <a {...props} aria-busy={state.loading} />} />
 ```
 
-### `render` vs `children` as Function
+The `render` callback receives `(props, state)` for full control over both props and rendering.
 
-You might wonder why both exist—most libraries pick one or the other. They serve different purposes:
+## `useRenderContainer` — Containers with Items
 
-- **`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.
+For list-like components with two levels of state: container-level (e.g., item count) and item-level (e.g., index, value). The `className` and `style` callbacks receive container state, while `children` receives item state.
 
-They compose naturally—you can use both at once:
+**Component author:**
 
 ```tsx
-<Button render={<a href="/path" />}>
-  {(state) => (state.isPressed ? 'Going...' : 'Go somewhere')}
-</Button>
+import { useRenderContainer, ContainerProps } from '@diskette/use-render'
+
+type ContainerState = { count: number }
+type ItemState = { index: number; value: string }
+type ListProps = ContainerProps<'ul', ContainerState, ItemState>
+
+function List({ items, ...props }: ListProps & { items: string[] }) {
+  const { Container, renderItem, containerProps } = useRenderContainer(
+    'ul',
+    { count: items.length },
+    { props, baseProps: { children: (item) => <li>{item.value}</li> } },
+  )
+  // containerProps provides direct access to resolved props if needed
+  return <Container>{items.map((v, i) => renderItem({ index: i, value: v }))}</Container>
+}
 ```
 
-## API
+**Consumer:**
 
-### `useRender(tag, state, options)`
+```tsx
+// Container className receives ContainerState
+<List items={data} className={(state) => state.count > 5 ? 'scrollable' : undefined} />
+
+// Children function receives ItemState
+<List items={data}>{(item) => <li>{item.index + 1}. {item.value}</li>}</List>
 
-```ts
-function useRender<T extends ElementType, S>(
-  tag: T,
-  state: S,
-  options: UseRenderOptions<T, S>,
-): ReactNode
+// Swap container element
+<List items={data} render={<ol />} />
 ```
 
-| 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                            |
+## Props Types
 
-### `ComponentProps<ElementType, State>`
+Each hook has a corresponding type for your component's public API:
 
-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:
+| Hook | Props Type | State |
+|------|-----------|-------|
+| `useRenderSlot` | `SlotProps<T>` | None |
+| `useRender` | `ComponentProps<T, S>` | Single state |
+| `useRenderContainer` | `ContainerProps<T, CS, IS>` | Container + Item |
 
-```ts
-type ButtonProps = ComponentProps<'button', ButtonState>
-```
+These extend the element's native props, adding `render` and (for stateful hooks) function forms of `className`, `style`, and `children`.
 
-## License
+## What the Hooks Handle
 
-[MIT](./LICENSE) License
+- **Render prop** — swap the element via `render={<a />}` or `render={(props) => ...}`
+- **Ref composition** — refs from consumer, base props, and options are merged
+- **Event handler chaining** — consumer handlers run first, then base handlers
+- **className/style merging** — static values combine; functions receive state and the resolved base value as parameters

package/dist/index.d.ts

@@ -1,3 +1,7 @@
 export { useRender } from './use-render.ts';
+export { useRenderContainer } from './use-render-container.ts';
+export { useRenderSlot } from './use-render-slot.ts';
 export type { UseRenderOptions } from './use-render.ts';
+export type { SlotProps, SlotRenderer, UseRenderSlotOptions, } from './use-render-slot.ts';
+export type { ContainerBaseProps, ContainerProps, UseRenderContainerOptions, UseRenderContainerResult, } from './use-render-container.ts';
 export type { BaseComponentProps, ClassName, ComponentProps, ComponentRenderer, DataAttributes, Style, } from './types.ts';

package/dist/index.js

@@ -1 +1,3 @@
 export { useRender } from "./use-render.js";
+export { useRenderContainer } from "./use-render-container.js";
+export { useRenderSlot } from "./use-render-slot.js";

package/dist/use-composed-ref.d.ts

@@ -6,9 +6,12 @@ import { type Ref, type RefCallback } from 'react';
  * @returns The ref cleanup callback, if any.
  */
 export declare function assignRef<T>(ref: Ref<T> | undefined | null, value: T | null): ReturnType<RefCallback<T>>;
+type RefInput<T> = Ref<T> | undefined | (Ref<T> | undefined)[];
 /**
  * Composes multiple refs into a single one and memoizes the result to avoid refs execution on each render.
- * @param refs List of refs to merge.
+ * Accepts individual refs or arrays of refs, which are flattened automatically.
+ * @param refs Refs to merge (individual or arrays).
  * @returns Merged ref.
  */
-export declare function useComposedRef<T>(refs: (Ref<T> | undefined)[]): Ref<T>;
+export declare function useComposedRef<T>(...refs: RefInput<T>[]): Ref<T>;
+export {};

package/dist/use-composed-ref.js

@@ -29,9 +29,11 @@ function mergeRefs(refs) {
 }
 /**
  * Composes multiple refs into a single one and memoizes the result to avoid refs execution on each render.
- * @param refs List of refs to merge.
+ * Accepts individual refs or arrays of refs, which are flattened automatically.
+ * @param refs Refs to merge (individual or arrays).
  * @returns Merged ref.
  */
-export function useComposedRef(refs) {
-    return useMemo(() => mergeRefs(refs), refs);
+export function useComposedRef(...refs) {
+    const flatRefs = refs.flat();
+    return useMemo(() => mergeRefs(flatRefs), flatRefs);
 }

package/dist/use-render-container.d.ts

@@ -0,0 +1,81 @@
+import type { CSSProperties, ElementType, JSX, ReactNode, Ref } from 'react';
+import type { BaseComponentProps, ClassName, ComponentRenderer, DataAttributes, Style } from './types.ts';
+type Children<S> = ((state: S) => ReactNode) | ReactNode;
+/**
+ * Props for the container element.
+ * - className/style resolve with ContainerState
+ * - children resolves with ItemState (per-item rendering)
+ * - render prop swaps the container element
+ */
+export type ContainerProps<T extends ElementType, ContainerState, ItemState = ContainerState> = BaseComponentProps<T> & {
+    className?: ClassName<ContainerState> | undefined;
+    style?: Style<ContainerState> | undefined;
+    children?: Children<ItemState> | undefined;
+    render?: ComponentRenderer<ContainerState> | JSX.Element;
+};
+/**
+ * Base props for the container with defaults.
+ * - className/style are static (no state resolution)
+ * - children can be a function of ItemState for default item rendering
+ */
+export type ContainerBaseProps<T extends ElementType, ItemState> = Omit<React.ComponentProps<T>, 'children' | 'className' | 'style'> & DataAttributes & {
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+    children?: Children<ItemState> | undefined;
+};
+export interface UseRenderContainerOptions<T extends ElementType, ContainerState, ItemState> {
+    props?: ContainerProps<T, ContainerState, ItemState> & DataAttributes;
+    baseProps?: ContainerBaseProps<T, ItemState>;
+    ref?: Ref<any> | (Ref<any> | undefined)[];
+}
+export interface UseRenderContainerResult<T extends ElementType, ItemState> {
+    /** Renders the container element with resolved props */
+    Container: (props: {
+        children?: ReactNode;
+    }) => ReactNode;
+    /** Resolves children with item-specific state */
+    renderItem: (itemState: ItemState) => ReactNode;
+    /** Direct access to resolved container props */
+    containerProps: React.ComponentProps<T>;
+}
+/**
+ * Hook for rendering container elements with item-level render control.
+ *
+ * Combines the prop resolution of useRender with the render control of useRenderProps.
+ * - Container: handles className/style resolution, ref composition, and render prop
+ * - renderItem: resolves children function with per-item state
+ *
+ * @example
+ * ```tsx
+ * type ContainerState = { locale: string }
+ * type ItemState = ContainerState & { date: Date; index: number }
+ *
+ * function DateList(props: ContainerProps<'div', ContainerState, ItemState>) {
+ *   const { Container, renderItem } = useRenderContainer('div', { locale: 'en' }, {
+ *     props,
+ *     baseProps: {
+ *       role: 'list',
+ *       children: (state) => <DateItem date={state.date} />,
+ *     },
+ *   })
+ *   const dates = generateDates()
+ *
+ *   return (
+ *     <Container>
+ *       {dates.map((date, index) => (
+ *         <ItemContext key={date.toString()}>
+ *           {renderItem({ date, index, locale: 'en' })}
+ *         </ItemContext>
+ *       ))}
+ *     </Container>
+ *   )
+ * }
+ *
+ * // Consumer usage:
+ * <DateList className={(state) => state.locale === 'en' && 'ltr'} />
+ * <DateList render={<section />} />
+ * <DateList>{(state) => <CustomDateItem date={state.date} />}</DateList>
+ * ```
+ */
+export declare function useRenderContainer<T extends ElementType, ContainerState, ItemState = ContainerState>(tag: T, containerState: ContainerState, options?: UseRenderContainerOptions<T, ContainerState, ItemState>): UseRenderContainerResult<T, ItemState>;
+export {};

package/dist/use-render-container.js

@@ -0,0 +1,98 @@
+import { cloneElement, createElement, isValidElement, useCallback, useMemo, } from 'react';
+import { useComposedRef } from "./use-composed-ref.js";
+import { isFunction, isString, mergeProps, resolveClassName, resolveStyle, } from "./utils.js";
+/**
+ * Hook for rendering container elements with item-level render control.
+ *
+ * Combines the prop resolution of useRender with the render control of useRenderProps.
+ * - Container: handles className/style resolution, ref composition, and render prop
+ * - renderItem: resolves children function with per-item state
+ *
+ * @example
+ * ```tsx
+ * type ContainerState = { locale: string }
+ * type ItemState = ContainerState & { date: Date; index: number }
+ *
+ * function DateList(props: ContainerProps<'div', ContainerState, ItemState>) {
+ *   const { Container, renderItem } = useRenderContainer('div', { locale: 'en' }, {
+ *     props,
+ *     baseProps: {
+ *       role: 'list',
+ *       children: (state) => <DateItem date={state.date} />,
+ *     },
+ *   })
+ *   const dates = generateDates()
+ *
+ *   return (
+ *     <Container>
+ *       {dates.map((date, index) => (
+ *         <ItemContext key={date.toString()}>
+ *           {renderItem({ date, index, locale: 'en' })}
+ *         </ItemContext>
+ *       ))}
+ *     </Container>
+ *   )
+ * }
+ *
+ * // Consumer usage:
+ * <DateList className={(state) => state.locale === 'en' && 'ltr'} />
+ * <DateList render={<section />} />
+ * <DateList>{(state) => <CustomDateItem date={state.date} />}</DateList>
+ * ```
+ */
+// TODO: refactor args order, useRenderContainer('div', props, options). `props` is what defines what the interface is for the state
+export function useRenderContainer(tag, containerState, options = {}) {
+    // Workaround for getting the prop objects to be typed. Should still be ok as the properties we need are 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;
+    // Resolve container className/style with container state
+    const resolvedClassName = resolveClassName(containerState, baseClassName, className);
+    const resolvedStyle = resolveStyle(containerState, baseStyle, style);
+    // Compose refs
+    const mergedRef = useComposedRef(ref, options.ref);
+    // Build resolved container props (memoized for stable useCallback reference)
+    const resolvedProps = useMemo(() => {
+        const props = {
+            ...mergeProps(base, rest),
+            ref: mergedRef,
+        };
+        if (isString(resolvedClassName)) {
+            props.className = resolvedClassName;
+        }
+        if (typeof resolvedStyle === 'object') {
+            props.style = resolvedStyle;
+        }
+        return props;
+    }, [base, rest, mergedRef, resolvedClassName, resolvedStyle]);
+    // Container component that handles render prop
+    const Container = useCallback(({ children: containerChildren }) => {
+        const propsWithChildren = {
+            ...resolvedProps,
+            children: containerChildren,
+        };
+        // For `<Component render={<section />} />`
+        if (isValidElement(render)) {
+            return cloneElement(render, propsWithChildren);
+        }
+        // For `<Component render={(props, state) => <section {...props} />} />`
+        if (isFunction(render)) {
+            return render(propsWithChildren, containerState);
+        }
+        return createElement(tag, propsWithChildren);
+    }, [resolvedProps, render, containerState, tag]);
+    // Render function for items - resolves children with item state
+    const renderItem = useCallback((itemState) => {
+        // Props children take precedence over base children
+        const childrenToRender = children !== undefined ? children : baseChildren;
+        return isFunction(childrenToRender)
+            ? childrenToRender(itemState)
+            : childrenToRender;
+    }, [children, baseChildren]);
+    return {
+        Container,
+        renderItem,
+        containerProps: resolvedProps,
+    };
+}

package/dist/use-render-slot.d.ts

@@ -0,0 +1,39 @@
+import type { ComponentPropsWithRef, CSSProperties, ElementType, HTMLAttributes, JSX, ReactNode, Ref } from 'react';
+import type { DataAttributes } from './types.ts';
+export type SlotRenderer = (props: HTMLAttributes<any> & {
+    ref?: Ref<any> | undefined;
+}) => ReactNode;
+export type SlotProps<T extends ElementType> = Omit<ComponentPropsWithRef<T>, 'className' | 'style'> & {
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+    render?: SlotRenderer | JSX.Element;
+};
+export interface UseRenderSlotOptions<T extends ElementType> {
+    baseProps?: React.ComponentProps<T> & DataAttributes;
+    props?: SlotProps<T> & DataAttributes;
+    ref?: Ref<any> | (Ref<any> | undefined)[];
+}
+/**
+ * Hook for rendering slot elements with render prop support and prop merging.
+ * A simpler version of useRender for stateless components.
+ *
+ * @example
+ * ```tsx
+ * import { useRenderSlot, SlotProps } from '@diskette/use-render'
+ *
+ * type CardProps = SlotProps<'div'>
+ *
+ * function Card(props: CardProps) {
+ *   return useRenderSlot('div', {
+ *     props,
+ *     baseProps: { className: 'card' },
+ *   })
+ * }
+ *
+ * // Usage:
+ * <Card className="card-primary" />
+ * <Card render={<section />} />
+ * <Card render={(props) => <article {...props} />} />
+ * ```
+ */
+export declare function useRenderSlot<T extends ElementType>(tag: T, options?: UseRenderSlotOptions<T>): ReactNode;

package/dist/use-render-slot.js

@@ -0,0 +1,55 @@
+import { cloneElement, createElement, isValidElement } from 'react';
+import { useComposedRef } from "./use-composed-ref.js";
+import { cx, isFunction, isString, mergeProps } from "./utils.js";
+/**
+ * Hook for rendering slot elements with render prop support and prop merging.
+ * A simpler version of useRender for stateless components.
+ *
+ * @example
+ * ```tsx
+ * import { useRenderSlot, SlotProps } from '@diskette/use-render'
+ *
+ * type CardProps = SlotProps<'div'>
+ *
+ * function Card(props: CardProps) {
+ *   return useRenderSlot('div', {
+ *     props,
+ *     baseProps: { className: 'card' },
+ *   })
+ * }
+ *
+ * // Usage:
+ * <Card className="card-primary" />
+ * <Card render={<section />} />
+ * <Card render={(props) => <article {...props} />} />
+ * ```
+ */
+export function useRenderSlot(tag, options = {}) {
+    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 = cx(baseClassName, className);
+    const resolvedStyle = baseStyle || style ? { ...baseStyle, ...style } : undefined;
+    const mergedRef = useComposedRef(ref, options.ref);
+    const resolvedProps = {
+        ...mergeProps(base, rest),
+        ref: mergedRef,
+    };
+    if (isString(resolvedClassName)) {
+        resolvedProps.className = resolvedClassName;
+    }
+    if (typeof resolvedStyle === 'object') {
+        resolvedProps.style = resolvedStyle;
+    }
+    const resolvedChildren = children ?? baseChildren;
+    // For `<Component render={<a />} />`
+    if (isValidElement(render)) {
+        return cloneElement(render, resolvedProps, resolvedChildren);
+    }
+    // For `<Component render={(props) => <a {...props} />)} />`
+    if (isFunction(render)) {
+        return render({ ...resolvedProps, children: resolvedChildren });
+    }
+    return createElement(tag, resolvedProps, resolvedChildren);
+}

package/dist/use-render.js

@@ -29,10 +29,7 @@ export function useRender(tag, state, options = {}) {
     const { className, style, children, ref, render, ...rest } = props ?? {};
     const resolvedClassName = resolveClassName(state, baseClassName, className);
     const resolvedStyle = resolveStyle(state, baseStyle, style);
-    const refs = Array.isArray(options.ref)
-        ? [ref, ...options.ref]
-        : [ref, options.ref];
-    const mergedRef = useComposedRef(refs);
+    const mergedRef = useComposedRef(ref, options.ref);
     // Another workaround for getting component props typed
     const resolvedProps = {
         ...mergeProps(base, rest),
@@ -51,10 +48,7 @@ export function useRender(tag, state, options = {}) {
     }
     // For `<Component render={(props) => <a {...props} />)} />`
     if (isFunction(render)) {
-        return render({
-            ...resolvedProps,
-            children: resolvedChildren,
-        }, state);
+        return render({ ...resolvedProps, children: resolvedChildren }, state);
     }
     return createElement(tag, resolvedProps, resolvedChildren ?? baseChildren);
 }

package/package.json

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

package/dist/use-render.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/use-render.test.jsx

@@ -1,241 +0,0 @@
-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) {
-        const [isActive, setIsActive] = useState(false);
-        const state = { isActive };
-        return useRender('button', state, {
-            props,
-            baseProps: {
-                onClick: () => setIsActive((cur) => !cur),
-                ...defaultProps,
-            },
-        });
-    };
-}
-describe('useRender', () => {
-    describe('className', () => {
-        test('renders with static string className', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button className="btn-primary">Click</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('btn-primary');
-        });
-        test('className function receives state', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button className={(state) => (state.isActive ? 'active' : 'inactive')}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('inactive');
-            await button.click();
-            await expect.element(button).toHaveClass('active');
-        });
-        test('className function receives baseClassName as second argument', async () => {
-            const Button = createBtn({ className: 'btn-default' });
-            const { getByRole } = await render(<Button className={(_state, baseClassName) => `custom ${baseClassName ?? ''}`}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('custom');
-            await expect.element(button).toHaveClass('btn-default');
-        });
-        test('merges props className with defaultProps className', async () => {
-            const Button = createBtn({ className: 'btn-base' });
-            const { getByRole } = await render(<Button className="btn-primary">Click</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('btn-base');
-            await expect.element(button).toHaveClass('btn-primary');
-        });
-    });
-    describe('style', () => {
-        test('renders with static style object', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button style={{ backgroundColor: 'red' }}>Click</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveStyle({ backgroundColor: 'red' });
-        });
-        test('style function receives state', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button style={(state) => ({
-                    backgroundColor: state.isActive ? 'green' : 'gray',
-                })}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveStyle({ backgroundColor: 'gray' });
-            await button.click();
-            await expect.element(button).toHaveStyle({ backgroundColor: 'green' });
-        });
-        test('style function receives baseStyle as second argument', async () => {
-            const Button = createBtn({ style: { padding: '10px' } });
-            const { getByRole } = await render(<Button style={(_state, baseStyle) => ({
-                    ...baseStyle,
-                    color: 'blue',
-                })}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect
-                .element(button)
-                .toHaveStyle({ padding: '10px', color: 'blue' });
-        });
-        test('merges props style with defaultProps style', async () => {
-            const Button = createBtn({
-                style: { padding: '10px', margin: '5px' },
-            });
-            const { getByRole } = await render(<Button style={{ padding: '20px', color: 'red' }}>Click</Button>);
-            const button = getByRole('button');
-            // Props style should override default where they overlap
-            await expect.element(button).toHaveStyle({
-                padding: '20px',
-                margin: '5px',
-                color: 'red',
-            });
-        });
-    });
-    describe('children', () => {
-        test('renders static children', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button>Static Text</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveTextContent('Static Text');
-        });
-        test('children function receives state', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button>{(state) => (state.isActive ? 'Active!' : 'Inactive')}</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveTextContent('Inactive');
-            await button.click();
-            await expect.element(button).toHaveTextContent('Active!');
-        });
-        test('uses defaultProps children when no children provided', async () => {
-            const Button = createBtn({ children: 'Default Text' });
-            const { getByRole } = await render(<Button />);
-            const button = getByRole('button');
-            await expect.element(button).toHaveTextContent('Default Text');
-        });
-    });
-    describe('render', () => {
-        test('renders element from render prop instead of default tag', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button render={<a href="/path"/>}>Link</Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Link');
-            await expect.element(link).toHaveAttribute('href', '/path');
-        });
-        test('render function receives props and state', async () => {
-            const Button = createBtn();
-            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);
-                    }}/>)}>
-          Link
-        </Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Link');
-            await expect.element(link).toHaveAttribute('href', '/path');
-            await expect.element(link).toHaveClass('custom');
-            await expect.element(link).toHaveAttribute('data-active', 'false');
-            await link.click();
-            await expect.element(link).toHaveAttribute('data-active', 'true');
-        });
-        test('element render prop with children as function', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button render={<a href="/path"/>}>
-          {(state) => (state.isActive ? 'Active Link' : 'Inactive Link')}
-        </Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Inactive Link');
-            await expect.element(link).toHaveAttribute('href', '/path');
-        });
-        test('function render prop with children as function', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button render={(props, state) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
-                        e.preventDefault();
-                        props.onClick?.(e);
-                    }}/>)}>
-          {(state) => (state.isActive ? 'Active Link' : 'Inactive Link')}
-        </Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Inactive Link');
-            await expect.element(link).toHaveAttribute('data-active', 'false');
-            await link.click();
-            await expect.element(link).toHaveTextContent('Active Link');
-            await expect.element(link).toHaveAttribute('data-active', 'true');
-        });
-    });
-    describe('event handler composition', () => {
-        test('composes event handlers - both run, user first then default', async () => {
-            const callOrder = [];
-            const defaultHandler = vi.fn(() => callOrder.push('default'));
-            const userHandler = vi.fn(() => callOrder.push('user'));
-            const Button = createBtn({ onMouseEnter: defaultHandler });
-            const { getByRole } = await render(<Button onMouseEnter={userHandler}>Click</Button>);
-            const button = getByRole('button');
-            await button.hover();
-            expect(defaultHandler).toHaveBeenCalledTimes(1);
-            expect(userHandler).toHaveBeenCalledTimes(1);
-            expect(callOrder).toEqual(['user', 'default']);
-        });
-        test('user handler return value is preserved', async () => {
-            const defaultHandler = vi.fn(() => 'default-result');
-            const userHandler = vi.fn(() => 'user-result');
-            let capturedResult;
-            function TestButton(props) {
-                const [isActive, setIsActive] = useState(false);
-                return useRender('button', { isActive }, {
-                    props,
-                    baseProps: {
-                        onClick: (_e) => {
-                            setIsActive((cur) => !cur);
-                            return defaultHandler();
-                        },
-                    },
-                });
-            }
-            const { getByRole } = await render(<TestButton onClick={() => {
-                    capturedResult = userHandler();
-                    return capturedResult;
-                }}>
-          Click
-        </TestButton>);
-            const button = getByRole('button');
-            await button.click();
-            expect(userHandler).toHaveBeenCalled();
-            expect(defaultHandler).toHaveBeenCalled();
-            expect(capturedResult).toBe('user-result');
-        });
-        test('only default handler runs when no user handler provided', async () => {
-            const defaultHandler = vi.fn();
-            const Button = createBtn({ onMouseEnter: defaultHandler });
-            const { getByRole } = await render(<Button>Click</Button>);
-            const button = getByRole('button');
-            await button.hover();
-            expect(defaultHandler).toHaveBeenCalledTimes(1);
-        });
-        test('only user handler runs when no default handler', async () => {
-            const userHandler = vi.fn();
-            const Button = createBtn();
-            const { getByRole } = await render(<Button onMouseEnter={userHandler}>Click</Button>);
-            const button = getByRole('button');
-            await button.hover();
-            expect(userHandler).toHaveBeenCalledTimes(1);
-        });
-        test('composed onClick still updates internal state', async () => {
-            const userHandler = vi.fn();
-            const Button = createBtn();
-            const { getByRole } = await render(<Button className={(state) => (state.isActive ? 'active' : 'inactive')} onClick={userHandler}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('inactive');
-            await button.click();
-            await expect.element(button).toHaveClass('active');
-            expect(userHandler).toHaveBeenCalledTimes(1);
-        });
-    });
-});