@carlonicora/nextjs-jsonapi 6.12.1 → 6.13.0

package/pwa/sw.js

@@ -6,12 +6,147 @@
 //
 // Per-app values (appId, offlineRevision, notificationIcon) come from the app's
 // own public/sw-config.js, which sets self.NJA_SW_CONFIG.
+//
+// Offline mode (opt-in; without these keys the worker behaves exactly as before):
+// - offlineShell: { default: "/offline-shell", locales: { it: "/it/offline-shell" } }
+//   At install the worker reads /offline-manifest.json ({ buildId, assets }) and
+//   caches every asset plus each shell URL in `${appId}-shell-${buildId}`, then
+//   a completion marker last; one failed file fails the install and deletes the
+//   half-filled cache, so the previous worker stays in charge and no worker ever
+//   answers from a cache without the marker. A
+//   failed navigation answers the shell of its locale (the first path segment
+//   matched against `locales`, otherwise `default`), then offline.html. GETs
+//   under /_next/static/ are served cache-first from the shell cache; after an
+//   online navigation the worker re-reads the manifest (at most every few
+//   minutes) and precaches a new build's shell in the background, so a deploy
+//   refreshes the shell without a new worker; any other
+//   same-origin GET goes to the network first and, when it fails, is answered
+//   from the shell cache (the device worker and SQLite files). Activate deletes
+//   shell caches of other builds.
+// - offlineImageHosts: ["api.example.com"] (a host or an origin)
+//   A GET to one of these hosts goes to the network; when the network fails it
+//   is answered from `${appId}-images`, where the app stores each artwork image
+//   under its exact URL. That cache is kept across activations.
 
 importScripts("/sw-config.js");
 
 const OFFLINE_URL = "/offline.html";
 const CACHE_NAME = `${self.NJA_SW_CONFIG.appId}-offline-${self.NJA_SW_CONFIG.offlineRevision}`;
 
