@corva/create-app 0.0.0-2576df8

package/templates/ui/typescript/AGENTS.md

@@ -0,0 +1,344 @@
+# 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.scss             — Component styles (SCSS 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
+
+The preferred way to write styles is SCSS (`.scss` files).
+
+Every `.scss` file must import the shared utilities:
+
+```scss
+@import '@corva/ui/styles/common';
+```
+
+This provides all functions, variables, and mixins below.
+
+For custom shared variables or mixins specific to the project, create a `src/styles/` directory (e.g. `_variables.scss`, `_common.scss`) and import them alongside the `@corva/ui` import.
+
+**`spacing($top, $right?, $bottom?, $left?)`** — 8px base unit:
+
+```scss
+padding: spacing(2); // 16px
+margin: spacing(1, 0); // 8px 0
+gap: spacing(0.5); // 4px
+padding: spacing(2, 1, 2, 1); // 16px 8px 16px 8px
+```
+
+**`colorAlpha($color, $opacity)`** — transparency:
+
+```scss
+background: colorAlpha($palette_t1, 0.08); // white at 8% opacity
+border: 1px solid colorAlpha($palette_t1, 0.12);
+```
+
+**`transition($properties...)`** — standard `cubic-bezier(0.4, 0, 0.2, 1) 0.15s`:
+
+```scss
+transition: transition(opacity);
+transition: transition(color, background-color);
+```
+
+**Full example:**
+
+```scss
+@import '@corva/ui/styles/common';
+
+.container {
+  padding: spacing(2);
+  background: $palette_b5;
+  color: $palette_t1;
+  transition: transition(opacity, background-color);
+
+  &:hover {
+    background: colorAlpha($palette_t1, 0.08);
+  }
+}
+
+.label {
+  color: $palette_t7;
+  font-size: 12px;
+}
+```
+
+**Import in component:**
+
+```typescript
+import styles from './App.scss';
+// Use: <div className={styles.container}>
+```
+
+**Colors & Theming:**
+
+NEVER hardcode color values (hex, rgb, hsl). Always use `@corva/ui` theme colors:
+
+- In SCSS: use SCSS variables from `@corva/ui/styles/common` like `$palette_t1`, `$palette_b5`, `$palette_t7`
+- Use `colorAlpha($color, $opacity)` for transparency instead of raw `rgba()`
+- Run MCP tool `get_theme_docs` (section: "variables") to see all available theme variables
+- Run MCP tool `get_theme_docs` (section: "palette") to see available palette colors with hex values
+
+**Rules:**
+
+- No inline `style={{...}}` unless absolutely necessary for dynamic values
+- Use `classnames` for conditional/composed classes, never manual string joins
+- No global selectors (tag selectors like `div`, `span`) — use `:global()` only when absolutely necessary
+- No `!important`
+- Use a descriptive camelCase class as the root selector (e.g. `.toolbar`, `.chartPanel`) instead of generic `.root`
+
+### 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/README.md

