@checkstack/ui 1.8.3 → 1.9.0

package/src/components/DynamicForm/FormField.tsx

@@ -33,6 +33,9 @@ export const FormField: React.FC<FormFieldProps> = ({
   formValues,
   optionsResolvers,
   templateProperties,
+  typeDefinitions,
+  shellEnvVars,
+  starterTemplates,
   onChange,
 }) => {
   const description = propSchema.description || "";
@@ -129,6 +132,9 @@ export const FormField: React.FC<FormFieldProps> = ({
           isRequired={isRequired}
           editorTypes={editorTypes}
           templateProperties={templateProperties}
+          typeDefinitions={typeDefinitions}
+          shellEnvVars={shellEnvVars}
+          starterTemplates={starterTemplates}
           onChange={onChange as (val: string | undefined) => void}
         />
       );
@@ -346,6 +352,9 @@ export const FormField: React.FC<FormFieldProps> = ({
             formValues={formValues}
             optionsResolvers={optionsResolvers}
             templateProperties={templateProperties}
+            typeDefinitions={typeDefinitions}
+            shellEnvVars={shellEnvVars}
+            starterTemplates={starterTemplates}
             onChange={(val) =>
               onChange({ ...(value as Record<string, unknown>), [key]: val })
             }
@@ -454,6 +463,9 @@ export const FormField: React.FC<FormFieldProps> = ({
                   formValues={formValues}
                   optionsResolvers={optionsResolvers}
                   templateProperties={templateProperties}
+                  typeDefinitions={typeDefinitions}
+                  shellEnvVars={shellEnvVars}
+                  starterTemplates={starterTemplates}
                   onChange={(val) => {
                     const next = [...(items as unknown[])];
                     next[index] = val;
@@ -582,6 +594,9 @@ export const FormField: React.FC<FormFieldProps> = ({
                 formValues={formValues}
                 optionsResolvers={optionsResolvers}
                 templateProperties={templateProperties}
+                typeDefinitions={typeDefinitions}
+                shellEnvVars={shellEnvVars}
+                starterTemplates={starterTemplates}
                 onChange={(val) => onChange({ ...currentValue, [key]: val })}
               />
             ))}

package/src/components/DynamicForm/MultiTypeEditorField.tsx

@@ -17,6 +17,8 @@ import {
   parseFormData,
   EDITOR_TYPE_LABELS,
 } from "./utils";
+import type { EditorStarterTemplates, ShellEnvVar } from "./types";
+import { pickStarterForEmptyField } from "./starterTemplateSelector";
 
 export interface MultiTypeEditorFieldProps {
   /** Unique identifier for the field */
@@ -33,6 +35,25 @@ export interface MultiTypeEditorFieldProps {
   editorTypes: EditorType[];
   /** Optional template properties for autocomplete */
   templateProperties?: TemplateProperty[];
+  /**
+   * Optional TypeScript declarations injected into Monaco for TS/JS modes —
+   * powers IntelliSense + return-shape error reporting against the runtime
+   * context the user will see (`context.config`, `context.event`, ...).
+   */
+  typeDefinitions?: string;
+  /**
+   * Optional shell env-var hints surfaced as completion items after `$`
+   * (and `${`) in shell mode. Typically populated by the platform with
+   * names like `EVENT_ID` / `PAYLOAD_*` so users don't have to memorise.
+   */
+  shellEnvVars?: ShellEnvVar[];
+  /**
+   * Optional starter templates per editor language. When the field is
+   * empty (and the user hasn't typed yet), switching to an editor with a
+   * starter for that language pre-populates the editor so users see a
+   * working example instead of a blank canvas.
+   */
+  starterTemplates?: EditorStarterTemplates;
   /** Callback when value changes */
   onChange: (value: string | undefined) => void;
 }
@@ -50,6 +71,9 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
   isRequired,
   editorTypes,
   templateProperties,
+  typeDefinitions,
+  shellEnvVars,
+  starterTemplates,
   onChange,
 }) => {
   // Detect initial editor type from value
@@ -57,16 +81,81 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
     detectEditorType(value, editorTypes),
   );
 
-  // Track if this is the initial mount to avoid re-detecting on every value change
-  const isInitialMount = React.useRef(true);
+  // Latched once the field has had non-empty content at least once for
+  // this mount. Used by the seed effects below to decide whether to
+  // (re-)install the starter template.
+  const hasSeededRef = React.useRef(false);
+
+  // React reuses this `MultiTypeEditorField` instance across collector
+  // switches when its parent `FormField` keeps the same key (e.g. both
+  // collectors have a property called `script`). The `useState`
+  // initializer above only runs on the first mount, so without this
+  // effect a switch from a shell-only collector to a typescript-only
+  // collector leaves `selectedType` stuck on "shell" — Monaco then
+  // tokenises the new collector's TS content as shell (no
+  // highlighting), and the reverse direction tokenises shell content as
+  // TS (nonsense "Cannot find name" errors).
+  //
+  // Whenever `editorTypes` changes and the current selection is no
+  // longer offered, re-detect from the new value. We deliberately do
+  // NOT reset on every `value` change — that would clobber the user's
+  // manual dropdown choice mid-edit.
   React.useEffect(() => {
-    if (isInitialMount.current) {
-      isInitialMount.current = false;
-      return;
+    if (!editorTypes.includes(selectedType)) {
+      const next = detectEditorType(value, editorTypes);
+      setSelectedType(next);
+      // Reset the seed latch too — this is effectively a fresh field
+      // for a different collector, and the new language's starter
+      // template should be eligible again.
+      hasSeededRef.current = false;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- intentional: only re-derive when the offered types change
+  }, [editorTypes]);
+
+  // Seed an empty field with the starter template for its detected
+  // language so users see a working example instead of a blank canvas.
+  //
+  // Why this isn't just `useEffect(..., [])`:
+  // React fires CHILD effects before PARENT effects. `DynamicForm`'s
+  // own init effect (which applies schema defaults) runs AFTER this one
+  // and, on initial mount, calls `onChange(defaults)` — which clobbers
+  // a freshly-seeded `script: starter` back to `script: ""` because the
+  // defaults effect's closure-captured `value` was the original `{}`.
+  // A naive `[]`-dep seed would therefore appear to do nothing.
+  //
+  // Two-effect design fixes this without depending on cross-component
+  // effect ordering:
+  //   1. The "observed" effect (declared FIRST) flips `hasSeededRef` to
+  //      true the moment we see non-empty content in `value` — whether
+  //      that came from our seed surviving, a parent default landing
+  //      with content, or the user typing.
+  //   2. The "seed" effect re-runs on every value/starter change and
+  //      installs the starter while `hasSeededRef` is still false. If
+  //      the parent clobbers us back to "", we just re-seed on the
+  //      next pass — until the value sticks and effect (1) latches.
+  //
+  // The latch also means we DON'T re-seed if the user deliberately
+  // deletes their content later, or on any subsequent refetch / parent
+  // re-render: once non-empty has been observed at least once, the
+  // field is the user's territory.
+  React.useEffect(() => {
+    if (!hasSeededRef.current && (value ?? "").trim().length > 0) {
+      hasSeededRef.current = true;
     }
-    // Don't re-detect type when value changes after initial mount
   }, [value]);
 
+  React.useEffect(() => {
+    if (hasSeededRef.current) return;
+    const starter = pickStarterForEmptyField({
+      value,
+      selectedType,
+      starterTemplates,
+    });
+    if (starter !== undefined) {
+      onChange(starter);
+    }
+  }, [value, selectedType, starterTemplates, onChange]);
+
   const handleTypeChange = (newType: EditorType) => {
     setSelectedType(newType);
 
@@ -76,6 +165,19 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
       return;
     }
 
+    // If the field is empty after the switch and we have a starter template
+    // for the new language, seed it. (Switching languages on a non-empty
+    // field preserves the existing content, just like before.)
+    const starter = pickStarterForEmptyField({
+      value,
+      selectedType: newType,
+      starterTemplates,
+    });
+    if (starter !== undefined) {
+      onChange(starter);
+      return;
+    }
+
     // When switching to formdata
     if (newType === "formdata") {
       if (!value || value.trim() === "") {
@@ -242,6 +344,7 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           language="javascript"
           minHeight="150px"
           templateProperties={templateProperties}
+          typeDefinitions={typeDefinitions}
         />
       )}
 
@@ -253,6 +356,7 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           language="typescript"
           minHeight="150px"
           templateProperties={templateProperties}
+          typeDefinitions={typeDefinitions}
         />
       )}
 
@@ -264,6 +368,7 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           language="shell"
           minHeight="150px"
           templateProperties={templateProperties}
+          shellEnvVars={shellEnvVars}
         />
       )}
     </div>

package/src/components/DynamicForm/index.ts

@@ -13,6 +13,8 @@ export type {
   OptionsResolver,
   ResolverOption,
   EditorType,
+  ShellEnvVar,
+  EditorStarterTemplates,
 } from "./types";
 
 // Utility functions

package/src/components/DynamicForm/starterTemplateSelector.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "bun:test";
+import { pickStarterForEmptyField } from "./starterTemplateSelector";
+import type { EditorStarterTemplates } from "./types";
+
+/**
+ * Regression suite for the starter-template seeding behaviour in
+ * `MultiTypeEditorField`.
+ *
+ * The previous implementation gated seeding behind an `isInitialMount`
+ * ref that a sibling effect with `[value]` deps flipped to false BEFORE
+ * the seed effect ran — so seeding silently no-op'd on every mount and
+ * users always saw a blank canvas. The refactored seed effect delegates
+ * to this pure function; testing it here proves the decision is correct
+ * regardless of the React effect ordering trap.
+ */
+
+const STARTERS: EditorStarterTemplates = {
+  typescript: "// starter for TypeScript",
+  shell: "#!/bin/sh\necho starter for shell",
+};
+
+describe("pickStarterForEmptyField", () => {
+  it("returns the starter for the selected language when the field is empty", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: "",
+        selectedType: "typescript",
+        starterTemplates: STARTERS,
+      }),
+    ).toBe(STARTERS.typescript);
+  });
+
+  it("returns the starter when the value is whitespace-only", () => {
+    // The original bug let trailing whitespace block the seed; explicit
+    // coverage so we don't regress.
+    expect(
+      pickStarterForEmptyField({
+        value: "   \n\t  ",
+        selectedType: "typescript",
+        starterTemplates: STARTERS,
+      }),
+    ).toBe(STARTERS.typescript);
+  });
+
+  it("returns undefined when the field already has content (don't clobber)", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: "// user's existing code",
+        selectedType: "typescript",
+        starterTemplates: STARTERS,
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when value is undefined and no starter is defined for the selected language", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: undefined,
+        selectedType: "json",
+        starterTemplates: STARTERS,
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns undefined when no `starterTemplates` are provided at all", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: "",
+        selectedType: "typescript",
+      }),
+    ).toBeUndefined();
+  });
+
+  it("returns the shell starter when shell is selected", () => {
+    expect(
+      pickStarterForEmptyField({
+        value: undefined,
+        selectedType: "shell",
+        starterTemplates: STARTERS,
+      }),
+    ).toBe(STARTERS.shell);
+  });
+
+  it("treats an empty-string starter as 'no starter available'", () => {
+    // We never want to install a literal empty string on top of an
+    // already-empty field; that would just look like the seed silently
+    // did nothing.
+    expect(
+      pickStarterForEmptyField({
+        value: "",
+        selectedType: "typescript",
+        starterTemplates: { typescript: "" },
+      }),
+    ).toBeUndefined();
+  });
+});

