@bento/use-props 0.1.1 → 0.2.0

package/README.md

@@ -32,7 +32,34 @@ function Component(args) {
 As seen from the example above, the `useProps` hook takes two
 arguments:
 
-The `useProps` hook returns an object with two properties:
+### Forward Refs
+
+The `useProps` hook also accepts an optional third parameter for forwarded refs. When provided, it merges the forwarded ref with any refs from props and slots:
+
+```javascript
+import { useProps } from '@bento/use-props';
+import { withSlots } from '@bento/slots';
+import React from 'react';
+
+const Button = withSlots(
+  'Button',
+  React.forwardRef(function ButtonComponent(args, forwardedRef) {
+    const { props, apply, ref } = useProps(args, {}, forwardedRef);
+
+    // ref contains the merged reference from forwardedRef, props.ref, and slots
+    return <button {...apply({}, ['ref'])} ref={ref}>{props.children}</button>;
+  })
+);
+```
+
+The merged `ref` combines:
+- The forwarded ref from the parent component
+- Any ref passed through props
+- Any ref supplied via slots
+
+All refs are properly merged using `mergeRefs` from `@react-aria/utils`, ensuring all refs are called/updated when the element is mounted.
+
+The `useProps` hook returns an object with three properties:
 
 ### props
 

package/README.mdx

@@ -42,7 +42,34 @@ arguments:
 
 <ArgTypes of={Stories.useProps} />
 
-The `useProps` hook returns an object with two properties:
+### Forward Refs
+
+The `useProps` hook also accepts an optional third parameter for forwarded refs. When provided, it merges the forwarded ref with any refs from props and slots:
+
+```javascript
+import { useProps } from '@bento/use-props';
+import { withSlots } from '@bento/slots';
+import React from 'react';
+
+const Button = withSlots(
+  'Button',
+  React.forwardRef(function ButtonComponent(args, forwardedRef) {
+    const { props, apply, ref } = useProps(args, {}, forwardedRef);
+
+    // ref contains the merged reference from forwardedRef, props.ref, and slots
+    return <button {...apply({}, ['ref'])} ref={ref}>{props.children}</button>;
+  })
+);
+```
+
+The merged `ref` combines:
+- The forwarded ref from the parent component
+- Any ref passed through props
+- Any ref supplied via slots
+
+All refs are properly merged using `mergeRefs` from `@react-aria/utils`, ensuring all refs are called/updated when the element is mounted.
+
+The `useProps` hook returns an object with three properties:
 
 <ArgTypes of={Stories.hook} />
 

package/dist/index.cjs

@@ -2,6 +2,7 @@
 
 var box = require('@bento/box');
 var internalProps = require('@bento/internal-props');
+var utils = require('@react-aria/utils');
 var react = require('react');
 
 // src/index.ts
@@ -20,41 +21,71 @@ function renderProp(name, args) {
   const { props, slots, original } = args;
   return execute(name, slots, args) || execute(name, props, args) || original;
 }
-function useProps(args, state = {}) {
+function mergeRefList(refs) {
+  const filtered = refs.filter((ref) => ref != null);
+  if (!filtered.length) return void 0;
+  if (filtered.length === 1) return filtered[0];
+  return utils.mergeRefs(...filtered);
+}
+function useProps(...rest) {
+  let forwardedRef;
+  let args;
+  let state;
+  if (Array.isArray(rest[0])) {
+    [args, forwardedRef] = rest[0];
+    state = rest[1];
+  } else {
+    [args, state, forwardedRef] = rest;
+  }
   const { slots } = react.useContext(box.Box);
   const [props, internal] = internalProps.useInternalProps(args);
   const { namespace, assigned } = slots;
   const dot = namespace.join(".");
   const slotted = assigned[dot] || {};
-  const propsy = { ...internal, ...props, ...slotted };
+  const ref = mergeRefList([
+    props?.ref,
+    slotted?.ref,
+    forwardedRef
+  ]);
+  const slotNoRef = { ...slotted };
+  const propsNoRef = { ...props };
+  delete slotNoRef.ref;
+  delete propsNoRef.ref;
+  const propsy = { ...internal, ...propsNoRef, ...slotNoRef };
   function apply(attributes, except) {
     const data = attributes || propsy;
     const returned = {};
     function reduce(memo, key) {
       if (except && except.includes(key)) return memo;
       memo[key] = renderProp(key, {
+        props: { ...props, ...internal },
         original: data[key],
         slots: slotted,
-        props: { ...props, ...internal },
         state
       });
       return memo;
     }
-    if (!attributes) return Object.keys(propsy).reduce(reduce, returned);
-    return Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));
+    let result;
+    if (!attributes) result = Object.keys(propsy).reduce(reduce, returned);
+    else result = Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));
+    if (except && except.includes("ref")) return result;
+    if (ref) result.ref = ref;
+    return result;
   }
   return {
     props: new Proxy(propsy, {
       get: function getter(_, name) {
+        if (name === "ref") return ref;
         return renderProp(name, {
           original: isRenderProp(name, props[name]) ? void 0 : props[name],
-          slots: slotted,
           props: { ...props, ...internal },
+          slots: slotted,
           state
         });
       }
     }),
-    apply
+    apply,
+    ref
   };
 }
 

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["useContext","Box","useInternalProps"],"mappings":"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","file":"index.cjs","sourcesContent":["import { Box, type BoxContext } from '@bento/box';\nimport { useInternalProps } from '@bento/internal-props';\nimport { AnyObject } from '@bento/types';\nimport { useContext } from 'react';\n\nexport interface RenderPropData {\n  /**\n   * If the component is assigning a default value to the given prop,\n   * the original value be a reference to the previous assigned value.\n   * @default The original assigned value\n   */\n  original?: unknown;\n\n  /** All the props that were passed to the component. @default {} */\n  props: AnyObject;\n\n  /** If slots are used to modify the component, this will contain a reference to the original slots object. @default {} */\n  slots: AnyObject;\n\n  /** The exposed state of the component. @default {} */\n  state: AnyObject;\n}\n\n/**\n * Checks if the given string is an event listener name. An event listener name\n * is defined as a string that starts with \"on\" followed by an uppercase letter.\n *\n * @param name - The string to check.\n * @returns `true` if the string is an event listener name, otherwise `false`.\n * @private\n */\nexport function isEventListener(name: string): boolean {\n  return /^on[A-Z]/.test(name);\n}\n\n/**\n * Determines if a given value is a render prop.\n *\n * A render prop is a function that is used to dynamically generate\n * UI elements. This function checks if the provided value is a function\n * and not an event listener.\n *\n * @param name - The name of the prop.\n * @param value - The value of the prop to check.\n * @returns `true` if the value is a render prop, otherwise `false`.\n */\nexport function isRenderProp(name: string, value: any): boolean {\n  return typeof value === 'function' && !isEventListener(name);\n}\n\n/**\n * Executes a function or returns a value from the given data object.\n *\n * @param name - The name of the property to execute or retrieve.\n * @param data - The data object containing the property.\n * @param args - The arguments to pass if the property is a function.\n * @returns The result of the function execution or the value of the property.\n * @private\n */\nexport function execute(name: string, data: AnyObject, args: RenderPropData): any {\n  const value = data[name];\n\n  if (isRenderProp(name, value)) return value(args);\n  return value;\n}\n\n/**\n * Retrieves a property value, potentially overridden by a slotted value.\n *\n * @param name - The name of the property to retrieve.\n * @param options.props - The original properties.\n * @param options.slots - The slotted values that can override the original properties.\n * @param options.state - The current state.\n * @param options.original - The original value of the property.\n * @returns The original property value or the overridden value if provided.\n */\nexport function renderProp(name: string, args: RenderPropData): any {\n  const { props, slots, original } = args;\n\n  return execute(name, slots, args) || execute(name, props, args) || original;\n}\n\nexport interface Returns {\n  /**\n   * Proxy object that have access to the original props, slotted values, and internal props. When\n   * accessing a property, it will first check the slotted values, then the original props, and finally\n   * the internal props. If the property is a render prop, it will execute the function with the provided\n   * arguments.\n   *\n   * @default { ...props, ...slots }\n   */\n  props: AnyObject;\n  /**\n   * Applies the given attributes as default values to the props. If no attributes are provided, it will\n   * use the props as default values. The resulting object will contain all the properties of the props,\n   * except for the ones specified in the `except` array. The values of the properties will be the result\n   * of executing the render prop function with the provided arguments.\n   *\n   * @default function(attr)\n   */\n  apply: (attributes?: object, except?: string[]) => object;\n}\n\n/**\n * Hook that merges props with slotted props and provides a proxy for accessing them.\n *\n * @param args - The initial props to use.\n * @param state - The state object to use.\n * @returns An object containing the proxy based props object and the apply function.\n * @throws {BentoError} If the hook is used outside of a @bento/slots component.\n *\n * @example\n * const { props, apply } = useProps({ foo: 'bar' });\n * if (props.a) doSomething()\n * return <a {...apply({ className: 'foo' }) }>{ props.children }</a>;\n */\nexport function useProps(args: AnyObject, state: object = {}): Returns {\n  const { slots } = useContext<BoxContext<AnyObject>>(Box);\n  const [props, internal] = useInternalProps(args);\n  const { namespace, assigned } = slots;\n  const dot = namespace.join('.');\n  const slotted = assigned[dot] || {};\n  const propsy = { ...internal, ...props, ...slotted };\n\n  /**\n   * Applies the given attributes to an object.\n   *\n   * @param attributes - The attributes to apply. If not provided, defaults to `propsy`.\n   * @param except - An array of keys to exclude from the resulting object.\n   * @returns The resulting object with applied attributes.\n   * @public\n   */\n  function apply(attributes?: object, except?: string[]): object {\n    const data = attributes || propsy;\n    const returned = {};\n\n    function reduce(memo: AnyObject, key: string) {\n      if (except && except.includes(key)) return memo;\n\n      memo[key] = renderProp(key, {\n        original: data[key],\n        slots: slotted,\n        props: { ...props, ...internal },\n        state\n      });\n\n      return memo;\n    }\n\n    if (!attributes) return Object.keys(propsy).reduce(reduce, returned);\n    return Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));\n  }\n\n  return {\n    props: new Proxy(propsy, {\n      get: function getter(_: object, name: string) {\n        return renderProp(name, {\n          original: isRenderProp(name, props[name]) ? undefined : props[name],\n          slots: slotted,\n          props: { ...props, ...internal },\n          state\n        });\n      }\n    }),\n    apply\n  };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["mergeRefs","useContext","Box","useInternalProps"],"mappings":"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","file":"index.cjs","sourcesContent":["import { Box, type BoxContext } from '@bento/box';\nimport { useInternalProps } from '@bento/internal-props';\nimport { AnyObject } from '@bento/types';\nimport { mergeRefs } from '@react-aria/utils';\nimport { useContext } from 'react';\nimport type { ForwardedRef, Ref } from 'react';\n\nexport interface RenderPropData {\n  /**\n   * If the component is assigning a default value to the given prop,\n   * the original value be a reference to the previous assigned value.\n   * @default The original assigned value\n   */\n  original?: unknown;\n\n  /** All the props that were passed to the component. @default {} */\n  props: AnyObject;\n\n  /** If slots are used to modify the component, this will contain a reference to the original slots object. @default {} */\n  slots: AnyObject;\n\n  /** The exposed state of the component. @default {} */\n  state: AnyObject;\n}\n\n/**\n * Checks if the given string is an event listener name. An event listener name\n * is defined as a string that starts with \"on\" followed by an uppercase letter.\n *\n * @param name - The string to check.\n * @returns `true` if the string is an event listener name, otherwise `false`.\n * @private\n */\nexport function isEventListener(name: string): boolean {\n  return /^on[A-Z]/.test(name);\n}\n\n/**\n * Determines if a given value is a render prop.\n *\n * A render prop is a function that is used to dynamically generate\n * UI elements. This function checks if the provided value is a function\n * and not an event listener.\n *\n * @param name - The name of the prop.\n * @param value - The value of the prop to check.\n * @returns `true` if the value is a render prop, otherwise `false`.\n */\nexport function isRenderProp(name: string, value: any): boolean {\n  return typeof value === 'function' && !isEventListener(name);\n}\n\n/**\n * Executes a function or returns a value from the given data object.\n *\n * @param name - The name of the property to execute or retrieve.\n * @param data - The data object containing the property.\n * @param args - The arguments to pass if the property is a function.\n * @returns The result of the function execution or the value of the property.\n * @private\n */\nexport function execute(name: string, data: AnyObject, args: RenderPropData): any {\n  const value = data[name];\n\n  if (isRenderProp(name, value)) return value(args);\n  return value;\n}\n\n/**\n * Retrieves a property value, potentially overridden by a slotted value.\n *\n * @param name - The name of the property to retrieve.\n * @param options.props - The original properties.\n * @param options.slots - The slotted values that can override the original properties.\n * @param options.state - The current state.\n * @param options.original - The original value of the property.\n * @returns The original property value or the overridden value if provided.\n */\nexport function renderProp(name: string, args: RenderPropData): any {\n  const { props, slots, original } = args;\n\n  return execute(name, slots, args) || execute(name, props, args) || original;\n}\n\n/**\n * Merges multiple refs into a single ref callback.\n *\n * @param refs - Array of refs to merge (can include undefined/null).\n * @returns A single merged ref, undefined if no refs provided.\n * @private\n */\nfunction mergeRefList(refs: Array<ForwardedRef<any> | Ref<any> | undefined>): Ref<any> | undefined {\n  const filtered = refs.filter((ref): ref is ForwardedRef<any> | Ref<any> => ref != null);\n\n  if (!filtered.length) return undefined;\n  if (filtered.length === 1) return filtered[0] as Ref<any>;\n\n  return mergeRefs(...(filtered as Array<Ref<any>>)) as Ref<any>;\n}\n\nexport interface Returns {\n  /**\n   * Proxy object that have access to the original props, slotted values, and internal props. When\n   * accessing a property, it will first check the slotted values, then the original props, and finally\n   * the internal props. If the property is a render prop, it will execute the function with the provided\n   * arguments.\n   *\n   * @default { ...props, ...slots }\n   */\n  props: AnyObject;\n  /**\n   * Applies the given attributes as default values to the props. If no attributes are provided, it will\n   * use the props as default values. The resulting object will contain all the properties of the props,\n   * except for the ones specified in the `except` array. The values of the properties will be the result\n   * of executing the render prop function with the provided arguments.\n   *\n   * @default function(attr)\n   */\n  apply: (attributes?: object, except?: string[]) => object;\n  /**\n   * The merged ref combining forwarded refs with any ref supplied via slots.\n   */\n  ref?: Ref<any>;\n}\n\n/**\n * Hook that merges props with slotted props and provides a proxy for accessing them.\n *\n * @param args - The initial props to use, or array when using rest parameters.\n * @param state - The state object to use.\n * @param forwardedRef - The ref forwarded to the component.\n * @returns An object containing the proxy based props object and the apply function.\n * @throws {BentoError} If the hook is used outside of a @bento/slots component.\n *\n * @example\n * const { props, apply, ref } = useProps({ foo: 'bar' }, {}, forwardedRef);\n * if (props.a) doSomething()\n * return <a {...apply({ className: 'foo' }, ['ref']) } ref={ref}>{ props.children }</a>;\n *\n * @example\n * // With rest parameters\n * function Component(...rest) {\n *   const { props, apply, ref } = useProps(rest);\n *   return <div {...apply()} />;\n * }\n */\nexport function useProps(...rest: any[]): Returns {\n  let forwardedRef: ForwardedRef<any> | undefined;\n  let args: AnyObject;\n  let state: object;\n\n  if (Array.isArray(rest[0])) {\n    [args, forwardedRef] = rest[0];\n    state = rest[1];\n  } else {\n    [args, state, forwardedRef] = rest;\n  }\n\n  const { slots } = useContext<BoxContext<AnyObject>>(Box);\n  const [props, internal] = useInternalProps(args);\n  const { namespace, assigned } = slots;\n  const dot = namespace.join('.');\n  const slotted = assigned[dot] || {};\n\n  const ref = mergeRefList([\n    (props as AnyObject)?.ref as ForwardedRef<any> | Ref<any> | undefined,\n    (slotted as AnyObject)?.ref as ForwardedRef<any> | Ref<any> | undefined,\n    forwardedRef\n  ]);\n\n  const slotNoRef = { ...slotted } as AnyObject;\n  const propsNoRef = { ...props } as AnyObject;\n\n  delete slotNoRef.ref;\n  delete propsNoRef.ref;\n\n  const propsy: AnyObject = { ...internal, ...propsNoRef, ...slotNoRef };\n\n  /**\n   * Applies the given attributes to an object.\n   *\n   * @param attributes - The attributes to apply. If not provided, defaults to `propsy`.\n   * @param except - An array of keys to exclude from the resulting object.\n   * @returns The resulting object with applied attributes.\n   * @public\n   */\n  function apply(attributes?: object, except?: string[]): object {\n    const data = (attributes || propsy) as AnyObject;\n    const returned: AnyObject = {};\n\n    function reduce(memo: AnyObject, key: string) {\n      if (except && except.includes(key)) return memo;\n\n      memo[key] = renderProp(key, {\n        props: { ...props, ...internal },\n        original: data[key],\n        slots: slotted,\n        state\n      });\n\n      return memo;\n    }\n\n    let result: AnyObject;\n\n    if (!attributes) result = Object.keys(propsy).reduce(reduce, returned);\n    else result = Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));\n\n    // Always include the merged ref unless specifically excluded\n    if (except && except.includes('ref')) return result;\n    if (ref) result.ref = ref;\n\n    return result;\n  }\n\n  return {\n    props: new Proxy(propsy, {\n      get: function getter(_: object, name: string) {\n        if (name === 'ref') return ref;\n\n        return renderProp(name, {\n          original: isRenderProp(name, props[name]) ? undefined : props[name],\n          props: { ...props, ...internal },\n          slots: slotted,\n          state\n        });\n      }\n    }),\n    apply,\n    ref\n  };\n}\n"]}

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { AnyObject } from '@bento/types';
+import { Ref } from 'react';
 
 interface RenderPropData {
     /**
@@ -75,20 +76,32 @@ interface Returns {
      * @default function(attr)
      */
     apply: (attributes?: object, except?: string[]) => object;
+    /**
+     * The merged ref combining forwarded refs with any ref supplied via slots.
+     */
+    ref?: Ref<any>;
 }
 /**
  * Hook that merges props with slotted props and provides a proxy for accessing them.
  *
- * @param args - The initial props to use.
+ * @param args - The initial props to use, or array when using rest parameters.
  * @param state - The state object to use.
+ * @param forwardedRef - The ref forwarded to the component.
  * @returns An object containing the proxy based props object and the apply function.
  * @throws {BentoError} If the hook is used outside of a @bento/slots component.
  *
  * @example
- * const { props, apply } = useProps({ foo: 'bar' });
+ * const { props, apply, ref } = useProps({ foo: 'bar' }, {}, forwardedRef);
  * if (props.a) doSomething()
- * return <a {...apply({ className: 'foo' }) }>{ props.children }</a>;
+ * return <a {...apply({ className: 'foo' }, ['ref']) } ref={ref}>{ props.children }</a>;
+ *
+ * @example
+ * // With rest parameters
+ * function Component(...rest) {
+ *   const { props, apply, ref } = useProps(rest);
+ *   return <div {...apply()} />;
+ * }
  */
-declare function useProps(args: AnyObject, state?: object): Returns;
+declare function useProps(...rest: any[]): Returns;
 
 export { type RenderPropData, type Returns, execute, isEventListener, isRenderProp, renderProp, useProps };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AnyObject } from '@bento/types';
