@corva/create-app 0.0.0-210a1a8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/README.md +220 -0
  2. package/bin/cca.js +5 -0
  3. package/bin/create-corva-app.cjs +25 -0
  4. package/common/node/.env +15 -0
  5. package/common/node/.env.sample +26 -0
  6. package/common/node/gitignore +130 -0
  7. package/common/package.json +3 -0
  8. package/common/python/.env +5 -0
  9. package/common/python/.env.sample +7 -0
  10. package/common/python/Makefile +18 -0
  11. package/common/python/gitignore +161 -0
  12. package/common/python/pyproject.toml +25 -0
  13. package/common/python/uv.lock +381 -0
  14. package/common/ui/config/vite/corva-vite-config.mjs +384 -0
  15. package/common/ui/devApp.js +1 -0
  16. package/common/ui/index.html +17 -0
  17. package/common/ui/isolatedApp.js +1 -0
  18. package/common/ui/public/DevCenterIsolatedAppPage.html +26 -0
  19. package/common/ui/public/favicon.ico +0 -0
  20. package/common/ui/vite.config.mjs +3 -0
  21. package/common/ui/vitest.global-setup.js +4 -0
  22. package/common/ui/vitest.setup.js +26 -0
  23. package/lib/commands/attach.js +28 -0
  24. package/lib/commands/create.js +471 -0
  25. package/lib/commands/release.js +73 -0
  26. package/lib/commands/rerun.js +34 -0
  27. package/lib/commands/zip.js +39 -0
  28. package/lib/constants/cache.js +5 -0
  29. package/lib/constants/cli.js +32 -0
  30. package/lib/constants/manifest.js +263 -0
  31. package/lib/constants/messages.js +15 -0
  32. package/lib/constants/package.js +300 -0
  33. package/lib/flow.js +59 -0
  34. package/lib/flows/attach.js +8 -0
  35. package/lib/flows/lib/api.js +385 -0
  36. package/lib/flows/lib/create-zip-archive.js +83 -0
  37. package/lib/flows/lib/json.js +30 -0
  38. package/lib/flows/lib/manifest.js +81 -0
  39. package/lib/flows/lib/notification.js +142 -0
  40. package/lib/flows/lib/step-error.js +10 -0
  41. package/lib/flows/lib/waitForMs.js +3 -0
  42. package/lib/flows/prepare.js +6 -0
  43. package/lib/flows/release.js +30 -0
  44. package/lib/flows/rerun.js +8 -0
  45. package/lib/flows/steps/attach/add-app-to-stream.js +23 -0
  46. package/lib/flows/steps/attach/get-all-live-assets.js +135 -0
  47. package/lib/flows/steps/attach/index.js +5 -0
  48. package/lib/flows/steps/attach/prepare-data.js +19 -0
  49. package/lib/flows/steps/prepare-load-app-files.js +12 -0
  50. package/lib/flows/steps/release/add-label.js +10 -0
  51. package/lib/flows/steps/release/add-notes.js +10 -0
  52. package/lib/flows/steps/release/get-config.js +41 -0
  53. package/lib/flows/steps/release/prepare-data.js +12 -0
  54. package/lib/flows/steps/release/publish.js +11 -0
  55. package/lib/flows/steps/release/remove-failed-upload.js +21 -0
  56. package/lib/flows/steps/release/resolve-prebuilt-zip.js +35 -0
  57. package/lib/flows/steps/release/upload-zip-to-corva.js +136 -0
  58. package/lib/flows/steps/release/wait-for-build.js +36 -0
  59. package/lib/flows/steps/rerun/create-task.js +77 -0
  60. package/lib/flows/steps/rerun/ensure-that-app-in-stream.js +68 -0
  61. package/lib/flows/steps/rerun/get-app-version.js +111 -0
  62. package/lib/flows/steps/rerun/prepare-data.js +162 -0
  63. package/lib/flows/steps/rerun/prepare-well-and-stream-data.js +188 -0
  64. package/lib/flows/steps/rerun/rerun.js +13 -0
  65. package/lib/flows/steps/zip-cleanup.js +17 -0
  66. package/lib/flows/steps/zip-create-archive.js +15 -0
  67. package/lib/flows/steps/zip-file-list-resolve.js +273 -0
  68. package/lib/flows/steps/zip-prepare.js +20 -0
  69. package/lib/flows/steps/zip.js +6 -0
  70. package/lib/flows/zip-simple.js +8 -0
  71. package/lib/flows/zip.js +7 -0
  72. package/lib/helpers/cli-version.js +163 -0
  73. package/lib/helpers/commands.js +13 -0
  74. package/lib/helpers/logger.js +35 -0
  75. package/lib/helpers/manifest.js +82 -0
  76. package/lib/helpers/resolve-app-runtime.js +143 -0
  77. package/lib/helpers/utils.js +101 -0
  78. package/lib/helpers/versioning.js +94 -0
  79. package/lib/main.js +63 -0
  80. package/lib/options/api-key.js +6 -0
  81. package/lib/options/app-key.js +6 -0
  82. package/lib/options/app-version.js +3 -0
  83. package/lib/options/bump-version.js +19 -0
  84. package/lib/options/cache.js +11 -0
  85. package/lib/options/env.js +3 -0
  86. package/lib/options/original-cwd.js +3 -0
  87. package/lib/options/silent.js +3 -0
  88. package/lib/options/zip-file-name.js +18 -0
  89. package/package.json +1 -0
  90. package/template_extensions/corva/.commitlintrc.json +6 -0
  91. package/template_extensions/corva/.eslintrc +32 -0
  92. package/template_extensions/corva/.github/pull_request_template.md +14 -0
  93. package/template_extensions/corva/.github/workflows/code-checks.yml +15 -0
  94. package/template_extensions/corva/.github/workflows/develop.yml +19 -0
  95. package/template_extensions/corva/.github/workflows/feat-fix-delete.yml +14 -0
  96. package/template_extensions/corva/.github/workflows/feat-fix.yml +23 -0
  97. package/template_extensions/corva/.github/workflows/release-fix-X.X.X.yml +16 -0
  98. package/template_extensions/corva/.github/workflows/validate-pr-title.yml +19 -0
  99. package/template_extensions/corva/.husky/commit-msg +5 -0
  100. package/template_extensions/corva/.husky/pre-commit +4 -0
  101. package/template_extensions/corva/.release-please-manifest.json +3 -0
  102. package/template_extensions/corva/release-please-config.json +10 -0
  103. package/templates/scheduler_data-time/javascript/README.md +19 -0
  104. package/templates/scheduler_data-time/javascript/__tests__/processor.spec.js +15 -0
  105. package/templates/scheduler_data-time/javascript/index.js +15 -0
  106. package/templates/scheduler_data-time/python/README.md +31 -0
  107. package/templates/scheduler_data-time/python/lambda_function.py +7 -0
  108. package/templates/scheduler_data-time/python/test/__init__.py +0 -0
  109. package/templates/scheduler_data-time/python/test/app_test.py +10 -0
  110. package/templates/scheduler_data-time/typescript/README.md +25 -0
  111. package/templates/scheduler_data-time/typescript/__tests__/processor.spec.ts +15 -0
  112. package/templates/scheduler_data-time/typescript/index.ts +8 -0
  113. package/templates/scheduler_depth/javascript/README.md +19 -0
  114. package/templates/scheduler_depth/javascript/__tests__/processor.spec.js +17 -0
  115. package/templates/scheduler_depth/javascript/index.js +15 -0
  116. package/templates/scheduler_depth/python/README.md +31 -0
  117. package/templates/scheduler_depth/python/lambda_function.py +7 -0
  118. package/templates/scheduler_depth/python/test/__init__.py +0 -0
  119. package/templates/scheduler_depth/python/test/app_test.py +10 -0
  120. package/templates/scheduler_depth/typescript/README.md +25 -0
  121. package/templates/scheduler_depth/typescript/__tests__/processor.spec.ts +17 -0
  122. package/templates/scheduler_depth/typescript/index.ts +8 -0
  123. package/templates/scheduler_natural-time/javascript/README.md +19 -0
  124. package/templates/scheduler_natural-time/javascript/__tests__/processor.spec.js +15 -0
  125. package/templates/scheduler_natural-time/javascript/index.js +15 -0
  126. package/templates/scheduler_natural-time/python/README.md +31 -0
  127. package/templates/scheduler_natural-time/python/lambda_function.py +7 -0
  128. package/templates/scheduler_natural-time/python/test/__init__.py +0 -0
  129. package/templates/scheduler_natural-time/python/test/app_test.py +10 -0
  130. package/templates/scheduler_natural-time/typescript/README.md +25 -0
  131. package/templates/scheduler_natural-time/typescript/__tests__/processor.spec.ts +15 -0
  132. package/templates/scheduler_natural-time/typescript/index.ts +8 -0
  133. package/templates/stream_depth/javascript/README.md +19 -0
  134. package/templates/stream_depth/javascript/__tests__/processor.spec.js +20 -0
  135. package/templates/stream_depth/javascript/index.js +14 -0
  136. package/templates/stream_depth/python/README.md +31 -0
  137. package/templates/stream_depth/python/lambda_function.py +7 -0
  138. package/templates/stream_depth/python/test/__init__.py +0 -0
  139. package/templates/stream_depth/python/test/app_test.py +16 -0
  140. package/templates/stream_depth/typescript/README.md +25 -0
  141. package/templates/stream_depth/typescript/__tests__/processor.spec.ts +20 -0
  142. package/templates/stream_depth/typescript/index.ts +8 -0
  143. package/templates/stream_time/javascript/README.md +19 -0
  144. package/templates/stream_time/javascript/__tests__/processor.spec.js +14 -0
  145. package/templates/stream_time/javascript/index.js +14 -0
  146. package/templates/stream_time/python/README.md +31 -0
  147. package/templates/stream_time/python/lambda_function.py +7 -0
  148. package/templates/stream_time/python/test/__init__.py +0 -0
  149. package/templates/stream_time/python/test/app_test.py +16 -0
  150. package/templates/stream_time/typescript/README.md +25 -0
  151. package/templates/stream_time/typescript/__tests__/processor.spec.ts +14 -0
  152. package/templates/stream_time/typescript/index.ts +8 -0
  153. package/templates/task/javascript/README.md +19 -0
  154. package/templates/task/javascript/__tests__/processor.spec.js +16 -0
  155. package/templates/task/javascript/index.js +15 -0
  156. package/templates/task/python/README.md +31 -0
  157. package/templates/task/python/lambda_function.py +7 -0
  158. package/templates/task/python/test/__init__.py +0 -0
  159. package/templates/task/python/test/app_test.py +8 -0
  160. package/templates/task/typescript/README.md +25 -0
  161. package/templates/task/typescript/__tests__/processor.spec.ts +16 -0
  162. package/templates/task/typescript/index.ts +8 -0
  163. package/templates/ui/javascript/.codex/config.toml +3 -0
  164. package/templates/ui/javascript/.cursor/mcp.json +8 -0
  165. package/templates/ui/javascript/.eslintrc +13 -0
  166. package/templates/ui/javascript/.mcp.json +8 -0
  167. package/templates/ui/javascript/.prettierrc +1 -0
  168. package/templates/ui/javascript/AGENTS.md +306 -0
  169. package/templates/ui/javascript/CLAUDE.md +1 -0
  170. package/templates/ui/javascript/README.md +31 -0
  171. package/templates/ui/javascript/gitignore +27 -0
  172. package/templates/ui/javascript/src/App.completion.jsx +52 -0
  173. package/templates/ui/javascript/src/App.drilling.jsx +49 -0
  174. package/templates/ui/javascript/src/App.module.scss +17 -0
  175. package/templates/ui/javascript/src/AppSettings.jsx +28 -0
  176. package/templates/ui/javascript/src/__tests__/App.test.jsx +26 -0
  177. package/templates/ui/javascript/src/__tests__/AppSettings.test.jsx +28 -0
  178. package/templates/ui/javascript/src/__tests__/TestsExample.test.jsx +37 -0
  179. package/templates/ui/javascript/src/assets/logo.svg +7 -0
  180. package/templates/ui/javascript/src/constants.js +3 -0
  181. package/templates/ui/javascript/src/index.js +8 -0
  182. package/templates/ui/typescript/.codex/config.toml +3 -0
  183. package/templates/ui/typescript/.cursor/mcp.json +8 -0
  184. package/templates/ui/typescript/.eslintrc +31 -0
  185. package/templates/ui/typescript/.mcp.json +8 -0
  186. package/templates/ui/typescript/.prettierrc +1 -0
  187. package/templates/ui/typescript/AGENTS.md +347 -0
  188. package/templates/ui/typescript/CLAUDE.md +1 -0
  189. package/templates/ui/typescript/README.md +31 -0
  190. package/templates/ui/typescript/gitignore +27 -0
  191. package/templates/ui/typescript/src/App.completion.tsx +52 -0
  192. package/templates/ui/typescript/src/App.drilling.tsx +49 -0
  193. package/templates/ui/typescript/src/App.module.scss +17 -0
  194. package/templates/ui/typescript/src/AppSettings.tsx +28 -0
  195. package/templates/ui/typescript/src/__mocks__/mockData.ts +22 -0
  196. package/templates/ui/typescript/src/__tests__/App.test.tsx +27 -0
  197. package/templates/ui/typescript/src/__tests__/AppSettings.test.tsx +28 -0
  198. package/templates/ui/typescript/src/__tests__/TestsExample.test.tsx +37 -0
  199. package/templates/ui/typescript/src/assets/logo.svg +7 -0
  200. package/templates/ui/typescript/src/constants.ts +3 -0
  201. package/templates/ui/typescript/src/custom.d.ts +19 -0
  202. package/templates/ui/typescript/src/index.js +8 -0
  203. package/templates/ui/typescript/src/types.ts +3 -0
  204. package/templates/ui/typescript/tsconfig.json +20 -0
