@diskette/use-render 0.9.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`.
@@ -155,7 +165,10 @@ export interface ComboboxRef {
   clear: () => void
 }
 
-function Combobox({ ref, ...props }: ComboboxProps & { ref?: React.Ref<ComboboxRef> }) {
+function Combobox({
+  ref,
+  ...props
+}: ComboboxProps & { ref?: React.Ref<ComboboxRef> }) {
   const inputRef = useRef<HTMLInputElement>(null)
   const state: State = { open: false }
 

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/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@diskette/use-render",
   "type": "module",
-  "version": "0.9.0",
-  "exports": "./dist/index.js",
+  "version": "0.10.0",
+  "exports": {
+    ".": "./dist/index.js",
+    "./fns": "./dist/fns/index.js"
+  },
   "files": [
     "dist"
   ],