@bento/use-props 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,125 @@
+# Props Management
+
+The `@bento/use-props` package provides a hook that unifies the component
+and slot based props into a single interface. Both the component and slot-based
+props can be specified as a `renderProp`. A `renderProp` is a function that
+returns the value that should be applied as props to the component.
+
+## Installation
+
+```shell
+npm install --save @bento/use-props
+```
+
+## useProps
+
+The package exposes a `useProps` hook that can be used to apply the
+props to the component. The hook is designed to be used in conjunction
+with the `@bento/slots` package as it allows the `slots` props that are
+introduced on the component to override the props that are specified on the
+component.
+
+```javascript
+import { useProps } from '@bento/use-props';
+import { useState } from 'react';
+
+function Component(args) {
+  const [value, setValue] = useState(0);
+  const { props, apply } = useProps(args, { value });
+}
+```
+
+As seen from the example above, the `useProps` hook takes two
+arguments:
+
+The `useProps` hook returns an object with two properties:
+
+### props
+
+The `props` property is a `props`-like object - specifically a `Proxy` instance. It
+provides the familiar `props` interface for retrieving component props. When props
+are modified by slots to add or override values, this Proxy automatically returns
+the correct merged value. The Proxy seamlessly handles both component props and
+slot-based props.
+
+When the prop that you're trying to access is specified as a `renderProp`, the
+`Proxy` will automatically call the function and return the value returned by
+the function. It's designed to do all the work for you so you can focus on
+writing your components.
+
+Just like normal `props`, you can also use this instance to spread the props
+on your components:
+
+```javascript
+import { useProps } from '@bento/use-props';
+import { withSlots } from '@bento/slots';
+import { useState } from 'react';
+
+const Anchor = withSlots('Anchor', function AnchorComponent(args) {
+  const [value, setValue] = useState(0);
+  const { props, apply } = useProps(args, { value });
+
+  return <a {...props} />;
+})
+```
+
+The primary use case for the `props` item is to interact with properties that
+do not have a default value assigned to them or when you need to spread unknown
+props to your component. When you interact with a prop that is set as renderProp
+it will automatically call the function and return the value that is returned.
+Given that no default value is applied, this renderProp will not be called
+with the `original` value assigned.
+
+```javascript
+import { useProps } from '@bento/use-props';
+import { withSlots } from '@bento/slots';
+
+const Anchor = withSlots('Anchor', function AnchorComponent(args) {
+  const { props, apply } = useProps(args);
+  const { design, ...rest } = props;
+
+  const className = design === 'foo' ? 'foo' : 'bar';
+  return <a {...props} {...apply({ className })} />;
+}
+
+// Illustrative purposes only, useCallback is required in a real application
+<Anchor design={function renderProp({ original, state }) {
+  console.log(original);  // undefined - Design prop was only used to lookup values
+  console.log(state);     // {} - No state was specified in the useProps
+
+  return 'foo';
+}} />
+```
+
+### apply
+
+The `apply` function is used to apply props to your component. It takes an
+object of props and returns a new object with all the props applied, taking into
+account any render props and slot overrides.
+
+The function accepts an optional second parameter - an array of prop names that
+should be omitted from being applied to the component. This is useful when you
+want to prevent certain props from being passed down, such as props used only
+for internal logic or props that shouldn't be spread onto the underlying
+DOM element.
+
+```javascript
+// Apply all props
+const appliedProps = apply({ className: 'my-class', onClick: handleClick });
+
+// Apply props while omitting specific ones
+const appliedProps = apply({ className: 'my-class', onClick: handleClick }, ['onClick']);
+```
+
+The `apply` function ensures that all props are properly handled, including:
+- Regular props
+- Render props (functions that return prop values)
+- Props that might be overridden by slots
+- Props that need to be merged with existing values
+
+This makes it the recommended way to apply any props to your components, as it
+handles all the necessary prop management internally.
+
+<Source language='tsx' code={ SourceBasic } />
+
+<Source language='tsx' code={ SourceNestedSlots } />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bento/use-props",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Context aware props transformation for Bento",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -10,6 +10,7 @@
     "dev": "tsup-node --watch",
     "lint": "biome lint && tsc --noEmit",
     "posttest": "npm run lint",
+    "prepublishOnly": "node ../../scripts/compile-readme.ts",
     "pretest": "npm run build",
     "test": "vitest --run",
     "test:watch": "vitest"
@@ -40,8 +41,8 @@
     "package.json"
   ],
   "dependencies": {
-    "@bento/box": "^0.1.0",
-    "@bento/internal-props": "^0.1.0",
+    "@bento/box": "^0.1.1",
+    "@bento/internal-props": "^0.1.1",
     "@bento/types": "^0.1.0"
   },
   "peerDependencies": {