@diskette/use-render 0.3.0 → 0.5.0

package/README.md

@@ -39,7 +39,7 @@ function Button(props: ButtonProps) {
   const state: ButtonState = { isPressed, isHovered }
 
   return useRender('button', state, {
-    defaultProps: {
+    baseProps: {
       className: 'btn',
       onMouseDown: () => setIsPressed(true),
       onMouseUp: () => setIsPressed(false),
@@ -69,7 +69,7 @@ function Button(props: ButtonProps) {
 
 ```tsx
 <Button
-  render={(state, props) => (
+  render={(props, state) => (
     <a {...props} href="/path" data-pressed={state.isPressed} />
   )}
 >
@@ -83,8 +83,8 @@ Pass a function to resolve className based on component state:
 
 ```tsx
 <Button
-  className={(state, defaultClassName) =>
-    `${defaultClassName} ${state.isPressed ? 'pressed' : ''}`
+  className={(state, baseClassName) =>
+    `${baseClassName} ${state.isPressed ? 'pressed' : ''}`
   }
 >
   Press me
@@ -141,17 +141,17 @@ function useRender<T extends ElementType, S>(
 
 ```ts
 interface UseRenderOptions<T extends ElementType, S> {
-  defaultProps?: React.ComponentProps<T>
+  baseProps?: React.ComponentProps<T>
   props?: ComponentProps<T, S>
   ref?: React.Ref<any> | (React.Ref<any> | undefined)[]
 }
 ```
 
-| Option         | Description                                                        |
-| -------------- | ------------------------------------------------------------------ |
-| `defaultProps` | Default props applied to the element                               |
-| `props`        | Consumer-provided props (typically forwarded from component props) |
-| `ref`          | Ref(s) to merge with the consumer's ref                            |
+| Option      | Description                                                        |
+| ----------- | ------------------------------------------------------------------ |
+| `baseProps` | Base props applied to the element                                  |
+| `props`     | Consumer-provided props (typically forwarded from component props) |
+| `ref`       | Ref(s) to merge with the consumer's ref                            |
 
 ### `ComponentProps<T, S>`
 
@@ -170,7 +170,7 @@ type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
 
 ```ts
 type ClassNameResolver<S> =
-  | ((state: S, defaultClassName?: string) => string | undefined)
+  | ((state: S, baseClassName?: string) => string | undefined)
   | string
   | undefined
 ```
@@ -179,17 +179,17 @@ type ClassNameResolver<S> =
 
 ```ts
 type StyleResolver<S> =
-  | ((state: S, defaultStyle?: CSSProperties) => CSSProperties | undefined)
+  | ((state: S, baseStyle?: CSSProperties) => CSSProperties | undefined)
   | CSSProperties
   | undefined
 ```
 
-### `Renderer<T, S>`
+### `Renderer<S>`
 
 ```ts
-type Renderer<T extends ElementType, S> = (
-  state: S,
+type Renderer<S> = (
   props: ComponentPropsWithRef<T>,
+  state: S,
 ) => ReactNode
 ```
 

package/dist/types.d.ts

@@ -1,8 +1,8 @@
 import type { ComponentPropsWithRef, CSSProperties, ElementType, ReactNode } from 'react';
-export type ClassNameResolver<State> = ((state: State, defaultClassName?: string) => string | undefined) | string | undefined;
-export type StyleResolver<State> = ((state: State, defaultStyle?: CSSProperties) => CSSProperties | undefined) | CSSProperties | undefined;
-export type Renderer<S> = (state: S, props: React.HTMLAttributes<any> & {
+export type ClassNameResolver<State> = ((state: State, baseClassName?: string) => string | undefined) | string | undefined;
+export type StyleResolver<State> = ((state: State, baseStyle?: CSSProperties) => CSSProperties | undefined) | CSSProperties | undefined;
+export type Renderer<S> = (props: React.HTMLAttributes<any> & {
     ref?: React.Ref<any> | undefined;
-}) => ReactNode;
+}, state: S) => ReactNode;
 export type DataAttributes = Record<`data-${string}`, string | number | boolean>;
 export type BaseComponentProps<T extends ElementType> = Omit<ComponentPropsWithRef<T>, 'children' | 'className' | 'style'>;

package/dist/use-render.d.ts

@@ -7,12 +7,28 @@ export type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
     render?: Renderer<S> | JSX.Element;
 };
 export interface UseRenderOptions<T extends ElementType, S> {
-    defaultProps?: React.ComponentProps<T> & DataAttributes;
+    baseProps?: React.ComponentProps<T> & DataAttributes;
     props?: ComponentProps<T, S> & DataAttributes;
     ref?: React.Ref<any> | (React.Ref<any> | undefined)[];
 }
 /**
- * Hook for enabling a render prop in custom components. Designed to be used by component libraries as an implementation detail
- * in providing a way to override a component's default rendered element.
+ * Hook for rendering elements with render prop support, prop merging, and state-driven className/style resolution.
+ *
+ * @example
+ * ```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 })
+ * }
+ *
+ * // Usage:
+ * <Button className={(state) => state.disabled && 'opacity-50'} />
+ * <Button render={<a href="#" />} />
+ * ```
  */
 export declare function useRender<T extends ElementType, S>(tag: T, state: S, options: UseRenderOptions<T, S>): ReactNode;

package/dist/use-render.js

@@ -2,24 +2,40 @@ import { cloneElement, createElement, isValidElement } from 'react';
 import { useComposedRef } from "./use-composed-ref.js";
 import { isFunction, isString, mergeProps, resolveClassName, resolveStyle, } from "./utils.js";
 /**
- * Hook for enabling a render prop in custom components. Designed to be used by component libraries as an implementation detail
- * in providing a way to override a component's default rendered element.
+ * Hook for rendering elements with render prop support, prop merging, and state-driven className/style resolution.
+ *
+ * @example
+ * ```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 })
+ * }
+ *
+ * // Usage:
+ * <Button className={(state) => state.disabled && 'opacity-50'} />
+ * <Button render={<a href="#" />} />
+ * ```
  */
 export function useRender(tag, state, options) {
     // Workarounds for getting the prop objects to be typed. But should still be ok as the properties we need is common to all elements
-    const defaultProps = options.defaultProps ?? {};
+    const baseProps = options.baseProps ?? {};
     const props = (options.props ?? {});
-    const { className: defaultClassName, style: defaultStyle, children: defaultChildren, ...defaults } = defaultProps;
+    const { className: baseClassName, style: baseStyle, children: baseChildren, ...base } = baseProps;
     const { className, style, children, ref, render, ...rest } = props ?? {};
-    const resolvedClassName = resolveClassName(defaultClassName, className, state);
-    const resolvedStyle = resolveStyle(defaultStyle, style, state);
+    const resolvedClassName = resolveClassName(baseClassName, className, state);
+    const resolvedStyle = resolveStyle(baseStyle, style, state);
     const refs = Array.isArray(options.ref)
         ? [ref, ...options.ref]
         : [ref, options.ref];
     const mergedRef = useComposedRef(refs);
     // Another workaround for getting component props typed
     const resolvedProps = {
-        ...mergeProps(defaults, rest),
+        ...mergeProps(base, rest),
         ref: mergedRef,
     };
     if (isString(resolvedClassName)) {
@@ -33,12 +49,12 @@ export function useRender(tag, state, options) {
     if (isValidElement(render)) {
         return cloneElement(render, resolvedProps, resolvedChildren);
     }
-    // For `<Component render={(state, props) => <a {...props} />)} />`
+    // For `<Component render={(props) => <a {...props} />)} />`
     if (isFunction(render)) {
-        return render(state, {
+        return render({
             ...resolvedProps,
             children: resolvedChildren,
-        });
+        }, state);
     }
-    return createElement(tag, resolvedProps, resolvedChildren ?? defaultChildren);
+    return createElement(tag, resolvedProps, resolvedChildren ?? baseChildren);
 }

package/dist/use-render.test.jsx

@@ -8,7 +8,7 @@ function createBtn(defaultProps) {
         const state = { isActive };
         return useRender('button', state, {
             props,
-            defaultProps: {
+            baseProps: {
                 onClick: () => setIsActive((cur) => !cur),
                 ...defaultProps,
             },
@@ -33,9 +33,9 @@ describe('useRender', () => {
             await button.click();
             await expect.element(button).toHaveClass('active');
         });
-        test('className function receives defaultClassName as second argument', async () => {
+        test('className function receives baseClassName as second argument', async () => {
             const Button = createBtn({ className: 'btn-default' });
-            const { getByRole } = await render(<Button className={(_state, defaultClassName) => `custom ${defaultClassName ?? ''}`}>
+            const { getByRole } = await render(<Button className={(_state, baseClassName) => `custom ${baseClassName ?? ''}`}>
           Click
         </Button>);
             const button = getByRole('button');
@@ -69,10 +69,10 @@ describe('useRender', () => {
             await button.click();
             await expect.element(button).toHaveStyle({ backgroundColor: 'green' });
         });
-        test('style function receives defaultStyle as second argument', async () => {
+        test('style function receives baseStyle as second argument', async () => {
             const Button = createBtn({ style: { padding: '10px' } });
-            const { getByRole } = await render(<Button style={(_state, defaultStyle) => ({
-                    ...defaultStyle,
+            const { getByRole } = await render(<Button style={(_state, baseStyle) => ({
+                    ...baseStyle,
                     color: 'blue',
                 })}>
           Click
@@ -126,9 +126,9 @@ describe('useRender', () => {
             await expect.element(link).toHaveTextContent('Link');
             await expect.element(link).toHaveAttribute('href', '/path');
         });
-        test('render function receives state and props', async () => {
+        test('render function receives props and state', async () => {
             const Button = createBtn();
-            const { getByRole } = await render(<Button className="custom" render={(state, props) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
+            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);
                     }}/>)}>
@@ -153,7 +153,7 @@ describe('useRender', () => {
         });
         test('function render prop with children as function', async () => {
             const Button = createBtn();
-            const { getByRole } = await render(<Button render={(state, props) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
+            const { getByRole } = await render(<Button render={(props, state) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
                         e.preventDefault();
                         props.onClick?.(e);
                     }}/>)}>
@@ -188,7 +188,7 @@ describe('useRender', () => {
                 const [isActive, setIsActive] = useState(false);
                 return useRender('button', { isActive }, {
                     props,
-                    defaultProps: {
+                    baseProps: {
                         onClick: (_e) => {
                             setIsActive((cur) => !cur);
                             return defaultHandler();

package/package.json

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