@graph8/sdk 0.362.0 → 0.373.0

package/blocks/_foundation/hooks/use-load-more-list.ts

@@ -0,0 +1,61 @@
+"use client";
+
+/**
+ * useLoadMoreList: a list read that never stops at its first page. It has the shape of a plain `useG8Query` list
+ * (`data`, `loading`, `error`, `refetch`) plus `hasMore` / `loadMore` / `loadingMore`, so a screen that read one capped
+ * page can adopt it by swapping the hook and rendering <LoadMore> under the rows.
+ *
+ *   const list = useLoadMoreList(byOffset(100, async (offset, signal) => {
+ *     const env = await g8Get("/landing-pages", { limit: 100, offset }, { signal });
+ *     const rows = listOf(env.data);
+ *     return { rows, hasNext: hasNextOf(env, 100, rows.length) };
+ *   }), [status]);
+ *   ...
+ *   <LoadMore shown={rows.length} noun="landing pages" hasMore={list.hasMore} loading={list.loadingMore} onLoadMore={list.loadMore} />
+ *
+ * Built on usePaginated (changing `deps` starts over, stale responses are dropped). It calls no operation itself.
+ */
+import { useRef } from "react";
+import { usePaginated } from "./use-paginated";
+import type { UsePaginatedOptions } from "./use-paginated";
+import type { PaginatedResponse } from "@graph8/sdk";
+
+export interface UseLoadMoreList<T> {
+  /** The rows loaded so far; undefined until the first page arrives. */
+  data: T[] | undefined;
+  loading: boolean;
+  loadingMore: boolean;
+  error: unknown;
+  hasMore: boolean;
+  loadMore: () => void;
+  /** Start over from the first page; resolves with that first page of rows (what a poll needs to decide), undefined if it failed. */
+  refetch: () => Promise<T[] | undefined>;
+}
+
+export function useLoadMoreList<T>(
+  fetchPage: (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>,
+  deps: readonly unknown[],
+  options: UsePaginatedOptions = {},
+): UseLoadMoreList<T> {
+  const first = useRef<T[] | undefined>(undefined);
+  const p = usePaginated<T>(async (cursor, signal) => {
+    const page = await fetchPage(cursor, signal);
+    if (cursor === undefined) first.current = [...(page.data ?? [])];
+    return page;
+  }, deps, options);
+  return {
+    data: p.loading && p.items.length === 0 ? undefined : p.items,
+    loading: p.loading,
+    loadingMore: p.loadingMore,
+    error: p.error,
+    hasMore: p.hasMore,
+    loadMore: () => { void p.loadMore(); },
+    // Resolves with the FIRST page of the new load (first.current is set by the wrapped fetcher above), not the whole list:
+    // enough for a poll that only asks "is anything still generating?".
+    refetch: async () => {
+      first.current = undefined;
+      await p.reload();
+      return first.current;
+    },
+  };
+}

package/blocks/_foundation/hooks/use-paginated.ts

@@ -2,9 +2,28 @@
 
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { PaginatedResponse } from "@graph8/sdk";
+import { g8QueryCache } from "../lib/g8-cache";
+import type { G8QueryKey } from "../lib/g8-cache";
+import { useG8Query } from "./use-g8-query";
 
 export interface UsePaginatedOptions {
   enabled?: boolean;
+  /**
+   * Opt in to the shared cache: the loaded pages are kept under this key, shown instantly on the next
+   * mount and refreshed from the first page in the background; `invalidate(<prefix>)` reloads them.
+   * Name every filter in it: `["contacts", "cursor", { q }]`. Without a key nothing changes.
+   */
+  key?: G8QueryKey;
+  /** With `key`: ms the cached pages count as fresh. Default 0 (refresh on every mount). */
+  staleTime?: number;
+  /** With `key`: refresh (back to the first page) on window focus. Default false, so a long scroll is not lost. */
+  refetchOnFocus?: boolean;
+}
+
+/** What the cache holds for a keyed paginated list. */
+export interface PaginatedCacheData<T> {
+  items: T[];
+  nextCursor?: string;
 }
 
 export interface UsePaginatedResult<T> {
@@ -35,6 +54,19 @@ export function usePaginated<T>(
   fetchPage: (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>,
   deps: readonly unknown[],
   options: UsePaginatedOptions = {},
+): UsePaginatedResult<T> {
+  // Both are always called (rules of hooks); only one is ever active.
+  const keyed = options.key !== undefined;
+  const cached = useCachedPages(fetchPage, deps, options, keyed);
+  const plain = usePlainPages(fetchPage, deps, keyed ? { enabled: false } : options);
+  return keyed ? cached : plain;
+}
+
+/** The uncached hook, exactly as it was before the cache existed. */
+function usePlainPages<T>(
+  fetchPage: (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>,
+  deps: readonly unknown[],
+  options: UsePaginatedOptions,
 ): UsePaginatedResult<T> {
   const enabled = options.enabled ?? true;
   const fetchRef = useRef(fetchPage);
@@ -103,3 +135,91 @@ export function usePaginated<T>(
   const reload = useCallback(() => load(true), [load]);
   return { items, loading, loadingMore, error, hasMore, loadMore, reload };
 }
+
+/** The keyed hook: the first page goes through the shared cache; "load more" appends to the cached pages. */
+function useCachedPages<T>(
+  fetchPage: (cursor: string | undefined, signal: AbortSignal) => Promise<PaginatedResponse<T>>,
+  deps: readonly unknown[],
+  options: UsePaginatedOptions,
+  active: boolean,
+): UsePaginatedResult<T> {
+  const key = options.key ?? "";
+  const keyRef = useRef(key);
+  keyRef.current = key;
+  const fetchRef = useRef(fetchPage);
+  fetchRef.current = fetchPage;
+  const query = useG8Query<PaginatedCacheData<T>>(
+    async (signal) => {
+      const page = await fetchRef.current(undefined, signal);
+      return { items: [...(page.data ?? [])], nextCursor: page.pagination?.next_cursor ?? undefined };
+    },
+    deps,
+    {
+      key: active ? key : undefined,
+      enabled: active && (options.enabled ?? true),
+      staleTime: options.staleTime,
+      refetchOnFocus: options.refetchOnFocus ?? false,
+    },
+  );
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [moreError, setMoreError] = useState<unknown>(undefined);
+  const more = useRef<AbortController | null>(null);
+
+  // A new key (filter) or unmount drops a "load more" in flight.
+  useEffect(() => {
+    return () => {
+      more.current?.abort();
+      more.current = null;
+      setLoadingMore(false);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active ? JSON.stringify(key) : ""]);
+
+  const loadMore = useCallback(async (): Promise<void> => {
+    const start = g8QueryCache.getQueryData<PaginatedCacheData<T>>(keyRef.current);
+    if (!active || more.current || !start?.nextCursor) return;
+    const ctl = new AbortController();
+    more.current = ctl;
+    setLoadingMore(true);
+    try {
+      const page = await fetchRef.current(start.nextCursor, ctl.signal);
+      // The list was refreshed or replaced meanwhile: this page belongs to an older version.
+      if (ctl.signal.aborted || g8QueryCache.getQueryData(keyRef.current) !== start) return;
+      g8QueryCache.setQueryData<PaginatedCacheData<T>>(keyRef.current, {
+        items: [...start.items, ...(page.data ?? [])],
+        nextCursor: page.pagination?.next_cursor ?? undefined,
+      });
+      setMoreError(undefined);
+    } catch (err) {
+      if (!ctl.signal.aborted) setMoreError(err);
+    } finally {
+      if (more.current === ctl) {
+        more.current = null;
+        setLoadingMore(false);
+      }
+    }
+  }, [active]);
+
+  const reload = useCallback(async (): Promise<void> => {
+    more.current?.abort();
+    more.current = null;
+    setLoadingMore(false);
+    setMoreError(undefined);
+    await query.refetch();
+  }, [query.refetch]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const data = query.data;
+  return {
+    items: data?.items ?? EMPTY_ITEMS,
+    // Cached pages stay on screen while they refresh: only a list with nothing of its own yet is "loading".
+    loading: query.loading && (data === undefined || query.isPreviousData === true),
+    loadingMore,
+    error: query.error ?? moreError,
+    hasMore: Boolean(data?.nextCursor),
+    loadMore,
+    reload,
+  };
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const EMPTY_ITEMS: any[] = [];

package/blocks/_foundation/hooks/use-row-activation.ts

@@ -0,0 +1,57 @@
+"use client";
+
+/**
+ * useRowActivation: make a whole list row open its record from the keyboard as well as the mouse.
+ * Spread the returned props on the row (`<TableRow {...rowProps}>` or a `<li>`): it becomes focusable,
+ * Enter and Space open it, and a click opens it, but a click or key on something INSIDE the row that
+ * has its own job (a checkbox, a button, a link, an input) is left alone.
+ *
+ * A table row keeps its `row` role (pass `role: undefined`, the default); pass `role: "button"` for a
+ * plain `<div>` or `<li>` row that is not part of a table or list.
+ *
+ * SDK operations: none.
+ */
+import type { KeyboardEvent, MouseEvent } from "react";
+
+const INTERACTIVE = "a,button,input,select,textarea,label,[role='button'],[role='checkbox'],[role='link'],[role='menuitem'],[data-row-ignore]";
+
+export interface RowActivationProps {
+  role?: "button";
+  tabIndex: 0;
+  onClick: (e: MouseEvent<HTMLElement>) => void;
+  onKeyDown: (e: KeyboardEvent<HTMLElement>) => void;
+}
+
+/** True when the event started on a nested control that should keep its own behaviour. */
+function onNestedControl(e: { target: EventTarget; currentTarget: EventTarget }): boolean {
+  const el = e.target as HTMLElement | null;
+  if (!el || el === (e.currentTarget as HTMLElement) || typeof el.closest !== "function") return false;
+  const hit = el.closest(INTERACTIVE);
+  return hit != null && hit !== (e.currentTarget as HTMLElement) && (e.currentTarget as HTMLElement).contains(hit);
+}
+
+/**
+ * The props, as a plain function: use it inside `.map()` callbacks (`<TableRow {...rowActivationProps(() => open(row.id))}>`),
+ * where a hook cannot be called. `useRowActivation` is the same thing for a component's own top level.
+ */
+export function rowActivationProps(onOpen: () => void, options: { role?: "button" } = {}): RowActivationProps {
+  return {
+    ...(options.role ? { role: options.role } : {}),
+    tabIndex: 0,
+    onClick: (e) => {
+      if (onNestedControl(e)) return;
+      onOpen();
+    },
+    onKeyDown: (e) => {
+      if (e.target !== e.currentTarget) return; // Enter on an inner button is that button's own
+      if (e.key === "Enter" || e.key === " ") {
+        e.preventDefault();
+        onOpen();
+      }
+    },
+  };
+}
+
+export function useRowActivation(onOpen: () => void, options: { role?: "button" } = {}): RowActivationProps {
+  return rowActivationProps(onOpen, options);
+}

package/blocks/_foundation/hooks/use-url-filters.ts

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * useUrlFilters: the filter state of a list screen, kept in the URL so a filtered view survives reload, Back and sharing.
+ *
+ *   const f = useUrlFilters(["email", "city"] as const, { prefix: "c_" });
+ *   <input value={f.draft.email} onChange={(e) => f.set("email", e.target.value)} />
+ *   g8Get("/contacts", { page, ...f.query });      // f.query holds only the filters that are set, debounced
+ *
+ * Typing is local (`draft`, instant); the debounced `filters` are what the list reads, and they are written to the URL as
+ * `<prefix><key>=...`. A URL that already carries filters is the starting value, with no flash of an unfiltered list and
+ * no wipe at mount. It is read through `useSyncExternalStore` (like useUrlState), so it is hydration-safe: the server and
+ * the first hydration render both see empty filters, React then re-renders with the URL's. In that first hydration render
+ * `ready` is false: hold the list read until it is true (`enabled: filters.ready`), so no unfiltered read goes out. On a
+ * client-only render `ready` is true from the start. `clear()` empties everything. Params of other hooks (id, view, tab)
+ * are never touched.
+ *
+ * SDK operations: none.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { readUrlParam, writeUrlParam } from "./use-url-state";
+
+export interface UseUrlFiltersOptions {
+  /** URL param prefix, so two screens on one page do not share names. Default "". */
+  prefix?: string;
+  /** Milliseconds of quiet typing before the list reads the new filters. Default 300. */
+  debounceMs?: number;
+}
+
+export interface UseUrlFilters<K extends string> {
+  /** What the inputs show (instant). */
+  draft: Record<K, string>;
+  /** What the list reads (debounced after an edit). */
+  filters: Record<K, string>;
+  /** Only the filters that are set, ready to spread into a query. */
+  query: Partial<Record<K, string>>;
+  set: (key: K, value: string) => void;
+  clear: () => void;
+  /** Some filter is set (draft). */
+  active: boolean;
+  /** How many of `keys` are set (draft). */
+  count: number;
+  /** The URL's filters have been read (false only in the first hydration render): hold the list read until true. */
+  ready: boolean;
+}
+
+const noSubscribe = (): (() => void) => () => {};
+
+export function useUrlFilters<K extends string>(keys: readonly K[], options: UseUrlFiltersOptions = {}): UseUrlFilters<K> {
+  const prefix = options.prefix ?? "";
+  const ms = options.debounceMs ?? 300;
+  const sig = keys.join(",");
+  const empty = useCallback((): Record<K, string> => Object.fromEntries(keys.map((k) => [k, ""])) as Record<K, string>, [sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // The URL's filters as one string, frozen at the first client read. The server (and the first hydration render) sees "".
+  const frozen = useRef<string | null>(null);
+  const urlSnap = useSyncExternalStore(
+    noSubscribe,
+    () => (frozen.current ??= JSON.stringify(keys.map((k) => readUrlParam(prefix + k) ?? ""))),
+    () => JSON.stringify(keys.map(() => "")),
+  );
+  const ready = useSyncExternalStore(noSubscribe, () => true, () => false);
+  const fromUrl = useMemo(() => {
+    const values = JSON.parse(urlSnap) as string[];
+    return Object.fromEntries(keys.map((k, i) => [k, values[i] ?? ""])) as Record<K, string>;
+  }, [urlSnap, sig]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // `edited` is null until the person types: until then the filters ARE the URL's (no debounce lag, nothing to write back).
+  const [edited, setEdited] = useState<Record<K, string> | null>(null);
+  const [settled, setSettled] = useState<Record<K, string> | null>(null);
+  const draft = edited ?? fromUrl;
+  const filters = settled ?? fromUrl;
+  const latest = useRef(draft);
+  latest.current = draft;
+
+  useEffect(() => {
+    if (edited === null) return;
+    const t = setTimeout(() => setSettled(edited), ms);
+    return () => clearTimeout(t);
+  }, [edited, ms]);
+
+  // The settled filters are the URL's value; writeUrlParam skips an unchanged value, so mounting writes nothing.
+  useEffect(() => {
+    if (!ready) return;
+    for (const k of keys) writeUrlParam(prefix + k, filters[k] || null);
+  }, [ready, filters]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  const set = useCallback((key: K, value: string) => setEdited({ ...latest.current, [key]: value }), []);
+  const clear = useCallback(() => setEdited(empty()), [empty]);
+  const query = Object.fromEntries(keys.filter((k) => filters[k]).map((k) => [k, filters[k]])) as Partial<Record<K, string>>;
+  const count = keys.filter((k) => draft[k]).length;
+  return { draft, filters, query, set, clear, active: count > 0, count, ready };
+}