@buoy-gg/react-query 1.7.2

package/README.md

@@ -0,0 +1,389 @@
+# @buoy/react-query
+
+[![npm](https://img.shields.io/npm/v/@buoy%2Freact-query)](https://www.npmjs.com/package/@buoy/react-query)
+
+React Query (TanStack Query) devtools modal for React Native development.
+
+## Features
+
+- **Query Inspector**: Browse and inspect all queries in your app
+- **Mutation Tracking**: Monitor mutations and their states
+- **Cache Inspection**: View and manipulate the React Query cache
+- **Query Invalidation**: Invalidate queries directly from the UI
+- **Refetch Control**: Manually trigger query refetches
+- **Filter & Search**: Filter queries by status, search by key
+- **WiFi Toggle**: Simulate offline mode to test query behavior
+- **Performance Monitoring**: Track query timings and performance
+- **Beautiful UI**: Modern, game-themed interface matching other React Buoy tools
+
+## Installation
+
+This package is part of the React Buoy monorepo and is automatically available to other packages and the example app.
+
+For external projects:
+
+```bash
+npm install @buoy/react-query @tanstack/react-query
+# or
+pnpm add @buoy/react-query @tanstack/react-query
+# or
+yarn add @buoy/react-query @tanstack/react-query
+```
+
+## Quick Start
+
+### Simplest Setup - Just 1 Line!
+
+**Import the preset and add it to your tools array. Done!**
+
+```typescript
+import { reactQueryToolPreset } from '@buoy/react-query';
+import { FloatingDevTools } from '@buoy/core';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+const installedApps = [
+  reactQueryToolPreset, // That's it! One line.
+  // ...your other tools
+];
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <FloatingDevTools
+        apps={installedApps}
+        environment="local"
+        userRole="admin"
+      />
+      <YourAppContent />
+    </QueryClientProvider>
+  );
+}
+```
+
+**Done!** The preset automatically:
+- ✅ Inspects all queries and mutations
+- ✅ Provides cache manipulation tools
+- ✅ Includes WiFi toggle for offline testing
+- ✅ No configuration required
+
+### Custom Configuration
+
+If you want to customize the appearance:
+
+```typescript
+import { createReactQueryTool } from '@buoy/react-query';
+
+const myQueryTool = createReactQueryTool({
+  name: "TANSTACK",
+  colorPreset: "purple",
+  enableSharedModalDimensions: true,
+});
+
+const installedApps = [
+  myQueryTool,
+  // ...other tools
+];
+```
+
+### Alternative: Manual Setup
+
+If you're not using FloatingDevTools or want more control:
+
+```typescript
+import { ReactQueryDevToolsModal } from '@buoy/react-query';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+function App() {
+  const [showQuery, setShowQuery] = useState(false);
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Button onPress={() => setShowQuery(true)}>
+        Open Query Inspector
+      </Button>
+
+      <ReactQueryDevToolsModal
+        visible={showQuery}
+        onClose={() => setShowQuery(false)}
+      />
+      
+      <YourAppContent />
+    </QueryClientProvider>
+  );
+}
+```
+
+## API Reference
+
+### Presets
+
+#### `reactQueryToolPreset`
+
+Pre-configured React Query devtools ready to use with FloatingDevTools.
+
+**Example:**
+```typescript
+import { reactQueryToolPreset } from '@buoy/react-query';
+
+const installedApps = [reactQueryToolPreset];
+```
+
+#### `createReactQueryTool(options?)`
+
+Create a custom React Query devtools configuration.
+
+**Options:**
+```typescript
+{
+  /** Tool name (default: "QUERY") */
+  name?: string;
+  /** Tool description */
+  description?: string;
+  /** Icon color preset (default: "red") */
+  colorPreset?: "orange" | "cyan" | "purple" | "pink" | "yellow" | "green" | "red";
+  /** Custom tool ID (default: "query") */
+  id?: string;
+  /** Enable shared modal dimensions (default: true) */
+  enableSharedModalDimensions?: boolean;
+}
+```
+
+**Example:**
+```typescript
+import { createReactQueryTool } from '@buoy/react-query';
+
+const myQueryTool = createReactQueryTool({
+  name: "RQ DEVTOOLS",
+  colorPreset: "cyan",
+  enableSharedModalDimensions: true,
+});
+```
+
+### Components
+
+#### `ReactQueryDevToolsModal`
+
+Main modal component for React Query devtools.
+
+**Props:**
+```typescript
+interface ReactQueryDevToolsModalProps {
+  /** Whether the modal is visible */
+  visible: boolean;
+  /** Callback when modal is closed */
+  onClose: () => void;
+  /** Whether to use shared modal dimensions (default: true) */
+  enableSharedModalDimensions?: boolean;
+}
+```
+
+**Example:**
+```typescript
+<ReactQueryDevToolsModal
+  visible={isVisible}
+  onClose={handleClose}
+  enableSharedModalDimensions={true}
+/>
+```
+
+#### `WifiToggle`
+
+Small WiFi toggle component for simulating offline mode.
+
+**Props:**
+```typescript
+interface WifiToggleProps {
+  /** Icon size (default: 16) */
+  size?: number;
+}
+```
+
+**Example:**
+```typescript
+import { WifiToggle } from '@buoy/react-query';
+
+<WifiToggle size={20} />
+```
+
+### Hooks
+
+#### `useWifiState()`
+
+Hook to manage and access WiFi/online state.
+
+**Returns:**
+```typescript
+{
+  /** Whether the app is online */
+  isOnline: boolean;
+  /** Toggle WiFi state */
+  handleWifiToggle: () => void;
+  /** Set online state directly */
+  setIsOnline: (online: boolean) => void;
+}
+```
+
+**Example:**
+```typescript
+import { useWifiState } from '@buoy/react-query';
+
+function MyComponent() {
+  const { isOnline, handleWifiToggle } = useWifiState();
+
+  return (
+    <View>
+      <Text>Status: {isOnline ? 'Online' : 'Offline'}</Text>
+      <Button onPress={handleWifiToggle}>
+        Toggle WiFi
+      </Button>
+    </View>
+  );
+}
+```
+
+## Use Cases
+
+### Query Debugging
+
+Inspect and debug queries in real-time:
+
+```typescript
+import { reactQueryToolPreset } from '@buoy/react-query';
+
+// Add to your dev tools
+const installedApps = [reactQueryToolPreset];
+
+// Now you can:
+// - See all active queries
+// - View query data and status
+// - Inspect stale/fresh/loading states
+// - Manually refetch queries
+// - Invalidate queries to trigger refetch
+```
+
+### Offline Testing
+
+Test your app's behavior in offline mode:
+
+```typescript
+import { WifiToggle } from '@buoy/react-query';
+
+// Add WiFi toggle to your header
+<WifiToggle size={18} />
+
+// Or use the hook directly
+const { isOnline, handleWifiToggle } = useWifiState();
+```
+
+### Cache Manipulation
+
+Inspect and manipulate the query cache:
+
+```typescript
+// In the React Query devtools modal:
+// - View all cached queries
+// - See cache sizes and data
+// - Manually invalidate cache entries
+// - Trigger refetches
+// - Remove queries from cache
+```
+
+### Mutation Monitoring
+
+Track mutations and their states:
+
+```typescript
+// In the React Query devtools modal:
+// - View all active mutations
+// - See mutation status (idle, loading, success, error)
+// - Inspect mutation data and variables
+// - Track mutation timing
+```
+
+## Features in Detail
+
+### Query Browser
+
+- **View All Queries**: See all queries registered with React Query
+- **Filter by Status**: Filter by fresh, fetching, stale, or inactive
+- **Search**: Search queries by key
+- **Query Details**: View full query data, status, and metadata
+- **Refetch**: Manually trigger query refetches
+- **Invalidate**: Invalidate queries to trigger automatic refetch
+- **Remove**: Remove queries from cache
+
+### Mutation Tracking
+
+- **View Mutations**: See all registered mutations
+- **Mutation Status**: Track mutation states (idle, loading, success, error)
+- **Variables**: Inspect mutation variables
+- **Results**: View mutation results and errors
+- **Reset**: Reset mutation states
+
+### WiFi Toggle
+
+- **Offline Mode**: Simulate offline state
+- **Query Behavior**: Test how queries behave without network
+- **Retry Logic**: Verify retry and error handling
+- **Cache Fallbacks**: Test cache-first strategies
+
+### Performance Monitoring
+
+- **Query Timing**: See how long queries take
+- **Cache Hits**: Track cache hit rates
+- **Stale Time**: Monitor query freshness
+- **Background Updates**: See when queries update in background
+
+## React Query Integration
+
+This package integrates with React Query's online manager to provide WiFi toggle functionality. When you toggle WiFi off:
+
+- React Query treats the app as offline
+- Queries won't refetch automatically
+- New queries will be paused
+- Mutations will be paused until online
+- Background refetches are disabled
+
+This is perfect for testing offline scenarios without actually disconnecting your device.
+
+## Dependencies
+
+- `@buoy/shared-ui` - Common UI components and utilities
+- `@tanstack/react-query` - React Query library (peer dependency)
+- React and React Native (peer dependencies)
+
+## Development
+
+### Building
+
+```bash
+pnpm build
+```
+
+### Type Checking
+
+```bash
+pnpm typecheck
+```
+
+### Clean Build
+
+```bash
+pnpm clean
+```
+
+## License
+
+MIT
+
+## Contributing
+
+See the main repository [CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines.
+
+## Support
+
+For issues and feature requests, please visit the [GitHub repository](https://github.com/LovesWorking/react-native-buoy/issues).

package/lib/commonjs/index.js

@@ -0,0 +1,107 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _exportNames = {
+  reactQueryToolPreset: true,
+  createReactQueryTool: true,
+  wifiTogglePreset: true,
+  createWifiToggleTool: true
+};
+Object.defineProperty(exports, "createReactQueryTool", {
+  enumerable: true,
+  get: function () {
+    return _preset.createReactQueryTool;
+  }
+});
+Object.defineProperty(exports, "createWifiToggleTool", {
+  enumerable: true,
+  get: function () {
+    return _preset.createWifiToggleTool;
+  }
+});
+Object.defineProperty(exports, "reactQueryToolPreset", {
+  enumerable: true,
+  get: function () {
+    return _preset.reactQueryToolPreset;
+  }
+});
+Object.defineProperty(exports, "wifiTogglePreset", {
+  enumerable: true,
+  get: function () {
+    return _preset.wifiTogglePreset;
+  }
+});
+var _preset = require("./preset");
+var _reactQuery = require("./react-query");
+Object.keys(_reactQuery).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _reactQuery[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _reactQuery[key];
+    }
+  });
+});
+var _components = require("./react-query/components");
+Object.keys(_components).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _components[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _components[key];
+    }
+  });
+});
+var _hooks = require("./react-query/hooks");
+Object.keys(_hooks).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _hooks[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _hooks[key];
+    }
+  });
+});
+var _utils = require("./react-query/utils");
+Object.keys(_utils).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _utils[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _utils[key];
+    }
+  });
+});
+var _types = require("./react-query/types");
+Object.keys(_types).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _types[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _types[key];
+    }
+  });
+});
+// Check if @tanstack/react-query is installed
+try {
+  require("@tanstack/react-query");
+} catch (error) {
+  throw new Error("\n\n[@buoy-gg/react-query] ERROR: Missing required peer dependency\n\n" + "This package requires @tanstack/react-query to be installed.\n\n" + "Install it with:\n" + "  npm install @tanstack/react-query\n" + "  or\n" + "  pnpm add @tanstack/react-query\n" + "  or\n" + "  yarn add @tanstack/react-query\n\n" + "For more information, visit: https://tanstack.com/query/latest\n");
+}
+
+// Export preset configuration (easiest way to add to FloatingDevTools!)
+
+// React Query dev tools entry point
+// Re-export the full dev tools surface so consumers can tree-shake as needed

