@corva/create-app 0.114.0 → 0.116.0

package/templates/ui/typescript/AGENTS.md

@@ -0,0 +1,339 @@
+# AGENTS.md
+
+Corva.AI platform UI app — a React dashboard widget scaffolded by `create-corva-app`.
+Deployed to the Corva platform via `yarn release`.
+
+## Critical Rules
+
+These constraints are enforced by the platform. Violating them breaks the build or runtime.
+
+1. **Root export** — `src/index.js` MUST default-export `{ component: App, settings: AppSettings }`. The component may also be a `ParentApp` wrapper (e.g., `{ component: ParentApp, settings: AppSettings }`) that wraps `App` with Context.Providers and prop initialization. This is the platform loader contract.
+2. **UI components** — Use only `@corva/ui` components. Import from `@corva/ui/componentsV2`; fall back to `@corva/ui/components` only when a V2 version doesn't exist yet. `@material-ui/core` v4 is available as the underlying library.
+3. **HTTP clients** — Use `corvaDataAPI` / `corvaAPI` from `@corva/ui/clients` for all network requests.
+4. **Do not rename or delete** `App.tsx`, `AppSettings.tsx`, or `index.js` — they are platform entry points.
+
+## Project Structure
+
+```
+src/
+  App.tsx              — Main app component (default export required)
+  AppSettings.tsx      — Settings panel component (default export required)
+  index.js             — Root export: { component, settings }
+  constants.ts         — Default settings values
+  types.ts             — Custom app settings interface
+  custom.d.ts          — Module declarations for CSS/SVG imports
+  App.css              — Component styles (CSS modules)
+  __tests__/           — Jest test files
+  __mocks__/mockData.ts — Mock data for tests
+  assets/              — Static assets (SVGs, images)
+config/jest/           — Jest setup (setupTests, transforms)
+config-overrides.js    — Webpack 5 customization
+tsconfig.json          — TypeScript configuration
+manifest.json          — Corva platform app metadata (generated at scaffold time)
+```
+
+## Key Patterns
+
+### Component Structure
+
+- Use `useAppCommons()` from `@corva/ui/effects` to access platform data: `appKey`, `appSettings`, `well`, `rig`, `fracFleet`, `wells`, `currentUser`, `onSettingChange`, `onSettingsChange`, etc.
+- Define custom app settings shape in `src/types.ts` (`CustomAppSettings`).
+- Platform types (Well, Rig, FracFleet, User, etc.) are typed in `@corva/ui` — do NOT duplicate them.
+
+```typescript
+// App component pattern — use useAppCommons() instead of props
+const App = () => {
+  const { appKey, well, rig, appSettings } = useAppCommons();
+  const { isExampleCheckboxChecked } = appSettings || {};
+  // ...
+};
+
+// AppSettings component pattern — same hook
+const AppSettings = () => {
+  const { appSettings, onSettingChange } = useAppCommons();
+  // ...
+};
+```
+
+### Styling
+
+CSS modules for component styles:
+
+```typescript
+import styles from './App.css';
+// Use: <div className={styles.container}>
+```
+
+For custom component styles, use `makeStyles` from MUI v4:
+
+```typescript
+import { makeStyles } from '@material-ui/core/styles';
+
+const useStyles = makeStyles(theme => ({
+  root: { display: 'flex', gap: theme.spacing(1) },
+}));
+
+// Inside component:
+const styles = useStyles();
+return <div className={styles.root}>...</div>;
+```
+
+**`theme.spacing(n)`** — 8px base unit for layout dimensions:
+
+```typescript
+padding: theme.spacing(2)        // 16px
+margin: theme.spacing(1, 0)      // 8px 0
+borderRadius: theme.spacing(0.5) // 4px
+```
+
+**Color manipulation** — `fade`, `darken`, `lighten` from `@material-ui/core/styles`:
+
+```typescript
+import { fade, darken, lighten } from '@material-ui/core/styles';
+
+background: fade(theme.palette.common.white, 0.08)  // white at 8% opacity
+color: darken(theme.palette.primary.main, 0.2)       // darken by 20%
+```
+
+**Transitions:**
+
+```typescript
+transition: theme.transitions.create('opacity')
+transition: theme.transitions.create(['opacity', 'background-color'], {
+  duration: theme.transitions.duration.standard, // 300ms
+})
+```
+
+**Breakpoints:**
+
+```typescript
+[theme.breakpoints.down('sm')]: { padding: theme.spacing(1) }  // max-width: 599px
+[theme.breakpoints.up('md')]: { flexDirection: 'row' }         // min-width: 960px
+```
+
+**`theme.zIndex`** — stacking constants: `appBar` (1100), `drawer` (1200), `modal` (1300), `tooltip` (1500).
+
+**CSS variables** — available in `.css` files:
+
+```css
+color: var(--palette-primary-text-1);        /* primary text */
+background: var(--palette-background-b-5);   /* card background */
+border-color: var(--palette-primary-text-9);  /* borders */
+```
+
+**SCSS functions** — available in `.module.scss` files:
+
+```scss
+padding: spacing(2);                // 16px
+color: colorAlpha($color, 0.5);     // rgba transparency
+transition: transition(opacity);    // standard cubic-bezier
+```
+
+**Direct theme import:**
+
+```typescript
+import { lightTheme, darkTheme } from '@corva/ui/config';
+```
+
+### State Management (Zustand)
+
+The Corva platform can render multiple instances of the same app simultaneously. If a Zustand store is created at module level (singleton), all instances share the same state. To avoid this, always create store instances inside a React Context provider.
+
+**Store factory + context** — create a factory function and a context to hold the store instance:
+
+```typescript
+// store/createAppStore.ts
+import { createContext } from 'react';
+import { create } from 'zustand';
+
+import { AppStore } from '~/types';
+
+export const createAppStore = (initProps?: Partial<SavedSettings>) => {
+  return create<AppStore>()((set, get) => ({
+    // Compose sub-stores
+    ...createSettingsStore(initProps?.settings)(set, get),
+    ...createDataStore()(set, get),
+  }));
+};
+
+export const StoreContext = createContext<ReturnType<typeof createAppStore> | null>(null);
+```
+
+**Provider** — create the store once per app mount and pass it via context:
+
+```typescript
+// StoreProvider.tsx
+import { FC, PropsWithChildren, useState } from 'react';
+
+import { StoreContext, createAppStore } from '~/store/createAppStore';
+
+export const StoreProvider: FC<PropsWithChildren<{ savedSettings: SavedSettings }>> = ({
+  children,
+  savedSettings,
+}) => {
+  const [appStore] = useState(() => createAppStore(savedSettings));
+
+  return <StoreContext.Provider value={appStore}>{children}</StoreContext.Provider>;
+};
+```
+
+**Consumer hooks** — read from context, never from a global store:
+
+```typescript
+// hooks/useAppStore.ts
+import { useContext } from 'react';
+import { useStore } from 'zustand';
+import { useStoreWithEqualityFn } from 'zustand/traditional';
+
+import { StoreContext } from '~/store/createAppStore';
+import { AppStore } from '~/types';
+
+/** Read a single top-level key from the store. */
+export const useAppStore = <T extends keyof AppStore>(key: T): AppStore[T] => {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error('useAppStore must be used within StoreProvider');
+  return useStore(store, state => state[key]);
+};
+
+/** Subscribe to a derived value with optional custom equality. */
+export const useAppStoreSelector = <R>(
+  selector: (state: AppStore) => R,
+  equalityFn?: (a: R, b: R) => boolean
+): R => {
+  const store = useContext(StoreContext);
+  if (!store) throw new Error('useAppStoreSelector must be used within StoreProvider');
+  return useStoreWithEqualityFn(store, selector, equalityFn);
+};
+```
+
+**Usage in components:**
+
+```typescript
+const isLegendVisible = useAppStore('isLegendVisible');
+const selectedChannels = useAppStoreSelector(state => state.selectedChannels);
+```
+
+**Wire it up in `ParentApp`** (see full example with `QueryClientProvider` in the Data Fetching section below).
+
+General rules:
+- Name stores `use[Name]Store` (e.g., `useWellDataStore`)
+- Use selectors: `const value = useAppStore('value')`
+- Keep business logic in store actions
+
+### Data Fetching (React Query v4)
+
+Same as Zustand: the platform runs multiple app instances, so each must have its own `QueryClient`. Never create a `QueryClient` at module level — use a hook with `useState` to create it once per mount.
+
+**`useQueryClient` hook** — creates an isolated `QueryClient` per app instance:
+
+```typescript
+// hooks/useQueryClient.ts
+import { useState } from 'react';
+import { QueryCache, QueryClient } from '@tanstack/react-query';
+import { showErrorNotification } from '@corva/ui/utils';
+
+export const useQueryClient = () => {
+  const [queryClient] = useState(
+    new QueryClient({
+      queryCache: new QueryCache({
+        onError: (error: unknown) => {
+          if (typeof error === 'object' && error !== null && 'message' in error) {
+            showErrorNotification(`Something went wrong: ${String(error.message)}`);
+          }
+        },
+      }),
+      defaultOptions: {
+        queries: {
+          refetchOnWindowFocus: false,
+          refetchOnReconnect: false,
+        },
+      },
+    })
+  );
+
+  return queryClient;
+};
+```
+
+**Wire it up in `ParentApp`** — wrap the app tree with `QueryClientProvider`:
+
+```typescript
+import { QueryClientProvider } from '@tanstack/react-query';
+
+const ParentApp = () => {
+  const { appSettings, onSettingsChange } = useAppCommons();
+  const queryClient = useQueryClient();
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <StoreProvider savedSettings={appSettings?.savedSettings}>
+        <App />
+      </StoreProvider>
+    </QueryClientProvider>
+  );
+};
+
+export default { component: ParentApp, settings: AppSettings };
+```
+
+General rules:
+- Encapsulate queries in custom hooks (e.g., `useWellData`)
+- Use typed query keys (array format)
+- Always handle `isLoading` and `isError` states
+
+## Naming Conventions
+
+- Boolean variables: prefix with `is`, `has`, or `should`
+- Non-empty array checks: `!!array.length` (not `array.length > 0`)
+- Zustand stores: `use[StoreName]Store`
+- TypeScript props: use `interface` (not `type`)
+
+## Testing
+
+- **Framework:** Jest + React Testing Library
+- **Wrapper:** Use `AppTestWrapper` from `@corva/ui/testing` to wrap components — it provides `useAppCommons()` context
+- **Pattern:** Pass data via `AppTestWrapper` props, render components with no props
+- **Mocking:** Mock network requests (jest mocks or msw), never call real APIs
+- **Timezone:** UTC is enforced (`process.env.TZ = 'UTC'`)
+- **Mocked globals:** `ResizeObserver`, `MutationObserver` (in `setupTests.js`)
+
+```tsx
+// Test pattern — data flows through AppTestWrapper context
+render(
+  <AppTestWrapper appSettings={{ isExampleCheckboxChecked: true }} well={mockWell}>
+    <App />
+  </AppTestWrapper>
+);
+```
+
+## Commands
+
+```
+yarn start     Dev server at http://app.local.corva.ai:8080/
+yarn build     Production bundle
+yarn test      Run tests
+yarn lint      ESLint check
+yarn zip       Create deployment ZIP
+yarn release   Release to Corva platform
+```
+
+## @corva/ui Documentation
+
+Local documentation for `@corva/ui` is bundled at `node_modules/@corva/ui/docs/`.
+Before implementing any UI component, data fetch, or API call, read the relevant doc file:
+
+- **V2 Components:** `node_modules/@corva/ui/docs/01-components-v2/` — Props, examples, usage
+- **V1 Components:** `node_modules/@corva/ui/docs/02-components-v1/` — Legacy components reference
+- **Hooks:** `node_modules/@corva/ui/docs/03-hooks/` — Parameters, return types, examples
+- **API Clients:** `node_modules/@corva/ui/docs/04-clients/` — corvaAPI, corvaDataAPI endpoints
+- **Theme:** `node_modules/@corva/ui/docs/05-theme/` — Color palette, CSS variables
+- **Utilities:** `node_modules/@corva/ui/docs/06-utilities/` — Helper functions
+- **Constants:** `node_modules/@corva/ui/docs/07-constants/` — Platform constants
+
+Start with `node_modules/@corva/ui/docs/README.md` for the full index.
+Do NOT guess `@corva/ui` APIs — read the local docs first.
+
+## MCP Server (Interactive Fallback)
+
+The `corva-ui` MCP server is pre-configured (`.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`).
+Use it for interactive queries when the local docs are insufficient or you need to search across components.

