@diskette/use-render 0.7.0 → 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,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/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.8.0",
   "exports": "./dist/index.js",
   "files": [
     "dist"