@checkstack/command-frontend 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @checkstack/command-frontend
 
+## 0.2.0
+
+### Minor 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
+
+### Patch Changes
+
+- Updated dependencies [7a23261]
+  - @checkstack/frontend-api@0.2.0
+  - @checkstack/common@0.3.0
+  - @checkstack/command-common@0.2.0
+  - @checkstack/ui@0.2.1
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/command-frontend",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "exports": {
     ".": {

package/src/components/SearchDialog.tsx

@@ -24,7 +24,12 @@ export const SearchDialog: React.FC<SearchDialogProps> = ({
 }) => {
   const navigate = useNavigate();
   const formatShortcut = useFormatShortcut();
-  const { results, loading, search, reset } = useDebouncedSearch(300);
+  const {
+    results,
+    loading,
+    setQuery: setSearchQuery,
+    reset,
+  } = useDebouncedSearch(300);
 
   const [query, setQuery] = useState("");
   const [selectedIndex, setSelectedIndex] = useState(0);
@@ -34,7 +39,7 @@ export const SearchDialog: React.FC<SearchDialogProps> = ({
   // Trigger search when dialog opens or query changes
   useEffect(() => {
     if (open) {
-      search(query);
+      setSearchQuery(query);
       // Focus input after dialog opens
       setTimeout(() => inputRef.current?.focus(), 50);
     } else {
@@ -43,7 +48,7 @@ export const SearchDialog: React.FC<SearchDialogProps> = ({
       setSelectedIndex(0);
       reset();
     }
-  }, [open, query, search, reset]);
+  }, [open, query, setSearchQuery, reset]);
 
   // Group results by category
   const groupedResults: Record<string, SearchResult[]> = {};

package/src/index.tsx

@@ -1,17 +1,14 @@
-import { useEffect, useCallback, useMemo, useState, useRef } from "react";
+import { useEffect, useCallback, useMemo, useState } from "react";
 import {
-  useApi,
-  rpcApiRef,
-  createApiRef,
   createFrontendPlugin,
   NavbarCenterSlot,
+  usePluginClient,
 } from "@checkstack/frontend-api";
 import {
   CommandApi,
   pluginMetadata,
   type SearchResult,
 } from "@checkstack/command-common";
-import type { InferClient } from "@checkstack/common";
 import { NavbarSearch } from "./components/NavbarSearch";
 
 // =============================================================================
@@ -30,15 +27,6 @@ export const commandPlugin = createFrontendPlugin({
   ],
 });
 
-// =============================================================================
-// API REF
-// =============================================================================
-
-export type CommandApiClient = InferClient<typeof CommandApi>;
-
-export const commandApiRef =
-  createApiRef<CommandApiClient>("plugin.command.api");
-
 // =============================================================================
 // SHORTCUT UTILITIES (Frontend-only - requires DOM types)
 // =============================================================================
@@ -107,6 +95,27 @@ export function formatShortcut(shortcut: string, isMac: boolean): string {
   return isMac ? parts.join("") : parts.join("+");
 }
 
+// =============================================================================
+// DEBOUNCE HOOK
+// =============================================================================
+
+/**
+ * Hook to debounce a value by the specified delay.
+ */
+function useDebouncedValue<T>(value: T, delayMs: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delayMs);
+
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+
+  return debouncedValue;
+}
+
 // =============================================================================
 // HOOKS
 // =============================================================================
@@ -185,105 +194,36 @@ export function useFormatShortcut(): (shortcut: string) => string {
   );
 }
 
-/**
- * Hook to search across all providers via backend RPC.
- * Returns search function and loading state.
- */
-export function useCommandPaletteSearch(): {
-  search: (query: string) => Promise<SearchResult[]>;
-  getCommands: () => Promise<SearchResult[]>;
-  loading: boolean;
-} {
-  const rpcApi = useApi(rpcApiRef);
-  const commandApi = useMemo(() => rpcApi.forPlugin(CommandApi), [rpcApi]);
-  const [loading, setLoading] = useState(false);
-
-  const search = useCallback(
-    async (query: string): Promise<SearchResult[]> => {
-      setLoading(true);
-      try {
-        return await commandApi.search({ query });
-      } finally {
-        setLoading(false);
-      }
-    },
-    [commandApi]
-  );
-
-  const getCommands = useCallback(async (): Promise<SearchResult[]> => {
-    setLoading(true);
-    try {
-      return await commandApi.getCommands();
-    } finally {
-      setLoading(false);
-    }
-  }, [commandApi]);
-
-  return { search, getCommands, loading };
-}
-
 /**
  * Hook for debounced search in the command palette.
- * Automatically debounces the search query by the specified delay.
+ * Uses TanStack Query with a debounced query state.
  */
 export function useDebouncedSearch(delayMs: number = 300): {
   results: SearchResult[];
   loading: boolean;
-  search: (query: string) => void;
+  setQuery: (query: string) => void;
   reset: () => void;
 } {
-  const { search: doSearch, getCommands } = useCommandPaletteSearch();
-  const [results, setResults] = useState<SearchResult[]>([]);
-  const [loading, setLoading] = useState(false);
-  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
-
-  const search = useCallback(
-    (query: string) => {
-      // Clear any pending search
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-      }
-
-      // If empty query, fetch all results immediately (commands + entities)
-      if (!query.trim()) {
-        setLoading(true);
-        doSearch("")
-          .then(setResults)
-          .catch(() => setResults([]))
-          .finally(() => setLoading(false));
-        return;
-      }
-
-      // Debounce non-empty queries
-      setLoading(true);
-      timeoutRef.current = setTimeout(() => {
-        doSearch(query)
-          .then(setResults)
-          .catch(() => setResults([]))
-          .finally(() => setLoading(false));
-      }, delayMs);
-    },
-    [doSearch, getCommands, delayMs]
+  const commandClient = usePluginClient(CommandApi);
+  const [query, setQuery] = useState("");
+  const debouncedQuery = useDebouncedValue(query, delayMs);
+
+  // useQuery automatically refetches when debouncedQuery changes
+  const { data, isLoading } = commandClient.search.useQuery(
+    { query: debouncedQuery },
+    { staleTime: 30_000 } // Cache results for 30 seconds
   );
 
   const reset = useCallback(() => {
-    if (timeoutRef.current) {
-      clearTimeout(timeoutRef.current);
-    }
-    setResults([]);
-    setLoading(false);
-  }, []);
-
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      if (timeoutRef.current) {
-        clearTimeout(timeoutRef.current);
-      }
-    };
+    setQuery("");
   }, []);
 
