@diskette/use-render 0.8.0 → 0.10.0

package/README.md

@@ -8,11 +8,35 @@ pnpm add @diskette/use-render
 
 ## 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:
+When building component libraries, you often need to let consumers customize rendering to:
+
+- swap the underlying element
+- access internal state for styling
+- 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
 
+## `useRender` — Stateful Components
+
+For components that expose internal state to consumers. The state flows through `className`, `style`, `children`, and `render` as callback parameters.
+
+**Component author:**
+
+```tsx
+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 })
+}
+```
+
 ## `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.
@@ -39,24 +63,6 @@ function Card(props: CardProps) {
 
 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
-
-For components that expose internal state to consumers. The state flows through `className`, `style`, `children`, and `render` as callback parameters.
-
-**Component author:**
-
-```tsx
-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 })
-}
-```
-
 **Consumer:**
 
 ```tsx
@@ -101,7 +107,11 @@ function List({ items, ...props }: ListProps & { items: string[] }) {
     { 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>
+  return (
+    <Container>
+      {items.map((v, i) => renderItem({ index: i, value: v }))}
+    </Container>
+  )
 }
 ```
 
@@ -122,10 +132,10 @@ function List({ items, ...props }: ListProps & { items: string[] }) {
 
 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 |
+| 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`.
@@ -136,3 +146,57 @@ These extend the element's native props, adding `render` and (for stateful hooks
 - **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
+
+## 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
+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
+}
+
+function Combobox({
+  ref,
+  ...props
+}: ComboboxProps & { ref?: React.Ref<ComboboxRef> }) {
+  const inputRef = useRef<HTMLInputElement>(null)
+  const state: State = { open: false }
+
+  // Expose imperative API to consumers
+  useImperativeHandle(ref, () => ({
+    focus: () => inputRef.current?.focus(),
+    clear: () => {
+      if (inputRef.current) inputRef.current.value = ''
+    },
+  }))
+
+  // Internal ref composes with any ref passed through props
+  return useRender('input', state, { props, ref: inputRef })
+}
+```
+
+**Consumer:**
+
+```tsx
+const inputRef = useRef<HTMLInputElement>(null)
+const comboboxRef = useRef<ComboboxRef>(null)
+
+// Direct element access
+<Combobox ref={inputRef} />
+
+// Imperative handle access
+<Combobox ref={comboboxRef} />
+comboboxRef.current?.focus()
+```
+
+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/fns/index.d.ts

@@ -0,0 +1,2 @@
+export { renderSlot } from './render-slot.ts';
+export type { RenderSlotOptions, SlotProps, SlotRenderer, } from './render-slot.ts';

package/dist/fns/index.js

@@ -0,0 +1 @@
+export { renderSlot } from "./render-slot.js";

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

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

package/dist/fns/render-slot.js

@@ -0,0 +1,52 @@
+import { cloneElement, createElement, isValidElement } from 'react';
+import { cx, isFunction, isString, mergeProps } from "../utils.js";
+/**
+ * Pure function for rendering slot elements with render prop support and prop merging.
+ * RSC-compatible version of useRenderSlot without ref handling.
+ *
+ * @example
+ * ```tsx
+ * import { renderSlot, SlotProps } from '@diskette/use-render/fns'
+ *
+ * type CardProps = SlotProps<'div'>
+ *
+ * function Card(props: CardProps) {
+ *   return renderSlot('div', {
+ *     props,
+ *     baseProps: { className: 'card' },
+ *   })
+ * }
+ *
+ * // Usage:
+ * <Card className="card-primary" />
+ * <Card render={<section />} />
+ * <Card render={(props) => <article {...props} />} />
+ * ```
+ */
+export function renderSlot(tag, options = {}) {
+    const baseProps = (options.baseProps ?? {});
+    const props = (options.props ?? {});
+    const { className: baseClassName, style: baseStyle, children: baseChildren, ...base } = baseProps;
+    const { className, style, children, render, ...rest } = props;
+    const resolvedClassName = cx(baseClassName, className);
+    const resolvedStyle = baseStyle || style ? { ...baseStyle, ...style } : undefined;
+    const resolvedProps = {
+        ...mergeProps(base, rest),
+    };
+    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/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/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@diskette/use-render",
   "type": "module",
-  "version": "0.8.0",
-  "exports": "./dist/index.js",
+  "version": "0.10.0",
+  "exports": {
+    ".": "./dist/index.js",
+    "./fns": "./dist/fns/index.js"
+  },
   "files": [
     "dist"
   ],
@@ -21,18 +24,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_",