@@ -0,0 +1,31 @@
+# Getting Started with Create Corva App
+
+## Available Scripts
+
+In the project directory, you can run:
+
+### `yarn start`
+
+Runs the app in the development mode.\
+Open [http://app.local.corva.ai:8080](http://app.local.corva.ai:8080/) to view it in the browser.
+
+The page will reload if you make edits.\
+You will also see any lint errors in the console.
+
+### `yarn build`
+
+Bundles the app into static files for production.
+
+### `yarn zip`
+
+Bundles the app into ZIP file in app root directory
+
+### `yarn release`
+
+Releases the app into Corva
+
+## Documentation
+
+- [Dev Center documentation](https://dc-docs.corva.ai/) – information about development process
+- [Component Library](https://dc-docs.corva.ai/docs/Frontend/Data%20visualization/Components%20library)
+- [Datasets documentation](https://dc-docs.corva.ai/docs/Datasets/Link%20App%20to%20Dataset)

package/templates/ui/typescript/config/jest/babelTransform.js

@@ -0,0 +1,16 @@
+/* eslint-disable */
+
+const babelJest = require('babel-jest').default;
+
+module.exports = babelJest.createTransformer({
+  presets: [
+    [
+      require.resolve('babel-preset-react-app'),
+      {
+        runtime: 'automatic',
+      },
+    ],
+  ],
+  babelrc: false,
+  configFile: false,
+});

package/templates/ui/typescript/config/jest/cssTransform.js

@@ -0,0 +1,16 @@
+/* eslint-disable */
+
+// This is a custom Jest transformer turning style imports into empty objects.
+// http://facebook.github.io/jest/docs/en/webpack.html
+
+module.exports = {
+  process() {
+    return {
+      code: 'module.exports = {};',
+    };
+  },
+  getCacheKey() {
+    // The output is always the same.
+    return 'cssTransform';
+  },
+};

package/templates/ui/typescript/config/jest/fileTransform.js

@@ -0,0 +1,48 @@
+/* eslint-disable */
+
+const path = require('path');
+
+// This is a custom Jest transformer turning file imports into filenames.
+// http://facebook.github.io/jest/docs/en/webpack.html
+
+const toPascalCase = str => {
+  const allWordsIterator = str.matchAll(/\w+/g);
+
+  return Array.from(allWordsIterator).reduce((acc, matchResult) => {
+    const word = matchResult[0];
+    return acc + word[0].toUpperCase() + word.slice(1).toLowerCase();
+  }, '');
+};
+
+module.exports = {
+  process(src, filename) {
+    const assetFilename = JSON.stringify(path.basename(filename));
+
+    if (filename.match(/\.svg$/)) {
+      // Based on how SVGR generates a component name:
+      // https://github.com/smooth-code/svgr/blob/01b194cf967347d43d4cbe6b434404731b87cf27/packages/core/src/state.js#L6
+      const pascalCaseFilename = toPascalCase(path.parse(filename).name);
+      const componentName = `Svg${pascalCaseFilename}`;
+      return {
+        code: `const React = require('react');
+        module.exports = {
+          __esModule: true,
+          default: ${assetFilename},
+          ReactComponent: React.forwardRef(function ${componentName}(props, ref) {
+            return {
+              $$typeof: Symbol.for('react.element'),
+              type: 'svg',
+              ref: ref,
+              key: null,
+              props: Object.assign({}, props, {
+                children: ${assetFilename}
+              })
+            };
+          }),
+        };`,
+      };
+    }
+
+    return { code: `module.exports = ${assetFilename};` };
+  },
+};

package/templates/ui/typescript/config/jest/globalSetup.js

@@ -0,0 +1,5 @@
+module.exports = async () => {
+  // use UTC timezone to not break tests when you run them on
+  // an environemnt with a different timezone
+  process.env.TZ = 'UTC';
+};

package/templates/ui/typescript/config/jest/setupTests.js

@@ -0,0 +1,30 @@
+/* eslint-disable */
+
+// jest-dom adds custom jest matchers for asserting on DOM nodes.
+// allows you to do things like:
+// expect(element).toHaveTextContent(/react/i)
+// learn more: https://github.com/testing-library/jest-dom
+// eslint-disable-next-line
+import '@testing-library/jest-dom/extend-expect';
+
+// Set UTC timezone for tests to not use the environment timezone
+process.env.TZ = 'UTC';
+
+// Mock ResizeObserver & MutationObserver
+class FakeObserver {
+  observe() {}
+  unobserve() {}
+  disconnect() {}
+}
+
+global.ResizeObserver = FakeObserver;
+global.MutationObserver = FakeObserver;
+
+// Suppressing "Could not parse CSS stylesheet" from JSDOM
+const originalConsoleError = global.console.error;
+global.console.error = (message, ...optionalParams) => {
+  if (message.includes('Could not parse CSS stylesheet')) {
+    return;
+  }
+  originalConsoleError(message, ...optionalParams);
+};

package/templates/ui/typescript/config-overrides.js

@@ -0,0 +1,10 @@
+const { getWebpackConfig } = require('@corva/dc-platform-shared/cjs');
+const { merge } = require('webpack-merge');
+
+module.exports = (env, argv) => {
+  return merge(
+    getWebpackConfig(env, argv),
+    // NOTE: Custom webpack 5 plugins and module rules can be provided here
+    {}
+  );
+};

package/templates/ui/typescript/gitignore

@@ -0,0 +1,27 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# production
+/build
+/dist
+
+# misc
+.env
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.idea
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.eslintcache

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

@@ -0,0 +1,52 @@
+import { AppContainer, AppHeader } from '@corva/ui/componentsV2';
+import { useAppCommons } from '@corva/ui/effects';
+
+import { DEFAULT_SETTINGS } from './constants';
+import logo from './assets/logo.svg';
+
+import styles from './App.scss';
+
+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];
+
+  return (
+    <AppContainer header={<AppHeader />} testId={appKey}>
+      <div className={styles.container}>
+        <img src={logo} alt="logo" className={styles.logo} />
+        <p>
+          Edit <code>src/App.js</code> and save to reload.
+          <br />
+          <br />
+        </p>
+        <p>
+          Frac Fleet: <span data-testid="fracFleet">{fracFleet?.name || 'No Frac Fleet'}</span>
+          <br />
+          Wells: <span data-testid="wellsList">{wellsList.map(well => well?.name).join(', ')}</span>
+        </p>
+        <a
+          className="App-link"
+          href="https://reactjs.org"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Learn React
+        </a>
+      </div>
+      <div>
+        Settings &quot;Example&quot; checkbox is{' '}
+        <span data-testid="exampleCheckboxState">
+          {isExampleCheckboxChecked ? 'checked' : 'unchecked'}
+        </span>
+      </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;
+export default App;

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

@@ -0,0 +1,49 @@
+import { AppContainer, AppHeader } from '@corva/ui/componentsV2';
+import { useAppCommons } from '@corva/ui/effects';
+
+import { DEFAULT_SETTINGS } from './constants';
+import logo from './assets/logo.svg';
+
+import styles from './App.scss';
+
+const App = () => {
+  const { appKey, rig, well, appSettings } = useAppCommons();
+  const { isExampleCheckboxChecked = DEFAULT_SETTINGS.isExampleCheckboxChecked } =
+    appSettings || {};
+
+  return (
+    <AppContainer header={<AppHeader />} testId={appKey}>
+      <div className={styles.container}>
+        <img src={logo} alt="logo" className={styles.logo} />
+        <p>
+          Edit <code>src/App.js</code> and save to reload.
+          <br />
+          <br />
+        </p>
+        <p>
+          Rig: <span data-testid="rig">{rig?.name}</span>
+          <br />
+          Well: <span data-testid="well">{well?.name}</span>
+        </p>
+        <a
+          className="App-link"
+          href="https://reactjs.org"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Learn React
+        </a>
+      </div>
+      <div>
+        Settings &quot;Example&quot; checkbox is{' '}
+        <span data-testid="exampleCheckboxState">
+          {isExampleCheckboxChecked ? 'checked' : 'unchecked'}
+        </span>
+      </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;
+export default App;

package/templates/ui/typescript/src/App.scss

@@ -0,0 +1,17 @@
+.container {
+  text-align: center;
+}
+
+@keyframes App-logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(-360deg);
+  }
+}
+
+.logo {
+  animation: App-logo-spin infinite 20s linear;
+  height: 50px;
+}

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

@@ -0,0 +1,28 @@
+import { Checkbox, FormControlLabel } from '@material-ui/core';
+import { useAppCommons } from '@corva/ui/effects';
+
+import { DEFAULT_SETTINGS } from './constants';
+
+const AppSettings = () => {
+  const { appSettings, onSettingChange } = useAppCommons();
+  const settings = { ...DEFAULT_SETTINGS, ...appSettings };
+
+  return (
+    <div>
+      <FormControlLabel
+        label="Example checkbox"
+        control={
+          <Checkbox
+            data-testid="exampleCheckbox"
+            checked={settings.isExampleCheckboxChecked}
+            onChange={e => onSettingChange('isExampleCheckboxChecked', e.target.checked)}
+          />
+        }
+      />
+    </div>
+  );
+};
+
+// Important: Do not change root component default export (AppSettings.js). Use it as container
+//  for your App Settings. It's required to make build and zip scripts work as expected;
+export default AppSettings;