ropegeo-common 1.15.0 → 1.16.1

package/README.md

@@ -326,9 +326,9 @@ Legend entries for page minimaps are keyed objects (`legend` on `PageMiniMap`);
 
 | Name | Description | Import |
 | --- | --- | --- |
-| `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'` |
+| `RopeGeoDataLoader` | Single-request loader: `onlinePath` / `onlinePathParams`, optional `offlineData` (object used as `data` immediately; no network), optional `timeoutAfterSeconds` and `isOnline`. Children receive `data`, `errors`, `timeoutCountdown` (numeric only while an online fetch is in flight, otherwise `null`), and `reload`. Reconnect refetch uses `dirtyWhileOffline` driven by a semantic key (no `refreshOnReconnect` prop). Also exports `Method`, `Service`, `SERVICE_BASE_URL`. | `import { RopeGeoDataLoader, Method, Service } from 'ropegeo-common/components'` |
+| `RopeGeoPagedDataLoader` | Cursor-paginated list: same networking props as above; children get `loadNextPage`, `loadingNextPage`, `morePages`, plus `data`, `errors`, `timeoutCountdown`, `reload`. | `import { RopeGeoPagedDataLoader } from 'ropegeo-common/components'` |
+| `RopeGeoProgressDataLoader` | Page-based “progress” fetch: batches additional pages until `total` is satisfied; children get `received`, `total`, `data`, `errors`, `timeoutCountdown`, `reload`. | `import { RopeGeoProgressDataLoader } from 'ropegeo-common/components'` |
 
 ---
 

package/dist/components/RopeGeoDataLoader.d.ts

@@ -0,0 +1,51 @@
+import type { ReactNode } from "react";
+export declare const Service: {
+    readonly WEBSCRAPER: "WEBSCRAPER";
+};
+export type Service = (typeof Service)[keyof typeof Service];
+export declare const Method: {
+    readonly GET: "GET";
+    readonly POST: "POST";
+    readonly PUT: "PUT";
+    readonly DELETE: "DELETE";
+};
+export type Method = (typeof Method)[keyof typeof Method];
+export declare const SERVICE_BASE_URL: Record<Service, string>;
+export type RopeGeoDataLoaderProps<T = unknown> = {
+    service: Service;
+    method: Method;
+    /** HTTP path template (e.g. `/ropewiki/page/:id`). Used when loading from the network. */
+    onlinePath: string;
+    onlinePathParams?: Record<string, string>;
+    queryParams?: Record<string, string | number | boolean | undefined>;
+    body?: object;
+    /**
+     * Request deadline in seconds (abort + timeout error). When omitted, {@link timeoutCountdown}
+     * stays `null` and no deadline is enforced.
+     */
+    timeoutAfterSeconds?: number;
+    /**
+     * When `false`, the online request is not started and children receive {@link NO_NETWORK_MESSAGE}
+     * as the error. Previously loaded `data` is kept until the network returns. When `true` or
+     * omitted, behavior is unchanged.
+     */
+    isOnline?: boolean;
+    /**
+     * When set, this value is used as `data` immediately (no network). Callers that load from disk
+     * should read and parse the file themselves, then pass the resulting object here.
+     */
+    offlineData?: T;
+    children: (args: {
+        data: T | null;
+        errors: Error | null;
+        /**
+         * Whole seconds remaining until abort while an **online** fetch is in flight, only when
+         * `timeoutAfterSeconds` is set. Otherwise always `null`.
+         */
+        timeoutCountdown: number | null;
+        /** Re-runs the online request while online. No-op when `isOnline` is `false`. */
+        reload: () => void;
+    }) => ReactNode;
+};
+export declare function RopeGeoDataLoader<T = unknown>({ service, method, onlinePath, onlinePathParams, queryParams, body, timeoutAfterSeconds, isOnline, offlineData, children, }: RopeGeoDataLoaderProps<T>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=RopeGeoDataLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RopeGeoDataLoader.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoDataLoader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAavC,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;AAoEF,MAAM,MAAM,sBAAsB,CAAC,CAAC,GAAG,OAAO,IAAI;IAChD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,CAAC;IAChB,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;QACf,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB;;;WAGG;QACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,iFAAiF;QACjF,MAAM,EAAE,MAAM,IAAI,CAAC;KACpB,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,OAAO,EAAE,EAC7C,OAAO,EACP,MAAM,EACN,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,WAAW,EACX,QAAQ,GACT,EAAE,sBAAsB,CAAC,CAAC,CAAC,2CAwT3B"}

package/dist/components/{RopeGeoHttpRequest.js → RopeGeoDataLoader.js}

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SERVICE_BASE_URL = exports.Method = exports.Service = void 0;
-exports.RopeGeoHttpRequest = RopeGeoHttpRequest;
+exports.RopeGeoDataLoader = RopeGeoDataLoader;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const network_1 = require("../helpers/network");
@@ -40,38 +40,101 @@ function buildUrl(baseUrl, path, pathParams, queryParams) {
     }
     return url.toString();
 }
