@diskette/use-render 0.2.0

package/README.md

@@ -0,0 +1,7 @@
+# useRender
+
+_description_
+
+## License
+
+[MIT](./LICENSE) License ©

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { useRender } from './use-render.ts';
+export type { ComponentProps, UseRenderOptions } from './use-render.ts';

package/dist/index.js

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

package/dist/types.d.ts

@@ -0,0 +1,6 @@
+import type { ComponentProps, CSSProperties, ElementType, ReactNode } from 'react';
+export type ClassNameResolver<State> = ((state: State, defaultClassName?: string | undefined) => string | undefined) | string | undefined;
+export type StyleResolver<State> = ((state: State, defaultStyle?: CSSProperties | undefined) => CSSProperties | undefined) | CSSProperties | undefined;
+export type Renderer<T extends ElementType, S> = (state: S, props: ComponentProps<T>) => ReactNode;
+export type DataAttributes = Record<`data-${string}`, string | number | boolean>;
+export type BaseComponentProps<T extends ElementType> = Omit<ComponentProps<T>, 'children' | 'className' | 'style'>;

package/dist/types.js

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

package/dist/use-merge-refs.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+type Ref<Instance> = Exclude<React.Ref<Instance>, React.RefObject<Instance>> | React.RefObject<Instance | null>;
+/**
+ * Merges an array of refs into a single memoized callback ref or `null`.
+ * @see https://floating-ui.com/docs/react-utils#usemergerefs
+ */
+export declare function useMergeRefs<Instance>(refs: Array<Ref<Instance> | undefined>): null | React.RefCallback<Instance>;
+export {};

package/dist/use-merge-refs.js

@@ -0,0 +1,45 @@
+import * as React from 'react';
+/**
+ * Merges an array of refs into a single memoized callback ref or `null`.
+ * @see https://floating-ui.com/docs/react-utils#usemergerefs
+ */
+export function useMergeRefs(refs) {
+    const cleanupRef = React.useRef(undefined);
+    const refEffect = React.useCallback((instance) => {
+        const cleanups = refs.map((ref) => {
+            if (ref == null) {
+                return;
+            }
+            if (typeof ref === 'function') {
+                const refCallback = ref;
+                const refCleanup = refCallback(instance);
+                return typeof refCleanup === 'function'
+                    ? refCleanup
+                    : () => {
+                        refCallback(null);
+                    };
+            }
+            ref.current = instance;
+            return () => {
+                ref.current = null;
+            };
+        });
+        return () => {
+            cleanups.forEach((refCleanup) => refCleanup?.());
+        };
+    }, refs);
+    return React.useMemo(() => {
+        if (refs.every((ref) => ref == null)) {
+            return null;
+        }
+        return (value) => {
+            if (cleanupRef.current) {
+                cleanupRef.current();
+                cleanupRef.current = undefined;
+            }
+            if (value != null) {
+                cleanupRef.current = refEffect(value);
+            }
+        };
+    }, refs);
+}

package/dist/use-render.d.ts

@@ -0,0 +1,19 @@
+import type { ElementType, JSX, ReactNode } from 'react';
+import type { BaseComponentProps, ClassNameResolver, DataAttributes, Renderer, StyleResolver } from './types.ts';
+export type ComponentProps<T extends ElementType, S> = BaseComponentProps<T> & {
+    children?: ((state: S) => ReactNode) | ReactNode;
+    className?: ClassNameResolver<S>;
+    style?: StyleResolver<S>;
+    render?: Renderer<T, S> | JSX.Element;
+};
+export interface UseRenderOptions<T extends ElementType, S> {
+    defaultProps?: React.ComponentProps<T> & DataAttributes;
+    props?: ComponentProps<T, S> & DataAttributes;
+    ref?: React.Ref<any> | (React.Ref<any> | undefined)[];
+    state: S;
+}
+/**
+ * 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.
+ */
+export declare function useRender<T extends ElementType, S>(tag: T, options: UseRenderOptions<T, S>): JSX.Element;

package/dist/use-render.js

