create-bluecopa-react-app 1.0.12 → 1.0.13

package/templates/latest/Agent.md

@@ -73,583 +73,627 @@ export function Component({ className, children }: ComponentProps) {
 - Implement loading and error states
 - Use TanStack Query for caching
 - Handle optimistic updates
-      # @bluecopa/react [![npm version](https://img.shields.io/npm/v/@bluecopa/react)](https://www.npmjs.com/package/@bluecopa/react) [![License](https://img.shields.io/npm/l/@bluecopa/react)](https://github.com/bluecopa/blui/blob/main/packages/react/LICENSE)
-
-      ## A Comprehensive React Query Integration for Bluecopa
-
-      A React library providing opinionated custom hooks for TanStack React Query integration with Bluecopa core API. This package enables efficient data fetching, caching, and synchronization with the Bluecopa platform while maintaining type safety and developer experience.
-
-      ## Table of Contents
-
-      - [@bluecopa/react  ](#bluecopareact--)
-        - [A Comprehensive React Query Integration for Bluecopa](#a-comprehensive-react-query-integration-for-bluecopa)
-        - [Table of Contents](#table-of-contents)
-        - [Features](#features)
-        - [Installation](#installation)
-          - [Peer Dependencies](#peer-dependencies)
-        - [Usage](#usage)
-          - [Query Provider Setup](#query-provider-setup)
-          - [Boilerplate Integration](#boilerplate-integration)
-          - [Hook Examples](#hook-examples)
-            - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
-            - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
-        - [API Documentation](#api-documentation)
-          - [`useUser(options?)`](#useuseroptions)
-          - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
-          - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
-          - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
-          - [`useInputTable(inputTableId, options?)`](#useinputtableinputtableid-options)
-          - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-options)
-          - [`useGetPublishedWorkbookById(workbookId, options?)`](#usegetpublishedworkbookbyidworkbookid-options)
-          - [`useGetTableById(tableId, options?)`](#usegettablebyidtableid-options)
-          - [`useGetWorkbooksByType(workbookType, options?)`](#usegetworkbooksbytypeworkbooktype-options)
-          - [`useGetWorkflowInstanceStatusById(instanceId, options?)`](#usegetworkflowinstancestatusbyidinstanceid-options)
-          - [`useGetWorksheets(options?)`](#usegetworksheetsoptions)
-          - [`useGetWorksheetsByType(worksheetType, options?)`](#usegetworksheetsbytypeworksheettype-options)
-          - [`useRunDefinition(definitionId, options?)`](#userundefinitiondefinitionid-options)
-          - [`useRunPublishedDefinition(publishedDefinitionId, options?)`](#userunpublisheddefinitionpublisheddefinitionid-options)
-          - [`useRunSampleDefinition(sampleDefinitionId, options?)`](#userunsampledefinitionsampledefinitionid-options)
-          - [`useTriggerHttpWorkflow(workflowId, payload, options?)`](#usetriggerhttpworkflowworkflowid-payload-options)
-          - [`useTriggerWorkflow(workflowId, options?)`](#usetriggerworkflowworkflowid-options)
-          - [`useWorkbook(workbookId, options?)`](#useworkbookworkbookid-options)
-          - [`useWorkflow(workflowId, options?)`](#useworkflowworkflowid-options)
-          - [`useWorksheet(worksheetId, options?)`](#useworksheetworksheetid-options)
-        - [Configuration](#configuration)
-          - [Default Query Configuration](#default-query-configuration)
-          - [Customizable Parameters](#customizable-parameters)
-        - [Advanced Usage](#advanced-usage)
-          - [Error Handling](#error-handling)
-          - [Manual Refetching](#manual-refetching)
-        - [Re-exports](#re-exports)
-        - [TypeScript Support](#typescript-support)
-        - [Development](#development)
-
-      ## Features
-
-      - ✅ First-class TypeScript support with strict type definitions
-      - 🔁 Seamless integration with TanStack React Query (v5+)
-      - 🛡 Comprehensive error handling patterns
-      - ⚙ Optimized default query configuration
-      - 📦 Re-exports of core TanStack React Query utilities
-      - 📊 Sample data preview capabilities
-      - 🧩 Customizable query parameters (limit, caching, retries)
-
-      ## Installation
-
-      ```bash
-      npm install @bluecopa/react
-      # or with pnpm
-      pnpm add @bluecopa/react
-      ```
-
-      ### Peer Dependencies
-
-      This package requires the following in your application:
-
-      ```bash
-      npm install react@^18.0.0 react-dom@^18.0.0
-      ```
-
-      ## Usage
-
-      ### Query Provider Setup
-
-      Wrap your application with the React Query provider:
-
-      ```tsx
-      import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
-
-      const queryClient = new QueryClient({
-        defaultOptions: {
-          queries: {
-            staleTime: 60 * 1000, // 1 minute
-            refetchOnWindowFocus: false,
-          },
-        },
-      });
-
-      function App() {
-        return (
-          <QueryClientProvider client={queryClient}>
-            <YourApp />
-            <ReactQueryDevtools initialIsOpen={false} />
-          </QueryClientProvider>
-        );
-      }
-      ```
-
-      ### Boilerplate Integration
-
-      For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
-
-      ```tsx
-      // src/providers/query-provider.tsx
-      import { ReactQueryDevtools, reactQuery, copaSetConfig } from "@bluecopa/react";
-      import { useEffect, useState } from "react";
-
-      const { QueryClient, QueryClientProvider } = reactQuery;
-
-      export default function QueryProvider({ children }: { children: React.ReactNode }) {
-        const [queryClient] = useState(() => new QueryClient({
-          defaultOptions: {
-            queries: {
-              staleTime: 60 * 1000, // 1 minute
-              refetchOnWindowFocus: false,
-            },
-          },
-        }));
-
-        useEffect(() => {
-          let copaUser: any = {};
-          try {
-            const copaToken = import.meta.env.VITE_BLUECOPA_API_TOKEN
-              ? atob(import.meta.env.VITE_BLUECOPA_API_TOKEN)
-              : "{}";
-            
-            copaUser = JSON.parse(copaToken);
-          } catch (error) {
-            console.warn("Failed to parse VITE_BLUECOPA_API_TOKEN:", error);
-          }
-
-          copaSetConfig({
-            apiBaseUrl: import.meta.env.VITE_BLUECOPA_API_URL || "https://develop.bluecopa.com/api/v1",
-            workspaceId: import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || "",
-            accessToken: copaUser?.accessToken || "",
-          });
-        }, []);
-
-        return (
-          <QueryClientProvider client={queryClient}>
-            {children}
-            <ReactQueryDevtools initialIsOpen={false} />
-          </QueryClientProvider>
-        );
-      }
-      ```
-
-      **Required Environment Variables:**
-
-      | Variable | Description | Example |
-      |----------|-------------|---------|
-      | `VITE_BLUECOPA_API_URL` | Base URL for Bluecopa API | `https://develop.bluecopa.com` |
-      | `VITE_BLUECOPA_WORKSPACE_ID` | Your workspace identifier | `my-workspace-123` |
-      | `VITE_BLUECOPA_API_TOKEN` | Base64-encoded JSON string containing `accessToken` | `eyJhY2Nlc3NUb2tlbiI6IjEyMzQ1In0=` |
-
-      **Example `.env` file:**
-      ```
-      VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
-      VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
-      VITE_BLUECOPA_API_TOKEN=base64-encoded-json-here
-      ```
-
-      Then wrap your application with this provider:
-
-      ```tsx
-      import QueryProvider from './providers/query-provider';
-
-      function App() {
-        return (
-          <QueryProvider>
-            <YourApp />
-          </QueryProvider>
-        );
-      }
-      ```
-
-      This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
-
-      ### Hook Examples
-
-      #### `useUser` - Fetch authenticated user
-
-      ```tsx
-      import { useUser } from '@bluecopa/react';
-
-      function UserProfile() {
-        const { data, isLoading, error } = useUser({
-          staleTime: 5 * 60 * 1000, // 5 minutes
-          retry: 2
-        });
-        
-        if (isLoading) return <div>Loading...</div>;
-        if (error) return <div>Error: {error.message}</div>;
-        
-        return <div>Welcome, {data?.name}!</div>;
-      }
-      ```
-
-      #### `useDataset` - Fetch dataset with query controls
-
-      ```tsx
-      import { useDataset } from '@bluecopa/react';
-
-      function DatasetViewer({ datasetId }) {
-        const { data, isLoading } = useDataset(datasetId, {
-          limit: 500,
-          staleTime: 10 * 60 * 1000 // 10 minutes
-        });
-        
-        if (isLoading) return <div>Loading dataset...</div>;
-        return <div>{data?.name} ({data?.records?.length} records)</div>;
-      }
-      ```
-
-      ## API Documentation
-
-      ### `useUser(options?)`
-
-      Fetches authenticated user details with query controls.
-
-      **Parameters:**  
-      - `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
-
-      **Returns:**  
-      - `data`: User object or `undefined`
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
-
-      ### `useDataset(datasetId, options?)`
 
-      Fetches dataset data by ID with configurable parameters.
+# @bluecopa/react [![npm version](https://img.shields.io/npm/v/@bluecopa/react)](https://www.npmjs.com/package/@bluecopa/react) [![License](https://img.shields.io/npm/l/@bluecopa/react)](https://github.com/bluecopa/blui/blob/main/packages/react/LICENSE)
+
+## A Comprehensive React Query Integration for Bluecopa
+
+A React library providing opinionated custom hooks for TanStack React Query integration with Bluecopa core API. This package enables efficient data fetching, caching, and synchronization with the Bluecopa platform while maintaining type safety and developer experience.
+
+## Table of Contents
+
+- [AI Agent Guide for BlueCopa React shadcn/ui Template](#ai-agent-guide-for-bluecopa-react-shadcnui-template)
+  - [🏗️ Project Architecture Overview](#️-project-architecture-overview)
+    - [Core Stack](#core-stack)
+    - [Key Directories](#key-directories)
+  - [🎨 Component Patterns](#-component-patterns)
+    - [shadcn/ui Components](#shadcnui-components)
+    - [Custom Components](#custom-components)
+    - [Example Component Structure](#example-component-structure)
+  - [🔧 Development Patterns](#-development-patterns)
+    - [State Management](#state-management)
+    - [Data Fetching](#data-fetching)
+- [@bluecopa/react  ](#bluecopareact--)
+  - [A Comprehensive React Query Integration for Bluecopa](#a-comprehensive-react-query-integration-for-bluecopa)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Installation](#installation)
+    - [Peer Dependencies](#peer-dependencies)
+  - [Usage](#usage)
+    - [Query Provider Setup](#query-provider-setup)
+    - [Boilerplate Integration](#boilerplate-integration)
+    - [Hook Examples](#hook-examples)
+      - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
+      - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
+  - [API Documentation](#api-documentation)
+    - [`useUser(options?)`](#useuseroptions)
+    - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
+    - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
+    - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
+    - [`useInputTable(inputTableId, options?)`](#useinputtableinputtableid-options)
+    - [`useGetFileUrlByFileId(fileId, options?)`](#usegetfileurlbyfileidfileid-options)
+    - [`useGetPublishedWorkbookById(workbookId, options?)`](#usegetpublishedworkbookbyidworkbookid-options)
+    - [`useGetTableById(tableId, options?)`](#usegettablebyidtableid-options)
+    - [`useGetWorkbooksByType(workbookType, options?)`](#usegetworkbooksbytypeworkbooktype-options)
+    - [`useGetWorkflowInstanceStatusById(instanceId, options?)`](#usegetworkflowinstancestatusbyidinstanceid-options)
+    - [`useGetWorksheets(options?)`](#usegetworksheetsoptions)
+    - [`useGetWorksheetsByType(worksheetType, options?)`](#usegetworksheetsbytypeworksheettype-options)
+    - [`useRunDefinition(definitionId, options?)`](#userundefinitiondefinitionid-options)
+    - [`useRunPublishedDefinition(publishedDefinitionId, options?)`](#userunpublisheddefinitionpublisheddefinitionid-options)
+    - [`useRunSampleDefinition(sampleDefinitionId, options?)`](#userunsampledefinitionsampledefinitionid-options)
+    - [`useTriggerHttpWorkflow(workflowId, payload, options?)`](#usetriggerhttpworkflowworkflowid-payload-options)
+    - [`useTriggerWorkflow(workflowId, options?)`](#usetriggerworkflowworkflowid-options)
+    - [`useWorkbook(workbookId, options?)`](#useworkbookworkbookid-options)
+    - [`useWorkflow(workflowId, options?)`](#useworkflowworkflowid-options)
+    - [`useWorksheet(worksheetId, options?)`](#useworksheetworksheetid-options)
+  - [Configuration](#configuration)
+    - [Default Query Configuration](#default-query-configuration)
+    - [Customizable Parameters](#customizable-parameters)
+  - [Advanced Usage](#advanced-usage)
+    - [Error Handling](#error-handling)
+    - [Manual Refetching](#manual-refetching)
+  - [Re-exports](#re-exports)
+    - [Styling Guidelines](#styling-guidelines)
+  - [📊 Data Visualization](#-data-visualization)
+    - [Charts (Recharts)](#charts-recharts)
+    - [Tables (TanStack Table)](#tables-tanstack-table)
+  - [🎯 Common Tasks \& Solutions](#-common-tasks--solutions)
+    - [Adding New Pages](#adding-new-pages)
+    - [Adding New Components](#adding-new-components)
+    - [Working with Forms](#working-with-forms)
+    - [API Integration](#api-integration)
+  - [🚀 Performance Optimization](#-performance-optimization)
+    - [Code Splitting](#code-splitting)
+    - [Bundle Optimization](#bundle-optimization)
+    - [Runtime Performance](#runtime-performance)
+  - [🧪 Testing Strategies](#-testing-strategies)
+    - [Component Testing](#component-testing)
+    - [Integration Testing](#integration-testing)
+  - [🔒 Security Considerations](#-security-considerations)
+    - [Data Handling](#data-handling)
+  - [📱 Responsive Design](#-responsive-design)
+    - [Breakpoints](#breakpoints)
+    - [Layout Patterns](#layout-patterns)
+  - [🌙 Dark Mode Implementation](#-dark-mode-implementation)
+    - [Theme System](#theme-system)
+    - [Component Theming](#component-theming)
+  - [🐛 Debugging Tips](#-debugging-tips)
+    - [Common Issues](#common-issues)
+    - [Development Tools](#development-tools)
+  - [📚 Useful Resources](#-useful-resources)
+    - [Documentation](#documentation)
+    - [BlueCopa Specific](#bluecopa-specific)
+  - [🎯 Best Practices Summary](#-best-practices-summary)
+  - [🔄 Common Workflows](#-common-workflows)
+    - [Adding a New Feature](#adding-a-new-feature)
+    - [Debugging Issues](#debugging-issues)
+
+## Features
+
+- ✅ First-class TypeScript support with strict type definitions
+- 🔁 Seamless integration with TanStack React Query (v5+)
+- 🛡 Comprehensive error handling patterns
+- ⚙ Optimized default query configuration
+- 📦 Re-exports of core TanStack React Query utilities
+- 📊 Sample data preview capabilities
+- 🧩 Customizable query parameters (limit, caching, retries)
+
+## Installation
+
+```bash
+npm install @bluecopa/react
+# or with pnpm
+pnpm add @bluecopa/react
+```
 
-      **Parameters:**  
-      - `datasetId`: ID of the dataset to fetch
-      - `options` (optional): Query options with:
-        - `limit`: Maximum records to fetch
-        - `staleTime`: Duration (ms) before data is considered stale
+### Peer Dependencies
 
-      **Returns:**  
-      - `data`: Dataset object containing name and records
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+This package requires the following in your application:
 
-      ### `useDatasetSample(datasetId, options?)`
+```bash
+npm install react@^18.0.0 react-dom@^18.0.0
+```
 
-      Fetches a representative sample of dataset data.
+## Usage
 
-      **Parameters:**  
-      - `datasetId`: ID of the dataset
-      - `options` (optional): Query options with `enabled` flag
+### Query Provider Setup
 
-      **Returns:**  
-      - `data`: Object containing sample data
-      - `isLoading`: Boolean indicating loading state
-      - `refetch`: Function to manually trigger refetch
+Wrap your application with the React Query provider:
 
-      ### `useMetric(metricId, options?)`
+```tsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 60 * 1000, // 1 minute
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourApp />
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
 
-      Fetches metric data by ID.
+### Boilerplate Integration
 
-      **Parameters:**  
-      - `metricId`: ID of the metric
-      - `options` (optional): Query options
+For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
 
-      **Returns:**  
-      - `data`: Metric object with name and value
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+```tsx
+// src/providers/query-provider.tsx
+import { ReactQueryDevtools, reactQuery, copaSetConfig } from "@bluecopa/react";
+import { useEffect, useState } from "react";
+
+const { QueryClient, QueryClientProvider } = reactQuery;
+
+export default function QueryProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // 1 minute
+        refetchOnWindowFocus: false,
+      },
+    },
+  }));
+
+  useEffect(() => {
+    let copaUser: any = {};
+    try {
+      const copaToken = import.meta.env.VITE_BLUECOPA_API_TOKEN
+        ? atob(import.meta.env.VITE_BLUECOPA_API_TOKEN)
+        : "{}";
+      
+      copaUser = JSON.parse(copaToken);
+    } catch (error) {
+      console.warn("Failed to parse VITE_BLUECOPA_API_TOKEN:", error);
+    }
+
+    copaSetConfig({
+      apiBaseUrl: import.meta.env.VITE_BLUECOPA_API_URL || "https://develop.bluecopa.com/api/v1",
+      workspaceId: import.meta.env.VITE_BLUECOPA_WORKSPACE_ID || "",
+      accessToken: copaUser?.accessToken || "",
+    });
+  }, []);
 
-      ### `useInputTable(inputTableId, options?)`
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+      <ReactQueryDevtools initialIsOpen={false} />
+    </QueryClientProvider>
+  );
+}
+```
 
-      Fetches input table data with limit parameters.
+**Required Environment Variables:**
 
-      **Parameters:**  
-      - `inputTableId`: ID of the input table
-      - `options` (optional): Query options with `limitParams`:
-        - `limit`: Maximum rows to fetch
-        - `limitFrom`: Direction to apply limit from ('top' or 'bottom')
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VITE_BLUECOPA_API_URL` | Base URL for Bluecopa API | `https://develop.bluecopa.com` |
+| `VITE_BLUECOPA_WORKSPACE_ID` | Your workspace identifier | `my-workspace-123` |
+| `VITE_BLUECOPA_API_TOKEN` | Base64-encoded JSON string containing `accessToken` | `eyJhY2Nlc3NUb2tlbiI6IjEyMzQ1In0=` |
 
-      **Returns:**  
-      - `data`: Input table object with rows
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+**Example `.env` file:**
+```
+VITE_BLUECOPA_API_URL=https://develop.bluecopa.com
+VITE_BLUECOPA_WORKSPACE_ID=your-workspace-id
+VITE_BLUECOPA_API_TOKEN=base64-encoded-json-here
+```
 
-      ### `useGetFileUrlByFileId(fileId, options?)`
+Then wrap your application with this provider:
 
-      Fetches the URL for a file by its ID.
+```tsx
+import QueryProvider from './providers/query-provider';
 
-      **Parameters:**
-      - `fileId`: ID of the file to fetch URL for
-      - `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
+function App() {
+  return (
+    <QueryProvider>
+      <YourApp />
+    </QueryProvider>
+  );
+}
+```
 
-      **Returns:**
-      - `data`: Object containing file URL
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
 
-      ### `useGetPublishedWorkbookById(workbookId, options?)`
+### Hook Examples
 
-      Fetches published workbook details by ID.
+#### `useUser` - Fetch authenticated user
 
-      **Parameters:**
-      - `workbookId`: ID of the published workbook
-      - `options` (optional): Query options
+```tsx
+import { useUser } from '@bluecopa/react';
+
+function UserProfile() {
+  const { data, isLoading, error } = useUser({
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    retry: 2
+  });
+  
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return <div>Welcome, {data?.name}!</div>;
+}
+```
 
-      **Returns:**
-      - `data`: Published workbook object
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+#### `useDataset` - Fetch dataset with query controls
 
-      ### `useGetTableById(tableId, options?)`
+```tsx
+import { useDataset } from '@bluecopa/react';
+
+function DatasetViewer({ datasetId }) {
+  const { data, isLoading } = useDataset(datasetId, {
+    limit: 500,
+    staleTime: 10 * 60 * 1000 // 10 minutes
+  });
+  
+  if (isLoading) return <div>Loading dataset...</div>;
+  return <div>{data?.name} ({data?.records?.length} records)</div>;
+}
+```
 
-      Fetches table metadata by ID.
+## API Documentation
 
-      **Parameters:**
-      - `tableId`: ID of the table
-      - `options` (optional): Query options
+### `useUser(options?)`
 
-      **Returns:**
-      - `data`: Table metadata object
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches authenticated user details with query controls.
 
-      ### `useGetWorkbooksByType(workbookType, options?)`
+**Parameters:**  
+- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
 
-      Fetches workbooks filtered by type.
+**Returns:**  
+- `data`: User object or `undefined`
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `workbookType`: Type of workbooks to fetch
-      - `options` (optional): Query options
+### `useDataset(datasetId, options?)`
 
-      **Returns:**
-      - `data`: Array of workbook objects
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches dataset data by ID with configurable parameters.
 
-      ### `useGetWorkflowInstanceStatusById(instanceId, options?)`
+**Parameters:**  
+- `datasetId`: ID of the dataset to fetch
+- `options` (optional): Query options with:
+  - `limit`: Maximum records to fetch
+  - `staleTime`: Duration (ms) before data is considered stale
 
-      Fetches workflow instance status by ID.
+**Returns:**  
+- `data`: Dataset object containing name and records
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `instanceId`: ID of the workflow instance
-      - `options` (optional): Query options
+### `useDatasetSample(datasetId, options?)`
 
-      **Returns:**
-      - `data`: Workflow status object
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches a representative sample of dataset data.
 
-      ### `useGetWorksheets(options?)`
+**Parameters:**  
+- `datasetId`: ID of the dataset
+- `options` (optional): Query options with `enabled` flag
 
-      Fetches all available worksheets.
+**Returns:**  
+- `data`: Object containing sample data
+- `isLoading`: Boolean indicating loading state
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `options` (optional): Query options
+### `useMetric(metricId, options?)`
 
-      **Returns:**
-      - `data`: Array of worksheet objects
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches metric data by ID.
 
-      ### `useGetWorksheetsByType(worksheetType, options?)`
+**Parameters:**  
+- `metricId`: ID of the metric
+- `options` (optional): Query options
 
-      Fetches worksheets filtered by type.
+**Returns:**  
+- `data`: Metric object with name and value
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `worksheetType`: Type of worksheets to fetch
-      - `options` (optional): Query options
+### `useInputTable(inputTableId, options?)`
 
-      **Returns:**
-      - `data`: Array of worksheet objects
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches input table data with limit parameters.
 
-      ### `useRunDefinition(definitionId, options?)`
+**Parameters:**  
+- `inputTableId`: ID of the input table
+- `options` (optional): Query options with `limitParams`:
+  - `limit`: Maximum rows to fetch
+  - `limitFrom`: Direction to apply limit from ('top' or 'bottom')
 
-      Executes a run definition.
+**Returns:**  
+- `data`: Input table object with rows
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `definitionId`: ID of the run definition
-      - `options` (optional): Query options
+### `useGetFileUrlByFileId(fileId, options?)`
 
-      **Returns:**
-      - `data`: Execution result
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches the URL for a file by its ID.
 
-      ### `useRunPublishedDefinition(publishedDefinitionId, options?)`
+**Parameters:**
+- `fileId`: ID of the file to fetch URL for
+- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
 
-      Executes a published run definition.
+**Returns:**
+- `data`: Object containing file URL
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `publishedDefinitionId`: ID of the published definition
-      - `options` (optional): Query options
+### `useGetPublishedWorkbookById(workbookId, options?)`
 
-      **Returns:**
-      - `data`: Execution result
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches published workbook details by ID.
 
-      ### `useRunSampleDefinition(sampleDefinitionId, options?)`
+**Parameters:**
+- `workbookId`: ID of the published workbook
+- `options` (optional): Query options
 
-      Executes a sample run definition.
+**Returns:**
+- `data`: Published workbook object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `sampleDefinitionId`: ID of the sample definition
-      - `options` (optional): Query options
+### `useGetTableById(tableId, options?)`
 
-      **Returns:**
-      - `data`: Sample execution result
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches table metadata by ID.
 
-      ### `useTriggerHttpWorkflow(workflowId, payload, options?)`
+**Parameters:**
+- `tableId`: ID of the table
+- `options` (optional): Query options
 
-      Triggers an HTTP workflow execution.
+**Returns:**
+- `data`: Table metadata object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `workflowId`: ID of the workflow
-      - `payload`: Request payload
-      - `options` (optional): Query options
+### `useGetWorkbooksByType(workbookType, options?)`
 
-      **Returns:**
-      - `data`: Workflow execution response
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches workbooks filtered by type.
 
-      ### `useTriggerWorkflow(workflowId, options?)`
+**Parameters:**
+- `workbookType`: Type of workbooks to fetch
+- `options` (optional): Query options
 
-      Triggers a workflow execution.
+**Returns:**
+- `data`: Array of workbook objects
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `workflowId`: ID of the workflow
-      - `options` (optional): Query options
+### `useGetWorkflowInstanceStatusById(instanceId, options?)`
 
-      **Returns:**
-      - `data`: Workflow execution response
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches workflow instance status by ID.
 
-      ### `useWorkbook(workbookId, options?)`
+**Parameters:**
+- `instanceId`: ID of the workflow instance
+- `options` (optional): Query options
 
-      Fetches workbook details by ID.
+**Returns:**
+- `data`: Workflow status object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `workbookId`: ID of the workbook
-      - `options` (optional): Query options
+### `useGetWorksheets(options?)`
 
-      **Returns:**
-      - `data`: Workbook object
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches all available worksheets.
 
-      ### `useWorkflow(workflowId, options?)`
+**Parameters:**
+- `options` (optional): Query options
 
-      Fetches workflow configuration by ID.
+**Returns:**
+- `data`: Array of worksheet objects
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `workflowId`: ID of the workflow
-      - `options` (optional): Query options
+### `useGetWorksheetsByType(worksheetType, options?)`
 
-      **Returns:**
-      - `data`: Workflow configuration object
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Fetches worksheets filtered by type.
 
-      ### `useWorksheet(worksheetId, options?)`
+**Parameters:**
+- `worksheetType`: Type of worksheets to fetch
+- `options` (optional): Query options
 
-      Fetches worksheet details by ID.
+**Returns:**
+- `data`: Array of worksheet objects
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
 
-      **Parameters:**
-      - `worksheetId`: ID of the worksheet
-      - `options` (optional): Query options
+### `useRunDefinition(definitionId, options?)`
 
-      **Returns:**
-      - `data`: Worksheet object
-      - `isLoading`: Boolean indicating loading state
-      - `error`: Error object if request failed
-      - `refetch`: Function to manually trigger refetch
+Executes a run definition.
 
-      
-      ## Configuration
-
-      ### Default Query Configuration
-
-      ```tsx
-      const queryClient = new QueryClient({
-        defaultOptions: {
-          queries: {
-            retry: 3,
-            staleTime: 1000 * 60 * 5, // 5 minutes
-            gcTime: 1000 * 60 * 10, // 10 minutes
-          },
-        },
-      });
-      ```
-
-      ### Customizable Parameters
-
-      All hooks accept standard TanStack React Query options:
-
-      ```ts
-      interface QueryOptions {
-        enabled?: boolean;        // Enable/disable query
-        staleTime?: number;      // Duration (ms) before data is stale
-        gcTime?: number;         // Duration (ms) to keep data in cache
-        retry?: number | boolean; // Number of retries or disable retries
-        onSuccess?: (data: any) => void; // Success callback
-        onError?: (error: Error) => void; // Error callback
-      }
-      ```
-
-      ## Advanced Usage
-
-      ### Error Handling
-
-      ```tsx
-      useUser({
-        onError: (error) => {
-          console.error('User fetch failed:', error.message);
-          // Custom error recovery logic
-        }
-      });
-      ```
-
-      ### Manual Refetching
-
-      ```tsx
-      function ManualRefetch() {
-        const { data, refetch } = useUser();
-        
-        return (
-          <div>
-            <button onClick={() => refetch()}>Refresh</button>
-          </div>
-        );
-      }
-      ```
-
-      ## Re-exports
-
-      This package re-exports core TanStack React Query utilities:
-
-      ```ts
-      import { 
-        useQuery,
-        useMutation,
-        QueryClient,
-        QueryClientProvider,
-        ReactQueryDevtools 
-      } from '@bluecopa/react';
-      ```
+**Parameters:**
+- `definitionId`: ID of the run definition
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Execution result
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useRunPublishedDefinition(publishedDefinitionId, options?)`
+
+Executes a published run definition.
+
+**Parameters:**
+- `publishedDefinitionId`: ID of the published definition
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Execution result
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useRunSampleDefinition(sampleDefinitionId, options?)`
+
+Executes a sample run definition.
+
+**Parameters:**
+- `sampleDefinitionId`: ID of the sample definition
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Sample execution result
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useTriggerHttpWorkflow(workflowId, payload, options?)`
+
+Triggers an HTTP workflow execution.
+
+**Parameters:**
+- `workflowId`: ID of the workflow
+- `payload`: Request payload
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workflow execution response
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useTriggerWorkflow(workflowId, options?)`
+
+Triggers a workflow execution.
+
+**Parameters:**
+- `workflowId`: ID of the workflow
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workflow execution response
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useWorkbook(workbookId, options?)`
+
+Fetches workbook details by ID.
+
+**Parameters:**
+- `workbookId`: ID of the workbook
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workbook object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useWorkflow(workflowId, options?)`
+
+Fetches workflow configuration by ID.
+
+**Parameters:**
+- `workflowId`: ID of the workflow
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Workflow configuration object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+### `useWorksheet(worksheetId, options?)`
+
+Fetches worksheet details by ID.
+
+**Parameters:**
+- `worksheetId`: ID of the worksheet
+- `options` (optional): Query options
+
+**Returns:**
+- `data`: Worksheet object
+- `isLoading`: Boolean indicating loading state
+- `error`: Error object if request failed
+- `refetch`: Function to manually trigger refetch
+
+
+## Configuration
+
+### Default Query Configuration
+
+```tsx
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      retry: 3,
+      staleTime: 1000 * 60 * 5, // 5 minutes
+      gcTime: 1000 * 60 * 10, // 10 minutes
+    },
+  },
+});
+```
+
+### Customizable Parameters
+
+All hooks accept standard TanStack React Query options:
+
+```ts
+interface QueryOptions {
+  enabled?: boolean;        // Enable/disable query
+  staleTime?: number;      // Duration (ms) before data is stale
+  gcTime?: number;         // Duration (ms) to keep data in cache
+  retry?: number | boolean; // Number of retries or disable retries
+  onSuccess?: (data: any) => void; // Success callback
+  onError?: (error: Error) => void; // Error callback
+}
+```
+
+## Advanced Usage
+
+### Error Handling
+
+```tsx
+useUser({
+  onError: (error) => {
+    console.error('User fetch failed:', error.message);
+    // Custom error recovery logic
+  }
+});
+```
+
+### Manual Refetching
+
+```tsx
+function ManualRefetch() {
+  const { data, refetch } = useUser();
+  
+  return (
+    <div>
+      <button onClick={() => refetch()}>Refresh</button>
+    </div>
+  );
+}
+```
+
+## Re-exports
+
+This package re-exports core TanStack React Query utilities:
+
+```ts
+import { 
+  useQuery,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+  ReactQueryDevtools 
+} from '@bluecopa/react';
+```
 
 ### Styling Guidelines
 - Use Tailwind CSS classes