@@ -0,0 +1,306 @@
1
+ # AGENTS.md
2
+
3
+ Corva.AI platform UI app — a React dashboard widget scaffolded by `create-corva-app`.
4
+ Deployed to the Corva platform via `yarn release`.
5
+
6
+ ## Critical Rules
7
+
8
+ These constraints are enforced by the platform. Violating them breaks the build or runtime.
9
+
10
+ 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.
11
+ 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.
12
+ 3. **HTTP clients** — Use `corvaDataAPI` / `corvaAPI` from `@corva/ui/clients` for all network requests.
13
+ 4. **Do not rename or delete** `App.jsx`, `AppSettings.jsx`, or `index.js` — they are platform entry points.
14
+
15
+ ## Project Structure
16
+
17
+ ```
18
+ src/
19
+ App.jsx — Main app component (default export required)
20
+ AppSettings.jsx — Settings panel component (default export required)
21
+ index.js — Root export: { component, settings }
22
+ constants.js — Default settings values
23
+ App.module.scss — Component styles
24
+ __tests__/ — Vitest test files
25
+ __mocks__/ — Mock data (mockAppProps.js, mockAppSettingsProps.js)
26
+ assets/ — Static assets (SVGs, images)
27
+ config/vite/ — Shared Corva Vite config
28
+ vite.config.mjs — Vite entry config
29
+ vitest.setup.js — Test environment setup
30
+ index.html — Dev server host page
31
+ manifest.json — Corva platform app metadata (generated at scaffold time)
32
+ ```
33
+
34
+ ## Key Patterns
35
+
36
+ ### Component Structure
37
+
38
+ - Use JSDoc `@param` / `@returns` annotations for prop documentation.
39
+ - Use `useAppCommons()` from `@corva/ui/effects` for app context (`appKey`).
40
+
41
+ ### Styling
42
+
43
+ The preferred way to write styles is SCSS (`.scss` files).
44
+
45
+ Every `.scss` file must import the shared utilities:
46
+
47
+ ```scss
48
+ @import '@corva/ui/styles/common';
49
+ ```
50
+
51
+ This provides all functions, variables, and mixins below.
52
+
53
+ 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.
54
+
55
+ **`spacing($top, $right?, $bottom?, $left?)`** — 8px base unit:
56
+
57
+ ```scss
58
+ padding: spacing(2); // 16px
59
+ margin: spacing(1, 0); // 8px 0
60
+ gap: spacing(0.5); // 4px
61
+ padding: spacing(2, 1, 2, 1); // 16px 8px 16px 8px
62
+ ```
63
+
64
+ **`colorAlpha($color, $opacity)`** — transparency:
65
+
66
+ ```scss
67
+ background: colorAlpha($palette_t1, 0.08); // white at 8% opacity
68
+ border: 1px solid colorAlpha($palette_t1, 0.12);
69
+ ```
70
+
71
+ **`transition($properties...)`** — standard `cubic-bezier(0.4, 0, 0.2, 1) 0.15s`:
72
+
73
+ ```scss
74
+ transition: transition(opacity);
75
+ transition: transition(color, background-color);
76
+ ```
77
+
78
+ **Full example:**
79
+
80
+ ```scss
81
+ @import '@corva/ui/styles/common';
82
+
83
+ .container {
84
+ padding: spacing(2);
85
+ background: $palette_b5;
86
+ color: $palette_t1;
87
+ transition: transition(opacity, background-color);
88
+
89
+ &:hover {
90
+ background: colorAlpha($palette_t1, 0.08);
91
+ }
92
+ }
93
+
94
+ .label {
95
+ color: $palette_t7;
96
+ font-size: 12px;
97
+ }
98
+ ```
99
+
100
+ **Import in component:**
101
+
102
+ ```javascript
103
+ import styles from './App.module.scss';
104
+ // Use: <div className={styles.container}>
105
+ ```
106
+
107
+ **Colors & Theming:**
108
+
109
+ NEVER hardcode color values (hex, rgb, hsl). Always use `@corva/ui` theme colors:
110
+
111
+ - In SCSS: use SCSS variables from `@corva/ui/styles/common` like `$palette_t1`, `$palette_b5`, `$palette_t7`
112
+ - Use `colorAlpha($color, $opacity)` for transparency instead of raw `rgba()`
113
+ - Run MCP tool `get_theme_docs` (section: "variables") to see all available theme variables
114
+ - Run MCP tool `get_theme_docs` (section: "palette") to see available palette colors with hex values
115
+
116
+ **Rules:**
117
+
118
+ - No inline `style={{...}}` unless absolutely necessary for dynamic values
119
+ - Use `classnames` for conditional/composed classes, never manual string joins
120
+ - No global selectors (tag selectors like `div`, `span`) — use `:global()` only when absolutely necessary
121
+ - No `!important`
122
+ - Use a descriptive camelCase class as the root selector (e.g. `.toolbar`, `.chartPanel`) instead of generic `.root`
123
+
124
+ ### State Management (Zustand)
125
+
126
+ 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.
127
+
128
+ **Store factory + context** — create a factory function and a context to hold the store instance:
129
+
130
+ ```javascript
131
+ // store/createAppStore.js
132
+ import { createContext } from 'react';
133
+ import { create } from 'zustand';
134
+
135
+ export const createAppStore = (initProps = {}) => {
136
+ return create((set, get) => ({
137
+ // Compose sub-stores
138
+ ...createSettingsStore(initProps.settings)(set, get),
139
+ ...createDataStore()(set, get),
140
+ }));
141
+ };
142
+
143
+ export const StoreContext = createContext(null);
144
+ ```
145
+
146
+ **Provider** — create the store once per app mount and pass it via context:
147
+
148
+ ```javascript
149
+ // StoreProvider.js
150
+ import { useState } from 'react';
151
+
152
+ import { StoreContext, createAppStore } from './store/createAppStore';
153
+
154
+ export const StoreProvider = ({ children, savedSettings }) => {
155
+ const [appStore] = useState(() => createAppStore(savedSettings));
156
+
157
+ return <StoreContext.Provider value={appStore}>{children}</StoreContext.Provider>;
158
+ };
159
+ ```
160
+
161
+ **Consumer hooks** — read from context, never from a global store:
162
+
163
+ ```javascript
164
+ // hooks/useAppStore.js
165
+ import { useContext } from 'react';
166
+ import { useStore } from 'zustand';
167
+ import { useStoreWithEqualityFn } from 'zustand/traditional';
168
+
169
+ import { StoreContext } from '../store/createAppStore';
170
+
171
+ /** Read a single top-level key from the store. */
172
+ export const useAppStore = key => {
173
+ const store = useContext(StoreContext);
174
+ if (!store) throw new Error('useAppStore must be used within StoreProvider');
175
+ return useStore(store, state => state[key]);
176
+ };
177
+
178
+ /** Subscribe to a derived value with optional custom equality. */
179
+ export const useAppStoreSelector = (selector, equalityFn) => {
180
+ const store = useContext(StoreContext);
181
+ if (!store) throw new Error('useAppStoreSelector must be used within StoreProvider');
182
+ return useStoreWithEqualityFn(store, selector, equalityFn);
183
+ };
184
+ ```
185
+
186
+ **Usage in components:**
187
+
188
+ ```javascript
189
+ const isLegendVisible = useAppStore('isLegendVisible');
190
+ const selectedChannels = useAppStoreSelector(state => state.selectedChannels);
191
+ ```
192
+
193
+ **Wire it up in `ParentApp`** (see full example with `QueryClientProvider` in the Data Fetching section below).
194
+
195
+ General rules:
196
+
197
+ - Name stores `use[Name]Store` (e.g., `useWellDataStore`)
198
+ - Use selectors: `const value = useAppStore('value')`
199
+ - Keep business logic in store actions
200
+
201
+ ### Data Fetching (React Query v4)
202
+
203
+ 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.
204
+
205
+ **`useQueryClient` hook** — creates an isolated `QueryClient` per app instance:
206
+
207
+ ```javascript
208
+ // hooks/useQueryClient.js
209
+ import { useState } from 'react';
210
+ import { QueryCache, QueryClient } from '@tanstack/react-query';
211
+ import { showErrorNotification } from '@corva/ui/utils';
212
+
213
+ export const useQueryClient = () => {
214
+ const [queryClient] = useState(
215
+ new QueryClient({
216
+ queryCache: new QueryCache({
217
+ onError: error => {
218
+ if (error?.message) {
219
+ showErrorNotification(`Something went wrong: ${error.message}`);
220
+ }
221
+ },
222
+ }),
223
+ defaultOptions: {
224
+ queries: {
225
+ refetchOnWindowFocus: false,
226
+ refetchOnReconnect: false,
227
+ },
228
+ },
229
+ })
230
+ );
231
+
232
+ return queryClient;
233
+ };
234
+ ```
235
+
236
+ **Wire it up in `ParentApp`** — wrap the app tree with `QueryClientProvider`:
237
+
238
+ ```javascript
239
+ import { QueryClientProvider } from '@tanstack/react-query';
240
+
241
+ const ParentApp = () => {
242
+ const { appSettings, onSettingsChange } = useAppCommons();
243
+ const queryClient = useQueryClient();
244
+
245
+ return (
246
+ <QueryClientProvider client={queryClient}>
247
+ <StoreProvider savedSettings={appSettings?.savedSettings}>
248
+ <App />
249
+ </StoreProvider>
250
+ </QueryClientProvider>
251
+ );
252
+ };
253
+
254
+ export default { component: ParentApp, settings: AppSettings };
255
+ ```
256
+
257
+ General rules:
258
+
259
+ - Encapsulate queries in custom hooks (e.g., `useWellData`)
260
+ - Use typed query keys (array format)
261
+ - Always handle `isLoading` and `isError` states
262
+
263
+ ## Naming Conventions
264
+
265
+ - Boolean variables: prefix with `is`, `has`, or `should`
266
+ - Non-empty array checks: `!!array.length` (not `array.length > 0`)
267
+
268
+ ## Testing
269
+
270
+ - **Framework:** Vitest + React Testing Library
271
+ - **Wrapper:** Use `AppTestWrapper` from `@corva/ui/testing` to wrap components
272
+ - **Mocking:** Mock network requests (`vi.mock`/`vi.fn` or msw), never call real APIs
273
+ - **Timezone:** UTC is enforced (`process.env.TZ = 'UTC'`)
274
+ - **Mocked globals:** `ResizeObserver`, `MutationObserver` (in `vitest.setup.js`)
275
+
276
+ ## Commands
277
+
278
+ ```
279
+ yarn start Dev server at http://app.local.corva.ai:8080/
280
+ yarn build Production bundle
281
+ yarn test Run tests
282
+ yarn lint ESLint check
283
+ yarn zip Create deployment ZIP
284
+ yarn release Release to Corva platform
285
+ ```
286
+
287
+ ## @corva/ui Documentation
288
+
289
+ Local documentation for `@corva/ui` is bundled at `node_modules/@corva/ui/docs/`.
290
+ Before implementing any UI component, data fetch, or API call, read the relevant doc file:
291
+
292
+ - **V2 Components:** `node_modules/@corva/ui/docs/01-components-v2/` — Props, examples, usage
293
+ - **V1 Components:** `node_modules/@corva/ui/docs/02-components-v1/` — Legacy components reference
294
+ - **Hooks:** `node_modules/@corva/ui/docs/03-hooks/` — Parameters, return types, examples
295
+ - **API Clients:** `node_modules/@corva/ui/docs/04-clients/` — corvaAPI, corvaDataAPI endpoints
296
+ - **Theme:** `node_modules/@corva/ui/docs/05-theme/` — Color palette, CSS variables
297
+ - **Utilities:** `node_modules/@corva/ui/docs/06-utilities/` — Helper functions
298
+ - **Constants:** `node_modules/@corva/ui/docs/07-constants/` — Platform constants
299
+
300
+ Start with `node_modules/@corva/ui/docs/README.md` for the full index.
301
+ Do NOT guess `@corva/ui` APIs — read the local docs first.
302
+
303
+ ## MCP Server (Interactive Fallback)
304
+
305
+ The `corva-ui` MCP server is pre-configured (`.mcp.json`, `.cursor/mcp.json`, `.codex/config.toml`).
306
+ Use it for interactive queries when the local docs are insufficient or you need to search across components.
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,31 @@
1
+ # Getting Started with Create Corva App
2
+
3
+ ## Available Scripts
4
+
5
+ In the project directory, you can run:
6
+
7
+ ### `yarn start`
8
+
9
+ Runs the app in the development mode.\
10
+ Open [http://app.local.corva.ai:8080](http://app.local.corva.ai:8080/) to view it in the browser.
11
+
12
+ The page will reload if you make edits.\
13
+ You will also see any lint errors in the console.
14
+
15
+ ### `yarn build`
16
+
17
+ Bundles the app into static files for production.
18
+
19
+ ### `yarn zip`
20
+
21
+ Bundles the app into ZIP file in app root directory
22
+
23
+ ### `yarn release`
24
+
25
+ Releases the app into Corva
26
+
27
+ ## Documentation
28
+
29
+ - [Dev Center documentation](https://dc-docs.corva.ai/) – information about development process
30
+ - [Component Library](https://dc-docs.corva.ai/docs/Frontend/Data%20visualization/Components%20library)
31
+ - [Datasets documentation](https://dc-docs.corva.ai/docs/Datasets/Link%20App%20to%20Dataset)
@@ -0,0 +1,27 @@
1
+ # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
2
+
3
+ # dependencies
4
+ /node_modules
5
+ /.pnp
6
+ .pnp.js
7
+
8
+ # testing
9
+ /coverage
10
+
11
+ # production
12
+ /build
13
+ /dist
14
+
15
+ # misc
16
+ .env
17
+ .DS_Store
18
+ .env.local
19
+ .env.development.local
20
+ .env.test.local
21
+ .env.production.local
22
+ .idea
23
+
24
+ npm-debug.log*
25
+ yarn-debug.log*
26
+ yarn-error.log*
27
+ .eslintcache
@@ -0,0 +1,52 @@
1
+ import { AppContainer, AppHeader } from '@corva/ui/componentsV2';
2
+ import { useAppCommons } from '@corva/ui/effects';
3
+
4
+ import { DEFAULT_SETTINGS } from './constants';
5
+ import logo from './assets/logo.svg';
6
+
7
+ import styles from './App.module.scss';
8
+
9
+ const App = () => {
10
+ const { appKey, fracFleet, well, wells, appSettings } = useAppCommons();
11
+ const { isExampleCheckboxChecked = DEFAULT_SETTINGS.isExampleCheckboxChecked } =
12
+ appSettings || {};
13
+ // NOTE: On general type dashboard app receives wells array
14
+ // on asset type dashboard app receives well object
15
+ const wellsList = wells || [well];
16
+
17
+ return (
18
+ <AppContainer header={<AppHeader />} testId={appKey}>
19
+ <div className={styles.container}>
20
+ <img src={logo} alt="logo" className={styles.logo} />
21
+ <p>
22
+ Edit <code>src/App.jsx</code> and save to reload.
23
+ <br />
24
+ <br />
25
+ </p>
26
+ <p>
27
+ Frac Fleet: <span data-testid="fracFleet">{fracFleet?.name || 'No Frac Fleet'}</span>
28
+ <br />
29
+ Wells: <span data-testid="wellsList">{wellsList.map(well => well?.name).join(', ')}</span>
30
+ </p>
31
+ <a
32
+ className="App-link"
33
+ href="https://reactjs.org"
34
+ target="_blank"
35
+ rel="noopener noreferrer"
36
+ >
37
+ Learn React
38
+ </a>
39
+ </div>
40
+ <div>
41
+ Settings &quot;Example&quot; checkbox is{' '}
42
+ <span data-testid="exampleCheckboxChecked">
43
+ {isExampleCheckboxChecked ? 'checked' : 'unchecked'}
44
+ </span>
45
+ </div>
46
+ </AppContainer>
47
+ );
48
+ };
49
+
50
+ // Important: Do not change root component default export (App.jsx). Use it as container
51
+ // for your App. It's required to make build and zip scripts work as expected;
52
+ export default App;
@@ -0,0 +1,49 @@
1
+ import { AppContainer, AppHeader } from '@corva/ui/componentsV2';
2
+ import { useAppCommons } from '@corva/ui/effects';
3
+
4
+ import { DEFAULT_SETTINGS } from './constants';
5
+ import logo from './assets/logo.svg';
6
+
7
+ import styles from './App.module.scss';
8
+
9
+ const App = () => {
10
+ const { appKey, rig, well, appSettings } = useAppCommons();
11
+ const { isExampleCheckboxChecked = DEFAULT_SETTINGS.isExampleCheckboxChecked } =
12
+ appSettings || {};
13
+
14
+ return (
15
+ <AppContainer header={<AppHeader />} testId={appKey}>
16
+ <div className={styles.container}>
17
+ <img src={logo} alt="logo" className={styles.logo} />
18
+ <p>
19
+ Edit <code>src/App.jsx</code> and save to reload.
20
+ <br />
21
+ <br />
22
+ </p>
23
+ <p>
24
+ Rig: <span data-testid="rig">{rig?.name}</span>
25
+ <br />
26
+ Well: <span data-testid="well">{well?.name}</span>
27
+ </p>
28
+ <a
29
+ className="App-link"
30
+ href="https://reactjs.org"
31
+ target="_blank"
32
+ rel="noopener noreferrer"
33
+ >
34
+ Learn React
35
+ </a>
36
+ </div>
37
+ <div>
38
+ Settings &quot;Example&quot; checkbox is{' '}
39
+ <span data-testid="exampleCheckboxState">
40
+ {isExampleCheckboxChecked ? 'checked' : 'unchecked'}
41
+ </span>
42
+ </div>
43
+ </AppContainer>
44
+ );
45
+ };
46
+
47
+ // Important: Do not change root component default export (App.jsx). Use it as container
48
+ // for your App. It's required to make build and zip scripts work as expected;
49
+ export default App;
@@ -0,0 +1,17 @@
1
+ .container {
2
+ text-align: center;
3
+ }
4
+
5
+ @keyframes App-logo-spin {
6
+ from {
7
+ transform: rotate(0deg);
8
+ }
9
+ to {
10
+ transform: rotate(-360deg);
11
+ }
12
+ }
13
+
14
+ .logo {
15
+ animation: App-logo-spin infinite 20s linear;
16
+ height: 50px;
17
+ }
@@ -0,0 +1,28 @@
1
+ import { Checkbox, FormControlLabel } from '@material-ui/core';
2
+ import { useAppCommons } from '@corva/ui/effects';
3
+
4
+ import { DEFAULT_SETTINGS } from './constants';
5
+
6
+ const AppSettings = () => {
7
+ const { appSettings, onSettingChange } = useAppCommons();
8
+ const settings = { ...DEFAULT_SETTINGS, ...appSettings };
9
+
10
+ return (
11
+ <div>
12
+ <FormControlLabel
13
+ label="Example checkbox"
14
+ control={
15
+ <Checkbox
16
+ data-testid="exampleCheckbox"
17
+ checked={settings.isExampleCheckboxChecked}
18
+ onChange={e => onSettingChange('isExampleCheckboxChecked', e.target.checked)}
19
+ />
20
+ }
21
+ />
22
+ </div>
23
+ );
24
+ };
25
+
26
+ // Important: Do not change root component default export (AppSettings.jsx). Use it as container
27
+ // for your App Settings. It's required to make build and zip scripts work as expected;
28
+ export default AppSettings;
@@ -0,0 +1,26 @@
1
+ import { render, screen } from '@testing-library/react';
2
+ import { AppTestWrapper } from '@corva/ui/testing';
3
+
4
+ import App from '../App';
5
+
6
+ describe('<App />', () => {
7
+ it('should show correct layout', () => {
8
+ render(
9
+ <AppTestWrapper appSettings={{ isExampleCheckboxChecked: true }}>
10
+ <App />
11
+ </AppTestWrapper>
12
+ );
13
+
14
+ screen.getByText(/checked/i);
15
+ });
16
+
17
+ it('should show correct layout when settings are not provided', () => {
18
+ render(
19
+ <AppTestWrapper appSettings={{}}>
20
+ <App />
21
+ </AppTestWrapper>
22
+ );
23
+
24
+ screen.getByText(/unchecked/i);
25
+ });
26
+ });
@@ -0,0 +1,28 @@
1
+ import { render, screen, act } from '@testing-library/react';
2
+ import userEvent from '@testing-library/user-event';
3
+ import { AppTestWrapper } from '@corva/ui/testing';
4
+
5
+ import AppSettings from '../AppSettings';
6
+
7
+ describe('<AppSettings />', () => {
8
+ it('should call onChange with a changed setting on settings change', async () => {
9
+ const handleSettingChange = vi.fn();
10
+
11
+ render(
12
+ <AppTestWrapper
13
+ appSettings={{ isExampleCheckboxChecked: true }}
14
+ onSettingChange={handleSettingChange}
15
+ >
16
+ <AppSettings />
17
+ </AppTestWrapper>
18
+ );
19
+
20
+ const exampleCheckbox = screen.getByRole('checkbox', { name: /example/i });
21
+
22
+ await act(async () => {
23
+ await userEvent.click(exampleCheckbox);
24
+ });
25
+
26
+ expect(handleSettingChange).toBeCalledWith('isExampleCheckboxChecked', false);
27
+ });
28
+ });
@@ -0,0 +1,37 @@
1
+ import { useState } from 'react';
2
+ import { render, screen, waitFor } from '@testing-library/react';
3
+ import { Button } from '@corva/ui/componentsV2';
4
+ import userEvent from '@testing-library/user-event';
5
+
6
+ const Toggle = () => {
7
+ const [isOn, setIsOn] = useState(false);
8
+
9
+ return (
10
+ <>
11
+ {isOn ? 'ON' : 'OFF'}
12
+ <Button onClick={() => setIsOn(value => !value)}>toggle</Button>
13
+ </>
14
+ );
15
+ };
16
+
17
+ describe('Tests examples', () => {
18
+ it('should use UTC timezone by default to not depend on the environment timezone', () => {
19
+ expect(Intl.DateTimeFormat().resolvedOptions().timeZone).toBe('UTC');
20
+ });
21
+
22
+ describe('<Toggle />', () => {
23
+ it('should be OFF by default', () => {
24
+ render(<Toggle />);
25
+
26
+ expect(screen.getByText('OFF')).toBeInTheDocument();
27
+ });
28
+
29
+ it('should switch to ON after a single press', async () => {
30
+ render(<Toggle />);
31
+
32
+ userEvent.click(screen.getByText('toggle'));
33
+
34
+ await waitFor(() => screen.getByText('ON'));
35
+ });
36
+ });
37
+ });
@@ -0,0 +1,7 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 841.9 595.3">
2
+ <g fill="#61DAFB">
3
+ <path d="M666.3 296.5c0-32.5-40.7-63.3-103.1-82.4 14.4-63.6 8-114.2-20.2-130.4-6.5-3.8-14.1-5.6-22.4-5.6v22.3c4.6 0 8.3.9 11.4 2.6 13.6 7.8 19.5 37.5 14.9 75.7-1.1 9.4-2.9 19.3-5.1 29.4-19.6-4.8-41-8.5-63.5-10.9-13.5-18.5-27.5-35.3-41.6-50 32.6-30.3 63.2-46.9 84-46.9V78c-27.5 0-63.5 19.6-99.9 53.6-36.4-33.8-72.4-53.2-99.9-53.2v22.3c20.7 0 51.4 16.5 84 46.6-14 14.7-28 31.4-41.3 49.9-22.6 2.4-44 6.1-63.6 11-2.3-10-4-19.7-5.2-29-4.7-38.2 1.1-67.9 14.6-75.8 3-1.8 6.9-2.6 11.5-2.6V78.5c-8.4 0-16 1.8-22.6 5.6-28.1 16.2-34.4 66.7-19.9 130.1-62.2 19.2-102.7 49.9-102.7 82.3 0 32.5 40.7 63.3 103.1 82.4-14.4 63.6-8 114.2 20.2 130.4 6.5 3.8 14.1 5.6 22.5 5.6 27.5 0 63.5-19.6 99.9-53.6 36.4 33.8 72.4 53.2 99.9 53.2 8.4 0 16-1.8 22.6-5.6 28.1-16.2 34.4-66.7 19.9-130.1 62-19.1 102.5-49.9 102.5-82.3zm-130.2-66.7c-3.7 12.9-8.3 26.2-13.5 39.5-4.1-8-8.4-16-13.1-24-4.6-8-9.5-15.8-14.4-23.4 14.2 2.1 27.9 4.7 41 7.9zm-45.8 106.5c-7.8 13.5-15.8 26.3-24.1 38.2-14.9 1.3-30 2-45.2 2-15.1 0-30.2-.7-45-1.9-8.3-11.9-16.4-24.6-24.2-38-7.6-13.1-14.5-26.4-20.8-39.8 6.2-13.4 13.2-26.8 20.7-39.9 7.8-13.5 15.8-26.3 24.1-38.2 14.9-1.3 30-2 45.2-2 15.1 0 30.2.7 45 1.9 8.3 11.9 16.4 24.6 24.2 38 7.6 13.1 14.5 26.4 20.8 39.8-6.3 13.4-13.2 26.8-20.7 39.9zm32.3-13c5.4 13.4 10 26.8 13.8 39.8-13.1 3.2-26.9 5.9-41.2 8 4.9-7.7 9.8-15.6 14.4-23.7 4.6-8 8.9-16.1 13-24.1zM421.2 430c-9.3-9.6-18.6-20.3-27.8-32 9 .4 18.2.7 27.5.7 9.4 0 18.7-.2 27.8-.7-9 11.7-18.3 22.4-27.5 32zm-74.4-58.9c-14.2-2.1-27.9-4.7-41-7.9 3.7-12.9 8.3-26.2 13.5-39.5 4.1 8 8.4 16 13.1 24 4.7 8 9.5 15.8 14.4 23.4zM420.7 163c9.3 9.6 18.6 20.3 27.8 32-9-.4-18.2-.7-27.5-.7-9.4 0-18.7.2-27.8.7 9-11.7 18.3-22.4 27.5-32zm-74 58.9c-4.9 7.7-9.8 15.6-14.4 23.7-4.6 8-8.9 16-13 24-5.4-13.4-10-26.8-13.8-39.8 13.1-3.1 26.9-5.8 41.2-7.9zm-90.5 125.2c-35.4-15.1-58.3-34.9-58.3-50.6 0-15.7 22.9-35.6 58.3-50.6 8.6-3.7 18-7 27.7-10.1 5.7 19.6 13.2 40 22.5 60.9-9.2 20.8-16.6 41.1-22.2 60.6-9.9-3.1-19.3-6.5-28-10.2zM310 490c-13.6-7.8-19.5-37.5-14.9-75.7 1.1-9.4 2.9-19.3 5.1-29.4 19.6 4.8 41 8.5 63.5 10.9 13.5 18.5 27.5 35.3 41.6 50-32.6 30.3-63.2 46.9-84 46.9-4.5-.1-8.3-1-11.3-2.7zm237.2-76.2c4.7 38.2-1.1 67.9-14.6 75.8-3 1.8-6.9 2.6-11.5 2.6-20.7 0-51.4-16.5-84-46.6 14-14.7 28-31.4 41.3-49.9 22.6-2.4 44-6.1 63.6-11 2.3 10.1 4.1 19.8 5.2 29.1zm38.5-66.7c-8.6 3.7-18 7-27.7 10.1-5.7-19.6-13.2-40-22.5-60.9 9.2-20.8 16.6-41.1 22.2-60.6 9.9 3.1 19.3 6.5 28.1 10.2 35.4 15.1 58.3 34.9 58.3 50.6-.1 15.7-23 35.6-58.4 50.6zM320.8 78.4z"/>
4
+ <circle cx="420.9" cy="296.5" r="45.7"/>
5
+ <path d="M520.5 78.1z"/>
6
+ </g>
7
+ </svg>
@@ -0,0 +1,3 @@
1
+ export const DEFAULT_SETTINGS = {
2
+ isExampleCheckboxChecked: false,
3
+ };
@@ -0,0 +1,8 @@
1
+ // DO NOT modify this structure
2
+ import App from './App';
3
+ import AppSettings from './AppSettings';
4
+
5
+ export default {
6
+ component: App,
7
+ settings: AppSettings,
8
+ };
@@ -0,0 +1,3 @@
1
+ [mcp_servers.corva-ui]
2
+ command = "npx"
3
+ args = ["-p", "@corva/ui", "corva-ui-mcp"]
@@ -0,0 +1,8 @@
1
+ {
2
+ "mcpServers": {
3
+ "corva-ui": {
4
+ "command": "npx",
5
+ "args": ["-p", "@corva/ui", "corva-ui-mcp"]
6
+ }
7
+ }
8
+ }