@diskette/use-render 0.7.0 → 0.9.0

package/README.md

@@ -1,158 +1,189 @@
 # 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
+
+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:
+
+- **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
+
+## `useRenderSlot` — Stateless Slots
+
+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.
 
-Here's a simple button component that consumers can render as any element:
+**Component author:**
 
 ```tsx
-import { useRender, type ComponentProps } from '@diskette/use-render'
+import { useRenderSlot, SlotProps } from '@diskette/use-render'
 
-type ButtonProps = ComponentProps<'button', { isPressed: boolean }>
+type CardProps = SlotProps<'div'>
 
-function Button(props: ButtonProps) {
-  const [isPressed, setIsPressed] = useState(false)
-
-  return useRender(
-    'button',
-    { isPressed },
-    {
-      baseProps: {
-        className: 'btn',
-        onMouseDown: () => setIsPressed(true),
-        onMouseUp: () => setIsPressed(false),
-      },
-      props,
-    },
-  )
+function Card(props: CardProps) {
+  return useRenderSlot('div', { props, baseProps: { className: 'card' } })
 }
 ```
 
-Now consumers can use it normally, or swap the element entirely:
+**Consumer:**
 
 ```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>
+<Card className="card-primary">Content</Card>
+<Card render={<section />}>Content</Card>
+<Card render={(props) => <article {...props} />}>Content</Card>
 ```
 
-## Usage
+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.
+
+## `useRender` — Stateful Components
 
-### Overriding the `Element`
+For components that expose internal state to consumers. The state flows through `className`, `style`, `children`, and `render` as callback parameters.
 
-Pass a JSX element to `render` and it will be cloned with your component's props:
+**Component author:**
 
 ```tsx
-<Button render={<a href="/path" />}>Link styled as button</Button>
+import { useRender, ComponentProps } from '@diskette/use-render'
+
+type State = { disabled: boolean; loading: boolean }
+type ButtonProps = ComponentProps<'button', State>
+
+function Button(props: ButtonProps) {
+  const state: State = { disabled: props.disabled ?? false, loading: false }
+  return useRender('button', state, { props })
+}
 ```
 
-Or pass a function to get full control over rendering, with access to both props and state:
+**Consumer:**
 
 ```tsx
-<Button
-  render={(props, state) => (
-    <a {...props} href="/path" data-pressed={state.isPressed} />
-  )}
->
-  Link with state access
-</Button>
-```
+// State-driven className
+<Button className={(state) => state.disabled ? 'opacity-50' : undefined} />
 
-### State-Aware `className`
+// State-driven className with access to base className
+<Button className={(state, base) => `${base} ${state.disabled ? 'opacity-50' : ''}`} />
 
-Pass a function to compute `className` based on component state. The second argument gives you access to the base `className` set by the component:
+// State-driven style
+<Button style={(state) => ({ opacity: state.disabled ? 0.5 : 1 })} />
 
-```tsx
-<Button
-  className={(state, baseClassName) =>
-    `${baseClassName} ${state.isPressed ? 'pressed' : ''}`
-  }
->
-  Press me
-</Button>
-```
+// State-driven style with access to base style
+<Button style={(state, base) => ({ ...base, opacity: state.disabled ? 0.5 : 1 })} />
 
-Or just pass a string. It will be merged with the default `className`:
+// State-driven children
+<Button>{(state) => state.loading ? 'Loading...' : 'Submit'}</Button>
 
-```tsx
-<Button className="primary large">Click me</Button>
+// Render prop with state access
+<Button render={(props, state) => <a {...props} aria-busy={state.loading} />} />
 ```
 
-### State-Aware style `(CSSProperties)`
+The `render` callback receives `(props, state)` for full control over both props and rendering.
+
+## `useRenderContainer` — Containers with Items
+
+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.
 
-Same pattern works for inline styles:
+**Component author:**
 
 ```tsx
-<Button
-  style={(state) => ({
-    backgroundColor: state.isPressed ? 'darkblue' : 'blue',
-    transform: state.isPressed ? 'scale(0.98)' : undefined,
-  })}
->
-  Press me
-</Button>
-```
+import { useRenderContainer, ContainerProps } from '@diskette/use-render'
+
+type ContainerState = { count: number }
+type ItemState = { index: number; value: string }
+type ListProps = ContainerProps<'ul', ContainerState, ItemState>
 
-### Children as Render Function
+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>
+}
+```
 
-Access state by passing a function:
+**Consumer:**
 
 ```tsx
