@graph8/sdk 0.361.0 → 0.370.0

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

@@ -0,0 +1,52 @@
+"use client";
+
+/**
+ * White-label: who the app is and what the platform behind it is called. Every block reads the platform's name
+ * and link-outs from here ("Connect in graph8", "Open in graph8", the settings pages they open), so an agency or
+ * reseller can show its own name and its own app URL everywhere, from one config (`g8.config.ts` in a created app,
+ * passed to <BrandProvider>).
+ *
+ *   const brand = useBrand();           // { name, appUrl, linkLabel, logo? }
+ *   brandUrl(brand, "/studio/settings?tab=integrations")
+ *
+ * With no provider, or for any field left out, the default is graph8 itself (app.graph8.com), so nothing changes
+ * for an app that does not brand.
+ */
+
+import { createContext, useContext } from "react";
+
+export interface BrandConfig {
+  /** The app's own name (sidebar, page title). */
+  name: string;
+  /** Base URL of the platform's web app; link-outs append their path. No trailing slash needed. */
+  appUrl: string;
+  /** What the platform is called in copy and links ("Connect in <linkLabel>"). */
+  linkLabel: string;
+  /** Public path or URL of the logo (`/brand/logo.svg`). */
+  logo?: string;
+}
+
+export const DEFAULT_BRAND: BrandConfig = { name: "graph8 app", appUrl: "https://app.graph8.com", linkLabel: "graph8" };
+
+/** Fill the gaps of a partial config with the defaults; an appUrl that is not http(s) falls back to the default. */
+export function resolveBrand(partial?: Partial<BrandConfig> | null): BrandConfig {
+  const p = partial ?? {};
+  const text = (v: unknown, d: string) => (typeof v === "string" && v.trim() ? v.trim() : d);
+  let appUrl = DEFAULT_BRAND.appUrl;
+  if (typeof p.appUrl === "string" && /^https?:\/\/[^\s/]+/i.test(p.appUrl.trim())) appUrl = p.appUrl.trim().replace(/\/+$/, "");
+  const logo = typeof p.logo === "string" && p.logo.trim() ? p.logo.trim() : undefined;
+  return { name: text(p.name, DEFAULT_BRAND.name), appUrl, linkLabel: text(p.linkLabel, DEFAULT_BRAND.linkLabel), ...(logo ? { logo } : {}) };
+}
+
+export const BrandContext = createContext<BrandConfig>(DEFAULT_BRAND);
+
+/** The current brand: the nearest <BrandProvider>'s, else graph8's defaults. */
+export function useBrand(): BrandConfig {
+  return useContext(BrandContext);
+}
+
+/** `appUrl` + a path on the platform (`"/lists"`, `"/studio/settings?tab=api"`); no path gives the app's home. */
+export function brandUrl(brand: Pick<BrandConfig, "appUrl">, path = ""): string {
+  if (!path) return brand.appUrl;
+  return `${brand.appUrl}${path.startsWith("/") || path.startsWith("?") ? "" : "/"}${path}`;
+}

package/blocks/_foundation/hooks/use-g8-mutation.ts

