cursedbelt 5.20.0 → 5.22.0

package/src/react/usePagedList.ts

@@ -1,4 +1,5 @@
-import { type QueryKey, useInfiniteQuery } from '@tanstack/react-query';
+import { keepPreviousData, type QueryKey, useInfiniteQuery } from '@tanstack/react-query';
+import { useMemo } from 'react';
 
 // ── usePagedList — one cursor-paged list layer over TanStack ─────────────────
 // Every "cursor → items → nextCursor, append on Load more" list re-rolled the
@@ -18,6 +19,8 @@ export interface PagedPage<T> {
   items: T[];
   /** Opaque cursor for the next page; absent/undefined ⇒ no more pages. */
   nextCursor?: string;
+  /** The size of the whole result, when the server counts it ("1,204 films"). */
+  total?: number;
 }
 
 export interface UsePagedListOptions<T> {
@@ -36,10 +39,23 @@ export interface UsePagedListOptions<T> {
   pollWhile?: (items: T[]) => boolean;
   /** ms a page stays fresh before a background refetch (TanStack `staleTime`). */
   staleTime?: number;
+  /**
+   * ms an unwatched list's pages stay cached (TanStack `gcTime`, default 5 minutes). Raise it
+   * when the trip away is long — a film watched from a grid is two hours, and Back should still
+   * find every page.
+   */
+  gcTime?: number;
+  /**
+   * Keep the previous query's items on screen while a changed `queryKey` fetches its first
+   * page, instead of emptying the list — a search typed a letter at a time does not flash
+   * blank between keystrokes. `isLoading` stays false meanwhile; `isFetching` is true.
+   */
+  keepPreviousItems?: boolean;
 }
 
 export interface PagedList<T> {
-  /** Every loaded page, flattened in order. */
+  /** Every loaded page, flattened in order — the same array until a page changes, so it is
+   *  safe as a `useMemo` dependency. */
   items: T[];
   /** First load only (no pages yet) — drive skeletons off this, not `isFetching`. */
   isLoading: boolean;
@@ -49,6 +65,8 @@ export interface PagedList<T> {
   error: unknown;
   /** Another page is available. */
   hasMore: boolean;
+  /** The newest page's `total`, or `undefined` before the first page or when none carries one. */
+  total: number | undefined;
   /** Load the next page (no-op if none remain or one is already loading). */
   loadMore: () => void;
   /** Refetch from the first page (every loaded page re-fetches). */
@@ -62,6 +80,11 @@ export interface PagedList<T> {
  * `loadMore()` from a "Load more" button or an intersection observer.
  *
  * Requires `@tanstack/react-query` wrapped in a `QueryClientProvider`.
+ *
+ * **A list that is left and come back to keeps every page it had** (for the query cache's
+ * `gcTime`), in its first render — which is what lets `useScrollMemory` put the viewer back
+ * 30,000px down instead of at the end of page one. Give it a `staleTime` too, or the return
+ * trip refetches every page it holds in the background.
  */
 export function usePagedList<T>({
   queryKey,
@@ -70,11 +93,15 @@ export function usePagedList<T>({
   pollIntervalMs,
   pollWhile,
   staleTime,
+  gcTime,
+  keepPreviousItems = false,
 }: UsePagedListOptions<T>): PagedList<T> {
   const query = useInfiniteQuery({
     queryKey,
     enabled,
     staleTime,
+    gcTime,
+    placeholderData: keepPreviousItems ? keepPreviousData : undefined,
     initialPageParam: undefined as string | undefined,
     queryFn: ({ pageParam }) => fetchPage(pageParam),
     getNextPageParam: (last: PagedPage<T>) => last.nextCursor,
@@ -90,7 +117,11 @@ export function usePagedList<T>({
         : false,
   });
 
-  const items = (query.data?.pages ?? []).flatMap((p) => p.items);
+  const pages = query.data?.pages;
+  // Memoized on the query's data, which TanStack keeps referentially stable while nothing
+  // changed — flattening per render handed every consumer a new array and defeated its memos.
+  const items = useMemo(() => (pages ?? []).flatMap((p) => p.items), [pages]);
+  const total = useMemo(() => pages?.findLast((p) => p.total !== undefined)?.total, [pages]);
 
   return {
     items,
@@ -99,6 +130,7 @@ export function usePagedList<T>({
     isError: query.isError,
     error: query.error,
     hasMore: !!query.hasNextPage,
+    total,
     loadMore: () => {
       if (query.hasNextPage && !query.isFetchingNextPage) void query.fetchNextPage();
     },

package/src/styles-areas/core.css

@@ -15,7 +15,7 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 712 candidate(s).
+ * 713 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
@@ -112,7 +112,7 @@
 @source inline("min-h-11 min-h-[1lh] min-h-[var(--control-h-lg)] min-h-[var(--control-h-md)]");
 @source inline("min-h-[var(--control-h-sm)] min-w-0 min-w-11 min-w-[8rem]");
 @source inline("min-w-[var(--radix-select-trigger-width)] ml-1 ml-auto motion motion-reduce:animate-none mt-0.5");
-@source inline("mt-1 mt-2 mx-auto my-1 object object-cover opacity opacity-0 opacity-30 opacity-40 opacity-50");
+@source inline("mt-1 mt-2 mx-auto my my-1 object object-cover opacity opacity-0 opacity-30 opacity-40 opacity-50");
 @source inline("opacity-60 opacity-70 out outline outline-none over overflow overflow-auto overflow-hidden");
 @source inline("overflow-x-auto overflow-y-auto overscroll-contain p p-0 p-0.5 p-1 p-2 p-3 p-4 p-6 p-[7px]");
 @source inline("p-[var(--panel-pad)] pause paused pb-3 pb-[8vh]");