create-bluecopa-react-app 1.0.14 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-bluecopa-react-app",
-  "version": "1.0.14",
+  "version": "1.0.17",
   "description": "CLI tool to create bluecopa React applications",
   "type": "module",
   "main": "./bin/create-bluecopa-react-app.js",

package/templates/latest/Agent.md

@@ -1,61 +1,23 @@
-# AI Agent Guide for BlueCopa React shadcn/ui Template
+# AI Agent Guide for BlueCopa React UI Template
 
 This guide helps AI assistants and developers understand the project structure, patterns, and best practices for working with this BlueCopa React application template.
 
----
-
 ## 🏗️ Project Architecture Overview
 
 ### Core Stack
 - **React 18** with TypeScript
 - **React Router v7** with SSR support
 - **shadcn/ui** components built on Radix UI
+- **BlueCopa UI** components from `@bluecopa-ui` registry (built on Radix UI)
 - **Tailwind CSS v4** with CSS variables
 - **Vite 6** for build tooling
 - **TanStack Query** (via @bluecopa/react)
 
----
-
-## 💡 UI Components & @bluecopa-ui Registry
-
-This project uses [shadcn/ui](https://ui.shadcn.com/) to scaffold and manage UI component libraries, configured with an explicit support for the **@bluecopa-ui** component registry.
-
-### About the `@bluecopa-ui` Registry
-
-The registry location is defined in your `components.json` file, mapping the registry name to a hosted registry endpoint:
-
-```json
-{
-  ...
-  "registries": {
-    "@bluecopa-ui": "https://shadcn-ui-henna.vercel.app/r/{name}.json"
-  }
-}
-```
-
-- **@bluecopa-ui** registry extends the standard shadcn/ui workflow and provides a curated set of BlueCopa-centric UI components, patterns, and design tokens.  
-- When running any `npx shadcn@latest` CLI commands and passing `add` or `add registry`, you can use `@bluecopa-ui` as the registry source, e.g.:
-  
-  ```bash
-  npx shadcn@latest add @bluecopa-ui/<component>
-  ```
-- This enables streamlined upgrades, easy addition of company-specific components, and consistency with the BlueCopa Design System.
-
-#### Benefits
-
-- **Consistency:** Centralizes custom BlueCopa UI patterns and updates.
-- **Discoverability:** Quickly add business-specific primitives, layouts, dashboards, and utilities.
-- **Maintenance:** Receive improvements, fixes, and new patterns from BlueCopa UX engineering.
-
-**Tip:** `@bluecopa-ui` can be used alongside the default shadcn registry. Specify which to use with `--registry` CLI flag.
-
----
-
 ### Key Directories
 ```
 app/
 ├── components/          # Reusable UI components
-│   ├── ui/             # shadcn/ui & @bluecopa-ui components
+│   ├── ui/             # BlueCopa UI or shadcn/ui components
 │   ├── app-sidebar.tsx # Main navigation
 │   ├── data-table.tsx  # TanStack Table wrapper
 │   └── chart-*.tsx     # Recharts components
@@ -65,25 +27,68 @@ app/
 └── dashboard/          # Sample data and components
 ```
 
----
-
 ## 🎨 Component Patterns
 
-### shadcn/ui & @bluecopa-ui Components
-- All base UI components reside in `app/components/ui/`
-- Most are built atop [Radix UI](https://www.radix-ui.com/) primitives
-- Styled using Tailwind CSS and support theme variables
-- All component imports use the `@bluecopa-ui` registry if you fetch using `npx shadcn@latest add @bluecopa-ui/tooltip`
-- Use the `cn()` utility for conditional styling
-- Fully support dark mode and global CSS variables for design tokens
+### UI Component Registries
+
+This project supports components from two registries:
+
+1. **BlueCopa UI Registry** (Preferred for BlueCopa-specific components)
+   - Registry URL: https://blui.vercel.app
+   - Registry JSON: https://blui.vercel.app/r/registry.json
+   - Custom BlueCopa components built on Radix UI
+
+2. **shadcn/ui Registry** (Standard components)
+   - Registry URL: https://ui.shadcn.com
+   - Standard shadcn/ui components built on Radix UI
+
+Both registries:
+- Located in `app/components/ui/` after installation
+- Built on Radix UI primitives
+- Styled with Tailwind CSS
+- Use `cn()` utility for class merging
+- Support dark mode via CSS variables
+
+### Adding Components
+
+#### From BlueCopa UI Registry
+
+To add a component from the BlueCopa UI registry (preferred for BlueCopa-specific components):
+
+```bash
+pnpm dlx shadcn@latest add @bluecopa-ui/button
+pnpm dlx shadcn@latest add @bluecopa-ui/card
+pnpm dlx shadcn@latest add @bluecopa-ui/dialog
+```
+
+#### From shadcn/ui Registry
+
+To add a component from the standard shadcn/ui registry:
+
+```bash
+pnpm dlx shadcn@latest add button
+pnpm dlx shadcn@latest add card
+pnpm dlx shadcn@latest add dialog
+```
+
+The registries are configured in `components.json`:
+```json
+{
+  "registries": {
+    "@bluecopa-ui": "https://blui.vercel.app/r/{name}.json"
+  }
+}
+```
+
+**Note**: When no registry prefix is specified, components are added from the default shadcn/ui registry. Use `@bluecopa-ui/` prefix for BlueCopa-specific components.
 
 ### Custom Components
 - Use TypeScript interfaces for props
-- Follow React best practices: hooks, `React.memo` as appropriate
-- Implement full accessibility (aria attributes, keyboard nav)
-- Use semantic HTML
+- Follow React best practices (hooks, memo, etc.)
+- Implement proper accessibility
+- Use semantic HTML elements
 
-#### Example Component Structure
+### Example Component Structure
 ```tsx
 import { cn } from "~/lib/utils"
 
@@ -101,49 +106,44 @@ export function Component({ className, children }: ComponentProps) {
 }
 ```
 
----
-
 ## 🔧 Development Patterns
 
 ### State Management
-- Prefer React hooks (`useState`, `useReducer`, `useContext`)
-- Use TanStack Query for server state
-- Avoid prop drilling by using React Context
+- Use React hooks (useState, useReducer, useContext)
+- TanStack Query for server state
+- Local state for UI interactions
+- Avoid prop drilling with context
 
 ### Data Fetching
-- Use `@bluecopa/react` hooks for all API access
-- Implement loading and error states at the component level
-- Leverage TanStack Query caching and invalidation
-- Support optimistic UI for updating server state where possible
-
----
+- Use `@bluecopa/react` hooks for API calls
+- 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.
+## 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)
+- [AI Agent Guide for BlueCopa React UI Template](#ai-agent-guide-for-bluecopa-react-ui-template)
   - [🏗️ Project Architecture Overview](#️-project-architecture-overview)
     - [Core Stack](#core-stack)
-  - [💡 UI Components \& @bluecopa-ui Registry](#-ui-components--bluecopa-ui-registry)
-    - [About the `@bluecopa-ui` Registry](#about-the-bluecopa-ui-registry)
-      - [Benefits](#benefits)
     - [Key Directories](#key-directories)
   - [🎨 Component Patterns](#-component-patterns)
-    - [shadcn/ui \& @bluecopa-ui Components](#shadcnui--bluecopa-ui-components)
+    - [UI Component Registries](#ui-component-registries)
+    - [Adding Components](#adding-components)
+      - [From BlueCopa UI Registry](#from-bluecopa-ui-registry)
+      - [From shadcn/ui Registry](#from-shadcnui-registry)
     - [Custom Components](#custom-components)
-      - [Example Component Structure](#example-component-structure)
+    - [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)
+  - [A Comprehensive React Query Integration for Bluecopa](#a-comprehensive-react-query-integration-for-bluecopa)
   - [Table of Contents](#table-of-contents)
   - [Features](#features)
   - [Installation](#installation)
@@ -151,11 +151,11 @@ A React library providing opinionated custom hooks for TanStack React Query inte
   - [Usage](#usage)
     - [Query Provider Setup](#query-provider-setup)
     - [Boilerplate Integration](#boilerplate-integration)
-    - [Adding a BlueCopa UI Component](#adding-a-bluecopa-ui-component)
     - [Hook Examples](#hook-examples)
       - [`useUser` - Fetch authenticated user](#useuser---fetch-authenticated-user)
       - [`useDataset` - Fetch dataset with query controls](#usedataset---fetch-dataset-with-query-controls)
-  - [... *(rest of guide unchanged)*](#-rest-of-guide-unchanged)
+  - [API Documentation](#api-documentation)
+    - [`useUser(options?)`](#useuseroptions)
     - [`useDataset(datasetId, options?)`](#usedatasetdatasetid-options)
     - [`useDatasetSample(datasetId, options?)`](#usedatasetsampledatasetid-options)
     - [`useMetric(metricId, options?)`](#usemetricmetricid-options)
@@ -226,9 +226,6 @@ A React library providing opinionated custom hooks for TanStack React Query inte
 - 📦 Re-exports of core TanStack React Query utilities
 - 📊 Sample data preview capabilities
 - 🧩 Customizable query parameters (limit, caching, retries)
-- 🪄 Quickly use shadcn/ui and BlueCopa-specific components via `@bluecopa-ui` registry
-
----
 
 ## Installation
 
@@ -238,24 +235,14 @@ npm install @bluecopa/react
 pnpm add @bluecopa/react
 ```
 
-**To enable shadcn/ui with BlueCopa custom components (from @bluecopa-ui registry):**
-
-```bash
-npx shadcn@latest add @bluecopa-ui/<component>
-```
-
-This will fetch the component from the "@bluecopa-ui" registry endpoint declared in your `components.json`. This means you automatically get the most up-to-date BlueCopa patterns and design system building blocks.
-
 ### Peer Dependencies
 
-Install required 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
@@ -286,7 +273,7 @@ function App() {
 
 ### Boilerplate Integration
 
-For projects using the BlueCopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically and integrates all BlueCopa registry UI imports:
+For projects using the Bluecopa React boilerplate, use the pre-configured `QueryProvider` component that handles API configuration automatically:
 
 ```tsx
 // src/providers/query-provider.tsx
@@ -337,7 +324,7 @@ export default function QueryProvider({ children }: { children: React.ReactNode
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `VITE_BLUECOPA_API_URL` | Base URL for BlueCopa API | `https://develop.bluecopa.com` |
+| `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=` |
 
@@ -362,21 +349,7 @@ function App() {
 }
 ```
 
-This setup automatically configures both the BlueCopa API client and enables seamless usage of BlueCopa UI primitives pulled from the custom registry.
-
----
-
-### Adding a BlueCopa UI Component
-
-To add a BlueCopa custom UI primitive (e.g., "copa-card") to your project, use:
-
-```bash
-npx shadcn@latest add @bluecopa-ui/pagination-block
-```
-
-The CLI pulls the latest [copa-card](https://shadcn-ui-henna.vercel.app/r/copa-card.json) definition from the registry as specified in `components.json`, and installs it to `app/components/ui/`.
-
----
+This setup automatically configures the API client with your environment-specific settings and applies optimal caching defaults.
 
 ### Hook Examples
 
@@ -414,12 +387,14 @@ function DatasetViewer({ datasetId }) {
 }
 ```
 
----
+## API Documentation
 
-## ... *(rest of guide unchanged)*
+### `useUser(options?)`
 
-The rest of this guide covers all @bluecopa/react data hooks, configuration, testing, and best practices as before. For adding or updating UI primitives, always prefer `@bluecopa-ui` registry where available to match BlueCopa's latest design system and component standards.
+Fetches authenticated user details with query controls.
 
+**Parameters:**  
+- `options` (optional): Query options extending TanStack React Query's `UseQueryOptions`
 
 **Returns:**  
 - `data`: User object or `undefined`
@@ -799,18 +774,25 @@ import {
 4. Implement proper TypeScript types
 
 ### Adding New Components
-1. Create component file in appropriate directory
-2. Define TypeScript interface for props
-3. Use shadcn/ui components as base
-4. Implement responsive design
-5. Add proper accessibility attributes
+1. Add components from either registry:
+   - BlueCopa UI: `pnpm dlx shadcn@latest add @bluecopa-ui/component-name`
+   - shadcn/ui: `pnpm dlx shadcn@latest add component-name`
+2. Components are installed in `app/components/ui/`
+3. Prefer BlueCopa UI registry for BlueCopa-specific components
+4. Use shadcn/ui registry for standard components not available in BlueCopa UI
+5. Define TypeScript interface for props if extending components
+6. Implement responsive design
+7. Add proper accessibility attributes
 
 ### Working with Forms
-1. Use shadcn/ui form components
-2. Implement validation with Zod
-3. Handle form state with React hooks
-4. Show loading and error states
-5. Use proper form semantics
+1. Use form components from either registry:
+   - BlueCopa UI: `pnpm dlx shadcn@latest add @bluecopa-ui/form`
+   - shadcn/ui: `pnpm dlx shadcn@latest add form`
+2. Prefer BlueCopa UI form components when available
+3. Implement validation with Zod
+4. Handle form state with React hooks
+5. Show loading and error states
+6. Use proper form semantics
 
 ### API Integration
 1. Use `@bluecopa/react` hooks
@@ -904,6 +886,7 @@ import {
 
 ### Documentation
 - [React Router v7 Docs](https://reactrouter.com/)
+- [BlueCopa UI Registry](https://blui.vercel.app)
 - [shadcn/ui Components](https://ui.shadcn.com/)
 - [Tailwind CSS v4](https://tailwindcss.com/)
 - [TanStack Table](https://tanstack.com/table)
@@ -917,26 +900,30 @@ import {
 ## 🎯 Best Practices Summary
 
 1. **Always use TypeScript** - Define proper interfaces and types
-2. **Follow shadcn/ui patterns** - Use established component structure
-3. **Implement accessibility** - Use semantic HTML and ARIA attributes
-4. **Optimize for performance** - Use proper React patterns and code splitting
-5. **Test thoroughly** - Write tests for components and user workflows
-6. **Handle errors gracefully** - Implement proper error boundaries and fallbacks
-7. **Follow responsive design** - Mobile-first approach with proper breakpoints
-8. **Use proper state management** - Choose appropriate patterns for different data types
-9. **Implement proper loading states** - Show feedback during async operations
-10. **Follow security best practices** - Validate inputs and secure API calls
+2. **Use appropriate registry** - Prefer BlueCopa UI (`@bluecopa-ui/component-name`) for BlueCopa-specific components, use shadcn/ui (`component-name`) for standard components
+3. **Follow component patterns** - Use established component structure from both registries
+4. **Implement accessibility** - Use semantic HTML and ARIA attributes
+5. **Optimize for performance** - Use proper React patterns and code splitting
+6. **Test thoroughly** - Write tests for components and user workflows
+7. **Handle errors gracefully** - Implement proper error boundaries and fallbacks
+8. **Follow responsive design** - Mobile-first approach with proper breakpoints
+9. **Use proper state management** - Choose appropriate patterns for different data types
+10. **Implement proper loading states** - Show feedback during async operations
+11. **Follow security best practices** - Validate inputs and secure API calls
 
 ## 🔄 Common Workflows
 
 ### Adding a New Feature
 1. Create feature branch
-2. Implement components with TypeScript
-3. Add proper styling with Tailwind
-4. Implement responsive design
-5. Add tests
-6. Update documentation
-7. Test in both light and dark modes
+2. Add required UI components from appropriate registry:
+   - BlueCopa UI: `pnpm dlx shadcn@latest add @bluecopa-ui/component-name`
+   - shadcn/ui: `pnpm dlx shadcn@latest add component-name`
+3. Implement components with TypeScript
+4. Add proper styling with Tailwind
+5. Implement responsive design
+6. Add tests
+7. Update documentation
+8. Test in both light and dark modes
 
 ### Debugging Issues
 1. Check browser console for errors

package/templates/latest/README.md

@@ -112,6 +112,23 @@ encoded as base64.
 
 If the API errors out or is not configured, the application will show "Set Environment" as the user name with email "setenv@email.com" as a fallback.
 
+### Statement Hooks Example
+
+This template includes a comprehensive example of using BlueCopa statement hooks at `/statements`. The example demonstrates:
+
+- **useGetStatementData** - Fetching statement data by statement ID (with optional viewId and runId)
+- **useGetViewsBySheetId** - Fetching all views for a statement sheet
+- **useGetRunsByViewId** - Fetching all runs for a statement view
+- **useGetViewById** - Fetching specific view details
+- **useGetRunResultById** - Fetching specific run results
+- **useCreateStatementRun** - Creating new statement runs with mutations
+
+The example includes two pre-configured statement IDs:
+- Example 1: `MDYK9CU8NR1S41AFAOEX` (uses default view)
+- Example 2: `MGIZ7GD08NQJ71SK8RA7` with View ID `MGJ1ZF0JN53B0V0YH10Z`
+
+**Note:** The statement hooks require `@bluecopa/react` version 0.1.16 or higher. Update your `package.json` to use the latest version that includes these hooks.
+
 ## Building for Production
 
 Create a production build:

package/templates/latest/app/app.css

@@ -4,8 +4,7 @@
 @custom-variant dark (&:is(.dark *));
 
 @theme {
-  --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif,
-    "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+  --font-sans: "Satoshi", ui-sans-serif, system-ui, sans-serif;
 }
 
 html,

package/templates/latest/app/components/app-sidebar.tsx

@@ -55,6 +55,11 @@ const data = {
       title: "Payments",
       url: "/payments",
       icon: IconCreditCard,
+    },
+    {
+      title: "Statements",
+      url: "/statements",
+      icon: IconFileDescription,
     } 
   ],
   navClouds: [

package/templates/latest/app/components/nav-user.tsx

@@ -31,7 +31,6 @@ import { useBluecopaUser } from "~/hooks/use-bluecopa-user"
 export function NavUser() {
   const { isMobile } = useSidebar()
   const { user, isLoading } = useBluecopaUser()
-  const { firstName, email } = user?.user || {}
   // Show loading state while fetching user data
   if (isLoading) {
     return (
@@ -59,9 +58,9 @@ export function NavUser() {
               className="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
             >
               <div className="grid flex-1 text-left text-sm leading-tight">
-                <span className="truncate font-medium">{firstName}</span>
+                <span className="truncate font-medium">User ({user?.userId})</span>
                 <span className="text-muted-foreground truncate text-xs">
-                  {email}
+                  {user?.email}
                 </span>
               </div>
               <IconDotsVertical className="ml-auto size-4" />
@@ -77,9 +76,9 @@ export function NavUser() {
               <div className="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
                 
                 <div className="grid flex-1 text-left text-sm leading-tight">
-                  <span className="truncate font-medium">{firstName}</span>
+                  <span className="truncate font-medium">User ({user?.userId})</span>
                   <span className="text-muted-foreground truncate text-xs">
-                    {email}
+                    {user?.email}
                   </span>
                 </div>
               </div>