@@ -1,10 +1,22 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
+import { g8QueryCache } from "../lib/g8-cache";
+import type { G8QueryKey } from "../lib/g8-cache";
 
 export interface UseG8MutationOptions<TVars, TResult> {
   onSuccess?: (result: TResult, vars: TVars) => void;
   onError?: (error: unknown, vars: TVars) => void;
+  /**
+   * Cache keys (prefixes) to mark stale after a successful write, so every list and detail showing them
+   * refreshes: `invalidates: ["contacts"]`, or a function of the result: `(r, v) => [["contacts", "detail", v.id]]`.
+   */
+  invalidates?: readonly G8QueryKey[] | ((result: TResult, vars: TVars) => readonly G8QueryKey[]);
+  /**
+   * Optimistic update: change cached data under `prefix` before the request; on failure it is put back.
+   * Either way the prefix is invalidated afterwards so the server's answer wins.
+   */
+  optimistic?: { prefix: G8QueryKey; update: (old: any, vars: TVars, key: readonly unknown[]) => any }; // eslint-disable-line @typescript-eslint/no-explicit-any
 }
 
 export interface UseG8MutationResult<TVars, TResult> {
@@ -54,15 +66,26 @@ export function useG8Mutation<TVars, TResult>(
     const id = ++latest.current;
     setLoading(true);
     setError(undefined);
+    const { optimistic } = optionsRef.current;
+    const snapshot = optimistic
+      ? g8QueryCache.setQueriesData(optimistic.prefix, (old, key) => optimistic.update(old, vars, key))
+      : null;
     try {
       const result = await mutationRef.current(vars);
       if (id === latest.current && mounted.current) {
         setData(result);
         setLoading(false);
       }
+      const inv = optionsRef.current.invalidates;
+      const prefixes = typeof inv === "function" ? inv(result, vars) : inv ?? [];
+      for (const prefix of optimistic ? [...prefixes, optimistic.prefix] : prefixes) void g8QueryCache.invalidate(prefix);
       optionsRef.current.onSuccess?.(result, vars);
       return result;
     } catch (err) {
+      if (snapshot && optimistic) {
+        g8QueryCache.restore(snapshot);
+        void g8QueryCache.invalidate(optimistic.prefix);
+      }
       if (id === latest.current && mounted.current) {
         setError(err);
         setLoading(false);

package/blocks/_foundation/hooks/use-g8-query.ts

@@ -1,12 +1,31 @@
 "use client";
 
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { EMPTY_QUERY_STATE, g8QueryCache, hashKey } from "../lib/g8-cache";
+import type { G8QueryKey, G8QueryObserver, G8QueryState } from "../lib/g8-cache";
 
 export interface UseG8QueryOptions<T> {
   /** Set false to hold the request (for example until a required id is known). */
   enabled?: boolean;
   /** Shown until the first response lands. */
   initialData?: T;
+  /**
+   * Opt in to the shared cache (lib/g8-cache.ts). Every component asking for the same key shares one
+   * request and one answer; cached data shows instantly and refreshes in the background. The key must
+   * name every input the fetcher reads: `["contacts", "detail", id]`. Without a key nothing changes.
+   */
+  key?: G8QueryKey;
+  /** With `key`: how long (ms) cached data counts as fresh, so a mount does not refetch it. Default 0. */
+  staleTime?: number;
+  /** With `key`: refresh when the window regains focus or the network returns (throttled). Default true. */
+  refetchOnFocus?: boolean;
+  /** With `key`: keep showing the previous key's data while a new key loads (like the uncached hook does). Default true. */
+  keepPrevious?: boolean;
+  /**
+   * With `key`: shown while the key has no data yet (for example the row a detail was opened from), with
+   * `isPlaceholderData: true`. NEVER seed an edit form from it: wait until `isPlaceholderData` is false.
+   */
+  placeholderData?: T;
 }
 
 export interface UseG8QueryResult<T> {
@@ -16,6 +35,12 @@ export interface UseG8QueryResult<T> {
   loading: boolean;
   /** Re-run the request now. Resolves with the data, or undefined if it failed or was superseded. */
   refetch: () => Promise<T | undefined>;
+  /** With `key` only: `data` is `placeholderData` (not the real record yet). */
+  isPlaceholderData?: boolean;
+  /** With `key` only: `data` belongs to the previous key while the new one loads. */
+  isPreviousData?: boolean;
+  /** With `key` only: epoch ms when the data was fetched (0 = not yet). */
+  updatedAt?: number;
 }
 
 /**
@@ -34,6 +59,19 @@ export function useG8Query<T>(
   fetcher: (signal: AbortSignal) => Promise<T>,
   deps: readonly unknown[],
   options: UseG8QueryOptions<T> = {},
+): UseG8QueryResult<T> {
+  // Both are always called (rules of hooks); only one is ever active.
+  const keyed = options.key !== undefined;
+  const cached = useCachedQuery(fetcher, deps, options, keyed);
+  const plain = usePlainQuery(fetcher, deps, keyed ? { ...options, enabled: false } : options);
+  return keyed ? cached : plain;
+}
+
+/** The uncached hook, exactly as it was before the cache existed. */
+function usePlainQuery<T>(
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  deps: readonly unknown[],
+  options: UseG8QueryOptions<T>,
 ): UseG8QueryResult<T> {
   const enabled = options.enabled ?? true;
   const fetcherRef = useRef(fetcher);
@@ -85,3 +123,91 @@ export function useG8Query<T>(
 
   return { data, error, loading, refetch: run };
 }
+
+const noopSubscribe = (): (() => void) => () => undefined;
+const emptySnapshot = (): G8QueryState => EMPTY_QUERY_STATE;
+
+/** The keyed hook: state lives in the shared cache, this component only subscribes to it. */
+function useCachedQuery<T>(
+  fetcher: (signal: AbortSignal) => Promise<T>,
+  deps: readonly unknown[],
+  options: UseG8QueryOptions<T>,
+  active: boolean,
+): UseG8QueryResult<T> {
+  const enabled = options.enabled ?? true;
+  const key = options.key ?? "";
+  const hash = active ? hashKey(key) : "";
+  const keyRef = useRef(key);
+  keyRef.current = key;
+  const fetcherRef = useRef(fetcher);
+  fetcherRef.current = fetcher;
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const observer = useRef<G8QueryObserver>({
+    fetcher: () => (signal) => fetcherRef.current(signal),
+    enabled: () => optionsRef.current.enabled ?? true,
+    staleTime: () => optionsRef.current.staleTime ?? 0,
+    refetchOnFocus: () => (optionsRef.current.enabled ?? true) && (optionsRef.current.refetchOnFocus ?? true),
+  }).current;
+
+  const subscribe = useCallback(
+    (onChange: () => void) => (active ? g8QueryCache.subscribe(keyRef.current, onChange, observer) : () => undefined),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [active, hash],
+  );
+  const getSnapshot = useCallback(
+    () => (active ? g8QueryCache.getState(keyRef.current) : EMPTY_QUERY_STATE),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [active, hash],
+  );
+  const state = useSyncExternalStore(active ? subscribe : noopSubscribe, active ? getSnapshot : emptySnapshot, emptySnapshot) as G8QueryState<T>;
+
+  // Same key, new deps: the fetcher changed under the key, so the cached answer may be wrong. Refetch.
+  const lastRun = useRef<{ hash: string; deps: readonly unknown[] } | null>(null);
+  useEffect(() => {
+    if (!active || !enabled) return;
+    const prev = lastRun.current;
+    const depsChanged =
+      prev !== null && prev.hash === hash && (prev.deps.length !== deps.length || prev.deps.some((d, i) => !Object.is(d, deps[i])));
+    lastRun.current = { hash, deps };
+    if (depsChanged) void g8QueryCache.fetch(keyRef.current, observer.fetcher(), { force: true });
+    else void g8QueryCache.ensureFresh(keyRef.current, observer.fetcher(), optionsRef.current.staleTime ?? 0);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [active, enabled, hash, ...deps]);
+
+  const previous = useRef<{ hash: string; data: T } | null>(null);
+  if (active && state.data !== undefined) previous.current = { hash, data: state.data };
+
+  const refetch = useCallback(
+    () =>
+      active
+        ? (g8QueryCache.fetch(keyRef.current, observer.fetcher(), { force: true, share: false }) as Promise<T | undefined>)
+        : Promise.resolve(undefined),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [active, hash],
+  );
+
+  let data = state.data;
+  let isPreviousData = false;
+  let isPlaceholderData = false;
+  if (data === undefined && (options.keepPrevious ?? true) && previous.current && previous.current.hash !== hash) {
+    data = previous.current.data;
+    isPreviousData = true;
+  }
+  if (data === undefined && options.placeholderData !== undefined) {
+    data = options.placeholderData;
+    isPlaceholderData = true;
+  }
+  if (data === undefined) data = options.initialData;
+  const neverLoaded = state.updatedAt === 0 && state.error === undefined;
+  return {
+    data,
+    error: state.error,
+    loading: enabled && (state.fetching || neverLoaded),
+    refetch,
+    isPlaceholderData,
+    isPreviousData,
+    updatedAt: state.updatedAt,
+  };
+}

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-state.ts

@@ -0,0 +1,74 @@
+"use client";
+
+/**
+ * useUrlState: one string in the URL query (`?id=123`, `?tab=activity`, `?q=ada`) as React state.
+ * The URL owns it, so the open record, the tab and the search survive reload, Back and sharing.
+ * Framework-agnostic: window.history.replaceState (pushState with `{ push: true }`) plus `popstate`,
+ * no next/navigation. SSR-safe: the server and the first client render see `defaultValue`.
+ *
+ * SDK operations: none.
+ */
+import { useCallback, useSyncExternalStore } from "react";
+
+const EVENT = "g8:urlstate";
+
+type Listener = () => void;
+
+function subscribe(listener: Listener): () => void {
+  if (typeof window !== "undefined") {
+    window.addEventListener("popstate", listener);
+    window.addEventListener(EVENT, listener);
+  }
+  return () => {
+    if (typeof window !== "undefined") {
+      window.removeEventListener("popstate", listener);
+      window.removeEventListener(EVENT, listener);
+    }
+  };
+}
+
+/** Current value of `key` in the page URL, or undefined. */
+export function readUrlParam(key: string): string | undefined {
+  if (typeof window === "undefined") return undefined;
+  const v = new URLSearchParams(window.location.search).get(key);
+  return v == null ? undefined : v;
+}
+
+export interface SetUrlStateOptions {
+  /** Add a history entry (Back returns to the previous value) instead of replacing. */
+  push?: boolean;
+}
+
+/** Write `key` into the page URL (null, undefined or "" removes it) and notify every hook. */
+export function writeUrlParam(key: string, value: string | null | undefined, options: SetUrlStateOptions = {}): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  const current = url.searchParams.get(key);
+  const next = value == null || value === "" ? null : String(value);
+  if (current === next) return;
+  if (next == null) url.searchParams.delete(key);
+  else url.searchParams.set(key, next);
+  const href = `${url.pathname}${url.search}${url.hash}`;
+  if (options.push) window.history.pushState(window.history.state, "", href);
+  else window.history.replaceState(window.history.state, "", href);
+  window.dispatchEvent(new Event(EVENT));
+}
+
+export type UrlStateSetter = (value: string | null | undefined, options?: SetUrlStateOptions) => void;
+
+/**
+ * `const [id, setId] = useUrlState("id")`: `id` is the param or `defaultValue` ("" by default); `setId(null)`
+ * or `setId("")` removes it; `setId("42", { push: true })` adds a history entry.
+ */
+export function useUrlState(key: string, defaultValue = ""): [string, UrlStateSetter] {
+  const value = useSyncExternalStore(
+    subscribe,
+    () => readUrlParam(key) ?? defaultValue,
+    () => defaultValue,
+  );
+  const set = useCallback<UrlStateSetter>(
+    (next, options) => writeUrlParam(key, next == null || next === defaultValue ? null : next, options),
+    [key, defaultValue],
+  );
+  return [value, set];
+}