use-state-with-ref 0.0.0-main.ab7b671

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 William Wong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# `use-state-with-ref`
+
+React `useState` with a readonly `RefObject`.
+
+## Background
+
+Components often detect changes of props to check if the component need to be re-rendered. If the function is changed, the component should be re-rendered. To optimize performance, unnecessary changes should be removed.
+
+For example, unless there is an intentional change, the return value of `useCallback` should be kept the same across the lifetime of the component.
+
+`useStateWithRef` call `useState` and appending a readonly `RefObject`. The `RefObject` can be used in `useCallback` to minimize function changes.
+
+## How to use
+
+### Before optimization
+
+```tsx
+const MyComponent = ({ onSubmit }) => {
+  const [value, setValue] = useState();
+
+  // This callback will be recreated every time <MyComponent> is rendered.
+  const handleInput = ({ currentTarget: { value } }) => setValue(value);
+
+  // This callback will be recreated every time <MyComponent> is rendered.
+  const handleSubmit = () => onSubmit.current(valueRef.current);
+
+  return (
+    // <form> will be re-rendered every time <MyComponent> is rendered.
+    <form onSubmit={handleSubmit}>
+      <input onInput={handleInput} type="text" value={value} />
+    </form>
+  );
+};
+```
+
+### Optimization without `useStateWithRef`
+
+```tsx
+const MyComponent = ({ onSubmit }) => {
+  const [value, setValue] = useState();
+  const onSubmitRef = useRefFrom(onSubmit);
+  const valueRef = useRef();
+
+  valueRef.current = value;
+
+  // This callback will never change across the lifetime of <MyComponent> because `setValue` never change.
+  const handleInput = useCallback(({ currentTarget: { value } }) => setValue(value), [setValue]);
+
+  // This callback will never change across the lifetime of <MyComponent> because `onSubmitRef` and `valueRef` never change.
+  const handleSubmit = useCallback(() => onSubmitRef.current(valueRef.current), [onSubmitRef, valueRef]);
+
+  return (
+    // <form> will never re-render across the lifetime of <MyComponent>.
+    <form onSubmit={handleSubmit}>
+      <input onInput={handleInput} type="text" value={value} />
+    </form>
+  );
+};
+```
+
+### Optimization with `useStateWithRef`
+
+```tsx
+const MyComponent = ({ onSubmit }) => {
+  const [value, setValue, valueRef] = useStateWithRef();
+  const onSubmitRef = useRefFrom(onSubmit);
+
+  // This callback will never change across the lifetime of <MyComponent> because `setValue` never change.
+  const handleInput = useCallback(({ currentTarget: { value } }) => setValue(value), [setValue]);
+
+  // This callback will never change across the lifetime of <MyComponent> because `onSubmitRef` and `valueRef` never change.
+  const handleSubmit = useCallback(() => onSubmitRef.current(valueRef.current), [onSubmitRef, valueRef]);
+
+  return (
+    // <form> will never re-render across the lifetime of <MyComponent>.
+    <form onSubmit={handleSubmit}>
+      <input onInput={handleInput} type="text" value={value} />
+    </form>
+  );
+};
+```
+
+## API
+
+```ts
+export default function useStateWithRef<S>(
+  initialState: S | (() => S)
+): [
+  S,
+  Dispatch<SetStateAction<S>>,
+  ReadonlyRefObject<S>
+];
+
+export default function useStateWithRef<S = undefined>(): [
+  S | undefined,
+  Dispatch<SetStateAction<S | undefined>>,
+  ReadonlyRefObject<S | undefined>
+];
+```
+
+## Behaviors
+
+### Why should I use `RefObject` to optimize performance?
+
+When a prop change, a component will need to be re-rendered. This propagation amplifies when passing unchanged props to a large component. Thus, [`memo()`](https://react.dev/reference/react/memo) (a.k.a. [pure component](https://react.dev/reference/react/PureComponent)) helps prevent rendering when no props changed.
+
+[Pure components](https://react.dev/learn/keeping-components-pure) are components which will only re-render when there is any props changed.
+
+Generally, when any `onXXX` callback prop is changed, in most cases, the component should not need to be re-rendered because the callback props may not cause a visual change. In other words, changing `onXXX` will re-render but there will be no visual change (a.k.a. a wasted render).
+
+As props are changed, `memo()` and `PureComponent` could not prevent the wasted render.
+
+Despite `arePropsEqual` and `shouldComponentUpdate` can be used to ignore `onXXX` changes, a bad implementation could easily cause UI issues. Also, some callback functions may have legitimate reasons to cause a re-render. For example, in Fluent UI, changing the `IRenderFunction` should re-render because rows of a `<DetailsList>` could be rendered differently. Thus, `arePropsEqual` and `shouldComponentUpdate` are not generally recommended to use unless in very limited case.
+
+The most effective way to prevent wasted render is to follow [React best practices on pure rendering logic](https://react.dev/learn/keeping-components-pure), make sure all props are immutable and only change them when there is a visual change.
+
+#### Seriously?
+
+Let's look at [`useSyncExternalStore()`](https://react.dev/reference/react/useSyncExternalStore). When the `subscribe()` callback is changed, the `useSyncExternalStore()` hook will re-subscribe. Callback functions should be properly memoized and only change when needed. Otherwise, in `useSyncExternalStore()` case, every re-render will resubscribe again.
+
+## Contributions
+
+Like us? [Star](https://github.com/compulim/use-state-with-ref/stargazers) us.
+
+Want to make it better? [File](https://github.com/compulim/use-state-with-ref/issues) us an issue.
+
+Don't like something you see? [Submit](https://github.com/compulim/use-state-with-ref/pulls) a pull request.

package/lib/commonjs/index.js

@@ -0,0 +1,15 @@
+"use strict";
+
+var _Object$defineProperty = require("@babel/runtime-corejs3/core-js-stable/object/define-property");
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+_Object$defineProperty(exports, "__esModule", {
+  value: true
+});
+_Object$defineProperty(exports, "useStateWithRef", {
+  enumerable: true,
+  get: function get() {
+    return _useStateWithRef.default;
+  }
+});
+var _useStateWithRef = _interopRequireDefault(require("./useStateWithRef"));
+//# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_useStateWithRef","_interopRequireDefault","require"],"sources":["../../src/index.ts"],"sourcesContent":["import useStateWithRef from './useStateWithRef';\n\nexport { useStateWithRef };\n"],"mappings":";;;;;;;;;;;;;AAAA,IAAAA,gBAAA,GAAAC,sBAAA,CAAAC,OAAA"}

package/lib/commonjs/useStateWithRef.js

@@ -0,0 +1,20 @@
+"use strict";
+
+var _Object$defineProperty = require("@babel/runtime-corejs3/core-js-stable/object/define-property");
+var _interopRequireDefault = require("@babel/runtime-corejs3/helpers/interopRequireDefault").default;
+_Object$defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = useStateWithRef;
+var _freeze = _interopRequireDefault(require("@babel/runtime-corejs3/core-js-stable/object/freeze"));
+var _slicedToArray2 = _interopRequireDefault(require("@babel/runtime-corejs3/helpers/slicedToArray"));
+var _react = require("react");
+var _useRefFrom = require("use-ref-from");
+function useStateWithRef(initialState) {
+  var _useState = (0, _react.useState)(initialState),
+    _useState2 = (0, _slicedToArray2.default)(_useState, 2),
+    value = _useState2[0],
+    setter = _useState2[1];
+  return (0, _freeze.default)([value, setter, (0, _useRefFrom.useRefFrom)(value)]);
+}
+//# sourceMappingURL=useStateWithRef.js.map

package/lib/commonjs/useStateWithRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStateWithRef.js","names":["_react","require","_useRefFrom","useStateWithRef","initialState","_useState","useState","_useState2","_slicedToArray2","default","value","setter","_freeze","useRefFrom"],"sources":["../../src/useStateWithRef.ts"],"sourcesContent":["import { type Dispatch, type SetStateAction, useState } from 'react';\nimport { useRefFrom } from 'use-ref-from';\n\ntype ReadonlyRefObject<S> = ReturnType<typeof useRefFrom<S>>;\n\nexport default function useStateWithRef<S>(\n  initialState: S | (() => S)\n): [S, Dispatch<SetStateAction<S>>, ReadonlyRefObject<S>];\n\nexport default function useStateWithRef<S = undefined>(): [\n  S | undefined,\n  Dispatch<SetStateAction<S | undefined>>,\n  ReadonlyRefObject<S | undefined>\n];\n\nexport default function useStateWithRef<S>(\n  initialState?: S | (() => S)\n): readonly [S | undefined, Dispatch<SetStateAction<S | undefined>>, ReadonlyRefObject<S | undefined>] {\n  const [value, setter] = useState<S | undefined>(initialState);\n\n  return Object.freeze([value, setter, useRefFrom(value)]);\n}\n"],"mappings":";;;;;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,WAAA,GAAAD,OAAA;AAce,SAASE,eAAeA,CACrCC,YAA4B,EACyE;EACrG,IAAAC,SAAA,GAAwB,IAAAC,eAAQ,EAAgBF,YAAY,CAAC;IAAAG,UAAA,OAAAC,eAAA,CAAAC,OAAA,EAAAJ,SAAA;IAAtDK,KAAK,GAAAH,UAAA;IAAEI,MAAM,GAAAJ,UAAA;EAEpB,OAAO,IAAAK,OAAA,CAAAH,OAAA,EAAc,CAACC,KAAK,EAAEC,MAAM,EAAE,IAAAE,sBAAU,EAACH,KAAK,CAAC,CAAC,CAAC;AAC1D"}

package/lib/commonjs-types/index.d.ts

@@ -0,0 +1,2 @@
+import useStateWithRef from './useStateWithRef';
+export { useStateWithRef };

package/lib/commonjs-types/useStateWithRef.d.ts

@@ -0,0 +1,10 @@
+import { type Dispatch, type SetStateAction } from 'react';
+import { useRefFrom } from 'use-ref-from';
+type ReadonlyRefObject<S> = ReturnType<typeof useRefFrom<S>>;
+export default function useStateWithRef<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>, ReadonlyRefObject<S>];
+export default function useStateWithRef<S = undefined>(): [
+    S | undefined,
+    Dispatch<SetStateAction<S | undefined>>,
+    ReadonlyRefObject<S | undefined>
+];
+export {};

package/lib/esmodules/index.js

@@ -0,0 +1,3 @@
+import useStateWithRef from './useStateWithRef';
+export { useStateWithRef };
+//# sourceMappingURL=index.js.map

package/lib/esmodules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["useStateWithRef"],"sources":["../../src/index.ts"],"sourcesContent":["import useStateWithRef from './useStateWithRef';\n\nexport { useStateWithRef };\n"],"mappings":"AAAA,OAAOA,eAAe,MAAM,mBAAmB;AAE/C,SAASA,eAAe"}

package/lib/esmodules/useStateWithRef.js

@@ -0,0 +1,12 @@
+import _slicedToArray from "@babel/runtime-corejs3/helpers/slicedToArray";
+import _Object$freeze from "@babel/runtime-corejs3/core-js-stable/object/freeze";
+import { useState } from 'react';
+import { useRefFrom } from 'use-ref-from';
+export default function useStateWithRef(initialState) {
+  var _useState = useState(initialState),
+    _useState2 = _slicedToArray(_useState, 2),
+    value = _useState2[0],
+    setter = _useState2[1];
+  return _Object$freeze([value, setter, useRefFrom(value)]);
+}
+//# sourceMappingURL=useStateWithRef.js.map

package/lib/esmodules/useStateWithRef.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useStateWithRef.js","names":["useState","useRefFrom","useStateWithRef","initialState","_useState","_useState2","_slicedToArray","value","setter","_Object$freeze"],"sources":["../../src/useStateWithRef.ts"],"sourcesContent":["import { type Dispatch, type SetStateAction, useState } from 'react';\nimport { useRefFrom } from 'use-ref-from';\n\ntype ReadonlyRefObject<S> = ReturnType<typeof useRefFrom<S>>;\n\nexport default function useStateWithRef<S>(\n  initialState: S | (() => S)\n): [S, Dispatch<SetStateAction<S>>, ReadonlyRefObject<S>];\n\nexport default function useStateWithRef<S = undefined>(): [\n  S | undefined,\n  Dispatch<SetStateAction<S | undefined>>,\n  ReadonlyRefObject<S | undefined>\n];\n\nexport default function useStateWithRef<S>(\n  initialState?: S | (() => S)\n): readonly [S | undefined, Dispatch<SetStateAction<S | undefined>>, ReadonlyRefObject<S | undefined>] {\n  const [value, setter] = useState<S | undefined>(initialState);\n\n  return Object.freeze([value, setter, useRefFrom(value)]);\n}\n"],"mappings":";;AAAA,SAA6CA,QAAQ,QAAQ,OAAO;AACpE,SAASC,UAAU,QAAQ,cAAc;AAczC,eAAe,SAASC,eAAeA,CACrCC,YAA4B,EACyE;EACrG,IAAAC,SAAA,GAAwBJ,QAAQ,CAAgBG,YAAY,CAAC;IAAAE,UAAA,GAAAC,cAAA,CAAAF,SAAA;IAAtDG,KAAK,GAAAF,UAAA;IAAEG,MAAM,GAAAH,UAAA;EAEpB,OAAOI,cAAA,CAAc,CAACF,KAAK,EAAEC,MAAM,EAAEP,UAAU,CAACM,KAAK,CAAC,CAAC,CAAC;AAC1D"}

package/lib/esmodules-types/index.d.ts

@@ -0,0 +1,2 @@
+import useStateWithRef from './useStateWithRef';
+export { useStateWithRef };

package/lib/esmodules-types/useStateWithRef.d.ts

@@ -0,0 +1,10 @@
+import { type Dispatch, type SetStateAction } from 'react';
+import { useRefFrom } from 'use-ref-from';
+type ReadonlyRefObject<S> = ReturnType<typeof useRefFrom<S>>;
+export default function useStateWithRef<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>, ReadonlyRefObject<S>];
+export default function useStateWithRef<S = undefined>(): [
+    S | undefined,
+    Dispatch<SetStateAction<S | undefined>>,
+    ReadonlyRefObject<S | undefined>
+];
+export {};

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "use-state-with-ref",
+  "version": "0.0.0-main.ab7b671",
+  "description": "React `useState` with a readonly `RefObject`.",
+  "files": [
+    "./lib/"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/esmodules-types/index.d.ts",
+        "default": "./lib/esmodules/index.js"
+      },
+      "require": {
+        "types": "./lib/commonjs-types/index.d.ts",
+        "default": "./lib/commonjs/index.js"
+      }
+    },
+    "./useStateWithRef": {
+      "import": {
+        "types": "./lib/esmodules-types/useStateWithRef.d.ts",
+        "default": "./lib/esmodules/useStateWithRef.js"
+      },
+      "require": {
+        "types": "./lib/commonjs-types/useStateWithRef.d.ts",
+        "default": "./lib/commonjs/useStateWithRef.js"
+      }
+    }
+  },
+  "main": "./lib/commonjs/index.js",
+  "typings": "./lib/commonjs-types/index.d.ts",
+  "scripts": {
+    "build": "npm run build:babel:commonjs && npm run build:babel:esmodules && npm run build:typescript:commonjs && npm run build:typescript:esmodules",
+    "build:babel:commonjs": "babel src --config-file ./babel.commonjs.config.json --extensions .ts,.tsx --out-dir ./lib/commonjs/",
+    "build:babel:esmodules": "babel src --config-file ./babel.esmodules.config.json --extensions .ts,.tsx --out-dir ./lib/esmodules/",
+    "build:typescript:commonjs": "tsc --project ./src/tsconfig.declaration.commonjs.json",
+    "build:typescript:esmodules": "tsc --project ./src/tsconfig.declaration.esmodules.json",
+    "bump": "npm run bump:prod && npm run bump:dev && npm run bump:auditfix && npm run bump:babel",
+    "bump:auditfix": "npm audit fix || exit 0",
+    "bump:babel": "npm run bump:babel:commonjs && npm run bump:babel:esmodules",
+    "bump:babel:commonjs": "cat babel.commonjs.config.json | jq --arg CORE_JS_VERSION `[ -f node_modules/@babel/runtime-corejs3/package.json ] && cat node_modules/@babel/runtime-corejs3/package.json | jq -r .version || cat ../../node_modules/@babel/runtime-corejs3/package.json | jq -r .version` '(.plugins[] | select(.[0] == \"@babel/plugin-transform-runtime\"))[1].version = $CORE_JS_VERSION' | prettier --parser json > babel.commonjs.config.json.tmp && mv babel.commonjs.config.json.tmp babel.commonjs.config.json",
+    "bump:babel:esmodules": "cat babel.esmodules.config.json | jq --arg CORE_JS_VERSION `[ -f node_modules/@babel/runtime-corejs3/package.json ] && cat node_modules/@babel/runtime-corejs3/package.json | jq -r .version || cat ../../node_modules/@babel/runtime-corejs3/package.json | jq -r .version` '(.plugins[] | select(.[0] == \"@babel/plugin-transform-runtime\"))[1].version = $CORE_JS_VERSION' | prettier --parser json > babel.esmodules.config.json.tmp && mv babel.esmodules.config.json.tmp babel.esmodules.config.json",
+    "bump:dev": "PACKAGES_TO_BUMP=$(cat package.json | jq -r '.localPeerDependencies // {} as $L | .devDependencies // {} | to_entries | map(select(.key as $K | $L | has($K) | not)) | map(.key + \"@latest\") | join(\" \")') && [ ! -z \"$PACKAGES_TO_BUMP\" ] && npm install $PACKAGES_TO_BUMP || true",
+    "bump:prod": "PACKAGES_TO_BUMP=$(cat package.json | jq -r '.localPeerDependencies // {} as $L | .dependencies // {} | to_entries | map(select(.key as $K | $L | has($K) | not)) | map(.key + \"@latest\") | join(\" \")') && [ ! -z \"$PACKAGES_TO_BUMP\" ] && npm install $PACKAGES_TO_BUMP || true",
+    "postscaffold": "npm run bump:babel",
+    "precommit": "npm run precommit:eslint && npm run precommit:typescript:production && npm run precommit:typescript:test",
+    "precommit:eslint": "eslint ./src/",
+    "precommit:typescript:production": "tsc --noEmit --project ./src/tsconfig.precommit.production.json",
+    "precommit:typescript:test": "tsc --noEmit --project ./src/tsconfig.precommit.test.json",
+    "prepack": "cp ../../CHANGELOG.md . && cp ../../LICENSE . && cp ../../README.md .",
+    "start": "esbuild --bundle --outfile=./public/main.js --servedir=./public --sourcemap ./scenarios/index.jsx",
+    "test": "jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/compulim/use-state-with-ref.git"
+  },
+  "keywords": [
+    "react",
+    "react-hook",
+    "react-hooks"
+  ],
+  "author": "William Wong (https://github.com/compulim)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/compulim/use-state-with-ref/issues"
+  },
+  "homepage": "https://github.com/compulim/use-state-with-ref#readme",
+  "peerDependencies": {
+    "react": ">=16.9.0"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.22.15",
+    "@babel/core": "^7.22.17",
+    "@babel/plugin-transform-runtime": "^7.22.15",
+    "@babel/preset-env": "^7.22.15",
+    "@babel/preset-react": "^7.22.15",
+    "@babel/preset-typescript": "^7.22.15",
+    "@testing-library/react": "^14.0.0",
+    "@tsconfig/recommended": "^1.0.2",
+    "@tsconfig/strictest": "^2.0.2",
+    "@types/jest": "^29.5.4",
+    "@types/react": "^18.2.21",
+    "jest": "^29.6.4",
+    "jest-environment-jsdom": "^29.6.4",
+    "react": "^18.2.0",
+    "react-test-renderer": "^18.2.0",
+    "typescript": "^5.2.2"
+  },
+  "dependencies": {
+    "@babel/runtime-corejs3": "^7.22.15",
+    "use-ref-from": "^0.0.2",
+    "use-state-with-ref": "^0.0.0-main.ab7b671"
+  }
+}