+import { Ref } from 'react';
 
 interface RenderPropData {
     /**
@@ -75,20 +76,32 @@ interface Returns {
      * @default function(attr)
      */
     apply: (attributes?: object, except?: string[]) => object;
+    /**
+     * The merged ref combining forwarded refs with any ref supplied via slots.
+     */
+    ref?: Ref<any>;
 }
 /**
  * Hook that merges props with slotted props and provides a proxy for accessing them.
  *
- * @param args - The initial props to use.
+ * @param args - The initial props to use, or array when using rest parameters.
  * @param state - The state object to use.
+ * @param forwardedRef - The ref forwarded to the component.
  * @returns An object containing the proxy based props object and the apply function.
  * @throws {BentoError} If the hook is used outside of a @bento/slots component.
  *
  * @example
- * const { props, apply } = useProps({ foo: 'bar' });
+ * const { props, apply, ref } = useProps({ foo: 'bar' }, {}, forwardedRef);
  * if (props.a) doSomething()
- * return <a {...apply({ className: 'foo' }) }>{ props.children }</a>;
+ * return <a {...apply({ className: 'foo' }, ['ref']) } ref={ref}>{ props.children }</a>;
+ *
+ * @example
+ * // With rest parameters
+ * function Component(...rest) {
+ *   const { props, apply, ref } = useProps(rest);
+ *   return <div {...apply()} />;
+ * }
  */