package/templates/ui/typescript/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/ui/typescript/src/App.completion.tsx

@@ -2,18 +2,14 @@ import { AppContainer, AppHeader } from '@corva/ui/componentsV2';
 import { useAppCommons } from '@corva/ui/effects';
 
 import { DEFAULT_SETTINGS } from './constants';
-import { AppProps, CustomAppSettings } from './types';
 import logo from './assets/logo.svg';
 
 import styles from './App.css';
 
-function App({
-  isExampleCheckboxChecked = DEFAULT_SETTINGS.isExampleCheckboxChecked,
-  fracFleet,
-  well,
-  wells,
-}: AppProps & CustomAppSettings): JSX.Element {
-  const { appKey } = useAppCommons();
+const App = () => {
+  const { appKey, fracFleet, well, wells, appSettings } = useAppCommons();
+  const { isExampleCheckboxChecked = DEFAULT_SETTINGS.isExampleCheckboxChecked } =
+    appSettings || {};
   // NOTE: On general type dashboard app receives wells array
   // on asset type dashboard app receives well object
   const wellsList = wells || [well];
@@ -49,7 +45,7 @@ function App({
       </div>
     </AppContainer>
   );
-}
+};
 
 // Important: Do not change root component default export (App.js). Use it as container
 //  for your App. It's required to make build and zip scripts work as expected;

package/templates/ui/typescript/src/App.drilling.tsx

@@ -2,17 +2,15 @@ import { AppContainer, AppHeader } from '@corva/ui/componentsV2';
 import { useAppCommons } from '@corva/ui/effects';
 
 import { DEFAULT_SETTINGS } from './constants';
-import { AppProps, CustomAppSettings } from './types';
 import logo from './assets/logo.svg';
 
 import styles from './App.css';
 
-function App({
-  isExampleCheckboxChecked = DEFAULT_SETTINGS.isExampleCheckboxChecked,
-  rig,
-  well,
-}: AppProps & CustomAppSettings): JSX.Element {
-  const { appKey } = useAppCommons();
+const App = () => {
+  const { appKey, rig, well, appSettings } = useAppCommons();
+  const { isExampleCheckboxChecked = DEFAULT_SETTINGS.isExampleCheckboxChecked } =
+    appSettings || {};
+
   return (
     <AppContainer header={<AppHeader />} testId={appKey}>
       <div className={styles.container}>
@@ -44,7 +42,7 @@ function App({
       </div>
     </AppContainer>
   );
-}
+};
 
 // Important: Do not change root component default export (App.js). Use it as container
 //  for your App. It's required to make build and zip scripts work as expected;

package/templates/ui/typescript/src/AppSettings.tsx

@@ -1,11 +1,11 @@
 import { Checkbox, FormControlLabel } from '@material-ui/core';
+import { useAppCommons } from '@corva/ui/effects';
 
 import { DEFAULT_SETTINGS } from './constants';
-import { AppSettingsProps, CustomAppSettings } from './types';
 
-const AppSettings = (props: AppSettingsProps & CustomAppSettings): JSX.Element => {
-  const { settings: apiSettings, onSettingChange } = props;
-  const settings = { ...DEFAULT_SETTINGS, ...apiSettings };
+const AppSettings = () => {
+  const { appSettings, onSettingChange } = useAppCommons();
+  const settings = { ...DEFAULT_SETTINGS, ...appSettings };
 
   return (
     <div>

package/templates/ui/typescript/src/__mocks__/mockData.ts

@@ -1,194 +1,22 @@
-import { AppInstance, AppInstanceData, User, AppHeaderData } from '../types';
-
-export const mockApp: AppInstance = {
-  app: { app_key: 'test', platform: 'test' },
-  id: 1,
-  package: {
-    manifest: {
-      format: 1,
-      license: { type: 'test', url: 'test' },
-      developer: { name: 'test', identifier: 'test', authors: [] },
-      application: {
-        type: 'test',
-        key: 'test',
-        visibility: 'test',
-        name: 'test',
-        description: 'test',
-        summary: 'test',
-        category: 'test',
-        website: 'test',
-        segments: ['test'],
-        ui: {
-          initial_size: { w: 100, h: 100 },
-          multi_rig: false,
-          full_screen_report: false,
-          use_app_header_v3: false,
-        },
-      },
-      settings: {
-        entrypoint: { file: 'test', function: 'test' },
-        environment: {},
-        runtime: 'test',
-        app: { log_type: 'test' },
-        enable_isolation: false,
-      },
-      datasets: {},
-    },
-    build: 'test',
-    version: 'test',
-  },
-  segment: ['test'],
-  settings: {},
+export const mockAppSettings = {
+  isExampleCheckboxChecked: true,
 };
 
-export const mockUser: User = {
-  id: 1,
-  company_id: 1,
-  first_name: 'Test',
-  last_name: 'User',
-  email: 'test@test.com',
-  mobile: '1234567890',
-  created_at: '2023-01-01',
-  terms_acceptance_at: '2023-01-01',
-  profile_photo: null,
-  recently_viewed_asset_ids: [],
-  unit_system: null,
-  custom_unit_system: null,
-  role: 'test',
-  title: null,
-  group: null,
-  favorite_asset_id: null,
-  current_segment: 'test',
-  theme: 'test',
-  messaging_id: 'test',
-  restricted_assets: [],
-  restricted_programs: [],
-  settings: {
-    favorites: [],
-    home_page: { selected_assets_tab: 'test' },
-    onboarded: false,
-    beta_2_158: {},
-    uiSettings: {},
-    singleAsset: {
-      padId: 1,
-      rigId: 1,
-      wellId: null,
-      rigAssetId: 1,
-      fracFleetId: 1,
-      wellAssetId: null,
-      drilloutUnitId: 1,
-      completionWellAssetId: 1,
-    },
-    feed_filters: {
-      company_id: null,
-      start_date: '2023-01-01',
-      content_types: [],
-      selected_rigs_ids: [],
-      selected_user_ids: [],
-      users_radio_value: 'test',
-      assets_radio_value: 'test',
-      date_range_radio_value: 'test',
-    },
-    sms_blacklisted: false,
-    favorit_asset_ids: [],
-    restricted_assets: [],
-    alerts_list_filters: {
-      end_date: '2023-01-01',
-      segments: [],
-      alert_name: 'test',
-      start_date: '2023-01-01',
-      validation: 'test',
-      alert_levels: [],
-      subscription: 'test',
-      classification: 'test',
-      assets_radio_value: 'test',
-      date_range_radio_value: 'test',
-    },
-    restricted_programs: [],
-    is_dnd_feature_shown: false,
-    last_new_alerts_check: '2023-01-01',
-    notifications_filters: {
-      end_date: '2023-01-01',
-      start_date: '2023-01-01',
-      content_types: [],
-      date_range_radio_value: 'test',
-    },
-    directional_app_settings: {
-      curve_to_lat_threshold: 0,
-      vert_to_curve_threshold: 0,
-    },
-    last_new_feed_items_check: '2023-01-01',
-    participates_in_beta_apps: false,
-    'cross-plot__gradient-manager': [],
-    last_new_dashboard_shares_check: '2023-01-01',
-    formation_evaluation_lithology_types: {},
-    formation_evaluation_custom_gradients: [],
-  },
-  last_sign_in_at: '2023-01-01',
-  locked_access: false,
-  unit_ids: [],
-  intercom_admin_id: null,
-  resource: [],
-  consent_to_process_data: false,
-  identity_verification_enabled: null,
-  intercom_user_hash: 'test',
-  impersonating: false,
-  profile_groups: [],
-  preference: {
-    id: 1,
-    push_notifications_enabled: false,
-    emails_enabled: false,
-    sms_enabled: false,
-    alert_levels: [],
-    play_alerts_sound: false,
-    show_intercom_icon: false,
-    segment: [],
-    disable_create_dashboard: false,
-    disable_costs: false,
-    disable_documents: false,
-    realtime_operation_mode: false,
-    disable_file_upload: false,
-    stay_on_app_store: false,
-    new_navigation_beta: false,
-    new_mobile_app_enabled: false,
-  },
-  company: {
-    id: 1,
-    name: 'Test Company',
-    time_zone: 'UTC',
-    language: 'en',
-    provider: 'test',
-    unit_system: {},
-    custom_unit_system: {},
-    custom_units: {},
-    dev_center_enabled: false,
-    with_subscription: false,
-    competitor_analysis_enabled: false,
-    ai_model_scope: 'test',
-  },
-  groups: [],
+export const mockWell = {
+  name: 'Test Well',
+  asset_id: 12345,
+  last_active_at: '2023-01-01',
+  id: '1',
 };
 
-export const mockAppData: AppInstanceData = {
-  id: 1,
-  rig: null,
-  well: null,
-  fracFleet: null,
-  program: {
-    id: null,
-    name: null,
-  },
-  wells: null,
-  isLoading: false,
-  appHash: 'test',
+export const mockRig = {
+  name: 'Test Rig',
+  id: '1',
+  asset_id: 9999,
 };
 
-export const mockAppHeaderProps: AppHeaderData = {
-  app: mockApp,
-  appLastAnnotation: null,
-  appSettings: {},
-  coordinates: { w: 0, h: 0, x: 0, y: 0, pixelHeight: 0, pixelWidth: 0 },
-  currentUser: mockUser,
-  isMaximized: false,
-  layoutEnvironment: { type: 'test', pdfReportMode: false },
+export const mockFracFleet = {
+  name: 'Test Frac Fleet',
+  id: '1',
+  current_pad_id: 101,
 };