@checkstack/ui 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # @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
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+### Patch Changes
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [f533141]
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

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

package/src/components/{PermissionDenied.tsx → AccessDenied.tsx}

@@ -3,13 +3,10 @@ import { ShieldAlert } from "lucide-react";
 import { Card, CardHeader, CardTitle, CardContent } from "./Card";
 import { cn } from "../utils";
 
-export const PermissionDenied: React.FC<{
+export const AccessDenied: React.FC<{
   message?: string;
   className?: string;
-}> = ({
-  message = "You do not have permission to view this page.",
-  className,
-}) => {
+}> = ({ message = "You do not have access to this page.", className }) => {
   return (
     <div
       className={cn(

package/src/components/AccessGate.tsx

@@ -0,0 +1,97 @@
+import React from "react";
+import { AccessDenied } from "./AccessDenied";
+import { LoadingSpinner } from "./LoadingSpinner";
+
+/**
+ * Props for the AccessGate component.
+ */
+export interface AccessGateProps {
+  /**
+   * The access rule ID to check for access.
+   */
+  accessRuleId: string;
+  /**
+   * Content to render when access is granted.
+   */
+  children: React.ReactNode;
+  /**
+   * Custom fallback to render when access is denied.
+   * If not provided and showDenied is false, renders nothing.
+   */
+  fallback?: React.ReactNode;
+  /**
+   * If true, shows a AccessDenied component when access is denied.
+   * Useful for entire page sections. Overridden by fallback if provided.
+   */
+  showDenied?: boolean;
+  /**
+   * Custom message to show in the AccessDenied component.
+   */
+  deniedMessage?: string;
+  /**
+   * Hook to check access. Must be provided by the consumer.
+   * This allows the component to be used without depending on auth-frontend directly.
+   */
+  useAccess: (accessRuleId: string) => { loading: boolean; allowed: boolean };
+}
+
+/**
+ * Conditionally renders children based on whether the user has a required access rule.
+ *
+ * @example
+ * // Hide content if access denied
+ * <AccessGate accessRuleId="catalog.manage" useAccess={accessApi.useAccess}>
+ *   <ManageButton />
+ * </AccessGate>
+ *
+ * @example
+ * // Show access denied message
+ * <AccessGate
+ *   accessRuleId="catalog.read"
+ *   useAccess={accessApi.useAccess}
+ *   showDenied
+ *   deniedMessage="You don't have access to view the catalog."
+ * >
+ *   <CatalogList />
+ * </AccessGate>
+ *
+ * @example
+ * // Custom fallback
+ * <AccessGate
+ *   accessRuleId="admin.manage"
+ *   useAccess={accessApi.useAccess}
+ *   fallback={<p>Admin access required</p>}
+ * >
+ *   <AdminPanel />
+ * </AccessGate>
+ */
+export const AccessGate: React.FC<AccessGateProps> = ({
+  accessRuleId,
+  children,
+  fallback,
+  showDenied = false,
+  deniedMessage,
+  useAccess,
+}) => {
+  const { loading, allowed } = useAccess(accessRuleId);
+
+  if (loading) {
+    return <LoadingSpinner size="sm" />;
+  }
+
+  if (!allowed) {
+    if (fallback) {
+      return <>{fallback}</>;
+    }
+    if (showDenied) {
+      return (
+        <AccessDenied
+          message={deniedMessage ?? `You don't have access: ${accessRuleId}`}
+        />
+      );
+    }
+    return <></>;
+  }
+
+  return <>{children}</>;
+};

package/src/components/NavItem.tsx

@@ -2,13 +2,15 @@ import React, { useState, useRef, useEffect } from "react";
 import { NavLink } from "react-router-dom";
 import { ChevronDown } from "lucide-react";
 import { cn } from "../utils";
-import { useApi, permissionApiRef } from "@checkstack/frontend-api";
+import { useApi, accessApiRef } from "@checkstack/frontend-api";
+import type { AccessRule } from "@checkstack/common";
 
 export interface NavItemProps {
   to?: string;
   label: string;
   icon?: React.ReactNode;
-  permission?: string;
+  /** Access rule to check - if not provided, always shows */
+  accessRule?: AccessRule;
   children?: React.ReactNode;
   className?: string;
 }
@@ -17,7 +19,7 @@ export const NavItem: React.FC<NavItemProps> = ({
   to,
   label,
   icon,
-  permission,
+  accessRule,
   children,
   className,
 }) => {
@@ -25,11 +27,17 @@ export const NavItem: React.FC<NavItemProps> = ({
   const containerRef = useRef<HTMLDivElement>(null);
 
   // Always call hooks at top level
-  // We assume permissionApi is available if we use it. Safe fallback?
-  // ApiProvider guarantees it if registered. App.tsx registers a default.
-  const permissionApi = useApi(permissionApiRef);
-  const { allowed, loading } = permissionApi.usePermission(permission || "");
-  const hasAccess = permission ? allowed : true;
+  const accessApi = useApi(accessApiRef);
+
+  // Create a dummy access rule for when accessRule is undefined
+  const dummyRule: AccessRule = {
+    id: "",
+    resource: "",
+    level: "read",
+    description: "",
+  };
+  const { allowed, loading } = accessApi.useAccess(accessRule ?? dummyRule);
+  const hasAccess = accessRule ? allowed : true;
 
   // Handle click outside for dropdown
   useEffect(() => {

package/src/components/PageLayout.tsx

@@ -4,7 +4,7 @@ import {
   PageHeader,
   PageContent,
   LoadingSpinner,
-  PermissionDenied,
+  AccessDenied,
 } from "..";
 
 interface PageLayoutProps {
@@ -39,7 +39,7 @@ export const PageLayout: React.FC<PageLayoutProps> = ({
 }) => {
   // If loading is explicitly true, show loading state
   // If loading is undefined and allowed is false, also show loading state
-  // (this prevents "Access Denied" flash when permissions are still being fetched)
+  // (this prevents "Access Denied" flash when access rules are still being fetched)
   const isLoading =
     loading === true || (loading === undefined && allowed === false);
 
@@ -56,13 +56,13 @@ export const PageLayout: React.FC<PageLayoutProps> = ({
     );
   }
 
-  // Only show permission denied when loading is explicitly false and allowed is false
+  // Only show access denied when loading is explicitly false and allowed is false
   if (allowed === false) {
     return (
       <Page>
         <PageHeader title={title} subtitle={subtitle} actions={actions} />
         <PageContent>
-          <PermissionDenied />
+          <AccessDenied />
         </PageContent>
       </Page>
     );

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/index.ts

@@ -3,8 +3,8 @@ export * from "./components/Input";
 export * from "./components/Card";
 export * from "./components/Label";
 export * from "./components/NavItem";
-export * from "./components/PermissionDenied";
-export * from "./components/PermissionGate";
+export * from "./components/AccessDenied";
+export * from "./components/AccessGate";
 export * from "./components/SectionHeader";
 export * from "./components/StatusCard";
 export * from "./components/EmptyState";

package/src/components/PermissionGate.tsx

@@ -1,97 +0,0 @@
-import React from "react";
-import { PermissionDenied } from "./PermissionDenied";
-import { LoadingSpinner } from "./LoadingSpinner";
-
-/**
- * Props for the PermissionGate component.
- */
-export interface PermissionGateProps {
-  /**
-   * The permission ID to check for access.
-   */
-  permission: string;
-  /**
-   * Content to render when permission is granted.
-   */
-  children: React.ReactNode;
-  /**
-   * Custom fallback to render when permission is denied.
-   * If not provided and showDenied is false, renders nothing.
-   */
-  fallback?: React.ReactNode;
-  /**
-   * If true, shows a PermissionDenied component when access is denied.
-   * Useful for entire page sections. Overridden by fallback if provided.
-   */
-  showDenied?: boolean;
-  /**
-   * Custom message to show in the PermissionDenied component.
-   */
-  deniedMessage?: string;
-  /**
-   * Hook to check permissions. Must be provided by the consumer.
-   * This allows the component to be used without depending on auth-frontend directly.
-   */
-  usePermission: (permission: string) => { loading: boolean; allowed: boolean };
-}
-
-/**
- * Conditionally renders children based on whether the user has a required permission.
- *
- * @example
- * // Hide content if permission denied
- * <PermissionGate permission="catalog.manage" usePermission={permissionApi.usePermission}>
- *   <ManageButton />
- * </PermissionGate>
- *
- * @example
- * // Show permission denied message
- * <PermissionGate
- *   permission="catalog.read"
- *   usePermission={permissionApi.usePermission}
- *   showDenied
- *   deniedMessage="You don't have access to view the catalog."
- * >
- *   <CatalogList />
- * </PermissionGate>
- *
- * @example
- * // Custom fallback
- * <PermissionGate
- *   permission="admin.manage"
- *   usePermission={permissionApi.usePermission}
- *   fallback={<p>Admin access required</p>}
- * >
- *   <AdminPanel />
- * </PermissionGate>
- */
-export const PermissionGate: React.FC<PermissionGateProps> = ({
-  permission,
-  children,
-  fallback,
-  showDenied = false,
-  deniedMessage,
-  usePermission,
-}) => {
-  const { loading, allowed } = usePermission(permission);
-
-  if (loading) {
-    return <LoadingSpinner size="sm" />;
-  }
-
-  if (!allowed) {
-    if (fallback) {
-      return <>{fallback}</>;
-    }
-    if (showDenied) {
-      return (
-        <PermissionDenied
-          message={deniedMessage ?? `You don't have permission: ${permission}`}
-        />
-      );
-    }
-    return <></>;
-  }
-
-  return <>{children}</>;
-};

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);
-  });
-});