+const OFFLINE_SHELL = self.NJA_SW_CONFIG.offlineShell || null;
+const OFFLINE_IMAGE_HOSTS = self.NJA_SW_CONFIG.offlineImageHosts || [];
+const MANIFEST_URL = "/offline-manifest.json";
+const SHELL_CACHE_PREFIX = `${self.NJA_SW_CONFIG.appId}-shell-`;
+const IMAGES_CACHE_NAME = `${self.NJA_SW_CONFIG.appId}-images`;
+// Written last into a shell cache: a shell cache without it is incomplete and never used.
+const SHELL_COMPLETE_URL = "/__nja-offline-shell-complete__";
+
+// The shell cache this worker installed. A worker can be stopped and restarted
+// between events, losing this value; it then falls back to the newest complete
+// shell cache (caches.keys() lists caches in creation order).
+let shellCacheName = null;
+
+async function currentShellCacheName() {
+  if (shellCacheName) return shellCacheName;
+  const keys = await caches.keys();
+  const shells = keys.filter(function (key) {
+    return key.startsWith(SHELL_CACHE_PREFIX);
+  });
+  for (let index = shells.length - 1; index >= 0; index--) {
+    const cache = await caches.open(shells[index]);
+    if (await cache.match(SHELL_COMPLETE_URL)) return shells[index];
+  }
+  return null;
+}
+
+function shellUrls() {
+  const urls = [OFFLINE_SHELL.default];
+  const locales = OFFLINE_SHELL.locales || {};
+  for (const locale of Object.keys(locales)) urls.push(locales[locale]);
+  return urls;
+}
+
+function shellUrlFor(url) {
+  const segment = new URL(url).pathname.split("/")[1] || "";
+  const locales = OFFLINE_SHELL.locales || {};
+  return Object.prototype.hasOwnProperty.call(locales, segment) ? locales[segment] : OFFLINE_SHELL.default;
+}
+
+async function installShell() {
+  const response = await fetch(new Request(MANIFEST_URL, { cache: "no-store" }));
+  if (!response.ok) throw new Error(`${MANIFEST_URL} answered ${response.status}`);
+  const manifest = await response.json();
+  const name = `${SHELL_CACHE_PREFIX}${manifest.buildId}`;
+  try {
+    const cache = await caches.open(name);
+    // cache.addAll rejects when any file fails, so the install fails with it.
+    await cache.addAll(
+      manifest.assets.concat(shellUrls()).map(function (url) {
+        return new Request(url, { cache: "reload" });
+      }),
+    );
+    await cache.put(SHELL_COMPLETE_URL, new Response("", { status: 200 }));
+  } catch (error) {
+    // Never leave a half-filled shell cache behind for any worker to pick.
+    await caches.delete(name);
+    throw error;
+  }
+  shellCacheName = name;
+}
+
+// A deploy changes the app's build, not this file: sw.js is byte-identical across builds, so no
+// new worker is installed. After an online navigation the worker reads the manifest and, when
+// the server runs a build it has no complete shell cache for, precaches that build's shell in
+// the background, then drops the other shell caches. At most one check per few minutes.
+const SHELL_REFRESH_INTERVAL_MS = 5 * 60 * 1000;
+let lastShellRefresh = 0;
+let shellRefresh = null;
+
+async function refreshShellIfStale() {
+  const response = await fetch(new Request(MANIFEST_URL, { cache: "no-store" }));
+  if (!response.ok) return;
+  const manifest = await response.json();
+  const name = `${SHELL_CACHE_PREFIX}${manifest.buildId}`;
+  const keys = await caches.keys();
+  if (keys.indexOf(name) !== -1) {
+    const existing = await caches.open(name);
+    if (await existing.match(SHELL_COMPLETE_URL)) {
+      shellCacheName = name;
+      return;
+    }
+  }
+  await installShell();
+  const others = (await caches.keys()).filter(function (key) {
+    return key.startsWith(SHELL_CACHE_PREFIX) && key !== shellCacheName;
+  });
+  await Promise.all(
+    others.map(function (key) {
+      return caches.delete(key);
+    }),
+  );
+}
+
+function maybeRefreshShell() {
+  const now = Date.now();
+  if (shellRefresh || now - lastShellRefresh < SHELL_REFRESH_INTERVAL_MS) return shellRefresh || Promise.resolve();
+  lastShellRefresh = now;
+  shellRefresh = refreshShellIfStale()
+    .catch(function (error) {
+      // The current shell stays in charge; the next navigation tries again later.
+      console.warn("[sw] refreshing the offline shell failed", error);
+    })
+    .finally(function () {
+      shellRefresh = null;
+    });
+  return shellRefresh;
+}
+
+function isImageHost(url) {
+  if (!OFFLINE_IMAGE_HOSTS.length) return false;
+  const parsed = new URL(url);
+  return OFFLINE_IMAGE_HOSTS.indexOf(parsed.host) !== -1 || OFFLINE_IMAGE_HOSTS.indexOf(parsed.origin) !== -1;
+}
+
 // Served when a navigation fails and the cached offline page is missing too
 // (evicted or cleared). Never answer a navigation with a bare network error.
 const OFFLINE_FALLBACK_HTML = `<!doctype html>
@@ -58,11 +193,16 @@ const OFFLINE_FALLBACK_HTML = `<!doctype html>
 
 self.addEventListener("install", function (event) {
   event.waitUntil(
-    caches.open(CACHE_NAME).then(function (cache) {
-      // cache.add rejects on a network error or a non-2xx response, so the
-      // install fails and the previous worker stays in charge.
-      return cache.add(new Request(OFFLINE_URL, { cache: "reload" }));
-    }),
+    caches
+      .open(CACHE_NAME)
+      .then(function (cache) {
+        // cache.add rejects on a network error or a non-2xx response, so the
+        // install fails and the previous worker stays in charge.
+        return cache.add(new Request(OFFLINE_URL, { cache: "reload" }));
+      })
+      .then(function () {
+        if (OFFLINE_SHELL) return installShell();
+      }),
   );
 });
 
