@diskette/use-render 0.6.1 → 0.7.0

package/dist/index.d.ts

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

package/dist/use-render-container.d.ts

@@ -0,0 +1,81 @@
+import type { CSSProperties, ElementType, JSX, ReactNode, Ref } from 'react';
+import type { BaseComponentProps, ClassName, ComponentRenderer, DataAttributes, Style } from './types.ts';
+type Children<S> = ((state: S) => ReactNode) | ReactNode;
+/**
+ * Props for the container element.
+ * - className/style resolve with ContainerState
+ * - children resolves with ItemState (per-item rendering)
+ * - render prop swaps the container element
+ */
+export type ContainerProps<T extends ElementType, ContainerState, ItemState = ContainerState> = BaseComponentProps<T> & {
+    className?: ClassName<ContainerState> | undefined;
+    style?: Style<ContainerState> | undefined;
+    children?: Children<ItemState> | undefined;
+    render?: ComponentRenderer<ContainerState> | JSX.Element;
+};
+/**
+ * Base props for the container with defaults.
+ * - className/style are static (no state resolution)
+ * - children can be a function of ItemState for default item rendering
+ */
+export type ContainerBaseProps<T extends ElementType, ItemState> = Omit<React.ComponentProps<T>, 'children' | 'className' | 'style'> & DataAttributes & {
+    className?: string | undefined;
+    style?: CSSProperties | undefined;
+    children?: Children<ItemState> | undefined;
+};
+export interface UseRenderContainerOptions<T extends ElementType, ContainerState, ItemState> {
+    props?: ContainerProps<T, ContainerState, ItemState> & DataAttributes;
+    baseProps?: ContainerBaseProps<T, ItemState>;
+    ref?: Ref<any> | (Ref<any> | undefined)[];
+}
+export interface UseRenderContainerResult<T extends ElementType, ItemState> {
+    /** Renders the container element with resolved props */
+    Container: (props: {
+        children?: ReactNode;
+    }) => ReactNode;
+    /** Resolves children with item-specific state */
+    renderItem: (itemState: ItemState) => ReactNode;
+    /** Direct access to resolved container props */
+    containerProps: React.ComponentProps<T>;
+}
+/**
+ * Hook for rendering container elements with item-level render control.
+ *
+ * Combines the prop resolution of useRender with the render control of useRenderProps.
+ * - Container: handles className/style resolution, ref composition, and render prop
+ * - renderItem: resolves children function with per-item state
+ *
+ * @example
+ * ```tsx
+ * type ContainerState = { locale: string }
+ * type ItemState = ContainerState & { date: Date; index: number }
+ *
+ * function DateList(props: ContainerProps<'div', ContainerState, ItemState>) {
+ *   const { Container, renderItem } = useRenderContainer('div', { locale: 'en' }, {
+ *     props,
+ *     baseProps: {
+ *       role: 'list',
+ *       children: (state) => <DateItem date={state.date} />,
+ *     },
+ *   })
+ *   const dates = generateDates()
+ *
+ *   return (
+ *     <Container>
+ *       {dates.map((date, index) => (
+ *         <ItemContext key={date.toString()}>
+ *           {renderItem({ date, index, locale: 'en' })}
+ *         </ItemContext>
+ *       ))}
+ *     </Container>
+ *   )
+ * }
+ *
+ * // Consumer usage:
+ * <DateList className={(state) => state.locale === 'en' && 'ltr'} />
+ * <DateList render={<section />} />
+ * <DateList>{(state) => <CustomDateItem date={state.date} />}</DateList>
+ * ```
+ */
+export declare function useRenderContainer<T extends ElementType, ContainerState, ItemState = ContainerState>(tag: T, containerState: ContainerState, options?: UseRenderContainerOptions<T, ContainerState, ItemState>): UseRenderContainerResult<T, ItemState>;
+export {};

package/dist/use-render-container.js