-declare function useProps(args: AnyObject, state?: object): Returns;
+declare function useProps(...rest: any[]): Returns;
 
 export { type RenderPropData, type Returns, execute, isEventListener, isRenderProp, renderProp, useProps };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { Box } from '@bento/box';
 import { useInternalProps } from '@bento/internal-props';
+import { mergeRefs } from '@react-aria/utils';
 import { useContext } from 'react';
 
 // src/index.ts
@@ -18,41 +19,71 @@ function renderProp(name, args) {
   const { props, slots, original } = args;
   return execute(name, slots, args) || execute(name, props, args) || original;
 }
-function useProps(args, state = {}) {
+function mergeRefList(refs) {
+  const filtered = refs.filter((ref) => ref != null);
+  if (!filtered.length) return void 0;
+  if (filtered.length === 1) return filtered[0];
+  return mergeRefs(...filtered);
+}
+function useProps(...rest) {
+  let forwardedRef;
+  let args;
+  let state;
+  if (Array.isArray(rest[0])) {
+    [args, forwardedRef] = rest[0];
+    state = rest[1];
+  } else {
+    [args, state, forwardedRef] = rest;
+  }
   const { slots } = useContext(Box);
   const [props, internal] = useInternalProps(args);
   const { namespace, assigned } = slots;
   const dot = namespace.join(".");
   const slotted = assigned[dot] || {};
-  const propsy = { ...internal, ...props, ...slotted };
+  const ref = mergeRefList([
+    props?.ref,
+    slotted?.ref,
+    forwardedRef
+  ]);
+  const slotNoRef = { ...slotted };
+  const propsNoRef = { ...props };
+  delete slotNoRef.ref;
+  delete propsNoRef.ref;
+  const propsy = { ...internal, ...propsNoRef, ...slotNoRef };
   function apply(attributes, except) {
     const data = attributes || propsy;
     const returned = {};
     function reduce(memo, key) {
       if (except && except.includes(key)) return memo;
       memo[key] = renderProp(key, {
+        props: { ...props, ...internal },
         original: data[key],
         slots: slotted,
-        props: { ...props, ...internal },
         state
       });
       return memo;
     }
-    if (!attributes) return Object.keys(propsy).reduce(reduce, returned);
-    return Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));
+    let result;
+    if (!attributes) result = Object.keys(propsy).reduce(reduce, returned);
+    else result = Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));
+    if (except && except.includes("ref")) return result;
+    if (ref) result.ref = ref;
+    return result;
   }
   return {
     props: new Proxy(propsy, {
       get: function getter(_, name) {
+        if (name === "ref") return ref;
         return renderProp(name, {
           original: isRenderProp(name, props[name]) ? void 0 : props[name],
-          slots: slotted,
           props: { ...props, ...internal },
+          slots: slotted,
           state
         });
       }
     }),
-    apply
+    apply,
+    ref
   };
 }
 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { Box, type BoxContext } from '@bento/box';\nimport { useInternalProps } from '@bento/internal-props';\nimport { AnyObject } from '@bento/types';\nimport { useContext } from 'react';\n\nexport interface RenderPropData {\n  /**\n   * If the component is assigning a default value to the given prop,\n   * the original value be a reference to the previous assigned value.\n   * @default The original assigned value\n   */\n  original?: unknown;\n\n  /** All the props that were passed to the component. @default {} */\n  props: AnyObject;\n\n  /** If slots are used to modify the component, this will contain a reference to the original slots object. @default {} */\n  slots: AnyObject;\n\n  /** The exposed state of the component. @default {} */\n  state: AnyObject;\n}\n\n/**\n * Checks if the given string is an event listener name. An event listener name\n * is defined as a string that starts with \"on\" followed by an uppercase letter.\n *\n * @param name - The string to check.\n * @returns `true` if the string is an event listener name, otherwise `false`.\n * @private\n */\nexport function isEventListener(name: string): boolean {\n  return /^on[A-Z]/.test(name);\n}\n\n/**\n * Determines if a given value is a render prop.\n *\n * A render prop is a function that is used to dynamically generate\n * UI elements. This function checks if the provided value is a function\n * and not an event listener.\n *\n * @param name - The name of the prop.\n * @param value - The value of the prop to check.\n * @returns `true` if the value is a render prop, otherwise `false`.\n */\nexport function isRenderProp(name: string, value: any): boolean {\n  return typeof value === 'function' && !isEventListener(name);\n}\n\n/**\n * Executes a function or returns a value from the given data object.\n *\n * @param name - The name of the property to execute or retrieve.\n * @param data - The data object containing the property.\n * @param args - The arguments to pass if the property is a function.\n * @returns The result of the function execution or the value of the property.\n * @private\n */\nexport function execute(name: string, data: AnyObject, args: RenderPropData): any {\n  const value = data[name];\n\n  if (isRenderProp(name, value)) return value(args);\n  return value;\n}\n\n/**\n * Retrieves a property value, potentially overridden by a slotted value.\n *\n * @param name - The name of the property to retrieve.\n * @param options.props - The original properties.\n * @param options.slots - The slotted values that can override the original properties.\n * @param options.state - The current state.\n * @param options.original - The original value of the property.\n * @returns The original property value or the overridden value if provided.\n */\nexport function renderProp(name: string, args: RenderPropData): any {\n  const { props, slots, original } = args;\n\n  return execute(name, slots, args) || execute(name, props, args) || original;\n}\n\nexport interface Returns {\n  /**\n   * Proxy object that have access to the original props, slotted values, and internal props. When\n   * accessing a property, it will first check the slotted values, then the original props, and finally\n   * the internal props. If the property is a render prop, it will execute the function with the provided\n   * arguments.\n   *\n   * @default { ...props, ...slots }\n   */\n  props: AnyObject;\n  /**\n   * Applies the given attributes as default values to the props. If no attributes are provided, it will\n   * use the props as default values. The resulting object will contain all the properties of the props,\n   * except for the ones specified in the `except` array. The values of the properties will be the result\n   * of executing the render prop function with the provided arguments.\n   *\n   * @default function(attr)\n   */\n  apply: (attributes?: object, except?: string[]) => object;\n}\n\n/**\n * Hook that merges props with slotted props and provides a proxy for accessing them.\n *\n * @param args - The initial props to use.\n * @param state - The state object to use.\n * @returns An object containing the proxy based props object and the apply function.\n * @throws {BentoError} If the hook is used outside of a @bento/slots component.\n *\n * @example\n * const { props, apply } = useProps({ foo: 'bar' });\n * if (props.a) doSomething()\n * return <a {...apply({ className: 'foo' }) }>{ props.children }</a>;\n */\nexport function useProps(args: AnyObject, state: object = {}): Returns {\n  const { slots } = useContext<BoxContext<AnyObject>>(Box);\n  const [props, internal] = useInternalProps(args);\n  const { namespace, assigned } = slots;\n  const dot = namespace.join('.');\n  const slotted = assigned[dot] || {};\n  const propsy = { ...internal, ...props, ...slotted };\n\n  /**\n   * Applies the given attributes to an object.\n   *\n   * @param attributes - The attributes to apply. If not provided, defaults to `propsy`.\n   * @param except - An array of keys to exclude from the resulting object.\n   * @returns The resulting object with applied attributes.\n   * @public\n   */\n  function apply(attributes?: object, except?: string[]): object {\n    const data = attributes || propsy;\n    const returned = {};\n\n    function reduce(memo: AnyObject, key: string) {\n      if (except && except.includes(key)) return memo;\n\n      memo[key] = renderProp(key, {\n        original: data[key],\n        slots: slotted,\n        props: { ...props, ...internal },\n        state\n      });\n\n      return memo;\n    }\n\n    if (!attributes) return Object.keys(propsy).reduce(reduce, returned);\n    return Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));\n  }\n\n  return {\n    props: new Proxy(propsy, {\n      get: function getter(_: object, name: string) {\n        return renderProp(name, {\n          original: isRenderProp(name, props[name]) ? undefined : props[name],\n          slots: slotted,\n          props: { ...props, ...internal },\n          state\n        });\n      }\n    }),\n    apply\n  };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import { Box, type BoxContext } from '@bento/box';\nimport { useInternalProps } from '@bento/internal-props';\nimport { AnyObject } from '@bento/types';\nimport { mergeRefs } from '@react-aria/utils';\nimport { useContext } from 'react';\nimport type { ForwardedRef, Ref } from 'react';\n\nexport interface RenderPropData {\n  /**\n   * If the component is assigning a default value to the given prop,\n   * the original value be a reference to the previous assigned value.\n   * @default The original assigned value\n   */\n  original?: unknown;\n\n  /** All the props that were passed to the component. @default {} */\n  props: AnyObject;\n\n  /** If slots are used to modify the component, this will contain a reference to the original slots object. @default {} */\n  slots: AnyObject;\n\n  /** The exposed state of the component. @default {} */\n  state: AnyObject;\n}\n\n/**\n * Checks if the given string is an event listener name. An event listener name\n * is defined as a string that starts with \"on\" followed by an uppercase letter.\n *\n * @param name - The string to check.\n * @returns `true` if the string is an event listener name, otherwise `false`.\n * @private\n */\nexport function isEventListener(name: string): boolean {\n  return /^on[A-Z]/.test(name);\n}\n\n/**\n * Determines if a given value is a render prop.\n *\n * A render prop is a function that is used to dynamically generate\n * UI elements. This function checks if the provided value is a function\n * and not an event listener.\n *\n * @param name - The name of the prop.\n * @param value - The value of the prop to check.\n * @returns `true` if the value is a render prop, otherwise `false`.\n */\nexport function isRenderProp(name: string, value: any): boolean {\n  return typeof value === 'function' && !isEventListener(name);\n}\n\n/**\n * Executes a function or returns a value from the given data object.\n *\n * @param name - The name of the property to execute or retrieve.\n * @param data - The data object containing the property.\n * @param args - The arguments to pass if the property is a function.\n * @returns The result of the function execution or the value of the property.\n * @private\n */\nexport function execute(name: string, data: AnyObject, args: RenderPropData): any {\n  const value = data[name];\n\n  if (isRenderProp(name, value)) return value(args);\n  return value;\n}\n\n/**\n * Retrieves a property value, potentially overridden by a slotted value.\n *\n * @param name - The name of the property to retrieve.\n * @param options.props - The original properties.\n * @param options.slots - The slotted values that can override the original properties.\n * @param options.state - The current state.\n * @param options.original - The original value of the property.\n * @returns The original property value or the overridden value if provided.\n */\nexport function renderProp(name: string, args: RenderPropData): any {\n  const { props, slots, original } = args;\n\n  return execute(name, slots, args) || execute(name, props, args) || original;\n}\n\n/**\n * Merges multiple refs into a single ref callback.\n *\n * @param refs - Array of refs to merge (can include undefined/null).\n * @returns A single merged ref, undefined if no refs provided.\n * @private\n */\nfunction mergeRefList(refs: Array<ForwardedRef<any> | Ref<any> | undefined>): Ref<any> | undefined {\n  const filtered = refs.filter((ref): ref is ForwardedRef<any> | Ref<any> => ref != null);\n\n  if (!filtered.length) return undefined;\n  if (filtered.length === 1) return filtered[0] as Ref<any>;\n\n  return mergeRefs(...(filtered as Array<Ref<any>>)) as Ref<any>;\n}\n\nexport interface Returns {\n  /**\n   * Proxy object that have access to the original props, slotted values, and internal props. When\n   * accessing a property, it will first check the slotted values, then the original props, and finally\n   * the internal props. If the property is a render prop, it will execute the function with the provided\n   * arguments.\n   *\n   * @default { ...props, ...slots }\n   */\n  props: AnyObject;\n  /**\n   * Applies the given attributes as default values to the props. If no attributes are provided, it will\n   * use the props as default values. The resulting object will contain all the properties of the props,\n   * except for the ones specified in the `except` array. The values of the properties will be the result\n   * of executing the render prop function with the provided arguments.\n   *\n   * @default function(attr)\n   */\n  apply: (attributes?: object, except?: string[]) => object;\n  /**\n   * The merged ref combining forwarded refs with any ref supplied via slots.\n   */\n  ref?: Ref<any>;\n}\n\n/**\n * Hook that merges props with slotted props and provides a proxy for accessing them.\n *\n * @param args - The initial props to use, or array when using rest parameters.\n * @param state - The state object to use.\n * @param forwardedRef - The ref forwarded to the component.\n * @returns An object containing the proxy based props object and the apply function.\n * @throws {BentoError} If the hook is used outside of a @bento/slots component.\n *\n * @example\n * const { props, apply, ref } = useProps({ foo: 'bar' }, {}, forwardedRef);\n * if (props.a) doSomething()\n * return <a {...apply({ className: 'foo' }, ['ref']) } ref={ref}>{ props.children }</a>;\n *\n * @example\n * // With rest parameters\n * function Component(...rest) {\n *   const { props, apply, ref } = useProps(rest);\n *   return <div {...apply()} />;\n * }\n */\nexport function useProps(...rest: any[]): Returns {\n  let forwardedRef: ForwardedRef<any> | undefined;\n  let args: AnyObject;\n  let state: object;\n\n  if (Array.isArray(rest[0])) {\n    [args, forwardedRef] = rest[0];\n    state = rest[1];\n  } else {\n    [args, state, forwardedRef] = rest;\n  }\n\n  const { slots } = useContext<BoxContext<AnyObject>>(Box);\n  const [props, internal] = useInternalProps(args);\n  const { namespace, assigned } = slots;\n  const dot = namespace.join('.');\n  const slotted = assigned[dot] || {};\n\n  const ref = mergeRefList([\n    (props as AnyObject)?.ref as ForwardedRef<any> | Ref<any> | undefined,\n    (slotted as AnyObject)?.ref as ForwardedRef<any> | Ref<any> | undefined,\n    forwardedRef\n  ]);\n\n  const slotNoRef = { ...slotted } as AnyObject;\n  const propsNoRef = { ...props } as AnyObject;\n\n  delete slotNoRef.ref;\n  delete propsNoRef.ref;\n\n  const propsy: AnyObject = { ...internal, ...propsNoRef, ...slotNoRef };\n\n  /**\n   * Applies the given attributes to an object.\n   *\n   * @param attributes - The attributes to apply. If not provided, defaults to `propsy`.\n   * @param except - An array of keys to exclude from the resulting object.\n   * @returns The resulting object with applied attributes.\n   * @public\n   */\n  function apply(attributes?: object, except?: string[]): object {\n    const data = (attributes || propsy) as AnyObject;\n    const returned: AnyObject = {};\n\n    function reduce(memo: AnyObject, key: string) {\n      if (except && except.includes(key)) return memo;\n\n      memo[key] = renderProp(key, {\n        props: { ...props, ...internal },\n        original: data[key],\n        slots: slotted,\n        state\n      });\n\n      return memo;\n    }\n\n    let result: AnyObject;\n\n    if (!attributes) result = Object.keys(propsy).reduce(reduce, returned);\n    else result = Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));\n\n    // Always include the merged ref unless specifically excluded\n    if (except && except.includes('ref')) return result;\n    if (ref) result.ref = ref;\n\n    return result;\n  }\n\n  return {\n    props: new Proxy(propsy, {\n      get: function getter(_: object, name: string) {\n        if (name === 'ref') return ref;\n\n        return renderProp(name, {\n          original: isRenderProp(name, props[name]) ? undefined : props[name],\n          props: { ...props, ...internal },\n          slots: slotted,\n          state\n        });\n      }\n    }),\n    apply,\n    ref\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bento/use-props",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Context aware props transformation for Bento",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -41,8 +41,11 @@
     "package.json"
   ],
   "dependencies": {
-    "@bento/box": "^0.1.1",
+    "@bento/box": "^0.2.0",
     "@bento/internal-props": "^0.1.1",
+    "@react-aria/utils": "^3.30.0"
+  },
+  "devDependencies": {
     "@bento/types": "^0.1.0"
   },
   "peerDependencies": {

package/src/index.ts

@@ -1,7 +1,9 @@
 import { Box, type BoxContext } from '@bento/box';
 import { useInternalProps } from '@bento/internal-props';
 import { AnyObject } from '@bento/types';
+import { mergeRefs } from '@react-aria/utils';
 import { useContext } from 'react';
+import type { ForwardedRef, Ref } from 'react';
 
 export interface RenderPropData {
   /**
@@ -80,6 +82,22 @@ export function renderProp(name: string, args: RenderPropData): any {
   return execute(name, slots, args) || execute(name, props, args) || original;
 }
 
+/**
+ * Merges multiple refs into a single ref callback.
+ *
+ * @param refs - Array of refs to merge (can include undefined/null).
+ * @returns A single merged ref, undefined if no refs provided.
+ * @private
+ */
+function mergeRefList(refs: Array<ForwardedRef<any> | Ref<any> | undefined>): Ref<any> | undefined {
+  const filtered = refs.filter((ref): ref is ForwardedRef<any> | Ref<any> => ref != null);
+
+  if (!filtered.length) return undefined;
+  if (filtered.length === 1) return filtered[0] as Ref<any>;
+
+  return mergeRefs(...(filtered as Array<Ref<any>>)) as Ref<any>;
+}
+
 export interface Returns {
   /**
    * Proxy object that have access to the original props, slotted values, and internal props. When
@@ -99,28 +117,64 @@ export interface Returns {
    * @default function(attr)
    */
   apply: (attributes?: object, except?: string[]) => object;
+  /**
+   * The merged ref combining forwarded refs with any ref supplied via slots.
+   */
+  ref?: Ref<any>;
 }
 
 /**
  * Hook that merges props with slotted props and provides a proxy for accessing them.
  *
- * @param args - The initial props to use.
+ * @param args - The initial props to use, or array when using rest parameters.
  * @param state - The state object to use.
+ * @param forwardedRef - The ref forwarded to the component.
  * @returns An object containing the proxy based props object and the apply function.
  * @throws {BentoError} If the hook is used outside of a @bento/slots component.
  *
  * @example
- * const { props, apply } = useProps({ foo: 'bar' });
+ * const { props, apply, ref } = useProps({ foo: 'bar' }, {}, forwardedRef);
  * if (props.a) doSomething()
- * return <a {...apply({ className: 'foo' }) }>{ props.children }</a>;
+ * return <a {...apply({ className: 'foo' }, ['ref']) } ref={ref}>{ props.children }</a>;
+ *
+ * @example
+ * // With rest parameters
+ * function Component(...rest) {
+ *   const { props, apply, ref } = useProps(rest);
+ *   return <div {...apply()} />;
+ * }
  */
-export function useProps(args: AnyObject, state: object = {}): Returns {
+export function useProps(...rest: any[]): Returns {
+  let forwardedRef: ForwardedRef<any> | undefined;
+  let args: AnyObject;
+  let state: object;
+
+  if (Array.isArray(rest[0])) {
+    [args, forwardedRef] = rest[0];
+    state = rest[1];
+  } else {
+    [args, state, forwardedRef] = rest;
+  }
+
   const { slots } = useContext<BoxContext<AnyObject>>(Box);
   const [props, internal] = useInternalProps(args);
   const { namespace, assigned } = slots;
   const dot = namespace.join('.');
   const slotted = assigned[dot] || {};
-  const propsy = { ...internal, ...props, ...slotted };
+
+  const ref = mergeRefList([
+    (props as AnyObject)?.ref as ForwardedRef<any> | Ref<any> | undefined,
+    (slotted as AnyObject)?.ref as ForwardedRef<any> | Ref<any> | undefined,
+    forwardedRef
+  ]);
+
+  const slotNoRef = { ...slotted } as AnyObject;
+  const propsNoRef = { ...props } as AnyObject;
+
+  delete slotNoRef.ref;
+  delete propsNoRef.ref;
+
+  const propsy: AnyObject = { ...internal, ...propsNoRef, ...slotNoRef };
 
   /**
    * Applies the given attributes to an object.
@@ -131,37 +185,48 @@ export function useProps(args: AnyObject, state: object = {}): Returns {
    * @public
    */
   function apply(attributes?: object, except?: string[]): object {
-    const data = attributes || propsy;
-    const returned = {};
+    const data = (attributes || propsy) as AnyObject;
+    const returned: AnyObject = {};
 
     function reduce(memo: AnyObject, key: string) {
       if (except && except.includes(key)) return memo;
 
       memo[key] = renderProp(key, {
+        props: { ...props, ...internal },
         original: data[key],
         slots: slotted,
-        props: { ...props, ...internal },
         state
       });
 
       return memo;
     }
 
-    if (!attributes) return Object.keys(propsy).reduce(reduce, returned);
-    return Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));
+    let result: AnyObject;
+
+    if (!attributes) result = Object.keys(propsy).reduce(reduce, returned);
+    else result = Object.keys(propsy).reduce(reduce, Object.keys(attributes).reduce(reduce, returned));
+
+    // Always include the merged ref unless specifically excluded
+    if (except && except.includes('ref')) return result;
+    if (ref) result.ref = ref;
+
+    return result;
   }
 
   return {
     props: new Proxy(propsy, {
       get: function getter(_: object, name: string) {
+        if (name === 'ref') return ref;
+
         return renderProp(name, {
           original: isRenderProp(name, props[name]) ? undefined : props[name],
-          slots: slotted,
           props: { ...props, ...internal },
+          slots: slotted,
           state
         });
       }
     }),
-    apply
+    apply,
+    ref
   };
 }