@@ -70,10 +210,16 @@ self.addEventListener("activate", function (event) {
   event.waitUntil(
     (async function () {
       const keys = await caches.keys();
+      const keep = [CACHE_NAME];
+      if (OFFLINE_SHELL) {
+        const shell = await currentShellCacheName();
+        if (shell) keep.push(shell);
+      }
+      if (OFFLINE_SHELL || OFFLINE_IMAGE_HOSTS.length) keep.push(IMAGES_CACHE_NAME);
       await Promise.all(
         keys
           .filter(function (key) {
-            return key !== CACHE_NAME;
+            return keep.indexOf(key) === -1;
           })
           .map(function (key) {
             return caches.delete(key);
@@ -88,28 +234,133 @@ self.addEventListener("activate", function (event) {
 });
 
 self.addEventListener("fetch", function (event) {
-  // Only navigations are intercepted. Everything else goes straight to the
-  // network without respondWith.
-  if (event.request.mode !== "navigate") return;
+  // Only navigations are intercepted, plus (offline mode only) build assets and
+  // artwork images. Everything else goes straight to the network without
+  // respondWith.
+  if (event.request.mode !== "navigate") {
+    if (!OFFLINE_SHELL && !OFFLINE_IMAGE_HOSTS.length) return;
+    const method = event.request.method || "GET";
+    if (method !== "GET") return;
+    // A no-store request (the page's session refresh of the shell) is never answered from a
+    // cache: when the network fails it must fail, so the page knows the app is unreachable.
+    if (event.request.cache === "no-store") return;
+    const url = new URL(event.request.url);
 
-  event.respondWith(
-    (async function () {
-      try {
-        const preload = await event.preloadResponse;
-        if (preload) return preload;
-        // A 4xx/5xx or an opaque redirect is passed through as is.
-        return await fetch(event.request);
-      } catch (error) {
-        const cache = await caches.open(CACHE_NAME);
-        const cached = await cache.match(OFFLINE_URL);
-        if (cached) return cached;
-        return new Response(OFFLINE_FALLBACK_HTML, {
-          status: 200,
-          headers: { "content-type": "text/html; charset=utf-8" },
-        });
+    if (OFFLINE_SHELL && url.origin === self.location.origin && url.pathname.startsWith("/_next/static/")) {
+      event.respondWith(
+        (async function () {
+          const name = await currentShellCacheName();
+          if (name) {
+            const cache = await caches.open(name);
+            const cached = await cache.match(event.request.url);
+            if (cached) return cached;
+          }
+          try {
+            return await fetch(event.request);
+          } catch {
+            // Offline and not in the shell: a plain network error for the page, no uncaught rejection here.
+            return Response.error();
+          }
+        })(),
+      );
+      return;
+    }
+
+    // An image of an offline image host through Next's image optimizer (`/_next/image?url=...`):
+    // network first, then the downloaded original (the images cache keeps it under its own URL).
+    const optimizedSource = url.origin === self.location.origin && url.pathname === "/_next/image" ? url.searchParams.get("url") : null;
+    if (optimizedSource && /^https?:/.test(optimizedSource) && isImageHost(optimizedSource)) {
+      event.respondWith(
+        (async function () {
+          try {
+            return await fetch(event.request);
+          } catch {
+            const cache = await caches.open(IMAGES_CACHE_NAME);
+            const cached = await cache.match(optimizedSource);
+            if (cached) return cached;
+            return Response.error();
+          }
+        })(),
+      );
+      return;
+    }
+
+    // Any other same-origin file the offline manifest precached (the device worker and the
+    // SQLite files it loads): network first, the shell cache when the network fails.
+    if (OFFLINE_SHELL && url.origin === self.location.origin) {
+      event.respondWith(
+        (async function () {
+          try {
+            return await fetch(event.request);
+          } catch {
+            const name = await currentShellCacheName();
+            if (name) {
+              const cache = await caches.open(name);
+              const cached = await cache.match(event.request.url);
+              if (cached) return cached;
+            }
+            return Response.error();
+          }
+        })(),
+      );
+      return;
+    }
+
+    if (isImageHost(event.request.url)) {
+      event.respondWith(
+        (async function () {
+          try {
+            return await fetch(event.request);
+          } catch {
+            const cache = await caches.open(IMAGES_CACHE_NAME);
+            const cached = await cache.match(event.request.url);
+            if (cached) return cached;
+            return Response.error();
+          }
+        })(),
+      );
+    }
+    return;
+  }
+
+  let reachedNetwork = false;
+  const answer = (async function () {
+    try {
+      const preload = await event.preloadResponse;
+      if (preload) {
+        reachedNetwork = true;
+        return preload;
       }
-    })(),
-  );
+      // A 4xx/5xx or an opaque redirect is passed through as is.
+      const response = await fetch(event.request);
+      reachedNetwork = true;
+      return response;
+    } catch (error) {
+      if (OFFLINE_SHELL) {
+        const name = await currentShellCacheName();
+        if (name) {
+          const shellCache = await caches.open(name);
+          const shell = await shellCache.match(shellUrlFor(event.request.url));
+          if (shell) return shell;
+        }
+      }
+      const cache = await caches.open(CACHE_NAME);
+      const cached = await cache.match(OFFLINE_URL);
+      if (cached) return cached;
+      return new Response(OFFLINE_FALLBACK_HTML, {
+        status: 200,
+        headers: { "content-type": "text/html; charset=utf-8" },
+      });
+    }
+  })();
+  event.respondWith(answer);
+  if (OFFLINE_SHELL) {
+    event.waitUntil(
+      answer.then(function () {
+        if (reachedNetwork) return maybeRefreshShell();
+      }),
+    );
+  }
 });
 
 self.addEventListener("message", function (event) {

package/src/client/request.ts

@@ -1,6 +1,9 @@
 "use client";
 
 import { ApiData } from "../core/interfaces/ApiData";
+import { isOfflineConfigured } from "../offline/config";
+import { getOfflineState, reachesNetworkWhileOffline, setOfflineState } from "../offline/state";
+import { OFFLINE_REPLAY_HEADER } from "../offline/types";
 
 export interface DirectFetchParams {
   method: string;
@@ -18,6 +21,39 @@ export interface DirectFetchParams {
  * Use this for client-side API calls.
  */
 export async function directFetch(params: DirectFetchParams): Promise<ApiData> {
+  // Offline mode is opt-in (`configureOffline`). Without it nothing below loads or runs. A request
+  // the server runs as an offline replay always goes to the network, and so do the reads and the
+  // change-set request of a reconnect attempt (the session stays offline until its sync succeeds).
+  const offline = isOfflineConfigured() && !hasReplayHeader(params.additionalHeaders);
+  if (offline && !getOfflineState().online && !reachesNetworkWhileOffline(params.method, params.url)) {
+    return answerLocally(params);
+  }
+
+  const response = await fetchFromApi(params);
+
+  if (offline && response.networkError) {
+    setOfflineState({ online: false });
+    return answerLocally(params);
+  }
+  if (offline && response.ok && params.method.toUpperCase() !== "GET") {
+    const { writeThrough } = await import("../offline/write-through");
+    await writeThrough({ method: params.method, url: params.url }, response);
+  }
+
+  return response;
+}
+
+function hasReplayHeader(headers?: Record<string, string>): boolean {
+  if (!headers) return false;
+  return Object.keys(headers).some((key) => key.toLowerCase() === OFFLINE_REPLAY_HEADER);
+}
+
+async function answerLocally(params: DirectFetchParams): Promise<ApiData> {
+  const { localTransport } = await import("../offline/local-transport");
+  return localTransport({ method: params.method, url: params.url, body: params.body, files: params.files });
+}
+
+async function fetchFromApi(params: DirectFetchParams): Promise<ApiData> {
   const response: ApiData = {
     data: undefined,
     ok: false,
@@ -95,6 +131,7 @@ export async function directFetch(params: DirectFetchParams): Promise<ApiData> {
     response.status = 503;
     response.statusText = "Service Unavailable";
     response.data = undefined;
+    response.networkError = true;
   }
 
   return response;

package/src/components/containers/RoundPageContainer.tsx

@@ -486,7 +486,7 @@ export function RoundPageContainer({
                         of label length. */}
                     <TabsList className="flex h-auto w-full flex-col items-stretch gap-0.5 bg-transparent p-0">
                       {ungrouped.map((tab) => (
-                        <TabsTrigger key={tab.label} value={tabValue(tab)} className={railTriggerClass}>
+                        <TabsTrigger key={tabValue(tab)} value={tabValue(tab)} className={railTriggerClass}>
                           {tab.contentLabel ?? tab.label}
                         </TabsTrigger>
                       ))}
@@ -496,7 +496,7 @@ export function RoundPageContainer({
                             {group.label}
                           </MicroLabel>
                           {group.items.map((tab) => (
-                            <TabsTrigger key={tab.label} value={tabValue(tab)} className={railTriggerClass}>
+                            <TabsTrigger key={tabValue(tab)} value={tabValue(tab)} className={railTriggerClass}>
                               {tab.contentLabel ?? tab.label}
                             </TabsTrigger>
                           ))}
@@ -529,7 +529,7 @@ export function RoundPageContainer({
                         </SelectTrigger>
                         <SelectContent>
                           {ungrouped.map((tab) => (
-                            <SelectItem key={tab.label} value={tabValue(tab)}>
+                            <SelectItem key={tabValue(tab)} value={tabValue(tab)}>
                               {tab.contentLabel ?? tab.label}
                             </SelectItem>
                           ))}
@@ -537,7 +537,7 @@ export function RoundPageContainer({
                             <SelectGroup key={group.label}>
                               <SelectLabel>{group.label}</SelectLabel>
                               {group.items.map((tab) => (
-                                <SelectItem key={tab.label} value={tabValue(tab)}>
+                                <SelectItem key={tabValue(tab)} value={tabValue(tab)}>
                                   {tab.contentLabel ?? tab.label}
                                 </SelectItem>
                               ))}
@@ -565,7 +565,7 @@ export function RoundPageContainer({
                         {header}
                         {tabs.map((tab) => (
                           <TabsContent
-                            key={tab.label}
+                            key={tabValue(tab)}
                             value={tabValue(tab)}
                             className={tab.fillHeight ? `flex min-h-0 w-full flex-1 flex-col` : ``}
                           >
@@ -615,7 +615,7 @@ export function RoundPageContainer({
                                 </SelectTrigger>
                                 <SelectContent>
                                   {tabs.map((tab) => (
-                                    <SelectItem key={tab.label} value={tabValue(tab)}>
+                                    <SelectItem key={tabValue(tab)} value={tabValue(tab)}>
                                       {tab.contentLabel ?? tab.label}
                                     </SelectItem>
                                   ))}
@@ -626,7 +626,7 @@ export function RoundPageContainer({
                             <div className="p-4">
                               <TabsList data-help="page.tabs">
                                 {tabs.map((tab) => (
-                                  <TabsTrigger key={tab.label} value={tabValue(tab)} className="px-4">
+                                  <TabsTrigger key={tabValue(tab)} value={tabValue(tab)} className="px-4">
                                     {tab.contentLabel ?? tab.label}
                                   </TabsTrigger>
                                 ))}
@@ -642,7 +642,7 @@ export function RoundPageContainer({
                           >
                             {tabs.map((tab) => (
                               <TabsContent
-                                key={tab.label}
+                                key={tabValue(tab)}
                                 value={tabValue(tab)}
                                 className={tab.fillHeight ? `flex flex-1 min-h-0 w-full flex-col` : `pb-20`}
                               >

package/src/components/editors/BlockNoteEditor.tsx

@@ -821,11 +821,21 @@ export default function BlockNoteEditor({
   // initialContent is just an echo of our own emission (form-controlled flow).
   const lastEmittedHashRef = useRef<string | null>(null);
 
+  // Whether the parent's copy of the text is empty: the content it handed in, then each change
+  // reported to it. A change from empty to still empty is not reported: BlockNote emits one when an
+  // empty editor mounts (its trailing empty paragraph), and reported it became a save of nothing on
+  // every view of a page with an empty field.
+  const processedContentRef = useRef<any[]>([]);
+  const parentKnowsEmptyRef = useRef<boolean | null>(null);
+
   const handleChange = useCallback(async () => {
     if (!onChange) return;
     const newBlocks = editor.document;
     lastEmittedHashRef.current = JSON.stringify(newBlocks);
     const isEmpty = isDocumentEmpty(newBlocks);
+    const wasEmpty = parentKnowsEmptyRef.current ?? isDocumentEmpty(processedContentRef.current);
+    if (isEmpty && wasEmpty) return;
+    parentKnowsEmptyRef.current = isEmpty;
 
     function hasUnresolvedDiffsRecursive(block: any): boolean {
       if (!block || typeof block !== "object") return false;
@@ -880,6 +890,8 @@ export default function BlockNoteEditor({
     onChange(newBlocks, isEmpty, hasUnresolvedDiff);
   }, [editor, onChange, id, acceptedChanges, rejectedChanges]);
 
+  processedContentRef.current = processedContent as any[];
+
   // Utility: deep equality for arrays of blocks
   const areBlocksEqual = (a: any[], b: any[]): boolean => {
     return JSON.stringify(a) === JSON.stringify(b);
@@ -912,6 +924,8 @@ export default function BlockNoteEditor({
     if (collaboration) return;
     const hash = JSON.stringify(processedContent);
     if (previousContentHashRef.current === hash) return; // no changes
+    // New content from the parent: that is now the text it knows.
+    parentKnowsEmptyRef.current = isDocumentEmpty(processedContent as any[]);
     // Skip replaceBlocks when the new initialContent is just an echo of what
     // the editor itself emitted. Without this, a form-controlled parent
     // (FormBlockNote) round-trips field.value back as initialContent on every