package/src/components/DynamicForm/starterTemplateSelector.ts

@@ -0,0 +1,32 @@
+import type { EditorStarterTemplates, EditorType } from "./types";
+
+/**
+ * Pure decision function powering the "seed empty editor with a starter
+ * template" behaviour in `MultiTypeEditorField`. Returns the starter
+ * content to install, or `undefined` if the field shouldn't be touched.
+ *
+ * Used both on first mount and when the user switches editor language on
+ * a still-empty field, so a single source of truth governs both paths
+ * (and a single test suite covers them).
+ *
+ * Returns `undefined` when:
+ *  - the field already has non-whitespace content (don't clobber user input)
+ *  - no `starterTemplates` were provided
+ *  - no starter exists for the currently-selected language
+ *  - the matching starter is the empty string
+ */
+export function pickStarterForEmptyField({
+  value,
+  selectedType,
+  starterTemplates,
+}: {
+  value: string | undefined;
+  selectedType: EditorType;
+  starterTemplates?: EditorStarterTemplates;
+}): string | undefined {
+  const trimmed = (value ?? "").trim();
+  if (trimmed.length > 0) return undefined;
+  const starter = starterTemplates?.[selectedType];
+  if (!starter || starter.length === 0) return undefined;
+  return starter;
+}

package/src/components/DynamicForm/types.ts

