@rethunk/react-load-hooks 0.3.0 → 0.4.0

package/README.md

@@ -32,20 +32,20 @@ A worked example and the contracts: [HUMANS.md](HUMANS.md).
 - `useLoaded` and `useDebouncedLoad` fetch on dependency changes and drop superseded answers.
 - `loader` is the same logic without React, for a store or a class.
 - `useStoredState` persists UI state in `localStorage`.
-- `useWidth` tracks an element's width before paint; `useDebouncedValue` settles a fast-changing value.
+- `useSize` tracks an element's width and height before paint; `useWidth` is the width only. `useDebouncedValue` settles a fast-changing value.
 - `sameValue`, `keepUnchanged` and `keepFields` keep the stored value when a fresh backend answer is equal, so subscribers do not re-render.
 - `clockWhen`, `absoluteWhen` and `relativeWhen` label a time through `Intl`: "3 minutes ago" within a week, a date after.
 - `useNowValue` and `useSecondValue` share one timer per period and re-render only on a changed answer.
 
 ## Documentation
 
-| Doc | Audience |
-| --- | --- |
-| [HUMANS.md](HUMANS.md) | Running and using the package |
-| [AGENTS.md](AGENTS.md) | Internals, invariants, and why |
+| Doc                                | Audience                       |
+| ---------------------------------- | ------------------------------ |
+| [HUMANS.md](HUMANS.md)             | Running and using the package  |
+| [AGENTS.md](AGENTS.md)             | Internals, invariants, and why |
 | [CONTRIBUTING.md](CONTRIBUTING.md) | Process — commits, tests, docs |
-| [SECURITY.md](SECURITY.md) | Vulnerability disclosure |
-| [CHANGELOG.md](CHANGELOG.md) | Release notes |
+| [SECURITY.md](SECURITY.md)         | Vulnerability disclosure       |
+| [CHANGELOG.md](CHANGELOG.md)       | Release notes                  |
 
 ## License
 

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { useDebouncedLoad } from './useDebouncedLoad.ts';
 export { useDebouncedValue } from './useDebouncedValue.ts';
 export { type LoadedOptions, useLoaded } from './useLoaded.ts';
 export { useNowValue, useSecondValue } from './useNow.ts';
+export { useSize } from './useSize.ts';
 export { readStored, useStoredState, writeStored } from './useStoredState.ts';
 export { useWidth } from './useWidth.ts';
 export { absoluteWhen, clockWhen, relativeWhen, type WhenOptions } from './when.ts';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACrE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC1D,OAAO,EAAE,KAAK,aAAa,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC9D,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACzD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAC7E,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA"}

package/dist/index.js

@@ -5,6 +5,7 @@ export { useDebouncedLoad } from './useDebouncedLoad.js';
 export { useDebouncedValue } from './useDebouncedValue.js';
 export { useLoaded } from './useLoaded.js';
 export { useNowValue, useSecondValue } from './useNow.js';
+export { useSize } from './useSize.js';
 export { readStored, useStoredState, writeStored } from './useStoredState.js';
 export { useWidth } from './useWidth.js';
 export { absoluteWhen, clockWhen, relativeWhen } from './when.js';

package/dist/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAK3C,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,4HAA4H;AAC5H,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAOzD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,EACE,cAAsB,EACtB,KAAW,GACZ,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CAAO;IA6C1E,IAAI,OAAO,cAAc,QAAQ,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI;IAoB/C,8GAA8G;IAC9G,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC,IAAI;EAKP"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../src/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAA;AAK3C,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAA;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;IAC/B,OAAO,EAAE,CAAC,EAAE,EAAE,OAAO,KAAK,IAAI,CAAA;IAC9B,4CAA4C;IAC5C,KAAK,EAAE,MAAM,IAAI,CAAA;CAClB;AAED,4HAA4H;AAC5H,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAOzD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,EACjB,EACE,cAAsB,EACtB,KAAW,GACZ,GAAE;IAAE,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CAAO;IA8C1E,IAAI,OAAO,cAAc,QAAQ,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI;IAoB/C,8GAA8G;IAC9G,GAAG,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC,IAAI;EAKP"}

package/dist/loader.js