@@ -0,0 +1,100 @@
+import { cloneElement, createElement, isValidElement, useCallback, useMemo, } from 'react';
+import { useComposedRef } from "./use-composed-ref.js";
+import { isFunction, isString, mergeProps, resolveClassName, resolveStyle, } from "./utils.js";
+/**
+ * Hook for rendering container elements with item-level render control.
+ *
+ * Combines the prop resolution of useRender with the render control of useRenderProps.
+ * - Container: handles className/style resolution, ref composition, and render prop
+ * - renderItem: resolves children function with per-item state
+ *
+ * @example
+ * ```tsx
+ * type ContainerState = { locale: string }
+ * type ItemState = ContainerState & { date: Date; index: number }
+ *
+ * function DateList(props: ContainerProps<'div', ContainerState, ItemState>) {
+ *   const { Container, renderItem } = useRenderContainer('div', { locale: 'en' }, {
+ *     props,
+ *     baseProps: {
+ *       role: 'list',
+ *       children: (state) => <DateItem date={state.date} />,
+ *     },
+ *   })
+ *   const dates = generateDates()
+ *
+ *   return (
+ *     <Container>
+ *       {dates.map((date, index) => (
+ *         <ItemContext key={date.toString()}>
+ *           {renderItem({ date, index, locale: 'en' })}
+ *         </ItemContext>
+ *       ))}
+ *     </Container>
+ *   )
+ * }
+ *
+ * // Consumer usage:
+ * <DateList className={(state) => state.locale === 'en' && 'ltr'} />
+ * <DateList render={<section />} />
+ * <DateList>{(state) => <CustomDateItem date={state.date} />}</DateList>
+ * ```
+ */
+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 ?? {});
+    const props = (options.props ?? {});
+    const { className: baseClassName, style: baseStyle, children: baseChildren, ...base } = baseProps;
+    const { className, style, children, ref, render, ...rest } = props;
+    // Resolve container className/style with container state
+    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);
+    // Build resolved container props (memoized for stable useCallback reference)
+    const resolvedProps = useMemo(() => {
+        const props = {
+            ...mergeProps(base, rest),
+            ref: mergedRef,
+        };
+        if (isString(resolvedClassName)) {
+            props.className = resolvedClassName;
+        }
+        if (typeof resolvedStyle === 'object') {
+            props.style = resolvedStyle;
+        }
+        return props;
+    }, [base, rest, mergedRef, resolvedClassName, resolvedStyle]);
+    // Container component that handles render prop
+    const Container = useCallback(({ children: containerChildren }) => {
+        const propsWithChildren = {
+            ...resolvedProps,
+            children: containerChildren,
+        };
+        // For `<Component render={<section />} />`
+        if (isValidElement(render)) {
+            return cloneElement(render, propsWithChildren);
+        }
+        // For `<Component render={(props, state) => <section {...props} />} />`
+        if (isFunction(render)) {
+            return render(propsWithChildren, containerState);
+        }
+        return createElement(tag, propsWithChildren);
+    }, [resolvedProps, render, containerState, tag]);
+    // Render function for items - resolves children with item state
+    const renderItem = useCallback((itemState) => {
+        // Props children take precedence over base children
+        const childrenToRender = children !== undefined ? children : baseChildren;
+        return isFunction(childrenToRender)
+            ? childrenToRender(itemState)
+            : childrenToRender;
+    }, [children, baseChildren]);
+    return {
+        Container,
+        renderItem,
+        containerProps: resolvedProps,
+    };
+}

package/package.json

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

package/dist/use-render.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/use-render.test.jsx