-<Button>{(state) => (state.isPressed ? 'Pressing...' : 'Click me')}</Button>
+// 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>
+
+// Swap container element
+<List items={data} render={<ol />} />
 ```
 
-### `render` vs `children` as Function
+## Props Types
+
+Each hook has a corresponding type for your component's public API:
+
+| Hook | Props Type | State |
+|------|-----------|-------|
+| `useRenderSlot` | `SlotProps<T>` | None |
+| `useRender` | `ComponentProps<T, S>` | Single state |
+| `useRenderContainer` | `ContainerProps<T, CS, IS>` | Container + Item |
+
+These extend the element's native props, adding `render` and (for stateful hooks) function forms of `className`, `style`, and `children`.
 
-You might wonder why both exist—most libraries pick one or the other. They serve different purposes:
+## What the Hooks Handle
 
-- **`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.
+- **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
 
-They compose naturally—you can use both at once:
+## Ref Composition
+
+Component libraries often need internal ref access for focus management, measurements, or imperative APIs—while still letting consumers attach their own refs. The hooks handle this automatically.
+
+**Component author:**
 
 ```tsx
-<Button render={<a href="/path" />}>
-  {(state) => (state.isPressed ? 'Going...' : 'Go somewhere')}
-</Button>
-```
+import { useRef, useImperativeHandle } from 'react'
+import { useRender, ComponentProps } from '@diskette/use-render'
+
+type State = { open: boolean }
+type ComboboxProps = ComponentProps<'input', State>
+
+export interface ComboboxRef {
+  focus: () => void
+  clear: () => void
+}
 
-## API
+function Combobox({ ref, ...props }: ComboboxProps & { ref?: React.Ref<ComboboxRef> }) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const state: State = { open: false }
 
-### `useRender(tag, state, options)`
+  // Expose imperative API to consumers
+  useImperativeHandle(ref, () => ({
+    focus: () => inputRef.current?.focus(),
+    clear: () => {
+      if (inputRef.current) inputRef.current.value = ''
+    },
+  }))
 
-```ts
-function useRender<T extends ElementType, S>(
-  tag: T,
-  state: S,
-  options: UseRenderOptions<T, S>,
-): ReactNode
+  // Internal ref composes with any ref passed through props
+  return useRender('input', state, { props, ref: inputRef })
+}
 ```
 
-| 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                            |
+**Consumer:**
 
-### `ComponentProps<ElementType, State>`
+```tsx
+const inputRef = useRef<HTMLInputElement>(null)
+const comboboxRef = useRef<ComboboxRef>(null)
 
-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:
+// Direct element access
+<Combobox ref={inputRef} />
 
-```ts
-type ButtonProps = ComponentProps<'button', ButtonState>
+// Imperative handle access
+<Combobox ref={comboboxRef} />
+comboboxRef.current?.focus()
 ```
 
-## License
-
-[MIT](./LICENSE) License
+The `options.ref` parameter accepts a single ref or an array of refs. All refs—from `options.ref`, `baseProps.ref`, and consumer `props.ref`—are composed into a single callback ref that updates all sources and handles cleanup.

package/dist/index.d.ts

@@ -1,5 +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,2 +1,3 @@
 export { useRender } from "./use-render.js";
 export { useRenderContainer } from "./use-render-container.js";
+export { useRenderSlot } from "./use-render-slot.js";

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export type Style<State> = ((state: State, baseStyle?: CSSProperties) => CSSProp
 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 DataAttributes = Record<`data-${string}`, string | number | boolean | undefined>;
 export type BaseComponentProps<T extends ElementType> = Omit<ComponentPropsWithRef<T>, 'children' | 'className' | 'style'>;
 export type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
     children?: ReactNode | {

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.js

@@ -40,6 +40,7 @@ import { isFunction, isString, mergeProps, resolveClassName, resolveStyle, } fro
  * <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 ?? {});
@@ -50,10 +51,7 @@ export function useRenderContainer(tag, containerState, options = {}) {
     const resolvedClassName = resolveClassName(containerState, baseClassName, className);
     const resolvedStyle = resolveStyle(containerState, baseStyle, style);
     // Compose refs
-    const refs = Array.isArray(options.ref)
-        ? [ref, ...options.ref]
-        : [ref, options.ref];
-    const mergedRef = useComposedRef(refs);
+    const mergedRef = useComposedRef(ref, options.ref);
     // Build resolved container props (memoized for stable useCallback reference)
     const resolvedProps = useMemo(() => {
         const props = {

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.7.0",
+  "version": "0.9.0",
   "exports": "./dist/index.js",
   "files": [
     "dist"
@@ -21,18 +21,18 @@
     }
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.7",
-    "@types/react": "^19.2.6",
+    "@changesets/cli": "^2.29.8",
+    "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^5.1.1",
-    "@vitest/browser-playwright": "^4.0.13",
-    "oxlint": "^1.29.0",
-    "oxlint-tsgolint": "^0.8.1",
-    "prettier": "^3.6.2",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/browser-playwright": "^4.0.15",
+    "oxlint": "^1.32.0",
+    "oxlint-tsgolint": "^0.8.6",
+    "prettier": "^3.7.4",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.13",
+    "vitest": "^4.0.15",
     "vitest-browser-react": "^2.0.2"
   },
   "description": "_description_",