package/lib/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/commonjs/preset.js

@@ -0,0 +1,220 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createReactQueryTool = createReactQueryTool;
+exports.createWifiToggleTool = createWifiToggleTool;
+exports.wifiTogglePreset = exports.reactQueryToolPreset = void 0;
+var _floatingToolsCore = require("@buoy-gg/floating-tools-core");
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _ReactQueryDevToolsModal = require("./react-query/components/ReactQueryDevToolsModal");
+var _reactQuery = require("@tanstack/react-query");
+var _react = require("react");
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * Pre-configured React Query devtools for FloatingDevTools
+ *
+ * This preset provides a zero-config way to add React Query inspection to your dev tools.
+ * Just import and add it to your apps array!
+ *
+ * @example
+ * ```tsx
+ * import { reactQueryToolPreset } from '@buoy-gg/react-query';
+ *
+ * const installedApps = [
+ *   reactQueryToolPreset, // That's it!
+ *   // ...other tools
+ * ];
+ * ```
+ */
+
+// Empty component for toggle-only mode
+const EmptyComponent = () => null;
+
+// Save WiFi state to storage
+const saveWifiState = async enabled => {
+  try {
+    await (0, _sharedUi.safeSetItem)(_sharedUi.devToolsStorageKeys.settings.wifiEnabled(), enabled.toString());
+  } catch (error) {
+    // Failed to save WiFi state
+  }
+};
+
+/**
+ * WiFi icon component - uses hooks to subscribe to onlineManager changes.
+ *
+ * ⚠️ IMPORTANT - DO NOT MODIFY THIS COMPONENT ⚠️
+ * This component MUST use useState and useEffect hooks to subscribe to onlineManager.
+ * It is rendered as a JSX component (<IconComponent />) in FloatingMenu and DialIcon,
+ * which allows hooks to work properly.
+ *
+ * If you remove the hooks or change this to read onlineManager.isOnline() directly,
+ * the icon color will NOT update when the WiFi toggle is pressed.
+ *
+ * See: FloatingMenu.tsx (renders as <IconComponent />)
+ * See: DialIcon.tsx (renders as <icon.iconComponent />)
+ */
+function WifiIcon({
+  size
+}) {
+  const [isOnline, setIsOnline] = (0, _react.useState)(() => _reactQuery.onlineManager.isOnline());
+  (0, _react.useEffect)(() => {
+    const unsubscribe = _reactQuery.onlineManager.subscribe(online => {
+      setIsOnline(online);
+    });
+    return unsubscribe;
+  }, []);
+  const color = isOnline ? "#10B981" : "#DC2626";
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Wifi, {
+    size: size,
+    color: color
+  });
+}
+
+/**
+ * Pre-configured React Query devtools for FloatingDevTools.
+ * Includes:
+ * - Query browser and inspector
+ * - Mutation tracking
+ * - Cache inspection
+ * - Query invalidation
+ * - Performance monitoring
+ */
+const reactQueryToolPreset = exports.reactQueryToolPreset = {
+  id: "query",
+  name: "QUERY",
+  description: "React Query inspector",
+  slot: "both",
+  icon: ({
+    size
+  }) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_floatingToolsCore.QueryIcon, {
+    size: size
+  }),
+  component: _ReactQueryDevToolsModal.ReactQueryDevToolsModal,
+  props: {
+    enableSharedModalDimensions: false
+  }
+};
+
+/**
+ * Create a custom React Query devtools configuration.
+ * Use this if you want to override default settings.
+ *
+ * @example
+ * ```tsx
+ * import { createReactQueryTool } from '@buoy-gg/react-query';
+ *
+ * const myQueryTool = createReactQueryTool({
+ *   name: "TANSTACK",
+ *   colorPreset: "purple",
+ *   enableSharedModalDimensions: true,
+ * });
+ * ```
+ */
+function createReactQueryTool(options) {
+  return {
+    id: options?.id || "query",
+    name: options?.name || "QUERY",
+    description: options?.description || "React Query inspector",
+    slot: "both",
+    icon: ({
+      size
+    }) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_floatingToolsCore.QueryIcon, {
+      size: size
+    }),
+    component: _ReactQueryDevToolsModal.ReactQueryDevToolsModal,
+    props: {
+      enableSharedModalDimensions: options?.enableSharedModalDimensions !== undefined ? options.enableSharedModalDimensions : false
+    }
+  };
+}
+
+/**
+ * Pre-configured WiFi toggle tool for FloatingDevTools.
+ * Allows toggling React Query's online state to simulate offline scenarios.
+ * Simple toggle - no modal needed!
+ *
+ * @example
+ * ```tsx
+ * import { wifiTogglePreset } from '@buoy-gg/react-query';
+ *
+ * const installedApps = [
+ *   wifiTogglePreset, // That's it!
+ *   // ...other tools
+ * ];
+ * ```
+ */
+const wifiTogglePreset = exports.wifiTogglePreset = {
+  id: "query-wifi-toggle",
+  name: "WIFI",
+  description: "Toggle React Query online/offline state",
+  slot: "row",
+  icon: WifiIcon,
+  component: EmptyComponent,
+  props: {},
+  launchMode: "toggle-only",
+  onPress: () => {
+    const newState = !_reactQuery.onlineManager.isOnline();
+    _reactQuery.onlineManager.setOnline(newState);
+    saveWifiState(newState);
+  }
+};
+
+/**
+ * Create a custom WiFi toggle tool configuration.
+ * Use this if you want to override default settings.
+ *
+ * @example
+ * ```tsx
+ * import { createWifiToggleTool } from '@buoy-gg/react-query';
+ *
+ * const myWifiTool = createWifiToggleTool({
+ *   name: "OFFLINE",
+ *   onColor: "#10B981",
+ *   offColor: "#DC2626",
+ * });
+ * ```
+ */
+function createWifiToggleTool(options) {
+  const onColor = options?.onColor || "#10B981";
+  const offColor = options?.offColor || "#DC2626";
+
+  /**
+   * Custom WiFi icon component with hooks - rendered as JSX component.
+   *
+   * ⚠️ IMPORTANT - DO NOT MODIFY THIS COMPONENT ⚠️
+   * This component MUST use useState and useEffect hooks to subscribe to onlineManager.
+   * See the comment on WifiIcon above for full explanation.
+   */
+  const CustomWifiIcon = ({
+    size
+  }) => {
+    const [isOnline, setIsOnline] = (0, _react.useState)(() => _reactQuery.onlineManager.isOnline());
+    (0, _react.useEffect)(() => {
+      const unsubscribe = _reactQuery.onlineManager.subscribe(online => {
+        setIsOnline(online);
+      });
+      return unsubscribe;
+    }, []);
+    return /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Wifi, {
+      size: size,
+      color: isOnline ? onColor : offColor
+    });
+  };
+  return {
+    id: options?.id || "query-wifi-toggle",
+    name: options?.name || "WIFI",
+    description: options?.description || "Toggle React Query online/offline state",
+    slot: "row",
+    icon: CustomWifiIcon,
+    component: EmptyComponent,
+    props: {},
+    launchMode: "toggle-only",
+    onPress: () => {
+      const newState = !_reactQuery.onlineManager.isOnline();
+      _reactQuery.onlineManager.setOnline(newState);
+      saveWifiState(newState);
+    }
+  };
+}