-  return { results, loading, search, reset };
+  return {
+    results: data ?? [],
+    loading: isLoading,
+    setQuery,
+    reset,
+  };
 }
 
 // =============================================================================
@@ -298,40 +238,20 @@ export function useCommands(): {
   commands: SearchResult[];
   loading: boolean;
 } {
-  const rpcApi = useApi(rpcApiRef);
-  const commandApi = useMemo(() => rpcApi.forPlugin(CommandApi), [rpcApi]);
-  const [commands, setCommands] = useState<SearchResult[]>([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    let cancelled = false;
-
-    async function fetchCommands() {
-      try {
-        const results = await commandApi.getCommands();
-        if (!cancelled) {
-          // Filter to only commands with shortcuts
-          setCommands(
-            results.filter((r) => r.shortcuts && r.shortcuts.length > 0)
-          );
-        }
-      } catch {
-        // Ignore errors - commands just won't be available
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
-    }
+  const commandClient = usePluginClient(CommandApi);
 
-    fetchCommands();
+  // Fetch all commands (empty query returns all)
+  const { data, isLoading } = commandClient.getCommands.useQuery(undefined, {
+    staleTime: 60_000, // Cache for 1 minute
+  });
 
-    return () => {
-      cancelled = true;
-    };
-  }, [commandApi]);
+  // Filter to only commands with shortcuts
+  const commandsWithShortcuts = useMemo(
+    () => (data ?? []).filter((r) => r.shortcuts && r.shortcuts.length > 0),
+    [data]
+  );
 
-  return { commands, loading };
+  return { commands: commandsWithShortcuts, loading: isLoading };
 }
 
 /**