@@ -1,8 +1,11 @@
-import type { TemplateProperty } from "../CodeEditor";
+import type { TemplateProperty, ShellEnvVar } from "../CodeEditor";
 import type { EditorType } from "@checkstack/common";
 
 // Re-export types used by multi-type editor
 export type { EditorType } from "./utils";
+// Re-export `ShellEnvVar` so DynamicForm consumers don't have to import
+// from two paths. The canonical definition lives in `../CodeEditor`.
+export type { ShellEnvVar } from "../CodeEditor";
 import type {
   JsonSchemaPropertyCore,
   JsonSchemaBase,
@@ -40,6 +43,13 @@ export type OptionsResolver = (
  */
 export type JsonSchema = JsonSchemaBase<JsonSchemaProperty>;
 
+/**
+ * Default starter templates per editor language. Used to populate empty
+ * multi-type editor fields so users see a working example instead of a
+ * blank canvas. Keyed by `EditorType` (e.g. "typescript", "shell").
+ */
+export type EditorStarterTemplates = Partial<Record<EditorType, string>>;
+
 export interface DynamicFormProps {
   schema: JsonSchema;
   value: Record<string, unknown>;
@@ -59,6 +69,25 @@ export interface DynamicFormProps {
    * When provided, fields with x-editor-types get {{ autocomplete suggestions.
    */
   templateProperties?: TemplateProperty[];
+  /**
+   * Optional TypeScript declarations to inject into Monaco for `typescript`
+   * or `javascript` editor-type fields. Typically built from a schema via
+   * `generateTypeDefinitions()` so users get autocomplete + type errors
+   * against the runtime context they'll see.
+   */
+  typeDefinitions?: string;
+  /**
+   * Optional list of environment-variable names that are available to
+   * `shell` editor-type fields. When provided, Monaco autocompletes them
+   * after `$` and `${`. Use this to surface platform-injected vars like
+   * `EVENT_ID`, `PAYLOAD_*` etc. so users don't have to remember the names.
+   */
+  shellEnvVars?: ShellEnvVar[];
+  /**
+   * Optional initial content per editor language, used to populate empty
+   * fields with a working example. Keyed by `EditorType`.
+   */
+  starterTemplates?: EditorStarterTemplates;
 }
 
 /** Props for the FormField component */
@@ -71,10 +100,14 @@ export interface FormFieldProps {
   formValues: Record<string, unknown>;
   optionsResolvers?: Record<string, OptionsResolver>;
   templateProperties?: TemplateProperty[];
+  typeDefinitions?: string;
+  shellEnvVars?: ShellEnvVar[];
+  starterTemplates?: EditorStarterTemplates;
   /** Callback when value changes. Omit val to clear the field. */
   onChange: (val?: unknown) => void;
 }
 
+
 /** Props for the DynamicOptionsField component */
 export interface DynamicOptionsFieldProps {
   id: string;

package/src/hooks/useInitOnceForKey.test.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from "bun:test";
+import { shouldInitForKey } from "./useInitOnceForKey";
+
+/**
+ * Regression suite for the form-preservation bug in the healthcheck editor.
+ *
+ * Before this hook existed, the page had:
+ *
+ *   useEffect(() => {
+ *     if (existingConfig) setFormState({ … });
+ *   }, [existingConfig]);
+ *
+ * That fires on every refetch — including the refetches triggered by the
+ * realtime `HEALTH_CHECK_RUN_COMPLETED` signal — so the user's in-progress
+ * edits got wiped every time a healthcheck run completed anywhere on the
+ * platform.
+ *
+ * The hook delegates its decision to the pure `shouldInitForKey` function
+ * tested below. The hook is a thin React wrapper around two refs and a
+ * `useEffect` — testing the decision function gives full coverage of the
+ * logic without needing a DOM.
+ */
+
+describe("shouldInitForKey", () => {
+  it("returns true the first time value+key are defined and no key has been initialised", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(true);
+  });
+
+  it("returns false when value is undefined (query still loading)", () => {
+    expect(
+      shouldInitForKey({
+        value: undefined,
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when value is null", () => {
+    expect(
+      shouldInitForKey({
+        value: null,
+        key: "id-1",
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when key is undefined (no discriminator yet)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: undefined,
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false when key is null (record-not-found path)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: null,
+        initialisedKey: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("returns false on a background refetch (same key already initialised)", () => {
+    // THE regression case: react-query refetched the same record after an
+    // invalidation, handing us a new `value` object reference. The
+    // `initialisedKey` already matches the new key, so we must not re-fire.
+    expect(
+      shouldInitForKey({
+        value: { name: "A (refetched)" },
+        key: "id-1",
+        initialisedKey: "id-1",
+      }),
+    ).toBe(false);
+  });
+
+  it("returns true when the key changes (user navigated to a different record)", () => {
+    expect(
+      shouldInitForKey({
+        value: { name: "B" },
+        key: "id-2",
+        initialisedKey: "id-1",
+      }),
+    ).toBe(true);
+  });
+
+  it("returns true when we're returning to a previously-seen key from a different one", () => {
+    // The hook only stores the LAST initialised key, so flipping between
+    // two records re-initialises each time. That's the correct behaviour:
+    // each visit shows fresh server data.
+    expect(
+      shouldInitForKey({
+        value: { name: "A" },
+        key: "id-1",
+        initialisedKey: "id-2",
+      }),
+    ).toBe(true);
+  });
+
+  it("treats numeric keys correctly (different number → re-init)", () => {
+    expect(
+      shouldInitForKey({ value: "any", key: 1, initialisedKey: 1 }),
+    ).toBe(false);
+    expect(
+      shouldInitForKey({ value: "any", key: 2, initialisedKey: 1 }),
+    ).toBe(true);
+  });
+
+  it("treats string vs number keys as different (no implicit coercion)", () => {
+    // If a caller starts passing IDs as numbers after passing strings (or
+    // vice versa) we'd rather re-init than miss an update; strict !== handles it.
+    expect(
+      shouldInitForKey({ value: "any", key: "1", initialisedKey: 1 }),
+    ).toBe(true);
+  });
+});

package/src/hooks/useInitOnceForKey.ts

@@ -0,0 +1,87 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * Pure decision function powering {@link useInitOnceForKey}. Extracted so
+ * it can be unit-tested without a DOM (the hook itself wraps this with
+ * a `useRef` + `useEffect`).
+ *
+ * Returns `true` iff the caller should run their initialiser:
+ *
+ *  - `value` is defined (the query has finished loading), AND
+ *  - `key` is defined (we have a discriminator to track init-per-record),
+ *    AND
+ *  - we haven't yet initialised for this key (i.e. `initialisedKey !== key`).
+ *
+ * Background refetches of the same record produce a new `value` reference
+ * but the same `key`, so the function returns `false` for them — that's
+ * the whole point.
+ */
+export function shouldInitForKey({
+  value,
+  key,
+  initialisedKey,
+}: {
+  value: unknown;
+  key: string | number | null | undefined;
+  initialisedKey: string | number | null | undefined;
+}): boolean {
+  if (value === undefined || value === null) return false;
+  if (key === undefined || key === null) return false;
+  return initialisedKey !== key;
+}
+
+/**
+ * Run a one-shot initialiser exactly once per `key`, ignoring subsequent
+ * `value` changes that keep the same key.
+ *
+ * Built for forms that need to seed local state from a react-query result
+ * but **must not** reset that state when the query refetches in the
+ * background. The canonical use case is the healthcheck editor: a realtime
+ * `HEALTH_CHECK_RUN_COMPLETED` signal invalidates the configuration query
+ * on every run, which would otherwise wipe the user's in-progress edits
+ * via a naive `useEffect([data], () => setState(data))`.
+ *
+ * Behaviour:
+ *  - Calls `onInit(value)` the first time `value` is defined for a given
+ *    `key`.
+ *  - **Does NOT** call it again if `value` changes but `key` stays the
+ *    same. Background refetches keep the same key (= the same record's
+ *    primary id) and therefore don't re-run the initialiser.
+ *  - **Does** call it again when `key` changes — e.g. when the user
+ *    navigates to a different record without unmounting the page.
+ *  - Skips initialisation entirely while either `value` or `key` is
+ *    `undefined`/`null`.
+ *
+ * `onInit` is read from a ref so callers can safely pass a fresh closure
+ * each render without re-firing the effect.
+ *
+ * @example
+ *   useInitOnceForKey(existingConfig, existingConfig?.id, (config) => {
+ *     setFormState({
+ *       name: config.name,
+ *       collectors: config.collectors ?? [],
+ *     });
+ *   });
+ */
+export function useInitOnceForKey<T>(
+  value: T | undefined | null,
+  key: string | number | null | undefined,
+  onInit: (value: T) => void,
+): void {
+  const initialisedKeyRef = useRef<string | number | null | undefined>(undefined);
+  const onInitRef = useRef(onInit);
+
+  // Keep the latest callback in a ref so a fresh closure each render doesn't
+  // re-trigger the effect; only `value` and `key` should drive it.
+  useEffect(() => {
+    onInitRef.current = onInit;
+  });
+
+  useEffect(() => {
+    if (!shouldInitForKey({ value, key, initialisedKey: initialisedKeyRef.current })) {
+      return;
+    }
+    initialisedKeyRef.current = key;
+    onInitRef.current(value as T);
+  }, [value, key]);
+}

package/src/index.ts

@@ -63,3 +63,4 @@ export * from "./components/MetricTile";
 export * from "./components/Sheet";
 export * from "./components/Popover";
 export * from "./hooks/useIsMobile";
+export * from "./hooks/useInitOnceForKey";

package/tsconfig.json

@@ -1,7 +1,9 @@
 {
   "extends": "@checkstack/tsconfig/frontend.json",
   "include": [
-    "src"
+    "src",
+    "src/components/CodeEditor/generated/stdlib-types.json",
+    "scripts"
   ],
   "references": [
     {