@checkstack/ui 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @checkstack/ui
 
+## 0.2.1
+
+### Patch Changes
+
+- 7a23261: ## TanStack Query Integration
+
+  Migrated all frontend components to use `usePluginClient` hook with TanStack Query integration, replacing the legacy `forPlugin()` pattern.
+
+  ### New Features
+
+  - **`usePluginClient` hook**: Provides type-safe access to plugin APIs with `.useQuery()` and `.useMutation()` methods
+  - **Automatic request deduplication**: Multiple components requesting the same data share a single network request
+  - **Built-in caching**: Configurable stale time and cache duration per query
+  - **Loading/error states**: TanStack Query provides `isLoading`, `error`, `isRefetching` states automatically
+  - **Background refetching**: Stale data is automatically refreshed when components mount
+
+  ### Contract Changes
+
+  All RPC contracts now require `operationType: "query"` or `operationType: "mutation"` metadata:
+
+  ```typescript
+  const getItems = proc()
+    .meta({ operationType: "query", access: [access.read] })
+    .output(z.array(itemSchema))
+    .query();
+
+  const createItem = proc()
+    .meta({ operationType: "mutation", access: [access.manage] })
+    .input(createItemSchema)
+    .output(itemSchema)
+    .mutation();
+  ```
+
+  ### Migration
+
+  ```typescript
+  // Before (forPlugin pattern)
+  const api = useApi(myPluginApiRef);
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    api.getItems().then(setItems);
+  }, [api]);
+
+  // After (usePluginClient pattern)
+  const client = usePluginClient(MyPluginApi);
+  const { data: items, isLoading } = client.getItems.useQuery({});
+  ```
+
+  ### Bug Fixes
+
+  - Fixed `rpc.test.ts` test setup for middleware type inference
+  - Fixed `SearchDialog` to use `setQuery` instead of deprecated `search` method
+  - Fixed null→undefined warnings in notification and queue frontends
+
+- Updated dependencies [7a23261]
+  - @checkstack/frontend-api@0.2.0
+  - @checkstack/common@0.3.0
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/ui",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "src/index.ts",
   "dependencies": {

package/src/components/PaginatedList.tsx

@@ -1,14 +1,24 @@
 import * as React from "react";
-import {
-  usePagination,
-  type UsePaginationOptions,
-  type PaginationState,
-} from "../hooks/usePagination";
+import { type PaginationState } from "../hooks/usePagination";
 import { Pagination } from "./Pagination";
 import { cn } from "../utils";
 
-export interface PaginatedListProps<TResponse, TItem, TExtraParams = object>
-  extends UsePaginationOptions<TResponse, TItem, TExtraParams> {
+export interface PaginatedListProps<TItem> {
+  /**
+   * Items to display
+   */
+  items: TItem[];
+
+  /**
+   * Loading state
+   */
+  loading: boolean;
+
+  /**
+   * Pagination state from usePagination hook
+   */
+  pagination: PaginationState;
+
   /**
    * Render function for the items
    */
@@ -64,23 +74,31 @@ export interface PaginatedListProps<TResponse, TItem, TExtraParams = object>
 }
 
 /**
- * All-in-one paginated list component with automatic data fetching.
+ * Paginated list component for rendering paginated data.
+ * Use with usePagination() hook and TanStack Query.
  *
  * @example
  * ```tsx
+ * const pagination = usePagination({ defaultLimit: 20 });
+ * const { data, isLoading } = notificationClient.getNotifications.useQuery({
+ *   limit: pagination.limit,
+ *   offset: pagination.offset,
+ * });
+ * usePaginationSync(pagination, data?.total);
+ *
  * <PaginatedList
- *   fetchFn={(p) => client.getNotifications(p)}
- *   getItems={(r) => r.notifications}
- *   getTotal={(r) => r.total}
- *   extraParams={{ unreadOnly: true }}
+ *   items={data?.notifications ?? []}
+ *   loading={isLoading}
+ *   pagination={pagination}
  * >
- *   {(items, loading) =>
- *     loading ? null : items.map((item) => <Card key={item.id} {...item} />)
- *   }
+ *   {(items) => items.map((item) => <Card key={item.id} {...item} />)}
  * </PaginatedList>
  * ```
  */
-export function PaginatedList<TResponse, TItem, TExtraParams = object>({
+export function PaginatedList<TItem>({
+  items,
+  loading,
+  pagination,
   children,
   showLoadingSpinner = true,
   emptyContent,
@@ -90,10 +108,7 @@ export function PaginatedList<TResponse, TItem, TExtraParams = object>({
   pageSizes,
   className,
   paginationClassName,
-  ...paginationOptions
-}: PaginatedListProps<TResponse, TItem, TExtraParams>) {
-  const { items, loading, pagination } = usePagination(paginationOptions);
-
+}: PaginatedListProps<TItem>) {
   const showEmpty = !loading && items.length === 0 && emptyContent;
 
   return (

package/src/hooks/usePagination.ts

@@ -1,66 +1,17 @@
-import { useState, useEffect, useCallback, useMemo, useRef } from "react";
+import { useState, useCallback, useMemo, useEffect } from "react";
 
 /**
- * Pagination parameters passed to the fetch function
- */
-export interface PaginationParams {
-  limit: number;
-  offset: number;
-}
-
-/**
- * Options for usePagination hook
- */
-export interface UsePaginationOptions<TResponse, TItem, TExtraParams = object> {
-  /**
-   * Fetch function that receives pagination + extra params and returns response
-   */
-  fetchFn: (params: PaginationParams & TExtraParams) => Promise<TResponse>;
-
-  /**
-   * Extract items array from the response
-   */
-  getItems: (response: TResponse) => TItem[];
-
-  /**
-   * Extract total count from the response
-   */
-  getTotal: (response: TResponse) => number;
-
-  /**
-   * Extra parameters to pass to fetchFn (merged with pagination params)
-   * Changes to this object will trigger a refetch
-   */
-  extraParams?: TExtraParams;
-
-  /**
-   * Initial page number (1-indexed)
-   * @default 1
-   */
-  defaultPage?: number;
-
-  /**
-   * Items per page
-   * @default 10
-   */
-  defaultLimit?: number;
-
-  /**
-   * Whether to fetch on mount
-   * @default true
-   */
-  fetchOnMount?: boolean;
-}
-
-/**
- * Pagination state returned by usePagination hook
+ * Pagination state and controls.
+ * Used with TanStack Query's useQuery hook for paginated data.
  */
 export interface PaginationState {
   /** Current page (1-indexed) */
   page: number;
   /** Items per page */
   limit: number;
-  /** Total number of items */
+  /** Offset for query (calculated from page and limit) */
+  offset: number;
+  /** Total number of items (set via setTotal) */
   total: number;
   /** Total number of pages */
   totalPages: number;
@@ -72,130 +23,74 @@ export interface PaginationState {
   setPage: (page: number) => void;
   /** Change items per page (resets to page 1) */
   setLimit: (limit: number) => void;
+  /** Update total count from query response */
+  setTotal: (total: number) => void;
   /** Go to next page */
   nextPage: () => void;
   /** Go to previous page */
   prevPage: () => void;
-  /** Refresh current page (shows loading state) */
-  refetch: () => void;
-  /** Refresh current page silently (no loading state, prevents UI flicker) */
-  silentRefetch: () => void;
 }
 
 /**
- * Return value of usePagination hook
+ * Options for usePagination hook.
  */
-export interface UsePaginationResult<TItem> {
-  /** Current page items */
-  items: TItem[];
-  /** Loading state */
-  loading: boolean;
-  /** Error if fetch failed */
-  error: Error | undefined;
-  /** Pagination controls and state */
-  pagination: PaginationState;
+export interface UsePaginationOptions {
+  /**
+   * Initial page number (1-indexed)
+   * @default 1
+   */
+  defaultPage?: number;
+
+  /**
+   * Items per page
+   * @default 10
+   */
+  defaultLimit?: number;
 }
 
 /**
- * Hook for managing paginated data fetching with automatic state management.
+ * Hook for managing pagination state to use with TanStack Query.
+ *
+ * This hook manages page/limit state and provides computed offset for queries.
+ * Use with useQuery to build paginated data fetching.
  *
  * @example
  * ```tsx
- * const { items, loading, pagination } = usePagination({
- *   fetchFn: (p) => client.getNotifications(p),
- *   getItems: (r) => r.notifications,
- *   getTotal: (r) => r.total,
- *   extraParams: { unreadOnly: true },
+ * // Simple usage with usePluginClient
+ * const pagination = usePagination({ defaultLimit: 20 });
+ *
+ * const { data, isLoading } = notificationClient.getNotifications.useQuery({
+ *   limit: pagination.limit,
+ *   offset: pagination.offset,
+ *   unreadOnly: true,
  * });
  *
+ * // Update total when data changes
+ * useEffect(() => {
+ *   if (data) pagination.setTotal(data.total);
+ * }, [data, pagination]);
+ *
  * return (
  *   <>
- *     {items.map(item => <Card key={item.id} {...item} />)}
- *     <Pagination {...pagination} />
+ *     {data?.notifications.map(n => <Notification key={n.id} {...n} />)}
+ *     <Pagination {...pagination} loading={isLoading} />
  *   </>
  * );
  * ```
  */
-export function usePagination<TResponse, TItem, TExtraParams = object>({
-  fetchFn,
-  getItems,
-  getTotal,
-  extraParams,
+export function usePagination({
   defaultPage = 1,
   defaultLimit = 10,
-  fetchOnMount = true,
-}: UsePaginationOptions<
-  TResponse,
-  TItem,
-  TExtraParams
->): UsePaginationResult<TItem> {
-  const [items, setItems] = useState<TItem[]>([]);
-  const [loading, setLoading] = useState(fetchOnMount);
-  const [error, setError] = useState<Error>();
+}: UsePaginationOptions = {}): PaginationState {
   const [page, setPageState] = useState(defaultPage);
   const [limit, setLimitState] = useState(defaultLimit);
-  const [total, setTotal] = useState(0);
-
-  // Use refs for callback functions to avoid re-creating fetchData when they change
-  // This is better DX - callers don't need to memoize their functions
-  const fetchFnRef = useRef(fetchFn);
-  const getItemsRef = useRef(getItems);
-  const getTotalRef = useRef(getTotal);
-  const extraParamsRef = useRef(extraParams);
-
-  // Update refs when functions change
-  fetchFnRef.current = fetchFn;
-  getItemsRef.current = getItems;
-  getTotalRef.current = getTotal;
-  extraParamsRef.current = extraParams;
-
-  // Memoize extraParams to detect changes
-  const extraParamsKey = useMemo(
-    () => JSON.stringify(extraParams ?? {}),
-    [extraParams]
-  );
+  const [total, setTotalState] = useState(0);
 
-  const fetchData = useCallback(
-    async (showLoading = true) => {
-      if (showLoading) {
-        setLoading(true);
-      }
-      setError(undefined);
-
-      try {
-        const offset = (page - 1) * limit;
-        const params = {
-          limit,
-          offset,
-          ...extraParamsRef.current,
-        } as PaginationParams & TExtraParams;
-
-        const response = await fetchFnRef.current(params);
-        setItems(getItemsRef.current(response));
-        setTotal(getTotalRef.current(response));
-      } catch (error_) {
-        setError(error_ instanceof Error ? error_ : new Error(String(error_)));
-        setItems([]);
-      } finally {
-        setLoading(false);
-      }
-    },
-    [page, limit, extraParamsKey]
+  const offset = useMemo(() => (page - 1) * limit, [page, limit]);
+  const totalPages = useMemo(
+    () => Math.max(1, Math.ceil(total / limit)),
+    [total, limit]
   );
-
-  // Fetch on mount and when dependencies change
-  useEffect(() => {
-    if (fetchOnMount || page !== defaultPage || limit !== defaultLimit) {
-      void fetchData(true);
-    }
-  }, [fetchData, fetchOnMount, page, limit, defaultPage, defaultLimit]);
-
-  // Reset to page 1 when extraParams change
-  useEffect(() => {
-    setPageState(1);
-  }, [extraParamsKey]);
-
-  const totalPages = Math.max(1, Math.ceil(total / limit));
   const hasNext = page < totalPages;
   const hasPrev = page > 1;
 
@@ -208,6 +103,10 @@ export function usePagination<TResponse, TItem, TExtraParams = object>({
     setPageState(1); // Reset to first page when limit changes
   }, []);
 
+  const setTotal = useCallback((newTotal: number) => {
+    setTotalState(newTotal);
+  }, []);
+
   const nextPage = useCallback(() => {
     if (hasNext) {
       setPageState((p) => p + 1);
@@ -220,28 +119,46 @@ export function usePagination<TResponse, TItem, TExtraParams = object>({
     }
   }, [hasPrev]);
 
-  const refetch = useCallback(() => {
-    void fetchData(true);
-  }, [fetchData]);
-
-  const silentRefetch = useCallback(() => {
-    void fetchData(false);
-  }, [fetchData]);
-
-  const pagination: PaginationState = {
+  return {
     page,
     limit,
+    offset,
     total,
     totalPages,
     hasNext,
     hasPrev,
     setPage,
     setLimit,
+    setTotal,
     nextPage,
     prevPage,
-    refetch,
-    silentRefetch,
   };
+}
 
-  return { items, loading, error, pagination };
+/**
+ * Helper hook to sync query total with pagination state.
+ * Use this to automatically update pagination.total when query data changes.
+ *
+ * @example
+ * ```tsx
+ * const pagination = usePagination({ defaultLimit: 20 });
+ *
+ * const { data, isLoading } = notificationClient.getNotifications.useQuery({
+ *   limit: pagination.limit,
+ *   offset: pagination.offset,
+ * });
+ *
+ * // Auto-sync total from response
+ * usePaginationSync(pagination, data?.total);
+ * ```
+ */
+export function usePaginationSync(
+  pagination: PaginationState,
+  total: number | undefined
+): void {
+  useEffect(() => {
+    if (total !== undefined) {
+      pagination.setTotal(total);
+    }
+  }, [total, pagination]);
 }

package/src/hooks/usePagination.e2e.ts

@@ -1,275 +0,0 @@
-import { describe, it, expect, mock } from "bun:test";
-import { renderHook, act } from "@checkstack/test-utils-frontend";
-import { usePagination } from "./usePagination";
-
-describe("usePagination", () => {
-  // Create a deferred promise for controlled async testing
-  interface MockResponse {
-    items: { id: string; name: string }[];
-    total: number;
-  }
-
-  const createControlledMock = () => {
-    let resolvePromise: ((value: MockResponse) => void) | null = null;
-    const mockFn = mock(
-      ({
-        limit,
-        offset,
-      }: {
-        limit: number;
-        offset: number;
-      }): Promise<MockResponse> => {
-        return new Promise((resolve) => {
-          resolvePromise = resolve;
-          // Auto-resolve after a microtask to simulate instant response
-          queueMicrotask(() => {
-            resolve({
-              items: Array.from(
-                { length: Math.min(limit, 100 - offset) },
-                (_, i) => ({
-                  id: `item-${offset + i}`,
-                  name: `Item ${offset + i}`,
-                })
-              ),
-              total: 100,
-            });
-          });
-        });
-      }
-    );
-    return { mockFn, getResolver: () => resolvePromise };
-  };
-
-  // Simple sync mock for tests that don't need controlled timing
-  const createSyncMock = () =>
-    mock(({ limit, offset }: { limit: number; offset: number }) =>
-      Promise.resolve({
-        items: Array.from(
-          { length: Math.min(limit, 100 - offset) },
-          (_, i) => ({
-            id: `item-${offset + i}`,
-            name: `Item ${offset + i}`,
-          })
-        ),
-        total: 100,
-      })
-    );
-
-  it("should initialize with correct defaults", () => {
-    const mockFetchFn = createSyncMock();
-
-    const { result } = renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        fetchOnMount: false,
-      })
-    );
-
-    expect(result.current.loading).toBe(false);
-    expect(result.current.items).toEqual([]);
-    expect(result.current.pagination.page).toBe(1);
-    expect(result.current.pagination.limit).toBe(10);
-    expect(result.current.pagination.total).toBe(0);
-    expect(result.current.pagination.totalPages).toBe(1);
-  });
-
-  it("should not fetch on mount when fetchOnMount is false", () => {
-    const mockFetchFn = createSyncMock();
-
-    renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        fetchOnMount: false,
-      })
-    );
-
-    expect(mockFetchFn).not.toHaveBeenCalled();
-  });
-
-  it("should start loading immediately when fetchOnMount is true", () => {
-    const mockFetchFn = createSyncMock();
-
-    const { result } = renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        defaultLimit: 10,
-      })
-    );
-
-    // Should be loading immediately after render
-    expect(result.current.loading).toBe(true);
-    expect(mockFetchFn).toHaveBeenCalledWith({ limit: 10, offset: 0 });
-  });
-
-  it("should call fetch with correct params on mount", async () => {
-    const { mockFn } = createControlledMock();
-
-    renderHook(() =>
-      usePagination({
-        fetchFn: mockFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        defaultLimit: 20,
-      })
-    );
-
-    expect(mockFn).toHaveBeenCalledWith({ limit: 20, offset: 0 });
-  });
-
-  it("should pass extra params to fetch function", async () => {
-    const { mockFn } = createControlledMock();
-
-    renderHook(() =>
-      usePagination({
-        fetchFn: mockFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        defaultLimit: 10,
-        extraParams: { unreadOnly: true, category: "alerts" },
-      })
-    );
-
-    expect(mockFn).toHaveBeenCalledWith({
-      limit: 10,
-      offset: 0,
-      unreadOnly: true,
-      category: "alerts",
-    });
-  });
-
-  it("should update page when setPage is called", async () => {
-    const mockFetchFn = createSyncMock();
-
-    const { result } = renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        fetchOnMount: false,
-      })
-    );
-
-    act(() => {
-      result.current.pagination.setPage(5);
-    });
-
-    expect(result.current.pagination.page).toBe(5);
-    // Should trigger fetch with correct offset
-    expect(mockFetchFn).toHaveBeenCalledWith({ limit: 10, offset: 40 });
-  });
-
-  it("should update limit and reset to page 1 when setLimit is called", async () => {
-    const mockFetchFn = createSyncMock();
-
-    const { result } = renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        fetchOnMount: false,
-      })
-    );
-
-    // First go to page 3
-    act(() => {
-      result.current.pagination.setPage(3);
-    });
-
-    expect(result.current.pagination.page).toBe(3);
-
-    // Then change limit
-    act(() => {
-      result.current.pagination.setLimit(25);
-    });
-
-    // Should reset to page 1
-    expect(result.current.pagination.page).toBe(1);
-    expect(result.current.pagination.limit).toBe(25);
-    // Should fetch with new limit at offset 0
-    expect(mockFetchFn).toHaveBeenLastCalledWith({ limit: 25, offset: 0 });
-  });
-
-  it("should call nextPage correctly", async () => {
-    const mockFetchFn = createSyncMock();
-
-    const { result } = renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        fetchOnMount: false,
-      })
-    );
-
-    // First set page to 1 (which triggers fetch that sets total)
-    act(() => {
-      result.current.pagination.setPage(1);
-    });
-
-    // After fetch completes, hasNext should be calculated based on total
-    // Since our mock returns total: 100 and limit: 10, hasNext should be true
-    // We need to manually set up the condition where hasNext is true
-    // For now, test that nextPage at least calls the function - even if hasNext blocks it
-    const callsBefore = mockFetchFn.mock.calls.length;
-
-    act(() => {
-      result.current.pagination.nextPage();
-    });
-
-    // nextPage should attempt to increment page (if hasNext allows)
-    // The actual behavior depends on whether fetchData has completed
-    // Since we can't await async in happy-dom, just verify the method doesn't throw
-    expect(mockFetchFn.mock.calls.length).toBeGreaterThanOrEqual(callsBefore);
-  });
-
-  it("should call prevPage correctly", async () => {
-    const mockFetchFn = createSyncMock();
-
-    const { result } = renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        fetchOnMount: false,
-      })
-    );
-
-    // Go to page 3 first
-    act(() => {
-      result.current.pagination.setPage(3);
-    });
-
-    act(() => {
-      result.current.pagination.prevPage();
-    });
-
-    expect(result.current.pagination.page).toBe(2);
-  });
-
-  it("should trigger refetch when refetch is called", async () => {
-    const mockFetchFn = createSyncMock();
-
-    const { result } = renderHook(() =>
-      usePagination({
-        fetchFn: mockFetchFn,
-        getItems: (r) => r.items,
-        getTotal: (r) => r.total,
-        fetchOnMount: false,
-      })
-    );
-
-    const initialCallCount = mockFetchFn.mock.calls.length;
-
-    act(() => {
-      result.current.pagination.refetch();
-    });
-
-    expect(mockFetchFn.mock.calls.length).toBeGreaterThan(initialCallCount);
-  });
-});