-function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, body, timeoutAfterSeconds, isOnline, refreshOnReconnect = false, children, }) {
-    const [loading, setLoading] = (0, react_1.useState)(true);
+function hasEffectiveQueryParams(queryParams) {
+    if (queryParams == null)
+        return false;
+    return Object.entries(queryParams).some(([, v]) => v !== undefined && v !== "");
+}
+function dataLoaderReconnectSemanticKey(service, method, onlinePath, pathParamsKey, bodyKey, queryParams, queryParamsKey) {
+    const bodyStr = bodyKey === undefined || bodyKey === null
+        ? ""
+        : typeof bodyKey === "object"
+            ? JSON.stringify(bodyKey)
+            : String(bodyKey);
+    const q = hasEffectiveQueryParams(queryParams) ? queryParamsKey : "";
+    return `${service}|${method}|${onlinePath}|${pathParamsKey}|${bodyStr}|${q}`;
+}
+function offlineDataKeyPart(offlineData) {
+    if (offlineData === undefined)
+        return "";
+    return `|obj:${JSON.stringify(offlineData)}`;
+}
+function RopeGeoDataLoader({ service, method, onlinePath, onlinePathParams, queryParams, body, timeoutAfterSeconds, isOnline, offlineData, children, }) {
     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 [reloadTick, setReloadTick] = (0, react_1.useState)(0);
     const pendingReloadRef = (0, react_1.useRef)(false);
     const errorsRef = (0, react_1.useRef)(errors);
-    const hasCommittedRef = (0, react_1.useRef)(hasCommittedOnce);
+    const hasCommittedRef = (0, react_1.useRef)(false);
     errorsRef.current = errors;
-    hasCommittedRef.current = hasCommittedOnce;
-    const reload = (0, react_1.useCallback)(() => {
-        if (isOnline === false)
-            return;
-        pendingReloadRef.current = true;
-        setReloadTick((n) => n + 1);
-    }, [isOnline]);
-    const pathParamsKey = JSON.stringify(pathParams ?? null);
+    const dirtyWhileOfflineRef = (0, react_1.useRef)(false);
+    const semanticSnapshotRef = (0, react_1.useRef)(null);
+    const prevIsOnlineRef = (0, react_1.useRef)(undefined);
+    const pathParamsKey = JSON.stringify(onlinePathParams ?? null);
     const queryParamsKey = JSON.stringify(queryParams ?? null);
     const bodyKey = body === undefined || body === null
         ? body
         : 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 requestKey = (0, react_1.useMemo)(() => `${service}|${method}|${onlinePath}|${pathParamsKey}|${queryParamsKey}|${String(bodyKey)}|${timeoutAfterSeconds ?? ""}${offlineDataKeyPart(offlineData)}`, [
+        service,
+        method,
+        onlinePath,
+        pathParamsKey,
+        queryParamsKey,
+        bodyKey,
+        timeoutAfterSeconds,
+        offlineData,
+    ]);
+    const reconnectSemanticKey = (0, react_1.useMemo)(() => dataLoaderReconnectSemanticKey(service, method, onlinePath, pathParamsKey, bodyKey, queryParams, queryParamsKey), [
+        service,
+        method,
+        onlinePath,
+        pathParamsKey,
+        bodyKey,
+        queryParams,
+        queryParamsKey,
+    ]);
+    const reload = (0, react_1.useCallback)(() => {
+        if (isOnline === false)
+            return;
+        pendingReloadRef.current = true;
+        setReloadTick((n) => n + 1);
+    }, [isOnline]);
     const lastRequestKeyRef = (0, react_1.useRef)("");
+    /** `offlineData` object — immediate `data`, no network. */
+    (0, react_1.useEffect)(() => {
+        if (offlineData === undefined) {
+            return;
+        }
+        setData(offlineData);
+        setErrors(null);
+        hasCommittedRef.current = true;
+        dirtyWhileOfflineRef.current = false;
+        semanticSnapshotRef.current = null;
+    }, [offlineData]);
     (0, react_1.useEffect)(() => {
         const online = isOnline !== false;
         const prevOnline = prevIsOnlineRef.current;
+        const enteringOffline = prevOnline === true && !online;
         const reconnecting = prevOnline === false && online;
+        if (enteringOffline) {
+            dirtyWhileOfflineRef.current = false;
+            semanticSnapshotRef.current = reconnectSemanticKey;
+        }
+        if (!online && prevOnline !== undefined) {
+            if (semanticSnapshotRef.current != null &&
+                reconnectSemanticKey !== semanticSnapshotRef.current) {
+                dirtyWhileOfflineRef.current = true;
+            }
+        }
+        /** Object `offlineData`: dedicated effect owns `data`; never hit the network here. */
+        if (offlineData !== undefined) {
+            prevIsOnlineRef.current = online;
+            return;
+        }
         const keyChanged = lastRequestKeyRef.current !== requestKey;
         const isManualReload = pendingReloadRef.current;
         if (isManualReload) {
@@ -82,30 +145,30 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
             if (keyChanged) {
                 lastRequestKeyRef.current = requestKey;
                 setData(null);
-                setHasCommittedOnce(false);
+                hasCommittedRef.current = false;
                 setErrors(null);
             }
             prevIsOnlineRef.current = false;
-            setLoading(false);
             setErrors(new Error(network_1.NO_NETWORK_MESSAGE));
             setTimeoutCountdown(null);
             return;
         }
         if (keyChanged) {
             lastRequestKeyRef.current = requestKey;
-            setHasCommittedOnce(false);
+            hasCommittedRef.current = false;
             setData(null);
             setErrors(null);
         }
         if (!keyChanged && reconnecting) {
             const onlyNoNetwork = errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE;
-            if (!isManualReload &&
-                hasCommittedRef.current &&
-                onlyNoNetwork &&
-                !refreshOnReconnect) {
+            const shouldRefetchAfterReconnect = dirtyWhileOfflineRef.current ||
+                !hasCommittedRef.current ||
+                !onlyNoNetwork;
+            if (!isManualReload && !shouldRefetchAfterReconnect) {
                 setErrors(null);
-                setLoading(false);
                 prevIsOnlineRef.current = true;
+                dirtyWhileOfflineRef.current = false;
+                semanticSnapshotRef.current = null;
                 return;
             }
         }
@@ -115,15 +178,14 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
         const timedOutRef = { current: false };
         const requestStartedAt = Date.now();
         const timeoutMs = (0, network_1.resolveRequestTimeoutMs)(timeoutAfterSeconds);
-        setLoading(true);
         setErrors(null);
         setTimeoutCountdown(null);
-        const keepStaleDuringFetch = reconnecting &&
+        const keepStaleForManualReload = isManualReload && hasCommittedRef.current;
+        const keepStaleDuringReconnectRefetch = reconnecting &&
             hasCommittedRef.current &&
             errorsRef.current?.message === network_1.NO_NETWORK_MESSAGE &&
-            refreshOnReconnect;
-        const keepStaleForManualReload = isManualReload && hasCommittedRef.current;
-        if (!keyChanged && !keepStaleDuringFetch && !keepStaleForManualReload) {
+            dirtyWhileOfflineRef.current;
+        if (!keyChanged && !keepStaleForManualReload && !keepStaleDuringReconnectRefetch) {
             setData(null);
         }
         const policyDispose = timeoutMs == null
@@ -144,7 +206,7 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                 },
             });
         const baseUrl = exports.SERVICE_BASE_URL[service];
-        const url = buildUrl(baseUrl, path, pathParams, queryParams);
+        const url = buildUrl(baseUrl, onlinePath, onlinePathParams, queryParams);
         const init = {
             method,
             headers: {
@@ -163,13 +225,15 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
             if (!res.ok) {
                 setErrors(new Error((0, network_1.formatHttpStatusMessage)(res.status, text || res.statusText)));
                 setData(null);
-                setHasCommittedOnce(false);
+                hasCommittedRef.current = false;
                 return;
             }
             if (text.length === 0) {
                 setData(null);
                 setErrors(null);
-                setHasCommittedOnce(true);
+                hasCommittedRef.current = true;
+                dirtyWhileOfflineRef.current = false;
+                semanticSnapshotRef.current = null;
                 return;
             }
             try {
@@ -178,20 +242,26 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
                 if (!cancelled) {
                     setData(parsed.result);
                     setErrors(null);
-                    setHasCommittedOnce(true);
+                    hasCommittedRef.current = true;
+                    dirtyWhileOfflineRef.current = false;
+                    semanticSnapshotRef.current = null;
                 }
             }
             catch (parseError) {
                 if (!cancelled) {
-                    console.error("[RopeGeoHttpRequest] Invalid JSON response", {
+                    console.error("[RopeGeoDataLoader] Invalid JSON response", {
                         url,
                         status: res.status,
                         responseText: text.slice(0, 500),
-                        parseError: parseError instanceof Error ? parseError.message : String(parseError),
+                        parseError: parseError instanceof Error
+                            ? parseError.message
+                            : String(parseError),
                     });
-                    setErrors(parseError instanceof Error ? parseError : new Error("Invalid JSON response"));
+                    setErrors(parseError instanceof Error
+                        ? parseError
+                        : new Error("Invalid JSON response"));
                     setData(null);
-                    setHasCommittedOnce(false);
+                    hasCommittedRef.current = false;
                 }
             }
         })
@@ -201,24 +271,23 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
             if (timedOutRef.current) {
                 setErrors(new Error((0, network_1.formatNetworkRequestErrorMessage)(new Error(network_1.NETWORK_REQUEST_TIMED_OUT_MESSAGE))));
                 setData(null);
-                setHasCommittedOnce(false);
+                hasCommittedRef.current = false;
                 return;
             }
             if ((0, network_1.isAbortError)(err))
                 return;
-            console.error("[RopeGeoHttpRequest] Request failed", {
+            console.error("[RopeGeoDataLoader] Request failed", {
                 url,
                 error: err instanceof Error ? err.message : String(err),
             });
             setErrors(new Error((0, network_1.formatNetworkRequestErrorMessage)(err)));
             setData(null);
-            setHasCommittedOnce(false);
+            hasCommittedRef.current = false;
         })
             .finally(() => {
             policyDispose();
             if (!cancelled) {
                 setTimeoutCountdown(null);
-                setLoading(false);
             }
         });
         return () => {
@@ -229,20 +298,19 @@ function RopeGeoHttpRequest({ service, method, path, pathParams, queryParams, bo
     }, [
         service,
         method,
-        path,
+        onlinePath,
         pathParamsKey,
         queryParamsKey,
         bodyKey,
         timeoutAfterSeconds,
         isOnline,
-        refreshOnReconnect,
         requestKey,
         reloadTick,
+        offlineData,
+        reconnectSemanticKey,
+        queryParams,
     ]);
-    const refreshing = loading && hasCommittedOnce;
     return ((0, jsx_runtime_1.jsx)(jsx_runtime_1.Fragment, { children: children({
-            loading,
-            refreshing,
             data,
             errors,
             timeoutCountdown,

package/dist/components/RopeGeoPagedDataLoader.d.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from "react";
+import { type CursorPaginationParams } from "../models";
+import { Method, Service } from "./RopeGeoDataLoader";
+export type RopeGeoPagedDataLoaderProps<T = unknown> = {
+    service: Service;
+    method?: (typeof Method)[keyof typeof Method];
+    onlinePath: string;
+    onlinePathParams?: Record<string, string>;
+    queryParams: CursorPaginationParams;
+    timeoutAfterSeconds?: number;
+    isOnline?: boolean;
+    children: (args: {
+        loadingNextPage: boolean;
+        data: T[] | null;
+        errors: Error | null;
+        loadNextPage: () => void;
+        morePages: boolean;
+        timeoutCountdown: number | null;
+        reload: () => void;
+    }) => ReactNode;
+};
+export declare function RopeGeoPagedDataLoader<T = unknown>({ service, method, onlinePath, onlinePathParams, queryParams, timeoutAfterSeconds, isOnline, children, }: RopeGeoPagedDataLoaderProps<T>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=RopeGeoPagedDataLoader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RopeGeoPagedDataLoader.d.ts","sourceRoot":"","sources":["../../src/components/RopeGeoPagedDataLoader.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAWvC,OAAO,EACL,KAAK,sBAAsB,EAE5B,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAoB,MAAM,qBAAqB,CAAC;AAqCxE,MAAM,MAAM,2BAA2B,CAAC,CAAC,GAAG,OAAO,IAAI;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,WAAW,EAAE,sBAAsB,CAAC;IACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,CAAC,IAAI,EAAE;QACf,eAAe,EAAE,OAAO,CAAC;QACzB,IAAI,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC;QACjB,MAAM,EAAE,KAAK,GAAG,IAAI,CAAC;QACrB,YAAY,EAAE,MAAM,IAAI,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC;QACnB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,MAAM,EAAE,MAAM,IAAI,CAAC;KACpB,KAAK,SAAS,CAAC;CACjB,CAAC;AAEF,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,EAClD,OAAO,EACP,MAAmB,EACnB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,mBAAmB,EACnB,QAAQ,EACR,QAAQ,GACT,EAAE,2BAA2B,CAAC,CAAC,CAAC,2CAsahC"}