ropegeo-common 1.12.9 → 1.12.11

package/README.md

@@ -312,9 +312,9 @@ Abstract classes live under `minimap/abstract/`, concrete under `minimap/concret
 
 | Name | Description | Import |
 | --- | --- | --- |
-| `RopeGeoHttpRequest` | Single GET/POST wrapper; parses `Result.fromResponseBody`; optional `timeoutAfterSeconds` (default from helpers) + `timeoutCountdown` children arg. | `import { RopeGeoHttpRequest, Method, Service } from 'ropegeo-common/components'` |
-| `RopeGeoCursorPaginationHttpRequest` | Cursor-paginated fetch with `loadMore`; optional `timeoutAfterSeconds`; `timeoutCountdown` on initial and `loadMore` requests. | `import { RopeGeoCursorPaginationHttpRequest } from 'ropegeo-common/components'` |
-| `RopeGeoPaginationHttpRequest<T>` | Page-based fetch; page 1 emits `timeoutCountdown`; later pages use the same per-fetch deadline; concatenates `results` into `data` (`T[]` when complete, otherwise `null` with `errors`). | `import { RopeGeoPaginationHttpRequest } from 'ropegeo-common/components'` |
+| `RopeGeoHttpRequest` | Single GET/POST wrapper; parses `Result.fromResponseBody`; optional `timeoutAfterSeconds`, `isOnline`, `refreshOnReconnect`, `timeoutCountdown`, and `refreshing` (stale-while-revalidate) children args. | `import { RopeGeoHttpRequest, Method, Service } from 'ropegeo-common/components'` |
+| `RopeGeoCursorPaginationHttpRequest` | Cursor-paginated fetch with `loadMore`; `data` is `T[] \| null` (null until first success); optional `timeoutAfterSeconds`, `isOnline`, `refreshOnReconnect`, `refreshing`, `timeoutCountdown`. | `import { RopeGeoCursorPaginationHttpRequest } from 'ropegeo-common/components'` |
+| `RopeGeoPaginationHttpRequest<T>` | Page-based fetch; concatenates `results` into `data` (`T[]` when complete, otherwise `null` with `errors`); optional `isOnline`, `refreshOnReconnect`, `refreshing`, `timeoutCountdown`. | `import { RopeGeoPaginationHttpRequest } from 'ropegeo-common/components'` |
 
 ---
 

package/dist/components/RopeGeoCursorPaginationHttpRequest.d.ts

@@ -14,22 +14,37 @@ export type RopeGeoCursorPaginationHttpRequestProps<T = unknown> = {
     timeoutAfterSeconds?: number;
     /**
      * When `false`, no HTTP requests run and children receive {@link NO_NETWORK_MESSAGE} as the error.
-     * Same semantics as `isOnline` on {@link RopeGeoHttpRequest}.
+     * Previously loaded `data` and cursor `params` are kept until the network returns.
      */
     isOnline?: boolean;
+    /**
+     * When `isOnline` goes from `false` to online and there is already successful data for the same
+     * request (only the soft {@link NO_NETWORK_MESSAGE} error), a new fetch runs only if this is
+     * `true`. Otherwise stale data stays visible and `errors` is cleared. When there is no
+     * successful data yet, or the last error was not the offline placeholder, a fetch always runs.
+     * @default false
+     */
+    refreshOnReconnect?: boolean;
     /**
      * Response body is parsed via CursorPaginationResults.fromResponseBody (must include resultType).
      * Parsed shape is ValidatedCursorPaginationResponse; children receive result.results as data.
+     * `data` is `null` until the first successful response for the current request identity, then an
+     * array (possibly empty) for loaded pages.
      */
     children: (args: {
         loading: boolean;
         loadingMore: boolean;
-        data: T[];
+        /**
+         * `true` while the initial request is in flight after at least one successful response for the
+         * current request identity (stale-while-revalidate). Not used for `loadMore` alone.
+         */
+        refreshing: boolean;
+        data: T[] | null;
         errors: Error | null;
         loadMore: () => void;
         hasMore: boolean;
         timeoutCountdown: number | null;
     }) => ReactNode;
 };
-export declare function RopeGeoCursorPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, children, }: RopeGeoCursorPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function RopeGeoCursorPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, refreshOnReconnect, children, }: RopeGeoCursorPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=RopeGeoCursorPaginationHttpRequest.d.ts.map

package/dist/components/RopeGeoCursorPaginationHttpRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RopeGeoCursorPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoCursorPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AASvC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AAsCzE,MAAM,MAAM,uCAAuC,CAAC,CAAC,GAAG,OAAO,IAAI;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,sBAAsB,CAAC;IACpC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,OAAO,CAAC;QACrB,IAAI,EAAE,CAAC,EAAE,CAAC;QACV,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;QACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kCAAkC,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9D,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,uCAAuC,CAAC,CAAC,CAAC,2CAoQ5C"}
+{"version":3,"file":"RopeGeoCursorPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoCursorPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AASvC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AAsCzE,MAAM,MAAM,uCAAuC,CAAC,CAAC,GAAG,OAAO,IAAI;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,sBAAsB,CAAC;IACpC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,WAAW,EAAE,OAAO,CAAC;QACrB;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAC;QACpB,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,QAAQ,EAAE,MAAM,IAAI,CAAC;QACrB,OAAO,EAAE,OAAO,CAAC;QACjB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kCAAkC,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9D,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,QAAQ,EACR,kBAA0B,EAC1B,QAAQ,GACT,EAAE,uCAAuC,CAAC,CAAC,CAAC,2CA6U5C"}

package/dist/components/RopeGeoCursorPaginationHttpRequest.js

@@ -30,16 +30,26 @@ function getResponseBody(raw) {
     }
     return raw;
 }
-function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, children, }) {
+function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, timeoutAfterSeconds, isOnline, refreshOnReconnect = false, children, }) {
     const [loading, setLoading] = (0, react_1.useState)(true);
     const [loadingMore, setLoadingMore] = (0, react_1.useState)(false);
-    const [data, setData] = (0, react_1.useState)([]);
+    const [data, setData] = (0, react_1.useState)(null);
     const [params, setParams] = (0, react_1.useState)(queryParams);
     const [errors, setErrors] = (0, react_1.useState)(null);
     const [timeoutCountdown, setTimeoutCountdown] = (0, react_1.useState)(null);
+    const [hasCommittedOnce, setHasCommittedOnce] = (0, react_1.useState)(false);
+    const errorsRef = (0, react_1.useRef)(errors);
+    const hasCommittedRef = (0, react_1.useRef)(hasCommittedOnce);
+    errorsRef.current = errors;
+    hasCommittedRef.current = hasCommittedOnce;
     const loadingMoreRef = (0, react_1.useRef)(false);
     const loadMoreAbortRef = (0, react_1.useRef)(null);
     const hasMore = params.cursor != null;
+    const pathParamsKey = JSON.stringify(pathParams ?? null);
+    const queryKey = queryParams.toQueryString();
+    const requestKey = (0, react_1.useMemo)(() => `${service}|${method}|${path}|${pathParamsKey}|${queryKey}|${timeoutAfterSeconds ?? ""}`, [service, method, path, pathParamsKey, queryKey, timeoutAfterSeconds]);
+    const prevIsOnlineRef = (0, react_1.useRef)(undefined);
+    const lastRequestKeyRef = (0, react_1.useRef)("");
     const buildUrl = (0, react_1.useCallback)((p) => {
         const baseUrl = RopeGeoHttpRequest_1.SERVICE_BASE_URL[service];
         const resolvedPath = resolvePath(path, pathParams);
@@ -48,24 +58,61 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
         return new URL(fullPath, baseUrl).toString();
     }, [service, path, pathParams]);
     (0, react_1.useEffect)(() => {
-        if (isOnline === false) {
-            setData([]);
-            setParams(queryParams);
+        const online = isOnline !== false;
+        const prevOnline = prevIsOnlineRef.current;
+        const reconnecting = prevOnline === false && online;
+        const keyChanged = lastRequestKeyRef.current !== requestKey;
+        if (!online) {
+            if (keyChanged) {
+                lastRequestKeyRef.current = requestKey;
+                setData(null);
+                setHasCommittedOnce(false);
+                setParams(queryParams);
+                setErrors(null);
+            }
+            loadMoreAbortRef.current?.abort();
+            loadMoreAbortRef.current = null;
+            loadingMoreRef.current = false;
+            setLoadingMore(false);
+            prevIsOnlineRef.current = false;
             setLoading(false);
             setErrors(new Error(network_1.NO_NETWORK_MESSAGE));
             setTimeoutCountdown(null);
             return;
         }
+        if (keyChanged) {
+            lastRequestKeyRef.current = requestKey;
+            setHasCommittedOnce(false);
+            setData(null);
+            setParams(queryParams);
+            setErrors(null);
+        }
+        if (!keyChanged && reconnecting) {
+            const onlyNoNetwork = errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE;
+            if (hasCommittedRef.current && onlyNoNetwork && !refreshOnReconnect) {
+                setErrors(null);
+                setLoading(false);
+                prevIsOnlineRef.current = true;
+                return;
+            }
+        }
+        prevIsOnlineRef.current = true;
         let cancelled = false;
         const abortController = new AbortController();
         const timedOutRef = { current: false };
         const requestStartedAt = Date.now();
         const timeoutMs = (0, network_1.resolveRequestTimeoutMs)(timeoutAfterSeconds);
-        setData([]);
-        setParams(queryParams);
         setLoading(true);
         setErrors(null);
         setTimeoutCountdown(null);
+        const keepStaleDuringFetch = reconnecting &&
+            hasCommittedRef.current &&
+            errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE &&
+            refreshOnReconnect;
+        if (!keyChanged && !keepStaleDuringFetch) {
+            setData(null);
+            setParams(queryParams);
+        }
         const policyDispose = timeoutMs == null
             ? () => { }
             : (0, network_1.installNetworkRequestPolicyTimers)(requestStartedAt, timeoutMs, {
@@ -96,11 +143,15 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
             const text = await res.text();
             if (!res.ok) {
                 setErrors(new Error(`HTTP ${res.status}: ${text || res.statusText}`));
-                setData([]);
+                setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if (text.length === 0) {
                 setData([]);
+                setParams(queryParams.withCursor(null));
+                setErrors(null);
+                setHasCommittedOnce(true);
                 return;
             }
             try {
@@ -113,6 +164,7 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 setData(results);
                 setParams(queryParams.withCursor(nextCursor));
                 setErrors(null);
+                setHasCommittedOnce(true);
             }
             catch (parseError) {
                 if (!cancelled) {
@@ -123,7 +175,8 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                         parseError: parseError instanceof Error ? parseError.message : String(parseError),
                     });
                     setErrors(new Error("Invalid JSON response"));
-                    setData([]);
+                    setData(null);
+                    setHasCommittedOnce(false);
                 }
             }
         })
@@ -132,7 +185,8 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 return;
             if (timedOutRef.current) {
                 setErrors(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE));
-                setData([]);
+                setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if ((0, network_1.isAbortError)(err))
@@ -142,7 +196,8 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 error: err instanceof Error ? err.message : String(err),
             });
             setErrors(err instanceof Error ? err : new Error(String(err)));
-            setData([]);
+            setData(null);
+            setHasCommittedOnce(false);
         })
             .finally(() => {
             policyDispose();
@@ -160,11 +215,13 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
         service,
         method,
         path,
-        pathParams,
-        queryParams,
+        pathParamsKey,
+        queryKey,
         buildUrl,
         timeoutAfterSeconds,
         isOnline,
+        refreshOnReconnect,
+        requestKey,
     ]);
     (0, react_1.useEffect)(() => {
         return () => {
@@ -222,7 +279,7 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
                 const body = getResponseBody(raw);
                 const result = models_1.CursorPaginationResults.fromResponseBody(body);
                 const { results, nextCursor } = result;
-                setData((prev) => [...prev, ...results]);
+                setData((prev) => [...(prev ?? []), ...results]);
                 setParams((p) => p.withCursor(nextCursor));
             }
             catch (parseError) {
@@ -258,9 +315,11 @@ function RopeGeoCursorPaginationHttpRequest({ service, method = RopeGeoHttpReque
             setLoadingMore(false);
         });
     }, [params, method, buildUrl, timeoutAfterSeconds, isOnline]);
+    const refreshing = loading && hasCommittedOnce;
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children({
             loading,
             loadingMore,
+            refreshing,
             data,
             errors,
             loadMore,

package/dist/components/RopeGeoHttpRequest.d.ts

@@ -24,16 +24,30 @@ export type RopeGeoHttpRequestProps<T = unknown> = {
     timeoutAfterSeconds?: number;
     /**
      * When `false`, the request is not started and children receive {@link NO_NETWORK_MESSAGE} as the
-     * error. When `true` or omitted, behavior is unchanged. Pass from app-level connectivity (e.g.
-     * `expo-network`) so fetches are not fired while offline.
+     * error. Previously loaded `data` is kept until the network returns. When `true` or omitted,
+     * behavior is unchanged. Pass from app-level connectivity (e.g. `expo-network`) so fetches are
+     * not fired while offline.
      */
     isOnline?: boolean;
+    /**
+     * When `isOnline` goes from `false` to online and there is already successful data for the same
+     * request (only the soft {@link NO_NETWORK_MESSAGE} error), a new fetch runs only if this is
+     * `true`. Otherwise stale data stays visible and `errors` is cleared. When there is no
+     * successful data yet, or the last error was not the offline placeholder, a fetch always runs.
+     * @default false
+     */
+    refreshOnReconnect?: boolean;
     /**
      * Response body is parsed via Result.fromResponseBody (must include resultType and result).
      * Children receive the validated result.result as data (typed by T).
      */
     children: (args: {
         loading: boolean;
+        /**
+         * `true` while a request is in flight after at least one successful response for the current
+         * request identity (stale-while-revalidate).
+         */
+        refreshing: boolean;
         data: T | null;
         errors: Error | null;
         /**
@@ -44,5 +58,5 @@ export type RopeGeoHttpRequestProps<T = unknown> = {
         timeoutCountdown: number | null;
     }) => ReactNode;
 };
-export declare function RopeGeoHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, children, }: RopeGeoHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function RopeGeoHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, refreshOnReconnect, children, }: RopeGeoHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=RopeGeoHttpRequest.d.ts.map

package/dist/components/RopeGeoHttpRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RopeGeoHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAWvC,eAAO,MAAM,OAAO;;CAEV,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAEpD,CAAC;AAmCF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,OAAO,IAAI;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB;;;;WAIG;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9C,OAAO,EACP,MAAM,EACN,IAAI,EACJ,UAAU,EACV,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,uBAAuB,CAAC,CAAC,CAAC,2CAyJ5B"}
+{"version":3,"file":"RopeGeoHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAWvC,eAAO,MAAM,OAAO;;CAEV,CAAC;AACX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,OAAO,CAAC,CAAC,MAAM,OAAO,OAAO,CAAC,CAAC;AAE7D,eAAO,MAAM,MAAM;;;;;CAKT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAEpD,CAAC;AAmCF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,OAAO,IAAI;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;OAGG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAC;QACpB,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB;;;;WAIG;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC9C,OAAO,EACP,MAAM,EACN,IAAI,EACJ,UAAU,EACV,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,kBAA0B,EAC1B,QAAQ,GACT,EAAE,uBAAuB,CAAC,CAAC,CAAC,2CA0N5B"}

package/dist/components/RopeGeoHttpRequest.js

@@ -40,11 +40,16 @@ function buildUrl(baseUrl, path, pathParams, queryParams) {
     }
     return url.toString();
 }
-function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, children, }) {
+function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, refreshOnReconnect = false, children, }) {
     const [loading, setLoading] = (0, react_1.useState)(true);
     const [data, setData] = (0, react_1.useState)(null);
     const [errors, setErrors] = (0, react_1.useState)(null);
     const [timeoutCountdown, setTimeoutCountdown] = (0, react_1.useState)(null);
+    const [hasCommittedOnce, setHasCommittedOnce] = (0, react_1.useState)(false);
+    const errorsRef = (0, react_1.useRef)(errors);
+    const hasCommittedRef = (0, react_1.useRef)(hasCommittedOnce);
+    errorsRef.current = errors;
+    hasCommittedRef.current = hasCommittedOnce;
     const pathParamsKey = JSON.stringify(pathParams ?? null);
     const queryParamsKey = JSON.stringify(queryParams ?? null);
     const bodyKey = body === undefined || body === null
@@ -52,14 +57,43 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
         : typeof body === "object"
             ? JSON.stringify(body)
             : body;
+    const requestKey = (0, react_1.useMemo)(() => `${service}|${method}|${path}|${pathParamsKey}|${queryParamsKey}|${String(bodyKey)}|${timeoutAfterSeconds ?? ""}`, [service, method, path, pathParamsKey, queryParamsKey, bodyKey, timeoutAfterSeconds]);
+    const prevIsOnlineRef = (0, react_1.useRef)(undefined);
+    const lastRequestKeyRef = (0, react_1.useRef)("");
     (0, react_1.useEffect)(() => {
-        if (isOnline === false) {
+        const online = isOnline !== false;
+        const prevOnline = prevIsOnlineRef.current;
+        const reconnecting = prevOnline === false && online;
+        const keyChanged = lastRequestKeyRef.current !== requestKey;
+        if (!online) {
+            if (keyChanged) {
+                lastRequestKeyRef.current = requestKey;
+                setData(null);
+                setHasCommittedOnce(false);
+                setErrors(null);
+            }
+            prevIsOnlineRef.current = false;
             setLoading(false);
-            setData(null);
             setErrors(new Error(network_1.NO_NETWORK_MESSAGE));
             setTimeoutCountdown(null);
             return;
         }
+        if (keyChanged) {
+            lastRequestKeyRef.current = requestKey;
+            setHasCommittedOnce(false);
+            setData(null);
+            setErrors(null);
+        }
+        if (!keyChanged && reconnecting) {
+            const onlyNoNetwork = errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE;
+            if (hasCommittedRef.current && onlyNoNetwork && !refreshOnReconnect) {
+                setErrors(null);
+                setLoading(false);
+                prevIsOnlineRef.current = true;
+                return;
+            }
+        }
+        prevIsOnlineRef.current = true;
         let cancelled = false;
         const abortController = new AbortController();
         const timedOutRef = { current: false };
@@ -68,6 +102,13 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
         setLoading(true);
         setErrors(null);
         setTimeoutCountdown(null);
+        const keepStaleDuringFetch = reconnecting &&
+            hasCommittedRef.current &&
+            errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE &&
+            refreshOnReconnect;
+        if (!keyChanged && !keepStaleDuringFetch) {
+            setData(null);
+        }
         const policyDispose = timeoutMs == null
             ? () => { }
             : (0, network_1.installNetworkRequestPolicyTimers)(requestStartedAt, timeoutMs, {
@@ -105,10 +146,13 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
             if (!res.ok) {
                 setErrors(new Error(`HTTP ${res.status}: ${text || res.statusText}`));
                 setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if (text.length === 0) {
                 setData(null);
+                setErrors(null);
+                setHasCommittedOnce(true);
                 return;
             }
             try {
@@ -117,6 +161,7 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                 if (!cancelled) {
                     setData(parsed.result);
                     setErrors(null);
+                    setHasCommittedOnce(true);
                 }
             }
             catch (parseError) {
@@ -129,6 +174,7 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                     });
                     setErrors(parseError instanceof Error ? parseError : new Error("Invalid JSON response"));
                     setData(null);
+                    setHasCommittedOnce(false);
                 }
             }
         })
@@ -138,6 +184,7 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
             if (timedOutRef.current) {
                 setErrors(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE));
                 setData(null);
+                setHasCommittedOnce(false);
                 return;
             }
             if ((0, network_1.isAbortError)(err))
@@ -148,6 +195,7 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
             });
             setErrors(err instanceof Error ? err : new Error(String(err)));
             setData(null);
+            setHasCommittedOnce(false);
         })
             .finally(() => {
             policyDispose();
@@ -170,9 +218,13 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
         bodyKey,
         timeoutAfterSeconds,
         isOnline,
+        refreshOnReconnect,
+        requestKey,
     ]);
+    const refreshing = loading && hasCommittedOnce;
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children({
             loading,
+            refreshing,
             data,
             errors,
             timeoutCountdown,

package/dist/components/RopeGeoPaginationHttpRequest.d.ts

@@ -20,11 +20,26 @@ export type RopeGeoPaginationHttpRequestProps<T = unknown> = {
     timeoutAfterSeconds?: number;
     /**
      * When `false`, no HTTP requests run and children receive {@link NO_NETWORK_MESSAGE} as the error.
-     * Same semantics as `isOnline` on {@link RopeGeoHttpRequest}.
+     * Previously loaded `data`, `received`, and `total` are kept so UIs can stay on stale results until
+     * the network returns. Same semantics as `isOnline` on {@link RopeGeoHttpRequest} and
+     * {@link RopeGeoCursorPaginationHttpRequest}.
      */
     isOnline?: boolean;
+    /**
+     * When `isOnline` goes from `false` to online and there is already successful data for the same
+     * request (only the soft {@link NO_NETWORK_MESSAGE} error), a new fetch runs only if this is
+     * `true`. Otherwise stale data stays visible and `errors` is cleared. When there is no
+     * successful data yet, or the last error was not the offline placeholder, a fetch always runs.
+     * @default false
+     */
+    refreshOnReconnect?: boolean;
     children: (args: {
         loading: boolean;
+        /**
+         * `true` while a full pagination pass is in flight after at least one successful completion for
+         * the current request identity (stale-while-revalidate).
+         */
+        refreshing: boolean;
         received: number;
         total: number | null;
         /**
@@ -44,5 +59,5 @@ export type RopeGeoPaginationHttpRequestProps<T = unknown> = {
  * {@link PaginationResults.fromResponseBody}. Final `data` is pages concatenated in page order.
  * In-flight requests use one {@link AbortController}: unmount or any failure aborts the rest.
  */
-export declare function RopeGeoPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, batchSize, timeoutAfterSeconds, isOnline, children, }: RopeGeoPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function RopeGeoPaginationHttpRequest<T = unknown>({ service, method, path, pathParams, queryParams, batchSize, timeoutAfterSeconds, isOnline, refreshOnReconnect, children, }: RopeGeoPaginationHttpRequestProps<T>): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=RopeGeoPaginationHttpRequest.d.ts.map

package/dist/components/RopeGeoPaginationHttpRequest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RopeGeoPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAUvC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AA8DzE,MAAM,MAAM,iCAAiC,CAAC,CAAC,GAAG,OAAO,IAAI;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB;;;WAGG;QACH,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,+FAA+F;QAC/F,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,qGAAqG;QACrG,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,GAAG,OAAO,EAAE,EACxD,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,SAAc,EACd,mBAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,iCAAiC,CAAC,CAAC,CAAC,2CAuPtC"}
+{"version":3,"file":"RopeGeoPaginationHttpRequest.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoPaginationHttpRequest.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAUvC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,sBAAsB,CAAC;AA8DzE,MAAM,MAAM,iCAAiC,CAAC,CAAC,GAAG,OAAO,IAAI;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,OAAO,EAAE,OAAO,CAAC;QACjB;;;WAGG;QACH,UAAU,EAAE,OAAO,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB;;;WAGG;QACH,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,+FAA+F;QAC/F,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,qGAAqG;QACrG,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,CAAC,GAAG,OAAO,EAAE,EACxD,OAAO,EACP,MAAmB,EACnB,IAAI,EACJ,UAAU,EACV,WAAW,EACX,SAAc,EACd,mBAAmB,EACnB,QAAQ,EACR,kBAA0B,EAC1B,QAAQ,GACT,EAAE,iCAAiC,CAAC,CAAC,CAAC,2CAqTtC"}

package/dist/components/RopeGeoPaginationHttpRequest.js

@@ -57,36 +57,79 @@ function concatPaginationResultItemsSorted(pagesByNum) {
  * {@link PaginationResults.fromResponseBody}. Final `data` is pages concatenated in page order.
  * In-flight requests use one {@link AbortController}: unmount or any failure aborts the rest.
  */
-function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, batchSize = 10, timeoutAfterSeconds, isOnline, children, }) {
+function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.Method.GET, path, pathParams, queryParams, batchSize = 10, timeoutAfterSeconds, isOnline, refreshOnReconnect = false, children, }) {
     const [loading, setLoading] = (0, react_1.useState)(true);
     const [received, setReceived] = (0, react_1.useState)(0);
     const [total, setTotal] = (0, react_1.useState)(null);
     const [data, setData] = (0, react_1.useState)(null);
     const [errors, setErrors] = (0, react_1.useState)(null);
     const [timeoutCountdown, setTimeoutCountdown] = (0, react_1.useState)(null);
+    const [hasCommittedOnce, setHasCommittedOnce] = (0, react_1.useState)(false);
+    const errorsRef = (0, react_1.useRef)(errors);
+    const hasCommittedRef = (0, react_1.useRef)(hasCommittedOnce);
+    errorsRef.current = errors;
+    hasCommittedRef.current = hasCommittedOnce;
     const pathParamsKey = JSON.stringify(pathParams ?? null);
     const queryParamsKey = queryParams.toQueryString();
     const effectiveBatch = Math.max(1, Math.floor(batchSize));
+    const requestKey = (0, react_1.useMemo)(() => `${service}|${method}|${path}|${pathParamsKey}|${queryParamsKey}|${effectiveBatch}|${timeoutAfterSeconds ?? ""}`, [service, method, path, pathParamsKey, queryParamsKey, effectiveBatch, timeoutAfterSeconds]);
+    const prevIsOnlineRef = (0, react_1.useRef)(undefined);
+    const lastRequestKeyRef = (0, react_1.useRef)("");
     (0, react_1.useEffect)(() => {
-        if (isOnline === false) {
+        const online = isOnline !== false;
+        const prevOnline = prevIsOnlineRef.current;
+        const reconnecting = prevOnline === false && online;
+        const keyChanged = lastRequestKeyRef.current !== requestKey;
+        if (!online) {
+            if (keyChanged) {
+                lastRequestKeyRef.current = requestKey;
+                setHasCommittedOnce(false);
+                setReceived(0);
+                setTotal(null);
+                setData(null);
+                setErrors(null);
+            }
+            prevIsOnlineRef.current = false;
             setLoading(false);
-            setReceived(0);
-            setTotal(null);
-            setData(null);
             setErrors(new Error(network_1.NO_NETWORK_MESSAGE));
             setTimeoutCountdown(null);
             return;
         }
+        if (keyChanged) {
+            lastRequestKeyRef.current = requestKey;
+            setHasCommittedOnce(false);
+            setReceived(0);
+            setTotal(null);
+            setData(null);
+            setErrors(null);
+        }
+        if (!keyChanged && reconnecting) {
+            const onlyNoNetwork = errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE;
+            if (hasCommittedRef.current && onlyNoNetwork && !refreshOnReconnect) {
+                setErrors(null);
+                setLoading(false);
+                prevIsOnlineRef.current = true;
+                return;
+            }
+        }
+        prevIsOnlineRef.current = true;
         let cancelled = false;
         const abortController = new AbortController();
         const { signal } = abortController;
         const timeoutMs = (0, network_1.resolveRequestTimeoutMs)(timeoutAfterSeconds);
         setLoading(true);
-        setReceived(0);
-        setTotal(null);
-        setData(null);
         setErrors(null);
         setTimeoutCountdown(null);
+        const keepStaleDuringFetch = reconnecting &&
+            hasCommittedRef.current &&
+            errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE &&
+            refreshOnReconnect;
+        if (!keyChanged && !keepStaleDuringFetch) {
+            setReceived(0);
+            setTotal(null);
+            setData(null);
+            setHasCommittedOnce(false);
+        }
         const baseUrl = RopeGeoHttpRequest_1.SERVICE_BASE_URL[service];
         const resolvedPath = resolvePath(path, pathParams);
         const baseInit = {
@@ -219,6 +262,7 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                         return;
                     setData(concatPaginationResultItemsSorted(pagesByNum));
                     setErrors(null);
+                    setHasCommittedOnce(true);
                     return;
                 }
                 const lastPage = Math.max(1, Math.ceil(totalCount / limit));
@@ -249,6 +293,7 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                     return;
                 setData(concatPaginationResultItemsSorted(pagesByNum));
                 setErrors(null);
+                setHasCommittedOnce(true);
             }
             catch (err) {
                 if (cancelled || (0, network_1.isAbortError)(err))
@@ -258,6 +303,7 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
                 });
                 setErrors(err instanceof Error ? err : new Error(String(err)));
                 setData(null);
+                setHasCommittedOnce(false);
             }
             finally {
                 clearActivePolicy();
@@ -275,13 +321,16 @@ function RopeGeoPaginationHttpRequest({ service, method = RopeGeoHttpRequest_1.M
         path,
         pathParamsKey,
         queryParamsKey,
-        queryParams,
         effectiveBatch,
         timeoutAfterSeconds,
         isOnline,
+        refreshOnReconnect,
+        requestKey,
     ]);
+    const refreshing = loading && hasCommittedOnce;
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children({
             loading,
+            refreshing,
             received,
             total,
             data,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ropegeo-common",
-    "version": "1.12.9",
+    "version": "1.12.11",
     "description": "Shared domain models and helpers for RopeGeo and WebScraper",
     "license": "ISC",
     "repository": {