@weasel-js/react 1.8.1 → 1.9.0

package/README.md

@@ -2,7 +2,8 @@
 
 Generic React hooks the weasel packages share: `useLatest`, a ref holding the
 value of the last committed render, and `useStableByContent`, which keeps one
-identity for a value rebuilt equal every render. No weasel domain in it.
+identity for a value rebuilt equal every render; and `assignRef`, which writes
+a value into a ref prop of either shape. No weasel domain in it.
 
 Part of [weasel](https://github.com/orochi235/weasel), a domain-agnostic 2D
 scene-graph canvas kit for React. See the

package/dist/index.d.ts

@@ -1,3 +1,14 @@
+import { Ref } from 'react';
+
+/**
+ * Write `value` into a ref a caller passed in, whichever shape it has: call a
+ * callback ref, set an object ref's `current`, ignore `null` or `undefined`.
+ *
+ * For a component that keeps the element (or handle) for itself and also
+ * forwards it to a ref prop — call this from the component's own callback ref.
+ */
+declare function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void;
+
 /**
  * A ref holding the `value` of the last **committed** render, for event
  * handlers, frame loops and other code that runs outside render and must not
@@ -30,4 +41,4 @@ declare function useStableByContent<T>(value: T, same: (a: T, b: T) => boolean):
 /** Same length, and the same element at every index. */
 declare function sameList<T>(a: readonly T[], b: readonly T[]): boolean;
 
-export { sameList, useLatest, useStableByContent };
+export { assignRef, sameList, useLatest, useStableByContent };

package/dist/index.js

@@ -1,6 +1,10 @@
 import { useRef, useInsertionEffect } from 'react';
 
-// src/useLatest.ts
+// src/assignRef.ts
+function assignRef(ref, value) {
+  if (typeof ref === "function") ref(value);
+  else if (ref) ref.current = value;
+}
 function useLatest(value) {
   const ref = useRef(value);
   useInsertionEffect(() => {
@@ -20,6 +24,6 @@ function sameList(a, b) {
   return a.length === b.length && a.every((t, i) => t === b[i]);
 }
 
-export { sameList, useLatest, useStableByContent };
+export { assignRef, sameList, useLatest, useStableByContent };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/useLatest.ts","../src/useStableByContent.ts"],"names":["useRef","useInsertionEffect"],"mappings":";;;AAoBO,SAAS,UAAa,KAAA,EAAmC;AAC9D,EAAA,MAAM,GAAA,GAAM,OAAO,KAAK,CAAA;AACxB,EAAA,kBAAA,CAAmB,MAAM;AACvB,IAAA,GAAA,CAAI,OAAA,GAAU,KAAA;AAAA,EAChB,CAAC,CAAA;AACD,EAAA,OAAO,GAAA;AACT;AClBO,SAAS,kBAAA,CAAsB,OAAU,IAAA,EAAkC;AAChF,EAAA,MAAM,IAAA,GAAOA,OAAO,KAAK,CAAA;AACzB,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,KAAY,KAAA,IAAS,IAAA,CAAK,KAAK,OAAA,EAAS,KAAK,CAAA,GAAI,IAAA,CAAK,OAAA,GAAU,KAAA;AACjF,EAAAC,mBAAmB,MAAM;AACvB,IAAA,IAAA,CAAK,OAAA,GAAU,GAAA;AAAA,EACjB,CAAC,CAAA;AACD,EAAA,OAAO,GAAA;AACT;AAGO,SAAS,QAAA,CAAY,GAAiB,CAAA,EAA0B;AACrE,EAAA,OAAO,CAAA,CAAE,MAAA,KAAW,CAAA,CAAE,MAAA,IAAU,CAAA,CAAE,KAAA,CAAM,CAAC,CAAA,EAAG,CAAA,KAAM,CAAA,KAAM,CAAA,CAAE,CAAC,CAAC,CAAA;AAC9D","file":"index.js","sourcesContent":["import { useInsertionEffect, useRef } from 'react';\n\n/**\n * A ref holding the `value` of the last **committed** render, for event\n * handlers, frame loops and other code that runs outside render and must not\n * re-subscribe every time `value` changes.\n *\n * Writing `ref.current = value` in a render body is not the same thing: React\n * may start a render and throw it away (a transition that suspends, a render\n * interrupted by a more urgent update), and the value that render computed\n * would stay behind for the next event to read. This writes from\n * `useInsertionEffect`, so only a render that commits ever lands, and it lands\n * before any layout effect in that commit runs — a sibling's or a child's\n * `useLayoutEffect`, or a synchronous paint one of them triggers, already sees\n * it.\n *\n * Don't read `.current` during render expecting this render's value: until the\n * commit it holds the previous committed one (on mount, this first `value`).\n * Render code should use `value` itself.\n */\nexport function useLatest<T>(value: T): { readonly current: T } {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n","import { useInsertionEffect, useRef } from 'react';\n\n/**\n * `value`, or the one the last committed render returned when `same` says the\n * two are equal — so a caller rebuilding an equivalent object every render\n * hands its readers one identity. Compared against the committed value only:\n * a render React throws away never becomes the one the next render keeps.\n */\nexport function useStableByContent<T>(value: T, same: (a: T, b: T) => boolean): T {\n  const held = useRef(value);\n  const out = held.current === value || same(held.current, value) ? held.current : value;\n  useInsertionEffect(() => {\n    held.current = out;\n  });\n  return out;\n}\n\n/** Same length, and the same element at every index. */\nexport function sameList<T>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((t, i) => t === b[i]);\n}\n"]}
+{"version":3,"sources":["../src/assignRef.ts","../src/useLatest.ts","../src/useStableByContent.ts"],"names":["useRef","useInsertionEffect"],"mappings":";;;AASO,SAAS,SAAA,CAAa,KAAyB,KAAA,EAAuB;AAC3E,EAAA,IAAI,OAAO,GAAA,KAAQ,UAAA,EAAY,GAAA,CAAI,KAAK,CAAA;AAAA,OAAA,IAC/B,GAAA,EAAM,GAAA,CAA8B,OAAA,GAAU,KAAA;AACzD;ACQO,SAAS,UAAa,KAAA,EAAmC;AAC9D,EAAA,MAAM,GAAA,GAAM,OAAO,KAAK,CAAA;AACxB,EAAA,kBAAA,CAAmB,MAAM;AACvB,IAAA,GAAA,CAAI,OAAA,GAAU,KAAA;AAAA,EAChB,CAAC,CAAA;AACD,EAAA,OAAO,GAAA;AACT;AClBO,SAAS,kBAAA,CAAsB,OAAU,IAAA,EAAkC;AAChF,EAAA,MAAM,IAAA,GAAOA,OAAO,KAAK,CAAA;AACzB,EAAA,MAAM,GAAA,GAAM,IAAA,CAAK,OAAA,KAAY,KAAA,IAAS,IAAA,CAAK,KAAK,OAAA,EAAS,KAAK,CAAA,GAAI,IAAA,CAAK,OAAA,GAAU,KAAA;AACjF,EAAAC,mBAAmB,MAAM;AACvB,IAAA,IAAA,CAAK,OAAA,GAAU,GAAA;AAAA,EACjB,CAAC,CAAA;AACD,EAAA,OAAO,GAAA;AACT;AAGO,SAAS,QAAA,CAAY,GAAiB,CAAA,EAA0B;AACrE,EAAA,OAAO,CAAA,CAAE,MAAA,KAAW,CAAA,CAAE,MAAA,IAAU,CAAA,CAAE,KAAA,CAAM,CAAC,CAAA,EAAG,CAAA,KAAM,CAAA,KAAM,CAAA,CAAE,CAAC,CAAC,CAAA;AAC9D","file":"index.js","sourcesContent":["import type { Ref } from 'react';\n\n/**\n * Write `value` into a ref a caller passed in, whichever shape it has: call a\n * callback ref, set an object ref's `current`, ignore `null` or `undefined`.\n *\n * For a component that keeps the element (or handle) for itself and also\n * forwards it to a ref prop — call this from the component's own callback ref.\n */\nexport function assignRef<T>(ref: Ref<T> | undefined, value: T | null): void {\n  if (typeof ref === 'function') ref(value);\n  else if (ref) (ref as { current: T | null }).current = value;\n}\n","import { useInsertionEffect, useRef } from 'react';\n\n/**\n * A ref holding the `value` of the last **committed** render, for event\n * handlers, frame loops and other code that runs outside render and must not\n * re-subscribe every time `value` changes.\n *\n * Writing `ref.current = value` in a render body is not the same thing: React\n * may start a render and throw it away (a transition that suspends, a render\n * interrupted by a more urgent update), and the value that render computed\n * would stay behind for the next event to read. This writes from\n * `useInsertionEffect`, so only a render that commits ever lands, and it lands\n * before any layout effect in that commit runs — a sibling's or a child's\n * `useLayoutEffect`, or a synchronous paint one of them triggers, already sees\n * it.\n *\n * Don't read `.current` during render expecting this render's value: until the\n * commit it holds the previous committed one (on mount, this first `value`).\n * Render code should use `value` itself.\n */\nexport function useLatest<T>(value: T): { readonly current: T } {\n  const ref = useRef(value);\n  useInsertionEffect(() => {\n    ref.current = value;\n  });\n  return ref;\n}\n","import { useInsertionEffect, useRef } from 'react';\n\n/**\n * `value`, or the one the last committed render returned when `same` says the\n * two are equal — so a caller rebuilding an equivalent object every render\n * hands its readers one identity. Compared against the committed value only:\n * a render React throws away never becomes the one the next render keeps.\n */\nexport function useStableByContent<T>(value: T, same: (a: T, b: T) => boolean): T {\n  const held = useRef(value);\n  const out = held.current === value || same(held.current, value) ? held.current : value;\n  useInsertionEffect(() => {\n    held.current = out;\n  });\n  return out;\n}\n\n/** Same length, and the same element at every index. */\nexport function sameList<T>(a: readonly T[], b: readonly T[]): boolean {\n  return a.length === b.length && a.every((t, i) => t === b[i]);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/react",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "description": "Generic React hooks the weasel packages share: a committed-value ref and content-stable identity. No weasel domain in it.",
   "license": "MIT",
   "type": "module",