@decocms/tanstack 7.59.0 → 7.60.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +4 -4
- package/src/hooks/DecoPageRenderer.tsx +64 -28
- package/src/hooks/NavigationProgress.test.tsx +58 -0
- package/src/hooks/NavigationProgress.tsx +45 -3
- package/src/hooks/deferredObserverTiming.test.tsx +91 -0
- package/src/routes/cmsRoute.test.ts +56 -0
- package/src/routes/cmsRoute.ts +53 -15
- package/src/routes/pageUrl.ts +5 -4
- package/src/sdk/workerEntry.ts +7 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@decocms/tanstack",
|
|
3
|
-
"version": "7.
|
|
3
|
+
"version": "7.60.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Deco framework binding for TanStack Start + Cloudflare Workers",
|
|
6
6
|
"repository": {
|
|
@@ -27,9 +27,9 @@
|
|
|
27
27
|
"lint:unused": "knip"
|
|
28
28
|
},
|
|
29
29
|
"dependencies": {
|
|
30
|
-
"@decocms/blocks": "7.
|
|
31
|
-
"@decocms/blocks-admin": "7.
|
|
32
|
-
"@decocms/blocks-cli": "7.
|
|
30
|
+
"@decocms/blocks": "7.60.0",
|
|
31
|
+
"@decocms/blocks-admin": "7.60.0",
|
|
32
|
+
"@decocms/blocks-cli": "7.60.0",
|
|
33
33
|
"@deco-cx/warp-node": "^0.3.16",
|
|
34
34
|
"fast-json-patch": "^3.1.0",
|
|
35
35
|
"ws": "^8.18.0"
|
|
@@ -307,9 +307,9 @@ function DeferredSectionWrapper({
|
|
|
307
307
|
const el = ref.current;
|
|
308
308
|
if (!el) return;
|
|
309
309
|
|
|
310
|
-
|
|
310
|
+
const key = stableKey;
|
|
311
|
+
const load = () => {
|
|
311
312
|
triggered.current = true;
|
|
312
|
-
const key0 = stableKey;
|
|
313
313
|
loadFn({
|
|
314
314
|
component: deferred.component,
|
|
315
315
|
pagePath,
|
|
@@ -317,37 +317,60 @@ function DeferredSectionWrapper({
|
|
|
317
317
|
index: deferred.index,
|
|
318
318
|
})
|
|
319
319
|
.then((result) => {
|
|
320
|
-
if (result) deferredSectionCache.set(
|
|
320
|
+
if (result) deferredSectionCache.set(key, { section: result, ts: Date.now() });
|
|
321
321
|
setSection(result);
|
|
322
322
|
})
|
|
323
323
|
.catch((e) => setError(e));
|
|
324
|
+
};
|
|
325
|
+
|
|
326
|
+
if (typeof IntersectionObserver === "undefined") {
|
|
327
|
+
load();
|
|
324
328
|
return;
|
|
325
329
|
}
|
|
326
330
|
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
)
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
331
|
+
let observer: IntersectionObserver | undefined;
|
|
332
|
+
const startObserving = () => {
|
|
333
|
+
if (triggered.current) return;
|
|
334
|
+
observer = new IntersectionObserver(
|
|
335
|
+
([entry]) => {
|
|
336
|
+
if (entry?.isIntersecting && !triggered.current) {
|
|
337
|
+
observer?.disconnect();
|
|
338
|
+
load();
|
|
339
|
+
}
|
|
340
|
+
},
|
|
341
|
+
{ rootMargin: "300px" },
|
|
342
|
+
);
|
|
343
|
+
observer.observe(el);
|
|
344
|
+
};
|
|
345
|
+
|
|
346
|
+
// Wait one frame before observing, so the router's scroll reset lands first.
|
|
347
|
+
//
|
|
348
|
+
// On a client (SPA) navigation the scroll position is still wherever the
|
|
349
|
+
// user left the PREVIOUS page when this effect runs. TanStack resets it from
|
|
350
|
+
// the `onRendered` event, which is emitted in a `useLayoutEffect`
|
|
351
|
+
// (react-router's `OnRendered`) that depends on the `resolvedLocation` store
|
|
352
|
+
// — and that store is written from ANOTHER `useLayoutEffect` (Transitioner).
|
|
353
|
+
// So the reset necessarily lands one commit after the one that mounts these
|
|
354
|
+
// skeletons, and React flushes this commit's passive effects before starting
|
|
355
|
+
// that follow-up render. Verified ordering: observe → scroll reset.
|
|
356
|
+
//
|
|
357
|
+
// Observing synchronously therefore evaluates intersection against the stale
|
|
358
|
+
// scroll offset: a user navigating from the bottom of a long page has every
|
|
359
|
+
// skeleton "in view" at once, so every deferred section fires its serverFn
|
|
360
|
+
// POST simultaneously on commit — the exact thundering herd deferral exists
|
|
361
|
+
// to avoid. One frame is enough to let the reset apply.
|
|
362
|
+
//
|
|
363
|
+
// `triggered` is re-checked inside, so a section that resolved from cache in
|
|
364
|
+
// the meantime never starts an observer.
|
|
365
|
+
if (typeof requestAnimationFrame === "undefined") {
|
|
366
|
+
startObserving();
|
|
367
|
+
return () => observer?.disconnect();
|
|
368
|
+
}
|
|
369
|
+
const raf = requestAnimationFrame(startObserving);
|
|
370
|
+
return () => {
|
|
371
|
+
cancelAnimationFrame(raf);
|
|
372
|
+
observer?.disconnect();
|
|
373
|
+
};
|
|
351
374
|
}, [deferred.component, deferred.index, deferred.propsHash, pagePath, pageUrl, section, loadFn]);
|
|
352
375
|
|
|
353
376
|
if (error) {
|
|
@@ -495,6 +518,11 @@ interface Props {
|
|
|
495
518
|
* Unawaited promises for deferred sections, keyed by `d_<index>`.
|
|
496
519
|
* Created by the route loader for TanStack native SSR streaming.
|
|
497
520
|
* When provided, takes precedence over `loadDeferredSectionFn`.
|
|
521
|
+
*
|
|
522
|
+
* SSR-ONLY: promises cannot cross the server-fn JSON boundary, so a client
|
|
523
|
+
* (SPA) navigation never receives them. Any site that defers sections needs
|
|
524
|
+
* `loadDeferredSectionFn` wired regardless — it is the only path that works
|
|
525
|
+
* for both SSR and client nav.
|
|
498
526
|
*/
|
|
499
527
|
deferredPromises?: Record<string, Promise<ResolvedSection | null>>;
|
|
500
528
|
pagePath?: string;
|
|
@@ -509,7 +537,15 @@ interface Props {
|
|
|
509
537
|
device?: Device;
|
|
510
538
|
loadingFallback?: ReactNode;
|
|
511
539
|
errorFallback?: ReactNode;
|
|
512
|
-
/**
|
|
540
|
+
/**
|
|
541
|
+
* IntersectionObserver-driven loader for deferred sections — wire this to
|
|
542
|
+
* `deferredSectionLoader` from `@decocms/tanstack`.
|
|
543
|
+
*
|
|
544
|
+
* NOT deprecated: `deferredPromises` only covers SSR (promises can't be
|
|
545
|
+
* serialized through a server fn), so this is the only deferred-resolution
|
|
546
|
+
* path available on a client (SPA) navigation. Without it, deferred sections
|
|
547
|
+
* on a SPA transition render a skeleton that never resolves.
|
|
548
|
+
*/
|
|
513
549
|
loadDeferredSectionFn?: (data: {
|
|
514
550
|
component: string;
|
|
515
551
|
rawProps?: Record<string, unknown>;
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
import { renderToStaticMarkup } from "react-dom/server";
|
|
2
|
+
import { describe, expect, it, vi } from "vitest";
|
|
3
|
+
|
|
4
|
+
// The component only needs the router's isLoading flag.
|
|
5
|
+
let isLoading = true;
|
|
6
|
+
vi.mock("@tanstack/react-router", () => ({
|
|
7
|
+
useRouterState: ({ select }: { select: (s: { isLoading: boolean }) => unknown }) =>
|
|
8
|
+
select({ isLoading }),
|
|
9
|
+
}));
|
|
10
|
+
|
|
11
|
+
const { NavigationProgress } = await import("./NavigationProgress");
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* The bug this guards: the bar used to be painted with the Tailwind utility
|
|
15
|
+
* `bg-brand-primary-500`. That token is a *site* concern — framework code
|
|
16
|
+
* cannot assume it exists. On a Tailwind v4 theme that resets
|
|
17
|
+
* `--color-*: initial` the utility is never generated, so the class resolves to
|
|
18
|
+
* nothing and the bar is fully transparent: an invisible progress indicator, in
|
|
19
|
+
* production, with no build error and nothing in the console.
|
|
20
|
+
*
|
|
21
|
+
* The fix paints through an inline custom-property expression, which a CSS build
|
|
22
|
+
* cannot elide. It has to satisfy BOTH directions at once: sites that never
|
|
23
|
+
* defined the token must still see a bar, and sites that DID must keep their
|
|
24
|
+
* brand color rather than silently dropping to black — hence the var-with-
|
|
25
|
+
* fallback rather than a bare `currentColor`.
|
|
26
|
+
*/
|
|
27
|
+
describe("NavigationProgress — visibility does not depend on site color tokens", () => {
|
|
28
|
+
it("paints via inline style, never a site-defined Tailwind color utility", () => {
|
|
29
|
+
isLoading = true;
|
|
30
|
+
const html = renderToStaticMarkup(<NavigationProgress />);
|
|
31
|
+
|
|
32
|
+
expect(html).not.toMatch(/bg-brand-/);
|
|
33
|
+
expect(html).toMatch(/background-color:\s*currentColor/);
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
it("keeps the brand token when the site defines it, and falls back when it does not", () => {
|
|
37
|
+
isLoading = true;
|
|
38
|
+
const html = renderToStaticMarkup(<NavigationProgress />);
|
|
39
|
+
|
|
40
|
+
// Both halves matter: the var preserves branding for sites where the old
|
|
41
|
+
// utility worked, the fallback is what makes it visible for those where it
|
|
42
|
+
// silently did not.
|
|
43
|
+
expect(html).toContain("--color-brand-primary-500");
|
|
44
|
+
expect(html).toMatch(/var\(--color-brand-primary-500,\s*currentColor\)/);
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
it("accepts an explicit color so a site can brand it without that token name", () => {
|
|
48
|
+
isLoading = true;
|
|
49
|
+
const html = renderToStaticMarkup(<NavigationProgress color="#ff0080" />);
|
|
50
|
+
expect(html).toContain("#ff0080");
|
|
51
|
+
expect(html).not.toContain("--color-brand-primary-500");
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
it("renders nothing when the router is idle", () => {
|
|
55
|
+
isLoading = false;
|
|
56
|
+
expect(renderToStaticMarkup(<NavigationProgress />)).toBe("");
|
|
57
|
+
});
|
|
58
|
+
});
|
|
@@ -5,17 +5,59 @@ const PROGRESS_CSS = `
|
|
|
5
5
|
.nav-progress-bar { animation: progressSlide 1s ease-in-out infinite; }
|
|
6
6
|
`;
|
|
7
7
|
|
|
8
|
+
/**
|
|
9
|
+
* Brand token when the site defines it, inherited text color when it does not.
|
|
10
|
+
*
|
|
11
|
+
* The bar used to be painted with the Tailwind utility `bg-brand-primary-500`.
|
|
12
|
+
* That token is a *site* concern, and framework code cannot assume it exists: on
|
|
13
|
+
* a Tailwind v4 theme that resets `--color-*: initial` the utility is never
|
|
14
|
+
* generated, so the class resolved to nothing and the bar rendered fully
|
|
15
|
+
* transparent — an invisible progress indicator, in production, with no build
|
|
16
|
+
* error and nothing in the console.
|
|
17
|
+
*
|
|
18
|
+
* A CSS custom property with a fallback fixes that without regressing the sites
|
|
19
|
+
* where it already worked: they keep their brand color (Tailwind v4 emits
|
|
20
|
+
* `--color-brand-primary-500` for a `brand-primary` palette entry), and
|
|
21
|
+
* everyone else falls back to `currentColor` instead of nothing. Unlike a
|
|
22
|
+
* utility class, neither half can be dropped by a CSS build.
|
|
23
|
+
*/
|
|
24
|
+
const DEFAULT_COLOR = "var(--color-brand-primary-500, currentColor)";
|
|
25
|
+
|
|
26
|
+
export interface NavigationProgressProps {
|
|
27
|
+
/**
|
|
28
|
+
* Bar color. Any CSS color or custom-property expression. Defaults to
|
|
29
|
+
* {@link DEFAULT_COLOR} — the site's `brand-primary-500` token when defined,
|
|
30
|
+
* otherwise the inherited text color. Pass an explicit value to brand the bar
|
|
31
|
+
* without relying on that token name.
|
|
32
|
+
*/
|
|
33
|
+
color?: string;
|
|
34
|
+
}
|
|
35
|
+
|
|
8
36
|
/**
|
|
9
37
|
* Top-of-page loading bar that appears during SPA navigation.
|
|
10
38
|
* Uses the router's isLoading state — no extra dependencies.
|
|
11
39
|
*/
|
|
12
|
-
export function NavigationProgress() {
|
|
40
|
+
export function NavigationProgress({ color = DEFAULT_COLOR }: NavigationProgressProps = {}) {
|
|
13
41
|
const isLoading = useRouterState({ select: (s) => s.isLoading });
|
|
14
42
|
if (!isLoading) return null;
|
|
15
43
|
return (
|
|
16
|
-
<div
|
|
44
|
+
<div
|
|
45
|
+
className="fixed top-0 left-0 right-0 z-[9999] h-1 overflow-hidden"
|
|
46
|
+
style={{ color }}
|
|
47
|
+
role="progressbar"
|
|
48
|
+
aria-label="Carregando página"
|
|
49
|
+
>
|
|
17
50
|
<style dangerouslySetInnerHTML={{ __html: PROGRESS_CSS }} />
|
|
18
|
-
|
|
51
|
+
{/* Track and bar are siblings so the track's 20% alpha does not
|
|
52
|
+
inherit onto the bar (opacity applies to the whole subtree). */}
|
|
53
|
+
<div
|
|
54
|
+
className="absolute inset-0"
|
|
55
|
+
style={{ backgroundColor: "currentColor", opacity: 0.2 }}
|
|
56
|
+
/>
|
|
57
|
+
<div
|
|
58
|
+
className="nav-progress-bar absolute inset-y-0 left-0 w-1/3 rounded-full"
|
|
59
|
+
style={{ backgroundColor: "currentColor" }}
|
|
60
|
+
/>
|
|
19
61
|
</div>
|
|
20
62
|
);
|
|
21
63
|
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
import { act, useEffect, useLayoutEffect, useState } from "react";
|
|
2
|
+
import { createRoot } from "react-dom/client";
|
|
3
|
+
import { describe, expect, it } from "vitest";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Guards the frame gate in `DeferredSectionWrapper`'s IntersectionObserver
|
|
7
|
+
* effect (`DecoPageRenderer.tsx`).
|
|
8
|
+
*
|
|
9
|
+
* Enabling deferral on client navigation made a latent ordering problem
|
|
10
|
+
* reachable. On a SPA transition the scroll position is still wherever the user
|
|
11
|
+
* left the previous page when the new page's skeletons mount. TanStack resets it
|
|
12
|
+
* from the `onRendered` event, emitted by a `useLayoutEffect` in react-router's
|
|
13
|
+
* `OnRendered` that depends on the `resolvedLocation` store — which is itself
|
|
14
|
+
* written from another `useLayoutEffect` (`Transitioner`). The reset therefore
|
|
15
|
+
* lands one commit AFTER the mount commit, and React flushes the mount commit's
|
|
16
|
+
* passive effects before starting that follow-up render.
|
|
17
|
+
*
|
|
18
|
+
* Net effect without a gate: the observer evaluates intersection against the
|
|
19
|
+
* stale offset, so a user navigating from the bottom of a long page has every
|
|
20
|
+
* skeleton in view simultaneously and every deferred section fires its serverFn
|
|
21
|
+
* POST at once — the thundering herd deferral exists to avoid.
|
|
22
|
+
*
|
|
23
|
+
* This models that exact effect topology rather than mounting the real router,
|
|
24
|
+
* because the ordering is a property of React's commit/flush sequence, not of
|
|
25
|
+
* TanStack. If React ever changes it so passive effects run after a
|
|
26
|
+
* layout-effect-triggered re-render, the first case flips and the gate can go.
|
|
27
|
+
*/
|
|
28
|
+
function runOrdering(gate: "none" | "raf") {
|
|
29
|
+
const order: string[] = [];
|
|
30
|
+
|
|
31
|
+
/** Stands in for TanStack's Transitioner writing `resolvedLocation`. */
|
|
32
|
+
function Transitioner({ setResolved }: { setResolved: (n: number) => void }) {
|
|
33
|
+
useLayoutEffect(() => setResolved(1), [setResolved]);
|
|
34
|
+
return null;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** Stands in for `OnRendered` → `onRendered` → scroll-restoration reset. */
|
|
38
|
+
function OnRendered({ resolved }: { resolved: number }) {
|
|
39
|
+
useLayoutEffect(() => {
|
|
40
|
+
if (resolved > 0) order.push("SCROLL_RESET");
|
|
41
|
+
}, [resolved]);
|
|
42
|
+
return null;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** Stands in for DeferredSectionWrapper's observer effect. */
|
|
46
|
+
function DeferredWrapper() {
|
|
47
|
+
useEffect(() => {
|
|
48
|
+
const observe = () => order.push("OBSERVE");
|
|
49
|
+
if (gate === "none") {
|
|
50
|
+
observe();
|
|
51
|
+
return;
|
|
52
|
+
}
|
|
53
|
+
const raf = requestAnimationFrame(observe);
|
|
54
|
+
return () => cancelAnimationFrame(raf);
|
|
55
|
+
}, []);
|
|
56
|
+
return null;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function App() {
|
|
60
|
+
const [resolved, setResolved] = useState(0);
|
|
61
|
+
return (
|
|
62
|
+
<>
|
|
63
|
+
{/* Deliberately first: children flush before the root's own effects. */}
|
|
64
|
+
<DeferredWrapper />
|
|
65
|
+
<Transitioner setResolved={setResolved} />
|
|
66
|
+
<OnRendered resolved={resolved} />
|
|
67
|
+
</>
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
const el = document.createElement("div");
|
|
72
|
+
document.body.appendChild(el);
|
|
73
|
+
act(() => {
|
|
74
|
+
createRoot(el).render(<App />);
|
|
75
|
+
});
|
|
76
|
+
return order;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
describe("deferred observer vs router scroll reset", () => {
|
|
80
|
+
it("observing synchronously loses the race — this is why the gate exists", () => {
|
|
81
|
+
// If this ever reports SCROLL_RESET first, React's flush order changed and
|
|
82
|
+
// the requestAnimationFrame gate in DecoPageRenderer is dead weight.
|
|
83
|
+
expect(runOrdering("none")).toEqual(["OBSERVE", "SCROLL_RESET"]);
|
|
84
|
+
});
|
|
85
|
+
|
|
86
|
+
it("one frame is enough for the scroll reset to land first", () => {
|
|
87
|
+
// rAF does not run inside act(), so the reset is the only thing recorded —
|
|
88
|
+
// i.e. observation is strictly after it, which is the point.
|
|
89
|
+
expect(runOrdering("raf")).toEqual(["SCROLL_RESET"]);
|
|
90
|
+
});
|
|
91
|
+
});
|
|
@@ -2,6 +2,9 @@ import { registerCacheableSections, registerSectionLoader } from "@decocms/block
|
|
|
2
2
|
import type { ResolvedSection } from "@decocms/blocks/cms";
|
|
3
3
|
import { describe, expect, it } from "vitest";
|
|
4
4
|
import {
|
|
5
|
+
CmsPagePendingFallback,
|
|
6
|
+
cmsHomeRouteConfig,
|
|
7
|
+
cmsRouteConfig,
|
|
5
8
|
parseLoadCmsHomePageInput,
|
|
6
9
|
parseLoadCmsPageInput,
|
|
7
10
|
runSectionLoadersWithSeo,
|
|
@@ -98,3 +101,56 @@ describe("runSectionLoadersWithSeo (#355)", () => {
|
|
|
98
101
|
expect(enrichedSeoSection).toBeNull();
|
|
99
102
|
});
|
|
100
103
|
});
|
|
104
|
+
|
|
105
|
+
// ---------------------------------------------------------------------------
|
|
106
|
+
// Pending UI defaults
|
|
107
|
+
// ---------------------------------------------------------------------------
|
|
108
|
+
//
|
|
109
|
+
// There is deliberately NO default pendingComponent. Setting one turns every
|
|
110
|
+
// navigation slower than `pendingMs` (200ms) into a page → skeleton → page swap
|
|
111
|
+
// held for at least `pendingMinMs` (300ms). Deferral pulls most navigations into
|
|
112
|
+
// the 200–600ms band, i.e. exactly the window where that swap costs more than it
|
|
113
|
+
// buys, and this is a catch-all route, so one skeleton shape would have to serve
|
|
114
|
+
// PDP, PLP, search, and institutional pages alike. Keeping the previous page on
|
|
115
|
+
// screen until the new one commits is the better default; a site that wants a
|
|
116
|
+
// skeleton opts in per-shape.
|
|
117
|
+
//
|
|
118
|
+
// `pendingMs`/`pendingMinMs` DO keep defaults — they are inert without a
|
|
119
|
+
// pendingComponent, and they also govern a site-provided one.
|
|
120
|
+
|
|
121
|
+
describe("cmsRouteConfig / cmsHomeRouteConfig — pending UI defaults", () => {
|
|
122
|
+
const base = { siteName: "Loja", defaultTitle: "Loja" };
|
|
123
|
+
|
|
124
|
+
it("ships NO default pendingComponent — the previous page stays until commit", () => {
|
|
125
|
+
expect("pendingComponent" in cmsRouteConfig(base)).toBe(false);
|
|
126
|
+
expect("pendingComponent" in cmsHomeRouteConfig({ defaultTitle: "Loja" })).toBe(false);
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
it("honors a site-provided pendingComponent on both route configs", () => {
|
|
130
|
+
const custom = () => null;
|
|
131
|
+
expect(cmsRouteConfig({ ...base, pendingComponent: custom }).pendingComponent).toBe(custom);
|
|
132
|
+
expect(
|
|
133
|
+
cmsHomeRouteConfig({ defaultTitle: "Loja", pendingComponent: custom }).pendingComponent,
|
|
134
|
+
).toBe(custom);
|
|
135
|
+
});
|
|
136
|
+
|
|
137
|
+
it("treats an explicit null the same as omitting it", () => {
|
|
138
|
+
expect("pendingComponent" in cmsRouteConfig({ ...base, pendingComponent: null })).toBe(false);
|
|
139
|
+
expect(
|
|
140
|
+
"pendingComponent" in cmsHomeRouteConfig({ defaultTitle: "Loja", pendingComponent: null }),
|
|
141
|
+
).toBe(false);
|
|
142
|
+
});
|
|
143
|
+
|
|
144
|
+
it("still exports CmsPagePendingFallback as an opt-in starting point", () => {
|
|
145
|
+
expect(typeof CmsPagePendingFallback).toBe("function");
|
|
146
|
+
expect(
|
|
147
|
+
cmsRouteConfig({ ...base, pendingComponent: CmsPagePendingFallback }).pendingComponent,
|
|
148
|
+
).toBe(CmsPagePendingFallback);
|
|
149
|
+
});
|
|
150
|
+
|
|
151
|
+
it("keeps the documented pendingMs / pendingMinMs defaults", () => {
|
|
152
|
+
const cfg = cmsRouteConfig(base);
|
|
153
|
+
expect(cfg.pendingMs).toBe(200);
|
|
154
|
+
expect(cfg.pendingMinMs).toBe(300);
|
|
155
|
+
});
|
|
156
|
+
});
|
package/src/routes/cmsRoute.ts
CHANGED
|
@@ -289,13 +289,18 @@ export const loadCmsPage = createServerFn({ method: "GET" })
|
|
|
289
289
|
// Using basePath only caused /s?q=a and /s?q=b to share one promise,
|
|
290
290
|
// returning wrong/empty results for search and filtered PLPs.
|
|
291
291
|
//
|
|
292
|
-
//
|
|
293
|
-
// for the
|
|
294
|
-
//
|
|
295
|
-
//
|
|
296
|
-
//
|
|
297
|
-
//
|
|
298
|
-
//
|
|
292
|
+
// SSR and client-nav produce the same eager/deferred split now, so the
|
|
293
|
+
// original reason for the `__nav:` bucket — a client-nav request must never
|
|
294
|
+
// inherit an SSR response's deferredSections (#277) — no longer applies. It
|
|
295
|
+
// is kept anyway, because this map is module-global and the payload it
|
|
296
|
+
// shares carries `pageUrl`, `flags`, and `device` derived from whichever
|
|
297
|
+
// request won the race. That cross-request bleed is pre-existing and wider
|
|
298
|
+
// than this bucket (two concurrent same-path requests already collide on
|
|
299
|
+
// cookies/UA/geo), but SSR and client-nav are exactly the pair whose
|
|
300
|
+
// `derivePageUrl` inputs differ most, so collapsing them would widen a
|
|
301
|
+
// known hole for no gain. `resolveGlobals` is part of the key for the same
|
|
302
|
+
// reason: a `resolveGlobals: false` request must not share a promise with a
|
|
303
|
+
// `resolveGlobals: true` one.
|
|
299
304
|
const clientNav = isClientNavigation(fullPath, getRequestUrl());
|
|
300
305
|
const inflightKey =
|
|
301
306
|
(clientNav ? `__nav:${fullPath}` : fullPath) + (resolveGlobals ? "" : "|noGlobals");
|
|
@@ -392,9 +397,16 @@ export const loadCmsHomePage = createServerFn({ method: "GET" })
|
|
|
392
397
|
// ---------------------------------------------------------------------------
|
|
393
398
|
|
|
394
399
|
/**
|
|
395
|
-
*
|
|
396
|
-
*
|
|
397
|
-
*
|
|
400
|
+
* Resolves + enriches a single deferred section on demand, server-side.
|
|
401
|
+
*
|
|
402
|
+
* This is the deferred-resolution path for BOTH the initial SSR document and
|
|
403
|
+
* client (SPA) navigations — `deferredPromises`/TanStack native streaming is
|
|
404
|
+
* SSR-only, because promises cannot cross the server-fn JSON boundary. It
|
|
405
|
+
* rebuilds `MatcherContext` from the real incoming request (url/path/cookies/
|
|
406
|
+
* request), so the second hop sees the same per-request state the first one did
|
|
407
|
+
* (the `deco_segment` cookie set by the page response is already present, so
|
|
408
|
+
* sticky A/B decisions stay consistent — `flags` is intentionally left unset
|
|
409
|
+
* here: this response must not re-roll or re-persist the cohort cookie).
|
|
398
410
|
*/
|
|
399
411
|
export const loadDeferredSection = createServerFn({ method: "POST" })
|
|
400
412
|
.inputValidator(
|
|
@@ -558,8 +570,21 @@ export interface CmsRouteOptions {
|
|
|
558
570
|
* Defaults to `["skuId"]` — variant selection is client-side only.
|
|
559
571
|
*/
|
|
560
572
|
ignoreSearchParams?: string[];
|
|
561
|
-
/**
|
|
562
|
-
|
|
573
|
+
/**
|
|
574
|
+
* Pending component shown during SPA navigation while the route loader runs.
|
|
575
|
+
*
|
|
576
|
+
* NO DEFAULT, deliberately. With none set, TanStack keeps the previous page on
|
|
577
|
+
* screen until the new one commits — which at the sub-second latencies this
|
|
578
|
+
* route now sees is usually the better feel. Setting one buys feedback on a
|
|
579
|
+
* slow navigation at the cost of a page → skeleton → page swap on every
|
|
580
|
+
* navigation slower than {@link pendingMs} (held for at least
|
|
581
|
+
* {@link pendingMinMs}), and this is a *catch-all* route, so one skeleton
|
|
582
|
+
* shape has to serve PDP, PLP, search, and institutional pages alike.
|
|
583
|
+
* {@link CmsPagePendingFallback} is exported as a starting point; prefer a
|
|
584
|
+
* per-shape skeleton, or `NavigationProgress` (`@decocms/tanstack`) for
|
|
585
|
+
* feedback that does not replace the page at all.
|
|
586
|
+
*/
|
|
587
|
+
pendingComponent?: (() => any) | null;
|
|
563
588
|
/**
|
|
564
589
|
* Custom error boundary rendered when the loader / page resolution throws.
|
|
565
590
|
* Defaults to {@link CmsPageErrorFallback} (branded "instability" page with a
|
|
@@ -571,12 +596,23 @@ export interface CmsRouteOptions {
|
|
|
571
596
|
* Delay (ms) before showing the pending component during SPA navigation.
|
|
572
597
|
* If the loader resolves before this threshold, no pending UI is shown.
|
|
573
598
|
* Prevents skeleton flash on fast cache-hit navigations. Default: 200.
|
|
599
|
+
* Inert unless {@link pendingComponent} is set.
|
|
600
|
+
*
|
|
601
|
+
* This is a *catch-all* route, so the same value covers a sub-100ms PLP facet
|
|
602
|
+
* toggle and a cold PDP. Raising it only DELAYS the skeleton on the slow
|
|
603
|
+
* navigation (a 1s `pendingMs` still shows it on a 2s nav) — it does not
|
|
604
|
+
* suppress it. Use {@link pendingMinMs} for the flicker case where the loader
|
|
605
|
+
* lands just after the threshold.
|
|
574
606
|
*/
|
|
575
607
|
pendingMs?: number;
|
|
576
608
|
/**
|
|
577
609
|
* Minimum display time (ms) for the pending component once shown.
|
|
578
610
|
* Prevents jarring flash when data arrives shortly after the threshold.
|
|
579
|
-
* Default: 300.
|
|
611
|
+
* Default: 300. Inert unless {@link pendingComponent} is set.
|
|
612
|
+
*
|
|
613
|
+
* Independent of {@link pendingMs}, and applied after it: worst-case a
|
|
614
|
+
* navigation is held for `pendingMs + pendingMinMs` of visible skeleton
|
|
615
|
+
* before the new page commits.
|
|
580
616
|
*/
|
|
581
617
|
pendingMinMs?: number;
|
|
582
618
|
/**
|
|
@@ -905,7 +941,8 @@ export function cmsHomeRouteConfig(options: {
|
|
|
905
941
|
defaultDescription?: string;
|
|
906
942
|
/** Site name for OG title composition. Defaults to defaultTitle. */
|
|
907
943
|
siteName?: string;
|
|
908
|
-
pendingComponent
|
|
944
|
+
/** See `CmsRouteOptions.pendingComponent` — no default, deliberately. */
|
|
945
|
+
pendingComponent?: (() => any) | null;
|
|
909
946
|
/** Delay (ms) before showing pending component. Default: 200. */
|
|
910
947
|
pendingMs?: number;
|
|
911
948
|
/** Minimum display time (ms) for pending component. Default: 300. */
|
|
@@ -919,6 +956,7 @@ export function cmsHomeRouteConfig(options: {
|
|
|
919
956
|
defaultTitle,
|
|
920
957
|
defaultDescription,
|
|
921
958
|
siteName,
|
|
959
|
+
pendingComponent,
|
|
922
960
|
pendingMs = 200,
|
|
923
961
|
pendingMinMs = 300,
|
|
924
962
|
errorComponent = CmsPageErrorFallback,
|
|
@@ -939,7 +977,7 @@ export function cmsHomeRouteConfig(options: {
|
|
|
939
977
|
// See cmsRouteConfig loader for rationale.
|
|
940
978
|
return page;
|
|
941
979
|
},
|
|
942
|
-
...(
|
|
980
|
+
...(pendingComponent ? { pendingComponent } : {}),
|
|
943
981
|
pendingMs,
|
|
944
982
|
pendingMinMs,
|
|
945
983
|
errorComponent,
|
package/src/routes/pageUrl.ts
CHANGED
|
@@ -36,10 +36,11 @@ export function derivePageUrl(fullPath: string, serverUrl: URL): string {
|
|
|
36
36
|
* `serverUrl.pathname` is NOT the page path. On a real document request (SSR /
|
|
37
37
|
* full reload, including bots) `serverUrl.pathname === basePath`.
|
|
38
38
|
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
41
|
-
*
|
|
42
|
-
*
|
|
39
|
+
* This does NOT gate section deferral: a client nav gets the same eager/deferred
|
|
40
|
+
* split as SSR, because the route loader is blocking and awaiting the below-fold
|
|
41
|
+
* sections freezes the transition. Callers use it to rebuild the real page URL
|
|
42
|
+
* (`derivePageUrl`) and to tell a SPA nav apart from a genuine AJAX consumer
|
|
43
|
+
* (`isProgrammaticFetch`) — both send `Sec-Fetch-Dest: empty`.
|
|
43
44
|
*
|
|
44
45
|
* Mirrors the `serverUrl.pathname === basePath` comparison `derivePageUrl`
|
|
45
46
|
* already relies on, so the two stay consistent and we avoid hardcoding the
|
package/src/sdk/workerEntry.ts
CHANGED
|
@@ -1368,8 +1368,13 @@ export function createDecoWorkerEntry(
|
|
|
1368
1368
|
// bucket so a fetch-triggered eager response never poisons the navigation
|
|
1369
1369
|
// (deferred) entry, and vice-versa. MUST use the same `Sec-Fetch-Dest:
|
|
1370
1370
|
// empty` signal as isProgrammaticFetch so the key and render decisions can't
|
|
1371
|
-
// diverge. `/_serverFn` (SPA-nav data) is excluded: it
|
|
1372
|
-
//
|
|
1371
|
+
// diverge. `/_serverFn` (SPA-nav data) is excluded: it sends the same
|
|
1372
|
+
// `Sec-Fetch-Dest: empty` but is NOT a programmatic fetch — it renders
|
|
1373
|
+
// through DecoPageRenderer and so keeps the same deferred split as the
|
|
1374
|
+
// document (isProgrammaticFetch bails on isClientNavigation for the same
|
|
1375
|
+
// reason). It needs no bucket of its own here: its cache key is the
|
|
1376
|
+
// `/_serverFn/...` pathname + canonicalized payload, which can never
|
|
1377
|
+
// collide with a document entry.
|
|
1373
1378
|
const secFetchDest = request.headers.get("sec-fetch-dest");
|
|
1374
1379
|
const isServerFnPath =
|
|
1375
1380
|
url.pathname.startsWith("/_serverFn/") || url.pathname.startsWith("/_server/");
|