@@ -27,7 +27,8 @@ export function loader(sink, { keepAcrossKeys = false, defer = now, } = {}) {
         const mineController = new AbortController();
         controller = mineController;
         sink.loading(true);
-        return load(mineController.signal)
+        // A load that throws before returning a promise settles through the sink like a rejection.
+        return new Promise((resolve) => resolve(load(mineController.signal)))
             .then((value) => {
             if (current()) {
                 sink.value(value);

package/dist/useSize.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+/** The client size of the element the ref points at, kept current as it resizes; 0 until measured. */
+declare function useSize<T extends HTMLElement>(ref: RefObject<T | null>): {
+    width: number;
+    height: number;
+};
+export { useSize };
+//# sourceMappingURL=useSize.d.ts.map

package/dist/useSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSize.d.ts","sourceRoot":"","sources":["../src/useSize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAA6B,MAAM,OAAO,CAAA;AAGjE,sGAAsG;AACtG,iBAAS,OAAO,CAAC,CAAC,SAAS,WAAW,EACpC,GAAG,EAAE,SAAS,CAAC,CAAC,GAAG,IAAI,CAAC,GACvB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAsBnC;AAED,OAAO,EAAE,OAAO,EAAE,CAAA"}

package/dist/useSize.js

@@ -0,0 +1,24 @@
+import { useLayoutEffect, useState } from 'react';
+import { flushSync } from 'react-dom';
+/** The client size of the element the ref points at, kept current as it resizes; 0 until measured. */
+function useSize(ref) {
+    const [size, setSize] = useState({ width: 0, height: 0 });
+    // Measured before paint, so the first frame is laid out for the real size rather than 0.
+    useLayoutEffect(() => {
+        const el = ref.current;
+        if (!el) {
+            return;
+        }
+        const apply = () => setSize((prev) => prev.width === el.clientWidth && prev.height === el.clientHeight
+            ? prev
+            : { width: el.clientWidth, height: el.clientHeight });
+        // Rendered before the browser paints the resize: a default-priority update would paint one frame laid out for the
+        // old size, with whatever columns or scrollbar that size implies.
+        const ro = new ResizeObserver(() => flushSync(apply));
+        ro.observe(el);
+        apply();
+        return () => ro.disconnect();
+    }, [ref]);
+    return size;
+}
+export { useSize };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rethunk/react-load-hooks",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React hooks for async loads that never land out of order, plus the small state hooks an app builds screens from.",
   "license": "MIT",
   "author": "Rethunk.Tech, LLC",
@@ -29,7 +29,7 @@
     "pack:check": "bun scripts/check-pack.ts"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.6.4",
+    "@biomejs/biome": "^2.6.6",
     "@happy-dom/global-registrator": "^21.0.4",
     "@testing-library/dom": "^10.4.2",
     "@testing-library/react": "^16.3.3",

package/src/index.ts

@@ -5,6 +5,7 @@ export { useDebouncedLoad } from './useDebouncedLoad.ts'
 export { useDebouncedValue } from './useDebouncedValue.ts'
 export { type LoadedOptions, useLoaded } from './useLoaded.ts'
 export { useNowValue, useSecondValue } from './useNow.ts'
+export { useSize } from './useSize.ts'
 export { readStored, useStoredState, writeStored } from './useStoredState.ts'
 export { useWidth } from './useWidth.ts'
 export { absoluteWhen, clockWhen, relativeWhen, type WhenOptions } from './when.ts'

package/src/loader.ts

@@ -49,7 +49,8 @@ export function loader<T>(
     const mineController = new AbortController()
     controller = mineController
     sink.loading(true)
-    return load(mineController.signal)
+    // A load that throws before returning a promise settles through the sink like a rejection.
+    return new Promise<T>((resolve) => resolve(load(mineController.signal)))
       .then(
         (value) => {
           if (current()) {

package/src/useSize.ts

@@ -0,0 +1,31 @@
+import { type RefObject, useLayoutEffect, useState } from 'react'
+import { flushSync } from 'react-dom'
+
+/** The client size of the element the ref points at, kept current as it resizes; 0 until measured. */
+function useSize<T extends HTMLElement>(
+  ref: RefObject<T | null>,
+): { width: number; height: number } {
+  const [size, setSize] = useState({ width: 0, height: 0 })
+  // Measured before paint, so the first frame is laid out for the real size rather than 0.
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (!el) {
+      return
+    }
+    const apply = () =>
+      setSize((prev) =>
+        prev.width === el.clientWidth && prev.height === el.clientHeight
+          ? prev
+          : { width: el.clientWidth, height: el.clientHeight },
+      )
+    // Rendered before the browser paints the resize: a default-priority update would paint one frame laid out for the
+    // old size, with whatever columns or scrollbar that size implies.
+    const ro = new ResizeObserver(() => flushSync(apply))
+    ro.observe(el)
+    apply()
+    return () => ro.disconnect()
+  }, [ref])
+  return size
+}
+
+export { useSize }