@@ -0,0 +1,43 @@
+import { cloneElement, createElement, isValidElement, useMemo } from 'react';
+import { useMergeRefs } from "./use-merge-refs.js";
+import { isFunction, isUndefined, 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.
+ */
+export function useRender(tag, options) {
+    const { defaultProps, props = {}, ref: optionsRef, state } = options;
+    const defaultClassName = defaultProps?.className;
+    const defaultStyle = defaultProps?.style;
+    const defaultChildren = defaultProps?.children;
+    const { children, className: propsClassName, style: propsStyle, ref: propsRef, render, ...restProps } = defaultProps
+        ? { ...defaultProps, ...props }
+        : props;
+    const resolvedClassName = resolveClassName(defaultClassName, propsClassName, state);
+    const resolvedStyle = resolveStyle(defaultStyle, propsStyle, state);
+    const refs = useMemo(() => {
+        const refsArr = Array.isArray(optionsRef) ? optionsRef : [optionsRef];
+        if (propsRef) {
+            refsArr.push(propsRef);
+        }
+        return refsArr;
+    }, [optionsRef, propsRef]);
+    const mergedRef = useMergeRefs(refs);
+    const resolvedProps = {
+        ...restProps,
+        ...(!isUndefined(resolvedClassName) && { className: resolvedClassName }),
+        ...(!isUndefined(resolvedStyle) && { style: resolvedStyle }),
+        ...(mergedRef !== null && { ref: mergedRef }),
+    };
+    const resolvedChildren = isFunction(children) ? children(state) : children;
+    if (isValidElement(render)) {
+        return cloneElement(render, resolvedProps, resolvedChildren ?? defaultChildren);
+    }
+    if (isFunction(render)) {
+        return render(state, {
+            ...resolvedProps,
+            children: resolvedChildren,
+        });
+    }
+    return createElement(tag, resolvedProps, resolvedChildren ?? defaultChildren);
+}

package/dist/utils.d.ts

@@ -0,0 +1,18 @@
+import type { CSSProperties } from 'react';
+import type { ClassNameResolver, StyleResolver } from './types.ts';
+export declare const isFunction: (value: unknown) => value is Function;
+export declare const isUndefined: (value: unknown) => value is undefined;
+/**
+ * Resolves and merges className values from defaultProps and props.
+ * - Resolves function values with the provided state
+ * - Merges string values using clsx
+ * - Function props receive the resolved default value
+ */
+export declare function resolveClassName<State>(defaultClassName: ClassNameResolver<State>, propsClassName: ClassNameResolver<State>, state: State): string | undefined;
+/**
+ * Resolves and merges style values from defaultProps and props.
+ * - Resolves function values with the provided state
+ * - Merges object values using object spread
+ * - Function props receive the resolved default value
+ */
+export declare function resolveStyle<State>(defaultStyle: StyleResolver<State>, propsStyle: StyleResolver<State>, state: State): CSSProperties | undefined;

package/dist/utils.js

@@ -0,0 +1,49 @@
+import { clsx } from 'clsx';
+export const isFunction = (value) => typeof value === 'function';
+export const isUndefined = (value) => typeof value === 'undefined';
+/**
+ * Resolves and merges className values from defaultProps and props.
+ * - Resolves function values with the provided state
+ * - Merges string values using clsx
+ * - Function props receive the resolved default value
+ */
+export function resolveClassName(defaultClassName, propsClassName, state) {
+    const resolvedDefault = isFunction(defaultClassName)
+        ? defaultClassName(state)
+        : defaultClassName;
+    if (!isUndefined(propsClassName)) {
+        if (isFunction(propsClassName)) {
+            return propsClassName(state, resolvedDefault);
+        }
+        else {
+            return clsx(resolvedDefault, propsClassName);
+        }
+    }
+    else {
+        return resolvedDefault;
+    }
+}
+/**
+ * Resolves and merges style values from defaultProps and props.
+ * - Resolves function values with the provided state
+ * - Merges object values using object spread
+ * - Function props receive the resolved default value
+ */
+export function resolveStyle(defaultStyle, propsStyle, state) {
+    const resolvedDefault = isFunction(defaultStyle)
+        ? defaultStyle(state)
+        : defaultStyle;
+    if (!isUndefined(propsStyle)) {
+        if (isFunction(propsStyle)) {
+            return propsStyle(state, resolvedDefault);
+        }
+        else {
+            return resolvedDefault
+                ? { ...resolvedDefault, ...propsStyle }
+                : propsStyle;
+        }
+    }
+    else {
+        return resolvedDefault;
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@diskette/use-render",
+  "type": "module",
+  "version": "0.2.0",
+  "exports": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@types/react": "*",
+    "react": "^18.0 || ^19.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@types/react": "^19.2.6",
+    "@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",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.13",
+    "vitest-browser-react": "^2.0.2"
+  },
+  "description": "_description_",
+  "homepage": "https://github.com/diskettejs/use-render#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/diskettejs/use-render.git"
+  },
+  "keywords": [],
+  "prettier": {
+    "semi": false,
+    "singleQuote": true
+  },
+  "license": "MIT",
+  "dependencies": {
+    "clsx": "^2.1.1"
+  },
+  "scripts": {
+    "dev": "tsc --watch -p tsconfig.build.json",
+    "build": "rm -rf && tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc",
+    "lint": "oxlint --type-aware src",
+    "release": "changeset publish && git push --follow-tags"
+  }
+}