@@ -1,241 +0,0 @@
-import React, { useState } from 'react';
-import { describe, expect, test, vi } from 'vitest';
-import { render } from 'vitest-browser-react';
-import {} from "./types.js";
-import { useRender } from "./use-render.js";
-function createBtn(defaultProps) {
-    return function Button(props) {
-        const [isActive, setIsActive] = useState(false);
-        const state = { isActive };
-        return useRender('button', state, {
-            props,
-            baseProps: {
-                onClick: () => setIsActive((cur) => !cur),
-                ...defaultProps,
-            },
-        });
-    };
-}
-describe('useRender', () => {
-    describe('className', () => {
-        test('renders with static string className', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button className="btn-primary">Click</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('btn-primary');
-        });
-        test('className function receives state', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button className={(state) => (state.isActive ? 'active' : 'inactive')}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('inactive');
-            await button.click();
-            await expect.element(button).toHaveClass('active');
-        });
-        test('className function receives baseClassName as second argument', async () => {
-            const Button = createBtn({ className: 'btn-default' });
-            const { getByRole } = await render(<Button className={(_state, baseClassName) => `custom ${baseClassName ?? ''}`}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('custom');
-            await expect.element(button).toHaveClass('btn-default');
-        });
-        test('merges props className with defaultProps className', async () => {
-            const Button = createBtn({ className: 'btn-base' });
-            const { getByRole } = await render(<Button className="btn-primary">Click</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('btn-base');
-            await expect.element(button).toHaveClass('btn-primary');
-        });
-    });
-    describe('style', () => {
-        test('renders with static style object', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button style={{ backgroundColor: 'red' }}>Click</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveStyle({ backgroundColor: 'red' });
-        });
-        test('style function receives state', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button style={(state) => ({
-                    backgroundColor: state.isActive ? 'green' : 'gray',
-                })}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveStyle({ backgroundColor: 'gray' });
-            await button.click();
-            await expect.element(button).toHaveStyle({ backgroundColor: 'green' });
-        });
-        test('style function receives baseStyle as second argument', async () => {
-            const Button = createBtn({ style: { padding: '10px' } });
-            const { getByRole } = await render(<Button style={(_state, baseStyle) => ({
-                    ...baseStyle,
-                    color: 'blue',
-                })}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect
-                .element(button)
-                .toHaveStyle({ padding: '10px', color: 'blue' });
-        });
-        test('merges props style with defaultProps style', async () => {
-            const Button = createBtn({
-                style: { padding: '10px', margin: '5px' },
-            });
-            const { getByRole } = await render(<Button style={{ padding: '20px', color: 'red' }}>Click</Button>);
-            const button = getByRole('button');
-            // Props style should override default where they overlap
-            await expect.element(button).toHaveStyle({
-                padding: '20px',
-                margin: '5px',
-                color: 'red',
-            });
-        });
-    });
-    describe('children', () => {
-        test('renders static children', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button>Static Text</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveTextContent('Static Text');
-        });
-        test('children function receives state', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button>{(state) => (state.isActive ? 'Active!' : 'Inactive')}</Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveTextContent('Inactive');
-            await button.click();
-            await expect.element(button).toHaveTextContent('Active!');
-        });
-        test('uses defaultProps children when no children provided', async () => {
-            const Button = createBtn({ children: 'Default Text' });
-            const { getByRole } = await render(<Button />);
-            const button = getByRole('button');
-            await expect.element(button).toHaveTextContent('Default Text');
-        });
-    });
-    describe('render', () => {
-        test('renders element from render prop instead of default tag', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button render={<a href="/path"/>}>Link</Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Link');
-            await expect.element(link).toHaveAttribute('href', '/path');
-        });
-        test('render function receives props and state', async () => {
-            const Button = createBtn();
-            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);
-                    }}/>)}>
-          Link
-        </Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Link');
-            await expect.element(link).toHaveAttribute('href', '/path');
-            await expect.element(link).toHaveClass('custom');
-            await expect.element(link).toHaveAttribute('data-active', 'false');
-            await link.click();
-            await expect.element(link).toHaveAttribute('data-active', 'true');
-        });
-        test('element render prop with children as function', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button render={<a href="/path"/>}>
-          {(state) => (state.isActive ? 'Active Link' : 'Inactive Link')}
-        </Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Inactive Link');
-            await expect.element(link).toHaveAttribute('href', '/path');
-        });
-        test('function render prop with children as function', async () => {
-            const Button = createBtn();
-            const { getByRole } = await render(<Button render={(props, state) => (<a {...props} href="/path" data-active={state.isActive} onClick={(e) => {
-                        e.preventDefault();
-                        props.onClick?.(e);
-                    }}/>)}>
-          {(state) => (state.isActive ? 'Active Link' : 'Inactive Link')}
-        </Button>);
-            const link = getByRole('link');
-            await expect.element(link).toHaveTextContent('Inactive Link');
-            await expect.element(link).toHaveAttribute('data-active', 'false');
-            await link.click();
-            await expect.element(link).toHaveTextContent('Active Link');
-            await expect.element(link).toHaveAttribute('data-active', 'true');
-        });
-    });
-    describe('event handler composition', () => {
-        test('composes event handlers - both run, user first then default', async () => {
-            const callOrder = [];
-            const defaultHandler = vi.fn(() => callOrder.push('default'));
-            const userHandler = vi.fn(() => callOrder.push('user'));
-            const Button = createBtn({ onMouseEnter: defaultHandler });
-            const { getByRole } = await render(<Button onMouseEnter={userHandler}>Click</Button>);
-            const button = getByRole('button');
-            await button.hover();
-            expect(defaultHandler).toHaveBeenCalledTimes(1);
-            expect(userHandler).toHaveBeenCalledTimes(1);
-            expect(callOrder).toEqual(['user', 'default']);
-        });
-        test('user handler return value is preserved', async () => {
-            const defaultHandler = vi.fn(() => 'default-result');
-            const userHandler = vi.fn(() => 'user-result');
-            let capturedResult;
-            function TestButton(props) {
-                const [isActive, setIsActive] = useState(false);
-                return useRender('button', { isActive }, {
-                    props,
-                    baseProps: {
-                        onClick: (_e) => {
-                            setIsActive((cur) => !cur);
-                            return defaultHandler();
-                        },
-                    },
-                });
-            }
-            const { getByRole } = await render(<TestButton onClick={() => {
-                    capturedResult = userHandler();
-                    return capturedResult;
-                }}>
-          Click
-        </TestButton>);
-            const button = getByRole('button');
-            await button.click();
-            expect(userHandler).toHaveBeenCalled();
-            expect(defaultHandler).toHaveBeenCalled();
-            expect(capturedResult).toBe('user-result');
-        });
-        test('only default handler runs when no user handler provided', async () => {
-            const defaultHandler = vi.fn();
-            const Button = createBtn({ onMouseEnter: defaultHandler });
-            const { getByRole } = await render(<Button>Click</Button>);
-            const button = getByRole('button');
-            await button.hover();
-            expect(defaultHandler).toHaveBeenCalledTimes(1);
-        });
-        test('only user handler runs when no default handler', async () => {
-            const userHandler = vi.fn();
-            const Button = createBtn();
-            const { getByRole } = await render(<Button onMouseEnter={userHandler}>Click</Button>);
-            const button = getByRole('button');
-            await button.hover();
-            expect(userHandler).toHaveBeenCalledTimes(1);
-        });
-        test('composed onClick still updates internal state', async () => {
-            const userHandler = vi.fn();
-            const Button = createBtn();
-            const { getByRole } = await render(<Button className={(state) => (state.isActive ? 'active' : 'inactive')} onClick={userHandler}>
-          Click
-        </Button>);
-            const button = getByRole('button');
-            await expect.element(button).toHaveClass('inactive');
-            await button.click();
-            await expect.element(button).toHaveClass('active');
-            expect(userHandler).toHaveBeenCalledTimes(1);
-        });
-    });
-});